2
<!--Copyright 1997-2002 by Sleepycat Software, Inc.-->
3
<!--All rights reserved.-->
4
<!--See the file LICENSE for redistribution information.-->
7
<title>Berkeley DB: DbEnv::set_flags</title>
8
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
9
<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++">
12
<a name="2"><!--meow--></a>
13
<table width="100%"><tr valign=top>
15
<h1>DbEnv::set_flags</h1>
18
<a href="../api_cxx/c_index.html"><img src="../images/api.gif" alt="API"></a><a href="../reftoc.html"><img src="../images/ref.gif" alt="Ref"></a>
23
#include <db_cxx.h>
26
DbEnv::set_flags(u_int32_t flags, int onoff);
29
<p>The <b>flags</b> value must be set to 0 or by bitwise inclusively <b>OR</b>'ing together one or
30
more of the following values:
33
the specified flags are cleared; otherwise they are set.
35
<p><dt><a name="DB_AUTO_COMMIT">DB_AUTO_COMMIT</a><dd>If set, operations for which no explicit transaction handle was
36
specified, and which modify databases in the database environment, will
37
be automatically enclosed within a transaction. If the call succeeds,
38
changes made by the operation will be recoverable. If the call fails,
39
the operation will have made no changes.
40
<p>Calling DbEnv::set_flags with the <a href="../api_cxx/env_set_flags.html#DB_AUTO_COMMIT">DB_AUTO_COMMIT</a> flag only affects
41
the specified <a href="../api_cxx/env_class.html">DbEnv</a> handle (and any other Berkeley DB handles opened
42
within the scope of that handle).
43
For consistent behavior across the environment, all <a href="../api_cxx/env_class.html">DbEnv</a>
44
handles opened in the environment must either set the <a href="../api_cxx/env_set_flags.html#DB_AUTO_COMMIT">DB_AUTO_COMMIT</a> flag
45
or the flag should be specified in the <b>DB_CONFIG</b> configuration
47
<p>The <a href="../api_cxx/env_set_flags.html#DB_AUTO_COMMIT">DB_AUTO_COMMIT</a> flag may be used to configure Berkeley DB at any time during
48
the life of the application.
49
<a name="3"><!--meow--></a>
50
<p><dt><a name="DB_CDB_ALLDB">DB_CDB_ALLDB</a><dd>If set, Berkeley DB Concurrent Data Store applications will perform locking on an environment-wide
51
basis rather than on a per-database basis.
52
<p>Calling DbEnv::set_flags with the DB_CDB_ALLDB flag only affects
53
the specified <a href="../api_cxx/env_class.html">DbEnv</a> handle (and any other Berkeley DB handles opened
54
within the scope of that handle).
55
For consistent behavior across the environment, all <a href="../api_cxx/env_class.html">DbEnv</a>
56
handles opened in the environment must either set the DB_CDB_ALLDB flag
57
or the flag should be specified in the <b>DB_CONFIG</b> configuration
59
<p>The DB_CDB_ALLDB flag may be used to configure Berkeley DB only before the
60
<a href="../api_cxx/env_open.html">DbEnv::open</a> interface is called.
61
<a name="4"><!--meow--></a>
62
<p><dt><a name="DB_DIRECT_DB">DB_DIRECT_DB</a><dd>If set and supported by the system, Berkeley DB will turn off system buffering
63
of Berkeley DB database files to avoid double caching.
64
<p>Calling DbEnv::set_flags with the DB_DIRECT_DB flag only affects
65
the specified <a href="../api_cxx/env_class.html">DbEnv</a> handle (and any other Berkeley DB handles opened
66
within the scope of that handle).
67
For consistent behavior across the environment, all <a href="../api_cxx/env_class.html">DbEnv</a>
68
handles opened in the environment must either set the DB_DIRECT_DB flag
69
or the flag should be specified in the <b>DB_CONFIG</b> configuration
71
<p>The DB_DIRECT_DB flag may be used to configure Berkeley DB at any time during
72
the life of the application.
73
<a name="5"><!--meow--></a>
74
<p><dt><a name="DB_DIRECT_LOG">DB_DIRECT_LOG</a><dd>If set and supported by the system, Berkeley DB will turn off system buffering
75
of Berkeley DB log files to avoid double caching.
76
<p>Calling DbEnv::set_flags with the DB_DIRECT_LOG flag only affects
77
the specified <a href="../api_cxx/env_class.html">DbEnv</a> handle (and any other Berkeley DB handles opened
78
within the scope of that handle).
79
For consistent behavior across the environment, all <a href="../api_cxx/env_class.html">DbEnv</a>
80
handles opened in the environment must either set the DB_DIRECT_LOG flag
81
or the flag should be specified in the <b>DB_CONFIG</b> configuration
83
<p>The DB_DIRECT_LOG flag may be used to configure Berkeley DB at any time during
84
the life of the application.
85
<a name="6"><!--meow--></a>
86
<p><dt><a name="DB_NOLOCKING">DB_NOLOCKING</a><dd>If set, Berkeley DB will grant all requested mutual exclusion mutexes and
87
database locks without regard for their actual availability. This
88
functionality should never be used for purposes other than debugging.
89
<p>Calling DbEnv::set_flags with the DB_NOLOCKING flag only affects
90
the specified <a href="../api_cxx/env_class.html">DbEnv</a> handle (and any other Berkeley DB handles opened
91
within the scope of that handle).
92
<p>The DB_NOLOCKING flag may be used to configure Berkeley DB at any time during
93
the life of the application.
94
<a name="7"><!--meow--></a>
95
<p><dt><a name="DB_NOMMAP">DB_NOMMAP</a><dd>If set, Berkeley DB will copy read-only database files into the local cache
96
instead of potentially mapping them into process memory (see the
97
description of the <a href="../api_cxx/env_set_mp_mmapsize.html">DbEnv::set_mp_mmapsize</a> method for further
99
<p>Calling DbEnv::set_flags with the DB_NOMMAP flag only affects
100
the specified <a href="../api_cxx/env_class.html">DbEnv</a> handle (and any other Berkeley DB handles opened
101
within the scope of that handle).
102
For consistent behavior across the environment, all <a href="../api_cxx/env_class.html">DbEnv</a>
103
handles opened in the environment must either set the DB_NOMMAP flag
104
or the flag should be specified in the <b>DB_CONFIG</b> configuration
106
<p>The DB_NOMMAP flag may be used to configure Berkeley DB at any time during
107
the life of the application.
108
<a name="8"><!--meow--></a>
109
<p><dt><a name="DB_NOPANIC">DB_NOPANIC</a><dd>If set, Berkeley DB will ignore any panic state in the database environment.
110
(Database environments in a panic state normally refuse all attempts to
111
call Berkeley DB functions, returning <a href="../ref/program/errorret.html#DB_RUNRECOVERY">DB_RUNRECOVERY</a>.) This
112
functionality should never be used for purposes other than debugging.
113
<p>Calling DbEnv::set_flags with the DB_NOPANIC flag only affects
114
the specified <a href="../api_cxx/env_class.html">DbEnv</a> handle (and any other Berkeley DB handles opened
115
within the scope of that handle).
116
<p>The DB_NOPANIC flag may be used to configure Berkeley DB at any time during
117
the life of the application.
118
<p><dt><a name="DB_OVERWRITE">DB_OVERWRITE</a><dd>Overwrite files stored in encrypted formats before deleting them. Berkeley DB
119
overwrites files using alternating 0xff, 0x00 and 0xff byte patterns.
120
For file overwriting to be effective, the underlying file must be stored
121
on a fixed-block filesystem. Systems with journaling or logging filesystems
122
will require operating system support and probably modification of the
124
<p>Calling DbEnv::set_flags with the DB_OVERWRITE flag only affects
125
the specified <a href="../api_cxx/env_class.html">DbEnv</a> handle (and any other Berkeley DB handles opened
126
within the scope of that handle).
127
<p>The DB_OVERWRITE flag may be used to configure Berkeley DB at any time during
128
the life of the application.
129
<a name="9"><!--meow--></a>
130
<p><dt><a name="DB_PANIC_ENVIRONMENT">DB_PANIC_ENVIRONMENT</a><dd>If set, Berkeley DB will set the panic state for the database environment.
131
(Database environments in a panic state normally refuse all attempts to
132
call Berkeley DB functions, returning <a href="../ref/program/errorret.html#DB_RUNRECOVERY">DB_RUNRECOVERY</a>.) This flag may
133
not be specified using the environment's <b>DB_CONFIG</b> file. This
134
flag may be used to configure Berkeley DB only after the <a href="../api_cxx/env_open.html">DbEnv::open</a>
136
<p>Calling DbEnv::set_flags with the DB_PANIC_ENVIRONMENT flag affects the
137
database environment, including all threads of control accessing the
138
database environment.
139
<p>The DB_PANIC_ENVIRONMENT flag may be used to configure Berkeley DB at any time during
140
the life of the application.
141
<a name="10"><!--meow--></a>
142
<p><dt><a name="DB_REGION_INIT">DB_REGION_INIT</a><dd>In some applications, the expense of page-faulting the underlying shared
143
memory regions can affect performance. (For example, if the page-fault
144
occurs while holding a lock, other lock requests can convoy, and overall
145
throughput may decrease.) If set, Berkeley DB will page-fault shared regions
146
into memory when initially creating or joining a Berkeley DB environment. In
147
addition, Berkeley DB will write the shared regions when creating an
148
environment, forcing the underlying virtual memory and filesystems to
149
instantiate both the necessary memory and the necessary disk space.
150
This can also avoid out-of-disk space failures later on.
151
<p>Calling DbEnv::set_flags with the DB_REGION_INIT flag only affects
152
the specified <a href="../api_cxx/env_class.html">DbEnv</a> handle (and any other Berkeley DB handles opened
153
within the scope of that handle).
154
For consistent behavior across the environment, all <a href="../api_cxx/env_class.html">DbEnv</a>
155
handles opened in the environment must either set the DB_REGION_INIT flag
156
or the flag should be specified in the <b>DB_CONFIG</b> configuration
158
<p>The DB_REGION_INIT flag may be used to configure Berkeley DB at any time during
159
the life of the application.
160
<a name="11"><!--meow--></a>
161
<p><dt><a name="DB_TXN_NOSYNC">DB_TXN_NOSYNC</a><dd>If set, Berkeley DB will not write or synchronously flush the log on transaction
163
This means that transactions exhibit the ACI (atomicity, consistency,
164
and isolation) properties, but not D (durability); that is, database
165
integrity will be maintained, but if the application or system fails,
166
it is possible some number of the most recently committed transactions
167
may be undone during recovery. The number of transactions at risk is
168
governed by how many log updates can fit into the log buffer, how often
169
the operating system flushes dirty buffers to disk, and how often the
171
<p>Calling DbEnv::set_flags with the DB_TXN_NOSYNC flag only affects
172
the specified <a href="../api_cxx/env_class.html">DbEnv</a> handle (and any other Berkeley DB handles opened
173
within the scope of that handle).
174
For consistent behavior across the environment, all <a href="../api_cxx/env_class.html">DbEnv</a>
175
handles opened in the environment must either set the DB_TXN_NOSYNC flag
176
or the flag should be specified in the <b>DB_CONFIG</b> configuration
178
<p>The DB_TXN_NOSYNC flag may be used to configure Berkeley DB at any time during
179
the life of the application.
180
<a name="12"><!--meow--></a>
181
<p><dt><a name="DB_TXN_WRITE_NOSYNC">DB_TXN_WRITE_NOSYNC</a><dd>If set, Berkeley DB will write, but will not synchronously flush, the log on
182
transaction commit or prepare.
183
This means that transactions exhibit the ACI (atomicity, consistency,
184
and isolation) properties, but not D (durability); that is, database
185
integrity will be maintained, but if the system fails, it is possible
186
some number of the most recently committed transactions may be undone
187
during recovery. The number of transactions at risk is governed by how
188
often the system flushes dirty buffers to disk and how often the log is
190
<p>Calling DbEnv::set_flags with the DB_TXN_WRITE_NOSYNC flag only affects
191
the specified <a href="../api_cxx/env_class.html">DbEnv</a> handle (and any other Berkeley DB handles opened
192
within the scope of that handle).
193
For consistent behavior across the environment, all <a href="../api_cxx/env_class.html">DbEnv</a>
194
handles opened in the environment must either set the DB_TXN_WRITE_NOSYNC flag
195
or the flag should be specified in the <b>DB_CONFIG</b> configuration
197
<p>The DB_TXN_WRITE_NOSYNC flag may be used to configure Berkeley DB at any time during
198
the life of the application.
199
<a name="13"><!--meow--></a>
200
<p><dt><a name="DB_YIELDCPU">DB_YIELDCPU</a><dd>If set, Berkeley DB will yield the processor immediately after each page or
201
mutex acquisition. This functionality should never be used for purposes
202
other than stress testing.
203
<p>Calling DbEnv::set_flags with the DB_YIELDCPU flag only affects
204
the specified <a href="../api_cxx/env_class.html">DbEnv</a> handle (and any other Berkeley DB handles opened
205
within the scope of that handle).
206
For consistent behavior across the environment, all <a href="../api_cxx/env_class.html">DbEnv</a>
207
handles opened in the environment must either set the DB_YIELDCPU flag
208
or the flag should be specified in the <b>DB_CONFIG</b> configuration
210
<p>The DB_YIELDCPU flag may be used to configure Berkeley DB at any time during
211
the life of the application.
213
<p>The DbEnv::set_flags method either returns a non-zero error value or throws an exception that
214
encapsulates a non-zero error value on failure, and returns 0 on success.
215
<p>The database environment's flag values may also be set using the environment's
216
<b>DB_CONFIG</b> file. The syntax of the entry in that file is a
217
single line with the string "set_flags", one or more whitespace characters,
218
and the interface flag argument as a string; for example, "set_flags
219
DB_TXN_NOSYNC". Because the <b>DB_CONFIG</b> file is read when the database
220
environment is opened, it will silently overrule configuration done
223
<p>The DbEnv::set_flags method may fail and throw an exception or return a non-zero error for the following conditions:
225
<p><dt>EINVAL<dd>An invalid flag value or parameter was specified.
227
<p>The DbEnv::set_flags method may fail and throw an exception or return a non-zero error for errors specified for other Berkeley DB and C library or system methods.
228
If a catastrophic error has occurred, the DbEnv::set_flags method may fail and
229
either return <a href="../ref/program/errorret.html#DB_RUNRECOVERY">DB_RUNRECOVERY</a> or throw a
230
<a href="../api_cxx/runrec_class.html">DbRunRecoveryException</a>,
231
in which case all subsequent Berkeley DB calls will fail in the same way.
233
<a href="../api_cxx/env_class.html">DbEnv</a>
235
<a href="../api_cxx/env_list.html">Database Environments and Related Methods</a>
237
<table width="100%"><tr><td><br></td><td align=right>
238
<a href="../api_cxx/c_index.html"><img src="../images/api.gif" alt="API"></a><a href="../reftoc.html"><img src="../images/ref.gif" alt="Ref"></a>
240
<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
added
removed
libdb/docs/api_cxx/env_set_flags.html
