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->failchk()</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="enverr.html" title="DB_ENV->err()" /> 12 <link rel="next" href="envfileid_reset.html" title="DB_ENV->fileid_reset()" /> 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->failchk()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="enverr.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="envfileid_reset.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="envfailchk"></a>DB_ENV->failchk()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db.h> 39 40int 41DB_ENV->failchk(DB_ENV *dbenv, u_int32_t flags); </pre> 42 <p> 43 The <code class="methodname">DB_ENV->failchk()</code> method checks for threads of control (either a 44 true thread or a process) that have exited while manipulating Berkeley 45 DB library data structures, while holding a logical database lock, or 46 with an unresolved transaction (that is, a transaction that was never 47 aborted or committed). For more information, see 48 <a href="../../programmer_reference/cam_app.html" class="olink">Architecting Data Store and 49 Concurrent Data Store applications</a>, and 50 <a href="../../programmer_reference/transapp_app.html" class="olink">Architecting Transactional 51 Data Store applications</a>, both in the 52 <em class="citetitle">Berkeley DB Programmer's Reference Guide</em>. 53 </p> 54 <p> 55 The <code class="methodname">DB_ENV->failchk()</code> method is based on the <code class="literal">thread_id</code> and 56 <code class="literal">is_alive</code> functions specified to the 57 <a class="xref" href="envset_thread_id.html" title="DB_ENV->set_thread_id()">DB_ENV->set_thread_id()</a> 58 and 59 <a class="xref" href="envset_isalive.html" title="DB_ENV->set_isalive()">DB_ENV->set_isalive()</a> 60 methods. Applications calling the <code class="methodname">DB_ENV->failchk()</code> method must have 61 already called the <a class="xref" href="envset_isalive.html" title="DB_ENV->set_isalive()">DB_ENV->set_isalive()</a> 62 method, on the same <a class="link" href="env.html" title="Chapter��5.�� The DB_ENV Handle">DB_ENV</a>, and must have configured 63 their database environment using the 64 <a class="xref" href="envset_thread_count.html" title="DB_ENV->set_thread_count()">DB_ENV->set_thread_count()</a> 65 method. 66 </p> 67 <p> 68 If <code class="methodname">DB_ENV->failchk()</code> determines a thread of control exited while 69 holding database read locks, it will release those locks. If 70 <code class="methodname">DB_ENV->failchk()</code> determines a thread of control exited with an 71 unresolved transaction, the transaction will be aborted. In either of 72 these cases, <code class="methodname">DB_ENV->failchk()</code> will return 0 and the application may 73 continue to use the database environment. 74 </p> 75 <p> 76 In either of these cases, the <code class="methodname">DB_ENV->failchk()</code> method will also 77 report the process and thread IDs associated with any released locks 78 or aborted transactions. The information is printed to a specified 79 output channel (see the 80 <a class="xref" href="envset_msgfile.html" title="DB_ENV->set_msgfile()">DB_ENV->set_msgfile()</a> 81 method for more information), or passed to an application callback 82 function (see the 83 <a class="xref" href="envset_msgcall.html" title="DB_ENV->set_msgcall()">DB_ENV->set_msgcall()</a> 84 method for more information). 85 </p> 86 <p> 87 If <code class="methodname">DB_ENV->failchk()</code> determines a thread of control has exited such 88 that database environment recovery is required, it will return 89 <a href="../../programmer_reference/program_errorret.html#program_errorret.DB_RUNRECOVERY" class="olink">DB_RUNRECOVERY</a>. 90 In this case, the application should not continue to use the database 91 environment. For a further description as to the actions the 92 application should take when this failure occurs, see 93 <a href="../../programmer_reference/cam_fail.html" class="olink">Handling failure in Data Store and 94 Concurrent Data Store applications</a>, and 95 <a href="../../programmer_reference/transapp_fail.html" class="olink">Handling failure in Transactional Data 96 Store applications</a>, both in the 97 <em class="citetitle">Berkeley DB Programmer's Reference Guide</em>. 98 </p> 99 <p> 100 In multiprocess applications, it is recommended that the <a class="link" href="env.html" title="Chapter��5.�� The DB_ENV Handle">DB_ENV</a> handle 101 used to invoke the <code class="methodname">DB_ENV->failchk()</code> method not be shared and therefore 102 not <span class="emphasis"><em>free-threaded</em></span>. 103 </p> 104 <p> 105 The <code class="methodname">DB_ENV->failchk()</code> method may not be called by the 106 application before the <a class="xref" href="envopen.html" title="DB_ENV->open()">DB_ENV->open()</a> 107 method is called. 108 </p> 109 <p> 110 The <code class="methodname">DB_ENV->failchk()</code> <span> 111 <span> 112 method returns a non-zero error value on failure and 0 on success. 113 </span> 114 115 </span> 116 </p> 117 <div class="sect2" lang="en" xml:lang="en"> 118 <div class="titlepage"> 119 <div> 120 <div> 121 <h3 class="title"><a id="id1662424"></a>Parameters</h3> 122 </div> 123 </div> 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="id1662461"></a>flags</h4> 130 </div> 131 </div> 132 </div> 133 <p> 134 The <span class="bold"><strong>flags</strong></span> parameter is currently 135 unused, and must be set to 0. 136 </p> 137 </div> 138 </div> 139 <div class="sect2" lang="en" xml:lang="en"> 140 <div class="titlepage"> 141 <div> 142 <div> 143 <h3 class="title"><a id="id1662610"></a>Errors</h3> 144 </div> 145 </div> 146 </div> 147 <p> 148 The <code class="methodname">DB_ENV->failchk()</code> <span> 149 <span> 150 method may fail and return one of the following non-zero errors: 151 </span> 152 153 </span> 154 </p> 155 <div class="sect3" lang="en" xml:lang="en"> 156 <div class="titlepage"> 157 <div> 158 <div> 159 <h4 class="title"><a id="id1662362"></a>EINVAL</h4> 160 </div> 161 </div> 162 </div> 163 <p> 164 An invalid flag value or parameter was specified. 165 </p> 166 </div> 167 </div> 168 <div class="sect2" lang="en" xml:lang="en"> 169 <div class="titlepage"> 170 <div> 171 <div> 172 <h3 class="title"><a id="id1662559"></a>Class</h3> 173 </div> 174 </div> 175 </div> 176 <p> 177 <a class="link" href="env.html" title="Chapter��5.�� The DB_ENV Handle">DB_ENV</a> 178 </p> 179 </div> 180 <div class="sect2" lang="en" xml:lang="en"> 181 <div class="titlepage"> 182 <div> 183 <div> 184 <h3 class="title"><a id="id1662519"></a>See Also</h3> 185 </div> 186 </div> 187 </div> 188 <p> 189 <a class="xref" href="env.html#envlist" title="Database Environments and Related Methods">Database Environments and Related Methods</a> 190 </p> 191 </div> 192 </div> 193 <div class="navfooter"> 194 <hr /> 195 <table width="100%" summary="Navigation footer"> 196 <tr> 197 <td width="40%" align="left"><a accesskey="p" href="enverr.html">Prev</a>��</td> 198 <td width="20%" align="center"> 199 <a accesskey="u" href="env.html">Up</a> 200 </td> 201 <td width="40%" align="right">��<a accesskey="n" href="envfileid_reset.html">Next</a></td> 202 </tr> 203 <tr> 204 <td width="40%" align="left" valign="top">DB_ENV->err()��</td> 205 <td width="20%" align="center"> 206 <a accesskey="h" href="index.html">Home</a> 207 </td> 208 <td width="40%" align="right" valign="top">��DB_ENV->fileid_reset()</td> 209 </tr> 210 </table> 211 </div> 212 </body> 213</html> 214