db_dbm
NAME
dbm - dbminit, fetch, store, delete, firstkey, nextkey
ndbm - dbm_open, dbm_close, dbm_fetch, dbm_store, dbm_delete,
dbm_firstkey, dbm_nextkey, dbm_error, dbm_clearerr
SYNOPSIS
#define DB_DBM_HSEARCH
#include <db.h>
typedef struct {
char *dptr;
int dsize;
} datum;
DBM FUNCTIONS
int
dbminit(char *file);
datum
fetch(datum key);
int
store(datum key, datum content);
int
delete(datum key);
datum
firstkey(void);
datum
nextkey(datum key);
NDBM FUNCTIONS
DBM *
dbm_open(char *file, int flags, int mode);
void
dbm_close(DBM *db);
datum
dbm_fetch(DBM *db, datum key);
int
dbm_store(DBM *db, datum key, datum content, int flags);
int
dbm_delete(DBM *db, datum key);
datum
dbm_firstkey(DBM *db);
datum
dbm_nextkey(DBM *db);
int
dbm_error(DBM *db);
int
dbm_clearerr(DBM *db);
DESCRIPTION
The dbm and ndbm interfaces to the DB library are intended
to provide source code compatibility for historic applica-
tions. They are not recommended for any other purpose.
The historic dbm and ndbm database format is not sup-
ported, and databases previously built using the real dbm
or ndbm libraries cannot be read by the DB functions.
To compile dbm or ndbm applications, replace the applica-
tion's #include of the dbm or ndbm include file (e.g.,
``#include <dbm.h>'' or ``#include <ndbm.h>'') with the
following two lines:
#define DB_DBM_HSEARCH
#include <db.h>
and recompile. If the application attempts to load
against a dbm library (e.g., ``-ldbm''), remove the
library from the load line.
Keys and contents are described by the datum typedef. A
datum specifies a string of dsize bytes pointed to by
dptr. Arbitrary binary data, as well as normal text
strings, are allowed.
DBM FUNCTIONS
Before a database can be accessed, it must be opened by
dbminit. This will open and/or create the database
file.db. If created, the database file is created
read/write by owner only (as described in chmod(2)) and
modified by the process' umask value at the time of cre-
ation (see umask(2)). The group ownership of created
files is based on the system and directory defaults, and
is not further specified by DB.
Once open, the data stored under a key is accessed by
fetch and data is placed under a key by store. A key (and
its associated contents) is deleted by delete. A linear
pass through all keys in a database may be made, in an
(apparently) random order, by use of firstkey and nextkey.
Firstkey will return the first key in the database. With
any key nextkey will return the next key in the database.
This code will traverse the data base:
for (key = firstkey();
key.dptr != NULL; key = nextkey(key))
NDBM FUNCTIONS
Before a database can be accessed, it must be opened by
dbm_open. This will open and/or create the database file
file.db depending on the flags parameter (see open(2)).
If created, the database file is created with mode mode
(as described in chmod(2)) and modified by the process'
umask value at the time of creation (see umask(2)). The
group ownership of created files is based on the system
and directory defaults, and is not further specified by
DB.
Once open, the data stored under a key is accessed by
dbm_fetch and data is placed under a key by dbm_store.
The flags field can be either DBM_INSERT or DBM_REPLACE.
DBM_INSERT will only insert new entries into the database
and will not change an existing entry with the same key.
DBM_REPLACE will replace an existing entry if it has the
same key. A key (and its associated contents) is deleted
by dbm_delete. A linear pass through all keys in a
database may be made, in an (apparently) random order, by
use of dbm_firstkey and dbm_nextkey. Dbm_firstkey will
return the first key in the database. Dbm_nextkey will
return the next key in the database. This code will tra-
verse the data base:
for (key = dbm_firstkey(db);
key.dptr != NULL; key = dbm_nextkey(db))
Dbm_error returns non-zero when an error has occurred
reading or writing the database. Dbm_clearerr resets the
error condition on the named database.
COMPATIBILITY NOTES
The historic dbm and ndbm libraries created two underlying
database files, traditionally named file.dir and file.pag.
The DB library creates a single database file named
file.db. Applications that are aware of the underlying
database file names may require additional source code
modifications.
The historic dbminit interface required that the underly-
ing ``.dir'' and ``.pag'' files already exist (empty
databases were created by creating zero-length ``.dir''
and ``.pag'' files). Applications that expect to create
databases using this method may require additional source
code modifications.
The historic dbm_dirfno and dbm_pagfno macros are sup-
ported, but will return identical file descriptors as
there is only a single underlying file used by the DB
hashing access method. Applications using both file
descriptors for locking may require additional source code
modifications.
If an application using the ndbm interface exits without
closing the database, it may lose updates because the DB
library buffers all writes. Such applications will
require additional source code modifications to work cor-
rectly with the DB library.
DBM DIAGNOSTICS
The dbminit function returns -1 on failure, setting errno,
and 0 on success.
The fetch function sets the returned datum's dptr field to
NULL on failure, setting errno, and returns a non-NULL
dptr on success.
The store function returns -1 on failure, setting errno,
and 0 on success.
The delete function returns -1 on failure, setting errno,
and 0 on success.
The firstkey function sets the returned datum's dptr field
to NULL on failure, setting errno, and returns a non-NULL
dptr on success.
The nextkey function sets the returned datum's dptr field
to NULL on failure, setting errno, and returns a non-NULL
dptr on success.
NDBM DIAGNOSTICS
The dbm_open function returns NULL on failure, setting
errno, and 0 on success.
The dbm_fetch function sets the returned datum's dptr
field to NULL on failure, setting errno, and returns a
non-NULL dptr on success.
The dbm_store function returns -1 on failure, setting
errno, 0 on success, and 1 if DBM_INSERT was set and the
specified key already existed in the database.
The dbm_delete function returns -1 on failure, setting
errno, and 0 on success.
The dbm_firstkey function sets the returned datum's dptr
field to NULL on failure, setting errno, and returns a
non-NULL dptr on success.
The dbm_nextkey function sets the returned datum's dptr
field to NULL on failure, setting errno, and returns a
non-NULL dptr on success.
The dbm_error function returns -1 on failure, setting
errno, and 0 on success.
The dbm_clearerr function returns -1 on failure, setting
errno, and 0 on success.
ERRORS
The dbminit function may fail and set errno for any of the
errors specified for the following DB and library func-
tions: dbm_close(3) and dbm_open(3).
The fetch function may fail and set errno for any of the
errors specified for the following DB and library func-
tions: dbm_fetch(3) and fprintf(3).
The store function may fail and set errno for any of the
errors specified for the following DB and library func-
tions: dbm_store(3).
The delete function may fail and set errno for any of the
errors specified for the following DB and library func-
tions: dbm_delete(3).
The firstkey function may fail and set errno for any of
the errors specified for the following DB and library
functions: dbm_firstkey(3).
The nextkey function may fail and set errno for any of the
errors specified for the following DB and library func-
tions: dbm_nextkey(3).
The dbm_open function may fail and set errno for any of
the errors specified for the following DB and library
functions: db_open(3), memset(3) and snprintf(3).
The dbm_close function may fail and set errno for any of
the errors specified for the following DB and library
functions: db->close.
The dbm_fetch function may fail and set errno for any of
the errors specified for the following DB and library
functions: db->get and memset(3).
The dbm_store function may fail and set errno for any of
the errors specified for the following DB and library
functions: db->put and memset(3).
The dbm_delete function may fail and set errno for any of
the errors specified for the following DB and library
functions: db->del and memset(3).
The dbm_firstkey function may fail and set errno for any
of the errors specified for the following DB and library
functions: db->cursor and memset(3).
The dbm_nextkey function may fail and set errno for any of
the errors specified for the following DB and library
functions: db->cursor and memset(3).
SEE ALSO
The DB library is a family of groups of functions that
provides a modular programming interface to transactions
and record-oriented file access. The library includes
support for transactions, locking, logging and file page
caching, as well as various indexed access methods. Many
of the functional groups (e.g., the file page caching
functions) are useful independent of the other DB func-
tions, although some functional groups are explicitly
based on other functional groups (e.g., transactions and
logging). For a general description of the DB package,
see db_intro(3).
db_archive(1), db_checkpoint(1), db_deadlock(1), db_dump(1),
db_intro(3), db_load(1), db_recover(1), db_stat(1),
db_appinit(3), db_cursor(3), db_dbm(3), db_lock(3), db_log(3),
db_mpool(3), db_open(3), db_txn(3)