fixed API documentation
parent
f8d0b46a9f
commit
9f8b180d5d
|
@ -1,10 +1,10 @@
|
||||||
<html>
|
<html>
|
||||||
<head>
|
<head>
|
||||||
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
||||||
<title>zstd 1.4.5 Manual</title>
|
<title>zstd 1.4.6 Manual</title>
|
||||||
</head>
|
</head>
|
||||||
<body>
|
<body>
|
||||||
<h1>zstd 1.4.5 Manual</h1>
|
<h1>zstd 1.4.6 Manual</h1>
|
||||||
<hr>
|
<hr>
|
||||||
<a name="Contents"></a><h2>Contents</h2>
|
<a name="Contents"></a><h2>Contents</h2>
|
||||||
<ol>
|
<ol>
|
||||||
|
@ -27,16 +27,10 @@
|
||||||
<li><a href="#Chapter17">Advanced compression functions</a></li>
|
<li><a href="#Chapter17">Advanced compression functions</a></li>
|
||||||
<li><a href="#Chapter18">Advanced decompression functions</a></li>
|
<li><a href="#Chapter18">Advanced decompression functions</a></li>
|
||||||
<li><a href="#Chapter19">Advanced streaming functions</a></li>
|
<li><a href="#Chapter19">Advanced streaming functions</a></li>
|
||||||
<li><a href="#Chapter20">! ZSTD_initCStream_usingDict() :</a></li>
|
<li><a href="#Chapter20">Buffer-less and synchronous inner streaming functions</a></li>
|
||||||
<li><a href="#Chapter21">! ZSTD_initCStream_advanced() :</a></li>
|
<li><a href="#Chapter21">Buffer-less streaming compression (synchronous mode)</a></li>
|
||||||
<li><a href="#Chapter22">! ZSTD_initCStream_usingCDict() :</a></li>
|
<li><a href="#Chapter22">Buffer-less streaming decompression (synchronous mode)</a></li>
|
||||||
<li><a href="#Chapter23">! ZSTD_initCStream_usingCDict_advanced() :</a></li>
|
<li><a href="#Chapter23">Block level API</a></li>
|
||||||
<li><a href="#Chapter24">This function is deprecated, and is equivalent to:</a></li>
|
|
||||||
<li><a href="#Chapter25">This function is deprecated, and is equivalent to:</a></li>
|
|
||||||
<li><a href="#Chapter26">Buffer-less and synchronous inner streaming functions</a></li>
|
|
||||||
<li><a href="#Chapter27">Buffer-less streaming compression (synchronous mode)</a></li>
|
|
||||||
<li><a href="#Chapter28">Buffer-less streaming decompression (synchronous mode)</a></li>
|
|
||||||
<li><a href="#Chapter29">Block level API</a></li>
|
|
||||||
</ol>
|
</ol>
|
||||||
<hr>
|
<hr>
|
||||||
<a name="Chapter1"></a><h2>Introduction</h2><pre>
|
<a name="Chapter1"></a><h2>Introduction</h2><pre>
|
||||||
|
@ -72,8 +66,14 @@
|
||||||
|
|
||||||
<a name="Chapter2"></a><h2>Version</h2><pre></pre>
|
<a name="Chapter2"></a><h2>Version</h2><pre></pre>
|
||||||
|
|
||||||
<pre><b>unsigned ZSTD_versionNumber(void); </b>/**< to check runtime library version */<b>
|
<pre><b>unsigned ZSTD_versionNumber(void);
|
||||||
</b></pre><BR>
|
</b><p> Return runtime library version, the value is (MAJOR*100*100 + MINOR*100 + RELEASE).
|
||||||
|
</p></pre><BR>
|
||||||
|
|
||||||
|
<pre><b>const char* ZSTD_versionString(void);
|
||||||
|
</b><p> Return runtime library version, like "1.4.5". Requires v1.3.0+.
|
||||||
|
</p></pre><BR>
|
||||||
|
|
||||||
<a name="Chapter3"></a><h2>Simple API</h2><pre></pre>
|
<a name="Chapter3"></a><h2>Simple API</h2><pre></pre>
|
||||||
|
|
||||||
<pre><b>size_t ZSTD_compress( void* dst, size_t dstCapacity,
|
<pre><b>size_t ZSTD_compress( void* dst, size_t dstCapacity,
|
||||||
|
@ -277,7 +277,9 @@ size_t ZSTD_freeDCtx(ZSTD_DCtx* dctx);
|
||||||
* for large inputs, by finding large matches at long distance.
|
* for large inputs, by finding large matches at long distance.
|
||||||
* It increases memory usage and window size.
|
* It increases memory usage and window size.
|
||||||
* Note: enabling this parameter increases default ZSTD_c_windowLog to 128 MB
|
* Note: enabling this parameter increases default ZSTD_c_windowLog to 128 MB
|
||||||
* except when expressly set to a different value. */
|
* except when expressly set to a different value.
|
||||||
|
* Note: will be enabled by default if ZSTD_c_windowLog >= 128 MB and
|
||||||
|
* compression strategy >= ZSTD_btopt (== compression level 16+) */
|
||||||
ZSTD_c_ldmHashLog=161, </b>/* Size of the table for long distance matching, as a power of 2.<b>
|
ZSTD_c_ldmHashLog=161, </b>/* Size of the table for long distance matching, as a power of 2.<b>
|
||||||
* Larger values increase memory usage and compression ratio,
|
* Larger values increase memory usage and compression ratio,
|
||||||
* but decrease compression speed.
|
* but decrease compression speed.
|
||||||
|
@ -308,16 +310,20 @@ size_t ZSTD_freeDCtx(ZSTD_DCtx* dctx);
|
||||||
ZSTD_c_dictIDFlag=202, </b>/* When applicable, dictionary's ID is written into frame header (default:1) */<b>
|
ZSTD_c_dictIDFlag=202, </b>/* When applicable, dictionary's ID is written into frame header (default:1) */<b>
|
||||||
|
|
||||||
</b>/* multi-threading parameters */<b>
|
</b>/* multi-threading parameters */<b>
|
||||||
</b>/* These parameters are only useful if multi-threading is enabled (compiled with build macro ZSTD_MULTITHREAD).<b>
|
</b>/* These parameters are only active if multi-threading is enabled (compiled with build macro ZSTD_MULTITHREAD).<b>
|
||||||
* They return an error otherwise. */
|
* Otherwise, trying to set any other value than default (0) will be a no-op and return an error.
|
||||||
|
* In a situation where it's unknown if the linked library supports multi-threading or not,
|
||||||
|
* setting ZSTD_c_nbWorkers to any value >= 1 and consulting the return value provides a quick way to check this property.
|
||||||
|
*/
|
||||||
ZSTD_c_nbWorkers=400, </b>/* Select how many threads will be spawned to compress in parallel.<b>
|
ZSTD_c_nbWorkers=400, </b>/* Select how many threads will be spawned to compress in parallel.<b>
|
||||||
* When nbWorkers >= 1, triggers asynchronous mode when used with ZSTD_compressStream*() :
|
* When nbWorkers >= 1, triggers asynchronous mode when invoking ZSTD_compressStream*() :
|
||||||
* ZSTD_compressStream*() consumes input and flush output if possible, but immediately gives back control to caller,
|
* ZSTD_compressStream*() consumes input and flush output if possible, but immediately gives back control to caller,
|
||||||
* while compression work is performed in parallel, within worker threads.
|
* while compression is performed in parallel, within worker thread(s).
|
||||||
* (note : a strong exception to this rule is when first invocation of ZSTD_compressStream2() sets ZSTD_e_end :
|
* (note : a strong exception to this rule is when first invocation of ZSTD_compressStream2() sets ZSTD_e_end :
|
||||||
* in which case, ZSTD_compressStream2() delegates to ZSTD_compress2(), which is always a blocking call).
|
* in which case, ZSTD_compressStream2() delegates to ZSTD_compress2(), which is always a blocking call).
|
||||||
* More workers improve speed, but also increase memory usage.
|
* More workers improve speed, but also increase memory usage.
|
||||||
* Default value is `0`, aka "single-threaded mode" : no worker is spawned, compression is performed inside Caller's thread, all invocations are blocking */
|
* Default value is `0`, aka "single-threaded mode" : no worker is spawned,
|
||||||
|
* compression is performed inside Caller's thread, and all invocations are blocking */
|
||||||
ZSTD_c_jobSize=401, </b>/* Size of a compression job. This value is enforced only when nbWorkers >= 1.<b>
|
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.
|
* 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.
|
* 0 means default, which is dynamically determined based on compression parameters.
|
||||||
|
@ -346,6 +352,11 @@ size_t ZSTD_freeDCtx(ZSTD_DCtx* dctx);
|
||||||
* ZSTD_c_literalCompressionMode
|
* ZSTD_c_literalCompressionMode
|
||||||
* ZSTD_c_targetCBlockSize
|
* ZSTD_c_targetCBlockSize
|
||||||
* ZSTD_c_srcSizeHint
|
* ZSTD_c_srcSizeHint
|
||||||
|
* ZSTD_c_enableDedicatedDictSearch
|
||||||
|
* ZSTD_c_stableInBuffer
|
||||||
|
* ZSTD_c_stableOutBuffer
|
||||||
|
* ZSTD_c_blockDelimiters
|
||||||
|
* ZSTD_c_validateSequences
|
||||||
* Because they are not stable, it's necessary to define ZSTD_STATIC_LINKING_ONLY to access them.
|
* Because they are not stable, it's necessary to define ZSTD_STATIC_LINKING_ONLY to access them.
|
||||||
* note : never ever use experimentalParam? names directly;
|
* note : never ever use experimentalParam? names directly;
|
||||||
* also, the enums values themselves are unstable and can still change.
|
* also, the enums values themselves are unstable and can still change.
|
||||||
|
@ -356,7 +367,12 @@ size_t ZSTD_freeDCtx(ZSTD_DCtx* dctx);
|
||||||
ZSTD_c_experimentalParam4=1001,
|
ZSTD_c_experimentalParam4=1001,
|
||||||
ZSTD_c_experimentalParam5=1002,
|
ZSTD_c_experimentalParam5=1002,
|
||||||
ZSTD_c_experimentalParam6=1003,
|
ZSTD_c_experimentalParam6=1003,
|
||||||
ZSTD_c_experimentalParam7=1004
|
ZSTD_c_experimentalParam7=1004,
|
||||||
|
ZSTD_c_experimentalParam8=1005,
|
||||||
|
ZSTD_c_experimentalParam9=1006,
|
||||||
|
ZSTD_c_experimentalParam10=1007,
|
||||||
|
ZSTD_c_experimentalParam11=1008,
|
||||||
|
ZSTD_c_experimentalParam12=1009
|
||||||
} ZSTD_cParameter;
|
} ZSTD_cParameter;
|
||||||
</b></pre><BR>
|
</b></pre><BR>
|
||||||
<pre><b>typedef struct {
|
<pre><b>typedef struct {
|
||||||
|
@ -456,11 +472,13 @@ size_t ZSTD_freeDCtx(ZSTD_DCtx* dctx);
|
||||||
* At the time of this writing, they include :
|
* At the time of this writing, they include :
|
||||||
* ZSTD_d_format
|
* ZSTD_d_format
|
||||||
* ZSTD_d_stableOutBuffer
|
* ZSTD_d_stableOutBuffer
|
||||||
|
* ZSTD_d_forceIgnoreChecksum
|
||||||
* Because they are not stable, it's necessary to define ZSTD_STATIC_LINKING_ONLY to access them.
|
* Because they are not stable, it's necessary to define ZSTD_STATIC_LINKING_ONLY to access them.
|
||||||
* note : never ever use experimentalParam? names directly
|
* note : never ever use experimentalParam? names directly
|
||||||
*/
|
*/
|
||||||
ZSTD_d_experimentalParam1=1000,
|
ZSTD_d_experimentalParam1=1000,
|
||||||
ZSTD_d_experimentalParam2=1001
|
ZSTD_d_experimentalParam2=1001,
|
||||||
|
ZSTD_d_experimentalParam3=1002
|
||||||
|
|
||||||
} ZSTD_dParameter;
|
} ZSTD_dParameter;
|
||||||
</b></pre><BR>
|
</b></pre><BR>
|
||||||
|
@ -591,8 +609,9 @@ size_t ZSTD_freeCStream(ZSTD_CStream* zcs);
|
||||||
- Compression parameters cannot be changed once compression is started (save a list of exceptions in multi-threading mode)
|
- Compression parameters cannot be changed once compression is started (save a list of exceptions in multi-threading mode)
|
||||||
- output->pos must be <= dstCapacity, input->pos must be <= srcSize
|
- output->pos must be <= dstCapacity, input->pos must be <= srcSize
|
||||||
- output->pos and input->pos will be updated. They are guaranteed to remain below their respective limit.
|
- output->pos and input->pos will be updated. They are guaranteed to remain below their respective limit.
|
||||||
|
- endOp must be a valid directive
|
||||||
- When nbWorkers==0 (default), function is blocking : it completes its job before returning to caller.
|
- When nbWorkers==0 (default), function is blocking : it completes its job before returning to caller.
|
||||||
- When nbWorkers>=1, function is non-blocking : it just acquires a copy of input, and distributes jobs to internal worker threads, flush whatever is available,
|
- When nbWorkers>=1, function is non-blocking : it copies a portion of input, distributes jobs to internal worker threads, flush to output whatever is available,
|
||||||
and then immediately returns, just indicating that there is some data remaining to be flushed.
|
and then immediately returns, just indicating that there is some data remaining to be flushed.
|
||||||
The function nonetheless guarantees forward progress : it will return only after it reads or write at least 1+ byte.
|
The function nonetheless guarantees forward progress : it will return only after it reads or write at least 1+ byte.
|
||||||
- Exception : if the first call requests a ZSTD_e_end directive and provides enough dstCapacity, the function delegates to ZSTD_compress2() which is always blocking.
|
- Exception : if the first call requests a ZSTD_e_end directive and provides enough dstCapacity, the function delegates to ZSTD_compress2() which is always blocking.
|
||||||
|
@ -895,21 +914,40 @@ size_t ZSTD_sizeof_DDict(const ZSTD_DDict* ddict);
|
||||||
<BR></pre>
|
<BR></pre>
|
||||||
|
|
||||||
<pre><b>typedef struct {
|
<pre><b>typedef struct {
|
||||||
unsigned int matchPos; </b>/* Match pos in dst */<b>
|
unsigned int offset; </b>/* The offset of the match. (NOT the same as the offset code)<b>
|
||||||
</b>/* If seqDef.offset > 3, then this is seqDef.offset - 3<b>
|
* If offset == 0 and matchLength == 0, this sequence represents the last
|
||||||
* If seqDef.offset < 3, then this is the corresponding repeat offset
|
* literals in the block of litLength size.
|
||||||
* But if seqDef.offset < 3 and litLength == 0, this is the
|
*/
|
||||||
* repeat offset before the corresponding repeat offset
|
|
||||||
* And if seqDef.offset == 3 and litLength == 0, this is the
|
unsigned int litLength; </b>/* Literal length of the sequence. */<b>
|
||||||
* most recent repeat offset - 1
|
unsigned int matchLength; </b>/* Match length of the sequence. */<b>
|
||||||
*/
|
|
||||||
unsigned int offset;
|
</b>/* Note: Users of this API may provide a sequence with matchLength == litLength == offset == 0.<b>
|
||||||
unsigned int litLength; </b>/* Literal length */<b>
|
* In this case, we will treat the sequence as a marker for a block boundary.
|
||||||
unsigned int matchLength; </b>/* Match length */<b>
|
*/
|
||||||
</b>/* 0 when seq not rep and seqDef.offset otherwise<b>
|
|
||||||
* when litLength == 0 this will be <= 4, otherwise <= 3 like normal
|
unsigned int rep; </b>/* Represents which repeat offset is represented by the field 'offset'.<b>
|
||||||
*/
|
* Ranges from [0, 3].
|
||||||
unsigned int rep;
|
*
|
||||||
|
* Repeat offsets are essentially previous offsets from previous sequences sorted in
|
||||||
|
* recency order. For more detail, see doc/zstd_compression_format.md
|
||||||
|
*
|
||||||
|
* If rep == 0, then 'offset' does not contain a repeat offset.
|
||||||
|
* If rep > 0:
|
||||||
|
* If litLength != 0:
|
||||||
|
* rep == 1 --> offset == repeat_offset_1
|
||||||
|
* rep == 2 --> offset == repeat_offset_2
|
||||||
|
* rep == 3 --> offset == repeat_offset_3
|
||||||
|
* If litLength == 0:
|
||||||
|
* rep == 1 --> offset == repeat_offset_2
|
||||||
|
* rep == 2 --> offset == repeat_offset_3
|
||||||
|
* rep == 3 --> offset == repeat_offset_1 - 1
|
||||||
|
*
|
||||||
|
* Note: This field is optional. ZSTD_generateSequences() will calculate the value of
|
||||||
|
* 'rep', but repeat offsets do not necessarily need to be calculated from an external
|
||||||
|
* sequence provider's perspective. For example, ZSTD_compressSequences() does not
|
||||||
|
* use this 'rep' field at all (as of now).
|
||||||
|
*/
|
||||||
} ZSTD_Sequence;
|
} ZSTD_Sequence;
|
||||||
</b></pre><BR>
|
</b></pre><BR>
|
||||||
<pre><b>typedef struct {
|
<pre><b>typedef struct {
|
||||||
|
@ -951,6 +989,12 @@ size_t ZSTD_sizeof_DDict(const ZSTD_DDict* ddict);
|
||||||
* Decoder cannot recognise automatically this format, requiring this instruction. */
|
* Decoder cannot recognise automatically this format, requiring this instruction. */
|
||||||
} ZSTD_format_e;
|
} ZSTD_format_e;
|
||||||
</b></pre><BR>
|
</b></pre><BR>
|
||||||
|
<pre><b>typedef enum {
|
||||||
|
</b>/* Note: this enum controls ZSTD_d_forceIgnoreChecksum */<b>
|
||||||
|
ZSTD_d_validateChecksum = 0,
|
||||||
|
ZSTD_d_ignoreChecksum = 1
|
||||||
|
} ZSTD_forceIgnoreChecksum_e;
|
||||||
|
</b></pre><BR>
|
||||||
<pre><b>typedef enum {
|
<pre><b>typedef enum {
|
||||||
</b>/* Note: this enum and the behavior it controls are effectively internal<b>
|
</b>/* Note: this enum and the behavior it controls are effectively internal<b>
|
||||||
* implementation details of the compressor. They are expected to continue
|
* implementation details of the compressor. They are expected to continue
|
||||||
|
@ -1045,12 +1089,69 @@ size_t ZSTD_sizeof_DDict(const ZSTD_DDict* ddict);
|
||||||
or an error code (if srcSize is too small)
|
or an error code (if srcSize is too small)
|
||||||
</p></pre><BR>
|
</p></pre><BR>
|
||||||
|
|
||||||
<pre><b>size_t ZSTD_getSequences(ZSTD_CCtx* zc, ZSTD_Sequence* outSeqs,
|
<pre><b>typedef enum {
|
||||||
size_t outSeqsSize, const void* src, size_t srcSize);
|
ZSTD_sf_noBlockDelimiters = 0, </b>/* Representation of ZSTD_Sequence has no block delimiters, sequences only */<b>
|
||||||
</b><p> Extract sequences from the sequence store
|
ZSTD_sf_explicitBlockDelimiters = 1 </b>/* Representation of ZSTD_Sequence contains explicit block delimiters */<b>
|
||||||
|
} ZSTD_sequenceFormat_e;
|
||||||
|
</b></pre><BR>
|
||||||
|
<pre><b></b><p> Generate sequences using ZSTD_compress2, given a source buffer.
|
||||||
|
|
||||||
|
Each block will end with a dummy sequence
|
||||||
|
with offset == 0, matchLength == 0, and litLength == length of last literals.
|
||||||
|
litLength may be == 0, and if so, then the sequence of (of: 0 ml: 0 ll: 0)
|
||||||
|
simply acts as a block delimiter.
|
||||||
|
|
||||||
zc can be used to insert custom compression params.
|
zc can be used to insert custom compression params.
|
||||||
This function invokes ZSTD_compress2
|
This function invokes ZSTD_compress2
|
||||||
@return : number of sequences extracted
|
|
||||||
|
The output of this function can be fed into ZSTD_compressSequences() with CCtx
|
||||||
|
setting of ZSTD_c_blockDelimiters as ZSTD_sf_explicitBlockDelimiters
|
||||||
|
@return : number of sequences generated
|
||||||
|
|
||||||
|
</p></pre><BR>
|
||||||
|
|
||||||
|
<pre><b>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.
|
||||||
|
|
||||||
|
As such, the final generated result has no explicit representation of block boundaries,
|
||||||
|
and the final last literals segment is not represented in the sequences.
|
||||||
|
|
||||||
|
The output of this function can be fed into ZSTD_compressSequences() with CCtx
|
||||||
|
setting of ZSTD_c_blockDelimiters as ZSTD_sf_noBlockDelimiters
|
||||||
|
@return : number of sequences left after merging
|
||||||
|
|
||||||
|
</p></pre><BR>
|
||||||
|
|
||||||
|
<pre><b>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.
|
||||||
|
If a dictionary is included, then the cctx should reference the dict. (see: ZSTD_CCtx_refCDict(), ZSTD_CCtx_loadDictionary(), etc.)
|
||||||
|
The entire source is compressed into a single frame.
|
||||||
|
|
||||||
|
The compression behavior changes based on cctx params. In particular:
|
||||||
|
If ZSTD_c_blockDelimiters == ZSTD_sf_noBlockDelimiters, the array of ZSTD_Sequence is expected to contain
|
||||||
|
no block delimiters (defined in ZSTD_Sequence). Block boundaries are roughly determined based on
|
||||||
|
the block size derived from the cctx, and sequences may be split. This is the default setting.
|
||||||
|
|
||||||
|
If ZSTD_c_blockDelimiters == ZSTD_sf_explicitBlockDelimiters, the array of ZSTD_Sequence is expected to contain
|
||||||
|
block delimiters (defined in ZSTD_Sequence). Behavior is undefined if no block delimiters are provided.
|
||||||
|
|
||||||
|
If ZSTD_c_validateSequences == 0, this function will blindly accept the sequences provided. Invalid sequences cause undefined
|
||||||
|
behavior. If ZSTD_c_validateSequences == 1, then if sequence is invalid (see doc/zstd_compression_format.md for
|
||||||
|
specifics regarding offset/matchlength requirements) then the function will bail out and return an error.
|
||||||
|
|
||||||
|
In addition to the two adjustable experimental params, there are other important cctx params.
|
||||||
|
- ZSTD_c_minMatch MUST be set as less than or equal to the smallest match generated by the match finder. It has a minimum value of ZSTD_MINMATCH_MIN.
|
||||||
|
- ZSTD_c_compressionLevel accordingly adjusts the strength of the entropy coder, as it would in typical compression.
|
||||||
|
- ZSTD_c_windowLog affects offset validation: this function will return an error at higher debug levels if a provided offset
|
||||||
|
is larger than what the spec allows for a given window log and dictionary (if present). See: doc/zstd_compression_format.md
|
||||||
|
|
||||||
|
Note: Repcodes are, as of now, always re-calculated within this function, so ZSTD_Sequence::rep is unused.
|
||||||
|
Note 2: Once we integrate ability to ingest repcodes, the explicit block delims mode must respect those repcodes exactly,
|
||||||
|
and cannot emit an RLE block that disagrees with the repcode history
|
||||||
|
@return : final compressed size or a ZSTD error.
|
||||||
|
|
||||||
</p></pre><BR>
|
</p></pre><BR>
|
||||||
|
|
||||||
|
@ -1141,7 +1242,11 @@ ZSTD_CStream* ZSTD_initStaticCStream(void* workspace, size_t workspaceSize);
|
||||||
<pre><b>typedef void* (*ZSTD_allocFunction) (void* opaque, size_t size);
|
<pre><b>typedef void* (*ZSTD_allocFunction) (void* opaque, size_t size);
|
||||||
typedef void (*ZSTD_freeFunction) (void* opaque, void* address);
|
typedef void (*ZSTD_freeFunction) (void* opaque, void* address);
|
||||||
typedef struct { ZSTD_allocFunction customAlloc; ZSTD_freeFunction customFree; void* opaque; } ZSTD_customMem;
|
typedef struct { ZSTD_allocFunction customAlloc; ZSTD_freeFunction customFree; void* opaque; } ZSTD_customMem;
|
||||||
static ZSTD_customMem const ZSTD_defaultCMem = { NULL, NULL, NULL }; </b>/**< this constant defers to stdlib's functions */<b>
|
static
|
||||||
|
#ifdef __GNUC__
|
||||||
|
__attribute__((__unused__))
|
||||||
|
#endif
|
||||||
|
ZSTD_customMem const ZSTD_defaultCMem = { NULL, NULL, NULL }; </b>/**< this constant defers to stdlib's functions */<b>
|
||||||
</b><p> These prototypes make it possible to pass your own allocation/free functions.
|
</b><p> These prototypes make it possible to pass your own allocation/free functions.
|
||||||
ZSTD_customMem is provided at creation time, using ZSTD_create*_advanced() variants listed below.
|
ZSTD_customMem is provided at creation time, using ZSTD_create*_advanced() variants listed below.
|
||||||
All allocation/free operations will be completed using these custom variants instead of regular <stdlib.h> ones.
|
All allocation/free operations will be completed using these custom variants instead of regular <stdlib.h> ones.
|
||||||
|
@ -1270,8 +1375,10 @@ size_t ZSTD_freeCCtxParams(ZSTD_CCtx_params* params);
|
||||||
<pre><b>size_t ZSTD_CCtxParams_setParameter(ZSTD_CCtx_params* params, ZSTD_cParameter param, int value);
|
<pre><b>size_t ZSTD_CCtxParams_setParameter(ZSTD_CCtx_params* params, ZSTD_cParameter param, int value);
|
||||||
</b><p> Similar to ZSTD_CCtx_setParameter.
|
</b><p> Similar to ZSTD_CCtx_setParameter.
|
||||||
Set one compression parameter, selected by enum ZSTD_cParameter.
|
Set one compression parameter, selected by enum ZSTD_cParameter.
|
||||||
Parameters must be applied to a ZSTD_CCtx using ZSTD_CCtx_setParametersUsingCCtxParams().
|
Parameters must be applied to a ZSTD_CCtx using
|
||||||
@result : 0, or an error code (which can be tested with ZSTD_isError()).
|
ZSTD_CCtx_setParametersUsingCCtxParams().
|
||||||
|
@result : a code representing success or failure (which can be tested with
|
||||||
|
ZSTD_isError()).
|
||||||
|
|
||||||
</p></pre><BR>
|
</p></pre><BR>
|
||||||
|
|
||||||
|
@ -1348,6 +1455,13 @@ size_t ZSTD_freeCCtxParams(ZSTD_CCtx_params* params);
|
||||||
|
|
||||||
</p></pre><BR>
|
</p></pre><BR>
|
||||||
|
|
||||||
|
<pre><b>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);
|
<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.
|
</b><p> Instruct the decoder context about what kind of data to decode next.
|
||||||
This instruction is mandatory to decode data without a fully-formed header,
|
This instruction is mandatory to decode data without a fully-formed header,
|
||||||
|
@ -1371,24 +1485,29 @@ size_t ZSTD_freeCCtxParams(ZSTD_CCtx_params* params);
|
||||||
redundant functions will be deprecated, and then at some point removed.
|
redundant functions will be deprecated, and then at some point removed.
|
||||||
<BR></pre>
|
<BR></pre>
|
||||||
|
|
||||||
<h3>Advanced Streaming compression functions</h3><pre></pre><b><pre></b>/**! ZSTD_initCStream_srcSize() :<b>
|
<h3>Advanced Streaming compression functions</h3><pre></pre><b><pre></pre></b><BR>
|
||||||
* This function is deprecated, and equivalent to:
|
<pre><b>size_t
|
||||||
* 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);
|
|
||||||
* ZSTD_CCtx_setPledgedSrcSize(zcs, pledgedSrcSize);
|
|
||||||
*
|
|
||||||
* 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
|
|
||||||
*/
|
|
||||||
size_t
|
|
||||||
ZSTD_initCStream_srcSize(ZSTD_CStream* zcs,
|
ZSTD_initCStream_srcSize(ZSTD_CStream* zcs,
|
||||||
int compressionLevel,
|
int compressionLevel,
|
||||||
unsigned long long pledgedSrcSize);
|
unsigned long long pledgedSrcSize);
|
||||||
</pre></b><BR>
|
</b><p> This function is deprecated, and equivalent to:
|
||||||
<a name="Chapter20"></a><h2>! ZSTD_initCStream_usingDict() :</h2><pre> This function is deprecated, and is 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);
|
||||||
|
ZSTD_CCtx_setPledgedSrcSize(zcs, pledgedSrcSize);
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
</p></pre><BR>
|
||||||
|
|
||||||
|
<pre><b>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:
|
||||||
ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only);
|
ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only);
|
||||||
ZSTD_CCtx_setParameter(zcs, ZSTD_c_compressionLevel, compressionLevel);
|
ZSTD_CCtx_setParameter(zcs, ZSTD_c_compressionLevel, compressionLevel);
|
||||||
ZSTD_CCtx_loadDictionary(zcs, dict, dictSize);
|
ZSTD_CCtx_loadDictionary(zcs, dict, dictSize);
|
||||||
|
@ -1399,9 +1518,14 @@ ZSTD_initCStream_srcSize(ZSTD_CStream* zcs,
|
||||||
it begins with ZSTD_MAGIC_DICTIONARY, else as raw content) and ZSTD_dlm_byCopy.
|
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
|
Note : this prototype will be marked as deprecated and generate compilation warnings on reaching v1.5.x
|
||||||
|
|
||||||
<BR></pre>
|
</p></pre><BR>
|
||||||
|
|
||||||
<a name="Chapter21"></a><h2>! ZSTD_initCStream_advanced() :</h2><pre> This function is deprecated, and is approximately equivalent to:
|
<pre><b>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:
|
||||||
ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only);
|
ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only);
|
||||||
// Pseudocode: Set each zstd parameter and leave the rest as-is.
|
// Pseudocode: Set each zstd parameter and leave the rest as-is.
|
||||||
for ((param, value) : params) {
|
for ((param, value) : params) {
|
||||||
|
@ -1415,18 +1539,24 @@ ZSTD_initCStream_srcSize(ZSTD_CStream* zcs,
|
||||||
If srcSize is not known at init time, use value ZSTD_CONTENTSIZE_UNKNOWN.
|
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
|
Note : this prototype will be marked as deprecated and generate compilation warnings on reaching v1.5.x
|
||||||
|
|
||||||
<BR></pre>
|
</p></pre><BR>
|
||||||
|
|
||||||
<a name="Chapter22"></a><h2>! ZSTD_initCStream_usingCDict() :</h2><pre> This function is deprecated, and equivalent to:
|
<pre><b>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_reset(zcs, ZSTD_reset_session_only);
|
||||||
ZSTD_CCtx_refCDict(zcs, cdict);
|
ZSTD_CCtx_refCDict(zcs, cdict);
|
||||||
|
|
||||||
note : cdict will just be referenced, and must outlive compression session
|
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
|
Note : this prototype will be marked as deprecated and generate compilation warnings on reaching v1.5.x
|
||||||
|
|
||||||
<BR></pre>
|
</p></pre><BR>
|
||||||
|
|
||||||
<a name="Chapter23"></a><h2>! ZSTD_initCStream_usingCDict_advanced() :</h2><pre> This function is DEPRECATED, and is approximately equivalent to:
|
<pre><b>size_t
|
||||||
|
ZSTD_initCStream_usingCDict_advanced(ZSTD_CStream* zcs,
|
||||||
|
const ZSTD_CDict* cdict,
|
||||||
|
ZSTD_frameParameters fParams,
|
||||||
|
unsigned long long pledgedSrcSize);
|
||||||
|
</b><p> This function is DEPRECATED, and is approximately equivalent to:
|
||||||
ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only);
|
ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only);
|
||||||
// Pseudocode: Set each zstd frame parameter and leave the rest as-is.
|
// Pseudocode: Set each zstd frame parameter and leave the rest as-is.
|
||||||
for ((fParam, value) : fParams) {
|
for ((fParam, value) : fParams) {
|
||||||
|
@ -1440,7 +1570,7 @@ ZSTD_initCStream_srcSize(ZSTD_CStream* zcs,
|
||||||
value ZSTD_CONTENTSIZE_UNKNOWN.
|
value ZSTD_CONTENTSIZE_UNKNOWN.
|
||||||
Note : this prototype will be marked as deprecated and generate compilation warnings on reaching v1.5.x
|
Note : this prototype will be marked as deprecated and generate compilation warnings on reaching v1.5.x
|
||||||
|
|
||||||
<BR></pre>
|
</p></pre><BR>
|
||||||
|
|
||||||
<pre><b>size_t ZSTD_resetCStream(ZSTD_CStream* zcs, unsigned long long pledgedSrcSize);
|
<pre><b>size_t ZSTD_resetCStream(ZSTD_CStream* zcs, unsigned long long pledgedSrcSize);
|
||||||
</b><p> This function is deprecated, and is equivalent to:
|
</b><p> This function is deprecated, and is equivalent to:
|
||||||
|
@ -1483,42 +1613,44 @@ ZSTD_initCStream_srcSize(ZSTD_CStream* zcs,
|
||||||
|
|
||||||
</p></pre><BR>
|
</p></pre><BR>
|
||||||
|
|
||||||
<h3>Advanced Streaming decompression functions</h3><pre></pre><b><pre></b>/**<b>
|
<h3>Advanced Streaming decompression functions</h3><pre></pre><b><pre></pre></b><BR>
|
||||||
* This function is deprecated, and is equivalent to:
|
<pre><b>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_reset(zds, ZSTD_reset_session_only);
|
||||||
* ZSTD_DCtx_loadDictionary(zds, dict, dictSize);
|
ZSTD_DCtx_loadDictionary(zds, dict, dictSize);
|
||||||
*
|
|
||||||
* note: no dictionary will be used if dict == NULL or dictSize < 8
|
note: no dictionary will be used if dict == NULL or dictSize < 8
|
||||||
* Note : this prototype will be marked as deprecated and generate compilation warnings on reaching v1.5.x
|
Note : this prototype will be marked as deprecated and generate compilation warnings on reaching v1.5.x
|
||||||
*/
|
|
||||||
size_t ZSTD_initDStream_usingDict(ZSTD_DStream* zds, const void* dict, size_t dictSize);
|
</p></pre><BR>
|
||||||
</pre></b><BR>
|
|
||||||
<a name="Chapter24"></a><h2>This function is deprecated, and is equivalent to:</h2><pre>
|
<pre><b>size_t ZSTD_initDStream_usingDDict(ZSTD_DStream* zds, const ZSTD_DDict* ddict);
|
||||||
|
</b><p>
|
||||||
ZSTD_DCtx_reset(zds, ZSTD_reset_session_only);
|
ZSTD_DCtx_reset(zds, ZSTD_reset_session_only);
|
||||||
ZSTD_DCtx_refDDict(zds, ddict);
|
ZSTD_DCtx_refDDict(zds, ddict);
|
||||||
|
|
||||||
note : ddict is referenced, it must outlive decompression session
|
note : ddict is referenced, it must outlive decompression session
|
||||||
Note : this prototype will be marked as deprecated and generate compilation warnings on reaching v1.5.x
|
Note : this prototype will be marked as deprecated and generate compilation warnings on reaching v1.5.x
|
||||||
|
|
||||||
<BR></pre>
|
</p></pre><BR>
|
||||||
|
|
||||||
<a name="Chapter25"></a><h2>This function is deprecated, and is equivalent to:</h2><pre>
|
<pre><b>size_t ZSTD_resetDStream(ZSTD_DStream* zds);
|
||||||
|
</b><p>
|
||||||
ZSTD_DCtx_reset(zds, ZSTD_reset_session_only);
|
ZSTD_DCtx_reset(zds, ZSTD_reset_session_only);
|
||||||
|
|
||||||
re-use decompression parameters from previous init; saves dictionary loading
|
re-use decompression parameters from previous init; saves dictionary loading
|
||||||
Note : this prototype will be marked as deprecated and generate compilation warnings on reaching v1.5.x
|
Note : this prototype will be marked as deprecated and generate compilation warnings on reaching v1.5.x
|
||||||
|
|
||||||
<BR></pre>
|
</p></pre><BR>
|
||||||
|
|
||||||
<a name="Chapter26"></a><h2>Buffer-less and synchronous inner streaming functions</h2><pre>
|
<a name="Chapter20"></a><h2>Buffer-less and synchronous inner streaming functions</h2><pre>
|
||||||
This is an advanced API, giving full control over buffer management, for users which need direct control over memory.
|
This is an advanced API, giving full control over buffer management, for users which need direct control over memory.
|
||||||
But it's also a complex one, with several restrictions, documented below.
|
But it's also a complex one, with several restrictions, documented below.
|
||||||
Prefer normal streaming API for an easier experience.
|
Prefer normal streaming API for an easier experience.
|
||||||
|
|
||||||
<BR></pre>
|
<BR></pre>
|
||||||
|
|
||||||
<a name="Chapter27"></a><h2>Buffer-less streaming compression (synchronous mode)</h2><pre>
|
<a name="Chapter21"></a><h2>Buffer-less streaming compression (synchronous mode)</h2><pre>
|
||||||
A ZSTD_CCtx object is required to track streaming operations.
|
A ZSTD_CCtx object is required to track streaming operations.
|
||||||
Use ZSTD_createCCtx() / ZSTD_freeCCtx() to manage resource.
|
Use ZSTD_createCCtx() / ZSTD_freeCCtx() to manage resource.
|
||||||
ZSTD_CCtx object can be re-used multiple times within successive compression operations.
|
ZSTD_CCtx object can be re-used multiple times within successive compression operations.
|
||||||
|
@ -1554,7 +1686,7 @@ size_t ZSTD_compressBegin_usingCDict(ZSTD_CCtx* cctx, const ZSTD_CDict* cdict);
|
||||||
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_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>
|
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><BR>
|
||||||
<a name="Chapter28"></a><h2>Buffer-less streaming decompression (synchronous mode)</h2><pre>
|
<a name="Chapter22"></a><h2>Buffer-less streaming decompression (synchronous mode)</h2><pre>
|
||||||
A ZSTD_DCtx object is required to track streaming operations.
|
A ZSTD_DCtx object is required to track streaming operations.
|
||||||
Use ZSTD_createDCtx() / ZSTD_freeDCtx() to manage it.
|
Use ZSTD_createDCtx() / ZSTD_freeDCtx() to manage it.
|
||||||
A ZSTD_DCtx object can be re-used multiple times.
|
A ZSTD_DCtx object can be re-used multiple times.
|
||||||
|
@ -1650,7 +1782,7 @@ size_t ZSTD_decodingBufferSize_min(unsigned long long windowSize, unsigned long
|
||||||
|
|
||||||
<pre><b>typedef enum { ZSTDnit_frameHeader, ZSTDnit_blockHeader, ZSTDnit_block, ZSTDnit_lastBlock, ZSTDnit_checksum, ZSTDnit_skippableFrame } ZSTD_nextInputType_e;
|
<pre><b>typedef enum { ZSTDnit_frameHeader, ZSTDnit_blockHeader, ZSTDnit_block, ZSTDnit_lastBlock, ZSTDnit_checksum, ZSTDnit_skippableFrame } ZSTD_nextInputType_e;
|
||||||
</b></pre><BR>
|
</b></pre><BR>
|
||||||
<a name="Chapter29"></a><h2>Block level API</h2><pre></pre>
|
<a name="Chapter23"></a><h2>Block level API</h2><pre></pre>
|
||||||
|
|
||||||
<pre><b></b><p> Frame metadata cost is typically ~12 bytes, which can be non-negligible for very small blocks (< 100 bytes).
|
<pre><b></b><p> Frame metadata cost is typically ~12 bytes, which can be non-negligible for very small blocks (< 100 bytes).
|
||||||
But users will have to take in charge needed metadata to regenerate data, such as compressed and content sizes.
|
But users will have to take in charge needed metadata to regenerate data, such as compressed and content sizes.
|
||||||
|
|
66
lib/zstd.h
66
lib/zstd.h
|
@ -339,7 +339,7 @@ typedef enum {
|
||||||
* for large inputs, by finding large matches at long distance.
|
* for large inputs, by finding large matches at long distance.
|
||||||
* It increases memory usage and window size.
|
* It increases memory usage and window size.
|
||||||
* Note: enabling this parameter increases default ZSTD_c_windowLog to 128 MB
|
* Note: enabling this parameter increases default ZSTD_c_windowLog to 128 MB
|
||||||
* except when expressly set to a different value.
|
* except when expressly set to a different value.
|
||||||
* Note: will be enabled by default if ZSTD_c_windowLog >= 128 MB and
|
* Note: will be enabled by default if ZSTD_c_windowLog >= 128 MB and
|
||||||
* compression strategy >= ZSTD_btopt (== compression level 16+) */
|
* compression strategy >= ZSTD_btopt (== compression level 16+) */
|
||||||
ZSTD_c_ldmHashLog=161, /* Size of the table for long distance matching, as a power of 2.
|
ZSTD_c_ldmHashLog=161, /* Size of the table for long distance matching, as a power of 2.
|
||||||
|
@ -1135,13 +1135,13 @@ typedef struct {
|
||||||
/* Note: Users of this API may provide a sequence with matchLength == litLength == offset == 0.
|
/* Note: Users of this API may provide a sequence with matchLength == litLength == offset == 0.
|
||||||
* In this case, we will treat the sequence as a marker for a block boundary.
|
* In this case, we will treat the sequence as a marker for a block boundary.
|
||||||
*/
|
*/
|
||||||
|
|
||||||
unsigned int rep; /* Represents which repeat offset is represented by the field 'offset'.
|
unsigned int rep; /* Represents which repeat offset is represented by the field 'offset'.
|
||||||
* Ranges from [0, 3].
|
* Ranges from [0, 3].
|
||||||
*
|
*
|
||||||
* Repeat offsets are essentially previous offsets from previous sequences sorted in
|
* Repeat offsets are essentially previous offsets from previous sequences sorted in
|
||||||
* recency order. For more detail, see doc/zstd_compression_format.md
|
* recency order. For more detail, see doc/zstd_compression_format.md
|
||||||
*
|
*
|
||||||
* If rep == 0, then 'offset' does not contain a repeat offset.
|
* If rep == 0, then 'offset' does not contain a repeat offset.
|
||||||
* If rep > 0:
|
* If rep > 0:
|
||||||
* If litLength != 0:
|
* If litLength != 0:
|
||||||
|
@ -1152,7 +1152,7 @@ typedef struct {
|
||||||
* rep == 1 --> offset == repeat_offset_2
|
* rep == 1 --> offset == repeat_offset_2
|
||||||
* rep == 2 --> offset == repeat_offset_3
|
* rep == 2 --> offset == repeat_offset_3
|
||||||
* rep == 3 --> offset == repeat_offset_1 - 1
|
* rep == 3 --> offset == repeat_offset_1 - 1
|
||||||
*
|
*
|
||||||
* Note: This field is optional. ZSTD_generateSequences() will calculate the value of
|
* Note: This field is optional. ZSTD_generateSequences() will calculate the value of
|
||||||
* 'rep', but repeat offsets do not necessarily need to be calculated from an external
|
* 'rep', but repeat offsets do not necessarily need to be calculated from an external
|
||||||
* sequence provider's perspective. For example, ZSTD_compressSequences() does not
|
* sequence provider's perspective. For example, ZSTD_compressSequences() does not
|
||||||
|
@ -1309,15 +1309,15 @@ typedef enum {
|
||||||
|
|
||||||
/*! ZSTD_generateSequences() :
|
/*! ZSTD_generateSequences() :
|
||||||
* Generate sequences using ZSTD_compress2, given a source buffer.
|
* Generate sequences using ZSTD_compress2, given a source buffer.
|
||||||
*
|
*
|
||||||
* Each block will end with a dummy sequence
|
* Each block will end with a dummy sequence
|
||||||
* with offset == 0, matchLength == 0, and litLength == length of last literals.
|
* with offset == 0, matchLength == 0, and litLength == length of last literals.
|
||||||
* litLength may be == 0, and if so, then the sequence of (of: 0 ml: 0 ll: 0)
|
* litLength may be == 0, and if so, then the sequence of (of: 0 ml: 0 ll: 0)
|
||||||
* simply acts as a block delimiter.
|
* simply acts as a block delimiter.
|
||||||
*
|
*
|
||||||
* zc can be used to insert custom compression params.
|
* zc can be used to insert custom compression params.
|
||||||
* This function invokes ZSTD_compress2
|
* This function invokes ZSTD_compress2
|
||||||
*
|
*
|
||||||
* The output of this function can be fed into ZSTD_compressSequences() with CCtx
|
* The output of this function can be fed into ZSTD_compressSequences() with CCtx
|
||||||
* setting of ZSTD_c_blockDelimiters as ZSTD_sf_explicitBlockDelimiters
|
* setting of ZSTD_c_blockDelimiters as ZSTD_sf_explicitBlockDelimiters
|
||||||
* @return : number of sequences generated
|
* @return : number of sequences generated
|
||||||
|
@ -1329,10 +1329,10 @@ ZSTDLIB_API size_t ZSTD_generateSequences(ZSTD_CCtx* zc, ZSTD_Sequence* outSeqs,
|
||||||
/*! ZSTD_mergeBlockDelimiters() :
|
/*! ZSTD_mergeBlockDelimiters() :
|
||||||
* Given an array of ZSTD_Sequence, remove all sequences that represent block delimiters/last literals
|
* 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.
|
* by merging them into into the literals of the next sequence.
|
||||||
*
|
*
|
||||||
* As such, the final generated result has no explicit representation of block boundaries,
|
* As such, the final generated result has no explicit representation of block boundaries,
|
||||||
* and the final last literals segment is not represented in the sequences.
|
* and the final last literals segment is not represented in the sequences.
|
||||||
*
|
*
|
||||||
* The output of this function can be fed into ZSTD_compressSequences() with CCtx
|
* The output of this function can be fed into ZSTD_compressSequences() with CCtx
|
||||||
* setting of ZSTD_c_blockDelimiters as ZSTD_sf_noBlockDelimiters
|
* setting of ZSTD_c_blockDelimiters as ZSTD_sf_noBlockDelimiters
|
||||||
* @return : number of sequences left after merging
|
* @return : number of sequences left after merging
|
||||||
|
@ -1342,26 +1342,26 @@ ZSTDLIB_API size_t ZSTD_mergeBlockDelimiters(ZSTD_Sequence* sequences, size_t se
|
||||||
/*! ZSTD_compressSequences() :
|
/*! ZSTD_compressSequences() :
|
||||||
* Compress an array of ZSTD_Sequence, generated from the original source buffer, into dst.
|
* Compress an array of ZSTD_Sequence, generated from the original source buffer, into dst.
|
||||||
* If a dictionary is included, then the cctx should reference the dict. (see: ZSTD_CCtx_refCDict(), ZSTD_CCtx_loadDictionary(), etc.)
|
* If a dictionary is included, then the cctx should reference the dict. (see: ZSTD_CCtx_refCDict(), ZSTD_CCtx_loadDictionary(), etc.)
|
||||||
* The entire source is compressed into a single frame.
|
* The entire source is compressed into a single frame.
|
||||||
*
|
*
|
||||||
* The compression behavior changes based on cctx params. In particular:
|
* The compression behavior changes based on cctx params. In particular:
|
||||||
* If ZSTD_c_blockDelimiters == ZSTD_sf_noBlockDelimiters, the array of ZSTD_Sequence is expected to contain
|
* If ZSTD_c_blockDelimiters == ZSTD_sf_noBlockDelimiters, the array of ZSTD_Sequence is expected to contain
|
||||||
* no block delimiters (defined in ZSTD_Sequence). Block boundaries are roughly determined based on
|
* no block delimiters (defined in ZSTD_Sequence). Block boundaries are roughly determined based on
|
||||||
* the block size derived from the cctx, and sequences may be split. This is the default setting.
|
* the block size derived from the cctx, and sequences may be split. This is the default setting.
|
||||||
*
|
*
|
||||||
* If ZSTD_c_blockDelimiters == ZSTD_sf_explicitBlockDelimiters, the array of ZSTD_Sequence is expected to contain
|
* If ZSTD_c_blockDelimiters == ZSTD_sf_explicitBlockDelimiters, the array of ZSTD_Sequence is expected to contain
|
||||||
* block delimiters (defined in ZSTD_Sequence). Behavior is undefined if no block delimiters are provided.
|
* block delimiters (defined in ZSTD_Sequence). Behavior is undefined if no block delimiters are provided.
|
||||||
*
|
*
|
||||||
* If ZSTD_c_validateSequences == 0, this function will blindly accept the sequences provided. Invalid sequences cause undefined
|
* If ZSTD_c_validateSequences == 0, this function will blindly accept the sequences provided. Invalid sequences cause undefined
|
||||||
* behavior. If ZSTD_c_validateSequences == 1, then if sequence is invalid (see doc/zstd_compression_format.md for
|
* behavior. If ZSTD_c_validateSequences == 1, then if sequence is invalid (see doc/zstd_compression_format.md for
|
||||||
* specifics regarding offset/matchlength requirements) then the function will bail out and return an error.
|
* specifics regarding offset/matchlength requirements) then the function will bail out and return an error.
|
||||||
*
|
*
|
||||||
* In addition to the two adjustable experimental params, there are other important cctx params.
|
* In addition to the two adjustable experimental params, there are other important cctx params.
|
||||||
* - ZSTD_c_minMatch MUST be set as less than or equal to the smallest match generated by the match finder. It has a minimum value of ZSTD_MINMATCH_MIN.
|
* - ZSTD_c_minMatch MUST be set as less than or equal to the smallest match generated by the match finder. It has a minimum value of ZSTD_MINMATCH_MIN.
|
||||||
* - ZSTD_c_compressionLevel accordingly adjusts the strength of the entropy coder, as it would in typical compression.
|
* - ZSTD_c_compressionLevel accordingly adjusts the strength of the entropy coder, as it would in typical compression.
|
||||||
* - ZSTD_c_windowLog affects offset validation: this function will return an error at higher debug levels if a provided offset
|
* - ZSTD_c_windowLog affects offset validation: this function will return an error at higher debug levels if a provided offset
|
||||||
* is larger than what the spec allows for a given window log and dictionary (if present). See: doc/zstd_compression_format.md
|
* is larger than what the spec allows for a given window log and dictionary (if present). See: doc/zstd_compression_format.md
|
||||||
*
|
*
|
||||||
* Note: Repcodes are, as of now, always re-calculated within this function, so ZSTD_Sequence::rep is unused.
|
* Note: Repcodes are, as of now, always re-calculated within this function, so ZSTD_Sequence::rep is unused.
|
||||||
* Note 2: Once we integrate ability to ingest repcodes, the explicit block delims mode must respect those repcodes exactly,
|
* Note 2: Once we integrate ability to ingest repcodes, the explicit block delims mode must respect those repcodes exactly,
|
||||||
* and cannot emit an RLE block that disagrees with the repcode history
|
* and cannot emit an RLE block that disagrees with the repcode history
|
||||||
|
@ -1513,7 +1513,7 @@ ZSTDLIB_API ZSTD_threadPool* ZSTD_createThreadPool(size_t numThreads);
|
||||||
ZSTDLIB_API void ZSTD_freeThreadPool (ZSTD_threadPool* pool);
|
ZSTDLIB_API void ZSTD_freeThreadPool (ZSTD_threadPool* pool);
|
||||||
ZSTDLIB_API size_t ZSTD_CCtx_refThreadPool(ZSTD_CCtx* cctx, ZSTD_threadPool* pool);
|
ZSTDLIB_API size_t ZSTD_CCtx_refThreadPool(ZSTD_CCtx* cctx, ZSTD_threadPool* pool);
|
||||||
|
|
||||||
/**
|
/*
|
||||||
* This API is temporary and is expected to change or disappear in the future!
|
* This API is temporary and is expected to change or disappear in the future!
|
||||||
*/
|
*/
|
||||||
ZSTDLIB_API ZSTD_CDict* ZSTD_createCDict_advanced2(
|
ZSTDLIB_API ZSTD_CDict* ZSTD_createCDict_advanced2(
|
||||||
|
@ -1771,9 +1771,9 @@ ZSTDLIB_API size_t ZSTD_CCtx_refPrefix_advanced(ZSTD_CCtx* cctx, const void* pre
|
||||||
|
|
||||||
/* ZSTD_c_blockDelimiters
|
/* ZSTD_c_blockDelimiters
|
||||||
* Default is 0 == ZSTD_sf_noBlockDelimiters.
|
* Default is 0 == ZSTD_sf_noBlockDelimiters.
|
||||||
*
|
*
|
||||||
* For use with sequence compression API: ZSTD_compressSequences().
|
* For use with sequence compression API: ZSTD_compressSequences().
|
||||||
*
|
*
|
||||||
* Designates whether or not the given array of ZSTD_Sequence contains block delimiters
|
* Designates whether or not the given array of ZSTD_Sequence contains block delimiters
|
||||||
* and last literals, which are defined as sequences with offset == 0 and matchLength == 0.
|
* and last literals, which are defined as sequences with offset == 0 and matchLength == 0.
|
||||||
* See the definition of ZSTD_Sequence for more specifics.
|
* See the definition of ZSTD_Sequence for more specifics.
|
||||||
|
@ -1782,18 +1782,18 @@ ZSTDLIB_API size_t ZSTD_CCtx_refPrefix_advanced(ZSTD_CCtx* cctx, const void* pre
|
||||||
|
|
||||||
/* ZSTD_c_validateSequences
|
/* ZSTD_c_validateSequences
|
||||||
* Default is 0 == disabled. Set to 1 to enable sequence validation.
|
* Default is 0 == disabled. Set to 1 to enable sequence validation.
|
||||||
*
|
*
|
||||||
* For use with sequence compression API: ZSTD_compressSequences().
|
* For use with sequence compression API: ZSTD_compressSequences().
|
||||||
* Designates whether or not we validate sequences provided to ZSTD_compressSequences()
|
* Designates whether or not we validate sequences provided to ZSTD_compressSequences()
|
||||||
* during function execution.
|
* during function execution.
|
||||||
*
|
*
|
||||||
* Without validation, providing a sequence that does not conform to the zstd spec will cause
|
* Without validation, providing a sequence that does not conform to the zstd spec will cause
|
||||||
* undefined behavior, and may produce a corrupted block.
|
* undefined behavior, and may produce a corrupted block.
|
||||||
*
|
*
|
||||||
* With validation enabled, a if sequence is invalid (see doc/zstd_compression_format.md for
|
* With validation enabled, a if sequence is invalid (see doc/zstd_compression_format.md for
|
||||||
* specifics regarding offset/matchlength requirements) then the function will bail out and
|
* specifics regarding offset/matchlength requirements) then the function will bail out and
|
||||||
* return an error.
|
* return an error.
|
||||||
*
|
*
|
||||||
*/
|
*/
|
||||||
#define ZSTD_c_validateSequences ZSTD_c_experimentalParam12
|
#define ZSTD_c_validateSequences ZSTD_c_experimentalParam12
|
||||||
|
|
||||||
|
@ -2010,7 +2010,8 @@ ZSTDLIB_API size_t ZSTD_decompressStream_simpleArgs (
|
||||||
********************************************************************/
|
********************************************************************/
|
||||||
|
|
||||||
/*===== Advanced Streaming compression functions =====*/
|
/*===== Advanced Streaming compression functions =====*/
|
||||||
/**! ZSTD_initCStream_srcSize() :
|
|
||||||
|
/*! ZSTD_initCStream_srcSize() :
|
||||||
* This function is deprecated, and equivalent to:
|
* This function is deprecated, and equivalent to:
|
||||||
* ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only);
|
* ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only);
|
||||||
* ZSTD_CCtx_refCDict(zcs, NULL); // clear the dictionary (if any)
|
* ZSTD_CCtx_refCDict(zcs, NULL); // clear the dictionary (if any)
|
||||||
|
@ -2027,7 +2028,7 @@ ZSTD_initCStream_srcSize(ZSTD_CStream* zcs,
|
||||||
int compressionLevel,
|
int compressionLevel,
|
||||||
unsigned long long pledgedSrcSize);
|
unsigned long long pledgedSrcSize);
|
||||||
|
|
||||||
/**! ZSTD_initCStream_usingDict() :
|
/*! ZSTD_initCStream_usingDict() :
|
||||||
* This function is deprecated, and is equivalent to:
|
* This function is deprecated, and is equivalent to:
|
||||||
* ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only);
|
* ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only);
|
||||||
* ZSTD_CCtx_setParameter(zcs, ZSTD_c_compressionLevel, compressionLevel);
|
* ZSTD_CCtx_setParameter(zcs, ZSTD_c_compressionLevel, compressionLevel);
|
||||||
|
@ -2044,7 +2045,7 @@ ZSTD_initCStream_usingDict(ZSTD_CStream* zcs,
|
||||||
const void* dict, size_t dictSize,
|
const void* dict, size_t dictSize,
|
||||||
int compressionLevel);
|
int compressionLevel);
|
||||||
|
|
||||||
/**! ZSTD_initCStream_advanced() :
|
/*! ZSTD_initCStream_advanced() :
|
||||||
* This function is deprecated, and is approximately equivalent to:
|
* This function is deprecated, and is approximately equivalent to:
|
||||||
* ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only);
|
* ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only);
|
||||||
* // Pseudocode: Set each zstd parameter and leave the rest as-is.
|
* // Pseudocode: Set each zstd parameter and leave the rest as-is.
|
||||||
|
@ -2065,7 +2066,7 @@ ZSTD_initCStream_advanced(ZSTD_CStream* zcs,
|
||||||
ZSTD_parameters params,
|
ZSTD_parameters params,
|
||||||
unsigned long long pledgedSrcSize);
|
unsigned long long pledgedSrcSize);
|
||||||
|
|
||||||
/**! ZSTD_initCStream_usingCDict() :
|
/*! ZSTD_initCStream_usingCDict() :
|
||||||
* This function is deprecated, and equivalent to:
|
* This function is deprecated, and equivalent to:
|
||||||
* ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only);
|
* ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only);
|
||||||
* ZSTD_CCtx_refCDict(zcs, cdict);
|
* ZSTD_CCtx_refCDict(zcs, cdict);
|
||||||
|
@ -2075,7 +2076,7 @@ ZSTD_initCStream_advanced(ZSTD_CStream* zcs,
|
||||||
*/
|
*/
|
||||||
ZSTDLIB_API size_t ZSTD_initCStream_usingCDict(ZSTD_CStream* zcs, const ZSTD_CDict* cdict);
|
ZSTDLIB_API size_t ZSTD_initCStream_usingCDict(ZSTD_CStream* zcs, const ZSTD_CDict* cdict);
|
||||||
|
|
||||||
/**! ZSTD_initCStream_usingCDict_advanced() :
|
/*! ZSTD_initCStream_usingCDict_advanced() :
|
||||||
* This function is DEPRECATED, and is approximately equivalent to:
|
* This function is DEPRECATED, and is approximately equivalent to:
|
||||||
* ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only);
|
* ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only);
|
||||||
* // Pseudocode: Set each zstd frame parameter and leave the rest as-is.
|
* // Pseudocode: Set each zstd frame parameter and leave the rest as-is.
|
||||||
|
@ -2148,7 +2149,8 @@ ZSTDLIB_API size_t ZSTD_toFlushNow(ZSTD_CCtx* cctx);
|
||||||
|
|
||||||
|
|
||||||
/*===== Advanced Streaming decompression functions =====*/
|
/*===== Advanced Streaming decompression functions =====*/
|
||||||
/**
|
|
||||||
|
/*!
|
||||||
* This function is deprecated, and is equivalent to:
|
* This function is deprecated, and is equivalent to:
|
||||||
*
|
*
|
||||||
* ZSTD_DCtx_reset(zds, ZSTD_reset_session_only);
|
* ZSTD_DCtx_reset(zds, ZSTD_reset_session_only);
|
||||||
|
@ -2159,7 +2161,7 @@ ZSTDLIB_API size_t ZSTD_toFlushNow(ZSTD_CCtx* cctx);
|
||||||
*/
|
*/
|
||||||
ZSTDLIB_API size_t ZSTD_initDStream_usingDict(ZSTD_DStream* zds, const void* dict, size_t dictSize);
|
ZSTDLIB_API size_t ZSTD_initDStream_usingDict(ZSTD_DStream* zds, const void* dict, size_t dictSize);
|
||||||
|
|
||||||
/**
|
/*!
|
||||||
* This function is deprecated, and is equivalent to:
|
* This function is deprecated, and is equivalent to:
|
||||||
*
|
*
|
||||||
* ZSTD_DCtx_reset(zds, ZSTD_reset_session_only);
|
* ZSTD_DCtx_reset(zds, ZSTD_reset_session_only);
|
||||||
|
@ -2170,7 +2172,7 @@ ZSTDLIB_API size_t ZSTD_initDStream_usingDict(ZSTD_DStream* zds, const void* dic
|
||||||
*/
|
*/
|
||||||
ZSTDLIB_API size_t ZSTD_initDStream_usingDDict(ZSTD_DStream* zds, const ZSTD_DDict* ddict);
|
ZSTDLIB_API size_t ZSTD_initDStream_usingDDict(ZSTD_DStream* zds, const ZSTD_DDict* ddict);
|
||||||
|
|
||||||
/**
|
/*!
|
||||||
* This function is deprecated, and is equivalent to:
|
* This function is deprecated, and is equivalent to:
|
||||||
*
|
*
|
||||||
* ZSTD_DCtx_reset(zds, ZSTD_reset_session_only);
|
* ZSTD_DCtx_reset(zds, ZSTD_reset_session_only);
|
||||||
|
@ -2232,7 +2234,7 @@ ZSTDLIB_API size_t ZSTD_compressContinue(ZSTD_CCtx* cctx, void* dst, size_t dstC
|
||||||
ZSTDLIB_API size_t ZSTD_compressEnd(ZSTD_CCtx* cctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize);
|
ZSTDLIB_API size_t ZSTD_compressEnd(ZSTD_CCtx* cctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize);
|
||||||
|
|
||||||
|
|
||||||
/*-
|
/**
|
||||||
Buffer-less streaming decompression (synchronous mode)
|
Buffer-less streaming decompression (synchronous mode)
|
||||||
|
|
||||||
A ZSTD_DCtx object is required to track streaming operations.
|
A ZSTD_DCtx object is required to track streaming operations.
|
||||||
|
|
|
@ -149,12 +149,12 @@ fullbench-dll: $(PRGDIR)/datagen.c $(PRGDIR)/util.c $(PRGDIR)/benchfn.c $(PRGDIR
|
||||||
# $(CC) $(FLAGS) $(filter %.c,$^) -o $@$(EXT) -DZSTD_DLL_IMPORT=1 $(ZSTDDIR)/dll/libzstd.dll
|
# $(CC) $(FLAGS) $(filter %.c,$^) -o $@$(EXT) -DZSTD_DLL_IMPORT=1 $(ZSTDDIR)/dll/libzstd.dll
|
||||||
$(CC) $(FLAGS) $(filter %.c,$^) -o $@$(EXT)
|
$(CC) $(FLAGS) $(filter %.c,$^) -o $@$(EXT)
|
||||||
|
|
||||||
fuzzer : LDFLAGS += $(MULTITHREAD_LD)
|
fuzzer : LDFLAGS += $(MULTITHREAD_LD)
|
||||||
fuzzer : $(ZSTDMT_OBJECTS)
|
fuzzer : $(ZSTDMT_OBJECTS)
|
||||||
fuzzer fuzzer32 : $(ZDICT_FILES) $(PRGDIR)/util.c $(PRGDIR)/timefn.c $(PRGDIR)/datagen.c fuzzer.c
|
fuzzer fuzzer32 : $(ZDICT_FILES) $(PRGDIR)/util.c $(PRGDIR)/timefn.c $(PRGDIR)/datagen.c fuzzer.c
|
||||||
|
|
||||||
fuzzer32: CFLAGS += -m32
|
fuzzer32 : CFLAGS += -m32
|
||||||
fuzzer32: $(ZSTD_FILES)
|
fuzzer32 : $(ZSTD_FILES)
|
||||||
$(LINK.c) $^ -o $@$(EXT)
|
$(LINK.c) $^ -o $@$(EXT)
|
||||||
|
|
||||||
# note : broken : requires symbols unavailable from dynamic library
|
# note : broken : requires symbols unavailable from dynamic library
|
||||||
|
|
Loading…
Reference in New Issue