DBM_CLEARERR(3) | Library Functions Manual | DBM_CLEARERR(3)

# NAME

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

# LIBRARY

Standard C Library (libc, -lc)

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

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

# DESCRIPTION

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

The dbm_close() function closes a database.

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

The dbm_store() 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:

DBM_INSERT
  If a record matching key is already present, it is left unchanged.
DBM_REPLACE
  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 dbm_delete() function deletes a record from the database. The key argument is a datum that identifies the record to be deleted.

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

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

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

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

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

# IMPLEMENTATION NOTES

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

# RETURN VALUES

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 occured, its dptr member is a null pointer.

The dbm_store() function returns 0 when then 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 occured, 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.

# ERRORS

No errors are defined.

# SEE ALSO

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

# STANDARDS

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 7.2