Annotation of src/usr.bin/man/man.1, Revision 1.31
1.31 ! jmc 1: .\" $OpenBSD: man.1,v 1.30 2007/05/23 20:03:40 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.28 jmc 32: .Dd May 19, 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.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.
1.29 jmc 69: Normally, only the first manual page found is displayed.
1.21 jmc 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
1.30 jmc 84: A synonym for
85: .Xr whatis 1 .
86: It looks up a given command and
87: gives the header line from the manual page.
1.21 jmc 88: .It Fl h
89: Display only the
90: .Dq SYNOPSIS
91: lines of the requested manual pages.
92: .It Fl k Ar keyword
1.30 jmc 93: A synonym for
94: .Xr apropos 1 .
95: It shows which manual pages contain instances of any of the given
96: keywords in their title line.
1.7 deraadt 97: .Ar keyword
1.30 jmc 98: is case insensitive.
1.7 deraadt 99: .Pp
1.30 jmc 100: For instance,
101: to list all man pages which contain
1.27 jmc 102: .Dq mount
1.7 deraadt 103: in the
1.21 jmc 104: .Dq NAME
1.30 jmc 105: line of the man page:
106: .Pp
107: .Dl $ man -k mount
108: .Pp
109: Which would produce a list much like this:
1.19 jmc 110: .Bd -literal
1.27 jmc 111: amd (8) \(en automatically mount file systems
112: amq (8) \(en automounter query tool
113: domountroothooks (9) \(en run all mountroot hooks
114: exports (5) \(en define remote mount points for NFS mount requests
115: getfsstat (2) \(en get list of all mounted file systems
116: getmntinfo (3) \(en get information about mounted file systems
117: mount (8) \(en mount file systems
118: mount, unmount (2) \(en mount or dismount a filesystem
119: mount_ados (8) \(en mount an AmigaDOS file system
120: mount_cd9660 (8) \(en mount an ISO-9660 filesystem
121: mount_ext2fs (8) \(en mount an ext2fs file system
122: mount_ffs (8) \(en mount a Berkeley Fast File System
123: mount_msdos (8) \(en mount an MS-DOS file system
124: mount_nfs (8) \(en mount NFS file systems
125: mount_ntfs (8) \(en mount an NTFS file system
126: mount_portal (8) \(en mount the portal daemon
127: mount_procfs (8) \(en mount the process file system
128: mount_udf (8) \(en mount a UDF filesystem
129: mount_xfs (8) \(en mount the xfs filesystem
130: mountd (8) \(en service remote NFS mount requests
1.11 deraadt 131: \&...
132: .Ed
1.8 aaron 133: .It Fl M Ar path
1.1 deraadt 134: Override the list of standard directories which
1.9 aaron 135: .Nm
1.1 deraadt 136: searches for manual pages.
137: The supplied
138: .Ar path
1.9 aaron 139: must be a colon
140: .Pq Ql \&:
141: separated list of directories.
1.1 deraadt 142: This search path may also be set using the environment variable
143: .Ev MANPATH .
144: The subdirectories to be searched, and their search order,
1.21 jmc 145: are specified by the
1.9 aaron 146: .Dq _subdir
147: line in the
148: .Nm
1.1 deraadt 149: configuration file.
1.8 aaron 150: .It Fl m Ar path
1.1 deraadt 151: Augment the list of standard directories which
1.9 aaron 152: .Nm
1.1 deraadt 153: searches for manual pages.
154: The supplied
155: .Ar path
1.9 aaron 156: must be a colon
157: .Pq Ql \&:
158: separated list of directories.
1.1 deraadt 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: The subdirectories to be searched, and their search order,
1.21 jmc 166: are specified by the
1.9 aaron 167: .Dq _subdir
168: line in the
169: .Nm
1.1 deraadt 170: configuration file.
1.8 aaron 171: .It Fl S Ar subsection
1.28 jmc 172: Restricts the directories that
173: .Nm
174: will search to those of a specific machine architecture.
1.31 ! jmc 175: By default manual pages for all architectures are installed.
! 176: Therefore this option can be used to view pages for one
! 177: architecture whilst using another.
! 178: .Pp
1.28 jmc 179: Overrides the
1.4 millert 180: .Ev MACHINE
1.31 ! jmc 181: environment variable;
! 182: see also the
1.9 aaron 183: .Sx ENVIRONMENT
184: section below.
1.21 jmc 185: .It Fl s Ar section
186: Another way of specifying the section, for compatibility with
187: .Nm
188: on other operating systems.
1.1 deraadt 189: .It Fl w
190: List the pathnames of the manual pages which
1.9 aaron 191: .Nm
1.1 deraadt 192: would display for the specified
193: .Ar section
194: and
195: .Ar name
196: combination.
197: .El
198: .Pp
199: The optional
200: .Ar section
201: argument restricts the directories that
1.9 aaron 202: .Nm
1.28 jmc 203: will search to a specific section.
1.19 jmc 204: The currently available sections are:
205: .Pp
206: .Bl -tag -width "3p " -offset indent -compact
207: .It 1
208: General commands
209: .Pq tools and utilities .
210: .It 2
211: System calls and error numbers.
212: .It 3
213: Libraries.
214: .It 3p
215: .Xr perl 1
216: programmer's reference guide.
217: .It 4
218: Device drivers.
219: .It 5
220: File formats.
221: .It 6
222: Games.
223: .It 7
224: Miscellaneous.
225: .It 8
226: System maintenance and operation commands.
227: .It 9
228: Kernel internals.
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.28 jmc 238: Additional sections may also be specified.
1.22 jmc 239: .Pp
240: Guidelines for
241: .Ox
242: man pages can be found in
243: .Xr mdoc 7 .
244: A full tutorial for writing man pages is provided in
245: .Xr mdoc.samples 7 .
1.1 deraadt 246: .Sh ENVIRONMENT
247: .Bl -tag -width MANPATHX
248: .It Ev MACHINE
249: As some manual pages are intended only for specific architectures,
1.9 aaron 250: .Nm
1.1 deraadt 251: searches any subdirectories,
252: with the same name as the current architecture,
253: in every directory which it searches.
254: Machine specific areas are checked before general areas.
255: The current machine type may be overridden by setting the environment
256: variable
257: .Ev MACHINE
1.28 jmc 258: to the name of a specific architecture,
259: or with the
260: .Fl S
261: option.
1.20 millert 262: .It Ev MANPAGER
263: Any non-null value of the environment variable
264: .Ev MANPAGER
265: will be used instead of the standard pagination program,
266: .Xr more 1 .
1.1 deraadt 267: .It Ev MANPATH
268: The standard search path used by
1.9 aaron 269: .Nm
1.1 deraadt 270: may be overridden by specifying a path in the
271: .Ev MANPATH
272: environment
273: variable.
1.9 aaron 274: The format of the path is a colon
275: .Pq Ql \&:
276: separated list of directories.
1.21 jmc 277: The subdirectories to be searched, as well as their search order,
278: are specified by the
1.9 aaron 279: .Dq _subdir
280: line in the
281: .Nm
1.1 deraadt 282: configuration file.
283: .It Ev PAGER
1.20 millert 284: Specifies the pagination program to use when
285: .Ev MANPAGER
286: is not defined.
1.1 deraadt 287: .El
288: .Sh FILES
289: .Bl -tag -width /etc/man.conf -compact
290: .It Pa /etc/man.conf
1.8 aaron 291: default man configuration file
1.1 deraadt 292: .El
293: .Sh SEE ALSO
294: .Xr apropos 1 ,
1.19 jmc 295: .Xr intro 1 ,
1.1 deraadt 296: .Xr whatis 1 ,
297: .Xr whereis 1 ,
1.19 jmc 298: .Xr intro 2 ,
299: .Xr intro 3 ,
300: .Xr intro 4 ,
301: .Xr intro 5 ,
302: .Xr man.conf 5 ,
303: .Xr intro 6 ,
304: .Xr intro 7 ,
1.22 jmc 305: .Xr mdoc 7 ,
306: .Xr mdoc.samples 7 ,
1.19 jmc 307: .Xr intro 8 ,
308: .Xr intro 9
1.1 deraadt 309: .Sh HISTORY
310: A
311: .Nm
312: command appeared in
1.17 mickey 313: .At v3 .
1.14 aaron 314: .Sh BUGS
315: The on-line manual pages are, by necessity, forgiving toward stupid
316: display devices, causing a few manual pages to be not as nicely formatted
317: as their typeset counterparts.