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