ODBM_File#

📦 std

Tie a Perl hash to an old-style dbm database file.

ODBM_File is the tied-hash interface to the original Unix dbm: one database per process, keys and values of bytes. Bind a hash with tie; $h{key}, delete, keys and each then read and write the file. It has no exists.

Synopsis#

use Fcntl;
use ODBM_File;

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

Opening a database#

tie %h, 'ODBM_File', $basename, $flags, $mode;

With O_CREAT in $flags the files are created if missing, with the permission $mode; without it they must exist, or tie croaks ODBM_FILE: Can't open NAME. Only one database can be tied at a time in a process: a second tie croaks Old dbm can only open one database until the first is untied.

DBM filters#

(tied %h)->filter_store_key(sub {...}), filter_store_value, filter_fetch_key and filter_fetch_value install a sub that rewrites every key or value on its way into, or out of, the database. The sub changes $_ in place; a store filter works on a copy, so your own variable keeps its value. Each method returns the filter it replaces (or undef), and undef as the argument removes the filter. A filter that uses the same database croaks recursion detected in filter_store_key (or the filter’s own name).

Files#

pperl keeps the data in an LMDB file, NAME.pag, with NAME.dir beside it, as old dbm has the two, and LMDB’s lock file NAME.pag-lock. The dbm library is not used, and its files cannot be read: tying a real dbm (gdbm) or Berkeley DB file croaks, naming what the file is, and the file is left as it was. A key may be at most 511 bytes, 510 if it starts with a NUL byte; a longer one croaks.

Writes reach the file when the hash is untied: until then the tie holds the file’s one writer slot, and another process that writes the file waits for it (readers never wait). Set $Peta::LMDB::DBM_WRITE = 'through' before tie to commit every write as it happens; see Peta::LMDB.

Differences from upstream#

  • The files are LMDB files: real dbm and Berkeley DB files are refused, and pperl’s files cannot be read by perl 5’s ODBM_File. Covered by t/82-native/Peta-LMDB/080-odbm.t.

  • Keys are limited to 511 bytes. Covered by t/82-native/Peta-LMDB/080-odbm.t.

  • Writes reach the file at untie (or each one, with $Peta::LMDB::DBM_WRITE = 'through'), and a writer holds the file until then. Covered by t/82-native/Peta-LMDB/080-odbm.t.

  • tie with O_CREAT opens a database that already exists, where perl 5 croaks ODBM_File: Can't create NAME. Covered by t/82-native/Peta-LMDB/080-odbm.t.

  • A tie that fails does not keep later ones from opening a database; in perl 5 every later tie in the process croaks Old dbm can only open one database. Covered by t/82-native/Peta-LMDB/080-odbm.t.

Everything else behaves as with perl 5’s ODBM_File. Covered by its own test, t/81-xs-native/ODBM_File/100-upstream-odbm.t.