mirror of
https://github.com/MariaDB/server.git
synced 2025-01-31 02:51:44 +01:00
158 lines
9.5 KiB
HTML
158 lines
9.5 KiB
HTML
<!--$Id: dbt.so,v 10.37 2000/12/18 21:05:12 bostic Exp $-->
|
|
<!--Copyright 1997, 1998, 1999, 2000 by Sleepycat Software, Inc.-->
|
|
<!--All rights reserved.-->
|
|
<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,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++">
|
|
</head>
|
|
<body bgcolor=white>
|
|
<tt>
|
|
<a name="2"><!--meow--></a>
|
|
<h3>Key/Data Pairs</h3>
|
|
<p>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 <i>data base thang</i>, 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 reference strings of
|
|
zero length up to strings of essentially unlimited length. See
|
|
<a href="../ref/program/dbsizes.html">Database limits</a> for more
|
|
information.
|
|
<p><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>
|
|
<p>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
|
|
0 before the first time the structure is used. Do this by declaring the
|
|
structure external or static, or by calling the C library routine
|
|
<b>bzero</b>(3) or <b>memset</b>(3).
|
|
<p>By default, the <b>flags</b> structure element is expected to be 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 <b>data</b> structure
|
|
element to point to a byte string of <b>size</b> bytes. When returning
|
|
a key/data item to the application, Berkeley DB will store into the <b>data</b>
|
|
structure element a pointer to a byte string of <b>size</b> bytes, and
|
|
the memory referenced by the pointer will be allocated and managed by Berkeley DB.
|
|
<p>The elements of the DBT structure are defined as follows:
|
|
<p><dl compact>
|
|
<p><dt>void *<a name="data">data</a>;<dd>A pointer to a byte string.
|
|
<p><dt>u_int32_t <a name="size">size</a>;<dd>The length of <b>data</b>, in bytes.
|
|
<p><dt>u_int32_t <a name="ulen">ulen</a>;<dd>The size of the user's buffer (referenced by <b>data</b>), in bytes.
|
|
This location is not written by the Berkeley DB functions.
|
|
<p>Note that applications can determine the length of a record by setting
|
|
the <b>ulen</b> field to 0 and checking the return value in the
|
|
<b>size</b> field. See the DB_DBT_USERMEM flag for more information.
|
|
<p><dt>u_int32_t <a name="dlen">dlen</a>;<dd>The length of the partial record being read or written by the application,
|
|
in bytes. See the DB_DBT_PARTIAL flag for more information.
|
|
<p><dt>u_int32_t <a name="doff">doff</a>;<dd>The offset of the partial record being read or written by the application,
|
|
in bytes. See the DB_DBT_PARTIAL flag for more information.
|
|
<p><dt>u_int32_t flags;<dd>
|
|
<p>The <b>flags</b> value must be set to 0 or by bitwise inclusively <b>OR</b>'ing together one or more
|
|
of the following values.
|
|
<p><dl compact>
|
|
<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
|
|
or data item (using <b>malloc</b>(3), or the user-specified malloc
|
|
function) and return a pointer to it in the <b>data</b> field of the
|
|
key or data DBT structure. As any allocated memory becomes the
|
|
responsibility of the calling application, the caller must be able to
|
|
determine if memory was allocated.
|
|
<p>It is an error to specify more than one of DB_DBT_MALLOC,
|
|
DB_DBT_REALLOC and DB_DBT_USERMEM.
|
|
<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
|
|
or data item (using <b>realloc</b>(3), or the user-specified realloc
|
|
function) and return a pointer to it in the <b>data</b> field of the
|
|
key or data DBT structure. As any allocated memory becomes the
|
|
responsibility of the calling application, the caller must be able to
|
|
determine if memory was allocated.
|
|
<p>The difference between DB_DBT_MALLOC and DB_DBT_REALLOC
|
|
is that the latter will call <b>realloc</b>(3) instead of
|
|
<b>malloc</b>(3), so the allocated memory will be grown as necessary
|
|
instead of the application doing repeated free/malloc calls.
|
|
<p>It is an error to specify more than one of DB_DBT_MALLOC,
|
|
DB_DBT_REALLOC and DB_DBT_USERMEM.
|
|
<p><dt><a name="DB_DBT_USERMEM">DB_DBT_USERMEM</a><dd>The <b>data</b> field of the key or data structure must reference
|
|
memory that is at least <b>ulen</b> 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 referenced by the <b>data</b> field.
|
|
Otherwise, the <b>size</b> field is set to the length needed for the
|
|
requested item, and the error ENOMEM is returned.
|
|
<p>It is an error to specify more than one of DB_DBT_MALLOC,
|
|
DB_DBT_REALLOC and DB_DBT_USERMEM.
|
|
<p><dt><a name="DB_DBT_PARTIAL">DB_DBT_PARTIAL</a><dd>Do partial retrieval or storage of an item. If the calling application
|
|
is doing a get, the <b>dlen</b> bytes starting <b>doff</b> 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 the existing bytes
|
|
or nul bytes are returned.
|
|
<p>For example, if the data portion of a retrieved record was 100 bytes,
|
|
and a partial retrieval was done using a DBT having a <b>dlen</b>
|
|
field of 20 and a <b>doff</b> field of 85, the get call would succeed,
|
|
the <b>data</b> field would reference the last 15 bytes of the record,
|
|
and the <b>size</b> field would be set to 15.
|
|
<p>If the calling application is doing a put, the <b>dlen</b> bytes
|
|
starting <b>doff</b> bytes from the beginning of the specified key's
|
|
data record are replaced by the data specified by the <b>data</b>
|
|
and <b>size</b> structure elements.
|
|
If <b>dlen</b> is smaller than <b>size</b>, the record will grow,
|
|
and if <b>dlen</b> is larger than <b>size</b>, 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.
|
|
<p>It is an error to attempt a partial put using the <a href="../api_c/db_put.html">DB->put</a> function
|
|
in a database that supports duplicate records.
|
|
Partial puts in databases supporting duplicate records must be done
|
|
using a <a href="../api_c/dbc_put.html">DBcursor->c_put</a> function.
|
|
<p>It is an error to attempt a partial put with differing <b>dlen</b> and
|
|
<b>size</b> values in Queue or Recno databases with fixed-length records.
|
|
<p>For example, if the data portion of a retrieved record was 100 bytes,
|
|
and a partial put was done using a DBT having a <b>dlen</b> field of 20,
|
|
a <b>doff</b> field of 85, and a <b>size</b> 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.
|
|
</dl>
|
|
</dl>
|
|
<a name="3"><!--meow--></a> <a name="4"><!--meow--></a>
|
|
<h3>Retrieved key/data permanence</h3>
|
|
<p>When using the non-cursor Berkeley DB calls to retrieve key/data items (e.g.,
|
|
<a href="../api_c/db_get.html">DB->get</a>), the memory referenced by the pointer stored into the
|
|
Dbt is only valid until the next call to Berkeley DB using the Db
|
|
handle returned by <a href="../api_c/db_open.html">DB->open</a>. (This includes <b>any</b> use of
|
|
the returned Db handle, including by another thread of control
|
|
within the process. For this reason, when multiple threads are using the
|
|
returned Db handle concurrently, one of the DB_DBT_MALLOC,
|
|
DB_DBT_REALLOC or DB_DBT_USERMEM flags must be specified
|
|
with any non-cursor Dbt used for key or data retrieval.)
|
|
<p>When using the cursor Berkeley DB calls to retrieve key/data items (e.g.,
|
|
<a href="../api_c/dbc_get.html">DBcursor->c_get</a>), the memory referenced by the pointer into the
|
|
Dbt is only valid until the next call to Berkeley DB using the
|
|
DBC handle returned by <a href="../api_c/db_cursor.html">DB->cursor</a>.
|
|
<a name="5"><!--meow--></a>
|
|
<h3>Data alignment</h3>
|
|
<p>The Berkeley DB access methods provide no guarantees about key/data byte string
|
|
alignment, and applications are responsible for arranging any necessary
|
|
alignment. The DB_DBT_MALLOC, DB_DBT_REALLOC and
|
|
DB_DBT_USERMEM flags may be used to store returned items in memory
|
|
of arbitrary alignment.
|
|
<a name="6"><!--meow--></a>
|
|
<h3>Logical Record Numbers</h3>
|
|
<p>In all cases for the Queue and Recno access methods, and when calling the
|
|
<a href="../api_c/db_get.html">DB->get</a> and <a href="../api_c/dbc_get.html">DBcursor->c_get</a> functions with the
|
|
<a href="../api_c/db_get.html#DB_SET_RECNO">DB_SET_RECNO</a> flag specified, the <b>data</b> field of the key
|
|
must be a pointer to a memory location of type <b>db_recno_t</b>, as
|
|
typedef'd in the #include <db.h> include file. This type is a 32-bit
|
|
unsigned type, (which limits the number of logical records in a Queue or
|
|
Recno database, and the maximum logical record which may be directly
|
|
retrieved from a Btree database, to 4,294,967,296). The <b>size</b>
|
|
field of the key should be the size of that type, i.e., in the C
|
|
programming language, <b>sizeof(db_recno_t)</b>.
|
|
<p>Logical record numbers are 1-based, not 0-based, i.e., the first record
|
|
in the database is record number 1.
|
|
</tt>
|
|
<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
|
|
</body>
|
|
</html>
|