480 lines
23 KiB
HTML
480 lines
23 KiB
HTML
<HTML>
|
|
<HEAD>
|
|
<TITLE>db_cursor</TITLE>
|
|
</HEAD>
|
|
<BODY BGCOLOR=white>
|
|
<H1>db_cursor</H1>
|
|
<HR SIZE=1 NOSHADE>
|
|
<PRE>
|
|
<!-- Manpage converted by man2html 3.0.1 -->
|
|
<B>#include</B> <B><db.h></B>
|
|
|
|
<B>int</B>
|
|
<B>DBcursor->c</B>_<B>close(DBC</B> <B>*cursor);</B>
|
|
|
|
<B>int</B>
|
|
<B>DBcursor->c</B>_<B>del(DBC</B> <B>*cursor,</B> <B>u</B>_<B>int32</B>_<B>t</B> <B>flags);</B>
|
|
|
|
<B>int</B>
|
|
<B>DBcursor->c</B>_<B>get(DBC</B> <B>*cursor,</B> <B>DBT</B> <B>*key,</B> <B>DBT</B> <B>*data,</B> <B>u</B>_<B>int32</B>_<B>t</B> <B>flags);</B>
|
|
|
|
<B>int</B>
|
|
<B>DBcursor->c</B>_<B>put(DBC</B> <B>*,</B> <B>DBT</B> <B>*key,</B> <B>DBT</B> <B>*data,</B> <B>u</B>_<B>int32</B>_<B>t</B> <B>flags);</B>
|
|
|
|
|
|
</PRE>
|
|
<H2>DESCRIPTION</H2><PRE>
|
|
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
|
|
functions, 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 <B><A HREF="db_intro.html">db_intro(3)</A></B>.
|
|
|
|
This manual page describes the specific details of the
|
|
cursor support for the DB access methods.
|
|
|
|
The db_cursor 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 the cursor function of a DB structure returned by
|
|
<B><A HREF="db_open.html">db_open(3)</A></B>, 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,
|
|
cursors are only valid within the context of a single
|
|
transaction, the one specified during the cursor call
|
|
described in <B><A HREF="db_open.html">db_open(3)</A></B>. 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 txn_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
|
|
function (see <B><A HREF="db_open.html">db_open(3)</A></B>) 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, accessed through the DBC
|
|
structure. 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, u_int32_t 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_KEYEMPTY if the element
|
|
has already been deleted.
|
|
|
|
int (*c_get)(DBC *cursor, DBT *key, DBT *data, u_int32_t
|
|
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.
|
|
|
|
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 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
|
|
value of 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
|
|
values, the value of 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_KEYEMPTY.
|
|
|
|
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 the database is a recno database and the
|
|
requested key exists, but was never explicitly
|
|
created by the application or was later deleted,
|
|
the c_get function returns DB_KEYEMPTY.
|
|
|
|
If no matching keys are found, the c_get
|
|
function 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
|
|
<B><A HREF="db_dbt.html">db_dbt(3)</A></B>. 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
|
|
<B><A HREF="db_open.html">db_open(3)</A></B>).
|
|
|
|
DB_GET_RECNO
|
|
Return the record number associated with the
|
|
cursor. The record number will be returned in
|
|
the data DBT as described in <B><A HREF="db_dbt.html">db_dbt(3)</A></B>. 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
|
|
<B><A HREF="db_open.html">db_open(3)</A></B>).
|
|
|
|
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
|
|
cursor will be unchanged.
|
|
|
|
int (*c_put)(DBC *, DBT *key, DBT *data, u_int32_t flags);
|
|
A pointer to a function 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 structure referenced by the
|
|
parameter key. The initial value of the key
|
|
parameter is ignored. See <B><A HREF="db_open.html">db_open(3)</A></B> 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. 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 structure referenced
|
|
by the parameter key. The initial value of the
|
|
key parameter is ignored. See <B><A HREF="db_open.html">db_open(3)</A></B> 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
|
|
referenced 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
|
|
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 c_put
|
|
function will return DB_KEYEMPTY.
|
|
|
|
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
|
|
cursor 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.
|
|
|
|
|
|
</PRE>
|
|
<H2>CURSOR STABILITY</H2><PRE>
|
|
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 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.
|
|
|
|
|
|
</PRE>
|
|
<H2>ERRORS</H2><PRE>
|
|
The DBcursor->c_close function may fail and return errno
|
|
for any of the errors specified for the following DB and
|
|
library functions: <B>calloc(3)</B>, <B>fcntl(2)</B>, <B>fflush(3)</B>,
|
|
<B><A HREF="db_lock.html">lock_get(3)</A></B>, <B><A HREF="db_lock.html">lock_id(3)</A></B>, <B><A HREF="db_lock.html">lock_put(3)</A></B>, <B><A HREF="db_lock.html">lock_vec(3)</A></B>,
|
|
<B><A HREF="db_log.html">log_put(3)</A></B>, <B>malloc(3)</B>, <B>memcpy(3)</B>, <B>memmove(3)</B>,
|
|
<B><A HREF="db_mpool.html">memp_fget(3)</A></B>, <B><A HREF="db_mpool.html">memp_fput(3)</A></B>, <B><A HREF="db_mpool.html">memp_fset(3)</A></B>, <B>memset(3)</B>,
|
|
<B>realloc(3)</B>, and <B>strerror(3)</B>.
|
|
|
|
In addition, the DBcursor->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 DBcursor->c_del function may fail and return errno for
|
|
any of the errors specified for the following DB and
|
|
library functions: <B><A HREF="db_open.html">DB->del(3)</A></B>, <B>calloc(3)</B>, <B>fcntl(2)</B>,
|
|
<B>fflush(3)</B>, <B><A HREF="db_lock.html">lock_get(3)</A></B>, <B><A HREF="db_lock.html">lock_id(3)</A></B>, <B><A HREF="db_lock.html">lock_put(3)</A></B>,
|
|
<B><A HREF="db_lock.html">lock_vec(3)</A></B>, <B><A HREF="db_log.html">log_put(3)</A></B>, <B>malloc(3)</B>, <B>memcpy(3)</B>, <B>memmove(3)</B>,
|
|
<B><A HREF="db_mpool.html">memp_fget(3)</A></B>, <B><A HREF="db_mpool.html">memp_fput(3)</A></B>, <B><A HREF="db_mpool.html">memp_fset(3)</A></B>, <B>memset(3)</B>,
|
|
<B>realloc(3)</B>, and <B>strerror(3)</B>.
|
|
|
|
In addition, the DBcursor->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 DBcursor->c_get function may fail and return errno for
|
|
any of the errors specified for the following DB and
|
|
library functions: <B><A HREF="db_open.html">DB->get(3)</A></B>, <B>calloc(3)</B>, <B>fcntl(2)</B>,
|
|
<B>fflush(3)</B>, <B><A HREF="db_lock.html">lock_get(3)</A></B>, <B><A HREF="db_lock.html">lock_id(3)</A></B>, <B><A HREF="db_lock.html">lock_put(3)</A></B>,
|
|
<B><A HREF="db_lock.html">lock_vec(3)</A></B>, <B><A HREF="db_log.html">log_put(3)</A></B>, <B>malloc(3)</B>, <B>memcmp(3)</B>, <B>memcpy(3)</B>,
|
|
<B>memmove(3)</B>, <B><A HREF="db_mpool.html">memp_fget(3)</A></B>, <B><A HREF="db_mpool.html">memp_fput(3)</A></B>, <B><A HREF="db_mpool.html">memp_fset(3)</A></B>,
|
|
<B>memset(3)</B>, <B>realloc(3)</B>, and <B>strerror(3)</B>.
|
|
|
|
In addition, the DBcursor->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 <B><A HREF="db_open.html">db_open(3)</A></B>
|
|
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 DBcursor->c_put function may fail and return errno for
|
|
any of the errors specified for the following DB and
|
|
library functions: <B>calloc(3)</B>, <B>fcntl(2)</B>, <B>fflush(3)</B>,
|
|
<B><A HREF="db_lock.html">lock_get(3)</A></B>, <B><A HREF="db_lock.html">lock_id(3)</A></B>, <B><A HREF="db_lock.html">lock_put(3)</A></B>, <B><A HREF="db_lock.html">lock_vec(3)</A></B>,
|
|
<B><A HREF="db_log.html">log_put(3)</A></B>, <B>malloc(3)</B>, <B>memcmp(3)</B>, <B>memcpy(3)</B>, <B>memmove(3)</B>,
|
|
<B><A HREF="db_mpool.html">memp_fget(3)</A></B>, <B><A HREF="db_mpool.html">memp_fput(3)</A></B>, <B><A HREF="db_mpool.html">memp_fset(3)</A></B>, <B>memset(3)</B>,
|
|
<B>realloc(3)</B>, and <B>strerror(3)</B>.
|
|
|
|
In addition, the DBcursor->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.
|
|
|
|
|
|
</PRE>
|
|
<H2>SEE ALSO</H2><PRE>
|
|
<B><A HREF="db_archive.html">db_archive(1)</A></B>, <B><A HREF="db_checkpoint.html">db_checkpoint(1)</A></B>, <B><A HREF="db_deadlock.html">db_deadlock(1)</A></B>, <B><A HREF="db_dump.html">db_dump(1)</A></B>,
|
|
<B><A HREF="db_load.html">db_load(1)</A></B>, <B><A HREF="db_recover.html">db_recover(1)</A></B>, <B><A HREF="db_stat.html">db_stat(1)</A></B>, <B><A HREF="db_intro.html">db_intro(3)</A></B>,
|
|
<B><A HREF="db_appinit.html">db_appinit(3)</A></B>, <B><A HREF="db_cursor.html">db_cursor(3)</A></B>, <B><A HREF="db_dbm.html">db_dbm(3)</A></B>, <B><A HREF="db_internal.html">db_internal(3)</A></B>,
|
|
<B><A HREF="db_lock.html">db_lock(3)</A></B>, <B><A HREF="db_log.html">db_log(3)</A></B>, <B><A HREF="db_mpool.html">db_mpool(3)</A></B>, <B><A HREF="db_open.html">db_open(3)</A></B>, <B><A HREF="db_thread.html">db_thread(3)</A></B>,
|
|
<B><A HREF="db_txn.html">db_txn(3)</A></B>
|
|
|
|
</PRE>
|
|
<HR SIZE=1 NOSHADE>
|
|
<ADDRESS>
|
|
Man(1) output converted with
|
|
<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
|
|
</ADDRESS>
|
|
</BODY>
|
|
</HTML>
|