1man(1)                           User Commands                          man(1)
2
3
4

NAME

6       man - find and display reference manual pages
7

SYNOPSIS

9       man [-] [-adFlrt] [-M path] [-T macro-package] [-s section] name...
10
11
12       man [-M path] -k keyword...
13
14
15       man [-M path] -f file...
16
17

DESCRIPTION

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
25   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
32   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
41
42       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
51
52       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

OPTIONS

57       The following options are supported:
58
59       -a                  Shows all manual pages  matching  name  within  the
60                           MANPATH  search path. Manual pages are displayed in
61                           the order found.
62
63
64       -d                  Debugs. Displays what a section-specifier evaluates
65                           to,  method  used for searching, and paths searched
66                           by man.
67
68
69       -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
75
76       -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
84
85       -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
90
91       -l                  Lists  all  manual pages found matching name within
92                           the search path.
93
94
95       -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
108
109       -r                  Reformats the manual page, but does not display it.
110                           This replaces the man - -t name combination.
111
112
113       -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
126
127       -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
133
134       -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
140

OPERANDS

142       The following operand is supported:
143
144       name    The name of a standard utility or a keyword.
145
146

USAGE

148       The usage of man is described below:
149
150   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
162   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
167
168       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
176
177       Within the manual page directories, man confines its search to the sec‐
178       tions specified in the following order:
179
180           o      sections specified on the command line with the -s option
181
182           o      sections embedded in the MANPATH environment variable
183
184           o      sections  specified  in  the  man.cf file for each directory
185                  specified in the MANPATH environment variable
186
187
188       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
191
192       The man.cf file has the following format:
193
194         MANSECTS=section[,section]...
195
196
197
198
199       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

FORMATTING MANUAL PAGES

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
210   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
215         '\" X
216
217
218
219
220       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
224       e    eqn(1), or neqn for nroff
225
226
227       r    refer(1)
228
229
230       t    tbl(1)
231
232
233       v    vgrind(1)
234
235
236
237       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
241   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
245         .so man*/sourcefile
246
247
248
249
250       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
254
255       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
258   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

ENVIRONMENT VARIABLES

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
271       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
278
279       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
282
283       TCAT       The name of the program to use  to  display  troffed  manual
284                  pages.
285
286
287       TROFF      The  name of the formatter to use when the -t flag is given.
288                  If not set, troff(1) is used.
289
290

EXAMPLES

292       Example 1 Creating a PostScript Version of a man page
293
294
295       The following example creates the pipe(2) man page  in  postscript  for
296       csh, tcsh, ksh and sh users:
297
298
299              % env TCAT=/usr/lib/lp/postscript/dpost man -t -s 2 pipe > pipe.ps
300
301
302
303
304       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
308
309       Example 2 Creating a Text Version of a man page
310
311
312       The following example creates the pipe(2) man page in ascii text:
313
314
315         man pipe.2 | col -x -b > pipe.text
316
317
318
319
320       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
323

EXIT STATUS

325       The following exit values are returned:
326
327       0     Successful completion.
328
329
330       >0    An error occurred.
331
332

FILES

334       /usr/share/man
335
336           Root of the standard manual page directory subtree
337
338
339       /usr/share/man/man?/*
340
341           Unformatted nroff manual entries
342
343
344       /usr/share/man/sman?/*
345
346           Unformatted SGML manual entries
347
348
349       /usr/share/man/cat?/*
350
351           nroffed manual entries
352
353
354       /usr/share/man/fmt?/*
355
356           troffed manual entries
357
358
359       /usr/share/man/windex
360
361           Table of contents and keyword database
362
363
364       /usr/share/lib/tmac/an
365
366           Standard -man macro package
367
368
369       /usr/share/lib/sgml/locale/C/dtd/*
370
371           SGML document type definition files
372
373
374       /usr/share/lib/sgml/locale/C/solbook/*
375
376           SGML style sheet and entity definitions directories
377
378
379       /usr/share/lib/pub/eqnchar
380
381           Standard definitions for eqn and neqn
382
383
384       man.cf
385
386           Default search order by section
387
388

ATTRIBUTES

390       See attributes(5) for descriptions of the following attributes:
391
392
393
394
395       ┌─────────────────────────────┬─────────────────────────────┐
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

SEE ALSO

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

NOTES

413       The -f and -k options use the windex database, which is created by cat‐
414       man(1M).
415
416
417       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

BUGS

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
429
430       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.
436
437
438
439SunOS 5.11                        8 May 2008                            man(1)
Impressum