Query Mode 1

All query operations in first more deals with common data structure, struct cdb, associated with an open file descriptor. This structure is opaque to application.

The following routines exists for accessing cdb database:

int cdb_init(cdbp, fd)
   struct cdb *cdbp;
   int fd;

void cdb_free(cdbp)
   struct cdb *cdbp;

int cdb_fileno(cdbp)
  const struct cdb *cdbp;

int cdb_read(cdbp, buf, len, pos)
int cdb_readdata(cdbp, buf, len, pos)
int cdb_readkey(cdbp, buf, len, pos)
   const struct cdb *cdbp;
   void *buf;
   unsigned len;
   unsigned pos;

const void *cdb_get(cdbp, len, pos)
const void *cdb_getdata(cdbp)
const void *cdb_getkey(cdbp)
   const struct cdb *cdbp;
   unsigned len;
   unsigned pos;

int cdb_find(cdbp, key, klen)
unsigned cdb_datapos(cdbp)
unsigned cdb_datalen(cdbp)
unsigned cdb_keypos(cdbp)
unsigned cdb_keylen(cdbp)
   struct cdb *cdbp;
   const void *key;
   unsigned klen;

int cdb_findinit(cdbfp, cdbp, key, klen)
int cdb_findnext(cdbfp)
  struct cdb_find *cdbfp;
  const struct cdb *cdbp;
  const void *key;
  unsigned klen;

void cdb_seqinit(cptr, cdbp)
int cdb_seqnext(cptr, cdbp)
  unsigned *cptr;
  struct cdb *cdbp;

Query Mode 2

In this mode, one need to open a cdb file using one of standard system calls (such as open(2)) to obtain a filedescriptor, and then pass that filedescriptor to cdb routines. Available methods to query a cdb database using only a filedescriptor include:

int cdb_seek(fd, key, klen, dlenp)
  int fd;
  const void *key;
  unsigned klen;
  unsigned *dlenp;

int cdb_bread(fd, buf, len)
  int fd;
  void *buf;
  int len;

Notes

Note that value of any given key may be updated in place by another value of the same size, by writing to file at position found by cdb_find() or cdb_seek(). However one should be very careful when doing so, since write operation may not succeed in case of e.g. power failure, thus leaving corrupted data. When database is (re)created, one can guarantee that no incorrect data will be written to database, but not with inplace update. Note also that it is not possible to update any key or to change length of value.

Query Mode

 int fd;
 struct cdb cdb;
 char *key, *data;
 unsigned keylen, datalen;
 /* opening the database */
 fd = open(filename, O_RDONLY);
 cdb_init(&cdb, fd);
 /* initialize key and keylen here */
 /* single-record search. */
 if (cdb_find(&cdb, key, keylen) > 0) {
   datalen = cdb_datalen(&cdb);
   data = malloc(datalen + 1);
   cdb_read(&cdb, data, datalen, cdb_datapos(&cdb));
   data[datalen] = '\0';
   printf("key=%s data=%s\n", key, data);
   free(data);
 }
 else
   printf("key=%s not found\n", key);
 /* multiple record search */
 struct cdb_find cdbf;
 int n;
 cdb_findinit(&cdbf, &cdb, key, keylen);
 n = 0;
 while(cdb_findnext(&cdbf) > 0) {
   datalen = cdb_datalen(&cdb);
   data = malloc(datalen + 1);
   cdb_read(&cdb, data, datalen, cdb_datapos(&cdb));
   data[datalen] = '\0';
   printf("key=%s data=%s\n", key, data);
   free(data);
   ++n;
 }
 printf("key=%s %d records found\n", n);
 /* sequential database access */
 unsigned pos;
 int n;
 cdb_seqinit(&pos, &cdb);
 n = 0;
 while(cdb_seqnext(&pos, &cdb) > 0) {
   keylen = cdb_keylen(&cdb);
   key = malloc(keylen + 1);
   cdb_read(&cdb, key, keylen, cdb_keypos(&cdb));
   key[keylen] = '\0';
   datalen = cdb_datalen(&cdb);
   data = malloc(datalen + 1);
   cdb_read(&cdb, data, datalen, cdb_datapos(&cdb));
   data[datalen] = '\0';
   ++n;
   printf("record %n: key=%s data=%s\n", n, key, data);
   free(data); free(key);
 }
 printf("total records found: %d\n", n);
 /* close the database */
 cdb_free(&cdb);
 close(fd);
 /* simplistic query mode */
 fd = open(filename, O_RDONLY);
 if (cdb_seek(fd, key, keylen, &datalen) > 0) {
   data = malloc(datalen + 1);
   cdb_bread(fd, data, datalen);
   data[datalen] = '\0';
   printf("key=%s data=%s\n", key, data);
 }
 else
   printf("key=%s not found\n", key);
 close(fd);

Create Mode

 int fd;
 struct cdb_make cdbm;
 char *key, *data;
 unsigned keylen, datalen;
 /* initialize the database */
 fd = open(filename, O_RDWR|O_CREAT|O_TRUNC, 0644);
 cdb_make_start(&cdbm, fd);
 while(have_more_data()) {
   /* initialize key and data */
   if (cdb_make_exists(&cdbm, key, keylen) == 0)
     cdb_make_add(&cdbm, key, keylen, data, datalen);
   /* or use cdb_make_put() with appropriate flags */
 }
 /* finalize and close the database */
 cdb_make_finish(&cdbm);
 close(fd);