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 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 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 9.3