# SDBM_File

📦 min

Tie a Perl hash to an on-disk SDBM database so keys and values persist between runs. SDBM_File is a **tied-hash interface**: you never call `FETCH`, `STORE`, `DELETE`, or `EXISTS` directly. You bind a hash to a database file with `tie`, and from then on any ordinary hash syntax — `$h{key}`, `delete $h{key}`, `exists $h{key}`, `keys %h`, `each %h` — is routed by Perl’s tie machinery to the uppercase hook methods defined here. The database itself lives in two files alongside each other, `NAME.dir` and `NAME.pag`, that persist between program runs. Neither `untie` nor program exit removes them — clean-up is the caller’s responsibility. ## Synopsis ```none use Fcntl; use SDBM_File; tie my %h, 'SDBM_File', 'mydb', O_RDWR | O_CREAT, 0666 or die "tie failed: $!"; $h{greeting} = 'hello'; print $h{greeting}; # hello untie %h; ``` ## Persistence Tying creates (or opens) two files named after the `$basename` argument: `$basename.dir` and `$basename.pag`. Values written through the tied hash land in these files immediately and survive the process. `untie` closes the handle but leaves the files in place for the next run. Use `unlink` if you want them gone. The six-argument form of `tie` lets you name the two files independently when the `.dir` / `.pag` naming convention does not fit — typically with `File::Temp` handles. ## Size limits SDBM is a fixed-page format. The combined length of a key and its value must not exceed **1008 bytes** (the `PAIRMAX` constant). A `STORE` for a too-large pair croaks with `sdbm store returned -1, errno 22, key "..."` and the pair is not written. The two filename-extension constants `PAGFEXT` and `DIRFEXT` are exported for code that needs to locate the backing files. ## Security Do not open SDBM files from untrusted sources. The on-disk layout was designed for speed, not integrity, and a maliciously crafted file can drive the reader into undefined behavior. ## Functions ### Tie hooks #### [`tiehash`](SDBM_File/tiehash.md) Open an SDBM database and return a blessed handle. Invoked by Perl when the user writes `tie %h, 'SDBM_File', $basename, $flags, $mode`. #### `destroy` Close the SDBM database and release the handle. Invoked when the tied hash goes out of scope, is `untie`’d, or is garbage-collected. #### `fetch` Retrieve the value stored under a given key. Invoked by Perl’s tie machinery when the user writes `$h{key}`. #### [`store`](SDBM_File/store.md) Write a key-value pair to the database. Invoked by Perl’s tie machinery when the user writes `$h{key} = $value`. #### `delete` Remove a key from the database. Invoked by Perl’s tie machinery when the user writes `delete $h{key}`. #### `exists` Report whether a key is present in the database. Invoked by Perl’s tie machinery when the user writes `exists $h{key}`. #### `firstkey` Return the first key for an iteration over the tied hash. Invoked by Perl at the start of `keys %h`, `values %h`, or `each %h`, and whenever iteration is reset. #### `nextkey` Return the next key in an ongoing iteration. Invoked by Perl after FIRSTKEY for every subsequent step of `keys`, `values`, or `each`. #### `error` Report whether the database has a sticky I/O-error flag set. Called as a method on the tied object: `(tied %h)->error`. #### `clearerr` Clear the sticky I/O-error flag on the database. Called as a method on the tied object: `(tied %h)->sdbm_clearerr`. ### Filters #### `filter_fetch_key` Install a callback that rewrites keys on the way out of the database. Called as a method on the tied object: `(tied %h)->filter_fetch_key(sub { ... })`. #### `filter_store_key` Install a callback that rewrites keys on the way into the database. Called as a method on the tied object: `(tied %h)->filter_store_key(sub { ... })`. #### `filter_fetch_value` Install a callback that rewrites values on the way out of the database. Called as a method on the tied object: `(tied %h)->filter_fetch_value(sub { ... })`. #### `filter_store_value` Install a callback that rewrites values on the way into the database. Called as a method on the tied object: `(tied %h)->filter_store_value(sub { ... })`.