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_vec()</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="lockstat_print.html" title="DB_ENV->lock_stat_print()" /> 12 <link rel="next" href="lsn.html" title="Chapter��7.�� The DB_LSN Handle" /> 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_vec()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="lockstat_print.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="lsn.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="lockvec"></a>DB_ENV->lock_vec()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db.h> 39 40int 41DB_ENV->lock_vec(DB_ENV *env, u_int32_t locker, u_int32_t flags, 42 DB_LOCKREQ list[], int nlist, DB_LOCKREQ **elistp); </pre> 43 <p> 44 The <code class="methodname">DB_ENV->lock_vec()</code> method atomically obtains and releases one or 45 more locks from the lock table. The <code class="methodname">DB_ENV->lock_vec()</code> method is 46 intended to support acquisition or trading of multiple locks under one 47 lock table semaphore, as is needed for lock coupling or in 48 multigranularity locking for lock escalation. 49 </p> 50 <p> 51 If any of the requested locks cannot be acquired, or any of the locks 52 to be released cannot be released, the operations before the failing 53 operation are guaranteed to have completed successfully, and 54 <code class="methodname">DB_ENV->lock_vec()</code> returns a non-zero value. In addition, if 55 <span class="bold"><strong>elistp</strong></span> is not NULL, it is set to 56 point to the DB_LOCKREQ entry that was being processed when the error 57 occurred. 58 </p> 59 <p> 60 Unless otherwise specified, the <code class="methodname">DB_ENV->lock_vec()</code> <span> 61 <span> 62 method returns a non-zero error value on failure and 0 on success. 63 </span> 64 65 </span> 66 </p> 67 <div class="sect2" lang="en" xml:lang="en"> 68 <div class="titlepage"> 69 <div> 70 <div> 71 <h3 class="title"><a id="id1679321"></a>Parameters</h3> 72 </div> 73 </div> 74 </div> 75 <div class="sect3" lang="en" xml:lang="en"> 76 <div class="titlepage"> 77 <div> 78 <div> 79 <h4 class="title"><a id="id1678958"></a>elistp</h4> 80 </div> 81 </div> 82 </div> 83 <p> 84 If an error occurs, and the <span class="bold"><strong>elistp</strong></span> 85 parameter is non-NULL, it is set to point to the DB_LOCKREQ entry that 86 was being processed when the error occurred. 87 </p> 88 </div> 89 <div class="sect3" lang="en" xml:lang="en"> 90 <div class="titlepage"> 91 <div> 92 <div> 93 <h4 class="title"><a id="id1679335"></a>flags</h4> 94 </div> 95 </div> 96 </div> 97 <p> 98 The <span class="bold"><strong>flags</strong></span> parameter must be set to 0 99 or the following value: 100 </p> 101 <div class="itemizedlist"> 102 <ul type="disc"> 103 <li> 104 <p><a id="vec_DB_LOCK_NOWAIT"></a> 105 <code class="literal">DB_LOCK_NOWAIT</code> 106 </p> 107 <p> 108 If a lock cannot be granted because the requested lock conflicts with 109 an existing lock, return DB_LOCK_NOTGRANTED immediately instead of 110 waiting for the lock to become available. In this case, if non-NULL, 111 <span class="bold"><strong>elistp</strong></span> identifies the request that 112 was not granted. 113 </p> 114 </li> 115 </ul> 116 </div> 117 </div> 118 <div class="sect3" lang="en" xml:lang="en"> 119 <div class="titlepage"> 120 <div> 121 <div> 122 <h4 class="title"><a id="id1679017"></a>locker</h4> 123 </div> 124 </div> 125 </div> 126 <p> 127 The <span class="bold"><strong>locker</strong></span> parameter is an unsigned 128 32-bit integer quantity. It represents the entity requesting or 129 releasing the lock. 130 </p> 131 </div> 132 <div class="sect3" lang="en" xml:lang="en"> 133 <div class="titlepage"> 134 <div> 135 <div> 136 <h4 class="title"><a id="id1679509"></a>list</h4> 137 </div> 138 </div> 139 </div> 140 <p> 141 The <span class="bold"><strong>list</strong></span> array provided to 142 <code class="methodname">DB_ENV->lock_vec()</code> is typedef'd as DB_LOCKREQ. 143 </p> 144 <p> 145 To ensure compatibility with future releases of Berkeley DB, all 146 fields of the DB_LOCKREQ structure that are not explicitly set should 147 be initialized to 0 before the first time the structure is used. Do 148 this by declaring the structure external or static, or by calling 149 <span class="bold"><strong>memset</strong></span>(3). 150 </p> 151 <p> 152 A DB_LOCKREQ structure has at least the following fields: 153 </p> 154 <div class="itemizedlist"> 155 <ul type="disc"> 156 <li> 157 <p><a id="vec_op"></a> 158 <code class="literal">lockop_t op;</code> 159 </p> 160 <p> 161 The operation to be performed, which must be set to one of the 162 following values: 163 </p> 164 <div class="itemizedlist"> 165 <ul type="circle"> 166 <li> 167 <p><a id="vec_DB_LOCK_GET"></a> 168 <code class="literal">DB_LOCK_GET</code> 169 </p> 170 <p> 171 Get the lock defined by the values of the <span class="bold"><strong>mode</strong></span> and <span class="bold"><strong>obj</strong></span> 172 structure fields, for the specified 173 <span class="bold"><strong>locker</strong></span>. 174 Upon return from <code class="methodname">DB_ENV->lock_vec()</code>, 175 if the <span class="bold"><strong>lock</strong></span> field is non-NULL, a 176 reference to the acquired lock is stored there. (This reference is 177 invalidated by any call to <code class="methodname">DB_ENV->lock_vec()</code> or 178 <a class="xref" href="lockput.html" title="DB_ENV->lock_put()">DB_ENV->lock_put()</a> that releases 179 the lock.) 180 </p> 181 </li> 182 <li> 183 <p><a id="vec_DB_LOCK_GET_TIMEOUT"></a> 184 <code class="literal">DB_LOCK_GET_TIMEOUT</code> 185 </p> 186 <p> 187 Identical to DB_LOCK_GET except that the value in the <span class="bold"><strong>timeout</strong></span> structure field overrides any 188 previously specified timeout value for this lock. A value of 0 turns 189 off any previously specified timeout. 190 </p> 191 </li> 192 <li> 193 <p><a id="vec_DB_LOCK_PUT"></a> 194 <code class="literal">DB_LOCK_PUT</code> 195 </p> 196 <p> 197 The lock to which the <span class="bold"><strong>lock</strong></span> structure 198 field refers is released. The <span class="bold"><strong>locker</strong></span> 199 parameter, and <span class="bold"><strong>mode</strong></span> and <span class="bold"><strong>obj</strong></span> fields are ignored. 200 </p> 201 </li> 202 <li> 203 <p><a id="vec_DB_LOCK_PUT_ALL"></a> 204 <code class="literal">DB_LOCK_PUT_ALL</code> 205 </p> 206 <p> 207 All locks held by the specified <span class="bold"><strong>locker</strong></span> are released. The <span class="bold"><strong>lock</strong></span>, <span class="bold"><strong>mode</strong></span>, 208 and <span class="bold"><strong>obj</strong></span> structure fields are ignored. 209 Locks acquired in operations performed by the current call to 210 <code class="methodname">DB_ENV->lock_vec()</code> which appear before the DB_LOCK_PUT_ALL operation 211 are released; those acquired in operations appearing after the 212 DB_LOCK_PUT_ALL operation are not released. 213 </p> 214 </li> 215 <li> 216 <p><a id="vec_DB_LOCK_PUT_OBJ"></a> 217 <code class="literal">DB_LOCK_PUT_OBJ</code> 218 </p> 219 <p> 220 All locks held on <span class="bold"><strong>obj</strong></span> are released. 221 The <span class="bold"><strong>locker</strong></span> parameter and the 222 <span class="bold"><strong>lock</strong></span> and <span class="bold"><strong>mode</strong></span> structure fields are ignored. Locks 223 acquired in operations performed by the current call to 224 <code class="methodname">DB_ENV->lock_vec()</code> that appear before the DB_LOCK_PUT_OBJ operation 225 are released; those acquired in operations appearing after the 226 DB_LOCK_PUT_OBJ operation are not released. 227 </p> 228 </li> 229 <li> 230 <p><a id="vec_DB_LOCK_TIMEOUT"></a> 231 <code class="literal">DB_LOCK_TIMEOUT</code> 232 </p> 233 <p> 234 Cause the specified <span class="bold"><strong>locker</strong></span> to timeout 235 immediately. If the database environment has not configured automatic 236 deadlock detection, the transaction will timeout the next time 237 deadlock detection is performed. As transactions acquire locks on 238 behalf of a single locker ID, timing out the locker ID associated with 239 a transaction will time out the transaction itself. 240 </p> 241 </li> 242 </ul> 243 </div> 244 </li> 245 <li> 246 <p><a id="vec_lock"></a> 247 <code class="literal">DB_LOCK lock;</code> 248 </p> 249 <p> 250 A lock reference. 251 </p> 252 </li> 253 <li> 254 <p><a id="vec_mode"></a> 255 <code class="literal">const lockmode_t mode;</code> 256 </p> 257 <p> 258 The lock mode, used as an index into the environment's lock conflict 259 matrix. When using the default lock conflict matrix, <span class="bold"><strong>mode</strong></span> must be set to one of the following 260 values: 261 </p> 262 <div class="itemizedlist"> 263 <ul type="circle"> 264 <li> 265 <p><a id="vec_DB_LOCK_READ"></a> 266 <code class="literal">DB_LOCK_READ</code> 267 </p> 268 <p> 269 read (shared) 270 </p> 271 </li> 272 <li> 273 <p><a id="vec_DB_LOCK_WRITE"></a> 274 <code class="literal">DB_LOCK_WRITE</code> 275 </p> 276 <p> 277 write (exclusive) 278 </p> 279 </li> 280 <li> 281 <p><a id="vec_DB_LOCK_IWRITE"></a> 282 <code class="literal">DB_LOCK_IWRITE</code> 283 </p> 284 <p> 285 intention to write (shared) 286 </p> 287 </li> 288 <li> 289 <p><a id="vec_DB_LOCK_IREAD"></a> 290 <code class="literal">DB_LOCK_IREAD</code> 291 </p> 292 <p> 293 intention to read (shared) 294 </p> 295 </li> 296 <li> 297 <p><a id="vec_DB_LOCK_IWR"></a> 298 <code class="literal">DB_LOCK_IWR</code> 299 </p> 300 <p> 301 intention to read and write (shared) 302 </p> 303 </li> 304 </ul> 305 </div> 306 <p> 307 See <a class="xref" href="envset_lk_conflicts.html" title="DB_ENV->set_lk_conflicts()">DB_ENV->set_lk_conflicts()</a> 308 and <a href="../../programmer_reference/lock_stdmode.html" class="olink">Standard Lock Modes</a> 309 for more information on the lock conflict matrix. 310 </p> 311 </li> 312 <li> 313 <p> 314 <span class="bold"><a id="obj"></a><strong>const DBT obj;</strong></span> 315 </p> 316 <p> 317 An untyped byte string that specifies the object to be locked or 318 released. Applications using the locking subsystem directly while 319 also doing locking via the Berkeley DB access methods must take care 320 not to inadvertently lock objects that happen to be equal to the 321 unique file IDs used to lock files. See 322 <a href="../../programmer_reference/lock_am_conv.html" class="olink">Access method locking 323 conventions</a> in the 324 <em class="citetitle">Berkeley DB Programmer's Reference Guide</em> for more information. 325 </p> 326 </li> 327 <li> 328 <p> 329 <span class="bold"><strong>u_int32_t timeout;</strong></span> 330 </p> 331 <p> 332 The lock timeout value. 333 </p> 334 </li> 335 </ul> 336 </div> 337 </div> 338 <div class="sect3" lang="en" xml:lang="en"> 339 <div class="titlepage"> 340 <div> 341 <div> 342 <h4 class="title"><a id="id1679972"></a>nlist</h4> 343 </div> 344 </div> 345 </div> 346 <p> 347 The <span class="bold"><strong>nlist</strong></span> parameter specifies the 348 number of elements in the <span class="bold"><strong>list</strong></span> array. 349 </p> 350 </div> 351 </div> 352 <div class="sect2" lang="en" xml:lang="en"> 353 <div class="titlepage"> 354 <div> 355 <div> 356 <h3 class="title"><a id="id1680096"></a>Errors</h3> 357 </div> 358 </div> 359 </div> 360 <p> 361 The <code class="methodname">DB_ENV->lock_vec()</code> <span> 362 <span> 363 method may fail and return one of the following non-zero errors: 364 </span> 365 366 </span> 367 </p> 368 <div class="sect3" lang="en" xml:lang="en"> 369 <div class="titlepage"> 370 <div> 371 <div> 372 <h4 class="title"><a id="id1679525"></a>DB_LOCK_DEADLOCK</h4> 373 </div> 374 </div> 375 </div> 376 <p> 377 A transactional database environment operation was selected to resolve 378 a deadlock. 379 </p> 380 </div> 381 <div class="sect3" lang="en" xml:lang="en"> 382 <div class="titlepage"> 383 <div> 384 <div> 385 <h4 class="title"><a id="id1679668"></a>DB_LOCK_NOTGRANTED</h4> 386 </div> 387 </div> 388 </div> 389 <p> 390 A Berkeley DB Concurrent Data Store database environment configured 391 for lock timeouts was unable to grant a lock in the allowed time. 392 </p> 393 </div> 394 <div class="sect3" lang="en" xml:lang="en"> 395 <div class="titlepage"> 396 <div> 397 <div> 398 <h4 class="title"><a id="id1679658"></a>DB_LOCK_NOTGRANTED</h4> 399 </div> 400 </div> 401 </div> 402 <p> 403 The <a class="link" href="lockvec.html#vec_DB_LOCK_NOWAIT">DB_LOCK_NOWAIT</a> 404 flag or lock timers were configured and the lock could not be granted 405 before the wait-time expired. 406 </p> 407 </div> 408 <div class="sect3" lang="en" xml:lang="en"> 409 <div class="titlepage"> 410 <div> 411 <div> 412 <h4 class="title"><a id="id1679396"></a>EINVAL</h4> 413 </div> 414 </div> 415 </div> 416 <p> 417 An invalid flag value or parameter was specified. 418 </p> 419 </div> 420 <div class="sect3" lang="en" xml:lang="en"> 421 <div class="titlepage"> 422 <div> 423 <div> 424 <h4 class="title"><a id="id1679625"></a>ENOMEM</h4> 425 </div> 426 </div> 427 </div> 428 <p> 429 The maximum number of locks has been reached. 430 </p> 431 </div> 432 </div> 433 <div class="sect2" lang="en" xml:lang="en"> 434 <div class="titlepage"> 435 <div> 436 <div> 437 <h3 class="title"><a id="id1679316"></a>Class</h3> 438 </div> 439 </div> 440 </div> 441 <p> 442 <a class="link" href="env.html" title="Chapter��5.�� The DB_ENV Handle">DB_ENV</a>, 443 <a class="link" href="lock.html" title="Chapter��6.�� The DB_LOCK Handle">DB_LOCK</a> 444 </p> 445 </div> 446 <div class="sect2" lang="en" xml:lang="en"> 447 <div class="titlepage"> 448 <div> 449 <div> 450 <h3 class="title"><a id="id1679348"></a>See Also</h3> 451 </div> 452 </div> 453 </div> 454 <p> 455 <a class="xref" href="lock.html#locklist" title="Locking Subsystem and Related Methods">Locking Subsystem and Related Methods</a> 456 </p> 457 </div> 458 </div> 459 <div class="navfooter"> 460 <hr /> 461 <table width="100%" summary="Navigation footer"> 462 <tr> 463 <td width="40%" align="left"><a accesskey="p" href="lockstat_print.html">Prev</a>��</td> 464 <td width="20%" align="center"> 465 <a accesskey="u" href="lock.html">Up</a> 466 </td> 467 <td width="40%" align="right">��<a accesskey="n" href="lsn.html">Next</a></td> 468 </tr> 469 <tr> 470 <td width="40%" align="left" valign="top">DB_ENV->lock_stat_print()��</td> 471 <td width="20%" align="center"> 472 <a accesskey="h" href="index.html">Home</a> 473 </td> 474 <td width="40%" align="right" valign="top">��Chapter��7.�� 475 The DB_LSN Handle 476 </td> 477 </tr> 478 </table> 479 </div> 480 </body> 481</html> 482