1.\" $OpenBSD: apropos.1,v 1.31 2015/04/03 08:45: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 3 2015 $ 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 acfhklw 28.Op Fl C Ar file 29.Op Fl M Ar path 30.Op Fl m Ar path 31.Op Fl O Ar outkey 32.Op Fl S Ar arch 33.Op Fl s Ar section 34.Ar expression ... 35.Sh DESCRIPTION 36The 37.Nm apropos 38and 39.Nm whatis 40utilities query manual page databases generated by 41.Xr makewhatis 8 , 42evaluating 43.Ar expression 44for each file in each database. 45By default, they display the names, section numbers, and description lines 46of all matching manuals. 47.Pp 48By default, 49.Nm 50searches for 51.Xr makewhatis 8 52databases in the default paths stipulated by 53.Xr man 1 54and uses case-insensitive substring matching 55.Pq the Cm = No operator 56over manual names and descriptions 57.Pq the Li \&Nm No and Li \&Nd No macro keys . 58Multiple terms imply pairwise 59.Fl o . 60.Pp 61.Nm whatis 62is a synonym for 63.Nm 64.Fl f . 65.Pp 66The options are as follows: 67.Bl -tag -width Ds 68.It Fl a 69Instead of showing only the title lines, show the complete manual pages, 70just like 71.Xr man 1 72.Fl a 73would. 74If the standard output is a terminal device and 75.Fl c 76is not specified, use 77.Xr more 1 78to paginate them. 79In 80.Fl a 81mode, the options 82.Fl IKOTW 83described in the 84.Xr mandoc 1 85manual are also available. 86.It Fl C Ar file 87Specify an alternative configuration 88.Ar file 89in 90.Xr man.conf 5 91format. 92.It Fl c 93In 94.Fl a 95mode, copy the formatted manual pages to the standard output without using 96.Xr more 1 97to paginate them. 98.It Fl f 99Search for all words in 100.Ar expression 101in manual page names only. 102The search is case insensitive and matches whole words only. 103In this mode, macro keys, comparison operators, and logical operators 104are not available. 105This overrides any earlier 106.Fl k 107and 108.Fl l 109options. 110.It Fl h 111Instead of showing the title lines, show the SYNOPSIS sections, just like 112.Xr man 1 113.Fl h 114would. 115.It Fl k 116Support the full 117.Ar expression 118syntax. 119This overrides any earlier 120.Fl f 121and 122.Fl l 123options. 124It is the default for 125.Nm . 126.It Fl l 127An alias for 128.Xr mandoc 1 129.Fl a . 130This overrides any earlier 131.Fl f , 132.Fl k , 133and 134.Fl w 135options. 136.It Fl M Ar path 137Use the colon-separated path instead of the default list of paths 138searched for 139.Xr makewhatis 8 140databases. 141Invalid paths, or paths without manual databases, are ignored. 142.It Fl m Ar path 143Prepend the colon-separated paths to the list of paths searched 144for 145.Xr makewhatis 8 146databases. 147Invalid paths, or paths without manual databases, are ignored. 148.It Fl O Ar outkey 149Show the values associated with the key 150.Ar outkey 151instead of the manual descriptions. 152.It Fl S Ar arch 153Restrict the search to pages for the specified 154.Xr machine 1 155architecture. 156.Ar arch 157is case insensitive. 158By default, pages for all architectures are shown. 159.It Fl s Ar section 160Restrict the search to the specified section of the manual. 161By default, pages from all sections are shown. 162See 163.Xr man 1 164for a listing of sections. 165.It Fl w 166Instead of showing title lines, show the pathnames of the matching 167manual pages, just like 168.Xr man 1 169.Fl w 170would. 171.El 172.Pp 173An 174.Ar expression 175consists of search terms joined by logical operators 176.Fl a 177.Pq and 178and 179.Fl o 180.Pq or . 181The 182.Fl a 183operator has precedence over 184.Fl o 185and both are evaluated left-to-right. 186.Bl -tag -width Ds 187.It \&( Ar expr No \&) 188True if the subexpression 189.Ar expr 190is true. 191.It Ar expr1 Fl a Ar expr2 192True if both 193.Ar expr1 194and 195.Ar expr2 196are true (logical 197.Sq and ) . 198.It Ar expr1 Oo Fl o Oc Ar expr2 199True if 200.Ar expr1 201and/or 202.Ar expr2 203evaluate to true (logical 204.Sq or ) . 205.It Ar term 206True if 207.Ar term 208is satisfied. 209This has syntax 210.Sm off 211.Oo 212.Op Ar key Op , Ar key ... 213.Pq Cm = | \(ti 214.Oc 215.Ar val , 216.Sm on 217where 218.Ar key 219is an 220.Xr mdoc 7 221macro to query and 222.Ar val 223is its value. 224See 225.Sx Macro Keys 226for a list of available keys. 227Operator 228.Cm = 229evaluates a substring, while 230.Cm \(ti 231evaluates a regular expression. 232.It Fl i Ar term 233If 234.Ar term 235is a regular expression, it 236is evaluated case-insensitively. 237Has no effect on substring terms. 238.El 239.Pp 240Results are sorted by manual sections and names, with output formatted as 241.Pp 242.D1 name[, name...](sec) \- description 243.Pp 244Where 245.Dq name 246is the manual's name, 247.Dq sec 248is the manual section, and 249.Dq description 250is the manual's short description. 251If an architecture is specified for the manual, it is displayed as 252.Pp 253.D1 name(sec/arch) \- description 254.Pp 255Resulting manuals may be accessed as 256.Pp 257.Dl $ man \-s sec name 258.Pp 259If an architecture is specified in the output, use 260.Pp 261.Dl $ man \-s sec \-S arch name 262.Ss Macro Keys 263Queries evaluate over a subset of 264.Xr mdoc 7 265macros indexed by 266.Xr makewhatis 8 . 267In addition to the macro keys listed below, the special key 268.Cm any 269may be used to match any available macro key. 270.Pp 271Names and description: 272.Bl -column "xLix" description -offset indent -compact 273.It Li \&Nm Ta manual name 274.It Li \&Nd Ta one-line manual description 275.It Li arch Ta machine architecture (case-insensitive) 276.It Li sec Ta manual section number 277.El 278.Pp 279Sections and cross references: 280.Bl -column "xLix" description -offset indent -compact 281.It Li \&Sh Ta section header (excluding standard sections) 282.It Li \&Ss Ta subsection header 283.It Li \&Xr Ta cross reference to another manual page 284.It Li \&Rs Ta bibliographic reference 285.El 286.Pp 287Semantic markup for command line utilities: 288.Bl -column "xLix" description -offset indent -compact 289.It Li \&Fl Ta command line options (flags) 290.It Li \&Cm Ta command modifier 291.It Li \&Ar Ta command argument 292.It Li \&Ic Ta internal or interactive command 293.It Li \&Ev Ta environmental variable 294.It Li \&Pa Ta file system path 295.El 296.Pp 297Semantic markup for function libraries: 298.Bl -column "xLix" description -offset indent -compact 299.It Li \&Lb Ta function library name 300.It Li \&In Ta include file 301.It Li \&Ft Ta function return type 302.It Li \&Fn Ta function name 303.It Li \&Fa Ta function argument type and name 304.It Li \&Vt Ta variable type 305.It Li \&Va Ta variable name 306.It Li \&Dv Ta defined variable or preprocessor constant 307.It Li \&Er Ta error constant 308.It Li \&Ev Ta environmental variable 309.El 310.Pp 311Various semantic markup: 312.Bl -column "xLix" description -offset indent -compact 313.It Li \&An Ta author name 314.It Li \&Lk Ta hyperlink 315.It Li \&Mt Ta Do mailto Dc hyperlink 316.It Li \&Cd Ta kernel configuration declaration 317.It Li \&Ms Ta mathematical symbol 318.It Li \&Tn Ta tradename 319.El 320.Pp 321Physical markup: 322.Bl -column "xLix" description -offset indent -compact 323.It Li \&Em Ta italic font or underline 324.It Li \&Sy Ta boldface font 325.It Li \&Li Ta typewriter font 326.El 327.Pp 328Text production: 329.Bl -column "xLix" description -offset indent -compact 330.It Li \&St Ta reference to a standards document 331.It Li \&At Ta At No version reference 332.It Li \&Bx Ta Bx No version reference 333.It Li \&Bsx Ta Bsx No version reference 334.It Li \&Nx Ta Nx No version reference 335.It Li \&Fx Ta Fx No version reference 336.It Li \&Ox Ta Ox No version reference 337.It Li \&Dx Ta Dx No version reference 338.El 339.Sh ENVIRONMENT 340.Bl -tag -width MANPAGER 341.It Ev MANPAGER 342Any non-empty value of the environment variable 343.Ev MANPAGER 344will be used instead of the standard pagination program, 345.Xr more 1 . 346.It Ev MANPATH 347The standard search path used by 348.Xr man 1 349may be changed by specifying a path in the 350.Ev MANPATH 351environment variable. 352Invalid paths, or paths without manual databases, are ignored. 353Overridden by 354.Fl M . 355If 356.Ev MANPATH 357begins with a colon, it is appended to the default list; 358if it ends with a colon, it is prepended to the default list; 359or if it contains two adjacent colons, 360the standard search path is inserted between the colons. 361If none of these conditions are met, it overrides the 362standard search path. 363.It Ev PAGER 364Specifies the pagination program to use when 365.Ev MANPAGER 366is not defined. 367If neither PAGER nor MANPAGER is defined, 368.Xr more 1 369.Fl s 370will be used. 371.El 372.Sh FILES 373.Bl -tag -width "/etc/man.conf" -compact 374.It Pa mandoc.db 375name of the 376.Xr makewhatis 8 377keyword database 378.It Pa /etc/man.conf 379default 380.Xr man 1 381configuration file 382.El 383.Sh EXIT STATUS 384.Ex -std 385.Sh EXAMPLES 386Search for 387.Qq .cf 388as a substring of manual names and descriptions: 389.Pp 390.Dl $ apropos .cf 391.Pp 392Include matches for 393.Qq .cnf 394and 395.Qq .conf 396as well: 397.Pp 398.Dl $ apropos .cf .cnf .conf 399.Pp 400Search in names and descriptions using a regular expression: 401.Pp 402.Dl $ apropos \(aq\(tiset.?[ug]id\(aq 403.Pp 404Search for manuals in the library section mentioning both the 405.Qq optind 406and the 407.Qq optarg 408variables: 409.Pp 410.Dl $ apropos \-s 3 Va=optind \-a Va=optarg 411.Pp 412Do exactly the same as calling 413.Xr whatis 1 414with the argument 415.Qq ssh : 416.Pp 417.Dl $ apropos \-\- \-i \(aqNm\(ti[[:<:]]ssh[[:>:]]\(aq 418.Pp 419The following two invocations are equivalent: 420.Pp 421.D1 Li $ apropos -S Ar arch Li -s Ar section expression 422.Bd -ragged -offset indent 423.Li $ apropos \e( Ar expression Li \e) 424.Li -a arch\(ti^( Ns Ar arch Ns Li |any)$ 425.Li -a sec\(ti^ Ns Ar section Ns Li $ 426.Ed 427.Sh SEE ALSO 428.Xr man 1 , 429.Xr re_format 7 , 430.Xr makewhatis 8 431.Sh HISTORY 432Part of the functionality of 433.Nm whatis 434was already provided by the former 435.Nm manwhere 436utility in 437.Bx 1 . 438The 439.Nm 440and 441.Nm whatis 442utilities first appeared in 443.Bx 2 . 444They were rewritten from scratch for 445.Ox 5.6 . 446.Pp 447The 448.Fl M 449option and the 450.Ev MANPATH 451variable first appeared in 452.Bx 4.3 ; 453.Fl m 454in 455.Bx 4.3 Reno ; 456.Fl C 457in 458.Bx 4.4 Lite1 ; 459and 460.Fl S 461and 462.Fl s 463in 464.Ox 4.5 465for 466.Nm 467and in 468.Ox 5.6 469for 470.Nm whatis . 471.Sh AUTHORS 472.An -nosplit 473.An Bill Joy 474wrote 475.Nm manwhere 476in 1977 and the original 477.Bx 478.Nm 479and 480.Nm whatis 481in February 1979. 482The current version was written by 483.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv 484and 485.An Ingo Schwarze Aq Mt schwarze@openbsd.org . 486