NAME    [Toc]    [Back]

     dbminit, dbmclose, fetch, store, delete, firstkey, nextkey -
database
     subroutines

SYNOPSIS    [Toc]    [Back]

     #include <dbm.h>

     int
     dbminit(const char *file);

     int
     dbmclose(void);

     datum
     fetch(datum key);

     int
     store(datum key, datum content);

     int
     delete(datum key);

     datum
     firstkey(void);

     datum
     nextkey(datum key);

DESCRIPTION    [Toc]    [Back]

     These  functions  provide  a dbm-compatible interface to the
database access
     methods described in  db(3).   Each  unique  record  in  the
database is a
     key/content  pair,  the components of which may be any arbitrary binary data.
  The key and the content data are described by the datum
data structure:


           typedef struct {
                   void *dptr;
                   size_t dsize;
           } datum

     The  dbminit()  function is used to open a database.  Before
the call to
     dbminit(), the files file.pag and file.dir must exist.   The
user is responsible
  for creating the zero-length .pag and .dir files.

     Once the database is open, fetch() is used to  retrieve  the
data content
     associated  with  the  specified key.  Similarly, store() is
used to store
     the content data with the specified key.

     The delete() function removes the specified key and its  associated content
 from the database.

     The  functions  firstkey() and nextkey() are used to iterate
over all of
     the records in the database.  Each record  will  be  reached
exactly once,
     but in no particular order.  The firstkey() function returns
the first
     record of the database, and thereafter nextkey() returns the
following
     records.  The following code traverses the entire database:

       for  (key  =  firstkey();  key.dptr  !=  NULL;  key = nextkey(key))

     The behaviour of nextkey() is undefined if the  database  is
modified after
     a call to firstkey().

     The  database  is  closed  with the dbmclose() function (you
must close a
     database before opening a new one).

   Implementation notes    [Toc]    [Back]
     The underlying database is a hash(3) database with a  bucket
size of 4096,
     a  filling  factor of 40, default hashing function and cache
size, and uses
     the host's native byte order.

RETURN VALUES    [Toc]    [Back]

     Upon successful completion, all functions  that  return  int
return a value
     of 0, otherwise a negative value is returned.

     Functions that return a datum indicate errors by setting the
dptr field
     to NULL.

SEE ALSO    [Toc]    [Back]

     db(3), hash(3), ndbm(3)

BUGS    [Toc]    [Back]

     Because the dbm routines  are  implemented  on  top  of  the
db(3), only a single
  file, file.pag, is used to actually store the database.
The references
 to file.dir are  purely  for  backwards  compatibility
with historic
     implementations.

OpenBSD      3.6                        February     14,     1999