1man(1) User Commands man(1)
2
6 man - find and display reference manual pages
7
9 man [-] [-adFlrt] [-M path] [-T macro-package] [-s section] name...
10 man [-M path] -k keyword...
13 man [-M path] -f file...
16
19 The man command displays information from the reference manuals. It
20 displays complete manual pages that you select by name, or one-line
21 summaries selected either by keyword (-k), or by the name of an associ‐
22 ated file (-f). If no manual page is located, man prints an error mes‐
23 sage.
24 Source Format
26 Reference Manual pages are marked up with either nroff (see nroff(1))
27 or SGML (Standard Generalized Markup Language) tags (see sgml(5)). The
28 man command recognizes the type of markup and processes the file
29 accordingly. The various source files are kept in separate directories
30 depending on the type of markup.
31 Location of Manual Pages
33 The online Reference Manual page directories are conventionally located
34 in /usr/share/man. The nroff sources are located in the
35 /usr/share/man/man* directories. The SGML sources are located in the
36 /usr/share/man/sman* directories. Each directory corresponds to a sec‐
37 tion of the manual. Since these directories are optionally installed,
38 they might not reside on your host. You might have to mount
39 /usr/share/man from a host on which they do reside.
40 If there are preformatted, up-to-date versions in the corresponding
43 cat* or fmt* directories, man simply displays or prints those versions.
44 If the preformatted version of interest is out of date or missing, man
45 reformats it prior to display and stores the preformatted version if
46 cat* or fmt* is writable. The windex database is not updated. See cat‐
47 man(1M). If directories for the preformatted versions are not provided,
48 man reformats a page whenever it is requested. man uses a temporary
49 file to store the formatted text during display.
50 If the standard output is not a terminal, or if the `-' flag is given,
53 man pipes its output through cat(1). Otherwise, man pipes its output
54 through more(1) to handle paging and underlining on the screen.
55
57 The following options are supported:
58 -a Shows all manual pages matching name within the
60 MANPATH search path. Manual pages are displayed in
61 the order found.
62 -d Debugs. Displays what a section-specifier evaluates
65 to, method used for searching, and paths searched
66 by man.
67 -f file ... man attempts to locate manual pages related to any
70 of the given files. It strips the leading path name
71 components from each file, and then prints one-line
72 summaries containing the resulting basename or
73 names. This option also uses the windex database.
74 -F Forces man to search all directories specified by
77 MANPATH or the man.cf file, rather than using the
78 windex lookup database. This option is useful if
79 the database is not up to date and it has been made
80 the default behavior of the man command. The option
81 therefore does not have to be invoked and is docu‐
82 mented here for reference only.
83 -k keyword ... Prints out one-line summaries from the windex data‐
86 base (table of contents) that contain any of the
87 given keywords. The windex database is created
88 using catman(1M).
89 -l Lists all manual pages found matching name within
92 the search path.
93 -M path Specifies an alternate search path for manual
96 pages. path is a colon-separated list of directo‐
97 ries that contain manual page directory subtrees.
98 For example, if path is
99 /usr/share/man:/usr/local/man, man searches for
100 name in the standard location, and then
101 /usr/local/man. When used with the -k or -f
102 options, the -M option must appear first. Each
103 directory in the path is assumed to contain subdi‐
104 rectories of the form man* or sman* , one for each
105 section. This option overrides the MANPATH environ‐
106 ment variable.
107 -r Reformats the manual page, but does not display it.
110 This replaces the man - -t name combination.
111 -s section ... Specifies sections of the manual for man to search.
114 The directories searched for name are limited to
115 those specified by section. section can be a numer‐
116 ical digit, perhaps followed by one or more letters
117 to match the desired section of the manual, for
118 example, "3libucb". Also, section can be a word,
119 for example, local, new, old, public. section can
120 also be a letter. To specify multiple sections,
121 separate each section with a comma. This option
122 overrides the MANPATH environment variable and the
123 man.cf file. See Search Path below for an explana‐
124 tion of how man conducts its search.
125 -t man arranges for the specified manual pages to be
128 troffed to a suitable raster output device (see
129 troff(1)). If both the - and -t flags are given,
130 man updates the troffed versions of each named name
131 (if necessary), but does not display them.
132 -T macro-package Formats manual pages using macro-package rather
135 than the standard -man macros defined in
136 /usr/share/lib/tmac/an. See Search Path under USAGE
137 for a complete explanation of the default search
138 path order.
139
142 The following operand is supported:
143 name The name of a standard utility or a keyword.
145
148 The usage of man is described below:
149 Manual Page Sections
151 Entries in the reference manuals are organized into sections. A section
152 name consists of a major section name, typically a single digit,
153 optionally followed by a subsection name, typically one or more let‐
154 ters. An unadorned major section name, for example, "9", does not act
155 as an abbreviation for the subsections of that name, such as "9e",
156 "9f", or "9s". That is, each subsection must be searched separately by
157 man -s. Each section contains descriptions apropos to a particular ref‐
158 erence category, with subsections refining these distinctions. See the
159 intro manual pages for an explanation of the classification used in
160 this release.
161 Search Path
163 Before searching for a given name, man constructs a list of candidate
164 directories and sections. man searches for name in the directories
165 specified by the MANPATH environment variable.
166 In the absence of MANPATH, man constructs its search path based upon
169 the PATH environment variable, primarily by substituting man for the
170 last component of the PATH element. Special provisions are added to
171 account for unique characteristics of directories such as /sbin,
172 /usr/ucb, /usr/xpg4/bin, and others. If the file argument contains a /
173 character, the dirname portion of the argument is used in place of PATH
174 elements to construct the search path.
175 Within the manual page directories, man confines its search to the sec‐
178 tions specified in the following order:
179 o sections specified on the command line with the -s option
181 o sections embedded in the MANPATH environment variable
183 o sections specified in the man.cf file for each directory
185 specified in the MANPATH environment variable
186 If none of the above exist, man searches each directory in the manual
189 page path, and displays the first matching manual page found.
190 The man.cf file has the following format:
193 MANSECTS=section[,section]...
195 Lines beginning with `#' and blank lines are considered comments, and
200 are ignored. Each directory specified in MANPATH can contain a manual
201 page configuration file, specifying the default search order for that
202 directory.
203
205 Manual pages are marked up in nroff(1) or sgml(5). Nroff manual pages
206 are processed by nroff(1) or troff(1) with the -man macro package.
207 Please refer to man(5) for information on macro usage. SGML—tagged man‐
208 ual pages are processed by an SGML parser and passed to the formatter.
209 Preprocessing Nroff Manual Pages
211 When formatting an nroff manual page, man examines the first line to
212 determine whether it requires special processing. If the first line is
213 a string of the form:
214 '\" X
216 where X is separated from the `"' by a single SPACE and consists of any
221 combination of characters in the following list, man pipes its input to
222 troff(1) or nroff(1) through the corresponding preprocessors.
223 e eqn(1), or neqn for nroff
225 r refer(1)
228 t tbl(1)
231 v vgrind(1)
234 If eqn or neqn is invoked, it automatically reads the file
238 /usr/pub/eqnchar (see eqnchar(5)). If nroff(1) is invoked, col(1) is
239 automatically used.
240 Referring to Other nroff Manual Pages
242 If the first line of the nroff manual page is a reference to another
243 manual page entry fitting the pattern:
244 .so man*/sourcefile
246 man processes the indicated file in place of the current one. The ref‐
251 erence must be expressed as a path name relative to the root of the
252 manual page directory subtree.
253 When the second or any subsequent line starts with .so, man ignores it;
256 troff(1) or nroff(1) processes the request in the usual manner.
257 Processing SGML Manual Pages
259 Manual pages are identified as being marked up in SGML by the presence
260 of the string <!DOCTYPE. If the file also contains the string
261 SHADOW_PAGE, the file refers to another manual page for the content.
262 The reference is made with a file entity reference to the manual page
263 that contains the text. This is similar to the .so mechanism used in
264 the nroff formatted man pages.
265
267 See environ(5) for descriptions of the following environment variables
268 that affect the execution of man: LANG, LC_ALL, LC_CTYPE, LC_MESSAGES,
269 and NLSPATH.
270 MANPATH A colon-separated list of directories; each directory can be
272 followed by a comma-separated list of sections. If set, its
273 value overrides /usr/share/man as the default directory
274 search path, and the man.cf file as the default section
275 search path. The -M and -s flags, in turn, override these
276 values.)
277 PAGER A program to use for interactively delivering man's output
280 to the screen. If not set, `more -s' is used. See more(1).
281 TCAT The name of the program to use to display troffed manual
284 pages.
285 TROFF The name of the formatter to use when the -t flag is given.
288 If not set, troff(1) is used.
289
292 Example 1 Creating a PostScript Version of a man page
293 The following example creates the pipe(2) man page in postscript for
296 csh, tcsh, ksh and sh users:
297 % env TCAT=/usr/lib/lp/postscript/dpost man -t -s 2 pipe > pipe.ps
300 This is an alternative to using man -t, which sends the man page to the
305 default printer, if the user wants a postscript file version of the man
306 page.
307 Example 2 Creating a Text Version of a man page
310 The following example creates the pipe(2) man page in ascii text:
313 man pipe.2 | col -x -b > pipe.text
316 This is an alternative to using man -t, which sends the man page to the
321 default printer, if the user wants a text file version of the man page.
322
325 The following exit values are returned:
326 0 Successful completion.
328 >0 An error occurred.
331
334 /usr/share/man
335 Root of the standard manual page directory subtree
337 /usr/share/man/man?/*
340 Unformatted nroff manual entries
342 /usr/share/man/sman?/*
345 Unformatted SGML manual entries
347 /usr/share/man/cat?/*
350 nroffed manual entries
352 /usr/share/man/fmt?/*
355 troffed manual entries
357 /usr/share/man/windex
360 Table of contents and keyword database
362 /usr/share/lib/tmac/an
365 Standard -man macro package
367 /usr/share/lib/sgml/locale/C/dtd/*
370 SGML document type definition files
372 /usr/share/lib/sgml/locale/C/solbook/*
375 SGML style sheet and entity definitions directories
377 /usr/share/lib/pub/eqnchar
380 Standard definitions for eqn and neqn
382 man.cf
385 Default search order by section
387
390 See attributes(5) for descriptions of the following attributes:
391 ┌─────────────────────────────┬─────────────────────────────┐
396 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
397 ├─────────────────────────────┼─────────────────────────────┤
398 │Availability │SUNWdoc │
399 ├─────────────────────────────┼─────────────────────────────┤
400 │CSI │Enabled, see NOTES. │
401 ├─────────────────────────────┼─────────────────────────────┤
402 │Interface Stability │Committed │
403 ├─────────────────────────────┼─────────────────────────────┤
404 │Standard │See standards(5). │
405 └─────────────────────────────┴─────────────────────────────┘
406
408 apropos(1), cat(1), col(1), dpost(1), eqn(1), more(1), nroff(1),
409 refer(1), tbl(1), troff(1), vgrind(1), whatis(1), catman(1M),
410 attributes(5), environ(5), eqnchar(5), man(5), sgml(5), standards(5)
411
413 The -f and -k options use the windex database, which is created by cat‐
414 man(1M).
415 The man command is CSI-capable. However, some utilities invoked by the
418 man command, namely, troff, eqn, neqn, refer, tbl, and vgrind, are not
419 verified to be CSI-capable. Because of this, the man command with the
420 -t option can not handle non-EUC data. Also, using the man command to
421 display man pages that require special processing through eqn, neqn,
422 refer, tbl, or vgrind can not be CSI-capable.
423
425 The manual is supposed to be reproducible either on a phototypesetter
426 or on an ASCII terminal. However, on a terminal some information (indi‐
427 cated by font changes, for instance) is lost.
428 Some dumb terminals cannot process the vertical motions produced by the
431 e (see eqn(1)) preprocessing flag. To prevent garbled output on these
432 terminals, when you use e, also use t, to invoke col(1) implicitly.
433 This workaround has the disadvantage of eliminating superscripts and
434 subscripts, even on those terminals that can display them. Control-q
435 clears a terminal that gets confused by eqn(1) output.
436SunOS 5.11 8 May 2008 man(1)