db_log



NAME

       db_log - log management functions


SYNOPSIS

       On Solaris, load with -lthread:
            cc [ flag ... ] file ...  -lthread [ library ... ]

       #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(3).   For a description of the access methods, see
       db_open(3).  For a description of  cursors  within  access
       methods,  see  db_cursor(3);  transactions, see db_txn(3);
       the lock manager, see db_lock(3);  the  log  manager,  see
       db_log(3);  the memory pool manager, see db_mpool(3).  For
       information on configuring the DB  transaction  processing
       environment,  and DB support utilities, see db_appinit(3),
       db_archive(1),   db_checkpoint(1),   db_deadlock(1)    and
       db_recover(1).   For  information on dumping and reloading
       DB databases, see db_dump(1) and db_load(1).

       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_closed
       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_open(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
       characters.

       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  and  data file names and copies a pointer to them
       into the user-specified memory location list.  By default,
       log_archive  returns  the names of all log files which are
       no longer involved in  active  transactions,  and  may  be
       archived  (for catastrophic recovery) and removed from the
       system.  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
            List  only data file names in the array.  Note, it is
            possible that some of the files referenced in the log
            have since been deleted from the system.


       DB_ARCH_LOG
            List only log file names in the array and include all
            log files, regardless of  whether  or  not  they  are
            involved in active transactions.  db_appinit(3).

       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
       that utility for an example of using log_archive in a UNIX
       environment.

  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.


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_load(1), db_recover(1), db(3), db_appinit(3), db_cursor(3),
       db_dbm(3), db_lock(3), db_log(3), db_mpool(3), db_open(3),
       db_txn(3)