gnu/usr.bin/man/man/man.man

   1 .\" Man page for man
   2 .\"
   3 .\" Copyright (c) 1990, 1991, John W. Eaton.
   4 .\"
   5 .\" You may distribute under the terms of the GNU General Public
   6 .\" License as specified in the README file that comes with the man 1.0
   7 .\" distribution.
   8 .\"
   9 .\" John W. Eaton
  10 .\" jwe@che.utexas.edu
  11 .\" Department of Chemical Engineering
  12 .\" The University of Texas at Austin
  13 .\" Austin, Texas  78712
  14 .\"
  15 .\" $FreeBSD$
  16 .\"
  17 .Dd December 3, 2005
  18 .Dt MAN 1
  19 .Os
  20 .Sh NAME
  21 .Nm man
  22 .Nd format and display the on-line manual pages
  23 .Sh SYNOPSIS
  24 .Nm
  25 .Op Fl adfhkotw
  26 .Op Fl m Ar arch Ns Op : Ns Ar machine
  27 .Op Fl p Ar string
  28 .Op Fl M Ar path
  29 .Op Fl P Ar pager
  30 .Op Fl S Ar list
  31 .Op Ar section
  32 .Ar name ...
  33 .Sh DESCRIPTION
  34 The
  35 .Nm
  36 utility
  37 formats and displays the on-line manual pages.
  38 This version knows
  39 about the
  40 .Ev MANPATH
  41 and
  42 .Ev PAGER
  43 environment variables, so you can have
  44 your own set(s) of personal man pages and choose whatever program you
  45 like to display the formatted pages.
  46 If
  47 .Ar section
  48 is specified,
  49 .Nm
  50 only looks in that section of the manual.
  51 You may also specify the
  52 order to search the sections for entries and which preprocessors to
  53 run on the source files via command line options or environment
  54 variables.
  55 If enabled by the system administrator, formatted man
  56 pages will also be compressed with the
  57 .Dq Li "%compress%"
  58 command to save space.
  59 .Pp
  60 The options are as follows:
  61 .Bl -tag -width ".Fl P Ar pager"
  62 .It Fl M Ar path
  63 Specify an alternate manpath.
  64 By default,
  65 .Nm
  66 uses
  67 .Xr manpath 1
  68 (which is built into the
  69 .Nm
  70 binary)
  71 to determine the path to search.
  72 This option overrides the
  73 .Ev MANPATH
  74 environment variable.
  75 .It Fl P Ar pager
  76 Specify which pager to use.
  77 By default,
  78 .Nm
  79 uses
  80 .Dq Li "%pager%" .
  81 This option overrides the
  82 .Ev PAGER
  83 environment variable.
  84 .It Fl S Ar list
  85 List is a colon separated list of manual sections to search.
  86 This option overrides the
  87 .Ev MANSECT
  88 environment variable.
  89 .It Fl a
  90 By default,
  91 .Nm
  92 will exit after displaying the first manual page it
  93 finds.
  94 Using this option forces
  95 .Nm
  96 to display all the manual pages
  97 that match
  98 .Ar name ,
  99 not just the first.
 100 .It Fl d
 101 Do not actually display the man pages, but do print gobs of debugging
 102 information.
 103 .It Fl f
 104 Equivalent to
 105 .Nm whatis .
 106 .It Fl h
 107 Print a help message and exit.
 108 .It Fl k
 109 Equivalent to
 110 .Nm apropos .
 111 .It Fl m Ar arch Ns Op : Ns Ar machine
 112 As some manual pages are intended only for specific
 113 architectures and machine types,
 114 .Nm
 115 searches any subdirectories,
 116 with the same name as the current machine type and architecture,
 117 in every directory which it searches.
 118 Machine specific areas are checked before architecture specific areas,
 119 and architecture specific areas are checked before general areas.
 120 For example, for
 121 .Dq Li i386:pc98 ,
 122 the following subdirectories will be searched for section 8
 123 manpages, in order:
 124 .Pa man8/pc98, man8/i386 ,
 125 and
 126 .Pa man8 .
 127 .Pp
 128 The current machine type may be overridden using this option
 129 or by setting the environment variable
 130 .Ev MACHINE
 131 to the name of a specific machine.
 132 The current architecture may be overridden using this option
 133 or by setting the environment variable
 134 .Ev MACHINE_ARCH
 135 to the name of a specific architecture.
 136 This option overrides the
 137 .Ev MACHINE
 138 and
 139 .Ev MACHINE_ARCH
 140 environment variables.
 141 A
 142 .Ar machine
 143 component, if omitted, defaults to
 144 .Ar arch .
 145 .It Fl o
 146 Look for original, non-localized manpages only.
 147 .Pp
 148 By default,
 149 .Nm
 150 searches for a localized manpage
 151 in a set of locale subdirectories of each
 152 .Xr manpath 1
 153 component.
 154 .Pp
 155 Locale name is taken from the first of three environment variables
 156 with a nonempty value:
 157 .Ev LC_ALL , LC_CTYPE ,
 158 or
 159 .Ev LANG ,
 160 in the specified order.
 161 .Pp
 162 If the value could not be determined, or is not a valid locale name,
 163 then only non-localized manpage will be looked up.
 164 .Pp
 165 Otherwise,
 166 .Nm
 167 will search in the following subdirectories, in the order of precedence:
 168 .Pp
 169 .Bl -item -offset indent -compact
 170 .Sm off
 171 .It
 172 .Pa <lang> _ <country> . <charset>
 173 .It
 174 .Pa <lang> . <charset>
 175 .It
 176 .Pa en . <charset>
 177 .Sm on
 178 .El
 179 .Pp
 180 For example, for the
 181 .Dq Li de_DE.ISO8859-1
 182 locale,
 183 .Nm
 184 will search in the following subdirectories of the
 185 .Pa /usr/share/man
 186 manpath component:
 187 .Pp
 188 .Bl -item -offset indent -compact
 189 .It
 190 .Pa /usr/share/man/de_DE.ISO8859-1
 191 .It
 192 .Pa /usr/share/man/de.ISO8859-1
 193 .It
 194 .Pa /usr/share/man/en.ISO8859-1
 195 .El
 196 .Pp
 197 Finally,
 198 if the search of localized manpage fails,
 199 it will be looked up in the default
 200 .Pa /usr/share/man
 201 directory.
 202 .It Fl p Ar string
 203 Specify the sequence of preprocessors to run before
 204 .Xr nroff 1
 205 or
 206 .Xr troff 1 .
 207 Not all installations will have a full set of preprocessors.
 208 Some of the preprocessors and the letters used to designate them are:
 209 .Nm eqn Pq e ,
 210 .Nm grap Pq g ,
 211 .Nm pic Pq p ,
 212 .Nm tbl Pq t ,
 213 .Nm vgrind Pq v ,
 214 .Nm refer Pq r .
 215 This option overrides the
 216 .Ev MANROFFSEQ
 217 environment variable.
 218 .It Fl t
 219 Use
 220 .Dq Li "%troff%"
 221 to format the manual page, passing the output to stdout.
 222 The default output format of
 223 .Xr groff 1
 224 is Postscript, but see the manual page of
 225 .Xr groff 1
 226 for ways to pick an alternate format.
 227 .Pp
 228 Depending on the selected format and the availability of printing
 229 devices, the output
 230 may need to be passed through some filter or another before being
 231 printed.
 232 .It Fl w
 233 Do not actually display the man pages, but do print the location(s) of
 234 the files that would be formatted or displayed.
 235 .El
 236 .Sh ENVIRONMENT
 237 .Bl -tag -width ".Ev MACHINE_ARCH"
 238 .It Ev LC_ALL , LC_CTYPE , LANG
 239 These variables specify the preferred language for manual pages.
 240 (See the
 241 .Fl o
 242 option above.)
 243 .It Ev MACHINE
 244 If
 245 .Ev MACHINE
 246 is set, its value is used to override the current machine type
 247 when searching machine specific subdirectories.
 248 .It Ev MACHINE_ARCH
 249 If
 250 .Ev MACHINE_ARCH
 251 is set, its value is used to override the current architecture
 252 when searching architecture specific subdirectories.
 253 .It Ev MANPATH
 254 If
 255 .Ev MANPATH
 256 is set, its value is used as the path to search for manual pages.
 257 .It Ev MANROFFSEQ
 258 If
 259 .Ev MANROFFSEQ
 260 is set, its value is used to determine the set of preprocessors run
 261 before running
 262 .Xr nroff 1
 263 or
 264 .Xr troff 1 .
 265 By default, pages are passed through
 266 the table preprocessor
 267 .Pq Xr tbl 1
 268 before
 269 .Xr nroff 1 .
 270 .It Ev MANSECT
 271 If
 272 .Ev MANSECT
 273 is set, its value is used to determine which manual sections to search.
 274 .It Ev PAGER
 275 If
 276 .Ev PAGER
 277 is set, its value is used as the name of the program to use to display
 278 the man page.
 279 By default,
 280 .Dq Li "%pager%"
 281 is used.
 282 .El
 283 .Sh EXAMPLES
 284 .Pp
 285 Normally, to look at the relevant manpage information for
 286 .Dq Li getopt ,
 287 one would use:
 288 .Pp
 289 .Dl "man getopt"
 290 .Pp
 291 However, when referring to a specific section of the manual,
 292 such as
 293 .Xr getopt 3 ,
 294 one would use:
 295 .Pp
 296 .Dl "man 3 getopt"
 297 .Sh SEE ALSO
 298 .Xr apropos 1 ,
 299 .Xr groff 1 ,
 300 .Xr manpath 1 ,
 301 .Xr more 1 ,
 302 .Xr whatis 1 ,
 303 .Xr man 7 ,
 304 .Xr mdoc 7
 305 .Sh BUGS
 306 The
 307 .Fl t
 308 option only works if the
 309 .Xr troff 1 Ns -like
 310 program is installed.