Merging upstream version 1.15~rc1.

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

1 files changed, 161 insertions, 69 deletions

diff --git a/doc/lziprecover.info b/doc/lziprecover.info
index 0d39838..a15f890 100644
--- a/doc/lziprecover.info
+++ b/doc/lziprecover.info
@@ -3,7 +3,7 @@ lziprecover.texinfo.
 
 INFO-DIR-SECTION Data Compression
 START-INFO-DIR-ENTRY
-* Lziprecover: (lziprecover).   Data recovery tool for lzipped files
+* Lziprecover: (lziprecover).   Data recovery tool for lzip files
 END-INFO-DIR-ENTRY
 
 
@@ -12,18 +12,19 @@ File: lziprecover.info,  Node: Top,  Next: Introduction,  Up: (dir)
 Lziprecover Manual
 ******************
 
-This manual is for Lziprecover (version 1.15-pre1, 17 June 2013).
+This manual is for Lziprecover (version 1.15-rc1, 29 July 2013).
 
 * Menu:
 
 * 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
+* 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
+* Unzcrash::               Testing the robustness of decompressors
 * Problems::               Reporting bugs
-* Concept Index::          Index of concepts
+* Concept index::          Index of concepts
 
 
    Copyright (C) 2009, 2010, 2011, 2012, 2013 Antonio Diaz Diaz.
@@ -32,22 +33,38 @@ This manual is for Lziprecover (version 1.15-pre1, 17 June 2013).
 copy, distribute and modify it.
 
 
-File: lziprecover.info,  Node: Introduction,  Next: Invoking Lziprecover,  Prev: Top,  Up: Top
+File: lziprecover.info,  Node: Introduction,  Next: Invoking lziprecover,  Prev: Top,  Up: Top
 
 1 Introduction
 **************
 
 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 data from
-damaged files, decompress files and test integrity of files.
+lzip compressed data format (.lz), able to repair slightly damaged
+files, recover badly damaged files from two or more copies, extract data
+from damaged files, decompress files and test integrity of files.
+
+   The lzip file format is designed for long-term data archiving. It is
+clean, provides very safe 4 factor integrity checking, and is backed by
+the recovery capabilities of lziprecover.
 
    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. 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.
+and pdlzip.
+
+   Lziprecover makes lzip files resistant to bit-flip (one of the most
+common forms of data corruption), and can safely merge multiple damaged
+backup copies.
+
+   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.
+
+   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 -D0 -i -o file -q file.lz
 
    Lziprecover is able to efficiently extract a range of bytes from a
 multi-member file, because it only decompresses the members containing
@@ -64,24 +81,13 @@ damaged files themselves are never modified.
    When decompressing or testing file integrity, lziprecover behaves
 like lzip or lunzip.
 
-   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 -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: Repairing Files,  Prev: Introduction,  Up: Top
+File: lziprecover.info,  Node: Invoking lziprecover,  Next: Repairing files,  Prev: Introduction,  Up: Top
 
-2 Invoking Lziprecover
+2 Invoking lziprecover
 **********************
 
 The format for running lziprecover is:
@@ -149,8 +155,8 @@ The format for running lziprecover is:
      Try to produce a correct file merging the good parts of two or more
      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.
+     be produced, 2 otherwise. See the chapter `Merging files' (*note
+     Merging files::) for a complete description of the merge mode.
 
 `-o FILE'
 `--output=FILE'
@@ -167,10 +173,10 @@ The format for running lziprecover is:
 `-R'
 `--repair'
      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
+     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
+     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'
@@ -199,12 +205,11 @@ The format for running lziprecover is:
 `--verbose'
      Verbose mode.
      When decompressing or testing, further -v's (up to 4) increase the
-     verbosity level, showing status, dictionary size, compression
-     ratio, trailer contents (CRC, data size, member size), and up to 6
+     verbosity level, showing status, compression ratio, dictionary
+     size, trailer contents (CRC, data size, member size), and up to 6
      bytes of trailing garbage (if any).
 
 
-
    Numbers given as arguments to options may be followed by a multiplier
 and an optional `B' for "byte".
 
@@ -227,9 +232,9 @@ invalid input file, 3 for an internal consistency error (eg, bug) which
 caused lziprecover to panic.
 
 
-File: lziprecover.info,  Node: Repairing Files,  Next: Merging Files,  Prev: Invoking Lziprecover,  Up: Top
+File: lziprecover.info,  Node: Repairing files,  Next: Merging files,  Prev: Invoking lziprecover,  Up: Top
 
-3 Repairing Files
+3 Repairing files
 *****************
 
 Lziprecover is able to repair files with small errors (up to one byte
@@ -244,13 +249,13 @@ 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
+File: lziprecover.info,  Node: Merging files,  Next: File format,  Prev: Repairing files,  Up: Top
 
-4 Merging Files
+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
+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
@@ -262,17 +267,31 @@ the file.
 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
+   All the copies must have the same size. If some of them have been
+truncated and are therefore smaller than they should, you can extend
+them to the correct size with the following command before merging them
+with the other copies:
+
+     ddrescue --extend-outfile=<correct_size> small_file.lz extended_file.lz
+
+   If some of the copies have got garbage data at the end and are
+therefore larger than they should, you can reduce their sizes to the
+correct value with the following command before merging them with the
+other copies:
+
+     ddrescue --size=<correct_size> large_file.lz reduced_file.lz
+
+   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.
+such copies the probability rises to 99.97 percent. For large files (a
+few MB) with small errors (one sector damaged per copy), the probability
+approaches 100 percent even with only two copies.
 
 
-File: lziprecover.info,  Node: File Format,  Next: Examples,  Prev: Merging Files,  Up: Top
+File: lziprecover.info,  Node: File format,  Next: Examples,  Prev: Merging files,  Up: Top
 
-5 File Format
+5 File format
 *************
 
 Perfection is reached, not when there is no longer anything to add, but
@@ -343,7 +362,7 @@ additional information before, between, or after them.
 
 
 
-File: lziprecover.info,  Node: Examples,  Next: Problems,  Prev: File Format,  Up: Top
+File: lziprecover.info,  Node: Examples,  Next: Unzcrash,  Prev: File format,  Up: Top
 
 6 A small tutorial with examples
 ********************************
@@ -381,8 +400,8 @@ are abridged diagnostic messages from lziprecover).
 
 
 Example 6: Split the multi-member file `file.lz' and write each member
-in its own `recXXXXXfile.lz' file. Then use `lziprecover -t' to test
-the integrity of the resulting files.
+in its own `recXXXfile.lz' file. Then use `lziprecover -t' to test the
+integrity of the resulting files.
 
      lziprecover -s file.lz
      lziprecover -tv rec*file.lz
@@ -401,7 +420,7 @@ error-checked merging of copies (*Note GNU ddrescue manual:
      mount -t iso9660 -o loop,ro cdimage2 /mnt/cdimage
      cp /mnt/cdimage/backup.tar.lz rescued2.tar.lz
      umount /mnt/cdimage
-     lziprecover -m -v -o rescued.tar.lz rescued1.tar.lz rescued2.tar.lz
+     lziprecover -m -v -o backup.tar.lz rescued1.tar.lz rescued2.tar.lz
 
 
 Example 8: Recover the first volume of those created with the command
@@ -414,9 +433,80 @@ correct file produced is saved in `big_db_00001.lz'.
        Input files merged successfully
 
 
-File: lziprecover.info,  Node: Problems,  Next: Concept Index,  Prev: Examples,  Up: Top
+File: lziprecover.info,  Node: Unzcrash,  Next: Problems,  Prev: Examples,  Up: Top
+
+7 Testing the robustness of decompressors
+*****************************************
+
+The lziprecover package also includes unzcrash, a program written to
+test robustness to decompression of corrupted data, inspired by
+unzcrash.c from Julian Seward's bzip2. Type `make unzcrash' in the
+lziprecover source directory to build it.
+
+   Unzcrash reads the specified file and then repeatedly decompresses
+it, increasing 256 times each byte of the compressed data, so as to
+test all possible one-byte errors. This should not cause any invalid
+memory accesses. If it does, please, report it as a bug.
+
+   Unzcrash really executes as a subprocess the shell command specified
+in the first non-option argument, and then writes the file specified in
+the second non-option argument to the standard input of the subprocess,
+modifying the corresponding byte each time. Therefore you can use
+unzcrash to test any decompressor (not only lzip), or even other decoder
+programs with a suitable command line syntax.
+
+   The format for running unzcrash is:
+
+     unzcrash [OPTIONS] "lzip -tv" FILENAME.lz
+
+   Unzcrash supports the following options:
+
+`-h'
+`--help'
+     Print an informative help message describing the options and exit.
+
+`-V'
+`--version'
+     Print the version number of lziprecover on the standard output and
+     exit.
+
+`-b RANGE'
+`--bits=RANGE'
+     Test N-bit errors only, instead of testing all the 255 wrong
+     values for each byte. `N-bit error' means any value differing from
+     the original value in N bit positions, not a value differing from
+     the original value in the bit position N.
+     The number of N-bit errors per byte (N = 1 to 8) is: 8 28 56 70 56
+     28 8 1
+     Examples of RANGE:  1  1,2,3  1-4  1,3-5,8  1-3,5-8
+
+`-p BYTES'
+`--position=BYTES'
+     First byte position to test in the file. Defaults to 0.
+
+`-q'
+`--quiet'
+     Quiet operation. Suppress all messages.
+
+`-s BYTES'
+`--size=BYTES'
+     Number of byte positions to test. If not specified, the whole file
+     is tested.
+
+`-v'
+`--verbose'
+     Verbose mode.
+
+
+   Exit status: 0 for a normal exit, 1 for environmental problems (file
+not found, invalid flags, I/O errors, etc), 2 to indicate a corrupt or
+invalid input file, 3 for an internal consistency error (eg, bug) which
+caused unzcrash to panic.
+
+
+File: lziprecover.info,  Node: Problems,  Next: Concept index,  Prev: Unzcrash,  Up: Top
 
-7 Reporting Bugs
+8 Reporting bugs
 ****************
 
 There are probably bugs in lziprecover. There are certainly errors and
@@ -429,9 +519,9 @@ for all eternity, if not longer.
 by running `lziprecover --version'.
 
 
-File: lziprecover.info,  Node: Concept Index,  Prev: Problems,  Up: Top
+File: lziprecover.info,  Node: Concept index,  Prev: Problems,  Up: Top
 
-Concept Index
+Concept index
 *************
 
 
@@ -439,26 +529,28 @@ Concept Index
 
 * bugs:                                  Problems.              (line 6)
 * examples:                              Examples.              (line 6)
-* file format:                           File Format.           (line 6)
+* file format:                           File format.           (line 6)
 * getting help:                          Problems.              (line 6)
 * introduction:                          Introduction.          (line 6)
-* invoking:                              Invoking Lziprecover.  (line 6)
-* merging files:                         Merging Files.         (line 6)
-* repairing files:                       Repairing Files.       (line 6)
+* invoking:                              Invoking lziprecover.  (line 6)
+* merging files:                         Merging files.         (line 6)
+* repairing files:                       Repairing files.       (line 6)
+* unzcrash:                              Unzcrash.              (line 6)
 
 
 
 Tag Table:
-Node: Top231
-Node: Introduction1032
-Node: Invoking Lziprecover3052
-Node: Repairing Files8489
-Node: Merging Files9208
-Node: File Format10338
-Node: Examples12822
-Ref: ddrescue-example14024
-Node: Problems15134
-Node: Concept Index15684
+Node: Top228
+Node: Introduction1095
+Node: Invoking lziprecover3248
+Node: Repairing files8686
+Node: Merging files9405
+Node: File format11176
+Node: Examples13660
+Ref: ddrescue-example14860
+Node: Unzcrash15969
+Node: Problems18344
+Node: Concept index18894
 
 End Tag Table