Annotation of mandoc/apropos.1, Revision 1.26
1.26 ! schwarze 1: .\" $Id: apropos.1,v 1.25 2014/04/04 15:55:19 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.25 schwarze 18: .Dd $Mdocdate: April 4 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.13 schwarze 27: .Op Fl C Ar file
1.20 schwarze 28: .Op Fl M Ar path
29: .Op Fl m Ar path
1.24 schwarze 30: .Op Fl O Ar outkey
1.3 kristaps 31: .Op Fl S Ar arch
32: .Op Fl s Ar section
1.13 schwarze 33: .Ar expression ...
1.1 kristaps 34: .Sh DESCRIPTION
35: The
1.19 kristaps 36: .Nm apropos
37: and
38: .Nm whatis
39: utilities query manual page databases generated by
1.8 kristaps 40: .Xr mandocdb 8 ,
1.4 kristaps 41: evaluating on
42: .Ar expression
1.5 kristaps 43: for each file in each database.
1.16 kristaps 44: .Pp
45: By default,
46: .Nm
47: searches for
48: .Xr mandocdb 8
49: databases in the default paths stipulated by
1.23 schwarze 50: .Xr man 1 ,
51: parses terms as case-sensitive regular expressions
52: .Pq the Li \&~ operator
53: over manual names and descriptions
54: .Pq the Li \&Nm No and Li \&Nd No macro keys .
55: Multiple terms imply pairwise
56: .Fl o .
1.19 kristaps 57: .Nm whatis
58: maps terms only to case-sensitive manual names.
1.16 kristaps 59: .Pp
1.1 kristaps 60: Its arguments are as follows:
61: .Bl -tag -width Ds
1.13 schwarze 62: .It Fl C Ar file
63: Specify an alternative configuration
64: .Ar file
65: in
66: .Xr man.conf 5
67: format.
1.20 schwarze 68: .It Fl M Ar path
1.7 kristaps 69: Use the colon-separated path instead of the default list of paths
70: searched for
71: .Xr mandocdb 8
72: databases.
73: Invalid paths, or paths without manual databases, are ignored.
1.20 schwarze 74: .It Fl m Ar path
1.9 schwarze 75: Prepend the colon-separated paths to the list of paths searched
1.6 kristaps 76: for
1.5 kristaps 77: .Xr mandocdb 8
78: databases.
1.6 kristaps 79: Invalid paths, or paths without manual databases, are ignored.
1.24 schwarze 80: .It Fl O Ar outkey
81: Show the values associated with the key
82: .Ar outkey
83: instead of the manual descriptions.
1.3 kristaps 84: .It Fl S Ar arch
1.23 schwarze 85: Restrict the search to pages for the specified
86: .Xr machine 1
87: architecture.
88: .Ar arch
89: is case insensitive.
90: By default, pages for all architectures are shown.
91: .It Fl s Ar section
92: Restrict the search to the specified section of the manual.
93: By default, pages from all sections are shown.
1.1 kristaps 94: See
95: .Xr man 1
1.23 schwarze 96: for a listing of sections.
1.4 kristaps 97: .El
98: .Pp
1.23 schwarze 99: An
1.4 kristaps 100: .Ar expression
1.23 schwarze 101: consists of search terms joined by logical operators
102: .Fl a
103: .Pq and
104: and
105: .Fl o
106: .Pq or .
107: The
108: .Fl a
109: operator has precedence over
110: .Fl o
111: and both are evaluated left-to-right.
112: .Bl -tag -width Ds
113: .It \&( Ar expr No \&)
114: True if the subexpression
115: .Ar expr
116: is true.
117: .It Ar expr1 Fl a Ar expr2
118: True if both
119: .Ar expr1
120: and
121: .Ar expr2
122: are true (logical
123: .Qq and ) .
124: .It Ar expr1 Oo Fl o Oc Ar expr2
125: True if
126: .Ar expr1
127: and/or
128: .Ar expr2
129: evaluate to true (logical
130: .Qq or ) .
131: .It Ar term
132: True if
133: .Ar term
134: is satisfied.
135: This has syntax
1.4 kristaps 136: .Li [key[,key]*(=~)]?val ,
137: where operand
1.10 kristaps 138: .Cm key
1.4 kristaps 139: is an
140: .Xr mdoc 7
141: macro to query and
1.10 kristaps 142: .Cm val
1.4 kristaps 143: is its value.
1.10 kristaps 144: See
145: .Sx Macro Keys
146: for a list of available keys.
1.4 kristaps 147: Operator
148: .Li \&=
1.23 schwarze 149: evaluates a substring, while
1.4 kristaps 150: .Li \&~
1.23 schwarze 151: evaluates a regular expression.
152: .It Fl i Ar term
153: If
154: .Ar term
155: is a regular expression, it
156: is evaluated case-insensitively.
157: Has no effect on substring terms.
158: .El
159: .Pp
160: .Nm whatis
161: considers an
162: .Ar expression
163: to consist of an opaque keyword.
1.1 kristaps 164: .Pp
1.4 kristaps 165: Results are sorted by manual title, with output formatted as
1.23 schwarze 166: .Pp
167: .D1 title(sec) \- description
168: .Pp
169: Where
1.1 kristaps 170: .Qq title
171: is the manual's title (note multiple manual names may exist for one
172: title),
1.3 kristaps 173: .Qq sec
174: is the manual section, and
1.1 kristaps 175: .Qq description
176: is the manual's short description.
177: If an architecture is specified for the manual, it is displayed as
1.23 schwarze 178: .Pp
179: .D1 title(cat/arch) \- description
180: .Pp
181: Resulting manuals may be accessed as
182: .Pp
183: .Dl $ man \-s sec title
184: .Pp
185: If an architecture is specified in the output, use
186: .Pp
187: .Dl $ man \-s sec \-S arch title
1.10 kristaps 188: .Ss Macro Keys
1.23 schwarze 189: Queries evaluate over a subset of
1.10 kristaps 190: .Xr mdoc 7
191: macros indexed by
192: .Xr mandocdb 8 .
193: In addition to the macro keys listed below, the special key
194: .Cm any
195: may be used to match any available macro key.
196: .Pp
197: Names and description:
198: .Bl -column "xLix" description -offset indent -compact
199: .It Li \&Nm Ta manual name
200: .It Li \&Nd Ta one-line manual description
1.24 schwarze 201: .It Li arch Ta machine architecture (case-insensitive)
202: .It Li sec Ta manual section number
1.10 kristaps 203: .El
204: .Pp
205: Sections and cross references:
206: .Bl -column "xLix" description -offset indent -compact
207: .It Li \&Sh Ta section header (excluding standard sections)
208: .It Li \&Ss Ta subsection header
209: .It Li \&Xr Ta cross reference to another manual page
210: .It Li \&Rs Ta bibliographic reference
211: .El
212: .Pp
213: Semantic markup for command line utilities:
214: .Bl -column "xLix" description -offset indent -compact
215: .It Li \&Fl Ta command line options (flags)
216: .It Li \&Cm Ta command modifier
217: .It Li \&Ar Ta command argument
218: .It Li \&Ic Ta internal or interactive command
219: .It Li \&Ev Ta environmental variable
220: .It Li \&Pa Ta file system path
221: .El
222: .Pp
223: Semantic markup for function libraries:
224: .Bl -column "xLix" description -offset indent -compact
225: .It Li \&Lb Ta function library name
226: .It Li \&In Ta include file
227: .It Li \&Ft Ta function return type
228: .It Li \&Fn Ta function name
229: .It Li \&Fa Ta function argument type and name
230: .It Li \&Vt Ta variable type
231: .It Li \&Va Ta variable name
232: .It Li \&Dv Ta defined variable or preprocessor constant
233: .It Li \&Er Ta error constant
234: .It Li \&Ev Ta environmental variable
235: .El
236: .Pp
237: Various semantic markup:
238: .Bl -column "xLix" description -offset indent -compact
239: .It Li \&An Ta author name
240: .It Li \&Lk Ta hyperlink
241: .It Li \&Mt Ta Do mailto Dc hyperlink
242: .It Li \&Cd Ta kernel configuration declaration
243: .It Li \&Ms Ta mathematical symbol
244: .It Li \&Tn Ta tradename
245: .El
246: .Pp
247: Physical markup:
248: .Bl -column "xLix" description -offset indent -compact
249: .It Li \&Em Ta italic font or underline
250: .It Li \&Sy Ta boldface font
251: .It Li \&Li Ta typewriter font
252: .El
253: .Pp
254: Text production:
255: .Bl -column "xLix" description -offset indent -compact
256: .It Li \&St Ta reference to a standards document
257: .It Li \&At Ta At No version reference
258: .It Li \&Bx Ta Bx No version reference
259: .It Li \&Bsx Ta Bsx No version reference
260: .It Li \&Nx Ta Nx No version reference
261: .It Li \&Fx Ta Fx No version reference
262: .It Li \&Ox Ta Ox No version reference
263: .It Li \&Dx Ta Dx No version reference
264: .El
1.6 kristaps 265: .Sh ENVIRONMENT
1.23 schwarze 266: .Bl -tag -width MANPATH
1.6 kristaps 267: .It Ev MANPATH
1.23 schwarze 268: The standard search path used by
269: .Xr man 1
270: may be changed by specifying a path in the
271: .Ev MANPATH
272: environment variable.
1.6 kristaps 273: Invalid paths, or paths without manual databases, are ignored.
1.9 schwarze 274: Overridden by
1.7 kristaps 275: .Fl M .
1.14 kristaps 276: If
277: .Ev MANPATH
1.23 schwarze 278: begins with a colon, it is appended to the default list;
279: if it ends with a colon, it is prepended to the default list;
280: or if it contains two adjacent colons,
281: the standard search path is inserted between the colons.
282: If none of these conditions are met, it overrides the
283: standard search path.
1.13 schwarze 284: .El
285: .Sh FILES
286: .Bl -tag -width "/etc/man.conf" -compact
1.22 schwarze 287: .It Pa mandoc.db
1.13 schwarze 288: name of the
289: .Xr mandocdb 8
290: keyword database
291: .It Pa /etc/man.conf
292: default
293: .Xr man 1
294: configuration file
1.6 kristaps 295: .El
1.1 kristaps 296: .Sh EXIT STATUS
297: .Ex -std
298: .Sh EXAMPLES
299: Search for
1.23 schwarze 300: .Qq .cf
301: as a substring of manual names and descriptions:
1.4 kristaps 302: .Pp
1.23 schwarze 303: .Dl $ apropos .cf
1.4 kristaps 304: .Pp
1.11 kristaps 305: Include matches for
1.23 schwarze 306: .Qq .cnf
1.11 kristaps 307: and
1.23 schwarze 308: .Qq .conf
309: as well:
310: .Pp
311: .Dl $ apropos .cf .cnf .conf
312: .Pp
313: Search in names and descriptions using a regular expression:
1.4 kristaps 314: .Pp
1.23 schwarze 315: .Dl $ apropos '~set.?[ug]id'
1.4 kristaps 316: .Pp
1.23 schwarze 317: Search for manuals in the library category mentioning both the
318: .Qq optind
319: and the
1.4 kristaps 320: .Qq optarg
1.23 schwarze 321: variables:
322: .Pp
323: .Dl $ apropos \-s 3 Va=optind \-a Va=optarg
1.1 kristaps 324: .Pp
1.23 schwarze 325: Do exactly the same as calling
326: .Xr whatis 1
327: with the argument
328: .Qq ssh :
329: .Pp
330: .Dl $ apropos \-\- \-i 'Nm~[[:<:]]ssh[[:>:]]'
1.24 schwarze 331: .Pp
332: The following two invocations are equivalent:
333: .Pp
334: .D1 Li $ apropos -S Ar arch Li -s Ar section expression
335: .Bd -ragged -offset indent
336: .Li $ apropos \e( Ar expression Li \e)
337: .Li -a arch~^( Ns Ar arch Ns Li |any)$
338: .Li -a sec~^ Ns Ar section Ns Li $
339: .Ed
1.1 kristaps 340: .Sh SEE ALSO
1.23 schwarze 341: .Xr man 1 ,
342: .Xr re_format 7 ,
1.11 kristaps 343: .Xr mandocdb 8
1.23 schwarze 344: .Sh HISTORY
345: An
346: .Nm
347: utility first appeared in
348: .Bx 2 .
349: It was rewritten from scratch for
1.24 schwarze 350: .Ox 5.6 .
1.23 schwarze 351: .Pp
352: The
353: .Fl M
354: option and the
355: .Ev MANPATH
356: variable first appeared in
357: .Bx 4.3 ;
358: .Fl m
359: in
360: .Bx 4.3 Reno ;
361: .Fl C
362: in
363: .Bx 4.4 Lite1 ;
364: and
365: .Fl S
366: and
367: .Fl s
368: in
369: .Ox 4.5 .
1.1 kristaps 370: .Sh AUTHORS
1.23 schwarze 371: .An -nosplit
372: .An Bill Joy
373: wrote the original
374: .Bx
1.1 kristaps 375: .Nm
1.23 schwarze 376: in February 1979.
377: The current version was written by
1.24 schwarze 378: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
379: and
380: .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