NNAAMMEE hsearch - hsearch, hcreate, hdestroy SSYYNNOOPPSSIISS ##ddeeffiinnee DDBB__DDBBMM__HHSSEEAARRCCHH 11 ##iinncclluuddee <> ttyyppeeddeeff eennuumm {{ FFIINNDD,, EENNTTEERR }} AACCTTIIOONN;; ttyyppeeddeeff ssttrruucctt eennttrryy {{ cchhaarr **kkeeyy;; vvooiidd **ddaattaa;; }} EENNTTRRYY;; EENNTTRRYY ** hhsseeaarrcchh((EENNTTRRYY iitteemm,, AACCTTIIOONN aaccttiioonn));; iinntt hhccrreeaattee((ssiizzee__tt nneelleemm));; vvooiidd hhddeessttrrooyy((vvooiidd));; DDEESSCCRRIIPPTTIIOONN The _h_s_e_a_r_c_h interface to the DB library is intended to provide source code compatibility for historic applica- tions. It is not recommended for any other purpose. To compile _h_s_e_a_r_c_h applications, replace the application's _#_i_n_c_l_u_d_e of the hsearch include file (e.g., ``#include '') with the following two lines: #define DB_DBM_HSEARCH 1 #include and recompile. The _h_c_r_e_a_t_e function creates an in-memory database. The _n_e_l_e_m argument is an estimation of the maximum number of key/data pairs that will be stored in the database. The _h_d_e_s_t_r_o_y function discards the database. Database elements are structures of type _E_N_T_R_Y, which con- tain at least two fields: _k_e_y and _d_a_t_a. The field _k_e_y is declared to be of type ``char *'' and is the key used for storage and retrieval. The field _d_a_t_a is declared to be of type ``void *'' and is its associated data. The _h_s_e_a_r_c_h function retrieves key/data pairs from, and stores key/data pairs into, the database. The _a_c_t_i_o_n 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 refer- ence to an _E_N_T_R_Y structure referencing the existing key and its associated data element. FIND Retrieve the specified key/data pair from the database. CCOOMMPPAATTIIBBIILLIITTYY NNOOTTEESS Historically, _h_s_e_a_r_c_h required applications to maintain the keys and data in the application's memory for as long as the _h_s_e_a_r_c_h 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 alloca- tion of additional memory. DDIIAAGGNNOOSSTTIICCSS The _h_c_r_e_a_t_e function returns 0 on failure, setting _e_r_r_n_o, and non-zero on success. The _h_s_e_a_r_c_h function returns a pointer to an ENTRY struc- ture on success, and NULL, setting _e_r_r_n_o, if the _a_c_t_i_o_n specified was FIND and the item did not appear in the database. EERRRROORRSS The _h_c_r_e_a_t_e function may fail and return _e_r_r_n_o for any of the errors specified for the following DB and library functions: db_open(3), and memset(3). The _h_s_e_a_r_c_h function may fail and return _e_r_r_n_o 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 _h_s_e_a_r_c_h function will fail, setting _e_r_r_n_o to 0, if the _a_c_t_i_o_n specified was FIND and the item did not appear in the database. SSEEEE AALLSSOO 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 func- tions, 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 _d_b___i_n_t_r_o(3). _d_b___a_r_c_h_i_v_e(1), _d_b___c_h_e_c_k_p_o_i_n_t(1), _d_b___d_e_a_d_l_o_c_k(1), _d_b___d_u_m_p(1), _d_b___l_o_a_d(1), _d_b___r_e_c_o_v_e_r(1), _d_b___s_t_a_t(1), _d_b___i_n_t_r_o(3), _d_b___a_p_p_i_n_i_t(3), _d_b___c_u_r_s_o_r(3), _d_b___d_b_m(3), _d_b___i_n_t_e_r_n_a_l(3), _d_b___l_o_c_k(3), _d_b___l_o_g(3), _d_b___m_p_o_o_l(3), _d_b___o_p_e_n(3), _d_b___t_h_r_e_a_d(3), _d_b___t_x_n(3)