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

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