1.\" $Id: apropos.1,v 1.29 2014/04/24 00:28:19 schwarze Exp $
2.\"
3.\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
4.\" Copyright (c) 2011, 2012, 2014 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: April 24 2014 $
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 C Ar file
28.Op Fl M Ar path
29.Op Fl m Ar path
30.Op Fl O Ar outkey
31.Op Fl S Ar arch
32.Op Fl s Ar section
33.Ar expression ...
34.Sh DESCRIPTION
35The
36.Nm apropos
37and
38.Nm whatis
39utilities query manual page databases generated by
40.Xr makewhatis 8 ,
41evaluating
42.Ar expression
43for each file in each database.
44By default, it displays the names, section numbers, and description lines
45of all matching manuals.
46.Pp
47By default,
48.Nm
49searches for
50.Xr makewhatis 8
51databases in the default paths stipulated by
52.Xr man 1
53and uses case-insensitive substring matching
54.Pq the Cm = No operator
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.Nm whatis
60maps terms only to case-sensitive manual names.
61.Pp
62Its arguments are as follows:
63.Bl -tag -width Ds
64.It Fl C Ar file
65Specify an alternative configuration
66.Ar file
67in
68.Xr man.conf 5
69format.
70.It Fl M Ar path
71Use the colon-separated path instead of the default list of paths
72searched for
73.Xr makewhatis 8
74databases.
75Invalid paths, or paths without manual databases, are ignored.
76.It Fl m Ar path
77Prepend the colon-separated paths to the list of paths searched
--- 13 unchanged lines hidden (view full) ---
91is case insensitive.
92By default, pages for all architectures are shown.
93.It Fl s Ar section
94Restrict the search to the specified section of the manual.
95By default, pages from all sections are shown.
96See
97.Xr man 1
98for a listing of sections.
99.El
100.Pp
101An
102.Ar expression
103consists of search terms joined by logical operators
104.Fl a
105.Pq and
106and
--- 53 unchanged lines hidden (view full) ---
160.It Fl i Ar term
161If
162.Ar term
163is a regular expression, it
164is evaluated case-insensitively.
165Has no effect on substring terms.
166.El
167.Pp
168.Nm whatis
169considers an
170.Ar expression
171to consist of an opaque keyword.
172.Pp
173Results are sorted by manual sections and names, with output formatted as
174.Pp
175.D1 name[, name...](sec) \- description
176.Pp
177Where
178.Dq name
179is the manual's name,
180.Dq sec
--- 84 unchanged lines hidden (view full) ---
265.It Li \&Bx Ta Bx No version reference
266.It Li \&Bsx Ta Bsx No version reference
267.It Li \&Nx Ta Nx No version reference
268.It Li \&Fx Ta Fx No version reference
269.It Li \&Ox Ta Ox No version reference
270.It Li \&Dx Ta Dx No version reference
271.El
272.Sh ENVIRONMENT
273.Bl -tag -width MANPATH
274.It Ev MANPATH
275The standard search path used by
276.Xr man 1
277may be changed by specifying a path in the
278.Ev MANPATH
279environment variable.
280Invalid paths, or paths without manual databases, are ignored.
281Overridden by
282.Fl M .
283If
284.Ev MANPATH
285begins with a colon, it is appended to the default list;
286if it ends with a colon, it is prepended to the default list;
287or if it contains two adjacent colons,
288the standard search path is inserted between the colons.
289If none of these conditions are met, it overrides the
290standard search path.
291.El
292.Sh FILES
293.Bl -tag -width "/etc/man.conf" -compact
294.It Pa mandoc.db
295name of the
296.Xr makewhatis 8
297keyword database
298.It Pa /etc/man.conf
--- 45 unchanged lines hidden (view full) ---
344.Li -a arch~^( Ns Ar arch Ns Li |any)$
345.Li -a sec~^ Ns Ar section Ns Li $
346.Ed
347.Sh SEE ALSO
348.Xr man 1 ,
349.Xr re_format 7 ,
350.Xr makewhatis 8
351.Sh HISTORY
352An
353.Nm
354utility first appeared in
355.Bx 2 .
356It was rewritten from scratch for
357.Ox 5.6 .
358.Pp
359The
360.Fl M
361option and the
362.Ev MANPATH
363variable first appeared in
364.Bx 4.3 ;
365.Fl m
366in
367.Bx 4.3 Reno ;
368.Fl C
369in
370.Bx 4.4 Lite1 ;
371and
372.Fl S
373and
374.Fl s
375in
376.Ox 4.5 .
377.Sh AUTHORS
378.An -nosplit
379.An Bill Joy
380wrote the original
381.Bx
382.Nm
383in February 1979.
384The current version was written by
385.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
386and
387.An Ingo Schwarze Aq Mt schwarze@openbsd.org .
2.\"
3.\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
4.\" Copyright (c) 2011, 2012, 2014 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: April 24 2014 $
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 C Ar file
28.Op Fl M Ar path
29.Op Fl m Ar path
30.Op Fl O Ar outkey
31.Op Fl S Ar arch
32.Op Fl s Ar section
33.Ar expression ...
34.Sh DESCRIPTION
35The
36.Nm apropos
37and
38.Nm whatis
39utilities query manual page databases generated by
40.Xr makewhatis 8 ,
41evaluating
42.Ar expression
43for each file in each database.
44By default, it displays the names, section numbers, and description lines
45of all matching manuals.
46.Pp
47By default,
48.Nm
49searches for
50.Xr makewhatis 8
51databases in the default paths stipulated by
52.Xr man 1
53and uses case-insensitive substring matching
54.Pq the Cm = No operator
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.Nm whatis
60maps terms only to case-sensitive manual names.
61.Pp
62Its arguments are as follows:
63.Bl -tag -width Ds
64.It Fl C Ar file
65Specify an alternative configuration
66.Ar file
67in
68.Xr man.conf 5
69format.
70.It Fl M Ar path
71Use the colon-separated path instead of the default list of paths
72searched for
73.Xr makewhatis 8
74databases.
75Invalid paths, or paths without manual databases, are ignored.
76.It Fl m Ar path
77Prepend the colon-separated paths to the list of paths searched
--- 13 unchanged lines hidden (view full) ---
91is case insensitive.
92By default, pages for all architectures are shown.
93.It Fl s Ar section
94Restrict the search to the specified section of the manual.
95By default, pages from all sections are shown.
96See
97.Xr man 1
98for a listing of sections.
99.El
100.Pp
101An
102.Ar expression
103consists of search terms joined by logical operators
104.Fl a
105.Pq and
106and
--- 53 unchanged lines hidden (view full) ---
160.It Fl i Ar term
161If
162.Ar term
163is a regular expression, it
164is evaluated case-insensitively.
165Has no effect on substring terms.
166.El
167.Pp
168.Nm whatis
169considers an
170.Ar expression
171to consist of an opaque keyword.
172.Pp
173Results are sorted by manual sections and names, with output formatted as
174.Pp
175.D1 name[, name...](sec) \- description
176.Pp
177Where
178.Dq name
179is the manual's name,
180.Dq sec
--- 84 unchanged lines hidden (view full) ---
265.It Li \&Bx Ta Bx No version reference
266.It Li \&Bsx Ta Bsx No version reference
267.It Li \&Nx Ta Nx No version reference
268.It Li \&Fx Ta Fx No version reference
269.It Li \&Ox Ta Ox No version reference
270.It Li \&Dx Ta Dx No version reference
271.El
272.Sh ENVIRONMENT
273.Bl -tag -width MANPATH
274.It Ev MANPATH
275The standard search path used by
276.Xr man 1
277may be changed by specifying a path in the
278.Ev MANPATH
279environment variable.
280Invalid paths, or paths without manual databases, are ignored.
281Overridden by
282.Fl M .
283If
284.Ev MANPATH
285begins with a colon, it is appended to the default list;
286if it ends with a colon, it is prepended to the default list;
287or if it contains two adjacent colons,
288the standard search path is inserted between the colons.
289If none of these conditions are met, it overrides the
290standard search path.
291.El
292.Sh FILES
293.Bl -tag -width "/etc/man.conf" -compact
294.It Pa mandoc.db
295name of the
296.Xr makewhatis 8
297keyword database
298.It Pa /etc/man.conf
--- 45 unchanged lines hidden (view full) ---
344.Li -a arch~^( Ns Ar arch Ns Li |any)$
345.Li -a sec~^ Ns Ar section Ns Li $
346.Ed
347.Sh SEE ALSO
348.Xr man 1 ,
349.Xr re_format 7 ,
350.Xr makewhatis 8
351.Sh HISTORY
352An
353.Nm
354utility first appeared in
355.Bx 2 .
356It was rewritten from scratch for
357.Ox 5.6 .
358.Pp
359The
360.Fl M
361option and the
362.Ev MANPATH
363variable first appeared in
364.Bx 4.3 ;
365.Fl m
366in
367.Bx 4.3 Reno ;
368.Fl C
369in
370.Bx 4.4 Lite1 ;
371and
372.Fl S
373and
374.Fl s
375in
376.Ox 4.5 .
377.Sh AUTHORS
378.An -nosplit
379.An Bill Joy
380wrote the original
381.Bx
382.Nm
383in February 1979.
384The current version was written by
385.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
386and
387.An Ingo Schwarze Aq Mt schwarze@openbsd.org .