3.4. The recovery pending status

What happens when an application or the whole operating system crashes?

After a crash, a journal and some of its journaled files, may be in "recovery pending" status: the journal contains all the necessary information to fix journaled files, but journaled files content may be not consistent.

The previous examples are trivial and inconsistency does not happen, but... please remove previous journal and journaled files, and execute again two_files_crash program:

tiian@linux:~/tutorial> rm jf_tut_foo-*
tiian@linux:~/tutorial> ./two_files_crash
Floating point exception
Now execute the utility program jf_recover specifying "test mode" and check the return code:
tiian@linux:~/tutorial> jf_recover -j jf_tut_foo-journal -t
tiian@linux:~/tutorial> echo $?
please take a look to on-line help:
tiian@linux:~/tutorial> jf_recover -h
Usage: jf_recover -j JOURNALFILENAME [-t [-d{n|h|t|f}] ] [-f]
Recover all files journaled by JOURNALFILENAME

        -j : specify the name of the journal file must be host FILE
        -t : test only mode, useful to understand if recovery is necessary
             exit code values:
                0 - recovery is necessary
                1 - forced recovery is necessary
                2 - an error happened
                3 - recovery is not necessary
        -d : specifies which data must be dumped to output (test only mode)
                -dn   no data are dumped (essential dump)
                -dh   hexadecimal format data dump
                -dt   text format data dump
                -df   full (hexadecimal and text) data dump
        -f : forced recovery mode, useful to recover a damaged journal;
             use only as a LAST resource
        -h : print this help
as the help explain, if "0" is returned, a recovery is necessary: this is exactly what we expect because the application crashed and libjf is part of the application, so libjf crashed with the application and the journaled files needs a recovery phase. To discover which operations will be performed by jf_recover, try:
tiian@linux:~/tutorial> jf_recover -j jf_tut_foo-journal -t -dt
<?xml version="1.0" encoding="UTF-8"?>
   <patch type="redo">
    <append jrn_rec_off='16512' file_id='1' size='28' offset='0'>
      <data type='redo' format='text'>First string for first file </data>
   <patch type="redo">
    <append jrn_rec_off='16556' file_id='2' size='29' offset='0'>
      <data type='redo' format='text'>First string for second file </data>
jf_recover discovered two patches must be applied to journaled files and a rollback record must be written on journal: so we have just discovered ours journaled files incidentally are OK, but application crashed before libjf was able to mark the "no recovery pending status" (this behavior is the consequence of some optimizations: if you sync your files at every step, the resulting system becomes unusable).

OK, we discovered our journal is in "recovery pending" and the operations will be performed, do them and check the status a second time:

tiian@linux:~/tutorial> jf_recover -j jf_tut_foo-journal
tiian@linux:~/tutorial> jf_recover -j jf_tut_foo-journal -t
tiian@linux:~/tutorial> echo $?
Now journal is not in "recovery pending" status and data in journaled files can be safely accessed by any application, for example a utility command like cat or more...

Why jf_recover returns "0", "OK" code, if the journal is in "recovery pending" status? There are two reasons:

3.4.1. Automatic recovery

Can an application open a journal in "recovery pending" status without a previous execution of utility program jf_recover?

Can an application open a journal in "recovery pending" status without a previous execution of utility program jf_recover?

Yes, but it's not the default behavior because recovery is a potential dangerous operation and I think it's not a good thing someone takes a decision without asking you!

The boolean recovery_enabled field of jf_journal_opts_s struct, passed to jf_journal_open method, must be set to TRUE if you want automatic cold recovery feature active; the boolean field recovery_damaged_journal does the same when the journal is damaged: pay attention a damaged journal is a very serious situation will probably lead to data corruption (do you have a backup of your files?!).

"libjf API reference guide" documents all the available options.