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