File: gdbm.info,  Node: Crash Tolerance API,  Prev: Numsync,  Up: Crash Tolerance

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.  *Note 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' (*note Recovery::) and 'gdbm_reorganize' (*note
          Reorganization::).  In case of 'gdbm_recover', it should not
          be a problem, because if you enabled crash tolerance, the
          procedure described in *note 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 (*note 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.

     *Note 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.  *note
     Manual crash recovery::, for details.