NDBM_File#

📦 std

Tie a Perl hash to an ndbm database file, so keys and values persist between runs.

NDBM_File is a tied-hash interface: bind a hash to a database with tie, and from then on $h{key}, delete, exists, keys and each read and write the file. Most programs reach it through AnyDBM_File, which picks NDBM_File first.

Synopsis#

use Fcntl;
use NDBM_File;

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

Opening a database#

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

$flags are Fcntl’s O_RDONLY, O_RDWR, O_CREAT, O_TRUNC; $mode is the permission of the files it creates. tie returns the database object, or undef with $! set when the file cannot be opened.

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. The DBM_Filter module offers ready-made ones (utf8, null, int32 and others). 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 an empty NAME.dir beside it, as ndbm has the two, and LMDB’s lock file NAME.pag-lock. The ndbm library is not used, and its files cannot be read: tying a real 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, for files that several processes write; see Peta::LMDB.

Differences from upstream#

  • The files are LMDB files: real ndbm (gdbm) and Berkeley DB files are refused, and pperl’s files cannot be read by perl 5’s NDBM_File. Covered by t/82-native/Peta-LMDB/060-store.t.

  • Keys are limited to 511 bytes. Covered by t/82-native/Peta-LMDB/060-store.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/060-store.t.

  • Deleting the key each just returned is safe: the walk goes on with the next key. Covered by t/82-native/Peta-LMDB/060-store.t.

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

Functions#

Errors#

error#

(tied %h)->error: true when an operation on the database has failed since it was tied or since the last clearerr - a delete on a database tied O_RDONLY, for one.

clearerr#

(tied %h)->clearerr: reset the failure flag error reports.