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