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::lock_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="lock.html" title="Chapter 7. The DbLock Handle" /> 11 <link rel="prev" href="lockdetect.html" title="DbEnv::lock_detect()" /> 12 <link rel="next" href="lockid.html" title="DbEnv::lock_id()" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">DbEnv::lock_get()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="lockdetect.html">Prev</a> </td> 22 <th width="60%" align="center">Chapter 7. 23 The DbLock Handle 24 </th> 25 <td width="20%" align="right"> <a accesskey="n" href="lockid.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="lockget"></a>DbEnv::lock_get()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db_cxx.h> 39 40int 41DbEnv::lock_get(u_int32_t locker, u_int32_t flags, 42 const Dbt *object, const db_lockmode_t lock_mode, DbLock *lock);</pre> 43 <p> 44 The <code class="methodname">DbEnv::lock_get()</code> method acquires a lock from the lock table, 45 returning information about it in the <span class="bold"><strong>lock</strong></span> parameter. 46 </p> 47 <p> 48 The <code class="methodname">DbEnv::lock_get()</code> <span> 49 50 <span> 51 method either returns a non-zero error value or throws an 52 exception that encapsulates a non-zero error value on 53 failure, and returns 0 on success. 54 </span> 55 </span> 56 </p> 57 <div class="sect2" lang="en" xml:lang="en"> 58 <div class="titlepage"> 59 <div> 60 <div> 61 <h3 class="title"><a id="id1681320"></a>Parameters</h3> 62 </div> 63 </div> 64 </div> 65 <div class="sect3" lang="en" xml:lang="en"> 66 <div class="titlepage"> 67 <div> 68 <div> 69 <h4 class="title"><a id="id1680927"></a>locker</h4> 70 </div> 71 </div> 72 </div> 73 <p> 74 The <span class="bold"><strong>locker</strong></span> parameter is an unsigned 75 32-bit integer quantity. It represents the entity requesting the 76 lock. 77 </p> 78 </div> 79 <div class="sect3" lang="en" xml:lang="en"> 80 <div class="titlepage"> 81 <div> 82 <div> 83 <h4 class="title"><a id="id1680928"></a>flags</h4> 84 </div> 85 </div> 86 </div> 87 <p> 88 The <span class="bold"><strong>flags</strong></span> parameter must be set to 0 89 or the following value: 90 </p> 91 <div class="itemizedlist"> 92 <ul type="disc"> 93 <li> 94 <p><a id="get_DB_LOCK_NOWAIT"></a> 95 <code class="literal">DB_LOCK_NOWAIT</code> 96 </p> 97 <p> 98 If a lock cannot be granted because the requested lock conflicts with 99 an existing lock, return DB_LOCK_NOTGRANTED immediately instead of 100 waiting for the lock to become available. 101 </p> 102 </li> 103 </ul> 104 </div> 105 </div> 106 <div class="sect3" lang="en" xml:lang="en"> 107 <div class="titlepage"> 108 <div> 109 <div> 110 <h4 class="title"><a id="id1680951"></a>object</h4> 111 </div> 112 </div> 113 </div> 114 <p> 115 The <span class="bold"><strong>object</strong></span> parameter is an untyped 116 byte string that specifies the object to be locked. Applications 117 using the locking subsystem directly while also doing locking via the 118 Berkeley DB access methods must take care not to inadvertently lock 119 objects that happen to be equal to the unique file IDs used to lock 120 files. See <a href="../../programmer_reference/lock_am_conv.html" class="olink">Access method 121 locking conventions</a> in the <em class="citetitle">Berkeley DB Programmer's Reference Guide</em> 122 for more information. 123 </p> 124 </div> 125 <div class="sect3" lang="en" xml:lang="en"> 126 <div class="titlepage"> 127 <div> 128 <div> 129 <h4 class="title"><a id="id1681450"></a>lock_mode</h4> 130 </div> 131 </div> 132 </div> 133 <p> 134 The <span class="bold"><strong>lock_mode</strong></span> parameter is used as an 135 index into the environment's lock conflict matrix. When using the 136 default lock conflict matrix, <span class="bold"><strong>lock_mode</strong></span> must be set to one of the following 137 values: 138 </p> 139 <div class="itemizedlist"> 140 <ul type="disc"> 141 <li> 142 <p> 143 <code class="literal">DB_LOCK_READ</code> 144 </p> 145 <p> 146 read (shared) 147 </p> 148 </li> 149 <li> 150 <p> 151 <code class="literal">DB_LOCK_WRITE</code> 152 </p> 153 <p> 154 write (exclusive) 155 </p> 156 </li> 157 <li> 158 <p> 159 <code class="literal">DB_LOCK_IWRITE</code> 160 </p> 161 <p> 162 intention to write (shared) 163 </p> 164 </li> 165 <li> 166 <p> 167 <code class="literal">DB_LOCK_IREAD</code> 168 </p> 169 <p> 170 intention to read (shared) 171 </p> 172 </li> 173 <li> 174 <p> 175 <code class="literal">DB_LOCK_IWR</code> 176 </p> 177 <p> 178 intention to read and write (shared) 179 </p> 180 </li> 181 </ul> 182 </div> 183 <p> 184 See <a class="xref" href="envset_lk_conflicts.html" title="DbEnv::set_lk_conflicts()">DbEnv::set_lk_conflicts()</a> 185 and <a href="../../programmer_reference/lock_stdmode.html" class="olink">Standard Lock Modes</a> 186 for more information on the lock conflict matrix. 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="id1681590"></a>lock</h4> 194 </div> 195 </div> 196 </div> 197 <p> 198 The <code class="methodname">DbEnv::lock_get()</code> 199 method returns the lock information in <span class="bold"><strong>lock</strong></span>. 200 </p> 201 </div> 202 </div> 203 <div class="sect2" lang="en" xml:lang="en"> 204 <div class="titlepage"> 205 <div> 206 <div> 207 <h3 class="title"><a id="id1681679"></a>Errors</h3> 208 </div> 209 </div> 210 </div> 211 <p> 212 The <code class="methodname">DbEnv::lock_get()</code> <span> 213 214 <span> 215 method may fail and throw a <a class="link" href="dbexception.html" title="Chapter 6. The DbException Class">DbException</a> 216 exception, encapsulating one of the following non-zero errors, or return one 217 of the following non-zero errors: 218 </span> 219 </span> 220 </p> 221 <div class="sect3" lang="en" xml:lang="en"> 222 <div class="titlepage"> 223 <div> 224 <div> 225 <h4 class="title"><a id="id1680826"></a><span>DbDeadlockException or </span>DB_LOCK_DEADLOCK</h4> 226 </div> 227 </div> 228 </div> 229 <p> 230 A transactional database environment operation was selected to resolve 231 a deadlock. 232 </p> 233 <p> 234 <a class="xref" href="dbdeadlock.html" title="DbDeadlockException">DbDeadlockException</a> is thrown if 235 your Berkeley DB API is configured to throw exceptions. 236 Otherwise, <code class="literal">DB_LOCK_DEADLOCK</code> is returned. 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="id1681305"></a><span>DbLockNotGrantedException or </span>DB_LOCK_NOTGRANTED</h4> 244 </div> 245 </div> 246 </div> 247 <p> 248 A Berkeley DB Concurrent Data Store database environment configured 249 for lock timeouts was unable to grant a lock in the allowed time. 250 </p> 251 <p> 252 <a class="xref" href="dblocknotgranted.html" title="DbLockNotGrantedException">DbLockNotGrantedException</a> is thrown if 253 your Berkeley DB API is configured to throw exceptions. 254 Otherwise, <code class="literal">DB_LOCK_NOTGRANTED</code> is returned. 255 </p> 256 </div> 257 <div class="sect3" lang="en" xml:lang="en"> 258 <div class="titlepage"> 259 <div> 260 <div> 261 <h4 class="title"><a id="id1681513"></a><span>DbLockNotGrantedException or </span>DB_LOCK_NOTGRANTED</h4> 262 </div> 263 </div> 264 </div> 265 <p> 266 The <a class="link" href="lockvec.html#vec_DB_LOCK_NOWAIT">DB_LOCK_NOWAIT</a> 267 flag or lock timers were configured and the lock could not be granted 268 before the wait-time expired. 269 </p> 270 <p> 271 <a class="xref" href="dblocknotgranted.html" title="DbLockNotGrantedException">DbLockNotGrantedException</a> is thrown if 272 your Berkeley DB API is configured to throw exceptions. 273 Otherwise, <code class="literal">DB_LOCK_NOTGRANTED</code> is returned. 274 </p> 275 </div> 276 <div class="sect3" lang="en" xml:lang="en"> 277 <div class="titlepage"> 278 <div> 279 <div> 280 <h4 class="title"><a id="id1681285"></a>EINVAL</h4> 281 </div> 282 </div> 283 </div> 284 <p> 285 An invalid flag value or parameter was specified. 286 </p> 287 </div> 288 <div class="sect3" lang="en" xml:lang="en"> 289 <div class="titlepage"> 290 <div> 291 <div> 292 <h4 class="title"><a id="id1681743"></a>EINVAL</h4> 293 </div> 294 </div> 295 </div> 296 <p> 297 The method was called on an environment which had been 298 opened without being configured for locking. 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="id1681288"></a>ENOMEM</h4> 306 </div> 307 </div> 308 </div> 309 <p> 310 The maximum number of locks has been reached. 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="id1681440"></a>Class</h3> 319 </div> 320 </div> 321 </div> 322 <p> 323 <a class="link" href="env.html" title="Chapter 5. The DbEnv Handle">DbEnv</a>, 324 <a class="link" href="lock.html" title="Chapter 7. The DbLock Handle">DbLock</a> 325 </p> 326 </div> 327 <div class="sect2" lang="en" xml:lang="en"> 328 <div class="titlepage"> 329 <div> 330 <div> 331 <h3 class="title"><a id="id1681386"></a>See Also</h3> 332 </div> 333 </div> 334 </div> 335 <p> 336 <a class="xref" href="lock.html#locklist" title="Locking Subsystem and Related Methods">Locking Subsystem and Related Methods</a> 337 </p> 338 </div> 339 </div> 340 <div class="navfooter"> 341 <hr /> 342 <table width="100%" summary="Navigation footer"> 343 <tr> 344 <td width="40%" align="left"><a accesskey="p" href="lockdetect.html">Prev</a> </td> 345 <td width="20%" align="center"> 346 <a accesskey="u" href="lock.html">Up</a> 347 </td> 348 <td width="40%" align="right"> <a accesskey="n" href="lockid.html">Next</a></td> 349 </tr> 350 <tr> 351 <td width="40%" align="left" valign="top">DbEnv::lock_detect() </td> 352 <td width="20%" align="center"> 353 <a accesskey="h" href="index.html">Home</a> 354 </td> 355 <td width="40%" align="right" valign="top"> DbEnv::lock_id()</td> 356 </tr> 357 </table> 358 </div> 359 </body> 360</html> 361