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