version 1.2, 2011/10/08 12:24:40 |
version 1.20, 2013/07/05 09:33:02 |
|
|
.\" $Id$ |
.\" $Id$ |
.\" |
.\" |
.\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" |
.\" |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" purpose with or without fee is hereby granted, provided that the above |
.\" purpose with or without fee is hereby granted, provided that the above |
|
|
.Dt APROPOS 1 |
.Dt APROPOS 1 |
.Os |
.Os |
.Sh NAME |
.Sh NAME |
.Nm apropos |
.Nm apropos , |
.Nd search the manual page database |
.Nm whatis |
|
.Nd search manual page databases |
.Sh SYNOPSIS |
.Sh SYNOPSIS |
.Nm |
.Nm |
.Op Fl eIr |
.Op Fl C Ar file |
.Op Fl a Ar arch |
.Op Fl M Ar path |
.Op Fl c Ar cat |
.Op Fl m Ar path |
.Op Fl s Ar sort |
.Op Fl S Ar arch |
.Op Fl t Ar types |
.Op Fl s Ar section |
.Ar key |
.Ar expression ... |
.Sh DESCRIPTION |
.Sh DESCRIPTION |
The |
The |
|
.Nm apropos |
|
and |
|
.Nm whatis |
|
utilities query manual page databases generated by |
|
.Xr mandocdb 8 , |
|
evaluating on |
|
.Ar expression |
|
for each file in each database. |
|
.Pp |
|
By default, |
.Nm |
.Nm |
utility queries the manual page database. |
searches for |
|
.Xr mandocdb 8 |
|
databases in the default paths stipulated by |
|
.Xr man 1 |
|
and |
|
maps terms to case-sensitive manual names and descriptions. |
|
Multiple terms are OR'd. |
|
.Nm whatis |
|
maps terms only to case-sensitive manual names. |
|
.Pp |
Its arguments are as follows: |
Its arguments are as follows: |
.Bl -tag -width Ds |
.Bl -tag -width Ds |
.It Fl a Ar arch |
.It Fl C Ar file |
|
Specify an alternative configuration |
|
.Ar file |
|
in |
|
.Xr man.conf 5 |
|
format. |
|
.It Fl M Ar path |
|
Use the colon-separated path instead of the default list of paths |
|
searched for |
|
.Xr mandocdb 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 mandocdb 8 |
|
databases. |
|
Invalid paths, or paths without manual databases, are ignored. |
|
.It Fl S Ar arch |
Search only for a particular architecture. |
Search only for a particular architecture. |
.It Fl c Ar cat |
.It Fl s Ar cat |
Search only for a category (manual section). |
Search only for a manual section. |
See |
See |
.Xr man 1 |
.Xr man 1 |
for a listing of categories. |
for a listing of manual sections. |
.It Fl e |
|
Search only for exact matches (subject to |
|
.Fl I ) . |
|
.It Fl I |
|
Case-insensitive matching. |
|
.It Fl r |
|
Consider |
|
.Ar key |
|
to be a POSIX regular expression (subject to |
|
.Fl I ) . |
|
See |
|
.Xr re_format 7 |
|
for a description of regular expressions. |
|
.It Fl s Ar sort |
|
Sorting type. |
|
Accepts |
|
.Ar cat |
|
to sort by category and then by title or |
|
.Ar title |
|
to sort by title (which is the default). |
|
.It Fl t Ar types |
|
Consider only types of keyword match, where |
|
.Ar types |
|
is a comma-separated list consisting of the following: |
|
.Ar name , |
|
manual names; |
|
.Ar func , |
|
function names; |
|
.Ar utility , |
|
utility names; |
|
.Ar incl , |
|
include files; |
|
.Ar var , |
|
variable names; |
|
.Ar stand , |
|
standards ; |
|
.Ar auth , |
|
authors; |
|
.Ar conf , |
|
configuration strings; |
|
.Ar desc , |
|
descriptive text; |
|
.Ar xref , |
|
cross-references. |
|
.Ar path , |
|
file pathnames; |
|
.Ar env , |
|
environment variables; or |
|
.Ar err , |
|
error codes. |
|
Specifying |
|
.Ar all |
|
will search for all types. |
|
.It Ar key |
|
The search key. |
|
.El |
.El |
.Pp |
.Pp |
By default, |
.Nm whatis |
.Nm |
considers an |
searches for substring matches of |
.Ar expression |
.Ar key |
to consist of an opaque keyword. |
in manual names and descriptions |
.Nm apropos |
and displays results by manual title. |
parses a |
Output is formatted as |
.Ar expression |
|
into type and keyword pairs. |
|
This pair syntax |
|
.Li [key[,key]*(=~)]?val , |
|
where operand |
|
.Cm key |
|
is an |
|
.Xr mdoc 7 |
|
macro to query and |
|
.Cm val |
|
is its value. |
|
See |
|
.Sx Macro Keys |
|
for a list of available keys. |
|
Operator |
|
.Li \&= |
|
evaluates a full string, while |
|
.Li \&~ |
|
evaluates a |
|
.Xr glob 7 |
|
pattern. |
.Pp |
.Pp |
.D1 title(cat) \- description |
Results are sorted by manual title, with output formatted as |
.Pp |
.Qq title(sec) \- description |
Where |
where |
.Qq title |
.Qq title |
is the manual's title (note multiple manual names may exist for one |
is the manual's title (note multiple manual names may exist for one |
title), |
title), |
.Qq cat |
.Qq sec |
is the category, and |
is the manual section, and |
.Qq description |
.Qq description |
is the manual's short description. |
is the manual's short description. |
If an architecture is specified for the manual, it is displayed as |
If an architecture is specified for the manual, it is displayed as |
|
.Qq title(cat/arch) \- description . |
|
.Ss Macro Keys |
|
.Nm apropos |
|
queries evaluate over a subset of |
|
.Xr mdoc 7 |
|
macros indexed by |
|
.Xr mandocdb 8 . |
|
In addition to the macro keys listed below, the special key |
|
.Cm any |
|
may be used to match any available macro key. |
.Pp |
.Pp |
.D1 title(cat/arch) \- description |
Names and description: |
|
.Bl -column "xLix" description -offset indent -compact |
|
.It Li \&Nm Ta manual name |
|
.It Li \&Nd Ta one-line manual description |
|
.El |
.Pp |
.Pp |
Resulting manuals may be accessed as |
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 |
.Pp |
.Dl $ man -s cat title |
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 |
.Pp |
If an architecture is specified in the output, use |
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 |
.Pp |
.Dl $ man -s cat -S arch title |
Various semantic markup: |
.\" .Sh IMPLEMENTATION NOTES |
.Bl -column "xLix" description -offset indent -compact |
.\" Not used in OpenBSD. |
.It Li \&An Ta author name |
.\" .Sh RETURN VALUES |
.It Li \&Lk Ta hyperlink |
.\" For sections 2, 3, & 9 only. |
.It Li \&Mt Ta Do mailto Dc hyperlink |
.\" .Sh ENVIRONMENT |
.It Li \&Cd Ta kernel configuration declaration |
.\" For sections 1, 6, 7, & 8 only. |
.It Li \&Ms Ta mathematical symbol |
.\" .Sh FILES |
.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 |
|
.Sh ENVIRONMENT |
|
.Bl -tag -width Ds |
|
.It Ev MANPATH |
|
Colon-separated paths modifying the default list of paths searched for |
|
manual databases. |
|
Invalid paths, or paths without manual databases, are ignored. |
|
Overridden by |
|
.Fl M . |
|
If |
|
.Ev MANPATH |
|
begins with a |
|
.Sq \&: , |
|
it is appended to the default list; |
|
else if it ends with |
|
.Sq \&: , |
|
it is prepended to the default list; else if it contains |
|
.Sq \&:: , |
|
the default list is inserted between the colons. |
|
If none of these conditions are met, it overrides the default list. |
|
.El |
|
.Sh FILES |
|
.Bl -tag -width "/etc/man.conf" -compact |
|
.It Pa mandocdb.db |
|
name of the |
|
.Xr mandocdb 8 |
|
keyword database |
|
.It Pa /etc/man.conf |
|
default |
|
.Xr man 1 |
|
configuration file |
|
.El |
.Sh EXIT STATUS |
.Sh EXIT STATUS |
.Ex -std |
.Ex -std |
.Sh EXAMPLES |
.Sh EXAMPLES |
Search for |
Search for |
.Qq optind |
.Qq mdoc |
as a variable name in the library category: |
as a word or |
|
.Xr glob 7 |
|
expression: |
.Pp |
.Pp |
.Dl $ apropos -tvar -c 3 optind |
.Dl $ apropos mdoc |
|
.Dl $ apropos any~mdoc* |
.Pp |
.Pp |
Search for all manuals referencing the term |
Include matches for |
.Qq POSIX |
.Qq roff |
in any letter case: |
and |
|
.Qq man |
|
using |
|
.Xr glob 7 |
|
expressions: |
.Pp |
.Pp |
.Dl $ apropos -tall -I posix |
.Dl $ apropos ~*mdoc* ~*roff* |
.\" .Sh DIAGNOSTICS |
.Pp |
.\" For sections 1, 4, 6, 7, & 8 only. |
Search for |
.\" .Sh ERRORS |
.Qq optarg |
.\" For sections 2, 3, & 9 only. |
as a variable name in the library category: |
|
.Pp |
|
.Dl $ apropos \-s 3 Va=optarg |
.Sh SEE ALSO |
.Sh SEE ALSO |
.Xr man 1 , |
.Xr glob 7 , |
.Xr mandoc 1 , |
.Xr mandocdb 8 |
.Xr re_format 7 |
|
.\" .Sh STANDARDS |
|
.\" .Sh HISTORY |
|
.Sh AUTHORS |
.Sh AUTHORS |
The |
The |
.Nm |
.Nm |
utility was written by |
utility was written by |
.An Kristaps Dzonsons , |
.An Kristaps Dzonsons , |
.Mt kristaps@bsd.lv . |
.Mt kristaps@bsd.lv . |
.\" .Sh CAVEATS |
|
.\" .Sh BUGS |
|
.\" .Sh SECURITY CONSIDERATIONS |
|
.\" Not used in OpenBSD. |
|