1.\" $NetBSD: run_query.3,v 1.2 2012/02/07 21:02:23 wiz Exp $ 2.\" 3.\" Copyright (c) 2011 Abhinav Upadhyay <er.abhinav.upadhyay@gmail.com> 4.\" All rights reserved. 5.\" 6.\" This code was developed as part of Google's Summer of Code 2011 program. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in 16.\" the documentation and/or other materials provided with the 17.\" distribution. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 20.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 21.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 22.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 23.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 24.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, 25.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 26.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 27.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 28.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 29.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.Dd December 3, 2011 33.Dt RUN_QUERY 3 34.Os 35.Sh NAME 36.Nm run_query 37.Nd run a query against 38.Pa /var/db/man.db 39and process the results in a callback function. 40.Sh SYNOPSIS 41.In apropos-utils.h 42.Ft int 43.Fn run_query "sqlite3 *db" "const char **snippet_args" "query_args *args" 44.Sh DESCRIPTION 45The 46.Fn run_query 47function prepares the user supplied query in a form suitable to be run 48against 49.Pa /var/db/man.db 50and executes the query. 51For each row obtained in the result set, 52.Fn run_query 53will call the user supplied callback function, which should contain the 54logic for processing the data thus obtained. 55.Pp 56The 57.Fn run_query 58function takes following arguments: 59.Bl -tag -width 8n 60.It Fa sqlite3 *db 61Handle to the database connection which can be obtained by calling 62.Fn init_db . 63.It Fa const char *snippet_args 64An array of strings which specify the 65delimiters to the matching text in snippet. 66It is an optional argument and caller can supply a 67.Dv NULL 68value for it, in which case, a default value of 69.Brq \&"\&", \&"\&", \&"...\&" 70will be used. 71The 3 members of the array specify the following values: 72.Bl -enum -offset indent 73.It 74The first element marks the beginning of each matching token in the snippet. 75.It 76The second element the end of each matching token in the snippet. 77.It 78The third element is used to delimit the beginning and end of the snippet. 79.El 80For example for highlighting matching tokens in HTML style mark-up, use this 81value: 82.Bd -literal -offset indent 83 const char **snippet_args = { 84 "<b>", 85 "</b>", 86 "..." 87 }; 88.Ed 89.It Fa query_args *args 90.Ft query_args 91is a struct which is defined in 92.Pa apropos-utils.h . 93It has the following fields: 94.Bl -tag -width 8n -offset indent 95.It Li const char *search_str 96This is the query as entered by the user. 97You may want to pre-process it to do sanitization etc. 98.It Li int *sec_nums 99This is an array of 100.Ft int 101wherein each index element represents the 102section number in which search should be performed. 103The sections whose corresponding index element in this array is set to 104.Dv NULL 105are not searched. 106If all the elements in the array are 107.Dv 0 108then all the sections are searched. 109Alternatively pass 110.Dv NULL 111as to search in all the sections. 112.It Li int nrec 113This specifies the number of matching rows to fetch from the database. 114Specifiy a negative value to fetch all the matching rows. 115.It Li int offset 116This specifies the offset within the result-set. 117Use it to specify the position 118from where to start processing the result-set. 119For example if the value of nrec is m and value of offset is n, then the first 120n records from the result-set will be omitted and rest m-n (or less) records will 121be available for processing inside the callback. 122Use a negative value if you don't wish to offset any records. 123.It Li const char *machine 124The machine architecture to which the searches should be restricted. 125Specify NULL if the search should not be restricted a particular machine architecture. 126.It Li int (*callback) (void *, const char *, const char *, const char *,\ 127const char *, size_t) 128This is the callback function which will 129be called for each row retrieved from the database. 130The function should return a value of 0 on successful execution. 131A non-zero return value will indicate a failure and 132.Fn run_query 133will return. 134The interface of the callback function is described later in this section. 135.It Li void *callback_data 136Use this argument to pass any data to the callback function. 137It can be retrieved inside the callback function from its first argument. 138.It Li char **errmsg 139If an error occurs while fetching the data from the database, 140a human readable error message will be stored in 141.Fa errmsg . 142If no error occurs then 143.Fa errmsg 144will be set to 145.Dv NULL . 146In case 147.Fa errmsg 148is not 149.Dv NULL , 150then the caller should make sure to free it. 151.El 152.El 153.Pp 154The interface of the callback function is 155.Ft int 156.Fn (*callback) "void *callback_data" "const char *section" "const char *name"\ 157"const char *name_desc" "const char *snippet" "size_t snippet_length" 158.Pp 159Its arguments are: 160.Bl -column -offset indent "Function" "Argument Description" 161.It Li void *callback_data Ta This is the caller supplied data. 162.It Li const char *section Ta Ta \&It is the section number to which this man 163page belongs. 164.It Li const char *name Ta This is the name of the man page 165.It Li const char *name_desc Ta This is the one line description of this man 166page obtained from it's NAME section. 167.It Li const char *snippet Ta This is a snippet of the matching text from this 168man page. 169.It Li size_t snippet_length Ta This is the length of the snippet. 170.El 171.Sh RETURN VALUES 172On successful execution the 173.Fn run_query 174function will return 0 and in case of an error \-1 will be returned. 175.Sh FILES 176.Bl -hang -width /var/db/man.db -compact 177.It Pa /var/db/man.db 178The Sqlite FTS database which contains an index of the manual pages. 179.El 180.Sh EXAMPLES 181Following is a code excerpt of how 182.Pa apropos.c 183uses 184.Fn run_query . 185.Bd -literal -offset indent 186#include <apropos-utils.h> 187query_args args; 188char *errmsg = NULL; 189int *sec_nums = {0, 1, 1, 0, 0, 0, 0, 0, 0}; 190args.search_str = argv[1]; 191args.sec_nums = sec_nums; 192args.nrec = 10; 193args.offset = -1; 194args.machine = NULL; 195args.callback = &query_callback; 196args.callback_data = NULL; 197args.errmsg = &errmsg; 198if (run_query(db, NULL, &args) < 0) 199 errx(EXIT_FAILURE, "%s", errmsg); 200} 201 202free(query); 203free(errmsg); 204 205static int 206query_callback(void *data, const char *section, const char *name, 207 const char *name_desc, const char *snippet, size_t snippet_length ) 208{ 209 /* The user supplied data could be obtained as follows */ 210 // my_data *buf = (my_data *) data; 211 212 fprintf(stdout, "%s(%s)\t%s\en%s\en\en", name, section, name_desc, 213 snippet); 214 return 0; 215} 216.Ed 217.Sh SEE ALSO 218.Xr apropos-utils 3 , 219.Xr close_db 3 , 220.Xr init_db 3 , 221.Xr run_query_html 3 , 222.Xr run_query_pager 3 223.Sh AUTHORS 224.An Abhinav Upadhyay 225