man - format and display the on-line manual pages
manpath - determine user's search path for man pages
SYNOPSIS
man [-acdfFhkKtwW] [--path] [-m system] [-p string] [-C
config_file] [-M pathlist] [-P pager] [-S section_list]
[section] name ...
DESCRIPTION
man formats and displays the on-line manual pages. If you
specify section, man only looks in that section of the
manual. name is normally the name of the manual page,
which is typically the name of a command, function, or
file. However, if name contains a slash (/) then man
interprets it as a file specification, so that you can do
man ./foo.5 or even man /cd/foo/bar.1.gz.
See below for a description of where man looks for the
manual page files.
OPTIONS
-C config_file
Specify the configuration file to use; the default
is /etc/man.config. (See man.conf(5).)
-M path
Specify the list of directories to search for man
pages. Separate the directories with colons. An
empty list is the same as not specifying -M at all.
See SEARCH PATH FOR MANUAL PAGES.
-P pager
Specify which pager to use. This option overrides
the MANPAGER environment variable, which in turn
overrides the PAGER variable. By default, man uses
/usr/bin/less-isr.
-S section_list
List is a colon separated list of manual sections
to search. This option overrides the MANSECT envi
ronment variable.
-a By default, man will exit after displaying the
first manual page it finds. Using this option
forces man to display all the manual pages that
match name, not just the first.
-c Reformat the source man page, even when an up-to-
date cat page exists. This can be meaningful if
the cat page was formatted for a screen with a dif
ferent number of columns, or if the preformatted
-d Don't actually display the man pages, but do print
gobs of debugging information.
-D Both display and print debugging info.
-f Equivalent to whatis.
-F or --preformat
Format only - do not display.
-h Print a one-line help message and exit.
-k Equivalent to apropos.
-K Search for the specified string in *all* man pages.
Warning: this is probably very slow! It helps to
specify a section. (Just to give a rough idea, on
my machine this takes about a minute per 500 man
pages.)
-m system
Specify an alternate set of man pages to search
based on the system name given.
-p string
Specify the sequence of preprocessors to run before
nroff or troff. Not all installations will have a
full set of preprocessors. Some of the preproces
sors and the letters used to designate them are:
eqn (e), grap (g), pic (p), tbl (t), vgrind (v),
refer (r). This option overrides the MANROFFSEQ
environment variable.
-t Use /usr/bin/groff -Tps -mandoc to format the man
ual page, passing the output to stdout. The output
from /usr/bin/groff -Tps -mandoc may need to be
passed through some filter or another before being
printed.
-w or --path
Don't actually display the man pages, but do print
the location(s) of the files that would be format
ted or displayed. If no argument is given: display
(on stdout) the list of directories that is
searched by man for man pages. If manpath is a link
to man, then "manpath" is equivalent to "man
--path".
-W Like -w, but print file names one per line, without
additional information. This is useful in shell
commands like man -aW man | xargs ls -l
Man will try to save the formatted man pages, in order to
save formatting time the next time these pages are needed.
Traditionally, formatted versions of pages in DIR/manX are
saved in DIR/catX, but other mappings from man dir to cat
dir can be specified in /etc/man.config. No cat pages are
saved when the required cat directory does not exist.
It is possible to make man suid to a user man. Then, if a
cat directory has owner man and mode 0755 (only writable
by man), and the cat files have owner man and mode 0644 or
0444 (only writable by man, or not writable at all), no
ordinary user can change the cat pages or put other files
in the cat directory. If man is not made suid, then a cat
directory should have mode 0777 if all users should be
able to leave cat pages there.
The option -c forces reformatting a page, even if a recent
cat page exists.
SEARCH PATH FOR MANUAL PAGES
man uses a sophisticated method of finding manual page
files, based on the invocation options and environment
variables, the /etc/man.config configuration file, and
some built in conventions and heuristics.
First of all, when the name argument to man contains a
slash (/), man assumes it is a file specification itself,
and there is no searching involved.
But in the normal case where name doesn't contain a slash,
man searches a variety of directories for a file that
could be a manual page for the topic named.
If you specify the -M pathlist option, pathlist is a
colon-separated list of the directories that man searches.
If you don't specify -M but set the MANPATH environment
variable, the value of that variable is the list of the
directories that man searches.
If you don't specify an explicit path list with -M or MAN
PATH, man develops its own path list based on the contents
of the configuration file /etc/man.config. The MANPATH
statements in the configuration file identify particular
directories to include in the search path.
Furthermore, the MANPATH_MAP statements add to the search
path depending on your command search path (i.e. your PATH
environment variable). For each directory that may be in
the command search path, a MANPATH_MAP statement specifies
a directory that should be added to the search path for
adds the corresponding directories to the manual page file
search path. Thus, with the proper use of MANPATH_MAP,
when you issue the command man xyz, you get a manual page
for the program that would run if you issued the command
xyz.
In addition, for each directory in the command search path
(we'll call it a "command directory") for which you do not
have a MANPATH_MAP statement, man automatically looks for
a manual page directory "nearby" namely as a subdirectory
in the command directory itself or in the parent directory
of the command directory.
You can disable the automatic "nearby" searches by includ
ing a NOAUTOPATH statement in /etc/man.config.
In each directory in the search path as described above,
man searches for a file named topic.section, with an
optional suffix on the section number and possibly a com
pression suffix. If it doesn't find such a file, it then
looks in any subdirectories named manN or catN where N is
the manual section number. If the file is in a catN sub
directory, man assumes it is a formatted manual page file
(cat page). Otherwise, man assumes it is unformatted. In
either case, if the filename has a known compression suf
fix (like .gz), man assumes it is gzipped.
If you want to see where (or if) man would find the manual
page for a particular topic, use the --path (-w) option.
ENVIRONMENT
MANPATH
If MANPATH is set, man uses it as the path to
search for manual page files. It overrides the
configuration file and the automatic search path,
but is overridden by the -M invocation option. See
SEARCH PATH FOR MANUAL PAGES.
MANPL If MANPL is set, its value is used as the display
page length. Otherwise, the entire man page will
occupy one (long) page.
MANROFFSEQ
If MANROFFSEQ is set, its value is used to deter
mine the set of preprocessors run before running
nroff or troff. By default, pages are passed
through the tbl preprocessor before nroff.
MANSECT
If MANSECT is set, its value is used to determine
which manual sections to search.
If MANWIDTH is set, its value is used as the width
manpages should be displayed. Otherwise the pages
may be displayed over the whole width of your
screen.
MANPAGER
If MANPAGER is set, its value is used as the name
of the program to use to display the man page. If
not, then PAGER is used. If that has no value
either, /usr/bin/less -isr is used.
LANG If LANG is set, its value defines the name of the
subdirectory where man first looks for man pages.
Thus, the command `LANG=dk man 1 foo' will cause
man to look for the foo man page in
.../dk/man1/foo.1, and if it cannot find such a
file, then in .../man1/foo.1, where ... is a direc
tory on the search path.
NLSPATH, LC_MESSAGES, LANG
The environment variables NLSPATH and LC_MESSAGES
(or LANG when the latter does not exist) play a
role in locating the message catalog. (But the
English messages are compiled in, and for English
no catalog is required.) Note that programs like
col(1) called by man also use e.g. LC_CTYPE.
PATH PATH helps determine the search path for manual
page files. See SEARCH PATH FOR MANUAL PAGES.
SYSTEM SYSTEM is used to get the default alternate system
name (for use with the -m option).
SEE ALSO
apropos(1), whatis(1), less(1), groff(1), man.config(5).
BUGS
The -t option only works if a troff-like program is
installed.
If you see blinking \255 or <AD> instead of hyphens, put
`LESSCHARSET=latin1' in your environment.
TIPS
If you add the line
(global-set-key [(f1)] (lambda () (interactive) (manual-
entry (current-word))))
to your .emacs file, then hitting F1 will give you the man
page for the library call at the current cursor position.
To get a plain text version of a man page, without
backspaces and underscores, try
Man(1) output converted with
man2html