db_cursor



NAME

       db_cursor - database sequential access functions


SYNOPSIS

       #include <db.h>


DESCRIPTION

       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(3).   For a description of the access methods, see
       db_open(3).  For a description of  cursors  within  access
       methods,  see  db_cursor(3);  transactions, see db_txn(3);
       the lock manager, see db_lock(3);  the  log  manager,  see
       db_log(3);  the memory pool manager, see db_mpool(3).  For
       information on configuring the DB  transaction  processing
       environment,  and DB support utilities, see db_appinit(3),
       db_archive(1),   db_checkpoint(1),   db_deadlock(1)    and
       db_recover(1).   For  information on dumping and reloading
       DB databases, see db_dump(1) and db_load(1).

       This manual page describes the  specific  details  of  the
       cursor support for the access methods.

       The db_cursor functions are the library interface support-
       ing sequential access to the records stored by the  access
       methods of the DB library.  Cursors are created by calling
       the  cursor  function  of  a  DB  structure  returned   by
       db_open(3), which returns a pointer to a DBC structure.

       Each cursor maintains positioning information within a set
       of key/data pairs.  In the presence of transactions,  cur-
       sors  are only valid within the context of a single trans-
       action, the one specified during the cursor call described
       in  db_open(3).  All cursor operations will be executed in
       the context of that transaction.  Before aborting or  com-
       mitting a transaction, all cursors used within that trans-
       action must be closed.  In the presence  of  transactions,
       the  application  must call txn_abort if any of the cursor
       operations returns that a system failure occurred.

       When locking is enabled, page locks are  retained  between
       consecutive  cursor  calls.  For this reason, in the pres-
       ence of locking, applications should  discard  cursors  as
       soon  as  they  are  done with them.  Calling the db close
       function (see db_open(3)) discards any cursors  opened  in
       the  context  of a particular DB structure returned by the
       db_open call.

       The cursor has an associated set of  functions  to  access
       elements in the database.

       The elements of the DBC structure are defined as follows:

       int (*c_close)(DBC *cursor);
            A pointer to a function that discards the cursor.  No
            further references to the cursor should be made.

            The c_close function returns the value  of  errno  on
            failure and 0 on success.

       int (*c_del)(DBC *cursor, int flags);
            A  pointer  to  a  function that deletes the key/data
            pair currently referenced by the cursor.

            The flags parameter is currently unused, and must  be
            set to 0.

            The  cursor  position is unchanged after a delete and
            subsequent calls to cursor  functions  expecting  the
            cursor to reference an existing key will fail.

            The  c_del  function  returns  the  value of errno on
            failure, 0 on success, and DB_NOTFOUND if the current
            element has already been deleted.

       int (*c_get)(DBC *cursor, DBT *key, DBT *data, int flags);
            A pointer to a function that retrieves key/data pairs
            from the database.  The address and length of the key
            are returned  in  the  structure  referenced  by  key
            (except for the case of the DB_SET flag where the key
            structure is unchanged), and the address  and  length
            of  the data are returned in the structure referenced
            by data.

            Modifications to the  database  during  a  sequential
            scan  will  be  reflected  in  the scan, i.e. records
            inserted behind a cursor will not be  returned  while
            records  inserted  in  front  of  a  cursor  will  be
            returned.

            If multiple threads or processes  insert  items  into
            the  same  database  file  without using locking, the
            results are undefined.  For more detail, see the sec-
            tion below on cursor stability.

            The parameter flags must be set to exactly one of the
            following values:

            DB_FIRST
                 The  cursor  is  set  to  reference  the   first
                 key/data  pair of the database, and that pair is
                 returned.  In the presence of duplicate key val-
                 ues,  the  first  data item in the set of dupli-
                 cates is returned.

                 If the database is  empty,  the  c_get  function
                 will return DB_NOTFOUND.

            DB_LAST
                 The cursor is set to reference the last key/data
                 pair of the database, and that pair is returned.
                 In  the  presence  of  duplicate key values, the
                 last data item  in  the  set  of  duplicates  is
                 returned.

                 If  the  database  is  empty, the c_get function
                 will return DB_NOTFOUND.

            DB_NEXT
                 If the cursor is not yet initialized, DB_NEXT is
                 identical to DB_FIRST.

                 Otherwise,  move the cursor to the next key/data
                 pair of the database, and that pair is returned.
                 In the presence of duplicate key values, the key
                 may not change.

                 If the cursor is already on the last  record  in
                 the  database,  the  c_get  function will return
                 DB_NOTFOUND.

            DB_PREV
                 If the cursor is not yet initialized, DB_PREV is
                 identical to DB_LAST.

                 Otherwise,  move  the  cursor  to  the  previous
                 key/data pair of the database, and that pair  is
                 returned.  In the presence of duplicate key val-
                 ues, the key may not change.

                 If the cursor is already on the first record  in
                 the  database,  the  c_get  function will return
                 DB_NOTFOUND.

            DB_CURRENT
                 Return the key/data pair currently referenced by
                 the cursor.

                 If  the  cursor  key/data pair has been deleted,
                 the c_get function will return DB_NOTFOUND.

                 If the cursor is not yet initialized, the  c_get
                 function will return EINVAL.

            DB_SET
                 Move  the  cursor to the specified key/data pair
                 of the database, and return the datum associated
                 with the given key.

                 In  the  presence of duplicate key values, c_get
                 will return the first data item  for  the  given
                 key.

                 If  no  matching keys are found, the c_get func-
                 tion will return DB_NOTFOUND.

            DB_SET_RANGE
                 The DB_SET_RANGE flag is identical to the DB_SET
                 flag,  except  that the key is returned, and, in
                 the  case  of  the  btree  access  method,   the
                 returned  key/data  pair  is  the  smallest  key
                 greater than or equal to the specified key, per-
                 mitting  partial key matches and range searches.

            Otherwise, the c_get function returns  the  value  of
            errno on failure and 0 on success.

            If  c_get fails for any reason, the state of the cur-
            sor will be unchanged.

       int (*c_put)(DBC *, DBT *key, DBT *data, int flags);
            A pointer to a function that  stores  key/data  pairs
            into  the database.  Neither of the structures refer-
            enced by key and data are modified.

            The flags parameter must be set to exactly one of the
            following values:

            DB_AFTER
                 In  the  case of the btree and hash access meth-
                 ods, insert the data element as a duplicate ele-
                 ment  of  the key referenced by the cursor.  The
                 new element appears immediately after  the  cur-
                 rent  cursor  position.   The  key  parameter is
                 ignored.

                 In the case of the recno access  method,  a  new
                 key  is  created, all records after the inserted
                 item are automatically renumbered, and  the  key
                 of  the  new record is returned in the structure
                 referenced by the parameter key.  See db_open(3)
                 for more information.

                 If  the cursor is not yet initialized, the c_put
                 function will return EINVAL.

            DB_BEFORE
                 In  the  case  of  the  btree  and  hash  access
                 methods,  insert the data element as a duplicate
                 element of the key  referenced  by  the  cursor.
                 The  new  element appears immediately before the
                 current cursor position.  The key  parameter  is
                 ignored.

                 In  the  case  of the recno access method, a new
                 key is  created,  the  current  record  and  all
                 records  after  it are automatically renumbered,
                 and the key of the new record is returned in the
                 structure  referenced by the parameter key.  See
                 db_open(3) for more information.

                 If the cursor is not yet initialized, the  c_put
                 function will return EINVAL.

            DB_CURRENT
                 Overwrite  the  data of the key/data pair refer-
                 enced by the  cursor  with  the  specified  data
                 item.

                 The key parameter is ignored.

                 If  the cursor is not yet initialized, the c_put
                 function will return EINVAL.

            DB_KEYFIRST
                 In the case of the btree and hash  access  meth-
                 ods, insert the specified key/data pair into the
                 database.  If the  key  already  exists  in  the
                 database, the inserted data item is added as the
                 first of the data items for that key.

                 The DB_KEYFIRST flag may not be specified to the
                 recno access method.

            DB_KEYLAST
                 Insert  the  specified  key/data  pair  into the
                 database.  If the  key  already  exists  in  the
                 database, the inserted data item is added as the
                 last of the data items for that key.

                 The DB_KEYLAST flag may not be specified to  the
                 recno access method.

            If  the  cursor  record  has  been deleted, the c_put
            function will return DB_NOTFOUND.

            Otherwise, the c_put function returns  the  value  of
            errno on failure and 0 on success.

            If  c_put fails for any reason, the state of the cur-
            sor will be unchanged.  If c_put succeeds and an item
            is  inserted  into the database, the cursor is always
            positioned to reference the newly inserted item.


CURSOR STABILITY

       In the absence of locking, no guarantees  are  made  about
       the   stability  of  cursors  in  different  processes  or
       threads.  However, the  btree  and  recno  access  methods
       guarantee  that cursor operations, interspersed with other
       cursor or non-cursor operations in the same thread of con-
       trol  (i.e.,  thread  or  single-threaded  process),  will
       always return keys in order  and  will  return  each  non-
       deleted  key/data  pair  exactly  once.   Because the hash
       access method uses a dynamic hashing algorithm, it  cannot
       guarantee any form of stability in the presence of inserts
       and deletes unless locking is performed.

       If locking was specified when the DB file was opened,  but
       transactions are not in effect, the access methods provide
       repeatable reads with respect to the cursor.  That  is,  a
       DB_CURRENT  call on the cursor is guaranteed to return the
       same record as was returned on the last call to  the  cur-
       sor.

       In  the  presence of transactions, the access method calls
       between txn_begin  and  txn_abort  or  txn_commit  provide
       degree  3  consistency.   For all access methods, a cursor
       scan of the database performed within  the  context  of  a
       transaction  is  guaranteed  to  return each key/data pair
       once and only once, except in  the  following  case.   If,
       while  performing  a  cursor  scan  using  the hash access
       method, the transaction performing the scan inserts a  new
       pair  into  the  database,  it  is possible that duplicate
       key/data pairs will be returned.


ERRORS

       The c_close function may fail and return errno for any  of
       the  errors  specified  for  the  following DB and library
       functions: fflush(3),  fprintf(3),  free(3),  lock_get(3),
       lock_put(3),   lock_vec(3),  log_put(3),  malloc(3),  mem-
       cpy(3),   memp_fget(3),   memp_fput(3),   memset(3)    and
       vsnprintf(3).


       In  addition,  the  c_close  function  may fail and return
       errno for the following conditions:

       [EAGAIN]
            A lock was unavailable.

       [EPERM]
            Database corruption  was  detected.   All  subsequent
            database  calls  (other  than  db->close) will return
            EPERM.

       The c_del function may fail and return errno  for  any  of
       the  errors  specified  for  the  following DB and library
       functions: fflush(3),  fprintf(3),  free(3),  lock_get(3),
       lock_put(3),   lock_vec(3),  log_put(3),  malloc(3),  mem-
       cpy(3),   memp_fget(3),   memp_fput(3),   memset(3)    and
       vsnprintf(3).


       In  addition, the c_del function may fail and return errno
       for the following conditions:

       [EAGAIN]
            A lock was unavailable.

       [EINVAL]
            An invalid flag value or parameter was specified.

       [EPERM]
            Database corruption  was  detected.   All  subsequent
            database  calls  (other  than  db->close) will return
            EPERM.

       The c_get function may fail and return errno  for  any  of
       the  errors  specified  for  the  following DB and library
       functions:    dbp->db_malloc,    fflush(3),    fprintf(3),
       lock_get(3),  lock_put(3),  lock_vec(3),  malloc(3),  mem-
       cpy(3),   memp_fget(3),   memp_fput(3),   realloc(3)   and
       vsnprintf(3).


       In  addition, the c_get function may fail and return errno
       for the following conditions:

       [EAGAIN]
            A lock was unavailable.

       [EINVAL]
            An invalid flag value or parameter was specified.

            The DB_THREAD flag was specified  to  the  db_open(3)
            function    and    neither   the   DB_DBT_MALLOC   or
            DB_DBT_USERMEM flags were set in the DBT.

       [EPERM]
            Database corruption  was  detected.   All  subsequent
            database  calls  (other  than  db->close) will return
            EPERM.

       The c_put function may fail and return errno  for  any  of
       the  errors  specified  for  the  following DB and library
       functions:    abort(3),     dbp->db_malloc,     fflush(3),
       fprintf(3),     free(3),     lock_get(3),     lock_put(3),
       lock_vec(3), log_put(3), malloc(3), memcpy(3), memmove(3),
       memp_fget(3), memp_fput(3), memp_fset(3), memset(3), real-
       loc(3), t->bt_prefix and vsnprintf(3).
       In addition, the c_put function may fail and return  errno
       for the following conditions:

       [EACCES]
            An attempt was made to modify a read-only database.

       [EAGAIN]
            A lock was unavailable.

       [EINVAL]
            An invalid flag value or parameter was specified.

       [EPERM]
            Database  corruption  was  detected.   All subsequent
            database calls (other  than  db->close)  will  return
            EPERM.


SEE ALSO

       db_archive(1), db_checkpoint(1), db_deadlock(1), db_dump(1),
       db_load(1), db_recover(1), db(3), db_appinit(3), db_cursor(3),
       db_dbm(3), db_lock(3), db_log(3), db_mpool(3), db_open(3),
       db_txn(3)