Penguin
Recent Changes
Annotated edit history of man(1) version 3, including all changes. View license author blame.
Rev Author # Line
1 perry 1 man
2 !!!man
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 EXAMPLES
7 OVERVIEW
8 DEFAULTS
9 OPTIONS
10 EXIT STATUS
11 ENVIRONMENT
12 FILES
13 SEE ALSO
14 HISTORY
15 ----
16 !!NAME
17
18
19 man - an interface to the on-line reference manuals
20 !!SYNOPSIS
21
22
23 __man__ [[__-c__|__-w__|__-tZHT__ ''device'']
24 [[__-adhu7V__] [[__-m__ ''system''[[,...]] [[__-L__
25 ''locale''] [[__-p__ ''string''] [[__-M__
26 ''path''] [[__-P__ ''pager''] [[__-r__
27 ''prompt''] [[__-S__ ''list''] [[__-e__
28 ''extension''] [[[[''section''] ''page'' ...]
29 ...__
30 man -l__ [[__-7__] [[__-tZHT__ ''device'']
31 [[__-p__ ''string''] [[__-P__ ''pager'']
32 [[__-r__ ''prompt''] ''file'' ...__
33 man -k__ [[''apropos options''] ''regexp'' ...__
34 man -f__ [[''whatis options''] ''page''
35 ...
36 !!DESCRIPTION
37
38
39 __man__ is the system's manual pager. Each ''page''
40 argument given to __man__ is normally the name of a
41 program, utility or function. The ''manual page''
42 associated with each of these arguments is then found and
43 displayed. A ''section'', if provided, will direct
44 __man__ to look only in that ''section'' of the
45 manual. The default action is to search in all of the
46 available ''sections'', following a pre-defined order and
47 to show only the first ''page'' found, even if
48 ''page'' exists in several ''sections''.
49
50
51 The table below shows the ''section'' numbers of the
52 manual followed by the types of pages they
53 contain.
54
55
56 A manual ''page'' consists of several parts.
57
58
59 They may be labelled __NAME__, __SYNOPSIS__,
60 __DESCRIPTION__, __OPTIONS__, __FILES__, __SEE
61 ALSO__, __BUGS__, and __AUTHOR__.
62
63
64 The following conventions apply to the __SYNOPSIS__
65 section and can be used as a guide in other
66 sections.
67
68
69 The command or function illustration is a pattern that should match all possible invocations. In some cases it is advisable to illustrate several exclusive invocations as is shown in the __SYNOPSIS__ section of this manual page.
70 !!EXAMPLES
71
72
73 __man__ ''ls''
74
75
76 Display the manual page for the ''item'' (program)
77 ''ls''.
78
79
80 __man -a__ ''intro''
81
82
83 Display, in succession, all of the available ''intro''
84 manual pages contained within the manual. It is possible to
85 quit between successive displays or skip any of
86 them.
87
88
89 __man -t__ ''alias'' | ''lpr -Pps''
90
91
92 Format the manual page referenced by `''alias''', usually
93 a shell manual page, into the default __troff__ or
94 __groff__ format and pipe it to the printer named
95 ''ps''. The default output for __groff__ is usually
2 perry 96 !PostScript. __man --help__ should advise as to which
1 perry 97 processor is bound to the __-t__ option.
98
99
100 __man -l -T__''dvi ./foo.1x.gz'' ____
101 ''./foo.1x.dvi''
102
103
104 This command will decompress and format the nroff source
105 manual page ''./foo.1x.gz'' into a __device independent
106 (dvi)__ file. The redirection is necessary as the
107 __-T__ flag causes output to be directed to __stdout__
108 with no pager. The output could be viewed with a program
2 perry 109 such as __xdvi__ or further processed into !PostScript
1 perry 110 using a program such as __dvips.__
111
112
113 __man -k__ ''printf''
114
115
116 Search the short descriptions and manual page names for the
117 keyword ''printf'' as regular expression. Print out any
118 matches. Equivalent to __apropos -r__
119 ''printf''__.__
120
121
122 __man -f__ ''smail''
123
124
125 Lookup the manual pages referenced by ''smail'' and print
126 out the short descriptions of any found. Equivalent to
127 __whatis -r__ ''smail''__.__
128 !!OVERVIEW
129
130
131 Many options are available to __man__ in order to give as
132 much flexibility as possible to the user. Changes can be
133 made to the search path, section order, output processor,
134 and other behaviours and operations detailed
135 below.
136
137
138 If set, various environment variables are interrogated to
139 determine the operation of __man__. It is possible to set
140 the `catch all' variable $__MANOPT__ to any string in
141 command line format with the exception that any spaces used
142 as part of an option's argument must be escaped (preceded by
143 a backslash). __man__ will parse $__MANOPT__ prior to
144 parsing its own command line. Those options requiring an
145 argument will be overridden by the same options found on the
146 command line. To reset all of the options set in
147 $__MANOPT__, __-D__ can be specified as the initial
148 command line option. This will allow man to `forget' about
149 the options specified in $__MANOPT__ although they must
150 still have been valid.
151
152
153 The manual pager utilities packaged as __man_db__ make
154 extensive use of __index__ database caches. These caches
155 contain information such as where each manual page can be
156 found on the filesystem and what its ''whatis'' (short
157 one line description of the man page) contains, and allow
158 __man__ to run faster than if it had to search the
159 filesystem each time to find the appropriate manual page. If
160 requested using the __-u__ option, __man__ will ensure
161 that the caches remain consistent, which can obviate the
162 need to manually run software to update traditional
163 ''whatis'' text databases.
164
165
166 If __man__ cannot find a __mandb__ initiated
167 __index__ database for a particular manual page
168 hierarchy, it will still search for the requested manual
169 pages, although file globbing will be necessary to search
170 within that hierarchy. If __whatis__ or __apropos__
171 fails to find an __index__ it will try to extract
172 information from a traditional ''whatis'' database
173 instead.
174
175
176 These utilities support compressed source nroff files
177 having, by default, the extensions of __.Z__, __.z__
178 and __.gz__. It is possible to deal with any compression
179 extension, but this information must be known at compile
180 time. Also, by default, any cat pages produced are
181 compressed using __gzip__. Each `global' manual page
182 hierarchy such as ''/usr/share/man'' or
183 ''/usr/X11R6/man'' may have any directory as its cat page
184 hierarchy. Traditionally the cat pages are stored under the
185 same hierarchy as the man pages, but for reasons such as
186 those specified in the __File Hierarchy Standard (FHS)__,
187 it may be better to store them elsewhere. For details on how
188 to do this, please read manpath(5). For details on
189 why to do this, read the standard.
190
191
192 International support is available with this package. Native
193 language manual pages are accessible (if available on your
194 system) via use of ''locale'' functions. To activate such
195 support, it is necessary to set either $__LC_MESSAGES__,
196 $__LANG__ or another system dependent environment
197 variable to your language locale, usually specified in the
198 __POSIX 1003.1__ based format:
199
200
201 language''''_____territory''''.____character-set'''',____version''''
202
203
204 If the desired page is available in your ''locale,'' it
205 will be displayed in lieu of the standard (usually American
206 English) page.
207
208
209 Support for international message catalogues is also
210 featured in this package and can be activated in the same
211 way, again if available. If you find that the manual pages
212 and message catalogues supplied with this package are not
213 available in your native language and you would like to
214 supply them, please contact the maintainer who will be
215 coordinating such activity.
216
217
218 For information regarding other features and extensions
219 available with this manual pager, please read the documents
220 supplied with the package.
221 !!DEFAULTS
222
223
224 __man__ will search for the desired manual pages within
225 the ''index'' database caches. If the __-u__ option is
226 given, a cache consistency check is performed to ensure the
227 databases accurately reflect the filesystem. If this option
228 is always given, it is not generally necessary to run
229 __mandb__ after the caches are initially created, unless
230 a cache becomes corrupt. However, the cache consistency
231 check can be slow on systems with many manual pages
232 installed, so it is not performed by default, and system
233 administrators may wish to run __mandb__ every week or so
234 to keep the database caches fresh. To forestall problems
235 caused by outdated caches, __man__ will fall back to file
236 globbing if a cache lookup fails, just as it would if no
237 cache was present.
238
239
240 Once a manual page has been located, a check is performed to
241 find out if a relative preformatted `cat' file already
242 exists and is newer than the nroff file. If it does and is,
243 this preformatted file is (usually) decompressed and then
244 displayed, via use of a pager. The pager can be specified in
245 a number of ways, or else will fall back to a default is
246 used (see option __-P__ for details). If no cat is found
247 or is older than the nroff file, the nroff is filtered
248 through various programs and is shown
249 immediately.
250
251
252 If a cat file can be produced (a relative cat directory
253 exists and has appropriate permissions), __man__ will
254 compress and store the cat file in the
255 background.
256
257
258 The filters are deciphered by a number of means. Firstly,
259 the command line option __-p__ or the environment
260 variable $__MANROFFSEQ__ is interrogated. If __-p__
261 was not used and the environment variable was not set, the
262 initial line of the nroff file is parsed for a preprocessor
263 string. To contain a valid preprocessor string, the first
264 line must resemble
265
266
267 __'__ __string____
268
269
270 where __string__ can be any combination of letters
271 described by option __-p__ below.
272
273
274 If none of the above methods provide any filter information,
275 a default set is used.
276
277
278 A formatting pipeline is formed from the filters and the
279 primary formatter (__nroff__ or [[__tg__]__roff__
280 with __-t__) and executed. Alternatively, if an
281 executable program ''mandb_nfmt'' (or ''mandb_tfmt''
282 with __-t__) exists in the man tree root, it is executed
283 instead. It gets passed the manual source file, the
284 preprocessor string, and optionally the device specified
285 with __-T__ as arguments.
286 !!OPTIONS
287
288
289 Non argument options that are duplicated either on the
290 command line, in $__MANOPT__, or both, are not harmful.
291 For options that require an argument, each duplication will
292 override the previous argument value.
293
294
295 __-l, --local-file__
296
297
298 Activate `local' mode. Format and display local manual files
299 instead of searching through the system's manual collection.
300 Each manual page argument will be interpreted as an nroff
301 source file in the correct format. No cat file is produced.
302 If '-' is listed as one of the arguments, input will be
303 taken from stdin. When this option is not used, and man
304 fails to find the page required, before displaying the error
305 message, it attempts to act as if this option was supplied,
306 using the name as a filename and looking for an exact
307 match.
308
309
310 __-L__ ''locale''__,
311 --locale=__''locale''
312
313
314 __man__ will normally determine your current locale by a
315 call to the C function setlocale(3) which
316 interrogates various environment variables, possibly
317 including $__LC_MESSAGES__ and $__LANG__. To
318 temporarily override the determined value, use this option
319 to supply a ''locale'' string directly to __man__.
320 Note that it will not take effect until the search for pages
321 actually begins. Output such as the help message will always
322 be displayed in the initially determined
323 locale.
324
325
326 __-D, --default__
327
328
329 This option is normally issued as the very first option and
330 resets __man's__ behaviour to its default. Its use is to
331 reset those options that may have been set in
332 $__MANOPT__. Any options that follow __-D__ will have
333 their usual effect.
334
335
336 __-M__ ''path''__,
337 --manpath=__''path''
338
339
340 Specify an alternate manpath to use. By default, __man__
341 uses __manpath__ derived code to determine the path to
342 search. This option overrides the $__MANPATH__
343 environment variable and causes option __-m__ to be
344 ignored.
345
346
347 A path specified as a manpath must be the root of a manual
348 page hierarchy structured into sections as described in the
349 man_db manual (under
350 -l__ option.
351
352
353 __-P__ ''pager''__,
354 --pager=__''pager''
355
356
357 Specify which output pager to use. By default, __man__
358 uses __exec /usr/bin/pager -s__. This option overrides
359 the $__PAGER__ environment variable and is not used in
360 conjunction with __-f__ or __-k__.
361
362
363 __-r__ ''prompt''__,
364 --prompt=__''prompt''
365
366
367 If a recent version of __less__ is used as the pager,
368 __man__ will attempt to set its prompt and some sensible
369 options. The default prompt looks like
370
371
372 __Manual page__ ''name''__(__''sec''__)
373 line__ ''x''
374
375
376 where ''name'' denotes the manual page name, ''sec''
377 denotes the section it was found under and ''x'' the
378 current line number. This is achieved by using the
379 $__LESS__ environment variable.
380
381
382 Supplying __-r__ with a string will override this
383 default. The string may contain the text __$MAN_PN__
384 which will be expanded to the name of the current manual
385 page and its section name surrounded by `(' and `)'. The
386 string used to produce the default could be expressed
387 as
388
389
390 __\ Manual\ page\ $MAN_PN\ ?ltline\ %lt?L/%L.:
391 byte\ %bB?s/%s..?\ (END):?pB %pB\%..__
392
393
394 It is broken into two lines here for the sake of readability
395 only. For its meaning see the less(1) manual page.
396 The prompt string is first evaluated by the shell. All
397 double quotes, back-quotes and backslashes in the prompt
398 must be escaped by a preceding backslash. The prompt string
399 may end in an escaped $ which may be followed by further
400 options for less. By default __man__ sets the __-ix8__
401 options.
402
403
404 __-7, --ascii__
405
406
407 When viewing a pure ascii(7) manual page on a 7 bit
408 terminal or terminal emulator, some characters may not
409 display correctly when using the ''latin1''(7) device
410 description with __GNU nroff__. This option allows pure
411 ''ascii'' manual pages to be displayed in ''ascii''
412 with the ''latin1'' device. It will not translate any
413 ''latin1'' text. The following table shows the
414 translations performed.
415
416
417 If the ''latin1'' column displays correctly, your terminal may be set up for ''latin1'' characters and this option is not necessary. If the ''latin1'' and ''ascii'' columns are identical, you are reading this page using this option or __man__ did not format this page using the ''latin1'' device description. If the ''latin1'' column is missing or corrupt, you may need to view manual pages with this option.
418
419
420 This option is ignored when using options __-t__,
421 __-H__, __-T__, or __-Z__ and may be useless for
422 __nroff__ other than __GNU's__.
423
424
425 __-S__ ''list''__,
426 --sections=__''list''
427
428
429 List is a colon-separated list of `order specific' manual
430 sections to search. This option overrides the
431 $__MANSECT__ environment variable.
432
433
434 __-a, --all__
435
436
437 By default, __man__ will exit after displaying the most
438 suitable manual page it finds. Using this option forces
439 __man__ to display all the manual pages with names that
440 match the search criteria.
441
442
443 __-c, --catman__
444
445
446 This option is not for general use and should only be used
447 by the __catman__ program.
448
449
450 __-d, --debug__
451
452
453 Don't actually display any manual pages, but do print lots
454 of debugging information.
455
456
457 __-e__ ''sub-extension''__,
458 --extension=__''sub-extension''
459
460
461 Some systems incorporate large packages of manual pages,
462 such as those that accompany the __Tcl__ package, into
463 the main manual page hierarchy. To get around the problem of
464 having two manual pages with the same name such as
465 exit(3), the __Tcl__ pages were usually all
466 assigned to section __l__. As this is unfortunate, it is
467 now possible to put the pages in the correct section, and to
468 assign a specific `extension' to them, in this case,
469 exit(3tcl). Under normal operation, __man__ will
470 display exit(3) in preference to exit(3tcl).
471 To negotiate this situation and to avoid having to know
472 which section the page you require resides in, it is now
473 possible to give __man__ a string indicating which
474 package the page must belong to. Using the above example,
475 supplying the option __-e tcl__ to __man__ will
476 restrict the search to pages having an extension of
477 __*tcl__.
478
479
480 __-f, --whatis__
481
482
483 Equivalent to __whatis__. Display a short description
484 from the manual page, if available. See whatis(1) for
485 details.
486
487
488 __-h, --help__
489
490
491 Print a help message and exit.
492
493
494 __-k, --apropos__
495
496
497 Equivalent to __apropos__. Search the short manual page
498 descriptions for keywords and display any matches. See
499 apropos(1) for details.
500
501
502 __-m__ ''system''[[,...]__,
503 --systems=__''system''[[,...]
504
505
506 If this system has access to other operating system's manual
507 pages, they can be accessed using this option. To search for
508 a manual page from NewOS's manual page collection, use the
509 option __-m NewOS__.
510
511
512 The ''system'' specified can be a combination of comma
513 delimited operating system names. To include a search of the
514 native operating system's manual pages, include the system
515 name __man__ in the argument string. This option will
516 override the $__SYSTEM__ environment
517 variable.
518
519
520 __-p__ ''string''__,
521 --preprocessor=__''string''
522
523
524 Specify the sequence of preprocessors to run before
525 __nroff__ or __troff__/__groff__. Not all
526 installations will have a full set of preprocessors. Some of
527 the preprocessors and the letters used to designate them
528 are: __eqn__ (__e__), __grap__ (__g__),
529 __pic__ (__p__), __tbl__ (__t__), __vgrind__
530 (__v__), __refer__ (__r__). This option overrides
531 the $__MANROFFSEQ__ environment variable. __zsoelim__
532 is always run as the very first preprocessor.
533
534
535 __-u, --update__
536
537
538 This option causes __man__ to perform an `inode level'
539 consistency check on its database caches to ensure that they
540 are an accurate representation of the filesystem. It will
541 only have a useful effect if __man__ is installed with
542 the setuid bit set.
543
544
545 __-t, --troff__
546
547
548 Use ''/usr/bin/groff -mandoc'' to format the manual page
549 to stdout. This option is not required in conjunction with
550 __-H__, __-T__, or __-Z__.
551
552
553 __-T__ ''device''__, --troff-device__
554 [[''=device'']
555
556
557 This option is used to change __groff__ (or possibly
558 __troff's__) output to be suitable for a device other
559 than the default. It implies __-t__. Examples (provided
560 with Groff-1.09) include __dvi__, __latin1__,
561 __X75__ and __X100__.
562
563
564 __-Z, --ditroff__
565
566
567 __groff__ will run __troff__ and then use an
568 appropriate post-processor to produce output suitable for
569 the chosen device. If ''/usr/bin/groff -mandoc'' is
570 __groff__, this option is passed to __groff__ and will
571 suppress the use of a post-processor. It implies
572 __-t__.
573
574
575 __-H, --html__
576
577
578 This option will cause __groff__ to produce HTML output,
579 and will display that output in a web browser. The choice of
580 browser is determined by the $__BROWSER__ environment
581 variable, or by a compile-time default if that is unset
582 (usually __lynx__). This option implies __-t__, and
583 will only work with __GNU troff__.
584
585
586 __-w, --where, --location__
587
588
589 Don't actually display the manual pages, but do print the
590 location(s) of the files that would be formatted or
591 displayed. If the file is a cat file, also show the location
592 of its source nroff file.
593
594
595 __-V, --version__
596
597
598 Display version information.
599 !!EXIT STATUS
600
601
602 __0__
603
604
605 Successful program execution.
606
607
608 __1__
609
610
611 Usage, syntax or configuration file error.
612
613
614 __2__
615
616
617 Operational error.
618
619
620 __3__
621
622
623 A child process returned a non-zero exit
624 status.
625
626
627 __16__
628
629
630 At least one of the pages/files/keywords didn't exist or
631 wasn't matched.
632 !!ENVIRONMENT
633
634
635 __MANPATH__
636
637
638 If $__MANPATH__ is set, its value is used as the path to
639 search for manual pages.
640
641
642 __MANROFFSEQ__
643
644
645 If $__MANROFFSEQ__ is set, its value is used to determine
646 the set of preprocessors to pass each manual page through.
647 The default preprocessor list is system
648 dependent.
649
650
651 __MANSECT__
652
653
654 If $__MANSECT__ is set, its value is a colon-delimited
655 list of sections and it is used to determine which manual
656 sections to search and in what order.
657
658
659 __PAGER__
660
661
662 If $__PAGER__ is set, its value is used as the name of
663 the program used to display the manual page. By default,
664 __exec /usr/bin/pager -s__ is used.
665
666
667 __BROWSER__
668
669
670 If $__BROWSER__ is set, its value is a colon-delimited
671 list of commands, each of which in turn is used to try to
672 start a web browser for __man --html__. In each command,
673 ''%s'' is replaced by a filename containing the HTML
674 output from __groff__, ''%%'' is replaced by a single
675 percent sign (%), and ''%c'' is replaced by a colon
676 (:).
677
678
679 __SYSTEM__
680
681
682 If $__SYSTEM__ is set, it will have the same effect as
683 option __-m string__ where string will be taken as
684 $__SYSTEM__'s contents.
685
686
687 __MANOPT__
688
689
690 If $__MANOPT__ is set, it will be parsed prior to
691 __man's__ command line and is expected to be in a similar
692 format. As all of the other __man__ specific environment
693 variables can be expressed as command line options, and are
694 thus candidates for being included in $__MANOPT__ it is
695 expected that they will become obsolete. N.B. All spaces
696 that should be interpreted as part of an option's argument
697 must be escaped.
698
699
700 __MANWIDTH__
701
702
703 If $__MANWIDTH__ is set, its value is used as the line
704 length for which manual pages should be formatted. If it is
705 not set, manual pages will be formatted with a line length
706 appropriate to the current terminal (using an
707 ioctl(2) if available, the value of $__COLUMNS__,
708 or falling back to 80 characters if neither is available).
709 Cat pages will only be saved when the default formatting can
710 be used, that is when the terminal line length is between 66
711 and 80 characters.
712
713
714 __LANG__, __LC_MESSAGES__
715
716
717 Depending on system and implementation, either or both of
718 $__LANG__ and $__LC_MESSAGES__ will be interrogated
719 for the current message locale. __man__ will display its
720 messages in that locale (if available). See
721 setlocale(3) for precise details.
722 !!FILES
723
724
725 ''/etc/manpath.config''
726
727
728 man_db configuration file.
729
730
731 ''/usr/share/man''
732
733
734 A global manual page hierarchy.
735
736
737 ''/usr/share/man/index.(bt|db|dir|pag)''
738
739
740 A traditional global ''index'' database
741 cache.
742
743
744 ''/var/cache/man/index.(bt|db|dir|pag)''
745
746
747 An alternate or FHS compliant global ''index'' database
748 cache.
749 !!SEE ALSO
750
751
752 mandb(8), manpath(1), manpath(5),
753 apropos(1), whatis(1), catman(8),
754 less(1), nroff(1), troff(1),
755 groff(1), zsoelim(1), setlocale(3),
3 perry 756 man(7), ascii(7), latin1(7), the man_db
1 perry 757 package manual, __FSSTND__.
758 !!HISTORY
759
760
761 1990, 1991 - Originally written by John W. Eaton
762 (jwe@che.utexas.edu).
763
764
765 Dec 23 1992: Rik Faith (faith@cs.unc.edu) applied bug fixes
766 supplied by Willem Kasdorp
767 (wkasdo@nikhefk.nikef.nl).
768
769
770 30th April 1994 - 23rd February 2000: Wilf.
771 (G.Wilford@ee.surrey.ac.uk) has been developing and
772 maintaining this package with the help of a few dedicated
773 people.
774
775
776 30th October 1996 - 30th March 2001: Fabrizio Polacco
777
778
779 31st March 2001 - 07 September 2001: Colin Watson
780 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.