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_MPOOLFILE->get()</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="memp.html" title="Chapter��8.�� The DB_MPOOLFILE Handle" /> 11 <link rel="prev" href="mempfclose.html" title="DB_MPOOLFILE->close()" /> 12 <link rel="next" href="mempfopen.html" title="DB_MPOOLFILE->open()" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">DB_MPOOLFILE->get()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="mempfclose.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��8.�� 23 The DB_MPOOLFILE Handle 24 </th> 25 <td width="20%" align="right">��<a accesskey="n" href="mempfopen.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="mempfget"></a>DB_MPOOLFILE->get()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db.h> 39 40int 41DB_MPOOLFILE->get(DB_MPOOLFILE *mpf, 42 db_pgno_t *pgnoaddr, DB_TXN * txnid, u_int32_t flags, void **pagep); </pre> 43 <p> 44 The <code class="methodname">DB_MPOOLFILE->get()</code> method returns pages from the cache. 45 </p> 46 <p> 47 All pages returned by <code class="methodname">DB_MPOOLFILE->get()</code> will be retained (that is, 48 <span class="emphasis"><em>latched</em></span>) in the cache until a subsequent call to 49 <a class="xref" href="mempput.html" title="DB_MPOOLFILE->put()">DB_MPOOLFILE->put()</a>. 50 There is no deadlock detection amoung latches so care must be taken in the application if the DB_MPOOL_DIRTY 51 or DB_MPOOL_EDIT flags are used as these get exlusive latches on the pages. 52 </p> 53 <p> 54 The returned page is <span class="bold"><strong>size_t</strong></span> type 55 aligned. 56 </p> 57 <p> 58 Fully or partially created pages have all their bytes set to a nul 59 byte, unless the 60 <a class="xref" href="mempset_clear_len.html" title="DB_MPOOLFILE->set_clear_len()">DB_MPOOLFILE->set_clear_len()</a> 61 method was called to specify other behavior before the file was 62 opened. 63 </p> 64 <p><a id="fget_DB_PAGE_NOTFOUND"></a> 65 The <code class="methodname">DB_MPOOLFILE->get()</code> method will return 66 <code class="literal">DB_PAGE_NOTFOUND</code> if the requested page does not exist and DB_MPOOL_CREATE 67 was not set. Unless otherwise specified, the <code class="methodname">DB_MPOOLFILE->get()</code> 68 <span> 69 <span> 70 method returns a non-zero error value on failure and 0 on success. 71 </span> 72 73 </span> 74 </p> 75 <div class="sect2" lang="en" xml:lang="en"> 76 <div class="titlepage"> 77 <div> 78 <div> 79 <h3 class="title"><a id="id1689424"></a>Parameters</h3> 80 </div> 81 </div> 82 </div> 83 <div class="sect3" lang="en" xml:lang="en"> 84 <div class="titlepage"> 85 <div> 86 <div> 87 <h4 class="title"><a id="id1689441"></a>flags</h4> 88 </div> 89 </div> 90 </div> 91 <p> 92 The <span class="bold"><strong>flags</strong></span> parameter must be set to 0 93 or by bitwise inclusively <span class="bold"><strong>OR</strong></span>'ing 94 together one or more of the following values: 95 </p> 96 <div class="itemizedlist"> 97 <ul type="disc"> 98 <li> 99 <p><a id="mpoolfget_DB_MPOOL_CREATE"></a> 100 <code class="literal">DB_MPOOL_CREATE</code> 101 </p> 102 <p> 103 If the specified page does not exist, create it. In this case, the 104 <a class="link" href="mempregister.html" title="DB_ENV->memp_register()">pgin</a> method, if 105 specified, is called. 106 </p> 107 </li> 108 <li> 109 <p><a id="fget_DB_MPOOL_DIRTY"></a> 110 <code class="literal">DB_MPOOL_DIRTY</code> 111 </p> 112 <p> 113 The page will be modified and must be written to the source file 114 before being evicted from the cache. For files open with the 115 <a class="link" href="dbopen.html#dbopen_DB_MULTIVERSION">DB_MULTIVERSION</a> 116 flag set, a new copy of the page will be made if this is the first 117 time the specified transaction is modifying it. 118 A page fetched with the <code class="literal">DB_MPOOL_DIRTY</code> flag will be 119 <span class="bold"><strong>excluively latched</strong></span> until 120 a subsequent call to <a class="xref" href="mempput.html" title="DB_MPOOLFILE->put()">DB_MPOOLFILE->put()</a>. 121 </p> 122 </li> 123 <li> 124 <p><a id="fget_DB_MPOOL_EDIT"></a> 125 <code class="literal">DB_MPOOL_EDIT</code> 126 </p> 127 <p> 128 The page will be modified and must be written to the source file 129 before being evicted from the cache. No copy of the page will be made, 130 regardless of the 131 <a class="link" href="dbopen.html#dbopen_DB_MULTIVERSION">DB_MULTIVERSION</a> 132 setting. This flag is only intended for use in situations where a 133 transaction handle is not available, such as during aborts or 134 recovery. 135 A page fetched with the <code class="literal">DB_MPOOL_EDIT</code> flag will be 136 <span class="bold"><strong>excluively latched</strong></span> until 137 a subsequent call to <a class="xref" href="mempput.html" title="DB_MPOOLFILE->put()">DB_MPOOLFILE->put()</a>. 138 </p> 139 </li> 140 <li> 141 <p><a id="fget_DB_MPOOL_LAST"></a> 142 <code class="literal">DB_MPOOL_LAST</code> 143 </p> 144 <p> 145 Return the last page of the source file, and copy its page number into 146 the memory location to which <span class="bold"><strong>pgnoaddr</strong></span> 147 refers. 148 </p> 149 </li> 150 <li> 151 <p><a id="mpoolfget_DB_MPOOL_NEW"></a> 152 <code class="literal">DB_MPOOL_NEW</code> 153 </p> 154 <p> 155 Create a new page in the file, and copy its page number into the 156 memory location to which <span class="bold"><strong>pgnoaddr</strong></span> 157 refers. In this case, the <code class="literal">pgin_fcn</code> callback, if specified on 158 <a class="xref" href="mempregister.html" title="DB_ENV->memp_register()">DB_ENV->memp_register()</a>, is 159 <span class="bold"><strong>not</strong></span> called. 160 </p> 161 </li> 162 </ul> 163 </div> 164 <p> 165 The <code class="literal">DB_MPOOL_CREATE</code>, <code class="literal">DB_MPOOL_LAST</code>, and 166 <code class="literal">DB_MPOOL_NEW</code> flags are mutually exclusive. 167 </p> 168 </div> 169 <div class="sect3" lang="en" xml:lang="en"> 170 <div class="titlepage"> 171 <div> 172 <div> 173 <h4 class="title"><a id="id1689759"></a>pagep</h4> 174 </div> 175 </div> 176 </div> 177 <p> 178 The <span class="bold"><strong>pagep</strong></span> parameter references memory 179 into which a pointer to the returned page is copied. 180 </p> 181 </div> 182 <div class="sect3" lang="en" xml:lang="en"> 183 <div class="titlepage"> 184 <div> 185 <div> 186 <h4 class="title"><a id="id1689735"></a>pgnoaddr</h4> 187 </div> 188 </div> 189 </div> 190 <p> 191 If the <span class="bold"><strong>flags</strong></span> parameter is set to 192 <code class="literal">DB_MPOOL_LAST</code> or <code class="literal">DB_MPOOL_NEW</code>, the 193 page number of the created page is copied into the memory location to 194 which the <span class="bold"><strong>pgnoaddr</strong></span> parameter refers. 195 Otherwise, the <span class="bold"><strong>pgnoaddr</strong></span> parameter is the 196 page to create or retrieve. 197 </p> 198 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> 199 <h3 class="title">Note</h3> 200 <p> 201 Page numbers begin at 0; that is, the first page in the file is page number 0, 202 not page number 1. 203 </p> 204 </div> 205 </div> 206 <div class="sect3" lang="en" xml:lang="en"> 207 <div class="titlepage"> 208 <div> 209 <div> 210 <h4 class="title"><a id="id1689745"></a>txnid</h4> 211 </div> 212 </div> 213 </div> 214 <p> 215 If the operation is part of an application-specified transaction, the 216 <span class="bold"><strong>txnid</strong></span> parameter is a transaction 217 handle returned from <a class="xref" href="txnbegin.html" title="DB_ENV->txn_begin()">DB_ENV->txn_begin()</a>; 218 otherwise NULL. A transaction is required if the file is open for multiversion 219 concurrency control by passing 220 <a class="link" href="dbopen.html#dbopen_DB_MULTIVERSION">DB_MULTIVERSION</a> 221 to 222 <a class="xref" href="mempfopen.html" title="DB_MPOOLFILE->open()">DB_MPOOLFILE->open()</a> 223 and the DB_MPOOL_DIRTY, DB_MPOOL_CREATE or DB_MPOOL_NEW flags were 224 specified. Otherwise it is ignored. 225 </p> 226 </div> 227 </div> 228 <div class="sect2" lang="en" xml:lang="en"> 229 <div class="titlepage"> 230 <div> 231 <div> 232 <h3 class="title"><a id="id1689577"></a>Errors</h3> 233 </div> 234 </div> 235 </div> 236 <p> 237 The <code class="methodname">DB_MPOOLFILE->get()</code> <span> 238 <span> 239 method may fail and return one of the following non-zero errors: 240 </span> 241 242 </span> 243 </p> 244 <div class="sect3" lang="en" xml:lang="en"> 245 <div class="titlepage"> 246 <div> 247 <div> 248 <h4 class="title"><a id="id1689663"></a>EACCES</h4> 249 </div> 250 </div> 251 </div> 252 <p> 253 The <code class="literal">DB_MPOOL_DIRTY</code> or 254 <code class="literal">DB_MPOOL_EDIT</code> flag was set and the source file was 255 not opened for writing. 256 </p> 257 </div> 258 <div class="sect3" lang="en" xml:lang="en"> 259 <div class="titlepage"> 260 <div> 261 <div> 262 <h4 class="title"><a id="id1689754"></a>EAGAIN</h4> 263 </div> 264 </div> 265 </div> 266 <p> 267 The page reference count has overflowed. (This should never happen 268 unless there is a bug in the application.) 269 </p> 270 </div> 271 <div class="sect3" lang="en" xml:lang="en"> 272 <div class="titlepage"> 273 <div> 274 <div> 275 <h4 class="title"><a id="id1689606"></a>EINVAL</h4> 276 </div> 277 </div> 278 </div> 279 <p> 280 If the <code class="literal">DB_MPOOL_NEW</code> flag was set, and the source 281 file was not opened for writing; more than one of 282 <code class="literal">DB_MPOOL_CREATE</code>, <code class="literal">DB_MPOOL_LAST</code>, 283 and <code class="literal">DB_MPOOL_NEW</code> was set; or if an invalid flag 284 value or parameter was specified. 285 </p> 286 </div> 287 <div class="sect3" lang="en" xml:lang="en"> 288 <div class="titlepage"> 289 <div> 290 <div> 291 <h4 class="title"><a id="id1689278"></a>DB_LOCK_DEADLOCK</h4> 292 </div> 293 </div> 294 </div> 295 <p> 296 For transactions configured with 297 <a class="link" href="txnbegin.html#txnbegin_DB_TXN_SNAPSHOT">DB_TXN_SNAPSHOT</a>, 298 the page has been modified since the transaction began. 299 </p> 300 </div> 301 <div class="sect3" lang="en" xml:lang="en"> 302 <div class="titlepage"> 303 <div> 304 <div> 305 <h4 class="title"><a id="id1689437"></a>ENOMEM</h4> 306 </div> 307 </div> 308 </div> 309 <p> 310 The cache is full, and no more pages will fit in the cache. 311 </p> 312 </div> 313 </div> 314 <div class="sect2" lang="en" xml:lang="en"> 315 <div class="titlepage"> 316 <div> 317 <div> 318 <h3 class="title"><a id="id1689659"></a>Class</h3> 319 </div> 320 </div> 321 </div> 322 <p> 323 <a class="link" href="env.html" title="Chapter��5.�� The DB_ENV Handle">DB_ENV</a>, <a class="link" href="memp.html" title="Chapter��8.�� The DB_MPOOLFILE Handle">DB_MPOOLFILE</a> 324 </p> 325 </div> 326 <div class="sect2" lang="en" xml:lang="en"> 327 <div class="titlepage"> 328 <div> 329 <div> 330 <h3 class="title"><a id="id1689400"></a>See Also</h3> 331 </div> 332 </div> 333 </div> 334 <p> 335 <a class="xref" href="memp.html#memplist" title="Memory Pools and Related Methods">Memory Pools and Related Methods</a> 336 </p> 337 </div> 338 </div> 339 <div class="navfooter"> 340 <hr /> 341 <table width="100%" summary="Navigation footer"> 342 <tr> 343 <td width="40%" align="left"><a accesskey="p" href="mempfclose.html">Prev</a>��</td> 344 <td width="20%" align="center"> 345 <a accesskey="u" href="memp.html">Up</a> 346 </td> 347 <td width="40%" align="right">��<a accesskey="n" href="mempfopen.html">Next</a></td> 348 </tr> 349 <tr> 350 <td width="40%" align="left" valign="top">DB_MPOOLFILE->close()��</td> 351 <td width="20%" align="center"> 352 <a accesskey="h" href="index.html">Home</a> 353 </td> 354 <td width="40%" align="right" valign="top">��DB_MPOOLFILE->open()</td> 355 </tr> 356 </table> 357 </div> 358 </body> 359</html> 360