ndbm(3)                             CLIX                             ndbm(3)



  NAME

    ndbm: dbm_open, dbm_close, dbm_fetch, dbm_store, dbm_delete, dbm_firstkey,
    dbm_nextkey, dbm_error, dbm_clearerr - Database functions

  LIBRARY

    Berkeley Software Distribution Library (libbsd.a)

  SYNOPSIS

    #include <ndbm.h>

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

    void dbm_close(
      DBM *db );

    datum dbm_fetch(
      DBM *db ,
      datum key );

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

    int dbm_delete(
      DBM *db ,
      datum key );

    datum dbm_firstkey(
      DBM *db );

    datum(
      DBM *db );

    int dbm_error(
      DBM *db );

    int dbm_clearerr(
      DBM *db );

  PARAMETERS

    file      One of the files in which the database is stored




  2/94 - Intergraph Corporation                                              1

  ndbm(3)                             CLIX                             ndbm(3)



    flags     An integer specifying whether to overwrite an already existing
              entry

    mode      An integer representing the mode in which to open an entry

    db        A pointer to a database

    key       A datum holding the key to a database entry

    content   A datum holding the contents of a database entry

  DESCRIPTION

    These functions maintain key/content pairs in a database.  The functions
    will handle very large (a billion blocks) databases and will access a
    keyed item in one or two file system accesses.

    The 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 database 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 dbm_open().  This
    will open and/or create the files file.dir and file.pag depending on the
    flags parameter (see open()).

    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.  Specifying dbm_insert will only insert new
    entries in to the database and will not change an existing entry with the
    same key.  The Specifying 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().
    The dbm_firstkey() function will return the first key in the database.
    The dbm_nextkey() returns the next key in the database.  This code will
    traverse the database:

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

    The dbm_error() function returns nonzero when an error has occurred
    reading or writing the database.  dbm_clearerr() resets the error
    condition on the named database.

    The *.pag file will contain holes so that its apparent size is
    approximately four times its actual content.  These files cannot be copied
    by normal means (cp, cat, tar, ar) without filling in the holes.

    The dptr pointers returned by these functions point to static storage



  2                                              Intergraph Corporation - 2/94

  ndbm(3)                             CLIX                             ndbm(3)



    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.  The dbm_store() will return an
    error if a disk block fills with inseparable data.

    The dbm_delete() function does not physically reclaim file space, although
    it makes it available for reuse.  The order of keys presented by
    dbm_firstkey() and dbm_nextkey() depends on a hashing function.

  RETURN VALUES

    All functions that return an integer indicate errors with negative values.
    A zero return indicates success.  Functions 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.

  RELATED INFORMATION

    Functions:  open(2)

































  2/94 - Intergraph Corporation                                              3