1.\" Id: apropos.1,v 1.22 2013/10/01 20:56:18 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 October 1, 2013 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 33The 34.Nm apropos 35and 36.Nm whatis 37utilities query manual page databases generated by 38.Xr mandocdb 8 , 39evaluating on 40.Ar expression 41for each file in each database. 42.Pp 43By default, 44.Nm 45searches for 46.Xr mandocdb 8 47databases in the default paths stipulated by 48.Xr man 1 49and 50maps terms to case-sensitive manual names and descriptions. 51Multiple terms are OR'd. 52.Nm whatis 53maps terms only to case-sensitive manual names. 54.Pp 55Its arguments are as follows: 56.Bl -tag -width Ds 57.It Fl C Ar file 58Specify an alternative configuration 59.Ar file 60in 61.Xr man.conf 5 62format. 63.It Fl M Ar path 64Use the colon-separated path instead of the default list of paths 65searched for 66.Xr mandocdb 8 67databases. 68Invalid paths, or paths without manual databases, are ignored. 69.It Fl m Ar path 70Prepend the colon-separated paths to the list of paths searched 71for 72.Xr mandocdb 8 73databases. 74Invalid paths, or paths without manual databases, are ignored. 75.It Fl S Ar arch 76Search only for a particular architecture. 77.It Fl s Ar cat 78Search only for a manual section. 79See 80.Xr man 1 81for a listing of manual sections. 82.El 83.Pp 84.Nm whatis 85considers an 86.Ar expression 87to consist of an opaque keyword. 88.Nm apropos 89parses a 90.Ar expression 91into type and keyword pairs. 92This pair syntax 93.Li [key[,key]*(=~)]?val , 94where operand 95.Cm key 96is an 97.Xr mdoc 7 98macro to query and 99.Cm val 100is its value. 101See 102.Sx Macro Keys 103for a list of available keys. 104Operator 105.Li \&= 106evaluates a full string, while 107.Li \&~ 108evaluates a 109.Xr glob 7 110pattern. 111.Pp 112Results are sorted by manual title, with output formatted as 113.Qq title(sec) \- description 114where 115.Qq title 116is the manual's title (note multiple manual names may exist for one 117title), 118.Qq sec 119is the manual section, and 120.Qq description 121is the manual's short description. 122If an architecture is specified for the manual, it is displayed as 123.Qq title(cat/arch) \- description . 124.Ss Macro Keys 125.Nm apropos 126queries evaluate over a subset of 127.Xr mdoc 7 128macros indexed by 129.Xr mandocdb 8 . 130In addition to the macro keys listed below, the special key 131.Cm any 132may be used to match any available macro key. 133.Pp 134Names and description: 135.Bl -column "xLix" description -offset indent -compact 136.It Li \&Nm Ta manual name 137.It Li \&Nd Ta one-line manual description 138.El 139.Pp 140Sections and cross references: 141.Bl -column "xLix" description -offset indent -compact 142.It Li \&Sh Ta section header (excluding standard sections) 143.It Li \&Ss Ta subsection header 144.It Li \&Xr Ta cross reference to another manual page 145.It Li \&Rs Ta bibliographic reference 146.El 147.Pp 148Semantic markup for command line utilities: 149.Bl -column "xLix" description -offset indent -compact 150.It Li \&Fl Ta command line options (flags) 151.It Li \&Cm Ta command modifier 152.It Li \&Ar Ta command argument 153.It Li \&Ic Ta internal or interactive command 154.It Li \&Ev Ta environmental variable 155.It Li \&Pa Ta file system path 156.El 157.Pp 158Semantic markup for function libraries: 159.Bl -column "xLix" description -offset indent -compact 160.It Li \&Lb Ta function library name 161.It Li \&In Ta include file 162.It Li \&Ft Ta function return type 163.It Li \&Fn Ta function name 164.It Li \&Fa Ta function argument type and name 165.It Li \&Vt Ta variable type 166.It Li \&Va Ta variable name 167.It Li \&Dv Ta defined variable or preprocessor constant 168.It Li \&Er Ta error constant 169.It Li \&Ev Ta environmental variable 170.El 171.Pp 172Various semantic markup: 173.Bl -column "xLix" description -offset indent -compact 174.It Li \&An Ta author name 175.It Li \&Lk Ta hyperlink 176.It Li \&Mt Ta Do mailto Dc hyperlink 177.It Li \&Cd Ta kernel configuration declaration 178.It Li \&Ms Ta mathematical symbol 179.It Li \&Tn Ta tradename 180.El 181.Pp 182Physical markup: 183.Bl -column "xLix" description -offset indent -compact 184.It Li \&Em Ta italic font or underline 185.It Li \&Sy Ta boldface font 186.It Li \&Li Ta typewriter font 187.El 188.Pp 189Text production: 190.Bl -column "xLix" description -offset indent -compact 191.It Li \&St Ta reference to a standards document 192.It Li \&At Ta At No version reference 193.It Li \&Bx Ta Bx No version reference 194.It Li \&Bsx Ta Bsx No version reference 195.It Li \&Nx Ta Nx No version reference 196.It Li \&Fx Ta Fx No version reference 197.It Li \&Ox Ta Ox No version reference 198.It Li \&Dx Ta Dx No version reference 199.El 200.Sh ENVIRONMENT 201.Bl -tag -width Ds 202.It Ev MANPATH 203Colon-separated paths modifying the default list of paths searched for 204manual databases. 205Invalid paths, or paths without manual databases, are ignored. 206Overridden by 207.Fl M . 208If 209.Ev MANPATH 210begins with a 211.Sq \&: , 212it is appended to the default list; 213else if it ends with 214.Sq \&: , 215it is prepended to the default list; else if it contains 216.Sq \&:: , 217the default list is inserted between the colons. 218If none of these conditions are met, it overrides the default list. 219.El 220.Sh FILES 221.Bl -tag -width "/etc/man.conf" -compact 222.It Pa mandoc.db 223name of the 224.Xr mandocdb 8 225keyword database 226.It Pa /etc/man.conf 227default 228.Xr man 1 229configuration file 230.El 231.Sh EXIT STATUS 232.Ex -std 233.Sh EXAMPLES 234Search for 235.Qq mdoc 236as a word or 237.Xr glob 7 238expression: 239.Pp 240.Dl $ apropos mdoc 241.Dl $ apropos any~mdoc* 242.Pp 243Include matches for 244.Qq roff 245and 246.Qq man 247using 248.Xr glob 7 249expressions: 250.Pp 251.Dl $ apropos ~*mdoc* ~*roff* 252.Pp 253Search for 254.Qq optarg 255as a variable name in the library category: 256.Pp 257.Dl $ apropos \-s 3 Va=optarg 258.Sh SEE ALSO 259.Xr glob 7 , 260.Xr mandocdb 8 261.Sh AUTHORS 262The 263.Nm 264utility was written by 265.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . 266