NNAAMMEE dbm - dbminit, fetch, store, delete, firstkey, nextkey ndbm - dbm_open, dbm_close, dbm_fetch, dbm_store, dbm_delete, dbm_firstkey, dbm_nextkey, dbm_error, dbm_clearerr SSYYNNOOPPSSIISS ##ddeeffiinnee DDBB__DDBBMM__HHSSEEAARRCCHH 11 ##iinncclluuddee <> ttyyppeeddeeff ssttrruucctt {{ cchhaarr **ddppttrr;; iinntt ddssiizzee;; }} ddaattuumm;; DDBBMM FFUUNNCCTTIIOONNSS iinntt ddbbmmiinniitt((cchhaarr **ffiillee));; ddaattuumm ffeettcchh((ddaattuumm kkeeyy));; iinntt ssttoorree((ddaattuumm kkeeyy,, ddaattuumm ccoonntteenntt));; iinntt ddeelleettee((ddaattuumm kkeeyy));; ddaattuumm ffiirrssttkkeeyy((vvooiidd));; ddaattuumm nneexxttkkeeyy((ddaattuumm kkeeyy));; NNDDBBMM FFUUNNCCTTIIOONNSS DDBBMM ** ddbbmm__ooppeenn((cchhaarr **ffiillee,, iinntt ffllaaggss,, iinntt mmooddee));; vvooiidd ddbbmm__cclloossee((DDBBMM **ddbb));; ddaattuumm ddbbmm__ffeettcchh((DDBBMM **ddbb,, ddaattuumm kkeeyy));; iinntt ddbbmm__ssttoorree((DDBBMM **ddbb,, ddaattuumm kkeeyy,, ddaattuumm ccoonntteenntt,, iinntt ffllaaggss));; iinntt ddbbmm__ddeelleettee((DDBBMM **ddbb,, ddaattuumm kkeeyy));; ddaattuumm ddbbmm__ffiirrssttkkeeyy((DDBBMM **ddbb));; ddaattuumm ddbbmm__nneexxttkkeeyy((DDBBMM **ddbb));; iinntt ddbbmm__eerrrroorr((DDBBMM **ddbb));; iinntt ddbbmm__cclleeaarreerrrr((DDBBMM **ddbb));; DDEESSCCRRIIPPTTIIOONN The _d_b_m and _n_d_b_m interfaces to the DB library are intended to provide source code compatibility for historic applica- tions. They are not recommended for any other purpose. The historic _d_b_m and _n_d_b_m database format is nnoott sup- ported, and databases previously built using the real _d_b_m or _n_d_b_m libraries cannot be read by the DB functions. To compile _d_b_m or _n_d_b_m applications, replace the applica- tion's _#_i_n_c_l_u_d_e of the dbm or ndbm include file (e.g., ``#include '' or ``#include '') with the following two lines: #define DB_DBM_HSEARCH 1 #include and recompile. If the application attempts to load against a dbm library (e.g., ``-ldbm''), remove the library from the load line. _K_e_ys and _c_o_n_t_e_n_ts are described by the _d_a_t_u_m typedef. A _d_a_t_u_m specifies a string of _d_s_i_z_e bytes pointed to by _d_p_t_r. Arbitrary binary data, as well as normal text strings, are allowed. DDBBMM FFUUNNCCTTIIOONNSS Before a database can be accessed, it must be opened by _d_b_m_i_n_i_t. This will open and/or create the database _f_i_l_e.db. If created, the database file is created read/write by owner only (as described in _c_h_m_o_d(2)) and modified by the process' umask value at the time of cre- ation (see _u_m_a_s_k(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 _f_e_t_c_h and data is placed under a key by _s_t_o_r_e. A key (and its associated contents) is deleted by _d_e_l_e_t_e. A linear pass through all keys in a database may be made, in an (apparently) random order, by use of _f_i_r_s_t_k_e_y and _n_e_x_t_k_e_y. _F_i_r_s_t_k_e_y will return the first key in the database. With any key _n_e_x_t_k_e_y will return the next key in the database. This code will traverse the data base: for (key = firstkey(); key.dptr != NULL; key = nextkey(key)) NNDDBBMM FFUUNNCCTTIIOONNSS Before a database can be accessed, it must be opened by _d_b_m___o_p_e_n. This will open and/or create the database file _f_i_l_e.db depending on the flags parameter (see _o_p_e_n(2)). If created, the database file is created with mode _m_o_d_e (as described in _c_h_m_o_d(2)) and modified by the process' umask value at the time of creation (see _u_m_a_s_k(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 _d_b_m___f_e_t_c_h and data is placed under a key by _d_b_m___s_t_o_r_e. The _f_l_a_g_s field can be either DDBBMM__IINNSSEERRTT or DDBBMM__RREEPPLLAACCEE.. DDBBMM__IINNSSEERRTT will only insert new entries into the database and will not change an existing entry with the same key. DDBBMM__RREEPPLLAACCEE will replace an existing entry if it has the same key. A key (and its associated contents) is deleted by _d_b_m___d_e_l_e_t_e. A linear pass through all keys in a database may be made, in an (apparently) random order, by use of _d_b_m___f_i_r_s_t_k_e_y and _d_b_m___n_e_x_t_k_e_y. _D_b_m___f_i_r_s_t_k_e_y will return the first key in the database. _D_b_m___n_e_x_t_k_e_y will return the next key in the database. This code will tra- verse the data base: for (key = dbm_firstkey(db); key.dptr != NULL; key = dbm_nextkey(db)) _D_b_m___e_r_r_o_r returns non-zero when an error has occurred reading or writing the database. _D_b_m___c_l_e_a_r_e_r_r resets the error condition on the named database. CCOOMMPPAATTIIBBIILLIITTYY NNOOTTEESS The historic _d_b_m and _n_d_b_m libraries created two underlying database files, traditionally named _f_i_l_e.dir and _f_i_l_e.pag. The DB library creates a single database file named _f_i_l_e.db. Applications that are aware of the underlying database file names may require additional source code modifications. The historic _d_b_m_i_n_i_t interface required that the underly- ing ``.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 _d_b_m___d_i_r_f_n_o and _d_b_m___p_a_g_f_n_o macros are sup- ported, 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 _n_d_b_m 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. DDBBMM DDIIAAGGNNOOSSTTIICCSS The _d_b_m_i_n_i_t function returns -1 on failure, setting _e_r_r_n_o, and 0 on success. The _f_e_t_c_h function sets the returned _d_a_t_u_m's _d_p_t_r field to NULL on failure, setting _e_r_r_n_o, and returns a non-NULL _d_p_t_r on success. The _s_t_o_r_e function returns -1 on failure, setting _e_r_r_n_o, and 0 on success. The _d_e_l_e_t_e function returns -1 on failure, setting _e_r_r_n_o, and 0 on success. The _f_i_r_s_t_k_e_y function sets the returned _d_a_t_u_m's _d_p_t_r field to NULL on failure, setting _e_r_r_n_o, and returns a non-NULL _d_p_t_r on success. The _n_e_x_t_k_e_y function sets the returned _d_a_t_u_m's _d_p_t_r field to NULL on failure, setting _e_r_r_n_o, and returns a non-NULL _d_p_t_r on success. NNDDBBMM DDIIAAGGNNOOSSTTIICCSS The _d_b_m___o_p_e_n function returns NULL on failure, setting _e_r_r_n_o, and 0 on success. The _d_b_m___f_e_t_c_h function sets the returned _d_a_t_u_m's _d_p_t_r field to NULL on failure, setting _e_r_r_n_o, and returns a non-NULL _d_p_t_r on success. The _d_b_m___s_t_o_r_e function returns -1 on failure, setting _e_r_r_n_o, 0 on success, and 1 if DBM_INSERT was set and the specified key already existed in the database. The _d_b_m___d_e_l_e_t_e function returns -1 on failure, setting _e_r_r_n_o, and 0 on success. The _d_b_m___f_i_r_s_t_k_e_y function sets the returned _d_a_t_u_m's _d_p_t_r field to NULL on failure, setting _e_r_r_n_o, and returns a non-NULL _d_p_t_r on success. The _d_b_m___n_e_x_t_k_e_y function sets the returned _d_a_t_u_m's _d_p_t_r field to NULL on failure, setting _e_r_r_n_o, and returns a non-NULL _d_p_t_r on success. The _d_b_m___e_r_r_o_r function returns -1 on failure, setting _e_r_r_n_o, and 0 on success. The _d_b_m___c_l_e_a_r_e_r_r function returns -1 on failure, setting _e_r_r_n_o, and 0 on success. EERRRROORRSS The _d_b_m_i_n_i_t function may fail and return _e_r_r_n_o for any of the errors specified for the following DB and library functions: dbm_close(3), and dbm_open(3). The _f_e_t_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: dbm_fetch(3). The _s_t_o_r_e function may fail and return _e_r_r_n_o for any of the errors specified for the following DB and library functions: dbm_store(3). The _d_e_l_e_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: dbm_delete(3). The _f_i_r_s_t_k_e_y function may fail and return _e_r_r_n_o for any of the errors specified for the following DB and library functions: dbm_firstkey(3). The _n_e_x_t_k_e_y function may fail and return _e_r_r_n_o for any of the errors specified for the following DB and library functions: dbm_nextkey(3). The _d_b_m___o_p_e_n 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 _d_b_m___c_l_o_s_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->close(3). The _d_b_m___f_e_t_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), and memset(3). The _d_b_m___s_t_o_r_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->put(3), and memset(3). The _d_b_m___d_e_l_e_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: memset(3). The _d_b_m___f_i_r_s_t_k_e_y function may fail and return _e_r_r_n_o for any of the errors specified for the following DB and library functions: DB->cursor(3), and memset(3). The _d_b_m___n_e_x_t_k_e_y function may fail and return _e_r_r_n_o for any of the errors specified for the following DB and library functions: DB->cursor(3), and memset(3). 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)