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