docs/api_cxx/env_open.html

<!--$Id: env_open.so,v 10.114 2008/04/29 22:42:03 mbrey Exp $-->
<!--Copyright (c) 1997,2008 Oracle.  All rights reserved.-->
<!--See the file LICENSE for redistribution information.-->
<html>
<head>
<title>Berkeley DB: DbEnv::open</title>
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++">
</head>
<body bgcolor=white>
<table width="100%"><tr valign=top>
<td>
<b>DbEnv::open</b>
</td>
<td align=right>
<a href="../api_cxx/api_core.html"><img src="../images/api.gif" alt="API"></a>
<a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a></td>
</tr></table>
<hr size=1 noshade>
<tt>
<b><pre>
#include &lt;db_cxx.h&gt;
<p>
int
DbEnv::open(const char *db_home, u_int32_t flags, int mode);
<p>
int
DbEnv::get_home(const char **homep);
<p>
int
DbEnv::get_open_flags(u_int32_t *flagsp);
</pre></b>
<hr size=1 noshade>
<b>Description: DbEnv::open</b>
<p>The DbEnv::open method opens a Berkeley DB environment.  It provides a
structure for creating a consistent environment for processes using one
or more of the features of Berkeley DB.</p>
<p>The DbEnv::open method
either returns a non-zero error value
or throws an exception that encapsulates a non-zero error value on
failure, and returns 0 on success.
If DbEnv::open fails, the <a href="../api_cxx/env_close.html">DbEnv::close</a> method must be called
to discard the <a href="../api_cxx/env_class.html">DbEnv</a> handle.
</p>
<b>Parameters</b> <br>
 <b>db_home</b><ul compact><li>The <b>db_home</b> parameter is the database environment's home
directory.  For more information on <b>db_home</b>, and filename
resolution in general, see <a href="../ref/env/naming.html">Berkeley DB File
Naming</a>.  The environment variable <b>DB_HOME</b> may be used as
the path of the database home, as described in
<a href="../ref/env/naming.html">Berkeley DB File Naming</a>.</ul>
<p>When using a Unicode build on Windows (the default), the <b>db_home</b>
argument will be interpreted as a UTF-8 string, which is equivalent to
ASCII for Latin characters.</p>
 <b>flags</b><ul compact><li>The <b>flags</b> parameter specifies the subsystems that are initialized
and how the application's environment affects Berkeley DB file naming, among
other things.
The <b>flags</b> parameter must be set to 0 or by bitwise inclusively <b>OR</b>'ing together one
or more of the following values:
<p>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.</p>
<p>The choice of subsystems initialized for a Berkeley DB database environment
is specified by the thread of control initially creating the
environment.  Any subsequent thread of control joining the environment
will automatically be configured to use the same subsystems as were
created in the environment (unless the thread of control requests a
subsystem not available in the environment, which will fail).
Applications joining an environment, able to adapt to whatever
subsystems have been configured in the environment, should open the
environment without specifying any subsystem flags.  Applications
joining an environment, requiring specific subsystems from their
environments, should open the environment specifying those specific
subsystem flags.</p>
<br>
<b><a name="DB_INIT_CDB">DB_INIT_CDB</a></b><ul compact><li>Initialize locking for the <a href="../ref/cam/intro.html">Berkeley DB Concurrent Data Store</a>
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.</ul>
<b><a name="DB_INIT_LOCK">DB_INIT_LOCK</a></b><ul compact><li>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 <a href="../utility/db_deadlock.html">db_deadlock</a> and
<a href="../api_cxx/lock_detect.html">DbEnv::lock_detect</a> for more information.</ul>
<b><a name="DB_INIT_LOG">DB_INIT_LOG</a></b><ul compact><li>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.</ul>
<b><a name="DB_INIT_MPOOL">DB_INIT_MPOOL</a></b><ul compact><li>Initialize the shared memory buffer pool subsystem.  This subsystem
should be used whenever an application is using any Berkeley DB access
method.</ul>
<b><a name="DB_INIT_REP">DB_INIT_REP</a></b><ul compact><li>Initialize the replication subsystem.  This subsystem
should be used whenever an application plans on using replication.
The DB_INIT_REP flag requires the DB_INIT_TXN and
DB_INIT_LOCK flags also be configured.</ul>
<b><a name="DB_INIT_TXN">DB_INIT_TXN</a></b><ul compact><li>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.</ul>
<br>
<p>The second group of flags govern what recovery, if any, is performed when
the environment is initialized:</p>
<br>
<b><a name="DB_RECOVER">DB_RECOVER</a></b><ul compact><li>Run normal recovery on this environment before opening it for normal
use.  If this flag is set, the DB_CREATE and DB_INIT_TXN
flags must also be set, because the regions will be removed and
re-created, and transactions are required for application recovery.</ul>
<b><a name="DB_RECOVER_FATAL">DB_RECOVER_FATAL</a></b><ul compact><li>Run catastrophic recovery on this environment before opening it for
normal use.  If this flag is set, the DB_CREATE and
DB_INIT_TXN flags must also be set, because the regions will be
removed and re-created, and transactions are required for application
recovery.</ul>
<br>
<p>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 DbEnv::open method; or it
should remove the environment after recovery is completed, leaving
creation of the correctly sized environment to a subsequent call to
DbEnv::open.</p>
<p>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.</p>
<p>The DbEnv::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 <a href="../utility/db_archive.html">db_archive</a>
and <a href="../utility/db_recover.html">db_recover</a>.</p>
<p>The third group of flags govern file-naming extensions in the environment:</p>
<br>
<a name="2"><!--meow--></a>
<b><a name="DB_USE_ENVIRON">DB_USE_ENVIRON</a></b><ul compact><li>The Berkeley DB process' environment may be permitted to specify information
to be used when naming files; see <a href="../ref/env/naming.html">Berkeley DB File Naming</a>.  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.</ul>
<b><a name="DB_USE_ENVIRON_ROOT">DB_USE_ENVIRON_ROOT</a></b><ul compact><li>The Berkeley DB process' environment may be permitted to specify information
to be used when naming files; see <a href="../ref/env/naming.html">Berkeley DB File Naming</a>.  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).</ul>
<br>
<p>Finally, there are a few additional unrelated flags:</p>
<br>
<b><a name="DB_CREATE">DB_CREATE</a></b><ul compact><li>Cause Berkeley DB subsystems to create any underlying files, as necessary.</ul>
<b><a name="DB_LOCKDOWN">DB_LOCKDOWN</a></b><ul compact><li>Lock shared Berkeley DB environment files and memory-mapped databases into
memory.</ul>
<b><a name="DB_PRIVATE">DB_PRIVATE</a></b><ul compact><li>Allocate region memory from the heap instead of from memory backed by
the filesystem or system shared memory.
<p>This flag implies 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 accessible to more than a single process.  Second, mutexes are only
configured to work between threads.</p>
<p>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 Berkeley DB utilities (for example, <a href="../utility/db_archive.html">db_archive</a>,
<a href="../utility/db_checkpoint.html">db_checkpoint</a> or <a href="../utility/db_stat.html">db_stat</a>) are expected to access the
environment, the DB_PRIVATE flag should not be specified.</p>
<p>See <a href="../ref/env/region.html">Shared Memory Regions</a> for more
information.</p></ul>
<b><a name="DB_REGISTER">DB_REGISTER</a></b><ul compact><li>Check to see if recovery needs to be performed before opening the
database environment.  (For this check to be accurate, all processes
using the environment must specify DB_REGISTER when opening the
environment.)  If recovery needs to be performed for any reason
(including the initial use of the DB_REGISTER flag), and
DB_RECOVER is also specified, recovery will be performed and the
open will proceed normally.  If recovery needs to be performed and
DB_RECOVER is not specified, <a href="../ref/program/errorret.html#DB_RUNRECOVERY">DB_RUNRECOVERY</a> will be
returned.  If recovery does not need to be performed, the
DB_RECOVER flag will be ignored.  See
<a href="../ref/transapp/app.html">Architecting Transactional Data Store
applications</a> for more information.</ul>
<b><a name="DB_SYSTEM_MEM">DB_SYSTEM_MEM</a></b><ul compact><li>Allocate region memory from system shared memory instead of from heap
memory or memory backed by the filesystem.
<p>See <a href="../ref/env/region.html">Shared Memory Regions</a> for more
information.</p></ul>
<b><a name="DB_THREAD">DB_THREAD</a></b><ul compact><li>Cause the <a href="../api_cxx/env_class.html">DbEnv</a> handle returned by DbEnv::open to be
<i>free-threaded</i>; that is, concurrently usable by multiple
threads in the address space.  The DB_THREAD flag should be specified
if the <a href="../api_cxx/env_class.html">DbEnv</a> handle will be concurrently used by more than one
thread in the process, or if any <a href="../api_cxx/db_class.html">Db</a> handles opened in the scope
of the <a href="../api_cxx/env_class.html">DbEnv</a> handle will be concurrently used by more than one
thread in the process.
<p>This flag is required when using the Replication Manager.</p></ul>
<br></ul>
 <b>mode</b><ul compact><li>On Windows systems, the mode parameter is ignored.
<p>On UNIX systems or in IEEE/ANSI Std 1003.1 (POSIX) environments, files created by Berkeley DB
are created with mode <b>mode</b> (as described in <b>chmod</b>(2))
and modified by the process' umask value at the time of creation (see
<b>umask</b>(2)).  Created files are owned by the process owner; the
group ownership of created files is based on the system and directory
defaults, and is not further specified by Berkeley DB.  System shared memory
segments created by Berkeley DB are created with mode <b>mode</b>, unmodified
by the process' umask value.  If <b>mode</b> is 0, Berkeley DB will use a
default mode of readable and writable by both owner and group.</p></ul>
<br>
<a name="3"><!--meow--></a>
<br><b>Errors</b>
<p>The DbEnv::open method
may fail and throw
<a href="../api_cxx/except_class.html">DbException</a>,
encapsulating one of the following non-zero errors, or return one of
the following non-zero errors:</p>
<br>
<b>DB_RUNRECOVERY</b><ul compact><li>The DB_REGISTER flag was specified, a failure has occurred, and no
recovery flag was specified.</ul>
<br>
<br>
<b>DB_VERSION_MISMATCH</b><ul compact><li>The version of the Berkeley DB library doesn't match the version that created
the database environment.</ul>
<br>
<br>
<b>EAGAIN</b><ul compact><li>The shared memory region was locked and (repeatedly) unavailable.</ul>
<br>
<br>
<b>EINVAL</b><ul compact><li>If 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 <b>NAME VALUE</b> entry or line was found; or if an
invalid flag value or parameter was specified.</ul>
<br>
<br>
<b>ENOSPC</b><ul compact><li>HP-UX only:
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 Berkeley DB environment may be opened only once by a
process on HP-UX; that is, calls to DbEnv::open will fail if the
specified Berkeley DB environment has been opened and not subsequently closed.</ul>
<br>
<br>
<b>ENOENT</b><ul compact><li>The file or directory does not exist.</ul>
<br>
<hr size=1 noshade>
<b>Description: DbEnv::get_home</b>
<p>The DbEnv::get_home method returns the database environment home directory.</p>
<p>The DbEnv::get_home method may be called at any time during the life of the
application.</p>
<hr size=1 noshade>
<b>Description: DbEnv::get_open_flags</b>
<p>The DbEnv::get_open_flags method returns the open method flags originally used to create the database environment.</p>
<p>The DbEnv::get_open_flags method may not be called before the DbEnv::open method is called.</p>
<p>The DbEnv::get_open_flags method
either returns a non-zero error value
or throws an exception that encapsulates a non-zero error value on
failure, and returns 0 on success.
</p>
<b>Parameters</b> <br>
 <b>flagsp</b><ul compact><li>The DbEnv::get_open_flags method returns  the
open method flags originally used to create the database environment in <b>flagsp</b>.</ul>
<br>
<hr size=1 noshade>
<br><b>Class</b>
<a href="../api_cxx/env_class.html">DbEnv</a>
<br><b>See Also</b>
<a href="../api_cxx/env_list.html">Database Environments and Related Methods</a>
</tt>
<table width="100%"><tr><td><br></td><td align=right>
<a href="../api_cxx/api_core.html"><img src="../images/api.gif" alt="API"></a><a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a>
</td></tr></table>
<p><font size=1>Copyright (c) 1996,2008 Oracle.  All rights reserved.</font>
</body>
</html>