zstd.h 49 KB

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