+IBerkeley DB: Dbt[P

Dbt




Key/Data Pairs



UStorage and retrieval for the Berkeley DB access methods are based on key/data pairs.BBoth key and data items are represented by the DBT data structure.D(The name DBT is a mnemonic for data base thang, and was usedEbecause noone could think of a reasonable name that wasn't already inuse somewhere else.)

typedef struct {

} DBT;

HKey and data byte strings may reference strings of essentially unlimitedIlength. See Database limitsfor more information.

EIn order to ensure compatibility with future releases of Berkeley DB,Eall fields of the DBT structure that are not explicitly set should be=initialized to 0 before the first time the structure is used.6Do this by declaring the structure external or static,#or by calling the C library routine$bzero(3) or memset(3).

GBy default, the flags structure element is expected to be 0. In@this default case, when being provided a key or data item by theNapplication, the Berkeley DB package expects the data structure elementAto point to a byte string of size bytes. When returning aMkey/data item to the application, the Berkeley DB package will store into theGdata structure element a pointer to a byte string of sizebytes.

9The elements of the DBT structure are defined as follows:

1

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 Berkeley DB functions.

FNote that applications can determine the length of a record by setting?the ulen field to 0 and checking the return value in theEsize field. See the DB_DBT_USERMEM flag for more information.d

u_int32_t dlen;
The length of the partial record being read or written by the application, in bytes.1See the DB_DBT_PARTIAL flag for more information.d

u_int32_t doff;
The offset of the partial record being read or written by the application, in bytes.1See the DB_DBT_PARTIAL flag for more information.n

u_int32_t flags;
The flags value is specified by logically OR'ing together one or more of thefollowing values:
[

DB_DBT_MALLOC
Ignored except when retrieving information from a database, e.g., amDB->get or DBcursor->c_get call.LThis flag causes Berkeley DB to allocate memory for the returned key or dataDitem (using malloc(3), or the user-specified malloc function)Fand return a pointer to it in the data field of the key or dataDBT structure.KThe 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., anDB->get, or DBcursor->c_get call.HThe data field of the key or data structure must reference memory-that is at least ulen bytes in length.HIf the length of the requested item is less than or equal to that number of bytes,Gthe item is copied into the memory referenced by the data field.DOtherwise, the size field is set to the length needed for the1requested item, and the error ENOMEM is returned.@It is an error to specify both DB_DBT_MALLOC and DB_DBT_USERMEM.L

DB_DBT_PARTIAL
Ignored except when specified for a data parameter,Cwhere this flag causes the partial retrieval or storage of an item.@If the calling application is doing a get, the dlen bytesCstarting 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,Ethe get is successful and the existing bytes or 0 bytes are returned.

EFor example, if the data portion of a retrieved record was 100 bytes,Aand a partial retrieval was done using a DBT having a dlenFfield of 20 and a doff field of 85, the get call would succeed,Fthe 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 bytesDstarting doff bytes from the beginning of the specified key'sAdata record are replaced by the data specified by the data#and size structure elements.AIf dlen is smaller than size, the record will grow,Fand if dlen is larger than size, the record will shrink.FIf the specified bytes do not exist, the record will be extended using6nul bytes as necessary, and the put call will succeed.

hIt is an error to attempt a partial put using the DB->get function.in a database that supports duplicate records.CPartial puts in databases supporting duplicate records must be doneHusing a DBcursor->c_put function.FIt is an error to attempt a partial put with differing dlen andAsize values in a recno database with fixed-length records.

EFor example, if the data portion of a retrieved record was 100 bytes,Hand a partial put was done using a DBT having a dlen field of 20,Ga doff field of 85, and a size field of 30, the resultingErecord would be 115 bytes in length, where the last 30 bytes would be those specified by the put call.




%Retrieved key/data permanence:MWhen using the non-cursor Berkeley DB calls to retrieve key/data items (e.g.,dDB->get), the memory referenced by the pointer stored into theADBT is only valid until the next call to Berkeley DB using the DBdhandle returned by db_open. (This includes any use of>the returned DB handle, including by another thread of controlIwithin the process. For this reason, when multiple threads are using the<returned DB handle concurrently, either the DB_DBT_MALLOC or<DB_DBT_USERMEM flag must be specified for any non-cursor DBTLused for key or data retrieval.) When using the cursor Berkeley DB calls topretrieve key/data items (e.g., DBcursor->c_get), the memory referenced by=the pointer into the DBT is only valid until the next call toaBerkeley DB using the DBC handle returned by DB->cursor.

OThe Berkeley DB access methods provide no guarantees about key/data byte stringGalignment, and applications are responsible for arranging any necessaryHalignment. The DB_DBT_MALLOC and DB_DBT_USERMEM flags may be used to6store returned items in memory of arbitrary alignment.

Logical Record Numbers

>In all cases for the recno access method, and when calling the{DB->get and DBcursor->c_get functions with the=DB_SET_RECNO flag specified, the data field of the keyAmust be a pointer to a memory location of type db_recno_t,r7as typedef'd in the #include <db.h> include file.e@This type is a 32-bit unsigned type, (which limits the number ofClogical records in a recno database, and the maximum logical recordsIwhich may be directly retrieved from a btree database, to 4,294,967,296).nGThe size field of the key should be the size of that type, i.e.,,9in the C programming language, sizeof(db_recno_t).

GLogical record numbers are 1-based, not 0-based, i.e., the first record #in the database is record number 1.patÿÿs are represented by the DBT data structure.D(The name DBT is a mnemonic for data base thang, and was usedEbecause noone could think of a reasonable name that wasn't already inuse somewhere else.)

typedef struct {