"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "doc/lzlib.texi" 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.texi  (lzlib-1.11.tar.lz):lzlib.texi  (lzlib-1.12-rc1.tar.lz)
\input texinfo @c -*-texinfo-*- \input texinfo @c -*-texinfo-*-
@c %**start of header @c %**start of header
@setfilename lzlib.info @setfilename lzlib.info
@documentencoding ISO-8859-15 @documentencoding ISO-8859-15
@settitle Lzlib Manual @settitle Lzlib Manual
@finalout @finalout
@c %**end of header @c %**end of header
@set UPDATED 2 January 2019 @set UPDATED 6 June 2020
@set VERSION 1.11 @set VERSION 1.12-rc1
@dircategory Data Compression @dircategory Data Compression
@direntry @direntry
* Lzlib: (lzlib). Compression library for the lzip format * Lzlib: (lzlib). Compression library for the lzip format
@end direntry @end direntry
@ifnothtml @ifnothtml
@titlepage @titlepage
@title Lzlib @title Lzlib
@subtitle Compression library for the lzip format @subtitle Compression library for the lzip format
skipping to change at line 53 skipping to change at line 53
* 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
@end menu @end menu
@sp 1 @sp 1
Copyright @copyright{} 2009-2019 Antonio Diaz Diaz. Copyright @copyright{} 2009-2020 Antonio Diaz Diaz.
This manual is free documentation: you have unlimited permission This manual is free documentation: you have unlimited permission to copy,
to copy, distribute and modify it. distribute, and modify it.
@node Introduction @node Introduction
@chapter Introduction @chapter Introduction
@cindex introduction @cindex introduction
@uref{http://www.nongnu.org/lzip/lzlib.html,,Lzlib} is a data compression @uref{http://www.nongnu.org/lzip/lzlib.html,,Lzlib} is a data compression
library providing in-memory LZMA compression and decompression functions, library providing in-memory LZMA compression and decompression functions,
including integrity checking of the decompressed data. The compressed data including integrity checking of the decompressed data. The compressed data
format used by the library is the lzip format. Lzlib is written in C. format used by the library is the lzip format. Lzlib is written in C.
The lzip file format is designed for data sharing and long-term archiving, The lzip file format is designed for data sharing and long-term archiving,
taking into account both data integrity and decoder availability: taking into account both data integrity and decoder availability:
@itemize @bullet @itemize @bullet
@item @item
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 recovery means. The program
@uref{http://www.nongnu.org/lzip/manual/lziprecover_manual.html#Data-safety,,lzi precover} @uref{http://www.nongnu.org/lzip/manual/lziprecover_manual.html#Data-safety,,lzi precover}
program can repair bit flip errors (one of the most common forms of data can repair bit flip errors (one of the most common forms of data
corruption) in lzip files, and provides data recovery capabilities, corruption) in lzip files, and provides data recovery capabilities,
including error-checked merging of damaged copies of a file. including error-checked merging of damaged copies of a file.
@ifnothtml @ifnothtml
@xref{Data safety,,,lziprecover}. @xref{Data safety,,,lziprecover}.
@end ifnothtml @end ifnothtml
@item @item
The lzip format is as simple as possible (but not simpler). The lzip The lzip format is as simple as possible (but not simpler). The lzip
manual provides the source code of a simple decompressor along with a manual provides the source code of a simple decompressor along with a
detailed explanation of how it works, so that with the only help of the detailed explanation of how it works, so that with the only help of the
lzip manual it would be possible for a digital archaeologist to extract lzip manual it would be possible for a digital archaeologist to extract
the data from a lzip file long after quantum computers eventually render the data from a lzip file long after quantum computers eventually render
LZMA obsolete. LZMA obsolete.
@item @item
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.
@end itemize @end itemize
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
repair the nearer it is from the beginning of the file. Therefore, with the nearer it is from the beginning of the file. Therefore, with the help of
the help of lziprecover, losing an entire archive just because of a lziprecover, losing an entire archive just because of a corrupt byte near
corrupt byte near the beginning is a thing of the past. 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
library are declared in the file @samp{lzlib.h}. Usage examples of the are declared in the file @samp{lzlib.h}. Usage examples of the library are
library are given in the files @samp{main.c} and @samp{bbexample.c} from given in the files @samp{bbexample.c}, @samp{ffexample.c}, and @samp{main.c}
the source distribution. from the 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. This Compression/decompression is done when the read function is called. This
means the value returned by the position functions will not be updated means the value returned by the position functions will not be updated until
until a read call, even if a lot of data are written. If you want the a read call, even if a lot of data are written. If you want the data to be
data to be compressed in advance, just call the read function with a compressed in advance, just call the read function with a @var{size} equal
@var{size} equal to 0. 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 @samp{LZ_compress_open}. This feature reduces the given to @samp{LZ_compress_open}. This feature reduces the amount of memory
amount 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 concatenation Lzlib will correctly decompress a data stream which is the concatenation of
of two or more compressed data streams. The result is the concatenation two or more compressed data streams. The result is the concatenation of the
of the corresponding decompressed data streams. Integrity testing of corresponding decompressed data streams. Integrity testing of concatenated
concatenated compressed data streams is also supported. 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 @w{2 PiB} each. about @w{2 PiB} each.
All the library functions are thread safe. The library does not install All the library functions are thread safe. The library does not install
any signal handler. The decoder checks the consistency of the compressed any signal handler. The decoder checks the consistency of the compressed
data, so the library should never crash even in case of corrupted input. data, so the library should never crash even in case of 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 not a
concrete algorithm; it is more like "any algorithm using the LZMA coding concrete algorithm; it is more like "any algorithm using the LZMA coding
scheme". For example, the option @samp{-0} of lzip uses the scheme in almost scheme". For example, the option @samp{-0} of lzip uses the scheme in almost
the simplest way possible; issuing the longest match it can find, or a the simplest way possible; issuing the longest match it can find, or a
literal byte if it can't find a match. Inversely, a much more elaborated literal byte if it can't find a match. Inversely, a much more elaborated way
way of finding coding sequences of minimum size than the one currently of finding coding sequences of minimum size than the one currently used by
used by lzip could be developed, and the resulting sequence could also lzip could be developed, and the resulting sequence could also be coded
be coded using the LZMA coding scheme. 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
(used by option @samp{-0} of minilzip) and normal (used by all other option @samp{-0} of minilzip) and normal (used by all other compression
compression levels). levels).
The high compression of LZMA comes from combining two basic, well-proven The high compression of LZMA comes from combining two basic, well-proven
compression ideas: sliding dictionaries (LZ77/78) and markov models (the compression ideas: sliding dictionaries (LZ77/78) and markov models (the
thing used by every compression algorithm that uses a range encoder or thing used by every compression algorithm that uses a range encoder or
similar order-0 entropy coder as its last stage) with segregation of similar order-0 entropy coder as its last stage) 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 people: The ideas embodied in lzlib are due to (at least) the following people:
Abraham Lempel and Jacob Ziv (for the LZ algorithm), Andrey Markov (for Abraham Lempel and Jacob Ziv (for the LZ algorithm), Andrey Markov (for the
the definition of Markov chains), G.N.N. Martin (for the definition of definition of Markov chains), G.N.N. Martin (for the definition of range
range encoding), Igor Pavlov (for putting all the above together in encoding), Igor Pavlov (for putting all the above together in LZMA), and
LZMA), and Julian Seward (for bzip2's CLI). Julian Seward (for bzip2's CLI).
LANGUAGE NOTE: Uncompressed = not compressed = plain data; it may never LANGUAGE NOTE: Uncompressed = not compressed = plain data; it may never have
have been compressed. Decompressed is used to refer to data which have been compressed. Decompressed is used to refer to data which have undergone
undergone the process of decompression. the process of decompression.
@node Library version @node Library version
@chapter Library version @chapter Library version
@cindex library version @cindex library version
@deftypefun {const char *} LZ_version ( void ) @deftypefun {const char *} LZ_version ( void )
Returns the library version as a string. Returns the library version as a string.
@end deftypefun @end deftypefun
@deftypevr Constant {const char *} LZ_version_string @deftypevr Constant {const char *} LZ_version_string
skipping to change at line 198 skipping to change at line 198
@chapter Buffering @chapter Buffering
@cindex buffering @cindex 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 the dictionary size (sliding window). For efficiency reasons, the as the dictionary size (sliding window). For efficiency reasons, the
input buffer for compression is twice or sixteen times as large as the input buffer for compression is twice or sixteen times as large as the
dictionary size. dictionary 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 minimum These are the four buffers used by lzlib, and their guaranteed minimum sizes:
sizes:
@itemize @bullet @itemize @bullet
@item Input compression buffer. Written to by the @item Input compression buffer. Written to by the function
@samp{LZ_compress_write} function. For the normal variant of LZMA, its @samp{LZ_compress_write}. For the normal variant of LZMA, its size is two
size is two times the dictionary size set with the times the dictionary size set with the function @samp{LZ_compress_open} or
@samp{LZ_compress_open} function or @w{64 KiB}, whichever is larger. For @w{64 KiB}, whichever is larger. For the fast variant, its size is @w{1 MiB}.
the fast variant, its size is @w{1 MiB}.
@item Output compression buffer. Read from by the function
@item Output compression buffer. Read from by the @samp{LZ_compress_read}. Its size is @w{64 KiB}.
@samp{LZ_compress_read} function. Its size is @w{64 KiB}.
@item Input decompression buffer. Written to by the function
@item Input decompression buffer. Written to by the @samp{LZ_decompress_write}. Its size is @w{64 KiB}.
@samp{LZ_decompress_write} function. Its size is @w{64 KiB}.
@item Output decompression buffer. Read from by the function
@item Output decompression buffer. Read from by the @samp{LZ_decompress_read}. Its size is the dictionary size set in the header
@samp{LZ_decompress_read} function. Its size is the dictionary size set of the member currently being decompressed or @w{64 KiB}, whichever is larger.
in the header of the member currently being decompressed or @w{64 KiB},
whichever is larger.
@end itemize @end itemize
@node Parameter limits @node Parameter limits
@chapter Parameter limits @chapter Parameter limits
@cindex parameter limits @cindex 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.
@deftypefun int LZ_min_dictionary_bits ( void ) @deftypefun int LZ_min_dictionary_bits ( void )
skipping to change at line 273 skipping to change at line 270
other LZ_compress functions, or a null pointer if the encoder could not other LZ_compress functions, or a null pointer if the encoder could not
be allocated. be allocated.
The returned pointer must be verified by calling The returned pointer must be verified by calling
@samp{LZ_compress_errno} before using it. If @samp{LZ_compress_errno} @samp{LZ_compress_errno} before using it. If @samp{LZ_compress_errno}
does not return @samp{LZ_ok}, the returned pointer must not be used and does not return @samp{LZ_ok}, the returned pointer must not be used and
should be freed with @samp{LZ_compress_close} to avoid memory leaks. should be freed with @samp{LZ_compress_close} to avoid memory leaks.
@var{dictionary_size} sets the dictionary size to be used, in bytes. @var{dictionary_size} sets the dictionary size to be used, in bytes.
Valid values range from @w{4 KiB} to @w{512 MiB}. Note that dictionary Valid values range from @w{4 KiB} to @w{512 MiB}. Note that dictionary
sizes are quantized. If the specified size does not match one of the sizes are quantized. If the size specified does not match one of the
valid sizes, it will be rounded upwards by adding up to valid sizes, it will be rounded upwards by adding up to
@w{(@var{dictionary_size} / 8)} to it. @w{(@var{dictionary_size} / 8)} to it.
@var{match_len_limit} sets the match length limit in bytes. Valid values @var{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
ratios but longer compression times. but longer compression times.
If @var{dictionary_size} is 65535 and @var{match_len_limit} is 16, the If @var{dictionary_size} is 65535 and @var{match_len_limit} is 16, the fast
fast variant of LZMA is chosen, which produces identical compressed variant of LZMA is chosen, which produces identical compressed output as
output as @code{lzip -0}. (The dictionary size used will be rounded @w{@samp{lzip -0}}. (The dictionary size used will be rounded upwards to
upwards to @w{64 KiB}). @w{64 KiB}).
@var{member_size} sets the member size limit in bytes. Valid values @anchor{member_size}
range from @w{100 kB} to @w{2 PiB}. Small member size may degrade @var{member_size} sets the member size limit in bytes. Valid values range
compression ratio, so use it only when needed. To produce a from @w{4 KiB} to @w{2 PiB}. A small member size may degrade compression
single-member data stream, give @var{member_size} a value larger than ratio, so use it only when needed. To produce a single-member data stream,
the amount of data to be produced. Values larger than @w{2 PiB} will be give @var{member_size} a value larger than the amount of data to be
reduced to @w{2 PiB} to prevent the uncompressed size of the member from produced. Values larger than @w{2 PiB} will be reduced to @w{2 PiB} to
overflowing. prevent the uncompressed size of the member from overflowing.
@end deftypefun @end deftypefun
@deftypefun int LZ_compress_close ( struct LZ_Encoder * const @var{encoder} ) @deftypefun int LZ_compress_close ( struct LZ_Encoder * const @var{encoder} )
Frees all dynamically allocated data structures for this stream. This Frees all dynamically allocated data structures for this stream. This
function discards any unprocessed input and does not flush any pending function discards any unprocessed input and does not flush any pending
output. After a call to @samp{LZ_compress_close}, @var{encoder} can no output. After a call to @samp{LZ_compress_close}, @var{encoder} can no
longer be used as an argument to any LZ_compress function. longer be used as an argument to any LZ_compress function.
It is safe to call @samp{LZ_compress_close} with a null argument.
@end deftypefun @end deftypefun
@deftypefun int LZ_compress_finish ( struct LZ_Encoder * const @var{encoder} ) @deftypefun int LZ_compress_finish ( struct LZ_Encoder * const @var{encoder} )
Use this function to tell @samp{lzlib} that all the data for this member Use this function to tell @samp{lzlib} that all the data for this member
have already been written (with the @samp{LZ_compress_write} function). have already been written (with the function @samp{LZ_compress_write}).
It is safe to call @samp{LZ_compress_finish} as many times as needed. It is safe to call @samp{LZ_compress_finish} as many times as needed.
After all the produced compressed data have been read with After all the compressed data have been read with @samp{LZ_compress_read}
@samp{LZ_compress_read} and @samp{LZ_compress_member_finished} returns and @samp{LZ_compress_member_finished} returns 1, a new member can be
1, a new member can be started with @samp{LZ_compress_restart_member}. started with @samp{LZ_compress_restart_member}.
@end deftypefun @end deftypefun
@deftypefun int LZ_compress_restart_member ( struct LZ_Encoder * const @var{enco der}, const unsigned long long @var{member_size} ) @deftypefun int LZ_compress_restart_member ( struct LZ_Encoder * const @var{enco der}, const unsigned long long @var{member_size} )
Use this function to start a new member in a multimember data stream. Use this function to start a new member in a multimember data stream. Call
Call this function only after @samp{LZ_compress_member_finished} this function only after @samp{LZ_compress_member_finished} indicates that
indicates that the current member has been fully read (with the the current member has been fully read (with the function
@samp{LZ_compress_read} function). @samp{LZ_compress_read}). @xref{member_size}, for a description of
@var{member_size}.
@end deftypefun @end deftypefun
@anchor{sync_flush}
@deftypefun int LZ_compress_sync_flush ( struct LZ_Encoder * const @var{encoder} ) @deftypefun int LZ_compress_sync_flush ( struct LZ_Encoder * const @var{encoder} )
Use this function to make available to @samp{LZ_compress_read} all the Use this function to make available to @samp{LZ_compress_read} all the data
data already written with the @samp{LZ_compress_write} function. First already written with the function @samp{LZ_compress_write}. First call
call @samp{LZ_compress_sync_flush}. Then call @samp{LZ_compress_read} @samp{LZ_compress_sync_flush}. Then call @samp{LZ_compress_read} until it
until it returns 0. returns 0.
This function writes a LZMA marker @samp{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 @samp{application/lzip}. The LZMA marker @samp{2} ("End Of
Stream" marker) is the only marker allowed in lzip files. @xref{Data format}.
Repeated use of @samp{LZ_compress_sync_flush} may degrade compression Repeated use of @samp{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
@samp{LZ_compress_sync_flush} is large (comparable to dictionary size),
creating a multimember data stream with @samp{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 @var{member_size},
@samp{LZ_compress_restart_member} needs to be called when
@samp{LZ_compress_member_finished} returns 1, followed by a new call to
@samp{LZ_compress_sync_flush}.
@end deftypefun @end deftypefun
@deftypefun int LZ_compress_read ( struct LZ_Encoder * const @var{encoder}, uint 8_t * const @var{buffer}, const int @var{size} ) @deftypefun int LZ_compress_read ( struct LZ_Encoder * const @var{encoder}, uint 8_t * const @var{buffer}, const int @var{size} )
The @samp{LZ_compress_read} function reads up to @var{size} bytes from The function @samp{LZ_compress_read} reads up to @var{size} bytes from the
the stream pointed to by @var{encoder}, storing the results in stream pointed to by @var{encoder}, storing the results in @var{buffer}.
@var{buffer}.
The return value is the number of bytes actually read. This might be The return value is the number of bytes actually read. This might be less
less than @var{size}; for example, if there aren't that many bytes left than @var{size}; for example, if there aren't that many bytes left in the
in the stream or if more bytes have to be yet written with the stream or if more bytes have to be yet written with the function
@samp{LZ_compress_write} function. Note that reading less than @samp{LZ_compress_write}. Note that reading less than @var{size} bytes is
@var{size} bytes is not an error. not an error.
@end deftypefun @end deftypefun
@deftypefun int LZ_compress_write ( struct LZ_Encoder * const @var{encoder}, uin t8_t * const @var{buffer}, const int @var{size} ) @deftypefun int LZ_compress_write ( struct LZ_Encoder * const @var{encoder}, uin t8_t * const @var{buffer}, const int @var{size} )
The @samp{LZ_compress_write} function writes up to @var{size} bytes from The function @samp{LZ_compress_write} writes up to @var{size} bytes from
@var{buffer} to the stream pointed to by @var{encoder}. @var{buffer} to the stream pointed to by @var{encoder}.
The return value is the number of bytes actually written. This might be The return value is the number of bytes actually written. This might be
less than @var{size}. Note that writing less than @var{size} bytes is less than @var{size}. Note that writing less than @var{size} bytes is
not an error. not an error.
@end deftypefun @end deftypefun
@deftypefun int LZ_compress_write_size ( struct LZ_Encoder * const @var{encoder} ) @deftypefun int LZ_compress_write_size ( struct LZ_Encoder * const @var{encoder} )
The @samp{LZ_compress_write_size} function returns the maximum number of The function @samp{LZ_compress_write_size} returns the maximum number of
bytes that can be immediately written through the @samp{LZ_compress_write} bytes that can be immediately written through @samp{LZ_compress_write}.
function. For efficiency reasons, once the input buffer is full and
@samp{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 @samp{LZ_compress_write} will It is guaranteed that an immediate call to @samp{LZ_compress_write} will
accept a @var{size} up to the returned number of bytes. accept a @var{size} up to the returned number of bytes.
@end deftypefun @end deftypefun
@deftypefun {enum LZ_Errno} LZ_compress_errno ( struct LZ_Encoder * const @var{e ncoder} ) @deftypefun {enum LZ_Errno} LZ_compress_errno ( struct LZ_Encoder * const @var{e ncoder} )
Returns the current error code for @var{encoder}. @xref{Error codes}. Returns the current error code for @var{encoder}. @xref{Error codes}.
It is safe to call @samp{LZ_compress_errno} with a null argument, in which
case it returns @samp{LZ_bad_argument}.
@end deftypefun @end deftypefun
@deftypefun int LZ_compress_finished ( struct LZ_Encoder * const @var{encoder} ) @deftypefun int LZ_compress_finished ( struct LZ_Encoder * const @var{encoder} )
Returns 1 if all the data have been read and @samp{LZ_compress_close} Returns 1 if all the data have been read and @samp{LZ_compress_close}
can be safely called. Otherwise it returns 0. @samp{LZ_compress_finished} can be safely called. Otherwise it returns 0. @samp{LZ_compress_finished}
implies @samp{LZ_compress_member_finished}. implies @samp{LZ_compress_member_finished}.
@end deftypefun @end deftypefun
@deftypefun int LZ_compress_member_finished ( struct LZ_Encoder * const @var{enc oder} ) @deftypefun int LZ_compress_member_finished ( struct LZ_Encoder * const @var{enc oder} )
Returns 1 if the current member, in a multimember data stream, has been Returns 1 if the current member, in a multimember data stream, has been
fully read and @samp{LZ_compress_restart_member} can be safely called. fully read and @samp{LZ_compress_restart_member} can be safely called.
Otherwise it returns 0. Otherwise it returns 0.
@end deftypefun @end deftypefun
@deftypefun {unsigned long long} LZ_compress_data_position ( struct LZ_Encoder * const @var{encoder} ) @deftypefun {unsigned long long} LZ_compress_data_position ( struct LZ_Encoder * const @var{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.
@end deftypefun @end deftypefun
@deftypefun {unsigned long long} LZ_compress_member_position ( struct LZ_Encoder * const @var{encoder} ) @deftypefun {unsigned long long} LZ_compress_member_position ( struct LZ_Encoder * const @var{encoder} )
Returns the number of compressed bytes already produced, but perhaps not Returns the number of compressed bytes already produced, but perhaps not
yet read, in the current member. yet read, in the current member.
@end deftypefun @end deftypefun
@deftypefun {unsigned long long} LZ_compress_total_in_size ( struct LZ_Encoder * const @var{encoder} ) @deftypefun {unsigned long long} LZ_compress_total_in_size ( struct LZ_Encoder * const @var{encoder} )
Returns the total number of input bytes already compressed. Returns the total number of input bytes already compressed.
@end deftypefun @end deftypefun
skipping to change at line 420 skipping to change at line 440
@samp{LZ_decompress_errno} does not return @samp{LZ_ok}, the returned @samp{LZ_decompress_errno} does not return @samp{LZ_ok}, the returned
pointer must not be used and should be freed with pointer must not be used and should be freed with
@samp{LZ_decompress_close} to avoid memory leaks. @samp{LZ_decompress_close} to avoid memory leaks.
@end deftypefun @end deftypefun
@deftypefun int LZ_decompress_close ( struct LZ_Decoder * const @var{decoder} ) @deftypefun int LZ_decompress_close ( struct LZ_Decoder * const @var{decoder} )
Frees all dynamically allocated data structures for this stream. This Frees all dynamically allocated data structures for this stream. This
function discards any unprocessed input and does not flush any pending function discards any unprocessed input and does not flush any pending
output. After a call to @samp{LZ_decompress_close}, @var{decoder} can no output. After a call to @samp{LZ_decompress_close}, @var{decoder} can no
longer be used as an argument to any LZ_decompress function. longer be used as an argument to any LZ_decompress function.
It is safe to call @samp{LZ_decompress_close} with a null argument.
@end deftypefun @end deftypefun
@deftypefun int LZ_decompress_finish ( struct LZ_Decoder * const @var{decoder} ) @deftypefun int LZ_decompress_finish ( struct LZ_Decoder * const @var{decoder} )
Use this function to tell @samp{lzlib} that all the data for this stream Use this function to tell @samp{lzlib} that all the data for this stream
have already been written (with the @samp{LZ_decompress_write} function). have already been written (with the function @samp{LZ_decompress_write}).
It is safe to call @samp{LZ_decompress_finish} as many times as needed. It is safe to call @samp{LZ_decompress_finish} as many times as needed.
It is not required to call @samp{LZ_decompress_finish} if the input stream
only contains whole members, but not calling it prevents lzlib from
detecting a truncated member.
@end deftypefun @end deftypefun
@deftypefun int LZ_decompress_reset ( struct LZ_Decoder * const @var{decoder} ) @deftypefun int LZ_decompress_reset ( struct LZ_Decoder * const @var{decoder} )
Resets the internal state of @var{decoder} as it was just after opening Resets the internal state of @var{decoder} as it was just after opening
it with the @samp{LZ_decompress_open} function. Data stored in the it with the function @samp{LZ_decompress_open}. Data stored in the
internal buffers is discarded. Position counters are set to 0. internal buffers is discarded. Position counters are set to 0.
@end deftypefun @end deftypefun
@deftypefun int LZ_decompress_sync_to_member ( struct LZ_Decoder * const @var{de coder} ) @deftypefun int LZ_decompress_sync_to_member ( struct LZ_Decoder * const @var{de coder} )
Resets the error state of @var{decoder} and enters a search state that Resets the error state of @var{decoder} and enters a search state that
lasts until a new member header (or the end of the stream) is found. lasts until a new member header (or the end of the stream) is found.
After a successful call to @samp{LZ_decompress_sync_to_member}, data After a successful call to @samp{LZ_decompress_sync_to_member}, data
written with @samp{LZ_decompress_write} will be consumed and written with @samp{LZ_decompress_write} will be consumed and
@samp{LZ_decompress_read} will return 0 until a header is found. @samp{LZ_decompress_read} will return 0 until a header is found.
This function is useful to discard any data preceding the first member, This function is useful to discard any data preceding the first member,
or to discard the rest of the current member, for example in case of a or to discard the rest of the current member, for example in case of a
data error. If the decoder is already at the beginning of a member, this data error. If the decoder is already at the beginning of a member, this
function does nothing. function does nothing.
@end deftypefun @end deftypefun
@deftypefun int LZ_decompress_read ( struct LZ_Decoder * const @var{decoder}, ui nt8_t * const @var{buffer}, const int @var{size} ) @deftypefun int LZ_decompress_read ( struct LZ_Decoder * const @var{decoder}, ui nt8_t * const @var{buffer}, const int @var{size} )
The @samp{LZ_decompress_read} function reads up to @var{size} bytes from The function @samp{LZ_decompress_read} reads up to @var{size} bytes from the
the stream pointed to by @var{decoder}, storing the results in stream pointed to by @var{decoder}, storing the results in @var{buffer}.
@var{buffer}.
The return value is the number of bytes actually read. This might be The return value is the number of bytes actually read. This might be
less than @var{size}; for example, if there aren't that many bytes left less than @var{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 in the stream or if more bytes have to be yet written with the function
@samp{LZ_decompress_write} function. Note that reading less than @samp{LZ_decompress_write}. Note that reading less than @var{size} bytes
@var{size} bytes is not an error. is not an error.
@samp{LZ_decompress_read} returns at least once per member so that
@samp{LZ_decompress_member_finished} can be called (and trailer data
retrieved) for each member, even for empty members. Therefore,
@samp{LZ_decompress_read} returning 0 does not mean that the end of the
stream has been reached. The increase in the value returned by
@samp{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,
@samp{LZ_decompress_read} does not signal the error immediately to the @samp{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 allows tools like
@uref{http://www.nongnu.org/lzip/manual/tarlz_manual.html,,tarlz} to @uref{http://www.nongnu.org/lzip/manual/tarlz_manual.html,,tarlz} to
recover as much data as possible from each damaged member. recover as much data as possible from each damaged member.
@ifnothtml @ifnothtml
@xref{Top,tarlz manual,,tarlz}. @xref{Top,tarlz manual,,tarlz}.
@end ifnothtml @end ifnothtml
@end deftypefun @end deftypefun
@deftypefun int LZ_decompress_write ( struct LZ_Decoder * const @var{decoder}, u int8_t * const @var{buffer}, const int @var{size} ) @deftypefun int LZ_decompress_write ( struct LZ_Decoder * const @var{decoder}, u int8_t * const @var{buffer}, const int @var{size} )
The @samp{LZ_decompress_write} function writes up to @var{size} bytes from The function @samp{LZ_decompress_write} writes up to @var{size} bytes from
@var{buffer} to the stream pointed to by @var{decoder}. @var{buffer} to the stream pointed to by @var{decoder}.
The return value is the number of bytes actually written. This might be The return value is the number of bytes actually written. This might be
less than @var{size}. Note that writing less than @var{size} bytes is less than @var{size}. Note that writing less than @var{size} bytes is
not an error. not an error.
@end deftypefun @end deftypefun
@deftypefun int LZ_decompress_write_size ( struct LZ_Decoder * const @var{decode r} ) @deftypefun int LZ_decompress_write_size ( struct LZ_Decoder * const @var{decode r} )
The @samp{LZ_decompress_write_size} function returns the maximum number The function @samp{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 @samp{LZ_decompress_write}.
@samp{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 @samp{LZ_decompress_write} It is guaranteed that an immediate call to @samp{LZ_decompress_write} will
will accept a @var{size} up to the returned number of bytes. accept a @var{size} up to the returned number of bytes.
@end deftypefun @end deftypefun
@deftypefun {enum LZ_Errno} LZ_decompress_errno ( struct LZ_Decoder * const @var {decoder} ) @deftypefun {enum LZ_Errno} LZ_decompress_errno ( struct LZ_Decoder * const @var {decoder} )
Returns the current error code for @var{decoder}. @xref{Error codes}. Returns the current error code for @var{decoder}. @xref{Error codes}.
It is safe to call @samp{LZ_decompress_errno} with a null argument, in which
case it returns @samp{LZ_bad_argument}.
@end deftypefun @end deftypefun
@deftypefun int LZ_decompress_finished ( struct LZ_Decoder * const @var{decoder} ) @deftypefun int LZ_decompress_finished ( struct LZ_Decoder * const @var{decoder} )
Returns 1 if all the data have been read and @samp{LZ_decompress_close} Returns 1 if all the data have been read and @samp{LZ_decompress_close}
can be safely called. Otherwise it returns 0. can be safely called. Otherwise it returns 0. @samp{LZ_decompress_finished}
does not imply @samp{LZ_decompress_member_finished}.
@end deftypefun @end deftypefun
@deftypefun int LZ_decompress_member_finished ( struct LZ_Decoder * const @var{d ecoder} ) @deftypefun int LZ_decompress_member_finished ( struct LZ_Decoder * const @var{d ecoder} )
Returns 1 if the previous call to @samp{LZ_decompress_read} finished Returns 1 if the previous call to @samp{LZ_decompress_read} finished reading
reading the current member, indicating that final values for member are the current member, indicating that final values for member are available
available through @samp{LZ_decompress_data_crc}, through @samp{LZ_decompress_data_crc}, @samp{LZ_decompress_data_position},
@samp{LZ_decompress_data_position}, and and @samp{LZ_decompress_member_position}. Otherwise it returns 0.
@samp{LZ_decompress_member_position}. Otherwise it returns 0.
@end deftypefun @end deftypefun
@deftypefun int LZ_decompress_member_version ( struct LZ_Decoder * const @var{de coder} ) @deftypefun int LZ_decompress_member_version ( struct LZ_Decoder * const @var{de coder} )
Returns the version of current member from member header. Returns the version of current member from member header.
@end deftypefun @end deftypefun
@deftypefun int LZ_decompress_dictionary_size ( struct LZ_Decoder * const @var{d ecoder} ) @deftypefun int LZ_decompress_dictionary_size ( struct LZ_Decoder * const @var{d ecoder} )
Returns the dictionary size of current member from member header. Returns the dictionary size of the current member, read from the member
header.
@end deftypefun @end deftypefun
@deftypefun {unsigned} LZ_decompress_data_crc ( struct LZ_Decoder * const @var{d ecoder} ) @deftypefun {unsigned} LZ_decompress_data_crc ( struct LZ_Decoder * const @var{d ecoder} )
Returns the 32 bit Cyclic Redundancy Check of the data decompressed from Returns the 32 bit Cyclic Redundancy Check of the data decompressed from
the current member. The returned value is valid only when the current member. The returned value is valid only when
@samp{LZ_decompress_member_finished} returns 1. @samp{LZ_decompress_member_finished} returns 1.
@end deftypefun @end deftypefun
@deftypefun {unsigned long long} LZ_decompress_data_position ( struct LZ_Decoder * const @var{decoder} ) @deftypefun {unsigned long long} LZ_decompress_data_position ( struct LZ_Decoder * const @var{decoder} )
Returns the number of decompressed bytes already produced, but perhaps Returns the number of decompressed bytes already produced, but perhaps
not yet read, in the current member. not yet read, in the current member.
@end deftypefun @end deftypefun
@deftypefun {unsigned long long} LZ_decompress_member_position ( struct LZ_Decod er * const @var{decoder} ) @deftypefun {unsigned long long} LZ_decompress_member_position ( struct LZ_Decod er * const @var{decoder} )
Returns the number of input bytes already decompressed in the current Returns the number of input bytes already decompressed in the current member.
member.
@end deftypefun @end deftypefun
@deftypefun {unsigned long long} LZ_decompress_total_in_size ( struct LZ_Decoder * const @var{decoder} ) @deftypefun {unsigned long long} LZ_decompress_total_in_size ( struct LZ_Decoder * const @var{decoder} )
Returns the total number of input bytes already decompressed. Returns the total number of input bytes already decompressed.
@end deftypefun @end deftypefun
@deftypefun {unsigned long long} LZ_decompress_total_out_size ( struct LZ_Decode r * const @var{decoder} ) @deftypefun {unsigned long long} LZ_decompress_total_out_size ( struct LZ_Decode r * const @var{decoder} )
Returns the total number of decompressed bytes already produced, but Returns the total number of decompressed bytes already produced, but
perhaps not yet read. perhaps not yet read.
@end deftypefun @end deftypefun
skipping to change at line 561 skipping to change at line 595
examine @samp{LZ_(de)compress_errno}. examine @samp{LZ_(de)compress_errno}.
The error codes are defined in the header file @samp{lzlib.h}. The error codes are defined in the header file @samp{lzlib.h}.
@deftypevr Constant {enum LZ_Errno} LZ_ok @deftypevr Constant {enum LZ_Errno} LZ_ok
The value of this constant is 0 and is used to indicate that there is no The value of this constant is 0 and is used to indicate that there is no
error. error.
@end deftypevr @end deftypevr
@deftypevr Constant {enum LZ_Errno} LZ_bad_argument @deftypevr 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.
@end deftypevr @end deftypevr
@deftypevr Constant {enum LZ_Errno} LZ_mem_error @deftypevr 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.
@end deftypevr @end deftypevr
@deftypevr Constant {enum LZ_Errno} LZ_sequence_error @deftypevr 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
@samp{LZ_compress_restart_member} was called before @samp{LZ_compress_restart_member} was called before
@samp{LZ_compress_member_finished} indicates that the current member is @samp{LZ_compress_member_finished} indicates that the current member is
finished. finished.
@end deftypevr @end deftypevr
@deftypevr Constant {enum LZ_Errno} LZ_header_error @deftypevr Constant {enum LZ_Errno} LZ_header_error
An invalid member header (one with the wrong magic bytes) was read. If An invalid member header (one with the wrong magic bytes) was read. If
this happens at the end of the data stream it may indicate trailing this happens at the end of the data stream it may indicate trailing data.
data.
@end deftypevr @end deftypevr
@deftypevr Constant {enum LZ_Errno} LZ_unexpected_eof @deftypevr 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.
@end deftypevr @end deftypevr
@deftypevr Constant {enum LZ_Errno} LZ_data_error @deftypevr Constant {enum LZ_Errno} LZ_data_error
The data stream is corrupt. If @samp{LZ_decompress_member_position} is 6 The data stream is corrupt. If @samp{LZ_decompress_member_position} is 6
or less, it indicates either a format version not supported, an invalid or less, it indicates either a format version not supported, an invalid
dictionary size, a corrupt header in a multimember data stream, or dictionary size, a corrupt header in a multimember data stream, or
skipping to change at line 618 skipping to change at line 650
The value of @var{lz_errno} normally comes from a call to The value of @var{lz_errno} normally comes from a call to
@samp{LZ_(de)compress_errno}. @samp{LZ_(de)compress_errno}.
@end deftypefun @end deftypefun
@node Invoking minilzip @node Invoking minilzip
@chapter Invoking minilzip @chapter Invoking minilzip
@cindex invoking @cindex invoking
@cindex options @cindex options
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.
@uref{http://www.nongnu.org/lzip/lzip.html,,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 @w{(lzip -0)} or compress most files more
than bzip2 @w{(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.
@noindent @noindent
The format for running minilzip is: The format for running minilzip is:
@example @example
minilzip [@var{options}] [@var{files}] minilzip [@var{options}] [@var{files}]
@end example @end example
@noindent @noindent
@samp{-} used as a @var{file} argument means standard input. It can be If no file names are specified, minilzip compresses (or decompresses) from
mixed with other @var{files} and is read just once, the first time it standard input to standard output. A hyphen @samp{-} used as a @var{file}
appears in the command line. argument means standard input. It can be mixed with other @var{files} and is
read just once, the first time it appears in the command line.
minilzip supports the following options: minilzip supports the following
@uref{http://www.nongnu.org/arg-parser/manual/arg_parser_manual.html#Argument-sy
ntax,,options}:
@ifnothtml
@xref{Argument syntax,,,arg_parser}.
@end ifnothtml
@table @code @table @code
@item -h @item -h
@itemx --help @itemx --help
Print an informative help message describing the options and exit. Print an informative help message describing the options and exit.
@item -V @item -V
@itemx --version @itemx --version
Print the version number of minilzip on the standard output and exit. Print the version number of minilzip on the standard output and exit.
This version number should be included in all bug reports. This version number should be included in all bug reports.
@anchor{--trailing-error}
@item -a @item -a
@itemx --trailing-error @itemx --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 trailing decompressing the last member. Such remaining input is usually trailing
garbage that can be safely ignored. garbage that can be safely ignored.
@item -b @var{bytes} @item -b @var{bytes}
@itemx --member-size=@var{bytes} @itemx --member-size=@var{bytes}
When compressing, set the member size limit to @var{bytes}. A small When compressing, set the member size limit to @var{bytes}. It is advisable
member size may degrade compression ratio, so use it only when needed. to keep members smaller than RAM size so that they can be repaired with
Valid values range from @w{100 kB} to @w{2 PiB}. Defaults to @w{2 PiB}. lziprecover in case of corruption. A small member size may degrade
compression ratio, so use it only when needed. Valid values range from
@w{100 kB} to @w{2 PiB}. Defaults to @w{2 PiB}.
@item -c @item -c
@itemx --stdout @itemx --stdout
Compress or decompress to standard output; keep input files unchanged. Compress or decompress to standard output; keep input files unchanged. If
If compressing several files, each file is compressed independently. compressing several files, each file is compressed independently. (The
This option is needed when reading from a named pipe (fifo) or from a output consists of a sequence of independently compressed members). This
device. Use it also to recover as much of the decompressed data as option (or @samp{-o}) is needed when reading from a named pipe (fifo) or
possible when decompressing a corrupt file. from a device. Use it also to recover as much of the decompressed data as
possible when decompressing a corrupt file. @samp{-c} overrides @samp{-o}
and @samp{-S}. @samp{-c} has no effect when testing or listing.
@item -d @item -d
@itemx --decompress @itemx --decompress
Decompress the specified files. If a file does not exist or can't be Decompress the files specified. If a file does not exist or can't be
opened, minilzip continues decompressing the rest of the files. If a file opened, minilzip continues decompressing the rest of the files. If a file
fails to decompress, or is a terminal, minilzip exits immediately without fails to decompress, or is a terminal, minilzip exits immediately without
decompressing the rest of the files. decompressing the rest of the files.
@item -f @item -f
@itemx --force @itemx --force
Force overwrite of output files. Force overwrite of output files.
@item -F @item -F
@itemx --recompress @itemx --recompress
skipping to change at line 695 skipping to change at line 746
@item -m @var{bytes} @item -m @var{bytes}
@itemx --match-length=@var{bytes} @itemx --match-length=@var{bytes}
When compressing, set the match length limit in bytes. After a match 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 this long is found, the search is finished. Valid values range from 5 to
273. Larger values usually give better compression ratios but longer 273. Larger values usually give better compression ratios but longer
compression times. compression times.
@item -o @var{file} @item -o @var{file}
@itemx --output=@var{file} @itemx --output=@var{file}
When reading from standard input and @samp{--stdout} has not been If @samp{-c} has not been also specified, write the (de)compressed output to
specified, use @samp{@var{file}} as the virtual name of the uncompressed @samp{@var{file}}; keep input files unchanged. If compressing several files,
file. This produces a file named @samp{@var{file}} when decompressing, each file is compressed independently. (The output consists of a sequence of
or a file named @samp{@var{file}.lz} when compressing. A second independently compressed members). This option (or @samp{-c}) is needed when
@samp{.lz} extension is not added if @samp{@var{file}} already ends in reading from a named pipe (fifo) or from a device. @samp{-o -} is equivalent
@samp{.lz} or @samp{.tlz}. When compressing and splitting the output in to @samp{-c}. @samp{-o} has no effect when testing or listing.
volumes, several files named @samp{@var{file}00001.lz},
@samp{@var{file}00002.lz}, etc, are created. When compressing and splitting the output in volumes, @samp{@var{file}} is
used as a prefix, and several files named @samp{@var{file}00001.lz},
@samp{@var{file}00002.lz}, etc, are created. In this case, only one input
file is allowed.
@item -q @item -q
@itemx --quiet @itemx --quiet
Quiet operation. Suppress all messages. Quiet operation. Suppress all messages.
@item -s @var{bytes} @item -s @var{bytes}
@itemx --dictionary-size=@var{bytes} @itemx --dictionary-size=@var{bytes}
When compressing, set the dictionary size limit in bytes. Minilzip will use When compressing, set the dictionary size limit in bytes. Minilzip will use
for each file the largest dictionary size that does not exceed neither for each file the largest dictionary size that does not exceed neither
the file size nor this limit. Valid values range from @w{4 KiB} to the file size nor this limit. Valid values range from @w{4 KiB} to
@w{512 MiB}. Values 12 to 29 are interpreted as powers of two, meaning @w{512 MiB}. Values 12 to 29 are interpreted as powers of two, meaning
2^12 to 2^29 bytes. Dictionary sizes are quantized so that they can be 2^12 to 2^29 bytes. Dictionary sizes are quantized so that they can be
coded in just one byte (@pxref{coded-dict-size}). If the specified size coded in just one byte (@pxref{coded-dict-size}). If the size specified
does not match one of the valid sizes, it will be rounded upwards by does not match one of the valid sizes, it will be rounded upwards by
adding up to @w{(@var{bytes} / 8)} to it. adding up to @w{(@var{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 large
as possible, but keep in mind that the decompression memory requirement as possible, but keep in mind that the decompression memory requirement
is affected at compression time by the choice of dictionary size limit. is affected at compression time by the choice of dictionary size limit.
@item -S @var{bytes} @item -S @var{bytes}
@itemx --volume-size=@var{bytes} @itemx --volume-size=@var{bytes}
When compressing, split the compressed output into several volume files When compressing, and @samp{-c} has not been also specified, split the
with names @samp{original_name00001.lz}, @samp{original_name00002.lz}, compressed output into several volume files with names
etc, and set the volume size limit to @var{bytes}. Input files are kept @samp{original_name00001.lz}, @samp{original_name00002.lz}, etc, and set the
unchanged. Each volume is a complete, maybe multimember, lzip file. A volume size limit to @var{bytes}. Input files are kept unchanged. Each
small volume size may degrade compression ratio, so use it only when volume is a complete, maybe multimember, lzip file. A small volume size may
needed. Valid values range from @w{100 kB} to @w{4 EiB}. degrade compression ratio, so use it only when needed. Valid values range
from @w{100 kB} to @w{4 EiB}.
@item -t @item -t
@itemx --test @itemx --test
Check integrity of the specified files, but don't decompress them. This Check integrity of the files specified, but don't decompress them. This
really performs a trial decompression and throws away the result. Use it really performs a trial decompression and throws away the result. Use it
together with @samp{-v} to see information about the files. If a file together with @samp{-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 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 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 verbosity level 1 or higher if any file fails the test when testing
multiple files. multiple files.
@item -v @item -v
@itemx --verbose @itemx --verbose
Verbose mode.@* Verbose mode.@*
skipping to change at line 760 skipping to change at line 815
@item -0 .. -9 @item -0 .. -9
Compression level. Set the compression parameters (dictionary size and Compression level. Set the compression parameters (dictionary size and
match length limit) as shown in the table below. The default compression match length limit) as shown in the table below. The default compression
level is @samp{-6}, equivalent to @w{@samp{-s8MiB -m36}}. Note that level is @samp{-6}, equivalent to @w{@samp{-s8MiB -m36}}. Note that
@samp{-9} can be much slower than @samp{-0}. These options have no @samp{-9} can be much slower than @samp{-0}. These options have no
effect when decompressing or testing. effect when decompressing or testing.
The bidimensional parameter space of LZMA can't be mapped to a linear 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, scale optimal for all files. If your files are large, very repetitive,
etc, you may need to use the @samp{--dictionary-size} and etc, you may need to use the options @samp{--dictionary-size} and
@samp{--match-length} options directly to achieve optimal performance. @samp{--match-length} directly to achieve optimal performance.
If several compression levels or @samp{-s} or @samp{-m} options are If several compression levels or @samp{-s} or @samp{-m} options are
given, the last setting is used. For example @w{@samp{-9 -s64MiB}} is given, the last setting is used. For example @w{@samp{-9 -s64MiB}} is
equivalent to @w{@samp{-s64MiB -m273}} equivalent to @w{@samp{-s64MiB -m273}}
@multitable {Level} {Dictionary size (-s)} {Match length limit (-m)} @multitable {Level} {Dictionary size (-s)} {Match length limit (-m)}
@item Level @tab Dictionary size (-s) @tab Match length limit (-m) @item Level @tab Dictionary size (-s) @tab Match length limit (-m)
@item -0 @tab 64 KiB @tab 16 bytes @item -0 @tab 64 KiB @tab 16 bytes
@item -1 @tab 1 MiB @tab 5 bytes @item -1 @tab 1 MiB @tab 5 bytes
@item -2 @tab 1.5 MiB @tab 6 bytes @item -2 @tab 1.5 MiB @tab 6 bytes
skipping to change at line 826 skipping to change at line 881
@node Data format @node Data format
@chapter Data format @chapter Data format
@cindex data format @cindex 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
@sp 1 @sp 1
In the diagram below, a box like this: In the diagram below, a box like this:
@verbatim @verbatim
+---+ +---+
| | <-- the vertical bars might be missing | | <-- the vertical bars might be missing
+---+ +---+
@end verbatim @end verbatim
represents one byte; a box like this: represents one byte; a box like this:
@verbatim @verbatim
+==============+ +==============+
| | | |
+==============+ +==============+
@end verbatim @end verbatim
represents a variable number of bytes. represents a variable number of bytes.
@sp 1 @sp 1
A lzip data stream consists of a series of "members" (compressed data sets). 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 The members simply appear one after another in the data stream, with no
additional information before, between, or after them. additional information before, between, or after them.
Each member has the following structure: Each member has the following structure:
@verbatim @verbatim
+--+--+--+--+----+----+=============+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +--+--+--+--+----+----+=============+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| ID string | VN | DS | LZMA stream | CRC32 | Data size | Member size | | ID string | VN | DS | LZMA stream | CRC32 | Data size | Member size |
+--+--+--+--+----+----+=============+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +--+--+--+--+----+----+=============+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
@end verbatim @end verbatim
All multibyte values are stored in little endian order. All multibyte values are stored in little endian order.
@table @samp @table @samp
@item ID string (the "magic" bytes) @item ID string (the "magic" bytes)
A four byte string, identifying the lzip format, with the value "LZIP" A four byte string, identifying the lzip format, with the value "LZIP"
(0x4C, 0x5A, 0x49, 0x50). (0x4C, 0x5A, 0x49, 0x50).
@item VN (version number, 1 byte) @item VN (version number, 1 byte)
Just in case something needs to be modified in the future. 1 for now. Just in case something needs to be modified in the future. 1 for now.
@anchor{coded-dict-size} @anchor{coded-dict-size}
@item DS (coded dictionary size, 1 byte) @item DS (coded dictionary size, 1 byte)
The dictionary size is calculated by taking a power of 2 (the base size) 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 the base and subtracting from it a fraction between 0/16 and 7/16 of the base size.@*
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.
@item LZMA stream @item 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
values for encoder properties. for encoder properties.
@ifnothtml @ifnothtml
@xref{Stream format,,,lzip}, @xref{Stream format,,,lzip},
@end ifnothtml @end ifnothtml
@ifhtml @ifhtml
See See
@uref{http://www.nongnu.org/lzip/manual/lzip_manual.html#Stream-format,,Stream f ormat} @uref{http://www.nongnu.org/lzip/manual/lzip_manual.html#Stream-format,,Stream f ormat}
@end ifhtml @end ifhtml
for a complete description.@* for a complete description.@*
Lzip only uses the LZMA marker @samp{2} ("End Of Stream" marker). Lzlib Lzip only uses the LZMA marker @samp{2} ("End Of Stream" marker). Lzlib
also uses the LZMA marker @samp{3} ("Sync Flush" marker). also uses the LZMA marker @samp{3} ("Sync Flush" marker). @xref{sync_flush}.
@item CRC32 (4 bytes) @item CRC32 (4 bytes)
CRC of the uncompressed original data. Cyclic Redundancy Check (CRC) of the uncompressed original data.
@item Data size (8 bytes) @item Data size (8 bytes)
Size of the uncompressed original data. Size of the uncompressed original data.
@item Member size (8 bytes) @item Member size (8 bytes)
Total size of the member, including header and trailer. This field acts Total size of the member, including header and trailer. This field acts
as a distributed index, allows the verification of stream integrity, and as a distributed index, allows the verification of stream integrity, and
facilitates safe recovery of undamaged members from multimember files. facilitates safe recovery of undamaged members from multimember files.
@end table @end table
@node Examples @node Examples
@chapter A small tutorial with examples @chapter A small tutorial with examples
@cindex examples @cindex 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 @samp{bbexample.c} and
decompress. See the file @samp{bbexample.c} in the source distribution @samp{ffexample.c} from the source distribution of lzlib.
for an example of how buffer-to-buffer compression/decompression can be
implemented using lzlib.
Note that lzlib's interface is symmetrical. That is, the code for normal Note that the interface of lzlib is symmetrical. That is, the code for
compression and decompression is identical except because one calls normal compression and decompression is identical except because one calls
LZ_compress* functions while the other calls LZ_decompress* functions. LZ_compress* functions while the other calls LZ_decompress* functions.
@sp 1 @menu
@noindent * Buffer compression:: Buffer-to-buffer single-member compression
Example 1: Normal compression (@var{member_size} > total output). * Buffer decompression:: Buffer-to-buffer decompression
* File compression:: File-to-file single-member compression
* File decompression:: File-to-file decompression
* File compression mm:: File-to-file multimember compression
* Skipping data errors:: Decompression with automatic resynchronization
@end menu
@example @node Buffer compression
1) LZ_compress_open @section Buffer compression
2) LZ_compress_write @cindex buffer compression
3) if no more data to write, call LZ_compress_finish
4) LZ_compress_read
5) go back to step 2 until LZ_compress_finished returns 1
6) LZ_compress_close
@end example
@sp 1 Buffer-to-buffer single-member compression
@noindent @w{(@var{member_size} > total output)}.
Example 2: Normal compression using LZ_compress_write_size.
@example @verbatim
1) LZ_compress_open /* Compresses 'insize' bytes from 'inbuf' to 'outbuf'.
2) go to step 5 if LZ_compress_write_size returns 0 Returns the size of the compressed data in '*outlenp'.
3) LZ_compress_write In case of error, or if 'outsize' is too small, returns false and does
4) if no more data to write, call LZ_compress_finish not modify '*outlenp'.
5) LZ_compress_read */
6) go back to step 2 until LZ_compress_finished returns 1 bool bbcompress( const uint8_t * const inbuf, const int insize,
7) LZ_compress_close const int dictionary_size, const int match_len_limit,
@end example uint8_t * const outbuf, const int outsize,
int * const outlenp )
{
int inpos = 0, outpos = 0;
bool error = false;
struct LZ_Encoder * const encoder =
LZ_compress_open( dictionary_size, match_len_limit, INT64_MAX );
if( !encoder || LZ_compress_errno( encoder ) != LZ_ok )
{ LZ_compress_close( encoder ); return false; }
while( true )
{
int ret = LZ_compress_write( encoder, inbuf + inpos, insize - inpos );
if( ret < 0 ) { error = true; break; }
inpos += ret;
if( inpos >= insize ) LZ_compress_finish( encoder );
ret = LZ_compress_read( encoder, outbuf + outpos, outsize - outpos );
if( ret < 0 ) { error = true; break; }
outpos += ret;
if( LZ_compress_finished( encoder ) == 1 ) break;
if( outpos >= outsize ) { error = true; break; }
}
if( LZ_compress_close( encoder ) < 0 ) error = true;
if( error ) return false;
*outlenp = outpos;
return true;
}
@end verbatim
@sp 1 @node Buffer decompression
@noindent @section Buffer decompression
Example 3: Decompression. @cindex buffer decompression
@example Buffer-to-buffer decompression.
1) LZ_decompress_open
2) LZ_decompress_write
3) if no more data to write, call LZ_decompress_finish
4) LZ_decompress_read
5) go back to step 2 until LZ_decompress_finished returns 1
6) LZ_decompress_close
@end example
@sp 1 @verbatim
@noindent /* Decompresses 'insize' bytes from 'inbuf' to 'outbuf'.
Example 4: Decompression using LZ_decompress_write_size. Returns the size of the decompressed data in '*outlenp'.
In case of error, or if 'outsize' is too small, returns false and does
not modify '*outlenp'.
*/
bool bbdecompress( const uint8_t * const inbuf, const int insize,
uint8_t * const outbuf, const int outsize,
int * const outlenp )
{
int inpos = 0, outpos = 0;
bool error = false;
struct LZ_Decoder * const decoder = LZ_decompress_open();
if( !decoder || LZ_decompress_errno( decoder ) != LZ_ok )
{ LZ_decompress_close( decoder ); return false; }
while( true )
{
int ret = LZ_decompress_write( decoder, inbuf + inpos, insize - inpos );
if( ret < 0 ) { error = true; break; }
inpos += ret;
if( inpos >= insize ) LZ_decompress_finish( decoder );
ret = LZ_decompress_read( decoder, outbuf + outpos, outsize - outpos );
if( ret < 0 ) { error = true; break; }
outpos += ret;
if( LZ_decompress_finished( decoder ) == 1 ) break;
if( outpos >= outsize ) { error = true; break; }
}
if( LZ_decompress_close( decoder ) < 0 ) error = true;
if( error ) return false;
*outlenp = outpos;
return true;
}
@end verbatim
@example @node File compression
1) LZ_decompress_open @section File compression
2) go to step 5 if LZ_decompress_write_size returns 0 @cindex file compression
3) LZ_decompress_write
4) if no more data to write, call LZ_decompress_finish
5) LZ_decompress_read
5a) optionally, if LZ_decompress_member_finished returns 1, read
final values for member with LZ_decompress_data_crc, etc.
6) go back to step 2 until LZ_decompress_finished returns 1
7) LZ_decompress_close
@end example
@sp 1 File-to-file compression using LZ_compress_write_size.
@noindent
Example 5: Multimember compression (@var{member_size} < total output).
@example @verbatim
1) LZ_compress_open int ffcompress( struct LZ_Encoder * const encoder,
2) go to step 5 if LZ_compress_write_size returns 0 FILE * const infile, FILE * const outfile )
3) LZ_compress_write {
4) if no more data to write, call LZ_compress_finish enum { buffer_size = 16384 };
5) LZ_compress_read uint8_t buffer[buffer_size];
6) go back to step 2 until LZ_compress_member_finished returns 1 while( true )
7) go to step 10 if LZ_compress_finished() returns 1 {
8) LZ_compress_restart_member int len, ret;
9) go back to step 2 int size = min( buffer_size, LZ_compress_write_size( encoder ) );
10) LZ_compress_close if( size > 0 )
@end example {
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;
}
@end verbatim
@sp 1 @node File decompression
@noindent @section File decompression
Example 6: Multimember compression (user-restarted members). @cindex file decompression
@example File-to-file decompression using LZ_decompress_write_size.
1) LZ_compress_open (with @var{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
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
@end example
@sp 1 @verbatim
@noindent int ffdecompress( struct LZ_Decoder * const decoder,
Example 7: Decompression with automatic removal of leading data. 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;
}
@end verbatim
@example @node File compression mm
1) LZ_decompress_open @section File-to-file multimember compression
2) LZ_decompress_sync_to_member @cindex multimember compression
3) go to step 6 if LZ_decompress_write_size returns 0
4) LZ_decompress_write Example 1: Multimember compression with members of fixed size
5) if no more data to write, call LZ_decompress_finish @w{(@var{member_size} < total output)}.
6) LZ_decompress_read
7) go back to step 3 until LZ_decompress_finished returns 1 @verbatim
8) LZ_decompress_close int ffmmcompress( FILE * const infile, FILE * const outfile )
@end example {
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;
}
@end verbatim
@sp 1 @sp 1
@noindent @noindent
Example 8: Streamed decompression with automatic resynchronization to Example 2: Multimember compression (user-restarted members).
next member in case of data error. (Call LZ_compress_open with @var{member_size} > largest member).
@example @verbatim
1) LZ_decompress_open /* Compresses 'infile' to 'outfile' as a multimember stream with one member
2) go to step 5 if LZ_decompress_write_size returns 0 for each line of text terminated by a newline character or by EOF.
3) LZ_decompress_write Returns 0 if success, 1 if error.
4) if no more data to write, call LZ_decompress_finish */
5) if LZ_decompress_read produces LZ_header_error or LZ_data_error, int fflfcompress( struct LZ_Encoder * const encoder,
call LZ_decompress_sync_to_member FILE * const infile, FILE * const outfile )
6) go back to step 2 until LZ_decompress_finished returns 1 {
7) LZ_decompress_close enum { buffer_size = 16384 };
@end example 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;
}
@end verbatim
@node Skipping data errors
@section Skipping data errors
@cindex skipping data errors
@verbatim
/* 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;
}
@end verbatim
@node Problems @node Problems
@chapter Reporting bugs @chapter Reporting bugs
@cindex bugs @cindex bugs
@cindex getting help @cindex getting help
There are probably bugs in lzlib. There are certainly errors and There are probably bugs in lzlib. There are certainly errors and
omissions in this manual. If you report them, they will get fixed. If omissions in this manual. If you report them, they will get fixed. If
you don't, no one will ever know about them and they will remain unfixed you don't, no one will ever know about them and they will remain unfixed
for all eternity, if not longer. for all 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
@email{lzip-bug@@nongnu.org}. Include the version number, which you can @email{lzip-bug@@nongnu.org}. Include the version number, which you can
find by running @w{@code{minilzip --version}} or in find by running @w{@samp{minilzip --version}} or in
@samp{LZ_version_string} from @samp{lzlib.h}. @samp{LZ_version_string} from @samp{lzlib.h}.
@node Concept index @node Concept index
@unnumbered Concept index @unnumbered Concept index
@printindex cp @printindex cp
@bye @bye
 End of changes. 86 change blocks. 
291 lines changed or deleted 518 lines changed or added

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