OpenBSD manual page server

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_storedatabase access methods

#include <ndbm.h>

dbm_clearerr(DBM *db);

dbm_close(DBM *db);

dbm_delete(DBM *db, datum key);

dbm_dirfno(DBM *db);

dbm_error(DBM *db);

dbm_fetch(DBM *db, datum key);

dbm_firstkey(DBM *db);

dbm_nextkey(DBM *db);

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

dbm_pagfno(DBM *db);

dbm_rdonly(DBM *db);

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 dbm_open() 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 dbm_rdonly() function may be used to determine if a database is opened for read-only access.

Once the database is open, dbm_fetch() is used to retrieve the data content associated with the key key. Similarly, dbm_store() 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 dbm_delete() function removes the key key and its associated content from the database.

The functions dbm_firstkey() 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 dbm_nextkey() is undefined if the database is modified after a call to dbm_firstkey().

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

The dbm_dirfno() 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 dbm_pagfno() 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 dbm_close() 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-current