xref: /aosp_15_r20/external/zstd/lib/zstd.h (revision 01826a4963a0d8a59bc3812d29bdf0fb76416722) 
1*01826a49SYabin Cui /*
2*01826a49SYabin Cui  * Copyright (c) Meta Platforms, Inc. and affiliates.
3*01826a49SYabin Cui  * All rights reserved.
4*01826a49SYabin Cui  *
5*01826a49SYabin Cui  * This source code is licensed under both the BSD-style license (found in the
6*01826a49SYabin Cui  * LICENSE file in the root directory of this source tree) and the GPLv2 (found
7*01826a49SYabin Cui  * in the COPYING file in the root directory of this source tree).
8*01826a49SYabin Cui  * You may select, at your option, one of the above-listed licenses.
9*01826a49SYabin Cui  */
10*01826a49SYabin Cui #if defined (__cplusplus)
11*01826a49SYabin Cui extern "C" {
12*01826a49SYabin Cui #endif
13*01826a49SYabin Cui 
14*01826a49SYabin Cui #ifndef ZSTD_H_235446
15*01826a49SYabin Cui #define ZSTD_H_235446
16*01826a49SYabin Cui 
17*01826a49SYabin Cui /* ======   Dependencies   ======*/
18*01826a49SYabin Cui #include <limits.h>   /* INT_MAX */
19*01826a49SYabin Cui #include <stddef.h>   /* size_t */
20*01826a49SYabin Cui 
21*01826a49SYabin Cui 
22*01826a49SYabin Cui /* =====   ZSTDLIB_API : control library symbols visibility   ===== */
23*01826a49SYabin Cui #ifndef ZSTDLIB_VISIBLE
24*01826a49SYabin Cui    /* Backwards compatibility with old macro name */
25*01826a49SYabin Cui #  ifdef ZSTDLIB_VISIBILITY
26*01826a49SYabin Cui #    define ZSTDLIB_VISIBLE ZSTDLIB_VISIBILITY
27*01826a49SYabin Cui #  elif defined(__GNUC__) && (__GNUC__ >= 4) && !defined(__MINGW32__)
28*01826a49SYabin Cui #    define ZSTDLIB_VISIBLE __attribute__ ((visibility ("default")))
29*01826a49SYabin Cui #  else
30*01826a49SYabin Cui #    define ZSTDLIB_VISIBLE
31*01826a49SYabin Cui #  endif
32*01826a49SYabin Cui #endif
33*01826a49SYabin Cui 
34*01826a49SYabin Cui #ifndef ZSTDLIB_HIDDEN
35*01826a49SYabin Cui #  if defined(__GNUC__) && (__GNUC__ >= 4) && !defined(__MINGW32__)
36*01826a49SYabin Cui #    define ZSTDLIB_HIDDEN __attribute__ ((visibility ("hidden")))
37*01826a49SYabin Cui #  else
38*01826a49SYabin Cui #    define ZSTDLIB_HIDDEN
39*01826a49SYabin Cui #  endif
40*01826a49SYabin Cui #endif
41*01826a49SYabin Cui 
42*01826a49SYabin Cui #if defined(ZSTD_DLL_EXPORT) && (ZSTD_DLL_EXPORT==1)
43*01826a49SYabin Cui #  define ZSTDLIB_API __declspec(dllexport) ZSTDLIB_VISIBLE
44*01826a49SYabin Cui #elif defined(ZSTD_DLL_IMPORT) && (ZSTD_DLL_IMPORT==1)
45*01826a49SYabin Cui #  define ZSTDLIB_API __declspec(dllimport) ZSTDLIB_VISIBLE /* It isn't required but allows to generate better code, saving a function pointer load from the IAT and an indirect jump.*/
46*01826a49SYabin Cui #else
47*01826a49SYabin Cui #  define ZSTDLIB_API ZSTDLIB_VISIBLE
48*01826a49SYabin Cui #endif
49*01826a49SYabin Cui 
50*01826a49SYabin Cui /* Deprecation warnings :
51*01826a49SYabin Cui  * Should these warnings be a problem, it is generally possible to disable them,
52*01826a49SYabin Cui  * typically with -Wno-deprecated-declarations for gcc or _CRT_SECURE_NO_WARNINGS in Visual.
53*01826a49SYabin Cui  * Otherwise, it's also possible to define ZSTD_DISABLE_DEPRECATE_WARNINGS.
54*01826a49SYabin Cui  */
55*01826a49SYabin Cui #ifdef ZSTD_DISABLE_DEPRECATE_WARNINGS
56*01826a49SYabin Cui #  define ZSTD_DEPRECATED(message) /* disable deprecation warnings */
57*01826a49SYabin Cui #else
58*01826a49SYabin Cui #  if defined (__cplusplus) && (__cplusplus >= 201402) /* C++14 or greater */
59*01826a49SYabin Cui #    define ZSTD_DEPRECATED(message) [[deprecated(message)]]
60*01826a49SYabin Cui #  elif (defined(GNUC) && (GNUC > 4 || (GNUC == 4 && GNUC_MINOR >= 5))) || defined(__clang__)
61*01826a49SYabin Cui #    define ZSTD_DEPRECATED(message) __attribute__((deprecated(message)))
62*01826a49SYabin Cui #  elif defined(__GNUC__) && (__GNUC__ >= 3)
63*01826a49SYabin Cui #    define ZSTD_DEPRECATED(message) __attribute__((deprecated))
64*01826a49SYabin Cui #  elif defined(_MSC_VER)
65*01826a49SYabin Cui #    define ZSTD_DEPRECATED(message) __declspec(deprecated(message))
66*01826a49SYabin Cui #  else
67*01826a49SYabin Cui #    pragma message("WARNING: You need to implement ZSTD_DEPRECATED for this compiler")
68*01826a49SYabin Cui #    define ZSTD_DEPRECATED(message)
69*01826a49SYabin Cui #  endif
70*01826a49SYabin Cui #endif /* ZSTD_DISABLE_DEPRECATE_WARNINGS */
71*01826a49SYabin Cui 
72*01826a49SYabin Cui 
73*01826a49SYabin Cui /*******************************************************************************
74*01826a49SYabin Cui   Introduction
75*01826a49SYabin Cui 
76*01826a49SYabin Cui   zstd, short for Zstandard, is a fast lossless compression algorithm, targeting
77*01826a49SYabin Cui   real-time compression scenarios at zlib-level and better compression ratios.
78*01826a49SYabin Cui   The zstd compression library provides in-memory compression and decompression
79*01826a49SYabin Cui   functions.
80*01826a49SYabin Cui 
81*01826a49SYabin Cui   The library supports regular compression levels from 1 up to ZSTD_maxCLevel(),
82*01826a49SYabin Cui   which is currently 22. Levels >= 20, labeled `--ultra`, should be used with
83*01826a49SYabin Cui   caution, as they require more memory. The library also offers negative
84*01826a49SYabin Cui   compression levels, which extend the range of speed vs. ratio preferences.
85*01826a49SYabin Cui   The lower the level, the faster the speed (at the cost of compression).
86*01826a49SYabin Cui 
87*01826a49SYabin Cui   Compression can be done in:
88*01826a49SYabin Cui     - a single step (described as Simple API)
89*01826a49SYabin Cui     - a single step, reusing a context (described as Explicit context)
90*01826a49SYabin Cui     - unbounded multiple steps (described as Streaming compression)
91*01826a49SYabin Cui 
92*01826a49SYabin Cui   The compression ratio achievable on small data can be highly improved using
93*01826a49SYabin Cui   a dictionary. Dictionary compression can be performed in:
94*01826a49SYabin Cui     - a single step (described as Simple dictionary API)
95*01826a49SYabin Cui     - a single step, reusing a dictionary (described as Bulk-processing
96*01826a49SYabin Cui       dictionary API)
97*01826a49SYabin Cui 
98*01826a49SYabin Cui   Advanced experimental functions can be accessed using
99*01826a49SYabin Cui   `#define ZSTD_STATIC_LINKING_ONLY` before including zstd.h.
100*01826a49SYabin Cui 
101*01826a49SYabin Cui   Advanced experimental APIs should never be used with a dynamically-linked
102*01826a49SYabin Cui   library. They are not "stable"; their definitions or signatures may change in
103*01826a49SYabin Cui   the future. Only static linking is allowed.
104*01826a49SYabin Cui *******************************************************************************/
105*01826a49SYabin Cui 
106*01826a49SYabin Cui /*------   Version   ------*/
107*01826a49SYabin Cui #define ZSTD_VERSION_MAJOR    1
108*01826a49SYabin Cui #define ZSTD_VERSION_MINOR    5
109*01826a49SYabin Cui #define ZSTD_VERSION_RELEASE  6
110*01826a49SYabin Cui #define ZSTD_VERSION_NUMBER  (ZSTD_VERSION_MAJOR *100*100 + ZSTD_VERSION_MINOR *100 + ZSTD_VERSION_RELEASE)
111*01826a49SYabin Cui 
112*01826a49SYabin Cui /*! ZSTD_versionNumber() :
113*01826a49SYabin Cui  *  Return runtime library version, the value is (MAJOR*100*100 + MINOR*100 + RELEASE). */
114*01826a49SYabin Cui ZSTDLIB_API unsigned ZSTD_versionNumber(void);
115*01826a49SYabin Cui 
116*01826a49SYabin Cui #define ZSTD_LIB_VERSION ZSTD_VERSION_MAJOR.ZSTD_VERSION_MINOR.ZSTD_VERSION_RELEASE
117*01826a49SYabin Cui #define ZSTD_QUOTE(str) #str
118*01826a49SYabin Cui #define ZSTD_EXPAND_AND_QUOTE(str) ZSTD_QUOTE(str)
119*01826a49SYabin Cui #define ZSTD_VERSION_STRING ZSTD_EXPAND_AND_QUOTE(ZSTD_LIB_VERSION)
120*01826a49SYabin Cui 
121*01826a49SYabin Cui /*! ZSTD_versionString() :
122*01826a49SYabin Cui  *  Return runtime library version, like "1.4.5". Requires v1.3.0+. */
123*01826a49SYabin Cui ZSTDLIB_API const char* ZSTD_versionString(void);
124*01826a49SYabin Cui 
125*01826a49SYabin Cui /* *************************************
126*01826a49SYabin Cui  *  Default constant
127*01826a49SYabin Cui  ***************************************/
128*01826a49SYabin Cui #ifndef ZSTD_CLEVEL_DEFAULT
129*01826a49SYabin Cui #  define ZSTD_CLEVEL_DEFAULT 3
130*01826a49SYabin Cui #endif
131*01826a49SYabin Cui 
132*01826a49SYabin Cui /* *************************************
133*01826a49SYabin Cui  *  Constants
134*01826a49SYabin Cui  ***************************************/
135*01826a49SYabin Cui 
136*01826a49SYabin Cui /* All magic numbers are supposed read/written to/from files/memory using little-endian convention */
137*01826a49SYabin Cui #define ZSTD_MAGICNUMBER            0xFD2FB528    /* valid since v0.8.0 */
138*01826a49SYabin Cui #define ZSTD_MAGIC_DICTIONARY       0xEC30A437    /* valid since v0.7.0 */
139*01826a49SYabin Cui #define ZSTD_MAGIC_SKIPPABLE_START  0x184D2A50    /* all 16 values, from 0x184D2A50 to 0x184D2A5F, signal the beginning of a skippable frame */
140*01826a49SYabin Cui #define ZSTD_MAGIC_SKIPPABLE_MASK   0xFFFFFFF0
141*01826a49SYabin Cui 
142*01826a49SYabin Cui #define ZSTD_BLOCKSIZELOG_MAX  17
143*01826a49SYabin Cui #define ZSTD_BLOCKSIZE_MAX     (1<<ZSTD_BLOCKSIZELOG_MAX)
144*01826a49SYabin Cui 
145*01826a49SYabin Cui 
146*01826a49SYabin Cui /***************************************
147*01826a49SYabin Cui *  Simple API
148*01826a49SYabin Cui ***************************************/
149*01826a49SYabin Cui /*! ZSTD_compress() :
150*01826a49SYabin Cui  *  Compresses `src` content as a single zstd compressed frame into already allocated `dst`.
151*01826a49SYabin Cui  *  NOTE: Providing `dstCapacity >= ZSTD_compressBound(srcSize)` guarantees that zstd will have
152*01826a49SYabin Cui  *        enough space to successfully compress the data.
153*01826a49SYabin Cui  *  @return : compressed size written into `dst` (<= `dstCapacity),
154*01826a49SYabin Cui  *            or an error code if it fails (which can be tested using ZSTD_isError()). */
155*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_compress( void* dst, size_t dstCapacity,
156*01826a49SYabin Cui                             const void* src, size_t srcSize,
157*01826a49SYabin Cui                                   int compressionLevel);
158*01826a49SYabin Cui 
159*01826a49SYabin Cui /*! ZSTD_decompress() :
160*01826a49SYabin Cui  *  `compressedSize` : must be the _exact_ size of some number of compressed and/or skippable frames.
161*01826a49SYabin Cui  *  `dstCapacity` is an upper bound of originalSize to regenerate.
162*01826a49SYabin Cui  *  If user cannot imply a maximum upper bound, it's better to use streaming mode to decompress data.
163*01826a49SYabin Cui  *  @return : the number of bytes decompressed into `dst` (<= `dstCapacity`),
164*01826a49SYabin Cui  *            or an errorCode if it fails (which can be tested using ZSTD_isError()). */
165*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_decompress( void* dst, size_t dstCapacity,
166*01826a49SYabin Cui                               const void* src, size_t compressedSize);
167*01826a49SYabin Cui 
168*01826a49SYabin Cui /*! ZSTD_getFrameContentSize() : requires v1.3.0+
169*01826a49SYabin Cui  *  `src` should point to the start of a ZSTD encoded frame.
170*01826a49SYabin Cui  *  `srcSize` must be at least as large as the frame header.
171*01826a49SYabin Cui  *            hint : any size >= `ZSTD_frameHeaderSize_max` is large enough.
172*01826a49SYabin Cui  *  @return : - decompressed size of `src` frame content, if known
173*01826a49SYabin Cui  *            - ZSTD_CONTENTSIZE_UNKNOWN if the size cannot be determined
174*01826a49SYabin Cui  *            - ZSTD_CONTENTSIZE_ERROR if an error occurred (e.g. invalid magic number, srcSize too small)
175*01826a49SYabin Cui  *   note 1 : a 0 return value means the frame is valid but "empty".
176*01826a49SYabin Cui  *   note 2 : decompressed size is an optional field, it may not be present, typically in streaming mode.
177*01826a49SYabin Cui  *            When `return==ZSTD_CONTENTSIZE_UNKNOWN`, data to decompress could be any size.
178*01826a49SYabin Cui  *            In which case, it's necessary to use streaming mode to decompress data.
179*01826a49SYabin Cui  *            Optionally, application can rely on some implicit limit,
180*01826a49SYabin Cui  *            as ZSTD_decompress() only needs an upper bound of decompressed size.
181*01826a49SYabin Cui  *            (For example, data could be necessarily cut into blocks <= 16 KB).
182*01826a49SYabin Cui  *   note 3 : decompressed size is always present when compression is completed using single-pass functions,
183*01826a49SYabin Cui  *            such as ZSTD_compress(), ZSTD_compressCCtx() ZSTD_compress_usingDict() or ZSTD_compress_usingCDict().
184*01826a49SYabin Cui  *   note 4 : decompressed size can be very large (64-bits value),
185*01826a49SYabin Cui  *            potentially larger than what local system can handle as a single memory segment.
186*01826a49SYabin Cui  *            In which case, it's necessary to use streaming mode to decompress data.
187*01826a49SYabin Cui  *   note 5 : If source is untrusted, decompressed size could be wrong or intentionally modified.
188*01826a49SYabin Cui  *            Always ensure return value fits within application's authorized limits.
189*01826a49SYabin Cui  *            Each application can set its own limits.
190*01826a49SYabin Cui  *   note 6 : This function replaces ZSTD_getDecompressedSize() */
191*01826a49SYabin Cui #define ZSTD_CONTENTSIZE_UNKNOWN (0ULL - 1)
192*01826a49SYabin Cui #define ZSTD_CONTENTSIZE_ERROR   (0ULL - 2)
193*01826a49SYabin Cui ZSTDLIB_API unsigned long long ZSTD_getFrameContentSize(const void *src, size_t srcSize);
194*01826a49SYabin Cui 
195*01826a49SYabin Cui /*! ZSTD_getDecompressedSize() :
196*01826a49SYabin Cui  *  NOTE: This function is now obsolete, in favor of ZSTD_getFrameContentSize().
197*01826a49SYabin Cui  *  Both functions work the same way, but ZSTD_getDecompressedSize() blends
198*01826a49SYabin Cui  *  "empty", "unknown" and "error" results to the same return value (0),
199*01826a49SYabin Cui  *  while ZSTD_getFrameContentSize() gives them separate return values.
200*01826a49SYabin Cui  * @return : decompressed size of `src` frame content _if known and not empty_, 0 otherwise. */
201*01826a49SYabin Cui ZSTD_DEPRECATED("Replaced by ZSTD_getFrameContentSize")
202*01826a49SYabin Cui ZSTDLIB_API
203*01826a49SYabin Cui unsigned long long ZSTD_getDecompressedSize(const void* src, size_t srcSize);
204*01826a49SYabin Cui 
205*01826a49SYabin Cui /*! ZSTD_findFrameCompressedSize() : Requires v1.4.0+
206*01826a49SYabin Cui  * `src` should point to the start of a ZSTD frame or skippable frame.
207*01826a49SYabin Cui  * `srcSize` must be >= first frame size
208*01826a49SYabin Cui  * @return : the compressed size of the first frame starting at `src`,
209*01826a49SYabin Cui  *           suitable to pass as `srcSize` to `ZSTD_decompress` or similar,
210*01826a49SYabin Cui  *        or an error code if input is invalid */
211*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_findFrameCompressedSize(const void* src, size_t srcSize);
212*01826a49SYabin Cui 
213*01826a49SYabin Cui 
214*01826a49SYabin Cui /*======  Helper functions  ======*/
215*01826a49SYabin Cui /* ZSTD_compressBound() :
216*01826a49SYabin Cui  * maximum compressed size in worst case single-pass scenario.
217*01826a49SYabin Cui  * When invoking `ZSTD_compress()` or any other one-pass compression function,
218*01826a49SYabin Cui  * it's recommended to provide @dstCapacity >= ZSTD_compressBound(srcSize)
219*01826a49SYabin Cui  * as it eliminates one potential failure scenario,
220*01826a49SYabin Cui  * aka not enough room in dst buffer to write the compressed frame.
221*01826a49SYabin Cui  * Note : ZSTD_compressBound() itself can fail, if @srcSize > ZSTD_MAX_INPUT_SIZE .
222*01826a49SYabin Cui  *        In which case, ZSTD_compressBound() will return an error code
223*01826a49SYabin Cui  *        which can be tested using ZSTD_isError().
224*01826a49SYabin Cui  *
225*01826a49SYabin Cui  * ZSTD_COMPRESSBOUND() :
226*01826a49SYabin Cui  * same as ZSTD_compressBound(), but as a macro.
227*01826a49SYabin Cui  * It can be used to produce constants, which can be useful for static allocation,
228*01826a49SYabin Cui  * for example to size a static array on stack.
229*01826a49SYabin Cui  * Will produce constant value 0 if srcSize too large.
230*01826a49SYabin Cui  */
231*01826a49SYabin Cui #define ZSTD_MAX_INPUT_SIZE ((sizeof(size_t)==8) ? 0xFF00FF00FF00FF00ULL : 0xFF00FF00U)
232*01826a49SYabin Cui #define ZSTD_COMPRESSBOUND(srcSize)   (((size_t)(srcSize) >= ZSTD_MAX_INPUT_SIZE) ? 0 : (srcSize) + ((srcSize)>>8) + (((srcSize) < (128<<10)) ? (((128<<10) - (srcSize)) >> 11) /* margin, from 64 to 0 */ : 0))  /* this formula ensures that bound(A) + bound(B) <= bound(A+B) as long as A and B >= 128 KB */
233*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_compressBound(size_t srcSize); /*!< maximum compressed size in worst case single-pass scenario */
234*01826a49SYabin Cui /* ZSTD_isError() :
235*01826a49SYabin Cui  * Most ZSTD_* functions returning a size_t value can be tested for error,
236*01826a49SYabin Cui  * using ZSTD_isError().
237*01826a49SYabin Cui  * @return 1 if error, 0 otherwise
238*01826a49SYabin Cui  */
239*01826a49SYabin Cui ZSTDLIB_API unsigned    ZSTD_isError(size_t code);          /*!< tells if a `size_t` function result is an error code */
240*01826a49SYabin Cui ZSTDLIB_API const char* ZSTD_getErrorName(size_t code);     /*!< provides readable string from an error code */
241*01826a49SYabin Cui ZSTDLIB_API int         ZSTD_minCLevel(void);               /*!< minimum negative compression level allowed, requires v1.4.0+ */
242*01826a49SYabin Cui ZSTDLIB_API int         ZSTD_maxCLevel(void);               /*!< maximum compression level available */
243*01826a49SYabin Cui ZSTDLIB_API int         ZSTD_defaultCLevel(void);           /*!< default compression level, specified by ZSTD_CLEVEL_DEFAULT, requires v1.5.0+ */
244*01826a49SYabin Cui 
245*01826a49SYabin Cui 
246*01826a49SYabin Cui /***************************************
247*01826a49SYabin Cui *  Explicit context
248*01826a49SYabin Cui ***************************************/
249*01826a49SYabin Cui /*= Compression context
250*01826a49SYabin Cui  *  When compressing many times,
251*01826a49SYabin Cui  *  it is recommended to allocate a context just once,
252*01826a49SYabin Cui  *  and reuse it for each successive compression operation.
253*01826a49SYabin Cui  *  This will make workload friendlier for system's memory.
254*01826a49SYabin Cui  *  Note : re-using context is just a speed / resource optimization.
255*01826a49SYabin Cui  *         It doesn't change the compression ratio, which remains identical.
256*01826a49SYabin Cui  *  Note 2 : In multi-threaded environments,
257*01826a49SYabin Cui  *         use one different context per thread for parallel execution.
258*01826a49SYabin Cui  */
259*01826a49SYabin Cui typedef struct ZSTD_CCtx_s ZSTD_CCtx;
260*01826a49SYabin Cui ZSTDLIB_API ZSTD_CCtx* ZSTD_createCCtx(void);
261*01826a49SYabin Cui ZSTDLIB_API size_t     ZSTD_freeCCtx(ZSTD_CCtx* cctx);  /* accept NULL pointer */
262*01826a49SYabin Cui 
263*01826a49SYabin Cui /*! ZSTD_compressCCtx() :
264*01826a49SYabin Cui  *  Same as ZSTD_compress(), using an explicit ZSTD_CCtx.
265*01826a49SYabin Cui  *  Important : in order to mirror `ZSTD_compress()` behavior,
266*01826a49SYabin Cui  *  this function compresses at the requested compression level,
267*01826a49SYabin Cui  *  __ignoring any other advanced parameter__ .
268*01826a49SYabin Cui  *  If any advanced parameter was set using the advanced API,
269*01826a49SYabin Cui  *  they will all be reset. Only `compressionLevel` remains.
270*01826a49SYabin Cui  */
271*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_compressCCtx(ZSTD_CCtx* cctx,
272*01826a49SYabin Cui                                      void* dst, size_t dstCapacity,
273*01826a49SYabin Cui                                const void* src, size_t srcSize,
274*01826a49SYabin Cui                                      int compressionLevel);
275*01826a49SYabin Cui 
276*01826a49SYabin Cui /*= Decompression context
277*01826a49SYabin Cui  *  When decompressing many times,
278*01826a49SYabin Cui  *  it is recommended to allocate a context only once,
279*01826a49SYabin Cui  *  and reuse it for each successive compression operation.
280*01826a49SYabin Cui  *  This will make workload friendlier for system's memory.
281*01826a49SYabin Cui  *  Use one context per thread for parallel execution. */
282*01826a49SYabin Cui typedef struct ZSTD_DCtx_s ZSTD_DCtx;
283*01826a49SYabin Cui ZSTDLIB_API ZSTD_DCtx* ZSTD_createDCtx(void);
284*01826a49SYabin Cui ZSTDLIB_API size_t     ZSTD_freeDCtx(ZSTD_DCtx* dctx);  /* accept NULL pointer */
285*01826a49SYabin Cui 
286*01826a49SYabin Cui /*! ZSTD_decompressDCtx() :
287*01826a49SYabin Cui  *  Same as ZSTD_decompress(),
288*01826a49SYabin Cui  *  requires an allocated ZSTD_DCtx.
289*01826a49SYabin Cui  *  Compatible with sticky parameters (see below).
290*01826a49SYabin Cui  */
291*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_decompressDCtx(ZSTD_DCtx* dctx,
292*01826a49SYabin Cui                                        void* dst, size_t dstCapacity,
293*01826a49SYabin Cui                                  const void* src, size_t srcSize);
294*01826a49SYabin Cui 
295*01826a49SYabin Cui 
296*01826a49SYabin Cui /*********************************************
297*01826a49SYabin Cui *  Advanced compression API (Requires v1.4.0+)
298*01826a49SYabin Cui **********************************************/
299*01826a49SYabin Cui 
300*01826a49SYabin Cui /* API design :
301*01826a49SYabin Cui  *   Parameters are pushed one by one into an existing context,
302*01826a49SYabin Cui  *   using ZSTD_CCtx_set*() functions.
303*01826a49SYabin Cui  *   Pushed parameters are sticky : they are valid for next compressed frame, and any subsequent frame.
304*01826a49SYabin Cui  *   "sticky" parameters are applicable to `ZSTD_compress2()` and `ZSTD_compressStream*()` !
305*01826a49SYabin Cui  *   __They do not apply to one-shot variants such as ZSTD_compressCCtx()__ .
306*01826a49SYabin Cui  *
307*01826a49SYabin Cui  *   It's possible to reset all parameters to "default" using ZSTD_CCtx_reset().
308*01826a49SYabin Cui  *
309*01826a49SYabin Cui  *   This API supersedes all other "advanced" API entry points in the experimental section.
310*01826a49SYabin Cui  *   In the future, we expect to remove API entry points from experimental which are redundant with this API.
311*01826a49SYabin Cui  */
312*01826a49SYabin Cui 
313*01826a49SYabin Cui 
314*01826a49SYabin Cui /* Compression strategies, listed from fastest to strongest */
315*01826a49SYabin Cui typedef enum { ZSTD_fast=1,
316*01826a49SYabin Cui                ZSTD_dfast=2,
317*01826a49SYabin Cui                ZSTD_greedy=3,
318*01826a49SYabin Cui                ZSTD_lazy=4,
319*01826a49SYabin Cui                ZSTD_lazy2=5,
320*01826a49SYabin Cui                ZSTD_btlazy2=6,
321*01826a49SYabin Cui                ZSTD_btopt=7,
322*01826a49SYabin Cui                ZSTD_btultra=8,
323*01826a49SYabin Cui                ZSTD_btultra2=9
324*01826a49SYabin Cui                /* note : new strategies _might_ be added in the future.
325*01826a49SYabin Cui                          Only the order (from fast to strong) is guaranteed */
326*01826a49SYabin Cui } ZSTD_strategy;
327*01826a49SYabin Cui 
328*01826a49SYabin Cui typedef enum {
329*01826a49SYabin Cui 
330*01826a49SYabin Cui     /* compression parameters
331*01826a49SYabin Cui      * Note: When compressing with a ZSTD_CDict these parameters are superseded
332*01826a49SYabin Cui      * by the parameters used to construct the ZSTD_CDict.
333*01826a49SYabin Cui      * See ZSTD_CCtx_refCDict() for more info (superseded-by-cdict). */
334*01826a49SYabin Cui     ZSTD_c_compressionLevel=100, /* Set compression parameters according to pre-defined cLevel table.
335*01826a49SYabin Cui                               * Note that exact compression parameters are dynamically determined,
336*01826a49SYabin Cui                               * depending on both compression level and srcSize (when known).
337*01826a49SYabin Cui                               * Default level is ZSTD_CLEVEL_DEFAULT==3.
338*01826a49SYabin Cui                               * Special: value 0 means default, which is controlled by ZSTD_CLEVEL_DEFAULT.
339*01826a49SYabin Cui                               * Note 1 : it's possible to pass a negative compression level.
340*01826a49SYabin Cui                               * Note 2 : setting a level does not automatically set all other compression parameters
341*01826a49SYabin Cui                               *   to default. Setting this will however eventually dynamically impact the compression
342*01826a49SYabin Cui                               *   parameters which have not been manually set. The manually set
343*01826a49SYabin Cui                               *   ones will 'stick'. */
344*01826a49SYabin Cui     /* Advanced compression parameters :
345*01826a49SYabin Cui      * It's possible to pin down compression parameters to some specific values.
346*01826a49SYabin Cui      * In which case, these values are no longer dynamically selected by the compressor */
347*01826a49SYabin Cui     ZSTD_c_windowLog=101,    /* Maximum allowed back-reference distance, expressed as power of 2.
348*01826a49SYabin Cui                               * This will set a memory budget for streaming decompression,
349*01826a49SYabin Cui                               * with larger values requiring more memory
350*01826a49SYabin Cui                               * and typically compressing more.
351*01826a49SYabin Cui                               * Must be clamped between ZSTD_WINDOWLOG_MIN and ZSTD_WINDOWLOG_MAX.
352*01826a49SYabin Cui                               * Special: value 0 means "use default windowLog".
353*01826a49SYabin Cui                               * Note: Using a windowLog greater than ZSTD_WINDOWLOG_LIMIT_DEFAULT
354*01826a49SYabin Cui                               *       requires explicitly allowing such size at streaming decompression stage. */
355*01826a49SYabin Cui     ZSTD_c_hashLog=102,      /* Size of the initial probe table, as a power of 2.
356*01826a49SYabin Cui                               * Resulting memory usage is (1 << (hashLog+2)).
357*01826a49SYabin Cui                               * Must be clamped between ZSTD_HASHLOG_MIN and ZSTD_HASHLOG_MAX.
358*01826a49SYabin Cui                               * Larger tables improve compression ratio of strategies <= dFast,
359*01826a49SYabin Cui                               * and improve speed of strategies > dFast.
360*01826a49SYabin Cui                               * Special: value 0 means "use default hashLog". */
361*01826a49SYabin Cui     ZSTD_c_chainLog=103,     /* Size of the multi-probe search table, as a power of 2.
362*01826a49SYabin Cui                               * Resulting memory usage is (1 << (chainLog+2)).
363*01826a49SYabin Cui                               * Must be clamped between ZSTD_CHAINLOG_MIN and ZSTD_CHAINLOG_MAX.
364*01826a49SYabin Cui                               * Larger tables result in better and slower compression.
365*01826a49SYabin Cui                               * This parameter is useless for "fast" strategy.
366*01826a49SYabin Cui                               * It's still useful when using "dfast" strategy,
367*01826a49SYabin Cui                               * in which case it defines a secondary probe table.
368*01826a49SYabin Cui                               * Special: value 0 means "use default chainLog". */
369*01826a49SYabin Cui     ZSTD_c_searchLog=104,    /* Number of search attempts, as a power of 2.
370*01826a49SYabin Cui                               * More attempts result in better and slower compression.
371*01826a49SYabin Cui                               * This parameter is useless for "fast" and "dFast" strategies.
372*01826a49SYabin Cui                               * Special: value 0 means "use default searchLog". */
373*01826a49SYabin Cui     ZSTD_c_minMatch=105,     /* Minimum size of searched matches.
374*01826a49SYabin Cui                               * Note that Zstandard can still find matches of smaller size,
375*01826a49SYabin Cui                               * it just tweaks its search algorithm to look for this size and larger.
376*01826a49SYabin Cui                               * Larger values increase compression and decompression speed, but decrease ratio.
377*01826a49SYabin Cui                               * Must be clamped between ZSTD_MINMATCH_MIN and ZSTD_MINMATCH_MAX.
378*01826a49SYabin Cui                               * Note that currently, for all strategies < btopt, effective minimum is 4.
379*01826a49SYabin Cui                               *                    , for all strategies > fast, effective maximum is 6.
380*01826a49SYabin Cui                               * Special: value 0 means "use default minMatchLength". */
381*01826a49SYabin Cui     ZSTD_c_targetLength=106, /* Impact of this field depends on strategy.
382*01826a49SYabin Cui                               * For strategies btopt, btultra & btultra2:
383*01826a49SYabin Cui                               *     Length of Match considered "good enough" to stop search.
384*01826a49SYabin Cui                               *     Larger values make compression stronger, and slower.
385*01826a49SYabin Cui                               * For strategy fast:
386*01826a49SYabin Cui                               *     Distance between match sampling.
387*01826a49SYabin Cui                               *     Larger values make compression faster, and weaker.
388*01826a49SYabin Cui                               * Special: value 0 means "use default targetLength". */
389*01826a49SYabin Cui     ZSTD_c_strategy=107,     /* See ZSTD_strategy enum definition.
390*01826a49SYabin Cui                               * The higher the value of selected strategy, the more complex it is,
391*01826a49SYabin Cui                               * resulting in stronger and slower compression.
392*01826a49SYabin Cui                               * Special: value 0 means "use default strategy". */
393*01826a49SYabin Cui 
394*01826a49SYabin Cui     ZSTD_c_targetCBlockSize=130, /* v1.5.6+
395*01826a49SYabin Cui                                   * Attempts to fit compressed block size into approximatively targetCBlockSize.
396*01826a49SYabin Cui                                   * Bound by ZSTD_TARGETCBLOCKSIZE_MIN and ZSTD_TARGETCBLOCKSIZE_MAX.
397*01826a49SYabin Cui                                   * Note that it's not a guarantee, just a convergence target (default:0).
398*01826a49SYabin Cui                                   * No target when targetCBlockSize == 0.
399*01826a49SYabin Cui                                   * This is helpful in low bandwidth streaming environments to improve end-to-end latency,
400*01826a49SYabin Cui                                   * when a client can make use of partial documents (a prominent example being Chrome).
401*01826a49SYabin Cui                                   * Note: this parameter is stable since v1.5.6.
402*01826a49SYabin Cui                                   * It was present as an experimental parameter in earlier versions,
403*01826a49SYabin Cui                                   * but it's not recommended using it with earlier library versions
404*01826a49SYabin Cui                                   * due to massive performance regressions.
405*01826a49SYabin Cui                                   */
406*01826a49SYabin Cui     /* LDM mode parameters */
407*01826a49SYabin Cui     ZSTD_c_enableLongDistanceMatching=160, /* Enable long distance matching.
408*01826a49SYabin Cui                                      * This parameter is designed to improve compression ratio
409*01826a49SYabin Cui                                      * for large inputs, by finding large matches at long distance.
410*01826a49SYabin Cui                                      * It increases memory usage and window size.
411*01826a49SYabin Cui                                      * Note: enabling this parameter increases default ZSTD_c_windowLog to 128 MB
412*01826a49SYabin Cui                                      * except when expressly set to a different value.
413*01826a49SYabin Cui                                      * Note: will be enabled by default if ZSTD_c_windowLog >= 128 MB and
414*01826a49SYabin Cui                                      * compression strategy >= ZSTD_btopt (== compression level 16+) */
415*01826a49SYabin Cui     ZSTD_c_ldmHashLog=161,   /* Size of the table for long distance matching, as a power of 2.
416*01826a49SYabin Cui                               * Larger values increase memory usage and compression ratio,
417*01826a49SYabin Cui                               * but decrease compression speed.
418*01826a49SYabin Cui                               * Must be clamped between ZSTD_HASHLOG_MIN and ZSTD_HASHLOG_MAX
419*01826a49SYabin Cui                               * default: windowlog - 7.
420*01826a49SYabin Cui                               * Special: value 0 means "automatically determine hashlog". */
421*01826a49SYabin Cui     ZSTD_c_ldmMinMatch=162,  /* Minimum match size for long distance matcher.
422*01826a49SYabin Cui                               * Larger/too small values usually decrease compression ratio.
423*01826a49SYabin Cui                               * Must be clamped between ZSTD_LDM_MINMATCH_MIN and ZSTD_LDM_MINMATCH_MAX.
424*01826a49SYabin Cui                               * Special: value 0 means "use default value" (default: 64). */
425*01826a49SYabin Cui     ZSTD_c_ldmBucketSizeLog=163, /* Log size of each bucket in the LDM hash table for collision resolution.
426*01826a49SYabin Cui                               * Larger values improve collision resolution but decrease compression speed.
427*01826a49SYabin Cui                               * The maximum value is ZSTD_LDM_BUCKETSIZELOG_MAX.
428*01826a49SYabin Cui                               * Special: value 0 means "use default value" (default: 3). */
429*01826a49SYabin Cui     ZSTD_c_ldmHashRateLog=164, /* Frequency of inserting/looking up entries into the LDM hash table.
430*01826a49SYabin Cui                               * Must be clamped between 0 and (ZSTD_WINDOWLOG_MAX - ZSTD_HASHLOG_MIN).
431*01826a49SYabin Cui                               * Default is MAX(0, (windowLog - ldmHashLog)), optimizing hash table usage.
432*01826a49SYabin Cui                               * Larger values improve compression speed.
433*01826a49SYabin Cui                               * Deviating far from default value will likely result in a compression ratio decrease.
434*01826a49SYabin Cui                               * Special: value 0 means "automatically determine hashRateLog". */
435*01826a49SYabin Cui 
436*01826a49SYabin Cui     /* frame parameters */
437*01826a49SYabin Cui     ZSTD_c_contentSizeFlag=200, /* Content size will be written into frame header _whenever known_ (default:1)
438*01826a49SYabin Cui                               * Content size must be known at the beginning of compression.
439*01826a49SYabin Cui                               * This is automatically the case when using ZSTD_compress2(),
440*01826a49SYabin Cui                               * For streaming scenarios, content size must be provided with ZSTD_CCtx_setPledgedSrcSize() */
441*01826a49SYabin Cui     ZSTD_c_checksumFlag=201, /* A 32-bits checksum of content is written at end of frame (default:0) */
442*01826a49SYabin Cui     ZSTD_c_dictIDFlag=202,   /* When applicable, dictionary's ID is written into frame header (default:1) */
443*01826a49SYabin Cui 
444*01826a49SYabin Cui     /* multi-threading parameters */
445*01826a49SYabin Cui     /* These parameters are only active if multi-threading is enabled (compiled with build macro ZSTD_MULTITHREAD).
446*01826a49SYabin Cui      * Otherwise, trying to set any other value than default (0) will be a no-op and return an error.
447*01826a49SYabin Cui      * In a situation where it's unknown if the linked library supports multi-threading or not,
448*01826a49SYabin Cui      * setting ZSTD_c_nbWorkers to any value >= 1 and consulting the return value provides a quick way to check this property.
449*01826a49SYabin Cui      */
450*01826a49SYabin Cui     ZSTD_c_nbWorkers=400,    /* Select how many threads will be spawned to compress in parallel.
451*01826a49SYabin Cui                               * When nbWorkers >= 1, triggers asynchronous mode when invoking ZSTD_compressStream*() :
452*01826a49SYabin Cui                               * ZSTD_compressStream*() consumes input and flush output if possible, but immediately gives back control to caller,
453*01826a49SYabin Cui                               * while compression is performed in parallel, within worker thread(s).
454*01826a49SYabin Cui                               * (note : a strong exception to this rule is when first invocation of ZSTD_compressStream2() sets ZSTD_e_end :
455*01826a49SYabin Cui                               *  in which case, ZSTD_compressStream2() delegates to ZSTD_compress2(), which is always a blocking call).
456*01826a49SYabin Cui                               * More workers improve speed, but also increase memory usage.
457*01826a49SYabin Cui                               * Default value is `0`, aka "single-threaded mode" : no worker is spawned,
458*01826a49SYabin Cui                               * compression is performed inside Caller's thread, and all invocations are blocking */
459*01826a49SYabin Cui     ZSTD_c_jobSize=401,      /* Size of a compression job. This value is enforced only when nbWorkers >= 1.
460*01826a49SYabin Cui                               * Each compression job is completed in parallel, so this value can indirectly impact the nb of active threads.
461*01826a49SYabin Cui                               * 0 means default, which is dynamically determined based on compression parameters.
462*01826a49SYabin Cui                               * Job size must be a minimum of overlap size, or ZSTDMT_JOBSIZE_MIN (= 512 KB), whichever is largest.
463*01826a49SYabin Cui                               * The minimum size is automatically and transparently enforced. */
464*01826a49SYabin Cui     ZSTD_c_overlapLog=402,   /* Control the overlap size, as a fraction of window size.
465*01826a49SYabin Cui                               * The overlap size is an amount of data reloaded from previous job at the beginning of a new job.
466*01826a49SYabin Cui                               * It helps preserve compression ratio, while each job is compressed in parallel.
467*01826a49SYabin Cui                               * This value is enforced only when nbWorkers >= 1.
468*01826a49SYabin Cui                               * Larger values increase compression ratio, but decrease speed.
469*01826a49SYabin Cui                               * Possible values range from 0 to 9 :
470*01826a49SYabin Cui                               * - 0 means "default" : value will be determined by the library, depending on strategy
471*01826a49SYabin Cui                               * - 1 means "no overlap"
472*01826a49SYabin Cui                               * - 9 means "full overlap", using a full window size.
473*01826a49SYabin Cui                               * Each intermediate rank increases/decreases load size by a factor 2 :
474*01826a49SYabin Cui                               * 9: full window;  8: w/2;  7: w/4;  6: w/8;  5:w/16;  4: w/32;  3:w/64;  2:w/128;  1:no overlap;  0:default
475*01826a49SYabin Cui                               * default value varies between 6 and 9, depending on strategy */
476*01826a49SYabin Cui 
477*01826a49SYabin Cui     /* note : additional experimental parameters are also available
478*01826a49SYabin Cui      * within the experimental section of the API.
479*01826a49SYabin Cui      * At the time of this writing, they include :
480*01826a49SYabin Cui      * ZSTD_c_rsyncable
481*01826a49SYabin Cui      * ZSTD_c_format
482*01826a49SYabin Cui      * ZSTD_c_forceMaxWindow
483*01826a49SYabin Cui      * ZSTD_c_forceAttachDict
484*01826a49SYabin Cui      * ZSTD_c_literalCompressionMode
485*01826a49SYabin Cui      * ZSTD_c_srcSizeHint
486*01826a49SYabin Cui      * ZSTD_c_enableDedicatedDictSearch
487*01826a49SYabin Cui      * ZSTD_c_stableInBuffer
488*01826a49SYabin Cui      * ZSTD_c_stableOutBuffer
489*01826a49SYabin Cui      * ZSTD_c_blockDelimiters
490*01826a49SYabin Cui      * ZSTD_c_validateSequences
491*01826a49SYabin Cui      * ZSTD_c_useBlockSplitter
492*01826a49SYabin Cui      * ZSTD_c_useRowMatchFinder
493*01826a49SYabin Cui      * ZSTD_c_prefetchCDictTables
494*01826a49SYabin Cui      * ZSTD_c_enableSeqProducerFallback
495*01826a49SYabin Cui      * ZSTD_c_maxBlockSize
496*01826a49SYabin Cui      * Because they are not stable, it's necessary to define ZSTD_STATIC_LINKING_ONLY to access them.
497*01826a49SYabin Cui      * note : never ever use experimentalParam? names directly;
498*01826a49SYabin Cui      *        also, the enums values themselves are unstable and can still change.
499*01826a49SYabin Cui      */
500*01826a49SYabin Cui      ZSTD_c_experimentalParam1=500,
501*01826a49SYabin Cui      ZSTD_c_experimentalParam2=10,
502*01826a49SYabin Cui      ZSTD_c_experimentalParam3=1000,
503*01826a49SYabin Cui      ZSTD_c_experimentalParam4=1001,
504*01826a49SYabin Cui      ZSTD_c_experimentalParam5=1002,
505*01826a49SYabin Cui      /* was ZSTD_c_experimentalParam6=1003; is now ZSTD_c_targetCBlockSize */
506*01826a49SYabin Cui      ZSTD_c_experimentalParam7=1004,
507*01826a49SYabin Cui      ZSTD_c_experimentalParam8=1005,
508*01826a49SYabin Cui      ZSTD_c_experimentalParam9=1006,
509*01826a49SYabin Cui      ZSTD_c_experimentalParam10=1007,
510*01826a49SYabin Cui      ZSTD_c_experimentalParam11=1008,
511*01826a49SYabin Cui      ZSTD_c_experimentalParam12=1009,
512*01826a49SYabin Cui      ZSTD_c_experimentalParam13=1010,
513*01826a49SYabin Cui      ZSTD_c_experimentalParam14=1011,
514*01826a49SYabin Cui      ZSTD_c_experimentalParam15=1012,
515*01826a49SYabin Cui      ZSTD_c_experimentalParam16=1013,
516*01826a49SYabin Cui      ZSTD_c_experimentalParam17=1014,
517*01826a49SYabin Cui      ZSTD_c_experimentalParam18=1015,
518*01826a49SYabin Cui      ZSTD_c_experimentalParam19=1016
519*01826a49SYabin Cui } ZSTD_cParameter;
520*01826a49SYabin Cui 
521*01826a49SYabin Cui typedef struct {
522*01826a49SYabin Cui     size_t error;
523*01826a49SYabin Cui     int lowerBound;
524*01826a49SYabin Cui     int upperBound;
525*01826a49SYabin Cui } ZSTD_bounds;
526*01826a49SYabin Cui 
527*01826a49SYabin Cui /*! ZSTD_cParam_getBounds() :
528*01826a49SYabin Cui  *  All parameters must belong to an interval with lower and upper bounds,
529*01826a49SYabin Cui  *  otherwise they will either trigger an error or be automatically clamped.
530*01826a49SYabin Cui  * @return : a structure, ZSTD_bounds, which contains
531*01826a49SYabin Cui  *         - an error status field, which must be tested using ZSTD_isError()
532*01826a49SYabin Cui  *         - lower and upper bounds, both inclusive
533*01826a49SYabin Cui  */
534*01826a49SYabin Cui ZSTDLIB_API ZSTD_bounds ZSTD_cParam_getBounds(ZSTD_cParameter cParam);
535*01826a49SYabin Cui 
536*01826a49SYabin Cui /*! ZSTD_CCtx_setParameter() :
537*01826a49SYabin Cui  *  Set one compression parameter, selected by enum ZSTD_cParameter.
538*01826a49SYabin Cui  *  All parameters have valid bounds. Bounds can be queried using ZSTD_cParam_getBounds().
539*01826a49SYabin Cui  *  Providing a value beyond bound will either clamp it, or trigger an error (depending on parameter).
540*01826a49SYabin Cui  *  Setting a parameter is generally only possible during frame initialization (before starting compression).
541*01826a49SYabin Cui  *  Exception : when using multi-threading mode (nbWorkers >= 1),
542*01826a49SYabin Cui  *              the following parameters can be updated _during_ compression (within same frame):
543*01826a49SYabin Cui  *              => compressionLevel, hashLog, chainLog, searchLog, minMatch, targetLength and strategy.
544*01826a49SYabin Cui  *              new parameters will be active for next job only (after a flush()).
545*01826a49SYabin Cui  * @return : an error code (which can be tested using ZSTD_isError()).
546*01826a49SYabin Cui  */
547*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_CCtx_setParameter(ZSTD_CCtx* cctx, ZSTD_cParameter param, int value);
548*01826a49SYabin Cui 
549*01826a49SYabin Cui /*! ZSTD_CCtx_setPledgedSrcSize() :
550*01826a49SYabin Cui  *  Total input data size to be compressed as a single frame.
551*01826a49SYabin Cui  *  Value will be written in frame header, unless if explicitly forbidden using ZSTD_c_contentSizeFlag.
552*01826a49SYabin Cui  *  This value will also be controlled at end of frame, and trigger an error if not respected.
553*01826a49SYabin Cui  * @result : 0, or an error code (which can be tested with ZSTD_isError()).
554*01826a49SYabin Cui  *  Note 1 : pledgedSrcSize==0 actually means zero, aka an empty frame.
555*01826a49SYabin Cui  *           In order to mean "unknown content size", pass constant ZSTD_CONTENTSIZE_UNKNOWN.
556*01826a49SYabin Cui  *           ZSTD_CONTENTSIZE_UNKNOWN is default value for any new frame.
557*01826a49SYabin Cui  *  Note 2 : pledgedSrcSize is only valid once, for the next frame.
558*01826a49SYabin Cui  *           It's discarded at the end of the frame, and replaced by ZSTD_CONTENTSIZE_UNKNOWN.
559*01826a49SYabin Cui  *  Note 3 : Whenever all input data is provided and consumed in a single round,
560*01826a49SYabin Cui  *           for example with ZSTD_compress2(),
561*01826a49SYabin Cui  *           or invoking immediately ZSTD_compressStream2(,,,ZSTD_e_end),
562*01826a49SYabin Cui  *           this value is automatically overridden by srcSize instead.
563*01826a49SYabin Cui  */
564*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_CCtx_setPledgedSrcSize(ZSTD_CCtx* cctx, unsigned long long pledgedSrcSize);
565*01826a49SYabin Cui 
566*01826a49SYabin Cui typedef enum {
567*01826a49SYabin Cui     ZSTD_reset_session_only = 1,
568*01826a49SYabin Cui     ZSTD_reset_parameters = 2,
569*01826a49SYabin Cui     ZSTD_reset_session_and_parameters = 3
570*01826a49SYabin Cui } ZSTD_ResetDirective;
571*01826a49SYabin Cui 
572*01826a49SYabin Cui /*! ZSTD_CCtx_reset() :
573*01826a49SYabin Cui  *  There are 2 different things that can be reset, independently or jointly :
574*01826a49SYabin Cui  *  - The session : will stop compressing current frame, and make CCtx ready to start a new one.
575*01826a49SYabin Cui  *                  Useful after an error, or to interrupt any ongoing compression.
576*01826a49SYabin Cui  *                  Any internal data not yet flushed is cancelled.
577*01826a49SYabin Cui  *                  Compression parameters and dictionary remain unchanged.
578*01826a49SYabin Cui  *                  They will be used to compress next frame.
579*01826a49SYabin Cui  *                  Resetting session never fails.
580*01826a49SYabin Cui  *  - The parameters : changes all parameters back to "default".
581*01826a49SYabin Cui  *                  This also removes any reference to any dictionary or external sequence producer.
582*01826a49SYabin Cui  *                  Parameters can only be changed between 2 sessions (i.e. no compression is currently ongoing)
583*01826a49SYabin Cui  *                  otherwise the reset fails, and function returns an error value (which can be tested using ZSTD_isError())
584*01826a49SYabin Cui  *  - Both : similar to resetting the session, followed by resetting parameters.
585*01826a49SYabin Cui  */
586*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_CCtx_reset(ZSTD_CCtx* cctx, ZSTD_ResetDirective reset);
587*01826a49SYabin Cui 
588*01826a49SYabin Cui /*! ZSTD_compress2() :
589*01826a49SYabin Cui  *  Behave the same as ZSTD_compressCCtx(), but compression parameters are set using the advanced API.
590*01826a49SYabin Cui  *  (note that this entry point doesn't even expose a compression level parameter).
591*01826a49SYabin Cui  *  ZSTD_compress2() always starts a new frame.
592*01826a49SYabin Cui  *  Should cctx hold data from a previously unfinished frame, everything about it is forgotten.
593*01826a49SYabin Cui  *  - Compression parameters are pushed into CCtx before starting compression, using ZSTD_CCtx_set*()
594*01826a49SYabin Cui  *  - The function is always blocking, returns when compression is completed.
595*01826a49SYabin Cui  *  NOTE: Providing `dstCapacity >= ZSTD_compressBound(srcSize)` guarantees that zstd will have
596*01826a49SYabin Cui  *        enough space to successfully compress the data, though it is possible it fails for other reasons.
597*01826a49SYabin Cui  * @return : compressed size written into `dst` (<= `dstCapacity),
598*01826a49SYabin Cui  *           or an error code if it fails (which can be tested using ZSTD_isError()).
599*01826a49SYabin Cui  */
600*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_compress2( ZSTD_CCtx* cctx,
601*01826a49SYabin Cui                                    void* dst, size_t dstCapacity,
602*01826a49SYabin Cui                              const void* src, size_t srcSize);
603*01826a49SYabin Cui 
604*01826a49SYabin Cui 
605*01826a49SYabin Cui /***********************************************
606*01826a49SYabin Cui *  Advanced decompression API (Requires v1.4.0+)
607*01826a49SYabin Cui ************************************************/
608*01826a49SYabin Cui 
609*01826a49SYabin Cui /* The advanced API pushes parameters one by one into an existing DCtx context.
610*01826a49SYabin Cui  * Parameters are sticky, and remain valid for all following frames
611*01826a49SYabin Cui  * using the same DCtx context.
612*01826a49SYabin Cui  * It's possible to reset parameters to default values using ZSTD_DCtx_reset().
613*01826a49SYabin Cui  * Note : This API is compatible with existing ZSTD_decompressDCtx() and ZSTD_decompressStream().
614*01826a49SYabin Cui  *        Therefore, no new decompression function is necessary.
615*01826a49SYabin Cui  */
616*01826a49SYabin Cui 
617*01826a49SYabin Cui typedef enum {
618*01826a49SYabin Cui 
619*01826a49SYabin Cui     ZSTD_d_windowLogMax=100, /* Select a size limit (in power of 2) beyond which
620*01826a49SYabin Cui                               * the streaming API will refuse to allocate memory buffer
621*01826a49SYabin Cui                               * in order to protect the host from unreasonable memory requirements.
622*01826a49SYabin Cui                               * This parameter is only useful in streaming mode, since no internal buffer is allocated in single-pass mode.
623*01826a49SYabin Cui                               * By default, a decompression context accepts window sizes <= (1 << ZSTD_WINDOWLOG_LIMIT_DEFAULT).
624*01826a49SYabin Cui                               * Special: value 0 means "use default maximum windowLog". */
625*01826a49SYabin Cui 
626*01826a49SYabin Cui     /* note : additional experimental parameters are also available
627*01826a49SYabin Cui      * within the experimental section of the API.
628*01826a49SYabin Cui      * At the time of this writing, they include :
629*01826a49SYabin Cui      * ZSTD_d_format
630*01826a49SYabin Cui      * ZSTD_d_stableOutBuffer
631*01826a49SYabin Cui      * ZSTD_d_forceIgnoreChecksum
632*01826a49SYabin Cui      * ZSTD_d_refMultipleDDicts
633*01826a49SYabin Cui      * ZSTD_d_disableHuffmanAssembly
634*01826a49SYabin Cui      * ZSTD_d_maxBlockSize
635*01826a49SYabin Cui      * Because they are not stable, it's necessary to define ZSTD_STATIC_LINKING_ONLY to access them.
636*01826a49SYabin Cui      * note : never ever use experimentalParam? names directly
637*01826a49SYabin Cui      */
638*01826a49SYabin Cui      ZSTD_d_experimentalParam1=1000,
639*01826a49SYabin Cui      ZSTD_d_experimentalParam2=1001,
640*01826a49SYabin Cui      ZSTD_d_experimentalParam3=1002,
641*01826a49SYabin Cui      ZSTD_d_experimentalParam4=1003,
642*01826a49SYabin Cui      ZSTD_d_experimentalParam5=1004,
643*01826a49SYabin Cui      ZSTD_d_experimentalParam6=1005
644*01826a49SYabin Cui 
645*01826a49SYabin Cui } ZSTD_dParameter;
646*01826a49SYabin Cui 
647*01826a49SYabin Cui /*! ZSTD_dParam_getBounds() :
648*01826a49SYabin Cui  *  All parameters must belong to an interval with lower and upper bounds,
649*01826a49SYabin Cui  *  otherwise they will either trigger an error or be automatically clamped.
650*01826a49SYabin Cui  * @return : a structure, ZSTD_bounds, which contains
651*01826a49SYabin Cui  *         - an error status field, which must be tested using ZSTD_isError()
652*01826a49SYabin Cui  *         - both lower and upper bounds, inclusive
653*01826a49SYabin Cui  */
654*01826a49SYabin Cui ZSTDLIB_API ZSTD_bounds ZSTD_dParam_getBounds(ZSTD_dParameter dParam);
655*01826a49SYabin Cui 
656*01826a49SYabin Cui /*! ZSTD_DCtx_setParameter() :
657*01826a49SYabin Cui  *  Set one compression parameter, selected by enum ZSTD_dParameter.
658*01826a49SYabin Cui  *  All parameters have valid bounds. Bounds can be queried using ZSTD_dParam_getBounds().
659*01826a49SYabin Cui  *  Providing a value beyond bound will either clamp it, or trigger an error (depending on parameter).
660*01826a49SYabin Cui  *  Setting a parameter is only possible during frame initialization (before starting decompression).
661*01826a49SYabin Cui  * @return : 0, or an error code (which can be tested using ZSTD_isError()).
662*01826a49SYabin Cui  */
663*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_DCtx_setParameter(ZSTD_DCtx* dctx, ZSTD_dParameter param, int value);
664*01826a49SYabin Cui 
665*01826a49SYabin Cui /*! ZSTD_DCtx_reset() :
666*01826a49SYabin Cui  *  Return a DCtx to clean state.
667*01826a49SYabin Cui  *  Session and parameters can be reset jointly or separately.
668*01826a49SYabin Cui  *  Parameters can only be reset when no active frame is being decompressed.
669*01826a49SYabin Cui  * @return : 0, or an error code, which can be tested with ZSTD_isError()
670*01826a49SYabin Cui  */
671*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_DCtx_reset(ZSTD_DCtx* dctx, ZSTD_ResetDirective reset);
672*01826a49SYabin Cui 
673*01826a49SYabin Cui 
674*01826a49SYabin Cui /****************************
675*01826a49SYabin Cui *  Streaming
676*01826a49SYabin Cui ****************************/
677*01826a49SYabin Cui 
678*01826a49SYabin Cui typedef struct ZSTD_inBuffer_s {
679*01826a49SYabin Cui   const void* src;    /**< start of input buffer */
680*01826a49SYabin Cui   size_t size;        /**< size of input buffer */
681*01826a49SYabin Cui   size_t pos;         /**< position where reading stopped. Will be updated. Necessarily 0 <= pos <= size */
682*01826a49SYabin Cui } ZSTD_inBuffer;
683*01826a49SYabin Cui 
684*01826a49SYabin Cui typedef struct ZSTD_outBuffer_s {
685*01826a49SYabin Cui   void*  dst;         /**< start of output buffer */
686*01826a49SYabin Cui   size_t size;        /**< size of output buffer */
687*01826a49SYabin Cui   size_t pos;         /**< position where writing stopped. Will be updated. Necessarily 0 <= pos <= size */
688*01826a49SYabin Cui } ZSTD_outBuffer;
689*01826a49SYabin Cui 
690*01826a49SYabin Cui 
691*01826a49SYabin Cui 
692*01826a49SYabin Cui /*-***********************************************************************
693*01826a49SYabin Cui *  Streaming compression - HowTo
694*01826a49SYabin Cui *
695*01826a49SYabin Cui *  A ZSTD_CStream object is required to track streaming operation.
696*01826a49SYabin Cui *  Use ZSTD_createCStream() and ZSTD_freeCStream() to create/release resources.
697*01826a49SYabin Cui *  ZSTD_CStream objects can be reused multiple times on consecutive compression operations.
698*01826a49SYabin Cui *  It is recommended to reuse ZSTD_CStream since it will play nicer with system's memory, by re-using already allocated memory.
699*01826a49SYabin Cui *
700*01826a49SYabin Cui *  For parallel execution, use one separate ZSTD_CStream per thread.
701*01826a49SYabin Cui *
702*01826a49SYabin Cui *  note : since v1.3.0, ZSTD_CStream and ZSTD_CCtx are the same thing.
703*01826a49SYabin Cui *
704*01826a49SYabin Cui *  Parameters are sticky : when starting a new compression on the same context,
705*01826a49SYabin Cui *  it will reuse the same sticky parameters as previous compression session.
706*01826a49SYabin Cui *  When in doubt, it's recommended to fully initialize the context before usage.
707*01826a49SYabin Cui *  Use ZSTD_CCtx_reset() to reset the context and ZSTD_CCtx_setParameter(),
708*01826a49SYabin Cui *  ZSTD_CCtx_setPledgedSrcSize(), or ZSTD_CCtx_loadDictionary() and friends to
709*01826a49SYabin Cui *  set more specific parameters, the pledged source size, or load a dictionary.
710*01826a49SYabin Cui *
711*01826a49SYabin Cui *  Use ZSTD_compressStream2() with ZSTD_e_continue as many times as necessary to
712*01826a49SYabin Cui *  consume input stream. The function will automatically update both `pos`
713*01826a49SYabin Cui *  fields within `input` and `output`.
714*01826a49SYabin Cui *  Note that the function may not consume the entire input, for example, because
715*01826a49SYabin Cui *  the output buffer is already full, in which case `input.pos < input.size`.
716*01826a49SYabin Cui *  The caller must check if input has been entirely consumed.
717*01826a49SYabin Cui *  If not, the caller must make some room to receive more compressed data,
718*01826a49SYabin Cui *  and then present again remaining input data.
719*01826a49SYabin Cui *  note: ZSTD_e_continue is guaranteed to make some forward progress when called,
720*01826a49SYabin Cui *        but doesn't guarantee maximal forward progress. This is especially relevant
721*01826a49SYabin Cui *        when compressing with multiple threads. The call won't block if it can
722*01826a49SYabin Cui *        consume some input, but if it can't it will wait for some, but not all,
723*01826a49SYabin Cui *        output to be flushed.
724*01826a49SYabin Cui * @return : provides a minimum amount of data remaining to be flushed from internal buffers
725*01826a49SYabin Cui *           or an error code, which can be tested using ZSTD_isError().
726*01826a49SYabin Cui *
727*01826a49SYabin Cui *  At any moment, it's possible to flush whatever data might remain stuck within internal buffer,
728*01826a49SYabin Cui *  using ZSTD_compressStream2() with ZSTD_e_flush. `output->pos` will be updated.
729*01826a49SYabin Cui *  Note that, if `output->size` is too small, a single invocation with ZSTD_e_flush might not be enough (return code > 0).
730*01826a49SYabin Cui *  In which case, make some room to receive more compressed data, and call again ZSTD_compressStream2() with ZSTD_e_flush.
731*01826a49SYabin Cui *  You must continue calling ZSTD_compressStream2() with ZSTD_e_flush until it returns 0, at which point you can change the
732*01826a49SYabin Cui *  operation.
733*01826a49SYabin Cui *  note: ZSTD_e_flush will flush as much output as possible, meaning when compressing with multiple threads, it will
734*01826a49SYabin Cui *        block until the flush is complete or the output buffer is full.
735*01826a49SYabin Cui *  @return : 0 if internal buffers are entirely flushed,
736*01826a49SYabin Cui *            >0 if some data still present within internal buffer (the value is minimal estimation of remaining size),
737*01826a49SYabin Cui *            or an error code, which can be tested using ZSTD_isError().
738*01826a49SYabin Cui *
739*01826a49SYabin Cui *  Calling ZSTD_compressStream2() with ZSTD_e_end instructs to finish a frame.
740*01826a49SYabin Cui *  It will perform a flush and write frame epilogue.
741*01826a49SYabin Cui *  The epilogue is required for decoders to consider a frame completed.
742*01826a49SYabin Cui *  flush operation is the same, and follows same rules as calling ZSTD_compressStream2() with ZSTD_e_flush.
743*01826a49SYabin Cui *  You must continue calling ZSTD_compressStream2() with ZSTD_e_end until it returns 0, at which point you are free to
744*01826a49SYabin Cui *  start a new frame.
745*01826a49SYabin Cui *  note: ZSTD_e_end will flush as much output as possible, meaning when compressing with multiple threads, it will
746*01826a49SYabin Cui *        block until the flush is complete or the output buffer is full.
747*01826a49SYabin Cui *  @return : 0 if frame fully completed and fully flushed,
748*01826a49SYabin Cui *            >0 if some data still present within internal buffer (the value is minimal estimation of remaining size),
749*01826a49SYabin Cui *            or an error code, which can be tested using ZSTD_isError().
750*01826a49SYabin Cui *
751*01826a49SYabin Cui * *******************************************************************/
752*01826a49SYabin Cui 
753*01826a49SYabin Cui typedef ZSTD_CCtx ZSTD_CStream;  /**< CCtx and CStream are now effectively same object (>= v1.3.0) */
754*01826a49SYabin Cui                                  /* Continue to distinguish them for compatibility with older versions <= v1.2.0 */
755*01826a49SYabin Cui /*===== ZSTD_CStream management functions =====*/
756*01826a49SYabin Cui ZSTDLIB_API ZSTD_CStream* ZSTD_createCStream(void);
757*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_freeCStream(ZSTD_CStream* zcs);  /* accept NULL pointer */
758*01826a49SYabin Cui 
759*01826a49SYabin Cui /*===== Streaming compression functions =====*/
760*01826a49SYabin Cui typedef enum {
761*01826a49SYabin Cui     ZSTD_e_continue=0, /* collect more data, encoder decides when to output compressed result, for optimal compression ratio */
762*01826a49SYabin Cui     ZSTD_e_flush=1,    /* flush any data provided so far,
763*01826a49SYabin Cui                         * it creates (at least) one new block, that can be decoded immediately on reception;
764*01826a49SYabin Cui                         * frame will continue: any future data can still reference previously compressed data, improving compression.
765*01826a49SYabin Cui                         * note : multithreaded compression will block to flush as much output as possible. */
766*01826a49SYabin Cui     ZSTD_e_end=2       /* flush any remaining data _and_ close current frame.
767*01826a49SYabin Cui                         * note that frame is only closed after compressed data is fully flushed (return value == 0).
768*01826a49SYabin Cui                         * After that point, any additional data starts a new frame.
769*01826a49SYabin Cui                         * note : each frame is independent (does not reference any content from previous frame).
770*01826a49SYabin Cui                         : note : multithreaded compression will block to flush as much output as possible. */
771*01826a49SYabin Cui } ZSTD_EndDirective;
772*01826a49SYabin Cui 
773*01826a49SYabin Cui /*! ZSTD_compressStream2() : Requires v1.4.0+
774*01826a49SYabin Cui  *  Behaves about the same as ZSTD_compressStream, with additional control on end directive.
775*01826a49SYabin Cui  *  - Compression parameters are pushed into CCtx before starting compression, using ZSTD_CCtx_set*()
776*01826a49SYabin Cui  *  - Compression parameters cannot be changed once compression is started (save a list of exceptions in multi-threading mode)
777*01826a49SYabin Cui  *  - output->pos must be <= dstCapacity, input->pos must be <= srcSize
778*01826a49SYabin Cui  *  - output->pos and input->pos will be updated. They are guaranteed to remain below their respective limit.
779*01826a49SYabin Cui  *  - endOp must be a valid directive
780*01826a49SYabin Cui  *  - When nbWorkers==0 (default), function is blocking : it completes its job before returning to caller.
781*01826a49SYabin Cui  *  - When nbWorkers>=1, function is non-blocking : it copies a portion of input, distributes jobs to internal worker threads, flush to output whatever is available,
782*01826a49SYabin Cui  *                                                  and then immediately returns, just indicating that there is some data remaining to be flushed.
783*01826a49SYabin Cui  *                                                  The function nonetheless guarantees forward progress : it will return only after it reads or write at least 1+ byte.
784*01826a49SYabin Cui  *  - Exception : if the first call requests a ZSTD_e_end directive and provides enough dstCapacity, the function delegates to ZSTD_compress2() which is always blocking.
785*01826a49SYabin Cui  *  - @return provides a minimum amount of data remaining to be flushed from internal buffers
786*01826a49SYabin Cui  *            or an error code, which can be tested using ZSTD_isError().
787*01826a49SYabin Cui  *            if @return != 0, flush is not fully completed, there is still some data left within internal buffers.
788*01826a49SYabin Cui  *            This is useful for ZSTD_e_flush, since in this case more flushes are necessary to empty all buffers.
789*01826a49SYabin Cui  *            For ZSTD_e_end, @return == 0 when internal buffers are fully flushed and frame is completed.
790*01826a49SYabin Cui  *  - after a ZSTD_e_end directive, if internal buffer is not fully flushed (@return != 0),
791*01826a49SYabin Cui  *            only ZSTD_e_end or ZSTD_e_flush operations are allowed.
792*01826a49SYabin Cui  *            Before starting a new compression job, or changing compression parameters,
793*01826a49SYabin Cui  *            it is required to fully flush internal buffers.
794*01826a49SYabin Cui  *  - note: if an operation ends with an error, it may leave @cctx in an undefined state.
795*01826a49SYabin Cui  *          Therefore, it's UB to invoke ZSTD_compressStream2() of ZSTD_compressStream() on such a state.
796*01826a49SYabin Cui  *          In order to be re-employed after an error, a state must be reset,
797*01826a49SYabin Cui  *          which can be done explicitly (ZSTD_CCtx_reset()),
798*01826a49SYabin Cui  *          or is sometimes implied by methods starting a new compression job (ZSTD_initCStream(), ZSTD_compressCCtx())
799*01826a49SYabin Cui  */
800*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_compressStream2( ZSTD_CCtx* cctx,
801*01826a49SYabin Cui                                          ZSTD_outBuffer* output,
802*01826a49SYabin Cui                                          ZSTD_inBuffer* input,
803*01826a49SYabin Cui                                          ZSTD_EndDirective endOp);
804*01826a49SYabin Cui 
805*01826a49SYabin Cui 
806*01826a49SYabin Cui /* These buffer sizes are softly recommended.
807*01826a49SYabin Cui  * They are not required : ZSTD_compressStream*() happily accepts any buffer size, for both input and output.
808*01826a49SYabin Cui  * Respecting the recommended size just makes it a bit easier for ZSTD_compressStream*(),
809*01826a49SYabin Cui  * reducing the amount of memory shuffling and buffering, resulting in minor performance savings.
810*01826a49SYabin Cui  *
811*01826a49SYabin Cui  * However, note that these recommendations are from the perspective of a C caller program.
812*01826a49SYabin Cui  * If the streaming interface is invoked from some other language,
813*01826a49SYabin Cui  * especially managed ones such as Java or Go, through a foreign function interface such as jni or cgo,
814*01826a49SYabin Cui  * a major performance rule is to reduce crossing such interface to an absolute minimum.
815*01826a49SYabin Cui  * It's not rare that performance ends being spent more into the interface, rather than compression itself.
816*01826a49SYabin Cui  * In which cases, prefer using large buffers, as large as practical,
817*01826a49SYabin Cui  * for both input and output, to reduce the nb of roundtrips.
818*01826a49SYabin Cui  */
819*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_CStreamInSize(void);    /**< recommended size for input buffer */
820*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_CStreamOutSize(void);   /**< recommended size for output buffer. Guarantee to successfully flush at least one complete compressed block. */
821*01826a49SYabin Cui 
822*01826a49SYabin Cui 
823*01826a49SYabin Cui /* *****************************************************************************
824*01826a49SYabin Cui  * This following is a legacy streaming API, available since v1.0+ .
825*01826a49SYabin Cui  * It can be replaced by ZSTD_CCtx_reset() and ZSTD_compressStream2().
826*01826a49SYabin Cui  * It is redundant, but remains fully supported.
827*01826a49SYabin Cui  ******************************************************************************/
828*01826a49SYabin Cui 
829*01826a49SYabin Cui /*!
830*01826a49SYabin Cui  * Equivalent to:
831*01826a49SYabin Cui  *
832*01826a49SYabin Cui  *     ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only);
833*01826a49SYabin Cui  *     ZSTD_CCtx_refCDict(zcs, NULL); // clear the dictionary (if any)
834*01826a49SYabin Cui  *     ZSTD_CCtx_setParameter(zcs, ZSTD_c_compressionLevel, compressionLevel);
835*01826a49SYabin Cui  *
836*01826a49SYabin Cui  * Note that ZSTD_initCStream() clears any previously set dictionary. Use the new API
837*01826a49SYabin Cui  * to compress with a dictionary.
838*01826a49SYabin Cui  */
839*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_initCStream(ZSTD_CStream* zcs, int compressionLevel);
840*01826a49SYabin Cui /*!
841*01826a49SYabin Cui  * Alternative for ZSTD_compressStream2(zcs, output, input, ZSTD_e_continue).
842*01826a49SYabin Cui  * NOTE: The return value is different. ZSTD_compressStream() returns a hint for
843*01826a49SYabin Cui  * the next read size (if non-zero and not an error). ZSTD_compressStream2()
844*01826a49SYabin Cui  * returns the minimum nb of bytes left to flush (if non-zero and not an error).
845*01826a49SYabin Cui  */
846*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_compressStream(ZSTD_CStream* zcs, ZSTD_outBuffer* output, ZSTD_inBuffer* input);
847*01826a49SYabin Cui /*! Equivalent to ZSTD_compressStream2(zcs, output, &emptyInput, ZSTD_e_flush). */
848*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_flushStream(ZSTD_CStream* zcs, ZSTD_outBuffer* output);
849*01826a49SYabin Cui /*! Equivalent to ZSTD_compressStream2(zcs, output, &emptyInput, ZSTD_e_end). */
850*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_endStream(ZSTD_CStream* zcs, ZSTD_outBuffer* output);
851*01826a49SYabin Cui 
852*01826a49SYabin Cui 
853*01826a49SYabin Cui /*-***************************************************************************
854*01826a49SYabin Cui *  Streaming decompression - HowTo
855*01826a49SYabin Cui *
856*01826a49SYabin Cui *  A ZSTD_DStream object is required to track streaming operations.
857*01826a49SYabin Cui *  Use ZSTD_createDStream() and ZSTD_freeDStream() to create/release resources.
858*01826a49SYabin Cui *  ZSTD_DStream objects can be reused multiple times.
859*01826a49SYabin Cui *
860*01826a49SYabin Cui *  Use ZSTD_initDStream() to start a new decompression operation.
861*01826a49SYabin Cui * @return : recommended first input size
862*01826a49SYabin Cui *  Alternatively, use advanced API to set specific properties.
863*01826a49SYabin Cui *
864*01826a49SYabin Cui *  Use ZSTD_decompressStream() repetitively to consume your input.
865*01826a49SYabin Cui *  The function will update both `pos` fields.
866*01826a49SYabin Cui *  If `input.pos < input.size`, some input has not been consumed.
867*01826a49SYabin Cui *  It's up to the caller to present again remaining data.
868*01826a49SYabin Cui *  The function tries to flush all data decoded immediately, respecting output buffer size.
869*01826a49SYabin Cui *  If `output.pos < output.size`, decoder has flushed everything it could.
870*01826a49SYabin Cui *  But if `output.pos == output.size`, there might be some data left within internal buffers.,
871*01826a49SYabin Cui *  In which case, call ZSTD_decompressStream() again to flush whatever remains in the buffer.
872*01826a49SYabin Cui *  Note : with no additional input provided, amount of data flushed is necessarily <= ZSTD_BLOCKSIZE_MAX.
873*01826a49SYabin Cui * @return : 0 when a frame is completely decoded and fully flushed,
874*01826a49SYabin Cui *        or an error code, which can be tested using ZSTD_isError(),
875*01826a49SYabin Cui *        or any other value > 0, which means there is still some decoding or flushing to do to complete current frame :
876*01826a49SYabin Cui *                                the return value is a suggested next input size (just a hint for better latency)
877*01826a49SYabin Cui *                                that will never request more than the remaining frame size.
878*01826a49SYabin Cui * *******************************************************************************/
879*01826a49SYabin Cui 
880*01826a49SYabin Cui typedef ZSTD_DCtx ZSTD_DStream;  /**< DCtx and DStream are now effectively same object (>= v1.3.0) */
881*01826a49SYabin Cui                                  /* For compatibility with versions <= v1.2.0, prefer differentiating them. */
882*01826a49SYabin Cui /*===== ZSTD_DStream management functions =====*/
883*01826a49SYabin Cui ZSTDLIB_API ZSTD_DStream* ZSTD_createDStream(void);
884*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_freeDStream(ZSTD_DStream* zds);  /* accept NULL pointer */
885*01826a49SYabin Cui 
886*01826a49SYabin Cui /*===== Streaming decompression functions =====*/
887*01826a49SYabin Cui 
888*01826a49SYabin Cui /*! ZSTD_initDStream() :
889*01826a49SYabin Cui  * Initialize/reset DStream state for new decompression operation.
890*01826a49SYabin Cui  * Call before new decompression operation using same DStream.
891*01826a49SYabin Cui  *
892*01826a49SYabin Cui  * Note : This function is redundant with the advanced API and equivalent to:
893*01826a49SYabin Cui  *     ZSTD_DCtx_reset(zds, ZSTD_reset_session_only);
894*01826a49SYabin Cui  *     ZSTD_DCtx_refDDict(zds, NULL);
895*01826a49SYabin Cui  */
896*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_initDStream(ZSTD_DStream* zds);
897*01826a49SYabin Cui 
898*01826a49SYabin Cui /*! ZSTD_decompressStream() :
899*01826a49SYabin Cui  * Streaming decompression function.
900*01826a49SYabin Cui  * Call repetitively to consume full input updating it as necessary.
901*01826a49SYabin Cui  * Function will update both input and output `pos` fields exposing current state via these fields:
902*01826a49SYabin Cui  * - `input.pos < input.size`, some input remaining and caller should provide remaining input
903*01826a49SYabin Cui  *   on the next call.
904*01826a49SYabin Cui  * - `output.pos < output.size`, decoder finished and flushed all remaining buffers.
905*01826a49SYabin Cui  * - `output.pos == output.size`, potentially uncflushed data present in the internal buffers,
906*01826a49SYabin Cui  *   call ZSTD_decompressStream() again to flush remaining data to output.
907*01826a49SYabin Cui  * Note : with no additional input, amount of data flushed <= ZSTD_BLOCKSIZE_MAX.
908*01826a49SYabin Cui  *
909*01826a49SYabin Cui  * @return : 0 when a frame is completely decoded and fully flushed,
910*01826a49SYabin Cui  *           or an error code, which can be tested using ZSTD_isError(),
911*01826a49SYabin Cui  *           or any other value > 0, which means there is some decoding or flushing to do to complete current frame.
912*01826a49SYabin Cui  *
913*01826a49SYabin Cui  * Note: when an operation returns with an error code, the @zds state may be left in undefined state.
914*01826a49SYabin Cui  *       It's UB to invoke `ZSTD_decompressStream()` on such a state.
915*01826a49SYabin Cui  *       In order to re-use such a state, it must be first reset,
916*01826a49SYabin Cui  *       which can be done explicitly (`ZSTD_DCtx_reset()`),
917*01826a49SYabin Cui  *       or is implied for operations starting some new decompression job (`ZSTD_initDStream`, `ZSTD_decompressDCtx()`, `ZSTD_decompress_usingDict()`)
918*01826a49SYabin Cui  */
919*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_decompressStream(ZSTD_DStream* zds, ZSTD_outBuffer* output, ZSTD_inBuffer* input);
920*01826a49SYabin Cui 
921*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_DStreamInSize(void);    /*!< recommended size for input buffer */
922*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_DStreamOutSize(void);   /*!< recommended size for output buffer. Guarantee to successfully flush at least one complete block in all circumstances. */
923*01826a49SYabin Cui 
924*01826a49SYabin Cui 
925*01826a49SYabin Cui /**************************
926*01826a49SYabin Cui *  Simple dictionary API
927*01826a49SYabin Cui ***************************/
928*01826a49SYabin Cui /*! ZSTD_compress_usingDict() :
929*01826a49SYabin Cui  *  Compression at an explicit compression level using a Dictionary.
930*01826a49SYabin Cui  *  A dictionary can be any arbitrary data segment (also called a prefix),
931*01826a49SYabin Cui  *  or a buffer with specified information (see zdict.h).
932*01826a49SYabin Cui  *  Note : This function loads the dictionary, resulting in significant startup delay.
933*01826a49SYabin Cui  *         It's intended for a dictionary used only once.
934*01826a49SYabin Cui  *  Note 2 : When `dict == NULL || dictSize < 8` no dictionary is used. */
935*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_compress_usingDict(ZSTD_CCtx* ctx,
936*01826a49SYabin Cui                                            void* dst, size_t dstCapacity,
937*01826a49SYabin Cui                                      const void* src, size_t srcSize,
938*01826a49SYabin Cui                                      const void* dict,size_t dictSize,
939*01826a49SYabin Cui                                            int compressionLevel);
940*01826a49SYabin Cui 
941*01826a49SYabin Cui /*! ZSTD_decompress_usingDict() :
942*01826a49SYabin Cui  *  Decompression using a known Dictionary.
943*01826a49SYabin Cui  *  Dictionary must be identical to the one used during compression.
944*01826a49SYabin Cui  *  Note : This function loads the dictionary, resulting in significant startup delay.
945*01826a49SYabin Cui  *         It's intended for a dictionary used only once.
946*01826a49SYabin Cui  *  Note : When `dict == NULL || dictSize < 8` no dictionary is used. */
947*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_decompress_usingDict(ZSTD_DCtx* dctx,
948*01826a49SYabin Cui                                              void* dst, size_t dstCapacity,
949*01826a49SYabin Cui                                        const void* src, size_t srcSize,
950*01826a49SYabin Cui                                        const void* dict,size_t dictSize);
951*01826a49SYabin Cui 
952*01826a49SYabin Cui 
953*01826a49SYabin Cui /***********************************
954*01826a49SYabin Cui  *  Bulk processing dictionary API
955*01826a49SYabin Cui  **********************************/
956*01826a49SYabin Cui typedef struct ZSTD_CDict_s ZSTD_CDict;
957*01826a49SYabin Cui 
958*01826a49SYabin Cui /*! ZSTD_createCDict() :
959*01826a49SYabin Cui  *  When compressing multiple messages or blocks using the same dictionary,
960*01826a49SYabin Cui  *  it's recommended to digest the dictionary only once, since it's a costly operation.
961*01826a49SYabin Cui  *  ZSTD_createCDict() will create a state from digesting a dictionary.
962*01826a49SYabin Cui  *  The resulting state can be used for future compression operations with very limited startup cost.
963*01826a49SYabin Cui  *  ZSTD_CDict can be created once and shared by multiple threads concurrently, since its usage is read-only.
964*01826a49SYabin Cui  * @dictBuffer can be released after ZSTD_CDict creation, because its content is copied within CDict.
965*01826a49SYabin Cui  *  Note 1 : Consider experimental function `ZSTD_createCDict_byReference()` if you prefer to not duplicate @dictBuffer content.
966*01826a49SYabin Cui  *  Note 2 : A ZSTD_CDict can be created from an empty @dictBuffer,
967*01826a49SYabin Cui  *      in which case the only thing that it transports is the @compressionLevel.
968*01826a49SYabin Cui  *      This can be useful in a pipeline featuring ZSTD_compress_usingCDict() exclusively,
969*01826a49SYabin Cui  *      expecting a ZSTD_CDict parameter with any data, including those without a known dictionary. */
970*01826a49SYabin Cui ZSTDLIB_API ZSTD_CDict* ZSTD_createCDict(const void* dictBuffer, size_t dictSize,
971*01826a49SYabin Cui                                          int compressionLevel);
972*01826a49SYabin Cui 
973*01826a49SYabin Cui /*! ZSTD_freeCDict() :
974*01826a49SYabin Cui  *  Function frees memory allocated by ZSTD_createCDict().
975*01826a49SYabin Cui  *  If a NULL pointer is passed, no operation is performed. */
976*01826a49SYabin Cui ZSTDLIB_API size_t      ZSTD_freeCDict(ZSTD_CDict* CDict);
977*01826a49SYabin Cui 
978*01826a49SYabin Cui /*! ZSTD_compress_usingCDict() :
979*01826a49SYabin Cui  *  Compression using a digested Dictionary.
980*01826a49SYabin Cui  *  Recommended when same dictionary is used multiple times.
981*01826a49SYabin Cui  *  Note : compression level is _decided at dictionary creation time_,
982*01826a49SYabin Cui  *     and frame parameters are hardcoded (dictID=yes, contentSize=yes, checksum=no) */
983*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_compress_usingCDict(ZSTD_CCtx* cctx,
984*01826a49SYabin Cui                                             void* dst, size_t dstCapacity,
985*01826a49SYabin Cui                                       const void* src, size_t srcSize,
986*01826a49SYabin Cui                                       const ZSTD_CDict* cdict);
987*01826a49SYabin Cui 
988*01826a49SYabin Cui 
989*01826a49SYabin Cui typedef struct ZSTD_DDict_s ZSTD_DDict;
990*01826a49SYabin Cui 
991*01826a49SYabin Cui /*! ZSTD_createDDict() :
992*01826a49SYabin Cui  *  Create a digested dictionary, ready to start decompression operation without startup delay.
993*01826a49SYabin Cui  *  dictBuffer can be released after DDict creation, as its content is copied inside DDict. */
994*01826a49SYabin Cui ZSTDLIB_API ZSTD_DDict* ZSTD_createDDict(const void* dictBuffer, size_t dictSize);
995*01826a49SYabin Cui 
996*01826a49SYabin Cui /*! ZSTD_freeDDict() :
997*01826a49SYabin Cui  *  Function frees memory allocated with ZSTD_createDDict()
998*01826a49SYabin Cui  *  If a NULL pointer is passed, no operation is performed. */
999*01826a49SYabin Cui ZSTDLIB_API size_t      ZSTD_freeDDict(ZSTD_DDict* ddict);
1000*01826a49SYabin Cui 
1001*01826a49SYabin Cui /*! ZSTD_decompress_usingDDict() :
1002*01826a49SYabin Cui  *  Decompression using a digested Dictionary.
1003*01826a49SYabin Cui  *  Recommended when same dictionary is used multiple times. */
1004*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_decompress_usingDDict(ZSTD_DCtx* dctx,
1005*01826a49SYabin Cui                                               void* dst, size_t dstCapacity,
1006*01826a49SYabin Cui                                         const void* src, size_t srcSize,
1007*01826a49SYabin Cui                                         const ZSTD_DDict* ddict);
1008*01826a49SYabin Cui 
1009*01826a49SYabin Cui 
1010*01826a49SYabin Cui /********************************
1011*01826a49SYabin Cui  *  Dictionary helper functions
1012*01826a49SYabin Cui  *******************************/
1013*01826a49SYabin Cui 
1014*01826a49SYabin Cui /*! ZSTD_getDictID_fromDict() : Requires v1.4.0+
1015*01826a49SYabin Cui  *  Provides the dictID stored within dictionary.
1016*01826a49SYabin Cui  *  if @return == 0, the dictionary is not conformant with Zstandard specification.
1017*01826a49SYabin Cui  *  It can still be loaded, but as a content-only dictionary. */
1018*01826a49SYabin Cui ZSTDLIB_API unsigned ZSTD_getDictID_fromDict(const void* dict, size_t dictSize);
1019*01826a49SYabin Cui 
1020*01826a49SYabin Cui /*! ZSTD_getDictID_fromCDict() : Requires v1.5.0+
1021*01826a49SYabin Cui  *  Provides the dictID of the dictionary loaded into `cdict`.
1022*01826a49SYabin Cui  *  If @return == 0, the dictionary is not conformant to Zstandard specification, or empty.
1023*01826a49SYabin Cui  *  Non-conformant dictionaries can still be loaded, but as content-only dictionaries. */
1024*01826a49SYabin Cui ZSTDLIB_API unsigned ZSTD_getDictID_fromCDict(const ZSTD_CDict* cdict);
1025*01826a49SYabin Cui 
1026*01826a49SYabin Cui /*! ZSTD_getDictID_fromDDict() : Requires v1.4.0+
1027*01826a49SYabin Cui  *  Provides the dictID of the dictionary loaded into `ddict`.
1028*01826a49SYabin Cui  *  If @return == 0, the dictionary is not conformant to Zstandard specification, or empty.
1029*01826a49SYabin Cui  *  Non-conformant dictionaries can still be loaded, but as content-only dictionaries. */
1030*01826a49SYabin Cui ZSTDLIB_API unsigned ZSTD_getDictID_fromDDict(const ZSTD_DDict* ddict);
1031*01826a49SYabin Cui 
1032*01826a49SYabin Cui /*! ZSTD_getDictID_fromFrame() : Requires v1.4.0+
1033*01826a49SYabin Cui  *  Provides the dictID required to decompressed the frame stored within `src`.
1034*01826a49SYabin Cui  *  If @return == 0, the dictID could not be decoded.
1035*01826a49SYabin Cui  *  This could for one of the following reasons :
1036*01826a49SYabin Cui  *  - The frame does not require a dictionary to be decoded (most common case).
1037*01826a49SYabin Cui  *  - The frame was built with dictID intentionally removed. Whatever dictionary is necessary is a hidden piece of information.
1038*01826a49SYabin Cui  *    Note : this use case also happens when using a non-conformant dictionary.
1039*01826a49SYabin Cui  *  - `srcSize` is too small, and as a result, the frame header could not be decoded (only possible if `srcSize < ZSTD_FRAMEHEADERSIZE_MAX`).
1040*01826a49SYabin Cui  *  - This is not a Zstandard frame.
1041*01826a49SYabin Cui  *  When identifying the exact failure cause, it's possible to use ZSTD_getFrameHeader(), which will provide a more precise error code. */
1042*01826a49SYabin Cui ZSTDLIB_API unsigned ZSTD_getDictID_fromFrame(const void* src, size_t srcSize);
1043*01826a49SYabin Cui 
1044*01826a49SYabin Cui 
1045*01826a49SYabin Cui /*******************************************************************************
1046*01826a49SYabin Cui  * Advanced dictionary and prefix API (Requires v1.4.0+)
1047*01826a49SYabin Cui  *
1048*01826a49SYabin Cui  * This API allows dictionaries to be used with ZSTD_compress2(),
1049*01826a49SYabin Cui  * ZSTD_compressStream2(), and ZSTD_decompressDCtx().
1050*01826a49SYabin Cui  * Dictionaries are sticky, they remain valid when same context is reused,
1051*01826a49SYabin Cui  * they only reset when the context is reset
1052*01826a49SYabin Cui  * with ZSTD_reset_parameters or ZSTD_reset_session_and_parameters.
1053*01826a49SYabin Cui  * In contrast, Prefixes are single-use.
1054*01826a49SYabin Cui  ******************************************************************************/
1055*01826a49SYabin Cui 
1056*01826a49SYabin Cui 
1057*01826a49SYabin Cui /*! ZSTD_CCtx_loadDictionary() : Requires v1.4.0+
1058*01826a49SYabin Cui  *  Create an internal CDict from `dict` buffer.
1059*01826a49SYabin Cui  *  Decompression will have to use same dictionary.
1060*01826a49SYabin Cui  * @result : 0, or an error code (which can be tested with ZSTD_isError()).
1061*01826a49SYabin Cui  *  Special: Loading a NULL (or 0-size) dictionary invalidates previous dictionary,
1062*01826a49SYabin Cui  *           meaning "return to no-dictionary mode".
1063*01826a49SYabin Cui  *  Note 1 : Dictionary is sticky, it will be used for all future compressed frames,
1064*01826a49SYabin Cui  *           until parameters are reset, a new dictionary is loaded, or the dictionary
1065*01826a49SYabin Cui  *           is explicitly invalidated by loading a NULL dictionary.
1066*01826a49SYabin Cui  *  Note 2 : Loading a dictionary involves building tables.
1067*01826a49SYabin Cui  *           It's also a CPU consuming operation, with non-negligible impact on latency.
1068*01826a49SYabin Cui  *           Tables are dependent on compression parameters, and for this reason,
1069*01826a49SYabin Cui  *           compression parameters can no longer be changed after loading a dictionary.
1070*01826a49SYabin Cui  *  Note 3 :`dict` content will be copied internally.
1071*01826a49SYabin Cui  *           Use experimental ZSTD_CCtx_loadDictionary_byReference() to reference content instead.
1072*01826a49SYabin Cui  *           In such a case, dictionary buffer must outlive its users.
1073*01826a49SYabin Cui  *  Note 4 : Use ZSTD_CCtx_loadDictionary_advanced()
1074*01826a49SYabin Cui  *           to precisely select how dictionary content must be interpreted.
1075*01826a49SYabin Cui  *  Note 5 : This method does not benefit from LDM (long distance mode).
1076*01826a49SYabin Cui  *           If you want to employ LDM on some large dictionary content,
1077*01826a49SYabin Cui  *           prefer employing ZSTD_CCtx_refPrefix() described below.
1078*01826a49SYabin Cui  */
1079*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_CCtx_loadDictionary(ZSTD_CCtx* cctx, const void* dict, size_t dictSize);
1080*01826a49SYabin Cui 
1081*01826a49SYabin Cui /*! ZSTD_CCtx_refCDict() : Requires v1.4.0+
1082*01826a49SYabin Cui  *  Reference a prepared dictionary, to be used for all future compressed frames.
1083*01826a49SYabin Cui  *  Note that compression parameters are enforced from within CDict,
1084*01826a49SYabin Cui  *  and supersede any compression parameter previously set within CCtx.
1085*01826a49SYabin Cui  *  The parameters ignored are labelled as "superseded-by-cdict" in the ZSTD_cParameter enum docs.
1086*01826a49SYabin Cui  *  The ignored parameters will be used again if the CCtx is returned to no-dictionary mode.
1087*01826a49SYabin Cui  *  The dictionary will remain valid for future compressed frames using same CCtx.
1088*01826a49SYabin Cui  * @result : 0, or an error code (which can be tested with ZSTD_isError()).
1089*01826a49SYabin Cui  *  Special : Referencing a NULL CDict means "return to no-dictionary mode".
1090*01826a49SYabin Cui  *  Note 1 : Currently, only one dictionary can be managed.
1091*01826a49SYabin Cui  *           Referencing a new dictionary effectively "discards" any previous one.
1092*01826a49SYabin Cui  *  Note 2 : CDict is just referenced, its lifetime must outlive its usage within CCtx. */
1093*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_CCtx_refCDict(ZSTD_CCtx* cctx, const ZSTD_CDict* cdict);
1094*01826a49SYabin Cui 
1095*01826a49SYabin Cui /*! ZSTD_CCtx_refPrefix() : Requires v1.4.0+
1096*01826a49SYabin Cui  *  Reference a prefix (single-usage dictionary) for next compressed frame.
1097*01826a49SYabin Cui  *  A prefix is **only used once**. Tables are discarded at end of frame (ZSTD_e_end).
1098*01826a49SYabin Cui  *  Decompression will need same prefix to properly regenerate data.
1099*01826a49SYabin Cui  *  Compressing with a prefix is similar in outcome as performing a diff and compressing it,
1100*01826a49SYabin Cui  *  but performs much faster, especially during decompression (compression speed is tunable with compression level).
1101*01826a49SYabin Cui  *  This method is compatible with LDM (long distance mode).
1102*01826a49SYabin Cui  * @result : 0, or an error code (which can be tested with ZSTD_isError()).
1103*01826a49SYabin Cui  *  Special: Adding any prefix (including NULL) invalidates any previous prefix or dictionary
1104*01826a49SYabin Cui  *  Note 1 : Prefix buffer is referenced. It **must** outlive compression.
1105*01826a49SYabin Cui  *           Its content must remain unmodified during compression.
1106*01826a49SYabin Cui  *  Note 2 : If the intention is to diff some large src data blob with some prior version of itself,
1107*01826a49SYabin Cui  *           ensure that the window size is large enough to contain the entire source.
1108*01826a49SYabin Cui  *           See ZSTD_c_windowLog.
1109*01826a49SYabin Cui  *  Note 3 : Referencing a prefix involves building tables, which are dependent on compression parameters.
1110*01826a49SYabin Cui  *           It's a CPU consuming operation, with non-negligible impact on latency.
1111*01826a49SYabin Cui  *           If there is a need to use the same prefix multiple times, consider loadDictionary instead.
1112*01826a49SYabin Cui  *  Note 4 : By default, the prefix is interpreted as raw content (ZSTD_dct_rawContent).
1113*01826a49SYabin Cui  *           Use experimental ZSTD_CCtx_refPrefix_advanced() to alter dictionary interpretation. */
1114*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_CCtx_refPrefix(ZSTD_CCtx* cctx,
1115*01826a49SYabin Cui                                  const void* prefix, size_t prefixSize);
1116*01826a49SYabin Cui 
1117*01826a49SYabin Cui /*! ZSTD_DCtx_loadDictionary() : Requires v1.4.0+
1118*01826a49SYabin Cui  *  Create an internal DDict from dict buffer, to be used to decompress all future frames.
1119*01826a49SYabin Cui  *  The dictionary remains valid for all future frames, until explicitly invalidated, or
1120*01826a49SYabin Cui  *  a new dictionary is loaded.
1121*01826a49SYabin Cui  * @result : 0, or an error code (which can be tested with ZSTD_isError()).
1122*01826a49SYabin Cui  *  Special : Adding a NULL (or 0-size) dictionary invalidates any previous dictionary,
1123*01826a49SYabin Cui  *            meaning "return to no-dictionary mode".
1124*01826a49SYabin Cui  *  Note 1 : Loading a dictionary involves building tables,
1125*01826a49SYabin Cui  *           which has a non-negligible impact on CPU usage and latency.
1126*01826a49SYabin Cui  *           It's recommended to "load once, use many times", to amortize the cost
1127*01826a49SYabin Cui  *  Note 2 :`dict` content will be copied internally, so `dict` can be released after loading.
1128*01826a49SYabin Cui  *           Use ZSTD_DCtx_loadDictionary_byReference() to reference dictionary content instead.
1129*01826a49SYabin Cui  *  Note 3 : Use ZSTD_DCtx_loadDictionary_advanced() to take control of
1130*01826a49SYabin Cui  *           how dictionary content is loaded and interpreted.
1131*01826a49SYabin Cui  */
1132*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_DCtx_loadDictionary(ZSTD_DCtx* dctx, const void* dict, size_t dictSize);
1133*01826a49SYabin Cui 
1134*01826a49SYabin Cui /*! ZSTD_DCtx_refDDict() : Requires v1.4.0+
1135*01826a49SYabin Cui  *  Reference a prepared dictionary, to be used to decompress next frames.
1136*01826a49SYabin Cui  *  The dictionary remains active for decompression of future frames using same DCtx.
1137*01826a49SYabin Cui  *
1138*01826a49SYabin Cui  *  If called with ZSTD_d_refMultipleDDicts enabled, repeated calls of this function
1139*01826a49SYabin Cui  *  will store the DDict references in a table, and the DDict used for decompression
1140*01826a49SYabin Cui  *  will be determined at decompression time, as per the dict ID in the frame.
1141*01826a49SYabin Cui  *  The memory for the table is allocated on the first call to refDDict, and can be
1142*01826a49SYabin Cui  *  freed with ZSTD_freeDCtx().
1143*01826a49SYabin Cui  *
1144*01826a49SYabin Cui  *  If called with ZSTD_d_refMultipleDDicts disabled (the default), only one dictionary
1145*01826a49SYabin Cui  *  will be managed, and referencing a dictionary effectively "discards" any previous one.
1146*01826a49SYabin Cui  *
1147*01826a49SYabin Cui  * @result : 0, or an error code (which can be tested with ZSTD_isError()).
1148*01826a49SYabin Cui  *  Special: referencing a NULL DDict means "return to no-dictionary mode".
1149*01826a49SYabin Cui  *  Note 2 : DDict is just referenced, its lifetime must outlive its usage from DCtx.
1150*01826a49SYabin Cui  */
1151*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_DCtx_refDDict(ZSTD_DCtx* dctx, const ZSTD_DDict* ddict);
1152*01826a49SYabin Cui 
1153*01826a49SYabin Cui /*! ZSTD_DCtx_refPrefix() : Requires v1.4.0+
1154*01826a49SYabin Cui  *  Reference a prefix (single-usage dictionary) to decompress next frame.
1155*01826a49SYabin Cui  *  This is the reverse operation of ZSTD_CCtx_refPrefix(),
1156*01826a49SYabin Cui  *  and must use the same prefix as the one used during compression.
1157*01826a49SYabin Cui  *  Prefix is **only used once**. Reference is discarded at end of frame.
1158*01826a49SYabin Cui  *  End of frame is reached when ZSTD_decompressStream() returns 0.
1159*01826a49SYabin Cui  * @result : 0, or an error code (which can be tested with ZSTD_isError()).
1160*01826a49SYabin Cui  *  Note 1 : Adding any prefix (including NULL) invalidates any previously set prefix or dictionary
1161*01826a49SYabin Cui  *  Note 2 : Prefix buffer is referenced. It **must** outlive decompression.
1162*01826a49SYabin Cui  *           Prefix buffer must remain unmodified up to the end of frame,
1163*01826a49SYabin Cui  *           reached when ZSTD_decompressStream() returns 0.
1164*01826a49SYabin Cui  *  Note 3 : By default, the prefix is treated as raw content (ZSTD_dct_rawContent).
1165*01826a49SYabin Cui  *           Use ZSTD_CCtx_refPrefix_advanced() to alter dictMode (Experimental section)
1166*01826a49SYabin Cui  *  Note 4 : Referencing a raw content prefix has almost no cpu nor memory cost.
1167*01826a49SYabin Cui  *           A full dictionary is more costly, as it requires building tables.
1168*01826a49SYabin Cui  */
1169*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_DCtx_refPrefix(ZSTD_DCtx* dctx,
1170*01826a49SYabin Cui                                  const void* prefix, size_t prefixSize);
1171*01826a49SYabin Cui 
1172*01826a49SYabin Cui /* ===   Memory management   === */
1173*01826a49SYabin Cui 
1174*01826a49SYabin Cui /*! ZSTD_sizeof_*() : Requires v1.4.0+
1175*01826a49SYabin Cui  *  These functions give the _current_ memory usage of selected object.
1176*01826a49SYabin Cui  *  Note that object memory usage can evolve (increase or decrease) over time. */
1177*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_sizeof_CCtx(const ZSTD_CCtx* cctx);
1178*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_sizeof_DCtx(const ZSTD_DCtx* dctx);
1179*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_sizeof_CStream(const ZSTD_CStream* zcs);
1180*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_sizeof_DStream(const ZSTD_DStream* zds);
1181*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_sizeof_CDict(const ZSTD_CDict* cdict);
1182*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_sizeof_DDict(const ZSTD_DDict* ddict);
1183*01826a49SYabin Cui 
1184*01826a49SYabin Cui #endif  /* ZSTD_H_235446 */
1185*01826a49SYabin Cui 
1186*01826a49SYabin Cui 
1187*01826a49SYabin Cui /* **************************************************************************************
1188*01826a49SYabin Cui  *   ADVANCED AND EXPERIMENTAL FUNCTIONS
1189*01826a49SYabin Cui  ****************************************************************************************
1190*01826a49SYabin Cui  * The definitions in the following section are considered experimental.
1191*01826a49SYabin Cui  * They are provided for advanced scenarios.
1192*01826a49SYabin Cui  * They should never be used with a dynamic library, as prototypes may change in the future.
1193*01826a49SYabin Cui  * Use them only in association with static linking.
1194*01826a49SYabin Cui  * ***************************************************************************************/
1195*01826a49SYabin Cui 
1196*01826a49SYabin Cui #if defined(ZSTD_STATIC_LINKING_ONLY) && !defined(ZSTD_H_ZSTD_STATIC_LINKING_ONLY)
1197*01826a49SYabin Cui #define ZSTD_H_ZSTD_STATIC_LINKING_ONLY
1198*01826a49SYabin Cui 
1199*01826a49SYabin Cui /* This can be overridden externally to hide static symbols. */
1200*01826a49SYabin Cui #ifndef ZSTDLIB_STATIC_API
1201*01826a49SYabin Cui #  if defined(ZSTD_DLL_EXPORT) && (ZSTD_DLL_EXPORT==1)
1202*01826a49SYabin Cui #    define ZSTDLIB_STATIC_API __declspec(dllexport) ZSTDLIB_VISIBLE
1203*01826a49SYabin Cui #  elif defined(ZSTD_DLL_IMPORT) && (ZSTD_DLL_IMPORT==1)
1204*01826a49SYabin Cui #    define ZSTDLIB_STATIC_API __declspec(dllimport) ZSTDLIB_VISIBLE
1205*01826a49SYabin Cui #  else
1206*01826a49SYabin Cui #    define ZSTDLIB_STATIC_API ZSTDLIB_VISIBLE
1207*01826a49SYabin Cui #  endif
1208*01826a49SYabin Cui #endif
1209*01826a49SYabin Cui 
1210*01826a49SYabin Cui /****************************************************************************************
1211*01826a49SYabin Cui  *   experimental API (static linking only)
1212*01826a49SYabin Cui  ****************************************************************************************
1213*01826a49SYabin Cui  * The following symbols and constants
1214*01826a49SYabin Cui  * are not planned to join "stable API" status in the near future.
1215*01826a49SYabin Cui  * They can still change in future versions.
1216*01826a49SYabin Cui  * Some of them are planned to remain in the static_only section indefinitely.
1217*01826a49SYabin Cui  * Some of them might be removed in the future (especially when redundant with existing stable functions)
1218*01826a49SYabin Cui  * ***************************************************************************************/
1219*01826a49SYabin Cui 
1220*01826a49SYabin Cui #define ZSTD_FRAMEHEADERSIZE_PREFIX(format) ((format) == ZSTD_f_zstd1 ? 5 : 1)   /* minimum input size required to query frame header size */
1221*01826a49SYabin Cui #define ZSTD_FRAMEHEADERSIZE_MIN(format)    ((format) == ZSTD_f_zstd1 ? 6 : 2)
1222*01826a49SYabin Cui #define ZSTD_FRAMEHEADERSIZE_MAX   18   /* can be useful for static allocation */
1223*01826a49SYabin Cui #define ZSTD_SKIPPABLEHEADERSIZE    8
1224*01826a49SYabin Cui 
1225*01826a49SYabin Cui /* compression parameter bounds */
1226*01826a49SYabin Cui #define ZSTD_WINDOWLOG_MAX_32    30
1227*01826a49SYabin Cui #define ZSTD_WINDOWLOG_MAX_64    31
1228*01826a49SYabin Cui #define ZSTD_WINDOWLOG_MAX     ((int)(sizeof(size_t) == 4 ? ZSTD_WINDOWLOG_MAX_32 : ZSTD_WINDOWLOG_MAX_64))
1229*01826a49SYabin Cui #define ZSTD_WINDOWLOG_MIN       10
1230*01826a49SYabin Cui #define ZSTD_HASHLOG_MAX       ((ZSTD_WINDOWLOG_MAX < 30) ? ZSTD_WINDOWLOG_MAX : 30)
1231*01826a49SYabin Cui #define ZSTD_HASHLOG_MIN          6
1232*01826a49SYabin Cui #define ZSTD_CHAINLOG_MAX_32     29
1233*01826a49SYabin Cui #define ZSTD_CHAINLOG_MAX_64     30
1234*01826a49SYabin Cui #define ZSTD_CHAINLOG_MAX      ((int)(sizeof(size_t) == 4 ? ZSTD_CHAINLOG_MAX_32 : ZSTD_CHAINLOG_MAX_64))
1235*01826a49SYabin Cui #define ZSTD_CHAINLOG_MIN        ZSTD_HASHLOG_MIN
1236*01826a49SYabin Cui #define ZSTD_SEARCHLOG_MAX      (ZSTD_WINDOWLOG_MAX-1)
1237*01826a49SYabin Cui #define ZSTD_SEARCHLOG_MIN        1
1238*01826a49SYabin Cui #define ZSTD_MINMATCH_MAX         7   /* only for ZSTD_fast, other strategies are limited to 6 */
1239*01826a49SYabin Cui #define ZSTD_MINMATCH_MIN         3   /* only for ZSTD_btopt+, faster strategies are limited to 4 */
1240*01826a49SYabin Cui #define ZSTD_TARGETLENGTH_MAX    ZSTD_BLOCKSIZE_MAX
1241*01826a49SYabin Cui #define ZSTD_TARGETLENGTH_MIN     0   /* note : comparing this constant to an unsigned results in a tautological test */
1242*01826a49SYabin Cui #define ZSTD_STRATEGY_MIN        ZSTD_fast
1243*01826a49SYabin Cui #define ZSTD_STRATEGY_MAX        ZSTD_btultra2
1244*01826a49SYabin Cui #define ZSTD_BLOCKSIZE_MAX_MIN (1 << 10) /* The minimum valid max blocksize. Maximum blocksizes smaller than this make compressBound() inaccurate. */
1245*01826a49SYabin Cui 
1246*01826a49SYabin Cui 
1247*01826a49SYabin Cui #define ZSTD_OVERLAPLOG_MIN       0
1248*01826a49SYabin Cui #define ZSTD_OVERLAPLOG_MAX       9
1249*01826a49SYabin Cui 
1250*01826a49SYabin Cui #define ZSTD_WINDOWLOG_LIMIT_DEFAULT 27   /* by default, the streaming decoder will refuse any frame
1251*01826a49SYabin Cui                                            * requiring larger than (1<<ZSTD_WINDOWLOG_LIMIT_DEFAULT) window size,
1252*01826a49SYabin Cui                                            * to preserve host's memory from unreasonable requirements.
1253*01826a49SYabin Cui                                            * This limit can be overridden using ZSTD_DCtx_setParameter(,ZSTD_d_windowLogMax,).
1254*01826a49SYabin Cui                                            * The limit does not apply for one-pass decoders (such as ZSTD_decompress()), since no additional memory is allocated */
1255*01826a49SYabin Cui 
1256*01826a49SYabin Cui 
1257*01826a49SYabin Cui /* LDM parameter bounds */
1258*01826a49SYabin Cui #define ZSTD_LDM_HASHLOG_MIN      ZSTD_HASHLOG_MIN
1259*01826a49SYabin Cui #define ZSTD_LDM_HASHLOG_MAX      ZSTD_HASHLOG_MAX
1260*01826a49SYabin Cui #define ZSTD_LDM_MINMATCH_MIN        4
1261*01826a49SYabin Cui #define ZSTD_LDM_MINMATCH_MAX     4096
1262*01826a49SYabin Cui #define ZSTD_LDM_BUCKETSIZELOG_MIN   1
1263*01826a49SYabin Cui #define ZSTD_LDM_BUCKETSIZELOG_MAX   8
1264*01826a49SYabin Cui #define ZSTD_LDM_HASHRATELOG_MIN     0
1265*01826a49SYabin Cui #define ZSTD_LDM_HASHRATELOG_MAX (ZSTD_WINDOWLOG_MAX - ZSTD_HASHLOG_MIN)
1266*01826a49SYabin Cui 
1267*01826a49SYabin Cui /* Advanced parameter bounds */
1268*01826a49SYabin Cui #define ZSTD_TARGETCBLOCKSIZE_MIN   1340 /* suitable to fit into an ethernet / wifi / 4G transport frame */
1269*01826a49SYabin Cui #define ZSTD_TARGETCBLOCKSIZE_MAX   ZSTD_BLOCKSIZE_MAX
1270*01826a49SYabin Cui #define ZSTD_SRCSIZEHINT_MIN        0
1271*01826a49SYabin Cui #define ZSTD_SRCSIZEHINT_MAX        INT_MAX
1272*01826a49SYabin Cui 
1273*01826a49SYabin Cui 
1274*01826a49SYabin Cui /* ---  Advanced types  --- */
1275*01826a49SYabin Cui 
1276*01826a49SYabin Cui typedef struct ZSTD_CCtx_params_s ZSTD_CCtx_params;
1277*01826a49SYabin Cui 
1278*01826a49SYabin Cui typedef struct {
1279*01826a49SYabin Cui     unsigned int offset;      /* The offset of the match. (NOT the same as the offset code)
1280*01826a49SYabin Cui                                * If offset == 0 and matchLength == 0, this sequence represents the last
1281*01826a49SYabin Cui                                * literals in the block of litLength size.
1282*01826a49SYabin Cui                                */
1283*01826a49SYabin Cui 
1284*01826a49SYabin Cui     unsigned int litLength;   /* Literal length of the sequence. */
1285*01826a49SYabin Cui     unsigned int matchLength; /* Match length of the sequence. */
1286*01826a49SYabin Cui 
1287*01826a49SYabin Cui                               /* Note: Users of this API may provide a sequence with matchLength == litLength == offset == 0.
1288*01826a49SYabin Cui                                * In this case, we will treat the sequence as a marker for a block boundary.
1289*01826a49SYabin Cui                                */
1290*01826a49SYabin Cui 
1291*01826a49SYabin Cui     unsigned int rep;         /* Represents which repeat offset is represented by the field 'offset'.
1292*01826a49SYabin Cui                                * Ranges from [0, 3].
1293*01826a49SYabin Cui                                *
1294*01826a49SYabin Cui                                * Repeat offsets are essentially previous offsets from previous sequences sorted in
1295*01826a49SYabin Cui                                * recency order. For more detail, see doc/zstd_compression_format.md
1296*01826a49SYabin Cui                                *
1297*01826a49SYabin Cui                                * If rep == 0, then 'offset' does not contain a repeat offset.
1298*01826a49SYabin Cui                                * If rep > 0:
1299*01826a49SYabin Cui                                *  If litLength != 0:
1300*01826a49SYabin Cui                                *      rep == 1 --> offset == repeat_offset_1
1301*01826a49SYabin Cui                                *      rep == 2 --> offset == repeat_offset_2
1302*01826a49SYabin Cui                                *      rep == 3 --> offset == repeat_offset_3
1303*01826a49SYabin Cui                                *  If litLength == 0:
1304*01826a49SYabin Cui                                *      rep == 1 --> offset == repeat_offset_2
1305*01826a49SYabin Cui                                *      rep == 2 --> offset == repeat_offset_3
1306*01826a49SYabin Cui                                *      rep == 3 --> offset == repeat_offset_1 - 1
1307*01826a49SYabin Cui                                *
1308*01826a49SYabin Cui                                * Note: This field is optional. ZSTD_generateSequences() will calculate the value of
1309*01826a49SYabin Cui                                * 'rep', but repeat offsets do not necessarily need to be calculated from an external
1310*01826a49SYabin Cui                                * sequence provider's perspective. For example, ZSTD_compressSequences() does not
1311*01826a49SYabin Cui                                * use this 'rep' field at all (as of now).
1312*01826a49SYabin Cui                                */
1313*01826a49SYabin Cui } ZSTD_Sequence;
1314*01826a49SYabin Cui 
1315*01826a49SYabin Cui typedef struct {
1316*01826a49SYabin Cui     unsigned windowLog;       /**< largest match distance : larger == more compression, more memory needed during decompression */
1317*01826a49SYabin Cui     unsigned chainLog;        /**< fully searched segment : larger == more compression, slower, more memory (useless for fast) */
1318*01826a49SYabin Cui     unsigned hashLog;         /**< dispatch table : larger == faster, more memory */
1319*01826a49SYabin Cui     unsigned searchLog;       /**< nb of searches : larger == more compression, slower */
1320*01826a49SYabin Cui     unsigned minMatch;        /**< match length searched : larger == faster decompression, sometimes less compression */
1321*01826a49SYabin Cui     unsigned targetLength;    /**< acceptable match size for optimal parser (only) : larger == more compression, slower */
1322*01826a49SYabin Cui     ZSTD_strategy strategy;   /**< see ZSTD_strategy definition above */
1323*01826a49SYabin Cui } ZSTD_compressionParameters;
1324*01826a49SYabin Cui 
1325*01826a49SYabin Cui typedef struct {
1326*01826a49SYabin Cui     int contentSizeFlag; /**< 1: content size will be in frame header (when known) */
1327*01826a49SYabin Cui     int checksumFlag;    /**< 1: generate a 32-bits checksum using XXH64 algorithm at end of frame, for error detection */
1328*01826a49SYabin Cui     int noDictIDFlag;    /**< 1: no dictID will be saved into frame header (dictID is only useful for dictionary compression) */
1329*01826a49SYabin Cui } ZSTD_frameParameters;
1330*01826a49SYabin Cui 
1331*01826a49SYabin Cui typedef struct {
1332*01826a49SYabin Cui     ZSTD_compressionParameters cParams;
1333*01826a49SYabin Cui     ZSTD_frameParameters fParams;
1334*01826a49SYabin Cui } ZSTD_parameters;
1335*01826a49SYabin Cui 
1336*01826a49SYabin Cui typedef enum {
1337*01826a49SYabin Cui     ZSTD_dct_auto = 0,       /* dictionary is "full" when starting with ZSTD_MAGIC_DICTIONARY, otherwise it is "rawContent" */
1338*01826a49SYabin Cui     ZSTD_dct_rawContent = 1, /* ensures dictionary is always loaded as rawContent, even if it starts with ZSTD_MAGIC_DICTIONARY */
1339*01826a49SYabin Cui     ZSTD_dct_fullDict = 2    /* refuses to load a dictionary if it does not respect Zstandard's specification, starting with ZSTD_MAGIC_DICTIONARY */
1340*01826a49SYabin Cui } ZSTD_dictContentType_e;
1341*01826a49SYabin Cui 
1342*01826a49SYabin Cui typedef enum {
1343*01826a49SYabin Cui     ZSTD_dlm_byCopy = 0,  /**< Copy dictionary content internally */
1344*01826a49SYabin Cui     ZSTD_dlm_byRef = 1    /**< Reference dictionary content -- the dictionary buffer must outlive its users. */
1345*01826a49SYabin Cui } ZSTD_dictLoadMethod_e;
1346*01826a49SYabin Cui 
1347*01826a49SYabin Cui typedef enum {
1348*01826a49SYabin Cui     ZSTD_f_zstd1 = 0,           /* zstd frame format, specified in zstd_compression_format.md (default) */
1349*01826a49SYabin Cui     ZSTD_f_zstd1_magicless = 1  /* Variant of zstd frame format, without initial 4-bytes magic number.
1350*01826a49SYabin Cui                                  * Useful to save 4 bytes per generated frame.
1351*01826a49SYabin Cui                                  * Decoder cannot recognise automatically this format, requiring this instruction. */
1352*01826a49SYabin Cui } ZSTD_format_e;
1353*01826a49SYabin Cui 
1354*01826a49SYabin Cui typedef enum {
1355*01826a49SYabin Cui     /* Note: this enum controls ZSTD_d_forceIgnoreChecksum */
1356*01826a49SYabin Cui     ZSTD_d_validateChecksum = 0,
1357*01826a49SYabin Cui     ZSTD_d_ignoreChecksum = 1
1358*01826a49SYabin Cui } ZSTD_forceIgnoreChecksum_e;
1359*01826a49SYabin Cui 
1360*01826a49SYabin Cui typedef enum {
1361*01826a49SYabin Cui     /* Note: this enum controls ZSTD_d_refMultipleDDicts */
1362*01826a49SYabin Cui     ZSTD_rmd_refSingleDDict = 0,
1363*01826a49SYabin Cui     ZSTD_rmd_refMultipleDDicts = 1
1364*01826a49SYabin Cui } ZSTD_refMultipleDDicts_e;
1365*01826a49SYabin Cui 
1366*01826a49SYabin Cui typedef enum {
1367*01826a49SYabin Cui     /* Note: this enum and the behavior it controls are effectively internal
1368*01826a49SYabin Cui      * implementation details of the compressor. They are expected to continue
1369*01826a49SYabin Cui      * to evolve and should be considered only in the context of extremely
1370*01826a49SYabin Cui      * advanced performance tuning.
1371*01826a49SYabin Cui      *
1372*01826a49SYabin Cui      * Zstd currently supports the use of a CDict in three ways:
1373*01826a49SYabin Cui      *
1374*01826a49SYabin Cui      * - The contents of the CDict can be copied into the working context. This
1375*01826a49SYabin Cui      *   means that the compression can search both the dictionary and input
1376*01826a49SYabin Cui      *   while operating on a single set of internal tables. This makes
1377*01826a49SYabin Cui      *   the compression faster per-byte of input. However, the initial copy of
1378*01826a49SYabin Cui      *   the CDict's tables incurs a fixed cost at the beginning of the
1379*01826a49SYabin Cui      *   compression. For small compressions (< 8 KB), that copy can dominate
1380*01826a49SYabin Cui      *   the cost of the compression.
1381*01826a49SYabin Cui      *
1382*01826a49SYabin Cui      * - The CDict's tables can be used in-place. In this model, compression is
1383*01826a49SYabin Cui      *   slower per input byte, because the compressor has to search two sets of
1384*01826a49SYabin Cui      *   tables. However, this model incurs no start-up cost (as long as the
1385*01826a49SYabin Cui      *   working context's tables can be reused). For small inputs, this can be
1386*01826a49SYabin Cui      *   faster than copying the CDict's tables.
1387*01826a49SYabin Cui      *
1388*01826a49SYabin Cui      * - The CDict's tables are not used at all, and instead we use the working
1389*01826a49SYabin Cui      *   context alone to reload the dictionary and use params based on the source
1390*01826a49SYabin Cui      *   size. See ZSTD_compress_insertDictionary() and ZSTD_compress_usingDict().
1391*01826a49SYabin Cui      *   This method is effective when the dictionary sizes are very small relative
1392*01826a49SYabin Cui      *   to the input size, and the input size is fairly large to begin with.
1393*01826a49SYabin Cui      *
1394*01826a49SYabin Cui      * Zstd has a simple internal heuristic that selects which strategy to use
1395*01826a49SYabin Cui      * at the beginning of a compression. However, if experimentation shows that
1396*01826a49SYabin Cui      * Zstd is making poor choices, it is possible to override that choice with
1397*01826a49SYabin Cui      * this enum.
1398*01826a49SYabin Cui      */
1399*01826a49SYabin Cui     ZSTD_dictDefaultAttach = 0, /* Use the default heuristic. */
1400*01826a49SYabin Cui     ZSTD_dictForceAttach   = 1, /* Never copy the dictionary. */
1401*01826a49SYabin Cui     ZSTD_dictForceCopy     = 2, /* Always copy the dictionary. */
1402*01826a49SYabin Cui     ZSTD_dictForceLoad     = 3  /* Always reload the dictionary */
1403*01826a49SYabin Cui } ZSTD_dictAttachPref_e;
1404*01826a49SYabin Cui 
1405*01826a49SYabin Cui typedef enum {
1406*01826a49SYabin Cui   ZSTD_lcm_auto = 0,          /**< Automatically determine the compression mode based on the compression level.
1407*01826a49SYabin Cui                                *   Negative compression levels will be uncompressed, and positive compression
1408*01826a49SYabin Cui                                *   levels will be compressed. */
1409*01826a49SYabin Cui   ZSTD_lcm_huffman = 1,       /**< Always attempt Huffman compression. Uncompressed literals will still be
1410*01826a49SYabin Cui                                *   emitted if Huffman compression is not profitable. */
1411*01826a49SYabin Cui   ZSTD_lcm_uncompressed = 2   /**< Always emit uncompressed literals. */
1412*01826a49SYabin Cui } ZSTD_literalCompressionMode_e;
1413*01826a49SYabin Cui 
1414*01826a49SYabin Cui typedef enum {
1415*01826a49SYabin Cui   /* Note: This enum controls features which are conditionally beneficial. Zstd typically will make a final
1416*01826a49SYabin Cui    * decision on whether or not to enable the feature (ZSTD_ps_auto), but setting the switch to ZSTD_ps_enable
1417*01826a49SYabin Cui    * or ZSTD_ps_disable allow for a force enable/disable the feature.
1418*01826a49SYabin Cui    */
1419*01826a49SYabin Cui   ZSTD_ps_auto = 0,         /* Let the library automatically determine whether the feature shall be enabled */
1420*01826a49SYabin Cui   ZSTD_ps_enable = 1,       /* Force-enable the feature */
1421*01826a49SYabin Cui   ZSTD_ps_disable = 2       /* Do not use the feature */
1422*01826a49SYabin Cui } ZSTD_paramSwitch_e;
1423*01826a49SYabin Cui 
1424*01826a49SYabin Cui /***************************************
1425*01826a49SYabin Cui *  Frame header and size functions
1426*01826a49SYabin Cui ***************************************/
1427*01826a49SYabin Cui 
1428*01826a49SYabin Cui /*! ZSTD_findDecompressedSize() :
1429*01826a49SYabin Cui  *  `src` should point to the start of a series of ZSTD encoded and/or skippable frames
1430*01826a49SYabin Cui  *  `srcSize` must be the _exact_ size of this series
1431*01826a49SYabin Cui  *       (i.e. there should be a frame boundary at `src + srcSize`)
1432*01826a49SYabin Cui  *  @return : - decompressed size of all data in all successive frames
1433*01826a49SYabin Cui  *            - if the decompressed size cannot be determined: ZSTD_CONTENTSIZE_UNKNOWN
1434*01826a49SYabin Cui  *            - if an error occurred: ZSTD_CONTENTSIZE_ERROR
1435*01826a49SYabin Cui  *
1436*01826a49SYabin Cui  *   note 1 : decompressed size is an optional field, that may not be present, especially in streaming mode.
1437*01826a49SYabin Cui  *            When `return==ZSTD_CONTENTSIZE_UNKNOWN`, data to decompress could be any size.
1438*01826a49SYabin Cui  *            In which case, it's necessary to use streaming mode to decompress data.
1439*01826a49SYabin Cui  *   note 2 : decompressed size is always present when compression is done with ZSTD_compress()
1440*01826a49SYabin Cui  *   note 3 : decompressed size can be very large (64-bits value),
1441*01826a49SYabin Cui  *            potentially larger than what local system can handle as a single memory segment.
1442*01826a49SYabin Cui  *            In which case, it's necessary to use streaming mode to decompress data.
1443*01826a49SYabin Cui  *   note 4 : If source is untrusted, decompressed size could be wrong or intentionally modified.
1444*01826a49SYabin Cui  *            Always ensure result fits within application's authorized limits.
1445*01826a49SYabin Cui  *            Each application can set its own limits.
1446*01826a49SYabin Cui  *   note 5 : ZSTD_findDecompressedSize handles multiple frames, and so it must traverse the input to
1447*01826a49SYabin Cui  *            read each contained frame header.  This is fast as most of the data is skipped,
1448*01826a49SYabin Cui  *            however it does mean that all frame data must be present and valid. */
1449*01826a49SYabin Cui ZSTDLIB_STATIC_API unsigned long long ZSTD_findDecompressedSize(const void* src, size_t srcSize);
1450*01826a49SYabin Cui 
1451*01826a49SYabin Cui /*! ZSTD_decompressBound() :
1452*01826a49SYabin Cui  *  `src` should point to the start of a series of ZSTD encoded and/or skippable frames
1453*01826a49SYabin Cui  *  `srcSize` must be the _exact_ size of this series
1454*01826a49SYabin Cui  *       (i.e. there should be a frame boundary at `src + srcSize`)
1455*01826a49SYabin Cui  *  @return : - upper-bound for the decompressed size of all data in all successive frames
1456*01826a49SYabin Cui  *            - if an error occurred: ZSTD_CONTENTSIZE_ERROR
1457*01826a49SYabin Cui  *
1458*01826a49SYabin Cui  *  note 1  : an error can occur if `src` contains an invalid or incorrectly formatted frame.
1459*01826a49SYabin Cui  *  note 2  : the upper-bound is exact when the decompressed size field is available in every ZSTD encoded frame of `src`.
1460*01826a49SYabin Cui  *            in this case, `ZSTD_findDecompressedSize` and `ZSTD_decompressBound` return the same value.
1461*01826a49SYabin Cui  *  note 3  : when the decompressed size field isn't available, the upper-bound for that frame is calculated by:
1462*01826a49SYabin Cui  *              upper-bound = # blocks * min(128 KB, Window_Size)
1463*01826a49SYabin Cui  */
1464*01826a49SYabin Cui ZSTDLIB_STATIC_API unsigned long long ZSTD_decompressBound(const void* src, size_t srcSize);
1465*01826a49SYabin Cui 
1466*01826a49SYabin Cui /*! ZSTD_frameHeaderSize() :
1467*01826a49SYabin Cui  *  srcSize must be >= ZSTD_FRAMEHEADERSIZE_PREFIX.
1468*01826a49SYabin Cui  * @return : size of the Frame Header,
1469*01826a49SYabin Cui  *           or an error code (if srcSize is too small) */
1470*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_frameHeaderSize(const void* src, size_t srcSize);
1471*01826a49SYabin Cui 
1472*01826a49SYabin Cui typedef enum { ZSTD_frame, ZSTD_skippableFrame } ZSTD_frameType_e;
1473*01826a49SYabin Cui typedef struct {
1474*01826a49SYabin Cui     unsigned long long frameContentSize; /* if == ZSTD_CONTENTSIZE_UNKNOWN, it means this field is not available. 0 means "empty" */
1475*01826a49SYabin Cui     unsigned long long windowSize;       /* can be very large, up to <= frameContentSize */
1476*01826a49SYabin Cui     unsigned blockSizeMax;
1477*01826a49SYabin Cui     ZSTD_frameType_e frameType;          /* if == ZSTD_skippableFrame, frameContentSize is the size of skippable content */
1478*01826a49SYabin Cui     unsigned headerSize;
1479*01826a49SYabin Cui     unsigned dictID;
1480*01826a49SYabin Cui     unsigned checksumFlag;
1481*01826a49SYabin Cui     unsigned _reserved1;
1482*01826a49SYabin Cui     unsigned _reserved2;
1483*01826a49SYabin Cui } ZSTD_frameHeader;
1484*01826a49SYabin Cui 
1485*01826a49SYabin Cui /*! ZSTD_getFrameHeader() :
1486*01826a49SYabin Cui  *  decode Frame Header, or requires larger `srcSize`.
1487*01826a49SYabin Cui  * @return : 0, `zfhPtr` is correctly filled,
1488*01826a49SYabin Cui  *          >0, `srcSize` is too small, value is wanted `srcSize` amount,
1489*01826a49SYabin Cui  *           or an error code, which can be tested using ZSTD_isError() */
1490*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_getFrameHeader(ZSTD_frameHeader* zfhPtr, const void* src, size_t srcSize);   /**< doesn't consume input */
1491*01826a49SYabin Cui /*! ZSTD_getFrameHeader_advanced() :
1492*01826a49SYabin Cui  *  same as ZSTD_getFrameHeader(),
1493*01826a49SYabin Cui  *  with added capability to select a format (like ZSTD_f_zstd1_magicless) */
1494*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_getFrameHeader_advanced(ZSTD_frameHeader* zfhPtr, const void* src, size_t srcSize, ZSTD_format_e format);
1495*01826a49SYabin Cui 
1496*01826a49SYabin Cui /*! ZSTD_decompressionMargin() :
1497*01826a49SYabin Cui  * Zstd supports in-place decompression, where the input and output buffers overlap.
1498*01826a49SYabin Cui  * In this case, the output buffer must be at least (Margin + Output_Size) bytes large,
1499*01826a49SYabin Cui  * and the input buffer must be at the end of the output buffer.
1500*01826a49SYabin Cui  *
1501*01826a49SYabin Cui  *  _______________________ Output Buffer ________________________
1502*01826a49SYabin Cui  * |                                                              |
1503*01826a49SYabin Cui  * |                                        ____ Input Buffer ____|
1504*01826a49SYabin Cui  * |                                       |                      |
1505*01826a49SYabin Cui  * v                                       v                      v
1506*01826a49SYabin Cui  * |---------------------------------------|-----------|----------|
1507*01826a49SYabin Cui  * ^                                                   ^          ^
1508*01826a49SYabin Cui  * |___________________ Output_Size ___________________|_ Margin _|
1509*01826a49SYabin Cui  *
1510*01826a49SYabin Cui  * NOTE: See also ZSTD_DECOMPRESSION_MARGIN().
1511*01826a49SYabin Cui  * NOTE: This applies only to single-pass decompression through ZSTD_decompress() or
1512*01826a49SYabin Cui  * ZSTD_decompressDCtx().
1513*01826a49SYabin Cui  * NOTE: This function supports multi-frame input.
1514*01826a49SYabin Cui  *
1515*01826a49SYabin Cui  * @param src The compressed frame(s)
1516*01826a49SYabin Cui  * @param srcSize The size of the compressed frame(s)
1517*01826a49SYabin Cui  * @returns The decompression margin or an error that can be checked with ZSTD_isError().
1518*01826a49SYabin Cui  */
1519*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_decompressionMargin(const void* src, size_t srcSize);
1520*01826a49SYabin Cui 
1521*01826a49SYabin Cui /*! ZSTD_DECOMPRESS_MARGIN() :
1522*01826a49SYabin Cui  * Similar to ZSTD_decompressionMargin(), but instead of computing the margin from
1523*01826a49SYabin Cui  * the compressed frame, compute it from the original size and the blockSizeLog.
1524*01826a49SYabin Cui  * See ZSTD_decompressionMargin() for details.
1525*01826a49SYabin Cui  *
1526*01826a49SYabin Cui  * WARNING: This macro does not support multi-frame input, the input must be a single
1527*01826a49SYabin Cui  * zstd frame. If you need that support use the function, or implement it yourself.
1528*01826a49SYabin Cui  *
1529*01826a49SYabin Cui  * @param originalSize The original uncompressed size of the data.
1530*01826a49SYabin Cui  * @param blockSize    The block size == MIN(windowSize, ZSTD_BLOCKSIZE_MAX).
1531*01826a49SYabin Cui  *                     Unless you explicitly set the windowLog smaller than
1532*01826a49SYabin Cui  *                     ZSTD_BLOCKSIZELOG_MAX you can just use ZSTD_BLOCKSIZE_MAX.
1533*01826a49SYabin Cui  */
1534*01826a49SYabin Cui #define ZSTD_DECOMPRESSION_MARGIN(originalSize, blockSize) ((size_t)(                                              \
1535*01826a49SYabin Cui         ZSTD_FRAMEHEADERSIZE_MAX                                                              /* Frame header */ + \
1536*01826a49SYabin Cui         4                                                                                         /* checksum */ + \
1537*01826a49SYabin Cui         ((originalSize) == 0 ? 0 : 3 * (((originalSize) + (blockSize) - 1) / blockSize)) /* 3 bytes per block */ + \
1538*01826a49SYabin Cui         (blockSize)                                                                    /* One block of margin */   \
1539*01826a49SYabin Cui     ))
1540*01826a49SYabin Cui 
1541*01826a49SYabin Cui typedef enum {
1542*01826a49SYabin Cui   ZSTD_sf_noBlockDelimiters = 0,         /* Representation of ZSTD_Sequence has no block delimiters, sequences only */
1543*01826a49SYabin Cui   ZSTD_sf_explicitBlockDelimiters = 1    /* Representation of ZSTD_Sequence contains explicit block delimiters */
1544*01826a49SYabin Cui } ZSTD_sequenceFormat_e;
1545*01826a49SYabin Cui 
1546*01826a49SYabin Cui /*! ZSTD_sequenceBound() :
1547*01826a49SYabin Cui  * `srcSize` : size of the input buffer
1548*01826a49SYabin Cui  *  @return : upper-bound for the number of sequences that can be generated
1549*01826a49SYabin Cui  *            from a buffer of srcSize bytes
1550*01826a49SYabin Cui  *
1551*01826a49SYabin Cui  *  note : returns number of sequences - to get bytes, multiply by sizeof(ZSTD_Sequence).
1552*01826a49SYabin Cui  */
1553*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_sequenceBound(size_t srcSize);
1554*01826a49SYabin Cui 
1555*01826a49SYabin Cui /*! ZSTD_generateSequences() :
1556*01826a49SYabin Cui  * WARNING: This function is meant for debugging and informational purposes ONLY!
1557*01826a49SYabin Cui  * Its implementation is flawed, and it will be deleted in a future version.
1558*01826a49SYabin Cui  * It is not guaranteed to succeed, as there are several cases where it will give
1559*01826a49SYabin Cui  * up and fail. You should NOT use this function in production code.
1560*01826a49SYabin Cui  *
1561*01826a49SYabin Cui  * This function is deprecated, and will be removed in a future version.
1562*01826a49SYabin Cui  *
1563*01826a49SYabin Cui  * Generate sequences using ZSTD_compress2(), given a source buffer.
1564*01826a49SYabin Cui  *
1565*01826a49SYabin Cui  * @param zc The compression context to be used for ZSTD_compress2(). Set any
1566*01826a49SYabin Cui  *           compression parameters you need on this context.
1567*01826a49SYabin Cui  * @param outSeqs The output sequences buffer of size @p outSeqsSize
1568*01826a49SYabin Cui  * @param outSeqsSize The size of the output sequences buffer.
1569*01826a49SYabin Cui  *                    ZSTD_sequenceBound(srcSize) is an upper bound on the number
1570*01826a49SYabin Cui  *                    of sequences that can be generated.
1571*01826a49SYabin Cui  * @param src The source buffer to generate sequences from of size @p srcSize.
1572*01826a49SYabin Cui  * @param srcSize The size of the source buffer.
1573*01826a49SYabin Cui  *
1574*01826a49SYabin Cui  * Each block will end with a dummy sequence
1575*01826a49SYabin Cui  * with offset == 0, matchLength == 0, and litLength == length of last literals.
1576*01826a49SYabin Cui  * litLength may be == 0, and if so, then the sequence of (of: 0 ml: 0 ll: 0)
1577*01826a49SYabin Cui  * simply acts as a block delimiter.
1578*01826a49SYabin Cui  *
1579*01826a49SYabin Cui  * @returns The number of sequences generated, necessarily less than
1580*01826a49SYabin Cui  *          ZSTD_sequenceBound(srcSize), or an error code that can be checked
1581*01826a49SYabin Cui  *          with ZSTD_isError().
1582*01826a49SYabin Cui  */
1583*01826a49SYabin Cui ZSTD_DEPRECATED("For debugging only, will be replaced by ZSTD_extractSequences()")
1584*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t
1585*01826a49SYabin Cui ZSTD_generateSequences(ZSTD_CCtx* zc,
1586*01826a49SYabin Cui                        ZSTD_Sequence* outSeqs, size_t outSeqsSize,
1587*01826a49SYabin Cui                        const void* src, size_t srcSize);
1588*01826a49SYabin Cui 
1589*01826a49SYabin Cui /*! ZSTD_mergeBlockDelimiters() :
1590*01826a49SYabin Cui  * Given an array of ZSTD_Sequence, remove all sequences that represent block delimiters/last literals
1591*01826a49SYabin Cui  * by merging them into the literals of the next sequence.
1592*01826a49SYabin Cui  *
1593*01826a49SYabin Cui  * As such, the final generated result has no explicit representation of block boundaries,
1594*01826a49SYabin Cui  * and the final last literals segment is not represented in the sequences.
1595*01826a49SYabin Cui  *
1596*01826a49SYabin Cui  * The output of this function can be fed into ZSTD_compressSequences() with CCtx
1597*01826a49SYabin Cui  * setting of ZSTD_c_blockDelimiters as ZSTD_sf_noBlockDelimiters
1598*01826a49SYabin Cui  * @return : number of sequences left after merging
1599*01826a49SYabin Cui  */
1600*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_mergeBlockDelimiters(ZSTD_Sequence* sequences, size_t seqsSize);
1601*01826a49SYabin Cui 
1602*01826a49SYabin Cui /*! ZSTD_compressSequences() :
1603*01826a49SYabin Cui  * Compress an array of ZSTD_Sequence, associated with @src buffer, into dst.
1604*01826a49SYabin Cui  * @src contains the entire input (not just the literals).
1605*01826a49SYabin Cui  * If @srcSize > sum(sequence.length), the remaining bytes are considered all literals
1606*01826a49SYabin Cui  * If a dictionary is included, then the cctx should reference the dict. (see: ZSTD_CCtx_refCDict(), ZSTD_CCtx_loadDictionary(), etc.)
1607*01826a49SYabin Cui  * The entire source is compressed into a single frame.
1608*01826a49SYabin Cui  *
1609*01826a49SYabin Cui  * The compression behavior changes based on cctx params. In particular:
1610*01826a49SYabin Cui  *    If ZSTD_c_blockDelimiters == ZSTD_sf_noBlockDelimiters, the array of ZSTD_Sequence is expected to contain
1611*01826a49SYabin Cui  *    no block delimiters (defined in ZSTD_Sequence). Block boundaries are roughly determined based on
1612*01826a49SYabin Cui  *    the block size derived from the cctx, and sequences may be split. This is the default setting.
1613*01826a49SYabin Cui  *
1614*01826a49SYabin Cui  *    If ZSTD_c_blockDelimiters == ZSTD_sf_explicitBlockDelimiters, the array of ZSTD_Sequence is expected to contain
1615*01826a49SYabin Cui  *    block delimiters (defined in ZSTD_Sequence). Behavior is undefined if no block delimiters are provided.
1616*01826a49SYabin Cui  *
1617*01826a49SYabin Cui  *    If ZSTD_c_validateSequences == 0, this function will blindly accept the sequences provided. Invalid sequences cause undefined
1618*01826a49SYabin Cui  *    behavior. If ZSTD_c_validateSequences == 1, then if sequence is invalid (see doc/zstd_compression_format.md for
1619*01826a49SYabin Cui  *    specifics regarding offset/matchlength requirements) then the function will bail out and return an error.
1620*01826a49SYabin Cui  *
1621*01826a49SYabin Cui  *    In addition to the two adjustable experimental params, there are other important cctx params.
1622*01826a49SYabin Cui  *    - ZSTD_c_minMatch MUST be set as less than or equal to the smallest match generated by the match finder. It has a minimum value of ZSTD_MINMATCH_MIN.
1623*01826a49SYabin Cui  *    - ZSTD_c_compressionLevel accordingly adjusts the strength of the entropy coder, as it would in typical compression.
1624*01826a49SYabin Cui  *    - ZSTD_c_windowLog affects offset validation: this function will return an error at higher debug levels if a provided offset
1625*01826a49SYabin Cui  *      is larger than what the spec allows for a given window log and dictionary (if present). See: doc/zstd_compression_format.md
1626*01826a49SYabin Cui  *
1627*01826a49SYabin Cui  * Note: Repcodes are, as of now, always re-calculated within this function, so ZSTD_Sequence::rep is unused.
1628*01826a49SYabin Cui  * Note 2: Once we integrate ability to ingest repcodes, the explicit block delims mode must respect those repcodes exactly,
1629*01826a49SYabin Cui  *         and cannot emit an RLE block that disagrees with the repcode history
1630*01826a49SYabin Cui  * @return : final compressed size, or a ZSTD error code.
1631*01826a49SYabin Cui  */
1632*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t
1633*01826a49SYabin Cui ZSTD_compressSequences( ZSTD_CCtx* cctx, void* dst, size_t dstSize,
1634*01826a49SYabin Cui                         const ZSTD_Sequence* inSeqs, size_t inSeqsSize,
1635*01826a49SYabin Cui                         const void* src, size_t srcSize);
1636*01826a49SYabin Cui 
1637*01826a49SYabin Cui 
1638*01826a49SYabin Cui /*! ZSTD_writeSkippableFrame() :
1639*01826a49SYabin Cui  * Generates a zstd skippable frame containing data given by src, and writes it to dst buffer.
1640*01826a49SYabin Cui  *
1641*01826a49SYabin Cui  * Skippable frames begin with a 4-byte magic number. There are 16 possible choices of magic number,
1642*01826a49SYabin Cui  * ranging from ZSTD_MAGIC_SKIPPABLE_START to ZSTD_MAGIC_SKIPPABLE_START+15.
1643*01826a49SYabin Cui  * As such, the parameter magicVariant controls the exact skippable frame magic number variant used, so
1644*01826a49SYabin Cui  * the magic number used will be ZSTD_MAGIC_SKIPPABLE_START + magicVariant.
1645*01826a49SYabin Cui  *
1646*01826a49SYabin Cui  * Returns an error if destination buffer is not large enough, if the source size is not representable
1647*01826a49SYabin Cui  * with a 4-byte unsigned int, or if the parameter magicVariant is greater than 15 (and therefore invalid).
1648*01826a49SYabin Cui  *
1649*01826a49SYabin Cui  * @return : number of bytes written or a ZSTD error.
1650*01826a49SYabin Cui  */
1651*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_writeSkippableFrame(void* dst, size_t dstCapacity,
1652*01826a49SYabin Cui                                             const void* src, size_t srcSize, unsigned magicVariant);
1653*01826a49SYabin Cui 
1654*01826a49SYabin Cui /*! ZSTD_readSkippableFrame() :
1655*01826a49SYabin Cui  * Retrieves a zstd skippable frame containing data given by src, and writes it to dst buffer.
1656*01826a49SYabin Cui  *
1657*01826a49SYabin Cui  * The parameter magicVariant will receive the magicVariant that was supplied when the frame was written,
1658*01826a49SYabin Cui  * i.e. magicNumber - ZSTD_MAGIC_SKIPPABLE_START.  This can be NULL if the caller is not interested
1659*01826a49SYabin Cui  * in the magicVariant.
1660*01826a49SYabin Cui  *
1661*01826a49SYabin Cui  * Returns an error if destination buffer is not large enough, or if the frame is not skippable.
1662*01826a49SYabin Cui  *
1663*01826a49SYabin Cui  * @return : number of bytes written or a ZSTD error.
1664*01826a49SYabin Cui  */
1665*01826a49SYabin Cui ZSTDLIB_API size_t ZSTD_readSkippableFrame(void* dst, size_t dstCapacity, unsigned* magicVariant,
1666*01826a49SYabin Cui                                             const void* src, size_t srcSize);
1667*01826a49SYabin Cui 
1668*01826a49SYabin Cui /*! ZSTD_isSkippableFrame() :
1669*01826a49SYabin Cui  *  Tells if the content of `buffer` starts with a valid Frame Identifier for a skippable frame.
1670*01826a49SYabin Cui  */
1671*01826a49SYabin Cui ZSTDLIB_API unsigned ZSTD_isSkippableFrame(const void* buffer, size_t size);
1672*01826a49SYabin Cui 
1673*01826a49SYabin Cui 
1674*01826a49SYabin Cui 
1675*01826a49SYabin Cui /***************************************
1676*01826a49SYabin Cui *  Memory management
1677*01826a49SYabin Cui ***************************************/
1678*01826a49SYabin Cui 
1679*01826a49SYabin Cui /*! ZSTD_estimate*() :
1680*01826a49SYabin Cui  *  These functions make it possible to estimate memory usage
1681*01826a49SYabin Cui  *  of a future {D,C}Ctx, before its creation.
1682*01826a49SYabin Cui  *  This is useful in combination with ZSTD_initStatic(),
1683*01826a49SYabin Cui  *  which makes it possible to employ a static buffer for ZSTD_CCtx* state.
1684*01826a49SYabin Cui  *
1685*01826a49SYabin Cui  *  ZSTD_estimateCCtxSize() will provide a memory budget large enough
1686*01826a49SYabin Cui  *  to compress data of any size using one-shot compression ZSTD_compressCCtx() or ZSTD_compress2()
1687*01826a49SYabin Cui  *  associated with any compression level up to max specified one.
1688*01826a49SYabin Cui  *  The estimate will assume the input may be arbitrarily large,
1689*01826a49SYabin Cui  *  which is the worst case.
1690*01826a49SYabin Cui  *
1691*01826a49SYabin Cui  *  Note that the size estimation is specific for one-shot compression,
1692*01826a49SYabin Cui  *  it is not valid for streaming (see ZSTD_estimateCStreamSize*())
1693*01826a49SYabin Cui  *  nor other potential ways of using a ZSTD_CCtx* state.
1694*01826a49SYabin Cui  *
1695*01826a49SYabin Cui  *  When srcSize can be bound by a known and rather "small" value,
1696*01826a49SYabin Cui  *  this knowledge can be used to provide a tighter budget estimation
1697*01826a49SYabin Cui  *  because the ZSTD_CCtx* state will need less memory for small inputs.
1698*01826a49SYabin Cui  *  This tighter estimation can be provided by employing more advanced functions
1699*01826a49SYabin Cui  *  ZSTD_estimateCCtxSize_usingCParams(), which can be used in tandem with ZSTD_getCParams(),
1700*01826a49SYabin Cui  *  and ZSTD_estimateCCtxSize_usingCCtxParams(), which can be used in tandem with ZSTD_CCtxParams_setParameter().
1701*01826a49SYabin Cui  *  Both can be used to estimate memory using custom compression parameters and arbitrary srcSize limits.
1702*01826a49SYabin Cui  *
1703*01826a49SYabin Cui  *  Note : only single-threaded compression is supported.
1704*01826a49SYabin Cui  *  ZSTD_estimateCCtxSize_usingCCtxParams() will return an error code if ZSTD_c_nbWorkers is >= 1.
1705*01826a49SYabin Cui  */
1706*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_estimateCCtxSize(int maxCompressionLevel);
1707*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_estimateCCtxSize_usingCParams(ZSTD_compressionParameters cParams);
1708*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_estimateCCtxSize_usingCCtxParams(const ZSTD_CCtx_params* params);
1709*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_estimateDCtxSize(void);
1710*01826a49SYabin Cui 
1711*01826a49SYabin Cui /*! ZSTD_estimateCStreamSize() :
1712*01826a49SYabin Cui  *  ZSTD_estimateCStreamSize() will provide a memory budget large enough for streaming compression
1713*01826a49SYabin Cui  *  using any compression level up to the max specified one.
1714*01826a49SYabin Cui  *  It will also consider src size to be arbitrarily "large", which is a worst case scenario.
1715*01826a49SYabin Cui  *  If srcSize is known to always be small, ZSTD_estimateCStreamSize_usingCParams() can provide a tighter estimation.
1716*01826a49SYabin Cui  *  ZSTD_estimateCStreamSize_usingCParams() can be used in tandem with ZSTD_getCParams() to create cParams from compressionLevel.
1717*01826a49SYabin Cui  *  ZSTD_estimateCStreamSize_usingCCtxParams() can be used in tandem with ZSTD_CCtxParams_setParameter(). Only single-threaded compression is supported. This function will return an error code if ZSTD_c_nbWorkers is >= 1.
1718*01826a49SYabin Cui  *  Note : CStream size estimation is only correct for single-threaded compression.
1719*01826a49SYabin Cui  *  ZSTD_estimateCStreamSize_usingCCtxParams() will return an error code if ZSTD_c_nbWorkers is >= 1.
1720*01826a49SYabin Cui  *  Note 2 : ZSTD_estimateCStreamSize* functions are not compatible with the Block-Level Sequence Producer API at this time.
1721*01826a49SYabin Cui  *  Size estimates assume that no external sequence producer is registered.
1722*01826a49SYabin Cui  *
1723*01826a49SYabin Cui  *  ZSTD_DStream memory budget depends on frame's window Size.
1724*01826a49SYabin Cui  *  This information can be passed manually, using ZSTD_estimateDStreamSize,
1725*01826a49SYabin Cui  *  or deducted from a valid frame Header, using ZSTD_estimateDStreamSize_fromFrame();
1726*01826a49SYabin Cui  *  Any frame requesting a window size larger than max specified one will be rejected.
1727*01826a49SYabin Cui  *  Note : if streaming is init with function ZSTD_init?Stream_usingDict(),
1728*01826a49SYabin Cui  *         an internal ?Dict will be created, which additional size is not estimated here.
1729*01826a49SYabin Cui  *         In this case, get total size by adding ZSTD_estimate?DictSize
1730*01826a49SYabin Cui  */
1731*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_estimateCStreamSize(int maxCompressionLevel);
1732*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_estimateCStreamSize_usingCParams(ZSTD_compressionParameters cParams);
1733*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_estimateCStreamSize_usingCCtxParams(const ZSTD_CCtx_params* params);
1734*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_estimateDStreamSize(size_t maxWindowSize);
1735*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_estimateDStreamSize_fromFrame(const void* src, size_t srcSize);
1736*01826a49SYabin Cui 
1737*01826a49SYabin Cui /*! ZSTD_estimate?DictSize() :
1738*01826a49SYabin Cui  *  ZSTD_estimateCDictSize() will bet that src size is relatively "small", and content is copied, like ZSTD_createCDict().
1739*01826a49SYabin Cui  *  ZSTD_estimateCDictSize_advanced() makes it possible to control compression parameters precisely, like ZSTD_createCDict_advanced().
1740*01826a49SYabin Cui  *  Note : dictionaries created by reference (`ZSTD_dlm_byRef`) are logically smaller.
1741*01826a49SYabin Cui  */
1742*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_estimateCDictSize(size_t dictSize, int compressionLevel);
1743*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_estimateCDictSize_advanced(size_t dictSize, ZSTD_compressionParameters cParams, ZSTD_dictLoadMethod_e dictLoadMethod);
1744*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_estimateDDictSize(size_t dictSize, ZSTD_dictLoadMethod_e dictLoadMethod);
1745*01826a49SYabin Cui 
1746*01826a49SYabin Cui /*! ZSTD_initStatic*() :
1747*01826a49SYabin Cui  *  Initialize an object using a pre-allocated fixed-size buffer.
1748*01826a49SYabin Cui  *  workspace: The memory area to emplace the object into.
1749*01826a49SYabin Cui  *             Provided pointer *must be 8-bytes aligned*.
1750*01826a49SYabin Cui  *             Buffer must outlive object.
1751*01826a49SYabin Cui  *  workspaceSize: Use ZSTD_estimate*Size() to determine
1752*01826a49SYabin Cui  *                 how large workspace must be to support target scenario.
1753*01826a49SYabin Cui  * @return : pointer to object (same address as workspace, just different type),
1754*01826a49SYabin Cui  *           or NULL if error (size too small, incorrect alignment, etc.)
1755*01826a49SYabin Cui  *  Note : zstd will never resize nor malloc() when using a static buffer.
1756*01826a49SYabin Cui  *         If the object requires more memory than available,
1757*01826a49SYabin Cui  *         zstd will just error out (typically ZSTD_error_memory_allocation).
1758*01826a49SYabin Cui  *  Note 2 : there is no corresponding "free" function.
1759*01826a49SYabin Cui  *           Since workspace is allocated externally, it must be freed externally too.
1760*01826a49SYabin Cui  *  Note 3 : cParams : use ZSTD_getCParams() to convert a compression level
1761*01826a49SYabin Cui  *           into its associated cParams.
1762*01826a49SYabin Cui  *  Limitation 1 : currently not compatible with internal dictionary creation, triggered by
1763*01826a49SYabin Cui  *                 ZSTD_CCtx_loadDictionary(), ZSTD_initCStream_usingDict() or ZSTD_initDStream_usingDict().
1764*01826a49SYabin Cui  *  Limitation 2 : static cctx currently not compatible with multi-threading.
1765*01826a49SYabin Cui  *  Limitation 3 : static dctx is incompatible with legacy support.
1766*01826a49SYabin Cui  */
1767*01826a49SYabin Cui ZSTDLIB_STATIC_API ZSTD_CCtx*    ZSTD_initStaticCCtx(void* workspace, size_t workspaceSize);
1768*01826a49SYabin Cui ZSTDLIB_STATIC_API ZSTD_CStream* ZSTD_initStaticCStream(void* workspace, size_t workspaceSize);    /**< same as ZSTD_initStaticCCtx() */
1769*01826a49SYabin Cui 
1770*01826a49SYabin Cui ZSTDLIB_STATIC_API ZSTD_DCtx*    ZSTD_initStaticDCtx(void* workspace, size_t workspaceSize);
1771*01826a49SYabin Cui ZSTDLIB_STATIC_API ZSTD_DStream* ZSTD_initStaticDStream(void* workspace, size_t workspaceSize);    /**< same as ZSTD_initStaticDCtx() */
1772*01826a49SYabin Cui 
1773*01826a49SYabin Cui ZSTDLIB_STATIC_API const ZSTD_CDict* ZSTD_initStaticCDict(
1774*01826a49SYabin Cui                                         void* workspace, size_t workspaceSize,
1775*01826a49SYabin Cui                                         const void* dict, size_t dictSize,
1776*01826a49SYabin Cui                                         ZSTD_dictLoadMethod_e dictLoadMethod,
1777*01826a49SYabin Cui                                         ZSTD_dictContentType_e dictContentType,
1778*01826a49SYabin Cui                                         ZSTD_compressionParameters cParams);
1779*01826a49SYabin Cui 
1780*01826a49SYabin Cui ZSTDLIB_STATIC_API const ZSTD_DDict* ZSTD_initStaticDDict(
1781*01826a49SYabin Cui                                         void* workspace, size_t workspaceSize,
1782*01826a49SYabin Cui                                         const void* dict, size_t dictSize,
1783*01826a49SYabin Cui                                         ZSTD_dictLoadMethod_e dictLoadMethod,
1784*01826a49SYabin Cui                                         ZSTD_dictContentType_e dictContentType);
1785*01826a49SYabin Cui 
1786*01826a49SYabin Cui 
1787*01826a49SYabin Cui /*! Custom memory allocation :
1788*01826a49SYabin Cui  *  These prototypes make it possible to pass your own allocation/free functions.
1789*01826a49SYabin Cui  *  ZSTD_customMem is provided at creation time, using ZSTD_create*_advanced() variants listed below.
1790*01826a49SYabin Cui  *  All allocation/free operations will be completed using these custom variants instead of regular <stdlib.h> ones.
1791*01826a49SYabin Cui  */
1792*01826a49SYabin Cui typedef void* (*ZSTD_allocFunction) (void* opaque, size_t size);
1793*01826a49SYabin Cui typedef void  (*ZSTD_freeFunction) (void* opaque, void* address);
1794*01826a49SYabin Cui typedef struct { ZSTD_allocFunction customAlloc; ZSTD_freeFunction customFree; void* opaque; } ZSTD_customMem;
1795*01826a49SYabin Cui static
1796*01826a49SYabin Cui #ifdef __GNUC__
1797*01826a49SYabin Cui __attribute__((__unused__))
1798*01826a49SYabin Cui #endif
1799*01826a49SYabin Cui ZSTD_customMem const ZSTD_defaultCMem = { NULL, NULL, NULL };  /**< this constant defers to stdlib's functions */
1800*01826a49SYabin Cui 
1801*01826a49SYabin Cui ZSTDLIB_STATIC_API ZSTD_CCtx*    ZSTD_createCCtx_advanced(ZSTD_customMem customMem);
1802*01826a49SYabin Cui ZSTDLIB_STATIC_API ZSTD_CStream* ZSTD_createCStream_advanced(ZSTD_customMem customMem);
1803*01826a49SYabin Cui ZSTDLIB_STATIC_API ZSTD_DCtx*    ZSTD_createDCtx_advanced(ZSTD_customMem customMem);
1804*01826a49SYabin Cui ZSTDLIB_STATIC_API ZSTD_DStream* ZSTD_createDStream_advanced(ZSTD_customMem customMem);
1805*01826a49SYabin Cui 
1806*01826a49SYabin Cui ZSTDLIB_STATIC_API ZSTD_CDict* ZSTD_createCDict_advanced(const void* dict, size_t dictSize,
1807*01826a49SYabin Cui                                                   ZSTD_dictLoadMethod_e dictLoadMethod,
1808*01826a49SYabin Cui                                                   ZSTD_dictContentType_e dictContentType,
1809*01826a49SYabin Cui                                                   ZSTD_compressionParameters cParams,
1810*01826a49SYabin Cui                                                   ZSTD_customMem customMem);
1811*01826a49SYabin Cui 
1812*01826a49SYabin Cui /*! Thread pool :
1813*01826a49SYabin Cui  *  These prototypes make it possible to share a thread pool among multiple compression contexts.
1814*01826a49SYabin Cui  *  This can limit resources for applications with multiple threads where each one uses
1815*01826a49SYabin Cui  *  a threaded compression mode (via ZSTD_c_nbWorkers parameter).
1816*01826a49SYabin Cui  *  ZSTD_createThreadPool creates a new thread pool with a given number of threads.
1817*01826a49SYabin Cui  *  Note that the lifetime of such pool must exist while being used.
1818*01826a49SYabin Cui  *  ZSTD_CCtx_refThreadPool assigns a thread pool to a context (use NULL argument value
1819*01826a49SYabin Cui  *  to use an internal thread pool).
1820*01826a49SYabin Cui  *  ZSTD_freeThreadPool frees a thread pool, accepts NULL pointer.
1821*01826a49SYabin Cui  */
1822*01826a49SYabin Cui typedef struct POOL_ctx_s ZSTD_threadPool;
1823*01826a49SYabin Cui ZSTDLIB_STATIC_API ZSTD_threadPool* ZSTD_createThreadPool(size_t numThreads);
1824*01826a49SYabin Cui ZSTDLIB_STATIC_API void ZSTD_freeThreadPool (ZSTD_threadPool* pool);  /* accept NULL pointer */
1825*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_CCtx_refThreadPool(ZSTD_CCtx* cctx, ZSTD_threadPool* pool);
1826*01826a49SYabin Cui 
1827*01826a49SYabin Cui 
1828*01826a49SYabin Cui /*
1829*01826a49SYabin Cui  * This API is temporary and is expected to change or disappear in the future!
1830*01826a49SYabin Cui  */
1831*01826a49SYabin Cui ZSTDLIB_STATIC_API ZSTD_CDict* ZSTD_createCDict_advanced2(
1832*01826a49SYabin Cui     const void* dict, size_t dictSize,
1833*01826a49SYabin Cui     ZSTD_dictLoadMethod_e dictLoadMethod,
1834*01826a49SYabin Cui     ZSTD_dictContentType_e dictContentType,
1835*01826a49SYabin Cui     const ZSTD_CCtx_params* cctxParams,
1836*01826a49SYabin Cui     ZSTD_customMem customMem);
1837*01826a49SYabin Cui 
1838*01826a49SYabin Cui ZSTDLIB_STATIC_API ZSTD_DDict* ZSTD_createDDict_advanced(
1839*01826a49SYabin Cui     const void* dict, size_t dictSize,
1840*01826a49SYabin Cui     ZSTD_dictLoadMethod_e dictLoadMethod,
1841*01826a49SYabin Cui     ZSTD_dictContentType_e dictContentType,
1842*01826a49SYabin Cui     ZSTD_customMem customMem);
1843*01826a49SYabin Cui 
1844*01826a49SYabin Cui 
1845*01826a49SYabin Cui /***************************************
1846*01826a49SYabin Cui *  Advanced compression functions
1847*01826a49SYabin Cui ***************************************/
1848*01826a49SYabin Cui 
1849*01826a49SYabin Cui /*! ZSTD_createCDict_byReference() :
1850*01826a49SYabin Cui  *  Create a digested dictionary for compression
1851*01826a49SYabin Cui  *  Dictionary content is just referenced, not duplicated.
1852*01826a49SYabin Cui  *  As a consequence, `dictBuffer` **must** outlive CDict,
1853*01826a49SYabin Cui  *  and its content must remain unmodified throughout the lifetime of CDict.
1854*01826a49SYabin Cui  *  note: equivalent to ZSTD_createCDict_advanced(), with dictLoadMethod==ZSTD_dlm_byRef */
1855*01826a49SYabin Cui ZSTDLIB_STATIC_API ZSTD_CDict* ZSTD_createCDict_byReference(const void* dictBuffer, size_t dictSize, int compressionLevel);
1856*01826a49SYabin Cui 
1857*01826a49SYabin Cui /*! ZSTD_getCParams() :
1858*01826a49SYabin Cui  * @return ZSTD_compressionParameters structure for a selected compression level and estimated srcSize.
1859*01826a49SYabin Cui  * `estimatedSrcSize` value is optional, select 0 if not known */
1860*01826a49SYabin Cui ZSTDLIB_STATIC_API ZSTD_compressionParameters ZSTD_getCParams(int compressionLevel, unsigned long long estimatedSrcSize, size_t dictSize);
1861*01826a49SYabin Cui 
1862*01826a49SYabin Cui /*! ZSTD_getParams() :
1863*01826a49SYabin Cui  *  same as ZSTD_getCParams(), but @return a full `ZSTD_parameters` object instead of sub-component `ZSTD_compressionParameters`.
1864*01826a49SYabin Cui  *  All fields of `ZSTD_frameParameters` are set to default : contentSize=1, checksum=0, noDictID=0 */
1865*01826a49SYabin Cui ZSTDLIB_STATIC_API ZSTD_parameters ZSTD_getParams(int compressionLevel, unsigned long long estimatedSrcSize, size_t dictSize);
1866*01826a49SYabin Cui 
1867*01826a49SYabin Cui /*! ZSTD_checkCParams() :
1868*01826a49SYabin Cui  *  Ensure param values remain within authorized range.
1869*01826a49SYabin Cui  * @return 0 on success, or an error code (can be checked with ZSTD_isError()) */
1870*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_checkCParams(ZSTD_compressionParameters params);
1871*01826a49SYabin Cui 
1872*01826a49SYabin Cui /*! ZSTD_adjustCParams() :
1873*01826a49SYabin Cui  *  optimize params for a given `srcSize` and `dictSize`.
1874*01826a49SYabin Cui  * `srcSize` can be unknown, in which case use ZSTD_CONTENTSIZE_UNKNOWN.
1875*01826a49SYabin Cui  * `dictSize` must be `0` when there is no dictionary.
1876*01826a49SYabin Cui  *  cPar can be invalid : all parameters will be clamped within valid range in the @return struct.
1877*01826a49SYabin Cui  *  This function never fails (wide contract) */
1878*01826a49SYabin Cui ZSTDLIB_STATIC_API ZSTD_compressionParameters ZSTD_adjustCParams(ZSTD_compressionParameters cPar, unsigned long long srcSize, size_t dictSize);
1879*01826a49SYabin Cui 
1880*01826a49SYabin Cui /*! ZSTD_CCtx_setCParams() :
1881*01826a49SYabin Cui  *  Set all parameters provided within @p cparams into the working @p cctx.
1882*01826a49SYabin Cui  *  Note : if modifying parameters during compression (MT mode only),
1883*01826a49SYabin Cui  *         note that changes to the .windowLog parameter will be ignored.
1884*01826a49SYabin Cui  * @return 0 on success, or an error code (can be checked with ZSTD_isError()).
1885*01826a49SYabin Cui  *         On failure, no parameters are updated.
1886*01826a49SYabin Cui  */
1887*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_CCtx_setCParams(ZSTD_CCtx* cctx, ZSTD_compressionParameters cparams);
1888*01826a49SYabin Cui 
1889*01826a49SYabin Cui /*! ZSTD_CCtx_setFParams() :
1890*01826a49SYabin Cui  *  Set all parameters provided within @p fparams into the working @p cctx.
1891*01826a49SYabin Cui  * @return 0 on success, or an error code (can be checked with ZSTD_isError()).
1892*01826a49SYabin Cui  */
1893*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_CCtx_setFParams(ZSTD_CCtx* cctx, ZSTD_frameParameters fparams);
1894*01826a49SYabin Cui 
1895*01826a49SYabin Cui /*! ZSTD_CCtx_setParams() :
1896*01826a49SYabin Cui  *  Set all parameters provided within @p params into the working @p cctx.
1897*01826a49SYabin Cui  * @return 0 on success, or an error code (can be checked with ZSTD_isError()).
1898*01826a49SYabin Cui  */
1899*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_CCtx_setParams(ZSTD_CCtx* cctx, ZSTD_parameters params);
1900*01826a49SYabin Cui 
1901*01826a49SYabin Cui /*! ZSTD_compress_advanced() :
1902*01826a49SYabin Cui  *  Note : this function is now DEPRECATED.
1903*01826a49SYabin Cui  *         It can be replaced by ZSTD_compress2(), in combination with ZSTD_CCtx_setParameter() and other parameter setters.
1904*01826a49SYabin Cui  *  This prototype will generate compilation warnings. */
1905*01826a49SYabin Cui ZSTD_DEPRECATED("use ZSTD_compress2")
1906*01826a49SYabin Cui ZSTDLIB_STATIC_API
1907*01826a49SYabin Cui size_t ZSTD_compress_advanced(ZSTD_CCtx* cctx,
1908*01826a49SYabin Cui                               void* dst, size_t dstCapacity,
1909*01826a49SYabin Cui                         const void* src, size_t srcSize,
1910*01826a49SYabin Cui                         const void* dict,size_t dictSize,
1911*01826a49SYabin Cui                               ZSTD_parameters params);
1912*01826a49SYabin Cui 
1913*01826a49SYabin Cui /*! ZSTD_compress_usingCDict_advanced() :
1914*01826a49SYabin Cui  *  Note : this function is now DEPRECATED.
1915*01826a49SYabin Cui  *         It can be replaced by ZSTD_compress2(), in combination with ZSTD_CCtx_loadDictionary() and other parameter setters.
1916*01826a49SYabin Cui  *  This prototype will generate compilation warnings. */
1917*01826a49SYabin Cui ZSTD_DEPRECATED("use ZSTD_compress2 with ZSTD_CCtx_loadDictionary")
1918*01826a49SYabin Cui ZSTDLIB_STATIC_API
1919*01826a49SYabin Cui size_t ZSTD_compress_usingCDict_advanced(ZSTD_CCtx* cctx,
1920*01826a49SYabin Cui                                               void* dst, size_t dstCapacity,
1921*01826a49SYabin Cui                                         const void* src, size_t srcSize,
1922*01826a49SYabin Cui                                         const ZSTD_CDict* cdict,
1923*01826a49SYabin Cui                                               ZSTD_frameParameters fParams);
1924*01826a49SYabin Cui 
1925*01826a49SYabin Cui 
1926*01826a49SYabin Cui /*! ZSTD_CCtx_loadDictionary_byReference() :
1927*01826a49SYabin Cui  *  Same as ZSTD_CCtx_loadDictionary(), but dictionary content is referenced, instead of being copied into CCtx.
1928*01826a49SYabin Cui  *  It saves some memory, but also requires that `dict` outlives its usage within `cctx` */
1929*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_CCtx_loadDictionary_byReference(ZSTD_CCtx* cctx, const void* dict, size_t dictSize);
1930*01826a49SYabin Cui 
1931*01826a49SYabin Cui /*! ZSTD_CCtx_loadDictionary_advanced() :
1932*01826a49SYabin Cui  *  Same as ZSTD_CCtx_loadDictionary(), but gives finer control over
1933*01826a49SYabin Cui  *  how to load the dictionary (by copy ? by reference ?)
1934*01826a49SYabin Cui  *  and how to interpret it (automatic ? force raw mode ? full mode only ?) */
1935*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_CCtx_loadDictionary_advanced(ZSTD_CCtx* cctx, const void* dict, size_t dictSize, ZSTD_dictLoadMethod_e dictLoadMethod, ZSTD_dictContentType_e dictContentType);
1936*01826a49SYabin Cui 
1937*01826a49SYabin Cui /*! ZSTD_CCtx_refPrefix_advanced() :
1938*01826a49SYabin Cui  *  Same as ZSTD_CCtx_refPrefix(), but gives finer control over
1939*01826a49SYabin Cui  *  how to interpret prefix content (automatic ? force raw mode (default) ? full mode only ?) */
1940*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_CCtx_refPrefix_advanced(ZSTD_CCtx* cctx, const void* prefix, size_t prefixSize, ZSTD_dictContentType_e dictContentType);
1941*01826a49SYabin Cui 
1942*01826a49SYabin Cui /* ===   experimental parameters   === */
1943*01826a49SYabin Cui /* these parameters can be used with ZSTD_setParameter()
1944*01826a49SYabin Cui  * they are not guaranteed to remain supported in the future */
1945*01826a49SYabin Cui 
1946*01826a49SYabin Cui  /* Enables rsyncable mode,
1947*01826a49SYabin Cui   * which makes compressed files more rsync friendly
1948*01826a49SYabin Cui   * by adding periodic synchronization points to the compressed data.
1949*01826a49SYabin Cui   * The target average block size is ZSTD_c_jobSize / 2.
1950*01826a49SYabin Cui   * It's possible to modify the job size to increase or decrease
1951*01826a49SYabin Cui   * the granularity of the synchronization point.
1952*01826a49SYabin Cui   * Once the jobSize is smaller than the window size,
1953*01826a49SYabin Cui   * it will result in compression ratio degradation.
1954*01826a49SYabin Cui   * NOTE 1: rsyncable mode only works when multithreading is enabled.
1955*01826a49SYabin Cui   * NOTE 2: rsyncable performs poorly in combination with long range mode,
1956*01826a49SYabin Cui   * since it will decrease the effectiveness of synchronization points,
1957*01826a49SYabin Cui   * though mileage may vary.
1958*01826a49SYabin Cui   * NOTE 3: Rsyncable mode limits maximum compression speed to ~400 MB/s.
1959*01826a49SYabin Cui   * If the selected compression level is already running significantly slower,
1960*01826a49SYabin Cui   * the overall speed won't be significantly impacted.
1961*01826a49SYabin Cui   */
1962*01826a49SYabin Cui  #define ZSTD_c_rsyncable ZSTD_c_experimentalParam1
1963*01826a49SYabin Cui 
1964*01826a49SYabin Cui /* Select a compression format.
1965*01826a49SYabin Cui  * The value must be of type ZSTD_format_e.
1966*01826a49SYabin Cui  * See ZSTD_format_e enum definition for details */
1967*01826a49SYabin Cui #define ZSTD_c_format ZSTD_c_experimentalParam2
1968*01826a49SYabin Cui 
1969*01826a49SYabin Cui /* Force back-reference distances to remain < windowSize,
1970*01826a49SYabin Cui  * even when referencing into Dictionary content (default:0) */
1971*01826a49SYabin Cui #define ZSTD_c_forceMaxWindow ZSTD_c_experimentalParam3
1972*01826a49SYabin Cui 
1973*01826a49SYabin Cui /* Controls whether the contents of a CDict
1974*01826a49SYabin Cui  * are used in place, or copied into the working context.
1975*01826a49SYabin Cui  * Accepts values from the ZSTD_dictAttachPref_e enum.
1976*01826a49SYabin Cui  * See the comments on that enum for an explanation of the feature. */
1977*01826a49SYabin Cui #define ZSTD_c_forceAttachDict ZSTD_c_experimentalParam4
1978*01826a49SYabin Cui 
1979*01826a49SYabin Cui /* Controlled with ZSTD_paramSwitch_e enum.
1980*01826a49SYabin Cui  * Default is ZSTD_ps_auto.
1981*01826a49SYabin Cui  * Set to ZSTD_ps_disable to never compress literals.
1982*01826a49SYabin Cui  * Set to ZSTD_ps_enable to always compress literals. (Note: uncompressed literals
1983*01826a49SYabin Cui  * may still be emitted if huffman is not beneficial to use.)
1984*01826a49SYabin Cui  *
1985*01826a49SYabin Cui  * By default, in ZSTD_ps_auto, the library will decide at runtime whether to use
1986*01826a49SYabin Cui  * literals compression based on the compression parameters - specifically,
1987*01826a49SYabin Cui  * negative compression levels do not use literal compression.
1988*01826a49SYabin Cui  */
1989*01826a49SYabin Cui #define ZSTD_c_literalCompressionMode ZSTD_c_experimentalParam5
1990*01826a49SYabin Cui 
1991*01826a49SYabin Cui /* User's best guess of source size.
1992*01826a49SYabin Cui  * Hint is not valid when srcSizeHint == 0.
1993*01826a49SYabin Cui  * There is no guarantee that hint is close to actual source size,
1994*01826a49SYabin Cui  * but compression ratio may regress significantly if guess considerably underestimates */
1995*01826a49SYabin Cui #define ZSTD_c_srcSizeHint ZSTD_c_experimentalParam7
1996*01826a49SYabin Cui 
1997*01826a49SYabin Cui /* Controls whether the new and experimental "dedicated dictionary search
1998*01826a49SYabin Cui  * structure" can be used. This feature is still rough around the edges, be
1999*01826a49SYabin Cui  * prepared for surprising behavior!
2000*01826a49SYabin Cui  *
2001*01826a49SYabin Cui  * How to use it:
2002*01826a49SYabin Cui  *
2003*01826a49SYabin Cui  * When using a CDict, whether to use this feature or not is controlled at
2004*01826a49SYabin Cui  * CDict creation, and it must be set in a CCtxParams set passed into that
2005*01826a49SYabin Cui  * construction (via ZSTD_createCDict_advanced2()). A compression will then
2006*01826a49SYabin Cui  * use the feature or not based on how the CDict was constructed; the value of
2007*01826a49SYabin Cui  * this param, set in the CCtx, will have no effect.
2008*01826a49SYabin Cui  *
2009*01826a49SYabin Cui  * However, when a dictionary buffer is passed into a CCtx, such as via
2010*01826a49SYabin Cui  * ZSTD_CCtx_loadDictionary(), this param can be set on the CCtx to control
2011*01826a49SYabin Cui  * whether the CDict that is created internally can use the feature or not.
2012*01826a49SYabin Cui  *
2013*01826a49SYabin Cui  * What it does:
2014*01826a49SYabin Cui  *
2015*01826a49SYabin Cui  * Normally, the internal data structures of the CDict are analogous to what
2016*01826a49SYabin Cui  * would be stored in a CCtx after compressing the contents of a dictionary.
2017*01826a49SYabin Cui  * To an approximation, a compression using a dictionary can then use those
2018*01826a49SYabin Cui  * data structures to simply continue what is effectively a streaming
2019*01826a49SYabin Cui  * compression where the simulated compression of the dictionary left off.
2020*01826a49SYabin Cui  * Which is to say, the search structures in the CDict are normally the same
2021*01826a49SYabin Cui  * format as in the CCtx.
2022*01826a49SYabin Cui  *
2023*01826a49SYabin Cui  * It is possible to do better, since the CDict is not like a CCtx: the search
2024*01826a49SYabin Cui  * structures are written once during CDict creation, and then are only read
2025*01826a49SYabin Cui  * after that, while the search structures in the CCtx are both read and
2026*01826a49SYabin Cui  * written as the compression goes along. This means we can choose a search
2027*01826a49SYabin Cui  * structure for the dictionary that is read-optimized.
2028*01826a49SYabin Cui  *
2029*01826a49SYabin Cui  * This feature enables the use of that different structure.
2030*01826a49SYabin Cui  *
2031*01826a49SYabin Cui  * Note that some of the members of the ZSTD_compressionParameters struct have
2032*01826a49SYabin Cui  * different semantics and constraints in the dedicated search structure. It is
2033*01826a49SYabin Cui  * highly recommended that you simply set a compression level in the CCtxParams
2034*01826a49SYabin Cui  * you pass into the CDict creation call, and avoid messing with the cParams
2035*01826a49SYabin Cui  * directly.
2036*01826a49SYabin Cui  *
2037*01826a49SYabin Cui  * Effects:
2038*01826a49SYabin Cui  *
2039*01826a49SYabin Cui  * This will only have any effect when the selected ZSTD_strategy
2040*01826a49SYabin Cui  * implementation supports this feature. Currently, that's limited to
2041*01826a49SYabin Cui  * ZSTD_greedy, ZSTD_lazy, and ZSTD_lazy2.
2042*01826a49SYabin Cui  *
2043*01826a49SYabin Cui  * Note that this means that the CDict tables can no longer be copied into the
2044*01826a49SYabin Cui  * CCtx, so the dict attachment mode ZSTD_dictForceCopy will no longer be
2045*01826a49SYabin Cui  * usable. The dictionary can only be attached or reloaded.
2046*01826a49SYabin Cui  *
2047*01826a49SYabin Cui  * In general, you should expect compression to be faster--sometimes very much
2048*01826a49SYabin Cui  * so--and CDict creation to be slightly slower. Eventually, we will probably
2049*01826a49SYabin Cui  * make this mode the default.
2050*01826a49SYabin Cui  */
2051*01826a49SYabin Cui #define ZSTD_c_enableDedicatedDictSearch ZSTD_c_experimentalParam8
2052*01826a49SYabin Cui 
2053*01826a49SYabin Cui /* ZSTD_c_stableInBuffer
2054*01826a49SYabin Cui  * Experimental parameter.
2055*01826a49SYabin Cui  * Default is 0 == disabled. Set to 1 to enable.
2056*01826a49SYabin Cui  *
2057*01826a49SYabin Cui  * Tells the compressor that input data presented with ZSTD_inBuffer
2058*01826a49SYabin Cui  * will ALWAYS be the same between calls.
2059*01826a49SYabin Cui  * Technically, the @src pointer must never be changed,
2060*01826a49SYabin Cui  * and the @pos field can only be updated by zstd.
2061*01826a49SYabin Cui  * However, it's possible to increase the @size field,
2062*01826a49SYabin Cui  * allowing scenarios where more data can be appended after compressions starts.
2063*01826a49SYabin Cui  * These conditions are checked by the compressor,
2064*01826a49SYabin Cui  * and compression will fail if they are not respected.
2065*01826a49SYabin Cui  * Also, data in the ZSTD_inBuffer within the range [src, src + pos)
2066*01826a49SYabin Cui  * MUST not be modified during compression or it will result in data corruption.
2067*01826a49SYabin Cui  *
2068*01826a49SYabin Cui  * When this flag is enabled zstd won't allocate an input window buffer,
2069*01826a49SYabin Cui  * because the user guarantees it can reference the ZSTD_inBuffer until
2070*01826a49SYabin Cui  * the frame is complete. But, it will still allocate an output buffer
2071*01826a49SYabin Cui  * large enough to fit a block (see ZSTD_c_stableOutBuffer). This will also
2072*01826a49SYabin Cui  * avoid the memcpy() from the input buffer to the input window buffer.
2073*01826a49SYabin Cui  *
2074*01826a49SYabin Cui  * NOTE: So long as the ZSTD_inBuffer always points to valid memory, using
2075*01826a49SYabin Cui  * this flag is ALWAYS memory safe, and will never access out-of-bounds
2076*01826a49SYabin Cui  * memory. However, compression WILL fail if conditions are not respected.
2077*01826a49SYabin Cui  *
2078*01826a49SYabin Cui  * WARNING: The data in the ZSTD_inBuffer in the range [src, src + pos) MUST
2079*01826a49SYabin Cui  * not be modified during compression or it will result in data corruption.
2080*01826a49SYabin Cui  * This is because zstd needs to reference data in the ZSTD_inBuffer to find
2081*01826a49SYabin Cui  * matches. Normally zstd maintains its own window buffer for this purpose,
2082*01826a49SYabin Cui  * but passing this flag tells zstd to rely on user provided buffer instead.
2083*01826a49SYabin Cui  */
2084*01826a49SYabin Cui #define ZSTD_c_stableInBuffer ZSTD_c_experimentalParam9
2085*01826a49SYabin Cui 
2086*01826a49SYabin Cui /* ZSTD_c_stableOutBuffer
2087*01826a49SYabin Cui  * Experimental parameter.
2088*01826a49SYabin Cui  * Default is 0 == disabled. Set to 1 to enable.
2089*01826a49SYabin Cui  *
2090*01826a49SYabin Cui  * Tells he compressor that the ZSTD_outBuffer will not be resized between
2091*01826a49SYabin Cui  * calls. Specifically: (out.size - out.pos) will never grow. This gives the
2092*01826a49SYabin Cui  * compressor the freedom to say: If the compressed data doesn't fit in the
2093*01826a49SYabin Cui  * output buffer then return ZSTD_error_dstSizeTooSmall. This allows us to
2094*01826a49SYabin Cui  * always decompress directly into the output buffer, instead of decompressing
2095*01826a49SYabin Cui  * into an internal buffer and copying to the output buffer.
2096*01826a49SYabin Cui  *
2097*01826a49SYabin Cui  * When this flag is enabled zstd won't allocate an output buffer, because
2098*01826a49SYabin Cui  * it can write directly to the ZSTD_outBuffer. It will still allocate the
2099*01826a49SYabin Cui  * input window buffer (see ZSTD_c_stableInBuffer).
2100*01826a49SYabin Cui  *
2101*01826a49SYabin Cui  * Zstd will check that (out.size - out.pos) never grows and return an error
2102*01826a49SYabin Cui  * if it does. While not strictly necessary, this should prevent surprises.
2103*01826a49SYabin Cui  */
2104*01826a49SYabin Cui #define ZSTD_c_stableOutBuffer ZSTD_c_experimentalParam10
2105*01826a49SYabin Cui 
2106*01826a49SYabin Cui /* ZSTD_c_blockDelimiters
2107*01826a49SYabin Cui  * Default is 0 == ZSTD_sf_noBlockDelimiters.
2108*01826a49SYabin Cui  *
2109*01826a49SYabin Cui  * For use with sequence compression API: ZSTD_compressSequences().
2110*01826a49SYabin Cui  *
2111*01826a49SYabin Cui  * Designates whether or not the given array of ZSTD_Sequence contains block delimiters
2112*01826a49SYabin Cui  * and last literals, which are defined as sequences with offset == 0 and matchLength == 0.
2113*01826a49SYabin Cui  * See the definition of ZSTD_Sequence for more specifics.
2114*01826a49SYabin Cui  */
2115*01826a49SYabin Cui #define ZSTD_c_blockDelimiters ZSTD_c_experimentalParam11
2116*01826a49SYabin Cui 
2117*01826a49SYabin Cui /* ZSTD_c_validateSequences
2118*01826a49SYabin Cui  * Default is 0 == disabled. Set to 1 to enable sequence validation.
2119*01826a49SYabin Cui  *
2120*01826a49SYabin Cui  * For use with sequence compression API: ZSTD_compressSequences().
2121*01826a49SYabin Cui  * Designates whether or not we validate sequences provided to ZSTD_compressSequences()
2122*01826a49SYabin Cui  * during function execution.
2123*01826a49SYabin Cui  *
2124*01826a49SYabin Cui  * Without validation, providing a sequence that does not conform to the zstd spec will cause
2125*01826a49SYabin Cui  * undefined behavior, and may produce a corrupted block.
2126*01826a49SYabin Cui  *
2127*01826a49SYabin Cui  * With validation enabled, if sequence is invalid (see doc/zstd_compression_format.md for
2128*01826a49SYabin Cui  * specifics regarding offset/matchlength requirements) then the function will bail out and
2129*01826a49SYabin Cui  * return an error.
2130*01826a49SYabin Cui  *
2131*01826a49SYabin Cui  */
2132*01826a49SYabin Cui #define ZSTD_c_validateSequences ZSTD_c_experimentalParam12
2133*01826a49SYabin Cui 
2134*01826a49SYabin Cui /* ZSTD_c_useBlockSplitter
2135*01826a49SYabin Cui  * Controlled with ZSTD_paramSwitch_e enum.
2136*01826a49SYabin Cui  * Default is ZSTD_ps_auto.
2137*01826a49SYabin Cui  * Set to ZSTD_ps_disable to never use block splitter.
2138*01826a49SYabin Cui  * Set to ZSTD_ps_enable to always use block splitter.
2139*01826a49SYabin Cui  *
2140*01826a49SYabin Cui  * By default, in ZSTD_ps_auto, the library will decide at runtime whether to use
2141*01826a49SYabin Cui  * block splitting based on the compression parameters.
2142*01826a49SYabin Cui  */
2143*01826a49SYabin Cui #define ZSTD_c_useBlockSplitter ZSTD_c_experimentalParam13
2144*01826a49SYabin Cui 
2145*01826a49SYabin Cui /* ZSTD_c_useRowMatchFinder
2146*01826a49SYabin Cui  * Controlled with ZSTD_paramSwitch_e enum.
2147*01826a49SYabin Cui  * Default is ZSTD_ps_auto.
2148*01826a49SYabin Cui  * Set to ZSTD_ps_disable to never use row-based matchfinder.
2149*01826a49SYabin Cui  * Set to ZSTD_ps_enable to force usage of row-based matchfinder.
2150*01826a49SYabin Cui  *
2151*01826a49SYabin Cui  * By default, in ZSTD_ps_auto, the library will decide at runtime whether to use
2152*01826a49SYabin Cui  * the row-based matchfinder based on support for SIMD instructions and the window log.
2153*01826a49SYabin Cui  * Note that this only pertains to compression strategies: greedy, lazy, and lazy2
2154*01826a49SYabin Cui  */
2155*01826a49SYabin Cui #define ZSTD_c_useRowMatchFinder ZSTD_c_experimentalParam14
2156*01826a49SYabin Cui 
2157*01826a49SYabin Cui /* ZSTD_c_deterministicRefPrefix
2158*01826a49SYabin Cui  * Default is 0 == disabled. Set to 1 to enable.
2159*01826a49SYabin Cui  *
2160*01826a49SYabin Cui  * Zstd produces different results for prefix compression when the prefix is
2161*01826a49SYabin Cui  * directly adjacent to the data about to be compressed vs. when it isn't.
2162*01826a49SYabin Cui  * This is because zstd detects that the two buffers are contiguous and it can
2163*01826a49SYabin Cui  * use a more efficient match finding algorithm. However, this produces different
2164*01826a49SYabin Cui  * results than when the two buffers are non-contiguous. This flag forces zstd
2165*01826a49SYabin Cui  * to always load the prefix in non-contiguous mode, even if it happens to be
2166*01826a49SYabin Cui  * adjacent to the data, to guarantee determinism.
2167*01826a49SYabin Cui  *
2168*01826a49SYabin Cui  * If you really care about determinism when using a dictionary or prefix,
2169*01826a49SYabin Cui  * like when doing delta compression, you should select this option. It comes
2170*01826a49SYabin Cui  * at a speed penalty of about ~2.5% if the dictionary and data happened to be
2171*01826a49SYabin Cui  * contiguous, and is free if they weren't contiguous. We don't expect that
2172*01826a49SYabin Cui  * intentionally making the dictionary and data contiguous will be worth the
2173*01826a49SYabin Cui  * cost to memcpy() the data.
2174*01826a49SYabin Cui  */
2175*01826a49SYabin Cui #define ZSTD_c_deterministicRefPrefix ZSTD_c_experimentalParam15
2176*01826a49SYabin Cui 
2177*01826a49SYabin Cui /* ZSTD_c_prefetchCDictTables
2178*01826a49SYabin Cui  * Controlled with ZSTD_paramSwitch_e enum. Default is ZSTD_ps_auto.
2179*01826a49SYabin Cui  *
2180*01826a49SYabin Cui  * In some situations, zstd uses CDict tables in-place rather than copying them
2181*01826a49SYabin Cui  * into the working context. (See docs on ZSTD_dictAttachPref_e above for details).
2182*01826a49SYabin Cui  * In such situations, compression speed is seriously impacted when CDict tables are
2183*01826a49SYabin Cui  * "cold" (outside CPU cache). This parameter instructs zstd to prefetch CDict tables
2184*01826a49SYabin Cui  * when they are used in-place.
2185*01826a49SYabin Cui  *
2186*01826a49SYabin Cui  * For sufficiently small inputs, the cost of the prefetch will outweigh the benefit.
2187*01826a49SYabin Cui  * For sufficiently large inputs, zstd will by default memcpy() CDict tables
2188*01826a49SYabin Cui  * into the working context, so there is no need to prefetch. This parameter is
2189*01826a49SYabin Cui  * targeted at a middle range of input sizes, where a prefetch is cheap enough to be
2190*01826a49SYabin Cui  * useful but memcpy() is too expensive. The exact range of input sizes where this
2191*01826a49SYabin Cui  * makes sense is best determined by careful experimentation.
2192*01826a49SYabin Cui  *
2193*01826a49SYabin Cui  * Note: for this parameter, ZSTD_ps_auto is currently equivalent to ZSTD_ps_disable,
2194*01826a49SYabin Cui  * but in the future zstd may conditionally enable this feature via an auto-detection
2195*01826a49SYabin Cui  * heuristic for cold CDicts.
2196*01826a49SYabin Cui  * Use ZSTD_ps_disable to opt out of prefetching under any circumstances.
2197*01826a49SYabin Cui  */
2198*01826a49SYabin Cui #define ZSTD_c_prefetchCDictTables ZSTD_c_experimentalParam16
2199*01826a49SYabin Cui 
2200*01826a49SYabin Cui /* ZSTD_c_enableSeqProducerFallback
2201*01826a49SYabin Cui  * Allowed values are 0 (disable) and 1 (enable). The default setting is 0.
2202*01826a49SYabin Cui  *
2203*01826a49SYabin Cui  * Controls whether zstd will fall back to an internal sequence producer if an
2204*01826a49SYabin Cui  * external sequence producer is registered and returns an error code. This fallback
2205*01826a49SYabin Cui  * is block-by-block: the internal sequence producer will only be called for blocks
2206*01826a49SYabin Cui  * where the external sequence producer returns an error code. Fallback parsing will
2207*01826a49SYabin Cui  * follow any other cParam settings, such as compression level, the same as in a
2208*01826a49SYabin Cui  * normal (fully-internal) compression operation.
2209*01826a49SYabin Cui  *
2210*01826a49SYabin Cui  * The user is strongly encouraged to read the full Block-Level Sequence Producer API
2211*01826a49SYabin Cui  * documentation (below) before setting this parameter. */
2212*01826a49SYabin Cui #define ZSTD_c_enableSeqProducerFallback ZSTD_c_experimentalParam17
2213*01826a49SYabin Cui 
2214*01826a49SYabin Cui /* ZSTD_c_maxBlockSize
2215*01826a49SYabin Cui  * Allowed values are between 1KB and ZSTD_BLOCKSIZE_MAX (128KB).
2216*01826a49SYabin Cui  * The default is ZSTD_BLOCKSIZE_MAX, and setting to 0 will set to the default.
2217*01826a49SYabin Cui  *
2218*01826a49SYabin Cui  * This parameter can be used to set an upper bound on the blocksize
2219*01826a49SYabin Cui  * that overrides the default ZSTD_BLOCKSIZE_MAX. It cannot be used to set upper
2220*01826a49SYabin Cui  * bounds greater than ZSTD_BLOCKSIZE_MAX or bounds lower than 1KB (will make
2221*01826a49SYabin Cui  * compressBound() inaccurate). Only currently meant to be used for testing.
2222*01826a49SYabin Cui  *
2223*01826a49SYabin Cui  */
2224*01826a49SYabin Cui #define ZSTD_c_maxBlockSize ZSTD_c_experimentalParam18
2225*01826a49SYabin Cui 
2226*01826a49SYabin Cui /* ZSTD_c_searchForExternalRepcodes
2227*01826a49SYabin Cui  * This parameter affects how zstd parses external sequences, such as sequences
2228*01826a49SYabin Cui  * provided through the compressSequences() API or from an external block-level
2229*01826a49SYabin Cui  * sequence producer.
2230*01826a49SYabin Cui  *
2231*01826a49SYabin Cui  * If set to ZSTD_ps_enable, the library will check for repeated offsets in
2232*01826a49SYabin Cui  * external sequences, even if those repcodes are not explicitly indicated in
2233*01826a49SYabin Cui  * the "rep" field. Note that this is the only way to exploit repcode matches
2234*01826a49SYabin Cui  * while using compressSequences() or an external sequence producer, since zstd
2235*01826a49SYabin Cui  * currently ignores the "rep" field of external sequences.
2236*01826a49SYabin Cui  *
2237*01826a49SYabin Cui  * If set to ZSTD_ps_disable, the library will not exploit repeated offsets in
2238*01826a49SYabin Cui  * external sequences, regardless of whether the "rep" field has been set. This
2239*01826a49SYabin Cui  * reduces sequence compression overhead by about 25% while sacrificing some
2240*01826a49SYabin Cui  * compression ratio.
2241*01826a49SYabin Cui  *
2242*01826a49SYabin Cui  * The default value is ZSTD_ps_auto, for which the library will enable/disable
2243*01826a49SYabin Cui  * based on compression level.
2244*01826a49SYabin Cui  *
2245*01826a49SYabin Cui  * Note: for now, this param only has an effect if ZSTD_c_blockDelimiters is
2246*01826a49SYabin Cui  * set to ZSTD_sf_explicitBlockDelimiters. That may change in the future.
2247*01826a49SYabin Cui  */
2248*01826a49SYabin Cui #define ZSTD_c_searchForExternalRepcodes ZSTD_c_experimentalParam19
2249*01826a49SYabin Cui 
2250*01826a49SYabin Cui /*! ZSTD_CCtx_getParameter() :
2251*01826a49SYabin Cui  *  Get the requested compression parameter value, selected by enum ZSTD_cParameter,
2252*01826a49SYabin Cui  *  and store it into int* value.
2253*01826a49SYabin Cui  * @return : 0, or an error code (which can be tested with ZSTD_isError()).
2254*01826a49SYabin Cui  */
2255*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_CCtx_getParameter(const ZSTD_CCtx* cctx, ZSTD_cParameter param, int* value);
2256*01826a49SYabin Cui 
2257*01826a49SYabin Cui 
2258*01826a49SYabin Cui /*! ZSTD_CCtx_params :
2259*01826a49SYabin Cui  *  Quick howto :
2260*01826a49SYabin Cui  *  - ZSTD_createCCtxParams() : Create a ZSTD_CCtx_params structure
2261*01826a49SYabin Cui  *  - ZSTD_CCtxParams_setParameter() : Push parameters one by one into
2262*01826a49SYabin Cui  *                                     an existing ZSTD_CCtx_params structure.
2263*01826a49SYabin Cui  *                                     This is similar to
2264*01826a49SYabin Cui  *                                     ZSTD_CCtx_setParameter().
2265*01826a49SYabin Cui  *  - ZSTD_CCtx_setParametersUsingCCtxParams() : Apply parameters to
2266*01826a49SYabin Cui  *                                    an existing CCtx.
2267*01826a49SYabin Cui  *                                    These parameters will be applied to
2268*01826a49SYabin Cui  *                                    all subsequent frames.
2269*01826a49SYabin Cui  *  - ZSTD_compressStream2() : Do compression using the CCtx.
2270*01826a49SYabin Cui  *  - ZSTD_freeCCtxParams() : Free the memory, accept NULL pointer.
2271*01826a49SYabin Cui  *
2272*01826a49SYabin Cui  *  This can be used with ZSTD_estimateCCtxSize_advanced_usingCCtxParams()
2273*01826a49SYabin Cui  *  for static allocation of CCtx for single-threaded compression.
2274*01826a49SYabin Cui  */
2275*01826a49SYabin Cui ZSTDLIB_STATIC_API ZSTD_CCtx_params* ZSTD_createCCtxParams(void);
2276*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_freeCCtxParams(ZSTD_CCtx_params* params);  /* accept NULL pointer */
2277*01826a49SYabin Cui 
2278*01826a49SYabin Cui /*! ZSTD_CCtxParams_reset() :
2279*01826a49SYabin Cui  *  Reset params to default values.
2280*01826a49SYabin Cui  */
2281*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_CCtxParams_reset(ZSTD_CCtx_params* params);
2282*01826a49SYabin Cui 
2283*01826a49SYabin Cui /*! ZSTD_CCtxParams_init() :
2284*01826a49SYabin Cui  *  Initializes the compression parameters of cctxParams according to
2285*01826a49SYabin Cui  *  compression level. All other parameters are reset to their default values.
2286*01826a49SYabin Cui  */
2287*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_CCtxParams_init(ZSTD_CCtx_params* cctxParams, int compressionLevel);
2288*01826a49SYabin Cui 
2289*01826a49SYabin Cui /*! ZSTD_CCtxParams_init_advanced() :
2290*01826a49SYabin Cui  *  Initializes the compression and frame parameters of cctxParams according to
2291*01826a49SYabin Cui  *  params. All other parameters are reset to their default values.
2292*01826a49SYabin Cui  */
2293*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_CCtxParams_init_advanced(ZSTD_CCtx_params* cctxParams, ZSTD_parameters params);
2294*01826a49SYabin Cui 
2295*01826a49SYabin Cui /*! ZSTD_CCtxParams_setParameter() : Requires v1.4.0+
2296*01826a49SYabin Cui  *  Similar to ZSTD_CCtx_setParameter.
2297*01826a49SYabin Cui  *  Set one compression parameter, selected by enum ZSTD_cParameter.
2298*01826a49SYabin Cui  *  Parameters must be applied to a ZSTD_CCtx using
2299*01826a49SYabin Cui  *  ZSTD_CCtx_setParametersUsingCCtxParams().
2300*01826a49SYabin Cui  * @result : a code representing success or failure (which can be tested with
2301*01826a49SYabin Cui  *           ZSTD_isError()).
2302*01826a49SYabin Cui  */
2303*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_CCtxParams_setParameter(ZSTD_CCtx_params* params, ZSTD_cParameter param, int value);
2304*01826a49SYabin Cui 
2305*01826a49SYabin Cui /*! ZSTD_CCtxParams_getParameter() :
2306*01826a49SYabin Cui  * Similar to ZSTD_CCtx_getParameter.
2307*01826a49SYabin Cui  * Get the requested value of one compression parameter, selected by enum ZSTD_cParameter.
2308*01826a49SYabin Cui  * @result : 0, or an error code (which can be tested with ZSTD_isError()).
2309*01826a49SYabin Cui  */
2310*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_CCtxParams_getParameter(const ZSTD_CCtx_params* params, ZSTD_cParameter param, int* value);
2311*01826a49SYabin Cui 
2312*01826a49SYabin Cui /*! ZSTD_CCtx_setParametersUsingCCtxParams() :
2313*01826a49SYabin Cui  *  Apply a set of ZSTD_CCtx_params to the compression context.
2314*01826a49SYabin Cui  *  This can be done even after compression is started,
2315*01826a49SYabin Cui  *    if nbWorkers==0, this will have no impact until a new compression is started.
2316*01826a49SYabin Cui  *    if nbWorkers>=1, new parameters will be picked up at next job,
2317*01826a49SYabin Cui  *       with a few restrictions (windowLog, pledgedSrcSize, nbWorkers, jobSize, and overlapLog are not updated).
2318*01826a49SYabin Cui  */
2319*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_CCtx_setParametersUsingCCtxParams(
2320*01826a49SYabin Cui         ZSTD_CCtx* cctx, const ZSTD_CCtx_params* params);
2321*01826a49SYabin Cui 
2322*01826a49SYabin Cui /*! ZSTD_compressStream2_simpleArgs() :
2323*01826a49SYabin Cui  *  Same as ZSTD_compressStream2(),
2324*01826a49SYabin Cui  *  but using only integral types as arguments.
2325*01826a49SYabin Cui  *  This variant might be helpful for binders from dynamic languages
2326*01826a49SYabin Cui  *  which have troubles handling structures containing memory pointers.
2327*01826a49SYabin Cui  */
2328*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_compressStream2_simpleArgs (
2329*01826a49SYabin Cui                             ZSTD_CCtx* cctx,
2330*01826a49SYabin Cui                             void* dst, size_t dstCapacity, size_t* dstPos,
2331*01826a49SYabin Cui                       const void* src, size_t srcSize, size_t* srcPos,
2332*01826a49SYabin Cui                             ZSTD_EndDirective endOp);
2333*01826a49SYabin Cui 
2334*01826a49SYabin Cui 
2335*01826a49SYabin Cui /***************************************
2336*01826a49SYabin Cui *  Advanced decompression functions
2337*01826a49SYabin Cui ***************************************/
2338*01826a49SYabin Cui 
2339*01826a49SYabin Cui /*! ZSTD_isFrame() :
2340*01826a49SYabin Cui  *  Tells if the content of `buffer` starts with a valid Frame Identifier.
2341*01826a49SYabin Cui  *  Note : Frame Identifier is 4 bytes. If `size < 4`, @return will always be 0.
2342*01826a49SYabin Cui  *  Note 2 : Legacy Frame Identifiers are considered valid only if Legacy Support is enabled.
2343*01826a49SYabin Cui  *  Note 3 : Skippable Frame Identifiers are considered valid. */
2344*01826a49SYabin Cui ZSTDLIB_STATIC_API unsigned ZSTD_isFrame(const void* buffer, size_t size);
2345*01826a49SYabin Cui 
2346*01826a49SYabin Cui /*! ZSTD_createDDict_byReference() :
2347*01826a49SYabin Cui  *  Create a digested dictionary, ready to start decompression operation without startup delay.
2348*01826a49SYabin Cui  *  Dictionary content is referenced, and therefore stays in dictBuffer.
2349*01826a49SYabin Cui  *  It is important that dictBuffer outlives DDict,
2350*01826a49SYabin Cui  *  it must remain read accessible throughout the lifetime of DDict */
2351*01826a49SYabin Cui ZSTDLIB_STATIC_API ZSTD_DDict* ZSTD_createDDict_byReference(const void* dictBuffer, size_t dictSize);
2352*01826a49SYabin Cui 
2353*01826a49SYabin Cui /*! ZSTD_DCtx_loadDictionary_byReference() :
2354*01826a49SYabin Cui  *  Same as ZSTD_DCtx_loadDictionary(),
2355*01826a49SYabin Cui  *  but references `dict` content instead of copying it into `dctx`.
2356*01826a49SYabin Cui  *  This saves memory if `dict` remains around.,
2357*01826a49SYabin Cui  *  However, it's imperative that `dict` remains accessible (and unmodified) while being used, so it must outlive decompression. */
2358*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_DCtx_loadDictionary_byReference(ZSTD_DCtx* dctx, const void* dict, size_t dictSize);
2359*01826a49SYabin Cui 
2360*01826a49SYabin Cui /*! ZSTD_DCtx_loadDictionary_advanced() :
2361*01826a49SYabin Cui  *  Same as ZSTD_DCtx_loadDictionary(),
2362*01826a49SYabin Cui  *  but gives direct control over
2363*01826a49SYabin Cui  *  how to load the dictionary (by copy ? by reference ?)
2364*01826a49SYabin Cui  *  and how to interpret it (automatic ? force raw mode ? full mode only ?). */
2365*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_DCtx_loadDictionary_advanced(ZSTD_DCtx* dctx, const void* dict, size_t dictSize, ZSTD_dictLoadMethod_e dictLoadMethod, ZSTD_dictContentType_e dictContentType);
2366*01826a49SYabin Cui 
2367*01826a49SYabin Cui /*! ZSTD_DCtx_refPrefix_advanced() :
2368*01826a49SYabin Cui  *  Same as ZSTD_DCtx_refPrefix(), but gives finer control over
2369*01826a49SYabin Cui  *  how to interpret prefix content (automatic ? force raw mode (default) ? full mode only ?) */
2370*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_DCtx_refPrefix_advanced(ZSTD_DCtx* dctx, const void* prefix, size_t prefixSize, ZSTD_dictContentType_e dictContentType);
2371*01826a49SYabin Cui 
2372*01826a49SYabin Cui /*! ZSTD_DCtx_setMaxWindowSize() :
2373*01826a49SYabin Cui  *  Refuses allocating internal buffers for frames requiring a window size larger than provided limit.
2374*01826a49SYabin Cui  *  This protects a decoder context from reserving too much memory for itself (potential attack scenario).
2375*01826a49SYabin Cui  *  This parameter is only useful in streaming mode, since no internal buffer is allocated in single-pass mode.
2376*01826a49SYabin Cui  *  By default, a decompression context accepts all window sizes <= (1 << ZSTD_WINDOWLOG_LIMIT_DEFAULT)
2377*01826a49SYabin Cui  * @return : 0, or an error code (which can be tested using ZSTD_isError()).
2378*01826a49SYabin Cui  */
2379*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_DCtx_setMaxWindowSize(ZSTD_DCtx* dctx, size_t maxWindowSize);
2380*01826a49SYabin Cui 
2381*01826a49SYabin Cui /*! ZSTD_DCtx_getParameter() :
2382*01826a49SYabin Cui  *  Get the requested decompression parameter value, selected by enum ZSTD_dParameter,
2383*01826a49SYabin Cui  *  and store it into int* value.
2384*01826a49SYabin Cui  * @return : 0, or an error code (which can be tested with ZSTD_isError()).
2385*01826a49SYabin Cui  */
2386*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_DCtx_getParameter(ZSTD_DCtx* dctx, ZSTD_dParameter param, int* value);
2387*01826a49SYabin Cui 
2388*01826a49SYabin Cui /* ZSTD_d_format
2389*01826a49SYabin Cui  * experimental parameter,
2390*01826a49SYabin Cui  * allowing selection between ZSTD_format_e input compression formats
2391*01826a49SYabin Cui  */
2392*01826a49SYabin Cui #define ZSTD_d_format ZSTD_d_experimentalParam1
2393*01826a49SYabin Cui /* ZSTD_d_stableOutBuffer
2394*01826a49SYabin Cui  * Experimental parameter.
2395*01826a49SYabin Cui  * Default is 0 == disabled. Set to 1 to enable.
2396*01826a49SYabin Cui  *
2397*01826a49SYabin Cui  * Tells the decompressor that the ZSTD_outBuffer will ALWAYS be the same
2398*01826a49SYabin Cui  * between calls, except for the modifications that zstd makes to pos (the
2399*01826a49SYabin Cui  * caller must not modify pos). This is checked by the decompressor, and
2400*01826a49SYabin Cui  * decompression will fail if it ever changes. Therefore the ZSTD_outBuffer
2401*01826a49SYabin Cui  * MUST be large enough to fit the entire decompressed frame. This will be
2402*01826a49SYabin Cui  * checked when the frame content size is known. The data in the ZSTD_outBuffer
2403*01826a49SYabin Cui  * in the range [dst, dst + pos) MUST not be modified during decompression
2404*01826a49SYabin Cui  * or you will get data corruption.
2405*01826a49SYabin Cui  *
2406*01826a49SYabin Cui  * When this flag is enabled zstd won't allocate an output buffer, because
2407*01826a49SYabin Cui  * it can write directly to the ZSTD_outBuffer, but it will still allocate
2408*01826a49SYabin Cui  * an input buffer large enough to fit any compressed block. This will also
2409*01826a49SYabin Cui  * avoid the memcpy() from the internal output buffer to the ZSTD_outBuffer.
2410*01826a49SYabin Cui  * If you need to avoid the input buffer allocation use the buffer-less
2411*01826a49SYabin Cui  * streaming API.
2412*01826a49SYabin Cui  *
2413*01826a49SYabin Cui  * NOTE: So long as the ZSTD_outBuffer always points to valid memory, using
2414*01826a49SYabin Cui  * this flag is ALWAYS memory safe, and will never access out-of-bounds
2415*01826a49SYabin Cui  * memory. However, decompression WILL fail if you violate the preconditions.
2416*01826a49SYabin Cui  *
2417*01826a49SYabin Cui  * WARNING: The data in the ZSTD_outBuffer in the range [dst, dst + pos) MUST
2418*01826a49SYabin Cui  * not be modified during decompression or you will get data corruption. This
2419*01826a49SYabin Cui  * is because zstd needs to reference data in the ZSTD_outBuffer to regenerate
2420*01826a49SYabin Cui  * matches. Normally zstd maintains its own buffer for this purpose, but passing
2421*01826a49SYabin Cui  * this flag tells zstd to use the user provided buffer.
2422*01826a49SYabin Cui  */
2423*01826a49SYabin Cui #define ZSTD_d_stableOutBuffer ZSTD_d_experimentalParam2
2424*01826a49SYabin Cui 
2425*01826a49SYabin Cui /* ZSTD_d_forceIgnoreChecksum
2426*01826a49SYabin Cui  * Experimental parameter.
2427*01826a49SYabin Cui  * Default is 0 == disabled. Set to 1 to enable
2428*01826a49SYabin Cui  *
2429*01826a49SYabin Cui  * Tells the decompressor to skip checksum validation during decompression, regardless
2430*01826a49SYabin Cui  * of whether checksumming was specified during compression. This offers some
2431*01826a49SYabin Cui  * slight performance benefits, and may be useful for debugging.
2432*01826a49SYabin Cui  * Param has values of type ZSTD_forceIgnoreChecksum_e
2433*01826a49SYabin Cui  */
2434*01826a49SYabin Cui #define ZSTD_d_forceIgnoreChecksum ZSTD_d_experimentalParam3
2435*01826a49SYabin Cui 
2436*01826a49SYabin Cui /* ZSTD_d_refMultipleDDicts
2437*01826a49SYabin Cui  * Experimental parameter.
2438*01826a49SYabin Cui  * Default is 0 == disabled. Set to 1 to enable
2439*01826a49SYabin Cui  *
2440*01826a49SYabin Cui  * If enabled and dctx is allocated on the heap, then additional memory will be allocated
2441*01826a49SYabin Cui  * to store references to multiple ZSTD_DDict. That is, multiple calls of ZSTD_refDDict()
2442*01826a49SYabin Cui  * using a given ZSTD_DCtx, rather than overwriting the previous DDict reference, will instead
2443*01826a49SYabin Cui  * store all references. At decompression time, the appropriate dictID is selected
2444*01826a49SYabin Cui  * from the set of DDicts based on the dictID in the frame.
2445*01826a49SYabin Cui  *
2446*01826a49SYabin Cui  * Usage is simply calling ZSTD_refDDict() on multiple dict buffers.
2447*01826a49SYabin Cui  *
2448*01826a49SYabin Cui  * Param has values of byte ZSTD_refMultipleDDicts_e
2449*01826a49SYabin Cui  *
2450*01826a49SYabin Cui  * WARNING: Enabling this parameter and calling ZSTD_DCtx_refDDict(), will trigger memory
2451*01826a49SYabin Cui  * allocation for the hash table. ZSTD_freeDCtx() also frees this memory.
2452*01826a49SYabin Cui  * Memory is allocated as per ZSTD_DCtx::customMem.
2453*01826a49SYabin Cui  *
2454*01826a49SYabin Cui  * Although this function allocates memory for the table, the user is still responsible for
2455*01826a49SYabin Cui  * memory management of the underlying ZSTD_DDict* themselves.
2456*01826a49SYabin Cui  */
2457*01826a49SYabin Cui #define ZSTD_d_refMultipleDDicts ZSTD_d_experimentalParam4
2458*01826a49SYabin Cui 
2459*01826a49SYabin Cui /* ZSTD_d_disableHuffmanAssembly
2460*01826a49SYabin Cui  * Set to 1 to disable the Huffman assembly implementation.
2461*01826a49SYabin Cui  * The default value is 0, which allows zstd to use the Huffman assembly
2462*01826a49SYabin Cui  * implementation if available.
2463*01826a49SYabin Cui  *
2464*01826a49SYabin Cui  * This parameter can be used to disable Huffman assembly at runtime.
2465*01826a49SYabin Cui  * If you want to disable it at compile time you can define the macro
2466*01826a49SYabin Cui  * ZSTD_DISABLE_ASM.
2467*01826a49SYabin Cui  */
2468*01826a49SYabin Cui #define ZSTD_d_disableHuffmanAssembly ZSTD_d_experimentalParam5
2469*01826a49SYabin Cui 
2470*01826a49SYabin Cui /* ZSTD_d_maxBlockSize
2471*01826a49SYabin Cui  * Allowed values are between 1KB and ZSTD_BLOCKSIZE_MAX (128KB).
2472*01826a49SYabin Cui  * The default is ZSTD_BLOCKSIZE_MAX, and setting to 0 will set to the default.
2473*01826a49SYabin Cui  *
2474*01826a49SYabin Cui  * Forces the decompressor to reject blocks whose content size is
2475*01826a49SYabin Cui  * larger than the configured maxBlockSize. When maxBlockSize is
2476*01826a49SYabin Cui  * larger than the windowSize, the windowSize is used instead.
2477*01826a49SYabin Cui  * This saves memory on the decoder when you know all blocks are small.
2478*01826a49SYabin Cui  *
2479*01826a49SYabin Cui  * This option is typically used in conjunction with ZSTD_c_maxBlockSize.
2480*01826a49SYabin Cui  *
2481*01826a49SYabin Cui  * WARNING: This causes the decoder to reject otherwise valid frames
2482*01826a49SYabin Cui  * that have block sizes larger than the configured maxBlockSize.
2483*01826a49SYabin Cui  */
2484*01826a49SYabin Cui #define ZSTD_d_maxBlockSize ZSTD_d_experimentalParam6
2485*01826a49SYabin Cui 
2486*01826a49SYabin Cui 
2487*01826a49SYabin Cui /*! ZSTD_DCtx_setFormat() :
2488*01826a49SYabin Cui  *  This function is REDUNDANT. Prefer ZSTD_DCtx_setParameter().
2489*01826a49SYabin Cui  *  Instruct the decoder context about what kind of data to decode next.
2490*01826a49SYabin Cui  *  This instruction is mandatory to decode data without a fully-formed header,
2491*01826a49SYabin Cui  *  such ZSTD_f_zstd1_magicless for example.
2492*01826a49SYabin Cui  * @return : 0, or an error code (which can be tested using ZSTD_isError()). */
2493*01826a49SYabin Cui ZSTD_DEPRECATED("use ZSTD_DCtx_setParameter() instead")
2494*01826a49SYabin Cui ZSTDLIB_STATIC_API
2495*01826a49SYabin Cui size_t ZSTD_DCtx_setFormat(ZSTD_DCtx* dctx, ZSTD_format_e format);
2496*01826a49SYabin Cui 
2497*01826a49SYabin Cui /*! ZSTD_decompressStream_simpleArgs() :
2498*01826a49SYabin Cui  *  Same as ZSTD_decompressStream(),
2499*01826a49SYabin Cui  *  but using only integral types as arguments.
2500*01826a49SYabin Cui  *  This can be helpful for binders from dynamic languages
2501*01826a49SYabin Cui  *  which have troubles handling structures containing memory pointers.
2502*01826a49SYabin Cui  */
2503*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_decompressStream_simpleArgs (
2504*01826a49SYabin Cui                             ZSTD_DCtx* dctx,
2505*01826a49SYabin Cui                             void* dst, size_t dstCapacity, size_t* dstPos,
2506*01826a49SYabin Cui                       const void* src, size_t srcSize, size_t* srcPos);
2507*01826a49SYabin Cui 
2508*01826a49SYabin Cui 
2509*01826a49SYabin Cui /********************************************************************
2510*01826a49SYabin Cui *  Advanced streaming functions
2511*01826a49SYabin Cui *  Warning : most of these functions are now redundant with the Advanced API.
2512*01826a49SYabin Cui *  Once Advanced API reaches "stable" status,
2513*01826a49SYabin Cui *  redundant functions will be deprecated, and then at some point removed.
2514*01826a49SYabin Cui ********************************************************************/
2515*01826a49SYabin Cui 
2516*01826a49SYabin Cui /*=====   Advanced Streaming compression functions  =====*/
2517*01826a49SYabin Cui 
2518*01826a49SYabin Cui /*! ZSTD_initCStream_srcSize() :
2519*01826a49SYabin Cui  * This function is DEPRECATED, and equivalent to:
2520*01826a49SYabin Cui  *     ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only);
2521*01826a49SYabin Cui  *     ZSTD_CCtx_refCDict(zcs, NULL); // clear the dictionary (if any)
2522*01826a49SYabin Cui  *     ZSTD_CCtx_setParameter(zcs, ZSTD_c_compressionLevel, compressionLevel);
2523*01826a49SYabin Cui  *     ZSTD_CCtx_setPledgedSrcSize(zcs, pledgedSrcSize);
2524*01826a49SYabin Cui  *
2525*01826a49SYabin Cui  * pledgedSrcSize must be correct. If it is not known at init time, use
2526*01826a49SYabin Cui  * ZSTD_CONTENTSIZE_UNKNOWN. Note that, for compatibility with older programs,
2527*01826a49SYabin Cui  * "0" also disables frame content size field. It may be enabled in the future.
2528*01826a49SYabin Cui  * This prototype will generate compilation warnings.
2529*01826a49SYabin Cui  */
2530*01826a49SYabin Cui ZSTD_DEPRECATED("use ZSTD_CCtx_reset, see zstd.h for detailed instructions")
2531*01826a49SYabin Cui ZSTDLIB_STATIC_API
2532*01826a49SYabin Cui size_t ZSTD_initCStream_srcSize(ZSTD_CStream* zcs,
2533*01826a49SYabin Cui                          int compressionLevel,
2534*01826a49SYabin Cui                          unsigned long long pledgedSrcSize);
2535*01826a49SYabin Cui 
2536*01826a49SYabin Cui /*! ZSTD_initCStream_usingDict() :
2537*01826a49SYabin Cui  * This function is DEPRECATED, and is equivalent to:
2538*01826a49SYabin Cui  *     ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only);
2539*01826a49SYabin Cui  *     ZSTD_CCtx_setParameter(zcs, ZSTD_c_compressionLevel, compressionLevel);
2540*01826a49SYabin Cui  *     ZSTD_CCtx_loadDictionary(zcs, dict, dictSize);
2541*01826a49SYabin Cui  *
2542*01826a49SYabin Cui  * Creates of an internal CDict (incompatible with static CCtx), except if
2543*01826a49SYabin Cui  * dict == NULL or dictSize < 8, in which case no dict is used.
2544*01826a49SYabin Cui  * Note: dict is loaded with ZSTD_dct_auto (treated as a full zstd dictionary if
2545*01826a49SYabin Cui  * it begins with ZSTD_MAGIC_DICTIONARY, else as raw content) and ZSTD_dlm_byCopy.
2546*01826a49SYabin Cui  * This prototype will generate compilation warnings.
2547*01826a49SYabin Cui  */
2548*01826a49SYabin Cui ZSTD_DEPRECATED("use ZSTD_CCtx_reset, see zstd.h for detailed instructions")
2549*01826a49SYabin Cui ZSTDLIB_STATIC_API
2550*01826a49SYabin Cui size_t ZSTD_initCStream_usingDict(ZSTD_CStream* zcs,
2551*01826a49SYabin Cui                      const void* dict, size_t dictSize,
2552*01826a49SYabin Cui                            int compressionLevel);
2553*01826a49SYabin Cui 
2554*01826a49SYabin Cui /*! ZSTD_initCStream_advanced() :
2555*01826a49SYabin Cui  * This function is DEPRECATED, and is equivalent to:
2556*01826a49SYabin Cui  *     ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only);
2557*01826a49SYabin Cui  *     ZSTD_CCtx_setParams(zcs, params);
2558*01826a49SYabin Cui  *     ZSTD_CCtx_setPledgedSrcSize(zcs, pledgedSrcSize);
2559*01826a49SYabin Cui  *     ZSTD_CCtx_loadDictionary(zcs, dict, dictSize);
2560*01826a49SYabin Cui  *
2561*01826a49SYabin Cui  * dict is loaded with ZSTD_dct_auto and ZSTD_dlm_byCopy.
2562*01826a49SYabin Cui  * pledgedSrcSize must be correct.
2563*01826a49SYabin Cui  * If srcSize is not known at init time, use value ZSTD_CONTENTSIZE_UNKNOWN.
2564*01826a49SYabin Cui  * This prototype will generate compilation warnings.
2565*01826a49SYabin Cui  */
2566*01826a49SYabin Cui ZSTD_DEPRECATED("use ZSTD_CCtx_reset, see zstd.h for detailed instructions")
2567*01826a49SYabin Cui ZSTDLIB_STATIC_API
2568*01826a49SYabin Cui size_t ZSTD_initCStream_advanced(ZSTD_CStream* zcs,
2569*01826a49SYabin Cui                     const void* dict, size_t dictSize,
2570*01826a49SYabin Cui                           ZSTD_parameters params,
2571*01826a49SYabin Cui                           unsigned long long pledgedSrcSize);
2572*01826a49SYabin Cui 
2573*01826a49SYabin Cui /*! ZSTD_initCStream_usingCDict() :
2574*01826a49SYabin Cui  * This function is DEPRECATED, and equivalent to:
2575*01826a49SYabin Cui  *     ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only);
2576*01826a49SYabin Cui  *     ZSTD_CCtx_refCDict(zcs, cdict);
2577*01826a49SYabin Cui  *
2578*01826a49SYabin Cui  * note : cdict will just be referenced, and must outlive compression session
2579*01826a49SYabin Cui  * This prototype will generate compilation warnings.
2580*01826a49SYabin Cui  */
2581*01826a49SYabin Cui ZSTD_DEPRECATED("use ZSTD_CCtx_reset and ZSTD_CCtx_refCDict, see zstd.h for detailed instructions")
2582*01826a49SYabin Cui ZSTDLIB_STATIC_API
2583*01826a49SYabin Cui size_t ZSTD_initCStream_usingCDict(ZSTD_CStream* zcs, const ZSTD_CDict* cdict);
2584*01826a49SYabin Cui 
2585*01826a49SYabin Cui /*! ZSTD_initCStream_usingCDict_advanced() :
2586*01826a49SYabin Cui  *   This function is DEPRECATED, and is equivalent to:
2587*01826a49SYabin Cui  *     ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only);
2588*01826a49SYabin Cui  *     ZSTD_CCtx_setFParams(zcs, fParams);
2589*01826a49SYabin Cui  *     ZSTD_CCtx_setPledgedSrcSize(zcs, pledgedSrcSize);
2590*01826a49SYabin Cui  *     ZSTD_CCtx_refCDict(zcs, cdict);
2591*01826a49SYabin Cui  *
2592*01826a49SYabin Cui  * same as ZSTD_initCStream_usingCDict(), with control over frame parameters.
2593*01826a49SYabin Cui  * pledgedSrcSize must be correct. If srcSize is not known at init time, use
2594*01826a49SYabin Cui  * value ZSTD_CONTENTSIZE_UNKNOWN.
2595*01826a49SYabin Cui  * This prototype will generate compilation warnings.
2596*01826a49SYabin Cui  */
2597*01826a49SYabin Cui ZSTD_DEPRECATED("use ZSTD_CCtx_reset and ZSTD_CCtx_refCDict, see zstd.h for detailed instructions")
2598*01826a49SYabin Cui ZSTDLIB_STATIC_API
2599*01826a49SYabin Cui size_t ZSTD_initCStream_usingCDict_advanced(ZSTD_CStream* zcs,
2600*01826a49SYabin Cui                                const ZSTD_CDict* cdict,
2601*01826a49SYabin Cui                                      ZSTD_frameParameters fParams,
2602*01826a49SYabin Cui                                      unsigned long long pledgedSrcSize);
2603*01826a49SYabin Cui 
2604*01826a49SYabin Cui /*! ZSTD_resetCStream() :
2605*01826a49SYabin Cui  * This function is DEPRECATED, and is equivalent to:
2606*01826a49SYabin Cui  *     ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only);
2607*01826a49SYabin Cui  *     ZSTD_CCtx_setPledgedSrcSize(zcs, pledgedSrcSize);
2608*01826a49SYabin Cui  * Note: ZSTD_resetCStream() interprets pledgedSrcSize == 0 as ZSTD_CONTENTSIZE_UNKNOWN, but
2609*01826a49SYabin Cui  *       ZSTD_CCtx_setPledgedSrcSize() does not do the same, so ZSTD_CONTENTSIZE_UNKNOWN must be
2610*01826a49SYabin Cui  *       explicitly specified.
2611*01826a49SYabin Cui  *
2612*01826a49SYabin Cui  *  start a new frame, using same parameters from previous frame.
2613*01826a49SYabin Cui  *  This is typically useful to skip dictionary loading stage, since it will reuse it in-place.
2614*01826a49SYabin Cui  *  Note that zcs must be init at least once before using ZSTD_resetCStream().
2615*01826a49SYabin Cui  *  If pledgedSrcSize is not known at reset time, use macro ZSTD_CONTENTSIZE_UNKNOWN.
2616*01826a49SYabin Cui  *  If pledgedSrcSize > 0, its value must be correct, as it will be written in header, and controlled at the end.
2617*01826a49SYabin Cui  *  For the time being, pledgedSrcSize==0 is interpreted as "srcSize unknown" for compatibility with older programs,
2618*01826a49SYabin Cui  *  but it will change to mean "empty" in future version, so use macro ZSTD_CONTENTSIZE_UNKNOWN instead.
2619*01826a49SYabin Cui  * @return : 0, or an error code (which can be tested using ZSTD_isError())
2620*01826a49SYabin Cui  *  This prototype will generate compilation warnings.
2621*01826a49SYabin Cui  */
2622*01826a49SYabin Cui ZSTD_DEPRECATED("use ZSTD_CCtx_reset, see zstd.h for detailed instructions")
2623*01826a49SYabin Cui ZSTDLIB_STATIC_API
2624*01826a49SYabin Cui size_t ZSTD_resetCStream(ZSTD_CStream* zcs, unsigned long long pledgedSrcSize);
2625*01826a49SYabin Cui 
2626*01826a49SYabin Cui 
2627*01826a49SYabin Cui typedef struct {
2628*01826a49SYabin Cui     unsigned long long ingested;   /* nb input bytes read and buffered */
2629*01826a49SYabin Cui     unsigned long long consumed;   /* nb input bytes actually compressed */
2630*01826a49SYabin Cui     unsigned long long produced;   /* nb of compressed bytes generated and buffered */
2631*01826a49SYabin Cui     unsigned long long flushed;    /* nb of compressed bytes flushed : not provided; can be tracked from caller side */
2632*01826a49SYabin Cui     unsigned currentJobID;         /* MT only : latest started job nb */
2633*01826a49SYabin Cui     unsigned nbActiveWorkers;      /* MT only : nb of workers actively compressing at probe time */
2634*01826a49SYabin Cui } ZSTD_frameProgression;
2635*01826a49SYabin Cui 
2636*01826a49SYabin Cui /* ZSTD_getFrameProgression() :
2637*01826a49SYabin Cui  * tells how much data has been ingested (read from input)
2638*01826a49SYabin Cui  * consumed (input actually compressed) and produced (output) for current frame.
2639*01826a49SYabin Cui  * Note : (ingested - consumed) is amount of input data buffered internally, not yet compressed.
2640*01826a49SYabin Cui  * Aggregates progression inside active worker threads.
2641*01826a49SYabin Cui  */
2642*01826a49SYabin Cui ZSTDLIB_STATIC_API ZSTD_frameProgression ZSTD_getFrameProgression(const ZSTD_CCtx* cctx);
2643*01826a49SYabin Cui 
2644*01826a49SYabin Cui /*! ZSTD_toFlushNow() :
2645*01826a49SYabin Cui  *  Tell how many bytes are ready to be flushed immediately.
2646*01826a49SYabin Cui  *  Useful for multithreading scenarios (nbWorkers >= 1).
2647*01826a49SYabin Cui  *  Probe the oldest active job, defined as oldest job not yet entirely flushed,
2648*01826a49SYabin Cui  *  and check its output buffer.
2649*01826a49SYabin Cui  * @return : amount of data stored in oldest job and ready to be flushed immediately.
2650*01826a49SYabin Cui  *  if @return == 0, it means either :
2651*01826a49SYabin Cui  *  + there is no active job (could be checked with ZSTD_frameProgression()), or
2652*01826a49SYabin Cui  *  + oldest job is still actively compressing data,
2653*01826a49SYabin Cui  *    but everything it has produced has also been flushed so far,
2654*01826a49SYabin Cui  *    therefore flush speed is limited by production speed of oldest job
2655*01826a49SYabin Cui  *    irrespective of the speed of concurrent (and newer) jobs.
2656*01826a49SYabin Cui  */
2657*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_toFlushNow(ZSTD_CCtx* cctx);
2658*01826a49SYabin Cui 
2659*01826a49SYabin Cui 
2660*01826a49SYabin Cui /*=====   Advanced Streaming decompression functions  =====*/
2661*01826a49SYabin Cui 
2662*01826a49SYabin Cui /*!
2663*01826a49SYabin Cui  * This function is deprecated, and is equivalent to:
2664*01826a49SYabin Cui  *
2665*01826a49SYabin Cui  *     ZSTD_DCtx_reset(zds, ZSTD_reset_session_only);
2666*01826a49SYabin Cui  *     ZSTD_DCtx_loadDictionary(zds, dict, dictSize);
2667*01826a49SYabin Cui  *
2668*01826a49SYabin Cui  * note: no dictionary will be used if dict == NULL or dictSize < 8
2669*01826a49SYabin Cui  */
2670*01826a49SYabin Cui ZSTD_DEPRECATED("use ZSTD_DCtx_reset + ZSTD_DCtx_loadDictionary, see zstd.h for detailed instructions")
2671*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_initDStream_usingDict(ZSTD_DStream* zds, const void* dict, size_t dictSize);
2672*01826a49SYabin Cui 
2673*01826a49SYabin Cui /*!
2674*01826a49SYabin Cui  * This function is deprecated, and is equivalent to:
2675*01826a49SYabin Cui  *
2676*01826a49SYabin Cui  *     ZSTD_DCtx_reset(zds, ZSTD_reset_session_only);
2677*01826a49SYabin Cui  *     ZSTD_DCtx_refDDict(zds, ddict);
2678*01826a49SYabin Cui  *
2679*01826a49SYabin Cui  * note : ddict is referenced, it must outlive decompression session
2680*01826a49SYabin Cui  */
2681*01826a49SYabin Cui ZSTD_DEPRECATED("use ZSTD_DCtx_reset + ZSTD_DCtx_refDDict, see zstd.h for detailed instructions")
2682*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_initDStream_usingDDict(ZSTD_DStream* zds, const ZSTD_DDict* ddict);
2683*01826a49SYabin Cui 
2684*01826a49SYabin Cui /*!
2685*01826a49SYabin Cui  * This function is deprecated, and is equivalent to:
2686*01826a49SYabin Cui  *
2687*01826a49SYabin Cui  *     ZSTD_DCtx_reset(zds, ZSTD_reset_session_only);
2688*01826a49SYabin Cui  *
2689*01826a49SYabin Cui  * reuse decompression parameters from previous init; saves dictionary loading
2690*01826a49SYabin Cui  */
2691*01826a49SYabin Cui ZSTD_DEPRECATED("use ZSTD_DCtx_reset, see zstd.h for detailed instructions")
2692*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_resetDStream(ZSTD_DStream* zds);
2693*01826a49SYabin Cui 
2694*01826a49SYabin Cui 
2695*01826a49SYabin Cui /* ********************* BLOCK-LEVEL SEQUENCE PRODUCER API *********************
2696*01826a49SYabin Cui  *
2697*01826a49SYabin Cui  * *** OVERVIEW ***
2698*01826a49SYabin Cui  * The Block-Level Sequence Producer API allows users to provide their own custom
2699*01826a49SYabin Cui  * sequence producer which libzstd invokes to process each block. The produced list
2700*01826a49SYabin Cui  * of sequences (literals and matches) is then post-processed by libzstd to produce
2701*01826a49SYabin Cui  * valid compressed blocks.
2702*01826a49SYabin Cui  *
2703*01826a49SYabin Cui  * This block-level offload API is a more granular complement of the existing
2704*01826a49SYabin Cui  * frame-level offload API compressSequences() (introduced in v1.5.1). It offers
2705*01826a49SYabin Cui  * an easier migration story for applications already integrated with libzstd: the
2706*01826a49SYabin Cui  * user application continues to invoke the same compression functions
2707*01826a49SYabin Cui  * ZSTD_compress2() or ZSTD_compressStream2() as usual, and transparently benefits
2708*01826a49SYabin Cui  * from the specific advantages of the external sequence producer. For example,
2709*01826a49SYabin Cui  * the sequence producer could be tuned to take advantage of known characteristics
2710*01826a49SYabin Cui  * of the input, to offer better speed / ratio, or could leverage hardware
2711*01826a49SYabin Cui  * acceleration not available within libzstd itself.
2712*01826a49SYabin Cui  *
2713*01826a49SYabin Cui  * See contrib/externalSequenceProducer for an example program employing the
2714*01826a49SYabin Cui  * Block-Level Sequence Producer API.
2715*01826a49SYabin Cui  *
2716*01826a49SYabin Cui  * *** USAGE ***
2717*01826a49SYabin Cui  * The user is responsible for implementing a function of type
2718*01826a49SYabin Cui  * ZSTD_sequenceProducer_F. For each block, zstd will pass the following
2719*01826a49SYabin Cui  * arguments to the user-provided function:
2720*01826a49SYabin Cui  *
2721*01826a49SYabin Cui  *   - sequenceProducerState: a pointer to a user-managed state for the sequence
2722*01826a49SYabin Cui  *     producer.
2723*01826a49SYabin Cui  *
2724*01826a49SYabin Cui  *   - outSeqs, outSeqsCapacity: an output buffer for the sequence producer.
2725*01826a49SYabin Cui  *     outSeqsCapacity is guaranteed >= ZSTD_sequenceBound(srcSize). The memory
2726*01826a49SYabin Cui  *     backing outSeqs is managed by the CCtx.
2727*01826a49SYabin Cui  *
2728*01826a49SYabin Cui  *   - src, srcSize: an input buffer for the sequence producer to parse.
2729*01826a49SYabin Cui  *     srcSize is guaranteed to be <= ZSTD_BLOCKSIZE_MAX.
2730*01826a49SYabin Cui  *
2731*01826a49SYabin Cui  *   - dict, dictSize: a history buffer, which may be empty, which the sequence
2732*01826a49SYabin Cui  *     producer may reference as it parses the src buffer. Currently, zstd will
2733*01826a49SYabin Cui  *     always pass dictSize == 0 into external sequence producers, but this will
2734*01826a49SYabin Cui  *     change in the future.
2735*01826a49SYabin Cui  *
2736*01826a49SYabin Cui  *   - compressionLevel: a signed integer representing the zstd compression level
2737*01826a49SYabin Cui  *     set by the user for the current operation. The sequence producer may choose
2738*01826a49SYabin Cui  *     to use this information to change its compression strategy and speed/ratio
2739*01826a49SYabin Cui  *     tradeoff. Note: the compression level does not reflect zstd parameters set
2740*01826a49SYabin Cui  *     through the advanced API.
2741*01826a49SYabin Cui  *
2742*01826a49SYabin Cui  *   - windowSize: a size_t representing the maximum allowed offset for external
2743*01826a49SYabin Cui  *     sequences. Note that sequence offsets are sometimes allowed to exceed the
2744*01826a49SYabin Cui  *     windowSize if a dictionary is present, see doc/zstd_compression_format.md
2745*01826a49SYabin Cui  *     for details.
2746*01826a49SYabin Cui  *
2747*01826a49SYabin Cui  * The user-provided function shall return a size_t representing the number of
2748*01826a49SYabin Cui  * sequences written to outSeqs. This return value will be treated as an error
2749*01826a49SYabin Cui  * code if it is greater than outSeqsCapacity. The return value must be non-zero
2750*01826a49SYabin Cui  * if srcSize is non-zero. The ZSTD_SEQUENCE_PRODUCER_ERROR macro is provided
2751*01826a49SYabin Cui  * for convenience, but any value greater than outSeqsCapacity will be treated as
2752*01826a49SYabin Cui  * an error code.
2753*01826a49SYabin Cui  *
2754*01826a49SYabin Cui  * If the user-provided function does not return an error code, the sequences
2755*01826a49SYabin Cui  * written to outSeqs must be a valid parse of the src buffer. Data corruption may
2756*01826a49SYabin Cui  * occur if the parse is not valid. A parse is defined to be valid if the
2757*01826a49SYabin Cui  * following conditions hold:
2758*01826a49SYabin Cui  *   - The sum of matchLengths and literalLengths must equal srcSize.
2759*01826a49SYabin Cui  *   - All sequences in the parse, except for the final sequence, must have
2760*01826a49SYabin Cui  *     matchLength >= ZSTD_MINMATCH_MIN. The final sequence must have
2761*01826a49SYabin Cui  *     matchLength >= ZSTD_MINMATCH_MIN or matchLength == 0.
2762*01826a49SYabin Cui  *   - All offsets must respect the windowSize parameter as specified in
2763*01826a49SYabin Cui  *     doc/zstd_compression_format.md.
2764*01826a49SYabin Cui  *   - If the final sequence has matchLength == 0, it must also have offset == 0.
2765*01826a49SYabin Cui  *
2766*01826a49SYabin Cui  * zstd will only validate these conditions (and fail compression if they do not
2767*01826a49SYabin Cui  * hold) if the ZSTD_c_validateSequences cParam is enabled. Note that sequence
2768*01826a49SYabin Cui  * validation has a performance cost.
2769*01826a49SYabin Cui  *
2770*01826a49SYabin Cui  * If the user-provided function returns an error, zstd will either fall back
2771*01826a49SYabin Cui  * to an internal sequence producer or fail the compression operation. The user can
2772*01826a49SYabin Cui  * choose between the two behaviors by setting the ZSTD_c_enableSeqProducerFallback
2773*01826a49SYabin Cui  * cParam. Fallback compression will follow any other cParam settings, such as
2774*01826a49SYabin Cui  * compression level, the same as in a normal compression operation.
2775*01826a49SYabin Cui  *
2776*01826a49SYabin Cui  * The user shall instruct zstd to use a particular ZSTD_sequenceProducer_F
2777*01826a49SYabin Cui  * function by calling
2778*01826a49SYabin Cui  *         ZSTD_registerSequenceProducer(cctx,
2779*01826a49SYabin Cui  *                                       sequenceProducerState,
2780*01826a49SYabin Cui  *                                       sequenceProducer)
2781*01826a49SYabin Cui  * This setting will persist until the next parameter reset of the CCtx.
2782*01826a49SYabin Cui  *
2783*01826a49SYabin Cui  * The sequenceProducerState must be initialized by the user before calling
2784*01826a49SYabin Cui  * ZSTD_registerSequenceProducer(). The user is responsible for destroying the
2785*01826a49SYabin Cui  * sequenceProducerState.
2786*01826a49SYabin Cui  *
2787*01826a49SYabin Cui  * *** LIMITATIONS ***
2788*01826a49SYabin Cui  * This API is compatible with all zstd compression APIs which respect advanced parameters.
2789*01826a49SYabin Cui  * However, there are three limitations:
2790*01826a49SYabin Cui  *
2791*01826a49SYabin Cui  * First, the ZSTD_c_enableLongDistanceMatching cParam is not currently supported.
2792*01826a49SYabin Cui  * COMPRESSION WILL FAIL if it is enabled and the user tries to compress with a block-level
2793*01826a49SYabin Cui  * external sequence producer.
2794*01826a49SYabin Cui  *   - Note that ZSTD_c_enableLongDistanceMatching is auto-enabled by default in some
2795*01826a49SYabin Cui  *     cases (see its documentation for details). Users must explicitly set
2796*01826a49SYabin Cui  *     ZSTD_c_enableLongDistanceMatching to ZSTD_ps_disable in such cases if an external
2797*01826a49SYabin Cui  *     sequence producer is registered.
2798*01826a49SYabin Cui  *   - As of this writing, ZSTD_c_enableLongDistanceMatching is disabled by default
2799*01826a49SYabin Cui  *     whenever ZSTD_c_windowLog < 128MB, but that's subject to change. Users should
2800*01826a49SYabin Cui  *     check the docs on ZSTD_c_enableLongDistanceMatching whenever the Block-Level Sequence
2801*01826a49SYabin Cui  *     Producer API is used in conjunction with advanced settings (like ZSTD_c_windowLog).
2802*01826a49SYabin Cui  *
2803*01826a49SYabin Cui  * Second, history buffers are not currently supported. Concretely, zstd will always pass
2804*01826a49SYabin Cui  * dictSize == 0 to the external sequence producer (for now). This has two implications:
2805*01826a49SYabin Cui  *   - Dictionaries are not currently supported. Compression will *not* fail if the user
2806*01826a49SYabin Cui  *     references a dictionary, but the dictionary won't have any effect.
2807*01826a49SYabin Cui  *   - Stream history is not currently supported. All advanced compression APIs, including
2808*01826a49SYabin Cui  *     streaming APIs, work with external sequence producers, but each block is treated as
2809*01826a49SYabin Cui  *     an independent chunk without history from previous blocks.
2810*01826a49SYabin Cui  *
2811*01826a49SYabin Cui  * Third, multi-threading within a single compression is not currently supported. In other words,
2812*01826a49SYabin Cui  * COMPRESSION WILL FAIL if ZSTD_c_nbWorkers > 0 and an external sequence producer is registered.
2813*01826a49SYabin Cui  * Multi-threading across compressions is fine: simply create one CCtx per thread.
2814*01826a49SYabin Cui  *
2815*01826a49SYabin Cui  * Long-term, we plan to overcome all three limitations. There is no technical blocker to
2816*01826a49SYabin Cui  * overcoming them. It is purely a question of engineering effort.
2817*01826a49SYabin Cui  */
2818*01826a49SYabin Cui 
2819*01826a49SYabin Cui #define ZSTD_SEQUENCE_PRODUCER_ERROR ((size_t)(-1))
2820*01826a49SYabin Cui 
2821*01826a49SYabin Cui typedef size_t (*ZSTD_sequenceProducer_F) (
2822*01826a49SYabin Cui   void* sequenceProducerState,
2823*01826a49SYabin Cui   ZSTD_Sequence* outSeqs, size_t outSeqsCapacity,
2824*01826a49SYabin Cui   const void* src, size_t srcSize,
2825*01826a49SYabin Cui   const void* dict, size_t dictSize,
2826*01826a49SYabin Cui   int compressionLevel,
2827*01826a49SYabin Cui   size_t windowSize
2828*01826a49SYabin Cui );
2829*01826a49SYabin Cui 
2830*01826a49SYabin Cui /*! ZSTD_registerSequenceProducer() :
2831*01826a49SYabin Cui  * Instruct zstd to use a block-level external sequence producer function.
2832*01826a49SYabin Cui  *
2833*01826a49SYabin Cui  * The sequenceProducerState must be initialized by the caller, and the caller is
2834*01826a49SYabin Cui  * responsible for managing its lifetime. This parameter is sticky across
2835*01826a49SYabin Cui  * compressions. It will remain set until the user explicitly resets compression
2836*01826a49SYabin Cui  * parameters.
2837*01826a49SYabin Cui  *
2838*01826a49SYabin Cui  * Sequence producer registration is considered to be an "advanced parameter",
2839*01826a49SYabin Cui  * part of the "advanced API". This means it will only have an effect on compression
2840*01826a49SYabin Cui  * APIs which respect advanced parameters, such as compress2() and compressStream2().
2841*01826a49SYabin Cui  * Older compression APIs such as compressCCtx(), which predate the introduction of
2842*01826a49SYabin Cui  * "advanced parameters", will ignore any external sequence producer setting.
2843*01826a49SYabin Cui  *
2844*01826a49SYabin Cui  * The sequence producer can be "cleared" by registering a NULL function pointer. This
2845*01826a49SYabin Cui  * removes all limitations described above in the "LIMITATIONS" section of the API docs.
2846*01826a49SYabin Cui  *
2847*01826a49SYabin Cui  * The user is strongly encouraged to read the full API documentation (above) before
2848*01826a49SYabin Cui  * calling this function. */
2849*01826a49SYabin Cui ZSTDLIB_STATIC_API void
2850*01826a49SYabin Cui ZSTD_registerSequenceProducer(
2851*01826a49SYabin Cui   ZSTD_CCtx* cctx,
2852*01826a49SYabin Cui   void* sequenceProducerState,
2853*01826a49SYabin Cui   ZSTD_sequenceProducer_F sequenceProducer
2854*01826a49SYabin Cui );
2855*01826a49SYabin Cui 
2856*01826a49SYabin Cui /*! ZSTD_CCtxParams_registerSequenceProducer() :
2857*01826a49SYabin Cui  * Same as ZSTD_registerSequenceProducer(), but operates on ZSTD_CCtx_params.
2858*01826a49SYabin Cui  * This is used for accurate size estimation with ZSTD_estimateCCtxSize_usingCCtxParams(),
2859*01826a49SYabin Cui  * which is needed when creating a ZSTD_CCtx with ZSTD_initStaticCCtx().
2860*01826a49SYabin Cui  *
2861*01826a49SYabin Cui  * If you are using the external sequence producer API in a scenario where ZSTD_initStaticCCtx()
2862*01826a49SYabin Cui  * is required, then this function is for you. Otherwise, you probably don't need it.
2863*01826a49SYabin Cui  *
2864*01826a49SYabin Cui  * See tests/zstreamtest.c for example usage. */
2865*01826a49SYabin Cui ZSTDLIB_STATIC_API void
2866*01826a49SYabin Cui ZSTD_CCtxParams_registerSequenceProducer(
2867*01826a49SYabin Cui   ZSTD_CCtx_params* params,
2868*01826a49SYabin Cui   void* sequenceProducerState,
2869*01826a49SYabin Cui   ZSTD_sequenceProducer_F sequenceProducer
2870*01826a49SYabin Cui );
2871*01826a49SYabin Cui 
2872*01826a49SYabin Cui 
2873*01826a49SYabin Cui /*********************************************************************
2874*01826a49SYabin Cui *  Buffer-less and synchronous inner streaming functions (DEPRECATED)
2875*01826a49SYabin Cui *
2876*01826a49SYabin Cui *  This API is deprecated, and will be removed in a future version.
2877*01826a49SYabin Cui *  It allows streaming (de)compression with user allocated buffers.
2878*01826a49SYabin Cui *  However, it is hard to use, and not as well tested as the rest of
2879*01826a49SYabin Cui *  our API.
2880*01826a49SYabin Cui *
2881*01826a49SYabin Cui *  Please use the normal streaming API instead: ZSTD_compressStream2,
2882*01826a49SYabin Cui *  and ZSTD_decompressStream.
2883*01826a49SYabin Cui *  If there is functionality that you need, but it doesn't provide,
2884*01826a49SYabin Cui *  please open an issue on our GitHub.
2885*01826a49SYabin Cui ********************************************************************* */
2886*01826a49SYabin Cui 
2887*01826a49SYabin Cui /**
2888*01826a49SYabin Cui   Buffer-less streaming compression (synchronous mode)
2889*01826a49SYabin Cui 
2890*01826a49SYabin Cui   A ZSTD_CCtx object is required to track streaming operations.
2891*01826a49SYabin Cui   Use ZSTD_createCCtx() / ZSTD_freeCCtx() to manage resource.
2892*01826a49SYabin Cui   ZSTD_CCtx object can be reused multiple times within successive compression operations.
2893*01826a49SYabin Cui 
2894*01826a49SYabin Cui   Start by initializing a context.
2895*01826a49SYabin Cui   Use ZSTD_compressBegin(), or ZSTD_compressBegin_usingDict() for dictionary compression.
2896*01826a49SYabin Cui 
2897*01826a49SYabin Cui   Then, consume your input using ZSTD_compressContinue().
2898*01826a49SYabin Cui   There are some important considerations to keep in mind when using this advanced function :
2899*01826a49SYabin Cui   - ZSTD_compressContinue() has no internal buffer. It uses externally provided buffers only.
2900*01826a49SYabin Cui   - Interface is synchronous : input is consumed entirely and produces 1+ compressed blocks.
2901*01826a49SYabin Cui   - Caller must ensure there is enough space in `dst` to store compressed data under worst case scenario.
2902*01826a49SYabin Cui     Worst case evaluation is provided by ZSTD_compressBound().
2903*01826a49SYabin Cui     ZSTD_compressContinue() doesn't guarantee recover after a failed compression.
2904*01826a49SYabin Cui   - ZSTD_compressContinue() presumes prior input ***is still accessible and unmodified*** (up to maximum distance size, see WindowLog).
2905*01826a49SYabin Cui     It remembers all previous contiguous blocks, plus one separated memory segment (which can itself consists of multiple contiguous blocks)
2906*01826a49SYabin Cui   - ZSTD_compressContinue() detects that prior input has been overwritten when `src` buffer overlaps.
2907*01826a49SYabin Cui     In which case, it will "discard" the relevant memory section from its history.
2908*01826a49SYabin Cui 
2909*01826a49SYabin Cui   Finish a frame with ZSTD_compressEnd(), which will write the last block(s) and optional checksum.
2910*01826a49SYabin Cui   It's possible to use srcSize==0, in which case, it will write a final empty block to end the frame.
2911*01826a49SYabin Cui   Without last block mark, frames are considered unfinished (hence corrupted) by compliant decoders.
2912*01826a49SYabin Cui 
2913*01826a49SYabin Cui   `ZSTD_CCtx` object can be reused (ZSTD_compressBegin()) to compress again.
2914*01826a49SYabin Cui */
2915*01826a49SYabin Cui 
2916*01826a49SYabin Cui /*=====   Buffer-less streaming compression functions  =====*/
2917*01826a49SYabin Cui ZSTD_DEPRECATED("The buffer-less API is deprecated in favor of the normal streaming API. See docs.")
2918*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_compressBegin(ZSTD_CCtx* cctx, int compressionLevel);
2919*01826a49SYabin Cui ZSTD_DEPRECATED("The buffer-less API is deprecated in favor of the normal streaming API. See docs.")
2920*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_compressBegin_usingDict(ZSTD_CCtx* cctx, const void* dict, size_t dictSize, int compressionLevel);
2921*01826a49SYabin Cui ZSTD_DEPRECATED("The buffer-less API is deprecated in favor of the normal streaming API. See docs.")
2922*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_compressBegin_usingCDict(ZSTD_CCtx* cctx, const ZSTD_CDict* cdict); /**< note: fails if cdict==NULL */
2923*01826a49SYabin Cui 
2924*01826a49SYabin Cui ZSTD_DEPRECATED("This function will likely be removed in a future release. It is misleading and has very limited utility.")
2925*01826a49SYabin Cui ZSTDLIB_STATIC_API
2926*01826a49SYabin Cui size_t ZSTD_copyCCtx(ZSTD_CCtx* cctx, const ZSTD_CCtx* preparedCCtx, unsigned long long pledgedSrcSize); /**<  note: if pledgedSrcSize is not known, use ZSTD_CONTENTSIZE_UNKNOWN */
2927*01826a49SYabin Cui 
2928*01826a49SYabin Cui ZSTD_DEPRECATED("The buffer-less API is deprecated in favor of the normal streaming API. See docs.")
2929*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_compressContinue(ZSTD_CCtx* cctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize);
2930*01826a49SYabin Cui ZSTD_DEPRECATED("The buffer-less API is deprecated in favor of the normal streaming API. See docs.")
2931*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_compressEnd(ZSTD_CCtx* cctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize);
2932*01826a49SYabin Cui 
2933*01826a49SYabin Cui /* The ZSTD_compressBegin_advanced() and ZSTD_compressBegin_usingCDict_advanced() are now DEPRECATED and will generate a compiler warning */
2934*01826a49SYabin Cui ZSTD_DEPRECATED("use advanced API to access custom parameters")
2935*01826a49SYabin Cui ZSTDLIB_STATIC_API
2936*01826a49SYabin Cui size_t ZSTD_compressBegin_advanced(ZSTD_CCtx* cctx, const void* dict, size_t dictSize, ZSTD_parameters params, unsigned long long pledgedSrcSize); /**< pledgedSrcSize : If srcSize is not known at init time, use ZSTD_CONTENTSIZE_UNKNOWN */
2937*01826a49SYabin Cui ZSTD_DEPRECATED("use advanced API to access custom parameters")
2938*01826a49SYabin Cui ZSTDLIB_STATIC_API
2939*01826a49SYabin Cui size_t ZSTD_compressBegin_usingCDict_advanced(ZSTD_CCtx* const cctx, const ZSTD_CDict* const cdict, ZSTD_frameParameters const fParams, unsigned long long const pledgedSrcSize);   /* compression parameters are already set within cdict. pledgedSrcSize must be correct. If srcSize is not known, use macro ZSTD_CONTENTSIZE_UNKNOWN */
2940*01826a49SYabin Cui /**
2941*01826a49SYabin Cui   Buffer-less streaming decompression (synchronous mode)
2942*01826a49SYabin Cui 
2943*01826a49SYabin Cui   A ZSTD_DCtx object is required to track streaming operations.
2944*01826a49SYabin Cui   Use ZSTD_createDCtx() / ZSTD_freeDCtx() to manage it.
2945*01826a49SYabin Cui   A ZSTD_DCtx object can be reused multiple times.
2946*01826a49SYabin Cui 
2947*01826a49SYabin Cui   First typical operation is to retrieve frame parameters, using ZSTD_getFrameHeader().
2948*01826a49SYabin Cui   Frame header is extracted from the beginning of compressed frame, so providing only the frame's beginning is enough.
2949*01826a49SYabin Cui   Data fragment must be large enough to ensure successful decoding.
2950*01826a49SYabin Cui  `ZSTD_frameHeaderSize_max` bytes is guaranteed to always be large enough.
2951*01826a49SYabin Cui   result  : 0 : successful decoding, the `ZSTD_frameHeader` structure is correctly filled.
2952*01826a49SYabin Cui            >0 : `srcSize` is too small, please provide at least result bytes on next attempt.
2953*01826a49SYabin Cui            errorCode, which can be tested using ZSTD_isError().
2954*01826a49SYabin Cui 
2955*01826a49SYabin Cui   It fills a ZSTD_frameHeader structure with important information to correctly decode the frame,
2956*01826a49SYabin Cui   such as the dictionary ID, content size, or maximum back-reference distance (`windowSize`).
2957*01826a49SYabin Cui   Note that these values could be wrong, either because of data corruption, or because a 3rd party deliberately spoofs false information.
2958*01826a49SYabin Cui   As a consequence, check that values remain within valid application range.
2959*01826a49SYabin Cui   For example, do not allocate memory blindly, check that `windowSize` is within expectation.
2960*01826a49SYabin Cui   Each application can set its own limits, depending on local restrictions.
2961*01826a49SYabin Cui   For extended interoperability, it is recommended to support `windowSize` of at least 8 MB.
2962*01826a49SYabin Cui 
2963*01826a49SYabin Cui   ZSTD_decompressContinue() needs previous data blocks during decompression, up to `windowSize` bytes.
2964*01826a49SYabin Cui   ZSTD_decompressContinue() is very sensitive to contiguity,
2965*01826a49SYabin Cui   if 2 blocks don't follow each other, make sure that either the compressor breaks contiguity at the same place,
2966*01826a49SYabin Cui   or that previous contiguous segment is large enough to properly handle maximum back-reference distance.
2967*01826a49SYabin Cui   There are multiple ways to guarantee this condition.
2968*01826a49SYabin Cui 
2969*01826a49SYabin Cui   The most memory efficient way is to use a round buffer of sufficient size.
2970*01826a49SYabin Cui   Sufficient size is determined by invoking ZSTD_decodingBufferSize_min(),
2971*01826a49SYabin Cui   which can return an error code if required value is too large for current system (in 32-bits mode).
2972*01826a49SYabin Cui   In a round buffer methodology, ZSTD_decompressContinue() decompresses each block next to previous one,
2973*01826a49SYabin Cui   up to the moment there is not enough room left in the buffer to guarantee decoding another full block,
2974*01826a49SYabin Cui   which maximum size is provided in `ZSTD_frameHeader` structure, field `blockSizeMax`.
2975*01826a49SYabin Cui   At which point, decoding can resume from the beginning of the buffer.
2976*01826a49SYabin Cui   Note that already decoded data stored in the buffer should be flushed before being overwritten.
2977*01826a49SYabin Cui 
2978*01826a49SYabin Cui   There are alternatives possible, for example using two or more buffers of size `windowSize` each, though they consume more memory.
2979*01826a49SYabin Cui 
2980*01826a49SYabin Cui   Finally, if you control the compression process, you can also ignore all buffer size rules,
2981*01826a49SYabin Cui   as long as the encoder and decoder progress in "lock-step",
2982*01826a49SYabin Cui   aka use exactly the same buffer sizes, break contiguity at the same place, etc.
2983*01826a49SYabin Cui 
2984*01826a49SYabin Cui   Once buffers are setup, start decompression, with ZSTD_decompressBegin().
2985*01826a49SYabin Cui   If decompression requires a dictionary, use ZSTD_decompressBegin_usingDict() or ZSTD_decompressBegin_usingDDict().
2986*01826a49SYabin Cui 
2987*01826a49SYabin Cui   Then use ZSTD_nextSrcSizeToDecompress() and ZSTD_decompressContinue() alternatively.
2988*01826a49SYabin Cui   ZSTD_nextSrcSizeToDecompress() tells how many bytes to provide as 'srcSize' to ZSTD_decompressContinue().
2989*01826a49SYabin Cui   ZSTD_decompressContinue() requires this _exact_ amount of bytes, or it will fail.
2990*01826a49SYabin Cui 
2991*01826a49SYabin Cui   result of ZSTD_decompressContinue() is the number of bytes regenerated within 'dst' (necessarily <= dstCapacity).
2992*01826a49SYabin Cui   It can be zero : it just means ZSTD_decompressContinue() has decoded some metadata item.
2993*01826a49SYabin Cui   It can also be an error code, which can be tested with ZSTD_isError().
2994*01826a49SYabin Cui 
2995*01826a49SYabin Cui   A frame is fully decoded when ZSTD_nextSrcSizeToDecompress() returns zero.
2996*01826a49SYabin Cui   Context can then be reset to start a new decompression.
2997*01826a49SYabin Cui 
2998*01826a49SYabin Cui   Note : it's possible to know if next input to present is a header or a block, using ZSTD_nextInputType().
2999*01826a49SYabin Cui   This information is not required to properly decode a frame.
3000*01826a49SYabin Cui 
3001*01826a49SYabin Cui   == Special case : skippable frames ==
3002*01826a49SYabin Cui 
3003*01826a49SYabin Cui   Skippable frames allow integration of user-defined data into a flow of concatenated frames.
3004*01826a49SYabin Cui   Skippable frames will be ignored (skipped) by decompressor.
3005*01826a49SYabin Cui   The format of skippable frames is as follows :
3006*01826a49SYabin Cui   a) Skippable frame ID - 4 Bytes, Little endian format, any value from 0x184D2A50 to 0x184D2A5F
3007*01826a49SYabin Cui   b) Frame Size - 4 Bytes, Little endian format, unsigned 32-bits
3008*01826a49SYabin Cui   c) Frame Content - any content (User Data) of length equal to Frame Size
3009*01826a49SYabin Cui   For skippable frames ZSTD_getFrameHeader() returns zfhPtr->frameType==ZSTD_skippableFrame.
3010*01826a49SYabin Cui   For skippable frames ZSTD_decompressContinue() always returns 0 : it only skips the content.
3011*01826a49SYabin Cui */
3012*01826a49SYabin Cui 
3013*01826a49SYabin Cui /*=====   Buffer-less streaming decompression functions  =====*/
3014*01826a49SYabin Cui 
3015*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_decodingBufferSize_min(unsigned long long windowSize, unsigned long long frameContentSize);  /**< when frame content size is not known, pass in frameContentSize == ZSTD_CONTENTSIZE_UNKNOWN */
3016*01826a49SYabin Cui 
3017*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_decompressBegin(ZSTD_DCtx* dctx);
3018*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_decompressBegin_usingDict(ZSTD_DCtx* dctx, const void* dict, size_t dictSize);
3019*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_decompressBegin_usingDDict(ZSTD_DCtx* dctx, const ZSTD_DDict* ddict);
3020*01826a49SYabin Cui 
3021*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_nextSrcSizeToDecompress(ZSTD_DCtx* dctx);
3022*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_decompressContinue(ZSTD_DCtx* dctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize);
3023*01826a49SYabin Cui 
3024*01826a49SYabin Cui /* misc */
3025*01826a49SYabin Cui ZSTD_DEPRECATED("This function will likely be removed in the next minor release. It is misleading and has very limited utility.")
3026*01826a49SYabin Cui ZSTDLIB_STATIC_API void   ZSTD_copyDCtx(ZSTD_DCtx* dctx, const ZSTD_DCtx* preparedDCtx);
3027*01826a49SYabin Cui typedef enum { ZSTDnit_frameHeader, ZSTDnit_blockHeader, ZSTDnit_block, ZSTDnit_lastBlock, ZSTDnit_checksum, ZSTDnit_skippableFrame } ZSTD_nextInputType_e;
3028*01826a49SYabin Cui ZSTDLIB_STATIC_API ZSTD_nextInputType_e ZSTD_nextInputType(ZSTD_DCtx* dctx);
3029*01826a49SYabin Cui 
3030*01826a49SYabin Cui 
3031*01826a49SYabin Cui 
3032*01826a49SYabin Cui 
3033*01826a49SYabin Cui /* ========================================= */
3034*01826a49SYabin Cui /**       Block level API (DEPRECATED)       */
3035*01826a49SYabin Cui /* ========================================= */
3036*01826a49SYabin Cui 
3037*01826a49SYabin Cui /*!
3038*01826a49SYabin Cui 
3039*01826a49SYabin Cui     This API is deprecated in favor of the regular compression API.
3040*01826a49SYabin Cui     You can get the frame header down to 2 bytes by setting:
3041*01826a49SYabin Cui       - ZSTD_c_format = ZSTD_f_zstd1_magicless
3042*01826a49SYabin Cui       - ZSTD_c_contentSizeFlag = 0
3043*01826a49SYabin Cui       - ZSTD_c_checksumFlag = 0
3044*01826a49SYabin Cui       - ZSTD_c_dictIDFlag = 0
3045*01826a49SYabin Cui 
3046*01826a49SYabin Cui     This API is not as well tested as our normal API, so we recommend not using it.
3047*01826a49SYabin Cui     We will be removing it in a future version. If the normal API doesn't provide
3048*01826a49SYabin Cui     the functionality you need, please open a GitHub issue.
3049*01826a49SYabin Cui 
3050*01826a49SYabin Cui     Block functions produce and decode raw zstd blocks, without frame metadata.
3051*01826a49SYabin Cui     Frame metadata cost is typically ~12 bytes, which can be non-negligible for very small blocks (< 100 bytes).
3052*01826a49SYabin Cui     But users will have to take in charge needed metadata to regenerate data, such as compressed and content sizes.
3053*01826a49SYabin Cui 
3054*01826a49SYabin Cui     A few rules to respect :
3055*01826a49SYabin Cui     - Compressing and decompressing require a context structure
3056*01826a49SYabin Cui       + Use ZSTD_createCCtx() and ZSTD_createDCtx()
3057*01826a49SYabin Cui     - It is necessary to init context before starting
3058*01826a49SYabin Cui       + compression : any ZSTD_compressBegin*() variant, including with dictionary
3059*01826a49SYabin Cui       + decompression : any ZSTD_decompressBegin*() variant, including with dictionary
3060*01826a49SYabin Cui     - Block size is limited, it must be <= ZSTD_getBlockSize() <= ZSTD_BLOCKSIZE_MAX == 128 KB
3061*01826a49SYabin Cui       + If input is larger than a block size, it's necessary to split input data into multiple blocks
3062*01826a49SYabin Cui       + For inputs larger than a single block, consider using regular ZSTD_compress() instead.
3063*01826a49SYabin Cui         Frame metadata is not that costly, and quickly becomes negligible as source size grows larger than a block.
3064*01826a49SYabin Cui     - When a block is considered not compressible enough, ZSTD_compressBlock() result will be 0 (zero) !
3065*01826a49SYabin Cui       ===> In which case, nothing is produced into `dst` !
3066*01826a49SYabin Cui       + User __must__ test for such outcome and deal directly with uncompressed data
3067*01826a49SYabin Cui       + A block cannot be declared incompressible if ZSTD_compressBlock() return value was != 0.
3068*01826a49SYabin Cui         Doing so would mess up with statistics history, leading to potential data corruption.
3069*01826a49SYabin Cui       + ZSTD_decompressBlock() _doesn't accept uncompressed data as input_ !!
3070*01826a49SYabin Cui       + In case of multiple successive blocks, should some of them be uncompressed,
3071*01826a49SYabin Cui         decoder must be informed of their existence in order to follow proper history.
3072*01826a49SYabin Cui         Use ZSTD_insertBlock() for such a case.
3073*01826a49SYabin Cui */
3074*01826a49SYabin Cui 
3075*01826a49SYabin Cui /*=====   Raw zstd block functions  =====*/
3076*01826a49SYabin Cui ZSTD_DEPRECATED("The block API is deprecated in favor of the normal compression API. See docs.")
3077*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_getBlockSize   (const ZSTD_CCtx* cctx);
3078*01826a49SYabin Cui ZSTD_DEPRECATED("The block API is deprecated in favor of the normal compression API. See docs.")
3079*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_compressBlock  (ZSTD_CCtx* cctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize);
3080*01826a49SYabin Cui ZSTD_DEPRECATED("The block API is deprecated in favor of the normal compression API. See docs.")
3081*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_decompressBlock(ZSTD_DCtx* dctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize);
3082*01826a49SYabin Cui ZSTD_DEPRECATED("The block API is deprecated in favor of the normal compression API. See docs.")
3083*01826a49SYabin Cui ZSTDLIB_STATIC_API size_t ZSTD_insertBlock    (ZSTD_DCtx* dctx, const void* blockStart, size_t blockSize);  /**< insert uncompressed block into `dctx` history. Useful for multi-blocks decompression. */
3084*01826a49SYabin Cui 
3085*01826a49SYabin Cui #endif   /* ZSTD_H_ZSTD_STATIC_LINKING_ONLY */
3086*01826a49SYabin Cui 
3087*01826a49SYabin Cui #if defined (__cplusplus)
3088*01826a49SYabin Cui }
3089*01826a49SYabin Cui #endif
3090