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
|
<! "@(#)open.so 10.11 (Sleepycat) 10/2/98">
<!Copyright 1997, 1998 by Sleepycat Software, Inc. All rights reserved.>
<html>
<body bgcolor=white>
<head>
<title>Berkeley DB: DbTxnMgr::open</title>
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btr
ee,hash,hashing,transaction,transactions,locking,logging,access method,access me
thods,java,C,C++">
</head>
<h1>DbTxnMgr::open</h1>
<hr size=1 noshade>
<tt>
<h3>
<pre>
#include <db_cxx.h>
<p>
static int
DbTxnMgr::open(const char *dir,
u_int32_t flags, int mode, DbEnv *dbenv, DbTxnMgr **regionp);
</pre>
</h3>
<h1>Description</h1>
The DbTxnMgr::open
method copies a pointer, to the "transaction region" identified by the <i>directory</i>
<b>dir</b>, into the memory location referenced by <b>regionp</b>.
<p>
The
<b>dir</b> pathname argument is interpreted as described in
<a href="../../ref/env/naming.html">Berkeley DB File Naming</a>.
<p>
The <b>flags</b> and <b>mode</b> arguments specify how files will be opened
and/or created if they do not already exist.
The flags value is specified by logically <b>OR</b>'ing together one or more of the
following values:
<dl compact>
<a name="DB_CREATE">
<p><dt>DB_CREATE<dd>Create any underlying files, as necessary. If the files do not already
exist and the DB_CREATE flag is not specified, the call will fail.
<a name="DB_THREAD">
<p><dt>DB_THREAD<dd>Cause the m4_reg(DbTxnMgr) handle returned by DbTxnMgr::open to be useable
by multiple threads within a single address space, i.e., to be
<i>free-threaded</i>.
<a name="DB_TXN_NOSYNC">
<p><dt>DB_TXN_NOSYNC<dd>On transaction commit, do not synchronously flush the log.
This means that transactions exhibit the ACI (atomicity, consistency and
isolation) properties, but not D (durability), i.e., database integrity
will be maintained but it is possible that some number of the most
recently committed transactions may be undone during recovery instead of
being redone.
<p>
The number of transactions that are potentially at risk is governed by
how often the log is checkpointed (see <a href="../../utility/db_checkpoint.html">db_checkpoint</a> for more
information) and how many log updates can fit on a single log page.
</dl>
<p>
All files created by the transaction subsystem 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)))).
The group ownership of created files is based on the system and directory
defaults, and is not further specified by Berkeley DB.
<p>
The transaction subsystem is configured
based on the <b>dbenv</b> argument. It is expected that applications
will use a single <a href="../../api_cxx/DbEnv/class.html">DbEnv</a> object as the argument to all of the
subsystems in the Berkeley DB package. The fields of the <a href="../../api_cxx/DbEnv/class.html">DbEnv</a> object
used by DbTxnMgr::open are described below.
References to the <a href="../../api_cxx/DbEnv/class.html">DbEnv</a> object are maintained by Berkeley DB, so it
is necessary that the object and memory it references be valid until
the object is destroyed.
Any of the <a href="../../api_cxx/DbEnv/class.html">DbEnv</a> fields that are not explicitly set will default
to appropriate values.
<p>
The following fields in the <a href="../../api_cxx/DbEnv/class.html">DbEnv</a> object may be initialized, using
the appropriate set method, before calling DbTxnMgr::open:
<dl compact>
<p><dt>void *(*db_errcall)(char *db_errpfx, char *buffer);<dd>
<dt>FILE *db_errfile;<dd>
<dt>const char *db_errpfx;<dd>
<dt>class ostream *db_error_stream;<dd>
<dt>int db_verbose;<dd>The error fields of the <a href="../../api_cxx/DbEnv/class.html">DbEnv</a> behave as described for
<a href="../../api_cxx/DbEnv/appinit.html">DbEnv::appinit</a>.
<a name="lg_info">
<p><dt><a href="../../api_cxx/DbLog/class.html">DbLog</a> *lg_info;<dd>The logging region that is being used for this transaction environment.
The <b>lg_info</b> field contains a return value from the <a href="../../api_cxx/DbLog/open.html">DbLog::open</a> method.
<b>Logging is required for transaction environments,
and it is an error to not specify a logging region.</b>
<a name="lk_info">
<p><dt><a href="../../api_cxx/DbLockTab/class.html">DbLockTab</a> *lk_info;<dd>The locking region that is being used for this transaction environment.
The <b>lk_info</b> field contains a return value from the <a href="../../api_cxx/DbLockTab/open.html">DbLockTab::open</a> method.
If <b>lk_info</b> is NULL, no locking is done in this transaction
environment.
<a name="tx_max">
<p><dt>u_int32_t tx_max;<dd>The maximum number of simultaneous transactions that are supported.
This bounds the size of backing files and is used to derive limits for
the size of the lock region and logfiles.
When there are more than <b>tx_max</b> concurrent transactions, calls to
<a href="../../api_cxx/DbTxnMgr/begin.html">DbTxnMgr::begin</a> may cause backing files to grow.
If <b>tx_max</b> is 0, a default value is used.
<a name="tx_recover">
<p><dt>
int DbTxnMgr::recover(DbLog *logp, Dbt *DbLog::rec, DbLsn *lsnp, int redo, void *info);
<dd>A method that is called by <a href="../../api_cxx/DbTxn/abort.html">DbTxn::abort</a> during transaction abort.
This method takes five arguments:
<dl compact>
<p><dt>logp<dd>A pointer to the transaction log (<a href="../../api_cxx/DbLog/class.html">DbLog</a> *).
<p><dt>DbLog::rec<dd>A log record.
<p><dt>lsnp<dd>A pointer to a log sequence number (DB_LSN *).
<p><dt>redo<dd>An integer value that is set to one of the following values:
<dl compact>
<p><dt>DB_TXN_BACKWARD_ROLL<dd>The log is being read backward to determine which transactions have been
committed and which transactions were not (and should therefore be aborted
during recovery).
<p><dt>DB_TXN_FORWARD_ROLL<dd>The log is being played forward, any transaction ids encountered that
have not been entered into the list referenced by
<b>info</b> should be ignored.
<p><dt>DB_TXN_OPENFILES<dd>The log is being read to open all the files required to perform recovery.
<p><dt>DB_TXN_REDO<dd>Redo the operation described by the log record.
<p><dt>DB_TXN_UNDO<dd>Undo the operation described by the log record.
</dl>
<p><dt>info<dd>An opaque pointer used to reference the list of transaction IDs encountered
during recovery.
</dl>
<p>
If <b>tx_recover</b> is NULL, the default is that only Berkeley DB access method
operations are transaction protected, and the default recover method
will be used.
</dl>
<p>
The DbTxnMgr::open
method either returns <b>errno</b> or throws an exception that
encapsulates an <b>errno</b> on failure, and 0 on success.
<h1>Environment Variables</h1>
<p>
<dl compact>
<p><dt>DB_HOME<dd>If the <b>dbenv</b> argument to DbTxnMgr::open was initialized using
<a href="../../api_cxx/DbEnv/appinit.html">DbEnv::appinit</a> the environment variable <b>DB_HOME</b> may
be used as the path of the database home for the interpretation of
the <b>dir</b> argument.
</dl>
<p>
<dl compact>
<p><dt>TMPDIR<dd>If the <b>dbenv</b> argument to DbTxnMgr::open was NULL or not initialized
using <a href="../../api_cxx/DbEnv/appinit.html">DbEnv::appinit</a> the environment variable <b>TMPDIR</b> may
be used as the directory in which to create the transaction region, as described in
DbTxnMgr::open.
</dl>
<p>
<h1>Errors</h1>
If a fatal error occurs in Berkeley DB, the DbTxnMgr::open method may fail and either
return DB_RUNRECOVERY or throw an exception encapsulating DB_RUNRECOVERY,
at which point all subsequent database calls will also fail in the same
way. Methods marked as returning <b>errno</b> will, by default, throw
an exception that encapsulates the error information. The default error
behavior can be changed, see <a href="../../api_cxx/DbException/class.html">DbException</a>.
<p>
The DbTxnMgr::open
method may fail and throw an exception
for any of the errors specified for the following Berkeley DB and C library
functions:
abort(3),
close(3),
<a href="../../api_cxx/DbEnv/version.html">DbEnv::version</a>,
fcntl(3),
fflush(3),
fprintf(3),
free(3),
fstat(3),
fsync(3),
getenv(3),
getpid(3),
getuid(3),
isdigit(3),
lseek(3),
malloc(3),
memcpy(3),
memset(3),
mmap(3),
munmap(3),
open(3),
pstat_getdynamic(3),
read(3),
shmat(3),
shmctl(3),
shmdt(3),
sigfillset(3),
sigprocmask(3),
stat(3),
strerror(3),
strlen(3),
sysconf(3),
time(3),
<a href="../../api_cxx/DbTxnMgr/unlink.html">DbTxnMgr::unlink</a>,
unlink(3),
vfprintf(3),
vsnprintf(3),
and
write(3).
<p>
In addition, the DbTxnMgr::open
method may fail and throw an exception
or return <b>errno</b>
for the following conditions:
<dl compact>
<p><dt>EAGAIN<dd>The shared memory region was locked and (repeatedly) unavailable.
</dl>
<dl compact>
<p><dt>EINVAL<dd>An invalid flag value or parameter was specified.
<p>
The DB_THREAD flag was specified and spinlocks are not implemented for
this architecture.
<p>
The <b>dbenv</b> parameter was NULL.
</dl>
<p>
<h1>Class</h1>
<a href="../../api_cxx/DbTxnMgr/class.html">DbTxnMgr</a>
<p>
<h1>See Also</h1>
<a href="../../api_cxx/DbTxnMgr/begin.html">DbTxnMgr::begin</a>,
<a href="../../api_cxx/DbTxnMgr/checkpoint.html">DbTxnMgr::checkpoint</a>,
<a href="../../api_cxx/DbTxnMgr/close.html">DbTxnMgr::close</a>,
DbTxnMgr::open,
<a href="../../api_cxx/DbTxnMgr/stat.html">DbTxnMgr::stat</a>
and
<a href="../../api_cxx/DbTxnMgr/unlink.html">DbTxnMgr::unlink</a>.
</tt>
</body>
</html>
|
