man(1): import man(1) replacement
[dragonfly.git] / usr.bin / man / man.1
1 .\"     $NetBSD: man.1,v 1.26 2013/07/18 03:40:31 uwe Exp $
2 .\"
3 .\" Copyright (c) 1989, 1990, 1993
4 .\"     The Regents of the University of California.  All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\"    notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\"    notice, this list of conditions and the following disclaimer in the
13 .\"    documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\"    may be used to endorse or promote products derived from this software
16 .\"    without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\"     @(#)man.1       8.2 (Berkeley) 1/2/94
31 .\"
32 .Dd October 7, 2011
33 .Dt MAN 1
34 .Os
35 .Sh NAME
36 .Nm man
37 .Nd display the on-line manual pages
38 .Pq aka Dq Em man pages
39 .Sh SYNOPSIS
40 .Nm
41 .Oo Fl acw Ns \&| Ns Fl h Oc
42 .Op Fl C Ar file
43 .Op Fl M Ar path
44 .Op Fl m Ar path
45 .Op Fl S Ar srch
46 .Oo
47 .Op Fl s
48 .Ar section
49 .Oc
50 .Ar name Ar ...
51 .Nm
52 .Fl k
53 .Op Fl C Ar file
54 .Op Fl M Ar path
55 .Op Fl m Ar path
56 .Ar keyword Ar ...
57 .Nm
58 .Fl p
59 .Sh DESCRIPTION
60 The
61 .Nm
62 utility displays the manual pages named on the command line.
63 Its options are as follows:
64 .Bl -tag -width indent
65 .It Fl a
66 Display all of the man pages for a specified
67 .Ar section
68 and
69 .Ar name
70 combination.
71 (Normally, only the first man page found is displayed.)
72 .It Fl C
73 Use the specified
74 .Ar file
75 instead of the default configuration file.
76 This permits users to configure their own man environment.
77 See
78 .Xr man.conf 5
79 for a description of the contents of this file.
80 .It Fl c
81 Copy the man page to the standard output instead of using
82 .Xr more 1
83 to paginate it.
84 This is done by default if the standard output is not a terminal device.
85 .It Fl h
86 Display only the
87 .Dq Tn SYNOPSIS
88 lines of the requested man pages.
89 For commands, this is typically the command line usage information.
90 For library functions, this usually contains the required include
91 files and function prototypes.
92 .It Fl k
93 Display the header lines for any man pages matching
94 .Ar keyword Ns Pq s ,
95 in the same manner as
96 .Xr apropos 1 .
97 .It Fl M
98 Override the list of standard directories which
99 .Nm
100 searches for man pages.
101 The supplied
102 .Ar path
103 must be a colon
104 .Pq Dq \&:
105 separated list of directories.
106 This search path may also be set using the environment variable
107 .Ev MANPATH .
108 The subdirectories to be searched, and their search order,
109 is specified by the
110 .Dq _subdir
111 line in the
112 .Nm
113 configuration file.
114 .It Fl m
115 Augment the list of standard directories which
116 .Nm
117 searches for man pages.
118 The supplied
119 .Ar path
120 must be a colon
121 .Pq Dq \&:
122 separated list of directories.
123 These directories will be searched before the standard directories or
124 the directories specified using the
125 .Fl M
126 option or the
127 .Ev MANPATH
128 environment variable.
129 The subdirectories to be searched, and their search order,
130 is specified by the
131 .Dq _subdir
132 line in the
133 .Nm
134 configuration file.
135 .It Fl p
136 Print the search path for the manual pages.
137 .It Fl s
138 Restrict the directories that
139 .Nm
140 will search to the specified section.
141 The
142 .Nm
143 configuration file (see
144 .Xr man.conf 5 )
145 specifies the possible
146 .Ar section
147 values that are currently available.
148 .It Fl S
149 Display only man pages that have the specified string in the directory
150 part of their filenames.
151 This allows the man page search process criteria to be
152 narrowed without having to change the MANPATH or
153 .Dq _default
154 variables.
155 .It Fl w
156 List the pathnames of the man pages which
157 .Nm
158 would display for the specified
159 .Ar section
160 and
161 .Ar name
162 combination.
163 .El
164 .Pp
165 If the
166 .Ql Fl s
167 option is not specified,
168 there is more than one argument,
169 the
170 .Ql Fl k
171 option is not used, and the first argument is a valid section, then that
172 argument will be used as if specified by the
173 .Ql Fl s
174 option.
175 .Pp
176 If
177 .Ar name
178 is given with a full or relative path then
179 .Nm
180 interprets it as a file specification, so that you can do
181 .Nm
182 .Cm ./foo.5
183 or even
184 .Nm
185 .Cm /cd/foo/bar.1.gz .
186 .Sh ENVIRONMENT
187 .Bl -tag -width MANPATHX
188 .It Ev MACHINE
189 As some man pages are intended only for specific architectures,
190 .Nm
191 searches any subdirectories,
192 with the same name as the current architecture,
193 in every directory which it searches.
194 Machine specific areas are checked before general areas.
195 The current machine type may be overridden by setting the environment
196 variable
197 .Ev MACHINE
198 to the name of a specific architecture.
199 .It Ev MANPATH
200 The standard search path used by
201 .Nm
202 may be overridden by specifying a path in the
203 .Ev MANPATH
204 environment variable.
205 The format of the path is a colon
206 .Pq Dq \&:
207 separated list of directories.
208 The subdirectories to be searched as well as their search order
209 is specified by the
210 .Dq _subdir
211 line in the
212 .Nm
213 configuration file.
214 .It Ev PAGER
215 The pagination command used for writing the output.
216 If the
217 .Ev PAGER
218 environment variable is null or not set, the standard pagination program
219 .Xr more 1
220 will be used.
221 .El
222 .Sh FILES
223 .Bl -hang -width /etc/man.conf -compact
224 .It Pa /etc/man.conf
225 default man configuration file.
226 .El
227 .Sh SEE ALSO
228 .Xr apropos 1 ,
229 .Xr whatis 1 ,
230 .Xr whereis 1 ,
231 .Xr man.conf 5 ,
232 .Xr mdoc 7 ,
233 .Xr mdoc.samples 7
234 .Sh STANDARDS
235 .Nm
236 conforms to
237 .St -xcu5 .
238 .\"and is expected to conform to
239 .\".St -p1003.2-?? .
240 .Sh BUGS
241 The on-line man pages are, by necessity, forgiving toward stupid
242 display devices, causing a few man pages to be not as nicely formatted
243 as their typeset counterparts.