File: gdbm.info,  Node: Sync,  Next: Database format,  Prev: Reorganization,  Up: Top

11 Database Synchronization
***************************

Normally, 'GDBM' functions don't flush changed data to the disk
immediately after a change.  This allows for faster writing of databases
at the risk of having a corrupted database if the application terminates
in an abnormal fashion.  The following function allows the programmer to
make sure the disk version of the database has been completely updated
with all changes to the current time.

 -- gdbm interface: int gdbm_sync (GDBM_FILE DBF)
     Synchronizes the changes in DBF with its disk file.  The parameter
     is a pointer returned by 'gdbm_open'.

     This function would usually be called after a complete set of
     changes have been made to the database and before some long waiting
     time.  This set of changes should preserve application-level
     invariants.  In other words, call 'gdbm_sync' only when the
     database is in a consistent state with regard to the application
     logic, a state from which you are willing and able to recover.  You
     can think about all database operations between two consecutive
     'gdbm_sync' calls as constituting a single "transaction".  *Note
     Synchronizing the Database::, for a detailed discussion about how
     to properly select the synchronization points.

     The 'gdbm_close' function automatically calls the equivalent of
     'gdbm_sync' so no call is needed if the database is to be closed
     immediately after the set of changes have been made.

     'Gdbm_sync' returns 0 on success.  On error, it sets 'gdbm_errno'
     and system 'errno' variables to the codes describing the error and
     returns -1.

   Opening the database with 'GDBM_SYNC' flag ensures that 'gdbm_sync'
function will be called after each change, thereby flushing the changes
to disk immediately.  You are advised against using this flag, however,
because it incurs a severe performance penalty, while giving only a
moderate guarantee that the _structural_ consistency of the database
will be preserved in case of failure, and that only unless the failure
occurs while being in the 'fsync' call.  For the ways to ensure proper
_logical_ consistency of the database, see *note Crash Tolerance::.