db_log
NAME
db_log - log management functions
SYNOPSIS
#include <db.h>
int
log_open(const char *dir,
int flags, int mode, DB_ENV *dbenv, DB_LOG **regionp);
int
log_close(DB_LOG *logp);
int
log_flush(DB_LOG *logp, const DB_LSN *lsn);
int
log_get(DB_LOG *logp, DB_LSN *lsn, DBT *data, int flags);
int
log_compare(const DB_LSN *lsn0, const DB_LSN *lsn1);
int
log_file(DB_LOG *logp, const DB_LSN *lsn, char *namep, size_t len);
int
log_put(DB_LOG *logp, DB_LSN *lsn, const DBT *data, int flags);
int
log_unlink(const char *dir, int force, DB_ENV *);
int
log_archive(DB_LOG *logp,
char **list[], int flags, void *(*db_malloc)(size_t));
int
log_register(DB_LOG *logp,
const DB *dbp, const char *name, DBTYPE type, u_int32_t *fidp);
int
log_unregister(DB_LOG *logp, u_int32_t fid);
DESCRIPTION
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 func-
tions, although some functional groups are explicitly
based on other functional groups (e.g., transactions and
logging). For a general description of the DB package,
see db_intro(3).
This manual page describes the specific details of the log
manager.
These functions provide a general-purpose logging facility
sufficient for transaction management. Logs can be shared
by multiple processes.
The DB transaction log is represented by a directory con-
taining a set of files. The log is a record-oriented,
append-only file, with records identified and accessed via
DB_LSN's (database log sequence numbers).
DB_LSN's are returned on each log_put operation, and only
those DB_LSN's returned by log_put can later be used to
retrieve records from the log.
log_open
The log_open function copies a pointer, to the log identi-
fied by the directory dir, into the memory location refer-
enced by regionp.
If the dbenv argument to log_open was initialized using
db_appinit, dir is interpreted as described by
db_appinit(3).
Otherwise, if dir is not NULL, it is interpreted relative
to the current working directory of the process. If dir
is NULL, the following environment variables are checked
in order: ``TMPDIR'', ``TEMP'', and ``TMP''. If one of
them is set, log files are created relative to the direc-
tory it specifies. If none of them are set, the first
possible one of the following directories is used:
/var/tmp, /usr/tmp, /temp, /tmp, C:/temp and C:/tmp.
All files associated with the log are created in this
directory. This directory must already exist when
log_open is called. If the log already exists, the pro-
cess must have permission to read and write the existing
files. If the log does not already exist, it is option-
ally created and initialized.
If the log region is being created and log files are
already present, the log files are ``recovered'' and sub-
sequent log writes are appended to the end of the log.
The log is stored in one or more files in the specified
directory. Each file is named using the format
log.NNNNN
where ``NNNNN'' is the sequence number of the file within
the log.
The flags and mode arguments specify how files will be
opened and/or created when they don't already exist. The
flags value is specified by or'ing together one or more of
the following values:
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
Cause the DB_LOG handle returned by the log_open
function to be useable by multiple threads within a
single address space, i.e., to be ``free-threaded''.
All files created by the log subsystem are created with
mode mode (as described in chmod(2)) and modified by the
process' umask value at the time of creation (see
umask(2)). The group ownership of created files is based
on the system and directory defaults, and is not further
specified by DB.
The logging subsystem is configured based on the dbenv
argument to log_open, which is a pointer to a structure of
type DB_ENV (typedef'd in <db.h>). It is expected that
applications will use a single DB_ENV structure as the
argument to all of the subsystems in the DB package. 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
bzero(3) or memset(3).
The fields of DB_ENV used by log_open are described below.
As references to the DB_ENV structure may be maintained by
log_open, it is necessary that the DB_ENV structure and
memory it references be valid until after the log_close
function is called. If dbenv is NULL or any of its fields
are set to 0, defaults appropriate for the system are used
where possible.
The following DB_ENV fields may be initialized before
calling log_open:
void *(*db_errcall)(char *db_errpfx, char *buffer);
FILE *db_errfile;
const char *db_errpfx;
int db_verbose;
The error fields of the DB_ENV structure behave as
described for db_appinit(3).
int (*db_yield)(void);
The db_yield field of the DB_ENV structure behaves as
described for db_appinit(3).
u_int32_t lg_max;
The maximum size of a single file in the log.
Because DB_LSN file offsets are unsigned 4-byte val-
ues, lg_max may not be larger than the maximum
unsigned 4-byte value.
If lg_max is 0, a default value is used.
The log_open function returns the value of errno on fail-
ure and 0 on success.
log_close
The log_close function closes the log specified by the
logp argument.
In addition, if the dir argument to log_open was NULL and
dbenv was not initialized using db_appinit, all files cre-
ated for this shared region will be removed, as if
log_unlink were called.
When multiple threads are using the DB_LOG handle concur-
rently, only a single thread may call the log_close func-
tion.
The log_close function returns the value of errno on fail-
ure and 0 on success.
log_flush
The log_flush function guarantees that all log records
whose LSNs are less than or equal to the lsn parameter
have been written to disk. If lsn is NULL, all records in
the log are flushed.
The log_flush function returns the value of errno on fail-
ure and 0 on success.
log_get
The log_get function implements a cursor inside of the
log, retrieving records from the log according to the lsn
and flags parameters.
The data field of the data structure is set to the record
retrieved and the size field indicates the number of bytes
in the record. See db_dbt(3) for a description of other
fields in the data structure. When multiple threads are
using the returned DB_LOG handle concurrently, either the
DB_DBT_MALLOC or DB_DBT_USERMEM flags must be specified
for any DBT used for data retrieval.
The flags parameter must be set to exactly one of the fol-
lowing values:
DB_CHECKPOINT
The last record written with the DB_CHECKPOINT flag
specified to the log_put function is returned in the
data argument. The lsn argument is overwritten with
the DB_LSN 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.
If the log is empty the log_get function will return
DB_NOTFOUND.
DB_FIRST
The first record from any of the log files found in
the log directory is returned in the data argument.
The lsn argument is overwritten with the DB_LSN of
the record returned.
If the log is empty the log_get function will return
DB_NOTFOUND.
DB_LAST
The last record in the log is returned in the data
argument. The lsn argument is overwritten with the
DB_LSN of the record returned.
If the log is empty, the log_get function will return
DB_NOTFOUND.
DB_NEXT
The current log position is advanced to the next
record in the log and that record is returned in the
data argument. The lsn argument is overwritten with
the DB_LSN of the record returned.
If the pointer has not been initialized via DB_FIRST,
DB_LAST, DB_SET, DB_NEXT, or DB_PREV, log_get will
return the first record in the log. If the last log
record has already been returned or the log is empty,
the log_get function will return DB_NOTFOUND.
If the log was opened with the DB_THREAD flag set,
calls to log_get with the DB_NEXT flag set will
return EINVAL.
DB_PREV
The current log position is moved to the previous
record in the log and that record is returned in the
data argument. The lsn argument is overwritten with
the DB_LSN of the record returned.
If the pointer has not been initialized via DB_FIRST,
DB_LAST, DB_SET, DB_NEXT, or DB_PREV, log_get will
return the last record in the log. If the first log
record has already been returned or the log is empty,
the log_get function will return DB_NOTFOUND.
If the log was opened with the DB_THREAD flag set,
calls to log_get with the DB_PREV flag set will
return EINVAL.
DB_CURRENT
Return the log record currently referenced by the
log.
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,
log_get will return EINVAL.
DB_SET
Retrieve the record specified by the lsn argument.
If the specified DB_LSN is invalid (e.g., does not
appear in the log) log_get will return EINVAL.
Otherwise, the log_get function returns the value of errno
on failure and 0 on success.
log_compare
The log_compare function allows the caller to compare two
DB_LSN's. Log_compare returns 0 if the two DB_LSN's are
equal, 1 if lsn0 is greater than lsn1, and -1 if lsn0 is
less than lsn1.
log_file
The log_file function maps DB_LSN's to file names. The
log_file function copies the name of the file containing
the record named by lsn into the memory location refer-
enced by namep. (This mapping of DB_LSN to file is needed
for database administration. For example, a transaction
manager typically records the earliest DB_LSN needed for
restart, and the database administrator may want to
archive log files to tape when they contain only DB_LSN's
before the earliest one needed for restart.)
The len argument is the length of the namep buffer in
bytes. If namep is too short to hold the file name,
log_file will return ENOMEM. Note, as described above,
log file names are quite short, on the order of 10 charac-
ters.
The log_file function returns the value of errno on fail-
ure and 0 on success.
log_put
The log_put function appends records to the log. The
DB_LSN of the put record is returned in the lsn parameter.
The flags parameter may be set to one of the following
values:
DB_CHECKPOINT
The log should write a checkpoint record, recording
any information necessary to make the log structures
recoverable after a crash.
DB_FLUSH
The log is forced to disk after this record is writ-
ten, guaranteeing that all records with DB_LSNs less
than or equal to the one being put are on disk before
this function returns (this function is most often
used for a transaction commit, see db_txn(3)).
The caller is responsible for providing any necessary
structure to data. (For example, in a write-ahead logging
protocol, the application must understand what part of
data is an operation code, what part is redo information,
and what part is undo information. In addition, most
transaction managers will store in data the DB_LSN of the
previous log record for the same transaction, to support
chaining back through the transaction's log records during
undo.)
The log_put function returns the value of errno on failure
and 0 on success.
log_unlink
The log_unlink function destroys the log region identified
by the directory dir, removing all files used to implement
the log region. (The log files themselves and the direc-
tory dir are not removed.) If there are processes that
have called log_open without calling log_close (i.e.,
there are processes currently using the log region),
log_unlink will fail without further action, unless the
force flag is set, in which case log_unlink will attempt
to remove the log region files regardless of any processes
still using the log region.
The result of attempting to forcibly destroy the region
when a process has the region open is unspecified. Pro-
cesses 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 log
region will either fail or attempt to create a new region.
On other systems, e.g., WNT, where the unlink(2) system
call will fail if any process has an open file descriptor
for the file, the region removal will fail.
In the case of catastrophic or system failure, database
recovery must be performed (see db_recovery(1) or the
DB_RECOVER flags to db_appinit(3)). Alternatively, if
recovery is not required because no database state is
maintained across failures, it is possible to clean up a
log region by removing all of the files in the directory
specified to the log_open function, as log region files
are never created in any directory other than the one
specified to log_open. Note, however, that this has the
potential to remove files created by the other DB subsys-
tems in this database environment.
The log_unlink function returns the value of errno on
failure and 0 on success.
log_archive
The log_archive function creates a NULL-terminated array
of log or database file names and copies a pointer to them
into the user-specified memory location list.
By default, log_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 sys-
tem. If there were no file names to return, list will be
set to NULL.
Arrays of log file names are created in allocated memory.
If db_malloc is non-NULL, it is called to allocate the
memory, otherwise, the library function malloc(3) is used.
The function db_malloc must match the calling conventions
of the 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.
The flags argument is specified by or'ing together one or
more of the following values:
DB_ARCH_ABS
All pathnames are returned as absolute pathnames,
instead of relative to the database home directory.
DB_ARCH_DATA
Return the database files that need to be archived in
order to recover the database from catastrophic fail-
ure. If any of the database files have not been
accessed during the lifetime of the current log
files, log_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.
DB_ARCH_LOG
Return all the log file names regardless of whether
or not they are in use.
The DB_ARCH_DATA and DB_ARCH_LOG flags are mutually
exclusive.
The log_archive function returns the value of errno on
failure and 0 on success.
The log_archive function is the underlying function used
by the db_archive(1) utility. See the source code for the
db_archive utility for an example of using log_archive in
a UNIX environment. See the db_archive(1) manual page for
more information on database archival procedures.
log_register
The log_register function registers a file name with the
log manager and copies a file identification number into
the memory location referenced by fidp. This file identi-
fication number should be used in all subsequent log mes-
sages that refer to operations on this file. The log man-
ager 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.
The log_register function is called when an access method
registers the open of a file. The dbp parameter should be
a pointer to the DB structure which is being returned by
the access method.
The type parameter should be one of the DB types specified
in db_open(3), e.g., DB_HASH.
The log_register function returns the value of errno on
failure and 0 on success.
log_unregister
The log_unregister function disassociates the file name to
file identification number mapping for the file identifi-
cation number specified by the fid parameter. The file
identification number may then be reused.
The log_unregister function returns the value of errno on
failure and 0 on success.
ENVIRONMENT VARIABLES
The following environment variables affect the execution
of db_log:
DB_HOME
If the dbenv argument to log_open was initialized
using db_appinit, the environment variable DB_HOME
may be used as the path of the database home for the
interpretation of the dir argument to log_open, as
described in db_appinit(3). Specifically, log_open
is affected by the configuration string value of
DB_LOG_DIR.
TMPDIR
If the dbenv argument to log_open was NULL or not
initialized using db_appinit, the environment vari-
able TMPDIR may be used as the directory in which to
create the log, as described in the log_open section
above.
COMPILING
On IRIX, if you are compiling a threaded application, you
must compile with the -D_SGI_MP_SOURCE flag:
cc -D_SGI_MP_SOURCE ...
On OSF/1, if you are compiling a threaded application, you
must compile with the -D_REENTRANT flag:
cc -D_REENTRANT ...
On Solaris, if you are compiling a threaded application,
you must compile with the -D_REENTRANT flag and link with
the -lthread library:
cc -D_REENTRANT ... -lthread
ERRORS
The log_open function may fail and return errno for any of
the errors specified for the following DB and library
functions: close(2), fcntl(2), fstat(2), getpid(2),
lseek(2), mmap(2), open(2), read(2), unlink(2), write(2),
abort(3), atoi(3), closedir(3), db_version(3), fflush(3),
free(3), getenv(3), isdigit(3), llseek(3), log_unlink(3),
malloc(3), memcpy(3), memset(3), opendir(3), readdir(3),
realloc(3), sigfillset(3), sigprocmask(3), snprintf(3),
stat(3), strcpy(3), strdup(3), strerror(3), strlen(3),
strncmp(3), strrchr(3) and vsnprintf(3).
In addition, the log_open function may fail and return
errno for the following conditions:
[EAGAIN]
The shared memory region was locked and (repeatedly)
unavailable.
[EINVAL]
An invalid flag value or parameter was specified.
TMPDIR If the dbenv argument to _open was NULL or not
initialized using db_appinit, the environment vari-
able TMPDIR may be used as the directory in which to
create the , as described in the _open section above.
The specified file size was too large.
The log_close function may fail and return errno for any
of the errors specified for the following DB and library
functions: close(2), fcntl(2), getpid(2), munmap(2),
fflush(3), strerror(3) and vsnprintf(3).
The log_flush function may fail and return errno for any
of the errors specified for the following DB and library
functions: close(2), fcntl(2), fsync(2), getpid(2),
lseek(2), open(2), unlink(2), write(2), abort(3),
fflush(3), getenv(3), isdigit(3), llseek(3), malloc(3),
memcpy(3), memset(3), sigfillset(3), sigprocmask(3),
snprintf(3), stat(3), strcpy(3), strdup(3), strerror(3),
strlen(3) and vsnprintf(3).
In addition, the log_flush function may fail and return
errno for the following conditions:
[EINVAL]
An invalid flag value or parameter was specified.
The log_get function may fail and return errno for any of
the errors specified for the following DB and library
functions: close(2), fcntl(2), getpid(2), lseek(2),
open(2), read(2), unlink(2), abort(3), fflush(3), free(3),
getenv(3), isdigit(3), llseek(3), malloc(3), memcpy(3),
memset(3), realloc(3), sigfillset(3), sigprocmask(3),
snprintf(3), stat(3), strcpy(3), strdup(3), strerror(3),
strlen(3) and vsnprintf(3).
In addition, the log_get function may fail and return
errno for the following conditions:
[EINVAL]
An invalid flag value or parameter was specified.
The DB_FIRST flag was specified and no log files were
found.
The log_file function may fail and return errno for any of
the errors specified for the following DB and library
functions: close(2), fcntl(2), getpid(2), open(2),
unlink(2), abort(3), fflush(3), getenv(3), isdigit(3),
malloc(3), memcpy(3), memset(3), sigfillset(3), sigproc-
mask(3), snprintf(3), stat(3), strcpy(3), strdup(3), str-
error(3), strlen(3) and vsnprintf(3).
In addition, the log_file function may fail and return
errno for the following conditions:
[ENOMEM]
The supplied buffer was too small to hold the log
file name.
The log_put function may fail and return errno for any of
the errors specified for the following DB and library
functions: close(2), fcntl(2), fsync(2), getpid(2),
lseek(2), open(2), unlink(2), write(2), abort(3),
fflush(3), free(3), getenv(3), isdigit(3), llseek(3), mal-
loc(3), memcpy(3), memset(3), sigfillset(3), sigproc-
mask(3), snprintf(3), stat(3), strcpy(3), strdup(3), str-
error(3), strlen(3), time(3) and vsnprintf(3).
In addition, the log_put function may fail and return
errno for the following conditions:
[EINVAL]
An invalid flag value or parameter was specified.
The record to be logged is larger than the maximum
log record.
The log_unlink function may fail and return errno for any
of the errors specified for the following DB and library
functions: close(2), fcntl(2), fstat(2), getpid(2),
mmap(2), munmap(2), open(2), unlink(2), abort(3),
fflush(3), getenv(3), isdigit(3), malloc(3), memcpy(3),
memset(3), sigfillset(3), sigprocmask(3), stat(3), str-
cpy(3), strdup(3), strerror(3), strlen(3) and
vsnprintf(3).
In addition, the log_unlink function may fail and return
errno for the following conditions:
[EBUSY]
The shared memory region was in use and the force
flag was not set.
The log_archive function may fail and return errno for any
of the errors specified for the following DB and library
functions: close(2), fcntl(2), getpid(2), lseek(2),
open(2), read(2), unlink(2), abort(3), getcwd(3),
fflush(3), free(3), getenv(3), isdigit(3), llseek(3), mal-
loc(3), memcpy(3), memset(3), realloc(3), sigfillset(3),
sigprocmask(3), snprintf(3), stat(3), strcpy(3),
strdup(3), strerror(3), strlen(3) and vsnprintf(3).
In addition, the log_archive function may fail and return
errno for the following conditions:
[EINVAL]
An invalid flag value or parameter was specified.
The log was corrupted.
The log_register function may fail and return errno for
any of the errors specified for the following DB and
library functions: close(2), fcntl(2), fsync(2), get-
pid(2), lseek(2), open(2), unlink(2), write(2), abort(3),
fflush(3), free(3), getenv(3), isdigit(3), llseek(3), mal-
loc(3), memcmp(3), memcpy(3), memset(3), realloc(3), sig-
fillset(3), sigprocmask(3), snprintf(3), stat(3), str-
cpy(3), strdup(3), strerror(3), strlen(3), time(3) and
vsnprintf(3).
In addition, the log_register function may fail and return
errno for the following conditions:
[EINVAL]
An invalid flag value or parameter was specified.
The log_unregister function may fail and return errno for
any of the errors specified for the following DB and
library functions: fcntl(2), getpid(2), fflush(3) and
vsnprintf(3).
In addition, the log_unregister function may fail and
return errno for the following conditions:
[EINVAL]
An invalid flag value or parameter was specified.
BUGS
The log files are not machine architecture independent.
Specifically, their metadata are not stored in a fixed
byte order.
SEE ALSO
db_archive(1), db_checkpoint(1), db_deadlock(1), db_dump(1),
db_intro(3), db_load(1), db_recover(1), db_stat(1),
db_appinit(3), db_cursor(3), db_dbm(3), db_lock(3), db_log(3),
db_mpool(3), db_open(3), db_txn(3)