summaryrefslogtreecommitdiffstats
path: root/doc/lziprecover.info
diff options
context:
space:
mode:
authorDaniel Baumann <mail@daniel-baumann.ch>2015-11-07 10:15:36 +0000
committerDaniel Baumann <mail@daniel-baumann.ch>2015-11-07 10:15:36 +0000
commitd313f09b6c5ba39aa4569bbcceffab475b7edbfb (patch)
tree254d28fea0f549b0ff596b255d177cc023f9ce39 /doc/lziprecover.info
parentInitial commit. (diff)
downloadlziprecover-d313f09b6c5ba39aa4569bbcceffab475b7edbfb.tar.xz
lziprecover-d313f09b6c5ba39aa4569bbcceffab475b7edbfb.zip
Adding upstream version 1.13~rc1.upstream/1.13_rc1
Signed-off-by: Daniel Baumann <mail@daniel-baumann.ch>
Diffstat (limited to 'doc/lziprecover.info')
-rw-r--r--doc/lziprecover.info368
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