1 files changed, 397 insertions, 0 deletions
diff --git a/doc/lziprecover.texinfo b/doc/lziprecover.texinfo
new file mode 100644
index 0000000..2447c14
--- /dev/null
+++ b/doc/lziprecover.texinfo
@@ -0,0 +1,397 @@
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename lziprecover.info
+@settitle Lziprecover Manual
+@finalout
+@c %**end of header
+
+@set UPDATED 12 November 2011
+@set VERSION 1.13-rc1
+
+@dircategory Data Compression
+@direntry
+* Lziprecover: (lziprecover).   Data recovery tool for lzipped files
+@end direntry
+
+
+@ifnothtml
+@titlepage
+@title Lziprecover
+@subtitle Data recovery tool for lzipped files
+@subtitle for Lziprecover version @value{VERSION}, @value{UPDATED}
+@author by Antonio Diaz Diaz
+
+@page
+@vskip 0pt plus 1filll
+@end titlepage
+
+@contents
+@end ifnothtml
+
+@node Top
+@top
+
+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
+@end menu
+
+@sp 1
+Copyright @copyright{} 2009, 2010, 2011 Antonio Diaz Diaz.
+
+This manual is free documentation: you have unlimited permission
+to copy, distribute and modify it.
+
+
+@node Introduction
+@chapter Introduction
+@cindex 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):
+
+@example
+lziprecover -cd rec00001file.lz > rec00001file
+@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.
+
+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.
+
+
+@node Invoking Lziprecover
+@chapter Invoking Lziprecover
+@cindex invoking lziprecover
+
+The format for running lziprecover is:
+
+@example
+lziprecover [@var{options}] [@var{files}]
+@end example
+
+Lziprecover supports the following options:
+
+@table @samp
+@item -h
+@itemx --help
+Print an informative help message describing the options and exit.
+
+@item -V
+@itemx --version
+Print the version number of lziprecover on the standard output and exit.
+
+@item -c
+@itemx --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.
+
+@item -d
+@itemx --decompress
+Decompress.
+
+@item -f
+@itemx --force
+Force overwrite of output files.
+
+@item -k
+@itemx --keep
+Keep (don't delete) input files during decompression.
+
+@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.
+
+@item -o @var{file}
+@itemx --output=@var{file}
+Place the output into @samp{@var{file}} instead of into
+@samp{@var{file}_fixed.lz}. If splitting, the names of the files
+produced are in the form @samp{rec00001@var{file}},
+@samp{rec00002@var{file}}, etc. If decompressing from standard input and
+@samp{--stdout} has not been specified, use @samp{@var{file}} as the
+name of the decompressed file.
+
+@item -q
+@itemx --quiet
+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
+@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.
+
+@item -s
+@itemx --split
+Search for members in @samp{@var{file}} and write each member in its own
+@samp{.lz} file. You can then use @samp{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
+@samp{rec00001@var{file}.lz}, @samp{rec00002@var{file}.lz}, etc, and are
+designed so that the use of wildcards in subsequent processing, for
+example, @w{@samp{lziprecover -cd rec*@var{file}.lz > recovered_data}},
+processes the files in the correct order.
+
+@item -t
+@itemx --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 @samp{-v} to see information about the file.
+
+@item -v
+@itemx --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).
+
+@end table
+
+
+@node File Format
+@chapter File Format
+@cindex file format
+
+In the diagram below, a box like this:
+@verbatim
++---+
+|   | <-- the vertical bars might be missing
++---+
+@end verbatim
+
+represents one byte; a box like this:
+@verbatim
++==============+
+|              |
++==============+
+@end verbatim
+
+represents a variable number of bytes.
+
+@sp 1
+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:
+@verbatim
++--+--+--+--+----+----+=============+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+| ID string | VN | DS | Lzma stream | CRC32 |   Data size   |  Member size  |
++--+--+--+--+----+----+=============+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+@end verbatim
+
+All multibyte values are stored in little endian order.
+
+@table @samp
+@item ID string
+A four byte string, identifying the lzip format, with the value "LZIP".
+
+@item 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 @samp{Member size} field.
+
+@item 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.
+
+@item Lzma stream
+The lzma stream, finished by an end of stream marker. Uses default values
+for encoder properties.
+
+@item CRC32 (4 bytes)
+CRC of the uncompressed original data.
+
+@item Data size (8 bytes)
+Size of the uncompressed original data.
+
+@item Member size (8 bytes)
+Total size of the member, including header and trailer. This facilitates
+safe recovery of undamaged members from multimember files.
+
+@end table
+
+
+@node Examples
+@chapter A small tutorial with examples
+@cindex examples
+
+Example 1: Restore a regular file from its compressed version
+@samp{file.lz}. If the operation is successful, @samp{file.lz} is
+removed.
+
+@example
+lziprecover -d file.lz
+@end example
+
+@sp 1
+@noindent
+Example 2: Verify the integrity of the compressed file @samp{file.lz}
+and show status.
+
+@example
+lziprecover -tv file.lz
+@end example
+
+@sp 1
+@noindent
+Example 3: Decompress @samp{file.lz} partially until 10KiB of
+decompressed data are produced.
+
+@example
+lziprecover -cd file.lz | dd bs=1024 count=10
+@end example
+
+@sp 1
+@noindent
+Example 4: Decompress @samp{file.lz} partially from decompressed byte
+10000 to decompressed byte 15000 (5000 bytes are produced).
+
+@example
+lziprecover -cd file.lz | dd bs=1000 skip=10 count=5
+@end example
+
+@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
+lziprecover -v -R file.lz
+  Copy of input file repaired successfully.
+mv file_fixed.lz file.lz
+@end example
+
+@sp 1
+@noindent
+Example 6: Split the multi-member file @samp{file.lz} and write each
+member in its own @samp{recXXXXXfile.lz} file. Then use
+@w{@samp{lziprecover -t}} to test the integrity of the resulting files.
+
+@example
+lziprecover -s file.lz
+lziprecover -tv rec*file.lz
+@end example
+
+@sp 1
+@anchor{ddrescue-example}
+@noindent
+Example 7: Recover a compressed backup from two copies on CD-ROM (see
+the GNU ddrescue manual for details about ddrescue)
+
+@example
+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
+@end example
+
+@sp 1
+@noindent
+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 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.
+
+@example
+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
+@end example
+
+
+@node Problems
+@chapter Reporting Bugs
+@cindex bugs
+@cindex getting help
+
+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
+@email{lzip-bug@@nongnu.org}. Include the version number, which you can
+find by running @w{@samp{lziprecover --version}}.
+
+
+@node Concept Index
+@unnumbered Concept Index
+
+@printindex cp
+
+@bye