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::set_alloc()</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="envremove.html" title="DbEnv::remove()" /> 12 <link rel="next" href="envset_app_dispatch.html" title="DbEnv::set_app_dispatch()" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">DbEnv::set_alloc()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="envremove.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_app_dispatch.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="envset_alloc"></a>DbEnv::set_alloc()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db_cxx.h> 39 40extern "C" { 41 typedef void *(*db_malloc_fcn_type)(size_t); 42 typedef void *(*db_realloc_fcn_type)(void *, size_t); 43 typedef void *(*db_free_fcn_type)(void *); 44}; 45 46int 47DbEnv::set_alloc(db_malloc_fcn_type app_malloc, 48 db_realloc_fcn_type app_realloc, 49 db_free_fcn_type app_free);</pre> 50 <p> 51 Set the allocation functions used by the <a class="link" href="env.html" title="Chapter 5. The DbEnv Handle">DbEnv</a> and 52 <a class="link" href="db.html" title="Chapter 2. The Db Handle">Db</a> methods to allocate or free 53 memory owned by the application. 54 </p> 55 <p> 56 There are a number of interfaces in Berkeley DB where memory is 57 allocated by the library and then given to the application. For 58 example, the <a class="link" href="dbt.html#dbt_DB_DBT_MALLOC">DB_DBT_MALLOC</a> 59 flag, when specified in the <a class="link" href="dbt.html" title="Chapter 4. The Dbt Handle">Dbt</a> 60 object, will cause the <a class="link" href="db.html" title="Chapter 2. The Db Handle">Db</a> methods to allocate and 61 reallocate memory which then becomes the responsibility of the calling 62 application. Other examples are the Berkeley DB interfaces 63 which return statistical information to the application: 64 <a class="xref" href="dbstat.html" title="Db::stat()">Db::stat()</a>, 65 <a class="xref" href="lockstat.html" title="DbEnv::lock_stat()">DbEnv::lock_stat()</a>, 66 <a class="xref" href="logarchive.html" title="DbEnv::log_archive()">DbEnv::log_archive()</a>, 67 <a class="xref" href="logstat.html" title="DbEnv::log_stat()">DbEnv::log_stat()</a>, 68 <a class="xref" href="mempstat.html" title="DbEnv::memp_stat()">DbEnv::memp_stat()</a>, and 69 <a class="xref" href="txnstat.html" title="DbEnv::txn_stat()">DbEnv::txn_stat()</a>. There is 70 one method in Berkeley DB where memory is allocated by the application 71 and then given to the library: the callback specified to 72 <a class="xref" href="dbassociate.html" title="Db::associate()">Db::associate()</a>. 73 </p> 74 <p> 75 On systems in which there may be multiple library versions of the 76 standard allocation routines (notably Windows NT), transferring memory 77 between the library and the application will fail because the Berkeley 78 DB library allocates memory from a different heap than the application 79 uses to free it. To avoid this problem, the <code class="methodname">DbEnv::set_alloc()</code> and 80 <a class="xref" href="dbset_alloc.html" title="Db::set_alloc()">Db::set_alloc()</a> 81 methods can be used to pass Berkeley DB references to the 82 application's allocation routines. 83 </p> 84 <p> 85 It is not an error to specify only one or two of the possible 86 allocation function parameters to these interfaces; however, in that 87 case the specified interfaces must be compatible with the standard 88 library interfaces, as they will be used together. The functions 89 specified must match the calling conventions of the ANSI C X3.159-1989 90 (ANSI C) library routines of the same name. 91 </p> 92 <p> 93 The <code class="methodname">DbEnv::set_alloc()</code> method configures operations performed using 94 the specified <a class="link" href="env.html" title="Chapter 5. The DbEnv Handle">DbEnv</a> 95 handle, not all operations performed on the underlying database 96 environment. 97 </p> 98 <p> 99 The <code class="methodname">DbEnv::set_alloc()</code> method may not be called after the 100 <a class="xref" href="envopen.html" title="DbEnv::open()">DbEnv::open()</a> method is called. 101 </p> 102 <p> 103 The <code class="methodname">DbEnv::set_alloc()</code> <span> 104 105 <span> 106 method either returns a non-zero error value or throws an 107 exception that encapsulates a non-zero error value on 108 failure, and returns 0 on success. 109 </span> 110 </span> 111 </p> 112 <div class="sect2" lang="en" xml:lang="en"> 113 <div class="titlepage"> 114 <div> 115 <div> 116 <h3 class="title"><a id="id1669048"></a>Parameters</h3> 117 </div> 118 </div> 119 </div> 120 <div class="sect3" lang="en" xml:lang="en"> 121 <div class="titlepage"> 122 <div> 123 <div> 124 <h4 class="title"><a id="id1669054"></a>app_malloc</h4> 125 </div> 126 </div> 127 </div> 128 <p> 129 The <span class="bold"><strong>app_malloc</strong></span> parameter is the 130 application-specified malloc function. 131 </p> 132 </div> 133 <div class="sect3" lang="en" xml:lang="en"> 134 <div class="titlepage"> 135 <div> 136 <div> 137 <h4 class="title"><a id="id1669169"></a>app_realloc</h4> 138 </div> 139 </div> 140 </div> 141 <p> 142 The <span class="bold"><strong>app_realloc</strong></span> parameter is the 143 application-specified realloc function. 144 </p> 145 </div> 146 <div class="sect3" lang="en" xml:lang="en"> 147 <div class="titlepage"> 148 <div> 149 <div> 150 <h4 class="title"><a id="id1669173"></a>app_free</h4> 151 </div> 152 </div> 153 </div> 154 <p> 155 The <span class="bold"><strong>app_free</strong></span> parameter is the 156 application-specified free function. 157 </p> 158 </div> 159 </div> 160 <div class="sect2" lang="en" xml:lang="en"> 161 <div class="titlepage"> 162 <div> 163 <div> 164 <h3 class="title"><a id="id1669197"></a>Errors</h3> 165 </div> 166 </div> 167 </div> 168 <p> 169 The <code class="methodname">DbEnv::set_alloc()</code> <span> 170 171 <span> 172 method may fail and throw a <a class="link" href="dbexception.html" title="Chapter 6. The DbException Class">DbException</a> 173 exception, encapsulating one of the following non-zero errors, or return one 174 of the following non-zero errors: 175 </span> 176 </span> 177 </p> 178 <div class="sect3" lang="en" xml:lang="en"> 179 <div class="titlepage"> 180 <div> 181 <div> 182 <h4 class="title"><a id="id1669106"></a>EINVAL</h4> 183 </div> 184 </div> 185 </div> 186 <p> 187 If the method was called after <a class="xref" href="envopen.html" title="DbEnv::open()">DbEnv::open()</a> 188 was called; or if an invalid flag value or parameter was specified. 189 </p> 190 </div> 191 </div> 192 <div class="sect2" lang="en" xml:lang="en"> 193 <div class="titlepage"> 194 <div> 195 <div> 196 <h3 class="title"><a id="id1669075"></a>Class</h3> 197 </div> 198 </div> 199 </div> 200 <p> 201 <a class="link" href="env.html" title="Chapter 5. The DbEnv Handle">DbEnv</a> 202 </p> 203 </div> 204 <div class="sect2" lang="en" xml:lang="en"> 205 <div class="titlepage"> 206 <div> 207 <div> 208 <h3 class="title"><a id="id1669172"></a>See Also</h3> 209 </div> 210 </div> 211 </div> 212 <p> 213 <a class="xref" href="env.html#envlist" title="Database Environments and Related Methods">Database Environments and Related Methods</a> 214 </p> 215 </div> 216 </div> 217 <div class="navfooter"> 218 <hr /> 219 <table width="100%" summary="Navigation footer"> 220 <tr> 221 <td width="40%" align="left"><a accesskey="p" href="envremove.html">Prev</a> </td> 222 <td width="20%" align="center"> 223 <a accesskey="u" href="env.html">Up</a> 224 </td> 225 <td width="40%" align="right"> <a accesskey="n" href="envset_app_dispatch.html">Next</a></td> 226 </tr> 227 <tr> 228 <td width="40%" align="left" valign="top">DbEnv::remove() </td> 229 <td width="20%" align="center"> 230 <a accesskey="h" href="index.html">Home</a> 231 </td> 232 <td width="40%" align="right" valign="top"> DbEnv::set_app_dispatch()</td> 233 </tr> 234 </table> 235 </div> 236 </body> 237</html> 238