1
<!--$Id: env_open.so,v 10.69 2001/05/15 14:44:07 bostic Exp $-->
2
<!--Copyright 1997-2001 by Sleepycat Software, Inc.-->
3
<!--All rights reserved.-->
6
<title>Berkeley DB: DB_ENV->open</title>
7
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
8
<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++">
11
<a name="2"><!--meow--></a>
12
<table width="100%"><tr valign=top>
14
<h1>DB_ENV->open</h1>
17
<a href="../api_c/c_index.html"><img src="../images/api.gif" alt="API"></a><a href="../reftoc.html"><img src="../images/ref.gif" alt="Ref"></a>
25
DB_ENV->open(DB_ENV *, char *db_home, u_int32_t flags, int mode);
28
<p>The DB_ENV->open function is the interface for opening the Berkeley DB
29
environment. It provides a structure for creating a consistent
30
environment for processes using one or more of the features of Berkeley DB.
31
<p>The <b>db_home</b> argument to DB_ENV->open (and filename
32
resolution in general) is described in
33
<a href="../ref/env/naming.html">Berkeley DB File Naming</a>.
34
<p>The <b>flags</b> argument specifies the subsystems that are initialized
35
and how the application's environment affects Berkeley DB file naming, among
37
<p>The <b>flags</b> value must be set to 0 or by bitwise inclusively <b>OR</b>'ing together one or
38
more of the following values:
39
<p>Because there are a large number of flags that can be specified, they
40
have been grouped together by functionality. The first group of flags
41
indicates which of the Berkeley DB subsystems should be initialized:
43
<p><dt><a name="DB_JOINENV">DB_JOINENV</a><dd>Join an existing environment. This option allows applications to
44
join an existing environment without knowing which Berkeley DB subsystems
45
the environment supports.
46
<p><dt><a name="DB_INIT_CDB">DB_INIT_CDB</a><dd>Initialize locking for the <a href="../ref/cam/intro.html">Berkeley DB Concurrent Data Store</a>
47
product. In this mode, Berkeley DB provides multiple reader/single writer
48
access. The only other subsystem that should be specified with the
49
DB_INIT_CDB flag is DB_INIT_MPOOL.
50
<p><dt><a name="DB_INIT_LOCK">DB_INIT_LOCK</a><dd>Initialize the locking subsystem. This subsystem should be used when
51
multiple processes or threads are going to be reading and writing a
52
Berkeley DB database, so that they do not interfere with each other. If all
53
threads are accessing the database(s) read-only, locking is unnecessary.
54
When the DB_INIT_LOCK flag is specified, it is usually necessary
55
to run a deadlock detector, as well. See <a href="../utility/db_deadlock.html">db_deadlock</a> and
56
<a href="../api_c/lock_detect.html">lock_detect</a> for more information.
57
<p><dt><a name="DB_INIT_LOG">DB_INIT_LOG</a><dd>Initialize the logging subsystem. This subsystem should be used when
58
recovery from application or system failure is necessary. If the log
59
region is being created and log files are already present, the log files
60
are reviewed; subsequent log writes are appended to the end of the log,
61
rather than overwriting current log entries.
62
<p><dt><a name="DB_INIT_MPOOL">DB_INIT_MPOOL</a><dd>Initialize the shared memory buffer pool subsystem. This subsystem
63
should be used whenever an application is using any Berkeley DB access
65
<p><dt><a name="DB_INIT_TXN">DB_INIT_TXN</a><dd>Initialize the transaction subsystem. This subsystem should be used
66
when recovery and atomicity of multiple operations are important. The
67
DB_INIT_TXN flag implies the DB_INIT_LOG flag.
69
<p>The second group of flags govern what recovery, if any, is performed when
70
the environment is initialized:
72
<p><dt><a name="DB_RECOVER">DB_RECOVER</a><dd>Run normal recovery on this environment before opening it for normal
73
use. If this flag is set, the DB_CREATE flag must also be set
74
because the regions will be removed and re-created.
75
<p><dt><a name="DB_RECOVER_FATAL">DB_RECOVER_FATAL</a><dd>Run catastrophic recovery on this environment before opening it for
76
normal use. If this flag is set, the DB_CREATE flag must also
77
be set because the regions will be removed and re-created.
79
<p>A standard part of the recovery process is to remove the existing Berkeley DB
80
environment and create a new one in which to perform recovery. If the
81
thread of control performing recovery does not specify the correct
82
region initialization information (for example, the correct memory pool
83
cache size), the result can be an application running in an environment
84
with incorrect cache and other subsystem sizes. For this reason, the
85
thread of control performing recovery should specify correct
86
configuration information before calling the DB_ENV->open function; or it
87
should remove the environment after recovery is completed, leaving
88
creation of the correctly sized environment to a subsequent call to
90
<p>All Berkeley DB recovery processing must be single-threaded; that is, only a
91
single thread of control may perform recovery or access a Berkeley DB
92
environment while recovery is being performed. Because it is not an
93
error to specify DB_RECOVER for an environment for which no
94
recovery is required, it is reasonable programming practice for the
95
thread of control responsible for performing recovery and creating the
96
environment to always specify the DB_CREATE and
97
DB_RECOVER flags during startup.
98
<p>The DB_ENV->open function returns successfully if DB_RECOVER
99
or DB_RECOVER_FATAL is specified and no log files exist, so it
100
is necessary to ensure that all necessary log files are present before
101
running recovery. For further information, consult <a href="../utility/db_archive.html">db_archive</a>
102
and <a href="../utility/db_recover.html">db_recover</a>.
103
<p>The third group of flags govern file-naming extensions in the environment:
105
<a name="3"><!--meow--></a>
106
<p><dt><a name="DB_USE_ENVIRON">DB_USE_ENVIRON</a><dd>The Berkeley DB process' environment may be permitted to specify information
107
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
108
are used can create security problems, environment information will be
109
used in file naming for all users only if the DB_USE_ENVIRON flag is
111
<p><dt><a name="DB_USE_ENVIRON_ROOT">DB_USE_ENVIRON_ROOT</a><dd>The Berkeley DB process' environment may be permitted to specify information
112
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
113
are used can create security problems, if the DB_USE_ENVIRON_ROOT flag
114
is set, environment information will be used for file naming only for
115
users with appropriate permissions (for example, users with a user-ID
116
of 0 on UNIX systems).
118
<p>Finally, there are a few additional unrelated flags:
120
<p><dt><a name="DB_CREATE">DB_CREATE</a><dd>Cause Berkeley DB subsystems to create any underlying files, as necessary.
121
<p><dt><a name="DB_LOCKDOWN">DB_LOCKDOWN</a><dd>Lock shared Berkeley DB environment files and memory-mapped databases into
123
<p><dt><a name="DB_PRIVATE">DB_PRIVATE</a><dd>Specify that the environment will only be accessed by a single process
124
(although that process may be multithreaded). This flag has two effects
125
on the Berkeley DB environment. First, all underlying data structures are
126
allocated from per-process memory instead of from shared memory that is
127
potentially accessible to more than a single process. Second, mutexes
128
are only configured to work between threads.
129
<p>This flag should not be specified if more than a single process is
130
accessing the environment because it is likely to cause database
131
corruption and unpredictable behavior. For example, if both a server
132
application and the Berkeley DB utility <a href="../utility/db_stat.html">db_stat</a> are expected to access
133
the environment, the DB_PRIVATE flag should not be
135
<p><dt><a name="DB_SYSTEM_MEM">DB_SYSTEM_MEM</a><dd>Allocate memory from system shared memory instead of from memory backed
136
by the filesystem. See <a href="../ref/env/region.html">Shared Memory
137
Regions</a> for more information.
138
<p><dt><a name="DB_THREAD">DB_THREAD</a><dd>Cause the DB_ENV handle returned by DB_ENV->open to be
139
<i>free-threaded</i>; that is, usable by multiple threads within a
140
single address space.
142
<p>On UNIX systems or in IEEE/ANSI Std 1003.1 (POSIX) environments, all files created by
143
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
144
(see <b>umask</b>(2)). If <b>mode</b> is 0, Berkeley DB will use a default
145
mode of readable and writable by both owner and group. On Windows
146
systems, the mode argument is ignored. The group ownership of created
147
files is based on the system and directory defaults, and is not further
148
specified by Berkeley DB.
149
<p>The DB_ENV->open function returns a non-zero error value on failure and 0 on success.
150
<h1>Environment Variables</h1>
152
<p><dt>DB_HOME<dd>The environment variable <b>DB_HOME</b> may be used as the path of
153
the database home, as described in
154
<a href="../ref/env/naming.html">Berkeley DB File Naming</a>.
157
<p>The DB_ENV->open function may fail and return a non-zero error for the following conditions:
159
<p><dt>EAGAIN<dd>The shared memory region was locked and (repeatedly) unavailable.
162
<p><dt>EINVAL<dd>An invalid flag value or parameter was specified.
164
The DB_THREAD flag was specified and fast mutexes are not
165
available for this architecture.
166
<p>The DB_HOME or TMPDIR environment variables were set, but empty.
167
<p>An incorrectly formatted <b>NAME VALUE</b> entry or line was found.
170
<p><dt>ENOSPC<dd>HP-UX only: a previously created Berkeley DB environment for this process still
173
<p>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.
174
If a catastrophic error has occurred, the DB_ENV->open function may fail and return
175
<a href="../ref/program/errorret.html#DB_RUNRECOVERY">DB_RUNRECOVERY</a>, in which case all subsequent Berkeley DB calls will fail
178
<a href="../api_c/env_create.html">db_env_create</a>,
179
<a href="../api_c/env_close.html">DB_ENV->close</a>,
180
<a href="../api_c/env_err.html">DB_ENV->err</a>, <a href="../api_c/env_err.html">DB_ENV->errx</a>
181
<a href="../api_c/env_open.html">DB_ENV->open</a>,
182
<a href="../api_c/env_remove.html">DB_ENV->remove</a>,
183
<a href="../api_c/env_set_alloc.html">DB_ENV->set_alloc</a>,
184
<a href="../api_c/env_set_cachesize.html">DB_ENV->set_cachesize</a>,
185
<a href="../api_c/env_set_data_dir.html">DB_ENV->set_data_dir</a>,
186
<a href="../api_c/env_set_errcall.html">DB_ENV->set_errcall</a>,
187
<a href="../api_c/env_set_errfile.html">DB_ENV->set_errfile</a>,
188
<a href="../api_c/env_set_errpfx.html">DB_ENV->set_errpfx</a>,
189
<a href="../api_c/env_set_feedback.html">DB_ENV->set_feedback</a>,
190
<a href="../api_c/env_set_flags.html">DB_ENV->set_flags</a>,
191
<a href="../api_c/env_set_mutexlocks.html">DB_ENV->set_mutexlocks</a>,
192
<a href="../api_c/env_set_pageyield.html">db_env_set_pageyield</a>,
193
<a href="../api_c/env_set_paniccall.html">DB_ENV->set_paniccall</a>,
194
<a href="../api_c/env_set_panicstate.html">db_env_set_panicstate</a>,
195
<a href="../api_c/env_set_rec_init.html">DB_ENV->set_recovery_init</a>,
196
<a href="../api_c/env_set_rpc_server.html">DB_ENV->set_rpc_server</a>,
197
<a href="../api_c/env_set_region_init.html">db_env_set_region_init</a>,
198
<a href="../api_c/env_set_shm_key.html">DB_ENV->set_shm_key</a>,
199
<a href="../api_c/env_set_tas_spins.html">db_env_set_tas_spins</a>,
200
<a href="../api_c/env_set_tmp_dir.html">DB_ENV->set_tmp_dir</a>,
201
<a href="../api_c/env_set_verbose.html">DB_ENV->set_verbose</a>,
202
<a href="../api_c/env_strerror.html">db_strerror</a>
204
<a href="../api_c/env_version.html">db_version</a>.
206
<table width="100%"><tr><td><br></td><td align=right>
207
<a href="../api_c/c_index.html"><img src="../images/api.gif" alt="API"></a><a href="../reftoc.html"><img src="../images/ref.gif" alt="Ref"></a>
209
<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
added
removed
db/docs/api_c/env_open.html
