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