1man(1) General Commands Manual man(1)
2
6 man - format and display the on-line manual pages
7
9 man [-acdfFhkKtwW] [--path] [-m system] [-p string] [-C config_file]
10 [-M pathlist] [-P pager] [-B browser] [-H htmlpager] [-S section_list]
11 [section] name ...
12
15 man formats and displays the on-line manual pages. If you specify sec‐
16 tion, man only looks in that section of the manual. name is normally
17 the name of the manual page, which is typically the name of a command,
18 function, or file. However, if name contains a slash (/) then man
19 interprets it as a file specification, so that you can do man ./foo.5
20 or even man /cd/foo/bar.1.gz.
21 See below for a description of where man looks for the manual page
23 files.
24
27 -C config_file
28 Specify the configuration file to use; the default is
29 /etc/man.config. (See man.config(5).)
30 -M path
32 Specify the list of directories to search for man pages. Sepa‐
33 rate the directories with colons. An empty list is the same as
34 not specifying -M at all. See SEARCH PATH FOR MANUAL PAGES.
35 -P pager
37 Specify which pager to use. This option overrides the MANPAGER
38 environment variable, which in turn overrides the PAGER vari‐
39 able. By default, man uses /usr/bin/less -is.
40 -B Specify which browser to use on HTML files. This option over‐
42 rides the BROWSER environment variable. By default, man uses
43 /usr/bin/less-is,
44 -H Specify a command that renders HTML files as text. This option
46 overrides the HTMLPAGER environment variable. By default, man
47 uses /bin/cat,
48 -S section_list
50 List is a colon separated list of manual sections to search.
51 This option overrides the MANSECT environment variable.
52 -a By default, man will exit after displaying the first manual page
54 it finds. Using this option forces man to display all the man‐
55 ual pages that match name, not just the first.
56 -c Reformat the source man page, even when an up-to-date cat page
58 exists. This can be meaningful if the cat page was formatted
59 for a screen with a different number of columns, or if the pre‐
60 formatted page is corrupted.
61 -d Don't actually display the man pages, but do print gobs of
63 debugging information.
64 -D Both display and print debugging info.
66 -f Equivalent to whatis.
68 -F or --preformat
70 Format only - do not display.
71 -h Print a help message and exit.
73 -k Equivalent to apropos.
75 -K Search for the specified string in *all* man pages. Warning:
77 this is probably very slow! It helps to specify a section.
78 (Just to give a rough idea, on my machine this takes about a
79 minute per 500 man pages.)
80 -m system
82 Specify an alternate set of man pages to search based on the
83 system name given.
84 -p string
86 Specify the sequence of preprocessors to run before nroff or
87 troff. Not all installations will have a full set of preproces‐
88 sors. Some of the preprocessors and the letters used to desig‐
89 nate them are: eqn (e), grap (g), pic (p), tbl (t), vgrind (v),
90 refer (r). This option overrides the MANROFFSEQ environment
91 variable.
92 -t Use /usr/bin/groff -Tps -mandoc to format the manual page, pass‐
94 ing the output to stdout. The default output format of
95 /usr/bin/groff -Tps -mandoc is Postscript, refer to the manual
96 page of /usr/bin/groff -Tps -mandoc for ways to pick an alter‐
97 nate format.
98 Depending on the selected format and the availability of printing
100 devices, the output may need to be passed through some filter or
101 another before being printed.
102 -w or --path
104 Don't actually display the man pages, but do print the loca‐
105 tion(s) of the files that would be formatted or displayed. If no
106 argument is given: display (on stdout) the list of directories
107 that is searched by man for man pages. If manpath is a link to
108 man, then "manpath" is equivalent to "man --path".
109 -W Like -w, but print file names one per line, without additional
111 information. This is useful in shell commands like man -aW man
112 | xargs ls -l
113
116 Man will try to save the formatted man pages, in order to save format‐
117 ting time the next time these pages are needed. Traditionally, format‐
118 ted versions of pages in DIR/manX are saved in DIR/catX, but other map‐
119 pings from man dir to cat dir can be specified in /etc/man.config. No
120 cat pages are saved when the required cat directory does not exist. No
121 cat pages are saved when they are formatted for a line length different
122 from 80. No cat pages are saved when man.config contains the line
123 NOCACHE.
124 It is possible to make man suid to a user man. Then, if a cat directory
126 has owner man and mode 0755 (only writable by man), and the cat files
127 have owner man and mode 0644 or 0444 (only writable by man, or not
128 writable at all), no ordinary user can change the cat pages or put
129 other files in the cat directory. If man is not made suid, then a cat
130 directory should have mode 0777 if all users should be able to leave
131 cat pages there.
132 The option -c forces reformatting a page, even if a recent cat page
134 exists.
135
138 Man will find HTML pages if they live in directories named as expected
139 to be ".html", thus a valid name for an HTML version of the ls(1) man
140 page would be /usr/share/man/htmlman1/ls.1.html.
141
144 man uses a sophisticated method of finding manual page files, based on
145 the invocation options and environment variables, the /etc/man.config
146 configuration file, and some built in conventions and heuristics.
147 First of all, when the name argument to man contains a slash (/), man
149 assumes it is a file specification itself, and there is no searching
150 involved.
151 But in the normal case where name doesn't contain a slash, man searches
153 a variety of directories for a file that could be a manual page for the
154 topic named.
155 If you specify the -M pathlist option, pathlist is a colon-separated
157 list of the directories that man searches.
158 If you don't specify -M but set the MANPATH environment variable, the
160 value of that variable is the list of the directories that man
161 searches.
162 If you don't specify an explicit path list with -M or MANPATH, man
164 develops its own path list based on the contents of the configuration
165 file /etc/man.config. The MANPATH statements in the configuration file
166 identify particular directories to include in the search path.
167 Furthermore, the MANPATH_MAP statements add to the search path depend‐
169 ing on your command search path (i.e. your PATH environment variable).
170 For each directory that may be in the command search path, a MAN‐
171 PATH_MAP statement specifies a directory that should be added to the
172 search path for manual page files. man looks at the PATH variable and
173 adds the corresponding directories to the manual page file search path.
174 Thus, with the proper use of MANPATH_MAP, when you issue the command
175 man xyz, you get a manual page for the program that would run if you
176 issued the command xyz.
177 In addition, for each directory in the command search path (we'll call
179 it a "command directory") for which you do not have a MANPATH_MAP
180 statement, man automatically looks for a manual page directory "nearby"
181 namely as a subdirectory in the command directory itself or in the par‐
182 ent directory of the command directory.
183 You can disable the automatic "nearby" searches by including a NOAU‐
185 TOPATH statement in /etc/man.config.
186 In each directory in the search path as described above, man searches
188 for a file named topic.section, with an optional suffix on the section
189 number and possibly a compression suffix. If it doesn't find such a
190 file, it then looks in any subdirectories named manN or catN where N is
191 the manual section number. If the file is in a catN subdirectory, man
192 assumes it is a formatted manual page file (cat page). Otherwise, man
193 assumes it is unformatted. In either case, if the filename has a known
194 compression suffix (like .gz), man assumes it is gzipped.
195 If you want to see where (or if) man would find the manual page for a
197 particular topic, use the --path (-w) option.
198
201 MANPATH
202 If MANPATH is set, man uses it as the path to search for manual
203 page files. It overrides the configuration file and the auto‐
204 matic search path, but is overridden by the -M invocation
205 option. See SEARCH PATH FOR MANUAL PAGES.
206 MANPL If MANPL is set, its value is used as the display page length.
208 Otherwise, the entire man page will occupy one (long) page.
209 MANROFFSEQ
211 If MANROFFSEQ is set, its value is used to determine the set of
212 preprocessors run before running nroff or troff. By default,
213 pages are passed through the tbl preprocessor before nroff.
214 MANSECT
216 If MANSECT is set, its value is used to determine which manual
217 sections to search.
218 MANWIDTH
220 If MANWIDTH is set, its value is used as the width manpages
221 should be displayed. Otherwise the pages may be displayed over
222 the whole width of your screen.
223 MANPAGER
225 If MANPAGER is set, its value is used as the name of the program
226 to use to display the man page. If not, then PAGER is used. If
227 that has no value either, /usr/bin/less -is is used.
228 BROWSER
230 The name of a browser to use for displaying HTML manual pages.
231 If it is not set, /usr/bin/less -is is used.
232 HTMLPAGER
234 The command to use for rendering HTML manual pages as text. If
235 it is not set, /bin/cat is used.
236 LANG If LANG is set, its value defines the name of the subdirectory
238 where man first looks for man pages. Thus, the command `LANG=dk
239 man 1 foo' will cause man to look for the foo man page in
240 .../dk/man1/foo.1, and if it cannot find such a file, then in
241 .../man1/foo.1, where ... is a directory on the search path.
242 NLSPATH, LC_MESSAGES, LANG
244 The environment variables NLSPATH and LC_MESSAGES (or LANG when
245 the latter does not exist) play a role in locating the message
246 catalog. (But the English messages are compiled in, and for
247 English no catalog is required.) Note that programs like col(1)
248 called by man also use e.g. LC_CTYPE.
249 PATH PATH helps determine the search path for manual page files. See
251 SEARCH PATH FOR MANUAL PAGES.
252 SYSTEM SYSTEM is used to get the default alternate system name (for use
254 with the -m option).
255
257 The -t option only works if a troff-like program is installed.
258 If you see blinking \255 or <AD> instead of hyphens, put `LESS‐
259 CHARSET=latin1' in your environment.
260
262 If you add the line
263 (global-set-key [(f1)] (lambda () (interactive) (manual-entry (cur‐
265 rent-word))))
266 to your .emacs file, then hitting F1 will give you the man page for the
268 library call at the current cursor position.
269 To get a plain text version of a man page, without backspaces and
271 underscores, try
272 # man foo | col -b > foo.mantxt
274
276 John W. Eaton was the original author of man. Zeyd M. Ben-Halim
277 released man 1.2, and Andries Brouwer followed up with versions 1.3
278 thru 1.5p. Federico Lucifredi <flucifredi@acm.org> is the current
279 maintainer.
280
282 apropos(1), whatis(1), less(1), groff(1), man.config(5).
283 September 19, 2005 man(1)