apropos.1

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