17.9 Crash Tolerance API

gdbm interface: int gdbm_failure_atomic (GDBM_FILE dbf, const char *even, const char *odd)

Enables crash tolerance for the database file dbf. The even and odd arguments are the pathnames of two files that will be created and filled with snapshots of the database file. These two files must not exist when gdbm_failure_atomic is called and must reside on the same reflink-capable filesystem as the database file.

Returns 0 on success. On failure, returns -1 and sets gdbm_errno to one of the following values:

GDBM_ERR_USAGE

Improper function usage. Either even or odd is NULL, or they point to the same string.

GDBM_NEED_RECOVERY

The database needs recovery. See Recovery.

GDBM_ERR_SNAPSHOT_CLONE

Failed to clone the database file into a snapshot. Examine the system errno variable for details.

If one of the following error codes is returned, examine the system errno variable for details:

GDBM_ERR_REALPATH

Call to realpath function failed. realpath is used to determine actual path names of the snapshot files.

GDBM_FILE_OPEN_ERROR

Unable to create snapshot file.

GDBM_FILE_SYNC_ERROR

Failed to sync a snapshot file or one of directories in its pathname, during initial synchronization.

GDBM_FILE_CLOSE_ERROR

Failed to close a snapshot file or one of directories in its pathname, during initial synchronization.

GDBM_ERR_FILE_MODE

The fchmod call on one of the snapshot files failed.

Notes:

• It is not an error to call gdbm_failure_atomic several times. Each subsequent call closes the previously configured snapshot files and installs new ones instead.
• Crash tolerance settings are cleared by functions gdbm_recover (see Recovery) and gdbm_reorganize (see Reorganization). In case of gdbm_recover, it should not be a problem, because if you enabled crash tolerance, the procedure described in Crash recovery is the preferred way of recovering the database. If, however, you decided to call either function even though you had enabled crash tolerance previously, be sure to call gdbm_failure_atomic again with the same arguments as before (provided that the call returns successfully).

gdbm interface: int gdbm_latest_snapshot (const char *even, const char *odd, const char **retval)

Selects between two snapshots, even and odd, the one to be used for crash recovery. On success, stores a pointer to the selected filename in the memory location pointed to by retval and returns GDBM_SNAPSHOT_OK. If neither snapshot file is usable, the function returns GDBM_SNAPSHOT_BAD. If a system error occurs, it returns GDBM_SNAPSHOT_ERR and sets errno to the error code describing the problem. Finally, in the unlikely case that it cannot select between the two snapshots (this means they are both readable and have exactly the same mtime timestamp), the function returns GDBM_SNAPSHOT_SAME.

If the ‘numsync’ extension is enabled (see Numsync), the function can also return the GDBM_SNAPSHOT_SUSPICIOUS status code. This happens when the numsync counters in the two snapshots differ by more than one.

See Crash recovery, for a detailed description of possible return codes and their interpretation.

If any value other than GDBM_SNAPSHOT_OK is returned, it is guaranteed that the function did not touch retval. In this case it is recommended to switch to manual recovery procedure, letting the user examine the snapshots and take the appropriate action. see Manual crash recovery, for details.