man.1p (8887B)
- '\" et
- .TH MAN "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- man
- \(em display system documentation
- .SH SYNOPSIS
- .LP
- .nf
- man \fB[\fR-k\fB] \fIname\fR...
- .fi
- .SH DESCRIPTION
- The
- .IR man
- utility shall write information about each of the
- .IR name
- operands. If
- .IR name
- is the name of a standard utility,
- .IR man
- 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
- .IR man
- utility shall provide it in an implementation-defined manner.
- .P
- An implementation may provide information for values of
- .IR name
- 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
- The
- .IR man
- utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 12.2" ", " "Utility Syntax Guidelines".
- .P
- The following option shall be supported:
- .IP "\fB\-k\fP" 8
- Interpret
- .IR name
- 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:
- .RS 8
- .sp
- .RS 4
- .nf
- grep -Ei \(aq
- \fIname
- name\fP
- \&...
- \&\(aq \fIsummary-database\fR
- .fi
- .P
- .RE
- .P
- This assumes that the
- .IR summary-database
- is a text file with a single entry per line; this organization is not
- required and the example using
- .IR grep
- .BR \-Ei
- 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.
- .RE
- .SH OPERANDS
- The following operand shall be supported:
- .IP "\fIname\fR" 10
- A keyword or the name of a standard utility. When
- .BR \-k
- is not specified and
- .IR name
- does not represent one of the standard utilities, the results are
- unspecified.
- .SH STDIN
- Not used.
- .SH "INPUT FILES"
- None.
- .SH "ENVIRONMENT VARIABLES"
- The following environment variables shall affect the execution of
- .IR man :
- .IP "\fILANG\fP" 10
- Provide a default value for the internationalization variables that are
- unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 8.2" ", " "Internationalization Variables"
- for the precedence of internationalization variables used to determine
- the values of locale categories.)
- .IP "\fILC_ALL\fP" 10
- If set to a non-empty string value, override the values of all the
- other internationalization variables.
- .IP "\fILC_CTYPE\fP" 10
- 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
- .IR LC_CTYPE
- need not affect the format of the information written about the
- .IR name
- operands.
- .IP "\fILC_MESSAGES\fP" 10
- .br
- 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.
- .IP "\fINLSPATH\fP" 10
- Determine the location of message catalogs for the processing of
- .IR LC_MESSAGES .
- .IP "\fIPAGER\fP" 10
- Determine an output filtering command for writing the output to a
- terminal. Any string acceptable as a
- .IR command_string
- operand to the
- .IR sh
- .BR \-c
- command shall be valid. When standard output is a terminal device, the
- reference page output shall be piped through the command. If the
- .IR PAGER
- variable is null or not set, the command shall be either
- .IR more
- or another paginator utility documented in the system documentation.
- .SH "ASYNCHRONOUS EVENTS"
- Default.
- .SH STDOUT
- The
- .IR man
- utility shall write text describing the syntax of the utility
- .IR name ,
- its options and its operands, or, when
- .BR \-k
- is specified, lines from the summary database. The format of this text
- is implementation-defined.
- .SH STDERR
- The standard error shall be used for diagnostic messages, and may also
- be used for informational messages of unspecified format.
- .SH "OUTPUT FILES"
- None.
- .SH "EXTENDED DESCRIPTION"
- None.
- .SH "EXIT STATUS"
- The following exit values shall be returned:
- .IP "\00" 6
- Successful completion.
- .IP >0 6
- An error occurred.
- .SH "CONSEQUENCES OF ERRORS"
- Default.
- .LP
- .IR "The following sections are informative."
- .SH "APPLICATION USAGE"
- None.
- .SH EXAMPLES
- None.
- .SH RATIONALE
- It is recognized that the
- .IR man
- 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
- .IR man
- 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 " *" 4
- Large quantities of documentation should not be required on a system
- that does not have excess disk space.
- .IP " *" 4
- The current manual system does not present information in a manner that
- greatly aids user portability.
- .IP " *" 4
- A ``better help system'' is currently an area in which vendors feel
- that they can add value to their POSIX implementations.
- .P
- The
- .BR \-f
- option was considered, but due to implementation differences, it was
- not included in this volume of POSIX.1\(hy2017.
- .P
- 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.
- .P
- The ``purpose'' entry to be included in the database can be similar to
- the section title (less the numeric prefix) from this volume of POSIX.1\(hy2017 for each utility.
- These titles are similar to those used in historical systems for this
- purpose.
- .P
- See
- .IR mailx
- for rationale concerning the default paginator.
- .P
- The caveat in the
- .IR LC_CTYPE
- 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
- .IR LC_CTYPE
- does not necessarily translate the reference page into another
- language. This is equivalent to the current state of
- .IR LC_MESSAGES
- in POSIX.1\(hy2008\(emlocale-specific messages are not yet a requirement.
- .P
- The historical
- .IR MANPATH
- 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
- .IR man
- executable. The standard developers considered the portability of
- reference pages to be outside their scope of work. However, users
- should be aware that
- .IR MANPATH
- 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.
- .P
- 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 4
- .nf
- man \(em Display system documentation
- ps \(em Report process status
- .fi
- .P
- .RE
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "\fImore\fR\^"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "Chapter 8" ", " "Environment Variables",
- .IR "Section 12.2" ", " "Utility Syntax Guidelines"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 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 .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .