1APROPOS(1) BSD General Commands Manual APROPOS(1)
2
4 apropos, whatis — search manual page databases
5
7 apropos [-afk] [-C file] [-M path] [-m path] [-O outkey] [-S arch]
8 [-s section] expression ...
9
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 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 whatis is a synonym for apropos -f.
22 The options are as follows:
24 -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 -C file
32 Specify an alternative configuration file in man.conf(5) format.
33 -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 -k Support the full expression syntax. It is the default for
40 apropos.
41 -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 -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 -O outkey
53 Show the values associated with the key outkey instead of the
54 manual descriptions.
55 -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 -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 The options -chlw are also supported and are documented in man(1). The
67 options -fkl are mutually exclusive and override each other.
68 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 ( expr )
74 True if the subexpression expr is true.
75 expr1 -a expr2
77 True if both expr1 and expr2 are true (logical ‘and’).
78 expr1 [-o] expr2
80 True if expr1 and/or expr2 evaluate to true (logical ‘or’).
81 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 -i term
89 If term is a regular expression, it is evaluated case-insensi‐
90 tively. Has no effect on substring terms.
91 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 Each output line is formatted as
97 name[, name...](sec) - description
99 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 name(sec/arch) - description
105 Resulting manuals may be accessed as
107 $ man -s sec name
109 If an architecture is specified in the output, use
111 $ man -s sec -S arch name
113 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 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 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 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 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 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 Physical markup:
160 Em italic font or underline
161 Sy boldface font
162 Li typewriter font
163 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 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 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
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 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 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
198 mandoc.db name of the makewhatis(8) keyword database
199 /etc/man.conf default man(1) configuration file
200
202 The apropos utility exits 0 on success, and >0 if an error occurs.
203
205 Search for ".cf" as a substring of manual names and descriptions:
206 $ apropos =.cf
208 Include matches for ".cnf" and ".conf" as well:
210 $ apropos =.cf =.cnf =.conf
212 Search in names and descriptions using a case-sensitive regular expres‐
214 sion:
215 $ apropos '~set.?[ug]id'
217 Search for manuals in the library section mentioning both the "optind"
219 and the "optarg" variables:
220 $ apropos -s 3 Va=optind -a Va=optarg
222 Do exactly the same as calling whatis with the argument "ssh":
224 $ apropos -- -i 'Nm~[[:<:]]ssh[[:>:]]'
226 The following two invocations are equivalent:
228 $ apropos -S arch -s section expression
230 $ apropos \( expression \) -a arch~^(arch|any)$ -a sec~^section$
232
234 man(1), re_format(7), makewhatis(8)
235
237 The apropos utility is compliant with the IEEE Std 1003.1-2008
238 (“POSIX.1”) specification of man(1) -k.
239 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
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 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
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>.
259BSD May 10, 2020 BSD