зеркало из https://github.com/mozilla/gecko-dev.git
269 строки
14 KiB
HTML
269 строки
14 KiB
HTML
<HTML>
|
|
<HEAD>
|
|
<TITLE>Dbt</TITLE>
|
|
</HEAD>
|
|
<BODY BGCOLOR=white>
|
|
<H1>Dbt</H1>
|
|
<HR SIZE=1 NOSHADE>
|
|
<PRE>
|
|
<!-- Manpage converted by man2html 3.0.1 -->
|
|
<B>void</B> <B>*Dbt::get</B>_<B>data()</B> <B>const;</B>
|
|
<B>void</B> <B>Dbt::set</B>_<B>data(void</B> <B>*);</B>
|
|
|
|
<B>u</B>_<B>int32</B>_<B>t</B> <B>Dbt::get</B>_<B>size()</B> <B>const;</B>
|
|
<B>void</B> <B>Dbt::set</B>_<B>size(u</B>_<B>int32</B>_<B>t);</B>
|
|
|
|
<B>u</B>_<B>int32</B>_<B>t</B> <B>Dbt::get</B>_<B>ulen()</B> <B>const;</B>
|
|
<B>void</B> <B>Dbt::set</B>_<B>ulen(u</B>_<B>int32</B>_<B>t);</B>
|
|
|
|
<B>u</B>_<B>int32</B>_<B>t</B> <B>Dbt::get</B>_<B>dlen()</B> <B>const;</B>
|
|
<B>void</B> <B>Dbt::set</B>_<B>dlen(u</B>_<B>int32</B>_<B>t);</B>
|
|
|
|
<B>u</B>_<B>int32</B>_<B>t</B> <B>Dbt::get</B>_<B>doff()</B> <B>const;</B>
|
|
<B>void</B> <B>Dbt::set</B>_<B>doff(u</B>_<B>int32</B>_<B>t);</B>
|
|
|
|
<B>u</B>_<B>int32</B>_<B>t</B> <B>Dbt::get</B>_<B>flags()</B> <B>const;</B>
|
|
<B>void</B> <B>Dbt::set</B>_<B>flags(u</B>_<B>int32</B>_<B>t);</B>
|
|
|
|
<B>Dbt::Dbt(void</B> <B>*data,</B> <B>size</B>_<B>t</B> <B>size);</B>
|
|
<B>Dbt::Dbt();</B>
|
|
<B>Dbt::~Dbt();</B>
|
|
<B>Dbt::Dbt(const</B> <B>Dbt</B> <B>&);</B>
|
|
<B>Dbt::Dbt</B> <B>&operator</B> <B>=</B> <B>(const</B> <B>Dbt</B> <B>&);</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 Dbt class, used to encode keys and
|
|
data items in a database.
|
|
|
|
|
|
</PRE>
|
|
<H2>KEY/DATA PAIRS</H2><PRE>
|
|
Storage and retrieval for the Db access methods are based
|
|
on key/data pairs. Both key and data items are
|
|
represented by Dbt objects.
|
|
|
|
Key and data byte strings may reference strings of
|
|
essentially unlimited length, although any two keys must
|
|
fit into available memory at the same time so that they
|
|
may be compared, and any one data item must fit into
|
|
available memory so that it may be returned.
|
|
|
|
The Dbt class provides simple access to an underlying data
|
|
structure, whose elements can be examined or changed using
|
|
the set_ or get_ methods. The remainder of the manual
|
|
page sometimes refers to these accesses using the
|
|
underlying name, e.g., simply ulen instead of get_ulen and
|
|
set_ulen. The constructors set all elements of the
|
|
underlying structure to zero. The constructor with two
|
|
arguments has the effect of setting all elements to zero
|
|
except for the specified data and size elements. In the
|
|
case where the flags structure element is 0, when being
|
|
provided a key or data item by the application, the DB
|
|
package expects the data object to point to a byte string
|
|
of size bytes. When returning a key/data item to the
|
|
application, the DB package will store into the data
|
|
object a pointer to a byte string of size bytes. <B>By</B>
|
|
<B>default,</B> <B>the</B> <B>memory</B> <B>referenced</B> <B>by</B> <B>this</B> <B>stored</B> <B>pointer</B> <B>is</B>
|
|
<B>only</B> <B>valid</B> <B>until</B> <B>the</B> <B>next</B> <B>call</B> <B>to</B> <B>the</B> <B>DB</B> <B>package</B> <B>using</B> <B>the</B>
|
|
<B>Db</B> <B>handle</B> <B>returned</B> <B>by</B> Db::open.
|
|
|
|
<B>The</B> <B>access</B> <B>methods</B> <B>provide</B> <B>no</B> <B>guarantees</B> <B>about</B> <B>byte</B> <B>string</B>
|
|
<B>alignment,</B> <B>and</B> <B>applications</B> <B>are</B> <B>responsible</B> <B>for</B>
|
|
<B>maintaining</B> <B>any</B> <B>necessary</B> <B>alignment.</B> Use the
|
|
DB_DBT_USERMEM flag to cause returned items to be placed
|
|
in memory of arbitrary alignment. Although Java normally
|
|
maintains proper alignment of byte arrays, the set_offset
|
|
method can be used to specify unaligned addresses.
|
|
Unaligned address accesses that are not supported by the
|
|
underlying hardware may be reported as an exception, or
|
|
may stop the running Java program.
|
|
|
|
The elements of the structure underlying the Dbt class are
|
|
defined as follows:
|
|
|
|
void *data;
|
|
A pointer to a byte string. This element is accessed
|
|
using get_data and set_data, and may be initialized
|
|
using one of the constructors.
|
|
|
|
int offset;
|
|
The number of bytes offset into the data array to
|
|
determine the portion of the array actually used.
|
|
This element is accessed using get_offset and
|
|
set_offset.
|
|
|
|
u_int32_t size;
|
|
The length of data, in bytes. This element is
|
|
accessed using get_size and set_size, and may be
|
|
initialized using the constructor with two arguments.
|
|
|
|
u_int32_t ulen;
|
|
The size of the user's buffer (referenced by data),
|
|
in bytes. This location is not written by the Db
|
|
functions. See the DB_DBT_USERMEM flag for more
|
|
information. This element is accessed using get_ulen
|
|
and set_ulen.
|
|
|
|
u_int32_t dlen;
|
|
The length of the partial record being read or
|
|
written by the application, in bytes. See the
|
|
DB_DBT_PARTIAL flag for more information. This
|
|
element is accessed using get_dlen and set_dlen.
|
|
|
|
u_int32_t doff;
|
|
The offset of the partial record being read or
|
|
written by the application, in bytes. See the
|
|
DB_DBT_PARTIAL flag for more information. This
|
|
element is accessed using get_doff and set_doff.
|
|
|
|
u_int32_t flags;
|
|
This element is accessed using get_flags and
|
|
set_flags. The flags value is specified by <B>or</B>'ing
|
|
together one or more of the following values:
|
|
|
|
DB_DBT_MALLOC
|
|
Ignored except when retrieving information from
|
|
a database, e.g., a Db::get or Dbc::get call.
|
|
This flag causes Db to allocate memory for the
|
|
returned key or data item (using <B>malloc(3)</B>, or
|
|
the user-specified malloc method) and return a
|
|
pointer to it in the data field of the key or
|
|
data Dbt object. The allocated memory becomes
|
|
the responsibility of the calling application.
|
|
It is an error to specify both DB_DBT_MALLOC and
|
|
DB_DBT_USERMEM.
|
|
|
|
DB_DBT_USERMEM
|
|
Ignored except when retrieving information from
|
|
a database, e.g., a Db::get or Dbc::get call.
|
|
The data field of the key or data object must
|
|
reference memory that is at least ulen bytes in
|
|
length. If the length of the requested item is
|
|
less than or equal to that number of bytes, the
|
|
item is copied into the memory referenced by the
|
|
data field. Otherwise, an error is returned,
|
|
the size field is set to the length needed for
|
|
the requested item, and the errno variable is
|
|
set to ENOMEM. It is an error to specify both
|
|
DB_DBT_MALLOC and DB_DBT_USERMEM.
|
|
|
|
DB_DBT_PARTIAL
|
|
Ignored except when specified for a data
|
|
parameter, where this flag causes the partial
|
|
retrieval or storage of an item. If the calling
|
|
application is doing a get, the dlen bytes
|
|
starting doff bytes from the beginning of the
|
|
retrieved data record are returned as if they
|
|
comprised the entire record. If any or all of
|
|
the specified bytes do not exist in the record,
|
|
the get is successful and the existing bytes or
|
|
0 bytes are returned.
|
|
|
|
For example, if the data portion of a retrieved
|
|
record was 100 bytes, and a partial retrieval
|
|
was done using a Dbt having a dlen field of 20
|
|
and a doff field of 85, the get call would
|
|
succeed, the data field would reference the last
|
|
15 bytes of the record, and the size field would
|
|
be set to 15.
|
|
|
|
If the calling application is doing a put, the
|
|
dlen bytes starting doff bytes from the
|
|
beginning of the specified key's data record are
|
|
replaced by the data specified by the data and
|
|
size objects. If dlen is smaller than size, the
|
|
record will grow, and if dlen is larger than
|
|
size, the record will shrink. If the specified
|
|
bytes do not exist, the record will be extended
|
|
using nul bytes as necessary, and the put call
|
|
will succeed.
|
|
|
|
It is an error to attempt a partial put using
|
|
the Db::put method in a database that supports
|
|
duplicate records. Partial puts in databases
|
|
supporting duplicate records must be done using
|
|
a Db::cursor method. It is an error to attempt
|
|
a partial put with differing dlen and size
|
|
values in a recno database with fixed-length
|
|
records.
|
|
|
|
For example, if the data portion of a retrieved
|
|
record was 100 bytes, and a partial put was done
|
|
using a Dbt having a dlen field of 20, a doff
|
|
field of 85, and a size field of 30, the
|
|
resulting record would be 115 bytes in length,
|
|
where the last 30 bytes would be those specified
|
|
by the put call.
|
|
|
|
The default algorithm of associating returned key or data
|
|
items with the Db handle returned by <B><A HREF="Db.html">Db::open(3)</A></B> will
|
|
obviously not work when Db handles are being used
|
|
concurrently by multiple threads within a process, i.e,
|
|
when DB_THREAD was specified to <B><A HREF="Db.html">Db::open(3)</A></B>. <B>When</B>
|
|
<B>multiple</B> <B>threads</B> <B>are</B> <B>using</B> <B>the</B> <B>returned</B> <B>Db</B> <B>handle</B>
|
|
<B>concurrently,</B> <B>either</B> <B>the</B> <B>DB</B>_<B>DBT</B>_<B>MALLOC</B> <B>or</B> <B>DB</B>_<B>DBT</B>_<B>USERMEM</B>
|
|
<B>flags</B> <B>must</B> <B>be</B> <B>specified</B> <B>for</B> <B>any</B> <B>Dbt</B> <B>used</B> <B>for</B> <B>key</B> <B>or</B> <B>data</B>
|
|
<B>retrieval.</B>
|
|
|
|
|
|
</PRE>
|
|
<H2>LOGICAL RECORD NUMBERS</H2><PRE>
|
|
In all cases for the recno access method, and when calling
|
|
the Db::get and Dbc::get functions with the DB_GET_RECNO
|
|
flag specified, the data
|
|
|
|
field of the key must be a pointer to a memory location of
|
|
type db_recno_t, as typedef'd in the <db_cxx.h> include
|
|
file. This type is a 32-bit unsigned type, (which limits
|
|
the number of logical records in a recno database, and the
|
|
maximum logical record which may be directly retrieved
|
|
from a btree database, to 4,294,967,296). The size field
|
|
of the key should be the size of that type, e.g.,
|
|
|
|
in the C programming language, ``sizeof(db_recno_t)''.
|
|
|
|
Logical record numbers are 1-based, not 0-based, i.e., the
|
|
first record in the database is record number 1.
|
|
|
|
|
|
</PRE>
|
|
<H2>BUGS</H2><PRE>
|
|
The Db access methods provide no guarantees about byte
|
|
string alignment, and applications are responsible for
|
|
maintaining any necessary alignment.
|
|
|
|
The name Dbt is a mnemonic for ``data base thang'', and
|
|
was used because noone could think of a reasonable name
|
|
that wasn't already in use somewhere else.
|
|
|
|
|
|
</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>
|