NDBM_File(3perl)

💖 NDBM_File — tied access to ndbm files 💖

okay bestie, so this one's NDBM_File(3perl), straight out of the Perl Programmers Reference Guide, and it's genuinely one of those "small page, big power" situations. let's get into it 🫶

---

✨ SYNOPSIS ✨

use Fcntl;   # For O_RDWR, O_CREAT, etc.
use NDBM_File;

tie(%h, 'NDBM_File', 'filename', O_RDWR|O_CREAT, 0666)
  or die "Couldn't tie NDBM file 'filename': $!; aborting";

# Now read and change the hash
$h{newkey} = newvalue;
print $h{oldkey};
...

untie %h;

like?? a whole database but it's just a hash?? the way that untie is the polite lil goodbye at the end 🎀 periodt.

---

🌸 DESCRIPTION 🌸

NDBM_File sets up a connection between a Perl hash variable and a file in NDBM_File format. that's it, that's the whole vibe. you read and change the data in the file exactly as if it were a regular Perl hash — but here's the iconic part: when your program exits, the data stays in the file, chillin' there waiting for the next time your program runs. main character persistence energy, no cap ✨

you hook it up with Perl's built-in tie function. the arguments to tie should be, in order:

1. the hash variable you want to tie, obvs.
2. the literal string NDBM_File. this is the part that tells Perl to use the NDBM_File package to do all the hash-y heavy lifting. 💅
3. the name of the file you want to tie to the hash.
4. flags. pick exactly one of these:
   • O_RDONLY — read-only access to the data in the file.
   • O_WRONLY — write-only access to the data in the file.
   • O_RDWR — both read and write access, the full package.

now if you want the file to be created when it doesn't exist yet, you add O_CREAT on top of any of those, exactly like the example does. and listen: if you skip O_CREAT and the file isn't already there, the tie call will fail. no file, no tie, no exceptions. 💀

5. the default permissions to use if a new file gets created. heads up though — the actual permissions get modified by the user's umask, so you should probably just use 0666 here. (peep "umask" in perlfunc for the whole story.) 🌈

---

🚨 DIAGNOSTICS 🚨

if it fails, the tie call hands you back an undefined value, and it probably sets $! to hold the reason the file couldn't be tied. so like, always check, bestie. 🙈

🫠 "ndbm store returned -1, errno 22, key "..." at ..."

this warning shows up when you try to store a key or a value that is too long. it means the change was not recorded in the database — like it just. didn't happen. go look at BUGS AND WARNINGS below for the receipts.

---

🔒 SECURITY AND PORTABILITY 🔒

Do not accept NDBM files from untrusted sources. fr fr, this is the important one.

on modern Linux systems, these are typically GDBM files, and those are not portable across platforms. so don't go assuming your file is gonna slay on every machine.

the GDBM documentation doesn't imply that files from untrusted sources can be safely used with libgdbm. read that again, bestie.

and systems that don't use GDBM compatibility for ndbm support are using a platform specific library — possibly one inherited from BSD systems — where it may or may not be safe to use an untrusted file. so... maybe. maybe not. nobody's promising anything. 😭

a maliciously crafted file might cause perl to crash or even expose a security vulnerability. so like, do not open random files with this, i'm begging you. 🙏

---

💀 BUGS AND WARNINGS 💀

there are a whole bunch of limits on how much data you can store in the NDBM file. the most important one, the one you will hit: the length of a key, plus the length of its associated value, may not exceed 1008 bytes.

one thousand and eight. that's the number. write it down. ✍️

see "tie" in perlfunc, perldbmfilter, Fcntl 🦋

---

and that's the whole page, bestie!! this manual page is from perl v5.44.0, dated 2026-10-17, brought to you by the Perl Programmers Reference Guide 💜 go forth and tie responsibly, ily, bye!! 👑✨