Annotation of src/usr.bin/man/man.1, Revision 1.22
1.22 ! jmc 1: .\" $OpenBSD: man.1,v 1.21 2004/02/23 14:14:14 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.4 millert 32: .Dd March 9, 1998
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.8 aaron 47: .Ar name Op Ar ...
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 .
60: .Pp
61: The options are as follows:
1.13 aaron 62: .Bl -tag -width Ds
1.21 jmc 63: .It Fl a
64: Display all of the manual pages for a specified
65: .Ar section
66: and
67: .Ar name
68: combination.
69: (Normally, only the first manual page found is displayed.)
70: .It Fl C Ar file
71: Use the specified
72: .Ar file
73: instead of the default configuration file.
74: This permits users to configure their own manual environment.
75: See
76: .Xr man.conf 5
77: for a description of the contents of this file.
78: .It Fl c
79: Copy the manual page to the standard output instead of using
80: .Xr more 1
81: to paginate it.
82: This is done by default if the standard output is not a terminal device.
83: .It Fl f Ar command
84: Locate man pages matching the
85: .Ar command
86: in much the same way
87: .Xr whatis 1
88: works.
89: .It Fl h
90: Display only the
91: .Dq SYNOPSIS
92: lines of the requested manual pages.
93: .It Fl k Ar keyword
1.8 aaron 94: Locate man pages matching
1.7 deraadt 95: .Ar keyword
96: in much the same way as
97: .Xr apropos 1
98: works (in fact, it runs
1.21 jmc 99: .Xr apropos 1 ) .
1.7 deraadt 100: This can be used to find which man page applies to a particular subsystem
1.21 jmc 101: you are interested in.
102: For instance:
1.7 deraadt 103: .Pp
1.21 jmc 104: .Dl $ man -k mount
1.7 deraadt 105: .Pp
1.21 jmc 106: will list all man pages which contain
1.7 deraadt 107: .Ar keyword
108: in the
1.21 jmc 109: .Dq NAME
1.11 deraadt 110: line of the man page;
111: in this case a list much like this:
1.19 jmc 112: .Bd -literal
113: amd (8) \- automatically mount file systems
114: amq (8) \- automounter query tool
115: mount (8) \- mount file systems
116: mount, unmount (2) \- mount or dismount a filesystem
117: mount_ados (8) \- mount an AmigaDOS file system
118: mount_cd9660 (8) \- mount an ISO-9660 filesystem
119: mount_ext2fs (8) \- mount a ext2fs file system
120: mount_fdesc (8) \- mount the file-descriptor file system
121: mount_ffs, mount_ufs (8) \- mount a Berkeley Fast File System
122: mount_kernfs (8) \- mount the /kern file system
123: mount_procfs (8) \- mount the process file system
124: mount_umap (8) \- sample file system layer
125: mount_union (8) \- mount union filesystems
126: mount_xfs (8) \- mount the xfs filesystem
127: mountd (8) \- service remote NFS mount requests
128: newfs, mount_mfs (8) \- construct a new file system
129: umount (8) \- unmount file systems
1.11 deraadt 130: \&...
131: .Ed
1.8 aaron 132: .It Fl M Ar path
1.1 deraadt 133: Override the list of standard directories which
1.9 aaron 134: .Nm
1.1 deraadt 135: searches for manual pages.
136: The supplied
137: .Ar path
1.9 aaron 138: must be a colon
139: .Pq Ql \&:
140: separated list of directories.
1.1 deraadt 141: This search path may also be set using the environment variable
142: .Ev MANPATH .
143: The subdirectories to be searched, and their search order,
1.21 jmc 144: are specified by the
1.9 aaron 145: .Dq _subdir
146: line in the
147: .Nm
1.1 deraadt 148: configuration file.
1.8 aaron 149: .It Fl m Ar path
1.1 deraadt 150: Augment the list of standard directories which
1.9 aaron 151: .Nm
1.1 deraadt 152: searches for manual pages.
153: The supplied
154: .Ar path
1.9 aaron 155: must be a colon
156: .Pq Ql \&:
157: separated list of directories.
1.1 deraadt 158: These directories will be searched before the standard directories or
159: the directories specified using the
160: .Fl M
161: option or the
162: .Ev MANPATH
163: environment variable.
164: The subdirectories to be searched, and their search order,
1.21 jmc 165: are specified by the
1.9 aaron 166: .Dq _subdir
167: line in the
168: .Nm
1.1 deraadt 169: configuration file.
1.8 aaron 170: .It Fl S Ar subsection
1.12 aaron 171: Specifies the machine-dependent subsection.
172: This overrides the
1.4 millert 173: .Ev MACHINE
1.12 aaron 174: environment variable.
175: See the
1.9 aaron 176: .Sx ENVIRONMENT
177: section below.
1.21 jmc 178: .It Fl s Ar section
179: Another way of specifying the section, for compatibility with
180: .Nm
181: on other operating systems.
1.1 deraadt 182: .It Fl w
183: List the pathnames of the manual pages which
1.9 aaron 184: .Nm
1.1 deraadt 185: would display for the specified
186: .Ar section
187: and
188: .Ar name
189: combination.
190: .El
191: .Pp
192: The optional
193: .Ar section
194: argument restricts the directories that
1.9 aaron 195: .Nm
1.1 deraadt 196: will search.
1.19 jmc 197: The currently available sections are:
198: .Pp
199: .Bl -tag -width "3p " -offset indent -compact
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.
222: .El
223: .Pp
1.1 deraadt 224: The
1.9 aaron 225: .Nm
1.1 deraadt 226: configuration file (see
227: .Xr man.conf 5 )
228: specifies the possible
229: .Ar section
1.19 jmc 230: values, and their search order.
1.21 jmc 231: If only a single argument is specified, or if the first argument is
1.1 deraadt 232: not a valid section,
1.9 aaron 233: .Nm
1.1 deraadt 234: assumes that the argument is the name of a manual page to be displayed.
1.22 ! jmc 235: .Pp
! 236: Guidelines for
! 237: .Ox
! 238: man pages can be found in
! 239: .Xr mdoc 7 .
! 240: A full tutorial for writing man pages is provided in
! 241: .Xr mdoc.samples 7 .
1.1 deraadt 242: .Sh ENVIRONMENT
243: .Bl -tag -width MANPATHX
244: .It Ev MACHINE
245: As some manual pages are intended only for specific architectures,
1.9 aaron 246: .Nm
1.1 deraadt 247: searches any subdirectories,
248: with the same name as the current architecture,
249: in every directory which it searches.
250: Machine specific areas are checked before general areas.
251: The current machine type may be overridden by setting the environment
252: variable
253: .Ev MACHINE
254: to the name of a specific architecture.
1.20 millert 255: .It Ev MANPAGER
256: Any non-null value of the environment variable
257: .Ev MANPAGER
258: will be used instead of the standard pagination program,
259: .Xr more 1 .
1.1 deraadt 260: .It Ev MANPATH
261: The standard search path used by
1.9 aaron 262: .Nm
1.1 deraadt 263: may be overridden by specifying a path in the
264: .Ev MANPATH
265: environment
266: variable.
1.9 aaron 267: The format of the path is a colon
268: .Pq Ql \&:
269: separated list of directories.
1.21 jmc 270: The subdirectories to be searched, as well as their search order,
271: are specified by the
1.9 aaron 272: .Dq _subdir
273: line in the
274: .Nm
1.1 deraadt 275: configuration file.
276: .It Ev PAGER
1.20 millert 277: Specifies the pagination program to use when
278: .Ev MANPAGER
279: is not defined.
1.1 deraadt 280: .El
281: .Sh FILES
282: .Bl -tag -width /etc/man.conf -compact
283: .It Pa /etc/man.conf
1.8 aaron 284: default man configuration file
1.1 deraadt 285: .El
286: .Sh SEE ALSO
287: .Xr apropos 1 ,
1.19 jmc 288: .Xr intro 1 ,
1.1 deraadt 289: .Xr whatis 1 ,
290: .Xr whereis 1 ,
1.19 jmc 291: .Xr intro 2 ,
292: .Xr intro 3 ,
293: .Xr intro 4 ,
294: .Xr intro 5 ,
295: .Xr man.conf 5 ,
296: .Xr intro 6 ,
297: .Xr intro 7 ,
1.22 ! jmc 298: .Xr mdoc 7 ,
! 299: .Xr mdoc.samples 7 ,
1.19 jmc 300: .Xr intro 8 ,
301: .Xr intro 9
1.1 deraadt 302: .Sh HISTORY
303: A
304: .Nm
305: command appeared in
1.17 mickey 306: .At v3 .
1.14 aaron 307: .Sh BUGS
308: The on-line manual pages are, by necessity, forgiving toward stupid
309: display devices, causing a few manual pages to be not as nicely formatted
310: as their typeset counterparts.