1.\" $Id: mansearch.3,v 1.4 2015/03/27 17:37:25 schwarze Exp $
| 1.\" $Id: mansearch.3,v 1.5 2017/03/30 22:22:05 schwarze Exp $
|
2.\"
3.\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org>
4.\"
5.\" Permission to use, copy, modify, and distribute this software for any
6.\" purpose with or without fee is hereby granted, provided that the above
7.\" copyright notice and this permission notice appear in all copies.
8.\"
9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16.\"
| 2.\"
3.\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org>
4.\"
5.\" Permission to use, copy, modify, and distribute this software for any
6.\" purpose with or without fee is hereby granted, provided that the above
7.\" copyright notice and this permission notice appear in all copies.
8.\"
9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16.\"
|
17.Dd $Mdocdate: March 27 2015 $
| 17.Dd $Mdocdate: March 30 2017 $
|
18.Dt MANSEARCH 3
19.Os
20.Sh NAME
| 18.Dt MANSEARCH 3
19.Os
20.Sh NAME
|
21.Nm mansearch ,
22.Nm mansearch_setup
| 21.Nm mansearch
|
23.Nd search manual page databases
24.Sh SYNOPSIS
25.In stdint.h
26.In manconf.h
27.In mansearch.h
28.Ft int
| 22.Nd search manual page databases
23.Sh SYNOPSIS
24.In stdint.h
25.In manconf.h
26.In mansearch.h
27.Ft int
|
29.Fo mansearch_setup
30.Fa "int start"
31.Fc
32.Ft int
| |
33.Fo mansearch
34.Fa "const struct mansearch *search"
35.Fa "const struct manpaths *paths"
36.Fa "int argc"
37.Fa "char *argv[]"
| 28.Fo mansearch
29.Fa "const struct mansearch *search"
30.Fa "const struct manpaths *paths"
31.Fa "int argc"
32.Fa "char *argv[]"
|
38.Fa "const char *outkey"
| |
39.Fa "struct manpage **res"
40.Fa "size_t *sz"
41.Fc
42.Sh DESCRIPTION
43The
44.Fn mansearch
45function returns information about manuals matching a search query from a
46.Xr mandoc.db 5
| 33.Fa "struct manpage **res"
34.Fa "size_t *sz"
35.Fc
36.Sh DESCRIPTION
37The
38.Fn mansearch
39function returns information about manuals matching a search query from a
40.Xr mandoc.db 5
|
47SQLite3 database.
| 41database.
|
48.Pp
49The query arguments are as follows:
50.Bl -tag -width Ds
51.It Fa "const struct mansearch *search"
52Search options, defined in
53.In mansearch.h .
54.It Fa "const struct manpaths *paths"
55Directories to be searched, defined in
56.In manconf.h .
57.It Fa "int argc" , "char *argv[]"
58Search criteria, usually taken from the command line.
59.El
60.Pp
| 42.Pp
43The query arguments are as follows:
44.Bl -tag -width Ds
45.It Fa "const struct mansearch *search"
46Search options, defined in
47.In mansearch.h .
48.It Fa "const struct manpaths *paths"
49Directories to be searched, defined in
50.In manconf.h .
51.It Fa "int argc" , "char *argv[]"
52Search criteria, usually taken from the command line.
53.El
54.Pp
|
61The
62.Fa "const char *outkey"
63selects which data to return in the
64.Va output
65field of the
66.Fa res
67structures.
68It takes any of the macro keys defined in
69.Pa mansearch_const.c
70and described in
71.Xr apropos 1 .
72.Pp
| |
73The output arguments are as follows:
74.Bl -tag -width Ds
75.It Fa "struct manpage **res"
76Returns a pointer to an array of result structures defined in
77.In mansearch.h .
78The user is expected to call
79.Xr free 3
80on the
81.Va file ,
82.Va names ,
83and
84.Va output
85fields of all structures, as well as the
86.Fa res
87array itself.
88.It Fa "size_t *sz"
89Returns the number of result structures contained in
90.Fa res .
91.El
| 55The output arguments are as follows:
56.Bl -tag -width Ds
57.It Fa "struct manpage **res"
58Returns a pointer to an array of result structures defined in
59.In mansearch.h .
60The user is expected to call
61.Xr free 3
62on the
63.Va file ,
64.Va names ,
65and
66.Va output
67fields of all structures, as well as the
68.Fa res
69array itself.
70.It Fa "size_t *sz"
71Returns the number of result structures contained in
72.Fa res .
73.El
|
92.Pp
93To speed up searches, the
94.Fn mansearch_setup
95function can optionally be called with a
96.Fa start
97argument of 1 before
98.Fn mansearch
99to set up an SQLite3 pagecache.
100If it was called, it has to be called again with a
101.Fa start
102argument of 0 after the last call to
103.Fn mansearch
104to release the memory used for the pagecache.
| |
105.Sh IMPLEMENTATION NOTES
106For each manual page tree, the search is done in two steps.
107In the first step, a list of pages matching the search criteria is built.
108In the second step, the requested information about these pages is
109retrieved from the database and assembled into the
110.Fa res
111array.
112.Pp
113All function mentioned here are defined in the file
114.Pa mansearch.c .
| 74.Sh IMPLEMENTATION NOTES
75For each manual page tree, the search is done in two steps.
76In the first step, a list of pages matching the search criteria is built.
77In the second step, the requested information about these pages is
78retrieved from the database and assembled into the
79.Fa res
80array.
81.Pp
82All function mentioned here are defined in the file
83.Pa mansearch.c .
|
115No functions except
116.Fn mansearch
117and
118.Fn sql_statement
119build any SQL code, and no functions except
120.Fn mansearch ,
121.Fn buildnames ,
122and
123.Fn buildoutput
124execute it.
| |
125.Ss Finding matches
| 84.Ss Finding matches
|
126The query is built using the following grammar:
127.Bd -literal -offset indent
128<query> ::= "SELECT * FROM mpages WHERE" <condition>
129<condition> ::= "(" <condition> ")" |
130 <condition> "OR" <condition> |
131 <condition> "AND" <condition> |
132 "desc" <operator> "?" |
133 "id IN (SELECT pageid FROM" <subquery> ")"
134<subquery> ::= "names WHERE name" <operator> "?" |
135 "keys WHERE key" <operator> "? AND bits & ?"
136<operator> ::= "MATCH" | "REGEXP"
137.Ed
138.Pp
139The MATCH and REGEXP operators are implemented by the functions
140.Fn sql_match
141and
142.Fn sql_regexp ,
143respectively.
144This is required because SQLite3 natively neither supports
145case-insensitive substring matching nor regular expression matching,
146but only string identity, shell globbing, and the weird home-brewed
147LIKE operator.
148.Pp
| |
149Command line parsing is done by the function
150.Fn exprcomp
151building a singly linked list of
152.Vt expr
153structures, using the helper functions
| 85Command line parsing is done by the function
86.Fn exprcomp
87building a singly linked list of
88.Vt expr
89structures, using the helper functions
|
154.Fn exprterm
| 90.Fn expr_and
|
155and
| 91and
|
156.Fn exprspec .
157The resulting SQL statement is assembled by the function
158.Fn sql_statement
159and evaluated in the main loop of the
160.Fn mansearch
161function.
| 92.Fn exprterm .
|
162.Ss Assembling the results
163The names, sections, and architectures of the manuals found
164are assembled into the
165.Va names
166field of the result structure by the function
| 93.Ss Assembling the results
94The names, sections, and architectures of the manuals found
95are assembled into the
96.Va names
97field of the result structure by the function
|
167.Fn buildnames ,
168using the following query:
169.Pp
170.Dl "SELECT * FROM mlinks WHERE pageid=? ORDER BY sec, arch, name"
171.Pp
172If the
173.Fa outkey
174differs from
175.Qq Ic \&Nd ,
176the requested output data is assembled into the
177.Va output
178field of the result structure by the function
179.Fn buildoutput ,
180using the following query:
181.Pp
182.Dl "SELECT * FROM keys WHERE pageid=? AND bits & ?"
| 98.Fn buildnames .
|
183.Sh FILES
184.Bl -tag -width mandoc.db -compact
185.It Pa mandoc.db
186The manual page database.
187.El
| 99.Sh FILES
100.Bl -tag -width mandoc.db -compact
101.It Pa mandoc.db
102The manual page database.
103.El
|
188.Sh EXAMPLES
189The simplest invocation
190.Pp
191.Dl apropos keyword
192.Pp
193results in the following SQL query:
194.Bd -literal
195SELECT * FROM mpages WHERE (
196 id IN (SELECT pageid FROM names WHERE name MATCH 'keyword') OR
197 desc MATCH 'keyword'
198);
199.Ed
200.Pp
201A more complicated request like
202.Pp
203.Dl apropos -s 2 Nm,Xr=getuid
204.Pp
205results in:
206.Bd -literal
207SELECT * FROM mpages WHERE (
208 id IN (SELECT pageid FROM names WHERE name MATCH 'getuid') OR
209 id IN (SELECT pageid FROM keys WHERE key MATCH 'getuid' AND bits & 4)
210) AND id IN (SELECT pageid FROM keys WHERE key REGEXP '^2$' AND bits & 2);
211.Ed
| |
212.Sh SEE ALSO
213.Xr apropos 1 ,
214.Xr mandoc.db 5 ,
215.Xr makewhatis 8
216.Sh HISTORY
217The
218.Fn mansearch
219subsystem first appeared in
220.Ox 5.6 .
221.Sh AUTHORS
222.An -nosplit
223A module to search manual page databases was first written by
224.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
225in 2011, at first using the Berkeley DB;
| 104.Sh SEE ALSO
105.Xr apropos 1 ,
106.Xr mandoc.db 5 ,
107.Xr makewhatis 8
108.Sh HISTORY
109The
110.Fn mansearch
111subsystem first appeared in
112.Ox 5.6 .
113.Sh AUTHORS
114.An -nosplit
115A module to search manual page databases was first written by
116.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
117in 2011, at first using the Berkeley DB;
|
226he rewrote it for SQLite3 in 2012.
227The current version received major changes from
228.An Ingo Schwarze Aq Mt schwarze@openbsd.org .
| 118he rewrote it for SQLite3 in 2012, and
119.An Ingo Schwarze Aq Mt schwarze@openbsd.org
120removed the dependency on SQLite3 in 2016.
|
| |