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