From 86d8a187c1da626287cc436debbb5658b1884f03 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sat, 7 Nov 2015 16:33:57 +0100 Subject: Merging upstream version 1.0~rc1. Signed-off-by: Daniel Baumann --- doc/plzip.1 | 8 ++-- doc/plzip.info | 116 ++++++++++++++++++++++++++++++++---------------------- doc/plzip.texinfo | 90 ++++++++++++++++++++++++++---------------- 3 files changed, 130 insertions(+), 84 deletions(-) (limited to 'doc') diff --git a/doc/plzip.1 b/doc/plzip.1 index ec3fc36..2b1261b 100644 --- a/doc/plzip.1 +++ b/doc/plzip.1 @@ -1,5 +1,5 @@ .\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.37.1. -.TH PLZIP "1" "January 2012" "Plzip 0.8" "User Commands" +.TH PLZIP "1" "March 2013" "Plzip 1.0-rc1" "User Commands" .SH NAME Plzip \- reduces the size of files .SH SYNOPSIS @@ -37,7 +37,7 @@ keep (don't delete) input files set match length limit in bytes [36] .TP \fB\-n\fR, \fB\-\-threads=\fR -set the number of (de)compression threads +set number of (de)compression threads [1] .TP \fB\-o\fR, \fB\-\-output=\fR if reading stdin, place the output into @@ -78,8 +78,8 @@ Plzip home page: http://www.nongnu.org/lzip/plzip.html .SH COPYRIGHT Copyright \(co 2009 Laszlo Ersek. .br -Copyright \(co 2012 Antonio Diaz Diaz. -Using Lzlib 1.3\-rc1 +Copyright \(co 2013 Antonio Diaz Diaz. +Using Lzlib 1.4\-rc2 License GPLv3+: GNU GPL version 3 or later .br This is free software: you are free to change and redistribute it. diff --git a/doc/plzip.info b/doc/plzip.info index 3a12bef..bf22e32 100644 --- a/doc/plzip.info +++ b/doc/plzip.info @@ -12,25 +12,25 @@ File: plzip.info, Node: Top, Next: Introduction, Up: (dir) Plzip Manual ************ -This manual is for Plzip (version 0.8, 17 January 2012). +This manual is for Plzip (version 1.0-rc1, 8 March 2013). * 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 - Copyright (C) 2009, 2010, 2011, 2012 Antonio Diaz Diaz. + Copyright (C) 2009, 2010, 2011, 2012, 2013 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 +File: plzip.info, Node: Introduction, Next: Program Design, Prev: Top, Up: Top 1 Introduction ************** @@ -81,15 +81,45 @@ 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. + WARNING! Even if plzip is bug-free, other causes may result in a +corrupt compressed file (bugs in the system libraries, memory errors, +etc). Therefore, if the data you are going to compress is important, +give the `--keep' option to plzip and do not remove the original file +until you verify the compressed file with a command like +`plzip -cd file.lz | cmp file -'. + 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: Program Design, Prev: Introduction, Up: Top +File: plzip.info, Node: Program Design, Next: Invoking Plzip, Prev: Introduction, Up: Top + +2 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. + + +File: plzip.info, Node: Invoking Plzip, Next: File Format, Prev: Program Design, Up: Top -2 Invoking Plzip +3 Invoking Plzip **************** The format for running plzip is: @@ -149,7 +179,8 @@ The format for running plzip is: 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. + use it as default value. `plzip --help' shows the system's default + value. `-o FILE' `--output=FILE' @@ -236,28 +267,17 @@ Z zettabyte (10^21) | Zi zebibyte (2^70) Y yottabyte (10^24) | Yi yobibyte (2^80)  -File: plzip.info, Node: Program Design, Next: File Format, Prev: Invoking Plzip, Up: Top - -3 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. - - -File: plzip.info, Node: File Format, Next: Problems, Prev: Program Design, Up: Top +File: plzip.info, Node: File Format, Next: Problems, Prev: Invoking Plzip, Up: Top 4 File Format ************* -In the diagram below, a box like this: +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 + + + In the diagram below, a box like this: +---+ | | <-- the vertical bars might be missing +---+ @@ -286,15 +306,19 @@ additional information before, between, or after them. "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. + Just in case something needs to be modified in the future. 1 for + now. `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. `Lzma stream' @@ -308,9 +332,9 @@ additional information before, between, or after them. 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 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.  @@ -351,12 +375,12 @@ Concept Index  Tag Table: Node: Top223 -Node: Introduction845 -Node: Invoking Plzip3641 -Node: Program Design8597 -Node: File Format9259 -Node: Problems11254 -Node: Concept Index11783 +Node: Introduction864 +Node: Program Design4030 +Node: Invoking Plzip5084 +Node: File Format10093 +Node: Problems12473 +Node: Concept Index13002  End Tag Table diff --git a/doc/plzip.texinfo b/doc/plzip.texinfo index c83d5a5..5e62234 100644 --- a/doc/plzip.texinfo +++ b/doc/plzip.texinfo @@ -6,8 +6,8 @@ @finalout @c %**end of header -@set UPDATED 17 January 2012 -@set VERSION 0.8 +@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. @@ -102,12 +102,41 @@ 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. +WARNING! Even if plzip is bug-free, other causes may result in a corrupt +compressed file (bugs in the system libraries, memory errors, etc). +Therefore, if the data you are going to compress is important, give the +@samp{--keep} option to plzip and do not remove the original file until +you verify the compressed file with a command like +@w{@samp{plzip -cd file.lz | cmp file -}}. + 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 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 @@ -173,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} @@ -261,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 +---+ @@ -315,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 @@ -337,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 -- cgit v1.2.3