1 /*
2 * Copyright (c) 2016-present, Yann Collet, Facebook, Inc.
3 * All rights reserved.
4 *
5 * This source code is licensed under the BSD-style license found in the
6 * LICENSE file in the root directory of https://github.com/facebook/zstd.
7 * An additional grant of patent rights can be found in the PATENTS file in the
8 * same directory.
9 *
10 * This program is free software; you can redistribute it and/or modify it under
11 * the terms of the GNU General Public License version 2 as published by the
12 * Free Software Foundation. This program is dual-licensed; you may select
13 * either version 2 of the GNU General Public License ("GPL") or BSD license
14 * ("BSD").
15 */
16
17 #ifndef ZSTD_H
18 #define ZSTD_H
19
20 /* ====== Dependency ======*/
21 #include <linux/types.h> /* size_t */
22
23
24 /*-*****************************************************************************
25 * Introduction
26 *
27 * zstd, short for Zstandard, is a fast lossless compression algorithm,
28 * targeting real-time compression scenarios at zlib-level and better
29 * compression ratios. The zstd compression library provides in-memory
30 * compression and decompression functions. The library supports compression
31 * levels from 1 up to ZSTD_maxCLevel() which is 22. Levels >= 20, labeled
32 * ultra, should be used with caution, as they require more memory.
33 * Compression can be done in:
34 * - a single step, reusing a context (described as Explicit memory management)
35 * - unbounded multiple steps (described as Streaming compression)
36 * The compression ratio achievable on small data can be highly improved using
37 * compression with a dictionary in:
38 * - a single step (described as Simple dictionary API)
39 * - a single step, reusing a dictionary (described as Fast dictionary API)
40 ******************************************************************************/
41
42 /*====== Helper functions ======*/
43
44 /**
45 * enum ZSTD_ErrorCode - zstd error codes
46 *
47 * Functions that return size_t can be checked for errors using ZSTD_isError()
48 * and the ZSTD_ErrorCode can be extracted using ZSTD_getErrorCode().
49 */
50 typedef enum {
51 ZSTD_error_no_error,
52 ZSTD_error_GENERIC,
53 ZSTD_error_prefix_unknown,
54 ZSTD_error_version_unsupported,
55 ZSTD_error_parameter_unknown,
56 ZSTD_error_frameParameter_unsupported,
57 ZSTD_error_frameParameter_unsupportedBy32bits,
58 ZSTD_error_frameParameter_windowTooLarge,
59 ZSTD_error_compressionParameter_unsupported,
60 ZSTD_error_init_missing,
61 ZSTD_error_memory_allocation,
62 ZSTD_error_stage_wrong,
63 ZSTD_error_dstSize_tooSmall,
64 ZSTD_error_srcSize_wrong,
65 ZSTD_error_corruption_detected,
66 ZSTD_error_checksum_wrong,
67 ZSTD_error_tableLog_tooLarge,
68 ZSTD_error_maxSymbolValue_tooLarge,
69 ZSTD_error_maxSymbolValue_tooSmall,
70 ZSTD_error_dictionary_corrupted,
71 ZSTD_error_dictionary_wrong,
72 ZSTD_error_dictionaryCreation_failed,
73 ZSTD_error_maxCode
74 } ZSTD_ErrorCode;
75
76 /**
77 * ZSTD_maxCLevel() - maximum compression level available
78 *
79 * Return: Maximum compression level available.
80 */
81 int ZSTD_maxCLevel(void);
82 /**
83 * ZSTD_compressBound() - maximum compressed size in worst case scenario
84 * @srcSize: The size of the data to compress.
85 *
86 * Return: The maximum compressed size in the worst case scenario.
87 */
88 size_t ZSTD_compressBound(size_t srcSize);
89 /**
90 * ZSTD_isError() - tells if a size_t function result is an error code
91 * @code: The function result to check for error.
92 *
93 * Return: Non-zero iff the code is an error.
94 */
95 static __attribute__((unused)) unsigned int ZSTD_isError(size_t code)
96 {
97 return code > (size_t)-ZSTD_error_maxCode;
98 }
99 /**
100 * ZSTD_getErrorCode() - translates an error function result to a ZSTD_ErrorCode
101 * @functionResult: The result of a function for which ZSTD_isError() is true.
102 *
103 * Return: The ZSTD_ErrorCode corresponding to the functionResult or 0
104 * if the functionResult isn't an error.
105 */
106 static __attribute__((unused)) ZSTD_ErrorCode ZSTD_getErrorCode(
107 size_t functionResult)
108 {
109 if (!ZSTD_isError(functionResult))
110 return (ZSTD_ErrorCode)0;
111 return (ZSTD_ErrorCode)(0 - functionResult);
112 }
113
114 /**
115 * enum ZSTD_strategy - zstd compression search strategy
116 *
117 * From faster to stronger.
118 */
119 typedef enum {
120 ZSTD_fast,
121 ZSTD_dfast,
122 ZSTD_greedy,
123 ZSTD_lazy,
124 ZSTD_lazy2,
125 ZSTD_btlazy2,
126 ZSTD_btopt,
127 ZSTD_btopt2
128 } ZSTD_strategy;
129
130 /**
131 * struct ZSTD_compressionParameters - zstd compression parameters
132 * @windowLog: Log of the largest match distance. Larger means more
133 * compression, and more memory needed during decompression.
134 * @chainLog: Fully searched segment. Larger means more compression, slower,
135 * and more memory (useless for fast).
136 * @hashLog: Dispatch table. Larger means more compression,
137 * slower, and more memory.
138 * @searchLog: Number of searches. Larger means more compression and slower.
139 * @searchLength: Match length searched. Larger means faster decompression,
140 * sometimes less compression.
141 * @targetLength: Acceptable match size for optimal parser (only). Larger means
142 * more compression, and slower.
143 * @strategy: The zstd compression strategy.
144 */
145 typedef struct {
146 unsigned int windowLog;
147 unsigned int chainLog;
148 unsigned int hashLog;
149 unsigned int searchLog;
150 unsigned int searchLength;
151 unsigned int targetLength;
152 ZSTD_strategy strategy;
153 } ZSTD_compressionParameters;
154
155 /**
156 * struct ZSTD_frameParameters - zstd frame parameters
157 * @contentSizeFlag: Controls whether content size will be present in the frame
158 * header (when known).
159 * @checksumFlag: Controls whether a 32-bit checksum is generated at the end
160 * of the frame for error detection.
161 * @noDictIDFlag: Controls whether dictID will be saved into the frame header
162 * when using dictionary compression.
163 *
164 * The default value is all fields set to 0.
165 */
166 typedef struct {
167 unsigned int contentSizeFlag;
168 unsigned int checksumFlag;
169 unsigned int noDictIDFlag;
170 } ZSTD_frameParameters;
171
172 /**
173 * struct ZSTD_parameters - zstd parameters
174 * @cParams: The compression parameters.
175 * @fParams: The frame parameters.
176 */
177 typedef struct {
178 ZSTD_compressionParameters cParams;
179 ZSTD_frameParameters fParams;
180 } ZSTD_parameters;
181
182 /**
183 * ZSTD_getCParams() - returns ZSTD_compressionParameters for selected level
184 * @compressionLevel: The compression level from 1 to ZSTD_maxCLevel().
185 * @estimatedSrcSize: The estimated source size to compress or 0 if unknown.
186 * @dictSize: The dictionary size or 0 if a dictionary isn't being used.
187 *
188 * Return: The selected ZSTD_compressionParameters.
189 */
190 ZSTD_compressionParameters ZSTD_getCParams(int compressionLevel,
191 unsigned long long estimatedSrcSize, size_t dictSize);
192
193 /**
194 * ZSTD_getParams() - returns ZSTD_parameters for selected level
195 * @compressionLevel: The compression level from 1 to ZSTD_maxCLevel().
196 * @estimatedSrcSize: The estimated source size to compress or 0 if unknown.
197 * @dictSize: The dictionary size or 0 if a dictionary isn't being used.
198 *
199 * The same as ZSTD_getCParams() except also selects the default frame
200 * parameters (all zero).
201 *
202 * Return: The selected ZSTD_parameters.
203 */
204 ZSTD_parameters ZSTD_getParams(int compressionLevel,
205 unsigned long long estimatedSrcSize, size_t dictSize);
206
207 /*-*************************************
208 * Explicit memory management
209 **************************************/
210
211 /**
212 * ZSTD_CCtxWorkspaceBound() - amount of memory needed to initialize a ZSTD_CCtx
213 * @cParams: The compression parameters to be used for compression.
214 *
215 * If multiple compression parameters might be used, the caller must call
216 * ZSTD_CCtxWorkspaceBound() for each set of parameters and use the maximum
217 * size.
218 *
219 * Return: A lower bound on the size of the workspace that is passed to
220 * ZSTD_initCCtx().
221 */
222 size_t ZSTD_CCtxWorkspaceBound(ZSTD_compressionParameters cParams);
223
224 /**
225 * struct ZSTD_CCtx - the zstd compression context
226 *
227 * When compressing many times it is recommended to allocate a context just once
228 * and reuse it for each successive compression operation.
229 */
230 typedef struct ZSTD_CCtx_s ZSTD_CCtx;
231 /**
232 * ZSTD_initCCtx() - initialize a zstd compression context
233 * @workspace: The workspace to emplace the context into. It must outlive
234 * the returned context.
235 * @workspaceSize: The size of workspace. Use ZSTD_CCtxWorkspaceBound() to
236 * determine how large the workspace must be.
237 *
238 * Return: A compression context emplaced into workspace.
239 */
240 ZSTD_CCtx *ZSTD_initCCtx(void *workspace, size_t workspaceSize);
241
242 /**
243 * ZSTD_compressCCtx() - compress src into dst
244 * @ctx: The context. Must have been initialized with a workspace at
245 * least as large as ZSTD_CCtxWorkspaceBound(params.cParams).
246 * @dst: The buffer to compress src into.
247 * @dstCapacity: The size of the destination buffer. May be any size, but
248 * ZSTD_compressBound(srcSize) is guaranteed to be large enough.
249 * @src: The data to compress.
250 * @srcSize: The size of the data to compress.
251 * @params: The parameters to use for compression. See ZSTD_getParams().
252 *
253 * Return: The compressed size or an error, which can be checked using
254 * ZSTD_isError().
255 */
256 size_t ZSTD_compressCCtx(ZSTD_CCtx *ctx, void *dst, size_t dstCapacity,
257 const void *src, size_t srcSize, ZSTD_parameters params);
258
259 /**
260 * ZSTD_DCtxWorkspaceBound() - amount of memory needed to initialize a ZSTD_DCtx
261 *
262 * Return: A lower bound on the size of the workspace that is passed to
263 * ZSTD_initDCtx().
264 */
265 size_t ZSTD_DCtxWorkspaceBound(void);
266
267 /**
268 * struct ZSTD_DCtx - the zstd decompression context
269 *
270 * When decompressing many times it is recommended to allocate a context just
271 * once and reuse it for each successive decompression operation.
272 */
273 typedef struct ZSTD_DCtx_s ZSTD_DCtx;
274 /**
275 * ZSTD_initDCtx() - initialize a zstd decompression context
276 * @workspace: The workspace to emplace the context into. It must outlive
277 * the returned context.
278 * @workspaceSize: The size of workspace. Use ZSTD_DCtxWorkspaceBound() to
279 * determine how large the workspace must be.
280 *
281 * Return: A decompression context emplaced into workspace.
282 */
283 ZSTD_DCtx *ZSTD_initDCtx(void *workspace, size_t workspaceSize);
284
285 /**
286 * ZSTD_decompressDCtx() - decompress zstd compressed src into dst
287 * @ctx: The decompression context.
288 * @dst: The buffer to decompress src into.
289 * @dstCapacity: The size of the destination buffer. Must be at least as large
290 * as the decompressed size. If the caller cannot upper bound the
291 * decompressed size, then it's better to use the streaming API.
292 * @src: The zstd compressed data to decompress. Multiple concatenated
293 * frames and skippable frames are allowed.
294 * @srcSize: The exact size of the data to decompress.
295 *
296 * Return: The decompressed size or an error, which can be checked using
297 * ZSTD_isError().
298 */
299 size_t ZSTD_decompressDCtx(ZSTD_DCtx *ctx, void *dst, size_t dstCapacity,
300 const void *src, size_t srcSize);
301
302 /*-************************
303 * Simple dictionary API
304 **************************/
305
306 /**
307 * ZSTD_compress_usingDict() - compress src into dst using a dictionary
308 * @ctx: The context. Must have been initialized with a workspace at
309 * least as large as ZSTD_CCtxWorkspaceBound(params.cParams).
310 * @dst: The buffer to compress src into.
311 * @dstCapacity: The size of the destination buffer. May be any size, but
312 * ZSTD_compressBound(srcSize) is guaranteed to be large enough.
313 * @src: The data to compress.
314 * @srcSize: The size of the data to compress.
315 * @dict: The dictionary to use for compression.
316 * @dictSize: The size of the dictionary.
317 * @params: The parameters to use for compression. See ZSTD_getParams().
318 *
319 * Compression using a predefined dictionary. The same dictionary must be used
320 * during decompression.
321 *
322 * Return: The compressed size or an error, which can be checked using
323 * ZSTD_isError().
324 */
325 size_t ZSTD_compress_usingDict(ZSTD_CCtx *ctx, void *dst, size_t dstCapacity,
326 const void *src, size_t srcSize, const void *dict, size_t dictSize,
327 ZSTD_parameters params);
328
329 /**
330 * ZSTD_decompress_usingDict() - decompress src into dst using a dictionary
331 * @ctx: The decompression context.
332 * @dst: The buffer to decompress src into.
333 * @dstCapacity: The size of the destination buffer. Must be at least as large
334 * as the decompressed size. If the caller cannot upper bound the
335 * decompressed size, then it's better to use the streaming API.
336 * @src: The zstd compressed data to decompress. Multiple concatenated
337 * frames and skippable frames are allowed.
338 * @srcSize: The exact size of the data to decompress.
339 * @dict: The dictionary to use for decompression. The same dictionary
340 * must've been used to compress the data.
341 * @dictSize: The size of the dictionary.
342 *
343 * Return: The decompressed size or an error, which can be checked using
344 * ZSTD_isError().
345 */
346 size_t ZSTD_decompress_usingDict(ZSTD_DCtx *ctx, void *dst, size_t dstCapacity,
347 const void *src, size_t srcSize, const void *dict, size_t dictSize);
348
349 /*-**************************
350 * Fast dictionary API
351 ***************************/
352
353 /**
354 * ZSTD_CDictWorkspaceBound() - memory needed to initialize a ZSTD_CDict
355 * @cParams: The compression parameters to be used for compression.
356 *
357 * Return: A lower bound on the size of the workspace that is passed to
358 * ZSTD_initCDict().
359 */
360 size_t ZSTD_CDictWorkspaceBound(ZSTD_compressionParameters cParams);
361
362 /**
363 * struct ZSTD_CDict - a digested dictionary to be used for compression
364 */
365 typedef struct ZSTD_CDict_s ZSTD_CDict;
366
367 /**
368 * ZSTD_initCDict() - initialize a digested dictionary for compression
369 * @dictBuffer: The dictionary to digest. The buffer is referenced by the
370 * ZSTD_CDict so it must outlive the returned ZSTD_CDict.
371 * @dictSize: The size of the dictionary.
372 * @params: The parameters to use for compression. See ZSTD_getParams().
373 * @workspace: The workspace. It must outlive the returned ZSTD_CDict.
374 * @workspaceSize: The workspace size. Must be at least
375 * ZSTD_CDictWorkspaceBound(params.cParams).
376 *
377 * When compressing multiple messages / blocks with the same dictionary it is
378 * recommended to load it just once. The ZSTD_CDict merely references the
379 * dictBuffer, so it must outlive the returned ZSTD_CDict.
380 *
381 * Return: The digested dictionary emplaced into workspace.
382 */
383 ZSTD_CDict *ZSTD_initCDict(const void *dictBuffer, size_t dictSize,
384 ZSTD_parameters params, void *workspace, size_t workspaceSize);
385
386 /**
387 * ZSTD_compress_usingCDict() - compress src into dst using a ZSTD_CDict
388 * @ctx: The context. Must have been initialized with a workspace at
389 * least as large as ZSTD_CCtxWorkspaceBound(cParams) where
390 * cParams are the compression parameters used to initialize the
391 * cdict.
392 * @dst: The buffer to compress src into.
393 * @dstCapacity: The size of the destination buffer. May be any size, but
394 * ZSTD_compressBound(srcSize) is guaranteed to be large enough.
395 * @src: The data to compress.
396 * @srcSize: The size of the data to compress.
397 * @cdict: The digested dictionary to use for compression.
398 * @params: The parameters to use for compression. See ZSTD_getParams().
399 *
400 * Compression using a digested dictionary. The same dictionary must be used
401 * during decompression.
402 *
403 * Return: The compressed size or an error, which can be checked using
404 * ZSTD_isError().
405 */
406 size_t ZSTD_compress_usingCDict(ZSTD_CCtx *cctx, void *dst, size_t dstCapacity,
407 const void *src, size_t srcSize, const ZSTD_CDict *cdict);
408
409
410 /**
411 * ZSTD_DDictWorkspaceBound() - memory needed to initialize a ZSTD_DDict
412 *
413 * Return: A lower bound on the size of the workspace that is passed to
414 * ZSTD_initDDict().
415 */
416 size_t ZSTD_DDictWorkspaceBound(void);
417
418 /**
419 * struct ZSTD_DDict - a digested dictionary to be used for decompression
420 */
421 typedef struct ZSTD_DDict_s ZSTD_DDict;
422
423 /**
424 * ZSTD_initDDict() - initialize a digested dictionary for decompression
425 * @dictBuffer: The dictionary to digest. The buffer is referenced by the
426 * ZSTD_DDict so it must outlive the returned ZSTD_DDict.
427 * @dictSize: The size of the dictionary.
428 * @workspace: The workspace. It must outlive the returned ZSTD_DDict.
429 * @workspaceSize: The workspace size. Must be at least
430 * ZSTD_DDictWorkspaceBound().
431 *
432 * When decompressing multiple messages / blocks with the same dictionary it is
433 * recommended to load it just once. The ZSTD_DDict merely references the
434 * dictBuffer, so it must outlive the returned ZSTD_DDict.
435 *
436 * Return: The digested dictionary emplaced into workspace.
437 */
438 ZSTD_DDict *ZSTD_initDDict(const void *dictBuffer, size_t dictSize,
439 void *workspace, size_t workspaceSize);
440
441 /**
442 * ZSTD_decompress_usingDDict() - decompress src into dst using a ZSTD_DDict
443 * @ctx: The decompression context.
444 * @dst: The buffer to decompress src into.
445 * @dstCapacity: The size of the destination buffer. Must be at least as large
446 * as the decompressed size. If the caller cannot upper bound the
447 * decompressed size, then it's better to use the streaming API.
448 * @src: The zstd compressed data to decompress. Multiple concatenated
449 * frames and skippable frames are allowed.
450 * @srcSize: The exact size of the data to decompress.
451 * @ddict: The digested dictionary to use for decompression. The same
452 * dictionary must've been used to compress the data.
453 *
454 * Return: The decompressed size or an error, which can be checked using
455 * ZSTD_isError().
456 */
457 size_t ZSTD_decompress_usingDDict(ZSTD_DCtx *dctx, void *dst,
458 size_t dstCapacity, const void *src, size_t srcSize,
459 const ZSTD_DDict *ddict);
460
461
462 /*-**************************
463 * Streaming
464 ***************************/
465
466 /**
467 * struct ZSTD_inBuffer - input buffer for streaming
468 * @src: Start of the input buffer.
469 * @size: Size of the input buffer.
470 * @pos: Position where reading stopped. Will be updated.
471 * Necessarily 0 <= pos <= size.
472 */
473 typedef struct ZSTD_inBuffer_s {
474 const void *src;
475 size_t size;
476 size_t pos;
477 } ZSTD_inBuffer;
478
479 /**
480 * struct ZSTD_outBuffer - output buffer for streaming
481 * @dst: Start of the output buffer.
482 * @size: Size of the output buffer.
483 * @pos: Position where writing stopped. Will be updated.
484 * Necessarily 0 <= pos <= size.
485 */
486 typedef struct ZSTD_outBuffer_s {
487 void *dst;
488 size_t size;
489 size_t pos;
490 } ZSTD_outBuffer;
491
492
493
494 /*-*****************************************************************************
495 * Streaming compression - HowTo
496 *
497 * A ZSTD_CStream object is required to track streaming operation.
498 * Use ZSTD_initCStream() to initialize a ZSTD_CStream object.
499 * ZSTD_CStream objects can be reused multiple times on consecutive compression
500 * operations. It is recommended to re-use ZSTD_CStream in situations where many
501 * streaming operations will be achieved consecutively. Use one separate
502 * ZSTD_CStream per thread for parallel execution.
503 *
504 * Use ZSTD_compressStream() repetitively to consume input stream.
505 * The function will automatically update both `pos` fields.
506 * Note that it may not consume the entire input, in which case `pos < size`,
507 * and it's up to the caller to present again remaining data.
508 * It returns a hint for the preferred number of bytes to use as an input for
509 * the next function call.
510 *
511 * At any moment, it's possible to flush whatever data remains within internal
512 * buffer, using ZSTD_flushStream(). `output->pos` will be updated. There might
513 * still be some content left within the internal buffer if `output->size` is
514 * too small. It returns the number of bytes left in the internal buffer and
515 * must be called until it returns 0.
516 *
517 * ZSTD_endStream() instructs to finish a frame. It will perform a flush and
518 * write frame epilogue. The epilogue is required for decoders to consider a
519 * frame completed. Similar to ZSTD_flushStream(), it may not be able to flush
520 * the full content if `output->size` is too small. In which case, call again
521 * ZSTD_endStream() to complete the flush. It returns the number of bytes left
522 * in the internal buffer and must be called until it returns 0.
523 ******************************************************************************/
524
525 /**
526 * ZSTD_CStreamWorkspaceBound() - memory needed to initialize a ZSTD_CStream
527 * @cParams: The compression parameters to be used for compression.
528 *
529 * Return: A lower bound on the size of the workspace that is passed to
530 * ZSTD_initCStream() and ZSTD_initCStream_usingCDict().
531 */
532 size_t ZSTD_CStreamWorkspaceBound(ZSTD_compressionParameters cParams);
533
534 /**
535 * struct ZSTD_CStream - the zstd streaming compression context
536 */
537 typedef struct ZSTD_CStream_s ZSTD_CStream;
538
539 /*===== ZSTD_CStream management functions =====*/
540 /**
541 * ZSTD_initCStream() - initialize a zstd streaming compression context
542 * @params: The zstd compression parameters.
543 * @pledgedSrcSize: If params.fParams.contentSizeFlag == 1 then the caller must
544 * pass the source size (zero means empty source). Otherwise,
545 * the caller may optionally pass the source size, or zero if
546 * unknown.
547 * @workspace: The workspace to emplace the context into. It must outlive
548 * the returned context.
549 * @workspaceSize: The size of workspace.
550 * Use ZSTD_CStreamWorkspaceBound(params.cParams) to determine
551 * how large the workspace must be.
552 *
553 * Return: The zstd streaming compression context.
554 */
555 ZSTD_CStream *ZSTD_initCStream(ZSTD_parameters params,
556 unsigned long long pledgedSrcSize, void *workspace,
557 size_t workspaceSize);
558
559 /**
560 * ZSTD_initCStream_usingCDict() - initialize a streaming compression context
561 * @cdict: The digested dictionary to use for compression.
562 * @pledgedSrcSize: Optionally the source size, or zero if unknown.
563 * @workspace: The workspace to emplace the context into. It must outlive
564 * the returned context.
565 * @workspaceSize: The size of workspace. Call ZSTD_CStreamWorkspaceBound()
566 * with the cParams used to initialize the cdict to determine
567 * how large the workspace must be.
568 *
569 * Return: The zstd streaming compression context.
570 */
571 ZSTD_CStream *ZSTD_initCStream_usingCDict(const ZSTD_CDict *cdict,
572 unsigned long long pledgedSrcSize, void *workspace,
573 size_t workspaceSize);
574
575 /*===== Streaming compression functions =====*/
576 /**
577 * ZSTD_resetCStream() - reset the context using parameters from creation
578 * @zcs: The zstd streaming compression context to reset.
579 * @pledgedSrcSize: Optionally the source size, or zero if unknown.
580 *
581 * Resets the context using the parameters from creation. Skips dictionary
582 * loading, since it can be reused. If `pledgedSrcSize` is non-zero the frame
583 * content size is always written into the frame header.
584 *
585 * Return: Zero or an error, which can be checked using ZSTD_isError().
586 */
587 size_t ZSTD_resetCStream(ZSTD_CStream *zcs, unsigned long long pledgedSrcSize);
588 /**
589 * ZSTD_compressStream() - streaming compress some of input into output
590 * @zcs: The zstd streaming compression context.
591 * @output: Destination buffer. `output->pos` is updated to indicate how much
592 * compressed data was written.
593 * @input: Source buffer. `input->pos` is updated to indicate how much data was
594 * read. Note that it may not consume the entire input, in which case
595 * `input->pos < input->size`, and it's up to the caller to present
596 * remaining data again.
597 *
598 * The `input` and `output` buffers may be any size. Guaranteed to make some
599 * forward progress if `input` and `output` are not empty.
600 *
601 * Return: A hint for the number of bytes to use as the input for the next
602 * function call or an error, which can be checked using
603 * ZSTD_isError().
604 */
605 size_t ZSTD_compressStream(ZSTD_CStream *zcs, ZSTD_outBuffer *output,
606 ZSTD_inBuffer *input);
607 /**
608 * ZSTD_flushStream() - flush internal buffers into output
609 * @zcs: The zstd streaming compression context.
610 * @output: Destination buffer. `output->pos` is updated to indicate how much
611 * compressed data was written.
612 *
613 * ZSTD_flushStream() must be called until it returns 0, meaning all the data
614 * has been flushed. Since ZSTD_flushStream() causes a block to be ended,
615 * calling it too often will degrade the compression ratio.
616 *
617 * Return: The number of bytes still present within internal buffers or an
618 * error, which can be checked using ZSTD_isError().
619 */
620 size_t ZSTD_flushStream(ZSTD_CStream *zcs, ZSTD_outBuffer *output);
621 /**
622 * ZSTD_endStream() - flush internal buffers into output and end the frame
623 * @zcs: The zstd streaming compression context.
624 * @output: Destination buffer. `output->pos` is updated to indicate how much
625 * compressed data was written.
626 *
627 * ZSTD_endStream() must be called until it returns 0, meaning all the data has
628 * been flushed and the frame epilogue has been written.
629 *
630 * Return: The number of bytes still present within internal buffers or an
631 * error, which can be checked using ZSTD_isError().
632 */
633 size_t ZSTD_endStream(ZSTD_CStream *zcs, ZSTD_outBuffer *output);
634
635 /**
636 * ZSTD_CStreamInSize() - recommended size for the input buffer
637 *
638 * Return: The recommended size for the input buffer.
639 */
640 size_t ZSTD_CStreamInSize(void);
641 /**
642 * ZSTD_CStreamOutSize() - recommended size for the output buffer
643 *
644 * When the output buffer is at least this large, it is guaranteed to be large
645 * enough to flush at least one complete compressed block.
646 *
647 * Return: The recommended size for the output buffer.
648 */
649 size_t ZSTD_CStreamOutSize(void);
650
651
652
653 /*-*****************************************************************************
654 * Streaming decompression - HowTo
655 *
656 * A ZSTD_DStream object is required to track streaming operations.
657 * Use ZSTD_initDStream() to initialize a ZSTD_DStream object.
658 * ZSTD_DStream objects can be re-used multiple times.
659 *
660 * Use ZSTD_decompressStream() repetitively to consume your input.
661 * The function will update both `pos` fields.
662 * If `input->pos < input->size`, some input has not been consumed.
663 * It's up to the caller to present again remaining data.
664 * If `output->pos < output->size`, decoder has flushed everything it could.
665 * Returns 0 iff a frame is completely decoded and fully flushed.
666 * Otherwise it returns a suggested next input size that will never load more
667 * than the current frame.
668 ******************************************************************************/
669
670 /**
671 * ZSTD_DStreamWorkspaceBound() - memory needed to initialize a ZSTD_DStream
672 * @maxWindowSize: The maximum window size allowed for compressed frames.
673 *
674 * Return: A lower bound on the size of the workspace that is passed to
675 * ZSTD_initDStream() and ZSTD_initDStream_usingDDict().
676 */
677 size_t ZSTD_DStreamWorkspaceBound(size_t maxWindowSize);
678
679 /**
680 * struct ZSTD_DStream - the zstd streaming decompression context
681 */
682 typedef struct ZSTD_DStream_s ZSTD_DStream;
683 /*===== ZSTD_DStream management functions =====*/
684 /**
685 * ZSTD_initDStream() - initialize a zstd streaming decompression context
686 * @maxWindowSize: The maximum window size allowed for compressed frames.
687 * @workspace: The workspace to emplace the context into. It must outlive
688 * the returned context.
689 * @workspaceSize: The size of workspace.
690 * Use ZSTD_DStreamWorkspaceBound(maxWindowSize) to determine
691 * how large the workspace must be.
692 *
693 * Return: The zstd streaming decompression context.
694 */
695 ZSTD_DStream *ZSTD_initDStream(size_t maxWindowSize, void *workspace,
696 size_t workspaceSize);
697 /**
698 * ZSTD_initDStream_usingDDict() - initialize streaming decompression context
699 * @maxWindowSize: The maximum window size allowed for compressed frames.
700 * @ddict: The digested dictionary to use for decompression.
701 * @workspace: The workspace to emplace the context into. It must outlive
702 * the returned context.
703 * @workspaceSize: The size of workspace.
704 * Use ZSTD_DStreamWorkspaceBound(maxWindowSize) to determine
705 * how large the workspace must be.
706 *
707 * Return: The zstd streaming decompression context.
708 */
709 ZSTD_DStream *ZSTD_initDStream_usingDDict(size_t maxWindowSize,
710 const ZSTD_DDict *ddict, void *workspace, size_t workspaceSize);
711
712 /*===== Streaming decompression functions =====*/
713 /**
714 * ZSTD_resetDStream() - reset the context using parameters from creation
715 * @zds: The zstd streaming decompression context to reset.
716 *
717 * Resets the context using the parameters from creation. Skips dictionary
718 * loading, since it can be reused.
719 *
720 * Return: Zero or an error, which can be checked using ZSTD_isError().
721 */
722 size_t ZSTD_resetDStream(ZSTD_DStream *zds);
723 /**
724 * ZSTD_decompressStream() - streaming decompress some of input into output
725 * @zds: The zstd streaming decompression context.
726 * @output: Destination buffer. `output.pos` is updated to indicate how much
727 * decompressed data was written.
728 * @input: Source buffer. `input.pos` is updated to indicate how much data was
729 * read. Note that it may not consume the entire input, in which case
730 * `input.pos < input.size`, and it's up to the caller to present
731 * remaining data again.
732 *
733 * The `input` and `output` buffers may be any size. Guaranteed to make some
734 * forward progress if `input` and `output` are not empty.
735 * ZSTD_decompressStream() will not consume the last byte of the frame until
736 * the entire frame is flushed.
737 *
738 * Return: Returns 0 iff a frame is completely decoded and fully flushed.
739 * Otherwise returns a hint for the number of bytes to use as the input
740 * for the next function call or an error, which can be checked using
741 * ZSTD_isError(). The size hint will never load more than the frame.
742 */
743 size_t ZSTD_decompressStream(ZSTD_DStream *zds, ZSTD_outBuffer *output,
744 ZSTD_inBuffer *input);
745
746 /**
747 * ZSTD_DStreamInSize() - recommended size for the input buffer
748 *
749 * Return: The recommended size for the input buffer.
750 */
751 size_t ZSTD_DStreamInSize(void);
752 /**
753 * ZSTD_DStreamOutSize() - recommended size for the output buffer
754 *
755 * When the output buffer is at least this large, it is guaranteed to be large
756 * enough to flush at least one complete decompressed block.
757 *
758 * Return: The recommended size for the output buffer.
759 */
760 size_t ZSTD_DStreamOutSize(void);
761
762
763 /* --- Constants ---*/
764 #define ZSTD_MAGICNUMBER 0xFD2FB528 /* >= v0.8.0 */
765 #define ZSTD_MAGIC_SKIPPABLE_START 0x184D2A50U
766
767 #define ZSTD_CONTENTSIZE_UNKNOWN (0ULL - 1)
768 #define ZSTD_CONTENTSIZE_ERROR (0ULL - 2)
769
770 #define ZSTD_WINDOWLOG_MAX_32 27
771 #define ZSTD_WINDOWLOG_MAX_64 27
772 #define ZSTD_WINDOWLOG_MAX \
773 ((unsigned int)(sizeof(size_t) == 4 \
774 ? ZSTD_WINDOWLOG_MAX_32 \
775 : ZSTD_WINDOWLOG_MAX_64))
776 #define ZSTD_WINDOWLOG_MIN 10
777 #define ZSTD_HASHLOG_MAX ZSTD_WINDOWLOG_MAX
778 #define ZSTD_HASHLOG_MIN 6
779 #define ZSTD_CHAINLOG_MAX (ZSTD_WINDOWLOG_MAX+1)
780 #define ZSTD_CHAINLOG_MIN ZSTD_HASHLOG_MIN
781 #define ZSTD_HASHLOG3_MAX 17
782 #define ZSTD_SEARCHLOG_MAX (ZSTD_WINDOWLOG_MAX-1)
783 #define ZSTD_SEARCHLOG_MIN 1
784 /* only for ZSTD_fast, other strategies are limited to 6 */
785 #define ZSTD_SEARCHLENGTH_MAX 7
786 /* only for ZSTD_btopt, other strategies are limited to 4 */
787 #define ZSTD_SEARCHLENGTH_MIN 3
788 #define ZSTD_TARGETLENGTH_MIN 4
789 #define ZSTD_TARGETLENGTH_MAX 999
790
791 /* for static allocation */
792 #define ZSTD_FRAMEHEADERSIZE_MAX 18
793 #define ZSTD_FRAMEHEADERSIZE_MIN 6
794 static const size_t ZSTD_frameHeaderSize_prefix = 5;
795 static const size_t ZSTD_frameHeaderSize_min = ZSTD_FRAMEHEADERSIZE_MIN;
796 static const size_t ZSTD_frameHeaderSize_max = ZSTD_FRAMEHEADERSIZE_MAX;
797 /* magic number + skippable frame length */
798 static const size_t ZSTD_skippableHeaderSize = 8;
799
800
801 /*-*************************************
802 * Compressed size functions
803 **************************************/
804
805 /**
806 * ZSTD_findFrameCompressedSize() - returns the size of a compressed frame
807 * @src: Source buffer. It should point to the start of a zstd encoded frame
808 * or a skippable frame.
809 * @srcSize: The size of the source buffer. It must be at least as large as the
810 * size of the frame.
811 *
812 * Return: The compressed size of the frame pointed to by `src` or an error,
813 * which can be check with ZSTD_isError().
814 * Suitable to pass to ZSTD_decompress() or similar functions.
815 */
816 size_t ZSTD_findFrameCompressedSize(const void *src, size_t srcSize);
817
818 /*-*************************************
819 * Decompressed size functions
820 **************************************/
821 /**
822 * ZSTD_getFrameContentSize() - returns the content size in a zstd frame header
823 * @src: It should point to the start of a zstd encoded frame.
824 * @srcSize: The size of the source buffer. It must be at least as large as the
825 * frame header. `ZSTD_frameHeaderSize_max` is always large enough.
826 *
827 * Return: The frame content size stored in the frame header if known.
828 * `ZSTD_CONTENTSIZE_UNKNOWN` if the content size isn't stored in the
829 * frame header. `ZSTD_CONTENTSIZE_ERROR` on invalid input.
830 */
831 unsigned long long ZSTD_getFrameContentSize(const void *src, size_t srcSize);
832
833 /**
834 * ZSTD_findDecompressedSize() - returns decompressed size of a series of frames
835 * @src: It should point to the start of a series of zstd encoded and/or
836 * skippable frames.
837 * @srcSize: The exact size of the series of frames.
838 *
839 * If any zstd encoded frame in the series doesn't have the frame content size
840 * set, `ZSTD_CONTENTSIZE_UNKNOWN` is returned. But frame content size is always
841 * set when using ZSTD_compress(). The decompressed size can be very large.
842 * If the source is untrusted, the decompressed size could be wrong or
843 * intentionally modified. Always ensure the result fits within the
844 * application's authorized limits. ZSTD_findDecompressedSize() handles multiple
845 * frames, and so it must traverse the input to read each frame header. This is
846 * efficient as most of the data is skipped, however it does mean that all frame
847 * data must be present and valid.
848 *
849 * Return: Decompressed size of all the data contained in the frames if known.
850 * `ZSTD_CONTENTSIZE_UNKNOWN` if the decompressed size is unknown.
851 * `ZSTD_CONTENTSIZE_ERROR` if an error occurred.
852 */
853 unsigned long long ZSTD_findDecompressedSize(const void *src, size_t srcSize);
854
855 /*-*************************************
856 * Advanced compression functions
857 **************************************/
858 /**
859 * ZSTD_checkCParams() - ensure parameter values remain within authorized range
860 * @cParams: The zstd compression parameters.
861 *
862 * Return: Zero or an error, which can be checked using ZSTD_isError().
863 */
864 size_t ZSTD_checkCParams(ZSTD_compressionParameters cParams);
865
866 /**
867 * ZSTD_adjustCParams() - optimize parameters for a given srcSize and dictSize
868 * @srcSize: Optionally the estimated source size, or zero if unknown.
869 * @dictSize: Optionally the estimated dictionary size, or zero if unknown.
870 *
871 * Return: The optimized parameters.
872 */
873 ZSTD_compressionParameters ZSTD_adjustCParams(
874 ZSTD_compressionParameters cParams, unsigned long long srcSize,
875 size_t dictSize);
876
877 /*--- Advanced decompression functions ---*/
878
879 /**
880 * ZSTD_isFrame() - returns true iff the buffer starts with a valid frame
881 * @buffer: The source buffer to check.
882 * @size: The size of the source buffer, must be at least 4 bytes.
883 *
884 * Return: True iff the buffer starts with a zstd or skippable frame identifier.
885 */
886 unsigned int ZSTD_isFrame(const void *buffer, size_t size);
887
888 /**
889 * ZSTD_getDictID_fromDict() - returns the dictionary id stored in a dictionary
890 * @dict: The dictionary buffer.
891 * @dictSize: The size of the dictionary buffer.
892 *
893 * Return: The dictionary id stored within the dictionary or 0 if the
894 * dictionary is not a zstd dictionary. If it returns 0 the
895 * dictionary can still be loaded as a content-only dictionary.
896 */
897 unsigned int ZSTD_getDictID_fromDict(const void *dict, size_t dictSize);
898
899 /**
900 * ZSTD_getDictID_fromDDict() - returns the dictionary id stored in a ZSTD_DDict
901 * @ddict: The ddict to find the id of.
902 *
903 * Return: The dictionary id stored within `ddict` or 0 if the dictionary is not
904 * a zstd dictionary. If it returns 0 `ddict` will be loaded as a
905 * content-only dictionary.
906 */
907 unsigned int ZSTD_getDictID_fromDDict(const ZSTD_DDict *ddict);
908
909 /**
910 * ZSTD_getDictID_fromFrame() - returns the dictionary id stored in a zstd frame
911 * @src: Source buffer. It must be a zstd encoded frame.
912 * @srcSize: The size of the source buffer. It must be at least as large as the
913 * frame header. `ZSTD_frameHeaderSize_max` is always large enough.
914 *
915 * Return: The dictionary id required to decompress the frame stored within
916 * `src` or 0 if the dictionary id could not be decoded. It can return
917 * 0 if the frame does not require a dictionary, the dictionary id
918 * wasn't stored in the frame, `src` is not a zstd frame, or `srcSize`
919 * is too small.
920 */
921 unsigned int ZSTD_getDictID_fromFrame(const void *src, size_t srcSize);
922
923 /**
924 * struct ZSTD_frameParams - zstd frame parameters stored in the frame header
925 * @frameContentSize: The frame content size, or 0 if not present.
926 * @windowSize: The window size, or 0 if the frame is a skippable frame.
927 * @dictID: The dictionary id, or 0 if not present.
928 * @checksumFlag: Whether a checksum was used.
929 */
930 typedef struct {
931 unsigned long long frameContentSize;
932 unsigned int windowSize;
933 unsigned int dictID;
934 unsigned int checksumFlag;
935 } ZSTD_frameParams;
936
937 /**
938 * ZSTD_getFrameParams() - extracts parameters from a zstd or skippable frame
939 * @fparamsPtr: On success the frame parameters are written here.
940 * @src: The source buffer. It must point to a zstd or skippable frame.
941 * @srcSize: The size of the source buffer. `ZSTD_frameHeaderSize_max` is
942 * always large enough to succeed.
943 *
944 * Return: 0 on success. If more data is required it returns how many bytes
945 * must be provided to make forward progress. Otherwise it returns
946 * an error, which can be checked using ZSTD_isError().
947 */
948 size_t ZSTD_getFrameParams(ZSTD_frameParams *fparamsPtr, const void *src,
949 size_t srcSize);
950
951 /*-*****************************************************************************
952 * Buffer-less and synchronous inner streaming functions
953 *
954 * This is an advanced API, giving full control over buffer management, for
955 * users which need direct control over memory.
956 * But it's also a complex one, with many restrictions (documented below).
957 * Prefer using normal streaming API for an easier experience
958 ******************************************************************************/
959
960 /*-*****************************************************************************
961 * Buffer-less streaming compression (synchronous mode)
962 *
963 * A ZSTD_CCtx object is required to track streaming operations.
964 * Use ZSTD_initCCtx() to initialize a context.
965 * ZSTD_CCtx object can be re-used multiple times within successive compression
966 * operations.
967 *
968 * Start by initializing a context.
969 * Use ZSTD_compressBegin(), or ZSTD_compressBegin_usingDict() for dictionary
970 * compression,
971 * or ZSTD_compressBegin_advanced(), for finer parameter control.
972 * It's also possible to duplicate a reference context which has already been
973 * initialized, using ZSTD_copyCCtx()
974 *
975 * Then, consume your input using ZSTD_compressContinue().
976 * There are some important considerations to keep in mind when using this
977 * advanced function :
978 * - ZSTD_compressContinue() has no internal buffer. It uses externally provided
979 * buffer only.
980 * - Interface is synchronous : input is consumed entirely and produce 1+
981 * (or more) compressed blocks.
982 * - Caller must ensure there is enough space in `dst` to store compressed data
983 * under worst case scenario. Worst case evaluation is provided by
984 * ZSTD_compressBound().
985 * ZSTD_compressContinue() doesn't guarantee recover after a failed
986 * compression.
987 * - ZSTD_compressContinue() presumes prior input ***is still accessible and
988 * unmodified*** (up to maximum distance size, see WindowLog).
989 * It remembers all previous contiguous blocks, plus one separated memory
990 * segment (which can itself consists of multiple contiguous blocks)
991 * - ZSTD_compressContinue() detects that prior input has been overwritten when
992 * `src` buffer overlaps. In which case, it will "discard" the relevant memory
993 * section from its history.
994 *
995 * Finish a frame with ZSTD_compressEnd(), which will write the last block(s)
996 * and optional checksum. It's possible to use srcSize==0, in which case, it
997 * will write a final empty block to end the frame. Without last block mark,
998 * frames will be considered unfinished (corrupted) by decoders.
999 *
1000 * `ZSTD_CCtx` object can be re-used (ZSTD_compressBegin()) to compress some new
1001 * frame.
1002 ******************************************************************************/
1003
1004 /*===== Buffer-less streaming compression functions =====*/
1005 size_t ZSTD_compressBegin(ZSTD_CCtx *cctx, int compressionLevel);
1006 size_t ZSTD_compressBegin_usingDict(ZSTD_CCtx *cctx, const void *dict,
1007 size_t dictSize, int compressionLevel);
1008 size_t ZSTD_compressBegin_advanced(ZSTD_CCtx *cctx, const void *dict,
1009 size_t dictSize, ZSTD_parameters params,
1010 unsigned long long pledgedSrcSize);
1011 size_t ZSTD_copyCCtx(ZSTD_CCtx *cctx, const ZSTD_CCtx *preparedCCtx,
1012 unsigned long long pledgedSrcSize);
1013 size_t ZSTD_compressBegin_usingCDict(ZSTD_CCtx *cctx, const ZSTD_CDict *cdict,
1014 unsigned long long pledgedSrcSize);
1015 size_t ZSTD_compressContinue(ZSTD_CCtx *cctx, void *dst, size_t dstCapacity,
1016 const void *src, size_t srcSize);
1017 size_t ZSTD_compressEnd(ZSTD_CCtx *cctx, void *dst, size_t dstCapacity,
1018 const void *src, size_t srcSize);
1019
1020
1021
1022 /*-*****************************************************************************
1023 * Buffer-less streaming decompression (synchronous mode)
1024 *
1025 * A ZSTD_DCtx object is required to track streaming operations.
1026 * Use ZSTD_initDCtx() to initialize a context.
1027 * A ZSTD_DCtx object can be re-used multiple times.
1028 *
1029 * First typical operation is to retrieve frame parameters, using
1030 * ZSTD_getFrameParams(). It fills a ZSTD_frameParams structure which provide
1031 * important information to correctly decode the frame, such as the minimum
1032 * rolling buffer size to allocate to decompress data (`windowSize`), and the
1033 * dictionary ID used.
1034 * Note: content size is optional, it may not be present. 0 means unknown.
1035 * Note that these values could be wrong, either because of data malformation,
1036 * or because an attacker is spoofing deliberate false information. As a
1037 * consequence, check that values remain within valid application range,
1038 * especially `windowSize`, before allocation. Each application can set its own
1039 * limit, depending on local restrictions. For extended interoperability, it is
1040 * recommended to support at least 8 MB.
1041 * Frame parameters are extracted from the beginning of the compressed frame.
1042 * Data fragment must be large enough to ensure successful decoding, typically
1043 * `ZSTD_frameHeaderSize_max` bytes.
1044 * Result: 0: successful decoding, the `ZSTD_frameParams` structure is filled.
1045 * >0: `srcSize` is too small, provide at least this many bytes.
1046 * errorCode, which can be tested using ZSTD_isError().
1047 *
1048 * Start decompression, with ZSTD_decompressBegin() or
1049 * ZSTD_decompressBegin_usingDict(). Alternatively, you can copy a prepared
1050 * context, using ZSTD_copyDCtx().
1051 *
1052 * Then use ZSTD_nextSrcSizeToDecompress() and ZSTD_decompressContinue()
1053 * alternatively.
1054 * ZSTD_nextSrcSizeToDecompress() tells how many bytes to provide as 'srcSize'
1055 * to ZSTD_decompressContinue().
1056 * ZSTD_decompressContinue() requires this _exact_ amount of bytes, or it will
1057 * fail.
1058 *
1059 * The result of ZSTD_decompressContinue() is the number of bytes regenerated
1060 * within 'dst' (necessarily <= dstCapacity). It can be zero, which is not an
1061 * error; it just means ZSTD_decompressContinue() has decoded some metadata
1062 * item. It can also be an error code, which can be tested with ZSTD_isError().
1063 *
1064 * ZSTD_decompressContinue() needs previous data blocks during decompression, up
1065 * to `windowSize`. They should preferably be located contiguously, prior to
1066 * current block. Alternatively, a round buffer of sufficient size is also
1067 * possible. Sufficient size is determined by frame parameters.
1068 * ZSTD_decompressContinue() is very sensitive to contiguity, if 2 blocks don't
1069 * follow each other, make sure that either the compressor breaks contiguity at
1070 * the same place, or that previous contiguous segment is large enough to
1071 * properly handle maximum back-reference.
1072 *
1073 * A frame is fully decoded when ZSTD_nextSrcSizeToDecompress() returns zero.
1074 * Context can then be reset to start a new decompression.
1075 *
1076 * Note: it's possible to know if next input to present is a header or a block,
1077 * using ZSTD_nextInputType(). This information is not required to properly
1078 * decode a frame.
1079 *
1080 * == Special case: skippable frames ==
1081 *
1082 * Skippable frames allow integration of user-defined data into a flow of
1083 * concatenated frames. Skippable frames will be ignored (skipped) by a
1084 * decompressor. The format of skippable frames is as follows:
1085 * a) Skippable frame ID - 4 Bytes, Little endian format, any value from
1086 * 0x184D2A50 to 0x184D2A5F
1087 * b) Frame Size - 4 Bytes, Little endian format, unsigned 32-bits
1088 * c) Frame Content - any content (User Data) of length equal to Frame Size
1089 * For skippable frames ZSTD_decompressContinue() always returns 0.
1090 * For skippable frames ZSTD_getFrameParams() returns fparamsPtr->windowLog==0
1091 * what means that a frame is skippable.
1092 * Note: If fparamsPtr->frameContentSize==0, it is ambiguous: the frame might
1093 * actually be a zstd encoded frame with no content. For purposes of
1094 * decompression, it is valid in both cases to skip the frame using
1095 * ZSTD_findFrameCompressedSize() to find its size in bytes.
1096 * It also returns frame size as fparamsPtr->frameContentSize.
1097 ******************************************************************************/
1098
1099 /*===== Buffer-less streaming decompression functions =====*/
1100 size_t ZSTD_decompressBegin(ZSTD_DCtx *dctx);
1101 size_t ZSTD_decompressBegin_usingDict(ZSTD_DCtx *dctx, const void *dict,
1102 size_t dictSize);
1103 void ZSTD_copyDCtx(ZSTD_DCtx *dctx, const ZSTD_DCtx *preparedDCtx);
1104 size_t ZSTD_nextSrcSizeToDecompress(ZSTD_DCtx *dctx);
1105 size_t ZSTD_decompressContinue(ZSTD_DCtx *dctx, void *dst, size_t dstCapacity,
1106 const void *src, size_t srcSize);
1107 typedef enum {
1108 ZSTDnit_frameHeader,
1109 ZSTDnit_blockHeader,
1110 ZSTDnit_block,
1111 ZSTDnit_lastBlock,
1112 ZSTDnit_checksum,
1113 ZSTDnit_skippableFrame
1114 } ZSTD_nextInputType_e;
1115 ZSTD_nextInputType_e ZSTD_nextInputType(ZSTD_DCtx *dctx);
1116
1117 /*-*****************************************************************************
1118 * Block functions
1119 *
1120 * Block functions produce and decode raw zstd blocks, without frame metadata.
1121 * Frame metadata cost is typically ~18 bytes, which can be non-negligible for
1122 * very small blocks (< 100 bytes). User will have to take in charge required
1123 * information to regenerate data, such as compressed and content sizes.
1124 *
1125 * A few rules to respect:
1126 * - Compressing and decompressing require a context structure
1127 * + Use ZSTD_initCCtx() and ZSTD_initDCtx()
1128 * - It is necessary to init context before starting
1129 * + compression : ZSTD_compressBegin()
1130 * + decompression : ZSTD_decompressBegin()
1131 * + variants _usingDict() are also allowed
1132 * + copyCCtx() and copyDCtx() work too
1133 * - Block size is limited, it must be <= ZSTD_getBlockSizeMax()
1134 * + If you need to compress more, cut data into multiple blocks
1135 * + Consider using the regular ZSTD_compress() instead, as frame metadata
1136 * costs become negligible when source size is large.
1137 * - When a block is considered not compressible enough, ZSTD_compressBlock()
1138 * result will be zero. In which case, nothing is produced into `dst`.
1139 * + User must test for such outcome and deal directly with uncompressed data
1140 * + ZSTD_decompressBlock() doesn't accept uncompressed data as input!!!
1141 * + In case of multiple successive blocks, decoder must be informed of
1142 * uncompressed block existence to follow proper history. Use
1143 * ZSTD_insertBlock() in such a case.
1144 ******************************************************************************/
1145
1146 /* Define for static allocation */
1147 #define ZSTD_BLOCKSIZE_ABSOLUTEMAX (128 * 1024)
1148 /*===== Raw zstd block functions =====*/
1149 size_t ZSTD_getBlockSizeMax(ZSTD_CCtx *cctx);
1150 size_t ZSTD_compressBlock(ZSTD_CCtx *cctx, void *dst, size_t dstCapacity,
1151 const void *src, size_t srcSize);
1152 size_t ZSTD_decompressBlock(ZSTD_DCtx *dctx, void *dst, size_t dstCapacity,
1153 const void *src, size_t srcSize);
1154 size_t ZSTD_insertBlock(ZSTD_DCtx *dctx, const void *blockStart,
1155 size_t blockSize);
1156
1157 #endif /* ZSTD_H */