Berkeley DB Database Environment

References to the DB_ENV structure are maintained by Berkeley DB, so it may not be discarded until the last close function, corresponding to an open function for which it was an argument, has returned. To ensure compatibility with future releases of Berkeley DB, all fields of the DB_ENV structure that are not explicitly set should be initialized to 0 before the first time the structure is used. Do this by declaring the structure external or static, or by calling one of the C library routines bzero(3) or memset(3).

The fields of the DB_ENV structure used by db_open are described below. If dbenv is NULL or any of its fields are set to 0, defaults appropriate for the system are used where possible.

The following fields in the DB_ENV structure may be initialized before calling db_open:

DB_LOG *lg_info;

If modifications to the file being opened should be logged, the lg_info field contains a return value from the function log_open. If lg_info is NULL, no logging is done by the Berkeley DB access methods.

DB_LOCKTAB *lk_info;

If locking is required for the file being opened (as is the case when multiple processes or threads are accessing the same file), the lk_info field contains a return value from the function lock_open. If lk_info is NULL, no locking is done by the Berkeley DB access methods.

If both locking and transactions are being performed (i.e., both lk_info and tx_info are non-NULL), the transaction ID will be used as the locker ID. If only locking is being performed, db_open will acquire a locker ID from lock_id and will use it for all locks required for this instance of db_open.

DB_MPOOL *mp_info;

If the cache for the file being opened should be maintained in a shared buffer pool, the mp_info field contains a return value from the function memp_open. If mp_info is NULL, a memory pool may still be created by Berkeley DB, but it will be private to the application and entirely managed by Berkeley DB.

DB_TXNMGR *tx_info;

If the accesses to the file being opened should take place in the context of transactions (providing atomicity and error recovery), the tx_info field contains a return value from the function txn_open. If transactions are specified, the application is responsible for making suitable calls to txn_begin, txn_abort and txn_commit. If tx_info is NULL, no transaction support is done by the Berkeley DB access methods.

When the access methods are used in conjunction with transactions, the application must abort the transaction (using txn_abort) if any of the transaction protected access method calls (i.e., any calls other than open, close and sync) returns a system error (e.g., deadlock, which returns EAGAIN).