Annotation of mandoc/man.1, Revision 1.35
1.35 ! schwarze 1: .\" $Id: man.1,v 1.34 2018/11/22 11:30:23 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.34 schwarze 6: .\" Copyright (c) 2010, 2011, 2014-2018 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.35 ! schwarze 34: .Dd $Mdocdate: November 22 2018 $
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
44: .Op Fl M Ar path
45: .Op Fl m Ar path
46: .Op Fl S Ar subsection
1.28 schwarze 47: .Op Oo Fl s Oc Ar section
1.1 schwarze 48: .Ar name ...
49: .Sh DESCRIPTION
50: The
51: .Nm
52: utility
53: displays the
54: manual pages entitled
55: .Ar name .
56: Pages may be selected according to
57: a specific category
58: .Pq Ar section
59: or
60: machine architecture
61: .Pq Ar subsection .
62: .Pp
63: The options are as follows:
64: .Bl -tag -width Ds
65: .It Fl a
1.18 schwarze 66: Display all matching manual pages.
67: Normally, only the first page found is displayed.
1.1 schwarze 68: .It Fl C Ar file
69: Use the specified
70: .Ar file
71: instead of the default configuration file.
72: This permits users to configure their own manual environment.
73: See
74: .Xr man.conf 5
75: for a description of the contents of this file.
76: .It Fl c
77: Copy the manual page to the standard output instead of using
78: .Xr more 1
79: to paginate it.
80: This is done by default if the standard output is not a terminal device.
1.30 schwarze 81: .Pp
82: When using
83: .Fl c ,
84: most terminal devices are unable to show the markup.
85: To print the output of
86: .Nm
87: to the terminal with markup but without using a pager, pipe it to
88: .Xr ul 1 .
89: To remove the markup, pipe the output to
90: .Xr col 1
91: .Fl b
92: instead.
1.2 schwarze 93: .It Fl f
1.1 schwarze 94: A synonym for
95: .Xr whatis 1 .
1.2 schwarze 96: It searches for
97: .Ar name
98: in manual page names and displays the header lines from all matching pages.
99: The search is case insensitive and matches whole words only.
1.20 schwarze 100: .It Fl h
101: Display only the SYNOPSIS lines of the requested manual pages.
102: Implies
103: .Fl a
104: and
105: .Fl c .
1.2 schwarze 106: .It Fl k
1.1 schwarze 107: A synonym for
108: .Xr apropos 1 .
1.2 schwarze 109: Instead of
110: .Ar name ,
111: an expression can be provided using the syntax described in the
112: .Xr apropos 1
113: manual.
114: By default, it displays the header lines of all matching pages.
1.4 schwarze 115: .It Fl l
116: A synonym for
1.33 schwarze 117: .Xr mandoc 1 .
1.4 schwarze 118: The
119: .Ar name
120: arguments are interpreted as filenames.
121: No search is done and
122: .Ar file ,
123: .Ar path ,
124: .Ar section ,
1.27 schwarze 125: .Ar subsection ,
1.4 schwarze 126: and
1.27 schwarze 127: .Fl w
1.4 schwarze 128: are ignored.
1.33 schwarze 129: This option implies
130: .Fl a .
1.1 schwarze 131: .It Fl M Ar path
132: Override the list of standard directories which
133: .Nm
134: searches for manual pages.
135: The supplied
136: .Ar path
137: must be a colon
138: .Pq Ql \&:
139: separated list of directories.
140: This search path may also be set using the environment variable
141: .Ev MANPATH .
142: .It Fl m Ar path
143: Augment the list of standard directories which
144: .Nm
145: searches for manual pages.
146: The supplied
147: .Ar path
148: must be a colon
149: .Pq Ql \&:
150: separated list of directories.
151: These directories will be searched before the standard directories or
152: the directories specified using the
153: .Fl M
154: option or the
155: .Ev MANPATH
156: environment variable.
157: .It Fl S Ar subsection
1.25 schwarze 158: Only show pages for the specified
1.1 schwarze 159: .Xr machine 1
160: architecture.
161: .Ar subsection
162: is case insensitive.
163: .Pp
164: By default manual pages for all architectures are installed.
165: Therefore this option can be used to view pages for one
166: architecture whilst using another.
167: .Pp
168: This option overrides the
169: .Ev MACHINE
170: environment variable.
1.17 schwarze 171: .It Oo Fl s Oc Ar section
172: Only select manuals from the specified
173: .Ar section .
1.1 schwarze 174: The currently available sections are:
175: .Pp
176: .Bl -tag -width "localXXX" -offset indent -compact
177: .It 1
178: General commands
179: .Pq tools and utilities .
180: .It 2
181: System calls and error numbers.
182: .It 3
1.17 schwarze 183: Library functions.
1.1 schwarze 184: .It 3p
185: .Xr perl 1
186: programmer's reference guide.
187: .It 4
188: Device drivers.
189: .It 5
190: File formats.
191: .It 6
192: Games.
193: .It 7
1.17 schwarze 194: Miscellaneous information.
1.1 schwarze 195: .It 8
196: System maintenance and operation commands.
197: .It 9
198: Kernel internals.
199: .El
1.22 schwarze 200: .Pp
201: If not specified and a match is found in more than one section,
202: the first match is selected from the following list:
203: 1, 8, 6, 2, 3, 5, 7, 4, 9, 3p.
1.1 schwarze 204: .It Fl w
1.25 schwarze 205: List the pathnames of all matching manual pages instead of displaying
206: any of them.
1.1 schwarze 207: .El
1.26 schwarze 208: .Pp
209: The options
210: .Fl IKOTW
211: are also supported and are documented in
212: .Xr mandoc 1 .
1.27 schwarze 213: The options
214: .Fl fkl
215: are mutually exclusive and override each other.
1.1 schwarze 216: .Pp
1.2 schwarze 217: Guidelines for writing
1.1 schwarze 218: man pages can be found in
219: .Xr mdoc 7 .
220: .Pp
1.35 ! schwarze 221: The
! 222: .Xr mandoc.db 5
! 223: database is used for looking up manual page entries.
! 224: In cases where the database is absent, outdated, or corrupt,
! 225: .Nm
! 226: falls back to looking for files called
! 227: .Ar name . Ns Ar section .
1.1 schwarze 228: If both a formatted and an unformatted version of the same manual page,
229: for example
230: .Pa cat1/foo.0
231: and
232: .Pa man1/foo.1 ,
1.24 schwarze 233: exist in the same directory, only the unformatted version is used.
1.35 ! schwarze 234: The database is kept up to date with
! 235: .Xr makewhatis 8 ,
! 236: which is run by the
! 237: .Xr weekly 8
! 238: maintenance script.
1.1 schwarze 239: .Sh ENVIRONMENT
240: .Bl -tag -width MANPATHX
241: .It Ev MACHINE
242: As some manual pages are intended only for specific architectures,
243: .Nm
244: searches any subdirectories,
245: with the same name as the current architecture,
246: in every directory which it searches.
247: Machine specific areas are checked before general areas.
248: The current machine type may be overridden by setting the environment
249: variable
250: .Ev MACHINE
251: to the name of a specific architecture,
252: or with the
253: .Fl S
254: option.
255: .Ev MACHINE
256: is case insensitive.
257: .It Ev MANPAGER
258: Any non-empty value of the environment variable
259: .Ev MANPAGER
1.23 schwarze 260: is used instead of the standard pagination program,
1.1 schwarze 261: .Xr more 1 .
1.15 schwarze 262: If
263: .Xr less 1
264: is used, the interactive
265: .Ic :t
266: command can be used to go to the definitions of various terms, for
267: example command line options, command modifiers, internal commands,
1.19 schwarze 268: environment variables, function names, preprocessor macros,
269: .Xr errno 2
270: values, and some other emphasized words.
271: Some terms may have defining text at more than one place.
272: In that case, the
273: .Xr less 1
274: interactive commands
275: .Ic t
276: and
277: .Ic T
278: can be used to move to the next and to the previous place providing
279: information about the term last searched for with
280: .Ic :t .
1.34 schwarze 281: The
282: .Fl O Cm tag Ns Op = Ns Ar term
283: option documented in the
284: .Xr mandoc 1
285: manual opens a manual page at the definition of a specific
286: .Ar term
287: rather than at the beginning.
1.1 schwarze 288: .It Ev MANPATH
289: The standard search path used by
290: .Nm
1.23 schwarze 291: may be changed by specifying a path in the
1.1 schwarze 292: .Ev MANPATH
1.23 schwarze 293: environment variable.
1.1 schwarze 294: The format of the path is a colon
295: .Pq Ql \&:
296: separated list of directories.
1.29 schwarze 297: Invalid paths are ignored.
1.23 schwarze 298: Overridden by
299: .Fl M ,
300: ignored if
301: .Fl l
302: is specified.
303: .Pp
304: If
305: .Ev MANPATH
306: begins with a colon, it is appended to the default list;
307: if it ends with a colon, it is prepended to the default list;
308: or if it contains two adjacent colons,
309: the standard search path is inserted between the colons.
310: If none of these conditions are met, it overrides the
311: standard search path.
1.1 schwarze 312: .It Ev PAGER
313: Specifies the pagination program to use when
314: .Ev MANPAGER
315: is not defined.
316: If neither PAGER nor MANPAGER is defined,
1.14 schwarze 317: .Xr more 1
318: .Fl s
1.23 schwarze 319: is used.
1.1 schwarze 320: .El
321: .Sh FILES
322: .Bl -tag -width /etc/man.conf -compact
323: .It Pa /etc/man.conf
324: default man configuration file
325: .El
326: .Sh EXIT STATUS
327: .Ex -std man
1.25 schwarze 328: See
329: .Xr mandoc 1
330: for details.
1.31 schwarze 331: .Sh EXAMPLES
332: Format a page for pasting extracts into an email message \(em
333: avoid printing any UTF-8 characters, reduce the width to ease
334: quoting in replies, and remove markup:
335: .Pp
336: .Dl $ man -T ascii -O width=65 pledge | col -b
337: .Pp
338: Read a typeset page in a PDF viewer:
339: .Pp
340: .Dl $ MANPAGER=mupdf man -T pdf lpd
1.1 schwarze 341: .Sh SEE ALSO
342: .Xr apropos 1 ,
1.30 schwarze 343: .Xr col 1 ,
344: .Xr mandoc 1 ,
345: .Xr ul 1 ,
1.1 schwarze 346: .Xr whereis 1 ,
347: .Xr man.conf 5 ,
1.30 schwarze 348: .Xr mdoc 7
1.1 schwarze 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
1.13 schwarze 357: .Op Fl aCcfhIKlMmOSsTWw ,
1.1 schwarze 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: .Fl s
397: and
398: .Fl S
399: in
1.21 schwarze 400: .Ox 2.3 ;
401: and
402: .Fl I ,
403: .Fl K ,
404: .Fl l ,
405: .Fl O ,
406: and
407: .Fl W
408: in
409: .Ox 5.7 .
410: The
411: .Fl T
412: option first appeared in
413: .At III
414: and was also added in
415: .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