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->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 DB_ENV Handle" /> 11 <link rel="prev" href="envopen.html" title="DB_ENV->open()" /> 12 <link rel="next" href="envset_alloc.html" title="DB_ENV->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">DB_ENV->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 DB_ENV 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>DB_ENV->remove()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db.h> 39 40int 41DB_ENV->remove(DB_ENV *dbenv, char *db_home, u_int32_t flags); </pre> 42 <p> 43 The <code class="methodname">DB_ENV->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="DB_ENV->open()">DB_ENV->open()</a> without calling 51 <a class="xref" href="envclose.html" title="DB_ENV->close()">DB_ENV->close()</a> (that 52 is, there are processes currently using the environment), 53 <code class="methodname">DB_ENV->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">DB_ENV->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">DB_ENV->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">DB_ENV->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="DB_ENV->open()">DB_ENV->open()</a>, 78 it may be useful to call <code class="methodname">DB_ENV->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">DB_ENV->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">DB_ENV->remove()</code> method. 90 </p> 91 <p> 92 A <a class="link" href="env.html" title="Chapter��5.�� The DB_ENV Handle">DB_ENV</a> handle that has 93 already been used to open an environment should not be used to call 94 the <code class="methodname">DB_ENV->remove()</code> method; a new <a class="link" href="env.html" title="Chapter��5.�� The DB_ENV Handle">DB_ENV</a> 95 handle should be created for that purpose. 96 </p> 97 <p> 98 After <code class="methodname">DB_ENV->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">DB_ENV->remove()</code> <span> 103 <span> 104 method returns a non-zero error value on failure and 0 on success. 105 </span> 106 107 </span> 108 </p> 109 <div class="sect2" lang="en" xml:lang="en"> 110 <div class="titlepage"> 111 <div> 112 <div> 113 <h3 class="title"><a id="id1666271"></a>Parameters</h3> 114 </div> 115 </div> 116 </div> 117 <div class="sect3" lang="en" xml:lang="en"> 118 <div class="titlepage"> 119 <div> 120 <div> 121 <h4 class="title"><a id="id1666365"></a>db_home</h4> 122 </div> 123 </div> 124 </div> 125 <p> 126 The <span class="bold"><strong>db_home</strong></span> parameter names the 127 database environment to be removed. 128 </p> 129 <p> 130 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 131 string, which is equivalent to ASCII for Latin characters. 132 </p> 133 </div> 134 <div class="sect3" lang="en" xml:lang="en"> 135 <div class="titlepage"> 136 <div> 137 <div> 138 <h4 class="title"><a id="id1666466"></a>flags</h4> 139 </div> 140 </div> 141 </div> 142 <p> 143 The <span class="bold"><strong>flags</strong></span> parameter must be set to 0 or by 144 bitwise inclusively <span class="bold"><strong>OR</strong></span>'ing together one or more of the 145 following values: 146 </p> 147 <div class="itemizedlist"> 148 <ul type="disc"> 149 <li> 150 <p><a id="envremove_DB_FORCE"></a> 151 <code class="literal">DB_FORCE</code> 152 </p> 153 <p> 154 If set, the environment is removed, regardless of any 155 processes that may still using it, and no locks are acquired during this 156 process. (Generally, this flag is specified only when applications were 157 unable to shut down cleanly, and there is a risk that an application may have 158 died holding a Berkeley DB lock.) 159 </p> 160 </li> 161 <li> 162 <p><a id="envremove_DB_USE_ENVIRON"></a> 163 <code class="literal">DB_USE_ENVIRON</code> 164 </p> 165 <p> 166 The Berkeley DB process' environment may be permitted to specify information to 167 be used when naming files; see 168 <a href="../../programmer_reference/env_naming.html" class="olink">Berkeley DB File Naming</a>. 169 Because permitting users to specify which files are used can create security 170 problems, environment information will be used in file naming for all users 171 only if the <code class="literal">DB_USE_ENVIRON</code> flag is set. 172 </p> 173 </li> 174 <li> 175 <p><a id="envremove_DB_USE_ENVIRON_ROOT"></a> 176 <code class="literal">DB_USE_ENVIRON_ROOT</code> 177 </p> 178 <p> 179 The Berkeley DB process' environment may be permitted to specify information to 180 be used when naming files; see 181 <a href="../../programmer_reference/env_naming.html" class="olink">Berkeley DB File Naming</a>. 182 Because permitting users to specify which files are used can create security 183 problems, if the <code class="literal">DB_USE_ENVIRON_ROOT</code> flag is set, environment 184 information will be used in file naming only for users with appropriate 185 permissions (for example, users with a user-ID of 0 on <code class="literal">UNIX</code> 186 systems). 187 </p> 188 </li> 189 </ul> 190 </div> 191 </div> 192 </div> 193 <div class="sect2" lang="en" xml:lang="en"> 194 <div class="titlepage"> 195 <div> 196 <div> 197 <h3 class="title"><a id="id1666645"></a>Errors</h3> 198 </div> 199 </div> 200 </div> 201 <p> 202 The <code class="methodname">DB_ENV->remove()</code> <span> 203 <span> 204 method may fail and return one of the following non-zero errors: 205 </span> 206 207 </span> 208 </p> 209 <div class="sect3" lang="en" xml:lang="en"> 210 <div class="titlepage"> 211 <div> 212 <div> 213 <h4 class="title"><a id="id1666517"></a>EBUSY</h4> 214 </div> 215 </div> 216 </div> 217 <p> 218 The shared memory region was in use and the force flag was not set. 219 </p> 220 </div> 221 </div> 222 <div class="sect2" lang="en" xml:lang="en"> 223 <div class="titlepage"> 224 <div> 225 <div> 226 <h3 class="title"><a id="id1666357"></a>Class</h3> 227 </div> 228 </div> 229 </div> 230 <p> 231 <a class="link" href="env.html" title="Chapter��5.�� The DB_ENV Handle">DB_ENV</a> 232 </p> 233 </div> 234 <div class="sect2" lang="en" xml:lang="en"> 235 <div class="titlepage"> 236 <div> 237 <div> 238 <h3 class="title"><a id="id1666401"></a>See Also</h3> 239 </div> 240 </div> 241 </div> 242 <p> 243 <a class="xref" href="env.html#envlist" title="Database Environments and Related Methods">Database Environments and Related Methods</a> 244 </p> 245 </div> 246 </div> 247 <div class="navfooter"> 248 <hr /> 249 <table width="100%" summary="Navigation footer"> 250 <tr> 251 <td width="40%" align="left"><a accesskey="p" href="envopen.html">Prev</a>��</td> 252 <td width="20%" align="center"> 253 <a accesskey="u" href="env.html">Up</a> 254 </td> 255 <td width="40%" align="right">��<a accesskey="n" href="envset_alloc.html">Next</a></td> 256 </tr> 257 <tr> 258 <td width="40%" align="left" valign="top">DB_ENV->open()��</td> 259 <td width="20%" align="center"> 260 <a accesskey="h" href="index.html">Home</a> 261 </td> 262 <td width="40%" align="right" valign="top">��DB_ENV->set_alloc()</td> 263 </tr> 264 </table> 265 </div> 266 </body> 267</html> 268