| blob | 14682420ff0046ce63faab7f4a157f6e0c7ef3d6 |
1 .\" $Id: apropos.1,v 1.29 2014/04/24 00:28:19 schwarze Exp $
2 .\"
3 .\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
4 .\" Copyright (c) 2011, 2012, 2014 Ingo Schwarze <schwarze@openbsd.org>
5 .\"
6 .\" Permission to use, copy, modify, and distribute this software for any
7 .\" purpose with or without fee is hereby granted, provided that the above
8 .\" copyright notice and this permission notice appear in all copies.
9 .\"
10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 .\"
18 .Dd $Mdocdate: April 24 2014 $
19 .Dt APROPOS 1
20 .Os
21 .Sh NAME
22 .Nm apropos ,
23 .Nm whatis
24 .Nd search manual page databases
25 .Sh SYNOPSIS
26 .Nm
27 .Op Fl C Ar file
28 .Op Fl M Ar path
29 .Op Fl m Ar path
30 .Op Fl O Ar outkey
31 .Op Fl S Ar arch
32 .Op Fl s Ar section
33 .Ar expression ...
34 .Sh DESCRIPTION
35 The
36 .Nm apropos
37 and
38 .Nm whatis
39 utilities query manual page databases generated by
40 .Xr makewhatis 8 ,
41 evaluating
42 .Ar expression
43 for each file in each database.
44 By default, it displays the names, section numbers, and description lines
45 of all matching manuals.
46 .Pp
47 By default,
48 .Nm
49 searches for
50 .Xr makewhatis 8
51 databases in the default paths stipulated by
52 .Xr man 1
53 and uses case-insensitive substring matching
54 .Pq the Cm = No operator
55 over manual names and descriptions
56 .Pq the Li \&Nm No and Li \&Nd No macro keys .
57 Multiple terms imply pairwise
58 .Fl o .
59 .Nm whatis
60 maps terms only to case-sensitive manual names.
61 .Pp
62 Its arguments are as follows:
63 .Bl -tag -width Ds
64 .It Fl C Ar file
65 Specify an alternative configuration
66 .Ar file
67 in
68 .Xr man.conf 5
69 format.
70 .It Fl M Ar path
71 Use the colon-separated path instead of the default list of paths
72 searched for
73 .Xr makewhatis 8
74 databases.
75 Invalid paths, or paths without manual databases, are ignored.
76 .It Fl m Ar path
77 Prepend the colon-separated paths to the list of paths searched
78 for
79 .Xr makewhatis 8
80 databases.
81 Invalid paths, or paths without manual databases, are ignored.
82 .It Fl O Ar outkey
83 Show the values associated with the key
84 .Ar outkey
85 instead of the manual descriptions.
86 .It Fl S Ar arch
87 Restrict the search to pages for the specified
88 .Xr machine 1
89 architecture.
90 .Ar arch
91 is case insensitive.
92 By default, pages for all architectures are shown.
93 .It Fl s Ar section
94 Restrict the search to the specified section of the manual.
95 By default, pages from all sections are shown.
96 See
97 .Xr man 1
98 for a listing of sections.
99 .El
100 .Pp
101 An
102 .Ar expression
103 consists of search terms joined by logical operators
104 .Fl a
105 .Pq and
106 and
107 .Fl o
108 .Pq or .
109 The
110 .Fl a
111 operator has precedence over
112 .Fl o
113 and both are evaluated left-to-right.
114 .Bl -tag -width Ds
115 .It \&( Ar expr No \&)
116 True if the subexpression
117 .Ar expr
118 is true.
119 .It Ar expr1 Fl a Ar expr2
120 True if both
121 .Ar expr1
122 and
123 .Ar expr2
124 are true (logical
125 .Sq and ) .
126 .It Ar expr1 Oo Fl o Oc Ar expr2
127 True if
128 .Ar expr1
129 and/or
130 .Ar expr2
131 evaluate to true (logical
132 .Sq or ) .
133 .It Ar term
134 True if
135 .Ar term
136 is satisfied.
137 This has syntax
138 .Sm off
139 .Oo
140 .Op Ar key Op , Ar key ...
141 .Pq Cm = | ~
142 .Oc
143 .Ar val ,
144 .Sm on
145 where
146 .Ar key
147 is an
148 .Xr mdoc 7
149 macro to query and
150 .Ar val
151 is its value.
152 See
153 .Sx Macro Keys
154 for a list of available keys.
155 Operator
156 .Cm =
157 evaluates a substring, while
158 .Cm ~
159 evaluates a regular expression.
160 .It Fl i Ar term
161 If
162 .Ar term
163 is a regular expression, it
164 is evaluated case-insensitively.
165 Has no effect on substring terms.
166 .El
167 .Pp
168 .Nm whatis
169 considers an
170 .Ar expression
171 to consist of an opaque keyword.
172 .Pp
173 Results are sorted by manual sections and names, with output formatted as
174 .Pp
175 .D1 name[, name...](sec) \- description
176 .Pp
177 Where
178 .Dq name
179 is the manual's name,
180 .Dq sec
181 is the manual section, and
182 .Dq description
183 is the manual's short description.
184 If an architecture is specified for the manual, it is displayed as
185 .Pp
186 .D1 name(sec/arch) \- description
187 .Pp
188 Resulting manuals may be accessed as
189 .Pp
190 .Dl $ man \-s sec name
191 .Pp
192 If an architecture is specified in the output, use
193 .Pp
194 .Dl $ man \-s sec \-S arch name
195 .Ss Macro Keys
196 Queries evaluate over a subset of
197 .Xr mdoc 7
198 macros indexed by
199 .Xr makewhatis 8 .
200 In addition to the macro keys listed below, the special key
201 .Cm any
202 may be used to match any available macro key.
203 .Pp
204 Names and description:
205 .Bl -column "xLix" description -offset indent -compact
206 .It Li \&Nm Ta manual name
207 .It Li \&Nd Ta one-line manual description
208 .It Li arch Ta machine architecture (case-insensitive)
209 .It Li sec Ta manual section number
210 .El
211 .Pp
212 Sections and cross references:
213 .Bl -column "xLix" description -offset indent -compact
214 .It Li \&Sh Ta section header (excluding standard sections)
215 .It Li \&Ss Ta subsection header
216 .It Li \&Xr Ta cross reference to another manual page
217 .It Li \&Rs Ta bibliographic reference
218 .El
219 .Pp
220 Semantic markup for command line utilities:
221 .Bl -column "xLix" description -offset indent -compact
222 .It Li \&Fl Ta command line options (flags)
223 .It Li \&Cm Ta command modifier
224 .It Li \&Ar Ta command argument
225 .It Li \&Ic Ta internal or interactive command
226 .It Li \&Ev Ta environmental variable
227 .It Li \&Pa Ta file system path
228 .El
229 .Pp
230 Semantic markup for function libraries:
231 .Bl -column "xLix" description -offset indent -compact
232 .It Li \&Lb Ta function library name
233 .It Li \&In Ta include file
234 .It Li \&Ft Ta function return type
235 .It Li \&Fn Ta function name
236 .It Li \&Fa Ta function argument type and name
237 .It Li \&Vt Ta variable type
238 .It Li \&Va Ta variable name
239 .It Li \&Dv Ta defined variable or preprocessor constant
240 .It Li \&Er Ta error constant
241 .It Li \&Ev Ta environmental variable
242 .El
243 .Pp
244 Various semantic markup:
245 .Bl -column "xLix" description -offset indent -compact
246 .It Li \&An Ta author name
247 .It Li \&Lk Ta hyperlink
248 .It Li \&Mt Ta Do mailto Dc hyperlink
249 .It Li \&Cd Ta kernel configuration declaration
250 .It Li \&Ms Ta mathematical symbol
251 .It Li \&Tn Ta tradename
252 .El
253 .Pp
254 Physical markup:
255 .Bl -column "xLix" description -offset indent -compact
256 .It Li \&Em Ta italic font or underline
257 .It Li \&Sy Ta boldface font
258 .It Li \&Li Ta typewriter font
259 .El
260 .Pp
261 Text production:
262 .Bl -column "xLix" description -offset indent -compact
263 .It Li \&St Ta reference to a standards document
264 .It Li \&At Ta At No version reference
265 .It Li \&Bx Ta Bx No version reference
266 .It Li \&Bsx Ta Bsx No version reference
267 .It Li \&Nx Ta Nx No version reference
268 .It Li \&Fx Ta Fx No version reference
269 .It Li \&Ox Ta Ox No version reference
270 .It Li \&Dx Ta Dx No version reference
271 .El
272 .Sh ENVIRONMENT
273 .Bl -tag -width MANPATH
274 .It Ev MANPATH
275 The standard search path used by
276 .Xr man 1
277 may be changed by specifying a path in the
278 .Ev MANPATH
279 environment variable.
280 Invalid paths, or paths without manual databases, are ignored.
281 Overridden by
282 .Fl M .
283 If
284 .Ev MANPATH
285 begins with a colon, it is appended to the default list;
286 if it ends with a colon, it is prepended to the default list;
287 or if it contains two adjacent colons,
288 the standard search path is inserted between the colons.
289 If none of these conditions are met, it overrides the
290 standard search path.
291 .El
292 .Sh FILES
293 .Bl -tag -width "/etc/man.conf" -compact
294 .It Pa mandoc.db
295 name of the
296 .Xr makewhatis 8
297 keyword database
298 .It Pa /etc/man.conf
299 default
300 .Xr man 1
301 configuration file
302 .El
303 .Sh EXIT STATUS
304 .Ex -std
305 .Sh EXAMPLES
306 Search for
307 .Qq .cf
308 as a substring of manual names and descriptions:
309 .Pp
310 .Dl $ apropos .cf
311 .Pp
312 Include matches for
313 .Qq .cnf
314 and
315 .Qq .conf
316 as well:
317 .Pp
318 .Dl $ apropos .cf .cnf .conf
319 .Pp
320 Search in names and descriptions using a regular expression:
321 .Pp
322 .Dl $ apropos '~set.?[ug]id'
323 .Pp
324 Search for manuals in the library section mentioning both the
325 .Qq optind
326 and the
327 .Qq optarg
328 variables:
329 .Pp
330 .Dl $ apropos \-s 3 Va=optind \-a Va=optarg
331 .Pp
332 Do exactly the same as calling
333 .Xr whatis 1
334 with the argument
335 .Qq ssh :
336 .Pp
337 .Dl $ apropos \-\- \-i 'Nm~[[:<:]]ssh[[:>:]]'
338 .Pp
339 The following two invocations are equivalent:
340 .Pp
341 .D1 Li $ apropos -S Ar arch Li -s Ar section expression
342 .Bd -ragged -offset indent
343 .Li $ apropos \e( Ar expression Li \e)
344 .Li -a arch~^( Ns Ar arch Ns Li |any)$
345 .Li -a sec~^ Ns Ar section Ns Li $
346 .Ed
347 .Sh SEE ALSO
348 .Xr man 1 ,
349 .Xr re_format 7 ,
350 .Xr makewhatis 8
351 .Sh HISTORY
352 An
353 .Nm
354 utility first appeared in
355 .Bx 2 .
356 It was rewritten from scratch for
357 .Ox 5.6 .
358 .Pp
359 The
360 .Fl M
361 option and the
362 .Ev MANPATH
363 variable first appeared in
364 .Bx 4.3 ;
365 .Fl m
366 in
367 .Bx 4.3 Reno ;
368 .Fl C
369 in
370 .Bx 4.4 Lite1 ;
371 and
372 .Fl S
373 and
374 .Fl s
375 in
376 .Ox 4.5 .
377 .Sh AUTHORS
378 .An -nosplit
379 .An Bill Joy
380 wrote the original
381 .Bx
382 .Nm
383 in February 1979.
384 The current version was written by
385 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
386 and
387 .An Ingo Schwarze Aq Mt schwarze@openbsd.org .