run_query - run a query against /var/db/man.db and process the results in a callback function.


int run_query(sqlite3 *db, const char **snippet_args, query_args *args)


The run_query() function prepares the user supplied query in a form suitable to be run against /var/db/man.db and executes the query. For each row obtained in the result set, run_query() will call the user supplied callback function, which should contain the logic for processing the data thus obtained.

The run_query() function takes following arguments:

sqlite3 *db
Handle to the database connection which can be obtained by calling init_db().

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 NULL value for it, in which case, a default value of {"", "", "..."} will be used. The 3 members of the array specify the following values:

  1. The first element marks the beginning of each matching token in the snippet.

  2. The second element the end of each matching token in the snippet.

  3. The third element is used to delimit the beginning and end of the snippet.
For example for highlighting matching tokens in HTML style mark-up, use this value:
 const char **snippet_args = {

query_args *args

query_args is a struct which is defined in apropos-utils.h. It has the following fields:

const char *search_str
This is the query as entered by the user. You may want to pre-process it to do sanitization etc.

const char **sec_nums
This is an array of

char * 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 NULL are not searched. If all the elements in the array are NULL then all the sections are searched.

const char *nrec
This specifies the number of matching rows to fetch from the database.

int (*callback) (void *, int, char **, char **)
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 run_query() will return. The interface of the callback function is described later in this section.

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.

char **errmsg
If an error occurs while fetching the data from the database, a human readable error message will be stored in errmsg. If no error occurs then errmsg will be set to NULL. In case errmsg is not NULL, then the caller should make sure to free it.

The interface of the callback function is

int (*callback)(void *callback_data, int ncol, char **col_values, char **col_names).

Its arguments are:

void *callback_data This is the caller supplied data.
int ncol It represents the number of columns in the result set.
char **col_values This is an array of strings, where each index element represents the value of the correspondingly indexed column in the result set.
char **col_names This array stores the name of the columns whose values have been fetched from the database.
The query which run_query() results in a 5 column result set. Those are as follows:
section The section number of the page.
name The name of the page.
snippet The snippet of the matching text in the page.
name_desc The one line description from the NAME section.
rank A double value indicating rank/weight of the page.


On successful execution the run_query() function will return 0 and in case of an error -1 will be returned.


The Sqlite FTS database which contains an index of the manual pages.


Following is a code excerpt of how apropos.c uses run_query().
query_args args;
char *errmsg = NULL;
const char **sec_nums = {NULL, "2", "3", NULL, NULL, NULL, NULL, NULL, NULL};
args.search_str = argv[1];
args.sec_nums = sec_nums;
args.nrec = "10";
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, int ncol, char **col_values, char **col_names) { char *section = col_values[0]; char *name = col_values[1]; char *snippet = col_values[2]; char *name_desc = col_values[3]; /* The user supplied data could be obtained as follows */ // my_data *buf = (my_data *) data;

fprintf(stdout, "%s(%s)%s\n%s\n\n", name, section, name_desc, snippet); return 0; }


apropos-utils(3), close_db(3), init_db(3), run_query_html(3), run_query_pager(3)


Abhinav Upadhyay

Get NetBSD Summer of Code projects at Fast, secure and Free Open Source software downloads
Abhinav Upadhyay <er.abhinav.upadhyay at gmail dot com>
$Id: run_query.html3,v 1.2 2011/08/25 06:52:59 abhinavupadhyay Exp $