File: gdbm.info,  Node: Recovery,  Next: Crash Tolerance,  Prev: Database consistency,  Up: Top

16 Recovering structural consistency
************************************

Certain errors (such as write error when saving stored key) can leave
database file in "structurally inconsistent state".  When such a
critical error occurs, the database file is marked as needing recovery.
Subsequent calls to any GDBM functions for that database file (except
'gdbm_recover'), will return immediately with 'GDBM' error code
'GDBM_NEED_RECOVERY'.

   To escape from this state and bring the database back to operational
state, use the following function:

 -- gdbm interface: int gdbm_recover (GDBM_FILE DBF, gdbm_recovery
          *RCVR, int FLAGS)
     Check the database file DBF and fix eventual errors.  The RCVR
     argument points to a structure that has "input members", providing
     additional information to alter the behavior of 'gdbm_recover', and
     "output members", which are used to return additional statistics
     about the recovery process (RCVR can be 'NULL' if no such
     information is needed).

     Each input member has a corresponding flag bit, which must be set
     in FLAGS, in order to instruct the function to use it.

     The 'gdbm_recover' type is defined as:

          typedef struct gdbm_recovery_s
          {
            /* Input members.
               These are initialized before call to gdbm_recover.
               The flags argument specifies which of them are initialized. */
            void (*errfun) (void *data, char const *fmt, ...);
            void *data;
            size_t max_failed_keys;
            size_t max_failed_buckets;
            size_t max_failures;

            /* Output members.
               The gdbm_recover function fills these before returning. */
            size_t recovered_keys;
            size_t recovered_buckets;
            size_t failed_keys;
            size_t failed_buckets;
            char *backup_name;
          } gdbm_recovery;

     The "input members" modify the behavior of 'gdbm_recover':

      -- input member of gdbm_recovery: void (*errfun) (void *DATA, char
               const *FMT, ...)
          If the 'GDBM_RCVR_ERRFUN' flag bit is set, 'errfun' points to
          a function that will be called upon each recoverable or
          non-fatal error that occurred during the recovery.  The 'data'
          field of 'gdbm_recovery' will be passed to it as its first
          argument.  The FMT argument is a 'printf'-like (*note
          (printf(3))Format of the format string::), format string.  The
          rest of arguments supply parameters for that format.

      -- input member of gdbm_recovery: void * data
          Supplies first argument for the 'errfun' invocations.

      -- input member of gdbm_recovery: size_t max_failed_keys
          If 'GDBM_RCVR_MAX_FAILED_KEYS' is set, this member sets the
          limit on the number of keys that cannot be retrieved.  If the
          number of failed keys becomes equal to 'max_failed_keys',
          recovery is aborted and error is returned.

      -- input member of gdbm_recovery: size_t max_failed_buckets
          If 'GDBM_RCVR_MAX_FAILED_BUCKETS' is set, this member sets the
          limit on the number of buckets that cannot be retrieved or
          that contain bogus information.  If the number of failed
          buckets becomes equal to 'max_failed_buckets', recovery is
          aborted and error is returned.

      -- output member of gdbm_recovery: size_t max_failures
          If 'GDBM_RCVR_MAX_FAILURES' is set, this member sets the limit
          of failures that are tolerated during recovery.  If the number
          of errors becomes equal to 'max_failures', recovery is aborted
          and error is returned.

     The following members are filled on output, upon successful return
     from the function:

      -- output member of gdbm_recovery: size_t recovered_keys
          Number of recovered keys.

      -- output member of gdbm_recovery: size_t recovered_buckets
          Number of recovered buckets.

      -- output member of gdbm_recovery: size_t failed_keys
          Number of key/data pairs that could not be retrieved.

      -- output member of gdbm_recovery: size_t failed_buckets
          Number of buckets that could not be retrieved.

      -- output member of gdbm_recovery: char * backup_name
          Name of the file keeping the copy of the original database, in
          the state prior to recovery.  It is filled if the
          GDBM_RCVR_BACKUP flag is set.  The string is allocated using
          the 'malloc' call.  The caller is responsible for freeing that
          memory when no longer needed.

   By default, 'gdbm_recovery' first checks the database for
inconsistencies and attempts recovery only if some were found.  The
special flag bit 'GDBM_RCVR_FORCE' instructs 'gdbm_recovery' to omit
this check and to perform database recovery unconditionally.