sdbm(3)

NAME

sdbm, sdbm_open, sdbm_prep, sdbm_close, sdbm_fetch,
sdbm_store, sdbm_delete, sdbm_firstkey, sdbm_nextkey,
sdbm_hash, sdbm_rdonly, sdbm_error, sdbm_clearerr,
sdbm_dirfno, sdbm_pagfno - data base subroutines

SYNOPSIS

#include <sdbm.h>
typedef struct {
     char *dptr;
     int dsize;
} datum;
datum nullitem = { NULL, 0 };
DBM *sdbm_open(char *file, int flags, int mode)
DBM  *sdbm_prep(char  *dirname,  char *pagname, int flags,
int mode)
void sdbm_close(DBM *db)
datum sdbm_fetch(DBM *db, key)
int sdbm_store(DBM *db, datum key, datum val, int flags)
int sdbm_delete(DBM *db, datum key)
datum sdbm_firstkey(DBM *db)
datum sdbm_nextkey(DBM *db)
long sdbm_hash(char *string, int len)
int sdbm_rdonly(DBM *db)
int sdbm_error(DBM *db)
sdbm_clearerr(DBM *db)
int sdbm_dirfno(DBM *db)
int sdbm_pagfno(DBM *db)

DESCRIPTION

This package allows an application to maintain a mapping
of <key,value> pairs in disk files. This is not to be
considered a real database system, but is still useful in
many simple applications built around fast retrieval of a
data value from a key. This implementation uses an exter
nal hashing scheme, called Dynamic Hashing, as described
by Per-Aake Larson in BIT 18 (1978) pp. 184-201.
Retrieval of any item usually requires a single disk
access. The application interface is compatible with the
ndbm(3) library.

An sdbm database is kept in two files usually given the
extensions .dir and .pag. The .dir file contains a bitmap representing a forest of binary hash trees, the leaves of
which indicate data pages in the .pag file.

The application interface uses the datum structure to
describe both keys and values. A datum specifies a byte sequence of dsize size pointed to by dptr. If you use ASCII strings as keys or values, then you must decide whether or not to include the terminating NUL byte which
sometimes defines strings. Including it will require
larger database files, but it will be possible to get sen
sible output from a strings(1) command applied to the data file.

In order to allow a process using this package to manipu
late multiple databases, the applications interface always
requires a handle, a DBM *, to identify the database to be manipulated. Such a handle can be obtained from the only
routines that do not require it, namely sdbm_open() or sdbm_prep(). Either of these will open or create the two necessary files. The difference is that the latter allows
explicitly naming the bitmap and data files whereas
sdbm_open() will take a base file name and call sdbm_prep() with the default extensions. The flags and mode parameters are the same as for open(2).

To free the resources occupied while a database handle is
active, call sdbm_close().

Given a handle, one can retrieve data associated with a
key by using the sdbm_fetch() routine, and associate data with a key by using the sdbm_store() routine.

The values of the flags parameter for sdbm_store() can be either DBM_INSERT, which will not change an existing entry with the same key, or DBM_REPLACE, which will replace an existing entry with the same key. Keys are unique within
the database.

To delete a key and its associated value use the
sdbm_delete() routine.

To retrieve every key in the database, use a loop like:

for (key = sdbm_firstkey(db); key.dptr != NULL; key =

sdbm_nextkey(db))

;

The order of retrieval is unspecified.

If you determine that the performance of the database is
inadequate or you notice clustering or other effects that
may be due to the hashing algorithm used by this package,
you can override it by supplying your own sdbm_hash() rou tine. Doing so will make the database unintelligable to
any other applications that do not use your specialized
hash function.

The following macros are defined in the header file:

sdbm_rdonly() returns true if the database has been opened read-only.

sdbm_error() returns true if an I/O error has occurred.

sdbm_clearerr() allows you to clear the error flag if you think you know what the error was and insist
on ignoring it.

sdbm_dirfno() returns the file descriptor associ ated with the bitmap file.

sdbm_pagfno() returns the file descriptor associ ated with the data file.

SEE ALSO

open(2).

DIAGNOSTICS

Functions that return a DBM * handle will use NULL to
indicate an error. Functions that return an int will use
-1 to indicate an error. The normal return value in that
case is 0. Functions that return a datum will return nul litem to indicate an error.

As a special case of sdbm_store(), if it is called with the DBM_INSERT flag and the key already exists in the database, the return value will be 1.

In general, if a function parameter is invalid, errno will
be set to EINVAL. If a write operation is requested on a read-only database, errno will be set to ENOPERM. If a memory allocation (using malloc(3)) failed, errno will be set to ENOMEM. For I/O operation failures errno will con tain the value set by the relevant failed system call,
either read(2), write(2), or lseek(2).

AUTHOR

Ozan S. Yigit

BUGS

The sum of key and value data sizes must not exceed PAIR
MAX (1008 bytes).

The sum of the key and value data sizes where several keys
hash to the same value must fit within one bitmap page.

The .pag file will contain holes, so its apparent size is
larger than its contents. When copied through the
filesystem the holes will be filled.

The contents of datum values returned are in volatile
storage. If you want to retain the values pointed to, you
must copy them immediately before another call to this
package.

The only safe way for multiple processes to (read and)
update a database at the same time, is to implement a pri
vate locking scheme outside this package and open and
close the database between lock acquisitions. It is safe
for multiple processes to concurrently access a database
read-only.

APPLICATIONS PORTABILITY

For complete source code compatibility with the Berkeley
Unix ndbm(3) library, the sdbm.h header file should be installed in /usr/include/ndbm.h.

The nullitem data item, and the sdbm_prep(), sdbm_hash(), sdbm_rdonly(), sdbm_dirfno(), and sdbm_pagfno() functions are unique to this package.

1 March 1990 SDBM(3)