DBM(3)

💾 DBM(3) — the Unix manual, but make it make sense ✨

okay so bestie, welcome to the Library Functions Manual moment of your life 💅 this whole page is about the dbm_* squad — a bunch of database access functions that live in <ndbm.h> and are literally built on top of dbopen(3) with a hash(3) database underneath. iykyk. let's get into it 🫶

---

🌸 NAME 🌸

dbm_clearerr, dbm_close, dbm_delete, dbm_dirfno, dbm_error, dbm_fetch, dbm_firstkey, dbm_nextkey, dbm_open, dbm_store — the database access functions, aka the whole friend group 💖

---

🎀 SYNOPSIS 🎀

here's the whole squad's signatures, no cap:

#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 ✨

so these are the database access functions, and the tea is they're implemented using dbopen(3) with a hash(3) database. iconic behavior honestly 🔥

datum is declared in <ndbm.h> and it's giving very simple struct energy:

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

🦋 dbm_open(base, flags, mode) 🦋

this one opens or creates a database, main character energy fr. the base argument is the basename of the file containing the database — and the actual database has a .db suffix. so like, if base is "/home/me/mystuff" then the actual database is in the file /home/me/mystuff.db. yes bestie, the .db is automatic 💅

the flags and mode arguments get passed straight to open(2), no thoughts just vibes. (O_RDWR | O_CREAT) is a typical value for flags, and 0660 is a typical value for mode. the pointer that dbm_open() returns identifies the database and becomes the db argument for all the other functions. and if anything goes wrong? dbm_open() returns NULL and sets errno, tragic but at least you know 😭

🧚 dbm_close(db) 🧚

closes the database. that's it. that's the tweet. short and sweet 🎀

🌈 dbm_store(db, key, data, flags) 🌈

inserts or replaces an entry in the database. the flags argument is either DBM_INSERT or DBM_REPLACE. here's the nuance bestie: 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, depending on the flag.

dbm_store() 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) — so like a "no thanks, already got one" situation. or it returns -1 and sets errno if there were any errors 💀

🍓 dbm_fetch(db, key) 🍓

returns NULL or the data corresponding to key. simple as that, lowkey underrated ✨

💜 dbm_delete(db, key) 💜

deletes the entry for key. normally returns zero, or returns -1 and sets errno if there were any errors. bye bye entry 👋

⭐ dbm_firstkey(db) and dbm_nextkey(db) ⭐

dbm_firstkey(db) returns the first key in the database, and dbm_nextkey(db) returns subsequent keys. important detail bestie: the db_firstkey() function must be called before dbm_nextkey(). the order in which keys are returned is unspecified and may appear random (so don't come for it, it's just quirky like that 🙈). dbm_nextkey() returns NULL after all keys have been returned — that's your cue that you're done 🏁

💀 dbm_error(db) and dbm_clearerr(db) 💀

dbm_error(db) returns the errno value of the most recent error. dbm_clearerr(db) resets this value to 0 and returns 0. clean slate energy ✨

🌸 dbm_dirfno(db) 🌸

returns the file descriptor to the database. that's the whole function, she's a one-liner and she knows it 💅

---

👀 SEE ALSO 👀

open(2), dbopen(3), hash(3) — go read those too bestie, they're part of the lore 🫶

---

📜 STANDARDS 📜

these functions (except dbm_dirfno()) are included in Version 2 of the Single UNIX Specification (aka “SUSv2”). so like, they're officially official 💖

---

🕰️ HISTORY 🕰️

the functions dbminit(), fetch(), store(), delete(), firstkey(), and nextkey() first appeared in Version 7 AT&T UNIX. old money, historic behavior, we love a legacy queen 👑

---

⚠️ quick vibe check bestie: this page is the real deal from the Library Functions Manual, brought to you by Debian, dated July 25, 2025. that's the whole tea. now go forth and use dbm_* responsibly, mwah 💋