diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/lziprecover.1 | 2 | ||||
| -rw-r--r-- | doc/lziprecover.info | 167 | ||||
| -rw-r--r-- | doc/lziprecover.texinfo | 133 |
3 files changed, 179 insertions, 123 deletions
diff --git a/doc/lziprecover.1 b/doc/lziprecover.1 index f62094a..fce7640 100644 --- a/doc/lziprecover.1 +++ b/doc/lziprecover.1 @@ -1,5 +1,5 @@ .\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.37.1. -.TH LZIPRECOVER "1" "May 2013" "Lziprecover 1.14" "User Commands" +.TH LZIPRECOVER "1" "June 2013" "Lziprecover 1.15-pre1" "User Commands" .SH NAME Lziprecover \- recovers data from damaged lzip files .SH SYNOPSIS diff --git a/doc/lziprecover.info b/doc/lziprecover.info index 83267d5..0d39838 100644 --- a/doc/lziprecover.info +++ b/doc/lziprecover.info @@ -12,16 +12,18 @@ File: lziprecover.info, Node: Top, Next: Introduction, Up: (dir) Lziprecover Manual ****************** -This manual is for Lziprecover (version 1.14, 31 May 2013). +This manual is for Lziprecover (version 1.15-pre1, 17 June 2013). * Menu: -* Introduction:: Purpose and features of lziprecover -* Invoking Lziprecover:: Command line interface -* File Format:: Detailed format of the compressed file -* Examples:: A small tutorial with examples -* Problems:: Reporting bugs -* Concept Index:: Index of concepts +* 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 +* Examples:: A small tutorial with examples +* Problems:: Reporting bugs +* Concept Index:: Index of concepts Copyright (C) 2009, 2010, 2011, 2012, 2013 Antonio Diaz Diaz. @@ -37,14 +39,15 @@ File: lziprecover.info, Node: Introduction, Next: Invoking Lziprecover, Prev: 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 undamaged -members from multi-member files, decompress files and test integrity of -files. +recover badly damaged files from two or more copies, extract data from +damaged files, decompress files and test integrity of files. 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. This recovery capability contributes to make the lzip format -one of the best options for long-term data archiving. +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. Lziprecover is able to efficiently extract a range of bytes from a multi-member file, because it only decompresses the members containing @@ -61,19 +64,22 @@ damaged files themselves are never modified. When decompressing or testing file integrity, lziprecover behaves like lzip or lunzip. - If the files are too damaged for lziprecover to repair them, data -from damaged members can be partially recovered writing it to stdout as -shown in the following example (the resulting file may contain some -garbage data at the end): + 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 -cd rec01file.lz > rec01file + 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: File Format, Prev: Introduction, Up: Top +File: lziprecover.info, Node: Invoking Lziprecover, Next: Repairing Files, Prev: Introduction, Up: Top 2 Invoking Lziprecover ********************** @@ -141,18 +147,10 @@ The format for running lziprecover is: `-m' `--merge' Try to produce a correct file merging the good parts of two or more - damaged copies. The copies must be single-member files. The merge - will fail if the copies have too many damaged areas or if the same - byte is damaged in all copies. If successful, a repaired copy is - written to the file `FILE_fixed.lz'. The exit status is 0 if the - file could be repaired, 2 otherwise. - - 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. + 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. `-o FILE' `--output=FILE' @@ -168,10 +166,12 @@ The format for running lziprecover is: `-R' `--repair' - Try to repair a small error, affecting only one byte, in a - single-member FILE. 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. + 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 + `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 + description of the repair mode. `-s' `--split' @@ -227,9 +227,52 @@ invalid input file, 3 for an internal consistency error (eg, bug) which caused lziprecover to panic. -File: lziprecover.info, Node: File Format, Next: Examples, Prev: Invoking Lziprecover, Up: Top +File: lziprecover.info, Node: Repairing Files, Next: Merging Files, Prev: Invoking Lziprecover, Up: Top + +3 Repairing Files +***************** + +Lziprecover is able to repair files with small errors (up to one byte +error per member). 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. + + 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 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 + +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 +correct file merging the good parts of the damaged copies. + + The merge may succeed even if some copies of the file have all the +headers and trailers damaged, as long as there is at least one copy of +every header and trailer intact, even if they are in different copies of +the file. + + 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 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. + + +File: lziprecover.info, Node: File Format, Next: Examples, Prev: Merging Files, Up: Top -3 File Format +5 File Format ************* Perfection is reached, not when there is no longer anything to add, but @@ -302,7 +345,7 @@ additional information before, between, or after them. File: lziprecover.info, Node: Examples, Next: Problems, Prev: File Format, Up: Top -4 A small tutorial with examples +6 A small tutorial with examples ******************************** Example 1: Restore a regular file from its compressed version @@ -329,9 +372,8 @@ to decompressed byte 15000 (5000 bytes are produced). lziprecover -D 10000-15000 file.lz -Example 5: Repair a one-byte corruption in the single-member file -`file.lz'. (Indented lines are abridged error messages from -lziprecover). +Example 5: Repair small errors in the file `file.lz'. (Indented lines +are abridged diagnostic messages from lziprecover). lziprecover -v -R file.lz Copy of input file repaired successfully. @@ -365,31 +407,16 @@ error-checked merging of copies (*Note GNU ddrescue manual: Example 8: Recover the first volume of those created with the command `lzip -b 32MiB -S 650MB big_db' from two copies, `big_db1_00001.lz' and `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. Two -correct copies are produced and compared. - - lziprecover -s big_db1_00001.lz - lziprecover -s big_db2_00001.lz - lziprecover -t rec*big_db1_00001.lz - rec07big_db1_00001.lz: crc mismatch - rec12big_db1_00001.lz: crc mismatch - lziprecover -t rec*big_db2_00001.lz - rec12big_db2_00001.lz: crc mismatch - rec18big_db2_00001.lz: crc mismatch - lziprecover -m -v rec12big_db1_00001.lz rec12big_db2_00001.lz +damaged in the second copy, and member 12 damaged in both copies. The +correct file produced is saved in `big_db_00001.lz'. + + lziprecover -m -v -o big_db_00001.lz big_db1_00001.lz big_db2_00001.lz Input files merged successfully - cp rec07big_db2_00001.lz rec07big_db1_00001.lz - cp rec12big_db1_00001_fixed.lz rec12big_db1_00001.lz - cp rec12big_db1_00001_fixed.lz rec12big_db2_00001.lz - cp rec18big_db1_00001.lz rec18big_db2_00001.lz - cat rec*big_db1_00001.lz > big_db3_00001.lz - cat rec*big_db2_00001.lz > big_db4_00001.lz - zcmp big_db3_00001.lz big_db4_00001.lz File: lziprecover.info, Node: Problems, Next: Concept Index, Prev: Examples, Up: Top -5 Reporting Bugs +7 Reporting Bugs **************** There are probably bugs in lziprecover. There are certainly errors and @@ -415,19 +442,23 @@ Concept Index * file format: File Format. (line 6) * getting help: Problems. (line 6) * introduction: Introduction. (line 6) -* invoking lziprecover: Invoking Lziprecover. (line 6) +* invoking: Invoking Lziprecover. (line 6) +* merging files: Merging Files. (line 6) +* repairing files: Repairing Files. (line 6) Tag Table: Node: Top231 -Node: Introduction901 -Node: Invoking Lziprecover2685 -Node: File Format8447 -Node: Examples10938 -Ref: ddrescue-example12158 -Node: Problems13938 -Node: Concept Index14488 +Node: Introduction1032 +Node: Invoking Lziprecover3052 +Node: Repairing Files8489 +Node: Merging Files9208 +Node: File Format10338 +Node: Examples12822 +Ref: ddrescue-example14024 +Node: Problems15134 +Node: Concept Index15684 End Tag Table diff --git a/doc/lziprecover.texinfo b/doc/lziprecover.texinfo index 142cdae..54834e9 100644 --- a/doc/lziprecover.texinfo +++ b/doc/lziprecover.texinfo @@ -6,8 +6,8 @@ @finalout @c %**end of header -@set UPDATED 31 May 2013 -@set VERSION 1.14 +@set UPDATED 17 June 2013 +@set VERSION 1.15-pre1 @dircategory Data Compression @direntry @@ -35,12 +35,14 @@ This manual is for Lziprecover (version @value{VERSION}, @value{UPDATED}). @menu -* Introduction:: Purpose and features of lziprecover -* Invoking Lziprecover:: Command line interface -* File Format:: Detailed format of the compressed file -* Examples:: A small tutorial with examples -* Problems:: Reporting bugs -* Concept Index:: Index of concepts +* 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 +* Examples:: A small tutorial with examples +* Problems:: Reporting bugs +* Concept Index:: Index of concepts @end menu @sp 1 @@ -56,14 +58,15 @@ to copy, distribute and modify it. 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 undamaged -members from multi-member files, decompress files and test integrity of -files. +recover badly damaged files from two or more copies, extract data from +damaged files, decompress files and test integrity of files. 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. This recovery capability contributes to make the lzip format -one of the best options for long-term data archiving. +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. Lziprecover is able to efficiently extract a range of bytes from a multi-member file, because it only decompresses the members containing @@ -80,23 +83,26 @@ damaged files themselves are never modified. When decompressing or testing file integrity, lziprecover behaves like lzip or lunzip. -If the files are too damaged for lziprecover to repair them, data from -damaged members can be partially recovered writing it to stdout as shown -in the following example (the resulting file may contain some garbage -data at the end): +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 -cd rec01file.lz > rec01file +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 -@cindex invoking lziprecover +@cindex invoking The format for running lziprecover is: @@ -164,18 +170,10 @@ information about the members in the file. @item -m @itemx --merge Try to produce a correct file merging the good parts of two or more -damaged copies. The copies must be single-member files. The merge will -fail if the copies have too many damaged areas or if the same byte is -damaged in all copies. If successful, a repaired copy is written to the -file @samp{@var{file}_fixed.lz}. The exit status is 0 if the file could -be repaired, 2 otherwise. - -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. +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. @item -o @var{file} @itemx --output=@var{file} @@ -192,10 +190,12 @@ Quiet operation. Suppress all messages. @item -R @itemx --repair -Try to repair a small error, affecting only one byte, in a single-member -@var{file}. 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 +description of the repair mode. @item -s @itemx --split @@ -252,6 +252,47 @@ invalid input file, 3 for an internal consistency error (eg, bug) which caused lziprecover to panic. +@node Repairing Files +@chapter Repairing Files +@cindex repairing files + +Lziprecover is able to repair files with small errors (up to one byte +error per member). 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. + +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 +seen a case of bit-flip in a file stored in an USB flash drive. + + +@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 +correct file merging the good parts of the damaged copies. + +The merge may succeed even if some copies of the file have all the +headers and trailers damaged, as long as there is at least one copy of +every header and trailer intact, even if they are in different copies of +the file. + +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 +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. + + @node File Format @chapter File Format @cindex file format @@ -368,9 +409,8 @@ lziprecover -D 10000-15000 file.lz @sp 1 @noindent -Example 5: Repair a one-byte corruption in the single-member file -@samp{file.lz}. (Indented lines are abridged error messages from -lziprecover). +Example 5: Repair small errors in the file @samp{file.lz}. (Indented +lines are abridged diagnostic messages from lziprecover). @example lziprecover -v -R file.lz @@ -422,27 +462,12 @@ Example 8: Recover the first volume of those created with the command @w{@code{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. Two correct copies are produced and -compared. +member 12 damaged in both copies. The correct file produced is saved in +@samp{big_db_00001.lz}. @example -lziprecover -s big_db1_00001.lz -lziprecover -s big_db2_00001.lz -lziprecover -t rec*big_db1_00001.lz - rec07big_db1_00001.lz: crc mismatch - rec12big_db1_00001.lz: crc mismatch -lziprecover -t rec*big_db2_00001.lz - rec12big_db2_00001.lz: crc mismatch - rec18big_db2_00001.lz: crc mismatch -lziprecover -m -v rec12big_db1_00001.lz rec12big_db2_00001.lz +lziprecover -m -v -o big_db_00001.lz big_db1_00001.lz big_db2_00001.lz Input files merged successfully -cp rec07big_db2_00001.lz rec07big_db1_00001.lz -cp rec12big_db1_00001_fixed.lz rec12big_db1_00001.lz -cp rec12big_db1_00001_fixed.lz rec12big_db2_00001.lz -cp rec18big_db1_00001.lz rec18big_db2_00001.lz -cat rec*big_db1_00001.lz > big_db3_00001.lz -cat rec*big_db2_00001.lz > big_db4_00001.lz -zcmp big_db3_00001.lz big_db4_00001.lz @end example |