зеркало из https://github.com/mozilla/gecko-dev.git
1888 строки
39 KiB
Groff
1888 строки
39 KiB
Groff
.ds TYPE CXX
|
|
.\"
|
|
.\" See the file LICENSE for redistribution information.
|
|
.\"
|
|
.\" Copyright (c) 1997, 1998
|
|
.\" Sleepycat Software. All rights reserved.
|
|
.\"
|
|
.\" @(#)Db.sox 10.16 (Sleepycat) 5/4/98
|
|
.\"
|
|
.\"
|
|
.\" See the file LICENSE for redistribution information.
|
|
.\"
|
|
.\" Copyright (c) 1997, 1998
|
|
.\" Sleepycat Software. All rights reserved.
|
|
.\"
|
|
.\" @(#)macros.so 10.45 (Sleepycat) 5/4/98
|
|
.\"
|
|
.\" We don't want hyphenation for any HTML documents.
|
|
.ie '\*[HTML]'YES'\{\
|
|
.nh
|
|
\}
|
|
.el\{\
|
|
.ds Hy
|
|
.hy
|
|
..
|
|
.ds Nh
|
|
.nh
|
|
..
|
|
\}
|
|
.\" The alternative text macro
|
|
.\" This macro takes two arguments:
|
|
.\" + the text produced if this is a "C" manpage
|
|
.\" + the text produced if this is a "CXX" or "JAVA" manpage
|
|
.\"
|
|
.de Al
|
|
.ie '\*[TYPE]'C'\{\\$1
|
|
\}
|
|
.el\{\\$2
|
|
\}
|
|
..
|
|
.\" Scoped name macro.
|
|
.\" Produces a_b, a::b, a.b depending on language
|
|
.\" This macro takes two arguments:
|
|
.\" + the class or prefix (without underscore)
|
|
.\" + the name within the class or following the prefix
|
|
.de Sc
|
|
.ie '\*[TYPE]'C'\{\\$1_\\$2
|
|
\}
|
|
.el\{\
|
|
.ie '\*[TYPE]'CXX'\{\\$1::\\$2
|
|
\}
|
|
.el\{\\$1.\\$2
|
|
\}
|
|
\}
|
|
..
|
|
.\" Scoped name for Java.
|
|
.\" Produces Db.b, for Java, otherwise just b. This macro is used for
|
|
.\" constants that must be scoped in Java, but are global otherwise.
|
|
.\" This macro takes two arguments:
|
|
.\" + the class
|
|
.\" + the name within the class or following the prefix
|
|
.de Sj
|
|
.ie '\*[TYPE]'JAVA'\{\
|
|
.TP 5
|
|
Db.\\$1\}
|
|
.el\{\
|
|
.TP 5
|
|
\\$1\}
|
|
..
|
|
.\" The general information text macro.
|
|
.de Gn
|
|
.ie '\*[TYPE]'C'\{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).
|
|
\}
|
|
.el\{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
|
|
.IR db_intro (3).
|
|
..
|
|
.\" The library error macro, the local error macro.
|
|
.\" These macros take one argument:
|
|
.\" + the function name.
|
|
.de Ee
|
|
The
|
|
.I \\$1
|
|
.ie '\*[TYPE]'C'\{function may fail and return
|
|
.I errno
|
|
\}
|
|
.el\{method may fail and throw a
|
|
.IR DbException (3)
|
|
.if '\*[TYPE]'CXX'\{
|
|
or return
|
|
.I errno
|
|
\}
|
|
\}
|
|
for any of the errors specified for the following DB and library functions:
|
|
..
|
|
.de Ec
|
|
In addition, the
|
|
.I \\$1
|
|
.ie '\*[TYPE]'C'\{function may fail and return
|
|
.I errno
|
|
\}
|
|
.el\{method may fail and throw a
|
|
.IR DbException (3)
|
|
.ie '\*[TYPE]'CXX'\{or return
|
|
.I errno
|
|
\}
|
|
.el\{encapsulating an
|
|
.I errno
|
|
\}
|
|
\}
|
|
for the following conditions:
|
|
..
|
|
.de Ea
|
|
[EAGAIN]
|
|
A lock was unavailable.
|
|
..
|
|
.de Eb
|
|
[EBUSY]
|
|
The shared memory region was in use and the force flag was not set.
|
|
..
|
|
.de Em
|
|
[EAGAIN]
|
|
The shared memory region was locked and (repeatedly) unavailable.
|
|
..
|
|
.de Ei
|
|
[EINVAL]
|
|
An invalid flag value or parameter was specified.
|
|
..
|
|
.de Es
|
|
[EACCES]
|
|
An attempt was made to modify a read-only database.
|
|
..
|
|
.de Et
|
|
The DB_THREAD flag was specified and spinlocks are not implemented for
|
|
this architecture.
|
|
..
|
|
.de Ep
|
|
[EPERM]
|
|
Database corruption was detected.
|
|
All subsequent database calls (other than
|
|
.ie '\*[TYPE]'C'\{\
|
|
.IR DB->close )
|
|
\}
|
|
.el\{\
|
|
.IR Db::close )
|
|
\}
|
|
will return EPERM.
|
|
..
|
|
.de Ek
|
|
.if '\*[TYPE]'CXX'\{\
|
|
Methods marked as returning
|
|
.I errno
|
|
will, by default, throw an exception that encapsulates the error information.
|
|
The default error behavior can be changed, see
|
|
.IR DbException (3).
|
|
\}
|
|
..
|
|
.\" The SEE ALSO text macro
|
|
.de Sa
|
|
.\" make the line long for nroff.
|
|
.if n .ll 72
|
|
.nh
|
|
.na
|
|
.IR db_archive (1),
|
|
.IR db_checkpoint (1),
|
|
.IR db_deadlock (1),
|
|
.IR db_dump (1),
|
|
.IR db_load (1),
|
|
.IR db_recover (1),
|
|
.IR db_stat (1),
|
|
.IR db_intro (3),
|
|
.ie '\*[TYPE]'C'\{\
|
|
.IR db_appinit (3),
|
|
.IR db_cursor (3),
|
|
.IR db_dbm (3),
|
|
.IR db_internal (3),
|
|
.IR db_lock (3),
|
|
.IR db_log (3),
|
|
.IR db_mpool (3),
|
|
.IR db_open (3),
|
|
.IR db_thread (3),
|
|
.IR db_txn (3)
|
|
\}
|
|
.el\{\
|
|
.IR db_internal (3),
|
|
.IR db_thread (3),
|
|
.IR Db (3),
|
|
.IR Dbc (3),
|
|
.IR DbEnv (3),
|
|
.IR DbException (3),
|
|
.IR DbInfo (3),
|
|
.IR DbLock (3),
|
|
.IR DbLockTab (3),
|
|
.IR DbLog (3),
|
|
.IR DbLsn (3),
|
|
.IR DbMpool (3),
|
|
.if !'\*[TYPE]'JAVA'\{\
|
|
.IR DbMpoolFile (3),
|
|
\}
|
|
.IR Dbt (3),
|
|
.IR DbTxn (3),
|
|
.IR DbTxnMgr (3)
|
|
\}
|
|
.ad
|
|
.Hy
|
|
..
|
|
.\" The function header macro.
|
|
.\" This macro takes one argument:
|
|
.\" + the function name.
|
|
.de Fn
|
|
.in 2
|
|
.I \\$1
|
|
.in
|
|
..
|
|
.\" The XXX_open function text macro, for merged create/open calls.
|
|
.\" This macro takes two arguments:
|
|
.\" + the interface, e.g., "transaction region"
|
|
.\" + the prefix, e.g., "txn" (or the class name for C++, e.g., "DbTxn")
|
|
.de Co
|
|
.ie '\*[TYPE]'C'\{\
|
|
.Fn \\$2_open
|
|
The
|
|
.I \\$2_open
|
|
function copies a pointer, to the \\$1 identified by the
|
|
.B directory
|
|
.IR dir ,
|
|
into the memory location referenced by
|
|
.IR regionp .
|
|
.PP
|
|
If the
|
|
.I dbenv
|
|
argument to
|
|
.I \\$2_open
|
|
was initialized using
|
|
.IR db_appinit ,
|
|
.I dir
|
|
is interpreted as described by
|
|
.IR db_appinit (3).
|
|
\}
|
|
.el\{\
|
|
.Fn \\$2::open
|
|
The
|
|
.I \\$2::open
|
|
.ie '\*[TYPE]'CXX'\{\
|
|
method copies a pointer, to the \\$1 identified by the
|
|
.B directory
|
|
.IR dir ,
|
|
into the memory location referenced by
|
|
.IR regionp .
|
|
\}
|
|
.el\{\
|
|
method returns a \\$1 identified by the
|
|
.B directory
|
|
.IR dir .
|
|
\}
|
|
.PP
|
|
If the
|
|
.I dbenv
|
|
argument to
|
|
.I \\$2::open
|
|
was initialized using
|
|
.IR DbEnv::appinit ,
|
|
.I dir
|
|
is interpreted as described by
|
|
.IR DbEnv (3).
|
|
\}
|
|
.PP
|
|
Otherwise,
|
|
if
|
|
.I dir
|
|
is not NULL,
|
|
it is interpreted relative to the current working directory of the process.
|
|
If
|
|
.I dir
|
|
is NULL,
|
|
the following environment variables are checked in order:
|
|
``TMPDIR'', ``TEMP'', and ``TMP''.
|
|
If one of them is set,
|
|
\\$1 files are created relative to the directory it specifies.
|
|
If none of them are set, the first possible one of the following
|
|
directories is used:
|
|
.IR /var/tmp ,
|
|
.IR /usr/tmp ,
|
|
.IR /temp ,
|
|
.IR /tmp ,
|
|
.I C:/temp
|
|
and
|
|
.IR C:/tmp .
|
|
.PP
|
|
All files associated with the \\$1 are created in this directory.
|
|
This directory must already exist when
|
|
.ie '\*[TYPE]'C'\{
|
|
\\$1_open
|
|
\}
|
|
.el\{\
|
|
\\$2::open
|
|
\}
|
|
is called.
|
|
If the \\$1 already exists,
|
|
the process must have permission to read and write the existing files.
|
|
If the \\$1 does not already exist,
|
|
it is optionally created and initialized.
|
|
..
|
|
.\" The common close language macro, for discarding created regions
|
|
.\" This macro takes one argument:
|
|
.\" + the function prefix, e.g., txn (the class name for C++, e.g., DbTxn)
|
|
.de Cc
|
|
In addition, if the
|
|
.I dir
|
|
argument to
|
|
.ie '\*[TYPE]'C'\{\
|
|
.ds Va db_appinit
|
|
.ds Vo \\$1_open
|
|
.ds Vu \\$1_unlink
|
|
\}
|
|
.el\{\
|
|
.ds Va DbEnv::appinit
|
|
.ds Vo \\$1::open
|
|
.ds Vu \\$1::unlink
|
|
\}
|
|
.I \\*(Vo
|
|
was NULL
|
|
and
|
|
.I dbenv
|
|
was not initialized using
|
|
.IR \\*(Va ,
|
|
.if '\\$1'memp'\{\
|
|
or the DB_MPOOL_PRIVATE flag was set,
|
|
\}
|
|
all files created for this shared region will be removed,
|
|
as if
|
|
.I \\*(Vu
|
|
were called.
|
|
.rm Va
|
|
.rm Vo
|
|
.rm Vu
|
|
..
|
|
.\" The DB_ENV information macro.
|
|
.\" This macro takes two arguments:
|
|
.\" + the function called to open, e.g., "txn_open"
|
|
.\" + the function called to close, e.g., "txn_close"
|
|
.de En
|
|
.ie '\*[TYPE]'C'\{\
|
|
based on the
|
|
.I dbenv
|
|
argument to
|
|
.IR \\$1 ,
|
|
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
|
|
.IR db_appinit (3)),
|
|
as an argument to all of the subsystems in the DB package.
|
|
.PP
|
|
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
|
|
.IR bzero (3)
|
|
or
|
|
.IR memset (3).
|
|
.PP
|
|
The fields of the DB_ENV structure used by
|
|
.I \\$1
|
|
are described below.
|
|
.if '\*[TYPE]'CXX'\{\
|
|
As references to the DB_ENV structure may be maintained by
|
|
.IR \\$1 ,
|
|
it is necessary that the DB_ENV structure and memory it references be valid
|
|
until the
|
|
.I \\$2
|
|
function is called.
|
|
\}
|
|
.ie '\\$1'db_appinit'\{The
|
|
.I dbenv
|
|
argument may not be NULL.
|
|
If any of the fields of the
|
|
.I dbenv
|
|
are set to 0,
|
|
defaults appropriate for the system are used where possible.
|
|
\}
|
|
.el\{If
|
|
.I dbenv
|
|
is NULL
|
|
or any of its fields are set to 0,
|
|
defaults appropriate for the system are used where possible.
|
|
\}
|
|
.PP
|
|
The following fields in the DB_ENV structure may be initialized before calling
|
|
.IR \\$1 :
|
|
\}
|
|
.el\{\
|
|
based on which set methods have been used.
|
|
It is expected that applications will use a single DbEnv object as the
|
|
argument to all of the subsystems in the DB package.
|
|
The fields of the DbEnv object used by
|
|
.I \\$1
|
|
are described below.
|
|
As references to the DbEnv object may be maintained by
|
|
.IR \\$1 ,
|
|
it is necessary that the DbEnv object and memory it references be valid
|
|
until the object is destroyed.
|
|
.ie '\\$1'appinit'\{\
|
|
The
|
|
.I dbenv
|
|
argument may not be NULL.
|
|
If any of the fields of the
|
|
.I dbenv
|
|
are set to 0,
|
|
defaults appropriate for the system are used where possible.
|
|
\}
|
|
.el\{\
|
|
Any of the DbEnv fields that are not explicitly set will default to
|
|
appropriate values.
|
|
\}
|
|
.PP
|
|
The following fields in the DbEnv object may be initialized, using the
|
|
appropriate set method, before calling
|
|
.IR \\$1 :
|
|
\}
|
|
..
|
|
.\" The DB_ENV common fields macros.
|
|
.de Se
|
|
.if '\*[TYPE]'JAVA'\{\
|
|
.TP 5
|
|
DbErrcall db_errcall;
|
|
.ns
|
|
.TP 5
|
|
String db_errpfx;
|
|
.ns
|
|
.TP 5
|
|
int db_verbose;
|
|
The error fields of the DbEnv behave as described for
|
|
.IR DbEnv (3).
|
|
\}
|
|
.ie '\*[TYPE]'CXX'\{\
|
|
.TP 5
|
|
void *(*db_errcall)(char *db_errpfx, char *buffer);
|
|
.ns
|
|
.TP 5
|
|
FILE *db_errfile;
|
|
.ns
|
|
.TP 5
|
|
const char *db_errpfx;
|
|
.ns
|
|
.TP 5
|
|
class ostream *db_error_stream;
|
|
.ns
|
|
.TP 5
|
|
int db_verbose;
|
|
The error fields of the DbEnv behave as described for
|
|
.IR DbEnv (3).
|
|
\}
|
|
.el\{\
|
|
void *(*db_errcall)(char *db_errpfx, char *buffer);
|
|
.ns
|
|
.TP 5
|
|
FILE *db_errfile;
|
|
.ns
|
|
.TP 5
|
|
const char *db_errpfx;
|
|
.ns
|
|
.TP 5
|
|
int db_verbose;
|
|
The error fields of the DB_ENV behave as described for
|
|
.IR db_appinit (3).
|
|
.sp
|
|
\}
|
|
..
|
|
.\" The open flags.
|
|
.de Fm
|
|
The
|
|
.I flags
|
|
and
|
|
.I mode
|
|
arguments specify how files will be opened and/or created when they
|
|
don't already exist.
|
|
The flags value is specified by
|
|
.BR or 'ing
|
|
together one or more of the following values:
|
|
.Sj 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_THREAD open flag macro.
|
|
.\" This macro takes two arguments:
|
|
.\" + the open function name
|
|
.\" + the object it returns.
|
|
.de Ft
|
|
.TP 5
|
|
.Sj DB_THREAD
|
|
Cause the \\$2 handle returned by the
|
|
.I \\$1
|
|
.Al function method
|
|
to be useable by multiple threads within a single address space,
|
|
i.e., to be ``free-threaded''.
|
|
.if '\*[TYPE]'JAVA'\{\
|
|
Threading is assumed in the Java API,
|
|
so no special flags are required,
|
|
and DB functions will always behave as if the DB_THREAD flag was specified.
|
|
\}
|
|
..
|
|
.\" The mode macro.
|
|
.\" This macro takes one argument:
|
|
.\" + the subsystem name.
|
|
.de Mo
|
|
All files created by the \\$1 are created with mode
|
|
.I mode
|
|
(as described in
|
|
.IR chmod (2))
|
|
and modified by the process' umask value at the time of creation (see
|
|
.IR umask (2)).
|
|
The group ownership of created files is based on the system and directory
|
|
defaults, and is not further specified by DB.
|
|
..
|
|
.\" The application exits macro.
|
|
.\" This macro takes one argument:
|
|
.\" + the application name.
|
|
.de Ex
|
|
The
|
|
.I \\$1
|
|
utility exits 0 on success, and >0 if an error occurs.
|
|
..
|
|
.\" The application -h section.
|
|
.\" This macro takes one argument:
|
|
.\" + the application name
|
|
.de Dh
|
|
DB_HOME
|
|
If the
|
|
.B \-h
|
|
option is not specified and the environment variable
|
|
.I DB_HOME
|
|
is set, it is used as the path of the database home, as described in
|
|
.IR db_appinit (3).
|
|
..
|
|
.\" The function DB_HOME ENVIRONMENT VARIABLES section.
|
|
.\" This macro takes one argument:
|
|
.\" + the open function name
|
|
.de Eh
|
|
DB_HOME
|
|
If the
|
|
.I dbenv
|
|
argument to
|
|
.I \\$1
|
|
was initialized using
|
|
.IR db_appinit ,
|
|
the environment variable DB_HOME may be used as the path of the database
|
|
home for the interpretation of the
|
|
.I dir
|
|
argument to
|
|
.IR \\$1 ,
|
|
as described in
|
|
.IR db_appinit (3).
|
|
.if \\n(.$>1 \{Specifically,
|
|
.I \\$1
|
|
is affected by the configuration string value of \\$2.\}
|
|
..
|
|
.\" The function TMPDIR ENVIRONMENT VARIABLES section.
|
|
.\" This macro takes two arguments:
|
|
.\" + the interface, e.g., "transaction region"
|
|
.\" + the prefix, e.g., "txn" (or the class name for C++, e.g., "DbTxn")
|
|
.de Ev
|
|
TMPDIR
|
|
If the
|
|
.I dbenv
|
|
argument to
|
|
.ie '\*[TYPE]'C'\{\
|
|
.ds Vo \\$2_open
|
|
\}
|
|
.el\{\
|
|
.ds Vo \\$2::open
|
|
\}
|
|
.I \\*(Vo
|
|
was NULL or not initialized using
|
|
.IR db_appinit ,
|
|
the environment variable TMPDIR may be used as the directory in which to
|
|
create the \\$1,
|
|
as described in the
|
|
.I \\*(Vo
|
|
section above.
|
|
.rm Vo
|
|
..
|
|
.\" The unused flags macro.
|
|
.de Fl
|
|
The
|
|
.I flags
|
|
parameter is currently unused, and must be set to 0.
|
|
..
|
|
.\" The no-space TP macro.
|
|
.de Nt
|
|
.br
|
|
.ns
|
|
.TP 5
|
|
..
|
|
.\" The return values of the functions macros.
|
|
.\" Rc is the standard two-value return with a suffix for more values.
|
|
.\" Ro is the standard two-value return but there were previous values.
|
|
.\" Rt is the standard two-value return, returning errno, 0, or < 0.
|
|
.\" These macros take one argument:
|
|
.\" + the routine name
|
|
.de Rc
|
|
The
|
|
.I \\$1
|
|
.ie '\*[TYPE]'C'\{function returns the value of
|
|
.I errno
|
|
on failure,
|
|
0 on success,
|
|
\}
|
|
.el\{method throws a
|
|
.IR DbException (3)
|
|
.ie '\*[TYPE]'CXX'\{or returns the value of
|
|
.I errno
|
|
on failure,
|
|
0 on success,
|
|
\}
|
|
.el\{that encapsulates an
|
|
.I errno
|
|
on failure,
|
|
\}
|
|
\}
|
|
..
|
|
.de Ro
|
|
Otherwise, the
|
|
.I \\$1
|
|
.ie '\*[TYPE]'C'\{function returns the value of
|
|
.I errno
|
|
on failure and 0 on success.
|
|
\}
|
|
.el\{method throws a
|
|
.IR DbException (3)
|
|
.ie '\*[TYPE]'CXX'\{or returns the value of
|
|
.I errno
|
|
on failure and 0 on success.
|
|
\}
|
|
.el\{that encapsulates an
|
|
.I errno
|
|
on failure,
|
|
\}
|
|
\}
|
|
..
|
|
.de Rt
|
|
The
|
|
.I \\$1
|
|
.ie '\*[TYPE]'C'\{function returns the value of
|
|
.I errno
|
|
on failure and 0 on success.
|
|
\}
|
|
.el\{method throws a
|
|
.IR DbException (3)
|
|
.ie '\*[TYPE]'CXX'\{or returns the value of
|
|
.I errno
|
|
on failure and 0 on success.
|
|
\}
|
|
.el\{that encapsulates an
|
|
.I errno
|
|
on failure.
|
|
\}
|
|
\}
|
|
..
|
|
.\" The TXN id macro.
|
|
.de Tx
|
|
.IP
|
|
If the file is being accessed under transaction protection,
|
|
the
|
|
.I txnid
|
|
parameter is a transaction ID returned from
|
|
.IR txn_begin ,
|
|
otherwise, NULL.
|
|
..
|
|
.\" The XXX_unlink function text macro.
|
|
.\" This macro takes two arguments:
|
|
.\" + the interface, e.g., "transaction region"
|
|
.\" + the prefix (for C++, this is the class name)
|
|
.de Un
|
|
.ie '\*[TYPE]'C'\{\
|
|
.ds Va db_appinit
|
|
.ds Vc \\$2_close
|
|
.ds Vo \\$2_open
|
|
.ds Vu \\$2_unlink
|
|
\}
|
|
.el\{\
|
|
.ds Va DbEnv::appinit
|
|
.ds Vc \\$2::close
|
|
.ds Vo \\$2::open
|
|
.ds Vu \\$2::unlink
|
|
\}
|
|
.Fn \\*(Vu
|
|
The
|
|
.I \\*(Vu
|
|
.Al function method
|
|
destroys the \\$1 identified by the directory
|
|
.IR dir ,
|
|
removing all files used to implement the \\$1.
|
|
.ie '\\$2'log' \{(The log files themselves and the directory
|
|
.I dir
|
|
are not removed.)\}
|
|
.el \{(The directory
|
|
.I dir
|
|
is not removed.)\}
|
|
If there are processes that have called
|
|
.I \\*(Vo
|
|
without calling
|
|
.I \\*(Vc
|
|
(i.e., there are processes currently using the \\$1),
|
|
.I \\*(Vu
|
|
will fail without further action,
|
|
unless the force flag is set,
|
|
in which case
|
|
.I \\*(Vu
|
|
will attempt to remove the \\$1 files regardless of any processes
|
|
still using the \\$1.
|
|
.PP
|
|
The result of attempting to forcibly destroy the region when a process
|
|
has the region open is unspecified.
|
|
Processes using a shared memory region maintain an open file descriptor
|
|
for it.
|
|
On UNIX systems, the region removal should succeed
|
|
and processes that have already joined the region should continue to
|
|
run in the region without change,
|
|
however processes attempting to join the \\$1 will either fail or
|
|
attempt to create a new region.
|
|
On other systems, e.g., WNT, where the
|
|
.IR unlink (2)
|
|
system call will fail if any process has an open file descriptor
|
|
for the file,
|
|
the region removal will fail.
|
|
.PP
|
|
In the case of catastrophic or system failure,
|
|
database recovery must be performed (see
|
|
.IR db_recover (1)
|
|
or the DB_RECOVER and DB_RECOVER_FATAL flags to
|
|
.IR \\*(Va (3)).
|
|
Alternatively, if recovery is not required because no database state is
|
|
maintained across failures,
|
|
it is possible to clean up a \\$1 by removing all of the
|
|
files in the directory specified to the
|
|
.I \\*(Vo
|
|
.Al function, method,
|
|
as \\$1 files are never created in any directory other than the one
|
|
specified to
|
|
.IR \\*(Vo .
|
|
Note, however,
|
|
that this has the potential to remove files created by the other DB
|
|
subsystems in this database environment.
|
|
.PP
|
|
.Rt \\*(Vu
|
|
.rm Va
|
|
.rm Vo
|
|
.rm Vu
|
|
.rm Vc
|
|
..
|
|
.\" Signal paragraph for standard utilities.
|
|
.\" This macro takes one argument:
|
|
.\" + the utility name.
|
|
.de Si
|
|
The
|
|
.I \\$1
|
|
utility attaches to DB shared memory regions.
|
|
In order to avoid region corruption,
|
|
it should always be given the chance to detach and exit gracefully.
|
|
To cause
|
|
.I \\$1
|
|
to clean up after itself and exit,
|
|
send it an interrupt signal (SIGINT).
|
|
..
|
|
.\" Logging paragraph for standard utilities.
|
|
.\" This macro takes one argument:
|
|
.\" + the utility name.
|
|
.de Pi
|
|
.B \-L
|
|
Log the execution of the \\$1 utility to the specified file in the
|
|
following format, where ``###'' is the process ID, and the date is
|
|
the time the utility starting running.
|
|
.sp
|
|
\\$1: ### Wed Jun 15 01:23:45 EDT 1995
|
|
.sp
|
|
This file will be removed if the \\$1 utility exits gracefully.
|
|
..
|
|
.\" Malloc paragraph.
|
|
.\" This macro takes one argument:
|
|
.\" + the allocated object
|
|
.de Ma
|
|
.if !'\*[TYPE]'JAVA'\{\
|
|
\\$1 are created in allocated memory.
|
|
If
|
|
.I db_malloc
|
|
is non-NULL,
|
|
it is called to allocate the memory,
|
|
otherwise,
|
|
the library function
|
|
.IR malloc (3)
|
|
is used.
|
|
The function
|
|
.I db_malloc
|
|
must match the calling conventions of the
|
|
.IR malloc (3)
|
|
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.
|
|
\}
|
|
..
|
|
.\" Underlying function paragraph.
|
|
.\" This macro takes two arguments:
|
|
.\" + the function name
|
|
.\" + the utility name
|
|
.de Uf
|
|
The
|
|
.I \\$1
|
|
.Al function method
|
|
is the underlying function used by the
|
|
.IR \\$2 (1)
|
|
utility.
|
|
See the source code for the
|
|
.I \\$2
|
|
utility for an example of using
|
|
.I \\$1
|
|
in a UNIX environment.
|
|
..
|
|
.\" Underlying function paragraph, for C++.
|
|
.\" This macro takes three arguments:
|
|
.\" + the C++ method name
|
|
.\" + the function name for C
|
|
.\" + the utility name
|
|
.de Ux
|
|
The
|
|
.I \\$1
|
|
method is based on the C
|
|
.I \\$2
|
|
function, which
|
|
is the underlying function used by the
|
|
.IR \\$3 (1)
|
|
utility.
|
|
See the source code for the
|
|
.I \\$3
|
|
utility for an example of using
|
|
.I \\$2
|
|
in a UNIX environment.
|
|
..
|
|
.\" Stat field macro.
|
|
.de Sf
|
|
.ie '\*[TYPE]'CXX'\{\
|
|
u_int32_t \\$1;\}
|
|
.el\{\
|
|
int get_\\$1();\}
|
|
..
|
|
.TH Db 3 "May 4, 1998"
|
|
.UC 7
|
|
.SH NAME
|
|
Db \- database access class
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.ft B
|
|
.ie '\*[TYPE]'CXX'\{
|
|
#include <db_cxx.h>
|
|
|
|
static int
|
|
Db::open(const char *fname, DBTYPE type,
|
|
.ti +5
|
|
u_int32_t flags, int mode, DbEnv *dbenv, DbInfo *dbinfo, Db **dbpp);
|
|
|
|
DBTYPE
|
|
Db::get_type(void) const;
|
|
|
|
int
|
|
Db::close(u_int32_t flags);
|
|
|
|
int
|
|
Db::cursor(DbTxn *txnid, Dbc **cursorp);
|
|
|
|
int
|
|
Db::del(Dbt *key, DbTxn *txnid);
|
|
|
|
int
|
|
Db::fd(int *fdp);
|
|
|
|
int
|
|
Db::get(DbTxn *txnid, Dbt *key, Dbt *data, u_int32_t flags);
|
|
|
|
int
|
|
Db::put(DbTxn *txnid, Dbt *key, Dbt *data, u_int32_t flags);
|
|
|
|
int
|
|
Db::stat(void *sp, void *(*db_malloc)(size_t), u_int32_t flags);
|
|
|
|
int
|
|
Db::sync(u_int32_t flags);
|
|
\}
|
|
.el\{\
|
|
import com.sleepycat.db.*;
|
|
|
|
public static Db open(
|
|
.ti +5
|
|
String fname, int type,
|
|
.ti +5
|
|
int flags, int mode, DbEnv dbenv, DbInfo dbinfo)
|
|
throws DbException;
|
|
|
|
public int get_type();
|
|
|
|
public void close(int flags)
|
|
.ti +5
|
|
throws DbException;
|
|
|
|
public Dbc cursor(DbTxn txnid)
|
|
.ti +5
|
|
throws DbException;
|
|
|
|
public void del(Dbt key, DbTxn txnid)
|
|
.ti +5
|
|
throws DbException;
|
|
|
|
public int fd()
|
|
.ti +5
|
|
throws DbException;
|
|
|
|
public int get(DbTxn txnid, Dbt key, Dbt data, int flags)
|
|
.ti +5
|
|
throws DbException;
|
|
|
|
public void put(DbTxn txnid, Dbt key, Dbt data, int flags)
|
|
.ti +5
|
|
throws DbException;
|
|
|
|
public void sync(int flags)
|
|
.ti +5
|
|
throws DbException;
|
|
\}
|
|
.ft R
|
|
.fi
|
|
.SH DESCRIPTION
|
|
.Gn
|
|
.PP
|
|
This manual page describes the Db class, which is the center of
|
|
access activity.
|
|
.PP
|
|
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).
|
|
.PP
|
|
Storage and retrieval for the Db access methods are based on key/data pairs,
|
|
using the Dbt class.
|
|
See
|
|
.IR Dbt (3)
|
|
for specific information on the structure and capabilities of a Dbt.
|
|
.PP
|
|
The
|
|
.I Db::open
|
|
method opens the database represented by
|
|
.I 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.
|
|
.PP
|
|
The
|
|
.I Db::open
|
|
method
|
|
.ie '\*[TYPE]'CXX'\{\
|
|
copies a pointer to a Db object into the memory location referenced by
|
|
.IR dbpp .
|
|
\}
|
|
.el\{\
|
|
returns a Db object.
|
|
\}
|
|
The methods of this object allow you to perform various database actions,
|
|
as described below.
|
|
.Rt Db::open
|
|
.PP
|
|
Note, while most of the access methods use
|
|
.I file
|
|
as the name of an underlying file on disk,
|
|
this is not guaranteed.
|
|
Also,
|
|
calling
|
|
.I 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.)
|
|
.PP
|
|
The
|
|
.I type
|
|
argument is of type
|
|
.ie '\*[TYPE]'CXX'\{DBTYPE (as defined in the <db_cxx.h> include file)
|
|
and must be set to one of DB_BTREE, DB_HASH, DB_RECNO or DB_UNKNOWN.
|
|
\}
|
|
.el\{int
|
|
and must be set to one of Db.DB_BTREE, Db.DB_HASH, Db.DB_RECNO or Db.DB_UNKNOWN.
|
|
\}
|
|
If
|
|
.I type
|
|
is DB_UNKNOWN,
|
|
the database must already exist and
|
|
.I Db::open
|
|
will then determine if it is of type DB_BTREE, DB_HASH or DB_RECNO.
|
|
.PP
|
|
.Fm
|
|
.TP 5
|
|
.Sj DB_NOMMAP
|
|
Do not map this file (see
|
|
.IR DbMpool (3)
|
|
for further information).
|
|
.TP 5
|
|
.Sj 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.
|
|
.Ft Db::open Db
|
|
.TP 5
|
|
.Sj DB_TRUNCATE
|
|
``Truncate'' the database if it exists, i.e.,
|
|
behave as if the database were just created,
|
|
discarding any previous contents.
|
|
.PP
|
|
.Mo "access methods"
|
|
.PP
|
|
See
|
|
.IR DbEnv (3)
|
|
for a description of the
|
|
.I dbenv
|
|
argument, and
|
|
.IR DbInfo (3)
|
|
for a description of the
|
|
.I dbinfo
|
|
argument.
|
|
.SH "Db OPERATIONS"
|
|
The Db object returned by
|
|
.I Db::open
|
|
describes a database type,
|
|
and includes a set of functions to perform various actions,
|
|
as described below.
|
|
The methods for Db are as follows:
|
|
.ie '\*[TYPE]'CXX'\{
|
|
.TP 5
|
|
DBTYPE Db::get_type(void);\}
|
|
.el\{
|
|
.TP 5
|
|
int Db.get_type();\}
|
|
The type of the underlying access method (and file format).
|
|
Returns one of DB_BTREE, DB_HASH or DB_RECNO.
|
|
This value may be used to determine the type of the database after a
|
|
return from
|
|
.I Db::open
|
|
with the
|
|
.I type
|
|
argument set to DB_UNKNOWN.
|
|
.ie '\*[TYPE]'CXX'\{
|
|
.TP 5
|
|
int Db::close(u_int32_t flags);\}
|
|
.el\{
|
|
.TP 5
|
|
public void Db.close(int flags);\}
|
|
A method to flush any cached information to disk,
|
|
close any open cursors (see
|
|
.IR Dbc (3)),
|
|
free any allocated resources, and close any underlying files.
|
|
Since key/data pairs are cached in memory, failing to sync the
|
|
file with the
|
|
.I close
|
|
or
|
|
.I sync
|
|
method may result in inconsistent or lost information.
|
|
.IP
|
|
The
|
|
.I flags
|
|
parameter must be set to 0 or the following value:
|
|
.RS
|
|
.TP 5
|
|
.Sj DB_NOSYNC
|
|
Do not flush cached information to disk.
|
|
.RE
|
|
.IP
|
|
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.
|
|
.IP
|
|
.ft B
|
|
It is important to understand that flushing cached information to disk
|
|
only minimizes the window of opportunity for corrupted data.
|
|
.ft R
|
|
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
|
|
.IR close ,
|
|
replace the original database with the updated copy.
|
|
.IP
|
|
When multiple threads are using the Db handle concurrently,
|
|
only a single thread may call the Db handle close method.
|
|
.IP
|
|
.Rt close
|
|
.ie '\*[TYPE]'CXX'\{
|
|
.TP 5
|
|
int Db::cursor(DbTxn *txnid, Dbc **cursorp);
|
|
A method to create a cursor and copy a pointer to it into
|
|
the memory referenced by
|
|
.IR cursorp .
|
|
\}
|
|
.el\{
|
|
.TP 5
|
|
public Dbc Db.cursor(DbTxn txnid);
|
|
A method to create a cursor.
|
|
\}
|
|
.IP
|
|
A cursor is an object used to provide sequential access through a database.
|
|
.IP
|
|
.Tx
|
|
If transaction protection is enabled,
|
|
cursors must be opened and closed within the context of a transaction,
|
|
and the
|
|
.I txnid
|
|
parameter specifies the transaction context in which the cursor may be used.
|
|
See
|
|
.IR Dbc (3)
|
|
for more information.
|
|
.IP
|
|
.Rt cursor
|
|
.ie '\*[TYPE]'CXX'\{
|
|
.TP 5
|
|
int Db::del(DbTxn *txnid, Dbt *key, u_int32_t flags);\}
|
|
.el\{
|
|
.TP 5
|
|
public void Db.del(DbTxn txnid, Dbt key, int flags);\}
|
|
.br
|
|
A method to remove key/data pairs from the database.
|
|
The key/data pair associated with the specified
|
|
.I key
|
|
is discarded from the database.
|
|
In the presence of duplicate key values,
|
|
all records associated with the designated key will be discarded.
|
|
.Tx
|
|
.IP
|
|
.Fl
|
|
.IP
|
|
.Rc del
|
|
and DB_NOTFOUND if the specified
|
|
.I key
|
|
did not exist in the file.
|
|
.ie '\*[TYPE]'CXX'\{
|
|
.TP 5
|
|
int Db::fd(int *fdp);
|
|
A method that copies a file descriptor representative
|
|
of the underlying database into the memory referenced by
|
|
.IR fdp .
|
|
A file descriptor referencing the same file will be returned to all
|
|
processes that call
|
|
.I Db::open
|
|
with the same
|
|
.I file
|
|
argument.
|
|
This file descriptor may be safely used as an argument to the
|
|
.IR fcntl (2)
|
|
and
|
|
.IR flock (2)
|
|
locking functions.
|
|
The file descriptor is not necessarily associated with any of the
|
|
underlying files used by the access method.
|
|
.IP
|
|
The
|
|
.I fd
|
|
method only supports a coarse-grained form of locking.
|
|
\}
|
|
.el\{
|
|
.TP 5
|
|
public int Db.fd();
|
|
A method that returns a file descriptor representative
|
|
of the underlying database.
|
|
This method does not fit well into the Java framework and
|
|
may not appear in subsequent releases.
|
|
\}
|
|
Applications should use the lock manager where possible.
|
|
.IP
|
|
.Rt fd
|
|
.ie '\*[TYPE]'CXX'\{
|
|
.TP 5
|
|
int Db::get(DbTxn *txnid, Dbt *key, Dbt *data, u_int32_t flags);\}
|
|
.el\{
|
|
.TP 5
|
|
public int Db.get(DbTxn txnid, Dbt key, Dbt data, int flags);\}
|
|
.br
|
|
A method that is an interface for keyed retrieval from
|
|
the database.
|
|
.ie '\*[TYPE]'CXX'\{\
|
|
The address
|
|
\}
|
|
.el\{\
|
|
The byte array
|
|
\}
|
|
and length of the data associated with the specified
|
|
.I key
|
|
are returned in the object referenced by
|
|
.IR data .
|
|
.sp
|
|
In the presence of duplicate key values,
|
|
.I 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.
|
|
.ft B
|
|
Retrieval of duplicates requires the use of cursor operations.
|
|
.ft R
|
|
See
|
|
.IR Dbc (3)
|
|
for details.
|
|
.Tx
|
|
.IP
|
|
The
|
|
.I flags
|
|
parameter must be set to 0 or the following value:
|
|
.RS
|
|
.TP 5
|
|
.Sj DB_GET_RECNO
|
|
Retrieve a specific numbered record from a database.
|
|
Upon return,
|
|
both the
|
|
.I key
|
|
and
|
|
.I data
|
|
items will have been filled in,
|
|
not just the data item as is done for all other uses of the
|
|
.I get
|
|
method.
|
|
.sp
|
|
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
|
|
.IR Db::open (3)).
|
|
In this case, the
|
|
.I data
|
|
field of the
|
|
.I key
|
|
.ie '\*[TYPE]'CXX'\{\
|
|
must be a pointer to a memory location of type
|
|
.IR db_recno_t ,
|
|
\}
|
|
.el\{\
|
|
must be byte array to a memory location large enough to
|
|
hold an int,
|
|
\}
|
|
as described in
|
|
.IR Dbt (3).
|
|
.RE
|
|
.IP
|
|
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
|
|
.I get
|
|
method returns DB_KEYEMPTY.
|
|
Otherwise, if the requested key isn't in the database, the
|
|
.I get
|
|
method returns DB_NOTFOUND.
|
|
.Ro get
|
|
.ie '\*[TYPE]'CXX'\{
|
|
.TP 5
|
|
int Db::put(DbTxn *txnid, Dbt *key, Dbt *data, u_int32_t flags);\}
|
|
.el\{
|
|
.TP 5
|
|
public int Db::put(DbTxn txnid, Dbt key, Dbt data, int flags);\}
|
|
.br
|
|
A method to store key/data pairs in the database.
|
|
If the database supports duplicates,
|
|
the
|
|
.I put
|
|
method adds the new data value at the end of the duplicate set.
|
|
.Tx
|
|
.IP
|
|
The flags value is specified by
|
|
.BR or 'ing
|
|
together one or more of the following values:
|
|
.RS
|
|
.TP 5
|
|
.Sj 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
|
|
.IR key .
|
|
.TP 5
|
|
.Sj DB_NOOVERWRITE
|
|
Enter the new key/data pair only if the key does not already appear
|
|
in the database.
|
|
.RE
|
|
.IP
|
|
The default behavior of the
|
|
.I put
|
|
method 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
|
|
.I put
|
|
with the DB_NOOVERWRITE flag set will fail if the key already exists in
|
|
the database.
|
|
.IP
|
|
.Rc put
|
|
and DB_KEYEXIST if the DB_NOOVERWRITE
|
|
.I flag
|
|
was set and the key already exists in the file.
|
|
.ie '\*[TYPE]'CXX'\{
|
|
.TP 5
|
|
int Db::sync(u_int32_t flags);\}
|
|
.el\{
|
|
.TP 5
|
|
public void Db.sync(int flags);\}
|
|
A method to flush any cached information to disk.
|
|
If the database is in memory only, the
|
|
.I sync
|
|
method has no effect and will always succeed.
|
|
.IP
|
|
.Fl
|
|
.IP
|
|
See the
|
|
.I close
|
|
method description above for a discussion of Db and cached data.
|
|
.IP
|
|
.Rt sync
|
|
.ie '\*[TYPE]'CXX'\{
|
|
.TP 5
|
|
int Db::stat(void *sp,
|
|
.ti +5
|
|
void *(*db_malloc)(size_t), u_int32_t flags);
|
|
.br
|
|
A method to create a statistical structure and copy a pointer
|
|
to it into user-specified memory locations.
|
|
Specifically, if
|
|
.I sp
|
|
is non-NULL,
|
|
a pointer to the statistics for the database are copied into the memory
|
|
location it references.
|
|
\}
|
|
.el\{
|
|
.TP 5
|
|
public int DbBtreeStat Db.stat(int flags);
|
|
.br
|
|
A method to create a statistical structure and fill it with
|
|
statistics for the database.
|
|
\}
|
|
.sp
|
|
.Ma "Statistical structures"
|
|
.sp
|
|
.ft B
|
|
In the presence of multiple threads or processes accessing an active
|
|
database,
|
|
the returned information may be out-of-date.
|
|
.ft R
|
|
.sp
|
|
.ft B
|
|
This method may access all of the pages in the database,
|
|
and therefore may incur a severe performance penalty and have obvious
|
|
negative effects on the underlying buffer pool.
|
|
.ft R
|
|
.sp
|
|
.IP
|
|
The
|
|
.I flags
|
|
parameter must be set to 0 or the following value:
|
|
.IP
|
|
.RS
|
|
.TP 5
|
|
.Sj DB_RECORDCOUNT
|
|
In the case of a btree or recno database,
|
|
fill in the
|
|
.I bt_nrecs
|
|
field, 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.
|
|
.RE
|
|
.IP
|
|
.Rt stat
|
|
.IP
|
|
.ie '\*[TYPE]'CXX'\{
|
|
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_cxx.h>).
|
|
The following fields will be filled in:
|
|
\}
|
|
.el\{\
|
|
In the case of a btree or recno database,
|
|
the statistics are returned in an instance of DbBtreeStat.
|
|
The following methods are available on DbBtreeStat:
|
|
\}
|
|
.RS
|
|
.TP 5
|
|
.Sf bt_magic
|
|
Magic number that identifies the file as a btree file.
|
|
.Nt
|
|
.Sf bt_version
|
|
The version of the btree file type.
|
|
.Nt
|
|
.Sf bt_flags
|
|
Permanent database flags,
|
|
including DB_DUP, DB_FIXEDLEN, DB_RECNUM and DB_RENUMBER.
|
|
.\".Nt
|
|
.\"Sf bt_maxkey
|
|
.\"The
|
|
.\".I bt_maxkey
|
|
.\"value specified to
|
|
.\".IR Db::open (3),
|
|
.\"if any.
|
|
.Nt
|
|
.Sf bt_minkey
|
|
The
|
|
.I bt_minkey
|
|
value specified to
|
|
.IR Db::open (3),
|
|
if any.
|
|
.Nt
|
|
.Sf bt_re_len
|
|
The
|
|
.I re_len
|
|
value specified to
|
|
.IR Db::open (3),
|
|
if any.
|
|
.Nt
|
|
.Sf bt_re_pad
|
|
The
|
|
.I re_pad
|
|
value specified to
|
|
.IR Db::open (3),
|
|
if any.
|
|
.Nt
|
|
.Sf bt_pagesize
|
|
Underlying tree page size.
|
|
.Nt
|
|
.Sf bt_levels
|
|
Number of levels in the tree.
|
|
.Nt
|
|
.Sf 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).
|
|
.Nt
|
|
.Sf bt_int_pg
|
|
Number of tree internal pages.
|
|
.Nt
|
|
.Sf bt_leaf_pg
|
|
Number of tree leaf pages.
|
|
.Nt
|
|
.Sf bt_dup_pg
|
|
Number of tree duplicate pages.
|
|
.Nt
|
|
.Sf bt_over_pg
|
|
Number of tree overflow pages.
|
|
.Nt
|
|
.Sf bt_free
|
|
Number of pages on the free list.
|
|
.Nt
|
|
.Sf bt_freed
|
|
Number of pages made available for reuse because they were emptied.
|
|
.Nt
|
|
.Sf bt_int_pgfree
|
|
Number of bytes free in tree internal pages.
|
|
.Nt
|
|
.Sf bt_leaf_pgfree
|
|
Number of bytes free in tree leaf pages.
|
|
.Nt
|
|
.Sf bt_dup_pgfree
|
|
Number of bytes free in tree duplicate pages.
|
|
.Nt
|
|
.Sf bt_over_pgfree
|
|
Number of bytes free in tree overflow pages.
|
|
.Nt
|
|
.Sf bt_pfxsaved
|
|
Number of bytes saved by prefix compression.
|
|
.Nt
|
|
.Sf bt_split
|
|
Total number of tree page splits (includes fast and root splits).
|
|
.Nt
|
|
.Sf bt_rootsplit
|
|
Number of root page splits.
|
|
.Nt
|
|
.Sf 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.
|
|
.Nt
|
|
.Sf bt_added
|
|
Number of keys added.
|
|
.Nt
|
|
.Sf bt_deleted
|
|
Number of keys deleted.
|
|
.Nt
|
|
.Sf 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.)
|
|
.Nt
|
|
.Sf 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.
|
|
.Nt
|
|
.Sf 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.
|
|
.RE
|
|
.SH "ENVIRONMENT VARIABLES"
|
|
The following environment variables affect the execution of
|
|
.IR Db::open :
|
|
.TP 5
|
|
.Eh Db::open DB_DATA_DIR
|
|
.SH EXAMPLES
|
|
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
|
|
.I 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 file
|
|
.ie '\*[TYPE]'CXX'\{\
|
|
.I examples_cxx/AccessExample.cpp
|
|
in the Db source distribution for a C++
|
|
\}
|
|
.el\{\
|
|
.I java/src/com/sleepycat/examples/AccessExample.java
|
|
in the Db source distribution for a Java
|
|
\}
|
|
language code example of how such
|
|
an application might use the Db library.
|
|
.SH ERRORS
|
|
.Ek
|
|
.PP
|
|
.Ee Db::open
|
|
.na
|
|
.Nh
|
|
Db::sync(3),
|
|
DbLock::get(3),
|
|
DbLock::put(3),
|
|
DbLockTab::id(3),
|
|
DbLockTab::vec(3),
|
|
DbLog::db_register(3),
|
|
DbLog::put(3),
|
|
DbMpool::close(3),
|
|
DbMpool::db_register(3),
|
|
DbMpool::open(3),
|
|
DbMpoolFile::close(3),
|
|
DbMpoolFile::get(3),
|
|
DbMpoolFile::open(3),
|
|
DbMpoolFile::put(3),
|
|
DbMpoolFile::set(3),
|
|
DbMpoolFile::sync(3),
|
|
calloc(3),
|
|
close(2),
|
|
fcntl(2),
|
|
fflush(3),
|
|
malloc(3),
|
|
memcpy(3),
|
|
memmove(3),
|
|
memset(3),
|
|
mmap(2),
|
|
munmap(2),
|
|
open(2),
|
|
read(2),
|
|
realloc(3),
|
|
sigfillset(3),
|
|
sigprocmask(2),
|
|
stat(2),
|
|
strcpy(3),
|
|
strdup(3),
|
|
strerror(3),
|
|
strlen(3),
|
|
time(3),
|
|
and
|
|
unlink(2).
|
|
.Hy
|
|
.ad
|
|
.PP
|
|
.Ec Db::open
|
|
.TP 5
|
|
.Ea
|
|
.TP 5
|
|
[EINVAL]
|
|
An invalid flag value or parameter was specified (e.g., unknown database
|
|
type, page size, hash method, recno pad byte, byte order) or a flag
|
|
value or parameter that is incompatible with the current
|
|
.I file
|
|
specification.
|
|
.sp
|
|
.Et
|
|
.sp
|
|
There is a mismatch between the version number of
|
|
.I file
|
|
and the software.
|
|
.sp
|
|
A
|
|
.I re_source
|
|
file was specified with either the DB_THREAD flag or a non-NULL
|
|
.I tx_info
|
|
field in the DbEnv argument to
|
|
.IR Db::open .
|
|
.TP 5
|
|
[ENOENT]
|
|
A non-existent
|
|
.I re_source
|
|
file was specified.
|
|
.TP 5
|
|
.Ep
|
|
.PP
|
|
.Ee Db::close
|
|
.na
|
|
.Nh
|
|
Db::sync(3),
|
|
DbLock::get(3),
|
|
DbLock::put(3),
|
|
DbLockTab::vec(3),
|
|
DbLog::db_register(3),
|
|
DbLog::put(3),
|
|
DbMpool::close(3),
|
|
DbMpoolFile::close(3),
|
|
DbMpoolFile::get(3),
|
|
DbMpoolFile::put(3),
|
|
DbMpoolFile::set(3),
|
|
DbMpoolFile::sync(3),
|
|
calloc(3),
|
|
close(2),
|
|
fflush(3),
|
|
malloc(3),
|
|
memcpy(3),
|
|
memmove(3),
|
|
memset(3),
|
|
munmap(2),
|
|
realloc(3),
|
|
and
|
|
strerror(3).
|
|
.Hy
|
|
.ad
|
|
.PP
|
|
.Ee Db::cursor
|
|
.na
|
|
.Nh
|
|
calloc(3).
|
|
.Hy
|
|
.ad
|
|
.PP
|
|
.Ec Db::cursor
|
|
.TP 5
|
|
.Ei
|
|
.TP 5
|
|
.Ep
|
|
.PP
|
|
.Ee Db::del
|
|
.na
|
|
.Nh
|
|
DbLock::get(3),
|
|
DbLock::put(3),
|
|
DbLockTab::id(3),
|
|
DbLockTab::vec(3),
|
|
DbLog::put(3),
|
|
DbMpoolFile::get(3),
|
|
DbMpoolFile::put(3),
|
|
DbMpoolFile::set(3),
|
|
calloc(3),
|
|
fcntl(2),
|
|
fflush(3),
|
|
malloc(3),
|
|
memcmp(3),
|
|
memcpy(3),
|
|
memmove(3),
|
|
memset(3),
|
|
realloc(3),
|
|
and
|
|
strerror(3).
|
|
.Hy
|
|
.ad
|
|
.PP
|
|
.Ec Db::del
|
|
.TP 5
|
|
.Ea
|
|
.TP 5
|
|
.Ei
|
|
.TP 5
|
|
.Ep
|
|
.PP
|
|
.Ec Db::fd
|
|
.TP 5
|
|
[ENOENT]
|
|
The
|
|
.I Db::fd
|
|
method was called for an in-memory database,
|
|
or no underlying file has yet been created.
|
|
.TP 5
|
|
.Ep
|
|
.PP
|
|
.Ee Db::get
|
|
.na
|
|
.Nh
|
|
DbLock::get(3),
|
|
DbLock::put(3),
|
|
DbLockTab::id(3),
|
|
DbLockTab::vec(3),
|
|
DbLog::put(3),
|
|
DbMpoolFile::get(3),
|
|
DbMpoolFile::put(3),
|
|
DbMpoolFile::set(3),
|
|
Dbc::get(3),
|
|
calloc(3),
|
|
fcntl(2),
|
|
fflush(3),
|
|
malloc(3),
|
|
memcmp(3),
|
|
memcpy(3),
|
|
memmove(3),
|
|
memset(3),
|
|
realloc(3),
|
|
and
|
|
strerror(3).
|
|
.Hy
|
|
.ad
|
|
.PP
|
|
.Ec Db::get
|
|
.TP 5
|
|
.Ea
|
|
.TP 5
|
|
.Ei
|
|
.sp
|
|
The DB_THREAD flag was specified to the
|
|
.IR Db::open (3)
|
|
method and neither the DB_DBT_MALLOC or DB_DBT_USERMEM flags were set
|
|
in the Dbt.
|
|
.sp
|
|
A record number of 0 was specified.
|
|
.TP 5
|
|
.Ep
|
|
.PP
|
|
.Ee Db::put
|
|
.na
|
|
.Nh
|
|
DbLock::get(3),
|
|
DbLock::put(3),
|
|
DbLockTab::id(3),
|
|
DbLockTab::vec(3),
|
|
DbLog::put(3),
|
|
DbMpoolFile::get(3),
|
|
DbMpoolFile::put(3),
|
|
DbMpoolFile::set(3),
|
|
calloc(3),
|
|
fcntl(2),
|
|
fflush(3),
|
|
malloc(3),
|
|
memcmp(3),
|
|
memcpy(3),
|
|
memmove(3),
|
|
memset(3),
|
|
realloc(3),
|
|
and
|
|
strerror(3).
|
|
.Hy
|
|
.ad
|
|
.PP
|
|
.Ec Db::put
|
|
.TP 5
|
|
.Es
|
|
.TP 5
|
|
.Ea
|
|
.TP 5
|
|
.Ei
|
|
.sp
|
|
A record number of 0 was specified.
|
|
.sp
|
|
An attempt was made to add a record to a fixed-length database that
|
|
was too large to fit.
|
|
.sp
|
|
An attempt was made to do a partial put.
|
|
.TP 5
|
|
.Ep
|
|
.TP 5
|
|
[ENOSPC]
|
|
A btree exceeded the maximum btree depth (255).
|
|
.PP
|
|
.Ee Db::stat
|
|
.na
|
|
.Nh
|
|
DbLock::get(3),
|
|
DbLock::put(3),
|
|
DbLockTab::id(3),
|
|
DbLockTab::vec(3),
|
|
DbMpoolFile::get(3),
|
|
DbMpoolFile::put(3),
|
|
calloc(3),
|
|
fcntl(2),
|
|
fflush(3),
|
|
malloc(3),
|
|
memcpy(3),
|
|
and
|
|
memset(3).
|
|
.Hy
|
|
.ad
|
|
.PP
|
|
.Ee Db::sync
|
|
.na
|
|
.Nh
|
|
Db::get(3),
|
|
Db::sync(3),
|
|
DbLock::get(3),
|
|
DbLock::put(3),
|
|
DbLockTab::id(3),
|
|
DbLockTab::vec(3),
|
|
DbLog::put(3),
|
|
DbMpoolFile::get(3),
|
|
DbMpoolFile::put(3),
|
|
DbMpoolFile::set(3),
|
|
DbMpoolFile::sync(3),
|
|
calloc(3),
|
|
close(2),
|
|
fcntl(2),
|
|
fflush(3),
|
|
malloc(3),
|
|
memcpy(3),
|
|
memmove(3),
|
|
memset(3),
|
|
munmap(2),
|
|
open(2),
|
|
realloc(3),
|
|
strerror(3),
|
|
unlink(2),
|
|
and
|
|
write(2).
|
|
.Hy
|
|
.ad
|
|
.PP
|
|
.Ec Db::sync
|
|
.TP 5
|
|
.Ei
|
|
.TP 5
|
|
.Ep
|
|
.SH "SEE ALSO"
|
|
.IR "The Ubiquitous B-tree" ,
|
|
Douglas Comer, ACM Comput. Surv. 11, 2 (June 1979), 121-138.
|
|
.sp
|
|
.IR "Prefix B-trees" ,
|
|
Bayer and Unterauer, ACM Transactions on Database Systems, Vol. 2, 1
|
|
(March 1977), 11-26.
|
|
.sp
|
|
.IR "The Art of Computer Programming Vol. 3: Sorting and Searching" ,
|
|
D.E. Knuth, 1968, pp 471-480.
|
|
.sp
|
|
.IR "Dynamic Hash Tables" ,
|
|
Per-Ake Larson, Communications of the ACM, April 1988.
|
|
.sp
|
|
.IR "A New Hash Package for UNIX" ,
|
|
Margo Seltzer, USENIX Proceedings, Winter 1991.
|
|
.sp
|
|
.IR "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.
|
|
.sp
|
|
.Sa
|