127b27ec6Sopenharmony_ci<html> 227b27ec6Sopenharmony_ci<head> 327b27ec6Sopenharmony_ci<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> 427b27ec6Sopenharmony_ci<title>1.9.4 Manual</title> 527b27ec6Sopenharmony_ci</head> 627b27ec6Sopenharmony_ci<body> 727b27ec6Sopenharmony_ci<h1>1.9.4 Manual</h1> 827b27ec6Sopenharmony_ci<hr> 927b27ec6Sopenharmony_ci<a name="Contents"></a><h2>Contents</h2> 1027b27ec6Sopenharmony_ci<ol> 1127b27ec6Sopenharmony_ci<li><a href="#Chapter1">Introduction</a></li> 1227b27ec6Sopenharmony_ci<li><a href="#Chapter2">Version</a></li> 1327b27ec6Sopenharmony_ci<li><a href="#Chapter3">Tuning parameter</a></li> 1427b27ec6Sopenharmony_ci<li><a href="#Chapter4">Simple Functions</a></li> 1527b27ec6Sopenharmony_ci<li><a href="#Chapter5">Advanced Functions</a></li> 1627b27ec6Sopenharmony_ci<li><a href="#Chapter6">Streaming Compression Functions</a></li> 1727b27ec6Sopenharmony_ci<li><a href="#Chapter7">Streaming Decompression Functions</a></li> 1827b27ec6Sopenharmony_ci<li><a href="#Chapter8">Experimental section</a></li> 1927b27ec6Sopenharmony_ci<li><a href="#Chapter9">Private Definitions</a></li> 2027b27ec6Sopenharmony_ci<li><a href="#Chapter10">Obsolete Functions</a></li> 2127b27ec6Sopenharmony_ci</ol> 2227b27ec6Sopenharmony_ci<hr> 2327b27ec6Sopenharmony_ci<a name="Chapter1"></a><h2>Introduction</h2><pre> 2427b27ec6Sopenharmony_ci LZ4 is lossless compression algorithm, providing compression speed >500 MB/s per core, 2527b27ec6Sopenharmony_ci scalable with multi-cores CPU. It features an extremely fast decoder, with speed in 2627b27ec6Sopenharmony_ci multiple GB/s per core, typically reaching RAM speed limits on multi-core systems. 2727b27ec6Sopenharmony_ci 2827b27ec6Sopenharmony_ci The LZ4 compression library provides in-memory compression and decompression functions. 2927b27ec6Sopenharmony_ci It gives full buffer control to user. 3027b27ec6Sopenharmony_ci Compression can be done in: 3127b27ec6Sopenharmony_ci - a single step (described as Simple Functions) 3227b27ec6Sopenharmony_ci - a single step, reusing a context (described in Advanced Functions) 3327b27ec6Sopenharmony_ci - unbounded multiple steps (described as Streaming compression) 3427b27ec6Sopenharmony_ci 3527b27ec6Sopenharmony_ci lz4.h generates and decodes LZ4-compressed blocks (doc/lz4_Block_format.md). 3627b27ec6Sopenharmony_ci Decompressing such a compressed block requires additional metadata. 3727b27ec6Sopenharmony_ci Exact metadata depends on exact decompression function. 3827b27ec6Sopenharmony_ci For the typical case of LZ4_decompress_safe(), 3927b27ec6Sopenharmony_ci metadata includes block's compressed size, and maximum bound of decompressed size. 4027b27ec6Sopenharmony_ci Each application is free to encode and pass such metadata in whichever way it wants. 4127b27ec6Sopenharmony_ci 4227b27ec6Sopenharmony_ci lz4.h only handle blocks, it can not generate Frames. 4327b27ec6Sopenharmony_ci 4427b27ec6Sopenharmony_ci Blocks are different from Frames (doc/lz4_Frame_format.md). 4527b27ec6Sopenharmony_ci Frames bundle both blocks and metadata in a specified manner. 4627b27ec6Sopenharmony_ci Embedding metadata is required for compressed data to be self-contained and portable. 4727b27ec6Sopenharmony_ci Frame format is delivered through a companion API, declared in lz4frame.h. 4827b27ec6Sopenharmony_ci The `lz4` CLI can only manage frames. 4927b27ec6Sopenharmony_ci<BR></pre> 5027b27ec6Sopenharmony_ci 5127b27ec6Sopenharmony_ci<pre><b>#if defined(LZ4_FREESTANDING) && (LZ4_FREESTANDING == 1) 5227b27ec6Sopenharmony_ci# define LZ4_HEAPMODE 0 5327b27ec6Sopenharmony_ci# define LZ4HC_HEAPMODE 0 5427b27ec6Sopenharmony_ci# define LZ4_STATIC_LINKING_ONLY_DISABLE_MEMORY_ALLOCATION 1 5527b27ec6Sopenharmony_ci# if !defined(LZ4_memcpy) 5627b27ec6Sopenharmony_ci# error "LZ4_FREESTANDING requires macro 'LZ4_memcpy'." 5727b27ec6Sopenharmony_ci# endif 5827b27ec6Sopenharmony_ci# if !defined(LZ4_memset) 5927b27ec6Sopenharmony_ci# error "LZ4_FREESTANDING requires macro 'LZ4_memset'." 6027b27ec6Sopenharmony_ci# endif 6127b27ec6Sopenharmony_ci# if !defined(LZ4_memmove) 6227b27ec6Sopenharmony_ci# error "LZ4_FREESTANDING requires macro 'LZ4_memmove'." 6327b27ec6Sopenharmony_ci# endif 6427b27ec6Sopenharmony_ci#elif ! defined(LZ4_FREESTANDING) 6527b27ec6Sopenharmony_ci# define LZ4_FREESTANDING 0 6627b27ec6Sopenharmony_ci#endif 6727b27ec6Sopenharmony_ci</b><p> When this macro is set to 1, it enables "freestanding mode" that is 6827b27ec6Sopenharmony_ci suitable for typical freestanding environment which doesn't support 6927b27ec6Sopenharmony_ci standard C library. 7027b27ec6Sopenharmony_ci 7127b27ec6Sopenharmony_ci - LZ4_FREESTANDING is a compile-time switch. 7227b27ec6Sopenharmony_ci - It requires the following macros to be defined: 7327b27ec6Sopenharmony_ci LZ4_memcpy, LZ4_memmove, LZ4_memset. 7427b27ec6Sopenharmony_ci - It only enables LZ4/HC functions which don't use heap. 7527b27ec6Sopenharmony_ci All LZ4F_* functions are not supported. 7627b27ec6Sopenharmony_ci - See tests/freestanding.c to check its basic setup. 7727b27ec6Sopenharmony_ci 7827b27ec6Sopenharmony_ci</p></pre><BR> 7927b27ec6Sopenharmony_ci 8027b27ec6Sopenharmony_ci<a name="Chapter2"></a><h2>Version</h2><pre></pre> 8127b27ec6Sopenharmony_ci 8227b27ec6Sopenharmony_ci<pre><b>int LZ4_versionNumber (void); </b>/**< library version number; useful to check dll version; requires v1.3.0+ */<b> 8327b27ec6Sopenharmony_ci</b></pre><BR> 8427b27ec6Sopenharmony_ci<pre><b>const char* LZ4_versionString (void); </b>/**< library version string; useful to check dll version; requires v1.7.5+ */<b> 8527b27ec6Sopenharmony_ci</b></pre><BR> 8627b27ec6Sopenharmony_ci<a name="Chapter3"></a><h2>Tuning parameter</h2><pre></pre> 8727b27ec6Sopenharmony_ci 8827b27ec6Sopenharmony_ci<pre><b>#ifndef LZ4_MEMORY_USAGE 8927b27ec6Sopenharmony_ci# define LZ4_MEMORY_USAGE LZ4_MEMORY_USAGE_DEFAULT 9027b27ec6Sopenharmony_ci#endif 9127b27ec6Sopenharmony_ci</b><p> Memory usage formula : N->2^N Bytes (examples : 10 -> 1KB; 12 -> 4KB ; 16 -> 64KB; 20 -> 1MB; ) 9227b27ec6Sopenharmony_ci Increasing memory usage improves compression ratio, at the cost of speed. 9327b27ec6Sopenharmony_ci Reduced memory usage may improve speed at the cost of ratio, thanks to better cache locality. 9427b27ec6Sopenharmony_ci Default value is 14, for 16KB, which nicely fits into Intel x86 L1 cache 9527b27ec6Sopenharmony_ci 9627b27ec6Sopenharmony_ci</p></pre><BR> 9727b27ec6Sopenharmony_ci 9827b27ec6Sopenharmony_ci<a name="Chapter4"></a><h2>Simple Functions</h2><pre></pre> 9927b27ec6Sopenharmony_ci 10027b27ec6Sopenharmony_ci<pre><b>int LZ4_compress_default(const char* src, char* dst, int srcSize, int dstCapacity); 10127b27ec6Sopenharmony_ci</b><p> Compresses 'srcSize' bytes from buffer 'src' 10227b27ec6Sopenharmony_ci into already allocated 'dst' buffer of size 'dstCapacity'. 10327b27ec6Sopenharmony_ci Compression is guaranteed to succeed if 'dstCapacity' >= LZ4_compressBound(srcSize). 10427b27ec6Sopenharmony_ci It also runs faster, so it's a recommended setting. 10527b27ec6Sopenharmony_ci If the function cannot compress 'src' into a more limited 'dst' budget, 10627b27ec6Sopenharmony_ci compression stops *immediately*, and the function result is zero. 10727b27ec6Sopenharmony_ci In which case, 'dst' content is undefined (invalid). 10827b27ec6Sopenharmony_ci srcSize : max supported value is LZ4_MAX_INPUT_SIZE. 10927b27ec6Sopenharmony_ci dstCapacity : size of buffer 'dst' (which must be already allocated) 11027b27ec6Sopenharmony_ci @return : the number of bytes written into buffer 'dst' (necessarily <= dstCapacity) 11127b27ec6Sopenharmony_ci or 0 if compression fails 11227b27ec6Sopenharmony_ci Note : This function is protected against buffer overflow scenarios (never writes outside 'dst' buffer, nor read outside 'source' buffer). 11327b27ec6Sopenharmony_ci 11427b27ec6Sopenharmony_ci</p></pre><BR> 11527b27ec6Sopenharmony_ci 11627b27ec6Sopenharmony_ci<pre><b>int LZ4_decompress_safe (const char* src, char* dst, int compressedSize, int dstCapacity); 11727b27ec6Sopenharmony_ci</b><p> compressedSize : is the exact complete size of the compressed block. 11827b27ec6Sopenharmony_ci dstCapacity : is the size of destination buffer (which must be already allocated), presumed an upper bound of decompressed size. 11927b27ec6Sopenharmony_ci @return : the number of bytes decompressed into destination buffer (necessarily <= dstCapacity) 12027b27ec6Sopenharmony_ci If destination buffer is not large enough, decoding will stop and output an error code (negative value). 12127b27ec6Sopenharmony_ci If the source stream is detected malformed, the function will stop decoding and return a negative result. 12227b27ec6Sopenharmony_ci Note 1 : This function is protected against malicious data packets : 12327b27ec6Sopenharmony_ci it will never writes outside 'dst' buffer, nor read outside 'source' buffer, 12427b27ec6Sopenharmony_ci even if the compressed block is maliciously modified to order the decoder to do these actions. 12527b27ec6Sopenharmony_ci In such case, the decoder stops immediately, and considers the compressed block malformed. 12627b27ec6Sopenharmony_ci Note 2 : compressedSize and dstCapacity must be provided to the function, the compressed block does not contain them. 12727b27ec6Sopenharmony_ci The implementation is free to send / store / derive this information in whichever way is most beneficial. 12827b27ec6Sopenharmony_ci If there is a need for a different format which bundles together both compressed data and its metadata, consider looking at lz4frame.h instead. 12927b27ec6Sopenharmony_ci 13027b27ec6Sopenharmony_ci</p></pre><BR> 13127b27ec6Sopenharmony_ci 13227b27ec6Sopenharmony_ci<a name="Chapter5"></a><h2>Advanced Functions</h2><pre></pre> 13327b27ec6Sopenharmony_ci 13427b27ec6Sopenharmony_ci<pre><b>int LZ4_compressBound(int inputSize); 13527b27ec6Sopenharmony_ci</b><p> Provides the maximum size that LZ4 compression may output in a "worst case" scenario (input data not compressible) 13627b27ec6Sopenharmony_ci This function is primarily useful for memory allocation purposes (destination buffer size). 13727b27ec6Sopenharmony_ci Macro LZ4_COMPRESSBOUND() is also provided for compilation-time evaluation (stack memory allocation for example). 13827b27ec6Sopenharmony_ci Note that LZ4_compress_default() compresses faster when dstCapacity is >= LZ4_compressBound(srcSize) 13927b27ec6Sopenharmony_ci inputSize : max supported value is LZ4_MAX_INPUT_SIZE 14027b27ec6Sopenharmony_ci return : maximum output size in a "worst case" scenario 14127b27ec6Sopenharmony_ci or 0, if input size is incorrect (too large or negative) 14227b27ec6Sopenharmony_ci</p></pre><BR> 14327b27ec6Sopenharmony_ci 14427b27ec6Sopenharmony_ci<pre><b>int LZ4_compress_fast (const char* src, char* dst, int srcSize, int dstCapacity, int acceleration); 14527b27ec6Sopenharmony_ci</b><p> Same as LZ4_compress_default(), but allows selection of "acceleration" factor. 14627b27ec6Sopenharmony_ci The larger the acceleration value, the faster the algorithm, but also the lesser the compression. 14727b27ec6Sopenharmony_ci It's a trade-off. It can be fine tuned, with each successive value providing roughly +~3% to speed. 14827b27ec6Sopenharmony_ci An acceleration value of "1" is the same as regular LZ4_compress_default() 14927b27ec6Sopenharmony_ci Values <= 0 will be replaced by LZ4_ACCELERATION_DEFAULT (currently == 1, see lz4.c). 15027b27ec6Sopenharmony_ci Values > LZ4_ACCELERATION_MAX will be replaced by LZ4_ACCELERATION_MAX (currently == 65537, see lz4.c). 15127b27ec6Sopenharmony_ci</p></pre><BR> 15227b27ec6Sopenharmony_ci 15327b27ec6Sopenharmony_ci<pre><b>int LZ4_sizeofState(void); 15427b27ec6Sopenharmony_ciint LZ4_compress_fast_extState (void* state, const char* src, char* dst, int srcSize, int dstCapacity, int acceleration); 15527b27ec6Sopenharmony_ci</b><p> Same as LZ4_compress_fast(), using an externally allocated memory space for its state. 15627b27ec6Sopenharmony_ci Use LZ4_sizeofState() to know how much memory must be allocated, 15727b27ec6Sopenharmony_ci and allocate it on 8-bytes boundaries (using `malloc()` typically). 15827b27ec6Sopenharmony_ci Then, provide this buffer as `void* state` to compression function. 15927b27ec6Sopenharmony_ci 16027b27ec6Sopenharmony_ci</p></pre><BR> 16127b27ec6Sopenharmony_ci 16227b27ec6Sopenharmony_ci<pre><b>int LZ4_compress_destSize (const char* src, char* dst, int* srcSizePtr, int targetDstSize); 16327b27ec6Sopenharmony_ci</b><p> Reverse the logic : compresses as much data as possible from 'src' buffer 16427b27ec6Sopenharmony_ci into already allocated buffer 'dst', of size >= 'targetDestSize'. 16527b27ec6Sopenharmony_ci This function either compresses the entire 'src' content into 'dst' if it's large enough, 16627b27ec6Sopenharmony_ci or fill 'dst' buffer completely with as much data as possible from 'src'. 16727b27ec6Sopenharmony_ci note: acceleration parameter is fixed to "default". 16827b27ec6Sopenharmony_ci 16927b27ec6Sopenharmony_ci *srcSizePtr : will be modified to indicate how many bytes where read from 'src' to fill 'dst'. 17027b27ec6Sopenharmony_ci New value is necessarily <= input value. 17127b27ec6Sopenharmony_ci @return : Nb bytes written into 'dst' (necessarily <= targetDestSize) 17227b27ec6Sopenharmony_ci or 0 if compression fails. 17327b27ec6Sopenharmony_ci 17427b27ec6Sopenharmony_ci Note : from v1.8.2 to v1.9.1, this function had a bug (fixed un v1.9.2+): 17527b27ec6Sopenharmony_ci the produced compressed content could, in specific circumstances, 17627b27ec6Sopenharmony_ci require to be decompressed into a destination buffer larger 17727b27ec6Sopenharmony_ci by at least 1 byte than the content to decompress. 17827b27ec6Sopenharmony_ci If an application uses `LZ4_compress_destSize()`, 17927b27ec6Sopenharmony_ci it's highly recommended to update liblz4 to v1.9.2 or better. 18027b27ec6Sopenharmony_ci If this can't be done or ensured, 18127b27ec6Sopenharmony_ci the receiving decompression function should provide 18227b27ec6Sopenharmony_ci a dstCapacity which is > decompressedSize, by at least 1 byte. 18327b27ec6Sopenharmony_ci See https://github.com/lz4/lz4/issues/859 for details 18427b27ec6Sopenharmony_ci 18527b27ec6Sopenharmony_ci</p></pre><BR> 18627b27ec6Sopenharmony_ci 18727b27ec6Sopenharmony_ci<pre><b>int LZ4_decompress_safe_partial (const char* src, char* dst, int srcSize, int targetOutputSize, int dstCapacity); 18827b27ec6Sopenharmony_ci</b><p> Decompress an LZ4 compressed block, of size 'srcSize' at position 'src', 18927b27ec6Sopenharmony_ci into destination buffer 'dst' of size 'dstCapacity'. 19027b27ec6Sopenharmony_ci Up to 'targetOutputSize' bytes will be decoded. 19127b27ec6Sopenharmony_ci The function stops decoding on reaching this objective. 19227b27ec6Sopenharmony_ci This can be useful to boost performance 19327b27ec6Sopenharmony_ci whenever only the beginning of a block is required. 19427b27ec6Sopenharmony_ci 19527b27ec6Sopenharmony_ci @return : the number of bytes decoded in `dst` (necessarily <= targetOutputSize) 19627b27ec6Sopenharmony_ci If source stream is detected malformed, function returns a negative result. 19727b27ec6Sopenharmony_ci 19827b27ec6Sopenharmony_ci Note 1 : @return can be < targetOutputSize, if compressed block contains less data. 19927b27ec6Sopenharmony_ci 20027b27ec6Sopenharmony_ci Note 2 : targetOutputSize must be <= dstCapacity 20127b27ec6Sopenharmony_ci 20227b27ec6Sopenharmony_ci Note 3 : this function effectively stops decoding on reaching targetOutputSize, 20327b27ec6Sopenharmony_ci so dstCapacity is kind of redundant. 20427b27ec6Sopenharmony_ci This is because in older versions of this function, 20527b27ec6Sopenharmony_ci decoding operation would still write complete sequences. 20627b27ec6Sopenharmony_ci Therefore, there was no guarantee that it would stop writing at exactly targetOutputSize, 20727b27ec6Sopenharmony_ci it could write more bytes, though only up to dstCapacity. 20827b27ec6Sopenharmony_ci Some "margin" used to be required for this operation to work properly. 20927b27ec6Sopenharmony_ci Thankfully, this is no longer necessary. 21027b27ec6Sopenharmony_ci The function nonetheless keeps the same signature, in an effort to preserve API compatibility. 21127b27ec6Sopenharmony_ci 21227b27ec6Sopenharmony_ci Note 4 : If srcSize is the exact size of the block, 21327b27ec6Sopenharmony_ci then targetOutputSize can be any value, 21427b27ec6Sopenharmony_ci including larger than the block's decompressed size. 21527b27ec6Sopenharmony_ci The function will, at most, generate block's decompressed size. 21627b27ec6Sopenharmony_ci 21727b27ec6Sopenharmony_ci Note 5 : If srcSize is _larger_ than block's compressed size, 21827b27ec6Sopenharmony_ci then targetOutputSize **MUST** be <= block's decompressed size. 21927b27ec6Sopenharmony_ci Otherwise, *silent corruption will occur*. 22027b27ec6Sopenharmony_ci 22127b27ec6Sopenharmony_ci</p></pre><BR> 22227b27ec6Sopenharmony_ci 22327b27ec6Sopenharmony_ci<a name="Chapter6"></a><h2>Streaming Compression Functions</h2><pre></pre> 22427b27ec6Sopenharmony_ci 22527b27ec6Sopenharmony_ci<pre><b>void LZ4_resetStream_fast (LZ4_stream_t* streamPtr); 22627b27ec6Sopenharmony_ci</b><p> Use this to prepare an LZ4_stream_t for a new chain of dependent blocks 22727b27ec6Sopenharmony_ci (e.g., LZ4_compress_fast_continue()). 22827b27ec6Sopenharmony_ci 22927b27ec6Sopenharmony_ci An LZ4_stream_t must be initialized once before usage. 23027b27ec6Sopenharmony_ci This is automatically done when created by LZ4_createStream(). 23127b27ec6Sopenharmony_ci However, should the LZ4_stream_t be simply declared on stack (for example), 23227b27ec6Sopenharmony_ci it's necessary to initialize it first, using LZ4_initStream(). 23327b27ec6Sopenharmony_ci 23427b27ec6Sopenharmony_ci After init, start any new stream with LZ4_resetStream_fast(). 23527b27ec6Sopenharmony_ci A same LZ4_stream_t can be re-used multiple times consecutively 23627b27ec6Sopenharmony_ci and compress multiple streams, 23727b27ec6Sopenharmony_ci provided that it starts each new stream with LZ4_resetStream_fast(). 23827b27ec6Sopenharmony_ci 23927b27ec6Sopenharmony_ci LZ4_resetStream_fast() is much faster than LZ4_initStream(), 24027b27ec6Sopenharmony_ci but is not compatible with memory regions containing garbage data. 24127b27ec6Sopenharmony_ci 24227b27ec6Sopenharmony_ci Note: it's only useful to call LZ4_resetStream_fast() 24327b27ec6Sopenharmony_ci in the context of streaming compression. 24427b27ec6Sopenharmony_ci The *extState* functions perform their own resets. 24527b27ec6Sopenharmony_ci Invoking LZ4_resetStream_fast() before is redundant, and even counterproductive. 24627b27ec6Sopenharmony_ci 24727b27ec6Sopenharmony_ci</p></pre><BR> 24827b27ec6Sopenharmony_ci 24927b27ec6Sopenharmony_ci<pre><b>int LZ4_loadDict (LZ4_stream_t* streamPtr, const char* dictionary, int dictSize); 25027b27ec6Sopenharmony_ci</b><p> Use this function to reference a static dictionary into LZ4_stream_t. 25127b27ec6Sopenharmony_ci The dictionary must remain available during compression. 25227b27ec6Sopenharmony_ci LZ4_loadDict() triggers a reset, so any previous data will be forgotten. 25327b27ec6Sopenharmony_ci The same dictionary will have to be loaded on decompression side for successful decoding. 25427b27ec6Sopenharmony_ci Dictionary are useful for better compression of small data (KB range). 25527b27ec6Sopenharmony_ci While LZ4 accept any input as dictionary, 25627b27ec6Sopenharmony_ci results are generally better when using Zstandard's Dictionary Builder. 25727b27ec6Sopenharmony_ci Loading a size of 0 is allowed, and is the same as reset. 25827b27ec6Sopenharmony_ci @return : loaded dictionary size, in bytes (necessarily <= 64 KB) 25927b27ec6Sopenharmony_ci 26027b27ec6Sopenharmony_ci</p></pre><BR> 26127b27ec6Sopenharmony_ci 26227b27ec6Sopenharmony_ci<pre><b>int LZ4_compress_fast_continue (LZ4_stream_t* streamPtr, const char* src, char* dst, int srcSize, int dstCapacity, int acceleration); 26327b27ec6Sopenharmony_ci</b><p> Compress 'src' content using data from previously compressed blocks, for better compression ratio. 26427b27ec6Sopenharmony_ci 'dst' buffer must be already allocated. 26527b27ec6Sopenharmony_ci If dstCapacity >= LZ4_compressBound(srcSize), compression is guaranteed to succeed, and runs faster. 26627b27ec6Sopenharmony_ci 26727b27ec6Sopenharmony_ci @return : size of compressed block 26827b27ec6Sopenharmony_ci or 0 if there is an error (typically, cannot fit into 'dst'). 26927b27ec6Sopenharmony_ci 27027b27ec6Sopenharmony_ci Note 1 : Each invocation to LZ4_compress_fast_continue() generates a new block. 27127b27ec6Sopenharmony_ci Each block has precise boundaries. 27227b27ec6Sopenharmony_ci Each block must be decompressed separately, calling LZ4_decompress_*() with relevant metadata. 27327b27ec6Sopenharmony_ci It's not possible to append blocks together and expect a single invocation of LZ4_decompress_*() to decompress them together. 27427b27ec6Sopenharmony_ci 27527b27ec6Sopenharmony_ci Note 2 : The previous 64KB of source data is __assumed__ to remain present, unmodified, at same address in memory ! 27627b27ec6Sopenharmony_ci 27727b27ec6Sopenharmony_ci Note 3 : When input is structured as a double-buffer, each buffer can have any size, including < 64 KB. 27827b27ec6Sopenharmony_ci Make sure that buffers are separated, by at least one byte. 27927b27ec6Sopenharmony_ci This construction ensures that each block only depends on previous block. 28027b27ec6Sopenharmony_ci 28127b27ec6Sopenharmony_ci Note 4 : If input buffer is a ring-buffer, it can have any size, including < 64 KB. 28227b27ec6Sopenharmony_ci 28327b27ec6Sopenharmony_ci Note 5 : After an error, the stream status is undefined (invalid), it can only be reset or freed. 28427b27ec6Sopenharmony_ci 28527b27ec6Sopenharmony_ci</p></pre><BR> 28627b27ec6Sopenharmony_ci 28727b27ec6Sopenharmony_ci<pre><b>int LZ4_saveDict (LZ4_stream_t* streamPtr, char* safeBuffer, int maxDictSize); 28827b27ec6Sopenharmony_ci</b><p> If last 64KB data cannot be guaranteed to remain available at its current memory location, 28927b27ec6Sopenharmony_ci save it into a safer place (char* safeBuffer). 29027b27ec6Sopenharmony_ci This is schematically equivalent to a memcpy() followed by LZ4_loadDict(), 29127b27ec6Sopenharmony_ci but is much faster, because LZ4_saveDict() doesn't need to rebuild tables. 29227b27ec6Sopenharmony_ci @return : saved dictionary size in bytes (necessarily <= maxDictSize), or 0 if error. 29327b27ec6Sopenharmony_ci 29427b27ec6Sopenharmony_ci</p></pre><BR> 29527b27ec6Sopenharmony_ci 29627b27ec6Sopenharmony_ci<a name="Chapter7"></a><h2>Streaming Decompression Functions</h2><pre> Bufferless synchronous API 29727b27ec6Sopenharmony_ci<BR></pre> 29827b27ec6Sopenharmony_ci 29927b27ec6Sopenharmony_ci<pre><b>#if !defined(LZ4_STATIC_LINKING_ONLY_DISABLE_MEMORY_ALLOCATION) 30027b27ec6Sopenharmony_ciLZ4_streamDecode_t* LZ4_createStreamDecode(void); 30127b27ec6Sopenharmony_ciint LZ4_freeStreamDecode (LZ4_streamDecode_t* LZ4_stream); 30227b27ec6Sopenharmony_ci#endif </b>/* !defined(LZ4_STATIC_LINKING_ONLY_DISABLE_MEMORY_ALLOCATION) */<b> 30327b27ec6Sopenharmony_ci</b><p> creation / destruction of streaming decompression tracking context. 30427b27ec6Sopenharmony_ci A tracking context can be re-used multiple times. 30527b27ec6Sopenharmony_ci 30627b27ec6Sopenharmony_ci</p></pre><BR> 30727b27ec6Sopenharmony_ci 30827b27ec6Sopenharmony_ci<pre><b>int LZ4_setStreamDecode (LZ4_streamDecode_t* LZ4_streamDecode, const char* dictionary, int dictSize); 30927b27ec6Sopenharmony_ci</b><p> An LZ4_streamDecode_t context can be allocated once and re-used multiple times. 31027b27ec6Sopenharmony_ci Use this function to start decompression of a new stream of blocks. 31127b27ec6Sopenharmony_ci A dictionary can optionally be set. Use NULL or size 0 for a reset order. 31227b27ec6Sopenharmony_ci Dictionary is presumed stable : it must remain accessible and unmodified during next decompression. 31327b27ec6Sopenharmony_ci @return : 1 if OK, 0 if error 31427b27ec6Sopenharmony_ci 31527b27ec6Sopenharmony_ci</p></pre><BR> 31627b27ec6Sopenharmony_ci 31727b27ec6Sopenharmony_ci<pre><b>int LZ4_decoderRingBufferSize(int maxBlockSize); 31827b27ec6Sopenharmony_ci#define LZ4_DECODER_RING_BUFFER_SIZE(maxBlockSize) (65536 + 14 + (maxBlockSize)) </b>/* for static allocation; maxBlockSize presumed valid */<b> 31927b27ec6Sopenharmony_ci</b><p> Note : in a ring buffer scenario (optional), 32027b27ec6Sopenharmony_ci blocks are presumed decompressed next to each other 32127b27ec6Sopenharmony_ci up to the moment there is not enough remaining space for next block (remainingSize < maxBlockSize), 32227b27ec6Sopenharmony_ci at which stage it resumes from beginning of ring buffer. 32327b27ec6Sopenharmony_ci When setting such a ring buffer for streaming decompression, 32427b27ec6Sopenharmony_ci provides the minimum size of this ring buffer 32527b27ec6Sopenharmony_ci to be compatible with any source respecting maxBlockSize condition. 32627b27ec6Sopenharmony_ci @return : minimum ring buffer size, 32727b27ec6Sopenharmony_ci or 0 if there is an error (invalid maxBlockSize). 32827b27ec6Sopenharmony_ci 32927b27ec6Sopenharmony_ci</p></pre><BR> 33027b27ec6Sopenharmony_ci 33127b27ec6Sopenharmony_ci<pre><b>int 33227b27ec6Sopenharmony_ciLZ4_decompress_safe_continue (LZ4_streamDecode_t* LZ4_streamDecode, 33327b27ec6Sopenharmony_ci const char* src, char* dst, 33427b27ec6Sopenharmony_ci int srcSize, int dstCapacity); 33527b27ec6Sopenharmony_ci</b><p> These decoding functions allow decompression of consecutive blocks in "streaming" mode. 33627b27ec6Sopenharmony_ci A block is an unsplittable entity, it must be presented entirely to a decompression function. 33727b27ec6Sopenharmony_ci Decompression functions only accepts one block at a time. 33827b27ec6Sopenharmony_ci The last 64KB of previously decoded data *must* remain available and unmodified at the memory position where they were decoded. 33927b27ec6Sopenharmony_ci If less than 64KB of data has been decoded, all the data must be present. 34027b27ec6Sopenharmony_ci 34127b27ec6Sopenharmony_ci Special : if decompression side sets a ring buffer, it must respect one of the following conditions : 34227b27ec6Sopenharmony_ci - Decompression buffer size is _at least_ LZ4_decoderRingBufferSize(maxBlockSize). 34327b27ec6Sopenharmony_ci maxBlockSize is the maximum size of any single block. It can have any value > 16 bytes. 34427b27ec6Sopenharmony_ci In which case, encoding and decoding buffers do not need to be synchronized. 34527b27ec6Sopenharmony_ci Actually, data can be produced by any source compliant with LZ4 format specification, and respecting maxBlockSize. 34627b27ec6Sopenharmony_ci - Synchronized mode : 34727b27ec6Sopenharmony_ci Decompression buffer size is _exactly_ the same as compression buffer size, 34827b27ec6Sopenharmony_ci and follows exactly same update rule (block boundaries at same positions), 34927b27ec6Sopenharmony_ci and decoding function is provided with exact decompressed size of each block (exception for last block of the stream), 35027b27ec6Sopenharmony_ci _then_ decoding & encoding ring buffer can have any size, including small ones ( < 64 KB). 35127b27ec6Sopenharmony_ci - Decompression buffer is larger than encoding buffer, by a minimum of maxBlockSize more bytes. 35227b27ec6Sopenharmony_ci In which case, encoding and decoding buffers do not need to be synchronized, 35327b27ec6Sopenharmony_ci and encoding ring buffer can have any size, including small ones ( < 64 KB). 35427b27ec6Sopenharmony_ci 35527b27ec6Sopenharmony_ci Whenever these conditions are not possible, 35627b27ec6Sopenharmony_ci save the last 64KB of decoded data into a safe buffer where it can't be modified during decompression, 35727b27ec6Sopenharmony_ci then indicate where this data is saved using LZ4_setStreamDecode(), before decompressing next block. 35827b27ec6Sopenharmony_ci</p></pre><BR> 35927b27ec6Sopenharmony_ci 36027b27ec6Sopenharmony_ci<pre><b>int 36127b27ec6Sopenharmony_ciLZ4_decompress_safe_usingDict(const char* src, char* dst, 36227b27ec6Sopenharmony_ci int srcSize, int dstCapacity, 36327b27ec6Sopenharmony_ci const char* dictStart, int dictSize); 36427b27ec6Sopenharmony_ci</b><p> These decoding functions work the same as 36527b27ec6Sopenharmony_ci a combination of LZ4_setStreamDecode() followed by LZ4_decompress_*_continue() 36627b27ec6Sopenharmony_ci They are stand-alone, and don't need an LZ4_streamDecode_t structure. 36727b27ec6Sopenharmony_ci Dictionary is presumed stable : it must remain accessible and unmodified during decompression. 36827b27ec6Sopenharmony_ci Performance tip : Decompression speed can be substantially increased 36927b27ec6Sopenharmony_ci when dst == dictStart + dictSize. 37027b27ec6Sopenharmony_ci 37127b27ec6Sopenharmony_ci</p></pre><BR> 37227b27ec6Sopenharmony_ci 37327b27ec6Sopenharmony_ci<a name="Chapter8"></a><h2>Experimental section</h2><pre> 37427b27ec6Sopenharmony_ci Symbols declared in this section must be considered unstable. Their 37527b27ec6Sopenharmony_ci signatures or semantics may change, or they may be removed altogether in the 37627b27ec6Sopenharmony_ci future. They are therefore only safe to depend on when the caller is 37727b27ec6Sopenharmony_ci statically linked against the library. 37827b27ec6Sopenharmony_ci 37927b27ec6Sopenharmony_ci To protect against unsafe usage, not only are the declarations guarded, 38027b27ec6Sopenharmony_ci the definitions are hidden by default 38127b27ec6Sopenharmony_ci when building LZ4 as a shared/dynamic library. 38227b27ec6Sopenharmony_ci 38327b27ec6Sopenharmony_ci In order to access these declarations, 38427b27ec6Sopenharmony_ci define LZ4_STATIC_LINKING_ONLY in your application 38527b27ec6Sopenharmony_ci before including LZ4's headers. 38627b27ec6Sopenharmony_ci 38727b27ec6Sopenharmony_ci In order to make their implementations accessible dynamically, you must 38827b27ec6Sopenharmony_ci define LZ4_PUBLISH_STATIC_FUNCTIONS when building the LZ4 library. 38927b27ec6Sopenharmony_ci<BR></pre> 39027b27ec6Sopenharmony_ci 39127b27ec6Sopenharmony_ci<pre><b>LZ4LIB_STATIC_API int LZ4_compress_fast_extState_fastReset (void* state, const char* src, char* dst, int srcSize, int dstCapacity, int acceleration); 39227b27ec6Sopenharmony_ci</b><p> A variant of LZ4_compress_fast_extState(). 39327b27ec6Sopenharmony_ci 39427b27ec6Sopenharmony_ci Using this variant avoids an expensive initialization step. 39527b27ec6Sopenharmony_ci It is only safe to call if the state buffer is known to be correctly initialized already 39627b27ec6Sopenharmony_ci (see above comment on LZ4_resetStream_fast() for a definition of "correctly initialized"). 39727b27ec6Sopenharmony_ci From a high level, the difference is that 39827b27ec6Sopenharmony_ci this function initializes the provided state with a call to something like LZ4_resetStream_fast() 39927b27ec6Sopenharmony_ci while LZ4_compress_fast_extState() starts with a call to LZ4_resetStream(). 40027b27ec6Sopenharmony_ci 40127b27ec6Sopenharmony_ci</p></pre><BR> 40227b27ec6Sopenharmony_ci 40327b27ec6Sopenharmony_ci<pre><b>LZ4LIB_STATIC_API void 40427b27ec6Sopenharmony_ciLZ4_attach_dictionary(LZ4_stream_t* workingStream, 40527b27ec6Sopenharmony_ci const LZ4_stream_t* dictionaryStream); 40627b27ec6Sopenharmony_ci</b><p> This is an experimental API that allows 40727b27ec6Sopenharmony_ci efficient use of a static dictionary many times. 40827b27ec6Sopenharmony_ci 40927b27ec6Sopenharmony_ci Rather than re-loading the dictionary buffer into a working context before 41027b27ec6Sopenharmony_ci each compression, or copying a pre-loaded dictionary's LZ4_stream_t into a 41127b27ec6Sopenharmony_ci working LZ4_stream_t, this function introduces a no-copy setup mechanism, 41227b27ec6Sopenharmony_ci in which the working stream references the dictionary stream in-place. 41327b27ec6Sopenharmony_ci 41427b27ec6Sopenharmony_ci Several assumptions are made about the state of the dictionary stream. 41527b27ec6Sopenharmony_ci Currently, only streams which have been prepared by LZ4_loadDict() should 41627b27ec6Sopenharmony_ci be expected to work. 41727b27ec6Sopenharmony_ci 41827b27ec6Sopenharmony_ci Alternatively, the provided dictionaryStream may be NULL, 41927b27ec6Sopenharmony_ci in which case any existing dictionary stream is unset. 42027b27ec6Sopenharmony_ci 42127b27ec6Sopenharmony_ci If a dictionary is provided, it replaces any pre-existing stream history. 42227b27ec6Sopenharmony_ci The dictionary contents are the only history that can be referenced and 42327b27ec6Sopenharmony_ci logically immediately precede the data compressed in the first subsequent 42427b27ec6Sopenharmony_ci compression call. 42527b27ec6Sopenharmony_ci 42627b27ec6Sopenharmony_ci The dictionary will only remain attached to the working stream through the 42727b27ec6Sopenharmony_ci first compression call, at the end of which it is cleared. The dictionary 42827b27ec6Sopenharmony_ci stream (and source buffer) must remain in-place / accessible / unchanged 42927b27ec6Sopenharmony_ci through the completion of the first compression call on the stream. 43027b27ec6Sopenharmony_ci 43127b27ec6Sopenharmony_ci</p></pre><BR> 43227b27ec6Sopenharmony_ci 43327b27ec6Sopenharmony_ci<pre><b></b><p> 43427b27ec6Sopenharmony_ci It's possible to have input and output sharing the same buffer, 43527b27ec6Sopenharmony_ci for highly constrained memory environments. 43627b27ec6Sopenharmony_ci In both cases, it requires input to lay at the end of the buffer, 43727b27ec6Sopenharmony_ci and decompression to start at beginning of the buffer. 43827b27ec6Sopenharmony_ci Buffer size must feature some margin, hence be larger than final size. 43927b27ec6Sopenharmony_ci 44027b27ec6Sopenharmony_ci |<------------------------buffer--------------------------------->| 44127b27ec6Sopenharmony_ci |<-----------compressed data--------->| 44227b27ec6Sopenharmony_ci |<-----------decompressed size------------------>| 44327b27ec6Sopenharmony_ci |<----margin---->| 44427b27ec6Sopenharmony_ci 44527b27ec6Sopenharmony_ci This technique is more useful for decompression, 44627b27ec6Sopenharmony_ci since decompressed size is typically larger, 44727b27ec6Sopenharmony_ci and margin is short. 44827b27ec6Sopenharmony_ci 44927b27ec6Sopenharmony_ci In-place decompression will work inside any buffer 45027b27ec6Sopenharmony_ci which size is >= LZ4_DECOMPRESS_INPLACE_BUFFER_SIZE(decompressedSize). 45127b27ec6Sopenharmony_ci This presumes that decompressedSize > compressedSize. 45227b27ec6Sopenharmony_ci Otherwise, it means compression actually expanded data, 45327b27ec6Sopenharmony_ci and it would be more efficient to store such data with a flag indicating it's not compressed. 45427b27ec6Sopenharmony_ci This can happen when data is not compressible (already compressed, or encrypted). 45527b27ec6Sopenharmony_ci 45627b27ec6Sopenharmony_ci For in-place compression, margin is larger, as it must be able to cope with both 45727b27ec6Sopenharmony_ci history preservation, requiring input data to remain unmodified up to LZ4_DISTANCE_MAX, 45827b27ec6Sopenharmony_ci and data expansion, which can happen when input is not compressible. 45927b27ec6Sopenharmony_ci As a consequence, buffer size requirements are much higher, 46027b27ec6Sopenharmony_ci and memory savings offered by in-place compression are more limited. 46127b27ec6Sopenharmony_ci 46227b27ec6Sopenharmony_ci There are ways to limit this cost for compression : 46327b27ec6Sopenharmony_ci - Reduce history size, by modifying LZ4_DISTANCE_MAX. 46427b27ec6Sopenharmony_ci Note that it is a compile-time constant, so all compressions will apply this limit. 46527b27ec6Sopenharmony_ci Lower values will reduce compression ratio, except when input_size < LZ4_DISTANCE_MAX, 46627b27ec6Sopenharmony_ci so it's a reasonable trick when inputs are known to be small. 46727b27ec6Sopenharmony_ci - Require the compressor to deliver a "maximum compressed size". 46827b27ec6Sopenharmony_ci This is the `dstCapacity` parameter in `LZ4_compress*()`. 46927b27ec6Sopenharmony_ci When this size is < LZ4_COMPRESSBOUND(inputSize), then compression can fail, 47027b27ec6Sopenharmony_ci in which case, the return code will be 0 (zero). 47127b27ec6Sopenharmony_ci The caller must be ready for these cases to happen, 47227b27ec6Sopenharmony_ci and typically design a backup scheme to send data uncompressed. 47327b27ec6Sopenharmony_ci The combination of both techniques can significantly reduce 47427b27ec6Sopenharmony_ci the amount of margin required for in-place compression. 47527b27ec6Sopenharmony_ci 47627b27ec6Sopenharmony_ci In-place compression can work in any buffer 47727b27ec6Sopenharmony_ci which size is >= (maxCompressedSize) 47827b27ec6Sopenharmony_ci with maxCompressedSize == LZ4_COMPRESSBOUND(srcSize) for guaranteed compression success. 47927b27ec6Sopenharmony_ci LZ4_COMPRESS_INPLACE_BUFFER_SIZE() depends on both maxCompressedSize and LZ4_DISTANCE_MAX, 48027b27ec6Sopenharmony_ci so it's possible to reduce memory requirements by playing with them. 48127b27ec6Sopenharmony_ci 48227b27ec6Sopenharmony_ci</p></pre><BR> 48327b27ec6Sopenharmony_ci 48427b27ec6Sopenharmony_ci<pre><b>#define LZ4_DECOMPRESS_INPLACE_BUFFER_SIZE(decompressedSize) ((decompressedSize) + LZ4_DECOMPRESS_INPLACE_MARGIN(decompressedSize)) </b>/**< note: presumes that compressedSize < decompressedSize. note2: margin is overestimated a bit, since it could use compressedSize instead */<b> 48527b27ec6Sopenharmony_ci</b></pre><BR> 48627b27ec6Sopenharmony_ci<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> 48727b27ec6Sopenharmony_ci</b></pre><BR> 48827b27ec6Sopenharmony_ci<a name="Chapter9"></a><h2>Private Definitions</h2><pre> 48927b27ec6Sopenharmony_ci Do not use these definitions directly. 49027b27ec6Sopenharmony_ci They are only exposed to allow static allocation of `LZ4_stream_t` and `LZ4_streamDecode_t`. 49127b27ec6Sopenharmony_ci Accessing members will expose user code to API and/or ABI break in future versions of the library. 49227b27ec6Sopenharmony_ci<BR></pre> 49327b27ec6Sopenharmony_ci 49427b27ec6Sopenharmony_ci<pre><b></b><p> Never ever use below internal definitions directly ! 49527b27ec6Sopenharmony_ci These definitions are not API/ABI safe, and may change in future versions. 49627b27ec6Sopenharmony_ci If you need static allocation, declare or allocate an LZ4_stream_t object. 49727b27ec6Sopenharmony_ci</p></pre><BR> 49827b27ec6Sopenharmony_ci 49927b27ec6Sopenharmony_ci<pre><b>LZ4_stream_t* LZ4_initStream (void* buffer, size_t size); 50027b27ec6Sopenharmony_ci</b><p> An LZ4_stream_t structure must be initialized at least once. 50127b27ec6Sopenharmony_ci This is automatically done when invoking LZ4_createStream(), 50227b27ec6Sopenharmony_ci but it's not when the structure is simply declared on stack (for example). 50327b27ec6Sopenharmony_ci 50427b27ec6Sopenharmony_ci Use LZ4_initStream() to properly initialize a newly declared LZ4_stream_t. 50527b27ec6Sopenharmony_ci It can also initialize any arbitrary buffer of sufficient size, 50627b27ec6Sopenharmony_ci and will @return a pointer of proper type upon initialization. 50727b27ec6Sopenharmony_ci 50827b27ec6Sopenharmony_ci Note : initialization fails if size and alignment conditions are not respected. 50927b27ec6Sopenharmony_ci In which case, the function will @return NULL. 51027b27ec6Sopenharmony_ci Note2: An LZ4_stream_t structure guarantees correct alignment and size. 51127b27ec6Sopenharmony_ci Note3: Before v1.9.0, use LZ4_resetStream() instead 51227b27ec6Sopenharmony_ci</p></pre><BR> 51327b27ec6Sopenharmony_ci 51427b27ec6Sopenharmony_ci<pre><b>typedef struct { 51527b27ec6Sopenharmony_ci const LZ4_byte* externalDict; 51627b27ec6Sopenharmony_ci const LZ4_byte* prefixEnd; 51727b27ec6Sopenharmony_ci size_t extDictSize; 51827b27ec6Sopenharmony_ci size_t prefixSize; 51927b27ec6Sopenharmony_ci} LZ4_streamDecode_t_internal; 52027b27ec6Sopenharmony_ci</b><p> Never ever use below internal definitions directly ! 52127b27ec6Sopenharmony_ci These definitions are not API/ABI safe, and may change in future versions. 52227b27ec6Sopenharmony_ci If you need static allocation, declare or allocate an LZ4_streamDecode_t object. 52327b27ec6Sopenharmony_ci</p></pre><BR> 52427b27ec6Sopenharmony_ci 52527b27ec6Sopenharmony_ci<a name="Chapter10"></a><h2>Obsolete Functions</h2><pre></pre> 52627b27ec6Sopenharmony_ci 52727b27ec6Sopenharmony_ci<pre><b>#ifdef LZ4_DISABLE_DEPRECATE_WARNINGS 52827b27ec6Sopenharmony_ci# define LZ4_DEPRECATED(message) </b>/* disable deprecation warnings */<b> 52927b27ec6Sopenharmony_ci#else 53027b27ec6Sopenharmony_ci# if defined (__cplusplus) && (__cplusplus >= 201402) </b>/* C++14 or greater */<b> 53127b27ec6Sopenharmony_ci# define LZ4_DEPRECATED(message) [[deprecated(message)]] 53227b27ec6Sopenharmony_ci# elif defined(_MSC_VER) 53327b27ec6Sopenharmony_ci# define LZ4_DEPRECATED(message) __declspec(deprecated(message)) 53427b27ec6Sopenharmony_ci# elif defined(__clang__) || (defined(__GNUC__) && (__GNUC__ * 10 + __GNUC_MINOR__ >= 45)) 53527b27ec6Sopenharmony_ci# define LZ4_DEPRECATED(message) __attribute__((deprecated(message))) 53627b27ec6Sopenharmony_ci# elif defined(__GNUC__) && (__GNUC__ * 10 + __GNUC_MINOR__ >= 31) 53727b27ec6Sopenharmony_ci# define LZ4_DEPRECATED(message) __attribute__((deprecated)) 53827b27ec6Sopenharmony_ci# else 53927b27ec6Sopenharmony_ci# pragma message("WARNING: LZ4_DEPRECATED needs custom implementation for this compiler") 54027b27ec6Sopenharmony_ci# define LZ4_DEPRECATED(message) </b>/* disabled */<b> 54127b27ec6Sopenharmony_ci# endif 54227b27ec6Sopenharmony_ci#endif </b>/* LZ4_DISABLE_DEPRECATE_WARNINGS */<b> 54327b27ec6Sopenharmony_ci</b><p> 54427b27ec6Sopenharmony_ci Deprecated functions make the compiler generate a warning when invoked. 54527b27ec6Sopenharmony_ci This is meant to invite users to update their source code. 54627b27ec6Sopenharmony_ci Should deprecation warnings be a problem, it is generally possible to disable them, 54727b27ec6Sopenharmony_ci typically with -Wno-deprecated-declarations for gcc 54827b27ec6Sopenharmony_ci or _CRT_SECURE_NO_WARNINGS in Visual. 54927b27ec6Sopenharmony_ci 55027b27ec6Sopenharmony_ci Another method is to define LZ4_DISABLE_DEPRECATE_WARNINGS 55127b27ec6Sopenharmony_ci before including the header file. 55227b27ec6Sopenharmony_ci 55327b27ec6Sopenharmony_ci</p></pre><BR> 55427b27ec6Sopenharmony_ci 55527b27ec6Sopenharmony_ci<pre><b>LZ4_DEPRECATED("use LZ4_compress_default() instead") LZ4LIB_API int LZ4_compress (const char* src, char* dest, int srcSize); 55627b27ec6Sopenharmony_ciLZ4_DEPRECATED("use LZ4_compress_default() instead") LZ4LIB_API int LZ4_compress_limitedOutput (const char* src, char* dest, int srcSize, int maxOutputSize); 55727b27ec6Sopenharmony_ciLZ4_DEPRECATED("use LZ4_compress_fast_extState() instead") LZ4LIB_API int LZ4_compress_withState (void* state, const char* source, char* dest, int inputSize); 55827b27ec6Sopenharmony_ciLZ4_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); 55927b27ec6Sopenharmony_ciLZ4_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); 56027b27ec6Sopenharmony_ciLZ4_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); 56127b27ec6Sopenharmony_ci</b><p></p></pre><BR> 56227b27ec6Sopenharmony_ci 56327b27ec6Sopenharmony_ci<pre><b>LZ4_DEPRECATED("use LZ4_decompress_fast() instead") LZ4LIB_API int LZ4_uncompress (const char* source, char* dest, int outputSize); 56427b27ec6Sopenharmony_ciLZ4_DEPRECATED("use LZ4_decompress_safe() instead") LZ4LIB_API int LZ4_uncompress_unknownOutputSize (const char* source, char* dest, int isize, int maxOutputSize); 56527b27ec6Sopenharmony_ci</b><p></p></pre><BR> 56627b27ec6Sopenharmony_ci 56727b27ec6Sopenharmony_ci<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); 56827b27ec6Sopenharmony_ciLZ4_DEPRECATED("use LZ4_decompress_fast_usingDict() instead") LZ4LIB_API int LZ4_decompress_fast_withPrefix64k (const char* src, char* dst, int originalSize); 56927b27ec6Sopenharmony_ci</b><p></p></pre><BR> 57027b27ec6Sopenharmony_ci 57127b27ec6Sopenharmony_ci<pre><b>LZ4_DEPRECATED("This function is deprecated and unsafe. Consider using LZ4_decompress_safe() instead") 57227b27ec6Sopenharmony_ciint LZ4_decompress_fast (const char* src, char* dst, int originalSize); 57327b27ec6Sopenharmony_ciLZ4_DEPRECATED("This function is deprecated and unsafe. Consider using LZ4_decompress_safe_continue() instead") 57427b27ec6Sopenharmony_ciint LZ4_decompress_fast_continue (LZ4_streamDecode_t* LZ4_streamDecode, const char* src, char* dst, int originalSize); 57527b27ec6Sopenharmony_ciLZ4_DEPRECATED("This function is deprecated and unsafe. Consider using LZ4_decompress_safe_usingDict() instead") 57627b27ec6Sopenharmony_ciint LZ4_decompress_fast_usingDict (const char* src, char* dst, int originalSize, const char* dictStart, int dictSize); 57727b27ec6Sopenharmony_ci</b><p> These functions used to be faster than LZ4_decompress_safe(), 57827b27ec6Sopenharmony_ci but this is no longer the case. They are now slower. 57927b27ec6Sopenharmony_ci This is because LZ4_decompress_fast() doesn't know the input size, 58027b27ec6Sopenharmony_ci and therefore must progress more cautiously into the input buffer to not read beyond the end of block. 58127b27ec6Sopenharmony_ci On top of that `LZ4_decompress_fast()` is not protected vs malformed or malicious inputs, making it a security liability. 58227b27ec6Sopenharmony_ci As a consequence, LZ4_decompress_fast() is strongly discouraged, and deprecated. 58327b27ec6Sopenharmony_ci 58427b27ec6Sopenharmony_ci The last remaining LZ4_decompress_fast() specificity is that 58527b27ec6Sopenharmony_ci it can decompress a block without knowing its compressed size. 58627b27ec6Sopenharmony_ci Such functionality can be achieved in a more secure manner 58727b27ec6Sopenharmony_ci by employing LZ4_decompress_safe_partial(). 58827b27ec6Sopenharmony_ci 58927b27ec6Sopenharmony_ci Parameters: 59027b27ec6Sopenharmony_ci originalSize : is the uncompressed size to regenerate. 59127b27ec6Sopenharmony_ci `dst` must be already allocated, its size must be >= 'originalSize' bytes. 59227b27ec6Sopenharmony_ci @return : number of bytes read from source buffer (== compressed size). 59327b27ec6Sopenharmony_ci The function expects to finish at block's end exactly. 59427b27ec6Sopenharmony_ci If the source stream is detected malformed, the function stops decoding and returns a negative result. 59527b27ec6Sopenharmony_ci note : LZ4_decompress_fast*() requires originalSize. Thanks to this information, it never writes past the output buffer. 59627b27ec6Sopenharmony_ci However, since it doesn't know its 'src' size, it may read an unknown amount of input, past input buffer bounds. 59727b27ec6Sopenharmony_ci Also, since match offsets are not validated, match reads from 'src' may underflow too. 59827b27ec6Sopenharmony_ci These issues never happen if input (compressed) data is correct. 59927b27ec6Sopenharmony_ci But they may happen if input data is invalid (error or intentional tampering). 60027b27ec6Sopenharmony_ci As a consequence, use these functions in trusted environments with trusted data **only**. 60127b27ec6Sopenharmony_ci 60227b27ec6Sopenharmony_ci</p></pre><BR> 60327b27ec6Sopenharmony_ci 60427b27ec6Sopenharmony_ci<pre><b>void LZ4_resetStream (LZ4_stream_t* streamPtr); 60527b27ec6Sopenharmony_ci</b><p> An LZ4_stream_t structure must be initialized at least once. 60627b27ec6Sopenharmony_ci This is done with LZ4_initStream(), or LZ4_resetStream(). 60727b27ec6Sopenharmony_ci Consider switching to LZ4_initStream(), 60827b27ec6Sopenharmony_ci invoking LZ4_resetStream() will trigger deprecation warnings in the future. 60927b27ec6Sopenharmony_ci 61027b27ec6Sopenharmony_ci</p></pre><BR> 61127b27ec6Sopenharmony_ci 61227b27ec6Sopenharmony_ci</html> 61327b27ec6Sopenharmony_ci</body> 614