>, Db::set_re_source, Db::stat, Db::sync, Db::truncate, Db::upgrade, and Db::verify.

APIRef

Copyright Sleepycat Software Berkeley DB: Db::stat

Db::stat

APIRef


#include <db_cxx.h>

int Db::stat(void *sp, 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 to which it refers.

Statistical structures are created in allocated memory. If application-specific allocation routines have been declared (see DbEnv::set_alloc for more information), they are used to allocate the memory; otherwise, the library function malloc(3) is used. The caller is responsible for deallocating the memory. To deallocate the memory, free the memory reference; references inside the returned memory need not be individually freed.

The flags value must be set to 0 or one of the following values:

DB_CACHED_COUNTS
Return a cached count of the keys and records in a database. The DB_CACHED_COUNTS flag has been deprecated in favor of the DB_FAST_STAT flag. Please update your applications.

DB_FAST_STAT
Return only the values which do not require traversal of the database. Fields returned when this flag is set are noted with an asterisk (*) below.

Among other things, this flag makes it possible for applications to request key and record counts without incurring the performance penalty of traversing the entire database. If the underlying database is of type Recno, or of type Btree and the database was created with the DB_RECNUM flag, the count of keys will be exact. Otherwise, the count of keys will be the value saved the last time the database was traversed, or 0 if no count of keys has ever been made. If the underlying database is of type Recno, the count of data items will be exact, otherwise, the count of data items will be the value saved the last time the database was traversed, or 0 if no count of data items has ever been done.

DB_RECORDCOUNT
Return a count of the records in a Btree or Recno Access Method database. The DB_RECORDCOUNT flag has been deprecated in favor of the DB_FAST_STAT flag. Please update your applications.

If the DB_FAST_STAT flag has not been specified, the Db::stat method will access some of or all the pages in the database, incurring a severe performance penalty as well as possibly flushing 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.

If the database was not opened read-only and the DB_FAST_STAT flag was not specified, the cached key and record numbers will be updated after the statistical information has been gathered.

The Db::stat method 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 method either returns a non-zero error value or throws an exception that encapsulates a non-zero error value on fail