contrib/mdocml/apropos.1

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