docs/api_reference/CXX/lockget.html

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