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