1<!--$Id: dbt_class.so,v 10.1 2002/08/24 18:22:30 bostic Exp $--> 2<!--$Id: dbt_c.so,v 10.52 2007/02/27 00:41:24 mjc Exp $--> 3<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 4<!--See the file LICENSE for redistribution information.--> 5<html> 6<head> 7<title>Berkeley DB: DBT</title> 8<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> 9<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 10</head> 11<body bgcolor=white> 12<table width="100%"><tr valign=top> 13<td> 14<b>DBT: Key/Data Pairs</b> 15</td> 16<td align=right> 17<a href="/api_c/api_core.html"><img src="/images/api.gif" alt="API"></a> 18<a href="/ref/toc.html"><img src="/images/ref.gif" alt="Ref"></a></td> 19</tr></table> 20<hr size=1 noshade> 21<tt> 22<a name="2"><!--meow--></a> 23<p>Storage and retrieval for the Berkeley DB access methods are based on key/data 24pairs. Both key and data items are represented by the DBT data 25structure. (The name <i>DBT</i> is a mnemonic for <i>data 26base thang</i>, and was used because no one could think of a reasonable 27name that wasn't already in use somewhere else.) Key and data byte 28strings may refer to strings of zero length up to strings of 29essentially unlimited length. See <a href="/ref/am_misc/dbsizes.html">Database limits</a> for more information.</p> 30<blockquote><pre>typedef struct { 31 void *data; 32 u_int32_t size; 33 u_int32_t ulen; 34 u_int32_t dlen; 35 u_int32_t doff; 36 u_int32_t flags; 37} DBT;</pre></blockquote> 38<p>In order to ensure compatibility with future releases of Berkeley DB, all 39fields of the DBT structure that are not explicitly set should be 40initialized to nul bytes before the first time the structure is used. 41Do this by declaring the structure external or static, or by calling 42the C library routine <b>bzero</b>(3) or <b>memset</b>(3).</p> 43<p>By default, the <b>flags</b> structure element is expected to be set 44to 0. In this default case, when the application is providing Berkeley DB a 45key or data item to store into the database, Berkeley DB expects the 46<b>data</b> structure element to point to a byte string of <b>size</b> 47bytes. When returning a key/data item to the application, Berkeley DB will 48store into the <b>data</b> structure element a pointer to a byte string 49of <b>size</b> bytes, and the memory to which the pointer refers will be 50allocated and managed by Berkeley DB.</p> 51<p>The elements of the DBT structure are defined as follows:</p> 52<br> 53<b>void *<a name="data">data</a>;</b><ul compact><li>A pointer to a byte string.</ul> 54<b>u_int32_t <a name="size">size</a>;</b><ul compact><li>The length of <b>data</b>, in bytes.</ul> 55<b>u_int32_t <a name="ulen">ulen</a>;</b><ul compact><li>The size of the user's buffer (to which <b>data</b> refers), in bytes. 56This location is not written by the Berkeley DB functions. 57<p>Note that applications can determine the length of a record by setting 58the <b>ulen</b> field to 0 and checking the return value in the 59<b>size</b> field. See the DB_DBT_USERMEM flag for more information.</p></ul> 60<b>u_int32_t <a name="dlen">dlen</a>;</b><ul compact><li>The length of the partial record being read or written by the application, 61in bytes. See the DB_DBT_PARTIAL flag for more information.</ul> 62<b>u_int32_t <a name="doff">doff</a>;</b><ul compact><li>The offset of the partial record being read or written by the application, 63in bytes. See the DB_DBT_PARTIAL flag for more information.</ul> 64<b>u_int32_t flags;</b><ul compact><li>The <b>flags</b> parameter must be set to 0 or by bitwise inclusively <b>OR</b>'ing together one 65or more of the following values: 66<br> 67<b><a name="DB_DBT_MALLOC">DB_DBT_MALLOC</a></b><ul compact><li>When this flag is set, Berkeley DB will allocate memory for the returned key 68or data item (using <b>malloc</b>(3), or the user-specified malloc 69function), and return a pointer to it in the <b>data</b> field of the 70key or data DBT structure. Because any allocated memory becomes the 71responsibility of the calling application, the caller must determine 72whether memory was allocated using the returned value of the 73<b>data</b> field. 74<p>It is an error to specify more than one of DB_DBT_MALLOC, 75DB_DBT_REALLOC, and DB_DBT_USERMEM.</p></ul> 76<b><a name="DB_DBT_REALLOC">DB_DBT_REALLOC</a></b><ul compact><li>When this flag is set Berkeley DB will allocate memory for the returned key 77or data item (using <b>realloc</b>(3), or the user-specified realloc 78function), and return a pointer to it in the <b>data</b> field of the 79key or data DBT structure. Because any allocated memory becomes the 80responsibility of the calling application, the caller must determine 81whether memory was allocated using the returned value of the 82<b>data</b> field. 83<p>The difference between DB_DBT_MALLOC and DB_DBT_REALLOC 84is 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 86instead of the application doing repeated free/malloc calls.</p> 87<p>It is an error to specify more than one of DB_DBT_MALLOC, 88DB_DBT_REALLOC, and DB_DBT_USERMEM.</p></ul> 89<a name="3"><!--meow--></a> 90<b><a name="DB_DBT_USERMEM">DB_DBT_USERMEM</a></b><ul compact><li>The <b>data</b> field of the key or data structure must refer to 91memory that is at least <b>ulen</b> bytes in length. If the length of 92the requested item is less than or equal to that number of bytes, the 93item is copied into the memory to which the <b>data</b> field refers. 94Otherwise, the <b>size</b> field is set to the length needed for the 95requested item, and the error DB_BUFFER_SMALL is returned. 96<p>It is an error to specify more than one of DB_DBT_MALLOC, 97DB_DBT_REALLOC, and DB_DBT_USERMEM.</p></ul> 98<b><a name="DB_DBT_PARTIAL">DB_DBT_PARTIAL</a></b><ul compact><li>Do partial retrieval or storage of an item. If the calling application 99is doing a get, the <b>dlen</b> bytes starting <b>doff</b> bytes from 100the beginning of the retrieved data record are returned as if they 101comprised the entire record. If any or all of the specified bytes do 102not exist in the record, the get is successful, and any existing bytes 103are returned. 104<p>For example, if the data portion of a retrieved record was 100 bytes, 105and a partial retrieval was done using a DBT having a <b>dlen</b> 106field of 20 and a <b>doff</b> field of 85, the get call would succeed, 107the <b>data</b> field would refer to the last 15 bytes of the record, 108and the <b>size</b> field would be set to 15.</p> 109<p>If the calling application is doing a put, the <b>dlen</b> bytes 110starting <b>doff</b> bytes from the beginning of the specified key's 111data record are replaced by the data specified by the <b>data</b> and 112<b>size</b> structure elements. If <b>dlen</b> is smaller than 113<b>size</b>, the record will grow; if <b>dlen</b> is larger than 114<b>size</b>, the record will shrink. If the specified bytes do not 115exist, the record will be extended using nul bytes as necessary, and 116the put call will succeed.</p> 117<p>It is an error to attempt a partial put using the <a href="/api_c/db_put.html">DB->put</a> function 118in a database that supports duplicate records. 119Partial puts in databases supporting duplicate records must be done 120using a <a href="/api_c/dbc_put.html">DBcursor->put</a> function.</p> 121<p>It is an error to attempt a partial put with differing <b>dlen</b> and 122<b>size</b> values in Queue or Recno databases with fixed-length records.</p> 123<p>For example, if the data portion of a retrieved record was 100 bytes, 124and a partial put was done using a DBT having a <b>dlen</b> field of 20, 125a <b>doff</b> field of 85, and a <b>size</b> field of 30, the resulting 126record would be 115 bytes in length, where the last 30 bytes would be 127those specified by the put call.</p></ul> 128<b><a name="DB_DBT_APPMALLOC">DB_DBT_APPMALLOC</a></b><ul compact><li>After an application-supplied callback routine passed to either 129<a href="/api_c/db_associate.html">DB->associate</a> or <a href="/api_c/db_set_append_recno.html">DB->set_append_recno</a> is executed, the 130<b>data</b> field of a DBT may refer to memory allocated with 131<b>malloc</b>(3) or <b>realloc</b>(3). In that case, the 132callback sets the <a href="/api_c/dbt_class.html#DB_DBT_APPMALLOC">DB_DBT_APPMALLOC</a> flag in the DBT so 133that Berkeley DB will call <b>free</b>(3) to deallocate the memory when it 134is no longer required.</ul> 135<b><a name="DB_DBT_MULTIPLE">DB_DBT_MULTIPLE</a></b><ul compact><li>Set in a secondary key creation callback routine passed to 136<a href="/api_c/db_associate.html">DB->associate</a> to indicate that multiple secondary keys should be 137associated with the given primary key/data pair. If set, the 138<b>size</b> field indicates the number of secondary keys and the 139<b>data</b> field refers to an array of that number of DBT 140structures. 141<p>The <a href="/api_c/dbt_class.html#DB_DBT_APPMALLOC">DB_DBT_APPMALLOC</a> flag may be set on any of the DBT 142structures to indicate that their <b>data</b> field needs to be 143freed.</p></ul> 144<br></ul> 145<br> 146</tt> 147<table width="100%"><tr><td><br></td><td align=right> 148<a href="/api_c/api_core.html"><img src="/images/api.gif" alt="API"></a><a href="/ref/toc.html"><img src="/images/ref.gif" alt="Ref"></a> 149</td></tr></table> 150<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 151</body> 152</html> 153
