209 lines
6.8 KiB
Groff
209 lines
6.8 KiB
Groff
.\" $NetBSD: run_query.3,v 1.4 2016/05/24 18:06:42 abhinav 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 May 23, 2016
|
|
.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" "query_format fmt" "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 query_format fmt
|
|
An enum value
|
|
indicating the output format.
|
|
Currently you can specify following values:
|
|
.Bl -hang -width compact
|
|
.It Dv APROPOS_PAGER
|
|
.It Dv APROPOS_TERM
|
|
.It Dv APROPOS_HTML
|
|
.It Dv APROPOS_NONE
|
|
.El
|
|
.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 int legacy
|
|
If the output should be in legacy format (similary to classic apropos).
|
|
.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 its 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, APROPOS_PAGER, &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
|
|
.Sh AUTHORS
|
|
.An Abhinav Upadhyay
|