Annotation of src/usr.bin/man/man.1, Revision 1.37
1.37 ! sobrado 1: .\" $OpenBSD: man.1,v 1.36 2007/06/01 06:27:57 jmc Exp $
1.3 deraadt 2: .\"
1.1 deraadt 3: .\" Copyright (c) 1989, 1990, 1993
4: .\" The Regents of the University of California. All rights reserved.
5: .\"
6: .\" Redistribution and use in source and binary forms, with or without
7: .\" modification, are permitted provided that the following conditions
8: .\" are met:
9: .\" 1. Redistributions of source code must retain the above copyright
10: .\" notice, this list of conditions and the following disclaimer.
11: .\" 2. Redistributions in binary form must reproduce the above copyright
12: .\" notice, this list of conditions and the following disclaimer in the
13: .\" documentation and/or other materials provided with the distribution.
1.18 millert 14: .\" 3. Neither the name of the University nor the names of its contributors
1.1 deraadt 15: .\" may be used to endorse or promote products derived from this software
16: .\" without specific prior written permission.
17: .\"
18: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28: .\" SUCH DAMAGE.
29: .\"
30: .\" @(#)man.1 8.2 (Berkeley) 1/2/94
31: .\"
1.37 ! sobrado 32: .Dd $Mdocdate: June 1 2007 $
1.1 deraadt 33: .Dt MAN 1
1.4 millert 34: .Os
1.1 deraadt 35: .Sh NAME
36: .Nm man
37: .Nd display the on-line manual pages
38: .Sh SYNOPSIS
39: .Nm man
40: .Op Fl achw
41: .Op Fl C Ar file
42: .Op Fl M Ar path
43: .Op Fl m Ar path
1.21 jmc 44: .Op Fl S Ar subsection
1.4 millert 45: .Op Fl s Ar section
1.1 deraadt 46: .Op Ar section
1.37 ! sobrado 47: .Ar name ...
1.5 art 48: .Nm man
1.21 jmc 49: .Fl f Ar command
50: .Nm man
1.5 art 51: .Fl k Ar keyword
1.1 deraadt 52: .Sh DESCRIPTION
53: The
1.9 aaron 54: .Nm
1.1 deraadt 55: utility
56: displays the
57: .Bx
58: manual pages entitled
59: .Ar name .
1.33 jmc 60: Pages may be selected according to
61: a specific category
62: .Pq Ar section
63: or
64: machine architecture
65: .Pq Ar subsection .
1.1 deraadt 66: .Pp
67: The options are as follows:
1.13 aaron 68: .Bl -tag -width Ds
1.21 jmc 69: .It Fl a
70: Display all of the manual pages for a specified
71: .Ar section
72: and
73: .Ar name
74: combination.
1.29 jmc 75: Normally, only the first manual page found is displayed.
1.21 jmc 76: .It Fl C Ar file
77: Use the specified
78: .Ar file
79: instead of the default configuration file.
80: This permits users to configure their own manual environment.
81: See
82: .Xr man.conf 5
83: for a description of the contents of this file.
84: .It Fl c
85: Copy the manual page to the standard output instead of using
86: .Xr more 1
87: to paginate it.
88: This is done by default if the standard output is not a terminal device.
89: .It Fl f Ar command
1.30 jmc 90: A synonym for
91: .Xr whatis 1 .
92: It looks up a given command and
93: gives the header line from the manual page.
1.21 jmc 94: .It Fl h
95: Display only the
96: .Dq SYNOPSIS
97: lines of the requested manual pages.
98: .It Fl k Ar keyword
1.30 jmc 99: A synonym for
100: .Xr apropos 1 .
101: It shows which manual pages contain instances of any of the given
102: keywords in their title line.
1.7 deraadt 103: .Ar keyword
1.30 jmc 104: is case insensitive.
1.7 deraadt 105: .Pp
1.30 jmc 106: For instance,
107: to list all man pages which contain
1.27 jmc 108: .Dq mount
1.7 deraadt 109: in the
1.21 jmc 110: .Dq NAME
1.30 jmc 111: line of the man page:
112: .Pp
113: .Dl $ man -k mount
114: .Pp
115: Which would produce a list much like this:
1.19 jmc 116: .Bd -literal
1.27 jmc 117: amd (8) \(en automatically mount file systems
118: amq (8) \(en automounter query tool
119: domountroothooks (9) \(en run all mountroot hooks
120: exports (5) \(en define remote mount points for NFS mount requests
121: getfsstat (2) \(en get list of all mounted file systems
122: getmntinfo (3) \(en get information about mounted file systems
123: mount (8) \(en mount file systems
124: mount, unmount (2) \(en mount or dismount a filesystem
125: mount_cd9660 (8) \(en mount an ISO-9660 filesystem
126: mount_ext2fs (8) \(en mount an ext2fs file system
127: mount_ffs (8) \(en mount a Berkeley Fast File System
128: mount_msdos (8) \(en mount an MS-DOS file system
129: mount_nfs (8) \(en mount NFS file systems
130: mount_ntfs (8) \(en mount an NTFS file system
131: mount_portal (8) \(en mount the portal daemon
132: mount_procfs (8) \(en mount the process file system
133: mount_udf (8) \(en mount a UDF filesystem
134: mount_xfs (8) \(en mount the xfs filesystem
135: mountd (8) \(en service remote NFS mount requests
1.11 deraadt 136: \&...
137: .Ed
1.8 aaron 138: .It Fl M Ar path
1.1 deraadt 139: Override the list of standard directories which
1.9 aaron 140: .Nm
1.1 deraadt 141: searches for manual pages.
142: The supplied
143: .Ar path
1.9 aaron 144: must be a colon
145: .Pq Ql \&:
146: separated list of directories.
1.1 deraadt 147: This search path may also be set using the environment variable
148: .Ev MANPATH .
149: The subdirectories to be searched, and their search order,
1.21 jmc 150: are specified by the
1.9 aaron 151: .Dq _subdir
152: line in the
153: .Nm
1.1 deraadt 154: configuration file.
1.8 aaron 155: .It Fl m Ar path
1.1 deraadt 156: Augment the list of standard directories which
1.9 aaron 157: .Nm
1.1 deraadt 158: searches for manual pages.
159: The supplied
160: .Ar path
1.9 aaron 161: must be a colon
162: .Pq Ql \&:
163: separated list of directories.
1.1 deraadt 164: These directories will be searched before the standard directories or
165: the directories specified using the
166: .Fl M
167: option or the
168: .Ev MANPATH
169: environment variable.
170: The subdirectories to be searched, and their search order,
1.21 jmc 171: are specified by the
1.9 aaron 172: .Dq _subdir
173: line in the
174: .Nm
1.1 deraadt 175: configuration file.
1.8 aaron 176: .It Fl S Ar subsection
1.28 jmc 177: Restricts the directories that
178: .Nm
179: will search to those of a specific machine architecture.
1.31 jmc 180: By default manual pages for all architectures are installed.
181: Therefore this option can be used to view pages for one
182: architecture whilst using another.
183: .Pp
1.28 jmc 184: Overrides the
1.4 millert 185: .Ev MACHINE
1.31 jmc 186: environment variable;
187: see also the
1.9 aaron 188: .Sx ENVIRONMENT
189: section below.
1.33 jmc 190: .It Xo
191: .Op Fl s
1.1 deraadt 192: .Ar section
1.33 jmc 193: .Xc
194: Restricts the directories that
1.9 aaron 195: .Nm
1.28 jmc 196: will search to a specific section.
1.19 jmc 197: The currently available sections are:
198: .Pp
1.32 jmc 199: .Bl -tag -width "localXXX" -offset indent -compact
1.19 jmc 200: .It 1
201: General commands
202: .Pq tools and utilities .
203: .It 2
204: System calls and error numbers.
205: .It 3
206: Libraries.
207: .It 3p
208: .Xr perl 1
209: programmer's reference guide.
210: .It 4
211: Device drivers.
212: .It 5
213: File formats.
214: .It 6
215: Games.
216: .It 7
217: Miscellaneous.
218: .It 8
219: System maintenance and operation commands.
220: .It 9
221: Kernel internals.
1.32 jmc 222: .It X11
223: An alias for X11R6.
224: .It X11R6
225: X Window System.
226: .It local
227: Pages located in
228: .Pa /usr/local .
1.19 jmc 229: .El
230: .Pp
1.1 deraadt 231: The
1.9 aaron 232: .Nm
1.28 jmc 233: configuration file,
234: .Xr man.conf 5 ,
1.1 deraadt 235: specifies the possible
236: .Ar section
1.19 jmc 237: values, and their search order.
1.32 jmc 238: Additional sections may be specified.
1.33 jmc 239: .It Fl w
240: List the pathnames of the manual pages which
241: .Nm
242: would display for the specified
243: .Ar section
244: and
245: .Ar name
246: combination.
247: .El
1.22 jmc 248: .Pp
249: Guidelines for
250: .Ox
251: man pages can be found in
252: .Xr mdoc 7 .
253: A full tutorial for writing man pages is provided in
254: .Xr mdoc.samples 7 .
1.1 deraadt 255: .Sh ENVIRONMENT
256: .Bl -tag -width MANPATHX
257: .It Ev MACHINE
258: As some manual pages are intended only for specific architectures,
1.9 aaron 259: .Nm
1.1 deraadt 260: searches any subdirectories,
261: with the same name as the current architecture,
262: in every directory which it searches.
263: Machine specific areas are checked before general areas.
264: The current machine type may be overridden by setting the environment
265: variable
266: .Ev MACHINE
1.28 jmc 267: to the name of a specific architecture,
268: or with the
269: .Fl S
270: option.
1.20 millert 271: .It Ev MANPAGER
272: Any non-null value of the environment variable
273: .Ev MANPAGER
274: will be used instead of the standard pagination program,
275: .Xr more 1 .
1.1 deraadt 276: .It Ev MANPATH
277: The standard search path used by
1.9 aaron 278: .Nm
1.1 deraadt 279: may be overridden by specifying a path in the
280: .Ev MANPATH
281: environment
282: variable.
1.9 aaron 283: The format of the path is a colon
284: .Pq Ql \&:
285: separated list of directories.
1.21 jmc 286: The subdirectories to be searched, as well as their search order,
287: are specified by the
1.9 aaron 288: .Dq _subdir
289: line in the
290: .Nm
1.1 deraadt 291: configuration file.
292: .It Ev PAGER
1.20 millert 293: Specifies the pagination program to use when
294: .Ev MANPAGER
295: is not defined.
1.1 deraadt 296: .El
297: .Sh FILES
298: .Bl -tag -width /etc/man.conf -compact
299: .It Pa /etc/man.conf
1.8 aaron 300: default man configuration file
1.1 deraadt 301: .El
302: .Sh SEE ALSO
303: .Xr apropos 1 ,
1.19 jmc 304: .Xr intro 1 ,
1.1 deraadt 305: .Xr whatis 1 ,
306: .Xr whereis 1 ,
1.19 jmc 307: .Xr intro 2 ,
308: .Xr intro 3 ,
309: .Xr intro 4 ,
310: .Xr intro 5 ,
311: .Xr man.conf 5 ,
312: .Xr intro 6 ,
313: .Xr intro 7 ,
1.22 jmc 314: .Xr mdoc 7 ,
315: .Xr mdoc.samples 7 ,
1.19 jmc 316: .Xr intro 8 ,
317: .Xr intro 9
1.34 jmc 318: .Sh STANDARDS
319: The
320: .Nm
321: utility is compliant with the
322: .St -p1003.1-2004
323: specification.
324: .Pp
325: The flags
326: .Op Fl aCcfhMmSsw
327: are extensions to that specification.
1.1 deraadt 328: .Sh HISTORY
329: A
330: .Nm
331: command appeared in
1.17 mickey 332: .At v3 .
1.14 aaron 333: .Sh BUGS
334: The on-line manual pages are, by necessity, forgiving toward stupid
335: display devices, causing a few manual pages to be not as nicely formatted
336: as their typeset counterparts.