ndbm(3)            UNIX System V(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 package replaces the
      earlier dbm(3X) library, which managed only a single data base.



10/89                                                                    Page 1

ndbm(3)            UNIX System V(BSD Compatibility Package)             ndbm(3)


      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.

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





Page 2                                                                    10/89

ndbm(3)            UNIX System V(BSD Compatibility Package)             ndbm(3)


      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.









































10/89                                                                    Page 3