diff options
Diffstat (limited to 'doc/lz4frame_manual.html')
| -rw-r--r-- | doc/lz4frame_manual.html | 106 |
1 files changed, 74 insertions, 32 deletions
diff --git a/doc/lz4frame_manual.html b/doc/lz4frame_manual.html index fb8e0ce..914405f 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.3 Manual</title> +<title>1.9.0 Manual</title> </head> <body> -<h1>1.8.3 Manual</h1> +<h1>1.9.0 Manual</h1> <hr> <a name="Contents"></a><h2>Contents</h2> <ol> @@ -84,19 +84,21 @@ 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. - For all fields, 0 sets it to default value + 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, 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 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 detailed compression parameters to the stream interface. - Structure is presumed initially memset() to zero, representing default settings. +</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> @@ -155,15 +157,19 @@ 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 minimum dstCapacity required to guarantee compression success - given a srcSize and preferences, covering worst case scenario. +</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. - 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. + tech details : + @return 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> @@ -192,6 +198,7 @@ LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx); `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> @@ -204,6 +211,7 @@ LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx); `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> @@ -229,25 +237,58 @@ LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* dctx); <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. - Extracted information is typically useful for allocation and dictionary. - This function works in 2 situations : - - At the beginning of a new frame, in which case - it will decode information from `srcBuffer`, starting the decoding process. - Input size must be large enough to successfully decode the entire frame header. - Frame header size is variable, but is guaranteed to be <= LZ4F_HEADER_SIZE_MAX bytes. - It's allowed to provide more input data than this minimum. - - After decoding has been started. - In which case, no input is read, frame parameters are extracted from dctx. - - If decoding has barely started, but not yet extracted information from header, + 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 within *srcSizePtr (necessarily <= original value). - Decompression must resume from (srcBuffer + *srcSizePtr). - @return : an hint about how many srcSize bytes LZ4F_decompress() expects for next call, + + 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. @@ -295,13 +336,14 @@ 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; +<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 with the same dictionary, it's recommended to load it just once. +</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 |