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_stat()</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="lockput.html" title="DB_ENV->lock_put()" /> 12 <link rel="next" href="lockstat_print.html" title="DB_ENV->lock_stat_print()" /> 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_stat()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="lockput.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="lockstat_print.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="lockstat"></a>DB_ENV->lock_stat()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db.h> 39 40int 41DB_ENV->lock_stat(DB_ENV *env, DB_LOCK_STAT **statp, u_int32_t flags); </pre> 42 <p> 43 The <code class="methodname">DB_ENV->lock_stat()</code> method returns the locking subsystem 44 statistics. 45 </p> 46 <p> 47 The <code class="methodname">DB_ENV->lock_stat()</code> method creates a statistical structure of 48 type DB_LOCK_STAT and copies a pointer to it into a user-specified 49 memory location. 50 </p> 51 <p> 52 Statistical structures are stored in allocated memory. If 53 application-specific allocation routines have been declared (see 54 <a class="xref" href="envset_alloc.html" title="DB_ENV->set_alloc()">DB_ENV->set_alloc()</a> 55 for more information), they are used to allocate the memory; 56 otherwise, the standard C library <span class="bold"><strong>malloc</strong></span>(3) is used. The caller is responsible 57 for deallocating the memory. To deallocate the memory, free the 58 memory reference; references inside the returned memory need not be 59 individually freed. 60 </p> 61 <p> 62 The following DB_LOCK_STAT fields will be filled in: 63 </p> 64 <div class="itemizedlist"> 65 <ul type="disc"> 66 <li> 67 <p> 68 <span class="bold"><strong>u_int32_t st_id;</strong></span> 69 </p> 70 <p> 71 The last allocated locker ID. 72 </p> 73 </li> 74 <li> 75 <p> 76 <span class="bold"><strong>u_int32_t st_cur_maxid;</strong></span> 77 </p> 78 <p> 79 The current maximum unused locker ID. 80 </p> 81 </li> 82 <li> 83 <p> 84 <span class="bold"><strong>int st_nmodes;</strong></span> 85 </p> 86 <p> 87 The number of lock modes. 88 </p> 89 </li> 90 <li> 91 <p> 92 <span class="bold"><strong>u_int32_t st_maxlocks;</strong></span> 93 </p> 94 <p> 95 The maximum number of locks possible. 96 </p> 97 </li> 98 <li> 99 <p> 100 <span class="bold"><strong>u_int32_t st_maxlockers;</strong></span> 101 </p> 102 <p> 103 The maximum number of lockers possible. 104 </p> 105 </li> 106 <li> 107 <p> 108 <span class="bold"><strong>u_int32_t st_maxobjects;</strong></span> 109 </p> 110 <p> 111 The maximum number of lock objects possible. 112 </p> 113 </li> 114 <li> 115 <p> 116 <span class="bold"><strong>u_int32_t st_partitions;</strong></span> 117 </p> 118 <p> 119 The number of lock table partitions. 120 </p> 121 </li> 122 <li> 123 <p> 124 <span class="bold"><strong>u_int32_t st_nlocks;</strong></span> 125 </p> 126 <p> 127 The number of current locks. 128 </p> 129 </li> 130 <li> 131 <p> 132 <span class="bold"><strong>u_int32_t st_maxnlocks;</strong></span> 133 </p> 134 <p> 135 The maximum number of locks at any one time. Note that if there is 136 more than one partition, this is the sum of the maximum across all 137 partitions. 138 </p> 139 </li> 140 <li> 141 <p> 142 <span class="bold"><strong>u_int32_t st_maxhlocks;</strong></span> 143 </p> 144 <p> 145 The maximum number of locks in any hash bucket at any one time. 146 </p> 147 </li> 148 <li> 149 <p> 150 <span class="bold"><strong>uintmax_t st_locksteals;</strong></span> 151 </p> 152 <p> 153 The maximum number of locks stolen by an empty partition. 154 </p> 155 </li> 156 <li> 157 <p> 158 <span class="bold"><strong>uintmax_t st_maxlsteals;</strong></span> 159 </p> 160 <p> 161 The maximum number of lock steals for any one partition. 162 </p> 163 </li> 164 <li> 165 <p> 166 <span class="bold"><strong>u_int32_t st_nlockers;</strong></span> 167 </p> 168 <p> 169 The number of current lockers. 170 </p> 171 </li> 172 <li> 173 <p> 174 <span class="bold"><strong>u_int32_t st_maxnlockers;</strong></span> 175 </p> 176 <p> 177 The maximum number of lockers at any one time. 178 </p> 179 </li> 180 <li> 181 <p> 182 <span class="bold"><strong>u_int32_t st_nobjects;</strong></span> 183 </p> 184 <p> 185 The number of current lock objects. 186 </p> 187 </li> 188 <li> 189 <p> 190 <span class="bold"><strong>u_int32_t st_maxnobjects;</strong></span> 191 </p> 192 <p> 193 The maximum number of lock objects at any one time. Note that if there 194 is more than one partition this is the sum of the maximum across all 195 partitions. 196 </p> 197 </li> 198 <li> 199 <p> 200 <span class="bold"><strong>u_int32_t st_maxhobjects;</strong></span> 201 </p> 202 <p> 203 The maximum number of objects in any hash bucket at any one time. 204 </p> 205 </li> 206 <li> 207 <p> 208 <span class="bold"><strong>uintmax_t st_objectsteals;</strong></span> 209 </p> 210 <p> 211 The maximum number of objects stolen by an empty partition. 212 </p> 213 </li> 214 <li> 215 <p> 216 <span class="bold"><strong>uintmax_t st_maxosteals;</strong></span> 217 </p> 218 <p> 219 The maximum number of object steals for any one partition. 220 </p> 221 </li> 222 <li> 223 <p> 224 <span class="bold"><strong>uintmax_t st_nrequests;</strong></span> 225 </p> 226 <p> 227 The total number of locks requested. 228 </p> 229 </li> 230 <li> 231 <p> 232 <span class="bold"><strong>uintmax_t st_nreleases;</strong></span> 233 </p> 234 <p> 235 The total number of locks released. 236 </p> 237 </li> 238 <li> 239 <p> 240 <span class="bold"><strong>uintmax_t st_nupgrade;</strong></span> 241 </p> 242 <p> 243 The total number of locks upgraded. 244 </p> 245 </li> 246 <li> 247 <p> 248 <span class="bold"><strong>uintmax_t st_ndowngrade;</strong></span> 249 </p> 250 <p> 251 The total number of locks downgraded. 252 </p> 253 </li> 254 <li> 255 <p> 256 <span class="bold"><strong>uintmax_t st_lock_wait;</strong></span> 257 </p> 258 <p> 259 The number of lock requests not immediately available due to 260 conflicts, for which the thread of control waited. 261 </p> 262 </li> 263 <li> 264 <p> 265 <span class="bold"><strong>uintmax_t st_lock_nowait;</strong></span> 266 </p> 267 <p> 268 The number of lock requests not immediately available due to 269 conflicts, for which the thread of control did not wait. 270 </p> 271 </li> 272 <li> 273 <p> 274 <span class="bold"><strong>uintmax_t st_ndeadlocks;</strong></span> 275 </p> 276 <p> 277 The number of deadlocks. 278 </p> 279 </li> 280 <li> 281 <p> 282 <span class="bold"><strong>db_timeout_t st_locktimeout;</strong></span> 283 </p> 284 <p> 285 Lock timeout value. 286 </p> 287 </li> 288 <li> 289 <p> 290 <span class="bold"><strong>uintmax_t st_nlocktimeouts;</strong></span> 291 </p> 292 <p> 293 The number of lock requests that have timed out. 294 </p> 295 </li> 296 <li> 297 <p> 298 <span class="bold"><strong>u_int32_t st_txntimeout;</strong></span> 299 </p> 300 <p> 301 Transaction timeout value. 302 </p> 303 </li> 304 <li> 305 <p> 306 <span class="bold"><strong>uintmax_t st_ntxntimeouts;</strong></span> 307 </p> 308 <p> 309 The number of transactions that have timed out. This value is also a 310 component of <span class="bold"><strong>st_ndeadlocks</strong></span>, the total 311 number of deadlocks detected. 312 </p> 313 </li> 314 <li> 315 <p> 316 <span class="bold"><strong>uintmax_t st_objs_wait;</strong></span> 317 </p> 318 <p> 319 The number of requests to allocate or deallocate an object for which 320 the thread of control waited. 321 </p> 322 </li> 323 <li> 324 <p> 325 <span class="bold"><strong>uintmax_t st_objs_nowait;</strong></span> 326 </p> 327 <p> 328 The number of requests to allocate or deallocate an object for which 329 the thread of control did not wait. 330 </p> 331 </li> 332 <li> 333 <p> 334 <span class="bold"><strong>uintmax_t st_lockers_wait;</strong></span> 335 </p> 336 <p> 337 The number of requests to allocate or deallocate a locker for which 338 the thread of control waited. 339 </p> 340 </li> 341 <li> 342 <p> 343 <span class="bold"><strong>uintmax_t st_lockers_nowait;</strong></span> 344 </p> 345 <p> 346 The number of requests to allocate or deallocate a locker for which 347 the thread of control did not wait. 348 </p> 349 </li> 350 <li> 351 <p> 352 <span class="bold"><strong>u_int32_t st_hash_len;</strong></span> 353 </p> 354 <p> 355 Maximum length of a lock hash bucket. 356 </p> 357 </li> 358 <li> 359 <p> 360 <span class="bold"><strong>roff_t st_regsize;</strong></span> 361 </p> 362 <p> 363 The size of the lock region, in bytes. 364 </p> 365 </li> 366 <li> 367 <p> 368 <span class="bold"><strong>uintmax_t st_part_wait;</strong></span> 369 </p> 370 <p> 371 The number of times that a thread of control was forced to wait before 372 obtaining the lock partition mutex. 373 </p> 374 </li> 375 <li> 376 <p> 377 <span class="bold"><strong>uintmax_t st_part_nowait;</strong></span> 378 </p> 379 <p> 380 The number of times that a thread of control was able to obtain the 381 lock partition mutex without waiting. 382 </p> 383 </li> 384 <li> 385 <p> 386 <span class="bold"><strong>uintmax_t st_part_max_wait;</strong></span> 387 </p> 388 <p> 389 The maximum number of times that a thread of control was forced to 390 wait before obtaining any one lock partition mutex. 391 </p> 392 </li> 393 <li> 394 <p> 395 <span class="bold"><strong>uintmax_t st_part_max_nowait;</strong></span> 396 </p> 397 <p> 398 The number of times that a thread of control was able to obtain any 399 one lock partition mutex without waiting. 400 </p> 401 </li> 402 <li> 403 <p> 404 <span class="bold"><strong>uintmax_t st_region_wait;</strong></span> 405 </p> 406 <p> 407 The number of times that a thread of control was forced to wait before 408 obtaining the lock region mutex. 409 </p> 410 </li> 411 <li> 412 <p> 413 <span class="bold"><strong>uintmax_t st_region_nowait;</strong></span> 414 </p> 415 <p> 416 The number of times that a thread of control was able to obtain the 417 lock region mutex without waiting. 418 </p> 419 </li> 420 </ul> 421 </div> 422 <p> 423 The <code class="methodname">DB_ENV->lock_stat()</code> method may not be called before the 424 <a class="xref" href="envopen.html" title="DB_ENV->open()">DB_ENV->open()</a> method is called. 425 </p> 426 <p> 427 The <code class="methodname">DB_ENV->lock_stat()</code> method returns a non-zero error value on 428 failure and 0 on success. 429 </p> 430 <div class="sect2" lang="en" xml:lang="en"> 431 <div class="titlepage"> 432 <div> 433 <div> 434 <h3 class="title"><a id="id1678525"></a>Parameters</h3> 435 </div> 436 </div> 437 </div> 438 <div class="sect3" lang="en" xml:lang="en"> 439 <div class="titlepage"> 440 <div> 441 <div> 442 <h4 class="title"><a id="id1678883"></a>flags</h4> 443 </div> 444 </div> 445 </div> 446 <p> 447 The <span class="bold"><strong>flags</strong></span> parameter must be set to 0 448 or the following value: 449 </p> 450 <div class="itemizedlist"> 451 <ul type="disc"> 452 <li> 453 <p><a id="stat_DB_STAT_CLEAR"></a> 454 <code class="literal">DB_STAT_CLEAR</code> 455 </p> 456 <p> 457 Reset statistics after returning their values. 458 </p> 459 </li> 460 </ul> 461 </div> 462 </div> 463 <div class="sect3" lang="en" xml:lang="en"> 464 <div class="titlepage"> 465 <div> 466 <div> 467 <h4 class="title"><a id="id1678037"></a>statp</h4> 468 </div> 469 </div> 470 </div> 471 <p> 472 The <span class="bold"><strong>statp</strong></span> parameter references memory 473 into which a pointer to the allocated statistics structure is copied. 474 </p> 475 </div> 476 </div> 477 <div class="sect2" lang="en" xml:lang="en"> 478 <div class="titlepage"> 479 <div> 480 <div> 481 <h3 class="title"><a id="id1678909"></a>Errors</h3> 482 </div> 483 </div> 484 </div> 485 <p> 486 The <code class="methodname">DB_ENV->lock_stat()</code> <span> 487 <span> 488 method may fail and return one of the following non-zero errors: 489 </span> 490 491 </span> 492 </p> 493 <div class="sect3" lang="en" xml:lang="en"> 494 <div class="titlepage"> 495 <div> 496 <div> 497 <h4 class="title"><a id="id1677920"></a>EINVAL</h4> 498 </div> 499 </div> 500 </div> 501 <p> 502 An invalid flag value or parameter was specified. 503 </p> 504 </div> 505 </div> 506 <div class="sect2" lang="en" xml:lang="en"> 507 <div class="titlepage"> 508 <div> 509 <div> 510 <h3 class="title"><a id="id1678670"></a>Class</h3> 511 </div> 512 </div> 513 </div> 514 <p> 515 <a class="link" href="env.html" title="Chapter 5. The DB_ENV Handle">DB_ENV</a>, 516 <a class="link" href="lock.html" title="Chapter 6. The DB_LOCK Handle">DB_LOCK</a> 517 </p> 518 </div> 519 <div class="sect2" lang="en" xml:lang="en"> 520 <div class="titlepage"> 521 <div> 522 <div> 523 <h3 class="title"><a id="id1678621"></a>See Also</h3> 524 </div> 525 </div> 526 </div> 527 <p> 528 <a class="xref" href="lock.html#locklist" title="Locking Subsystem and Related Methods">Locking Subsystem and Related Methods</a> 529 </p> 530 </div> 531 </div> 532 <div class="navfooter"> 533 <hr /> 534 <table width="100%" summary="Navigation footer"> 535 <tr> 536 <td width="40%" align="left"><a accesskey="p" href="lockput.html">Prev</a> </td> 537 <td width="20%" align="center"> 538 <a accesskey="u" href="lock.html">Up</a> 539 </td> 540 <td width="40%" align="right"> <a accesskey="n" href="lockstat_print.html">Next</a></td> 541 </tr> 542 <tr> 543 <td width="40%" align="left" valign="top">DB_ENV->lock_put() </td> 544 <td width="20%" align="center"> 545 <a accesskey="h" href="index.html">Home</a> 546 </td> 547 <td width="40%" align="right" valign="top"> DB_ENV->lock_stat_print()</td> 548 </tr> 549 </table> 550 </div> 551 </body> 552</html> 553