"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "doc/lzlib.info" between
lzlib-1.11.tar.lz and lzlib-1.12-rc1.tar.lz

About: Lzlib is a data compression library providing in-memory LZMA compression and decompression functions using the lzip format. Release candidate.

lzlib.info  (lzlib-1.11.tar.lz):lzlib.info  (lzlib-1.12-rc1.tar.lz)
File: lzlib.info, Node: Top, Next: Introduction, Up: (dir) File: lzlib.info, Node: Top, Next: Introduction, Up: (dir)
Lzlib Manual Lzlib Manual
************ ************
This manual is for Lzlib (version 1.11, 2 January 2019). This manual is for Lzlib (version 1.12-rc1, 6 June 2020).
* Menu: * Menu:
* Introduction:: Purpose and features of lzlib * Introduction:: Purpose and features of lzlib
* Library version:: Checking library version * Library version:: Checking library version
* Buffering:: Sizes of lzlib's buffers * Buffering:: Sizes of lzlib's buffers
* Parameter limits:: Min / max values for some parameters * Parameter limits:: Min / max values for some parameters
* Compression functions:: Descriptions of the compression functions * Compression functions:: Descriptions of the compression functions
* Decompression functions:: Descriptions of the decompression functions * Decompression functions:: Descriptions of the decompression functions
* Error codes:: Meaning of codes returned by functions * Error codes:: Meaning of codes returned by functions
* Error messages:: Error messages corresponding to error codes * Error messages:: Error messages corresponding to error codes
* Invoking minilzip:: Command line interface of the test program * Invoking minilzip:: Command line interface of the test program
* Data format:: Detailed format of the compressed data * Data format:: Detailed format of the compressed data
* Examples:: A small tutorial with examples * Examples:: A small tutorial with examples
* Problems:: Reporting bugs * Problems:: Reporting bugs
* Concept index:: Index of concepts * Concept index:: Index of concepts
Copyright (C) 2009-2019 Antonio Diaz Diaz. Copyright (C) 2009-2020 Antonio Diaz Diaz.
This manual is free documentation: you have unlimited permission to This manual is free documentation: you have unlimited permission to copy,
copy, distribute and modify it. distribute, and modify it.
File: lzlib.info, Node: Introduction, Next: Library version, Prev: Top, Up: Top File: lzlib.info, Node: Introduction, Next: Library version, Prev: Top, Up: Top
1 Introduction 1 Introduction
************** **************
Lzlib is a data compression library providing in-memory LZMA Lzlib is a data compression library providing in-memory LZMA compression
compression and decompression functions, including integrity checking and decompression functions, including integrity checking of the
of the decompressed data. The compressed data format used by the decompressed data. The compressed data format used by the library is the
library is the lzip format. Lzlib is written in C. lzip format. Lzlib is written in C.
The lzip file format is designed for data sharing and long-term The lzip file format is designed for data sharing and long-term
archiving, taking into account both data integrity and decoder archiving, taking into account both data integrity and decoder availability:
availability:
* The lzip format provides very safe integrity checking and some data * The lzip format provides very safe integrity checking and some data
recovery means. The lziprecover program can repair bit flip errors recovery means. The program lziprecover can repair bit flip errors
(one of the most common forms of data corruption) in lzip files, (one of the most common forms of data corruption) in lzip files, and
and provides data recovery capabilities, including error-checked provides data recovery capabilities, including error-checked merging
merging of damaged copies of a file. *Note Data safety: of damaged copies of a file. *Note Data safety: (lziprecover)Data
(lziprecover)Data safety. safety.
* The lzip format is as simple as possible (but not simpler). The * The lzip format is as simple as possible (but not simpler). The lzip
lzip manual provides the source code of a simple decompressor manual provides the source code of a simple decompressor along with a
along with a detailed explanation of how it works, so that with detailed explanation of how it works, so that with the only help of the
the only help of the lzip manual it would be possible for a lzip manual it would be possible for a digital archaeologist to extract
digital archaeologist to extract the data from a lzip file long the data from a lzip file long after quantum computers eventually
after quantum computers eventually render LZMA obsolete. render LZMA obsolete.
* Additionally the lzip reference implementation is copylefted, which * Additionally the lzip reference implementation is copylefted, which
guarantees that it will remain free forever. guarantees that it will remain free forever.
A nice feature of the lzip format is that a corrupt byte is easier to A nice feature of the lzip format is that a corrupt byte is easier to
repair the nearer it is from the beginning of the file. Therefore, with repair the nearer it is from the beginning of the file. Therefore, with the
the help of lziprecover, losing an entire archive just because of a help of lziprecover, losing an entire archive just because of a corrupt
corrupt byte near the beginning is a thing of the past. byte near the beginning is a thing of the past.
The functions and variables forming the interface of the compression The functions and variables forming the interface of the compression
library are declared in the file 'lzlib.h'. Usage examples of the library are declared in the file 'lzlib.h'. Usage examples of the library
library are given in the files 'main.c' and 'bbexample.c' from the are given in the files 'bbexample.c', 'ffexample.c', and 'main.c' from the
source distribution. source distribution.
Compression/decompression is done by repeatedly calling a couple of Compression/decompression is done by repeatedly calling a couple of
read/write functions until all the data have been processed by the read/write functions until all the data have been processed by the library.
library. This interface is safer and less error prone than the This interface is safer and less error prone than the traditional zlib
traditional zlib interface. interface.
Compression/decompression is done when the read function is called. Compression/decompression is done when the read function is called. This
This means the value returned by the position functions will not be means the value returned by the position functions will not be updated until
updated until a read call, even if a lot of data are written. If you a read call, even if a lot of data are written. If you want the data to be
want the data to be compressed in advance, just call the read function compressed in advance, just call the read function with a SIZE equal to 0.
with a SIZE equal to 0.
If all the data to be compressed are written in advance, lzlib will If all the data to be compressed are written in advance, lzlib will
automatically adjust the header of the compressed data to use the automatically adjust the header of the compressed data to use the largest
largest dictionary size that does not exceed neither the data size nor dictionary size that does not exceed neither the data size nor the limit
the limit given to 'LZ_compress_open'. This feature reduces the amount given to 'LZ_compress_open'. This feature reduces the amount of memory
of memory needed for decompression and allows minilzip to produce needed for decompression and allows minilzip to produce identical compressed
identical compressed output as lzip. output as lzip.
Lzlib will correctly decompress a data stream which is the Lzlib will correctly decompress a data stream which is the concatenation
concatenation of two or more compressed data streams. The result is the of two or more compressed data streams. The result is the concatenation of
concatenation of the corresponding decompressed data streams. Integrity the corresponding decompressed data streams. Integrity testing of
testing of concatenated compressed data streams is also supported. concatenated compressed data streams is also supported.
Lzlib is able to compress and decompress streams of unlimited size by Lzlib is able to compress and decompress streams of unlimited size by
automatically creating multimember output. The members so created are automatically creating multimember output. The members so created are large,
large, about 2 PiB each. about 2 PiB each.
All the library functions are thread safe. The library does not All the library functions are thread safe. The library does not install
install any signal handler. The decoder checks the consistency of the any signal handler. The decoder checks the consistency of the compressed
compressed data, so the library should never crash even in case of data, so the library should never crash even in case of corrupted input.
corrupted input.
In spite of its name (Lempel-Ziv-Markov chain-Algorithm), LZMA is not a
In spite of its name (Lempel-Ziv-Markov chain-Algorithm), LZMA is concrete algorithm; it is more like "any algorithm using the LZMA coding
not a concrete algorithm; it is more like "any algorithm using the LZMA scheme". For example, the option '-0' of lzip uses the scheme in almost the
coding scheme". For example, the option '-0' of lzip uses the scheme in simplest way possible; issuing the longest match it can find, or a literal
almost the simplest way possible; issuing the longest match it can byte if it can't find a match. Inversely, a much more elaborated way of
find, or a literal byte if it can't find a match. Inversely, a much finding coding sequences of minimum size than the one currently used by
more elaborated way of finding coding sequences of minimum size than lzip could be developed, and the resulting sequence could also be coded
the one currently used by lzip could be developed, and the resulting using the LZMA coding scheme.
sequence could also be coded using the LZMA coding scheme.
Lzlib currently implements two variants of the LZMA algorithm; fast Lzlib currently implements two variants of the LZMA algorithm; fast
(used by option '-0' of minilzip) and normal (used by all other (used by option '-0' of minilzip) and normal (used by all other compression
compression levels). levels).
The high compression of LZMA comes from combining two basic, The high compression of LZMA comes from combining two basic, well-proven
well-proven compression ideas: sliding dictionaries (LZ77/78) and compression ideas: sliding dictionaries (LZ77/78) and markov models (the
markov models (the thing used by every compression algorithm that uses thing used by every compression algorithm that uses a range encoder or
a range encoder or similar order-0 entropy coder as its last stage) similar order-0 entropy coder as its last stage) with segregation of
with segregation of contexts according to what the bits are used for. contexts according to what the bits are used for.
The ideas embodied in lzlib are due to (at least) the following The ideas embodied in lzlib are due to (at least) the following people:
people: Abraham Lempel and Jacob Ziv (for the LZ algorithm), Andrey Abraham Lempel and Jacob Ziv (for the LZ algorithm), Andrey Markov (for the
Markov (for the definition of Markov chains), G.N.N. Martin (for the definition of Markov chains), G.N.N. Martin (for the definition of range
definition of range encoding), Igor Pavlov (for putting all the above encoding), Igor Pavlov (for putting all the above together in LZMA), and
together in LZMA), and Julian Seward (for bzip2's CLI). Julian Seward (for bzip2's CLI).
LANGUAGE NOTE: Uncompressed = not compressed = plain data; it may LANGUAGE NOTE: Uncompressed = not compressed = plain data; it may never
never have been compressed. Decompressed is used to refer to data which have been compressed. Decompressed is used to refer to data which have
have undergone the process of decompression. undergone the process of decompression.
File: lzlib.info, Node: Library version, Next: Buffering, Prev: Introduction, Up: Top File: lzlib.info, Node: Library version, Next: Buffering, Prev: Introduction, Up: Top
2 Library version 2 Library version
***************** *****************
-- Function: const char * LZ_version ( void ) -- Function: const char * LZ_version ( void )
Returns the library version as a string. Returns the library version as a string.
-- Constant: const char * LZ_version_string -- Constant: const char * LZ_version_string
This constant is defined in the header file 'lzlib.h'. This constant is defined in the header file 'lzlib.h'.
The application should compare LZ_version and LZ_version_string for The application should compare LZ_version and LZ_version_string for
consistency. If the first character differs, the library code actually consistency. If the first character differs, the library code actually used
used may be incompatible with the 'lzlib.h' header file used by the may be incompatible with the 'lzlib.h' header file used by the application.
application.
if( LZ_version()[0] != LZ_version_string[0] ) if( LZ_version()[0] != LZ_version_string[0] )
error( "bad library version" ); error( "bad library version" );
File: lzlib.info, Node: Buffering, Next: Parameter limits, Prev: Library vers ion, Up: Top File: lzlib.info, Node: Buffering, Next: Parameter limits, Prev: Library vers ion, Up: Top
3 Buffering 3 Buffering
*********** ***********
Lzlib internal functions need access to a memory chunk at least as large Lzlib internal functions need access to a memory chunk at least as large as
as the dictionary size (sliding window). For efficiency reasons, the the dictionary size (sliding window). For efficiency reasons, the input
input buffer for compression is twice or sixteen times as large as the buffer for compression is twice or sixteen times as large as the dictionary
dictionary size. size.
Finally, for safety reasons, lzlib uses two more internal buffers. Finally, for safety reasons, lzlib uses two more internal buffers.
These are the four buffers used by lzlib, and their guaranteed These are the four buffers used by lzlib, and their guaranteed minimum
minimum sizes: sizes:
* Input compression buffer. Written to by the 'LZ_compress_write' * Input compression buffer. Written to by the function
function. For the normal variant of LZMA, its size is two times 'LZ_compress_write'. For the normal variant of LZMA, its size is two
the dictionary size set with the 'LZ_compress_open' function or times the dictionary size set with the function 'LZ_compress_open' or
64 KiB, whichever is larger. For the fast variant, its size is 64 KiB, whichever is larger. For the fast variant, its size is 1 MiB.
1 MiB.
* Output compression buffer. Read from by the function
* Output compression buffer. Read from by the 'LZ_compress_read' 'LZ_compress_read'. Its size is 64 KiB.
function. Its size is 64 KiB.
* Input decompression buffer. Written to by the function
* Input decompression buffer. Written to by the 'LZ_decompress_write'. Its size is 64 KiB.
'LZ_decompress_write' function. Its size is 64 KiB.
* Output decompression buffer. Read from by the function
* Output decompression buffer. Read from by the 'LZ_decompress_read' 'LZ_decompress_read'. Its size is the dictionary size set in the header
function. Its size is the dictionary size set in the header of the of the member currently being decompressed or 64 KiB, whichever is
member currently being decompressed or 64 KiB, whichever is larger. larger.
File: lzlib.info, Node: Parameter limits, Next: Compression functions, Prev: Buffering, Up: Top File: lzlib.info, Node: Parameter limits, Next: Compression functions, Prev: Buffering, Up: Top
4 Parameter limits 4 Parameter limits
****************** ******************
These functions provide minimum and maximum values for some parameters. These functions provide minimum and maximum values for some parameters.
Current values are shown in square brackets. Current values are shown in square brackets.
-- Function: int LZ_min_dictionary_bits ( void ) -- Function: int LZ_min_dictionary_bits ( void )
Returns the base 2 logarithm of the smallest valid dictionary size Returns the base 2 logarithm of the smallest valid dictionary size
[12]. [12].
-- Function: int LZ_min_dictionary_size ( void ) -- Function: int LZ_min_dictionary_size ( void )
Returns the smallest valid dictionary size [4 KiB]. Returns the smallest valid dictionary size [4 KiB].
-- Function: int LZ_max_dictionary_bits ( void ) -- Function: int LZ_max_dictionary_bits ( void )
Returns the base 2 logarithm of the largest valid dictionary size Returns the base 2 logarithm of the largest valid dictionary size [29].
[29].
-- Function: int LZ_max_dictionary_size ( void ) -- Function: int LZ_max_dictionary_size ( void )
Returns the largest valid dictionary size [512 MiB]. Returns the largest valid dictionary size [512 MiB].
-- Function: int LZ_min_match_len_limit ( void ) -- Function: int LZ_min_match_len_limit ( void )
Returns the smallest valid match length limit [5]. Returns the smallest valid match length limit [5].
-- Function: int LZ_max_match_len_limit ( void ) -- Function: int LZ_max_match_len_limit ( void )
Returns the largest valid match length limit [273]. Returns the largest valid match length limit [273].
File: lzlib.info, Node: Compression functions, Next: Decompression functions, Prev: Parameter limits, Up: Top File: lzlib.info, Node: Compression functions, Next: Decompression functions, Prev: Parameter limits, Up: Top
5 Compression functions 5 Compression functions
*********************** ***********************
These are the functions used to compress data. In case of error, all of These are the functions used to compress data. In case of error, all of
them return -1 or 0, for signed and unsigned return values respectively, them return -1 or 0, for signed and unsigned return values respectively,
except 'LZ_compress_open' whose return value must be verified by except 'LZ_compress_open' whose return value must be verified by calling
calling 'LZ_compress_errno' before using it. 'LZ_compress_errno' before using it.
-- Function: struct LZ_Encoder * LZ_compress_open ( const int -- Function: struct LZ_Encoder * LZ_compress_open ( const int
DICTIONARY_SIZE, const int MATCH_LEN_LIMIT, const unsigned DICTIONARY_SIZE, const int MATCH_LEN_LIMIT, const unsigned long
long long MEMBER_SIZE ) long MEMBER_SIZE )
Initializes the internal stream state for compression and returns a Initializes the internal stream state for compression and returns a
pointer that can only be used as the ENCODER argument for the pointer that can only be used as the ENCODER argument for the other
other LZ_compress functions, or a null pointer if the encoder LZ_compress functions, or a null pointer if the encoder could not be
could not be allocated. allocated.
The returned pointer must be verified by calling The returned pointer must be verified by calling 'LZ_compress_errno'
'LZ_compress_errno' before using it. If 'LZ_compress_errno' does before using it. If 'LZ_compress_errno' does not return 'LZ_ok', the
not return 'LZ_ok', the returned pointer must not be used and returned pointer must not be used and should be freed with
should be freed with 'LZ_compress_close' to avoid memory leaks. 'LZ_compress_close' to avoid memory leaks.
DICTIONARY_SIZE sets the dictionary size to be used, in bytes. DICTIONARY_SIZE sets the dictionary size to be used, in bytes. Valid
Valid values range from 4 KiB to 512 MiB. Note that dictionary values range from 4 KiB to 512 MiB. Note that dictionary sizes are
sizes are quantized. If the specified size does not match one of quantized. If the size specified does not match one of the valid
the valid sizes, it will be rounded upwards by adding up to sizes, it will be rounded upwards by adding up to
(DICTIONARY_SIZE / 8) to it. (DICTIONARY_SIZE / 8) to it.
MATCH_LEN_LIMIT sets the match length limit in bytes. Valid values MATCH_LEN_LIMIT sets the match length limit in bytes. Valid values
range from 5 to 273. Larger values usually give better compression range from 5 to 273. Larger values usually give better compression
ratios but longer compression times. ratios but longer compression times.
If DICTIONARY_SIZE is 65535 and MATCH_LEN_LIMIT is 16, the fast If DICTIONARY_SIZE is 65535 and MATCH_LEN_LIMIT is 16, the fast
variant of LZMA is chosen, which produces identical compressed variant of LZMA is chosen, which produces identical compressed output
output as 'lzip -0'. (The dictionary size used will be rounded as 'lzip -0'. (The dictionary size used will be rounded upwards to
upwards to 64 KiB). 64 KiB).
MEMBER_SIZE sets the member size limit in bytes. Valid values MEMBER_SIZE sets the member size limit in bytes. Valid values range
range from 100 kB to 2 PiB. Small member size may degrade from 4 KiB to 2 PiB. A small member size may degrade compression
compression ratio, so use it only when needed. To produce a ratio, so use it only when needed. To produce a single-member data
single-member data stream, give MEMBER_SIZE a value larger than stream, give MEMBER_SIZE a value larger than the amount of data to be
the amount of data to be produced. Values larger than 2 PiB will be produced. Values larger than 2 PiB will be reduced to 2 PiB to prevent
reduced to 2 PiB to prevent the uncompressed size of the member the uncompressed size of the member from overflowing.
from overflowing.
-- Function: int LZ_compress_close ( struct LZ_Encoder * const ENCODER )
-- Function: int LZ_compress_close ( struct LZ_Encoder * const ENCODER Frees all dynamically allocated data structures for this stream. This
) function discards any unprocessed input and does not flush any pending
Frees all dynamically allocated data structures for this stream. output. After a call to 'LZ_compress_close', ENCODER can no longer be
This function discards any unprocessed input and does not flush used as an argument to any LZ_compress function. It is safe to call
any pending output. After a call to 'LZ_compress_close', ENCODER 'LZ_compress_close' with a null argument.
can no longer be used as an argument to any LZ_compress function.
-- Function: int LZ_compress_finish ( struct LZ_Encoder * const -- Function: int LZ_compress_finish ( struct LZ_Encoder * const ENCODER )
ENCODER )
Use this function to tell 'lzlib' that all the data for this member Use this function to tell 'lzlib' that all the data for this member
have already been written (with the 'LZ_compress_write' function). have already been written (with the function 'LZ_compress_write'). It
It is safe to call 'LZ_compress_finish' as many times as needed. is safe to call 'LZ_compress_finish' as many times as needed. After
After all the produced compressed data have been read with all the compressed data have been read with 'LZ_compress_read' and
'LZ_compress_read' and 'LZ_compress_member_finished' returns 1, a 'LZ_compress_member_finished' returns 1, a new member can be started
new member can be started with 'LZ_compress_restart_member'. with 'LZ_compress_restart_member'.
-- Function: int LZ_compress_restart_member ( struct LZ_Encoder * -- Function: int LZ_compress_restart_member ( struct LZ_Encoder * const
const ENCODER, const unsigned long long MEMBER_SIZE ) ENCODER, const unsigned long long MEMBER_SIZE )
Use this function to start a new member in a multimember data Use this function to start a new member in a multimember data stream.
stream. Call this function only after Call this function only after 'LZ_compress_member_finished' indicates
'LZ_compress_member_finished' indicates that the current member that the current member has been fully read (with the function
has been fully read (with the 'LZ_compress_read' function). 'LZ_compress_read'). *Note member_size::, for a description of
MEMBER_SIZE.
-- Function: int LZ_compress_sync_flush ( struct LZ_Encoder * const -- Function: int LZ_compress_sync_flush ( struct LZ_Encoder * const
ENCODER ) ENCODER )
Use this function to make available to 'LZ_compress_read' all the Use this function to make available to 'LZ_compress_read' all the data
data already written with the 'LZ_compress_write' function. First already written with the function 'LZ_compress_write'. First call
call 'LZ_compress_sync_flush'. Then call 'LZ_compress_read' until 'LZ_compress_sync_flush'. Then call 'LZ_compress_read' until it
it returns 0. returns 0.
This function writes a LZMA marker '3' ("Sync Flush" marker) to the
compressed output. Note that the sync flush marker is not allowed in
lzip files; it is a device for interactive communication between
applications using lzlib, but is useless and wasteful in a file, and
is excluded from the media type 'application/lzip'. The LZMA marker
'2' ("End Of Stream" marker) is the only marker allowed in lzip files.
*Note Data format::.
Repeated use of 'LZ_compress_sync_flush' may degrade compression Repeated use of 'LZ_compress_sync_flush' may degrade compression
ratio, so use it only when needed. ratio, so use it only when needed. If the interval between calls to
'LZ_compress_sync_flush' is large (comparable to dictionary size),
creating a multimember data stream with 'LZ_compress_restart_member'
may be an alternative.
Combining multimember stream creation with flushing may be tricky. If
there are more bytes available than those needed to complete
MEMBER_SIZE, 'LZ_compress_restart_member' needs to be called when
'LZ_compress_member_finished' returns 1, followed by a new call to
'LZ_compress_sync_flush'.
-- Function: int LZ_compress_read ( struct LZ_Encoder * const ENCODER, -- Function: int LZ_compress_read ( struct LZ_Encoder * const ENCODER,
uint8_t * const BUFFER, const int SIZE ) uint8_t * const BUFFER, const int SIZE )
The 'LZ_compress_read' function reads up to SIZE bytes from the The function 'LZ_compress_read' reads up to SIZE bytes from the stream
stream pointed to by ENCODER, storing the results in BUFFER. pointed to by ENCODER, storing the results in BUFFER.
The return value is the number of bytes actually read. This might be
less than SIZE; for example, if there aren't that many bytes left in
the stream or if more bytes have to be yet written with the function
'LZ_compress_write'. Note that reading less than SIZE bytes is not an
error.
The return value is the number of bytes actually read. This might -- Function: int LZ_compress_write ( struct LZ_Encoder * const ENCODER,
be less than SIZE; for example, if there aren't that many bytes uint8_t * const BUFFER, const int SIZE )
left in the stream or if more bytes have to be yet written with the The function 'LZ_compress_write' writes up to SIZE bytes from BUFFER
'LZ_compress_write' function. Note that reading less than SIZE to the stream pointed to by ENCODER.
bytes is not an error.
The return value is the number of bytes actually written. This might be
-- Function: int LZ_compress_write ( struct LZ_Encoder * const less than SIZE. Note that writing less than SIZE bytes is not an error.
ENCODER, uint8_t * const BUFFER, const int SIZE )
The 'LZ_compress_write' function writes up to SIZE bytes from
BUFFER to the stream pointed to by ENCODER.
The return value is the number of bytes actually written. This
might be less than SIZE. Note that writing less than SIZE bytes is
not an error.
-- Function: int LZ_compress_write_size ( struct LZ_Encoder * const -- Function: int LZ_compress_write_size ( struct LZ_Encoder * const
ENCODER ) ENCODER )
The 'LZ_compress_write_size' function returns the maximum number of The function 'LZ_compress_write_size' returns the maximum number of
bytes that can be immediately written through the bytes that can be immediately written through 'LZ_compress_write'. For
'LZ_compress_write' function. efficiency reasons, once the input buffer is full and
'LZ_compress_write_size' returns 0, almost all the buffer must be
compressed before a size greater than 0 is returned again. (This is
done to minimize the amount of data that must be copied to the
beginning of the buffer before new data can be accepted).
It is guaranteed that an immediate call to 'LZ_compress_write' will It is guaranteed that an immediate call to 'LZ_compress_write' will
accept a SIZE up to the returned number of bytes. accept a SIZE up to the returned number of bytes.
-- Function: enum LZ_Errno LZ_compress_errno ( struct LZ_Encoder * -- Function: enum LZ_Errno LZ_compress_errno ( struct LZ_Encoder * const
const ENCODER ) ENCODER )
Returns the current error code for ENCODER. *Note Error codes::. Returns the current error code for ENCODER. *Note Error codes::. It is
safe to call 'LZ_compress_errno' with a null argument, in which case
it returns 'LZ_bad_argument'.
-- Function: int LZ_compress_finished ( struct LZ_Encoder * const 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_finished ( struct LZ_Encoder * const -- Function: int LZ_compress_member_finished ( struct LZ_Encoder * const
ENCODER ) ENCODER )
Returns 1 if all the data have been read and 'LZ_compress_close' Returns 1 if the current member, in a multimember data stream, has been
can be safely called. Otherwise it returns 0. fully read and 'LZ_compress_restart_member' can be safely called.
'LZ_compress_finished' implies 'LZ_compress_member_finished'. Otherwise it returns 0.
-- Function: int LZ_compress_member_finished ( struct LZ_Encoder *
const ENCODER )
Returns 1 if the current member, in a multimember data stream, has
been fully read and 'LZ_compress_restart_member' can be safely
called. Otherwise it returns 0.
-- Function: unsigned long long LZ_compress_data_position ( struct -- Function: unsigned long long LZ_compress_data_position ( struct
LZ_Encoder * const ENCODER ) LZ_Encoder * const ENCODER )
Returns the number of input bytes already compressed in the current Returns the number of input bytes already compressed in the current
member. member.
-- Function: unsigned long long LZ_compress_member_position ( struct -- Function: unsigned long long LZ_compress_member_position ( struct
LZ_Encoder * const ENCODER ) LZ_Encoder * const ENCODER )
Returns the number of compressed bytes already produced, but Returns the number of compressed bytes already produced, but perhaps
perhaps not yet read, in the current member. not yet read, in the current member.
-- Function: unsigned long long LZ_compress_total_in_size ( struct -- Function: unsigned long long LZ_compress_total_in_size ( struct
LZ_Encoder * const ENCODER ) LZ_Encoder * const ENCODER )
Returns the total number of input bytes already compressed. Returns the total number of input bytes already compressed.
-- Function: unsigned long long LZ_compress_total_out_size ( struct -- Function: unsigned long long LZ_compress_total_out_size ( struct
LZ_Encoder * const ENCODER ) LZ_Encoder * const ENCODER )
Returns the total number of compressed bytes already produced, but Returns the total number of compressed bytes already produced, but
perhaps not yet read. perhaps not yet read.
File: lzlib.info, Node: Decompression functions, Next: Error codes, Prev: Com pression functions, Up: Top File: lzlib.info, Node: Decompression functions, Next: Error codes, Prev: Com pression functions, Up: Top
6 Decompression functions 6 Decompression functions
************************* *************************
These are the functions used to decompress data. In case of error, all These are the functions used to decompress data. In case of error, all of
of them return -1 or 0, for signed and unsigned return values them return -1 or 0, for signed and unsigned return values respectively,
respectively, except 'LZ_decompress_open' whose return value must be except 'LZ_decompress_open' whose return value must be verified by calling
verified by calling 'LZ_decompress_errno' before using it. 'LZ_decompress_errno' before using it.
-- Function: struct LZ_Decoder * LZ_decompress_open ( void ) -- Function: struct LZ_Decoder * LZ_decompress_open ( void )
Initializes the internal stream state for decompression and Initializes the internal stream state for decompression and returns a
returns a pointer that can only be used as the DECODER argument pointer that can only be used as the DECODER argument for the other
for the other LZ_decompress functions, or a null pointer if the LZ_decompress functions, or a null pointer if the decoder could not be
decoder could not be allocated. allocated.
The returned pointer must be verified by calling The returned pointer must be verified by calling 'LZ_decompress_errno'
'LZ_decompress_errno' before using it. If 'LZ_decompress_errno' before using it. If 'LZ_decompress_errno' does not return 'LZ_ok', the
does not return 'LZ_ok', the returned pointer must not be used and returned pointer must not be used and should be freed with
should be freed with 'LZ_decompress_close' to avoid memory leaks. 'LZ_decompress_close' to avoid memory leaks.
-- Function: int LZ_decompress_close ( struct LZ_Decoder * const -- Function: int LZ_decompress_close ( struct LZ_Decoder * const DECODER )
DECODER ) Frees all dynamically allocated data structures for this stream. This
Frees all dynamically allocated data structures for this stream. function discards any unprocessed input and does not flush any pending
This function discards any unprocessed input and does not flush output. After a call to 'LZ_decompress_close', DECODER can no longer
any pending output. After a call to 'LZ_decompress_close', DECODER be used as an argument to any LZ_decompress function. It is safe to
can no longer be used as an argument to any LZ_decompress function. call 'LZ_decompress_close' with a null argument.
-- Function: int LZ_decompress_finish ( struct LZ_Decoder * const -- Function: int LZ_decompress_finish ( struct LZ_Decoder * const DECODER )
DECODER )
Use this function to tell 'lzlib' that all the data for this stream Use this function to tell 'lzlib' that all the data for this stream
have already been written (with the 'LZ_decompress_write' have already been written (with the function 'LZ_decompress_write').
function). It is safe to call 'LZ_decompress_finish' as many It is safe to call 'LZ_decompress_finish' as many times as needed. It
times as needed. is not required to call 'LZ_decompress_finish' if the input stream
only contains whole members, but not calling it prevents lzlib from
detecting a truncated member.
-- Function: int LZ_decompress_reset ( struct LZ_Decoder * const DECODER )
Resets the internal state of DECODER as it was just after opening it
with the function 'LZ_decompress_open'. Data stored in the internal
buffers is discarded. Position counters are set to 0.
-- Function: int LZ_decompress_reset ( struct LZ_Decoder * const -- Function: int LZ_decompress_sync_to_member ( struct LZ_Decoder * const
DECODER ) DECODER )
Resets the internal state of DECODER as it was just after opening Resets the error state of DECODER and enters a search state that lasts
it with the 'LZ_decompress_open' function. Data stored in the until a new member header (or the end of the stream) is found. After a
internal buffers is discarded. Position counters are set to 0. successful call to 'LZ_decompress_sync_to_member', data written with
'LZ_decompress_write' will be consumed and 'LZ_decompress_read' will
-- Function: int LZ_decompress_sync_to_member ( struct LZ_Decoder * return 0 until a header is found.
const DECODER )
Resets the error state of DECODER and enters a search state that This function is useful to discard any data preceding the first member,
lasts until a new member header (or the end of the stream) is or to discard the rest of the current member, for example in case of a
found. After a successful call to 'LZ_decompress_sync_to_member', data error. If the decoder is already at the beginning of a member,
data written with 'LZ_decompress_write' will be consumed and this function does nothing.
'LZ_decompress_read' will return 0 until a header is found.
-- Function: int LZ_decompress_read ( struct LZ_Decoder * const DECODER,
This function is useful to discard any data preceding the first uint8_t * const BUFFER, const int SIZE )
member, or to discard the rest of the current member, for example The function 'LZ_decompress_read' reads up to SIZE bytes from the
in case of a data error. If the decoder is already at the
beginning of a member, this function does nothing.
-- Function: int LZ_decompress_read ( struct LZ_Decoder * const
DECODER, uint8_t * const BUFFER, const int SIZE )
The 'LZ_decompress_read' function reads up to SIZE bytes from the
stream pointed to by DECODER, storing the results in BUFFER. stream pointed to by DECODER, storing the results in BUFFER.
The return value is the number of bytes actually read. This might The return value is the number of bytes actually read. This might be
be less than SIZE; for example, if there aren't that many bytes less than SIZE; for example, if there aren't that many bytes left in
left in the stream or if more bytes have to be yet written with the the stream or if more bytes have to be yet written with the function
'LZ_decompress_write' function. Note that reading less than SIZE 'LZ_decompress_write'. Note that reading less than SIZE bytes is not
bytes is not an error. an error.
'LZ_decompress_read' returns at least once per member so that
'LZ_decompress_member_finished' can be called (and trailer data
retrieved) for each member, even for empty members. Therefore,
'LZ_decompress_read' returning 0 does not mean that the end of the
stream has been reached. The increase in the value returned by
'LZ_decompress_total_in_size' can be used to tell the end of the stream
from an empty member.
In case of decompression error caused by corrupt or truncated data, In case of decompression error caused by corrupt or truncated data,
'LZ_decompress_read' does not signal the error immediately to the 'LZ_decompress_read' does not signal the error immediately to the
application, but waits until all decoded bytes have been read. This application, but waits until all the bytes decoded have been read. This
allows tools like tarlz to recover as much data as possible from allows tools like tarlz to recover as much data as possible from each
each damaged member. *Note tarlz manual: (tarlz)Top. damaged member. *Note tarlz manual: (tarlz)Top.
-- Function: int LZ_decompress_write ( struct LZ_Decoder * const -- Function: int LZ_decompress_write ( struct LZ_Decoder * const DECODER,
DECODER, uint8_t * const BUFFER, const int SIZE ) uint8_t * const BUFFER, const int SIZE )
The 'LZ_decompress_write' function writes up to SIZE bytes from The function 'LZ_decompress_write' writes up to SIZE bytes from BUFFER
BUFFER to the stream pointed to by DECODER. to the stream pointed to by DECODER.
The return value is the number of bytes actually written. This The return value is the number of bytes actually written. This might be
might be less than SIZE. Note that writing less than SIZE bytes is less than SIZE. Note that writing less than SIZE bytes is not an error.
not an error.
-- Function: int LZ_decompress_write_size ( struct LZ_Decoder * const -- Function: int LZ_decompress_write_size ( struct LZ_Decoder * const
DECODER ) DECODER )
The 'LZ_decompress_write_size' function returns the maximum number The function 'LZ_decompress_write_size' returns the maximum number of
of bytes that can be immediately written through the bytes that can be immediately written through 'LZ_decompress_write'.
'LZ_decompress_write' function. This number varies smoothly; each compressed byte consumed may be
overwritten immediately, increasing by 1 the value returned.
It is guaranteed that an immediate call to 'LZ_decompress_write'
will accept a SIZE up to the returned number of bytes. It is guaranteed that an immediate call to 'LZ_decompress_write' will
accept a SIZE up to the returned number of bytes.
-- Function: enum LZ_Errno LZ_decompress_errno ( struct LZ_Decoder *
const DECODER ) -- Function: enum LZ_Errno LZ_decompress_errno ( struct LZ_Decoder * const
Returns the current error code for DECODER. *Note Error codes::. DECODER )
Returns the current error code for DECODER. *Note Error codes::. It is
safe to call 'LZ_decompress_errno' with a null argument, in which case
it returns 'LZ_bad_argument'.
-- Function: int LZ_decompress_finished ( struct LZ_Decoder * const -- Function: int LZ_decompress_finished ( struct LZ_Decoder * const
DECODER ) DECODER )
Returns 1 if all the data have been read and 'LZ_decompress_close' Returns 1 if all the data have been read and 'LZ_decompress_close' can
can be safely called. Otherwise it returns 0. be safely called. Otherwise it returns 0. 'LZ_decompress_finished'
does not imply 'LZ_decompress_member_finished'.
-- Function: int LZ_decompress_member_finished ( struct LZ_Decoder * -- Function: int LZ_decompress_member_finished ( struct LZ_Decoder * const
const DECODER ) DECODER )
Returns 1 if the previous call to 'LZ_decompress_read' finished Returns 1 if the previous call to 'LZ_decompress_read' finished reading
reading the current member, indicating that final values for the current member, indicating that final values for member are
member are available through 'LZ_decompress_data_crc', available through 'LZ_decompress_data_crc',
'LZ_decompress_data_position', and 'LZ_decompress_data_position', and 'LZ_decompress_member_position'.
'LZ_decompress_member_position'. Otherwise it returns 0. Otherwise it returns 0.
-- Function: int LZ_decompress_member_version ( struct LZ_Decoder * -- Function: int LZ_decompress_member_version ( struct LZ_Decoder * const
const DECODER ) DECODER )
Returns the version of current member from member header. Returns the version of current member from member header.
-- Function: int LZ_decompress_dictionary_size ( struct LZ_Decoder * -- Function: int LZ_decompress_dictionary_size ( struct LZ_Decoder * const
const DECODER ) DECODER )
Returns the dictionary size of current member from member header. Returns the dictionary size of the current member, read from the member
header.
-- Function: unsigned LZ_decompress_data_crc ( struct LZ_Decoder *
const DECODER ) -- Function: unsigned LZ_decompress_data_crc ( struct LZ_Decoder * const
Returns the 32 bit Cyclic Redundancy Check of the data DECODER )
decompressed from the current member. The returned value is valid Returns the 32 bit Cyclic Redundancy Check of the data decompressed
only when 'LZ_decompress_member_finished' returns 1. from the current member. The returned value is valid only when
'LZ_decompress_member_finished' returns 1.
-- Function: unsigned long long LZ_decompress_data_position ( struct -- Function: unsigned long long LZ_decompress_data_position ( struct
LZ_Decoder * const DECODER ) LZ_Decoder * const DECODER )
Returns the number of decompressed bytes already produced, but Returns the number of decompressed bytes already produced, but perhaps
perhaps not yet read, in the current member. not yet read, in the current member.
-- Function: unsigned long long LZ_decompress_member_position ( struct -- Function: unsigned long long LZ_decompress_member_position ( struct
LZ_Decoder * const DECODER ) LZ_Decoder * const DECODER )
Returns the number of input bytes already decompressed in the Returns the number of input bytes already decompressed in the current
current member. member.
-- Function: unsigned long long LZ_decompress_total_in_size ( struct -- Function: unsigned long long LZ_decompress_total_in_size ( struct
LZ_Decoder * const DECODER ) LZ_Decoder * const DECODER )
Returns the total number of input bytes already decompressed. Returns the total number of input bytes already decompressed.
-- Function: unsigned long long LZ_decompress_total_out_size ( struct -- Function: unsigned long long LZ_decompress_total_out_size ( struct
LZ_Decoder * const DECODER ) LZ_Decoder * const DECODER )
Returns the total number of decompressed bytes already produced, Returns the total number of decompressed bytes already produced, but
but perhaps not yet read. perhaps not yet read.
File: lzlib.info, Node: Error codes, Next: Error messages, Prev: Decompressio n functions, Up: Top File: lzlib.info, Node: Error codes, Next: Error messages, Prev: Decompressio n functions, Up: Top
7 Error codes 7 Error codes
************* *************
Most library functions return -1 to indicate that they have failed. But Most library functions return -1 to indicate that they have failed. But
this return value only tells you that an error has occurred. To find out this return value only tells you that an error has occurred. To find out
what kind of error it was, you need to verify the error code by calling what kind of error it was, you need to verify the error code by calling
'LZ_(de)compress_errno'. 'LZ_(de)compress_errno'.
Library functions don't change the value returned by Library functions don't change the value returned by
'LZ_(de)compress_errno' when they succeed; thus, the value returned by 'LZ_(de)compress_errno' when they succeed; thus, the value returned by
'LZ_(de)compress_errno' after a successful call is not necessarily 'LZ_(de)compress_errno' after a successful call is not necessarily LZ_ok,
LZ_ok, and you should not use 'LZ_(de)compress_errno' to determine and you should not use 'LZ_(de)compress_errno' to determine whether a call
whether a call failed. If the call failed, then you can examine failed. If the call failed, then you can examine 'LZ_(de)compress_errno'.
'LZ_(de)compress_errno'.
The error codes are defined in the header file 'lzlib.h'. The error codes are defined in the header file 'lzlib.h'.
-- Constant: enum LZ_Errno LZ_ok -- Constant: enum LZ_Errno LZ_ok
The value of this constant is 0 and is used to indicate that there The value of this constant is 0 and is used to indicate that there is
is no error. no error.
-- Constant: enum LZ_Errno LZ_bad_argument -- Constant: enum LZ_Errno LZ_bad_argument
At least one of the arguments passed to the library function was At least one of the arguments passed to the library function was
invalid. invalid.
-- Constant: enum LZ_Errno LZ_mem_error -- Constant: enum LZ_Errno LZ_mem_error
No memory available. The system cannot allocate more virtual memory No memory available. The system cannot allocate more virtual memory
because its capacity is full. because its capacity is full.
-- Constant: enum LZ_Errno LZ_sequence_error -- Constant: enum LZ_Errno LZ_sequence_error
A library function was called in the wrong order. For example A library function was called in the wrong order. For example
'LZ_compress_restart_member' was called before 'LZ_compress_restart_member' was called before
'LZ_compress_member_finished' indicates that the current member is 'LZ_compress_member_finished' indicates that the current member is
finished. finished.
-- Constant: enum LZ_Errno LZ_header_error -- Constant: enum LZ_Errno LZ_header_error
An invalid member header (one with the wrong magic bytes) was An invalid member header (one with the wrong magic bytes) was read. If
read. If this happens at the end of the data stream it may this happens at the end of the data stream it may indicate trailing
indicate trailing data. data.
-- Constant: enum LZ_Errno LZ_unexpected_eof -- Constant: enum LZ_Errno LZ_unexpected_eof
The end of the data stream was reached in the middle of a member. The end of the data stream was reached in the middle of a member.
-- Constant: enum LZ_Errno LZ_data_error -- Constant: enum LZ_Errno LZ_data_error
The data stream is corrupt. If 'LZ_decompress_member_position' is 6 The data stream is corrupt. If 'LZ_decompress_member_position' is 6 or
or less, it indicates either a format version not supported, an less, it indicates either a format version not supported, an invalid
invalid dictionary size, a corrupt header in a multimember data dictionary size, a corrupt header in a multimember data stream, or
stream, or trailing data too similar to a valid lzip header. trailing data too similar to a valid lzip header. Lziprecover can be
Lziprecover can be used to remove conflicting trailing data from a used to remove conflicting trailing data from a file.
file.
-- Constant: enum LZ_Errno LZ_library_error -- Constant: enum LZ_Errno LZ_library_error
A bug was detected in the library. Please, report it. *Note A bug was detected in the library. Please, report it. *Note Problems::.
Problems::.
File: lzlib.info, Node: Error messages, Next: Invoking minilzip, Prev: Error codes, Up: Top File: lzlib.info, Node: Error messages, Next: Invoking minilzip, Prev: Error codes, Up: Top
8 Error messages 8 Error messages
**************** ****************
-- Function: const char * LZ_strerror ( const enum LZ_Errno LZ_ERRNO ) -- Function: const char * LZ_strerror ( const enum LZ_Errno LZ_ERRNO )
Returns the standard error message for a given error code. The Returns the standard error message for a given error code. The messages
messages are fairly short; there are no multi-line messages or are fairly short; there are no multi-line messages or embedded
embedded newlines. This function makes it easy for your program newlines. This function makes it easy for your program to report
to report informative error messages about the failure of a informative error messages about the failure of a library call.
library call.
The value of LZ_ERRNO normally comes from a call to The value of LZ_ERRNO normally comes from a call to
'LZ_(de)compress_errno'. 'LZ_(de)compress_errno'.
File: lzlib.info, Node: Invoking minilzip, Next: Data format, Prev: Error mes sages, Up: Top File: lzlib.info, Node: Invoking minilzip, Next: Data format, Prev: Error mes sages, Up: Top
9 Invoking minilzip 9 Invoking minilzip
******************* *******************
Minilzip is a test program for the lzlib compression library, fully Minilzip is a test program for the compression library lzlib, fully
compatible with lzip 1.4 or newer. compatible with lzip 1.4 or newer.
Lzip is a lossless data compressor with a user interface similar to the
one of gzip or bzip2. Lzip uses a simplified form of the 'Lempel-Ziv-Markov
chain-Algorithm' (LZMA) stream format, chosen to maximize safety and
interoperability. Lzip can compress about as fast as gzip (lzip -0) or
compress most files more than bzip2 (lzip -9). Decompression speed is
intermediate between gzip and bzip2. Lzip is better than gzip and bzip2
from a data recovery perspective. Lzip has been designed, written, and
tested with great care to replace gzip and bzip2 as the standard
general-purpose compressed format for unix-like systems.
The format for running minilzip is: The format for running minilzip is:
minilzip [OPTIONS] [FILES] minilzip [OPTIONS] [FILES]
'-' used as a FILE argument means standard input. It can be mixed with If no file names are specified, minilzip compresses (or decompresses) from
other FILES and is read just once, the first time it appears in the standard input to standard output. A hyphen '-' used as a FILE argument
command line. 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: minilzip supports the following options: *Note Argument syntax:
(arg_parser)Argument syntax.
'-h' '-h'
'--help' '--help'
Print an informative help message describing the options and exit. Print an informative help message describing the options and exit.
'-V' '-V'
'--version' '--version'
Print the version number of minilzip on the standard output and Print the version number of minilzip on the standard output and exit.
exit. This version number should be included in all bug reports. This version number should be included in all bug reports.
'-a' '-a'
'--trailing-error' '--trailing-error'
Exit with error status 2 if any remaining input is detected after Exit with error status 2 if any remaining input is detected after
decompressing the last member. Such remaining input is usually decompressing the last member. Such remaining input is usually trailing
trailing garbage that can be safely ignored. garbage that can be safely ignored.
'-b BYTES' '-b BYTES'
'--member-size=BYTES' '--member-size=BYTES'
When compressing, set the member size limit to BYTES. A small When compressing, set the member size limit to BYTES. It is advisable
member size may degrade compression ratio, so use it only when to keep members smaller than RAM size so that they can be repaired with
needed. Valid values range from 100 kB to 2 PiB. Defaults to lziprecover in case of corruption. A small member size may degrade
2 PiB. compression ratio, so use it only when needed. Valid values range from
100 kB to 2 PiB. Defaults to 2 PiB.
'-c' '-c'
'--stdout' '--stdout'
Compress or decompress to standard output; keep input files Compress or decompress to standard output; keep input files unchanged.
unchanged. If compressing several files, each file is compressed If compressing several files, each file is compressed independently.
independently. This option is needed when reading from a named (The output consists of a sequence of independently compressed
pipe (fifo) or from a device. Use it also to recover as much of members). This option (or '-o') is needed when reading from a named
the decompressed data as possible when decompressing a corrupt pipe (fifo) or from a device. Use it also to recover as much of the
file. decompressed data as possible when decompressing a corrupt file. '-c'
overrides '-o' and '-S'. '-c' has no effect when testing or listing.
'-d' '-d'
'--decompress' '--decompress'
Decompress the specified files. If a file does not exist or can't Decompress the files specified. If a file does not exist or can't be
be opened, minilzip continues decompressing the rest of the files. opened, minilzip continues decompressing the rest of the files. If a
If a file fails to decompress, or is a terminal, minilzip exits file fails to decompress, or is a terminal, minilzip exits immediately
immediately without decompressing the rest of the files. without decompressing the rest of the files.
'-f' '-f'
'--force' '--force'
Force overwrite of output files. Force overwrite of output files.
'-F' '-F'
'--recompress' '--recompress'
When compressing, force re-compression of files whose name already When compressing, force re-compression of files whose name already has
has the '.lz' or '.tlz' suffix. the '.lz' or '.tlz' suffix.
'-k' '-k'
'--keep' '--keep'
Keep (don't delete) input files during compression or Keep (don't delete) input files during compression or decompression.
decompression.
'-m BYTES' '-m BYTES'
'--match-length=BYTES' '--match-length=BYTES'
When compressing, set the match length limit in bytes. After a When compressing, set the match length limit in bytes. After a match
match this long is found, the search is finished. Valid values this long is found, the search is finished. Valid values range from 5
range from 5 to 273. Larger values usually give better compression to 273. Larger values usually give better compression ratios but longer
ratios but longer compression times. compression times.
'-o FILE' '-o FILE'
'--output=FILE' '--output=FILE'
When reading from standard input and '--stdout' has not been If '-c' has not been also specified, write the (de)compressed output to
specified, use 'FILE' as the virtual name of the uncompressed 'FILE'; keep input files unchanged. If compressing several files, each
file. This produces a file named 'FILE' when decompressing, or a file is compressed independently. (The output consists of a sequence of
file named 'FILE.lz' when compressing. A second '.lz' extension is independently compressed members). This option (or '-c') is needed when
not added if 'FILE' already ends in '.lz' or '.tlz'. When reading from a named pipe (fifo) or from a device. '-o -' is equivalent
compressing and splitting the output in volumes, several files to '-c'. '-o' has no effect when testing or listing.
named 'FILE00001.lz', 'FILE00002.lz', etc, are created.
When compressing and splitting the output in volumes, 'FILE' is used
as a prefix, and several files named 'FILE00001.lz', 'FILE00002.lz',
etc, are created. In this case, only one input file is allowed.
'-q' '-q'
'--quiet' '--quiet'
Quiet operation. Suppress all messages. Quiet operation. Suppress all messages.
'-s BYTES' '-s BYTES'
'--dictionary-size=BYTES' '--dictionary-size=BYTES'
When compressing, set the dictionary size limit in bytes. Minilzip When compressing, set the dictionary size limit in bytes. Minilzip
will use for each file the largest dictionary size that does not will use for each file the largest dictionary size that does not
exceed neither the file size nor this limit. Valid values range exceed neither the file size nor this limit. Valid values range from
from 4 KiB to 512 MiB. Values 12 to 29 are interpreted as powers 4 KiB to 512 MiB. Values 12 to 29 are interpreted as powers of two,
of two, meaning 2^12 to 2^29 bytes. Dictionary sizes are quantized meaning 2^12 to 2^29 bytes. Dictionary sizes are quantized so that
so that they can be coded in just one byte (*note they can be coded in just one byte (*note coded-dict-size::). If the
coded-dict-size::). If the specified size does not match one of size specified does not match one of the valid sizes, it will be
the valid sizes, it will be rounded upwards by adding up to rounded upwards by adding up to (BYTES / 8) to it.
(BYTES / 8) to it.
For maximum compression you should use a dictionary size limit as large
For maximum compression you should use a dictionary size limit as as possible, but keep in mind that the decompression memory requirement
large as possible, but keep in mind that the decompression memory is affected at compression time by the choice of dictionary size limit.
requirement is affected at compression time by the choice of
dictionary size limit.
'-S BYTES' '-S BYTES'
'--volume-size=BYTES' '--volume-size=BYTES'
When compressing, split the compressed output into several volume When compressing, and '-c' has not been also specified, split the
files with names 'original_name00001.lz', 'original_name00002.lz', compressed output into several volume files with names
etc, and set the volume size limit to BYTES. Input files are kept 'original_name00001.lz', 'original_name00002.lz', etc, and set the
unchanged. Each volume is a complete, maybe multimember, lzip volume size limit to BYTES. Input files are kept unchanged. Each
file. A small volume size may degrade compression ratio, so use it volume is a complete, maybe multimember, lzip file. A small volume
only when needed. Valid values range from 100 kB to 4 EiB. size may degrade compression ratio, so use it only when needed. Valid
values range from 100 kB to 4 EiB.
'-t' '-t'
'--test' '--test'
Check integrity of the specified files, but don't decompress them. Check integrity of the files specified, but don't decompress them. This
This really performs a trial decompression and throws away the really performs a trial decompression and throws away the result. Use
result. Use it together with '-v' to see information about the it together with '-v' to see information about the files. If a file
files. If a file fails the test, does not exist, can't be opened, fails the test, does not exist, can't be opened, or is a terminal,
or is a terminal, minilzip continues checking the rest of the minilzip continues checking the rest of the files. A final diagnostic
files. A final diagnostic is shown at verbosity level 1 or higher is shown at verbosity level 1 or higher if any file fails the test
if any file fails the test when testing multiple files. when testing multiple files.
'-v' '-v'
'--verbose' '--verbose'
Verbose mode. Verbose mode.
When compressing, show the compression ratio and size for each file When compressing, show the compression ratio and size for each file
processed. processed.
When decompressing or testing, further -v's (up to 4) increase the When decompressing or testing, further -v's (up to 4) increase the
verbosity level, showing status, compression ratio, dictionary verbosity level, showing status, compression ratio, dictionary size,
size, and trailer contents (CRC, data size, member size). and trailer contents (CRC, data size, member size).
'-0 .. -9' '-0 .. -9'
Compression level. Set the compression parameters (dictionary size Compression level. Set the compression parameters (dictionary size and
and match length limit) as shown in the table below. The default match length limit) as shown in the table below. The default
compression level is '-6', equivalent to '-s8MiB -m36'. Note that compression level is '-6', equivalent to '-s8MiB -m36'. Note that '-9'
'-9' can be much slower than '-0'. These options have no effect can be much slower than '-0'. These options have no effect when
when decompressing or testing. decompressing or testing.
The bidimensional parameter space of LZMA can't be mapped to a The bidimensional parameter space of LZMA can't be mapped to a linear
linear scale optimal for all files. If your files are large, very scale optimal for all files. If your files are large, very repetitive,
repetitive, etc, you may need to use the '--dictionary-size' and etc, you may need to use the options '--dictionary-size' and
'--match-length' options directly to achieve optimal performance. '--match-length' directly to achieve optimal performance.
If several compression levels or '-s' or '-m' options are given, If several compression levels or '-s' or '-m' options are given, the
the last setting is used. For example '-9 -s64MiB' is equivalent last setting is used. For example '-9 -s64MiB' is equivalent to
to '-s64MiB -m273' '-s64MiB -m273'
Level Dictionary size (-s) Match length limit (-m) Level Dictionary size (-s) Match length limit (-m)
-0 64 KiB 16 bytes -0 64 KiB 16 bytes
-1 1 MiB 5 bytes -1 1 MiB 5 bytes
-2 1.5 MiB 6 bytes -2 1.5 MiB 6 bytes
-3 2 MiB 8 bytes -3 2 MiB 8 bytes
-4 3 MiB 12 bytes -4 3 MiB 12 bytes
-5 4 MiB 20 bytes -5 4 MiB 20 bytes
-6 8 MiB 36 bytes -6 8 MiB 36 bytes
-7 16 MiB 68 bytes -7 16 MiB 68 bytes
-8 24 MiB 132 bytes -8 24 MiB 132 bytes
-9 32 MiB 273 bytes -9 32 MiB 273 bytes
'--fast' '--fast'
'--best' '--best'
Aliases for GNU gzip compatibility. Aliases for GNU gzip compatibility.
'--loose-trailing' '--loose-trailing'
When decompressing or testing, allow trailing data whose first When decompressing or testing, allow trailing data whose first bytes
bytes are so similar to the magic bytes of a lzip header that they are so similar to the magic bytes of a lzip header that they can be
can be confused with a corrupt header. Use this option if a file confused with a corrupt header. Use this option if a file triggers a
triggers a "corrupt header" error and the cause is not indeed a "corrupt header" error and the cause is not indeed a corrupt header.
corrupt header.
Numbers given as arguments to options may be followed by a multiplier 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): Table of SI and binary prefixes (unit multipliers):
Prefix Value | Prefix Value Prefix Value | Prefix Value
k kilobyte (10^3 = 1000) | Ki kibibyte (2^10 = 1024) k kilobyte (10^3 = 1000) | Ki kibibyte (2^10 = 1024)
M megabyte (10^6) | Mi mebibyte (2^20) M megabyte (10^6) | Mi mebibyte (2^20)
G gigabyte (10^9) | Gi gibibyte (2^30) G gigabyte (10^9) | Gi gibibyte (2^30)
T terabyte (10^12) | Ti tebibyte (2^40) T terabyte (10^12) | Ti tebibyte (2^40)
P petabyte (10^15) | Pi pebibyte (2^50) P petabyte (10^15) | Pi pebibyte (2^50)
E exabyte (10^18) | Ei exbibyte (2^60) E exabyte (10^18) | Ei exbibyte (2^60)
Z zettabyte (10^21) | Zi zebibyte (2^70) Z zettabyte (10^21) | Zi zebibyte (2^70)
Y yottabyte (10^24) | Yi yobibyte (2^80) Y yottabyte (10^24) | Yi yobibyte (2^80)
Exit status: 0 for a normal exit, 1 for environmental problems (file Exit status: 0 for a normal exit, 1 for environmental problems (file not
not found, invalid flags, I/O errors, etc), 2 to indicate a corrupt or found, invalid flags, I/O errors, etc), 2 to indicate a corrupt or invalid
invalid input file, 3 for an internal consistency error (eg, bug) which input file, 3 for an internal consistency error (eg, bug) which caused
caused minilzip to panic. minilzip to panic.
File: lzlib.info, Node: Data format, Next: Examples, Prev: Invoking minilzip, Up: Top File: lzlib.info, Node: Data format, Next: Examples, Prev: Invoking minilzip, Up: Top
10 Data format 10 Data format
************** **************
Perfection is reached, not when there is no longer anything to add, but Perfection is reached, not when there is no longer anything to add, but
when there is no longer anything to take away. when there is no longer anything to take away.
-- Antoine de Saint-Exupery -- Antoine de Saint-Exupery
In the diagram below, a box like this: In the diagram below, a box like this:
+---+ +---+
| | <-- the vertical bars might be missing | | <-- the vertical bars might be missing
+---+ +---+
represents one byte; a box like this: represents one byte; a box like this:
+==============+ +==============+
| | | |
+==============+ +==============+
represents a variable number of bytes. represents a variable number of bytes.
A lzip data stream consists of a series of "members" (compressed A lzip data stream consists of a series of "members" (compressed data
data sets). The members simply appear one after another in the data sets). The members simply appear one after another in the data stream, with
stream, with no additional information before, between, or after them. no additional information before, between, or after them.
Each member has the following structure: Each member has the following structure:
+--+--+--+--+----+----+=============+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +--+--+--+--+----+----+=============+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| ID string | VN | DS | LZMA stream | CRC32 | Data size | Member size | | ID string | VN | DS | LZMA stream | CRC32 | Data size | Member size |
+--+--+--+--+----+----+=============+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +--+--+--+--+----+----+=============+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
All multibyte values are stored in little endian order. All multibyte values are stored in little endian order.
'ID string (the "magic" bytes)' 'ID string (the "magic" bytes)'
A four byte string, identifying the lzip format, with the value A four byte string, identifying the lzip format, with the value "LZIP"
"LZIP" (0x4C, 0x5A, 0x49, 0x50). (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 Just in case something needs to be modified in the future. 1 for now.
now.
'DS (coded dictionary size, 1 byte)' 'DS (coded dictionary size, 1 byte)'
The dictionary size is calculated by taking a power of 2 (the base The dictionary size is calculated by taking a power of 2 (the base
size) and subtracting from it a fraction between 0/16 and 7/16 of size) and subtracting from it a fraction between 0/16 and 7/16 of the
the base size. base size.
Bits 4-0 contain the base 2 logarithm of the base size (12 to 29). Bits 4-0 contain the base 2 logarithm of the base size (12 to 29).
Bits 7-5 contain the numerator of the fraction (0 to 7) to subtract Bits 7-5 contain the numerator of the fraction (0 to 7) to subtract
from the base size to obtain the dictionary size. from the base size to obtain the dictionary size.
Example: 0xD3 = 2^19 - 6 * 2^15 = 512 KiB - 6 * 32 KiB = 320 KiB 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. 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 The LZMA stream, finished by an end of stream marker. Uses default
values for encoder properties. *Note Stream format: (lzip)Stream values for encoder properties. *Note Stream format: (lzip)Stream
format, for a complete description. format, for a complete description.
Lzip only uses the LZMA marker '2' ("End Of Stream" marker). Lzlib Lzip only uses the LZMA marker '2' ("End Of Stream" marker). Lzlib
also uses the LZMA marker '3' ("Sync Flush" marker). also uses the LZMA marker '3' ("Sync Flush" marker). *Note
sync_flush::.
'CRC32 (4 bytes)' 'CRC32 (4 bytes)'
CRC of the uncompressed original data. Cyclic Redundancy Check (CRC) of the uncompressed original data.
'Data size (8 bytes)' 'Data size (8 bytes)'
Size of the uncompressed original data. 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 Total size of the member, including header and trailer. This field acts
acts as a distributed index, allows the verification of stream as a distributed index, allows the verification of stream integrity,
integrity, and facilitates safe recovery of undamaged members from and facilitates safe recovery of undamaged members from multimember
multimember files. files.
File: lzlib.info, Node: Examples, Next: Problems, Prev: Data format, Up: Top File: lzlib.info, Node: Examples, Next: Problems, Prev: Data format, Up: Top
11 A small tutorial with examples 11 A small tutorial with examples
********************************* *********************************
This chapter shows the order in which the library functions should be This chapter provides real code examples for the most common uses of the
called depending on what kind of data stream you want to compress or library. See these examples in context in the files 'bbexample.c' and
decompress. See the file 'bbexample.c' in the source distribution for 'ffexample.c' from the source distribution of lzlib.
an example of how buffer-to-buffer compression/decompression can be
implemented using lzlib. Note that the interface of lzlib is symmetrical. That is, the code for
normal compression and decompression is identical except because one calls
Note that lzlib's interface is symmetrical. That is, the code for LZ_compress* functions while the other calls LZ_decompress* functions.
normal compression and decompression is identical except because one
calls LZ_compress* functions while the other calls LZ_decompress* * Menu:
functions.
* Buffer compression:: Buffer-to-buffer single-member compression
Example 1: Normal compression (MEMBER_SIZE > total output). * Buffer decompression:: Buffer-to-buffer decompression
* File compression:: File-to-file single-member compression
1) LZ_compress_open * File decompression:: File-to-file decompression
2) LZ_compress_write * File compression mm:: File-to-file multimember compression
3) if no more data to write, call LZ_compress_finish * Skipping data errors:: Decompression with automatic resynchronization
4) LZ_compress_read
5) go back to step 2 until LZ_compress_finished returns 1 File: lzlib.info, Node: Buffer compression, Next: Buffer decompression, Up: E
6) LZ_compress_close xamples
Example 2: Normal compression using LZ_compress_write_size. 11.1 Buffer compression
=======================
1) LZ_compress_open
2) go to step 5 if LZ_compress_write_size returns 0 Buffer-to-buffer single-member compression (MEMBER_SIZE > total output).
3) LZ_compress_write
4) if no more data to write, call LZ_compress_finish /* Compresses 'insize' bytes from 'inbuf' to 'outbuf'.
5) LZ_compress_read Returns the size of the compressed data in '*outlenp'.
6) go back to step 2 until LZ_compress_finished returns 1 In case of error, or if 'outsize' is too small, returns false and does
7) LZ_compress_close not modify '*outlenp'.
*/
Example 3: Decompression. bool bbcompress( const uint8_t * const inbuf, const int insize,
const int dictionary_size, const int match_len_limit,
1) LZ_decompress_open uint8_t * const outbuf, const int outsize,
2) LZ_decompress_write int * const outlenp )
3) if no more data to write, call LZ_decompress_finish {
4) LZ_decompress_read int inpos = 0, outpos = 0;
5) go back to step 2 until LZ_decompress_finished returns 1 bool error = false;
6) LZ_decompress_close struct LZ_Encoder * const encoder =
LZ_compress_open( dictionary_size, match_len_limit, INT64_MAX );
Example 4: Decompression using LZ_decompress_write_size. if( !encoder || LZ_compress_errno( encoder ) != LZ_ok )
{ LZ_compress_close( encoder ); return false; }
1) LZ_decompress_open
2) go to step 5 if LZ_decompress_write_size returns 0 while( true )
3) LZ_decompress_write {
4) if no more data to write, call LZ_decompress_finish int ret = LZ_compress_write( encoder, inbuf + inpos, insize - inpos );
5) LZ_decompress_read if( ret < 0 ) { error = true; break; }
5a) optionally, if LZ_decompress_member_finished returns 1, read inpos += ret;
final values for member with LZ_decompress_data_crc, etc. if( inpos >= insize ) LZ_compress_finish( encoder );
6) go back to step 2 until LZ_decompress_finished returns 1 ret = LZ_compress_read( encoder, outbuf + outpos, outsize - outpos );
7) LZ_decompress_close if( ret < 0 ) { error = true; break; }
outpos += ret;
Example 5: Multimember compression (MEMBER_SIZE < total output). if( LZ_compress_finished( encoder ) == 1 ) break;
if( outpos >= outsize ) { error = true; break; }
1) LZ_compress_open }
2) go to step 5 if LZ_compress_write_size returns 0
3) LZ_compress_write if( LZ_compress_close( encoder ) < 0 ) error = true;
4) if no more data to write, call LZ_compress_finish if( error ) return false;
5) LZ_compress_read *outlenp = outpos;
6) go back to step 2 until LZ_compress_member_finished returns 1 return true;
7) go to step 10 if LZ_compress_finished() returns 1 }
8) LZ_compress_restart_member
9) go back to step 2 File: lzlib.info, Node: Buffer decompression, Next: File compression, Prev: B
10) LZ_compress_close uffer compression, Up: Examples
Example 6: Multimember compression (user-restarted members). 11.2 Buffer decompression
=========================
1) LZ_compress_open (with MEMBER_SIZE > largest member).
2) LZ_compress_write Buffer-to-buffer decompression.
3) LZ_compress_read
4) go back to step 2 until member termination is desired /* Decompresses 'insize' bytes from 'inbuf' to 'outbuf'.
5) LZ_compress_finish Returns the size of the decompressed data in '*outlenp'.
6) LZ_compress_read In case of error, or if 'outsize' is too small, returns false and does
7) go back to step 6 until LZ_compress_member_finished returns 1 not modify '*outlenp'.
9) go to step 12 if all input data have been written and */
LZ_compress_finished returns 1 bool bbdecompress( const uint8_t * const inbuf, const int insize,
10) LZ_compress_restart_member uint8_t * const outbuf, const int outsize,
11) go back to step 2 int * const outlenp )
12) LZ_compress_close {
int inpos = 0, outpos = 0;
Example 7: Decompression with automatic removal of leading data. bool error = false;
struct LZ_Decoder * const decoder = LZ_decompress_open();
1) LZ_decompress_open if( !decoder || LZ_decompress_errno( decoder ) != LZ_ok )
2) LZ_decompress_sync_to_member { LZ_decompress_close( decoder ); return false; }
3) go to step 6 if LZ_decompress_write_size returns 0
4) LZ_decompress_write while( true )
5) if no more data to write, call LZ_decompress_finish {
6) LZ_decompress_read int ret = LZ_decompress_write( decoder, inbuf + inpos, insize - inpos );
7) go back to step 3 until LZ_decompress_finished returns 1 if( ret < 0 ) { error = true; break; }
8) LZ_decompress_close inpos += ret;
if( inpos >= insize ) LZ_decompress_finish( decoder );
Example 8: Streamed decompression with automatic resynchronization to ret = LZ_decompress_read( decoder, outbuf + outpos, outsize - outpos );
next member in case of data error. if( ret < 0 ) { error = true; break; }
outpos += ret;
1) LZ_decompress_open if( LZ_decompress_finished( decoder ) == 1 ) break;
2) go to step 5 if LZ_decompress_write_size returns 0 if( outpos >= outsize ) { error = true; break; }
3) LZ_decompress_write }
4) if no more data to write, call LZ_decompress_finish
5) if LZ_decompress_read produces LZ_header_error or LZ_data_error, if( LZ_decompress_close( decoder ) < 0 ) error = true;
call LZ_decompress_sync_to_member if( error ) return false;
6) go back to step 2 until LZ_decompress_finished returns 1 *outlenp = outpos;
7) LZ_decompress_close return true;
}
File: lzlib.info, Node: File compression, Next: File decompression, Prev: Buf
fer decompression, Up: Examples
11.3 File compression
=====================
File-to-file compression using LZ_compress_write_size.
int ffcompress( struct LZ_Encoder * const encoder,
FILE * const infile, FILE * const outfile )
{
enum { buffer_size = 16384 };
uint8_t buffer[buffer_size];
while( true )
{
int len, ret;
int size = min( buffer_size, LZ_compress_write_size( encoder ) );
if( size > 0 )
{
len = fread( buffer, 1, size, infile );
ret = LZ_compress_write( encoder, buffer, len );
if( ret < 0 || ferror( infile ) ) break;
if( feof( infile ) ) LZ_compress_finish( encoder );
}
ret = LZ_compress_read( encoder, buffer, buffer_size );
if( ret < 0 ) break;
len = fwrite( buffer, 1, ret, outfile );
if( len < ret ) break;
if( LZ_compress_finished( encoder ) == 1 ) return 0;
}
return 1;
}
File: lzlib.info, Node: File decompression, Next: File compression mm, Prev:
File compression, Up: Examples
11.4 File decompression
=======================
File-to-file decompression using LZ_decompress_write_size.
int ffdecompress( struct LZ_Decoder * const decoder,
FILE * const infile, FILE * const outfile )
{
enum { buffer_size = 16384 };
uint8_t buffer[buffer_size];
while( true )
{
int len, ret;
int size = min( buffer_size, LZ_decompress_write_size( decoder ) );
if( size > 0 )
{
len = fread( buffer, 1, size, infile );
ret = LZ_decompress_write( decoder, buffer, len );
if( ret < 0 || ferror( infile ) ) break;
if( feof( infile ) ) LZ_decompress_finish( decoder );
}
ret = LZ_decompress_read( decoder, buffer, buffer_size );
if( ret < 0 ) break;
len = fwrite( buffer, 1, ret, outfile );
if( len < ret ) break;
if( LZ_decompress_finished( decoder ) == 1 ) return 0;
}
return 1;
}
File: lzlib.info, Node: File compression mm, Next: Skipping data errors, Prev
: File decompression, Up: Examples
11.5 File-to-file multimember compression
=========================================
Example 1: Multimember compression with members of fixed size
(MEMBER_SIZE < total output).
int ffmmcompress( FILE * const infile, FILE * const outfile )
{
enum { buffer_size = 16384, member_size = 4096 };
uint8_t buffer[buffer_size];
bool done = false;
struct LZ_Encoder * const encoder =
LZ_compress_open( 65535, 16, member_size );
if( !encoder || LZ_compress_errno( encoder ) != LZ_ok )
{ fputs( "ffexample: Not enough memory.\n", stderr );
LZ_compress_close( encoder ); return 1; }
while( true )
{
int len, ret;
int size = min( buffer_size, LZ_compress_write_size( encoder ) );
if( size > 0 )
{
len = fread( buffer, 1, size, infile );
ret = LZ_compress_write( encoder, buffer, len );
if( ret < 0 || ferror( infile ) ) break;
if( feof( infile ) ) LZ_compress_finish( encoder );
}
ret = LZ_compress_read( encoder, buffer, buffer_size );
if( ret < 0 ) break;
len = fwrite( buffer, 1, ret, outfile );
if( len < ret ) break;
if( LZ_compress_member_finished( encoder ) == 1 )
{
if( LZ_compress_finished( encoder ) == 1 ) { done = true; break; }
if( LZ_compress_restart_member( encoder, member_size ) < 0 ) break;
}
}
if( LZ_compress_close( encoder ) < 0 ) done = false;
return done;
}
Example 2: Multimember compression (user-restarted members). (Call
LZ_compress_open with MEMBER_SIZE > largest member).
/* Compresses 'infile' to 'outfile' as a multimember stream with one member
for each line of text terminated by a newline character or by EOF.
Returns 0 if success, 1 if error.
*/
int fflfcompress( struct LZ_Encoder * const encoder,
FILE * const infile, FILE * const outfile )
{
enum { buffer_size = 16384 };
uint8_t buffer[buffer_size];
while( true )
{
int len, ret;
int size = min( buffer_size, LZ_compress_write_size( encoder ) );
if( size > 0 )
{
for( len = 0; len < size; )
{
int ch = getc( infile );
if( ch == EOF || ( buffer[len++] = ch ) == '\n' ) break;
}
/* avoid writing an empty member to outfile */
if( len == 0 && LZ_compress_data_position( encoder ) == 0 ) return 0;
ret = LZ_compress_write( encoder, buffer, len );
if( ret < 0 || ferror( infile ) ) break;
if( feof( infile ) || buffer[len-1] == '\n' )
LZ_compress_finish( encoder );
}
ret = LZ_compress_read( encoder, buffer, buffer_size );
if( ret < 0 ) break;
len = fwrite( buffer, 1, ret, outfile );
if( len < ret ) break;
if( LZ_compress_member_finished( encoder ) == 1 )
{
if( feof( infile ) && LZ_compress_finished( encoder ) == 1 ) return 0;
if( LZ_compress_restart_member( encoder, INT64_MAX ) < 0 ) break;
}
}
return 1;
}
File: lzlib.info, Node: Skipping data errors, Prev: File compression mm, Up:
Examples
11.6 Skipping data errors
=========================
/* Decompresses 'infile' to 'outfile' with automatic resynchronization to
next member in case of data error, including the automatic removal of
leading data.
*/
int ffrsdecompress( struct LZ_Decoder * const decoder,
FILE * const infile, FILE * const outfile )
{
enum { buffer_size = 16384 };
uint8_t buffer[buffer_size];
while( true )
{
int len, ret;
int size = min( buffer_size, LZ_decompress_write_size( decoder ) );
if( size > 0 )
{
len = fread( buffer, 1, size, infile );
ret = LZ_decompress_write( decoder, buffer, len );
if( ret < 0 || ferror( infile ) ) break;
if( feof( infile ) ) LZ_decompress_finish( decoder );
}
ret = LZ_decompress_read( decoder, buffer, buffer_size );
if( ret < 0 )
{
if( LZ_decompress_errno( decoder ) == LZ_header_error ||
LZ_decompress_errno( decoder ) == LZ_data_error )
{ LZ_decompress_sync_to_member( decoder ); continue; }
else break;
}
len = fwrite( buffer, 1, ret, outfile );
if( len < ret ) break;
if( LZ_decompress_finished( decoder ) == 1 ) return 0;
}
return 1;
}
File: lzlib.info, Node: Problems, Next: Concept index, Prev: Examples, Up: T op File: lzlib.info, Node: Problems, Next: Concept index, Prev: Examples, Up: T op
12 Reporting bugs 12 Reporting bugs
***************** *****************
There are probably bugs in lzlib. There are certainly errors and There are probably bugs in lzlib. There are certainly errors and omissions
omissions in this manual. If you report them, they will get fixed. If in this manual. If you report them, they will get fixed. If you don't, no
you don't, no one will ever know about them and they will remain unfixed one will ever know about them and they will remain unfixed for all
for all eternity, if not longer. eternity, if not longer.
If you find a bug in lzlib, please send electronic mail to If you find a bug in lzlib, please send electronic mail to
<lzip-bug@nongnu.org>. Include the version number, which you can find <lzip-bug@nongnu.org>. Include the version number, which you can find by
by running 'minilzip --version' or in 'LZ_version_string' from running 'minilzip --version' or in 'LZ_version_string' from 'lzlib.h'.
'lzlib.h'.
File: lzlib.info, Node: Concept index, Prev: Problems, Up: Top File: lzlib.info, Node: Concept index, Prev: Problems, Up: Top
Concept index Concept index
************* *************
* Menu: * Menu:
* buffering: Buffering. (line 6) * buffer compression: Buffer compression. (line 6)
* bugs: Problems. (line 6) * buffer decompression: Buffer decompression. (line 6)
* compression functions: Compression functions. (line 6) * buffering: Buffering. (line 6)
* data format: Data format. (line 6) * bugs: Problems. (line 6)
* decompression functions: Decompression functions. * compression functions: Compression functions. (line 6)
(line 6) * data format: Data format. (line 6)
* error codes: Error codes. (line 6) * decompression functions: Decompression functions. (line 6)
* error messages: Error messages. (line 6) * error codes: Error codes. (line 6)
* examples: Examples. (line 6) * error messages: Error messages. (line 6)
* getting help: Problems. (line 6) * examples: Examples. (line 6)
* introduction: Introduction. (line 6) * file compression: File compression. (line 6)
* invoking: Invoking minilzip. (line 6) * file decompression: File decompression. (line 6)
* library version: Library version. (line 6) * getting help: Problems. (line 6)
* options: Invoking minilzip. (line 6) * introduction: Introduction. (line 6)
* parameter limits: Parameter limits. (line 6) * invoking: Invoking minilzip. (line 6)
* library version: Library version. (line 6)
* multimember compression: File compression mm. (line 6)
* options: Invoking minilzip. (line 6)
* parameter limits: Parameter limits. (line 6)
* skipping data errors: Skipping data errors. (line 6)
 End of changes. 91 change blocks. 
525 lines changed or deleted 759 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)