summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/lziprecover.15
-rw-r--r--doc/lziprecover.info101
-rw-r--r--doc/lziprecover.texi60
3 files changed, 131 insertions, 35 deletions
diff --git a/doc/lziprecover.1 b/doc/lziprecover.1
index 7eefb7a..c2f55d7 100644
--- a/doc/lziprecover.1
+++ b/doc/lziprecover.1
@@ -1,5 +1,5 @@
.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.46.1.
-.TH LZIPRECOVER "1" "October 2014" "lziprecover 1.17-pre1" "User Commands"
+.TH LZIPRECOVER "1" "January 2015" "lziprecover 1.17-rc1" "User Commands"
.SH NAME
lziprecover \- recovers data from damaged lzip files
.SH SYNOPSIS
@@ -7,6 +7,7 @@ lziprecover \- recovers data from damaged lzip files
[\fI\,options\/\fR] [\fI\,files\/\fR]
.SH DESCRIPTION
Lziprecover \- Data recovery tool and decompressor for the lzip format.
+.PP
Lziprecover can repair perfectly most files with small errors (up to one
single\-byte error per member), without the need of any extra redundance
at all. Losing an entire archive just because of a corrupt byte near the
@@ -76,7 +77,7 @@ Report bugs to lzip\-bug@nongnu.org
.br
Lziprecover home page: http://www.nongnu.org/lzip/lziprecover.html
.SH COPYRIGHT
-Copyright \(co 2014 Antonio Diaz Diaz.
+Copyright \(co 2015 Antonio Diaz Diaz.
License GPLv2+: GNU GPL version 2 or later <http://gnu.org/licenses/gpl.html>
.br
This is free software: you are free to change and redistribute it.
diff --git a/doc/lziprecover.info b/doc/lziprecover.info
index 6c636e8..05c1196 100644
--- a/doc/lziprecover.info
+++ b/doc/lziprecover.info
@@ -12,12 +12,13 @@ File: lziprecover.info, Node: Top, Next: Introduction, Up: (dir)
Lziprecover Manual
******************
-This manual is for Lziprecover (version 1.17-pre1, 16 October 2014).
+This manual is for Lziprecover (version 1.17-rc1, 21 January 2015).
* Menu:
* Introduction:: Purpose and features of lziprecover
* Invoking lziprecover:: Command line interface
+* Data safety:: Protecting data from accidental loss
* Repairing files:: Fixing bit-flip and similar errors
* Merging files:: Fixing several damaged copies
* File names:: Names of the files produced by lziprecover
@@ -28,7 +29,7 @@ This manual is for Lziprecover (version 1.17-pre1, 16 October 2014).
* Concept index:: Index of concepts
- Copyright (C) 2009-2014 Antonio Diaz Diaz.
+ Copyright (C) 2009-2015 Antonio Diaz Diaz.
This manual is free documentation: you have unlimited permission to
copy, distribute and modify it.
@@ -104,7 +105,7 @@ like lzip or lunzip.
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: Data safety, Prev: Introduction, Up: Top
2 Invoking lziprecover
**********************
@@ -252,20 +253,66 @@ 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: Data safety, Next: Repairing files, Prev: Invoking lziprecover, Up: Top
-3 Repairing files
+3 Protecting data from accidental loss
+**************************************
+
+There are 3 main types of data corruption that may cause data loss:
+single-byte errors, multi-byte errors (generally affecting a whole
+sector in a block device), and total device failure.
+
+ Lziprecover protects natively against single-byte errors (*note
+Repairing files::), as long as file integrity is checked frequently
+enough that a second single-byte error does not develop in the same
+member before the first one is repaired.
+
+ Lziprecover also protects against multi-byte errors (*note Merging
+files::), if at least one backup copy of the file is made.
+
+ The only remedy for total device failure is storing backup copies in
+separate media.
+
+ How does lzip compare with gzip and bzip2 with respect to data
+safety? Lets suppose that you made a backup copy of your valuable
+scientific data, compressed it, and stored two copies on separate
+media. Years later you notice that both copies are corrupt.
+
+ If you compressed with gzip and both copies suffer any damage in the
+data stream, even if it is just one altered bit, the original data can't
+be recovered.
+
+ If you used bzip2, and if the file is large enough to contain more
+than one compressed data block (usually larger than 900 kB), and if no
+block is damaged in both files, then the data can be manually recovered
+by splitting the files with bzip2recover, verifying every block and then
+copying the right blocks in the right order in another file.
+
+ But if you used lzip, the data can be automatically recovered as
+long as no byte is damaged in both files.
+
+ Note that each error in a bzip2 file makes a whole block unusable,
+but each error in a lzip file only affects the damaged bytes, making it
+possible to recover a file with thousands of errors.
+
+
+File: lziprecover.info, Node: Repairing files, Next: Merging files, Prev: Data safety, Up: Top
+
+4 Repairing files
*****************
Lziprecover can repair perfectly most files with small errors (up to one
single-byte error per member), without the need of any extra redundance
at all. If the reparation is successful, the repaired file will be
-identical bit for bit to the original.
+identical bit for bit to the original. This makes lzip files resistant
+to bit-flip, one of the most common forms of data corruption.
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.
+trailer (last 8 bytes of each member). If the error is in the header it
+can be easily repaired with a text editor like GNU Moe (*note File
+format::). If the error is in the member size, it is enough to ignore
+the message about 'bad member size' when decompressing.
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
@@ -289,7 +336,7 @@ lziprecover repairs more efficiently the worst errors.

File: lziprecover.info, Node: Merging files, Next: File names, Prev: Repairing files, Up: Top
-4 Merging files
+5 Merging files
***************
If you have several copies of a file but all of them are too damaged to
@@ -330,7 +377,7 @@ errors are randomly located inside each copy).

File: lziprecover.info, Node: File names, Next: File format, Prev: Merging files, Up: Top
-5 Names of the files produced by lziprecover
+6 Names of the files produced by lziprecover
********************************************
The name of the fixed file produced by '--merge' and '--repair' is made
@@ -341,7 +388,7 @@ original file name ends with one of the extensions '.tar.lz', '.lz' or

File: lziprecover.info, Node: File format, Next: Examples, Prev: File names, Up: Top
-6 File format
+7 File format
*************
Perfection is reached, not when there is no longer anything to add, but
@@ -414,7 +461,7 @@ additional information before, between, or after them.

File: lziprecover.info, Node: Examples, Next: Unzcrash, Prev: File format, Up: Top
-7 A small tutorial with examples
+8 A small tutorial with examples
********************************
Example 1: Restore a regular file from its compressed version
@@ -485,7 +532,7 @@ correct file produced is saved in 'big_db_00001.lz'.

File: lziprecover.info, Node: Unzcrash, Next: Problems, Prev: Examples, Up: Top
-8 Testing the robustness of decompressors
+9 Testing the robustness of decompressors
*****************************************
The lziprecover package also includes unzcrash, a program written to
@@ -562,8 +609,8 @@ caused unzcrash to panic.

File: lziprecover.info, Node: Problems, Next: Concept index, Prev: Unzcrash, Up: Top
-9 Reporting bugs
-****************
+10 Reporting bugs
+*****************
There are probably bugs in lziprecover. There are certainly errors and
omissions in this manual. If you report them, they will get fixed. If
@@ -584,6 +631,7 @@ Concept index
* Menu:
* bugs: Problems. (line 6)
+* data safety: Data safety. (line 6)
* examples: Examples. (line 6)
* file format: File format. (line 6)
* file names: File names. (line 6)
@@ -598,17 +646,18 @@ Concept index

Tag Table:
Node: Top231
-Node: Introduction1153
-Node: Invoking lziprecover4249
-Node: Repairing files9686
-Node: Merging files11371
-Node: File names13212
-Node: File format13676
-Node: Examples16183
-Ref: ddrescue-example17384
-Node: Unzcrash18493
-Node: Problems21047
-Node: Concept index21597
+Node: Introduction1216
+Node: Invoking lziprecover4312
+Node: Data safety9745
+Node: Repairing files11661
+Node: Merging files13563
+Node: File names15404
+Node: File format15868
+Node: Examples18375
+Ref: ddrescue-example19576
+Node: Unzcrash20685
+Node: Problems23239
+Node: Concept index23791

End Tag Table
diff --git a/doc/lziprecover.texi b/doc/lziprecover.texi
index 08d4312..85f0385 100644
--- a/doc/lziprecover.texi
+++ b/doc/lziprecover.texi
@@ -6,8 +6,8 @@
@finalout
@c %**end of header
-@set UPDATED 16 October 2014
-@set VERSION 1.17-pre1
+@set UPDATED 21 January 2015
+@set VERSION 1.17-rc1
@dircategory Data Compression
@direntry
@@ -37,6 +37,7 @@ This manual is for Lziprecover (version @value{VERSION}, @value{UPDATED}).
@menu
* Introduction:: Purpose and features of lziprecover
* Invoking lziprecover:: Command line interface
+* Data safety:: Protecting data from accidental loss
* Repairing files:: Fixing bit-flip and similar errors
* Merging files:: Fixing several damaged copies
* File names:: Names of the files produced by lziprecover
@@ -48,7 +49,7 @@ This manual is for Lziprecover (version @value{VERSION}, @value{UPDATED}).
@end menu
@sp 1
-Copyright @copyright{} 2009-2014 Antonio Diaz Diaz.
+Copyright @copyright{} 2009-2015 Antonio Diaz Diaz.
This manual is free documentation: you have unlimited permission
to copy, distribute and modify it.
@@ -281,6 +282,48 @@ invalid input file, 3 for an internal consistency error (eg, bug) which
caused lziprecover to panic.
+@node Data safety
+@chapter Protecting data from accidental loss
+@cindex data safety
+
+There are 3 main types of data corruption that may cause data loss:
+single-byte errors, multi-byte errors (generally affecting a whole
+sector in a block device), and total device failure.
+
+Lziprecover protects natively against single-byte errors
+(@pxref{Repairing files}), as long as file integrity is checked
+frequently enough that a second single-byte error does not develop in
+the same member before the first one is repaired.
+
+Lziprecover also protects against multi-byte errors (@pxref{Merging
+files}), if at least one backup copy of the file is made.
+
+The only remedy for total device failure is storing backup copies in
+separate media.
+
+How does lzip compare with gzip and bzip2 with respect to data safety?
+Lets suppose that you made a backup copy of your valuable scientific
+data, compressed it, and stored two copies on separate media. Years
+later you notice that both copies are corrupt.
+
+If you compressed with gzip and both copies suffer any damage in the
+data stream, even if it is just one altered bit, the original data can't
+be recovered.
+
+If you used bzip2, and if the file is large enough to contain more than
+one compressed data block (usually larger than 900 kB), and if no block
+is damaged in both files, then the data can be manually recovered by
+splitting the files with bzip2recover, verifying every block and then
+copying the right blocks in the right order in another file.
+
+But if you used lzip, the data can be automatically recovered as long as
+no byte is damaged in both files.
+
+Note that each error in a bzip2 file makes a whole block unusable, but
+each error in a lzip file only affects the damaged bytes, making it
+possible to recover a file with thousands of errors.
+
+
@node Repairing files
@chapter Repairing files
@cindex repairing files
@@ -288,12 +331,15 @@ caused lziprecover to panic.
Lziprecover can repair perfectly most files with small errors (up to one
single-byte error per member), without the need of any extra redundance
at all. If the reparation is successful, the repaired file will be
-identical bit for bit to the original.
+identical bit for bit to the original. This makes lzip files resistant
+to bit-flip, one of the most common forms of data corruption.
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.
+trailer (last 8 bytes of each member). If the error is in the header it
+can be easily repaired with a text editor like GNU Moe (@pxref{File
+format}). If the error is in the member size, it is enough to ignore the
+message about @samp{bad member size} when decompressing.
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
@@ -641,7 +687,7 @@ for all eternity, if not longer.
If you find a bug in lziprecover, please send electronic mail to
@email{lzip-bug@@nongnu.org}. Include the version number, which you can
-find by running @w{@samp{lziprecover --version}}.
+find by running @w{@code{lziprecover --version}}.
@node Concept index