Annotation of mandoc/man.1, Revision 1.25
1.25 ! schwarze 1: .\" $Id: man.1,v 1.24 2017/03/21 18:06:12 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>
1.22 schwarze 6: .\" Copyright (c) 2010, 2011, 2014-2017 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.25 ! schwarze 34: .Dd $Mdocdate: March 21 2017 $
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.13 schwarze 42: .Op Fl acfhklw
1.1 schwarze 43: .Op Fl C Ar file
1.8 schwarze 44: .Op Fl I Cm os Ns = Ns Ar name
45: .Op Fl K Ar encoding
1.1 schwarze 46: .Op Fl M Ar path
47: .Op Fl m Ar path
1.8 schwarze 48: .Op Fl O Ar option Ns = Ns Ar value
1.1 schwarze 49: .Op Fl S Ar subsection
50: .Op Fl s Ar section
1.8 schwarze 51: .Op Fl T Ar output
52: .Op Fl W Ar level
1.1 schwarze 53: .Op Ar section
54: .Ar name ...
55: .Sh DESCRIPTION
56: The
57: .Nm
58: utility
59: displays the
60: manual pages entitled
61: .Ar name .
62: Pages may be selected according to
63: a specific category
64: .Pq Ar section
65: or
66: machine architecture
67: .Pq Ar subsection .
68: .Pp
69: The options are as follows:
70: .Bl -tag -width Ds
71: .It Fl a
1.18 schwarze 72: Display all matching manual pages.
73: Normally, only the first page found is displayed.
1.1 schwarze 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.20 schwarze 99: .It Fl h
100: Display only the SYNOPSIS lines of the requested manual pages.
101: Implies
102: .Fl a
103: and
104: .Fl c .
1.8 schwarze 105: .It Fl I Cm os Ns = Ns Ar name
106: Override the default operating system
107: .Ar name
108: for the
109: .Xr mdoc 7
110: .Ic \&Os
1.10 schwarze 111: and for the
112: .Xr man 7
113: .Ic \&TH
1.8 schwarze 114: macro.
115: .It Fl K Ar encoding
116: Specify the input encoding.
117: The supported
118: .Ar encoding
119: arguments are
120: .Cm us-ascii ,
121: .Cm iso-8859-1 ,
122: and
123: .Cm utf-8 .
124: By default, the encoding is automatically detected as described in the
125: .Xr mandoc 1
126: manual.
1.2 schwarze 127: .It Fl k
1.1 schwarze 128: A synonym for
129: .Xr apropos 1 .
1.2 schwarze 130: Instead of
131: .Ar name ,
132: an expression can be provided using the syntax described in the
133: .Xr apropos 1
134: manual.
135: By default, it displays the header lines of all matching pages.
1.4 schwarze 136: This overrides any earlier
137: .Fl f
138: and
139: .Fl l
140: options.
141: .It Fl l
142: A synonym for
143: .Xr mandoc 1
144: .Fl a .
145: The
146: .Ar name
147: arguments are interpreted as filenames.
148: No search is done and
149: .Ar file ,
150: .Ar path ,
151: .Ar section ,
152: and
153: .Ar subsection
154: are ignored.
155: This overrides any earlier
156: .Fl f ,
157: .Fl k ,
158: and
159: .Fl w
160: options.
1.1 schwarze 161: .It Fl M Ar path
162: Override the list of standard directories which
163: .Nm
164: searches for manual pages.
165: The supplied
166: .Ar path
167: must be a colon
168: .Pq Ql \&:
169: separated list of directories.
170: This search path may also be set using the environment variable
171: .Ev MANPATH .
172: .It Fl m Ar path
173: Augment the list of standard directories which
174: .Nm
175: searches for manual pages.
176: The supplied
177: .Ar path
178: must be a colon
179: .Pq Ql \&:
180: separated list of directories.
181: These directories will be searched before the standard directories or
182: the directories specified using the
183: .Fl M
184: option or the
185: .Ev MANPATH
186: environment variable.
1.8 schwarze 187: .It Fl O Ar option Ns = Ns Ar value
188: Comma-separated output options.
189: For each output format, the available options are described in the
190: .Xr mandoc 1
191: manual.
1.1 schwarze 192: .It Fl S Ar subsection
1.25 ! schwarze 193: Only show pages for the specified
1.1 schwarze 194: .Xr machine 1
195: architecture.
196: .Ar subsection
197: is case insensitive.
198: .Pp
199: By default manual pages for all architectures are installed.
200: Therefore this option can be used to view pages for one
201: architecture whilst using another.
202: .Pp
203: This option overrides the
204: .Ev MACHINE
205: environment variable.
1.17 schwarze 206: .It Oo Fl s Oc Ar section
207: Only select manuals from the specified
208: .Ar section .
1.1 schwarze 209: The currently available sections are:
210: .Pp
211: .Bl -tag -width "localXXX" -offset indent -compact
212: .It 1
213: General commands
214: .Pq tools and utilities .
215: .It 2
216: System calls and error numbers.
217: .It 3
1.17 schwarze 218: Library functions.
1.1 schwarze 219: .It 3p
220: .Xr perl 1
221: programmer's reference guide.
222: .It 4
223: Device drivers.
224: .It 5
225: File formats.
226: .It 6
227: Games.
228: .It 7
1.17 schwarze 229: Miscellaneous information.
1.1 schwarze 230: .It 8
231: System maintenance and operation commands.
232: .It 9
233: Kernel internals.
234: .El
1.22 schwarze 235: .Pp
236: If not specified and a match is found in more than one section,
237: the first match is selected from the following list:
238: 1, 8, 6, 2, 3, 5, 7, 4, 9, 3p.
1.8 schwarze 239: .It Fl T Ar output
240: Select the output format.
241: The default is
242: .Cm locale .
243: The other output modes
244: .Cm ascii ,
245: .Cm html ,
246: .Cm lint ,
247: .Cm man ,
248: .Cm pdf ,
249: .Cm ps ,
250: .Cm tree ,
251: and
252: .Cm utf8
253: are described in the
254: .Xr mandoc 1
255: manual.
256: .It Fl W Ar level
257: Specify the minimum message
258: .Ar level
259: to be reported on the standard error output and to affect the exit status.
260: The
261: .Ar level
262: can be
1.12 schwarze 263: .Cm warning ,
264: .Cm error ,
1.8 schwarze 265: or
1.12 schwarze 266: .Cm unsupp ;
1.8 schwarze 267: .Cm all
268: is an alias for
269: .Cm warning .
1.11 schwarze 270: By default,
271: .Nm
272: is silent.
1.8 schwarze 273: See the
274: .Xr mandoc 1
275: manual for details.
1.1 schwarze 276: .It Fl w
1.25 ! schwarze 277: List the pathnames of all matching manual pages instead of displaying
! 278: any of them.
1.1 schwarze 279: .El
280: .Pp
1.2 schwarze 281: Guidelines for writing
1.1 schwarze 282: man pages can be found in
283: .Xr mdoc 7 .
284: .Pp
285: If both a formatted and an unformatted version of the same manual page,
286: for example
287: .Pa cat1/foo.0
288: and
289: .Pa man1/foo.1 ,
1.24 schwarze 290: exist in the same directory, only the unformatted version is used.
1.1 schwarze 291: .Sh ENVIRONMENT
292: .Bl -tag -width MANPATHX
293: .It Ev MACHINE
294: As some manual pages are intended only for specific architectures,
295: .Nm
296: searches any subdirectories,
297: with the same name as the current architecture,
298: in every directory which it searches.
299: Machine specific areas are checked before general areas.
300: The current machine type may be overridden by setting the environment
301: variable
302: .Ev MACHINE
303: to the name of a specific architecture,
304: or with the
305: .Fl S
306: option.
307: .Ev MACHINE
308: is case insensitive.
309: .It Ev MANPAGER
310: Any non-empty value of the environment variable
311: .Ev MANPAGER
1.23 schwarze 312: is used instead of the standard pagination program,
1.1 schwarze 313: .Xr more 1 .
1.15 schwarze 314: If
315: .Xr less 1
316: is used, the interactive
317: .Ic :t
318: command can be used to go to the definitions of various terms, for
319: example command line options, command modifiers, internal commands,
1.19 schwarze 320: environment variables, function names, preprocessor macros,
321: .Xr errno 2
322: values, and some other emphasized words.
323: Some terms may have defining text at more than one place.
324: In that case, the
325: .Xr less 1
326: interactive commands
327: .Ic t
328: and
329: .Ic T
330: can be used to move to the next and to the previous place providing
331: information about the term last searched for with
332: .Ic :t .
1.1 schwarze 333: .It Ev MANPATH
334: The standard search path used by
335: .Nm
1.23 schwarze 336: may be changed by specifying a path in the
1.1 schwarze 337: .Ev MANPATH
1.23 schwarze 338: environment variable.
1.1 schwarze 339: The format of the path is a colon
340: .Pq Ql \&:
341: separated list of directories.
1.23 schwarze 342: Invalid paths, or paths without manual databases, are ignored.
343: Overridden by
344: .Fl M ,
345: ignored if
346: .Fl l
347: is specified.
348: .Pp
349: If
350: .Ev MANPATH
351: begins with a colon, it is appended to the default list;
352: if it ends with a colon, it is prepended to the default list;
353: or if it contains two adjacent colons,
354: the standard search path is inserted between the colons.
355: If none of these conditions are met, it overrides the
356: standard search path.
1.1 schwarze 357: .It Ev PAGER
358: Specifies the pagination program to use when
359: .Ev MANPAGER
360: is not defined.
361: If neither PAGER nor MANPAGER is defined,
1.14 schwarze 362: .Xr more 1
363: .Fl s
1.23 schwarze 364: is used.
365: Only used if
366: .Fl a
367: or
368: .Fl l
369: is specified.
1.1 schwarze 370: .El
371: .Sh FILES
372: .Bl -tag -width /etc/man.conf -compact
373: .It Pa /etc/man.conf
374: default man configuration file
375: .El
376: .Sh EXIT STATUS
377: .Ex -std man
1.25 ! schwarze 378: See
! 379: .Xr mandoc 1
! 380: for details.
1.1 schwarze 381: .Sh SEE ALSO
382: .Xr apropos 1 ,
383: .Xr intro 1 ,
384: .Xr whereis 1 ,
385: .Xr intro 2 ,
386: .Xr intro 3 ,
387: .Xr intro 4 ,
388: .Xr intro 5 ,
389: .Xr man.conf 5 ,
390: .Xr intro 6 ,
391: .Xr intro 7 ,
392: .Xr mdoc 7 ,
393: .Xr intro 8 ,
394: .Xr intro 9
395: .Sh STANDARDS
396: The
397: .Nm
398: utility is compliant with the
399: .St -p1003.1-2008
400: specification.
401: .Pp
402: The flags
1.13 schwarze 403: .Op Fl aCcfhIKlMmOSsTWw ,
1.1 schwarze 404: as well as the environment variables
405: .Ev MACHINE ,
406: .Ev MANPAGER ,
407: and
408: .Ev MANPATH ,
409: are extensions to that specification.
410: .Sh HISTORY
411: A
412: .Nm
413: command first appeared in
414: .At v3 .
415: .Pp
416: The
417: .Fl w
418: option first appeared in
419: .At v7 ;
420: .Fl f
421: and
422: .Fl k
423: in
424: .Bx 4 ;
425: .Fl M
426: in
427: .Bx 4.3 ;
428: .Fl a
429: in
430: .Bx 4.3 Tahoe ;
431: .Fl c
432: and
433: .Fl m
434: in
435: .Bx 4.3 Reno ;
436: .Fl h
437: in
438: .Bx 4.3 Net/2 ;
439: .Fl C
440: in
441: .Nx 1.0 ;
442: .Fl s
443: and
444: .Fl S
445: in
1.21 schwarze 446: .Ox 2.3 ;
447: and
448: .Fl I ,
449: .Fl K ,
450: .Fl l ,
451: .Fl O ,
452: and
453: .Fl W
454: in
455: .Ox 5.7 .
456: The
457: .Fl T
458: option first appeared in
459: .At III
460: and was also added in
461: .Ox 5.7 .
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to man.1 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc