diff options
Diffstat (limited to 'bdb/docs/api_c/dbt.html')
| -rw-r--r-- | bdb/docs/api_c/dbt.html | 158 |
1 files changed, 0 insertions, 158 deletions
diff --git a/bdb/docs/api_c/dbt.html b/bdb/docs/api_c/dbt.html deleted file mode 100644 index a0c3e76db8d..00000000000 --- a/bdb/docs/api_c/dbt.html +++ /dev/null @@ -1,158 +0,0 @@ -<!--$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> |