Merging upstream version 1.15~rc1.

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

1 files changed, 150 insertions, 56 deletions

diff --git a/doc/lziprecover.texinfo b/doc/lziprecover.texinfo
index 54834e9..e2aed0a 100644
--- a/doc/lziprecover.texinfo
+++ b/doc/lziprecover.texinfo
@@ -6,19 +6,19 @@
 @finalout
 @c %**end of header
 
-@set UPDATED 17 June 2013
-@set VERSION 1.15-pre1
+@set UPDATED 29 July 2013
+@set VERSION 1.15-rc1
 
 @dircategory Data Compression
 @direntry
-* Lziprecover: (lziprecover).   Data recovery tool for lzipped files
+* Lziprecover: (lziprecover).   Data recovery tool for lzip files
 @end direntry
 
 
 @ifnothtml
 @titlepage
 @title Lziprecover
-@subtitle Data recovery tool for lzipped files
+@subtitle Data recovery tool for lzip files
 @subtitle for Lziprecover version @value{VERSION}, @value{UPDATED}
 @author by Antonio Diaz Diaz
 
@@ -36,13 +36,14 @@ This manual is for Lziprecover (version @value{VERSION}, @value{UPDATED}).
 
 @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
 @end menu
 
 @sp 1
@@ -57,16 +58,34 @@ to copy, distribute and modify it.
 @cindex 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
+@w{GNU ddrescue + lziprecover} is the best option for recovering data
+from multiple damaged copies. @xref{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):
+
+@example
+lziprecover -D0 -i -o file -q file.lz
+@end example
 
 Lziprecover is able to efficiently extract a range of bytes from a
 multi-member file, because it only decompresses the members containing
@@ -83,25 +102,12 @@ 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):
-
-@example
-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
+@node Invoking lziprecover
+@chapter Invoking lziprecover
 @cindex invoking
 
 The format for running lziprecover is:
@@ -172,8 +178,8 @@ information about the members in the file.
 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
 @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.
+be produced, 2 otherwise. See the chapter @samp{Merging files}
+(@pxref{Merging files}) for a complete description of the merge mode.
 
 @item -o @var{file}
 @itemx --output=@var{file}
@@ -190,11 +196,11 @@ Quiet operation. Suppress all messages.
 
 @item -R
 @itemx --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
+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
+The exit status is 0 if the file could be repaired, 2 otherwise. See the
+chapter @samp{Repairing files} (@pxref{Repairing files}) for a complete
 description of the repair mode.
 
 @item -s
@@ -221,13 +227,12 @@ Use it together with @samp{-v} to see information about the file.
 @itemx --verbose
 Verbose mode.@*
 When decompressing or testing, further -v's (up to 4) increase the
-verbosity level, showing status, dictionary size, compression ratio,
+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).
 
 @end table
 
-@sp 1
 Numbers given as arguments to options may be followed by a multiplier
 and an optional @samp{B} for "byte".
 
@@ -252,8 +257,8 @@ invalid input file, 3 for an internal consistency error (eg, bug) which
 caused lziprecover to panic.
 
 
-@node Repairing Files
-@chapter Repairing Files
+@node Repairing files
+@chapter Repairing files
 @cindex repairing files
 
 Lziprecover is able to repair files with small errors (up to one byte
@@ -268,12 +273,12 @@ 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
+@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
+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
@@ -285,16 +290,33 @@ 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
+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:
+
+@example
+ddrescue --extend-outfile=<correct_size> small_file.lz extended_file.lz
+@end example
+
+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:
+
+@example
+ddrescue --size=<correct_size> large_file.lz reduced_file.lz
+@end example
+
+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.
 
 
-@node File Format
-@chapter File Format
+@node File format
+@chapter File format
 @cindex file format
 
 Perfection is reached, not when there is no longer anything to add, but
@@ -421,7 +443,7 @@ mv file_fixed.lz file.lz
 @sp 1
 @noindent
 Example 6: Split the multi-member file @samp{file.lz} and write each
-member in its own @samp{recXXXXXfile.lz} file. Then use
+member in its own @samp{recXXXfile.lz} file. Then use
 @w{@samp{lziprecover -t}} to test the integrity of the resulting files.
 
 @example
@@ -453,13 +475,13 @@ ddrescue -b2048 /dev/cdrom cdimage2 logfile2
 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
 @end example
 
 @sp 1
 @noindent
 Example 8: Recover the first volume of those created with the command
-@w{@code{lzip -b 32MiB -S 650MB big_db}} from two copies,
+@w{@samp{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. The correct file produced is saved in
@@ -471,8 +493,80 @@ lziprecover -m -v -o big_db_00001.lz big_db1_00001.lz big_db2_00001.lz
 @end example
 
 
+@node Unzcrash
+@chapter Testing the robustness of decompressors
+@cindex unzcrash
+
+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 @samp{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:
+
+@example
+unzcrash [@var{options}] "lzip -tv" @var{filename}.lz
+@end example
+
+Unzcrash supports the following options:
+
+@table @samp
+@item -h
+@itemx --help
+Print an informative help message describing the options and exit.
+
+@item -V
+@itemx --version
+Print the version number of lziprecover on the standard output and exit.
+
+@item -b @var{range}
+@itemx --bits=@var{range}
+Test N-bit errors only, instead of testing all the 255 wrong values for
+each byte. @samp{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 @var{range}:  1  1,2,3  1-4  1,3-5,8  1-3,5-8
+
+@item -p @var{bytes}
+@itemx --position=@var{bytes}
+First byte position to test in the file. Defaults to 0.
+
+@item -q
+@itemx --quiet
+Quiet operation. Suppress all messages.
+
+@item -s @var{bytes}
+@itemx --size=@var{bytes}
+Number of byte positions to test. If not specified, the whole file is
+tested.
+
+@item -v
+@itemx --verbose
+Verbose mode.
+
+@end table
+
+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.
+
+
 @node Problems
-@chapter Reporting Bugs
+@chapter Reporting bugs
 @cindex bugs
 @cindex getting help
 
@@ -486,8 +580,8 @@ If you find a bug in lziprecover, please send electronic mail to
 find by running @w{@samp{lziprecover --version}}.
 
 
-@node Concept Index
-@unnumbered Concept Index
+@node Concept index
+@unnumbered Concept index
 
 @printindex cp