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.

This is a native implementation of SDBM_File 1.17, its sdbm library included; SDBM_File.pm is used unchanged. The files it writes are byte for byte those perl5’s SDBM_File writes, and each reads the other’s.

Differences from upstream#

None.

Functions#

Tie hooks#

`error`#

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

`sdbm_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 { ... }).