include/linux/zstd.h

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