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

17.8 Numsync Extension
======================

In *note Crash recovery::, we have shown that for database recovery, one
should select the snapshot whose permission bits are read-only and whose
last-modification timestamp is greatest.  However, there may be cases
when a crash occurs at such a time that both snapshot files remain
readable.  It may also happen, that their permissions had been reset to
read-only and/or modification times inadvertently changed before
recovery.  To make it possible to select the right snapshot in such
cases, a new "extended database format" was introduced in 'GDBM' version
1.21.  This format adds to the database header the 'numsync' field,
which holds the number of synchronizations the database underwent before
being closed or abandoned due to a crash.

   A readable snapshot is a consistent copy of the database at a given
point of time.  Thus, if both snapshots of a database in extended format
are readable, it will suffice to examine their 'numsync' counters and
select the one whose 'numsync' is greater.  That's what the
'gdbm_latest_snapshot' function does in this case.

   It is worth noticing, that the two counters should differ exactly by
one.  If the difference is greater than that, 'gdbm_latest_snapshot'
will return a special status code, 'GDBM_SNAPSHOT_SUSPICIOUS'.  If,
during a recovery attempt, you get this status code, we recommend to
proceed with the manual recovery (*note Manual crash recovery::).

   To create a database in extended format, call 'gdbm_open' with both
'GDBM_NEWDB' and 'GDBM_NUMSYNC' flags:

     dbf = gdbm_open(dbfile, 0, GDBM_NEWDB|GDBM_NUMSYNC, 0600, NULL);

Notice, that this flag must always be used together with 'GDBM_NEWDB'
(*note Open::).  It is silently ignored when used together with another
opening flag.

   A standard 'GDBM' database can be converted to the extended format
and vice versa.  To convert an existing database to the extended format,
use the 'gdbm_convert' function (*note Database format::):

       rc = gdbm_convert(dbf, GDBM_NUMSYNC);

   You can do the same using the 'gdbmtool' utility (*note upgrade:
commands.):

     gdbmtool DBNAME upgrade

   To convert a database from extended format back to the standard
'GDBM' format, do:

       rc = gdbm_convert(dbf, 0);

   To do the same from the command line, run:

     gdbmtool DBNAME downgrade