#include <db_cxx.h>

void *Dbt::get_data() const;
void Dbt::set_data(void *);

u_int32_t Dbt::get_size() const;
void Dbt::set_size(u_int32_t);

u_int32_t Dbt::get_ulen() const;
void Dbt::set_ulen(u_int32_t);

u_int32_t Dbt::get_dlen() const;
void Dbt::set_dlen(u_int32_t);

u_int32_t Dbt::get_doff() const;
void Dbt::set_doff(u_int32_t);

u_int32_t Dbt::get_flags() const;
void Dbt::set_flags(u_int32_t);

Dbt::Dbt(void *data, size_t size);
Dbt::Dbt();
Dbt::~Dbt();
Dbt::Dbt(const Dbt &);
Dbt::Dbt &operator = (const Dbt &);

Description

This manual page describes the specific details of the Dbt class, used to encode keys and data items in a database.

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 Dbt objects.

Key and data byte strings may reference strings of essentially unlimited length. See Database limits for more information.

The Dbt class provides simple access to an underlying data structure, whose elements can be examined or changed using the set_ or get_ methods. The remainder of the manual page sometimes refers to these accesses using the underlying name, e.g., simply ulen instead of Dbt::get_ulen and Dbt::set_ulen.

The constructors set all elements of the underlying structure to zero. The constructor with two arguments has the effect of setting all elements to zero except for the specified data and size elements. In the case where the flags structure element is 0, when being provided a key or data item by the application, the Berkeley DB package expects the data object to point to a byte string of size bytes. When returning a key/data item to the application, the Berkeley DB package will store into the data object a pointer to a byte string of size bytes.

The elements of the structure underlying the Dbt class are defined as follows:

void *data;

A pointer to a byte string. This element is accessed using Dbt::get_data and Dbt::set_data, and may be initialized using one of the constructors.

int offset;

The number of bytes offset into the data array to determine the portion of the array actually used. This element is accessed using dbt_get_offset and dbt_set_offset.

u_int32_t size;

The length of data, in bytes. This element is accessed using Dbt::get_size and Dbt::set_size, and may be initialized using the constructor with two arguments.

u_int32_t ulen;

The size of the user's buffer (referenced by data), in bytes. This location is not written by the Db methods.

Note that applications can determine the length of a record by setting the ulen to 0 and checking the return value found in size. See the DB_DBT_USERMEM flag for more information.

This element is accessed using Dbt::get_ulen and Dbt::set_ulen.

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. This element is accessed using Dbt::get_dlen, and Dbt::set_dlen.

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. This element is accessed using Dbt::get_doff and Dbt::set_doff.

u_int32_t flags;

This element is accessed using Dbt::get_flags and Dbt::set_flags. The flags value is specified by logically 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 Dbc::get call. This flag causes Db to allocate memory for the returned key or data item (using malloc(3) or the user-specified malloc method) and return a pointer to it in the data field of the key or data Dbt object. 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 Dbc::get call. The data field of the key or data object 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, the size field is set to the length needed for the requested item, and the error ENOMEM is returned.

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 objects. 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 method in a database that supports duplicate records. Partial puts in databases supporting duplicate records must be done using a Dbc method. 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.

Retrieved key/data permanence: When using the non-cursor Berkeley DB calls to retrieve key/data items (e.g., Db::get), 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 Db::open. (This includes any 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, either the DB_DBT_MALLOC or DB_DBT_USERMEM flag must be specified for any non-cursor Dbt used for key or data retrieval.) When using the cursor Berkeley DB calls to retrieve key/data items (e.g., Dbc::get), 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 Db::cursor.

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 and DB_DBT_USERMEM flags may be used to store returned items in memory of arbitrary alignment.

Logical Record Numbers