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>DbEnv::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 DbEnv Handle" /> 11 <link rel="prev" href="enverr.html" title="DbEnv::err()" /> 12 <link rel="next" href="envfileid_reset.html" title="DbEnv::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">DbEnv::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 DbEnv 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>DbEnv::failchk()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db_cxx.h> 39 40int 41DbEnv::failchk(u_int32_t flags);</pre> 42 <p> 43 The <code class="methodname">DbEnv::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">DbEnv::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="DbEnv::set_thread_id()">DbEnv::set_thread_id()</a> 58 and 59 <a class="xref" href="envset_isalive.html" title="DbEnv::set_isalive()">DbEnv::set_isalive()</a> 60 methods. Applications calling the <code class="methodname">DbEnv::failchk()</code> method must have 61 already called the <a class="xref" href="envset_isalive.html" title="DbEnv::set_isalive()">DbEnv::set_isalive()</a> 62 method, on the same <a class="link" href="env.html" title="Chapter 5. The DbEnv Handle">DbEnv</a>, and must have configured 63 their database environment using the 64 <a class="xref" href="envset_thread_count.html" title="DbEnv::set_thread_count()">DbEnv::set_thread_count()</a> 65 method. 66 </p> 67 <p> 68 If <code class="methodname">DbEnv::failchk()</code> determines a thread of control exited while 69 holding database read locks, it will release those locks. If 70 <code class="methodname">DbEnv::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">DbEnv::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">DbEnv::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="DbEnv::set_msgfile()">DbEnv::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="DbEnv::set_msgcall()">DbEnv::set_msgcall()</a> 84 method for more information). 85 </p> 86 <p> 87 If <code class="methodname">DbEnv::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 DbEnv Handle">DbEnv</a> handle 101 used to invoke the <code class="methodname">DbEnv::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">DbEnv::failchk()</code> method may not be called by the 106 application before the <a class="xref" href="envopen.html" title="DbEnv::open()">DbEnv::open()</a> 107 method is called. 108 </p> 109 <p> 110 The <code class="methodname">DbEnv::failchk()</code> <span> 111 112 <span> 113 method either returns a non-zero error value or throws an 114 exception that encapsulates a non-zero error value on 115 failure, and returns 0 on success. 116 </span> 117 </span> 118 </p> 119 <div class="sect2" lang="en" xml:lang="en"> 120 <div class="titlepage"> 121 <div> 122 <div> 123 <h3 class="title"><a id="id1664521"></a>Parameters</h3> 124 </div> 125 </div> 126 </div> 127 <div class="sect3" lang="en" xml:lang="en"> 128 <div class="titlepage"> 129 <div> 130 <div> 131 <h4 class="title"><a id="id1664711"></a>flags</h4> 132 </div> 133 </div> 134 </div> 135 <p> 136 The <span class="bold"><strong>flags</strong></span> parameter is currently 137 unused, and must be set to 0. 138 </p> 139 </div> 140 </div> 141 <div class="sect2" lang="en" xml:lang="en"> 142 <div class="titlepage"> 143 <div> 144 <div> 145 <h3 class="title"><a id="id1664866"></a>Errors</h3> 146 </div> 147 </div> 148 </div> 149 <p> 150 The <code class="methodname">DbEnv::failchk()</code> <span> 151 152 <span> 153 method may fail and throw a <a class="link" href="dbexception.html" title="Chapter 6. The DbException Class">DbException</a> 154 exception, encapsulating one of the following non-zero errors, or return one 155 of the following non-zero errors: 156 </span> 157 </span> 158 </p> 159 <div class="sect3" lang="en" xml:lang="en"> 160 <div class="titlepage"> 161 <div> 162 <div> 163 <h4 class="title"><a id="id1664694"></a>EINVAL</h4> 164 </div> 165 </div> 166 </div> 167 <p> 168 An invalid flag value or parameter was specified. 169 </p> 170 </div> 171 </div> 172 <div class="sect2" lang="en" xml:lang="en"> 173 <div class="titlepage"> 174 <div> 175 <div> 176 <h3 class="title"><a id="id1664798"></a>Class</h3> 177 </div> 178 </div> 179 </div> 180 <p> 181 <a class="link" href="env.html" title="Chapter 5. The DbEnv Handle">DbEnv</a> 182 </p> 183 </div> 184 <div class="sect2" lang="en" xml:lang="en"> 185 <div class="titlepage"> 186 <div> 187 <div> 188 <h3 class="title"><a id="id1664629"></a>See Also</h3> 189 </div> 190 </div> 191 </div> 192 <p> 193 <a class="xref" href="env.html#envlist" title="Database Environments and Related Methods">Database Environments and Related Methods</a> 194 </p> 195 </div> 196 </div> 197 <div class="navfooter"> 198 <hr /> 199 <table width="100%" summary="Navigation footer"> 200 <tr> 201 <td width="40%" align="left"><a accesskey="p" href="enverr.html">Prev</a> </td> 202 <td width="20%" align="center"> 203 <a accesskey="u" href="env.html">Up</a> 204 </td> 205 <td width="40%" align="right"> <a accesskey="n" href="envfileid_reset.html">Next</a></td> 206 </tr> 207 <tr> 208 <td width="40%" align="left" valign="top">DbEnv::err() </td> 209 <td width="20%" align="center"> 210 <a accesskey="h" href="index.html">Home</a> 211 </td> 212 <td width="40%" align="right" valign="top"> DbEnv::fileid_reset()</td> 213 </tr> 214 </table> 215 </div> 216 </body> 217</html> 218