apropos.1

   1 .\"     $Id: apropos.1,v 1.26 2014/04/15 23:02:27 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 15 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 \&Nm Ta manual name
 200 .It Li \&Nd Ta one-line manual description
 201 .It Li arch Ta machine architecture (case-insensitive)
 202 .It Li sec  Ta manual section number
 203 .El
 204 .Pp
 205 Sections and cross references:
 206 .Bl -column "xLix" description -offset indent -compact
 207 .It Li \&Sh Ta section header (excluding standard sections)
 208 .It Li \&Ss Ta subsection header
 209 .It Li \&Xr Ta cross reference to another manual page
 210 .It Li \&Rs Ta bibliographic reference
 211 .El
 212 .Pp
 213 Semantic markup for command line utilities:
 214 .Bl -column "xLix" description -offset indent -compact
 215 .It Li \&Fl Ta command line options (flags)
 216 .It Li \&Cm Ta command modifier
 217 .It Li \&Ar Ta command argument
 218 .It Li \&Ic Ta internal or interactive command
 219 .It Li \&Ev Ta environmental variable
 220 .It Li \&Pa Ta file system path
 221 .El
 222 .Pp
 223 Semantic markup for function libraries:
 224 .Bl -column "xLix" description -offset indent -compact
 225 .It Li \&Lb Ta function library name
 226 .It Li \&In Ta include file
 227 .It Li \&Ft Ta function return type
 228 .It Li \&Fn Ta function name
 229 .It Li \&Fa Ta function argument type and name
 230 .It Li \&Vt Ta variable type
 231 .It Li \&Va Ta variable name
 232 .It Li \&Dv Ta defined variable or preprocessor constant
 233 .It Li \&Er Ta error constant
 234 .It Li \&Ev Ta environmental variable
 235 .El
 236 .Pp
 237 Various semantic markup:
 238 .Bl -column "xLix" description -offset indent -compact
 239 .It Li \&An Ta author name
 240 .It Li \&Lk Ta hyperlink
 241 .It Li \&Mt Ta Do mailto Dc hyperlink
 242 .It Li \&Cd Ta kernel configuration declaration
 243 .It Li \&Ms Ta mathematical symbol
 244 .It Li \&Tn Ta tradename
 245 .El
 246 .Pp
 247 Physical markup:
 248 .Bl -column "xLix" description -offset indent -compact
 249 .It Li \&Em Ta italic font or underline
 250 .It Li \&Sy Ta boldface font
 251 .It Li \&Li Ta typewriter font
 252 .El
 253 .Pp
 254 Text production:
 255 .Bl -column "xLix" description -offset indent -compact
 256 .It Li \&St Ta reference to a standards document
 257 .It Li \&At Ta At No version reference
 258 .It Li \&Bx Ta Bx No version reference
 259 .It Li \&Bsx Ta Bsx No version reference
 260 .It Li \&Nx Ta Nx No version reference
 261 .It Li \&Fx Ta Fx No version reference
 262 .It Li \&Ox Ta Ox No version reference
 263 .It Li \&Dx Ta Dx No version reference
 264 .El
 265 .Sh ENVIRONMENT
 266 .Bl -tag -width MANPATH
 267 .It Ev MANPATH
 268 The standard search path used by
 269 .Xr man 1
 270 may be changed by specifying a path in the
 271 .Ev MANPATH
 272 environment variable.
 273 Invalid paths, or paths without manual databases, are ignored.
 274 Overridden by
 275 .Fl M .
 276 If
 277 .Ev MANPATH
 278 begins with a colon, it is appended to the default list;
 279 if it ends with a colon, it is prepended to the default list;
 280 or if it contains two adjacent colons,
 281 the standard search path is inserted between the colons.
 282 If none of these conditions are met, it overrides the
 283 standard search path.
 284 .El
 285 .Sh FILES
 286 .Bl -tag -width "/etc/man.conf" -compact
 287 .It Pa mandoc.db
 288 name of the
 289 .Xr mandocdb 8
 290 keyword database
 291 .It Pa /etc/man.conf
 292 default
 293 .Xr man 1
 294 configuration file
 295 .El
 296 .Sh EXIT STATUS
 297 .Ex -std
 298 .Sh EXAMPLES
 299 Search for
 300 .Qq .cf
 301 as a substring of manual names and descriptions:
 302 .Pp
 303 .Dl $ apropos .cf
 304 .Pp
 305 Include matches for
 306 .Qq .cnf
 307 and
 308 .Qq .conf
 309 as well:
 310 .Pp
 311 .Dl $ apropos .cf .cnf .conf
 312 .Pp
 313 Search in names and descriptions using a regular expression:
 314 .Pp
 315 .Dl $ apropos '~set.?[ug]id'
 316 .Pp
 317 Search for manuals in the library category mentioning both the
 318 .Qq optind
 319 and the
 320 .Qq optarg
 321 variables:
 322 .Pp
 323 .Dl $ apropos \-s 3 Va=optind \-a Va=optarg
 324 .Pp
 325 Do exactly the same as calling
 326 .Xr whatis 1
 327 with the argument
 328 .Qq ssh :
 329 .Pp
 330 .Dl $ apropos \-\- \-i 'Nm~[[:<:]]ssh[[:>:]]'
 331 .Pp
 332 The following two invocations are equivalent:
 333 .Pp
 334 .D1 Li $ apropos -S Ar arch Li -s Ar section expression
 335 .Bd -ragged -offset indent
 336 .Li $ apropos \e( Ar expression Li \e)
 337 .Li -a arch~^( Ns Ar arch Ns Li |any)$
 338 .Li -a sec~^ Ns Ar section Ns Li $
 339 .Ed
 340 .Sh SEE ALSO
 341 .Xr man 1 ,
 342 .Xr re_format 7 ,
 343 .Xr mandocdb 8
 344 .Sh HISTORY
 345 An
 346 .Nm
 347 utility first appeared in
 348 .Bx 2 .
 349 It was rewritten from scratch for
 350 .Ox 5.6 .
 351 .Pp
 352 The
 353 .Fl M
 354 option and the
 355 .Ev MANPATH
 356 variable first appeared in
 357 .Bx 4.3 ;
 358 .Fl m
 359 in
 360 .Bx 4.3 Reno ;
 361 .Fl C
 362 in
 363 .Bx 4.4 Lite1 ;
 364 and
 365 .Fl S
 366 and
 367 .Fl s
 368 in
 369 .Ox 4.5 .
 370 .Sh AUTHORS
 371 .An -nosplit
 372 .An Bill Joy
 373 wrote the original
 374 .Bx
 375 .Nm
 376 in February 1979.
 377 The current version was written by
 378 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
 379 and
 380 .An Ingo Schwarze Aq Mt schwarze@openbsd.org .