APROPOS(1) | General Commands Manual | APROPOS(1) |
apropos
, whatis
— search manual page databases
apropos |
[-afk ] [-C
file] [-M
path] [-m
path] [-O
outkey] [-S
arch] [-s
section] expression ... |
The apropos
and
whatis
utilities query manual page databases
generated by makewhatis(8),
evaluating expression for each file in each database.
By default, they display the names, section numbers, and description lines
of all matching manuals.
By default, apropos
searches for
makewhatis(8) databases in
the default paths stipulated by
man(1) and uses case-insensitive
extended regular expression matching over manual names and descriptions (the
Nm
and
Nd
macro keys). Multiple
terms imply pairwise -o
.
whatis
is a synonym for
apropos
-f
.
The options are as follows:
-a
-a
would. If the standard output is a terminal
device and -c
is not specified, use
less(1) to
paginate them. In -a
mode, the options
-IKOTW
described in the
mandoc(1) manual are also
available.-C
file-f
-k
apropos
.-M
path-m
path-O
outkey-S
arch-s
sectionThe options -chlw
are also supported and
are documented in man(1). The
options -fkl
are mutually exclusive and override
each other.
An expression consists of search terms
joined by logical operators -a
(and) and
-o
(or). The -a
operator has
precedence over -o
and both are evaluated
left-to-right.
-a
expr2-o
]
expr2=
|~
)]val,
where key is an
mdoc(7) macro to query and
val is its value. See
Macro Keys for a list of available
keys. Operator =
evaluates a substring, while
~
evaluates a case-sensitive extended regular
expression.-i
termResults are sorted first according to the section number in ascending numerical order, then by the page name in ascending ascii(7) alphabetical order, case-insensitive.
Each output line is formatted as
Where “name” is the manual's name, “sec” is the manual section, and “description” is the manual's short description. If an architecture is specified for the manual, it is displayed as
Resulting manuals may be accessed as
$ man -s sec name
If an architecture is specified in the output, use
$ man -s sec -S arch
name
Queries evaluate over a subset of
mdoc(7) macros indexed by
makewhatis(8). In addition
to the macro keys listed below, the special key any
may be used to match any available macro key.
Names and description:
Nm |
manual name |
Nd |
one-line manual description |
arch |
machine architecture (case-insensitive) |
sec |
manual section number |
Sections and cross references:
Sh |
section header (excluding standard sections) |
Ss |
subsection header |
Xr |
cross reference to another manual page |
Rs |
bibliographic reference |
Semantic markup for command line utilities:
Fl |
command line options (flags) |
Cm |
command modifier |
Ar |
command argument |
Ic |
internal or interactive command |
Ev |
environmental variable |
Pa |
file system path |
Semantic markup for function libraries:
Lb |
function library name |
In |
include file |
Ft |
function return type |
Fn |
function name |
Fa |
function argument type and name |
Vt |
variable type |
Va |
variable name |
Dv |
defined variable or preprocessor constant |
Er |
error constant |
Ev |
environmental variable |
Various semantic markup:
An |
author name |
Lk |
hyperlink |
Mt |
“mailto” hyperlink |
Cd |
kernel configuration declaration |
Ms |
mathematical symbol |
Tn |
tradename |
Physical markup:
Em |
italic font or underline |
Sy |
boldface font |
Li |
typewriter font |
Text production:
St |
reference to a standards document |
At |
AT&T UNIX version reference |
Bx |
BSD version reference |
Bsx |
BSD/OS version reference |
Nx |
NetBSD version reference |
Fx |
FreeBSD version reference |
Ox |
OpenBSD version reference |
Dx |
DragonFly version reference |
In general, macro keys are supposed to yield complete results without expecting the user to consider actual macro usage. For example, results include:
MANPAGER
MANPAGER
is used instead of the standard
pagination program,
less(1); see
man(1) for details. Only used if
-a
or -l
is
specified.MANPATH
-M
, ignored if -l
is
specified.PAGER
MANPAGER
is not defined. If neither PAGER nor
MANPAGER is defined,
less(1) is used.
Only used if -a
or -l
is
specified.The apropos
utility exits 0 on
success, and >0 if an error occurs.
Search for ".cf" as a substring of manual names and descriptions:
$ apropos =.cf
Include matches for ".cnf" and ".conf" as well:
$ apropos =.cf =.cnf
=.conf
Search in names and descriptions using a case-sensitive regular expression:
$ apropos '~set.?[ug]id'
Search for all manual pages in a given section:
$ apropos -s 9 .
Search for manuals in the library section mentioning both the "optind" and the "optarg" variables:
$ apropos -s 3 Va=optind -a
Va=optarg
Do exactly the same as calling whatis
with
the argument "ssh":
$ apropos -- -i
'Nm~[[:<:]]ssh[[:>:]]'
The following two invocations are equivalent:
$ apropos -S
arch -s
section
expression$ apropos \(
expression \)
-a
arch~^(
arch|any)$
-a
sec~^
section$
The apropos
utility is compliant with the
IEEE Std 1003.1-2008 (“POSIX.1”)
specification of man(1)
-k
.
All options, the whatis
command, support
for logical operators, macro keys, substring matching, sorting of results,
the environment variables MANPAGER
and
MANPATH
, the database format, and the configuration
file are extensions to that specification.
Part of the functionality of whatis
was
already provided by the former manwhere
utility in
1BSD. The apropos
and
whatis
utilities first appeared in
2BSD. They were rewritten from scratch for
OpenBSD 5.6.
The -M
option and the
MANPATH
variable first appeared in
4.3BSD; -m
in
4.3BSD-Reno; -C
in
4.4BSD-Lite1; and -S
and
-s
in OpenBSD 4.5 for
apropos
and in OpenBSD 5.6
for whatis
. The options
-acfhIKklOTWw
appeared in OpenBSD
5.7.
Bill Joy wrote
manwhere
in 1977 and the original
BSD apropos
and
whatis
in February 1979. The current version was
written by Kristaps Dzonsons
<kristaps@bsd.lv> and
Ingo Schwarze
<schwarze@openbsd.org>.
October 1, 2020 | Linux 5.14.0-pf2 |