34 |
36 |
35 |
37 |
36 /******************************************************************************************************* |
38 /******************************************************************************************************* |
37 Introduction |
39 Introduction |
38 |
40 |
39 zstd, short for Zstandard, is a fast lossless compression algorithm, targeting real-time compression scenarios |
41 zstd, short for Zstandard, is a fast lossless compression algorithm, |
40 at zlib-level and better compression ratios. The zstd compression library provides in-memory compression and |
42 targeting real-time compression scenarios at zlib-level and better compression ratios. |
41 decompression functions. The library supports compression levels from 1 up to ZSTD_maxCLevel() which is 22. |
43 The zstd compression library provides in-memory compression and decompression functions. |
42 Levels >= 20, labelled `--ultra`, should be used with caution, as they require more memory. |
44 The library supports compression levels from 1 up to ZSTD_maxCLevel() which is currently 22. |
|
45 Levels >= 20, labeled `--ultra`, should be used with caution, as they require more memory. |
43 Compression can be done in: |
46 Compression can be done in: |
44 - a single step (described as Simple API) |
47 - a single step (described as Simple API) |
45 - a single step, reusing a context (described as Explicit memory management) |
48 - a single step, reusing a context (described as Explicit context) |
46 - unbounded multiple steps (described as Streaming compression) |
49 - unbounded multiple steps (described as Streaming compression) |
47 The compression ratio achievable on small data can be highly improved using compression with a dictionary in: |
50 The compression ratio achievable on small data can be highly improved using a dictionary in: |
48 - a single step (described as Simple dictionary API) |
51 - a single step (described as Simple dictionary API) |
49 - a single step, reusing a dictionary (described as Fast dictionary API) |
52 - a single step, reusing a dictionary (described as Bulk-processing dictionary API) |
50 |
53 |
51 Advanced experimental functions can be accessed using #define ZSTD_STATIC_LINKING_ONLY before including zstd.h. |
54 Advanced experimental functions can be accessed using #define ZSTD_STATIC_LINKING_ONLY before including zstd.h. |
52 These APIs shall never be used with a dynamic library. |
55 Advanced experimental APIs shall never be used with a dynamic library. |
53 They are not "stable", their definition may change in the future. Only static linking is allowed. |
56 They are not "stable", their definition may change in the future. Only static linking is allowed. |
54 *********************************************************************************************************/ |
57 *********************************************************************************************************/ |
55 |
58 |
56 /*------ Version ------*/ |
59 /*------ Version ------*/ |
57 #define ZSTD_VERSION_MAJOR 1 |
60 #define ZSTD_VERSION_MAJOR 1 |
58 #define ZSTD_VERSION_MINOR 1 |
61 #define ZSTD_VERSION_MINOR 3 |
59 #define ZSTD_VERSION_RELEASE 3 |
62 #define ZSTD_VERSION_RELEASE 4 |
|
63 |
|
64 #define ZSTD_VERSION_NUMBER (ZSTD_VERSION_MAJOR *100*100 + ZSTD_VERSION_MINOR *100 + ZSTD_VERSION_RELEASE) |
|
65 ZSTDLIB_API unsigned ZSTD_versionNumber(void); /**< useful to check dll version */ |
60 |
66 |
61 #define ZSTD_LIB_VERSION ZSTD_VERSION_MAJOR.ZSTD_VERSION_MINOR.ZSTD_VERSION_RELEASE |
67 #define ZSTD_LIB_VERSION ZSTD_VERSION_MAJOR.ZSTD_VERSION_MINOR.ZSTD_VERSION_RELEASE |
62 #define ZSTD_QUOTE(str) #str |
68 #define ZSTD_QUOTE(str) #str |
63 #define ZSTD_EXPAND_AND_QUOTE(str) ZSTD_QUOTE(str) |
69 #define ZSTD_EXPAND_AND_QUOTE(str) ZSTD_QUOTE(str) |
64 #define ZSTD_VERSION_STRING ZSTD_EXPAND_AND_QUOTE(ZSTD_LIB_VERSION) |
70 #define ZSTD_VERSION_STRING ZSTD_EXPAND_AND_QUOTE(ZSTD_LIB_VERSION) |
65 |
71 ZSTDLIB_API const char* ZSTD_versionString(void); /* added in v1.3.0 */ |
66 #define ZSTD_VERSION_NUMBER (ZSTD_VERSION_MAJOR *100*100 + ZSTD_VERSION_MINOR *100 + ZSTD_VERSION_RELEASE) |
|
67 ZSTDLIB_API unsigned ZSTD_versionNumber(void); /**< library version number; to be used when checking dll version */ |
|
68 |
72 |
69 |
73 |
70 /*************************************** |
74 /*************************************** |
71 * Simple API |
75 * Simple API |
72 ***************************************/ |
76 ***************************************/ |
73 /*! ZSTD_compress() : |
77 /*! ZSTD_compress() : |
74 Compresses `src` content as a single zstd compressed frame into already allocated `dst`. |
78 * Compresses `src` content as a single zstd compressed frame into already allocated `dst`. |
75 Hint : compression runs faster if `dstCapacity` >= `ZSTD_compressBound(srcSize)`. |
79 * Hint : compression runs faster if `dstCapacity` >= `ZSTD_compressBound(srcSize)`. |
76 @return : compressed size written into `dst` (<= `dstCapacity), |
80 * @return : compressed size written into `dst` (<= `dstCapacity), |
77 or an error code if it fails (which can be tested using ZSTD_isError()). */ |
81 * or an error code if it fails (which can be tested using ZSTD_isError()). */ |
78 ZSTDLIB_API size_t ZSTD_compress( void* dst, size_t dstCapacity, |
82 ZSTDLIB_API size_t ZSTD_compress( void* dst, size_t dstCapacity, |
79 const void* src, size_t srcSize, |
83 const void* src, size_t srcSize, |
80 int compressionLevel); |
84 int compressionLevel); |
81 |
85 |
82 /*! ZSTD_decompress() : |
86 /*! ZSTD_decompress() : |
83 `compressedSize` : must be the _exact_ size of a single compressed frame. |
87 * `compressedSize` : must be the _exact_ size of some number of compressed and/or skippable frames. |
84 `dstCapacity` is an upper bound of originalSize. |
88 * `dstCapacity` is an upper bound of originalSize to regenerate. |
85 If user cannot imply a maximum upper bound, it's better to use streaming mode to decompress data. |
89 * If user cannot imply a maximum upper bound, it's better to use streaming mode to decompress data. |
86 @return : the number of bytes decompressed into `dst` (<= `dstCapacity`), |
90 * @return : the number of bytes decompressed into `dst` (<= `dstCapacity`), |
87 or an errorCode if it fails (which can be tested using ZSTD_isError()). */ |
91 * or an errorCode if it fails (which can be tested using ZSTD_isError()). */ |
88 ZSTDLIB_API size_t ZSTD_decompress( void* dst, size_t dstCapacity, |
92 ZSTDLIB_API size_t ZSTD_decompress( void* dst, size_t dstCapacity, |
89 const void* src, size_t compressedSize); |
93 const void* src, size_t compressedSize); |
90 |
94 |
|
95 /*! ZSTD_getFrameContentSize() : added in v1.3.0 |
|
96 * `src` should point to the start of a ZSTD encoded frame. |
|
97 * `srcSize` must be at least as large as the frame header. |
|
98 * hint : any size >= `ZSTD_frameHeaderSize_max` is large enough. |
|
99 * @return : - decompressed size of the frame in `src`, if known |
|
100 * - ZSTD_CONTENTSIZE_UNKNOWN if the size cannot be determined |
|
101 * - ZSTD_CONTENTSIZE_ERROR if an error occurred (e.g. invalid magic number, srcSize too small) |
|
102 * note 1 : a 0 return value means the frame is valid but "empty". |
|
103 * note 2 : decompressed size is an optional field, it may not be present, typically in streaming mode. |
|
104 * When `return==ZSTD_CONTENTSIZE_UNKNOWN`, data to decompress could be any size. |
|
105 * In which case, it's necessary to use streaming mode to decompress data. |
|
106 * Optionally, application can rely on some implicit limit, |
|
107 * as ZSTD_decompress() only needs an upper bound of decompressed size. |
|
108 * (For example, data could be necessarily cut into blocks <= 16 KB). |
|
109 * note 3 : decompressed size is always present when compression is done with ZSTD_compress() |
|
110 * note 4 : decompressed size can be very large (64-bits value), |
|
111 * potentially larger than what local system can handle as a single memory segment. |
|
112 * In which case, it's necessary to use streaming mode to decompress data. |
|
113 * note 5 : If source is untrusted, decompressed size could be wrong or intentionally modified. |
|
114 * Always ensure return value fits within application's authorized limits. |
|
115 * Each application can set its own limits. |
|
116 * note 6 : This function replaces ZSTD_getDecompressedSize() */ |
|
117 #define ZSTD_CONTENTSIZE_UNKNOWN (0ULL - 1) |
|
118 #define ZSTD_CONTENTSIZE_ERROR (0ULL - 2) |
|
119 ZSTDLIB_API unsigned long long ZSTD_getFrameContentSize(const void *src, size_t srcSize); |
|
120 |
91 /*! ZSTD_getDecompressedSize() : |
121 /*! ZSTD_getDecompressedSize() : |
92 * 'src' is the start of a zstd compressed frame. |
122 * NOTE: This function is now obsolete, in favor of ZSTD_getFrameContentSize(). |
93 * @return : content size to be decompressed, as a 64-bits value _if known_, 0 otherwise. |
123 * Both functions work the same way, but ZSTD_getDecompressedSize() blends |
94 * note 1 : decompressed size is an optional field, that may not be present, especially in streaming mode. |
124 * "empty", "unknown" and "error" results to the same return value (0), |
95 * When `return==0`, data to decompress could be any size. |
125 * while ZSTD_getFrameContentSize() gives them separate return values. |
96 * In which case, it's necessary to use streaming mode to decompress data. |
126 * `src` is the start of a zstd compressed frame. |
97 * Optionally, application can still use ZSTD_decompress() while relying on implied limits. |
127 * @return : content size to be decompressed, as a 64-bits value _if known and not empty_, 0 otherwise. */ |
98 * (For example, data may be necessarily cut into blocks <= 16 KB). |
|
99 * note 2 : decompressed size is always present when compression is done with ZSTD_compress() |
|
100 * note 3 : decompressed size can be very large (64-bits value), |
|
101 * potentially larger than what local system can handle as a single memory segment. |
|
102 * In which case, it's necessary to use streaming mode to decompress data. |
|
103 * note 4 : If source is untrusted, decompressed size could be wrong or intentionally modified. |
|
104 * Always ensure result fits within application's authorized limits. |
|
105 * Each application can set its own limits. |
|
106 * note 5 : when `return==0`, if precise failure cause is needed, use ZSTD_getFrameParams() to know more. */ |
|
107 ZSTDLIB_API unsigned long long ZSTD_getDecompressedSize(const void* src, size_t srcSize); |
128 ZSTDLIB_API unsigned long long ZSTD_getDecompressedSize(const void* src, size_t srcSize); |
108 |
129 |
109 |
130 |
110 /*====== Helper functions ======*/ |
131 /*====== Helper functions ======*/ |
111 ZSTDLIB_API int ZSTD_maxCLevel(void); /*!< maximum compression level available */ |
132 #define ZSTD_COMPRESSBOUND(srcSize) ((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 */ |
112 ZSTDLIB_API size_t ZSTD_compressBound(size_t srcSize); /*!< maximum compressed size in worst case scenario */ |
133 ZSTDLIB_API size_t ZSTD_compressBound(size_t srcSize); /*!< maximum compressed size in worst case single-pass scenario */ |
113 ZSTDLIB_API unsigned ZSTD_isError(size_t code); /*!< tells if a `size_t` function result is an error code */ |
134 ZSTDLIB_API unsigned ZSTD_isError(size_t code); /*!< tells if a `size_t` function result is an error code */ |
114 ZSTDLIB_API const char* ZSTD_getErrorName(size_t code); /*!< provides readable string from an error code */ |
135 ZSTDLIB_API const char* ZSTD_getErrorName(size_t code); /*!< provides readable string from an error code */ |
|
136 ZSTDLIB_API int ZSTD_maxCLevel(void); /*!< maximum compression level available */ |
115 |
137 |
116 |
138 |
117 /*************************************** |
139 /*************************************** |
118 * Explicit memory management |
140 * Explicit context |
119 ***************************************/ |
141 ***************************************/ |
120 /*= Compression context |
142 /*= Compression context |
121 * When compressing many times, |
143 * When compressing many times, |
122 * it is recommended to allocate a context just once, and re-use it for each successive compression operation. |
144 * it is recommended to allocate a context just once, and re-use it for each successive compression operation. |
123 * This will make workload friendlier for system's memory. |
145 * This will make workload friendlier for system's memory. |
124 * Use one context per thread for parallel execution in multi-threaded environments. */ |
146 * Use one context per thread for parallel execution in multi-threaded environments. */ |
125 typedef struct ZSTD_CCtx_s ZSTD_CCtx; |
147 typedef struct ZSTD_CCtx_s ZSTD_CCtx; |
126 ZSTDLIB_API ZSTD_CCtx* ZSTD_createCCtx(void); |
148 ZSTDLIB_API ZSTD_CCtx* ZSTD_createCCtx(void); |
127 ZSTDLIB_API size_t ZSTD_freeCCtx(ZSTD_CCtx* cctx); |
149 ZSTDLIB_API size_t ZSTD_freeCCtx(ZSTD_CCtx* cctx); |
128 |
150 |
129 /*! ZSTD_compressCCtx() : |
151 /*! ZSTD_compressCCtx() : |
130 Same as ZSTD_compress(), requires an allocated ZSTD_CCtx (see ZSTD_createCCtx()). */ |
152 * Same as ZSTD_compress(), requires an allocated ZSTD_CCtx (see ZSTD_createCCtx()). */ |
131 ZSTDLIB_API size_t ZSTD_compressCCtx(ZSTD_CCtx* ctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize, int compressionLevel); |
153 ZSTDLIB_API size_t ZSTD_compressCCtx(ZSTD_CCtx* ctx, |
132 |
154 void* dst, size_t dstCapacity, |
133 /*= Decompression context */ |
155 const void* src, size_t srcSize, |
|
156 int compressionLevel); |
|
157 |
|
158 /*= Decompression context |
|
159 * When decompressing many times, |
|
160 * it is recommended to allocate a context only once, |
|
161 * and re-use it for each successive compression operation. |
|
162 * This will make workload friendlier for system's memory. |
|
163 * Use one context per thread for parallel execution. */ |
134 typedef struct ZSTD_DCtx_s ZSTD_DCtx; |
164 typedef struct ZSTD_DCtx_s ZSTD_DCtx; |
135 ZSTDLIB_API ZSTD_DCtx* ZSTD_createDCtx(void); |
165 ZSTDLIB_API ZSTD_DCtx* ZSTD_createDCtx(void); |
136 ZSTDLIB_API size_t ZSTD_freeDCtx(ZSTD_DCtx* dctx); |
166 ZSTDLIB_API size_t ZSTD_freeDCtx(ZSTD_DCtx* dctx); |
137 |
167 |
138 /*! ZSTD_decompressDCtx() : |
168 /*! ZSTD_decompressDCtx() : |
139 * Same as ZSTD_decompress(), requires an allocated ZSTD_DCtx (see ZSTD_createDCtx()). */ |
169 * Same as ZSTD_decompress(), requires an allocated ZSTD_DCtx (see ZSTD_createDCtx()) */ |
140 ZSTDLIB_API size_t ZSTD_decompressDCtx(ZSTD_DCtx* ctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize); |
170 ZSTDLIB_API size_t ZSTD_decompressDCtx(ZSTD_DCtx* ctx, |
|
171 void* dst, size_t dstCapacity, |
|
172 const void* src, size_t srcSize); |
141 |
173 |
142 |
174 |
143 /************************** |
175 /************************** |
144 * Simple dictionary API |
176 * Simple dictionary API |
145 ***************************/ |
177 ***************************/ |
146 /*! ZSTD_compress_usingDict() : |
178 /*! ZSTD_compress_usingDict() : |
147 * Compression using a predefined Dictionary (see dictBuilder/zdict.h). |
179 * Compression using a predefined Dictionary (see dictBuilder/zdict.h). |
148 * Note : This function loads the dictionary, resulting in significant startup delay. |
180 * Note : This function loads the dictionary, resulting in significant startup delay. |
149 * Note : When `dict == NULL || dictSize < 8` no dictionary is used. */ |
181 * Note : When `dict == NULL || dictSize < 8` no dictionary is used. */ |
150 ZSTDLIB_API size_t ZSTD_compress_usingDict(ZSTD_CCtx* ctx, |
182 ZSTDLIB_API size_t ZSTD_compress_usingDict(ZSTD_CCtx* ctx, |
151 void* dst, size_t dstCapacity, |
183 void* dst, size_t dstCapacity, |
152 const void* src, size_t srcSize, |
184 const void* src, size_t srcSize, |
153 const void* dict,size_t dictSize, |
185 const void* dict,size_t dictSize, |
154 int compressionLevel); |
186 int compressionLevel); |
155 |
187 |
156 /*! ZSTD_decompress_usingDict() : |
188 /*! ZSTD_decompress_usingDict() : |
157 * Decompression using a predefined Dictionary (see dictBuilder/zdict.h). |
189 * Decompression using a predefined Dictionary (see dictBuilder/zdict.h). |
158 * Dictionary must be identical to the one used during compression. |
190 * Dictionary must be identical to the one used during compression. |
159 * Note : This function loads the dictionary, resulting in significant startup delay. |
191 * Note : This function loads the dictionary, resulting in significant startup delay. |
160 * Note : When `dict == NULL || dictSize < 8` no dictionary is used. */ |
192 * Note : When `dict == NULL || dictSize < 8` no dictionary is used. */ |
161 ZSTDLIB_API size_t ZSTD_decompress_usingDict(ZSTD_DCtx* dctx, |
193 ZSTDLIB_API size_t ZSTD_decompress_usingDict(ZSTD_DCtx* dctx, |
162 void* dst, size_t dstCapacity, |
194 void* dst, size_t dstCapacity, |
163 const void* src, size_t srcSize, |
195 const void* src, size_t srcSize, |
164 const void* dict,size_t dictSize); |
196 const void* dict,size_t dictSize); |
165 |
197 |
166 |
198 |
167 /**************************** |
199 /********************************** |
168 * Fast dictionary API |
200 * Bulk processing dictionary API |
169 ****************************/ |
201 *********************************/ |
170 typedef struct ZSTD_CDict_s ZSTD_CDict; |
202 typedef struct ZSTD_CDict_s ZSTD_CDict; |
171 |
203 |
172 /*! ZSTD_createCDict() : |
204 /*! ZSTD_createCDict() : |
173 * When compressing multiple messages / blocks with the same dictionary, it's recommended to load it just once. |
205 * When compressing multiple messages / blocks with the same dictionary, it's recommended to load it just once. |
174 * ZSTD_createCDict() will create a digested dictionary, ready to start future compression operations without startup delay. |
206 * ZSTD_createCDict() will create a digested dictionary, ready to start future compression operations without startup delay. |
175 * ZSTD_CDict can be created once and used by multiple threads concurrently, as its usage is read-only. |
207 * ZSTD_CDict can be created once and shared by multiple threads concurrently, since its usage is read-only. |
176 * `dictBuffer` can be released after ZSTD_CDict creation, as its content is copied within CDict */ |
208 * `dictBuffer` can be released after ZSTD_CDict creation, since its content is copied within CDict */ |
177 ZSTDLIB_API ZSTD_CDict* ZSTD_createCDict(const void* dictBuffer, size_t dictSize, int compressionLevel); |
209 ZSTDLIB_API ZSTD_CDict* ZSTD_createCDict(const void* dictBuffer, size_t dictSize, |
|
210 int compressionLevel); |
178 |
211 |
179 /*! ZSTD_freeCDict() : |
212 /*! ZSTD_freeCDict() : |
180 * Function frees memory allocated by ZSTD_createCDict(). */ |
213 * Function frees memory allocated by ZSTD_createCDict(). */ |
181 ZSTDLIB_API size_t ZSTD_freeCDict(ZSTD_CDict* CDict); |
214 ZSTDLIB_API size_t ZSTD_freeCDict(ZSTD_CDict* CDict); |
182 |
215 |
183 /*! ZSTD_compress_usingCDict() : |
216 /*! ZSTD_compress_usingCDict() : |
184 * Compression using a digested Dictionary. |
217 * Compression using a digested Dictionary. |
185 * Faster startup than ZSTD_compress_usingDict(), recommended when same dictionary is used multiple times. |
218 * Faster startup than ZSTD_compress_usingDict(), recommended when same dictionary is used multiple times. |
186 * Note that compression level is decided during dictionary creation. */ |
219 * Note that compression level is decided during dictionary creation. |
|
220 * Frame parameters are hardcoded (dictID=yes, contentSize=yes, checksum=no) */ |
187 ZSTDLIB_API size_t ZSTD_compress_usingCDict(ZSTD_CCtx* cctx, |
221 ZSTDLIB_API size_t ZSTD_compress_usingCDict(ZSTD_CCtx* cctx, |
188 void* dst, size_t dstCapacity, |
222 void* dst, size_t dstCapacity, |
189 const void* src, size_t srcSize, |
223 const void* src, size_t srcSize, |
190 const ZSTD_CDict* cdict); |
224 const ZSTD_CDict* cdict); |
191 |
225 |
192 |
226 |
193 typedef struct ZSTD_DDict_s ZSTD_DDict; |
227 typedef struct ZSTD_DDict_s ZSTD_DDict; |
194 |
228 |
195 /*! ZSTD_createDDict() : |
229 /*! ZSTD_createDDict() : |
196 * Create a digested dictionary, ready to start decompression operation without startup delay. |
230 * Create a digested dictionary, ready to start decompression operation without startup delay. |
197 * dictBuffer can be released after DDict creation, as its content is copied inside DDict */ |
231 * dictBuffer can be released after DDict creation, as its content is copied inside DDict */ |
198 ZSTDLIB_API ZSTD_DDict* ZSTD_createDDict(const void* dictBuffer, size_t dictSize); |
232 ZSTDLIB_API ZSTD_DDict* ZSTD_createDDict(const void* dictBuffer, size_t dictSize); |
199 |
233 |
200 /*! ZSTD_freeDDict() : |
234 /*! ZSTD_freeDDict() : |
201 * Function frees memory allocated with ZSTD_createDDict() */ |
235 * Function frees memory allocated with ZSTD_createDDict() */ |
202 ZSTDLIB_API size_t ZSTD_freeDDict(ZSTD_DDict* ddict); |
236 ZSTDLIB_API size_t ZSTD_freeDDict(ZSTD_DDict* ddict); |
203 |
237 |
204 /*! ZSTD_decompress_usingDDict() : |
238 /*! ZSTD_decompress_usingDDict() : |
205 * Decompression using a digested Dictionary. |
239 * Decompression using a digested Dictionary. |
206 * Faster startup than ZSTD_decompress_usingDict(), recommended when same dictionary is used multiple times. */ |
240 * Faster startup than ZSTD_decompress_usingDict(), recommended when same dictionary is used multiple times. */ |
207 ZSTDLIB_API size_t ZSTD_decompress_usingDDict(ZSTD_DCtx* dctx, |
241 ZSTDLIB_API size_t ZSTD_decompress_usingDDict(ZSTD_DCtx* dctx, |
208 void* dst, size_t dstCapacity, |
242 void* dst, size_t dstCapacity, |
209 const void* src, size_t srcSize, |
243 const void* src, size_t srcSize, |
210 const ZSTD_DDict* ddict); |
244 const ZSTD_DDict* ddict); |
211 |
245 |
377 typedef struct { |
427 typedef struct { |
378 ZSTD_compressionParameters cParams; |
428 ZSTD_compressionParameters cParams; |
379 ZSTD_frameParameters fParams; |
429 ZSTD_frameParameters fParams; |
380 } ZSTD_parameters; |
430 } ZSTD_parameters; |
381 |
431 |
382 /*= Custom memory allocation functions */ |
432 typedef struct ZSTD_CCtx_params_s ZSTD_CCtx_params; |
|
433 |
|
434 typedef enum { |
|
435 ZSTD_dct_auto=0, /* dictionary is "full" when starting with ZSTD_MAGIC_DICTIONARY, otherwise it is "rawContent" */ |
|
436 ZSTD_dct_rawContent, /* ensures dictionary is always loaded as rawContent, even if it starts with ZSTD_MAGIC_DICTIONARY */ |
|
437 ZSTD_dct_fullDict /* refuses to load a dictionary if it does not respect Zstandard's specification */ |
|
438 } ZSTD_dictContentType_e; |
|
439 |
|
440 typedef enum { |
|
441 ZSTD_dlm_byCopy = 0, /**< Copy dictionary content internally */ |
|
442 ZSTD_dlm_byRef, /**< Reference dictionary content -- the dictionary buffer must outlive its users. */ |
|
443 } ZSTD_dictLoadMethod_e; |
|
444 |
|
445 |
|
446 |
|
447 /*************************************** |
|
448 * Frame size functions |
|
449 ***************************************/ |
|
450 |
|
451 /*! ZSTD_findFrameCompressedSize() : |
|
452 * `src` should point to the start of a ZSTD encoded frame or skippable frame |
|
453 * `srcSize` must be >= first frame size |
|
454 * @return : the compressed size of the first frame starting at `src`, |
|
455 * suitable to pass to `ZSTD_decompress` or similar, |
|
456 * or an error code if input is invalid */ |
|
457 ZSTDLIB_API size_t ZSTD_findFrameCompressedSize(const void* src, size_t srcSize); |
|
458 |
|
459 /*! ZSTD_findDecompressedSize() : |
|
460 * `src` should point the start of a series of ZSTD encoded and/or skippable frames |
|
461 * `srcSize` must be the _exact_ size of this series |
|
462 * (i.e. there should be a frame boundary exactly at `srcSize` bytes after `src`) |
|
463 * @return : - decompressed size of all data in all successive frames |
|
464 * - if the decompressed size cannot be determined: ZSTD_CONTENTSIZE_UNKNOWN |
|
465 * - if an error occurred: ZSTD_CONTENTSIZE_ERROR |
|
466 * |
|
467 * note 1 : decompressed size is an optional field, that may not be present, especially in streaming mode. |
|
468 * When `return==ZSTD_CONTENTSIZE_UNKNOWN`, data to decompress could be any size. |
|
469 * In which case, it's necessary to use streaming mode to decompress data. |
|
470 * note 2 : decompressed size is always present when compression is done with ZSTD_compress() |
|
471 * note 3 : decompressed size can be very large (64-bits value), |
|
472 * potentially larger than what local system can handle as a single memory segment. |
|
473 * In which case, it's necessary to use streaming mode to decompress data. |
|
474 * note 4 : If source is untrusted, decompressed size could be wrong or intentionally modified. |
|
475 * Always ensure result fits within application's authorized limits. |
|
476 * Each application can set its own limits. |
|
477 * note 5 : ZSTD_findDecompressedSize handles multiple frames, and so it must traverse the input to |
|
478 * read each contained frame header. This is fast as most of the data is skipped, |
|
479 * however it does mean that all frame data must be present and valid. */ |
|
480 ZSTDLIB_API unsigned long long ZSTD_findDecompressedSize(const void* src, size_t srcSize); |
|
481 |
|
482 /*! ZSTD_frameHeaderSize() : |
|
483 * `src` should point to the start of a ZSTD frame |
|
484 * `srcSize` must be >= ZSTD_frameHeaderSize_prefix. |
|
485 * @return : size of the Frame Header */ |
|
486 ZSTDLIB_API size_t ZSTD_frameHeaderSize(const void* src, size_t srcSize); |
|
487 |
|
488 |
|
489 /*************************************** |
|
490 * Memory management |
|
491 ***************************************/ |
|
492 |
|
493 /*! ZSTD_sizeof_*() : |
|
494 * These functions give the current memory usage of selected object. |
|
495 * Object memory usage can evolve when re-used. */ |
|
496 ZSTDLIB_API size_t ZSTD_sizeof_CCtx(const ZSTD_CCtx* cctx); |
|
497 ZSTDLIB_API size_t ZSTD_sizeof_DCtx(const ZSTD_DCtx* dctx); |
|
498 ZSTDLIB_API size_t ZSTD_sizeof_CStream(const ZSTD_CStream* zcs); |
|
499 ZSTDLIB_API size_t ZSTD_sizeof_DStream(const ZSTD_DStream* zds); |
|
500 ZSTDLIB_API size_t ZSTD_sizeof_CDict(const ZSTD_CDict* cdict); |
|
501 ZSTDLIB_API size_t ZSTD_sizeof_DDict(const ZSTD_DDict* ddict); |
|
502 |
|
503 /*! ZSTD_estimate*() : |
|
504 * These functions make it possible to estimate memory usage |
|
505 * of a future {D,C}Ctx, before its creation. |
|
506 * ZSTD_estimateCCtxSize() will provide a budget large enough for any compression level up to selected one. |
|
507 * It will also consider src size to be arbitrarily "large", which is worst case. |
|
508 * If srcSize is known to always be small, ZSTD_estimateCCtxSize_usingCParams() can provide a tighter estimation. |
|
509 * ZSTD_estimateCCtxSize_usingCParams() can be used in tandem with ZSTD_getCParams() to create cParams from compressionLevel. |
|
510 * ZSTD_estimateCCtxSize_usingCCtxParams() can be used in tandem with ZSTD_CCtxParam_setParameter(). Only single-threaded compression is supported. This function will return an error code if ZSTD_p_nbWorkers is >= 1. |
|
511 * Note : CCtx size estimation is only correct for single-threaded compression. */ |
|
512 ZSTDLIB_API size_t ZSTD_estimateCCtxSize(int compressionLevel); |
|
513 ZSTDLIB_API size_t ZSTD_estimateCCtxSize_usingCParams(ZSTD_compressionParameters cParams); |
|
514 ZSTDLIB_API size_t ZSTD_estimateCCtxSize_usingCCtxParams(const ZSTD_CCtx_params* params); |
|
515 ZSTDLIB_API size_t ZSTD_estimateDCtxSize(void); |
|
516 |
|
517 /*! ZSTD_estimateCStreamSize() : |
|
518 * ZSTD_estimateCStreamSize() will provide a budget large enough for any compression level up to selected one. |
|
519 * It will also consider src size to be arbitrarily "large", which is worst case. |
|
520 * If srcSize is known to always be small, ZSTD_estimateCStreamSize_usingCParams() can provide a tighter estimation. |
|
521 * ZSTD_estimateCStreamSize_usingCParams() can be used in tandem with ZSTD_getCParams() to create cParams from compressionLevel. |
|
522 * ZSTD_estimateCStreamSize_usingCCtxParams() can be used in tandem with ZSTD_CCtxParam_setParameter(). Only single-threaded compression is supported. This function will return an error code if ZSTD_p_nbWorkers is >= 1. |
|
523 * Note : CStream size estimation is only correct for single-threaded compression. |
|
524 * ZSTD_DStream memory budget depends on window Size. |
|
525 * This information can be passed manually, using ZSTD_estimateDStreamSize, |
|
526 * or deducted from a valid frame Header, using ZSTD_estimateDStreamSize_fromFrame(); |
|
527 * Note : if streaming is init with function ZSTD_init?Stream_usingDict(), |
|
528 * an internal ?Dict will be created, which additional size is not estimated here. |
|
529 * In this case, get total size by adding ZSTD_estimate?DictSize */ |
|
530 ZSTDLIB_API size_t ZSTD_estimateCStreamSize(int compressionLevel); |
|
531 ZSTDLIB_API size_t ZSTD_estimateCStreamSize_usingCParams(ZSTD_compressionParameters cParams); |
|
532 ZSTDLIB_API size_t ZSTD_estimateCStreamSize_usingCCtxParams(const ZSTD_CCtx_params* params); |
|
533 ZSTDLIB_API size_t ZSTD_estimateDStreamSize(size_t windowSize); |
|
534 ZSTDLIB_API size_t ZSTD_estimateDStreamSize_fromFrame(const void* src, size_t srcSize); |
|
535 |
|
536 /*! ZSTD_estimate?DictSize() : |
|
537 * ZSTD_estimateCDictSize() will bet that src size is relatively "small", and content is copied, like ZSTD_createCDict(). |
|
538 * ZSTD_estimateCDictSize_advanced() makes it possible to control compression parameters precisely, like ZSTD_createCDict_advanced(). |
|
539 * Note : dictionaries created by reference (`ZSTD_dlm_byRef`) are logically smaller. |
|
540 */ |
|
541 ZSTDLIB_API size_t ZSTD_estimateCDictSize(size_t dictSize, int compressionLevel); |
|
542 ZSTDLIB_API size_t ZSTD_estimateCDictSize_advanced(size_t dictSize, ZSTD_compressionParameters cParams, ZSTD_dictLoadMethod_e dictLoadMethod); |
|
543 ZSTDLIB_API size_t ZSTD_estimateDDictSize(size_t dictSize, ZSTD_dictLoadMethod_e dictLoadMethod); |
|
544 |
|
545 /*! ZSTD_initStatic*() : |
|
546 * Initialize an object using a pre-allocated fixed-size buffer. |
|
547 * workspace: The memory area to emplace the object into. |
|
548 * Provided pointer *must be 8-bytes aligned*. |
|
549 * Buffer must outlive object. |
|
550 * workspaceSize: Use ZSTD_estimate*Size() to determine |
|
551 * how large workspace must be to support target scenario. |
|
552 * @return : pointer to object (same address as workspace, just different type), |
|
553 * or NULL if error (size too small, incorrect alignment, etc.) |
|
554 * Note : zstd will never resize nor malloc() when using a static buffer. |
|
555 * If the object requires more memory than available, |
|
556 * zstd will just error out (typically ZSTD_error_memory_allocation). |
|
557 * Note 2 : there is no corresponding "free" function. |
|
558 * Since workspace is allocated externally, it must be freed externally too. |
|
559 * Note 3 : cParams : use ZSTD_getCParams() to convert a compression level |
|
560 * into its associated cParams. |
|
561 * Limitation 1 : currently not compatible with internal dictionary creation, triggered by |
|
562 * ZSTD_CCtx_loadDictionary(), ZSTD_initCStream_usingDict() or ZSTD_initDStream_usingDict(). |
|
563 * Limitation 2 : static cctx currently not compatible with multi-threading. |
|
564 * Limitation 3 : static dctx is incompatible with legacy support. |
|
565 */ |
|
566 ZSTDLIB_API ZSTD_CCtx* ZSTD_initStaticCCtx(void* workspace, size_t workspaceSize); |
|
567 ZSTDLIB_API ZSTD_CStream* ZSTD_initStaticCStream(void* workspace, size_t workspaceSize); /**< same as ZSTD_initStaticCCtx() */ |
|
568 |
|
569 ZSTDLIB_API ZSTD_DCtx* ZSTD_initStaticDCtx(void* workspace, size_t workspaceSize); |
|
570 ZSTDLIB_API ZSTD_DStream* ZSTD_initStaticDStream(void* workspace, size_t workspaceSize); /**< same as ZSTD_initStaticDCtx() */ |
|
571 |
|
572 ZSTDLIB_API const ZSTD_CDict* ZSTD_initStaticCDict( |
|
573 void* workspace, size_t workspaceSize, |
|
574 const void* dict, size_t dictSize, |
|
575 ZSTD_dictLoadMethod_e dictLoadMethod, |
|
576 ZSTD_dictContentType_e dictContentType, |
|
577 ZSTD_compressionParameters cParams); |
|
578 |
|
579 ZSTDLIB_API const ZSTD_DDict* ZSTD_initStaticDDict( |
|
580 void* workspace, size_t workspaceSize, |
|
581 const void* dict, size_t dictSize, |
|
582 ZSTD_dictLoadMethod_e dictLoadMethod, |
|
583 ZSTD_dictContentType_e dictContentType); |
|
584 |
|
585 /*! Custom memory allocation : |
|
586 * These prototypes make it possible to pass your own allocation/free functions. |
|
587 * ZSTD_customMem is provided at creation time, using ZSTD_create*_advanced() variants listed below. |
|
588 * All allocation/free operations will be completed using these custom variants instead of regular <stdlib.h> ones. |
|
589 */ |
383 typedef void* (*ZSTD_allocFunction) (void* opaque, size_t size); |
590 typedef void* (*ZSTD_allocFunction) (void* opaque, size_t size); |
384 typedef void (*ZSTD_freeFunction) (void* opaque, void* address); |
591 typedef void (*ZSTD_freeFunction) (void* opaque, void* address); |
385 typedef struct { ZSTD_allocFunction customAlloc; ZSTD_freeFunction customFree; void* opaque; } ZSTD_customMem; |
592 typedef struct { ZSTD_allocFunction customAlloc; ZSTD_freeFunction customFree; void* opaque; } ZSTD_customMem; |
|
593 static ZSTD_customMem const ZSTD_defaultCMem = { NULL, NULL, NULL }; /**< this constant defers to stdlib's functions */ |
|
594 |
|
595 ZSTDLIB_API ZSTD_CCtx* ZSTD_createCCtx_advanced(ZSTD_customMem customMem); |
|
596 ZSTDLIB_API ZSTD_CStream* ZSTD_createCStream_advanced(ZSTD_customMem customMem); |
|
597 ZSTDLIB_API ZSTD_DCtx* ZSTD_createDCtx_advanced(ZSTD_customMem customMem); |
|
598 ZSTDLIB_API ZSTD_DStream* ZSTD_createDStream_advanced(ZSTD_customMem customMem); |
|
599 |
|
600 ZSTDLIB_API ZSTD_CDict* ZSTD_createCDict_advanced(const void* dict, size_t dictSize, |
|
601 ZSTD_dictLoadMethod_e dictLoadMethod, |
|
602 ZSTD_dictContentType_e dictContentType, |
|
603 ZSTD_compressionParameters cParams, |
|
604 ZSTD_customMem customMem); |
|
605 |
|
606 ZSTDLIB_API ZSTD_DDict* ZSTD_createDDict_advanced(const void* dict, size_t dictSize, |
|
607 ZSTD_dictLoadMethod_e dictLoadMethod, |
|
608 ZSTD_dictContentType_e dictContentType, |
|
609 ZSTD_customMem customMem); |
|
610 |
386 |
611 |
387 |
612 |
388 /*************************************** |
613 /*************************************** |
389 * Advanced compression functions |
614 * Advanced compression functions |
390 ***************************************/ |
615 ***************************************/ |
391 /*! ZSTD_estimateCCtxSize() : |
|
392 * Gives the amount of memory allocated for a ZSTD_CCtx given a set of compression parameters. |
|
393 * `frameContentSize` is an optional parameter, provide `0` if unknown */ |
|
394 ZSTDLIB_API size_t ZSTD_estimateCCtxSize(ZSTD_compressionParameters cParams); |
|
395 |
|
396 /*! ZSTD_createCCtx_advanced() : |
|
397 * Create a ZSTD compression context using external alloc and free functions */ |
|
398 ZSTDLIB_API ZSTD_CCtx* ZSTD_createCCtx_advanced(ZSTD_customMem customMem); |
|
399 |
|
400 /*! ZSTD_sizeofCCtx() : |
|
401 * Gives the amount of memory used by a given ZSTD_CCtx */ |
|
402 ZSTDLIB_API size_t ZSTD_sizeof_CCtx(const ZSTD_CCtx* cctx); |
|
403 |
|
404 typedef enum { |
|
405 ZSTD_p_forceWindow /* Force back-references to remain < windowSize, even when referencing Dictionary content (default:0)*/ |
|
406 } ZSTD_CCtxParameter; |
|
407 /*! ZSTD_setCCtxParameter() : |
|
408 * Set advanced parameters, selected through enum ZSTD_CCtxParameter |
|
409 * @result : 0, or an error code (which can be tested with ZSTD_isError()) */ |
|
410 ZSTDLIB_API size_t ZSTD_setCCtxParameter(ZSTD_CCtx* cctx, ZSTD_CCtxParameter param, unsigned value); |
|
411 |
616 |
412 /*! ZSTD_createCDict_byReference() : |
617 /*! ZSTD_createCDict_byReference() : |
413 * Create a digested dictionary for compression |
618 * Create a digested dictionary for compression |
414 * Dictionary content is simply referenced, and therefore stays in dictBuffer. |
619 * Dictionary content is simply referenced, and therefore stays in dictBuffer. |
415 * It is important that dictBuffer outlives CDict, it must remain read accessible throughout the lifetime of CDict */ |
620 * It is important that dictBuffer outlives CDict, it must remain read accessible throughout the lifetime of CDict */ |
416 ZSTDLIB_API ZSTD_CDict* ZSTD_createCDict_byReference(const void* dictBuffer, size_t dictSize, int compressionLevel); |
621 ZSTDLIB_API ZSTD_CDict* ZSTD_createCDict_byReference(const void* dictBuffer, size_t dictSize, int compressionLevel); |
417 |
622 |
418 /*! ZSTD_createCDict_advanced() : |
|
419 * Create a ZSTD_CDict using external alloc and free, and customized compression parameters */ |
|
420 ZSTDLIB_API ZSTD_CDict* ZSTD_createCDict_advanced(const void* dict, size_t dictSize, unsigned byReference, |
|
421 ZSTD_parameters params, ZSTD_customMem customMem); |
|
422 |
|
423 /*! ZSTD_sizeof_CDict() : |
|
424 * Gives the amount of memory used by a given ZSTD_sizeof_CDict */ |
|
425 ZSTDLIB_API size_t ZSTD_sizeof_CDict(const ZSTD_CDict* cdict); |
|
426 |
|
427 /*! ZSTD_getCParams() : |
623 /*! ZSTD_getCParams() : |
428 * @return ZSTD_compressionParameters structure for a selected compression level and estimated srcSize. |
624 * @return ZSTD_compressionParameters structure for a selected compression level and estimated srcSize. |
429 * `estimatedSrcSize` value is optional, select 0 if not known */ |
625 * `estimatedSrcSize` value is optional, select 0 if not known */ |
430 ZSTDLIB_API ZSTD_compressionParameters ZSTD_getCParams(int compressionLevel, unsigned long long estimatedSrcSize, size_t dictSize); |
626 ZSTDLIB_API ZSTD_compressionParameters ZSTD_getCParams(int compressionLevel, unsigned long long estimatedSrcSize, size_t dictSize); |
431 |
627 |
432 /*! ZSTD_getParams() : |
628 /*! ZSTD_getParams() : |
433 * same as ZSTD_getCParams(), but @return a full `ZSTD_parameters` object instead of sub-component `ZSTD_compressionParameters`. |
629 * same as ZSTD_getCParams(), but @return a full `ZSTD_parameters` object instead of sub-component `ZSTD_compressionParameters`. |
434 * All fields of `ZSTD_frameParameters` are set to default (0) */ |
630 * All fields of `ZSTD_frameParameters` are set to default : contentSize=1, checksum=0, noDictID=0 */ |
435 ZSTDLIB_API ZSTD_parameters ZSTD_getParams(int compressionLevel, unsigned long long estimatedSrcSize, size_t dictSize); |
631 ZSTDLIB_API ZSTD_parameters ZSTD_getParams(int compressionLevel, unsigned long long estimatedSrcSize, size_t dictSize); |
436 |
632 |
437 /*! ZSTD_checkCParams() : |
633 /*! ZSTD_checkCParams() : |
438 * Ensure param values remain within authorized range */ |
634 * Ensure param values remain within authorized range */ |
439 ZSTDLIB_API size_t ZSTD_checkCParams(ZSTD_compressionParameters params); |
635 ZSTDLIB_API size_t ZSTD_checkCParams(ZSTD_compressionParameters params); |
440 |
636 |
441 /*! ZSTD_adjustCParams() : |
637 /*! ZSTD_adjustCParams() : |
442 * optimize params for a given `srcSize` and `dictSize`. |
638 * optimize params for a given `srcSize` and `dictSize`. |
443 * both values are optional, select `0` if unknown. */ |
639 * both values are optional, select `0` if unknown. */ |
444 ZSTDLIB_API ZSTD_compressionParameters ZSTD_adjustCParams(ZSTD_compressionParameters cPar, unsigned long long srcSize, size_t dictSize); |
640 ZSTDLIB_API ZSTD_compressionParameters ZSTD_adjustCParams(ZSTD_compressionParameters cPar, unsigned long long srcSize, size_t dictSize); |
445 |
641 |
446 /*! ZSTD_compress_advanced() : |
642 /*! ZSTD_compress_advanced() : |
447 * Same as ZSTD_compress_usingDict(), with fine-tune control of each compression parameter */ |
643 * Same as ZSTD_compress_usingDict(), with fine-tune control over each compression parameter */ |
448 ZSTDLIB_API size_t ZSTD_compress_advanced (ZSTD_CCtx* ctx, |
644 ZSTDLIB_API size_t ZSTD_compress_advanced (ZSTD_CCtx* cctx, |
449 void* dst, size_t dstCapacity, |
645 void* dst, size_t dstCapacity, |
450 const void* src, size_t srcSize, |
646 const void* src, size_t srcSize, |
451 const void* dict,size_t dictSize, |
647 const void* dict,size_t dictSize, |
452 ZSTD_parameters params); |
648 ZSTD_parameters params); |
|
649 |
|
650 /*! ZSTD_compress_usingCDict_advanced() : |
|
651 * Same as ZSTD_compress_usingCDict(), with fine-tune control over frame parameters */ |
|
652 ZSTDLIB_API size_t ZSTD_compress_usingCDict_advanced(ZSTD_CCtx* cctx, |
|
653 void* dst, size_t dstCapacity, |
|
654 const void* src, size_t srcSize, |
|
655 const ZSTD_CDict* cdict, ZSTD_frameParameters fParams); |
453 |
656 |
454 |
657 |
455 /*--- Advanced decompression functions ---*/ |
658 /*--- Advanced decompression functions ---*/ |
456 |
659 |
457 /*! ZSTD_isFrame() : |
660 /*! ZSTD_isFrame() : |
556 or ZSTD_compressBegin_advanced(), for finer parameter control. |
765 or ZSTD_compressBegin_advanced(), for finer parameter control. |
557 It's also possible to duplicate a reference context which has already been initialized, using ZSTD_copyCCtx() |
766 It's also possible to duplicate a reference context which has already been initialized, using ZSTD_copyCCtx() |
558 |
767 |
559 Then, consume your input using ZSTD_compressContinue(). |
768 Then, consume your input using ZSTD_compressContinue(). |
560 There are some important considerations to keep in mind when using this advanced function : |
769 There are some important considerations to keep in mind when using this advanced function : |
561 - ZSTD_compressContinue() has no internal buffer. It uses externally provided buffer only. |
770 - ZSTD_compressContinue() has no internal buffer. It uses externally provided buffers only. |
562 - Interface is synchronous : input is consumed entirely and produce 1+ (or more) compressed blocks. |
771 - Interface is synchronous : input is consumed entirely and produces 1+ compressed blocks. |
563 - Caller must ensure there is enough space in `dst` to store compressed data under worst case scenario. |
772 - Caller must ensure there is enough space in `dst` to store compressed data under worst case scenario. |
564 Worst case evaluation is provided by ZSTD_compressBound(). |
773 Worst case evaluation is provided by ZSTD_compressBound(). |
565 ZSTD_compressContinue() doesn't guarantee recover after a failed compression. |
774 ZSTD_compressContinue() doesn't guarantee recover after a failed compression. |
566 - ZSTD_compressContinue() presumes prior input ***is still accessible and unmodified*** (up to maximum distance size, see WindowLog). |
775 - ZSTD_compressContinue() presumes prior input ***is still accessible and unmodified*** (up to maximum distance size, see WindowLog). |
567 It remembers all previous contiguous blocks, plus one separated memory segment (which can itself consists of multiple contiguous blocks) |
776 It remembers all previous contiguous blocks, plus one separated memory segment (which can itself consists of multiple contiguous blocks) |
568 - ZSTD_compressContinue() detects that prior input has been overwritten when `src` buffer overlaps. |
777 - ZSTD_compressContinue() detects that prior input has been overwritten when `src` buffer overlaps. |
569 In which case, it will "discard" the relevant memory section from its history. |
778 In which case, it will "discard" the relevant memory section from its history. |
570 |
779 |
571 Finish a frame with ZSTD_compressEnd(), which will write the last block(s) and optional checksum. |
780 Finish a frame with ZSTD_compressEnd(), which will write the last block(s) and optional checksum. |
572 It's possible to use srcSize==0, in which case, it will write a final empty block to end the frame. |
781 It's possible to use srcSize==0, in which case, it will write a final empty block to end the frame. |
573 Without last block mark, frames will be considered unfinished (corrupted) by decoders. |
782 Without last block mark, frames are considered unfinished (hence corrupted) by compliant decoders. |
574 |
783 |
575 `ZSTD_CCtx` object can be re-used (ZSTD_compressBegin()) to compress some new frame. |
784 `ZSTD_CCtx` object can be re-used (ZSTD_compressBegin()) to compress again. |
576 */ |
785 */ |
577 |
786 |
578 /*===== Buffer-less streaming compression functions =====*/ |
787 /*===== Buffer-less streaming compression functions =====*/ |
579 ZSTDLIB_API size_t ZSTD_compressBegin(ZSTD_CCtx* cctx, int compressionLevel); |
788 ZSTDLIB_API size_t ZSTD_compressBegin(ZSTD_CCtx* cctx, int compressionLevel); |
580 ZSTDLIB_API size_t ZSTD_compressBegin_usingDict(ZSTD_CCtx* cctx, const void* dict, size_t dictSize, int compressionLevel); |
789 ZSTDLIB_API size_t ZSTD_compressBegin_usingDict(ZSTD_CCtx* cctx, const void* dict, size_t dictSize, int compressionLevel); |
581 ZSTDLIB_API size_t ZSTD_compressBegin_advanced(ZSTD_CCtx* cctx, const void* dict, size_t dictSize, ZSTD_parameters params, unsigned long long pledgedSrcSize); |
790 ZSTDLIB_API 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 */ |
582 ZSTDLIB_API size_t ZSTD_copyCCtx(ZSTD_CCtx* cctx, const ZSTD_CCtx* preparedCCtx, unsigned long long pledgedSrcSize); |
791 ZSTDLIB_API size_t ZSTD_compressBegin_usingCDict(ZSTD_CCtx* cctx, const ZSTD_CDict* cdict); /**< note: fails if cdict==NULL */ |
583 ZSTDLIB_API size_t ZSTD_compressBegin_usingCDict(ZSTD_CCtx* cctx, const ZSTD_CDict* cdict, unsigned long long pledgedSrcSize); |
792 ZSTDLIB_API 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 */ |
|
793 ZSTDLIB_API 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 */ |
|
794 |
584 ZSTDLIB_API size_t ZSTD_compressContinue(ZSTD_CCtx* cctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize); |
795 ZSTDLIB_API size_t ZSTD_compressContinue(ZSTD_CCtx* cctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize); |
585 ZSTDLIB_API size_t ZSTD_compressEnd(ZSTD_CCtx* cctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize); |
796 ZSTDLIB_API size_t ZSTD_compressEnd(ZSTD_CCtx* cctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize); |
586 |
|
587 |
797 |
588 |
798 |
589 /*- |
799 /*- |
590 Buffer-less streaming decompression (synchronous mode) |
800 Buffer-less streaming decompression (synchronous mode) |
591 |
801 |
592 A ZSTD_DCtx object is required to track streaming operations. |
802 A ZSTD_DCtx object is required to track streaming operations. |
593 Use ZSTD_createDCtx() / ZSTD_freeDCtx() to manage it. |
803 Use ZSTD_createDCtx() / ZSTD_freeDCtx() to manage it. |
594 A ZSTD_DCtx object can be re-used multiple times. |
804 A ZSTD_DCtx object can be re-used multiple times. |
595 |
805 |
596 First typical operation is to retrieve frame parameters, using ZSTD_getFrameParams(). |
806 First typical operation is to retrieve frame parameters, using ZSTD_getFrameHeader(). |
597 It fills a ZSTD_frameParams structure which provide important information to correctly decode the frame, |
807 Frame header is extracted from the beginning of compressed frame, so providing only the frame's beginning is enough. |
598 such as the minimum rolling buffer size to allocate to decompress data (`windowSize`), |
808 Data fragment must be large enough to ensure successful decoding. |
599 and the dictionary ID used. |
809 `ZSTD_frameHeaderSize_max` bytes is guaranteed to always be large enough. |
600 (Note : content size is optional, it may not be present. 0 means : content size unknown). |
810 @result : 0 : successful decoding, the `ZSTD_frameHeader` structure is correctly filled. |
601 Note that these values could be wrong, either because of data malformation, or because an attacker is spoofing deliberate false information. |
|
602 As a consequence, check that values remain within valid application range, especially `windowSize`, before allocation. |
|
603 Each application can set its own limit, depending on local restrictions. For extended interoperability, it is recommended to support at least 8 MB. |
|
604 Frame parameters are extracted from the beginning of the compressed frame. |
|
605 Data fragment must be large enough to ensure successful decoding, typically `ZSTD_frameHeaderSize_max` bytes. |
|
606 @result : 0 : successful decoding, the `ZSTD_frameParams` structure is correctly filled. |
|
607 >0 : `srcSize` is too small, please provide at least @result bytes on next attempt. |
811 >0 : `srcSize` is too small, please provide at least @result bytes on next attempt. |
608 errorCode, which can be tested using ZSTD_isError(). |
812 errorCode, which can be tested using ZSTD_isError(). |
609 |
813 |
610 Start decompression, with ZSTD_decompressBegin() or ZSTD_decompressBegin_usingDict(). |
814 It fills a ZSTD_frameHeader structure with important information to correctly decode the frame, |
611 Alternatively, you can copy a prepared context, using ZSTD_copyDCtx(). |
815 such as the dictionary ID, content size, or maximum back-reference distance (`windowSize`). |
|
816 Note that these values could be wrong, either because of data corruption, or because a 3rd party deliberately spoofs false information. |
|
817 As a consequence, check that values remain within valid application range. |
|
818 For example, do not allocate memory blindly, check that `windowSize` is within expectation. |
|
819 Each application can set its own limits, depending on local restrictions. |
|
820 For extended interoperability, it is recommended to support `windowSize` of at least 8 MB. |
|
821 |
|
822 ZSTD_decompressContinue() needs previous data blocks during decompression, up to `windowSize` bytes. |
|
823 ZSTD_decompressContinue() is very sensitive to contiguity, |
|
824 if 2 blocks don't follow each other, make sure that either the compressor breaks contiguity at the same place, |
|
825 or that previous contiguous segment is large enough to properly handle maximum back-reference distance. |
|
826 There are multiple ways to guarantee this condition. |
|
827 |
|
828 The most memory efficient way is to use a round buffer of sufficient size. |
|
829 Sufficient size is determined by invoking ZSTD_decodingBufferSize_min(), |
|
830 which can @return an error code if required value is too large for current system (in 32-bits mode). |
|
831 In a round buffer methodology, ZSTD_decompressContinue() decompresses each block next to previous one, |
|
832 up to the moment there is not enough room left in the buffer to guarantee decoding another full block, |
|
833 which maximum size is provided in `ZSTD_frameHeader` structure, field `blockSizeMax`. |
|
834 At which point, decoding can resume from the beginning of the buffer. |
|
835 Note that already decoded data stored in the buffer should be flushed before being overwritten. |
|
836 |
|
837 There are alternatives possible, for example using two or more buffers of size `windowSize` each, though they consume more memory. |
|
838 |
|
839 Finally, if you control the compression process, you can also ignore all buffer size rules, |
|
840 as long as the encoder and decoder progress in "lock-step", |
|
841 aka use exactly the same buffer sizes, break contiguity at the same place, etc. |
|
842 |
|
843 Once buffers are setup, start decompression, with ZSTD_decompressBegin(). |
|
844 If decompression requires a dictionary, use ZSTD_decompressBegin_usingDict() or ZSTD_decompressBegin_usingDDict(). |
612 |
845 |
613 Then use ZSTD_nextSrcSizeToDecompress() and ZSTD_decompressContinue() alternatively. |
846 Then use ZSTD_nextSrcSizeToDecompress() and ZSTD_decompressContinue() alternatively. |
614 ZSTD_nextSrcSizeToDecompress() tells how many bytes to provide as 'srcSize' to ZSTD_decompressContinue(). |
847 ZSTD_nextSrcSizeToDecompress() tells how many bytes to provide as 'srcSize' to ZSTD_decompressContinue(). |
615 ZSTD_decompressContinue() requires this _exact_ amount of bytes, or it will fail. |
848 ZSTD_decompressContinue() requires this _exact_ amount of bytes, or it will fail. |
616 |
849 |
617 @result of ZSTD_decompressContinue() is the number of bytes regenerated within 'dst' (necessarily <= dstCapacity). |
850 @result of ZSTD_decompressContinue() is the number of bytes regenerated within 'dst' (necessarily <= dstCapacity). |
618 It can be zero, which is not an error; it just means ZSTD_decompressContinue() has decoded some metadata item. |
851 It can be zero : it just means ZSTD_decompressContinue() has decoded some metadata item. |
619 It can also be an error code, which can be tested with ZSTD_isError(). |
852 It can also be an error code, which can be tested with ZSTD_isError(). |
620 |
|
621 ZSTD_decompressContinue() needs previous data blocks during decompression, up to `windowSize`. |
|
622 They should preferably be located contiguously, prior to current block. |
|
623 Alternatively, a round buffer of sufficient size is also possible. Sufficient size is determined by frame parameters. |
|
624 ZSTD_decompressContinue() is very sensitive to contiguity, |
|
625 if 2 blocks don't follow each other, make sure that either the compressor breaks contiguity at the same place, |
|
626 or that previous contiguous segment is large enough to properly handle maximum back-reference. |
|
627 |
853 |
628 A frame is fully decoded when ZSTD_nextSrcSizeToDecompress() returns zero. |
854 A frame is fully decoded when ZSTD_nextSrcSizeToDecompress() returns zero. |
629 Context can then be reset to start a new decompression. |
855 Context can then be reset to start a new decompression. |
630 |
856 |
631 Note : it's possible to know if next input to present is a header or a block, using ZSTD_nextInputType(). |
857 Note : it's possible to know if next input to present is a header or a block, using ZSTD_nextInputType(). |
632 This information is not required to properly decode a frame. |
858 This information is not required to properly decode a frame. |
633 |
859 |
634 == Special case : skippable frames == |
860 == Special case : skippable frames == |
635 |
861 |
636 Skippable frames allow integration of user-defined data into a flow of concatenated frames. |
862 Skippable frames allow integration of user-defined data into a flow of concatenated frames. |
637 Skippable frames will be ignored (skipped) by a decompressor. The format of skippable frames is as follows : |
863 Skippable frames will be ignored (skipped) by decompressor. |
|
864 The format of skippable frames is as follows : |
638 a) Skippable frame ID - 4 Bytes, Little endian format, any value from 0x184D2A50 to 0x184D2A5F |
865 a) Skippable frame ID - 4 Bytes, Little endian format, any value from 0x184D2A50 to 0x184D2A5F |
639 b) Frame Size - 4 Bytes, Little endian format, unsigned 32-bits |
866 b) Frame Size - 4 Bytes, Little endian format, unsigned 32-bits |
640 c) Frame Content - any content (User Data) of length equal to Frame Size |
867 c) Frame Content - any content (User Data) of length equal to Frame Size |
641 For skippable frames ZSTD_decompressContinue() always returns 0. |
868 For skippable frames ZSTD_getFrameHeader() returns zfhPtr->frameType==ZSTD_skippableFrame. |
642 For skippable frames ZSTD_getFrameParams() returns fparamsPtr->windowLog==0 what means that a frame is skippable. |
869 For skippable frames ZSTD_decompressContinue() always returns 0 : it only skips the content. |
643 It also returns Frame Size as fparamsPtr->frameContentSize. |
|
644 */ |
870 */ |
645 |
871 |
|
872 /*===== Buffer-less streaming decompression functions =====*/ |
|
873 typedef enum { ZSTD_frame, ZSTD_skippableFrame } ZSTD_frameType_e; |
646 typedef struct { |
874 typedef struct { |
647 unsigned long long frameContentSize; |
875 unsigned long long frameContentSize; /* if == ZSTD_CONTENTSIZE_UNKNOWN, it means this field is not available. 0 means "empty" */ |
648 unsigned windowSize; |
876 unsigned long long windowSize; /* can be very large, up to <= frameContentSize */ |
|
877 unsigned blockSizeMax; |
|
878 ZSTD_frameType_e frameType; /* if == ZSTD_skippableFrame, frameContentSize is the size of skippable content */ |
|
879 unsigned headerSize; |
649 unsigned dictID; |
880 unsigned dictID; |
650 unsigned checksumFlag; |
881 unsigned checksumFlag; |
651 } ZSTD_frameParams; |
882 } ZSTD_frameHeader; |
652 |
883 ZSTDLIB_API size_t ZSTD_getFrameHeader(ZSTD_frameHeader* zfhPtr, const void* src, size_t srcSize); /**< doesn't consume input */ |
653 /*===== Buffer-less streaming decompression functions =====*/ |
884 ZSTDLIB_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 */ |
654 ZSTDLIB_API size_t ZSTD_getFrameParams(ZSTD_frameParams* fparamsPtr, const void* src, size_t srcSize); /**< doesn't consume input, see details below */ |
885 |
655 ZSTDLIB_API size_t ZSTD_decompressBegin(ZSTD_DCtx* dctx); |
886 ZSTDLIB_API size_t ZSTD_decompressBegin(ZSTD_DCtx* dctx); |
656 ZSTDLIB_API size_t ZSTD_decompressBegin_usingDict(ZSTD_DCtx* dctx, const void* dict, size_t dictSize); |
887 ZSTDLIB_API size_t ZSTD_decompressBegin_usingDict(ZSTD_DCtx* dctx, const void* dict, size_t dictSize); |
657 ZSTDLIB_API void ZSTD_copyDCtx(ZSTD_DCtx* dctx, const ZSTD_DCtx* preparedDCtx); |
888 ZSTDLIB_API size_t ZSTD_decompressBegin_usingDDict(ZSTD_DCtx* dctx, const ZSTD_DDict* ddict); |
|
889 |
658 ZSTDLIB_API size_t ZSTD_nextSrcSizeToDecompress(ZSTD_DCtx* dctx); |
890 ZSTDLIB_API size_t ZSTD_nextSrcSizeToDecompress(ZSTD_DCtx* dctx); |
659 ZSTDLIB_API size_t ZSTD_decompressContinue(ZSTD_DCtx* dctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize); |
891 ZSTDLIB_API size_t ZSTD_decompressContinue(ZSTD_DCtx* dctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize); |
|
892 |
|
893 /* misc */ |
|
894 ZSTDLIB_API void ZSTD_copyDCtx(ZSTD_DCtx* dctx, const ZSTD_DCtx* preparedDCtx); |
660 typedef enum { ZSTDnit_frameHeader, ZSTDnit_blockHeader, ZSTDnit_block, ZSTDnit_lastBlock, ZSTDnit_checksum, ZSTDnit_skippableFrame } ZSTD_nextInputType_e; |
895 typedef enum { ZSTDnit_frameHeader, ZSTDnit_blockHeader, ZSTDnit_block, ZSTDnit_lastBlock, ZSTDnit_checksum, ZSTDnit_skippableFrame } ZSTD_nextInputType_e; |
661 ZSTDLIB_API ZSTD_nextInputType_e ZSTD_nextInputType(ZSTD_DCtx* dctx); |
896 ZSTDLIB_API ZSTD_nextInputType_e ZSTD_nextInputType(ZSTD_DCtx* dctx); |
662 |
897 |
663 /** |
898 |
664 Block functions |
899 |
665 |
900 /* ============================================ */ |
|
901 /** New advanced API (experimental) */ |
|
902 /* ============================================ */ |
|
903 |
|
904 /* notes on API design : |
|
905 * In this proposal, parameters are pushed one by one into an existing context, |
|
906 * and then applied on all subsequent compression jobs. |
|
907 * When no parameter is ever provided, CCtx is created with compression level ZSTD_CLEVEL_DEFAULT. |
|
908 * |
|
909 * This API is intended to replace all others advanced / experimental API entry points. |
|
910 * But it stands a reasonable chance to become "stable", after a reasonable testing period. |
|
911 */ |
|
912 |
|
913 /* note on naming convention : |
|
914 * Initially, the API favored names like ZSTD_setCCtxParameter() . |
|
915 * In this proposal, convention is changed towards ZSTD_CCtx_setParameter() . |
|
916 * The main driver is that it identifies more clearly the target object type. |
|
917 * It feels clearer when considering multiple targets : |
|
918 * ZSTD_CDict_setParameter() (rather than ZSTD_setCDictParameter()) |
|
919 * ZSTD_CCtxParams_setParameter() (rather than ZSTD_setCCtxParamsParameter() ) |
|
920 * etc... |
|
921 */ |
|
922 |
|
923 /* note on enum design : |
|
924 * All enum will be pinned to explicit values before reaching "stable API" status */ |
|
925 |
|
926 typedef enum { |
|
927 /* Opened question : should we have a format ZSTD_f_auto ? |
|
928 * Today, it would mean exactly the same as ZSTD_f_zstd1. |
|
929 * But, in the future, should several formats become supported, |
|
930 * on the compression side, it would mean "default format". |
|
931 * On the decompression side, it would mean "automatic format detection", |
|
932 * so that ZSTD_f_zstd1 would mean "accept *only* zstd frames". |
|
933 * Since meaning is a little different, another option could be to define different enums for compression and decompression. |
|
934 * This question could be kept for later, when there are actually multiple formats to support, |
|
935 * but there is also the question of pinning enum values, and pinning value `0` is especially important */ |
|
936 ZSTD_f_zstd1 = 0, /* zstd frame format, specified in zstd_compression_format.md (default) */ |
|
937 ZSTD_f_zstd1_magicless, /* Variant of zstd frame format, without initial 4-bytes magic number. |
|
938 * Useful to save 4 bytes per generated frame. |
|
939 * Decoder cannot recognise automatically this format, requiring instructions. */ |
|
940 } ZSTD_format_e; |
|
941 |
|
942 typedef enum { |
|
943 /* compression format */ |
|
944 ZSTD_p_format = 10, /* See ZSTD_format_e enum definition. |
|
945 * Cast selected format as unsigned for ZSTD_CCtx_setParameter() compatibility. */ |
|
946 |
|
947 /* compression parameters */ |
|
948 ZSTD_p_compressionLevel=100, /* Update all compression parameters according to pre-defined cLevel table |
|
949 * Default level is ZSTD_CLEVEL_DEFAULT==3. |
|
950 * Special: value 0 means "do not change cLevel". |
|
951 * Note 1 : it's possible to pass a negative compression level by casting it to unsigned type. |
|
952 * Note 2 : setting a level sets all default values of other compression parameters. |
|
953 * Note 3 : setting compressionLevel automatically updates ZSTD_p_compressLiterals. */ |
|
954 ZSTD_p_windowLog, /* Maximum allowed back-reference distance, expressed as power of 2. |
|
955 * Must be clamped between ZSTD_WINDOWLOG_MIN and ZSTD_WINDOWLOG_MAX. |
|
956 * Special: value 0 means "use default windowLog". |
|
957 * Note: Using a window size greater than ZSTD_MAXWINDOWSIZE_DEFAULT (default: 2^27) |
|
958 * requires explicitly allowing such window size during decompression stage. */ |
|
959 ZSTD_p_hashLog, /* Size of the probe table, as a power of 2. |
|
960 * Resulting table size is (1 << (hashLog+2)). |
|
961 * Must be clamped between ZSTD_HASHLOG_MIN and ZSTD_HASHLOG_MAX. |
|
962 * Larger tables improve compression ratio of strategies <= dFast, |
|
963 * and improve speed of strategies > dFast. |
|
964 * Special: value 0 means "use default hashLog". */ |
|
965 ZSTD_p_chainLog, /* Size of the full-search table, as a power of 2. |
|
966 * Resulting table size is (1 << (chainLog+2)). |
|
967 * Larger tables result in better and slower compression. |
|
968 * This parameter is useless when using "fast" strategy. |
|
969 * Special: value 0 means "use default chainLog". */ |
|
970 ZSTD_p_searchLog, /* Number of search attempts, as a power of 2. |
|
971 * More attempts result in better and slower compression. |
|
972 * This parameter is useless when using "fast" and "dFast" strategies. |
|
973 * Special: value 0 means "use default searchLog". */ |
|
974 ZSTD_p_minMatch, /* Minimum size of searched matches (note : repCode matches can be smaller). |
|
975 * Larger values make faster compression and decompression, but decrease ratio. |
|
976 * Must be clamped between ZSTD_SEARCHLENGTH_MIN and ZSTD_SEARCHLENGTH_MAX. |
|
977 * Note that currently, for all strategies < btopt, effective minimum is 4. |
|
978 * , for all strategies > fast, effective maximum is 6. |
|
979 * Special: value 0 means "use default minMatchLength". */ |
|
980 ZSTD_p_targetLength, /* Impact of this field depends on strategy. |
|
981 * For strategies btopt & btultra: |
|
982 * Length of Match considered "good enough" to stop search. |
|
983 * Larger values make compression stronger, and slower. |
|
984 * For strategy fast: |
|
985 * Distance between match sampling. |
|
986 * Larger values make compression faster, and weaker. |
|
987 * Special: value 0 means "use default targetLength". */ |
|
988 ZSTD_p_compressionStrategy, /* See ZSTD_strategy enum definition. |
|
989 * Cast selected strategy as unsigned for ZSTD_CCtx_setParameter() compatibility. |
|
990 * The higher the value of selected strategy, the more complex it is, |
|
991 * resulting in stronger and slower compression. |
|
992 * Special: value 0 means "use default strategy". */ |
|
993 |
|
994 ZSTD_p_enableLongDistanceMatching=160, /* Enable long distance matching. |
|
995 * This parameter is designed to improve compression ratio |
|
996 * for large inputs, by finding large matches at long distance. |
|
997 * It increases memory usage and window size. |
|
998 * Note: enabling this parameter increases ZSTD_p_windowLog to 128 MB |
|
999 * except when expressly set to a different value. */ |
|
1000 ZSTD_p_ldmHashLog, /* Size of the table for long distance matching, as a power of 2. |
|
1001 * Larger values increase memory usage and compression ratio, |
|
1002 * but decrease compression speed. |
|
1003 * Must be clamped between ZSTD_HASHLOG_MIN and ZSTD_HASHLOG_MAX |
|
1004 * default: windowlog - 7. |
|
1005 * Special: value 0 means "automatically determine hashlog". */ |
|
1006 ZSTD_p_ldmMinMatch, /* Minimum match size for long distance matcher. |
|
1007 * Larger/too small values usually decrease compression ratio. |
|
1008 * Must be clamped between ZSTD_LDM_MINMATCH_MIN and ZSTD_LDM_MINMATCH_MAX. |
|
1009 * Special: value 0 means "use default value" (default: 64). */ |
|
1010 ZSTD_p_ldmBucketSizeLog, /* Log size of each bucket in the LDM hash table for collision resolution. |
|
1011 * Larger values improve collision resolution but decrease compression speed. |
|
1012 * The maximum value is ZSTD_LDM_BUCKETSIZELOG_MAX . |
|
1013 * Special: value 0 means "use default value" (default: 3). */ |
|
1014 ZSTD_p_ldmHashEveryLog, /* Frequency of inserting/looking up entries in the LDM hash table. |
|
1015 * Must be clamped between 0 and (ZSTD_WINDOWLOG_MAX - ZSTD_HASHLOG_MIN). |
|
1016 * Default is MAX(0, (windowLog - ldmHashLog)), optimizing hash table usage. |
|
1017 * Larger values improve compression speed. |
|
1018 * Deviating far from default value will likely result in a compression ratio decrease. |
|
1019 * Special: value 0 means "automatically determine hashEveryLog". */ |
|
1020 |
|
1021 /* frame parameters */ |
|
1022 ZSTD_p_contentSizeFlag=200, /* Content size will be written into frame header _whenever known_ (default:1) |
|
1023 * Content size must be known at the beginning of compression, |
|
1024 * it is provided using ZSTD_CCtx_setPledgedSrcSize() */ |
|
1025 ZSTD_p_checksumFlag, /* A 32-bits checksum of content is written at end of frame (default:0) */ |
|
1026 ZSTD_p_dictIDFlag, /* When applicable, dictionary's ID is written into frame header (default:1) */ |
|
1027 |
|
1028 /* multi-threading parameters */ |
|
1029 /* These parameters are only useful if multi-threading is enabled (ZSTD_MULTITHREAD). |
|
1030 * They return an error otherwise. */ |
|
1031 ZSTD_p_nbWorkers=400, /* Select how many threads will be spawned to compress in parallel. |
|
1032 * When nbWorkers >= 1, triggers asynchronous mode : |
|
1033 * ZSTD_compress_generic() consumes some input, flush some output if possible, and immediately gives back control to caller, |
|
1034 * while compression work is performed in parallel, within worker threads. |
|
1035 * (note : a strong exception to this rule is when first invocation sets ZSTD_e_end : it becomes a blocking call). |
|
1036 * More workers improve speed, but also increase memory usage. |
|
1037 * Default value is `0`, aka "single-threaded mode" : no worker is spawned, compression is performed inside Caller's thread, all invocations are blocking */ |
|
1038 ZSTD_p_jobSize, /* Size of a compression job. This value is enforced only in non-blocking mode. |
|
1039 * Each compression job is completed in parallel, so this value indirectly controls the nb of active threads. |
|
1040 * 0 means default, which is dynamically determined based on compression parameters. |
|
1041 * Job size must be a minimum of overlapSize, or 1 MB, whichever is largest. |
|
1042 * The minimum size is automatically and transparently enforced */ |
|
1043 ZSTD_p_overlapSizeLog, /* Size of previous input reloaded at the beginning of each job. |
|
1044 * 0 => no overlap, 6(default) => use 1/8th of windowSize, >=9 => use full windowSize */ |
|
1045 |
|
1046 /* =================================================================== */ |
|
1047 /* experimental parameters - no stability guaranteed */ |
|
1048 /* =================================================================== */ |
|
1049 |
|
1050 ZSTD_p_compressLiterals=1000, /* control huffman compression of literals (enabled) by default. |
|
1051 * disabling it improves speed and decreases compression ratio by a large amount. |
|
1052 * note : this setting is automatically updated when changing compression level. |
|
1053 * positive compression levels set ZSTD_p_compressLiterals to 1. |
|
1054 * negative compression levels set ZSTD_p_compressLiterals to 0. */ |
|
1055 |
|
1056 ZSTD_p_forceMaxWindow=1100, /* Force back-reference distances to remain < windowSize, |
|
1057 * even when referencing into Dictionary content (default:0) */ |
|
1058 |
|
1059 } ZSTD_cParameter; |
|
1060 |
|
1061 |
|
1062 /*! ZSTD_CCtx_setParameter() : |
|
1063 * Set one compression parameter, selected by enum ZSTD_cParameter. |
|
1064 * Setting a parameter is generally only possible during frame initialization (before starting compression), |
|
1065 * except for a few exceptions which can be updated during compression: compressionLevel, hashLog, chainLog, searchLog, minMatch, targetLength and strategy. |
|
1066 * Note : when `value` is an enum, cast it to unsigned for proper type checking. |
|
1067 * @result : informational value (typically, value being set clamped correctly), |
|
1068 * or an error code (which can be tested with ZSTD_isError()). */ |
|
1069 ZSTDLIB_API size_t ZSTD_CCtx_setParameter(ZSTD_CCtx* cctx, ZSTD_cParameter param, unsigned value); |
|
1070 |
|
1071 /*! ZSTD_CCtx_setPledgedSrcSize() : |
|
1072 * Total input data size to be compressed as a single frame. |
|
1073 * This value will be controlled at the end, and result in error if not respected. |
|
1074 * @result : 0, or an error code (which can be tested with ZSTD_isError()). |
|
1075 * Note 1 : 0 means zero, empty. |
|
1076 * In order to mean "unknown content size", pass constant ZSTD_CONTENTSIZE_UNKNOWN. |
|
1077 * ZSTD_CONTENTSIZE_UNKNOWN is default value for any new compression job. |
|
1078 * Note 2 : If all data is provided and consumed in a single round, |
|
1079 * this value is overriden by srcSize instead. */ |
|
1080 ZSTDLIB_API size_t ZSTD_CCtx_setPledgedSrcSize(ZSTD_CCtx* cctx, unsigned long long pledgedSrcSize); |
|
1081 |
|
1082 /*! ZSTD_CCtx_loadDictionary() : |
|
1083 * Create an internal CDict from `dict` buffer. |
|
1084 * Decompression will have to use same dictionary. |
|
1085 * @result : 0, or an error code (which can be tested with ZSTD_isError()). |
|
1086 * Special: Adding a NULL (or 0-size) dictionary invalidates previous dictionary, |
|
1087 * meaning "return to no-dictionary mode". |
|
1088 * Note 1 : Dictionary will be used for all future compression jobs. |
|
1089 * To return to "no-dictionary" situation, load a NULL dictionary |
|
1090 * Note 2 : Loading a dictionary involves building tables, which are dependent on compression parameters. |
|
1091 * For this reason, compression parameters cannot be changed anymore after loading a dictionary. |
|
1092 * It's also a CPU consuming operation, with non-negligible impact on latency. |
|
1093 * Note 3 :`dict` content will be copied internally. |
|
1094 * Use ZSTD_CCtx_loadDictionary_byReference() to reference dictionary content instead. |
|
1095 * In such a case, dictionary buffer must outlive its users. |
|
1096 * Note 4 : Use ZSTD_CCtx_loadDictionary_advanced() |
|
1097 * to precisely select how dictionary content must be interpreted. */ |
|
1098 ZSTDLIB_API size_t ZSTD_CCtx_loadDictionary(ZSTD_CCtx* cctx, const void* dict, size_t dictSize); |
|
1099 ZSTDLIB_API size_t ZSTD_CCtx_loadDictionary_byReference(ZSTD_CCtx* cctx, const void* dict, size_t dictSize); |
|
1100 ZSTDLIB_API size_t ZSTD_CCtx_loadDictionary_advanced(ZSTD_CCtx* cctx, const void* dict, size_t dictSize, ZSTD_dictLoadMethod_e dictLoadMethod, ZSTD_dictContentType_e dictContentType); |
|
1101 |
|
1102 |
|
1103 /*! ZSTD_CCtx_refCDict() : |
|
1104 * Reference a prepared dictionary, to be used for all next compression jobs. |
|
1105 * Note that compression parameters are enforced from within CDict, |
|
1106 * and supercede any compression parameter previously set within CCtx. |
|
1107 * The dictionary will remain valid for future compression jobs using same CCtx. |
|
1108 * @result : 0, or an error code (which can be tested with ZSTD_isError()). |
|
1109 * Special : adding a NULL CDict means "return to no-dictionary mode". |
|
1110 * Note 1 : Currently, only one dictionary can be managed. |
|
1111 * Adding a new dictionary effectively "discards" any previous one. |
|
1112 * Note 2 : CDict is just referenced, its lifetime must outlive CCtx. */ |
|
1113 ZSTDLIB_API size_t ZSTD_CCtx_refCDict(ZSTD_CCtx* cctx, const ZSTD_CDict* cdict); |
|
1114 |
|
1115 /*! ZSTD_CCtx_refPrefix() : |
|
1116 * Reference a prefix (single-usage dictionary) for next compression job. |
|
1117 * Decompression need same prefix to properly regenerate data. |
|
1118 * Prefix is **only used once**. Tables are discarded at end of compression job. |
|
1119 * Subsequent compression jobs will be done without prefix (if none is explicitly referenced). |
|
1120 * If there is a need to use same prefix multiple times, consider embedding it into a ZSTD_CDict instead. |
|
1121 * @result : 0, or an error code (which can be tested with ZSTD_isError()). |
|
1122 * Special: Adding any prefix (including NULL) invalidates any previous prefix or dictionary |
|
1123 * Note 1 : Prefix buffer is referenced. It must outlive compression job. |
|
1124 * Note 2 : Referencing a prefix involves building tables, which are dependent on compression parameters. |
|
1125 * It's a CPU consuming operation, with non-negligible impact on latency. |
|
1126 * Note 3 : By default, the prefix is treated as raw content (ZSTD_dm_rawContent). |
|
1127 * Use ZSTD_CCtx_refPrefix_advanced() to alter dictMode. */ |
|
1128 ZSTDLIB_API size_t ZSTD_CCtx_refPrefix(ZSTD_CCtx* cctx, const void* prefix, size_t prefixSize); |
|
1129 ZSTDLIB_API size_t ZSTD_CCtx_refPrefix_advanced(ZSTD_CCtx* cctx, const void* prefix, size_t prefixSize, ZSTD_dictContentType_e dictContentType); |
|
1130 |
|
1131 /*! ZSTD_CCtx_reset() : |
|
1132 * Return a CCtx to clean state. |
|
1133 * Useful after an error, or to interrupt an ongoing compression job and start a new one. |
|
1134 * Any internal data not yet flushed is cancelled. |
|
1135 * Dictionary (if any) is dropped. |
|
1136 * All parameters are back to default values. |
|
1137 * It's possible to modify compression parameters after a reset. |
|
1138 */ |
|
1139 ZSTDLIB_API void ZSTD_CCtx_reset(ZSTD_CCtx* cctx); |
|
1140 |
|
1141 |
|
1142 |
|
1143 typedef enum { |
|
1144 ZSTD_e_continue=0, /* collect more data, encoder decides when to output compressed result, for optimal conditions */ |
|
1145 ZSTD_e_flush, /* flush any data provided so far - frame will continue, future data can still reference previous data for better compression */ |
|
1146 ZSTD_e_end /* flush any remaining data and close current frame. Any additional data starts a new frame. */ |
|
1147 } ZSTD_EndDirective; |
|
1148 |
|
1149 /*! ZSTD_compress_generic() : |
|
1150 * Behave about the same as ZSTD_compressStream. To note : |
|
1151 * - Compression parameters are pushed into CCtx before starting compression, using ZSTD_CCtx_setParameter() |
|
1152 * - Compression parameters cannot be changed once compression is started. |
|
1153 * - outpot->pos must be <= dstCapacity, input->pos must be <= srcSize |
|
1154 * - outpot->pos and input->pos will be updated. They are guaranteed to remain below their respective limit. |
|
1155 * - In single-thread mode (default), function is blocking : it completed its job before returning to caller. |
|
1156 * - In multi-thread mode, function is non-blocking : it just acquires a copy of input, and distribute job to internal worker threads, |
|
1157 * and then immediately returns, just indicating that there is some data remaining to be flushed. |
|
1158 * The function nonetheless guarantees forward progress : it will return only after it reads or write at least 1+ byte. |
|
1159 * - Exception : in multi-threading mode, if the first call requests a ZSTD_e_end directive, it is blocking : it will complete compression before giving back control to caller. |
|
1160 * - @return provides a minimum amount of data remaining to be flushed from internal buffers |
|
1161 * or an error code, which can be tested using ZSTD_isError(). |
|
1162 * if @return != 0, flush is not fully completed, there is still some data left within internal buffers. |
|
1163 * This is useful for ZSTD_e_flush, since in this case more flushes are necessary to empty all buffers. |
|
1164 * For ZSTD_e_end, @return == 0 when internal buffers are fully flushed and frame is completed. |
|
1165 * - after a ZSTD_e_end directive, if internal buffer is not fully flushed (@return != 0), |
|
1166 * only ZSTD_e_end or ZSTD_e_flush operations are allowed. |
|
1167 * Before starting a new compression job, or changing compression parameters, |
|
1168 * it is required to fully flush internal buffers. |
|
1169 */ |
|
1170 ZSTDLIB_API size_t ZSTD_compress_generic (ZSTD_CCtx* cctx, |
|
1171 ZSTD_outBuffer* output, |
|
1172 ZSTD_inBuffer* input, |
|
1173 ZSTD_EndDirective endOp); |
|
1174 |
|
1175 |
|
1176 /*! ZSTD_compress_generic_simpleArgs() : |
|
1177 * Same as ZSTD_compress_generic(), |
|
1178 * but using only integral types as arguments. |
|
1179 * Argument list is larger than ZSTD_{in,out}Buffer, |
|
1180 * but can be helpful for binders from dynamic languages |
|
1181 * which have troubles handling structures containing memory pointers. |
|
1182 */ |
|
1183 ZSTDLIB_API size_t ZSTD_compress_generic_simpleArgs ( |
|
1184 ZSTD_CCtx* cctx, |
|
1185 void* dst, size_t dstCapacity, size_t* dstPos, |
|
1186 const void* src, size_t srcSize, size_t* srcPos, |
|
1187 ZSTD_EndDirective endOp); |
|
1188 |
|
1189 |
|
1190 /*! ZSTD_CCtx_params : |
|
1191 * Quick howto : |
|
1192 * - ZSTD_createCCtxParams() : Create a ZSTD_CCtx_params structure |
|
1193 * - ZSTD_CCtxParam_setParameter() : Push parameters one by one into |
|
1194 * an existing ZSTD_CCtx_params structure. |
|
1195 * This is similar to |
|
1196 * ZSTD_CCtx_setParameter(). |
|
1197 * - ZSTD_CCtx_setParametersUsingCCtxParams() : Apply parameters to |
|
1198 * an existing CCtx. |
|
1199 * These parameters will be applied to |
|
1200 * all subsequent compression jobs. |
|
1201 * - ZSTD_compress_generic() : Do compression using the CCtx. |
|
1202 * - ZSTD_freeCCtxParams() : Free the memory. |
|
1203 * |
|
1204 * This can be used with ZSTD_estimateCCtxSize_advanced_usingCCtxParams() |
|
1205 * for static allocation for single-threaded compression. |
|
1206 */ |
|
1207 ZSTDLIB_API ZSTD_CCtx_params* ZSTD_createCCtxParams(void); |
|
1208 ZSTDLIB_API size_t ZSTD_freeCCtxParams(ZSTD_CCtx_params* params); |
|
1209 |
|
1210 |
|
1211 /*! ZSTD_CCtxParams_reset() : |
|
1212 * Reset params to default values. |
|
1213 */ |
|
1214 ZSTDLIB_API size_t ZSTD_CCtxParams_reset(ZSTD_CCtx_params* params); |
|
1215 |
|
1216 /*! ZSTD_CCtxParams_init() : |
|
1217 * Initializes the compression parameters of cctxParams according to |
|
1218 * compression level. All other parameters are reset to their default values. |
|
1219 */ |
|
1220 ZSTDLIB_API size_t ZSTD_CCtxParams_init(ZSTD_CCtx_params* cctxParams, int compressionLevel); |
|
1221 |
|
1222 /*! ZSTD_CCtxParams_init_advanced() : |
|
1223 * Initializes the compression and frame parameters of cctxParams according to |
|
1224 * params. All other parameters are reset to their default values. |
|
1225 */ |
|
1226 ZSTDLIB_API size_t ZSTD_CCtxParams_init_advanced(ZSTD_CCtx_params* cctxParams, ZSTD_parameters params); |
|
1227 |
|
1228 |
|
1229 /*! ZSTD_CCtxParam_setParameter() : |
|
1230 * Similar to ZSTD_CCtx_setParameter. |
|
1231 * Set one compression parameter, selected by enum ZSTD_cParameter. |
|
1232 * Parameters must be applied to a ZSTD_CCtx using ZSTD_CCtx_setParametersUsingCCtxParams(). |
|
1233 * Note : when `value` is an enum, cast it to unsigned for proper type checking. |
|
1234 * @result : 0, or an error code (which can be tested with ZSTD_isError()). |
|
1235 */ |
|
1236 ZSTDLIB_API size_t ZSTD_CCtxParam_setParameter(ZSTD_CCtx_params* params, ZSTD_cParameter param, unsigned value); |
|
1237 |
|
1238 /*! ZSTD_CCtx_setParametersUsingCCtxParams() : |
|
1239 * Apply a set of ZSTD_CCtx_params to the compression context. |
|
1240 * This can be done even after compression is started, |
|
1241 * if nbWorkers==0, this will have no impact until a new compression is started. |
|
1242 * if nbWorkers>=1, new parameters will be picked up at next job, |
|
1243 * with a few restrictions (windowLog, pledgedSrcSize, nbWorkers, jobSize, and overlapLog are not updated). |
|
1244 */ |
|
1245 ZSTDLIB_API size_t ZSTD_CCtx_setParametersUsingCCtxParams( |
|
1246 ZSTD_CCtx* cctx, const ZSTD_CCtx_params* params); |
|
1247 |
|
1248 |
|
1249 /*=== Advanced parameters for decompression API ===*/ |
|
1250 |
|
1251 /* The following parameters must be set after creating a ZSTD_DCtx* (or ZSTD_DStream*) object, |
|
1252 * but before starting decompression of a frame. |
|
1253 */ |
|
1254 |
|
1255 /*! ZSTD_DCtx_loadDictionary() : |
|
1256 * Create an internal DDict from dict buffer, |
|
1257 * to be used to decompress next frames. |
|
1258 * @result : 0, or an error code (which can be tested with ZSTD_isError()). |
|
1259 * Special : Adding a NULL (or 0-size) dictionary invalidates any previous dictionary, |
|
1260 * meaning "return to no-dictionary mode". |
|
1261 * Note 1 : `dict` content will be copied internally. |
|
1262 * Use ZSTD_DCtx_loadDictionary_byReference() |
|
1263 * to reference dictionary content instead. |
|
1264 * In which case, the dictionary buffer must outlive its users. |
|
1265 * Note 2 : Loading a dictionary involves building tables, |
|
1266 * which has a non-negligible impact on CPU usage and latency. |
|
1267 * Note 3 : Use ZSTD_DCtx_loadDictionary_advanced() to select |
|
1268 * how dictionary content will be interpreted and loaded. |
|
1269 */ |
|
1270 ZSTDLIB_API size_t ZSTD_DCtx_loadDictionary(ZSTD_DCtx* dctx, const void* dict, size_t dictSize); |
|
1271 ZSTDLIB_API size_t ZSTD_DCtx_loadDictionary_byReference(ZSTD_DCtx* dctx, const void* dict, size_t dictSize); |
|
1272 ZSTDLIB_API size_t ZSTD_DCtx_loadDictionary_advanced(ZSTD_DCtx* dctx, const void* dict, size_t dictSize, ZSTD_dictLoadMethod_e dictLoadMethod, ZSTD_dictContentType_e dictContentType); |
|
1273 |
|
1274 |
|
1275 /*! ZSTD_DCtx_refDDict() : |
|
1276 * Reference a prepared dictionary, to be used to decompress next frames. |
|
1277 * The dictionary remains active for decompression of future frames using same DCtx. |
|
1278 * @result : 0, or an error code (which can be tested with ZSTD_isError()). |
|
1279 * Note 1 : Currently, only one dictionary can be managed. |
|
1280 * Referencing a new dictionary effectively "discards" any previous one. |
|
1281 * Special : adding a NULL DDict means "return to no-dictionary mode". |
|
1282 * Note 2 : DDict is just referenced, its lifetime must outlive its usage from DCtx. |
|
1283 */ |
|
1284 ZSTDLIB_API size_t ZSTD_DCtx_refDDict(ZSTD_DCtx* dctx, const ZSTD_DDict* ddict); |
|
1285 |
|
1286 |
|
1287 /*! ZSTD_DCtx_refPrefix() : |
|
1288 * Reference a prefix (single-usage dictionary) for next compression job. |
|
1289 * Prefix is **only used once**. It must be explicitly referenced before each frame. |
|
1290 * If there is a need to use same prefix multiple times, consider embedding it into a ZSTD_DDict instead. |
|
1291 * @result : 0, or an error code (which can be tested with ZSTD_isError()). |
|
1292 * Note 1 : Adding any prefix (including NULL) invalidates any previously set prefix or dictionary |
|
1293 * Note 2 : Prefix buffer is referenced. It must outlive compression job. |
|
1294 * Note 3 : By default, the prefix is treated as raw content (ZSTD_dm_rawContent). |
|
1295 * Use ZSTD_CCtx_refPrefix_advanced() to alter dictMode. |
|
1296 * Note 4 : Referencing a raw content prefix has almost no cpu nor memory cost. |
|
1297 */ |
|
1298 ZSTDLIB_API size_t ZSTD_DCtx_refPrefix(ZSTD_DCtx* dctx, const void* prefix, size_t prefixSize); |
|
1299 ZSTDLIB_API size_t ZSTD_DCtx_refPrefix_advanced(ZSTD_DCtx* dctx, const void* prefix, size_t prefixSize, ZSTD_dictContentType_e dictContentType); |
|
1300 |
|
1301 |
|
1302 /*! ZSTD_DCtx_setMaxWindowSize() : |
|
1303 * Refuses allocating internal buffers for frames requiring a window size larger than provided limit. |
|
1304 * This is useful to prevent a decoder context from reserving too much memory for itself (potential attack scenario). |
|
1305 * This parameter is only useful in streaming mode, since no internal buffer is allocated in direct mode. |
|
1306 * By default, a decompression context accepts all window sizes <= (1 << ZSTD_WINDOWLOG_MAX) |
|
1307 * @return : 0, or an error code (which can be tested using ZSTD_isError()). |
|
1308 */ |
|
1309 ZSTDLIB_API size_t ZSTD_DCtx_setMaxWindowSize(ZSTD_DCtx* dctx, size_t maxWindowSize); |
|
1310 |
|
1311 |
|
1312 /*! ZSTD_DCtx_setFormat() : |
|
1313 * Instruct the decoder context about what kind of data to decode next. |
|
1314 * This instruction is mandatory to decode data without a fully-formed header, |
|
1315 * such ZSTD_f_zstd1_magicless for example. |
|
1316 * @return : 0, or an error code (which can be tested using ZSTD_isError()). |
|
1317 */ |
|
1318 ZSTDLIB_API size_t ZSTD_DCtx_setFormat(ZSTD_DCtx* dctx, ZSTD_format_e format); |
|
1319 |
|
1320 |
|
1321 /*! ZSTD_decompress_generic() : |
|
1322 * Behave the same as ZSTD_decompressStream. |
|
1323 * Decompression parameters cannot be changed once decompression is started. |
|
1324 * @return : an error code, which can be tested using ZSTD_isError() |
|
1325 * if >0, a hint, nb of expected input bytes for next invocation. |
|
1326 * `0` means : a frame has just been fully decoded and flushed. |
|
1327 */ |
|
1328 ZSTDLIB_API size_t ZSTD_decompress_generic(ZSTD_DCtx* dctx, |
|
1329 ZSTD_outBuffer* output, |
|
1330 ZSTD_inBuffer* input); |
|
1331 |
|
1332 |
|
1333 /*! ZSTD_decompress_generic_simpleArgs() : |
|
1334 * Same as ZSTD_decompress_generic(), |
|
1335 * but using only integral types as arguments. |
|
1336 * Argument list is larger than ZSTD_{in,out}Buffer, |
|
1337 * but can be helpful for binders from dynamic languages |
|
1338 * which have troubles handling structures containing memory pointers. |
|
1339 */ |
|
1340 ZSTDLIB_API size_t ZSTD_decompress_generic_simpleArgs ( |
|
1341 ZSTD_DCtx* dctx, |
|
1342 void* dst, size_t dstCapacity, size_t* dstPos, |
|
1343 const void* src, size_t srcSize, size_t* srcPos); |
|
1344 |
|
1345 |
|
1346 /*! ZSTD_DCtx_reset() : |
|
1347 * Return a DCtx to clean state. |
|
1348 * If a decompression was ongoing, any internal data not yet flushed is cancelled. |
|
1349 * All parameters are back to default values, including sticky ones. |
|
1350 * Dictionary (if any) is dropped. |
|
1351 * Parameters can be modified again after a reset. |
|
1352 */ |
|
1353 ZSTDLIB_API void ZSTD_DCtx_reset(ZSTD_DCtx* dctx); |
|
1354 |
|
1355 |
|
1356 |
|
1357 /* ============================ */ |
|
1358 /** Block level API */ |
|
1359 /* ============================ */ |
|
1360 |
|
1361 /*! |
666 Block functions produce and decode raw zstd blocks, without frame metadata. |
1362 Block functions produce and decode raw zstd blocks, without frame metadata. |
667 Frame metadata cost is typically ~18 bytes, which can be non-negligible for very small blocks (< 100 bytes). |
1363 Frame metadata cost is typically ~18 bytes, which can be non-negligible for very small blocks (< 100 bytes). |
668 User will have to take in charge required information to regenerate data, such as compressed and content sizes. |
1364 User will have to take in charge required information to regenerate data, such as compressed and content sizes. |
669 |
1365 |
670 A few rules to respect : |
1366 A few rules to respect : |
671 - Compressing and decompressing require a context structure |
1367 - Compressing and decompressing require a context structure |
672 + Use ZSTD_createCCtx() and ZSTD_createDCtx() |
1368 + Use ZSTD_createCCtx() and ZSTD_createDCtx() |
673 - It is necessary to init context before starting |
1369 - It is necessary to init context before starting |
674 + compression : ZSTD_compressBegin() |
1370 + compression : any ZSTD_compressBegin*() variant, including with dictionary |
675 + decompression : ZSTD_decompressBegin() |
1371 + decompression : any ZSTD_decompressBegin*() variant, including with dictionary |
676 + variants _usingDict() are also allowed |
1372 + copyCCtx() and copyDCtx() can be used too |
677 + copyCCtx() and copyDCtx() work too |
1373 - Block size is limited, it must be <= ZSTD_getBlockSize() <= ZSTD_BLOCKSIZE_MAX == 128 KB |
678 - Block size is limited, it must be <= ZSTD_getBlockSizeMax() |
1374 + If input is larger than a block size, it's necessary to split input data into multiple blocks |
679 + If you need to compress more, cut data into multiple blocks |
1375 + For inputs larger than a single block size, consider using the regular ZSTD_compress() instead. |
680 + Consider using the regular ZSTD_compress() instead, as frame metadata costs become negligible when source size is large. |
1376 Frame metadata is not that costly, and quickly becomes negligible as source size grows larger. |
681 - When a block is considered not compressible enough, ZSTD_compressBlock() result will be zero. |
1377 - When a block is considered not compressible enough, ZSTD_compressBlock() result will be zero. |
682 In which case, nothing is produced into `dst`. |
1378 In which case, nothing is produced into `dst`. |
683 + User must test for such outcome and deal directly with uncompressed data |
1379 + User must test for such outcome and deal directly with uncompressed data |
684 + ZSTD_decompressBlock() doesn't accept uncompressed data as input !!! |
1380 + ZSTD_decompressBlock() doesn't accept uncompressed data as input !!! |
685 + In case of multiple successive blocks, decoder must be informed of uncompressed block existence to follow proper history. |
1381 + In case of multiple successive blocks, should some of them be uncompressed, |
686 Use ZSTD_insertBlock() in such a case. |
1382 decoder must be informed of their existence in order to follow proper history. |
|
1383 Use ZSTD_insertBlock() for such a case. |
687 */ |
1384 */ |
688 |
1385 |
689 #define ZSTD_BLOCKSIZE_ABSOLUTEMAX (128 * 1024) /* define, for static allocation */ |
1386 #define ZSTD_BLOCKSIZELOG_MAX 17 |
|
1387 #define ZSTD_BLOCKSIZE_MAX (1<<ZSTD_BLOCKSIZELOG_MAX) /* define, for static allocation */ |
690 /*===== Raw zstd block functions =====*/ |
1388 /*===== Raw zstd block functions =====*/ |
691 ZSTDLIB_API size_t ZSTD_getBlockSizeMax(ZSTD_CCtx* cctx); |
1389 ZSTDLIB_API size_t ZSTD_getBlockSize (const ZSTD_CCtx* cctx); |
692 ZSTDLIB_API size_t ZSTD_compressBlock (ZSTD_CCtx* cctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize); |
1390 ZSTDLIB_API size_t ZSTD_compressBlock (ZSTD_CCtx* cctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize); |
693 ZSTDLIB_API size_t ZSTD_decompressBlock(ZSTD_DCtx* dctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize); |
1391 ZSTDLIB_API size_t ZSTD_decompressBlock(ZSTD_DCtx* dctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize); |
694 ZSTDLIB_API size_t ZSTD_insertBlock(ZSTD_DCtx* dctx, const void* blockStart, size_t blockSize); /**< insert block into `dctx` history. Useful for uncompressed blocks */ |
1392 ZSTDLIB_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. */ |
695 |
1393 |
696 |
1394 |
697 #endif /* ZSTD_H_ZSTD_STATIC_LINKING_ONLY */ |
1395 #endif /* ZSTD_H_ZSTD_STATIC_LINKING_ONLY */ |
698 |
1396 |
699 #if defined (__cplusplus) |
1397 #if defined (__cplusplus) |