514 lines
11 KiB
Groff
514 lines
11 KiB
Groff
.\" $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 .
|