SDBM_File(3perl)

💖 NAME 💖

SDBM_File — it's your girl for tied access to sdbm files, bestie. Straight out of the Perl Programmers Reference Guide, section 3perl, and yes she eats every time. 💅

---

🌸 SYNOPSIS 🌸

Okay so here's the whole vibe, front to back:

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

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

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

untie %h;

Like. That's it. That's the whole flex. 🔥

---

🦋 DESCRIPTION 🦋

SDBM_File sets up a whole connection between a Perl hash variable and a file in SDBM_File format. The way you can just manipulate the data in that file like it's a regular Perl hash?? Iconic behaviour, honestly. But here's the part that matters: when your program exits, the data stays in the file, waiting there for the next time your program runs. Persistent queen. 👑

🎀 Tie 🎀

Use SDBM_File together with Perl's built-in tie function to make the connection between the variable and the file. It's giving marriage, it's giving commitment:

tie %hash, 'SDBM_File', $basename, $modeflags, $perms;

tie %hash, 'SDBM_File', $dirfile,  $modeflags, $perms, $pagfilename;

So $basename is the base filename for the database. And listen — the database isn't one file, it's two files, with .dir and .pag extensions appended onto $basename:

$basename.dir     (or .sdbm_dir on VMS, per DIRFEXT constant)
$basename.pag

And plot twist, you can also hand over the two filenames separately, in full, as $dirfile and $pagfilename. That's your move when you've got two files with no .dir and .pag extensions at all — like, say, two files from File::Temp. No cap.

$modeflags can be the following constants from the Fcntl module, done up in the style of the open(2) system call:

O_RDONLY          read-only access
O_WRONLY          write-only access
O_RDWR            read and write access

If you want the file to be created when it doesn't already exist, then bitwise-OR (|) O_CREAT on there too. And fr — if you omit O_CREAT and the database doesn't already exist, the tie call will fail. No database, no tie, no cute little hash. 😭

O_CREAT           create database if doesn't already exist

$perms is the file permissions bits to use if new database files get created. Heads up: this parameter is mandatory even when you're not creating a new database, so don't skip it. The permissions get reduced by the user's umask, which is why the usual value here would be 0666, or 0600 if it's some very private data. (See umask in perlfunc.) ✨

---

🍓 EXPORTS 🍓

SDBM_File optionally exports the following constants, bestie:

• PAGFEXT — the extension used for the page file, usually .pag. 🎀
• DIRFEXT — the extension used for the directory file, .dir everywhere but VMS, where it is .sdbm_dir. 🦋
• PAIRMAX — the maximum size of a stored hash entry, including the length of both the key and value. 💀

And these constants can also be used with fully qualified names, eg. SDBM_File::PAGFEXT. Periodt.

---

👑 DIAGNOSTICS 👑

On failure, the tie call returns an undefined value and probably sets $! to contain the reason the file could not be tied. So always check that return value, okay? Don't be out here ignoring warnings like it's your situationship.

💀 "sdbm store returned -1, errno 22, key "..." at ..."

This warning gets emitted 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. See BUGS AND WARNINGS below for the tea. 🫖

---

🔒 SECURITY WARNING 🔒

🚨 Do not accept SDBM files from untrusted sources! 🚨

The sdbm file format was designed for speed and convenience, not for portability or security. A maliciously crafted file might cause perl to crash or even expose a security vulnerability. So if someone slides an sdbm file into your DMs and you don't know them? Block. 🚫

---

😭 BUGS AND WARNINGS 😭

There are a number of limits on the size of the data that you can store in the SDBM file. The most important one is that the length of a key, plus the length of its associated value, may not exceed 1008 bytes. That's the whole budget, key and value combined, no exceptions. 💔

See tie in perlfunc, perldbmfilter, Fcntl.

---

okay that's the page, bestie, go forth and tie responsibly 💜 This was perl v5.44.0 — yes, dated 2026-10-17, from your favourite SDBM_File(3perl) era. Stay tied, stay unproblematic. 🎀✨🦋