run_query.3

.\" $NetBSD: run_query.3,v 1.2 2012/02/07 21:02:23 wiz Exp $
.\"
.\" Copyright (c) 2011 Abhinav Upadhyay <er.abhinav.upadhyay@gmail.com>
.\" All rights reserved.
.\"
.\" This code was developed as part of Google's Summer of Code 2011 program.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in
.\"    the documentation and/or other materials provided with the
.\"    distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd December 3, 2011
.Dt RUN_QUERY 3
.Os
.Sh NAME
.Nm run_query
.Nd run a query against
.Pa /var/db/man.db
and process the results in a callback function.
.Sh SYNOPSIS
.In apropos-utils.h
.Ft int
.Fn run_query "sqlite3 *db" "const char **snippet_args" "query_args *args"
.Sh DESCRIPTION
The
.Fn run_query
function prepares the user supplied query in a form suitable to be run
against
.Pa /var/db/man.db
and executes the query.
For each row obtained in the result set,
.Fn run_query
will call the user supplied callback function, which should contain the
logic for processing the data thus obtained.
.Pp
The
.Fn run_query
function takes following arguments:
.Bl -tag -width 8n
.It Fa sqlite3 *db
Handle to the database connection which can be obtained by calling
.Fn init_db .
.It Fa const char *snippet_args
An array of strings which specify the
delimiters to the matching text in snippet.
It is an optional argument and caller can supply a
.Dv NULL
value for it, in which case, a default value of
.Brq \&"\&", \&"\&", \&"...\&"
will be used.
The 3 members of the array specify the following values:
.Bl -enum -offset indent
.It
The first element marks the beginning of each matching token in the snippet.
.It
The second element the end of each matching token in the snippet.
.It
The third element is used to delimit the beginning and end of the snippet.
.El
For example for highlighting matching tokens in HTML style mark-up, use this
value:
.Bd -literal -offset indent
 const char **snippet_args = {
	"<b>",
	"</b>",
	"..."
 };
.Ed
.It Fa query_args *args
.Ft query_args
is a struct which is defined in
.Pa apropos-utils.h .
It has the following fields:
.Bl -tag -width 8n -offset indent
.It Li const char *search_str
This is the query as entered by the user.
You may want to pre-process it to do sanitization etc.
.It Li int *sec_nums
This is an array of
.Ft int
wherein each index element represents the
section number in which search should be performed.
The sections whose corresponding index element in this array is set to
.Dv NULL
are not searched.
If all the elements in the array are
.Dv 0
then all the sections are searched.
Alternatively pass
.Dv NULL
as to search in all the sections.
.It Li int nrec
This specifies the number of matching rows to fetch from the database.
Specifiy a negative value to fetch all the matching rows.
.It Li int offset
This specifies the offset within the result-set.
Use it to specify the position
from where to start processing the result-set.
For example if the value of nrec is m and value of offset is n, then the first
n records from the result-set will be omitted and rest m-n (or less) records will
be available for processing inside the callback.
Use a negative value if you don't wish to offset any records.
.It Li const char *machine
The machine architecture to which the searches should be restricted.
Specify NULL if the search should not be restricted a particular machine architecture.
.It Li int (*callback) (void *, const char *, const char *, const char *,\
const char *, size_t)
This is the callback function which will
be called for each row retrieved from the database.
The function should return a value of 0 on successful execution.
A non-zero return value will indicate a failure and
.Fn run_query
will return.
The interface of the callback function is described later in this section.
.It Li void *callback_data
Use this argument to pass any data to the callback function.
It can be retrieved inside the callback function from its first argument.
.It Li char **errmsg
If an error occurs while fetching the data from the database,
a human readable error message will be stored in
.Fa errmsg .
If no error occurs then
.Fa errmsg
will be set to
.Dv NULL .
In case
.Fa errmsg
is not
.Dv NULL ,
then the caller should make sure to free it.
.El
.El
.Pp
The interface of the callback function is
.Ft int
.Fn (*callback) "void *callback_data" "const char *section" "const char *name"\
"const char *name_desc" "const char *snippet" "size_t snippet_length"
.Pp
Its arguments are:
.Bl -column -offset indent "Function" "Argument Description"
.It Li void *callback_data Ta This is the caller supplied data.
.It Li const char *section Ta Ta \&It is the section number to which this man
page belongs.
.It Li const char *name Ta This is the name of the man page
.It Li const char *name_desc Ta This is the one line description of this man
page obtained from it's NAME section.
.It Li const char *snippet Ta This is a snippet of the matching text from this
man page.
.It Li size_t snippet_length Ta This is the length of the snippet.
.El
.Sh RETURN VALUES
On successful execution the
.Fn run_query
function will return 0 and in case of an error \-1 will be returned.
.Sh FILES
.Bl -hang -width /var/db/man.db -compact
.It Pa /var/db/man.db
The Sqlite FTS database which contains an index of the manual pages.
.El
.Sh EXAMPLES
Following is a code excerpt of how
.Pa apropos.c
uses
.Fn run_query .
.Bd -literal -offset indent
#include <apropos-utils.h>
query_args args;
char *errmsg = NULL;
int *sec_nums = {0, 1, 1, 0, 0, 0, 0, 0, 0};
args.search_str = argv[1];
args.sec_nums = sec_nums;
args.nrec = 10;
args.offset = -1;
args.machine = NULL;
args.callback = &query_callback;
args.callback_data = NULL;
args.errmsg = &errmsg;
if (run_query(db, NULL, &args) < 0)
		errx(EXIT_FAILURE, "%s", errmsg);
}

free(query);
free(errmsg);

static int
query_callback(void *data, const char *section, const char *name,
	const char *name_desc, const char *snippet, size_t snippet_length )
{
	/* The user supplied data could be obtained as follows */
	// my_data *buf = (my_data *) data;

	fprintf(stdout, "%s(%s)\t%s\en%s\en\en", name, section, name_desc,
		snippet);
	return 0;
}
.Ed
.Sh SEE ALSO
.Xr apropos-utils 3 ,
.Xr close_db 3 ,
.Xr init_db 3 ,
.Xr run_query_html 3 ,
.Xr run_query_pager 3
.Sh AUTHORS
.An Abhinav Upadhyay