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);

       int
       log_stat(DB_LOG *logp, DB_LOG_STAT **spp, void *(*db_malloc)(size_t));


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
       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 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  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 the DB_ENV structure 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
       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 fields in the DB_ENV structure may  be  ini-
       tialized 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 behave 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-
       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
            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.
            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-
       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 exclu-
       sive.

       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-

       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.

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

       Statistical structure are created in allocated memory.  If
       db_malloc is non-NULL, it is called to allocate  the  mem-
       ory,  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  region  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_int32_t st_magic;
            The  magic  number  that  identifies  a file as a log
            file.
       u_int32_t st_version;
            The version of the log file type.
       int st_mode;
            The mode of any created log files.
       u_int32_t st_lg_max;
            The maximum size of any  individual  file  comprising
            the log.
       u_int32_t st_w_bytes;
            The  number of bytes over and above st_w_mbytes writ-
            ten to this log.
       u_int32_t st_w_mbytes;
            The number of megabytes written to this log.
       u_int32_t st_wc_bytes;
            The number of bytes over and above st_wc_mbytes writ-
            ten to this log since the last checkpoint.
       u_int32_t st_wc_mbytes;
            The number of megabytes written to this log since the
            last checkpoint.
       u_int32_t st_region_wait;
            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: atoi(3), close(2), db_version(3), fcntl(2),
       fflush(3), log_close(3), log_unlink(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 log_open function may fail and return er-
       rno for the following conditions:

       [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 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), fflush(3), munmap(2), and
       strerror(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), 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  log_flush function may fail and return
       errno for the following conditions:


       In  addition, the log_get function may fail and return er-
       rno 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), 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 log_file function may fail and return er-
       rno 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), 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 log_put function may fail and return  er-
       rno 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), 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 log_unlink function may fail and return
       errno for the following conditions:

       [EBUSY]
            The shared memory region was in  use  and  the  force

       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  li-
       brary 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 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 li-
       brary 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 log_unregister function may fail and  re-
       turn errno for the following conditions:

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

       The log_stat function may fail and return errno for any of
       the errors specified for  the  following  DB  and  library
       functions: fcntl(2), and malloc(3).


BUGS

       The  log  files  are not machine architecture independent.
       Specifically, log file metadata is 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_appinit(3), db_cursor(3), db_dbm(3), db_jump(3), db_lock(3),
       db_log(3), db_mpool(3), db_open(3), db_thread(3), db_txn(3)