APROPOS(1) General Commands Manual APROPOS(1)

NAME

apropossearch manual page databases

SYNOPSIS

apropos [-C file] [-M path] [-m path] [-S arch] [-s section] expression ...

DESCRIPTION

The apropos utility queries manual page databases generated by mandocdb(8), evaluating on expression for each file in each database.

By default, apropos searches for mandocdb(8) databases in the default paths stipulated by man(1), parses terms as case-sensitive regular expressions (the ~ operator) over manual names and descriptions (the Nm and Nd macro keys). Multiple terms imply pairwise -o.

Its arguments are as follows:

-C file
Specify an alternative configuration file in man.conf(5) format.
-M path
Use the colon-separated path instead of the default list of paths searched for mandocdb(8) databases. Invalid paths, or paths without manual databases, are ignored.
-m path
Prepend the colon-separated paths to the list of paths searched for mandocdb(8) databases. Invalid paths, or paths without manual databases, are ignored.
-S arch
Search only for a particular architecture.
-s cat
Search only for a manual section. See man(1) for a listing of manual sections.

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.

( 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]*(=~)]?val, where operand 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 regular expression.
-i term
If term is a regular expression, it is evaluated case-insensitively. Has no effect on substring terms.

Results are sorted by manual title, with output formatted as

title(sec) - description

Where “title” is the manual's title (note multiple manual names may exist for one title), “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

title(cat/arch) - description

Resulting manuals may be accessed as

$ man -s sec title

If an architecture is specified in the output, use

$ man -s sec -S arch title

Macro Keys

Queries evaluate over a subset of mdoc(7) macros indexed by mandocdb(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

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

ENVIRONMENT

MANPATH
Colon-separated paths modifying the default list of paths searched for manual databases. Invalid paths, or paths without manual databases, are ignored. Overridden by -M. If MANPATH begins with a ‘:’, it is appended to the default list; else if it ends with ‘:’, it is prepended to the default list; else if it contains ‘::’, the default list is inserted between the colons. If none of these conditions are met, it overrides the default list.

FILES

mandoc.db
name of the mandocdb(8) keyword database
mandoc.index
name of the mandocdb(8) filename database
/etc/man.conf
default man(1) configuration file

EXIT STATUS

The apropos utility exits 0 on success, and >0 if an error occurs.

EXAMPLES

Search for “mdoc” as a substring and regular expression within each manual name and description:

$ apropos mdoc
$ apropos ~^mdoc$

Include matches for “roff” and “man” for the regular expression case:

$ apropos ~^mdoc$ roff man
$ apropos ~^mdoc$ -o roff -o man

Search for “optind” and “optarg” as variable names in the library category:

$ apropos -s 3 Va~^optind -a Va~^optarg$

SEE ALSO

man(1), re_format(7), mandocdb(8)

AUTHORS

The apropos utility was written by Kristaps Dzonsons <kristaps@bsd.lv>.
October 5, 2013 OpenBSD 5.4