1.\" $Id: man.1,v 1.7 2014/11/11 02:43:41 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>
6.\" Copyright (c) 2010, 2011 Ingo Schwarze
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 $
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
43.Op Fl C Ar file
44.Op Fl M Ar path
45.Op Fl m Ar path
46.Op Fl S Ar subsection
47.Op Fl s Ar section
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.
98.It Fl h
99Display only the SYNOPSIS lines of the requested manual pages.
100Implies
101.Fl a
102and
103.Fl c .
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.
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.
245.It Fl V
246Print version and exit.
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
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
358.Op Fl aCcfhMmSsw ,
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 .
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
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 $
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
43.Op Fl C Ar file
44.Op Fl M Ar path
45.Op Fl m Ar path
46.Op Fl S Ar subsection
47.Op Fl s Ar section
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.
98.It Fl h
99Display only the SYNOPSIS lines of the requested manual pages.
100Implies
101.Fl a
102and
103.Fl c .
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.
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.
245.It Fl V
246Print version and exit.
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
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
358.Op Fl aCcfhMmSsw ,
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 .