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->memp_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="memp.html" title="Chapter��8.�� The DB_MPOOLFILE Handle" /> 11 <link rel="prev" href="mempregister.html" title="DB_ENV->memp_register()" /> 12 <link rel="next" href="mempstat_print.html" title="DB_ENV->memp_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->memp_stat()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="mempregister.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��8.�� 23 The DB_MPOOLFILE Handle 24 </th> 25 <td width="20%" align="right">��<a accesskey="n" href="mempstat_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="mempstat"></a>DB_ENV->memp_stat()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db.h> 39 40int 41DB_ENV->memp_stat(DB_ENV *env, DB_MPOOL_STAT **gsp, 42 DB_MPOOL_FSTAT *(*fsp)[], u_int32_t flags); </pre> 43 <p> 44 The <code class="methodname">DB_ENV->memp_stat()</code> method returns the memory pool (that is, the 45 buffer cache) subsystem statistics. 46 </p> 47 <p> 48 The <code class="methodname">DB_ENV->memp_stat()</code> method creates statistical structures of 49 type <code class="literal">DB_MPOOL_STAT</code> and <code class="literal">DB_MPOOL_FSTAT</code>, and copy 50 pointers to them into user-specified memory locations. The cache statistics are stored in 51 the <code class="literal">DB_MPOOL_STAT</code> structure and the per-file cache statistics are stored 52 the <code class="literal">DB_MPOOL_FSTAT</code> structure. 53 </p> 54 <p> 55 Statistical structures are stored in allocated memory. If 56 application-specific allocation routines have been declared (see 57 <a class="xref" href="envset_alloc.html" title="DB_ENV->set_alloc()">DB_ENV->set_alloc()</a> 58 for more information), they are used to allocate the memory; 59 otherwise, the standard C library <span class="bold"><strong>malloc</strong></span>(3) is used. The caller is responsible 60 for deallocating the memory. To deallocate the memory, free the 61 memory reference; references inside the returned memory need not be 62 individually freed. 63 </p> 64 <p> 65 If <span class="bold"><strong>gsp</strong></span> is non-NULL, the global 66 statistics for the cache <span class="bold"><strong>mp</strong></span> are 67 copied into the memory location to which it refers. The following 68 <code class="literal">DB_MPOOL_STAT</code> fields will be filled in: 69 </p> 70 <div class="itemizedlist"> 71 <ul type="disc"> 72 <li> 73 <p> 74 <span class="bold"><strong>u_int32_t st_gbytes;</strong></span> 75 </p> 76 <p> 77 Gigabytes of cache (total cache size is st_gbytes + st_bytes). 78 </p> 79 </li> 80 <li> 81 <p> 82 <span class="bold"><strong>u_int32_t st_bytes;</strong></span> 83 </p> 84 <p> 85 Bytes of cache (total cache size is st_gbytes + st_bytes). 86 </p> 87 </li> 88 <li> 89 <p> 90 <span class="bold"><strong>u_int32_t st_ncache;</strong></span> 91 </p> 92 <p> 93 Number of caches. 94 </p> 95 </li> 96 <li> 97 <p> 98 <span class="bold"><strong>u_int32_t st_max_ncache;</strong></span> 99 </p> 100 <p> 101 Maximum number of caches, as configured with the 102 <a class="xref" href="envset_cache_max.html" title="DB_ENV->set_cache_max()">DB_ENV->set_cache_max()</a> 103 method. 104 </p> 105 </li> 106 <li> 107 <p> 108 <span class="bold"><strong>roff_t st_regsize;</strong></span> 109 </p> 110 <p> 111 Individual cache size, in bytes. 112 </p> 113 </li> 114 <li> 115 <p> 116 <span class="bold"><strong>size_t st_mmapsize;</strong></span> 117 </p> 118 <p> 119 Maximum memory-mapped file size. 120 </p> 121 </li> 122 <li> 123 <p> 124 <span class="bold"><strong>int st_maxopenfd;</strong></span> 125 </p> 126 <p> 127 Maximum open file descriptors. 128 </p> 129 </li> 130 <li> 131 <p> 132 <span class="bold"><strong>int st_maxwrite;</strong></span> 133 </p> 134 <p> 135 Maximum sequential buffer writes. 136 </p> 137 </li> 138 <li> 139 <p> 140 <span class="bold"><strong>db_timeout_t st_maxwrite_sleep;</strong></span> 141 </p> 142 <p> 143 Microseconds to pause after writing maximum sequential buffers. 144 </p> 145 </li> 146 <li> 147 <p> 148 <span class="bold"><strong>u_int32_t st_map;</strong></span> 149 </p> 150 <p> 151 Requested pages mapped into the process' address space (there is no 152 available information about whether or not this request caused disk 153 I/O, although examining the application page fault rate may be 154 helpful). 155 </p> 156 </li> 157 <li> 158 <p> 159 <span class="bold"><strong>uintmax_t st_cache_hit;</strong></span> 160 </p> 161 <p> 162 Requested pages found in the cache. 163 </p> 164 </li> 165 <li> 166 <p> 167 <span class="bold"><strong>uintmax_t st_cache_miss;</strong></span> 168 </p> 169 <p> 170 Requested pages not found in the cache. 171 </p> 172 </li> 173 <li> 174 <p> 175 <span class="bold"><strong>uintmax_t st_page_create;</strong></span> 176 </p> 177 <p> 178 Pages created in the cache. 179 </p> 180 </li> 181 <li> 182 <p> 183 <span class="bold"><strong>uintmax_t st_page_in;</strong></span> 184 </p> 185 <p> 186 Pages read into the cache. 187 </p> 188 </li> 189 <li> 190 <p> 191 <span class="bold"><strong>uintmax_t st_page_out;</strong></span> 192 </p> 193 <p> 194 Pages written from the cache to the backing file. 195 </p> 196 </li> 197 <li> 198 <p> 199 <span class="bold"><strong>uintmax_t st_ro_evict;</strong></span> 200 </p> 201 <p> 202 Clean pages forced from the cache. 203 </p> 204 </li> 205 <li> 206 <p> 207 <span class="bold"><strong>uintmax_t st_rw_evict;</strong></span> 208 </p> 209 <p> 210 Dirty pages forced from the cache. 211 </p> 212 </li> 213 <li> 214 <p> 215 <span class="bold"><strong>uintmax_t st_page_trickle;</strong></span> 216 </p> 217 <p> 218 Dirty pages written using the 219 <a class="xref" href="memptrickle.html" title="DB_ENV->memp_trickle()">DB_ENV->memp_trickle()</a> 220 method. 221 </p> 222 </li> 223 <li> 224 <p> 225 <span class="bold"><strong>u_int32_t st_pages;</strong></span> 226 </p> 227 <p> 228 Pages in the cache. 229 </p> 230 </li> 231 <li> 232 <p> 233 <span class="bold"><strong>uintmax_t st_page_clean;</strong></span> 234 </p> 235 <p> 236 Clean pages currently in the cache. 237 </p> 238 </li> 239 <li> 240 <p> 241 <span class="bold"><strong>uintmax_t st_page_dirty;</strong></span> 242 </p> 243 <p> 244 Dirty pages currently in the cache. 245 </p> 246 </li> 247 <li> 248 <p> 249 <span class="bold"><strong>uintmax_t st_hash_buckets;</strong></span> 250 </p> 251 <p> 252 Number of hash buckets in buffer hash table. 253 </p> 254 </li> 255 <li> 256 <p> 257 <span class="bold"><strong>uintmax_t st_hash_searches;</strong></span> 258 </p> 259 <p> 260 Total number of buffer hash table lookups. 261 </p> 262 </li> 263 <li> 264 <p> 265 <span class="bold"><strong>uintmax_t st_hash_longest;</strong></span> 266 </p> 267 <p> 268 Longest chain ever encountered in buffer hash table lookups. 269 </p> 270 </li> 271 <li> 272 <p> 273 <span class="bold"><strong>uintmax_t st_hash_examined;</strong></span> 274 </p> 275 <p> 276 Total number of hash elements traversed during hash table lookups. 277 </p> 278 </li> 279 <li> 280 <p> 281 <span class="bold"><strong>uintmax_t st_hash_nowait;</strong></span> 282 </p> 283 <p> 284 Number of times that a thread of control was able to obtain a hash 285 bucket lock without waiting. 286 </p> 287 </li> 288 <li> 289 <p> 290 <span class="bold"><strong>uintmax_t st_hash_wait;</strong></span> 291 </p> 292 <p> 293 Number of times that a thread of control was forced to wait before 294 obtaining a hash bucket lock. 295 </p> 296 </li> 297 <li> 298 <p> 299 <span class="bold"><strong>uintmax_t st_hash_max_nowait;</strong></span> 300 </p> 301 <p> 302 The number of times a thread of control was able to obtain the hash 303 bucket lock without waiting on the bucket which had the maximum number 304 of times that a thread of control needed to wait. 305 </p> 306 </li> 307 <li> 308 <p> 309 <span class="bold"><strong>uintmax_t st_hash_max_wait;</strong></span> 310 </p> 311 <p> 312 Maximum number of times any hash bucket lock was waited for by a 313 thread of control. 314 </p> 315 </li> 316 <li> 317 <p> 318 <span class="bold"><strong>uintmax_t st_region_wait;</strong></span> 319 </p> 320 <p> 321 Number of times that a thread of control was forced to wait before 322 obtaining a cache region mutex. 323 </p> 324 </li> 325 <li> 326 <p> 327 <span class="bold"><strong>uintmax_t st_region_nowait;</strong></span> 328 </p> 329 <p> 330 Number of times that a thread of control was able to obtain a cache 331 region mutex without waiting. 332 </p> 333 </li> 334 <li> 335 <p> 336 <span class="bold"><strong>uintmax_t st_mvcc_frozen;</strong></span> 337 </p> 338 <p> 339 Number of buffers frozen. 340 </p> 341 </li> 342 <li> 343 <p> 344 <span class="bold"><strong>uintmax_t st_mvcc_thawed;</strong></span> 345 </p> 346 <p> 347 Number of buffers thawed. 348 </p> 349 </li> 350 <li> 351 <p> 352 <span class="bold"><strong>uintmax_t st_mvcc_freed;</strong></span> 353 </p> 354 <p> 355 Number of frozen buffers freed. 356 </p> 357 </li> 358 <li> 359 <p> 360 <span class="bold"><strong>uintmax_t st_alloc;</strong></span> 361 </p> 362 <p> 363 Number of page allocations. 364 </p> 365 </li> 366 <li> 367 <p> 368 <span class="bold"><strong>uintmax_t st_alloc_buckets;</strong></span> 369 </p> 370 <p> 371 Number of hash buckets checked during allocation. 372 </p> 373 </li> 374 <li> 375 <p> 376 <span class="bold"><strong>uintmax_t st_alloc_max_buckets;</strong></span> 377 </p> 378 <p> 379 Maximum number of hash buckets checked during an allocation. 380 </p> 381 </li> 382 <li> 383 <p> 384 <span class="bold"><strong>uintmax_t st_alloc_pages;</strong></span> 385 </p> 386 <p> 387 Number of pages checked during allocation. 388 </p> 389 </li> 390 <li> 391 <p> 392 <span class="bold"><strong>uintmax_t st_alloc_max_pages;</strong></span> 393 </p> 394 <p> 395 Maximum number of pages checked during an allocation. 396 </p> 397 </li> 398 <li> 399 <p> 400 <span class="bold"><strong>uintmax_t st_io_wait;</strong></span> 401 </p> 402 <p> 403 Number of operations blocked waiting for I/O to complete. 404 </p> 405 </li> 406 <li> 407 <p> 408 <span class="bold"><strong>uintmax_t st_sync_interrupted;</strong></span> 409 </p> 410 <p> 411 Number of mpool sync operations interrupted. 412 </p> 413 </li> 414 </ul> 415 </div> 416 <p> 417 If <span class="bold"><strong>fsp</strong></span> is non-NULL, a pointer to a 418 NULL-terminated variable length array of statistics for individual 419 files, in the cache <span class="bold"><strong>mp</strong></span>, is copied 420 into the memory location to which it refers. If no individual files 421 currently exist in the cache, <span class="bold"><strong>fsp</strong></span> 422 will be set to NULL. 423 </p> 424 <p> 425 The per-file statistics are stored in structures of type <code class="literal">DB_MPOOL_FSTAT</code>. 426 The following <code class="literal">DB_MPOOL_FSTAT</code> fields will be filled in for each file in 427 the cache; that is, each element of the array: 428 </p> 429 <div class="itemizedlist"> 430 <ul type="disc"> 431 <li> 432 <p> 433 <span class="bold"><strong>char * file_name;</strong></span> 434 </p> 435 <p> 436 The name of the file. 437 </p> 438 </li> 439 <li> 440 <p> 441 <span class="bold"><strong>size_t st_pagesize;</strong></span> 442 </p> 443 <p> 444 Page size in bytes. 445 </p> 446 </li> 447 <li> 448 <p> 449 <span class="bold"><strong>uintmax_t st_cache_hit;</strong></span> 450 </p> 451 <p> 452 Requested pages found in the cache. 453 </p> 454 </li> 455 <li> 456 <p> 457 <span class="bold"><strong>uintmax_t st_cache_miss;</strong></span> 458 </p> 459 <p> 460 Requested pages not found in the cache. 461 </p> 462 </li> 463 <li> 464 <p> 465 <span class="bold"><strong>u_int32_t st_map;</strong></span> 466 </p> 467 <p> 468 Requested pages mapped into the process' address space. 469 </p> 470 </li> 471 <li> 472 <p> 473 <span class="bold"><strong>uintmax_t st_page_create;</strong></span> 474 </p> 475 <p> 476 Pages created in the cache. 477 </p> 478 </li> 479 <li> 480 <p> 481 <span class="bold"><strong>uintmax_t st_page_in;</strong></span> 482 </p> 483 <p> 484 Pages read into the cache. 485 </p> 486 </li> 487 <li> 488 <p> 489 <span class="bold"><strong>uintmax_t st_page_out;</strong></span> 490 </p> 491 <p> 492 Pages written from the cache to the backing file. 493 </p> 494 </li> 495 </ul> 496 </div> 497 <p> 498 The <code class="methodname">DB_ENV->memp_stat()</code> method may not be called before the 499 <a class="xref" href="envopen.html" title="DB_ENV->open()">DB_ENV->open()</a> method is called. 500 </p> 501 <p> 502 The <code class="methodname">DB_ENV->memp_stat()</code> <span> 503 <span> 504 method returns a non-zero error value on failure and 0 on success. 505 </span> 506 507 </span> 508 </p> 509 <div class="sect2" lang="en" xml:lang="en"> 510 <div class="titlepage"> 511 <div> 512 <div> 513 <h3 class="title"><a id="id1687401"></a>Parameters</h3> 514 </div> 515 </div> 516 </div> 517 <div class="sect3" lang="en" xml:lang="en"> 518 <div class="titlepage"> 519 <div> 520 <div> 521 <h4 class="title"><a id="id1687482"></a>flags</h4> 522 </div> 523 </div> 524 </div> 525 <p> 526 The <span class="bold"><strong>flags</strong></span> parameter must be set to 0 527 or the following value: 528 </p> 529 <div class="itemizedlist"> 530 <ul type="disc"> 531 <li> 532 <p><a id="stat_DB_STAT_CLEAR"></a> 533 <code class="literal">DB_STAT_CLEAR</code> 534 </p> 535 <p> 536 Reset statistics after returning their values. 537 </p> 538 </li> 539 </ul> 540 </div> 541 </div> 542 <div class="sect3" lang="en" xml:lang="en"> 543 <div class="titlepage"> 544 <div> 545 <div> 546 <h4 class="title"><a id="id1687821"></a>fsp</h4> 547 </div> 548 </div> 549 </div> 550 <p> 551 The <span class="bold"><strong>fsp</strong></span> parameter references memory 552 into which a pointer to the allocated per-file statistics structures 553 is copied. 554 </p> 555 </div> 556 <div class="sect3" lang="en" xml:lang="en"> 557 <div class="titlepage"> 558 <div> 559 <div> 560 <h4 class="title"><a id="id1687571"></a>gsp</h4> 561 </div> 562 </div> 563 </div> 564 <p> 565 The <span class="bold"><strong>gsp</strong></span> parameter references memory 566 into which a pointer to the allocated global statistics structure is 567 copied. 568 </p> 569 </div> 570 </div> 571 <div class="sect2" lang="en" xml:lang="en"> 572 <div class="titlepage"> 573 <div> 574 <div> 575 <h3 class="title"><a id="id1687501"></a>Errors</h3> 576 </div> 577 </div> 578 </div> 579 <p> 580 The <code class="methodname">DB_ENV->memp_stat()</code> <span> 581 <span> 582 method may fail and return one of the following non-zero errors: 583 </span> 584 585 </span> 586 </p> 587 <div class="sect3" lang="en" xml:lang="en"> 588 <div class="titlepage"> 589 <div> 590 <div> 591 <h4 class="title"><a id="id1687530"></a>EINVAL</h4> 592 </div> 593 </div> 594 </div> 595 <p> 596 An invalid flag value or parameter was specified. 597 </p> 598 </div> 599 </div> 600 <div class="sect2" lang="en" xml:lang="en"> 601 <div class="titlepage"> 602 <div> 603 <div> 604 <h3 class="title"><a id="id1686868"></a>Class</h3> 605 </div> 606 </div> 607 </div> 608 <p> 609 <a class="link" href="env.html" title="Chapter��5.�� The DB_ENV Handle">DB_ENV</a>, <a class="link" href="memp.html" title="Chapter��8.�� The DB_MPOOLFILE Handle">DB_MPOOLFILE</a> 610 </p> 611 </div> 612 <div class="sect2" lang="en" xml:lang="en"> 613 <div class="titlepage"> 614 <div> 615 <div> 616 <h3 class="title"><a id="id1686856"></a>See Also</h3> 617 </div> 618 </div> 619 </div> 620 <p> 621 <a class="xref" href="memp.html#memplist" title="Memory Pools and Related Methods">Memory Pools and Related Methods</a> 622 </p> 623 </div> 624 </div> 625 <div class="navfooter"> 626 <hr /> 627 <table width="100%" summary="Navigation footer"> 628 <tr> 629 <td width="40%" align="left"><a accesskey="p" href="mempregister.html">Prev</a>��</td> 630 <td width="20%" align="center"> 631 <a accesskey="u" href="memp.html">Up</a> 632 </td> 633 <td width="40%" align="right">��<a accesskey="n" href="mempstat_print.html">Next</a></td> 634 </tr> 635 <tr> 636 <td width="40%" align="left" valign="top">DB_ENV->memp_register()��</td> 637 <td width="20%" align="center"> 638 <a accesskey="h" href="index.html">Home</a> 639 </td> 640 <td width="40%" align="right" valign="top">��DB_ENV->memp_stat_print()</td> 641 </tr> 642 </table> 643 </div> 644 </body> 645</html> 646