contrib/mdocml/apropos.1

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