APROPOS
Section: User Commands (1)
Index
Return to Main Contents
BSD mandoc
NAME
apropos
whatis
- search manual page databases
SYNOPSIS
[-
afk
]
[-
C file
]
[-
M path
]
[-
m path
]
[-
O outkey
]
[-
S arch
]
[-
s section
]
expression ...
DESCRIPTION
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,
searches for
makewhatis(8)
databases in the default paths stipulated by
man(1)
and uses cas-insensitive extended regular expression matching
over manual names and descriptions
(the and - macro keys
)
Multiple terms imply pairwise
-o
whatis
is a synonym for
-f
The options are as follows:
- -a
-
Instead of showing only the title lines, show the complete manual pages,
just like
man(1)
-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
-
Specify an alternative configuration
file
in
man.conf5
format.
- -f
-
Search for all words in
expression
in manual page names only.
The search is cas-insensitive and matches whole words only.
In this mode, macro keys, comparison operators, and logical operators
are not available.
- -k
-
Support the full
expression
syntax.
It is the default for
.
- -M path
-
Use the colo-separated path instead of the default list of paths
searched for
makewhatis(8)
databases.
Invalid paths, or paths without manual databases, are ignored.
- -m path
-
Prepend the colo-separated paths to the list of paths searched
for
makewhatis(8)
databases.
Invalid paths, or paths without manual databases, are ignored.
- -O outkey
-
Show the values associated with the key
outkey
instead of the manual descriptions.
- -S arch
-
Restrict the search to pages for the specified
machine(1)
architecture.
arch
is cas-insensitive.
By default, pages for all architectures are shown.
- -s section
-
Restrict the search to the specified section of the manual.
By default, pages from all sections are shown.
See
man(1)
for a listing of sections.
The 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 lef-t-right.
- ( expr )
-
True if the subexpression
expr
is true.
- expr1 -a expr2
-
True if both
expr1
and
expr2
are true (logical
`and )'
- expr1 [-o expr2
]
-
True if
expr1
and/or
expr2
evaluate to true (logical
`or )'
- term
-
True if
term
is satisfied.
This has syntax
[[key [, key ...
]
]
(= | ti
)
]
val
where
key
is an
mdoc(7)
macro to query and
val
is its value.
See
Sx Macro Keys
for a list of available keys.
Operator
=
evaluates a substring, while
ti
evaluates a cas-sensitive extended regular expression.
- -i term
-
If
term
is a regular expression, it
is evaluated cas-insensitively.
Has no effect on substring terms.
Results are sorted first according to the section number in ascending
numerical order, then by the page name in ascending
ascii(7)
alphabetical order, cas-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
Macro Keys
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:
- Ta manual name
-
- - Ta on-line manual description
-
- arch Ta machine architecture (cas-insensitive)
-
- sec Ta manual section number
-
Sections and cross references:
Ta section header (excluding standard sections)
Li Ss Ta subsection header
Li Xr Ta cross reference to another manual page
Li Rs Ta bibliographic reference
Semantic markup for command line utilities:
- -Ta command line options (flags)
-
- Ta command modifier
-
- Ta command argument
-
- Ta internal or interactive command
-
- Ta environmental variable
-
- Ta file system path
-
Semantic markup for function libraries:
- Lb Ta function library name
-
- In Ta include file
-
- Ft Ta function return type
-
- Fn Ta function name
-
- Fa Ta function argument type and name
-
- Vt Ta variable type
-
- Ta variable name
-
- Ta defined variable or preprocessor constant
-
- Er Ta error constant
-
- Ta environmental variable
-
Various semantic markup:
- An Ta author name
-
- Lk Ta hyperlink
-
- Mt Ta Do mailto Dc hyperlink
-
- Ta kernel configuration declaration
-
- Ta mathematical symbol
-
- Ta tradename
-
Physical markup:
- Ta italic font or underline
-
- Ta boldface font
-
- Ta typewriter font
-
Text production:
- St Ta reference to a standards document
-
- AT&T System
Ta AT&T System
version reference
-
- BSD Ta BSD version reference
-
- Bsx Ta Bsx version reference
-
- Nx Ta Nx version reference
-
- Fx Ta Fx version reference
-
- Ox Ta Ox version reference
-
- Dx Ta Dx 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:
- Fa function arguments appearing on
-
Fn lines
- Fn function names marked up with
-
Fo macros
- In include file names marked up with
-
Fd macros
- Vt types appearing as function return types and
-
-
-
types appearing in function arguments in the SYNOPSIS
ENVIRONMENT
- MANPAGER
-
Any no-empty value of the environment variable
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
-
A colo-separated list of directories to search for manual pages; see
man(1)
for details.
Overridden by
-M
ignored if
-l
is specified.
- PAGER
-
Specifies the pagination program to use when
MANPAGER
is not defined.
If neither PAGER nor MANPAGER is defined,
less(1)
is used.
Only used if
-a
or
-l
is specified.
FILES
- mandoc.db
-
name of the
makewhatis(8)
keyword database
- /etc/man.conf
-
default
man(1)
configuration file
EXIT STATUS
Ex -std
EXAMPLES
Search for
Qq .cf
as a substring of manual names and descriptions:
$ apropos =.cf
Include matches for
Qq .cnf
and
Qq .conf
as well:
$ apropos =.cf =.cnf =.conf
Search in names and descriptions using a cas-sensitive regular expression:
$ apropos aqtiset.?[ug]idaq
Search for all manual pages in a given section:
$ apropos -s 9 .
Search for manuals in the library section mentioning both the
Qq optind
and the
Qq optarg
variables:
$ apropos -s 3 Va=optind -a Va=optarg
Do exactly the same as calling
whatis
with the argument
Qq ssh :
$ apropos -- -i aqNmti[[:<:]]ssh[[:>:]]aq
The following two invocations are equivalent:
$ apropos ( expression )
-a archti^( arch |any)$
-a secti^ section $
SEE ALSO
man(1),
re_format7,
makewhatis(8)
STANDARDS
The
utility is compliant with the
St -p1003.-2008
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.
HISTORY
Part of the functionality of
whatis
was already provided by the former
manwhere
utility in
BSD 1
The
and
whatis
utilities first appeared in
BSD 2
They were rewritten from scratch for
Ox 5.6 .
The
-M
option and the
MANPATH
variable first appeared in
BSD 4.3
-m
in
BSD 4.3 Reno
-C
in
BSD 4.4 Lite1
and
-S
and
-s
in
Ox 4.5
for
and in
Ox 5.6
for
whatis
The options
-acfhIKklOTWw appeared in
Ox 5.7 .
AUTHORS
An -nosplit
An Bill Joy
wrote
manwhere
in 1977 and the original
BSD
and
whatis
in February 1979.
The current version was written by
An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
and
An Ingo Schwarze Aq Mt schwarze@openbsd.org .
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- Macro Keys
-
- Ta section header (excluding standard sections)
-
- ENVIRONMENT
-
- FILES
-
- EXIT STATUS
-
- EXAMPLES
-
- SEE ALSO
-
- STANDARDS
-
- HISTORY
-
- AUTHORS
-
|
|
- Running on 
-
:
