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 (see Format of the format string in printf(3) man page), 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.