SDBM_File

📦 min

Tie a Perl hash to an on-disk SDBM database so keys and values persist between runs.

SDBM_File is a tied-hash interface: you never call FETCH, STORE, DELETE, or EXISTS directly. You bind a hash to a database file with tie, and from then on any ordinary hash syntax — $h{key}, delete $h{key}, exists $h{key}, keys %h, each %h — is routed by Perl’s tie machinery to the uppercase hook methods defined here.

The database itself lives in two files alongside each other, NAME.dir and NAME.pag, that persist between program runs. Neither untie nor program exit removes them — clean-up is the caller’s responsibility.

Synopsis

use Fcntl;
use SDBM_File;

tie my %h, 'SDBM_File', 'mydb', O_RDWR | O_CREAT, 0666
    or die "tie failed: $!";
$h{greeting} = 'hello';
print $h{greeting};        # hello
untie %h;

Persistence

Tying creates (or opens) two files named after the $basename argument: $basename.dir and $basename.pag. Values written through the tied hash land in these files immediately and survive the process. untie closes the handle but leaves the files in place for the next run. Use unlink if you want them gone.

The six-argument form of tie lets you name the two files independently when the .dir / .pag naming convention does not fit — typically with File::Temp handles.

Size limits

SDBM is a fixed-page format. The combined length of a key and its value must not exceed 1008 bytes (the PAIRMAX constant). A STORE for a too-large pair croaks with sdbm store returned -1, errno 22, key "..." and the pair is not written. The two filename-extension constants PAGFEXT and DIRFEXT are exported for code that needs to locate the backing files.

Security

Do not open SDBM files from untrusted sources. The on-disk layout was designed for speed, not integrity, and a maliciously crafted file can drive the reader into undefined behavior.

Functions

Tie hooks

tiehash

Open an SDBM database and return a blessed handle. Invoked by Perl when the user writes tie %h, 'SDBM_File', $basename, $flags, $mode.

destroy

Close the SDBM database and release the handle. Invoked when the tied hash goes out of scope, is untie’d, or is garbage-collected.

fetch

Retrieve the value stored under a given key. Invoked by Perl’s tie machinery when the user writes $h{key}.

store

Write a key-value pair to the database. Invoked by Perl’s tie machinery when the user writes $h{key} = $value.

delete

Remove a key from the database. Invoked by Perl’s tie machinery when the user writes delete $h{key}.

exists

Report whether a key is present in the database. Invoked by Perl’s tie machinery when the user writes exists $h{key}.

firstkey

Return the first key for an iteration over the tied hash. Invoked by Perl at the start of keys %h, values %h, or each %h, and whenever iteration is reset.

nextkey

Return the next key in an ongoing iteration. Invoked by Perl after FIRSTKEY for every subsequent step of keys, values, or each.

error

Report whether the database has a sticky I/O-error flag set. Called as a method on the tied object: (tied %h)->error.

clearerr

Clear the sticky I/O-error flag on the database. Called as a method on the tied object: (tied %h)->sdbm_clearerr.

Filters

filter_fetch_key

Install a callback that rewrites keys on the way out of the database. Called as a method on the tied object: (tied %h)->filter_fetch_key(sub { ... }).

filter_store_key

Install a callback that rewrites keys on the way into the database. Called as a method on the tied object: (tied %h)->filter_store_key(sub { ... }).

filter_fetch_value

Install a callback that rewrites values on the way out of the database. Called as a method on the tied object: (tied %h)->filter_fetch_value(sub { ... }).

filter_store_value

Install a callback that rewrites values on the way into the database. Called as a method on the tied object: (tied %h)->filter_store_value(sub { ... }).