diff options
| author | Yann Collet <cyan@fb.com> | 2017-05-10 20:26:04 (GMT) |
|---|---|---|
| committer | Yann Collet <cyan@fb.com> | 2017-05-10 20:26:04 (GMT) |
| commit | b8575f2d2b1e05c20812215759b29bf2d0f7a708 (patch) | |
| tree | a026a79e25bd21d158905e92a62ab4096fed8be2 /doc/lz4frame_manual.html | |
| parent | fe932c4527aabd1c642b67fddf90e9be8ea380f8 (diff) | |
| download | lz4-b8575f2d2b1e05c20812215759b29bf2d0f7a708.zip lz4-b8575f2d2b1e05c20812215759b29bf2d0f7a708.tar.gz lz4-b8575f2d2b1e05c20812215759b29bf2d0f7a708.tar.bz2 | |
updated Makefile
to automatically build manual files with
make all
Diffstat (limited to 'doc/lz4frame_manual.html')
| -rw-r--r-- | doc/lz4frame_manual.html | 75 |
1 files changed, 52 insertions, 23 deletions
diff --git a/doc/lz4frame_manual.html b/doc/lz4frame_manual.html index f76ec3d..5d553ed 100644 --- a/doc/lz4frame_manual.html +++ b/doc/lz4frame_manual.html @@ -1,19 +1,23 @@ <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> -<title>lz4frame 1.7.5 Manual</title> +<title>1.7.6 Manual</title> </head> <body> -<h1>lz4frame 1.7.5 Manual</h1> +<h1>1.7.6 Manual</h1> <hr> <a name="Contents"></a><h2>Contents</h2> <ol> <li><a href="#Chapter1">Introduction</a></li> -<li><a href="#Chapter2">Error management</a></li> -<li><a href="#Chapter3">Frame compression types</a></li> -<li><a href="#Chapter4">Simple compression function</a></li> -<li><a href="#Chapter5">Advanced compression functions</a></li> -<li><a href="#Chapter6">Decompression functions</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> </ol> <hr> <a name="Chapter1"></a><h2>Introduction</h2><pre> @@ -22,13 +26,15 @@ of encoding standard metadata alongside LZ4-compressed blocks. <BR></pre> -<a name="Chapter2"></a><h2>Error management</h2><pre></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 if a `LZ4F_errorCode_t` 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> </b></pre><BR> -<a name="Chapter3"></a><h2>Frame compression types</h2><pre></pre> +<a name="Chapter4"></a><h2>Frame compression types</h2><pre></pre> <pre><b>typedef enum { LZ4F_default=0, @@ -77,7 +83,7 @@ <pre><b>typedef struct { LZ4F_frameInfo_t frameInfo; - int compressionLevel; </b>/* 0 == default (fast mode); values above 16 count as 16; values below 0 count as 0 */<b> + 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 (reduce usage of tmp buffer) */<b> unsigned reserved[4]; </b>/* must be zero for forward compatibility */<b> } LZ4F_preferences_t; @@ -86,7 +92,7 @@ All reserved fields must be set to zero. </p></pre><BR> -<a name="Chapter4"></a><h2>Simple compression function</h2><pre></pre> +<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. @@ -105,17 +111,19 @@ </p></pre><BR> -<a name="Chapter5"></a><h2>Advanced compression functions</h2><pre></pre> +<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 and an LZ4F_preferences_t structure. + 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. @@ -123,6 +131,8 @@ LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx); </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 large enough to store the header. Maximum header size is LZ4F_HEADER_SIZE_MAX bytes. @@ -173,7 +183,7 @@ LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx); </p></pre><BR> -<a name="Chapter6"></a><h2>Decompression functions</h2><pre></pre> +<a name="Chapter9"></a><h2>Decompression functions</h2><pre></pre> <pre><b>typedef struct { unsigned stableDst; </b>/* guarantee that decompressed data will still be there on next function calls (avoid storage into tmp buffers) */<b> @@ -181,7 +191,7 @@ LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx); } 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* const dctx); +LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* dctx); </b><p> Create an LZ4F_decompressionContext_t object, which will be used to track all decompression operations. The version provided MUST be LZ4F_VERSION. It is intended to track potential breaking differences between different versions. The function will provide a pointer to a fully allocated and initialized LZ4F_decompressionContext_t object. @@ -192,19 +202,27 @@ LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* const dctx); </p></pre><BR> +<a name="Chapter10"></a><h2>Streaming decompression functions</h2><pre></pre> + <pre><b>size_t LZ4F_getFrameInfo(LZ4F_dctx* dctx, LZ4F_frameInfo_t* frameInfoPtr, const void* srcBuffer, size_t* srcSizePtr); -</b><p> This function decodes frame header information (such as max blockSize, frame checksum, etc.). - Its usage is optional. The objective is to extract frame header information, typically for allocation purposes. - A header size is variable and can length from 7 to 15 bytes. It's possible to provide more input bytes than that. +</b><p> This function extracts frame parameters (such as max blockSize, frame checksum, etc.). + Its usage is optional. Extracted information can be useful for allocation purposes, typically. + This function works in 2 situations : + - At the beginning of a new frame, in which case it will decode this information from `srcBuffer`, and start 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 just started, but not yet extracted information from header, LZ4F_getFrameInfo() will fail. The number of bytes consumed from srcBuffer will be updated within *srcSizePtr (necessarily <= original value). - Decompression must resume from this point (srcBuffer + *srcSizePtr). - Note that LZ4F_getFrameInfo() can also be used anytime *after* decompression is started, in which case 0 input byte can be enough. - Frame header info is *copied into* an already allocated LZ4F_frameInfo_t structure. + Decompression must resume from (srcBuffer + *srcSizePtr). @return : an hint about how many srcSize bytes LZ4F_decompress() expects for next call, or an error code which can be tested using LZ4F_isError() - (typically, when there is not enough src bytes to fully decode the frame header) + note 1 : in case of error, dctx is not modified. Decoding operations can resume from where they stopped. + note 2 : frame parameters are *copied into* an already allocated LZ4F_frameInfo_t structure. </p></pre><BR> @@ -227,14 +245,25 @@ LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* const dctx); @return is 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 boost to performance, since it does skip intermediate buffers. + 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). If decompression failed, @return is an error code, which can be tested using LZ4F_isError(). After a frame is fully decoded, dctx can be used again to decompress another frame. + After a decompression error, use LZ4F_resetDecompressionContext() before re-using dctx, to return to clean state. </p></pre><BR> +<pre><b>LZ4F_errorCode_t LZ4F_resetDecompressionContext(LZ4F_dctx* dctx); +</b><p> When decompression ends successfully, + it's possible to start a new decompression immediately + re-using the same context. + However, 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 an unfinished decompression, + and start a new on the same context. +</p></pre><BR> + </html> </body> |