All query operations in first more deals with common data structure, struct cdb, assotiated 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;

initializes structure given by cdbp pointer and assotiates it with opened file descriptor fd. Memory allocation for structure itself if needed and file open operation should be done by application. File fd should be opened at least read-only, and should be seekable. Routine returns 0 on success or negative value on error.

void cdb_free(cdbp)
   struct cdb *cdbp;

frees internal resources held by structure. Note that this routine does not closes a file.

int cdb_fileno(cdbp)
  const struct cdb *cdbp;

returns filedescriptor assotiated with cdb (as was passed to cdb_init()).

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;

reads a data from cdb file, starting at position pos of length len, placing result to buf. This routine may be used to get actual value found by cdb_find() or other routines that returns position and length of a data. Returns 0 on success or negative value on error. Routines cdb_readdata() and cdb_readkey() are shorthands to read current (after e.g. cdb_find()) data and key respectively, using cdb_read().

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

Internally, cdb library uses memory-mmaped region to access the on-disk database. cdb_get() allows to access internal memory in a way similar to cdb_read() but without extra copying and buffer allocation. Returns pointer to actual data on success or NULL on error (position points to outside of the database). Routines cdb_getdata() and cdb_getkey() are shorthands to access current (after e.g. cdb_find()) data and key respectively, using cdb_get().

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;

attempts to find a key given by (key,klen) parameters. If key exists in database, routine returns 1 and places position and length of value assotiated with this key to internal fields inside cdbp structure, to be accessible by cdb_datapos(cdbp) and cdb_datalen(cdbp) routines. If key is not in database, cdb_find() returns 0. On error, negative value is returned. Data pointers (available via cdb_datapos() and cdb_datalen()) gets updated only in case of successeful search. Note that using cdb_find() it is possible to lookup only first record with a given key.

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

sequential-find routines that used separate structure. It is possible to have many than one record with the same key in a database, and these routines allows to enumerate all them. cdb_findinit() initializes search structure pointed to by cdbfp. It will return negative value on error or non-negative value on success. cdb_findnext() attempts to find next (first when called right after cdb_findinit()) matching key, setting value position and length in cdbfp structure. It will return positive value if given key was found, 0 if there is no more such key(s), or negative value on error. To access value position and length after successeful call to cdb_findnext() (when it returned positive result), use cdb_datapos(cdbp) and cdb_datalen(cdbp) routines. It is error to continue using cdb_findnext() after it returned 0 or error condition (cdb_findinit() should be called again). Current data pointers (available via cdb_datapos() and cdb_datalen()) gets updated only on successeful search.

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

sequential enumeration of all records stored in cdb file. cdb_seqinit() initializes access current data pointer cptr to point before first record in a cdb file. cdb_seqnext() updates data pointers in cdbp to point to the next record and updates cptr, returning positive value on success, 0 on end of data condition and negative value on error. Current record will be available after successeful operation using cdb_datapos(cdbp) and cdb_datalen(cdbp) (for the data) and cdb_keypos(cdbp) and cdb_keylen(cdbp) (for the key of the record). Data pointers gets updated only in case of successeful operation.

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;

searches a cdb database (as pointed to by fd filedescriptor) for a key given by (key, klen), and positions file pointer to start of data assotiated with that key if found, so that next read operation from this filedescriptor will read that value, and places length of value, in bytes, to variable pointed to by dlenp. Returns positive value if operation was successeful, 0 if key was not found, or negavive value on error. To read the data from a cdb file, cdb_bread() routine below can be used.

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

reads data from a file (as pointed to by fd filedescriptor) and places len bytes from this file to a buffer pointed to by buf. Returns 0 if exactly len bytes was read, or a negative value in case of error or end-of-file. This routine ignores interrupt errors (EINTR). Sets errno variable to EIO in case of end-of-file condition (when there is less than len bytes available to read).

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 succed 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.

 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(&cdb, &cpos); n = 0; while(cdb_seqnext(&cdb, &cpos) > 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);

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