DbLog



NAME

       DbLog - log management class


SYNOPSIS

       #include <db_cxx.h>

       static int
       DbLog::open(const char *dir,
            int flags, int mode, DbEnv *dbenv, DbLog **regionp);

       int
       DbLog::close();

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

       int
       DbLog::get(DbLsn *lsn, Dbt *data, int 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, int flags);

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

       int
       DbLog::archive(char **list[],
            int flags, void *(*db_malloc)(size_t));

       int
       DbLog::db_register(const Db *dbp,
            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));


DESCRIPTION

       The DB library is a family of classes that provides a mod-
       ular programming interface to transactions and record-ori-
       ented  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
       append-only file, with records identified and accessed via
       DbLsn's (database log sequence numbers).

       DbLsn's are returned on  each  DbLog::put  operation,  and
       only  those  DbLsn's  returned  by DbLog::put can later be
       used to retrieve records from the log.

  DbLog::open
       The DbLog::open method copies a pointer, to the log  iden-
       tified by the directory dir, into the memory location ref-
       erenced by regionp.

       If the dbenv argument to DbLog::open was initialized using
       DbEnv::appinit,   dir   is  interpreted  as  described  by
       DbEnv(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  is
       called.   If the log already exists, the process must have
       permission to read and write the existing files.   If  the
       log  does  not already exist, it is optionally 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.

       The  logging  subsystem  is  configured 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 DbLog::open are described below.  As refer-
       ences  to  the  DbEnv  object   may   be   maintained   by
       DbLog::open,  it  is  necessary  that the DbEnv object and
       memory  it  references  be  valid  until  the  object   is
       destroyed.   Any  of the DbEnv fields that are not explic-
       itly set will default to appropriate values.

       The following fields in the DbEnv object may  be  initial-
       ized,  using  the  appropriate  set method, before calling
       DbLog::open:


       void *(*db_errcall)(char *db_errpfx, char *buffer);
       FILE *db_errfile;
       const char *db_errpfx;
       class ostream *db_error_stream;
       int db_verbose;
            The error fields of the DbEnv behave as described for
            DbEnv(3).

       u_int32_t lg_max;
            The  maximum  size  of  a  single  file  in  the log.
            Because DbLsn 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 DbLog::open method throws a DbException(3) or  returns
       the value of errno on failure and 0 on success.

  DbLog::close
       The DbLog::close method closes the log associated with the
       DbLog object.

       In addition, if the dir argument to DbLog::open  was  NULL
       and  dbenv  was  not initialized using DbEnv::appinit, all
       files created for this shared region will be  removed,  as
       if DbLog::unlink were called.

       When  multiple  threads are using the DbLog handle concur-
       rently, only a single thread  may  call  the  DbLog::close
       method.

       The DbLog::close method throws a DbException(3) or returns
       the value of errno on failure and 0 on success.

  DbLog::flush
       The DbLog::flush method guarantees that  all  log  records
       The data field of the data object is  set  to  the  record
       retrieved and the size field indicates the number of bytes
       in the record.  See Dbt(3)  for  a  description  of  other
       fields  in  the  data  object.   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.

       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 DbLog::put method is returned in the
            data  argument.  The 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.


            If the log is empty the DbLog::get method 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 DbLsn of the
            record returned.

            If the log is empty the DbLog::get method 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
            DbLsn of the record returned.

            If  the  log  is  empty,  the  DbLog::get method 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 DbLsn of the record returned.

            If the pointer has not been initialized via DB_FIRST,
            DB_LAST, DB_SET, DB_NEXT, or DB_PREV, 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 DbLog::get method will return DB_NOTFOUND.

            If  the  log  was opened with the DB_THREAD flag set,
            calls to DbLog::get with the DB_NEXT  flag  set  will
            the DbLog::get method will return DB_NOTFOUND.

            If the log was opened with the  DB_THREAD  flag  set,
            calls  to  DbLog::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,
            DbLog::get will return EINVAL.

       DB_SET
            Retrieve the record specified by  the  lsn  argument.
            If  the  specified  DbLsn  is invalid (e.g., does not
            appear in the log) DbLog::get will return EINVAL.

       Otherwise, the DbLog::get method throws  a  DbException(3)
       or returns the value of errno on failure and 0 on success.

  DbLog::compare
       The DbLog::compare method allows the caller to compare two
       DbLsn's.   DbLog::compare returns 0 if the two DbLsn's are
       equal, 1 if lsn0 is greater than lsn1, and -1 if  lsn0  is
       less than lsn1.

  DbLog::file
       The  DbLog::file  method  maps DbLsn's to file names.  The
       DbLog::file method copies the name of the file  containing
       the  record  named  by lsn into the memory location refer-
       enced by 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.)

       The  len  argument  is  the  length of the namep buffer in
       bytes.  If namep is too  short  to  hold  the  file  name,
       DbLog::file will return ENOMEM.  Note, as described above,
       log file names are quite short, on the order of 10 charac-
       ters.

       The  DbLog::file method throws a DbException(3) or returns
       the value of errno on failure and 0 on success.

  DbLog::put
       The DbLog::put method appends records  to  the  log.   The
       DbLsn  of the put record is returned in the lsn parameter.
       The flags parameter may be set to  one  of  the  following
       values:
            Db (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 DbLsn of the
       previous log record for the same transaction,  to  support
       chaining back through the transaction's log records during
       undo.)

       The DbLog::put method throws a DbException(3)  or  returns
       the value of errno on failure and 0 on success.


  DbLog::unlink
       The  DbLog::unlink  method destroys the log region identi-
       fied by the directory dir,  removing  all  files  used  to
       implement  the  log  region.   (The  directory  dir is not
       removed.)   If  there  are  processes  that  have   called
       DbLog::open  without calling DbLog::close (i.e., there are
       processes currently using the log  region),  DbLog::unlink
       will fail without further action, unless the force flag is
       set, in which case DbLog::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 DbEnv::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 DbLog::open method, as log  region  files
       are  never  created  in  any  directory other than the one
       specified to DbLog::open.  Note, however,  that  this  has
       the  potential  to  remove  files  created by the other DB
       subsystems in this database environment.

       The  DbLog::unlink  method  throws  a  DbException(3)   or
       returns the value of errno on failure and 0 on success.

       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, 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.

       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 exclu-
       sive.

       The  DbLog::archive  method  throws  a  DbException(3)  or
       returns the value of errno on failure and 0 on success.


       The DbLog::archive method is based on  the  C  log_archive
       function,  which  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.

  DbLog::db_register
       The  DbLog::db_register  method registers a file name with
       the log manager and copies a  file  identification  number
       into  the  memory  location referenced by fidp.  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  num-
       ber mappings at each checkpoint so that a recovery process

  DbLog::db_unregister
       The DbLog::db_unregister  method  disassociates  the  file
       name  to  file  identification number mapping for the file
       identification number specified by the fid parameter.  The
       file identification number may then be reused.

       The DbLog::db_unregister method throws a DbException(3) or
       returns the value of errno on failure and 0 on success.

  DbLog::stat
       The DbLog::stat function creates a  statistical  structure
       and  copies a pointer to it into the user-specified memory
       location.

       Statistical structures 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 log statistics are  stored  in  a
       structure  of type DB_LOG_STAT (typedef'd in <db.h>).  The
       following DB_LOG_STAT fields will be filled in:

       u_long st_magic;
            The magic number that identifies  a  file  as  a  log
            file.
       u_long st_version;
            The version of the log file type.
       u_long st_mode;
            The mode of any created log files.
       u_long st_lg_max;
            The  maximum  size  of any individual file comprising
            the log.
       u_long st_written;
            The total number of bytes written to this log.
       u_long st_written_chkpt;
            The number of bytes written  since  the  last  check-
            point.
       u_long st_region_wait;
            The number of times that a process was able to obtain
            the region lock without waiting.
       u_long st_region_nowait;
            The number of times that a process was forced to wait
            before obtaining the region lock.


ENVIRONMENT VARIABLES

       The  following  environment variables affect the execution
       of db_log:

       DB_HOME
            create  the log, as described in the DbLog::open sec-
            tion above.


ERRORS

       Methods marked as returning errno will, by default,  throw
       an exception that encapsulates the error information.  The
       default error behavior can be changed, see DbException(3).

       The DbLog::open method may fail and throw a DbException(3)
       or return errno for any of the errors  specified  for  the
       following DB and library functions: 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).

       In addition, the DbLog::open method may fail and  throw  a
       DbException(3)  or  return  errno for the following condi-
       tions:

       [EAGAIN]
            The shared memory region was locked and  (repeatedly)
            unavailable.

       [EINVAL]
            An invalid flag value or parameter was specified.

            The  DB_THREAD  flag  was specified and spinlocks are
            not implemented for this architecture.

            The specified file size was too large.

       The DbLog::close method may  fail  and  throw  a  DbExcep-
       tion(3)  or  return  errno for any of the errors specified
       for the following DB and library functions: close(2),
       fcntl(2), fflush(3), munmap(2), and strerror(3).

       The  DbLog::flush  method  may  fail  and throw a DbExcep-
       tion(3) or return errno for any of  the  errors  specified
       for the following DB and library functions: 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).

       In  addition, the DbLog::flush method may fail and throw a
       DbException(3) or return errno for  the  following  condi-
       tions:

       [EINVAL]
            An invalid flag value or parameter was specified.

       tions:


       [EINVAL]
            An invalid flag value or parameter was specified.

            The DB_FIRST flag was specified and no log files were
            found.

       The DbLog::file method may fail and throw a DbException(3)
       or return errno for any of the errors  specified  for  the
       following DB and library functions: 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).

       In addition, the DbLog::file method may fail and  throw  a
       DbException(3)  or  return  errno for the following condi-
       tions:

       [ENOMEM]
            The supplied buffer was too small  to  hold  the  log
            file name.

       The  DbLog::put method may fail and throw a DbException(3)
       or return errno for any of the errors  specified  for  the
       following DB and library functions: 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).

       In  addition,  the  DbLog::put method may fail and throw a
       DbException(3) or return errno for  the  following  condi-
       tions:

       [EINVAL]
            An invalid flag value or parameter was specified.

            The  record  to  be logged is larger than the maximum
            log record.

       The DbLog::unlink method may fail  and  throw  a  DbExcep-
       tion(3)  or  return  errno for any of the errors specified
       for the following DB and library functions: 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).

       In addition, the DbLog::unlink method may fail and throw a
       DbException(3)  or  return  errno for the following condi-
       tions:


       In addition, the DbLog::archive method may fail and  throw
       a  DbException(3) or return errno for the following condi-
       tions:

       [EINVAL]
            An invalid flag value or parameter was specified.

            The log was corrupted.

       The DbLog::db_register method may fail and throw  a  DbEx-
       ception(3) or return errno for any of the errors specified
       for the following DB and library functions: 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).

       In  addition,  the  DbLog::db_register method may fail and
       throw a DbException(3) or return errno for  the  following
       conditions:

       [EINVAL]
            An invalid flag value or parameter was specified.

       The DbLog::db_unregister method may fail and throw a DbEx-
       ception(3) or return errno for any of the errors specified
       for the following DB and library functions: 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).

       In addition, the DbLog::db_unregister method may fail  and
       throw  a  DbException(3) or 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_load(1), db_recover(1), db_stat(1), db_intro(3), db_jump(3),
       db_thread(3), Db(3), Dbc(3), DbEnv(3), DbException(3), DbInfo(3),
       DbLock(3), DbLocktab(3), DbLog(3), DbLsn(3), DbMpool(3),
       DbMpoolFile(3), Dbt(3), DbTxn(3), DbTxnMgr(3)