Print this page
Latest round of fixes per RM and AL. Fix bugs found in man.c.
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man1/man.1
+++ new/usr/src/man/man1/man.1
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
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
16 7 .Dt MAN 1
17 8 .Os
18 9 .Sh NAME
19 10 .Nm man
20 11 .Nd find and display reference manual pages
21 12 .Sh SYNOPSIS
22 13 .Nm
23 -.Op Fl alptw
24 -.Op Fl M Ar manpath
25 -.Op Fl s Ar mansect
26 -.Ar page ...
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 ...
27 20 .Nm
28 -.Op Fl s Ar mansect
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 29 .Fl f
30 -.Ar keyword ...
30 +.Ar
31 31 .Nm
32 -.Op Fl s Ar mansect
33 -.Fl k
34 -.Ar keyword ...
32 +.Op Fl M Ar path
33 +.Fl w
35 34 .Sh DESCRIPTION
36 35 The
37 36 .Nm
38 -utility finds and displays reference manual pages.
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.
39 70 .Pp
40 -Options that
71 +If the standard output is not a terminal, or if the
72 +.Fl
73 +flag is given,
41 74 .Nm
42 -understands:
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:
43 84 .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 85 .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 .
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.
60 117 .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.
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.
67 180 .It Fl t
68 -Send the content formatted as PostScript to the default printer.
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.
69 186 .It Fl w
70 -Create
187 +Updates the
71 188 .Nm whatis
72 -databases used by
73 -.Xr apropos 1
74 -and
75 -.Xr whatis 1 .
189 +database.
76 190 .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
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
98 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 ,
99 325 and
100 -.Fl M
101 -are not specified.
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 .
102 340 .El
103 341 .Sh FILES
104 -.Bl -tag -width indent -compact
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
105 349 .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.
350 +Default search order by section
115 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
116 373 .Sh CODE SET INDEPENDENCE
117 374 Enabled.
118 375 .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 376 .Nm Committed .
127 377 .Sh SEE ALSO
128 378 .Xr apropos 1 ,
129 -.Xr intro 1 ,
379 +.Xr cat 1 ,
380 +.Xr col 1 ,
130 381 .Xr mandoc 1 ,
382 +.Xr more 1 ,
131 383 .Xr whatis 1 ,
384 +.Xr environ 5 ,
132 385 .Xr man 5 ,
133 -.Xr mdoc 5 ,
134 -.Xr standards 5
386 +.Xr mdoc 5
135 387 .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.
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.
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX