path: root/man1p/man.1p

.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "MAN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" man 
.SH NAME
man \- display system documentation
.SH SYNOPSIS
.LP
\fBman\fP \fB[\fP\fB-k\fP\fB]\fP \fIname\fP\fB...\fP
.SH DESCRIPTION
.LP
The \fIman\fP utility shall write information about each of the \fIname\fP
operands. If \fIname\fP is the name of a standard
utility, \fIman\fP at a minimum shall write a message describing the
syntax used by the standard utility, its options, and
operands. If more information is available, the \fIman\fP utility
shall provide it in an implementation-defined manner.
.LP
An implementation may provide information for values of \fIname\fP
other than the standard utilities. Standard utilities that
are listed as optional and that are not supported by the implementation
either shall cause a brief message indicating that fact to
be displayed or shall cause a full display of information as described
previously.
.SH OPTIONS
.LP
The \fIman\fP utility shall conform to the Base Definitions volume
of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
.LP
The following option shall be supported:
.TP 7
\fB-k\fP
Interpret \fIname\fP operands as keywords to be used in searching
a utilities summary database that contains a brief purpose
entry for each standard utility and write lines from the summary database
that match any of the keywords. The keyword search shall
produce results that are the equivalent of the output of the following
command: 
.sp
.RS
.nf

\fBgrep -Ei '
\fP\fIname
name\fP\fB...
'\fP \fIsummary-database\fP
.fi
.RE
.LP
This assumes that the \fIsummary-database\fP is a text file with a
single entry per line; this organization is not required and
the example using \fIgrep\fP \fB-Ei\fP is merely illustrative of the
type of search
intended. The purpose entry to be included in the database shall consist
of a terse description of the purpose of the utility.
.sp
.SH OPERANDS
.LP
The following operand shall be supported:
.TP 7
\fIname\fP
A keyword or the name of a standard utility. When \fB-k\fP is not
specified and \fIname\fP does not represent one of the
standard utilities, the results are unspecified.
.sp
.SH STDIN
.LP
Not used.
.SH INPUT FILES
.LP
None.
.SH ENVIRONMENT VARIABLES
.LP
The following environment variables shall affect the execution of
\fIman\fP:
.TP 7
\fILANG\fP
Provide a default value for the internationalization variables that
are unset or null. (See the Base Definitions volume of
IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
for
the precedence of internationalization variables used to determine
the values of locale categories.)
.TP 7
\fILC_ALL\fP
If set to a non-empty string value, override the values of all the
other internationalization variables.
.TP 7
\fILC_CTYPE\fP
Determine the locale for the interpretation of sequences of bytes
of text data as characters (for example, single-byte as
opposed to multi-byte characters in arguments and in the summary database).
The value of \fILC_CTYPE\fP need not affect the format
of the information written about the \fIname\fP operands.
.TP 7
\fILC_MESSAGES\fP
Determine the locale that should be used to affect the format and
contents of diagnostic messages written to standard error and
informative messages written to standard output.
.TP 7
\fINLSPATH\fP
Determine the location of message catalogs for the processing of \fILC_MESSAGES
\&.\fP 
.TP 7
\fIPAGER\fP
Determine an output filtering command for writing the output to a
terminal. Any string acceptable as a \fIcommand_string\fP
operand to the \fIsh\fP \fB-c\fP command shall be valid. When standard
output is a terminal
device, the reference page output shall be piped through the command.
If the \fIPAGER\fP variable is null or not set, the command
shall be either \fImore\fP or another paginator utility documented
in the system
documentation.
.sp
.SH ASYNCHRONOUS EVENTS
.LP
Default.
.SH STDOUT
.LP
The \fIman\fP utility shall write text describing the syntax of the
utility \fIname\fP, its options and its operands, or, when
\fB-k\fP is specified, lines from the summary database. The format
of this text is implementation-defined.
.SH STDERR
.LP
The standard error shall be used only for diagnostic messages.
.SH OUTPUT FILES
.LP
None.
.SH EXTENDED DESCRIPTION
.LP
None.
.SH EXIT STATUS
.LP
The following exit values shall be returned:
.TP 7
\ 0
Successful completion.
.TP 7
>0
An error occurred.
.sp
.SH CONSEQUENCES OF ERRORS
.LP
Default.
.LP
\fIThe following sections are informative.\fP
.SH APPLICATION USAGE
.LP
None.
.SH EXAMPLES
.LP
None.
.SH RATIONALE
.LP
It is recognized that the \fIman\fP utility is only of minimal usefulness
as specified. The opinion of the standard developers
was strongly divided as to how much or how little information \fIman\fP
should be required to provide. They considered, however,
that the provision of some portable way of accessing documentation
would aid user portability. The arguments against a fuller
specification were:
.IP " *" 3
Large quantities of documentation should not be required on a system
that does not have excess disk space.
.LP
.IP " *" 3
The current manual system does not present information in a manner
that greatly aids user portability.
.LP
.IP " *" 3
A "better help system" is currently an area in which vendors feel
that they can add value to their POSIX implementations.
.LP
.LP
The \fB-f\fP option was considered, but due to implementation differences,
it was not included in this volume of
IEEE\ Std\ 1003.1-2001.
.LP
The description was changed to be more specific about what has to
be displayed for a utility. The standard developers considered
it insufficient to allow a display of only the synopsis without giving
a short description of what each option and operand
does.
.LP
The "purpose" entry to be included in the database can be similar
to the section title (less the numeric prefix) from this
volume of IEEE\ Std\ 1003.1-2001 for each utility. These titles are
similar to those used in historical systems for this
purpose.
.LP
See \fImailx\fP for rationale concerning the default paginator.
.LP
The caveat in the \fILC_CTYPE\fP description was added because it
is not a requirement that an implementation provide reference
pages for all of its supported locales on each system; changing \fILC_CTYPE\fP
does not necessarily translate the reference page
into another language. This is equivalent to the current state of
\fILC_MESSAGES\fP in
IEEE\ Std\ 1003.1-2001-locale-specific messages are not yet a requirement.
.LP
The historical \fIMANPATH\fP variable is not included in POSIX because
no attempt is made to specify naming conventions for
reference page files, nor even to mandate that they are files at all.
On some implementations they could be a true database, a
hypertext file, or even fixed strings within the \fIman\fP executable.
The standard developers considered the portability of
reference pages to be outside their scope of work. However, users
should be aware that \fIMANPATH\fP is implemented on a number of
historical systems and that it can be used to tailor the search pattern
for reference pages from the various categories (utilities,
functions, file formats, and so on) when the system administrator
reveals the location and conventions for reference pages on the
system.
.LP
The keyword search can rely on at least the text of the section titles
from these utility descriptions, and the implementation
may add more keywords. The term "section titles" refers to the strings
such as:
.sp
.RS
.nf

\fBman - Display system documentation
ps - Report process status
\fP
.fi
.RE
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fImore\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .