version 1.4, 2015/03/27 17:37:25 |
version 1.5, 2017/03/30 22:22:05 |
|
|
.Dt MANSEARCH 3 |
.Dt MANSEARCH 3 |
.Os |
.Os |
.Sh NAME |
.Sh NAME |
.Nm mansearch , |
.Nm mansearch |
.Nm mansearch_setup |
|
.Nd search manual page databases |
.Nd search manual page databases |
.Sh SYNOPSIS |
.Sh SYNOPSIS |
.In stdint.h |
.In stdint.h |
.In manconf.h |
.In manconf.h |
.In mansearch.h |
.In mansearch.h |
.Ft int |
.Ft int |
.Fo mansearch_setup |
|
.Fa "int start" |
|
.Fc |
|
.Ft int |
|
.Fo mansearch |
.Fo mansearch |
.Fa "const struct mansearch *search" |
.Fa "const struct mansearch *search" |
.Fa "const struct manpaths *paths" |
.Fa "const struct manpaths *paths" |
.Fa "int argc" |
.Fa "int argc" |
.Fa "char *argv[]" |
.Fa "char *argv[]" |
.Fa "const char *outkey" |
|
.Fa "struct manpage **res" |
.Fa "struct manpage **res" |
.Fa "size_t *sz" |
.Fa "size_t *sz" |
.Fc |
.Fc |
|
|
.Fn mansearch |
.Fn mansearch |
function returns information about manuals matching a search query from a |
function returns information about manuals matching a search query from a |
.Xr mandoc.db 5 |
.Xr mandoc.db 5 |
SQLite3 database. |
database. |
.Pp |
.Pp |
The query arguments are as follows: |
The query arguments are as follows: |
.Bl -tag -width Ds |
.Bl -tag -width Ds |
Line 58 Directories to be searched, defined in |
|
Line 52 Directories to be searched, defined in |
|
Search criteria, usually taken from the command line. |
Search criteria, usually taken from the command line. |
.El |
.El |
.Pp |
.Pp |
The |
|
.Fa "const char *outkey" |
|
selects which data to return in the |
|
.Va output |
|
field of the |
|
.Fa res |
|
structures. |
|
It takes any of the macro keys defined in |
|
.Pa mansearch_const.c |
|
and described in |
|
.Xr apropos 1 . |
|
.Pp |
|
The output arguments are as follows: |
The output arguments are as follows: |
.Bl -tag -width Ds |
.Bl -tag -width Ds |
.It Fa "struct manpage **res" |
.It Fa "struct manpage **res" |
|
|
Returns the number of result structures contained in |
Returns the number of result structures contained in |
.Fa res . |
.Fa res . |
.El |
.El |
.Pp |
|
To speed up searches, the |
|
.Fn mansearch_setup |
|
function can optionally be called with a |
|
.Fa start |
|
argument of 1 before |
|
.Fn mansearch |
|
to set up an SQLite3 pagecache. |
|
If it was called, it has to be called again with a |
|
.Fa start |
|
argument of 0 after the last call to |
|
.Fn mansearch |
|
to release the memory used for the pagecache. |
|
.Sh IMPLEMENTATION NOTES |
.Sh IMPLEMENTATION NOTES |
For each manual page tree, the search is done in two steps. |
For each manual page tree, the search is done in two steps. |
In the first step, a list of pages matching the search criteria is built. |
In the first step, a list of pages matching the search criteria is built. |
|
|
.Pp |
.Pp |
All function mentioned here are defined in the file |
All function mentioned here are defined in the file |
.Pa mansearch.c . |
.Pa mansearch.c . |
No functions except |
|
.Fn mansearch |
|
and |
|
.Fn sql_statement |
|
build any SQL code, and no functions except |
|
.Fn mansearch , |
|
.Fn buildnames , |
|
and |
|
.Fn buildoutput |
|
execute it. |
|
.Ss Finding matches |
.Ss Finding matches |
The query is built using the following grammar: |
|
.Bd -literal -offset indent |
|
<query> ::= "SELECT * FROM mpages WHERE" <condition> |
|
<condition> ::= "(" <condition> ")" | |
|
<condition> "OR" <condition> | |
|
<condition> "AND" <condition> | |
|
"desc" <operator> "?" | |
|
"id IN (SELECT pageid FROM" <subquery> ")" |
|
<subquery> ::= "names WHERE name" <operator> "?" | |
|
"keys WHERE key" <operator> "? AND bits & ?" |
|
<operator> ::= "MATCH" | "REGEXP" |
|
.Ed |
|
.Pp |
|
The MATCH and REGEXP operators are implemented by the functions |
|
.Fn sql_match |
|
and |
|
.Fn sql_regexp , |
|
respectively. |
|
This is required because SQLite3 natively neither supports |
|
case-insensitive substring matching nor regular expression matching, |
|
but only string identity, shell globbing, and the weird home-brewed |
|
LIKE operator. |
|
.Pp |
|
Command line parsing is done by the function |
Command line parsing is done by the function |
.Fn exprcomp |
.Fn exprcomp |
building a singly linked list of |
building a singly linked list of |
.Vt expr |
.Vt expr |
structures, using the helper functions |
structures, using the helper functions |
.Fn exprterm |
.Fn expr_and |
and |
and |
.Fn exprspec . |
.Fn exprterm . |
The resulting SQL statement is assembled by the function |
|
.Fn sql_statement |
|
and evaluated in the main loop of the |
|
.Fn mansearch |
|
function. |
|
.Ss Assembling the results |
.Ss Assembling the results |
The names, sections, and architectures of the manuals found |
The names, sections, and architectures of the manuals found |
are assembled into the |
are assembled into the |
.Va names |
.Va names |
field of the result structure by the function |
field of the result structure by the function |
.Fn buildnames , |
.Fn buildnames . |
using the following query: |
|
.Pp |
|
.Dl "SELECT * FROM mlinks WHERE pageid=? ORDER BY sec, arch, name" |
|
.Pp |
|
If the |
|
.Fa outkey |
|
differs from |
|
.Qq Ic \&Nd , |
|
the requested output data is assembled into the |
|
.Va output |
|
field of the result structure by the function |
|
.Fn buildoutput , |
|
using the following query: |
|
.Pp |
|
.Dl "SELECT * FROM keys WHERE pageid=? AND bits & ?" |
|
.Sh FILES |
.Sh FILES |
.Bl -tag -width mandoc.db -compact |
.Bl -tag -width mandoc.db -compact |
.It Pa mandoc.db |
.It Pa mandoc.db |
The manual page database. |
The manual page database. |
.El |
.El |
.Sh EXAMPLES |
|
The simplest invocation |
|
.Pp |
|
.Dl apropos keyword |
|
.Pp |
|
results in the following SQL query: |
|
.Bd -literal |
|
SELECT * FROM mpages WHERE ( |
|
id IN (SELECT pageid FROM names WHERE name MATCH 'keyword') OR |
|
desc MATCH 'keyword' |
|
); |
|
.Ed |
|
.Pp |
|
A more complicated request like |
|
.Pp |
|
.Dl apropos -s 2 Nm,Xr=getuid |
|
.Pp |
|
results in: |
|
.Bd -literal |
|
SELECT * FROM mpages WHERE ( |
|
id IN (SELECT pageid FROM names WHERE name MATCH 'getuid') OR |
|
id IN (SELECT pageid FROM keys WHERE key MATCH 'getuid' AND bits & 4) |
|
) AND id IN (SELECT pageid FROM keys WHERE key REGEXP '^2$' AND bits & 2); |
|
.Ed |
|
.Sh SEE ALSO |
.Sh SEE ALSO |
.Xr apropos 1 , |
.Xr apropos 1 , |
.Xr mandoc.db 5 , |
.Xr mandoc.db 5 , |
Line 223 subsystem first appeared in |
|
Line 115 subsystem first appeared in |
|
A module to search manual page databases was first written by |
A module to search manual page databases was first written by |
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv |
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv |
in 2011, at first using the Berkeley DB; |
in 2011, at first using the Berkeley DB; |
he rewrote it for SQLite3 in 2012. |
he rewrote it for SQLite3 in 2012, and |
The current version received major changes from |
.An Ingo Schwarze Aq Mt schwarze@openbsd.org |
.An Ingo Schwarze Aq Mt schwarze@openbsd.org . |
removed the dependency on SQLite3 in 2016. |