NAME
dbminit
, dbmclose
,
fetch
, store
,
delete
, firstkey
,
nextkey
—
database subroutines
SYNOPSIS
#include
<dbm.h>
int
dbminit
(const
char *file);
int
dbmclose
(void);
datum
fetch
(datum
key);
int
store
(datum
key, datum
content);
int
delete
(datum
key);
datum
firstkey
(void);
datum
nextkey
(datum
key);
DESCRIPTION
These functions provide a dbm-compatible interface to the database access methods described in db(3). Each unique record in the database is a key/content pair, the components of which may be any arbitrary binary data. The key and the content data are described by the datum data structure:
typedef struct { void *dptr; size_t dsize; } datum;
The
dbminit
()
function is used to open a database. Before the call to
dbminit
(), the files
file.pag and file.dir must
exist. The user is responsible for creating the zero-length
.pag and .dir files.
Once the database is open,
fetch
() is
used to retrieve the data content associated with the specified
key. Similarly,
store
()
is used to store the content data with the specified
key.
The
delete
()
function removes the specified key and its associated
content from the database.
The functions
firstkey
()
and nextkey
() are used to iterate over all of the
records in the database. Each record will be reached exactly once, but in no
particular order. The firstkey
() function returns
the first record of the database, and thereafter
nextkey
() returns the following records. The
following code traverses the entire database:
for (key = firstkey(); key.dptr != NULL; key = nextkey(key))
The behaviour of
nextkey
()
is undefined if the database is modified after a call to
firstkey
().
The database is closed with the
dbmclose
()
function (it must be closed before a new one can be opened).
Implementation notes
The underlying database is a hash(3) database with a bucket size of 4096, a filling factor of 40, default hashing function and cache size, and uses the host's native byte order.
RETURN VALUES
Upon successful completion, all functions that return int return a value of 0, otherwise a negative value is returned.
Functions that return a datum indicate
errors by setting the dptr field to
NULL
.
SEE ALSO
BUGS
Because the dbm
routines are implemented
on top of db(3), only a single file, file.pag, is used
to actually store the database. The references to
file.dir are purely for backwards compatibility with
historic implementations.