107 lines
3.4 KiB
Groff
107 lines
3.4 KiB
Groff
.\" $NetBSD: run_query_pager.3,v 1.2 2012/02/07 21:02:33 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_PAGER 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm run_query_pager
|
|
.Nd run a query against
|
|
.Pa /var/db/man.db
|
|
and returns the results in a format which can be piped to a pager
|
|
.Sh SYNOPSIS
|
|
.In apropos-utils.h
|
|
.Ft int
|
|
.Fn run_query_pager "sqlite3 *db" "query_args *args"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Fn run_query_pager
|
|
is very similar to
|
|
.Xr run_query_html 3
|
|
with the only difference that the snippet returned is formatted in a manner so
|
|
that the matching text in it appears highlighted when viewed using a pager.
|
|
.Pp
|
|
For more details, refer to the manual page of
|
|
.Xr run_query 3 .
|
|
.Sh RETURN VALUES
|
|
On successful execution the
|
|
.Fn run_query_pager
|
|
function will return 0 and in case of an error \-1 will be returned.
|
|
.Sh FILES
|
|
.Bl -hang -width -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
|
|
.Nm
|
|
can be used.
|
|
.Bd -literal -offset indent
|
|
#include <apropos-utils.h>
|
|
query_args args;
|
|
FILE *pager = popen("more", "w");
|
|
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 = -1; //A negative value means fetch all matching records
|
|
args.offset = -1;
|
|
args.machine = NULL;
|
|
args.callback = &query_callback;
|
|
args.callback_data = (void *)pager;
|
|
args.errmsg = &errmsg;
|
|
if (run_query(db, &args) < 0)
|
|
errx(EXIT_FAILURE, "%s", errmsg);
|
|
}
|
|
|
|
free(query);
|
|
free(errmsg);
|
|
pclose(pager);
|
|
|
|
static int
|
|
query_callback(void *data, const char *section, const char *name,
|
|
const char *name_desc, const char *snippet, size_t snippet_length)
|
|
{
|
|
FILE *out = (FILE *) data;
|
|
fprintf(out, "%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 3 ,
|
|
.Xr run_query_html 3
|
|
.Sh AUTHORS
|
|
.An Abhinav Upadhyay
|