diff options
author | Yann Collet <cyan@fb.com> | 2020-11-08 20:54:59 (GMT) |
---|---|---|
committer | Yann Collet <cyan@fb.com> | 2020-11-08 20:54:59 (GMT) |
commit | be634559e3b6bb7bce77cc83ec2080b2bfb6c844 (patch) | |
tree | c598740ac7a30ec310839a850025d5e20ea7ae55 | |
parent | c41be7e92060cfc2e5f52bcdd7f7426edd4935a4 (diff) | |
download | lz4-be634559e3b6bb7bce77cc83ec2080b2bfb6c844.zip lz4-be634559e3b6bb7bce77cc83ec2080b2bfb6c844.tar.gz lz4-be634559e3b6bb7bce77cc83ec2080b2bfb6c844.tar.bz2 |
update obsolete section documentation
and update manuals.
fix #712
-rw-r--r-- | doc/lz4_manual.html | 63 | ||||
-rw-r--r-- | doc/lz4frame_manual.html | 6 | ||||
-rw-r--r-- | lib/lz4.h | 23 |
3 files changed, 54 insertions, 38 deletions
diff --git a/doc/lz4_manual.html b/doc/lz4_manual.html index 208dbb9..47fe18d 100644 --- a/doc/lz4_manual.html +++ b/doc/lz4_manual.html @@ -16,7 +16,7 @@ <li><a href="#Chapter6">Streaming Compression Functions</a></li> <li><a href="#Chapter7">Streaming Decompression Functions</a></li> <li><a href="#Chapter8">Experimental section</a></li> -<li><a href="#Chapter9">PRIVATE DEFINITIONS</a></li> +<li><a href="#Chapter9">Private Definitions</a></li> <li><a href="#Chapter10">Obsolete Functions</a></li> </ol> <hr> @@ -446,39 +446,33 @@ int LZ4_freeStreamDecode (LZ4_streamDecode_t* LZ4_stream); </b></pre><BR> <pre><b>#define LZ4_COMPRESS_INPLACE_BUFFER_SIZE(maxCompressedSize) ((maxCompressedSize) + LZ4_COMPRESS_INPLACE_MARGIN) </b>/**< maxCompressedSize is generally LZ4_COMPRESSBOUND(inputSize), but can be set to any lower value, with the risk that compression can fail (return code 0(zero)) */<b> </b></pre><BR> -<a name="Chapter9"></a><h2>PRIVATE DEFINITIONS</h2><pre> +<a name="Chapter9"></a><h2>Private Definitions</h2><pre> Do not use these definitions directly. They are only exposed to allow static allocation of `LZ4_stream_t` and `LZ4_streamDecode_t`. - Accessing members will expose code to API and/or ABI break in future versions of the library. + Accessing members will expose user code to API and/or ABI break in future versions of the library. <BR></pre> <pre><b>typedef struct { - const uint8_t* externalDict; + const LZ4_byte* externalDict; size_t extDictSize; - const uint8_t* prefixEnd; + const LZ4_byte* prefixEnd; size_t prefixSize; } LZ4_streamDecode_t_internal; </b></pre><BR> -<pre><b>typedef struct { - const unsigned char* externalDict; - const unsigned char* prefixEnd; - size_t extDictSize; - size_t prefixSize; -} LZ4_streamDecode_t_internal; -</b></pre><BR> -<pre><b>#define LZ4_STREAMSIZE_U64 ((1 << (LZ4_MEMORY_USAGE-3)) + 4 + ((sizeof(void*)==16) ? 4 : 0) </b>/*AS-400*/ )<b> -#define LZ4_STREAMSIZE (LZ4_STREAMSIZE_U64 * sizeof(unsigned long long)) +<pre><b>#define LZ4_STREAMSIZE 16416 </b>/* static size, for inter-version compatibility */<b> +#define LZ4_STREAMSIZE_VOIDP (LZ4_STREAMSIZE / sizeof(void*)) union LZ4_stream_u { - unsigned long long table[LZ4_STREAMSIZE_U64]; + void* table[LZ4_STREAMSIZE_VOIDP]; LZ4_stream_t_internal internal_donotuse; -} ; </b>/* previously typedef'd to LZ4_stream_t */<b> -</b><p> information structure to track an LZ4 stream. +}; </b>/* previously typedef'd to LZ4_stream_t */<b> +</b><p> Do not use below internal definitions directly ! + Declare or allocate an LZ4_stream_t instead. LZ4_stream_t can also be created using LZ4_createStream(), which is recommended. The structure definition can be convenient for static allocation (on stack, or as part of larger structure). Init this structure with LZ4_initStream() before first use. note : only use this definition in association with static linking ! - this definition is not API/ABI safe, and may change in a future version. + this definition is not API/ABI safe, and may change in future versions. </p></pre><BR> @@ -542,18 +536,39 @@ union LZ4_streamDecode_u { </p></pre><BR> -<pre><b></b><p> These functions used to be faster than LZ4_decompress_safe(), - but it has changed, and they are now slower than LZ4_decompress_safe(). +<pre><b>LZ4_DEPRECATED("use LZ4_compress_default() instead") LZ4LIB_API int LZ4_compress (const char* src, char* dest, int srcSize); +LZ4_DEPRECATED("use LZ4_compress_default() instead") LZ4LIB_API int LZ4_compress_limitedOutput (const char* src, char* dest, int srcSize, int maxOutputSize); +LZ4_DEPRECATED("use LZ4_compress_fast_extState() instead") LZ4LIB_API int LZ4_compress_withState (void* state, const char* source, char* dest, int inputSize); +LZ4_DEPRECATED("use LZ4_compress_fast_extState() instead") LZ4LIB_API int LZ4_compress_limitedOutput_withState (void* state, const char* source, char* dest, int inputSize, int maxOutputSize); +LZ4_DEPRECATED("use LZ4_compress_fast_continue() instead") LZ4LIB_API int LZ4_compress_continue (LZ4_stream_t* LZ4_streamPtr, const char* source, char* dest, int inputSize); +LZ4_DEPRECATED("use LZ4_compress_fast_continue() instead") LZ4LIB_API int LZ4_compress_limitedOutput_continue (LZ4_stream_t* LZ4_streamPtr, const char* source, char* dest, int inputSize, int maxOutputSize); +</b><p></p></pre><BR> + +<pre><b>LZ4_DEPRECATED("use LZ4_decompress_fast() instead") LZ4LIB_API int LZ4_uncompress (const char* source, char* dest, int outputSize); +LZ4_DEPRECATED("use LZ4_decompress_safe() instead") LZ4LIB_API int LZ4_uncompress_unknownOutputSize (const char* source, char* dest, int isize, int maxOutputSize); +</b><p></p></pre><BR> + +<pre><b>LZ4_DEPRECATED("use LZ4_decompress_safe_usingDict() instead") LZ4LIB_API int LZ4_decompress_safe_withPrefix64k (const char* src, char* dst, int compressedSize, int maxDstSize); +LZ4_DEPRECATED("use LZ4_decompress_fast_usingDict() instead") LZ4LIB_API int LZ4_decompress_fast_withPrefix64k (const char* src, char* dst, int originalSize); +</b><p></p></pre><BR> + +<pre><b>LZ4_DEPRECATED("This function is deprecated and unsafe. Consider using LZ4_decompress_safe() instead") +int LZ4_decompress_fast (const char* src, char* dst, int originalSize); +LZ4_DEPRECATED("This function is deprecated and unsafe. Consider using LZ4_decompress_safe_continue() instead") +int LZ4_decompress_fast_continue (LZ4_streamDecode_t* LZ4_streamDecode, const char* src, char* dst, int originalSize); +LZ4_DEPRECATED("This function is deprecated and unsafe. Consider using LZ4_decompress_safe_usingDict() instead") +int LZ4_decompress_fast_usingDict (const char* src, char* dst, int originalSize, const char* dictStart, int dictSize); +</b><p> These functions used to be faster than LZ4_decompress_safe(), + but this is no longer the case. They are now slower. This is because LZ4_decompress_fast() doesn't know the input size, - and therefore must progress more cautiously in the input buffer to not read beyond the end of block. + and therefore must progress more cautiously into the input buffer to not read beyond the end of block. On top of that `LZ4_decompress_fast()` is not protected vs malformed or malicious inputs, making it a security liability. As a consequence, LZ4_decompress_fast() is strongly discouraged, and deprecated. The last remaining LZ4_decompress_fast() specificity is that it can decompress a block without knowing its compressed size. - Such functionality could be achieved in a more secure manner, - by also providing the maximum size of input buffer, - but it would require new prototypes, and adaptation of the implementation to this new use case. + Such functionality can be achieved in a more secure manner + by employing LZ4_decompress_safe_partial(). Parameters: originalSize : is the uncompressed size to regenerate. diff --git a/doc/lz4frame_manual.html b/doc/lz4frame_manual.html index 607583b..2758306 100644 --- a/doc/lz4frame_manual.html +++ b/doc/lz4frame_manual.html @@ -299,8 +299,10 @@ LZ4F_errorCode_t LZ4F_freeDecompressionContext(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 compressed data from `srcBuffer`. - The function will read up to *srcSizePtr bytes from srcBuffer, +</b><p> Call this function repetitively to regenerate data compressed in `srcBuffer`. + + The function requires a valid dctx state. + It will read up to *srcSizePtr bytes from srcBuffer, and decompress data into dstBuffer, of capacity *dstSizePtr. The nb of bytes consumed from srcBuffer will be written into *srcSizePtr (necessarily <= original value). @@ -569,7 +569,7 @@ LZ4LIB_STATIC_API void LZ4_attach_dictionary(LZ4_stream_t* workingStream, const #define LZ4_H_98237428734687 /*-************************************************************ - * PRIVATE DEFINITIONS + * Private Definitions ************************************************************** * Do not use these definitions directly. * They are only exposed to allow static allocation of `LZ4_stream_t` and `LZ4_streamDecode_t`. @@ -693,7 +693,7 @@ union LZ4_streamDecode_u { # endif #endif /* LZ4_DISABLE_DEPRECATE_WARNINGS */ -/* Obsolete compression functions */ +/*! Obsolete compression functions (since v1.7.3) */ LZ4_DEPRECATED("use LZ4_compress_default() instead") LZ4LIB_API int LZ4_compress (const char* src, char* dest, int srcSize); LZ4_DEPRECATED("use LZ4_compress_default() instead") LZ4LIB_API int LZ4_compress_limitedOutput (const char* src, char* dest, int srcSize, int maxOutputSize); LZ4_DEPRECATED("use LZ4_compress_fast_extState() instead") LZ4LIB_API int LZ4_compress_withState (void* state, const char* source, char* dest, int inputSize); @@ -701,11 +701,12 @@ LZ4_DEPRECATED("use LZ4_compress_fast_extState() instead") LZ4LIB_API int LZ4_co LZ4_DEPRECATED("use LZ4_compress_fast_continue() instead") LZ4LIB_API int LZ4_compress_continue (LZ4_stream_t* LZ4_streamPtr, const char* source, char* dest, int inputSize); LZ4_DEPRECATED("use LZ4_compress_fast_continue() instead") LZ4LIB_API int LZ4_compress_limitedOutput_continue (LZ4_stream_t* LZ4_streamPtr, const char* source, char* dest, int inputSize, int maxOutputSize); -/* Obsolete decompression functions */ +/*! Obsolete decompression functions (since v1.8.0) */ LZ4_DEPRECATED("use LZ4_decompress_fast() instead") LZ4LIB_API int LZ4_uncompress (const char* source, char* dest, int outputSize); LZ4_DEPRECATED("use LZ4_decompress_safe() instead") LZ4LIB_API int LZ4_uncompress_unknownOutputSize (const char* source, char* dest, int isize, int maxOutputSize); -/* Obsolete streaming functions; degraded functionality; do not use! +/* Obsolete streaming functions (since v1.7.0) + * degraded functionality; do not use! * * In order to perform streaming compression, these functions depended on data * that is no longer tracked in the state. They have been preserved as well as @@ -719,23 +720,22 @@ LZ4_DEPRECATED("Use LZ4_createStream() instead") LZ4LIB_API int LZ4_sizeofStre LZ4_DEPRECATED("Use LZ4_resetStream() instead") LZ4LIB_API int LZ4_resetStreamState(void* state, char* inputBuffer); LZ4_DEPRECATED("Use LZ4_saveDict() instead") LZ4LIB_API char* LZ4_slideInputBuffer (void* state); -/* Obsolete streaming decoding functions */ +/*! Obsolete streaming decoding functions (since v1.7.0) */ LZ4_DEPRECATED("use LZ4_decompress_safe_usingDict() instead") LZ4LIB_API int LZ4_decompress_safe_withPrefix64k (const char* src, char* dst, int compressedSize, int maxDstSize); LZ4_DEPRECATED("use LZ4_decompress_fast_usingDict() instead") LZ4LIB_API int LZ4_decompress_fast_withPrefix64k (const char* src, char* dst, int originalSize); -/*! LZ4_decompress_fast() : **unsafe!** +/*! Obsolete LZ4_decompress_fast variants (since v1.9.0) : * These functions used to be faster than LZ4_decompress_safe(), - * but it has changed, and they are now slower than LZ4_decompress_safe(). + * but this is no longer the case. They are now slower. * This is because LZ4_decompress_fast() doesn't know the input size, - * and therefore must progress more cautiously in the input buffer to not read beyond the end of block. + * and therefore must progress more cautiously into the input buffer to not read beyond the end of block. * On top of that `LZ4_decompress_fast()` is not protected vs malformed or malicious inputs, making it a security liability. * As a consequence, LZ4_decompress_fast() is strongly discouraged, and deprecated. * * The last remaining LZ4_decompress_fast() specificity is that * it can decompress a block without knowing its compressed size. - * Such functionality could be achieved in a more secure manner, - * by also providing the maximum size of input buffer, - * but it would require new prototypes, and adaptation of the implementation to this new use case. + * Such functionality can be achieved in a more secure manner + * by employing LZ4_decompress_safe_partial(). * * Parameters: * originalSize : is the uncompressed size to regenerate. @@ -750,7 +750,6 @@ LZ4_DEPRECATED("use LZ4_decompress_fast_usingDict() instead") LZ4LIB_API int LZ4 * But they may happen if input data is invalid (error or intentional tampering). * As a consequence, use these functions in trusted environments with trusted data **only**. */ - LZ4_DEPRECATED("This function is deprecated and unsafe. Consider using LZ4_decompress_safe() instead") LZ4LIB_API int LZ4_decompress_fast (const char* src, char* dst, int originalSize); LZ4_DEPRECATED("This function is deprecated and unsafe. Consider using LZ4_decompress_safe_continue() instead") |