diff options
Diffstat (limited to 'doc/zstd_manual.html')
| -rw-r--r-- | doc/zstd_manual.html | 336 |
1 files changed, 213 insertions, 123 deletions
diff --git a/doc/zstd_manual.html b/doc/zstd_manual.html index 315488844ba6..9f73c4c815e6 100644 --- a/doc/zstd_manual.html +++ b/doc/zstd_manual.html @@ -1,10 +1,10 @@ <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> -<title>zstd 1.4.8 Manual</title> +<title>zstd 1.5.2 Manual</title> </head> <body> -<h1>zstd 1.4.8 Manual</h1> +<h1>zstd 1.5.2 Manual</h1> <hr> <a name="Contents"></a><h2>Contents</h2> <ol> @@ -12,15 +12,15 @@ <li><a href="#Chapter2">Version</a></li> <li><a href="#Chapter3">Simple API</a></li> <li><a href="#Chapter4">Explicit context</a></li> -<li><a href="#Chapter5">Advanced compression API</a></li> -<li><a href="#Chapter6">Advanced decompression API</a></li> +<li><a href="#Chapter5">Advanced compression API (Requires v1.4.0+)</a></li> +<li><a href="#Chapter6">Advanced decompression API (Requires v1.4.0+)</a></li> <li><a href="#Chapter7">Streaming</a></li> <li><a href="#Chapter8">Streaming compression - HowTo</a></li> <li><a href="#Chapter9">Streaming decompression - HowTo</a></li> <li><a href="#Chapter10">Simple dictionary API</a></li> <li><a href="#Chapter11">Bulk processing dictionary API</a></li> <li><a href="#Chapter12">Dictionary helper functions</a></li> -<li><a href="#Chapter13">Advanced dictionary and prefix API</a></li> +<li><a href="#Chapter13">Advanced dictionary and prefix API (Requires v1.4.0+)</a></li> <li><a href="#Chapter14">experimental API (static linking only)</a></li> <li><a href="#Chapter15">Frame size functions</a></li> <li><a href="#Chapter16">Memory management</a></li> @@ -141,8 +141,9 @@ unsigned long long ZSTD_getFrameContentSize(const void *src, size_t srcSize); size_t ZSTD_compressBound(size_t srcSize); </b>/*!< maximum compressed size in worst case single-pass scenario */<b> unsigned ZSTD_isError(size_t code); </b>/*!< tells if a `size_t` function result is an error code */<b> const char* ZSTD_getErrorName(size_t code); </b>/*!< provides readable string from an error code */<b> -int ZSTD_minCLevel(void); </b>/*!< minimum negative compression level allowed */<b> +int ZSTD_minCLevel(void); </b>/*!< minimum negative compression level allowed, requires v1.4.0+ */<b> int ZSTD_maxCLevel(void); </b>/*!< maximum compression level available */<b> +int ZSTD_defaultCLevel(void); </b>/*!< default compression level, specified by ZSTD_CLEVEL_DEFAULT, requires v1.5.0+ */<b> </pre></b><BR> <a name="Chapter4"></a><h2>Explicit context</h2><pre></pre> @@ -157,7 +158,7 @@ int ZSTD_maxCLevel(void); </b>/*!< maximum compression lev </pre><b><pre>typedef struct ZSTD_CCtx_s ZSTD_CCtx; ZSTD_CCtx* ZSTD_createCCtx(void); -size_t ZSTD_freeCCtx(ZSTD_CCtx* cctx); +size_t ZSTD_freeCCtx(ZSTD_CCtx* cctx); </b>/* accept NULL pointer */<b> </pre></b><BR> <pre><b>size_t ZSTD_compressCCtx(ZSTD_CCtx* cctx, void* dst, size_t dstCapacity, @@ -179,7 +180,7 @@ size_t ZSTD_freeCCtx(ZSTD_CCtx* cctx); Use one context per thread for parallel execution. </pre><b><pre>typedef struct ZSTD_DCtx_s ZSTD_DCtx; ZSTD_DCtx* ZSTD_createDCtx(void); -size_t ZSTD_freeDCtx(ZSTD_DCtx* dctx); +size_t ZSTD_freeDCtx(ZSTD_DCtx* dctx); </b>/* accept NULL pointer */<b> </pre></b><BR> <pre><b>size_t ZSTD_decompressDCtx(ZSTD_DCtx* dctx, void* dst, size_t dstCapacity, @@ -190,7 +191,7 @@ size_t ZSTD_freeDCtx(ZSTD_DCtx* dctx); </p></pre><BR> -<a name="Chapter5"></a><h2>Advanced compression API</h2><pre></pre> +<a name="Chapter5"></a><h2>Advanced compression API (Requires v1.4.0+)</h2><pre></pre> <pre><b>typedef enum { ZSTD_fast=1, ZSTD_dfast=2, @@ -270,7 +271,6 @@ size_t ZSTD_freeDCtx(ZSTD_DCtx* dctx); * The higher the value of selected strategy, the more complex it is, * resulting in stronger and slower compression. * Special: value 0 means "use default strategy". */ - </b>/* LDM mode parameters */<b> ZSTD_c_enableLongDistanceMatching=160, </b>/* Enable long distance matching.<b> * This parameter is designed to improve compression ratio @@ -327,7 +327,7 @@ size_t ZSTD_freeDCtx(ZSTD_DCtx* dctx); ZSTD_c_jobSize=401, </b>/* Size of a compression job. This value is enforced only when nbWorkers >= 1.<b> * Each compression job is completed in parallel, so this value can indirectly impact the nb of active threads. * 0 means default, which is dynamically determined based on compression parameters. - * Job size must be a minimum of overlap size, or 1 MB, whichever is largest. + * Job size must be a minimum of overlap size, or ZSTDMT_JOBSIZE_MIN (= 512 KB), whichever is largest. * The minimum size is automatically and transparently enforced. */ ZSTD_c_overlapLog=402, </b>/* Control the overlap size, as a fraction of window size.<b> * The overlap size is an amount of data reloaded from previous job at the beginning of a new job. @@ -357,6 +357,8 @@ size_t ZSTD_freeDCtx(ZSTD_DCtx* dctx); * ZSTD_c_stableOutBuffer * ZSTD_c_blockDelimiters * ZSTD_c_validateSequences + * ZSTD_c_useBlockSplitter + * ZSTD_c_useRowMatchFinder * Because they are not stable, it's necessary to define ZSTD_STATIC_LINKING_ONLY to access them. * note : never ever use experimentalParam? names directly; * also, the enums values themselves are unstable and can still change. @@ -372,7 +374,10 @@ size_t ZSTD_freeDCtx(ZSTD_DCtx* dctx); ZSTD_c_experimentalParam9=1006, ZSTD_c_experimentalParam10=1007, ZSTD_c_experimentalParam11=1008, - ZSTD_c_experimentalParam12=1009 + ZSTD_c_experimentalParam12=1009, + ZSTD_c_experimentalParam13=1010, + ZSTD_c_experimentalParam14=1011, + ZSTD_c_experimentalParam15=1012 } ZSTD_cParameter; </b></pre><BR> <pre><b>typedef struct { @@ -456,7 +461,7 @@ size_t ZSTD_freeDCtx(ZSTD_DCtx* dctx); </p></pre><BR> -<a name="Chapter6"></a><h2>Advanced decompression API</h2><pre></pre> +<a name="Chapter6"></a><h2>Advanced decompression API (Requires v1.4.0+)</h2><pre></pre> <pre><b>typedef enum { @@ -473,12 +478,14 @@ size_t ZSTD_freeDCtx(ZSTD_DCtx* dctx); * ZSTD_d_format * ZSTD_d_stableOutBuffer * ZSTD_d_forceIgnoreChecksum + * ZSTD_d_refMultipleDDicts * Because they are not stable, it's necessary to define ZSTD_STATIC_LINKING_ONLY to access them. * note : never ever use experimentalParam? names directly */ ZSTD_d_experimentalParam1=1000, ZSTD_d_experimentalParam2=1001, - ZSTD_d_experimentalParam3=1002 + ZSTD_d_experimentalParam3=1002, + ZSTD_d_experimentalParam4=1003 } ZSTD_dParameter; </b></pre><BR> @@ -585,7 +592,7 @@ size_t ZSTD_freeDCtx(ZSTD_DCtx* dctx); <pre><b>typedef ZSTD_CCtx ZSTD_CStream; </b>/**< CCtx and CStream are now effectively same object (>= v1.3.0) */<b> </b></pre><BR> <h3>ZSTD_CStream management functions</h3><pre></pre><b><pre>ZSTD_CStream* ZSTD_createCStream(void); -size_t ZSTD_freeCStream(ZSTD_CStream* zcs); +size_t ZSTD_freeCStream(ZSTD_CStream* zcs); </b>/* accept NULL pointer */<b> </pre></b><BR> <h3>Streaming compression functions</h3><pre></pre><b><pre>typedef enum { ZSTD_e_continue=0, </b>/* collect more data, encoder decides when to output compressed result, for optimal compression ratio */<b> @@ -679,7 +686,7 @@ size_t ZSTD_endStream(ZSTD_CStream* zcs, ZSTD_outBuffer* output); <pre><b>typedef ZSTD_DCtx ZSTD_DStream; </b>/**< DCtx and DStream are now effectively same object (>= v1.3.0) */<b> </b></pre><BR> <h3>ZSTD_DStream management functions</h3><pre></pre><b><pre>ZSTD_DStream* ZSTD_createDStream(void); -size_t ZSTD_freeDStream(ZSTD_DStream* zds); +size_t ZSTD_freeDStream(ZSTD_DStream* zds); </b>/* accept NULL pointer */<b> </pre></b><BR> <h3>Streaming decompression functions</h3><pre></pre><b><pre></pre></b><BR> <pre><b>size_t ZSTD_DStreamInSize(void); </b>/*!< recommended size for input buffer */<b> @@ -695,7 +702,7 @@ size_t ZSTD_freeDStream(ZSTD_DStream* zds); int compressionLevel); </b><p> Compression at an explicit compression level using a Dictionary. A dictionary can be any arbitrary data segment (also called a prefix), - or a buffer with specified information (see dictBuilder/zdict.h). + or a buffer with specified information (see zdict.h). Note : This function loads the dictionary, resulting in significant startup delay. It's intended for a dictionary used only once. Note 2 : When `dict == NULL || dictSize < 8` no dictionary is used. @@ -730,7 +737,8 @@ size_t ZSTD_freeDStream(ZSTD_DStream* zds); </p></pre><BR> <pre><b>size_t ZSTD_freeCDict(ZSTD_CDict* CDict); -</b><p> Function frees memory allocated by ZSTD_createCDict(). +</b><p> Function frees memory allocated by ZSTD_createCDict(). + If a NULL pointer is passed, no operation is performed. </p></pre><BR> <pre><b>size_t ZSTD_compress_usingCDict(ZSTD_CCtx* cctx, @@ -749,7 +757,8 @@ size_t ZSTD_freeDStream(ZSTD_DStream* zds); </p></pre><BR> <pre><b>size_t ZSTD_freeDDict(ZSTD_DDict* ddict); -</b><p> Function frees memory allocated with ZSTD_createDDict() +</b><p> Function frees memory allocated with ZSTD_createDDict() + If a NULL pointer is passed, no operation is performed. </p></pre><BR> <pre><b>size_t ZSTD_decompress_usingDDict(ZSTD_DCtx* dctx, @@ -768,6 +777,12 @@ size_t ZSTD_freeDStream(ZSTD_DStream* zds); It can still be loaded, but as a content-only dictionary. </p></pre><BR> +<pre><b>unsigned ZSTD_getDictID_fromCDict(const ZSTD_CDict* cdict); +</b><p> Provides the dictID of the dictionary loaded into `cdict`. + If @return == 0, the dictionary is not conformant to Zstandard specification, or empty. + Non-conformant dictionaries can still be loaded, but as content-only dictionaries. +</p></pre><BR> + <pre><b>unsigned ZSTD_getDictID_fromDDict(const ZSTD_DDict* ddict); </b><p> Provides the dictID of the dictionary loaded into `ddict`. If @return == 0, the dictionary is not conformant to Zstandard specification, or empty. @@ -786,9 +801,9 @@ size_t ZSTD_freeDStream(ZSTD_DStream* zds); When identifying the exact failure cause, it's possible to use ZSTD_getFrameHeader(), which will provide a more precise error code. </p></pre><BR> -<a name="Chapter13"></a><h2>Advanced dictionary and prefix API</h2><pre> +<a name="Chapter13"></a><h2>Advanced dictionary and prefix API (Requires v1.4.0+)</h2><pre> This API allows dictionaries to be used with ZSTD_compress2(), - ZSTD_compressStream2(), and ZSTD_decompress(). Dictionaries are sticky, and + ZSTD_compressStream2(), and ZSTD_decompressDCtx(). Dictionaries are sticky, and only reset with the context is reset with ZSTD_reset_parameters or ZSTD_reset_session_and_parameters. Prefixes are single-use. <BR></pre> @@ -816,7 +831,7 @@ size_t ZSTD_freeDStream(ZSTD_DStream* zds); </b><p> Reference a prepared dictionary, to be used for all next compressed frames. Note that compression parameters are enforced from within CDict, and supersede any compression parameter previously set within CCtx. - The parameters ignored are labled as "superseded-by-cdict" in the ZSTD_cParameter enum docs. + The parameters ignored are labelled as "superseded-by-cdict" in the ZSTD_cParameter enum docs. The ignored parameters will be used again if the CCtx is returned to no-dictionary mode. The dictionary will remain valid for future compressed frames using same CCtx. @result : 0, or an error code (which can be tested with ZSTD_isError()). @@ -867,6 +882,13 @@ size_t ZSTD_freeDStream(ZSTD_DStream* zds); <pre><b>size_t ZSTD_DCtx_refDDict(ZSTD_DCtx* dctx, const ZSTD_DDict* ddict); </b><p> Reference a prepared dictionary, to be used to decompress next frames. The dictionary remains active for decompression of future frames using same DCtx. + + If called with ZSTD_d_refMultipleDDicts enabled, repeated calls of this function + will store the DDict references in a table, and the DDict used for decompression + will be determined at decompression time, as per the dict ID in the frame. + The memory for the table is allocated on the first call to refDDict, and can be + freed with ZSTD_freeDCtx(). + @result : 0, or an error code (which can be tested with ZSTD_isError()). Note 1 : Currently, only one dictionary can be managed. Referencing a new dictionary effectively "discards" any previous one. @@ -996,6 +1018,12 @@ size_t ZSTD_sizeof_DDict(const ZSTD_DDict* ddict); } ZSTD_forceIgnoreChecksum_e; </b></pre><BR> <pre><b>typedef enum { + </b>/* Note: this enum controls ZSTD_d_refMultipleDDicts */<b> + ZSTD_rmd_refSingleDDict = 0, + ZSTD_rmd_refMultipleDDicts = 1 +} ZSTD_refMultipleDDicts_e; +</b></pre><BR> +<pre><b>typedef enum { </b>/* Note: this enum and the behavior it controls are effectively internal<b> * implementation details of the compressor. They are expected to continue * to evolve and should be considered only in the context of extremely @@ -1043,9 +1071,19 @@ size_t ZSTD_sizeof_DDict(const ZSTD_DDict* ddict); ZSTD_lcm_uncompressed = 2 </b>/**< Always emit uncompressed literals. */<b> } ZSTD_literalCompressionMode_e; </b></pre><BR> +<pre><b>typedef enum { + </b>/* Note: This enum controls features which are conditionally beneficial. Zstd typically will make a final<b> + * decision on whether or not to enable the feature (ZSTD_ps_auto), but setting the switch to ZSTD_ps_enable + * or ZSTD_ps_disable allow for a force enable/disable the feature. + */ + ZSTD_ps_auto = 0, </b>/* Let the library automatically determine whether the feature shall be enabled */<b> + ZSTD_ps_enable = 1, </b>/* Force-enable the feature */<b> + ZSTD_ps_disable = 2 </b>/* Do not use the feature */<b> +} ZSTD_paramSwitch_e; +</b></pre><BR> <a name="Chapter15"></a><h2>Frame size functions</h2><pre></pre> -<pre><b>unsigned long long ZSTD_findDecompressedSize(const void* src, size_t srcSize); +<pre><b>ZSTDLIB_STATIC_API unsigned long long ZSTD_findDecompressedSize(const void* src, size_t srcSize); </b><p> `src` should point to the start of a series of ZSTD encoded and/or skippable frames `srcSize` must be the _exact_ size of this series (i.e. there should be a frame boundary at `src + srcSize`) @@ -1068,12 +1106,12 @@ size_t ZSTD_sizeof_DDict(const ZSTD_DDict* ddict); however it does mean that all frame data must be present and valid. </p></pre><BR> -<pre><b>unsigned long long ZSTD_decompressBound(const void* src, size_t srcSize); +<pre><b>ZSTDLIB_STATIC_API unsigned long long ZSTD_decompressBound(const void* src, size_t srcSize); </b><p> `src` should point to the start of a series of ZSTD encoded and/or skippable frames `srcSize` must be the _exact_ size of this series (i.e. there should be a frame boundary at `src + srcSize`) @return : - upper-bound for the decompressed size of all data in all successive frames - - if an error occured: ZSTD_CONTENTSIZE_ERROR + - if an error occurred: ZSTD_CONTENTSIZE_ERROR note 1 : an error can occur if `src` contains an invalid or incorrectly formatted frame. note 2 : the upper-bound is exact when the decompressed size field is available in every ZSTD encoded frame of `src`. @@ -1083,7 +1121,7 @@ size_t ZSTD_sizeof_DDict(const ZSTD_DDict* ddict); </p></pre><BR> -<pre><b>size_t ZSTD_frameHeaderSize(const void* src, size_t srcSize); +<pre><b>ZSTDLIB_STATIC_API size_t ZSTD_frameHeaderSize(const void* src, size_t srcSize); </b><p> srcSize must be >= ZSTD_FRAMEHEADERSIZE_PREFIX. @return : size of the Frame Header, or an error code (if srcSize is too small) @@ -1110,7 +1148,7 @@ size_t ZSTD_sizeof_DDict(const ZSTD_DDict* ddict); </p></pre><BR> -<pre><b>size_t ZSTD_mergeBlockDelimiters(ZSTD_Sequence* sequences, size_t seqsSize); +<pre><b>ZSTDLIB_STATIC_API size_t ZSTD_mergeBlockDelimiters(ZSTD_Sequence* sequences, size_t seqsSize); </b><p> Given an array of ZSTD_Sequence, remove all sequences that represent block delimiters/last literals by merging them into into the literals of the next sequence. @@ -1123,7 +1161,7 @@ size_t ZSTD_sizeof_DDict(const ZSTD_DDict* ddict); </p></pre><BR> -<pre><b>size_t ZSTD_compressSequences(ZSTD_CCtx* const cctx, void* dst, size_t dstSize, +<pre><b>ZSTDLIB_STATIC_API size_t ZSTD_compressSequences(ZSTD_CCtx* const cctx, void* dst, size_t dstSize, const ZSTD_Sequence* inSeqs, size_t inSeqsSize, const void* src, size_t srcSize); </b><p> Compress an array of ZSTD_Sequence, generated from the original source buffer, into dst. @@ -1155,12 +1193,47 @@ size_t ZSTD_sizeof_DDict(const ZSTD_DDict* ddict); </p></pre><BR> +<pre><b>ZSTDLIB_STATIC_API size_t ZSTD_writeSkippableFrame(void* dst, size_t dstCapacity, + const void* src, size_t srcSize, unsigned magicVariant); +</b><p> Generates a zstd skippable frame containing data given by src, and writes it to dst buffer. + + Skippable frames begin with a a 4-byte magic number. There are 16 possible choices of magic number, + ranging from ZSTD_MAGIC_SKIPPABLE_START to ZSTD_MAGIC_SKIPPABLE_START+15. + As such, the parameter magicVariant controls the exact skippable frame magic number variant used, so + the magic number used will be ZSTD_MAGIC_SKIPPABLE_START + magicVariant. + + Returns an error if destination buffer is not large enough, if the source size is not representable + with a 4-byte unsigned int, or if the parameter magicVariant is greater than 15 (and therefore invalid). + + @return : number of bytes written or a ZSTD error. + +</p></pre><BR> + +<pre><b>size_t ZSTD_readSkippableFrame(void* dst, size_t dstCapacity, unsigned* magicVariant, + const void* src, size_t srcSize); +</b><p> Retrieves a zstd skippable frame containing data given by src, and writes it to dst buffer. + + The parameter magicVariant will receive the magicVariant that was supplied when the frame was written, + i.e. magicNumber - ZSTD_MAGIC_SKIPPABLE_START. This can be NULL if the caller is not interested + in the magicVariant. + + Returns an error if destination buffer is not large enough, or if the frame is not skippable. + + @return : number of bytes written or a ZSTD error. + +</p></pre><BR> + +<pre><b>unsigned ZSTD_isSkippableFrame(const void* buffer, size_t size); +</b><p> Tells if the content of `buffer` starts with a valid Frame Identifier for a skippable frame. + +</p></pre><BR> + <a name="Chapter16"></a><h2>Memory management</h2><pre></pre> -<pre><b>size_t ZSTD_estimateCCtxSize(int compressionLevel); -size_t ZSTD_estimateCCtxSize_usingCParams(ZSTD_compressionParameters cParams); -size_t ZSTD_estimateCCtxSize_usingCCtxParams(const ZSTD_CCtx_params* params); -size_t ZSTD_estimateDCtxSize(void); +<pre><b>ZSTDLIB_STATIC_API size_t ZSTD_estimateCCtxSize(int compressionLevel); +ZSTDLIB_STATIC_API size_t ZSTD_estimateCCtxSize_usingCParams(ZSTD_compressionParameters cParams); +ZSTDLIB_STATIC_API size_t ZSTD_estimateCCtxSize_usingCCtxParams(const ZSTD_CCtx_params* params); +ZSTDLIB_STATIC_API size_t ZSTD_estimateDCtxSize(void); </b><p> These functions make it possible to estimate memory usage of a future {D,C}Ctx, before its creation. @@ -1185,11 +1258,11 @@ size_t ZSTD_estimateDCtxSize(void); </p></pre><BR> -<pre><b>size_t ZSTD_estimateCStreamSize(int compressionLevel); -size_t ZSTD_estimateCStreamSize_usingCParams(ZSTD_compressionParameters cParams); -size_t ZSTD_estimateCStreamSize_usingCCtxParams(const ZSTD_CCtx_params* params); -size_t ZSTD_estimateDStreamSize(size_t windowSize); -size_t ZSTD_estimateDStreamSize_fromFrame(const void* src, size_t srcSize); +<pre><b>ZSTDLIB_STATIC_API size_t ZSTD_estimateCStreamSize(int compressionLevel); +ZSTDLIB_STATIC_API size_t ZSTD_estimateCStreamSize_usingCParams(ZSTD_compressionParameters cParams); +ZSTDLIB_STATIC_API size_t ZSTD_estimateCStreamSize_usingCCtxParams(const ZSTD_CCtx_params* params); +ZSTDLIB_STATIC_API size_t ZSTD_estimateDStreamSize(size_t windowSize); +ZSTDLIB_STATIC_API size_t ZSTD_estimateDStreamSize_fromFrame(const void* src, size_t srcSize); </b><p> ZSTD_estimateCStreamSize() will provide a budget large enough for any compression level up to selected one. It will also consider src size to be arbitrarily "large", which is worst case. If srcSize is known to always be small, ZSTD_estimateCStreamSize_usingCParams() can provide a tighter estimation. @@ -1204,17 +1277,17 @@ size_t ZSTD_estimateDStreamSize_fromFrame(const void* src, size_t srcSize); In this case, get total size by adding ZSTD_estimate?DictSize </p></pre><BR> -<pre><b>size_t ZSTD_estimateCDictSize(size_t dictSize, int compressionLevel); -size_t ZSTD_estimateCDictSize_advanced(size_t dictSize, ZSTD_compressionParameters cParams, ZSTD_dictLoadMethod_e dictLoadMethod); -size_t ZSTD_estimateDDictSize(size_t dictSize, ZSTD_dictLoadMethod_e dictLoadMethod); +<pre><b>ZSTDLIB_STATIC_API size_t ZSTD_estimateCDictSize(size_t dictSize, int compressionLevel); +ZSTDLIB_STATIC_API size_t ZSTD_estimateCDictSize_advanced(size_t dictSize, ZSTD_compressionParameters cParams, ZSTD_dictLoadMethod_e dictLoadMethod); +ZSTDLIB_STATIC_API size_t ZSTD_estimateDDictSize(size_t dictSize, ZSTD_dictLoadMethod_e dictLoadMethod); </b><p> ZSTD_estimateCDictSize() will bet that src size is relatively "small", and content is copied, like ZSTD_createCDict(). ZSTD_estimateCDictSize_advanced() makes it possible to control compression parameters precisely, like ZSTD_createCDict_advanced(). Note : dictionaries created by reference (`ZSTD_dlm_byRef`) are logically smaller. </p></pre><BR> -<pre><b>ZSTD_CCtx* ZSTD_initStaticCCtx(void* workspace, size_t workspaceSize); -ZSTD_CStream* ZSTD_initStaticCStream(void* workspace, size_t workspaceSize); </b>/**< same as ZSTD_initStaticCCtx() */<b> +<pre><b>ZSTDLIB_STATIC_API ZSTD_CCtx* ZSTD_initStaticCCtx(void* workspace, size_t workspaceSize); +ZSTDLIB_STATIC_API ZSTD_CStream* ZSTD_initStaticCStream(void* workspace, size_t workspaceSize); </b>/**< same as ZSTD_initStaticCCtx() */<b> </b><p> Initialize an object using a pre-allocated fixed-size buffer. workspace: The memory area to emplace the object into. Provided pointer *must be 8-bytes aligned*. @@ -1237,7 +1310,7 @@ ZSTD_CStream* ZSTD_initStaticCStream(void* workspace, size_t workspaceSize); </p></pre><BR> -<pre><b>ZSTD_DStream* ZSTD_initStaticDStream(void* workspace, size_t workspaceSize); </b>/**< same as ZSTD_initStaticDCtx() */<b> +<pre><b>ZSTDLIB_STATIC_API ZSTD_DStream* ZSTD_initStaticDStream(void* workspace, size_t workspaceSize); </b>/**< same as ZSTD_initStaticDCtx() */<b> </b></pre><BR> <pre><b>typedef void* (*ZSTD_allocFunction) (void* opaque, size_t size); typedef void (*ZSTD_freeFunction) (void* opaque, void* address); @@ -1253,9 +1326,24 @@ ZSTD_customMem const ZSTD_defaultCMem = { NULL, NULL, NULL }; </b>/**< this con </p></pre><BR> +<pre><b>typedef struct POOL_ctx_s ZSTD_threadPool; +ZSTDLIB_STATIC_API ZSTD_threadPool* ZSTD_createThreadPool(size_t numThreads); +ZSTDLIB_STATIC_API void ZSTD_freeThreadPool (ZSTD_threadPool* pool); </b>/* accept NULL pointer */<b> +ZSTDLIB_STATIC_API size_t ZSTD_CCtx_refThreadPool(ZSTD_CCtx* cctx, ZSTD_threadPool* pool); +</b><p> These prototypes make it possible to share a thread pool among multiple compression contexts. + This can limit resources for applications with multiple threads where each one uses + a threaded compression mode (via ZSTD_c_nbWorkers parameter). + ZSTD_createThreadPool creates a new thread pool with a given number of threads. + Note that the lifetime of such pool must exist while being used. + ZSTD_CCtx_refThreadPool assigns a thread pool to a context (use NULL argument value + to use an internal thread pool). + ZSTD_freeThreadPool frees a thread pool, accepts NULL pointer. + +</p></pre><BR> + <a name="Chapter17"></a><h2>Advanced compression functions</h2><pre></pre> -<pre><b>ZSTD_CDict* ZSTD_createCDict_byReference(const void* dictBuffer, size_t dictSize, int compressionLevel); +<pre><b>ZSTDLIB_STATIC_API ZSTD_CDict* ZSTD_createCDict_byReference(const void* dictBuffer, size_t dictSize, int compressionLevel); </b><p> Create a digested dictionary for compression Dictionary content is just referenced, not duplicated. As a consequence, `dictBuffer` **must** outlive CDict, @@ -1263,28 +1351,22 @@ ZSTD_customMem const ZSTD_defaultCMem = { NULL, NULL, NULL }; </b>/**< this con note: equivalent to ZSTD_createCDict_advanced(), with dictLoadMethod==ZSTD_dlm_byRef </p></pre><BR> -<pre><b>unsigned ZSTD_getDictID_fromCDict(const ZSTD_CDict* cdict); -</b><p> Provides the dictID of the dictionary loaded into `cdict`. - If @return == 0, the dictionary is not conformant to Zstandard specification, or empty. - Non-conformant dictionaries can still be loaded, but as content-only dictionaries. -</p></pre><BR> - -<pre><b>ZSTD_compressionParameters ZSTD_getCParams(int compressionLevel, unsigned long long estimatedSrcSize, size_t dictSize); +<pre><b>ZSTDLIB_STATIC_API ZSTD_compressionParameters ZSTD_getCParams(int compressionLevel, unsigned long long estimatedSrcSize, size_t dictSize); </b><p> @return ZSTD_compressionParameters structure for a selected compression level and estimated srcSize. `estimatedSrcSize` value is optional, select 0 if not known </p></pre><BR> -<pre><b>ZSTD_parameters ZSTD_getParams(int compressionLevel, unsigned long long estimatedSrcSize, size_t dictSize); +<pre><b>ZSTDLIB_STATIC_API ZSTD_parameters ZSTD_getParams(int compressionLevel, unsigned long long estimatedSrcSize, size_t dictSize); </b><p> same as ZSTD_getCParams(), but @return a full `ZSTD_parameters` object instead of sub-component `ZSTD_compressionParameters`. All fields of `ZSTD_frameParameters` are set to default : contentSize=1, checksum=0, noDictID=0 </p></pre><BR> -<pre><b>size_t ZSTD_checkCParams(ZSTD_compressionParameters params); +<pre><b>ZSTDLIB_STATIC_API size_t ZSTD_checkCParams(ZSTD_compressionParameters params); </b><p> Ensure param values remain within authorized range. @return 0 on success, or an error code (can be checked with ZSTD_isError()) </p></pre><BR> -<pre><b>ZSTD_compressionParameters ZSTD_adjustCParams(ZSTD_compressionParameters cPar, unsigned long long srcSize, size_t dictSize); +<pre><b>ZSTDLIB_STATIC_API ZSTD_compressionParameters ZSTD_adjustCParams(ZSTD_compressionParameters cPar, unsigned long long srcSize, size_t dictSize); </b><p> optimize params for a given `srcSize` and `dictSize`. `srcSize` can be unknown, in which case use ZSTD_CONTENTSIZE_UNKNOWN. `dictSize` must be `0` when there is no dictionary. @@ -1292,51 +1374,53 @@ ZSTD_customMem const ZSTD_defaultCMem = { NULL, NULL, NULL }; </b>/**< this con This function never fails (wide contract) </p></pre><BR> -<pre><b>size_t ZSTD_compress_advanced(ZSTD_CCtx* cctx, +<pre><b>ZSTD_DEPRECATED("use ZSTD_compress2") +size_t ZSTD_compress_advanced(ZSTD_CCtx* cctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize, const void* dict,size_t dictSize, ZSTD_parameters params); </b><p> Note : this function is now DEPRECATED. It can be replaced by ZSTD_compress2(), in combination with ZSTD_CCtx_setParameter() and other parameter setters. - This prototype will be marked as deprecated and generate compilation warning on reaching v1.5.x + This prototype will generate compilation warnings. </p></pre><BR> -<pre><b>size_t ZSTD_compress_usingCDict_advanced(ZSTD_CCtx* cctx, +<pre><b>ZSTD_DEPRECATED("use ZSTD_compress2 with ZSTD_CCtx_loadDictionary") +size_t ZSTD_compress_usingCDict_advanced(ZSTD_CCtx* cctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize, const ZSTD_CDict* cdict, ZSTD_frameParameters fParams); -</b><p> Note : this function is now REDUNDANT. +</b><p> Note : this function is now DEPRECATED. It can be replaced by ZSTD_compress2(), in combination with ZSTD_CCtx_loadDictionary() and other parameter setters. - This prototype will be marked as deprecated and generate compilation warning in some future version + This prototype will generate compilation warnings. </p></pre><BR> -<pre><b>size_t ZSTD_CCtx_loadDictionary_byReference(ZSTD_CCtx* cctx, const void* dict, size_t dictSize); +<pre><b>ZSTDLIB_STATIC_API size_t ZSTD_CCtx_loadDictionary_byReference(ZSTD_CCtx* cctx, const void* dict, size_t dictSize); </b><p> Same as ZSTD_CCtx_loadDictionary(), but dictionary content is referenced, instead of being copied into CCtx. It saves some memory, but also requires that `dict` outlives its usage within `cctx` </p></pre><BR> -<pre><b>size_t ZSTD_CCtx_loadDictionary_advanced(ZSTD_CCtx* cctx, const void* dict, size_t dictSize, ZSTD_dictLoadMethod_e dictLoadMethod, ZSTD_dictContentType_e dictContentType); +<pre><b>ZSTDLIB_STATIC_API size_t ZSTD_CCtx_loadDictionary_advanced(ZSTD_CCtx* cctx, const void* dict, size_t dictSize, ZSTD_dictLoadMethod_e dictLoadMethod, ZSTD_dictContentType_e dictContentType); </b><p> Same as ZSTD_CCtx_loadDictionary(), but gives finer control over how to load the dictionary (by copy ? by reference ?) and how to interpret it (automatic ? force raw mode ? full mode only ?) </p></pre><BR> -<pre><b>size_t ZSTD_CCtx_refPrefix_advanced(ZSTD_CCtx* cctx, const void* prefix, size_t prefixSize, ZSTD_dictContentType_e dictContentType); +<pre><b>ZSTDLIB_STATIC_API size_t ZSTD_CCtx_refPrefix_advanced(ZSTD_CCtx* cctx, const void* prefix, size_t prefixSize, ZSTD_dictContentType_e dictContentType); </b><p> Same as ZSTD_CCtx_refPrefix(), but gives finer control over how to interpret prefix content (automatic ? force raw mode (default) ? full mode only ?) </p></pre><BR> -<pre><b>size_t ZSTD_CCtx_getParameter(ZSTD_CCtx* cctx, ZSTD_cParameter param, int* value); +<pre><b>ZSTDLIB_STATIC_API size_t ZSTD_CCtx_getParameter(const ZSTD_CCtx* cctx, ZSTD_cParameter param, int* value); </b><p> Get the requested compression parameter value, selected by enum ZSTD_cParameter, and store it into int* value. @return : 0, or an error code (which can be tested with ZSTD_isError()). </p></pre><BR> -<pre><b>ZSTD_CCtx_params* ZSTD_createCCtxParams(void); -size_t ZSTD_freeCCtxParams(ZSTD_CCtx_params* params); +<pre><b>ZSTDLIB_STATIC_API ZSTD_CCtx_params* ZSTD_createCCtxParams(void); +ZSTDLIB_STATIC_API size_t ZSTD_freeCCtxParams(ZSTD_CCtx_params* params); </b>/* accept NULL pointer */<b> </b><p> Quick howto : - ZSTD_createCCtxParams() : Create a ZSTD_CCtx_params structure - ZSTD_CCtxParams_setParameter() : Push parameters one by one into @@ -1348,31 +1432,31 @@ size_t ZSTD_freeCCtxParams(ZSTD_CCtx_params* params); These parameters will be applied to all subsequent frames. - ZSTD_compressStream2() : Do compression using the CCtx. - - ZSTD_freeCCtxParams() : Free the memory. + - ZSTD_freeCCtxParams() : Free the memory, accept NULL pointer. This can be used with ZSTD_estimateCCtxSize_advanced_usingCCtxParams() for static allocation of CCtx for single-threaded compression. </p></pre><BR> -<pre><b>size_t ZSTD_CCtxParams_reset(ZSTD_CCtx_params* params); +<pre><b>ZSTDLIB_STATIC_API size_t ZSTD_CCtxParams_reset(ZSTD_CCtx_params* params); </b><p> Reset params to default values. </p></pre><BR> -<pre><b>size_t ZSTD_CCtxParams_init(ZSTD_CCtx_params* cctxParams, int compressionLevel); +<pre><b>ZSTDLIB_STATIC_API size_t ZSTD_CCtxParams_init(ZSTD_CCtx_params* cctxParams, int compressionLevel); </b><p> Initializes the compression parameters of cctxParams according to compression level. All other parameters are reset to their default values. </p></pre><BR> -<pre><b>size_t ZSTD_CCtxParams_init_advanced(ZSTD_CCtx_params* cctxParams, ZSTD_parameters params); +<pre><b>ZSTDLIB_STATIC_API size_t ZSTD_CCtxParams_init_advanced(ZSTD_CCtx_params* cctxParams, ZSTD_parameters params); </b><p> Initializes the compression and frame parameters of cctxParams according to params. All other parameters are reset to their default values. </p></pre><BR> -<pre><b>size_t ZSTD_CCtxParams_setParameter(ZSTD_CCtx_params* params, ZSTD_cParameter param, int value); +<pre><b>ZSTDLIB_STATIC_API size_t ZSTD_CCtxParams_setParameter(ZSTD_CCtx_params* params, ZSTD_cParameter param, int value); </b><p> Similar to ZSTD_CCtx_setParameter. Set one compression parameter, selected by enum ZSTD_cParameter. Parameters must be applied to a ZSTD_CCtx using @@ -1382,14 +1466,14 @@ size_t ZSTD_freeCCtxParams(ZSTD_CCtx_params* params); </p></pre><BR> -<pre><b>size_t ZSTD_CCtxParams_getParameter(ZSTD_CCtx_params* params, ZSTD_cParameter param, int* value); +<pre><b>ZSTDLIB_STATIC_API size_t ZSTD_CCtxParams_getParameter(const ZSTD_CCtx_params* params, ZSTD_cParameter param, int* value); </b><p> Similar to ZSTD_CCtx_getParameter. Get the requested value of one compression parameter, selected by enum ZSTD_cParameter. @result : 0, or an error code (which can be tested with ZSTD_isError()). </p></pre><BR> -<pre><b>size_t ZSTD_CCtx_setParametersUsingCCtxParams( +<pre><b>ZSTDLIB_STATIC_API size_t ZSTD_CCtx_setParametersUsingCCtxParams( ZSTD_CCtx* cctx, const ZSTD_CCtx_params* params); </b><p> Apply a set of ZSTD_CCtx_params to the compression context. This can be done even after compression is started, @@ -1399,7 +1483,7 @@ size_t ZSTD_freeCCtxParams(ZSTD_CCtx_params* params); </p></pre><BR> -<pre><b>size_t ZSTD_compressStream2_simpleArgs ( +<pre><b>ZSTDLIB_STATIC_API size_t ZSTD_compressStream2_simpleArgs ( ZSTD_CCtx* cctx, void* dst, size_t dstCapacity, size_t* dstPos, const void* src, size_t srcSize, size_t* srcPos, @@ -1413,40 +1497,40 @@ size_t ZSTD_freeCCtxParams(ZSTD_CCtx_params* params); <a name="Chapter18"></a><h2>Advanced decompression functions</h2><pre></pre> -<pre><b>unsigned ZSTD_isFrame(const void* buffer, size_t size); +<pre><b>ZSTDLIB_STATIC_API unsigned ZSTD_isFrame(const void* buffer, size_t size); </b><p> Tells if the content of `buffer` starts with a valid Frame Identifier. Note : Frame Identifier is 4 bytes. If `size < 4`, @return will always be 0. Note 2 : Legacy Frame Identifiers are considered valid only if Legacy Support is enabled. Note 3 : Skippable Frame Identifiers are considered valid. </p></pre><BR> -<pre><b>ZSTD_DDict* ZSTD_createDDict_byReference(const void* dictBuffer, size_t dictSize); +<pre><b>ZSTDLIB_STATIC_API ZSTD_DDict* ZSTD_createDDict_byReference(const void* dictBuffer, size_t dictSize); </b><p> Create a digested dictionary, ready to start decompression operation without startup delay. Dictionary content is referenced, and therefore stays in dictBuffer. It is important that dictBuffer outlives DDict, it must remain read accessible throughout the lifetime of DDict </p></pre><BR> -<pre><b>size_t ZSTD_DCtx_loadDictionary_byReference(ZSTD_DCtx* dctx, const void* dict, size_t dictSize); +<pre><b>ZSTDLIB_STATIC_API size_t ZSTD_DCtx_loadDictionary_byReference(ZSTD_DCtx* dctx, const void* dict, size_t dictSize); </b><p> Same as ZSTD_DCtx_loadDictionary(), but references `dict` content instead of copying it into `dctx`. This saves memory if `dict` remains around., However, it's imperative that `dict` remains accessible (and unmodified) while being used, so it must outlive decompression. </p></pre><BR> -<pre><b>size_t ZSTD_DCtx_loadDictionary_advanced(ZSTD_DCtx* dctx, const void* dict, size_t dictSize, ZSTD_dictLoadMethod_e dictLoadMethod, ZSTD_dictContentType_e dictContentType); +<pre><b>ZSTDLIB_STATIC_API size_t ZSTD_DCtx_loadDictionary_advanced(ZSTD_DCtx* dctx, const void* dict, size_t dictSize, ZSTD_dictLoadMethod_e dictLoadMethod, ZSTD_dictContentType_e dictContentType); </b><p> Same as ZSTD_DCtx_loadDictionary(), but gives direct control over how to load the dictionary (by copy ? by reference ?) and how to interpret it (automatic ? force raw mode ? full mode only ?). </p></pre><BR> -<pre><b>size_t ZSTD_DCtx_refPrefix_advanced(ZSTD_DCtx* dctx, const void* prefix, size_t prefixSize, ZSTD_dictContentType_e dictContentType); +<pre><b>ZSTDLIB_STATIC_API size_t ZSTD_DCtx_refPrefix_advanced(ZSTD_DCtx* dctx, const void* prefix, size_t prefixSize, ZSTD_dictContentType_e dictContentType); </b><p> Same as ZSTD_DCtx_refPrefix(), but gives finer control over how to interpret prefix content (automatic ? force raw mode (default) ? full mode only ?) </p></pre><BR> -<pre><b>size_t ZSTD_DCtx_setMaxWindowSize(ZSTD_DCtx* dctx, size_t maxWindowSize); +<pre><b>ZSTDLIB_STATIC_API size_t ZSTD_DCtx_setMaxWindowSize(ZSTD_DCtx* dctx, size_t maxWindowSize); </b><p> Refuses allocating internal buffers for frames requiring a window size larger than provided limit. This protects a decoder context from reserving too much memory for itself (potential attack scenario). This parameter is only useful in streaming mode, since no internal buffer is allocated in single-pass mode. @@ -1455,21 +1539,23 @@ size_t ZSTD_freeCCtxParams(ZSTD_CCtx_params* params); </p></pre><BR> -<pre><b>size_t ZSTD_DCtx_getParameter(ZSTD_DCtx* dctx, ZSTD_dParameter param, int* value); +<pre><b>ZSTDLIB_STATIC_API size_t ZSTD_DCtx_getParameter(ZSTD_DCtx* dctx, ZSTD_dParameter param, int* value); </b><p> Get the requested decompression parameter value, selected by enum ZSTD_dParameter, and store it into int* value. @return : 0, or an error code (which can be tested with ZSTD_isError()). </p></pre><BR> -<pre><b>size_t ZSTD_DCtx_setFormat(ZSTD_DCtx* dctx, ZSTD_format_e format); -</b><p> Instruct the decoder context about what kind of data to decode next. +<pre><b>ZSTD_DEPRECATED("use ZSTD_DCtx_setParameter() instead") +size_t ZSTD_DCtx_setFormat(ZSTD_DCtx* dctx, ZSTD_format_e format); +</b><p> This function is REDUNDANT. Prefer ZSTD_DCtx_setParameter(). + Instruct the decoder context about what kind of data to decode next. This instruction is mandatory to decode data without a fully-formed header, such ZSTD_f_zstd1_magicless for example. @return : 0, or an error code (which can be tested using ZSTD_isError()). </p></pre><BR> -<pre><b>size_t ZSTD_decompressStream_simpleArgs ( +<pre><b>ZSTDLIB_STATIC_API size_t ZSTD_decompressStream_simpleArgs ( ZSTD_DCtx* dctx, void* dst, size_t dstCapacity, size_t* dstPos, const void* src, size_t srcSize, size_t* srcPos); @@ -1486,11 +1572,11 @@ size_t ZSTD_freeCCtxParams(ZSTD_CCtx_params* params); <BR></pre> <h3>Advanced Streaming compression functions</h3><pre></pre><b><pre></pre></b><BR> -<pre><b>size_t -ZSTD_initCStream_srcSize(ZSTD_CStream* zcs, +<pre><b>ZSTD_DEPRECATED("use ZSTD_CCtx_reset, see zstd.h for detailed instructions") +size_t ZSTD_initCStream_srcSize(ZSTD_CStream* zcs, int compressionLevel, unsigned long long pledgedSrcSize); -</b><p> This function is deprecated, and equivalent to: +</b><p> This function is DEPRECATED, and equivalent to: ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only); ZSTD_CCtx_refCDict(zcs, NULL); // clear the dictionary (if any) ZSTD_CCtx_setParameter(zcs, ZSTD_c_compressionLevel, compressionLevel); @@ -1499,15 +1585,15 @@ ZSTD_initCStream_srcSize(ZSTD_CStream* zcs, pledgedSrcSize must be correct. If it is not known at init time, use ZSTD_CONTENTSIZE_UNKNOWN. Note that, for compatibility with older programs, "0" also disables frame content size field. It may be enabled in the future. - Note : this prototype will be marked as deprecated and generate compilation warnings on reaching v1.5.x + This prototype will generate compilation warnings. </p></pre><BR> -<pre><b>size_t -ZSTD_initCStream_usingDict(ZSTD_CStream* zcs, +<pre><b>ZSTD_DEPRECATED("use ZSTD_CCtx_reset, see zstd.h for detailed instructions") +size_t ZSTD_initCStream_usingDict(ZSTD_CStream* zcs, const void* dict, size_t dictSize, int compressionLevel); -</b><p> This function is deprecated, and is equivalent to: +</b><p> This function is DEPRECATED, and is equivalent to: ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only); ZSTD_CCtx_setParameter(zcs, ZSTD_c_compressionLevel, compressionLevel); ZSTD_CCtx_loadDictionary(zcs, dict, dictSize); @@ -1516,16 +1602,16 @@ ZSTD_initCStream_usingDict(ZSTD_CStream* zcs, dict == NULL or dictSize < 8, in which case no dict is used. Note: dict is loaded with ZSTD_dct_auto (treated as a full zstd dictionary if it begins with ZSTD_MAGIC_DICTIONARY, else as raw content) and ZSTD_dlm_byCopy. - Note : this prototype will be marked as deprecated and generate compilation warnings on reaching v1.5.x + This prototype will generate compilation warnings. </p></pre><BR> -<pre><b>size_t -ZSTD_initCStream_advanced(ZSTD_CStream* zcs, +<pre><b>ZSTD_DEPRECATED("use ZSTD_CCtx_reset, see zstd.h for detailed instructions") +size_t ZSTD_initCStream_advanced(ZSTD_CStream* zcs, const void* dict, size_t dictSize, ZSTD_parameters params, unsigned long long pledgedSrcSize); -</b><p> This function is deprecated, and is approximately equivalent to: +</b><p> This function is DEPRECATED, and is approximately equivalent to: ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only); // Pseudocode: Set each zstd parameter and leave the rest as-is. for ((param, value) : params) { @@ -1537,22 +1623,23 @@ ZSTD_initCStream_advanced(ZSTD_CStream* zcs, dict is loaded with ZSTD_dct_auto and ZSTD_dlm_byCopy. pledgedSrcSize must be correct. If srcSize is not known at init time, use value ZSTD_CONTENTSIZE_UNKNOWN. - Note : this prototype will be marked as deprecated and generate compilation warnings on reaching v1.5.x + This prototype will generate compilation warnings. </p></pre><BR> -<pre><b>size_t ZSTD_initCStream_usingCDict(ZSTD_CStream* zcs, const ZSTD_CDict* cdict); -</b><p> This function is deprecated, and equivalent to: +<pre><b>ZSTD_DEPRECATED("use ZSTD_CCtx_reset and ZSTD_CCtx_refCDict, see zstd.h for detailed instructions") +size_t ZSTD_initCStream_usingCDict(ZSTD_CStream* zcs, const ZSTD_CDict* cdict); +</b><p> This function is DEPRECATED, and equivalent to: ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only); ZSTD_CCtx_refCDict(zcs, cdict); note : cdict will just be referenced, and must outlive compression session - Note : this prototype will be marked as deprecated and generate compilation warnings on reaching v1.5.x + This prototype will generate compilation warnings. </p></pre><BR> -<pre><b>size_t -ZSTD_initCStream_usingCDict_advanced(ZSTD_CStream* zcs, +<pre><b>ZSTD_DEPRECATED("use ZSTD_CCtx_reset and ZSTD_CCtx_refCDict, see zstd.h for detailed instructions") +size_t ZSTD_initCStream_usingCDict_advanced(ZSTD_CStream* zcs, const ZSTD_CDict* cdict, ZSTD_frameParameters fParams, unsigned long long pledgedSrcSize); @@ -1568,14 +1655,18 @@ ZSTD_initCStream_usingCDict_advanced(ZSTD_CStream* zcs, same as ZSTD_initCStream_usingCDict(), with control over frame parameters. pledgedSrcSize must be correct. If srcSize is not known at init time, use value ZSTD_CONTENTSIZE_UNKNOWN. - Note : this prototype will be marked as deprecated and generate compilation warnings on reaching v1.5.x + This prototype will generate compilation warnings. </p></pre><BR> -<pre><b>size_t ZSTD_resetCStream(ZSTD_CStream* zcs, unsigned long long pledgedSrcSize); -</b><p> This function is deprecated, and is equivalent to: +<pre><b>ZSTD_DEPRECATED("use ZSTD_CCtx_reset, see zstd.h for detailed instructions") +size_t ZSTD_resetCStream(ZSTD_CStream* zcs, unsigned long long pledgedSrcSize); +</b><p> This function is DEPRECATED, and is equivalent to: ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only); ZSTD_CCtx_setPledgedSrcSize(zcs, pledgedSrcSize); + Note: ZSTD_resetCStream() interprets pledgedSrcSize == 0 as ZSTD_CONTENTSIZE_UNKNOWN, but + ZSTD_CCtx_setPledgedSrcSize() does not do the same, so ZSTD_CONTENTSIZE_UNKNOWN must be + explicitly specified. start a new frame, using same parameters from previous frame. This is typically useful to skip dictionary loading stage, since it will re-use it in-place. @@ -1585,7 +1676,7 @@ ZSTD_initCStream_usingCDict_advanced(ZSTD_CStream* zcs, For the time being, pledgedSrcSize==0 is interpreted as "srcSize unknown" for compatibility with older programs, but it will change to mean "empty" in future version, so use macro ZSTD_CONTENTSIZE_UNKNOWN instead. @return : 0, or an error code (which can be tested using ZSTD_isError()) - Note : this prototype will be marked as deprecated and generate compilation warnings on reaching v1.5.x + This prototype will generate compilation warnings. </p></pre><BR> @@ -1598,7 +1689,7 @@ ZSTD_initCStream_usingCDict_advanced(ZSTD_CStream* zcs, unsigned nbActiveWorkers; </b>/* MT only : nb of workers actively compressing at probe time */<b> } ZSTD_frameProgression; </b></pre><BR> -<pre><b>size_t ZSTD_toFlushNow(ZSTD_CCtx* cctx); +<pre><b>ZSTDLIB_STATIC_API size_t ZSTD_toFlushNow(ZSTD_CCtx* cctx); </b><p> Tell how many bytes are ready to be flushed immediately. Useful for multithreading scenarios (nbWorkers >= 1). Probe the oldest active job, defined as oldest job not yet entirely flushed, @@ -1614,7 +1705,7 @@ ZSTD_initCStream_usingCDict_advanced(ZSTD_CStream* zcs, </p></pre><BR> <h3>Advanced Streaming decompression functions</h3><pre></pre><b><pre></pre></b><BR> -<pre><b>size_t ZSTD_initDStream_usingDict(ZSTD_DStream* zds, const void* dict, size_t dictSize); +<pre><b>ZSTDLIB_STATIC_API size_t ZSTD_initDStream_usingDict(ZSTD_DStream* zds, const void* dict, size_t dictSize); </b><p> ZSTD_DCtx_reset(zds, ZSTD_reset_session_only); ZSTD_DCtx_loadDictionary(zds, dict, dictSize); @@ -1624,7 +1715,7 @@ ZSTD_initCStream_usingCDict_advanced(ZSTD_CStream* zcs, </p></pre><BR> -<pre><b>size_t ZSTD_initDStream_usingDDict(ZSTD_DStream* zds, const ZSTD_DDict* ddict); +<pre><b>ZSTDLIB_STATIC_API size_t ZSTD_initDStream_usingDDict(ZSTD_DStream* zds, const ZSTD_DDict* ddict); </b><p> ZSTD_DCtx_reset(zds, ZSTD_reset_session_only); ZSTD_DCtx_refDDict(zds, ddict); @@ -1634,7 +1725,7 @@ ZSTD_initCStream_usingCDict_advanced(ZSTD_CStream* zcs, </p></pre><BR> -<pre><b>size_t ZSTD_resetDStream(ZSTD_DStream* zds); +<pre><b>ZSTDLIB_STATIC_API size_t ZSTD_resetDStream(ZSTD_DStream* zds); </b><p> ZSTD_DCtx_reset(zds, ZSTD_reset_session_only); @@ -1656,8 +1747,7 @@ ZSTD_initCStream_usingCDict_advanced(ZSTD_CStream* zcs, ZSTD_CCtx object can be re-used multiple times within successive compression operations. Start by initializing a context. - Use ZSTD_compressBegin(), or ZSTD_compressBegin_usingDict() for dictionary compression, - or ZSTD_compressBegin_advanced(), for finer parameter control. + Use ZSTD_compressBegin(), or ZSTD_compressBegin_usingDict() for dictionary compression. It's also possible to duplicate a reference context which has already been initialized, using ZSTD_copyCCtx() Then, consume your input using ZSTD_compressContinue(). @@ -1679,13 +1769,13 @@ ZSTD_initCStream_usingCDict_advanced(ZSTD_CStream* zcs, `ZSTD_CCtx` object can be re-used (ZSTD_compressBegin()) to compress again. <BR></pre> -<h3>Buffer-less streaming compression functions</h3><pre></pre><b><pre>size_t ZSTD_compressBegin(ZSTD_CCtx* cctx, int compressionLevel); -size_t ZSTD_compressBegin_usingDict(ZSTD_CCtx* cctx, const void* dict, size_t dictSize, int compressionLevel); -size_t ZSTD_compressBegin_advanced(ZSTD_CCtx* cctx, const void* dict, size_t dictSize, ZSTD_parameters params, unsigned long long pledgedSrcSize); </b>/**< pledgedSrcSize : If srcSize is not known at init time, use ZSTD_CONTENTSIZE_UNKNOWN */<b> -size_t ZSTD_compressBegin_usingCDict(ZSTD_CCtx* cctx, const ZSTD_CDict* cdict); </b>/**< note: fails if cdict==NULL */<b> -size_t ZSTD_compressBegin_usingCDict_advanced(ZSTD_CCtx* const cctx, const ZSTD_CDict* const cdict, ZSTD_frameParameters const fParams, unsigned long long const pledgedSrcSize); </b>/* compression parameters are already set within cdict. pledgedSrcSize must be correct. If srcSize is not known, use macro ZSTD_CONTENTSIZE_UNKNOWN */<b> -size_t ZSTD_copyCCtx(ZSTD_CCtx* cctx, const ZSTD_CCtx* preparedCCtx, unsigned long long pledgedSrcSize); </b>/**< note: if pledgedSrcSize is not known, use ZSTD_CONTENTSIZE_UNKNOWN */<b> +<h3>Buffer-less streaming compression functions</h3><pre></pre><b><pre>ZSTDLIB_STATIC_API size_t ZSTD_compressBegin(ZSTD_CCtx* cctx, int compressionLevel); +ZSTDLIB_STATIC_API size_t ZSTD_compressBegin_usingDict(ZSTD_CCtx* cctx, const void* dict, size_t dictSize, int compressionLevel); +ZSTDLIB_STATIC_API size_t ZSTD_compressBegin_usingCDict(ZSTD_CCtx* cctx, const ZSTD_CDict* cdict); </b>/**< note: fails if cdict==NULL */<b> +ZSTDLIB_STATIC_API size_t ZSTD_copyCCtx(ZSTD_CCtx* cctx, const ZSTD_CCtx* preparedCCtx, unsigned long long pledgedSrcSize); </b>/**< note: if pledgedSrcSize is not known, use ZSTD_CONTENTSIZE_UNKNOWN */<b> </pre></b><BR> +<pre><b>size_t ZSTD_compressBegin_advanced(ZSTD_CCtx* cctx, const void* dict, size_t dictSize, ZSTD_parameters params, unsigned long long pledgedSrcSize); </b>/**< pledgedSrcSize : If srcSize is not known at init time, use ZSTD_CONTENTSIZE_UNKNOWN */<b> +</b></pre><BR> <a name="Chapter22"></a><h2>Buffer-less streaming decompression (synchronous mode)</h2><pre> A ZSTD_DCtx object is required to track streaming operations. Use ZSTD_createDCtx() / ZSTD_freeDCtx() to manage it. @@ -1768,12 +1858,12 @@ typedef struct { unsigned checksumFlag; } ZSTD_frameHeader; </pre></b><BR> -<pre><b>size_t ZSTD_getFrameHeader(ZSTD_frameHeader* zfhPtr, const void* src, size_t srcSize); </b>/**< doesn't consume input */<b> +<pre><b>ZSTDLIB_STATIC_API size_t ZSTD_getFrameHeader(ZSTD_frameHeader* zfhPtr, const void* src, size_t srcSize); </b>/**< doesn't consume input */<b> </b>/*! ZSTD_getFrameHeader_advanced() :<b> * same as ZSTD_getFrameHeader(), * with added capability to select a format (like ZSTD_f_zstd1_magicless) */ -size_t ZSTD_getFrameHeader_advanced(ZSTD_frameHeader* zfhPtr, const void* src, size_t srcSize, ZSTD_format_e format); -size_t ZSTD_decodingBufferSize_min(unsigned long long windowSize, unsigned long long frameContentSize); </b>/**< when frame content size is not known, pass in frameContentSize == ZSTD_CONTENTSIZE_UNKNOWN */<b> +ZSTDLIB_STATIC_API size_t ZSTD_getFrameHeader_advanced(ZSTD_frameHeader* zfhPtr, const void* src, size_t srcSize, ZSTD_format_e format); +ZSTDLIB_STATIC_API size_t ZSTD_decodingBufferSize_min(unsigned long long windowSize, unsigned long long frameContentSize); </b>/**< when frame content size is not known, pass in frameContentSize == ZSTD_CONTENTSIZE_UNKNOWN */<b> </b><p> decode Frame Header, or requires larger `srcSize`. @return : 0, `zfhPtr` is correctly filled, >0, `srcSize` is too small, value is wanted `srcSize` amount, @@ -1809,10 +1899,10 @@ size_t ZSTD_decodingBufferSize_min(unsigned long long windowSize, unsigned long Use ZSTD_insertBlock() for such a case. </p></pre><BR> -<h3>Raw zstd block functions</h3><pre></pre><b><pre>size_t ZSTD_getBlockSize (const ZSTD_CCtx* cctx); -size_t ZSTD_compressBlock (ZSTD_CCtx* cctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize); -size_t ZSTD_decompressBlock(ZSTD_DCtx* dctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize); -size_t ZSTD_insertBlock (ZSTD_DCtx* dctx, const void* blockStart, size_t blockSize); </b>/**< insert uncompressed block into `dctx` history. Useful for multi-blocks decompression. */<b> +<h3>Raw zstd block functions</h3><pre></pre><b><pre>ZSTDLIB_STATIC_API size_t ZSTD_getBlockSize (const ZSTD_CCtx* cctx); +ZSTDLIB_STATIC_API size_t ZSTD_compressBlock (ZSTD_CCtx* cctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize); +ZSTDLIB_STATIC_API size_t ZSTD_decompressBlock(ZSTD_DCtx* dctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize); +ZSTDLIB_STATIC_API size_t ZSTD_insertBlock (ZSTD_DCtx* dctx, const void* blockStart, size_t blockSize); </b>/**< insert uncompressed block into `dctx` history. Useful for multi-blocks decompression. */<b> </pre></b><BR> </html> </body> |