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

NAME
     ndbm - 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, int mode);

     int
     dbm_pagfno(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 {
                   char *dptr;
                   int 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 created
     with mode mode. Access to this file depends on the flags parameter (see
     open(2)).  Read-only access may be indicated by specifying DBM_READONLY.

     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 pre-
                        viously 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 datbase 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),  hash(3)

OpenBSD 2.6                      May 13, 1998                                2