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