db_appinit
NAME
db_appinit - initializing the DB environment
SYNOPSIS
#include <db.h>
char *
db_version(int *major, int *minor, int *patch);
int
db_appinit(char *db_home,
char *db_config[], DB_ENV *dbenv, int 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 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 db_intro(3).
db_version
The db_version function returns a pointer to a string con-
taining 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 initial-
ize 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 ini-
tialized 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 or writing a DB
database, so that they do not interfere with each
other. 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 open-
ing it for normal use. If this flag is set, the
DB_CREATE, DB_INIT_TXN, and DB_INIT_LOG flags must
also be set since the regions will be removed and
recreated. For further information, consult the man
page for 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, DB_INIT_TXN, and DB_INIT_LOG flags must
also be set since the regions will be removed and
recreated. For further information, consult the man
page for db_recover(1).
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 spec-
ify information to be used when naming files (see the
section entitled ``FILE NAMING'' below). As permit-
ting 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 spec-
ify information to be used when naming files (see the
section entitled ``FILE NAMING'' below). As permit-
ting 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 argu-
ment to db_appinit, which is a pointer to a structure of
type DB_ENV (typedef'd in <db.h>). It is expected that
applications will use a single DB_ENV structure as the
argument to all of the subsystems in the DB package. 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 DB_ENV used by db_appinit are described
below. As references to the DB_ENV structure may be main-
tained by db_appinit, it is necessary that the DB_ENV
structure and memory it references be valid until after
the db_appexit function is called. 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 pos-
sible.
The following DB_ENV fields 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 com-
pletely 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 pre-
ceded 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.
int (*db_yield)(void);
The DB library makes a system call to pause for some
number of microseconds whenever it is necessary to
wait on a lock. This may not be optimal, especially
in a thread-only environment where it will be more
efficient to explicitly yield the processor to
another thread. If db_yield returns 0, indicating
success, the lock will be re-tried, otherwise, the
default descheduling function will be called and then
the lock will be re-tried. Note, it is probably
incorrect to supply a thread db_yield function if
more than a single process is operating in the DB
environment. This is because most thread-yield func-
tions will not allow other processes to run, and the
lock may be held by another process, not by another
thread.
Solaris architecture note: Because of bugs in ver-
sions of Solaris before version 5.6, DB uses the
sema_wait(3T) call instead of the sema_trywait(3T)
call. For this reason, setting the db_yield field of
the DB_ENV structure will have no effect on Solaris.
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 sub-
system has permission to read and write underlying files
as necessary, and optionally to create files. (All cre-
ated 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 rele-
vant to the subsystems being initialized must themselves
be initialized before db_appinit is called. See the man-
ual 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 applica-
tions; 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 auto-
matically 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.
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 subsys-
tems, freeing any allocated resources and closing any
underlying subsystems.
When multiple threads are using the DB_ENV handle concur-
rently, only a single thread may call the db_appexit func-
tion.
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 appli-
cations 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 eas-
ily in the call to db_appinit by specifying a value for
the db_home argument. There are more complex configura-
tions 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 trail-
ing <space> and <tab> characters are discarded.)
Each entry must specify both the NAME and the VALUE
of the pair. All entries with unrecognized NAME val-
ues will be ignored. The db_config array must be
NULL terminated.
DB_CONFIG
The same information specified to the db_config argu-
ment to db_appinit may be specified using a configu-
ration 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_ENV-
IRON_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 argu-
ment 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-mem-
ory access method databases will be created relative
to this path. Note, these temporary files can poten-
tially be quite large, depending on the size of the
database.
If DB_TMP_DIR is not specified, the following envi-
ronment 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 nam-
ing 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 configu-
ration 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 per-
mit 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 cur-
rent 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 applica-
tions to customize file location for a database. For
example, an application writer can place data files
and log files in different directories, or instanti-
ate 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 per-
mit 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 argu-
ment to db_appinit (and the database home was not
already specified using the DB_HOME environment vari-
able) its value is prepended to the current file
name. If the resulting file name begins with a lead-
ing slash, the file name is used without further mod-
ification 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.
COMPILING
On IRIX, if you are compiling a threaded application, you
must compile with the -D_SGI_MP_SOURCE flag:
cc -D_SGI_MP_SOURCE ...
On OSF/1, if you are compiling a threaded application, you
must compile with the -D_REENTRANT flag:
cc -D_REENTRANT ...
On Solaris, if you are compiling a threaded application,
you must compile with the -D_REENTRANT flag and link with
the -lthread library:
cc -D_REENTRANT ... -lthread
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 datadir",
"DB_LOG 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 /b/data2",
"DB_DATA data1",
NULL
};
db_appinit("/a/database", config, ...);
See the file examples/ex_appinit.c in the DB source dis-
tribution for a C language code example of how an applica-
tion 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: getuid(2), db_appexit(3), fclose(3), fflush(3),
fgets(3), fopen(3), getenv(3), lock_open(3), log_open(3),
malloc(3), memp_open(3), realloc(3), snprintf(3), stat(3),
strcmp(3), strdup(3), strerror(3), strsep(3), txn_open(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.
TMPDIR If the dbenv argument to _open was NULL or not
initialized using db_appinit, the environment vari-
able TMPDIR may be used as the directory in which to
create the , as described in the _open section above.
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, only a
single DB environment may be maintained by a process on
HP-UX, i.e., calls to db_appinit will fail if a previously
created DB environment has not been closed.
Because of bugs in versions of Solaris before version 5.6,
setting the db_yield field of the DB_ENV structure will
have no effect on Solaris.
SEE ALSO
db_archive(1), db_checkpoint(1), db_deadlock(1), db_dump(1),
db_intro(3), db_load(1), db_recover(1), db_stat(1),
db_appinit(3), db_cursor(3), db_dbm(3), db_lock(3), db_log(3),
db_mpool(3), db_open(3), db_txn(3)