diff options
Diffstat (limited to 'doc/lziprecover.info')
| -rw-r--r-- | doc/lziprecover.info | 368 |
1 files changed, 368 insertions, 0 deletions
diff --git a/doc/lziprecover.info b/doc/lziprecover.info new file mode 100644 index 0000000..4528103 --- /dev/null +++ b/doc/lziprecover.info @@ -0,0 +1,368 @@ +This is lziprecover.info, produced by makeinfo version 4.13 from +lziprecover.texinfo. + +INFO-DIR-SECTION Data Compression +START-INFO-DIR-ENTRY +* Lziprecover: (lziprecover). Data recovery tool for lzipped files +END-INFO-DIR-ENTRY + + +File: lziprecover.info, Node: Top, Next: Introduction, Up: (dir) + +Lziprecover Manual +****************** + +This manual is for Lziprecover (version 1.13-rc1, 12 November 2011). + +* 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 + + + Copyright (C) 2009, 2010, 2011 Antonio Diaz Diaz. + + This manual is free documentation: you have unlimited permission to +copy, distribute and modify it. + + +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 undamaged +members from multi-member 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. + + When recovering data, lziprecover takes as arguments the names of the +damaged files and writes zero or more recovered files depending on the +operation selected and whether the recovery succeeded or not. The +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): + + lziprecover -cd rec00001file.lz > rec00001file + + 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. + + Return values: 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 lziprecover to panic. + + +File: lziprecover.info, Node: Invoking Lziprecover, Next: File Format, Prev: Introduction, Up: Top + +2 Invoking Lziprecover +********************** + +The format for running lziprecover is: + + lziprecover [OPTIONS] [FILES] + + Lziprecover 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. + +`-c' +`--stdout' + Decompress to standard output. Needed when reading from a named + pipe (fifo) or from a device. Use it to recover as much of the + uncompressed data as possible when decompressing a corrupt file. + +`-d' +`--decompress' + Decompress. + +`-f' +`--force' + Force overwrite of output files. + +`-k' +`--keep' + Keep (don't delete) input files during decompression. + +`-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. + +`-o FILE' +`--output=FILE' + Place the output into `FILE' instead of into `FILE_fixed.lz'. If + splitting, the names of the files produced are in the form + `rec00001FILE', `rec00002FILE', etc. If decompressing from + standard input and `--stdout' has not been specified, use `FILE' + as the name of the decompressed file. + +`-q' +`--quiet' + Quiet operation. Suppress all messages. + +`-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. + +`-s' +`--split' + Search for members in `FILE' and write each member in its own + `.lz' file. You can then use `lziprecover -t' to test the + integrity of the resulting files, decompress those which are + undamaged, and try to repair or partially decompress those which + are damaged. + + The names of the files produced are in the form `rec00001FILE.lz', + `rec00002FILE.lz', etc, and are designed so that the use of + wildcards in subsequent processing, for example, + `lziprecover -cd rec*FILE.lz > recovered_data', processes the + files in the correct order. + +`-t' +`--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 `-v' to see information about + the file. + +`-v' +`--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 + bytes of trailing garbage (if any). + + + +File: lziprecover.info, Node: File Format, Next: Examples, Prev: Invoking Lziprecover, Up: Top + +3 File Format +************* + +In the diagram below, a box like this: ++---+ +| | <-- the vertical bars might be missing ++---+ + + represents one byte; a box like this: ++==============+ +| | ++==============+ + + represents a variable number of bytes. + + + A lzip file consists of a series of "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 has the following structure: ++--+--+--+--+----+----+=============+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| ID string | VN | DS | Lzma stream | CRC32 | Data size | Member size | ++--+--+--+--+----+----+=============+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + All multibyte values are stored in little endian order. + +`ID string' + A four byte string, identifying the lzip format, with the value + "LZIP". + +`VN (version number, 1 byte)' + Just in case something needs to be modified in the future. Valid + values are 0 and 1. Version 0 files are deprecated. They can + contain only one member and lack the `Member size' field. + +`DS (coded dictionary size, 1 byte)' + Bits 4-0 contain the base 2 logarithm of the base dictionary size. + Bits 7-5 contain the number of "wedges" to substract from the base + dictionary size to obtain the dictionary size. The size of a wedge + is (base dictionary size / 16). + Valid values for dictionary size range from 4KiB to 512MiB. + +`Lzma stream' + The lzma stream, finished by an end of stream marker. Uses default + values for encoder properties. + +`CRC32 (4 bytes)' + CRC of the uncompressed original data. + +`Data size (8 bytes)' + Size of the uncompressed original data. + +`Member size (8 bytes)' + Total size of the member, including header and trailer. This + facilitates safe recovery of undamaged members from multimember + files. + + + +File: lziprecover.info, Node: Examples, Next: Problems, Prev: File Format, Up: Top + +4 A small tutorial with examples +******************************** + +Example 1: Restore a regular file from its compressed version +`file.lz'. If the operation is successful, `file.lz' is removed. + + lziprecover -d file.lz + + +Example 2: Verify the integrity of the compressed file `file.lz' and +show status. + + lziprecover -tv file.lz + + +Example 3: Decompress `file.lz' partially until 10KiB of decompressed +data are produced. + + lziprecover -cd file.lz | dd bs=1024 count=10 + + +Example 4: Decompress `file.lz' partially from decompressed byte 10000 +to decompressed byte 15000 (5000 bytes are produced). + + lziprecover -cd file.lz | dd bs=1000 skip=10 count=5 + + +Example 5: Repair a one-byte corruption in the single-member file +`file.lz'. (Indented lines are abridged error messages from +lziprecover). + + lziprecover -v -R file.lz + Copy of input file repaired successfully. + mv file_fixed.lz file.lz + + +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. + + lziprecover -s file.lz + lziprecover -tv rec*file.lz + + +Example 7: Recover a compressed backup from two copies on CD-ROM (see +the GNU ddrescue manual for details about ddrescue) + + ddrescue -b2048 /dev/cdrom cdimage1 logfile1 + 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 -b2048 /dev/cdrom cdimage2 logfile2 + 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 + + +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 00007 damaged in the first copy, member +00018 damaged in the second copy, and member 00012 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 + rec00007big_db1_00001.lz: crc mismatch + rec00012big_db1_00001.lz: crc mismatch + lziprecover -t rec*big_db2_00001.lz + rec00012big_db2_00001.lz: crc mismatch + rec00018big_db2_00001.lz: crc mismatch + lziprecover -m -v rec00012big_db1_00001.lz rec00012big_db2_00001.lz + Input files merged successfully + cp rec00007big_db2_00001.lz rec00007big_db1_00001.lz + cp rec00012big_db1_00001_fixed.lz rec00012big_db1_00001.lz + cp rec00012big_db1_00001_fixed.lz rec00012big_db2_00001.lz + cp rec00018big_db1_00001.lz rec00018big_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 +**************** + +There are probably bugs in lziprecover. There are certainly errors and +omissions in this manual. If you report them, they will get fixed. If +you don't, no one will ever know about them and they will remain unfixed +for all eternity, if not longer. + + If you find a bug in lziprecover, please send electronic mail to +<lzip-bug@nongnu.org>. Include the version number, which you can find +by running `lziprecover --version'. + + +File: lziprecover.info, Node: Concept Index, Prev: Problems, Up: Top + +Concept Index +************* + + +* Menu: + +* bugs: Problems. (line 6) +* examples: Examples. (line 6) +* file format: File Format. (line 6) +* getting help: Problems. (line 6) +* introduction: Introduction. (line 6) +* invoking lziprecover: Invoking Lziprecover. (line 6) + + + +Tag Table: +Node: Top231 +Node: Introduction898 +Node: Invoking Lziprecover2684 +Node: File Format6150 +Node: Examples8156 +Ref: ddrescue-example9409 +Node: Problems11188 +Node: Concept Index11738 + +End Tag Table |