[BACK]Return to mansearch.3 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mansearch.3 between version 1.2 and 1.5

version 1.2, 2014/08/05 15:29:30 version 1.5, 2017/03/30 22:22:05
Line 18 
Line 18 
 .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 manpath.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
Line 44  The
Line 38  The
 .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 53  Search options, defined in
Line 47  Search options, defined in
 .In mansearch.h .  .In mansearch.h .
 .It Fa "const struct manpaths *paths"  .It Fa "const struct manpaths *paths"
 Directories to be searched, defined in  Directories to be searched, defined in
 .In manpath.h .  .In manconf.h .
 .It Fa "int argc" , "char *argv[]"  .It Fa "int argc" , "char *argv[]"
 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"
Line 89  array itself.
Line 71  array itself.
 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.
Line 112  array.
Line 81  array.
 .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 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.

Legend:
Removed from v.1.2  
changed lines
  Added in v.1.5

CVSweb