Db::stat(void *sp, void *(*db_malloc)(size_t), u_int32_t flags);
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
Statistical structures are created in allocated memory.
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
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:
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).
Number of tree internal pages.
Number of tree leaf pages.
Number of tree duplicate pages.
Number of tree overflow pages.
Number of pages on the free list.
Number of bytes free in tree internal pages.
Number of bytes free in tree leaf pages.
Number of bytes free in tree duplicate pages.
Number of bytes free in tree overflow pages.
method either returns errno or throws an exception that
encapsulates an errno on failure, and 0 on success.
If a fatal error occurs in Berkeley DB, the Db::stat method may fail and either
return DB_RUNRECOVERY or throw an exception encapsulating DB_RUNRECOVERY,
at which point all subsequent database calls will also fail in the same
way. Methods marked as returning errno will, by default, throw
an exception that encapsulates the error information. The default error
behavior can be changed, see DbException.