qlibs:cdbread

Section: C Library Functions (3)
Index Return to Main Contents

NAME

cdbread - fetch information from a constant database

SYNTAX

#include "cdbread.h"

void cdb_init(struct cdb *c,int fd);
int cdb_read(struct cdb *c,char *data,unsigned int dlen,uint32 pos);
int cdb_findstart(int fd,char *key,unsigned int len);
int cdb_findnext(int fd,char *key,unsigned int len);
int cdb_find(int fd,char *ney,unsigned int len);

int cdb_findnext(int fd,char *key,unsigned int len);
void cdb_free(struct cdb *c):

DESCRIPTION

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

cdb_datapos and cdb_datalen are macros pointing to the found information following key in the cdb and returning their length.

EXAMPLE

#include <cdbread.h>

  int fd;
  char *data;
  unsigned int len;
  stralloc key = {0};

static struct cdb c;

cdb_init(&c,fd);

  switch (cdb_find(&c,key.s,key.len)) {
    case -1: return -1;
    case  0: return 0;
  }

  len = cdb_datalen(&c);
  data = alloc(len);
  if (!data) return -1;

  if (cdb_read(&c,data,datalen,cdb_datapos(&c)) == -1) {
    alloc_free(data);
    return -1;
  }

cdb_free(&c);