NAME
dbm_clearerr,
dbm_close, dbm_delete,
dbm_dirfno, dbm_error,
dbm_fetch, dbm_firstkey,
dbm_nextkey, dbm_open,
dbm_store —
database access functions
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
Database access functions. These functions are implemented using dbopen(3) with a hash(3) database.
datum is declared in
<ndbm.h>:
typedef struct {
char *dptr;
int dsize;
} datum;
The
dbm_open(file,
open_flags, file_mode) function
opens or creates a database file. The file argument is
the basename of the file containing the database; the actual database has a
.db suffix. I.e., if file is
"/home/me/mystuff" then the actual
database is in the file /home/me/mystuff.db. The
open_flags and file_mode
arguments are passed to open(2). (O_RDWR |
O_CREAT) is a typical value for
open_flags; 0660 is a typical
value for file_mode. O_WRONLY
is not allowed in open_flags. The pointer returned by
dbm_open() identifies the database and is the
db argument to the other functions. The
dbm_open() function returns
NULL and sets errno if there
were any errors.
The
dbm_close(db)
function closes the database.
The
dbm_store(db,
key, content,
store_mode) function inserts or replaces an entry in
the database. The store_mode argument is either
DBM_INSERT or DBM_REPLACE.
If store_mode is DBM_INSERT
and the database already contains an entry for key,
that entry is not replaced. Otherwise the entry is replaced or inserted. The
dbm_store() function normally returns zero but
returns 1 if the entry could not be inserted (because
store_mode is DBM_INSERT, and
an entry with key already exists) or returns -1 and
sets errno if there were any errors.
The
dbm_fetch(db,
key) function returns NULL or
the content corresponding to
key.
The
dbm_delete(db,
key) function deletes the entry for
key. The dbm_delete() function
normally returns zero but returns 1 if there was no entry with
key in the database or returns -1 and sets
errno if there were any errors.
The
dbm_firstkey(db)
function returns the first key in the database. The
dbm_nextkey(db)
function returns subsequent keys. The
db_firstkey()
function must be called before dbm_nextkey(). The
order in which keys are returned is unspecified and may appear random. The
dbm_nextkey() function returns
NULL after all keys have been returned.
The
dbm_error(db)
function returns the errno value of the most recent
error. The
dbm_clearerr(db)
function resets this value to 0 and returns 0.
The
dbm_dirfno(db)
function returns the file descriptor to the database.
LEGACY SYNOPSIS
#include <fcntl.h>
#include <ndbm.h>
The include file
<ndbm.h> is necessary for
all functions.
DBM *
dbm_open(const
char *file, int open_flags, int
file_mode);;
file_mode has type int.
SEE ALSO
STANDARDS
These functions (except dbm_dirfno()) are
included in the Version 2 of the Single UNIX
Specification (“SUSv2”).