File: gdbm.info,  Node: Errors,  Next: Database consistency,  Prev: Flat files,  Up: Top

14 Error handling
*****************

The global variable 'gdbm_errno' (*note gdbm_errno: Variables.) keeps
the error code of the most recent error encountered by 'GDBM' functions.

   To convert this code to human-readable string, use the following
function:

 -- gdbm interface: const char * gdbm_strerror (gdbm_error ERRNO)
     Converts ERRNO (an integer value) into a human-readable descriptive
     text.  Returns a pointer to a static string.  The caller must not
     free the returned pointer or alter the string it points to.

   Detailed information about the most recent error that occurred while
operating on a 'GDBM' file is stored in the 'GDBM_FILE' object itself.
To retrieve it, the following functions are provided:

 -- gdbm interface: gdbm_error gdbm_last_errno (GDBM_FILE DBF)
     Returns the code of the most recent error encountered when
     operating on DBF.

     When 'gdbm_last_errno' called immediately after the failed
     function, its return equals the value of the 'gdbm_errno' variable.
     However, 'gdbm_errno' can be changed if any 'GDBM' functions
     (operating on another databases) were called afterwards, and
     'gdbm_last_errno' will always return the code of the last error
     that occurred while working with _that_ database.

 -- gdbm interface: int gdbm_last_syserr (GDBM_FILE DBF)
     Returns the value of the system 'errno' variable associated with
     the most recent error.

     Notice, that not all 'GDBM' errors have an associated system error
     code.  The following are the ones that have:

        * GDBM_FILE_OPEN_ERROR
        * GDBM_FILE_WRITE_ERROR
        * GDBM_FILE_SEEK_ERROR
        * GDBM_FILE_READ_ERROR
        * GDBM_FILE_STAT_ERROR
        * GDBM_BACKUP_FAILED
        * GDBM_FILE_CLOSE_ERROR
        * GDBM_FILE_SYNC_ERROR
        * GDBM_FILE_TRUNCATE_ERROR
        * GDBM_ERR_SNAPSHOT_CLONE
        * GDBM_ERR_REALPATH
        * GDBM_ERR_USAGE

     For other errors, 'gdbm_last_syserr' will return 0.

 -- gdbm interface: int gdbm_check_syserr (gdbm_errno ERR)
     Returns '1', if the system 'errno' value should be inspected to get
     more info on the error described by 'GDBM' error code ERR.

   To get a human-readable description of the recent error for a
particular database file, use the 'gdbm_db_strerror' function:

 -- gdbm interface: const char * gdbm_db_strerror (GDBM_FILE DBF)
     Returns textual description of the most recent error encountered
     when operating on the database DBF.  The resulting string is often
     more informative than what would be returned by
     'gdbm_strerror(gdbm_last_errno(DBF))'.  In particular, if there is
     a system error associated with the recent failure, it will be
     described as well.

 -- gdbm interface: void gdbm_clear_error (GDBM_FILE DBF)
     Clears the error state for the database DBF.  Normally, this
     function is called upon the entry to any 'GDBM' function.

   Certain errors (such as write error when saving stored key) can leave
database file in inconsistent state (*note Database consistency::).
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'.  Additionally, the following
function can be used to check the state of the database file:

 -- gdbm interface: int gdbm_needs_recovery (GDBM_FILE DBF)
     Returns '1' if the database file DBF is in inconsistent state and
     needs recovery.

   To restore structural consistency of the database, use the
'gdbm_recover' function (*note Recovery::).

   Crash tolerance provides a better way of recovery, because it
restores both structural and logical consistency.  *Note Crash
Tolerance::, for a detailed discussion,