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.


            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 DB->get  or  DBcursor->c_get
                 call.   This  flag  causes DB to allocate memory
                 for the returned key or data  item  (using  mal-
                 loc(3),  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  struc-
                 ture 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 refer-
                 enced 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 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 suc-
                 ceed, the data field would reference the last 15
                 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 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_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 <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  program-
       ming 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

       db_archive(1), db_checkpoint(1), db_deadlock(1), db_dump(1),
       db_load(1), db_recover(1), db_stat(1), db_intro(3),
       db_appinit(3), db_cursor(3), db_dbm(3), db_jump(3), db_lock(3),
       db_log(3), db_mpool(3), db_open(3), db_thread(3), db_txn(3)