db_dbt
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 repre-
sented by the DBT data structure.
Key and data byte strings may reference strings of essen-
tially 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 explic-
itly 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) or memset(3).
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 maintain-
ing any necessary alignment. Use the DB_DBT_USERMEM flag
to cause returned items to be placed in memory of arbi-
trary 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 writ-
ten 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 writ-
ten 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 get call. This flag causes
DB to allocate memory for the returned key or
data item (using malloc(3), or the user-speci-
fied malloc function) and return a pointer to it
in the data field of the key or data DBT struc-
ture. The allocated memory becomes the respon-
sibility 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 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 parame-
ter, 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 the specified
bytes do not exist in the record, the get is
successful, and 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 suc-
ceed, 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 begin-
ning 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_open returned put function in a database
that supports duplicate records. Partial puts
in databases supporting duplicate records must
be done using a db_cursor 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 result-
ing 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 obvi-
ously 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_GETREC
flag specified, the data field of the key must be a
pointer to a memory location of type db_recno_t, as type-
def'd in the <db.h> 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 func-
tions, 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_checkpoint(1), db_deadlock(1), db_dump(1),
db_intro(3), db_load(1), db_recover(1), db_stat(1),
db_appinit(3), db_cursor(3), db_dbm(3), db_lock(3), db_log(3),
db_mpool(3), db_open(3), db_txn(3)