path: root/usr/src/man/man1/man.1

'\" te
.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright (c) 1980 Regents of the University of California. The Berkeley software License Agreement specifies the terms and conditions for redistribution.
.TH man 1 "8 May 2008" "SunOS 5.11" "User Commands"
.SH NAME
man \- find and display reference manual pages
.SH SYNOPSIS
.LP
.nf
\fBman\fR [\fB-\fR] [\fB-adFlrt\fR] [\fB-M\fR \fIpath\fR] [\fB-T\fR \fImacro-package\fR] [\fB-s\fR \fIsection\fR] \fIname\fR...
.fi

.LP
.nf
\fBman\fR [\fB-M\fR \fIpath\fR] \fB-k\fR \fIkeyword\fR...
.fi

.LP
.nf
\fBman\fR [\fB-M\fR \fIpath\fR] \fB-f\fR \fIfile\fR...
.fi

.SH DESCRIPTION
.sp
.LP
The \fBman\fR command displays information from the reference manuals. It
displays complete manual pages that you select by \fIname\fR, or one-line
summaries selected either by \fIkeyword\fR (\fB-k\fR), or by the name of an
associated file (\fB-f\fR). If no manual page is located, \fBman\fR prints an
error message.
.SS "Source Format"
.sp
.LP
Reference Manual pages are marked up with either \fBnroff\fR (see
\fBnroff\fR(1)) or \fBSGML\fR (Standard Generalized Markup Language) tags (see
\fBsgml\fR(5)). The \fBman\fR 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.
.SS "Location of Manual Pages"
.sp
.LP
The online Reference Manual page directories are conventionally located in
\fB/usr/share/man\fR. The nroff sources are located in the
\fB/usr/share/man/man\fR* directories. The \fBSGML\fR sources are located in
the \fB/usr/share/man/sman\fR* directories. Each directory corresponds to a
section of the manual. Since these directories are optionally installed, they
might not reside on your host. You might have to mount \fB/usr/share/man\fR
from a host on which they do reside.
.sp
.LP
If there are preformatted, up-to-date versions in the corresponding \fBcat\fR*
or \fBfmt\fR* directories, \fBman\fR simply displays or prints those versions.
If the preformatted version of interest is out of date or missing, \fBman\fR
reformats it prior to display and stores the preformatted version if \fBcat\fR*
or \fBfmt\fR* is writable. The \fBwindex\fR database is not updated. See
\fBcatman\fR(1M). If directories for the preformatted versions are not
provided, \fBman\fR reformats a page whenever it is requested. \fBman\fR uses a
temporary file to store the formatted text during display.
.sp
.LP
If the standard output is not a terminal, or if the `\fB-\fR' flag is given,
\fBman\fR pipes its output through \fBcat\fR(1). Otherwise, \fBman\fR pipes its
output through \fBmore\fR(1) to handle paging and underlining on the screen.
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.mk
.na
\fB\fB-a\fR\fR
.ad
.RS 20n
.rt  
Shows all manual pages matching \fIname\fR within the \fBMANPATH\fR search
path. Manual pages are displayed in the order found.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-d\fR\fR
.ad
.RS 20n
.rt  
Debugs. Displays what a section-specifier evaluates to, method used for
searching, and paths searched by \fBman\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-f\fR \fIfile ...\fR\fR
.ad
.RS 20n
.rt  
\fBman\fR attempts to locate manual pages related to any of the given
\fIfile\fRs. It strips the leading path name components from each \fIfile\fR,
and then prints one-line summaries containing the resulting basename or names.
This option also uses the \fBwindex\fR database.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-F\fR\fR
.ad
.RS 20n
.rt  
Forces \fBman\fR to search all directories specified by \fBMANPATH\fR or the
\fBman.cf\fR file, rather than using the \fBwindex\fR lookup database. This
option is useful if the database is not up to date and it has been made the
default behavior of the \fBman\fR command. The option therefore does not have
to be invoked and is documented here for reference only.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-k\fR \fIkeyword ...\fR\fR
.ad
.RS 20n
.rt  
Prints out one-line summaries from the \fBwindex\fR database (table of
contents) that contain any of the given \fIkeyword\fRs. The \fBwindex\fR
database is created using \fBcatman\fR(1M).
.RE

.sp
.ne 2
.mk
.na
\fB\fB-l\fR\fR
.ad
.RS 20n
.rt  
Lists all manual pages found matching \fIname\fR within the search path.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-M\fR \fIpath\fR\fR
.ad
.RS 20n
.rt  
Specifies an alternate search path for manual pages. \fIpath\fR is a
colon-separated list of directories that contain manual page directory
subtrees. For example, if \fIpath\fR is \fB/usr/share/man:/usr/local/man\fR,
\fBman\fR searches for \fIname\fR in the standard location, and then
\fB/usr/local/man\fR. When used with the \fB-k\fR or \fB-f\fR options, the
\fB-M\fR option must appear first. Each directory in the \fIpath\fR is assumed
to contain subdirectories of the form \fBman\fR* or \fBsman\fR* , one for each
section. This option overrides the \fBMANPATH\fR environment variable.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-r\fR\fR
.ad
.RS 20n
.rt  
Reformats the manual page, but does not display it. This replaces the \fBman\fR
\fB-\fR \fB-t\fR \fIname\fR combination.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-s\fR \fIsection ...\fR\fR
.ad
.RS 20n
.rt  
Specifies sections of the manual for \fBman\fR to search. The directories
searched for \fIname\fR are limited to those specified by \fIsection\fR.
\fIsection\fR can be a numerical digit, perhaps followed by one or more letters
to match the desired section of the manual, for example, "\fB3libucb\fR". Also,
\fIsection\fR can be a word, for example, \fBlocal\fR, \fBnew\fR, \fBold\fR,
\fBpublic\fR. \fIsection\fR can also be a letter. To specify multiple sections,
separate each section with a comma. This option overrides the \fBMANPATH\fR
environment variable and the \fBman.cf\fR file. See \fBSearch\fR \fBPath\fR
below for an explanation of how \fBman\fR conducts its search.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-t\fR\fR
.ad
.RS 20n
.rt  
\fBman\fR arranges for the specified manual pages to be \fBtroff\fRed to a
suitable raster output device (see \fBtroff\fR(1)). If both the \fB-\fR and
\fB-t\fR flags are given, \fBman\fR updates the \fBtroff\fRed versions of each
named \fIname\fR (if necessary), but does not display them.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-T\fR \fImacro-package\fR\fR
.ad
.RS 20n
.rt  
Formats manual pages using \fImacro-package\fR rather than the standard
\fB-man\fR macros defined in \fB/usr/share/lib/tmac/an\fR. See \fBSearch
Path\fR under USAGE for a complete explanation of the default search path
order.
.RE

.SH OPERANDS
.sp
.LP
The following operand is supported:
.sp
.ne 2
.mk
.na
\fB\fIname\fR\fR
.ad
.RS 8n
.rt  
The name of a standard utility or a keyword.
.RE

.SH USAGE
.sp
.LP
The usage of \fBman\fR is described below:
.SS "Manual Page Sections"
.sp
.LP
Entries in the reference manuals are organized into \fIsection\fRs. A section
name consists of a major section name, typically a single digit, optionally
followed by a subsection name, typically one or more letters. An unadorned
major section name, for example, "\fB9\fR", does not act as an abbreviation for
the subsections of that name, such as "\fB9e\fR", "\fB9f\fR", or "\fB9s\fR".
That is, each subsection must be searched separately by \fBman\fR \fB-s\fR.
Each section contains descriptions apropos to a particular reference category,
with subsections refining these distinctions. See the \fBintro\fR manual pages
for an explanation of the classification used in this release.
.SS "Search Path"
.sp
.LP
Before searching for a given \fIname\fR, \fBman\fR constructs a list of
candidate directories and sections. \fBman\fR searches for \fIname\fR in the
directories specified by the \fBMANPATH\fR environment variable.
.sp
.LP
In the absence of \fBMANPATH\fR, \fBman\fR constructs its search path based
upon the \fBPATH\fR environment variable, primarily by substituting \fBman\fR
for the last component of the \fBPATH\fR element. Special provisions are added
to account for unique characteristics of directories such as \fB/sbin\fR,
\fB/usr/ucb\fR, \fB/usr/xpg4/bin\fR, and others. If the file argument contains
a \fB/\fR character, the \fIdirname\fR portion of the argument is used in place
of \fBPATH\fR elements to construct the search path.
.sp
.LP
Within the manual page directories, \fBman\fR confines its search to the
sections specified in the following order:
.RS +4
.TP
.ie t \(bu
.el o
\fIsection\fRs specified on the command line with the \fB-s\fR option
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fIsection\fRs embedded in the \fBMANPATH\fR environment variable
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fIsection\fRs specified in the \fBman.cf\fR file for each directory specified
in the \fBMANPATH\fR environment variable
.RE
.sp
.LP
If none of the above exist, \fBman\fR searches each directory in the manual
page path, and displays the first matching manual page found.
.sp
.LP
The \fBman.cf\fR file has the following format:
.sp
.in +2
.nf
MANSECTS=\fIsection\fR[,\fIsection\fR]... 
.fi
.in -2
.sp

.sp
.LP
Lines beginning with `\fB#\fR' and blank lines are considered comments, and are
ignored. Each directory specified in \fBMANPATH\fR can contain a manual page
configuration file, specifying the default search order for that directory.
.SH FORMATTING MANUAL PAGES
.sp
.LP
Manual pages are marked up in \fBnroff\fR(1) or \fBsgml\fR(5). Nroff manual
pages are processed by \fBnroff\fR(1) or \fBtroff\fR(1) with the \fB-man\fR
macro package. Please refer to \fBman\fR(5) for information on macro usage.
\fBSGML\fR\(emtagged manual pages are processed by an \fBSGML\fR parser and
passed to the formatter.
.SS "Preprocessing Nroff Manual Pages"
.sp
.LP
When formatting an nroff manual page, \fBman\fR examines the first line to
determine whether it requires special processing. If the first line is a string
of the form:
.sp
.in +2
.nf
\&'\e" \fIX\fR
.fi
.in -2
.sp

.sp
.LP
where \fIX\fR is separated from the `\fB"\fR' by a single SPACE and consists of
any combination of characters in the following list, \fBman\fR pipes its input
to \fBtroff\fR(1) or \fBnroff\fR(1) through the corresponding preprocessors.
.sp
.ne 2
.mk
.na
\fB\fBe\fR\fR
.ad
.RS 5n
.rt  
\fBeqn\fR(1), or \fBneqn\fR for \fBnroff\fR
.RE

.sp
.ne 2
.mk
.na
\fB\fBr\fR\fR
.ad
.RS 5n
.rt  
\fBrefer\fR(1)
.RE

.sp
.ne 2
.mk
.na
\fB\fBt\fR\fR
.ad
.RS 5n
.rt  
\fBtbl\fR(1)
.RE

.sp
.ne 2
.mk
.na
\fB\fBv\fR\fR
.ad
.RS 5n
.rt  
\fBvgrind\fR(1)
.RE

.sp
.LP
If \fBeqn\fR or \fBneqn\fR is invoked, it automatically reads the file
\fB/usr/pub/eqnchar\fR (see \fBeqnchar\fR(5)). If \fBnroff\fR(1) is invoked,
\fBcol\fR(1) is automatically used.
.SS "Referring to Other nroff Manual Pages"
.sp
.LP
If the first line of the nroff manual page is a reference to another manual
page entry fitting the pattern:
.sp
.in +2
.nf
\&.so man*/\fIsourcefile\fR
.fi
.in -2
.sp

.sp
.LP
\fBman\fR processes the indicated file in place of the current one. The
reference must be expressed as a path name relative to the root of the manual
page directory subtree.
.sp
.LP
When the second or any subsequent line starts with \fB\&.so\fR, \fBman\fR
ignores it; \fBtroff\fR(1) or \fBnroff\fR(1) processes the request in the usual
manner.
.SS "Processing SGML Manual Pages"
.sp
.LP
Manual pages are identified as being marked up in SGML by the presence of the
string \fB<!DOCTYPE\fR\&. If the file also contains the string
\fBSHADOW_PAGE\fR, 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 \fB\&.so\fR mechanism used in the nroff
formatted man pages.
.SH ENVIRONMENT VARIABLES
.sp
.LP
See \fBenviron\fR(5) for descriptions of the following environment variables
that affect the execution of \fBman\fR: \fBLANG\fR, \fBLC_ALL\fR,
\fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
.sp
.ne 2
.mk
.na
\fB\fBMANPATH\fR\fR
.ad
.RS 11n
.rt  
A colon-separated list of directories; each directory can be followed by a
comma-separated list of sections. If set, its value overrides
\fB/usr/share/man\fR as the default directory search path, and the \fBman.cf\fR
file as the default section search path. The \fB-M\fR and \fB-s\fR flags, in
turn, override these values.)
.RE

.sp
.ne 2
.mk
.na
\fB\fBPAGER\fR\fR
.ad
.RS 11n
.rt  
A program to use for interactively delivering \fBman\fR's output to the screen.
If not set, `\fBmore\fR \fB-s\fR' is used. See \fBmore\fR(1).
.RE

.sp
.ne 2
.mk
.na
\fB\fBTCAT\fR\fR
.ad
.RS 11n
.rt  
The name of the program to use to display \fBtroff\fRed manual pages.
.RE

.sp
.ne 2
.mk
.na
\fB\fBTROFF\fR\fR
.ad
.RS 11n
.rt  
The name of the formatter to use when the \fB-t\fR flag is given. If not set,
\fBtroff\fR(1) is used.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRCreating a PostScript Version of a man page
.sp
.LP
The following example creates the \fBpipe\fR(2) man page in postscript for csh,
tcsh, ksh and sh users:

.sp
.in +2
.nf
	% env TCAT=/usr/lib/lp/postscript/dpost man -t -s 2 pipe > pipe.ps
.fi
.in -2
.sp

.sp
.LP
This is an alternative to using \fBman\fR \fB-t\fR, which sends the man page to
the default printer, if the user wants a postscript file version of the man
page.

.LP
\fBExample 2 \fRCreating a Text Version of a man page
.sp
.LP
The following example creates the \fBpipe\fR(2) man page in ascii text:

.sp
.in +2
.nf
man pipe.2 | col -x -b > pipe.text
.fi
.in -2
.sp

.sp
.LP
This is an alternative to using \fBman\fR \fB-t\fR, which sends the man page to
the default printer, if the user wants a text file version of the man page.

.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.mk
.na
\fB\fB0\fR\fR
.ad
.RS 6n
.rt  
Successful completion.
.RE

.sp
.ne 2
.mk
.na
\fB\fB>0\fR\fR
.ad
.RS 6n
.rt  
An error occurred.
.RE

.SH FILES
.sp
.ne 2
.mk
.na
\fB\fB/usr/share/man\fR\fR
.ad
.sp .6
.RS 4n
Root of the standard manual page directory subtree
.RE

.sp
.ne 2
.mk
.na
\fB\fB/usr/share/man/man?/*\fR\fR
.ad
.sp .6
.RS 4n
Unformatted nroff manual entries
.RE

.sp
.ne 2
.mk
.na
\fB\fB/usr/share/man/sman?/*\fR\fR
.ad
.sp .6
.RS 4n
Unformatted \fBSGML\fR manual entries
.RE

.sp
.ne 2
.mk
.na
\fB\fB/usr/share/man/cat?/*\fR\fR
.ad
.sp .6
.RS 4n
\fBnroff\fRed manual entries
.RE

.sp
.ne 2
.mk
.na
\fB\fB/usr/share/man/fmt?/*\fR\fR
.ad
.sp .6
.RS 4n
\fBtroff\fRed manual entries
.RE

.sp
.ne 2
.mk
.na
\fB\fB/usr/share/man/windex\fR\fR
.ad
.sp .6
.RS 4n
Table of contents and keyword database
.RE

.sp
.ne 2
.mk
.na
\fB\fB/usr/share/lib/tmac/an\fR\fR
.ad
.sp .6
.RS 4n
Standard \fB-man\fR macro package
.RE

.sp
.ne 2
.mk
.na
\fB\fB/usr/share/lib/sgml/locale/C/dtd/*\fR\fR
.ad
.sp .6
.RS 4n
\fBSGML\fR document type definition files
.RE

.sp
.ne 2
.mk
.na
\fB\fB/usr/share/lib/sgml/locale/C/solbook/*\fR\fR
.ad
.sp .6
.RS 4n
\fBSGML\fR style sheet and entity definitions directories
.RE

.sp
.ne 2
.mk
.na
\fB\fB/usr/share/lib/pub/eqnchar\fR\fR
.ad
.sp .6
.RS 4n
Standard definitions for \fBeqn\fR and \fBneqn\fR
.RE

.sp
.ne 2
.mk
.na
\fB\fBman.cf\fR\fR
.ad
.sp .6
.RS 4n
Default search order by section
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
CSIEnabled, see \fBNOTES\fR.
_
Interface StabilityCommitted
_
StandardSee \fBstandards\fR(5). 
.TE

.SH SEE ALSO
.sp
.LP
\fBapropos\fR(1), \fBcat\fR(1), \fBcol\fR(1), \fBdpost\fR(1), \fBeqn\fR(1),
\fBmore\fR(1), \fBnroff\fR(1), \fBrefer\fR(1), \fBtbl\fR(1), \fBtroff\fR(1),
\fBvgrind\fR(1), \fBwhatis\fR(1), \fBcatman\fR(1M), \fBattributes\fR(5),
\fBenviron\fR(5), \fBeqnchar\fR(5), \fBman\fR(5), \fBsgml\fR(5),
\fBstandards\fR(5)
.SH NOTES
.sp
.LP
The \fB-f\fR and \fB-k\fR options use the \fBwindex\fR database, which is
created by \fBcatman\fR(1M).
.sp
.LP
The \fBman\fR command is CSI-capable. However, some utilities invoked by the
\fBman\fR command, namely, \fBtroff\fR, \fBeqn\fR, \fBneqn\fR, \fBrefer\fR,
\fBtbl\fR, and \fBvgrind\fR, are not verified to be CSI-capable. Because of
this, the man command with the \fB-t\fR option can not handle non-EUC data.
Also, using the \fBman\fR command to display man pages that require special
processing through \fBeqn\fR, \fBneqn\fR, \fBrefer\fR, \fBtbl\fR, or
\fBvgrind\fR can not be CSI-capable.
.SH BUGS
.sp
.LP
The manual is supposed to be reproducible either on a phototypesetter or on an
\fBASCII\fR terminal. However, on a terminal some information (indicated by
font changes, for instance) is lost.
.sp
.LP
Some dumb terminals cannot process the vertical motions produced by the \fBe\fR
(see \fBeqn\fR(1)) preprocessing flag. To prevent garbled output on these
terminals, when you use \fBe\fR, also use \fBt\fR, to invoke \fBcol\fR(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 \fBeqn\fR(1) output.