DBM(3) OpenBSD Programmer's Manual DBM(3)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 ALSOdb(3), hash(3), ndbm(3)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.
OpenBSD 4.9 May 31, 2007 OpenBSD 4.9