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 #define ZSTD_frameHeaderSize_prefix 5 795 #define ZSTD_frameHeaderSize_min ZSTD_FRAMEHEADERSIZE_MIN 796 #define ZSTD_frameHeaderSize_max ZSTD_FRAMEHEADERSIZE_MAX 797 /* magic number + skippable frame length */ 798 #define ZSTD_skippableHeaderSize 8 799 800 801 /*-************************************* 802 * Compressed size functions 803 **************************************/ 804 805 /** 806 * ZSTD_findFrameCompressedSize() - returns the size of a compressed frame 807 * @src: Source buffer. It should point to the start of a zstd encoded frame 808 * or a skippable frame. 809 * @srcSize: The size of the source buffer. It must be at least as large as the 810 * size of the frame. 811 * 812 * Return: The compressed size of the frame pointed to by `src` or an error, 813 * which can be check with ZSTD_isError(). 814 * Suitable to pass to ZSTD_decompress() or similar functions. 815 */ 816 size_t ZSTD_findFrameCompressedSize(const void *src, size_t srcSize); 817 818 /*-************************************* 819 * Decompressed size functions 820 **************************************/ 821 /** 822 * ZSTD_getFrameContentSize() - returns the content size in a zstd frame header 823 * @src: It should point to the start of a zstd encoded frame. 824 * @srcSize: The size of the source buffer. It must be at least as large as the 825 * frame header. `ZSTD_frameHeaderSize_max` is always large enough. 826 * 827 * Return: The frame content size stored in the frame header if known. 828 * `ZSTD_CONTENTSIZE_UNKNOWN` if the content size isn't stored in the 829 * frame header. `ZSTD_CONTENTSIZE_ERROR` on invalid input. 830 */ 831 unsigned long long ZSTD_getFrameContentSize(const void *src, size_t srcSize); 832 833 /** 834 * ZSTD_findDecompressedSize() - returns decompressed size of a series of frames 835 * @src: It should point to the start of a series of zstd encoded and/or 836 * skippable frames. 837 * @srcSize: The exact size of the series of frames. 838 * 839 * If any zstd encoded frame in the series doesn't have the frame content size 840 * set, `ZSTD_CONTENTSIZE_UNKNOWN` is returned. But frame content size is always 841 * set when using ZSTD_compress(). The decompressed size can be very large. 842 * If the source is untrusted, the decompressed size could be wrong or 843 * intentionally modified. Always ensure the result fits within the 844 * application's authorized limits. ZSTD_findDecompressedSize() handles multiple 845 * frames, and so it must traverse the input to read each frame header. This is 846 * efficient as most of the data is skipped, however it does mean that all frame 847 * data must be present and valid. 848 * 849 * Return: Decompressed size of all the data contained in the frames if known. 850 * `ZSTD_CONTENTSIZE_UNKNOWN` if the decompressed size is unknown. 851 * `ZSTD_CONTENTSIZE_ERROR` if an error occurred. 852 */ 853 unsigned long long ZSTD_findDecompressedSize(const void *src, size_t srcSize); 854 855 /*-************************************* 856 * Advanced compression functions 857 **************************************/ 858 /** 859 * ZSTD_checkCParams() - ensure parameter values remain within authorized range 860 * @cParams: The zstd compression parameters. 861 * 862 * Return: Zero or an error, which can be checked using ZSTD_isError(). 863 */ 864 size_t ZSTD_checkCParams(ZSTD_compressionParameters cParams); 865 866 /** 867 * ZSTD_adjustCParams() - optimize parameters for a given srcSize and dictSize 868 * @srcSize: Optionally the estimated source size, or zero if unknown. 869 * @dictSize: Optionally the estimated dictionary size, or zero if unknown. 870 * 871 * Return: The optimized parameters. 872 */ 873 ZSTD_compressionParameters ZSTD_adjustCParams( 874 ZSTD_compressionParameters cParams, unsigned long long srcSize, 875 size_t dictSize); 876 877 /*--- Advanced decompression functions ---*/ 878 879 /** 880 * ZSTD_isFrame() - returns true iff the buffer starts with a valid frame 881 * @buffer: The source buffer to check. 882 * @size: The size of the source buffer, must be at least 4 bytes. 883 * 884 * Return: True iff the buffer starts with a zstd or skippable frame identifier. 885 */ 886 unsigned int ZSTD_isFrame(const void *buffer, size_t size); 887 888 /** 889 * ZSTD_getDictID_fromDict() - returns the dictionary id stored in a dictionary 890 * @dict: The dictionary buffer. 891 * @dictSize: The size of the dictionary buffer. 892 * 893 * Return: The dictionary id stored within the dictionary or 0 if the 894 * dictionary is not a zstd dictionary. If it returns 0 the 895 * dictionary can still be loaded as a content-only dictionary. 896 */ 897 unsigned int ZSTD_getDictID_fromDict(const void *dict, size_t dictSize); 898 899 /** 900 * ZSTD_getDictID_fromDDict() - returns the dictionary id stored in a ZSTD_DDict 901 * @ddict: The ddict to find the id of. 902 * 903 * Return: The dictionary id stored within `ddict` or 0 if the dictionary is not 904 * a zstd dictionary. If it returns 0 `ddict` will be loaded as a 905 * content-only dictionary. 906 */ 907 unsigned int ZSTD_getDictID_fromDDict(const ZSTD_DDict *ddict); 908 909 /** 910 * ZSTD_getDictID_fromFrame() - returns the dictionary id stored in a zstd frame 911 * @src: Source buffer. It must be a zstd encoded frame. 912 * @srcSize: The size of the source buffer. It must be at least as large as the 913 * frame header. `ZSTD_frameHeaderSize_max` is always large enough. 914 * 915 * Return: The dictionary id required to decompress the frame stored within 916 * `src` or 0 if the dictionary id could not be decoded. It can return 917 * 0 if the frame does not require a dictionary, the dictionary id 918 * wasn't stored in the frame, `src` is not a zstd frame, or `srcSize` 919 * is too small. 920 */ 921 unsigned int ZSTD_getDictID_fromFrame(const void *src, size_t srcSize); 922 923 /** 924 * struct ZSTD_frameParams - zstd frame parameters stored in the frame header 925 * @frameContentSize: The frame content size, or 0 if not present. 926 * @windowSize: The window size, or 0 if the frame is a skippable frame. 927 * @dictID: The dictionary id, or 0 if not present. 928 * @checksumFlag: Whether a checksum was used. 929 */ 930 typedef struct { 931 unsigned long long frameContentSize; 932 unsigned int windowSize; 933 unsigned int dictID; 934 unsigned int checksumFlag; 935 } ZSTD_frameParams; 936 937 /** 938 * ZSTD_getFrameParams() - extracts parameters from a zstd or skippable frame 939 * @fparamsPtr: On success the frame parameters are written here. 940 * @src: The source buffer. It must point to a zstd or skippable frame. 941 * @srcSize: The size of the source buffer. `ZSTD_frameHeaderSize_max` is 942 * always large enough to succeed. 943 * 944 * Return: 0 on success. If more data is required it returns how many bytes 945 * must be provided to make forward progress. Otherwise it returns 946 * an error, which can be checked using ZSTD_isError(). 947 */ 948 size_t ZSTD_getFrameParams(ZSTD_frameParams *fparamsPtr, const void *src, 949 size_t srcSize); 950 951 /*-***************************************************************************** 952 * Buffer-less and synchronous inner streaming functions 953 * 954 * This is an advanced API, giving full control over buffer management, for 955 * users which need direct control over memory. 956 * But it's also a complex one, with many restrictions (documented below). 957 * Prefer using normal streaming API for an easier experience 958 ******************************************************************************/ 959 960 /*-***************************************************************************** 961 * Buffer-less streaming compression (synchronous mode) 962 * 963 * A ZSTD_CCtx object is required to track streaming operations. 964 * Use ZSTD_initCCtx() to initialize a context. 965 * ZSTD_CCtx object can be re-used multiple times within successive compression 966 * operations. 967 * 968 * Start by initializing a context. 969 * Use ZSTD_compressBegin(), or ZSTD_compressBegin_usingDict() for dictionary 970 * compression, 971 * or ZSTD_compressBegin_advanced(), for finer parameter control. 972 * It's also possible to duplicate a reference context which has already been 973 * initialized, using ZSTD_copyCCtx() 974 * 975 * Then, consume your input using ZSTD_compressContinue(). 976 * There are some important considerations to keep in mind when using this 977 * advanced function : 978 * - ZSTD_compressContinue() has no internal buffer. It uses externally provided 979 * buffer only. 980 * - Interface is synchronous : input is consumed entirely and produce 1+ 981 * (or more) compressed blocks. 982 * - Caller must ensure there is enough space in `dst` to store compressed data 983 * under worst case scenario. Worst case evaluation is provided by 984 * ZSTD_compressBound(). 985 * ZSTD_compressContinue() doesn't guarantee recover after a failed 986 * compression. 987 * - ZSTD_compressContinue() presumes prior input ***is still accessible and 988 * unmodified*** (up to maximum distance size, see WindowLog). 989 * It remembers all previous contiguous blocks, plus one separated memory 990 * segment (which can itself consists of multiple contiguous blocks) 991 * - ZSTD_compressContinue() detects that prior input has been overwritten when 992 * `src` buffer overlaps. In which case, it will "discard" the relevant memory 993 * section from its history. 994 * 995 * Finish a frame with ZSTD_compressEnd(), which will write the last block(s) 996 * and optional checksum. It's possible to use srcSize==0, in which case, it 997 * will write a final empty block to end the frame. Without last block mark, 998 * frames will be considered unfinished (corrupted) by decoders. 999 * 1000 * `ZSTD_CCtx` object can be re-used (ZSTD_compressBegin()) to compress some new 1001 * frame. 1002 ******************************************************************************/ 1003 1004 /*===== Buffer-less streaming compression functions =====*/ 1005 size_t ZSTD_compressBegin(ZSTD_CCtx *cctx, int compressionLevel); 1006 size_t ZSTD_compressBegin_usingDict(ZSTD_CCtx *cctx, const void *dict, 1007 size_t dictSize, int compressionLevel); 1008 size_t ZSTD_compressBegin_advanced(ZSTD_CCtx *cctx, const void *dict, 1009 size_t dictSize, ZSTD_parameters params, 1010 unsigned long long pledgedSrcSize); 1011 size_t ZSTD_copyCCtx(ZSTD_CCtx *cctx, const ZSTD_CCtx *preparedCCtx, 1012 unsigned long long pledgedSrcSize); 1013 size_t ZSTD_compressBegin_usingCDict(ZSTD_CCtx *cctx, const ZSTD_CDict *cdict, 1014 unsigned long long pledgedSrcSize); 1015 size_t ZSTD_compressContinue(ZSTD_CCtx *cctx, void *dst, size_t dstCapacity, 1016 const void *src, size_t srcSize); 1017 size_t ZSTD_compressEnd(ZSTD_CCtx *cctx, void *dst, size_t dstCapacity, 1018 const void *src, size_t srcSize); 1019 1020 1021 1022 /*-***************************************************************************** 1023 * Buffer-less streaming decompression (synchronous mode) 1024 * 1025 * A ZSTD_DCtx object is required to track streaming operations. 1026 * Use ZSTD_initDCtx() to initialize a context. 1027 * A ZSTD_DCtx object can be re-used multiple times. 1028 * 1029 * First typical operation is to retrieve frame parameters, using 1030 * ZSTD_getFrameParams(). It fills a ZSTD_frameParams structure which provide 1031 * important information to correctly decode the frame, such as the minimum 1032 * rolling buffer size to allocate to decompress data (`windowSize`), and the 1033 * dictionary ID used. 1034 * Note: content size is optional, it may not be present. 0 means unknown. 1035 * Note that these values could be wrong, either because of data malformation, 1036 * or because an attacker is spoofing deliberate false information. As a 1037 * consequence, check that values remain within valid application range, 1038 * especially `windowSize`, before allocation. Each application can set its own 1039 * limit, depending on local restrictions. For extended interoperability, it is 1040 * recommended to support at least 8 MB. 1041 * Frame parameters are extracted from the beginning of the compressed frame. 1042 * Data fragment must be large enough to ensure successful decoding, typically 1043 * `ZSTD_frameHeaderSize_max` bytes. 1044 * Result: 0: successful decoding, the `ZSTD_frameParams` structure is filled. 1045 * >0: `srcSize` is too small, provide at least this many bytes. 1046 * errorCode, which can be tested using ZSTD_isError(). 1047 * 1048 * Start decompression, with ZSTD_decompressBegin() or 1049 * ZSTD_decompressBegin_usingDict(). Alternatively, you can copy a prepared 1050 * context, using ZSTD_copyDCtx(). 1051 * 1052 * Then use ZSTD_nextSrcSizeToDecompress() and ZSTD_decompressContinue() 1053 * alternatively. 1054 * ZSTD_nextSrcSizeToDecompress() tells how many bytes to provide as 'srcSize' 1055 * to ZSTD_decompressContinue(). 1056 * ZSTD_decompressContinue() requires this _exact_ amount of bytes, or it will 1057 * fail. 1058 * 1059 * The result of ZSTD_decompressContinue() is the number of bytes regenerated 1060 * within 'dst' (necessarily <= dstCapacity). It can be zero, which is not an 1061 * error; it just means ZSTD_decompressContinue() has decoded some metadata 1062 * item. It can also be an error code, which can be tested with ZSTD_isError(). 1063 * 1064 * ZSTD_decompressContinue() needs previous data blocks during decompression, up 1065 * to `windowSize`. They should preferably be located contiguously, prior to 1066 * current block. Alternatively, a round buffer of sufficient size is also 1067 * possible. Sufficient size is determined by frame parameters. 1068 * ZSTD_decompressContinue() is very sensitive to contiguity, if 2 blocks don't 1069 * follow each other, make sure that either the compressor breaks contiguity at 1070 * the same place, or that previous contiguous segment is large enough to 1071 * properly handle maximum back-reference. 1072 * 1073 * A frame is fully decoded when ZSTD_nextSrcSizeToDecompress() returns zero. 1074 * Context can then be reset to start a new decompression. 1075 * 1076 * Note: it's possible to know if next input to present is a header or a block, 1077 * using ZSTD_nextInputType(). This information is not required to properly 1078 * decode a frame. 1079 * 1080 * == Special case: skippable frames == 1081 * 1082 * Skippable frames allow integration of user-defined data into a flow of 1083 * concatenated frames. Skippable frames will be ignored (skipped) by a 1084 * decompressor. The format of skippable frames is as follows: 1085 * a) Skippable frame ID - 4 Bytes, Little endian format, any value from 1086 * 0x184D2A50 to 0x184D2A5F 1087 * b) Frame Size - 4 Bytes, Little endian format, unsigned 32-bits 1088 * c) Frame Content - any content (User Data) of length equal to Frame Size 1089 * For skippable frames ZSTD_decompressContinue() always returns 0. 1090 * For skippable frames ZSTD_getFrameParams() returns fparamsPtr->windowLog==0 1091 * what means that a frame is skippable. 1092 * Note: If fparamsPtr->frameContentSize==0, it is ambiguous: the frame might 1093 * actually be a zstd encoded frame with no content. For purposes of 1094 * decompression, it is valid in both cases to skip the frame using 1095 * ZSTD_findFrameCompressedSize() to find its size in bytes. 1096 * It also returns frame size as fparamsPtr->frameContentSize. 1097 ******************************************************************************/ 1098 1099 /*===== Buffer-less streaming decompression functions =====*/ 1100 size_t ZSTD_decompressBegin(ZSTD_DCtx *dctx); 1101 size_t ZSTD_decompressBegin_usingDict(ZSTD_DCtx *dctx, const void *dict, 1102 size_t dictSize); 1103 void ZSTD_copyDCtx(ZSTD_DCtx *dctx, const ZSTD_DCtx *preparedDCtx); 1104 size_t ZSTD_nextSrcSizeToDecompress(ZSTD_DCtx *dctx); 1105 size_t ZSTD_decompressContinue(ZSTD_DCtx *dctx, void *dst, size_t dstCapacity, 1106 const void *src, size_t srcSize); 1107 typedef enum { 1108 ZSTDnit_frameHeader, 1109 ZSTDnit_blockHeader, 1110 ZSTDnit_block, 1111 ZSTDnit_lastBlock, 1112 ZSTDnit_checksum, 1113 ZSTDnit_skippableFrame 1114 } ZSTD_nextInputType_e; 1115 ZSTD_nextInputType_e ZSTD_nextInputType(ZSTD_DCtx *dctx); 1116 1117 /*-***************************************************************************** 1118 * Block functions 1119 * 1120 * Block functions produce and decode raw zstd blocks, without frame metadata. 1121 * Frame metadata cost is typically ~18 bytes, which can be non-negligible for 1122 * very small blocks (< 100 bytes). User will have to take in charge required 1123 * information to regenerate data, such as compressed and content sizes. 1124 * 1125 * A few rules to respect: 1126 * - Compressing and decompressing require a context structure 1127 * + Use ZSTD_initCCtx() and ZSTD_initDCtx() 1128 * - It is necessary to init context before starting 1129 * + compression : ZSTD_compressBegin() 1130 * + decompression : ZSTD_decompressBegin() 1131 * + variants _usingDict() are also allowed 1132 * + copyCCtx() and copyDCtx() work too 1133 * - Block size is limited, it must be <= ZSTD_getBlockSizeMax() 1134 * + If you need to compress more, cut data into multiple blocks 1135 * + Consider using the regular ZSTD_compress() instead, as frame metadata 1136 * costs become negligible when source size is large. 1137 * - When a block is considered not compressible enough, ZSTD_compressBlock() 1138 * result will be zero. In which case, nothing is produced into `dst`. 1139 * + User must test for such outcome and deal directly with uncompressed data 1140 * + ZSTD_decompressBlock() doesn't accept uncompressed data as input!!! 1141 * + In case of multiple successive blocks, decoder must be informed of 1142 * uncompressed block existence to follow proper history. Use 1143 * ZSTD_insertBlock() in such a case. 1144 ******************************************************************************/ 1145 1146 /* Define for static allocation */ 1147 #define ZSTD_BLOCKSIZE_ABSOLUTEMAX (128 * 1024) 1148 /*===== Raw zstd block functions =====*/ 1149 size_t ZSTD_getBlockSizeMax(ZSTD_CCtx *cctx); 1150 size_t ZSTD_compressBlock(ZSTD_CCtx *cctx, void *dst, size_t dstCapacity, 1151 const void *src, size_t srcSize); 1152 size_t ZSTD_decompressBlock(ZSTD_DCtx *dctx, void *dst, size_t dstCapacity, 1153 const void *src, size_t srcSize); 1154 size_t ZSTD_insertBlock(ZSTD_DCtx *dctx, const void *blockStart, 1155 size_t blockSize); 1156 1157 #endif /* ZSTD_H */ 1158