# perldoc > DB_File

---
type: CommandReference
command: DB_File
mode: perldoc
section: 
source: perldoc
---

## Quick Reference

- `tie %hash, 'DB_File', $filename` — open DB_HASH database with defaults
- `tie %hash, 'DB_File', $filename, $flags, $mode, $DB_BTREE` — open DB_BTREE
- `tie @array, 'DB_File', $filename, $flags, $mode, $DB_RECNO` — open DB_RECNO
- `$X->get($key, $value)` — fetch value for key
- `$X->put($key, $value [, $flags])` — store key/value pair
- `$X->del($key [, $flags])` — delete key/value pairs
- `$X->seq($key, $value, $flags)` — sequential key/value retrieval
- `$X->get_dup($key)` — get duplicate values (BTREE only)

## Name

DB_File - Perl5 access to Berkeley DB version 1.x

## Synopsis

perl
use DB_File;

# Tie interface
[$X =] tie %hash,  'DB_File', [$filename, $flags, $mode, $DB_HASH];
[$X =] tie %hash,  'DB_File', $filename, $flags, $mode, $DB_BTREE;
[$X =] tie @array, 'DB_File', $filename, $flags, $mode, $DB_RECNO;

# API methods
$status = $X->del($key [, $flags]);
$status = $X->put($key, $value [, $flags]);
$status = $X->get($key, $value [, $flags]);
$status = $X->seq($key, $value, $flags);
$status = $X->sync([$flags]);
$status = $X->fd;

# BTREE only
$count = $X->get_dup($key);
@list  = $X->get_dup($key);
%list  = $X->get_dup($key, 1);
$status = $X->find_dup($key, $value);
$status = $X->del_dup($key, $value);

# RECNO only
$a = $X->length;
$a = $X->pop;
$X->push(list);
$a = $X->shift;
$X->unshift(list);
@r = $X->splice(offset, length, elements);

# DBM Filters
$old_filter = $db->filter_store_key  ( sub { ... } );
$old_filter = $db->filter_store_value( sub { ... } );
$old_filter = $db->filter_fetch_key  ( sub { ... } );
$old_filter = $db->filter_fetch_value( sub { ... } );

untie %hash;
untie @array;
## Options

### Common Parameters

- `$filename` — database file path; `undef` for in-memory database
- `$flags` — file open flags (e.g., `O_RDWR|O_CREAT`); defaults to `O_CREAT|O_RDWR`
- `$mode` — file permissions (e.g., `0666`)
- `$DB_HASH`, `$DB_BTREE`, `$DB_RECNO` — predefined references to configuration objects

### DB_HASH Configuration (`$DB_HASH`)

- `bsize` — bucket size
- `cachesize` — cache size (bytes)
- `ffactor` — fill factor
- `hash` — reference to Perl sub for custom hashing (returns hash value)
- `lorder` — byte order (0 = current host)
- `nelem` — estimated number of elements

### DB_BTREE Configuration (`$DB_BTREE`)

- `flags` — bitmask; set `R_DUP` to allow duplicate keys
- `cachesize` — cache size (bytes)
- `maxkeypage` — maximum keys per page
- `minkeypage` — minimum keys per page
- `psize` — page size
- `compare` — reference to Perl sub for key comparison (returns -1, 0, 1)
- `prefix` — reference to Perl sub for prefix compression (returns number of bytes)
- `lorder` — byte order

### DB_RECNO Configuration (`$DB_RECNO`)

- `bval` — delimiter byte for variable-length records or pad byte for fixed-length; defaults to `"\n"` for variable, space for fixed
- `cachesize` — cache size (bytes)
- `psize` — page size
- `flags` — bitmask
- `lorder` — byte order
- `reclen` — record length (fixed-length records)
- `bfname` — name of backing file for in-memory databases

### DBM Filter Methods

- `filter_store_key(sub)` — filter applied to keys before storing
- `filter_store_value(sub)` — filter applied to values before storing
- `filter_fetch_key(sub)` — filter applied to keys after fetching
- `filter_fetch_value(sub)` — filter applied to values after fetching

Each filter modifies `$_` in place. Returns previous filter or `undef`. Pass `undef` to remove.

## Examples

### Simple DB_HASH

perl
use DB_File;
unlink "fruit";
tie %h, "DB_File", "fruit", O_RDWR|O_CREAT, 0666, $DB_HASH
    or die "Cannot open file: $!\n";
$h{"apple"} = "red";
$h{"banana"} = "yellow";
delete $h{"apple"};
while (($k, $v) = each %h) { print "$k -> $v\n" }
untie %h;
### BTREE with Custom Sort Order

perl
use DB_File;
sub Compare {
    my ($key1, $key2) = @_;
    lc $key1 cmp lc $key2;
}
$DB_BTREE->{'compare'} = \&Compare;
unlink "tree";
tie %h, "DB_File", "tree", O_RDWR|O_CREAT, 0666, $DB_BTREE
    or die "Cannot open file: $!\n";
$h{'Wall'} = 'Larry';
$h{'Smith'} = 'John';
foreach (keys %h) { print "$_\n" }
untie %h;
### Handling Duplicate Keys (BTREE with R_DUP)

perl
use DB_File;
$DB_BTREE->{'flags'} = R_DUP;
$x = tie %h, "DB_File", "tree", O_RDWR|O_CREAT, 0666, $DB_BTREE
    or die "Cannot open file: $!\n";
$h{'Wall'} = 'Larry';
$h{'Wall'} = 'Brick';
$key = $value = 0;
for ($status = $x->seq($key, $value, R_FIRST);
     $status == 0;
     $status = $x->seq($key, $value, R_NEXT)) {
    print "$key -> $value\n";
}
undef $x; untie %h;
### RECNO Array Interface

perl
use DB_File;
unlink "text";
tie @h, "DB_File", "text", O_RDWR|O_CREAT, 0666, $DB_RECNO
    or die "Cannot open file: $!\n";
$h[0] = "orange";
$h[1] = "blue";
push @h, "green", "black";
my $last = pop @h;
print "popped $last\n";
untie @h;
### DBM Filter for NULL Termination

perl
use DB_File;
$db = tie %hash, 'DB_File', "filt", O_CREAT|O_RDWR, 0666, $DB_HASH
    or die "Cannot open: $!\n";
$db->filter_fetch_key  ( sub { s/\0$// } );
$db->filter_store_key  ( sub { $_ .= "\0" } );
$db->filter_fetch_value( sub { s/\0$// } );
$db->filter_store_value( sub { $_ .= "\0" } );
$hash{"abc"} = "def";
undef $db; untie %hash;
## See Also

- [perl](https://perldoc.perl.org/perl)
- [dbopen(3)](https://man.openbsd.org/dbopen.3)
- [hash(3)](https://man.openbsd.org/hash.3)
- [recno(3)](https://man.openbsd.org/recno.3)
- [btree(3)](https://man.openbsd.org/btree.3)
- [perldbmfilter](https://perldoc.perl.org/perldbmfilter)
- [DBM_Filter](https://metacpan.org/pod/DBM_Filter)
- [BerkeleyDB](https://metacpan.org/pod/BerkeleyDB)
- [Tie::DB_Lock](https://metacpan.org/pod/Tie::DB_Lock)
- [Tie::DB_LockFile](https://metacpan.org/pod/Tie::DB_LockFile)
- [DB_File::Lock](https://metacpan.org/pod/DB_File::Lock)
- [MLDBM](https://metacpan.org/pod/MLDBM)

## Exit Codes

All API methods return 0 on success, -1 on error (with `$!` set), and 1 when the requested key does not exist (for `get`, `del`, `find_dup`, `del_dup`). Other return codes may be defined; see Berkeley DB documentation.