зеркало из https://github.com/mozilla/gecko-dev.git
1908 строки
45 KiB
Groff
1908 строки
45 KiB
Groff
.ds TYPE CXX
|
|
.\"
|
|
.\" See the file LICENSE for redistribution information.
|
|
.\"
|
|
.\" Copyright (c) 1997, 1998
|
|
.\" Sleepycat Software. All rights reserved.
|
|
.\"
|
|
.\" @(#)DbEnv.sox 10.17 (Sleepycat) 5/1/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 DbEnv 3 "May 1, 1998"
|
|
.UC 7
|
|
.SH NAME
|
|
DbEnv \- Db initialization and environment options
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.ft B
|
|
.ie '\*[TYPE]'CXX'\{
|
|
#include <db_cxx.h>
|
|
|
|
DbEnv::DbEnv(const char *db_home, char *const *db_config, u_int32_t flags);
|
|
DbEnv::DbEnv();
|
|
DbEnv::~DbEnv();
|
|
|
|
int DbEnv::appinit(const char *db_home,
|
|
.ti +5
|
|
char *const *db_config, u_int32_t flags);
|
|
|
|
int DbEnv::get_lorder() const;
|
|
void DbEnv::set_lorder(int);
|
|
|
|
typedef void (*db_errcall_fcn)(const char *, char *);
|
|
db_errcall_fcn DbEnv::get_errcall() const;
|
|
void DbEnv::set_errcall(db_errcall_fcn);
|
|
|
|
FILE DbEnv::*get_errfile() const;
|
|
void DbEnv::set_errfile(FILE *);
|
|
|
|
const char DbEnv::*get_errpfx() const;
|
|
void DbEnv::set_errpfx(const char *);
|
|
|
|
int DbEnv::get_verbose() const;
|
|
void DbEnv::set_verbose(int);
|
|
|
|
char DbEnv::*get_home() const;
|
|
void DbEnv::set_home(char *);
|
|
|
|
char DbEnv::*get_log_dir() const;
|
|
void DbEnv::set_log_dir(char *);
|
|
|
|
char DbEnv::*get_tmp_dir() const;
|
|
void DbEnv::set_tmp_dir(char *);
|
|
|
|
char DbEnv::**get_data_dir() const;
|
|
void DbEnv::set_data_dir(char **);
|
|
|
|
DbLockTab DbEnv::*get_lk_info() const;
|
|
|
|
u_int8_t DbEnv::*get_lk_conflicts() const;
|
|
void DbEnv::set_lk_conflicts(u_int8_t *);
|
|
|
|
u_int32_t DbEnv::get_lk_modes() const;
|
|
void DbEnv::set_lk_modes(u_int32_t);
|
|
|
|
u_int32_t DbEnv::get_lk_max() const;
|
|
void DbEnv::set_lk_max(u_int32_t);
|
|
|
|
u_int32_t DbEnv::get_lk_detect() const;
|
|
void DbEnv::set_lk_detect(u_int32_t);
|
|
|
|
DbLog DbEnv::*get_lg_info() const;
|
|
|
|
u_int32_t DbEnv::get_lg_max() const;
|
|
void DbEnv::set_lg_max(u_int32_t);
|
|
|
|
DbMpool DbEnv::*get_mp_info() const;
|
|
|
|
size_t DbEnv::get_mp_mmapsize() const;
|
|
void DbEnv::set_mp_mmapsize(size_t);
|
|
|
|
size_t DbEnv::get_mp_size() const;
|
|
void DbEnv::set_mp_size(size_t);
|
|
|
|
DbTxnMgr DbEnv::*get_tx_info() const;
|
|
|
|
u_int32_t DbEnv::get_tx_max() const;
|
|
void DbEnv::set_tx_max(u_int32_t);
|
|
|
|
typedef int (*tx_recover_fcn)(DB_LOG *, DBT *, DB_LSN *, int, void *);
|
|
tx_recover_fcn DbEnv::get_tx_recover() const;
|
|
void DbEnv::set_tx_recover(tx_recover_fcn);
|
|
|
|
u_int32_t DbEnv::get_flags() const;
|
|
void DbEnv::set_flags(u_int32_t);
|
|
|
|
enum ErrorModel { Exception, ErrorReturn };
|
|
void DbEnv::set_error_model(ErrorModel);
|
|
ErrorModel DbEnv::get_error_model() const;
|
|
|
|
class ostream* DbEnv::get_error_stream() const;
|
|
void DbEnv::set_error_stream(class ostream*);
|
|
\}
|
|
.el\{\
|
|
import com.sleepycat.db.*;
|
|
|
|
public DbEnv(String homeDir, String[] db_config, int flags)
|
|
.ti +5
|
|
throws DbException;
|
|
|
|
public DbEnv();
|
|
|
|
public void appinit(String homeDir, String[] db_config, int flags)
|
|
.ti +5
|
|
throws DbException;
|
|
|
|
public void appexit()
|
|
.ti +5
|
|
throws DbException;
|
|
|
|
public int get_lorder();
|
|
public void set_lorder(int lorder);
|
|
|
|
public DbErrcall get_errcall();
|
|
public void set_errcall(DbErrcall errcall);
|
|
|
|
public String get_errpfx();
|
|
public void set_errpfx(String errpfx);
|
|
|
|
public int get_verbose();
|
|
public void set_verbose(int verbose);
|
|
|
|
public String get_home();
|
|
public void set_home(String home);
|
|
|
|
public String get_log_dir();
|
|
public void set_log_dir(String log_dir);
|
|
|
|
public String get_tmp_dir();
|
|
public void set_tmp_dir(String tmp_dir);
|
|
|
|
public DbLockTab get_lk_info();
|
|
|
|
public byte[][] get_lk_conflicts();
|
|
public void set_lk_conflicts(byte[][] lk_conflicts);
|
|
|
|
public int get_lk_modes();
|
|
public void set_lk_modes(int lk_modes);
|
|
|
|
public int get_lk_max();
|
|
public void set_lk_max(int lk_max);
|
|
|
|
public int get_lk_detect();
|
|
public void set_lk_detect(int lk_detect);
|
|
|
|
public DbLog get_lg_info();
|
|
|
|
public int get_lg_max();
|
|
public void set_lg_max(int lg_max);
|
|
|
|
public DbMpool get_mp_info();
|
|
|
|
public long get_mp_mmapsize();
|
|
public void set_mp_mmapsize(long mmapsize);
|
|
|
|
public long get_mp_size();
|
|
public void set_mp_size(long mp_size);
|
|
|
|
public DbTxnMgr get_tx_info();
|
|
|
|
public int get_tx_max();
|
|
public void set_tx_max(int tx_max);
|
|
|
|
public int get_flags();
|
|
public void set_flags(int flags);
|
|
|
|
public static int get_version_major();
|
|
public static int get_version_minor();
|
|
public static int get_version_patch();
|
|
public static String get_version_string();
|
|
public static String get_java_version_string();
|
|
|
|
public void set_error_stream(OutputStream s);
|
|
\}
|
|
.ft R
|
|
.fi
|
|
.SH DESCRIPTION
|
|
.Gn
|
|
.PP
|
|
The DbEnv class provides simple access to an underlying data structure,
|
|
whose elements can be examined or changed using the
|
|
.I set_
|
|
or
|
|
.I get_
|
|
methods. The remainder of the manual page sometimes
|
|
refers to these accesses using the underlying name, e.g., simply
|
|
.I lorder
|
|
instead of
|
|
.I get_lorder
|
|
and
|
|
.IR set_lorder .
|
|
The constructors set all elements of the underlying structure to zero.
|
|
The constructor with three arguments has the effect of calling
|
|
.I DbEnv::appinit
|
|
immediately to initialize the application with default parameters.
|
|
To delay the initialization, use the default constructor.
|
|
The various set_ methods can then be used to initialize the
|
|
DbEnv, and finally, a call to
|
|
.I DbEnv::appinit
|
|
should be made to initialize DB.
|
|
.PP
|
|
Once the DB environment has been initialized by a call to
|
|
.IR DbEnv::appinit ,
|
|
no set methods other than
|
|
.I set_errpfx
|
|
should be called.
|
|
.PP
|
|
.Fn appinit
|
|
The
|
|
.I appinit
|
|
method provides a simple way to initialize and configure the Db
|
|
environment.
|
|
It is not necessary that it be called,
|
|
but it provides a method of creating a consistent environment for
|
|
processes using one or more of the features of Db.
|
|
.PP
|
|
The
|
|
.I db_home
|
|
and
|
|
.I db_config
|
|
arguments to
|
|
.I appinit
|
|
are described in the section below entitled ``FILE NAMING''.
|
|
.PP
|
|
The
|
|
.I flags
|
|
argument specifies the subsystems that are initialized
|
|
and how the environment affects Db file naming,
|
|
among other things.
|
|
The
|
|
.I flags
|
|
value is specified by
|
|
.BR or 'ing
|
|
together one or more of the following values:
|
|
.TP 5
|
|
.Sj DB_CREATE
|
|
Cause subsystems to create any underlying files, as necessary.
|
|
(See
|
|
.IR Db (3),
|
|
.IR DbLockTab (3),
|
|
.IR DbLog (3),
|
|
.IR DbMpool (3)
|
|
and
|
|
.IR DbTxnMgr (3)
|
|
for more information.)
|
|
.TP 5
|
|
.Sj DB_INIT_LOCK
|
|
Initialize the lock subsystem; see
|
|
.IR DbLockTab (3).
|
|
This subsystem should be used when multiple processes or threads are
|
|
going to be reading and writing a Db database,
|
|
so that they do not interfere with each other.
|
|
If all threads are accessing the database(s) read-only, then locking
|
|
is unnecessary.
|
|
When the DB_INIT_LOCK flag is specified, it is usually necessary
|
|
to run the deadlock detector,
|
|
.IR db_deadlock (1),
|
|
as well.
|
|
.TP 5
|
|
.Sj DB_INIT_LOG
|
|
Initialize the log subsystem; see
|
|
.IR DbLog (3).
|
|
This subsystem is used when recovery from application or system
|
|
failure is important.
|
|
.TP 5
|
|
.Sj DB_INIT_MPOOL
|
|
Initialize the mpool subsystem; see
|
|
.IR DbMpool (3).
|
|
This subsystem is used whenever the application is using the Db access
|
|
methods for any purpose.
|
|
.TP 5
|
|
.Sj DB_INIT_TXN
|
|
Initialize the transaction subsystem; see
|
|
.IR DbTxn (3).
|
|
This subsystem is used when atomicity of multiple operations
|
|
and recovery are important.
|
|
The DB_INIT_TXN flag implies the DB_INIT_LOG flag.
|
|
.TP 5
|
|
.Sj DB_MPOOL_PRIVATE
|
|
Create a private memory pool (see
|
|
.IR DbMpool (3)
|
|
for further information).
|
|
Ignored unless DB_INIT_MPOOL is also specified.
|
|
.TP 5
|
|
.Sj DB_NOMMAP
|
|
Do not map any files within this environment (see
|
|
.IR DbMpool (3)
|
|
for further information).
|
|
Ignored unless DB_INIT_MPOOL is also specified.
|
|
.TP 5
|
|
.Sj DB_RECOVER
|
|
Run normal recovery on this environment before opening it for normal use.
|
|
If this flag is set, the DB_CREATE flag must also be set since the regions
|
|
will be removed and recreated.
|
|
.sp
|
|
The
|
|
.I DbEnv::appinit
|
|
function returns successfully if DB_RECOVER is specified and no log files
|
|
exist, so it is necessary to ensure all necessary log files are present
|
|
before running recovery.
|
|
For further information, consult the man page for
|
|
.IR db_archive (1)
|
|
and
|
|
.IR db_recover (1).
|
|
.TP 5
|
|
.Sj DB_RECOVER_FATAL
|
|
Run catastrophic recovery on this environment before opening it for normal use.
|
|
If this flag is set, the DB_CREATE flag must also be set since the regions
|
|
will be removed and recreated.
|
|
.sp
|
|
The
|
|
.I DbEnv::appinit
|
|
function returns successfully if DB_RECOVER is specified and no log files
|
|
exist, so it is necessary to ensure all necessary log files are present
|
|
before running recovery.
|
|
For further information, consult the man page for
|
|
.IR db_archive (1)
|
|
and
|
|
.IR db_recover (1).
|
|
.TP 5
|
|
.Sj DB_THREAD
|
|
Ensure that handles returned by the Db subsystems are useable by multiple
|
|
threads within a single process, i.e., that the system is ``free-threaded''.
|
|
(See
|
|
.IR DbLockTab (3),
|
|
.IR DbLog (3),
|
|
.IR DbMpool (3),
|
|
.IR Db::open (3)
|
|
and
|
|
.IR DbTxn (3)
|
|
for more information.)
|
|
.if '\*[TYPE]'JAVA'\{\
|
|
.sp
|
|
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.
|
|
\}
|
|
.TP 5
|
|
.Sj DB_TXN_NOSYNC
|
|
On transaction commit, do not synchronously flush the log (see
|
|
.IR DbTxn (3)
|
|
for further information).
|
|
Ignored unless DB_INIT_TXN is also specified.
|
|
.TP 5
|
|
.Sj DB_USE_ENVIRON
|
|
The Db process' environment may be permitted to specify information to
|
|
be used when naming files (see the section entitled ``FILE NAMING'' below).
|
|
As permitting users to specify which files are used can create security
|
|
problems,
|
|
environment information will be used in file naming for all users only
|
|
if the DB_USE_ENVIRON flag is set.
|
|
.TP 5
|
|
.Sj DB_USE_ENVIRON_ROOT
|
|
The Db process' environment may be permitted to specify information to
|
|
be used when naming files (see the section entitled ``FILE NAMING'' below).
|
|
As permitting users to specify which files are used can create security
|
|
problems,
|
|
if the DB_USE_ENVIRON_ROOT flag is set,
|
|
environment information will be used for file naming only
|
|
for users with a user-ID matching that of the superuser (specifically,
|
|
users for whom the
|
|
.I getuid
|
|
system call returns the user-ID 0).
|
|
.PP
|
|
The Db environment is configured
|
|
.En "appinit" "appexit"
|
|
.ie '\*[TYPE]'CXX'\{\
|
|
.TP 5
|
|
void (*db_errcall)(char *db_errpfx, char *buffer);\}
|
|
.el\{\
|
|
.TP 5
|
|
DbErrcall db_errcall;\}
|
|
When an error occurs in the DB package, an
|
|
.I errno
|
|
value is returned by the method.
|
|
In some cases, however, the
|
|
.I errno
|
|
value may be insufficient to completely describe the cause of the error.
|
|
.IP
|
|
If
|
|
.I db_errcall
|
|
.ie '\*[TYPE]'CXX'\{\
|
|
is non-NULL,
|
|
it may be called with additional error information.
|
|
The
|
|
.I db_errpfx
|
|
argument is the current environment's
|
|
.I db_errpfx
|
|
field.
|
|
The
|
|
.I buffer
|
|
argument contains a nul-terminated string with the additional information.
|
|
\}
|
|
.el\{\
|
|
is not null,
|
|
db_errcall.errcall() may be called with additional error information.
|
|
This method takes two arguments. The
|
|
.I prefix
|
|
argument is the current environment's
|
|
.I db_errpfx
|
|
field.
|
|
The
|
|
.I buffer
|
|
argument is a string with the additional information.
|
|
\}
|
|
.sp
|
|
This error logging facility should not be required for normal operation,
|
|
but may be useful in debugging applications.
|
|
.if '\*[TYPE]'CXX'\{\
|
|
.TP 5
|
|
FILE *db_errfile;
|
|
The
|
|
.I db_errfile
|
|
field behaves similarly to the
|
|
.I db_errcall
|
|
field,
|
|
except that the error message is written to the file stream represented by
|
|
.IR db_errfile .
|
|
.sp
|
|
If
|
|
.I db_errpfx
|
|
is non-NULL,
|
|
the message will be preceded by the string referenced by
|
|
.IR db_errpfx ,
|
|
a colon (``:'') and a space.
|
|
The message will be followed by a newline character.
|
|
\}
|
|
.ie '\*[TYPE]'CXX'\{\
|
|
.TP 5
|
|
const char *db_errpfx;\}
|
|
.el\{\
|
|
.TP 5
|
|
String db_errpfx;\}
|
|
A prefix to prepend to error messages.
|
|
Because Db does not copy the memory referenced by the
|
|
.I db_errpfx
|
|
field,
|
|
the application may modify the error message prefix at
|
|
any time.
|
|
.ie '\*[TYPE]'CXX'\{\
|
|
.TP 5
|
|
ostream* error_stream;
|
|
The error_stream functions like the error file, allowing errors
|
|
to be redirected to a C++ error stream. It is unwise to use
|
|
both error_stream with nonzero values of either errcall or errfile.
|
|
\}
|
|
.el\{\
|
|
.TP 5
|
|
java.io.OutputStream error_stream;
|
|
The
|
|
.I error_stream
|
|
field behaves similarly to the
|
|
.I db_errcall
|
|
field,
|
|
except that the error message is written to the OutputStream represented by
|
|
.IR error_stream .
|
|
.sp
|
|
If
|
|
.I db_errpfx
|
|
is not null,
|
|
the message will be preceded by the string referenced by
|
|
.IR db_errpfx ,
|
|
a colon (``:'') and a space.
|
|
The message will be followed by a newline character.
|
|
\}
|
|
.TP 5
|
|
int db_verbose;
|
|
Include informational and debugging messages as well as error messages in the
|
|
.I db_errcall
|
|
and
|
|
.I db_errfile
|
|
output.
|
|
.PP
|
|
Each of the open functions that
|
|
.I appinit
|
|
may call (\c
|
|
.IR DbLockTab::open ,
|
|
.IR DbLog::open ,
|
|
.I DbMpool::open
|
|
and
|
|
.IR DbTxnMgr::open )
|
|
is called as follows,
|
|
where the DB_CREATE flag is optional:
|
|
.ie '\*[TYPE]'CXX'\{\
|
|
.sp
|
|
.ti +5
|
|
XXX::open(NULL, DB_CREATE,
|
|
.ti +8
|
|
S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP, dbenv)
|
|
\}
|
|
.el\{\
|
|
.sp
|
|
.ti +5
|
|
XXX::open(null, Db.DB_CREATE, 0660, dbenv)
|
|
\}
|
|
.PP
|
|
This call will cause each subsystem to construct pathnames as described in
|
|
the section on ``FILE NAMING''.
|
|
The subsystem has permission to read and write underlying files as necessary,
|
|
and optionally to create files.
|
|
(All created files will be created readable and writeable by the owner and
|
|
the group.
|
|
The group ownership of created files is based on the system and directory
|
|
defaults, and is not further specified by Db.)
|
|
.PP
|
|
In addition, the
|
|
.I dbenv
|
|
argument is passed to the open functions of any subsystems initialized by
|
|
.IR appinit .
|
|
For this reason the fields of the DbEnv object relevant to the
|
|
subsystems being initialized must themselves be initialized before
|
|
.I appinit
|
|
is called.
|
|
See the manual page for each subsystem for a list of these fields and
|
|
their uses.
|
|
.PP
|
|
The return value from each of these calls is placed in the appropriate
|
|
field of the DbEnv object:
|
|
.ie '\*[TYPE]'CXX'\{\
|
|
.TP 5
|
|
DbLockTab *lk_info;
|
|
\}
|
|
.el\{\
|
|
.TP 5
|
|
DbLockTab lk_info;
|
|
\}
|
|
The return value of the
|
|
.IR DbLockTab::open (3)
|
|
call.
|
|
.ie '\*[TYPE]'CXX'\{\
|
|
.TP 5
|
|
DbLog *lg_info;
|
|
\}
|
|
.el\{\
|
|
.TP 5
|
|
DbLog lg_info;
|
|
\}
|
|
The return value of the
|
|
.IR DbLog::open (3)
|
|
call.
|
|
.ie '\*[TYPE]'CXX'\{\
|
|
.TP 5
|
|
DbMpool *mp_info;
|
|
\}
|
|
.el\{\
|
|
.TP 5
|
|
DbMpool mp_info;
|
|
\}
|
|
The return value of the
|
|
.IR DbMpool::open (3)
|
|
call.
|
|
.ie '\*[TYPE]'CXX'\{\
|
|
.TP 5
|
|
DbTxnMgr *tx_info;
|
|
\}
|
|
.el\{\
|
|
.TP 5
|
|
DbTxnMgr tx_info;
|
|
\}
|
|
The return value of the
|
|
.IR DbTxnMgr::open (3)
|
|
call.
|
|
.PP
|
|
In general,
|
|
these fields are not directly used by applications; subsystems of Db that
|
|
use these fields will simply reference them using the DbEnv argument passed
|
|
to the subsystem.
|
|
.PP
|
|
For example,
|
|
an application using the Db hash access method functions to access a
|
|
database will first call
|
|
.I Db::open
|
|
passing it the DbEnv argument filled in by the initial call to
|
|
.IR appinit .
|
|
Then,
|
|
all future calls to the hash access method functions for that database will
|
|
automatically use the underlying shared memory buffer pool that was specified
|
|
by the
|
|
.I mp_info
|
|
field of that DbEnv argument.
|
|
.PP
|
|
The single exception to this rule is the
|
|
.I tx_info
|
|
field,
|
|
which applications must explicitly specify to the
|
|
.IR DbTxnMgr::begin ,
|
|
.I DbTxnMgr::checkpoint
|
|
and
|
|
.I DbTxnMgr::close
|
|
functions.
|
|
.PP
|
|
The
|
|
.I error_model
|
|
field of DbEnv allows the user to configure the way
|
|
errors are treated in DB. It can be changed at
|
|
any time (e.g., after the call to
|
|
.IR DbEnv::appinit ).
|
|
The error model is described in
|
|
.IR DbException (3).
|
|
.SH "FILE NAMING"
|
|
The most important task of
|
|
.I appinit
|
|
is to structure file naming within Db.
|
|
.PP
|
|
Each of the locking, logging,
|
|
memory pool and transaction subsystems of Db require shared memory regions,
|
|
backed by the filesystem.
|
|
Further,
|
|
cooperating applications (or multiple invocations of the same application)
|
|
must agree on the location of the shared memory regions and other files used
|
|
by the Db subsystems,
|
|
the log files used by the logging subsystem,
|
|
and, of course, the data files.
|
|
.PP
|
|
Although it is possible to specify full pathnames to all Db functions,
|
|
this is cumbersome and requires that applications be recompiled when
|
|
database files are moved.
|
|
The
|
|
.I appinit
|
|
method makes it possible to place database files in a single directory,
|
|
or in multiple directories,
|
|
grouped by their method within the database.
|
|
.PP
|
|
Applications are normally expected to specify a single directory home for
|
|
their database.
|
|
This can be done easily in the call to
|
|
.I appinit
|
|
by specifying a value for the
|
|
.I db_home
|
|
argument.
|
|
There are more complex configurations where it may be desirable to override
|
|
.I db_home
|
|
or provide supplementary path information.
|
|
.PP
|
|
The following describes the possible ways in which file naming information
|
|
may be specified to the Db library.
|
|
The specific circumstances and order in which these ways are applied are
|
|
described in a subsequent paragraph.
|
|
.TP 5
|
|
.I db_home
|
|
If the
|
|
.I db_home
|
|
argument to
|
|
.I appinit
|
|
is non-NULL,
|
|
its value may be used as the database home,
|
|
and files named relative to its path.
|
|
.TP 5
|
|
DB_HOME
|
|
If the DB_HOME environment variable is set when
|
|
.I appinit
|
|
is called,
|
|
its value may be used as the database home,
|
|
and files named relative to its path.
|
|
.TP 5
|
|
.I db_config
|
|
The
|
|
.I db_config
|
|
argument to
|
|
.I appinit
|
|
may be used to specify an array of character strings of the
|
|
format ``NAME VALUE'',
|
|
that specify file name information for the process' Db environment.
|
|
The whitespace delimiting the two parts of the entry may be one or
|
|
more <space> or <tab> characters.
|
|
(Leading or trailing <space> and <tab> characters are discarded.)
|
|
Each entry must specify both the NAME and the VALUE of the pair.
|
|
All entries with unrecognized NAME values will be ignored.
|
|
The
|
|
.I db_config
|
|
array must be NULL terminated.
|
|
.TP 5
|
|
DB_CONFIG
|
|
The same information specified to the
|
|
.I db_config
|
|
argument to
|
|
.I appinit
|
|
may be specified using a configuration file.
|
|
If a database home directory has been specified (either by the
|
|
application specifying a non-NULL
|
|
.I db_home
|
|
argument to
|
|
.IR appinit ,
|
|
or by the application setting the DB_USE_ENVIRON or DB_USE_ENVIRON_ROOT
|
|
flags and the DB_HOME environment variable being set),
|
|
any file named ``DB_CONFIG'' in the database home directory will be read
|
|
for lines of the format ``NAME VALUE''.
|
|
The whitespace delimiting the two parts of the line may be one or more
|
|
<space> or <tab> characters.
|
|
(Leading or trailing <space> and <tab> characters are discarded.)
|
|
All empty lines or lines whose first non-whitespace character is a
|
|
hash character (``#'') will be ignored.
|
|
Each line must specify both the NAME and the VALUE of the pair.
|
|
All lines with unrecognized NAME values will be ignored.
|
|
.PP
|
|
The following ``NAME VALUE'' pairs in the
|
|
.I db_config
|
|
argument and the DB_CONFIG file are currently supported by Db.
|
|
.TP 5
|
|
DB_DATA_DIR
|
|
The path of a directory to be used as the location of the access method
|
|
data files, e.g.,
|
|
paths specified to the
|
|
.IR Db::open (3)
|
|
method will be relative to this path.
|
|
.IP
|
|
The DB_DATA_DIR paths are additive,
|
|
and specifying more than one will result in each specified directory being
|
|
searched for database data files.
|
|
If multiple paths are specified,
|
|
created data files will always be created in the
|
|
.B first
|
|
directory specified.
|
|
.TP 5
|
|
DB_LOG_DIR
|
|
The path of a directory to be used as the location of logging files, e.g.,
|
|
files created by the
|
|
.IR DbLog (3)
|
|
subsystem will be relative to this directory.
|
|
If specified,
|
|
this is the directory name that will be passed to
|
|
.IR DbLog::open (3).
|
|
.\".TP 5
|
|
.\"DB_SUPPORT_DIR
|
|
.\"The path of a directory to be used as the location for shared memory
|
|
.\"segments, e.g., the supporting shared memory region for the shared
|
|
.\"memory buffer pool will be created in this directory.
|
|
.TP 5
|
|
DB_TMP_DIR
|
|
The path of a directory to be used as the location of temporary files, e.g.,
|
|
files created to back in-memory access method databases will be created
|
|
relative to this path.
|
|
Note, these temporary files can potentially be quite large, depending on the
|
|
size of the database.
|
|
.sp
|
|
If DB_TMP_DIR is not specified,
|
|
the following environment variables are checked in order:
|
|
``TMPDIR'', ``TEMP'', ``TMP'' and ``TempFolder''.
|
|
If one of them is set,
|
|
temporary files are created relative to the directory it specifies.
|
|
.sp
|
|
If DB_TMP_DIR is not specified and none of the above environment variables
|
|
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
|
|
The following describes the specific circumstances and order in which the
|
|
different ways of specifying file naming information are applied.
|
|
Specifically,
|
|
Db file name processing proceeds sequentially through the following steps:
|
|
.TP 5
|
|
``/''
|
|
If any file name specified to any Db method begins with a leading slash,
|
|
that file name is used without modification by Db.
|
|
.TP 5
|
|
DB_CONFIG
|
|
If a relevant configuration string (e.g., DB_DATA_DIR),
|
|
is specified in the DB_CONFIG configuration file,
|
|
the VALUE from the ``NAME VALUE'' pair is prepended to the current file name.
|
|
If the resulting file name begins with a leading slash,
|
|
the file name is used without further modification by Db.
|
|
.sp
|
|
The DB_CONFIG configuration file is intended to permit systems to customize
|
|
file location for a database independent of applications using that database.
|
|
For example,
|
|
a database administrator can move the database log and data files to a
|
|
different location without application recompilation.
|
|
.TP 5
|
|
.I db_config
|
|
If a relevant configuration string (e.g., DB_DATA_DIR),
|
|
is specified in the
|
|
.I db_config
|
|
argument and is not specified in the DB_CONFIG file,
|
|
the VALUE from the ``NAME VALUE'' pair is prepended to the current file name.
|
|
If the resulting file name begins with a leading slash,
|
|
the file name is used without further modification by Db.
|
|
.sp
|
|
The
|
|
.I db_config
|
|
argument is intended to permit applications to customize file location
|
|
for a database.
|
|
For example,
|
|
an application writer can place data files and log files in different
|
|
directories,
|
|
or instantiate a new log directory each time the application runs.
|
|
.TP 5
|
|
DB_HOME
|
|
If the DB_HOME environment variable was set,
|
|
(and the application has set the appropriate DB_USE_ENVIRON or
|
|
DB_USE_ENVIRON_ROOT environment variable),
|
|
its value is prepended to the current file name.
|
|
If the resulting file name begins with a leading slash,
|
|
the file name is used without further modification by Db.
|
|
.sp
|
|
The DB_HOME environment variable is intended to permit users and system
|
|
administrators to override application and installation defaults, e.g.,
|
|
.sp
|
|
.ti +5
|
|
env DB_HOME=/database/my_home application
|
|
.sp
|
|
Alternatively,
|
|
application writers are encouraged to support the
|
|
.B \-h
|
|
option found in the supporting Db utilities to let users specify a database
|
|
home.
|
|
.TP 5
|
|
.I db_home
|
|
If the application specified a non-NULL
|
|
.I db_home
|
|
argument to
|
|
.I appinit
|
|
(and the database home was not already specified using the DB_HOME
|
|
environment variable) its value is prepended to the current file name.
|
|
If the resulting file name begins with a leading slash,
|
|
the file name is used without further modification by Db.
|
|
.TP 5
|
|
(nothing)
|
|
Finally, all file names are interpreted relative to the current working
|
|
directory of the process.
|
|
.PP
|
|
The common model for a Db environment is one where only the DB_HOME
|
|
environment variable,
|
|
or the
|
|
.I db_home
|
|
argument, is specified.
|
|
In this case,
|
|
all data files will be presumed to be relative to that directory,
|
|
and all files created by the Db subsystems will be created in that
|
|
directory.
|
|
.PP
|
|
The more complex model for a transaction environment might be one where
|
|
a database home is specified,
|
|
using either the DB_HOME environment variable or the
|
|
.I db_home
|
|
argument to
|
|
.IR appinit ,
|
|
and then DB_DATA_DIR and DB_LOG_DIR are set to the relative path names
|
|
of directories underneath the home directory using the
|
|
.I db_config
|
|
argument to
|
|
.I appinit
|
|
or the DB_CONFIG file.
|
|
.SH EXAMPLES
|
|
Store all files in the directory
|
|
.IR /a/database :
|
|
.PP
|
|
.RS
|
|
.nf
|
|
.ie '\*[TYPE]'CXX'\{\
|
|
DbEnv::appinit("/a/database", NULL, ...);
|
|
\}
|
|
.el\{\
|
|
DbEnv::appinit("/a/database", null, ...);
|
|
\}
|
|
.fi
|
|
.RE
|
|
.PP
|
|
Create temporary backing files in
|
|
.IR /b/temporary ,
|
|
and all other files in
|
|
.IR /a/database :
|
|
.PP
|
|
.RS
|
|
.nf
|
|
.ie '\*[TYPE]'CXX'\{\
|
|
char *config[] = {
|
|
"DB_TMP_DIR /b/temporary",
|
|
NULL
|
|
};
|
|
|
|
DbEnv::appinit("/a/database", config, ...);
|
|
\}
|
|
.el\{\
|
|
String[] config = new String[1];
|
|
config[0] = "DB_TMP_DIR /b/temporary";
|
|
|
|
DbEnv::appinit("/a/database", config, ...);
|
|
\}
|
|
.fi
|
|
.RE
|
|
.PP
|
|
Store data files in
|
|
.IR /a/database/datadir ,
|
|
log files in
|
|
.IR /a/database/logdir ,
|
|
and all other files in the directory
|
|
.IR /a/database :
|
|
.PP
|
|
.RS
|
|
.nf
|
|
.ie '\*[TYPE]'CXX'\{\
|
|
char *config[] = {
|
|
"DB_DATA_DIR datadir",
|
|
"DB_LOG_DIR logdir",
|
|
NULL
|
|
};
|
|
|
|
DbEnv::appinit("/a/database", config, ...);
|
|
\}
|
|
.el\{\
|
|
String[] config = new String[2];
|
|
config[0] = "DB_DATA_DIR datadir";
|
|
config[1] = "DB_LOG_DIR logdir",
|
|
|
|
DbEnv::appinit("/a/database", config, ...);
|
|
\}
|
|
.fi
|
|
.RE
|
|
.PP
|
|
Store data files in
|
|
.I /a/database/data1
|
|
and
|
|
.IR /b/data2 ,
|
|
and all other files in the directory
|
|
.IR /a/database .
|
|
Any data files that are created will be created in
|
|
.IR /b/data2 :
|
|
.PP
|
|
.RS
|
|
.nf
|
|
.ie '\*[TYPE]'CXX'\{\
|
|
char *config[] = {
|
|
"DB_DATA_DIR /b/data2",
|
|
"DB_DATA_DIR data1",
|
|
NULL
|
|
};
|
|
|
|
DbEnv::appinit("/a/database", config, ...);
|
|
\}
|
|
.el\{\
|
|
String[] config = new String[2];
|
|
config[0] = "DB_DATA_DIR /b/data2";
|
|
config[1] = "DB_DATA_DIR data1";
|
|
|
|
DbEnv::appinit("/a/database", config, ...);
|
|
\}
|
|
.fi
|
|
.RE
|
|
.PP
|
|
.ie '\*[TYPE]'CXX'\{\
|
|
See the file
|
|
.I examples_cxx/AppinitExample.cpp
|
|
in the Db source distribution for a C++ language code example of how an
|
|
\}
|
|
.el\{\
|
|
See the file
|
|
.I java/src/com/sleepycat/examples/AppinitExample.java
|
|
in the Db source distribution for a Java language code example of how an
|
|
\}
|
|
application might use
|
|
.I appinit
|
|
to configure its Db environment.
|
|
.SH ERRORS
|
|
.Ek
|
|
.PP
|
|
.Ee appinit
|
|
.na
|
|
.Nh
|
|
Db::close(3),
|
|
DbEnv::appexit(3),
|
|
DbLock::unlink(3),
|
|
DbLockTab::open(3),
|
|
DbLog::compare(3),
|
|
DbLog::get(3),
|
|
DbLog::open(3),
|
|
DbLog::unlink(3),
|
|
DbMpool::open(3),
|
|
DbMpool::unlink(3),
|
|
DbTxnMgr::checkpoint(3),
|
|
DbTxnMgr::open(3),
|
|
DbTxnMgr::unlink(3),
|
|
calloc(3),
|
|
fclose(3),
|
|
fcntl(2),
|
|
fflush(3),
|
|
fgets(3),
|
|
fopen(3),
|
|
malloc(3),
|
|
memcpy(3),
|
|
memset(3),
|
|
realloc(3),
|
|
stat(2),
|
|
strchr(3),
|
|
strcmp(3),
|
|
strcpy(3),
|
|
strdup(3),
|
|
strerror(3),
|
|
strlen(3),
|
|
strsep(3),
|
|
and
|
|
time(3).
|
|
.Hy
|
|
.ad
|
|
.PP
|
|
.Ec appinit
|
|
.TP 5
|
|
.Ei
|
|
.sp
|
|
.Et
|
|
.sp
|
|
The DB_RECOVER or DB_RECOVER_FATAL flag was specified, and no
|
|
log files were found.
|
|
.sp
|
|
The DB_HOME or TMPDIR environment variables were set but empty.
|
|
.sp
|
|
An incorrectly formatted ``NAME VALUE'' entry or line was found.
|
|
.TP 5
|
|
[ENOSPC]
|
|
HP-UX only: a previously created Db environment for this process still
|
|
exists.
|
|
.PP
|
|
.Ee DbEnv::appexit
|
|
.na
|
|
.Nh
|
|
DbLockTab::close(3),
|
|
DbLog::close(3),
|
|
DbMpool::close(3),
|
|
and
|
|
DbTxnMgr::close(3).
|
|
.Hy
|
|
.ad
|
|
.SH "BUGS"
|
|
Due to the constraints of the PA-RISC memory architecture,
|
|
HP-UX does not allow a process to map a file into its address space
|
|
multiple times.
|
|
For this reason,
|
|
each DB environment may be opened only once by a process on HP-UX,
|
|
i.e., calls to
|
|
.I appinit
|
|
will fail if the specified Db environment has been opened and not
|
|
subsequently closed.
|
|
.PP
|
|
On Windows/95, files that are opened by multiple processes do not share
|
|
data correctly. To tell Berkeley DB to use the paging file to share
|
|
memory among processes, use the DB_REGION_NAME flag of the
|
|
.I db_value_set
|
|
function.
|
|
Obviously, you do not need to do this if only a single process will be
|
|
accessing database files.
|
|
.SH "SEE ALSO"
|
|
.Sa
|