NAME

cdb - read a constant database

SYNOPSIS

#include "cdb.h"

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);

DESCRIPTION

You can read records in a constant database from file descriptor fd as follows:

• Use cdb_init to place information about fd into a struct cdb variable c.

• Carry out any number of searches, as described below.

• Use cdb_free to remove any memory map that might have been reserved by cdb_init.

Each search works as follows:

• Use cdb_find to search for a record under key k. If cdb_find returns 0, the database does not contain that key; stop. If cdb_find returns -1, there was a read error; abort.

• Use cdb_datalen to find the number of bytes of data in this record. Allocate a pointer d to a region of memory large enough to hold the data. If not enough memory is available, abort.

• Use cdb_read with cdb_datapos to read the data. If cdb_read returns -1, there was a read error; abort.

• Do something with the data, and then free the allocated region of memory.

There may be several records under a single key. You can use cdb_findnext to find the next record under this key.

DETAILS

A struct cdb variable such as c is either unallocated or allocated. If it is allocated, it holds information about a constant database:

• a file descriptor fd reading from the database;

• if convenient, a shared memory map reading from the database; and

• information about a search in progress.

c must be initialized to zero, meaning unallocated.

cdb_free unallocates c if c is allocated. Otherwise it leaves c alone. cdb_free does not close fd.

cdb_init allocates c to hold information about a constant database read by descriptor fd. You may call cdb_init repeatedly; if c is already allocated, cdb_init unallocates it first.

cdb_read reads dlen bytes into d from byte position dpos in the database. You must allocate c before calling cdb_read. Normally cdb_read returns 0. If the database file is shorter than dpos+dlen bytes, or if there is a disk read error, cdb_read returns -1, setting errno appropriately.

cdb_findstart prepares c to search for the first record under a new key. You must allocate c before calling cdb_findstart, and you must call cdb_findstart before calling cdb_findnext.

cdb_findnext looks for the nth record under key k in the database, where n is the number of calls to cdb_findnext after the most recent call to cdb_findstart. If it finds the record, cdb_findnext returns 1; if there are exactly n-1 such records, cdb_findnext returns 0; if there are fewer than n-1 such records, the behavior of cdb_findnext is undefined; if there is a database format error or disk error, cdb_findnext returns -1, setting errno appropriately. Each call to cdb_findnext (before another call to cdb_findstart) must use the same k and klen.

If cdb_findnext returns 1, it arranges for cdb_datapos to return the starting byte position of the data in the record, and for cdb_datalen to return the number of bytes of data in the record. Otherwise the results of cdb_datapos and cdb_datalen are undefined.

cdb_find is the same as cdb_findstart followed by cdb_findnext: it finds the first record under key k.

Beware that these functions may rely on non-atomic operations on the fd ofile, such as seeking to a particular position and then reading. Do not attempt two simultaneous database reads using a single ofile.

SEE ALSO

cdbget(1)

---

Version: This is version 2025.10.21 of the "Read API" web page.