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