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