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