db_appinit
#include <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.
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_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 <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.
SEE ALSO
db_archive(1), db_checkpoint(1), db_deadlock(1), db_dump(1),
db_load(1), db_recover(1), db_stat(1), db_intro(3),
db_appinit(3), db_cursor(3), db_dbm(3), db_internal(3),
db_lock(3), db_log(3), db_mpool(3), db_open(3), db_thread(3),
db_txn(3)
Man(1) output converted with
man2html