packages icon



 SDBM(3)                                                             SDBM(3)
                                1 March 1990



 NAME
      sdbm, sdbm_open, sdbm_prep, sdbm_close, sdbm_fetch, sdbm_store,
      sdbm_delete, sdbm_exists, sdbm_firstkey, sdbm_nextkey, sdbm_hash,
      sdbm_rdonly, sdbm_error, sdbm_clearerr, sdbm_dirfno, sdbm_pagfno -
      data base subroutines

 SYNOPSIS
      #include <sdbm.h>

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

      datum nullitem = { NULL, 0 };

      DBM *sdbm_open(char *file, int flags, int mode)

      DBM *sdbm_prep(char *dirname, char *pagname, int flags, int mode)

      void sdbm_close(DBM *db)

      datum sdbm_fetch(DBM *db, key)

      int sdbm_store(DBM *db, datum key, datum val, int flags)

      int sdbm_delete(DBM *db, datum key)

      int sdbm_exists(DBM *db, datum key)

      datum sdbm_firstkey(DBM *db)

      datum sdbm_nextkey(DBM *db)

      long sdbm_hash(char *string, int len)

      int sdbm_rdonly(DBM *db)
      int sdbm_error(DBM *db)
      sdbm_clearerr(DBM *db)
      int sdbm_dirfno(DBM *db)
      int sdbm_pagfno(DBM *db)

 DESCRIPTION
      This package allows an application to maintain a mapping of
      <key,value> pairs in disk files.  This is not to be considered a real
      database system, but is still useful in many simple applications built
      around fast retrieval of a data value from a key.  This implementation
      uses an external hashing scheme, called Dynamic Hashing, as described
      by Per-Aake Larson in BIT 18 (1978) pp.  184-201.  Retrieval of any
      item usually requires a single disk access.  The application interface
      is compatible with the ndbm(3) library.  An sdbm database is kept in



                                    - 1 -       Formatted:  October 15, 2024






 SDBM(3)                                                             SDBM(3)
                                1 March 1990



      two files usually given the extensions .dir and .pag.  The .dir file
      contains a bitmap representing a forest of binary hash trees, the
      leaves of which indicate data pages in the .pag file.  The application
      interface uses the datum structure to describe both keys and values.
      A datum specifies a byte sequence of dsize size pointed to by dptr.
      If you use ASCII strings as keys or values, then you must decide
      whether or not to include the terminating NUL byte which sometimes
      defines strings.  Including it will require larger database files, but
      it will be possible to get sensible output from a strings(1) command
      applied to the data file.  In order to allow a process using this
      package to manipulate multiple databases, the applications interface
      always requires a handle, a DBM *, to identify the database to be
      manipulated.  Such a handle can be obtained from the only routines
      that do not require it, namely sdbm_open() or sdbm_prep().  Either of
      these will open or create the two necessary files.  The difference is
      that the latter allows explicitly naming the bitmap and data files
      whereas sdbm_open() will take a base file name and call sdbm_prep()
      with the default extensions.  The flags and mode parameters are the
      same as for open(2).  To free the resources occupied while a database
      handle is active, call sdbm_close().  Given a handle, one can retrieve
      data associated with a key by using the sdbm_fetch() routine, and
      associate data with a key by using the sdbm_store() routine.
      sdbm_exists() will say whether a given key exists in the database.
      The values of the flags parameter for sdbm_store() can be either
      DBM_INSERT, which will not change an existing entry with the same key,
      or DBM_REPLACE, which will replace an existing entry with the same
      key.  Keys are unique within the database.  To delete a key and its
      associated value use the sdbm_delete() routine.  To retrieve every key
      in the database, use a loop like:

      for (key = sdbm_firstkey(db); key.dptr != NULL; key = sdbm_nextkey(db))
              ;
      The order of retrieval is unspecified.  If you determine that the
      performance of the database is inadequate or you notice clustering or
      other effects that may be due to the hashing algorithm used by this
      package, you can override it by supplying your own sdbm_hash()
      routine.  Doing so will make the database unintelligable to any other
      applications that do not use your specialized hash function.

      The following macros are defined in the header file:

           sdbm_rdonly() returns true if the database has been opened
           read-only.

           sdbm_error() returns true if an I/O error has occurred.

           sdbm_clearerr() allows you to clear the error flag if you think
           you know what the error was and insist on ignoring it.

           sdbm_dirfno() returns the file descriptor associated with the
           bitmap file.



                                    - 2 -       Formatted:  October 15, 2024






 SDBM(3)                                                             SDBM(3)
                                1 March 1990



           sdbm_pagfno() returns the file descriptor associated with the
           data file.

 SEE ALSO
      open(2).

 DIAGNOSTICS
      Functions that return a DBM * handle will use NULL to indicate an
      error.  Functions that return an int will use -1 to indicate an error.
      The normal return value in that case is 0.  Functions that return a
      datum will return nullitem to indicate an error.  As a special case of
      sdbm_store(), if it is called with the DBM_INSERT flag and the key
      already exists in the database, the return value will be 1.  In
      general, if a function parameter is invalid, errno will be set to
      EINVAL.  If a write operation is requested on a read-only database,
      errno will be set to ENOPERM.  If a memory allocation (using
      malloc(3)) failed, errno will be set to ENOMEM.  For I/O operation
      failures errno will contain the value set by the relevant failed
      system call, either read(2), write(2), or lseek(2).

 AUTHOR
      Ozan S. Yigit

 BUGS
      The sum of key and value data sizes must not exceed PAIRMAX (1008
      bytes).  The sum of the key and value data sizes where several keys
      hash to the same value must fit within one bitmap page.  The .pag file
      will contain holes, so its apparent size is larger than its contents.
      When copied through the filesystem the holes will be filled.  The
      contents of datum values returned are in volatile storage.  If you
      want to retain the values pointed to, you must copy them immediately
      before another call to this package.  The only safe way for multiple
      processes to (read and) update a database at the same time, is to
      implement a private locking scheme outside this package and open and
      close the database between lock acquisitions.  It is safe for multiple
      processes to concurrently access a database read-only.

 APPLICATIONS PORTABILITY
      For complete source code compatibility with the Berkeley Unix ndbm(3)
      library, the sdbm.h header file should be installed in
      /usr/include/ndbm.h.  The nullitem data item, and the sdbm_prep(),
      sdbm_hash(), sdbm_rdonly(), sdbm_dirfno(), and sdbm_pagfno() functions
      are unique to this package.











                                    - 3 -       Formatted:  October 15, 2024