gecko-dev/db/man/mancxx.roff/DbLog.3

.ds TYPE CXX
.\"
.\" See the file LICENSE for redistribution information.
.\"
.\" Copyright (c) 1997, 1998
.\"	Sleepycat Software.  All rights reserved.
.\"
.\"	@(#)DbLog.sox	10.15 (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.
..
.\" Stat field macro.
.de Sf
.ie '\*[TYPE]'CXX'\{\
u_int32_t \\$1;\}
.el\{\
int get_\\$1();\}
..
.TH DbLog 3 "May 10, 1998"
.UC 7
.SH NAME
DbLog \- log management class
.SH SYNOPSIS
.nf
.ft B
.ie '\*[TYPE]'CXX'\{
#include <db_cxx.h>

static int
DbLog::open(const char *dir,
.ti +5
u_int32_t flags, int mode, DbEnv *dbenv, DbLog **regionp);

int
DbLog::close();

int
DbLog::flush(const DbLsn *lsn);

int
DbLog::get(DbLsn *lsn, Dbt *data, u_int32_t flags);

static int
DbLog::compare(const DbLsn *lsn0, const DbLsn *lsn1);

int
DbLog::file(const DbLsn *lsn, char *namep, size_t len);

int
DbLog::put(DbLsn *lsn, const Dbt *data, u_int32_t flags);

static int
DbLog::unlink(const char *dir, int force, DbEnv *);

int
DbLog::archive(char **list[],
.ti +5
u_int32_t flags, void *(*db_malloc)(size_t));

int
DbLog::db_register(const Db *dbp,
.ti +5
const char *name, DBTYPE type, u_int32_t *fidp);

int
DbLog::db_unregister(u_int32_t fid);

int
DbLog::stat(DB_LOG_STAT **spp, void *(*db_malloc)(size_t));
\}
.el\{\
import com.sleepycat.db.*;

public static DbLog open(String dir, int flags, int mode, DbEnv dbenv)
.ti +5
throws DbException;

public void close()
.ti +5
throws DbException;

public static int compare(DbLsn lsn0, DbLsn lsn1);

public String file(DbLsn lsn)
.ti +5
throws DbException;

public void flush(DbLsn lsn)
.ti +5
throws DbException;

public void get(DbLsn lsn, Dbt data, int flags)
.ti +5
throws DbException;

public void put(DbLsn lsn, Dbt data, int flags)
.ti +5
throws DbException;

public DbLogStat stat()
.ti +5
throws DbException;

public int db_register(Db dbp, String name, int dbtype)
.ti +5
throws DbException;

public void db_unregister(int fid)
.ti +5
throws DbException;

public static void unlink(String dir, int force, DbEnv dbenv)
.ti +5
throws DbException;
\}
.ft R
.fi
.SH DESCRIPTION
.Gn
.PP
This manual page describes the specific details of the log class.
.PP
This class provide a general-purpose logging facility sufficient
for transaction management.
Logs can be shared by multiple processes.
.PP
The DB transaction log is represented by a directory containing a set of
files.
The log is a record-oriented, append-only file, with records identified
and accessed via
.IR DbLsn 's
(database log sequence numbers).
.PP
DbLsn's are returned on each
.I DbLog::put
operation, and only those DbLsn's returned by
.I DbLog::put
can later be used to retrieve records from the log.
.PP
.Co log DbLog
.PP
If the log region is being created and log files are already present,
the log files are ``recovered'' and subsequent log writes are appended
to the end of the log.
.PP
The log is stored in one or more files in the specified directory.
Each file is named using the format
.sp
.ti +5
log.NNNNN
.sp
where ``NNNNN'' is the sequence number of the file within the log.
.PP
.Fm
.Ft DbLog::open DbLog
.PP
.Mo "log subsystem"
.PP
The logging subsystem is configured
.En "DbLog::open" "DbLog::close"
.TP 5
.Se
.ie '\*[TYPE]'CXX'\{\
.TP 5
u_int32_t lg_max;\}
.el\{\
.TP 5
int lg_max;\}
The maximum size of a single file in the log.
Because DbLsn file offsets are unsigned 4-byte values,
.I lg_max
may not be larger than the maximum unsigned 4-byte value.
.sp
If
.I lg_max
is 0, a default value is used.
.sp
See the section "LOG FILE LIMITS" below, for further information.
.PP
.Rt DbLog::open
.PP
.Fn DbLog::close
The
.I DbLog::close
method closes the log associated with the DbLog object.
.PP
.Cc DbLog
.PP
When multiple threads are using the DbLog handle concurrently,
only a single thread may call the
.I DbLog::close
method.
.PP
.Rt DbLog::close
.PP
.Fn DbLog::flush
The
.I DbLog::flush
method guarantees that all log records whose DbLsns are less than or
equal to the
.I lsn
parameter have been written to disk.
If
.I lsn
is NULL,
all records in the log are flushed.
.PP
.Rt DbLog::flush
.PP
.Fn DbLog::get
The
.I DbLog::get
method implements a cursor inside of the log,
retrieving records from the log according to the
.I lsn
and
.I flags
parameters.
.PP
The data field of the
.I data
object is set to the record retrieved and the size field indicates the
number of bytes in the record.
See
.IR Dbt (3)
for a description of other fields in the
.I data
object.
.ft B
When multiple threads are using the returned DbLog handle concurrently,
either the DB_DBT_MALLOC or DB_DBT_USERMEM flags must be specified for
any Dbt used for data retrieval.
.ft R
.PP
The
.I flags
parameter must be set to exactly one of the following values:
.TP 5
.Sj DB_CHECKPOINT
The last record written with the DB_CHECKPOINT flag specified to the
.I DbLog::put
method is returned in the
.I data
argument.
The
.I lsn
argument is overwritten with the DbLsn of the record returned.
If no record has been previously written with the DB_CHECKPOINT flag
specified,
the first record in the log is returned.
.IP
If the log is empty the
.I DbLog::get
method will return DB_NOTFOUND.
.TP 5
.Sj DB_FIRST
The first record from any of the log files found in the log directory
is returned in the
.I data
argument.
The
.I lsn
argument is overwritten with the DbLsn of the record returned.
.IP
If the log is empty the
.I DbLog::get
method will return DB_NOTFOUND.
.TP 5
.Sj DB_LAST
The last record in the log is returned in the
.I data
argument.
The
.I lsn
argument is overwritten with the DbLsn of the record returned.
.IP
If the log is empty,
the
.I DbLog::get
method will return DB_NOTFOUND.
.TP 5
.Sj DB_NEXT
The current log position is advanced to the next record in the log and that
record is returned in the
.I data
argument.
The
.I lsn
argument is overwritten with the DbLsn of the record returned.
.IP
If the pointer has not been initialized via DB_FIRST, DB_LAST,
DB_SET, DB_NEXT, or DB_PREV,
.I DbLog::get
will return the first record in the log.
If the last log record has already been returned or the log is empty,
the
.I DbLog::get
method will return DB_NOTFOUND.
.IP
If the log was opened with the DB_THREAD flag set,
calls to
.I DbLog::get
with the DB_NEXT flag set will return EINVAL.
.TP 5
.Sj DB_PREV
The current log position is moved to the previous record in the log and that
record is returned in the
.I data
argument.
The
.I lsn
argument is overwritten with the DbLsn of the record returned.
.IP
If the pointer has not been initialized via DB_FIRST, DB_LAST,
DB_SET, DB_NEXT, or DB_PREV,
.I DbLog::get
will return the last record in the log.
If the first log record has already been returned or the log is empty,
the
.I DbLog::get
method will return DB_NOTFOUND.
.IP
If the log was opened with the DB_THREAD flag set,
calls to
.I DbLog::get
with the DB_PREV flag set will return EINVAL.
.TP 5
.Sj DB_CURRENT
Return the log record currently referenced by the log.
.IP
If the log pointer has not been initialized via DB_FIRST, DB_LAST, DB_SET,
DB_NEXT, or DB_PREV, or if the log was opened with the DB_THREAD flag set,
.I DbLog::get
will return EINVAL.
.Sj DB_SET
Retrieve the record specified by the
.I lsn
argument.
If the specified DbLsn is invalid (e.g., does not appear in the log)
.I DbLog::get
will return EINVAL.
.PP
.Ro DbLog::get
.PP
.Fn DbLog::compare
The
.I DbLog::compare
method allows the caller to compare two DbLsn's.
.I DbLog::compare
returns 0 if the two DbLsn's are equal, 1 if
.I lsn0
is greater than
.IR lsn1 ,
and -1 if
.I lsn0
is less than
.IR lsn1 .
.PP
.Fn DbLog::file
The
.I DbLog::file
method maps DbLsn's to file names.
The
.I DbLog::file
method
.ie '\*[TYPE]'CXX'\{\
copies the name of the file containing the record named by
.I lsn
into the memory location referenced by
.IR namep .
(This mapping of DbLsn to file is needed for database administration.
For example, a transaction manager typically records the earliest DbLsn
needed for restart, and the database administrator may want to archive
log files to tape when they contain only DbLsn's before the earliest one
needed for restart.)
.PP
The
.I len
argument is the length of the
.I namep
buffer in bytes.
If
.I namep
is too short to hold the file name,
.I DbLog::file
will return ENOMEM.
Note, as described above,
log file names are quite short,
on the order of 10 characters.
\}
.el\{\
returns the name of the file containing the record named by
.IR lsn .
(This mapping of DbLsn to file is needed for database administration.
For example, a transaction manager typically records the earliest DbLsn
needed for restart, and the database administrator may want to archive
log files to tape when they contain only DbLsn's before the earliest one
needed for restart.)
\}
.PP
.Rt DbLog::file
.PP
.Fn DbLog::put
The
.I DbLog::put
method appends records to the log.
The DbLsn of the put record is returned in the
.I lsn
parameter.
The
.I flags
parameter may be set to one of the following values:
.TP 5
.Sj DB_CHECKPOINT
The log should write a checkpoint record, recording any information
necessary to make the log structures recoverable after a crash.
.TP 5
.Sj DB_CURLSN
The DB_LSN of the next record to be put is returned in the
.I lsn
parameter.
.TP 5
.Sj DB_FLUSH
The log is forced to disk after this record is written, guaranteeing
that all records with DbLsns less than or equal to the one being put
are on disk
before this method returns (this function is most often used for
a transaction commit, see
.I Db::Txn
in
Db (3)).
.PP
The caller is responsible for providing any necessary structure to
.IR data .
(For example, in a write-ahead logging protocol, the application must
understand what part of
.I data
is an operation code, what part is redo information, and what part is
undo information.
In addition, most transaction managers will store in
.I data
the DbLsn of the previous log record for the same transaction,
to support chaining back through the transaction's log records
during undo.)
.PP
.Rt DbLog::put
.PP
.Un "log region" DbLog
.PP
.Fn DbLog::archive
The
.I DbLog::archive
method creates
.ie '\*[TYPE]'CXX'\{\
a NULL-terminated
array of log or database file names
and copies a pointer to them into the user-specified memory location
.IR list .
\}
.el \{\
and returns an array of log or database file names.
\}
.PP
By default,
.I DbLog::archive
returns the names of all of the log files that are no longer in use (e.g.,
no longer involved in active transactions),
and that may be archived for catastrophic recovery and then removed
from the system.
If there were no file names to return,
.I list
will be set to NULL.
.PP
.if '\*[TYPE]'CXX'\{\
.Ma "Arrays of log file names"
\}
.PP
The
.I flags
argument is specified by
.BR or 'ing
together one or more of the following values:
.TP 5
.Sj DB_ARCH_ABS
All pathnames are returned as absolute pathnames,
instead of relative to the database home directory.
.TP 5
.Sj DB_ARCH_DATA
Return the database files that need to be archived in order to recover
the database from catastrophic failure.
If any of the database files have not been accessed during the lifetime of
the current log files,
.I DbLog::archive
will not include them in this list.
It is also possible that some of the files referenced in the log have
since been deleted from the system.
.TP 5
.Sj DB_ARCH_LOG
Return all the log file names regardless of whether or not they are in
use.
.PP
The DB_ARCH_DATA and DB_ARCH_LOG flags are mutually exclusive.
.PP
.Rt DbLog::archive
.PP
.Ux DbLog::archive log_archive db_archive
See the
.IR db_archive (1)
manual page for more information on database archival procedures.
.PP
.Fn DbLog::db_register
The
.I DbLog::db_register
method registers a file name with the log manager and
.ie '\*[TYPE]'CXX'\{\
copies a file
identification number into the memory location referenced by
.IR fidp .
\}
.el\{\
returns a file identification number.
\}
This file identification number should be used in all subsequent log
messages that refer to operations on this file.
The log manager records all file name to file identification number mappings
at each checkpoint so that a recovery process can identify the file to which
a record in the log refers.
.PP
The
.I DbLog::db_register
method is called when an access method registers the open of a file.
The
.I dbp
parameter should be a
.if '\*[TYPE]'CXX'\{\
pointer to the
\}
Db object which is being returned
by the access method.
.PP
The
.I type
parameter should be one of the Db types specified in
.I Db::open
.IR (see Db (3)),
e.g., DB_HASH.
.PP
.Rt DbLog::db_register
.PP
.Fn DbLog::db_unregister
The
.I DbLog::db_unregister
method disassociates the file name to file identification number
mapping for the file identification number specified by the
.I fid
parameter.
The file identification number may then be reused.
.PP
.Rt DbLog::db_unregister
.PP
.Fn DbLog::stat
The
.I DbLog::stat
function creates a statistical structure and
.ie '\*[TYPE]'CXX'\{\
copies a pointer to it into
the user-specified memory location.
\}
.el\{\
returns it to the caller.
\}
.PP
.Ma "Statistical structures"
The log statistics are stored in a
.ie '\*[TYPE]'CXX'\{\
structure of type
DB_LOG_STAT (typedef'd in <db.h>).
The following DB_LOG_STAT fields will be filled in:
\}
.el\{\
DbLogStat object.  Data fields in DbLogStat can be accessed
via
.I get
methods.
\}
.TP 5
.Sf st_magic
The magic number that identifies a file as a log file.
.Nt
.Sf st_version
The version of the log file type.
.Nt
.Sf st_refcnt
The number of references to the region.
.Nt
.Sf st_regsize
The size of the region.
.Nt
.Sf st_mode
The mode of any created log files.
.Nt
.Sf st_lg_max
The maximum size of any individual file comprising the log.
.Nt
.Sf st_written
The total number of bytes written to this log.
.Nt
.Sf st_written_chkpt
The number of bytes written since the last checkpoint.
.Nt
.Sf st_region_wait
The number of times that a process was able to obtain
the region lock without waiting.
.Nt
.Sf st_region_nowait
The number of times that a process was forced to wait before
obtaining the region lock.
.\"
.\" See the file LICENSE for redistribution information.
.\"
.\" Copyright (c) 1998
.\"	Sleepycat Software.  All rights reserved.
.\"
.\"	@(#)limits.so	8.1 (Sleepycat) 5/3/98
.\"
.de Ll
.SH "LOG FILE LIMITS
Log file sizes impose a time limit on the length of time a database
may be accessed under transaction protection, before it needs to be
dumped and reloaded (see
.IR db_dump(3)
and
.IR db_load(3)).
Unfortunately, the limits are potentially difficult to calculate.
.PP
The log file name consists of "log." followed by 5 digits, resulting
in a maximum of 99,999 log files.
Consider an application performing 600 transactions per second, for
15 hours a day, logged into 10Mb log files, where each transaction
is logging approximately 100 bytes of data.  The calculation:
.PP
.nf
.RS
(10 * 2^20 * 99999) /
.ti +5
(600 * 60 * 60 * 15 * 100) = 323.63
.RE
.fi
.PP
indicates that the system will run out of log file space in
roughly 324 days.
If we increase the maximum size of the files from 10Mb to 100Mb,
the same calculation indicates that the application will run out
of log file space in roughly 9 years.
.PP
There is no way to reset the log file name space in Berkeley DB.
If your application is reaching the end of its log file name space,
you should:
.TP 5
1.
Archive your databases as if to prepare for catastrophic failure (see
.IR db_archive (1)
for more information).
.TP 5
2.
Dump and re-load
.B all
your databases (see
.IR db_dump (1)
and
.IR db_load (1)
for more information).
.TP 5
3.
Remove all of the log files from the database environment (see
.IR db_archive (1)
for more information).
.TP 5
4.
Restart your applications.
..
.de Tl
.SH "TRANSACTION ID LIMITS
The transaction ID space in Berkeley DB is 2^31, or 2 billion entries.
It is possible that some environments may need to be aware of this
limitation.
Consider an application performing 600 transactions a second for 15
hours a day.
The transaction ID space will run out in roughly 66 days:
.PP
.nf
.RS
2^31 / (600 * 15 * 60 * 60) = 66
.RE
.fi
.PP
Doing only 100 transactions a second exhausts the transaction ID space
in roughly one year.
.PP
The transaction ID space is reset each time recovery is run.
If you reach the end of your transaction ID space,
shut down your applications and restart them after running recovery (see
.IR db_recover (1)
for more information).
The most recently allocated transaction ID is the
.I st_last_txnid
value in the transaction statistics information, and is displayed by the
.IR db_stat (1)
utility.
..
.Ll
.SH "ENVIRONMENT VARIABLES"
The following environment variables affect the execution of
.IR db_log :
.TP 5
.Eh DbLog::open DB_LOG_DIR
.TP 5
.Ev log DbLog
.SH ERRORS
.Ek
.PP
.Ee DbLog::open
.na
.Nh
DbLog::close(3), 
DbLog::unlink(3), 
atoi(3), 
close(2), 
db_version(3), 
fcntl(2), 
fflush(3), 
lseek(2), 
malloc(3), 
memcpy(3), 
memset(3), 
mmap(2), 
munmap(2), 
open(2), 
opendir(3), 
read(2), 
readdir(3), 
realloc(3), 
sigfillset(3), 
sigprocmask(2), 
stat(2), 
strchr(3), 
strcpy(3), 
strdup(3), 
strerror(3), 
strlen(3), 
strncmp(3), 
unlink(2), 
and
write(2). 
.Hy
.ad
.PP
.Ec DbLog::open
.TP 5
.Em
.TP 5
.Ei
.sp
.Et
.sp
The specified file size was too large.
.PP
.Ee DbLog::close
.na
.Nh
close(2), 
fcntl(2), 
fflush(3), 
munmap(2), 
and
strerror(3). 
.Hy
.ad
.PP
.Ee DbLog::flush
.na
.Nh
close(2), 
fcntl(2), 
fflush(3), 
fsync(2), 
lseek(2), 
malloc(3), 
memcpy(3), 
memset(3), 
open(2), 
sigfillset(3), 
sigprocmask(2), 
stat(2), 
strcpy(3), 
strdup(3), 
strerror(3), 
strlen(3), 
unlink(2), 
and
write(2). 
.Hy
.ad
.PP
.Ec DbLog::flush
.TP 5
.Ei
.PP
.Ee DbLog::get
.na
.Nh
atoi(3), 
close(2), 
fcntl(2), 
fflush(3), 
lseek(2), 
malloc(3), 
memcpy(3), 
memset(3), 
open(2), 
opendir(3), 
read(2), 
readdir(3), 
realloc(3), 
sigfillset(3), 
sigprocmask(2), 
stat(2), 
strchr(3), 
strcpy(3), 
strdup(3), 
strerror(3), 
strlen(3), 
strncmp(3), 
and
unlink(2). 
.Hy
.ad
.PP
.Ec DbLog::get
.TP 5
.Ei
.sp
The DB_FIRST flag was specified and no log files were found.
.PP
.Ee DbLog::file
.na
.Nh
close(2), 
fcntl(2), 
fflush(3), 
malloc(3), 
memcpy(3), 
memset(3), 
open(2), 
sigfillset(3), 
sigprocmask(2), 
stat(2), 
strcpy(3), 
strdup(3), 
strerror(3), 
strlen(3), 
and
unlink(2). 
.Hy
.ad
.PP
.Ec DbLog::file
.TP 5
[ENOMEM]
The supplied buffer was too small to hold the log file name.
.PP
.Ee DbLog::put
.na
.Nh
close(2), 
fcntl(2), 
fflush(3), 
fsync(2), 
lseek(2), 
malloc(3), 
memcpy(3), 
memset(3), 
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 DbLog::put
.TP 5
.Ei
.sp
The record to be logged is larger than the maximum log record.
.PP
.Ee DbLog::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 DbLog::unlink
.TP 5
.Eb
.PP
.Ee DbLog::archive
.na
.Nh
DbLog::compare(3), 
DbLog::get(3), 
close(2), 
fcntl(2), 
fflush(3), 
getcwd(3), 
malloc(3), 
memcpy(3), 
memset(3), 
open(2), 
qsort(3), 
realloc(3), 
sigfillset(3), 
sigprocmask(2), 
stat(2), 
strchr(3), 
strcmp(3), 
strcpy(3), 
strdup(3), 
strerror(3), 
strlen(3), 
and
unlink(2). 
.Hy
.ad
.PP
.Ec DbLog::archive
.TP 5
.Ei
.sp
The log was corrupted.
.PP
.Ee DbLog::db_register
.na
.Nh
close(2), 
fcntl(2), 
fflush(3), 
fsync(2), 
lseek(2), 
malloc(3), 
memcmp(3), 
memcpy(3), 
memset(3), 
open(2), 
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 DbLog::db_register
.TP 5
.Ei
.PP
.Ee DbLog::db_unregister
.na
.Nh
close(2), 
fcntl(2), 
fflush(3), 
fsync(2), 
lseek(2), 
malloc(3), 
memcpy(3), 
memset(3), 
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 DbLog::db_unregister
.TP 5
.Ei
.SH BUGS
The log files are not machine architecture independent.
Specifically, their metadata are not stored in a fixed byte order.
.SH "SEE ALSO"
.Sa