apropos.1 (10983B)
- .\" $Id: apropos.1,v 1.51 2020/10/01 22:50:00 schwarze Exp $
- .\"
- .\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
- .\" Copyright (c) 2011,2012,2014,2017,2018 Ingo Schwarze <schwarze@openbsd.org>
- .\"
- .\" Permission to use, copy, modify, and distribute this software for any
- .\" purpose with or without fee is hereby granted, provided that the above
- .\" copyright notice and this permission notice appear in all copies.
- .\"
- .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
- .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
- .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
- .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
- .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
- .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
- .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
- .\"
- .Dd $Mdocdate: October 1 2020 $
- .Dt APROPOS 1
- .Os
- .Sh NAME
- .Nm apropos ,
- .Nm whatis
- .Nd search manual page databases
- .Sh SYNOPSIS
- .Nm
- .Op Fl afk
- .Op Fl C Ar file
- .Op Fl M Ar path
- .Op Fl m Ar path
- .Op Fl O Ar outkey
- .Op Fl S Ar arch
- .Op Fl s Ar section
- .Ar expression ...
- .Sh DESCRIPTION
- The
- .Nm apropos
- and
- .Nm whatis
- utilities query manual page databases generated by
- .Xr makewhatis 8 ,
- evaluating
- .Ar expression
- for each file in each database.
- By default, they display the names, section numbers, and description lines
- of all matching manuals.
- .Pp
- By default,
- .Nm
- searches for
- .Xr makewhatis 8
- databases in the default paths stipulated by
- .Xr man 1
- and uses case-insensitive extended regular expression matching
- over manual names and descriptions
- .Pq the Li \&Nm No and Li \&Nd No macro keys .
- Multiple terms imply pairwise
- .Fl o .
- .Pp
- .Nm whatis
- is a synonym for
- .Nm
- .Fl f .
- .Pp
- The options are as follows:
- .Bl -tag -width Ds
- .It Fl a
- Instead of showing only the title lines, show the complete manual pages,
- just like
- .Xr man 1
- .Fl a
- would.
- If the standard output is a terminal device and
- .Fl c
- is not specified, use
- .Xr less 1
- to paginate them.
- In
- .Fl a
- mode, the options
- .Fl IKOTW
- described in the
- .Xr mandoc 1
- manual are also available.
- .It Fl C Ar file
- Specify an alternative configuration
- .Ar file
- in
- .Xr man.conf 5
- format.
- .It Fl f
- Search for all words in
- .Ar expression
- in manual page names only.
- The search is case-insensitive and matches whole words only.
- In this mode, macro keys, comparison operators, and logical operators
- are not available.
- .It Fl k
- Support the full
- .Ar expression
- syntax.
- It is the default for
- .Nm .
- .It Fl M Ar path
- Use the colon-separated path instead of the default list of paths
- searched for
- .Xr makewhatis 8
- databases.
- Invalid paths, or paths without manual databases, are ignored.
- .It Fl m Ar path
- Prepend the colon-separated paths to the list of paths searched
- for
- .Xr makewhatis 8
- databases.
- Invalid paths, or paths without manual databases, are ignored.
- .It Fl O Ar outkey
- Show the values associated with the key
- .Ar outkey
- instead of the manual descriptions.
- .It Fl S Ar arch
- Restrict the search to pages for the specified
- .Xr machine 1
- architecture.
- .Ar arch
- is case-insensitive.
- By default, pages for all architectures are shown.
- .It Fl s Ar section
- Restrict the search to the specified section of the manual.
- By default, pages from all sections are shown.
- See
- .Xr man 1
- for a listing of sections.
- .El
- .Pp
- The options
- .Fl chlw
- are also supported and are documented in
- .Xr man 1 .
- The options
- .Fl fkl
- are mutually exclusive and override each other.
- .Pp
- An
- .Ar expression
- consists of search terms joined by logical operators
- .Fl a
- .Pq and
- and
- .Fl o
- .Pq or .
- The
- .Fl a
- operator has precedence over
- .Fl o
- and both are evaluated left-to-right.
- .Bl -tag -width Ds
- .It \&( Ar expr No \&)
- True if the subexpression
- .Ar expr
- is true.
- .It Ar expr1 Fl a Ar expr2
- True if both
- .Ar expr1
- and
- .Ar expr2
- are true (logical
- .Sq and ) .
- .It Ar expr1 Oo Fl o Oc Ar expr2
- True if
- .Ar expr1
- and/or
- .Ar expr2
- evaluate to true (logical
- .Sq or ) .
- .It Ar term
- True if
- .Ar term
- is satisfied.
- This has syntax
- .Sm off
- .Oo
- .Op Ar key Op , Ar key ...
- .Pq Cm = | \(ti
- .Oc
- .Ar val ,
- .Sm on
- where
- .Ar key
- is an
- .Xr mdoc 7
- macro to query and
- .Ar val
- is its value.
- See
- .Sx Macro Keys
- for a list of available keys.
- Operator
- .Cm =
- evaluates a substring, while
- .Cm \(ti
- evaluates a case-sensitive extended regular expression.
- .It Fl i Ar term
- If
- .Ar term
- is a regular expression, it
- is evaluated case-insensitively.
- Has no effect on substring terms.
- .El
- .Pp
- Results are sorted first according to the section number in ascending
- numerical order, then by the page name in ascending
- .Xr ascii 7
- alphabetical order, case-insensitive.
- .Pp
- Each output line is formatted as
- .Pp
- .D1 name[, name...](sec) \- description
- .Pp
- Where
- .Dq name
- is the manual's name,
- .Dq sec
- is the manual section, and
- .Dq description
- is the manual's short description.
- If an architecture is specified for the manual, it is displayed as
- .Pp
- .D1 name(sec/arch) \- description
- .Pp
- Resulting manuals may be accessed as
- .Pp
- .Dl $ man \-s sec name
- .Pp
- If an architecture is specified in the output, use
- .Pp
- .Dl $ man \-s sec \-S arch name
- .Ss Macro Keys
- Queries evaluate over a subset of
- .Xr mdoc 7
- macros indexed by
- .Xr makewhatis 8 .
- In addition to the macro keys listed below, the special key
- .Cm any
- may be used to match any available macro key.
- .Pp
- Names and description:
- .Bl -column "xLix" description -offset indent -compact
- .It Li \&Nm Ta manual name
- .It Li \&Nd Ta one-line manual description
- .It Li arch Ta machine architecture (case-insensitive)
- .It Li sec Ta manual section number
- .El
- .Pp
- Sections and cross references:
- .Bl -column "xLix" description -offset indent -compact
- .It Li \&Sh Ta section header (excluding standard sections)
- .It Li \&Ss Ta subsection header
- .It Li \&Xr Ta cross reference to another manual page
- .It Li \&Rs Ta bibliographic reference
- .El
- .Pp
- Semantic markup for command line utilities:
- .Bl -column "xLix" description -offset indent -compact
- .It Li \&Fl Ta command line options (flags)
- .It Li \&Cm Ta command modifier
- .It Li \&Ar Ta command argument
- .It Li \&Ic Ta internal or interactive command
- .It Li \&Ev Ta environmental variable
- .It Li \&Pa Ta file system path
- .El
- .Pp
- Semantic markup for function libraries:
- .Bl -column "xLix" description -offset indent -compact
- .It Li \&Lb Ta function library name
- .It Li \&In Ta include file
- .It Li \&Ft Ta function return type
- .It Li \&Fn Ta function name
- .It Li \&Fa Ta function argument type and name
- .It Li \&Vt Ta variable type
- .It Li \&Va Ta variable name
- .It Li \&Dv Ta defined variable or preprocessor constant
- .It Li \&Er Ta error constant
- .It Li \&Ev Ta environmental variable
- .El
- .Pp
- Various semantic markup:
- .Bl -column "xLix" description -offset indent -compact
- .It Li \&An Ta author name
- .It Li \&Lk Ta hyperlink
- .It Li \&Mt Ta Do mailto Dc hyperlink
- .It Li \&Cd Ta kernel configuration declaration
- .It Li \&Ms Ta mathematical symbol
- .It Li \&Tn Ta tradename
- .El
- .Pp
- Physical markup:
- .Bl -column "xLix" description -offset indent -compact
- .It Li \&Em Ta italic font or underline
- .It Li \&Sy Ta boldface font
- .It Li \&Li Ta typewriter font
- .El
- .Pp
- Text production:
- .Bl -column "xLix" description -offset indent -compact
- .It Li \&St Ta reference to a standards document
- .It Li \&At Ta At No version reference
- .It Li \&Bx Ta Bx No version reference
- .It Li \&Bsx Ta Bsx No version reference
- .It Li \&Nx Ta Nx No version reference
- .It Li \&Fx Ta Fx No version reference
- .It Li \&Ox Ta Ox No version reference
- .It Li \&Dx Ta Dx No version reference
- .El
- .Pp
- In general, macro keys are supposed to yield complete results without
- expecting the user to consider actual macro usage.
- For example, results include:
- .Pp
- .Bl -tag -width 3n -offset 3n -compact
- .It Li \&Fa
- function arguments appearing on
- .Ic \&Fn
- lines
- .It Li \&Fn
- function names marked up with
- .Ic \&Fo
- macros
- .It Li \&In
- include file names marked up with
- .Ic \&Fd
- macros
- .It Li \&Vt
- types appearing as function return types and
- .It \&
- types appearing in function arguments in the SYNOPSIS
- .El
- .Sh ENVIRONMENT
- .Bl -tag -width MANPAGER
- .It Ev MANPAGER
- Any non-empty value of the environment variable
- .Ev MANPAGER
- is used instead of the standard pagination program,
- .Xr less 1 ;
- see
- .Xr man 1
- for details.
- Only used if
- .Fl a
- or
- .Fl l
- is specified.
- .It Ev MANPATH
- A colon-separated list of directories to search for manual pages; see
- .Xr man 1
- for details.
- Overridden by
- .Fl M ,
- ignored if
- .Fl l
- is specified.
- .It Ev PAGER
- Specifies the pagination program to use when
- .Ev MANPAGER
- is not defined.
- If neither PAGER nor MANPAGER is defined,
- .Xr less 1
- is used.
- Only used if
- .Fl a
- or
- .Fl l
- is specified.
- .El
- .Sh FILES
- .Bl -tag -width "/etc/man.conf" -compact
- .It Pa mandoc.db
- name of the
- .Xr makewhatis 8
- keyword database
- .It Pa /etc/man.conf
- default
- .Xr man 1
- configuration file
- .El
- .Sh EXIT STATUS
- .Ex -std
- .Sh EXAMPLES
- Search for
- .Qq .cf
- as a substring of manual names and descriptions:
- .Pp
- .Dl $ apropos =.cf
- .Pp
- Include matches for
- .Qq .cnf
- and
- .Qq .conf
- as well:
- .Pp
- .Dl $ apropos =.cf =.cnf =.conf
- .Pp
- Search in names and descriptions using a case-sensitive regular expression:
- .Pp
- .Dl $ apropos \(aq\(tiset.?[ug]id\(aq
- .Pp
- Search for all manual pages in a given section:
- .Pp
- .Dl $ apropos \-s 9 \&.
- .Pp
- Search for manuals in the library section mentioning both the
- .Qq optind
- and the
- .Qq optarg
- variables:
- .Pp
- .Dl $ apropos \-s 3 Va=optind \-a Va=optarg
- .Pp
- Do exactly the same as calling
- .Nm whatis
- with the argument
- .Qq ssh :
- .Pp
- .Dl $ apropos \-\- \-i \(aqNm\(ti[[:<:]]ssh[[:>:]]\(aq
- .Pp
- The following two invocations are equivalent:
- .Pp
- .D1 Li $ apropos -S Ar arch Li -s Ar section expression
- .Bd -ragged -offset indent
- .Li $ apropos \e( Ar expression Li \e)
- .Li -a arch\(ti^( Ns Ar arch Ns Li |any)$
- .Li -a sec\(ti^ Ns Ar section Ns Li $
- .Ed
- .Sh SEE ALSO
- .Xr man 1 ,
- .Xr re_format 7 ,
- .Xr makewhatis 8
- .Sh STANDARDS
- The
- .Nm
- utility is compliant with the
- .St -p1003.1-2008
- specification of
- .Xr man 1
- .Fl k .
- .Pp
- All options, the
- .Nm whatis
- command, support for logical operators, macro keys,
- substring matching, sorting of results, the environment variables
- .Ev MANPAGER
- and
- .Ev MANPATH ,
- the database format, and the configuration file
- are extensions to that specification.
- .Sh HISTORY
- Part of the functionality of
- .Nm whatis
- was already provided by the former
- .Nm manwhere
- utility in
- .Bx 1 .
- The
- .Nm
- and
- .Nm whatis
- utilities first appeared in
- .Bx 2 .
- They were rewritten from scratch for
- .Ox 5.6 .
- .Pp
- The
- .Fl M
- option and the
- .Ev MANPATH
- variable first appeared in
- .Bx 4.3 ;
- .Fl m
- in
- .Bx 4.3 Reno ;
- .Fl C
- in
- .Bx 4.4 Lite1 ;
- and
- .Fl S
- and
- .Fl s
- in
- .Ox 4.5
- for
- .Nm
- and in
- .Ox 5.6
- for
- .Nm whatis .
- The options
- .Fl acfhIKklOTWw
- appeared in
- .Ox 5.7 .
- .Sh AUTHORS
- .An -nosplit
- .An Bill Joy
- wrote
- .Nm manwhere
- in 1977 and the original
- .Bx
- .Nm
- and
- .Nm whatis
- in February 1979.
- The current version was written by
- .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
- and
- .An Ingo Schwarze Aq Mt schwarze@openbsd.org .