diff options
Diffstat (limited to 'upstream/mageia-cauldron/man1p/man.1p')
| -rw-r--r-- | upstream/mageia-cauldron/man1p/man.1p | 269 |
1 files changed, 269 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man1p/man.1p b/upstream/mageia-cauldron/man1p/man.1p new file mode 100644 index 00000000..054ea7c4 --- /dev/null +++ b/upstream/mageia-cauldron/man1p/man.1p @@ -0,0 +1,269 @@ +'\" 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 . |