include/linux/zstd.h

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