Previous: , Up: Crash Tolerance   [Contents][Index]

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:


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


The database needs recovery. See Recovery.


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:


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


Unable to create snapshot file.


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


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


The fchmod call on one of the snapshot files failed.


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.

Previous: , Up: Crash Tolerance   [Contents][Index]