diff options
Diffstat (limited to 'doc/lz4frame_manual.html')
| -rw-r--r-- | doc/lz4frame_manual.html | 126 |
1 files changed, 78 insertions, 48 deletions
diff --git a/doc/lz4frame_manual.html b/doc/lz4frame_manual.html index 196881e4..cfb437e4 100644 --- a/doc/lz4frame_manual.html +++ b/doc/lz4frame_manual.html @@ -22,9 +22,9 @@ </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. + lz4frame.h implements LZ4 frame specification: see doc/lz4_Frame_format.md . + LZ4 Frames are compatible with `lz4` CLI, + and designed to be interoperable with any system. <BR></pre> <a name="Chapter2"></a><h2>Compiler specifics</h2><pre></pre> @@ -135,17 +135,19 @@ <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 keep track of operation state during streaming compression. - 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 context creation failed. - Once all streaming compression jobs are completed, - the state object can be released using LZ4F_freeCompressionContext(). - Note1 : LZ4F_freeCompressionContext() is always successful. Its return value can be ignored. - Note2 : LZ4F_freeCompressionContext() works fine with NULL input pointers (do nothing). - +</b><p> The first thing to do is to create a compressionContext object, + which will keep track of operation state during streaming compression. + This is achieved using LZ4F_createCompressionContext(), which takes as argument a version, + and a pointer to LZ4F_cctx*, to write the resulting pointer into. + @version provided MUST be LZ4F_VERSION. It is intended to track potential version mismatch, notably when using DLL. + The function provides a pointer to a fully allocated LZ4F_cctx object. + @cctxPtr MUST be != NULL. + If @return != zero, context creation failed. + A created compression context can be employed multiple times for consecutive streaming operations. + Once all streaming compression jobs are completed, + the state object can be released using LZ4F_freeCompressionContext(). + Note1 : LZ4F_freeCompressionContext() is always successful. Its return value can be ignored. + Note2 : LZ4F_freeCompressionContext() works fine with NULL input pointers (do nothing). </p></pre><BR> <a name="Chapter8"></a><h2>Compression</h2><pre></pre> @@ -225,16 +227,21 @@ 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>/* 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> + unsigned stableDst; /* pledges that last 64KB decompressed data will remain available unmodified between invocations. + * This optimization skips storage operations in tmp buffers. */ + unsigned skipChecksums; /* disable checksum calculation and verification, even when one is present in frame, to save CPU time. + * Setting this option to 1 once disables all checksums for the rest of the frame. */ + unsigned reserved1; </b>/* must be set to zero for forward compatibility */<b> + unsigned reserved0; </b>/* idem */<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(). + @version provided MUST be LZ4F_VERSION. + @dctxPtr MUST be valid. + The function fills @dctxPtr with the value of a pointer to an allocated and initialized LZ4F_dctx object. + The @return 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. @@ -254,11 +261,12 @@ LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* dctx); </p></pre><BR> -<pre><b>size_t LZ4F_getFrameInfo(LZ4F_dctx* dctx, - LZ4F_frameInfo_t* frameInfoPtr, - const void* srcBuffer, size_t* srcSizePtr); +<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. + Its usage is optional: user can also invoke LZ4F_decompress() directly. Extracted information will fill an existing LZ4F_frameInfo_t structure. This can be useful for allocation and dictionary identification purposes. @@ -301,10 +309,11 @@ LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* dctx); </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); +<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 data compressed in `srcBuffer`. The function requires a valid dctx state. @@ -352,10 +361,11 @@ LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* dctx); the maximum block size associated with blockSizeID. </p></pre><BR> -<pre><b>LZ4FLIB_STATIC_API size_t LZ4F_uncompressedUpdate(LZ4F_cctx* cctx, - void* dstBuffer, size_t dstCapacity, - const void* srcBuffer, size_t srcSize, - const LZ4F_compressOptions_t* cOptPtr); +<pre><b>LZ4FLIB_STATIC_API size_t +LZ4F_uncompressedUpdate(LZ4F_cctx* cctx, + void* dstBuffer, size_t dstCapacity, + const void* srcBuffer, size_t srcSize, + const LZ4F_compressOptions_t* cOptPtr); </b><p> LZ4F_uncompressedUpdate() can be called repetitively to add as much data uncompressed data as necessary. Important rule: dstCapacity MUST be large enough to store the entire source buffer as no compression is done for this operation @@ -380,12 +390,12 @@ LZ4FLIB_STATIC_API void LZ4F_freeCDict(LZ4F_CDict* CDict); `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); +<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. @@ -397,11 +407,11 @@ LZ4FLIB_STATIC_API void LZ4F_freeCDict(LZ4F_CDict* CDict); 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); +<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, @@ -410,16 +420,36 @@ LZ4FLIB_STATIC_API void LZ4F_freeCDict(LZ4F_CDict* CDict); 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); +<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> +<pre><b>typedef void* (*LZ4F_AllocFunction) (void* opaqueState, size_t size); +typedef void* (*LZ4F_CallocFunction) (void* opaqueState, size_t size); +typedef void (*LZ4F_FreeFunction) (void* opaqueState, void* address); +typedef struct { + LZ4F_AllocFunction customAlloc; + LZ4F_CallocFunction customCalloc; </b>/* optional; when not defined, uses customAlloc + memset */<b> + LZ4F_FreeFunction customFree; + void* opaqueState; +} LZ4F_CustomMem; +static +#ifdef __GNUC__ +__attribute__((__unused__)) +#endif +LZ4F_CustomMem const LZ4F_defaultCMem = { NULL, NULL, NULL, NULL }; </b>/**< this constant defers to stdlib's functions */<b> +</b><p> These prototypes make it possible to pass custom allocation/free functions. + LZ4F_customMem is provided at state creation time, using LZ4F_create*_advanced() listed below. + All allocation/free operations will be completed using these custom variants instead of regular <stdlib.h> ones. + +</p></pre><BR> + </html> </body> |