packages icon
 NDBM(3)                       1987                        NDBM(3)

      ndbm, dbm_open, dbm_close, dbm_fetch, dbm_store, dbm_delete,
      dbm_firstkey,  dbm_nextkey,  dbm_error,  dbm_clearerr - data
      base subroutines

      #include <ndbm.h>

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

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

      void dbm_close (db)
      DBM *db;

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

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

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

      datum dbm_firstkey(db)
      DBM *db;

      datum dbm_nextkey(db)
      DBM *db;

      int dbm_error(db)
      DBM *db;

      int dbm_clearerr(db)
      DBM *db;

      These functions maintain key/content pairs in a  data  base.
      The  functions  will  handle  very  large (a billion blocks)
      databases 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 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 suf-

      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

      A database is closed by calling dbm_close.

      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.  This code will traverse the
      data base:

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

      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.

      ar(1V), cat(1V), cp(1), tar(1), open(2V), dbm(3X)

      All functions that return an int indicate errors with  nega-
      tive  values.   A  zero return indicates no error.  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.

      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(1V),  tar(1),  ar(1V))   without
      filling in the holes.

      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  sin-
      gle  block.   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

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

 November                 Last change: 24                        3