← Back to branch summary

~ubuntu-branches/ubuntu/maverick/evolution-data-server/maverick-proposed

« back to all changes in this revision

Viewing changes to libdb/docs/api_c/db_stat.html

  • Committer: Bazaar Package Importer
  • Author(s): Didier Roche
  • Date: 2010-05-17 17:02:06 UTC
  • mfrom: (1.1.79 upstream) (1.6.12 experimental)
  • Revision ID: james.westby@ubuntu.com-20100517170206-4ufr52vwrhh26yh0
Tags: 2.30.1-1ubuntu1
https://launchpad.net/bugs/42199
https://launchpad.net/bugs/229669
https://launchpad.net/bugs/173703
https://launchpad.net/bugs/360344
https://launchpad.net/bugs/508494
* Merge from debian experimental. Remaining change:
  (LP: #42199, #229669, #173703, #360344, #508494)
  + debian/control:
    - add Vcs-Bzr tag
    - don't use libgnome
    - Use Breaks instead of Conflicts against evolution 2.25 and earlier.
  + debian/evolution-data-server.install,
    debian/patches/45_libcamel_providers_version.patch:
    - use the upstream versioning, not a Debian-specific one 
  + debian/libedata-book1.2-dev.install, debian/libebackend-1.2-dev.install,
    debian/libcamel1.2-dev.install, debian/libedataserverui1.2-dev.install:
    - install html documentation
  + debian/rules:
    - don't build documentation it's shipped with the tarball

Show diffs side-by-side

added added

removed removed

Lines of Context:
libdb/docs/api_c/db_stat.html
1
 
<!--$Id$-->
2
 
<!--Copyright 1997-2002 by Sleepycat Software, Inc.-->
3
 
<!--All rights reserved.-->
4
 
<!--See the file LICENSE for redistribution information.-->
5
 
<html>
6
 
<head>
7
 
<title>Berkeley DB: DB-&gt;stat</title>
8
 
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
9
 
<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++">
10
 
</head>
11
 
<body bgcolor=white>
12
 
<a name="2"><!--meow--></a>
13
 
<table width="100%"><tr valign=top>
14
 
<td>
15
 
<h1>DB-&gt;stat</h1>
16
 
</td>
17
 
<td align=right>
18
 
<a href="../api_c/c_index.html"><img src="../images/api.gif" alt="API"></a><a href="../reftoc.html"><img src="../images/ref.gif" alt="Ref"></a>
19
 
</td></tr></table>
20
 
<hr size=1 noshade>
21
 
<tt>
22
 
<h3><pre>
23
 
#include &lt;db.h&gt;
24
 
<p>
25
 
int
26
 
DB-&gt;stat(DB *db, void *sp, u_int32_t flags);
27
 
</pre></h3>
28
 
<h1>Description</h1>
29
 
<p>The DB-&gt;stat method creates a statistical structure and
30
 
copies a pointer to it into user-specified memory locations.
31
 
Specifically, if <b>sp</b> is non-NULL, a pointer to the statistics
32
 
for the database are copied into the memory location to which it refers.
33
 
<p>Statistical structures are created in allocated memory.  If application-specific allocation
34
 
routines have been declared (see <a href="../api_c/env_set_alloc.html">DB_ENV-&gt;set_alloc</a> for more
35
 
information), they are used to allocate the memory; otherwise, the
36
 
library <b>malloc</b>(3) interface is used.  The caller is
37
 
responsible for deallocating the memory.  To deallocate the memory, free
38
 
the memory reference; references inside the returned memory need not be
39
 
individually freed.
40
 
<p>The <b>flags</b> value must be set to 0 or
41
 
one of the following values:
42
 
<p><dl compact>
43
 
<p><dt><a name="DB_FAST_STAT">DB_FAST_STAT</a><dd>Return only the values which do not require traversal of the database.
44
 
Fields returned when this flag is set are noted with an asterisk (*)
45
 
below.
46
 
<p>Among other things, this flag makes it possible for applications to
47
 
request key and record counts without incurring the performance penalty
48
 
of traversing the entire database.  If the underlying database is of
49
 
type Recno, or of type Btree and the database was created with the
50
 
<a href="../api_c/db_set_flags.html#DB_RECNUM">DB_RECNUM</a> flag, the count of keys will be exact.  Otherwise,
51
 
the count of keys will be the value saved the last time the database
52
 
was traversed, or 0 if no count of keys has ever been made.  If the
53
 
underlying database is of type Recno, the count of data items will be
54
 
exact, otherwise, the count of data items will be the value saved the
55
 
last time the database was traversed, or 0 if no count of data items
56
 
has ever been done.
57
 
</dl>
58
 
<p>If the DB_FAST_STAT flag has not been specified, the
59
 
DB-&gt;stat method will access some of or all the pages in the database,
60
 
incurring a severe performance penalty as well as possibly flushing the
61
 
underlying buffer pool.
62
 
<p>In the presence of multiple threads or processes accessing an active
63
 
database, the information returned by DB-&gt;stat may be out-of-date.
64
 
<p>If the database was not opened read-only and the DB_FAST_STAT
65
 
flag was not specified, the cached key and record numbers will be
66
 
updated after the statistical information has been gathered.
67
 
<p>The DB-&gt;stat method cannot be transaction-protected.  For this reason,
68
 
it should be called in a thread of control that has no open cursors or
69
 
active transactions.
70
 
<p>The DB-&gt;stat method returns a non-zero error value on failure and 0 on success.
71
 
<h3>Hash Statistics</h3>
72
 
<p>In the case of a Hash database,
73
 
the statistics are stored in a structure of type DB_HASH_STAT.  The
74
 
following fields will be filled in:
75
 
<p><dl compact>
76
 
<p><dt>u_int32_t hash_magic*<dd>Magic number that identifies the file as a Hash file.
77
 
<dt>u_int32_t hash_version*<dd>The version of the Hash database.
78
 
<dt>u_int32_t hash_nkeys*<dd>The number of unique keys in the database.  If DB_FAST_STAT was
79
 
specified the count will be the last saved value unless it has never
80
 
been calculated, in which case it will be 0.
81
 
<dt>u_int32_t hash_ndata*<dd>The number of key/data pairs in the database.  If DB_FAST_STAT
82
 
was specified the count will be the last saved value unless it has never
83
 
been calculated, in which case it will be 0.
84
 
<dt>u_int32_t hash_pagesize*<dd>The underlying Hash database page (and bucket) size, in bytes.
85
 
<dt>u_int32_t hash_ffactor*<dd>The desired fill factor (number of items per bucket) specified at
86
 
database-creation time.
87
 
<dt>u_int32_t hash_buckets*<dd>The number of hash buckets.
88
 
<dt>u_int32_t hash_free<dd>The number of pages on the free list.
89
 
<dt>u_int32_t hash_bfree<dd>The number of bytes free on bucket pages.
90
 
<dt>u_int32_t hash_bigpages<dd>The number of big key/data pages.
91
 
<dt>u_int32_t hash_big_bfree<dd>The number of bytes free on big item pages.
92
 
<dt>u_int32_t hash_overflows<dd>The number of overflow pages (overflow pages are pages that contain items
93
 
that did not fit in the main bucket page).
94
 
<dt>u_int32_t hash_ovfl_free<dd>The number of bytes free on overflow pages.
95
 
<dt>u_int32_t hash_dup<dd>The number of duplicate pages.
96
 
<dt>u_int32_t hash_dup_free<dd>The number of bytes free on duplicate pages.
97
 
</dl>
98
 
<h3>Btree and Recno Statistics</h3>
99
 
<p>In the case of a Btree or Recno database,
100
 
the statistics are stored in a structure of type DB_BTREE_STAT.  The
101
 
following fields will be filled in:
102
 
<p><dl compact>
103
 
<p><dt>u_int32_t bt_magic*<dd>Magic number that identifies the file as a Btree database.
104
 
<dt>u_int32_t bt_version*<dd>The version of the Btree database.
105
 
<dt>u_int32_t bt_nkeys*<dd>For the Btree Access Method, the number of unique keys in the database.
106
 
If DB_FAST_STAT was specified and the database was created with
107
 
the <a href="../api_c/db_set_flags.html#DB_RECNUM">DB_RECNUM</a> flag, the count will be exact, otherwise, the
108
 
count will be the last saved value unless it has never been calculated,
109
 
in which case it will be 0.
110
 
<p>For the Recno Access Method, the exact number of records in the
111
 
database.
112
 
<dt>u_int32_t bt_ndata*<dd>For the Btree Access Method, the number of key/data pairs in the
113
 
database.  If DB_FAST_STAT was specified the count will be the
114
 
last saved value unless it has never been calculated, in which case it
115
 
will be 0.
116
 
<p>For the Recno Access Method, the exact number of records in the
117
 
database. If the database has been configured to not renumber records
118
 
during deletion, the count of records will only reflect undeleted
119
 
records.
120
 
<dt>u_int32_t bt_pagesize*<dd>Underlying database page size, in bytes.
121
 
<dt>u_int32_t bt_minkey*<dd>The minimum keys per page.
122
 
<dt>u_int32_t bt_re_len*<dd>The length of fixed-length records.
123
 
<dt>u_int32_t bt_re_pad*<dd>The padding byte value for fixed-length records.
124
 
<dt>u_int32_t bt_levels<dd>Number of levels in the database.
125
 
<dt>u_int32_t bt_int_pg<dd>Number of database internal pages.
126
 
<dt>u_int32_t bt_leaf_pg<dd>Number of database leaf pages.
127
 
<dt>u_int32_t bt_dup_pg<dd>Number of database duplicate pages.
128
 
<dt>u_int32_t bt_over_pg<dd>Number of database overflow pages.
129
 
<dt>u_int32_t bt_free<dd>Number of pages on the free list.
130
 
<dt>u_int32_t bt_int_pgfree<dd>Number of bytes free in database internal pages.
131
 
<dt>u_int32_t bt_leaf_pgfree<dd>Number of bytes free in database leaf pages.
132
 
<dt>u_int32_t bt_dup_pgfree<dd>Number of bytes free in database duplicate pages.
133
 
<dt>u_int32_t bt_over_pgfree<dd>Number of bytes free in database overflow pages.
134
 
</dl>
135
 
<h3>Queue Statistics</h3>
136
 
<p>In the case of a Queue database,
137
 
the statistics are stored in a structure of type DB_QUEUE_STAT.  The
138
 
following fields will be filled in:
139
 
<p><dl compact>
140
 
<p><dt>u_int32_t qs_magic*<dd>Magic number that identifies the file as a Queue file.
141
 
<dt>u_int32_t qs_version*<dd>The version of the Queue file type.
142
 
<dt>u_int32_t qs_nkeys*<dd>The number of records in the database.  If DB_FAST_STAT was
143
 
specified the count will be the last saved value unless it has never
144
 
been calculated, in which case it will be 0.
145
 
<dt>u_int32_t qs_ndata*<dd>The number of records in the database.  If DB_FAST_STAT was
146
 
specified the count will be the last saved value unless it has never
147
 
been calculated, in which case it will be 0.
148
 
<dt>u_int32_t qs_pagesize*<dd>Underlying database page size, in bytes.
149
 
<dt>u_int32_t qs_extentsize*<dd>Underlying database extent size, in pages.
150
 
<dt>u_int32_t qs_pages<dd>Number of pages in the database.
151
 
<dt>u_int32_t qs_re_len*<dd>The length of the records.
152
 
<dt>u_int32_t qs_re_pad*<dd>The padding byte value for the records.
153
 
<dt>u_int32_t qs_pgfree<dd>Number of bytes free in database pages.
154
 
<dt>u_int32_t qs_first_recno*<dd>First undeleted record in the database.
155
 
<dt>u_int32_t qs_cur_recno*<dd>Next available record number.
156
 
</dl>
157
 
<p>The DB-&gt;stat method returns a non-zero error value on failure and 0 on success.
158
 
<h1>Errors</h1>
159
 
<p>The DB-&gt;stat method may fail and return a non-zero error for errors specified for other Berkeley DB and C library or system functions.
160
 
If a catastrophic error has occurred, the DB-&gt;stat method may fail and
161
 
return <a href="../ref/program/errorret.html#DB_RUNRECOVERY">DB_RUNRECOVERY</a>,
162
 
in which case all subsequent Berkeley DB calls will fail in the same way.
163
 
<h1>Class</h1>
164
 
<a href="../api_c/db_class.html">DB</a>
165
 
<h1>See Also</h1>
166
 
<a href="../api_c/db_list.html">Databases and Related Methods</a>
167
 
</tt>
168
 
<table width="100%"><tr><td><br></td><td align=right>
169
 
<a href="../api_c/c_index.html"><img src="../images/api.gif" alt="API"></a><a href="../reftoc.html"><img src="../images/ref.gif" alt="Ref"></a>
170
 
</td></tr></table>
171
 
<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
172
 
</body>
173
 
</html>