diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/lziprecover.info | 149 |
1 files changed, 76 insertions, 73 deletions
diff --git a/doc/lziprecover.info b/doc/lziprecover.info index 2ef7641..b1f820f 100644 --- a/doc/lziprecover.info +++ b/doc/lziprecover.info @@ -12,12 +12,12 @@ File: lziprecover.info, Node: Top, Next: Introduction, Up: (dir) Lziprecover Manual ****************** -This manual is for Lziprecover (version 1.24-pre1, 14 June 2023). +This manual is for Lziprecover (version 1.24, 20 January 2024). * Menu: * Introduction:: Purpose and features of lziprecover -* Invoking lziprecover:: Command line interface +* Invoking lziprecover:: Command-line interface * Data safety:: Protecting data from accidental loss * Repairing one byte:: Fixing bit flips and similar errors * Merging files:: Fixing several damaged copies @@ -32,7 +32,7 @@ This manual is for Lziprecover (version 1.24-pre1, 14 June 2023). * Concept index:: Index of concepts - Copyright (C) 2009-2023 Antonio Diaz Diaz. + Copyright (C) 2009-2024 Antonio Diaz Diaz. This manual is free documentation: you have unlimited permission to copy, distribute, and modify it. @@ -211,12 +211,12 @@ to prepend './' to any file name beginning with a hyphen, or use '--'. '--reproduce' Try to recover a missing (zeroed) sector in FILE using a reference file and the same version of lzip that created FILE. If successful, a - repaired copy is written to the file 'FILE_fixed.lz'. FILE is not + repaired copy is written to the file FILE_fixed.lz. FILE is not modified at all. The exit status is 0 if the member containing the - zeroed sector could be repaired, 2 otherwise. Note that - 'FILE_fixed.lz' may still contain errors in the members following the - one repaired. *Note Reproducing one sector::, for a complete - description of the reproduce mode. + zeroed sector could be repaired, 2 otherwise. Note that FILE_fixed.lz + may still contain errors in the members following the one repaired. + *Note Reproducing one sector::, for a complete description of the + reproduce mode. '--lzip-level=DIGIT|a|m[LENGTH]' Try only the given compression level or match length limit when @@ -273,7 +273,7 @@ to prepend './' to any file name beginning with a hyphen, or use '--'. file numbers produced by '--split'. If any file is damaged, does not exist, can't be opened, or is not - regular, the final exit status will be > 0. '-lq' can be used to check + regular, the final exit status is > 0. '-lq' can be used to check quickly (without decompressing) the structural integrity of the files specified. (Use '--test' to check the data integrity). '-alq' additionally checks that none of the files specified contain trailing @@ -283,21 +283,21 @@ to prepend './' to any file name beginning with a hyphen, or use '--'. '--merge' Try to produce a correct file by 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 + FILE_fixed.lz. The exit status is 0 if a correct file could be produced, 2 otherwise. *Note Merging files::, for a complete description of the merge mode. '-o FILE' '--output=FILE' - Place the output into FILE instead of into 'FILE_fixed.lz'. If + Place the repaired output into FILE instead of into FILE_fixed.lz. If splitting, the names of the files produced are in the form 'rec01FILE', 'rec02FILE', etc. - If decompressing, or converting lzma-alone files, and '-c' has not been - also specified, write the decompressed or converted output to FILE; - keep input files unchanged. This option (or '-c') is needed when - reading from a named pipe (fifo) or from a device. '-o -' is - equivalent to '-c'. '-o' has no effect when testing or listing. + If '-c' has not been also specified, write the (de)compressed output + to FILE, automatically creating any missing parent directories; keep + input files unchanged. This option (or '-c') is needed when reading + from a named pipe (fifo) or from a device. '-o -' is equivalent to + '-c'. '-o' has no effect when testing or listing. '-q' '--quiet' @@ -307,7 +307,7 @@ to prepend './' to any file name beginning with a hyphen, or use '--'. '--byte-repair' Try to repair a FILE with small errors (up to one single-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 + FILE_fixed.lz. FILE is not modified at all. The exit status is 0 if the file could be repaired, 2 otherwise. *Note Repairing one byte::, for a complete description of the repair mode. @@ -491,12 +491,12 @@ to prepend './' to any file name beginning with a hyphen, or use '--'. With argument '1', test 1-bit errors in the LZMA stream of the compressed input FILE like the command 'unzcrash -b1 -p7 -s-20 'lzip -t' FILE' but in memory, and therefore - much faster. *Note Unzcrash::. This option tests all the members - independently in a multimember file, skipping headers and trailers. If - a decompression succeeds, the decompressed output is compared with the - decompressed output of the original FILE using MD5 digests. FILE must - not contain errors and must decompress correctly for the comparisons to - work. + much faster (30 to 50 times faster). *Note Unzcrash::. This option + tests all the members independently in a multimember file, skipping + headers and trailers. If a decompression succeeds, the decompressed + output is compared with the decompressed output of the original FILE + using MD5 digests. FILE must not contain errors and must decompress + correctly for the comparisons to work. With argument 'B', test zeroed sectors (blocks of bytes) in the LZMA stream of the compressed input FILE like the command @@ -517,8 +517,8 @@ to prepend './' to any file name beginning with a hyphen, or use '--'. '--debug-decompress=POSITION,VALUE' Load the compressed FILE into memory, set the byte at POSITION to VALUE, and decompress the modified compressed data to standard output. - If the damaged member is decompressed fully (just fails with a CRC - mismatch), the members following it are also decompressed. + If the damaged member can be decompressed to the end (just fails with + a CRC mismatch), the members following it are also decompressed. '-X[POSITION,VALUE]' '--show-packets[=POSITION,VALUE]' @@ -564,7 +564,7 @@ Q quettabyte (10^30) | Qi quebibyte (2^100) Exit status: 0 for a normal exit, 1 for environmental problems (file not -found, invalid command line options, I/O errors, etc), 2 to indicate a +found, invalid command-line options, I/O errors, etc), 2 to indicate a corrupt or invalid input file, 3 for an internal consistency error (e.g., bug) which caused lziprecover to panic. @@ -574,7 +574,7 @@ File: lziprecover.info, Node: Data safety, Next: Repairing one byte, Prev: In 3 Protecting data from accidental loss ************************************** -It is a fact of life that sometimes data will become corrupt. Software has +It is a fact of life that sometimes data becomes corrupt. Software has errors. Hardware may misbehave or fail. RAM may be struck by a cosmic ray. This is why a safe enough integrity checking is needed in compressed formats, and the reason why a data recovery tool is sometimes needed. @@ -690,9 +690,9 @@ File: lziprecover.info, Node: Repairing one byte, Next: Merging files, Prev: 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. This makes lzip files resistant to bit flip, -one of the most common forms of data corruption. +all. If the reparation is successful, the repaired file is 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 file is repaired in memory. Therefore, enough virtual memory (RAM + swap) to contain the largest damaged member is required. @@ -730,23 +730,23 @@ File: lziprecover.info, Node: Merging files, Next: Reproducing one sector, Pr *************** If you have several copies of a file but all of them are too damaged to -repair them (*note Repairing one byte::), lziprecover can try to produce a -correct file by merging the good parts of the damaged copies. +repair them individually (*note Repairing one byte::), lziprecover can try +to produce a correct file by 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 + The merge fails 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. All the copies to be merged must have the same size. If any of them is larger or smaller than it should, either because it has been truncated or because it got some garbage data appended at the end, it can be brought to -the correct size with the following command before merging it with the -other copies: +the correct size with the following command before merging it with the other +copies: ddrescue -s<correct_size> -x<correct_size> file.lz correct_size_file.lz @@ -1009,8 +1009,8 @@ the tar archiver and the lzip compressor. Tarlz creates tar archives using a simplified and safer variant of the POSIX pax format compressed in lzip format, keeping the alignment between tar members and lzip members. The resulting multimember tar.lz archive is -fully backward compatible with standard tar tools like GNU tar, which treat -it like any other tar.lz archive. *Note tarlz manual: (tarlz)Top, and *note +backward compatible with standard tar tools like GNU tar, which treat it +like any other tar.lz archive. *Note tarlz manual: (tarlz)Top, and *note lzip manual: (lzip)Top. Multimember tar.lz archives have some safety advantages over solidly @@ -1113,7 +1113,7 @@ when there is no longer anything to take away. represents a variable number of bytes. - A lzip file consists of a series of independent "members" (compressed + A lzip file consists of one or more independent "members" (compressed data sets). The members simply appear one after another in the file, with no additional information before, between, or after them. Each member can encode in compressed form up to 16 EiB - 1 byte of uncompressed data. The @@ -1180,7 +1180,7 @@ member. Such trailing data may be: the file has not been truncated), a cryptographically secure hash, a description of file contents, etc. It is safe to append any amount of text to a lzip file as long as none of the first four bytes of the - text match the corresponding byte in the string "LZIP", and the text + text matches the corresponding byte in the string "LZIP", and the text does not contain any zero bytes (null characters). Nonzero bytes and zero bytes can't be safely mixed in trailing data. @@ -1198,7 +1198,7 @@ member. Such trailing data may be: discriminate trailing data from a corrupt header has a Hamming distance (HD) of 3, and the 3 bit flips must happen in different magic bytes for the test to fail. In any case, the option '--trailing-error' - guarantees that any corrupt header will be detected. + guarantees that any corrupt header is detected. Trailing data are in no way part of the lzip file format, but tools reading lzip files are expected to behave as correctly and usefully as @@ -1305,7 +1305,9 @@ File: lziprecover.info, Node: Unzcrash, Next: Problems, Prev: Examples, Up: 12 Testing the robustness of decompressors ****************************************** -The lziprecover package also includes unzcrash, a program written to test +*Note --unzcrash::, for a faster way of testing the robustness of lzip. + + 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. @@ -1332,7 +1334,7 @@ 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 unzcrash can be used to test any decompressor (not only lzip), or even other decoder programs -having a suitable command line syntax. +having a suitable command-line syntax. If the decompressor returns with zero status, unzcrash compares the output of the decompressor for the original and corrupt files. If the @@ -1345,9 +1347,9 @@ latter case, please, report any false negative as a bug. In order to compare the outputs, unzcrash needs a 'zcmp' program able to understand the format being tested. For example the 'zcmp' provided by zutils. If the 'zcmp' program used does not understand the format being -tested, all the comparisons will fail because the compressed files will be -compared without being decompressed first. Use '--zcmp=false' to disable -comparisons. *Note Zcmp: (zutils)Zcmp. +tested, all the comparisons fail because the compressed files are compared +without being decompressed first. Use '--zcmp=false' to disable comparisons. +*Note Zcmp: (zutils)Zcmp. The format for running unzcrash is: @@ -1395,8 +1397,8 @@ tested must decompress it correctly for the comparisons to work. Test one byte, block, or truncation size every N bytes. If '--delta' is not specified, unzcrash tests all the bytes, non-overlapping blocks, or truncation sizes. Values of N smaller than the block size - will result in overlapping blocks. (Which is convenient for testing - because there are usually too few non-overlapping blocks in a file). + result in overlapping blocks. (Which is convenient for testing because + there are usually too few non-overlapping blocks in a file). '-e POSITION,VALUE' '--set-byte=POSITION,VALUE' @@ -1447,7 +1449,7 @@ tested must decompress it correctly for the comparisons to work. Exit status: 0 for a normal exit, 1 for environmental problems (file not -found, invalid command line options, I/O errors, etc), 2 to indicate a +found, invalid command-line options, I/O errors, etc), 2 to indicate a corrupt or invalid input file, 3 for an internal consistency error (e.g., bug) which caused unzcrash to panic. @@ -1499,31 +1501,32 @@ Concept index Tag Table: Node: Top226 -Node: Introduction1408 -Node: Invoking lziprecover5414 -Ref: --trailing-error6361 -Ref: range-format8793 -Ref: --reproduce9128 -Ref: --byte-repair13424 -Node: Data safety27441 -Node: Merging with a backup29429 -Node: Reproducing a mailbox30692 -Node: Repairing one byte33146 -Node: Merging files35211 -Ref: performance-of-merge36381 -Ref: ddrescue-example37990 -Node: Reproducing one sector39277 -Ref: performance-of-reproduce43163 -Ref: ddrescue-example245837 -Node: Tarlz48257 -Node: File names51921 -Node: File format52383 -Node: Trailing data55070 -Node: Examples58388 -Ref: concat-example58963 -Node: Unzcrash60355 -Node: Problems66633 -Node: Concept index67185 +Node: Introduction1406 +Node: Invoking lziprecover5412 +Ref: --trailing-error6359 +Ref: range-format8791 +Ref: --reproduce9126 +Ref: --byte-repair13411 +Ref: --unzcrash23209 +Node: Data safety27459 +Node: Merging with a backup29443 +Node: Reproducing a mailbox30706 +Node: Repairing one byte33160 +Node: Merging files35220 +Ref: performance-of-merge36399 +Ref: ddrescue-example38008 +Node: Reproducing one sector39295 +Ref: performance-of-reproduce43181 +Ref: ddrescue-example245855 +Node: Tarlz48275 +Node: File names51933 +Node: File format52395 +Node: Trailing data55082 +Node: Examples58397 +Ref: concat-example58972 +Node: Unzcrash60364 +Node: Problems66704 +Node: Concept index67256 End Tag Table |