DB->stat

APIRef

#include <db.h>

int DB->stat(DB *db, void *sp, void *(*db_malloc)(size_t), u_int32_t flags);

Description

The DB->stat function creates a statistical structure and copies a pointer to it into user-specified memory locations. Specifically, if sp is non-NULL, a pointer to the statistics for the database are copied into the memory location it references.

Statistical structures are created in allocated memory. If db_malloc is non-NULL, it is called to allocate the memory, otherwise, the library function malloc(3) is used. The function db_malloc must match the calling conventions of the malloc(3) library routine. Regardless, the caller is responsible for deallocating the returned memory. To deallocate the returned memory, free each returned memory pointer; pointers inside the memory do not need to be individually freed.

The flags parameter must be set to 0 or the following value:

DB_RECORDCOUNT
Fill in the bt_nrecs information of the statistics structure, but do not collect any other information. This flag makes it reasonable for applications to request a record count from a database without incurring a performance penalty. It is only available for Recno databases, or Btree databases where the underlying database was created with the DB_RECNUM flag.

The DB->stat function may access all of the pages in the database, and so can incur a severe performance penalty as well as flush the underlying buffer pool.

In the presence of multiple threads or processes accessing an active database, the information returned by DB->stat may be out-of-date.

The DB->stat function cannot be transaction protected. For this reason, it should be called in a thread of control that has no open cursors or active transactions.

The DB->stat function returns a non-zero error value on failure and 0 on success.

Hash Statistics

In the case of a Hash database, the statistics are stored in a structure of type DB_HASH_STAT. The following fields will be filled in:

u_int32_t hash_magic;
Magic number that identifies the file as a Hash file.
u_int32_t hash_version;
The version of the Hash database.
u_int32_t hash_pagesize;
The underlying Hash database page (and bucket) size.
u_int32_t hash_nrecs;
The number of unique keys in the Hash database (since keys may have duplicates, this is not the total number of elements in the database).
u_int32_t hash_nelem;
The estimated size of the hash table specified at database creation time.
u_int32_t hash_ffactor;
The desired fill factor (number of items per bucket) specified at database creation time.
u_int32_t hash_buckets;
The number of hash buckets.
u_int32_t hash_free;
The number of pages on the free list.
u_int32_t hash_bfree;
The number of bytes free on bucket pages.
u_int32_t hash_bigpages;
The number of big key/data pages.
u_int32_t hash_big_bfree;
The number of bytes free on big item pages.
u_int32_t hash_overflows;
The number of overflow pages (overflow pages are pages that contain items that did not fit in the main bucket page).
u_int32_t hash_ovfl_free;
The number of bytes free on overflow pages.
u_int32_t hash_dup;
The number of duplicate pages.
u_int32_t hash_dup_free;
The number of bytes free on duplicate pages.

Btree and Recno Statistics

In the case of a Btree or Recno database, the statistics are stored in a structure of type DB_BTREE_STAT. The following fields will be filled in:

u_int32_t bt_magic;
Magic number that identifies the file as a Btree database.
u_int32_t bt_version;
The version of the Btree database.
u_int32_t bt_dup_pg;
Number of database duplicate pages.
u_int32_t bt_dup_pgfree;
Number of bytes free in database duplicate pages.
u_int32_t bt_free;
Number of pages on the free list.
u_int32_t bt_int_pg;
Number of database internal pages.
u_int32_t bt_int_pgfree;
Number of bytes free in database internal pages.
u_int32_t bt_leaf_pg;
Number of database leaf pages.
u_int32_t bt_leaf_pgfree;
Number of bytes free in database leaf pages.
u_int32_t bt_levels;
Number of levels in the database.
u_int32_t bt_minkey;
The minimum keys per page.
u_int32_t bt_nrecs;
Number of records in the database for Recno. Number of data items in the database for Btree (and since there may be multiple data items per key, this number may not be the same as the number of keys).
u_int32_t bt_over_pg;
Number of database overflow pages.
u_int32_t bt_over_pgfree;
Number of bytes free in database overflow pages.
u_int32_t bt_pagesize;
Underlying database page size.
u_int32_t bt_re_len;
The length of fixed-length records.
u_int32_t bt_re_pad;
The padding byte value for fixed-length records.

Queue Statistics

In the case of a Queue database, the statistics are stored in a structure of type DB_QUEUE_STAT. The following fields will be filled in:

u_int32_t qs_magic;
Magic number that identifies the file as a Queue file.
u_int32_t qs_version;
The version of the Queue file type.
u_int32_t qs_nrecs;
Number of records in the database.
u_int32_t qs_pages;
Number of pages in the database.
u_int32_t qs_pagesize;
Underlying database page size.
u_int32_t qs_pgfree;
Number of bytes free in database pages.
u_int32_t qs_re_len;
The length of the records.
u_int32_t qs_re_pad;
The padding byte value for the records.
u_int32_t qs_start;
Start offset.
u_int32_t qs_first_recno;
First undeleted record in the database.
u_int32_t qs_cur_recno;
Last allocated record number in the database.

The DB->stat function returns a non-zero error value on failure and 0 on success.

Errors

If a fatal error occurs in Berkeley DB, the DB->stat function will fail and return DB_RUNRECOVERY, at which point all subsequent database calls will fail in the same way.

In addition, the DB->stat function may fail and return a non-zero error for errors specified for other Berkeley DB and C library or system functions.

See Also

db_create, DB->close, DB->cursor, DB->del, DB->err, DB->fd, DB->get, DB->get_byteswapped, DB->get_type, DB->join, DB->open, DB->put, DB->remove, DB->set_bt_compare, DB->set_bt_minkey, DB->set_bt_prefix, DB->set_cachesize, DB->set_dup_compare, DB->set_errcall, DB->set_errfile, DB->set_errpfx, DB->set_flags, DB->set_h_ffactor, DB->set_h_hash, DB->set_h_nelem, DB->set_lorder, DB->set_malloc, DB->set_pagesize, DB->set_paniccall, DB->set_realloc, DB->set_re_delim, DB->set_re_len, DB->set_re_pad, DB->set_re_source, DB->stat, DB->sync and DB->upgrade.

APIRef

Copyright Sleepycat Software