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