DBM(3)

okay bestie, welcome to DBM(3) from the Library Functions Manual 🫶💾 this is literally the database access functions, and we’re about to make old-school Unix feel like a group chat. no cap.

✨ NAME ✨

dbm_clearerr, dbm_close, dbm_delete, dbm_dirfno, dbm_error, dbm_fetch, dbm_firstkey, dbm_nextkey, dbm_open, dbm_store — database access functions. periodt 💅

📜 SYNOPSIS 📜

#include <fcntl.h>
#include <ndbm.h>

DBM *
dbm_open(const char *base, int flags, mode_t mode);

void
dbm_close(DBM *db);

int
dbm_store(DBM *db, datum key, datum data, int flags);

datum
dbm_fetch(DBM *db, datum key);

int
dbm_delete(DBM *db, datum key);

datum
dbm_firstkey(DBM *db);

datum
dbm_nextkey(DBM *db);

int
dbm_error(DBM *db);

int
dbm_clearerr(DBM *db);

int
dbm_dirfno(DBM *db);

🌸 DESCRIPTION 🌸

Database access functions. These functions are implemented using dbopen(3) with a hash(3) database. iykyk 💖

datum is declared in <ndbm.h>:

typedef struct {
        void *dptr;
        int dsize;
} datum;

okay so the dbm_open(base, flags, mode) function opens or creates a database. The base argument is the basename of the file containing the database; the actual database has a .db suffix. I.e., if base is /home/me/mystuff then the actual database is in the file /home/me/mystuff.db. The flags and mode arguments are passed to open(2). (O_RDWR | O_CREAT) is a typical value for flags; 0660 is a typical value for mode.

bestie, O_WRONLY is not allowed in flags 🚫

The pointer returned by dbm_open() identifies the database and is the db argument to the other functions. The dbm_open() function returns NULL and sets errno if there were any errors.

The dbm_close(db) function closes the database. bye-bye database 👋

The dbm_store(db, key, data, flags) function inserts or replaces an entry in the database. The flags argument is either DBM_INSERT or DBM_REPLACE. If flags is DBM_INSERT and the database already contains an entry for key, that entry is not replaced. Otherwise the entry is replaced or inserted. The dbm_store() function normally returns zero but returns 1 if the entry could not be inserted (because flags is DBM_INSERT, and an entry with key already exists) or returns -1 and sets errno if there were any errors. slay or cry, no in-between 😭

The dbm_fetch(db, key) function returns NULL or the data corresponding to key. literally the data retrieval moment ✨

The dbm_delete(db, key) function deletes the entry for key. The dbm_delete() function normally returns zero or returns -1 and sets errno if there were any errors.

The dbm_firstkey(db) function returns the first key in the database. The dbm_nextkey(db) function returns subsequent keys. The db_firstkey() function must be called before dbm_nextkey(). The order in which keys are returned is unspecified and may appear random. The dbm_nextkey() function returns NULL after all keys have been returned. yes, that’s db_firstkey() — no m — the page said it, not me 😭

The dbm_error(db) function returns the errno value of the most recent error. The dbm_clearerr(db) function resets this value to 0 and returns 0.

The dbm_dirfno(db) function returns the file descriptor to the database. file descriptor reveal 💅

🔗 SEE ALSO 🔗

open(2), dbopen(3), hash(3) — go read these too, bestie 💖

📏 STANDARDS 📏

These functions (except dbm_dirfno()) are included in the Version 2 of the Single UNIX Specification (“SUSv2”). iconic standardization behavior 👑

🕰️ HISTORY 🕰️

The functions dbminit(), fetch(), store(), delete(), firstkey(), and nextkey() first appeared in Version 7 AT&T UNIX. vintage Unix lore fr fr 🦋

---

that’s the whole page, bestie 🎀 source/version: Debian; date: April 2, 2022. mwah 💋