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 $?
0
    

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"?>
<recovery_report>
  <rotation_recovery>false</rotation_recovery>
  <journal_real_path>jf_tut_foo-journal</journal_real_path>
  <analyze_damaged_journal>false</analyze_damaged_journal>
  <journal_last_pos>16512</journal_last_pos>
  <damaged_journal>false</damaged_journal>
  <recovery_pending_status>true</recovery_pending_status>
  <patches>
   <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>
    </append>
   </patch>
  </patches>
  <new_journal_last_pos>28</new_journal_last_pos>
  <patches>
   <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>
    </append>
   </patch>
  </patches>
  <new_journal_last_pos>29</new_journal_last_pos>
  <write_rollback_record/>
</recovery_report>
    

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 $?
3
    

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:

• jf_recover executed in "test mode" has to check for "recovery pending" status, so "0", means "OK, recovery pending is TRUE"

• you can concatenate jf_recover in a shell script using the compact form "&&":

  jf_recover -j <journal_name> -t -df && jf_recover -j <journal_name>
  	

  a recovery phase is performed only if the journal is in "recovery pending status".