apropos.1

   1 .\"     $Id: apropos.1,v 1.47 2018/02/23 18:54:02 schwarze Exp $
   2 .\"
   3 .\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
   4 .\" Copyright (c) 2011, 2012, 2014, 2017 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: February 23 2018 $
  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 afk
  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 IKOTW
  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 f
  93 Search for all words in
  94 .Ar expression
  95 in manual page names only.
  96 The search is case insensitive and matches whole words only.
  97 In this mode, macro keys, comparison operators, and logical operators
  98 are not available.
  99 .It Fl k
 100 Support the full
 101 .Ar expression
 102 syntax.
 103 It is the default for
 104 .Nm .
 105 .It Fl M Ar path
 106 Use the colon-separated path instead of the default list of paths
 107 searched for
 108 .Xr makewhatis 8
 109 databases.
 110 Invalid paths, or paths without manual databases, are ignored.
 111 .It Fl m Ar path
 112 Prepend the colon-separated paths to the list of paths searched
 113 for
 114 .Xr makewhatis 8
 115 databases.
 116 Invalid paths, or paths without manual databases, are ignored.
 117 .It Fl O Ar outkey
 118 Show the values associated with the key
 119 .Ar outkey
 120 instead of the manual descriptions.
 121 .It Fl S Ar arch
 122 Restrict the search to pages for the specified
 123 .Xr machine 1
 124 architecture.
 125 .Ar arch
 126 is case insensitive.
 127 By default, pages for all architectures are shown.
 128 .It Fl s Ar section
 129 Restrict the search to the specified section of the manual.
 130 By default, pages from all sections are shown.
 131 See
 132 .Xr man 1
 133 for a listing of sections.
 134 .El
 135 .Pp
 136 The options
 137 .Fl chlw
 138 are also supported and are documented in
 139 .Xr man 1 .
 140 The options
 141 .Fl fkl
 142 are mutually exclusive and override each other.
 143 .Pp
 144 An
 145 .Ar expression
 146 consists of search terms joined by logical operators
 147 .Fl a
 148 .Pq and
 149 and
 150 .Fl o
 151 .Pq or .
 152 The
 153 .Fl a
 154 operator has precedence over
 155 .Fl o
 156 and both are evaluated left-to-right.
 157 .Bl -tag -width Ds
 158 .It \&( Ar expr No \&)
 159 True if the subexpression
 160 .Ar expr
 161 is true.
 162 .It Ar expr1 Fl a Ar expr2
 163 True if both
 164 .Ar expr1
 165 and
 166 .Ar expr2
 167 are true (logical
 168 .Sq and ) .
 169 .It Ar expr1 Oo Fl o Oc Ar expr2
 170 True if
 171 .Ar expr1
 172 and/or
 173 .Ar expr2
 174 evaluate to true (logical
 175 .Sq or ) .
 176 .It Ar term
 177 True if
 178 .Ar term
 179 is satisfied.
 180 This has syntax
 181 .Sm off
 182 .Oo
 183 .Op Ar key Op , Ar key ...
 184 .Pq Cm = | \(ti
 185 .Oc
 186 .Ar val ,
 187 .Sm on
 188 where
 189 .Ar key
 190 is an
 191 .Xr mdoc 7
 192 macro to query and
 193 .Ar val
 194 is its value.
 195 See
 196 .Sx Macro Keys
 197 for a list of available keys.
 198 Operator
 199 .Cm =
 200 evaluates a substring, while
 201 .Cm \(ti
 202 evaluates a regular expression.
 203 .It Fl i Ar term
 204 If
 205 .Ar term
 206 is a regular expression, it
 207 is evaluated case-insensitively.
 208 Has no effect on substring terms.
 209 .El
 210 .Pp
 211 Results are sorted according to the following criteria:
 212 .Bl -enum
 213 .It
 214 The manpath directory tree the page is found in, according to the
 215 order specified with
 216 .Fl M ,
 217 .Fl m ,
 218 the
 219 .Ev MANPATH
 220 environment variable, the
 221 .Xr man.conf 5
 222 configuration file, or the default documented in
 223 .Xr man.conf 5 .
 224 .It
 225 The section number in ascending numerical order.
 226 .It
 227 The page name in ascending
 228 .Xr ascii 7
 229 alphabetical order, case-insensitive.
 230 .El
 231 .Pp
 232 Each output line is formatted as
 233 .Pp
 234 .D1 name[, name...](sec) \- description
 235 .Pp
 236 Where
 237 .Dq name
 238 is the manual's name,
 239 .Dq sec
 240 is the manual section, and
 241 .Dq description
 242 is the manual's short description.
 243 If an architecture is specified for the manual, it is displayed as
 244 .Pp
 245 .D1 name(sec/arch) \- description
 246 .Pp
 247 Resulting manuals may be accessed as
 248 .Pp
 249 .Dl $ man \-s sec name
 250 .Pp
 251 If an architecture is specified in the output, use
 252 .Pp
 253 .Dl $ man \-s sec \-S arch name
 254 .Ss Macro Keys
 255 Queries evaluate over a subset of
 256 .Xr mdoc 7
 257 macros indexed by
 258 .Xr makewhatis 8 .
 259 In addition to the macro keys listed below, the special key
 260 .Cm any
 261 may be used to match any available macro key.
 262 .Pp
 263 Names and description:
 264 .Bl -column "xLix" description -offset indent -compact
 265 .It Li \&Nm Ta manual name
 266 .It Li \&Nd Ta one-line manual description
 267 .It Li arch Ta machine architecture (case-insensitive)
 268 .It Li sec  Ta manual section number
 269 .El
 270 .Pp
 271 Sections and cross references:
 272 .Bl -column "xLix" description -offset indent -compact
 273 .It Li \&Sh Ta section header (excluding standard sections)
 274 .It Li \&Ss Ta subsection header
 275 .It Li \&Xr Ta cross reference to another manual page
 276 .It Li \&Rs Ta bibliographic reference
 277 .El
 278 .Pp
 279 Semantic markup for command line utilities:
 280 .Bl -column "xLix" description -offset indent -compact
 281 .It Li \&Fl Ta command line options (flags)
 282 .It Li \&Cm Ta command modifier
 283 .It Li \&Ar Ta command argument
 284 .It Li \&Ic Ta internal or interactive command
 285 .It Li \&Ev Ta environmental variable
 286 .It Li \&Pa Ta file system path
 287 .El
 288 .Pp
 289 Semantic markup for function libraries:
 290 .Bl -column "xLix" description -offset indent -compact
 291 .It Li \&Lb Ta function library name
 292 .It Li \&In Ta include file
 293 .It Li \&Ft Ta function return type
 294 .It Li \&Fn Ta function name
 295 .It Li \&Fa Ta function argument type and name
 296 .It Li \&Vt Ta variable type
 297 .It Li \&Va Ta variable name
 298 .It Li \&Dv Ta defined variable or preprocessor constant
 299 .It Li \&Er Ta error constant
 300 .It Li \&Ev Ta environmental variable
 301 .El
 302 .Pp
 303 Various semantic markup:
 304 .Bl -column "xLix" description -offset indent -compact
 305 .It Li \&An Ta author name
 306 .It Li \&Lk Ta hyperlink
 307 .It Li \&Mt Ta Do mailto Dc hyperlink
 308 .It Li \&Cd Ta kernel configuration declaration
 309 .It Li \&Ms Ta mathematical symbol
 310 .It Li \&Tn Ta tradename
 311 .El
 312 .Pp
 313 Physical markup:
 314 .Bl -column "xLix" description -offset indent -compact
 315 .It Li \&Em Ta italic font or underline
 316 .It Li \&Sy Ta boldface font
 317 .It Li \&Li Ta typewriter font
 318 .El
 319 .Pp
 320 Text production:
 321 .Bl -column "xLix" description -offset indent -compact
 322 .It Li \&St Ta reference to a standards document
 323 .It Li \&At Ta At No version reference
 324 .It Li \&Bx Ta Bx No version reference
 325 .It Li \&Bsx Ta Bsx No version reference
 326 .It Li \&Nx Ta Nx No version reference
 327 .It Li \&Fx Ta Fx No version reference
 328 .It Li \&Ox Ta Ox No version reference
 329 .It Li \&Dx Ta Dx No version reference
 330 .El
 331 .Pp
 332 In general, macro keys are supposed to yield complete results without
 333 expecting the user to consider actual macro usage.
 334 For example, results include:
 335 .Pp
 336 .Bl -tag -width 3n -offset 3n -compact
 337 .It Li \&Fa
 338 function arguments appearing on
 339 .Ic \&Fn
 340 lines
 341 .It Li \&Fn
 342 fuction names marked up with
 343 .Ic \&Fo
 344 macros
 345 .It Li \&In
 346 include file names marked up with
 347 .Ic \&Fd
 348 macros
 349 .It Li \&Vt
 350 types appearing as function return types and
 351 .It \&
 352 types appearing in function arguments in the SYNOPSIS
 353 .El
 354 .Sh ENVIRONMENT
 355 .Bl -tag -width MANPAGER
 356 .It Ev MANPAGER
 357 Any non-empty value of the environment variable
 358 .Ev MANPAGER
 359 is used instead of the standard pagination program,
 360 .Xr more 1 ;
 361 see
 362 .Xr man 1
 363 for details.
 364 Only used if
 365 .Fl a
 366 or
 367 .Fl l
 368 is specified.
 369 .It Ev MANPATH
 370 A colon-separated list of directories to search for manual pages; see
 371 .Xr man 1
 372 for details.
 373 Overridden by
 374 .Fl M ,
 375 ignored if
 376 .Fl l
 377 is specified.
 378 .It Ev PAGER
 379 Specifies the pagination program to use when
 380 .Ev MANPAGER
 381 is not defined.
 382 If neither PAGER nor MANPAGER is defined,
 383 .Xr more 1
 384 .Fl s
 385 is used.
 386 Only used if
 387 .Fl a
 388 or
 389 .Fl l
 390 is specified.
 391 .El
 392 .Sh FILES
 393 .Bl -tag -width "/etc/man.conf" -compact
 394 .It Pa mandoc.db
 395 name of the
 396 .Xr makewhatis 8
 397 keyword database
 398 .It Pa /etc/man.conf
 399 default
 400 .Xr man 1
 401 configuration file
 402 .El
 403 .Sh EXIT STATUS
 404 .Ex -std
 405 .Sh EXAMPLES
 406 Search for
 407 .Qq .cf
 408 as a substring of manual names and descriptions:
 409 .Pp
 410 .Dl $ apropos .cf
 411 .Pp
 412 Include matches for
 413 .Qq .cnf
 414 and
 415 .Qq .conf
 416 as well:
 417 .Pp
 418 .Dl $ apropos .cf .cnf .conf
 419 .Pp
 420 Search in names and descriptions using a regular expression:
 421 .Pp
 422 .Dl $ apropos \(aq\(tiset.?[ug]id\(aq
 423 .Pp
 424 Search for manuals in the library section mentioning both the
 425 .Qq optind
 426 and the
 427 .Qq optarg
 428 variables:
 429 .Pp
 430 .Dl $ apropos \-s 3 Va=optind \-a Va=optarg
 431 .Pp
 432 Do exactly the same as calling
 433 .Nm whatis
 434 with the argument
 435 .Qq ssh :
 436 .Pp
 437 .Dl $ apropos \-\- \-i \(aqNm\(ti[[:<:]]ssh[[:>:]]\(aq
 438 .Pp
 439 The following two invocations are equivalent:
 440 .Pp
 441 .D1 Li $ apropos -S Ar arch Li -s Ar section expression
 442 .Bd -ragged -offset indent
 443 .Li $ apropos \e( Ar expression Li \e)
 444 .Li -a arch\(ti^( Ns Ar arch Ns Li |any)$
 445 .Li -a sec\(ti^ Ns Ar section Ns Li $
 446 .Ed
 447 .Sh SEE ALSO
 448 .Xr man 1 ,
 449 .Xr re_format 7 ,
 450 .Xr makewhatis 8
 451 .Sh HISTORY
 452 Part of the functionality of
 453 .Nm whatis
 454 was already provided by the former
 455 .Nm manwhere
 456 utility in
 457 .Bx 1 .
 458 The
 459 .Nm
 460 and
 461 .Nm whatis
 462 utilities first appeared in
 463 .Bx 2 .
 464 They were rewritten from scratch for
 465 .Ox 5.6 .
 466 .Pp
 467 The
 468 .Fl M
 469 option and the
 470 .Ev MANPATH
 471 variable first appeared in
 472 .Bx 4.3 ;
 473 .Fl m
 474 in
 475 .Bx 4.3 Reno ;
 476 .Fl C
 477 in
 478 .Bx 4.4 Lite1 ;
 479 and
 480 .Fl S
 481 and
 482 .Fl s
 483 in
 484 .Ox 4.5
 485 for
 486 .Nm
 487 and in
 488 .Ox 5.6
 489 for
 490 .Nm whatis .
 491 The options
 492 .Fl acfhIKklOTWw
 493 appeared in
 494 .Ox 5.7 .
 495 .Sh AUTHORS
 496 .An -nosplit
 497 .An Bill Joy
 498 wrote
 499 .Nm manwhere
 500 in 1977 and the original
 501 .Bx
 502 .Nm
 503 and
 504 .Nm whatis
 505 in February 1979.
 506 The current version was written by
 507 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
 508 and
 509 .An Ingo Schwarze Aq Mt schwarze@openbsd.org .