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::remove()</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="envopen.html" title="DbEnv::open()" /> 12 <link rel="next" href="envset_alloc.html" title="DbEnv::set_alloc()" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">DbEnv::remove()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="envopen.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="envset_alloc.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="envremove"></a>DbEnv::remove()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db_cxx.h> 39 40int 41DbEnv::remove(const char *db_home, u_int32_t flags);</pre> 42 <p> 43 The <code class="methodname">DbEnv::remove()</code> method destroys a Berkeley DB environment if it 44 is not currently in use. The environment regions, including any 45 backing files, are removed. Any log or database files and the 46 environment directory are not removed. 47 </p> 48 <p> 49 If there are processes that have called 50 <a class="xref" href="envopen.html" title="DbEnv::open()">DbEnv::open()</a> without calling 51 <a class="xref" href="envclose.html" title="DbEnv::close()">DbEnv::close()</a> (that 52 is, there are processes currently using the environment), 53 <code class="methodname">DbEnv::remove()</code> will fail without further action unless the 54 <a class="link" href="envremove.html#envremove_DB_FORCE">DB_FORCE</a> flag is set, 55 in which case <code class="methodname">DbEnv::remove()</code> will attempt to remove the 56 environment, regardless of any processes still using it. 57 </p> 58 <p> 59 The result of attempting to forcibly destroy the environment when it 60 is in use is unspecified. Processes using an environment often 61 maintain open file descriptors for shared regions within it. On UNIX 62 systems, the environment removal will usually succeed, and processes 63 that have already joined the region will continue to run in that 64 region without change. However, processes attempting to join the 65 environment will either fail or create new regions. On other systems 66 in which the <span class="bold"><strong>unlink</strong></span>(2) system call 67 will fail if any process has an open file descriptor for the file (for 68 example Windows/NT), the region removal will fail. 69 </p> 70 <p> 71 Calling <code class="methodname">DbEnv::remove()</code> should not be necessary for most 72 applications because the Berkeley DB environment is cleaned up as part 73 of normal database recovery procedures. However, applications may want 74 to call <code class="methodname">DbEnv::remove()</code> as part of application shut down to free up 75 system resources. For example, if the 76 <a class="link" href="envopen.html#envopen_DB_SYSTEM_MEM">DB_SYSTEM_MEM</a> flag 77 was specified to <a class="xref" href="envopen.html" title="DbEnv::open()">DbEnv::open()</a>, 78 it may be useful to call <code class="methodname">DbEnv::remove()</code> in order to release system shared memory 79 segments that have been allocated. Or, on architectures in which 80 mutexes require allocation of underlying system resources, it may be 81 useful to call <code class="methodname">DbEnv::remove()</code> in order to release those resources. 82 Alternatively, if recovery is not required because no database state 83 is maintained across failures, and no system resources need to be 84 released, it is possible to clean up an environment by simply removing 85 all the Berkeley DB files in the database environment's directories. 86 </p> 87 <p> 88 In multithreaded applications, only a single thread may call the 89 <code class="methodname">DbEnv::remove()</code> method. 90 </p> 91 <p> 92 A <a class="link" href="env.html" title="Chapter 5. The DbEnv Handle">DbEnv</a> handle that has 93 already been used to open an environment should not be used to call 94 the <code class="methodname">DbEnv::remove()</code> method; a new <a class="link" href="env.html" title="Chapter 5. The DbEnv Handle">DbEnv</a> 95 handle should be created for that purpose. 96 </p> 97 <p> 98 After <code class="methodname">DbEnv::remove()</code> has been called, regardless of its return, the 99 Berkeley DB environment handle may not be accessed again. 100 </p> 101 <p> 102 The <code class="methodname">DbEnv::remove()</code> <span> 103 104 <span> 105 method either returns a non-zero error value or throws an 106 exception that encapsulates a non-zero error value on 107 failure, and returns 0 on success. 108 </span> 109 </span> 110 </p> 111 <div class="sect2" lang="en" xml:lang="en"> 112 <div class="titlepage"> 113 <div> 114 <div> 115 <h3 class="title"><a id="id1668663"></a>Parameters</h3> 116 </div> 117 </div> 118 </div> 119 <div class="sect3" lang="en" xml:lang="en"> 120 <div class="titlepage"> 121 <div> 122 <div> 123 <h4 class="title"><a id="id1668671"></a>db_home</h4> 124 </div> 125 </div> 126 </div> 127 <p> 128 The <span class="bold"><strong>db_home</strong></span> parameter names the 129 database environment to be removed. 130 </p> 131 <p> 132 When using a Unicode build on Windows (the default), the <span class="bold"><strong>db_home</strong></span> argument will be interpreted as a UTF-8 133 string, which is equivalent to ASCII for Latin characters. 134 </p> 135 </div> 136 <div class="sect3" lang="en" xml:lang="en"> 137 <div class="titlepage"> 138 <div> 139 <div> 140 <h4 class="title"><a id="id1668767"></a>flags</h4> 141 </div> 142 </div> 143 </div> 144 <p> 145 The <span class="bold"><strong>flags</strong></span> parameter must be set to 0 or by 146 bitwise inclusively <span class="bold"><strong>OR</strong></span>'ing together one or more of the 147 following values: 148 </p> 149 <div class="itemizedlist"> 150 <ul type="disc"> 151 <li> 152 <p><a id="envremove_DB_FORCE"></a> 153 <code class="literal">DB_FORCE</code> 154 </p> 155 <p> 156 If set, the environment is removed, regardless of any 157 processes that may still using it, and no locks are acquired during this 158 process. (Generally, this flag is specified only when applications were 159 unable to shut down cleanly, and there is a risk that an application may have 160 died holding a Berkeley DB lock.) 161 </p> 162 </li> 163 <li> 164 <p><a id="envremove_DB_USE_ENVIRON"></a> 165 <code class="literal">DB_USE_ENVIRON</code> 166 </p> 167 <p> 168 The Berkeley DB process' environment may be permitted to specify information to 169 be used when naming files; see 170 <a href="../../programmer_reference/env_naming.html" class="olink">Berkeley DB File Naming</a>. 171 Because permitting users to specify which files are used can create security 172 problems, environment information will be used in file naming for all users 173 only if the <code class="literal">DB_USE_ENVIRON</code> flag is set. 174 </p> 175 </li> 176 <li> 177 <p><a id="envremove_DB_USE_ENVIRON_ROOT"></a> 178 <code class="literal">DB_USE_ENVIRON_ROOT</code> 179 </p> 180 <p> 181 The Berkeley DB process' environment may be permitted to specify information to 182 be used when naming files; see 183 <a href="../../programmer_reference/env_naming.html" class="olink">Berkeley DB File Naming</a>. 184 Because permitting users to specify which files are used can create security 185 problems, if the <code class="literal">DB_USE_ENVIRON_ROOT</code> flag is set, environment 186 information will be used in file naming only for users with appropriate 187 permissions (for example, users with a user-ID of 0 on <code class="literal">UNIX</code> 188 systems). 189 </p> 190 </li> 191 </ul> 192 </div> 193 </div> 194 </div> 195 <div class="sect2" lang="en" xml:lang="en"> 196 <div class="titlepage"> 197 <div> 198 <div> 199 <h3 class="title"><a id="id1668945"></a>Errors</h3> 200 </div> 201 </div> 202 </div> 203 <p> 204 The <code class="methodname">DbEnv::remove()</code> <span> 205 206 <span> 207 method may fail and throw a <a class="link" href="dbexception.html" title="Chapter 6. The DbException Class">DbException</a> 208 exception, encapsulating one of the following non-zero errors, or return one 209 of the following non-zero errors: 210 </span> 211 </span> 212 </p> 213 <div class="sect3" lang="en" xml:lang="en"> 214 <div class="titlepage"> 215 <div> 216 <div> 217 <h4 class="title"><a id="id1668675"></a>EBUSY</h4> 218 </div> 219 </div> 220 </div> 221 <p> 222 The shared memory region was in use and the force flag was not set. 223 </p> 224 </div> 225 </div> 226 <div class="sect2" lang="en" xml:lang="en"> 227 <div class="titlepage"> 228 <div> 229 <div> 230 <h3 class="title"><a id="id1668807"></a>Class</h3> 231 </div> 232 </div> 233 </div> 234 <p> 235 <a class="link" href="env.html" title="Chapter 5. The DbEnv Handle">DbEnv</a> 236 </p> 237 </div> 238 <div class="sect2" lang="en" xml:lang="en"> 239 <div class="titlepage"> 240 <div> 241 <div> 242 <h3 class="title"><a id="id1668709"></a>See Also</h3> 243 </div> 244 </div> 245 </div> 246 <p> 247 <a class="xref" href="env.html#envlist" title="Database Environments and Related Methods">Database Environments and Related Methods</a> 248 </p> 249 </div> 250 </div> 251 <div class="navfooter"> 252 <hr /> 253 <table width="100%" summary="Navigation footer"> 254 <tr> 255 <td width="40%" align="left"><a accesskey="p" href="envopen.html">Prev</a> </td> 256 <td width="20%" align="center"> 257 <a accesskey="u" href="env.html">Up</a> 258 </td> 259 <td width="40%" align="right"> <a accesskey="n" href="envset_alloc.html">Next</a></td> 260 </tr> 261 <tr> 262 <td width="40%" align="left" valign="top">DbEnv::open() </td> 263 <td width="20%" align="center"> 264 <a accesskey="h" href="index.html">Home</a> 265 </td> 266 <td width="40%" align="right" valign="top"> DbEnv::set_alloc()</td> 267 </tr> 268 </table> 269 </div> 270 </body> 271</html> 272