--- name: "Dbc" section: "3db" platform: "linux" package: "libdb2++-dev" version: "2.4.14-1" release: "Debian 2.1 (Slink)" platforms: ["linux"] url: "https://new.carta.tech/Dbc" --- # Dbc(3db) database sequential access functions ## NAME Dbc - database sequential access functions ## SYNOPSIS ``` #include int Dbc::close(void); int Dbc::del(u_int32_t flags); int Dbc::get(Dbt *key, Dbt *data, u_int32_t flags); int Dbc::put(Dbt *key, Dbt *data, u_int32_t flags); ``` ## DESCRIPTION The DB library is a family of classes 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 classes (e.g., the file page caching class) are useful independent of the other DB classes, although some classes are explicitly based on other classes (e.g., transactions and logging). For a general description of the DB package, see *db\_intro*(3). This manual page describes the specific details of the cursor support for the access methods in *Db(3)*. The *Dbc* functions are the library interface supporting sequential access to the records stored by the access methods of the Db library. Cursors are created by calling *Db::cursor* method described in *Db*(3), which returns a pointer to a Dbc object. Each cursor maintains positioning information within a set of key/data pairs. In the presence of transactions, cursors are only valid within the context of a single transaction, the one specified during the *Db::cursor* call described in *Db*(3). All cursor operations will be executed in the context of that transaction. Before aborting or committing a transaction, all cursors used within that transaction must be closed. In the presence of transactions, the application must call *DbTxn::abort* if any of the cursor operations returns that a deadlock (EAGAIN) or system failure occurred. When locking is enabled, page locks are retained between consecutive cursor calls. For this reason, in the presence of locking, applications should discard cursors as soon as they are done with them. Calling the *Db::close* method (see *Db*(3)) discards any cursors opened in the context of a particular Db object returned by the *Db::open* call. The methods of the Dbc are defined as follows: - int Dbc::close(); A method that discards the cursor. No further references to the Dbc object should be made. - The *Dbc::close* method throws a *DbException*(3) or returns the value of *errno* on failure and 0 on success. - int Dbc::del(u\_int32\_t flags); A method 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 *Dbc::del* method throws a *DbException*(3) or returns the value of *errno* on failure, 0 on success, and DB\_KEYEMPTY if the element has already been deleted. - int Dbc::get(Dbt \*key, Dbt \*data, u\_int32\_t flags); A method that retrieves key/data pairs from the database. The address and length of the key are returned in the object referenced by *key* (except for the case of the DB\_SET flag where the *key* object is unchanged), and the address and length of the data are returned in the object 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. In recno databases, missing entries (i.e., entries that were never explicitly created or that were created and then deleted), will be skipped during a sequential scan. If multiple threads or processes insert items into the same database file without using locking, the results are undefined. For more detail, see the section 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 values, the first data item in the set of duplicates is returned. - If the database is empty, the *Dbc::get* method 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 *Dbc::get* method 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 value of the key may not change. - If the cursor is already on the last record in the database, the *Dbc::get* method 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 values, the value of the key may not change. - If the cursor is already on the first record in the database, the *Dbc::get* method 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 *Dbc::get* method will return DB\_KEYEMPTY. - If the cursor is not yet initialized, the *Dbc::get* method 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, *Dbc::get* will return the first data item for the given key. - If the database is a recno database and the requested key exists, but was never explicitly created by the application or was later deleted, the *Dbc::get* method returns DB\_KEYEMPTY. - If no matching keys are found, the *Dbc::get* method 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 as well as the data item, 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 (as determined by the comparison function), permitting partial key matches and range searches. - - DB\_SET\_RECNO Move the cursor to the specific numbered record of the database, and return the associated key/data pair. The *data* field of the specified *key* must be a pointer to a memory location from which a *db\_recno\_t* may be read, as described in *Dbt*(3). This memory location will be read to determine the record to be retrieved. For DB\_SET\_RECNO to be specified, the underlying database must be of type btree and it must have been created with the DB\_RECNUM flag (see *Db::open* in *Db*(3)). - - DB\_GET\_RECNO Return the record number associated with the cursor. The record number will be returned in the data Dbt as described in *Dbt*(3). The *key* parameter is ignored. For DB\_GET\_RECNO to be specified, the underlying database must be of type btree and it must have been created with the DB\_RECNUM flag (see *Db::open* in *Db*(3)). - Otherwise, the *Dbc::get* method throws a *DbException*(3) or returns the value of *errno* on failure and 0 on success. - If *Dbc::get* fails for any reason, the state of the cursor will be unchanged. - int Dbc::put(Dbt \*key, Dbt \*data, u\_int32\_t flags); A method that stores key/data pairs into the database. - The *flags* parameter must be set to exactly one of the following values: - - DB\_AFTER 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 after the current cursor position. It is an error to specify DB\_AFTER if the underlying btree or hash database was not created with the DB\_DUP flag. The *key* parameter is ignored. - In the case of the recno access method, it is an error to specify DB\_AFTER if the underlying recno database was not created with the DB\_RENUMBER flag. If the DB\_RENUMBER flag was specified, 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 object referenced by the parameter *key*. The initial value of the *key* parameter is ignored. See *Db::open* in *Db*(3) for more information. - If the cursor is not yet initialized, the *Dbc::put* method 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. It is an error to specify DB\_BEFORE if the underlying btree or hash database was not created with the DB\_DUP flag. The *key* parameter is ignored. - In the case of the recno access method, it is an error to specify DB\_BEFORE if the underlying recno database was not created with the DB\_RENUMBER flag. If the DB\_RENUMBER flag was specified, 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 object referenced by the parameter *key*. The initial value of the *key* parameter is ignored. See *Db::open* in *Db*(3) for more information. - If the cursor is not yet initialized, the *Dbc::put* method will return EINVAL. - - DB\_CURRENT Overwrite the data of the key/data pair referenced by the cursor with the specified data item. - The *key* parameter is ignored. - If the cursor is not yet initialized, the *Dbc::put* method will return EINVAL. - - DB\_KEYFIRST In the case of the btree and hash access methods, 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 *Dbc::put* method will return DB\_KEYEMPTY. - Otherwise, the *Dbc::put* method throws a *DbException*(3) or returns the value of *errno* on failure and 0 on success. - If *Dbc::put* fails for any reason, the state of the cursor will be unchanged. If *Dbc::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 control (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 cursor. In the presence of transactions, the access method calls between *DbTxnMgr::begin* and *DbTxn::abort* or *DbTxn::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 Methods marked as returning *errno* will, by default, throw an exception that encapsulates the error information. The default error behavior can be changed, see *DbException*(3). The *Dbc::close* method may fail and throw a *DbException*(3) or return *errno* for any of the errors specified for the following DB and library functions: DbLock::get(3), DbLock::put(3), DbLockTab::id(3), DbLockTab::vec(3), DbLog::put(3), DbMpoolFile::get(3), DbMpoolFile::put(3), DbMpoolFile::set(3), [calloc(3)](/calloc/3.md), [fcntl(2)](/fcntl/2.md), [fflush(3)](/fflush/3.md), [malloc(3)](/malloc/3.md), [memcpy(3)](/memcpy/3.md), [memmove(3)](/memmove/3.md), [memset(3)](/memset/3.md), [realloc(3)](/realloc/3.md), and [strerror(3)](/strerror/3.md). In addition, the *Dbc::close* method may fail and throw a *DbException*(3) or 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 *Dbc::del* method may fail and throw a *DbException*(3) or return *errno* for any of the errors specified for the following DB and library functions: Db::del(3), DbLock::get(3), DbLock::put(3), DbLockTab::id(3), DbLockTab::vec(3), DbLog::put(3), DbMpoolFile::get(3), DbMpoolFile::put(3), DbMpoolFile::set(3), [calloc(3)](/calloc/3.md), [fcntl(2)](/fcntl/2.md), [fflush(3)](/fflush/3.md), [malloc(3)](/malloc/3.md), [memcpy(3)](/memcpy/3.md), [memmove(3)](/memmove/3.md), [memset(3)](/memset/3.md), [realloc(3)](/realloc/3.md), and [strerror(3)](/strerror/3.md). In addition, the *Dbc::del* method may fail and throw a *DbException*(3) or 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 *Dbc::get* method may fail and throw a *DbException*(3) or return *errno* for any of the errors specified for the following DB and library functions: Db::get(3), DbLock::get(3), DbLock::put(3), DbLockTab::id(3), DbLockTab::vec(3), DbLog::put(3), DbMpoolFile::get(3), DbMpoolFile::put(3), DbMpoolFile::set(3), [calloc(3)](/calloc/3.md), [fcntl(2)](/fcntl/2.md), [fflush(3)](/fflush/3.md), [malloc(3)](/malloc/3.md), [memcmp(3)](/memcmp/3.md), [memcpy(3)](/memcpy/3.md), [memmove(3)](/memmove/3.md), [memset(3)](/memset/3.md), [realloc(3)](/realloc/3.md), and [strerror(3)](/strerror/3.md). In addition, the *Dbc::get* method may fail and throw a *DbException*(3) or 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* method described in *Db*(3) 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 *Dbc::put* method may fail and throw a *DbException*(3) or return *errno* for any of the errors specified for the following DB and library functions: DbLock::get(3), DbLock::put(3), DbLockTab::id(3), DbLockTab::vec(3), DbLog::put(3), DbMpoolFile::get(3), DbMpoolFile::put(3), DbMpoolFile::set(3), [calloc(3)](/calloc/3.md), [fcntl(2)](/fcntl/2.md), [fflush(3)](/fflush/3.md), [malloc(3)](/malloc/3.md), [memcmp(3)](/memcmp/3.md), [memcpy(3)](/memcpy/3.md), [memmove(3)](/memmove/3.md), [memset(3)](/memset/3.md), [realloc(3)](/realloc/3.md), and [strerror(3)](/strerror/3.md). In addition, the *Dbc::put* method may fail and throw a *DbException*(3) or 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_archive/1.md), [*db\_checkpoint*(1)](/db_checkpoint/1.md), [*db\_deadlock*(1)](/db_deadlock/1.md), [*db\_dump*(1)](/db_dump/1.md), [*db\_load*(1)](/db_load/1.md), [*db\_recover*(1)](/db_recover/1.md), [*db\_stat*(1)](/db_stat/1.md), *db\_intro*(3), *db\_internal*(3), *db\_thread*(3), *Db*(3), *Dbc*(3), *DbEnv*(3), *DbException*(3), *DbInfo*(3), *DbLock*(3), *DbLockTab*(3), *DbLog*(3), *DbLsn*(3), *DbMpool*(3), *DbMpoolFile*(3), *Dbt*(3), *DbTxn*(3), *DbTxnMgr*(3)