-rw-r--r-- 5008 cdb-20251021/doc/man/cdb.3 raw
.\" Automatically generated by Pandoc 2.17.1.1
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "cdb" "3" "" "" ""
.hy
.SS NAME
.PP
cdb - read a constant database
.SS SYNOPSIS
.IP
.nf
\f[C]
#include \[dq]cdb.h\[dq]

static struct cdb c;
num fd;

char *k;
num klen;
num result;

char *d;
num dlen;
num dpos;

cdb_init(&c,fd);
result = cdb_find(&c,k,klen);

/* optional decomposition of cdb_find: */
   cdb_findstart(&c);
   result = cdb_findnext(&c,k,klen);

dlen = cdb_datalen(&c);
dpos = cdb_datapos(&c);
result = cdb_read(&c,d,dlen,dpos);

cdb_free(&c);
\f[R]
.fi
.SS DESCRIPTION
.PP
You can read records in a constant database from file descriptor
\f[V]fd\f[R] as follows:
.IP \[bu] 2
Use \f[V]cdb_init\f[R] to place information about \f[V]fd\f[R] into a
\f[V]struct cdb\f[R] variable \f[V]c\f[R].
.IP \[bu] 2
Carry out any number of searches, as described below.
.IP \[bu] 2
Use \f[V]cdb_free\f[R] to remove any memory map that might have been
reserved by \f[V]cdb_init\f[R].
.PP
Each search works as follows:
.IP \[bu] 2
Use \f[V]cdb_find\f[R] to search for a record under key \f[V]k\f[R].
If \f[V]cdb_find\f[R] returns \f[V]0\f[R], the database does not contain
that key; stop.
If \f[V]cdb_find\f[R] returns \f[V]-1\f[R], there was a read error;
abort.
.IP \[bu] 2
Use \f[V]cdb_datalen\f[R] to find the number of bytes of data in this
record.
Allocate a pointer \f[V]d\f[R] to a region of memory large enough to
hold the data.
If not enough memory is available, abort.
.IP \[bu] 2
Use \f[V]cdb_read\f[R] with \f[V]cdb_datapos\f[R] to read the data.
If \f[V]cdb_read\f[R] returns \f[V]-1\f[R], there was a read error;
abort.
.IP \[bu] 2
Do something with the data, and then free the allocated region of
memory.
.PP
There may be several records under a single key.
You can use \f[V]cdb_findnext\f[R] to find the next record under this
key.
.SS DETAILS
.PP
A \f[V]struct cdb\f[R] variable such as \f[V]c\f[R] is either
unallocated or allocated.
If it is allocated, it holds information about a constant database:
.IP \[bu] 2
a file descriptor \f[V]fd\f[R] reading from the database;
.IP \[bu] 2
if convenient, a shared memory map reading from the database; and
.IP \[bu] 2
information about a search in progress.
.PP
\f[V]c\f[R] must be initialized to zero, meaning unallocated.
.PP
\f[V]cdb_free\f[R] unallocates \f[V]c\f[R] if \f[V]c\f[R] is allocated.
Otherwise it leaves \f[V]c\f[R] alone.
\f[V]cdb_free\f[R] does not close \f[V]fd\f[R].
.PP
\f[V]cdb_init\f[R] allocates \f[V]c\f[R] to hold information about a
constant database read by descriptor \f[V]fd\f[R].
You may call \f[V]cdb_init\f[R] repeatedly; if \f[V]c\f[R] is already
allocated, \f[V]cdb_init\f[R] unallocates it first.
.PP
\f[V]cdb_read\f[R] reads \f[V]dlen\f[R] bytes into \f[V]d\f[R] from byte
position \f[V]dpos\f[R] in the database.
You must allocate \f[V]c\f[R] before calling \f[V]cdb_read\f[R].
Normally \f[V]cdb_read\f[R] returns \f[V]0\f[R].
If the database file is shorter than \f[V]dpos+dlen\f[R] bytes, or if
there is a disk read error, \f[V]cdb_read\f[R] returns \f[V]-1\f[R],
setting \f[V]errno\f[R] appropriately.
.PP
\f[V]cdb_findstart\f[R] prepares \f[V]c\f[R] to search for the first
record under a new key.
You must allocate \f[V]c\f[R] before calling \f[V]cdb_findstart\f[R],
and you must call \f[V]cdb_findstart\f[R] before calling
\f[V]cdb_findnext\f[R].
.PP
\f[V]cdb_findnext\f[R] looks for the nth record under key \f[V]k\f[R] in
the database, where \f[V]n\f[R] is the number of calls to
\f[V]cdb_findnext\f[R] after the most recent call to
\f[V]cdb_findstart\f[R].
If it finds the record, \f[V]cdb_findnext\f[R] returns 1; if there are
exactly \f[V]n-1\f[R] such records, \f[V]cdb_findnext\f[R] returns
\f[V]0\f[R]; if there are fewer than \f[V]n-1\f[R] such records, the
behavior of \f[V]cdb_findnext\f[R] is undefined; if there is a database
format error or disk error, \f[V]cdb_findnext\f[R] returns \f[V]-1\f[R],
setting \f[V]errno\f[R] appropriately.
Each call to \f[V]cdb_findnext\f[R] (before another call to
\f[V]cdb_findstart\f[R]) must use the same \f[V]k\f[R] and
\f[V]klen\f[R].
.PP
If \f[V]cdb_findnext\f[R] returns 1, it arranges for
\f[V]cdb_datapos\f[R] to return the starting byte position of the data
in the record, and for \f[V]cdb_datalen\f[R] to return the number of
bytes of data in the record.
Otherwise the results of \f[V]cdb_datapos\f[R] and \f[V]cdb_datalen\f[R]
are undefined.
.PP
\f[V]cdb_find\f[R] is the same as \f[V]cdb_findstart\f[R] followed by
\f[V]cdb_findnext\f[R]: it finds the first record under key \f[V]k\f[R].
.PP
Beware that these functions may rely on non-atomic operations on the
\f[V]fd\f[R] ofile, such as seeking to a particular position and then
reading.
Do not attempt two simultaneous database reads using a single ofile.
.SS SEE ALSO
.PP
\f[B]cdbget\f[R](1)