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