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