SDBM(3) SDBM(3)
NAME
sdbm, dbm_open, dbm_prep, dbm_close, dbm_fetch, dbm_store, dbm_delete,
dbm_firstkey, dbm_nextkey, dbm_hash, dbm_rdonly, dbm_error, dbm_clear-
err, dbm_dirfno, dbm_pagfno - data base subroutines
SYNOPSIS
#include <sdbm.h>
typedef struct {
char *dptr;
int dsize;
} datum;
datum nullitem = { NULL, 0 };
DBM *dbm_open(char *file(1,n), int flags, int mode)
DBM *dbm_prep(char *dirname, char *pagname, int flags, int mode)
void dbm_close(DBM *db)
datum dbm_fetch(DBM *db, key)
int dbm_store(DBM *db, datum key, datum val, int flags)
int dbm_delete(DBM *db, datum key)
datum dbm_firstkey(DBM *db)
datum dbm_nextkey(DBM *db)
long dbm_hash(char *string(3,n), int len)
int dbm_rdonly(DBM *db)
int dbm_error(DBM *db)
dbm_clearerr(DBM *db)
int dbm_dirfno(DBM *db)
int dbm_pagfno(DBM *db)
DESCRIPTION
This package allows an application to maintain a mapping of <key,value>
pairs in(1,8) disk files. This is not to be considered a real database sys-
tem, but is still useful in(1,8) many simple applications built around fast
retrieval of a data value from a key. This implementation uses an
external hashing scheme, called Dynamic Hashing, as described by Per-
Aake Larson in(1,8) BIT 18 (1978) pp. 184-201. Retrieval of any item usu-
ally requires a single disk access. The application interface is com-
patible with the ndbm(3) library.
An sdbm database is kept in(1,8) two files usually given the extensions .dir
and .pag. The .dir file(1,n) contains a bitmap representing a forest of
binary hash trees, the leaves of which indicate data pages in(1,8) 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 sensible output from a
strings(1) command applied to the data file.
In order to allow a process using this package to manipulate 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
dbm_open() or dbm_prep(). Either of these will open(2,3,n) or create the two
necessary files. The difference is that the latter allows explicitly
naming the bitmap and data files whereas dbm_open() will take a base
file(1,n) name and call dbm_prep() with the default extensions. The flags
and mode parameters are the same as for open(2,3,n)(2).
To free the resources occupied while a database handle is active, call
dbm_close().
Given a handle, one can retrieve data associated with a key by using
the dbm_fetch() routine, and associate data with a key by using the
dbm_store() routine.
The values of the flags parameter for dbm_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 dbm_delete() routine.
To retrieve every key in(1,8) the database, use a loop like:
for (key = dbm_firstkey(db); key.dptr != NULL; key = dbm_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 dbm_hash() routine. Doing so will make the database unintelligable
to any other applications that do not use your specialized hash func-
tion.
The following macros are defined in(1,8) the header file:
dbm_rdonly() returns true if(3,n) the database has been opened
read-only.
dbm_error() returns true if(3,n) an I/O error(8,n) has occurred.
dbm_clearerr() allows you to clear(1,3x,3x clrtobot) the error(8,n) flag if(3,n) you think
you know what the error(8,n) was and insist on ignoring it.
dbm_dirfno() returns the file(1,n) descriptor associated with the
bitmap file.
dbm_pagfno() returns the file(1,n) descriptor associated with the
data file.
SEE ALSO
open(2,3,n)(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(1,8) that case is 0. Functions that return a
datum will return nullitem to indicate an error.
As a special case of dbm_store(), if(3,n) it is called with the DBM_INSERT
flag and the key already exists in(1,8) the database, the return value will
be 1.
In general, if(3,n) a function parameter is invalid, errno will be set(7,n,1 builtins) to
EINVAL. If a write(1,2) operation is requested on a read-only database,
errno will be set(7,n,1 builtins) to ENOPERM. If a memory allocation (using malloc(3))
failed, errno will be set(7,n,1 builtins) to ENOMEM. For I/O operation failures errno
will contain the value set(7,n,1 builtins) by the relevant failed system call, either
read(2,n,1 builtins)(2), write(1,2)(2), or lseek(2).
AUTHOR
Ozan S. Yigit
BUGS
The sum of key and value data sizes must not exceed PAIRMAX (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(1,n) 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(1,8) 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(2,n,1 builtins) and) update(7,n) a data-
base at the same time(1,2,n), is to implement a private locking scheme outside
this package and open(2,3,n) and close(2,7,n) the database between lock acquisitions.
It is safe for multiple processes to concurrently access(2,5) a database
read-only.
APPLICATIONS PORTABILITY
For complete source code compatibility with the Berkeley Unix ndbm(3)
library, the sdbm.h header file(1,n) should be installed in(1,8)
/usr/include/ndbm.h.
The nullitem data item, and the dbm_prep(), dbm_hash(), dbm_rdonly(),
dbm_dirfno(), and dbm_pagfno() functions are unique to this package.
1 March 1990 SDBM(3)