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