\" Id: apropos.1,v 1.51 2020/10/01 22:50:00 schwarze Exp
\"
\" Copyright (c) 2011, 2012 Kristaps Dzonsons <[email protected]>
\" Copyright (c) 2011,2012,2014,2017,2018 Ingo Schwarze <[email protected]>
\"
\" 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 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 [email protected]
and
An Ingo Schwarze Aq Mt [email protected] .

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.