1MAN(1P)                    POSIX Programmer's Manual                   MAN(1P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       man — display system documentation
14

SYNOPSIS

16       man [−k] name...
17

DESCRIPTION

19       The man utility shall write information about each of  the  name  oper‐
20       ands. If name is the name of a standard utility, man at a minimum shall
21       write a message describing the syntax used by the standard utility, its
22       options,  and operands. If more information is available, the man util‐
23       ity shall provide it in an implementation-defined manner.
24
25       An implementation may provide information for values of name other than
26       the  standard utilities. Standard utilities that are listed as optional
27       and that are not supported by the implementation either shall  cause  a
28       brief  message  indicating  that  fact to be displayed or shall cause a
29       full display of information as described previously.
30

OPTIONS

32       The man utility  shall  conform  to  the  Base  Definitions  volume  of
33       POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.
34
35       The following option shall be supported:
36
37       −k      Interpret  name  operands as keywords to be used in searching a
38               utilities summary database that contains a brief purpose  entry
39               for  each  standard  utility  and  write lines from the summary
40               database that match any of the  keywords.  The  keyword  search
41               shall  produce results that are the equivalent of the output of
42               the following command:
43
44                   grep −Ei '
45                   name
46                   name
47                   ...
48                   ' summary-database
49
50               This assumes that the summary-database is a text  file  with  a
51               single  entry  per  line; this organization is not required and
52               the example using grep −Ei is merely illustrative of  the  type
53               of  search  intended.  The  purpose entry to be included in the
54               database shall consist of a terse description of the purpose of
55               the utility.
56

OPERANDS

58       The following operand shall be supported:
59
60       name      A  keyword  or the name of a standard utility. When −k is not
61                 specified and name does not represent  one  of  the  standard
62                 utilities, the results are unspecified.
63

STDIN

65       Not used.
66

INPUT FILES

68       None.
69

ENVIRONMENT VARIABLES

71       The following environment variables shall affect the execution of man:
72
73       LANG      Provide  a  default  value for the internationalization vari‐
74                 ables that are unset or null. (See the Base Definitions  vol‐
75                 ume  of POSIX.1‐2008, Section 8.2, Internationalization Vari‐
76                 ables for the precedence  of  internationalization  variables
77                 used to determine the values of locale categories.)
78
79       LC_ALL    If  set  to  a non-empty string value, override the values of
80                 all the other internationalization variables.
81
82       LC_CTYPE  Determine the locale for the interpretation of  sequences  of
83                 bytes of text data as characters (for example, single-byte as
84                 opposed to multi-byte characters in arguments and in the sum‐
85                 mary  database).  The  value  of LC_CTYPE need not affect the
86                 format of the information written about the name operands.
87
88       LC_MESSAGES
89                 Determine the locale that should be used to affect the format
90                 and contents of diagnostic messages written to standard error
91                 and informative messages written to standard output.
92
93       NLSPATH   Determine the location of message catalogs for the processing
94                 of LC_MESSAGES.
95
96       PAGER     Determine  an output filtering command for writing the output
97                 to a terminal. Any string acceptable as a command_string  op‐
98                 erand to the sh −c command shall be valid. When standard out‐
99                 put is a terminal device, the reference page output shall  be
100                 piped  through  the command. If the PAGER variable is null or
101                 not set, the command shall be either more or another  pagina‐
102                 tor utility documented in the system documentation.
103

ASYNCHRONOUS EVENTS

105       Default.
106

STDOUT

108       The  man  utility shall write text describing the syntax of the utility
109       name, its options and its operands, or, when  −k  is  specified,  lines
110       from  the  summary database. The format of this text is implementation-
111       defined.
112

STDERR

114       The standard error shall be used for diagnostic messages, and may  also
115       be used for informational messages of unspecified format.
116

OUTPUT FILES

118       None.
119

EXTENDED DESCRIPTION

121       None.
122

EXIT STATUS

124       The following exit values shall be returned:
125
126        0    Successful completion.
127
128       >0    An error occurred.
129

CONSEQUENCES OF ERRORS

131       Default.
132
133       The following sections are informative.
134

APPLICATION USAGE

136       None.
137

EXAMPLES

139       None.
140

RATIONALE

142       It  is recognized that the man utility is only of minimal usefulness as
143       specified. The opinion of the standard developers was strongly  divided
144       as to how much or how little information man should be required to pro‐
145       vide. They considered, however, that the provision of some portable way
146       of  accessing  documentation  would aid user portability. The arguments
147       against a fuller specification were:
148
149        *  Large quantities of documentation should not be required on a  sys‐
150           tem that does not have excess disk space.
151
152        *  The  current manual system does not present information in a manner
153           that greatly aids user portability.
154
155        *  A ``better help system'' is currently an area in which vendors feel
156           that they can add value to their POSIX implementations.
157
158       The −f option was considered, but due to implementation differences, it
159       was not included in this volume of POSIX.1‐2008.
160
161       The description was changed to be more specific about what  has  to  be
162       displayed for a utility. The standard developers considered it insuffi‐
163       cient to allow a display of only the synopsis without  giving  a  short
164       description of what each option and operand does.
165
166       The  ``purpose'' entry to be included in the database can be similar to
167       the section title  (less  the  numeric  prefix)  from  this  volume  of
168       POSIX.1‐2008  for each utility.  These titles are similar to those used
169       in historical systems for this purpose.
170
171       See mailx for rationale concerning the default paginator.
172
173       The caveat in the LC_CTYPE description was added because it  is  not  a
174       requirement  that  an implementation provide reference pages for all of
175       its supported locales on each system; changing LC_CTYPE does not neces‐
176       sarily  translate  the  reference  page  into another language. This is
177       equivalent to the current state of LC_MESSAGES in  POSIX.1‐2008—locale-
178       specific messages are not yet a requirement.
179
180       The  historical  MANPATH  variable  is not included in POSIX because no
181       attempt is made to specify naming conventions for reference page files,
182       nor even to mandate that they are files at all. On some implementations
183       they could be a true database, a hypertext file, or even fixed  strings
184       within  the  man  executable.  The  standard  developers considered the
185       portability of reference pages to be outside their scope of work.  How‐
186       ever,  users should be aware that MANPATH is implemented on a number of
187       historical systems and that it can be used to tailor the search pattern
188       for  reference pages from the various categories (utilities, functions,
189       file formats, and so on) when  the  system  administrator  reveals  the
190       location and conventions for reference pages on the system.
191
192       The  keyword search can rely on at least the text of the section titles
193       from these utility descriptions, and the implementation  may  add  more
194       keywords. The term ``section titles'' refers to the strings such as:
195
196           man — Display system documentation
197           ps — Report process status
198

FUTURE DIRECTIONS

200       None.
201

SEE ALSO

203       more
204
205       The  Base  Definitions  volume  of POSIX.1‐2008, Chapter 8, Environment
206       Variables, Section 12.2, Utility Syntax Guidelines
207
209       Portions of this text are reprinted and reproduced in  electronic  form
210       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
211       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
212       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
213       cal and Electronics Engineers,  Inc  and  The  Open  Group.   (This  is
214       POSIX.1-2008  with  the  2013  Technical Corrigendum 1 applied.) In the
215       event of any discrepancy between this version and the original IEEE and
216       The  Open Group Standard, the original IEEE and The Open Group Standard
217       is the referee document. The original Standard can be  obtained  online
218       at http://www.unix.org/online.html .
219
220       Any  typographical  or  formatting  errors that appear in this page are
221       most likely to have been introduced during the conversion of the source
222       files  to  man page format. To report such errors, see https://www.ker
223       nel.org/doc/man-pages/reporting_bugs.html .
224
225
226
227IEEE/The Open Group                  2013                              MAN(1P)
Impressum