Annotation of mandoc/man.1, Revision 1.29
1.29 ! schwarze 1: .\" $Id: man.1,v 1.28 2017/03/27 18:51:36 schwarze Exp $
1.1 schwarze 2: .\"
3: .\" Copyright (c) 1989, 1990, 1993
4: .\" The Regents of the University of California. All rights reserved.
1.2 schwarze 5: .\" Copyright (c) 2003, 2007, 2008, 2014 Jason McIntyre <jmc@openbsd.org>
1.22 schwarze 6: .\" Copyright (c) 2010, 2011, 2014-2017 Ingo Schwarze <schwarze@openbsd.org>
1.1 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: .\"
1.28 schwarze 34: .Dd $Mdocdate: March 27 2017 $
1.1 schwarze 35: .Dt MAN 1
36: .Os
37: .Sh NAME
38: .Nm man
39: .Nd display manual pages
40: .Sh SYNOPSIS
41: .Nm man
1.13 schwarze 42: .Op Fl acfhklw
1.1 schwarze 43: .Op Fl C Ar file
44: .Op Fl M Ar path
45: .Op Fl m Ar path
46: .Op Fl S Ar subsection
1.28 schwarze 47: .Op Oo Fl s Oc Ar section
1.1 schwarze 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
1.18 schwarze 66: Display all matching manual pages.
67: Normally, only the first page found is displayed.
1.1 schwarze 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.
1.2 schwarze 81: .It Fl f
1.1 schwarze 82: A synonym for
83: .Xr whatis 1 .
1.2 schwarze 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.
1.20 schwarze 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 .
1.2 schwarze 94: .It Fl k
1.1 schwarze 95: A synonym for
96: .Xr apropos 1 .
1.2 schwarze 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.
1.4 schwarze 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 ,
1.27 schwarze 114: .Ar subsection ,
1.4 schwarze 115: and
1.27 schwarze 116: .Fl w
1.4 schwarze 117: are ignored.
1.1 schwarze 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
1.25 schwarze 145: Only show pages for the specified
1.1 schwarze 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.
1.17 schwarze 158: .It Oo Fl s Oc Ar section
159: Only select manuals from the specified
160: .Ar section .
1.1 schwarze 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
1.17 schwarze 170: Library functions.
1.1 schwarze 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
1.17 schwarze 181: Miscellaneous information.
1.1 schwarze 182: .It 8
183: System maintenance and operation commands.
184: .It 9
185: Kernel internals.
186: .El
1.22 schwarze 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.
1.1 schwarze 191: .It Fl w
1.25 schwarze 192: List the pathnames of all matching manual pages instead of displaying
193: any of them.
1.1 schwarze 194: .El
1.26 schwarze 195: .Pp
196: The options
197: .Fl IKOTW
198: are also supported and are documented in
199: .Xr mandoc 1 .
1.27 schwarze 200: The options
201: .Fl fkl
202: are mutually exclusive and override each other.
1.1 schwarze 203: .Pp
1.2 schwarze 204: Guidelines for writing
1.1 schwarze 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 ,
1.24 schwarze 213: exist in the same directory, only the unformatted version is used.
1.1 schwarze 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
1.23 schwarze 235: is used instead of the standard pagination program,
1.1 schwarze 236: .Xr more 1 .
1.15 schwarze 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,
1.19 schwarze 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 .
1.1 schwarze 256: .It Ev MANPATH
257: The standard search path used by
258: .Nm
1.23 schwarze 259: may be changed by specifying a path in the
1.1 schwarze 260: .Ev MANPATH
1.23 schwarze 261: environment variable.
1.1 schwarze 262: The format of the path is a colon
263: .Pq Ql \&:
264: separated list of directories.
1.29 ! schwarze 265: Invalid paths are ignored.
1.23 schwarze 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.
1.1 schwarze 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,
1.14 schwarze 285: .Xr more 1
286: .Fl s
1.23 schwarze 287: is used.
288: Only used if
289: .Fl a
290: or
291: .Fl l
292: is specified.
1.1 schwarze 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
1.25 schwarze 301: See
302: .Xr mandoc 1
303: for details.
1.1 schwarze 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
1.13 schwarze 326: .Op Fl aCcfhIKlMmOSsTWw ,
1.1 schwarze 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
1.21 schwarze 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 .
CVSweb