Print this page
Latest round of fixes per RM and AL.  Fix bugs found in man.c.
manpage lint.
feedback from Hans
mandoc import
   1 '\" te
   2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" Copyright (c) 1980 Regents of the University of California. The Berkeley software License Agreement specifies the terms and conditions for redistribution.
   4 .TH MAN 1 "May 8, 2008"
   5 .SH NAME
   6 man \- find and display reference manual pages
   7 .SH SYNOPSIS
   8 .LP
   9 .nf
  10 \fBman\fR [\fB-\fR] [\fB-adFlrt\fR] [\fB-M\fR \fIpath\fR] [\fB-T\fR \fImacro-package\fR] [\fB-s\fR \fIsection\fR] \fIname\fR...
  11 .fi
  12 
  13 .LP
  14 .nf
  15 \fBman\fR [\fB-M\fR \fIpath\fR] \fB-k\fR \fIkeyword\fR...
  16 .fi
  17 
  18 .LP
  19 .nf
  20 \fBman\fR [\fB-M\fR \fIpath\fR] \fB-f\fR \fIfile\fR...
  21 .fi
  22 
  23 .SH DESCRIPTION
  24 .sp
  25 .LP
  26 The \fBman\fR command displays information from the reference manuals. It
  27 displays complete manual pages that you select by \fIname\fR, or one-line
  28 summaries selected either by \fIkeyword\fR (\fB-k\fR), or by the name of an
  29 associated file (\fB-f\fR). If no manual page is located, \fBman\fR prints an
  30 error message.
  31 .SS "Source Format"
  32 .sp
  33 .LP
  34 Reference Manual pages are marked up with either \fBnroff\fR (see
  35 \fBnroff\fR(1)) or \fBSGML\fR (Standard Generalized Markup Language) tags (see
  36 \fBsgml\fR(5)). The \fBman\fR command recognizes the type of markup and
  37 processes the file accordingly. The various source files are kept in separate
  38 directories depending on the type of markup.
  39 .SS "Location of Manual Pages"
  40 .sp
  41 .LP


















  42 The online Reference Manual page directories are conventionally located in
  43 \fB/usr/share/man\fR. The nroff sources are located in the
  44 \fB/usr/share/man/man\fR* directories. The \fBSGML\fR sources are located in
  45 the \fB/usr/share/man/sman\fR* directories. Each directory corresponds to a
  46 section of the manual. Since these directories are optionally installed, they
  47 might not reside on your host. You might have to mount \fB/usr/share/man\fR

  48 from a host on which they do reside.
  49 .sp
  50 .LP
  51 If there are preformatted, up-to-date versions in the corresponding \fBcat\fR*
  52 or \fBfmt\fR* directories, \fBman\fR simply displays or prints those versions.
  53 If the preformatted version of interest is out of date or missing, \fBman\fR
  54 reformats it prior to display and stores the preformatted version if \fBcat\fR*
  55 or \fBfmt\fR* is writable. The \fBwindex\fR database is not updated. See
  56 \fBcatman\fR(1M). If directories for the preformatted versions are not
  57 provided, \fBman\fR reformats a page whenever it is requested. \fBman\fR uses a
  58 temporary file to store the formatted text during display.
  59 .sp
  60 .LP
  61 If the standard output is not a terminal, or if the `\fB-\fR' flag is given,
  62 \fBman\fR pipes its output through \fBcat\fR(1). Otherwise, \fBman\fR pipes its
  63 output through \fBmore\fR(1) to handle paging and underlining on the screen.
  64 .SH OPTIONS
  65 .sp
  66 .LP
  67 The following options are supported:
  68 .sp
  69 .ne 2
  70 .na
  71 \fB\fB-a\fR\fR
  72 .ad
  73 .RS 20n
  74 Shows all manual pages matching \fIname\fR within the \fBMANPATH\fR search
  75 path. Manual pages are displayed in the order found.
  76 .RE
  77 
  78 .sp
  79 .ne 2
  80 .na
  81 \fB\fB-d\fR\fR
  82 .ad
  83 .RS 20n
  84 Debugs. Displays what a section-specifier evaluates to, method used for
  85 searching, and paths searched by \fBman\fR.
  86 .RE
  87 
  88 .sp
  89 .ne 2
  90 .na
  91 \fB\fB-f\fR \fIfile ...\fR\fR
  92 .ad
  93 .RS 20n
  94 \fBman\fR attempts to locate manual pages related to any of the given
  95 \fIfile\fRs. It strips the leading path name components from each \fIfile\fR,
  96 and then prints one-line summaries containing the resulting basename or names.
  97 This option also uses the \fBwindex\fR database.
  98 .RE
  99 
 100 .sp
 101 .ne 2
 102 .na
 103 \fB\fB-F\fR\fR
 104 .ad
 105 .RS 20n
 106 Forces \fBman\fR to search all directories specified by \fBMANPATH\fR or the
 107 \fBman.cf\fR file, rather than using the \fBwindex\fR lookup database. This
 108 option is useful if the database is not up to date and it has been made the
 109 default behavior of the \fBman\fR command. The option therefore does not have
 110 to be invoked and is documented here for reference only.
 111 .RE
 112 
 113 .sp
 114 .ne 2
 115 .na
 116 \fB\fB-k\fR \fIkeyword ...\fR\fR
 117 .ad
 118 .RS 20n
 119 Prints out one-line summaries from the \fBwindex\fR database (table of
 120 contents) that contain any of the given \fIkeyword\fRs. The \fBwindex\fR
 121 database is created using \fBcatman\fR(1M).
 122 .RE
 123 
 124 .sp
 125 .ne 2
 126 .na
 127 \fB\fB-l\fR\fR
 128 .ad
 129 .RS 20n
 130 Lists all manual pages found matching \fIname\fR within the search path.
 131 .RE
 132 
 133 .sp
 134 .ne 2
 135 .na
 136 \fB\fB-M\fR \fIpath\fR\fR
 137 .ad
 138 .RS 20n
 139 Specifies an alternate search path for manual pages. \fIpath\fR is a
 140 colon-separated list of directories that contain manual page directory
 141 subtrees. For example, if \fIpath\fR is \fB/usr/share/man:/usr/local/man\fR,
 142 \fBman\fR searches for \fIname\fR in the standard location, and then
 143 \fB/usr/local/man\fR. When used with the \fB-k\fR or \fB-f\fR options, the
 144 \fB-M\fR option must appear first. Each directory in the \fIpath\fR is assumed
 145 to contain subdirectories of the form \fBman\fR* or \fBsman\fR* , one for each
 146 section. This option overrides the \fBMANPATH\fR environment variable.
 147 .RE
 148 
 149 .sp
 150 .ne 2
 151 .na
 152 \fB\fB-r\fR\fR
 153 .ad
 154 .RS 20n
 155 Reformats the manual page, but does not display it. This replaces the \fBman\fR
 156 \fB-\fR \fB-t\fR \fIname\fR combination.
 157 .RE
 158 
 159 .sp
 160 .ne 2
 161 .na
 162 \fB\fB-s\fR \fIsection ...\fR\fR
 163 .ad
 164 .RS 20n
 165 Specifies sections of the manual for \fBman\fR to search. The directories
 166 searched for \fIname\fR are limited to those specified by \fIsection\fR.
 167 \fIsection\fR can be a numerical digit, perhaps followed by one or more letters
 168 to match the desired section of the manual, for example, "\fB3libucb\fR". Also,
 169 \fIsection\fR can be a word, for example, \fBlocal\fR, \fBnew\fR, \fBold\fR,
 170 \fBpublic\fR. \fIsection\fR can also be a letter. To specify multiple sections,
 171 separate each section with a comma. This option overrides the \fBMANPATH\fR
 172 environment variable and the \fBman.cf\fR file. See \fBSearch\fR \fBPath\fR
 173 below for an explanation of how \fBman\fR conducts its search.
 174 .RE
 175 
 176 .sp
 177 .ne 2
 178 .na
 179 \fB\fB-t\fR\fR
 180 .ad
 181 .RS 20n
 182 \fBman\fR arranges for the specified manual pages to be \fBtroff\fRed to a
 183 suitable raster output device (see \fBtroff\fR(1)). If both the \fB-\fR and
 184 \fB-t\fR flags are given, \fBman\fR updates the \fBtroff\fRed versions of each
 185 named \fIname\fR (if necessary), but does not display them.
 186 .RE
 187 
 188 .sp
 189 .ne 2
 190 .na
 191 \fB\fB-T\fR \fImacro-package\fR\fR
 192 .ad
 193 .RS 20n
 194 Formats manual pages using \fImacro-package\fR rather than the standard
 195 \fB-man\fR macros defined in \fB/usr/share/lib/tmac/an\fR. See \fBSearch
 196 Path\fR under USAGE for a complete explanation of the default search path
 197 order.
 198 .RE
 199 
 200 .SH OPERANDS
 201 .sp
 202 .LP
 203 The following operand is supported:
 204 .sp
 205 .ne 2
 206 .na
 207 \fB\fIname\fR\fR
 208 .ad
 209 .RS 8n
 210 The name of a standard utility or a keyword.
 211 .RE
 212 
 213 .SH USAGE
 214 .sp
 215 .LP
 216 The usage of \fBman\fR is described below:
 217 .SS "Manual Page Sections"
 218 .sp
 219 .LP
 220 Entries in the reference manuals are organized into \fIsection\fRs. A section

 221 name consists of a major section name, typically a single digit, optionally
 222 followed by a subsection name, typically one or more letters. An unadorned
 223 major section name, for example, "\fB9\fR", does not act as an abbreviation for
 224 the subsections of that name, such as "\fB9e\fR", "\fB9f\fR", or "\fB9s\fR".
 225 That is, each subsection must be searched separately by \fBman\fR \fB-s\fR.








 226 Each section contains descriptions apropos to a particular reference category,
 227 with subsections refining these distinctions. See the \fBintro\fR manual pages
 228 for an explanation of the classification used in this release.
 229 .SS "Search Path"
 230 .sp
 231 .LP
 232 Before searching for a given \fIname\fR, \fBman\fR constructs a list of
 233 candidate directories and sections. \fBman\fR searches for \fIname\fR in the
 234 directories specified by the \fBMANPATH\fR environment variable.
 235 .sp
 236 .LP
 237 In the absence of \fBMANPATH\fR, \fBman\fR constructs its search path based
 238 upon the \fBPATH\fR environment variable, primarily by substituting \fBman\fR
 239 for the last component of the \fBPATH\fR element. Special provisions are added
 240 to account for unique characteristics of directories such as \fB/sbin\fR,
 241 \fB/usr/ucb\fR, \fB/usr/xpg4/bin\fR, and others. If the file argument contains
 242 a \fB/\fR character, the \fIdirname\fR portion of the argument is used in place
 243 of \fBPATH\fR elements to construct the search path.
 244 .sp
 245 .LP
 246 Within the manual page directories, \fBman\fR confines its search to the






















 247 sections specified in the following order:
 248 .RS +4
 249 .TP
 250 .ie t \(bu
 251 .el o
 252 \fIsection\fRs specified on the command line with the \fB-s\fR option
 253 .RE
 254 .RS +4
 255 .TP
 256 .ie t \(bu
 257 .el o
 258 \fIsection\fRs embedded in the \fBMANPATH\fR environment variable
 259 .RE
 260 .RS +4
 261 .TP
 262 .ie t \(bu
 263 .el o
 264 \fIsection\fRs specified in the \fBman.cf\fR file for each directory specified
 265 in the \fBMANPATH\fR environment variable
 266 .RE
 267 .sp
 268 .LP
 269 If none of the above exist, \fBman\fR searches each directory in the manual
 270 page path, and displays the first matching manual page found.
 271 .sp
 272 .LP
 273 The \fBman.cf\fR file has the following format:
 274 .sp
 275 .in +2
 276 .nf
 277 MANSECTS=\fIsection\fR[,\fIsection\fR]...
 278 .fi
 279 .in -2
 280 .sp
 281 
 282 .sp
 283 .LP
 284 Lines beginning with `\fB#\fR' and blank lines are considered comments, and are
 285 ignored. Each directory specified in \fBMANPATH\fR can contain a manual page
 286 configuration file, specifying the default search order for that directory.
 287 .SH FORMATTING MANUAL PAGES
 288 .sp
 289 .LP
 290 Manual pages are marked up in \fBnroff\fR(1) or \fBsgml\fR(5). Nroff manual
 291 pages are processed by \fBnroff\fR(1) or \fBtroff\fR(1) with the \fB-man\fR
 292 macro package. Please refer to \fBman\fR(5) for information on macro usage.
 293 \fBSGML\fR\(emtagged manual pages are processed by an \fBSGML\fR parser and
 294 passed to the formatter.
 295 .SS "Preprocessing Nroff Manual Pages"
 296 .sp
 297 .LP
 298 When formatting an nroff manual page, \fBman\fR examines the first line to
 299 determine whether it requires special processing. If the first line is a string
 300 of the form:
 301 .sp
 302 .in +2
 303 .nf
 304 \&'\e" \fIX\fR
 305 .fi
 306 .in -2
 307 .sp
 308 
 309 .sp
 310 .LP
 311 where \fIX\fR is separated from the `\fB"\fR' by a single SPACE and consists of
 312 any combination of characters in the following list, \fBman\fR pipes its input
 313 to \fBtroff\fR(1) or \fBnroff\fR(1) through the corresponding preprocessors.
 314 .sp
 315 .ne 2
 316 .na
 317 \fB\fBe\fR\fR
 318 .ad
 319 .RS 5n
 320 \fBeqn\fR(1), or \fBneqn\fR for \fBnroff\fR
 321 .RE
 322 
 323 .sp
 324 .ne 2
 325 .na
 326 \fB\fBr\fR\fR
 327 .ad
 328 .RS 5n
 329 \fBrefer\fR(1)
 330 .RE
 331 
 332 .sp
 333 .ne 2
 334 .na
 335 \fB\fBt\fR\fR
 336 .ad
 337 .RS 5n
 338 \fBtbl\fR(1)
 339 .RE
 340 
 341 .sp
 342 .ne 2
 343 .na
 344 \fB\fBv\fR\fR
 345 .ad
 346 .RS 5n
 347 \fBvgrind\fR(1)
 348 .RE
 349 
 350 .sp
 351 .LP
 352 If \fBeqn\fR or \fBneqn\fR is invoked, it automatically reads the file
 353 \fB/usr/pub/eqnchar\fR (see \fBeqnchar\fR(5)). If \fBnroff\fR(1) is invoked,
 354 \fBcol\fR(1) is automatically used.
 355 .SS "Referring to Other nroff Manual Pages"
 356 .sp
 357 .LP
 358 If the first line of the nroff manual page is a reference to another manual
 359 page entry fitting the pattern:
 360 .sp
 361 .in +2
 362 .nf
 363 \&.so man*/\fIsourcefile\fR
 364 .fi
 365 .in -2
 366 .sp
 367 
 368 .sp
 369 .LP
 370 \fBman\fR processes the indicated file in place of the current one. The
 371 reference must be expressed as a path name relative to the root of the manual
 372 page directory subtree.
 373 .sp
 374 .LP
 375 When the second or any subsequent line starts with \fB\&.so\fR, \fBman\fR
 376 ignores it; \fBtroff\fR(1) or \fBnroff\fR(1) processes the request in the usual
 377 manner.
 378 .SS "Processing SGML Manual Pages"
 379 .sp
 380 .LP
 381 Manual pages are identified as being marked up in SGML by the presence of the
 382 string \fB<!DOCTYPE\fR\&. If the file also contains the string
 383 \fBSHADOW_PAGE\fR, the file refers to another manual page for the content. The
 384 reference is made with a file entity reference to the manual page that contains
 385 the text. This is similar to the \fB\&.so\fR mechanism used in the nroff
 386 formatted man pages.
 387 .SH ENVIRONMENT VARIABLES
 388 .sp
 389 .LP
 390 See \fBenviron\fR(5) for descriptions of the following environment variables
 391 that affect the execution of \fBman\fR: \fBLANG\fR, \fBLC_ALL\fR,
 392 \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
 393 .sp
 394 .ne 2
 395 .na
 396 \fB\fBMANPATH\fR\fR
 397 .ad
 398 .RS 11n
 399 A colon-separated list of directories; each directory can be followed by a
 400 comma-separated list of sections. If set, its value overrides
 401 \fB/usr/share/man\fR as the default directory search path, and the \fBman.cf\fR
 402 file as the default section search path. The \fB-M\fR and \fB-s\fR flags, in
 403 turn, override these values.)
 404 .RE
 405 
 406 .sp
 407 .ne 2
 408 .na
 409 \fB\fBPAGER\fR\fR
 410 .ad
 411 .RS 11n
 412 A program to use for interactively delivering \fBman\fR's output to the screen.
 413 If not set, `\fBmore\fR \fB-s\fR' is used. See \fBmore\fR(1).
 414 .RE
 415 
 416 .sp
 417 .ne 2
 418 .na
 419 \fB\fBTCAT\fR\fR
 420 .ad
 421 .RS 11n
 422 The name of the program to use to display \fBtroff\fRed manual pages.
 423 .RE
 424 
 425 .sp
 426 .ne 2
 427 .na
 428 \fB\fBTROFF\fR\fR
 429 .ad
 430 .RS 11n
 431 The name of the formatter to use when the \fB-t\fR flag is given. If not set,
 432 \fBtroff\fR(1) is used.
 433 .RE
 434 
 435 .SH EXAMPLES
 436 .LP
 437 \fBExample 1 \fRCreating a PostScript Version of a man page
 438 .sp
 439 .LP
 440 The following example creates the \fBpipe\fR(2) man page in postscript for csh,
 441 tcsh, ksh and sh users:
 442 
 443 .sp
 444 .in +2
 445 .nf
 446         % env TCAT=/usr/lib/lp/postscript/dpost man -t -s 2 pipe > pipe.ps
 447 .fi
 448 .in -2
 449 .sp
 450 
 451 .sp
 452 .LP
 453 This is an alternative to using \fBman\fR \fB-t\fR, which sends the man page to
 454 the default printer, if the user wants a postscript file version of the man
 455 page.
 456 
 457 .LP
 458 \fBExample 2 \fRCreating a Text Version of a man page
 459 .sp
 460 .LP
 461 The following example creates the \fBpipe\fR(2) man page in ascii text:
 462 
 463 .sp
 464 .in +2
 465 .nf
 466 man pipe.2 | col -x -b > pipe.text
 467 .fi
 468 .in -2
 469 .sp
 470 
 471 .sp
 472 .LP
 473 This is an alternative to using \fBman\fR \fB-t\fR, which sends the man page to
 474 the default printer, if the user wants a text file version of the man page.
 475 
 476 .SH EXIT STATUS
 477 .sp
 478 .LP
 479 The following exit values are returned:
 480 .sp
 481 .ne 2
 482 .na
 483 \fB\fB0\fR\fR
 484 .ad
 485 .RS 6n
 486 Successful completion.
 487 .RE
 488 
 489 .sp
 490 .ne 2
 491 .na
 492 \fB\fB>0\fR\fR
 493 .ad
 494 .RS 6n
 495 An error occurred.
 496 .RE
 497 
 498 .SH FILES
 499 .sp
 500 .ne 2
 501 .na
 502 \fB\fB/usr/share/man\fR\fR
 503 .ad
 504 .sp .6
 505 .RS 4n
 506 Root of the standard manual page directory subtree
 507 .RE
 508 
 509 .sp
 510 .ne 2
 511 .na
 512 \fB\fB/usr/share/man/man?/*\fR\fR
 513 .ad
 514 .sp .6
 515 .RS 4n
 516 Unformatted nroff manual entries
 517 .RE
 518 
 519 .sp
 520 .ne 2
 521 .na
 522 \fB\fB/usr/share/man/sman?/*\fR\fR
 523 .ad
 524 .sp .6
 525 .RS 4n
 526 Unformatted \fBSGML\fR manual entries
 527 .RE
 528 
 529 .sp
 530 .ne 2
 531 .na
 532 \fB\fB/usr/share/man/cat?/*\fR\fR
 533 .ad
 534 .sp .6
 535 .RS 4n
 536 \fBnroff\fRed manual entries
 537 .RE
 538 
 539 .sp
 540 .ne 2
 541 .na
 542 \fB\fB/usr/share/man/fmt?/*\fR\fR
 543 .ad
 544 .sp .6
 545 .RS 4n
 546 \fBtroff\fRed manual entries
 547 .RE
 548 
 549 .sp
 550 .ne 2
 551 .na
 552 \fB\fB/usr/share/man/windex\fR\fR
 553 .ad
 554 .sp .6
 555 .RS 4n
 556 Table of contents and keyword database
 557 .RE
 558 
 559 .sp
 560 .ne 2
 561 .na
 562 \fB\fB/usr/share/lib/tmac/an\fR\fR
 563 .ad
 564 .sp .6
 565 .RS 4n
 566 Standard \fB-man\fR macro package
 567 .RE
 568 
 569 .sp
 570 .ne 2
 571 .na
 572 \fB\fB/usr/share/lib/sgml/locale/C/dtd/*\fR\fR
 573 .ad
 574 .sp .6
 575 .RS 4n
 576 \fBSGML\fR document type definition files
 577 .RE
 578 
 579 .sp
 580 .ne 2
 581 .na
 582 \fB\fB/usr/share/lib/sgml/locale/C/solbook/*\fR\fR
 583 .ad
 584 .sp .6
 585 .RS 4n
 586 \fBSGML\fR style sheet and entity definitions directories
 587 .RE
 588 
 589 .sp
 590 .ne 2
 591 .na
 592 \fB\fB/usr/share/lib/pub/eqnchar\fR\fR
 593 .ad
 594 .sp .6
 595 .RS 4n
 596 Standard definitions for \fBeqn\fR and \fBneqn\fR
 597 .RE
 598 
 599 .sp
 600 .ne 2
 601 .na
 602 \fB\fBman.cf\fR\fR
 603 .ad
 604 .sp .6
 605 .RS 4n
 606 Default search order by section
 607 .RE
 608 
 609 .SH ATTRIBUTES
 610 .sp
 611 .LP
 612 See \fBattributes\fR(5) for descriptions of the following attributes:
 613 .sp
 614 
 615 .sp
 616 .TS
 617 box;
 618 c | c
 619 l | l .
 620 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 621 _
 622 CSI     Enabled, see \fBNOTES\fR.
 623 _
 624 Interface Stability     Committed
 625 _
 626 Standard        See \fBstandards\fR(5).
 627 .TE
 628 
 629 .SH SEE ALSO
 630 .sp
 631 .LP
 632 \fBapropos\fR(1), \fBcat\fR(1), \fBcol\fR(1), \fBdpost\fR(1), \fBeqn\fR(1),
 633 \fBmore\fR(1), \fBnroff\fR(1), \fBrefer\fR(1), \fBtbl\fR(1), \fBtroff\fR(1),
 634 \fBvgrind\fR(1), \fBwhatis\fR(1), \fBcatman\fR(1M), \fBattributes\fR(5),
 635 \fBenviron\fR(5), \fBeqnchar\fR(5), \fBman\fR(5), \fBsgml\fR(5),
 636 \fBstandards\fR(5)
 637 .SH NOTES
 638 .sp
 639 .LP
 640 The \fB-f\fR and \fB-k\fR options use the \fBwindex\fR database, which is
 641 created by \fBcatman\fR(1M).
 642 .sp
 643 .LP
 644 The \fBman\fR command is CSI-capable. However, some utilities invoked by the
 645 \fBman\fR command, namely, \fBtroff\fR, \fBeqn\fR, \fBneqn\fR, \fBrefer\fR,
 646 \fBtbl\fR, and \fBvgrind\fR, are not verified to be CSI-capable. Because of
 647 this, the man command with the \fB-t\fR option can not handle non-EUC data.
 648 Also, using the \fBman\fR command to display man pages that require special
 649 processing through \fBeqn\fR, \fBneqn\fR, \fBrefer\fR, \fBtbl\fR, or
 650 \fBvgrind\fR can not be CSI-capable.
 651 .SH BUGS
 652 .sp
 653 .LP

 654 The manual is supposed to be reproducible either on a phototypesetter or on an
 655 \fBASCII\fR terminal. However, on a terminal some information (indicated by
 656 font changes, for instance) is lost.
 657 .sp
 658 .LP
 659 Some dumb terminals cannot process the vertical motions produced by the \fBe\fR
 660 (see \fBeqn\fR(1)) preprocessing flag. To prevent garbled output on these
 661 terminals, when you use \fBe\fR, also use \fBt\fR, to invoke \fBcol\fR(1)
 662 implicitly. This workaround has the disadvantage of eliminating superscripts
 663 and subscripts, even on those terminals that can display them. Control-q clears
 664 a terminal that gets confused by \fBeqn\fR(1) output.
   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.