зеркало из https://github.com/mozilla/gecko-dev.git
1503 строки
40 KiB
Groff
1503 строки
40 KiB
Groff
.ds TYPE C
|
|
.\"
|
|
.\" See the file LICENSE for redistribution information.
|
|
.\"
|
|
.\" Copyright (c) 1996, 1997, 1998
|
|
.\" Sleepycat Software. All rights reserved.
|
|
.\"
|
|
.\" @(#)db_intro.so 10.35 (Sleepycat) 4/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_INTRO 3 "April 10, 1998"
|
|
.UC 7
|
|
.SH "NAME
|
|
db \- the DB library overview and introduction
|
|
.SH "DESCRIPTION
|
|
.Gn
|
|
.PP
|
|
The DB library does not provide user interfaces,
|
|
data entry GUI's,
|
|
SQL support or any of the other standard user-level database interfaces.
|
|
What it does provide are the programmatic building blocks that allow you
|
|
to easily embed database-style functionality and support into other objects
|
|
or interfaces.
|
|
.SH "ARCHITECTURE
|
|
The DB library supports two different models of applications: client-server
|
|
and embedded.
|
|
.PP
|
|
In the client-server model,
|
|
a database server is created by writing an application that accepts requests
|
|
via some form of IPC and issues calls to the DB functions based on those
|
|
queries.
|
|
In this model,
|
|
applications are client programs that attach to the server and issue queries.
|
|
The client-server model trades performance for protection,
|
|
as it does not require that the applications share a protection domain with
|
|
the server,
|
|
but IPC/RPC is generally slower than a function call.
|
|
In addition,
|
|
this model simplifies the creation of network client-server applications.
|
|
.PP
|
|
In the embedded model,
|
|
an application links the DB library directly into its address space.
|
|
This provides for faster access to database functionality,
|
|
but means that the applications sharing log files, lock manager,
|
|
transaction manager or memory pool manager have the ability to read,
|
|
write, and corrupt each other's data.
|
|
.PP
|
|
It is the application designer's responsibility to select the appropriate
|
|
model for their application.
|
|
.PP
|
|
Applications require a single include file,
|
|
.IR <db.h> ,
|
|
which must be installed in an appropriate location on the system.
|
|
.SH "C++
|
|
The C++ classes provide a thin wrapper around the C API,
|
|
with the major advantages being improved encapsulation and an optional
|
|
exception mechanism for errors.
|
|
.PP
|
|
The classes and methods are named in a fashion that directly corresponds
|
|
to structures and functions in the C interface.
|
|
Likewise, arguments to methods appear in the same order as the C interface,
|
|
except to remove the explicit ``this'' pointer.
|
|
The #defines used for flags are identical between the C and C++ interfaces.
|
|
.PP
|
|
As a rule, each C++ object has exactly one structure from the underlying C
|
|
API associated with it.
|
|
The C structure is allocated with each constructor call and deallocated
|
|
with each destructor call.
|
|
Thus, the rules the user needs to follow in allocating and deallocating
|
|
structures are the same between the C and C++ interfaces.
|
|
.PP
|
|
To ensure portability to many platforms, both new and old, we make few
|
|
assumptions about the C++ compiler and library.
|
|
For example, we do not expect STL, templates or namespaces to be available.
|
|
The newest C++ feature used is exceptions, which are used liberally to
|
|
transmit error information.
|
|
Even the use of exceptions can be disabled at runtime, by using
|
|
.IR DbEnv::set_error_model ()
|
|
(see
|
|
.IR DbEnv (3)).
|
|
For a discussion of the exception mechanism, see
|
|
.IR DbException (3).
|
|
.PP
|
|
For the rest of this manual page, C interfaces are listed as the primary
|
|
reference, and C++ interfaces following parenthetically, e.g.,
|
|
.I db_open
|
|
(\c
|
|
.IR Db::open ).
|
|
.SH "JAVA
|
|
The Java classes provide a layer around the C API that is almost
|
|
identical to the C++ layer.
|
|
The classes and methods are, for the most part identical to the C++
|
|
layer. Db constants and #defines are represented as "static final int"
|
|
values. Errors conditions appear as Java exceptions.
|
|
.PP
|
|
As in C++, each Java object has exactly one structure from the underlying C
|
|
API associated with it. The Java structure is allocated with each constructor
|
|
or open call, but is deallocated only when the Java GC does so. Because
|
|
the timing or ordering of GC is not predictable, the user should take
|
|
care to do a close() when finished with any object that has such a method.
|
|
.PP
|
|
.SH SUBSYSTEMS
|
|
The DB library is made up of five major subsystems, as follows:
|
|
.TP 5
|
|
Access methods
|
|
The access methods subsystem is made up of general-purpose support for
|
|
creating and accessing files formatted as B+tree's, hashed files, and
|
|
fixed and variable length records.
|
|
These modules are useful in the absence of transactions for processes
|
|
that need fast, formatted file support.
|
|
See
|
|
.IR db_open (3)
|
|
and
|
|
.IR db_cursor (3)
|
|
(\c
|
|
.IR Db (3)
|
|
and
|
|
.IR Dbc (3))
|
|
for more information.
|
|
.TP 5
|
|
Locking
|
|
The locking subsystem is a general-purpose lock manager used by DB.
|
|
This module is useful in the absence of the rest of the DB package for
|
|
processes that require
|
|
a fast, configurable lock manager.
|
|
See
|
|
.IR db_lock (3)
|
|
(\c
|
|
.IR DbLockTab (3)
|
|
and
|
|
.IR DbLock (3))
|
|
for more information.
|
|
.TP 5
|
|
Logging
|
|
The logging subsystem is the logging support used to support the DB
|
|
transaction model.
|
|
It is largely specific to the DB package,
|
|
and unlikely to be used elsewhere.
|
|
See
|
|
.IR db_log (3)
|
|
(\c
|
|
.IR DbLog (3))
|
|
for more information.
|
|
.TP 5
|
|
Memory Pool
|
|
The memory pool subsystem is the general-purpose shared memory buffer pool
|
|
used by DB.
|
|
This module is useful outside of the DB package for processes that require
|
|
page-oriented, cached, shared file access.
|
|
See
|
|
.IR db_mpool (3)
|
|
(\c
|
|
.IR DbMpool (3)
|
|
and
|
|
.IR DbMpoolFile (3))
|
|
for more information.
|
|
.TP 5
|
|
Transactions
|
|
The transaction subsystem implements the DB transaction model.
|
|
It is largely specific to the DB package.
|
|
See
|
|
.IR db_txn (3)
|
|
(\c
|
|
.IR DbTxnMgr (3)
|
|
and
|
|
.IR DbTxn (3))
|
|
for more information.
|
|
.PP
|
|
There are several stand-alone utilities that support the DB environment.
|
|
They are as follows:
|
|
.TP 5
|
|
db_archive
|
|
The
|
|
.I db_archive
|
|
utility supports database backup, archival and log file administration.
|
|
See
|
|
.IR db_archive (1)
|
|
for more information.
|
|
.TP 5
|
|
db_recover
|
|
The
|
|
.I db_recover
|
|
utility runs after an unexpected DB or system failure to restore the
|
|
database to a consistent state.
|
|
See
|
|
.IR db_recover (1)
|
|
for more information.
|
|
.TP 5
|
|
db_checkpoint
|
|
The
|
|
.I db_checkpoint
|
|
utility runs as a daemon process,
|
|
monitoring the database log and periodically issuing checkpoints.
|
|
See
|
|
.IR db_checkpoint (1)
|
|
for more information.
|
|
.TP 5
|
|
db_deadlock
|
|
The
|
|
.I db_deadlock
|
|
utility runs as a daemon process,
|
|
periodically traversing the database lock structures and aborting transactions
|
|
when it detects a deadlock.
|
|
See
|
|
.IR db_deadlock (1)
|
|
for more information.
|
|
.TP 5
|
|
db_dump
|
|
The
|
|
.I db_dump
|
|
utility writes a copy of the database to a flat-text file in a portable
|
|
format.
|
|
See
|
|
.IR db_dump (1)
|
|
for more information.
|
|
.TP 5
|
|
db_load
|
|
The
|
|
.I db_load
|
|
utility reads the flat-text file produced by
|
|
.IR db_dump ,
|
|
and loads it into a database file.
|
|
See
|
|
.IR db_load (1)
|
|
for more information.
|
|
.TP 5
|
|
db_stat
|
|
The
|
|
.I db_stat
|
|
utility displays statistics for databases and database environments.
|
|
See
|
|
.IR db_stat (1)
|
|
for more information.
|
|
.SH "NAMING AND THE DB ENVIRONMENT
|
|
The DB application environment is described by the
|
|
.IR db_appinit (3)
|
|
(\c
|
|
.IR DbEnv (3))
|
|
manual page.
|
|
The
|
|
.I db_appinit
|
|
(\c
|
|
.IR DbEnv::appinit )
|
|
function is used to create a consistent naming scheme for all of the
|
|
subsystems sharing a DB environment.
|
|
If
|
|
.I db_appinit
|
|
(\c
|
|
.IR DbEnv::appinit )
|
|
is not called by a DB application,
|
|
naming is performed as specified by the manual page for the specific
|
|
subsystem.
|
|
.PP
|
|
DB applications that run with additional privilege should always call the
|
|
.I db_appinit
|
|
(\c
|
|
.IR DbEnv::appinit )
|
|
function to initialize DB naming for their application.
|
|
This ensures that the environment variables DB_HOME and TMPDIR will only
|
|
be used if the application explicitly specifies that they are safe.
|
|
.SH "ADMINISTERING THE DB ENVIRONMENT
|
|
A DB environment consists of a database home directory and all the
|
|
long-running daemons necessary to ensure continued functioning of
|
|
DB and its applications.
|
|
In the presence of transactions, the checkpoint daemon,
|
|
.IR db_checkpoint ,
|
|
must be run as long as there are applications present (see
|
|
.IR db_checkpoint (1)
|
|
for details).
|
|
When locking is being used, the deadlock detection daemon,
|
|
.IR db_deadlock ,
|
|
must be run as long as there are applications present (see
|
|
.IR db_deadlock (1)
|
|
for details).
|
|
The
|
|
.I db_archive
|
|
utility provides information to facilitate log reclamation and
|
|
creation of database snapshots (see
|
|
.IR db_archive (1)
|
|
for details).
|
|
After application or system failure, the
|
|
.I db_recover
|
|
utility must be run before any applications are restarted
|
|
to return the database to a consistent state (see
|
|
.IR db_recover (1)
|
|
for details).
|
|
.PP
|
|
The simplest way to administer a DB application environment is to create a
|
|
single ``home'' directory that houses all the files for the applications
|
|
that are sharing the DB environment.
|
|
In this model,
|
|
the shared memory regions (i.e., the locking, logging, memory pool, and
|
|
transaction regions) and log files will be stored in the specified directory
|
|
hierarchy.
|
|
In addition,
|
|
all data files specified using relative pathnames will be named relative
|
|
to this home directory.
|
|
When recovery needs to be run (e.g., after system or application failure),
|
|
this directory is specified as the home directory to
|
|
.IR db_recover (1),
|
|
and the system is restored to a consistent state,
|
|
ready for the applications to be restarted.
|
|
.PP
|
|
In situations where further customization is desired,
|
|
such as placing the log files on a separate device,
|
|
it is recommended that the application installation process create a
|
|
configuration file named ``DB_CONFIG'' in the database home directory,
|
|
specifying the customization.
|
|
See
|
|
.IR db_appinit (3)
|
|
(\c
|
|
.IR DbEnv (3))
|
|
for details on this procedure.
|
|
.PP
|
|
The DB architecture does not support placing the shared memory regions on
|
|
remote filesystems, e.g.,
|
|
the Network File System (NFS) and the Andrew File System (AFS).
|
|
For this reason, the database home directory must reside on a local
|
|
filesystem.
|
|
Databases,
|
|
log files and temporary files may be placed on remote filesystems,
|
|
although the application may incur a performance penalty for doing so.
|
|
.PP
|
|
It is important to realize that all applications sharing a single home
|
|
directory implicitly trust each other.
|
|
They have access to each other's data as it resides in the shared memory
|
|
buffer pool and will share resources such as buffer space and locks.
|
|
At the same time,
|
|
any applications that access the same files
|
|
.B must
|
|
share an environment if consistency is to be maintained across the
|
|
different applications.
|
|
.SH "ERROR RETURNS
|
|
Except for the historic
|
|
.I dbm
|
|
and
|
|
.I hsearch
|
|
interfaces (see
|
|
.IR db_dbm (3)
|
|
and
|
|
.IR db_hsearch (3)),
|
|
DB does not use the global variable
|
|
.I errno
|
|
to return error values.
|
|
The return values for all DB functions can be grouped into three categories:
|
|
.TP 5
|
|
0
|
|
A return value of 0 indicates that the operation was successful.
|
|
.TP 5
|
|
>0
|
|
A return value that is greater than 0 indicates that there was a system
|
|
error.
|
|
The
|
|
.I errno
|
|
value returned by the system is returned by the function, e.g.,
|
|
when a DB function is unable to allocate memory,
|
|
the return value from the function will be ENOMEM.
|
|
.TP 5
|
|
<0
|
|
A return value that is less than 0 indicates a condition that was not
|
|
a system failure,
|
|
but was not an unqualified success, either.
|
|
For example,
|
|
a routine to retrieve a key/data pair from the database may return
|
|
DB_NOTFOUND when the key/data pair does not appear in the database,
|
|
as opposed to the value of 0, which would be returned if the key/data
|
|
pair were found in the database.
|
|
All such special values returned by DB functions are less than 0 in
|
|
order to avoid conflict with possible values of
|
|
.IR errno .
|
|
.PP
|
|
There are two special return values that are somewhat similar in meaning,
|
|
are returned in similar situations,
|
|
and therefore might be confused: DB_NOTFOUND and DB_KEYEMPTY.
|
|
The DB_NOTFOUND error return indicates that the requested key/data pair did
|
|
not exist in the database or that start- or end-of-file has been reached.
|
|
The DB_KEYEMPTY error return indicates that the requested key/data pair
|
|
logically exists but was never explicitly created by the application (the
|
|
recno access method will automatically create key/data pairs under some
|
|
circumstances, see
|
|
.IR db_open (3)
|
|
(\c
|
|
.IR Db (3))
|
|
for more information),
|
|
or that the requested key/data pair was deleted and is currently in a deleted
|
|
state.
|
|
.SH "SIGNALS
|
|
When applications using DB receive signals,
|
|
it is important that they exit gracefully,
|
|
discarding any DB locks that they may hold.
|
|
This is normally done by setting a flag when a signal arrives,
|
|
and then checking for that flag periodically within the application.
|
|
Specifically, the signal handler should not attempt to release locks
|
|
and/or close the database handles itself.
|
|
This is not guaranteed to work correctly and the results are undefined.
|
|
.PP
|
|
If an application exits holding a lock,
|
|
the situation is no different than if the application crashed,
|
|
and all applications participating in the database environment
|
|
must be shutdown, and then recovery must be performed.
|
|
If this is not done, the locks that the application held can cause
|
|
unresolvable deadlocks inside the database,
|
|
and applications may then hang.
|
|
.SH "MULTI-THREADING
|
|
See
|
|
.IR db_thread (3)
|
|
for information on using DB in threaded applications.
|
|
.SH "DATABASE AND PAGE SIZES
|
|
DB stores database file page numbers as unsigned 32-bit numbers
|
|
and database file page sizes as unsigned 16-bit numbers.
|
|
This results in a maximum database size of 2^48.
|
|
The minimum database page size is 512 bytes,
|
|
resulting in a minimum maximum database size of 2^41.
|
|
.PP
|
|
DB is potentially further limited if the host system does not have
|
|
filesystem support for files larger than 2^32,
|
|
including seeking to absolute offsets within such files.
|
|
.PP
|
|
The maximum btree depth is 255.
|
|
.SH "BYTE ORDERING
|
|
The database files created by DB can be created in either little or
|
|
big-endian formats.
|
|
By default, the native format of the machine on which the database
|
|
is created will be used.
|
|
Any format database can be used on a machine with a different native
|
|
format,
|
|
although it is possible that the application will incur a performance
|
|
penalty for the run-time conversion.
|
|
.SH "EXTENDING DB
|
|
DB includes tools to simplify the development of application-specific
|
|
logging and recovery.
|
|
Specifically,
|
|
given a description of the information to be logged,
|
|
these tools will automatically create logging functions (functions that take
|
|
the values as parameters and construct a single record that is written to
|
|
the log), read functions (functions that read a log record and unmarshall the
|
|
values into a structure that maps onto the values you chose to log),
|
|
a print function (for debugging),
|
|
templates for the recovery functions,
|
|
and automatic dispatching to your recovery functions.
|
|
.SH "EXAMPLES
|
|
There are a number of examples included with the DB library distribution,
|
|
intended to demonstrate various ways of using the DB library.
|
|
.PP
|
|
Some applications require the use of formatted files to store data,
|
|
but do not require concurrent access and can cope with the loss of
|
|
data due to catastrophic failure.
|
|
Generally,
|
|
these applications create short-lived databases that are discarded or
|
|
recreated when the system fails.
|
|
Such applications need only use the DB access methods.
|
|
The DB access methods will use the memory pool subsystem,
|
|
but the application is unlikely to do so explicitly.
|
|
See the files
|
|
.IR examples/ex_access.c ,
|
|
.IR examples/ex_btrec.c ,
|
|
.I examples_cxx/AccessExample.cpp
|
|
and
|
|
.I java/src/com/sleepycat/examples/AccessExample.java
|
|
in the DB source distribution for C, C++, and Java language code examples of
|
|
how such applications might use the DB library.
|
|
.PP
|
|
Some applications require the use formatted files to store data,
|
|
but also need to use
|
|
.IR db_appinit (3)
|
|
(\c
|
|
.IR DbEnv::appinit (3))
|
|
for environment initialization.
|
|
See the files
|
|
.IR examples/ex_appinit.c ,
|
|
.I examples_cxx/AppinitExample.cpp
|
|
or
|
|
.I java/src/com/sleepycat/examples/AppinitExample.java
|
|
in the DB source distribution for C, C++ and Java language code examples of how
|
|
such an application might use the DB library.
|
|
.\".PP
|
|
.\"Applications that wish to transaction protect structures other than
|
|
.\"the DB access methods.
|
|
.\"See the file
|
|
.\".I examples/ex_trans.c
|
|
.\"in the DB source distribution for a C language code example of how such
|
|
.\"an application might use the DB library.
|
|
.PP
|
|
Some applications use the DB access methods,
|
|
but are also concerned about catastrophic failure,
|
|
and therefore need to transaction protect the underlying DB files.
|
|
See the files
|
|
.IR examples/ex_tpcb.c ,
|
|
.I examples_cxx/TpcbExample.cpp
|
|
or
|
|
.I java/src/com/sleepycat/examples/TpcbExample.java
|
|
in the DB source distribution for C, C++ and Java language code examples of how
|
|
such an application might use the DB library.
|
|
.PP
|
|
Some applications will benefit from the ability to buffer input files
|
|
other than the underlying
|
|
DB access method files.
|
|
See the files
|
|
.I examples/ex_mpool.c
|
|
or
|
|
.I examples_cxx/MpoolExample.cpp
|
|
in the DB source distribution for C and C++ language code examples of how
|
|
such an application might use the DB library.
|
|
.PP
|
|
Some applications need a general-purpose lock manager separate from
|
|
locking support for the DB access methods.
|
|
See the files
|
|
.IR examples/ex_lock.c ,
|
|
.I examples_cxx/LockExample.cpp
|
|
or
|
|
.I java/src/com/sleepycat/examples/LockExample.java
|
|
in the DB source distribution for C, C++ and Java language code examples of how
|
|
such an application might use the DB library.
|
|
.PP
|
|
Some applications will use the DB access methods in a threaded fashion,
|
|
including trickle flushing of the underlying buffer pool and deadlock
|
|
detection.
|
|
See the file
|
|
.I examples/ex_thread.c
|
|
in the DB source distribution for a C language code example of how
|
|
such an application might use the DB library.
|
|
Note that the Java API assumes a threaded environment and performs
|
|
all thread-specific initialization automatically.
|
|
.SH "COMPATIBILITY
|
|
The DB 2.0 library provides backward compatible interfaces for the
|
|
historic UNIX
|
|
.IR dbm (3),
|
|
.IR ndbm (3)
|
|
and
|
|
.IR hsearch (3)
|
|
interfaces.
|
|
See
|
|
.IR db_dbm (3)
|
|
and
|
|
.IR db_hsearch (3)
|
|
for further information on these interfaces.
|
|
It also provides a backward compatible interface for the historic DB 1.85
|
|
release.
|
|
.ft B
|
|
DB 2.0 does not provide database compatibility for any of the above
|
|
interfaces,
|
|
and existing databases must be converted manually.
|
|
.ft R
|
|
To convert existing databases from the DB 1.85 format to the DB 2.0 format,
|
|
review the
|
|
.IR db_dump185 (1)
|
|
and
|
|
.IR db_load (1)
|
|
manual pages.
|
|
.PP
|
|
The name space in DB 2.0 has been changed from that of previous DB versions,
|
|
notably version 1.85, for portability and consistency reasons.
|
|
The only name collisions in the two libraries are the names used by the
|
|
.IR dbm (3),
|
|
.IR ndbm (3),
|
|
.IR hsearch (3)
|
|
and the DB 1.85 compatibility interfaces.
|
|
To include both DB 1.85 and DB 2.0 in a single library,
|
|
remove the
|
|
.IR dbm (3),
|
|
.IR ndbm (3)
|
|
and
|
|
.IR hsearch (3)
|
|
interfaces from either of the two libraries,
|
|
and the DB 1.85 compatibility interface from the DB 2.0 library.
|
|
This can be done by editing the library Makefiles and reconfiguring
|
|
and rebuilding the DB 2.0 library.
|
|
Obviously, if you use the historic interfaces, you will get the version
|
|
in the library from which you did not remove it.
|
|
Similarly, you will not be able to access DB 2.0 files using the DB 1.85
|
|
compatibility interface, since you have removed that from the library
|
|
as well.
|
|
.PP
|
|
It is possible to simply relink applications written to the DB 1.85 interface
|
|
against the DB 2.0 library.
|
|
Recompilation of such applications is slightly more complex.
|
|
When the DB 2.0 library is installed,
|
|
it installs two include files,
|
|
.I db.h
|
|
and
|
|
.IR db_185.h .
|
|
The former file is likely to replace the DB 1.85 version's include file
|
|
which had the same name.
|
|
If this did not happen,
|
|
recompiling DB 1.85 applications to use the DB 2.0 library is simple:
|
|
recompile as done historically, and load against the DB 2.0 library
|
|
instead of the DB 1.85 library.
|
|
If,
|
|
however,
|
|
the DB 2.0 installation process has replaced the system's
|
|
.I db.h
|
|
include file, replace the application's include of
|
|
.I db.h
|
|
with inclusion of
|
|
.IR db_185.h ,
|
|
recompile as done historically,
|
|
and then load against the DB 2.0 library.
|
|
.PP
|
|
Applications written using the historic interfaces of the DB library should
|
|
not require significant effort to port to the DB 2.0 interfaces.
|
|
While the functionality has been greatly enhanced in DB 2.0,
|
|
the historic interface and functionality and is largely unchanged.
|
|
Reviewing the application's calls into the DB library and updating those
|
|
calls to the new names,
|
|
flags and return values should be sufficient.
|
|
.PP
|
|
While
|
|
loading applications that use the DB 1.85 interfaces against the DB 2.0
|
|
library,
|
|
or converting DB 1.85 function calls to DB 2.0 function calls will work,
|
|
reconsidering your application's interface to the DB database library in
|
|
light of the additional functionality in DB 2.0 is recommended,
|
|
as it is likely to result in enhanced application performance.
|
|
.SH "SEE ALSO: ADMINISTRATIVE AND OTHER UTILITIES
|
|
.\" make the line long for nroff.
|
|
.if n .ll 72
|
|
.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)
|
|
.SH "SEE ALSO: C API
|
|
.IR db_appinit (3),
|
|
.IR db_cursor (3),
|
|
.IR db_dbm (3),
|
|
.IR db_lock (3),
|
|
.IR db_log (3),
|
|
.IR db_mpool (3),
|
|
.IR db_open (3),
|
|
.IR db_txn (3)
|
|
.SH "SEE ALSO: C++ and Java API
|
|
.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),
|
|
.IR DbMpoolFile (3),
|
|
.IR Dbt (3),
|
|
.IR DbTxn (3),
|
|
.IR DbTxnMgr (3)
|
|
.SH "SEE ALSO: ADDITIONAL REFERENCES
|
|
.IR "LIBTP: Portable, Modular Transactions for UNIX" ,
|
|
Margo Seltzer, Michael Olson, USENIX proceedings, Winter 1992.
|