Manual Page Search Parameters
DBM_OPEN(3) Library Functions Manual DBM_OPEN(3)

dbm_clearerr, dbm_close, dbm_delete, dbm_dirfno, dbm_error, dbm_fetch, dbm_firstkey, dbm_nextkey, dbm_open, dbm_pagfno, dbm_rdonly, dbm_store — database access methods

#include <ndbm.h>

int
dbm_clearerr(DBM *db);

void
dbm_close(DBM *db);

int
dbm_delete(DBM *db, datum key);

int
dbm_dirfno(DBM *db);

int
dbm_error(DBM *db);

datum
dbm_fetch(DBM *db, datum key);

datum
dbm_firstkey(DBM *db);

datum
dbm_nextkey(DBM *db);

DBM *
dbm_open(const char *file, int flags, mode_t mode);

int
dbm_pagfno(DBM *db);

int
dbm_rdonly(DBM *db);

int
dbm_store(DBM *db, datum key, datum content, int store_mode);

These functions provide a ndbm-compatible interface to the database access methods described in dbopen(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 () function is used to open a database in the file named by file, suffixed with DBM_SUFFIX (‘.db’). If necessary, the file is created with mode mode. Access to this file depends on the flags parameter (see open(2)). Read-only access may be indicated by specifying DBM_RDONLY. The () function may be used to determine if a database is opened for read-only access.

Once the database is open, () is used to retrieve the data content associated with the key key. Similarly, () is used to store the content data with the key key. When storing, the store_mode parameter must be one of:

Only insert new keys into the database. Existing key/content pairs are untouched.
Replace any existing entry with the same key. Any previously stored records with the same key are lost.

The () function removes the key key and its associated content from the database.

The functions () and dbm_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 dbm_firstkey() function returns the first record of the database, and thereafter dbm_nextkey() returns the following records. The following code traverses the entire database:

for (key = dbm_firstkey(db); key.dptr != NULL;
    key = dbm_nextkey(db))

The behaviour of () is undefined if the database is modified after a call to dbm_firstkey().

The () function returns the last error condition of the database, or 0 if no error had occurred or had been cleared. The () function clears the error condition of the database.

The () function is used to find the file descriptor associated with the directory file of an open database. Since a directory bitmap file is not used in this implementation, this function returns the file descriptor of the database file opened with dbm_open().

The () function is used to find the file descriptor associated with the page file of an open database. Since a page file is not used in this implementation, this function is implemented as a macro that always returns the (undefined) value DBM_PAGFNO_NOT_AVAILABLE.

The database is closed with the () function. Thereafter, the db handle is invalid.

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.

Upon successful completion, all functions that return int return a value of 0, otherwise a negative value is returned.

Routines that return a datum indicate errors by setting the dptr field to NULL.

The dbm_open() function returns NULL on error, and sets errno appropriately. On success, it returns a handle to the database that should be used as the db argument in the other functions.

The dbm_store() function returns 1 when it is called with a flags value of DBM_INSERT and a record with the specified key already exists.

If an error occurs, the error can be retrieved with dbm_error() and corresponds to those errors described in dbopen(3).

open(2), dbopen(3), hash(3)

May 7, 2016 openbsd