dbmclose#

Break the binding between a DBM file and a hash previously attached by dbmopen.

dbmclose is the teardown counterpart to dbmopen. It flushes any pending writes, releases the DBM library’s handles, and leaves HASH as an ordinary, untied hash you can continue to use or discard. In modern code dbmclose has been largely superseded by untie — the two accomplish the same thing, but untie works for every tied variable, not just DBM-bound hashes. Prefer untie unless you are maintaining existing dbmopen/dbmclose pairs and want them to read symmetrically.

Synopsis#

dbmclose HASH
dbmclose %hash

What you get back#

True on success, false on failure. Failure modes are rare — the common one is passing a hash that was never tied to a DBM file in the first place, in which case dbmclose returns false and sets $!. Most programs do not check the return value; the interesting errors (disk full, quota exceeded) surface on the writes that preceded the close, not on dbmclose itself. Check it when the DBM file is on a filesystem where a delayed write failure at close time is plausible:

dbmclose(%cache)
    or warn "dbmclose failed: $!";

Global state it touches#

dbmclose reads and mutates the tie state of HASH. It does not touch any of the usual I/O-related special variables ($,, $\, $|, the selected filehandle); DBM access does not flow through the PerlIO layers that print and friends use. On failure, $! is set by the underlying DBM library.

Examples#

Open a DBM file, iterate it, close it:

dbmopen(%HIST, '/usr/lib/news/history', 0666)
    or die "dbmopen: $!";
while (my ($key, $val) = each %HIST) {
    print $key, ' = ', unpack('L', $val), "\n";
}
dbmclose(%HIST);

Equivalent using the modern tie/untie pair — this is what new code should look like:

use AnyDBM_File;
use Fcntl;
tie(my %HIST, 'AnyDBM_File', '/usr/lib/news/history', O_RDWR, 0666)
    or die "tie: $!";
# ... use %HIST ...
untie %HIST;

Guard against closing an unbound hash:

my %h;
dbmclose(%h)
    or warn "not tied to a DBM file: $!";   # warns

Pair with an eval block to localise any cleanup errors without aborting the surrounding code:

eval {
    dbmclose(%cache) or die "dbmclose: $!";
    1;
} or warn $@;

Edge cases#

Hash not tied to a DBM file: returns false, sets $!. No exception is raised. The hash is left unchanged.
Hash tied via tie, not dbmopen: dbmclose still works and is equivalent to untie for that hash, because dbmopen is itself implemented as a tie under the hood. Mixing the two APIs is legal but confusing — pick one per hash and stay with it.
References still held to the tied object: like untie, dbmclose severs the binding between the hash and the DBM file, but if other code still holds a reference to the underlying tied object the DBM library may not actually release its handles until that reference is dropped. The symptom is a DBM file that stays locked or open past the dbmclose call. A use warnings program receives the untie attempted while N inner references still exist warning in that case.
Calling dbmclose twice on the same hash: the first call succeeds, the second returns false. Idempotent-style code should either track whether the hash is currently tied or ignore the failure.
Hash is local’d or goes out of scope without dbmclose: the binding is broken implicitly when the hash is destroyed, and the DBM library closes the file as part of that teardown. Explicit dbmclose is preferable because it makes write-flush failures visible at a known point in the program.

Differences from upstream#

Fully compatible with upstream Perl 5.42.