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)