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

   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: src/gnu/usr.bin/man/man/man.man,v 1.10.2.8 2002/06/25 00:02:55 eric Exp $
  16 .\"
  17 .Dd August 21, 2008
  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 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 .Nm Man
  35 formats and displays the on-line manual pages.
  36 This version knows about the
  37 .Ev MANPATH
  38 and
  39 .Ev PAGER
  40 environment variables, so you can have
  41 your own set(s) of personal man pages and choose whatever program you
  42 like to display the formatted pages.
  43 If
  44 .Ar section
  45 is specified,
  46 .Nm
  47 only looks in that section of the manual.
  48 You may also specify the order to search the sections for entries and
  49 which preprocessors to run on the source files via command line options
  50 or environment variables.
  51 If enabled by the system administrator, formatted man pages will also
  52 be compressed with the
  53 .Nm /usr/bin/gzip -c
  54 command to save space.
  55 If
  56 .Ar name
  57 contains a
  58 .Sq / ,
  59 .Nm
  60 treats it as a file name.
  61 .Pp
  62 The options are as follows:
  63 .Bl -tag -width Fl
  64 .It Fl M Ar path
  65 Specify an alternate manpath.
  66 By default,
  67 .Nm
  68 uses
  69 .Xr manpath 1
  70 (which is built into the
  71 .Nm
  72 binary)
  73 to determine the path to search.
  74 This option overrides the
  75 .Ev MANPATH
  76 environment variable.
  77 .It Fl P Ar pager
  78 Specify which pager to use.
  79 By default,
  80 .Nm
  81 uses
  82 .Nm more -s .
  83 This option overrides the
  84 .Ev PAGER
  85 environment variable.
  86 .It Fl S Ar list
  87 List is a colon separated list of manual sections to search.
  88 The default is
  89 .Dq 1:8:2:3:4:5:6:7:9 .
  90 This option overrides the
  91 .Ev MANSECT
  92 environment variable.
  93 .It Fl a
  94 By default,
  95 .Nm
  96 will exit after displaying the first manual page it
  97 finds.
  98 Using this option forces
  99 .Nm
 100 to display all the manual pages
 101 that match
 102 .Ar name ,
 103 not just the first.
 104 .It Fl d
 105 Don't actually display the man pages, but do print gobs of debugging
 106 information.
 107 .It Fl f
 108 Equivalent to
 109 .Nm whatis .
 110 .It Fl h
 111 Print a help message and exit.
 112 .It Fl k
 113 Equivalent to
 114 .Nm apropos .
 115 .It Fl m Ar machine
 116 As some manual pages are intended only for specific architectures,
 117 .Nm
 118 searches any subdirectories,
 119 with the same name as the current architecture,
 120 in every directory which it searches.
 121 Machine specific areas are checked before general areas.
 122 The current machine type may be overridden using this option
 123 or by setting the environment variable
 124 .Ev MACHINE
 125 to the name of a specific architecture.
 126 This option overrides the
 127 .Ev MACHINE
 128 environment variable.
 129 .It Fl o
 130 Look for original, non-localized manpages only.
 131 .Pp
 132 By default,
 133 .Nm
 134 searches for a localized manpage
 135 in a set of locale subdirectories of each
 136 .Xr manpath 1
 137 component.
 138 .Pp
 139 Locale name is taken from the first of three environment variables
 140 with a nonempty value:
 141 .Ev LC_ALL , LC_CTYPE ,
 142 or
 143 .Ev LANG ,
 144 in the specified order.
 145 .Pp
 146 If the value could not be determined, or is not a valid locale name,
 147 then only non-localized manpage will be looked up.
 148 .Pp
 149 Otherwise,
 150 .Nm
 151 will search in the following subdirectories, in the order of precedence:
 152 .Pp
 153 .Bl -item -offset indent -compact
 154 .Sm off
 155 .It
 156 .Pa <lang> _ <country> . <charset>
 157 .It
 158 .Pa <lang> . <charset>
 159 .It
 160 .Pa en . <charset>
 161 .Sm on
 162 .El
 163 .Pp
 164 For example, for
 165 .Dq de_DE.ISO8859-1
 166 locale,
 167 .Nm
 168 will search in the following subdirectories of the
 169 .Pa /usr/share/man
 170 manpath component:
 171 .Pp
 172 .Bl -item -offset indent -compact
 173 .It
 174 .Pa /usr/share/man/de_DE.ISO8859-1
 175 .It
 176 .Pa /usr/share/man/de.ISO8859-1
 177 .It
 178 .Pa /usr/share/man/en.ISO8859-1
 179 .El
 180 .Pp
 181 Finally,
 182 if the search of localized manpage fails,
 183 it will be looked up in the default
 184 .Pa /usr/share/man
 185 directory.
 186 .It Fl p Ar string
 187 Specify the sequence of preprocessors to run before nroff or troff.
 188 Not all installations will have a full set of preprocessors.
 189 Some of the preprocessors and the letters used to designate them are:
 190 eqn (e), grap (g), pic (p), tbl (t), vgrind (v), refer (r).
 191 This option overrides the
 192 .Ev MANROFFSEQ
 193 environment variable.
 194 .It Fl t
 195 Use
 196 .Nm /usr/bin/groff -S -man
 197 to format the manual page, passing the output to stdout.
 198 The output from
 199 .Nm /usr/bin/groff -S -man
 200 may need to be passed through some filter or another before being
 201 printed.
 202 .It Fl w
 203 Don't actually display the man pages, but do print the location(s) of
 204 the files that would be formatted or displayed.
 205 .El
 206 .Sh ENVIRONMENT
 207 .Bl -tag -width MANROFFSEQ
 208 .It Ev LC_ALL , LC_CTYPE , LANG
 209 These variables specify the preferred language for manual pages.
 210 (See the
 211 .Fl o
 212 option above.)
 213 .It Ev MACHINE
 214 If
 215 .Ev MACHINE
 216 is set, its value is used to override the current machine type
 217 when searching machine specific subdirectories.
 218 .It Ev MANPATH
 219 If
 220 .Ev MANPATH
 221 is set, its value is used as the path to search for manual pages.
 222 .It Ev MANROFFSEQ
 223 If
 224 .Ev MANROFFSEQ
 225 is set, its value is used to determine the set of preprocessors run
 226 before running
 227 .Xr nroff 1
 228 or
 229 .Xr troff 1 .
 230 By default, pages are passed through the table preprocessor before
 231 .Xr nroff 1 .
 232 .It Ev MANSECT
 233 If
 234 .Ev MANSECT
 235 is set, its value is used to determine which manual sections to search.
 236 .It Ev PAGER
 237 If
 238 .Ev PAGER
 239 is set, its value is used as the name of the program to use to display
 240 the man page.
 241 By default,
 242 .Nm more -s
 243 is used.
 244 .El
 245 .Sh EXAMPLES
 246 .Pp
 247 Normally, to look at the relevant manpage information for getopt,
 248 one would use:
 249 .Pp
 250 .Dl man getopt
 251 .Pp
 252 However, when referring to a specific section of the manual,
 253 such as
 254 .Xr getopt 3 ,
 255 one would use:
 256 .Pp
 257 .Dl man 3 getopt
 258 .Sh SEE ALSO
 259 .Xr apropos 1 ,
 260 .Xr groff 1 ,
 261 .Xr manpath 1 ,
 262 .Xr more 1 ,
 263 .Xr whatis 1 ,
 264 .Xr man 7 ,
 265 .Xr mdoc 7
 266 .Sh BUGS
 267 The
 268 .Fl t
 269 option only works if the
 270 .Xr troff 1 Ns -like
 271 program is installed.