User Commands man(1)
NAME
man - find and display reference manual pages
SYNOPSIS
man [-] [-adFlrt] [-M path] [-T macro-package] [-s section] name...
man [-M path] -k keyword...
man [-M path] -f file...
DESCRIPTION
The man command displays information from the reference
manuals. It displays complete manual pages that you select
by name, or one-line summaries selected either by keyword
(-k), or by the name of an associated file (-f). If no
manual page is located, man prints an error message.
Source Format Reference Manual pages are marked up with either nroff (see nroff(1)) or SGML (Standard Generalized Markup Language)tags (see sgml(5)). The man command recognizes the type of
markup and processes the file accordingly. The various source files are kept in separate directories depending on the type of markup. Location of Manual PagesThe online Reference Manual page directories are convention-
ally located in /usr/share/man. The nroff sources are
located in the /usr/share/man/man* directories. The SGML
sources are located in the /usr/share/man/sman* directories.
Each directory corresponds to a section of the manual. Since
these directories are optionally installed, they might notreside on your host. You might have to mount /usr/share/man
from a host on which they do reside.If there are preformatted, up-to-date versions in the
corresponding cat* or fmt* directories, man simply displays
or prints those versions. If the preformatted version ofinterest is out of date or missing, man reformats it prior
to display and stores the preformatted version if cat* or fmt* is writable. The windex database is not updated. Seecatman(1M). If directories for the preformatted versions are
not provided, man reformats a page whenever it is requested.
man uses a temporary file to store the formatted text during
display.SunOS 5.11 Last change: 29 Apr 2010 1
User Commands man(1)
If the standard output is not a terminal, or if the `-' flag
is given, man pipes its output through cat(1). Otherwise,
man pipes its output through more(1) to handle paging and
underlining on the screen. OPTIONS The following options are supported:-a Shows all manual pages matching name
within the MANPATH search path. Manual pages are displayed in the order found.-d Debugs. Displays what a section-
specifier evaluates to, method used forsearching, and paths searched by man.
-f file ... man attempts to locate manual pages
related to any of the given files. It strips the leading path name componentsfrom each file, and then prints one-line
summaries containing the resulting basename or names. This option also uses the windex database.-F Forces man to search all directories
specified by MANPATH or the man.cf file,
rather than using the windex lookup database. This option is useful if the database is not up to date and it has been made the default behavior of theman command. The option therefore does
not have to be invoked and is documented here for reference only.-k keyword ... Prints out one-line summaries from the
windex database (table of contents) that contain any of the given keywords. The windex database is created usingcatman(1M).
-l Lists all manual pages found matching
name within the search path.-M path Specifies an alternate search path for
manual pages. path is a colon-separated
list of directories that contain manual
SunOS 5.11 Last change: 29 Apr 2010 2
User Commands man(1)
page directory subtrees. For example, ifpath is /usr/share/man:/usr/local/man,
man searches for name in the standard
location, and then /usr/local/man. When
used with the -k or -f options, the -M
option must appear first. Each directoryin the path is assumed to contain sub-
directories of the form man* or sman* ,
one for each section. This option over-
rides the MANPATH environment variable.-r Reformats the manual page, but does not
display it. This replaces the man - -t
name combination.-s section ... Specifies sections of the manual for man
to search. The directories searched for name are limited to those specified by section. section can be a numerical digit, perhaps followed by one or more letters to match the desired section ofthe manual, for example, "3lib". Also,
section can be a word, for example, local, new, old, public. section can also be a letter. To specify multiple sections, separate each section with a comma. This option overrides the MANPATHenvironment variable and the man.cf
file. See Search Path below for anexplanation of how man conducts its
search.-t man arranges for the specified manual
pages to be troffed to a suitable raster output device (see troff(1)). If boththe - and -t flags are given, man
updates the troffed versions of each named name (if necessary), but does not display them.-T macro-package Formats manual pages using macro-package
rather than the standard -man macros
defined in /usr/share/lib/tmac/an. SeeSearch Path under USAGE for a complete
explanation of the default search path order.SunOS 5.11 Last change: 29 Apr 2010 3
User Commands man(1)
OPERANDS The following operand is supported: name The name of a standard utility or a keyword.USAGE
The usage of man is described below:
Manual Page SectionsEntries in the reference manuals are organized into sec-
tions. A section name consists of a major section name, typ-
ically a single digit, optionally followed by a subsectionname, typically one or more letters. An unadorned major sec-
tion name, for example, "9", does not act as an abbreviation for the subsections of that name, such as "9e", "9f", or "9s". That is, each subsection must be searched separatelyby man -s. Each section contains descriptions apropos to a
particular reference category, with subsections refiningthese distinctions. See the intro manual pages for an expla-
nation of the classification used in this release.The following contains a brief description of each man page
section and the information it references:o Section 1 describes, in alphabetical order, com-
mands available with the operating system.
o Section 1M describes, in alphabetical order, com-
mands that are used chiefly for system maintenance
and administration purposes. o Section 2 describes all of the system calls. Most of these calls have one or more error returns. Anerror condition is indicated by an otherwise impos-
sible returned value. o Section 3 describes functions found in various libraries, other than those functions that directly invoke UNIX system primitives, which are described in Section 2. o Section 4 outlines the formats of various files. The C structure declarations for the file formats are given where applicable. o Section 5 contains miscellaneous documentation suchas character-set tables.
o Section 7 describes various special files that refer to specifichardware peripherals and deviceSunOS 5.11 Last change: 29 Apr 2010 4
User Commands man(1)
drivers. STREAMS software drivers, modules and theSTREAMS-generic set of system calls are also
described. o Section 9E describes the DDI (Device DriverInterface)/DKI (Driver/Kernel Interface), DDI-only,
and DKI-only entry-point routines a developer can
include in a device driver. o Section 9F describes the kernel functions available for use by device drivers. o Section 9S describes the data structures used by drivers to share information between the driver and the kernel. Search PathBefore searching for a given name, man constructs a list of
candidate directories and sections. man searches for name in
the directories specified by the MANPATH environment vari-
able.In the absence of MANPATH, man constructs its search path
based upon the PATH environment variable, primarily by sub-
stituting man for the last component of the PATH element.
Special provisions are added to account for unique charac-
teristics of directories such as /sbin, /usr/ucb, /usr/xpg4/bin, and others. If the file argument contains a / character, the dirname portion of the argument is used in place of PATH elements to construct the search path.Within the manual page directories, man confines its search
to the sections specified in the following order:o sections specified on the command line with the -s
optiono sections embedded in the MANPATH environment vari-
ableo sections specified in the man.cf file for each
directory specified in the MANPATH environment variableIf none of the above exist, man searches each directory in
the manual page path, and displays the first matching manual
page found.SunOS 5.11 Last change: 29 Apr 2010 5
User Commands man(1)
The man.cf file has the following format:
MANSECTS=section[,section]...Lines beginning with `#' and blank lines are considered com-
ments, and are ignored. Each directory specified in MANPATHcan contain a manual page configuration file, specifying the
default search order for that directory. FORMATTING MANUAL PAGES Manual pages are marked up in nroff(1) or sgml(5). Nroffmanual pages are processed by nroff(1) or troff(1) with the
-man macro package. Please refer to man(5) for information
on macro usage. SGML-tagged manual pages are processed by an
SGML parser and passed to the formatter. Preprocessing Nroff Manual PagesWhen formatting an nroff manual page, man examines the first
line to determine whether it requires special processing. If the first line is a string of the form: '\" Xwhere X is separated from the `"' by a single SPACE and con-
sists of any combination of characters in the followinglist, man pipes its input to troff(1) or nroff(1) through
the corresponding preprocessors. e eqn(1), or neqn for nroff r refer(1) t tbl(1) v vgrind(1) If eqn or neqn is invoked, it automatically reads the file /usr/pub/eqnchar (see eqnchar(5)). If nroff(1) is invoked, col(1) is automatically used.SunOS 5.11 Last change: 29 Apr 2010 6
User Commands man(1)
Referring to Other nroff Manual PagesIf the first line of the nroff manual page is a reference to
another manual page entry fitting the pattern:
.so man*/sourcefile
man processes the indicated file in place of the current
one. The reference must be expressed as a path name relativeto the root of the manual page directory subtree.
When the second or any subsequent line starts with .so, man
ignores it; troff(1) or nroff(1) processes the request inthe usual manner.
Processing SGML Manual Pages Manual pages are identified as being marked up in SGML bythe presence of the string
tains the string SHADOW_PAGE, the file refers to another
manual page for the content. The reference is made with a
file entity reference to the manual page that contains the
text. This is similar to the .so mechanism used in the nroffformatted man pages.
ENVIRONMENT VARIABLES See environ(5) for descriptions of the following environmentvariables that affect the execution of man: LANG, LC_ALL,
LC_CTYPE, LC_MESSAGES, and NLSPATH.
MANPATH A colon-separated list of directories; each
directory can be followed by a comma-separated
list of sections. If set, its value overrides/usr/share/man as the default directory search
path, and the man.cf file as the default section
search path. The -M and -s flags, in turn, over-
ride these values.) PAGER A program to use for interactively deliveringman's output to the screen. If not set, `more -s'
is used. See more(1). TCAT The name of the program to use to display troffedmanual pages.
TROFF The name of the formatter to use when the -t flag
is given. If not set, troff(1) is used.SunOS 5.11 Last change: 29 Apr 2010 7
User Commands man(1)
EXAMPLES
Example 1 Creating a PostScript Version of a man page
The following example creates the pipe(2) man page in
postscript for csh, tcsh, ksh and sh users:% env TCAT=/usr/lib/lp/postscript/dpost man -t -s 2 pipe > pipe.ps
This is an alternative to using man -t, which sends the man
page to the default printer, if the user wants a postscriptfile version of the man page.
Example 2 Creating a Text Version of a man page
The following example creates the pipe(2) man page in ascii
text:man pipe.2 | col -x -b > pipe.text
This is an alternative to using man -t, which sends the man
page to the default printer, if the user wants a text fileversion of the man page.
EXIT STATUS The following exit values are returned: 0 Successful completion. >0 An error occurred. FILES/usr/share/man
Root of the standard manual page directory subtree
/usr/share/man/man?/*
SunOS 5.11 Last change: 29 Apr 2010 8
User Commands man(1)
Unformatted nroff manual entries
/usr/share/man/sman?/*
Unformatted SGML manual entries
/usr/share/man/cat?/*
nroffed manual entries
/usr/share/man/fmt?/*
troffed manual entries
/usr/share/man/windex
Table of contents and keyword database /usr/share/lib/tmac/anStandard -man macro package
/usr/share/lib/sgml/locale/C/dtd/* SGML document type definition files
/usr/share/lib/sgml/locale/C/solbook/* SGML style sheet and entity definitions directories /usr/share/lib/pub/eqnchar Standard definitions for eqn and neqn
man.cf
Default search order by sectionATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:SunOS 5.11 Last change: 29 Apr 2010 9
User Commands man(1)
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | text/doctools ||_____________________________|_____________________________|
| CSI | Enabled, see NOTES. ||_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
| Standard | See standards(5). ||_____________________________|_____________________________|
SEE ALSO
apropos(1), cat(1), col(1), dpost(1), eqn(1), more(1), nroff(1), refer(1), tbl(1), troff(1), vgrind(1), whatis(1),catman(1M), attributes(5), environ(5), eqnchar(5), man(5),
sgml(5), standards(5) NOTESThe -f and -k options use the windex database, which is
created by catman(1M).
The man command is CSI-capable. However, some utilities
invoked by the man command, namely, troff, eqn, neqn, refer,
tbl, and vgrind, are not verified to be CSI-capable. Because
of this, the man command with the -t option can not handle
non-EUC data. Also, using the man command to display man
pages that require special processing through eqn, neqn,refer, tbl, or vgrind can not be CSI-capable.
BUGS
The manual is supposed to be reproducible either on a photo-
typesetter or on an ASCII terminal. However, on a terminal some information (indicated by font changes, for instance) is lost.Some dumb terminals cannot process the vertical motions pro-
duced by the e (see eqn(1)) preprocessing flag. To prevent garbled output on these terminals, when you use e, also use t, to invoke col(1) implicitly. This workaround has the disadvantage of eliminating superscripts and subscripts,even on those terminals that can display them. Control-q
clears a terminal that gets confused by eqn(1) output.SunOS 5.11 Last change: 29 Apr 2010 10