diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/plzip.1 | 6 | ||||
| -rw-r--r-- | doc/plzip.info | 188 | ||||
| -rw-r--r-- | doc/plzip.texi (renamed from doc/plzip.texinfo) | 61 |
3 files changed, 138 insertions, 117 deletions
diff --git a/doc/plzip.1 b/doc/plzip.1 index 291a67f..11bd052 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" "September 2013" "Plzip 1.1" "User Commands" +.TH PLZIP "1" "January 2014" "Plzip 1.2-pre1" "User Commands" .SH NAME Plzip \- reduces the size of files .SH SYNOPSIS @@ -84,8 +84,8 @@ Plzip home page: http://www.nongnu.org/lzip/plzip.html .SH COPYRIGHT Copyright \(co 2009 Laszlo Ersek. .br -Copyright \(co 2013 Antonio Diaz Diaz. -Using Lzlib 1.5 +Copyright \(co 2014 Antonio Diaz Diaz. +Using Lzlib 1.6\-pre1 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. diff --git a/doc/plzip.info b/doc/plzip.info index 7461e06..717471c 100644 --- a/doc/plzip.info +++ b/doc/plzip.info @@ -1,5 +1,4 @@ -This is plzip.info, produced by makeinfo version 4.13 from -plzip.texinfo. +This is plzip.info, produced by makeinfo version 4.13+ from plzip.texi. INFO-DIR-SECTION Data Compression START-INFO-DIR-ENTRY @@ -12,7 +11,7 @@ File: plzip.info, Node: Top, Next: Introduction, Up: (dir) Plzip Manual ************ -This manual is for Plzip (version 1.1, 17 September 2013). +This manual is for Plzip (version 1.2-pre1, 20 January 2014). * Menu: @@ -24,7 +23,7 @@ This manual is for Plzip (version 1.1, 17 September 2013). * Concept index:: Index of concepts - Copyright (C) 2009, 2010, 2011, 2012, 2013 Antonio Diaz Diaz. + Copyright (C) 2009, 2010, 2011, 2012, 2013, 2014 Antonio Diaz Diaz. This manual is free documentation: you have unlimited permission to copy, distribute and modify it. @@ -41,12 +40,9 @@ the one of lzip, bzip2 or gzip. Plzip can compress/decompress large files on multiprocessor machines much faster than lzip, at the cost of a slightly reduced compression -ratio. On files large enough (several GB), plzip can use hundreds of -processors. On files of only a few MB it is better to use lzip. - - Plzip uses the same well-defined exit status values used by lzip and -bzip2, which makes it safer when used in pipes or scripts than -compressors returning ambiguous warning values, like gzip. +ratio. Note that the number of usable threads is limited by file size, +so on files larger than a few GB plzip can use hundreds of processors, +but on files of only a few MB plzip is no faster than lzip. Plzip uses the lzip file format; the files produced by plzip are fully compatible with lzip-1.4 or newer, and can be rescued with @@ -71,12 +67,27 @@ lziprecover program. Lziprecover makes lzip files resistant to bit-flip recovery capabilities, including error-checked merging of damaged copies of a file. - 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. + Plzip uses the same well-defined exit status values used by lzip and +bzip2, which makes it safer than compressors returning ambiguous warning +values (like gzip) when it is used as a back end for tar or zutils. + + When compressing, plzip replaces every file given in the command line +with a compressed version of itself, with the name "original_name.lz". +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 + + (De)compressing a file is much like copying or moving it; therefore +plzip preserves the access and modification dates, permissions, and, +when possible, ownership of the file just as "cp -p" does. (If the user +ID or the group ID can't be duplicated, the file permission bits +S_ISUID and S_ISGID are cleared). + + 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 @@ -88,19 +99,12 @@ 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 - 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 +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 -'. +'plzip -cd file.lz | cmp file -'. File: plzip.info, Node: Program design, Next: Invoking plzip, Prev: Introduction, Up: Top @@ -137,73 +141,78 @@ The format for running plzip is: Plzip supports the following options: -`-h' -`--help' +'-h' +'--help' Print an informative help message describing the options and exit. -`-V' -`--version' +'-V' +'--version' Print the version number of plzip on the standard output and exit. -`-B BYTES' -`--data-size=BYTES' +'-B BYTES' +'--data-size=BYTES' Set the input data block size in bytes. The input file will be divided in chunks of this size before compression is performed. Valid values range from 8 KiB to 1 GiB. Default value is two times the dictionary size. Plzip will reduce the dictionary size if it is larger than the chosen data size. -`-c' -`--stdout' +'-c' +'--stdout' Compress or decompress to standard output. Needed when reading from a named pipe (fifo) or from a device. -`-d' -`--decompress' +'-d' +'--decompress' Decompress. -`-f' -`--force' +'-f' +'--force' Force overwrite of output files. -`-F' -`--recompress' - Force recompression of files whose name already has the `.lz' or - `.tlz' suffix. +'-F' +'--recompress' + Force recompression of files whose name already has the '.lz' or + '.tlz' suffix. -`-k' -`--keep' +'-k' +'--keep' Keep (don't delete) input files during compression or decompression. -`-m BYTES' -`--match-length=BYTES' +'-m BYTES' +'--match-length=BYTES' Set the match length limit in bytes. After a match this long is found, the search is finished. Valid values range from 5 to 273. Larger values usually give better compression ratios but longer compression times. -`-n N' -`--threads=N' +'-n N' +'--threads=N' 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. `plzip --help' shows the system's default + use it as default value. 'plzip --help' shows the system's default value. -`-o FILE' -`--output=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. + Note that the number of usable threads is limited to + ceil( file_size / data_size ) during compression (*note + --data-size::), and to the number of members in the input during + decompression. + +'-o FILE' +'--output=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. -`-q' -`--quiet' +'-q' +'--quiet' Quiet operation. Suppress all messages. -`-s BYTES' -`--dictionary-size=BYTES' +'-s BYTES' +'--dictionary-size=BYTES' Set the dictionary size limit in bytes. Valid values range from 4 KiB to 512 MiB. Plzip will use the smallest possible dictionary size for each member without exceeding this limit. Note that @@ -216,33 +225,33 @@ The format for running plzip is: requirement is affected at compression time by the choice of dictionary size limit. -`-t' -`--test' +'-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 result. Use it together with '-v' to see information about the file. -`-v' -`--verbose' +'-v' +'--verbose' Verbose mode. When compressing, show the compression ratio for each file - processed. A second -v shows the progress of compression. + processed. A second '-v' shows the progress of compression. When decompressing or testing, further -v's (up to 4) increase the verbosity level, showing status, compression ratio, decompressed size, and compressed size. -`-1 .. -9' +'-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. + limit) as shown in the table below. Note that '-9' can be much + slower than '-1'. These options have no effect when decompressing. The bidimensional parameter space of LZMA can't be mapped to a linear scale optimal for all files. If your files are large, very - repetitive, etc, you may need to use the `--match-length' and - `--dictionary-size' options directly to achieve optimal - performance. For example, `-9m64' usually compresses executables - more (and faster) than `-9'. + repetitive, etc, you may need to use the '--match-length' and + '--dictionary-size' options directly to achieve optimal + performance. For example, '-9m64' usually compresses executables + more (and faster) than '-9'. Level Dictionary size Match length limit -1 1 MiB 5 bytes @@ -255,13 +264,13 @@ The format for running plzip is: -8 24 MiB 132 bytes -9 32 MiB 273 bytes -`--fast' -`--best' +'--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". +and an optional 'B' for "byte". Table of SI and binary prefixes (unit multipliers): @@ -316,15 +325,15 @@ additional information before, between, or after them. All multibyte values are stored in little endian order. -`ID string' +'ID string' A four byte string, identifying the lzip format, with the value "LZIP" (0x4C, 0x5A, 0x49, 0x50). -`VN (version number, 1 byte)' +'VN (version number, 1 byte)' Just in case something needs to be modified in the future. 1 for now. -`DS (coded dictionary size, 1 byte)' +'DS (coded dictionary size, 1 byte)' 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 @@ -336,18 +345,18 @@ additional information before, between, or after them. Example: 0xD3 = 2^19 - 6 * 2^15 = 512 KiB - 6 * 32 KiB = 320 KiB Valid values for dictionary size range from 4 KiB to 512 MiB. -`Lzma stream' +'Lzma stream' The lzma stream, finished by an end of stream marker. Uses default values for encoder properties. See the lzip manual for a full description. -`CRC32 (4 bytes)' +'CRC32 (4 bytes)' CRC of the uncompressed original data. -`Data size (8 bytes)' +'Data size (8 bytes)' Size of the uncompressed original data. -`Member size (8 bytes)' +'Member size (8 bytes)' Total size of the member, including header and trailer. This field acts as a distributed index, allows the verification of stream integrity, and facilitates safe recovery of undamaged members from @@ -367,7 +376,7 @@ 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'. +by running 'plzip --version'. File: plzip.info, Node: Concept index, Prev: Problems, Up: Top @@ -391,13 +400,14 @@ Concept index Tag Table: -Node: Top223 -Node: Introduction871 -Node: Program design4426 -Node: Invoking plzip5480 -Node: File format10864 -Node: Problems13369 -Node: Concept index13898 +Node: Top221 +Node: Introduction878 +Node: Program design4650 +Node: Invoking plzip5704 +Ref: --data-size6149 +Node: File format11300 +Node: Problems13805 +Node: Concept index14334 End Tag Table diff --git a/doc/plzip.texinfo b/doc/plzip.texi index 0370677..413a9e3 100644 --- a/doc/plzip.texinfo +++ b/doc/plzip.texi @@ -6,8 +6,8 @@ @finalout @c %**end of header -@set UPDATED 17 September 2013 -@set VERSION 1.1 +@set UPDATED 20 January 2014 +@set VERSION 1.2-pre1 @dircategory Data Compression @direntry @@ -44,7 +44,8 @@ This manual is for Plzip (version @value{VERSION}, @value{UPDATED}). @end menu @sp 1 -Copyright @copyright{} 2009, 2010, 2011, 2012, 2013 Antonio Diaz Diaz. +Copyright @copyright{} 2009, 2010, 2011, 2012, 2013, 2014 +Antonio Diaz Diaz. This manual is free documentation: you have unlimited permission to copy, distribute and modify it. @@ -60,12 +61,9 @@ the one of lzip, bzip2 or gzip. Plzip can compress/decompress large files on multiprocessor machines much faster than lzip, at the cost of a slightly reduced compression -ratio. On files large enough (several GB), plzip can use hundreds of -processors. On files of only a few MB it is better to use lzip. - -Plzip uses the same well-defined exit status values used by lzip and -bzip2, which makes it safer when used in pipes or scripts than -compressors returning ambiguous warning values, like gzip. +ratio. Note that the number of usable threads is limited by file size, +so on files larger than a few GB plzip can use hundreds of processors, +but on files of only a few MB plzip is no faster than lzip. Plzip uses the lzip file format; the files produced by plzip are fully compatible with lzip-1.4 or newer, and can be rescued with lziprecover. @@ -89,12 +87,29 @@ lziprecover program. Lziprecover makes lzip files resistant to bit-flip recovery capabilities, including error-checked merging of damaged copies of a file. -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. +Plzip uses the same well-defined exit status values used by lzip and +bzip2, which makes it safer than compressors returning ambiguous warning +values (like gzip) when it is used as a back end for tar or zutils. + +When compressing, plzip replaces every file given in the command line +with a compressed version of itself, with the name "original_name.lz". +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 + +(De)compressing a file is much like copying or moving it; therefore plzip +preserves the access and modification dates, permissions, and, when +possible, ownership of the file just as "cp -p" does. (If the user ID or +the group ID can't be duplicated, the file permission bits S_ISUID and +S_ISGID are cleared). + +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 @@ -106,15 +121,6 @@ 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 - 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 @@ -171,6 +177,7 @@ Print the version number of plzip on the standard output and exit. @item -B @var{bytes} @itemx --data-size=@var{bytes} +@anchor{--data-size} Set the input data block size in bytes. The input file will be divided in chunks of this size before compression is performed. Valid values range from 8 KiB to 1 GiB. Default value is two times the dictionary @@ -212,6 +219,10 @@ 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. @w{@samp{plzip --help}} shows the system's default value. +Note that the number of usable threads is limited to @w{ceil( file_size +/ data_size )} during compression (@pxref{--data-size}), and to the +number of members in the input during decompression. + @item -o @var{file} @itemx --output=@var{file} When reading from standard input and @samp{--stdout} has not been @@ -245,7 +256,7 @@ Use it together with @samp{-v} to see information about the file. @itemx --verbose Verbose mode.@* When compressing, show the compression ratio for each file processed. A -second -v shows the progress of compression.@* +second @samp{-v} shows the progress of compression.@* When decompressing or testing, further -v's (up to 4) increase the verbosity level, showing status, compression ratio, decompressed size, and compressed size. |