,I$Berkeley DB: Db::stat[P

Db::stat





#include <db_cxx.h>

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





Description



7The Db::stat method creates a statistical structure and<copies a pointer to it into user-specified memory locations.8Specifically, if sp is non-NULL, a pointer to the?statistics for the database are copied into the memory locationit references.

7Statistical structures are created in allocated memory.IfBdb_malloc is non-NULL, it is called to allocate the memory,:otherwise, the library function malloc(3)) is used.CThe function db_malloc must match the calling conventions of&the malloc(3)) library routine.CRegardless, the caller is responsible for deallocating the returnedmemory.ETo deallocate the returned memory, free each returned memory pointer;@pointers inside the memory do not need to be individually freed.

CThe Db::stat method cannot be transaction protected, and, should2be done outside of the scope of a transaction.

GIn 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, andAtherefore may incur a severe performance penalty and have obvious3negative effects on the underlying buffer pool.

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

]

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


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

Btree and Recno Statistics



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

T

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.8
u_int32_t bt_pagesize;
Underlying tree page size.9
u_int32_t bt_levels;
Number of levels in the tree.c
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.7
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.L
u_int32_t bt_int_pgfree;
Number of bytes free in tree internal pages.I
u_int32_t bt_leaf_pgfree;
Number of bytes free in tree leaf pages.M
u_int32_t bt_dup_pgfree;
Number of bytes free in tree duplicate pages.M
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

OIf a fatal error occurs in Berkeley DB, the Db::stat method may fail and eitherIreturn DB_RUNRECOVERY or throw an exception encapsulating DB_RUNRECOVERY,Gat which point all subsequent database calls will also fail in the sameFway. Methods marked as returning errno will, by default, throwHan exception that encapsulates the error information. The default error\behavior can be changed, see DbException.

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



Class

,Db



See Also

4Db::close,6Db::cursor,0Db::del,.Db::fd,0Db::get,HDb::get_byteswapped,:Db::get_type,2Db::join,2Db::open,0Db::put,Db::statand2Db::sync.
ÿÿ