dbm
Purpose
Performs data base operations.
Library
Database Library (libdbm.a)
Syntax
int dbminit (file) datum firstkey ( )
char *file;
datum nextkey (key)
datum fetch (key) datum key;
datum key;
typedef struct
int store (key, content) {
datum key, content; char *dptr;
int dsize;
int delete (key) } datum;
datum key;
Description
The dbm subroutines maintain a data base of key-content
pairs. These subroutines can handle very large data
bases and access keyed items in one or two file-system
accesses.
The key parameter is a pointer to data specified by the
content parameter. The sum of the sizes of the key-
content pairs must not exceed the internal block size of
512 bytes. All key-content pairs that hash together must
fit on a single block. The store subroutine returns an
error if a disk block fills with inseparable data.
The key and the content parameters are described by the
typedef datum structure. The datum structure sets up a
string of bytes. The length of the string is specified
by the dsize field. The string is pointed to by the
dptr field. The dptr pointers that are returned by these
subroutines point to static storage that changes with
subsequent calls. You can use binary data or normal
ASCII strings.
The data base is stored in two files. One file is a
directory that contains a bit map and is suffixed with
.dir. The second file contains all data and is suffixed
with .pag. The .pag file contains holes that increases
its apparent size to about four times its actual size.
You cannot copy a .pag file using the standard utilities
such as cp and cat without first filling these holes.
Before you can access a data base, you must open the data
base with the dbminit subroutine. The file, .dir, and
.pag files must already exist before you call the dbminit
subroutine. You can create an empty data base by cre-
ating zero-length .dir and .pag files.
After the data base is opened with the dbminit subrou-
tine, you can use the fetch subroutine to access the data
that is is pointed to by the key parameter. You can use
the store subroutine to write the data specified by the
content parameter to a file and to specify the key to be
used to access that data with the key parameter.
The delete subroutine removes the key specified by the
key parameter and the data to which that key points. The
delete subroutine does not actually reclaim the file
space, but it does make it available for reuse.
The firstkey and nextkey subroutines make a linear pass
through all of the keys in a data base. The firstkey
subroutine returns the first key in the data base. The
nextkey subroutine returns the next key in the data base.
The following code makes a linear pass through a data
base:
for (key = firstkey(); key.dptr != NULL; key = nextkey(key))
{
. . .
}
The order of keys that are presented to firstkey and
nextkey depend on the hashing function.
Return Value
All of the dbm subroutines that return an int value
return 0 upon successful completion, and they return a
negative value if an error occurs. Subroutines that
return a datum value indicate an error by setting the
dptr field to NULL.