зеркало из https://github.com/mozilla/gecko-dev.git
1249 строки
62 KiB
HTML
1249 строки
62 KiB
HTML
<HTML>
|
|
<HEAD>
|
|
<TITLE>db_open</TITLE>
|
|
</HEAD>
|
|
<BODY BGCOLOR=white>
|
|
<H1>db_open</H1>
|
|
<HR SIZE=1 NOSHADE>
|
|
<PRE>
|
|
<!-- Manpage converted by man2html 3.0.1 -->
|
|
<B>#include</B> <B><db.h></B>
|
|
|
|
<B>int</B>
|
|
<B>db</B>_<B>open(const</B> <B>char</B> <B>*file,</B> <B>DBTYPE</B> <B>type,</B> <B>u</B>_<B>int32</B>_<B>t</B> <B>flags,</B>
|
|
<B>int</B> <B>mode,</B> <B>DB</B>_<B>ENV</B> <B>*dbenv,</B> <B>DB</B>_<B>INFO</B> <B>*dbinfo,</B> <B>DB</B> <B>**dbpp);</B>
|
|
|
|
<B>int</B>
|
|
<B>DB->close(DB</B> <B>*db,</B> <B>u</B>_<B>int32</B>_<B>t</B> <B>flags);</B>
|
|
|
|
<B>int</B>
|
|
<B>DB->cursor(DB</B> <B>*db,</B> <B>DB</B>_<B>TXN</B> <B>*txnid,</B> <B>DBC</B> <B>**cursorp);</B>
|
|
|
|
<B>int</B>
|
|
<B>DB->del(DB</B> <B>*db,</B> <B>DB</B>_<B>TXN</B> <B>*txnid,</B> <B>DBT</B> <B>*key,</B> <B>u</B>_<B>int32</B>_<B>t</B> <B>flags);</B>
|
|
|
|
<B>int</B>
|
|
<B>DB->fd(DB</B> <B>*db,</B> <B>int</B> <B>*fdp);</B>
|
|
|
|
<B>int</B>
|
|
<B>DB->get(DB</B> <B>*db,</B> <B>DB</B>_<B>TXN</B> <B>*txnid,</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>DB->put(DB</B> <B>*db,</B> <B>DB</B>_<B>TXN</B> <B>*txnid,</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>DB->sync(DB</B> <B>*db,</B> <B>u</B>_<B>int32</B>_<B>t</B> <B>flags);</B>
|
|
|
|
<B>int</B>
|
|
<B>DB->stat(DB</B> <B>*db,</B> <B>void</B> <B>*sp,</B> <B>void</B> <B>*(*db</B>_<B>malloc)(size</B>_<B>t),</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 overall structure of the DB
|
|
library access methods.
|
|
|
|
The currently supported file formats are btree, hashed and
|
|
recno. The btree format is a representation of a sorted,
|
|
balanced tree structure. The hashed format is an
|
|
extensible, dynamic hashing scheme. The recno format
|
|
supports fixed or variable length records (optionally
|
|
retrieved from a flat text file).
|
|
|
|
Storage and retrieval for the DB access methods are based
|
|
on key/data pairs, or DBT structures as they are typedef'd
|
|
in the <db.h> include file. See <B><A HREF="db_dbt.html">db_dbt(3)</A></B> for specific
|
|
information on the structure and capabilities of a DBT.
|
|
|
|
The db_open function opens the database represented by
|
|
file for both reading and writing. Files never intended
|
|
to be shared or preserved on disk may be created by
|
|
setting the file parameter to NULL.
|
|
|
|
The db_open function copies a pointer to a DB structure
|
|
(as typedef'd in the <db.h> include file), into the memory
|
|
location referenced by dbpp. This structure includes a
|
|
set of functions to perform various database actions, as
|
|
described below. The db_open function returns the value
|
|
of errno on failure and 0 on success.
|
|
|
|
Note, while most of the access methods use file as the
|
|
name of an underlying file on disk, this is not
|
|
guaranteed. Also, calling db_open is a reasonably
|
|
expensive operation. (This is based on a model where the
|
|
DBMS keeps a set of files open for a long time rather than
|
|
opening and closing them on each query.)
|
|
|
|
The type argument is of type DBTYPE (as defined in the
|
|
<db.h> include file) and must be set to one of DB_BTREE,
|
|
DB_HASH, DB_RECNO or DB_UNKNOWN. If type is DB_UNKNOWN,
|
|
the database must already exist and db_open will then
|
|
determine if it is of type DB_BTREE, DB_HASH or DB_RECNO.
|
|
|
|
The flags and mode arguments specify how files will be
|
|
opened and/or created when they don't already exist. The
|
|
flags value is specified by <B>or</B>'ing together one or more of
|
|
the following values:
|
|
|
|
DB_CREATE
|
|
Create any underlying files, as necessary. If the
|
|
files do not already exist and the DB_CREATE flag is
|
|
not specified, the call will fail.
|
|
|
|
DB_NOMMAP
|
|
Do not map this file (see <B><A HREF="db_mpool.html">db_mpool(3)</A></B> for further
|
|
information).
|
|
|
|
DB_RDONLY
|
|
Open the database for reading only. Any attempt to
|
|
write the database using the access methods will fail
|
|
regardless of the actual permissions of any
|
|
underlying files.
|
|
|
|
DB_THREAD
|
|
Cause the DB handle returned by the db_open function
|
|
to be useable by multiple threads within a single
|
|
address space, i.e., to be ``free-threaded''.
|
|
|
|
DB_TRUNCATE
|
|
``Truncate'' the database if it exists, i.e., behave
|
|
as if the database were just created, discarding any
|
|
previous contents.
|
|
|
|
All files created by the access methods are created with
|
|
mode mode (as described in <B>chmod(2)</B>) and modified by the
|
|
process' umask value at the time of creation (see
|
|
<B>umask(2)</B>). The group ownership of created files is based
|
|
on the system and directory defaults, and is not further
|
|
specified by DB.
|
|
|
|
|
|
</PRE>
|
|
<H2>DB_ENV</H2><PRE>
|
|
The access methods make calls to the other subsystems in
|
|
the DB library based on the dbenv argument to db_open,
|
|
which is a pointer to a structure of type DB_ENV
|
|
(typedef'd in <db.h>). Applications will normally use the
|
|
same DB_ENV structure (initialized by <B><A HREF="db_appinit.html">db_appinit(3)</A></B>), as
|
|
an argument to all of the subsystems in the DB package.
|
|
|
|
References to the DB_ENV structure are maintained by DB,
|
|
so it may not be discarded until the last close function,
|
|
corresponding to an open function for which it was an
|
|
argument, has returned. In order to ensure compatibility
|
|
with future releases of DB, all fields of the DB_ENV
|
|
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>.
|
|
|
|
The fields of the DB_ENV structure used by db_open are
|
|
described below. If dbenv is NULL or any of its fields
|
|
are set to 0, defaults appropriate for the system are used
|
|
where possible.
|
|
|
|
The following fields in the DB_ENV structure may be
|
|
initialized before calling db_open:
|
|
|
|
DB_LOG *lg_info;
|
|
If modifications to the file being opened should be
|
|
logged, the lg_info field contains a return value
|
|
from the function log_open. If lg_info is NULL, no
|
|
logging is done by the DB access methods.
|
|
|
|
DB_LOCKTAB *lk_info;
|
|
If locking is required for the file being opened (as
|
|
is the case when multiple processes or threads are
|
|
accessing the same file), the lk_info field contains
|
|
a return value from the function lock_open. If
|
|
lk_info is NULL, no locking is done by the DB access
|
|
methods.
|
|
|
|
If both locking and transactions are being performed
|
|
(i.e., both lk_info and tx_info are non-NULL), the
|
|
transaction ID will be used as the locker ID. If
|
|
only locking is being performed, db_open will acquire
|
|
a locker ID from <B><A HREF="db_lock.html">lock_id(3)</A></B>, and will use it for all
|
|
locks required for this instance of db_open.
|
|
|
|
DB_MPOOL *mp_info;
|
|
If the cache for the file being opened should be
|
|
maintained in a shared buffer pool, the mp_info field
|
|
contains a return value from the function memp_open.
|
|
If mp_info is NULL, a memory pool may still be
|
|
created by DB, but it will be private to the
|
|
application and managed by DB.
|
|
|
|
DB_TXNMGR *tx_info;
|
|
If the accesses to the file being opened should take
|
|
place in the context of transactions (providing
|
|
atomicity and error recovery), the tx_info field
|
|
contains a return value from the function txn_open
|
|
(see <B><A HREF="db_txn.html">db_txn(3)</A></B>). If transactions are specified, the
|
|
application is responsible for making suitable calls
|
|
to txn_begin, txn_abort, and txn_commit. If tx_info
|
|
is NULL, no transaction support is done by the DB
|
|
access methods.
|
|
|
|
When the access methods are used in conjunction with
|
|
transactions, the application must abort the
|
|
transaction (using txn_abort) if any of the
|
|
transaction protected access method calls (i.e., any
|
|
calls other than open, close and sync) returns a
|
|
system error (e.g., deadlock, which returns EAGAIN).
|
|
As described by <B><A HREF="db_intro.html">db_intro(3)</A></B>, a system error is any
|
|
value greater than 0.
|
|
|
|
|
|
</PRE>
|
|
<H2>DB_INFO</H2><PRE>
|
|
The access methods are configured using the DB_INFO data
|
|
structure argument to db_open. The DB_INFO structure is
|
|
typedef'd in <db.h> and has a large number of fields, most
|
|
specific to a single access method, although a few are
|
|
shared. The fields that are common to all access methods
|
|
are listed here; those specific to an individual access
|
|
method are described below. No reference to the DB_INFO
|
|
structure is maintained by DB, so it is possible to
|
|
discard it as soon as the db_open call returns.
|
|
|
|
In order to ensure compatibility with future releases of
|
|
DB, all fields of the DB_INFO structure should be
|
|
initialized to 0 before the structure is used. Do this by
|
|
declaring the structure external or static, or by calling
|
|
the C library function <B>bzero(3)</B> or <B>memset(3)</B>.
|
|
|
|
If possible, defaults appropriate for the system are used
|
|
for the DB_INFO fields if dbinfo is NULL or any fields of
|
|
the DB_INFO structure are set to 0. The following DB_INFO
|
|
fields may be initialized before calling db_open:
|
|
|
|
size_t db_cachesize;
|
|
A suggested maximum size of the memory pool cache, in
|
|
bytes. If db_cachesize is 0, an appropriate default
|
|
is used. It is an error to specify both the mp_info
|
|
field and a non-zero db_cachesize.
|
|
|
|
<B>Note,</B> <B>the</B> <B>minimum</B> <B>number</B> <B>of</B> <B>pages</B> <B>in</B> <B>the</B> <B>cache</B> <B>should</B>
|
|
<B>be</B> <B>no</B> <B>less</B> <B>than</B> <B>10,</B> <B>and</B> <B>the</B> <B>access</B> <B>methods</B> <B>will</B> <B>fail</B>
|
|
<B>if</B> <B>an</B> <B>insufficiently</B> <B>large</B> <B>cache</B> <B>is</B> <B>specified.</B> In
|
|
addition, for applications that exhibit strong
|
|
locality in their data access patterns, increasing
|
|
the size of the cache can significantly improve
|
|
application performance.
|
|
|
|
int db_lorder;
|
|
The byte order for integers in the stored database
|
|
metadata. The number should represent the order as
|
|
an integer, for example, big endian order is the
|
|
number 4,321, and little endian order is the number
|
|
1,234. If db_lorder is 0, the host order of the
|
|
machine where the DB library was compiled is used.
|
|
|
|
The value of db_lorder is ignored except when
|
|
databases are being created. If a database already
|
|
exists, the byte order it uses is determined when the
|
|
file is read.
|
|
|
|
<B>The</B> <B>access</B> <B>methods</B> <B>provide</B> <B>no</B> <B>guarantees</B> <B>about</B> <B>the</B>
|
|
<B>byte</B> <B>ordering</B> <B>of</B> <B>the</B> <B>application</B> <B>data</B> <B>stored</B> <B>in</B> <B>the</B>
|
|
<B>database,</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>ordering.</B>
|
|
|
|
size_t db_pagesize;
|
|
The size of the pages used to hold items in the
|
|
database, in bytes. The minimum page size is 512
|
|
bytes and the maximum page size is 64K bytes. If
|
|
db_pagesize is 0, a page size is selected based on
|
|
the underlying filesystem I/O block size. The
|
|
selected size has a lower limit of 512 bytes and an
|
|
upper limit of 16K bytes.
|
|
|
|
void *(*db_malloc)(size_t);
|
|
The flag DB_DBT_MALLOC, when specified in the DBT
|
|
structure, will cause the DB library to allocate
|
|
memory which then becomes the responsibility of the
|
|
calling application. See <B><A HREF="db_dbt.html">db_dbt(3)</A></B> for more
|
|
information.
|
|
|
|
On systems where there may be multiple library
|
|
versions of malloc (notably Windows NT), specifying
|
|
the DB_DBT_MALLOC flag will fail because the DB
|
|
library will allocate memory from a different heap
|
|
than the application will use to free it. To avoid
|
|
this problem, the db_malloc field should be set to
|
|
point to the application's allocation routine. If
|
|
db_malloc is non-NULL, it will be used to allocate
|
|
the memory returned when the DB_DBT_MALLOC flag is
|
|
set. The db_malloc function must match the calling
|
|
conventions of the <B>malloc(3)</B> library routine.
|
|
|
|
|
|
</PRE>
|
|
<H2>BTREE</H2><PRE>
|
|
The btree data structure is a sorted, balanced tree
|
|
structure storing associated key/data pairs. Searches,
|
|
insertions, and deletions in the btree will all complete
|
|
in O (lg base N) where base is the average number of keys
|
|
per page. Often, inserting ordered data into btrees
|
|
results in pages that are half-full. This implementation
|
|
has been modified to make ordered (or inverse ordered)
|
|
insertion the best case, resulting in nearly perfect page
|
|
space utilization.
|
|
|
|
Space freed by deleting key/data pairs from the database
|
|
is never reclaimed from the filesystem, although it is
|
|
reused where possible. This means that the btree storage
|
|
structure is grow-only. If sufficiently many keys are
|
|
deleted from a tree that shrinking the underlying database
|
|
file is desirable, this can be accomplished by creating a
|
|
new tree from a scan of the existing one.
|
|
|
|
The following additional fields and flags may be
|
|
initialized in the DB_INFO structure before calling
|
|
db_open, when using the btree access method:
|
|
|
|
int (*bt_compare)(const DBT *, const DBT *);
|
|
The bt_compare function is the key comparison
|
|
function. It must return an integer less than, equal
|
|
to, or greater than zero if the first key argument is
|
|
considered to be respectively less than, equal to, or
|
|
greater than the second key argument. The same
|
|
comparison function must be used on a given tree
|
|
every time it is opened.
|
|
|
|
The data and size fields of the DBT are the only
|
|
fields that may be used for the purposes of this
|
|
comparison.
|
|
|
|
If bt_compare is NULL, the keys are compared
|
|
lexically, with shorter keys collating before longer
|
|
keys.
|
|
|
|
u_int32_t bt_minkey;
|
|
The minimum number of keys that will be stored on any
|
|
single page. This value is used to determine which
|
|
keys will be stored on overflow pages, i.e. if a key
|
|
or data item is larger than the pagesize divided by
|
|
the bt_minkey value, it will be stored on overflow
|
|
pages instead of in the page itself. The bt_minkey
|
|
value specified must be at least 2; if bt_minkey is
|
|
0, a value of 2 is used.
|
|
|
|
size_t (*bt_prefix)(const DBT *, const DBT *);
|
|
The bt_prefix function is the prefix comparison
|
|
function. If specified, this function must return
|
|
the number of bytes of the second key argument that
|
|
are necessary to determine that it is greater than
|
|
the first key argument. If the keys are equal, the
|
|
key length should be returned.
|
|
|
|
The data and size fields of the DBT are the only
|
|
fields that may be used for the purposes of this
|
|
comparison.
|
|
|
|
This is used to compress the keys stored on the btree
|
|
internal pages. The usefulness of this is data
|
|
dependent, but in some data sets can produce
|
|
significantly reduced tree sizes and search times.
|
|
If bt_prefix is NULL, and no comparison function is
|
|
specified, a default lexical comparison function is
|
|
used. If bt_prefix is NULL and a comparison function
|
|
is specified, no prefix comparison is done.
|
|
|
|
u_int32_t flags;
|
|
The following additional flags may be specified by
|
|
<B>or</B>'ing together one or more of the following values:
|
|
|
|
DB_DUP
|
|
Permit duplicate keys in the tree, i.e.
|
|
insertion when the key of the key/data pair
|
|
being inserted already exists in the tree will
|
|
be successful. The ordering of duplicates in
|
|
the tree is determined by the order of
|
|
insertion, unless the ordering is otherwise
|
|
specified by use of a cursor (see <B><A HREF="db_cursor.html">db_cursor(3)</A></B>
|
|
for more information.) It is an error to
|
|
specify both DB_DUP and DB_RECNUM.
|
|
|
|
DB_RECNUM
|
|
Support retrieval from btrees using record
|
|
numbers. For more information, see the
|
|
DB_SET_RECNO flag to the DB->get function
|
|
(below), and the cursor c_get function (in
|
|
<B><A HREF="db_cursor.html">db_cursor(3)</A></B>).
|
|
|
|
Logical record numbers in btrees are mutable in
|
|
the face of record insertion or deletion. See
|
|
the DB_RENUMBER flag in the RECNO section below
|
|
for further discussion.
|
|
|
|
Maintaining record counts within a btree
|
|
introduces a serious point of contention, namely
|
|
the page locations where the record counts are
|
|
stored. In addition, the entire tree must be
|
|
locked during both insertions and deletions,
|
|
effectively single-threading the tree for those
|
|
operations. Specifying DB_RECNUM can result in
|
|
serious performance degradation for some
|
|
applications and data sets.
|
|
|
|
It is an error to specify both DB_DUP and
|
|
DB_RECNUM.
|
|
|
|
|
|
</PRE>
|
|
<H2>HASH</H2><PRE>
|
|
The hash data structure is an extensible, dynamic hashing
|
|
scheme. Backward compatible interfaces to the functions
|
|
described in <B>dbm(3)</B>, <B>ndbm(3)</B> and <B>hsearch(3)</B> are provided,
|
|
however these interfaces are not compatible with previous
|
|
file formats.
|
|
|
|
The following additional fields and flags may be
|
|
initialized in the DB_INFO structure before calling
|
|
db_open, when using the hash access method:
|
|
|
|
u_int32_t h_ffactor;
|
|
The desired density within the hash table. It is an
|
|
approximation of the number of keys allowed to
|
|
accumulate in any one bucket, determining when the
|
|
hash table grows or shrinks. The default value is 0,
|
|
indicating that the fill factor will be selected
|
|
dynamically as pages are filled.
|
|
|
|
u_int32_t (*h_hash)(const void *, u_int32_t);
|
|
The h_hash field is a user defined hash function; if
|
|
h_hash is NULL, a default hash function is used.
|
|
Since no hash function performs equally well on all
|
|
possible data, the user may find that the built-in
|
|
hash function performs poorly with a particular data
|
|
set. User specified hash functions must take a
|
|
pointer to a byte string and a length as arguments
|
|
and return a u_int32_t value.
|
|
|
|
If a hash function is specified, hash_open will
|
|
attempt to determine if the hash function specified
|
|
is the same as the one with which the database was
|
|
created, and will fail if it detects that it is not.
|
|
|
|
u_int32_t h_nelem;
|
|
An estimate of the final size of the hash table. If
|
|
not set or set too low, hash tables will expand
|
|
gracefully as keys are entered, although a slight
|
|
performance degradation may be noticed. The default
|
|
value is 1.
|
|
|
|
u_int32_t flags;
|
|
The following additional flags may be specified by
|
|
<B>or</B>'ing together one or more of the following values:
|
|
|
|
DB_DUP
|
|
Permit duplicate keys in the tree, i.e.
|
|
insertion when the key of the key/data pair
|
|
being inserted already exists in the tree will
|
|
be successful. The ordering of duplicates in
|
|
the tree is determined by the order of
|
|
insertion, unless the ordering is otherwise
|
|
specified by use of a cursor (see <B><A HREF="db_cursor.html">db_cursor(3)</A></B>
|
|
for more information.)
|
|
|
|
|
|
</PRE>
|
|
<H2>RECNO</H2><PRE>
|
|
The recno access method provides support for fixed and
|
|
variable length records, optionally backed by a flat text
|
|
(byte stream) file. Both fixed and variable length
|
|
records are accessed by their logical record number.
|
|
|
|
It is valid to create a record whose record number is more
|
|
than one greater than the last record currently in the
|
|
database. For example, the creation of record number 8,
|
|
when records 6 and 7 do not yet exist, is not an error.
|
|
However, any attempt to retrieve such records (e.g.,
|
|
records 6 and 7) will return DB_KEYEMPTY.
|
|
|
|
Deleting a record will not, by default, renumber records
|
|
following the deleted record (see DB_RENUMBER below for
|
|
more information). Any attempt to retrieve deleted
|
|
records will return DB_KEYEMPTY.
|
|
|
|
The following additional fields and flags may be
|
|
initialized in the DB_INFO structure before calling
|
|
db_open, when using the recno access method:
|
|
|
|
int re_delim;
|
|
For variable length records, if the re_source file is
|
|
specified and the DB_DELIMITER flag is set, the
|
|
delimiting byte used to mark the end of a record in
|
|
the source file. If the re_source file is specified
|
|
and the DB_DELIMITER flag is not set, <newline>
|
|
characters (i.e. ``\n'', 0x0a) are interpreted as
|
|
end-of-record markers.
|
|
|
|
u_int32_t re_len;
|
|
The length of a fixed-length record.
|
|
|
|
int re_pad;
|
|
For fixed length records, if the DB_PAD flag is set,
|
|
the pad character for short records. If the DB_PAD
|
|
flag is not set, <space> characters (i.e., 0x20) are
|
|
used for padding.
|
|
|
|
char *re_source;
|
|
The purpose of the re_source field is to provide fast
|
|
access and modification to databases that are
|
|
normally stored as flat text files.
|
|
|
|
If the re_source field is non-NULL, it specifies an
|
|
underlying flat text database file that is read to
|
|
initialize a transient record number index. In the
|
|
case of variable length records, the records are
|
|
separated by the byte value re_delim. For example,
|
|
standard UNIX byte stream files can be interpreted as
|
|
a sequence of variable length records separated by
|
|
<newline> characters.
|
|
|
|
In addition, when cached data would normally be
|
|
written back to the underlying database file (e.g.,
|
|
the close or sync functions are called), the in-
|
|
memory copy of the database will be written back to
|
|
the re_source file.
|
|
|
|
By default, the backing source file is read lazily,
|
|
i.e., records are not read from the file until they
|
|
are requested by the application. <B>If</B> <B>multiple</B>
|
|
<B>processes</B> <B>(not</B> <B>threads)</B> <B>are</B> <B>accessing</B> <B>a</B> <B>recno</B>
|
|
<B>database</B> <B>concurrently</B> <B>and</B> <B>either</B> <B>inserting</B> <B>or</B>
|
|
<B>deleting</B> <B>records,</B> <B>the</B> <B>backing</B> <B>source</B> <B>file</B> <B>must</B> <B>be</B>
|
|
<B>read</B> <B>in</B> <B>its</B> <B>entirety</B> <B>before</B> <B>more</B> <B>than</B> <B>a</B> <B>single</B>
|
|
<B>process</B> <B>accesses</B> <B>the</B> <B>database,</B> <B>and</B> <B>only</B> <B>that</B> <B>process</B>
|
|
<B>should</B> <B>specify</B> <B>the</B> <B>backing</B> <B>source</B> <B>file</B> <B>as</B> <B>part</B> <B>of</B> <B>the</B>
|
|
<B>db</B>_<B>open</B> <B>call.</B> See the DB_SNAPSHOT flag below for
|
|
more information.
|
|
|
|
<B>Reading</B> <B>and</B> <B>writing</B> <B>the</B> <B>backing</B> <B>source</B> <B>file</B> <B>specified</B>
|
|
<B>by</B> <B>re</B>_<B>source</B> <B>cannot</B> <B>be</B> <B>transactionally</B> <B>protected</B>
|
|
<B>because</B> <B>it</B> <B>involves</B> <B>filesystem</B> <B>operations</B> <B>that</B> <B>are</B>
|
|
<B>not</B> <B>part</B> <B>of</B> <B>the</B> <B>DB</B> <B>transaction</B> <B>methodology.</B> For this
|
|
reason, if a temporary database is used to hold the
|
|
records, i.e., a NULL was specified as the file
|
|
argument to db_open, it is possible to lose the
|
|
contents of the re_source file, e.g., if the system
|
|
crashes at the right instant. If a file is used to
|
|
hold the database, i.e., a file name was specified as
|
|
the file argument to db_open, normal database
|
|
recovery on that file can be used to prevent
|
|
information loss, although it is still possible that
|
|
the contents of re_source will be lost if the system
|
|
crashes.
|
|
|
|
The re_source file must already exist (but may be
|
|
zero-length) when db_open is called.
|
|
|
|
For all of the above reasons, the re_source field is
|
|
generally used to specify databases that are read-
|
|
only for DB applications, and that are either
|
|
generated on the fly by software tools, or modified
|
|
using a different mechanism, e.g., a text editor.
|
|
|
|
u_int32_t flags;
|
|
The following additional flags may be specified by
|
|
<B>or</B>'ing together one or more of the following values:
|
|
|
|
DB_DELIMITER
|
|
The re_delim field is set.
|
|
|
|
DB_FIXEDLEN
|
|
The records are fixed-length, not byte
|
|
delimited. The structure element re_len
|
|
specifies the length of the record, and the
|
|
structure element re_pad is used as the pad
|
|
character.
|
|
|
|
Any records added to the database that are less
|
|
than re_len bytes long are automatically padded.
|
|
Any attempt to insert records into the database
|
|
that are greater than re_len bytes long will
|
|
cause the call to fail immediately and return an
|
|
error.
|
|
|
|
DB_PAD
|
|
The re_pad field is set.
|
|
|
|
DB_RENUMBER
|
|
Specifying the DB_RENUMBER flag causes the
|
|
logical record numbers to be mutable, and change
|
|
as records are added to and deleted from the
|
|
database. For example, the deletion of record
|
|
number 4 causes records numbered 5 and greater
|
|
to be renumbered downward by 1. If a cursor was
|
|
positioned to record number 4 before the
|
|
deletion, it will reference the new record
|
|
number 4, if any such record exists, after the
|
|
deletion. If a cursor was positioned after
|
|
record number 4 before the deletion, it will be
|
|
shifted downward 1 logical record, continuing to
|
|
reference the same record as it did before.
|
|
|
|
Using the c_put or put interfaces to create new
|
|
records will cause the creation of multiple
|
|
records if the record number is more than one
|
|
greater than the largest record currently in the
|
|
database. For example, creating record 28, when
|
|
record 25 was previously the last record in the
|
|
database, will create records 26 and 27 as well
|
|
as 28. Attempts to retrieve records that were
|
|
created in this manner will result in an error
|
|
return of DB_KEYEMPTY.
|
|
|
|
If a created record is not at the end of the
|
|
database, all records following the new record
|
|
will be automatically renumbered upward by 1.
|
|
For example, the creation of a new record
|
|
numbered 8 causes records numbered 8 and greater
|
|
to be renumbered upward by 1. If a cursor was
|
|
positioned to record number 8 or greater before
|
|
the insertion, it will be shifted upward 1
|
|
logical record, continuing to reference the same
|
|
record as it did before.
|
|
|
|
For these reasons, concurrent access to a recno
|
|
database with the DB_RENUMBER flag specified may
|
|
be largely meaningless, although it is
|
|
supported.
|
|
|
|
DB_SNAPSHOT
|
|
This flag specifies that any specified re_source
|
|
file be read in its entirety when db_open is
|
|
called. If this flag is not specified, the
|
|
re_source file may be read lazily.
|
|
|
|
|
|
</PRE>
|
|
<H2>DB OPERATIONS</H2><PRE>
|
|
The DB structure returned by db_open describes a database
|
|
type, and includes a set of functions to perform various
|
|
actions, as described below. Each of these functions
|
|
takes a pointer to a DB structure, and may take one or
|
|
more DBT *'s and a flag value as well. The fields of the
|
|
DB structure are as follows:
|
|
|
|
DBTYPE type;
|
|
The type of the underlying access method (and file
|
|
format). Set to one of DB_BTREE, DB_HASH or
|
|
DB_RECNO. This field may be used to determine the
|
|
type of the database after a return from db_open with
|
|
the type argument set to DB_UNKNOWN.
|
|
|
|
int (*close)(DB *db, u_int32_t flags);
|
|
A pointer to a function to flush any cached
|
|
information to disk, close any open cursors (see
|
|
<B><A HREF="db_cursor.html">db_cursor(3)</A></B>), free any allocated resources, and
|
|
close any underlying files. Since key/data pairs are
|
|
cached in memory, failing to sync the file with the
|
|
close or sync function may result in inconsistent or
|
|
lost information.
|
|
|
|
The flags parameter must be set to 0 or the following
|
|
value:
|
|
|
|
DB_NOSYNC
|
|
Do not flush cached information to disk.
|
|
|
|
The DB_NOSYNC flag is a dangerous option. It should
|
|
only be set if the application is doing logging (with
|
|
transactions) so that the database is recoverable
|
|
after a system or application crash, or if the
|
|
database is always generated from scratch after any
|
|
system or application crash.
|
|
|
|
<B>It</B> <B>is</B> <B>important</B> <B>to</B> <B>understand</B> <B>that</B> <B>flushing</B> <B>cached</B>
|
|
<B>information</B> <B>to</B> <B>disk</B> <B>only</B> <B>minimizes</B> <B>the</B> <B>window</B> <B>of</B>
|
|
<B>opportunity</B> <B>for</B> <B>corrupted</B> <B>data.</B> While unlikely, it
|
|
is possible for database corruption to happen if a
|
|
system or application crash occurs while writing data
|
|
to the database. To ensure that database corruption
|
|
never occurs, applications must either: use
|
|
transactions and logging with automatic recovery, use
|
|
logging and application-specific recovery, or edit a
|
|
copy of the database, and, once all applications
|
|
using the database have successfully called close,
|
|
replace the original database with the updated copy.
|
|
|
|
When multiple threads are using the DB handle
|
|
concurrently, only a single thread may call the DB
|
|
handle close function.
|
|
|
|
The close function returns the value of errno on
|
|
failure and 0 on success.
|
|
|
|
int (*cursor)(DB *db, DB_TXN *txnid, DBC **cursorp);
|
|
A pointer to a function to create a cursor and copy a
|
|
pointer to it into the memory referenced by cursorp.
|
|
|
|
A cursor is a structure used to provide sequential
|
|
access through a database. This interface and its
|
|
associated functions replaces the functionality
|
|
provided by the seq function in previous releases of
|
|
the DB library.
|
|
|
|
If the file is being accessed under transaction
|
|
protection, the txnid parameter is a transaction ID
|
|
returned from txn_begin, otherwise, NULL. If
|
|
transaction protection is enabled, cursors must be
|
|
opened and closed within the context of a
|
|
transaction, and the txnid parameter specifies the
|
|
transaction context in which the cursor may be used.
|
|
See <B><A HREF="db_cursor.html">db_cursor(3)</A></B> for more information.
|
|
|
|
The cursor function returns the value of errno on
|
|
failure and 0 on success.
|
|
|
|
int (*del)(DB *db, DB_TXN *txnid, DBT *key, u_int32_t
|
|
flags);
|
|
A pointer to a function to remove key/data pairs from
|
|
the database. The key/data pair associated with the
|
|
specified key is discarded from the database. In the
|
|
presence of duplicate key values, all records
|
|
associated with the designated key will be discarded.
|
|
|
|
If the file is being accessed under transaction
|
|
protection, the txnid parameter is a transaction ID
|
|
returned from txn_begin, otherwise, NULL.
|
|
|
|
The flags parameter is currently unused, and must be
|
|
set to 0.
|
|
|
|
The del function returns the value of errno on
|
|
failure, 0 on success, and DB_NOTFOUND if the
|
|
specified key did not exist in the file.
|
|
|
|
int (*fd)(DB *db, int *fdp);
|
|
A pointer to a function that copies a file descriptor
|
|
representative of the underlying database into the
|
|
memory referenced by fdp. A file descriptor
|
|
referencing the same file will be returned to all
|
|
processes that call db_open with the same file
|
|
argument. This file descriptor may be safely used as
|
|
an argument to the <B>fcntl(2)</B> and <B>flock(2)</B> locking
|
|
functions. The file descriptor is not necessarily
|
|
associated with any of the underlying files used by
|
|
the access method.
|
|
|
|
The fd function only supports a coarse-grained form
|
|
of locking. Applications should use the lock manager
|
|
where possible.
|
|
|
|
The fd function returns the value of errno on failure
|
|
and 0 on success.
|
|
|
|
int (*get)(DB *db, DB_TXN *txnid,
|
|
DBT *key, DBT *data, u_int32_t flags);
|
|
A pointer to a function that is an interface for
|
|
keyed retrieval from the database. The address and
|
|
length of the data associated with the specified key
|
|
are returned in the structure referenced by data.
|
|
|
|
In the presence of duplicate key values, get will
|
|
return the first data item for the designated key.
|
|
Duplicates are sorted by insert order except where
|
|
this order has been overridden by cursor operations.
|
|
<B>Retrieval</B> <B>of</B> <B>duplicates</B> <B>requires</B> <B>the</B> <B>use</B> <B>of</B> <B>cursor</B>
|
|
<B>operations.</B> See <B><A HREF="db_cursor.html">db_cursor(3)</A></B> for details.
|
|
|
|
If the file is being accessed under transaction
|
|
protection, the txnid parameter is a transaction ID
|
|
returned from txn_begin, otherwise, NULL.
|
|
|
|
The flags parameter must be set to 0 or the following
|
|
value:
|
|
|
|
DB_SET_RECNO
|
|
Retrieve the specified numbered key/data pair
|
|
from a database. Upon return, both the key and
|
|
data items will have been filled in, not just
|
|
the data item as is done for all other uses of
|
|
the get function.
|
|
|
|
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>).
|
|
|
|
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 get function
|
|
returns DB_KEYEMPTY. Otherwise, if the requested key
|
|
isn't in the database, the get function returns
|
|
DB_NOTFOUND. Otherwise, the get function returns the
|
|
value of errno on failure and 0 on success.
|
|
|
|
int (*put)(DB *db, DB_TXN *txnid,
|
|
DBT *key, DBT *data, u_int32_t flags);
|
|
A pointer to a function to store key/data pairs in
|
|
the database. If the database supports duplicates,
|
|
the put function adds the new data value at the end
|
|
of the duplicate set.
|
|
|
|
If the file is being accessed under transaction
|
|
protection, the txnid parameter is a transaction ID
|
|
returned from txn_begin, otherwise, NULL.
|
|
|
|
The flags value is specified by <B>or</B>'ing together one
|
|
or more of the following values:
|
|
|
|
DB_APPEND
|
|
Append the key/data pair to the end of the
|
|
database. For DB_APPEND to be specified, the
|
|
underlying database must be of type recno. The
|
|
record number allocated to the record is
|
|
returned in the specified key.
|
|
|
|
DB_NOOVERWRITE
|
|
Enter the new key/data pair only if the key does
|
|
not already appear in the database.
|
|
|
|
The default behavior of the put function is to enter
|
|
the new key/data pair, replacing any previously
|
|
existing key if duplicates are disallowed, or to add
|
|
a duplicate entry if duplicates are allowed. Even if
|
|
the designated database allows duplicates, a call to
|
|
put with the DB_NOOVERWRITE flag set will fail if the
|
|
key already exists in the database.
|
|
The put function returns the value of errno on
|
|
failure, 0 on success, and DB_KEYEXIST if the
|
|
DB_NOOVERWRITE flag was set and the key already
|
|
exists in the file.
|
|
|
|
int (*sync)(DB *db, u_int32_t flags);
|
|
A pointer to a function to flush any cached
|
|
information to disk. If the database is in memory
|
|
only, the sync function has no effect and will always
|
|
succeed.
|
|
|
|
The flags parameter is currently unused, and must be
|
|
set to 0.
|
|
|
|
See the close function description above for a
|
|
discussion of DB and cached data.
|
|
|
|
The sync function returns the value of errno on
|
|
failure and 0 on success.
|
|
|
|
int (*stat)(DB *db, void *sp,
|
|
void *(*db_malloc)(size_t), u_int32_t flags);
|
|
A pointer to a function to create a statistical
|
|
structure and copy a pointer to it into user-
|
|
specified memory locations. Specifically, if sp is
|
|
non-NULL, a pointer to the statistics for the
|
|
database are copied into the memory location it
|
|
references.
|
|
|
|
Statistical structures are created in allocated
|
|
memory. If db_malloc is non-NULL, it is called to
|
|
allocate the memory, otherwise, the library function
|
|
<B>malloc(3)</B> is used. The function db_malloc must match
|
|
the calling conventions of the <B>malloc(3)</B> library
|
|
routine. Regardless, the caller is responsible for
|
|
deallocating the returned memory. To deallocate the
|
|
returned memory, free each returned memory pointer;
|
|
pointers inside the memory do not need to be
|
|
individually freed.
|
|
|
|
<B>In</B> <B>the</B> <B>presence</B> <B>of</B> <B>multiple</B> <B>threads</B> <B>or</B> <B>processes</B>
|
|
<B>accessing</B> <B>an</B> <B>active</B> <B>database,</B> <B>the</B> <B>returned</B>
|
|
<B>information</B> <B>may</B> <B>be</B> <B>out-of-date.</B>
|
|
|
|
<B>This</B> <B>function</B> <B>may</B> <B>access</B> <B>all</B> <B>of</B> <B>the</B> <B>pages</B> <B>in</B> <B>the</B>
|
|
<B>database,</B> <B>and</B> <B>therefore</B> <B>may</B> <B>incur</B> <B>a</B> <B>severe</B>
|
|
<B>performance</B> <B>penalty</B> <B>and</B> <B>have</B> <B>obvious</B> <B>negative</B> <B>effects</B>
|
|
<B>on</B> <B>the</B> <B>underlying</B> <B>buffer</B> <B>pool.</B>
|
|
|
|
The flags parameter must be set to 0 or the following
|
|
value:
|
|
|
|
DB_RECORDCOUNT
|
|
Fill in the bt_nrecs field of the statistics
|
|
structure, but do not collect any other
|
|
information. This flag makes it reasonable for
|
|
applications to request a record count from a
|
|
database without incurring a performance
|
|
penalty. It is only available for recno
|
|
databases, or btree databases where the
|
|
underlying database was created with the
|
|
DB_RECNUM flag.
|
|
|
|
The stat function returns the value of errno on
|
|
failure and 0 on success.
|
|
|
|
In the case of a btree or recno database, the
|
|
statistics are stored in a structure of type
|
|
DB_BTREE_STAT (typedef'd in <db.h>). The following
|
|
fields will be filled in:
|
|
|
|
u_int32_t bt_magic;
|
|
Magic number that identifies the file as a btree
|
|
file.
|
|
u_int32_t bt_version;
|
|
The version of the btree file type.
|
|
u_int32_t bt_flags;
|
|
Permanent database flags, including DB_DUP,
|
|
DB_FIXEDLEN, DB_RECNUM and DB_RENUMBER.
|
|
u_int32_t bt_minkey;
|
|
The bt_minkey value specified to <B><A HREF="db_open.html">db_open(3)</A></B>, if
|
|
any.
|
|
u_int32_t bt_re_len;
|
|
The re_len value specified to <B><A HREF="db_open.html">db_open(3)</A></B>, if
|
|
any.
|
|
u_int32_t bt_re_pad;
|
|
The re_pad value specified to <B><A HREF="db_open.html">db_open(3)</A></B>, if
|
|
any.
|
|
u_int32_t bt_pagesize;
|
|
Underlying tree page size.
|
|
u_int32_t bt_levels;
|
|
Number of levels in the tree.
|
|
u_int32_t bt_nrecs;
|
|
Number of data items in the tree (since there
|
|
may be multiple data items per key, this number
|
|
may not be the same as the number of keys).
|
|
u_int32_t bt_int_pg;
|
|
Number of tree internal pages.
|
|
u_int32_t bt_leaf_pg;
|
|
Number of tree leaf pages.
|
|
u_int32_t bt_dup_pg;
|
|
Number of tree duplicate pages.
|
|
u_int32_t bt_over_pg;
|
|
Number of tree overflow pages.
|
|
u_int32_t bt_free;
|
|
Number of pages on the free list.
|
|
|
|
u_int32_t bt_freed;
|
|
Number of pages made available for reuse because
|
|
they were emptied.
|
|
u_int32_t bt_int_pgfree;
|
|
Number of bytes free in tree internal pages.
|
|
u_int32_t bt_leaf_pgfree;
|
|
Number of bytes free in tree leaf pages.
|
|
u_int32_t bt_dup_pgfree;
|
|
Number of bytes free in tree duplicate pages.
|
|
u_int32_t bt_over_pgfree;
|
|
Number of bytes free in tree overflow pages.
|
|
u_int32_t bt_pfxsaved;
|
|
Number of bytes saved by prefix compression.
|
|
u_int32_t bt_split;
|
|
Total number of tree page splits (includes fast
|
|
and root splits).
|
|
u_int32_t bt_rootsplit;
|
|
Number of root page splits.
|
|
u_int32_t bt_fastsplit;
|
|
Number of fast splits. When sorted keys are
|
|
added to the database, the DB btree
|
|
implementation will split left or right to
|
|
increase the page-fill factor. This number is a
|
|
measure of how often it was possible to make
|
|
such a split.
|
|
u_int32_t bt_added;
|
|
Number of keys added.
|
|
u_int32_t bt_deleted;
|
|
Number of keys deleted.
|
|
u_int32_t bt_get;
|
|
Number of keys retrieved. (Note, this value
|
|
will not reflect any keys retrieved when the
|
|
database was open for read-only access, as there
|
|
is no permanent location to store the
|
|
information in this case.)
|
|
u_int32_t bt_cache_hit;
|
|
Number of hits in tree fast-insert code. When
|
|
sorted keys are added to the database, the DB
|
|
btree implementation will check the last page
|
|
where an insert occurred before doing a full
|
|
lookup. This number is a measure of how often
|
|
the lookup was successful.
|
|
u_int32_t bt_cache_miss;
|
|
Number of misses in tree fast-insert code. See
|
|
the description of bt_cache_hit; this number is
|
|
a measure of how often the lookup failed.
|
|
|
|
|
|
</PRE>
|
|
<H2>ENVIRONMENT VARIABLES</H2><PRE>
|
|
The following environment variables affect the execution
|
|
of db_open:
|
|
|
|
DB_HOME
|
|
If the dbenv argument to db_open was initialized
|
|
using db_appinit, the environment variable DB_HOME
|
|
may be used as the path of the database home for the
|
|
interpretation of the dir argument to db_open, as
|
|
described in <B><A HREF="db_appinit.html">db_appinit(3)</A></B>. Specifically, db_open is
|
|
affected by the configuration string value of
|
|
DB_DATA_DIR.
|
|
|
|
|
|
</PRE>
|
|
<H2>EXAMPLES</H2><PRE>
|
|
Applications that create short-lived databases that are
|
|
discarded or recreated when the system fails and are
|
|
unconcerned with concurrent access and loss of data due to
|
|
catastrophic failure, may wish to use the db_open
|
|
functionality without other parts of the DB library. Such
|
|
applications will only be concerned with the DB access
|
|
methods. The DB access methods will use the memory pool
|
|
subsystem, but the application is unlikely to be aware of
|
|
this. See the files example/ex_access.c and
|
|
example/ex_btrec.c in the DB source distribution for C
|
|
language code examples of how such applications might use
|
|
the DB library.
|
|
|
|
|
|
</PRE>
|
|
<H2>ERRORS</H2><PRE>
|
|
The db_open 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->sync(3)</A></B>, <B>calloc(3)</B>, <B>close(2)</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><A HREF="db_log.html">log_register(3)</A></B>,
|
|
<B><A HREF="db_log.html">log_unregister(3)</A></B>, <B>malloc(3)</B>, <B>memcpy(3)</B>, <B>memmove(3)</B>,
|
|
<B><A HREF="db_mpool.html">memp_close(3)</A></B>, <B><A HREF="db_mpool.html">memp_fclose(3)</A></B>, <B><A HREF="db_mpool.html">memp_fget(3)</A></B>,
|
|
<B><A HREF="db_mpool.html">memp_fopen(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><A HREF="db_mpool.html">memp_fsync(3)</A></B>,
|
|
<B><A HREF="db_mpool.html">memp_open(3)</A></B>, <B><A HREF="db_mpool.html">memp_register(3)</A></B>, <B>memset(3)</B>, <B>mmap(2)</B>,
|
|
<B>munmap(2)</B>, <B>open(2)</B>, <B>read(2)</B>, <B>realloc(3)</B>, <B>sigfillset(3)</B>,
|
|
<B>sigprocmask(2)</B>, <B>stat(2)</B>, <B>strcpy(3)</B>, <B>strdup(3)</B>,
|
|
<B>strerror(3)</B>, <B>strlen(3)</B>, <B>time(3)</B>, and <B>unlink(2)</B>.
|
|
|
|
In addition, the db_open function may fail and return
|
|
errno for the following conditions:
|
|
|
|
[EAGAIN]
|
|
A lock was unavailable.
|
|
|
|
[EINVAL]
|
|
An invalid flag value or parameter was specified
|
|
(e.g., unknown database type, page size, hash
|
|
function, recno pad byte, byte order) or a flag value
|
|
or parameter that is incompatible with the current
|
|
file specification.
|
|
|
|
The DB_THREAD flag was specified and spinlocks are
|
|
not implemented for this architecture.
|
|
|
|
There is a mismatch between the version number of
|
|
file and the software.
|
|
|
|
A re_source file was specified with either the
|
|
DB_THREAD flag or a non-NULL tx_info field in the
|
|
DB_ENV argument to db_open.
|
|
|
|
[ENOENT]
|
|
A non-existent re_source file was specified.
|
|
|
|
[EPERM]
|
|
Database corruption was detected. All subsequent
|
|
database calls (other than DB->close) will return
|
|
EPERM.
|
|
|
|
The DB->close 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->sync(3)</A></B>, <B>calloc(3)</B>, <B>close(2)</B>, <B>fflush(3)</B>,
|
|
<B><A HREF="db_lock.html">lock_get(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><A HREF="db_log.html">log_unregister(3)</A></B>, <B>malloc(3)</B>, <B>memcpy(3)</B>, <B>memmove(3)</B>,
|
|
<B><A HREF="db_mpool.html">memp_close(3)</A></B>, <B><A HREF="db_mpool.html">memp_fclose(3)</A></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><A HREF="db_mpool.html">memp_fsync(3)</A></B>, <B>memset(3)</B>, <B>munmap(2)</B>,
|
|
<B>realloc(3)</B>, and <B>strerror(3)</B>.
|
|
|
|
The DB->cursor function may fail and return errno for any
|
|
of the errors specified for the following DB and library
|
|
functions: <B>calloc(3)</B>.
|
|
|
|
In addition, the DB->cursor function may fail and return
|
|
errno for the following conditions:
|
|
|
|
[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 DB->del 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 DB->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.
|
|
|
|
In addition, the DB->fd function may fail and return errno
|
|
for the following conditions:
|
|
|
|
[ENOENT]
|
|
The DB->fd function was called for an in-memory
|
|
database, or no underlying file has yet been created.
|
|
|
|
[EPERM]
|
|
Database corruption was detected. All subsequent
|
|
database calls (other than DB->close) will return
|
|
EPERM.
|
|
|
|
The DB->get function may fail and return errno for any of
|
|
the errors specified for the following DB and library
|
|
functions: <B><A HREF="db_cursor.html">DBcursor->c_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 DB->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.
|
|
|
|
A record number of 0 was specified.
|
|
|
|
[EPERM]
|
|
Database corruption was detected. All subsequent
|
|
database calls (other than DB->close) will return
|
|
EPERM.
|
|
|
|
The DB->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 DB->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.
|
|
|
|
A record number of 0 was specified.
|
|
|
|
An attempt was made to add a record to a fixed-length
|
|
database that was too large to fit.
|
|
|
|
An attempt was made to do a partial put.
|
|
|
|
[EPERM]
|
|
Database corruption was detected. All subsequent
|
|
database calls (other than DB->close) will return
|
|
EPERM.
|
|
|
|
[ENOSPC]
|
|
A btree exceeded the maximum btree depth (255).
|
|
|
|
The DB->stat 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>malloc(3)</B>,
|
|
<B>memcpy(3)</B>, <B><A HREF="db_mpool.html">memp_fget(3)</A></B>, <B><A HREF="db_mpool.html">memp_fput(3)</A></B>, and <B>memset(3)</B>.
|
|
|
|
The DB->sync 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><A HREF="db_open.html">DB->sync(3)</A></B>, <B>calloc(3)</B>, <B>close(2)</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><A HREF="db_mpool.html">memp_fsync(3)</A></B>,
|
|
<B>memset(3)</B>, <B>munmap(2)</B>, <B>open(2)</B>, <B>realloc(3)</B>, <B>strerror(3)</B>,
|
|
<B>unlink(2)</B>, and <B>write(2)</B>.
|
|
|
|
In addition, the DB->sync function may fail and return
|
|
errno for the following conditions:
|
|
|
|
[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>
|
|
The Ubiquitous B-tree, Douglas Comer, ACM Comput. Surv.
|
|
11, 2 (June 1979), 121-138.
|
|
|
|
Prefix B-trees, Bayer and Unterauer, ACM Transactions on
|
|
Database Systems, Vol. 2, 1 (March 1977), 11-26.
|
|
|
|
The Art of Computer Programming Vol. 3: Sorting and
|
|
Searching, D.E. Knuth, 1968, pp 471-480.
|
|
|
|
Dynamic Hash Tables, Per-Ake Larson, Communications of the
|
|
ACM, April 1988.
|
|
|
|
A New Hash Package for UNIX, Margo Seltzer, USENIX
|
|
Proceedings, Winter 1991.
|
|
|
|
Document Processing in a Relational Database System,
|
|
Michael Stonebraker, Heidi Stettner, Joseph Kalash,
|
|
Antonin Guttman, Nadene Lynn, Memorandum No. UCB/ERL
|
|
M82/32, May 1982.
|
|
|
|
<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>
|