diff options
Diffstat (limited to 'doc/lzlib.info')
| -rw-r--r-- | doc/lzlib.info | 284 |
1 files changed, 242 insertions, 42 deletions
diff --git a/doc/lzlib.info b/doc/lzlib.info index a2a8c68..23a4d21 100644 --- a/doc/lzlib.info +++ b/doc/lzlib.info @@ -11,25 +11,26 @@ File: lzlib.info, Node: Top, Next: Introduction, Up: (dir) Lzlib Manual ************ -This manual is for Lzlib (version 1.9, 11 April 2017). +This manual is for Lzlib (version 1.10, 7 February 2018). * Menu: -* Introduction:: Purpose and features of lzlib -* Library version:: Checking library version -* Buffering:: Sizes of lzlib's buffers -* Parameter limits:: Min / max values for some parameters -* Compression functions:: Descriptions of the compression functions -* Decompression functions:: Descriptions of the decompression functions -* Error codes:: Meaning of codes returned by functions -* Error messages:: Error messages corresponding to error codes -* Data format:: Detailed format of the compressed data -* Examples:: A small tutorial with examples -* Problems:: Reporting bugs -* Concept index:: Index of concepts +* Introduction:: Purpose and features of lzlib +* Library version:: Checking library version +* Buffering:: Sizes of lzlib's buffers +* Parameter limits:: Min / max values for some parameters +* Compression functions:: Descriptions of the compression functions +* Decompression functions:: Descriptions of the decompression functions +* Error codes:: Meaning of codes returned by functions +* Error messages:: Error messages corresponding to error codes +* Invoking minilzip:: Command line interface of the test program +* Data format:: Detailed format of the compressed data +* Examples:: A small tutorial with examples +* Problems:: Reporting bugs +* Concept index:: Index of concepts - Copyright (C) 2009-2017 Antonio Diaz Diaz. + Copyright (C) 2009-2018 Antonio Diaz Diaz. This manual is free documentation: you have unlimited permission to copy, distribute and modify it. @@ -50,7 +51,7 @@ archiving, taking into account both data integrity and decoder availability: * The lzip format provides very safe integrity checking and some data - recovery means. The lziprecover program can repair bit-flip errors + recovery means. The lziprecover program can repair bit flip errors (one of the most common forms of data corruption) in lzip files, and provides data recovery capabilities, including error-checked merging of damaged copies of a file. *Note Data safety: @@ -170,8 +171,9 @@ minimum sizes: * Input compression buffer. Written to by the 'LZ_compress_write' function. For the normal variant of LZMA, its size is two times - the dictionary size set with the 'LZ_compress_open' function or 64 - KiB, whichever is larger. For the fast variant, its size is 1 MiB. + the dictionary size set with the 'LZ_compress_open' function or + 64 KiB, whichever is larger. For the fast variant, its size is + 1 MiB. * Output compression buffer. Read from by the 'LZ_compress_read' function. Its size is 64 KiB. @@ -326,6 +328,7 @@ calling 'LZ_compress_errno' before using it. ENCODER ) Returns 1 if all the data have been read and 'LZ_compress_close' can be safely called. Otherwise it returns 0. + 'LZ_compress_finished' implies 'LZ_compress_member_finished'. -- Function: int LZ_compress_member_finished ( struct LZ_Encoder * const ENCODER ) @@ -532,14 +535,19 @@ whether a call failed. If the call failed, then you can examine The end of the data stream was reached in the middle of a member. -- Constant: enum LZ_Errno LZ_data_error - The data stream is corrupt. + The data stream is corrupt. If 'LZ_decompress_member_position' is 6 + or less, it indicates either a format version not supported, an + invalid dictionary size, a corrupt header in a multimember data + stream, or trailing data too similar to a valid lzip header. + Lziprecover can be used to remove conflicting trailing data from a + file. -- Constant: enum LZ_Errno LZ_library_error A bug was detected in the library. Please, report it (*note Problems::). -File: lzlib.info, Node: Error messages, Next: Data format, Prev: Error codes, Up: Top +File: lzlib.info, Node: Error messages, Next: Invoking minilzip, Prev: Error codes, Up: Top 8 Error messages **************** @@ -555,10 +563,198 @@ File: lzlib.info, Node: Error messages, Next: Data format, Prev: Error codes, 'LZ_(de)compress_errno'. -File: lzlib.info, Node: Data format, Next: Examples, Prev: Error messages, Up: Top +File: lzlib.info, Node: Invoking minilzip, Next: Data format, Prev: Error messages, Up: Top + +9 Invoking minilzip +******************* + +The format for running minilzip is: + + minilzip [OPTIONS] [FILES] + +'-' used as a FILE argument means standard input. It can be mixed with +other FILES and is read just once, the first time it appears in the +command line. + + minilzip supports the following options: + +'-h' +'--help' + Print an informative help message describing the options and exit. + +'-V' +'--version' + Print the version number of minilzip on the standard output and + exit. + +'-a' +'--trailing-error' + Exit with error status 2 if any remaining input is detected after + decompressing the last member. Such remaining input is usually + trailing garbage that can be safely ignored. + +'-b BYTES' +'--member-size=BYTES' + When compressing, set the member size limit to BYTES. A small + member size may degrade compression ratio, so use it only when + needed. Valid values range from 100 kB to 2 PiB. Defaults to + 2 PiB. + +'-c' +'--stdout' + Compress or decompress to standard output; keep input files + unchanged. If compressing several files, each file is compressed + independently. This option is needed when reading from a named + pipe (fifo) or from a device. Use it also to recover as much of + the decompressed data as possible when decompressing a corrupt + file. + +'-d' +'--decompress' + Decompress the specified files. If a file does not exist or can't + be opened, minilzip continues decompressing the rest of the files. + If a file fails to decompress, or is a terminal, minilzip exits + immediately without decompressing the rest of the files. + +'-f' +'--force' + Force overwrite of output files. + +'-F' +'--recompress' + When compressing, force re-compression of files whose name already + has the '.lz' or '.tlz' suffix. + +'-k' +'--keep' + Keep (don't delete) input files during compression or + decompression. + +'-m BYTES' +'--match-length=BYTES' + When compressing, 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. -9 Data format -************* +'-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, or a + file named 'FILE.lz' when compressing. A second '.lz' extension is + not added if 'FILE' already ends in '.lz' or '.tlz'. When + compressing and splitting the output in volumes, several files + named 'FILE00001.lz', 'FILE00002.lz', etc, are created. + +'-q' +'--quiet' + Quiet operation. Suppress all messages. + +'-s BYTES' +'--dictionary-size=BYTES' + When compressing, set the dictionary size limit in bytes. Minilzip + will use the smallest possible dictionary size for each file + without exceeding this limit. Valid values range from 4 KiB to + 512 MiB. Values 12 to 29 are interpreted as powers of two, meaning + 2^12 to 2^29 bytes. Note that dictionary sizes are quantized. If + the specified size does not match one of the valid sizes, it will + be rounded upwards by adding up to (BYTES / 8) to it. + + For maximum compression you should use a dictionary size limit as + large as possible, but keep in mind that the decompression memory + requirement is affected at compression time by the choice of + dictionary size limit. + +'-S BYTES' +'--volume-size=BYTES' + When compressing, split the compressed output into several volume + files with names 'original_name00001.lz', 'original_name00002.lz', + etc, and set the volume size limit to BYTES. Input files are kept + unchanged. Each volume is a complete, maybe multimember, lzip + file. A small volume size may degrade compression ratio, so use it + only when needed. Valid values range from 100 kB to 4 EiB. + +'-t' +'--test' + Check integrity of the specified files, 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 + files. If a file fails the test, does not exist, can't be opened, + or is a terminal, minilzip continues checking the rest of the + files. A final diagnostic is shown at verbosity level 1 or higher + if any file fails the test when testing multiple files. + +'-v' +'--verbose' + Verbose mode. + When compressing, show the compression ratio and size for each file + processed. + When decompressing or testing, further -v's (up to 4) increase the + verbosity level, showing status, compression ratio, dictionary + size, and trailer contents (CRC, data size, member size). + +'-0 .. -9' + Set the compression parameters (dictionary size and match length + limit) as shown in the table below. The default compression level + is '-6'. Note that '-9' can be much slower than '-0'. These + options have no effect when decompressing or testing. + + 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 '--dictionary-size' and + '--match-length' options directly to achieve optimal performance. + + Level Dictionary size Match length limit + -0 64 KiB 16 bytes + -1 1 MiB 5 bytes + -2 1.5 MiB 6 bytes + -3 2 MiB 8 bytes + -4 3 MiB 12 bytes + -5 4 MiB 20 bytes + -6 8 MiB 36 bytes + -7 16 MiB 68 bytes + -8 24 MiB 132 bytes + -9 32 MiB 273 bytes + +'--fast' +'--best' + Aliases for GNU gzip compatibility. + +'--loose-trailing' + When decompressing or testing, allow trailing data whose first + bytes are so similar to the magic bytes of a lzip header that they + can be confused with a corrupt header. Use this option if a file + triggers a "corrupt header" error and the cause is not indeed a + corrupt header. + + + 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) + + + Exit status: 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 minilzip to panic. + + +File: lzlib.info, Node: Data format, Next: Examples, Prev: Invoking minilzip, Up: Top + +10 Data format +************** Perfection is reached, not when there is no longer anything to add, but when there is no longer anything to take away. @@ -578,9 +774,9 @@ when there is no longer anything to take away. represents a variable number of bytes. - A lzip data stream consists of a series of "members" (compressed data -sets). The members simply appear one after another in the data stream, -with no additional information before, between, or after them. + A lzip data stream consists of a series of "members" (compressed +data sets). The members simply appear one after another in the data +stream, with no additional information before, between, or after them. Each member has the following structure: +--+--+--+--+----+----+=============+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ @@ -630,7 +826,7 @@ with no additional information before, between, or after them. File: lzlib.info, Node: Examples, Next: Problems, Prev: Data format, Up: Top -10 A small tutorial with examples +11 A small tutorial with examples ********************************* This chapter shows the order in which the library functions should be @@ -709,15 +905,15 @@ Example 5: Multimember compression (MEMBER_SIZE < total output). Example 6: Multimember compression (user-restarted members). - 1) LZ_compress_open + 1) LZ_compress_open (with MEMBER_SIZE > largest member). 2) LZ_compress_write 3) LZ_compress_read 4) go back to step 2 until member termination is desired 5) LZ_compress_finish 6) LZ_compress_read 7) go back to step 6 until LZ_compress_member_finished returns 1 - 8) verify that LZ_compress_finished returns 1 - 9) go to step 12 if all input data have been written + 9) go to step 12 if all input data have been written and + LZ_compress_finished returns 1 10) LZ_compress_restart_member 11) go back to step 2 12) LZ_compress_close @@ -750,7 +946,7 @@ next member in case of data error. File: lzlib.info, Node: Problems, Next: Concept index, Prev: Examples, Up: Top -11 Reporting bugs +12 Reporting bugs ***************** There are probably bugs in lzlib. There are certainly errors and @@ -783,25 +979,29 @@ Concept index * examples: Examples. (line 6) * getting help: Problems. (line 6) * introduction: Introduction. (line 6) +* invoking: Invoking minilzip. (line 6) * library version: Library version. (line 6) +* options: Invoking minilzip. (line 6) * parameter limits: Parameter limits. (line 6) Tag Table: Node: Top220 -Node: Introduction1303 -Node: Library version6115 -Node: Buffering6760 -Node: Parameter limits7980 -Node: Compression functions8939 -Node: Decompression functions15481 -Node: Error codes21651 -Node: Error messages23626 -Node: Data format24205 -Node: Examples26770 -Node: Problems30851 -Node: Concept index31423 +Node: Introduction1342 +Node: Library version6154 +Node: Buffering6799 +Node: Parameter limits8024 +Node: Compression functions8983 +Node: Decompression functions15592 +Node: Error codes21762 +Node: Error messages24064 +Node: Invoking minilzip24649 +Ref: --trailing-error25243 +Node: Data format31883 +Node: Examples34454 +Node: Problems38570 +Node: Concept index39142 End Tag Table |