mirror of https://github.com/mkerrisk/man-pages
245 lines
8.1 KiB
Groff
245 lines
8.1 KiB
Groff
|
.\" 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 .
|