# db_dbm

           dbm_firstkey, dbm_nextkey, dbm_error, dbm_clearerr

## SYNOPSIS

           #define DB_DBM_HSEARCH    1
           #include <db.h>

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

## DBM FUNCTIONS

           int
           dbminit(char *file);

           datum
           fetch(datum key);

           int
           store(datum key, datum content);

           int
           delete(datum key);

           datum
           firstkey(void);

           datum
           nextkey(datum key);

## NDBM FUNCTIONS

           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_nextkey(DBM *db);

           int
           dbm_error(DBM *db);
           int
           dbm_clearerr(DBM *db);

## DESCRIPTION

           The dbm and ndbm interfaces to the DB library are intended
           to  provide  source  code   compatibility   for   historic
           applications.   They  are  not  recommended  for any other
           purpose.  The historic dbm and ndbm database format is not
           supported,  and  databases previously built using the real
           dbm or ndbm libraries cannot be read by the DB  functions.

           To   compile   dbm   or  ndbm  applications,  replace  the
           application's #include of the dbm  or  ndbm  include  file
           (e.g., ``#include <dbm.h>'' or ``#include <ndbm.h>'') with
           the following two lines:

                  #define DB_DBM_HSEARCH    1
                  #include <db.h>

           and  recompile.   If  the  application  attempts  to  load
           against  a  dbm  library  (e.g.,  ``-ldbm''),  remove  the
           library from the load line.

           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  text
           strings, are allowed.

## DBM FUNCTIONS

           Before  a  database  can be accessed, it must be opened by
           dbminit.   This  will  open  and/or  create  the  database
           file.db.    If  created,  the  database  file  is  created
           read/write by owner only (as described  in  chmod(2))  and
           modified  by  the  process'  umask  value  at  the time of
           creation (see umask(2)).  The group ownership  of  created
           files  is  based on the system and directory defaults, and
           is not further specified by DB.

           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))

## NDBM FUNCTIONS

           Before  a  database  can be accessed, it must be opened by
           dbm_open.  This will open and/or create the database  file
           file.db  depending  on  the flags parameter (see open(2)).
           If created, the database file is created  with  mode  mode
           (as  described  in  chmod(2)) and modified by the process'
           umask value at the time of creation (see  umask(2)).   The
           group  ownership  of  created files is based on the system
           and directory defaults, and is not  further  specified  by
           DB.

           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.
           DBM_INSERT will only insert new entries into the  database
           and  will  not change an existing entry with the same key.
           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.   Dbm_firstkey  will
           return  the  first  key in the database.  Dbm_nextkey will
           return the next key  in  the  database.   This  code  will
           traverse the data base:

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

           Dbm_error  returns  non-zero  when  an  error has occurred
           reading or writing the database.  Dbm_clearerr resets  the
           error condition on the named database.

## COMPATIBILITY NOTES

           The historic dbm and ndbm libraries created two underlying
           database files, traditionally named file.dir and file.pag.
           The  DB  library  creates  a  single  database  file named
           file.db.  Applications that are aware  of  the  underlying
           database  file  names  may  require additional source code
           modifications.

           The  historic  dbminit   interface   required   that   the
           underlying  ``.dir''  and  ``.pag''  files  already  exist
           (empty databases  were  created  by  creating  zero-length
           ``.dir'' and ``.pag'' files).  Applications that expect to
           create databases using this method may require  additional
           source code modifications.

           The   historic   dbm_dirfno   and  dbm_pagfno  macros  are
           supported, but will return identical file  descriptors  as
           there  is  only  a  single  underlying file used by the DB
           hashing  access  method.   Applications  using  both  file
           descriptors for locking may require additional source code
           modifications.

           If an application using the ndbm interface  exits  without
           closing  the  database, it may lose updates because the DB
           library  buffers  all  writes.   Such  applications   will
           require  additional  source  code  modifications  to  work
           correctly with the DB library.

## DBM DIAGNOSTICS

           The dbminit function returns -1 on failure, setting errno,
           and 0 on success.

           The fetch function sets the returned datum's dptr field to
           NULL on failure, setting errno,  and  returns  a  non-NULL
           dptr on success.

           The  store  function returns -1 on failure, setting errno,
           and 0 on success.

           The delete function returns -1 on failure, setting  errno,
           and 0 on success.

           The firstkey function sets the returned datum's dptr field
           to NULL on failure, setting errno, and returns a  non-NULL
           dptr on success.

           The  nextkey function sets the returned datum's dptr field
           to NULL on failure, setting errno, and returns a  non-NULL
           dptr on success.

## NDBM DIAGNOSTICS

           The  dbm_open  function  returns  NULL on failure, setting
           errno, and 0 on success.

           The dbm_fetch function  sets  the  returned  datum's  dptr
           field  to  NULL  on  failure, setting errno, and returns a
           non-NULL dptr on success.

           The dbm_store function  returns  -1  on  failure,  setting
           errno,  0  on success, and 1 if DBM_INSERT was set and the
           specified key already existed in the database.

           The dbm_delete function returns  -1  on  failure,  setting
           errno, and 0 on success.

           The  dbm_firstkey  function sets the returned datum's dptr
           field to NULL on failure, setting  errno,  and  returns  a
           non-NULL dptr on success.

           The  dbm_nextkey  function  sets the returned datum's dptr
           field to NULL on failure, setting  errno,  and  returns  a
           non-NULL dptr on success.

           The  dbm_error  function  returns  -1  on failure, setting
           errno, and 0 on success.

           The dbm_clearerr function returns -1 on  failure,  setting
           errno, and 0 on success.

## ERRORS

           The  dbminit function may fail and return errno for any of
           the errors specified for  the  following  DB  and  library
           functions: dbm_close(3), and dbm_open(3).

           The  fetch  function  may fail and return errno for any of
           the errors specified for  the  following  DB  and  library
           functions: dbm_fetch(3).

           The  store  function  may fail and return errno for any of
           the errors specified for  the  following  DB  and  library
           functions: dbm_store(3).

           The  delete  function may fail and return errno for any of
           the errors specified for  the  following  DB  and  library
           functions: dbm_delete(3).

           The firstkey function may fail and return errno for any of
           the errors specified for  the  following  DB  and  library
           functions: dbm_firstkey(3).

           The  nextkey function may fail and return errno for any of
           the errors specified for  the  following  DB  and  library
           functions: dbm_nextkey(3).

           The dbm_open function may fail and return errno for any of
           the errors specified for  the  following  DB  and  library
           functions: db_open(3), and memset(3).

           The  dbm_close  function may fail and return errno for any
           of the errors specified for the following DB  and  library
           functions: DB->close(3).

           The  dbm_fetch  function may fail and return errno for any
           of the errors specified for the following DB  and  library
           functions: DB->get(3), and memset(3).

           The  dbm_store  function may fail and return errno for any
           of the errors specified for the following DB  and  library
           functions: DB->put(3), and memset(3).

           The  dbm_delete function may fail and return errno for any
           of the errors specified for the following DB  and  library
           functions: memset(3).

           The  dbm_firstkey  function  may fail and return errno for
           any of the errors  specified  for  the  following  DB  and
           library functions: DB->cursor(3), and memset(3).

           The dbm_nextkey function may fail and return errno for any
           of the errors specified for the following DB  and  library
           functions: DB->cursor(3), and memset(3).

## SEE ALSO

           The  DB  library  is  a family of groups of functions that
           provides a modular programming interface  to  transactions
           and  record-oriented  file  access.   The library includes
           support for transactions, locking, logging and  file  page
           caching,  as well as various indexed access methods.  Many
           of the functional groups  (e.g.,  the  file  page  caching
           functions)   are   useful  independent  of  the  other  DB
           functions, although some functional groups are  explicitly
           based  on  other functional groups (e.g., transactions and
           logging).  For a general description of  the  DB  package,
           see db_intro(3).

           db_archive(1), db_checkpoint(1), db_deadlock(1), db_dump(1),
           db_load(1), db_recover(1), db_stat(1), db_intro(3),
           db_appinit(3), db_cursor(3), db_dbm(3), db_internal(3),
           db_lock(3), db_log(3), db_mpool(3), db_open(3), db_thread(3),
           db_txn(3)