зеркало из https://github.com/mozilla/gecko-dev.git
2026 строки
43 KiB
Groff
2026 строки
43 KiB
Groff
.ds TYPE C
|
|
.\"
|
|
.\" See the file LICENSE for redistribution information.
|
|
.\"
|
|
.\" Copyright (c) 1996, 1997, 1998
|
|
.\" Sleepycat Software. All rights reserved.
|
|
.\"
|
|
.\" @(#)db_mpool.so 10.42 (Sleepycat) 5/10/98
|
|
.\"
|
|
.\"
|
|
.\" See the file LICENSE for redistribution information.
|
|
.\"
|
|
.\" Copyright (c) 1997, 1998
|
|
.\" Sleepycat Software. All rights reserved.
|
|
.\"
|
|
.\" @(#)macros.so 10.45 (Sleepycat) 5/4/98
|
|
.\"
|
|
.\" We don't want hyphenation for any HTML documents.
|
|
.ie '\*[HTML]'YES'\{\
|
|
.nh
|
|
\}
|
|
.el\{\
|
|
.ds Hy
|
|
.hy
|
|
..
|
|
.ds Nh
|
|
.nh
|
|
..
|
|
\}
|
|
.\" The alternative text macro
|
|
.\" This macro takes two arguments:
|
|
.\" + the text produced if this is a "C" manpage
|
|
.\" + the text produced if this is a "CXX" or "JAVA" manpage
|
|
.\"
|
|
.de Al
|
|
.ie '\*[TYPE]'C'\{\\$1
|
|
\}
|
|
.el\{\\$2
|
|
\}
|
|
..
|
|
.\" Scoped name macro.
|
|
.\" Produces a_b, a::b, a.b depending on language
|
|
.\" This macro takes two arguments:
|
|
.\" + the class or prefix (without underscore)
|
|
.\" + the name within the class or following the prefix
|
|
.de Sc
|
|
.ie '\*[TYPE]'C'\{\\$1_\\$2
|
|
\}
|
|
.el\{\
|
|
.ie '\*[TYPE]'CXX'\{\\$1::\\$2
|
|
\}
|
|
.el\{\\$1.\\$2
|
|
\}
|
|
\}
|
|
..
|
|
.\" Scoped name for Java.
|
|
.\" Produces Db.b, for Java, otherwise just b. This macro is used for
|
|
.\" constants that must be scoped in Java, but are global otherwise.
|
|
.\" This macro takes two arguments:
|
|
.\" + the class
|
|
.\" + the name within the class or following the prefix
|
|
.de Sj
|
|
.ie '\*[TYPE]'JAVA'\{\
|
|
.TP 5
|
|
Db.\\$1\}
|
|
.el\{\
|
|
.TP 5
|
|
\\$1\}
|
|
..
|
|
.\" The general information text macro.
|
|
.de Gn
|
|
.ie '\*[TYPE]'C'\{The DB library is a family of groups of functions that provides a modular
|
|
programming interface to transactions and record-oriented file access.
|
|
The library includes support for transactions, locking, logging and file
|
|
page caching, as well as various indexed access methods.
|
|
Many of the functional groups (e.g., the file page caching functions)
|
|
are useful independent of the other DB functions,
|
|
although some functional groups are explicitly based on other functional
|
|
groups (e.g., transactions and logging).
|
|
\}
|
|
.el\{The DB library is a family of classes that provides a modular
|
|
programming interface to transactions and record-oriented file access.
|
|
The library includes support for transactions, locking, logging and file
|
|
page caching, as well as various indexed access methods.
|
|
Many of the classes (e.g., the file page caching class)
|
|
are useful independent of the other DB classes,
|
|
although some classes are explicitly based on other classes
|
|
(e.g., transactions and logging).
|
|
\}
|
|
For a general description of the DB package, see
|
|
.IR db_intro (3).
|
|
..
|
|
.\" The library error macro, the local error macro.
|
|
.\" These macros take one argument:
|
|
.\" + the function name.
|
|
.de Ee
|
|
The
|
|
.I \\$1
|
|
.ie '\*[TYPE]'C'\{function may fail and return
|
|
.I errno
|
|
\}
|
|
.el\{method may fail and throw a
|
|
.IR DbException (3)
|
|
.if '\*[TYPE]'CXX'\{
|
|
or return
|
|
.I errno
|
|
\}
|
|
\}
|
|
for any of the errors specified for the following DB and library functions:
|
|
..
|
|
.de Ec
|
|
In addition, the
|
|
.I \\$1
|
|
.ie '\*[TYPE]'C'\{function may fail and return
|
|
.I errno
|
|
\}
|
|
.el\{method may fail and throw a
|
|
.IR DbException (3)
|
|
.ie '\*[TYPE]'CXX'\{or return
|
|
.I errno
|
|
\}
|
|
.el\{encapsulating an
|
|
.I errno
|
|
\}
|
|
\}
|
|
for the following conditions:
|
|
..
|
|
.de Ea
|
|
[EAGAIN]
|
|
A lock was unavailable.
|
|
..
|
|
.de Eb
|
|
[EBUSY]
|
|
The shared memory region was in use and the force flag was not set.
|
|
..
|
|
.de Em
|
|
[EAGAIN]
|
|
The shared memory region was locked and (repeatedly) unavailable.
|
|
..
|
|
.de Ei
|
|
[EINVAL]
|
|
An invalid flag value or parameter was specified.
|
|
..
|
|
.de Es
|
|
[EACCES]
|
|
An attempt was made to modify a read-only database.
|
|
..
|
|
.de Et
|
|
The DB_THREAD flag was specified and spinlocks are not implemented for
|
|
this architecture.
|
|
..
|
|
.de Ep
|
|
[EPERM]
|
|
Database corruption was detected.
|
|
All subsequent database calls (other than
|
|
.ie '\*[TYPE]'C'\{\
|
|
.IR DB->close )
|
|
\}
|
|
.el\{\
|
|
.IR Db::close )
|
|
\}
|
|
will return EPERM.
|
|
..
|
|
.de Ek
|
|
.if '\*[TYPE]'CXX'\{\
|
|
Methods marked as returning
|
|
.I errno
|
|
will, by default, throw an exception that encapsulates the error information.
|
|
The default error behavior can be changed, see
|
|
.IR DbException (3).
|
|
\}
|
|
..
|
|
.\" The SEE ALSO text macro
|
|
.de Sa
|
|
.\" make the line long for nroff.
|
|
.if n .ll 72
|
|
.nh
|
|
.na
|
|
.IR db_archive (1),
|
|
.IR db_checkpoint (1),
|
|
.IR db_deadlock (1),
|
|
.IR db_dump (1),
|
|
.IR db_load (1),
|
|
.IR db_recover (1),
|
|
.IR db_stat (1),
|
|
.IR db_intro (3),
|
|
.ie '\*[TYPE]'C'\{\
|
|
.IR db_appinit (3),
|
|
.IR db_cursor (3),
|
|
.IR db_dbm (3),
|
|
.IR db_internal (3),
|
|
.IR db_lock (3),
|
|
.IR db_log (3),
|
|
.IR db_mpool (3),
|
|
.IR db_open (3),
|
|
.IR db_thread (3),
|
|
.IR db_txn (3)
|
|
\}
|
|
.el\{\
|
|
.IR db_internal (3),
|
|
.IR db_thread (3),
|
|
.IR Db (3),
|
|
.IR Dbc (3),
|
|
.IR DbEnv (3),
|
|
.IR DbException (3),
|
|
.IR DbInfo (3),
|
|
.IR DbLock (3),
|
|
.IR DbLockTab (3),
|
|
.IR DbLog (3),
|
|
.IR DbLsn (3),
|
|
.IR DbMpool (3),
|
|
.if !'\*[TYPE]'JAVA'\{\
|
|
.IR DbMpoolFile (3),
|
|
\}
|
|
.IR Dbt (3),
|
|
.IR DbTxn (3),
|
|
.IR DbTxnMgr (3)
|
|
\}
|
|
.ad
|
|
.Hy
|
|
..
|
|
.\" The function header macro.
|
|
.\" This macro takes one argument:
|
|
.\" + the function name.
|
|
.de Fn
|
|
.in 2
|
|
.I \\$1
|
|
.in
|
|
..
|
|
.\" The XXX_open function text macro, for merged create/open calls.
|
|
.\" This macro takes two arguments:
|
|
.\" + the interface, e.g., "transaction region"
|
|
.\" + the prefix, e.g., "txn" (or the class name for C++, e.g., "DbTxn")
|
|
.de Co
|
|
.ie '\*[TYPE]'C'\{\
|
|
.Fn \\$2_open
|
|
The
|
|
.I \\$2_open
|
|
function copies a pointer, to the \\$1 identified by the
|
|
.B directory
|
|
.IR dir ,
|
|
into the memory location referenced by
|
|
.IR regionp .
|
|
.PP
|
|
If the
|
|
.I dbenv
|
|
argument to
|
|
.I \\$2_open
|
|
was initialized using
|
|
.IR db_appinit ,
|
|
.I dir
|
|
is interpreted as described by
|
|
.IR db_appinit (3).
|
|
\}
|
|
.el\{\
|
|
.Fn \\$2::open
|
|
The
|
|
.I \\$2::open
|
|
.ie '\*[TYPE]'CXX'\{\
|
|
method copies a pointer, to the \\$1 identified by the
|
|
.B directory
|
|
.IR dir ,
|
|
into the memory location referenced by
|
|
.IR regionp .
|
|
\}
|
|
.el\{\
|
|
method returns a \\$1 identified by the
|
|
.B directory
|
|
.IR dir .
|
|
\}
|
|
.PP
|
|
If the
|
|
.I dbenv
|
|
argument to
|
|
.I \\$2::open
|
|
was initialized using
|
|
.IR DbEnv::appinit ,
|
|
.I dir
|
|
is interpreted as described by
|
|
.IR DbEnv (3).
|
|
\}
|
|
.PP
|
|
Otherwise,
|
|
if
|
|
.I dir
|
|
is not NULL,
|
|
it is interpreted relative to the current working directory of the process.
|
|
If
|
|
.I dir
|
|
is NULL,
|
|
the following environment variables are checked in order:
|
|
``TMPDIR'', ``TEMP'', and ``TMP''.
|
|
If one of them is set,
|
|
\\$1 files are created relative to the directory it specifies.
|
|
If none of them are set, the first possible one of the following
|
|
directories is used:
|
|
.IR /var/tmp ,
|
|
.IR /usr/tmp ,
|
|
.IR /temp ,
|
|
.IR /tmp ,
|
|
.I C:/temp
|
|
and
|
|
.IR C:/tmp .
|
|
.PP
|
|
All files associated with the \\$1 are created in this directory.
|
|
This directory must already exist when
|
|
.ie '\*[TYPE]'C'\{
|
|
\\$1_open
|
|
\}
|
|
.el\{\
|
|
\\$2::open
|
|
\}
|
|
is called.
|
|
If the \\$1 already exists,
|
|
the process must have permission to read and write the existing files.
|
|
If the \\$1 does not already exist,
|
|
it is optionally created and initialized.
|
|
..
|
|
.\" The common close language macro, for discarding created regions
|
|
.\" This macro takes one argument:
|
|
.\" + the function prefix, e.g., txn (the class name for C++, e.g., DbTxn)
|
|
.de Cc
|
|
In addition, if the
|
|
.I dir
|
|
argument to
|
|
.ie '\*[TYPE]'C'\{\
|
|
.ds Va db_appinit
|
|
.ds Vo \\$1_open
|
|
.ds Vu \\$1_unlink
|
|
\}
|
|
.el\{\
|
|
.ds Va DbEnv::appinit
|
|
.ds Vo \\$1::open
|
|
.ds Vu \\$1::unlink
|
|
\}
|
|
.I \\*(Vo
|
|
was NULL
|
|
and
|
|
.I dbenv
|
|
was not initialized using
|
|
.IR \\*(Va ,
|
|
.if '\\$1'memp'\{\
|
|
or the DB_MPOOL_PRIVATE flag was set,
|
|
\}
|
|
all files created for this shared region will be removed,
|
|
as if
|
|
.I \\*(Vu
|
|
were called.
|
|
.rm Va
|
|
.rm Vo
|
|
.rm Vu
|
|
..
|
|
.\" The DB_ENV information macro.
|
|
.\" This macro takes two arguments:
|
|
.\" + the function called to open, e.g., "txn_open"
|
|
.\" + the function called to close, e.g., "txn_close"
|
|
.de En
|
|
.ie '\*[TYPE]'C'\{\
|
|
based on the
|
|
.I dbenv
|
|
argument to
|
|
.IR \\$1 ,
|
|
which is a pointer to a structure of type DB_ENV (typedef'd in <db.h>).
|
|
Applications will normally use the same DB_ENV structure (initialized
|
|
by
|
|
.IR db_appinit (3)),
|
|
as an argument to all of the subsystems in the DB package.
|
|
.PP
|
|
References to the DB_ENV structure are maintained by DB,
|
|
so it may not be discarded until the last close function,
|
|
corresponding to an open function for which it was an argument,
|
|
has returned.
|
|
In order to ensure compatibility with future releases of DB, all fields of
|
|
the DB_ENV structure that are not explicitly set should be initialized to 0
|
|
before the first time the structure is used.
|
|
Do this by declaring the structure external or static, or by calling the C
|
|
library routine
|
|
.IR bzero (3)
|
|
or
|
|
.IR memset (3).
|
|
.PP
|
|
The fields of the DB_ENV structure used by
|
|
.I \\$1
|
|
are described below.
|
|
.if '\*[TYPE]'CXX'\{\
|
|
As references to the DB_ENV structure may be maintained by
|
|
.IR \\$1 ,
|
|
it is necessary that the DB_ENV structure and memory it references be valid
|
|
until the
|
|
.I \\$2
|
|
function is called.
|
|
\}
|
|
.ie '\\$1'db_appinit'\{The
|
|
.I dbenv
|
|
argument may not be NULL.
|
|
If any of the fields of the
|
|
.I dbenv
|
|
are set to 0,
|
|
defaults appropriate for the system are used where possible.
|
|
\}
|
|
.el\{If
|
|
.I dbenv
|
|
is NULL
|
|
or any of its fields are set to 0,
|
|
defaults appropriate for the system are used where possible.
|
|
\}
|
|
.PP
|
|
The following fields in the DB_ENV structure may be initialized before calling
|
|
.IR \\$1 :
|
|
\}
|
|
.el\{\
|
|
based on which set methods have been used.
|
|
It is expected that applications will use a single DbEnv object as the
|
|
argument to all of the subsystems in the DB package.
|
|
The fields of the DbEnv object used by
|
|
.I \\$1
|
|
are described below.
|
|
As references to the DbEnv object may be maintained by
|
|
.IR \\$1 ,
|
|
it is necessary that the DbEnv object and memory it references be valid
|
|
until the object is destroyed.
|
|
.ie '\\$1'appinit'\{\
|
|
The
|
|
.I dbenv
|
|
argument may not be NULL.
|
|
If any of the fields of the
|
|
.I dbenv
|
|
are set to 0,
|
|
defaults appropriate for the system are used where possible.
|
|
\}
|
|
.el\{\
|
|
Any of the DbEnv fields that are not explicitly set will default to
|
|
appropriate values.
|
|
\}
|
|
.PP
|
|
The following fields in the DbEnv object may be initialized, using the
|
|
appropriate set method, before calling
|
|
.IR \\$1 :
|
|
\}
|
|
..
|
|
.\" The DB_ENV common fields macros.
|
|
.de Se
|
|
.if '\*[TYPE]'JAVA'\{\
|
|
.TP 5
|
|
DbErrcall db_errcall;
|
|
.ns
|
|
.TP 5
|
|
String db_errpfx;
|
|
.ns
|
|
.TP 5
|
|
int db_verbose;
|
|
The error fields of the DbEnv behave as described for
|
|
.IR DbEnv (3).
|
|
\}
|
|
.ie '\*[TYPE]'CXX'\{\
|
|
.TP 5
|
|
void *(*db_errcall)(char *db_errpfx, char *buffer);
|
|
.ns
|
|
.TP 5
|
|
FILE *db_errfile;
|
|
.ns
|
|
.TP 5
|
|
const char *db_errpfx;
|
|
.ns
|
|
.TP 5
|
|
class ostream *db_error_stream;
|
|
.ns
|
|
.TP 5
|
|
int db_verbose;
|
|
The error fields of the DbEnv behave as described for
|
|
.IR DbEnv (3).
|
|
\}
|
|
.el\{\
|
|
void *(*db_errcall)(char *db_errpfx, char *buffer);
|
|
.ns
|
|
.TP 5
|
|
FILE *db_errfile;
|
|
.ns
|
|
.TP 5
|
|
const char *db_errpfx;
|
|
.ns
|
|
.TP 5
|
|
int db_verbose;
|
|
The error fields of the DB_ENV behave as described for
|
|
.IR db_appinit (3).
|
|
.sp
|
|
\}
|
|
..
|
|
.\" The open flags.
|
|
.de Fm
|
|
The
|
|
.I flags
|
|
and
|
|
.I mode
|
|
arguments specify how files will be opened and/or created when they
|
|
don't already exist.
|
|
The flags value is specified by
|
|
.BR or 'ing
|
|
together one or more of the following values:
|
|
.Sj DB_CREATE
|
|
Create any underlying files, as necessary.
|
|
If the files do not already exist and the DB_CREATE flag is not specified,
|
|
the call will fail.
|
|
..
|
|
.\" DB_THREAD open flag macro.
|
|
.\" This macro takes two arguments:
|
|
.\" + the open function name
|
|
.\" + the object it returns.
|
|
.de Ft
|
|
.TP 5
|
|
.Sj DB_THREAD
|
|
Cause the \\$2 handle returned by the
|
|
.I \\$1
|
|
.Al function method
|
|
to be useable by multiple threads within a single address space,
|
|
i.e., to be ``free-threaded''.
|
|
.if '\*[TYPE]'JAVA'\{\
|
|
Threading is assumed in the Java API,
|
|
so no special flags are required,
|
|
and DB functions will always behave as if the DB_THREAD flag was specified.
|
|
\}
|
|
..
|
|
.\" The mode macro.
|
|
.\" This macro takes one argument:
|
|
.\" + the subsystem name.
|
|
.de Mo
|
|
All files created by the \\$1 are created with mode
|
|
.I mode
|
|
(as described in
|
|
.IR chmod (2))
|
|
and modified by the process' umask value at the time of creation (see
|
|
.IR umask (2)).
|
|
The group ownership of created files is based on the system and directory
|
|
defaults, and is not further specified by DB.
|
|
..
|
|
.\" The application exits macro.
|
|
.\" This macro takes one argument:
|
|
.\" + the application name.
|
|
.de Ex
|
|
The
|
|
.I \\$1
|
|
utility exits 0 on success, and >0 if an error occurs.
|
|
..
|
|
.\" The application -h section.
|
|
.\" This macro takes one argument:
|
|
.\" + the application name
|
|
.de Dh
|
|
DB_HOME
|
|
If the
|
|
.B \-h
|
|
option is not specified and the environment variable
|
|
.I DB_HOME
|
|
is set, it is used as the path of the database home, as described in
|
|
.IR db_appinit (3).
|
|
..
|
|
.\" The function DB_HOME ENVIRONMENT VARIABLES section.
|
|
.\" This macro takes one argument:
|
|
.\" + the open function name
|
|
.de Eh
|
|
DB_HOME
|
|
If the
|
|
.I dbenv
|
|
argument to
|
|
.I \\$1
|
|
was initialized using
|
|
.IR db_appinit ,
|
|
the environment variable DB_HOME may be used as the path of the database
|
|
home for the interpretation of the
|
|
.I dir
|
|
argument to
|
|
.IR \\$1 ,
|
|
as described in
|
|
.IR db_appinit (3).
|
|
.if \\n(.$>1 \{Specifically,
|
|
.I \\$1
|
|
is affected by the configuration string value of \\$2.\}
|
|
..
|
|
.\" The function TMPDIR ENVIRONMENT VARIABLES section.
|
|
.\" This macro takes two arguments:
|
|
.\" + the interface, e.g., "transaction region"
|
|
.\" + the prefix, e.g., "txn" (or the class name for C++, e.g., "DbTxn")
|
|
.de Ev
|
|
TMPDIR
|
|
If the
|
|
.I dbenv
|
|
argument to
|
|
.ie '\*[TYPE]'C'\{\
|
|
.ds Vo \\$2_open
|
|
\}
|
|
.el\{\
|
|
.ds Vo \\$2::open
|
|
\}
|
|
.I \\*(Vo
|
|
was NULL or not initialized using
|
|
.IR db_appinit ,
|
|
the environment variable TMPDIR may be used as the directory in which to
|
|
create the \\$1,
|
|
as described in the
|
|
.I \\*(Vo
|
|
section above.
|
|
.rm Vo
|
|
..
|
|
.\" The unused flags macro.
|
|
.de Fl
|
|
The
|
|
.I flags
|
|
parameter is currently unused, and must be set to 0.
|
|
..
|
|
.\" The no-space TP macro.
|
|
.de Nt
|
|
.br
|
|
.ns
|
|
.TP 5
|
|
..
|
|
.\" The return values of the functions macros.
|
|
.\" Rc is the standard two-value return with a suffix for more values.
|
|
.\" Ro is the standard two-value return but there were previous values.
|
|
.\" Rt is the standard two-value return, returning errno, 0, or < 0.
|
|
.\" These macros take one argument:
|
|
.\" + the routine name
|
|
.de Rc
|
|
The
|
|
.I \\$1
|
|
.ie '\*[TYPE]'C'\{function returns the value of
|
|
.I errno
|
|
on failure,
|
|
0 on success,
|
|
\}
|
|
.el\{method throws a
|
|
.IR DbException (3)
|
|
.ie '\*[TYPE]'CXX'\{or returns the value of
|
|
.I errno
|
|
on failure,
|
|
0 on success,
|
|
\}
|
|
.el\{that encapsulates an
|
|
.I errno
|
|
on failure,
|
|
\}
|
|
\}
|
|
..
|
|
.de Ro
|
|
Otherwise, the
|
|
.I \\$1
|
|
.ie '\*[TYPE]'C'\{function returns the value of
|
|
.I errno
|
|
on failure and 0 on success.
|
|
\}
|
|
.el\{method throws a
|
|
.IR DbException (3)
|
|
.ie '\*[TYPE]'CXX'\{or returns the value of
|
|
.I errno
|
|
on failure and 0 on success.
|
|
\}
|
|
.el\{that encapsulates an
|
|
.I errno
|
|
on failure,
|
|
\}
|
|
\}
|
|
..
|
|
.de Rt
|
|
The
|
|
.I \\$1
|
|
.ie '\*[TYPE]'C'\{function returns the value of
|
|
.I errno
|
|
on failure and 0 on success.
|
|
\}
|
|
.el\{method throws a
|
|
.IR DbException (3)
|
|
.ie '\*[TYPE]'CXX'\{or returns the value of
|
|
.I errno
|
|
on failure and 0 on success.
|
|
\}
|
|
.el\{that encapsulates an
|
|
.I errno
|
|
on failure.
|
|
\}
|
|
\}
|
|
..
|
|
.\" The TXN id macro.
|
|
.de Tx
|
|
.IP
|
|
If the file is being accessed under transaction protection,
|
|
the
|
|
.I txnid
|
|
parameter is a transaction ID returned from
|
|
.IR txn_begin ,
|
|
otherwise, NULL.
|
|
..
|
|
.\" The XXX_unlink function text macro.
|
|
.\" This macro takes two arguments:
|
|
.\" + the interface, e.g., "transaction region"
|
|
.\" + the prefix (for C++, this is the class name)
|
|
.de Un
|
|
.ie '\*[TYPE]'C'\{\
|
|
.ds Va db_appinit
|
|
.ds Vc \\$2_close
|
|
.ds Vo \\$2_open
|
|
.ds Vu \\$2_unlink
|
|
\}
|
|
.el\{\
|
|
.ds Va DbEnv::appinit
|
|
.ds Vc \\$2::close
|
|
.ds Vo \\$2::open
|
|
.ds Vu \\$2::unlink
|
|
\}
|
|
.Fn \\*(Vu
|
|
The
|
|
.I \\*(Vu
|
|
.Al function method
|
|
destroys the \\$1 identified by the directory
|
|
.IR dir ,
|
|
removing all files used to implement the \\$1.
|
|
.ie '\\$2'log' \{(The log files themselves and the directory
|
|
.I dir
|
|
are not removed.)\}
|
|
.el \{(The directory
|
|
.I dir
|
|
is not removed.)\}
|
|
If there are processes that have called
|
|
.I \\*(Vo
|
|
without calling
|
|
.I \\*(Vc
|
|
(i.e., there are processes currently using the \\$1),
|
|
.I \\*(Vu
|
|
will fail without further action,
|
|
unless the force flag is set,
|
|
in which case
|
|
.I \\*(Vu
|
|
will attempt to remove the \\$1 files regardless of any processes
|
|
still using the \\$1.
|
|
.PP
|
|
The result of attempting to forcibly destroy the region when a process
|
|
has the region open is unspecified.
|
|
Processes using a shared memory region maintain an open file descriptor
|
|
for it.
|
|
On UNIX systems, the region removal should succeed
|
|
and processes that have already joined the region should continue to
|
|
run in the region without change,
|
|
however processes attempting to join the \\$1 will either fail or
|
|
attempt to create a new region.
|
|
On other systems, e.g., WNT, where the
|
|
.IR unlink (2)
|
|
system call will fail if any process has an open file descriptor
|
|
for the file,
|
|
the region removal will fail.
|
|
.PP
|
|
In the case of catastrophic or system failure,
|
|
database recovery must be performed (see
|
|
.IR db_recover (1)
|
|
or the DB_RECOVER and DB_RECOVER_FATAL flags to
|
|
.IR \\*(Va (3)).
|
|
Alternatively, if recovery is not required because no database state is
|
|
maintained across failures,
|
|
it is possible to clean up a \\$1 by removing all of the
|
|
files in the directory specified to the
|
|
.I \\*(Vo
|
|
.Al function, method,
|
|
as \\$1 files are never created in any directory other than the one
|
|
specified to
|
|
.IR \\*(Vo .
|
|
Note, however,
|
|
that this has the potential to remove files created by the other DB
|
|
subsystems in this database environment.
|
|
.PP
|
|
.Rt \\*(Vu
|
|
.rm Va
|
|
.rm Vo
|
|
.rm Vu
|
|
.rm Vc
|
|
..
|
|
.\" Signal paragraph for standard utilities.
|
|
.\" This macro takes one argument:
|
|
.\" + the utility name.
|
|
.de Si
|
|
The
|
|
.I \\$1
|
|
utility attaches to DB shared memory regions.
|
|
In order to avoid region corruption,
|
|
it should always be given the chance to detach and exit gracefully.
|
|
To cause
|
|
.I \\$1
|
|
to clean up after itself and exit,
|
|
send it an interrupt signal (SIGINT).
|
|
..
|
|
.\" Logging paragraph for standard utilities.
|
|
.\" This macro takes one argument:
|
|
.\" + the utility name.
|
|
.de Pi
|
|
.B \-L
|
|
Log the execution of the \\$1 utility to the specified file in the
|
|
following format, where ``###'' is the process ID, and the date is
|
|
the time the utility starting running.
|
|
.sp
|
|
\\$1: ### Wed Jun 15 01:23:45 EDT 1995
|
|
.sp
|
|
This file will be removed if the \\$1 utility exits gracefully.
|
|
..
|
|
.\" Malloc paragraph.
|
|
.\" This macro takes one argument:
|
|
.\" + the allocated object
|
|
.de Ma
|
|
.if !'\*[TYPE]'JAVA'\{\
|
|
\\$1 are created in allocated memory.
|
|
If
|
|
.I db_malloc
|
|
is non-NULL,
|
|
it is called to allocate the memory,
|
|
otherwise,
|
|
the library function
|
|
.IR malloc (3)
|
|
is used.
|
|
The function
|
|
.I db_malloc
|
|
must match the calling conventions of the
|
|
.IR malloc (3)
|
|
library routine.
|
|
Regardless,
|
|
the caller is responsible for deallocating the returned memory.
|
|
To deallocate the returned memory,
|
|
free each returned memory pointer;
|
|
pointers inside the memory do not need to be individually freed.
|
|
\}
|
|
..
|
|
.\" Underlying function paragraph.
|
|
.\" This macro takes two arguments:
|
|
.\" + the function name
|
|
.\" + the utility name
|
|
.de Uf
|
|
The
|
|
.I \\$1
|
|
.Al function method
|
|
is the underlying function used by the
|
|
.IR \\$2 (1)
|
|
utility.
|
|
See the source code for the
|
|
.I \\$2
|
|
utility for an example of using
|
|
.I \\$1
|
|
in a UNIX environment.
|
|
..
|
|
.\" Underlying function paragraph, for C++.
|
|
.\" This macro takes three arguments:
|
|
.\" + the C++ method name
|
|
.\" + the function name for C
|
|
.\" + the utility name
|
|
.de Ux
|
|
The
|
|
.I \\$1
|
|
method is based on the C
|
|
.I \\$2
|
|
function, which
|
|
is the underlying function used by the
|
|
.IR \\$3 (1)
|
|
utility.
|
|
See the source code for the
|
|
.I \\$3
|
|
utility for an example of using
|
|
.I \\$2
|
|
in a UNIX environment.
|
|
..
|
|
.TH DB_MPOOL 3 "May 10, 1998"
|
|
.UC 7
|
|
.SH NAME
|
|
db_mpool \- shared memory buffer pool
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.ft B
|
|
#include <db.h>
|
|
|
|
int
|
|
memp_open(char *dir,
|
|
.ti +5
|
|
u_int32_t flags, int mode, DB_ENV *dbenv, DB_MPOOL **regionp);
|
|
|
|
int
|
|
memp_close(DB_MPOOL *mp);
|
|
|
|
int
|
|
memp_fopen(DB_MPOOL *mp, char *file, u_int32_t flags, int mode,
|
|
.ti +5
|
|
size_t pagesize, DB_MPOOL_FINFO *finfop, DB_MPOOLFILE **mpf);
|
|
|
|
int
|
|
memp_fclose(DB_MPOOLFILE *mpf);
|
|
|
|
int
|
|
memp_fget(DB_MPOOLFILE *mpf,
|
|
.ti +5
|
|
db_pgno_t *pgnoaddr, u_int32_t flags, void **pagep);
|
|
|
|
int
|
|
memp_fput(DB_MPOOLFILE *mpf, void *pgaddr, u_int32_t flags);
|
|
|
|
int
|
|
memp_fset(DB_MPOOLFILE *mpf, void *pgaddr, u_int32_t flags);
|
|
|
|
int
|
|
memp_fsync(DB_MPOOLFILE *mpf);
|
|
|
|
int
|
|
memp_unlink(const char *dir, int force, DB_ENV *);
|
|
|
|
int
|
|
memp_register(DB_MPOOL *mp, int ftype,
|
|
.ti +5
|
|
int (*pgin)(db_pgno_t pgno, void *pgaddr, DBT *pgcookie),
|
|
.ti +5
|
|
int (*pgout)(db_pgno_t pgno, void *pgaddr, DBT *pgcookie));
|
|
|
|
int
|
|
memp_trickle(DB_MPOOL *mp, int pct, int *nwrotep);
|
|
|
|
int
|
|
memp_sync(DB_MPOOL *mp, LSN *lsn);
|
|
|
|
int
|
|
memp_stat(DB_MPOOL *mp, DB_MPOOL_STAT **gsp,
|
|
.ti +5
|
|
DB_MPOOL_FSTAT *(*fsp)[], void *(*db_malloc)(size_t));
|
|
.ft R
|
|
.fi
|
|
.SH DESCRIPTION
|
|
.Gn
|
|
.PP
|
|
This manual page describes the specific details of the memory pool interface.
|
|
.PP
|
|
The
|
|
.I db_mpool
|
|
functions are the library interface intended to provide general-purpose,
|
|
page-oriented buffer management of one or more files.
|
|
While designed to work with the other DB functions, these functions are
|
|
also useful for more general purposes.
|
|
The memory pools (DB_MPOOL's) are referred to in this document as
|
|
simply ``pools''.
|
|
Pools may be shared between processes.
|
|
Pools are usually filled by pages from one or more files (DB_MPOOLFILE's).
|
|
Pages in the pool are replaced in LRU (least-recently-used) order,
|
|
with each new page replacing the page that has been unused the longest.
|
|
Pages retrieved from the pool using
|
|
.I memp_fget
|
|
are ``pinned'' in the pool, by default,
|
|
until they are returned to the pool's control using the
|
|
.I memp_fput
|
|
function.
|
|
.PP
|
|
.Co "memory pool" memp
|
|
.PP
|
|
.Fm
|
|
.TP 5
|
|
DB_MPOOL_PRIVATE
|
|
Create a private MPOOL that is not shared with any other process (although
|
|
it may be shared with other threads).
|
|
.TP 5
|
|
DB_NOMMAP
|
|
Always copy files in this memory pool into the local cache instead of mapping
|
|
them into process memory (see the description of the
|
|
.I mp_mmapsize
|
|
field of the DB_ENV structure for further information).
|
|
.Ft memp_open DB_MPOOL
|
|
.PP
|
|
.Mo "memory pool subsystem (other than files created by the \fImemp_fopen\fP function, which are separately specified)"
|
|
.PP
|
|
The memory pool subsystem is configured
|
|
.En "memp_open" "memp_closed"
|
|
.TP 5
|
|
.Se
|
|
.TP 5
|
|
size_t mp_mmapsize;
|
|
Files that are opened read-only in the pool (and that satisfy a few other
|
|
criteria) are, by default,
|
|
mapped into the process address space instead of being copied into the local
|
|
cache.
|
|
This can result in better-than-usual performance,
|
|
as available virtual memory is normally much larger than the local cache,
|
|
and page faults are faster than page copying on many systems.
|
|
However,
|
|
in the presence of limited virtual memory it can cause resource starvation,
|
|
and in the presence of large databases,
|
|
it can result in immense process sizes.
|
|
If
|
|
.I mp_mmapsize
|
|
is non-zero,
|
|
it specifies the maximum file size, in bytes,
|
|
for a file to be mapped into the process address space.
|
|
By default,
|
|
it is set to 10Mb.
|
|
.TP 5
|
|
size_t mp_size;
|
|
The suggested size of the pool, in bytes.
|
|
This should be the size of the normal working data set of the application,
|
|
with some small amount of additional memory for unusual situations.
|
|
(Note,
|
|
the working set is not the same as the number of simultaneously referenced
|
|
pages,
|
|
and should be quite a bit larger!)
|
|
The default cache size is 128K bytes (16 8K byte pages),
|
|
and may not be less than 20K bytes.
|
|
.PP
|
|
.Rt memp_open
|
|
.PP
|
|
.Fn memp_close
|
|
The
|
|
.I memp_close
|
|
function closes the pool indicated by the DB_MPOOL pointer
|
|
.IR mp ,
|
|
as returned by
|
|
.IR memp_open .
|
|
This function does not imply a call to
|
|
.IR memp_fsync ,
|
|
but does imply a call to
|
|
.I memp_fclose
|
|
for any remaining open DB_MPOOLFILE pointers returned to this process by
|
|
calls to
|
|
.IR memp_fopen .
|
|
.PP
|
|
.Cc memp
|
|
.PP
|
|
When multiple threads are using the DB_MPOOL handle concurrently,
|
|
only a single thread may call the
|
|
.I memp_close
|
|
function.
|
|
.PP
|
|
.Rt memp_close
|
|
.PP
|
|
.Fn memp_fopen
|
|
The
|
|
.I memp_fopen
|
|
function opens a file in the pool specified by the DB_MPOOL argument,
|
|
copying the DB_MPOOLFILE pointer representing it into the memory
|
|
location referenced by
|
|
.IR mpf .
|
|
.PP
|
|
The
|
|
.I file
|
|
argument is the name of the file to be opened.
|
|
If
|
|
.I file
|
|
is NULL,
|
|
a private file is created that cannot be shared with any other process
|
|
(although it may be shared with other threads).
|
|
.PP
|
|
.Fm
|
|
.TP 5
|
|
DB_NOMMAP
|
|
Always copy this file into the local cache instead of mapping it into
|
|
process memory (see the description of the
|
|
.I mp_mmapsize
|
|
field of the DB_ENV structure for further information).
|
|
.TP 5
|
|
DB_RDONLY
|
|
Open any underlying files for reading only.
|
|
Any attempt to write the file using the pool functions will fail,
|
|
regardless of the actual permissions of the file.
|
|
.PP
|
|
.Mo "function \fImemp_fopen\fP"
|
|
.PP
|
|
The
|
|
.I pagesize
|
|
argument is the size, in bytes,
|
|
of the unit of transfer between the application and the pool,
|
|
although it is not necessarily the unit of transfer between the pool and
|
|
the source file.
|
|
.PP
|
|
Files opened in the pool may be further configured based on the
|
|
.I finfop
|
|
argument to
|
|
.IR memp_fopen ,
|
|
which is a pointer to a structure of type DB_MPOOL_FINFO (typedef'd
|
|
in <db.h>).
|
|
No references to the
|
|
.I finfop
|
|
structure are maintained by DB, so it may be discarded when the
|
|
.I memp_fopen
|
|
function returns.
|
|
In order to ensure compatibility with future releases of DB, all fields
|
|
of the DB_MPOOL_FINFO 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_MPOOL_FINFO structure used by
|
|
.I memp_fopen
|
|
are described below.
|
|
If
|
|
.I finfop
|
|
is NULL or any of its fields are set to their default value,
|
|
defaults appropriate for the system are used.
|
|
.TP 5
|
|
int ftype;
|
|
The
|
|
.I ftype
|
|
field should be the same as a
|
|
.I ftype
|
|
argument previously specified to the
|
|
.I memp_register
|
|
function,
|
|
unless no input or output processing of the file's pages are necessary,
|
|
in which case it should be 0.
|
|
(See the description of the
|
|
.I memp_register
|
|
function for more information.)
|
|
.TP 5
|
|
DBT *pgcookie;
|
|
The
|
|
.I pgcookie
|
|
field contains the byte string that is passed to the
|
|
.I pgin
|
|
and
|
|
.I pgout
|
|
functions for this file, if any.
|
|
If no
|
|
.I pgin
|
|
or
|
|
.I pgout
|
|
functions are specified, the
|
|
.I pgcookie
|
|
field should be NULL.
|
|
(See the description of the
|
|
.I memp_register
|
|
function for more information.)
|
|
.TP 5
|
|
u_int8_t *fileid;
|
|
The
|
|
.I fileid
|
|
field is a unique identifier for the file.
|
|
The mpool
|
|
functions must be able to uniquely identify files in order that multiple
|
|
processes sharing a file will correctly share its underlying pages.
|
|
Normally, the
|
|
.I fileid
|
|
field should be NULL and the mpool functions will use the file's
|
|
device and inode numbers (see
|
|
.IR stat (2))
|
|
for this purpose.
|
|
On some filesystems, (e.g., FAT or NFS) file device and inode numbers are
|
|
not necessarily unique across system reboots.
|
|
.ft B
|
|
Applications wanting to maintain a shared memory buffer pool across system
|
|
reboots, where the pool contains pages from files stored on such filesystems,
|
|
must specify a unique file identifier to the
|
|
.I memp_fopen
|
|
call and each process opening or registering the file must provide the same
|
|
unique identifier.
|
|
.ft R
|
|
If the
|
|
.I fileid
|
|
field is non-NULL,
|
|
it must reference a DB_FILE_ID_LEN (as defined in <db.h>) length array of
|
|
bytes that will be used to uniquely identify the file.
|
|
This should not be necessary for most applications.
|
|
Specifically, it is not necessary if the memory pool is re-instantiated after
|
|
each system reboot, the application is using the DB access methods instead of
|
|
calling the pool functions explicitly, or the files in the memory pool are
|
|
stored on filesystems where the file device and inode numbers do not change
|
|
across system reboots.
|
|
.TP 5
|
|
int32_t lsn_offset;
|
|
The
|
|
.I lsn_offset
|
|
field is the zero-based byte offset in the page of the page's log sequence
|
|
number (LSN),
|
|
or \-1 if no LSN offset is specified.
|
|
(See the description of the
|
|
.I memp_sync
|
|
function for more information.)
|
|
.TP 5
|
|
u_int32_t clear_len;
|
|
The
|
|
.I clear_len
|
|
field is the number of initial bytes in a page that should be set to zero
|
|
when the page is created as a result of the DB_MPOOL_CREATE or DB_MPOOL_NEW
|
|
flags being specified to
|
|
.IR memp_fget .
|
|
If
|
|
.I finfop
|
|
is NULL or
|
|
.I clear_len
|
|
is 0, the entire page is cleared.
|
|
.PP
|
|
.Rt memp_fopen
|
|
.PP
|
|
.Fn memp_fclose
|
|
The
|
|
.I memp_fclose
|
|
function closes the source file indicated by the DB_MPOOLFILE pointer
|
|
.IR mpf .
|
|
This function does not imply a call to
|
|
.IR memp_fsync ,
|
|
i.e. no pages are written to the source file as as a result of calling
|
|
.IR memp_fclose .
|
|
.PP
|
|
In addition,
|
|
if the
|
|
.I file
|
|
argument to
|
|
.I memp_fopen
|
|
was NULL,
|
|
any underlying files created for this DB_MPOOLFILE will be removed.
|
|
.PP
|
|
.Rt memp_fclose
|
|
.PP
|
|
.Fn memp_fget
|
|
The
|
|
.I memp_fget
|
|
function copies a pointer to the page with the page number specified by
|
|
.IR pgnoaddr ,
|
|
from the source file specified by the DB_MPOOLFILE pointer
|
|
.IR mpf ,
|
|
into the memory location referenced by
|
|
.IR pagep .
|
|
If the page does not exist or cannot be retrieved,
|
|
.I memp_fget
|
|
will fail.
|
|
.PP
|
|
The returned page is size_t type aligned.
|
|
.PP
|
|
.ft B
|
|
Page numbers begin at 0, e.g., the first page in the file is page number 0,
|
|
not page number 1.
|
|
.ft R
|
|
.PP
|
|
The
|
|
.I flags
|
|
argument is specified by
|
|
.BR or 'ing
|
|
together one or more of the following values:
|
|
.TP 5
|
|
DB_MPOOL_CREATE
|
|
If the specified page does not exist, create it.
|
|
In this case, the
|
|
.I pgin
|
|
function, if specified, is called.
|
|
.TP 5
|
|
DB_MPOOL_LAST
|
|
Return the last page of the source file and copy its page number
|
|
to the location referenced by
|
|
.IR pgnoaddr .
|
|
.TP 5
|
|
DB_MPOOL_NEW
|
|
Create a new page in the file and copy its page number to the location
|
|
referenced by
|
|
.IR pgnoaddr .
|
|
In this case, the
|
|
.I pgin
|
|
function, if specified, is not called.
|
|
.PP
|
|
The DB_MPOOL_CREATE, DB_MPOOL_LAST and DB_MPOOL_NEW flags are mutually
|
|
exclusive.
|
|
.PP
|
|
Created pages have all their bytes set to 0, unless otherwise specified
|
|
when the file was opened.
|
|
.PP
|
|
All pages returned by
|
|
.I memp_fget
|
|
will be retained (i.e. ``pinned'') in the pool until a subsequent call to
|
|
.IR memp_fput .
|
|
.PP
|
|
.Rt memp_fget
|
|
.PP
|
|
.Fn memp_fput
|
|
The
|
|
.I memp_fput
|
|
function indicates that the page referenced by
|
|
.I pgaddr
|
|
can be evicted from the pool.
|
|
.I Pgaddr
|
|
must be an address previously returned by
|
|
.IR memp_fget .
|
|
.PP
|
|
The
|
|
.I flags
|
|
argument is specified by
|
|
.BR or 'ing
|
|
together one or more of the following values:
|
|
.TP 5
|
|
DB_MPOOL_CLEAN
|
|
Clear any previously set modification information (i.e.,
|
|
don't bother writing the page back to the source file).
|
|
.TP 5
|
|
DB_MPOOL_DIRTY
|
|
The page has been modified and must be written to the source file
|
|
before being evicted from the pool.
|
|
.TP 5
|
|
DB_MPOOL_DISCARD
|
|
The page is unlikely to be useful in the near future,
|
|
and should be discarded before other pages in the pool.
|
|
.PP
|
|
The DB_MPOOL_CLEAN and DB_MPOOL_DIRTY flags are mutually exclusive.
|
|
.PP
|
|
.Rt memp_fput
|
|
.PP
|
|
.Fn memp_fset
|
|
The
|
|
.I memp_fset
|
|
function sets the flags associated with the page referenced by
|
|
.I pgaddr
|
|
without unpinning it from the pool.
|
|
.I Pgaddr
|
|
must be an address previously returned by
|
|
.IR memp_fget .
|
|
The
|
|
.I flags
|
|
argument to
|
|
.I memp_fset
|
|
is specified by
|
|
.BR or 'ing
|
|
together one or more of the values specified as flags for the
|
|
.I memp_fput
|
|
call.
|
|
.PP
|
|
.Rt memp_fset
|
|
.PP
|
|
.Fn memp_fsync
|
|
The
|
|
.I memp_fsync
|
|
function writes all pages associated with the DB_MPOOLFILE pointer
|
|
.IR mpf ,
|
|
that were marked as modified using
|
|
.I memp_fput
|
|
or
|
|
.IR memp_fset ,
|
|
back to the source file.
|
|
If any of the modified pages are also pinned (i.e.,
|
|
currently referenced by this or another process)
|
|
.I memp_fsync
|
|
will ignore them.
|
|
.PP
|
|
.Rc memp_fsync
|
|
and DB_INCOMPLETE if there were pages which were modified but which
|
|
.I memp_fsync
|
|
was unable to write.
|
|
.PP
|
|
.Un "memory pool" memp
|
|
.PP
|
|
.Fn memp_register
|
|
The
|
|
.I memp_register
|
|
function registers page-in and page-out functions for files of type
|
|
.I ftype
|
|
in the specified pool.
|
|
.PP
|
|
If the
|
|
.I pgin
|
|
function is non-NULL,
|
|
it is called each time a page is read into the memory pool from a file
|
|
of type
|
|
.IR ftype ,
|
|
or a page is created for a file of type
|
|
.I ftype
|
|
(see the DB_MPOOL_CREATE flag for the
|
|
.I memp_fget
|
|
function).
|
|
If the
|
|
.I pgout
|
|
function is non-NULL,
|
|
it is called each time a page is written to a file of type
|
|
.IR ftype .
|
|
.PP
|
|
Both the
|
|
.I pgin
|
|
and
|
|
.I pgout
|
|
functions are called with the page number,
|
|
a pointer to the page being read or written,
|
|
and any argument
|
|
.I pgcookie
|
|
that was specified to the
|
|
.I memp_fopen
|
|
function when the file was opened.
|
|
The
|
|
.I pgin
|
|
and
|
|
.I pgout
|
|
functions should return 0 on success,
|
|
and an applicable non-zero
|
|
.I errno
|
|
value on failure,
|
|
in which case the
|
|
.I db_mpool
|
|
function calling it will also fail,
|
|
returning that
|
|
.I errno
|
|
value.
|
|
.PP
|
|
The purpose of the
|
|
.I memp_register
|
|
function is to support processing when pages are entered into,
|
|
or flushed from,
|
|
the pool.
|
|
A file type must be specified to make it possible for unrelated
|
|
threads or processes,
|
|
that are sharing a pool,
|
|
to evict each other's pages from the pool.
|
|
Applications should call
|
|
.IR memp_register ,
|
|
during initialization,
|
|
for each type of file requiring input or output processing that will be
|
|
sharing the underlying pool.
|
|
(No registry is necessary for the standard access method types,
|
|
btree, hash and recno, as
|
|
.IR db_open (3)
|
|
registers them separately.)
|
|
.PP
|
|
If a thread or process does not call
|
|
.I memp_register
|
|
for a file type,
|
|
it is impossible for it to evict pages for any file requiring input or
|
|
output processing from the pool.
|
|
For this reason,
|
|
.I memp_register
|
|
should always be called by each application sharing a pool for each type of
|
|
file included in the pool,
|
|
regardless of whether or not the application itself uses files of that type.
|
|
.PP
|
|
There are no standard values for
|
|
.IR ftype ,
|
|
.IR pgin ,
|
|
.I pgout
|
|
and
|
|
.IR pgcookie ,
|
|
except that the
|
|
.I ftype
|
|
value for a file must be a non-zero positive number,
|
|
as negative numbers are reserved for internal use by the DB library.
|
|
For this reason,
|
|
applications sharing a pool must coordinate their values amongst themselves.
|
|
.PP
|
|
.Rt memp_register
|
|
.PP
|
|
.Fn memp_trickle
|
|
The
|
|
.I memp_trickle
|
|
function ensures that at least
|
|
.I pct
|
|
percent of the pages in the shared memory pool are clean by writing dirty
|
|
pages to their backing files.
|
|
If the
|
|
.I nwrotep
|
|
argument is non-NULL,
|
|
the number of pages that were written to reach the correct percentage is
|
|
returned in the memory location it references.
|
|
.PP
|
|
The purpose of the
|
|
.I memp_trickle
|
|
function is to enable a memory pool manager to ensure that a page is
|
|
always available for reading in new information without having to wait
|
|
for a write.
|
|
.PP
|
|
.Rt memp_trickle
|
|
.PP
|
|
.Fn memp_sync
|
|
The
|
|
.I memp_sync
|
|
function ensures that all the modified pages in the pool with log sequence
|
|
numbers (LSNs) less than the
|
|
.I lsn
|
|
argument are written to disk.
|
|
.PP
|
|
.Rc memp_sync
|
|
and DB_INCOMPLETE if there were pages which need to be written but which
|
|
.I memp_sync
|
|
was unable to write immediately.
|
|
In addition,
|
|
if
|
|
.I memp_sync
|
|
returns success,
|
|
the value of
|
|
.I lsn
|
|
will be overwritten with the largest LSN from any page which was written by
|
|
.I memp_sync
|
|
to satisfy this request.
|
|
.PP
|
|
The purpose of the
|
|
.I memp_sync
|
|
function is to enable a transaction manager to ensure,
|
|
as part of a checkpoint,
|
|
that all pages modified by a certain time have been written to disk.
|
|
Pages in the pool which cannot be written back to disk immediately (e.g.,
|
|
are currently pinned) are written to disk as soon as it is possible to do
|
|
so.
|
|
The expected behavior of the transaction manager is to call the
|
|
.I memp_sync
|
|
function and then,
|
|
if the return indicates that some pages could not be written immediately,
|
|
to wait briefly and retry again with the same LSN until the
|
|
.I memp_sync
|
|
function returns that all pages have been written.
|
|
.PP
|
|
To support the
|
|
.I memp_sync
|
|
functionality,
|
|
it is necessary that the pool functions know the location of the LSN on
|
|
the page for each file type.
|
|
This location should be specified when the file is opened using the
|
|
.I memp_fopen
|
|
function.
|
|
(Note, it is not required that the LSN be aligned on the page in any way.)
|
|
.PP
|
|
.Fn memp_stat
|
|
The
|
|
.I memp_stat
|
|
function creates statistical structures and copies pointers to them into
|
|
user-specified memory locations.
|
|
The statistics include the number of files participating in the pool,
|
|
the active pages in the pool,
|
|
and information as to how effective the cache has been.
|
|
.PP
|
|
.Ma "Statistical structures"
|
|
.PP
|
|
If
|
|
.I gsp
|
|
is non-NULL, the global statistics for the memory pool
|
|
.I mp
|
|
are copied into the memory location it references.
|
|
The global statistics are stored in a structure of type
|
|
DB_MPOOL_STAT (typedef'd in <db.h>).
|
|
.PP
|
|
The following DB_MPOOL_STAT fields will be filled in:
|
|
.TP 5
|
|
u_int32_t st_refcnt;
|
|
The number of references to the region.
|
|
.Nt
|
|
u_int32_t st_regsize;
|
|
The size of the region.
|
|
.Nt
|
|
size_t st_cachesize;
|
|
Cache size in bytes.
|
|
.Nt
|
|
u_int32_t st_cache_hit;
|
|
Requested pages found in the cache.
|
|
.Nt
|
|
u_int32_t st_cache_miss;
|
|
Requested pages not found in the cache.
|
|
.Nt
|
|
u_int32_t st_map;
|
|
Requested pages mapped into the process' address space (there is no
|
|
available information as to whether or not this request caused disk I/O,
|
|
although examining the application page fault rate may be helpful).
|
|
.Nt
|
|
u_int32_t st_page_create;
|
|
Pages created in the cache.
|
|
.Nt
|
|
u_int32_t st_page_in;
|
|
Pages read into the cache.
|
|
.Nt
|
|
u_int32_t st_page_out;
|
|
Pages written from the cache to the backing file.
|
|
.Nt
|
|
u_int32_t st_ro_evict;
|
|
Clean pages forced from the cache.
|
|
.Nt
|
|
u_int32_t st_rw_evict;
|
|
Dirty pages forced from the cache.
|
|
.Nt
|
|
u_int32_t st_hash_buckets;
|
|
Number of hash buckets in buffer hash table.
|
|
.Nt
|
|
u_int32_t st_hash_searches;
|
|
Total number of buffer hash table lookups.
|
|
.Nt
|
|
u_int32_t st_hash_longest;
|
|
The longest chain ever encountered in buffer hash table lookups.
|
|
.Nt
|
|
u_int32_t st_hash_examined;
|
|
Total number of hash elements traversed during hash table lookups.
|
|
.Nt
|
|
u_int32_t st_page_clean;
|
|
Clean pages currently in the cache.
|
|
.Nt
|
|
u_int32_t st_page_dirty;
|
|
Dirty pages currently in the cache.
|
|
.Nt
|
|
u_int32_t st_page_trickle;
|
|
Dirty pages written using the
|
|
.I memp_trickle
|
|
interface.
|
|
.Nt
|
|
u_int32_t st_region_wait;
|
|
The number of times that a thread of control was forced to wait before
|
|
obtaining the region lock.
|
|
.Nt
|
|
u_int32_t st_region_nowait;
|
|
The number of times that a thread of control was able to obtain
|
|
the region lock without waiting.
|
|
.PP
|
|
If
|
|
.I fsp
|
|
is non-NULL,
|
|
a pointer to a NULL-terminated variable length array of statistics for
|
|
individual files,
|
|
in the memory pool
|
|
.IR mp ,
|
|
is copied into the memory location it references.
|
|
If no individual files currently exist in the memory pool,
|
|
.I fsp
|
|
will be set to NULL.
|
|
.PP
|
|
The per-file statistics are stored in structures of type
|
|
DB_MPOOL_FSTAT (typedef'd in <db.h>).
|
|
The following DB_MPOOL_FSTAT fields will be filled in for each file in the
|
|
pool, i.e., each element of the array:
|
|
.TP 5
|
|
char *file_name;
|
|
The name of the file.
|
|
.Nt
|
|
size_t st_pagesize;
|
|
Page size in bytes.
|
|
.Nt
|
|
u_int32_t st_cache_hit;
|
|
Requested pages found in the cache.
|
|
.Nt
|
|
u_int32_t st_cache_miss;
|
|
Requested pages not found in the cache.
|
|
.Nt
|
|
u_int32_t st_map;
|
|
Requested pages mapped into the process' address space.
|
|
.Nt
|
|
u_int32_t st_page_create;
|
|
Pages created in the cache.
|
|
.Nt
|
|
u_int32_t st_page_in;
|
|
Pages read into the cache.
|
|
.Nt
|
|
u_int32_t st_page_out;
|
|
Pages written from the cache to the backing file.
|
|
.PP
|
|
.Rt memp_stat
|
|
.SH "ENVIRONMENT VARIABLES"
|
|
The following environment variables affect the execution of
|
|
.IR db_mpool :
|
|
.TP 5
|
|
.Eh memp_open
|
|
.TP 5
|
|
.Ev "memory pool" memp
|
|
.SH ERRORS
|
|
.Ee memp_open
|
|
.na
|
|
.Nh
|
|
DBmemp->pgin(3),
|
|
DBmemp->pgout(3),
|
|
close(2),
|
|
db_version(3),
|
|
fcntl(2),
|
|
fflush(3),
|
|
fsync(2),
|
|
log_compare(3),
|
|
log_flush(3),
|
|
lseek(2),
|
|
malloc(3),
|
|
memcmp(3),
|
|
memcpy(3),
|
|
memp_close(3),
|
|
memp_unlink(3),
|
|
memset(3),
|
|
mmap(2),
|
|
munmap(2),
|
|
open(2),
|
|
sigfillset(3),
|
|
sigprocmask(2),
|
|
stat(2),
|
|
strcpy(3),
|
|
strdup(3),
|
|
strerror(3),
|
|
strlen(3),
|
|
time(3),
|
|
unlink(2),
|
|
and
|
|
write(2).
|
|
.Hy
|
|
.ad
|
|
.PP
|
|
.Ec memp_open
|
|
.TP 5
|
|
.Em
|
|
.TP 5
|
|
.Ei
|
|
.sp
|
|
.Et
|
|
.sp
|
|
A NULL pathname was specified without the DB_MPOOL_PRIVATE flag.
|
|
.sp
|
|
The specified cache size was impossibly small.
|
|
.PP
|
|
.Ee memp_close
|
|
.na
|
|
.Nh
|
|
close(2),
|
|
fcntl(2),
|
|
fflush(3),
|
|
memp_fclose(3),
|
|
munmap(2),
|
|
and
|
|
strerror(3).
|
|
.Hy
|
|
.ad
|
|
.PP
|
|
.Ee memp_fopen
|
|
.na
|
|
.Nh
|
|
DBmemp->pgin(3),
|
|
DBmemp->pgout(3),
|
|
close(2),
|
|
fcntl(2),
|
|
fflush(3),
|
|
fsync(2),
|
|
log_compare(3),
|
|
log_flush(3),
|
|
lseek(2),
|
|
malloc(3),
|
|
memcmp(3),
|
|
memcpy(3),
|
|
memset(3),
|
|
mmap(2),
|
|
open(2),
|
|
sigfillset(3),
|
|
sigprocmask(2),
|
|
stat(2),
|
|
strcpy(3),
|
|
strdup(3),
|
|
strerror(3),
|
|
strlen(3),
|
|
time(3),
|
|
unlink(2),
|
|
and
|
|
write(2).
|
|
.Hy
|
|
.ad
|
|
.PP
|
|
.Ec memp_fopen
|
|
.TP 5
|
|
.Ei
|
|
.sp
|
|
The file has already been entered into the pool,
|
|
and the
|
|
.I pagesize
|
|
value is not the same as when the file was entered into the pool,
|
|
or the length of the file is not zero or a multiple of the
|
|
.IR pagesize .
|
|
.sp
|
|
The DB_RDONLY flag was specified for an in-memory pool.
|
|
.PP
|
|
.Ee memp_fclose
|
|
.na
|
|
.Nh
|
|
close(2),
|
|
fcntl(2),
|
|
fflush(3),
|
|
munmap(2),
|
|
and
|
|
strerror(3).
|
|
.Hy
|
|
.ad
|
|
.PP
|
|
.Ee memp_fget
|
|
.na
|
|
.Nh
|
|
DBmemp->pgin(3),
|
|
DBmemp->pgout(3),
|
|
close(2),
|
|
fcntl(2),
|
|
fflush(3),
|
|
fsync(2),
|
|
log_compare(3),
|
|
log_flush(3),
|
|
lseek(2),
|
|
malloc(3),
|
|
memcmp(3),
|
|
memcpy(3),
|
|
memset(3),
|
|
mmap(2),
|
|
open(2),
|
|
read(2),
|
|
sigfillset(3),
|
|
sigprocmask(2),
|
|
stat(2),
|
|
strcpy(3),
|
|
strdup(3),
|
|
strerror(3),
|
|
strlen(3),
|
|
time(3),
|
|
unlink(2),
|
|
and
|
|
write(2).
|
|
.Hy
|
|
.ad
|
|
.PP
|
|
.Ec memp_fget
|
|
.TP 5
|
|
[EAGAIN]
|
|
The page reference count has overflowed.
|
|
(This should never happen unless there's a bug in the application.)
|
|
.TP 5
|
|
.Ei
|
|
.sp
|
|
The DB_MPOOL_NEW flag was set and the source file was not opened for writing.
|
|
.sp
|
|
The requested page does not exist and DB_MPOOL_CREATE was not set.
|
|
.sp
|
|
More than one of DB_MPOOL_CREATE, DB_MPOOL_LAST and DB_MPOOL_NEW was set.
|
|
.TP 5
|
|
[ENOMEM]
|
|
The cache is full and no more pages will fit in the pool.
|
|
.PP
|
|
.Ee memp_fput
|
|
.na
|
|
.Nh
|
|
DBmemp->pgin(3),
|
|
DBmemp->pgout(3),
|
|
close(2),
|
|
fcntl(2),
|
|
fflush(3),
|
|
fsync(2),
|
|
log_compare(3),
|
|
log_flush(3),
|
|
lseek(2),
|
|
malloc(3),
|
|
memcmp(3),
|
|
memcpy(3),
|
|
memset(3),
|
|
mmap(2),
|
|
open(2),
|
|
sigfillset(3),
|
|
sigprocmask(2),
|
|
stat(2),
|
|
strcpy(3),
|
|
strdup(3),
|
|
strerror(3),
|
|
strlen(3),
|
|
time(3),
|
|
unlink(2),
|
|
and
|
|
write(2).
|
|
.Hy
|
|
.ad
|
|
.PP
|
|
.Ec memp_fput
|
|
.TP 5
|
|
[EACCES]
|
|
The DB_MPOOL_DIRTY flag was set and the source file was not opened for
|
|
writing.
|
|
.TP 5
|
|
.Ei
|
|
.sp
|
|
The
|
|
.I pgaddr
|
|
parameter does not reference a page returned by
|
|
.IR memp_fget .
|
|
.sp
|
|
More than one of DB_MPOOL_CLEAN and DB_MPOOL_DIRTY was set.
|
|
.PP
|
|
.Ee memp_fset
|
|
.na
|
|
.Nh
|
|
fcntl(2),
|
|
and
|
|
fflush(3).
|
|
.Hy
|
|
.ad
|
|
.PP
|
|
.Ec memp_fset
|
|
.TP 5
|
|
.Ei
|
|
.PP
|
|
.Ee memp_fsync
|
|
.na
|
|
.Nh
|
|
DBmemp->pgin(3),
|
|
DBmemp->pgout(3),
|
|
close(2),
|
|
fcntl(2),
|
|
fflush(3),
|
|
fsync(2),
|
|
log_compare(3),
|
|
log_flush(3),
|
|
lseek(2),
|
|
malloc(3),
|
|
memcpy(3),
|
|
memset(3),
|
|
open(2),
|
|
qsort(3),
|
|
realloc(3),
|
|
sigfillset(3),
|
|
sigprocmask(2),
|
|
stat(2),
|
|
strcpy(3),
|
|
strdup(3),
|
|
strerror(3),
|
|
strlen(3),
|
|
unlink(2),
|
|
and
|
|
write(2).
|
|
.Hy
|
|
.ad
|
|
.PP
|
|
.Ee memp_unlink
|
|
.na
|
|
.Nh
|
|
close(2),
|
|
fcntl(2),
|
|
fflush(3),
|
|
malloc(3),
|
|
memcpy(3),
|
|
memset(3),
|
|
mmap(2),
|
|
munmap(2),
|
|
open(2),
|
|
sigfillset(3),
|
|
sigprocmask(2),
|
|
stat(2),
|
|
strcpy(3),
|
|
strdup(3),
|
|
strerror(3),
|
|
strlen(3),
|
|
and
|
|
unlink(2).
|
|
.Hy
|
|
.ad
|
|
.PP
|
|
.Ec memp_unlink
|
|
.TP 5
|
|
.Eb
|
|
.PP
|
|
.Ee memp_register
|
|
.na
|
|
.Nh
|
|
fcntl(2),
|
|
and
|
|
malloc(3).
|
|
.Hy
|
|
.ad
|
|
.PP
|
|
.Ee memp_trickle
|
|
.na
|
|
.Nh
|
|
DBmemp->pgin(3),
|
|
DBmemp->pgout(3),
|
|
close(2),
|
|
fcntl(2),
|
|
fflush(3),
|
|
fsync(2),
|
|
log_compare(3),
|
|
log_flush(3),
|
|
lseek(2),
|
|
malloc(3),
|
|
memcmp(3),
|
|
memcpy(3),
|
|
memset(3),
|
|
mmap(2),
|
|
open(2),
|
|
sigfillset(3),
|
|
sigprocmask(2),
|
|
stat(2),
|
|
strcpy(3),
|
|
strdup(3),
|
|
strerror(3),
|
|
strlen(3),
|
|
time(3),
|
|
unlink(2),
|
|
and
|
|
write(2).
|
|
.Hy
|
|
.ad
|
|
.PP
|
|
.Ec memp_trickle
|
|
.TP 5
|
|
.Ei
|
|
.PP
|
|
.Ee memp_sync
|
|
.na
|
|
.Nh
|
|
DBmemp->pgin(3),
|
|
DBmemp->pgout(3),
|
|
close(2),
|
|
fcntl(2),
|
|
fflush(3),
|
|
fsync(2),
|
|
log_compare(3),
|
|
log_flush(3),
|
|
lseek(2),
|
|
malloc(3),
|
|
memcmp(3),
|
|
memcpy(3),
|
|
memset(3),
|
|
mmap(2),
|
|
open(2),
|
|
qsort(3),
|
|
realloc(3),
|
|
sigfillset(3),
|
|
sigprocmask(2),
|
|
stat(2),
|
|
strcpy(3),
|
|
strdup(3),
|
|
strerror(3),
|
|
strlen(3),
|
|
time(3),
|
|
unlink(2),
|
|
and
|
|
write(2).
|
|
.Hy
|
|
.ad
|
|
.PP
|
|
.Ec memp_sync
|
|
.TP 5
|
|
.Ei
|
|
.sp
|
|
The
|
|
.I memp_sync
|
|
function was called without logging having been initialized in the environment.
|
|
.PP
|
|
.Ee memp_stat
|
|
.na
|
|
.Nh
|
|
fcntl(2),
|
|
malloc(3),
|
|
memcpy(3),
|
|
and
|
|
strlen(3).
|
|
.Hy
|
|
.ad
|
|
.SH "SEE ALSO"
|
|
.Sa
|