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