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>DbMpoolFile::open()</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 9. The DbMpoolFile Handle" /> 11 <link rel="prev" href="mempfget.html" title="DbMpoolFile::get()" /> 12 <link rel="next" href="mempput.html" title="DbMpoolFile::put()" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">DbMpoolFile::open()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="mempfget.html">Prev</a> </td> 22 <th width="60%" align="center">Chapter 9. 23 The DbMpoolFile Handle 24 </th> 25 <td width="20%" align="right"> <a accesskey="n" href="mempput.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="mempfopen"></a>DbMpoolFile::open()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db_cxx.h> 39 40int 41DbMpoolFile::open(const char *file, u_int32_t flags, int mode, size_t pagesize);</pre> 42 <p> 43 The <code class="methodname">DbMpoolFile::open()</code> method opens a file in the in-memory cache. 44 </p> 45 <p> 46 The <code class="methodname">DbMpoolFile::open()</code> <span> 47 48 <span> 49 method either returns a non-zero error value or throws an 50 exception that encapsulates a non-zero error value on 51 failure, and returns 0 on success. 52 </span> 53 </span> 54 </p> 55 <div class="sect2" lang="en" xml:lang="en"> 56 <div class="titlepage"> 57 <div> 58 <div> 59 <h3 class="title"><a id="id1693717"></a>Parameters</h3> 60 </div> 61 </div> 62 </div> 63 <div class="sect3" lang="en" xml:lang="en"> 64 <div class="titlepage"> 65 <div> 66 <div> 67 <h4 class="title"><a id="id1693787"></a>file</h4> 68 </div> 69 </div> 70 </div> 71 <p> 72 The <span class="bold"><strong>file</strong></span> parameter is the name of the 73 file to be opened. If <span class="bold"><strong>file</strong></span> is NULL, 74 a private temporary file is created that cannot be shared with any 75 other process (although it may be shared with other threads of control 76 in the same process). 77 </p> 78 <p> 79 When using a Unicode build on Windows (the default), the 80 <span class="bold"><strong>file</strong></span> argument will 81 be interpreted as a UTF-8 string, which is equivalent to ASCII for Latin 82 characters. 83 </p> 84 </div> 85 <div class="sect3" lang="en" xml:lang="en"> 86 <div class="titlepage"> 87 <div> 88 <div> 89 <h4 class="title"><a id="id1694490"></a>flags</h4> 90 </div> 91 </div> 92 </div> 93 <p> 94 The <span class="bold"><strong>flags</strong></span> parameter must be set to zero or 95 by bitwise inclusively <span class="bold"><strong>OR</strong></span>'ing together one 96 or more of the following values: 97 </p> 98 <div class="itemizedlist"> 99 <ul type="disc"> 100 <li> 101 <p><a id="mempopen_DB_CREATE"></a> 102 <code class="literal">DB_CREATE</code> 103 </p> 104 <p> 105 Create any underlying files, as necessary. If the database do not already exist 106 and the <code class="literal">DB_CREATE</code> flag is not specified, the 107 call will fail. 108 </p> 109 </li> 110 <li> 111 <p><a id="mempopen_DB_EXCL"></a> 112 <code class="literal">DB_DIRECT</code> 113 </p> 114 <p> 115 If set and supported by the system, turn off system buffering of the file to 116 avoid double caching. 117 </p> 118 </li> 119 <li> 120 <p><a id="mempopen_DB_MULTIVERSION"></a> 121 <code class="literal">DB_MULTIVERSION</code> 122 </p> 123 <p> 124 Open the file with support for 125 <a href="../../programmer_reference/transapp_read.html" class="olink">multiversion concurrency control</a>. 126 Calls to <a class="xref" href="mempfget.html" title="DbMpoolFile::get()">DbMpoolFile::get()</a> 127 with dirty pages will cause copies to be made in the cache. 128 </p> 129 </li> 130 <li> 131 <p><a id="mempopen_DB_NOMMAP"></a> 132 <code class="literal">DB_NOMMAP</code> 133 </p> 134 <p> 135 Always copy this file into the local cache instead of potentially mapping it 136 into process memory (see the 137 <a class="xref" href="envset_mp_mmapsize.html" title="DbEnv::set_mp_mmapsize()">DbEnv::set_mp_mmapsize()</a> 138 method for further information). 139 </p> 140 </li> 141 <li> 142 <p><a id="mempopen_DB_ODDFILESIZE"></a> 143 <code class="literal">DB_ODDFILESIZE</code> 144 </p> 145 <p> 146 Attempts to open files which are not a multiple of the page size in length will 147 fail, by default. If the DB_ODDFILESIZE flag is set, any partial page at the end 148 of the file will be ignored and the open will proceed. 149 </p> 150 </li> 151 <li> 152 <p><a id="mempopen_DB_RDONLY"></a> 153 <code class="literal">DB_RDONLY</code> 154 </p> 155 <p> 156 Open any underlying files for reading only. Any attempt to modify 157 the file using the memory pool (cache) functions will fail, regardless of the actual 158 permissions of the file. 159 </p> 160 </li> 161 </ul> 162 </div> 163 </div> 164 <div class="sect3" lang="en" xml:lang="en"> 165 <div class="titlepage"> 166 <div> 167 <div> 168 <h4 class="title"><a id="id1694688"></a>mode</h4> 169 </div> 170 </div> 171 </div> 172 <p> 173 On Windows systems, the mode parameter is ignored. 174 </p> 175 <p> 176 On UNIX systems or in IEEE/ANSI Std 1003.1 (POSIX) environments, files 177 created by <code class="methodname">DbMpoolFile::open()</code> are created with mode 178 <span class="bold"><strong>mode</strong></span> (as described in <span class="bold"><strong>chmod</strong></span>(2)) and modified by the process' umask 179 value at the time of creation (see <span class="bold"><strong>umask</strong></span>(2)). Created files are owned by the 180 process owner; the group ownership of created files is based on the system 181 and directory defaults, and is not further specified by Berkeley DB. System 182 shared memory segments created by <code class="methodname">DbMpoolFile::open()</code> are 183 created with mode <span class="bold"><strong>mode</strong></span>, unmodified by the 184 process' umask value. If <span class="bold"><strong>mode</strong></span> is 0, 185 <code class="methodname">DbMpoolFile::open()</code> will use a default mode of readable 186 and writable by both owner and group. 187 </p> 188 </div> 189 <div class="sect3" lang="en" xml:lang="en"> 190 <div class="titlepage"> 191 <div> 192 <div> 193 <h4 class="title"><a id="id1694813"></a>pagesize</h4> 194 </div> 195 </div> 196 </div> 197 <p> 198 The <span class="bold"><strong>pagesize</strong></span> parameter is the size, 199 in bytes, of the unit of transfer between the application and the 200 cache, although it is not necessarily the unit of transfer between the 201 cache and the underlying filesystem. 202 </p> 203 </div> 204 </div> 205 <div class="sect2" lang="en" xml:lang="en"> 206 <div class="titlepage"> 207 <div> 208 <div> 209 <h3 class="title"><a id="id1694724"></a>Errors</h3> 210 </div> 211 </div> 212 </div> 213 <p> 214 The <code class="methodname">DbMpoolFile::open()</code> <span> 215 216 <span> 217 method may fail and throw a <a class="link" href="dbexception.html" title="Chapter 6. The DbException Class">DbException</a> 218 exception, encapsulating one of the following non-zero errors, or return one 219 of the following non-zero errors: 220 </span> 221 </span> 222 </p> 223 <div class="sect3" lang="en" xml:lang="en"> 224 <div class="titlepage"> 225 <div> 226 <div> 227 <h4 class="title"><a id="id1694787"></a>EINVAL</h4> 228 </div> 229 </div> 230 </div> 231 <p> 232 If the file has already been entered into the cache, and the <span class="bold"><strong>pagesize</strong></span> value is not the same as when the file 233 was entered into the cache, or the length of the file is not zero or a 234 multiple of the <span class="bold"><strong>pagesize</strong></span>; the 235 DB_RDONLY flag was specified for an in-memory cache; or if an invalid 236 flag value or parameter was specified. 237 </p> 238 </div> 239 <div class="sect3" lang="en" xml:lang="en"> 240 <div class="titlepage"> 241 <div> 242 <div> 243 <h4 class="title"><a id="id1694749"></a>ENOMEM</h4> 244 </div> 245 </div> 246 </div> 247 <p> 248 The maximum number of open files has been reached. 249 </p> 250 </div> 251 </div> 252 <div class="sect2" lang="en" xml:lang="en"> 253 <div class="titlepage"> 254 <div> 255 <div> 256 <h3 class="title"><a id="id1694640"></a>Class</h3> 257 </div> 258 </div> 259 </div> 260 <p> 261 <a class="link" href="env.html" title="Chapter 5. The DbEnv Handle">DbEnv</a>, <a class="link" href="memp.html" title="Chapter 9. The DbMpoolFile Handle">DbMpoolFile</a> 262 </p> 263 </div> 264 <div class="sect2" lang="en" xml:lang="en"> 265 <div class="titlepage"> 266 <div> 267 <div> 268 <h3 class="title"><a id="id1694397"></a>See Also</h3> 269 </div> 270 </div> 271 </div> 272 <p> 273 <a class="xref" href="memp.html#memplist" title="Memory Pools and Related Methods">Memory Pools and Related Methods</a> 274 </p> 275 </div> 276 </div> 277 <div class="navfooter"> 278 <hr /> 279 <table width="100%" summary="Navigation footer"> 280 <tr> 281 <td width="40%" align="left"><a accesskey="p" href="mempfget.html">Prev</a> </td> 282 <td width="20%" align="center"> 283 <a accesskey="u" href="memp.html">Up</a> 284 </td> 285 <td width="40%" align="right"> <a accesskey="n" href="mempput.html">Next</a></td> 286 </tr> 287 <tr> 288 <td width="40%" align="left" valign="top">DbMpoolFile::get() </td> 289 <td width="20%" align="center"> 290 <a accesskey="h" href="index.html">Home</a> 291 </td> 292 <td width="40%" align="right" valign="top"> DbMpoolFile::put()</td> 293 </tr> 294 </table> 295 </div> 296 </body> 297</html> 298