Annotation of mandoc/man.1, Revision 1.27
1.27 ! schwarze 1: .\" $Id: man.1,v 1.26 2017/03/25 12:46:36 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.27 ! schwarze 34: .Dd $Mdocdate: March 25 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.20 schwarze 94: .It Fl h
95: Display only the SYNOPSIS lines of the requested manual pages.
96: Implies
97: .Fl a
98: and
99: .Fl c .
1.2 schwarze 100: .It Fl k
1.1 schwarze 101: A synonym for
102: .Xr apropos 1 .
1.2 schwarze 103: Instead of
104: .Ar name ,
105: an expression can be provided using the syntax described in the
106: .Xr apropos 1
107: manual.
108: By default, it displays the header lines of all matching pages.
1.4 schwarze 109: .It Fl l
110: A synonym for
111: .Xr mandoc 1
112: .Fl a .
113: The
114: .Ar name
115: arguments are interpreted as filenames.
116: No search is done and
117: .Ar file ,
118: .Ar path ,
119: .Ar section ,
1.27 ! schwarze 120: .Ar subsection ,
1.4 schwarze 121: and
1.27 ! schwarze 122: .Fl w
1.4 schwarze 123: are ignored.
1.1 schwarze 124: .It Fl M Ar path
125: Override the list of standard directories which
126: .Nm
127: searches for manual pages.
128: The supplied
129: .Ar path
130: must be a colon
131: .Pq Ql \&:
132: separated list of directories.
133: This search path may also be set using the environment variable
134: .Ev MANPATH .
135: .It Fl m Ar path
136: Augment the list of standard directories which
137: .Nm
138: searches for manual pages.
139: The supplied
140: .Ar path
141: must be a colon
142: .Pq Ql \&:
143: separated list of directories.
144: These directories will be searched before the standard directories or
145: the directories specified using the
146: .Fl M
147: option or the
148: .Ev MANPATH
149: environment variable.
150: .It Fl S Ar subsection
1.25 schwarze 151: Only show pages for the specified
1.1 schwarze 152: .Xr machine 1
153: architecture.
154: .Ar subsection
155: is case insensitive.
156: .Pp
157: By default manual pages for all architectures are installed.
158: Therefore this option can be used to view pages for one
159: architecture whilst using another.
160: .Pp
161: This option overrides the
162: .Ev MACHINE
163: environment variable.
1.17 schwarze 164: .It Oo Fl s Oc Ar section
165: Only select manuals from the specified
166: .Ar section .
1.1 schwarze 167: The currently available sections are:
168: .Pp
169: .Bl -tag -width "localXXX" -offset indent -compact
170: .It 1
171: General commands
172: .Pq tools and utilities .
173: .It 2
174: System calls and error numbers.
175: .It 3
1.17 schwarze 176: Library functions.
1.1 schwarze 177: .It 3p
178: .Xr perl 1
179: programmer's reference guide.
180: .It 4
181: Device drivers.
182: .It 5
183: File formats.
184: .It 6
185: Games.
186: .It 7
1.17 schwarze 187: Miscellaneous information.
1.1 schwarze 188: .It 8
189: System maintenance and operation commands.
190: .It 9
191: Kernel internals.
192: .El
1.22 schwarze 193: .Pp
194: If not specified and a match is found in more than one section,
195: the first match is selected from the following list:
196: 1, 8, 6, 2, 3, 5, 7, 4, 9, 3p.
1.1 schwarze 197: .It Fl w
1.25 schwarze 198: List the pathnames of all matching manual pages instead of displaying
199: any of them.
1.1 schwarze 200: .El
1.26 schwarze 201: .Pp
202: The options
203: .Fl IKOTW
204: are also supported and are documented in
205: .Xr mandoc 1 .
1.27 ! schwarze 206: The options
! 207: .Fl fkl
! 208: are mutually exclusive and override each other.
1.1 schwarze 209: .Pp
1.2 schwarze 210: Guidelines for writing
1.1 schwarze 211: man pages can be found in
212: .Xr mdoc 7 .
213: .Pp
214: If both a formatted and an unformatted version of the same manual page,
215: for example
216: .Pa cat1/foo.0
217: and
218: .Pa man1/foo.1 ,
1.24 schwarze 219: exist in the same directory, only the unformatted version is used.
1.1 schwarze 220: .Sh ENVIRONMENT
221: .Bl -tag -width MANPATHX
222: .It Ev MACHINE
223: As some manual pages are intended only for specific architectures,
224: .Nm
225: searches any subdirectories,
226: with the same name as the current architecture,
227: in every directory which it searches.
228: Machine specific areas are checked before general areas.
229: The current machine type may be overridden by setting the environment
230: variable
231: .Ev MACHINE
232: to the name of a specific architecture,
233: or with the
234: .Fl S
235: option.
236: .Ev MACHINE
237: is case insensitive.
238: .It Ev MANPAGER
239: Any non-empty value of the environment variable
240: .Ev MANPAGER
1.23 schwarze 241: is used instead of the standard pagination program,
1.1 schwarze 242: .Xr more 1 .
1.15 schwarze 243: If
244: .Xr less 1
245: is used, the interactive
246: .Ic :t
247: command can be used to go to the definitions of various terms, for
248: example command line options, command modifiers, internal commands,
1.19 schwarze 249: environment variables, function names, preprocessor macros,
250: .Xr errno 2
251: values, and some other emphasized words.
252: Some terms may have defining text at more than one place.
253: In that case, the
254: .Xr less 1
255: interactive commands
256: .Ic t
257: and
258: .Ic T
259: can be used to move to the next and to the previous place providing
260: information about the term last searched for with
261: .Ic :t .
1.1 schwarze 262: .It Ev MANPATH
263: The standard search path used by
264: .Nm
1.23 schwarze 265: may be changed by specifying a path in the
1.1 schwarze 266: .Ev MANPATH
1.23 schwarze 267: environment variable.
1.1 schwarze 268: The format of the path is a colon
269: .Pq Ql \&:
270: separated list of directories.
1.23 schwarze 271: Invalid paths, or paths without manual databases, are ignored.
272: Overridden by
273: .Fl M ,
274: ignored if
275: .Fl l
276: is specified.
277: .Pp
278: If
279: .Ev MANPATH
280: begins with a colon, it is appended to the default list;
281: if it ends with a colon, it is prepended to the default list;
282: or if it contains two adjacent colons,
283: the standard search path is inserted between the colons.
284: If none of these conditions are met, it overrides the
285: standard search path.
1.1 schwarze 286: .It Ev PAGER
287: Specifies the pagination program to use when
288: .Ev MANPAGER
289: is not defined.
290: If neither PAGER nor MANPAGER is defined,
1.14 schwarze 291: .Xr more 1
292: .Fl s
1.23 schwarze 293: is used.
294: Only used if
295: .Fl a
296: or
297: .Fl l
298: is specified.
1.1 schwarze 299: .El
300: .Sh FILES
301: .Bl -tag -width /etc/man.conf -compact
302: .It Pa /etc/man.conf
303: default man configuration file
304: .El
305: .Sh EXIT STATUS
306: .Ex -std man
1.25 schwarze 307: See
308: .Xr mandoc 1
309: for details.
1.1 schwarze 310: .Sh SEE ALSO
311: .Xr apropos 1 ,
312: .Xr intro 1 ,
313: .Xr whereis 1 ,
314: .Xr intro 2 ,
315: .Xr intro 3 ,
316: .Xr intro 4 ,
317: .Xr intro 5 ,
318: .Xr man.conf 5 ,
319: .Xr intro 6 ,
320: .Xr intro 7 ,
321: .Xr mdoc 7 ,
322: .Xr intro 8 ,
323: .Xr intro 9
324: .Sh STANDARDS
325: The
326: .Nm
327: utility is compliant with the
328: .St -p1003.1-2008
329: specification.
330: .Pp
331: The flags
1.13 schwarze 332: .Op Fl aCcfhIKlMmOSsTWw ,
1.1 schwarze 333: as well as the environment variables
334: .Ev MACHINE ,
335: .Ev MANPAGER ,
336: and
337: .Ev MANPATH ,
338: are extensions to that specification.
339: .Sh HISTORY
340: A
341: .Nm
342: command first appeared in
343: .At v3 .
344: .Pp
345: The
346: .Fl w
347: option first appeared in
348: .At v7 ;
349: .Fl f
350: and
351: .Fl k
352: in
353: .Bx 4 ;
354: .Fl M
355: in
356: .Bx 4.3 ;
357: .Fl a
358: in
359: .Bx 4.3 Tahoe ;
360: .Fl c
361: and
362: .Fl m
363: in
364: .Bx 4.3 Reno ;
365: .Fl h
366: in
367: .Bx 4.3 Net/2 ;
368: .Fl C
369: in
370: .Nx 1.0 ;
371: .Fl s
372: and
373: .Fl S
374: in
1.21 schwarze 375: .Ox 2.3 ;
376: and
377: .Fl I ,
378: .Fl K ,
379: .Fl l ,
380: .Fl O ,
381: and
382: .Fl W
383: in
384: .Ox 5.7 .
385: The
386: .Fl T
387: option first appeared in
388: .At III
389: and was also added in
390: .Ox 5.7 .
CVSweb