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.
|