1.\" $Id: man.1,v 1.7 2014/11/11 02:43:41 schwarze Exp $
| 1.\" $Id: man.1,v 1.13 2015/02/16 16:23:54 schwarze Exp $
|
2.\"
3.\" Copyright (c) 1989, 1990, 1993
4.\" The Regents of the University of California. All rights reserved.
5.\" Copyright (c) 2003, 2007, 2008, 2014 Jason McIntyre <jmc@openbsd.org>
| 2.\"
3.\" Copyright (c) 1989, 1990, 1993
4.\" The Regents of the University of California. All rights reserved.
5.\" Copyright (c) 2003, 2007, 2008, 2014 Jason McIntyre <jmc@openbsd.org>
|
6.\" Copyright (c) 2010, 2011 Ingo Schwarze
| 6.\" Copyright (c) 2010, 2011, 2014, 2015 Ingo Schwarze <schwarze@openbsd.org>
|
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
11.\" 1. Redistributions of source code must retain the above copyright
12.\" notice, this list of conditions and the following disclaimer.
13.\" 2. Redistributions in binary form must reproduce the above copyright
14.\" notice, this list of conditions and the following disclaimer in the
15.\" documentation and/or other materials provided with the distribution.
16.\" 3. Neither the name of the University nor the names of its contributors
17.\" may be used to endorse or promote products derived from this software
18.\" without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\" @(#)man.1 8.2 (Berkeley) 1/2/94
33.\"
| 7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
11.\" 1. Redistributions of source code must retain the above copyright
12.\" notice, this list of conditions and the following disclaimer.
13.\" 2. Redistributions in binary form must reproduce the above copyright
14.\" notice, this list of conditions and the following disclaimer in the
15.\" documentation and/or other materials provided with the distribution.
16.\" 3. Neither the name of the University nor the names of its contributors
17.\" may be used to endorse or promote products derived from this software
18.\" without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\" @(#)man.1 8.2 (Berkeley) 1/2/94
33.\"
|
34.Dd $Mdocdate: November 11 2014 $
| 34.Dd $Mdocdate: February 16 2015 $
|
35.Dt MAN 1
36.Os
37.Sh NAME
38.Nm man
39.Nd display manual pages
40.Sh SYNOPSIS
41.Nm man
| 35.Dt MAN 1
36.Os
37.Sh NAME
38.Nm man
39.Nd display manual pages
40.Sh SYNOPSIS
41.Nm man
|
42.Op Fl acfhklVw
| 42.Op Fl acfhklw
|
43.Op Fl C Ar file
| 43.Op Fl C Ar file
|
| 44.Op Fl I Cm os Ns = Ns Ar name
45.Op Fl K Ar encoding
|
44.Op Fl M Ar path
45.Op Fl m Ar path
| 46.Op Fl M Ar path
47.Op Fl m Ar path
|
| 48.Op Fl O Ar option Ns = Ns Ar value
|
46.Op Fl S Ar subsection
47.Op Fl s Ar section
| 49.Op Fl S Ar subsection
50.Op Fl s Ar section
|
| 51.Op Fl T Ar output
52.Op Fl W Ar level
|
48.Op Ar section
49.Ar name ...
50.Sh DESCRIPTION
51The
52.Nm
53utility
54displays the
55manual pages entitled
56.Ar name .
57Pages may be selected according to
58a specific category
59.Pq Ar section
60or
61machine architecture
62.Pq Ar subsection .
63.Pp
64The options are as follows:
65.Bl -tag -width Ds
66.It Fl a
67Display all of the manual pages for a specified
68.Ar section
69and
70.Ar name
71combination.
72Normally, only the first manual page found is displayed.
73.It Fl C Ar file
74Use the specified
75.Ar file
76instead of the default configuration file.
77This permits users to configure their own manual environment.
78See
79.Xr man.conf 5
80for a description of the contents of this file.
81.It Fl c
82Copy the manual page to the standard output instead of using
83.Xr more 1
84to paginate it.
85This is done by default if the standard output is not a terminal device.
86.It Fl f
87A synonym for
88.Xr whatis 1 .
89It searches for
90.Ar name
91in manual page names and displays the header lines from all matching pages.
92The search is case insensitive and matches whole words only.
93This overrides any earlier
94.Fl k
95and
96.Fl l
97options.
| 53.Op Ar section
54.Ar name ...
55.Sh DESCRIPTION
56The
57.Nm
58utility
59displays the
60manual pages entitled
61.Ar name .
62Pages may be selected according to
63a specific category
64.Pq Ar section
65or
66machine architecture
67.Pq Ar subsection .
68.Pp
69The options are as follows:
70.Bl -tag -width Ds
71.It Fl a
72Display all of the manual pages for a specified
73.Ar section
74and
75.Ar name
76combination.
77Normally, only the first manual page found is displayed.
78.It Fl C Ar file
79Use the specified
80.Ar file
81instead of the default configuration file.
82This permits users to configure their own manual environment.
83See
84.Xr man.conf 5
85for a description of the contents of this file.
86.It Fl c
87Copy the manual page to the standard output instead of using
88.Xr more 1
89to paginate it.
90This is done by default if the standard output is not a terminal device.
91.It Fl f
92A synonym for
93.Xr whatis 1 .
94It searches for
95.Ar name
96in manual page names and displays the header lines from all matching pages.
97The search is case insensitive and matches whole words only.
98This overrides any earlier
99.Fl k
100and
101.Fl l
102options.
|
| 103.It Fl I Cm os Ns = Ns Ar name
104Override the default operating system
105.Ar name
106for the
107.Xr mdoc 7
108.Ic \&Os
109and for the
110.Xr man 7
111.Ic \&TH
112macro.
|
98.It Fl h
99Display only the SYNOPSIS lines of the requested manual pages.
100Implies
101.Fl a
102and
103.Fl c .
| 113.It Fl h
114Display only the SYNOPSIS lines of the requested manual pages.
115Implies
116.Fl a
117and
118.Fl c .
|
| 119.It Fl K Ar encoding
120Specify the input encoding.
121The supported
122.Ar encoding
123arguments are
124.Cm us-ascii ,
125.Cm iso-8859-1 ,
126and
127.Cm utf-8 .
128By default, the encoding is automatically detected as described in the
129.Xr mandoc 1
130manual.
|
104.It Fl k
105A synonym for
106.Xr apropos 1 .
107Instead of
108.Ar name ,
109an expression can be provided using the syntax described in the
110.Xr apropos 1
111manual.
112By default, it displays the header lines of all matching pages.
113This overrides any earlier
114.Fl f
115and
116.Fl l
117options.
118.It Fl l
119A synonym for
120.Xr mandoc 1
121.Fl a .
122The
123.Ar name
124arguments are interpreted as filenames.
125No search is done and
126.Ar file ,
127.Ar path ,
128.Ar section ,
129and
130.Ar subsection
131are ignored.
132This overrides any earlier
133.Fl f ,
134.Fl k ,
135and
136.Fl w
137options.
138.It Fl M Ar path
139Override the list of standard directories which
140.Nm
141searches for manual pages.
142The supplied
143.Ar path
144must be a colon
145.Pq Ql \&:
146separated list of directories.
147This search path may also be set using the environment variable
148.Ev MANPATH .
149The subdirectories to be searched, and their search order,
150are specified by the
151.Dq _subdir
152line in the
153.Nm
154configuration file.
155.It Fl m Ar path
156Augment the list of standard directories which
157.Nm
158searches for manual pages.
159The supplied
160.Ar path
161must be a colon
162.Pq Ql \&:
163separated list of directories.
164These directories will be searched before the standard directories or
165the directories specified using the
166.Fl M
167option or the
168.Ev MANPATH
169environment variable.
170The subdirectories to be searched, and their search order,
171are specified by the
172.Dq _subdir
173line in the
174.Nm
175configuration file.
| 131.It Fl k
132A synonym for
133.Xr apropos 1 .
134Instead of
135.Ar name ,
136an expression can be provided using the syntax described in the
137.Xr apropos 1
138manual.
139By default, it displays the header lines of all matching pages.
140This overrides any earlier
141.Fl f
142and
143.Fl l
144options.
145.It Fl l
146A synonym for
147.Xr mandoc 1
148.Fl a .
149The
150.Ar name
151arguments are interpreted as filenames.
152No search is done and
153.Ar file ,
154.Ar path ,
155.Ar section ,
156and
157.Ar subsection
158are ignored.
159This overrides any earlier
160.Fl f ,
161.Fl k ,
162and
163.Fl w
164options.
165.It Fl M Ar path
166Override the list of standard directories which
167.Nm
168searches for manual pages.
169The supplied
170.Ar path
171must be a colon
172.Pq Ql \&:
173separated list of directories.
174This search path may also be set using the environment variable
175.Ev MANPATH .
176The subdirectories to be searched, and their search order,
177are specified by the
178.Dq _subdir
179line in the
180.Nm
181configuration file.
182.It Fl m Ar path
183Augment the list of standard directories which
184.Nm
185searches for manual pages.
186The supplied
187.Ar path
188must be a colon
189.Pq Ql \&:
190separated list of directories.
191These directories will be searched before the standard directories or
192the directories specified using the
193.Fl M
194option or the
195.Ev MANPATH
196environment variable.
197The subdirectories to be searched, and their search order,
198are specified by the
199.Dq _subdir
200line in the
201.Nm
202configuration file.
|
| 203.It Fl O Ar option Ns = Ns Ar value
204Comma-separated output options.
205For each output format, the available options are described in the
206.Xr mandoc 1
207manual.
|
176.It Fl S Ar subsection
177Restricts the directories that
178.Nm
179will search to those of a specific
180.Xr machine 1
181architecture.
182.Ar subsection
183is case insensitive.
184.Pp
185By default manual pages for all architectures are installed.
186Therefore this option can be used to view pages for one
187architecture whilst using another.
188.Pp
189This option overrides the
190.Ev MACHINE
191environment variable.
192.It Xo
193.Op Fl s
194.Ar section
195.Xc
196Restricts the directories that
197.Nm
198will search to a specific section.
199The currently available sections are:
200.Pp
201.Bl -tag -width "localXXX" -offset indent -compact
202.It 1
203General commands
204.Pq tools and utilities .
205.It 2
206System calls and error numbers.
207.It 3
208Libraries.
209.It 3f
210Fortran programmer's reference guide.
211.It 3p
212.Xr perl 1
213programmer's reference guide.
214.It 4
215Device drivers.
216.It 5
217File formats.
218.It 6
219Games.
220.It 7
221Miscellaneous.
222.It 8
223System maintenance and operation commands.
224.It 9
225Kernel internals.
226.It X11
227An alias for X11R6.
228.It X11R6
229X Window System.
230.It local
231Pages located in
232.Pa /usr/local .
233.It n
234Tcl/Tk commands.
235.El
236.Pp
237The
238.Nm
239configuration file,
240.Xr man.conf 5 ,
241specifies the possible
242.Ar section
243values, and their search order.
244Additional sections may be specified.
| 208.It Fl S Ar subsection
209Restricts the directories that
210.Nm
211will search to those of a specific
212.Xr machine 1
213architecture.
214.Ar subsection
215is case insensitive.
216.Pp
217By default manual pages for all architectures are installed.
218Therefore this option can be used to view pages for one
219architecture whilst using another.
220.Pp
221This option overrides the
222.Ev MACHINE
223environment variable.
224.It Xo
225.Op Fl s
226.Ar section
227.Xc
228Restricts the directories that
229.Nm
230will search to a specific section.
231The currently available sections are:
232.Pp
233.Bl -tag -width "localXXX" -offset indent -compact
234.It 1
235General commands
236.Pq tools and utilities .
237.It 2
238System calls and error numbers.
239.It 3
240Libraries.
241.It 3f
242Fortran programmer's reference guide.
243.It 3p
244.Xr perl 1
245programmer's reference guide.
246.It 4
247Device drivers.
248.It 5
249File formats.
250.It 6
251Games.
252.It 7
253Miscellaneous.
254.It 8
255System maintenance and operation commands.
256.It 9
257Kernel internals.
258.It X11
259An alias for X11R6.
260.It X11R6
261X Window System.
262.It local
263Pages located in
264.Pa /usr/local .
265.It n
266Tcl/Tk commands.
267.El
268.Pp
269The
270.Nm
271configuration file,
272.Xr man.conf 5 ,
273specifies the possible
274.Ar section
275values, and their search order.
276Additional sections may be specified.
|
245.It Fl V
246Print version and exit.
| 277.It Fl T Ar output
278Select the output format.
279The default is
280.Cm locale .
281The other output modes
282.Cm ascii ,
283.Cm html ,
284.Cm lint ,
285.Cm man ,
286.Cm pdf ,
287.Cm ps ,
288.Cm tree ,
289and
290.Cm utf8
291are described in the
292.Xr mandoc 1
293manual.
294.It Fl W Ar level
295Specify the minimum message
296.Ar level
297to be reported on the standard error output and to affect the exit status.
298The
299.Ar level
300can be
301.Cm warning ,
302.Cm error ,
303or
304.Cm unsupp ;
305.Cm all
306is an alias for
307.Cm warning .
308By default,
309.Nm
310is silent.
311See the
312.Xr mandoc 1
313manual for details.
|
247.It Fl w
248List the pathnames of the manual pages which
249.Nm
250would display for the specified
251.Ar section
252and
253.Ar name
254combination.
255.El
256.Pp
| 314.It Fl w
315List the pathnames of the manual pages which
316.Nm
317would display for the specified
318.Ar section
319and
320.Ar name
321combination.
322.El
323.Pp
|
257The
258.Nm
259utility also supports the options
260.Fl IKOTW
261described in the
262.Xr mandoc 1
263manual.
264.Pp
| |
265Guidelines for writing
266man pages can be found in
267.Xr mdoc 7 .
268.Pp
269If both a formatted and an unformatted version of the same manual page,
270for example
271.Pa cat1/foo.0
272and
273.Pa man1/foo.1 ,
274exist in the same directory, and at least one of them is selected,
275only the newer one is used.
276However, if both the
277.Fl a
278and the
279.Fl w
280options are specified, both file names are printed.
281.Sh ENVIRONMENT
282.Bl -tag -width MANPATHX
283.It Ev MACHINE
284As some manual pages are intended only for specific architectures,
285.Nm
286searches any subdirectories,
287with the same name as the current architecture,
288in every directory which it searches.
289Machine specific areas are checked before general areas.
290The current machine type may be overridden by setting the environment
291variable
292.Ev MACHINE
293to the name of a specific architecture,
294or with the
295.Fl S
296option.
297.Ev MACHINE
298is case insensitive.
299.It Ev MANPAGER
300Any non-empty value of the environment variable
301.Ev MANPAGER
302will be used instead of the standard pagination program,
303.Xr more 1 .
304.It Ev MANPATH
305The standard search path used by
306.Nm
307may be overridden by specifying a path in the
308.Ev MANPATH
309environment
310variable.
311The format of the path is a colon
312.Pq Ql \&:
313separated list of directories.
314The subdirectories to be searched, as well as their search order,
315are specified by the
316.Dq _subdir
317line in the
318.Nm
319configuration file.
320.It Ev PAGER
321Specifies the pagination program to use when
322.Ev MANPAGER
323is not defined.
324If neither PAGER nor MANPAGER is defined,
325.Pa /usr/bin/more Fl s
326will be used.
327.El
328.Sh FILES
329.Bl -tag -width /etc/man.conf -compact
330.It Pa /etc/man.conf
331default man configuration file
332.El
333.Sh EXIT STATUS
334.Ex -std man
335.Sh SEE ALSO
336.Xr apropos 1 ,
337.Xr intro 1 ,
338.Xr whatis 1 ,
339.Xr whereis 1 ,
340.Xr intro 2 ,
341.Xr intro 3 ,
342.Xr intro 4 ,
343.Xr intro 5 ,
344.Xr man.conf 5 ,
345.Xr intro 6 ,
346.Xr intro 7 ,
347.Xr mdoc 7 ,
348.Xr intro 8 ,
349.Xr intro 9
350.Sh STANDARDS
351The
352.Nm
353utility is compliant with the
354.St -p1003.1-2008
355specification.
356.Pp
357The flags
| 324Guidelines for writing
325man pages can be found in
326.Xr mdoc 7 .
327.Pp
328If both a formatted and an unformatted version of the same manual page,
329for example
330.Pa cat1/foo.0
331and
332.Pa man1/foo.1 ,
333exist in the same directory, and at least one of them is selected,
334only the newer one is used.
335However, if both the
336.Fl a
337and the
338.Fl w
339options are specified, both file names are printed.
340.Sh ENVIRONMENT
341.Bl -tag -width MANPATHX
342.It Ev MACHINE
343As some manual pages are intended only for specific architectures,
344.Nm
345searches any subdirectories,
346with the same name as the current architecture,
347in every directory which it searches.
348Machine specific areas are checked before general areas.
349The current machine type may be overridden by setting the environment
350variable
351.Ev MACHINE
352to the name of a specific architecture,
353or with the
354.Fl S
355option.
356.Ev MACHINE
357is case insensitive.
358.It Ev MANPAGER
359Any non-empty value of the environment variable
360.Ev MANPAGER
361will be used instead of the standard pagination program,
362.Xr more 1 .
363.It Ev MANPATH
364The standard search path used by
365.Nm
366may be overridden by specifying a path in the
367.Ev MANPATH
368environment
369variable.
370The format of the path is a colon
371.Pq Ql \&:
372separated list of directories.
373The subdirectories to be searched, as well as their search order,
374are specified by the
375.Dq _subdir
376line in the
377.Nm
378configuration file.
379.It Ev PAGER
380Specifies the pagination program to use when
381.Ev MANPAGER
382is not defined.
383If neither PAGER nor MANPAGER is defined,
384.Pa /usr/bin/more Fl s
385will be used.
386.El
387.Sh FILES
388.Bl -tag -width /etc/man.conf -compact
389.It Pa /etc/man.conf
390default man configuration file
391.El
392.Sh EXIT STATUS
393.Ex -std man
394.Sh SEE ALSO
395.Xr apropos 1 ,
396.Xr intro 1 ,
397.Xr whatis 1 ,
398.Xr whereis 1 ,
399.Xr intro 2 ,
400.Xr intro 3 ,
401.Xr intro 4 ,
402.Xr intro 5 ,
403.Xr man.conf 5 ,
404.Xr intro 6 ,
405.Xr intro 7 ,
406.Xr mdoc 7 ,
407.Xr intro 8 ,
408.Xr intro 9
409.Sh STANDARDS
410The
411.Nm
412utility is compliant with the
413.St -p1003.1-2008
414specification.
415.Pp
416The flags
|
358.Op Fl aCcfhMmSsw ,
| 417.Op Fl aCcfhIKlMmOSsTWw ,
|
359as well as the environment variables
360.Ev MACHINE ,
361.Ev MANPAGER ,
362and
363.Ev MANPATH ,
364are extensions to that specification.
365.Sh HISTORY
366A
367.Nm
368command first appeared in
369.At v3 .
370.Pp
371The
372.Fl w
373option first appeared in
374.At v7 ;
375.Fl f
376and
377.Fl k
378in
379.Bx 4 ;
380.Fl M
381in
382.Bx 4.3 ;
383.Fl a
384in
385.Bx 4.3 Tahoe ;
386.Fl c
387and
388.Fl m
389in
390.Bx 4.3 Reno ;
391.Fl h
392in
393.Bx 4.3 Net/2 ;
394.Fl C
395in
396.Nx 1.0 ;
397and
398.Fl s
399and
400.Fl S
401in
402.Ox 2.3 .
| 418as well as the environment variables
419.Ev MACHINE ,
420.Ev MANPAGER ,
421and
422.Ev MANPATH ,
423are extensions to that specification.
424.Sh HISTORY
425A
426.Nm
427command first appeared in
428.At v3 .
429.Pp
430The
431.Fl w
432option first appeared in
433.At v7 ;
434.Fl f
435and
436.Fl k
437in
438.Bx 4 ;
439.Fl M
440in
441.Bx 4.3 ;
442.Fl a
443in
444.Bx 4.3 Tahoe ;
445.Fl c
446and
447.Fl m
448in
449.Bx 4.3 Reno ;
450.Fl h
451in
452.Bx 4.3 Net/2 ;
453.Fl C
454in
455.Nx 1.0 ;
456and
457.Fl s
458and
459.Fl S
460in
461.Ox 2.3 .
|