version 1.25, 2014/04/04 15:55:19 |
version 1.49, 2018/11/22 12:33:52 |
|
|
.\" $Id$ |
.\" $Id$ |
.\" |
.\" |
.\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2011, 2012, 2014 Ingo Schwarze <schwarze@openbsd.org> |
.\" Copyright (c) 2011,2012,2014,2017,2018 Ingo Schwarze <schwarze@openbsd.org> |
.\" |
.\" |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" purpose with or without fee is hereby granted, provided that the above |
.\" purpose with or without fee is hereby granted, provided that the above |
|
|
.Nd search manual page databases |
.Nd search manual page databases |
.Sh SYNOPSIS |
.Sh SYNOPSIS |
.Nm |
.Nm |
|
.Op Fl afk |
.Op Fl C Ar file |
.Op Fl C Ar file |
.Op Fl M Ar path |
.Op Fl M Ar path |
.Op Fl m Ar path |
.Op Fl m Ar path |
|
|
and |
and |
.Nm whatis |
.Nm whatis |
utilities query manual page databases generated by |
utilities query manual page databases generated by |
.Xr mandocdb 8 , |
.Xr makewhatis 8 , |
evaluating on |
evaluating |
.Ar expression |
.Ar expression |
for each file in each database. |
for each file in each database. |
|
By default, they display the names, section numbers, and description lines |
|
of all matching manuals. |
.Pp |
.Pp |
By default, |
By default, |
.Nm |
.Nm |
searches for |
searches for |
.Xr mandocdb 8 |
.Xr makewhatis 8 |
databases in the default paths stipulated by |
databases in the default paths stipulated by |
.Xr man 1 , |
.Xr man 1 |
parses terms as case-sensitive regular expressions |
and uses case-insensitive extended regular expression matching |
.Pq the Li \&~ operator |
|
over manual names and descriptions |
over manual names and descriptions |
.Pq the Li \&Nm No and Li \&Nd No macro keys . |
.Pq the Li \&Nm No and Li \&Nd No macro keys . |
Multiple terms imply pairwise |
Multiple terms imply pairwise |
.Fl o . |
.Fl o . |
|
.Pp |
.Nm whatis |
.Nm whatis |
maps terms only to case-sensitive manual names. |
is a synonym for |
|
.Nm |
|
.Fl f . |
.Pp |
.Pp |
Its arguments are as follows: |
The options are as follows: |
.Bl -tag -width Ds |
.Bl -tag -width Ds |
|
.It Fl a |
|
Instead of showing only the title lines, show the complete manual pages, |
|
just like |
|
.Xr man 1 |
|
.Fl a |
|
would. |
|
If the standard output is a terminal device and |
|
.Fl c |
|
is not specified, use |
|
.Xr more 1 |
|
to paginate them. |
|
In |
|
.Fl a |
|
mode, the options |
|
.Fl IKOTW |
|
described in the |
|
.Xr mandoc 1 |
|
manual are also available. |
.It Fl C Ar file |
.It Fl C Ar file |
Specify an alternative configuration |
Specify an alternative configuration |
.Ar file |
.Ar file |
in |
in |
.Xr man.conf 5 |
.Xr man.conf 5 |
format. |
format. |
|
.It Fl f |
|
Search for all words in |
|
.Ar expression |
|
in manual page names only. |
|
The search is case-insensitive and matches whole words only. |
|
In this mode, macro keys, comparison operators, and logical operators |
|
are not available. |
|
.It Fl k |
|
Support the full |
|
.Ar expression |
|
syntax. |
|
It is the default for |
|
.Nm . |
.It Fl M Ar path |
.It Fl M Ar path |
Use the colon-separated path instead of the default list of paths |
Use the colon-separated path instead of the default list of paths |
searched for |
searched for |
.Xr mandocdb 8 |
.Xr makewhatis 8 |
databases. |
databases. |
Invalid paths, or paths without manual databases, are ignored. |
Invalid paths, or paths without manual databases, are ignored. |
.It Fl m Ar path |
.It Fl m Ar path |
Prepend the colon-separated paths to the list of paths searched |
Prepend the colon-separated paths to the list of paths searched |
for |
for |
.Xr mandocdb 8 |
.Xr makewhatis 8 |
databases. |
databases. |
Invalid paths, or paths without manual databases, are ignored. |
Invalid paths, or paths without manual databases, are ignored. |
.It Fl O Ar outkey |
.It Fl O Ar outkey |
Line 86 Restrict the search to pages for the specified |
|
Line 122 Restrict the search to pages for the specified |
|
.Xr machine 1 |
.Xr machine 1 |
architecture. |
architecture. |
.Ar arch |
.Ar arch |
is case insensitive. |
is case-insensitive. |
By default, pages for all architectures are shown. |
By default, pages for all architectures are shown. |
.It Fl s Ar section |
.It Fl s Ar section |
Restrict the search to the specified section of the manual. |
Restrict the search to the specified section of the manual. |
|
|
for a listing of sections. |
for a listing of sections. |
.El |
.El |
.Pp |
.Pp |
|
The options |
|
.Fl chlw |
|
are also supported and are documented in |
|
.Xr man 1 . |
|
The options |
|
.Fl fkl |
|
are mutually exclusive and override each other. |
|
.Pp |
An |
An |
.Ar expression |
.Ar expression |
consists of search terms joined by logical operators |
consists of search terms joined by logical operators |
|
|
and |
and |
.Ar expr2 |
.Ar expr2 |
are true (logical |
are true (logical |
.Qq and ) . |
.Sq and ) . |
.It Ar expr1 Oo Fl o Oc Ar expr2 |
.It Ar expr1 Oo Fl o Oc Ar expr2 |
True if |
True if |
.Ar expr1 |
.Ar expr1 |
and/or |
and/or |
.Ar expr2 |
.Ar expr2 |
evaluate to true (logical |
evaluate to true (logical |
.Qq or ) . |
.Sq or ) . |
.It Ar term |
.It Ar term |
True if |
True if |
.Ar term |
.Ar term |
is satisfied. |
is satisfied. |
This has syntax |
This has syntax |
.Li [key[,key]*(=~)]?val , |
.Sm off |
where operand |
.Oo |
.Cm key |
.Op Ar key Op , Ar key ... |
|
.Pq Cm = | \(ti |
|
.Oc |
|
.Ar val , |
|
.Sm on |
|
where |
|
.Ar key |
is an |
is an |
.Xr mdoc 7 |
.Xr mdoc 7 |
macro to query and |
macro to query and |
.Cm val |
.Ar val |
is its value. |
is its value. |
See |
See |
.Sx Macro Keys |
.Sx Macro Keys |
for a list of available keys. |
for a list of available keys. |
Operator |
Operator |
.Li \&= |
.Cm = |
evaluates a substring, while |
evaluates a substring, while |
.Li \&~ |
.Cm \(ti |
evaluates a regular expression. |
evaluates a case-sensitive extended regular expression. |
.It Fl i Ar term |
.It Fl i Ar term |
If |
If |
.Ar term |
.Ar term |
Line 157 is evaluated case-insensitively. |
|
Line 207 is evaluated case-insensitively. |
|
Has no effect on substring terms. |
Has no effect on substring terms. |
.El |
.El |
.Pp |
.Pp |
.Nm whatis |
Results are sorted first according to the section number in ascending |
considers an |
numerical order, then by the page name in ascending |
.Ar expression |
.Xr ascii 7 |
to consist of an opaque keyword. |
alphabetical order, case-insensitive. |
.Pp |
.Pp |
Results are sorted by manual title, with output formatted as |
Each output line is formatted as |
.Pp |
.Pp |
.D1 title(sec) \- description |
.D1 name[, name...](sec) \- description |
.Pp |
.Pp |
Where |
Where |
.Qq title |
.Dq name |
is the manual's title (note multiple manual names may exist for one |
is the manual's name, |
title), |
.Dq sec |
.Qq sec |
|
is the manual section, and |
is the manual section, and |
.Qq description |
.Dq description |
is the manual's short description. |
is the manual's short description. |
If an architecture is specified for the manual, it is displayed as |
If an architecture is specified for the manual, it is displayed as |
.Pp |
.Pp |
.D1 title(cat/arch) \- description |
.D1 name(sec/arch) \- description |
.Pp |
.Pp |
Resulting manuals may be accessed as |
Resulting manuals may be accessed as |
.Pp |
.Pp |
.Dl $ man \-s sec title |
.Dl $ man \-s sec name |
.Pp |
.Pp |
If an architecture is specified in the output, use |
If an architecture is specified in the output, use |
.Pp |
.Pp |
.Dl $ man \-s sec \-S arch title |
.Dl $ man \-s sec \-S arch name |
.Ss Macro Keys |
.Ss Macro Keys |
Queries evaluate over a subset of |
Queries evaluate over a subset of |
.Xr mdoc 7 |
.Xr mdoc 7 |
macros indexed by |
macros indexed by |
.Xr mandocdb 8 . |
.Xr makewhatis 8 . |
In addition to the macro keys listed below, the special key |
In addition to the macro keys listed below, the special key |
.Cm any |
.Cm any |
may be used to match any available macro key. |
may be used to match any available macro key. |
.Pp |
.Pp |
Names and description: |
Names and description: |
.Bl -column "xLix" description -offset indent -compact |
.Bl -column "xLix" description -offset indent -compact |
.It Li NAME Ta manual name in the NAME section, subset of \&Nm |
|
.It Li \&Nm Ta manual name |
.It Li \&Nm Ta manual name |
.It Li \&Nd Ta one-line manual description |
.It Li \&Nd Ta one-line manual description |
.It Li arch Ta machine architecture (case-insensitive) |
.It Li arch Ta machine architecture (case-insensitive) |
Line 263 Text production: |
|
Line 311 Text production: |
|
.It Li \&Ox Ta Ox No version reference |
.It Li \&Ox Ta Ox No version reference |
.It Li \&Dx Ta Dx No version reference |
.It Li \&Dx Ta Dx No version reference |
.El |
.El |
|
.Pp |
|
In general, macro keys are supposed to yield complete results without |
|
expecting the user to consider actual macro usage. |
|
For example, results include: |
|
.Pp |
|
.Bl -tag -width 3n -offset 3n -compact |
|
.It Li \&Fa |
|
function arguments appearing on |
|
.Ic \&Fn |
|
lines |
|
.It Li \&Fn |
|
function names marked up with |
|
.Ic \&Fo |
|
macros |
|
.It Li \&In |
|
include file names marked up with |
|
.Ic \&Fd |
|
macros |
|
.It Li \&Vt |
|
types appearing as function return types and |
|
.It \& |
|
types appearing in function arguments in the SYNOPSIS |
|
.El |
.Sh ENVIRONMENT |
.Sh ENVIRONMENT |
.Bl -tag -width MANPATH |
.Bl -tag -width MANPAGER |
|
.It Ev MANPAGER |
|
Any non-empty value of the environment variable |
|
.Ev MANPAGER |
|
is used instead of the standard pagination program, |
|
.Xr more 1 ; |
|
see |
|
.Xr man 1 |
|
for details. |
|
Only used if |
|
.Fl a |
|
or |
|
.Fl l |
|
is specified. |
.It Ev MANPATH |
.It Ev MANPATH |
The standard search path used by |
A colon-separated list of directories to search for manual pages; see |
.Xr man 1 |
.Xr man 1 |
may be changed by specifying a path in the |
for details. |
.Ev MANPATH |
|
environment variable. |
|
Invalid paths, or paths without manual databases, are ignored. |
|
Overridden by |
Overridden by |
.Fl M . |
.Fl M , |
If |
ignored if |
.Ev MANPATH |
.Fl l |
begins with a colon, it is appended to the default list; |
is specified. |
if it ends with a colon, it is prepended to the default list; |
.It Ev PAGER |
or if it contains two adjacent colons, |
Specifies the pagination program to use when |
the standard search path is inserted between the colons. |
.Ev MANPAGER |
If none of these conditions are met, it overrides the |
is not defined. |
standard search path. |
If neither PAGER nor MANPAGER is defined, |
|
.Xr more 1 |
|
.Fl s |
|
is used. |
|
Only used if |
|
.Fl a |
|
or |
|
.Fl l |
|
is specified. |
.El |
.El |
.Sh FILES |
.Sh FILES |
.Bl -tag -width "/etc/man.conf" -compact |
.Bl -tag -width "/etc/man.conf" -compact |
.It Pa mandoc.db |
.It Pa mandoc.db |
name of the |
name of the |
.Xr mandocdb 8 |
.Xr makewhatis 8 |
keyword database |
keyword database |
.It Pa /etc/man.conf |
.It Pa /etc/man.conf |
default |
default |
|
|
.Qq .cf |
.Qq .cf |
as a substring of manual names and descriptions: |
as a substring of manual names and descriptions: |
.Pp |
.Pp |
.Dl $ apropos .cf |
.Dl $ apropos =.cf |
.Pp |
.Pp |
Include matches for |
Include matches for |
.Qq .cnf |
.Qq .cnf |
|
|
.Qq .conf |
.Qq .conf |
as well: |
as well: |
.Pp |
.Pp |
.Dl $ apropos .cf .cnf .conf |
.Dl $ apropos =.cf =.cnf =.conf |
.Pp |
.Pp |
Search in names and descriptions using a regular expression: |
Search in names and descriptions using a case-sensitive regular expression: |
.Pp |
.Pp |
.Dl $ apropos '~set.?[ug]id' |
.Dl $ apropos \(aq\(tiset.?[ug]id\(aq |
.Pp |
.Pp |
Search for manuals in the library category mentioning both the |
Search for manuals in the library section mentioning both the |
.Qq optind |
.Qq optind |
and the |
and the |
.Qq optarg |
.Qq optarg |
|
|
.Dl $ apropos \-s 3 Va=optind \-a Va=optarg |
.Dl $ apropos \-s 3 Va=optind \-a Va=optarg |
.Pp |
.Pp |
Do exactly the same as calling |
Do exactly the same as calling |
.Xr whatis 1 |
.Nm whatis |
with the argument |
with the argument |
.Qq ssh : |
.Qq ssh : |
.Pp |
.Pp |
.Dl $ apropos \-\- \-i 'Nm~[[:<:]]ssh[[:>:]]' |
.Dl $ apropos \-\- \-i \(aqNm\(ti[[:<:]]ssh[[:>:]]\(aq |
.Pp |
.Pp |
The following two invocations are equivalent: |
The following two invocations are equivalent: |
.Pp |
.Pp |
.D1 Li $ apropos -S Ar arch Li -s Ar section expression |
.D1 Li $ apropos -S Ar arch Li -s Ar section expression |
.Bd -ragged -offset indent |
.Bd -ragged -offset indent |
.Li $ apropos \e( Ar expression Li \e) |
.Li $ apropos \e( Ar expression Li \e) |
.Li -a arch~^( Ns Ar arch Ns Li |any)$ |
.Li -a arch\(ti^( Ns Ar arch Ns Li |any)$ |
.Li -a sec~^ Ns Ar section Ns Li $ |
.Li -a sec\(ti^ Ns Ar section Ns Li $ |
.Ed |
.Ed |
.Sh SEE ALSO |
.Sh SEE ALSO |
.Xr man 1 , |
.Xr man 1 , |
.Xr re_format 7 , |
.Xr re_format 7 , |
.Xr mandocdb 8 |
.Xr makewhatis 8 |
|
.Sh STANDARDS |
|
The |
|
.Nm |
|
utility is compliant with the |
|
.St -p1003.1-2008 |
|
specification of |
|
.Xr man 1 |
|
.Fl k . |
|
.Pp |
|
All options, the |
|
.Nm whatis |
|
command, support for logical operators, macro keys, |
|
substring matching, sorting of results, the environment variables |
|
.Ev MANPAGER |
|
and |
|
.Ev MANPATH , |
|
the database format, and the configuration file |
|
are extensions to that specification. |
.Sh HISTORY |
.Sh HISTORY |
An |
Part of the functionality of |
|
.Nm whatis |
|
was already provided by the former |
|
.Nm manwhere |
|
utility in |
|
.Bx 1 . |
|
The |
.Nm |
.Nm |
utility first appeared in |
and |
|
.Nm whatis |
|
utilities first appeared in |
.Bx 2 . |
.Bx 2 . |
It was rewritten from scratch for |
They were rewritten from scratch for |
.Ox 5.6 . |
.Ox 5.6 . |
.Pp |
.Pp |
The |
The |
|
|
and |
and |
.Fl s |
.Fl s |
in |
in |
.Ox 4.5 . |
.Ox 4.5 |
|
for |
|
.Nm |
|
and in |
|
.Ox 5.6 |
|
for |
|
.Nm whatis . |
|
The options |
|
.Fl acfhIKklOTWw |
|
appeared in |
|
.Ox 5.7 . |
.Sh AUTHORS |
.Sh AUTHORS |
.An -nosplit |
.An -nosplit |
.An Bill Joy |
.An Bill Joy |
wrote the original |
wrote |
|
.Nm manwhere |
|
in 1977 and the original |
.Bx |
.Bx |
.Nm |
.Nm |
|
and |
|
.Nm whatis |
in February 1979. |
in February 1979. |
The current version was written by |
The current version was written by |
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv |
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv |