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 35The 36.Nm apropos 37and 38.Nm whatis 39utilities query manual page databases generated by 40.Xr makewhatis 8 , 41evaluating 42.Ar expression 43for each file in each database. 44By default, it displays the names, section numbers, and description lines 45of all matching manuals. 46.Pp 47By default, 48.Nm 49searches for 50.Xr makewhatis 8 51databases in the default paths stipulated by 52.Xr man 1 53and uses case-insensitive substring matching 54.Pq the Cm = No operator 55over manual names and descriptions 56.Pq the Li \&Nm No and Li \&Nd No macro keys . 57Multiple terms imply pairwise 58.Fl o . 59.Nm whatis 60maps terms only to case-sensitive manual names. 61.Pp 62Its arguments are as follows: 63.Bl -tag -width Ds 64.It Fl C Ar file 65Specify an alternative configuration 66.Ar file 67in 68.Xr man.conf 5 69format. 70.It Fl M Ar path 71Use the colon-separated path instead of the default list of paths 72searched for 73.Xr makewhatis 8 74databases. 75Invalid paths, or paths without manual databases, are ignored. 76.It Fl m Ar path 77Prepend the colon-separated paths to the list of paths searched 78for 79.Xr makewhatis 8 80databases. 81Invalid paths, or paths without manual databases, are ignored. 82.It Fl O Ar outkey 83Show the values associated with the key 84.Ar outkey 85instead of the manual descriptions. 86.It Fl S Ar arch 87Restrict the search to pages for the specified 88.Xr machine 1 89architecture. 90.Ar arch 91is case insensitive. 92By default, pages for all architectures are shown. 93.It Fl s Ar section 94Restrict the search to the specified section of the manual. 95By default, pages from all sections are shown. 96See 97.Xr man 1 98for a listing of sections. 99.El 100.Pp 101An 102.Ar expression 103consists of search terms joined by logical operators 104.Fl a 105.Pq and 106and 107.Fl o 108.Pq or . 109The 110.Fl a 111operator has precedence over 112.Fl o 113and both are evaluated left-to-right. 114.Bl -tag -width Ds 115.It \&( Ar expr No \&) 116True if the subexpression 117.Ar expr 118is true. 119.It Ar expr1 Fl a Ar expr2 120True if both 121.Ar expr1 122and 123.Ar expr2 124are true (logical 125.Sq and ) . 126.It Ar expr1 Oo Fl o Oc Ar expr2 127True if 128.Ar expr1 129and/or 130.Ar expr2 131evaluate to true (logical 132.Sq or ) . 133.It Ar term 134True if 135.Ar term 136is satisfied. 137This 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 145where 146.Ar key 147is an 148.Xr mdoc 7 149macro to query and 150.Ar val 151is its value. 152See 153.Sx Macro Keys 154for a list of available keys. 155Operator 156.Cm = 157evaluates a substring, while 158.Cm ~ 159evaluates a regular expression. 160.It Fl i Ar term 161If 162.Ar term 163is a regular expression, it 164is evaluated case-insensitively. 165Has no effect on substring terms. 166.El 167.Pp 168.Nm whatis 169considers an 170.Ar expression 171to consist of an opaque keyword. 172.Pp 173Results are sorted by manual sections and names, with output formatted as 174.Pp 175.D1 name[, name...](sec) \- description 176.Pp 177Where 178.Dq name 179is the manual's name, 180.Dq sec 181is the manual section, and 182.Dq description 183is the manual's short description. 184If an architecture is specified for the manual, it is displayed as 185.Pp 186.D1 name(sec/arch) \- description 187.Pp 188Resulting manuals may be accessed as 189.Pp 190.Dl $ man \-s sec name 191.Pp 192If an architecture is specified in the output, use 193.Pp 194.Dl $ man \-s sec \-S arch name 195.Ss Macro Keys 196Queries evaluate over a subset of 197.Xr mdoc 7 198macros indexed by 199.Xr makewhatis 8 . 200In addition to the macro keys listed below, the special key 201.Cm any 202may be used to match any available macro key. 203.Pp 204Names 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 212Sections 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 220Semantic 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 230Semantic 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 244Various 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 254Physical 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 261Text 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 275The standard search path used by 276.Xr man 1 277may be changed by specifying a path in the 278.Ev MANPATH 279environment variable. 280Invalid paths, or paths without manual databases, are ignored. 281Overridden by 282.Fl M . 283If 284.Ev MANPATH 285begins with a colon, it is appended to the default list; 286if it ends with a colon, it is prepended to the default list; 287or if it contains two adjacent colons, 288the standard search path is inserted between the colons. 289If none of these conditions are met, it overrides the 290standard search path. 291.El 292.Sh FILES 293.Bl -tag -width "/etc/man.conf" -compact 294.It Pa mandoc.db 295name of the 296.Xr makewhatis 8 297keyword database 298.It Pa /etc/man.conf 299default 300.Xr man 1 301configuration file 302.El 303.Sh EXIT STATUS 304.Ex -std 305.Sh EXAMPLES 306Search for 307.Qq .cf 308as a substring of manual names and descriptions: 309.Pp 310.Dl $ apropos .cf 311.Pp 312Include matches for 313.Qq .cnf 314and 315.Qq .conf 316as well: 317.Pp 318.Dl $ apropos .cf .cnf .conf 319.Pp 320Search in names and descriptions using a regular expression: 321.Pp 322.Dl $ apropos '~set.?[ug]id' 323.Pp 324Search for manuals in the library section mentioning both the 325.Qq optind 326and the 327.Qq optarg 328variables: 329.Pp 330.Dl $ apropos \-s 3 Va=optind \-a Va=optarg 331.Pp 332Do exactly the same as calling 333.Xr whatis 1 334with the argument 335.Qq ssh : 336.Pp 337.Dl $ apropos \-\- \-i 'Nm~[[:<:]]ssh[[:>:]]' 338.Pp 339The 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 352An 353.Nm 354utility first appeared in 355.Bx 2 . 356It was rewritten from scratch for 357.Ox 5.6 . 358.Pp 359The 360.Fl M 361option and the 362.Ev MANPATH 363variable first appeared in 364.Bx 4.3 ; 365.Fl m 366in 367.Bx 4.3 Reno ; 368.Fl C 369in 370.Bx 4.4 Lite1 ; 371and 372.Fl S 373and 374.Fl s 375in 376.Ox 4.5 . 377.Sh AUTHORS 378.An -nosplit 379.An Bill Joy 380wrote the original 381.Bx 382.Nm 383in February 1979. 384The current version was written by 385.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv 386and 387.An Ingo Schwarze Aq Mt schwarze@openbsd.org . 388