summaryrefslogtreecommitdiffstats
path: root/doc/plzip.texinfo
diff options
context:
space:
mode:
authorDaniel Baumann <mail@daniel-baumann.ch>2015-11-07 15:33:26 +0000
committerDaniel Baumann <mail@daniel-baumann.ch>2015-11-07 15:33:26 +0000
commit4766a0fb5fc0a2ce7c865450b1f63ddc6556aa3c (patch)
tree433a0c86a57b02c6ddf97910b122d8a3abe13ac8 /doc/plzip.texinfo
parentAdding upstream version 0.9. (diff)
downloadplzip-4766a0fb5fc0a2ce7c865450b1f63ddc6556aa3c.tar.xz
plzip-4766a0fb5fc0a2ce7c865450b1f63ddc6556aa3c.zip
Adding upstream version 1.0~rc1.upstream/1.0_rc1
Signed-off-by: Daniel Baumann <mail@daniel-baumann.ch>
Diffstat (limited to 'doc/plzip.texinfo')
-rw-r--r--doc/plzip.texinfo83
1 files changed, 49 insertions, 34 deletions
diff --git a/doc/plzip.texinfo b/doc/plzip.texinfo
index f981207..5e62234 100644
--- a/doc/plzip.texinfo
+++ b/doc/plzip.texinfo
@@ -6,8 +6,8 @@
@finalout
@c %**end of header
-@set UPDATED 1 March 2012
-@set VERSION 0.9
+@set UPDATED 8 March 2013
+@set VERSION 1.0-rc1
@dircategory Data Compression
@direntry
@@ -35,16 +35,16 @@
This manual is for Plzip (version @value{VERSION}, @value{UPDATED}).
@menu
-* Introduction:: Purpose and features of plzip
-* Invoking Plzip:: Command line interface
-* Program Design:: Internal structure of plzip
-* File Format:: Detailed format of the compressed file
-* Problems:: Reporting bugs
-* Concept Index:: Index of concepts
+* Introduction:: Purpose and features of plzip
+* Program Design:: Internal structure 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{} 2009, 2010, 2011, 2012 Antonio Diaz Diaz.
+Copyright @copyright{} 2009, 2010, 2011, 2012, 2013 Antonio Diaz Diaz.
This manual is free documentation: you have unlimited permission
to copy, distribute and modify it.
@@ -115,6 +115,28 @@ invalid input file, 3 for an internal consistency error (eg, bug) which
caused plzip to panic.
+@node Program Design
+@chapter Program Design
+@cindex program design
+
+For each input file, a splitter thread and several worker threads are
+created, acting the main thread as muxer (multiplexer) thread. A "packet
+courier" takes care of data transfers among threads and limits the
+maximum number of data blocks (packets) being processed simultaneously.
+
+The splitter reads data blocks from the input file, and distributes them
+to the workers. The workers (de)compress the blocks received from the
+splitter. The muxer collects processed packets from the workers, and
+writes them to the output file.
+
+When decompressing from a regular file, the splitter is removed and the
+workers read directly from the input file. If the output file is also a
+regular file, the muxer is also removed, and the workers write directly
+to the output file. With these optimizations, decompression speed of
+large files with many members is only limited by the number of
+processors available and by I/O speed.
+
+
@node Invoking Plzip
@chapter Invoking Plzip
@cindex invoking
@@ -180,7 +202,7 @@ usually give better compression ratios but longer compression times.
Set the number of worker threads. Valid values range from 1 to "as many
as your system can support". If this option is not used, plzip tries to
detect the number of processors in the system and use it as default
-value.
+value. @w{@samp{plzip --help}} shows the system's default value.
@item -o @var{file}
@itemx --output=@var{file}
@@ -268,25 +290,15 @@ Table of SI and binary prefixes (unit multipliers):
@end multitable
-@node Program Design
-@chapter Program Design
-@cindex program design
-
-For each input file, a splitter thread and several worker threads are
-created, acting the main thread as muxer (multiplexer) thread. A "packet
-courier" takes care of data transfers among threads and limits the
-maximum number of data blocks (packets) being processed simultaneously.
-
-The splitter reads data blocks from the input file, and distributes them
-to the workers. The workers (de)compress the blocks received from the
-splitter. The muxer collects processed packets from the workers, and
-writes them to the output file.
-
-
@node File Format
@chapter File Format
@cindex file format
+Perfection is reached, not when there is no longer anything to add, but
+when there is no longer anything to take away.@*
+--- Antoine de Saint-Exupery
+
+@sp 1
In the diagram below, a box like this:
@verbatim
+---+
@@ -322,15 +334,17 @@ All multibyte values are stored in little endian order.
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.
+Just in case something needs to be modified in the future. 1 for now.
@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).@*
+Lzip divides the distance between any two powers of 2 into 8 equally
+spaced intervals, named "wedges". The dictionary size is calculated by
+taking a power of 2 (the base size) and substracting from it a number of
+wedges between 0 and 7. The size of a wedge is (base_size / 16).@*
+Bits 4-0 contain the base 2 logarithm of the base size (12 to 29).@*
+Bits 7-5 contain the number of wedges (0 to 7) to substract from the
+base size to obtain the dictionary size.@*
+Example: 0xD3 = (2^19 - 6 * 2^15) = (512KiB - 6 * 32KiB) = 320KiB@*
Valid values for dictionary size range from 4KiB to 512MiB.
@item Lzma stream
@@ -344,8 +358,9 @@ CRC of the uncompressed original data.
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 multi-member files.
+Total size of the member, including header and trailer. This field acts
+as a distributed index, and facilitates safe recovery of undamaged
+members from multi-member files.
@end table