-I#Berkeley DB: hsearch[P

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

inthcreate(size_t nelem);

voidhdestroy(void);





Description



?The hsearch interface to the Berkeley DB library is intended toGprovide a high-performance implementation and source code compatibility;for applications written to the historic hsearch interface.,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:

and recompile.

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

3The hdestroy function discards the database.

DDatabase elements are structures of type ENTRY, which contain0at 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.AThe field data is declared to be of type void * andis its associated data.

3The 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:

C

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 ENTRYGstructure referencing the existing key and its associated data element.F

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


Compatibility Notes



@Historically, hsearch required applications to maintain the keysFand data in the application's memory for as long as the hsearchdatabase existed.RAs Berkeley DB handles key and data management internally, there is no requirement>that applications maintain local copies of key and data items,Kalthough the only effect of doing so should be the allocation of additionalmemory.

Hsearch Diagnostics



FThe hcreate function returns 0 on failure, setting errnoand non-zero on success.

FThe 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

€If a fatal error occurs in Berkeley DB, the hcreate function may fail and returnFDB_RUNRECOVERY, at which point all subsequent database calls will alsoreturn DB_RUNRECOVERY.

;The hcreate)function may fail and return errnoKfor any of the errors specified for the following Berkeley DB and C library functions:.DB->get,.DB->put, memset(3),and strlen(3).

;The hsearch)function may fail and return errnoKfor any of the errors specified for the following Berkeley DB and C library functions:.DB->get,.DB->put, memset(3),and strlen(3).

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

ÿÿ