apropos.1

   1 .\"     $Id: apropos.1,v 1.33 2014/08/22 04:52:55 schwarze Exp $
   2 .\"
   3 .\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
   4 .\" Copyright (c) 2011, 2012, 2014 Ingo Schwarze <schwarze@openbsd.org>
   5 .\"
   6 .\" Permission to use, copy, modify, and distribute this software for any
   7 .\" purpose with or without fee is hereby granted, provided that the above
   8 .\" copyright notice and this permission notice appear in all copies.
   9 .\"
  10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  17 .\"
  18 .Dd $Mdocdate: August 22 2014 $
  19 .Dt APROPOS 1
  20 .Os
  21 .Sh NAME
  22 .Nm apropos ,
  23 .Nm whatis
  24 .Nd search manual page databases
  25 .Sh SYNOPSIS
  26 .Nm
  27 .Op Fl acfkw
  28 .Op Fl C Ar file
  29 .Op Fl M Ar path
  30 .Op Fl m Ar path
  31 .Op Fl O Ar outkey
  32 .Op Fl S Ar arch
  33 .Op Fl s Ar section
  34 .Ar expression ...
  35 .Sh DESCRIPTION
  36 The
  37 .Nm apropos
  38 and
  39 .Nm whatis
  40 utilities query manual page databases generated by
  41 .Xr makewhatis 8 ,
  42 evaluating
  43 .Ar expression
  44 for each file in each database.
  45 By default, they display the names, section numbers, and description lines
  46 of all matching manuals.
  47 .Pp
  48 By default,
  49 .Nm
  50 searches for
  51 .Xr makewhatis 8
  52 databases in the default paths stipulated by
  53 .Xr man 1
  54 and uses case-insensitive substring matching
  55 .Pq the Cm = No operator
  56 over manual names and descriptions
  57 .Pq the Li \&Nm No and Li \&Nd No macro keys .
  58 Multiple terms imply pairwise
  59 .Fl o .
  60 .Pp
  61 .Nm whatis
  62 is a synonym for
  63 .Nm
  64 .Fl f .
  65 .Pp
  66 The options are as follows:
  67 .Bl -tag -width Ds
  68 .It Fl a
  69 Instead of showing only the title lines, show the complete manual pages,
  70 just like
  71 .Xr man 1
  72 .Fl a
  73 would.
  74 If the standard output is a terminal device and
  75 .Fl c
  76 is not specified, use
  77 .Xr more 1
  78 to paginate them.
  79 In
  80 .Fl a
  81 mode, the options
  82 .Fl IOTW
  83 described in the
  84 .Xr mandoc 1
  85 manual are also available.
  86 .It Fl C Ar file
  87 Specify an alternative configuration
  88 .Ar file
  89 in
  90 .Xr man.conf 5
  91 format.
  92 .It Fl c
  93 In
  94 .Fl a
  95 mode, copy the formatted manual pages to the standard output without using
  96 .Xr more 1
  97 to paginate them.
  98 .It Fl f
  99 Search for all words in
 100 .Ar expression
 101 in manual page names only.
 102 The search is case insensitive and matches whole words only.
 103 In this mode, macro keys, comparison operators, and logical operators
 104 are not available.
 105 This overrides any earlier
 106 .Fl k
 107 option.
 108 .It Fl k
 109 Support the full
 110 .Ar expression
 111 syntax.
 112 This overrides any earlier
 113 .Fl f
 114 option.
 115 It is the default for
 116 .Nm .
 117 .It Fl M Ar path
 118 Use the colon-separated path instead of the default list of paths
 119 searched for
 120 .Xr makewhatis 8
 121 databases.
 122 Invalid paths, or paths without manual databases, are ignored.
 123 .It Fl m Ar path
 124 Prepend the colon-separated paths to the list of paths searched
 125 for
 126 .Xr makewhatis 8
 127 databases.
 128 Invalid paths, or paths without manual databases, are ignored.
 129 .It Fl O Ar outkey
 130 Show the values associated with the key
 131 .Ar outkey
 132 instead of the manual descriptions.
 133 .It Fl S Ar arch
 134 Restrict the search to pages for the specified
 135 .Xr machine 1
 136 architecture.
 137 .Ar arch
 138 is case insensitive.
 139 By default, pages for all architectures are shown.
 140 .It Fl s Ar section
 141 Restrict the search to the specified section of the manual.
 142 By default, pages from all sections are shown.
 143 See
 144 .Xr man 1
 145 for a listing of sections.
 146 .It Fl w
 147 Instead of showing title lines, show the pathnames of the matching
 148 manual pages, just like
 149 .Xr man 1
 150 .Fl w
 151 would.
 152 .El
 153 .Pp
 154 An
 155 .Ar expression
 156 consists of search terms joined by logical operators
 157 .Fl a
 158 .Pq and
 159 and
 160 .Fl o
 161 .Pq or .
 162 The
 163 .Fl a
 164 operator has precedence over
 165 .Fl o
 166 and both are evaluated left-to-right.
 167 .Bl -tag -width Ds
 168 .It \&( Ar expr No \&)
 169 True if the subexpression
 170 .Ar expr
 171 is true.
 172 .It Ar expr1 Fl a Ar expr2
 173 True if both
 174 .Ar expr1
 175 and
 176 .Ar expr2
 177 are true (logical
 178 .Sq and ) .
 179 .It Ar expr1 Oo Fl o Oc Ar expr2
 180 True if
 181 .Ar expr1
 182 and/or
 183 .Ar expr2
 184 evaluate to true (logical
 185 .Sq or ) .
 186 .It Ar term
 187 True if
 188 .Ar term
 189 is satisfied.
 190 This has syntax
 191 .Sm off
 192 .Oo
 193 .Op Ar key Op , Ar key ...
 194 .Pq Cm = | ~
 195 .Oc
 196 .Ar val ,
 197 .Sm on
 198 where
 199 .Ar key
 200 is an
 201 .Xr mdoc 7
 202 macro to query and
 203 .Ar val
 204 is its value.
 205 See
 206 .Sx Macro Keys
 207 for a list of available keys.
 208 Operator
 209 .Cm =
 210 evaluates a substring, while
 211 .Cm ~
 212 evaluates a regular expression.
 213 .It Fl i Ar term
 214 If
 215 .Ar term
 216 is a regular expression, it
 217 is evaluated case-insensitively.
 218 Has no effect on substring terms.
 219 .El
 220 .Pp
 221 Results are sorted by manual sections and names, with output formatted as
 222 .Pp
 223 .D1 name[, name...](sec) \- description
 224 .Pp
 225 Where
 226 .Dq name
 227 is the manual's name,
 228 .Dq sec
 229 is the manual section, and
 230 .Dq description
 231 is the manual's short description.
 232 If an architecture is specified for the manual, it is displayed as
 233 .Pp
 234 .D1 name(sec/arch) \- description
 235 .Pp
 236 Resulting manuals may be accessed as
 237 .Pp
 238 .Dl $ man \-s sec name
 239 .Pp
 240 If an architecture is specified in the output, use
 241 .Pp
 242 .Dl $ man \-s sec \-S arch name
 243 .Ss Macro Keys
 244 Queries evaluate over a subset of
 245 .Xr mdoc 7
 246 macros indexed by
 247 .Xr makewhatis 8 .
 248 In addition to the macro keys listed below, the special key
 249 .Cm any
 250 may be used to match any available macro key.
 251 .Pp
 252 Names and description:
 253 .Bl -column "xLix" description -offset indent -compact
 254 .It Li \&Nm Ta manual name
 255 .It Li \&Nd Ta one-line manual description
 256 .It Li arch Ta machine architecture (case-insensitive)
 257 .It Li sec  Ta manual section number
 258 .El
 259 .Pp
 260 Sections and cross references:
 261 .Bl -column "xLix" description -offset indent -compact
 262 .It Li \&Sh Ta section header (excluding standard sections)
 263 .It Li \&Ss Ta subsection header
 264 .It Li \&Xr Ta cross reference to another manual page
 265 .It Li \&Rs Ta bibliographic reference
 266 .El
 267 .Pp
 268 Semantic markup for command line utilities:
 269 .Bl -column "xLix" description -offset indent -compact
 270 .It Li \&Fl Ta command line options (flags)
 271 .It Li \&Cm Ta command modifier
 272 .It Li \&Ar Ta command argument
 273 .It Li \&Ic Ta internal or interactive command
 274 .It Li \&Ev Ta environmental variable
 275 .It Li \&Pa Ta file system path
 276 .El
 277 .Pp
 278 Semantic markup for function libraries:
 279 .Bl -column "xLix" description -offset indent -compact
 280 .It Li \&Lb Ta function library name
 281 .It Li \&In Ta include file
 282 .It Li \&Ft Ta function return type
 283 .It Li \&Fn Ta function name
 284 .It Li \&Fa Ta function argument type and name
 285 .It Li \&Vt Ta variable type
 286 .It Li \&Va Ta variable name
 287 .It Li \&Dv Ta defined variable or preprocessor constant
 288 .It Li \&Er Ta error constant
 289 .It Li \&Ev Ta environmental variable
 290 .El
 291 .Pp
 292 Various semantic markup:
 293 .Bl -column "xLix" description -offset indent -compact
 294 .It Li \&An Ta author name
 295 .It Li \&Lk Ta hyperlink
 296 .It Li \&Mt Ta Do mailto Dc hyperlink
 297 .It Li \&Cd Ta kernel configuration declaration
 298 .It Li \&Ms Ta mathematical symbol
 299 .It Li \&Tn Ta tradename
 300 .El
 301 .Pp
 302 Physical markup:
 303 .Bl -column "xLix" description -offset indent -compact
 304 .It Li \&Em Ta italic font or underline
 305 .It Li \&Sy Ta boldface font
 306 .It Li \&Li Ta typewriter font
 307 .El
 308 .Pp
 309 Text production:
 310 .Bl -column "xLix" description -offset indent -compact
 311 .It Li \&St Ta reference to a standards document
 312 .It Li \&At Ta At No version reference
 313 .It Li \&Bx Ta Bx No version reference
 314 .It Li \&Bsx Ta Bsx No version reference
 315 .It Li \&Nx Ta Nx No version reference
 316 .It Li \&Fx Ta Fx No version reference
 317 .It Li \&Ox Ta Ox No version reference
 318 .It Li \&Dx Ta Dx No version reference
 319 .El
 320 .Sh ENVIRONMENT
 321 .Bl -tag -width MANPAGER
 322 .It Ev MANPAGER
 323 Any non-empty value of the environment variable
 324 .Ev MANPAGER
 325 will be used instead of the standard pagination program,
 326 .Xr more 1 .
 327 .It Ev MANPATH
 328 The standard search path used by
 329 .Xr man 1
 330 may be changed by specifying a path in the
 331 .Ev MANPATH
 332 environment variable.
 333 Invalid paths, or paths without manual databases, are ignored.
 334 Overridden by
 335 .Fl M .
 336 If
 337 .Ev MANPATH
 338 begins with a colon, it is appended to the default list;
 339 if it ends with a colon, it is prepended to the default list;
 340 or if it contains two adjacent colons,
 341 the standard search path is inserted between the colons.
 342 If none of these conditions are met, it overrides the
 343 standard search path.
 344 .It Ev PAGER
 345 Specifies the pagination program to use when
 346 .Ev MANPAGER
 347 is not defined.
 348 If neither PAGER nor MANPAGER is defined,
 349 .Pa /usr/bin/more Fl s
 350 will be used.
 351 .El
 352 .Sh FILES
 353 .Bl -tag -width "/etc/man.conf" -compact
 354 .It Pa mandoc.db
 355 name of the
 356 .Xr makewhatis 8
 357 keyword database
 358 .It Pa /etc/man.conf
 359 default
 360 .Xr man 1
 361 configuration file
 362 .El
 363 .Sh EXIT STATUS
 364 .Ex -std
 365 .Sh EXAMPLES
 366 Search for
 367 .Qq .cf
 368 as a substring of manual names and descriptions:
 369 .Pp
 370 .Dl $ apropos .cf
 371 .Pp
 372 Include matches for
 373 .Qq .cnf
 374 and
 375 .Qq .conf
 376 as well:
 377 .Pp
 378 .Dl $ apropos .cf .cnf .conf
 379 .Pp
 380 Search in names and descriptions using a regular expression:
 381 .Pp
 382 .Dl $ apropos '~set.?[ug]id'
 383 .Pp
 384 Search for manuals in the library section mentioning both the
 385 .Qq optind
 386 and the
 387 .Qq optarg
 388 variables:
 389 .Pp
 390 .Dl $ apropos \-s 3 Va=optind \-a Va=optarg
 391 .Pp
 392 Do exactly the same as calling
 393 .Xr whatis 1
 394 with the argument
 395 .Qq ssh :
 396 .Pp
 397 .Dl $ apropos \-\- \-i 'Nm~[[:<:]]ssh[[:>:]]'
 398 .Pp
 399 The following two invocations are equivalent:
 400 .Pp
 401 .D1 Li $ apropos -S Ar arch Li -s Ar section expression
 402 .Bd -ragged -offset indent
 403 .Li $ apropos \e( Ar expression Li \e)
 404 .Li -a arch~^( Ns Ar arch Ns Li |any)$
 405 .Li -a sec~^ Ns Ar section Ns Li $
 406 .Ed
 407 .Sh SEE ALSO
 408 .Xr man 1 ,
 409 .Xr re_format 7 ,
 410 .Xr makewhatis 8
 411 .Sh HISTORY
 412 Part of the functionality of
 413 .Nm whatis
 414 was already provided by the former
 415 .Nm manwhere
 416 utility in
 417 .Bx 1 .
 418 The
 419 .Nm
 420 and
 421 .Nm whatis
 422 utilities first appeared in
 423 .Bx 2 .
 424 They were rewritten from scratch for
 425 .Ox 5.6 .
 426 .Pp
 427 The
 428 .Fl M
 429 option and the
 430 .Ev MANPATH
 431 variable first appeared in
 432 .Bx 4.3 ;
 433 .Fl m
 434 in
 435 .Bx 4.3 Reno ;
 436 .Fl C
 437 in
 438 .Bx 4.4 Lite1 ;
 439 and
 440 .Fl S
 441 and
 442 .Fl s
 443 in
 444 .Ox 4.5
 445 for
 446 .Nm
 447 and in
 448 .Ox 5.6
 449 for
 450 .Nm whatis .
 451 .Sh AUTHORS
 452 .An -nosplit
 453 .An Bill Joy
 454 wrote
 455 .Nm manwhere
 456 in 1977 and the original
 457 .Bx
 458 .Nm
 459 and
 460 .Nm whatis
 461 in February 1979.
 462 The current version was written by
 463 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
 464 and
 465 .An Ingo Schwarze Aq Mt schwarze@openbsd.org .