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.