apropos.1

   1 .\"     $Id: apropos.1,v 1.25 2014/04/04 15:55:19 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 4 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 C Ar file
  28 .Op Fl M Ar path
  29 .Op Fl m Ar path
  30 .Op Fl O Ar outkey
  31 .Op Fl S Ar arch
  32 .Op Fl s Ar section
  33 .Ar expression ...
  34 .Sh DESCRIPTION
  35 The
  36 .Nm apropos
  37 and
  38 .Nm whatis
  39 utilities query manual page databases generated by
  40 .Xr mandocdb 8 ,
  41 evaluating on
  42 .Ar expression
  43 for each file in each database.
  44 .Pp
  45 By default,
  46 .Nm
  47 searches for
  48 .Xr mandocdb 8
  49 databases in the default paths stipulated by
  50 .Xr man 1 ,
  51 parses terms as case-sensitive regular expressions
  52 .Pq the Li \&~ operator
  53 over manual names and descriptions
  54 .Pq the Li \&Nm No and Li \&Nd No macro keys .
  55 Multiple terms imply pairwise
  56 .Fl o .
  57 .Nm whatis
  58 maps terms only to case-sensitive manual names.
  59 .Pp
  60 Its arguments are as follows:
  61 .Bl -tag -width Ds
  62 .It Fl C Ar file
  63 Specify an alternative configuration
  64 .Ar file
  65 in
  66 .Xr man.conf 5
  67 format.
  68 .It Fl M Ar path
  69 Use the colon-separated path instead of the default list of paths
  70 searched for
  71 .Xr mandocdb 8
  72 databases.
  73 Invalid paths, or paths without manual databases, are ignored.
  74 .It Fl m Ar path
  75 Prepend the colon-separated paths to the list of paths searched
  76 for
  77 .Xr mandocdb 8
  78 databases.
  79 Invalid paths, or paths without manual databases, are ignored.
  80 .It Fl O Ar outkey
  81 Show the values associated with the key
  82 .Ar outkey
  83 instead of the manual descriptions.
  84 .It Fl S Ar arch
  85 Restrict the search to pages for the specified
  86 .Xr machine 1
  87 architecture.
  88 .Ar arch
  89 is case insensitive.
  90 By default, pages for all architectures are shown.
  91 .It Fl s Ar section
  92 Restrict the search to the specified section of the manual.
  93 By default, pages from all sections are shown.
  94 See
  95 .Xr man 1
  96 for a listing of sections.
  97 .El
  98 .Pp
  99 An
 100 .Ar expression
 101 consists of search terms joined by logical operators
 102 .Fl a
 103 .Pq and
 104 and
 105 .Fl o
 106 .Pq or .
 107 The
 108 .Fl a
 109 operator has precedence over
 110 .Fl o
 111 and both are evaluated left-to-right.
 112 .Bl -tag -width Ds
 113 .It \&( Ar expr No \&)
 114 True if the subexpression
 115 .Ar expr
 116 is true.
 117 .It Ar expr1 Fl a Ar expr2
 118 True if both
 119 .Ar expr1
 120 and
 121 .Ar expr2
 122 are true (logical
 123 .Qq and ) .
 124 .It Ar expr1 Oo Fl o Oc Ar expr2
 125 True if
 126 .Ar expr1
 127 and/or
 128 .Ar expr2
 129 evaluate to true (logical
 130 .Qq or ) .
 131 .It Ar term
 132 True if
 133 .Ar term
 134 is satisfied.
 135 This has syntax
 136 .Li [key[,key]*(=~)]?val ,
 137 where operand
 138 .Cm key
 139 is an
 140 .Xr mdoc 7
 141 macro to query and
 142 .Cm val
 143 is its value.
 144 See
 145 .Sx Macro Keys
 146 for a list of available keys.
 147 Operator
 148 .Li \&=
 149 evaluates a substring, while
 150 .Li \&~
 151 evaluates a regular expression.
 152 .It Fl i Ar term
 153 If
 154 .Ar term
 155 is a regular expression, it
 156 is evaluated case-insensitively.
 157 Has no effect on substring terms.
 158 .El
 159 .Pp
 160 .Nm whatis
 161 considers an
 162 .Ar expression
 163 to consist of an opaque keyword.
 164 .Pp
 165 Results are sorted by manual title, with output formatted as
 166 .Pp
 167 .D1 title(sec) \- description
 168 .Pp
 169 Where
 170 .Qq title
 171 is the manual's title (note multiple manual names may exist for one
 172 title),
 173 .Qq sec
 174 is the manual section, and
 175 .Qq description
 176 is the manual's short description.
 177 If an architecture is specified for the manual, it is displayed as
 178 .Pp
 179 .D1 title(cat/arch) \- description
 180 .Pp
 181 Resulting manuals may be accessed as
 182 .Pp
 183 .Dl $ man \-s sec title
 184 .Pp
 185 If an architecture is specified in the output, use
 186 .Pp
 187 .Dl $ man \-s sec \-S arch title
 188 .Ss Macro Keys
 189 Queries evaluate over a subset of
 190 .Xr mdoc 7
 191 macros indexed by
 192 .Xr mandocdb 8 .
 193 In addition to the macro keys listed below, the special key
 194 .Cm any
 195 may be used to match any available macro key.
 196 .Pp
 197 Names and description:
 198 .Bl -column "xLix" description -offset indent -compact
 199 .It Li NAME Ta manual name in the NAME section, subset of \&Nm
 200 .It Li \&Nm Ta manual name
 201 .It Li \&Nd Ta one-line manual description
 202 .It Li arch Ta machine architecture (case-insensitive)
 203 .It Li sec  Ta manual section number
 204 .El
 205 .Pp
 206 Sections and cross references:
 207 .Bl -column "xLix" description -offset indent -compact
 208 .It Li \&Sh Ta section header (excluding standard sections)
 209 .It Li \&Ss Ta subsection header
 210 .It Li \&Xr Ta cross reference to another manual page
 211 .It Li \&Rs Ta bibliographic reference
 212 .El
 213 .Pp
 214 Semantic markup for command line utilities:
 215 .Bl -column "xLix" description -offset indent -compact
 216 .It Li \&Fl Ta command line options (flags)
 217 .It Li \&Cm Ta command modifier
 218 .It Li \&Ar Ta command argument
 219 .It Li \&Ic Ta internal or interactive command
 220 .It Li \&Ev Ta environmental variable
 221 .It Li \&Pa Ta file system path
 222 .El
 223 .Pp
 224 Semantic markup for function libraries:
 225 .Bl -column "xLix" description -offset indent -compact
 226 .It Li \&Lb Ta function library name
 227 .It Li \&In Ta include file
 228 .It Li \&Ft Ta function return type
 229 .It Li \&Fn Ta function name
 230 .It Li \&Fa Ta function argument type and name
 231 .It Li \&Vt Ta variable type
 232 .It Li \&Va Ta variable name
 233 .It Li \&Dv Ta defined variable or preprocessor constant
 234 .It Li \&Er Ta error constant
 235 .It Li \&Ev Ta environmental variable
 236 .El
 237 .Pp
 238 Various semantic markup:
 239 .Bl -column "xLix" description -offset indent -compact
 240 .It Li \&An Ta author name
 241 .It Li \&Lk Ta hyperlink
 242 .It Li \&Mt Ta Do mailto Dc hyperlink
 243 .It Li \&Cd Ta kernel configuration declaration
 244 .It Li \&Ms Ta mathematical symbol
 245 .It Li \&Tn Ta tradename
 246 .El
 247 .Pp
 248 Physical markup:
 249 .Bl -column "xLix" description -offset indent -compact
 250 .It Li \&Em Ta italic font or underline
 251 .It Li \&Sy Ta boldface font
 252 .It Li \&Li Ta typewriter font
 253 .El
 254 .Pp
 255 Text production:
 256 .Bl -column "xLix" description -offset indent -compact
 257 .It Li \&St Ta reference to a standards document
 258 .It Li \&At Ta At No version reference
 259 .It Li \&Bx Ta Bx No version reference
 260 .It Li \&Bsx Ta Bsx No version reference
 261 .It Li \&Nx Ta Nx No version reference
 262 .It Li \&Fx Ta Fx No version reference
 263 .It Li \&Ox Ta Ox No version reference
 264 .It Li \&Dx Ta Dx No version reference
 265 .El
 266 .Sh ENVIRONMENT
 267 .Bl -tag -width MANPATH
 268 .It Ev MANPATH
 269 The standard search path used by
 270 .Xr man 1
 271 may be changed by specifying a path in the
 272 .Ev MANPATH
 273 environment variable.
 274 Invalid paths, or paths without manual databases, are ignored.
 275 Overridden by
 276 .Fl M .
 277 If
 278 .Ev MANPATH
 279 begins with a colon, it is appended to the default list;
 280 if it ends with a colon, it is prepended to the default list;
 281 or if it contains two adjacent colons,
 282 the standard search path is inserted between the colons.
 283 If none of these conditions are met, it overrides the
 284 standard search path.
 285 .El
 286 .Sh FILES
 287 .Bl -tag -width "/etc/man.conf" -compact
 288 .It Pa mandoc.db
 289 name of the
 290 .Xr mandocdb 8
 291 keyword database
 292 .It Pa /etc/man.conf
 293 default
 294 .Xr man 1
 295 configuration file
 296 .El
 297 .Sh EXIT STATUS
 298 .Ex -std
 299 .Sh EXAMPLES
 300 Search for
 301 .Qq .cf
 302 as a substring of manual names and descriptions:
 303 .Pp
 304 .Dl $ apropos .cf
 305 .Pp
 306 Include matches for
 307 .Qq .cnf
 308 and
 309 .Qq .conf
 310 as well:
 311 .Pp
 312 .Dl $ apropos .cf .cnf .conf
 313 .Pp
 314 Search in names and descriptions using a regular expression:
 315 .Pp
 316 .Dl $ apropos '~set.?[ug]id'
 317 .Pp
 318 Search for manuals in the library category mentioning both the
 319 .Qq optind
 320 and the
 321 .Qq optarg
 322 variables:
 323 .Pp
 324 .Dl $ apropos \-s 3 Va=optind \-a Va=optarg
 325 .Pp
 326 Do exactly the same as calling
 327 .Xr whatis 1
 328 with the argument
 329 .Qq ssh :
 330 .Pp
 331 .Dl $ apropos \-\- \-i 'Nm~[[:<:]]ssh[[:>:]]'
 332 .Pp
 333 The following two invocations are equivalent:
 334 .Pp
 335 .D1 Li $ apropos -S Ar arch Li -s Ar section expression
 336 .Bd -ragged -offset indent
 337 .Li $ apropos \e( Ar expression Li \e)
 338 .Li -a arch~^( Ns Ar arch Ns Li |any)$
 339 .Li -a sec~^ Ns Ar section Ns Li $
 340 .Ed
 341 .Sh SEE ALSO
 342 .Xr man 1 ,
 343 .Xr re_format 7 ,
 344 .Xr mandocdb 8
 345 .Sh HISTORY
 346 An
 347 .Nm
 348 utility first appeared in
 349 .Bx 2 .
 350 It was rewritten from scratch for
 351 .Ox 5.6 .
 352 .Pp
 353 The
 354 .Fl M
 355 option and the
 356 .Ev MANPATH
 357 variable first appeared in
 358 .Bx 4.3 ;
 359 .Fl m
 360 in
 361 .Bx 4.3 Reno ;
 362 .Fl C
 363 in
 364 .Bx 4.4 Lite1 ;
 365 and
 366 .Fl S
 367 and
 368 .Fl s
 369 in
 370 .Ox 4.5 .
 371 .Sh AUTHORS
 372 .An -nosplit
 373 .An Bill Joy
 374 wrote the original
 375 .Bx
 376 .Nm
 377 in February 1979.
 378 The current version was written by
 379 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
 380 and
 381 .An Ingo Schwarze Aq Mt schwarze@openbsd.org .