1APROPOS(1)                BSD General Commands Manual               APROPOS(1)
2

NAME

4     apropos, whatis — search manual page databases
5

SYNOPSIS

7     apropos [-afk] [-C file] [-M path] [-m path] [-O outkey] [-S arch]
8             [-s section] expression ...
9

DESCRIPTION

11     The apropos and whatis utilities query manual page databases generated by
12     makewhatis(8), evaluating expression for each file in each database.  By
13     default, they display the names, section numbers, and description lines
14     of all matching manuals.
15
16     By default, apropos searches for makewhatis(8) databases in the default
17     paths stipulated by man(1) and uses case-insensitive extended regular
18     expression matching over manual names and descriptions (the Nm and Nd
19     macro keys).  Multiple terms imply pairwise -o.
20
21     whatis is a synonym for apropos -f.
22
23     The options are as follows:
24
25     -a      Instead of showing only the title lines, show the complete manual
26             pages, just like man(1) -a would.  If the standard output is a
27             terminal device and -c is not specified, use more(1) to paginate
28             them.  In -a mode, the options -IKOTW described in the mandoc(1)
29             manual are also available.
30
31     -C file
32             Specify an alternative configuration file in man.conf(5) format.
33
34     -f      Search for all words in expression in manual page names only.
35             The search is case-insensitive and matches whole words only.  In
36             this mode, macro keys, comparison operators, and logical opera‐
37             tors are not available.
38
39     -k      Support the full expression syntax.  It is the default for
40             apropos.
41
42     -M path
43             Use the colon-separated path instead of the default list of paths
44             searched for makewhatis(8) databases.  Invalid paths, or paths
45             without manual databases, are ignored.
46
47     -m path
48             Prepend the colon-separated paths to the list of paths searched
49             for makewhatis(8) databases.  Invalid paths, or paths without
50             manual databases, are ignored.
51
52     -O outkey
53             Show the values associated with the key outkey instead of the
54             manual descriptions.
55
56     -S arch
57             Restrict the search to pages for the specified machine(1) archi‐
58             tecture.  arch is case-insensitive.  By default, pages for all
59             architectures are shown.
60
61     -s section
62             Restrict the search to the specified section of the manual.  By
63             default, pages from all sections are shown.  See man(1) for a
64             listing of sections.
65
66     The options -chlw are also supported and are documented in man(1).  The
67     options -fkl are mutually exclusive and override each other.
68
69     An expression consists of search terms joined by logical operators -a
70     (and) and -o (or).  The -a operator has precedence over -o and both are
71     evaluated left-to-right.
72
73     ( expr )
74             True if the subexpression expr is true.
75
76     expr1 -a expr2
77             True if both expr1 and expr2 are true (logical ‘and’).
78
79     expr1 [-o] expr2
80             True if expr1 and/or expr2 evaluate to true (logical ‘or’).
81
82     term    True if term is satisfied.  This has syntax
83             [[key[,key...]](=|~)]val, where key is an mdoc(7) macro to query
84             and val is its value.  See Macro Keys for a list of available
85             keys.  Operator = evaluates a substring, while ~ evaluates a
86             case-sensitive extended regular expression.
87
88     -i term
89             If term is a regular expression, it is evaluated case-insensi‐
90             tively.  Has no effect on substring terms.
91
92     Results are sorted first according to the section number in ascending
93     numerical order, then by the page name in ascending ascii(7) alphabetical
94     order, case-insensitive.
95
96     Each output line is formatted as
97
98           name[, name...](sec) - description
99
100     Where “name” is the manual's name, “sec” is the manual section, and
101     “description” is the manual's short description.  If an architecture is
102     specified for the manual, it is displayed as
103
104           name(sec/arch) - description
105
106     Resulting manuals may be accessed as
107
108           $ man -s sec name
109
110     If an architecture is specified in the output, use
111
112           $ man -s sec -S arch name
113
114   Macro Keys
115     Queries evaluate over a subset of mdoc(7) macros indexed by
116     makewhatis(8).  In addition to the macro keys listed below, the special
117     key any may be used to match any available macro key.
118
119     Names and description:
120           Nm      manual name
121           Nd      one-line manual description
122           arch    machine architecture (case-insensitive)
123           sec     manual section number
124
125     Sections and cross references:
126           Sh      section header (excluding standard sections)
127           Ss      subsection header
128           Xr      cross reference to another manual page
129           Rs      bibliographic reference
130
131     Semantic markup for command line utilities:
132           Fl      command line options (flags)
133           Cm      command modifier
134           Ar      command argument
135           Ic      internal or interactive command
136           Ev      environmental variable
137           Pa      file system path
138
139     Semantic markup for function libraries:
140           Lb      function library name
141           In      include file
142           Ft      function return type
143           Fn      function name
144           Fa      function argument type and name
145           Vt      variable type
146           Va      variable name
147           Dv      defined variable or preprocessor constant
148           Er      error constant
149           Ev      environmental variable
150
151     Various semantic markup:
152           An      author name
153           Lk      hyperlink
154           Mt      “mailto” hyperlink
155           Cd      kernel configuration declaration
156           Ms      mathematical symbol
157           Tn      tradename
158
159     Physical markup:
160           Em      italic font or underline
161           Sy      boldface font
162           Li      typewriter font
163
164     Text production:
165           St      reference to a standards document
166           At      AT&T UNIX version reference
167           Bx      BSD version reference
168           Bsx     BSD/OS version reference
169           Nx      NetBSD version reference
170           Fx      FreeBSD version reference
171           Ox      OpenBSD version reference
172           Dx      DragonFly version reference
173
174     In general, macro keys are supposed to yield complete results without
175     expecting the user to consider actual macro usage.  For example, results
176     include:
177
178        Fa   function arguments appearing on Fn lines
179        Fn   function names marked up with Fo macros
180        In   include file names marked up with Fd macros
181        Vt   types appearing as function return types and
182             types appearing in function arguments in the SYNOPSIS
183

ENVIRONMENT

185     MANPAGER  Any non-empty value of the environment variable MANPAGER is
186               used instead of the standard pagination program, more(1); see
187               man(1) for details.  Only used if -a or -l is specified.
188
189     MANPATH   A colon-separated list of directories to search for manual
190               pages; see man(1) for details.  Overridden by -M, ignored if -l
191               is specified.
192
193     PAGER     Specifies the pagination program to use when MANPAGER is not
194               defined.  If neither PAGER nor MANPAGER is defined, more(1) -s
195               is used.  Only used if -a or -l is specified.
196

FILES

198     mandoc.db      name of the makewhatis(8) keyword database
199     /etc/man.conf  default man(1) configuration file
200

EXIT STATUS

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

EXAMPLES

205     Search for ".cf" as a substring of manual names and descriptions:
206
207           $ apropos =.cf
208
209     Include matches for ".cnf" and ".conf" as well:
210
211           $ apropos =.cf =.cnf =.conf
212
213     Search in names and descriptions using a case-sensitive regular expres‐
214     sion:
215
216           $ apropos '~set.?[ug]id'
217
218     Search for manuals in the library section mentioning both the "optind"
219     and the "optarg" variables:
220
221           $ apropos -s 3 Va=optind -a Va=optarg
222
223     Do exactly the same as calling whatis with the argument "ssh":
224
225           $ apropos -- -i 'Nm~[[:<:]]ssh[[:>:]]'
226
227     The following two invocations are equivalent:
228
229           $ apropos -S arch -s section expression
230
231           $ apropos \( expression \) -a arch~^(arch|any)$ -a sec~^section$
232

SEE ALSO

234     man(1), re_format(7), makewhatis(8)
235

STANDARDS

237     The apropos utility is compliant with the IEEE Std 1003.1-2008
238     (“POSIX.1”) specification of man(1) -k.
239
240     All options, the whatis command, support for logical operators, macro
241     keys, substring matching, sorting of results, the environment variables
242     MANPAGER and MANPATH, the database format, and the configuration file are
243     extensions to that specification.
244

HISTORY

246     Part of the functionality of whatis was already provided by the former
247     manwhere utility in 1BSD.  The apropos and whatis utilities first
248     appeared in 2BSD.  They were rewritten from scratch for OpenBSD 5.6.
249
250     The -M option and the MANPATH variable first appeared in 4.3BSD; -m in
251     4.3BSD-Reno; -C in 4.4BSD Lite1; and -S and -s in OpenBSD 4.5 for apropos
252     and in OpenBSD 5.6 for whatis.  The options -acfhIKklOTWw appeared in
253     OpenBSD 5.7.
254

AUTHORS

256     Bill Joy wrote manwhere in 1977 and the original BSD apropos and whatis
257     in February 1979.  The current version was written by Kristaps Dzonsons
258     <kristaps@bsd.lv> and Ingo Schwarze <schwarze@openbsd.org>.
259
260BSD                              May 10, 2020                              BSD
Impressum