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->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="db.html" title="Chapter��2.�� The DB Handle" /> 11 <link rel="prev" href="dbset_re_source.html" title="DB->set_re_source()" /> 12 <link rel="next" href="dbstat_print.html" title="DB->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->stat()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="dbset_re_source.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��2.�� 23 The DB Handle 24 </th> 25 <td width="20%" align="right">��<a accesskey="n" href="dbstat_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="dbstat"></a>DB->stat()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db.h> 39 40int 41DB->stat(DB *db, DB_TXN *txnid, void *sp, u_int32_t flags); </pre> 42 <p> 43 The <code class="methodname">DB->stat()</code> method creates a statistical structure and copies a 44 pointer to it into user-specified memory locations. Specifically, if 45 <span class="bold"><strong>sp</strong></span> is non-NULL, a pointer to the 46 statistics for the database are copied into the memory location to 47 which it refers. 48 </p> 49 <p> 50 The <code class="methodname">DB->stat()</code> <span> 51 <span> 52 method returns a non-zero error value on failure and 0 on success. 53 </span> 54 55 </span> 56 </p> 57 <div class="sect2" lang="en" xml:lang="en"> 58 <div class="titlepage"> 59 <div> 60 <div> 61 <h3 class="title"><a id="id1650806"></a>Parameters</h3> 62 </div> 63 </div> 64 </div> 65 <div class="sect3" lang="en" xml:lang="en"> 66 <div class="titlepage"> 67 <div> 68 <div> 69 <h4 class="title"><a id="id1650770"></a>flags</h4> 70 </div> 71 </div> 72 </div> 73 <p> 74 The <span class="bold"><strong>flags</strong></span> parameter must be set to 0 75 or one of the following values: 76 </p> 77 <div class="itemizedlist"> 78 <ul type="disc"> 79 <li> 80 <p><a id="stat_DB_FAST_STAT"></a> 81 <code class="literal">DB_FAST_STAT</code> 82 </p> 83 <p> 84 Return only the values which do not require traversal of the database. 85 Among other things, this flag makes it possible for applications to 86 request key and record counts without incurring the performance 87 penalty of traversing the entire database. 88 </p> 89 </li> 90 <li> 91 <p><a id="stat_DB_READ_COMMITTED"></a> 92 <code class="literal">DB_READ_COMMITTED</code> 93 </p> 94 <p> 95 Database items read during a transactional call will have degree 2 96 isolation. This ensures the stability of the data items read during 97 the stat operation but permits that data to be modified or deleted by 98 other transactions prior to the commit of the specified transaction. 99 </p> 100 </li> 101 <li> 102 <p><a id="stat_DB_READ_UNCOMMITTED"></a> 103 <code class="literal">DB_READ_UNCOMMITTED</code> 104 </p> 105 <p> 106 Database items read during a transactional call will have degree 1 107 isolation, including modified but not yet committed data. Silently 108 ignored if the 109 <a class="link" href="dbopen.html#dbopen_DB_READ_UNCOMMITTED">DB_READ_UNCOMMITTED</a> 110 flag was not specified when the underlying database was opened. 111 </p> 112 </li> 113 </ul> 114 </div> 115 </div> 116 <div class="sect3" lang="en" xml:lang="en"> 117 <div class="titlepage"> 118 <div> 119 <div> 120 <h4 class="title"><a id="id1650888"></a>txnid</h4> 121 </div> 122 </div> 123 </div> 124 <p> 125 If the operation is part of an application-specified transaction, the 126 <span class="bold"><strong>txnid</strong></span> parameter is a transaction 127 handle returned from <a class="xref" href="txnbegin.html" title="DB_ENV->txn_begin()">DB_ENV->txn_begin()</a>; if the 128 operation is part of a Berkeley DB Concurrent Data Store group, the 129 <span class="bold"><strong>txnid</strong></span> parameter is a handle returned 130 from <a class="xref" href="envcdsgroup_begin.html" title="DB_ENV->cdsgroup_begin()">DB_ENV->cdsgroup_begin()</a>; 131 otherwise NULL. If no transaction handle is specified, but the 132 operation occurs in a transactional database, the operation will be 133 implicitly transaction protected. 134 </p> 135 </div> 136 </div> 137 <div class="sect2" lang="en" xml:lang="en"> 138 <div class="titlepage"> 139 <div> 140 <div> 141 <h3 class="title"><a id="id1651027"></a>Statistical Structure</h3> 142 </div> 143 </div> 144 </div> 145 <p> 146 Statistical structures are stored in allocated memory. If 147 application-specific allocation routines have been declared (see 148 <a class="xref" href="envset_alloc.html" title="DB_ENV->set_alloc()">DB_ENV->set_alloc()</a> 149 for more information), they are used to allocate the 150 memory; otherwise, the standard C library 151 <span class="bold"><strong>malloc</strong></span>(3) is used. The caller is 152 responsible for deallocating the memory. To deallocate the memory, free the 153 memory reference; references inside the returned memory need not be 154 individually freed. 155 </p> 156 <p> 157 If the DB_FAST_STAT flag has not been specified, the 158 <code class="methodname">DB->stat()</code> method will 159 access some of or all the pages in the database, incurring a severe 160 performance penalty as well as possibly flushing the underlying buffer pool. 161 </p> 162 <p> 163 In the presence of multiple threads or processes accessing an active 164 database, the information returned by DB->stat may be out-of-date. 165 </p> 166 <p> 167 If the database was not opened read-only and the DB_FAST_STAT flag was not 168 specified, the cached key and record numbers will be updated after the 169 statistical information has been gathered. 170 </p> 171 <p> 172 The <code class="methodname">DB->stat()</code> method may not be called before the 173 <a class="xref" href="dbopen.html" title="DB->open()">DB->open()</a> 174 method is called. 175 </p> 176 <p> 177 The <code class="methodname">DB->stat()</code> method returns a non-zero error value on failure and 0 on 178 success. 179 </p> 180 <div class="sect3" lang="en" xml:lang="en"> 181 <div class="titlepage"> 182 <div> 183 <div> 184 <h4 class="title"><a id="id1651062"></a>Hash Statistics</h4> 185 </div> 186 </div> 187 </div> 188 <p> 189 In the case of a Hash database, the statistics are stored in a 190 structure of type <code class="literal">DB_HASH_STAT</code>. The following fields will be filled 191 in: 192 </p> 193 <div class="itemizedlist"> 194 <ul type="disc"> 195 <li> 196 <p> 197 <code class="literal">u_int32_t hash_magic;</code> 198 </p> 199 <p> 200 Magic number that identifies the file as a Hash file. Returned if 201 DB_FAST_STAT is set. 202 </p> 203 </li> 204 <li> 205 <p> 206 <code class="literal">u_int32_t hash_version;</code> 207 </p> 208 <p> 209 The version of the Hash database. Returned if DB_FAST_STAT is set. 210 </p> 211 </li> 212 <li> 213 <p> 214 <code class="literal">u_int32_t hash_nkeys;</code> 215 </p> 216 <p> 217 The number of unique keys in the database. If DB_FAST_STAT was 218 specified the count will be the last saved value unless it has never 219 been calculated, in which case it will be 0. Returned if DB_FAST_STAT 220 is set. 221 </p> 222 </li> 223 <li> 224 <p> 225 <code class="literal">u_int32_t hash_ndata;</code> 226 </p> 227 <p> 228 The number of key/data pairs in the database. If DB_FAST_STAT was 229 specified the count will be the last saved value unless it has never 230 been calculated, in which case it will be 0. Returned if DB_FAST_STAT 231 is set. 232 </p> 233 </li> 234 <li> 235 <p> 236 <code class="literal">u_int32_t hash_pagecnt;</code> 237 </p> 238 <p> 239 The number of pages in the database. Returned if DB_FAST_STAT is set. 240 </p> 241 </li> 242 <li> 243 <p> 244 <code class="literal">u_int32_t hash_pagesize;</code> 245 </p> 246 <p> 247 The underlying database page (and bucket) size, in bytes. Returned if 248 DB_FAST_STAT is set. 249 </p> 250 </li> 251 <li> 252 <p> 253 <code class="literal">u_int32_t hash_ffactor;</code> 254 </p> 255 <p> 256 The desired fill factor (number of items per bucket) specified at 257 database-creation time. Returned if DB_FAST_STAT is set. 258 </p> 259 </li> 260 <li> 261 <p> 262 <code class="literal">u_int32_t hash_buckets;</code> 263 </p> 264 <p> 265 The number of hash buckets. Returned if DB_FAST_STAT is set. 266 </p> 267 </li> 268 <li> 269 <p> 270 <code class="literal">u_int32_t hash_free;</code> 271 </p> 272 <p> 273 The number of pages on the free list. 274 </p> 275 </li> 276 <li> 277 <p> 278 <code class="literal">uintmax_t hash_bfree;</code> 279 </p> 280 <p> 281 The number of bytes free on bucket pages. 282 </p> 283 </li> 284 <li> 285 <p> 286 <code class="literal">u_int32_t hash_bigpages;</code> 287 </p> 288 <p> 289 The number of big key/data pages. 290 </p> 291 </li> 292 <li> 293 <p> 294 <code class="literal">uintmax_t hash_big_bfree;</code> 295 </p> 296 <p> 297 The number of bytes free on big item pages. 298 </p> 299 </li> 300 <li> 301 <p> 302 <code class="literal">u_int32_t hash_overflows;</code> 303 </p> 304 <p> 305 The number of overflow pages (overflow pages are pages that contain 306 items that did not fit in the main bucket page). 307 </p> 308 </li> 309 <li> 310 <p> 311 <code class="literal">uintmax_t hash_ovfl_free;</code> 312 </p> 313 <p> 314 The number of bytes free on overflow pages. 315 </p> 316 </li> 317 <li> 318 <p> 319 <code class="literal">u_int32_t hash_dup;</code> 320 </p> 321 <p> 322 The number of duplicate pages. 323 </p> 324 </li> 325 <li> 326 <p> 327 <code class="literal">uintmax_t hash_dup_free;</code> 328 </p> 329 <p> 330 The number of bytes free on duplicate pages. 331 </p> 332 </li> 333 </ul> 334 </div> 335 </div> 336 <div class="sect3" lang="en" xml:lang="en"> 337 <div class="titlepage"> 338 <div> 339 <div> 340 <h4 class="title"><a id="id1651092"></a>Btree and Recno Statistics</h4> 341 </div> 342 </div> 343 </div> 344 <p> 345 In the case of a Btree or Recno database, the statistics are stored in a 346 structure of type <code class="literal">DB_BTREE_STAT</code>. The following fields will be filled in: 347 </p> 348 <div class="itemizedlist"> 349 <ul type="disc"> 350 <li> 351 <p> 352 <code class="literal">u_int32_t bt_magic;</code> 353 </p> 354 <p> 355 Magic number that identifies the file as a Btree database. Returned 356 if DB_FAST_STAT is set. 357 </p> 358 </li> 359 <li> 360 <p> 361 <code class="literal">u_int32_t bt_version;</code> 362 </p> 363 <p> 364 The version of the Btree database. Returned if DB_FAST_STAT is set. 365 </p> 366 </li> 367 <li> 368 <p> 369 <code class="literal">u_int32_t bt_nkeys;</code> 370 </p> 371 <p> 372 For the Btree Access Method, the number of keys in the database. If 373 the DB_FAST_STAT flag is not specified or the database was configured 374 to support record numbers (see 375 <a class="link" href="dbset_flags.html#dbset_flags_DB_RECNUM">DB_RECNUM</a>), 376 the count will be exact. Otherwise, the count will be the last saved 377 value unless it has never been calculated, in which case it will be 0. 378 </p> 379 <p> 380 For the Recno Access Method, the number of records in the database. 381 If the database was configured with mutable record numbers (see 382 <a class="link" href="dbset_flags.html#dbset_flags_DB_RENUMBER">DB_RENUMBER</a>), 383 the count will be exact. Otherwise, if the DB_FAST_STAT flag is specified 384 the count will be exact but will include deleted and implicitly 385 created records; if the DB_FAST_STAT flag is not specified, the count 386 will be exact and will not include deleted or implicitly created 387 records. 388 </p> 389 <p> 390 Returned if DB_FAST_STAT is set. 391 </p> 392 </li> 393 <li> 394 <p> 395 <code class="literal">u_int32_t bt_ndata;</code> 396 </p> 397 <p> 398 For the Btree Access Method, the number of key/data pairs in the 399 database. If the DB_FAST_STAT flag is not specified, the count will 400 be exact. Otherwise, the count will be the last saved value unless it 401 has never been calculated, in which case it will be 0. 402 </p> 403 <p> 404 For the Recno Access Method, the number of records in the database. 405 If the database was configured with mutable record numbers (see 406 <a class="link" href="dbset_flags.html#dbset_flags_DB_RENUMBER">DB_RENUMBER</a>), 407 the count will be exact. Otherwise, if the DB_FAST_STAT flag is specified 408 the count will be exact but will include deleted and implicitly 409 created records; if the DB_FAST_STAT flag is not specified, the count 410 will be exact and will not include deleted or implicitly created 411 records. 412 </p> 413 <p> 414 Returned if DB_FAST_STAT is set. 415 </p> 416 </li> 417 <li> 418 <p> 419 <code class="literal">u_int32_t bt_pagecnt;</code> 420 </p> 421 <p> 422 The number of pages in the database. Returned if DB_FAST_STAT is set. 423 </p> 424 </li> 425 <li> 426 <p> 427 <code class="literal">u_int32_t bt_pagesize;</code> 428 </p> 429 <p> 430 The underlying database page size, in bytes. Returned if DB_FAST_STAT 431 is set. 432 </p> 433 </li> 434 <li> 435 <p> 436 <code class="literal">u_int32_t bt_minkey;</code> 437 </p> 438 <p> 439 The minimum keys per page. Returned if DB_FAST_STAT is set. 440 </p> 441 </li> 442 <li> 443 <p> 444 <code class="literal">u_int32_t bt_re_len;</code> 445 </p> 446 <p> 447 The length of fixed-length records. Returned if DB_FAST_STAT is set. 448 </p> 449 </li> 450 <li> 451 <p> 452 <code class="literal">u_int32_t bt_re_pad;</code> 453 </p> 454 <p> 455 The padding byte value for fixed-length records. Returned if 456 DB_FAST_STAT is set. 457 </p> 458 </li> 459 <li> 460 <p> 461 <code class="literal">u_int32_t bt_levels;</code> 462 </p> 463 <p> 464 Number of levels in the database. 465 </p> 466 </li> 467 <li> 468 <p> 469 <code class="literal">u_int32_t bt_int_pg;</code> 470 </p> 471 <p> 472 Number of database internal pages. 473 </p> 474 </li> 475 <li> 476 <p> 477 <code class="literal">u_int32_t bt_leaf_pg;</code> 478 </p> 479 <p> 480 Number of database leaf pages. 481 </p> 482 </li> 483 <li> 484 <p> 485 <code class="literal">u_int32_t bt_dup_pg;</code> 486 </p> 487 <p> 488 Number of database duplicate pages. 489 </p> 490 </li> 491 <li> 492 <p> 493 <code class="literal">u_int32_t bt_over_pg;</code> 494 </p> 495 <p> 496 Number of database overflow pages. 497 </p> 498 </li> 499 <li> 500 <p> 501 <code class="literal">u_int32_t bt_empty_pg;</code> 502 </p> 503 <p> 504 Number of empty database pages. 505 </p> 506 </li> 507 <li> 508 <p> 509 <code class="literal">u_int32_t bt_free;</code> 510 </p> 511 <p> 512 Number of pages on the free list. 513 </p> 514 </li> 515 <li> 516 <p> 517 <code class="literal">uintmax_t bt_int_pgfree;</code> 518 </p> 519 <p> 520 Number of bytes free in database internal pages. 521 </p> 522 </li> 523 <li> 524 <p> 525 <code class="literal">uintmax_t bt_leaf_pgfree;</code> 526 </p> 527 <p> 528 Number of bytes free in database leaf pages. 529 </p> 530 </li> 531 <li> 532 <p> 533 <code class="literal">uintmax_t bt_dup_pgfree;</code> 534 </p> 535 <p> 536 Number of bytes free in database duplicate pages. 537 </p> 538 </li> 539 <li> 540 <p> 541 <code class="literal">uintmax_t bt_over_pgfree;</code> 542 </p> 543 <p> 544 Number of bytes free in database overflow pages. 545 </p> 546 </li> 547 </ul> 548 </div> 549 </div> 550 <div class="sect3" lang="en" xml:lang="en"> 551 <div class="titlepage"> 552 <div> 553 <div> 554 <h4 class="title"><a id="id1651128"></a>Queue Statistics</h4> 555 </div> 556 </div> 557 </div> 558 <p> 559 In the case of a Queue database, the statistics are stored in a 560 structure of type <code class="literal">DB_QUEUE_STAT</code>. The following fields will be filled in: 561 </p> 562 <div class="itemizedlist"> 563 <ul type="disc"> 564 <li> 565 <p> 566 <code class="literal">u_int32_t qs_magic;</code> 567 </p> 568 <p> 569 Magic number that identifies the file as a Queue file. Returned if 570 DB_FAST_STAT is set. 571 </p> 572 </li> 573 <li> 574 <p> 575 <code class="literal">u_int32_t qs_version;</code> 576 </p> 577 <p> 578 The version of the Queue file type. Returned if DB_FAST_STAT is set. 579 </p> 580 </li> 581 <li> 582 <p> 583 <code class="literal">u_int32_t qs_nkeys;</code> 584 </p> 585 <p> 586 The number of records in the database. If DB_FAST_STAT was specified 587 the count will be the last saved value unless it has never been 588 calculated, in which case it will be 0. Returned if DB_FAST_STAT is 589 set. 590 </p> 591 </li> 592 <li> 593 <p> 594 <code class="literal">u_int32_t qs_ndata;</code> 595 </p> 596 <p> 597 The number of records in the database. If DB_FAST_STAT was specified 598 the count will be the last saved value unless it has never been 599 calculated, in which case it will be 0. Returned if DB_FAST_STAT is 600 set. 601 </p> 602 </li> 603 <li> 604 <p> 605 <code class="literal">u_int32_t qs_pagesize;</code> 606 </p> 607 <p> 608 Underlying database page size, in bytes. Returned if DB_FAST_STAT is 609 set. 610 </p> 611 </li> 612 <li> 613 <p> 614 <code class="literal">u_int32_t qs_extentsize;</code> 615 </p> 616 <p> 617 Underlying database extent size, in pages. Returned if DB_FAST_STAT 618 is set. 619 </p> 620 </li> 621 <li> 622 <p> 623 <code class="literal">u_int32_t qs_pages;</code> 624 </p> 625 <p> 626 Number of pages in the database. 627 </p> 628 </li> 629 <li> 630 <p> 631 <code class="literal">u_int32_t qs_re_len;</code> 632 </p> 633 <p> 634 The length of the records. Returned if DB_FAST_STAT is set. 635 </p> 636 </li> 637 <li> 638 <p> 639 <code class="literal">u_int32_t qs_re_pad;</code> 640 </p> 641 <p> 642 The padding byte value for the records. Returned if DB_FAST_STAT is 643 set. 644 </p> 645 </li> 646 <li> 647 <p> 648 <code class="literal">u_int32_t qs_pgfree;</code> 649 </p> 650 <p> 651 Number of bytes free in database pages. 652 </p> 653 </li> 654 <li> 655 <p> 656 <code class="literal">u_int32_t qs_first_recno;</code> 657 </p> 658 <p> 659 First undeleted record in the database. Returned if DB_FAST_STAT is 660 set. 661 </p> 662 </li> 663 <li> 664 <p> 665 <code class="literal">u_int32_t qs_cur_recno;</code> 666 </p> 667 <p> 668 Next available record number. Returned if DB_FAST_STAT is set. 669 </p> 670 </li> 671 </ul> 672 </div> 673 </div> 674 </div> 675 <div class="sect2" lang="en" xml:lang="en"> 676 <div class="titlepage"> 677 <div> 678 <div> 679 <h3 class="title"><a id="id1650880"></a>Errors</h3> 680 </div> 681 </div> 682 </div> 683 <p> 684 The <code class="methodname">DB->stat()</code> <span> 685 <span> 686 method may fail and return one of the following non-zero errors: 687 </span> 688 689 </span> 690 </p> 691 <div class="sect3" lang="en" xml:lang="en"> 692 <div class="titlepage"> 693 <div> 694 <div> 695 <h4 class="title"><a id="id1650612"></a> DB_REP_HANDLE_DEAD</h4> 696 </div> 697 </div> 698 </div> 699 <p> 700 When a client synchronizes with the master, it is possible for committed 701 transactions to be rolled back. This invalidates all the database and cursor 702 handles opened in the replication environment. Once this occurs, an attempt to use 703 such a handle will 704 705 return <code class="literal">DB_REP_HANDLE_DEAD</code>. 706 The application will need to discard the handle and open a new one in order to 707 continue processing. 708 </p> 709 </div> 710 <div class="sect3" lang="en" xml:lang="en"> 711 <div class="titlepage"> 712 <div> 713 <div> 714 <h4 class="title"><a id="id1651391"></a>DB_REP_LOCKOUT</h4> 715 </div> 716 </div> 717 </div> 718 <p> 719 The operation was blocked by client/master synchronization. 720 </p> 721 </div> 722 <div class="sect3" lang="en" xml:lang="en"> 723 <div class="titlepage"> 724 <div> 725 <div> 726 <h4 class="title"><a id="id1650597"></a>EINVAL</h4> 727 </div> 728 </div> 729 </div> 730 <p> 731 An invalid flag value or parameter was specified. 732 </p> 733 </div> 734 </div> 735 <div class="sect2" lang="en" xml:lang="en"> 736 <div class="titlepage"> 737 <div> 738 <div> 739 <h3 class="title"><a id="id1650718"></a>Class</h3> 740 </div> 741 </div> 742 </div> 743 <p> 744 <a class="link" href="db.html" title="Chapter��2.�� The DB Handle">DB</a> 745 </p> 746 </div> 747 <div class="sect2" lang="en" xml:lang="en"> 748 <div class="titlepage"> 749 <div> 750 <div> 751 <h3 class="title"><a id="id1650864"></a>See Also</h3> 752 </div> 753 </div> 754 </div> 755 <p> 756 <a class="xref" href="db.html#dblist" title="Database and Related Methods">Database and Related Methods</a> 757 </p> 758 </div> 759 </div> 760 <div class="navfooter"> 761 <hr /> 762 <table width="100%" summary="Navigation footer"> 763 <tr> 764 <td width="40%" align="left"><a accesskey="p" href="dbset_re_source.html">Prev</a>��</td> 765 <td width="20%" align="center"> 766 <a accesskey="u" href="db.html">Up</a> 767 </td> 768 <td width="40%" align="right">��<a accesskey="n" href="dbstat_print.html">Next</a></td> 769 </tr> 770 <tr> 771 <td width="40%" align="left" valign="top">DB->set_re_source()��</td> 772 <td width="20%" align="center"> 773 <a accesskey="h" href="index.html">Home</a> 774 </td> 775 <td width="40%" align="right" valign="top">��DB->stat_print()</td> 776 </tr> 777 </table> 778 </div> 779 </body> 780</html> 781