DB_ENV->open
|
![API](../images/api.gif)
|
#include <db.h>
int
DB_ENV->open(DB_ENV *, char *db_home, u_int32_t flags, int mode);
Description
The DB_ENV->open function is the interface for opening the Berkeley DB
environment. It provides a structure for creating a consistent
environment for processes using one or more of the features of Berkeley DB.
The db_home argument to DB_ENV->open (and filename
resolution in general) is described in
Berkeley DB File Naming.
The flags argument specifies the subsystems that are initialized
and how the application's environment affects Berkeley DB file naming, among
other things.
The flags value must be set to 0 or by bitwise inclusively OR'ing together one or
more of the following values:
Because there are a large number of flags that can be specified, they
have been grouped together by functionality. The first group of flags
indicates which of the Berkeley DB subsystems should be initialized:
- DB_JOINENV
- Join an existing environment. This option allows applications to
join an existing environment without knowing which Berkeley DB subsystems
the environment supports.
- DB_INIT_CDB
- Initialize locking for the Berkeley DB Concurrent Data Store
product. In this mode, Berkeley DB provides multiple reader/single writer
access. The only other subsystem that should be specified with the
DB_INIT_CDB flag is DB_INIT_MPOOL.
- DB_INIT_LOCK
- Initialize the locking subsystem. This subsystem should be used when
multiple processes or threads are going to be reading and writing a
Berkeley DB database, so that they do not interfere with each other. If all
threads are accessing the database(s) read-only, locking is unnecessary.
When the DB_INIT_LOCK flag is specified, it is usually necessary
to run a deadlock detector, as well. See db_deadlock and
DB_ENV->lock_detect for more information.
- DB_INIT_LOG
- Initialize the logging subsystem. This subsystem should be used when
recovery from application or system failure is necessary. If the log
region is being created and log files are already present, the log files
are reviewed; subsequent log writes are appended to the end of the log,
rather than overwriting current log entries.
- DB_INIT_MPOOL
- Initialize the shared memory buffer pool subsystem. This subsystem
should be used whenever an application is using any Berkeley DB access
method.
- DB_INIT_TXN
- Initialize the transaction subsystem. This subsystem should be used
when recovery and atomicity of multiple operations are important. The
DB_INIT_TXN flag implies the DB_INIT_LOG flag.
The second group of flags govern what recovery, if any, is performed when
the environment is initialized:
- 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
because the regions will be removed and re-created.
- 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 because the regions will be removed and re-created.
A standard part of the recovery process is to remove the existing Berkeley DB
environment and create a new one in which to perform recovery. If the
thread of control performing recovery does not specify the correct
region initialization information (for example, the correct memory pool
cache size), the result can be an application running in an environment
with incorrect cache and other subsystem sizes. For this reason, the
thread of control performing recovery should specify correct
configuration information before calling the DB_ENV->open function; or it
should remove the environment after recovery is completed, leaving
creation of the correctly sized environment to a subsequent call to
DB_ENV->open.
All Berkeley DB recovery processing must be single-threaded; that is, only a
single thread of control may perform recovery or access a Berkeley DB
environment while recovery is being performed. Because it is not an
error to specify DB_RECOVER for an environment for which no
recovery is required, it is reasonable programming practice for the
thread of control responsible for performing recovery and creating the
environment to always specify the DB_CREATE and
DB_RECOVER flags during startup.
The DB_ENV->open function returns successfully if DB_RECOVER
or DB_RECOVER_FATAL is specified and no log files exist, so it
is necessary to ensure that all necessary log files are present before
running recovery. For further information, consult db_archive
and db_recover.
The third group of flags govern file-naming extensions in the environment:
- DB_USE_ENVIRON
- The Berkeley DB process' environment may be permitted to specify information
to be used when naming files; see Berkeley DB File Naming. Because permitting users to specify which files
are used can create security problems, environment information will be
used in file naming for all users only if the DB_USE_ENVIRON flag is
set.
- DB_USE_ENVIRON_ROOT
- The Berkeley DB process' environment may be permitted to specify information
to be used when naming files; see Berkeley DB File Naming. Because 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 appropriate permissions (for example, users with a user-ID
of 0 on UNIX systems).
Finally, there are a few additional unrelated flags:
- DB_CREATE
- Cause Berkeley DB subsystems to create any underlying files, as necessary.
- DB_LOCKDOWN
- Lock shared Berkeley DB environment files and memory-mapped databases into
memory.
- DB_PRIVATE
- Specify that the environment will only be accessed by a single process
(although that process may be multithreaded). This flag has two effects
on the Berkeley DB environment. First, all underlying data structures are
allocated from per-process memory instead of from shared memory that is
potentially accessible to more than a single process. Second, mutexes
are only configured to work between threads.
This flag should not be specified if more than a single process is
accessing the environment because it is likely to cause database
corruption and unpredictable behavior. For example, if both a server
application and the Berkeley DB utility db_stat are expected to access
the environment, the DB_PRIVATE flag should not be
specified.
- DB_SYSTEM_MEM
- Allocate memory from system shared memory instead of from memory backed
by the filesystem. See Shared Memory
Regions for more information.
- DB_THREAD
- Cause the DB_ENV handle returned by DB_ENV->open to be
free-threaded; that is, usable by multiple threads within a
single address space.
On UNIX systems or in IEEE/ANSI Std 1003.1 (POSIX) environments, all files created by
Berkeley DB are created with mode mode (as described in chmod(2)) and modified by the process' umask value at the time of creation
(see umask(2)). If mode is 0, Berkeley DB will use a default
mode of readable and writable by both owner and group. On Windows
systems, the mode argument is ignored. The group ownership of created
files is based on the system and directory defaults, and is not further
specified by Berkeley DB.
The DB_ENV->open function returns a non-zero error value on failure and 0 on success.
Environment Variables
- DB_HOME
- The environment variable DB_HOME may be used as the path of
the database home, as described in
Berkeley DB File Naming.
Errors
The DB_ENV->open function may fail and return a non-zero error for the following conditions:
- EAGAIN
- The shared memory region was locked and (repeatedly) unavailable.
- EINVAL
- An invalid flag value or parameter was specified.
The DB_THREAD flag was specified and fast mutexes are not
available for this architecture.
The DB_HOME or TMPDIR environment variables were set, but empty.
An incorrectly formatted NAME VALUE entry or line was found.
- ENOSPC
- HP-UX only: a previously created Berkeley DB environment for this process still
exists.
The DB_ENV->open function may fail and return a non-zero error for errors specified for other Berkeley DB and C library or system functions.
If a catastrophic error has occurred, the DB_ENV->open function may fail and return
DB_RUNRECOVERY, in which case all subsequent Berkeley DB calls will fail
in the same way.
See Also
db_env_create,
DB_ENV->close,
DB_ENV->err, DB_ENV->errx
DB_ENV->open,
DB_ENV->remove,
DB_ENV->set_alloc,
DB_ENV->set_cachesize,
DB_ENV->set_data_dir,
DB_ENV->set_errcall,
DB_ENV->set_errfile,
DB_ENV->set_errpfx,
DB_ENV->set_feedback,
DB_ENV->set_flags,
DB_ENV->set_paniccall,
DB_ENV->set_recovery_init,
DB_ENV->set_rpc_server,
DB_ENV->set_shm_key,
DB_ENV->set_tas_spins,
DB_ENV->set_tmp_dir,
DB_ENV->set_timeout,
DB_ENV->set_verbose,
db_strerror
and
db_version.
Copyright Sleepycat Software