summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--doc/plzip.171
-rw-r--r--doc/plzip.info303
-rw-r--r--doc/plzip.texinfo311
3 files changed, 685 insertions, 0 deletions
diff --git a/doc/plzip.1 b/doc/plzip.1
new file mode 100644
index 0000000..4a812c0
--- /dev/null
+++ b/doc/plzip.1
@@ -0,0 +1,71 @@
+.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.36.
+.TH PLZIP "1" "December 2009" "Plzip 0.1" "User Commands"
+.SH NAME
+Plzip \- data compressor based on the LZMA algorithm
+.SH SYNOPSIS
+.B plzip
+[\fIoptions\fR] [\fIfiles\fR]
+.SH DESCRIPTION
+Plzip \- A parallel version of the lzip data compressor.
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+output version information and exit
+.TP
+\fB\-c\fR, \fB\-\-stdout\fR
+send output to standard output
+.TP
+\fB\-d\fR, \fB\-\-decompress\fR
+decompress
+.TP
+\fB\-n\fR, \fB\-\-threads=\fR<n>
+set the number of (de)compression threads
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+suppress all messages
+.TP
+\fB\-t\fR, \fB\-\-test\fR
+test compressed file integrity
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+be verbose (a 2nd \fB\-v\fR gives more)
+.TP
+\fB\-1\fR .. \fB\-9\fR
+set compression level [default 6]
+.TP
+\fB\-\-fast\fR
+alias for \fB\-1\fR
+.TP
+\fB\-\-best\fR
+alias for \fB\-9\fR
+.PP
+If no file names are given, plzip compresses or decompresses
+from standard input to standard output.
+Numbers may be followed by a multiplier: k = kB = 10^3 = 1000,
+Ki = KiB = 2^10 = 1024, M = 10^6, Mi = 2^20, G = 10^9, Gi = 2^30, etc...
+.SH "REPORTING BUGS"
+Report bugs to lzip\-bug@nongnu.org
+Lzip home page: http://www.nongnu.org/lzip/lzip.html
+.SH COPYRIGHT
+Copyright \(co 2009 Laszlo Ersek.
+.br
+Copyright \(co 2009 Antonio Diaz Diaz.
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+The full documentation for
+.B Plzip
+is maintained as a Texinfo manual. If the
+.B info
+and
+.B Plzip
+programs are properly installed at your site, the command
+.IP
+.B info Plzip
+.PP
+should give you access to the complete manual.
diff --git a/doc/plzip.info b/doc/plzip.info
new file mode 100644
index 0000000..68fa5fa
--- /dev/null
+++ b/doc/plzip.info
@@ -0,0 +1,303 @@
+This is plzip.info, produced by makeinfo version 4.13 from
+plzip.texinfo.
+
+INFO-DIR-SECTION Data Compression
+START-INFO-DIR-ENTRY
+* Plzip: (plzip). Parallel version of the lzip data compressor
+END-INFO-DIR-ENTRY
+
+
+File: plzip.info, Node: Top, Next: Introduction, Up: (dir)
+
+Plzip Manual
+************
+
+This manual is for Plzip (version 0.1, 5 December 2009).
+
+* Menu:
+
+* Introduction:: Purpose and features of plzip
+* Invoking Plzip:: Command line interface
+* File Format:: Detailed format of the compressed file
+* Problems:: Reporting bugs
+* Concept Index:: Index of concepts
+
+
+ Copyright (C) 2008, 2009 Antonio Diaz Diaz.
+
+ This manual is free documentation: you have unlimited permission to
+copy, distribute and modify it.
+
+
+File: plzip.info, Node: Introduction, Next: Invoking Plzip, Prev: Top, Up: Top
+
+1 Introduction
+**************
+
+Plzip is a parallel version of the lzip data compressor. Currently only
+compression is performed in parallel. Parallel decompression is planned
+to be implemented soon.
+
+ Lzip is a lossless data compressor based on the LZMA algorithm, with
+very safe integrity checking and a user interface similar to the one of
+gzip or bzip2. Lzip decompresses almost as fast as gzip and compresses
+better than bzip2, which makes it well suited for software distribution
+and data archiving.
+
+ Plzip replaces every file given in the command line with a compressed
+version of itself, with the name "original_name.lz". Each compressed
+file has the same modification date, permissions, and, when possible,
+ownership as the corresponding original, so that these properties can be
+correctly restored at decompression time. Plzip is able to read from
+some types of non regular files if the `--stdout' option is specified.
+
+ If no file names are specified, plzip compresses (or decompresses)
+from standard input to standard output. In this case, plzip will
+decline to write compressed output to a terminal, as this would be
+entirely incomprehensible and therefore pointless.
+
+ Plzip will correctly decompress a file which is the concatenation of
+two or more compressed files. The result is the concatenation of the
+corresponding uncompressed files. Integrity testing of concatenated
+compressed files is also supported.
+
+ When decompressing, plzip attempts to guess the name for the
+decompressed file from that of the compressed file as follows:
+
+filename.lz becomes filename
+filename.tlz becomes filename.tar
+anyothername becomes anyothername.out
+
+ As a self-check for your protection, plzip stores in the member
+trailer the 32-bit CRC of the original data and the size of the
+original data, to make sure that the decompressed version of the data
+is identical to the original. This guards against corruption of the
+compressed data, and against undetected bugs in plzip (hopefully very
+unlikely). The chances of data corruption going undetected are
+microscopic, less than one chance in 4000 million for each member
+processed. Be aware, though, that the check occurs upon decompression,
+so it can only tell you that something is wrong. It can't help you
+recover the original uncompressed data.
+
+ 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 plzip to panic.
+
+
+File: plzip.info, Node: Invoking Plzip, Next: File Format, Prev: Introduction, Up: Top
+
+2 Invoking Plzip
+****************
+
+The format for running plzip is:
+
+ plzip [OPTIONS] [FILES]
+
+ Plzip supports the following options:
+
+`--help'
+`-h'
+ Print an informative help message describing the options and exit.
+
+`--version'
+`-V'
+ Print the version number of plzip on the standard output and exit.
+
+`--stdout'
+`-c'
+ Compress or decompress to standard output. Needed when reading
+ from a named pipe (fifo) or from a device.
+
+`--decompress'
+`-d'
+ Decompress.
+
+`--force'
+`-f'
+ Force overwrite of output file.
+
+`--keep'
+`-k'
+ Keep (don't delete) input files during compression or
+ decompression.
+
+`--match-length=LENGTH'
+`-m LENGTH'
+ Set the match length limit in bytes. Valid values range from 5 to
+ 273. Larger values usually give better compression ratios but
+ longer compression times.
+
+`--output=FILE'
+`-o FILE'
+ When reading from standard input and `--stdout' has not been
+ specified, use `FILE' as the virtual name of the uncompressed
+ file. This produces a file named `FILE' when decompressing, and a
+ file named `FILE.lz' when compressing.
+
+`--quiet'
+`-q'
+ Quiet operation. Suppress all messages.
+
+`--dictionary-size=SIZE'
+`-s SIZE'
+ Set the dictionary size limit in bytes. Valid values range from
+ 4KiB to 512MiB. Note that dictionary sizes are quantized. If the
+ specified size does not match one of the valid sizes, it will be
+ rounded upwards.
+
+`--test'
+`-t'
+ Check integrity of the specified file(s), but don't decompress
+ them. This really performs a trial decompression and throws away
+ the result. Use `-tvv' or `-tvvv' to see information about the
+ file.
+
+`--verbose'
+`-v'
+ Verbose mode. Show the compression ratio for each file processed.
+ Further -v's increase the verbosity level.
+
+`-1 .. -9'
+ Set the compression parameters (dictionary size and match length
+ limit) as shown in the table below. Note that `-9' can be much
+ slower than `-1'. These options have no effect when decompressing.
+
+ Level Dictionary size Match length limit
+ -1 1MiB 10 bytes
+ -2 1MiB 12 bytes
+ -3 1MiB 17 bytes
+ -4 2MiB 26 bytes
+ -5 4MiB 44 bytes
+ -6 8MiB 80 bytes
+ -7 16MiB 108 bytes
+ -8 16MiB 163 bytes
+ -9 32MiB 273 bytes
+
+`--fast'
+`--best'
+ Aliases for GNU gzip compatibility.
+
+
+
+ Numbers given as arguments to options may be followed by a multiplier
+and an optional `B' for "byte".
+
+ Table of SI and binary prefixes (unit multipliers):
+
+Prefix Value | Prefix Value
+k kilobyte (10^3 = 1000) | Ki kibibyte (2^10 = 1024)
+M megabyte (10^6) | Mi mebibyte (2^20)
+G gigabyte (10^9) | Gi gibibyte (2^30)
+T terabyte (10^12) | Ti tebibyte (2^40)
+P petabyte (10^15) | Pi pebibyte (2^50)
+E exabyte (10^18) | Ei exbibyte (2^60)
+Z zettabyte (10^21) | Zi zebibyte (2^70)
+Y yottabyte (10^24) | Yi yobibyte (2^80)
+
+
+File: plzip.info, Node: File Format, Next: Problems, Prev: Invoking Plzip, 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 member type, 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 have only one member and lack
+ `Member size'.
+
+`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: plzip.info, Node: Problems, Next: Concept Index, Prev: File Format, Up: Top
+
+4 Reporting Bugs
+****************
+
+There are probably bugs in plzip. 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 plzip, please send electronic mail to
+<lzip-bug@nongnu.org>. Include the version number, which you can find
+by running `plzip --version'.
+
+
+File: plzip.info, Node: Concept Index, Prev: Problems, Up: Top
+
+Concept Index
+*************
+
+
+* Menu:
+
+* bugs: Problems. (line 6)
+* file format: File Format. (line 6)
+* getting help: Problems. (line 6)
+* introduction: Introduction. (line 6)
+* invoking: Invoking Plzip. (line 6)
+* options: Invoking Plzip. (line 6)
+* usage: Invoking Plzip. (line 6)
+* version: Invoking Plzip. (line 6)
+
+
+
+Tag Table:
+Node: Top227
+Node: Introduction750
+Node: Invoking Plzip3401
+Node: File Format6746
+Node: Problems8702
+Node: Concept Index9231
+
+End Tag Table
diff --git a/doc/plzip.texinfo b/doc/plzip.texinfo
new file mode 100644
index 0000000..78ccce5
--- /dev/null
+++ b/doc/plzip.texinfo
@@ -0,0 +1,311 @@
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename plzip.info
+@settitle Plzip Manual
+@finalout
+@c %**end of header
+
+@set UPDATED 5 December 2009
+@set VERSION 0.1
+
+@dircategory Data Compression
+@direntry
+* Plzip: (plzip). Parallel version of the lzip data compressor
+@end direntry
+
+
+@titlepage
+@title Plzip
+@subtitle A data compressor based on the LZMA algorithm
+@subtitle for Plzip version @value{VERSION}, @value{UPDATED}
+@author by Antonio Diaz Diaz
+
+@page
+@vskip 0pt plus 1filll
+@end titlepage
+
+@contents
+
+@node Top
+@top
+
+This manual is for Plzip (version @value{VERSION}, @value{UPDATED}).
+
+@menu
+* Introduction:: Purpose and features of plzip
+* Invoking Plzip:: Command line interface
+* File Format:: Detailed format of the compressed file
+* Problems:: Reporting bugs
+* Concept Index:: Index of concepts
+@end menu
+
+@sp 1
+Copyright @copyright{} 2008, 2009 Antonio Diaz Diaz.
+
+This manual is free documentation: you have unlimited permission
+to copy, distribute and modify it.
+
+
+@node Introduction
+@chapter Introduction
+@cindex introduction
+
+Plzip is a parallel version of the lzip data compressor. Currently only
+compression is performed in parallel. Parallel decompression is planned
+to be implemented soon.
+
+Lzip is a lossless data compressor based on the LZMA algorithm, with
+very safe integrity checking and a user interface similar to the one of
+gzip or bzip2. Lzip decompresses almost as fast as gzip and compresses
+better than bzip2, which makes it well suited for software distribution
+and data archiving.
+
+Plzip replaces every file given in the command line with a compressed
+version of itself, with the name "original_name.lz". Each compressed
+file has the same modification date, permissions, and, when possible,
+ownership as the corresponding original, so that these properties can be
+correctly restored at decompression time. Plzip is able to read from some
+types of non regular files if the @samp{--stdout} option is specified.
+
+If no file names are specified, plzip compresses (or decompresses) from
+standard input to standard output. In this case, plzip will decline to
+write compressed output to a terminal, as this would be entirely
+incomprehensible and therefore pointless.
+
+Plzip will correctly decompress a file which is the concatenation of two
+or more compressed files. The result is the concatenation of the
+corresponding uncompressed files. Integrity testing of concatenated
+compressed files is also supported.
+
+When decompressing, plzip attempts to guess the name for the decompressed
+file from that of the compressed file as follows:
+
+@multitable {anyothername} {becomes} {anyothername.out}
+@item filename.lz @tab becomes @tab filename
+@item filename.tlz @tab becomes @tab filename.tar
+@item anyothername @tab becomes @tab anyothername.out
+@end multitable
+
+As a self-check for your protection, plzip stores in the member trailer
+the 32-bit CRC of the original data and the size of the original data,
+to make sure that the decompressed version of the data is identical to
+the original. This guards against corruption of the compressed data, and
+against undetected bugs in plzip (hopefully very unlikely). The chances
+of data corruption going undetected are microscopic, less than one
+chance in 4000 million for each member processed. Be aware, though, that
+the check occurs upon decompression, so it can only tell you that
+something is wrong. It can't help you recover the original uncompressed
+data.
+
+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 plzip to panic.
+
+
+@node Invoking Plzip
+@chapter Invoking Plzip
+@cindex invoking
+@cindex options
+@cindex usage
+@cindex version
+
+The format for running plzip is:
+
+@example
+plzip [@var{options}] [@var{files}]
+@end example
+
+Plzip supports the following options:
+
+@table @samp
+@item --help
+@itemx -h
+Print an informative help message describing the options and exit.
+
+@item --version
+@itemx -V
+Print the version number of plzip on the standard output and exit.
+
+@item --stdout
+@itemx -c
+Compress or decompress to standard output. Needed when reading from a
+named pipe (fifo) or from a device.
+
+@item --decompress
+@itemx -d
+Decompress.
+
+@item --force
+@itemx -f
+Force overwrite of output file.
+
+@item --keep
+@itemx -k
+Keep (don't delete) input files during compression or decompression.
+
+@item --match-length=@var{length}
+@itemx -m @var{length}
+Set the match length limit in bytes. Valid values range from 5 to 273.
+Larger values usually give better compression ratios but longer
+compression times.
+
+@item --output=@var{file}
+@itemx -o @var{file}
+When reading from standard input and @samp{--stdout} has not been
+specified, use @samp{@var{file}} as the virtual name of the uncompressed
+file. This produces a file named @samp{@var{file}} when decompressing,
+and a file named @samp{@var{file}.lz} when compressing.
+
+@item --quiet
+@itemx -q
+Quiet operation. Suppress all messages.
+
+@item --dictionary-size=@var{size}
+@itemx -s @var{size}
+Set the dictionary size limit in bytes. Valid values range from 4KiB to
+512MiB. Note that dictionary sizes are quantized. If the specified size
+does not match one of the valid sizes, it will be rounded upwards.
+
+@item --test
+@itemx -t
+Check integrity of the specified file(s), but don't decompress them.
+This really performs a trial decompression and throws away the result.
+Use @samp{-tvv} or @samp{-tvvv} to see information about the file.
+
+@item --verbose
+@itemx -v
+Verbose mode. Show the compression ratio for each file processed.
+Further -v's increase the verbosity level.
+
+@item -1 .. -9
+Set the compression parameters (dictionary size and match length limit)
+as shown in the table below. Note that @samp{-9} can be much slower than
+@samp{-1}. These options have no effect when decompressing.
+
+@multitable {Level} {Dictionary size} {Match length limit}
+@item Level @tab Dictionary size @tab Match length limit
+@item -1 @tab 1MiB @tab 10 bytes
+@item -2 @tab 1MiB @tab 12 bytes
+@item -3 @tab 1MiB @tab 17 bytes
+@item -4 @tab 2MiB @tab 26 bytes
+@item -5 @tab 4MiB @tab 44 bytes
+@item -6 @tab 8MiB @tab 80 bytes
+@item -7 @tab 16MiB @tab 108 bytes
+@item -8 @tab 16MiB @tab 163 bytes
+@item -9 @tab 32MiB @tab 273 bytes
+@end multitable
+
+@item --fast
+@itemx --best
+Aliases for GNU gzip compatibility.
+
+@end table
+
+@sp 1
+Numbers given as arguments to options may be followed by a multiplier
+and an optional @samp{B} for "byte".
+
+Table of SI and binary prefixes (unit multipliers):
+
+@multitable {Prefix} {kilobyte (10^3 = 1000)} {|} {Prefix} {kibibyte (2^10 = 1024)}
+@item Prefix @tab Value @tab | @tab Prefix @tab Value
+@item k @tab kilobyte (10^3 = 1000) @tab | @tab Ki @tab kibibyte (2^10 = 1024)
+@item M @tab megabyte (10^6) @tab | @tab Mi @tab mebibyte (2^20)
+@item G @tab gigabyte (10^9) @tab | @tab Gi @tab gibibyte (2^30)
+@item T @tab terabyte (10^12) @tab | @tab Ti @tab tebibyte (2^40)
+@item P @tab petabyte (10^15) @tab | @tab Pi @tab pebibyte (2^50)
+@item E @tab exabyte (10^18) @tab | @tab Ei @tab exbibyte (2^60)
+@item Z @tab zettabyte (10^21) @tab | @tab Zi @tab zebibyte (2^70)
+@item Y @tab yottabyte (10^24) @tab | @tab Yi @tab yobibyte (2^80)
+@end multitable
+
+
+@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 member type, 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 have only one member and lack @samp{Member
+size}.
+
+@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 Problems
+@chapter Reporting Bugs
+@cindex bugs
+@cindex getting help
+
+There are probably bugs in plzip. 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 plzip, please send electronic mail to
+@email{lzip-bug@@nongnu.org}. Include the version number, which you can
+find by running @w{@samp{plzip --version}}.
+
+
+@node Concept Index
+@unnumbered Concept Index
+
+@printindex cp
+
+@bye