PERLDBMFILTER(1perl)

💖 perldbmfilter — Perl DBM Filters 💖

okay bestie, so this is perldbmfilter, straight out of the Perl Programmers Reference Guide. it's about DBM Filters and it's genuinely one of those "wait this is actually so useful" pages. buckle up 🎀

---

✨ NAME ✨

perldbmfilter — Perl DBM Filters. that's it. that's the whole name. iconic.

---

🌸 SYNOPSIS 🌸

$db = tie %hash, 'DBM', ...

$old_filter = $db->filter_store_key  ( sub { ... } );
$old_filter = $db->filter_store_value( sub { ... } );
$old_filter = $db->filter_fetch_key  ( sub { ... } );
$old_filter = $db->filter_fetch_value( sub { ... } );

look at that. four little methods, four little sub { ... } slots, infinite power. it's giving main character energy fr fr 💅

---

🦋 DESCRIPTION 🦋

so the four filter_* methods up there? they're available in every single DBM module that ships with Perl, namely:

• DB_File
• GDBM_File
• NDBM_File
• ODBM_File
• SDBM_File

all five. no cap 👑

each of these methods works identically — you use them to install (or uninstall) a single DBM Filter. the only thing that makes them different is the place where the filter gets installed. that's the whole vibe.

so to summarise, bestie:

• filter_store_key — if a filter has been installed with this method, it will be invoked every time you write a key to a DBM database. 🔑
• filter_store_value — if a filter has been installed with this method, it will be invoked every time you write a value to a DBM database. 📝
• filter_fetch_key — if a filter has been installed with this method, it will be invoked every time you read a key from a DBM database. 👀
• filter_fetch_value — if a filter has been installed with this method, it will be invoked every time you read a value from a DBM database. 📖

and you can use any combination of them — from none of them to all four. your call, your rules 💅

✨ all filter methods return the existing filter if one's present, or undef if there isn't one. and if you want to delete a filter? you pass undef to it. boom. gone. 🫶

🌈 The Filter 🌈

when each filter gets called by Perl, a local copy of $_ will contain the key or the value that's about to be filtered. filtering happens by modifying the contents of $_. the return code from the filter is ignored. like, genuinely ignored, don't stress about it. 🙈

🍓 An Example: the NULL termination problem 🍓

DBM Filters are lowkey perfect for that whole class of problems where you always want to make the same transformation to all keys, all values, or both. same energy every time. ⭐

for example, picture this scenario: you've got a DBM database that you need to share with a third-party C application. and the C application assumes that all keys and values are NULL terminated.

unfortunately 😭 when Perl writes to DBM databases it doesn't use NULL termination, so your Perl application has to manage NULL termination all by itself. so when you write to the database you'd have to do something like this:

$hash{"$key\0"} = "$value\0";

and similarly, the NULL needs to be taken into account when you're considering the length of existing keys/values. annoying, right? 💀

it would be SO much better if you could just ignore the whole NULL termination issue in your main application code and have a mechanism that automatically adds the terminating NULL to all keys and values whenever you write to the database, and removes them when you read from the database. and as I'm sure you've already guessed — this is a problem DBM Filters can fix very easily. slay. 👑

use v5.36;
use SDBM_File;
use Fcntl;

my %hash;
my $filename = "filt";
unlink $filename;

my $db = tie(%hash, 'SDBM_File', $filename, O_RDWR|O_CREAT, 0640)
  or die "Cannot open $filename: $!\n";

# Install DBM Filters
$db->filter_fetch_key  ( sub { s/\0$//    } );
$db->filter_store_key  ( sub { $_ .= "\0" } );
$db->filter_fetch_value(
    sub { no warnings 'uninitialized'; s/\0$// } );
$db->filter_store_value( sub { $_ .= "\0" } );

$hash{"abc"} = "def";
my $x = $hash{"ABC"};
# ...
undef $db;
untie %hash;

the code above uses SDBM_File, but bestie, it will work with any of the DBM modules. any of them. ✨

hopefully the contents of each of the filters should be self-explanatory — both "fetch" filters remove the terminating NULL, and both "store" filters add a terminating NULL. 🎀

🧚 Another Example: Key is a C int 🧚

here's another real-life example, because we're being thorough and we don't do half-measures here 💜

by default, whenever Perl writes to a DBM database it always writes the key and value as strings. so when you use this:

$hash{12345} = "something";

the key 12345 will get stored in the DBM database as the 5 byte string "12345". but if you actually want the key stored in the DBM database as a C int, you're gonna have to use "pack" when writing, and "unpack" when reading.

here's a DBM Filter that does exactly that:

use v5.36;
use DB_File;
my %hash;
my $filename = "filt";
unlink $filename;

my $db = tie %hash, 'DB_File', $filename, O_CREAT|O_RDWR, 0666,
    $DB_HASH or die "Cannot open $filename: $!\n";

$db->filter_fetch_key  ( sub { $_ = unpack("i", $_) } );
$db->filter_store_key  ( sub { $_ = pack ("i", $_) } );
$hash{123} = "def";
# ...
undef $db;
untie %hash;

the code above uses DB_File, but again — it will work with any of the DBM modules. 🔥

this time only two filters have been used; we only need to manipulate the contents of the key, so it wasn't necessary to install any value filters. efficient. ate and left no crumbs. 💅

---

👑 SEE ALSO 👑

DB_File, GDBM_File, NDBM_File, ODBM_File and SDBM_File.

---

🌟 AUTHOR 🌟

Paul Marquess — thank you for your service, legend 🫶

---

okay that's the whole page, bestie!! every option, every filter, every example, all of it. go forth and filter your DBM databases responsibly 💖✨

this was perl v5.44.0, dated 2026-10-17, and it lives in the Perl Programmers Reference Guide as PERLDBMFILTER(1perl) — ily, bye!! 🎀🦋🌸