1*27162e4eSAndroid Build Coastguard Worker<html> 2*27162e4eSAndroid Build Coastguard Worker<head> 3*27162e4eSAndroid Build Coastguard Worker<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> 4*27162e4eSAndroid Build Coastguard Worker<title>1.10.0 Manual</title> 5*27162e4eSAndroid Build Coastguard Worker</head> 6*27162e4eSAndroid Build Coastguard Worker<body> 7*27162e4eSAndroid Build Coastguard Worker<h1>1.10.0 Manual</h1> 8*27162e4eSAndroid Build Coastguard Worker<hr> 9*27162e4eSAndroid Build Coastguard Worker<a name="Contents"></a><h2>Contents</h2> 10*27162e4eSAndroid Build Coastguard Worker<ol> 11*27162e4eSAndroid Build Coastguard Worker<li><a href="#Chapter1">Introduction</a></li> 12*27162e4eSAndroid Build Coastguard Worker<li><a href="#Chapter2">Version</a></li> 13*27162e4eSAndroid Build Coastguard Worker<li><a href="#Chapter3">Tuning memory usage</a></li> 14*27162e4eSAndroid Build Coastguard Worker<li><a href="#Chapter4">Simple Functions</a></li> 15*27162e4eSAndroid Build Coastguard Worker<li><a href="#Chapter5">Advanced Functions</a></li> 16*27162e4eSAndroid Build Coastguard Worker<li><a href="#Chapter6">Streaming Compression Functions</a></li> 17*27162e4eSAndroid Build Coastguard Worker<li><a href="#Chapter7">Streaming Decompression Functions</a></li> 18*27162e4eSAndroid Build Coastguard Worker<li><a href="#Chapter8">Experimental section</a></li> 19*27162e4eSAndroid Build Coastguard Worker<li><a href="#Chapter9">Private Definitions</a></li> 20*27162e4eSAndroid Build Coastguard Worker<li><a href="#Chapter10">Obsolete Functions</a></li> 21*27162e4eSAndroid Build Coastguard Worker</ol> 22*27162e4eSAndroid Build Coastguard Worker<hr> 23*27162e4eSAndroid Build Coastguard Worker<a name="Chapter1"></a><h2>Introduction</h2><pre> 24*27162e4eSAndroid Build Coastguard Worker LZ4 is lossless compression algorithm, providing compression speed >500 MB/s per core, 25*27162e4eSAndroid Build Coastguard Worker scalable with multi-cores CPU. It features an extremely fast decoder, with speed in 26*27162e4eSAndroid Build Coastguard Worker multiple GB/s per core, typically reaching RAM speed limits on multi-core systems. 27*27162e4eSAndroid Build Coastguard Worker 28*27162e4eSAndroid Build Coastguard Worker The LZ4 compression library provides in-memory compression and decompression functions. 29*27162e4eSAndroid Build Coastguard Worker It gives full buffer control to user. 30*27162e4eSAndroid Build Coastguard Worker Compression can be done in: 31*27162e4eSAndroid Build Coastguard Worker - a single step (described as Simple Functions) 32*27162e4eSAndroid Build Coastguard Worker - a single step, reusing a context (described in Advanced Functions) 33*27162e4eSAndroid Build Coastguard Worker - unbounded multiple steps (described as Streaming compression) 34*27162e4eSAndroid Build Coastguard Worker 35*27162e4eSAndroid Build Coastguard Worker lz4.h generates and decodes LZ4-compressed blocks (doc/lz4_Block_format.md). 36*27162e4eSAndroid Build Coastguard Worker Decompressing such a compressed block requires additional metadata. 37*27162e4eSAndroid Build Coastguard Worker Exact metadata depends on exact decompression function. 38*27162e4eSAndroid Build Coastguard Worker For the typical case of LZ4_decompress_safe(), 39*27162e4eSAndroid Build Coastguard Worker metadata includes block's compressed size, and maximum bound of decompressed size. 40*27162e4eSAndroid Build Coastguard Worker Each application is free to encode and pass such metadata in whichever way it wants. 41*27162e4eSAndroid Build Coastguard Worker 42*27162e4eSAndroid Build Coastguard Worker lz4.h only handle blocks, it can not generate Frames. 43*27162e4eSAndroid Build Coastguard Worker 44*27162e4eSAndroid Build Coastguard Worker Blocks are different from Frames (doc/lz4_Frame_format.md). 45*27162e4eSAndroid Build Coastguard Worker Frames bundle both blocks and metadata in a specified manner. 46*27162e4eSAndroid Build Coastguard Worker Embedding metadata is required for compressed data to be self-contained and portable. 47*27162e4eSAndroid Build Coastguard Worker Frame format is delivered through a companion API, declared in lz4frame.h. 48*27162e4eSAndroid Build Coastguard Worker The `lz4` CLI can only manage frames. 49*27162e4eSAndroid Build Coastguard Worker<BR></pre> 50*27162e4eSAndroid Build Coastguard Worker 51*27162e4eSAndroid Build Coastguard Worker<pre><b>#if defined(LZ4_FREESTANDING) && (LZ4_FREESTANDING == 1) 52*27162e4eSAndroid Build Coastguard Worker# define LZ4_HEAPMODE 0 53*27162e4eSAndroid Build Coastguard Worker# define LZ4HC_HEAPMODE 0 54*27162e4eSAndroid Build Coastguard Worker# define LZ4_STATIC_LINKING_ONLY_DISABLE_MEMORY_ALLOCATION 1 55*27162e4eSAndroid Build Coastguard Worker# if !defined(LZ4_memcpy) 56*27162e4eSAndroid Build Coastguard Worker# error "LZ4_FREESTANDING requires macro 'LZ4_memcpy'." 57*27162e4eSAndroid Build Coastguard Worker# endif 58*27162e4eSAndroid Build Coastguard Worker# if !defined(LZ4_memset) 59*27162e4eSAndroid Build Coastguard Worker# error "LZ4_FREESTANDING requires macro 'LZ4_memset'." 60*27162e4eSAndroid Build Coastguard Worker# endif 61*27162e4eSAndroid Build Coastguard Worker# if !defined(LZ4_memmove) 62*27162e4eSAndroid Build Coastguard Worker# error "LZ4_FREESTANDING requires macro 'LZ4_memmove'." 63*27162e4eSAndroid Build Coastguard Worker# endif 64*27162e4eSAndroid Build Coastguard Worker#elif ! defined(LZ4_FREESTANDING) 65*27162e4eSAndroid Build Coastguard Worker# define LZ4_FREESTANDING 0 66*27162e4eSAndroid Build Coastguard Worker#endif 67*27162e4eSAndroid Build Coastguard Worker</b><p> When this macro is set to 1, it enables "freestanding mode" that is 68*27162e4eSAndroid Build Coastguard Worker suitable for typical freestanding environment which doesn't support 69*27162e4eSAndroid Build Coastguard Worker standard C library. 70*27162e4eSAndroid Build Coastguard Worker 71*27162e4eSAndroid Build Coastguard Worker - LZ4_FREESTANDING is a compile-time switch. 72*27162e4eSAndroid Build Coastguard Worker - It requires the following macros to be defined: 73*27162e4eSAndroid Build Coastguard Worker LZ4_memcpy, LZ4_memmove, LZ4_memset. 74*27162e4eSAndroid Build Coastguard Worker - It only enables LZ4/HC functions which don't use heap. 75*27162e4eSAndroid Build Coastguard Worker All LZ4F_* functions are not supported. 76*27162e4eSAndroid Build Coastguard Worker - See tests/freestanding.c to check its basic setup. 77*27162e4eSAndroid Build Coastguard Worker 78*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 79*27162e4eSAndroid Build Coastguard Worker 80*27162e4eSAndroid Build Coastguard Worker<a name="Chapter2"></a><h2>Version</h2><pre></pre> 81*27162e4eSAndroid Build Coastguard Worker 82*27162e4eSAndroid Build Coastguard Worker<pre><b>int LZ4_versionNumber (void); </b>/**< library version number; useful to check dll version; requires v1.3.0+ */<b> 83*27162e4eSAndroid Build Coastguard Worker</b></pre><BR> 84*27162e4eSAndroid Build Coastguard Worker<pre><b>const char* LZ4_versionString (void); </b>/**< library version string; useful to check dll version; requires v1.7.5+ */<b> 85*27162e4eSAndroid Build Coastguard Worker</b></pre><BR> 86*27162e4eSAndroid Build Coastguard Worker<a name="Chapter3"></a><h2>Tuning memory usage</h2><pre></pre> 87*27162e4eSAndroid Build Coastguard Worker 88*27162e4eSAndroid Build Coastguard Worker<pre><b>#ifndef LZ4_MEMORY_USAGE 89*27162e4eSAndroid Build Coastguard Worker# define LZ4_MEMORY_USAGE LZ4_MEMORY_USAGE_DEFAULT 90*27162e4eSAndroid Build Coastguard Worker#endif 91*27162e4eSAndroid Build Coastguard Worker</b><p> Can be selected at compile time, by setting LZ4_MEMORY_USAGE. 92*27162e4eSAndroid Build Coastguard Worker Memory usage formula : N->2^N Bytes (examples : 10 -> 1KB; 12 -> 4KB ; 16 -> 64KB; 20 -> 1MB) 93*27162e4eSAndroid Build Coastguard Worker Increasing memory usage improves compression ratio, generally at the cost of speed. 94*27162e4eSAndroid Build Coastguard Worker Reduced memory usage may improve speed at the cost of ratio, thanks to better cache locality. 95*27162e4eSAndroid Build Coastguard Worker Default value is 14, for 16KB, which nicely fits into most L1 caches. 96*27162e4eSAndroid Build Coastguard Worker 97*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 98*27162e4eSAndroid Build Coastguard Worker 99*27162e4eSAndroid Build Coastguard Worker<a name="Chapter4"></a><h2>Simple Functions</h2><pre></pre> 100*27162e4eSAndroid Build Coastguard Worker 101*27162e4eSAndroid Build Coastguard Worker<pre><b>int LZ4_compress_default(const char* src, char* dst, int srcSize, int dstCapacity); 102*27162e4eSAndroid Build Coastguard Worker</b><p> Compresses 'srcSize' bytes from buffer 'src' 103*27162e4eSAndroid Build Coastguard Worker into already allocated 'dst' buffer of size 'dstCapacity'. 104*27162e4eSAndroid Build Coastguard Worker Compression is guaranteed to succeed if 'dstCapacity' >= LZ4_compressBound(srcSize). 105*27162e4eSAndroid Build Coastguard Worker It also runs faster, so it's a recommended setting. 106*27162e4eSAndroid Build Coastguard Worker If the function cannot compress 'src' into a more limited 'dst' budget, 107*27162e4eSAndroid Build Coastguard Worker compression stops *immediately*, and the function result is zero. 108*27162e4eSAndroid Build Coastguard Worker In which case, 'dst' content is undefined (invalid). 109*27162e4eSAndroid Build Coastguard Worker srcSize : max supported value is LZ4_MAX_INPUT_SIZE. 110*27162e4eSAndroid Build Coastguard Worker dstCapacity : size of buffer 'dst' (which must be already allocated) 111*27162e4eSAndroid Build Coastguard Worker @return : the number of bytes written into buffer 'dst' (necessarily <= dstCapacity) 112*27162e4eSAndroid Build Coastguard Worker or 0 if compression fails 113*27162e4eSAndroid Build Coastguard Worker Note : This function is protected against buffer overflow scenarios (never writes outside 'dst' buffer, nor read outside 'source' buffer). 114*27162e4eSAndroid Build Coastguard Worker 115*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 116*27162e4eSAndroid Build Coastguard Worker 117*27162e4eSAndroid Build Coastguard Worker<pre><b>int LZ4_decompress_safe (const char* src, char* dst, int compressedSize, int dstCapacity); 118*27162e4eSAndroid Build Coastguard Worker</b><p> @compressedSize : is the exact complete size of the compressed block. 119*27162e4eSAndroid Build Coastguard Worker @dstCapacity : is the size of destination buffer (which must be already allocated), 120*27162e4eSAndroid Build Coastguard Worker presumed an upper bound of decompressed size. 121*27162e4eSAndroid Build Coastguard Worker @return : the number of bytes decompressed into destination buffer (necessarily <= dstCapacity) 122*27162e4eSAndroid Build Coastguard Worker If destination buffer is not large enough, decoding will stop and output an error code (negative value). 123*27162e4eSAndroid Build Coastguard Worker If the source stream is detected malformed, the function will stop decoding and return a negative result. 124*27162e4eSAndroid Build Coastguard Worker Note 1 : This function is protected against malicious data packets : 125*27162e4eSAndroid Build Coastguard Worker it will never writes outside 'dst' buffer, nor read outside 'source' buffer, 126*27162e4eSAndroid Build Coastguard Worker even if the compressed block is maliciously modified to order the decoder to do these actions. 127*27162e4eSAndroid Build Coastguard Worker In such case, the decoder stops immediately, and considers the compressed block malformed. 128*27162e4eSAndroid Build Coastguard Worker Note 2 : compressedSize and dstCapacity must be provided to the function, the compressed block does not contain them. 129*27162e4eSAndroid Build Coastguard Worker The implementation is free to send / store / derive this information in whichever way is most beneficial. 130*27162e4eSAndroid Build Coastguard Worker If there is a need for a different format which bundles together both compressed data and its metadata, consider looking at lz4frame.h instead. 131*27162e4eSAndroid Build Coastguard Worker 132*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 133*27162e4eSAndroid Build Coastguard Worker 134*27162e4eSAndroid Build Coastguard Worker<a name="Chapter5"></a><h2>Advanced Functions</h2><pre></pre> 135*27162e4eSAndroid Build Coastguard Worker 136*27162e4eSAndroid Build Coastguard Worker<pre><b>int LZ4_compressBound(int inputSize); 137*27162e4eSAndroid Build Coastguard Worker</b><p> Provides the maximum size that LZ4 compression may output in a "worst case" scenario (input data not compressible) 138*27162e4eSAndroid Build Coastguard Worker This function is primarily useful for memory allocation purposes (destination buffer size). 139*27162e4eSAndroid Build Coastguard Worker Macro LZ4_COMPRESSBOUND() is also provided for compilation-time evaluation (stack memory allocation for example). 140*27162e4eSAndroid Build Coastguard Worker Note that LZ4_compress_default() compresses faster when dstCapacity is >= LZ4_compressBound(srcSize) 141*27162e4eSAndroid Build Coastguard Worker inputSize : max supported value is LZ4_MAX_INPUT_SIZE 142*27162e4eSAndroid Build Coastguard Worker return : maximum output size in a "worst case" scenario 143*27162e4eSAndroid Build Coastguard Worker or 0, if input size is incorrect (too large or negative) 144*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 145*27162e4eSAndroid Build Coastguard Worker 146*27162e4eSAndroid Build Coastguard Worker<pre><b>int LZ4_compress_fast (const char* src, char* dst, int srcSize, int dstCapacity, int acceleration); 147*27162e4eSAndroid Build Coastguard Worker</b><p> Same as LZ4_compress_default(), but allows selection of "acceleration" factor. 148*27162e4eSAndroid Build Coastguard Worker The larger the acceleration value, the faster the algorithm, but also the lesser the compression. 149*27162e4eSAndroid Build Coastguard Worker It's a trade-off. It can be fine tuned, with each successive value providing roughly +~3% to speed. 150*27162e4eSAndroid Build Coastguard Worker An acceleration value of "1" is the same as regular LZ4_compress_default() 151*27162e4eSAndroid Build Coastguard Worker Values <= 0 will be replaced by LZ4_ACCELERATION_DEFAULT (currently == 1, see lz4.c). 152*27162e4eSAndroid Build Coastguard Worker Values > LZ4_ACCELERATION_MAX will be replaced by LZ4_ACCELERATION_MAX (currently == 65537, see lz4.c). 153*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 154*27162e4eSAndroid Build Coastguard Worker 155*27162e4eSAndroid Build Coastguard Worker<pre><b>int LZ4_sizeofState(void); 156*27162e4eSAndroid Build Coastguard Workerint LZ4_compress_fast_extState (void* state, const char* src, char* dst, int srcSize, int dstCapacity, int acceleration); 157*27162e4eSAndroid Build Coastguard Worker</b><p> Same as LZ4_compress_fast(), using an externally allocated memory space for its state. 158*27162e4eSAndroid Build Coastguard Worker Use LZ4_sizeofState() to know how much memory must be allocated, 159*27162e4eSAndroid Build Coastguard Worker and allocate it on 8-bytes boundaries (using `malloc()` typically). 160*27162e4eSAndroid Build Coastguard Worker Then, provide this buffer as `void* state` to compression function. 161*27162e4eSAndroid Build Coastguard Worker 162*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 163*27162e4eSAndroid Build Coastguard Worker 164*27162e4eSAndroid Build Coastguard Worker<pre><b>int LZ4_compress_destSize(const char* src, char* dst, int* srcSizePtr, int targetDstSize); 165*27162e4eSAndroid Build Coastguard Worker</b><p> Reverse the logic : compresses as much data as possible from 'src' buffer 166*27162e4eSAndroid Build Coastguard Worker into already allocated buffer 'dst', of size >= 'dstCapacity'. 167*27162e4eSAndroid Build Coastguard Worker This function either compresses the entire 'src' content into 'dst' if it's large enough, 168*27162e4eSAndroid Build Coastguard Worker or fill 'dst' buffer completely with as much data as possible from 'src'. 169*27162e4eSAndroid Build Coastguard Worker note: acceleration parameter is fixed to "default". 170*27162e4eSAndroid Build Coastguard Worker 171*27162e4eSAndroid Build Coastguard Worker *srcSizePtr : in+out parameter. Initially contains size of input. 172*27162e4eSAndroid Build Coastguard Worker Will be modified to indicate how many bytes where read from 'src' to fill 'dst'. 173*27162e4eSAndroid Build Coastguard Worker New value is necessarily <= input value. 174*27162e4eSAndroid Build Coastguard Worker @return : Nb bytes written into 'dst' (necessarily <= dstCapacity) 175*27162e4eSAndroid Build Coastguard Worker or 0 if compression fails. 176*27162e4eSAndroid Build Coastguard Worker 177*27162e4eSAndroid Build Coastguard Worker Note : from v1.8.2 to v1.9.1, this function had a bug (fixed in v1.9.2+): 178*27162e4eSAndroid Build Coastguard Worker the produced compressed content could, in specific circumstances, 179*27162e4eSAndroid Build Coastguard Worker require to be decompressed into a destination buffer larger 180*27162e4eSAndroid Build Coastguard Worker by at least 1 byte than the content to decompress. 181*27162e4eSAndroid Build Coastguard Worker If an application uses `LZ4_compress_destSize()`, 182*27162e4eSAndroid Build Coastguard Worker it's highly recommended to update liblz4 to v1.9.2 or better. 183*27162e4eSAndroid Build Coastguard Worker If this can't be done or ensured, 184*27162e4eSAndroid Build Coastguard Worker the receiving decompression function should provide 185*27162e4eSAndroid Build Coastguard Worker a dstCapacity which is > decompressedSize, by at least 1 byte. 186*27162e4eSAndroid Build Coastguard Worker See https://github.com/lz4/lz4/issues/859 for details 187*27162e4eSAndroid Build Coastguard Worker 188*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 189*27162e4eSAndroid Build Coastguard Worker 190*27162e4eSAndroid Build Coastguard Worker<pre><b>int LZ4_decompress_safe_partial (const char* src, char* dst, int srcSize, int targetOutputSize, int dstCapacity); 191*27162e4eSAndroid Build Coastguard Worker</b><p> Decompress an LZ4 compressed block, of size 'srcSize' at position 'src', 192*27162e4eSAndroid Build Coastguard Worker into destination buffer 'dst' of size 'dstCapacity'. 193*27162e4eSAndroid Build Coastguard Worker Up to 'targetOutputSize' bytes will be decoded. 194*27162e4eSAndroid Build Coastguard Worker The function stops decoding on reaching this objective. 195*27162e4eSAndroid Build Coastguard Worker This can be useful to boost performance 196*27162e4eSAndroid Build Coastguard Worker whenever only the beginning of a block is required. 197*27162e4eSAndroid Build Coastguard Worker 198*27162e4eSAndroid Build Coastguard Worker @return : the number of bytes decoded in `dst` (necessarily <= targetOutputSize) 199*27162e4eSAndroid Build Coastguard Worker If source stream is detected malformed, function returns a negative result. 200*27162e4eSAndroid Build Coastguard Worker 201*27162e4eSAndroid Build Coastguard Worker Note 1 : @return can be < targetOutputSize, if compressed block contains less data. 202*27162e4eSAndroid Build Coastguard Worker 203*27162e4eSAndroid Build Coastguard Worker Note 2 : targetOutputSize must be <= dstCapacity 204*27162e4eSAndroid Build Coastguard Worker 205*27162e4eSAndroid Build Coastguard Worker Note 3 : this function effectively stops decoding on reaching targetOutputSize, 206*27162e4eSAndroid Build Coastguard Worker so dstCapacity is kind of redundant. 207*27162e4eSAndroid Build Coastguard Worker This is because in older versions of this function, 208*27162e4eSAndroid Build Coastguard Worker decoding operation would still write complete sequences. 209*27162e4eSAndroid Build Coastguard Worker Therefore, there was no guarantee that it would stop writing at exactly targetOutputSize, 210*27162e4eSAndroid Build Coastguard Worker it could write more bytes, though only up to dstCapacity. 211*27162e4eSAndroid Build Coastguard Worker Some "margin" used to be required for this operation to work properly. 212*27162e4eSAndroid Build Coastguard Worker Thankfully, this is no longer necessary. 213*27162e4eSAndroid Build Coastguard Worker The function nonetheless keeps the same signature, in an effort to preserve API compatibility. 214*27162e4eSAndroid Build Coastguard Worker 215*27162e4eSAndroid Build Coastguard Worker Note 4 : If srcSize is the exact size of the block, 216*27162e4eSAndroid Build Coastguard Worker then targetOutputSize can be any value, 217*27162e4eSAndroid Build Coastguard Worker including larger than the block's decompressed size. 218*27162e4eSAndroid Build Coastguard Worker The function will, at most, generate block's decompressed size. 219*27162e4eSAndroid Build Coastguard Worker 220*27162e4eSAndroid Build Coastguard Worker Note 5 : If srcSize is _larger_ than block's compressed size, 221*27162e4eSAndroid Build Coastguard Worker then targetOutputSize **MUST** be <= block's decompressed size. 222*27162e4eSAndroid Build Coastguard Worker Otherwise, *silent corruption will occur*. 223*27162e4eSAndroid Build Coastguard Worker 224*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 225*27162e4eSAndroid Build Coastguard Worker 226*27162e4eSAndroid Build Coastguard Worker<a name="Chapter6"></a><h2>Streaming Compression Functions</h2><pre></pre> 227*27162e4eSAndroid Build Coastguard Worker 228*27162e4eSAndroid Build Coastguard Worker<pre><b>#if !defined(RC_INVOKED) </b>/* https://docs.microsoft.com/en-us/windows/win32/menurc/predefined-macros */<b> 229*27162e4eSAndroid Build Coastguard Worker#if !defined(LZ4_STATIC_LINKING_ONLY_DISABLE_MEMORY_ALLOCATION) 230*27162e4eSAndroid Build Coastguard WorkerLZ4_stream_t* LZ4_createStream(void); 231*27162e4eSAndroid Build Coastguard Workerint LZ4_freeStream (LZ4_stream_t* streamPtr); 232*27162e4eSAndroid Build Coastguard Worker#endif </b>/* !defined(LZ4_STATIC_LINKING_ONLY_DISABLE_MEMORY_ALLOCATION) */<b> 233*27162e4eSAndroid Build Coastguard Worker#endif 234*27162e4eSAndroid Build Coastguard Worker</b><p> 235*27162e4eSAndroid Build Coastguard Worker - RC_INVOKED is predefined symbol of rc.exe (the resource compiler which is part of MSVC/Visual Studio). 236*27162e4eSAndroid Build Coastguard Worker https://docs.microsoft.com/en-us/windows/win32/menurc/predefined-macros 237*27162e4eSAndroid Build Coastguard Worker 238*27162e4eSAndroid Build Coastguard Worker - Since rc.exe is a legacy compiler, it truncates long symbol (> 30 chars) 239*27162e4eSAndroid Build Coastguard Worker and reports warning "RC4011: identifier truncated". 240*27162e4eSAndroid Build Coastguard Worker 241*27162e4eSAndroid Build Coastguard Worker - To eliminate the warning, we surround long preprocessor symbol with 242*27162e4eSAndroid Build Coastguard Worker "#if !defined(RC_INVOKED) ... #endif" block that means 243*27162e4eSAndroid Build Coastguard Worker "skip this block when rc.exe is trying to read it". 244*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 245*27162e4eSAndroid Build Coastguard Worker 246*27162e4eSAndroid Build Coastguard Worker<pre><b>void LZ4_resetStream_fast (LZ4_stream_t* streamPtr); 247*27162e4eSAndroid Build Coastguard Worker</b><p> Use this to prepare an LZ4_stream_t for a new chain of dependent blocks 248*27162e4eSAndroid Build Coastguard Worker (e.g., LZ4_compress_fast_continue()). 249*27162e4eSAndroid Build Coastguard Worker 250*27162e4eSAndroid Build Coastguard Worker An LZ4_stream_t must be initialized once before usage. 251*27162e4eSAndroid Build Coastguard Worker This is automatically done when created by LZ4_createStream(). 252*27162e4eSAndroid Build Coastguard Worker However, should the LZ4_stream_t be simply declared on stack (for example), 253*27162e4eSAndroid Build Coastguard Worker it's necessary to initialize it first, using LZ4_initStream(). 254*27162e4eSAndroid Build Coastguard Worker 255*27162e4eSAndroid Build Coastguard Worker After init, start any new stream with LZ4_resetStream_fast(). 256*27162e4eSAndroid Build Coastguard Worker A same LZ4_stream_t can be re-used multiple times consecutively 257*27162e4eSAndroid Build Coastguard Worker and compress multiple streams, 258*27162e4eSAndroid Build Coastguard Worker provided that it starts each new stream with LZ4_resetStream_fast(). 259*27162e4eSAndroid Build Coastguard Worker 260*27162e4eSAndroid Build Coastguard Worker LZ4_resetStream_fast() is much faster than LZ4_initStream(), 261*27162e4eSAndroid Build Coastguard Worker but is not compatible with memory regions containing garbage data. 262*27162e4eSAndroid Build Coastguard Worker 263*27162e4eSAndroid Build Coastguard Worker Note: it's only useful to call LZ4_resetStream_fast() 264*27162e4eSAndroid Build Coastguard Worker in the context of streaming compression. 265*27162e4eSAndroid Build Coastguard Worker The *extState* functions perform their own resets. 266*27162e4eSAndroid Build Coastguard Worker Invoking LZ4_resetStream_fast() before is redundant, and even counterproductive. 267*27162e4eSAndroid Build Coastguard Worker 268*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 269*27162e4eSAndroid Build Coastguard Worker 270*27162e4eSAndroid Build Coastguard Worker<pre><b>int LZ4_loadDict (LZ4_stream_t* streamPtr, const char* dictionary, int dictSize); 271*27162e4eSAndroid Build Coastguard Worker</b><p> Use this function to reference a static dictionary into LZ4_stream_t. 272*27162e4eSAndroid Build Coastguard Worker The dictionary must remain available during compression. 273*27162e4eSAndroid Build Coastguard Worker LZ4_loadDict() triggers a reset, so any previous data will be forgotten. 274*27162e4eSAndroid Build Coastguard Worker The same dictionary will have to be loaded on decompression side for successful decoding. 275*27162e4eSAndroid Build Coastguard Worker Dictionary are useful for better compression of small data (KB range). 276*27162e4eSAndroid Build Coastguard Worker While LZ4 itself accepts any input as dictionary, dictionary efficiency is also a topic. 277*27162e4eSAndroid Build Coastguard Worker When in doubt, employ the Zstandard's Dictionary Builder. 278*27162e4eSAndroid Build Coastguard Worker Loading a size of 0 is allowed, and is the same as reset. 279*27162e4eSAndroid Build Coastguard Worker @return : loaded dictionary size, in bytes (note: only the last 64 KB are loaded) 280*27162e4eSAndroid Build Coastguard Worker 281*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 282*27162e4eSAndroid Build Coastguard Worker 283*27162e4eSAndroid Build Coastguard Worker<pre><b>int LZ4_loadDictSlow(LZ4_stream_t* streamPtr, const char* dictionary, int dictSize); 284*27162e4eSAndroid Build Coastguard Worker</b><p> Same as LZ4_loadDict(), 285*27162e4eSAndroid Build Coastguard Worker but uses a bit more cpu to reference the dictionary content more thoroughly. 286*27162e4eSAndroid Build Coastguard Worker This is expected to slightly improve compression ratio. 287*27162e4eSAndroid Build Coastguard Worker The extra-cpu cost is likely worth it if the dictionary is re-used across multiple sessions. 288*27162e4eSAndroid Build Coastguard Worker @return : loaded dictionary size, in bytes (note: only the last 64 KB are loaded) 289*27162e4eSAndroid Build Coastguard Worker 290*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 291*27162e4eSAndroid Build Coastguard Worker 292*27162e4eSAndroid Build Coastguard Worker<pre><b>void 293*27162e4eSAndroid Build Coastguard WorkerLZ4_attach_dictionary(LZ4_stream_t* workingStream, 294*27162e4eSAndroid Build Coastguard Worker const LZ4_stream_t* dictionaryStream); 295*27162e4eSAndroid Build Coastguard Worker</b><p> 296*27162e4eSAndroid Build Coastguard Worker This allows efficient re-use of a static dictionary multiple times. 297*27162e4eSAndroid Build Coastguard Worker 298*27162e4eSAndroid Build Coastguard Worker Rather than re-loading the dictionary buffer into a working context before 299*27162e4eSAndroid Build Coastguard Worker each compression, or copying a pre-loaded dictionary's LZ4_stream_t into a 300*27162e4eSAndroid Build Coastguard Worker working LZ4_stream_t, this function introduces a no-copy setup mechanism, 301*27162e4eSAndroid Build Coastguard Worker in which the working stream references @dictionaryStream in-place. 302*27162e4eSAndroid Build Coastguard Worker 303*27162e4eSAndroid Build Coastguard Worker Several assumptions are made about the state of @dictionaryStream. 304*27162e4eSAndroid Build Coastguard Worker Currently, only states which have been prepared by LZ4_loadDict() or 305*27162e4eSAndroid Build Coastguard Worker LZ4_loadDictSlow() should be expected to work. 306*27162e4eSAndroid Build Coastguard Worker 307*27162e4eSAndroid Build Coastguard Worker Alternatively, the provided @dictionaryStream may be NULL, 308*27162e4eSAndroid Build Coastguard Worker in which case any existing dictionary stream is unset. 309*27162e4eSAndroid Build Coastguard Worker 310*27162e4eSAndroid Build Coastguard Worker If a dictionary is provided, it replaces any pre-existing stream history. 311*27162e4eSAndroid Build Coastguard Worker The dictionary contents are the only history that can be referenced and 312*27162e4eSAndroid Build Coastguard Worker logically immediately precede the data compressed in the first subsequent 313*27162e4eSAndroid Build Coastguard Worker compression call. 314*27162e4eSAndroid Build Coastguard Worker 315*27162e4eSAndroid Build Coastguard Worker The dictionary will only remain attached to the working stream through the 316*27162e4eSAndroid Build Coastguard Worker first compression call, at the end of which it is cleared. 317*27162e4eSAndroid Build Coastguard Worker @dictionaryStream stream (and source buffer) must remain in-place / accessible / unchanged 318*27162e4eSAndroid Build Coastguard Worker through the completion of the compression session. 319*27162e4eSAndroid Build Coastguard Worker 320*27162e4eSAndroid Build Coastguard Worker Note: there is no equivalent LZ4_attach_*() method on the decompression side 321*27162e4eSAndroid Build Coastguard Worker because there is no initialization cost, hence no need to share the cost across multiple sessions. 322*27162e4eSAndroid Build Coastguard Worker To decompress LZ4 blocks using dictionary, attached or not, 323*27162e4eSAndroid Build Coastguard Worker just employ the regular LZ4_setStreamDecode() for streaming, 324*27162e4eSAndroid Build Coastguard Worker or the stateless LZ4_decompress_safe_usingDict() for one-shot decompression. 325*27162e4eSAndroid Build Coastguard Worker 326*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 327*27162e4eSAndroid Build Coastguard Worker 328*27162e4eSAndroid Build Coastguard Worker<pre><b>int LZ4_compress_fast_continue (LZ4_stream_t* streamPtr, const char* src, char* dst, int srcSize, int dstCapacity, int acceleration); 329*27162e4eSAndroid Build Coastguard Worker</b><p> Compress 'src' content using data from previously compressed blocks, for better compression ratio. 330*27162e4eSAndroid Build Coastguard Worker 'dst' buffer must be already allocated. 331*27162e4eSAndroid Build Coastguard Worker If dstCapacity >= LZ4_compressBound(srcSize), compression is guaranteed to succeed, and runs faster. 332*27162e4eSAndroid Build Coastguard Worker 333*27162e4eSAndroid Build Coastguard Worker @return : size of compressed block 334*27162e4eSAndroid Build Coastguard Worker or 0 if there is an error (typically, cannot fit into 'dst'). 335*27162e4eSAndroid Build Coastguard Worker 336*27162e4eSAndroid Build Coastguard Worker Note 1 : Each invocation to LZ4_compress_fast_continue() generates a new block. 337*27162e4eSAndroid Build Coastguard Worker Each block has precise boundaries. 338*27162e4eSAndroid Build Coastguard Worker Each block must be decompressed separately, calling LZ4_decompress_*() with relevant metadata. 339*27162e4eSAndroid Build Coastguard Worker It's not possible to append blocks together and expect a single invocation of LZ4_decompress_*() to decompress them together. 340*27162e4eSAndroid Build Coastguard Worker 341*27162e4eSAndroid Build Coastguard Worker Note 2 : The previous 64KB of source data is __assumed__ to remain present, unmodified, at same address in memory ! 342*27162e4eSAndroid Build Coastguard Worker 343*27162e4eSAndroid Build Coastguard Worker Note 3 : When input is structured as a double-buffer, each buffer can have any size, including < 64 KB. 344*27162e4eSAndroid Build Coastguard Worker Make sure that buffers are separated, by at least one byte. 345*27162e4eSAndroid Build Coastguard Worker This construction ensures that each block only depends on previous block. 346*27162e4eSAndroid Build Coastguard Worker 347*27162e4eSAndroid Build Coastguard Worker Note 4 : If input buffer is a ring-buffer, it can have any size, including < 64 KB. 348*27162e4eSAndroid Build Coastguard Worker 349*27162e4eSAndroid Build Coastguard Worker Note 5 : After an error, the stream status is undefined (invalid), it can only be reset or freed. 350*27162e4eSAndroid Build Coastguard Worker 351*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 352*27162e4eSAndroid Build Coastguard Worker 353*27162e4eSAndroid Build Coastguard Worker<pre><b>int LZ4_saveDict (LZ4_stream_t* streamPtr, char* safeBuffer, int maxDictSize); 354*27162e4eSAndroid Build Coastguard Worker</b><p> If last 64KB data cannot be guaranteed to remain available at its current memory location, 355*27162e4eSAndroid Build Coastguard Worker save it into a safer place (char* safeBuffer). 356*27162e4eSAndroid Build Coastguard Worker This is schematically equivalent to a memcpy() followed by LZ4_loadDict(), 357*27162e4eSAndroid Build Coastguard Worker but is much faster, because LZ4_saveDict() doesn't need to rebuild tables. 358*27162e4eSAndroid Build Coastguard Worker @return : saved dictionary size in bytes (necessarily <= maxDictSize), or 0 if error. 359*27162e4eSAndroid Build Coastguard Worker 360*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 361*27162e4eSAndroid Build Coastguard Worker 362*27162e4eSAndroid Build Coastguard Worker<a name="Chapter7"></a><h2>Streaming Decompression Functions</h2><pre> Bufferless synchronous API 363*27162e4eSAndroid Build Coastguard Worker<BR></pre> 364*27162e4eSAndroid Build Coastguard Worker 365*27162e4eSAndroid Build Coastguard Worker<pre><b>#if !defined(RC_INVOKED) </b>/* https://docs.microsoft.com/en-us/windows/win32/menurc/predefined-macros */<b> 366*27162e4eSAndroid Build Coastguard Worker#if !defined(LZ4_STATIC_LINKING_ONLY_DISABLE_MEMORY_ALLOCATION) 367*27162e4eSAndroid Build Coastguard WorkerLZ4_streamDecode_t* LZ4_createStreamDecode(void); 368*27162e4eSAndroid Build Coastguard Workerint LZ4_freeStreamDecode (LZ4_streamDecode_t* LZ4_stream); 369*27162e4eSAndroid Build Coastguard Worker#endif </b>/* !defined(LZ4_STATIC_LINKING_ONLY_DISABLE_MEMORY_ALLOCATION) */<b> 370*27162e4eSAndroid Build Coastguard Worker#endif 371*27162e4eSAndroid Build Coastguard Worker</b><p> creation / destruction of streaming decompression tracking context. 372*27162e4eSAndroid Build Coastguard Worker A tracking context can be re-used multiple times. 373*27162e4eSAndroid Build Coastguard Worker 374*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 375*27162e4eSAndroid Build Coastguard Worker 376*27162e4eSAndroid Build Coastguard Worker<pre><b>int LZ4_setStreamDecode (LZ4_streamDecode_t* LZ4_streamDecode, const char* dictionary, int dictSize); 377*27162e4eSAndroid Build Coastguard Worker</b><p> An LZ4_streamDecode_t context can be allocated once and re-used multiple times. 378*27162e4eSAndroid Build Coastguard Worker Use this function to start decompression of a new stream of blocks. 379*27162e4eSAndroid Build Coastguard Worker A dictionary can optionally be set. Use NULL or size 0 for a reset order. 380*27162e4eSAndroid Build Coastguard Worker Dictionary is presumed stable : it must remain accessible and unmodified during next decompression. 381*27162e4eSAndroid Build Coastguard Worker @return : 1 if OK, 0 if error 382*27162e4eSAndroid Build Coastguard Worker 383*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 384*27162e4eSAndroid Build Coastguard Worker 385*27162e4eSAndroid Build Coastguard Worker<pre><b>int LZ4_decoderRingBufferSize(int maxBlockSize); 386*27162e4eSAndroid Build Coastguard Worker#define LZ4_DECODER_RING_BUFFER_SIZE(maxBlockSize) (65536 + 14 + (maxBlockSize)) </b>/* for static allocation; maxBlockSize presumed valid */<b> 387*27162e4eSAndroid Build Coastguard Worker</b><p> Note : in a ring buffer scenario (optional), 388*27162e4eSAndroid Build Coastguard Worker blocks are presumed decompressed next to each other 389*27162e4eSAndroid Build Coastguard Worker up to the moment there is not enough remaining space for next block (remainingSize < maxBlockSize), 390*27162e4eSAndroid Build Coastguard Worker at which stage it resumes from beginning of ring buffer. 391*27162e4eSAndroid Build Coastguard Worker When setting such a ring buffer for streaming decompression, 392*27162e4eSAndroid Build Coastguard Worker provides the minimum size of this ring buffer 393*27162e4eSAndroid Build Coastguard Worker to be compatible with any source respecting maxBlockSize condition. 394*27162e4eSAndroid Build Coastguard Worker @return : minimum ring buffer size, 395*27162e4eSAndroid Build Coastguard Worker or 0 if there is an error (invalid maxBlockSize). 396*27162e4eSAndroid Build Coastguard Worker 397*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 398*27162e4eSAndroid Build Coastguard Worker 399*27162e4eSAndroid Build Coastguard Worker<pre><b>int 400*27162e4eSAndroid Build Coastguard WorkerLZ4_decompress_safe_continue (LZ4_streamDecode_t* LZ4_streamDecode, 401*27162e4eSAndroid Build Coastguard Worker const char* src, char* dst, 402*27162e4eSAndroid Build Coastguard Worker int srcSize, int dstCapacity); 403*27162e4eSAndroid Build Coastguard Worker</b><p> This decoding function allows decompression of consecutive blocks in "streaming" mode. 404*27162e4eSAndroid Build Coastguard Worker The difference with the usual independent blocks is that 405*27162e4eSAndroid Build Coastguard Worker new blocks are allowed to find references into former blocks. 406*27162e4eSAndroid Build Coastguard Worker A block is an unsplittable entity, and must be presented entirely to the decompression function. 407*27162e4eSAndroid Build Coastguard Worker LZ4_decompress_safe_continue() only accepts one block at a time. 408*27162e4eSAndroid Build Coastguard Worker It's modeled after `LZ4_decompress_safe()` and behaves similarly. 409*27162e4eSAndroid Build Coastguard Worker 410*27162e4eSAndroid Build Coastguard Worker @LZ4_streamDecode : decompression state, tracking the position in memory of past data 411*27162e4eSAndroid Build Coastguard Worker @compressedSize : exact complete size of one compressed block. 412*27162e4eSAndroid Build Coastguard Worker @dstCapacity : size of destination buffer (which must be already allocated), 413*27162e4eSAndroid Build Coastguard Worker must be an upper bound of decompressed size. 414*27162e4eSAndroid Build Coastguard Worker @return : number of bytes decompressed into destination buffer (necessarily <= dstCapacity) 415*27162e4eSAndroid Build Coastguard Worker If destination buffer is not large enough, decoding will stop and output an error code (negative value). 416*27162e4eSAndroid Build Coastguard Worker If the source stream is detected malformed, the function will stop decoding and return a negative result. 417*27162e4eSAndroid Build Coastguard Worker 418*27162e4eSAndroid Build Coastguard Worker The last 64KB of previously decoded data *must* remain available and unmodified 419*27162e4eSAndroid Build Coastguard Worker at the memory position where they were previously decoded. 420*27162e4eSAndroid Build Coastguard Worker If less than 64KB of data has been decoded, all the data must be present. 421*27162e4eSAndroid Build Coastguard Worker 422*27162e4eSAndroid Build Coastguard Worker Special : if decompression side sets a ring buffer, it must respect one of the following conditions : 423*27162e4eSAndroid Build Coastguard Worker - Decompression buffer size is _at least_ LZ4_decoderRingBufferSize(maxBlockSize). 424*27162e4eSAndroid Build Coastguard Worker maxBlockSize is the maximum size of any single block. It can have any value > 16 bytes. 425*27162e4eSAndroid Build Coastguard Worker In which case, encoding and decoding buffers do not need to be synchronized. 426*27162e4eSAndroid Build Coastguard Worker Actually, data can be produced by any source compliant with LZ4 format specification, and respecting maxBlockSize. 427*27162e4eSAndroid Build Coastguard Worker - Synchronized mode : 428*27162e4eSAndroid Build Coastguard Worker Decompression buffer size is _exactly_ the same as compression buffer size, 429*27162e4eSAndroid Build Coastguard Worker and follows exactly same update rule (block boundaries at same positions), 430*27162e4eSAndroid Build Coastguard Worker and decoding function is provided with exact decompressed size of each block (exception for last block of the stream), 431*27162e4eSAndroid Build Coastguard Worker _then_ decoding & encoding ring buffer can have any size, including small ones ( < 64 KB). 432*27162e4eSAndroid Build Coastguard Worker - Decompression buffer is larger than encoding buffer, by a minimum of maxBlockSize more bytes. 433*27162e4eSAndroid Build Coastguard Worker In which case, encoding and decoding buffers do not need to be synchronized, 434*27162e4eSAndroid Build Coastguard Worker and encoding ring buffer can have any size, including small ones ( < 64 KB). 435*27162e4eSAndroid Build Coastguard Worker 436*27162e4eSAndroid Build Coastguard Worker Whenever these conditions are not possible, 437*27162e4eSAndroid Build Coastguard Worker save the last 64KB of decoded data into a safe buffer where it can't be modified during decompression, 438*27162e4eSAndroid Build Coastguard Worker then indicate where this data is saved using LZ4_setStreamDecode(), before decompressing next block. 439*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 440*27162e4eSAndroid Build Coastguard Worker 441*27162e4eSAndroid Build Coastguard Worker<pre><b>int 442*27162e4eSAndroid Build Coastguard WorkerLZ4_decompress_safe_usingDict(const char* src, char* dst, 443*27162e4eSAndroid Build Coastguard Worker int srcSize, int dstCapacity, 444*27162e4eSAndroid Build Coastguard Worker const char* dictStart, int dictSize); 445*27162e4eSAndroid Build Coastguard Worker</b><p> Works the same as 446*27162e4eSAndroid Build Coastguard Worker a combination of LZ4_setStreamDecode() followed by LZ4_decompress_safe_continue() 447*27162e4eSAndroid Build Coastguard Worker However, it's stateless: it doesn't need any LZ4_streamDecode_t state. 448*27162e4eSAndroid Build Coastguard Worker Dictionary is presumed stable : it must remain accessible and unmodified during decompression. 449*27162e4eSAndroid Build Coastguard Worker Performance tip : Decompression speed can be substantially increased 450*27162e4eSAndroid Build Coastguard Worker when dst == dictStart + dictSize. 451*27162e4eSAndroid Build Coastguard Worker 452*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 453*27162e4eSAndroid Build Coastguard Worker 454*27162e4eSAndroid Build Coastguard Worker<pre><b>int 455*27162e4eSAndroid Build Coastguard WorkerLZ4_decompress_safe_partial_usingDict(const char* src, char* dst, 456*27162e4eSAndroid Build Coastguard Worker int compressedSize, 457*27162e4eSAndroid Build Coastguard Worker int targetOutputSize, int maxOutputSize, 458*27162e4eSAndroid Build Coastguard Worker const char* dictStart, int dictSize); 459*27162e4eSAndroid Build Coastguard Worker</b><p> Behaves the same as LZ4_decompress_safe_partial() 460*27162e4eSAndroid Build Coastguard Worker with the added ability to specify a memory segment for past data. 461*27162e4eSAndroid Build Coastguard Worker Performance tip : Decompression speed can be substantially increased 462*27162e4eSAndroid Build Coastguard Worker when dst == dictStart + dictSize. 463*27162e4eSAndroid Build Coastguard Worker 464*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 465*27162e4eSAndroid Build Coastguard Worker 466*27162e4eSAndroid Build Coastguard Worker<a name="Chapter8"></a><h2>Experimental section</h2><pre> 467*27162e4eSAndroid Build Coastguard Worker Symbols declared in this section must be considered unstable. Their 468*27162e4eSAndroid Build Coastguard Worker signatures or semantics may change, or they may be removed altogether in the 469*27162e4eSAndroid Build Coastguard Worker future. They are therefore only safe to depend on when the caller is 470*27162e4eSAndroid Build Coastguard Worker statically linked against the library. 471*27162e4eSAndroid Build Coastguard Worker 472*27162e4eSAndroid Build Coastguard Worker To protect against unsafe usage, not only are the declarations guarded, 473*27162e4eSAndroid Build Coastguard Worker the definitions are hidden by default 474*27162e4eSAndroid Build Coastguard Worker when building LZ4 as a shared/dynamic library. 475*27162e4eSAndroid Build Coastguard Worker 476*27162e4eSAndroid Build Coastguard Worker In order to access these declarations, 477*27162e4eSAndroid Build Coastguard Worker define LZ4_STATIC_LINKING_ONLY in your application 478*27162e4eSAndroid Build Coastguard Worker before including LZ4's headers. 479*27162e4eSAndroid Build Coastguard Worker 480*27162e4eSAndroid Build Coastguard Worker In order to make their implementations accessible dynamically, you must 481*27162e4eSAndroid Build Coastguard Worker define LZ4_PUBLISH_STATIC_FUNCTIONS when building the LZ4 library. 482*27162e4eSAndroid Build Coastguard Worker<BR></pre> 483*27162e4eSAndroid Build Coastguard Worker 484*27162e4eSAndroid Build Coastguard Worker<pre><b>LZ4LIB_STATIC_API int LZ4_compress_fast_extState_fastReset (void* state, const char* src, char* dst, int srcSize, int dstCapacity, int acceleration); 485*27162e4eSAndroid Build Coastguard Worker</b><p> A variant of LZ4_compress_fast_extState(). 486*27162e4eSAndroid Build Coastguard Worker 487*27162e4eSAndroid Build Coastguard Worker Using this variant avoids an expensive initialization step. 488*27162e4eSAndroid Build Coastguard Worker It is only safe to call if the state buffer is known to be correctly initialized already 489*27162e4eSAndroid Build Coastguard Worker (see above comment on LZ4_resetStream_fast() for a definition of "correctly initialized"). 490*27162e4eSAndroid Build Coastguard Worker From a high level, the difference is that 491*27162e4eSAndroid Build Coastguard Worker this function initializes the provided state with a call to something like LZ4_resetStream_fast() 492*27162e4eSAndroid Build Coastguard Worker while LZ4_compress_fast_extState() starts with a call to LZ4_resetStream(). 493*27162e4eSAndroid Build Coastguard Worker 494*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 495*27162e4eSAndroid Build Coastguard Worker 496*27162e4eSAndroid Build Coastguard Worker<pre><b>int LZ4_compress_destSize_extState(void* state, const char* src, char* dst, int* srcSizePtr, int targetDstSize, int acceleration); 497*27162e4eSAndroid Build Coastguard Worker</b><p> Same as LZ4_compress_destSize(), but using an externally allocated state. 498*27162e4eSAndroid Build Coastguard Worker Also: exposes @acceleration 499*27162e4eSAndroid Build Coastguard Worker 500*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 501*27162e4eSAndroid Build Coastguard Worker 502*27162e4eSAndroid Build Coastguard Worker<pre><b></b><p> 503*27162e4eSAndroid Build Coastguard Worker It's possible to have input and output sharing the same buffer, 504*27162e4eSAndroid Build Coastguard Worker for highly constrained memory environments. 505*27162e4eSAndroid Build Coastguard Worker In both cases, it requires input to lay at the end of the buffer, 506*27162e4eSAndroid Build Coastguard Worker and decompression to start at beginning of the buffer. 507*27162e4eSAndroid Build Coastguard Worker Buffer size must feature some margin, hence be larger than final size. 508*27162e4eSAndroid Build Coastguard Worker 509*27162e4eSAndroid Build Coastguard Worker |<------------------------buffer--------------------------------->| 510*27162e4eSAndroid Build Coastguard Worker |<-----------compressed data--------->| 511*27162e4eSAndroid Build Coastguard Worker |<-----------decompressed size------------------>| 512*27162e4eSAndroid Build Coastguard Worker |<----margin---->| 513*27162e4eSAndroid Build Coastguard Worker 514*27162e4eSAndroid Build Coastguard Worker This technique is more useful for decompression, 515*27162e4eSAndroid Build Coastguard Worker since decompressed size is typically larger, 516*27162e4eSAndroid Build Coastguard Worker and margin is short. 517*27162e4eSAndroid Build Coastguard Worker 518*27162e4eSAndroid Build Coastguard Worker In-place decompression will work inside any buffer 519*27162e4eSAndroid Build Coastguard Worker which size is >= LZ4_DECOMPRESS_INPLACE_BUFFER_SIZE(decompressedSize). 520*27162e4eSAndroid Build Coastguard Worker This presumes that decompressedSize > compressedSize. 521*27162e4eSAndroid Build Coastguard Worker Otherwise, it means compression actually expanded data, 522*27162e4eSAndroid Build Coastguard Worker and it would be more efficient to store such data with a flag indicating it's not compressed. 523*27162e4eSAndroid Build Coastguard Worker This can happen when data is not compressible (already compressed, or encrypted). 524*27162e4eSAndroid Build Coastguard Worker 525*27162e4eSAndroid Build Coastguard Worker For in-place compression, margin is larger, as it must be able to cope with both 526*27162e4eSAndroid Build Coastguard Worker history preservation, requiring input data to remain unmodified up to LZ4_DISTANCE_MAX, 527*27162e4eSAndroid Build Coastguard Worker and data expansion, which can happen when input is not compressible. 528*27162e4eSAndroid Build Coastguard Worker As a consequence, buffer size requirements are much higher, 529*27162e4eSAndroid Build Coastguard Worker and memory savings offered by in-place compression are more limited. 530*27162e4eSAndroid Build Coastguard Worker 531*27162e4eSAndroid Build Coastguard Worker There are ways to limit this cost for compression : 532*27162e4eSAndroid Build Coastguard Worker - Reduce history size, by modifying LZ4_DISTANCE_MAX. 533*27162e4eSAndroid Build Coastguard Worker Note that it is a compile-time constant, so all compressions will apply this limit. 534*27162e4eSAndroid Build Coastguard Worker Lower values will reduce compression ratio, except when input_size < LZ4_DISTANCE_MAX, 535*27162e4eSAndroid Build Coastguard Worker so it's a reasonable trick when inputs are known to be small. 536*27162e4eSAndroid Build Coastguard Worker - Require the compressor to deliver a "maximum compressed size". 537*27162e4eSAndroid Build Coastguard Worker This is the `dstCapacity` parameter in `LZ4_compress*()`. 538*27162e4eSAndroid Build Coastguard Worker When this size is < LZ4_COMPRESSBOUND(inputSize), then compression can fail, 539*27162e4eSAndroid Build Coastguard Worker in which case, the return code will be 0 (zero). 540*27162e4eSAndroid Build Coastguard Worker The caller must be ready for these cases to happen, 541*27162e4eSAndroid Build Coastguard Worker and typically design a backup scheme to send data uncompressed. 542*27162e4eSAndroid Build Coastguard Worker The combination of both techniques can significantly reduce 543*27162e4eSAndroid Build Coastguard Worker the amount of margin required for in-place compression. 544*27162e4eSAndroid Build Coastguard Worker 545*27162e4eSAndroid Build Coastguard Worker In-place compression can work in any buffer 546*27162e4eSAndroid Build Coastguard Worker which size is >= (maxCompressedSize) 547*27162e4eSAndroid Build Coastguard Worker with maxCompressedSize == LZ4_COMPRESSBOUND(srcSize) for guaranteed compression success. 548*27162e4eSAndroid Build Coastguard Worker LZ4_COMPRESS_INPLACE_BUFFER_SIZE() depends on both maxCompressedSize and LZ4_DISTANCE_MAX, 549*27162e4eSAndroid Build Coastguard Worker so it's possible to reduce memory requirements by playing with them. 550*27162e4eSAndroid Build Coastguard Worker 551*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 552*27162e4eSAndroid Build Coastguard Worker 553*27162e4eSAndroid Build Coastguard Worker<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> 554*27162e4eSAndroid Build Coastguard Worker</b></pre><BR> 555*27162e4eSAndroid Build Coastguard Worker<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> 556*27162e4eSAndroid Build Coastguard Worker</b></pre><BR> 557*27162e4eSAndroid Build Coastguard Worker<a name="Chapter9"></a><h2>Private Definitions</h2><pre> 558*27162e4eSAndroid Build Coastguard Worker Do not use these definitions directly. 559*27162e4eSAndroid Build Coastguard Worker They are only exposed to allow static allocation of `LZ4_stream_t` and `LZ4_streamDecode_t`. 560*27162e4eSAndroid Build Coastguard Worker Accessing members will expose user code to API and/or ABI break in future versions of the library. 561*27162e4eSAndroid Build Coastguard Worker<BR></pre> 562*27162e4eSAndroid Build Coastguard Worker 563*27162e4eSAndroid Build Coastguard Worker<pre><b></b><p> Never ever use below internal definitions directly ! 564*27162e4eSAndroid Build Coastguard Worker These definitions are not API/ABI safe, and may change in future versions. 565*27162e4eSAndroid Build Coastguard Worker If you need static allocation, declare or allocate an LZ4_stream_t object. 566*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 567*27162e4eSAndroid Build Coastguard Worker 568*27162e4eSAndroid Build Coastguard Worker<pre><b>LZ4_stream_t* LZ4_initStream (void* stateBuffer, size_t size); 569*27162e4eSAndroid Build Coastguard Worker</b><p> An LZ4_stream_t structure must be initialized at least once. 570*27162e4eSAndroid Build Coastguard Worker This is automatically done when invoking LZ4_createStream(), 571*27162e4eSAndroid Build Coastguard Worker but it's not when the structure is simply declared on stack (for example). 572*27162e4eSAndroid Build Coastguard Worker 573*27162e4eSAndroid Build Coastguard Worker Use LZ4_initStream() to properly initialize a newly declared LZ4_stream_t. 574*27162e4eSAndroid Build Coastguard Worker It can also initialize any arbitrary buffer of sufficient size, 575*27162e4eSAndroid Build Coastguard Worker and will @return a pointer of proper type upon initialization. 576*27162e4eSAndroid Build Coastguard Worker 577*27162e4eSAndroid Build Coastguard Worker Note : initialization fails if size and alignment conditions are not respected. 578*27162e4eSAndroid Build Coastguard Worker In which case, the function will @return NULL. 579*27162e4eSAndroid Build Coastguard Worker Note2: An LZ4_stream_t structure guarantees correct alignment and size. 580*27162e4eSAndroid Build Coastguard Worker Note3: Before v1.9.0, use LZ4_resetStream() instead 581*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 582*27162e4eSAndroid Build Coastguard Worker 583*27162e4eSAndroid Build Coastguard Worker<pre><b>typedef struct { 584*27162e4eSAndroid Build Coastguard Worker const LZ4_byte* externalDict; 585*27162e4eSAndroid Build Coastguard Worker const LZ4_byte* prefixEnd; 586*27162e4eSAndroid Build Coastguard Worker size_t extDictSize; 587*27162e4eSAndroid Build Coastguard Worker size_t prefixSize; 588*27162e4eSAndroid Build Coastguard Worker} LZ4_streamDecode_t_internal; 589*27162e4eSAndroid Build Coastguard Worker</b><p> Never ever use below internal definitions directly ! 590*27162e4eSAndroid Build Coastguard Worker These definitions are not API/ABI safe, and may change in future versions. 591*27162e4eSAndroid Build Coastguard Worker If you need static allocation, declare or allocate an LZ4_streamDecode_t object. 592*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 593*27162e4eSAndroid Build Coastguard Worker 594*27162e4eSAndroid Build Coastguard Worker<a name="Chapter10"></a><h2>Obsolete Functions</h2><pre></pre> 595*27162e4eSAndroid Build Coastguard Worker 596*27162e4eSAndroid Build Coastguard Worker<pre><b>#ifdef LZ4_DISABLE_DEPRECATE_WARNINGS 597*27162e4eSAndroid Build Coastguard Worker# define LZ4_DEPRECATED(message) </b>/* disable deprecation warnings */<b> 598*27162e4eSAndroid Build Coastguard Worker#else 599*27162e4eSAndroid Build Coastguard Worker# if defined (__cplusplus) && (__cplusplus >= 201402) </b>/* C++14 or greater */<b> 600*27162e4eSAndroid Build Coastguard Worker# define LZ4_DEPRECATED(message) [[deprecated(message)]] 601*27162e4eSAndroid Build Coastguard Worker# elif defined(_MSC_VER) 602*27162e4eSAndroid Build Coastguard Worker# define LZ4_DEPRECATED(message) __declspec(deprecated(message)) 603*27162e4eSAndroid Build Coastguard Worker# elif defined(__clang__) || (defined(__GNUC__) && (__GNUC__ * 10 + __GNUC_MINOR__ >= 45)) 604*27162e4eSAndroid Build Coastguard Worker# define LZ4_DEPRECATED(message) __attribute__((deprecated(message))) 605*27162e4eSAndroid Build Coastguard Worker# elif defined(__GNUC__) && (__GNUC__ * 10 + __GNUC_MINOR__ >= 31) 606*27162e4eSAndroid Build Coastguard Worker# define LZ4_DEPRECATED(message) __attribute__((deprecated)) 607*27162e4eSAndroid Build Coastguard Worker# else 608*27162e4eSAndroid Build Coastguard Worker# pragma message("WARNING: LZ4_DEPRECATED needs custom implementation for this compiler") 609*27162e4eSAndroid Build Coastguard Worker# define LZ4_DEPRECATED(message) </b>/* disabled */<b> 610*27162e4eSAndroid Build Coastguard Worker# endif 611*27162e4eSAndroid Build Coastguard Worker#endif </b>/* LZ4_DISABLE_DEPRECATE_WARNINGS */<b> 612*27162e4eSAndroid Build Coastguard Worker</b><p> 613*27162e4eSAndroid Build Coastguard Worker Deprecated functions make the compiler generate a warning when invoked. 614*27162e4eSAndroid Build Coastguard Worker This is meant to invite users to update their source code. 615*27162e4eSAndroid Build Coastguard Worker Should deprecation warnings be a problem, it is generally possible to disable them, 616*27162e4eSAndroid Build Coastguard Worker typically with -Wno-deprecated-declarations for gcc 617*27162e4eSAndroid Build Coastguard Worker or _CRT_SECURE_NO_WARNINGS in Visual. 618*27162e4eSAndroid Build Coastguard Worker 619*27162e4eSAndroid Build Coastguard Worker Another method is to define LZ4_DISABLE_DEPRECATE_WARNINGS 620*27162e4eSAndroid Build Coastguard Worker before including the header file. 621*27162e4eSAndroid Build Coastguard Worker 622*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 623*27162e4eSAndroid Build Coastguard Worker 624*27162e4eSAndroid Build Coastguard Worker<pre><b>LZ4_DEPRECATED("use LZ4_compress_default() instead") LZ4LIB_API int LZ4_compress (const char* src, char* dest, int srcSize); 625*27162e4eSAndroid Build Coastguard WorkerLZ4_DEPRECATED("use LZ4_compress_default() instead") LZ4LIB_API int LZ4_compress_limitedOutput (const char* src, char* dest, int srcSize, int maxOutputSize); 626*27162e4eSAndroid Build Coastguard WorkerLZ4_DEPRECATED("use LZ4_compress_fast_extState() instead") LZ4LIB_API int LZ4_compress_withState (void* state, const char* source, char* dest, int inputSize); 627*27162e4eSAndroid Build Coastguard WorkerLZ4_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); 628*27162e4eSAndroid Build Coastguard WorkerLZ4_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); 629*27162e4eSAndroid Build Coastguard WorkerLZ4_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); 630*27162e4eSAndroid Build Coastguard Worker</b><p></p></pre><BR> 631*27162e4eSAndroid Build Coastguard Worker 632*27162e4eSAndroid Build Coastguard Worker<pre><b>LZ4_DEPRECATED("use LZ4_decompress_fast() instead") LZ4LIB_API int LZ4_uncompress (const char* source, char* dest, int outputSize); 633*27162e4eSAndroid Build Coastguard WorkerLZ4_DEPRECATED("use LZ4_decompress_safe() instead") LZ4LIB_API int LZ4_uncompress_unknownOutputSize (const char* source, char* dest, int isize, int maxOutputSize); 634*27162e4eSAndroid Build Coastguard Worker</b><p></p></pre><BR> 635*27162e4eSAndroid Build Coastguard Worker 636*27162e4eSAndroid Build Coastguard Worker<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); 637*27162e4eSAndroid Build Coastguard WorkerLZ4_DEPRECATED("use LZ4_decompress_fast_usingDict() instead") LZ4LIB_API int LZ4_decompress_fast_withPrefix64k (const char* src, char* dst, int originalSize); 638*27162e4eSAndroid Build Coastguard Worker</b><p></p></pre><BR> 639*27162e4eSAndroid Build Coastguard Worker 640*27162e4eSAndroid Build Coastguard Worker<pre><b>LZ4_DEPRECATED("This function is deprecated and unsafe. Consider using LZ4_decompress_safe_partial() instead") 641*27162e4eSAndroid Build Coastguard Workerint LZ4_decompress_fast (const char* src, char* dst, int originalSize); 642*27162e4eSAndroid Build Coastguard WorkerLZ4_DEPRECATED("This function is deprecated and unsafe. Consider migrating towards LZ4_decompress_safe_continue() instead. " 643*27162e4eSAndroid Build Coastguard Worker "Note that the contract will change (requires block's compressed size, instead of decompressed size)") 644*27162e4eSAndroid Build Coastguard Workerint LZ4_decompress_fast_continue (LZ4_streamDecode_t* LZ4_streamDecode, const char* src, char* dst, int originalSize); 645*27162e4eSAndroid Build Coastguard WorkerLZ4_DEPRECATED("This function is deprecated and unsafe. Consider using LZ4_decompress_safe_partial_usingDict() instead") 646*27162e4eSAndroid Build Coastguard Workerint LZ4_decompress_fast_usingDict (const char* src, char* dst, int originalSize, const char* dictStart, int dictSize); 647*27162e4eSAndroid Build Coastguard Worker</b><p> These functions used to be faster than LZ4_decompress_safe(), 648*27162e4eSAndroid Build Coastguard Worker but this is no longer the case. They are now slower. 649*27162e4eSAndroid Build Coastguard Worker This is because LZ4_decompress_fast() doesn't know the input size, 650*27162e4eSAndroid Build Coastguard Worker and therefore must progress more cautiously into the input buffer to not read beyond the end of block. 651*27162e4eSAndroid Build Coastguard Worker On top of that `LZ4_decompress_fast()` is not protected vs malformed or malicious inputs, making it a security liability. 652*27162e4eSAndroid Build Coastguard Worker As a consequence, LZ4_decompress_fast() is strongly discouraged, and deprecated. 653*27162e4eSAndroid Build Coastguard Worker 654*27162e4eSAndroid Build Coastguard Worker The last remaining LZ4_decompress_fast() specificity is that 655*27162e4eSAndroid Build Coastguard Worker it can decompress a block without knowing its compressed size. 656*27162e4eSAndroid Build Coastguard Worker Such functionality can be achieved in a more secure manner 657*27162e4eSAndroid Build Coastguard Worker by employing LZ4_decompress_safe_partial(). 658*27162e4eSAndroid Build Coastguard Worker 659*27162e4eSAndroid Build Coastguard Worker Parameters: 660*27162e4eSAndroid Build Coastguard Worker originalSize : is the uncompressed size to regenerate. 661*27162e4eSAndroid Build Coastguard Worker `dst` must be already allocated, its size must be >= 'originalSize' bytes. 662*27162e4eSAndroid Build Coastguard Worker @return : number of bytes read from source buffer (== compressed size). 663*27162e4eSAndroid Build Coastguard Worker The function expects to finish at block's end exactly. 664*27162e4eSAndroid Build Coastguard Worker If the source stream is detected malformed, the function stops decoding and returns a negative result. 665*27162e4eSAndroid Build Coastguard Worker note : LZ4_decompress_fast*() requires originalSize. Thanks to this information, it never writes past the output buffer. 666*27162e4eSAndroid Build Coastguard Worker However, since it doesn't know its 'src' size, it may read an unknown amount of input, past input buffer bounds. 667*27162e4eSAndroid Build Coastguard Worker Also, since match offsets are not validated, match reads from 'src' may underflow too. 668*27162e4eSAndroid Build Coastguard Worker These issues never happen if input (compressed) data is correct. 669*27162e4eSAndroid Build Coastguard Worker But they may happen if input data is invalid (error or intentional tampering). 670*27162e4eSAndroid Build Coastguard Worker As a consequence, use these functions in trusted environments with trusted data **only**. 671*27162e4eSAndroid Build Coastguard Worker 672*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 673*27162e4eSAndroid Build Coastguard Worker 674*27162e4eSAndroid Build Coastguard Worker<pre><b>void LZ4_resetStream (LZ4_stream_t* streamPtr); 675*27162e4eSAndroid Build Coastguard Worker</b><p> An LZ4_stream_t structure must be initialized at least once. 676*27162e4eSAndroid Build Coastguard Worker This is done with LZ4_initStream(), or LZ4_resetStream(). 677*27162e4eSAndroid Build Coastguard Worker Consider switching to LZ4_initStream(), 678*27162e4eSAndroid Build Coastguard Worker invoking LZ4_resetStream() will trigger deprecation warnings in the future. 679*27162e4eSAndroid Build Coastguard Worker 680*27162e4eSAndroid Build Coastguard Worker</p></pre><BR> 681*27162e4eSAndroid Build Coastguard Worker 682*27162e4eSAndroid Build Coastguard Worker</html> 683*27162e4eSAndroid Build Coastguard Worker</body> 684