zstd.h 48 KB

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