зеркало из https://github.com/mozilla/gecko-dev.git
1551 строка
38 KiB
Groff
1551 строка
38 KiB
Groff
.ds TYPE CXX
|
|
.\"
|
|
.\" See the file LICENSE for redistribution information.
|
|
.\"
|
|
.\" Copyright (c) 1997, 1998
|
|
.\" Sleepycat Software. All rights reserved.
|
|
.\"
|
|
.\" @(#)DbInfo.sox 10.13 (Sleepycat) 5/3/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 DbInfo 3 "May 3, 1998"
|
|
.UC 7
|
|
.SH NAME
|
|
DbInfo \- informational parameters for database open
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.ft B
|
|
.ie '\*[TYPE]'CXX'\{
|
|
#include <db_cxx.h>
|
|
|
|
DbInfo::DbInfo();
|
|
DbInfo::~DbInfo();
|
|
DbInfo::DbInfo(const DbInfo &);
|
|
DbInfo::DbInfo &operator = (const DbInfo &);
|
|
|
|
int DbInfo::get_lorder() const;
|
|
void DbInfo::set_lorder(int);
|
|
|
|
size_t DbInfo::get_cachesize() const;
|
|
void DbInfo::set_cachesize(size_t);
|
|
|
|
size_t DbInfo::get_pagesize() const;
|
|
void DbInfo::set_pagesize(size_t);
|
|
|
|
typedef void *(*db_malloc_fcn)(size_t);
|
|
DbInfo::db_malloc_fcn DbInfo::get_malloc() const;
|
|
void DbInfo::set_malloc(db_malloc_fcn);
|
|
|
|
.\"u_int32_t DbInfo::get_bt_maxkey() const;
|
|
.\"void DbInfo::set_bt_maxkey(u_int32_t);
|
|
.\"
|
|
u_int32_t DbInfo::get_bt_minkey() const;
|
|
void DbInfo::set_bt_minkey(u_int32_t);
|
|
|
|
typedef int (*bt_compare_fcn)(const DBT *, const DBT *);
|
|
bt_compare_fcn DbInfo::get_bt_compare() const;
|
|
void DbInfo::set_bt_compare(bt_compare_fcn);
|
|
|
|
typedef size_t (*bt_prefix_fcn)(const DBT *, const DBT *);
|
|
bt_prefix_fcn DbInfo::get_bt_prefix() const;
|
|
void DbInfo::set_bt_prefix(bt_prefix_fcn);
|
|
|
|
u_int32_t DbInfo::get_h_ffactor() const;
|
|
void DbInfo::set_h_ffactor(u_int32_t);
|
|
|
|
u_int32_t DbInfo::get_h_nelem() const;
|
|
void DbInfo::set_h_nelem(u_int32_t);
|
|
|
|
typedef u_int32_t (*h_hash_fcn)(const void *, u_int32_t);
|
|
h_hash_fcn DbInfo::get_h_hash() const;
|
|
void DbInfo::set_h_hash(h_hash_fcn);
|
|
|
|
int DbInfo::get_re_pad() const;
|
|
void DbInfo::set_re_pad(int);
|
|
|
|
int DbInfo::get_re_delim() const;
|
|
void DbInfo::set_re_delim(int);
|
|
|
|
u_int32_t DbInfo::get_re_len() const;
|
|
void DbInfo::set_re_len(u_int32_t);
|
|
|
|
char DbInfo::*get_re_source() const;
|
|
void DbInfo::set_re_source(char *);
|
|
|
|
u_int32_t DbInfo::get_flags() const;
|
|
void DbInfo::set_flags(u_int32_t);
|
|
\}
|
|
.el\{\
|
|
import com.sleepycat.db.*;
|
|
|
|
public DbInfo();
|
|
public DbInfo(DbInfo that);
|
|
|
|
public int get_lorder();
|
|
public void set_lorder(int lorder);
|
|
|
|
public long get_cachesize();
|
|
public void set_cachesize(long cachesize);
|
|
|
|
public long get_pagesize();
|
|
public void set_pagesize(long pagesize);
|
|
|
|
.\"public int get_bt_maxkey();
|
|
.\"public void set_bt_maxkey(int bt_maxkey);
|
|
.\"
|
|
public int get_bt_minkey();
|
|
public void set_bt_minkey(int bt_minkey);
|
|
|
|
public int get_h_ffactor();
|
|
public void set_h_ffactor(int h_ffactor);
|
|
|
|
public int get_h_nelem();
|
|
public void set_h_nelem(int h_nelem);
|
|
|
|
public int get_re_pad();
|
|
public void set_re_pad(int re_pad);
|
|
|
|
public int get_re_delim();
|
|
public void set_re_delim(int re_delim);
|
|
|
|
public int get_re_len();
|
|
public void set_re_len(int re_len);
|
|
|
|
public String get_re_source();
|
|
public void set_re_source(String re_source);
|
|
|
|
public int get_flags();
|
|
public void set_flags(int flags);
|
|
\}
|
|
.ft R
|
|
.fi
|
|
.SH DESCRIPTION
|
|
.Gn
|
|
.PP
|
|
This manual page describes the DbInfo class. A DbInfo object
|
|
is used in conjunction with the
|
|
.I Db::open
|
|
method (see
|
|
.IR Db (3))
|
|
to specify particular configuration options for the open.
|
|
The DbInfo 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 refers to these accesses using the
|
|
underlying name, e.g.,
|
|
.I cachesize
|
|
instead of
|
|
.I get_cachesize
|
|
and
|
|
.IR set_cachesize .
|
|
The default constructor sets all elements of the underlying structure
|
|
to zero.
|
|
Some of the fields are specific to a type of file format (one of btree,
|
|
hashed and recno) and are thus named with an underscore separated string,
|
|
``bt'', ``h'' and ``re'', respectively.
|
|
For example, the method
|
|
.I set_bt_minkey
|
|
sets the underlying
|
|
.I bt_minkey
|
|
field, and this field is only used when opening a btree file.
|
|
.PP
|
|
The fields that are common to all access methods are listed here;
|
|
those specific to an individual access method are described below.
|
|
.if '\*[TYPE]'CXX'\{\
|
|
No reference to the DbInfo object is maintained by Db,
|
|
so it is possible to discard it as soon as the
|
|
.I Db::open
|
|
call returns.
|
|
\}
|
|
.PP
|
|
If possible,
|
|
defaults appropriate for the system are used for the DbInfo fields if
|
|
.I dbinfo
|
|
is NULL or any fields of the DbInfo object are not explicitly set.
|
|
The following DbInfo fields may be initialized before calling
|
|
.IR Db::open :
|
|
.ie '\*[TYPE]'CXX'\{\
|
|
.TP 5
|
|
size_t cachesize;\}
|
|
.el\{\
|
|
.TP 5
|
|
long cachesize;\}
|
|
A suggested maximum size of the memory pool cache, in bytes.
|
|
If
|
|
.I cachesize
|
|
is not explicitly set, an appropriate default is used.
|
|
It is an error to specify both the
|
|
.I mp_info
|
|
field and a non-zero
|
|
.IR db_cachesize .
|
|
.sp
|
|
.ft B
|
|
Note,
|
|
the minimum number of pages in the cache should be no less than 10,
|
|
and the access methods will fail if an insufficiently large cache is specified.
|
|
.ft R
|
|
In addition,
|
|
for applications that exhibit strong locality in their data access
|
|
patterns,
|
|
increasing the size of the cache can significantly improve application
|
|
performance.
|
|
.TP 5
|
|
int lorder;
|
|
The byte order for integers in the stored database metadata.
|
|
The number should represent the order as an integer, for example,
|
|
big endian order is the number 4,321, and little endian order is
|
|
the number 1,234.
|
|
If
|
|
.I lorder
|
|
is not explicitly set,
|
|
the host order of the machine where the Db library was compiled is used.
|
|
.sp
|
|
The value of
|
|
.I lorder
|
|
is ignored except when databases are being created.
|
|
If a database already exists,
|
|
the byte order it uses is determined when the file is read.
|
|
.sp
|
|
.ft B
|
|
The access methods provide no guarantees about the byte ordering of the
|
|
application data stored in the database,
|
|
and applications are responsible for maintaining any necessary ordering.
|
|
.ft R
|
|
.ie '\*[TYPE]'CXX'\{\
|
|
.TP 5
|
|
size_t pagesize;\}
|
|
.el\{\
|
|
.TP 5
|
|
long pagesize;\}
|
|
The size of the pages used to hold items in the database, in bytes.
|
|
The minimum page size is 512 bytes and the maximum page size is 64K bytes.
|
|
If
|
|
.I pagesize
|
|
is not explicitly set,
|
|
a page size is selected based on the underlying filesystem I/O block
|
|
size.
|
|
The selected size has a lower limit of 512 bytes and an upper limit
|
|
of 16K bytes.
|
|
.if '\*[TYPE]'CXX'\{\
|
|
.TP 5
|
|
void *(*malloc)(size_t);
|
|
The flag DB_DBT_MALLOC, when specified in the Dbt object, will cause
|
|
the Db library to allocate memory which then becomes the responsibility
|
|
of the calling application.
|
|
See
|
|
.IR Dbt (3)
|
|
for more information.
|
|
.sp
|
|
On systems where there may be multiple library versions of malloc
|
|
(notably Windows NT), specifying the DB_DBT_MALLOC flag will fail
|
|
because the Db library will allocate memory from a different heap
|
|
than the application will use to free it.
|
|
To avoid this problem, the
|
|
.I malloc
|
|
function should be set to point to the application's allocation routine.
|
|
If
|
|
.I malloc
|
|
is not explicitly set,
|
|
it will be used to allocate the memory returned when the DB_DBT_MALLOC flag
|
|
is set.
|
|
The
|
|
.I malloc
|
|
method must match the calling conventions of the
|
|
.IR malloc (3)
|
|
library routine.
|
|
\}
|
|
.SH BTREE
|
|
The btree data structure is a sorted, balanced tree structure storing
|
|
associated key/data pairs.
|
|
Searches, insertions,
|
|
and deletions in the btree will all complete in O (lg base N) where base
|
|
is the average number of keys per page.
|
|
Often,
|
|
inserting ordered data into btrees results in pages that are half-full.
|
|
This implementation has been modified to make ordered (or inverse ordered)
|
|
insertion the best case,
|
|
resulting in nearly perfect page space utilization.
|
|
.PP
|
|
Space freed by deleting key/data pairs from the database is never reclaimed
|
|
from the filesystem,
|
|
although it is reused where possible.
|
|
This means that the btree storage structure is grow-only.
|
|
If sufficiently many keys are deleted from a tree that shrinking the
|
|
underlying database file is desirable,
|
|
this can be accomplished by creating a new tree from a scan of the existing
|
|
one.
|
|
.PP
|
|
The following additional fields and flags may be initialized in the DbInfo
|
|
object before calling
|
|
.IR Db::open ,
|
|
when using the btree access method:
|
|
.if '\*[TYPE]'CXX'\{\
|
|
.TP 5
|
|
int (*bt_compare)(const Dbt *, const Dbt *);
|
|
The
|
|
.I bt_compare
|
|
function is the key comparison method.
|
|
It must return an integer less than, equal to, or greater than zero if the
|
|
first key argument is considered to be respectively less than, equal to,
|
|
or greater than the second key argument.
|
|
The same comparison method must be used on a given tree every time it
|
|
is opened.
|
|
.sp
|
|
The
|
|
.I data
|
|
and
|
|
.I size
|
|
fields of the DBT are the only fields that may be used for the purposes
|
|
of this comparison.
|
|
.sp
|
|
If
|
|
.I bt_compare
|
|
is NULL,
|
|
the keys are compared lexically,
|
|
with shorter keys collating before longer keys.
|
|
\}
|
|
.ie '\*[TYPE]'CXX'\{\
|
|
.TP 5
|
|
u_int32_t bt_minkey;\}
|
|
.el\{\
|
|
.TP 5
|
|
int bt_minkey;\}
|
|
The minimum number of keys that will be stored on any single page.
|
|
This value is used to determine which keys will be stored on overflow
|
|
pages, i.e. if a key or data item is larger than the pagesize divided
|
|
by the
|
|
.I bt_minkey
|
|
value,
|
|
it will be stored on overflow pages instead of in the page itself.
|
|
The
|
|
.I bt_minkey
|
|
value specified must be at least 2; if
|
|
.I bt_minkey
|
|
is not explicitly set, a value of 2 is used.
|
|
.if '\*[TYPE]'CXX'\{\
|
|
.TP 5
|
|
size_t (*bt_prefix)(const Dbt *, const Dbt *);
|
|
The
|
|
.I bt_prefix
|
|
function is the prefix comparison method.
|
|
If specified, this method must return the number of bytes of the second key
|
|
argument that are necessary to determine that it is greater than the first
|
|
key argument.
|
|
If the keys are equal, the key length should be returned.
|
|
.sp
|
|
The
|
|
.I data
|
|
and
|
|
.I size
|
|
fields of the DBT are the only fields that may be used for the purposes
|
|
of this comparison.
|
|
.sp
|
|
This is used to compress the keys stored on the btree internal pages.
|
|
The usefulness of this is data dependent,
|
|
but in some data sets can produce significantly reduced tree sizes and
|
|
search times.
|
|
If
|
|
.I bt_prefix
|
|
is not explicitly set, and no comparison method is specified,
|
|
a default lexical comparison method is used.
|
|
If
|
|
.I bt_prefix
|
|
is NULL and a comparison method is specified, no prefix comparison is
|
|
done.
|
|
\}
|
|
.TP 5
|
|
unsigned long flags;
|
|
The following additional flags may be specified:
|
|
.RS
|
|
.TP 5
|
|
.de DU
|
|
DB_DUP
|
|
Permit duplicate keys in the tree,
|
|
i.e. insertion when the key of the key/data pair being inserted already
|
|
exists in the tree will be successful.
|
|
The ordering of duplicates in the tree is determined by the order of
|
|
insertion,
|
|
unless the ordering is otherwise specified by use of a cursor (see
|
|
.IR Dbc (3)
|
|
for more information.)
|
|
..
|
|
.DU
|
|
It is an error to specify both DB_DUP and DB_RECNUM.
|
|
.TP 5
|
|
.Sj DB_RECNUM
|
|
Support retrieval from btrees using record numbers.
|
|
For more information, see the DB_GET_RECNO flag to the
|
|
.ie '\*[TYPE]'CXX'\{\
|
|
.I db->get
|
|
\}
|
|
.el\{\
|
|
.I db.get
|
|
\}
|
|
method (below),
|
|
and the cursor
|
|
.I Dbc::get
|
|
method (in
|
|
.IR Dbc (3)).
|
|
.sp
|
|
Logical record numbers in btrees are mutable in the face of record
|
|
insertion or deletion.
|
|
See the DB_RENUMBER flag in the RECNO section below for further discussion.
|
|
.sp
|
|
Maintaining record counts within a btree introduces a serious point of
|
|
contention,
|
|
namely the page locations where the record counts are stored.
|
|
In addition,
|
|
the entire tree must be locked during both insertions and deletions,
|
|
effectively single-threading the tree for those operations.
|
|
Specifying DB_RECNUM can result in serious performance degradation for
|
|
some applications and data sets.
|
|
.sp
|
|
It is an error to specify both DB_DUP and DB_RECNUM.
|
|
.RE
|
|
.SH HASH
|
|
The hash data structure is an extensible, dynamic hashing scheme.
|
|
Backward compatible interfaces to the functions described in
|
|
.IR dbm (3),
|
|
.IR ndbm (3)
|
|
and
|
|
.IR hsearch (3)
|
|
are provided, however these interfaces are not compatible with
|
|
previous file formats.
|
|
.PP
|
|
The following additional fields and flags may be initialized in the DbInfo
|
|
object before calling
|
|
.IR Db::open ,
|
|
when using the hash access method:
|
|
.TP 5
|
|
.ie '\*[TYPE]'CXX'\{\
|
|
.TP 5
|
|
u_int32_t h_ffactor;\}
|
|
.el\{\
|
|
.TP 5
|
|
int h_ffactor;\}
|
|
The desired density within the hash table.
|
|
It is an approximation of the number of keys allowed to accumulate in any
|
|
one bucket, determining when the hash table grows or shrinks.
|
|
The default value is 0, indicating that the fill factor will be selected
|
|
dynamically as pages are filled.
|
|
.if '\*[TYPE]'CXX'\{\
|
|
.TP 5
|
|
u_int32_t (*h_hash)(const void *, u_int32_t);
|
|
The
|
|
.I h_hash
|
|
field is a user defined hash method;
|
|
if
|
|
.I h_hash
|
|
is NULL,
|
|
a default hash method is used.
|
|
Since no hash method performs equally well on all possible data,
|
|
the user may find that the built-in hash method performs poorly with
|
|
a particular data set.
|
|
User specified hash functions must take a pointer to a byte string and
|
|
a length as arguments and return a u_int32_t value.
|
|
.IP
|
|
If a hash method is specified,
|
|
.I hash_open
|
|
will attempt to determine if the hash method specified is the same as
|
|
the one with which the database was created, and will fail if it detects
|
|
that it is not.
|
|
\}
|
|
.ie '\*[TYPE]'CXX'\{\
|
|
.TP 5
|
|
u_int32_t h_nelem;\}
|
|
.el\{\
|
|
.TP 5
|
|
int h_nelem;\}
|
|
An estimate of the final size of the hash table.
|
|
If not set or set too low,
|
|
hash tables will expand gracefully as keys are entered,
|
|
although a slight performance degradation may be noticed.
|
|
The default value is 1.
|
|
.TP 5
|
|
unsigned long flags;
|
|
The following additional flags may be specified by
|
|
.BR or 'ing
|
|
together one or more of the following values:
|
|
.RS
|
|
.TP 5
|
|
.DU
|
|
.SH RECNO
|
|
The recno access method provides support for fixed and variable length
|
|
records,
|
|
optionally backed by a flat text (byte stream) file.
|
|
Both fixed and variable length records are accessed by their logical
|
|
record number.
|
|
.PP
|
|
It is valid to create a record whose record number is more than one
|
|
greater than the last record currently in the database.
|
|
For example, the creation of record number 8, when records 6 and 7
|
|
do not yet exist, is not an error.
|
|
However, any attempt to retrieve such records (e.g., records 6 and 7)
|
|
will return DB_KEYEMPTY.
|
|
.PP
|
|
Deleting a record will not, by default, renumber records following
|
|
the deleted record (see DB_RENUMBER below for more information).
|
|
Any attempt to retrieve deleted records will return DB_KEYEMPTY.
|
|
.PP
|
|
The following additional fields and flags may be initialized in the DbInfo
|
|
object before calling
|
|
.IR Db::open ,
|
|
when using the recno access method:
|
|
.TP 5
|
|
int re_delim;
|
|
For variable length records,
|
|
if the
|
|
.I re_source
|
|
file is specified and the DB_DELIMITER flag is set,
|
|
the delimiting byte used to mark the end of a record in the source file.
|
|
If the
|
|
.I re_source
|
|
file is specified and the DB_DELIMITER flag is not set,
|
|
<newline> characters (i.e. ``\en'', 0x0a) are interpreted as
|
|
end-of-record markers.
|
|
.TP 5
|
|
.ie '\*[TYPE]'CXX'\{\
|
|
u_int32_t re_len;\}
|
|
.el\{\
|
|
int re_len;\}
|
|
The length of a fixed-length record.
|
|
.TP 5
|
|
int re_pad;
|
|
For fixed length records,
|
|
if the DB_PAD flag is set,
|
|
the pad character for short records.
|
|
If the DB_PAD flag is not explicitly set,
|
|
<space> characters (i.e., 0x20) are used for padding.
|
|
.ie '\*[TYPE]'CXX'\{\
|
|
.TP 5
|
|
char *re_source;\}
|
|
.el\{\
|
|
.TP 5
|
|
String re_source;\}
|
|
The purpose of the
|
|
.I re_source
|
|
field is to provide fast access and modification to databases that are
|
|
normally stored as flat text files.
|
|
.sp
|
|
If the
|
|
.I re_source
|
|
field is explicitly set,
|
|
it specifies an underlying flat text database file that is read to initialize
|
|
a transient record number index.
|
|
In the case of variable length records,
|
|
the records are separated by the byte value
|
|
.IR re_delim .
|
|
For example,
|
|
standard UNIX byte stream files can be interpreted as a sequence of variable
|
|
length records separated by <newline> characters.
|
|
.sp
|
|
In addition,
|
|
when cached data would normally be written back to the underlying database
|
|
file (e.g., the
|
|
.I close
|
|
or
|
|
.I sync
|
|
.ie '\*[TYPE]'CXX'\{\
|
|
functions\}
|
|
.el\{\
|
|
methods\}
|
|
are called),
|
|
the in-memory copy of the database will be written back to the
|
|
.I re_source
|
|
file.
|
|
.sp
|
|
By default, the backing source file is read lazily,
|
|
i.e., records are not read from the file until they are requested by the
|
|
application.
|
|
.ft B
|
|
If multiple processes (not threads) are accessing a recno database
|
|
concurrently and either inserting or deleting records,
|
|
the backing source file must be read in its entirety before more than
|
|
a single process accesses the database,
|
|
and only that process should specify the backing source file as part
|
|
of the
|
|
.I Db::open
|
|
call.
|
|
.ft R
|
|
See the DB_SNAPSHOT flag below for more information.
|
|
.sp
|
|
.ft B
|
|
Reading and writing the backing source file specified by re_source
|
|
cannot be transactionally protected because it involves filesystem
|
|
operations that are not part of the Db transaction methodology.
|
|
.ft R
|
|
For this reason,
|
|
if a temporary database is used to hold the records, i.e., a NULL was
|
|
specified as the
|
|
.I file
|
|
argument to
|
|
.IR Db::open ,
|
|
it is possible to lose the contents of the
|
|
.I re_source
|
|
file, e.g., if the system crashes at the right instant.
|
|
If a file is used to hold the database, i.e., a file name was specified
|
|
as the
|
|
.I file
|
|
argument to
|
|
.IR Db::open ,
|
|
normal database recovery on that file can be used to prevent information
|
|
loss,
|
|
although it is still possible that the contents of
|
|
.I re_source
|
|
will be lost if the system crashes.
|
|
.sp
|
|
The
|
|
.I re_source
|
|
file must already exist (but may be zero-length) when
|
|
.I Db::open
|
|
is called.
|
|
.sp
|
|
For all of the above reasons, the
|
|
.I re_source
|
|
field is generally used to specify databases that are read-only for Db
|
|
applications,
|
|
and that are either generated on the fly by software tools,
|
|
or modified using a different mechanism, e.g., a text editor.
|
|
.TP 5
|
|
unsigned long flags;
|
|
The following additional flags may be specified by
|
|
.BR or 'ing
|
|
together one or more of the following values:
|
|
.RS
|
|
.TP 5
|
|
.Sj DB_DELIMITER
|
|
The
|
|
.I re_delim
|
|
field is set.
|
|
.TP 5
|
|
.Sj DB_FIXEDLEN
|
|
The records are fixed-length, not byte delimited.
|
|
The
|
|
.I re_len
|
|
value specifies the length of the record,
|
|
and the
|
|
.I re_pad
|
|
value is used as the pad character.
|
|
.sp
|
|
Any records added to the database that are less than
|
|
.I re_len
|
|
bytes long are automatically padded.
|
|
Any attempt to insert records into the database that are greater than
|
|
.I re_len
|
|
bytes long will cause the call to fail immediately and return an error.
|
|
.TP 5
|
|
.Sj DB_PAD
|
|
The
|
|
.I re_pad
|
|
field is set.
|
|
.TP 5
|
|
.Sj DB_RENUMBER
|
|
Specifying the DB_RENUMBER flag causes the logical record numbers to be
|
|
mutable,
|
|
and change as records are added to and deleted from the database.
|
|
For example,
|
|
the deletion of record number 4 causes records numbered 5 and greater
|
|
to be renumbered downward by 1.
|
|
If a cursor was positioned to record number 4 before the deletion,
|
|
it will reference the new record number 4, if any such record exists,
|
|
after the deletion.
|
|
If a cursor was positioned after record number 4 before the deletion,
|
|
it will be shifted downward 1 logical record,
|
|
continuing to reference the same record as it did before.
|
|
.sp
|
|
Using the
|
|
.I Dbc::put
|
|
or
|
|
.I put
|
|
interfaces to create new records will cause the creation of multiple
|
|
records if the record number is more than one greater than the largest
|
|
record currently in the database.
|
|
For example, creating record 28,
|
|
when record 25 was previously the last record in the database,
|
|
will create records 26 and 27 as well as 28.
|
|
Attempts to retrieve records that were created in this manner
|
|
will result in an error return of DB_KEYEMPTY.
|
|
.sp
|
|
If a created record is not at the end of the database,
|
|
all records following the new record will be automatically renumbered
|
|
upward by 1.
|
|
For example,
|
|
the creation of a new record numbered 8 causes records numbered 8 and
|
|
greater to be renumbered upward by 1.
|
|
If a cursor was positioned to record number 8 or greater before the insertion,
|
|
it will be shifted upward 1 logical record,
|
|
continuing to reference the same record as it did before.
|
|
.sp
|
|
For these reasons,
|
|
concurrent access to a recno database with the DB_RENUMBER flag specified
|
|
may be largely meaningless, although it is supported.
|
|
.TP 5
|
|
.Sj DB_SNAPSHOT
|
|
This flag specifies that any specified
|
|
.I re_source
|
|
file be read in its entirety when
|
|
.I Db::open
|
|
is called.
|
|
If this flag is not specified,
|
|
the
|
|
.I re_source
|
|
file may be read lazily.
|
|
.RE
|
|
.PP
|
|
.SH "SEE ALSO"
|
|
.Sa
|