contrib/mdocml/apropos.1

   1 .\"     $Id: apropos.1,v 1.46 2017/07/04 23:40:01 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: July 4 2017 $
  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 .Sh ENVIRONMENT
 332 .Bl -tag -width MANPAGER
 333 .It Ev MANPAGER
 334 Any non-empty value of the environment variable
 335 .Ev MANPAGER
 336 is used instead of the standard pagination program,
 337 .Xr more 1 ;
 338 see
 339 .Xr man 1
 340 for details.
 341 Only used if
 342 .Fl a
 343 or
 344 .Fl l
 345 is specified.
 346 .It Ev MANPATH
 347 A colon-separated list of directories to search for manual pages; see
 348 .Xr man 1
 349 for details.
 350 Overridden by
 351 .Fl M ,
 352 ignored if
 353 .Fl l
 354 is specified.
 355 .It Ev PAGER
 356 Specifies the pagination program to use when
 357 .Ev MANPAGER
 358 is not defined.
 359 If neither PAGER nor MANPAGER is defined,
 360 .Xr more 1
 361 .Fl s
 362 is used.
 363 Only used if
 364 .Fl a
 365 or
 366 .Fl l
 367 is specified.
 368 .El
 369 .Sh FILES
 370 .Bl -tag -width "/etc/man.conf" -compact
 371 .It Pa mandoc.db
 372 name of the
 373 .Xr makewhatis 8
 374 keyword database
 375 .It Pa /etc/man.conf
 376 default
 377 .Xr man 1
 378 configuration file
 379 .El
 380 .Sh EXIT STATUS
 381 .Ex -std
 382 .Sh EXAMPLES
 383 Search for
 384 .Qq .cf
 385 as a substring of manual names and descriptions:
 386 .Pp
 387 .Dl $ apropos .cf
 388 .Pp
 389 Include matches for
 390 .Qq .cnf
 391 and
 392 .Qq .conf
 393 as well:
 394 .Pp
 395 .Dl $ apropos .cf .cnf .conf
 396 .Pp
 397 Search in names and descriptions using a regular expression:
 398 .Pp
 399 .Dl $ apropos \(aq\(tiset.?[ug]id\(aq
 400 .Pp
 401 Search for manuals in the library section mentioning both the
 402 .Qq optind
 403 and the
 404 .Qq optarg
 405 variables:
 406 .Pp
 407 .Dl $ apropos \-s 3 Va=optind \-a Va=optarg
 408 .Pp
 409 Do exactly the same as calling
 410 .Nm whatis
 411 with the argument
 412 .Qq ssh :
 413 .Pp
 414 .Dl $ apropos \-\- \-i \(aqNm\(ti[[:<:]]ssh[[:>:]]\(aq
 415 .Pp
 416 The following two invocations are equivalent:
 417 .Pp
 418 .D1 Li $ apropos -S Ar arch Li -s Ar section expression
 419 .Bd -ragged -offset indent
 420 .Li $ apropos \e( Ar expression Li \e)
 421 .Li -a arch\(ti^( Ns Ar arch Ns Li |any)$
 422 .Li -a sec\(ti^ Ns Ar section Ns Li $
 423 .Ed
 424 .Sh SEE ALSO
 425 .Xr man 1 ,
 426 .Xr re_format 7 ,
 427 .Xr makewhatis 8
 428 .Sh HISTORY
 429 Part of the functionality of
 430 .Nm whatis
 431 was already provided by the former
 432 .Nm manwhere
 433 utility in
 434 .Bx 1 .
 435 The
 436 .Nm
 437 and
 438 .Nm whatis
 439 utilities first appeared in
 440 .Bx 2 .
 441 They were rewritten from scratch for
 442 .Ox 5.6 .
 443 .Pp
 444 The
 445 .Fl M
 446 option and the
 447 .Ev MANPATH
 448 variable first appeared in
 449 .Bx 4.3 ;
 450 .Fl m
 451 in
 452 .Bx 4.3 Reno ;
 453 .Fl C
 454 in
 455 .Bx 4.4 Lite1 ;
 456 and
 457 .Fl S
 458 and
 459 .Fl s
 460 in
 461 .Ox 4.5
 462 for
 463 .Nm
 464 and in
 465 .Ox 5.6
 466 for
 467 .Nm whatis .
 468 The options
 469 .Fl acfhIKklOTWw
 470 appeared in
 471 .Ox 5.7 .
 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 .