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->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="db.html" title="Chapter��2.�� The DB Handle" /> 11 <link rel="prev" href="dbkey_range.html" title="DB->key_range()" /> 12 <link rel="next" href="dbput.html" title="DB->put()" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">DB->open()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="dbkey_range.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��2.�� 23 The DB Handle 24 </th> 25 <td width="20%" align="right">��<a accesskey="n" href="dbput.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="dbopen"></a>DB->open()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db.h> 39 40int 41DB->open(DB *db, DB_TXN *txnid, const char *file, 42 const char *database, DBTYPE type, u_int32_t flags, int mode); </pre> 43 <p> 44 The <code class="methodname">DB->open()</code> method opens the database represented by the 45 <span class="bold"><strong>file</strong></span> and <span class="bold"><strong>database</strong></span>. 46 </p> 47 <p> 48 The currently supported Berkeley DB file formats (or <span class="emphasis"><em>access 49 methods</em></span>) are Btree, Hash, Queue, and Recno. The Btree 50 format is a representation of a sorted, balanced tree structure. The 51 Hash format is an extensible, dynamic hashing scheme. The Queue 52 format supports fast access to fixed-length records accessed 53 sequentially or by logical record number. The Recno format supports 54 fixed- or variable-length records, accessed sequentially or by logical 55 record number, and optionally backed by a flat text file. 56 </p> 57 <p> 58 Storage and retrieval for the Berkeley DB access methods are based on 59 key/data pairs; see <a class="link" href="dbt.html" title="Chapter��4.�� The DBT Handle">DBT</a> 60 for more information. 61 </p> 62 <p> 63 Calling <code class="methodname">DB->open()</code> is a relatively expensive operation, and 64 maintaining a set of open databases will normally be preferable to 65 repeatedly opening and closing the database for each new query. 66 </p> 67 <p> 68 The <code class="methodname">DB->open()</code> <span> 69 <span> 70 method returns a non-zero error value on failure and 0 on success. 71 </span> 72 73 </span> 74 If <code class="methodname">DB->open()</code> fails, the 75 <a class="xref" href="dbclose.html" title="DB->close()">DB->close()</a> method must be 76 called to discard the <a class="link" href="db.html" title="Chapter��2.�� The DB Handle">DB</a> 77 handle. 78 </p> 79 <div class="sect2" lang="en" xml:lang="en"> 80 <div class="titlepage"> 81 <div> 82 <div> 83 <h3 class="title"><a id="id1639702"></a>Parameters</h3> 84 </div> 85 </div> 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="id1639737"></a>database</h4> 92 </div> 93 </div> 94 </div> 95 <p> 96 The <span class="bold"><strong>database</strong></span> parameter is optional, 97 and allows applications to have multiple databases in a single file. 98 Although no <span class="bold"><strong>database</strong></span> parameter needs 99 to be specified, it is an error to attempt to open a second database 100 in a <span class="bold"><strong>file</strong></span> that was not initially 101 created using a <span class="bold"><strong>database</strong></span> name. 102 Further, the <span class="bold"><strong>database</strong></span> parameter is 103 not supported by the Queue format. Finally, when opening multiple 104 databases in the same physical file, it is important to consider 105 locking and memory cache issues; see 106 <a href="../../programmer_reference/am_opensub.html" class="olink">Opening multiple databases in a single file</a> 107 for more information. 108 </p> 109 <p> 110 If both the <span class="bold"><strong>database</strong></span> and 111 <span class="bold"><strong>file</strong></span> parameters are NULL, 112 the database is strictly temporary and cannot be opened 113 by any other thread of control. Thus the database can only be accessed 114 by sharing the single database handle that created it, in 115 circumstances where doing so is safe. 116 </p> 117 <p> 118 If the <span class="bold"><strong>database</strong></span> parameter is not 119 set to NULL, the database can be opened by other threads of control 120 and will be replicated to client sites in any replication group, regardless 121 of whether the <span class="bold"><strong>file</strong></span> parameter is set to 122 NULL. 123 </p> 124 </div> 125 <div class="sect3" lang="en" xml:lang="en"> 126 <div class="titlepage"> 127 <div> 128 <div> 129 <h4 class="title"><a id="id1639952"></a>file</h4> 130 </div> 131 </div> 132 </div> 133 <p> 134 The <span class="bold"><strong>file</strong></span> parameter is used as the 135 name of an underlying file that will be used to back the database; see 136 <a href="../../programmer_reference/env_naming.html" class="olink">File naming</a> for more 137 information. 138 </p> 139 <p> 140 In-memory databases never intended to be preserved on disk may be 141 created by setting the <span class="bold"><strong>file</strong></span> parameter 142 to NULL. Whether other threads of control can access this database is 143 driven entirely by whether the <span class="bold"><strong>database</strong></span> 144 parameter is set to NULL. 145 </p> 146 <p> 147 When using a Unicode build on Windows (the default), the <span class="bold"><strong>file</strong></span> argument will be interpreted as a UTF-8 148 string, which is equivalent to ASCII for Latin characters. 149 </p> 150 </div> 151 <div class="sect3" lang="en" xml:lang="en"> 152 <div class="titlepage"> 153 <div> 154 <div> 155 <h4 class="title"><a id="id1639713"></a>flags</h4> 156 </div> 157 </div> 158 </div> 159 <p> 160 The <span class="bold"><strong>flags</strong></span> parameter must be set to zero or 161 by bitwise inclusively <span class="bold"><strong>OR</strong></span>'ing together one 162 or more of the following values: 163 </p> 164 <div class="itemizedlist"> 165 <ul type="disc"> 166 <li> 167 <p><a id="open_DB_AUTO_COMMIT"></a> 168 <code class="literal">DB_AUTO_COMMIT</code> 169 </p> 170 <p> 171 Enclose the <code class="methodname">DB->open()</code> call within a transaction. If the call 172 succeeds, the open operation will be recoverable and all 173 subsequent database modification operations based on this 174 handle will be transactionally protected. If the call fails, 175 no database will have been created. 176 </p> 177 </li> 178 <li> 179 <p><a id="open_DB_CREATE"></a> 180 <code class="literal">DB_CREATE</code> 181 </p> 182 <p> 183 Create the database. If the database does not already exist 184 and the <code class="literal">DB_CREATE</code> flag is not specified, the 185 <code class="methodname">DB->open()</code> will fail. 186 </p> 187 </li> 188 <li> 189 <p><a id="open_DB_EXCL"></a> 190 <code class="literal">DB_EXCL</code> 191 </p> 192 <p> 193 Return an error if the database already exists. The 194 <code class="literal">DB_EXCL</code> flag is only meaningful 195 when specified with the <code class="literal">DB_CREATE</code>. 196 flag. 197 </p> 198 </li> 199 <li> 200 <p><a id="dbopen_DB_MULTIVERSION"></a> 201 <code class="literal">DB_MULTIVERSION</code> 202 </p> 203 <p> 204 Open the database with support for 205 <a href="../../programmer_reference/transapp_read.html" class="olink">multiversion concurrency control</a>. 206 This will cause updates to the database to follow a 207 copy-on-write protocol, which is required to support 208 snapshot isolation. The <code class="literal">DB_MULTIVERSION</code> 209 flag requires that the database be transactionally protected during its open 210 and is not supported by the queue format. 211 </p> 212 </li> 213 <li> 214 <p><a id="open_DB_NOMMAP"></a> 215 <code class="literal">DB_NOMMAP</code> 216 </p> 217 <p> 218 Do not map this database into process memory (see the 219 <a class="xref" href="envset_mp_mmapsize.html" title="DB_ENV->set_mp_mmapsize()">DB_ENV->set_mp_mmapsize()</a> 220 method for further information). 221 </p> 222 </li> 223 <li> 224 <p><a id="dbopen_DB_RDONLY"></a> 225 <code class="literal">DB_RDONLY</code> 226 </p> 227 <p> 228 Open the database for reading only. Any attempt to modify 229 items in the database will fail, regardless of the actual 230 permissions of any underlying files. 231 </p> 232 </li> 233 <li> 234 <p><a id="dbopen_DB_READ_UNCOMMITTED"></a> 235 <code class="literal">DB_READ_UNCOMMITTED</code> 236 </p> 237 <p> 238 Support transactional read operations with degree 1 239 isolation. Read operations on the database may request the 240 return of modified but not yet committed data. This flag 241 must be specified on all 242 <a class="link" href="db.html" title="Chapter��2.�� The DB Handle">DB</a> 243 handles used to perform dirty 244 reads or database updates, otherwise requests for dirty 245 reads may not be honored and the read may block. 246 </p> 247 </li> 248 <li> 249 <p><a id="open_DB_THREAD"></a> 250 <code class="literal">DB_THREAD</code> 251 </p> 252 <p> 253 Cause the <a class="link" href="db.html" title="Chapter��2.�� The DB Handle">DB</a> 254 handle returned by <code class="methodname">DB->open()</code> to be <span class="emphasis"><em>free-threaded</em></span>; that is, 255 concurrently usable by multiple threads in the address 256 space. 257 </p> 258 </li> 259 <li> 260 <p><a id="open_DB_TRUNCATE"></a> 261 <code class="literal">DB_TRUNCATE</code> 262 </p> 263 <p> 264 Physically truncate the underlying file, discarding all 265 previous databases it might have held. Underlying filesystem 266 primitives are used to implement this flag. For this reason, 267 it is applicable only to the file and cannot be used to 268 discard databases within a file. 269 </p> 270 <p> 271 The <code class="literal">DB_TRUNCATE</code> flag cannot be lock or 272 transaction-protected, and it is an error to specify it in a 273 locking or transaction-protected environment. 274 </p> 275 </li> 276 </ul> 277 </div> 278 </div> 279 <div class="sect3" lang="en" xml:lang="en"> 280 <div class="titlepage"> 281 <div> 282 <div> 283 <h4 class="title"><a id="id1640280"></a>mode</h4> 284 </div> 285 </div> 286 </div> 287 <p> 288 On Windows systems, the mode parameter is ignored. 289 </p> 290 <p> 291 On UNIX systems or in IEEE/ANSI Std 1003.1 (POSIX) environments, files 292 created by the database open 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 293 value at the time of creation (see <span class="bold"><strong>umask</strong></span>(2)). Created files are owned by the 294 process owner; the group ownership of created files is based on the 295 system and directory defaults, and is not further specified by 296 Berkeley DB. System shared memory segments created by the database 297 open are created with mode <span class="bold"><strong>mode</strong></span>, 298 unmodified by the process' umask value. If <span class="bold"><strong>mode</strong></span> is 0, the database open will use a default 299 mode of readable and writable by both owner and group. 300 </p> 301 </div> 302 <div class="sect3" lang="en" xml:lang="en"> 303 <div class="titlepage"> 304 <div> 305 <div> 306 <h4 class="title"><a id="id1640355"></a>txnid</h4> 307 </div> 308 </div> 309 </div> 310 <p> 311 If the operation is part of an application-specified transaction, the 312 <span class="bold"><strong>txnid</strong></span> parameter is a transaction 313 handle returned from <a class="xref" href="txnbegin.html" title="DB_ENV->txn_begin()">DB_ENV->txn_begin()</a>; 314 if the operation is part of a Berkeley DB Concurrent Data Store group, the 315 <span class="bold"><strong>txnid</strong></span> parameter is a handle returned 316 from <a class="xref" href="envcdsgroup_begin.html" title="DB_ENV->cdsgroup_begin()">DB_ENV->cdsgroup_begin()</a>; 317 otherwise NULL. If no transaction handle is specified, but the 318 DB_AUTO_COMMIT flag is specified, the operation will be implicitly 319 transaction protected. Note that transactionally protected operations 320 on a <a class="link" href="db.html" title="Chapter��2.�� The DB Handle">DB</a> handle requires 321 the <a class="link" href="db.html" title="Chapter��2.�� The DB Handle">DB</a> handle itself be 322 transactionally protected during its open. Also note that the 323 transaction must be committed before the handle is closed; see <a href="../../programmer_reference/program_scope.html" class="olink">Berkeley DB handles</a> for more 324 information. 325 </p> 326 </div> 327 <div class="sect3" lang="en" xml:lang="en"> 328 <div class="titlepage"> 329 <div> 330 <div> 331 <h4 class="title"><a id="id1640243"></a>type</h4> 332 </div> 333 </div> 334 </div> 335 <p> 336 The <span class="bold"><strong>type</strong></span> parameter is of type DBTYPE, 337 and must be set to one of <code class="literal">DB_BTREE</code>, 338 <code class="literal">DB_HASH</code>, <code class="literal">DB_QUEUE</code>, 339 <code class="literal">DB_RECNO</code>, or <code class="literal">DB_UNKNOWN</code>. If <span class="bold"><strong>type</strong></span> is DB_UNKNOWN, the database must already 340 exist and <code class="methodname">DB->open()</code> will automatically determine its type. The 341 <a class="xref" href="dbget_type.html" title="DB->get_type()">DB->get_type()</a> method 342 may be used to determine the underlying type of databases opened using 343 DB_UNKNOWN. 344 </p> 345 <p> 346 It is an error to specify the incorrect <span class="bold"><strong>type</strong></span> 347 for a database that already exists. 348 </p> 349 </div> 350 </div> 351 <div class="sect2" lang="en" xml:lang="en"> 352 <div class="titlepage"> 353 <div> 354 <div> 355 <h3 class="title"><a id="id1640494"></a>Environment Variables</h3> 356 </div> 357 </div> 358 </div> 359 <p> 360 If the database was opened within a database environment, the 361 environment variable <span class="bold"><strong>DB_HOME</strong></span> may be used as the path of the 362 database environment home. 363 </p> 364 <p> 365 <code class="methodname">DB->open()</code> is affected by any database directory specified using the 366 <a class="xref" href="envset_data_dir.html" title="DB_ENV->set_data_dir()">DB_ENV->set_data_dir()</a> 367 method, or by setting the "set_data_dir" string in 368 the environment's 369 <a href="../../programmer_reference/env_db_config.html#env_db_config.DB_CONFIG" class="olink">DB_CONFIG</a> 370 file. 371 </p> 372 <div class="itemizedlist"> 373 <ul type="disc"> 374 <li> 375 <p> 376 <span class="bold"><strong>TMPDIR</strong></span> 377 </p> 378 <p> 379 If the <span class="bold"><strong>file</strong></span> 380 and <span class="bold"><strong>dbenv</strong></span> 381 parameters to <code class="methodname">DB->open()</code> are <code class="literal">NULL</code>, 382 the environment variable 383 <span class="bold"><strong>TMPDIR</strong></span> 384 may be used as a 385 directory in which to create temporary backing files 386 </p> 387 </li> 388 </ul> 389 </div> 390 </div> 391 <div class="sect2" lang="en" xml:lang="en"> 392 <div class="titlepage"> 393 <div> 394 <div> 395 <h3 class="title"><a id="id1640547"></a>Errors</h3> 396 </div> 397 </div> 398 </div> 399 <p> 400 The <code class="methodname">DB->open()</code> <span> 401 <span> 402 method may fail and return one of the following non-zero errors: 403 </span> 404 405 </span> 406 </p> 407 <div class="sect3" lang="en" xml:lang="en"> 408 <div class="titlepage"> 409 <div> 410 <div> 411 <h4 class="title"><a id="id1640178"></a>DB_LOCK_DEADLOCK</h4> 412 </div> 413 </div> 414 </div> 415 <p> 416 A transactional database environment operation was selected to resolve 417 a deadlock. 418 </p> 419 </div> 420 <div class="sect3" lang="en" xml:lang="en"> 421 <div class="titlepage"> 422 <div> 423 <div> 424 <h4 class="title"><a id="id1640657"></a>DB_LOCK_NOTGRANTED</h4> 425 </div> 426 </div> 427 </div> 428 <p> 429 A Berkeley DB Concurrent Data Store database environment configured 430 for lock timeouts was unable to grant a lock in the allowed time. 431 </p> 432 </div> 433 <div class="sect3" lang="en" xml:lang="en"> 434 <div class="titlepage"> 435 <div> 436 <div> 437 <h4 class="title"><a id="id1640651"></a>ENOENT</h4> 438 </div> 439 </div> 440 </div> 441 <p> 442 The file or directory does not exist. 443 </p> 444 </div> 445 <div class="sect3" lang="en" xml:lang="en"> 446 <div class="titlepage"> 447 <div> 448 <div> 449 <h4 class="title"><a id="id1640521"></a>ENOENT</h4> 450 </div> 451 </div> 452 </div> 453 <p> 454 A nonexistent <span class="bold"><strong>re_source</strong></span> file was specified. 455 </p> 456 </div> 457 <div class="sect3" lang="en" xml:lang="en"> 458 <div class="titlepage"> 459 <div> 460 <div> 461 <h4 class="title"><a id="id1640549"></a>DB_OLD_VERSION</h4> 462 </div> 463 </div> 464 </div> 465 <p> 466 The database cannot be opened without being first upgraded. 467 </p> 468 </div> 469 <div class="sect3" lang="en" xml:lang="en"> 470 <div class="titlepage"> 471 <div> 472 <div> 473 <h4 class="title"><a id="id1640555"></a>EEXIST</h4> 474 </div> 475 </div> 476 </div> 477 <p> 478 <code class="literal">DB_CREATE</code> and <code class="literal">DB_EXCL</code> 479 were specified and the database exists. 480 </p> 481 </div> 482 <div class="sect3" lang="en" xml:lang="en"> 483 <div class="titlepage"> 484 <div> 485 <div> 486 <h4 class="title"><a id="id1640602"></a>EINVAL</h4> 487 </div> 488 </div> 489 </div> 490 <p> 491 If an unknown database type, page size, hash function, pad byte, byte order, or a flag value 492 or parameter that is incompatible with the specified database was specified; the 493 <a class="link" href="envopen.html#envopen_DB_THREAD">DB_THREAD</a> 494 flag was specified and fast mutexes are not available for this architecture; the 495 <a class="link" href="envopen.html#envopen_DB_THREAD">DB_THREAD</a> 496 flag was specified to <code class="methodname">DB->open()</code>, but was 497 not specified to the <code class="methodname">DB_ENV->open()</code> call for the 498 environment in which the <a class="link" href="db.html" title="Chapter��2.�� The DB Handle">DB</a> 499 handle was created; a backing flat text file was specified with either the 500 <a class="link" href="envopen.html#envopen_DB_THREAD">DB_THREAD</a> 501 flag or the provided database environment supports transaction 502 processing; or if an invalid flag value or parameter was specified. 503 </p> 504 </div> 505 <div class="sect3" lang="en" xml:lang="en"> 506 <div class="titlepage"> 507 <div> 508 <div> 509 <h4 class="title"><a id="id1640610"></a> DB_REP_HANDLE_DEAD</h4> 510 </div> 511 </div> 512 </div> 513 <p> 514 When a client synchronizes with the master, it is possible for committed 515 transactions to be rolled back. This invalidates all the database and cursor 516 handles opened in the replication environment. Once this occurs, an attempt to use 517 such a handle will 518 519 return <code class="literal">DB_REP_HANDLE_DEAD</code>. 520 The application will need to discard the handle and open a new one in order to 521 continue processing. 522 </p> 523 </div> 524 <div class="sect3" lang="en" xml:lang="en"> 525 <div class="titlepage"> 526 <div> 527 <div> 528 <h4 class="title"><a id="id1640680"></a>DB_REP_LOCKOUT</h4> 529 </div> 530 </div> 531 </div> 532 <p> 533 The operation was blocked by client/master synchronization. 534 </p> 535 </div> 536 </div> 537 <div class="sect2" lang="en" xml:lang="en"> 538 <div class="titlepage"> 539 <div> 540 <div> 541 <h3 class="title"><a id="id1639733"></a>Class</h3> 542 </div> 543 </div> 544 </div> 545 <p> 546 <a class="link" href="db.html" title="Chapter��2.�� The DB Handle">DB</a> 547 </p> 548 </div> 549 <div class="sect2" lang="en" xml:lang="en"> 550 <div class="titlepage"> 551 <div> 552 <div> 553 <h3 class="title"><a id="id1639785"></a>See Also</h3> 554 </div> 555 </div> 556 </div> 557 <p> 558 <a class="xref" href="db.html#dblist" title="Database and Related Methods">Database and Related Methods</a> 559 </p> 560 </div> 561 </div> 562 <div class="navfooter"> 563 <hr /> 564 <table width="100%" summary="Navigation footer"> 565 <tr> 566 <td width="40%" align="left"><a accesskey="p" href="dbkey_range.html">Prev</a>��</td> 567 <td width="20%" align="center"> 568 <a accesskey="u" href="db.html">Up</a> 569 </td> 570 <td width="40%" align="right">��<a accesskey="n" href="dbput.html">Next</a></td> 571 </tr> 572 <tr> 573 <td width="40%" align="left" valign="top">DB->key_range()��</td> 574 <td width="20%" align="center"> 575 <a accesskey="h" href="index.html">Home</a> 576 </td> 577 <td width="40%" align="right" valign="top">��DB->put()</td> 578 </tr> 579 </table> 580 </div> 581 </body> 582</html> 583