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)