Annotation of mandoc/man.1, Revision 1.4
1.4 ! schwarze 1: .\" $Id: man.1,v 1.3 2014/08/21 02:38:24 schwarze Exp $
1.1 schwarze 2: .\" $OpenBSD: man.1,v 1.55 2014/04/03 06:15:18 jmc Exp $
3: .\"
4: .\" Copyright (c) 1989, 1990, 1993
5: .\" The Regents of the University of California. All rights reserved.
1.2 schwarze 6: .\" Copyright (c) 2003, 2007, 2008, 2014 Jason McIntyre <jmc@openbsd.org>
7: .\" Copyright (c) 2010, 2011 Ingo Schwarze <schwarze@openbsd.org>
1.1 schwarze 8: .\"
9: .\" Redistribution and use in source and binary forms, with or without
10: .\" modification, are permitted provided that the following conditions
11: .\" are met:
12: .\" 1. Redistributions of source code must retain the above copyright
13: .\" notice, this list of conditions and the following disclaimer.
14: .\" 2. Redistributions in binary form must reproduce the above copyright
15: .\" notice, this list of conditions and the following disclaimer in the
16: .\" documentation and/or other materials provided with the distribution.
17: .\" 3. Neither the name of the University nor the names of its contributors
18: .\" may be used to endorse or promote products derived from this software
19: .\" without specific prior written permission.
20: .\"
21: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
22: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
24: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
25: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
26: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
27: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
28: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
29: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
30: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31: .\" SUCH DAMAGE.
32: .\"
33: .\" @(#)man.1 8.2 (Berkeley) 1/2/94
34: .\"
1.2 schwarze 35: .Dd $Mdocdate: August 21 2014 $
1.1 schwarze 36: .Dt MAN 1
37: .Os
38: .Sh NAME
39: .Nm man
40: .Nd display manual pages
41: .Sh SYNOPSIS
42: .Nm man
1.4 ! schwarze 43: .Op Fl acfhklVw
1.1 schwarze 44: .Op Fl C Ar file
45: .Op Fl M Ar path
46: .Op Fl m Ar path
47: .Op Fl S Ar subsection
48: .Op Fl s Ar section
49: .Op Ar section
50: .Ar name ...
51: .Sh DESCRIPTION
52: The
53: .Nm
54: utility
55: displays the
56: manual pages entitled
57: .Ar name .
58: Pages may be selected according to
59: a specific category
60: .Pq Ar section
61: or
62: machine architecture
63: .Pq Ar subsection .
64: .Pp
65: The options are as follows:
66: .Bl -tag -width Ds
67: .It Fl a
68: Display all of the manual pages for a specified
69: .Ar section
70: and
71: .Ar name
72: combination.
73: Normally, only the first manual page found is displayed.
74: .It Fl C Ar file
75: Use the specified
76: .Ar file
77: instead of the default configuration file.
78: This permits users to configure their own manual environment.
79: See
80: .Xr man.conf 5
81: for a description of the contents of this file.
82: .It Fl c
83: Copy the manual page to the standard output instead of using
84: .Xr more 1
85: to paginate it.
86: This is done by default if the standard output is not a terminal device.
1.2 schwarze 87: .It Fl f
1.1 schwarze 88: A synonym for
89: .Xr whatis 1 .
1.2 schwarze 90: It searches for
91: .Ar name
92: in manual page names and displays the header lines from all matching pages.
93: The search is case insensitive and matches whole words only.
1.4 ! schwarze 94: This overrides any earlier
! 95: .Fl k
! 96: and
! 97: .Fl l
! 98: options.
1.1 schwarze 99: .It Fl h
100: Display only the
101: .Dq SYNOPSIS
102: lines of the requested manual pages.
1.2 schwarze 103: .It Fl k
1.1 schwarze 104: A synonym for
105: .Xr apropos 1 .
1.2 schwarze 106: Instead of
107: .Ar name ,
108: an expression can be provided using the syntax described in the
109: .Xr apropos 1
110: manual.
111: By default, it displays the header lines of all matching pages.
1.4 ! schwarze 112: This overrides any earlier
! 113: .Fl f
! 114: and
! 115: .Fl l
! 116: options.
! 117: .It Fl l
! 118: A synonym for
! 119: .Xr mandoc 1
! 120: .Fl a .
! 121: The
! 122: .Ar name
! 123: arguments are interpreted as filenames.
! 124: No search is done and
! 125: .Ar file ,
! 126: .Ar path ,
! 127: .Ar section ,
! 128: and
! 129: .Ar subsection
! 130: are ignored.
! 131: This overrides any earlier
! 132: .Fl f ,
! 133: .Fl k ,
! 134: and
! 135: .Fl w
! 136: options.
1.1 schwarze 137: .It Fl M Ar path
138: Override the list of standard directories which
139: .Nm
140: searches for manual pages.
141: The supplied
142: .Ar path
143: must be a colon
144: .Pq Ql \&:
145: separated list of directories.
146: This search path may also be set using the environment variable
147: .Ev MANPATH .
148: The subdirectories to be searched, and their search order,
149: are specified by the
150: .Dq _subdir
151: line in the
152: .Nm
153: configuration file.
154: .It Fl m Ar path
155: Augment the list of standard directories which
156: .Nm
157: searches for manual pages.
158: The supplied
159: .Ar path
160: must be a colon
161: .Pq Ql \&:
162: separated list of directories.
163: These directories will be searched before the standard directories or
164: the directories specified using the
165: .Fl M
166: option or the
167: .Ev MANPATH
168: environment variable.
169: The subdirectories to be searched, and their search order,
170: are specified by the
171: .Dq _subdir
172: line in the
173: .Nm
174: configuration file.
175: .It Fl S Ar subsection
176: Restricts the directories that
177: .Nm
178: will search to those of a specific
179: .Xr machine 1
180: architecture.
181: .Ar subsection
182: is case insensitive.
183: .Pp
184: By default manual pages for all architectures are installed.
185: Therefore this option can be used to view pages for one
186: architecture whilst using another.
187: .Pp
188: This option overrides the
189: .Ev MACHINE
190: environment variable.
191: .It Xo
192: .Op Fl s
193: .Ar section
194: .Xc
195: Restricts the directories that
196: .Nm
197: will search to a specific section.
198: The currently available sections are:
199: .Pp
200: .Bl -tag -width "localXXX" -offset indent -compact
201: .It 1
202: General commands
203: .Pq tools and utilities .
204: .It 2
205: System calls and error numbers.
206: .It 3
207: Libraries.
208: .It 3f
209: Fortran programmer's reference guide.
210: .It 3p
211: .Xr perl 1
212: programmer's reference guide.
213: .It 4
214: Device drivers.
215: .It 5
216: File formats.
217: .It 6
218: Games.
219: .It 7
220: Miscellaneous.
221: .It 8
222: System maintenance and operation commands.
223: .It 9
224: Kernel internals.
225: .It X11
226: An alias for X11R6.
227: .It X11R6
228: X Window System.
229: .It local
230: Pages located in
231: .Pa /usr/local .
232: .It n
233: Tcl/Tk commands.
234: .El
235: .Pp
236: The
237: .Nm
238: configuration file,
239: .Xr man.conf 5 ,
240: specifies the possible
241: .Ar section
242: values, and their search order.
243: Additional sections may be specified.
1.4 ! schwarze 244: .It Fl V
! 245: Print version and exit.
1.1 schwarze 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.3 schwarze 255: .Pp
256: The
257: .Nm
258: utility also supports the options
259: .Fl IOTW
260: described in the
261: .Xr mandoc 1
262: manual.
1.1 schwarze 263: .Pp
1.2 schwarze 264: Guidelines for writing
1.1 schwarze 265: man pages can be found in
266: .Xr mdoc 7 .
267: .Pp
268: If both a formatted and an unformatted version of the same manual page,
269: for example
270: .Pa cat1/foo.0
271: and
272: .Pa man1/foo.1 ,
273: exist in the same directory, and at least one of them is selected,
274: only the newer one is used.
275: However, if both the
276: .Fl a
277: and the
278: .Fl w
279: options are specified, both file names are printed.
280: .Sh ENVIRONMENT
281: .Bl -tag -width MANPATHX
282: .It Ev MACHINE
283: As some manual pages are intended only for specific architectures,
284: .Nm
285: searches any subdirectories,
286: with the same name as the current architecture,
287: in every directory which it searches.
288: Machine specific areas are checked before general areas.
289: The current machine type may be overridden by setting the environment
290: variable
291: .Ev MACHINE
292: to the name of a specific architecture,
293: or with the
294: .Fl S
295: option.
296: .Ev MACHINE
297: is case insensitive.
298: .It Ev MANPAGER
299: Any non-empty value of the environment variable
300: .Ev MANPAGER
301: will be used instead of the standard pagination program,
302: .Xr more 1 .
303: .It Ev MANPATH
304: The standard search path used by
305: .Nm
306: may be overridden by specifying a path in the
307: .Ev MANPATH
308: environment
309: variable.
310: The format of the path is a colon
311: .Pq Ql \&:
312: separated list of directories.
313: The subdirectories to be searched, as well as their search order,
314: are specified by the
315: .Dq _subdir
316: line in the
317: .Nm
318: configuration file.
319: .It Ev PAGER
320: Specifies the pagination program to use when
321: .Ev MANPAGER
322: is not defined.
323: If neither PAGER nor MANPAGER is defined,
324: .Pa /usr/bin/more Fl s
325: will be used.
326: .El
327: .Sh FILES
328: .Bl -tag -width /etc/man.conf -compact
329: .It Pa /etc/man.conf
330: default man configuration file
331: .El
332: .Sh EXIT STATUS
333: .Ex -std man
334: .Sh SEE ALSO
335: .Xr apropos 1 ,
336: .Xr intro 1 ,
337: .Xr whatis 1 ,
338: .Xr whereis 1 ,
339: .Xr intro 2 ,
340: .Xr intro 3 ,
341: .Xr intro 4 ,
342: .Xr intro 5 ,
343: .Xr man.conf 5 ,
344: .Xr intro 6 ,
345: .Xr intro 7 ,
346: .Xr mdoc 7 ,
347: .Xr intro 8 ,
348: .Xr intro 9
349: .Sh STANDARDS
350: The
351: .Nm
352: utility is compliant with the
353: .St -p1003.1-2008
354: specification.
355: .Pp
356: The flags
357: .Op Fl aCcfhMmSsw ,
358: as well as the environment variables
359: .Ev MACHINE ,
360: .Ev MANPAGER ,
361: and
362: .Ev MANPATH ,
363: are extensions to that specification.
364: .Sh HISTORY
365: A
366: .Nm
367: command first appeared in
368: .At v3 .
369: .Pp
370: The
371: .Fl w
372: option first appeared in
373: .At v7 ;
374: .Fl f
375: and
376: .Fl k
377: in
378: .Bx 4 ;
379: .Fl M
380: in
381: .Bx 4.3 ;
382: .Fl a
383: in
384: .Bx 4.3 Tahoe ;
385: .Fl c
386: and
387: .Fl m
388: in
389: .Bx 4.3 Reno ;
390: .Fl h
391: in
392: .Bx 4.3 Net/2 ;
393: .Fl C
394: in
395: .Nx 1.0 ;
396: and
397: .Fl s
398: and
399: .Fl S
400: in
401: .Ox 2.3 .
CVSweb