1<!--$Id: db_close.so,v 10.55 2004/08/13 03:38:55 bostic Exp $--> 2<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 3<!--See the file LICENSE for redistribution information.--> 4<html> 5<head> 6<title>Berkeley DB: Db::close</title> 7<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> 8<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 9</head> 10<body bgcolor=white> 11<table width="100%"><tr valign=top> 12<td> 13<b>Db::close</b> 14</td> 15<td align=right> 16<a href="../api_cxx/api_core.html"><img src="../images/api.gif" alt="API"></a> 17<a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a></td> 18</tr></table> 19<hr size=1 noshade> 20<tt> 21<b><pre> 22#include <db_cxx.h> 23<p> 24int 25Db::close(u_int32_t flags); 26</pre></b> 27<hr size=1 noshade> 28<b>Description: Db::close</b> 29<p>The Db::close method flushes any cached database information to disk, 30closes any open cursors, frees any allocated resources, and closes any 31underlying files.</p> 32<p>The <a href="../api_cxx/db_class.html">Db</a> handle should not be closed while any other handle that 33refers to it is not yet closed; for example, database handles must not 34be closed while cursor handles into the database remain open, or 35transactions that include operations on the database have not yet been 36committed or aborted. Specifically, this includes <a href="../api_cxx/dbc_class.html">Dbc</a> and 37<a href="../api_cxx/txn_class.html">DbTxn</a> handles.</p> 38<p>Because key/data pairs are cached in memory, failing to sync the file 39with the Db::close or <a href="../api_cxx/db_sync.html">Db::sync</a> method may result in 40inconsistent or lost information.</p> 41<p>When called on a database that is the primary database for a secondary 42index, the primary database should be closed only after all secondary 43indices which reference it have been closed.</p> 44<p>When multiple threads are using the <a href="../api_cxx/db_class.html">Db</a> concurrently, only a single 45thread may call the Db::close method.</p> 46<p>The <a href="../api_cxx/db_class.html">Db</a> handle may not be accessed again after Db::close is 47called, regardless of its return.</p> 48<p>The Db::close method 49either returns a non-zero error value 50or throws an exception that encapsulates a non-zero error value on 51failure, and returns 0 on success. 52</p> 53<b>Parameters</b> <br> 54 <b>flags</b><ul compact><li>The <b>flags</b> parameter must be set to 0 or by bitwise inclusively <b>OR</b>'ing together one 55or more of the following values: 56<br> 57<b><a name="DB_NOSYNC">DB_NOSYNC</a></b><ul compact><li>Do not flush cached information to disk. The <a href="../api_cxx/db_close.html#DB_NOSYNC">DB_NOSYNC</a> flag is 58a dangerous option. It should be set only if the application is doing 59logging (with transactions) so that the database is recoverable after 60a system or application crash, or if the database is always generated 61from scratch after any system or application crash. 62<p><b>It is important to understand that flushing cached information to disk 63only minimizes the window of opportunity for corrupted data.</b> Although 64unlikely, it is possible for database corruption to happen if a system 65or application crash occurs while writing data to the database. To 66ensure that database corruption never occurs, applications must either: 67use transactions and logging with automatic recovery; use logging and 68application-specific recovery; or edit a copy of the database, and once 69all applications using the database have successfully called 70Db::close, atomically replace the original database with the 71updated copy.</p></ul> 72<br></ul> 73<br> 74<br><b>Errors</b> 75<p>The Db::close method 76may fail and throw 77<a href="../api_cxx/except_class.html">DbException</a>, 78encapsulating one of the following non-zero errors, or return one of 79the following non-zero errors:</p> 80<br> 81<b>EINVAL</b><ul compact><li>An 82invalid flag value or parameter was specified.</ul> 83<br> 84<hr size=1 noshade> 85<br><b>Class</b> 86<a href="../api_cxx/db_class.html">Db</a> 87<br><b>See Also</b> 88<a href="../api_cxx/db_list.html">Databases and Related Methods</a> 89</tt> 90<table width="100%"><tr><td><br></td><td align=right> 91<a href="../api_cxx/api_core.html"><img src="../images/api.gif" alt="API"></a><a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a> 92</td></tr></table> 93<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 94</body> 95</html> 96
