#include <db.h>

int
db_appinit(char *db_home,
    char *db_config, DB_ENV *dbenv, u_int32_t flags);

Description

The db_appinit function 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 db_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., DBcursor->c_put, DBcursor->c_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 lock_open. 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 lock_detect for more information.

DB_INIT_LOG

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

DB_INIT_MPOOL

Initialize the mpool subsystem; see memp_open. 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 txn_open. 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 memp_open. Ignored unless DB_INIT_MPOOL is also specified.

DB_NOMMAP

Do not memory map database files within this environment; see memp_open. 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 db_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 db_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 txn_open. 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 to db_appinit which is a pointer to a structure of type DB_ENV. Applications normally use the same DB_ENV structure (initialized by db_appinit) as an argument to all of the subsystems in the Berkeley DB package.

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_appinit are described below. The dbenv argument may not be NULL. If any of the fields of the dbenv structure 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_appinit:

void (*db_paniccall)(DB_ENV *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 function. 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. allowing errors to be redirected to a C++ error stream. It is unwise to use both error_stream with nonzero values of either errcall or errfile.

FILE *db_errfile;

The db_errfile field behaves similarly to the db_errcall field

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 db_appinit may call (lock_open, log_open, memp_open and txn_open), is called as follows, where the DB_CREATE flag is optional:

XXX_open(NULL, DB_CREATE,
    S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP, 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 db_appinit. For this reason the fields of the DB_ENV structure relevant to the subsystems being initialized must themselves be initialized before db_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 DB_ENV structure:

DB_LOCKTAB *lk_info;

The return value of the lock_open call.

DB_LOG *lg_info;

The return value of the log_open call.

DB_MPOOL *mp_info;

The return value of the memp_open call.

DB_TXNMGR *tx_info;

The return value of the txn_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 DB_ENV structure 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 DB_ENV argument initialized by a call to db_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 DB_ENV structure.

The single exception to this rule is the tx_info field, which applications must explicitly specify to the txn_begin, txn_checkpoint and txn_close functions.

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

Otherwise, once the Berkeley DB environment has been initialized by a call to db_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 db_appinit function returns the value of errno on failure, and 0 on success.

Errors

The db_appinit function may fail and return errno for any of the errors specified for the following Berkeley DB and C library functions: DB->close, abort(3), ctime(3), db_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), lock_open, lock_unlink, log_compare, log_get, log_open, log_unlink, malloc(3), memcpy(3), memp_open, memp_unlink, memset(3), realloc(3), stat(3), strcat(3), strchr(3), strcmp(3), strcpy(3), strlen(3), time(3), txn_checkpoint, txn_open, txn_unlink, vfprintf(3), and vsnprintf(3).

In addition, the db_appinit function may fail and 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.

See Also