зеркало из https://github.com/mozilla/gecko-dev.git
226 строки
12 KiB
HTML
226 строки
12 KiB
HTML
<HTML>
|
|
<HEAD>
|
|
<TITLE>db_dbt</TITLE>
|
|
</HEAD>
|
|
<BODY BGCOLOR=white>
|
|
<H1>db_dbt</H1>
|
|
<HR SIZE=1 NOSHADE>
|
|
<PRE>
|
|
<!-- Manpage converted by man2html 3.0.1 -->
|
|
<B>typedef</B> <B>struct</B> <B>{</B>
|
|
<B>void</B> <B>*data;</B>
|
|
<B>u</B>_<B>int32</B>_<B>t</B> <B>size;</B>
|
|
<B>u</B>_<B>int32</B>_<B>t</B> <B>ulen;</B>
|
|
<B>u</B>_<B>int32</B>_<B>t</B> <B>dlen;</B>
|
|
<B>u</B>_<B>int32</B>_<B>t</B> <B>doff;</B>
|
|
<B>u</B>_<B>int32</B>_<B>t</B> <B>flags;</B>
|
|
<B>}</B> <B>DBT;</B>
|
|
|
|
|
|
</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 the DBT data structure.
|
|
|
|
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.
|
|
|
|
In order to ensure compatibility with future releases of
|
|
DB, all fields of the DBT structure that are not
|
|
explicitly set should be initialized to 0 before the first
|
|
time the structure is used. Do this by declaring the
|
|
structure external or static, or by calling the C library
|
|
routine <B>bzero(3)</B> or <B>memset(3)</B>.
|
|
|
|
By default, the flags structure element is expected to be
|
|
0. In this default case, when being provided a key or
|
|
data item by the application, the DB package expects the
|
|
data structure element 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 structure element
|
|
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.
|
|
|
|
The elements of the DBT structure are defined as follows:
|
|
|
|
void *data;
|
|
A pointer to a byte string.
|
|
|
|
u_int32_t size;
|
|
The length of data, in bytes.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
u_int32_t 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 DBcursor->c_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
|
|
function) and return a pointer to it in the data
|
|
field of the key or data DBT structure. 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 DBcursor->c_get
|
|
call. The data field of the key or data
|
|
structure 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 structure elements. 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 function in a database that supports
|
|
duplicate records. Partial puts in databases
|
|
supporting duplicate records must be done using
|
|
a <B><A HREF="db_cursor.html">db_cursor(3)</A></B> function. 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_open.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_open.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 cursor->c_get functions with the
|
|
DB_SET_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.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>
|
|
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>.
|
|
|
|
<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>
|