Annotation of src/usr.bin/man/man.1, Revision 1.55
1.55 ! jmc 1: .\" $OpenBSD: man.1,v 1.54 2014/01/21 03:15:46 schwarze 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.55 ! jmc 32: .Dd $Mdocdate: January 21 2014 $
1.1 deraadt 33: .Dt MAN 1
1.4 millert 34: .Os
1.1 deraadt 35: .Sh NAME
36: .Nm man
1.46 jmc 37: .Nd display manual pages
1.1 deraadt 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.39 jmc 49: .Fl f Ar command ...
1.21 jmc 50: .Nm man
1.39 jmc 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.41 jmc 94: .Ar command
95: is case insensitive.
1.21 jmc 96: .It Fl h
97: Display only the
98: .Dq SYNOPSIS
99: lines of the requested manual pages.
100: .It Fl k Ar keyword
1.30 jmc 101: A synonym for
102: .Xr apropos 1 .
103: It shows which manual pages contain instances of any of the given
104: keywords in their title line.
1.7 deraadt 105: .Ar keyword
1.30 jmc 106: is case insensitive.
1.7 deraadt 107: .Pp
1.30 jmc 108: For instance,
109: to list all man pages which contain
1.27 jmc 110: .Dq mount
1.7 deraadt 111: in the
1.21 jmc 112: .Dq NAME
1.30 jmc 113: line of the man page:
114: .Pp
115: .Dl $ man -k mount
116: .Pp
117: Which would produce a list much like this:
1.19 jmc 118: .Bd -literal
1.27 jmc 119: amd (8) \(en automatically mount file systems
120: amq (8) \(en automounter query tool
121: domountroothooks (9) \(en run all mountroot hooks
122: exports (5) \(en define remote mount points for NFS mount requests
123: getfsstat (2) \(en get list of all mounted file systems
124: getmntinfo (3) \(en get information about mounted file systems
125: mount (8) \(en mount file systems
126: mount, unmount (2) \(en mount or dismount a filesystem
127: mount_cd9660 (8) \(en mount an ISO-9660 filesystem
128: mount_ext2fs (8) \(en mount an ext2fs file system
129: mount_ffs (8) \(en mount a Berkeley Fast File System
130: mount_msdos (8) \(en mount an MS-DOS file system
131: mount_nfs (8) \(en mount NFS file systems
132: mount_ntfs (8) \(en mount an NTFS file system
133: mount_procfs (8) \(en mount the process file system
134: mount_udf (8) \(en mount a UDF filesystem
1.48 jmc 135: mount_vnd, vnconfig (8) \(en configure vnode disks
1.27 jmc 136: mountd (8) \(en service remote NFS mount requests
1.11 deraadt 137: \&...
138: .Ed
1.8 aaron 139: .It Fl M Ar path
1.1 deraadt 140: Override the list of standard directories which
1.9 aaron 141: .Nm
1.1 deraadt 142: searches for manual pages.
143: The supplied
144: .Ar path
1.9 aaron 145: must be a colon
146: .Pq Ql \&:
147: separated list of directories.
1.1 deraadt 148: This search path may also be set using the environment variable
149: .Ev MANPATH .
150: The subdirectories to be searched, and their search order,
1.21 jmc 151: are specified by the
1.9 aaron 152: .Dq _subdir
153: line in the
154: .Nm
1.1 deraadt 155: configuration file.
1.8 aaron 156: .It Fl m Ar path
1.1 deraadt 157: Augment the list of standard directories which
1.9 aaron 158: .Nm
1.1 deraadt 159: searches for manual pages.
160: The supplied
161: .Ar path
1.9 aaron 162: must be a colon
163: .Pq Ql \&:
164: separated list of directories.
1.1 deraadt 165: These directories will be searched before the standard directories or
166: the directories specified using the
167: .Fl M
168: option or the
169: .Ev MANPATH
170: environment variable.
171: The subdirectories to be searched, and their search order,
1.21 jmc 172: are specified by the
1.9 aaron 173: .Dq _subdir
174: line in the
175: .Nm
1.1 deraadt 176: configuration file.
1.8 aaron 177: .It Fl S Ar subsection
1.28 jmc 178: Restricts the directories that
179: .Nm
1.41 jmc 180: will search to those of a specific
181: .Xr machine 1
182: architecture.
183: .Ar subsection
184: is case insensitive.
185: .Pp
1.31 jmc 186: By default manual pages for all architectures are installed.
187: Therefore this option can be used to view pages for one
188: architecture whilst using another.
189: .Pp
1.41 jmc 190: This option overrides the
1.4 millert 191: .Ev MACHINE
1.41 jmc 192: environment variable.
1.33 jmc 193: .It Xo
194: .Op Fl s
1.1 deraadt 195: .Ar section
1.33 jmc 196: .Xc
197: Restricts the directories that
1.9 aaron 198: .Nm
1.28 jmc 199: will search to a specific section.
1.19 jmc 200: The currently available sections are:
201: .Pp
1.32 jmc 202: .Bl -tag -width "localXXX" -offset indent -compact
1.19 jmc 203: .It 1
204: General commands
205: .Pq tools and utilities .
206: .It 2
207: System calls and error numbers.
208: .It 3
209: Libraries.
1.38 jmc 210: .It 3f
211: Fortran programmer's reference guide.
1.19 jmc 212: .It 3p
213: .Xr perl 1
214: programmer's reference guide.
215: .It 4
216: Device drivers.
217: .It 5
218: File formats.
219: .It 6
220: Games.
221: .It 7
222: Miscellaneous.
223: .It 8
224: System maintenance and operation commands.
225: .It 9
226: Kernel internals.
1.32 jmc 227: .It X11
228: An alias for X11R6.
229: .It X11R6
230: X Window System.
231: .It local
232: Pages located in
233: .Pa /usr/local .
1.40 deanna 234: .It n
235: Tcl/Tk commands.
1.19 jmc 236: .El
237: .Pp
1.1 deraadt 238: The
1.9 aaron 239: .Nm
1.28 jmc 240: configuration file,
241: .Xr man.conf 5 ,
1.1 deraadt 242: specifies the possible
243: .Ar section
1.19 jmc 244: values, and their search order.
1.32 jmc 245: Additional sections may be specified.
1.33 jmc 246: .It Fl w
247: List the pathnames of the manual pages which
248: .Nm
249: would display for the specified
250: .Ar section
251: and
252: .Ar name
253: combination.
254: .El
1.22 jmc 255: .Pp
256: Guidelines for
257: .Ox
258: man pages can be found in
259: .Xr mdoc 7 .
1.47 schwarze 260: .Pp
261: If both a formatted and an unformatted version of the same manual page,
262: for example
263: .Pa cat1/foo.0
264: and
265: .Pa man1/foo.1 ,
266: exist in the same directory, and at least one of them is selected,
267: only the newer one is used.
268: However, if both the
269: .Fl a
270: and the
271: .Fl w
272: options are specified, both file names are printed.
1.1 deraadt 273: .Sh ENVIRONMENT
274: .Bl -tag -width MANPATHX
275: .It Ev MACHINE
276: As some manual pages are intended only for specific architectures,
1.9 aaron 277: .Nm
1.1 deraadt 278: searches any subdirectories,
279: with the same name as the current architecture,
280: in every directory which it searches.
281: Machine specific areas are checked before general areas.
282: The current machine type may be overridden by setting the environment
283: variable
284: .Ev MACHINE
1.28 jmc 285: to the name of a specific architecture,
286: or with the
287: .Fl S
288: option.
1.41 jmc 289: .Ev MACHINE
290: is case insensitive.
1.20 millert 291: .It Ev MANPAGER
1.53 jca 292: Any non-empty value of the environment variable
1.20 millert 293: .Ev MANPAGER
294: will be used instead of the standard pagination program,
295: .Xr more 1 .
1.1 deraadt 296: .It Ev MANPATH
297: The standard search path used by
1.9 aaron 298: .Nm
1.1 deraadt 299: may be overridden by specifying a path in the
300: .Ev MANPATH
301: environment
302: variable.
1.9 aaron 303: The format of the path is a colon
304: .Pq Ql \&:
305: separated list of directories.
1.21 jmc 306: The subdirectories to be searched, as well as their search order,
307: are specified by the
1.9 aaron 308: .Dq _subdir
309: line in the
310: .Nm
1.1 deraadt 311: configuration file.
312: .It Ev PAGER
1.20 millert 313: Specifies the pagination program to use when
314: .Ev MANPAGER
315: is not defined.
1.53 jca 316: If neither PAGER nor MANPAGER is defined,
1.54 schwarze 317: .Pa /usr/bin/more Fl s
1.53 jca 318: will be used.
1.1 deraadt 319: .El
320: .Sh FILES
321: .Bl -tag -width /etc/man.conf -compact
322: .It Pa /etc/man.conf
1.8 aaron 323: default man configuration file
1.1 deraadt 324: .El
1.45 jmc 325: .Sh EXIT STATUS
326: .Ex -std man
1.1 deraadt 327: .Sh SEE ALSO
328: .Xr apropos 1 ,
1.19 jmc 329: .Xr intro 1 ,
1.1 deraadt 330: .Xr whatis 1 ,
331: .Xr whereis 1 ,
1.19 jmc 332: .Xr intro 2 ,
333: .Xr intro 3 ,
334: .Xr intro 4 ,
335: .Xr intro 5 ,
336: .Xr man.conf 5 ,
337: .Xr intro 6 ,
338: .Xr intro 7 ,
1.22 jmc 339: .Xr mdoc 7 ,
1.19 jmc 340: .Xr intro 8 ,
341: .Xr intro 9
1.34 jmc 342: .Sh STANDARDS
343: The
344: .Nm
345: utility is compliant with the
1.42 jmc 346: .St -p1003.1-2008
1.34 jmc 347: specification.
348: .Pp
349: The flags
1.55 ! jmc 350: .Op Fl aCcfhMmSsw ,
! 351: as well as the environment variables
! 352: .Ev MACHINE ,
! 353: .Ev MANPAGER ,
! 354: and
! 355: .Ev MANPATH ,
1.34 jmc 356: are extensions to that specification.
1.1 deraadt 357: .Sh HISTORY
358: A
359: .Nm
1.50 schwarze 360: command first appeared in
1.17 mickey 361: .At v3 .
1.51 jmc 362: .Pp
1.50 schwarze 363: The
364: .Fl w
365: option first appeared in
366: .At v7 ;
367: .Fl f
368: and
369: .Fl k
370: in
371: .Bx 4 ;
372: .Fl M
373: in
374: .Bx 4.3 ;
375: .Fl a
376: in
377: .Bx 4.3 Tahoe ;
378: .Fl c
379: and
380: .Fl m
381: in
382: .Bx 4.3 Reno ;
383: .Fl h
384: in
385: .Bx 4.3 Net/2 ;
386: .Fl C
387: in
388: .Nx 1.0 ;
389: and
390: .Fl s
391: and
392: .Fl S
393: in
394: .Ox 2.3 .