---
name: dbmclose
signature: 'dbmclose HASH'
since: 5.0
status: documented
categories: ["I/O", "Classes and OO"]
---

```{index} single: dbmclose; Perl built-in
```

*[I/O](../perlfunc-by-category) · [Classes and OO](../perlfunc-by-category)*

# dbmclose

Break the binding between a DBM file and a hash previously attached by
[`dbmopen`](dbmopen).

`dbmclose` is the teardown counterpart to [`dbmopen`](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`](untie) — the two accomplish the same thing, but [`untie`](untie)
works for every tied variable, not just DBM-bound hashes. Prefer
[`untie`](untie) unless you are maintaining existing `dbmopen`/`dbmclose`
pairs and want them to read symmetrically.

## Synopsis

```perl
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 [`$!`](../perlvar).
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:

```perl
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
([`$,`](../perlvar), [`$\`](../perlvar), [`$|`](../perlvar), the
selected filehandle); DBM access does not flow through the PerlIO
layers that `print` and friends use. On failure, [`$!`](../perlvar) is
set by the underlying DBM library.

## Examples

Open a DBM file, iterate it, close it:

```perl
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`](tie)/[`untie`](untie) pair — this is
what new code should look like:

```perl
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:

```perl
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:

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

## Edge cases

- **Hash not tied to a DBM file**: returns false, sets
  [`$!`](../perlvar). No exception is raised. The hash is left
  unchanged.
- **Hash tied via [`tie`](tie), not [`dbmopen`](dbmopen)**: `dbmclose`
  still works and is equivalent to [`untie`](untie) for that hash,
  because `dbmopen` is itself implemented as a [`tie`](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`](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.

## See also

- [`dbmopen`](dbmopen) — the opening half of the pair; every
  `dbmclose` matches a prior `dbmopen` on the same hash
- [`untie`](untie) — the modern, general-purpose replacement;
  works for every tied variable, not just DBM-bound hashes
- [`tie`](tie) — the modern counterpart to [`dbmopen`](dbmopen),
  used with `AnyDBM_File`, `DB_File`, `GDBM_File`, `NDBM_File`, or
  `SDBM_File` to bind a hash to a DBM file
- [`close`](close) — unrelated, but the analogous operation for
  filehandles: needed when you care about write-flush failures
  surfacing at a known point