man1p/man.1p

   1 .\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
   2 .TH "MAN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
   3 .\" man
   4 .SH NAME
   5 man \- display system documentation
   6 .SH SYNOPSIS
   7 .LP
   8 \fBman\fP \fB[\fP\fB-k\fP\fB]\fP \fIname\fP\fB...\fP
   9 .SH DESCRIPTION
  10 .LP
  11 The \fIman\fP utility shall write information about each of the \fIname\fP
  12 operands. If \fIname\fP is the name of a standard
  13 utility, \fIman\fP at a minimum shall write a message describing the
  14 syntax used by the standard utility, its options, and
  15 operands. If more information is available, the \fIman\fP utility
  16 shall provide it in an implementation-defined manner.
  17 .LP
  18 An implementation may provide information for values of \fIname\fP
  19 other than the standard utilities. Standard utilities that
  20 are listed as optional and that are not supported by the implementation
  21 either shall cause a brief message indicating that fact to
  22 be displayed or shall cause a full display of information as described
  23 previously.
  24 .SH OPTIONS
  25 .LP
  26 The \fIman\fP utility shall conform to the Base Definitions volume
  27 of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
  28 .LP
  29 The following option shall be supported:
  30 .TP 7
  31 \fB-k\fP
  32 Interpret \fIname\fP operands as keywords to be used in searching
  33 a utilities summary database that contains a brief purpose
  34 entry for each standard utility and write lines from the summary database
  35 that match any of the keywords. The keyword search shall
  36 produce results that are the equivalent of the output of the following
  37 command:
  38 .sp
  39 .RS
  40 .nf
  41
  42 \fBgrep -Ei '
  43 \fP\fIname
  44 name\fP\fB...
  45 '\fP \fIsummary-database\fP
  46 .fi
  47 .RE
  48 .LP
  49 This assumes that the \fIsummary-database\fP is a text file with a
  50 single entry per line; this organization is not required and
  51 the example using \fIgrep\fP \fB-Ei\fP is merely illustrative of the
  52 type of search
  53 intended. The purpose entry to be included in the database shall consist
  54 of a terse description of the purpose of the utility.
  55 .sp
  56 .SH OPERANDS
  57 .LP
  58 The following operand shall be supported:
  59 .TP 7
  60 \fIname\fP
  61 A keyword or the name of a standard utility. When \fB-k\fP is not
  62 specified and \fIname\fP does not represent one of the
  63 standard utilities, the results are unspecified.
  64 .sp
  65 .SH STDIN
  66 .LP
  67 Not used.
  68 .SH INPUT FILES
  69 .LP
  70 None.
  71 .SH ENVIRONMENT VARIABLES
  72 .LP
  73 The following environment variables shall affect the execution of
  74 \fIman\fP:
  75 .TP 7
  76 \fILANG\fP
  77 Provide a default value for the internationalization variables that
  78 are unset or null. (See the Base Definitions volume of
  79 IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
  80 for
  81 the precedence of internationalization variables used to determine
  82 the values of locale categories.)
  83 .TP 7
  84 \fILC_ALL\fP
  85 If set to a non-empty string value, override the values of all the
  86 other internationalization variables.
  87 .TP 7
  88 \fILC_CTYPE\fP
  89 Determine the locale for the interpretation of sequences of bytes
  90 of text data as characters (for example, single-byte as
  91 opposed to multi-byte characters in arguments and in the summary database).
  92 The value of \fILC_CTYPE\fP need not affect the format
  93 of the information written about the \fIname\fP operands.
  94 .TP 7
  95 \fILC_MESSAGES\fP
  96 Determine the locale that should be used to affect the format and
  97 contents of diagnostic messages written to standard error and
  98 informative messages written to standard output.
  99 .TP 7
 100 \fINLSPATH\fP
 101 Determine the location of message catalogs for the processing of \fILC_MESSAGES
 102 \&.\fP
 103 .TP 7
 104 \fIPAGER\fP
 105 Determine an output filtering command for writing the output to a
 106 terminal. Any string acceptable as a \fIcommand_string\fP
 107 operand to the \fIsh\fP \fB-c\fP command shall be valid. When standard
 108 output is a terminal
 109 device, the reference page output shall be piped through the command.
 110 If the \fIPAGER\fP variable is null or not set, the command
 111 shall be either \fImore\fP or another paginator utility documented
 112 in the system
 113 documentation.
 114 .sp
 115 .SH ASYNCHRONOUS EVENTS
 116 .LP
 117 Default.
 118 .SH STDOUT
 119 .LP
 120 The \fIman\fP utility shall write text describing the syntax of the
 121 utility \fIname\fP, its options and its operands, or, when
 122 \fB-k\fP is specified, lines from the summary database. The format
 123 of this text is implementation-defined.
 124 .SH STDERR
 125 .LP
 126 The standard error shall be used only for diagnostic messages.
 127 .SH OUTPUT FILES
 128 .LP
 129 None.
 130 .SH EXTENDED DESCRIPTION
 131 .LP
 132 None.
 133 .SH EXIT STATUS
 134 .LP
 135 The following exit values shall be returned:
 136 .TP 7
 137 \ 0
 138 Successful completion.
 139 .TP 7
 140 >0
 141 An error occurred.
 142 .sp
 143 .SH CONSEQUENCES OF ERRORS
 144 .LP
 145 Default.
 146 .LP
 147 \fIThe following sections are informative.\fP
 148 .SH APPLICATION USAGE
 149 .LP
 150 None.
 151 .SH EXAMPLES
 152 .LP
 153 None.
 154 .SH RATIONALE
 155 .LP
 156 It is recognized that the \fIman\fP utility is only of minimal usefulness
 157 as specified. The opinion of the standard developers
 158 was strongly divided as to how much or how little information \fIman\fP
 159 should be required to provide. They considered, however,
 160 that the provision of some portable way of accessing documentation
 161 would aid user portability. The arguments against a fuller
 162 specification were:
 163 .IP " *" 3
 164 Large quantities of documentation should not be required on a system
 165 that does not have excess disk space.
 166 .LP
 167 .IP " *" 3
 168 The current manual system does not present information in a manner
 169 that greatly aids user portability.
 170 .LP
 171 .IP " *" 3
 172 A "better help system" is currently an area in which vendors feel
 173 that they can add value to their POSIX implementations.
 174 .LP
 175 .LP
 176 The \fB-f\fP option was considered, but due to implementation differences,
 177 it was not included in this volume of
 178 IEEE\ Std\ 1003.1-2001.
 179 .LP
 180 The description was changed to be more specific about what has to
 181 be displayed for a utility. The standard developers considered
 182 it insufficient to allow a display of only the synopsis without giving
 183 a short description of what each option and operand
 184 does.
 185 .LP
 186 The "purpose" entry to be included in the database can be similar
 187 to the section title (less the numeric prefix) from this
 188 volume of IEEE\ Std\ 1003.1-2001 for each utility. These titles are
 189 similar to those used in historical systems for this
 190 purpose.
 191 .LP
 192 See \fImailx\fP for rationale concerning the default paginator.
 193 .LP
 194 The caveat in the \fILC_CTYPE\fP description was added because it
 195 is not a requirement that an implementation provide reference
 196 pages for all of its supported locales on each system; changing \fILC_CTYPE\fP
 197 does not necessarily translate the reference page
 198 into another language. This is equivalent to the current state of
 199 \fILC_MESSAGES\fP in
 200 IEEE\ Std\ 1003.1-2001-locale-specific messages are not yet a requirement.
 201 .LP
 202 The historical \fIMANPATH\fP variable is not included in POSIX because
 203 no attempt is made to specify naming conventions for
 204 reference page files, nor even to mandate that they are files at all.
 205 On some implementations they could be a true database, a
 206 hypertext file, or even fixed strings within the \fIman\fP executable.
 207 The standard developers considered the portability of
 208 reference pages to be outside their scope of work. However, users
 209 should be aware that \fIMANPATH\fP is implemented on a number of
 210 historical systems and that it can be used to tailor the search pattern
 211 for reference pages from the various categories (utilities,
 212 functions, file formats, and so on) when the system administrator
 213 reveals the location and conventions for reference pages on the
 214 system.
 215 .LP
 216 The keyword search can rely on at least the text of the section titles
 217 from these utility descriptions, and the implementation
 218 may add more keywords. The term "section titles" refers to the strings
 219 such as:
 220 .sp
 221 .RS
 222 .nf
 223
 224 \fBman - Display system documentation
 225 ps - Report process status
 226 \fP
 227 .fi
 228 .RE
 229 .SH FUTURE DIRECTIONS
 230 .LP
 231 None.
 232 .SH SEE ALSO
 233 .LP
 234 \fImore\fP
 235 .SH COPYRIGHT
 236 Portions of this text are reprinted and reproduced in electronic form
 237 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
 238 -- Portable Operating System Interface (POSIX), The Open Group Base
 239 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
 240 Electrical and Electronics Engineers, Inc and The Open Group. In the
 241 event of any discrepancy between this version and the original IEEE and
 242 The Open Group Standard, the original IEEE and The Open Group Standard
 243 is the referee document. The original Standard can be obtained online at
 244 http://www.opengroup.org/unix/online.html .