mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-11-01 22:55:23 +00:00
628 lines
30 KiB
HTML
628 lines
30 KiB
HTML
|
<HTML>
|
||
|
|
<HEAD>
|
||
|
|
<TITLE>db_appinit</TITLE>
|
||
|
|
</HEAD>
|
||
|
|
<BODY BGCOLOR=white>
|
||
|
|
<H1>db_appinit</H1>
|
||
|
|
<HR SIZE=1 NOSHADE>
|
||
|
|
<PRE>
|
||
|
|
<!-- Manpage converted by man2html 3.0.1 -->
|
||
|
|
<B>#include</B> <B><db.h></B>
|
||
|
|
|
||
|
|
<B>char</B> <B>*</B>
|
||
|
|
<B>db</B>_<B>version(int</B> <B>*major,</B> <B>int</B> <B>*minor,</B> <B>int</B> <B>*patch);</B>
|
||
|
|
|
||
|
|
<B>int</B>
|
||
|
|
<B>db</B>_<B>appinit(char</B> <B>*db</B>_<B>home,</B>
|
||
|
|
<B>char</B> <B>*db</B>_<B>config[],</B> <B>DB</B>_<B>ENV</B> <B>*dbenv,</B> <B>u</B>_<B>int32</B>_<B>t</B> <B>flags);</B>
|
||
|
|
|
||
|
|
<B>int</B>
|
||
|
|
<B>db</B>_<B>appexit(DB</B>_<B>ENV</B> <B>*dbenv);</B>
|
||
|
|
|
||
|
|
|
||
|
|
</PRE>
|
||
|
|
<H2>DESCRIPTION</H2><PRE>
|
||
|
|
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 <B><A HREF="db_intro.html">db_intro(3)</A></B>.
|
||
|
|
|
||
|
|
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 <B>or</B>'ing together one or more of the following values:
|
||
|
|
|
||
|
|
DB_CREATE
|
||
|
|
Cause subsystems to create any underlying files, as
|
||
|
|
necessary. (See <B><A HREF="db_lock.html">db_lock(3)</A></B>, <B><A HREF="db_log.html">db_log(3)</A></B>, <B><A HREF="db_mpool.html">db_mpool(3)</A></B>,
|
||
|
|
<B><A HREF="db_open.html">db_open(3)</A></B> and <B><A HREF="db_txn.html">db_txn(3)</A></B> for more information.)
|
||
|
|
|
||
|
|
DB_INIT_LOCK
|
||
|
|
Initialize the lock subsystem; see <B><A HREF="db_lock.html">db_lock(3)</A></B>. 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,
|
||
|
|
<B><A HREF="db_deadlock.html">db_deadlock(1)</A></B>, as well.
|
||
|
|
|
||
|
|
DB_INIT_LOG
|
||
|
|
Initialize the log subsystem; see <B><A HREF="db_log.html">db_log(3)</A></B>. This
|
||
|
|
subsystem is used when recovery from application or
|
||
|
|
system failure is important.
|
||
|
|
|
||
|
|
DB_INIT_MPOOL
|
||
|
|
Initialize the mpool subsystem; see <B><A HREF="db_mpool.html">db_mpool(3)</A></B>.
|
||
|
|
This subsystem is used whenever the application is
|
||
|
|
using the DB access methods for any purpose.
|
||
|
|
|
||
|
|
DB_INIT_TXN
|
||
|
|
Initialize the transaction subsystem; see <B><A HREF="db_txn.html">db_txn(3)</A></B>.
|
||
|
|
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 <B><A HREF="db_mpool.html">db_mpool(3)</A></B> for
|
||
|
|
further information). Ignored unless DB_INIT_MPOOL
|
||
|
|
is also specified.
|
||
|
|
|
||
|
|
DB_NOMMAP
|
||
|
|
Do not map any files within this environment (see
|
||
|
|
<B><A HREF="db_mpool.html">db_mpool(3)</A></B> 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 <B><A HREF="db_archive.html">db_archive(1)</A></B>
|
||
|
|
and <B><A HREF="db_recover.html">db_recover(1)</A></B>.
|
||
|
|
|
||
|
|
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 <B><A HREF="db_archive.html">db_archive(1)</A></B>
|
||
|
|
and <B><A HREF="db_recover.html">db_recover(1)</A></B>.
|
||
|
|
|
||
|
|
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
|
||
|
|
<B><A HREF="db_lock.html">db_lock(3)</A></B>, <B><A HREF="db_log.html">db_log(3)</A></B>, <B><A HREF="db_mpool.html">db_mpool(3)</A></B>, <B><A HREF="db_open.html">db_open(3)</A></B> and
|
||
|
|
<B><A HREF="db_txn.html">db_txn(3)</A></B> for more information.)
|
||
|
|
|
||
|
|
DB_TXN_NOSYNC
|
||
|
|
On transaction commit, do not synchronously flush the
|
||
|
|
log (see <B><A HREF="db_txn.html">db_txn(3)</A></B> 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
|
||
|
|
<B><A HREF="db_appinit.html">db_appinit(3)</A></B>), 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 <B>bzero(3)</B> or
|
||
|
|
<B>memset(3)</B>.
|
||
|
|
|
||
|
|
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 <B><A HREF="db_lock.html">lock_open(3)</A></B> call.
|
||
|
|
|
||
|
|
DB_LOG *lg_info;
|
||
|
|
The return value of the <B><A HREF="db_log.html">log_open(3)</A></B> call.
|
||
|
|
|
||
|
|
DB_MPOOL *mp_info;
|
||
|
|
The return value of the <B><A HREF="db_mpool.html">memp_open(3)</A></B> call.
|
||
|
|
|
||
|
|
DB_TXNMGR *tx_info;
|
||
|
|
The return value of the <B><A HREF="db_txn.html">txn_open(3)</A></B> 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.
|
||
|
|
|
||
|
|
|
||
|
|
</PRE>
|
||
|
|
<H2>FILE NAMING</H2><PRE>
|
||
|
|
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 <B><A HREF="db_open.html">db_open(3)</A></B> 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 <B>first</B> 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 <B><A HREF="db_log.html">db_log(3)</A></B>
|
||
|
|
subsystem will be relative to this directory. If
|
||
|
|
specified, this is the directory name that will be
|
||
|
|
passed to <B><A HREF="db_log.html">log_open(3)</A></B>.
|
||
|
|
|
||
|
|
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 <B>-h</B> 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.
|
||
|
|
|
||
|
|
|
||
|
|
</PRE>
|
||
|
|
<H2>EXAMPLES</H2><PRE>
|
||
|
|
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.
|
||
|
|
|
||
|
|
|
||
|
|
</PRE>
|
||
|
|
<H2>ERRORS</H2><PRE>
|
||
|
|
The db_appinit function may fail and return errno for any
|
||
|
|
of the errors specified for the following DB and library
|
||
|
|
functions: <B><A HREF="db_open.html">DB->close(3)</A></B>, <B>calloc(3)</B>, <B><A HREF="db_appinit.html">db_appexit(3)</A></B>,
|
||
|
|
<B>fclose(3)</B>, <B>fcntl(2)</B>, <B>fflush(3)</B>, <B>fgets(3)</B>, <B>fopen(3)</B>,
|
||
|
|
<B><A HREF="db_lock.html">lock_open(3)</A></B>, <B><A HREF="db_lock.html">lock_unlink(3)</A></B>, <B><A HREF="db_log.html">log_compare(3)</A></B>, <B><A HREF="db_log.html">log_get(3)</A></B>,
|
||
|
|
<B><A HREF="db_log.html">log_open(3)</A></B>, <B><A HREF="db_log.html">log_unlink(3)</A></B>, <B>malloc(3)</B>, <B>memcpy(3)</B>,
|
||
|
|
<B><A HREF="db_mpool.html">memp_open(3)</A></B>, <B><A HREF="db_mpool.html">memp_unlink(3)</A></B>, <B>memset(3)</B>, <B>realloc(3)</B>,
|
||
|
|
<B>stat(2)</B>, <B>strchr(3)</B>, <B>strcmp(3)</B>, <B>strcpy(3)</B>, <B>strdup(3)</B>,
|
||
|
|
<B>strerror(3)</B>, <B>strlen(3)</B>, <B>strsep(3)</B>, <B>time(3)</B>,
|
||
|
|
<B><A HREF="db_txn.html">txn_checkpoint(3)</A></B>, <B><A HREF="db_txn.html">txn_open(3)</A></B>, and <B><A HREF="db_txn.html">txn_unlink(3)</A></B>.
|
||
|
|
|
||
|
|
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: <B><A HREF="db_lock.html">lock_close(3)</A></B>, <B><A HREF="db_log.html">log_close(3)</A></B>, <B><A HREF="db_mpool.html">memp_close(3)</A></B>, and
|
||
|
|
<B><A HREF="db_txn.html">txn_close(3)</A></B>.
|
||
|
|
|
||
|
|
|
||
|
|
</PRE>
|
||
|
|
<H2>BUGS</H2><PRE>
|
||
|
|
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.
|
||
|
|
|
||
|
|
|
||
|
|
</PRE>
|
||
|
|
<H2>SEE ALSO</H2><PRE>
|
||
|
|
<B><A HREF="db_archive.html">db_archive(1)</A></B>, <B><A HREF="db_checkpoint.html">db_checkpoint(1)</A></B>, <B><A HREF="db_deadlock.html">db_deadlock(1)</A></B>, <B><A HREF="db_dump.html">db_dump(1)</A></B>,
|
||
|
|
<B><A HREF="db_load.html">db_load(1)</A></B>, <B><A HREF="db_recover.html">db_recover(1)</A></B>, <B><A HREF="db_stat.html">db_stat(1)</A></B>, <B><A HREF="db_intro.html">db_intro(3)</A></B>,
|
||
|
|
<B><A HREF="db_appinit.html">db_appinit(3)</A></B>, <B><A HREF="db_cursor.html">db_cursor(3)</A></B>, <B><A HREF="db_dbm.html">db_dbm(3)</A></B>, <B><A HREF="db_internal.html">db_internal(3)</A></B>,
|
||
|
|
<B><A HREF="db_lock.html">db_lock(3)</A></B>, <B><A HREF="db_log.html">db_log(3)</A></B>, <B><A HREF="db_mpool.html">db_mpool(3)</A></B>, <B><A HREF="db_open.html">db_open(3)</A></B>, <B><A HREF="db_thread.html">db_thread(3)</A></B>,
|
||
|
|
<B><A HREF="db_txn.html">db_txn(3)</A></B>
|
||
|
|
|
||
|
|
</PRE>
|
||
|
|
<HR SIZE=1 NOSHADE>
|
||
|
|
<ADDRESS>
|
||
|
|
Man(1) output converted with
|
||
|
|
<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
|
||
|
|
</ADDRESS>
|
||
|
|
</BODY>
|
||
|
|
</HTML>
|