dbm(3X)          MISCELLANEOUS LIBRARY FUNCTIONS          dbm(3X)



NAME
     dbm:  dbminit, dbmclose,  fetch,  store,  delete,  firstkey,
     nextkey - data base subroutines

SYNOPSIS
     cc [ flag... ] file ...  -ldbm #include <dbm.h>
     typedef struct {
     char *dptr;
     int dsize;
     } datum;
     dbminit(file)
     char *file;
     dbmclose
     datum fetch(key)
     datum key;
     store(key, content)
     datum key, content;
     delete(key)
     datum key;
     datum firstkey
     datum nextkey(key)
     datum key;

DESCRIPTION
     Note: the dbm library has been superceded by ndbm(3), and is
     now   implemented  using  ndbm.   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.   The  func-
     tions are obtained with the loader option -libdbm.  keys and
     contents are described by the datum typedef.  A datum speci-
     fies  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 direc-
     tory 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
     dbminit.   At  the time of this call, the files file.dir and
     file.pag must exist.  An empty database is created by creat-
     ing  zero-length  .dir  and  .pag  files.  A database may be
     closed by calling  dbmclose.   You  must  close  a  database
     before  opening a new one.  Once open, the data stored under
     a key is accessed by fetch and data is placed under a key by
     store.   A  key  (and its associated contents) is deleted by
     delete.  A linear pass through all keys in a database may be
     made,  in  an  (apparently) random order, by use of firstkey
     and nextkey.  firstkey will return  the  first  key  in  the
     database.   With any key nextkey will return the next key in
     the database.  This code will traverse the data base:

          for  (key  =  firstkey;  key.dptr  !=   NULL;   key   =
          nextkey(key))



             Last change: BSD Compatibility Package             1

dbm(3X)          MISCELLANEOUS LIBRARY FUNCTIONS          dbm(3X)



SEE ALSO
     ndbm(3).

RETURN VALUE
     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.

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.
     The sum of the sizes of a key/content pair must  not  exceed
     the  internal  block  size (currently 1024 bytes).  Moreover
     all key/content pairs that hash together must fit on a  sin-
     gle  block.   store will return an error in the event that a
     disk block fills with inseparable  data.   delete  does  not
     physically  reclaim  file  space,  although  it does make it
     available for reuse.  The order of keys presented by  first-
     key  and  nextkey depends on a hashing function, not on any-
     thing interesting.  There are no interlocks and no  reliable
     cache  flushing;  thus  concurrent  updating  and reading is
     risky.



























             Last change: BSD Compatibility Package             2