Merging upstream version 1.15~pre1.

Signed-off-by: Daniel Baumann <mail@daniel-baumann.ch>

3 files changed, 179 insertions, 123 deletions

diff --git a/doc/lziprecover.1 b/doc/lziprecover.1
index f62094a..fce7640 100644
--- a/doc/lziprecover.1
+++ b/doc/lziprecover.1
@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.37.1.
-.TH LZIPRECOVER "1" "May 2013" "Lziprecover 1.14" "User Commands"
+.TH LZIPRECOVER "1" "June 2013" "Lziprecover 1.15-pre1" "User Commands"
 .SH NAME
 Lziprecover \- recovers data from damaged lzip files
 .SH SYNOPSIS
diff --git a/doc/lziprecover.info b/doc/lziprecover.info
index 83267d5..0d39838 100644
--- a/doc/lziprecover.info
+++ b/doc/lziprecover.info
@@ -12,16 +12,18 @@ File: lziprecover.info,  Node: Top,  Next: Introduction,  Up: (dir)
 Lziprecover Manual
 ******************
 
-This manual is for Lziprecover (version 1.14, 31 May 2013).
+This manual is for Lziprecover (version 1.15-pre1, 17 June 2013).
 
 * Menu:
 
-* Introduction::          Purpose and features of lziprecover
-* Invoking Lziprecover::  Command line interface
-* File Format::           Detailed format of the compressed file
-* Examples::              A small tutorial with examples
-* Problems::              Reporting bugs
-* Concept Index::         Index of concepts
+* Introduction::           Purpose and features of lziprecover
+* Invoking Lziprecover::   Command line interface
+* Repairing Files::        Fixing bit-flip and similar errors
+* Merging Files::          Fixing several damaged copies
+* File Format::            Detailed format of the compressed file
+* Examples::               A small tutorial with examples
+* Problems::               Reporting bugs
+* Concept Index::          Index of concepts
 
 
    Copyright (C) 2009, 2010, 2011, 2012, 2013 Antonio Diaz Diaz.
@@ -37,14 +39,15 @@ File: lziprecover.info,  Node: Introduction,  Next: Invoking Lziprecover,  Prev:
 
 Lziprecover is a data recovery tool and decompressor for files in the
 lzip compressed data format (.lz) able to repair slightly damaged files,
-recover badly damaged files from two or more copies, extract undamaged
-members from multi-member files, decompress files and test integrity of
-files.
+recover badly damaged files from two or more copies, extract data from
+damaged files, decompress files and test integrity of files.
 
    Lziprecover is able to recover or decompress files produced by any of
 the compressors in the lzip family; lzip, plzip, minilzip/lzlib, clzip
-and pdlzip. This recovery capability contributes to make the lzip format
-one of the best options for long-term data archiving.
+and pdlzip. It makes lzip files resistant to bit-flip, one of the most
+common forms of data corruption, and its recovery capabilities
+contribute to make of the lzip format one of the best options for
+long-term data archiving.
 
    Lziprecover is able to efficiently extract a range of bytes from a
 multi-member file, because it only decompresses the members containing
@@ -61,19 +64,22 @@ damaged files themselves are never modified.
    When decompressing or testing file integrity, lziprecover behaves
 like lzip or lunzip.
 
-   If the files are too damaged for lziprecover to repair them, data
-from damaged members can be partially recovered writing it to stdout as
-shown in the following example (the resulting file may contain some
-garbage data at the end):
+   If a file is too damaged for lziprecover to repair it, all the
+recoverable data in all members of the file can be extracted with the
+following command (the resulting file may contain errors and some
+garbage data may be produced at the end of each member):
 
-     lziprecover -cd rec01file.lz > rec01file
+     lziprecover -D0 -i -o file -q file.lz
 
    If the cause of file corruption is damaged media, the combination
 GNU ddrescue + lziprecover is the best option for recovering data from
 multiple damaged copies. *Note ddrescue-example::, for an example.
 
+   Lziprecover is not a replacement for regular backups, but a last
+line of defense for the case where the backups are also damaged.
+
 
-File: lziprecover.info,  Node: Invoking Lziprecover,  Next: File Format,  Prev: Introduction,  Up: Top
+File: lziprecover.info,  Node: Invoking Lziprecover,  Next: Repairing Files,  Prev: Introduction,  Up: Top
 
 2 Invoking Lziprecover
 **********************
@@ -141,18 +147,10 @@ The format for running lziprecover is:
 `-m'
 `--merge'
      Try to produce a correct file merging the good parts of two or more
-     damaged copies. The copies must be single-member files. The merge
-     will fail if the copies have too many damaged areas or if the same
-     byte is damaged in all copies. If successful, a repaired copy is
-     written to the file `FILE_fixed.lz'. The exit status is 0 if the
-     file could be repaired, 2 otherwise.
-
-     To give you an idea of its possibilities, when merging two copies
-     each of them with one damaged area affecting 1 percent of the
-     copy, the probability of obtaining a correct file is about 98
-     percent. With three such copies the probability rises to 99.97
-     percent. For large files with small errors, the probability
-     approaches 100 percent even with only two copies.
+     damaged copies. If successful, a repaired copy is written to the
+     file `FILE_fixed.lz'. The exit status is 0 if a correct file could
+     be produced, 2 otherwise. See the chapter Merging Files (*note
+     Merging Files::) for a complete description of the merge mode.
 
 `-o FILE'
 `--output=FILE'
@@ -168,10 +166,12 @@ The format for running lziprecover is:
 
 `-R'
 `--repair'
-     Try to repair a small error, affecting only one byte, in a
-     single-member FILE. If successful, a repaired copy is written to
-     the file `FILE_fixed.lz'. `FILE' is not modified at all.  The exit
-     status is 0 if the file could be repaired, 2 otherwise.
+     Try to repair a file with small errors (up to one byte error per
+     member).  If successful, a repaired copy is written to the file
+     `FILE_fixed.lz'. `FILE' is not modified at all.  The exit status
+     is 0 if the file could be repaired, 2 otherwise.  See the chapter
+     Repairing Files (*note Repairing Files::) for a complete
+     description of the repair mode.
 
 `-s'
 `--split'
@@ -227,9 +227,52 @@ invalid input file, 3 for an internal consistency error (eg, bug) which
 caused lziprecover to panic.
 
 
-File: lziprecover.info,  Node: File Format,  Next: Examples,  Prev: Invoking Lziprecover,  Up: Top
+File: lziprecover.info,  Node: Repairing Files,  Next: Merging Files,  Prev: Invoking Lziprecover,  Up: Top
+
+3 Repairing Files
+*****************
+
+Lziprecover is able to repair files with small errors (up to one byte
+error per member). The error may be located anywhere in the file except
+in the header (first 6 bytes of each member) or in the `Member size'
+field of the trailer (last 8 bytes of each member). This makes lzip
+files resistant to bit-flip, one of the most common forms of data
+corruption.
+
+   Bit-flip happens when one bit in the file is changed from 0 to 1 or
+vice versa. It may be caused by bad RAM or even by natural radiation. I
+have seen a case of bit-flip in a file stored in an USB flash drive.
+
+
+File: lziprecover.info,  Node: Merging Files,  Next: File Format,  Prev: Repairing Files,  Up: Top
+
+4 Merging Files
+***************
+
+If you have several copies of a file but all of them are too damaged to
+repair them (*note Repairing Files::), lziprecover can try to produce a
+correct file merging the good parts of the damaged copies.
+
+   The merge may succeed even if some copies of the file have all the
+headers and trailers damaged, as long as there is at least one copy of
+every header and trailer intact, even if they are in different copies of
+the file.
+
+   The merge will fail if the damaged areas overlap (at least one byte
+is damaged in all copies), or are adjacent and the boundary can't be
+determined, or if the copies have too many damaged areas.
+
+   To give you an idea of its possibilities, when merging two copies
+each of them with one damaged area affecting 1 percent of the copy, the
+probability of obtaining a correct file is about 98 percent. With three
+such copies the probability rises to 99.97 percent. For large files with
+small errors, the probability approaches 100 percent even with only two
+copies.
+
+
+File: lziprecover.info,  Node: File Format,  Next: Examples,  Prev: Merging Files,  Up: Top
 
-3 File Format
+5 File Format
 *************
 
 Perfection is reached, not when there is no longer anything to add, but
@@ -302,7 +345,7 @@ additional information before, between, or after them.
 
 File: lziprecover.info,  Node: Examples,  Next: Problems,  Prev: File Format,  Up: Top
 
-4 A small tutorial with examples
+6 A small tutorial with examples
 ********************************
 
 Example 1: Restore a regular file from its compressed version
@@ -329,9 +372,8 @@ to decompressed byte 15000 (5000 bytes are produced).
      lziprecover -D 10000-15000 file.lz
 
 
-Example 5: Repair a one-byte corruption in the single-member file
-`file.lz'. (Indented lines are abridged error messages from
-lziprecover).
+Example 5: Repair small errors in the file `file.lz'. (Indented lines
+are abridged diagnostic messages from lziprecover).
 
      lziprecover -v -R file.lz
        Copy of input file repaired successfully.
@@ -365,31 +407,16 @@ error-checked merging of copies (*Note GNU ddrescue manual:
 Example 8: Recover the first volume of those created with the command
 `lzip -b 32MiB -S 650MB big_db' from two copies, `big_db1_00001.lz' and
 `big_db2_00001.lz', with member 07 damaged in the first copy, member 18
-damaged in the second copy, and member 12 damaged in both copies. Two
-correct copies are produced and compared.
-
-     lziprecover -s big_db1_00001.lz
-     lziprecover -s big_db2_00001.lz
-     lziprecover -t rec*big_db1_00001.lz
-       rec07big_db1_00001.lz: crc mismatch
-       rec12big_db1_00001.lz: crc mismatch
-     lziprecover -t rec*big_db2_00001.lz
-       rec12big_db2_00001.lz: crc mismatch
-       rec18big_db2_00001.lz: crc mismatch
-     lziprecover -m -v rec12big_db1_00001.lz rec12big_db2_00001.lz
+damaged in the second copy, and member 12 damaged in both copies. The
+correct file produced is saved in `big_db_00001.lz'.
+
+     lziprecover -m -v -o big_db_00001.lz big_db1_00001.lz big_db2_00001.lz
        Input files merged successfully
-     cp rec07big_db2_00001.lz rec07big_db1_00001.lz
-     cp rec12big_db1_00001_fixed.lz rec12big_db1_00001.lz
-     cp rec12big_db1_00001_fixed.lz rec12big_db2_00001.lz
-     cp rec18big_db1_00001.lz rec18big_db2_00001.lz
-     cat rec*big_db1_00001.lz > big_db3_00001.lz
-     cat rec*big_db2_00001.lz > big_db4_00001.lz
-     zcmp big_db3_00001.lz big_db4_00001.lz
 
 
 File: lziprecover.info,  Node: Problems,  Next: Concept Index,  Prev: Examples,  Up: Top
 
-5 Reporting Bugs
+7 Reporting Bugs
 ****************
 
 There are probably bugs in lziprecover. There are certainly errors and
@@ -415,19 +442,23 @@ Concept Index
 * file format:                           File Format.           (line 6)
 * getting help:                          Problems.              (line 6)
 * introduction:                          Introduction.          (line 6)
-* invoking lziprecover:                  Invoking Lziprecover.  (line 6)
+* invoking:                              Invoking Lziprecover.  (line 6)
+* merging files:                         Merging Files.         (line 6)
+* repairing files:                       Repairing Files.       (line 6)
 
 
 
 Tag Table:
 Node: Top231
-Node: Introduction901
-Node: Invoking Lziprecover2685
-Node: File Format8447
-Node: Examples10938
-Ref: ddrescue-example12158
-Node: Problems13938
-Node: Concept Index14488
+Node: Introduction1032
+Node: Invoking Lziprecover3052
+Node: Repairing Files8489
+Node: Merging Files9208
+Node: File Format10338
+Node: Examples12822
+Ref: ddrescue-example14024
+Node: Problems15134
+Node: Concept Index15684
 
 End Tag Table
 
diff --git a/doc/lziprecover.texinfo b/doc/lziprecover.texinfo
index 142cdae..54834e9 100644
--- a/doc/lziprecover.texinfo
+++ b/doc/lziprecover.texinfo
@@ -6,8 +6,8 @@
 @finalout
 @c %**end of header
 
-@set UPDATED 31 May 2013
-@set VERSION 1.14
+@set UPDATED 17 June 2013
+@set VERSION 1.15-pre1
 
 @dircategory Data Compression
 @direntry
@@ -35,12 +35,14 @@
 This manual is for Lziprecover (version @value{VERSION}, @value{UPDATED}).
 
 @menu
-* Introduction::          Purpose and features of lziprecover
-* Invoking Lziprecover::  Command line interface
-* File Format::           Detailed format of the compressed file
-* Examples::              A small tutorial with examples
-* Problems::              Reporting bugs
-* Concept Index::         Index of concepts
+* Introduction::           Purpose and features of lziprecover
+* Invoking Lziprecover::   Command line interface
+* Repairing Files::        Fixing bit-flip and similar errors
+* Merging Files::          Fixing several damaged copies
+* File Format::            Detailed format of the compressed file
+* Examples::               A small tutorial with examples
+* Problems::               Reporting bugs
+* Concept Index::          Index of concepts
 @end menu
 
 @sp 1
@@ -56,14 +58,15 @@ to copy, distribute and modify it.
 
 Lziprecover is a data recovery tool and decompressor for files in the
 lzip compressed data format (.lz) able to repair slightly damaged files,
-recover badly damaged files from two or more copies, extract undamaged
-members from multi-member files, decompress files and test integrity of
-files.
+recover badly damaged files from two or more copies, extract data from
+damaged files, decompress files and test integrity of files.
 
 Lziprecover is able to recover or decompress files produced by any of
 the compressors in the lzip family; lzip, plzip, minilzip/lzlib, clzip
-and pdlzip. This recovery capability contributes to make the lzip format
-one of the best options for long-term data archiving.
+and pdlzip. It makes lzip files resistant to bit-flip, one of the most
+common forms of data corruption, and its recovery capabilities
+contribute to make of the lzip format one of the best options for
+long-term data archiving.
 
 Lziprecover is able to efficiently extract a range of bytes from a
 multi-member file, because it only decompresses the members containing
@@ -80,23 +83,26 @@ damaged files themselves are never modified.
 When decompressing or testing file integrity, lziprecover behaves like
 lzip or lunzip.
 
-If the files are too damaged for lziprecover to repair them, data from
-damaged members can be partially recovered writing it to stdout as shown
-in the following example (the resulting file may contain some garbage
-data at the end):
+If a file is too damaged for lziprecover to repair it, all the
+recoverable data in all members of the file can be extracted with the
+following command (the resulting file may contain errors and some
+garbage data may be produced at the end of each member):
 
 @example
-lziprecover -cd rec01file.lz > rec01file
+lziprecover -D0 -i -o file -q file.lz
 @end example
 
 If the cause of file corruption is damaged media, the combination
 @w{GNU ddrescue + lziprecover} is the best option for recovering data
 from multiple damaged copies. @xref{ddrescue-example}, for an example.
 
+Lziprecover is not a replacement for regular backups, but a last line of
+defense for the case where the backups are also damaged.
+
 
 @node Invoking Lziprecover
 @chapter Invoking Lziprecover
-@cindex invoking lziprecover
+@cindex invoking
 
 The format for running lziprecover is:
 
@@ -164,18 +170,10 @@ information about the members in the file.
 @item -m
 @itemx --merge
 Try to produce a correct file merging the good parts of two or more
-damaged copies. The copies must be single-member files. The merge will
-fail if the copies have too many damaged areas or if the same byte is
-damaged in all copies. If successful, a repaired copy is written to the
-file @samp{@var{file}_fixed.lz}. The exit status is 0 if the file could
-be repaired, 2 otherwise.
-
-To give you an idea of its possibilities, when merging two copies each
-of them with one damaged area affecting 1 percent of the copy, the
-probability of obtaining a correct file is about 98 percent. With three
-such copies the probability rises to 99.97 percent. For large files with
-small errors, the probability approaches 100 percent even with only two
-copies.
+damaged copies. If successful, a repaired copy is written to the file
+@samp{@var{file}_fixed.lz}. The exit status is 0 if a correct file could
+be produced, 2 otherwise. See the chapter Merging Files (@pxref{Merging
+Files}) for a complete description of the merge mode.
 
 @item -o @var{file}
 @itemx --output=@var{file}
@@ -192,10 +190,12 @@ Quiet operation. Suppress all messages.
 
 @item -R
 @itemx --repair
-Try to repair a small error, affecting only one byte, in a single-member
-@var{file}. If successful, a repaired copy is written to the file
+Try to repair a file with small errors (up to one byte error per member).
+If successful, a repaired copy is written to the file
 @samp{@var{file}_fixed.lz}. @samp{@var{file}} is not modified at all.
 The exit status is 0 if the file could be repaired, 2 otherwise.
+See the chapter Repairing Files (@pxref{Repairing Files}) for a complete
+description of the repair mode.
 
 @item -s
 @itemx --split
@@ -252,6 +252,47 @@ invalid input file, 3 for an internal consistency error (eg, bug) which
 caused lziprecover to panic.
 
 
+@node Repairing Files
+@chapter Repairing Files
+@cindex repairing files
+
+Lziprecover is able to repair files with small errors (up to one byte
+error per member). The error may be located anywhere in the file except
+in the header (first 6 bytes of each member) or in the @samp{Member
+size} field of the trailer (last 8 bytes of each member). This makes
+lzip files resistant to bit-flip, one of the most common forms of data
+corruption.
+
+Bit-flip happens when one bit in the file is changed from 0 to 1 or vice
+versa. It may be caused by bad RAM or even by natural radiation. I have
+seen a case of bit-flip in a file stored in an USB flash drive.
+
+
+@node Merging Files
+@chapter Merging Files
+@cindex merging files
+
+If you have several copies of a file but all of them are too damaged to
+repair them (@pxref{Repairing Files}), lziprecover can try to produce a
+correct file merging the good parts of the damaged copies.
+
+The merge may succeed even if some copies of the file have all the
+headers and trailers damaged, as long as there is at least one copy of
+every header and trailer intact, even if they are in different copies of
+the file.
+
+The merge will fail if the damaged areas overlap (at least one byte is
+damaged in all copies), or are adjacent and the boundary can't be
+determined, or if the copies have too many damaged areas.
+
+To give you an idea of its possibilities, when merging two copies each
+of them with one damaged area affecting 1 percent of the copy, the
+probability of obtaining a correct file is about 98 percent. With three
+such copies the probability rises to 99.97 percent. For large files with
+small errors, the probability approaches 100 percent even with only two
+copies.
+
+
 @node File Format
 @chapter File Format
 @cindex file format
@@ -368,9 +409,8 @@ lziprecover -D 10000-15000 file.lz
 
 @sp 1
 @noindent
-Example 5: Repair a one-byte corruption in the single-member file
-@samp{file.lz}. (Indented lines are abridged error messages from
-lziprecover).
+Example 5: Repair small errors in the file @samp{file.lz}. (Indented
+lines are abridged diagnostic messages from lziprecover).
 
 @example
 lziprecover -v -R file.lz
@@ -422,27 +462,12 @@ Example 8: Recover the first volume of those created with the command
 @w{@code{lzip -b 32MiB -S 650MB big_db}} from two copies,
 @samp{big_db1_00001.lz} and @samp{big_db2_00001.lz}, with member 07
 damaged in the first copy, member 18 damaged in the second copy, and
-member 12 damaged in both copies. Two correct copies are produced and
-compared.
+member 12 damaged in both copies. The correct file produced is saved in
+@samp{big_db_00001.lz}.
 
 @example
-lziprecover -s big_db1_00001.lz
-lziprecover -s big_db2_00001.lz
-lziprecover -t rec*big_db1_00001.lz
-  rec07big_db1_00001.lz: crc mismatch
-  rec12big_db1_00001.lz: crc mismatch
-lziprecover -t rec*big_db2_00001.lz
-  rec12big_db2_00001.lz: crc mismatch
-  rec18big_db2_00001.lz: crc mismatch
-lziprecover -m -v rec12big_db1_00001.lz rec12big_db2_00001.lz
+lziprecover -m -v -o big_db_00001.lz big_db1_00001.lz big_db2_00001.lz
   Input files merged successfully
-cp rec07big_db2_00001.lz rec07big_db1_00001.lz
-cp rec12big_db1_00001_fixed.lz rec12big_db1_00001.lz
-cp rec12big_db1_00001_fixed.lz rec12big_db2_00001.lz
-cp rec18big_db1_00001.lz rec18big_db2_00001.lz
-cat rec*big_db1_00001.lz > big_db3_00001.lz
-cat rec*big_db2_00001.lz > big_db4_00001.lz
-zcmp big_db3_00001.lz big_db4_00001.lz
 @end example