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