lzip/lzlib
1
0
Fork 0
Code Issues Activity

Adding upstream version 1.15~rc1.

Browse source 
Signed-off-by: Daniel Baumann <daniel@debian.org>
This commit is contained in:
Daniel Baumann 2025-02-20 21:34:51 +01:00
parent 57718ee5a9
commit 597f6b9db7
Signed by: daniel
GPG key ID: FBB4F0E80A80222F
27 changed files with 724 additions and 791 deletions
Download patch file Download diff file Expand all files Collapse all files

291
doc/lzlib.info
View file

@ -11,7 +11,7 @@ File: lzlib.info, Node: Top, Next: Introduction, Up: (dir)
Lzlib Manual
************
This manual is for Lzlib (version 1.15-pre2, 16 October 2024).
This manual is for Lzlib (version 1.15-rc1, 19 November 2024).
* Menu:
@ -46,31 +46,6 @@ decompression functions, including integrity checking of the decompressed
data. The compressed data format used by the library is the lzip format.
Lzlib is written in C and is distributed under a 2-clause BSD license.
The lzip file format is designed for data sharing and long-term
archiving, taking into account both data integrity and decoder availability:
* The lzip format provides very safe integrity checking and some data
recovery means. The program lziprecover can repair bit flip errors
(one of the most common forms of data corruption) in lzip files, and
provides data recovery capabilities, including error-checked merging
of damaged copies of a file. *Note Data safety: (lziprecover)Data
safety.
* 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
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
the data from a lzip file long after quantum computers eventually
render LZMA obsolete.
* Additionally the lzip reference implementation is copylefted, which
guarantees that it will remain free forever.
A nice feature of the lzip format is that a corrupt byte is easier to
repair the nearer it is from the beginning of the file. Therefore, with the
help of lziprecover, losing an entire archive just because of a corrupt
byte near the beginning is a thing of the past.
The functions and variables forming the interface of the compression
library are declared in the file 'lzlib.h'. Usage examples of the library
are given in the files 'bbexample.c', 'ffexample.c', and 'minilzip.c' from
@ -117,10 +92,10 @@ about 2 PiB each.
concrete algorithm; it is more like "any algorithm using the LZMA coding
scheme". For example, the option '-0' of lzip uses the scheme in almost 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 way of
finding coding sequences of minimum size than the one currently used by
lzip could be developed, and the resulting sequence could also be coded
using the LZMA coding scheme.
byte if it can't find a match. Inversely, a more elaborate way of finding
coding sequences of minimum size than the one currently used by lzip could
be developed, and the resulting sequence could also be coded using the LZMA
coding scheme.
Lzlib currently implements two variants of the LZMA algorithm: fast
(used by option '-0' of minilzip) and normal (used by all other compression
@ -269,9 +244,8 @@ them return -1 or 0, for signed and unsigned return values respectively,
except 'LZ_compress_open' whose return value must be checked by calling
'LZ_compress_errno' before using it.
-- Function: struct LZ_Encoder * LZ_compress_open ( const int
DICTIONARY_SIZE, const int MATCH_LEN_LIMIT, const unsigned long
long MEMBER_SIZE )
-- Function: LZ_Encoder * LZ_compress_open ( const int DICTIONARY_SIZE,
const int MATCH_LEN_LIMIT, const unsigned long long MEMBER_SIZE )
Initializes the internal stream state for compression and returns a
pointer that can only be used as the ENCODER argument for the other
LZ_compress functions, or a null pointer if the encoder could not be
@ -303,14 +277,14 @@ except 'LZ_compress_open' whose return value must be checked by calling
produced. Values larger than 2 PiB are reduced to 2 PiB to prevent the
uncompressed size of the member from overflowing.
-- Function: int LZ_compress_close ( struct LZ_Encoder * const ENCODER )
-- Function: int LZ_compress_close ( LZ_Encoder * const ENCODER )
Frees all dynamically allocated data structures for this stream. This
function discards any unprocessed input and does not flush any pending
output. After a call to 'LZ_compress_close', ENCODER can no longer be
used as an argument to any LZ_compress function. It is safe to call
'LZ_compress_close' with a null argument.
-- Function: int LZ_compress_finish ( struct LZ_Encoder * const ENCODER )
-- Function: int LZ_compress_finish ( LZ_Encoder * const ENCODER )
Use this function to tell 'lzlib' that all the data for this member
have already been written (with the function 'LZ_compress_write'). It
is safe to call 'LZ_compress_finish' as many times as needed. After
@ -318,27 +292,26 @@ except 'LZ_compress_open' whose return value must be checked by calling
'LZ_compress_member_finished' returns 1, a new member can be started
with 'LZ_compress_restart_member'.
-- Function: int LZ_compress_restart_member ( struct LZ_Encoder * const
ENCODER, const unsigned long long MEMBER_SIZE )
-- Function: int LZ_compress_restart_member ( LZ_Encoder * const ENCODER,
const unsigned long long MEMBER_SIZE )
Use this function to start a new member in a multimember data stream.
Call this function only after 'LZ_compress_member_finished' indicates
that the current member has been fully read (with the function
'LZ_compress_read'). *Note member_size::, for a description of
MEMBER_SIZE.
-- Function: int LZ_compress_sync_flush ( struct LZ_Encoder * const
ENCODER )
-- Function: int LZ_compress_sync_flush ( LZ_Encoder * const ENCODER )
Use this function to make available to 'LZ_compress_read' all the data
already written with the function 'LZ_compress_write'. First call
'LZ_compress_sync_flush'. Then call 'LZ_compress_read' until it
returns 0.
This function writes at least one LZMA marker '3' ("Sync Flush" marker)
This function writes at least one LZMA marker '3' ('Sync Flush' marker)
to the compressed output. Note that the sync flush marker is not
allowed in lzip files; it is a device for interactive communication
between applications using lzlib, but is useless and wasteful in a
file, and is excluded from the media type 'application/lzip'. The LZMA
marker '2' ("End Of Stream" marker) is the only marker allowed in lzip
marker '2' ('End Of Stream' marker) is the only marker allowed in lzip
files. *Note File format::.
Repeated use of 'LZ_compress_sync_flush' may degrade compression
@ -353,8 +326,8 @@ except 'LZ_compress_open' whose return value must be checked by calling
'LZ_compress_member_finished' returns 1, followed by a new call to
'LZ_compress_sync_flush'.
-- Function: int LZ_compress_read ( struct LZ_Encoder * const ENCODER,
uint8_t * const BUFFER, const int SIZE )
-- Function: int LZ_compress_read ( LZ_Encoder * const ENCODER, uint8_t *
const BUFFER, const int SIZE )
Reads up to SIZE bytes from the stream pointed to by ENCODER, storing
the results in BUFFER. If LZ_API_VERSION >= 1012, BUFFER may be a null
pointer, in which case the bytes read are discarded.
@ -365,14 +338,13 @@ except 'LZ_compress_open' whose return value must be checked by calling
'LZ_compress_write'. Note that reading less than SIZE bytes is not an
error.
-- Function: int LZ_compress_write ( struct LZ_Encoder * const ENCODER,
uint8_t * const BUFFER, const int SIZE )
-- Function: int LZ_compress_write ( LZ_Encoder * const ENCODER, uint8_t *
const BUFFER, const int SIZE )
Writes up to SIZE bytes from BUFFER to the stream pointed to by
ENCODER. Returns the number of bytes actually written. This might be
less than SIZE. Note that writing less than SIZE bytes is not an error.
-- Function: int LZ_compress_write_size ( struct LZ_Encoder * const
ENCODER )
-- Function: int LZ_compress_write_size ( LZ_Encoder * const ENCODER )
Returns the maximum number of bytes that can be immediately written
through 'LZ_compress_write'. For efficiency reasons, once the input
buffer is full and 'LZ_compress_write_size' returns 0, almost all the
@ -383,39 +355,37 @@ except 'LZ_compress_open' whose return value must be checked by calling
It is guaranteed that an immediate call to 'LZ_compress_write' will
accept a SIZE up to the returned number of bytes.
-- Function: enum LZ_Errno LZ_compress_errno ( struct LZ_Encoder * const
ENCODER )
-- Function: LZ_Errno LZ_compress_errno ( LZ_Encoder * const ENCODER )
Returns the current error code for ENCODER. *Note Error codes::. It is
safe to call 'LZ_compress_errno' with a null argument, in which case
it returns 'LZ_bad_argument'.
-- Function: int LZ_compress_finished ( struct LZ_Encoder * const ENCODER )
-- Function: int LZ_compress_finished ( LZ_Encoder * const ENCODER )
Returns 1 if all the data have been read and 'LZ_compress_close' can
be safely called. Otherwise it returns 0. 'LZ_compress_finished'
implies 'LZ_compress_member_finished'.
-- Function: int LZ_compress_member_finished ( struct LZ_Encoder * const
ENCODER )
-- Function: int LZ_compress_member_finished ( LZ_Encoder * const ENCODER )
Returns 1 if the current member, in a multimember data stream, has been
fully read and 'LZ_compress_restart_member' can be safely called.
Otherwise it returns 0.
-- Function: unsigned long long LZ_compress_data_position ( struct
LZ_Encoder * const ENCODER )
-- Function: unsigned long long LZ_compress_data_position ( LZ_Encoder *
const ENCODER )
Returns the number of input bytes already compressed in the current
member.
-- Function: unsigned long long LZ_compress_member_position ( struct
LZ_Encoder * const ENCODER )
-- Function: unsigned long long LZ_compress_member_position ( LZ_Encoder *
const ENCODER )
Returns the number of compressed bytes already produced, but perhaps
not yet read, in the current member.
-- Function: unsigned long long LZ_compress_total_in_size ( struct
LZ_Encoder * const ENCODER )
-- Function: unsigned long long LZ_compress_total_in_size ( LZ_Encoder *
const ENCODER )
Returns the total number of input bytes already compressed.
-- Function: unsigned long long LZ_compress_total_out_size ( struct
LZ_Encoder * const ENCODER )
-- Function: unsigned long long LZ_compress_total_out_size ( LZ_Encoder *
const ENCODER )
Returns the total number of compressed bytes already produced, but
perhaps not yet read.
@ -430,7 +400,7 @@ them return -1 or 0, for signed and unsigned return values respectively,
except 'LZ_decompress_open' whose return value must be checked by calling
'LZ_decompress_errno' before using it.
-- Function: struct LZ_Decoder * LZ_decompress_open ( void )
-- Function: LZ_Decoder * LZ_decompress_open ( void )
Initializes the internal stream state for decompression and returns a
pointer that can only be used as the DECODER argument for the other
LZ_decompress functions, or a null pointer if the decoder could not be
@ -441,14 +411,14 @@ except 'LZ_decompress_open' whose return value must be checked by calling
returned pointer must not be used and should be freed with
'LZ_decompress_close' to avoid memory leaks.
-- Function: int LZ_decompress_close ( struct LZ_Decoder * const DECODER )
-- Function: int LZ_decompress_close ( LZ_Decoder * const 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 'LZ_decompress_close', DECODER can no longer
be used as an argument to any LZ_decompress function. It is safe to
call 'LZ_decompress_close' with a null argument.
-- Function: int LZ_decompress_finish ( struct LZ_Decoder * const DECODER )
-- Function: int LZ_decompress_finish ( LZ_Decoder * const DECODER )
Use this function to tell 'lzlib' that all the data for this stream
have already been written (with the function 'LZ_decompress_write').
It is safe to call 'LZ_decompress_finish' as many times as needed. It
@ -456,13 +426,13 @@ except 'LZ_decompress_open' whose return value must be checked by calling
only contains whole members, but not calling it prevents lzlib from
detecting a truncated member.
-- Function: int LZ_decompress_reset ( struct LZ_Decoder * const DECODER )
-- Function: int LZ_decompress_reset ( LZ_Decoder * const DECODER )
Resets the internal state of DECODER as it was just after opening it
with the function 'LZ_decompress_open'. Data stored in the internal
buffers are discarded. Position counters are set to 0.
-- Function: int LZ_decompress_sync_to_member ( struct LZ_Decoder * const
DECODER )
-- Function: int LZ_decompress_sync_to_member ( LZ_Decoder * const DECODER
)
Resets the error state of 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 'LZ_decompress_sync_to_member', data written with
@ -474,8 +444,8 @@ except 'LZ_decompress_open' whose return value must be checked by calling
case of a data error. If the decoder is already at the beginning of a
member, this function does nothing.
-- Function: int LZ_decompress_read ( struct LZ_Decoder * const DECODER,
uint8_t * const BUFFER, const int SIZE )
-- Function: int LZ_decompress_read ( LZ_Decoder * const DECODER, uint8_t
* const BUFFER, const int SIZE )
Reads up to SIZE bytes from the stream pointed to by DECODER, storing
the results in BUFFER. If LZ_API_VERSION >= 1012, BUFFER may be a null
pointer, in which case the bytes read are discarded.
@ -500,14 +470,13 @@ except 'LZ_decompress_open' whose return value must be checked by calling
allows tools like tarlz to recover as much data as possible from each
damaged member. *Note tarlz manual: (tarlz)Top.
-- Function: int LZ_decompress_write ( struct LZ_Decoder * const DECODER,
uint8_t * const BUFFER, const int SIZE )
-- Function: int LZ_decompress_write ( LZ_Decoder * const DECODER, uint8_t
* const BUFFER, const int SIZE )
Writes up to SIZE bytes from BUFFER to the stream pointed to by
DECODER. Returns the number of bytes actually written. This might be
less than SIZE. Note that writing less than SIZE bytes is not an error.
-- Function: int LZ_decompress_write_size ( struct LZ_Decoder * const
DECODER )
-- Function: int LZ_decompress_write_size ( LZ_Decoder * const DECODER )
Returns the maximum number of bytes that can be immediately written
through 'LZ_decompress_write'. This number varies smoothly; each
compressed byte consumed may be overwritten immediately, increasing by
@ -516,19 +485,17 @@ except 'LZ_decompress_open' whose return value must be checked by calling
It is guaranteed that an immediate call to 'LZ_decompress_write' will
accept a SIZE up to the returned number of bytes.
-- Function: enum LZ_Errno LZ_decompress_errno ( struct LZ_Decoder * const
DECODER )
-- Function: LZ_Errno LZ_decompress_errno ( LZ_Decoder * const DECODER )
Returns the current error code for DECODER. *Note Error codes::. It is
safe to call 'LZ_decompress_errno' with a null argument, in which case
it returns 'LZ_bad_argument'.
-- Function: int LZ_decompress_finished ( struct LZ_Decoder * const
DECODER )
-- Function: int LZ_decompress_finished ( LZ_Decoder * const DECODER )
Returns 1 if all the data have been read and 'LZ_decompress_close' can
be safely called. Otherwise it returns 0. 'LZ_decompress_finished'
does not imply 'LZ_decompress_member_finished'.
-- Function: int LZ_decompress_member_finished ( struct LZ_Decoder * const
-- Function: int LZ_decompress_member_finished ( LZ_Decoder * const
DECODER )
Returns 1 if the previous call to 'LZ_decompress_read' finished reading
the current member, indicating that final values for the member are
@ -536,37 +503,36 @@ except 'LZ_decompress_open' whose return value must be checked by calling
'LZ_decompress_data_position', and 'LZ_decompress_member_position'.
Otherwise it returns 0.
-- Function: int LZ_decompress_member_version ( struct LZ_Decoder * const
DECODER )
-- Function: int LZ_decompress_member_version ( LZ_Decoder * const DECODER
)
Returns the version of the current member, read from the member header.
-- Function: int LZ_decompress_dictionary_size ( struct LZ_Decoder * const
-- Function: int LZ_decompress_dictionary_size ( LZ_Decoder * const
DECODER )
Returns the dictionary size of the current member, read from the
member header.
-- Function: unsigned LZ_decompress_data_crc ( struct LZ_Decoder * const
DECODER )
-- Function: unsigned LZ_decompress_data_crc ( LZ_Decoder * const DECODER )
Returns the 32 bit Cyclic Redundancy Check of the data decompressed
from the current member. The value returned is valid only when
'LZ_decompress_member_finished' returns 1.
-- Function: unsigned long long LZ_decompress_data_position ( struct
LZ_Decoder * const DECODER )
-- Function: unsigned long long LZ_decompress_data_position ( LZ_Decoder *
const DECODER )
Returns the number of decompressed bytes already produced, but perhaps
not yet read, in the current member.
-- Function: unsigned long long LZ_decompress_member_position ( struct
LZ_Decoder * const DECODER )
-- Function: unsigned long long LZ_decompress_member_position ( LZ_Decoder
* const DECODER )
Returns the number of input bytes already decompressed in the current
member.
-- Function: unsigned long long LZ_decompress_total_in_size ( struct
LZ_Decoder * const DECODER )
-- Function: unsigned long long LZ_decompress_total_in_size ( LZ_Decoder *
const DECODER )
Returns the total number of input bytes already decompressed.
-- Function: unsigned long long LZ_decompress_total_out_size ( struct
LZ_Decoder * const DECODER )
-- Function: unsigned long long LZ_decompress_total_out_size ( LZ_Decoder
* const DECODER )
Returns the total number of decompressed bytes already produced, but
perhaps not yet read.
@ -587,35 +553,36 @@ what kind of error it was, you need to check the error code by calling
and you should not use 'LZ_(de)compress_errno' to determine whether a call
failed. If the call failed, then you can examine 'LZ_(de)compress_errno'.
The error codes are defined in the header file 'lzlib.h'.
The error codes are defined in the header file 'lzlib.h'. 'LZ_Errno' is
an enum type:
-- Constant: enum LZ_Errno LZ_ok
-- Constant: LZ_Errno LZ_ok
The value of this constant is 0 and is used to indicate that there is
no error.
-- Constant: enum LZ_Errno LZ_bad_argument
-- Constant: LZ_Errno LZ_bad_argument
At least one of the arguments passed to the library function was
invalid.
-- Constant: enum LZ_Errno LZ_mem_error
-- Constant: LZ_Errno LZ_mem_error
No memory available. The system cannot allocate more virtual memory
because its capacity is full.
-- Constant: enum LZ_Errno LZ_sequence_error
-- Constant: LZ_Errno LZ_sequence_error
A library function was called in the wrong order. For example
'LZ_compress_restart_member' was called before
'LZ_compress_member_finished' indicates that the current member is
'LZ_compress_member_finished' indicated that the current member is
finished.
-- Constant: enum LZ_Errno LZ_header_error
-- Constant: LZ_Errno LZ_header_error
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
data.
-- Constant: enum LZ_Errno LZ_unexpected_eof
-- Constant: LZ_Errno LZ_unexpected_eof
The end of the data stream was reached in the middle of a member.
-- Constant: enum LZ_Errno LZ_data_error
-- Constant: LZ_Errno LZ_data_error
The data stream is corrupt. If 'LZ_decompress_member_position' is 6 or
less, it indicates either a format version not supported, an invalid
dictionary size, a nonzero first LZMA byte, a corrupt header in a
@ -623,7 +590,7 @@ failed. If the call failed, then you can examine 'LZ_(de)compress_errno'.
header. Lziprecover can be used to repair some of these errors and to
remove conflicting trailing data from a file.
-- Constant: enum LZ_Errno LZ_library_error
-- Constant: LZ_Errno LZ_library_error
A bug was detected in the library. Please, report it. *Note Problems::.

@ -632,11 +599,11 @@ File: lzlib.info, Node: Error messages, Next: Invoking minilzip, Prev: Error
8 Error messages
****************
-- Function: const char * LZ_strerror ( const enum LZ_Errno 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.
-- Function: const char * LZ_strerror ( const LZ_Errno LZ_ERRNO )
Returns the error message corresponding to the error code LZ_ERRNO.
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 LZ_ERRNO normally comes from a call to
'LZ_(de)compress_errno'.
@ -647,22 +614,22 @@ File: lzlib.info, Node: Invoking minilzip, Next: File format, Prev: Error mes
9 Invoking minilzip
*******************
Minilzip is a test program for the compression library lzlib, compatible
(interoperable) with lzip 1.4 or newer. Minilzip is not intended to be
installed because lzip has more features, but minilzip is well tested and
you can use it as your main compressor if so you wish.
Minilzip is a test program for the compression library lzlib. Minilzip is
not intended to be installed because lzip has more features, but minilzip is
well tested and you can use it as your main compressor if so you wish.
*Note lzip: (lzip)Top.
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 to maximize interoperability. The
maximum dictionary size is 512 MiB so that any lzip file can be decompressed
on 32-bit machines. Lzip provides accurate and robust 3-factor integrity
checking. Lzip can compress about as fast as gzip (lzip -0) or compress most
files more than bzip2 (lzip -9). Decompression speed is intermediate between
gzip and bzip2. Lzip provides better data recovery capabilities than gzip
and bzip2. 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.
one of gzip or bzip2. Lzip uses a simplified form of LZMA (Lempel-Ziv-Markov
chain-Algorithm) designed to achieve complete interoperability between
implementations. The maximum dictionary size is 512 MiB so that any lzip
file can be decompressed on 32-bit machines. Lzip provides accurate and
robust 3-factor integrity checking. 'lzip -0' compresses about as fast as
gzip, while 'lzip -9' compresses most files more than bzip2. Decompression
speed is intermediate between gzip and bzip2. Lzip provides better data
recovery capabilities than gzip and bzip2. Lzip has been designed, written,
and tested with great care to replace gzip and bzip2 as general-purpose
compressed format for Unix-like systems.
The format for running minilzip is:
@ -675,7 +642,7 @@ once, the first time it appears in the command line. Remember to prepend
'./' to any file name beginning with a hyphen, or use '--'.
minilzip supports the following options: *Note Argument syntax:
(arg_parser)Argument syntax.
(plzip)Argument syntax.
'-h'
'--help'
@ -694,11 +661,12 @@ minilzip supports the following options: *Note Argument syntax:
'-b BYTES'
'--member-size=BYTES'
When compressing, set the member size limit to BYTES. It is advisable
to keep members smaller than RAM size so that they can be repaired with
lziprecover in case of corruption. A small member size may degrade
compression ratio, so use it only when needed. Valid values range from
100 kB to 2 PiB. Defaults to 2 PiB.
When compressing, set the member size limit to BYTES. If BYTES is
smaller than the compressed size, a multimember file is produced. It is
advisable to keep members smaller than RAM size so that they can be
repaired with lziprecover in case of corruption. A small member size
may degrade compression ratio, so use it only when needed. Valid
values range from 100 kB to 2 PiB. Defaults to 2 PiB.
'-c'
'--stdout'
@ -719,7 +687,8 @@ minilzip supports the following options: *Note Argument syntax:
status 1. If a file fails to decompress, or is a terminal, minilzip
exits immediately with error status 2 without decompressing the rest
of the files. A terminal is considered an uncompressed file, and
therefore invalid.
therefore invalid. A multimember file with one or more empty members
is accepted if redirected to standard input.
'-f'
'--force'
@ -772,6 +741,8 @@ minilzip supports the following options: *Note Argument syntax:
For maximum compression you should use a dictionary size limit as large
as possible, but keep in mind that the decompression memory requirement
is affected at compression time by the choice of dictionary size limit.
The dictionary size used for decompression is the same dictionary size
used for compression.
'-S BYTES'
'--volume-size=BYTES'
@ -791,7 +762,8 @@ minilzip supports the following options: *Note Argument syntax:
fails the test, does not exist, can't be opened, or is a terminal,
minilzip continues testing the rest of the files. A final diagnostic
is shown at verbosity level 1 or higher if any file fails the test
when testing multiple files.
when testing multiple files. A multimember file with one or more empty
members is accepted if redirected to standard input.
'-v'
'--verbose'
@ -839,7 +811,7 @@ minilzip supports the following options: *Note Argument syntax:
When decompressing or testing, allow trailing data whose first bytes
are so similar to the magic bytes of a lzip header that they can be
confused with a corrupt header. Use this option if a file triggers a
"corrupt header" error and the cause is not indeed a corrupt header.
'corrupt header' error and the cause is not indeed a corrupt header.
'--check-lib'
Compare the version of lzlib used to compile minilzip with the version
@ -935,11 +907,11 @@ not allowed in multimember files.
Valid values for dictionary size range from 4 KiB to 512 MiB.
'LZMA stream'
The LZMA stream, terminated by an "End Of Stream" marker. Uses default
The LZMA stream, terminated by an 'End Of Stream' marker. Uses default
values for encoder properties. *Note Stream format: (lzip)Stream
format, for a complete description.
Lzip only uses the LZMA marker '2' ("End Of Stream" marker). Lzlib
also uses the LZMA marker '3' ("Sync Flush" marker). *Note
Lzip only uses the LZMA marker '2' ('End Of Stream' marker). Lzlib
also uses the LZMA marker '3' ('Sync Flush' marker). *Note
sync_flush::.
'CRC32 (4 bytes)'
@ -999,7 +971,7 @@ bool bbcompress( const uint8_t * const inbuf, const int insize,
{
int inpos = 0, outpos = 0;
bool error = false;
struct LZ_Encoder * const encoder =
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; }
@ -1042,7 +1014,7 @@ bool bbdecompress( const uint8_t * const inbuf, const int insize,
{
int inpos = 0, outpos = 0;
bool error = false;
struct LZ_Decoder * const decoder = LZ_decompress_open();
LZ_Decoder * const decoder = LZ_decompress_open();
if( !decoder || LZ_decompress_errno( decoder ) != LZ_ok )
{ LZ_decompress_close( decoder ); return false; }
@ -1073,7 +1045,7 @@ File: lzlib.info, Node: File compression, Next: File decompression, Prev: Buf
File-to-file compression using LZ_compress_write_size.
int ffcompress( struct LZ_Encoder * const encoder,
int ffcompress( LZ_Encoder * const encoder,
FILE * const infile, FILE * const outfile )
{
enum { buffer_size = 16384 };
@ -1106,7 +1078,7 @@ File: lzlib.info, Node: File decompression, Next: File compression mm, Prev:
File-to-file decompression using LZ_decompress_write_size.
int ffdecompress( struct LZ_Decoder * const decoder,
int ffdecompress( LZ_Decoder * const decoder,
FILE * const infile, FILE * const outfile )
{
enum { buffer_size = 16384 };
@ -1145,8 +1117,7 @@ int ffmmcompress( FILE * const infile, FILE * const outfile )
enum { buffer_size = 16384, member_size = 4096 };
uint8_t buffer[buffer_size];
bool done = false;
struct LZ_Encoder * const encoder =
LZ_compress_open( 65535, 16, member_size );
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; }
@ -1183,7 +1154,7 @@ LZ_compress_open with MEMBER_SIZE > largest member).
for each line of text terminated by a newline character or by EOF.
Return 0 if success, 1 if error.
*/
int fflfcompress( struct LZ_Encoder * const encoder,
int fflfcompress( LZ_Encoder * const encoder,
FILE * const infile, FILE * const outfile )
{
enum { buffer_size = 16384 };
@ -1229,7 +1200,7 @@ File: lzlib.info, Node: Skipping data errors, Prev: File compression mm, Up:
next member in case of data error, including the automatic removal of
leading garbage.
*/
int ffrsdecompress( struct LZ_Decoder * const decoder,
int ffrsdecompress( LZ_Decoder * const decoder,
FILE * const infile, FILE * const outfile )
{
enum { buffer_size = 16384 };
@ -1310,27 +1281,27 @@ Concept index
Tag Table:
Node: Top215
Node: Introduction1343
Node: Library version6831
Node: Buffering9382
Node: Parameter limits10607
Node: Compression functions11561
Ref: member_size13354
Ref: sync_flush15116
Node: Decompression functions19804
Node: Error codes27362
Node: Error messages29719
Node: Invoking minilzip30298
Node: File format41020
Ref: coded-dict-size42518
Node: Examples43925
Node: Buffer compression44886
Node: Buffer decompression46406
Node: File compression47820
Node: File decompression48803
Node: File compression mm49807
Node: Skipping data errors52836
Node: Problems54141
Node: Concept index54702
Node: Library version5506
Node: Buffering8057
Node: Parameter limits9282
Node: Compression functions10236
Ref: member_size12012
Ref: sync_flush13753
Node: Decompression functions18319
Node: Error codes25706
Node: Error messages28051
Node: Invoking minilzip28634
Node: File format39716
Ref: coded-dict-size41214
Node: Examples42621
Node: Buffer compression43582
Node: Buffer decompression45095
Node: File compression46502
Node: File decompression47478
Node: File compression mm48475
Node: Skipping data errors51486
Node: Problems52784
Node: Concept index53345

End Tag Table

225
doc/lzlib.texi
View file

@ -6,8 +6,8 @@
@finalout
@c %**end of header
@set UPDATED 16 October 2024
@set VERSION 1.15-pre2
@set UPDATED 19 November 2024
@set VERSION 1.15-rc1
@dircategory Compression
@direntry
@ -66,42 +66,10 @@ distribute, and modify it.
@uref{http://www.nongnu.org/lzip/lzlib.html,,Lzlib}
is a data compression library providing in-memory LZMA compression and
decompression functions, including integrity checking of the decompressed
data. The compressed data format used by the library is the lzip format.
data. The compressed data format used by the library is the
@uref{http://www.nongnu.org/lzip/lzip.html,,lzip} format.
Lzlib is written in C and is distributed under a 2-clause BSD license.
The lzip file format is designed for data sharing and long-term archiving,
taking into account both data integrity and decoder availability:
@itemize @bullet
@item
The lzip format provides very safe integrity checking and some data
recovery means. The program
@uref{http://www.nongnu.org/lzip/manual/lziprecover_manual.html#Data-safety,,lziprecover}
can repair bit flip errors (one of the most common forms of data corruption)
in lzip files, and provides data recovery capabilities, including
error-checked merging of damaged copies of a file.
@ifnothtml
@xref{Data safety,,,lziprecover}.
@end ifnothtml
@item
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
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
the data from a lzip file long after quantum computers eventually
render LZMA obsolete.
@item
Additionally the lzip reference implementation is copylefted, which
guarantees that it will remain free forever.
@end itemize
A nice feature of the lzip format is that a corrupt byte is easier to repair
the nearer it is from the beginning of the file. Therefore, with the help of
lziprecover, losing an entire archive just because of a corrupt byte near
the beginning is a thing of the past.
The functions and variables forming the interface of the compression library
are declared in the file @file{lzlib.h}. Usage examples of the library are
given in the files @file{bbexample.c}, @file{ffexample.c}, and
@ -149,10 +117,10 @@ 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
scheme". For example, the option @option{-0} of lzip uses the scheme in
almost 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
way of finding coding sequences of minimum size than the one currently used
by lzip could be developed, and the resulting sequence could also be coded
using the LZMA coding scheme.
a literal byte if it can't find a match. Inversely, a more elaborate way of
finding coding sequences of minimum size than the one currently used by lzip
could be developed, and the resulting sequence could also be coded using the
LZMA coding scheme.
Lzlib currently implements two variants of the LZMA algorithm: fast (used by
option @option{-0} of minilzip) and normal (used by all other compression levels).
@ -308,7 +276,7 @@ except @samp{LZ_compress_open} whose return value must be checked by
calling @samp{LZ_compress_errno} before using it.
@deftypefun {struct LZ_Encoder *} LZ_compress_open ( const int @var{dictionary_size}, const int @var{match_len_limit}, const unsigned long long @var{member_size} )
@deftypefun {LZ_Encoder *} LZ_compress_open ( const int @var{dictionary_size}, const int @var{match_len_limit}, const unsigned 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, or a null pointer if the encoder could not
@ -344,7 +312,7 @@ the uncompressed size of the member from overflowing.
@end deftypefun
@deftypefun int LZ_compress_close ( struct LZ_Encoder * const @var{encoder} )
@deftypefun int LZ_compress_close ( 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
@ -353,7 +321,7 @@ It is safe to call @samp{LZ_compress_close} with a null argument.
@end deftypefun
@deftypefun int LZ_compress_finish ( struct LZ_Encoder * const @var{encoder} )
@deftypefun int LZ_compress_finish ( LZ_Encoder * const @var{encoder} )
Use this function to tell @samp{lzlib} that all the data for this member
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.
@ -363,7 +331,7 @@ started with @samp{LZ_compress_restart_member}.
@end deftypefun
@deftypefun int LZ_compress_restart_member ( struct LZ_Encoder * const @var{encoder}, const unsigned long long @var{member_size} )
@deftypefun int LZ_compress_restart_member ( LZ_Encoder * const @var{encoder}, const unsigned 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 function
@ -373,18 +341,18 @@ the current member has been fully read (with the function
@anchor{sync_flush}
@deftypefun int LZ_compress_sync_flush ( struct LZ_Encoder * const @var{encoder} )
@deftypefun int LZ_compress_sync_flush ( LZ_Encoder * const @var{encoder} )
Use this function to make available to @samp{LZ_compress_read} all the data
already written with the function @samp{LZ_compress_write}. First call
@samp{LZ_compress_sync_flush}. Then call @samp{LZ_compress_read} until it
returns 0.
This function writes at least one LZMA marker @samp{3} ("Sync Flush" marker)
This function writes at least one 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.
@samp{2} ('End Of Stream' marker) is the only marker allowed in lzip files.
@xref{File format}.
Repeated use of @samp{LZ_compress_sync_flush} may degrade compression
@ -401,7 +369,7 @@ are more bytes available than those needed to complete @var{member_size},
@end deftypefun
@deftypefun int LZ_compress_read ( struct LZ_Encoder * const @var{encoder}, uint8_t * const @var{buffer}, const int @var{size} )
@deftypefun int LZ_compress_read ( LZ_Encoder * const @var{encoder}, uint8_t * const @var{buffer}, const int @var{size} )
Reads up to @var{size} bytes from the stream pointed to by @var{encoder},
storing the results in @var{buffer}. If @w{LZ_API_VERSION >= 1012},
@var{buffer} may be a null pointer, in which case the bytes read are
@ -415,7 +383,7 @@ not an error.
@end deftypefun
@deftypefun int LZ_compress_write ( struct LZ_Encoder * const @var{encoder}, uint8_t * const @var{buffer}, const int @var{size} )
@deftypefun int LZ_compress_write ( LZ_Encoder * const @var{encoder}, uint8_t * const @var{buffer}, const int @var{size} )
Writes up to @var{size} bytes from @var{buffer} to the stream pointed to by
@var{encoder}. Returns the number of bytes actually written. This might be
less than @var{size}. Note that writing less than @var{size} bytes is not an
@ -423,7 +391,7 @@ error.
@end deftypefun
@deftypefun int LZ_compress_write_size ( struct LZ_Encoder * const @var{encoder} )
@deftypefun int LZ_compress_write_size ( LZ_Encoder * const @var{encoder} )
Returns the maximum number of bytes that can be immediately written through
@samp{LZ_compress_write}. For efficiency reasons, once the input buffer is
full and @samp{LZ_compress_write_size} returns 0, almost all the buffer must
@ -436,44 +404,44 @@ accept a @var{size} up to the returned number of bytes.
@end deftypefun
@deftypefun {enum LZ_Errno} LZ_compress_errno ( struct LZ_Encoder * const @var{encoder} )
@deftypefun {LZ_Errno} LZ_compress_errno ( LZ_Encoder * const @var{encoder} )
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
@deftypefun int LZ_compress_finished ( struct LZ_Encoder * const @var{encoder} )
@deftypefun int LZ_compress_finished ( LZ_Encoder * const @var{encoder} )
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}
implies @samp{LZ_compress_member_finished}.
@end deftypefun
@deftypefun int LZ_compress_member_finished ( struct LZ_Encoder * const @var{encoder} )
@deftypefun int LZ_compress_member_finished ( 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 {unsigned long long} LZ_compress_data_position ( struct LZ_Encoder * const @var{encoder} )
@deftypefun {unsigned long long} LZ_compress_data_position ( LZ_Encoder * const @var{encoder} )
Returns the number of input bytes already compressed in the current member.
@end deftypefun
@deftypefun {unsigned long long} LZ_compress_member_position ( struct LZ_Encoder * const @var{encoder} )
@deftypefun {unsigned long long} LZ_compress_member_position ( 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 {unsigned long long} LZ_compress_total_in_size ( struct LZ_Encoder * const @var{encoder} )
@deftypefun {unsigned long long} LZ_compress_total_in_size ( LZ_Encoder * const @var{encoder} )
Returns the total number of input bytes already compressed.
@end deftypefun
@deftypefun {unsigned long long} LZ_compress_total_out_size ( struct LZ_Encoder * const @var{encoder} )
@deftypefun {unsigned long long} LZ_compress_total_out_size ( LZ_Encoder * const @var{encoder} )
Returns the total number of compressed bytes already produced, but
perhaps not yet read.
@end deftypefun
@ -489,7 +457,7 @@ except @samp{LZ_decompress_open} whose return value must be checked by
calling @samp{LZ_decompress_errno} before using it.
@deftypefun {struct LZ_Decoder *} LZ_decompress_open ( void )
@deftypefun {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, or a null pointer if the decoder could not be
@ -502,7 +470,7 @@ the returned pointer must not be used and should be freed with
@end deftypefun
@deftypefun int LZ_decompress_close ( struct LZ_Decoder * const @var{decoder} )
@deftypefun int LZ_decompress_close ( 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
@ -511,7 +479,7 @@ It is safe to call @samp{LZ_decompress_close} with a null argument.
@end deftypefun
@deftypefun int LZ_decompress_finish ( struct LZ_Decoder * const @var{decoder} )
@deftypefun int LZ_decompress_finish ( LZ_Decoder * const @var{decoder} )
Use this function to tell @samp{lzlib} that all the data for this stream
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.
@ -521,14 +489,14 @@ detecting a truncated member.
@end deftypefun
@deftypefun int LZ_decompress_reset ( struct LZ_Decoder * const @var{decoder} )
@deftypefun int LZ_decompress_reset ( LZ_Decoder * const @var{decoder} )
Resets the internal state of @var{decoder} as it was just after opening
it with the function @samp{LZ_decompress_open}. Data stored in the
internal buffers are discarded. Position counters are set to 0.
@end deftypefun
@deftypefun int LZ_decompress_sync_to_member ( struct LZ_Decoder * const @var{decoder} )
@deftypefun int LZ_decompress_sync_to_member ( 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
@ -542,7 +510,7 @@ does nothing.
@end deftypefun
@deftypefun int LZ_decompress_read ( struct LZ_Decoder * const @var{decoder}, uint8_t * const @var{buffer}, const int @var{size} )
@deftypefun int LZ_decompress_read ( LZ_Decoder * const @var{decoder}, uint8_t * const @var{buffer}, const int @var{size} )
Reads up to @var{size} bytes from the stream pointed to by @var{decoder},
storing the results in @var{buffer}. If @w{LZ_API_VERSION >= 1012},
@var{buffer} may be a null pointer, in which case the bytes read are
@ -574,7 +542,7 @@ recover as much data as possible from each damaged member.
@end deftypefun
@deftypefun int LZ_decompress_write ( struct LZ_Decoder * const @var{decoder}, uint8_t * const @var{buffer}, const int @var{size} )
@deftypefun int LZ_decompress_write ( LZ_Decoder * const @var{decoder}, uint8_t * const @var{buffer}, const int @var{size} )
Writes up to @var{size} bytes from @var{buffer} to the stream pointed to by
@var{decoder}. Returns the number of bytes actually written. This might be
less than @var{size}. Note that writing less than @var{size} bytes is not an
@ -582,7 +550,7 @@ error.
@end deftypefun
@deftypefun int LZ_decompress_write_size ( struct LZ_Decoder * const @var{decoder} )
@deftypefun int LZ_decompress_write_size ( LZ_Decoder * const @var{decoder} )
Returns the maximum number of bytes that can be immediately written through
@samp{LZ_decompress_write}. This number varies smoothly; each compressed
byte consumed may be overwritten immediately, increasing by 1 the value
@ -593,21 +561,21 @@ 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} )
@deftypefun {LZ_Errno} LZ_decompress_errno ( LZ_Decoder * const @var{decoder} )
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
@deftypefun int LZ_decompress_finished ( struct LZ_Decoder * const @var{decoder} )
@deftypefun int LZ_decompress_finished ( LZ_Decoder * const @var{decoder} )
Returns 1 if all the data have been read and @samp{LZ_decompress_close}
can be safely called. Otherwise it returns 0. @samp{LZ_decompress_finished}
does not imply @samp{LZ_decompress_member_finished}.
@end deftypefun
@deftypefun int LZ_decompress_member_finished ( struct LZ_Decoder * const @var{decoder} )
@deftypefun int LZ_decompress_member_finished ( LZ_Decoder * const @var{decoder} )
Returns 1 if the previous call to @samp{LZ_decompress_read} finished reading
the current member, indicating that final values for the member are available
through @samp{LZ_decompress_data_crc}, @samp{LZ_decompress_data_position},
@ -615,40 +583,40 @@ and @samp{LZ_decompress_member_position}. Otherwise it returns 0.
@end deftypefun
@deftypefun int LZ_decompress_member_version ( struct LZ_Decoder * const @var{decoder} )
@deftypefun int LZ_decompress_member_version ( LZ_Decoder * const @var{decoder} )
Returns the version of the current member, read from the member header.
@end deftypefun
@deftypefun int LZ_decompress_dictionary_size ( struct LZ_Decoder * const @var{decoder} )
@deftypefun int LZ_decompress_dictionary_size ( LZ_Decoder * const @var{decoder} )
Returns the dictionary size of the current member, read from the member header.
@end deftypefun
@deftypefun {unsigned} LZ_decompress_data_crc ( struct LZ_Decoder * const @var{decoder} )
@deftypefun {unsigned} LZ_decompress_data_crc ( LZ_Decoder * const @var{decoder} )
Returns the 32 bit Cyclic Redundancy Check of the data decompressed from
the current member. The value returned is valid only when
@samp{LZ_decompress_member_finished} returns 1.
@end deftypefun
@deftypefun {unsigned long long} LZ_decompress_data_position ( struct LZ_Decoder * const @var{decoder} )
@deftypefun {unsigned long long} LZ_decompress_data_position ( 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 {unsigned long long} LZ_decompress_member_position ( struct LZ_Decoder * const @var{decoder} )
@deftypefun {unsigned long long} LZ_decompress_member_position ( LZ_Decoder * const @var{decoder} )
Returns the number of input bytes already decompressed in the current member.
@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 ( LZ_Decoder * const @var{decoder} )
Returns the total number of input bytes already decompressed.
@end deftypefun
@deftypefun {unsigned long long} LZ_decompress_total_out_size ( struct LZ_Decoder * const @var{decoder} )
@deftypefun {unsigned long long} LZ_decompress_total_out_size ( LZ_Decoder * const @var{decoder} )
Returns the total number of decompressed bytes already produced, but
perhaps not yet read.
@end deftypefun
@ -671,37 +639,38 @@ to determine whether a call failed. If the call failed, then you can
examine @samp{LZ_(de)compress_errno}.
The error codes are defined in the header file @file{lzlib.h}.
@samp{LZ_Errno} is an enum type:
@deftypevr Constant {enum LZ_Errno} LZ_ok
@deftypevr Constant {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 {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
No memory available. The system cannot allocate more virtual memory
because its capacity is full.
@deftypevr Constant {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 {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
@samp{LZ_compress_member_finished} indicated that the current member is
finished.
@end deftypevr
@deftypevr Constant {enum LZ_Errno} LZ_header_error
@deftypevr Constant {LZ_Errno} LZ_header_error
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 data.
@end deftypevr
@deftypevr Constant {enum LZ_Errno} LZ_unexpected_eof
@deftypevr Constant {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 {LZ_Errno} LZ_data_error
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
dictionary size, a nonzero first LZMA byte, a corrupt header in a multimember
@ -710,7 +679,7 @@ Lziprecover can be used to repair some of these errors and to remove
conflicting trailing data from a file.
@end deftypevr
@deftypevr Constant {enum LZ_Errno} LZ_library_error
@deftypevr Constant {LZ_Errno} LZ_library_error
A bug was detected in the library. Please, report it. @xref{Problems}.
@end deftypevr
@ -719,11 +688,11 @@ A bug was detected in the library. Please, report it. @xref{Problems}.
@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.
@deftypefun {const char *} LZ_strerror ( const LZ_Errno @var{lz_errno} )
Returns the error message corresponding to the error code @var{lz_errno}.
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}.
@ -735,23 +704,25 @@ The value of @var{lz_errno} normally comes from a call to
@cindex invoking
@cindex options
Minilzip is a test program for the compression library lzlib, compatible
(interoperable) with lzip 1.4 or newer. Minilzip is not intended to be
installed because lzip has more features, but minilzip is well tested and
you can use it as your main compressor if so you wish.
Minilzip is a test program for the compression library lzlib. Minilzip is
not intended to be installed because lzip has more features, but minilzip is
well tested and you can use it as your main compressor if so you wish.
@ifnothtml
@xref{Top,lzip,,lzip}.
@end ifnothtml
@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 to maximize interoperability. The
maximum dictionary size is 512 MiB so that any lzip file can be decompressed
on 32-bit machines. Lzip provides accurate and robust 3-factor integrity
checking. 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 provides better data recovery capabilities than gzip
and bzip2. 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.
of gzip or bzip2. Lzip uses a simplified form of LZMA (Lempel-Ziv-Markov
chain-Algorithm) designed to achieve complete interoperability between
implementations. The maximum dictionary size is 512 MiB so that any lzip
file can be decompressed on 32-bit machines. Lzip provides accurate and
robust 3-factor integrity checking. @w{@samp{lzip -0}} compresses about as fast as
gzip, while @w{@samp{lzip -9}} compresses most files more than bzip2. Decompression
speed is intermediate between gzip and bzip2. Lzip provides better data
recovery capabilities than gzip and bzip2. Lzip has been designed, written,
and tested with great care to replace gzip and bzip2 as general-purpose
compressed format for Unix-like systems.
@noindent
The format for running minilzip is:
@ -769,9 +740,9 @@ prepend @file{./} to any file name beginning with a hyphen, or use @samp{--}.
@noindent
minilzip supports the following
@uref{http://www.nongnu.org/arg-parser/manual/arg_parser_manual.html#Argument-syntax,,options}:
@uref{http://www.nongnu.org/lzip/manual/plzip_manual.html#Argument-syntax,,options}:
@ifnothtml
@xref{Argument syntax,,,arg_parser}.
@xref{Argument syntax,,,plzip}.
@end ifnothtml
@table @code
@ -792,9 +763,10 @@ garbage that can be safely ignored.
@item -b @var{bytes}
@itemx --member-size=@var{bytes}
When compressing, set the member size limit to @var{bytes}. It is advisable
to keep members smaller than RAM size so that they can be repaired with
lziprecover in case of corruption. A small member size may degrade
When compressing, set the member size limit to @var{bytes}. If @var{bytes}
is smaller than the compressed size, a multimember file is produced. It is
advisable to keep members smaller than RAM size so that they can be repaired
with 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}.
@ -816,7 +788,8 @@ already exists and @option{--force} has not been specified, minilzip continues
decompressing the rest of the files and exits with error status 1. If a file
fails to decompress, or is a terminal, minilzip exits immediately with error
status 2 without decompressing the rest of the files. A terminal is
considered an uncompressed file, and therefore invalid.
considered an uncompressed file, and therefore invalid. A multimember file
with one or more empty members is accepted if redirected to standard input.
@item -f
@itemx --force
@ -870,6 +843,8 @@ to it.
For maximum compression you should use a dictionary size limit as large
as possible, but keep in mind that the decompression memory requirement
is affected at compression time by the choice of dictionary size limit.
The dictionary size used for decompression is the same dictionary size used
for compression.
@item -S @var{bytes}
@itemx --volume-size=@var{bytes}
@ -889,7 +864,8 @@ together with @option{-v} to see information about the files. If a file
fails the test, does not exist, can't be opened, or is a terminal, minilzip
continues testing the rest of the files. A final diagnostic is shown at
verbosity level 1 or higher if any file fails the test when testing multiple
files.
files. A multimember file with one or more empty members is accepted if
redirected to standard input.
@item -v
@itemx --verbose
@ -936,8 +912,8 @@ Aliases for GNU gzip compatibility.
@item --loose-trailing
When decompressing or testing, allow trailing data whose first bytes are
so similar to the magic bytes of a lzip header that they can be confused
with a corrupt header. Use this option if a file triggers a "corrupt
header" error and the cause is not indeed a corrupt header.
with a corrupt header. Use this option if a file triggers a 'corrupt
header' error and the cause is not indeed a corrupt header.
@item --check-lib
Compare the @uref{#Library-version,,version of lzlib} used to compile
@ -1044,7 +1020,7 @@ 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.
@item LZMA stream
The LZMA stream, terminated by an "End Of Stream" marker. Uses default values
The LZMA stream, terminated by an 'End Of Stream' marker. Uses default values
for encoder properties.
@ifnothtml
@xref{Stream format,,,lzip},
@ -1054,8 +1030,8 @@ See
@uref{http://www.nongnu.org/lzip/manual/lzip_manual.html#Stream-format,,Stream format}
@end ifhtml
for a complete description.@*
Lzip only uses the LZMA marker @samp{2} ("End Of Stream" marker). Lzlib
also uses the LZMA marker @samp{3} ("Sync Flush" marker). @xref{sync_flush}.
Lzip only uses the LZMA marker @samp{2} ('End Of Stream' marker). Lzlib
also uses the LZMA marker @samp{3} ('Sync Flush' marker). @xref{sync_flush}.
@item CRC32 (4 bytes)
Cyclic Redundancy Check (CRC) of the original uncompressed data.
@ -1115,7 +1091,7 @@ bool bbcompress( const uint8_t * const inbuf, const int insize,
{
int inpos = 0, outpos = 0;
bool error = false;
struct LZ_Encoder * const encoder =
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; }
@ -1159,7 +1135,7 @@ bool bbdecompress( const uint8_t * const inbuf, const int insize,
{
int inpos = 0, outpos = 0;
bool error = false;
struct LZ_Decoder * const decoder = LZ_decompress_open();
LZ_Decoder * const decoder = LZ_decompress_open();
if( !decoder || LZ_decompress_errno( decoder ) != LZ_ok )
{ LZ_decompress_close( decoder ); return false; }
@ -1191,7 +1167,7 @@ bool bbdecompress( const uint8_t * const inbuf, const int insize,
File-to-file compression using LZ_compress_write_size.
@verbatim
int ffcompress( struct LZ_Encoder * const encoder,
int ffcompress( LZ_Encoder * const encoder,
FILE * const infile, FILE * const outfile )
{
enum { buffer_size = 16384 };
@ -1225,7 +1201,7 @@ int ffcompress( struct LZ_Encoder * const encoder,
File-to-file decompression using LZ_decompress_write_size.
@verbatim
int ffdecompress( struct LZ_Decoder * const decoder,
int ffdecompress( LZ_Decoder * const decoder,
FILE * const infile, FILE * const outfile )
{
enum { buffer_size = 16384 };
@ -1265,8 +1241,7 @@ int ffmmcompress( FILE * const infile, FILE * const outfile )
enum { buffer_size = 16384, member_size = 4096 };
uint8_t buffer[buffer_size];
bool done = false;
struct LZ_Encoder * const encoder =
LZ_compress_open( 65535, 16, member_size );
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; }
@ -1306,7 +1281,7 @@ Example 2: Multimember compression (user-restarted members).
for each line of text terminated by a newline character or by EOF.
Return 0 if success, 1 if error.
*/
int fflfcompress( struct LZ_Encoder * const encoder,
int fflfcompress( LZ_Encoder * const encoder,
FILE * const infile, FILE * const outfile )
{
enum { buffer_size = 16384 };
@ -1353,7 +1328,7 @@ int fflfcompress( struct LZ_Encoder * const encoder,
next member in case of data error, including the automatic removal of
leading garbage.
*/
int ffrsdecompress( struct LZ_Decoder * const decoder,
int ffrsdecompress( LZ_Decoder * const decoder,
FILE * const infile, FILE * const outfile )
{
enum { buffer_size = 16384 };

31
doc/minilzip.1
View file

@ -1,25 +1,26 @@
.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.2.
.TH MINILZIP "1" "October 2024" "minilzip 1.15-pre2" "User Commands"
.TH MINILZIP "1" "November 2024" "minilzip 1.15-rc1" "User Commands"
.SH NAME
minilzip \- reduces the size of files
.SH SYNOPSIS
.B minilzip
[\fI\,options\/\fR] [\fI\,files\/\fR]
.SH DESCRIPTION
Minilzip is a test program for the compression library lzlib, compatible
(interoperable) with lzip 1.4 or newer.
Minilzip is a test program for the compression library lzlib. Minilzip is
not intended to be installed because lzip has more features, but minilzip is
well tested and you can use it as your main compressor if so you wish.
.PP
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 to maximize interoperability. The
maximum dictionary size is 512 MiB so that any lzip file can be decompressed
on 32\-bit machines. Lzip provides accurate and robust 3\-factor integrity
checking. Lzip can compress about as fast as gzip (lzip \fB\-0\fR) or compress most
files more than bzip2 (lzip \fB\-9\fR). Decompression speed is intermediate between
gzip and bzip2. Lzip provides better data recovery capabilities than gzip
and bzip2. 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.
of gzip or bzip2. Lzip uses a simplified form of LZMA (Lempel\-Ziv\-Markov
chain\-Algorithm) designed to achieve complete interoperability between
implementations. The maximum dictionary size is 512 MiB so that any lzip
file can be decompressed on 32\-bit machines. Lzip provides accurate and
robust 3\-factor integrity checking. 'lzip \fB\-0\fR' compresses about as fast as
gzip, while 'lzip \fB\-9\fR' compresses most files more than bzip2. Decompression
speed is intermediate between gzip and bzip2. Lzip provides better data
recovery capabilities than gzip and bzip2. Lzip has been designed, written,
and tested with great care to replace gzip and bzip2 as general\-purpose
compressed format for Unix\-like systems.
.SH OPTIONS
.TP
\fB\-h\fR, \fB\-\-help\fR
@ -32,7 +33,7 @@ output version information and exit
exit with error status if trailing data
.TP
\fB\-b\fR, \fB\-\-member\-size=\fR<bytes>
set member size limit in bytes
set member size limit of multimember files
.TP
\fB\-c\fR, \fB\-\-stdout\fR
write to standard output, keep input files
@ -120,7 +121,7 @@ License GPLv2+: GNU GPL version 2 or later <http://gnu.org/licenses/gpl.html>
.br
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Using lzlib 1.15\-pre2
Using lzlib 1.15\-rc1
Using LZ_API_VERSION = 1015
.SH "SEE ALSO"
The full documentation for