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.\" 17.Dd $Mdocdate: March 30 2017 $ 18.Dt MANSEARCH 3 19.Os 20.Sh NAME 21.Nm mansearch 22.Nd search manual page databases 23.Sh SYNOPSIS 24.In stdint.h 25.In manconf.h 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 37The 38.Fn mansearch 39function returns information about manuals matching a search query from a 40.Xr mandoc.db 5 41database. 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 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 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 . 84.Ss Finding matches 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 90.Fn expr_and 91and 92.Fn exprterm . 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 98.Fn buildnames . 99.Sh FILES 100.Bl -tag -width mandoc.db -compact 101.It Pa mandoc.db 102The 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 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; 118he rewrote it for SQLite3 in 2012, and 119.An Ingo Schwarze Aq Mt schwarze@openbsd.org 120removed the dependency on SQLite3 in 2016. 121