Annotation of mandoc/mansearch.3, Revision 1.5
1.5 ! schwarze 1: .\" $Id: mansearch.3,v 1.4 2015/03/27 17:37:25 schwarze Exp $
1.1 schwarze 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: .\"
1.5 ! schwarze 17: .Dd $Mdocdate: March 27 2015 $
1.1 schwarze 18: .Dt MANSEARCH 3
19: .Os
20: .Sh NAME
1.5 ! schwarze 21: .Nm mansearch
1.1 schwarze 22: .Nd search manual page databases
23: .Sh SYNOPSIS
1.2 schwarze 24: .In stdint.h
1.4 schwarze 25: .In manconf.h
1.1 schwarze 26: .In mansearch.h
27: .Ft int
28: .Fo mansearch
29: .Fa "const struct mansearch *search"
30: .Fa "const struct manpaths *paths"
31: .Fa "int argc"
32: .Fa "char *argv[]"
33: .Fa "struct manpage **res"
34: .Fa "size_t *sz"
35: .Fc
36: .Sh DESCRIPTION
37: The
38: .Fn mansearch
39: function returns information about manuals matching a search query from a
40: .Xr mandoc.db 5
1.5 ! schwarze 41: database.
1.1 schwarze 42: .Pp
43: The query arguments are as follows:
44: .Bl -tag -width Ds
45: .It Fa "const struct mansearch *search"
46: Search options, defined in
47: .In mansearch.h .
48: .It Fa "const struct manpaths *paths"
49: Directories to be searched, defined in
1.4 schwarze 50: .In manconf.h .
1.1 schwarze 51: .It Fa "int argc" , "char *argv[]"
52: Search criteria, usually taken from the command line.
53: .El
54: .Pp
55: The output arguments are as follows:
56: .Bl -tag -width Ds
57: .It Fa "struct manpage **res"
58: Returns a pointer to an array of result structures defined in
59: .In mansearch.h .
60: The user is expected to call
61: .Xr free 3
62: on the
63: .Va file ,
64: .Va names ,
65: and
66: .Va output
67: fields of all structures, as well as the
68: .Fa res
69: array itself.
70: .It Fa "size_t *sz"
71: Returns the number of result structures contained in
72: .Fa res .
73: .El
74: .Sh IMPLEMENTATION NOTES
75: For each manual page tree, the search is done in two steps.
76: In the first step, a list of pages matching the search criteria is built.
77: In the second step, the requested information about these pages is
78: retrieved from the database and assembled into the
79: .Fa res
80: array.
81: .Pp
82: All function mentioned here are defined in the file
83: .Pa mansearch.c .
84: .Ss Finding matches
85: Command line parsing is done by the function
86: .Fn exprcomp
87: building a singly linked list of
88: .Vt expr
89: structures, using the helper functions
1.5 ! schwarze 90: .Fn expr_and
1.1 schwarze 91: and
1.5 ! schwarze 92: .Fn exprterm .
1.1 schwarze 93: .Ss Assembling the results
94: The names, sections, and architectures of the manuals found
95: are assembled into the
96: .Va names
97: field of the result structure by the function
1.5 ! schwarze 98: .Fn buildnames .
1.1 schwarze 99: .Sh FILES
100: .Bl -tag -width mandoc.db -compact
101: .It Pa mandoc.db
102: The manual page database.
103: .El
104: .Sh SEE ALSO
105: .Xr apropos 1 ,
106: .Xr mandoc.db 5 ,
107: .Xr makewhatis 8
108: .Sh HISTORY
109: The
110: .Fn mansearch
111: subsystem first appeared in
112: .Ox 5.6 .
113: .Sh AUTHORS
114: .An -nosplit
115: A module to search manual page databases was first written by
116: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
117: in 2011, at first using the Berkeley DB;
1.5 ! schwarze 118: he rewrote it for SQLite3 in 2012, and
! 119: .An Ingo Schwarze Aq Mt schwarze@openbsd.org
! 120: removed the dependency on SQLite3 in 2016.
CVSweb