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