diff options
author | Yann Collet <Cyan4973@users.noreply.github.com> | 2018-09-11 19:52:06 (GMT) |
---|---|---|
committer | GitHub <noreply@github.com> | 2018-09-11 19:52:06 (GMT) |
commit | 641b453d9db536ee020851bfcb1dc39f61006f0a (patch) | |
tree | 0a0c78c393d0732bf85464275f5053ad96ff4eab /doc/lz4_manual.html | |
parent | b3692db46d2b23a7c0af2d5e69988c94f126e10a (diff) | |
parent | 08d347b5b217b011ff7487130b79480d8cfdaeb8 (diff) | |
download | lz4-641b453d9db536ee020851bfcb1dc39f61006f0a.zip lz4-641b453d9db536ee020851bfcb1dc39f61006f0a.tar.gz lz4-641b453d9db536ee020851bfcb1dc39f61006f0a.tar.bz2 |
Merge pull request #572 from lz4/devv1.8.3
v1.8.3
Diffstat (limited to 'doc/lz4_manual.html')
-rw-r--r-- | doc/lz4_manual.html | 111 |
1 files changed, 70 insertions, 41 deletions
diff --git a/doc/lz4_manual.html b/doc/lz4_manual.html index e5044fe..6ebf8d2 100644 --- a/doc/lz4_manual.html +++ b/doc/lz4_manual.html @@ -1,10 +1,10 @@ <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> -<title>1.8.2 Manual</title> +<title>1.8.3 Manual</title> </head> <body> -<h1>1.8.2 Manual</h1> +<h1>1.8.3 Manual</h1> <hr> <a name="Contents"></a><h2>Contents</h2> <ol> @@ -110,45 +110,67 @@ int LZ4_compress_fast_extState (void* state, const char* src, char* dst, int src </b><p> Same compression function, just using an externally allocated memory space to store compression state. Use LZ4_sizeofState() to know how much memory must be allocated, and allocate it on 8-bytes boundaries (using malloc() typically). - Then, provide it as 'void* state' to compression function. + Then, provide this buffer as 'void* state' to compression function. </p></pre><BR> <pre><b>int LZ4_compress_destSize (const char* src, char* dst, int* srcSizePtr, int targetDstSize); -</b><p> Reverse the logic : compresses as much data as possible from 'src' buffer - into already allocated buffer 'dst' of size 'targetDestSize'. - This function either compresses the entire 'src' content into 'dst' if it's large enough, - or fill 'dst' buffer completely with as much data as possible from 'src'. - *srcSizePtr : will be modified to indicate how many bytes where read from 'src' to fill 'dst'. - New value is necessarily <= old value. - return : Nb bytes written into 'dst' (necessarily <= targetDestSize) - or 0 if compression fails +</b><p> Reverse the logic : compresses as much data as possible from 'src' buffer + into already allocated buffer 'dst', of size >= 'targetDestSize'. + This function either compresses the entire 'src' content into 'dst' if it's large enough, + or fill 'dst' buffer completely with as much data as possible from 'src'. + note: acceleration parameter is fixed to "default". + + *srcSizePtr : will be modified to indicate how many bytes where read from 'src' to fill 'dst'. + New value is necessarily <= input value. + @return : Nb bytes written into 'dst' (necessarily <= targetDestSize) + or 0 if compression fails. </p></pre><BR> <pre><b>int LZ4_decompress_fast (const char* src, char* dst, int originalSize); -</b><p>This function is a bit faster than LZ4_decompress_safe(), -but it may misbehave on malformed input because it doesn't perform full validation of compressed data. - originalSize : is the uncompressed size to regenerate - Destination buffer must be already allocated, and its size must be >= 'originalSize' bytes. - return : number of bytes read from source buffer (== compressed size). - If the source stream is detected malformed, the function stops decoding and return a negative result. - note : This function is only usable if the originalSize of uncompressed data is known in advance. - The caller should also check that all the compressed input has been consumed properly, - i.e. that the return value matches the size of the buffer with compressed input. - The function never writes past the output buffer. However, since it doesn't know its 'src' size, - it may read past the intended input. Also, because match offsets are not validated during decoding, - reads from 'src' may underflow. Use this function in trusted environment **only**. +</b><p> This function used to be a bit faster than LZ4_decompress_safe(), + though situation has changed in recent versions, + and now `LZ4_decompress_safe()` can be as fast and sometimes faster than `LZ4_decompress_fast()`. + Moreover, LZ4_decompress_fast() is not protected vs malformed input, as it doesn't perform full validation of compressed data. + As a consequence, this function is no longer recommended, and may be deprecated in future versions. + It's only remaining specificity is that it can decompress data without knowing its compressed size. + + originalSize : is the uncompressed size to regenerate. + `dst` must be already allocated, its size must be >= 'originalSize' bytes. + @return : number of bytes read from source buffer (== compressed size). + If the source stream is detected malformed, the function stops decoding and returns a negative result. + note : This function requires uncompressed originalSize to be known in advance. + The function never writes past the output buffer. + However, since it doesn't know its 'src' size, it may read past the intended input. + Also, because match offsets are not validated during decoding, + reads from 'src' may underflow. + Use this function in trusted environment **only**. + </p></pre><BR> <pre><b>int LZ4_decompress_safe_partial (const char* src, char* dst, int srcSize, int targetOutputSize, int dstCapacity); -</b><p> This function decompress a compressed block of size 'srcSize' at position 'src' - into destination buffer 'dst' of size 'dstCapacity'. - The function will decompress a minimum of 'targetOutputSize' bytes, and stop after that. - However, it's not accurate, and may write more than 'targetOutputSize' (but always <= dstCapacity). - @return : the number of bytes decoded in the destination buffer (necessarily <= dstCapacity) - Note : this number can also be < targetOutputSize, if compressed block contains less data. - Therefore, always control how many bytes were decoded. - If source stream is detected malformed, function returns a negative result. - This function is protected against malicious data packets. +</b><p> Decompress an LZ4 compressed block, of size 'srcSize' at position 'src', + into destination buffer 'dst' of size 'dstCapacity'. + Up to 'targetOutputSize' bytes will be decoded. + The function stops decoding on reaching this objective, + which can boost performance when only the beginning of a block is required. + + @return : the number of bytes decoded in `dst` (necessarily <= dstCapacity) + If source stream is detected malformed, function returns a negative result. + + Note : @return can be < targetOutputSize, if compressed block contains less data. + + Note 2 : this function features 2 parameters, targetOutputSize and dstCapacity, + and expects targetOutputSize <= dstCapacity. + It effectively stops decoding on reaching targetOutputSize, + so dstCapacity is kind of redundant. + This is because in a previous version of this function, + decoding operation would not "break" a sequence in the middle. + As a consequence, there was no guarantee that decoding would stop at exactly targetOutputSize, + it could write more bytes, though only up to dstCapacity. + Some "margin" used to be required for this operation to work properly. + This is no longer necessary. + The function nonetheless keeps its signature, in an effort to not break API. + </p></pre><BR> <a name="Chapter6"></a><h2>Streaming Compression Functions</h2><pre></pre> @@ -179,16 +201,23 @@ int LZ4_freeStream (LZ4_stream_t* streamPtr); 'dst' buffer must be already allocated. If dstCapacity >= LZ4_compressBound(srcSize), compression is guaranteed to succeed, and runs faster. - Important : The previous 64KB of compressed data is assumed to remain present and unmodified in memory! - - Special 1 : When input is a double-buffer, they can have any size, including < 64 KB. - Make sure that buffers are separated by at least one byte. - This way, each block only depends on previous block. - Special 2 : If input buffer is a ring-buffer, it can have any size, including < 64 KB. - @return : size of compressed block or 0 if there is an error (typically, cannot fit into 'dst'). - After an error, the stream status is invalid, it can only be reset or freed. + + Note 1 : Each invocation to LZ4_compress_fast_continue() generates a new block. + Each block has precise boundaries. + It's not possible to append blocks together and expect a single invocation of LZ4_decompress_*() to decompress them together. + Each block must be decompressed separately, calling LZ4_decompress_*() with associated metadata. + + Note 2 : The previous 64KB of source data is __assumed__ to remain present, unmodified, at same address in memory! + + Note 3 : When input is structured as a double-buffer, each buffer can have any size, including < 64 KB. + Make sure that buffers are separated, by at least one byte. + This construction ensures that each block only depends on previous block. + + Note 4 : If input buffer is a ring-buffer, it can have any size, including < 64 KB. + + Note 5 : After an error, the stream status is invalid, it can only be reset or freed. </p></pre><BR> @@ -214,7 +243,7 @@ int LZ4_freeStreamDecode (LZ4_streamDecode_t* LZ4_stream); <pre><b>int LZ4_setStreamDecode (LZ4_streamDecode_t* LZ4_streamDecode, const char* dictionary, int dictSize); </b><p> An LZ4_streamDecode_t context can be allocated once and re-used multiple times. Use this function to start decompression of a new stream of blocks. - A dictionary can optionnally be set. Use NULL or size 0 for a reset order. + A dictionary can optionally be set. Use NULL or size 0 for a reset order. Dictionary is presumed stable : it must remain accessible and unmodified during next decompression. @return : 1 if OK, 0 if error |