ndbm(3) C LIBRARY FUNCTIONS ndbm(3)
NAME
ndbm: dbmclearerr, dbmclose, dbmdelete, dbmerror,
dbmfetch, dbmfirstkey, dbmnextkey, dbmopen, dbmstore -
data base subroutines
SYNOPSIS
cc [ flag... ] file ... -ldbm
#include <ndbm.h>
typedef struct {
char *dptr;
int dsize;
} datum;
int dbmclearerr(db)
DBM *db;
void dbmclose (db)
DBM *db;
int dbmdelete(db, key)
DBM *db;
datum key;
int dbmerror(db)
DBM *db;
datum dbmfetch(db, key)
DBM *db;
datum key;
datum dbmfirstkey(db)
DBM *db;
datum dbmnextkey(db)
DBM *db;
DBM *dbmopen(file, flags, mode)
char *file;
int flags, mode;
int dbmstore(db, key, content, flags)
DBM *db;
datum key, content;
int flags;
DESCRIPTION
These functions maintain key/content pairs in a data base.
The functions will handle very large (a billion blocks) data
base and will access a keyed item in one or two file system
accesses. This package replaces the earlier dbm(3X)
library, which managed only a single data base. keys and
contents are described by the datum typedef. A datum speci-
fies a string of dsize bytes pointed to by dptr. Arbitrary
binary data, as well as normal ASCII strings, are allowed.
The data base is stored in two files. One file is a direc-
tory containing a bit map and has .dir as its suffix. The
second file contains all data and has .pag as its suffix.
Before a data base can be accessed, it must be opened by
dbmopen. This will open and/or create the files file.dir
and file.pag depending on the flags parameter (see
open(2V)). A data base is closed by calling dbmclose.
Last change: BSD Compatibility Package 1
ndbm(3) C LIBRARY FUNCTIONS ndbm(3)
Once open, the data stored under a key is accessed by
dbmfetch and data is placed under a key by dbmstore. The
flags field can be either DBMINSERT or DBMREPLACE.
DBMINSERT will only insert new entries into the data base
and will not change an existing entry with the same key.
DBMREPLACE will replace an existing entry if it has the
same key. A key (and its associated contents) is deleted by
dbmdelete. A linear pass through all keys in a data base
may be made, in an (apparently) random order, by use of
dbmfirstkey and dbmnextkey. dbmfirstkey will return the
first key in the data base. dbmnextkey will return the
next key in the data base. This code will traverse the data
base:
for (key = dbmfirstkey(db); key.dptr != NULL; key = dbmnextkey(db))
dbmerror returns non-zero when an error has occurred read-
ing or writing the data base. dbmclearerr resets the error
condition on the named data base.
SEE ALSO
open(2), dbm(3X) in the Programmer's Reference Manual.
RETURN VALUE
All functions that return an int indicate errors with nega-
tive values. A zero return indicates no error. Routines
that return a datum indicate errors with a NULL (0) dptr.
If dbmstore is called with a flags value of DBMINSERT and
finds an existing entry with the same key, it returns 1.
NOTES
The .pag file will contain holes so that its apparent size
is about four times its actual content. Older versions of
the UNIX operating system may create real file blocks for
these holes when touched. These files cannot be copied by
normal means (cp(1), cat(1), tar(1), ar(1)) without filling
in the holes. dptr pointers returned by these subroutines
point into static storage that is changed by subsequent
calls. The sum of the sizes of a key/content pair must not
exceed the internal block size (currently 4096 bytes).
Moreover all key/content pairs that hash together must fit
on a single block. dbmstore will return an error in the
event that a disk block fills with inseparable data.
dbmdelete does not physically reclaim file space, although
it does make it available for reuse. The order of keys
presented by dbmfirstkey and dbmnextkey depends on a hash-
ing function. There are no interlocks and no reliable cache
flushing; thus concurrent updating and reading is risky.
Last change: BSD Compatibility Package 2