dbm(3X) — GENIX 4.1A



      DBM(3X)                 GENIX Programmer's Manual                 DBM(3X)



      NAME
           dbminit, fetch, store, delete, firstkey, nextkey - data base subrou-
           tines

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

           dbminit(file)
           char *file;

           datum fetch(key)
           datum key;

           store(key, content)
           datum key, content;

           delete(key)
           datum key;

           datum firstkey()

           datum nextkey(key)
           datum key;

      DESCRIPTION
           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
           functions are obtained with the loader option -ldbm.

           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 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  creating  zero-length  `.dir'  and
           `.pag' files.)

           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:



      Printed 11/16/83                                                        1



      DBM(3X)                 GENIX Programmer's Manual                 DBM(3X)



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

      DIAGNOSTICS
           All functions that return  an  int  indicate  errors  with  negative
           values.   A  zero return indicates ok.  Routines that return a datum
           indicate errors with a null (0) dptr.

      BUGS
           The `.pag' file will contain holes so  that  its  apparent  size  is
           about  four times its actual content.  Older UNIX systems may create
           real file blocks for these holes when touched.  These  files  cannot
           be  copied by normal means (cp, cat, tp, tar, ar) 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  single  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 firstkey and  nextkey  depends  on  a
           hashing function, not on anything interesting.



























      Printed 11/16/83                                                        2

Museum