1<!--$Id: db_stat.so,v 10.95 2007/10/24 16:06:06 bostic Exp $--> 2<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 3<!--See the file LICENSE for redistribution information.--> 4<html> 5<head> 6<title>Berkeley DB: DB->stat</title> 7<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> 8<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 9</head> 10<body bgcolor=white> 11<table width="100%"><tr valign=top> 12<td> 13<b>DB->stat</b> 14</td> 15<td align=right> 16<a href="../api_c/api_core.html"><img src="../images/api.gif" alt="API"></a> 17<a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a></td> 18</tr></table> 19<hr size=1 noshade> 20<tt> 21<b><pre> 22#include <db.h> 23<p> 24int 25DB->stat(DB *db, DB_TXN *txnid, void *sp, u_int32_t flags); 26<p> 27int 28DB->stat_print(DB *db, u_int32_t flags); 29</pre></b> 30<hr size=1 noshade> 31<b>Description: DB->stat</b> 32<p>The DB->stat method creates a statistical structure and copies a 33pointer to it into user-specified memory locations. Specifically, if 34<b>sp</b> is non-NULL, a pointer to the statistics for the database are 35copied into the memory location to which it refers.</p> 36<b>Parameters</b> <br> 37 <b>flags</b><ul compact><li>The <b>flags</b> parameter must be set to 0 or 38one of the following values: 39<br> 40<b><a name="DB_FAST_STAT">DB_FAST_STAT</a></b><ul compact><li>Return only the values which do not require traversal of the database. 41Among other things, this flag makes it possible for applications to 42request key and record counts without incurring the performance penalty 43of traversing the entire database.</ul> 44<b><a name="DB_READ_COMMITTED">DB_READ_COMMITTED</a></b><ul compact><li>Database items read during a transactional call will have degree 2 45isolation. This ensures the stability of the data items read during the 46stat operation but permits that data to be modified or deleted by other 47transactions prior to the commit of the specified transaction.</ul> 48<b><a name="DB_READ_UNCOMMITTED">DB_READ_UNCOMMITTED</a></b><ul compact><li>Database items read during a transactional call will have degree 1 49isolation, including modified but not yet committed data. Silently 50ignored if the <a href="../api_c/db_open.html#DB_READ_UNCOMMITTED">DB_READ_UNCOMMITTED</a> flag was not specified when 51the underlying database was opened.</ul> <br></ul> 52 <b>txnid</b><ul compact><li>If the operation is part of an application-specified transaction, the 53<b>txnid</b> parameter is a transaction handle returned from 54<a href="../api_c/txn_begin.html">DB_ENV->txn_begin</a>; if the operation is part of a Berkeley DB Concurrent Data Store group, the 55<b>txnid</b> parameter is a handle returned from 56<a href="../api_c/env_cdsgroup_begin.html">DB_ENV->cdsgroup_begin</a>; otherwise NULL. 57If no transaction handle is 58specified, but the 59operation occurs in a transactional 60database, 61the operation will be implicitly transaction protected. 62</ul> 63<br> 64<p>Statistical structures are stored in allocated memory. If application-specific allocation 65routines have been declared (see <a href="../api_c/env_set_alloc.html">DB_ENV->set_alloc</a> for more 66information), they are used to allocate the memory; otherwise, the 67standard C library <b>malloc</b>(3) is used. The caller is 68responsible for deallocating the memory. To deallocate the memory, free 69the memory reference; references inside the returned memory need not be 70individually freed.</p> 71<p>If the DB_FAST_STAT flag has not been specified, the 72DB->stat method will access some of or all the pages in the database, 73incurring a severe performance penalty as well as possibly flushing the 74underlying buffer pool.</p> 75<p>In the presence of multiple threads or processes accessing an active 76database, the information returned by DB->stat may be out-of-date.</p> 77<p>If the database was not opened read-only and the DB_FAST_STAT 78flag was not specified, the cached key and record numbers will be 79updated after the statistical information has been gathered.</p> 80<p>The DB->stat method may not be called before the <a href="../api_c/db_open.html">DB->open</a> method is called.</p> 81<p>The DB->stat method 82returns a non-zero error value on failure 83and 0 on success. 84</p> 85<b>Hash Statistics</b> 86<p>In the case of a Hash database, the statistics are stored in a structure 87of type DB_HASH_STAT. The following fields will be filled in:</p> 88<br> 89<b>u_int32_t hash_magic;</b><ul compact><li>Magic number that identifies the file as a Hash file. Returned if 90DB_FAST_STAT is set.</ul> 91<b>u_int32_t hash_version;</b><ul compact><li>The version of the Hash database. Returned if DB_FAST_STAT is 92set.</ul> 93<b>u_int32_t hash_nkeys;</b><ul compact><li>The number of unique keys in the database. If DB_FAST_STAT was 94specified the count will be the last saved value unless it has never 95been calculated, in which case it will be 0. Returned if 96DB_FAST_STAT is set.</ul> 97<b>u_int32_t hash_ndata;</b><ul compact><li>The number of key/data pairs in the database. If DB_FAST_STAT 98was specified the count will be the last saved value unless it has never 99been calculated, in which case it will be 0. Returned if 100DB_FAST_STAT is set.</ul> 101<b>u_int32_t hash_pagecnt;</b><ul compact><li>The number of pages in the database. Returned if DB_FAST_STAT 102is set.</ul> 103<b>u_int32_t hash_pagesize;</b><ul compact><li>The underlying database page (and bucket) size, in bytes. Returned if 104DB_FAST_STAT is set.</ul> 105<b>u_int32_t hash_ffactor;</b><ul compact><li>The desired fill factor (number of items per bucket) specified at 106database-creation time. Returned if DB_FAST_STAT is set.</ul> 107<b>u_int32_t hash_buckets;</b><ul compact><li>The number of hash buckets. Returned if DB_FAST_STAT is set.</ul> 108<b>u_int32_t hash_free;</b><ul compact><li>The number of pages on the free list.</ul> 109<b>u_int32_t hash_bfree;</b><ul compact><li>The number of bytes free on bucket pages.</ul> 110<b>u_int32_t hash_bigpages;</b><ul compact><li>The number of big key/data pages.</ul> 111<b>u_int32_t hash_big_bfree;</b><ul compact><li>The number of bytes free on big item pages.</ul> 112<b>u_int32_t hash_overflows;</b><ul compact><li>The number of overflow pages (overflow pages are pages that contain items 113that did not fit in the main bucket page).</ul> 114<b>u_int32_t hash_ovfl_free;</b><ul compact><li>The number of bytes free on overflow pages.</ul> 115<b>u_int32_t hash_dup;</b><ul compact><li>The number of duplicate pages.</ul> 116<b>u_int32_t hash_dup_free;</b><ul compact><li>The number of bytes free on duplicate pages.</ul> 117<br> 118<b>Btree and Recno Statistics</b> 119<p>In the case of a Btree or Recno database, the statistics are stored in 120a structure of type DB_BTREE_STAT. The following fields will be filled 121in:</p> 122<br> 123<b>u_int32_t bt_magic;</b><ul compact><li>Magic number that identifies the file as a Btree database. Returned 124if DB_FAST_STAT is set.</ul> 125<b>u_int32_t bt_version;</b><ul compact><li>The version of the Btree database. Returned if DB_FAST_STAT 126is set.</ul> 127<b>u_int32_t bt_nkeys;</b><ul compact><li>For the Btree Access Method, the number of keys in the database. If 128the DB_FAST_STAT flag is not specified or the database was 129configured to support record numbers (see <a href="../api_c/db_set_flags.html#DB_RECNUM">DB_RECNUM</a>), the count 130will be exact. Otherwise, the count will be the last saved value unless 131it has never been calculated, in which case it will be 0. 132<p>For the Recno Access Method, the number of records in the database. If 133the database was configured with mutable record numbers (see 134<a href="../api_c/db_set_flags.html#DB_RENUMBER">DB_RENUMBER</a>), the count will be exact. Otherwise, if the 135DB_FAST_STAT flag is specified the count will be exact but will 136include deleted and implicitly created records; if the 137DB_FAST_STAT flag is not specified, the count will be exact and 138will not include deleted or implicitly created records.</p> 139<p>Returned if DB_FAST_STAT is set.</p></ul> 140<b>u_int32_t bt_ndata;</b><ul compact><li>For the Btree Access Method, the number of key/data pairs in the 141database. If the DB_FAST_STAT flag is not specified, the count 142will be exact. Otherwise, the count will be the last saved value unless 143it has never been calculated, in which case it will be 0. 144<p>For the Recno Access Method, the number of records in the database. If 145the database was configured with mutable record numbers (see 146<a href="../api_c/db_set_flags.html#DB_RENUMBER">DB_RENUMBER</a>), the count will be exact. Otherwise, if the 147DB_FAST_STAT flag is specified the count will be exact but will 148include deleted and implicitly created records; if the 149DB_FAST_STAT flag is not specified, the count will be exact and 150will not include deleted or implicitly created records.</p> 151<p>Returned if DB_FAST_STAT is set.</p></ul> 152<b>u_int32_t bt_pagecnt;</b><ul compact><li>The number of pages in the database. Returned if DB_FAST_STAT 153is set.</ul> 154<b>u_int32_t bt_pagesize;</b><ul compact><li>The underlying database page size, in bytes. Returned if 155DB_FAST_STAT is set.</ul> 156<b>u_int32_t bt_minkey;</b><ul compact><li>The minimum keys per page. Returned if DB_FAST_STAT is set.</ul> 157<b>u_int32_t bt_re_len;</b><ul compact><li>The length of fixed-length records. Returned if DB_FAST_STAT 158is set.</ul> 159<b>u_int32_t bt_re_pad;</b><ul compact><li>The padding byte value for fixed-length records. Returned if 160DB_FAST_STAT is set.</ul> 161<b>u_int32_t bt_levels;</b><ul compact><li>Number of levels in the database.</ul> 162<b>u_int32_t bt_int_pg;</b><ul compact><li>Number of database internal pages.</ul> 163<b>u_int32_t bt_leaf_pg;</b><ul compact><li>Number of database leaf pages.</ul> 164<b>u_int32_t bt_dup_pg;</b><ul compact><li>Number of database duplicate pages.</ul> 165<b>u_int32_t bt_over_pg;</b><ul compact><li>Number of database overflow pages.</ul> 166<b>u_int32_t bt_empty_pg;</b><ul compact><li>Number of empty database pages.</ul> 167<b>u_int32_t bt_free;</b><ul compact><li>Number of pages on the free list.</ul> 168<b>u_int32_t bt_int_pgfree;</b><ul compact><li>Number of bytes free in database internal pages.</ul> 169<b>u_int32_t bt_leaf_pgfree;</b><ul compact><li>Number of bytes free in database leaf pages.</ul> 170<b>u_int32_t bt_dup_pgfree;</b><ul compact><li>Number of bytes free in database duplicate pages.</ul> 171<b>u_int32_t bt_over_pgfree;</b><ul compact><li>Number of bytes free in database overflow pages.</ul> 172<br> 173<b>Queue Statistics</b> 174<p>In the case of a Queue database, the statistics are stored in a 175structure of type DB_QUEUE_STAT. The following fields will be filled 176in:</p> 177<br> 178<b>u_int32_t qs_magic;</b><ul compact><li>Magic number that identifies the file as a Queue file. Returned if 179DB_FAST_STAT is set.</ul> 180<b>u_int32_t qs_version;</b><ul compact><li>The version of the Queue file type. Returned if DB_FAST_STAT 181is set.</ul> 182<b>u_int32_t qs_nkeys;</b><ul compact><li>The number of records in the database. If DB_FAST_STAT was 183specified the count will be the last saved value unless it has never 184been calculated, in which case it will be 0. Returned if 185DB_FAST_STAT is set.</ul> 186<b>u_int32_t qs_ndata;</b><ul compact><li>The number of records in the database. If DB_FAST_STAT was 187specified the count will be the last saved value unless it has never 188been calculated, in which case it will be 0. Returned if 189DB_FAST_STAT is set.</ul> 190<b>u_int32_t qs_pagesize;</b><ul compact><li>Underlying database page size, in bytes. Returned if 191DB_FAST_STAT is set.</ul> 192<b>u_int32_t qs_extentsize;</b><ul compact><li>Underlying database extent size, in pages. Returned if 193DB_FAST_STAT is set.</ul> 194<b>u_int32_t qs_pages;</b><ul compact><li>Number of pages in the database.</ul> 195<b>u_int32_t qs_re_len;</b><ul compact><li>The length of the records. Returned if DB_FAST_STAT is set.</ul> 196<b>u_int32_t qs_re_pad;</b><ul compact><li>The padding byte value for the records. Returned if 197DB_FAST_STAT is set.</ul> 198<b>u_int32_t qs_pgfree;</b><ul compact><li>Number of bytes free in database pages.</ul> 199<b>u_int32_t qs_first_recno;</b><ul compact><li>First undeleted record in the database. Returned if 200DB_FAST_STAT is set.</ul> 201<b>u_int32_t qs_cur_recno;</b><ul compact><li>Next available record number. Returned if DB_FAST_STAT is set.</ul> 202<br> 203<br><b>Errors</b> 204<p>The DB->stat method 205may fail and return one of the following non-zero errors:</p> 206<br> 207<b>DB_REP_HANDLE_DEAD</b><ul compact><li>The database handle has been invalidated because a replication election 208unrolled a committed transaction.</ul> 209<br> 210<br> 211<b>DB_REP_LOCKOUT</b><ul compact><li>The operation was blocked by client/master synchronization.</ul> 212<br> 213<br> 214<b>EINVAL</b><ul compact><li>An 215invalid flag value or parameter was specified.</ul> 216<br> 217<hr size=1 noshade> 218<b>Description: DB->stat_print</b> 219<p>The DB->stat_print method displays the 220database statistical information, as described for the DB->stat method. 221The information is printed to a specified output channel (see the 222<a href="../api_c/env_set_msgfile.html">DB_ENV->set_msgfile</a> method for more information), or passed to an 223application callback function (see the <a href="../api_c/env_set_msgcall.html">DB_ENV->set_msgcall</a> method for 224more information).</p> 225<p>The DB->stat_print method may not be called before the <a href="../api_c/db_open.html">DB->open</a> method is called.</p> 226<p>The DB->stat_print method 227returns a non-zero error value on failure 228and 0 on success. 229</p> 230<b>Parameters</b> <br> 231 <b>flags</b><ul compact><li>The <b>flags</b> parameter must be set to 0 or by bitwise inclusively <b>OR</b>'ing together one 232or more of the following values: 233<br> 234<b><a name="DB_FAST_STAT">DB_FAST_STAT</a></b><ul compact><li>Return only the values which do not require traversal of the database. 235Among other things, this flag makes it possible for applications to 236request key and record counts without incurring the performance penalty 237of traversing the entire database.</ul> 238<b><a name="DB_STAT_ALL">DB_STAT_ALL</a></b><ul compact><li>Display all available information.</ul> 239<br></ul> 240<br> 241<hr size=1 noshade> 242<br><b>Class</b> 243<a href="../api_c/db_class.html">DB</a> 244<br><b>See Also</b> 245<a href="../api_c/db_list.html">Databases and Related Methods</a> 246</tt> 247<table width="100%"><tr><td><br></td><td align=right> 248<a href="../api_c/api_core.html"><img src="../images/api.gif" alt="API"></a><a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a> 249</td></tr></table> 250<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 251</body> 252</html> 253
