OpenBSD manual page server

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).

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

db(3), hash(3), ndbm(3)

HISTORY

The functions dbminit(), fetch(), store(), delete(), firstkey(), and nextkey() first appeared in Version 7 AT&T UNIX.

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.