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