contrib/mdocml/apropos.1

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