summaryrefslogtreecommitdiffstats
path: root/doc/lziprecover.texi
diff options
context:
space:
mode:
authorDaniel Baumann <mail@daniel-baumann.ch>2015-11-07 11:53:09 +0000
committerDaniel Baumann <mail@daniel-baumann.ch>2015-11-07 11:53:09 +0000
commit746479a2d915d02f6f02ec508202afb1face7c2b (patch)
tree1d26867f949791b0e2ba99246aa252f02e693cef /doc/lziprecover.texi
parentAdding debian version 1.18~pre1-1. (diff)
downloadlziprecover-746479a2d915d02f6f02ec508202afb1face7c2b.tar.xz
lziprecover-746479a2d915d02f6f02ec508202afb1face7c2b.zip
Merging upstream version 1.18~pre2.
Signed-off-by: Daniel Baumann <mail@daniel-baumann.ch>
Diffstat (limited to 'doc/lziprecover.texi')
-rw-r--r--doc/lziprecover.texi101
1 files changed, 82 insertions, 19 deletions
diff --git a/doc/lziprecover.texi b/doc/lziprecover.texi
index 29045e7..e29a59f 100644
--- a/doc/lziprecover.texi
+++ b/doc/lziprecover.texi
@@ -6,8 +6,8 @@
@finalout
@c %**end of header
-@set UPDATED 30 June 2015
-@set VERSION 1.18-pre1
+@set UPDATED 16 September 2015
+@set VERSION 1.18-pre2
@dircategory Data Compression
@direntry
@@ -42,6 +42,7 @@ This manual is for Lziprecover (version @value{VERSION}, @value{UPDATED}).
* Merging files:: Fixing several damaged copies
* File names:: Names of the files produced by lziprecover
* File format:: Detailed format of the compressed file
+* Trailing data:: Extra data appended to the file
* Examples:: A small tutorial with examples
* Unzcrash:: Testing the robustness of decompressors
* Problems:: Reporting bugs
@@ -75,7 +76,7 @@ The lzip format provides very safe integrity checking and some data
recovery means. The lziprecover program can repair bit-flip errors (one
of the most common forms of data corruption) in lzip files, and provides
data recovery capabilities, including error-checked merging of damaged
-copies of a file.
+copies of a file. @xref{Data safety}.
@item
The lzip format is as simple as possible (but not simpler). The lzip
@@ -152,6 +153,13 @@ Print an informative help message describing the options and exit.
@itemx --version
Print the version number of lziprecover on the standard output and exit.
+@anchor{--trailing-error}
+@item -a
+@itemx --trailing-error
+Exit with error status 2 if any remaining input is detected after
+decompressing the last member. Such remaining input is usually trailing
+garbage that can be safely ignored. @xref{concat-example}.
+
@item -c
@itemx --stdout
Decompress to standard output. Needed when reading from a named pipe
@@ -160,7 +168,9 @@ data as possible when decompressing a corrupt file.
@item -d
@itemx --decompress
-Decompress.
+Decompress the specified file(s). If a file fails to decompress,
+lziprecover exits immediately without decompressing the rest of the
+files.
@item -D @var{range}
@itemx --range-decompress=@var{range}
@@ -246,7 +256,9 @@ on the number of members in @samp{@var{file}}.
@itemx --test
Check integrity of the specified file(s), but don't decompress them.
This really performs a trial decompression and throws away the result.
-Use it together with @samp{-v} to see information about the file.
+Use it together with @samp{-v} to see information about the file(s). If
+a file fails the test, lziprecover continues checking the rest of the
+files.
@item -v
@itemx --verbose
@@ -254,7 +266,7 @@ Verbose mode.@*
When decompressing or testing, further -v's (up to 4) increase the
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).
+trailing data (if any).
@end table
@@ -456,7 +468,7 @@ Each member has the following structure:
All multibyte values are stored in little endian order.
@table @samp
-@item ID string
+@item ID string (the "magic" bytes)
A four byte string, identifying the lzip format, with the value "LZIP"
(0x4C, 0x5A, 0x49, 0x50).
@@ -499,6 +511,44 @@ facilitates safe recovery of undamaged members from multi-member files.
@end table
+@node Trailing data
+@chapter Extra data appended to the file
+@cindex trailing data
+
+Sometimes extra data is found appended to a lzip file after the last
+member. Such trailing data may be:
+
+@itemize @bullet
+@item
+Padding added to make the file size a multiple of some block size, for
+example when writing to a tape.
+
+@item
+Garbage added by some not totally successful copy operation.
+
+@item
+Useful data added by the user; a cryptographically secure hash, a
+description of file contents, etc.
+
+@item
+Malicious data added to the file in order to make its total size and
+hash value (for a chosen hash) coincide with those of another file.
+
+@item
+In very rare cases, trailing data could be the corrupt header of another
+member. In multi-member or concatenated files the probability of
+corruption happening in the magic bytes is 5 times smaller than the
+probability of getting a false positive caused by the corruption of the
+integrity information itself. Therefore it can be considered to be below
+the noise level.
+@end itemize
+
+Trailing data can be safely ignored in most cases. In some cases, like
+user-added data, it is expected to be ignored. In those cases where a
+file containing trailing data must be rejected, the option
+@samp{--trailing-error} can be used. @xref{--trailing-error}.
+
+
@node Examples
@chapter A small tutorial with examples
@cindex examples
@@ -521,8 +571,21 @@ lziprecover -tv file.lz
@end example
@sp 1
+@anchor{concat-example}
+@noindent
+Example 3: The right way of concatenating compressed files.
+@xref{Trailing data}.
+
+@example
+Don't do this
+ cat file1.lz file2.lz file3.lz | lziprecover -d
+Do this instead
+ lziprecover -cd file1.lz file2.lz file3.lz
+@end example
+
+@sp 1
@noindent
-Example 3: Decompress @samp{file.lz} partially until 10 KiB of
+Example 4: Decompress @samp{file.lz} partially until 10 KiB of
decompressed data are produced.
@example
@@ -531,7 +594,7 @@ lziprecover -D 0,10KiB file.lz
@sp 1
@noindent
-Example 4: Decompress @samp{file.lz} partially from decompressed byte
+Example 5: Decompress @samp{file.lz} partially from decompressed byte
10000 to decompressed byte 15000 (5000 bytes are produced).
@example
@@ -540,20 +603,20 @@ lziprecover -D 10000-15000 file.lz
@sp 1
@noindent
-Example 5: Repair small errors in the file @samp{file.lz}. (Indented
+Example 6: Repair small errors in the file @samp{file.lz}. (Indented
lines are abridged diagnostic messages from lziprecover).
@example
lziprecover -v -R file.lz
Copy of input file repaired successfully.
lziprecover -tv file_fixed.lz
- ok
+ file_fixed.lz: ok
mv file_fixed.lz file.lz
@end example
@sp 1
@noindent
-Example 6: Split the multi-member file @samp{file.lz} and write each
+Example 7: Split the multi-member file @samp{file.lz} and write each
member in its own @samp{recXXXfile.lz} file. Then use
@w{@samp{lziprecover -t}} to test the integrity of the resulting files.
@@ -565,8 +628,8 @@ lziprecover -tv rec*file.lz
@sp 1
@anchor{ddrescue-example}
@noindent
-Example 7: Recover a compressed backup from two copies on CD-ROM with
-error-checked merging of copies
+Example 8: Recover a compressed backup from two copies on CD-ROM with
+error-checked merging of copies.
@ifnothtml
(@xref{Top,GNU ddrescue manual,,ddrescue},
@end ifnothtml
@@ -577,24 +640,24 @@ error-checked merging of copies
for details about ddrescue).
@example
-ddrescue -d -r1 -b2048 /dev/cdrom cdimage1 logfile1
+ddrescue -d -r1 -b2048 /dev/cdrom cdimage1 mapfile1
mount -t iso9660 -o loop,ro cdimage1 /mnt/cdimage
cp /mnt/cdimage/backup.tar.lz rescued1.tar.lz
umount /mnt/cdimage
(insert second copy in the CD drive)
-ddrescue -d -r1 -b2048 /dev/cdrom cdimage2 logfile2
+ddrescue -d -r1 -b2048 /dev/cdrom cdimage2 mapfile2
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 backup.tar.lz rescued1.tar.lz rescued2.tar.lz
Input files merged successfully.
lziprecover -tv backup.tar.lz
- ok
+ backup.tar.lz: ok
@end example
@sp 1
@noindent
-Example 8: Recover the first volume of those created with the command
+Example 9: Recover the first volume of those created with the command
@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
@@ -605,7 +668,7 @@ member 12 damaged in both copies. The correct file produced is saved in
lziprecover -m -v -o big_db_00001.lz big_db1_00001.lz big_db2_00001.lz
Input files merged successfully.
lziprecover -tv big_db_00001.lz
- ok
+ big_db_00001.lz: ok
@end example