-.\" $Id: mansearch.3,v 1.1 2014/04/15 20:18:26 schwarze Exp $
+.\" $Id: mansearch.3,v 1.5 2017/03/30 22:22:05 schwarze Exp $
.\"
.\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: April 15 2014 $
+.Dd $Mdocdate: March 30 2017 $
.Dt MANSEARCH 3
.Os
.Sh NAME
-.Nm mansearch ,
-.Nm mansearch_setup
+.Nm mansearch
.Nd search manual page databases
.Sh SYNOPSIS
-.In manpath.h
+.In stdint.h
+.In manconf.h
.In mansearch.h
.Ft int
-.Fo mansearch_setup
-.Fa "int start"
-.Fc
-.Ft int
.Fo mansearch
.Fa "const struct mansearch *search"
.Fa "const struct manpaths *paths"
.Fa "int argc"
.Fa "char *argv[]"
-.Fa "const char *outkey"
.Fa "struct manpage **res"
.Fa "size_t *sz"
.Fc
.Fn mansearch
function returns information about manuals matching a search query from a
.Xr mandoc.db 5
-SQLite3 database.
+database.
.Pp
The query arguments are as follows:
.Bl -tag -width Ds
.In mansearch.h .
.It Fa "const struct manpaths *paths"
Directories to be searched, defined in
-.In manpath.h .
+.In manconf.h .
.It Fa "int argc" , "char *argv[]"
Search criteria, usually taken from the command line.
.El
.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:
.Bl -tag -width Ds
.It Fa "struct manpage **res"
Returns the number of result structures contained in
.Fa res .
.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
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.
.Pp
All function mentioned here are defined in the file
.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
-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
.Fn exprcomp
building a singly linked list of
.Vt expr
structures, using the helper functions
-.Fn exprterm
+.Fn expr_and
and
-.Fn exprspec .
-The resulting SQL statement is assembled by the function
-.Fn sql_statement
-and evaluated in the main loop of the
-.Fn mansearch
-function.
+.Fn exprterm .
.Ss Assembling the results
The names, sections, and architectures of the manuals found
are assembled into the
.Va names
field of the result structure by the function
-.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 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 & ?"
+.Fn buildnames .
.Sh FILES
.Bl -tag -width mandoc.db -compact
.It Pa mandoc.db
The manual page database.
.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
.Xr apropos 1 ,
.Xr mandoc.db 5 ,
A module to search manual page databases was first written by
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
in 2011, at first using the Berkeley DB;
-he rewrote it for SQLite3 in 2012.
-The current version received major changes from
-.An Ingo Schwarze Aq Mt schwarze@openbsd.org .
+he rewrote it for SQLite3 in 2012, and
+.An Ingo Schwarze Aq Mt schwarze@openbsd.org
+removed the dependency on SQLite3 in 2016.
git.ckatri.com / mandoc.git / blobdiff