Adding upstream version 1.13~rc1.upstream/1.13_rc1

Signed-off-by: Daniel Baumann <mail@daniel-baumann.ch>

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