August 17, 2011 RUN

NAME

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

SYNOPSIS

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

DESCRIPTION

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:

The first element marks the beginning of each matching token in the snippet.
The second element the end of each matching token in the snippet.
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.`

RETURN VALUES

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

FILES

/var/db/man.db: The Sqlite FTS database which contains an index of the manual pages.

EXAMPLES

Following is a code excerpt of how apropos.c uses run_query().


#include 
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;
}

AUTHORS

Abhinav Upadhyay

Abhinav Upadhyay <er.abhinav.upadhyay at gmail dot com>

$Id: run_query.html3,v 1.2 2011/08/25 06:52:59 abhinavupadhyay Exp $