contrib/mdocml/apropos.1

   1 .\" $Id: apropos.1,v 1.51 2020/10/01 22:50:00 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: October 1 2020 $
  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 less 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 less 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 less 1
 367 is used.
 368 Only used if
 369 .Fl a
 370 or
 371 .Fl l
 372 is specified.
 373 .El
 374 .Sh FILES
 375 .Bl -tag -width "/etc/man.conf" -compact
 376 .It Pa mandoc.db
 377 name of the
 378 .Xr makewhatis 8
 379 keyword database
 380 .It Pa /etc/man.conf
 381 default
 382 .Xr man 1
 383 configuration file
 384 .El
 385 .Sh EXIT STATUS
 386 .Ex -std
 387 .Sh EXAMPLES
 388 Search for
 389 .Qq .cf
 390 as a substring of manual names and descriptions:
 391 .Pp
 392 .Dl $ apropos =.cf
 393 .Pp
 394 Include matches for
 395 .Qq .cnf
 396 and
 397 .Qq .conf
 398 as well:
 399 .Pp
 400 .Dl $ apropos =.cf =.cnf =.conf
 401 .Pp
 402 Search in names and descriptions using a case-sensitive regular expression:
 403 .Pp
 404 .Dl $ apropos \(aq\(tiset.?[ug]id\(aq
 405 .Pp
 406 Search for all manual pages in a given section:
 407 .Pp
 408 .Dl $ apropos \-s 9 \&.
 409 .Pp
 410 Search for manuals in the library section mentioning both the
 411 .Qq optind
 412 and the
 413 .Qq optarg
 414 variables:
 415 .Pp
 416 .Dl $ apropos \-s 3 Va=optind \-a Va=optarg
 417 .Pp
 418 Do exactly the same as calling
 419 .Nm whatis
 420 with the argument
 421 .Qq ssh :
 422 .Pp
 423 .Dl $ apropos \-\- \-i \(aqNm\(ti[[:<:]]ssh[[:>:]]\(aq
 424 .Pp
 425 The following two invocations are equivalent:
 426 .Pp
 427 .D1 Li $ apropos -S Ar arch Li -s Ar section expression
 428 .Bd -ragged -offset indent
 429 .Li $ apropos \e( Ar expression Li \e)
 430 .Li -a arch\(ti^( Ns Ar arch Ns Li |any)$
 431 .Li -a sec\(ti^ Ns Ar section Ns Li $
 432 .Ed
 433 .Sh SEE ALSO
 434 .Xr man 1 ,
 435 .Xr re_format 7 ,
 436 .Xr makewhatis 8
 437 .Sh STANDARDS
 438 The
 439 .Nm
 440 utility is compliant with the
 441 .St -p1003.1-2008
 442 specification of
 443 .Xr man 1
 444 .Fl k .
 445 .Pp
 446 All options, the
 447 .Nm whatis
 448 command, support for logical operators, macro keys,
 449 substring matching, sorting of results, the environment variables
 450 .Ev MANPAGER
 451 and
 452 .Ev MANPATH ,
 453 the database format, and the configuration file
 454 are extensions to that specification.
 455 .Sh HISTORY
 456 Part of the functionality of
 457 .Nm whatis
 458 was already provided by the former
 459 .Nm manwhere
 460 utility in
 461 .Bx 1 .
 462 The
 463 .Nm
 464 and
 465 .Nm whatis
 466 utilities first appeared in
 467 .Bx 2 .
 468 They were rewritten from scratch for
 469 .Ox 5.6 .
 470 .Pp
 471 The
 472 .Fl M
 473 option and the
 474 .Ev MANPATH
 475 variable first appeared in
 476 .Bx 4.3 ;
 477 .Fl m
 478 in
 479 .Bx 4.3 Reno ;
 480 .Fl C
 481 in
 482 .Bx 4.4 Lite1 ;
 483 and
 484 .Fl S
 485 and
 486 .Fl s
 487 in
 488 .Ox 4.5
 489 for
 490 .Nm
 491 and in
 492 .Ox 5.6
 493 for
 494 .Nm whatis .
 495 The options
 496 .Fl acfhIKklOTWw
 497 appeared in
 498 .Ox 5.7 .
 499 .Sh AUTHORS
 500 .An -nosplit
 501 .An Bill Joy
 502 wrote
 503 .Nm manwhere
 504 in 1977 and the original
 505 .Bx
 506 .Nm
 507 and
 508 .Nm whatis
 509 in February 1979.
 510 The current version was written by
 511 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
 512 and
 513 .An Ingo Schwarze Aq Mt schwarze@openbsd.org .