зеркало из https://github.com/mozilla/gecko-dev.git
495 строки
24 KiB
HTML
495 строки
24 KiB
HTML
<HTML>
|
|
<HEAD>
|
|
<TITLE>Dbc</TITLE>
|
|
</HEAD>
|
|
<BODY BGCOLOR=white>
|
|
<H1>Dbc</H1>
|
|
<HR SIZE=1 NOSHADE>
|
|
<PRE>
|
|
<!-- Manpage converted by man2html 3.0.1 -->
|
|
<B>#include</B> <B><db</B>_<B>cxx.h></B>
|
|
|
|
<B>int</B>
|
|
<B>Dbc::close(void);</B>
|
|
|
|
<B>int</B>
|
|
<B>Dbc::del(u</B>_<B>int32</B>_<B>t</B> <B>flags);</B>
|
|
|
|
<B>int</B>
|
|
<B>Dbc::get(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>Dbc::put(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 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 <B><A HREF="db_intro.html">db_intro(3)</A></B>.
|
|
|
|
This manual page describes the specific details of the
|
|
cursor support for the access methods in <B><A HREF="Db.html">Db(3)</A></B>.
|
|
|
|
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 <B><A HREF="Db.html">Db(3)</A></B>, 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 <B><A HREF="Db.html">Db(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 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 <B><A HREF="Db.html">Db(3)</A></B>) 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 <B><A HREF="DbException.html">DbException(3)</A></B> 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 <B><A HREF="DbException.html">DbException(3)</A></B> 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
|
|
<B><A HREF="Dbt.html">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
|
|
Db::open in <B><A HREF="Db.html">Db(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="Dbt.html">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
|
|
Db::open in <B><A HREF="Db.html">Db(3)</A></B>).
|
|
|
|
Otherwise, the Dbc::get method throws a
|
|
<B><A HREF="DbException.html">DbException(3)</A></B> 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 <B><A HREF="Db.html">Db(3)</A></B> 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 <B><A HREF="Db.html">Db(3)</A></B> 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
|
|
<B><A HREF="DbException.html">DbException(3)</A></B> 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.
|
|
|
|
|
|
</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 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.
|
|
|
|
|
|
</PRE>
|
|
<H2>ERRORS</H2><PRE>
|
|
Methods marked as returning errno will, by default, throw
|
|
an exception that encapsulates the error information. The
|
|
default error behavior can be changed, see <B><A HREF="DbException.html">DbException(3)</A></B>.
|
|
|
|
The Dbc::close method may fail and throw a <B><A HREF="DbException.html">DbException(3)</A></B>
|
|
|
|
or return errno for any of the errors specified for the
|
|
following DB and library functions: <B><A HREF="DbLock.html">DbLock::get(3)</A></B>,
|
|
<B><A HREF="DbLock.html">DbLock::put(3)</A></B>, <B><A HREF="DbLockTab.html">DbLockTab::id(3)</A></B>, <B><A HREF="DbLockTab.html">DbLockTab::vec(3)</A></B>,
|
|
<B><A HREF="DbLog.html">DbLog::put(3)</A></B>, <B><A HREF="DbMpoolFile.html">DbMpoolFile::get(3)</A></B>, <B><A HREF="DbMpoolFile.html">DbMpoolFile::put(3)</A></B>,
|
|
<B><A HREF="DbMpoolFile.html">DbMpoolFile::set(3)</A></B>, <B>calloc(3)</B>, <B>fcntl(2)</B>, <B>fflush(3)</B>,
|
|
<B>malloc(3)</B>, <B>memcpy(3)</B>, <B>memmove(3)</B>, <B>memset(3)</B>, <B>realloc(3)</B>,
|
|
and <B>strerror(3)</B>.
|
|
|
|
In addition, the Dbc::close method may fail and throw a
|
|
<B><A HREF="DbException.html">DbException(3)</A></B> 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 <B><A HREF="DbException.html">DbException(3)</A></B>
|
|
|
|
or return errno for any of the errors specified for the
|
|
following DB and library functions: <B><A HREF="Db.html">Db::del(3)</A></B>,
|
|
<B><A HREF="DbLock.html">DbLock::get(3)</A></B>, <B><A HREF="DbLock.html">DbLock::put(3)</A></B>, <B><A HREF="DbLockTab.html">DbLockTab::id(3)</A></B>,
|
|
<B><A HREF="DbLockTab.html">DbLockTab::vec(3)</A></B>, <B><A HREF="DbLog.html">DbLog::put(3)</A></B>, <B><A HREF="DbMpoolFile.html">DbMpoolFile::get(3)</A></B>,
|
|
<B><A HREF="DbMpoolFile.html">DbMpoolFile::put(3)</A></B>, <B><A HREF="DbMpoolFile.html">DbMpoolFile::set(3)</A></B>, <B>calloc(3)</B>,
|
|
<B>fcntl(2)</B>, <B>fflush(3)</B>, <B>malloc(3)</B>, <B>memcpy(3)</B>, <B>memmove(3)</B>,
|
|
<B>memset(3)</B>, <B>realloc(3)</B>, and <B>strerror(3)</B>.
|
|
|
|
In addition, the Dbc::del method may fail and throw a
|
|
<B><A HREF="DbException.html">DbException(3)</A></B> 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 <B><A HREF="DbException.html">DbException(3)</A></B>
|
|
|
|
or return errno for any of the errors specified for the
|
|
following DB and library functions: <B><A HREF="Db.html">Db::get(3)</A></B>,
|
|
<B><A HREF="DbLock.html">DbLock::get(3)</A></B>, <B><A HREF="DbLock.html">DbLock::put(3)</A></B>, <B><A HREF="DbLockTab.html">DbLockTab::id(3)</A></B>,
|
|
<B><A HREF="DbLockTab.html">DbLockTab::vec(3)</A></B>, <B><A HREF="DbLog.html">DbLog::put(3)</A></B>, <B><A HREF="DbMpoolFile.html">DbMpoolFile::get(3)</A></B>,
|
|
<B><A HREF="DbMpoolFile.html">DbMpoolFile::put(3)</A></B>, <B><A HREF="DbMpoolFile.html">DbMpoolFile::set(3)</A></B>, <B>calloc(3)</B>,
|
|
<B>fcntl(2)</B>, <B>fflush(3)</B>, <B>malloc(3)</B>, <B>memcmp(3)</B>, <B>memcpy(3)</B>,
|
|
<B>memmove(3)</B>, <B>memset(3)</B>, <B>realloc(3)</B>, and <B>strerror(3)</B>.
|
|
|
|
In addition, the Dbc::get method may fail and throw a
|
|
<B><A HREF="DbException.html">DbException(3)</A></B> 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 <B><A HREF="Db.html">Db(3)</A></B> 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 <B><A HREF="DbException.html">DbException(3)</A></B>
|
|
|
|
or return errno for any of the errors specified for the
|
|
following DB and library functions: <B><A HREF="DbLock.html">DbLock::get(3)</A></B>,
|
|
<B><A HREF="DbLock.html">DbLock::put(3)</A></B>, <B><A HREF="DbLockTab.html">DbLockTab::id(3)</A></B>, <B><A HREF="DbLockTab.html">DbLockTab::vec(3)</A></B>,
|
|
<B><A HREF="DbLog.html">DbLog::put(3)</A></B>, <B><A HREF="DbMpoolFile.html">DbMpoolFile::get(3)</A></B>, <B><A HREF="DbMpoolFile.html">DbMpoolFile::put(3)</A></B>,
|
|
<B><A HREF="DbMpoolFile.html">DbMpoolFile::set(3)</A></B>, <B>calloc(3)</B>, <B>fcntl(2)</B>, <B>fflush(3)</B>,
|
|
<B>malloc(3)</B>, <B>memcmp(3)</B>, <B>memcpy(3)</B>, <B>memmove(3)</B>, <B>memset(3)</B>,
|
|
<B>realloc(3)</B>, and <B>strerror(3)</B>.
|
|
|
|
In addition, the Dbc::put method may fail and throw a
|
|
<B><A HREF="DbException.html">DbException(3)</A></B> 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.
|
|
|
|
|
|
</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_internal.html">db_internal(3)</A></B>, <B><A HREF="db_thread.html">db_thread(3)</A></B>, <B><A HREF="Db.html">Db(3)</A></B>, <B><A HREF="Dbc.html">Dbc(3)</A></B>, <B><A HREF="DbEnv.html">DbEnv(3)</A></B>,
|
|
<B><A HREF="DbException.html">DbException(3)</A></B>, <B><A HREF="DbInfo.html">DbInfo(3)</A></B>, <B><A HREF="DbLock.html">DbLock(3)</A></B>, <B><A HREF="DbLockTab.html">DbLockTab(3)</A></B>, <B><A HREF="DbLog.html">DbLog(3)</A></B>,
|
|
<B><A HREF="DbLsn.html">DbLsn(3)</A></B>, <B><A HREF="DbMpool.html">DbMpool(3)</A></B>, <B><A HREF="DbMpoolFile.html">DbMpoolFile(3)</A></B>, <B><A HREF="Dbt.html">Dbt(3)</A></B>, <B><A HREF="DbTxn.html">DbTxn(3)</A></B>,
|
|
<B><A HREF="DbTxnMgr.html">DbTxnMgr(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>
|