1 | /* |
2 | * LZ4 - Fast LZ compression algorithm |
3 | * Header File |
4 | * Copyright (C) 2011-present, Yann Collet. |
5 | |
6 | BSD 2-Clause License (http://www.opensource.org/licenses/bsd-license.php) |
7 | |
8 | Redistribution and use in source and binary forms, with or without |
9 | modification, are permitted provided that the following conditions are |
10 | met: |
11 | |
12 | * Redistributions of source code must retain the above copyright |
13 | notice, this list of conditions and the following disclaimer. |
14 | * Redistributions in binary form must reproduce the above |
15 | copyright notice, this list of conditions and the following disclaimer |
16 | in the documentation and/or other materials provided with the |
17 | distribution. |
18 | |
19 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
20 | "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
21 | LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
22 | A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT |
23 | OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
24 | SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
25 | LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
26 | DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
27 | THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
28 | (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |
29 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
30 | |
31 | You can contact the author at : |
32 | - LZ4 homepage : http://www.lz4.org |
33 | - LZ4 source repository : https://github.com/lz4/lz4 |
34 | */ |
35 | #if defined (__cplusplus) |
36 | extern "C" { |
37 | #endif |
38 | |
39 | #ifndef LZ4_H_2983827168210 |
40 | #define LZ4_H_2983827168210 |
41 | |
42 | /* --- Dependency --- */ |
43 | #include <stddef.h> /* size_t */ |
44 | |
45 | |
46 | /** |
47 | Introduction |
48 | |
49 | LZ4 is lossless compression algorithm, providing compression speed >500 MB/s per core, |
50 | scalable with multi-cores CPU. It features an extremely fast decoder, with speed in |
51 | multiple GB/s per core, typically reaching RAM speed limits on multi-core systems. |
52 | |
53 | The LZ4 compression library provides in-memory compression and decompression functions. |
54 | It gives full buffer control to user. |
55 | Compression can be done in: |
56 | - a single step (described as Simple Functions) |
57 | - a single step, reusing a context (described in Advanced Functions) |
58 | - unbounded multiple steps (described as Streaming compression) |
59 | |
60 | lz4.h generates and decodes LZ4-compressed blocks (doc/lz4_Block_format.md). |
61 | Decompressing such a compressed block requires additional metadata. |
62 | Exact metadata depends on exact decompression function. |
63 | For the typical case of LZ4_decompress_safe(), |
64 | metadata includes block's compressed size, and maximum bound of decompressed size. |
65 | Each application is free to encode and pass such metadata in whichever way it wants. |
66 | |
67 | lz4.h only handle blocks, it can not generate Frames. |
68 | |
69 | Blocks are different from Frames (doc/lz4_Frame_format.md). |
70 | Frames bundle both blocks and metadata in a specified manner. |
71 | Embedding metadata is required for compressed data to be self-contained and portable. |
72 | Frame format is delivered through a companion API, declared in lz4frame.h. |
73 | The `lz4` CLI can only manage frames. |
74 | */ |
75 | |
76 | /*^*************************************************************** |
77 | * Export parameters |
78 | *****************************************************************/ |
79 | /* |
80 | * LZ4_DLL_EXPORT : |
81 | * Enable exporting of functions when building a Windows DLL |
82 | * LZ4LIB_VISIBILITY : |
83 | * Control library symbols visibility. |
84 | */ |
85 | #ifndef LZ4LIB_VISIBILITY |
86 | # if defined(__GNUC__) && (__GNUC__ >= 4) |
87 | # define LZ4LIB_VISIBILITY __attribute__ ((visibility ("default"))) |
88 | # else |
89 | # define LZ4LIB_VISIBILITY |
90 | # endif |
91 | #endif |
92 | #if defined(LZ4_DLL_EXPORT) && (LZ4_DLL_EXPORT==1) |
93 | # define LZ4LIB_API __declspec(dllexport) LZ4LIB_VISIBILITY |
94 | #elif defined(LZ4_DLL_IMPORT) && (LZ4_DLL_IMPORT==1) |
95 | # define LZ4LIB_API __declspec(dllimport) LZ4LIB_VISIBILITY /* It isn't required but allows to generate better code, saving a function pointer load from the IAT and an indirect jump.*/ |
96 | #else |
97 | # define LZ4LIB_API LZ4LIB_VISIBILITY |
98 | #endif |
99 | |
100 | /*------ Version ------*/ |
101 | #define LZ4_VERSION_MAJOR 1 /* for breaking interface changes */ |
102 | #define LZ4_VERSION_MINOR 9 /* for new (non-breaking) interface capabilities */ |
103 | #define LZ4_VERSION_RELEASE 2 /* for tweaks, bug-fixes, or development */ |
104 | |
105 | #define LZ4_VERSION_NUMBER (LZ4_VERSION_MAJOR *100*100 + LZ4_VERSION_MINOR *100 + LZ4_VERSION_RELEASE) |
106 | |
107 | #define LZ4_LIB_VERSION LZ4_VERSION_MAJOR.LZ4_VERSION_MINOR.LZ4_VERSION_RELEASE |
108 | #define LZ4_QUOTE(str) #str |
109 | #define LZ4_EXPAND_AND_QUOTE(str) LZ4_QUOTE(str) |
110 | #define LZ4_VERSION_STRING LZ4_EXPAND_AND_QUOTE(LZ4_LIB_VERSION) |
111 | |
112 | LZ4LIB_API int LZ4_versionNumber (void); /**< library version number; useful to check dll version */ |
113 | LZ4LIB_API const char* LZ4_versionString (void); /**< library version string; useful to check dll version */ |
114 | |
115 | |
116 | /*-************************************ |
117 | * Tuning parameter |
118 | **************************************/ |
119 | /*! |
120 | * LZ4_MEMORY_USAGE : |
121 | * Memory usage formula : N->2^N Bytes (examples : 10 -> 1KB; 12 -> 4KB ; 16 -> 64KB; 20 -> 1MB; etc.) |
122 | * Increasing memory usage improves compression ratio. |
123 | * Reduced memory usage may improve speed, thanks to better cache locality. |
124 | * Default value is 14, for 16KB, which nicely fits into Intel x86 L1 cache |
125 | */ |
126 | #ifndef LZ4_MEMORY_USAGE |
127 | # define LZ4_MEMORY_USAGE 14 |
128 | #endif |
129 | |
130 | |
131 | /*-************************************ |
132 | * Simple Functions |
133 | **************************************/ |
134 | /*! LZ4_compress_default() : |
135 | * Compresses 'srcSize' bytes from buffer 'src' |
136 | * into already allocated 'dst' buffer of size 'dstCapacity'. |
137 | * Compression is guaranteed to succeed if 'dstCapacity' >= LZ4_compressBound(srcSize). |
138 | * It also runs faster, so it's a recommended setting. |
139 | * If the function cannot compress 'src' into a more limited 'dst' budget, |
140 | * compression stops *immediately*, and the function result is zero. |
141 | * In which case, 'dst' content is undefined (invalid). |
142 | * srcSize : max supported value is LZ4_MAX_INPUT_SIZE. |
143 | * dstCapacity : size of buffer 'dst' (which must be already allocated) |
144 | * @return : the number of bytes written into buffer 'dst' (necessarily <= dstCapacity) |
145 | * or 0 if compression fails |
146 | * Note : This function is protected against buffer overflow scenarios (never writes outside 'dst' buffer, nor read outside 'source' buffer). |
147 | */ |
148 | LZ4LIB_API int LZ4_compress_default(const char* src, char* dst, int srcSize, int dstCapacity); |
149 | |
150 | /*! LZ4_decompress_safe() : |
151 | * compressedSize : is the exact complete size of the compressed block. |
152 | * dstCapacity : is the size of destination buffer (which must be already allocated), presumed an upper bound of decompressed size. |
153 | * @return : the number of bytes decompressed into destination buffer (necessarily <= dstCapacity) |
154 | * If destination buffer is not large enough, decoding will stop and output an error code (negative value). |
155 | * If the source stream is detected malformed, the function will stop decoding and return a negative result. |
156 | * Note 1 : This function is protected against malicious data packets : |
157 | * it will never writes outside 'dst' buffer, nor read outside 'source' buffer, |
158 | * even if the compressed block is maliciously modified to order the decoder to do these actions. |
159 | * In such case, the decoder stops immediately, and considers the compressed block malformed. |
160 | * Note 2 : compressedSize and dstCapacity must be provided to the function, the compressed block does not contain them. |
161 | * The implementation is free to send / store / derive this information in whichever way is most beneficial. |
162 | * If there is a need for a different format which bundles together both compressed data and its metadata, consider looking at lz4frame.h instead. |
163 | */ |
164 | LZ4LIB_API int LZ4_decompress_safe (const char* src, char* dst, int compressedSize, int dstCapacity); |
165 | |
166 | |
167 | /*-************************************ |
168 | * Advanced Functions |
169 | **************************************/ |
170 | #define LZ4_MAX_INPUT_SIZE 0x7E000000 /* 2 113 929 216 bytes */ |
171 | #define LZ4_COMPRESSBOUND(isize) ((unsigned)(isize) > (unsigned)LZ4_MAX_INPUT_SIZE ? 0 : (isize) + ((isize)/255) + 16) |
172 | |
173 | /*! LZ4_compressBound() : |
174 | Provides the maximum size that LZ4 compression may output in a "worst case" scenario (input data not compressible) |
175 | This function is primarily useful for memory allocation purposes (destination buffer size). |
176 | Macro LZ4_COMPRESSBOUND() is also provided for compilation-time evaluation (stack memory allocation for example). |
177 | Note that LZ4_compress_default() compresses faster when dstCapacity is >= LZ4_compressBound(srcSize) |
178 | inputSize : max supported value is LZ4_MAX_INPUT_SIZE |
179 | return : maximum output size in a "worst case" scenario |
180 | or 0, if input size is incorrect (too large or negative) |
181 | */ |
182 | LZ4LIB_API int LZ4_compressBound(int inputSize); |
183 | |
184 | /*! LZ4_compress_fast() : |
185 | Same as LZ4_compress_default(), but allows selection of "acceleration" factor. |
186 | The larger the acceleration value, the faster the algorithm, but also the lesser the compression. |
187 | It's a trade-off. It can be fine tuned, with each successive value providing roughly +~3% to speed. |
188 | An acceleration value of "1" is the same as regular LZ4_compress_default() |
189 | Values <= 0 will be replaced by ACCELERATION_DEFAULT (currently == 1, see lz4.c). |
190 | */ |
191 | LZ4LIB_API int LZ4_compress_fast (const char* src, char* dst, int srcSize, int dstCapacity, int acceleration); |
192 | |
193 | |
194 | /*! LZ4_compress_fast_extState() : |
195 | * Same as LZ4_compress_fast(), using an externally allocated memory space for its state. |
196 | * Use LZ4_sizeofState() to know how much memory must be allocated, |
197 | * and allocate it on 8-bytes boundaries (using `malloc()` typically). |
198 | * Then, provide this buffer as `void* state` to compression function. |
199 | */ |
200 | LZ4LIB_API int LZ4_sizeofState(void); |
201 | LZ4LIB_API int LZ4_compress_fast_extState (void* state, const char* src, char* dst, int srcSize, int dstCapacity, int acceleration); |
202 | |
203 | |
204 | /*! LZ4_compress_destSize() : |
205 | * Reverse the logic : compresses as much data as possible from 'src' buffer |
206 | * into already allocated buffer 'dst', of size >= 'targetDestSize'. |
207 | * This function either compresses the entire 'src' content into 'dst' if it's large enough, |
208 | * or fill 'dst' buffer completely with as much data as possible from 'src'. |
209 | * note: acceleration parameter is fixed to "default". |
210 | * |
211 | * *srcSizePtr : will be modified to indicate how many bytes where read from 'src' to fill 'dst'. |
212 | * New value is necessarily <= input value. |
213 | * @return : Nb bytes written into 'dst' (necessarily <= targetDestSize) |
214 | * or 0 if compression fails. |
215 | */ |
216 | LZ4LIB_API int LZ4_compress_destSize (const char* src, char* dst, int* srcSizePtr, int targetDstSize); |
217 | |
218 | |
219 | /*! LZ4_decompress_safe_partial() : |
220 | * Decompress an LZ4 compressed block, of size 'srcSize' at position 'src', |
221 | * into destination buffer 'dst' of size 'dstCapacity'. |
222 | * Up to 'targetOutputSize' bytes will be decoded. |
223 | * The function stops decoding on reaching this objective, |
224 | * which can boost performance when only the beginning of a block is required. |
225 | * |
226 | * @return : the number of bytes decoded in `dst` (necessarily <= dstCapacity) |
227 | * If source stream is detected malformed, function returns a negative result. |
228 | * |
229 | * Note : @return can be < targetOutputSize, if compressed block contains less data. |
230 | * |
231 | * Note 2 : this function features 2 parameters, targetOutputSize and dstCapacity, |
232 | * and expects targetOutputSize <= dstCapacity. |
233 | * It effectively stops decoding on reaching targetOutputSize, |
234 | * so dstCapacity is kind of redundant. |
235 | * This is because in a previous version of this function, |
236 | * decoding operation would not "break" a sequence in the middle. |
237 | * As a consequence, there was no guarantee that decoding would stop at exactly targetOutputSize, |
238 | * it could write more bytes, though only up to dstCapacity. |
239 | * Some "margin" used to be required for this operation to work properly. |
240 | * This is no longer necessary. |
241 | * The function nonetheless keeps its signature, in an effort to not break API. |
242 | */ |
243 | LZ4LIB_API int LZ4_decompress_safe_partial (const char* src, char* dst, int srcSize, int targetOutputSize, int dstCapacity); |
244 | |
245 | |
246 | /*-********************************************* |
247 | * Streaming Compression Functions |
248 | ***********************************************/ |
249 | typedef union LZ4_stream_u LZ4_stream_t; /* incomplete type (defined later) */ |
250 | |
251 | LZ4LIB_API LZ4_stream_t* LZ4_createStream(void); |
252 | LZ4LIB_API int LZ4_freeStream (LZ4_stream_t* streamPtr); |
253 | |
254 | /*! LZ4_resetStream_fast() : v1.9.0+ |
255 | * Use this to prepare an LZ4_stream_t for a new chain of dependent blocks |
256 | * (e.g., LZ4_compress_fast_continue()). |
257 | * |
258 | * An LZ4_stream_t must be initialized once before usage. |
259 | * This is automatically done when created by LZ4_createStream(). |
260 | * However, should the LZ4_stream_t be simply declared on stack (for example), |
261 | * it's necessary to initialize it first, using LZ4_initStream(). |
262 | * |
263 | * After init, start any new stream with LZ4_resetStream_fast(). |
264 | * A same LZ4_stream_t can be re-used multiple times consecutively |
265 | * and compress multiple streams, |
266 | * provided that it starts each new stream with LZ4_resetStream_fast(). |
267 | * |
268 | * LZ4_resetStream_fast() is much faster than LZ4_initStream(), |
269 | * but is not compatible with memory regions containing garbage data. |
270 | * |
271 | * Note: it's only useful to call LZ4_resetStream_fast() |
272 | * in the context of streaming compression. |
273 | * The *extState* functions perform their own resets. |
274 | * Invoking LZ4_resetStream_fast() before is redundant, and even counterproductive. |
275 | */ |
276 | LZ4LIB_API void LZ4_resetStream_fast (LZ4_stream_t* streamPtr); |
277 | |
278 | /*! LZ4_loadDict() : |
279 | * Use this function to reference a static dictionary into LZ4_stream_t. |
280 | * The dictionary must remain available during compression. |
281 | * LZ4_loadDict() triggers a reset, so any previous data will be forgotten. |
282 | * The same dictionary will have to be loaded on decompression side for successful decoding. |
283 | * Dictionary are useful for better compression of small data (KB range). |
284 | * While LZ4 accept any input as dictionary, |
285 | * results are generally better when using Zstandard's Dictionary Builder. |
286 | * Loading a size of 0 is allowed, and is the same as reset. |
287 | * @return : loaded dictionary size, in bytes (necessarily <= 64 KB) |
288 | */ |
289 | LZ4LIB_API int LZ4_loadDict (LZ4_stream_t* streamPtr, const char* dictionary, int dictSize); |
290 | |
291 | /*! LZ4_compress_fast_continue() : |
292 | * Compress 'src' content using data from previously compressed blocks, for better compression ratio. |
293 | * 'dst' buffer must be already allocated. |
294 | * If dstCapacity >= LZ4_compressBound(srcSize), compression is guaranteed to succeed, and runs faster. |
295 | * |
296 | * @return : size of compressed block |
297 | * or 0 if there is an error (typically, cannot fit into 'dst'). |
298 | * |
299 | * Note 1 : Each invocation to LZ4_compress_fast_continue() generates a new block. |
300 | * Each block has precise boundaries. |
301 | * Each block must be decompressed separately, calling LZ4_decompress_*() with relevant metadata. |
302 | * It's not possible to append blocks together and expect a single invocation of LZ4_decompress_*() to decompress them together. |
303 | * |
304 | * Note 2 : The previous 64KB of source data is __assumed__ to remain present, unmodified, at same address in memory ! |
305 | * |
306 | * Note 3 : When input is structured as a double-buffer, each buffer can have any size, including < 64 KB. |
307 | * Make sure that buffers are separated, by at least one byte. |
308 | * This construction ensures that each block only depends on previous block. |
309 | * |
310 | * Note 4 : If input buffer is a ring-buffer, it can have any size, including < 64 KB. |
311 | * |
312 | * Note 5 : After an error, the stream status is undefined (invalid), it can only be reset or freed. |
313 | */ |
314 | LZ4LIB_API int LZ4_compress_fast_continue (LZ4_stream_t* streamPtr, const char* src, char* dst, int srcSize, int dstCapacity, int acceleration); |
315 | |
316 | /*! LZ4_saveDict() : |
317 | * If last 64KB data cannot be guaranteed to remain available at its current memory location, |
318 | * save it into a safer place (char* safeBuffer). |
319 | * This is schematically equivalent to a memcpy() followed by LZ4_loadDict(), |
320 | * but is much faster, because LZ4_saveDict() doesn't need to rebuild tables. |
321 | * @return : saved dictionary size in bytes (necessarily <= maxDictSize), or 0 if error. |
322 | */ |
323 | LZ4LIB_API int LZ4_saveDict (LZ4_stream_t* streamPtr, char* safeBuffer, int maxDictSize); |
324 | |
325 | |
326 | /*-********************************************** |
327 | * Streaming Decompression Functions |
328 | * Bufferless synchronous API |
329 | ************************************************/ |
330 | typedef union LZ4_streamDecode_u LZ4_streamDecode_t; /* tracking context */ |
331 | |
332 | /*! LZ4_createStreamDecode() and LZ4_freeStreamDecode() : |
333 | * creation / destruction of streaming decompression tracking context. |
334 | * A tracking context can be re-used multiple times. |
335 | */ |
336 | LZ4LIB_API LZ4_streamDecode_t* LZ4_createStreamDecode(void); |
337 | LZ4LIB_API int LZ4_freeStreamDecode (LZ4_streamDecode_t* LZ4_stream); |
338 | |
339 | /*! LZ4_setStreamDecode() : |
340 | * An LZ4_streamDecode_t context can be allocated once and re-used multiple times. |
341 | * Use this function to start decompression of a new stream of blocks. |
342 | * A dictionary can optionally be set. Use NULL or size 0 for a reset order. |
343 | * Dictionary is presumed stable : it must remain accessible and unmodified during next decompression. |
344 | * @return : 1 if OK, 0 if error |
345 | */ |
346 | LZ4LIB_API int LZ4_setStreamDecode (LZ4_streamDecode_t* LZ4_streamDecode, const char* dictionary, int dictSize); |
347 | |
348 | /*! LZ4_decoderRingBufferSize() : v1.8.2+ |
349 | * Note : in a ring buffer scenario (optional), |
350 | * blocks are presumed decompressed next to each other |
351 | * up to the moment there is not enough remaining space for next block (remainingSize < maxBlockSize), |
352 | * at which stage it resumes from beginning of ring buffer. |
353 | * When setting such a ring buffer for streaming decompression, |
354 | * provides the minimum size of this ring buffer |
355 | * to be compatible with any source respecting maxBlockSize condition. |
356 | * @return : minimum ring buffer size, |
357 | * or 0 if there is an error (invalid maxBlockSize). |
358 | */ |
359 | LZ4LIB_API int LZ4_decoderRingBufferSize(int maxBlockSize); |
360 | #define LZ4_DECODER_RING_BUFFER_SIZE(maxBlockSize) (65536 + 14 + (maxBlockSize)) /* for static allocation; maxBlockSize presumed valid */ |
361 | |
362 | /*! LZ4_decompress_*_continue() : |
363 | * These decoding functions allow decompression of consecutive blocks in "streaming" mode. |
364 | * A block is an unsplittable entity, it must be presented entirely to a decompression function. |
365 | * Decompression functions only accepts one block at a time. |
366 | * The last 64KB of previously decoded data *must* remain available and unmodified at the memory position where they were decoded. |
367 | * If less than 64KB of data has been decoded, all the data must be present. |
368 | * |
369 | * Special : if decompression side sets a ring buffer, it must respect one of the following conditions : |
370 | * - Decompression buffer size is _at least_ LZ4_decoderRingBufferSize(maxBlockSize). |
371 | * maxBlockSize is the maximum size of any single block. It can have any value > 16 bytes. |
372 | * In which case, encoding and decoding buffers do not need to be synchronized. |
373 | * Actually, data can be produced by any source compliant with LZ4 format specification, and respecting maxBlockSize. |
374 | * - Synchronized mode : |
375 | * Decompression buffer size is _exactly_ the same as compression buffer size, |
376 | * and follows exactly same update rule (block boundaries at same positions), |
377 | * and decoding function is provided with exact decompressed size of each block (exception for last block of the stream), |
378 | * _then_ decoding & encoding ring buffer can have any size, including small ones ( < 64 KB). |
379 | * - Decompression buffer is larger than encoding buffer, by a minimum of maxBlockSize more bytes. |
380 | * In which case, encoding and decoding buffers do not need to be synchronized, |
381 | * and encoding ring buffer can have any size, including small ones ( < 64 KB). |
382 | * |
383 | * Whenever these conditions are not possible, |
384 | * save the last 64KB of decoded data into a safe buffer where it can't be modified during decompression, |
385 | * then indicate where this data is saved using LZ4_setStreamDecode(), before decompressing next block. |
386 | */ |
387 | LZ4LIB_API int LZ4_decompress_safe_continue (LZ4_streamDecode_t* LZ4_streamDecode, const char* src, char* dst, int srcSize, int dstCapacity); |
388 | |
389 | |
390 | /*! LZ4_decompress_*_usingDict() : |
391 | * These decoding functions work the same as |
392 | * a combination of LZ4_setStreamDecode() followed by LZ4_decompress_*_continue() |
393 | * They are stand-alone, and don't need an LZ4_streamDecode_t structure. |
394 | * Dictionary is presumed stable : it must remain accessible and unmodified during decompression. |
395 | * Performance tip : Decompression speed can be substantially increased |
396 | * when dst == dictStart + dictSize. |
397 | */ |
398 | LZ4LIB_API int LZ4_decompress_safe_usingDict (const char* src, char* dst, int srcSize, int dstCapcity, const char* dictStart, int dictSize); |
399 | |
400 | #endif /* LZ4_H_2983827168210 */ |
401 | |
402 | |
403 | /*^************************************* |
404 | * !!!!!! STATIC LINKING ONLY !!!!!! |
405 | ***************************************/ |
406 | |
407 | /*-**************************************************************************** |
408 | * Experimental section |
409 | * |
410 | * Symbols declared in this section must be considered unstable. Their |
411 | * signatures or semantics may change, or they may be removed altogether in the |
412 | * future. They are therefore only safe to depend on when the caller is |
413 | * statically linked against the library. |
414 | * |
415 | * To protect against unsafe usage, not only are the declarations guarded, |
416 | * the definitions are hidden by default |
417 | * when building LZ4 as a shared/dynamic library. |
418 | * |
419 | * In order to access these declarations, |
420 | * define LZ4_STATIC_LINKING_ONLY in your application |
421 | * before including LZ4's headers. |
422 | * |
423 | * In order to make their implementations accessible dynamically, you must |
424 | * define LZ4_PUBLISH_STATIC_FUNCTIONS when building the LZ4 library. |
425 | ******************************************************************************/ |
426 | |
427 | #ifdef LZ4_STATIC_LINKING_ONLY |
428 | |
429 | #ifndef LZ4_STATIC_3504398509 |
430 | #define LZ4_STATIC_3504398509 |
431 | |
432 | #ifdef LZ4_PUBLISH_STATIC_FUNCTIONS |
433 | #define LZ4LIB_STATIC_API LZ4LIB_API |
434 | #else |
435 | #define LZ4LIB_STATIC_API |
436 | #endif |
437 | |
438 | |
439 | /*! LZ4_compress_fast_extState_fastReset() : |
440 | * A variant of LZ4_compress_fast_extState(). |
441 | * |
442 | * Using this variant avoids an expensive initialization step. |
443 | * It is only safe to call if the state buffer is known to be correctly initialized already |
444 | * (see above comment on LZ4_resetStream_fast() for a definition of "correctly initialized"). |
445 | * From a high level, the difference is that |
446 | * this function initializes the provided state with a call to something like LZ4_resetStream_fast() |
447 | * while LZ4_compress_fast_extState() starts with a call to LZ4_resetStream(). |
448 | */ |
449 | LZ4LIB_STATIC_API int LZ4_compress_fast_extState_fastReset (void* state, const char* src, char* dst, int srcSize, int dstCapacity, int acceleration); |
450 | |
451 | /*! LZ4_attach_dictionary() : |
452 | * This is an experimental API that allows |
453 | * efficient use of a static dictionary many times. |
454 | * |
455 | * Rather than re-loading the dictionary buffer into a working context before |
456 | * each compression, or copying a pre-loaded dictionary's LZ4_stream_t into a |
457 | * working LZ4_stream_t, this function introduces a no-copy setup mechanism, |
458 | * in which the working stream references the dictionary stream in-place. |
459 | * |
460 | * Several assumptions are made about the state of the dictionary stream. |
461 | * Currently, only streams which have been prepared by LZ4_loadDict() should |
462 | * be expected to work. |
463 | * |
464 | * Alternatively, the provided dictionaryStream may be NULL, |
465 | * in which case any existing dictionary stream is unset. |
466 | * |
467 | * If a dictionary is provided, it replaces any pre-existing stream history. |
468 | * The dictionary contents are the only history that can be referenced and |
469 | * logically immediately precede the data compressed in the first subsequent |
470 | * compression call. |
471 | * |
472 | * The dictionary will only remain attached to the working stream through the |
473 | * first compression call, at the end of which it is cleared. The dictionary |
474 | * stream (and source buffer) must remain in-place / accessible / unchanged |
475 | * through the completion of the first compression call on the stream. |
476 | */ |
477 | LZ4LIB_STATIC_API void LZ4_attach_dictionary(LZ4_stream_t* workingStream, const LZ4_stream_t* dictionaryStream); |
478 | |
479 | |
480 | /*! In-place compression and decompression |
481 | * |
482 | * It's possible to have input and output sharing the same buffer, |
483 | * for highly contrained memory environments. |
484 | * In both cases, it requires input to lay at the end of the buffer, |
485 | * and decompression to start at beginning of the buffer. |
486 | * Buffer size must feature some margin, hence be larger than final size. |
487 | * |
488 | * |<------------------------buffer--------------------------------->| |
489 | * |<-----------compressed data--------->| |
490 | * |<-----------decompressed size------------------>| |
491 | * |<----margin---->| |
492 | * |
493 | * This technique is more useful for decompression, |
494 | * since decompressed size is typically larger, |
495 | * and margin is short. |
496 | * |
497 | * In-place decompression will work inside any buffer |
498 | * which size is >= LZ4_DECOMPRESS_INPLACE_BUFFER_SIZE(decompressedSize). |
499 | * This presumes that decompressedSize > compressedSize. |
500 | * Otherwise, it means compression actually expanded data, |
501 | * and it would be more efficient to store such data with a flag indicating it's not compressed. |
502 | * This can happen when data is not compressible (already compressed, or encrypted). |
503 | * |
504 | * For in-place compression, margin is larger, as it must be able to cope with both |
505 | * history preservation, requiring input data to remain unmodified up to LZ4_DISTANCE_MAX, |
506 | * and data expansion, which can happen when input is not compressible. |
507 | * As a consequence, buffer size requirements are much higher, |
508 | * and memory savings offered by in-place compression are more limited. |
509 | * |
510 | * There are ways to limit this cost for compression : |
511 | * - Reduce history size, by modifying LZ4_DISTANCE_MAX. |
512 | * Note that it is a compile-time constant, so all compressions will apply this limit. |
513 | * Lower values will reduce compression ratio, except when input_size < LZ4_DISTANCE_MAX, |
514 | * so it's a reasonable trick when inputs are known to be small. |
515 | * - Require the compressor to deliver a "maximum compressed size". |
516 | * This is the `dstCapacity` parameter in `LZ4_compress*()`. |
517 | * When this size is < LZ4_COMPRESSBOUND(inputSize), then compression can fail, |
518 | * in which case, the return code will be 0 (zero). |
519 | * The caller must be ready for these cases to happen, |
520 | * and typically design a backup scheme to send data uncompressed. |
521 | * The combination of both techniques can significantly reduce |
522 | * the amount of margin required for in-place compression. |
523 | * |
524 | * In-place compression can work in any buffer |
525 | * which size is >= (maxCompressedSize) |
526 | * with maxCompressedSize == LZ4_COMPRESSBOUND(srcSize) for guaranteed compression success. |
527 | * LZ4_COMPRESS_INPLACE_BUFFER_SIZE() depends on both maxCompressedSize and LZ4_DISTANCE_MAX, |
528 | * so it's possible to reduce memory requirements by playing with them. |
529 | */ |
530 | |
531 | #define LZ4_DECOMPRESS_INPLACE_MARGIN(compressedSize) (((compressedSize) >> 8) + 32) |
532 | #define LZ4_DECOMPRESS_INPLACE_BUFFER_SIZE(decompressedSize) ((decompressedSize) + LZ4_DECOMPRESS_INPLACE_MARGIN(decompressedSize)) /**< note: presumes that compressedSize < decompressedSize. note2: margin is overestimated a bit, since it could use compressedSize instead */ |
533 | |
534 | #ifndef LZ4_DISTANCE_MAX /* history window size; can be user-defined at compile time */ |
535 | # define LZ4_DISTANCE_MAX 65535 /* set to maximum value by default */ |
536 | #endif |
537 | |
538 | #define LZ4_COMPRESS_INPLACE_MARGIN (LZ4_DISTANCE_MAX + 32) /* LZ4_DISTANCE_MAX can be safely replaced by srcSize when it's smaller */ |
539 | #define LZ4_COMPRESS_INPLACE_BUFFER_SIZE(maxCompressedSize) ((maxCompressedSize) + LZ4_COMPRESS_INPLACE_MARGIN) /**< 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)) */ |
540 | |
541 | #endif /* LZ4_STATIC_3504398509 */ |
542 | #endif /* LZ4_STATIC_LINKING_ONLY */ |
543 | |
544 | |
545 | |
546 | #ifndef LZ4_H_98237428734687 |
547 | #define LZ4_H_98237428734687 |
548 | |
549 | /*-************************************************************ |
550 | * PRIVATE DEFINITIONS |
551 | ************************************************************** |
552 | * Do not use these definitions directly. |
553 | * They are only exposed to allow static allocation of `LZ4_stream_t` and `LZ4_streamDecode_t`. |
554 | * Accessing members will expose code to API and/or ABI break in future versions of the library. |
555 | **************************************************************/ |
556 | #define LZ4_HASHLOG (LZ4_MEMORY_USAGE-2) |
557 | #define LZ4_HASHTABLESIZE (1 << LZ4_MEMORY_USAGE) |
558 | #define LZ4_HASH_SIZE_U32 (1 << LZ4_HASHLOG) /* required as macro for static allocation */ |
559 | |
560 | #if defined(__cplusplus) || (defined (__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) /* C99 */) |
561 | #include <stdint.h> |
562 | |
563 | typedef struct LZ4_stream_t_internal LZ4_stream_t_internal; |
564 | struct LZ4_stream_t_internal { |
565 | uint32_t hashTable[LZ4_HASH_SIZE_U32]; |
566 | uint32_t currentOffset; |
567 | uint16_t dirty; |
568 | uint16_t tableType; |
569 | const uint8_t* dictionary; |
570 | const LZ4_stream_t_internal* dictCtx; |
571 | uint32_t dictSize; |
572 | }; |
573 | |
574 | typedef struct { |
575 | const uint8_t* externalDict; |
576 | size_t extDictSize; |
577 | const uint8_t* prefixEnd; |
578 | size_t prefixSize; |
579 | } LZ4_streamDecode_t_internal; |
580 | |
581 | #else |
582 | |
583 | typedef struct LZ4_stream_t_internal LZ4_stream_t_internal; |
584 | struct LZ4_stream_t_internal { |
585 | unsigned int hashTable[LZ4_HASH_SIZE_U32]; |
586 | unsigned int currentOffset; |
587 | unsigned short dirty; |
588 | unsigned short tableType; |
589 | const unsigned char* dictionary; |
590 | const LZ4_stream_t_internal* dictCtx; |
591 | unsigned int dictSize; |
592 | }; |
593 | |
594 | typedef struct { |
595 | const unsigned char* externalDict; |
596 | const unsigned char* prefixEnd; |
597 | size_t extDictSize; |
598 | size_t prefixSize; |
599 | } LZ4_streamDecode_t_internal; |
600 | |
601 | #endif |
602 | |
603 | /*! LZ4_stream_t : |
604 | * information structure to track an LZ4 stream. |
605 | * LZ4_stream_t can also be created using LZ4_createStream(), which is recommended. |
606 | * The structure definition can be convenient for static allocation |
607 | * (on stack, or as part of larger structure). |
608 | * Init this structure with LZ4_initStream() before first use. |
609 | * note : only use this definition in association with static linking ! |
610 | * this definition is not API/ABI safe, and may change in a future version. |
611 | */ |
612 | #define LZ4_STREAMSIZE_U64 ((1 << (LZ4_MEMORY_USAGE-3)) + 4 + ((sizeof(void*)==16) ? 4 : 0) /*AS-400*/ ) |
613 | #define LZ4_STREAMSIZE (LZ4_STREAMSIZE_U64 * sizeof(unsigned long long)) |
614 | union LZ4_stream_u { |
615 | unsigned long long table[LZ4_STREAMSIZE_U64]; |
616 | LZ4_stream_t_internal internal_donotuse; |
617 | } ; /* previously typedef'd to LZ4_stream_t */ |
618 | |
619 | /*! LZ4_initStream() : v1.9.0+ |
620 | * An LZ4_stream_t structure must be initialized at least once. |
621 | * This is automatically done when invoking LZ4_createStream(), |
622 | * but it's not when the structure is simply declared on stack (for example). |
623 | * |
624 | * Use LZ4_initStream() to properly initialize a newly declared LZ4_stream_t. |
625 | * It can also initialize any arbitrary buffer of sufficient size, |
626 | * and will @return a pointer of proper type upon initialization. |
627 | * |
628 | * Note : initialization fails if size and alignment conditions are not respected. |
629 | * In which case, the function will @return NULL. |
630 | * Note2: An LZ4_stream_t structure guarantees correct alignment and size. |
631 | * Note3: Before v1.9.0, use LZ4_resetStream() instead |
632 | */ |
633 | LZ4LIB_API LZ4_stream_t* LZ4_initStream (void* buffer, size_t size); |
634 | |
635 | |
636 | /*! LZ4_streamDecode_t : |
637 | * information structure to track an LZ4 stream during decompression. |
638 | * init this structure using LZ4_setStreamDecode() before first use. |
639 | * note : only use in association with static linking ! |
640 | * this definition is not API/ABI safe, |
641 | * and may change in a future version ! |
642 | */ |
643 | #define LZ4_STREAMDECODESIZE_U64 (4 + ((sizeof(void*)==16) ? 2 : 0) /*AS-400*/ ) |
644 | #define LZ4_STREAMDECODESIZE (LZ4_STREAMDECODESIZE_U64 * sizeof(unsigned long long)) |
645 | union LZ4_streamDecode_u { |
646 | unsigned long long table[LZ4_STREAMDECODESIZE_U64]; |
647 | LZ4_streamDecode_t_internal internal_donotuse; |
648 | } ; /* previously typedef'd to LZ4_streamDecode_t */ |
649 | |
650 | |
651 | |
652 | /*-************************************ |
653 | * Obsolete Functions |
654 | **************************************/ |
655 | |
656 | /*! Deprecation warnings |
657 | * |
658 | * Deprecated functions make the compiler generate a warning when invoked. |
659 | * This is meant to invite users to update their source code. |
660 | * Should deprecation warnings be a problem, it is generally possible to disable them, |
661 | * typically with -Wno-deprecated-declarations for gcc |
662 | * or _CRT_SECURE_NO_WARNINGS in Visual. |
663 | * |
664 | * Another method is to define LZ4_DISABLE_DEPRECATE_WARNINGS |
665 | * before including the header file. |
666 | */ |
667 | #ifdef LZ4_DISABLE_DEPRECATE_WARNINGS |
668 | # define LZ4_DEPRECATED(message) /* disable deprecation warnings */ |
669 | #else |
670 | # define LZ4_GCC_VERSION (__GNUC__ * 100 + __GNUC_MINOR__) |
671 | # if defined (__cplusplus) && (__cplusplus >= 201402) /* C++14 or greater */ |
672 | # define LZ4_DEPRECATED(message) [[deprecated(message)]] |
673 | # elif (LZ4_GCC_VERSION >= 405) || defined(__clang__) |
674 | # define LZ4_DEPRECATED(message) __attribute__((deprecated(message))) |
675 | # elif (LZ4_GCC_VERSION >= 301) |
676 | # define LZ4_DEPRECATED(message) __attribute__((deprecated)) |
677 | # elif defined(_MSC_VER) |
678 | # define LZ4_DEPRECATED(message) __declspec(deprecated(message)) |
679 | # else |
680 | # pragma message("WARNING: You need to implement LZ4_DEPRECATED for this compiler") |
681 | # define LZ4_DEPRECATED(message) |
682 | # endif |
683 | #endif /* LZ4_DISABLE_DEPRECATE_WARNINGS */ |
684 | |
685 | /* Obsolete compression functions */ |
686 | LZ4_DEPRECATED("use LZ4_compress_default() instead" ) LZ4LIB_API int LZ4_compress (const char* src, char* dest, int srcSize); |
687 | LZ4_DEPRECATED("use LZ4_compress_default() instead" ) LZ4LIB_API int LZ4_compress_limitedOutput (const char* src, char* dest, int srcSize, int maxOutputSize); |
688 | LZ4_DEPRECATED("use LZ4_compress_fast_extState() instead" ) LZ4LIB_API int LZ4_compress_withState (void* state, const char* source, char* dest, int inputSize); |
689 | LZ4_DEPRECATED("use LZ4_compress_fast_extState() instead" ) LZ4LIB_API int LZ4_compress_limitedOutput_withState (void* state, const char* source, char* dest, int inputSize, int maxOutputSize); |
690 | LZ4_DEPRECATED("use LZ4_compress_fast_continue() instead" ) LZ4LIB_API int LZ4_compress_continue (LZ4_stream_t* LZ4_streamPtr, const char* source, char* dest, int inputSize); |
691 | LZ4_DEPRECATED("use LZ4_compress_fast_continue() instead" ) LZ4LIB_API int LZ4_compress_limitedOutput_continue (LZ4_stream_t* LZ4_streamPtr, const char* source, char* dest, int inputSize, int maxOutputSize); |
692 | |
693 | /* Obsolete decompression functions */ |
694 | LZ4_DEPRECATED("use LZ4_decompress_fast() instead" ) LZ4LIB_API int LZ4_uncompress (const char* source, char* dest, int outputSize); |
695 | LZ4_DEPRECATED("use LZ4_decompress_safe() instead" ) LZ4LIB_API int LZ4_uncompress_unknownOutputSize (const char* source, char* dest, int isize, int maxOutputSize); |
696 | |
697 | /* Obsolete streaming functions; degraded functionality; do not use! |
698 | * |
699 | * In order to perform streaming compression, these functions depended on data |
700 | * that is no longer tracked in the state. They have been preserved as well as |
701 | * possible: using them will still produce a correct output. However, they don't |
702 | * actually retain any history between compression calls. The compression ratio |
703 | * achieved will therefore be no better than compressing each chunk |
704 | * independently. |
705 | */ |
706 | LZ4_DEPRECATED("Use LZ4_createStream() instead" ) LZ4LIB_API void* LZ4_create (char* inputBuffer); |
707 | LZ4_DEPRECATED("Use LZ4_createStream() instead" ) LZ4LIB_API int LZ4_sizeofStreamState(void); |
708 | LZ4_DEPRECATED("Use LZ4_resetStream() instead" ) LZ4LIB_API int LZ4_resetStreamState(void* state, char* inputBuffer); |
709 | LZ4_DEPRECATED("Use LZ4_saveDict() instead" ) LZ4LIB_API char* LZ4_slideInputBuffer (void* state); |
710 | |
711 | /* Obsolete streaming decoding functions */ |
712 | LZ4_DEPRECATED("use LZ4_decompress_safe_usingDict() instead" ) LZ4LIB_API int LZ4_decompress_safe_withPrefix64k (const char* src, char* dst, int compressedSize, int maxDstSize); |
713 | LZ4_DEPRECATED("use LZ4_decompress_fast_usingDict() instead" ) LZ4LIB_API int LZ4_decompress_fast_withPrefix64k (const char* src, char* dst, int originalSize); |
714 | |
715 | /*! LZ4_decompress_fast() : **unsafe!** |
716 | * These functions used to be faster than LZ4_decompress_safe(), |
717 | * but it has changed, and they are now slower than LZ4_decompress_safe(). |
718 | * This is because LZ4_decompress_fast() doesn't know the input size, |
719 | * and therefore must progress more cautiously in the input buffer to not read beyond the end of block. |
720 | * On top of that `LZ4_decompress_fast()` is not protected vs malformed or malicious inputs, making it a security liability. |
721 | * As a consequence, LZ4_decompress_fast() is strongly discouraged, and deprecated. |
722 | * |
723 | * The last remaining LZ4_decompress_fast() specificity is that |
724 | * it can decompress a block without knowing its compressed size. |
725 | * Such functionality could be achieved in a more secure manner, |
726 | * by also providing the maximum size of input buffer, |
727 | * but it would require new prototypes, and adaptation of the implementation to this new use case. |
728 | * |
729 | * Parameters: |
730 | * originalSize : is the uncompressed size to regenerate. |
731 | * `dst` must be already allocated, its size must be >= 'originalSize' bytes. |
732 | * @return : number of bytes read from source buffer (== compressed size). |
733 | * The function expects to finish at block's end exactly. |
734 | * If the source stream is detected malformed, the function stops decoding and returns a negative result. |
735 | * note : LZ4_decompress_fast*() requires originalSize. Thanks to this information, it never writes past the output buffer. |
736 | * However, since it doesn't know its 'src' size, it may read an unknown amount of input, past input buffer bounds. |
737 | * Also, since match offsets are not validated, match reads from 'src' may underflow too. |
738 | * These issues never happen if input (compressed) data is correct. |
739 | * But they may happen if input data is invalid (error or intentional tampering). |
740 | * As a consequence, use these functions in trusted environments with trusted data **only**. |
741 | */ |
742 | |
743 | LZ4_DEPRECATED("This function is deprecated and unsafe. Consider using LZ4_decompress_safe() instead" ) |
744 | LZ4LIB_API int LZ4_decompress_fast (const char* src, char* dst, int originalSize); |
745 | LZ4_DEPRECATED("This function is deprecated and unsafe. Consider using LZ4_decompress_safe_continue() instead" ) |
746 | LZ4LIB_API int LZ4_decompress_fast_continue (LZ4_streamDecode_t* LZ4_streamDecode, const char* src, char* dst, int originalSize); |
747 | LZ4_DEPRECATED("This function is deprecated and unsafe. Consider using LZ4_decompress_safe_usingDict() instead" ) |
748 | LZ4LIB_API int LZ4_decompress_fast_usingDict (const char* src, char* dst, int originalSize, const char* dictStart, int dictSize); |
749 | |
750 | /*! LZ4_resetStream() : |
751 | * An LZ4_stream_t structure must be initialized at least once. |
752 | * This is done with LZ4_initStream(), or LZ4_resetStream(). |
753 | * Consider switching to LZ4_initStream(), |
754 | * invoking LZ4_resetStream() will trigger deprecation warnings in the future. |
755 | */ |
756 | LZ4LIB_API void LZ4_resetStream (LZ4_stream_t* streamPtr); |
757 | |
758 | |
759 | #endif /* LZ4_H_98237428734687 */ |
760 | |
761 | |
762 | #if defined (__cplusplus) |
763 | } |
764 | #endif |
765 | |