#include <db_cxx.h>

int DbEnv::appinit(const char *db_home,
    char *const *db_config, u_int32_t flags);

Description

The DbEnv::appinit method provides a simple way to initialize and configure the Berkeley DB environment. It is not necessary that it be called, but it provides a structure for creating a consistent environment for processes using one or more of the features of Berkeley DB.

The db_home and db_config arguments to DbEnv::appinit are described in Berkeley DB File Naming.

The flags argument specifies the subsystems that are initialized and how the environment affects Berkeley DB file naming, among other things. The flags value is specified by logically OR'ing together one or more of the following values:

DB_CREATE

Cause subsystems to create any underlying files, as necessary.

DB_INIT_CDB

Initialize locking for the Berkeley DB Concurrent Access Methods product. In this mode, Berkeley DB provides multiple reader/single writer access. No other locking should be specified (e.g., do not set DB_INIT_LOCK). Access method calls are largely unchanged when using the DB_INIT_CDB flag, although any cursors through which update operations (e.g., Dbc::put, Dbc::del) will be made, must have the DB_RMW value set in the flags parameter to the cursor call that creates the cursor. See Db::cursor for more information.

DB_INIT_LOCK

Initialize the lock subsystem; see DbLock. This subsystem should be used when multiple processes or threads are going to be reading and writing a Berkeley DB database, so that they do not interfere with each other. If all threads are accessing the database(s) read-only, then locking is unnecessary. When the DB_INIT_LOCK flag is specified, it is usually necessary to run the deadlock detector, as well. See db_deadlock and DbLockTab::detect for more information.

DB_INIT_LOG

Initialize the log subsystem; see DbLog. This subsystem is used when recovery from application or system failure is necessary.]

DB_INIT_MPOOL

Initialize the mpool subsystem; see DbMpool. This subsystem is used whenever the application is using the Berkeley DB access methods for any purpose.]

DB_INIT_TXN

Initialize the transaction subsystem; see DbTxn. This subsystem is used when atomicity of multiple operations and recovery are important. The DB_INIT_TXN flag implies the DB_INIT_LOG flag.

DB_MPOOL_PRIVATE

Create a private memory pool; see DbMpool. Ignored unless DB_INIT_MPOOL is also specified.

DB_NOMMAP

Do not memory map database files within this environment; see DbMpool. Ignored unless DB_INIT_MPOOL is also specified.

DB_RECOVER

Run normal recovery on this environment before opening it for normal use. If this flag is set, the DB_CREATE flag must also be set since the regions will be removed and recreated.

The DbEnv::appinit function returns successfully if DB_RECOVER is specified and no log files exist, so it is necessary to ensure all necessary log files are present before running recovery. For further information, consult db_archive and db_recover.

DB_RECOVER_FATAL

Run catastrophic recovery on this environment before opening it for normal use. If this flag is set, the DB_CREATE flag must also be set since the regions will be removed and recreated.

The DbEnv::appinit function returns successfully if DB_RECOVER_FATAL is specified and no log files exist, so it is necessary to ensure all necessary log files are present before running recovery. For further information, consult db_archive and db_recover.

DB_THREAD

Ensure that handles returned by the Berkeley DB subsystems are useable by multiple threads within a single process, i.e., that the system is free-threaded.

DB_TXN_NOSYNC

On transaction commit, do not synchronously flush the log; see DbTxn. Ignored unless DB_INIT_TXN is also specified.

DB_USE_ENVIRON

The Berkeley DB process' environment may be permitted to specify information to be used when naming files; see Berkeley DB File Naming. As permitting users to specify which files are used can create security problems, environment information will be used in file naming for all users only if the DB_USE_ENVIRON flag is set.

DB_USE_ENVIRON_ROOT

The Berkeley DB process' environment may be permitted to specify information to be used when naming files; see Berkeley DB File Naming. As permitting users to specify which files are used can create security problems, if the DB_USE_ENVIRON_ROOT flag is set, environment information will be used for file naming only for users with a user-ID matching that of the superuser (specifically, users for whom the getuid(2) system call returns the user-ID 0).

The Berkeley DB environment is configured based on the dbenv argument. It is expected that applications will use a single DbEnv object as the argument to all of the subsystems in the Berkeley DB package. The fields of the DbEnv object used by DbEnv::appinit are described below. References to the DbEnv object are maintained by Berkeley DB, so it is necessary that the object and memory it references be valid until the object is destroyed. Any of the DbEnv fields that are not explicitly set will default to appropriate values.

The following fields in the DbEnv object may be initialized, using the appropriate set method, before calling DbEnv::appinit:

void (*db_paniccall)(DbEnv *dbenv, int errno);

Errors can occur in the Berkeley DB library where the only solution is to shut down the application and run recovery. (For example, if Berkeley DB is unable to write log records to disk because there is insufficient disk space.) In these cases, the value DB_RUNRECOVERY is returned by the function. It is often simpler, however, to simply shut down the application when such errors occur instead of attempting to gracefully return error values up the stack.

If db_paniccall is non-NULL and such an error occurs, it will called. The dbenv argument is a reference to the current environment, and the errval argument is the system errno value that was returned when the error occurred.

void (*db_errcall)(char *db_errpfx, char *buffer);

When an error occurs in the Berkeley DB library, an errno value is returned by the method. In some cases, however, the errno value may be insufficient to completely describe the cause of the error especially during initial application debugging.

If db_errcall is non-NULL, it may be called with additional error information. The db_errpfx argument is the current environment's db_errpfx field. The buffer argument contains a nul-terminated string with the additional information.

This error logging facility does not slow performance or significantly increase application size, and may be run during normal operation as well as during debugging. except that the error message is written to the OutputStream represented by error_stream.

ostream* error_stream;

The error_stream functions like the error file

const char *db_errpfx;

A prefix to prepend to error messages. Because Berkeley DB does not copy the memory referenced by the db_errpfx field, applications may modify the error message prefix at any time.

int db_verbose;

Include informational and debugging messages as well as error messages in the db_errcall and db_errfile output.

Each of the open functions that DbEnv::appinit may call (DbLockTab::open, DbLog::open, DbMpool::open and DbTxnMgr::open), is called as follows, where the DB_CREATE flag is optional:

XXX::open(NULL, DB_CREATE, 0660, dbenv);

This call will cause each subsystem to construct pathnames as described in Berkeley DB File Naming. The subsystem has permission to read and write underlying files as necessary, and optionally to create files. (All created files will be created readable and writeable by the owner and the group. The group ownership of created files is based on the system and directory defaults, and is not further specified by Berkeley DB.)

In addition, the dbenv argument is passed to the open functions of any subsystems initialized by DbEnv::appinit. For this reason the fields of the DbEnv object relevant to the subsystems being initialized must themselves be initialized before DbEnv::appinit is called. See the appropriate subsystem documentation for a list of these fields and their uses.

The return value from each of these calls is placed in the appropriate field of the DbEnv object:

DbLockTab *lk_info;

The return value of the DbLockTab::open call.

DbLog *lg_info;

The return value of the DbLog::open call.

DbMpool *mp_info;

The return value of the DbMpool::open call.

DbTxnMgr *tx_info;

The return value of the DbTxnMgr::open call.

In general, these fields are not directly used by applications; subsystems of Berkeley DB that use these fields simply reference them using the DbEnv object passed to the subsystem.

For example, an application using the Berkeley DB hash access method functions to access a database will first call Db::open passing it the DbEnv argument initialized by a call to DbEnv::appinit. Then, all future calls to the hash access method functions for that database will automatically use the underlying shared memory buffer pool that was specified by the mp_info field of that DbEnv object.

The single exception to this rule is the tx_info field, which applications must explicitly specify to the DbTxnMgr::begin, DbTxnMgr::checkpoint and DbTxnMgr::close methods.

The error_model field of DbEnv allows the user to configure the way errors are treated in Berkeley DB, and may be changed at any time, including after the call to DbEnv::appinit. The error model is further described in DbException.

The db_prefix field of DbEnv allows the user to configure the error message prefix, and may be changed at any time, including after the call to DbEnv::appinit.

Otherwise, once the Berkeley DB environment has been initialized by a call to DbEnv::appinit, no fields should be modified.

Architecture Notes

On Windows/95, files that are opened by multiple processes do not share data correctly. To cause Berkeley DB to use the paging file to share memory among processes, use the DB_REGION_NAME flag of the db_value_set function. Obviously, you do not need to do this if only a single process will be accessing database files.

The DbEnv::appinit method either returns errno or throws an exception that encapsulates an errno on failure, and 0 on success.

Errors

The DbEnv::appinit method may fail and throw an exception for any of the errors specified for the following Berkeley DB and C library functions: Db::close, abort(3), ctime(3), DbEnv::appexit, dbenv->tx_recover(3), fclose(3), fcntl(3), fflush(3), fgets(3), fopen(3), fprintf(3), free(3), getenv(3), getpid(3), getuid(3), isspace(3), DbLockTab::open, DbLockTab::unlink, DbLog::compare, DbLog::get, DbLog::open, DbLog::unlink, malloc(3), memcpy(3), DbMpool::open, DbMpool::unlink, memset(3), realloc(3), stat(3), strcat(3), strchr(3), strcmp(3), strcpy(3), strlen(3), time(3), DbTxnMgr::checkpoint, DbTxnMgr::open, DbTxnMgr::unlink, vfprintf(3), and vsnprintf(3).

In addition, the DbEnv::appinit method may fail and throw an exception or return errno for the following conditions:

EINVAL

An invalid flag value or parameter was specified.

The DB_THREAD flag was specified and spinlocks are not implemented for this architecture.

The DB_HOME or TMPDIR environment variables were set but empty.

An incorrectly formatted NAME VALUE entry or line was found.

ENOSPC

HP-UX only: a previously created Berkeley DB environment for this process still exists.

Class

See Also