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_c/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.h> 23<p> 24int 25DB->close(DB *db, 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_c/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_c/dbc_class.html">DBC</a> and 37<a href="../api_c/txn_class.html">DB_TXN</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_c/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_c/db_class.html">DB</a> concurrently, only a single 45thread may call the DB->close method.</p> 46<p>The <a href="../api_c/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 49returns a non-zero error value on failure 50and 0 on success. 51</p> 52<b>Parameters</b> <br> 53 <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 54or more of the following values: 55<br> 56<b><a name="DB_NOSYNC">DB_NOSYNC</a></b><ul compact><li>Do not flush cached information to disk. The <a href="../api_c/db_close.html#DB_NOSYNC">DB_NOSYNC</a> flag is 57a dangerous option. It should be set only if the application is doing 58logging (with transactions) so that the database is recoverable after 59a system or application crash, or if the database is always generated 60from scratch after any system or application crash. 61<p><b>It is important to understand that flushing cached information to disk 62only minimizes the window of opportunity for corrupted data.</b> Although 63unlikely, it is possible for database corruption to happen if a system 64or application crash occurs while writing data to the database. To 65ensure that database corruption never occurs, applications must either: 66use transactions and logging with automatic recovery; use logging and 67application-specific recovery; or edit a copy of the database, and once 68all applications using the database have successfully called 69DB->close, atomically replace the original database with the 70updated copy.</p></ul> 71<br></ul> 72<br> 73<br><b>Errors</b> 74<p>The DB->close method 75may fail and return one of the following non-zero errors:</p> 76<br> 77<b>EINVAL</b><ul compact><li>An 78invalid flag value or parameter was specified.</ul> 79<br> 80<hr size=1 noshade> 81<br><b>Class</b> 82<a href="../api_c/db_class.html">DB</a> 83<br><b>See Also</b> 84<a href="../api_c/db_list.html">Databases and Related Methods</a> 85</tt> 86<table width="100%"><tr><td><br></td><td align=right> 87<a href="../api_c/api_core.html"><img src="../images/api.gif" alt="API"></a><a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a> 88</td></tr></table> 89<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 90</body> 91</html> 92
