gecko-dev/db/man/man.roff/db_intro.3

.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.