contrib/mdocml/apropos.1

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