qlibs:cdbread(3)

🌸 NAME 🌸

okay bestie, this is the qlibs:cdbread(3) page — we're talking about cdbread, and its whole thing is: fetch information from a constant database. iconic, honestly 💖

✨ SYNTAX ✨

here's the include and the whole cast, copied exactly because signatures are sacred 🫶

#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. and no cap: 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. lowkey tidy of it ✨

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. bestie, check your lengths fr fr 😭

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. it's giving setup first, search second 💫

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.

🚨 undefined behavior alert: fewer than n-1 such records means cdb_findnext has no promised behavior. do not make it the main character of your error handling, bestie 💀

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. so like… only peek at those results after a 1, iykyk 👑

cdb_find is the same as cdb_findstart followed by cdb_findnext: it finds the first record under key. one-stop first-record slay 🎀

cdb_datapos and cdb_datalen are macros pointing to the found information following key in the cdb and returning their length. yes, macros — they're little shortcuts, not whole extra functions 🌈

🦋 EXAMPLE 🦋

here's the example, verbatim, because code deserves to stay exactly as written:

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

🌟 SEE ALSO 🌟

• cdbmake(3)

---

mwah 💖 signing off from the footer: source/version is qlibs:cdbread(3), and the page doesn't print a date — so I'm not making one up, bestie 💅✨