--- name: "db_dbt" section: "3db" platform: "linux" package: "libdb2-dev" version: "2.4.14-1" release: "Debian 2.1 (Slink)" platforms: ["linux"] url: "https://new.carta.tech/db_dbt" --- # db\_dbt(3db) DB key/data pairs ## NAME db\_dbt - DB key/data pairs ## SYNOPSIS **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;** ## KEY/DATA PAIRS Storage and retrieval for the DB access methods are based on key/data pairs. Both key and data items are represented by the DBT data structure. Key and data byte strings may reference strings of essentially unlimited length, although any two keys must fit into available memory at the same time so that they may be compared, and any one data item must fit into available memory so that it may be returned. In order to ensure compatibility with future releases of 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 [*bzero*(3)](/bzero/3.md) or [*memset*(3)](/memset/3.md). By default, the *flags* structure element is expected to be 0. In this default case, when being provided a key or data item by the application, the DB package expects the *data* structure element to point to a byte string of *size* bytes. When returning a key/data item to the application, the DB package will store into the *data* structure element a pointer to a byte string of *size* bytes. **By default,** **the memory referenced by this stored pointer is only valid until the next** **call to the DB package using the DB handle returned by** *db\_open*. **The access methods provide no guarantees about byte string alignment,** **and applications are responsible for maintaining any necessary alignment.** Use the DB\_DBT\_USERMEM flag to cause returned items to be placed in memory of arbitrary alignment. The elements of the DBT structure are defined as follows: - void \*data; A pointer to a byte string.\ - u\_int32\_t size; The length of *data*, in bytes. - u\_int32\_t ulen; The size of the user's buffer (referenced by *data*), in bytes. This location is not written by the DB functions. See the DB\_DBT\_USERMEM flag for more information. - u\_int32\_t dlen; The length of the partial record being read or written by the application, in bytes. See the DB\_DBT\_PARTIAL flag for more information. - u\_int32\_t doff; The offset of the partial record being read or written by the application, in bytes. See the DB\_DBT\_PARTIAL flag for more information. - u\_int32\_t flags; The flags value is specified by **or**'ing together one or more of the following values: - DB\_DBT\_MALLOC Ignored except when retrieving information from a database, e.g., a *DB-\>get* or *DBcursor-\>c\_get* call. This flag causes DB to allocate memory for the returned key or data item (using [*malloc*(3)](/malloc/3.md), or the user-specified malloc function) and return a pointer to it in the *data* field of the key or data DBT structure. The allocated memory becomes the responsibility of the calling application. It is an error to specify both DB\_DBT\_MALLOC and DB\_DBT\_USERMEM. - DB\_DBT\_USERMEM Ignored except when retrieving information from a database, e.g., a *DB-\>get* or *DBcursor-\>c\_get* call. The *data* field of the key or data structure must reference 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 referenced by the *data* field. Otherwise, an error is returned, the *size* field is set to the length needed for the requested item, and the *errno* variable is set to ENOMEM. It is an error to specify both DB\_DBT\_MALLOC and DB\_DBT\_USERMEM. - DB\_DBT\_PARTIAL Ignored except when specified for a data parameter, where this flag causes the 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 the existing bytes or 0 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 reference 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, and 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 *DB-\>put* function in a database that supports duplicate records. Partial puts in databases supporting duplicate records must be done using a *db\_cursor*(3) function. It is an error to attempt a partial put with differing *dlen* and *size* values in a recno database 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. The default algorithm of associating returned key or data items with the DB handle returned by *db\_open*(3) will obviously not work when DB handles are being used concurrently by multiple threads within a process, i.e, when DB\_THREAD was specified to *db\_open*(3). **When multiple threads are using the returned DB handle concurrently,** **either the DB\_DBT\_MALLOC or DB\_DBT\_USERMEM flags must be specified** **for any DBT used for key or data retrieval.** ## LOGICAL RECORD NUMBERS In all cases for the recno access method, and when calling the *db-\>get* and *cursor-\>c\_get* functions with the DB\_SET\_RECNO flag specified, the *data* field of the key must be a pointer to a memory location of type *db\_recno\_t*, as typedef'd in the \ include file. This type is a 32-bit unsigned type, (which limits the number of logical records in a recno database, and the maximum logical record which may be directly retrieved from a btree database, to 4,294,967,296). The *size* field of the key should be the size of that type, e.g., in the C programming language, \`\`sizeof(db\_recno\_t)''. Logical record numbers are 1-based, not 0-based, i.e., the first record in the database is record number 1. ## BUGS The DB access methods provide no guarantees about byte string alignment, and applications are responsible for maintaining any necessary alignment. The name DBT is a mnemonic for \`\`data base thang'', and was used because noone could think of a reasonable name that wasn't already in use somewhere else. ## SEE ALSO The DB library is a family of groups of functions that provides a modular programming interface to transactions and record-oriented file access. The library includes support for transactions, locking, logging and file page caching, as well as various indexed access methods. Many of the functional groups (e.g., the file page caching functions) are useful independent of the other DB functions, although some functional groups are explicitly based on other functional groups (e.g., transactions and logging). For a general description of the DB package, see *db\_intro*(3). [*db\_archive*(1)](/db_archive/1.md), [*db\_checkpoint*(1)](/db_checkpoint/1.md), [*db\_deadlock*(1)](/db_deadlock/1.md), [*db\_dump*(1)](/db_dump/1.md), [*db\_load*(1)](/db_load/1.md), [*db\_recover*(1)](/db_recover/1.md), [*db\_stat*(1)](/db_stat/1.md), *db\_intro*(3), *db\_appinit*(3), *db\_cursor*(3), *db\_dbm*(3), *db\_internal*(3), *db\_lock*(3), *db\_log*(3), *db\_mpool*(3), *db\_open*(3), *db\_thread*(3), *db\_txn*(3)