RUN_QUERY(3)

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

SYNOPSIS
#include <apropos-utils.h>
int
run_query(sqlite3 *db, query_format fmt, 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().

query_format fmt
    An enum value indicating the output format. Currently you can specify following values:

    APROPOS_PAGER

    APROPOS_TERM

    APROPOS_HTML

    APROPOS_NONE

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.

    int *sec_nums
        This is an array of 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 NULL are not searched. If all the elements in the array are 0 then all the sections are searched. Alternatively pass NULL as to search in all the sections.

    int nrec
        This specifies the number of matching rows to fetch from the database. Specify a negative value to fetch all the matching rows.

    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.

    int legacy
        If the output should be in legacy format (similary to classic apropos).

    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.

    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 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, const char *section, const char *name"const char *name_desc, const char *snippet, size_t snippet_length)

Its arguments are:
void *callback_data | This is the caller supplied data.
const char *section | | It is the section number to which this man
page belongs.
const char *name | This is the name of the man page
const char *name_desc | This is the one line description of this man
page obtained from its NAME section.
const char *snippet | This is a snippet of the matching text from this
man page.
size_t snippet_length | This is the length of the snippet.

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 <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)	%s\n%s\n\n", name, section, name_desc,
    		snippet);
    	return 0;
    }

SEE ALSO
apropos-utils(3), close_db(3), init_db(3)

AUTHORS
Abhinav Upadhyay