1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
|
<!--$Id: env_open.so,v 10.106 2005/09/23 14:36:39 bostic Exp $-->
<!--Copyright 1997-2005 by Sleepycat Software, Inc.-->
<!--All rights reserved.-->
<!--See the file LICENSE for redistribution information.-->
<html>
<head>
<title>Berkeley DB: DB_ENV->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>
<h3>DB_ENV->open</h3>
</td>
<td align=right>
<a href="../api_c/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>
<h3><pre>
#include <db.h>
<p>
int
DB_ENV->open(DB_ENV *dbenv, char *db_home, u_int32_t flags, int mode);
<p>
int
DB_ENV->get_home(DB_ENV *dbenv, const char **homep);
<p>
int
DB_ENV->get_open_flags(DB_ENV *dbenv, u_int32_t *flagsp);
</pre></h3>
<hr size=1 noshade>
<h3>Description: DB_ENV->open</h3>
<p>The DB_ENV->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 DB_ENV->open method
returns a non-zero error value on failure
and 0 on success.
If DB_ENV->open fails, the <a href="../api_c/env_close.html">DB_ENV->close</a> method should be called
to discard the <a href="../api_c/env_class.html">DB_ENV</a> handle.
</p>
<h3>Parameters</h3>
<dl compact>
<dt><b>db_home</b><dd>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>.
<p>On Windows, the <b>db_home</b> argument will be interpreted as a UTF-8
string, which is equivalent to ASCII for Latin characters.</p>
<dt><b>flags</b><dd>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>
<dl compact>
<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>
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.
<dt><a name="DB_INIT_LOCK">DB_INIT_LOCK</a><dd>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_c/lock_detect.html">DB_ENV->lock_detect</a> for more information.
<dt><a name="DB_INIT_LOG">DB_INIT_LOG</a><dd>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.
<dt><a name="DB_INIT_MPOOL">DB_INIT_MPOOL</a><dd>Initialize the shared memory buffer pool subsystem. This subsystem
should be used whenever an application is using any Berkeley DB access
method.
<dt><a name="DB_INIT_REP">DB_INIT_REP</a><dd>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.
<dt><a name="DB_INIT_TXN">DB_INIT_TXN</a><dd>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.
</dl>
<p>The second group of flags govern what recovery, if any, is performed when
the environment is initialized:</p>
<dl compact>
<dt><a name="DB_RECOVER">DB_RECOVER</a><dd>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.
<dt><a name="DB_RECOVER_FATAL">DB_RECOVER_FATAL</a><dd>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.
</dl>
<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 DB_ENV->open method; 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.</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 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 <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>
<dl compact>
<a name="2"><!--meow--></a>
<dt><a name="DB_USE_ENVIRON">DB_USE_ENVIRON</a><dd>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.
<dt><a name="DB_USE_ENVIRON_ROOT">DB_USE_ENVIRON_ROOT</a><dd>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).
</dl>
<p>Finally, there are a few additional unrelated flags:</p>
<dl compact>
<dt><a name="DB_CREATE">DB_CREATE</a><dd>Cause Berkeley DB subsystems to create any underlying files, as necessary.
<dt><a name="DB_LOCKDOWN">DB_LOCKDOWN</a><dd>Lock shared Berkeley DB environment files and memory-mapped databases into
memory.
<dt><a name="DB_PRIVATE">DB_PRIVATE</a><dd>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>
<dt><a name="DB_REGISTER">DB_REGISTER</a><dd>Check if a process has failed while using the database environment, that
is, if a process has exited with an open <a href="../api_c/env_class.html">DB_ENV</a> handle. (For
this check to be accurate, all processes using the environment must
specify DB_REGISTER when opening the environment.) If recovery
needs to be run for any reason and either DB_RECOVER or
DB_RECOVER_FATAL are also specified, recovery will be performed
and the open will proceed normally. If recovery needs to be run and no
recovery flag is specified, <a href="../ref/program/errorret.html#DB_RUNRECOVERY">DB_RUNRECOVERY</a> will be returned. If
recovery does not need to be run, the DB_RECOVER and
DB_RECOVER_FATAL flags will be ignored. See
<a href="../ref/transapp/app.html">Architecting Transactional Data Store
applications</a> for more information.
<dt><a name="DB_SYSTEM_MEM">DB_SYSTEM_MEM</a><dd>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>
<dt><a name="DB_THREAD">DB_THREAD</a><dd>Cause the <a href="../api_c/env_class.html">DB_ENV</a> handle returned by DB_ENV->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_c/env_class.html">DB_ENV</a> handle will be concurrently used by multiple
threads of control or if multiple DB handles, opened within the database
environment, will be used concurrently.
</dl>
<dt><b>mode</b><dd>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>
</dl>
<a name="3"><!--meow--></a>
<h3>Errors</h3>
<p>The DB_ENV->open method
may fail and return one of the following non-zero errors:</p>
<dl compact>
<dt>DB_RUNRECOVERY<dd>The DB_REGISTER flag was specified, a failure has occurred, and no
recovery flag was specified.
</dl>
<dl compact>
<dt>DB_VERSION_MISMATCH<dd>The version of the Berkeley DB library doesn't match the version that created
the database environment.
</dl>
<dl compact>
<dt>EAGAIN<dd>The shared memory region was locked and (repeatedly) unavailable.
</dl>
<dl compact>
<dt>EINVAL<dd>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.
</dl>
<dl compact>
<dt>ENOSPC<dd>HP-UX only: a previously created Berkeley DB environment for this process still
exists.
</dl>
<dl compact>
<dt>ENOENT<dd>The file or directory does not exist.
</dl>
<hr size=1 noshade>
<h3>Description: DB_ENV->get_home</h3>
<p>The DB_ENV->get_home method returns the database environment home directory.</p>
<p>The DB_ENV->get_home method may be called at any time during the life of the
application.</p>
<hr size=1 noshade>
<h3>Description: DB_ENV->get_open_flags</h3>
<p>The DB_ENV->get_open_flags method returns the open method flags.</p>
<p>The DB_ENV->get_open_flags method may not be called before the DB_ENV->open method has
been called.</p>
<p>The DB_ENV->get_open_flags method
returns a non-zero error value on failure
and 0 on success.
</p>
<h3>Parameters</h3>
<dl compact>
<dt><b>flagsp</b><dd>The DB_ENV->get_open_flags method returns the
open method flags in <b>flagsp</b>.
</dl>
<hr size=1 noshade>
<h3>Class</h3>
<a href="../api_c/env_class.html">DB_ENV</a>
<h3>See Also</h3>
<a href="../api_c/env_list.html">Database Environments and Related Methods</a>
</tt>
<table width="100%"><tr><td><br></td><td align=right>
<a href="../api_c/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><a href="../sleepycat/legal.html">Copyright (c) 1996-2005</a> <a href="http://www.sleepycat.com">Sleepycat Software, Inc.</a> - All rights reserved.</font>
</body>
</html>
|
