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