db_hsearch

       #define DB_DBM_HSEARCH    1
       #include <db.h>

       typedef enum {
               FIND, ENTER
       } ACTION;

       typedef struct entry {
               char *key;
               void *data;
       } ENTRY;

       ENTRY *
       hsearch(ENTRY item, ACTION action);

       int
       hcreate(size_t nelem);

       void
       hdestroy(void);

DESCRIPTION

       The  hsearch  interface  to  the DB library is intended to
       provide   source   code   compatibility    for    historic
       applications.    It  is  not  recommended  for  any  other
       purpose.

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

              #define DB_DBM_HSEARCH    1
              #include <db.h>

       and recompile.

       The hcreate function creates an in-memory  database.   The
       nelem  argument  is an estimation of the maximum number of
       key/data pairs that will be stored in the database.

       The hdestroy function discards the database.

       Database elements are  structures  of  type  ENTRY,  which
       contain  at least two fields: key and data.  The field key
       is declared to be of type ``char *'' and is the  key  used
       for  storage and retrieval.  The field data is declared to
       be of type ``void *'' and is its associated data.

       The hsearch function retrieves key/data  pairs  from,  and
       stores key/data pairs into, the database.

       The action argument must be set to one of two values:

       ENTER
            If  the  key does not already appear in the database,
            insert the key/data pair into the database.   If  the
            key   already  appears  in  the  database,  return  a
            reference  to  an  ENTRY  structure  referencing  the
            existing key and its associated data element.

       FIND Retrieve   the   specified  key/data  pair  from  the
            database.

COMPATIBILITY NOTES

       Historically, hsearch required  applications  to  maintain
       the  keys and data in the application's memory for as long
       as the hsearch database existed.  As DB  handles  key  and
       data  management  internally, there is no requirement that
       applications maintain local copies of key and data  items,
       although  the  only  effect  of  doing  so  should  be the
       allocation of additional memory.

DIAGNOSTICS

       The hcreate function returns 0 on failure, setting  errno,
       and non-zero on success.

       The  hsearch  function  returns  a  pointer  to  an  ENTRY
       structure on success, and  NULL,  setting  errno,  if  the
       action  specified  was FIND and the item did not appear in
       the database.

ERRORS

       The hcreate 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 hsearch function may fail and return errno for any  of
       the  errors  specified  for  the  following DB and library
       functions: DB->get(3), DB->put(3), memset(3), and
       strlen(3).

       In addition, the hsearch function will fail, setting errno
       to 0, if the action specified was FIND and  the  item  did
       not appear in the database.

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)