DBM_OPEN(3) | Library Functions Manual | DBM_OPEN(3)

# NAME

`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

# SYNOPSIS

`#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);

# DESCRIPTION

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:

`DBM_INSERT`
  Only insert new keys into the database. Existing key/content pairs are untouched.
`DBM_REPLACE`
  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.

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

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.

# ERRORS

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

# SEE ALSO

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

June 13, 2025 | Debian