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->close()</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="dbassociate_foreign.html" title="DB->associate_foreign()" /> 12 <link rel="next" href="dbcreate.html" title="db_create" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">DB->close()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="dbassociate_foreign.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="dbcreate.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="dbclose"></a>DB->close()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db.h> 39 40int 41DB->close(DB *db, u_int32_t flags); </pre> 42 <p> 43 The <code class="methodname">DB->close()</code> method flushes any cached database information to 44 disk, closes any open cursors, frees any allocated resources, and 45 closes any underlying files. 46 </p> 47 <p> 48 Although closing a database handle will close any open cursors, it 49 is recommended that applications explicitly close all their 50 <a class="link" href="dbc.html" title="Chapter��3.�� The DBcursor Handle">DBcursor</a> handles 51 before closing the database. The reason why is that when 52 the cursor is explicitly closed, the memory allocated for it is 53 reclaimed; however, this will <span class="emphasis"><em>not</em></span> happen if 54 you close a database while cursors are still opened. 55 </p> 56 <p> 57 The same rule, for the same reasons, hold true for 58 <a class="link" href="txn.html" title="Chapter��12.�� The DB_TXN Handle">DB_TXN</a> 59 handles. Simply make sure you close all your transaction handles 60 before closing your database handle. 61 </p> 62 <p> 63 Because key/data pairs are cached in memory, applications should 64 make a point to always either close database handles or sync their 65 data to disk (using the <a class="xref" href="dbsync.html" title="DB->sync()">DB->sync()</a> 66 method) before exiting, to ensure that any data cached in main memory are 67 reflected in the underlying file system. 68 </p> 69 <p> 70 When called on a database that is the primary database for a secondary 71 index, the primary database should be closed only after all secondary 72 indices referencing it have been closed. 73 </p> 74 <p> 75 When multiple threads are using the <a class="link" href="db.html" title="Chapter��2.�� The DB Handle">DB</a> 76 concurrently, only a single thread may call the <code class="methodname">DB->close()</code> method. 77 </p> 78 <p> 79 The <a class="link" href="db.html" title="Chapter��2.�� The DB Handle">DB</a> handle may not be 80 accessed again after <code class="methodname">DB->close()</code> is called, regardless of its return. 81 </p> 82 <p> 83 The <code class="methodname">DB->close()</code> <span> 84 <span> 85 method returns a non-zero error value on failure and 0 on success. 86 </span> 87 88 </span> 89 </p> 90 <div class="sect2" lang="en" xml:lang="en"> 91 <div class="titlepage"> 92 <div> 93 <div> 94 <h3 class="title"><a id="id1631977"></a>Parameters</h3> 95 </div> 96 </div> 97 </div> 98 <div class="sect3" lang="en" xml:lang="en"> 99 <div class="titlepage"> 100 <div> 101 <div> 102 <h4 class="title"><a id="id1632317"></a>flags</h4> 103 </div> 104 </div> 105 </div> 106 <p> 107 The <span class="bold"><strong>flags</strong></span> parameter must be set to 0 108 or be set to the following value: 109 </p> 110 <div class="itemizedlist"> 111 <ul type="disc"> 112 <li> 113 <p><a id="dbclose_DB_NOSYNC"></a> 114 <code class="literal">DB_NOSYNC</code> 115 </p> 116 <p> 117 Do not flush cached information to disk. This flag is a 118 dangerous option. It should be set only if the application is doing 119 logging (with transactions) so that the database is recoverable after 120 a system or application crash, or if the database is always generated 121 from scratch after any system or application crash. 122 </p> 123 <p> 124 <span class="bold"><strong>It is important to understand that flushing 125 cached information to disk only minimizes the window of opportunity 126 for corrupted data.</strong></span> Although unlikely, it is possible for 127 database corruption to happen if a system or application crash occurs 128 while writing data to the database. To ensure that database 129 corruption never occurs, applications must either: use transactions 130 and logging with automatic recovery; use logging and 131 application-specific recovery; or edit a copy of the database, and 132 once all applications using the database have successfully called 133 <code class="methodname">DB->close()</code>, atomically replace the original database with the 134 updated copy. 135 </p> 136 <p> 137 Note that this flag only works when the database 138 has been opened using an environment. 139 </p> 140 </li> 141 </ul> 142 </div> 143 </div> 144 </div> 145 <div class="sect2" lang="en" xml:lang="en"> 146 <div class="titlepage"> 147 <div> 148 <div> 149 <h3 class="title"><a id="id1632318"></a>Errors</h3> 150 </div> 151 </div> 152 </div> 153 <p> 154 The <code class="methodname">DB->close()</code> <span> 155 <span> 156 method may fail and return one of the following non-zero errors: 157 </span> 158 159 </span> 160 </p> 161 <div class="sect3" lang="en" xml:lang="en"> 162 <div class="titlepage"> 163 <div> 164 <div> 165 <h4 class="title"><a id="id1630003"></a>EINVAL</h4> 166 </div> 167 </div> 168 </div> 169 <p> 170 An invalid flag value or parameter was specified. 171 </p> 172 </div> 173 </div> 174 <div class="sect2" lang="en" xml:lang="en"> 175 <div class="titlepage"> 176 <div> 177 <div> 178 <h3 class="title"><a id="id1631853"></a>Class</h3> 179 </div> 180 </div> 181 </div> 182 <p> 183 <a class="link" href="db.html" title="Chapter��2.�� The DB Handle">DB</a> 184 </p> 185 </div> 186 <div class="sect2" lang="en" xml:lang="en"> 187 <div class="titlepage"> 188 <div> 189 <div> 190 <h3 class="title"><a id="id1632104"></a>See Also</h3> 191 </div> 192 </div> 193 </div> 194 <p> 195 <a class="xref" href="db.html#dblist" title="Database and Related Methods">Database and Related Methods</a> 196 </p> 197 </div> 198 </div> 199 <div class="navfooter"> 200 <hr /> 201 <table width="100%" summary="Navigation footer"> 202 <tr> 203 <td width="40%" align="left"><a accesskey="p" href="dbassociate_foreign.html">Prev</a>��</td> 204 <td width="20%" align="center"> 205 <a accesskey="u" href="db.html">Up</a> 206 </td> 207 <td width="40%" align="right">��<a accesskey="n" href="dbcreate.html">Next</a></td> 208 </tr> 209 <tr> 210 <td width="40%" align="left" valign="top">DB->associate_foreign()��</td> 211 <td width="20%" align="center"> 212 <a accesskey="h" href="index.html">Home</a> 213 </td> 214 <td width="40%" align="right" valign="top">��db_create</td> 215 </tr> 216 </table> 217 </div> 218 </body> 219</html> 220