db_appinit(3db)

NAME

db_appinit - initializing the DB environment

SYNOPSIS

#include <db2/db.h>
char *
db_version(int *major, int *minor, int *patch);
int
db_appinit(char *db_home,
char *db_config[], DB_ENV *dbenv, u_int32_t flags);
int
db_appexit(DB_ENV *dbenv);

DESCRIPTION

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 functions, 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 db_intro(3).

db_version The db_version function returns a pointer to a string containing DB version information. If major is non-NULL, the major version of the DB release is stored in the memory it references. If minor is non-NULL, the minor version of the DB release is stored in the memory it references. If patch is non-NULL, the patch version of the DB release is stored in the memory it references.

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

The db_home and db_config arguments to db_appinit are described in the section below entitled ``FILE NAMING''.

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

DB_CREATE: Cause subsystems to create any underlying files, as necessary. (See db_lock(3), db_log(3), db_mpool(3), db_open(3) and db_txn(3) for more information.)

DB_INIT_LOCK: Initialize the lock subsystem; see db_lock(3). This subsystem should be used when multiple processes or threads are going to be reading and writing a 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, db_deadlock(1), as well.

DB_INIT_LOG: Initialize the log subsystem; see db_log(3). This subsystem is used when recovery from application or system failure is important.

DB_INIT_MPOOL: Initialize the mpool subsystem; see db_mpool(3). This subsystem is used whenever the application is using the DB access methods for any purpose.

DB_INIT_TXN: Initialize the transaction subsystem; see db_txn(3). 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 db_mpool(3) for further information). Ignored unless DB_INIT_MPOOL is also specified.

DB_NOMMAP: Do not map any files within this environment (see db_mpool(3) for further information). 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 the man page for db_archive(1) and db_recover(1).

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.

DB_THREAD: Ensure that handles returned by the DB subsystems are useable by multiple threads within a single process, i.e., that the system is ``free-threaded''. (See db_lock(3), db_log(3), db_mpool(3), db_open(3) and db_txn(3) for more information.)

DB_TXN_NOSYNC: On transaction commit, do not synchronously flush the log (see db_txn(3) for further information). Ignored unless DB_INIT_TXN is also specified.

DB_USE_ENVIRON: The DB process' environment may be permitted to specify information to be used when naming files (see the section entitled ``FILE NAMING'' below). 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 DB process' environment may be permitted to specify information to be used when naming files (see the section entitled ``FILE NAMING'' below). 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 system call returns the user-ID 0).

The DB environment is configured based on the dbenv argument to db_appinit, which is a pointer to a structure of type DB_ENV (typedef'd in <db2/db.h>). Applications will normally use the same DB_ENV structure (initialized by db_appinit(3)), as an argument to all of the subsystems in the DB package.

References to the DB_ENV structure are maintained by 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. In order to ensure compatibility with future releases of 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 the C library routine 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 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_errcall)(char *db_errpfx, char *buffer);: When an error occurs in the DB package, 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.

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 should not be required for normal operation, but may be useful in debugging applications.

FILE *db_errfile;

The db_errfile field behaves similarly to the db_errcall field, except that the error message is written to the file stream represented by db_errfile.

If db_errpfx is non-NULL, the message will be preceded by the string referenced by db_errpfx, a colon (``:'') and a space. The message will be followed by a newline character.

const char *db_errpfx;: A prefix to prepend to error messages. Because DB does not copy the memory referenced by the db_errpfx field, the application 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 the section on ``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 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 manual page for each subsystem 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(3) call.

DB_LOG *lg_info;: The return value of the log_open(3) call.

DB_MPOOL *mp_info;: The return value of the memp_open(3) call.

DB_TXNMGR *tx_info;: The return value of the txn_open(3) call.

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

For example, an application using the DB hash access method functions to access a database will first call db_open passing it the DB_ENV argument filled in by the initial 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 argument.

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.

Once the DB environment has been initialized by a call to db_appinit, no fields other than db_errpfx should be modified.

The db_appinit function returns the value of errno on failure and 0 on success.

db_appexit The db_appexit function closes the initialized DB subsystems, freeing any allocated resources and closing any underlying subsystems.

When multiple threads are using the DB_ENV handle concurrently, only a single thread may call the db_appexit function.

The db_appexit function returns the value of errno on failure and 0 on success.

FILE NAMING

The most important task of db_appinit is to structure file naming within DB.

Each of the locking, logging, memory pool and transaction subsystems of DB require shared memory regions, backed by the filesystem. Further, cooperating applications (or multiple invocations of the same application) must agree on the location of the shared memory regions and other files used by the DB subsystems, the log files used by the logging subsystem, and, of course, the data files.

Although it is possible to specify full pathnames to all DB functions, this is cumbersome and requires that applications be recompiled when database files are moved. The db_appinit function makes it possible to place database files in a single directory, or in multiple directories, grouped by their function within the database.

Applications are normally expected to specify a single directory home for their database. This can be done easily in the call to db_appinit by specifying a value for the db_home argument. There are more complex configurations where it may be desirable to override db_home or provide supplementary path information.

The following describes the possible ways in which file naming information may be specified to the DB library. The specific circumstances and order in which these ways are applied are described in a subsequent paragraph.

db_home: If the db_home argument to db_appinit is non-NULL, its value may be used as the database home, and files named relative to its path.

DB_HOME: If the DB_HOME environment variable is set when db_appinit is called, its value may be used as the database home, and files named relative to its path.

db_config: The db_config argument to db_appinit may be used to specify an array of character strings of the format ``NAME VALUE'', that specify file name information for the process' DB environment. The whitespace delimiting the two parts of the entry may be one or more <space> or <tab> characters. (Leading or trailing <space> and <tab> characters are discarded.) Each entry must specify both the NAME and the VALUE of the pair. All entries with unrecognized NAME values will be ignored. The db_config array must be NULL terminated.

DB_CONFIG: The same information specified to the db_config argument to db_appinit may be specified using a configuration file. If a database home directory has been specified (either by the application specifying a non-NULL db_home argument to db_appinit, or by the application setting the DB_USE_ENVIRON or DB_USE_ENVIRON_ROOT flags and the DB_HOME environment variable being set), any file named ``DB_CONFIG'' in the database home directory will be read for lines of the format ``NAME VALUE''. The whitespace delimiting the two parts of the line may be one or more <space> or <tab> characters. (Leading or trailing <space> and <tab> characters are discarded.) All empty lines or lines whose first non-whitespace character is a hash character (``#'') will be ignored. Each line must specify both the NAME and the VALUE of the pair. All lines with unrecognized NAME values will be ignored.

The following ``NAME VALUE'' pairs in the db_config argument and the DB_CONFIG file are currently supported by DB.

DB_DATA_DIR: The path of a directory to be used as the location of the access method data files, e.g., paths specified to the db_open(3) function will be relative to this path.

: The DB_DATA_DIR paths are additive, and specifying more than one will result in each specified directory being searched for database data files. If multiple paths are specified, created data files will always be created in the first directory specified.

DB_LOG_DIR: The path of a directory to be used as the location of logging files, e.g., files created by the db_log(3) subsystem will be relative to this directory. If specified, this is the directory name that will be passed to log_open(3).

DB_TMP_DIR

The path of a directory to be used as the location of temporary files, e.g., files created to back in-memory access method databases will be created relative to this path. Note, these temporary files can potentially be quite large, depending on the size of the database.

If DB_TMP_DIR is not specified, the following environment variables are checked in order: ``TMPDIR'', ``TEMP'', ``TMP'' and ``TempFolder''. If one of them is set, temporary files are created relative to the directory it specifies.

If DB_TMP_DIR is not specified and none of the above environment variables are set, the first possible one of the following directories is used: /var/tmp, /usr/tmp, /temp, /tmp, C:/temp and C:/tmp.

The following describes the specific circumstances and order in which the different ways of specifying file naming information are applied. Specifically, DB file name processing proceeds sequentially through the following steps:

``/'': If any file name specified to any DB function begins with a leading slash, that file name is used without modification by DB.

DB_CONFIG

If a relevant configuration string (e.g., DB_DATA_DIR), is specified in the DB_CONFIG configuration file, the VALUE from the ``NAME VALUE'' pair is prepended to the current file name. If the resulting file name begins with a leading slash, the file name is used without further modification by DB.

The DB_CONFIG configuration file is intended to permit systems to customize file location for a database independent of applications using that database. For example, a database administrator can move the database log and data files to a different location without application recompilation.

db_config

If a relevant configuration string (e.g., DB_DATA_DIR), is specified in the db_config argument and is not specified in the DB_CONFIG file, the VALUE from the ``NAME VALUE'' pair is prepended to the current file name. If the resulting file name begins with a leading slash, the file name is used without further modification by DB.

The db_config argument is intended to permit applications to customize file location for a database. For example, an application writer can place data files and log files in different directories, or instantiate a new log directory each time the application runs.

DB_HOME

If the DB_HOME environment variable was set, (and the application has set the appropriate DB_USE_ENVIRON or DB_USE_ENVIRON_ROOT environment variable), its value is prepended to the current file name. If the resulting file name begins with a leading slash, the file name is used without further modification by DB.

The DB_HOME environment variable is intended to permit users and system administrators to override application and installation defaults, e.g.,

env DB_HOME=/database/my_home application

Alternatively, application writers are encouraged to support the -h option found in the supporting DB utilities to let users specify a database home.

db_home: If the application specified a non-NULL db_home argument to db_appinit (and the database home was not already specified using the DB_HOME environment variable) its value is prepended to the current file name. If the resulting file name begins with a leading slash, the file name is used without further modification by DB.

(nothing): Finally, all file names are interpreted relative to the current working directory of the process.

The common model for a DB environment is one where only the DB_HOME environment variable, or the db_home argument, is specified. In this case, all data files will be presumed to be relative to that directory, and all files created by the DB subsystems will be created in that directory.

The more complex model for a transaction environment might be one where a database home is specified, using either the DB_HOME environment variable or the db_home argument to db_appinit, and then DB_DATA_DIR and DB_LOG_DIR are set to the relative path names of directories underneath the home directory using the db_config argument to db_appinit or the DB_CONFIG file.

EXAMPLES

Store all files in the directory /a/database:

db_appinit("/a/database", NULL, ...);

Create temporary backing files in /b/temporary, and all other files in /a/database:

char *config[] = {
    "DB_TMP_DIR /b/temporary",
    NULL
};
db_appinit("/a/database", config, ...);

Store data files in /a/database/datadir, log files in /a/database/logdir, and all other files in the directory /a/database:

char *config[] = {
    "DB_DATA_DIR datadir",
    "DB_LOG_DIR logdir",
    NULL
};
db_appinit("/a/database", config, ...);

Store data files in /a/database/data1 and /b/data2, and all other files in the directory /a/database. Any data files that are created will be created in /b/data2:

char *config[] = {
    "DB_DATA_DIR /b/data2",
    "DB_DATA_DIR data1",
    NULL
};
db_appinit("/a/database", config, ...);

See the file examples/ex_appinit.c in the DB source distribution for a C language code example of how an application might use db_appinit to configure its DB environment.

ERRORS

The db_appinit function may fail and return errno for any of the errors specified for the following DB and library functions: DB->close(3), calloc(3), db_appexit(3), fclose(3), fcntl(2), fflush(3), fgets(3), fopen(3), lock_open(3), lock_unlink(3), log_compare(3), log_get(3), log_open(3), log_unlink(3), malloc(3), memcpy(3), memp_open(3), memp_unlink(3), memset(3), realloc(3), stat(2), strchr(3), strcmp(3), strcpy(3), strdup(3), strerror(3), strlen(3), strsep(3), time(3), txn_checkpoint(3), txn_open(3), and txn_unlink(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_RECOVER or DB_RECOVER_FATAL flag was specified, and no log files were found.

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 DB environment for this process still exists.

The db_appexit function may fail and return errno for any of the errors specified for the following DB and library functions: lock_close(3), log_close(3), memp_close(3), and txn_close(3).

BUGS

Due to the constraints of the PA-RISC memory architecture, HP-UX does not allow a process to map a file into its address space multiple times. For this reason, each DB environment may be opened only once by a process on HP-UX, i.e., calls to appinit will fail if the specified DB environment has been opened and not subsequently closed.

On Windows/95, files that are opened by multiple processes do not share data correctly. To tell 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.