DBM_CLEARERR(3) Library Functions Manual DBM_CLEARERR(3)

dbm_clearerr, dbm_close, dbm_delete, dbm_dirfno, dbm_error, dbm_fetch, dbm_firstkey, dbm_nextkey, dbm_open, dbm_store, ndbm — database functions

Standard C Library (libc, -lc)

#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 open_flags, mode_t file_mode);

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

The ndbm facility provides access to hash database files.

Two data types are fundamental to the ndbm facility. DBM serves as a handle to a database. It is an opaque type.

The other data type is datum, which is a structure type which includes the following members:

void *  dptr
size_t  dsize

A datum is thus given by dptr pointing at an object of dsize bytes in length.

The () function opens a database. The file argument is the pathname which the actual database file pathname is based on. This implementation uses a single file with the suffix .db appended to file. The open_flags argument has the same meaning as the flags argument to open(2) except that when opening a database for write-only access the file is opened for read/write access, and the O_APPEND flag must not be specified. The file_mode argument has the same meaning as the mode argument to open(2).

For the following functions, the db argument is a handle previously returned by a call to ().

The () function closes a database.

The () function retrieves a record from the database. The key argument is a datum that identifies the record to be fetched.

The () function stores a record into the database. The key argument is a datum that identifies the record to be stored. The content argument is a datum that specifies the value of the record to be stored. The store_mode argument specifies the behavior of dbm_store() if a record matching key is already present in the database, db. store_mode must be one of the following:

If a record matching key is already present, it is left unchanged.
If a record matching key is already present, its value is replaced by content.

If no record matching key is present, a new record is inserted regardless of store_mode.

The () function deletes a record from the database. The key argument is a datum that identifies the record to be deleted.

The () function returns the first key in the database.

The () function returns the next key in the database. In order to be meaningful, it must be preceded by a call to dbm_firstkey().

The () function returns the error indicator of the database.

The () function clears the error indicator of the database.

The () function returns the file descriptor of the underlying database file.

The ndbm facility is implemented on top of the hash(3) access method of the db(3) database facility.

The dbm_open() function returns a pointer to a DBM when successful; otherwise a null pointer is returned.

The dbm_close() function returns no value.

The dbm_fetch() function returns a content datum; if no record matching key was found or if an error occurred, its dptr member is a null pointer.

The dbm_store() function returns 0 when the record was successfully inserted; it returns 1 when called with store_mode being DBM_INSERT and a record matching key is already present; otherwise a negative value is returned.

The dbm_delete() function returns 0 when the record was successfully deleted; otherwise a negative value is returned.

The dbm_firstkey() and dbm_nextkey() functions return a key datum. When the end of the database is reached or if an error occurred, its dptr member is a null pointer.

The dbm_error() function returns 0 if the error indicator is clear; if the error indicator is set a non-zero value is returned.

The dbm_clearerr() function always returns 0.

The dbm_dirfno() function returns the file descriptor of the underlying database file.

No errors are defined.

open(2), db(3), hash(3)

The dbm_clearerr(), dbm_close(), dbm_delete(), dbm_error(), dbm_fetch(), dbm_firstkey(), dbm_nextkey(), dbm_open(), and dbm_store() functions conform to X/Open Portability Guide Issue 4, Version 2 (“XPG4.2”) and Version 2 of the Single UNIX Specification (“SUSv2”). The dbm_dirfno() function is an extension.

May 5, 2010 NetBSD 11.0