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)