1 .\" Copyright 2014 Garrett D'Amore <garrett@damore.o
   2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" Copyright (c) 1980 Regents of the University of California.
   4 .\" The Berkeley software License Agreement specifies the terms and conditions
   5 .\" for redistribution.
   6 .Dd Jul 18, 2014
   7 .Dt MAN 1
   8 .Os
   9 .Sh NAME
  10 .Nm man
  11 .Nd find and display reference manual pages
  12 .Sh SYNOPSIS
  13 .Nm
  14 .Op Fl
  15 .Op Fl adFlrt
  16 .Op Fl T Ar macro-package
  17 .Op Fl M Ar path
  18 .Op Fl s Ar section
  19 .Ar name ...
  20 .Nm
  21 .Op Fl M Ar path
  22 .Op Fl s Ar section
  23 .Fl k
  24 .Ar keyword
  25 .Ar ...
  26 .Nm
  27 .Op Fl M Ar path
  28 .Op Fl s Ar section
  29 .Fl f
  30 .Ar
  31 .Nm
  32 .Op Fl M Ar path
  33 .Fl w
  34 .Sh DESCRIPTION
  35 The
  36 .Nm
  37 command displays information from the reference manuals. It
  38 displays complete manual pages that you select by
  39 .Ar name ,
  40 or one-line summaries selected either by
  41 .Ar keyword
  42 .Pq Fl k ,
  43 or by the name of an associated file
  44 .Pq Fl f .
  45 If no manual page is located,
  46 .Nm
  47 prints an error message.
  48 .Ss "Source Format"
  49 Reference Manual pages are marked up with either
  50 .Xr man 5 ,
  51 or
  52 .Xr mdoc 5
  53 language tags. The
  54 .Nm
  55 command recognizes the type of markup and
  56 processes the file accordingly.
  57 .
  58 .Ss "Location of Manual Pages"
  59 .
  60 The online Reference Manual page directories are conventionally located in
  61 .Pa /usr/share/man .
  62 Each directory corresponds to a
  63 section of the manual. Since these directories are optionally installed, they
  64 might not reside on your host. You might have to mount
  65 .Pa /usr/share/man
  66 from a host on which they do reside.
  67 The
  68 .Nm
  69 command reformats a page whenever it is requested.
  70 .Pp
  71 If the standard output is not a terminal, or if the
  72 .Fl
  73 flag is given,
  74 .Nm
  75 pipes its output through
  76 .Xr cat 1 .
  77 Otherwise,
  78 .Nm
  79 pipes its output through a pager such as
  80 .Xr more 1
  81 to handle paging and underlining on the screen.
  82 .Sh OPTIONS
  83 The following options are supported:
  84 .Bl -tag -width indent
  85 .It Fl a
  86 Shows all manual pages matching
  87 .Ar name
  88 within the
  89 .Ev MANPATH
  90 search path. Manual pages are displayed in the order found.
  91 .It Fl d
  92 Debugs. Displays what a section-specifier evaluates to, method used for
  93 searching, and paths searched by
  94 .Nm .
  95 .It Fl f Ar file ...
  96 Attempts to locate manual pages related to any of the given
  97 .Ar file
  98 names. It strips the leading path name components from each
  99 .Ar file ,
 100 and then prints one-line summaries containing the resulting basename or names.
 101 This option also uses the
 102 .Pa whatis
 103 database.
 104 .It Fl F
 105 This option is present for backwards compatibility and is documented
 106 here for reference only.  It performs no function.
 107 .It Fl k Ar keyword ...
 108 Prints out one-line summaries from the
 109 .Pa whatis
 110 database (table of contents) that contain any of the given
 111 .Ar keyword .
 112 The
 113 .Pa whatis
 114 database is created using the
 115 .Fl w
 116 option.
 117 .It Fl l
 118 Lists all manual pages found matching
 119 .Ar name
 120 within the search path.
 121 .It Fl M Ar path
 122 Specifies an alternate search path for manual pages. The
 123 .Ar path
 124 is a colon-separated list of directories that contain manual page directory
 125 subtrees. For example, if
 126 .Ar path
 127 is
 128 .Pa /usr/share/man:/usr/local/man ,
 129 .Nm
 130 searches for
 131 .Ar name
 132 in the standard location, and then
 133 .Pa /usr/local/man .
 134 When used with the
 135 .Fl k ,
 136 .Fl f ,
 137 or
 138 .Fl w
 139 options, the
 140 .Fl M
 141 option must appear first. Each directory in the
 142 .Ar path
 143 is assumed to contain subdirectories of the form
 144 .Pa man* ,
 145 one for each section. This option overrides the
 146 .Ev MANPATH
 147 environment variable.
 148 .It Fl r
 149 Reformats the manual page, checking for formatting errors, but does not
 150 display it.
 151 .It Fl s Ar section
 152 Specifies sections of the manual for
 153 .Nm
 154 to search. The directories searched for
 155 .Ar name
 156 are limited to those specified by
 157 .Ar section .
 158 .Ar section
 159 can be a numerical digit, perhaps followed by one or more letters
 160 to match the desired section of the manual, for example,
 161 .Li "3libucb".
 162 Also,
 163 .Ar section
 164 can be a word, for example,
 165 .Li local ,
 166 .Li new ,
 167 .Li old ,
 168 .Li public .
 169 .Ar section
 170 can also be a letter. To specify multiple sections,
 171 separate each section with a comma. This option overrides the
 172 .Ev MANPATH
 173 environment variable and the
 174 .Pa man.cf
 175 file. See
 176 .Sx Search Path
 177 below for an explanation of how
 178 .Nm
 179 conducts its search.
 180 .It Fl t
 181 Arranges for the specified manual pages to be sent to the default
 182 printer as PostScript.
 183 .It Fl T Ar macro-package
 184 This option is present for backwards compatibility and is documented
 185 here for reference only.  It performs no function.
 186 .It Fl w
 187 Updates the
 188 .Nm whatis
 189 database.
 190 .El
 191 .Sh OPERANDS
 192 The following operand is supported:
 193 .Bl -tag -width indent
 194 .It Ar name
 195 The name of a standard utility or a keyword.
 196 .El
 197 .Sh USAGE
 198 The usage of
 199 .Nm
 200 is described below:
 201 .
 202 .Ss "Manual Page Sections"
 203 .
 204 Entries in the reference manuals are organized into
 205 .Em sections .
 206 A section
 207 name consists of a major section name, typically a single digit, optionally
 208 followed by a subsection name, typically one or more letters. An unadorned
 209 major section name, for example,
 210 .Qq 9 ,
 211 does not act as an abbreviation for
 212 the subsections of that name, such as
 213 .Qq 9e ,
 214 .Qq 9f ,
 215 or
 216 .Qq 9s .
 217 That is, each subsection must be searched separately by
 218 .Nm
 219 .Fl s .
 220 Each section contains descriptions apropos to a particular reference category,
 221 with subsections refining these distinctions. See the
 222 .Em intro
 223 manual pages for an explanation of the classification used in this release.
 224 .
 225 .Ss "Search Path"
 226 .
 227 Before searching for a given
 228 .Ar name ,
 229 .Nm
 230 constructs a list of candidate directories and sections.
 231 It searches for
 232 .Ar name
 233 in the directories specified by the
 234 .Ev MANPATH
 235 environment variable.
 236 .Lp
 237 In the absence of
 238 .Ev MANPATH ,
 239 .Nm
 240 constructs its search path based upon the
 241 .Ev PATH
 242 environment variable, primarily by substituting
 243 .Li man
 244 for the last component of the
 245 .Ev PATH
 246 element. Special provisions are added
 247 to account for unique characteristics of directories such as
 248 .Pa /sbin ,
 249 .Pa /usr/ucb ,
 250 .Pa /usr/xpg4/bin ,
 251 and others. If the file argument contains
 252 a
 253 .Qq /
 254 character, the
 255 .Em dirname
 256 portion of the argument is used in place of
 257 .Ev PATH
 258 elements to construct the search path.
 259 .Lp
 260 Within the manual page directories,
 261 .Nm
 262 confines its search to the
 263 sections specified in the following order:
 264 .Bl -bullet
 265 .It
 266 .Ar sections
 267 specified on the command line with the
 268 .Fl s
 269 option
 270 .It
 271 .Ar sections
 272 embedded in the
 273 .Ev MANPATH
 274 environment variable
 275 .It
 276 .Ar sections
 277 specified in the
 278 .Pa man.cf
 279 file for each directory specified in the
 280 .Ev MANPATH
 281 environment variable
 282 .El
 283 If none of the above exist,
 284 .Nm
 285 searches each directory in the manual
 286 page path, and displays the first matching manual page found.
 287 .Lp
 288 The
 289 .Pa man.cf
 290 file has the following format:
 291 .Lp
 292 .Dl Pf MANSECTS= Ar section , Ns Op Ar section...
 293 .Lp
 294 Lines beginning with
 295 .Sq Li #
 296 and blank lines are considered comments, and are
 297 ignored. Each directory specified in
 298 .Ev MANPATH
 299 can contain a manual page
 300 configuration file, specifying the default search order for that directory.
 301 .Sh "Referring to Other Manual Pages"
 302 If the first line of the manual page is a reference to another manual
 303 page entry fitting the pattern:
 304 .Lp
 305 .Dl \&.so man*/\fIsourcefile\fR
 306 .Lp
 307 .Nm
 308 processes the indicated file in place of the current one. The
 309 reference must be expressed as a path name relative to the root of the manual
 310 page directory subtree.
 311 .Lp
 312 When the second or any subsequent line starts with \fB\&.so\fR, \fBman\fR
 313 ignores it; \fBtroff\fR(1) or \fBnroff\fR(1) processes the request in the usual
 314 manner.
 315 .Sh ENVIRONMENT VARIABLES
 316 See
 317 .Xr environ 5
 318 for descriptions of the following environment variables
 319 that affect the execution of
 320 .Nm man :
 321 .Ev LANG ,
 322 .Ev LC_ALL ,
 323 .Ev LC_CTYPE ,
 324 .Ev LC_MESSAGES ,
 325 and
 326 .Ev NLSPATH .
 327 .Bl -tag -width indent
 328 .It Ev MANPATH
 329 A colon-separated list of directories; each directory can be followed by a
 330 comma-separated list of sections. If set, its value overrides
 331 \fB/usr/share/man\fR as the default directory search path, and the \fBman.cf\fR
 332 file as the default section search path. The \fB-M\fR and \fB-s\fR flags, in
 333 turn, override these values.)
 334 .It Ev PAGER
 335 A program to use for interactively delivering
 336 output to the screen. If not set,
 337 .Sq Nm more Fl s
 338 is used. See
 339 .Xr more 1 .
 340 .El
 341 .Sh FILES
 342 .Bl -tag -width indent
 343 .It Pa /usr/share/man
 344 Root of the standard manual page directory subtree
 345 .It Pa /usr/share/man/man?/*
 346 Unformatted manual entries
 347 .It Pa /usr/share/man/whatis
 348 Table of contents and keyword database
 349 .It Pa man.cf
 350 Default search order by section
 351 .El
 352 .Sh EXIT STATUS
 353 .Ex -std man
 354 .Sh EXAMPLES
 355 .
 356 .Ss Example 1: Creating a PostScript Version of a man page
 357 .
 358 The following example spools the
 359 .Xr pipe 2
 360 man page in PostScript to the default printer:
 361 .Pp
 362 .Dl % man -t -s 2 pipe
 363 .Pp
 364 Note that
 365 .Xr mandoc 1
 366 can be used to obtain the PostScript content directly.
 367 .Ss Example 2: Creating a Text Version of a man page
 368 The following example creates the
 369 .Xr pipe 2
 370 man page in ASCII text:
 371 .Pp
 372 .Dl % man pipe.2 | col -x -b > pipe.text
 373 .Sh CODE SET INDEPENDENCE
 374 Enabled.
 375 .Sh INTERFACE STABILITY
 376 .Nm Committed .
 377 .Sh SEE ALSO
 378 .Xr apropos 1 ,
 379 .Xr cat 1 ,
 380 .Xr col 1 ,
 381 .Xr mandoc 1 ,
 382 .Xr more 1 ,
 383 .Xr whatis 1 ,
 384 .Xr environ 5 ,
 385 .Xr man 5 ,
 386 .Xr mdoc 5
 387 .Sh NOTES
 388 The
 389 .Fl f
 390 and
 391 .Fl k
 392 options use the
 393 .Nm whatis
 394 database, which is
 395 created with the
 396 .Fl w
 397 option.
 398 .Sh BUGS
 399 The manual is supposed to be reproducible either on a phototypesetter or on an
 400 ASCII terminal. However, on a terminal some information (indicated by
 401 font changes, for instance) is lost.