| blob | c0895a87e4c32fd135ff059ea0b3bb5b839a87b7 |
1 .\" $Id: apropos.1,v 1.47 2018/02/23 18:54:02 schwarze Exp $
2 .\"
3 .\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
4 .\" Copyright (c) 2011, 2012, 2014, 2017 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: February 23 2018 $
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 afk
28 .Op Fl C Ar file
29 .Op Fl M Ar path
30 .Op Fl m Ar path
31 .Op Fl O Ar outkey
32 .Op Fl S Ar arch
33 .Op Fl s Ar section
34 .Ar expression ...
35 .Sh DESCRIPTION
36 The
37 .Nm apropos
38 and
39 .Nm whatis
40 utilities query manual page databases generated by
41 .Xr makewhatis 8 ,
42 evaluating
43 .Ar expression
44 for each file in each database.
45 By default, they display the names, section numbers, and description lines
46 of all matching manuals.
47 .Pp
48 By default,
49 .Nm
50 searches for
51 .Xr makewhatis 8
52 databases in the default paths stipulated by
53 .Xr man 1
54 and uses case-insensitive substring matching
55 .Pq the Cm = No operator
56 over manual names and descriptions
57 .Pq the Li \&Nm No and Li \&Nd No macro keys .
58 Multiple terms imply pairwise
59 .Fl o .
60 .Pp
61 .Nm whatis
62 is a synonym for
63 .Nm
64 .Fl f .
65 .Pp
66 The options are as follows:
67 .Bl -tag -width Ds
68 .It Fl a
69 Instead of showing only the title lines, show the complete manual pages,
70 just like
71 .Xr man 1
72 .Fl a
73 would.
74 If the standard output is a terminal device and
75 .Fl c
76 is not specified, use
77 .Xr more 1
78 to paginate them.
79 In
80 .Fl a
81 mode, the options
82 .Fl IKOTW
83 described in the
84 .Xr mandoc 1
85 manual are also available.
86 .It Fl C Ar file
87 Specify an alternative configuration
88 .Ar file
89 in
90 .Xr man.conf 5
91 format.
92 .It Fl f
93 Search for all words in
94 .Ar expression
95 in manual page names only.
96 The search is case insensitive and matches whole words only.
97 In this mode, macro keys, comparison operators, and logical operators
98 are not available.
99 .It Fl k
100 Support the full
101 .Ar expression
102 syntax.
103 It is the default for
104 .Nm .
105 .It Fl M Ar path
106 Use the colon-separated path instead of the default list of paths
107 searched for
108 .Xr makewhatis 8
109 databases.
110 Invalid paths, or paths without manual databases, are ignored.
111 .It Fl m Ar path
112 Prepend the colon-separated paths to the list of paths searched
113 for
114 .Xr makewhatis 8
115 databases.
116 Invalid paths, or paths without manual databases, are ignored.
117 .It Fl O Ar outkey
118 Show the values associated with the key
119 .Ar outkey
120 instead of the manual descriptions.
121 .It Fl S Ar arch
122 Restrict the search to pages for the specified
123 .Xr machine 1
124 architecture.
125 .Ar arch
126 is case insensitive.
127 By default, pages for all architectures are shown.
128 .It Fl s Ar section
129 Restrict the search to the specified section of the manual.
130 By default, pages from all sections are shown.
131 See
132 .Xr man 1
133 for a listing of sections.
134 .El
135 .Pp
136 The options
137 .Fl chlw
138 are also supported and are documented in
139 .Xr man 1 .
140 The options
141 .Fl fkl
142 are mutually exclusive and override each other.
143 .Pp
144 An
145 .Ar expression
146 consists of search terms joined by logical operators
147 .Fl a
148 .Pq and
149 and
150 .Fl o
151 .Pq or .
152 The
153 .Fl a
154 operator has precedence over
155 .Fl o
156 and both are evaluated left-to-right.
157 .Bl -tag -width Ds
158 .It \&( Ar expr No \&)
159 True if the subexpression
160 .Ar expr
161 is true.
162 .It Ar expr1 Fl a Ar expr2
163 True if both
164 .Ar expr1
165 and
166 .Ar expr2
167 are true (logical
168 .Sq and ) .
169 .It Ar expr1 Oo Fl o Oc Ar expr2
170 True if
171 .Ar expr1
172 and/or
173 .Ar expr2
174 evaluate to true (logical
175 .Sq or ) .
176 .It Ar term
177 True if
178 .Ar term
179 is satisfied.
180 This has syntax
181 .Sm off
182 .Oo
183 .Op Ar key Op , Ar key ...
184 .Pq Cm = | \(ti
185 .Oc
186 .Ar val ,
187 .Sm on
188 where
189 .Ar key
190 is an
191 .Xr mdoc 7
192 macro to query and
193 .Ar val
194 is its value.
195 See
196 .Sx Macro Keys
197 for a list of available keys.
198 Operator
199 .Cm =
200 evaluates a substring, while
201 .Cm \(ti
202 evaluates a regular expression.
203 .It Fl i Ar term
204 If
205 .Ar term
206 is a regular expression, it
207 is evaluated case-insensitively.
208 Has no effect on substring terms.
209 .El
210 .Pp
211 Results are sorted according to the following criteria:
212 .Bl -enum
213 .It
214 The manpath directory tree the page is found in, according to the
215 order specified with
216 .Fl M ,
217 .Fl m ,
218 the
219 .Ev MANPATH
220 environment variable, the
221 .Xr man.conf 5
222 configuration file, or the default documented in
223 .Xr man.conf 5 .
224 .It
225 The section number in ascending numerical order.
226 .It
227 The page name in ascending
228 .Xr ascii 7
229 alphabetical order, case-insensitive.
230 .El
231 .Pp
232 Each output line is formatted as
233 .Pp
234 .D1 name[, name...](sec) \- description
235 .Pp
236 Where
237 .Dq name
238 is the manual's name,
239 .Dq sec
240 is the manual section, and
241 .Dq description
242 is the manual's short description.
243 If an architecture is specified for the manual, it is displayed as
244 .Pp
245 .D1 name(sec/arch) \- description
246 .Pp
247 Resulting manuals may be accessed as
248 .Pp
249 .Dl $ man \-s sec name
250 .Pp
251 If an architecture is specified in the output, use
252 .Pp
253 .Dl $ man \-s sec \-S arch name
254 .Ss Macro Keys
255 Queries evaluate over a subset of
256 .Xr mdoc 7
257 macros indexed by
258 .Xr makewhatis 8 .
259 In addition to the macro keys listed below, the special key
260 .Cm any
261 may be used to match any available macro key.
262 .Pp
263 Names and description:
264 .Bl -column "xLix" description -offset indent -compact
265 .It Li \&Nm Ta manual name
266 .It Li \&Nd Ta one-line manual description
267 .It Li arch Ta machine architecture (case-insensitive)
268 .It Li sec Ta manual section number
269 .El
270 .Pp
271 Sections and cross references:
272 .Bl -column "xLix" description -offset indent -compact
273 .It Li \&Sh Ta section header (excluding standard sections)
274 .It Li \&Ss Ta subsection header
275 .It Li \&Xr Ta cross reference to another manual page
276 .It Li \&Rs Ta bibliographic reference
277 .El
278 .Pp
279 Semantic markup for command line utilities:
280 .Bl -column "xLix" description -offset indent -compact
281 .It Li \&Fl Ta command line options (flags)
282 .It Li \&Cm Ta command modifier
283 .It Li \&Ar Ta command argument
284 .It Li \&Ic Ta internal or interactive command
285 .It Li \&Ev Ta environmental variable
286 .It Li \&Pa Ta file system path
287 .El
288 .Pp
289 Semantic markup for function libraries:
290 .Bl -column "xLix" description -offset indent -compact
291 .It Li \&Lb Ta function library name
292 .It Li \&In Ta include file
293 .It Li \&Ft Ta function return type
294 .It Li \&Fn Ta function name
295 .It Li \&Fa Ta function argument type and name
296 .It Li \&Vt Ta variable type
297 .It Li \&Va Ta variable name
298 .It Li \&Dv Ta defined variable or preprocessor constant
299 .It Li \&Er Ta error constant
300 .It Li \&Ev Ta environmental variable
301 .El
302 .Pp
303 Various semantic markup:
304 .Bl -column "xLix" description -offset indent -compact
305 .It Li \&An Ta author name
306 .It Li \&Lk Ta hyperlink
307 .It Li \&Mt Ta Do mailto Dc hyperlink
308 .It Li \&Cd Ta kernel configuration declaration
309 .It Li \&Ms Ta mathematical symbol
310 .It Li \&Tn Ta tradename
311 .El
312 .Pp
313 Physical markup:
314 .Bl -column "xLix" description -offset indent -compact
315 .It Li \&Em Ta italic font or underline
316 .It Li \&Sy Ta boldface font
317 .It Li \&Li Ta typewriter font
318 .El
319 .Pp
320 Text production:
321 .Bl -column "xLix" description -offset indent -compact
322 .It Li \&St Ta reference to a standards document
323 .It Li \&At Ta At No version reference
324 .It Li \&Bx Ta Bx No version reference
325 .It Li \&Bsx Ta Bsx No version reference
326 .It Li \&Nx Ta Nx No version reference
327 .It Li \&Fx Ta Fx No version reference
328 .It Li \&Ox Ta Ox No version reference
329 .It Li \&Dx Ta Dx No version reference
330 .El
331 .Pp
332 In general, macro keys are supposed to yield complete results without
333 expecting the user to consider actual macro usage.
334 For example, results include:
335 .Pp
336 .Bl -tag -width 3n -offset 3n -compact
337 .It Li \&Fa
338 function arguments appearing on
339 .Ic \&Fn
340 lines
341 .It Li \&Fn
342 fuction names marked up with
343 .Ic \&Fo
344 macros
345 .It Li \&In
346 include file names marked up with
347 .Ic \&Fd
348 macros
349 .It Li \&Vt
350 types appearing as function return types and
351 .It \&
352 types appearing in function arguments in the SYNOPSIS
353 .El
354 .Sh ENVIRONMENT
355 .Bl -tag -width MANPAGER
356 .It Ev MANPAGER
357 Any non-empty value of the environment variable
358 .Ev MANPAGER
359 is used instead of the standard pagination program,
360 .Xr more 1 ;
361 see
362 .Xr man 1
363 for details.
364 Only used if
365 .Fl a
366 or
367 .Fl l
368 is specified.
369 .It Ev MANPATH
370 A colon-separated list of directories to search for manual pages; see
371 .Xr man 1
372 for details.
373 Overridden by
374 .Fl M ,
375 ignored if
376 .Fl l
377 is specified.
378 .It Ev PAGER
379 Specifies the pagination program to use when
380 .Ev MANPAGER
381 is not defined.
382 If neither PAGER nor MANPAGER is defined,
383 .Xr more 1
384 .Fl s
385 is used.
386 Only used if
387 .Fl a
388 or
389 .Fl l
390 is specified.
391 .El
392 .Sh FILES
393 .Bl -tag -width "/etc/man.conf" -compact
394 .It Pa mandoc.db
395 name of the
396 .Xr makewhatis 8
397 keyword database
398 .It Pa /etc/man.conf
399 default
400 .Xr man 1
401 configuration file
402 .El
403 .Sh EXIT STATUS
404 .Ex -std
405 .Sh EXAMPLES
406 Search for
407 .Qq .cf
408 as a substring of manual names and descriptions:
409 .Pp
410 .Dl $ apropos .cf
411 .Pp
412 Include matches for
413 .Qq .cnf
414 and
415 .Qq .conf
416 as well:
417 .Pp
418 .Dl $ apropos .cf .cnf .conf
419 .Pp
420 Search in names and descriptions using a regular expression:
421 .Pp
422 .Dl $ apropos \(aq\(tiset.?[ug]id\(aq
423 .Pp
424 Search for manuals in the library section mentioning both the
425 .Qq optind
426 and the
427 .Qq optarg
428 variables:
429 .Pp
430 .Dl $ apropos \-s 3 Va=optind \-a Va=optarg
431 .Pp
432 Do exactly the same as calling
433 .Nm whatis
434 with the argument
435 .Qq ssh :
436 .Pp
437 .Dl $ apropos \-\- \-i \(aqNm\(ti[[:<:]]ssh[[:>:]]\(aq
438 .Pp
439 The following two invocations are equivalent:
440 .Pp
441 .D1 Li $ apropos -S Ar arch Li -s Ar section expression
442 .Bd -ragged -offset indent
443 .Li $ apropos \e( Ar expression Li \e)
444 .Li -a arch\(ti^( Ns Ar arch Ns Li |any)$
445 .Li -a sec\(ti^ Ns Ar section Ns Li $
446 .Ed
447 .Sh SEE ALSO
448 .Xr man 1 ,
449 .Xr re_format 7 ,
450 .Xr makewhatis 8
451 .Sh HISTORY
452 Part of the functionality of
453 .Nm whatis
454 was already provided by the former
455 .Nm manwhere
456 utility in
457 .Bx 1 .
458 The
459 .Nm
460 and
461 .Nm whatis
462 utilities first appeared in
463 .Bx 2 .
464 They were rewritten from scratch for
465 .Ox 5.6 .
466 .Pp
467 The
468 .Fl M
469 option and the
470 .Ev MANPATH
471 variable first appeared in
472 .Bx 4.3 ;
473 .Fl m
474 in
475 .Bx 4.3 Reno ;
476 .Fl C
477 in
478 .Bx 4.4 Lite1 ;
479 and
480 .Fl S
481 and
482 .Fl s
483 in
484 .Ox 4.5
485 for
486 .Nm
487 and in
488 .Ox 5.6
489 for
490 .Nm whatis .
491 The options
492 .Fl acfhIKklOTWw
493 appeared in
494 .Ox 5.7 .
495 .Sh AUTHORS
496 .An -nosplit
497 .An Bill Joy
498 wrote
499 .Nm manwhere
500 in 1977 and the original
501 .Bx
502 .Nm
503 and
504 .Nm whatis
505 in February 1979.
506 The current version was written by
507 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
508 and
509 .An Ingo Schwarze Aq Mt schwarze@openbsd.org .