зеркало из https://github.com/mozilla/gecko-dev.git
1419 строки
32 KiB
Groff
1419 строки
32 KiB
Groff
.ds TYPE C
|
|
.\"
|
|
.\" See the file LICENSE for redistribution information.
|
|
.\"
|
|
.\" Copyright (c) 1997, 1998
|
|
.\" Sleepycat Software. All rights reserved.
|
|
.\"
|
|
.\" @(#)db_internal.so 10.19 (Sleepycat) 5/10/98
|
|
.\"
|
|
.\"
|
|
.\" See the file LICENSE for redistribution information.
|
|
.\"
|
|
.\" Copyright (c) 1997, 1998
|
|
.\" Sleepycat Software. All rights reserved.
|
|
.\"
|
|
.\" @(#)macros.so 10.45 (Sleepycat) 5/4/98
|
|
.\"
|
|
.\" We don't want hyphenation for any HTML documents.
|
|
.ie '\*[HTML]'YES'\{\
|
|
.nh
|
|
\}
|
|
.el\{\
|
|
.ds Hy
|
|
.hy
|
|
..
|
|
.ds Nh
|
|
.nh
|
|
..
|
|
\}
|
|
.\" The alternative text macro
|
|
.\" This macro takes two arguments:
|
|
.\" + the text produced if this is a "C" manpage
|
|
.\" + the text produced if this is a "CXX" or "JAVA" manpage
|
|
.\"
|
|
.de Al
|
|
.ie '\*[TYPE]'C'\{\\$1
|
|
\}
|
|
.el\{\\$2
|
|
\}
|
|
..
|
|
.\" Scoped name macro.
|
|
.\" Produces a_b, a::b, a.b depending on language
|
|
.\" This macro takes two arguments:
|
|
.\" + the class or prefix (without underscore)
|
|
.\" + the name within the class or following the prefix
|
|
.de Sc
|
|
.ie '\*[TYPE]'C'\{\\$1_\\$2
|
|
\}
|
|
.el\{\
|
|
.ie '\*[TYPE]'CXX'\{\\$1::\\$2
|
|
\}
|
|
.el\{\\$1.\\$2
|
|
\}
|
|
\}
|
|
..
|
|
.\" Scoped name for Java.
|
|
.\" Produces Db.b, for Java, otherwise just b. This macro is used for
|
|
.\" constants that must be scoped in Java, but are global otherwise.
|
|
.\" This macro takes two arguments:
|
|
.\" + the class
|
|
.\" + the name within the class or following the prefix
|
|
.de Sj
|
|
.ie '\*[TYPE]'JAVA'\{\
|
|
.TP 5
|
|
Db.\\$1\}
|
|
.el\{\
|
|
.TP 5
|
|
\\$1\}
|
|
..
|
|
.\" The general information text macro.
|
|
.de Gn
|
|
.ie '\*[TYPE]'C'\{The DB library is a family of groups of functions that provides a modular
|
|
programming interface to transactions and record-oriented file access.
|
|
The library includes support for transactions, locking, logging and file
|
|
page caching, as well as various indexed access methods.
|
|
Many of the functional groups (e.g., the file page caching functions)
|
|
are useful independent of the other DB functions,
|
|
although some functional groups are explicitly based on other functional
|
|
groups (e.g., transactions and logging).
|
|
\}
|
|
.el\{The DB library is a family of classes that provides a modular
|
|
programming interface to transactions and record-oriented file access.
|
|
The library includes support for transactions, locking, logging and file
|
|
page caching, as well as various indexed access methods.
|
|
Many of the classes (e.g., the file page caching class)
|
|
are useful independent of the other DB classes,
|
|
although some classes are explicitly based on other classes
|
|
(e.g., transactions and logging).
|
|
\}
|
|
For a general description of the DB package, see
|
|
.IR db_intro (3).
|
|
..
|
|
.\" The library error macro, the local error macro.
|
|
.\" These macros take one argument:
|
|
.\" + the function name.
|
|
.de Ee
|
|
The
|
|
.I \\$1
|
|
.ie '\*[TYPE]'C'\{function may fail and return
|
|
.I errno
|
|
\}
|
|
.el\{method may fail and throw a
|
|
.IR DbException (3)
|
|
.if '\*[TYPE]'CXX'\{
|
|
or return
|
|
.I errno
|
|
\}
|
|
\}
|
|
for any of the errors specified for the following DB and library functions:
|
|
..
|
|
.de Ec
|
|
In addition, the
|
|
.I \\$1
|
|
.ie '\*[TYPE]'C'\{function may fail and return
|
|
.I errno
|
|
\}
|
|
.el\{method may fail and throw a
|
|
.IR DbException (3)
|
|
.ie '\*[TYPE]'CXX'\{or return
|
|
.I errno
|
|
\}
|
|
.el\{encapsulating an
|
|
.I errno
|
|
\}
|
|
\}
|
|
for the following conditions:
|
|
..
|
|
.de Ea
|
|
[EAGAIN]
|
|
A lock was unavailable.
|
|
..
|
|
.de Eb
|
|
[EBUSY]
|
|
The shared memory region was in use and the force flag was not set.
|
|
..
|
|
.de Em
|
|
[EAGAIN]
|
|
The shared memory region was locked and (repeatedly) unavailable.
|
|
..
|
|
.de Ei
|
|
[EINVAL]
|
|
An invalid flag value or parameter was specified.
|
|
..
|
|
.de Es
|
|
[EACCES]
|
|
An attempt was made to modify a read-only database.
|
|
..
|
|
.de Et
|
|
The DB_THREAD flag was specified and spinlocks are not implemented for
|
|
this architecture.
|
|
..
|
|
.de Ep
|
|
[EPERM]
|
|
Database corruption was detected.
|
|
All subsequent database calls (other than
|
|
.ie '\*[TYPE]'C'\{\
|
|
.IR DB->close )
|
|
\}
|
|
.el\{\
|
|
.IR Db::close )
|
|
\}
|
|
will return EPERM.
|
|
..
|
|
.de Ek
|
|
.if '\*[TYPE]'CXX'\{\
|
|
Methods marked as returning
|
|
.I errno
|
|
will, by default, throw an exception that encapsulates the error information.
|
|
The default error behavior can be changed, see
|
|
.IR DbException (3).
|
|
\}
|
|
..
|
|
.\" The SEE ALSO text macro
|
|
.de Sa
|
|
.\" make the line long for nroff.
|
|
.if n .ll 72
|
|
.nh
|
|
.na
|
|
.IR db_archive (1),
|
|
.IR db_checkpoint (1),
|
|
.IR db_deadlock (1),
|
|
.IR db_dump (1),
|
|
.IR db_load (1),
|
|
.IR db_recover (1),
|
|
.IR db_stat (1),
|
|
.IR db_intro (3),
|
|
.ie '\*[TYPE]'C'\{\
|
|
.IR db_appinit (3),
|
|
.IR db_cursor (3),
|
|
.IR db_dbm (3),
|
|
.IR db_internal (3),
|
|
.IR db_lock (3),
|
|
.IR db_log (3),
|
|
.IR db_mpool (3),
|
|
.IR db_open (3),
|
|
.IR db_thread (3),
|
|
.IR db_txn (3)
|
|
\}
|
|
.el\{\
|
|
.IR db_internal (3),
|
|
.IR db_thread (3),
|
|
.IR Db (3),
|
|
.IR Dbc (3),
|
|
.IR DbEnv (3),
|
|
.IR DbException (3),
|
|
.IR DbInfo (3),
|
|
.IR DbLock (3),
|
|
.IR DbLockTab (3),
|
|
.IR DbLog (3),
|
|
.IR DbLsn (3),
|
|
.IR DbMpool (3),
|
|
.if !'\*[TYPE]'JAVA'\{\
|
|
.IR DbMpoolFile (3),
|
|
\}
|
|
.IR Dbt (3),
|
|
.IR DbTxn (3),
|
|
.IR DbTxnMgr (3)
|
|
\}
|
|
.ad
|
|
.Hy
|
|
..
|
|
.\" The function header macro.
|
|
.\" This macro takes one argument:
|
|
.\" + the function name.
|
|
.de Fn
|
|
.in 2
|
|
.I \\$1
|
|
.in
|
|
..
|
|
.\" The XXX_open function text macro, for merged create/open calls.
|
|
.\" This macro takes two arguments:
|
|
.\" + the interface, e.g., "transaction region"
|
|
.\" + the prefix, e.g., "txn" (or the class name for C++, e.g., "DbTxn")
|
|
.de Co
|
|
.ie '\*[TYPE]'C'\{\
|
|
.Fn \\$2_open
|
|
The
|
|
.I \\$2_open
|
|
function copies a pointer, to the \\$1 identified by the
|
|
.B directory
|
|
.IR dir ,
|
|
into the memory location referenced by
|
|
.IR regionp .
|
|
.PP
|
|
If the
|
|
.I dbenv
|
|
argument to
|
|
.I \\$2_open
|
|
was initialized using
|
|
.IR db_appinit ,
|
|
.I dir
|
|
is interpreted as described by
|
|
.IR db_appinit (3).
|
|
\}
|
|
.el\{\
|
|
.Fn \\$2::open
|
|
The
|
|
.I \\$2::open
|
|
.ie '\*[TYPE]'CXX'\{\
|
|
method copies a pointer, to the \\$1 identified by the
|
|
.B directory
|
|
.IR dir ,
|
|
into the memory location referenced by
|
|
.IR regionp .
|
|
\}
|
|
.el\{\
|
|
method returns a \\$1 identified by the
|
|
.B directory
|
|
.IR dir .
|
|
\}
|
|
.PP
|
|
If the
|
|
.I dbenv
|
|
argument to
|
|
.I \\$2::open
|
|
was initialized using
|
|
.IR DbEnv::appinit ,
|
|
.I dir
|
|
is interpreted as described by
|
|
.IR DbEnv (3).
|
|
\}
|
|
.PP
|
|
Otherwise,
|
|
if
|
|
.I dir
|
|
is not NULL,
|
|
it is interpreted relative to the current working directory of the process.
|
|
If
|
|
.I dir
|
|
is NULL,
|
|
the following environment variables are checked in order:
|
|
``TMPDIR'', ``TEMP'', and ``TMP''.
|
|
If one of them is set,
|
|
\\$1 files are created relative to the directory it specifies.
|
|
If none of them are set, the first possible one of the following
|
|
directories is used:
|
|
.IR /var/tmp ,
|
|
.IR /usr/tmp ,
|
|
.IR /temp ,
|
|
.IR /tmp ,
|
|
.I C:/temp
|
|
and
|
|
.IR C:/tmp .
|
|
.PP
|
|
All files associated with the \\$1 are created in this directory.
|
|
This directory must already exist when
|
|
.ie '\*[TYPE]'C'\{
|
|
\\$1_open
|
|
\}
|
|
.el\{\
|
|
\\$2::open
|
|
\}
|
|
is called.
|
|
If the \\$1 already exists,
|
|
the process must have permission to read and write the existing files.
|
|
If the \\$1 does not already exist,
|
|
it is optionally created and initialized.
|
|
..
|
|
.\" The common close language macro, for discarding created regions
|
|
.\" This macro takes one argument:
|
|
.\" + the function prefix, e.g., txn (the class name for C++, e.g., DbTxn)
|
|
.de Cc
|
|
In addition, if the
|
|
.I dir
|
|
argument to
|
|
.ie '\*[TYPE]'C'\{\
|
|
.ds Va db_appinit
|
|
.ds Vo \\$1_open
|
|
.ds Vu \\$1_unlink
|
|
\}
|
|
.el\{\
|
|
.ds Va DbEnv::appinit
|
|
.ds Vo \\$1::open
|
|
.ds Vu \\$1::unlink
|
|
\}
|
|
.I \\*(Vo
|
|
was NULL
|
|
and
|
|
.I dbenv
|
|
was not initialized using
|
|
.IR \\*(Va ,
|
|
.if '\\$1'memp'\{\
|
|
or the DB_MPOOL_PRIVATE flag was set,
|
|
\}
|
|
all files created for this shared region will be removed,
|
|
as if
|
|
.I \\*(Vu
|
|
were called.
|
|
.rm Va
|
|
.rm Vo
|
|
.rm Vu
|
|
..
|
|
.\" The DB_ENV information macro.
|
|
.\" This macro takes two arguments:
|
|
.\" + the function called to open, e.g., "txn_open"
|
|
.\" + the function called to close, e.g., "txn_close"
|
|
.de En
|
|
.ie '\*[TYPE]'C'\{\
|
|
based on the
|
|
.I dbenv
|
|
argument to
|
|
.IR \\$1 ,
|
|
which is a pointer to a structure of type DB_ENV (typedef'd in <db.h>).
|
|
Applications will normally use the same DB_ENV structure (initialized
|
|
by
|
|
.IR db_appinit (3)),
|
|
as an argument to all of the subsystems in the DB package.
|
|
.PP
|
|
References to the DB_ENV structure are maintained by DB,
|
|
so it may not be discarded until the last close function,
|
|
corresponding to an open function for which it was an argument,
|
|
has returned.
|
|
In order to ensure compatibility with future releases of DB, all fields of
|
|
the DB_ENV structure that are not explicitly set should be initialized to 0
|
|
before the first time the structure is used.
|
|
Do this by declaring the structure external or static, or by calling the C
|
|
library routine
|
|
.IR bzero (3)
|
|
or
|
|
.IR memset (3).
|
|
.PP
|
|
The fields of the DB_ENV structure used by
|
|
.I \\$1
|
|
are described below.
|
|
.if '\*[TYPE]'CXX'\{\
|
|
As references to the DB_ENV structure may be maintained by
|
|
.IR \\$1 ,
|
|
it is necessary that the DB_ENV structure and memory it references be valid
|
|
until the
|
|
.I \\$2
|
|
function is called.
|
|
\}
|
|
.ie '\\$1'db_appinit'\{The
|
|
.I dbenv
|
|
argument may not be NULL.
|
|
If any of the fields of the
|
|
.I dbenv
|
|
are set to 0,
|
|
defaults appropriate for the system are used where possible.
|
|
\}
|
|
.el\{If
|
|
.I dbenv
|
|
is NULL
|
|
or any of its fields are set to 0,
|
|
defaults appropriate for the system are used where possible.
|
|
\}
|
|
.PP
|
|
The following fields in the DB_ENV structure may be initialized before calling
|
|
.IR \\$1 :
|
|
\}
|
|
.el\{\
|
|
based on which set methods have been used.
|
|
It is expected that applications will use a single DbEnv object as the
|
|
argument to all of the subsystems in the DB package.
|
|
The fields of the DbEnv object used by
|
|
.I \\$1
|
|
are described below.
|
|
As references to the DbEnv object may be maintained by
|
|
.IR \\$1 ,
|
|
it is necessary that the DbEnv object and memory it references be valid
|
|
until the object is destroyed.
|
|
.ie '\\$1'appinit'\{\
|
|
The
|
|
.I dbenv
|
|
argument may not be NULL.
|
|
If any of the fields of the
|
|
.I dbenv
|
|
are set to 0,
|
|
defaults appropriate for the system are used where possible.
|
|
\}
|
|
.el\{\
|
|
Any of the DbEnv fields that are not explicitly set will default to
|
|
appropriate values.
|
|
\}
|
|
.PP
|
|
The following fields in the DbEnv object may be initialized, using the
|
|
appropriate set method, before calling
|
|
.IR \\$1 :
|
|
\}
|
|
..
|
|
.\" The DB_ENV common fields macros.
|
|
.de Se
|
|
.if '\*[TYPE]'JAVA'\{\
|
|
.TP 5
|
|
DbErrcall db_errcall;
|
|
.ns
|
|
.TP 5
|
|
String db_errpfx;
|
|
.ns
|
|
.TP 5
|
|
int db_verbose;
|
|
The error fields of the DbEnv behave as described for
|
|
.IR DbEnv (3).
|
|
\}
|
|
.ie '\*[TYPE]'CXX'\{\
|
|
.TP 5
|
|
void *(*db_errcall)(char *db_errpfx, char *buffer);
|
|
.ns
|
|
.TP 5
|
|
FILE *db_errfile;
|
|
.ns
|
|
.TP 5
|
|
const char *db_errpfx;
|
|
.ns
|
|
.TP 5
|
|
class ostream *db_error_stream;
|
|
.ns
|
|
.TP 5
|
|
int db_verbose;
|
|
The error fields of the DbEnv behave as described for
|
|
.IR DbEnv (3).
|
|
\}
|
|
.el\{\
|
|
void *(*db_errcall)(char *db_errpfx, char *buffer);
|
|
.ns
|
|
.TP 5
|
|
FILE *db_errfile;
|
|
.ns
|
|
.TP 5
|
|
const char *db_errpfx;
|
|
.ns
|
|
.TP 5
|
|
int db_verbose;
|
|
The error fields of the DB_ENV behave as described for
|
|
.IR db_appinit (3).
|
|
.sp
|
|
\}
|
|
..
|
|
.\" The open flags.
|
|
.de Fm
|
|
The
|
|
.I flags
|
|
and
|
|
.I mode
|
|
arguments specify how files will be opened and/or created when they
|
|
don't already exist.
|
|
The flags value is specified by
|
|
.BR or 'ing
|
|
together one or more of the following values:
|
|
.Sj DB_CREATE
|
|
Create any underlying files, as necessary.
|
|
If the files do not already exist and the DB_CREATE flag is not specified,
|
|
the call will fail.
|
|
..
|
|
.\" DB_THREAD open flag macro.
|
|
.\" This macro takes two arguments:
|
|
.\" + the open function name
|
|
.\" + the object it returns.
|
|
.de Ft
|
|
.TP 5
|
|
.Sj DB_THREAD
|
|
Cause the \\$2 handle returned by the
|
|
.I \\$1
|
|
.Al function method
|
|
to be useable by multiple threads within a single address space,
|
|
i.e., to be ``free-threaded''.
|
|
.if '\*[TYPE]'JAVA'\{\
|
|
Threading is assumed in the Java API,
|
|
so no special flags are required,
|
|
and DB functions will always behave as if the DB_THREAD flag was specified.
|
|
\}
|
|
..
|
|
.\" The mode macro.
|
|
.\" This macro takes one argument:
|
|
.\" + the subsystem name.
|
|
.de Mo
|
|
All files created by the \\$1 are created with mode
|
|
.I mode
|
|
(as described in
|
|
.IR chmod (2))
|
|
and modified by the process' umask value at the time of creation (see
|
|
.IR umask (2)).
|
|
The group ownership of created files is based on the system and directory
|
|
defaults, and is not further specified by DB.
|
|
..
|
|
.\" The application exits macro.
|
|
.\" This macro takes one argument:
|
|
.\" + the application name.
|
|
.de Ex
|
|
The
|
|
.I \\$1
|
|
utility exits 0 on success, and >0 if an error occurs.
|
|
..
|
|
.\" The application -h section.
|
|
.\" This macro takes one argument:
|
|
.\" + the application name
|
|
.de Dh
|
|
DB_HOME
|
|
If the
|
|
.B \-h
|
|
option is not specified and the environment variable
|
|
.I DB_HOME
|
|
is set, it is used as the path of the database home, as described in
|
|
.IR db_appinit (3).
|
|
..
|
|
.\" The function DB_HOME ENVIRONMENT VARIABLES section.
|
|
.\" This macro takes one argument:
|
|
.\" + the open function name
|
|
.de Eh
|
|
DB_HOME
|
|
If the
|
|
.I dbenv
|
|
argument to
|
|
.I \\$1
|
|
was initialized using
|
|
.IR db_appinit ,
|
|
the environment variable DB_HOME may be used as the path of the database
|
|
home for the interpretation of the
|
|
.I dir
|
|
argument to
|
|
.IR \\$1 ,
|
|
as described in
|
|
.IR db_appinit (3).
|
|
.if \\n(.$>1 \{Specifically,
|
|
.I \\$1
|
|
is affected by the configuration string value of \\$2.\}
|
|
..
|
|
.\" The function TMPDIR ENVIRONMENT VARIABLES section.
|
|
.\" This macro takes two arguments:
|
|
.\" + the interface, e.g., "transaction region"
|
|
.\" + the prefix, e.g., "txn" (or the class name for C++, e.g., "DbTxn")
|
|
.de Ev
|
|
TMPDIR
|
|
If the
|
|
.I dbenv
|
|
argument to
|
|
.ie '\*[TYPE]'C'\{\
|
|
.ds Vo \\$2_open
|
|
\}
|
|
.el\{\
|
|
.ds Vo \\$2::open
|
|
\}
|
|
.I \\*(Vo
|
|
was NULL or not initialized using
|
|
.IR db_appinit ,
|
|
the environment variable TMPDIR may be used as the directory in which to
|
|
create the \\$1,
|
|
as described in the
|
|
.I \\*(Vo
|
|
section above.
|
|
.rm Vo
|
|
..
|
|
.\" The unused flags macro.
|
|
.de Fl
|
|
The
|
|
.I flags
|
|
parameter is currently unused, and must be set to 0.
|
|
..
|
|
.\" The no-space TP macro.
|
|
.de Nt
|
|
.br
|
|
.ns
|
|
.TP 5
|
|
..
|
|
.\" The return values of the functions macros.
|
|
.\" Rc is the standard two-value return with a suffix for more values.
|
|
.\" Ro is the standard two-value return but there were previous values.
|
|
.\" Rt is the standard two-value return, returning errno, 0, or < 0.
|
|
.\" These macros take one argument:
|
|
.\" + the routine name
|
|
.de Rc
|
|
The
|
|
.I \\$1
|
|
.ie '\*[TYPE]'C'\{function returns the value of
|
|
.I errno
|
|
on failure,
|
|
0 on success,
|
|
\}
|
|
.el\{method throws a
|
|
.IR DbException (3)
|
|
.ie '\*[TYPE]'CXX'\{or returns the value of
|
|
.I errno
|
|
on failure,
|
|
0 on success,
|
|
\}
|
|
.el\{that encapsulates an
|
|
.I errno
|
|
on failure,
|
|
\}
|
|
\}
|
|
..
|
|
.de Ro
|
|
Otherwise, the
|
|
.I \\$1
|
|
.ie '\*[TYPE]'C'\{function returns the value of
|
|
.I errno
|
|
on failure and 0 on success.
|
|
\}
|
|
.el\{method throws a
|
|
.IR DbException (3)
|
|
.ie '\*[TYPE]'CXX'\{or returns the value of
|
|
.I errno
|
|
on failure and 0 on success.
|
|
\}
|
|
.el\{that encapsulates an
|
|
.I errno
|
|
on failure,
|
|
\}
|
|
\}
|
|
..
|
|
.de Rt
|
|
The
|
|
.I \\$1
|
|
.ie '\*[TYPE]'C'\{function returns the value of
|
|
.I errno
|
|
on failure and 0 on success.
|
|
\}
|
|
.el\{method throws a
|
|
.IR DbException (3)
|
|
.ie '\*[TYPE]'CXX'\{or returns the value of
|
|
.I errno
|
|
on failure and 0 on success.
|
|
\}
|
|
.el\{that encapsulates an
|
|
.I errno
|
|
on failure.
|
|
\}
|
|
\}
|
|
..
|
|
.\" The TXN id macro.
|
|
.de Tx
|
|
.IP
|
|
If the file is being accessed under transaction protection,
|
|
the
|
|
.I txnid
|
|
parameter is a transaction ID returned from
|
|
.IR txn_begin ,
|
|
otherwise, NULL.
|
|
..
|
|
.\" The XXX_unlink function text macro.
|
|
.\" This macro takes two arguments:
|
|
.\" + the interface, e.g., "transaction region"
|
|
.\" + the prefix (for C++, this is the class name)
|
|
.de Un
|
|
.ie '\*[TYPE]'C'\{\
|
|
.ds Va db_appinit
|
|
.ds Vc \\$2_close
|
|
.ds Vo \\$2_open
|
|
.ds Vu \\$2_unlink
|
|
\}
|
|
.el\{\
|
|
.ds Va DbEnv::appinit
|
|
.ds Vc \\$2::close
|
|
.ds Vo \\$2::open
|
|
.ds Vu \\$2::unlink
|
|
\}
|
|
.Fn \\*(Vu
|
|
The
|
|
.I \\*(Vu
|
|
.Al function method
|
|
destroys the \\$1 identified by the directory
|
|
.IR dir ,
|
|
removing all files used to implement the \\$1.
|
|
.ie '\\$2'log' \{(The log files themselves and the directory
|
|
.I dir
|
|
are not removed.)\}
|
|
.el \{(The directory
|
|
.I dir
|
|
is not removed.)\}
|
|
If there are processes that have called
|
|
.I \\*(Vo
|
|
without calling
|
|
.I \\*(Vc
|
|
(i.e., there are processes currently using the \\$1),
|
|
.I \\*(Vu
|
|
will fail without further action,
|
|
unless the force flag is set,
|
|
in which case
|
|
.I \\*(Vu
|
|
will attempt to remove the \\$1 files regardless of any processes
|
|
still using the \\$1.
|
|
.PP
|
|
The result of attempting to forcibly destroy the region when a process
|
|
has the region open is unspecified.
|
|
Processes using a shared memory region maintain an open file descriptor
|
|
for it.
|
|
On UNIX systems, the region removal should succeed
|
|
and processes that have already joined the region should continue to
|
|
run in the region without change,
|
|
however processes attempting to join the \\$1 will either fail or
|
|
attempt to create a new region.
|
|
On other systems, e.g., WNT, where the
|
|
.IR unlink (2)
|
|
system call will fail if any process has an open file descriptor
|
|
for the file,
|
|
the region removal will fail.
|
|
.PP
|
|
In the case of catastrophic or system failure,
|
|
database recovery must be performed (see
|
|
.IR db_recover (1)
|
|
or the DB_RECOVER and DB_RECOVER_FATAL flags to
|
|
.IR \\*(Va (3)).
|
|
Alternatively, if recovery is not required because no database state is
|
|
maintained across failures,
|
|
it is possible to clean up a \\$1 by removing all of the
|
|
files in the directory specified to the
|
|
.I \\*(Vo
|
|
.Al function, method,
|
|
as \\$1 files are never created in any directory other than the one
|
|
specified to
|
|
.IR \\*(Vo .
|
|
Note, however,
|
|
that this has the potential to remove files created by the other DB
|
|
subsystems in this database environment.
|
|
.PP
|
|
.Rt \\*(Vu
|
|
.rm Va
|
|
.rm Vo
|
|
.rm Vu
|
|
.rm Vc
|
|
..
|
|
.\" Signal paragraph for standard utilities.
|
|
.\" This macro takes one argument:
|
|
.\" + the utility name.
|
|
.de Si
|
|
The
|
|
.I \\$1
|
|
utility attaches to DB shared memory regions.
|
|
In order to avoid region corruption,
|
|
it should always be given the chance to detach and exit gracefully.
|
|
To cause
|
|
.I \\$1
|
|
to clean up after itself and exit,
|
|
send it an interrupt signal (SIGINT).
|
|
..
|
|
.\" Logging paragraph for standard utilities.
|
|
.\" This macro takes one argument:
|
|
.\" + the utility name.
|
|
.de Pi
|
|
.B \-L
|
|
Log the execution of the \\$1 utility to the specified file in the
|
|
following format, where ``###'' is the process ID, and the date is
|
|
the time the utility starting running.
|
|
.sp
|
|
\\$1: ### Wed Jun 15 01:23:45 EDT 1995
|
|
.sp
|
|
This file will be removed if the \\$1 utility exits gracefully.
|
|
..
|
|
.\" Malloc paragraph.
|
|
.\" This macro takes one argument:
|
|
.\" + the allocated object
|
|
.de Ma
|
|
.if !'\*[TYPE]'JAVA'\{\
|
|
\\$1 are created in allocated memory.
|
|
If
|
|
.I db_malloc
|
|
is non-NULL,
|
|
it is called to allocate the memory,
|
|
otherwise,
|
|
the library function
|
|
.IR malloc (3)
|
|
is used.
|
|
The function
|
|
.I db_malloc
|
|
must match the calling conventions of the
|
|
.IR malloc (3)
|
|
library routine.
|
|
Regardless,
|
|
the caller is responsible for deallocating the returned memory.
|
|
To deallocate the returned memory,
|
|
free each returned memory pointer;
|
|
pointers inside the memory do not need to be individually freed.
|
|
\}
|
|
..
|
|
.\" Underlying function paragraph.
|
|
.\" This macro takes two arguments:
|
|
.\" + the function name
|
|
.\" + the utility name
|
|
.de Uf
|
|
The
|
|
.I \\$1
|
|
.Al function method
|
|
is the underlying function used by the
|
|
.IR \\$2 (1)
|
|
utility.
|
|
See the source code for the
|
|
.I \\$2
|
|
utility for an example of using
|
|
.I \\$1
|
|
in a UNIX environment.
|
|
..
|
|
.\" Underlying function paragraph, for C++.
|
|
.\" This macro takes three arguments:
|
|
.\" + the C++ method name
|
|
.\" + the function name for C
|
|
.\" + the utility name
|
|
.de Ux
|
|
The
|
|
.I \\$1
|
|
method is based on the C
|
|
.I \\$2
|
|
function, which
|
|
is the underlying function used by the
|
|
.IR \\$3 (1)
|
|
utility.
|
|
See the source code for the
|
|
.I \\$3
|
|
utility for an example of using
|
|
.I \\$2
|
|
in a UNIX environment.
|
|
..
|
|
.\" ANSI C function replacement.
|
|
.de An
|
|
Replace all DB calls to the ANSI C X3.159-1989 (``ANSI C'') standard
|
|
.I \\$1
|
|
function with
|
|
.IR func ,
|
|
which must conform to the standard interface.
|
|
..
|
|
.ds aa "IEEE Std 1003.1b-1993 (``POSIX'')
|
|
.\" POSIX 1003.1 function replacement.
|
|
.de Po
|
|
Replace all DB calls to the \*(aa
|
|
.I \\$1
|
|
function with
|
|
.IR func ,
|
|
which must conform to the standard interface.
|
|
..
|
|
.TH DB_JUMP 3 "March 22, 1998"
|
|
.UC 7
|
|
.SH NAME
|
|
db_jump_set, db_value_set \- replace underlying DB functionality
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.ft B
|
|
#include <db.h>
|
|
|
|
int
|
|
db_jump_set(void *func, int which);
|
|
|
|
int
|
|
db_value_set(int value, int which);
|
|
.ft R
|
|
.fi
|
|
.SH DESCRIPTION
|
|
.Gn
|
|
.PP
|
|
This manual page describes interfaces to tune or replace underlying system
|
|
functionality used by the DB library.
|
|
Few applications should have any need for these interfaces.
|
|
.PP
|
|
.Fn db_jump_set
|
|
The
|
|
.I db_jump_set
|
|
function enables applications to replace underlying DB library functionality
|
|
by replacing entries in a function call jump table.
|
|
The
|
|
.I which
|
|
argument specifies the entry to be replaced by the argument
|
|
.IR func .
|
|
.PP
|
|
The following values of
|
|
.I which
|
|
are supported:
|
|
.TP 5
|
|
DB_FUNC_CLOSE
|
|
.Po close
|
|
.TP 5
|
|
DB_FUNC_DIRFREE
|
|
The DB library requires the ability to return any memory allocated as part
|
|
of the routine which reads through a directory and creates a list of files
|
|
that that the directory contains (see DB_FUNC_DIRLIST).
|
|
The
|
|
.I func
|
|
argument must conform to the following interface:
|
|
.sp
|
|
.ti +5
|
|
int dirfree(char **namesp, int cnt);
|
|
.sp
|
|
The
|
|
.I namesp
|
|
and
|
|
.I cnt
|
|
arguments are the same values as were returned by the
|
|
DB_FUNC_DIRLIST function.
|
|
.sp
|
|
.Rt dirfree
|
|
.TP 5
|
|
DB_FUNC_DIRLIST
|
|
The DB library requires the ability to read through a directory and create
|
|
a list of files that that the directory contains.
|
|
The
|
|
.I func
|
|
argument must conform to the following interface:
|
|
.sp
|
|
.nf
|
|
.ti +5
|
|
int dirlist(const char *dir,
|
|
.ti +8
|
|
char ***namesp, int *cntp);
|
|
.fi
|
|
.sp
|
|
The
|
|
.I dir
|
|
argument is the name of the directory to be searched.
|
|
The function must return a pointer to an array of nul-terminated file
|
|
names in the memory location referenced by the argument
|
|
.IR namesp ,
|
|
and a count of the number of elements in the array in the memory location
|
|
referenced by
|
|
.IR cntp .
|
|
.sp
|
|
.Rt dirlist
|
|
.TP 5
|
|
DB_FUNC_EXISTS
|
|
The DB library requires the ability to determine if a file exists,
|
|
and optionally, if it is a file of type directory.
|
|
The
|
|
.I func
|
|
argument must conform to the following interface:
|
|
.sp
|
|
.ti +5
|
|
int exists(const char *path, int *isdirp);
|
|
.sp
|
|
The
|
|
.I path
|
|
argument is the pathname of the file to be checked.
|
|
.sp
|
|
If the
|
|
.I isdirp
|
|
argument is non-NULL,
|
|
it must be set to non-0 if
|
|
.I path
|
|
is a directory, and 0 if
|
|
.I path
|
|
is not a directory.
|
|
.sp
|
|
.Rt exists
|
|
.TP 5
|
|
DB_FUNC_FREE
|
|
.An free
|
|
.TP 5
|
|
DB_FUNC_FSYNC
|
|
.Po fsync
|
|
.TP 5
|
|
DB_FUNC_IOINFO
|
|
The DB library requires the ability to determine the size and I/O
|
|
characteristics of a file.
|
|
The
|
|
.I func
|
|
argument must conform to the following interface:
|
|
.sp
|
|
.nf
|
|
.ti +5
|
|
int ioinfo(const char *path, int fd,
|
|
.ti +8
|
|
u_int32_t *mbytesp, u_int32_t *bytesp,
|
|
.ti +8
|
|
u_int32_t *iosizep);
|
|
.fi
|
|
.sp
|
|
The
|
|
.I path
|
|
argument is the pathname of the file to be checked, and the
|
|
.I fd
|
|
argument is an open file descriptor on the file.
|
|
.sp
|
|
If the
|
|
.I mbytesp
|
|
and
|
|
.I bytesp
|
|
arguments are non-NULL, the
|
|
.I ioinfo
|
|
function must return in them the size of the file: the number of megabytes
|
|
in the file into the memory location referenced by the
|
|
.I mbytesp
|
|
argument,
|
|
and the number of bytes over and above that number of megabytes into the
|
|
memory location referenced by the
|
|
.I bytesp
|
|
argument.
|
|
.sp
|
|
In addition, if the
|
|
.I iosizep
|
|
argument is non-NULL, the
|
|
.I ioinfo
|
|
function must return the optimum granularity for I/O operations to the
|
|
file in the memory location referenced by it.
|
|
.sp
|
|
.Rt ioinfo
|
|
.TP 5
|
|
DB_FUNC_MALLOC
|
|
.An malloc
|
|
.TP 5
|
|
DB_FUNC_MAP
|
|
The DB library requires the ability to map a file into memory and to
|
|
create shared memory regions (which may or may not be backed by files).
|
|
The
|
|
.I func
|
|
argument must conform to the following interface:
|
|
.sp
|
|
.nf
|
|
.ti +5
|
|
int map(char *path, int fd, size_t len,
|
|
.ti +8
|
|
int is_region, int is_anonymous, int is_rdonly,
|
|
.ti +8
|
|
void **addr);
|
|
.fi
|
|
.sp
|
|
The
|
|
.I path
|
|
argument is the name of a file.
|
|
The
|
|
.I fd
|
|
argument is an open file descriptor on that file.
|
|
.sp
|
|
The
|
|
.I is_region
|
|
argument will be zero if the intention is to map a file into shared
|
|
memory.
|
|
In this case, the
|
|
.I map
|
|
function must map the first
|
|
.I len
|
|
bytes of the file into memory and return a pointer to the mapped
|
|
location in the memory location referenced by the argument
|
|
.IR addr .
|
|
In this case, the
|
|
.I is_anonymous
|
|
argument will always be zero.
|
|
The
|
|
.I is_rdonly
|
|
argument will be non-zero if the file is considered read-only by the caller.
|
|
.sp
|
|
The
|
|
.I is_region
|
|
argument will be non-zero if the memory is intended to be used as a
|
|
shared memory region for synchronization between DB threads/processes.
|
|
In this case, the returned memory may be of any kind (e.g., anonymous),
|
|
but must be able to support semaphores.
|
|
If the application has previously specified that regions are to be
|
|
instantiated in anonymous memory (see DB_REGION_ANON below),
|
|
or the region is being joined and is believed to have been allocated
|
|
in anonymous shared memory, the
|
|
.I is_anonymous
|
|
argument will be non-zero.
|
|
Additionally, the
|
|
.I path
|
|
and
|
|
.I fd
|
|
arguments may be ignored (although future
|
|
.I map
|
|
calls using the same
|
|
.I path
|
|
must return the same memory),
|
|
and the
|
|
.I is_rdonly
|
|
argument will always be zero.
|
|
.sp
|
|
By default, on UNIX systems, the DB library will use the \*(aa
|
|
.IR mmap (2)
|
|
interface to both map regular files into shared memory and create
|
|
shared memory regions.
|
|
If the application specifies that shared memory regions be instantiated
|
|
in anonymous memory (see DB_REGION_ANON below), the
|
|
.IR shmget (2)
|
|
shared memory segment interface will be used, where available, and
|
|
the MAP_ANON or MAP_ANONYMOUS options to
|
|
.IR mmap (2)
|
|
when
|
|
.IR shmget (2)
|
|
is not available.
|
|
.sp
|
|
When using
|
|
.IR shmget (2),
|
|
shared memory regions are named, and so multiple processes may share them.
|
|
When using the
|
|
.I mmap
|
|
MAP_ANON or MAP_ANONYMOUS options, shared memory regions are
|
|
.B not
|
|
named, and so may only be accessed by a single process and its threads.
|
|
.sp
|
|
.RS
|
|
.TP 5
|
|
HP/UX note:
|
|
The
|
|
.IR shmget (2)
|
|
interfaces are not used on HP/UX, even though they exist, as anonymous
|
|
memory allocated using
|
|
.IR shmget (2)
|
|
cannot be used to store semaphores.
|
|
.RE
|
|
.sp
|
|
.Rt map
|
|
.TP 5
|
|
DB_FUNC_OPEN
|
|
.Po open
|
|
.TP 5
|
|
DB_FUNC_READ
|
|
.Po read
|
|
.TP 5
|
|
DB_FUNC_REALLOC
|
|
.An realloc
|
|
.TP 5
|
|
DB_FUNC_RUNLINK
|
|
The DB library requires the ability to remove shared memory regions from
|
|
the system, whether or not they are backed by regular files.
|
|
The
|
|
.I func
|
|
argument must conform to the following interface:
|
|
.sp
|
|
.nf
|
|
.ti +5
|
|
int runlink(char *path);
|
|
.fi
|
|
.sp
|
|
The
|
|
.I path
|
|
argument is the path argument specified to the DB_FUNC_MAP function when
|
|
the region was mapped into memory.
|
|
.sp
|
|
.Rt runlink
|
|
.TP 5
|
|
DB_FUNC_SEEK
|
|
The DB library requires the ability to specify that a subsequent read from
|
|
or write to a file will occur at a specific location in that file.
|
|
The
|
|
.I func
|
|
argument must conform to the following interface:
|
|
.sp
|
|
.nf
|
|
.ti +5
|
|
int seek(int fd, size_t pgsize, db_pgno_t pageno,
|
|
.ti +8
|
|
u_int32_t relative, int rewind, int whence);
|
|
.fi
|
|
.sp
|
|
The
|
|
.I fd
|
|
argument is an open file descriptor on the file.
|
|
The
|
|
.I seek
|
|
function must cause a subsequent read from or write to the file to occur
|
|
at a byte offset specified by the calculation:
|
|
.sp
|
|
.ti +5
|
|
(pgsize * pageno) + relative
|
|
.sp
|
|
If
|
|
.I rewind
|
|
is non-zero, the byte offset is treated as a backwards seek, not a forwards one.
|
|
.sp
|
|
The
|
|
.I whence
|
|
argument specifies where in the file the byte offset is relative to,
|
|
as described by the \*(aa
|
|
.I lseek
|
|
system call.
|
|
.sp
|
|
.Rt seek
|
|
.TP 5
|
|
DB_FUNC_SLEEP
|
|
The DB library requires the ability to cause a process to suspend itself
|
|
for a period of time, relinquishing control of the processor to any other
|
|
waiting thread of control.
|
|
The
|
|
.I func
|
|
argument must conform to the following interface:
|
|
.sp
|
|
.ti +5
|
|
int sleep(u_long seconds, u_long microseconds);
|
|
.sp
|
|
The
|
|
.I seconds
|
|
and
|
|
.I microseconds
|
|
arguments specify the amount of time to wait until the suspending thread
|
|
of control should run again.
|
|
.sp
|
|
The
|
|
.I seconds
|
|
and
|
|
.I microseconds
|
|
arguments may not be normalized when the
|
|
.I sleep
|
|
function is called, i.e., the
|
|
.I microseconds
|
|
argument may be greater than 1000000.
|
|
.sp
|
|
.Rt sleep
|
|
.TP 5
|
|
DB_FUNC_UNLINK
|
|
.Po unlink
|
|
.TP 5
|
|
DB_FUNC_UNMAP
|
|
The DB library requires the ability to unmap a file or shared memory region
|
|
from memory.
|
|
The
|
|
.I func
|
|
argument must conform to the following interface:
|
|
.sp
|
|
.ti +5
|
|
int unmap(void *addr, size_t len);
|
|
.sp
|
|
The
|
|
.I addr
|
|
argument is the argument returned by the DB_FUNC_MAP function when the
|
|
file or region was mapped into memory, and the
|
|
.I len
|
|
argument is the same as the
|
|
.I len
|
|
argument specified to the DB_FUNC_MAP function when the file or region
|
|
was mapped into memory.
|
|
.sp
|
|
.Rt unmap
|
|
.TP 5
|
|
DB_FUNC_WRITE
|
|
.Po write
|
|
.TP 5
|
|
DB_FUNC_YIELD
|
|
The DB library requires the ability to yield the processor from the current
|
|
thread of control to any other waiting threads of control.
|
|
The
|
|
.I func
|
|
argument must conform to the following interface:
|
|
.sp
|
|
.ti +5
|
|
int yield(void);
|
|
.sp
|
|
.sp
|
|
The
|
|
.I yield
|
|
function must be able to cause the rescheduling all participants in the
|
|
current DB environment, whether threaded or not.
|
|
It may be incorrect to supply a thread
|
|
.I yield
|
|
function if more than a single process is operating in the DB environment.
|
|
This is because many thread-yield functions will not allow other processes
|
|
to run,
|
|
and the contested lock may be held by another process, not by another thread.
|
|
.sp
|
|
If no
|
|
.I yield
|
|
function is specified, or if the
|
|
.I yield
|
|
function returns an error,
|
|
the function specified by the DB_FUNC_SLEEP entry will be used instead or
|
|
subsequently, i.e., if no
|
|
.I yield
|
|
function is specified,
|
|
or it is possible for the
|
|
.I yield
|
|
function to fail, the
|
|
.I sleep
|
|
function
|
|
.B must
|
|
cause the processor to reschedule any waiting threads of control for execution.
|
|
.\".sp
|
|
.\".ft B
|
|
.\"Solaris architecture note:
|
|
.\".ft R
|
|
.\"Because of bugs in versions of Solaris before version 5.6,
|
|
.\"the DB library uses the
|
|
.\".IR sema_wait (3T)
|
|
.\"call instead of the
|
|
.\".IR sema_trywait (3T)
|
|
.\"call.
|
|
.\"For this reason, replacing the
|
|
.\".I yield
|
|
.\"function will have no effect on Solaris.
|
|
.sp
|
|
.Rt yield
|
|
.PP
|
|
.Rt db_jump_set
|
|
.PP
|
|
.Fn db_value_set
|
|
The
|
|
.I db_value_set
|
|
function enables applications to specify underlying DB library functionality.
|
|
The
|
|
.I which
|
|
argument specifies the information being set by the argument
|
|
.IR value .
|
|
.PP
|
|
The following values of
|
|
.I which
|
|
are supported:
|
|
.TP 5
|
|
DB_MUTEXLOCKS
|
|
Grant all requested mutual exclusion mutexes without testing for their
|
|
availability.
|
|
This flag should never be used for any other purpose than debugging.
|
|
.TP 5
|
|
DB_REGION_ANON
|
|
Setting
|
|
.I value
|
|
to a non-zero value specifies that shared memory regions are to be created
|
|
in anonymous memory, and not backed by a regular file.
|
|
DB_REGION_NAME differs from DB_REGION_ANON in that the former will fail if
|
|
the shared memory regions cannot be named, that is, if multiple processes
|
|
cannot use them.
|
|
See DB_FUNC_MAP for more information.
|
|
.TP 5
|
|
DB_REGION_INIT
|
|
In some applications, the expense of page-faulting the shared memory regions
|
|
can affect performance, e.g., when the page-fault occurs while holding a lock,
|
|
other lock requests can convoy and overall throughput may decrease.
|
|
Setting
|
|
.I value
|
|
to a non-zero value specifies that one byte be read from each 4K page of the
|
|
shared memory region when the region is initialized.
|
|
.TP 5
|
|
DB_REGION_NAME
|
|
Setting
|
|
.I value
|
|
to a non-zero value specifies that shared memory regions are to be created
|
|
in anonymous memory, and not backed by a regular file.
|
|
DB_REGION_NAME differs from DB_REGION_ANON in that the former will fail if
|
|
the shared memory regions cannot be named, that is, if multiple processes
|
|
cannot use them.
|
|
See DB_FUNC_MAP for more information.
|
|
.TP 5
|
|
DB_TSL_SPINS
|
|
Specify the number of times mutexes should spin without blocking.
|
|
.sp
|
|
This value defaults to 1 on uniprocessor systems and to 50 times the number
|
|
of processors on multiprocessor systems.
|
|
.PP
|
|
.Rt db_value_set
|
|
.SH ERRORS
|
|
The
|
|
.I db_jump_set
|
|
function may fail and return
|
|
.I errno
|
|
for the following conditions:
|
|
.TP 5
|
|
.Ei
|
|
.SH BUGS
|
|
No type checking is done of the
|
|
.I func
|
|
argument,
|
|
and specifying an invalid replacement routine will cause unpredictable
|
|
results.
|
|
.PP
|
|
Applications should be careful to replace related functions as a group
|
|
and at the same time.
|
|
Replacing DB_FUNC_MALLOC without replacing DB_FUNC_REALLOC is likely
|
|
to result in unpredictable results.
|
|
.PP
|
|
On Windows/95, files that are opened by multiple processes do not share
|
|
data correctly. To tell Berkeley DB to use a named region of the paging
|
|
file to share memory instead, use:
|
|
.PP
|
|
.RS
|
|
db_value_set(1, DB_REGION_NAME);
|
|
.RE
|
|
.PP
|
|
You do not need to do this if your application can guarantee that
|
|
only one process will be accessing DB files.
|
|
.PP
|
|
On Windows/NT, sharing of data between processes through the paging file
|
|
does not work correctly, so you should not call
|
|
.IR db_value_set .
|
|
That will allow DB to use the file itself for sharing, which works
|
|
correctly.
|
|
.SH "SEE ALSO"
|
|
.Sa
|