Return to apropos.1 CVS log | Up to [cvsweb.bsd.lv] / mandoc |
version 1.35, 2014/09/03 05:22:45 | version 1.48, 2018/11/19 19:27:37 | ||
---|---|---|---|
|
|
||
.\" $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 acfhklVw | .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 | ||
|
|
||
.Xr makewhatis 8 | .Xr makewhatis 8 | ||
databases in the default paths stipulated by | databases in the default paths stipulated by | ||
.Xr man 1 | .Xr man 1 | ||
and uses case-insensitive substring matching | and uses case-insensitive extended regular expression matching | ||
.Pq the Cm = No 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 | ||
|
|
||
In | In | ||
.Fl a | .Fl a | ||
mode, the options | mode, the options | ||
.Fl IOTW | .Fl IKOTW | ||
described in the | described in the | ||
.Xr mandoc 1 | .Xr mandoc 1 | ||
manual are also available. | manual are also available. | ||
|
|
||
in | in | ||
.Xr man.conf 5 | .Xr man.conf 5 | ||
format. | format. | ||
.It Fl c | |||
In | |||
.Fl a | |||
mode, copy the formatted manual pages to the standard output without using | |||
.Xr more 1 | |||
to paginate them. | |||
.It Fl f | .It Fl f | ||
Search for all words in | Search for all words in | ||
.Ar expression | .Ar expression | ||
in manual page names only. | in manual page names only. | ||
The search is case insensitive and matches whole words only. | The search is case-insensitive and matches whole words only. | ||
In this mode, macro keys, comparison operators, and logical operators | In this mode, macro keys, comparison operators, and logical operators | ||
are not available. | are not available. | ||
This overrides any earlier | |||
.Fl k | |||
and | |||
.Fl l | |||
options. | |||
.It Fl h | |||
Instead of showing the title lines, show the SYNOPSIS sections, just like | |||
.Xr man 1 | |||
.Fl h | |||
would. | |||
.It Fl k | .It Fl k | ||
Support the full | Support the full | ||
.Ar expression | .Ar expression | ||
syntax. | syntax. | ||
This overrides any earlier | |||
.Fl f | |||
and | |||
.Fl l | |||
options. | |||
It is the default for | It is the default for | ||
.Nm . | .Nm . | ||
.It Fl l | |||
An alias for | |||
.Xr mandoc 1 | |||
.Fl a . | |||
This overrides any earlier | |||
.Fl f , | |||
.Fl k , | |||
and | |||
.Fl w | |||
options. | |||
.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 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. | ||
|
|
||
See | See | ||
.Xr man 1 | .Xr man 1 | ||
for a listing of sections. | for a listing of sections. | ||
.It Fl V | |||
Print version and exit. | |||
.It Fl w | |||
Instead of showing title lines, show the pathnames of the matching | |||
manual pages, just like | |||
.Xr man 1 | |||
.Fl w | |||
would. | |||
.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 | ||
|
|
||
.Sm off | .Sm off | ||
.Oo | .Oo | ||
.Op Ar key Op , Ar key ... | .Op Ar key Op , Ar key ... | ||
.Pq Cm = | ~ | .Pq Cm = | \(ti | ||
.Oc | .Oc | ||
.Ar val , | .Ar val , | ||
.Sm on | .Sm on | ||
|
|
||
Operator | Operator | ||
.Cm = | .Cm = | ||
evaluates a substring, while | evaluates a substring, while | ||
.Cm ~ | .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 | ||
|
|
||
Has no effect on substring terms. | Has no effect on substring terms. | ||
.El | .El | ||
.Pp | .Pp | ||
Results are sorted by manual sections and names, with output formatted as | Results are sorted according to the following criteria: | ||
.Bl -enum | |||
.It | |||
The manpath directory tree the page is found in, according to the | |||
order specified with | |||
.Fl M , | |||
.Fl m , | |||
the | |||
.Ev MANPATH | |||
environment variable, the | |||
.Xr man.conf 5 | |||
configuration file, or the default documented in | |||
.Xr man.conf 5 . | |||
.It | |||
The section number in ascending numerical order. | |||
.It | |||
The page name in ascending | |||
.Xr ascii 7 | |||
alphabetical order, case-insensitive. | |||
.El | |||
.Pp | .Pp | ||
Each output line is formatted as | |||
.Pp | |||
.D1 name[, name...](sec) \- description | .D1 name[, name...](sec) \- description | ||
.Pp | .Pp | ||
Where | Where | ||
|
|
||
.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 MANPAGER | .Bl -tag -width MANPAGER | ||
.It Ev MANPAGER | .It Ev MANPAGER | ||
Any non-empty value of the environment variable | Any non-empty value of the environment variable | ||
.Ev MANPAGER | .Ev MANPAGER | ||
will be used instead of the standard pagination program, | is used instead of the standard pagination program, | ||
.Xr more 1 . | .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; | |||
or if it contains two adjacent colons, | |||
the standard search path is inserted between the colons. | |||
If none of these conditions are met, it overrides the | |||
standard search path. | |||
.It Ev PAGER | .It Ev PAGER | ||
Specifies the pagination program to use when | Specifies the pagination program to use when | ||
.Ev MANPAGER | .Ev MANPAGER | ||
is not defined. | is not defined. | ||
If neither PAGER nor MANPAGER is defined, | If neither PAGER nor MANPAGER is defined, | ||
.Pa /usr/bin/more Fl s | .Xr more 1 | ||
will be used. | .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 | ||
|
|
||
.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 section mentioning both the | Search for manuals in the library section mentioning both the | ||
.Qq optind | .Qq optind | ||
|
|
||
.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 makewhatis 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 | ||
Part of the functionality of | Part of the functionality of | ||
.Nm whatis | .Nm whatis | ||
|
|
||
.Ox 5.6 | .Ox 5.6 | ||
for | for | ||
.Nm whatis . | .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 |