зеркало из https://github.com/mozilla/gecko-dev.git
1720 строки
39 KiB
Groff
1720 строки
39 KiB
Groff
.ds TYPE C
|
|
.\"
|
|
.\" See the file LICENSE for redistribution information.
|
|
.\"
|
|
.\" Copyright (c) 1996, 1997, 1998
|
|
.\" Sleepycat Software. All rights reserved.
|
|
.\"
|
|
.\" Copyright (c) 1994, 1995
|
|
.\" The President and Fellows of Harvard University. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the University of
|
|
.\" California, Berkeley and its contributors.
|
|
.\" 4. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" @(#)db_txn.so 10.34 (Sleepycat) 5/10/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.
|
|
..
|
|
.TH DB_TXN 3 "May 10, 1998"
|
|
.UC 7
|
|
.SH NAME
|
|
db_txn \- DB transaction management
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.ft B
|
|
#include <db.h>
|
|
|
|
int
|
|
txn_open(const char *dir,
|
|
.ti +5
|
|
u_int32_t flags, int mode, DB_ENV *dbenv, DB_TXNMGR **regionp);
|
|
|
|
int
|
|
txn_begin(DB_TXNMGR *txnp, DB_TXN *pid, DB_TXN **tid);
|
|
|
|
int
|
|
txn_prepare(DB_TXN *tid);
|
|
|
|
int
|
|
txn_commit(DB_TXN *tid);
|
|
|
|
int
|
|
txn_abort(DB_TXN *tid);
|
|
|
|
u_int32_t
|
|
txn_id(DB_TXN *tid);
|
|
|
|
int
|
|
txn_checkpoint(const DB_TXNMGR *txnp, u_int32_t kbyte, u_int32_t min);
|
|
|
|
int
|
|
txn_close(DB_TXNMGR *txnp);
|
|
|
|
int
|
|
txn_unlink(const char *dir, int force, DB_ENV *dbenv);
|
|
|
|
int
|
|
txn_stat(DB_TXNMGR *txnp,
|
|
.ti +5
|
|
DB_TXN_STAT **statp, void *(*db_malloc)(size_t));
|
|
.ft R
|
|
.fi
|
|
.SH DESCRIPTION
|
|
.Gn
|
|
.PP
|
|
This manual page describes the specific details of the DB transaction
|
|
support.
|
|
.PP
|
|
The
|
|
.I db_txn
|
|
functions are the library interface that provides transaction semantics.
|
|
Full transaction support is provided by a collection of modules that
|
|
provide interfaces to the services required for transaction processing.
|
|
These services are recovery (see
|
|
.IR db_log (3)),
|
|
concurrency control (see
|
|
.IR db_lock (3)),
|
|
and the management of shared data (see
|
|
.IR db_mpool (3)).
|
|
Transaction semantics can be applied to the access methods described in
|
|
.IR db_open (3)
|
|
through function call parameters.
|
|
.PP
|
|
The model intended for transactional use (and the one that is used by
|
|
the access methods) is write-ahead logging provided by
|
|
.IR db_log (3)
|
|
to record both before- and after-images.
|
|
Locking follows a two-phase protocol, with all locks being released
|
|
at transaction commit.
|
|
.PP
|
|
.Co "transaction region" txn
|
|
.PP
|
|
.Fm
|
|
.Ft txn_open DB_TXNMGR
|
|
.TP 5
|
|
DB_TXN_NOSYNC
|
|
On transaction commit, do not synchronously flush the log.
|
|
This means that transactions exhibit the ACI (atomicity,
|
|
consistency and isolation) properties, but not D (durability), i.e.,
|
|
database integrity will be maintained but it is possible that some number
|
|
of the most recently committed transactions may be undone during recovery
|
|
instead of being redone.
|
|
.sp
|
|
The number of transactions that are potentially at risk is governed by
|
|
how often the log is checkpointed (see
|
|
.IR db_checkpoint (1))
|
|
and how many log updates can fit on a single log page.
|
|
.PP
|
|
.Mo "transaction subsystem"
|
|
.PP
|
|
The transaction subsystem is configured
|
|
.En "txn_open" "txn_close"
|
|
.TP 5
|
|
.Se
|
|
.TP 5
|
|
DB_LOG *lg_info;
|
|
The logging region that is being used for this transaction environment.
|
|
The
|
|
.I lg_info
|
|
field contains a return value from the function
|
|
.IR log_open .
|
|
.ft B
|
|
Logging is required for transaction environments,
|
|
and it is an error to not specify a logging region.
|
|
.ft R
|
|
.TP 5
|
|
DB_LOCKTAB *lk_info;
|
|
The locking region that is being used for this transaction environment.
|
|
The
|
|
.I lk_info
|
|
field contains a return value from the function
|
|
.IR lock_open .
|
|
If
|
|
.I lk_info
|
|
is NULL, no locking is done in this transaction environment.
|
|
.TP 5
|
|
u_int32_t tx_max;
|
|
The maximum number of simultaneous transactions that are supported.
|
|
This bounds the size of backing files and is used to derive limits for
|
|
the size of the lock region and logfiles.
|
|
When there are more than
|
|
.I tx_max
|
|
concurrent transactions, calls to
|
|
.I txn_begin
|
|
may cause backing files to grow.
|
|
If
|
|
.I tx_max
|
|
is 0, a default value is used.
|
|
.TP 5
|
|
int (*tx_recover)(DB_LOG *logp, DBT *log_rec,
|
|
.ti +5
|
|
DB_LSN *lsnp, int redo, void *info);
|
|
.br
|
|
A function that is called by
|
|
.I txn_abort
|
|
during transaction abort.
|
|
This function takes five arguments:
|
|
.RS
|
|
.TP 5
|
|
logp
|
|
A pointer to the transaction log (DB_LOG *).
|
|
.TP 5
|
|
log_rec
|
|
A log record.
|
|
.TP 5
|
|
lsnp
|
|
A pointer to a log sequence number (DB_LSN *).
|
|
.TP 5
|
|
redo
|
|
An integer value that is set to one of the following values:
|
|
.RS
|
|
.TP 5
|
|
DB_TXN_BACKWARD_ROLL
|
|
The log is being read backward to determine which transactions have been
|
|
committed and which transactions were not (and should therefore be aborted
|
|
during recovery).
|
|
.TP 5
|
|
DB_TXN_FORWARD_ROLL
|
|
The log is being played forward, any transaction ids encountered that
|
|
have not been entered into the list referenced by
|
|
.I info
|
|
should be ignored.
|
|
.TP 5
|
|
DB_TXN_OPENFILES
|
|
The log is being read to open all the files required to perform recovery.
|
|
.TP 5
|
|
DB_TXN_REDO
|
|
Redo the operation described by the log record.
|
|
.TP 5
|
|
DB_TXN_UNDO
|
|
Undo the operation described by the log record.
|
|
.RE
|
|
.TP 5
|
|
info
|
|
An opaque pointer used to reference the list of transaction IDs encountered
|
|
during recovery.
|
|
.RE
|
|
.IP
|
|
If
|
|
.I recover
|
|
is NULL,
|
|
the default is that only DB access method operations are transaction
|
|
protected,
|
|
and the default recover function will be used.
|
|
.PP
|
|
.Rt txn_open
|
|
.PP
|
|
.Fn txn_begin
|
|
The
|
|
.I txn_begin
|
|
function creates a new transaction in the designated transaction manager,
|
|
copying a pointer to a DB_TXN that uniquely identifies it into the memory
|
|
referenced by
|
|
.IR tid .
|
|
If the
|
|
.I pid
|
|
argument is non-NULL,
|
|
the new transaction is a nested transaction with the transaction indicated by
|
|
.I pid
|
|
as its parent.
|
|
.PP
|
|
Transactions may not span threads, i.e.,
|
|
each transaction must begin and end in the same thread,
|
|
and each transaction may only be used by a single thread.
|
|
.PP
|
|
.Rt txn_begin
|
|
.PP
|
|
.Fn txn_prepare
|
|
The
|
|
.I txn_prepare
|
|
function initiates the beginning of a two phase commit.
|
|
In a distributed transaction environment,
|
|
.I db
|
|
can be used as a local transaction manager.
|
|
In this case,
|
|
the distributed transaction manager must send
|
|
.I prepare
|
|
messages to each local manager.
|
|
The local manager must then issue a
|
|
.I txn_prepare
|
|
and await its successful return before responding to the distributed
|
|
transaction manager.
|
|
Only after the distributed transaction manager receives successful
|
|
responses from all of its
|
|
.I prepare
|
|
messages should it issue any
|
|
.I commit
|
|
messages.
|
|
.PP
|
|
.Rt txn_prepare
|
|
.PP
|
|
.Fn txn_commit
|
|
The
|
|
.I txn_commit
|
|
function ends the transaction specified by the
|
|
.I tid
|
|
argument.
|
|
If DB_TXN_NOSYNC was not specified, a commit log record is written and
|
|
flushed to disk, as are all previously written log records.
|
|
If the transaction is nested, its locks are acquired by the parent
|
|
transaction, otherwise its locks are released.
|
|
Any applications that require strict two-phase locking must not
|
|
release any locks explicitly, leaving them all to be released by
|
|
.IR txn_commit .
|
|
.PP
|
|
.Rt txn_commit
|
|
.PP
|
|
.Fn txn_abort
|
|
The
|
|
.I txn_abort
|
|
function causes an abnormal termination of the transaction.
|
|
The log is played backwards and any necessary recovery operations are
|
|
initiated through the
|
|
.I recover
|
|
function specified to
|
|
.IR txn_open .
|
|
After recovery is completed, all locks held by the transaction are acquired
|
|
by the parent transaction in the case of a nested transaction or released
|
|
in the case of a non-nested transaction.
|
|
As is the case for
|
|
.IR txn_commit ,
|
|
applications that require strict two phase locking should not explicitly
|
|
release any locks.
|
|
.PP
|
|
.Rt txn_abort
|
|
.PP
|
|
.Fn txn_id
|
|
The
|
|
.I txn_id
|
|
function returns the unique transaction id associated with the specified
|
|
transaction.
|
|
Locking calls made on behalf of this transaction should use the value
|
|
returned from
|
|
.I txn_id
|
|
as the locker parameter to the
|
|
.I lock_get
|
|
or
|
|
.I lock_vec
|
|
calls.
|
|
.PP
|
|
.Fn txn_close
|
|
The
|
|
.I txn_close
|
|
function detaches a process from the transaction environment specified
|
|
by the DB_TXNMGR pointer.
|
|
All mapped regions are unmapped and any allocated resources are freed.
|
|
Any uncommitted transactions are aborted.
|
|
.PP
|
|
.Cc txn
|
|
.PP
|
|
When multiple threads are using the DB_TXNMGR handle concurrently,
|
|
only a single thread may call the
|
|
.I txn_close
|
|
function.
|
|
.PP
|
|
.Rt txn_close
|
|
.PP
|
|
.Un "transaction region" txn
|
|
.PP
|
|
.Fn txn_checkpoint
|
|
The
|
|
.I txn_checkpoint
|
|
function syncs the underlying memory pool,
|
|
writes a checkpoint record to the log and then flushes the log.
|
|
.PP
|
|
If either
|
|
.I kbyte
|
|
or
|
|
.I min
|
|
is non-zero,
|
|
the checkpoint is only done if more than
|
|
.I min
|
|
minutes have passed since the last checkpoint,
|
|
or if more than
|
|
.I kbyte
|
|
kilobytes of log data have been written since the last checkpoint.
|
|
.PP
|
|
.Rc txn_checkpoint
|
|
and DB_INCOMPLETE if there were pages that needed to be written but that
|
|
.IR memp_sync (3)
|
|
was unable to write immediately.
|
|
In this case, the
|
|
.I txn_checkpoint
|
|
call should be retried.
|
|
.PP
|
|
.Uf txn_checkpoint db_checkpoint
|
|
.PP
|
|
.Fn txn_stat
|
|
The
|
|
.I txn_stat
|
|
function creates a statistical structure and copies a pointer to it into
|
|
the user-specified memory location.
|
|
.PP
|
|
.Ma "Statistical structure"
|
|
.PP
|
|
The transaction region statistics are stored in a structure of type
|
|
DB_TXN_STAT (typedef'd in <db.h>).
|
|
The following DB_TXN_STAT fields will be filled in:
|
|
.TP 5
|
|
u_int32_t st_refcnt;
|
|
The number of references to the region.
|
|
.Nt
|
|
u_int32_t st_regsize;
|
|
The size of the region.
|
|
.Nt
|
|
DB_LSN st_last_ckp;
|
|
The LSN of the last checkpoint.
|
|
.Nt
|
|
DB_LSN st_pending_ckp;
|
|
The LSN of any checkpoint that is currently in progress.
|
|
If
|
|
.I st_pending_ckp
|
|
is the same as
|
|
.I st_last_ckp
|
|
there is no checkpoint in progress.
|
|
.Nt
|
|
time_t st_time_ckp;
|
|
The time the last completed checkpoint finished (as returned by
|
|
.IR time (2)).
|
|
.Nt
|
|
u_int32_t st_last_txnid;
|
|
The last transaction ID allocated.
|
|
.Nt
|
|
u_int32_t st_maxtxns;
|
|
The maximum number of active transactions supported by the region.
|
|
.Nt
|
|
u_int32_t st_naborts;
|
|
The number of transactions that have aborted.
|
|
.Nt
|
|
u_int32_t st_nactive;
|
|
The number of transactions that are currently active.
|
|
.Nt
|
|
u_int32_t st_nbegins;
|
|
The number of transactions that have begun.
|
|
.Nt
|
|
u_int32_t st_ncommits;
|
|
The number of transactions that have committed.
|
|
.Nt
|
|
u_int32_t st_region_wait;
|
|
The number of times that a thread of control was forced to wait before
|
|
obtaining the region lock.
|
|
.Nt
|
|
u_int32_t st_region_nowait;
|
|
The number of times that a thread of control was able to obtain
|
|
the region lock without waiting.
|
|
.Nt
|
|
DB_TXN_ACTIVE *st_txnarray;
|
|
A pointer to an array of
|
|
.I st_nactive
|
|
DB_TXN_ACTIVE structures, describing the currently active transactions.
|
|
The following fields of the DB_TXN_ACTIVE structure (typedef'd in <db.h>)
|
|
will be filled in:
|
|
.sp
|
|
.RS
|
|
.TP 5
|
|
u_int32_t txnid;
|
|
The transaction ID as returned by
|
|
.IR txn_begin (3).
|
|
.Nt
|
|
DB_LSN lsn;
|
|
The LSN of the transaction-begin record.
|
|
.RE
|
|
.PP
|
|
.SH "TRANSACTIONS
|
|
Creating transaction protected applications using the DB access methods
|
|
requires little system customization.
|
|
In most cases,
|
|
the default parameters to the locking, logging, memory pool,
|
|
and transaction subsystems will suffice.
|
|
Applications can use
|
|
.IR db_appinit (3)
|
|
to perform this initialization, or they may do it explicitly.
|
|
.PP
|
|
Each database operation (i.e., any call to a function underlying the
|
|
handles returned by
|
|
.IR db_open (3)
|
|
and
|
|
.IR db_cursor (3))
|
|
is normally performed on behalf of a unique locker.
|
|
If multiple calls on behalf of the same locker are desired,
|
|
then transactions must be used.
|
|
.PP
|
|
Once the application has initialized the DB subsystems that it is using,
|
|
it may open the DB access method databases.
|
|
For applications performing transactions,
|
|
the databases must be opened after subsystem initialization,
|
|
and cannot be opened as part of a transaction.
|
|
Once the databases are opened, the application can group sets of
|
|
operations into transactions, by surrounding the operations
|
|
with the appropriate
|
|
.IR txn_begin ,
|
|
.I txn_commit
|
|
and
|
|
.I txn_abort
|
|
calls.
|
|
Databases accessed by a transaction must not be closed
|
|
during the transaction.
|
|
Note,
|
|
it is not necessary to transaction protect read-only transactions,
|
|
unless those transactions require repeatable reads.
|
|
.PP
|
|
The DB access methods will make the appropriate calls into the
|
|
lock, log and memory pool subsystems in order to guarantee that
|
|
transaction semantics are applied.
|
|
When the application is ready to exit, all outstanding transactions
|
|
should have been committed or aborted.
|
|
At this point, all open DB files should be closed.
|
|
Once the DB database files are closed,
|
|
the DB subsystems should be closed,
|
|
either explicitly or by calling
|
|
.IR db_appexit (3).
|
|
.PP
|
|
It is also possible to use the locking, logging and transaction subsystems
|
|
of DB to provide transaction semantics to objects other than those described
|
|
by the DB access methods.
|
|
In these cases, the application will need more explicit customization of
|
|
the subsystems as well as the development of appropriate
|
|
data-structure-specific recovery functions.
|
|
.PP
|
|
For example, consider an application that provides transaction semantics
|
|
to data stored in plain UNIX files accessed using the
|
|
.IR read (2)
|
|
and
|
|
.IR write (2)
|
|
system calls.
|
|
The operations for which transaction protection is desired are bracketed
|
|
by calls to
|
|
.I txn_begin
|
|
and
|
|
.IR txn_commit .
|
|
.PP
|
|
Before data are referenced,
|
|
the application must make a call to the lock manager,
|
|
.IR db_lock ,
|
|
for a lock of the appropriate type (e.g., read)
|
|
on the object being locked.
|
|
The object might be a page in the file, a byte, a range of bytes,
|
|
or some key.
|
|
It is up to the application to ensure that appropriate locks are acquired.
|
|
Before a write is performed, the application should acquire a write
|
|
lock on the object, by making an appropriate call to the lock
|
|
manager,
|
|
.IR db_lock .
|
|
Then, the application should make a call to the
|
|
log manager,
|
|
.IR db_log ,
|
|
to record enough information to redo the operation in case of
|
|
failure after commit and to undo the operation in case of abort.
|
|
As discussed in the
|
|
.IR db_log (3)
|
|
manual page,
|
|
the application is responsible for providing any necessary structure
|
|
to the log record.
|
|
For example, the application must understand what part of the log
|
|
record is an operation code, what part identifies the file being
|
|
modified, what part is redo information, and what
|
|
part is undo information.
|
|
.PP
|
|
After the log message is written, the application may issue the write system call.
|
|
After all requests are issued, the application may call
|
|
.IR txn_commit .
|
|
When
|
|
.I txn_commit
|
|
returns, the caller is guaranteed that all necessary log writes have
|
|
been written to disk.
|
|
.PP
|
|
At any time, the application may call
|
|
.IR txn_abort ,
|
|
which will result in the appropriate calls to the
|
|
.I recover
|
|
function to restore the ``database'' to a consistent pre-transaction
|
|
state.
|
|
(The recover function must be able to either re-apply or undo the update
|
|
depending on the context, for each different type of log record.)
|
|
.PP
|
|
If the application should crash, the recovery process uses the
|
|
.I db_log
|
|
interface to read the log and call the
|
|
.I recover
|
|
function to restore the database to a consistent state.
|
|
.PP
|
|
The
|
|
.I txn_prepare
|
|
function provides the core functionality to implement distributed
|
|
transactions,
|
|
but it does not manage the notification of distributed transaction managers.
|
|
The caller is responsible for issuing
|
|
.I txn_prepare
|
|
calls to all sites participating in the transaction.
|
|
If all responses are positive, the caller can issue a
|
|
.IR txn_commit .
|
|
If any of the responses are negative, the caller should issue a
|
|
.IR txn_abort .
|
|
In general, the
|
|
.I txn_prepare
|
|
call requires that the transaction log be flushed to disk.
|
|
.\"
|
|
.\" See the file LICENSE for redistribution information.
|
|
.\"
|
|
.\" Copyright (c) 1998
|
|
.\" Sleepycat Software. All rights reserved.
|
|
.\"
|
|
.\" @(#)limits.so 8.1 (Sleepycat) 5/3/98
|
|
.\"
|
|
.de Ll
|
|
.SH "LOG FILE LIMITS
|
|
Log file sizes impose a time limit on the length of time a database
|
|
may be accessed under transaction protection, before it needs to be
|
|
dumped and reloaded (see
|
|
.IR db_dump(3)
|
|
and
|
|
.IR db_load(3)).
|
|
Unfortunately, the limits are potentially difficult to calculate.
|
|
.PP
|
|
The log file name consists of "log." followed by 5 digits, resulting
|
|
in a maximum of 99,999 log files.
|
|
Consider an application performing 600 transactions per second, for
|
|
15 hours a day, logged into 10Mb log files, where each transaction
|
|
is logging approximately 100 bytes of data. The calculation:
|
|
.PP
|
|
.nf
|
|
.RS
|
|
(10 * 2^20 * 99999) /
|
|
.ti +5
|
|
(600 * 60 * 60 * 15 * 100) = 323.63
|
|
.RE
|
|
.fi
|
|
.PP
|
|
indicates that the system will run out of log file space in
|
|
roughly 324 days.
|
|
If we increase the maximum size of the files from 10Mb to 100Mb,
|
|
the same calculation indicates that the application will run out
|
|
of log file space in roughly 9 years.
|
|
.PP
|
|
There is no way to reset the log file name space in Berkeley DB.
|
|
If your application is reaching the end of its log file name space,
|
|
you should:
|
|
.TP 5
|
|
1.
|
|
Archive your databases as if to prepare for catastrophic failure (see
|
|
.IR db_archive (1)
|
|
for more information).
|
|
.TP 5
|
|
2.
|
|
Dump and re-load
|
|
.B all
|
|
your databases (see
|
|
.IR db_dump (1)
|
|
and
|
|
.IR db_load (1)
|
|
for more information).
|
|
.TP 5
|
|
3.
|
|
Remove all of the log files from the database environment (see
|
|
.IR db_archive (1)
|
|
for more information).
|
|
.TP 5
|
|
4.
|
|
Restart your applications.
|
|
..
|
|
.de Tl
|
|
.SH "TRANSACTION ID LIMITS
|
|
The transaction ID space in Berkeley DB is 2^31, or 2 billion entries.
|
|
It is possible that some environments may need to be aware of this
|
|
limitation.
|
|
Consider an application performing 600 transactions a second for 15
|
|
hours a day.
|
|
The transaction ID space will run out in roughly 66 days:
|
|
.PP
|
|
.nf
|
|
.RS
|
|
2^31 / (600 * 15 * 60 * 60) = 66
|
|
.RE
|
|
.fi
|
|
.PP
|
|
Doing only 100 transactions a second exhausts the transaction ID space
|
|
in roughly one year.
|
|
.PP
|
|
The transaction ID space is reset each time recovery is run.
|
|
If you reach the end of your transaction ID space,
|
|
shut down your applications and restart them after running recovery (see
|
|
.IR db_recover (1)
|
|
for more information).
|
|
The most recently allocated transaction ID is the
|
|
.I st_last_txnid
|
|
value in the transaction statistics information, and is displayed by the
|
|
.IR db_stat (1)
|
|
utility.
|
|
..
|
|
.Tl
|
|
.SH "ENVIRONMENT VARIABLES"
|
|
The following environment variables affect the execution of
|
|
.IR db_txn :
|
|
.TP 5
|
|
.Eh txn_open
|
|
.TP 5
|
|
.Ev "transaction region" txn
|
|
.SH ERRORS
|
|
.Ee txn_open
|
|
.na
|
|
.Nh
|
|
close(2),
|
|
db_version(3),
|
|
fcntl(2),
|
|
fflush(3),
|
|
lseek(2),
|
|
malloc(3),
|
|
memcpy(3),
|
|
memset(3),
|
|
mmap(2),
|
|
munmap(2),
|
|
open(2),
|
|
sigfillset(3),
|
|
sigprocmask(2),
|
|
stat(2),
|
|
strcpy(3),
|
|
strdup(3),
|
|
strerror(3),
|
|
strlen(3),
|
|
time(3),
|
|
txn_unlink(3),
|
|
unlink(2),
|
|
and
|
|
write(2).
|
|
.Hy
|
|
.ad
|
|
.PP
|
|
.Ec txn_open
|
|
.TP 5
|
|
.Ei
|
|
.sp
|
|
.Et
|
|
.sp
|
|
The
|
|
.I dbenv
|
|
parameter was NULL.
|
|
.TP 5
|
|
.Em
|
|
.PP
|
|
.Ee txn_begin
|
|
.na
|
|
.Nh
|
|
fcntl(2),
|
|
fflush(3),
|
|
log_put(3),
|
|
lseek(2),
|
|
malloc(3),
|
|
memcpy(3),
|
|
memset(3),
|
|
mmap(2),
|
|
munmap(2),
|
|
strerror(3),
|
|
and
|
|
write(2).
|
|
.Hy
|
|
.ad
|
|
.PP
|
|
.Ec txn_begin
|
|
.TP 5
|
|
[ENOSPC]
|
|
The maximum number of concurrent transactions has been reached.
|
|
.PP
|
|
.Ee txn_prepare
|
|
.na
|
|
.Nh
|
|
fcntl(2),
|
|
fflush(3),
|
|
log_flush(3),
|
|
and
|
|
strerror(3).
|
|
.Hy
|
|
.ad
|
|
.PP
|
|
.Ee txn_commit
|
|
.na
|
|
.Nh
|
|
fcntl(2),
|
|
fflush(3),
|
|
lock_vec(3),
|
|
log_put(3),
|
|
malloc(3),
|
|
memcpy(3),
|
|
and
|
|
strerror(3).
|
|
.Hy
|
|
.ad
|
|
.PP
|
|
.Ec txn_commit
|
|
.TP 5
|
|
[EINVAL]
|
|
The transaction was aborted.
|
|
.PP
|
|
.Ee txn_abort
|
|
.na
|
|
.Nh
|
|
DBenv->tx_recover(3),
|
|
fcntl(2),
|
|
fflush(3),
|
|
lock_vec(3),
|
|
log_get(3),
|
|
memset(3),
|
|
and
|
|
strerror(3).
|
|
.Hy
|
|
.ad
|
|
.TP 5
|
|
[EINVAL]
|
|
The transaction was already aborted.
|
|
.PP
|
|
.Ee txn_checkpoint
|
|
.na
|
|
.Nh
|
|
fcntl(2),
|
|
fflush(3),
|
|
log_compare(3),
|
|
log_put(3),
|
|
malloc(3),
|
|
memcpy(3),
|
|
memp_sync(3),
|
|
memset(3),
|
|
strerror(3),
|
|
and
|
|
time(3).
|
|
.Hy
|
|
.ad
|
|
.TP 5
|
|
.Ei
|
|
.PP
|
|
.Ee txn_close
|
|
.na
|
|
.Nh
|
|
close(2),
|
|
fcntl(2),
|
|
fflush(3),
|
|
log_flush(3),
|
|
munmap(2),
|
|
strerror(3),
|
|
and
|
|
txn_abort(3).
|
|
.Hy
|
|
.ad
|
|
.PP
|
|
.Ee txn_unlink
|
|
.na
|
|
.Nh
|
|
close(2),
|
|
fcntl(2),
|
|
fflush(3),
|
|
malloc(3),
|
|
memcpy(3),
|
|
memset(3),
|
|
mmap(2),
|
|
munmap(2),
|
|
open(2),
|
|
sigfillset(3),
|
|
sigprocmask(2),
|
|
stat(2),
|
|
strcpy(3),
|
|
strdup(3),
|
|
strerror(3),
|
|
strlen(3),
|
|
and
|
|
unlink(2).
|
|
.Hy
|
|
.ad
|
|
.PP
|
|
.Ec txn_unlink
|
|
.TP 5
|
|
.Eb
|
|
.PP
|
|
.Ee txn_stat
|
|
.na
|
|
.Nh
|
|
fcntl(2),
|
|
and
|
|
malloc(3).
|
|
.Hy
|
|
.ad
|
|
.SH "SEE ALSO"
|
|
.IR "LIBTP: Portable, Modular Transactions for UNIX" ,
|
|
Margo Seltzer, Michael Olson, USENIX proceedings, Winter 1992.
|
|
.SH BUGS
|
|
Nested transactions are not yet implemented.
|
|
.sp
|
|
.Sa
|