1
<!--$Id: dbt.so,v 10.45 2001/06/19 14:37:20 bostic Exp $-->
2
<!--Copyright 1997-2001 by Sleepycat Software, Inc.-->
3
<!--All rights reserved.-->
6
<title>Berkeley DB: DBT</title>
7
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
8
<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++">
11
<a name="2"><!--meow--></a>
12
<table width="100%"><tr valign=top>
14
<h1>DBT: Key/Data Pairs</h1>
17
<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>
21
<a name="3"><!--meow--></a>
22
<p>Storage and retrieval for the Berkeley DB access methods are based on key/data
23
pairs. Both key and data items are represented by the DBT data
24
structure. (The name <i>DBT</i> is a mnemonic for <i>data
25
base thang</i>, and was used because no one could think of a reasonable
26
name that wasn't already in use somewhere else.) Key and data byte
27
strings may refer to strings of zero length up to strings of
28
essentially unlimited length. See <a href="../ref/am_misc/dbsizes.html">Database limits</a> for more information.
29
<p><blockquote><pre>typedef struct {
36
} DBT;</pre></blockquote>
37
<p>In order to ensure compatibility with future releases of Berkeley DB, all
38
fields of the DBT structure that are not explicitly set should be
39
initialized to nul bytes before the first time the structure is used.
40
Do this by declaring the structure external or static, or by calling
41
the C library routine <b>bzero</b>(3) or <b>memset</b>(3).
42
<p>By default, the <b>flags</b> structure element is expected to be set
43
to 0. In this default case, when the application is providing Berkeley DB a
44
key or data item to store into the database, Berkeley DB expects the
45
<b>data</b> structure element to point to a byte string of <b>size</b>
46
bytes. When returning a key/data item to the application, Berkeley DB will
47
store into the <b>data</b> structure element a pointer to a byte string
48
of <b>size</b> bytes, and the memory to which the pointer refers will be
49
allocated and managed by Berkeley DB.
50
<p>The elements of the DBT structure are defined as follows:
52
<p><dt>void *<a name="data">data</a>;<dd>A pointer to a byte string.
53
<p><dt>u_int32_t <a name="size">size</a>;<dd>The length of <b>data</b>, in bytes.
54
<p><dt>u_int32_t <a name="ulen">ulen</a>;<dd>The size of the user's buffer (to which <b>data</b> refers), in bytes.
55
This location is not written by the Berkeley DB functions.
56
<p>Note that applications can determine the length of a record by setting
57
the <b>ulen</b> field to 0 and checking the return value in the
58
<b>size</b> field. See the DB_DBT_USERMEM flag for more information.
59
<p><dt>u_int32_t <a name="dlen">dlen</a>;<dd>The length of the partial record being read or written by the application,
60
in bytes. See the DB_DBT_PARTIAL flag for more information.
61
<p><dt>u_int32_t <a name="doff">doff</a>;<dd>The offset of the partial record being read or written by the application,
62
in bytes. See the DB_DBT_PARTIAL flag for more information.
63
<p><dt>u_int32_t flags;<dd>
64
<p>The <b>flags</b> value must be set to 0 or by bitwise inclusively <b>OR</b>'ing together one or
65
more of the following values:
67
<p><dt><a name="DB_DBT_MALLOC">DB_DBT_MALLOC</a><dd>When this flag is set, Berkeley DB will allocate memory for the returned key
68
or data item (using <b>malloc</b>(3), or the user-specified malloc
69
function), and return a pointer to it in the <b>data</b> field of the
70
key or data DBT structure. Because any allocated memory becomes the
71
responsibility of the calling application, the caller must determine
72
whether memory was allocated using the returned value of the
74
<p>It is an error to specify more than one of DB_DBT_MALLOC,
75
DB_DBT_REALLOC, and DB_DBT_USERMEM.
76
<p><dt><a name="DB_DBT_REALLOC">DB_DBT_REALLOC</a><dd>When this flag is set Berkeley DB will allocate memory for the returned key
77
or data item (using <b>realloc</b>(3), or the user-specified realloc
78
function), and return a pointer to it in the <b>data</b> field of the
79
key or data DBT structure. Because any allocated memory becomes the
80
responsibility of the calling application, the caller must determine
81
whether memory was allocated using the returned value of the
83
<p>The difference between DB_DBT_MALLOC and DB_DBT_REALLOC
84
is that the latter will call <b>realloc</b>(3) instead of
85
<b>malloc</b>(3), so the allocated memory will be grown as necessary
86
instead of the application doing repeated free/malloc calls.
87
<p>DB_DBT_MALLOC, DB_DBT_REALLOC, and
89
<p><dt><a name="DB_DBT_USERMEM">DB_DBT_USERMEM</a><dd>The <b>data</b> field of the key or data structure must refer to
90
memory that is at least <b>ulen</b> bytes in length. If the length of
91
the requested item is less than or equal to that number of bytes, the
92
item is copied into the memory to which the <b>data</b> field refers.
93
Otherwise, the <b>size</b> field is set to the length needed for the
94
requested item, and the error ENOMEM is returned.
95
<p>It is an error to specify more than one of DB_DBT_MALLOC,
96
DB_DBT_REALLOC, and DB_DBT_USERMEM.
97
<p><dt><a name="DB_DBT_PARTIAL">DB_DBT_PARTIAL</a><dd>Do partial retrieval or storage of an item. If the calling application
98
is doing a get, the <b>dlen</b> bytes starting <b>doff</b> bytes from
99
the beginning of the retrieved data record are returned as if they
100
comprised the entire record. If any or all of the specified bytes do
101
not exist in the record, the get is successful, and any existing bytes
103
<p>For example, if the data portion of a retrieved record was 100 bytes,
104
and a partial retrieval was done using a DBT having a <b>dlen</b>
105
field of 20 and a <b>doff</b> field of 85, the get call would succeed,
106
the <b>data</b> field would refer to the last 15 bytes of the record,
107
and the <b>size</b> field would be set to 15.
108
<p>If the calling application is doing a put, the <b>dlen</b> bytes
109
starting <b>doff</b> bytes from the beginning of the specified key's
110
data record are replaced by the data specified by the <b>data</b> and
111
<b>size</b> structure elements. If <b>dlen</b> is smaller than
112
<b>size</b>, the record will grow; if <b>dlen</b> is larger than
113
<b>size</b>, the record will shrink. If the specified bytes do not
114
exist, the record will be extended using nul bytes as necessary, and
115
the put call will succeed.
116
<p>It is an error to attempt a partial put using the <a href="../api_c/db_put.html">DB->put</a> function
117
in a database that supports duplicate records.
118
Partial puts in databases supporting duplicate records must be done
119
using a <a href="../api_c/dbc_put.html">DBcursor->c_put</a> function.
120
<p>It is an error to attempt a partial put with differing <b>dlen</b> and
121
<b>size</b> values in Queue or Recno databases with fixed-length records.
122
<p>For example, if the data portion of a retrieved record was 100 bytes,
123
and a partial put was done using a DBT having a <b>dlen</b> field of 20,
124
a <b>doff</b> field of 85, and a <b>size</b> field of 30, the resulting
125
record would be 115 bytes in length, where the last 30 bytes would be
126
those specified by the put call.
130
<table width="100%"><tr><td><br></td><td align=right>
131
<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>
133
<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
added
removed
db/docs/api_c/dbt.html
