~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

TOMOYO Linux Cross Reference
Linux/include/linux/zstd.h

Version: ~ [ linux-5.2 ] ~ [ linux-5.1.16 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.57 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.132 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.184 ] ~ [ linux-4.8.17 ] ~ [ linux-4.7.10 ] ~ [ linux-4.6.7 ] ~ [ linux-4.5.7 ] ~ [ linux-4.4.184 ] ~ [ linux-4.3.6 ] ~ [ linux-4.2.8 ] ~ [ linux-4.1.52 ] ~ [ linux-4.0.9 ] ~ [ linux-3.19.8 ] ~ [ linux-3.18.140 ] ~ [ linux-3.17.8 ] ~ [ linux-3.16.69 ] ~ [ linux-3.15.10 ] ~ [ linux-3.14.79 ] ~ [ linux-3.13.11 ] ~ [ linux-3.12.74 ] ~ [ linux-3.11.10 ] ~ [ linux-3.10.108 ] ~ [ linux-3.9.11 ] ~ [ linux-3.8.13 ] ~ [ linux-3.7.10 ] ~ [ linux-3.6.11 ] ~ [ linux-3.5.7 ] ~ [ linux-3.4.113 ] ~ [ linux-3.3.8 ] ~ [ linux-3.2.102 ] ~ [ linux-3.1.10 ] ~ [ linux-3.0.101 ] ~ [ linux-2.6.39.4 ] ~ [ linux-2.6.38.8 ] ~ [ linux-2.6.37.6 ] ~ [ linux-2.6.36.4 ] ~ [ linux-2.6.35.14 ] ~ [ linux-2.6.34.15 ] ~ [ linux-2.6.33.20 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.5 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

  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 */
1158 

~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

kernel.org | git.kernel.org | LWN.net | Project Home | Wiki (Japanese) | Wiki (English) | SVN repository | Mail admin

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

osdn.jp