```{index} single: ODBM_File ``` # ODBM_File ```{pperl-module-badges} ODBM_File ``` 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 ```perl 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 ```perl 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`.