ndbm(3C) ndbm(3C)
NAME
ndbm: dbmclearerr, dbmclose, dbmdelete, dbmerror, dbmfetch,
dbmfirstkey, dbmnextkey, dbmopen, dbmstore - database functions
SYNOPSIS
#include <ndbm.h>
int dbmclearerr(DBM *db);
void dbmclose(DBM *db);
int dbmdelete(DBM *db, datum key);
int dbmerror(DBM *db);
datum dbmfetch(DBM *db, datum key);
datum dbmfirstkey(DBM *db);
datum dbmnextkey(DBM *db);
DBM *dbmopen(const char *file, int openflags, modet filemode);
int dbmstore(DBM *db, datum key, datum content, int storemode);
DESCRIPTION
These functions create, access and modify a database.
A datum consists of at least two members, dptr and dsize. The dptr
member points to an object that is dsize bytes in length. Arbitrary
binary data, as well as character strings, may be stored in the object
pointed to by dptr.
The database is stored in two files. One file is a directory contain-
ing a bit map of keys and has .dir as its suffix. The second file con-
tains all data and has .pag as its suffix.
The dbmopen() function opens a database. The file argument to the
function is the pathname of the database. The function opens two files
named file.dir and file.pag. The openflags argument has the same
meaning as the flags argument of open() except that a database opened
for write-only access opens the files for read and write access and
the behavior of the OAPPEND flag is unspecified. The filemode argu-
ment has the same meaning as the third argument of open().
The dbmclose() function closes a database. The argument db must be a
pointer to a dbm structure that has been returned from a call to
dbmopen().
Page 1 Reliant UNIX 5.44 Printed 11/98
ndbm(3C) ndbm(3C)
The dbmfetch() function reads a record from a database. The argument
db is a pointer to a database structure that has been returned from a
call to dbmopen(). The argument key is a datum that has been initial-
ized by the application program to the value of the key that matches
the key of the record the program is fetching.
The dbmstore() function writes a record to a database. The argument
db is a pointer to a database structure that has been returned from a
call to dbmopen(). The argument key is a datum that has been initial-
ized by the application program to the value of the key that identi-
fies (for subsequent reading, writing or deleting) the record the pro-
gram is writing. The argument content is a datum that has been ini-
tialized by the application program to the value of the record the
program is writing. The argument storemode controls whether
dbmstore() replaces any pre-existing record that has the same key
that is specified by the key argument. The application program must
set storemode to either DBMINSERT or DBMREPLACE. If the database
contains a record that matches the key argument and storemode is
DBMREPLACE, the existing record is replaced with the new record. If
the database contains a record that matches the key argument and
storemode is DBMINSERT, the existing record is not replaced with the
new record. If the database does not contain a record that matches the
key argument and storemode is either DBMINSERT or DBMREPLACE, the
new record is inserted in the database.
The dbmdelete() function deletes a record and its key from the data-
base. The argument db is a pointer to a database structure that has
been returned from a call to dbmopen(). The argument key is a datum
that has been initialized by the application program to the value of
the key that identifies the record the program is deleting.
The dbmfirstkey() function returns the first key in the database. The
argument db is a pointer to a database structure that has been
returned from a call to dbmopen().
The dbmnextkey() function returns the next key in the database. The
argument db is a pointer to a database structure that has been
returned from a call to dbmopen(). The dbmfirstkey() function must
be called before calling dbmnextkey(). Subsequent calls to
dbmnextkey() return the next key until all of the keys in the data-
base have been returned.
The dbmerror() function returns the error condition of the database.
The argument db is a pointer to a database structure that has been
returned from a call to dbmopen().
The dbmclearerr() function clears the error condition of the data-
base. The argument db is a pointer to a database structure that has
been returned from a call to dbmopen().
These database functions support key/content pairs of at least 1024
bytes.
Page 2 Reliant UNIX 5.44 Printed 11/98
ndbm(3C) ndbm(3C)
RETURN VALUE
The dbmstore() and dbmdelete() functions return 0 when they succeed
and a negative value when they fail.
The dbmstore() function returns 1 if it is called with a flags value
of DBMINSERT and the function finds an existing record with the same
key.
The dbmerror() function returns 0 if the error condition is not set
and returns a non-zero value if the error condition is set.
The return value of dbmclearerr() is unspecified.
The dbmfirstkey() and dbmnextkey() functions return a key datum.
When the end of the database is reached, the dptr member of the key is
a null pointer. If an error is detected, the dptr member of the key is
a null pointer and the error condition of the database is set.
The dbmfetch() function returns a content datum. If no record in the
database matches the key or if an error condition has been detected in
the database, the dptr member of the content is a null pointer.
The dbmopen() function returns a pointer to a database structure. If
an error is detected during the operation, dbmopen() returns a
(DBM *)0.
ERRORS
No errors are defined.
APPLICATION USAGE
The following code can be used to traverse the database:
for(key = dbmfirstkey(db); key.dptr != NULL; key = dbmnextkey(db))
The dbm functions provided in this library should not be confused in
any way with those of a general-purpose database management system.
These functions do not provide for multiple search keys per entry,
they do not protect against multi-user access (in other words they do
not lock records or files), and they do not provide the many other
useful database functions that are found in more robust database
management systems. Creating and updating databases by use of these
functions is relatively slow because of data copies that occur upon
hash collisions. These functions are useful for applications requiring
fast lookup of relatively static information that is to be indexed by
a single key.
The dptr pointers returned by these functions may point into static
storage that may be changed by subsequent calls.
The dbmdelete() function does not physically reclaim file space,
although it does make it available for reuse.
Page 3 Reliant UNIX 5.44 Printed 11/98
ndbm(3C) ndbm(3C)
After calling dbmstore() or dbmdelete() during a pass through the
keys by dbmfirstkey() and dbmnextkey(), the application should reset
the database by calling dbmfirstkey() before again calling
dbmnextkey().
SEE ALSO
open(2), ndbm(5).
Page 4 Reliant UNIX 5.44 Printed 11/98