MAN

Section: User Commands (1)
Index Return to Main Contents

NAME

man, apropos, whatis - display on-line reference manual information

SYNOPSIS

man [ -ltfikwuvthaAdgK ] [ -M manpath ] [ -Ssections ]

[ -Ttroffproc ] [ hwtype ] [ section ]

topic[/index] ...

apropos [ -uvdDK ] [ -M manpath ] [ hwtype ] keyword

whatis [ -uvdhD ] [ -M manpath ] [ hwtype ] topic ...

DESCRIPTION

The man program (and its links, apropos and whatis) formats and displays information from the on-line Programmer's Reference Manual. It can display complete entries selected by topic or brief one-line summaries selected by keyword (as apropos or with the -k or -K flags) or by topic (as whatis or with the -f flag). When invoked in the simplest way, without any options and with a topic, it displays the corresponding manual page formatted with If the standard output is to a terminal, the man page is piped by default through or else through the program specified in the user's PAGER environment variable if set.

Man pages are stored on-line as nroff source files and are reformatted whenever the formatted version is missing or has a newer modification date than the unformatted version. The formatted version of the man page stored in the corresponding cat*/ directory if it exists and is writable by the current user. Thus man1/stty.1 once formatted is stored in cat1/stty.1. Otherwise manual pages must be reformatted each time a user wishes to view them. If the root of the man tree from which the man page is taken contains the file tmac.an, then this file is used in lieu of the standard macros to reformat the page. Appropriate calls to and either or are automatically inserted as needed.

Section Selection

Some topics occur in more than one section of the manual. To select a man page from a particular section, put the section name in front of the topic, as in ``man 4 tty '' . For backwards compatibility with other man programs, certain non-numeric sections are recognized by longer aliases: local means section l, new means section n, public means section p, and old means section o. In other words, ``man new csh '' on the command line will search for a man page on the csh in section n of the manual.

The applicable topics for each component in the current MANPATH are sorted according to their section. The default ordering is ln16823457po. Thus, would be displayed before This ordering can be overridden on a site-wide basis by the system manager (see NOTES section below), a per-user basis using the MANSECT environment variable, or a per-command basis using the -S sections switch. Programmers may prefer a default ordering beginning 231 so that when they type ``man wait '' they see the man page for the system call rather than the one for the shell command of the same name. If multi-character sections exist (e.g. some systems have a man1m section) or subsection ordering is desired, then colons must be used to separate the sections. A FORTRAN programmer might prefer to set his MANSECT to 3f:2:3:1:6:8, so that when he asks for the manual page for system, he gets rather than the C function of the same name.

Case is significant for the topic itself, but not for the section. This allows you to make a distinction between the C compiler, and the C++ translator. However, section 3S is interpreted as section 3s to accommodate users who see a reference to the man page for and don't realize that it's stored in the file printf.3s.

Search Strategy

The man program by default consults the MANPATH environment variable for a list of complete man trees. If this variable is not set, then the user's PATH environment variable will be consulted instead. This way, if /usr/local/bin is before /usr/bin in the PATH variable, then /usr/local/man will be before /usr/man in the dynamically determined MANPATH variable. This is nice because it means the user need only add a PATH component, and the MANPATH will be automatically updated appropriately. This search order can be overridden on a site-wide basis by the system manager (see NOTES section below) or on a per-user basis by setting the environment variable MANPATH . This is a colon-separated list of directory names that contains subdirectories of the form man*/. A user keeping his own man pages under his home directory might place a line like the following in his ~/.cshrc file: ``setenv MANPATH $HOME/man:/usr/local/man:/usr/man '' The MANPATH may also be set on a per-command basis by using the -M command-line.

It is possible to install several complete sets of man pages on one host. These alternate sets are assumed to be installed in MANALT/subdir, where MANALT is an environment variable defaulting to /usr/local/man and subdir is assumed to be a complete man tree. If at least non-switch two arguments are supplied, then the MANALT directory is consulted to see whether it contains a sub-directory whose names is the first argument. This makes it easy to say things like ``man sun csh '' to read the csh man page from the installed set of sun man pages. This is equivalent to saying ``man -M /usr/local/man/sun csh '' (assuming MANALT is not set).

Indexing

Very long man pages are often broken up into several major subsections, whose tables of contents can be listed with the -i switch. To access one of these subsections directly, specify /index, where /index is the name of the subsection. For example, to see the section on expressions in the man page, use ``man csh/expr '' to skip to that section first. If index is not a valid section or subsection header, or if none is given, a list of all valid section headers is displayed and the user is prompted to select one. The special form of a missing subsection after the slash means to go into continuous menu mode, returning to the section menu after the manual page has been displayed.

The match against the index entries is not case-sensitive, nor is it required to be at the beginning of the string. For example, this allows ``/expr '' to be used to look up the ``Regular Expressions '' section. However, matches that do start at the front of the header are selected before those that do not. A numeric section index as listed by the -i flag may also be given, with an index of 0 meaning the whole page.

Man page indices (tables of contents) are generated automatically when needed. To save time, if a writable idx*/ subdirectory exists in the root of the man tree, the index is left there under the same name as its man page for quicker access in the future. Indices older than their parent man page are rebuilt upon demand.

As a special case of indexing, the form //string starts the PAGER at an arbitrary string in the text of the man page rather than at a subsection index.

Note that the /index feature may not be used in conjunction with the -l (local file) switch. The -i switch may still be used with local files.

Online Problem Reports

Some vendors provide their customers with electronically readable problem reports; also, some sites may wish to maintain their own list of known problems. To support inclusion of these in the man pages, the man program knows to look in a set of pr* subdirectories for additional source. For example, if you are reading the man page contained in /usr/man/man1/foo.1, then if there exists a file called /usr/man/pr1/foo.1, this will be appended to the data passed to nroff or troff as an additional "KNOWN PROBLEMS" section. These files should be in nroff format.

OPTIONS

-Mmanpath: Changes the search path for finding man pages for just this command, overriding the current MANPATH environment variable or system default. See the section on "Search Strategy" for further details.
-Ssections: sets the section and subsection ordering for just this command, overriding the current MANSECT environment variables or system default. See the Section Selection for further details.
-f: directs man to print out the applicable one-line descriptions for each corresponding topic. These one-line descriptions are stored in separate whatis files for each component in the specified MANPATH . If versions of these databases exist, these are used for more rapid location of manual pages. See for directions on generating the whatis databases. This switch is automatically enabled if man is invoked as whatis.
-k: direct man to search the whatis databases for any entry matching the given keyword. This is useful when the precise topic is unknown; it reports the topics that have to do with the given keywords, according to their whatis descriptions. Output will be sent to the user's PAGER . This switch is automatically enabled if man is invoked as apropos.
-K: same as -k except regular expressions as in may be used in the keywords.
-g: Grep through all man pages for one or more perl expressions. Compressed man pages will be correctly processed by
-t: is used to typeset the manual pages, usually using or a front-end for the same. If the default system typesetter is not desired, it can be overridden either with the TROFF environment variable or the -T flag.
-Ttroffproc: selects an alternate typesetting program, overriding the current TROFF environment variable or system default. It is most often used to select a previewer for workstations that support previewing of troff output.
-l: is used with specific file names rather than with topics. The same processing as man would perform on a system manual page will be performed on the given file. This is useful when first writing new manual pages or viewing ones not yet installed. It may be used in conjunction with other switches, such as -t. The indexing feature is not available for local man pages except via the -i switch.
-w: is used to determine the full pathnames of the files that man would display for the given topic. This is useful when the same topic occurs in more than one section of the manual or in more than one of the components in the supplied MANPATH . The files are listed in the order in which they would be presented to the user.
-a: displays all man pages for all possible matches for a given topic. Its effect is similar to calling man on all the files returned by the -w switch.
-A: prompts the user to select which man page is desired if more than one are found. A selection of 0 is effectively the same as having used the -a option in the first place.
-i: displays the complete section and subsection index for a given topic.
-v: prints out the current revision of the program as stored by
-u: displays a long usage message, piped through the user's PAGER . It includes the current defaults for PAGER , MANPATH , MANSECT , MANALT , and TROFF .
-h: forces man to ignore the whatis databases and search for its manual pages the slow way. This is the default behavior if no whatis database has been created for a particular man tree.
-d: triggers debugging output. All externally invoked programs such as nroff and egrep will have their arguments displayed before they are called. Certain other debugging information is also printed.
-D: causes embedded backspaces and their preceding characters in cat pages to be stripped upon output. This is useful for producing utterly clean output, such as when being viewed in an window.

EXAMPLES


man stty            # show me the first stty man page
man -w stty         # which stty man pages are there?
man 3 stty          # show me the one from section 3
man -a tty          # show all man pages on tty

man old makewhatis  # show me the makewhatis man page from mano
man new csh         # show me the csh man page from mann

man sun csh         # show me the csh man page for suns 
                    (assumes $MANALT/sun contains sun man pages)

man -i uucp         # get list of sections in uucp man page
man -ai tty         # give list of sections on all tty pages
man adb/bugs        # check for BUGS section of adb man page
man man/exam        # start at this example section
man ksh/            # select from section menu for ksh man page
man sun cron/files  # go to the FILES section of the sun cron man page

man -f rcs          # what is rcs?
whatis rcs          # same as previous
whatis vax rcs      # same as previous, but only vax man pages

man -k rcs          # what knows about rcs?
apropos rcs         # same as previous
apropos sun rcs     # same as previous, but only sun man pages
man -g 'file[-\s]*system' # find pages referencing file systems

man -S231 wait      # override system section ordering 
man -S3f:3s:3:2:1 system# subsection ordering

man -M  ~/man hack  # use ~/man as only man tree

man -t 4 tty        # troff tty(4) man page
man -at tty         # troff all tty pages
man -Tpnitroff perl # preview perl man page
man -lTpnitroff ../foo.1# preview local file as man page

man -l file.x       # run man on local file
man -tl file.x      # print local file as man would
man -il file.x      # get section index on local page

ENVIRONMENT

Man explicitly checks for the following environment variables; if they are present, they will override its internal defaults:

MANPATH: The colon-separated list of man trees for locating man pages. This may itself be overridden by the command line flags -M or by specifying an alternate hardware type.
MANSECT: The default ordering for section and subsection sorting. It need only be separated by colons if multi-character sections such as man1m exist or if subsection ordering is desired, such as to place subsection 3f in front of section 3 .
MANALT: The directory to check for alternate sets of man trees. This is useful for storing the man pages for several different machine architectures or versions of the operating system. See the Search Strategy section for details.
PAGER: The user's preferred viewer of paged output. Note that often the pager itself will consult the environment; for example, more looks for a MORE variable and less looks for a LESS variable in the environment.
TROFF: The preferred typesetter program. It should recognize troff input and switches. This may be overridden using the -T command line flag.

FILES


/usr/man                   default man tree
/usr/man/man*/*.*          unformatted (nroff source) man pages
/usr/man/cat*/*.*          formatted man pages
/usr/man/idx*/*.*          indices for section headers
/usr/man/whatis            default whatis database, text version
/usr/man/whatis.dir        dbm index file for default whatis database
/usr/man/whatis.pag        dbm data file for default whatis database
/usr/lib/perl/getopts.pl   required perl library file
/usr/lib/perl/stat.pl      required perl library file

NOTES

This version of man is written entirely in the programming language and thus requires that perl be properly installed on your system to run. Because man is distributed in a script, it can be easily reconfigured by the system managers to suit their site's particular style. This is good, as some of the default settings are somewhat idiosyncratic to the set-up at the CONVEX home office.

Be sure to save a copy of the original man program before any modification.

Things that can be configured include:

*: the default PAGER and its flags (alternate flags can be provided for less)
*: system defaults for MANPATH , MANSECT , MANALT , and TROFF .
*: paths for troff, nroff, tbl, eqn, neqn, ul, col, egrep, and compress
*: whether you have compressed man pages and how they are stored
*: which section aliases you want (as in public being recognized as section p)
*: whether to recognize man pages whose NAME sections don't mention their own names

To save disk space at the expense of execution time, a site may wish to run on the manual entries where available. The man program understands how to read compressed man pages, and knows to create a compressed cat page if the source man page was compressed to start with.

When running on slow CPUs, the start-up time for parsing the script may be annoying. These sites can skip this parsing phase at each invocation of by using perl's -u flag to dump a binary image of the interpreter.

DIAGNOSTICS

Several self-explanatory diagnostics are possible, such as ``No manual entry for xyzzy '', but the following warnings may not be intuitive:

``But what do you want from section %s? '' A section was specified but no topic.

``No dbm file for %s: %m ''
This means that the named man tree does not have an accessible dbm version of its whatis database and that should be run on it. This only shows up when -d option is used. %m is the appropriate message.

``%s has disappeared -- rerun makewhatis ''
A man page has been removed since makewhatis was last run. Note that new man pages being added will NOT be detected.

``nroff of %s failed ''
For some reason nroff did not exit correctly. The disk may be mounted read-only, it might be full, or nroff may not be installed on your system. Contact your system manager.

``%s was length 0; disk full? ''
A cat page was empty. The man program unlinks the useless cat page, issues this warning, and exits non-zero. Rerun the command and if the problem persists, contact your system manager.

``/tmp not writable ''
The /tmp and /usr/man/cat* directories are not writable by you. Contact your system manager.

``No whatis databases found, please run makewhatis ''
The man program was unable to find a whatis database for use with apropos or man -k in any of the directories listed in the MANPATH. Have your system manager run makewhatis on the system manual page directories, and run makewhatis on any personal manual page directories.

``bad eval: %s ''
``can't eval %s: %s ''
These are internal errors that should never occur. Contact your system manager, who should submit a problem report.

RESTRICTIONS

Once a whatis database has been created for a particular man root, new man pages will not be found unless the -h flag is used or until makewhatis is rerun.

If your PAGER is bold text shows up in the normal font; however, does display bold text in your terminal's bold font.

BUGS

The manual is supposed to be reproducible either on the phototypesetter or on an ASCII terminal. However, on a terminal, some information is necessarily lost.

The -t flag for man only works if the host system supports troff.

Not all systems have compress installed on them.