summaryrefslogtreecommitdiffstats
path: root/doc/lziprecover.info
diff options
context:
space:
mode:
authorDaniel Baumann <mail@daniel-baumann.ch>2015-11-07 11:42:39 +0000
committerDaniel Baumann <mail@daniel-baumann.ch>2015-11-07 11:42:39 +0000
commit04d72dd06c3c49fcc61e5ae7b8cee112d34e8df1 (patch)
treeaadf6684ddb287ecaaa4bfc482ab8859ce3742cb /doc/lziprecover.info
parentAdding debian version 1.15~pre1-2. (diff)
downloadlziprecover-04d72dd06c3c49fcc61e5ae7b8cee112d34e8df1.tar.xz
lziprecover-04d72dd06c3c49fcc61e5ae7b8cee112d34e8df1.zip
Merging upstream version 1.15~rc1.
Signed-off-by: Daniel Baumann <mail@daniel-baumann.ch>
Diffstat (limited to 'doc/lziprecover.info')
-rw-r--r--doc/lziprecover.info230
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