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->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="db.html" title="Chapter 2. The DB Handle" /> 11 <link rel="prev" href="dbrename.html" title="DB->rename()" /> 12 <link rel="next" href="dbset_append_recno.html" title="DB->set_append_recno()" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">DB->set_alloc()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="dbrename.html">Prev</a> </td> 22 <th width="60%" align="center">Chapter 2. 23 The DB Handle 24 </th> 25 <td width="20%" align="right"> <a accesskey="n" href="dbset_append_recno.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="dbset_alloc"></a>DB->set_alloc()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db.h> 39 40int 41DB->set_alloc(DB *db, 42 void *(*app_malloc)(size_t), 43 void *(*app_realloc)(void *, size_t), 44 void (*app_free)(void *)); </pre> 45 <p> 46 Set the allocation functions used by the 47 <a class="link" href="env.html" title="Chapter 5. The DB_ENV Handle">DB_ENV</a> and 48 <a class="link" href="db.html" title="Chapter 2. The DB Handle">DB</a> methods to allocate or free 49 memory owned by the application. 50 </p> 51 <p> 52 There are a number of interfaces in Berkeley DB where memory is 53 allocated by the library and then given to the application. For 54 example, the <a class="link" href="dbt.html#dbt_DB_DBT_MALLOC">DB_DBT_MALLOC</a> 55 flag, when specified in the <a class="link" href="dbt.html" title="Chapter 4. The DBT Handle">DBT</a> 56 object, will cause the <a class="link" href="db.html" title="Chapter 2. The DB Handle">DB</a> methods to allocate and 57 reallocate memory which then becomes the responsibility of the calling 58 application. (See <a class="link" href="dbt.html" title="Chapter 4. The DBT Handle">DBT</a> 59 for more information.) Other examples are the Berkeley DB interfaces 60 which return statistical information to the application: 61 <a class="xref" href="dbstat.html" title="DB->stat()">DB->stat()</a>, 62 <a class="xref" href="lockstat.html" title="DB_ENV->lock_stat()">DB_ENV->lock_stat()</a>, 63 <a class="xref" href="logarchive.html" title="DB_ENV->log_archive()">DB_ENV->log_archive()</a>, 64 <a class="xref" href="logstat.html" title="DB_ENV->log_stat()">DB_ENV->log_stat()</a>, 65 <a class="xref" href="mempstat.html" title="DB_ENV->memp_stat()">DB_ENV->memp_stat()</a>, 66 and <a class="xref" href="txnstat.html" title="DB_ENV->txn_stat()">DB_ENV->txn_stat()</a>. There is 67 one method in Berkeley DB where memory is allocated by the application 68 and then given to the library: <a class="xref" href="dbassociate.html" title="DB->associate()">DB->associate()</a>. 69 </p> 70 <p> 71 On systems in which there may be multiple library versions of the 72 standard allocation routines (notably Windows NT), transferring memory 73 between the library and the application will fail because the Berkeley 74 DB library allocates memory from a different heap than the application 75 uses to free it. To avoid this problem, the 76 <a class="xref" href="envset_alloc.html" title="DB_ENV->set_alloc()">DB_ENV->set_alloc()</a> and 77 <code class="methodname">DB->set_alloc()</code> methods can be used to pass Berkeley DB references to 78 the application's allocation routines. 79 </p> 80 <p> 81 It is not an error to specify only one or two of the possible 82 allocation function parameters to these interfaces; however, in that 83 case the specified interfaces must be compatible with the standard 84 library interfaces, as they will be used together. The functions 85 specified must match the calling conventions of the ANSI C X3.159-1989 86 (ANSI C) library routines of the same name. 87 </p> 88 <p> 89 Because databases opened within Berkeley DB environments use the 90 allocation interfaces specified to the environment, it is an error to 91 attempt to set those interfaces in a database created within an 92 environment. 93 </p> 94 <p> 95 The <code class="methodname">DB->set_alloc()</code> method may not be called after the 96 <a class="xref" href="dbopen.html" title="DB->open()">DB->open()</a> method is called. 97 </p> 98 <p> 99 The <code class="methodname">DB->set_alloc()</code> <span> 100 <span> 101 method returns a non-zero error value on failure and 0 on success. 102 </span> 103 104 </span> 105 </p> 106 <div class="sect2" lang="en" xml:lang="en"> 107 <div class="titlepage"> 108 <div> 109 <div> 110 <h3 class="title"><a id="id1642285"></a>Errors</h3> 111 </div> 112 </div> 113 </div> 114 <p> 115 The <code class="methodname">DB->set_alloc()</code> <span> 116 <span> 117 method may fail and return one of the following non-zero errors: 118 </span> 119 120 </span> 121 </p> 122 <div class="sect3" lang="en" xml:lang="en"> 123 <div class="titlepage"> 124 <div> 125 <div> 126 <h4 class="title"><a id="id1642418"></a>EINVAL</h4> 127 </div> 128 </div> 129 </div> 130 <p> 131 If called in a database environment, or called after 132 <a class="xref" href="dbopen.html" title="DB->open()">DB->open()</a> was called; or if an 133 invalid flag value or parameter was specified. 134 </p> 135 </div> 136 </div> 137 <div class="sect2" lang="en" xml:lang="en"> 138 <div class="titlepage"> 139 <div> 140 <div> 141 <h3 class="title"><a id="id1642429"></a>Class</h3> 142 </div> 143 </div> 144 </div> 145 <p> 146 <a class="link" href="db.html" title="Chapter 2. The DB Handle">DB</a> 147 </p> 148 </div> 149 <div class="sect2" lang="en" xml:lang="en"> 150 <div class="titlepage"> 151 <div> 152 <div> 153 <h3 class="title"><a id="id1642326"></a>See Also</h3> 154 </div> 155 </div> 156 </div> 157 <p> 158 <a class="xref" href="db.html#dblist" title="Database and Related Methods">Database and Related Methods</a> 159 </p> 160 </div> 161 </div> 162 <div class="navfooter"> 163 <hr /> 164 <table width="100%" summary="Navigation footer"> 165 <tr> 166 <td width="40%" align="left"><a accesskey="p" href="dbrename.html">Prev</a> </td> 167 <td width="20%" align="center"> 168 <a accesskey="u" href="db.html">Up</a> 169 </td> 170 <td width="40%" align="right"> <a accesskey="n" href="dbset_append_recno.html">Next</a></td> 171 </tr> 172 <tr> 173 <td width="40%" align="left" valign="top">DB->rename() </td> 174 <td width="20%" align="center"> 175 <a accesskey="h" href="index.html">Home</a> 176 </td> 177 <td width="40%" align="right" valign="top"> DB->set_append_recno()</td> 178 </tr> 179 </table> 180 </div> 181 </body> 182</html> 183