NDBM(3)                   OpenBSD Programmer's Manual                  NDBM(3)

NAME
     dbm_clearerr, dbm_close, dbm_delete, dbm_dirfno, dbm_error, dbm_fetch,
     dbm_firstkey, dbm_nextkey, dbm_open, dbm_pagfno, dbm_rdonly, dbm_store -
     database access methods

SYNOPSIS
     #include <ndbm.h>

     int
     dbm_clearerr(DBM *db);

     void
     dbm_close(DBM *db);

     int
     dbm_delete(DBM *db, datum key);

     int
     dbm_dirfno(DBM *db);

     int
     dbm_error(DBM *db);

     datum
     dbm_fetch(DBM *db, datum key);

     datum
     dbm_firstkey(DBM *db);

     datum
     dbm_nextkey(DBM *db);

     DBM *
     dbm_open(const char *file, int flags, mode_t mode);

     int
     dbm_pagfno(DBM *db);

     int
     dbm_rdonly(DBM *db);

     int
     dbm_store(DBM *db, datum key, datum content, int store_mode);

DESCRIPTION
     These functions provide a ndbm-compatible interface to the database ac-
     cess 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 da-
     ta.  The key and the content data are described by the datum data struc-
     ture:

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

     The dbm_open() function is used to open a database in the file named by
     file, suffixed with DBM_SUFFIX (`.db').  If necessary, the file is creat-
     ed with mode mode.  Access to this file depends on the flags parameter
     (see open(2)).  Read-only access may be indicated by specifying
     DBM_RDONLY.  The dbm_rdonly() function may be used to determine if a
     database is opened for read-only access.

     Once the database is open, dbm_fetch() is used to retrieve the data con-
     tent associated with the key key.  Similarly, dbm_store() is used to
     store the content data with the key key.  When storing, the store_mode
     parameter must be one of:

           DBM_INSERT   Only insert new keys into the database.  Existing
                        key/content pairs are untouched.

           DBM_REPLACE  Replace any existing entry with the same key.  Any
                        previously stored records with the same key are lost.

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

     The functions dbm_firstkey() and dbm_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 dbm_firstkey() function returns
     the first record of the database, and thereafter dbm_nextkey() returns
     the following records.  The following code traverses the entire database:

           for (key = dbm_firstkey(db); key.dptr != NULL;
               key = dbm_nextkey(db))

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

     The dbm_error() function returns the last error condition of the
     database, or 0 if no error had occurred or had been cleared.  The
     dbm_clearerr() function clears the error condition of the database.

     The dbm_dirfno() function is used to find the file descriptor associated
     with the directory file of an open database.  Since a directory bitmap
     file is not used in this implementation, this function returns the file
     descriptor of the database file opened with dbm_open().

     The dbm_pagfno() function is used to find the file descriptor associated
     with the page file of an open database.  Since a page file is not used in
     this implementation, this function is implemented as a macro that always
     returns the (undefined) value DBM_PAGFNO_NOT_AVAILABLE.

     The database is closed with the dbm_close() function.  Thereafter, the db
     handle is invalid.

   Implementation notes
     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
     Upon successful completion, all functions that return int return a value
     of 0, otherwise a negative value is returned.

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

     The dbm_open() function returns NULL on error, and sets errno appropri-
     ately.  On success, it returns a handle to the database that should be
     used as the db argument in the other functions.

     The dbm_store() function returns 1 when it is called with a flags value
     of DBM_INSERT and a record with the specified key already exists.

ERRORS
     If an error occurs, the error can be retrieved with dbm_error() and cor-
     responds to those errors described in db(3).

SEE ALSO
     open(2), db(3), dbm(3), hash(3)

OpenBSD 4.5                      May 31, 2007                                3