14 Error handling

The global variable gdbm_errno (see gdbm_errno) 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 (see 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 (see Recovery).

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