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