xref: /titanic_51/usr/src/man/man1/man.1 (revision 45818ee124adeaaf947698996b4f4c722afc6d1f)
1.\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
2.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
3.\" Copyright (c) 1980 Regents of the University of California.
4.\" The Berkeley software License Agreement specifies the terms and conditions
5.\" for redistribution.
6.Dd Jul 18, 2014
7.Dt MAN 1
8.Os
9.Sh NAME
10.Nm man
11.Nd find and display reference manual pages
12.Sh SYNOPSIS
13.Nm
14.Op Fl
15.Op Fl adFlrt
16.Op Fl T Ar macro-package
17.Op Fl M Ar path
18.Op Fl s Ar section
19.Ar name ...
20.Nm
21.Op Fl M Ar path
22.Op Fl s Ar section
23.Fl k
24.Ar keyword
25.Ar ...
26.Nm
27.Op Fl M Ar path
28.Op Fl s Ar section
29.Fl f
30.Ar
31.Nm
32.Op Fl M Ar path
33.Fl w
34.Sh DESCRIPTION
35The
36.Nm
37command displays information from the reference manuals. It
38displays complete manual pages that you select by
39.Ar name ,
40or one-line summaries selected either by
41.Ar keyword
42.Pq Fl k ,
43or by the name of an associated file
44.Pq Fl f .
45If no manual page is located,
46.Nm
47prints an error message.
48.Ss "Source Format"
49Reference Manual pages are marked up with either
50.Xr man 5 ,
51or
52.Xr mdoc 5
53language tags. The
54.Nm
55command recognizes the type of markup and
56processes the file accordingly.
57.
58.Ss "Location of Manual Pages"
59.
60The online Reference Manual page directories are conventionally located in
61.Pa /usr/share/man .
62Each directory corresponds to a
63section of the manual. Since these directories are optionally installed, they
64might not reside on your host. You might have to mount
65.Pa /usr/share/man
66from a host on which they do reside.
67The
68.Nm
69command reformats a page whenever it is requested.
70.Pp
71If the standard output is not a terminal, or if the
72.Fl
73flag is given,
74.Nm
75pipes its output through
76.Xr cat 1 .
77Otherwise,
78.Nm
79pipes its output through a pager such as
80.Xr more 1
81to handle paging and underlining on the screen.
82.Sh OPTIONS
83The following options are supported:
84.Bl -tag -width indent
85.It Fl a
86Shows all manual pages matching
87.Ar name
88within the
89.Ev MANPATH
90search path. Manual pages are displayed in the order found.
91.It Fl d
92Debugs. Displays what a section-specifier evaluates to, method used for
93searching, and paths searched by
94.Nm .
95.It Fl f Ar file ...
96Attempts to locate manual pages related to any of the given
97.Ar file
98names. It strips the leading path name components from each
99.Ar file ,
100and then prints one-line summaries containing the resulting basename or names.
101This option also uses the
102.Pa whatis
103database.
104.It Fl F
105This option is present for backwards compatibility and is documented
106here for reference only.  It performs no function.
107.It Fl k Ar keyword ...
108Prints out one-line summaries from the
109.Pa whatis
110database (table of contents) that contain any of the given
111.Ar keyword .
112The
113.Pa whatis
114database is created using the
115.Fl w
116option.
117.It Fl l
118Lists all manual pages found matching
119.Ar name
120within the search path.
121.It Fl M Ar path
122Specifies an alternate search path for manual pages. The
123.Ar path
124is a colon-separated list of directories that contain manual page directory
125subtrees. For example, if
126.Ar path
127is
128.Pa /usr/share/man:/usr/local/man ,
129.Nm
130searches for
131.Ar name
132in the standard location, and then
133.Pa /usr/local/man .
134When used with the
135.Fl k ,
136.Fl f ,
137or
138.Fl w
139options, the
140.Fl M
141option must appear first. Each directory in the
142.Ar path
143is assumed to contain subdirectories of the form
144.Pa man* ,
145one for each section. This option overrides the
146.Ev MANPATH
147environment variable.
148.It Fl r
149Reformats the manual page, checking for formatting errors, but does not
150display it.
151.It Fl s Ar section
152Specifies sections of the manual for
153.Nm
154to search. The directories searched for
155.Ar name
156are limited to those specified by
157.Ar section .
158.Ar section
159can be a numerical digit, perhaps followed by one or more letters
160to match the desired section of the manual, for example,
161.Li "3libucb".
162Also,
163.Ar section
164can be a word, for example,
165.Li local ,
166.Li new ,
167.Li old ,
168.Li public .
169.Ar section
170can also be a letter. To specify multiple sections,
171separate each section with a comma. This option overrides the
172.Ev MANPATH
173environment variable and the
174.Pa man.cf
175file. See
176.Sx Search Path
177below for an explanation of how
178.Nm
179conducts its search.
180.It Fl t
181Arranges for the specified manual pages to be sent to the default
182printer as PostScript.
183.It Fl T Ar macro-package
184This option is present for backwards compatibility and is documented
185here for reference only.  It performs no function.
186.It Fl w
187Updates the
188.Nm whatis
189database.
190.El
191.Sh OPERANDS
192The following operand is supported:
193.Bl -tag -width indent
194.It Ar name
195The name of a standard utility or a keyword.
196.El
197.Sh USAGE
198The usage of
199.Nm
200is described below:
201.
202.Ss "Manual Page Sections"
203.
204Entries in the reference manuals are organized into
205.Em sections .
206A section
207name consists of a major section name, typically a single digit, optionally
208followed by a subsection name, typically one or more letters. An unadorned
209major section name, for example,
210.Qq 9 ,
211does not act as an abbreviation for
212the subsections of that name, such as
213.Qq 9e ,
214.Qq 9f ,
215or
216.Qq 9s .
217That is, each subsection must be searched separately by
218.Nm
219.Fl s .
220Each section contains descriptions apropos to a particular reference category,
221with subsections refining these distinctions. See the
222.Em intro
223manual pages for an explanation of the classification used in this release.
224.
225.Ss "Search Path"
226.
227Before searching for a given
228.Ar name ,
229.Nm
230constructs a list of candidate directories and sections.
231It searches for
232.Ar name
233in the directories specified by the
234.Ev MANPATH
235environment variable.
236.Lp
237In the absence of
238.Ev MANPATH ,
239.Nm
240constructs its search path based upon the
241.Ev PATH
242environment variable, primarily by substituting
243.Li man
244for the last component of the
245.Ev PATH
246element. Special provisions are added
247to account for unique characteristics of directories such as
248.Pa /sbin ,
249.Pa /usr/ucb ,
250.Pa /usr/xpg4/bin ,
251and others. If the file argument contains
252a
253.Qq /
254character, the
255.Em dirname
256portion of the argument is used in place of
257.Ev PATH
258elements to construct the search path.
259.Lp
260Within the manual page directories,
261.Nm
262confines its search to the
263sections specified in the following order:
264.Bl -bullet
265.It
266.Ar sections
267specified on the command line with the
268.Fl s
269option
270.It
271.Ar sections
272embedded in the
273.Ev MANPATH
274environment variable
275.It
276.Ar sections
277specified in the
278.Pa man.cf
279file for each directory specified in the
280.Ev MANPATH
281environment variable
282.El
283If none of the above exist,
284.Nm
285searches each directory in the manual
286page path, and displays the first matching manual page found.
287.Lp
288The
289.Pa man.cf
290file has the following format:
291.Lp
292.Dl Pf MANSECTS= Ar section , Ns Op Ar section...
293.Lp
294Lines beginning with
295.Sq Li #
296and blank lines are considered comments, and are
297ignored. Each directory specified in
298.Ev MANPATH
299can contain a manual page
300configuration file, specifying the default search order for that directory.
301.Sh "Referring to Other Manual Pages"
302If the first line of the manual page is a reference to another manual
303page entry fitting the pattern:
304.Lp
305.Dl \&.so man*/\fIsourcefile\fR
306.Lp
307.Nm
308processes the indicated file in place of the current one. The
309reference must be expressed as a path name relative to the root of the manual
310page directory subtree.
311.Lp
312When the second or any subsequent line starts with \fB\&.so\fR, \fBman\fR
313ignores it; \fBtroff\fR(1) or \fBnroff\fR(1) processes the request in the usual
314manner.
315.Sh ENVIRONMENT VARIABLES
316See
317.Xr environ 5
318for descriptions of the following environment variables
319that affect the execution of
320.Nm man :
321.Ev LANG ,
322.Ev LC_ALL ,
323.Ev LC_CTYPE ,
324.Ev LC_MESSAGES ,
325and
326.Ev NLSPATH .
327.Bl -tag -width indent
328.It Ev MANPATH
329A colon-separated list of directories; each directory can be followed by a
330comma-separated list of sections. If set, its value overrides
331\fB/usr/share/man\fR as the default directory search path, and the \fBman.cf\fR
332file as the default section search path. The \fB-M\fR and \fB-s\fR flags, in
333turn, override these values.)
334.It Ev PAGER
335A program to use for interactively delivering
336output to the screen. If not set,
337.Sq Nm more Fl s
338is used. See
339.Xr more 1 .
340.El
341.Sh FILES
342.Bl -tag -width indent
343.It Pa /usr/share/man
344Root of the standard manual page directory subtree
345.It Pa /usr/share/man/man?/*
346Unformatted manual entries
347.It Pa /usr/share/man/whatis
348Table of contents and keyword database
349.It Pa man.cf
350Default search order by section
351.El
352.Sh EXIT STATUS
353.Ex -std man
354.Sh EXAMPLES
355.
356.Ss Example 1: Creating a PostScript Version of a man page
357.
358The following example spools the
359.Xr pipe 2
360man page in PostScript to the default printer:
361.Pp
362.Dl % man -t -s 2 pipe
363.Pp
364Note that
365.Xr mandoc 1
366can be used to obtain the PostScript content directly.
367.Ss Example 2: Creating a Text Version of a man page
368The following example creates the
369.Xr pipe 2
370man page in ASCII text:
371.Pp
372.Dl % man pipe.2 | col -x -b > pipe.text
373.Sh CODE SET INDEPENDENCE
374Enabled.
375.Sh INTERFACE STABILITY
376.Sy Committed .
377.Sh SEE ALSO
378.Xr apropos 1 ,
379.Xr cat 1 ,
380.Xr col 1 ,
381.Xr mandoc 1 ,
382.Xr more 1 ,
383.Xr whatis 1 ,
384.Xr environ 5 ,
385.Xr man 5 ,
386.Xr mdoc 5
387.Sh NOTES
388The
389.Fl f
390and
391.Fl k
392options use the
393.Nm whatis
394database, which is
395created with the
396.Fl w
397option.
398.Sh BUGS
399The manual is supposed to be reproducible either on a phototypesetter or on an
400ASCII terminal. However, on a terminal some information (indicated by
401font changes, for instance) is lost.
402