'\" te
.\" Copyright (c) 2007, Sun Microsystems, Inc.  All Rights Reserved.
.\"  Copyright (c) 1980 Regents of the University of California.  All rights reserved.  The Berkeley software License Agreement specifies the terms and conditions for redistribution.
.TH DBM 3UCB "Oct 30, 2007"
.SH NAME
dbm, dbminit, dbmclose, fetch, store, delete, firstkey, nextkey \- data base
subroutines
.SH SYNOPSIS
.LP
.nf
\fB/usr/ucb/cc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ldbm\fR
#include <dbm.h>

typedef struct {
     char *dptr;
     int dsize;
 }datum;

\fBint\fR \fBdbminit\fR(\fIfile\fR)
\fBchar *\fR\fIfile\fR;
.fi

.LP
.nf
\fBint\fR \fBdbmclose\fR();
.fi

.LP
.nf
\fBdatum\fR \fBfetch\fR(\fIkey\fR)
\fBdatum\fR \fIkey\fR;
.fi

.LP
.nf
\fBint\fR \fBstore\fR( \fIkey\fR, \fIdat\fR)
\fBdatum\fR \fIkey\fR, \fIdat\fR;
.fi

.LP
.nf
\fBint\fR \fBdelete\fR(\fIkey\fR)
\fBdatum\fR \fIkey\fR;
.fi

.LP
.nf
\fBdatum\fR \fBfirstkey\fR();
.fi

.LP
.nf
\fBdatum\fR \fBnextkey\fR(\fIkey\fR)
\fBdatum\fR \fIkey\fR;
.fi

.SH DESCRIPTION
.sp
.LP
The \fBdbm()\fR library has been superseded by \fBndbm\fR (see \fBndbm\fR(3C)).
.sp
.LP
These functions maintain key/content pairs in a data base. The functions will
handle very large (a billion blocks) databases and will access a keyed item in
one or two file system accesses.
.sp
.LP
\fIkey/dat\fR and their content are described by the \fBdatum\fR \fBtypedef\fR.
A \fBdatum\fR specifies a string of \fIdsize\fR bytes pointed to by \fIdptr\fR.
Arbitrary binary data, as well as normal ASCII strings, are allowed. The data
base is stored in two files. One file is a directory containing a bit map and
has \fB\&.dir\fR as its suffix. The second file contains all data and has
\fB\&.pag\fR as its suffix.
.sp
.LP
Before a database can be accessed, it must be opened by \fBdbminit()\fR. At the
time of this call, the files \fIfile\fR\fB\&.dir\fR and \fIfile\fR\fB\&.pag\fR
must exist. An empty database is created by creating zero-length \fB\&.dir\fR
and \fB\&.pag\fR files.
.sp
.LP
A database may be closed by calling \fBdbmclose()\fR. You must close a database
before opening a new one.
.sp
.LP
Once open, the data stored under a key is accessed by \fBfetch()\fR and data is
placed under a key by \fBstore\fR. A key (and its associated contents) is
deleted by \fBdelete()\fR. A linear pass through all keys in a database may be
made, in an (apparently) random order, by use of \fBfirstkey()\fR and
\fBnextkey()\fR. \fBfirstkey()\fR will return the first key in the database.
With any key \fBnextkey()\fR will return the next key in the database. This
code will traverse the data base:
.sp
.in +2
.nf
for (key = firstkey; key.dptr != NULL; key = nextkey(key))
.fi
.in -2

.SH RETURN VALUES
.sp
.LP
All functions that return an \fBint\fR indicate errors with negative values. A
zero return indicates no error. Routines that return a \fBdatum\fR indicate
errors with a \fINULL\fR (0) \fIdptr\fR.
.SH SEE ALSO
.sp
.LP
\fBar\fR(1), \fBcat\fR(1), \fBcp\fR(1), \fBtar\fR(1), \fBndbm\fR(3C)
.SH NOTES
.sp
.LP
Use of these interfaces should be restricted to only applications written on
BSD platforms.  Use of these interfaces with any of the system libraries or in
multi-thread applications is unsupported.
.sp
.LP
The \fB\&.pag\fR file will contain holes so that its apparent size may be
larger than its actual content. Older versions of the UNIX operating system may
create real file blocks for these holes when touched. These files cannot be
copied by normal means ( \fBcp\fR(1), \fBcat\fR(1), \fBtar\fR(1), \fBar\fR(1))
without filling in the holes.
.sp
.LP
\fIdptr\fR pointers returned by these subroutines point into static storage
that is changed by subsequent calls.
.sp
.LP
The sum of the sizes of a key/content pair must not exceed the internal block
size (currently 1024 bytes). Moreover all key/content pairs that hash together
must fit on a single block. \fBstore\fR will return an error in the event that
a disk block fills with inseparable data.
.sp
.LP
\fBdelete()\fR does not physically reclaim file space, although it does make it
available for reuse.
.sp
.LP
The order of keys presented by \fBfirstkey()\fR and \fBnextkey()\fR depends on
a hashing function, not on anything interesting.
.sp
.LP
There are no interlocks and no reliable cache flushing; thus concurrent
updating and reading is risky.
.sp
.LP
The database files (\fIfile\fR\fB\&.dir\fR and \fIfile\fR\fB\&.pag\fR) are
binary and are architecture-specific (for example, they depend on the
architecture's byte order.)  These files are not guaranteed to be portable
across architectures.