lzip/lzlib
1
0
Fork 0
Code Issues Activity

Adding upstream version 0.8.

Browse source 
Signed-off-by: Daniel Baumann <daniel@debian.org>
This commit is contained in:
Daniel Baumann 2025-02-20 16:18:54 +01:00
parent 37258e3901
commit f78fedc24f
Signed by: daniel
GPG key ID: FBB4F0E80A80222F
23 changed files with 1833 additions and 1235 deletions
Download patch file Download diff file Expand all files Collapse all files

284
doc/lzlib.texinfo
View file

@ -5,8 +5,8 @@
@finalout
@c %**end of header
@set UPDATED 20 October 2009
@set VERSION 0.7
@set UPDATED 17 January 2010
@set VERSION 0.8
@dircategory Data Compression
@direntry
@ -35,9 +35,11 @@ This manual is for Lzlib (version @value{VERSION}, @value{UPDATED}).
* Introduction:: Purpose and features of Lzlib
* Library Version:: Checking library version
* Buffering:: Sizes of Lzlib's buffers
* Parameter Limits:: Min / max values for some parameters
* Compression Functions:: Descriptions of the compression functions
* Decompression Functions:: Descriptions of the decompression functions
* Error Codes:: Meaning of codes returned by functions
* Error Messages:: Error messages corresponding to error codes
* Data Format:: Detailed format of the compressed data
* Examples:: A small tutorial with examples
* Problems:: Reporting bugs
@ -45,7 +47,7 @@ This manual is for Lzlib (version @value{VERSION}, @value{UPDATED}).
@end menu
@sp 1
Copyright @copyright{} 2009 Antonio Diaz Diaz.
Copyright @copyright{} 2009, 2010 Antonio Diaz Diaz.
This manual is free documentation: you have unlimited permission
to copy, distribute and modify it.
@ -139,11 +141,43 @@ is larger.
@item Output decompression buffer. Read from by the
@samp{LZ_decompress_read} function. Its size is the dictionary size set
with the @samp{LZ_decompress_open} function or 64KiB, whichever is
larger.
in the header of the member currently being decompressed or 64KiB,
whichever is larger.
@end itemize
@node Parameter Limits
@chapter Parameter Limits
@cindex parameter limits
These functions provide minimum and maximum values for some parameters.
Current values are shown in square brackets.
@deftypefun int LZ_min_dictionary_bits ( void )
Returns the base 2 logarithm of the smallest valid dictionary size [12].
@end deftypefun
@deftypefun int LZ_min_dictionary_size ( void )
Returns the smallest valid dictionary size [4KiB].
@end deftypefun
@deftypefun int LZ_max_dictionary_bits ( void )
Returns the base 2 logarithm of the largest valid dictionary size [29].
@end deftypefun
@deftypefun int LZ_max_dictionary_size ( void )
Returns the largest valid dictionary size [512MiB].
@end deftypefun
@deftypefun int LZ_min_match_len_limit ( void )
Returns the smallest valid match length limit [5].
@end deftypefun
@deftypefun int LZ_max_match_len_limit ( void )
Returns the largest valid match length limit [273].
@end deftypefun
@node Compression Functions
@chapter Compression Functions
@cindex compression functions
@ -153,10 +187,11 @@ them return -1, except @samp{LZ_compress_open} whose return value must
be verified by calling @samp{LZ_compress_errno} before using it.
@deftypefun {void *} LZ_compress_open ( const int @var{dictionary_size}, const int @var{match_len_limit}, const long long @var{member_size} )
@deftypefun {struct LZ_Encoder *} LZ_compress_open ( const int @var{dictionary_size}, const int @var{match_len_limit}, const long long @var{member_size} )
Initializes the internal stream state for compression and returns a
pointer that can only be used as the @var{encoder} argument for the
other LZ_compress functions.
other LZ_compress functions, or a null pointer if the encoder could not
be allocated.
The returned pointer must be verified by calling
@samp{LZ_compress_errno} before using it. If @samp{LZ_compress_errno}
@ -180,15 +215,7 @@ for example LLONG_MAX.
@end deftypefun
@deftypefun int LZ_compress_restart_member ( void * const @var{encoder}, const long long @var{member_size} )
Use this function to start a new member, in a multimember data stream.
Call this function only after @samp{LZ_compress_member_finished}
indicates that the current member has been fully read (with the
@samp{LZ_compress_read} function).
@end deftypefun
@deftypefun int LZ_compress_close ( void * const @var{encoder} )
@deftypefun int LZ_compress_close ( struct LZ_Encoder * const @var{encoder} )
Frees all dynamically allocated data structures for this stream. This
function discards any unprocessed input and does not flush any pending
output. After a call to @samp{LZ_compress_close}, @var{encoder} can no
@ -196,13 +223,24 @@ more be used as an argument to any LZ_compress function.
@end deftypefun
@deftypefun int LZ_compress_finish ( void * const @var{encoder} )
Use this function to tell @samp{lzlib} that all the data for this stream
@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
has already been written (with the @samp{LZ_compress_write} function).
After all the produced compressed data has been read with
@samp{LZ_compress_read} and @samp{LZ_compress_member_finished} returns
1, a new member can be started with @samp{LZ_compress_restart_member}.
@end deftypefun
@deftypefun int LZ_compress_sync_flush ( void * const @var{encoder} )
@deftypefun int LZ_compress_restart_member ( struct LZ_Encoder * const @var{encoder}, const long long @var{member_size} )
Use this function to start a new member, in a multimember data stream.
Call this function only after @samp{LZ_compress_member_finished}
indicates that the current member has been fully read (with the
@samp{LZ_compress_read} function).
@end deftypefun
@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
data already written with the @samp{LZ_compress_write} function.
Repeated use of @samp{LZ_compress_sync_flush} may degrade compression
@ -210,7 +248,7 @@ ratio, so use it only when needed.
@end deftypefun
@deftypefun int LZ_compress_read ( void * const @var{encoder}, uint8_t * const @var{buffer}, const int @var{size} )
@deftypefun int LZ_compress_read ( struct LZ_Encoder * const @var{encoder}, uint8_t * const @var{buffer}, const int @var{size} )
The @samp{LZ_compress_read} function reads up to @var{size} bytes from
the stream pointed to by @var{encoder}, storing the results in
@var{buffer}.
@ -223,7 +261,7 @@ in the stream or if more bytes have to be yet written with the
@end deftypefun
@deftypefun int LZ_compress_write ( void * const @var{encoder}, uint8_t * const @var{buffer}, const int @var{size} )
@deftypefun int LZ_compress_write ( struct LZ_Encoder * const @var{encoder}, uint8_t * const @var{buffer}, const int @var{size} )
The @samp{LZ_compress_write} function writes up to @var{size} bytes from
@var{buffer} to the stream pointed to by @var{encoder}.
@ -233,7 +271,7 @@ not an error.
@end deftypefun
@deftypefun int LZ_compress_write_size ( void * 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
bytes that can be inmediately written through the @samp{LZ_compress_write}
function.
@ -243,42 +281,42 @@ accept a @var{size} up to the returned number of bytes.
@end deftypefun
@deftypefun {enum LZ_errno} LZ_compress_errno ( void * const @var{encoder} )
@deftypefun {enum LZ_Errno} LZ_compress_errno ( struct LZ_Encoder * const @var{encoder} )
Returns the current error code for @var{encoder} (@pxref{Error Codes})
@end deftypefun
@deftypefun int LZ_compress_finished ( void * const @var{encoder} )
@deftypefun int LZ_compress_finished ( struct LZ_Encoder * const @var{encoder} )
Returns 1 if all the data has been read and @samp{LZ_compress_close} can
be safely called. Otherwise it returns 0.
@end deftypefun
@deftypefun int LZ_compress_member_finished ( void * const @var{encoder} )
@deftypefun int LZ_compress_member_finished ( struct LZ_Encoder * const @var{encoder} )
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.
Otherwise it returns 0.
@end deftypefun
@deftypefun {long long} LZ_compress_data_position ( void * const @var{encoder} )
@deftypefun {long long} LZ_compress_data_position ( struct LZ_Encoder * const @var{encoder} )
Returns the number of input bytes already compressed in the current
member.
@end deftypefun
@deftypefun {long long} LZ_compress_member_position ( void * const @var{encoder} )
@deftypefun {long long} LZ_compress_member_position ( struct LZ_Encoder * const @var{encoder} )
Returns the number of compressed bytes already produced, but perhaps not
yet read, in the current member.
@end deftypefun
@deftypefun {long long} LZ_compress_total_in_size ( void * const @var{encoder} )
@deftypefun {long long} LZ_compress_total_in_size ( struct LZ_Encoder * const @var{encoder} )
Returns the total number of input bytes already compressed.
@end deftypefun
@deftypefun {long long} LZ_compress_total_out_size ( void * const @var{encoder} )
@deftypefun {long long} LZ_compress_total_out_size ( struct LZ_Encoder * const @var{encoder} )
Returns the total number of compressed bytes already produced, but
perhaps not yet read.
@end deftypefun
@ -293,10 +331,11 @@ of them return -1, except @samp{LZ_decompress_open} whose return value
must be verified by calling @samp{LZ_decompress_errno} before using it.
@deftypefun {void *} LZ_decompress_open ( void )
@deftypefun {struct LZ_Decoder *} LZ_decompress_open ( void )
Initializes the internal stream state for decompression and returns a
pointer that can only be used as the @var{decoder} argument for the
other LZ_decompress functions.
other LZ_decompress functions, or a null pointer if the decoder could
not be allocated.
The returned pointer must be verified by calling
@samp{LZ_decompress_errno} before using it. If
@ -306,7 +345,7 @@ pointer must not be used and should be freed with
@end deftypefun
@deftypefun int LZ_decompress_close ( void * const @var{decoder} )
@deftypefun int LZ_decompress_close ( struct LZ_Decoder * const @var{decoder} )
Frees all dynamically allocated data structures for this stream. This
function discards any unprocessed input and does not flush any pending
output. After a call to @samp{LZ_decompress_close}, @var{decoder} can no
@ -314,13 +353,34 @@ more be used as an argument to any LZ_decompress function.
@end deftypefun
@deftypefun int LZ_decompress_finish ( void * 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
has already been written (with the @samp{LZ_decompress_write} function).
@end deftypefun
@deftypefun int LZ_decompress_read ( void * const @var{decoder}, uint8_t * const @var{buffer}, const int @var{size} )
@deftypefun int LZ_decompress_reset ( struct LZ_Decoder * const @var{decoder} )
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
internal buffers is discarded. Position counters are set to 0.
@end deftypefun
@deftypefun int LZ_decompress_sync_to_member ( struct LZ_Decoder * const @var{decoder} )
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.
After a successful call to @samp{LZ_decompress_sync_to_member}, data
written with @samp{LZ_decompress_write} will be consumed and
@samp{LZ_decompress_read} will return 0 until a header is found.
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
data error. If the decoder is already at the beginning of a member, this
function does nothing.
@end deftypefun
@deftypefun int LZ_decompress_read ( struct LZ_Decoder * const @var{decoder}, uint8_t * const @var{buffer}, const int @var{size} )
The @samp{LZ_decompress_read} function reads up to @var{size} bytes from
the stream pointed to by @var{decoder}, storing the results in
@var{buffer}.
@ -333,7 +393,7 @@ in the stream or if more bytes have to be yet written with the
@end deftypefun
@deftypefun int LZ_decompress_write ( void * const @var{decoder}, uint8_t * const @var{buffer}, const int @var{size} )
@deftypefun int LZ_decompress_write ( struct LZ_Decoder * const @var{decoder}, uint8_t * const @var{buffer}, const int @var{size} )
The @samp{LZ_decompress_write} function writes up to @var{size} bytes from
@var{buffer} to the stream pointed to by @var{decoder}.
@ -343,35 +403,45 @@ not an error.
@end deftypefun
@deftypefun {enum LZ_errno} LZ_decompress_errno ( void * const @var{decoder} )
@deftypefun int LZ_decompress_write_size ( struct LZ_Decoder * const @var{decoder} )
The @samp{LZ_decompress_write_size} function returns the maximum number
of bytes that can be inmediately written through the
@samp{LZ_decompress_write} function.
It is guaranteed that an inmediate call to @samp{LZ_decompress_write}
will accept a @var{size} up to the returned number of bytes.
@end deftypefun
@deftypefun {enum LZ_Errno} LZ_decompress_errno ( struct LZ_Decoder * const @var{decoder} )
Returns the current error code for @var{decoder} (@pxref{Error Codes})
@end deftypefun
@deftypefun int LZ_decompress_finished ( void * const @var{decoder} )
@deftypefun int LZ_decompress_finished ( struct LZ_Decoder * const @var{decoder} )
Returns 1 if all the data has been read and @samp{LZ_decompress_close}
can be safely called. Otherwise it returns 0.
@end deftypefun
@deftypefun {long long} LZ_decompress_data_position ( void * const @var{decoder} )
@deftypefun {long long} LZ_decompress_data_position ( struct LZ_Decoder * const @var{decoder} )
Returns the number of decompressed bytes already produced, but perhaps
not yet read, in the current member.
@end deftypefun
@deftypefun {long long} LZ_decompress_member_position ( void * const @var{decoder} )
@deftypefun {long long} LZ_decompress_member_position ( struct LZ_Decoder * const @var{decoder} )
Returns the number of input bytes already decompressed in the current
member.
@end deftypefun
@deftypefun {long long} LZ_decompress_total_in_size ( void * const @var{decoder} )
@deftypefun {long long} LZ_decompress_total_in_size ( struct LZ_Decoder * const @var{decoder} )
Returns the total number of input bytes already decompressed.
@end deftypefun
@deftypefun {long long} LZ_decompress_total_out_size ( void * const @var{decoder} )
@deftypefun {long long} LZ_decompress_total_out_size ( struct LZ_Decoder * const @var{decoder} )
Returns the total number of decompressed bytes already produced, but
perhaps not yet read.
@end deftypefun
@ -395,46 +465,61 @@ examine @samp{LZ_(de)compress_errno}.
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
error.
@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
invalid.
@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
because its capacity is full.
@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
@samp{LZ_compress_restart_member} was called before
@samp{LZ_compress_member_finished} indicates that the current member is
finished.
@end deftypevr
@deftypevr Constant {enum LZ_errno} LZ_header_error
@deftypevr Constant {enum LZ_Errno} LZ_header_error
Reading of member header failed. If this happens at the end of the data
stream it may indicate trailing garbage.
@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.
@end deftypevr
@deftypevr Constant {enum LZ_errno} LZ_data_error
@deftypevr Constant {enum LZ_Errno} LZ_data_error
The data stream is corrupt.
@end deftypevr
@deftypevr Constant {enum LZ_errno} LZ_library_error
@deftypevr Constant {enum LZ_Errno} LZ_library_error
A bug was detected in the library. Please, report it (@pxref{Problems}).
@end deftypevr
@node Error Messages
@chapter Error Messages
@cindex error messages
@deftypefun {const char *} LZ_strerror ( const enum LZ_Errno @var{lz_errno} )
Returns the standard error message for a given error code. The messages
are fairly short; there are no multi-line messages or embedded newlines.
This function makes it easy for your program to report informative error
messages about the failure of a library call.
The value of @var{lz_errno} normally comes from a call to
@samp{LZ_(de)compress_errno}.
@end deftypefun
@node Data Format
@chapter Data Format
@cindex data format
@ -528,7 +613,22 @@ Example 1: Normal compression (@var{member_size} > total output).
@sp 1
@noindent
Example 2: Decompression.
Example 2: Normal compression using LZ_compress_write_size.
@example
1) LZ_compress_open
2) go to step 5 if LZ_compress_write_size returns 0
3) LZ_compress_write
4) if no more data to write, call LZ_compress_finish
5) LZ_compress_read
6) go back to step 2 until LZ_compress_finished returns 1
7) LZ_compress_close
@end example
@sp 1
@noindent
Example 3: Decompression.
@example
1) LZ_decompress_open
@ -544,19 +644,87 @@ Example 2: Decompression.
@sp 1
@noindent
Example 3: Multimember compression (@var{member_size} < total output).
Example 4: Decompression using LZ_decompress_write_size.
@example
1) LZ_decompress_open
2) go to step 5 if LZ_decompress_write_size returns 0
3) LZ_decompress_write
4) if no more data to write, call LZ_decompress_finish
5) LZ_decompress_read
6) go back to step 2 until LZ_decompress_finished returns 1
7) LZ_decompress_close
@end example
@sp 1
@noindent
Example 5: Multimember compression (@var{member_size} < total output).
@example
1) LZ_compress_open
2) go to step 5 if LZ_compress_write_size returns 0
3) LZ_compress_write
4) if no more data to write, call LZ_compress_finish
5) LZ_compress_read
6) go back to step 2 until LZ_compress_member_finished returns 1
7) go to step 10 if LZ_compress_finished() returns 1
8) LZ_compress_restart_member
9) go back to step 2
10) LZ_compress_close
@end example
@sp 1
@noindent
Example 6: Multimember compression (user-restarted members).
@example
1) LZ_compress_open
2) LZ_compress_write
3) LZ_compress_read
4) go back to step 2 until LZ_compress_member_finished returns 1
5) LZ_compress_restart_member
6) go back to step 2 until all input data has been written
7) LZ_compress_finish
8) LZ_compress_read
9) go back to step 8 until LZ_compress_finished returns 1
10) LZ_compress_close
4) go back to step 2 until member termination is desired
5) LZ_compress_finish
6) LZ_compress_read
7) go back to step 6 until LZ_compress_member_finished returns 1
8) verify that LZ_compress_finished returns 1
9) go to step 12 if all input data has been written
10) LZ_compress_restart_member
11) go back to step 2
12) LZ_compress_close
@end example
@sp 1
@noindent
Example 7: Decompression with automatic removal of leading garbage.
@example
1) LZ_decompress_open
2) LZ_decompress_sync_to_member
3) go to step 6 if LZ_decompress_write_size returns 0
4) LZ_decompress_write
5) if no more data to write, call LZ_decompress_finish
6) LZ_decompress_read
7) go back to step 3 until LZ_decompress_finished returns 1
8) LZ_decompress_close
@end example
@sp 1
@noindent
Example 8: Streamed decompression with automatic resynchronization to
next member in case of data error.
@example
1) LZ_decompress_open
2) go to step 5 if LZ_decompress_write_size returns 0
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,
call LZ_decompress_sync_to_member
6) go back to step 2 until LZ_decompress_finished returns 1
7) LZ_decompress_close
@end example