1.\" $Id: apropos.1,v 1.51 2020/10/01 22:50:00 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: October 1 2020 $ 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 less 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 less 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 less 1 367is used. 368Only used if 369.Fl a 370or 371.Fl l 372is specified. 373.El 374.Sh FILES 375.Bl -tag -width "/etc/man.conf" -compact 376.It Pa mandoc.db 377name of the 378.Xr makewhatis 8 379keyword database 380.It Pa /etc/man.conf 381default 382.Xr man 1 383configuration file 384.El 385.Sh EXIT STATUS 386.Ex -std 387.Sh EXAMPLES 388Search for 389.Qq .cf 390as a substring of manual names and descriptions: 391.Pp 392.Dl $ apropos =.cf 393.Pp 394Include matches for 395.Qq .cnf 396and 397.Qq .conf 398as well: 399.Pp 400.Dl $ apropos =.cf =.cnf =.conf 401.Pp 402Search in names and descriptions using a case-sensitive regular expression: 403.Pp 404.Dl $ apropos \(aq\(tiset.?[ug]id\(aq 405.Pp 406Search for all manual pages in a given section: 407.Pp 408.Dl $ apropos \-s 9 \&. 409.Pp 410Search for manuals in the library section mentioning both the 411.Qq optind 412and the 413.Qq optarg 414variables: 415.Pp 416.Dl $ apropos \-s 3 Va=optind \-a Va=optarg 417.Pp 418Do exactly the same as calling 419.Nm whatis 420with the argument 421.Qq ssh : 422.Pp 423.Dl $ apropos \-\- \-i \(aqNm\(ti[[:<:]]ssh[[:>:]]\(aq 424.Pp 425The following two invocations are equivalent: 426.Pp 427.D1 Li $ apropos -S Ar arch Li -s Ar section expression 428.Bd -ragged -offset indent 429.Li $ apropos \e( Ar expression Li \e) 430.Li -a arch\(ti^( Ns Ar arch Ns Li |any)$ 431.Li -a sec\(ti^ Ns Ar section Ns Li $ 432.Ed 433.Sh SEE ALSO 434.Xr man 1 , 435.Xr re_format 7 , 436.Xr makewhatis 8 437.Sh STANDARDS 438The 439.Nm 440utility is compliant with the 441.St -p1003.1-2008 442specification of 443.Xr man 1 444.Fl k . 445.Pp 446All options, the 447.Nm whatis 448command, support for logical operators, macro keys, 449substring matching, sorting of results, the environment variables 450.Ev MANPAGER 451and 452.Ev MANPATH , 453the database format, and the configuration file 454are extensions to that specification. 455.Sh HISTORY 456Part of the functionality of 457.Nm whatis 458was already provided by the former 459.Nm manwhere 460utility in 461.Bx 1 . 462The 463.Nm 464and 465.Nm whatis 466utilities first appeared in 467.Bx 2 . 468They were rewritten from scratch for 469.Ox 5.6 . 470.Pp 471The 472.Fl M 473option and the 474.Ev MANPATH 475variable first appeared in 476.Bx 4.3 ; 477.Fl m 478in 479.Bx 4.3 Reno ; 480.Fl C 481in 482.Bx 4.4 Lite1 ; 483and 484.Fl S 485and 486.Fl s 487in 488.Ox 4.5 489for 490.Nm 491and in 492.Ox 5.6 493for 494.Nm whatis . 495The options 496.Fl acfhIKklOTWw 497appeared in 498.Ox 5.7 . 499.Sh AUTHORS 500.An -nosplit 501.An Bill Joy 502wrote 503.Nm manwhere 504in 1977 and the original 505.Bx 506.Nm 507and 508.Nm whatis 509in February 1979. 510The current version was written by 511.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv 512and 513.An Ingo Schwarze Aq Mt schwarze@openbsd.org . 514