Annotation of mandoc/man.1, Revision 1.7
1.7 ! schwarze 1: .\" $Id: man.1,v 1.6 2014/10/25 01:03:52 schwarze Exp $
1.1 schwarze 2: .\"
3: .\" Copyright (c) 1989, 1990, 1993
4: .\" The Regents of the University of California. All rights reserved.
1.2 schwarze 5: .\" Copyright (c) 2003, 2007, 2008, 2014 Jason McIntyre <jmc@openbsd.org>
6: .\" Copyright (c) 2010, 2011 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.7 ! schwarze 34: .Dd $Mdocdate: October 25 2014 $
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.4 schwarze 42: .Op Fl acfhklVw
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
47: .Op Fl s Ar section
48: .Op Ar section
49: .Ar name ...
50: .Sh DESCRIPTION
51: The
52: .Nm
53: utility
54: displays the
55: manual pages entitled
56: .Ar name .
57: Pages may be selected according to
58: a specific category
59: .Pq Ar section
60: or
61: machine architecture
62: .Pq Ar subsection .
63: .Pp
64: The options are as follows:
65: .Bl -tag -width Ds
66: .It Fl a
67: Display all of the manual pages for a specified
68: .Ar section
69: and
70: .Ar name
71: combination.
72: Normally, only the first manual page found is displayed.
73: .It Fl C Ar file
74: Use the specified
75: .Ar file
76: instead of the default configuration file.
77: This permits users to configure their own manual environment.
78: See
79: .Xr man.conf 5
80: for a description of the contents of this file.
81: .It Fl c
82: Copy the manual page to the standard output instead of using
83: .Xr more 1
84: to paginate it.
85: This is done by default if the standard output is not a terminal device.
1.2 schwarze 86: .It Fl f
1.1 schwarze 87: A synonym for
88: .Xr whatis 1 .
1.2 schwarze 89: It searches for
90: .Ar name
91: in manual page names and displays the header lines from all matching pages.
92: The search is case insensitive and matches whole words only.
1.4 schwarze 93: This overrides any earlier
94: .Fl k
95: and
96: .Fl l
97: options.
1.1 schwarze 98: .It Fl h
1.5 schwarze 99: Display only the SYNOPSIS lines of the requested manual pages.
100: Implies
1.7 ! schwarze 101: .Fl a
! 102: and
! 103: .Fl c .
1.2 schwarze 104: .It Fl k
1.1 schwarze 105: A synonym for
106: .Xr apropos 1 .
1.2 schwarze 107: Instead of
108: .Ar name ,
109: an expression can be provided using the syntax described in the
110: .Xr apropos 1
111: manual.
112: By default, it displays the header lines of all matching pages.
1.4 schwarze 113: This overrides any earlier
114: .Fl f
115: and
116: .Fl l
117: options.
118: .It Fl l
119: A synonym for
120: .Xr mandoc 1
121: .Fl a .
122: The
123: .Ar name
124: arguments are interpreted as filenames.
125: No search is done and
126: .Ar file ,
127: .Ar path ,
128: .Ar section ,
129: and
130: .Ar subsection
131: are ignored.
132: This overrides any earlier
133: .Fl f ,
134: .Fl k ,
135: and
136: .Fl w
137: options.
1.1 schwarze 138: .It Fl M Ar path
139: Override the list of standard directories which
140: .Nm
141: searches for manual pages.
142: The supplied
143: .Ar path
144: must be a colon
145: .Pq Ql \&:
146: separated list of directories.
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,
150: are specified by the
151: .Dq _subdir
152: line in the
153: .Nm
154: configuration file.
155: .It Fl m Ar path
156: Augment the list of standard directories which
157: .Nm
158: searches for manual pages.
159: The supplied
160: .Ar path
161: must be a colon
162: .Pq Ql \&:
163: separated list of directories.
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,
171: are specified by the
172: .Dq _subdir
173: line in the
174: .Nm
175: configuration file.
176: .It Fl S Ar subsection
177: Restricts the directories that
178: .Nm
179: will search to those of a specific
180: .Xr machine 1
181: architecture.
182: .Ar subsection
183: is case insensitive.
184: .Pp
185: By default manual pages for all architectures are installed.
186: Therefore this option can be used to view pages for one
187: architecture whilst using another.
188: .Pp
189: This option overrides the
190: .Ev MACHINE
191: environment variable.
192: .It Xo
193: .Op Fl s
194: .Ar section
195: .Xc
196: Restricts the directories that
197: .Nm
198: will search to a specific section.
199: The currently available sections are:
200: .Pp
201: .Bl -tag -width "localXXX" -offset indent -compact
202: .It 1
203: General commands
204: .Pq tools and utilities .
205: .It 2
206: System calls and error numbers.
207: .It 3
208: Libraries.
209: .It 3f
210: Fortran programmer's reference guide.
211: .It 3p
212: .Xr perl 1
213: programmer's reference guide.
214: .It 4
215: Device drivers.
216: .It 5
217: File formats.
218: .It 6
219: Games.
220: .It 7
221: Miscellaneous.
222: .It 8
223: System maintenance and operation commands.
224: .It 9
225: Kernel internals.
226: .It X11
227: An alias for X11R6.
228: .It X11R6
229: X Window System.
230: .It local
231: Pages located in
232: .Pa /usr/local .
233: .It n
234: Tcl/Tk commands.
235: .El
236: .Pp
237: The
238: .Nm
239: configuration file,
240: .Xr man.conf 5 ,
241: specifies the possible
242: .Ar section
243: values, and their search order.
244: Additional sections may be specified.
1.4 schwarze 245: .It Fl V
246: Print version and exit.
1.1 schwarze 247: .It Fl w
248: List the pathnames of the manual pages which
249: .Nm
250: would display for the specified
251: .Ar section
252: and
253: .Ar name
254: combination.
255: .El
1.3 schwarze 256: .Pp
257: The
258: .Nm
259: utility also supports the options
1.6 schwarze 260: .Fl IKOTW
1.3 schwarze 261: described in the
262: .Xr mandoc 1
263: manual.
1.1 schwarze 264: .Pp
1.2 schwarze 265: Guidelines for writing
1.1 schwarze 266: man pages can be found in
267: .Xr mdoc 7 .
268: .Pp
269: If both a formatted and an unformatted version of the same manual page,
270: for example
271: .Pa cat1/foo.0
272: and
273: .Pa man1/foo.1 ,
274: exist in the same directory, and at least one of them is selected,
275: only the newer one is used.
276: However, if both the
277: .Fl a
278: and the
279: .Fl w
280: options are specified, both file names are printed.
281: .Sh ENVIRONMENT
282: .Bl -tag -width MANPATHX
283: .It Ev MACHINE
284: As some manual pages are intended only for specific architectures,
285: .Nm
286: searches any subdirectories,
287: with the same name as the current architecture,
288: in every directory which it searches.
289: Machine specific areas are checked before general areas.
290: The current machine type may be overridden by setting the environment
291: variable
292: .Ev MACHINE
293: to the name of a specific architecture,
294: or with the
295: .Fl S
296: option.
297: .Ev MACHINE
298: is case insensitive.
299: .It Ev MANPAGER
300: Any non-empty value of the environment variable
301: .Ev MANPAGER
302: will be used instead of the standard pagination program,
303: .Xr more 1 .
304: .It Ev MANPATH
305: The standard search path used by
306: .Nm
307: may be overridden by specifying a path in the
308: .Ev MANPATH
309: environment
310: variable.
311: The format of the path is a colon
312: .Pq Ql \&:
313: separated list of directories.
314: The subdirectories to be searched, as well as their search order,
315: are specified by the
316: .Dq _subdir
317: line in the
318: .Nm
319: configuration file.
320: .It Ev PAGER
321: Specifies the pagination program to use when
322: .Ev MANPAGER
323: is not defined.
324: If neither PAGER nor MANPAGER is defined,
325: .Pa /usr/bin/more Fl s
326: will be used.
327: .El
328: .Sh FILES
329: .Bl -tag -width /etc/man.conf -compact
330: .It Pa /etc/man.conf
331: default man configuration file
332: .El
333: .Sh EXIT STATUS
334: .Ex -std man
335: .Sh SEE ALSO
336: .Xr apropos 1 ,
337: .Xr intro 1 ,
338: .Xr whatis 1 ,
339: .Xr whereis 1 ,
340: .Xr intro 2 ,
341: .Xr intro 3 ,
342: .Xr intro 4 ,
343: .Xr intro 5 ,
344: .Xr man.conf 5 ,
345: .Xr intro 6 ,
346: .Xr intro 7 ,
347: .Xr mdoc 7 ,
348: .Xr intro 8 ,
349: .Xr intro 9
350: .Sh STANDARDS
351: The
352: .Nm
353: utility is compliant with the
354: .St -p1003.1-2008
355: specification.
356: .Pp
357: The flags
358: .Op Fl aCcfhMmSsw ,
359: as well as the environment variables
360: .Ev MACHINE ,
361: .Ev MANPAGER ,
362: and
363: .Ev MANPATH ,
364: are extensions to that specification.
365: .Sh HISTORY
366: A
367: .Nm
368: command first appeared in
369: .At v3 .
370: .Pp
371: The
372: .Fl w
373: option first appeared in
374: .At v7 ;
375: .Fl f
376: and
377: .Fl k
378: in
379: .Bx 4 ;
380: .Fl M
381: in
382: .Bx 4.3 ;
383: .Fl a
384: in
385: .Bx 4.3 Tahoe ;
386: .Fl c
387: and
388: .Fl m
389: in
390: .Bx 4.3 Reno ;
391: .Fl h
392: in
393: .Bx 4.3 Net/2 ;
394: .Fl C
395: in
396: .Nx 1.0 ;
397: and
398: .Fl s
399: and
400: .Fl S
401: in
402: .Ox 2.3 .
CVSweb