NDBM(3B)                                                              NDBM(3B)


NAME
     ndbm: dbm_open, dbm_open64, dbm_close, dbm_close64, dbm_fetch,
     dbm_fetch64, dbm_store, dbm_store64, dbm_delete, dbm_delete64,
     dbm_firstkey, dbm_firstkey64, dbm_nextkey, dbm_nextkey64, dbm_error,
     dbm_error64, dbm_clearerr , dbm_clearerr64 - data base subroutines

SYNOPSIS
     #include <ndbm.h>

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

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

     DBM64 *dbm_open64(const char *file, int flags, mode_t mode);

     void dbm_close(DBM *db);

     void dbm_close64(DBM64 *db);

     datum dbm_fetch(DBM *db, datum key);

     datum dbm_fetch64(DBM64 *db, datum key);

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

     int dbm_store64(DBM64 *db, datum key, datum content, int flags);

     int dbm_delete(DBM *db, datum key);

     int dbm_delete64(DBM64 *db, datum key);

     datum dbm_firstkey(DBM *db);

     datum dbm_firstkey64(DBM64 *db);

     datum dbm_nextkey(DBM *db);

     datum dbm_nextkey64(DBM64 *db);

     int dbm_error(DBM *db);

     int dbm_error64(DBM64 *db);

     int dbm_clearerr(DBM *db);

     int dbm_clearerr64(DBM64 *db);


DESCRIPTION
     These functions maintain key/content pairs in a data base.  The ndbm
     functions will handle very large (a billion blocks) databases and will
     access a keyed item in one or two file system accesses.  The ndbm64
     functions are identical to the ndbm routines except that they can be used
     to operate on databases larger than 2 Gigabytes.  This package replaces
     the earlier dbm(3B) library, which managed only a single database.

     Keys and contents are described by the datum typedef.  A datum specifies
     a string of dsize bytes pointed to by dptr. Arbitrary binary data, as
     well as normal ASCII strings, are allowed.  The data base is stored in
     two files.  One file is a directory containing a bit map and has `.dir'
     as its suffix.  The second file contains all data and has `.pag' as its
     suffix.

     Before a database can be accessed, it must be opened by dbm_open.  This
     will open and/or create the files file.dir and file.pag depending on the
     flags parameter (see open(2)).

     Once open, the data stored under a key is accessed by dbm_fetch and data
     is placed under a key by dbm_store.  The flags field can be either
     DBM_INSERT or DBM_REPLACE. DBM_INSERT will only insert new entries into
     the database and will not change an existing entry with the same key.
     DBM_REPLACE will replace an existing entry if it has the same key.  A key
     (and its associated contents) is deleted by dbm_delete.  A linear pass
     through all keys in a database may be made, in an (apparently) random
     order, by use of dbm_firstkey and dbm_nextkey.  Dbm_firstkey will return
     the first key in the database.  Dbm_nextkey will return the next key in
     the database.  The following code will traverse the data base:

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


     Dbm_error returns non-zero when an error has occurred reading or writing
     the database.  Dbm_clearerr resets the error condition on the named
     database.

DIAGNOSTICS
     All functions that return an int indicate errors with negative values.  A
     zero return indicates ok.  Routines that return a datum indicate errors
     with a null (0) dptr. If dbm_store called with a flags value of
     DBM_INSERT finds an existing entry with the same key it returns 1.

     Some error conditions will set errno. These are:  ENOMEM: runtime memory
     allocation failed; EPERM: file permissions don't match the process
     euid/egid permissions; EINVAL: key+data sizes for dbm_store exceed the
     internal block size; EFBIG: hash table overflow would cause the maximum
     dbm file size to be exceeded.


SEE ALSO
     dbm(3B) and Berkeley db: dbopen(3)

BUGS
     The `.pag' file is designed to contain holes in files.  The EFS file
     system does not implement holes, so the file will frequently be
     significantly larger than the actual content.

     Dptr pointers returned by these subroutines point into static storage
     that is changed by subsequent calls.

     dbm databases may not be portable across machines with different
     alignment restrictions or different byte sexes.

     Dptr pointers returned by these subroutines point into possibly non word
     aligned storage. You cannot assume that you can cast the Dptr pointer
     into an arbitrary data type and dereference it.  This is a general rule
     in ANSI-C rather than dbm specific, but users often hit it while using
     dbm.

     The sum of the sizes of a key/content pair must not exceed the internal
     block size minus the dbm small book-keeping overhead (currently: _PBLKSIZ
     - 6 = 1018 bytes).  Moreover all key/content pairs that hash together
     must fit on a single block.  For a dbm-like implementation with much less
     size limitations, check out dbopen(3) (Berkeley DB).

     Dbm_store will return an error in the event that a disk block fills with
     inseparable data.

     Dbm_delete does not physically reclaim file space, although it does make
     it available for reuse.

     The order of keys presented by dbm_firstkey and dbm_nextkey depends on a
     hashing function, not on anything interesting.


                                                                        Page 3