1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6 <title>DB_ENV->open()</title> 7 <link rel="stylesheet" href="apiReference.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Berkeley DB C API Reference" /> 10 <link rel="up" href="env.html" title="Chapter��5.�� The DB_ENV Handle" /> 11 <link rel="prev" href="envlsn_reset.html" title="DB_ENV->lsn_reset()" /> 12 <link rel="next" href="envremove.html" title="DB_ENV->remove()" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">DB_ENV->open()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="envlsn_reset.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��5.�� 23 The DB_ENV Handle 24 </th> 25 <td width="20%" align="right">��<a accesskey="n" href="envremove.html">Next</a></td> 26 </tr> 27 </table> 28 <hr /> 29 </div> 30 <div class="sect1" lang="en" xml:lang="en"> 31 <div class="titlepage"> 32 <div> 33 <div> 34 <h2 class="title" style="clear: both"><a id="envopen"></a>DB_ENV->open()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db.h> 39 40int 41DB_ENV->open(DB_ENV *dbenv, char *db_home, u_int32_t flags, int mode); </pre> 42 <p> 43 The <code class="methodname">DB_ENV->open()</code> method opens a Berkeley DB environment. It 44 provides a structure for creating a consistent environment for 45 processes using one or more of the features of Berkeley DB. 46 </p> 47 <p> 48 The <code class="methodname">DB_ENV->open()</code> method <span> 49 <span> 50 method returns a non-zero error value on failure and 0 on success. 51 </span> 52 53 </span> 54 If <code class="methodname">DB_ENV->open()</code> fails, the 55 <a class="xref" href="envclose.html" title="DB_ENV->close()">DB_ENV->close()</a> method must be 56 called to discard the <a class="link" href="env.html" title="Chapter��5.�� The DB_ENV Handle">DB_ENV</a> handle. 57 </p> 58 <div class="sect2" lang="en" xml:lang="en"> 59 <div class="titlepage"> 60 <div> 61 <div> 62 <h3 class="title"><a id="id1664086"></a>Parameters</h3> 63 </div> 64 </div> 65 </div> 66 <div class="sect3" lang="en" xml:lang="en"> 67 <div class="titlepage"> 68 <div> 69 <div> 70 <h4 class="title"><a id="id1664969"></a>db_home</h4> 71 </div> 72 </div> 73 </div> 74 <p> 75 The <span class="bold"><strong>db_home</strong></span> parameter is the database 76 environment's home directory. For more information on <span class="bold"><strong>db_home</strong></span>, and filename resolution in general, 77 see <a href="../../programmer_reference/env_naming.html" class="olink">Berkeley DB File Naming</a>. The environment variable <span class="bold"><strong>DB_HOME</strong></span> may be used as the path of the database 78 home, as described in <a href="../../programmer_reference/env_naming.html" class="olink">Berkeley DB File Naming</a>. 79 </p> 80 <p> 81 When using a Unicode build on Windows (the default), the 82 <span class="bold"><strong>db_home</strong></span> argument 83 will be interpreted as a UTF-8 string, which is equivalent to ASCII for 84 Latin characters. 85 </p> 86 </div> 87 <div class="sect3" lang="en" xml:lang="en"> 88 <div class="titlepage"> 89 <div> 90 <div> 91 <h4 class="title"><a id="id1664825"></a>flags</h4> 92 </div> 93 </div> 94 </div> 95 <p> 96 The <span class="bold"><strong>flags</strong></span> parameter specifies the subsystems that are 97 initialized and how the application's environment affects Berkeley DB file naming, 98 among other things. The <span class="bold"><strong>flags</strong></span> parameter must be set to 0 or by 99 bitwise inclusively <span class="bold"><strong>OR</strong></span>'ing together one or more of the values 100 described in this section. 101 </p> 102 <p> 103 Because there are a large number of flags that can be specified, they have been grouped together by 104 functionality. The first group of flags indicates which of the Berkeley DB subsystems should be 105 initialized. 106 </p> 107 <p> 108 The choice of subsystems initialized for a Berkeley DB database environment is specified by the 109 thread of control initially creating the environment. Any subsequent thread of control joining 110 the environment will automatically be configured to use the same subsystems as were created in 111 the environment (unless the thread of control requests a subsystem not available in the 112 environment, which will fail). Applications joining an environment, able to adapt to whatever 113 subsystems have been configured in the environment, should open the environment without 114 specifying any subsystem flags. Applications joining an environment, requiring specific 115 subsystems from their environments, should open the environment specifying those specific 116 subsystem flags. 117 </p> 118 <div class="itemizedlist"> 119 <ul type="disc"> 120 <li> 121 <p><a id="envopen_DB_INIT_CDB"></a> 122 <code class="literal">DB_INIT_CDB</code> 123 </p> 124 <p> 125 Initialize locking for the 126 <a href="../../programmer_reference/cam.html#cam_intro" class="olink">Berkeley DB Concurrent Data Store</a> 127 product. In this mode, 128 Berkeley DB provides multiple reader/single writer access. The only other subsystem 129 that should be specified with the <code class="literal">DB_INIT_CDB</code> flag is 130 <code class="literal">DB_INIT_MPOOL</code>. 131 </p> 132 </li> 133 <li> 134 <p><a id="envopen_DB_INIT_LOCK"></a> 135 <code class="literal">DB_INIT_LOCK</code> 136 </p> 137 <p> 138 Initialize the locking subsystem. This subsystem should be used when multiple 139 processes or threads are going to be reading and writing a Berkeley DB database, 140 so that they do not interfere with each other. If all threads are accessing the 141 database(s) read-only, locking is unnecessary. When the DB_INIT_LOCK flag is 142 specified, it is usually necessary to run a deadlock detector, as well. See 143 <a class="link" href="db_deadlock.html" title="db_deadlock">db_deadlock</a> and 144 <a class="xref" href="lockdetect.html" title="DB_ENV->lock_detect()">DB_ENV->lock_detect()</a> 145 for more information. 146 </p> 147 </li> 148 <li> 149 <p><a id="envopen_DB_INIT_LOG"></a> 150 <code class="literal">DB_INIT_LOG</code> 151 </p> 152 <p> 153 Initialize the logging subsystem. This subsystem should be used when recovery 154 from application or system failure is necessary. If the log region is being 155 created and log files are already present, the log files are reviewed; 156 subsequent log writes are appended to the end of the log, rather than 157 overwriting current log entries. 158 </p> 159 </li> 160 <li> 161 <p><a id="envopen_DB_INIT_MPOOL"></a> 162 <code class="literal">DB_INIT_MPOOL</code> 163 </p> 164 <p> 165 Initialize the shared memory buffer pool subsystem. This subsystem should be 166 used whenever an application is using any Berkeley DB access method. 167 </p> 168 </li> 169 <li> 170 <p><a id="open_DB_INIT_REP"></a> 171 <code class="literal">DB_INIT_REP</code> 172 </p> 173 <p> 174 Initialize the replication subsystem. This subsystem should be used whenever an 175 application plans on using replication. The <code class="literal">DB_INIT_REP</code> 176 flag requires the 177 <code class="literal">DB_INIT_TXN</code> and <code class="literal">DB_INIT_LOCK</code> 178 flags also be configured. 179 </p> 180 </li> 181 <li> 182 <p><a id="envopen_DB_INIT_TXN"></a> 183 <code class="literal">DB_INIT_TXN</code> 184 </p> 185 <p> 186 Initialize the transaction subsystem. This subsystem should be used when 187 recovery and atomicity of multiple operations are important. The 188 <code class="literal">DB_INIT_TXN</code> flag implies the 189 <code class="literal">DB_INIT_LOG</code> flag. 190 </p> 191 </li> 192 </ul> 193 </div> 194 <p> 195 The second group of flags govern what recovery, if any, is performed when the environment is 196 initialized: 197 </p> 198 <div class="itemizedlist"> 199 <ul type="disc"> 200 <li> 201 <p><a id="envopen_DB_RECOVER"></a> 202 <code class="literal">DB_RECOVER</code> 203 </p> 204 <p> 205 Run normal recovery on this environment before opening it for normal use. If 206 this flag is set, the <code class="literal">DB_CREATE</code> and 207 <code class="literal">DB_INIT_TXN</code> flags must also be set, because 208 the regions will be removed and re-created, and transactions are required for 209 application recovery. 210 </p> 211 </li> 212 <li> 213 <p><a id="envopen_DB_RECOVER_FATAL"></a> 214 <code class="literal">DB_RECOVER_FATAL</code> 215 </p> 216 <p> 217 Run catastrophic recovery on this environment before opening it for normal use. 218 If this flag is set, the <code class="literal">DB_CREATE</code> and 219 <code class="literal">DB_INIT_TXN</code> flags must also be set, 220 because the regions will be removed and re-created, and transactions are 221 required for application recovery. 222 </p> 223 </li> 224 </ul> 225 </div> 226 <p> 227 A standard part of the recovery process is to remove the existing Berkeley DB environment and 228 create a new one in which to perform recovery. If the thread of control performing recovery does 229 not specify the correct region initialization information (for example, the correct memory pool 230 cache size), the result can be an application running in an environment with incorrect cache and 231 other subsystem sizes. For this reason, the thread of control performing recovery should specify 232 correct configuration information before calling the <code class="methodname">DB_ENV->open()</code> method; or it should remove 233 the environment after recovery is completed, leaving creation of the correctly sized environment 234 to a subsequent call to the <code class="methodname">DB_ENV->open()</code> method. 235 </p> 236 <p> 237 All Berkeley DB recovery processing must be single-threaded; that is, only a single thread of 238 control may perform recovery or access a Berkeley DB environment while recovery is being 239 performed. Because it is not an error to specify <code class="literal">DB_RECOVER</code> for an 240 environment for which no recovery is required, it is reasonable programming practice for 241 the thread of control responsible for performing recovery and creating the environment to 242 always specify the <code class="literal">DB_CREATE</code> and <code class="literal">DB_RECOVER</code> flags 243 during startup. 244 </p> 245 <p> 246 The third group of flags govern file-naming extensions in the environment: 247 </p> 248 <div class="itemizedlist"> 249 <ul type="disc"> 250 <li> 251 <p><a id="envopen_DB_USE_ENVIRON"></a> 252 <code class="literal">DB_USE_ENVIRON</code> 253 </p> 254 <p> 255 The Berkeley DB process' environment may be permitted to specify information to 256 be used when naming files; see 257 <a href="../../programmer_reference/env_naming.html" class="olink">Berkeley DB File Naming</a>. 258 Because permitting users to specify which files are used can create security 259 problems, environment information will be used in file naming for all users 260 only if the <code class="literal">DB_USE_ENVIRON</code> flag is set. 261 </p> 262 </li> 263 <li> 264 <p><a id="envopen_DB_USE_ENVIRON_ROOT"></a> 265 <code class="literal">DB_USE_ENVIRON_ROOT</code> 266 </p> 267 <p> 268 The Berkeley DB process' environment may be permitted to specify information to 269 be used when naming files; see 270 <a href="../../programmer_reference/env_naming.html" class="olink">Berkeley DB File Naming</a>. 271 Because permitting users to specify which files are used can create security 272 problems, if the <code class="literal">DB_USE_ENVIRON_ROOT</code> flag is set, environment 273 information will be used in file naming only for users with appropriate 274 permissions (for example, users with a user-ID of 0 on <code class="literal">UNIX</code> 275 systems). 276 </p> 277 </li> 278 </ul> 279 </div> 280 <p> 281 Finally, there are a few additional unrelated flags: 282 </p> 283 <div class="itemizedlist"> 284 <ul type="disc"> 285 <li> 286 <p><a id="open_DB_CREATE"></a> 287 <code class="literal">DB_CREATE</code> 288 </p> 289 <p> 290 Cause Berkeley DB subsystems to create any underlying files, as necessary. 291 </p> 292 </li> 293 <li> 294 <p><a id="open_DB_LOCKDOWN"></a> 295 <code class="literal">DB_LOCKDOWN</code> 296 </p> 297 <p> 298 Lock shared Berkeley DB environment files and memory-mapped databases into 299 memory. 300 </p> 301 </li> 302 <li> 303 <p><a id="envopen_DB_FAILCHK"></a> 304 <code class="literal">DB_FAILCHK</code> 305 </p> 306 <p> 307 Internally call the <a class="xref" href="envfailchk.html" title="DB_ENV->failchk()">DB_ENV->failchk()</a> 308 method as part of opening the environment. When <code class="literal">DB_FAILCHK</code> is 309 specified, a check is made to ensure all <code class="methodname">DB_ENV->failchk()</code> 310 prerequisites are meet. 311 </p> 312 <p> 313 If the <code class="literal">DB_FAILCHK</code> flag is used in conjunction with the 314 <code class="literal">DB_REGISTER</code> flag, then a check will be made to see if 315 the environment needs recovery. If recovery is needed, a call 316 will be made to the <code class="methodname">DB_ENV->failchk()</code> method 317 to release any database reads locks held by the thread of control that 318 exited and, if needed, to abort the unresolved transaction. If 319 <code class="methodname">DB_ENV->failchk()</code> determines environment recovery 320 is still 321 required, the recovery actions for <code class="literal">DB_REGISTER</code> will be 322 followed. 323 </p> 324 <p> 325 If the <code class="literal">DB_FAILCHK</code> flag is not used in conjunction with the 326 <code class="literal">DB_REGISTER</code> flag, then make an internal call to 327 <code class="methodname">DB_ENV->failchk()</code> as the last step of opening the environment. 328 If <code class="methodname">DB_ENV->failchk()</code> determines database environment recovery is 329 required, <a href="../../programmer_reference/program_errorret.html#program_errorret.DB_RUNRECOVERY" class="olink">DB_RUNRECOVERY</a> 330 will be returned. 331 332 </p> 333 </li> 334 <li> 335 <p><a id="open_DB_PRIVATE"></a> 336 <code class="literal">DB_PRIVATE</code> 337 </p> 338 <p> 339 Allocate region memory from the heap instead of from memory backed by the 340 filesystem or system shared memory. 341 </p> 342 <p> 343 This flag implies the environment will only be accessed by a single process 344 (although that process may be multithreaded). This flag has two effects on the 345 Berkeley DB environment. First, all underlying data structures are allocated 346 from per-process memory instead of from shared memory that is accessible to more 347 than a single process. Second, mutexes are only configured to work between 348 threads. 349 </p> 350 <p> 351 This flag should not be specified if more than a single process is accessing the 352 environment because it is likely to cause database corruption and unpredictable 353 behavior. For example, if both a server application and Berkeley DB utilities 354 (for example, 355 <a class="link" href="db_archive.html" title="db_archive">db_archive</a>, 356 <a class="link" href="db_checkpoint.html" title="db_checkpoint">db_checkpoint</a> or 357 <a class="link" href="db_stat.html" title="db_stat">db_stat</a>) are expected to access the 358 environment, the <code class="literal">DB_PRIVATE</code> flag should not be specified. 359 </p> 360 <p> 361 See <a href="../../programmer_reference/env_region.html" class="olink">Shared Memory Regions</a> for more 362 information. 363 </p> 364 </li> 365 <li> 366 <p><a id="envopen_DB_REGISTER"></a> 367 <code class="literal">DB_REGISTER</code> 368 </p> 369 <p> 370 Check to see if recovery needs to be performed before opening the database 371 environment. (For this check to be accurate, all processes using the environment 372 must specify <code class="literal">DB_REGISTER</code> when opening the environment.) If 373 recovery needs to be performed for any reason (including the initial use of the 374 <code class="literal">DB_REGISTER</code> flag), and <code class="literal">DB_RECOVER</code> is also 375 specified, recovery will be performed and the open will 376 proceed normally. If recovery needs to be performed and 377 <code class="literal">DB_RECOVER</code> is not specified, 378 <a href="../../programmer_reference/program_errorret.html#program_errorret.DB_RUNRECOVERY" class="olink">DB_RUNRECOVERY</a> 379 will be returned. If recovery does not need to be performed, the 380 <code class="literal">DB_RECOVER</code> flag will be ignored. See 381 <a href="../../programmer_reference/transapp_app.html" class="olink">Architecting Transactional Data Store applications</a> for more information. 382 </p> 383 </li> 384 <li> 385 <p><a id="envopen_DB_SYSTEM_MEM"></a> 386 <code class="literal">DB_SYSTEM_MEM</code> 387 </p> 388 <p> 389 Allocate region memory from system shared memory instead of from heap memory or 390 memory backed by the filesystem. 391 </p> 392 <p> 393 See <a href="../../programmer_reference/env_region.html" class="olink">Shared Memory Regions</a> for more 394 information. 395 </p> 396 </li> 397 <li> 398 <p><a id="envopen_DB_THREAD"></a> 399 <code class="literal">DB_THREAD</code> 400 </p> 401 <p> 402 Cause the 403 <a class="link" href="env.html" title="Chapter��5.�� The DB_ENV Handle">DB_ENV</a> 404 handle returned by <code class="methodname">DB_ENV->open()</code> to be <span class="emphasis"><em>free-threaded;</em></span> that is, 405 concurrently usable by multiple threads in the address space. The 406 <code class="literal">DB_THREAD </code> flag 407 should be specified if the 408 <a class="link" href="env.html" title="Chapter��5.�� The DB_ENV Handle">DB_ENV</a> 409 handle will be concurrently used by more than 410 one thread in the process, or if any 411 <a class="link" href="db.html" title="Chapter��2.�� The DB Handle">DB</a> 412 handles opened in the scope of the 413 <a class="link" href="env.html" title="Chapter��5.�� The DB_ENV Handle">DB_ENV</a> 414 handle will be concurrently used by more than one thread in the process. 415 </p> 416 <p> 417 This flag is required when using the Replication Manager. 418 </p> 419 </li> 420 </ul> 421 </div> 422 </div> 423 <div class="sect3" lang="en" xml:lang="en"> 424 <div class="titlepage"> 425 <div> 426 <div> 427 <h4 class="title"><a id="id1665205"></a>mode</h4> 428 </div> 429 </div> 430 </div> 431 <p> 432 On Windows systems, the mode parameter is ignored. 433 </p> 434 <p> 435 On UNIX systems or in IEEE/ANSI Std 1003.1 (POSIX) environments, files 436 created by Berkeley DB are created with mode <span class="bold"><strong>mode</strong></span> (as described in <span class="bold"><strong>chmod</strong></span>(2)) and modified by the process' umask 437 value at the time of creation (see <span class="bold"><strong>umask</strong></span>(2)). Created files are owned by the 438 process owner; the group ownership of created files is based on the 439 system and directory defaults, and is not further specified by 440 Berkeley DB. System shared memory segments created by Berkeley DB are 441 created with mode <span class="bold"><strong>mode</strong></span>, unmodified by 442 the process' umask value. If <span class="bold"><strong>mode</strong></span> is 443 0, Berkeley DB will use a default mode of readable and writable by 444 both owner and group. 445 </p> 446 </div> 447 </div> 448 <div class="sect2" lang="en" xml:lang="en"> 449 <div class="titlepage"> 450 <div> 451 <div> 452 <h3 class="title"><a id="id1666062"></a>Errors</h3> 453 </div> 454 </div> 455 </div> 456 <p> 457 The <code class="methodname">DB_ENV->open()</code> <span> 458 <span> 459 method may fail and return one of the following non-zero errors: 460 </span> 461 462 </span> 463 </p> 464 <div class="sect3" lang="en" xml:lang="en"> 465 <div class="titlepage"> 466 <div> 467 <div> 468 <h4 class="title"><a id="id1665093"></a>DB_RUNRECOVERY</h4> 469 </div> 470 </div> 471 </div> 472 <p> 473 Either the <code class="literal">DB_REGISTER</code> flag was specified, a failure occurred, and 474 no recovery flag was specified, or the <code class="literal">DB_FAILCHK</code> flag was specified 475 and recovery was deemed necessary. 476 </p> 477 </div> 478 <div class="sect3" lang="en" xml:lang="en"> 479 <div class="titlepage"> 480 <div> 481 <div> 482 <h4 class="title"><a id="id1664997"></a>DB_VERSION_MISMATCH</h4> 483 </div> 484 </div> 485 </div> 486 <p> 487 The version of the Berkeley DB library doesn't match the version that 488 created the database environment. 489 </p> 490 </div> 491 <div class="sect3" lang="en" xml:lang="en"> 492 <div class="titlepage"> 493 <div> 494 <div> 495 <h4 class="title"><a id="id1665647"></a>EAGAIN</h4> 496 </div> 497 </div> 498 </div> 499 <p> 500 The shared memory region was locked and (repeatedly) unavailable. 501 </p> 502 </div> 503 <div class="sect3" lang="en" xml:lang="en"> 504 <div class="titlepage"> 505 <div> 506 <div> 507 <h4 class="title"><a id="id1665736"></a>EINVAL</h4> 508 </div> 509 </div> 510 </div> 511 <p> 512 If the <code class="literal">DB_THREAD</code> flag was specified and fast mutexes are not available 513 for this architecture; The <code class="literal">DB_HOME</code> or <code class="literal">TMPDIR</code> 514 environment variables were set, but empty; An incorrectly formatted <span class="bold"><strong>NAME VALUE</strong></span> entry or line was found; or if an 515 invalid flag value or parameter was specified. 516 </p> 517 </div> 518 <div class="sect3" lang="en" xml:lang="en"> 519 <div class="titlepage"> 520 <div> 521 <div> 522 <h4 class="title"><a id="id1665247"></a>ENOSPC</h4> 523 </div> 524 </div> 525 </div> 526 <p> 527 HP-UX only: Due to the constraints of the PA-RISC memory architecture, 528 HP-UX does not allow a process to map a file into its address space 529 multiple times. For this reason, each Berkeley DB environment may be 530 opened only once by a process on HP-UX; that is, calls to 531 <code class="methodname">DB_ENV->open()</code> will fail if the specified Berkeley DB environment has 532 been opened and not subsequently closed. 533 </p> 534 </div> 535 <div class="sect3" lang="en" xml:lang="en"> 536 <div class="titlepage"> 537 <div> 538 <div> 539 <h4 class="title"><a id="id1665181"></a>ENOENT</h4> 540 </div> 541 </div> 542 </div> 543 <p> 544 The file or directory does not exist. 545 </p> 546 </div> 547 </div> 548 <div class="sect2" lang="en" xml:lang="en"> 549 <div class="titlepage"> 550 <div> 551 <div> 552 <h3 class="title"><a id="id1665174"></a>Class</h3> 553 </div> 554 </div> 555 </div> 556 <p> 557 <a class="link" href="env.html" title="Chapter��5.�� The DB_ENV Handle">DB_ENV</a> 558 </p> 559 </div> 560 <div class="sect2" lang="en" xml:lang="en"> 561 <div class="titlepage"> 562 <div> 563 <div> 564 <h3 class="title"><a id="id1665030"></a>See Also</h3> 565 </div> 566 </div> 567 </div> 568 <p> 569 <a class="xref" href="env.html#envlist" title="Database Environments and Related Methods">Database Environments and Related Methods</a> 570 </p> 571 </div> 572 </div> 573 <div class="navfooter"> 574 <hr /> 575 <table width="100%" summary="Navigation footer"> 576 <tr> 577 <td width="40%" align="left"><a accesskey="p" href="envlsn_reset.html">Prev</a>��</td> 578 <td width="20%" align="center"> 579 <a accesskey="u" href="env.html">Up</a> 580 </td> 581 <td width="40%" align="right">��<a accesskey="n" href="envremove.html">Next</a></td> 582 </tr> 583 <tr> 584 <td width="40%" align="left" valign="top">DB_ENV->lsn_reset()��</td> 585 <td width="20%" align="center"> 586 <a accesskey="h" href="index.html">Home</a> 587 </td> 588 <td width="40%" align="right" valign="top">��DB_ENV->remove()</td> 589 </tr> 590 </table> 591 </div> 592 </body> 593</html> 594