#include <db_cxx.h>

int
Db::stat(void *sp, void *(*db_malloc)(size_t), u_int32_t flags);

Description

The Db::stat method 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 Db::stat method cannot be transaction protected, and, should be done outside of the scope of a transaction.

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

This method may access all of the pages in the database, and therefore may incur a severe performance penalty and have obvious negative effects on the underlying buffer pool.

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.

u_int32_t bt_magic;

Magic number that identifies the file as a btree file.

u_int32_t bt_version;

The version of the btree file type.

u_int32_t bt_flags;

Permanent database flags, including DB_DUP, DB_FIXEDLEN, DB_RECNUM and DB_RENUMBER.

u_int32_t bt_minkey;

The bt_minkey value specified to Db::open, if any.

u_int32_t bt_re_len;

The re_len value specified to Db::open, if any.

u_int32_t bt_re_pad;

The re_pad value specified to Db::open, if any.

u_int32_t bt_pagesize;

Underlying tree page size.

u_int32_t bt_levels;

Number of levels in the tree.

u_int32_t bt_nrecs;

Number of data items in the tree (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_int_pg;

Number of tree internal pages.

u_int32_t bt_leaf_pg;

Number of tree leaf pages.

u_int32_t bt_dup_pg;

Number of tree duplicate pages.

u_int32_t bt_over_pg;

Number of tree overflow pages.

u_int32_t bt_free;

Number of pages on the free list.

u_int32_t bt_int_pgfree;

Number of bytes free in tree internal pages.

u_int32_t bt_leaf_pgfree;

Number of bytes free in tree leaf pages.

u_int32_t bt_dup_pgfree;

Number of bytes free in tree duplicate pages.

u_int32_t bt_over_pgfree;

Number of bytes free in tree overflow pages.

The Db::stat method either returns errno or throws an exception that encapsulates an errno on failure, and 0 on success.

Errors

The Db::stat method may fail and throw an exception for any of the errors specified for the following Berkeley DB and C library functions: Db::cursor, DBcursor->c_close(3), dbenv->db_paniccall(3), fflush(3), fprintf(3), DbLockTab::get, DbLock::put, DbLockTab::vec, malloc(3), DbMpoolFile::get, DbMpoolFile::put, memset(3), strerror(3), vfprintf(3), and vsnprintf(3).

Class

See Also