lzip/lzlib
1
0
Fork 0
Code Issues Activity

Merging upstream version 1.15~pre2.

Browse source 
Signed-off-by: Daniel Baumann <daniel@debian.org>
This commit is contained in:
Daniel Baumann 2025-02-20 21:34:33 +01:00
parent dcd7b7d39e
commit 8c8d69247f
Signed by: daniel
GPG key ID: FBB4F0E80A80222F
23 changed files with 249 additions and 188 deletions
Download patch file Download diff file Expand all files Collapse all files

101
doc/lzlib.texi
View file

@ -6,8 +6,8 @@
@finalout
@c %**end of header
@set UPDATED 19 April 2024
@set VERSION 1.15-pre1
@set UPDATED 16 October 2024
@set VERSION 1.15-pre2
@dircategory Compression
@direntry
@ -45,7 +45,7 @@ This manual is for Lzlib (version @value{VERSION}, @value{UPDATED}).
* Error codes:: Meaning of codes returned by functions
* Error messages:: Error messages corresponding to error codes
* Invoking minilzip:: Command-line interface of the test program
* Data format:: Detailed format of the compressed data
* File format:: Detailed format of the compressed file
* Examples:: A small tutorial with examples
* Problems:: Reporting bugs
* Concept index:: Index of concepts
@ -67,7 +67,7 @@ distribute, and modify it.
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.
Lzlib is written in C.
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:
@ -103,16 +103,16 @@ 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 @samp{lzlib.h}. Usage examples of the library are
given in the files @samp{bbexample.c}, @samp{ffexample.c}, and
@samp{minilzip.c} from the source distribution.
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
@file{minilzip.c} from the source distribution.
As @samp{lzlib.h} can be used by C and C++ programs, it must not impose a
As @file{lzlib.h} can be used by C and C++ programs, it must not impose a
choice of system headers on the program by including one of them. Therefore
it is the responsibility of the program using lzlib to include before
@samp{lzlib.h} some header that declares the type @samp{uint8_t}. There are
at least four such headers in C and C++: @samp{stdint.h}, @samp{cstdint},
@samp{inttypes.h}, and @samp{cinttypes}.
@file{lzlib.h} some header that declares the type @samp{uint8_t}. There are
at least four such headers in C and C++: @file{stdint.h}, @file{cstdint},
@file{inttypes.h}, and @file{cinttypes}.
All the library functions are thread safe. The library does not install any
signal handler. The decoder checks the consistency of the compressed data,
@ -183,10 +183,10 @@ versions of itself down to 1.0. Any application working with an older lzlib
should work with a newer lzlib. Installing a newer lzlib should not break
anything. This chapter describes the constants and functions that the
application can use to discover the version of the library being used. All
of them are declared in @samp{lzlib.h}.
of them are declared in @file{lzlib.h}.
@defvr Constant LZ_API_VERSION
This constant is defined in @samp{lzlib.h} and works as a version test
This constant is defined in @file{lzlib.h} and works as a version test
macro. The application should check at compile time that LZ_API_VERSION is
greater than or equal to the version required by the application:
@ -207,7 +207,7 @@ which allow the application to announce to the library its desire to have
certain symbols and prototypes exposed.
@deftypefun int LZ_api_version ( void )
If LZ_API_VERSION >= 1012, this function is declared in @samp{lzlib.h} (else
If LZ_API_VERSION >= 1012, this function is declared in @file{lzlib.h} (else
it doesn't exist). It returns the LZ_API_VERSION of the library object code
being used. The application should check at run time that the value
returned by @code{LZ_api_version} is greater than or equal to the version
@ -225,7 +225,7 @@ the functionality required by the application.
@end deftypefun
@deftypevr Constant {const char *} LZ_version_string
This string constant is defined in the header file @samp{lzlib.h} and
This string constant is defined in the header file @file{lzlib.h} and
represents the version of the library being used at compile time.
@end deftypevr
@ -385,7 +385,7 @@ 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}.
@xref{File format}.
Repeated use of @samp{LZ_compress_sync_flush} may degrade compression
ratio, so use it only when needed. If the interval between calls to
@ -524,7 +524,7 @@ detecting a truncated member.
@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 function @samp{LZ_decompress_open}. Data stored in the
internal buffers is discarded. Position counters are set to 0.
internal buffers are discarded. Position counters are set to 0.
@end deftypefun
@ -670,7 +670,7 @@ necessarily LZ_ok, and you should not use @samp{LZ_(de)compress_errno}
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 @samp{lzlib.h}.
The error codes are defined in the header file @file{lzlib.h}.
@deftypevr Constant {enum LZ_Errno} LZ_ok
The value of this constant is 0 and is used to indicate that there is no error.
@ -693,8 +693,8 @@ finished.
@end deftypevr
@deftypevr Constant {enum 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.
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
@ -702,11 +702,12 @@ The end of the data stream was reached in the middle of a member.
@end deftypevr
@deftypevr Constant {enum 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 corrupt header in a multimember data stream, or
trailing data too similar to a valid lzip header. Lziprecover can be
used to remove conflicting trailing data from a file.
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
data stream, or trailing data too similar to a valid lzip header.
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
@ -747,8 +748,8 @@ 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 is better than gzip and bzip2 from a data recovery
perspective. Lzip has been designed, written, and tested with great care to
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.
@ -766,6 +767,7 @@ 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. Remember to
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}:
@ifnothtml
@ -823,7 +825,7 @@ Force overwrite of output files.
@item -F
@itemx --recompress
When compressing, force re-compression of files whose name already has
the @samp{.lz} or @samp{.tlz} suffix.
the @file{.lz} or @file{.tlz} suffix.
@item -k
@itemx --keep
@ -846,8 +848,8 @@ when reading from a named pipe (fifo) or from a device. @w{@option{-o -}} is
equivalent to @option{-c}. @option{-o} has no effect when testing.
When compressing and splitting the output in volumes, @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
a prefix, and several files named @file{@var{file}00001.lz},
@file{@var{file}00002.lz}, etc, are created. In this case, only one input
file is allowed.
@item -q
@ -873,7 +875,7 @@ is affected at compression time by the choice of dictionary size limit.
@itemx --volume-size=@var{bytes}
When compressing, and @option{-c} has not been also specified, split the
compressed output into several volume files with names
@samp{original_name00001.lz}, @samp{original_name00002.lz}, etc, and set the
@file{original_name00001.lz}, @file{original_name00002.lz}, etc, and set the
volume size limit to @var{bytes}. Input files are kept unchanged. Each
volume is a complete, maybe multimember, lzip file. A small volume size may
degrade compression ratio, so use it only when needed. Valid values range
@ -892,11 +894,10 @@ files.
@item -v
@itemx --verbose
Verbose mode.@*
When compressing, show the compression ratio and size for each file
processed.@*
When decompressing or testing, further -v's (up to 4) increase the
verbosity level, showing status, compression ratio, dictionary size,
and trailer contents (CRC, data size, member size).
When compressing, show the compression ratio and size for each file processed.@*
When decompressing or testing, further -v's (up to 4) increase the verbosity
level, showing status, compression ratio, dictionary size, and trailer
contents (CRC, data size, member size).
@item -0 .. -9
Compression level. Set the compression parameters (dictionary size and
@ -915,7 +916,7 @@ given, the last setting is used. For example @w{@option{-9 -s64MiB}} is
equivalent to @w{@option{-s64MiB -m273}}
@multitable {Level} {Dictionary size (-s)} {Match length limit (-m)}
@item Level @tab Dictionary size (-s) @tab Match length limit (-m)
@headitem Level @tab Dictionary size (-s) @tab Match length limit (-m)
@item -0 @tab 64 KiB @tab 16 bytes
@item -1 @tab 1 MiB @tab 5 bytes
@item -2 @tab 1.5 MiB @tab 6 bytes
@ -960,7 +961,7 @@ and may be followed by a multiplier and an optional @samp{B} for "byte".
Table of SI and binary prefixes (unit multipliers):
@multitable {Prefix} {kilobyte (10^3 = 1000)} {|} {Prefix} {kibibyte (2^10 = 1024)}
@item Prefix @tab Value @tab | @tab Prefix @tab Value
@headitem Prefix @tab Value @tab | @tab Prefix @tab Value
@item k @tab kilobyte (10^3 = 1000) @tab | @tab Ki @tab kibibyte (2^10 = 1024)
@item M @tab megabyte (10^6) @tab | @tab Mi @tab mebibyte (2^20)
@item G @tab gigabyte (10^9) @tab | @tab Gi @tab gibibyte (2^30)
@ -980,15 +981,14 @@ indicate a corrupt or invalid input file, 3 for an internal consistency
error (e.g., bug) which caused minilzip to panic.
@node Data format
@chapter Data format
@cindex data format
@node File format
@chapter File format
@cindex file format
Perfection is reached, not when there is no longer anything to add, but
when there is no longer anything to take away.@*
--- Antoine de Saint-Exupery
@sp 1
In the diagram below, a box like this:
@verbatim
@ -1007,12 +1007,13 @@ represents one byte; a box like this:
represents a variable number of bytes.
@sp 1
Lzip data consist of one or more independent "members" (compressed data
sets). The members simply appear one after another in the data stream, with
no additional information before, between, or after them. Each member can
@noindent
A lzip file consists of one or more independent "members" (compressed data
sets). The members simply appear one after another in the file, with no
additional information before, between, or after them. Each member can
encode in compressed form up to @w{16 EiB - 1 byte} of uncompressed data.
The size of a multimember data stream is unlimited.
The size of a multimember file is unlimited. Empty members (data size = 0)
are not allowed in multimember files.
Each member has the following structure:
@ -1043,7 +1044,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, finished 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},
@ -1077,8 +1078,8 @@ overflowing.
@cindex examples
This chapter provides real code examples for the most common uses of the
library. See these examples in context in the files @samp{bbexample.c} and
@samp{ffexample.c} from the source distribution of lzlib.
library. See these examples in context in the files @file{bbexample.c} and
@file{ffexample.c} from the source distribution of lzlib.
Note that the interface of lzlib is symmetrical. That is, the code for
normal compression and decompression is identical except because one calls