AnonymousFox

//usr/share/doc/db4-devel-4.7.25/api_c/dbt_class.html

<html>
<head>
<title>Berkeley DB: DBT</title>
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++">
</head>
<body bgcolor=white>
<table width="100%"><tr valign=top>
<td>
DBT: Key/Data Pairs
</td>
<td align=right>
<a href="../../db4-devel-4.7.25/api_c/api_core.html"><img src="../../db4-devel-4.7.25/images/api.gif" alt="API"></a>
<a href="../../db4-devel-4.7.25/ref/toc.html"><img src="../../db4-devel-4.7.25/images/ref.gif" alt="Ref"></a></td>
</tr></table>
<hr size=1 noshade>
<tt>
<a name="2"></a>
Storage and retrieval for the Berkeley DB access methods are based on key/data
pairs. Both key and data items are represented by the DBT data
structure. (The name DBT is a mnemonic for data
base thang, and was used because no one could think of a reasonable
name that wasn't already in use somewhere else.) Key and data byte
strings may refer to strings of zero length up to strings of
essentially unlimited length. See <a href="../../db4-devel-4.7.25/ref/am_misc/dbsizes.html">Database limits</a> for more information.
<blockquote><pre>typedef struct {
	void *data;
	u_int32_t size;
	u_int32_t ulen;
	u_int32_t dlen;
	u_int32_t doff;
	u_int32_t flags;
} DBT;</pre></blockquote>
In order to ensure compatibility with future releases of Berkeley DB, all
fields of the DBT structure that are not explicitly set should be
initialized to nul bytes before the first time the structure is used.
Do this by declaring the structure external or static, or by calling
the C library routine bzero(3) or memset(3).
By default, the flags structure element is expected to be set
to 0. In this default case, when the application is providing Berkeley DB a
key or data item to store into the database, Berkeley DB expects the
data structure element to point to a byte string of size
bytes. When returning a key/data item to the application, Berkeley DB will
store into the data structure element a pointer to a byte string
of size bytes, and the memory to which the pointer refers will be
allocated and managed by Berkeley DB.
The elements of the DBT structure are defined as follows:
 
void *<a name="data">data</a>;<ul compact><li>A pointer to a byte string.</ul>
u_int32_t <a name="size">size</a>;<ul compact><li>The length of data, in bytes.</ul>
u_int32_t <a name="ulen">ulen</a>;<ul compact><li>The size of the user's buffer (to which data refers), in bytes.
This location is not written by the Berkeley DB functions.
Note that applications can determine the length of a record by setting
the ulen field to 0 and checking the return value in the
size field. See the DB_DBT_USERMEM flag for more information.</ul>
u_int32_t <a name="dlen">dlen</a>;<ul compact><li>The length of the partial record being read or written by the application,
in bytes. See the DB_DBT_PARTIAL flag for more information.</ul>
u_int32_t <a name="doff">doff</a>;<ul compact><li>The offset of the partial record being read or written by the application,
in bytes. See the DB_DBT_PARTIAL flag for more information.</ul>
u_int32_t flags;<ul compact><li>The flags parameter must be set to 0 or by bitwise inclusively OR'ing together one
or more of the following values:
 
<a name="DB_DBT_MALLOC">DB_DBT_MALLOC</a><ul compact><li>When this flag is set, Berkeley DB will allocate memory for the returned key
or data item (using malloc(3), or the user-specified malloc
function), and return a pointer to it in the data field of the
key or data DBT structure. Because any allocated memory becomes the
responsibility of the calling application, the caller must determine
whether memory was allocated using the returned value of the
data field.
It is an error to specify more than one of DB_DBT_MALLOC,
DB_DBT_REALLOC, and DB_DBT_USERMEM.</ul>
<a name="DB_DBT_REALLOC">DB_DBT_REALLOC</a><ul compact><li>When this flag is set Berkeley DB will allocate memory for the returned key
or data item (using realloc(3), or the user-specified realloc
function), and return a pointer to it in the data field of the
key or data DBT structure. Because any allocated memory becomes the
responsibility of the calling application, the caller must determine
whether memory was allocated using the returned value of the
data field.
The difference between DB_DBT_MALLOC and DB_DBT_REALLOC
is that the latter will call realloc(3) instead of
malloc(3), so the allocated memory will be grown as necessary
instead of the application doing repeated free/malloc calls.
It is an error to specify more than one of DB_DBT_MALLOC,
DB_DBT_REALLOC, and DB_DBT_USERMEM.</ul>
<a name="3"></a>
<a name="DB_DBT_USERMEM">DB_DBT_USERMEM</a><ul compact><li>The data field of the key or data structure must refer to
memory that is at least ulen bytes in length. If the length of
the requested item is less than or equal to that number of bytes, the
item is copied into the memory to which the data field refers.
Otherwise, the size field is set to the length needed for the
requested item, and the error DB_BUFFER_SMALL is returned.
It is an error to specify more than one of DB_DBT_MALLOC,
DB_DBT_REALLOC, and DB_DBT_USERMEM.</ul>
<a name="DB_DBT_PARTIAL">DB_DBT_PARTIAL</a><ul compact><li>Do partial retrieval or storage of an item. If the calling application
is doing a get, the dlen bytes starting doff bytes from
the beginning of the retrieved data record are returned as if they
comprised the entire record. If any or all of the specified bytes do
not exist in the record, the get is successful, and any existing bytes
are returned.
For example, if the data portion of a retrieved record was 100 bytes,
and a partial retrieval was done using a DBT having a dlen
field of 20 and a doff field of 85, the get call would succeed,
the data field would refer to the last 15 bytes of the record,
and the size field would be set to 15.
If the calling application is doing a put, the dlen bytes
starting doff bytes from the beginning of the specified key's
data record are replaced by the data specified by the data and
size structure elements. If dlen is smaller than
size, the record will grow; if dlen is larger than
size, the record will shrink. If the specified bytes do not
exist, the record will be extended using nul bytes as necessary, and
the put call will succeed.
It is an error to attempt a partial put using the <a href="../../db4-devel-4.7.25/api_c/db_put.html">DB-&gt;put</a> function
in a database that supports duplicate records.
Partial puts in databases supporting duplicate records must be done
using a <a href="../../db4-devel-4.7.25/api_c/dbc_put.html">DBcursor-&gt;put</a> function.
It is an error to attempt a partial put with differing dlen and
size values in Queue or Recno databases with fixed-length records.
For example, if the data portion of a retrieved record was 100 bytes,
and a partial put was done using a DBT having a dlen field of 20,
a doff field of 85, and a size field of 30, the resulting
record would be 115 bytes in length, where the last 30 bytes would be
those specified by the put call.</ul>
<a name="DB_DBT_APPMALLOC">DB_DBT_APPMALLOC</a><ul compact><li>After an application-supplied callback routine passed to either
<a href="../../db4-devel-4.7.25/api_c/db_associate.html">DB-&gt;associate</a> or <a href="../../db4-devel-4.7.25/api_c/db_set_append_recno.html">DB-&gt;set_append_recno</a> is executed, the
data field of a DBT may refer to memory allocated with
malloc(3) or realloc(3). In that case, the
callback sets the <a href="../../db4-devel-4.7.25/api_c/dbt_class.html#DB_DBT_APPMALLOC">DB_DBT_APPMALLOC</a> flag in the DBT so
that Berkeley DB will call free(3) to deallocate the memory when it
is no longer required.</ul>
<a name="DB_DBT_MULTIPLE">DB_DBT_MULTIPLE</a><ul compact><li>Set in a secondary key creation callback routine passed to
<a href="../../db4-devel-4.7.25/api_c/db_associate.html">DB-&gt;associate</a> to indicate that multiple secondary keys should be
associated with the given primary key/data pair. If set, the
size field indicates the number of secondary keys and the
data field refers to an array of that number of DBT
structures.
The <a href="../../db4-devel-4.7.25/api_c/dbt_class.html#DB_DBT_APPMALLOC">DB_DBT_APPMALLOC</a> flag may be set on any of the DBT
structures to indicate that their data field needs to be
freed.</ul>
 </ul>
 
</tt>
<table width="100%"><tr><td> </td><td align=right>
<a href="../../db4-devel-4.7.25/api_c/api_core.html"><img src="../../db4-devel-4.7.25/images/api.gif" alt="API"></a><a href="../../db4-devel-4.7.25/ref/toc.html"><img src="../../db4-devel-4.7.25/images/ref.gif" alt="Ref"></a>
</td></tr></table>
Copyright (c) 1996,2008 Oracle. All rights reserved.
</body>
</html>