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