ndbm(3)                C LIBRARY FUNCTIONS                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.   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  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.



             Last change: BSD Compatibility Package             1

ndbm(3)                C LIBRARY FUNCTIONS                ndbm(3)



     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  read-
     ing 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  nega-
     tive  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.   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 hash-
     ing function.  There are no interlocks and no reliable cache
     flushing; thus concurrent updating and reading is risky.









             Last change: BSD Compatibility Package             2