ndbm(3)                 (BSD Compatibility Package)                 ndbm(3)


   NAME
         ndbm:  dbmclearerr, dbmclose, dbmdelete, dbmerror, dbmfetch,
         dbmfirstkey, dbmnextkey, dbmopen, dbmstore - data base
         subroutines

   SYNOPSIS
         cc [ flag... ] file ... -ldbm

         #include <ndbm.h>

         typedef struct {
               char *dptr;
               int dsize;
         } datum;

         int dbmclearerr(db)
         DBM *db;

         void dbmclose (db)
         DBM *db;

         int dbmdelete(db, key)
         DBM *db;
         datum key;

         int dbmerror(db)
         DBM *db;

         datum dbmfetch(db, key)
         DBM *db;
         datum key;

         datum dbmfirstkey(db)
         DBM *db;

         datum dbmnextkey(db)
         DBM *db;

         DBM *dbmopen(file, flags, mode)
         char *file;
         int flags, mode;

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

   DESCRIPTION
         These functions maintain key/content pairs in a data base.  The
         functions will handle very large (a billion blocks) data base and
         will access a keyed item in one or two file system accesses.  This


   7/91                                                                 Page 1

   ndbm(3)                 (BSD Compatibility Package)                 ndbm(3)


         package replaces the earlier dbm(3X) library, which managed only a
         single data base.

         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 data base can be accessed, it must be opened by dbmopen.
         This will open and/or create the files file.dir and file.pag
         depending on the flags parameter (see open(2V)).

         A data base is closed by calling dbmclose.

         Once open, the data stored under a key is accessed by dbmfetch and
         data is placed under a key by dbmstore.  The flags field can be
         either DBMINSERT or DBMREPLACE.  DBMINSERT will only insert new
         entries into the data base and will not change an existing entry with
         the same key.  DBMREPLACE will replace an existing entry if it has
         the same key.  A key (and its associated contents) is deleted by
         dbmdelete.  A linear pass through all keys in a data base may be
         made, in an (apparently) random order, by use of dbmfirstkey and
         dbmnextkey.  dbmfirstkey will return the first key in the data
         base.  dbmnextkey will return the next key in the data base.  This
         code will traverse the data base:

         for (key = dbmfirstkey(db); key.dptr != NULL; key = dbmnextkey(db))

         dbmerror returns non-zero when an error has occurred reading or
         writing the data base.  dbmclearerr resets the error condition on
         the named data base.

   SEE ALSO
         open(2), dbm(3X) in the Programmer's Reference Manual.

   RETURN VALUE
         All functions that return an int indicate errors with negative
         values.  A zero return indicates no error.  Routines that return a
         datum indicate errors with a NULL (0) dptr.  If dbmstore is called
         with a flags value of DBMINSERT and finds an existing entry with the
         same key, it returns 1.

   NOTES
         The .pag file will contain holes so that its apparent size is about
         four times its actual content.  Older versions of the UNIX operating
         system may create real file blocks for these holes when touched.
         These files cannot be copied by normal means (cp(1), cat(1), tar(1),
         ar(1)) without filling in the holes.



   Page 2                                                                 7/91

   ndbm(3)                 (BSD Compatibility Package)                 ndbm(3)


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

         The sum of the sizes of a key/content pair must not exceed the
         internal block size (currently 4096 bytes).  Moreover all key/content
         pairs that hash together must fit on a single block.  dbmstore will
         return an error in the event that a disk block fills with inseparable
         data.

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

         The order of keys presented by dbmfirstkey and dbmnextkey depends
         on a hashing function.

         There are no interlocks and no reliable cache flushing; thus
         concurrent updating and reading is risky.




































   7/91                                                                 Page 3