APROPOS(1)

NAME
apropos - search manual page databases

SYNOPSIS
apropos [-C file] [-M manpath] [-m manpath] [-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 over manual names and descriptions. Multiple terms imply pairwise -o. If standard output is a TTY, a result may be selected from a list and its manual displayed with the pager.

Its arguments are as follows:

-C file
    Specify an alternative configuration file in man.conf(5) format.

-M manpath
    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 manpath
    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

If on a TTY, results are prefixed with a numeric identifier.

    [index] title(cat) - description

One may choose a manual be entering the index at the prompt. Valid choices are displayed using MANPAGER, or failing that , PAGER or just more(1). Source pages are formatted with mandoc(1); preformatted pages with cat(1).

  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:
apropos | manual name
- | one-line manual description

Sections and cross references:
Sh | section header (excluding standard sections)
Ss | subsection header
 | cross reference to another manual page
Rs | bibliographic reference

Semantic markup for command line utilities:
- | command line options (flags)
 | command modifier
file ... | command argument
 | internal or interactive command
 | environmental variable
~ | file system path

Semantic markup for function libraries:
 | function library name
 | include file
 | function return type
 | function name
 | function argument type and name
 | variable type
 | variable name
 | defined variable or preprocessor constant
 | error constant
 | environmental variable

Various semantic markup:
 | author name
 | hyperlink
~ | “mailto” hyperlink
 | kernel configuration declaration
 | mathematical symbol
 | tradename

Physical markup:
 | italic font or underline
 | boldface font
 | typewriter font

Text production:
 | reference to a standards document
AT&T UNIX | AT&T UNIX version reference
BSD | BSD version reference
BSD/OS | BSD/OS version reference
NetBSD | NetBSD version reference
FreeBSD | FreeBSD version reference
OpenBSD | OpenBSD version reference
DragonFly | DragonFly version reference

ENVIRONMENT

MANPAGER
    Default pager for manuals. If this is unset, falls back to Pager.

PAGER
    The second choice for a manual pager. If this is unset, use more(1).

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
whatis.db
    name of the mandocdb(8) keyword database
whatis.index
    name of the mandocdb(8) filename database
/etc/man.conf
    default man(1) configuration file

EXIT STATUS

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
more(1) re_format(7), mandocdb(8)

AUTHORS
The apropos utility was written by Kristaps Dzonsons, kristaps@bsd.lv.