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