| blob | 075497acab9dde0fab7b053fdadae3660c11ee17 |
1 .\" $Id: man.1,v 1.29 2017/05/17 23:23:00 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, 2014-2017 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 .\"
34 .Dd $Mdocdate: May 17 2017 $
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 acfhklw
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 Oo Fl s Oc Ar section
48 .Ar name ...
49 .Sh DESCRIPTION
50 The
51 .Nm
52 utility
53 displays the
54 manual pages entitled
55 .Ar name .
56 Pages may be selected according to
57 a specific category
58 .Pq Ar section
59 or
60 machine architecture
61 .Pq Ar subsection .
62 .Pp
63 The options are as follows:
64 .Bl -tag -width Ds
65 .It Fl a
66 Display all matching manual pages.
67 Normally, only the first page found is displayed.
68 .It Fl C Ar file
69 Use the specified
70 .Ar file
71 instead of the default configuration file.
72 This permits users to configure their own manual environment.
73 See
74 .Xr man.conf 5
75 for a description of the contents of this file.
76 .It Fl c
77 Copy the manual page to the standard output instead of using
78 .Xr more 1
79 to paginate it.
80 This is done by default if the standard output is not a terminal device.
81 .It Fl f
82 A synonym for
83 .Xr whatis 1 .
84 It searches for
85 .Ar name
86 in manual page names and displays the header lines from all matching pages.
87 The search is case insensitive and matches whole words only.
88 .It Fl h
89 Display only the SYNOPSIS lines of the requested manual pages.
90 Implies
91 .Fl a
92 and
93 .Fl c .
94 .It Fl k
95 A synonym for
96 .Xr apropos 1 .
97 Instead of
98 .Ar name ,
99 an expression can be provided using the syntax described in the
100 .Xr apropos 1
101 manual.
102 By default, it displays the header lines of all matching pages.
103 .It Fl l
104 A synonym for
105 .Xr mandoc 1
106 .Fl a .
107 The
108 .Ar name
109 arguments are interpreted as filenames.
110 No search is done and
111 .Ar file ,
112 .Ar path ,
113 .Ar section ,
114 .Ar subsection ,
115 and
116 .Fl w
117 are ignored.
118 .It Fl M Ar path
119 Override the list of standard directories which
120 .Nm
121 searches for manual pages.
122 The supplied
123 .Ar path
124 must be a colon
125 .Pq Ql \&:
126 separated list of directories.
127 This search path may also be set using the environment variable
128 .Ev MANPATH .
129 .It Fl m Ar path
130 Augment the list of standard directories which
131 .Nm
132 searches for manual pages.
133 The supplied
134 .Ar path
135 must be a colon
136 .Pq Ql \&:
137 separated list of directories.
138 These directories will be searched before the standard directories or
139 the directories specified using the
140 .Fl M
141 option or the
142 .Ev MANPATH
143 environment variable.
144 .It Fl S Ar subsection
145 Only show pages for the specified
146 .Xr machine 1
147 architecture.
148 .Ar subsection
149 is case insensitive.
150 .Pp
151 By default manual pages for all architectures are installed.
152 Therefore this option can be used to view pages for one
153 architecture whilst using another.
154 .Pp
155 This option overrides the
156 .Ev MACHINE
157 environment variable.
158 .It Oo Fl s Oc Ar section
159 Only select manuals from the specified
160 .Ar section .
161 The currently available sections are:
162 .Pp
163 .Bl -tag -width "localXXX" -offset indent -compact
164 .It 1
165 General commands
166 .Pq tools and utilities .
167 .It 2
168 System calls and error numbers.
169 .It 3
170 Library functions.
171 .It 3p
172 .Xr perl 1
173 programmer's reference guide.
174 .It 4
175 Device drivers.
176 .It 5
177 File formats.
178 .It 6
179 Games.
180 .It 7
181 Miscellaneous information.
182 .It 8
183 System maintenance and operation commands.
184 .It 9
185 Kernel internals.
186 .El
187 .Pp
188 If not specified and a match is found in more than one section,
189 the first match is selected from the following list:
190 1, 8, 6, 2, 3, 5, 7, 4, 9, 3p.
191 .It Fl w
192 List the pathnames of all matching manual pages instead of displaying
193 any of them.
194 .El
195 .Pp
196 The options
197 .Fl IKOTW
198 are also supported and are documented in
199 .Xr mandoc 1 .
200 The options
201 .Fl fkl
202 are mutually exclusive and override each other.
203 .Pp
204 Guidelines for writing
205 man pages can be found in
206 .Xr mdoc 7 .
207 .Pp
208 If both a formatted and an unformatted version of the same manual page,
209 for example
210 .Pa cat1/foo.0
211 and
212 .Pa man1/foo.1 ,
213 exist in the same directory, only the unformatted version is used.
214 .Sh ENVIRONMENT
215 .Bl -tag -width MANPATHX
216 .It Ev MACHINE
217 As some manual pages are intended only for specific architectures,
218 .Nm
219 searches any subdirectories,
220 with the same name as the current architecture,
221 in every directory which it searches.
222 Machine specific areas are checked before general areas.
223 The current machine type may be overridden by setting the environment
224 variable
225 .Ev MACHINE
226 to the name of a specific architecture,
227 or with the
228 .Fl S
229 option.
230 .Ev MACHINE
231 is case insensitive.
232 .It Ev MANPAGER
233 Any non-empty value of the environment variable
234 .Ev MANPAGER
235 is used instead of the standard pagination program,
236 .Xr more 1 .
237 If
238 .Xr less 1
239 is used, the interactive
240 .Ic :t
241 command can be used to go to the definitions of various terms, for
242 example command line options, command modifiers, internal commands,
243 environment variables, function names, preprocessor macros,
244 .Xr errno 2
245 values, and some other emphasized words.
246 Some terms may have defining text at more than one place.
247 In that case, the
248 .Xr less 1
249 interactive commands
250 .Ic t
251 and
252 .Ic T
253 can be used to move to the next and to the previous place providing
254 information about the term last searched for with
255 .Ic :t .
256 .It Ev MANPATH
257 The standard search path used by
258 .Nm
259 may be changed by specifying a path in the
260 .Ev MANPATH
261 environment variable.
262 The format of the path is a colon
263 .Pq Ql \&:
264 separated list of directories.
265 Invalid paths are ignored.
266 Overridden by
267 .Fl M ,
268 ignored if
269 .Fl l
270 is specified.
271 .Pp
272 If
273 .Ev MANPATH
274 begins with a colon, it is appended to the default list;
275 if it ends with a colon, it is prepended to the default list;
276 or if it contains two adjacent colons,
277 the standard search path is inserted between the colons.
278 If none of these conditions are met, it overrides the
279 standard search path.
280 .It Ev PAGER
281 Specifies the pagination program to use when
282 .Ev MANPAGER
283 is not defined.
284 If neither PAGER nor MANPAGER is defined,
285 .Xr more 1
286 .Fl s
287 is used.
288 Only used if
289 .Fl a
290 or
291 .Fl l
292 is specified.
293 .El
294 .Sh FILES
295 .Bl -tag -width /etc/man.conf -compact
296 .It Pa /etc/man.conf
297 default man configuration file
298 .El
299 .Sh EXIT STATUS
300 .Ex -std man
301 See
302 .Xr mandoc 1
303 for details.
304 .Sh SEE ALSO
305 .Xr apropos 1 ,
306 .Xr intro 1 ,
307 .Xr whereis 1 ,
308 .Xr intro 2 ,
309 .Xr intro 3 ,
310 .Xr intro 4 ,
311 .Xr intro 5 ,
312 .Xr man.conf 5 ,
313 .Xr intro 6 ,
314 .Xr intro 7 ,
315 .Xr mdoc 7 ,
316 .Xr intro 8 ,
317 .Xr intro 9
318 .Sh STANDARDS
319 The
320 .Nm
321 utility is compliant with the
322 .St -p1003.1-2008
323 specification.
324 .Pp
325 The flags
326 .Op Fl aCcfhIKlMmOSsTWw ,
327 as well as the environment variables
328 .Ev MACHINE ,
329 .Ev MANPAGER ,
330 and
331 .Ev MANPATH ,
332 are extensions to that specification.
333 .Sh HISTORY
334 A
335 .Nm
336 command first appeared in
337 .At v3 .
338 .Pp
339 The
340 .Fl w
341 option first appeared in
342 .At v7 ;
343 .Fl f
344 and
345 .Fl k
346 in
347 .Bx 4 ;
348 .Fl M
349 in
350 .Bx 4.3 ;
351 .Fl a
352 in
353 .Bx 4.3 Tahoe ;
354 .Fl c
355 and
356 .Fl m
357 in
358 .Bx 4.3 Reno ;
359 .Fl h
360 in
361 .Bx 4.3 Net/2 ;
362 .Fl C
363 in
364 .Nx 1.0 ;
365 .Fl s
366 and
367 .Fl S
368 in
369 .Ox 2.3 ;
370 and
371 .Fl I ,
372 .Fl K ,
373 .Fl l ,
374 .Fl O ,
375 and
376 .Fl W
377 in
378 .Ox 5.7 .
379 The
380 .Fl T
381 option first appeared in
382 .At III
383 and was also added in
384 .Ox 5.7 .