SNOBOL4NDBM(3)

🦋 SNOBOL4NDBM(3) 🦋

okay bestie, sit down, hydrate, because we're talking about the CSNOBOL4 Manual page for snobol4ndbm — the NDBM interface for SNOBOL4. it's giving database, it's giving hashed storage, it's giving ✨vintage Unix royalty✨. let's go 💅

---

✨ NAME ✨

snobol4ndbm — the SNOBOL4 NDBM interface 🫶

---

🌸 SYNOPSIS 🌸

        -INCLUDE 'ndbm.sno'
                dbhandle = DBM_OPEN(file,flags,mode)
                DBM_CLOSE(dbhandle)
                DBM_STORE(dbhandle,key,datum,flags)
                datum = DBM_FETCH(dbhandle,key)
                DBM_DELETE(dbhandle,key)
                key = DBM_FIRSTKEY(dbhandle)
                key = DBM_NEXTKEY(dbhandle)
                DBM_ERROR(dbhandle)
                DBM_CLEARERR(dbhandle)

---

💜 DESCRIPTION 💜

okay so "NDBM" stands for New Data Base Management (yes, really, that's the name, we don't make the rules) and it's an industry standard fast hashed storage API that was first created in 4.3BSD, and it got included in the Unix 98 (SUSv2) standard. iconic behavior honestly 👑

fun little lore drop: the original DBM API showed up in AT&T Research Unix Version 7, and it only let you touch a single file at a time. one file. that's it. tragic.

there are so many different implementations of this API out there, including:

• The original BSD 4.3 ndbm Based on AT&T dbm. Found in commercial Un*x offerings.
• Berkeley DB v1 compatibility interface. Supplied with 4.4BSD based systems: (Free|Open|Net)BSD, MacOS X.
• GNU DBM (GDBM) Found in Linux distributions (may require a DBM compatibility package to be installed).
• SDBM, Ozan Yigit's Public Domain implementation of NDBM. Supplied with this distribution, and used as a last resort on Un*x systems (and by default on non Un*x systems).

---

🎀 DBM_OPEN(filename,flags,mode) 🎀

takes a filename (STRING), flags (either "R" for read-only, "W" for write access, or "CW" to create and write a new file), and a "mode" string, which defaults to "0666" (octal) — and it returns a database handle which you can pass to all the remaining functions. your little passport to the database, fr fr 🛂✨

🎀 DBM_CLOSE 🎀

closes the database file. and bestie, listen to me: DBM_CLOSE MUST be called to ensure that all your data is written. MUST. no skipping. no "it'll be fine". it will not be fine 😭

🎀 DBM_STORE 🎀

takes a database handle, key and datum strings, and a flag (either DBM_INSERT to insert a new pair, or fail if the key already exists, or DBM_REPLACE to insert or replace existing data). the key and datum strings may contain an arbitrary series of characters. go off, put whatever you want in there 💅

🎀 DBM_FETCH 🎀

returns the stored datum (if any) for the supplied key, or fails.

🎀 DBM_DELETE 🎀

deletes the stored datum (if any) for the supplied key, or fails. bye bye data 👋

🎀 DBM_FIRSTKEY 🎀

and subsequent calls to DBM_NEXTKEY allow you to traverse all stored keys. the keys will be returned in arbitrary order (so don't come for me about sorting, it's not that kind of party), and the routines will fail at the end of the traversal.

🎀 DBM_ERROR 🎀

is a predicate which succeeds if the database handle is valid and an I/O error has occurred on the file. 🚨

🎀 DBM_CLEARERR 🎀

is a predicate which succeeds if the database handle is valid, and has the side effect of clearing the I/O error flag. ✨ clean slate energy ✨

---

🍓 FILES 🍓

• NDBM, GDBM, and SDBM create two files: filename.dir and filename.pag.
• Berkeley DB creates a single filename.db file.

---

🌈 SEE ALSO 🌈

snobol4sqlite3dbm(3), ndbm(3), dbopen(3), gdbm(3).

---

👑 AUTHOR 👑

Philip L. Budne — thank you for your service, legend 🫡💖

---

💀 BUGS 💀

Not safe for concurrent read and write. The snobol4sqlite3dbm(3) interface achieves this portably using snobol4sqlite3(3).

Some implementations (classic NDBM and SDBM) place limits on the total size of key plus datum (typically slightly less than 1KB). so like... keep it cute and small okay 😭

NOTE: Some implementations (classic NDBM and SDBM) create sparse files which appear (to "ls -l") to be larger than they are (see "ls -s"). Copying such files may cause the non-allocated blocks to be "filled" with zeroed disk blocks, and then the files really will be large! not a drill, not a vibe, an actual problem 🙈

Only GDBM provides locking to eliminate the possibility of file corruption, or reading of incomplete data. everyone else? living on the edge ✨

GDBM locking sometimes fails on NFS mounted partitions but does not provide a way to disable locking. it's giving trapped 😩

DBM databases accessed concurrently by multiple processes are traditionally (re)created from text files and used for fast disk-based read-only table lookups. Programs which need to update the file generate a new temporary copy using a different name, and then rename the new file(s), so that the next reader gets the new copies (existing readers continue to see old data). it's a whole pipeline, main character energy, we love to see it 🔥

---

aaaand that's the whole page bestie, no notes, you ate that 💅✨ this was CSNOBOL4B 2.3.1, dated March 31, 2022, and you just read the entire SNOBOL4NDBM(3) manual page. slay, go build something 🦋💖🎀