395 lines
20 KiB
HTML
395 lines
20 KiB
HTML
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
|
<title>1.9.3 Manual</title>
|
|
</head>
|
|
<body>
|
|
<h1>1.9.3 Manual</h1>
|
|
<hr>
|
|
<a name="Contents"></a><h2>Contents</h2>
|
|
<ol>
|
|
<li><a href="#Chapter1">Introduction</a></li>
|
|
<li><a href="#Chapter2">Compiler specifics</a></li>
|
|
<li><a href="#Chapter3">Error management</a></li>
|
|
<li><a href="#Chapter4">Frame compression types</a></li>
|
|
<li><a href="#Chapter5">Simple compression function</a></li>
|
|
<li><a href="#Chapter6">Advanced compression functions</a></li>
|
|
<li><a href="#Chapter7">Resource Management</a></li>
|
|
<li><a href="#Chapter8">Compression</a></li>
|
|
<li><a href="#Chapter9">Decompression functions</a></li>
|
|
<li><a href="#Chapter10">Streaming decompression functions</a></li>
|
|
<li><a href="#Chapter11">Bulk processing dictionary API</a></li>
|
|
</ol>
|
|
<hr>
|
|
<a name="Chapter1"></a><h2>Introduction</h2><pre>
|
|
lz4frame.h implements LZ4 frame specification (doc/lz4_Frame_format.md).
|
|
lz4frame.h provides frame compression functions that take care
|
|
of encoding standard metadata alongside LZ4-compressed blocks.
|
|
<BR></pre>
|
|
|
|
<a name="Chapter2"></a><h2>Compiler specifics</h2><pre></pre>
|
|
|
|
<a name="Chapter3"></a><h2>Error management</h2><pre></pre>
|
|
|
|
<pre><b>unsigned LZ4F_isError(LZ4F_errorCode_t code); </b>/**< tells when a function result is an error code */<b>
|
|
</b></pre><BR>
|
|
<pre><b>const char* LZ4F_getErrorName(LZ4F_errorCode_t code); </b>/**< return error code string; for debugging */<b>
|
|
</b></pre><BR>
|
|
<a name="Chapter4"></a><h2>Frame compression types</h2><pre></pre>
|
|
|
|
<pre><b>typedef enum {
|
|
LZ4F_default=0,
|
|
LZ4F_max64KB=4,
|
|
LZ4F_max256KB=5,
|
|
LZ4F_max1MB=6,
|
|
LZ4F_max4MB=7
|
|
LZ4F_OBSOLETE_ENUM(max64KB)
|
|
LZ4F_OBSOLETE_ENUM(max256KB)
|
|
LZ4F_OBSOLETE_ENUM(max1MB)
|
|
LZ4F_OBSOLETE_ENUM(max4MB)
|
|
} LZ4F_blockSizeID_t;
|
|
</b></pre><BR>
|
|
<pre><b>typedef enum {
|
|
LZ4F_blockLinked=0,
|
|
LZ4F_blockIndependent
|
|
LZ4F_OBSOLETE_ENUM(blockLinked)
|
|
LZ4F_OBSOLETE_ENUM(blockIndependent)
|
|
} LZ4F_blockMode_t;
|
|
</b></pre><BR>
|
|
<pre><b>typedef enum {
|
|
LZ4F_noContentChecksum=0,
|
|
LZ4F_contentChecksumEnabled
|
|
LZ4F_OBSOLETE_ENUM(noContentChecksum)
|
|
LZ4F_OBSOLETE_ENUM(contentChecksumEnabled)
|
|
} LZ4F_contentChecksum_t;
|
|
</b></pre><BR>
|
|
<pre><b>typedef enum {
|
|
LZ4F_noBlockChecksum=0,
|
|
LZ4F_blockChecksumEnabled
|
|
} LZ4F_blockChecksum_t;
|
|
</b></pre><BR>
|
|
<pre><b>typedef enum {
|
|
LZ4F_frame=0,
|
|
LZ4F_skippableFrame
|
|
LZ4F_OBSOLETE_ENUM(skippableFrame)
|
|
} LZ4F_frameType_t;
|
|
</b></pre><BR>
|
|
<pre><b>typedef struct {
|
|
LZ4F_blockSizeID_t blockSizeID; </b>/* max64KB, max256KB, max1MB, max4MB; 0 == default */<b>
|
|
LZ4F_blockMode_t blockMode; </b>/* LZ4F_blockLinked, LZ4F_blockIndependent; 0 == default */<b>
|
|
LZ4F_contentChecksum_t contentChecksumFlag; </b>/* 1: frame terminated with 32-bit checksum of decompressed data; 0: disabled (default) */<b>
|
|
LZ4F_frameType_t frameType; </b>/* read-only field : LZ4F_frame or LZ4F_skippableFrame */<b>
|
|
unsigned long long contentSize; </b>/* Size of uncompressed content ; 0 == unknown */<b>
|
|
unsigned dictID; </b>/* Dictionary ID, sent by compressor to help decoder select correct dictionary; 0 == no dictID provided */<b>
|
|
LZ4F_blockChecksum_t blockChecksumFlag; </b>/* 1: each block followed by a checksum of block's compressed data; 0: disabled (default) */<b>
|
|
} LZ4F_frameInfo_t;
|
|
</b><p> makes it possible to set or read frame parameters.
|
|
Structure must be first init to 0, using memset() or LZ4F_INIT_FRAMEINFO,
|
|
setting all parameters to default.
|
|
It's then possible to update selectively some parameters
|
|
</p></pre><BR>
|
|
|
|
<pre><b>typedef struct {
|
|
LZ4F_frameInfo_t frameInfo;
|
|
int compressionLevel; </b>/* 0: default (fast mode); values > LZ4HC_CLEVEL_MAX count as LZ4HC_CLEVEL_MAX; values < 0 trigger "fast acceleration" */<b>
|
|
unsigned autoFlush; </b>/* 1: always flush; reduces usage of internal buffers */<b>
|
|
unsigned favorDecSpeed; </b>/* 1: parser favors decompression speed vs compression ratio. Only works for high compression modes (>= LZ4HC_CLEVEL_OPT_MIN) */ /* v1.8.2+ */<b>
|
|
unsigned reserved[3]; </b>/* must be zero for forward compatibility */<b>
|
|
} LZ4F_preferences_t;
|
|
</b><p> makes it possible to supply advanced compression instructions to streaming interface.
|
|
Structure must be first init to 0, using memset() or LZ4F_INIT_PREFERENCES,
|
|
setting all parameters to default.
|
|
All reserved fields must be set to zero.
|
|
</p></pre><BR>
|
|
|
|
<a name="Chapter5"></a><h2>Simple compression function</h2><pre></pre>
|
|
|
|
<pre><b>size_t LZ4F_compressFrameBound(size_t srcSize, const LZ4F_preferences_t* preferencesPtr);
|
|
</b><p> Returns the maximum possible compressed size with LZ4F_compressFrame() given srcSize and preferences.
|
|
`preferencesPtr` is optional. It can be replaced by NULL, in which case, the function will assume default preferences.
|
|
Note : this result is only usable with LZ4F_compressFrame().
|
|
It may also be used with LZ4F_compressUpdate() _if no flush() operation_ is performed.
|
|
|
|
</p></pre><BR>
|
|
|
|
<pre><b>size_t LZ4F_compressFrame(void* dstBuffer, size_t dstCapacity,
|
|
const void* srcBuffer, size_t srcSize,
|
|
const LZ4F_preferences_t* preferencesPtr);
|
|
</b><p> Compress an entire srcBuffer into a valid LZ4 frame.
|
|
dstCapacity MUST be >= LZ4F_compressFrameBound(srcSize, preferencesPtr).
|
|
The LZ4F_preferences_t structure is optional : you can provide NULL as argument. All preferences will be set to default.
|
|
@return : number of bytes written into dstBuffer.
|
|
or an error code if it fails (can be tested using LZ4F_isError())
|
|
|
|
</p></pre><BR>
|
|
|
|
<a name="Chapter6"></a><h2>Advanced compression functions</h2><pre></pre>
|
|
|
|
<pre><b>typedef struct {
|
|
unsigned stableSrc; </b>/* 1 == src content will remain present on future calls to LZ4F_compress(); skip copying src content within tmp buffer */<b>
|
|
unsigned reserved[3];
|
|
} LZ4F_compressOptions_t;
|
|
</b></pre><BR>
|
|
<a name="Chapter7"></a><h2>Resource Management</h2><pre></pre>
|
|
|
|
<pre><b>LZ4F_errorCode_t LZ4F_createCompressionContext(LZ4F_cctx** cctxPtr, unsigned version);
|
|
LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx);
|
|
</b><p> The first thing to do is to create a compressionContext object, which will be used in all compression operations.
|
|
This is achieved using LZ4F_createCompressionContext(), which takes as argument a version.
|
|
The version provided MUST be LZ4F_VERSION. It is intended to track potential version mismatch, notably when using DLL.
|
|
The function will provide a pointer to a fully allocated LZ4F_cctx object.
|
|
If @return != zero, there was an error during context creation.
|
|
Object can release its memory using LZ4F_freeCompressionContext();
|
|
|
|
</p></pre><BR>
|
|
|
|
<a name="Chapter8"></a><h2>Compression</h2><pre></pre>
|
|
|
|
<pre><b>size_t LZ4F_compressBegin(LZ4F_cctx* cctx,
|
|
void* dstBuffer, size_t dstCapacity,
|
|
const LZ4F_preferences_t* prefsPtr);
|
|
</b><p> will write the frame header into dstBuffer.
|
|
dstCapacity must be >= LZ4F_HEADER_SIZE_MAX bytes.
|
|
`prefsPtr` is optional : you can provide NULL as argument, all preferences will then be set to default.
|
|
@return : number of bytes written into dstBuffer for the header
|
|
or an error code (which can be tested using LZ4F_isError())
|
|
|
|
</p></pre><BR>
|
|
|
|
<pre><b>size_t LZ4F_compressBound(size_t srcSize, const LZ4F_preferences_t* prefsPtr);
|
|
</b><p> Provides minimum dstCapacity required to guarantee success of
|
|
LZ4F_compressUpdate(), given a srcSize and preferences, for a worst case scenario.
|
|
When srcSize==0, LZ4F_compressBound() provides an upper bound for LZ4F_flush() and LZ4F_compressEnd() instead.
|
|
Note that the result is only valid for a single invocation of LZ4F_compressUpdate().
|
|
When invoking LZ4F_compressUpdate() multiple times,
|
|
if the output buffer is gradually filled up instead of emptied and re-used from its start,
|
|
one must check if there is enough remaining capacity before each invocation, using LZ4F_compressBound().
|
|
@return is always the same for a srcSize and prefsPtr.
|
|
prefsPtr is optional : when NULL is provided, preferences will be set to cover worst case scenario.
|
|
tech details :
|
|
@return if automatic flushing is not enabled, includes the possibility that internal buffer might already be filled by up to (blockSize-1) bytes.
|
|
It also includes frame footer (ending + checksum), since it might be generated by LZ4F_compressEnd().
|
|
@return doesn't include frame header, as it was already generated by LZ4F_compressBegin().
|
|
|
|
</p></pre><BR>
|
|
|
|
<pre><b>size_t LZ4F_compressUpdate(LZ4F_cctx* cctx,
|
|
void* dstBuffer, size_t dstCapacity,
|
|
const void* srcBuffer, size_t srcSize,
|
|
const LZ4F_compressOptions_t* cOptPtr);
|
|
</b><p> LZ4F_compressUpdate() can be called repetitively to compress as much data as necessary.
|
|
Important rule: dstCapacity MUST be large enough to ensure operation success even in worst case situations.
|
|
This value is provided by LZ4F_compressBound().
|
|
If this condition is not respected, LZ4F_compress() will fail (result is an errorCode).
|
|
LZ4F_compressUpdate() doesn't guarantee error recovery.
|
|
When an error occurs, compression context must be freed or resized.
|
|
`cOptPtr` is optional : NULL can be provided, in which case all options are set to default.
|
|
@return : number of bytes written into `dstBuffer` (it can be zero, meaning input data was just buffered).
|
|
or an error code if it fails (which can be tested using LZ4F_isError())
|
|
|
|
</p></pre><BR>
|
|
|
|
<pre><b>size_t LZ4F_flush(LZ4F_cctx* cctx,
|
|
void* dstBuffer, size_t dstCapacity,
|
|
const LZ4F_compressOptions_t* cOptPtr);
|
|
</b><p> When data must be generated and sent immediately, without waiting for a block to be completely filled,
|
|
it's possible to call LZ4_flush(). It will immediately compress any data buffered within cctx.
|
|
`dstCapacity` must be large enough to ensure the operation will be successful.
|
|
`cOptPtr` is optional : it's possible to provide NULL, all options will be set to default.
|
|
@return : nb of bytes written into dstBuffer (can be zero, when there is no data stored within cctx)
|
|
or an error code if it fails (which can be tested using LZ4F_isError())
|
|
Note : LZ4F_flush() is guaranteed to be successful when dstCapacity >= LZ4F_compressBound(0, prefsPtr).
|
|
|
|
</p></pre><BR>
|
|
|
|
<pre><b>size_t LZ4F_compressEnd(LZ4F_cctx* cctx,
|
|
void* dstBuffer, size_t dstCapacity,
|
|
const LZ4F_compressOptions_t* cOptPtr);
|
|
</b><p> To properly finish an LZ4 frame, invoke LZ4F_compressEnd().
|
|
It will flush whatever data remained within `cctx` (like LZ4_flush())
|
|
and properly finalize the frame, with an endMark and a checksum.
|
|
`cOptPtr` is optional : NULL can be provided, in which case all options will be set to default.
|
|
@return : nb of bytes written into dstBuffer, necessarily >= 4 (endMark),
|
|
or an error code if it fails (which can be tested using LZ4F_isError())
|
|
Note : LZ4F_compressEnd() is guaranteed to be successful when dstCapacity >= LZ4F_compressBound(0, prefsPtr).
|
|
A successful call to LZ4F_compressEnd() makes `cctx` available again for another compression task.
|
|
|
|
</p></pre><BR>
|
|
|
|
<a name="Chapter9"></a><h2>Decompression functions</h2><pre></pre>
|
|
|
|
<pre><b>typedef struct {
|
|
unsigned stableDst; </b>/* pledges that last 64KB decompressed data will remain available unmodified. This optimization skips storage operations in tmp buffers. */<b>
|
|
unsigned reserved[3]; </b>/* must be set to zero for forward compatibility */<b>
|
|
} LZ4F_decompressOptions_t;
|
|
</b></pre><BR>
|
|
<pre><b>LZ4F_errorCode_t LZ4F_createDecompressionContext(LZ4F_dctx** dctxPtr, unsigned version);
|
|
LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* dctx);
|
|
</b><p> Create an LZ4F_dctx object, to track all decompression operations.
|
|
The version provided MUST be LZ4F_VERSION.
|
|
The function provides a pointer to an allocated and initialized LZ4F_dctx object.
|
|
The result is an errorCode, which can be tested using LZ4F_isError().
|
|
dctx memory can be released using LZ4F_freeDecompressionContext();
|
|
Result of LZ4F_freeDecompressionContext() indicates current state of decompressionContext when being released.
|
|
That is, it should be == 0 if decompression has been completed fully and correctly.
|
|
|
|
</p></pre><BR>
|
|
|
|
<a name="Chapter10"></a><h2>Streaming decompression functions</h2><pre></pre>
|
|
|
|
<pre><b>size_t LZ4F_headerSize(const void* src, size_t srcSize);
|
|
</b><p> Provide the header size of a frame starting at `src`.
|
|
`srcSize` must be >= LZ4F_MIN_SIZE_TO_KNOW_HEADER_LENGTH,
|
|
which is enough to decode the header length.
|
|
@return : size of frame header
|
|
or an error code, which can be tested using LZ4F_isError()
|
|
note : Frame header size is variable, but is guaranteed to be
|
|
>= LZ4F_HEADER_SIZE_MIN bytes, and <= LZ4F_HEADER_SIZE_MAX bytes.
|
|
|
|
</p></pre><BR>
|
|
|
|
<pre><b>size_t LZ4F_getFrameInfo(LZ4F_dctx* dctx,
|
|
LZ4F_frameInfo_t* frameInfoPtr,
|
|
const void* srcBuffer, size_t* srcSizePtr);
|
|
</b><p> This function extracts frame parameters (max blockSize, dictID, etc.).
|
|
Its usage is optional: user can call LZ4F_decompress() directly.
|
|
|
|
Extracted information will fill an existing LZ4F_frameInfo_t structure.
|
|
This can be useful for allocation and dictionary identification purposes.
|
|
|
|
LZ4F_getFrameInfo() can work in the following situations :
|
|
|
|
1) At the beginning of a new frame, before any invocation of LZ4F_decompress().
|
|
It will decode header from `srcBuffer`,
|
|
consuming the header and starting the decoding process.
|
|
|
|
Input size must be large enough to contain the full frame header.
|
|
Frame header size can be known beforehand by LZ4F_headerSize().
|
|
Frame header size is variable, but is guaranteed to be >= LZ4F_HEADER_SIZE_MIN bytes,
|
|
and not more than <= LZ4F_HEADER_SIZE_MAX bytes.
|
|
Hence, blindly providing LZ4F_HEADER_SIZE_MAX bytes or more will always work.
|
|
It's allowed to provide more input data than the header size,
|
|
LZ4F_getFrameInfo() will only consume the header.
|
|
|
|
If input size is not large enough,
|
|
aka if it's smaller than header size,
|
|
function will fail and return an error code.
|
|
|
|
2) After decoding has been started,
|
|
it's possible to invoke LZ4F_getFrameInfo() anytime
|
|
to extract already decoded frame parameters stored within dctx.
|
|
|
|
Note that, if decoding has barely started,
|
|
and not yet read enough information to decode the header,
|
|
LZ4F_getFrameInfo() will fail.
|
|
|
|
The number of bytes consumed from srcBuffer will be updated in *srcSizePtr (necessarily <= original value).
|
|
LZ4F_getFrameInfo() only consumes bytes when decoding has not yet started,
|
|
and when decoding the header has been successful.
|
|
Decompression must then resume from (srcBuffer + *srcSizePtr).
|
|
|
|
@return : a hint about how many srcSize bytes LZ4F_decompress() expects for next call,
|
|
or an error code which can be tested using LZ4F_isError().
|
|
note 1 : in case of error, dctx is not modified. Decoding operation can resume from beginning safely.
|
|
note 2 : frame parameters are *copied into* an already allocated LZ4F_frameInfo_t structure.
|
|
|
|
</p></pre><BR>
|
|
|
|
<pre><b>size_t LZ4F_decompress(LZ4F_dctx* dctx,
|
|
void* dstBuffer, size_t* dstSizePtr,
|
|
const void* srcBuffer, size_t* srcSizePtr,
|
|
const LZ4F_decompressOptions_t* dOptPtr);
|
|
</b><p> Call this function repetitively to regenerate compressed data from `srcBuffer`.
|
|
The function will read up to *srcSizePtr bytes from srcBuffer,
|
|
and decompress data into dstBuffer, of capacity *dstSizePtr.
|
|
|
|
The nb of bytes consumed from srcBuffer will be written into *srcSizePtr (necessarily <= original value).
|
|
The nb of bytes decompressed into dstBuffer will be written into *dstSizePtr (necessarily <= original value).
|
|
|
|
The function does not necessarily read all input bytes, so always check value in *srcSizePtr.
|
|
Unconsumed source data must be presented again in subsequent invocations.
|
|
|
|
`dstBuffer` can freely change between each consecutive function invocation.
|
|
`dstBuffer` content will be overwritten.
|
|
|
|
@return : an hint of how many `srcSize` bytes LZ4F_decompress() expects for next call.
|
|
Schematically, it's the size of the current (or remaining) compressed block + header of next block.
|
|
Respecting the hint provides some small speed benefit, because it skips intermediate buffers.
|
|
This is just a hint though, it's always possible to provide any srcSize.
|
|
|
|
When a frame is fully decoded, @return will be 0 (no more data expected).
|
|
When provided with more bytes than necessary to decode a frame,
|
|
LZ4F_decompress() will stop reading exactly at end of current frame, and @return 0.
|
|
|
|
If decompression failed, @return is an error code, which can be tested using LZ4F_isError().
|
|
After a decompression error, the `dctx` context is not resumable.
|
|
Use LZ4F_resetDecompressionContext() to return to clean state.
|
|
|
|
After a frame is fully decoded, dctx can be used again to decompress another frame.
|
|
|
|
</p></pre><BR>
|
|
|
|
<pre><b>void LZ4F_resetDecompressionContext(LZ4F_dctx* dctx); </b>/* always successful */<b>
|
|
</b><p> In case of an error, the context is left in "undefined" state.
|
|
In which case, it's necessary to reset it, before re-using it.
|
|
This method can also be used to abruptly stop any unfinished decompression,
|
|
and start a new one using same context resources.
|
|
</p></pre><BR>
|
|
|
|
<pre><b>typedef enum { LZ4F_LIST_ERRORS(LZ4F_GENERATE_ENUM)
|
|
_LZ4F_dummy_error_enum_for_c89_never_used } LZ4F_errorCodes;
|
|
</b></pre><BR>
|
|
<a name="Chapter11"></a><h2>Bulk processing dictionary API</h2><pre></pre>
|
|
|
|
<pre><b>LZ4FLIB_STATIC_API LZ4F_CDict* LZ4F_createCDict(const void* dictBuffer, size_t dictSize);
|
|
LZ4FLIB_STATIC_API void LZ4F_freeCDict(LZ4F_CDict* CDict);
|
|
</b><p> When compressing multiple messages / blocks using the same dictionary, it's recommended to load it just once.
|
|
LZ4_createCDict() will create a digested dictionary, ready to start future compression operations without startup delay.
|
|
LZ4_CDict can be created once and shared by multiple threads concurrently, since its usage is read-only.
|
|
`dictBuffer` can be released after LZ4_CDict creation, since its content is copied within CDict
|
|
</p></pre><BR>
|
|
|
|
<pre><b>LZ4FLIB_STATIC_API size_t LZ4F_compressFrame_usingCDict(
|
|
LZ4F_cctx* cctx,
|
|
void* dst, size_t dstCapacity,
|
|
const void* src, size_t srcSize,
|
|
const LZ4F_CDict* cdict,
|
|
const LZ4F_preferences_t* preferencesPtr);
|
|
</b><p> Compress an entire srcBuffer into a valid LZ4 frame using a digested Dictionary.
|
|
cctx must point to a context created by LZ4F_createCompressionContext().
|
|
If cdict==NULL, compress without a dictionary.
|
|
dstBuffer MUST be >= LZ4F_compressFrameBound(srcSize, preferencesPtr).
|
|
If this condition is not respected, function will fail (@return an errorCode).
|
|
The LZ4F_preferences_t structure is optional : you may provide NULL as argument,
|
|
but it's not recommended, as it's the only way to provide dictID in the frame header.
|
|
@return : number of bytes written into dstBuffer.
|
|
or an error code if it fails (can be tested using LZ4F_isError())
|
|
</p></pre><BR>
|
|
|
|
<pre><b>LZ4FLIB_STATIC_API size_t LZ4F_compressBegin_usingCDict(
|
|
LZ4F_cctx* cctx,
|
|
void* dstBuffer, size_t dstCapacity,
|
|
const LZ4F_CDict* cdict,
|
|
const LZ4F_preferences_t* prefsPtr);
|
|
</b><p> Inits streaming dictionary compression, and writes the frame header into dstBuffer.
|
|
dstCapacity must be >= LZ4F_HEADER_SIZE_MAX bytes.
|
|
`prefsPtr` is optional : you may provide NULL as argument,
|
|
however, it's the only way to provide dictID in the frame header.
|
|
@return : number of bytes written into dstBuffer for the header,
|
|
or an error code (which can be tested using LZ4F_isError())
|
|
</p></pre><BR>
|
|
|
|
<pre><b>LZ4FLIB_STATIC_API size_t LZ4F_decompress_usingDict(
|
|
LZ4F_dctx* dctxPtr,
|
|
void* dstBuffer, size_t* dstSizePtr,
|
|
const void* srcBuffer, size_t* srcSizePtr,
|
|
const void* dict, size_t dictSize,
|
|
const LZ4F_decompressOptions_t* decompressOptionsPtr);
|
|
</b><p> Same as LZ4F_decompress(), using a predefined dictionary.
|
|
Dictionary is used "in place", without any preprocessing.
|
|
It must remain accessible throughout the entire frame decoding.
|
|
</p></pre><BR>
|
|
|
|
</html>
|
|
</body>
|