diff options
Diffstat (limited to 'doc/lz4frame_manual.html')
| -rw-r--r-- | doc/lz4frame_manual.html | 156 |
1 files changed, 113 insertions, 43 deletions
diff --git a/doc/lz4frame_manual.html b/doc/lz4frame_manual.html index 590c632..53ea7eb 100644 --- a/doc/lz4frame_manual.html +++ b/doc/lz4frame_manual.html @@ -1,10 +1,10 @@ <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> -<title>1.8.1 Manual</title> +<title>1.8.2 Manual</title> </head> <body> -<h1>1.8.1 Manual</h1> +<h1>1.8.2 Manual</h1> <hr> <a name="Contents"></a><h2>Contents</h2> <ol> @@ -18,6 +18,7 @@ <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> @@ -30,9 +31,9 @@ <a name="Chapter3"></a><h2>Error management</h2><pre></pre> -<pre><b>unsigned LZ4F_isError(LZ4F_errorCode_t code); </b>/**< tells if a `LZ4F_errorCode_t` function result is an error code */<b> +<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; useful for debugging */<b> +<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> @@ -74,13 +75,13 @@ } 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>/* if enabled, frame is terminated with a 32-bits 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 the compressor to help decoder select the correct dictionary; 0 == no dictID provided */<b> - LZ4F_blockChecksum_t blockChecksumFlag; </b>/* if enabled, each block is followed by a checksum of block's compressed data ; 0 == disabled (default) */<b> + 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. It's not required to set all fields, as long as the structure was initially memset() to zero. @@ -89,20 +90,23 @@ <pre><b>typedef struct { LZ4F_frameInfo_t frameInfo; - int compressionLevel; </b>/* 0 == default (fast mode); values above LZ4HC_CLEVEL_MAX count as LZ4HC_CLEVEL_MAX; values below 0 trigger "fast acceleration", proportional to value */<b> - unsigned autoFlush; </b>/* 1 == always flush, to reduce usage of internal buffers */<b> - unsigned reserved[4]; </b>/* must be zero for forward compatibility */<b> + 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, to reduce usage of internal buffers */<b> + unsigned favorDecSpeed; </b>/* 1: parser favors decompression speed vs compression ratio. Only works for high compression modes (>= LZ4LZ4HC_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 detailed compression parameters to the stream interface. - It's not required to set all fields, as long as the structure was initially memset() to zero. + Structure is presumed initially memset() to zero, representing default settings. 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 size of a frame compressed with LZ4F_compressFrame() given srcSize content and preferences. - Note : this result is only usable with LZ4F_compressFrame(), not with multi-segments compression. +</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> @@ -151,41 +155,54 @@ LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx); </p></pre><BR> <pre><b>size_t LZ4F_compressBound(size_t srcSize, const LZ4F_preferences_t* prefsPtr); -</b><p> Provides dstCapacity given a srcSize to guarantee operation success in worst case situations. - prefsPtr is optional : you can provide NULL as argument, preferences will be set to cover worst case scenario. - Result is always the same for a srcSize and prefsPtr, so it can be trusted to size reusable buffers. - When srcSize==0, LZ4F_compressBound() provides an upper bound for LZ4F_flush() and LZ4F_compressEnd() operations. +</b><p> Provides minimum dstCapacity required to guarantee compression success + given a srcSize and preferences, covering worst case scenario. + prefsPtr is optional : when NULL is provided, preferences will be set to cover worst case scenario. + Estimation is valid for either LZ4F_compressUpdate(), LZ4F_flush() or LZ4F_compressEnd(), + Estimation includes the possibility that internal buffer might already be filled by up to (blockSize-1) bytes. + It also includes frame footer (ending + checksum), which would have to be generated by LZ4F_compressEnd(). + Estimation doesn't include frame header, as it was already generated by LZ4F_compressBegin(). + Result is always the same for a srcSize and prefsPtr, so it can be trusted to size reusable buffers. + When srcSize==0, LZ4F_compressBound() provides an upper bound for LZ4F_flush() and LZ4F_compressEnd() operations. </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. - An important rule is that 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. +<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. +<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 : number of bytes written into dstBuffer (it can be zero, which means there was no data stored within cctx) + @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()) </p></pre><BR> -<pre><b>size_t LZ4F_compressEnd(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const LZ4F_compressOptions_t* cOptPtr); +<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 : number of bytes written into dstBuffer (necessarily >= 4 (endMark), or 8 if optional frame checksum is enabled) + @return : nb of bytes written into dstBuffer, necessarily >= 4 (endMark), or an error code if it fails (which can be tested using LZ4F_isError()) A successful call to LZ4F_compressEnd() makes `cctx` available again for another compression task. @@ -194,19 +211,19 @@ LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx); <a name="Chapter9"></a><h2>Decompression functions</h2><pre></pre> <pre><b>typedef struct { - unsigned stableDst; </b>/* pledge that at least 64KB+64Bytes of previously decompressed data remain unmodifed where it was decoded. This optimization skips storage operations in tmp buffers */<b> + 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(); - The result of LZ4F_freeDecompressionContext() is indicative of the current state of decompressionContext when being released. - That is, it should be == 0 if decompression has been completed fully and correctly. +</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> @@ -245,8 +262,8 @@ LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* dctx); The function will read up to *srcSizePtr bytes from srcBuffer, and decompress data into dstBuffer, of capacity *dstSizePtr. - The number of bytes consumed from srcBuffer will be written into *srcSizePtr (necessarily <= original value). - The number of bytes decompressed into dstBuffer will be written into *dstSizePtr (necessarily <= original value). + 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. @@ -278,5 +295,58 @@ LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* dctx); and start a new one using same context resources. </p></pre><BR> +<pre><b>typedef enum { LZ4F_LIST_ERRORS(LZ4F_GENERATE_ENUM) } 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 with 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> |