4. ZSTD#

group ZSTD_API

zstd, short for Zstandard, is a fast lossless compression algorithm, targeting real-time compression scenarios at zlib-level and better compression ratios. The zstd compression library provides in-memory compression and decompression functions.

The library supports regular compression levels from 1 up to ZSTD_maxCLevel(), which is currently 22. Levels >= 20, labeled --ultra, should be used with caution, as they require more memory. The library also offers negative compression levels, which extend the range of speed vs. ratio preferences. The lower the level, the faster the speed (at the cost of compression).

Compression can be done in:

a single step (described as Simple API)
a single step, reusing a context (described as Explicit context)
unbounded multiple steps (described as Streaming compression)

The compression ratio achievable on small data can be highly improved using a dictionary. Dictionary compression can be performed in:

a single step (described as Simple dictionary API)
a single step, reusing a dictionary (described as Bulk-processing dictionary API)

Advanced experimental functions can be accessed using #define ZSTD_STATIC_LINKING_ONLY before including zstd.h.

Advanced experimental APIs should never be used with a dynamically-linked library. They are not “stable”; their definitions or signatures may change in the future. Only static linking is allowed.

Advanced compression API (Requires v1.4.0+)

API design : Parameters are pushed one by one into an existing context, using ZSTD_CCtx_set*()

functions.

Pushed parameters are sticky : they are valid for next compressed frame, and any subsequent frame. “sticky” parameters are applicable to

ZSTD_compress2() and ZSTD_compressStream*(). They do not apply to “simple” one-shot variants such as ZSTD_compressCCtx()

It’s possible to reset all parameters to “default” using

ZSTD_CCtx_reset().

This API supercedes all other “advanced” API entry points in the experimental section. In the future, we expect to remove from experimental API entry points which are redundant with this API.

enum ZSTD_ResetDirective#

Values:

enumerator ZSTD_reset_session_only#

enumerator ZSTD_reset_parameters#

enumerator ZSTD_reset_session_and_parameters#

ZSTD_bounds ZSTD_cParam_getBounds(ZSTD_cParameter cParam)#

Note

All parameters must belong to an interval with lower and upper bounds, otherwise they will either trigger an error or be automatically clamped.

Parameters	Direction	Description
cParam	in	Compression Parameter of type `ZSTD_cParameter`.

Warning

All parameters must belong to an interval with lower and upper bounds, otherwise they will either trigger an error or be automatically clamped.

Returns:

Result	Description
Success	A structure, ZSTD_bounds, which contains
	- an error status field, which must be tested using ZSTD_isError()
	- lower and upper bounds, both inclusive

size_t ZSTD_CCtx_setParameter(ZSTD_CCtx *cctx, ZSTD_cParameter param, int value)#

Set one compression parameter, selected by enum ZSTD_cParameter.

Parameters	Direction	Description
cctx	in,out	ZSTD compression context. When compressing many times, it is recommended to allocate the context just once, and re-use it for each successive compression operation.
param	in	Compression parameter of type ZSTD_cParameter.
value	in	Compression level.

Note

All parameters have valid bounds. Bounds can be queried using ZSTD_cParam_getBounds(). Providing a value beyond bound will either clamp it, or trigger an error (depending on parameter). Setting a parameter is generally only possible during frame initialization (before starting compression).

Note

When using multi-threading mode (nbWorkers >= 1), the following parameters can be updated during compression (within same frame): => compressionLevel, hashLog, chainLog, searchLog, minMatch, targetLength and strategy. new parameters will be active for next job only (after a flush()).

Returns:

Result	Description
Success	0
Fail	An error code (which can be tested using ZSTD_isError()).

size_t ZSTD_CCtx_setPledgedSrcSize(ZSTD_CCtx *cctx, unsigned long long pledgedSrcSize)#

Total input data size to be compressed as a single frame.

Parameters	Direction	Description
cctx	in,out	ZSTD compression context. When compressing many times, it is recommended to allocate the context just once, and re-use it for each successive compression operation.
pledgedSrcSize	in	Pledged source size; content size. pledgedSrcSize must be correct. If it is not known at init time, use ZSTD_CONTENTSIZE_UNKNOWN.

Note

Value will be written in frame header, unless if explicitly forbidden using ZSTD_c_contentSizeFlag. This value will also be controlled at end of frame, and trigger an error if not respected.

Note

1 : pledgedSrcSize==0 actually means zero, aka an empty frame. In order to mean “unknown content size”, pass constant ZSTD_CONTENTSIZE_UNKNOWN. ZSTD_CONTENTSIZE_UNKNOWN is default value for any new frame.

Note

2 : pledgedSrcSize is only valid once, for the next frame. It’s discarded at the end of the frame, and replaced by ZSTD_CONTENTSIZE_UNKNOWN.

Note

3 : Whenever all input data is provided and consumed in a single round, for example with ZSTD_compress2(), or invoking immediately ZSTD_compressStream2(,,,ZSTD_e_end), this value is automatically overridden by srcSize instead.

Returns:

Result	Description
Success	0
Fail	An error code (which can be tested using ZSTD_isError()).

size_t ZSTD_CCtx_reset(ZSTD_CCtx *cctx, ZSTD_ResetDirective reset)#

Resets compression context; resets all parameters to default values.

Parameters	Direction	Description
cctx	in,out	ZSTD compression context. When compressing many times, it is recommended to allocate the context just once, and re-use it for each successive compression operation.
reset	in	A ZSTD_ResetDirective type, indicating to reset session only, parameters only or both session and parameters.

Note

There are 2 different things that can be reset, independently or jointly :

The session : will stop compressing current frame, and make CCtx ready to start a new one. Useful after an error, or to interrupt any ongoing compression. Any internal data not yet flushed is cancelled. Compression parameters and dictionary remain unchanged. They will be used to compress next frame. Resetting session never fails.
The parameters : changes all parameters back to “default”. This removes any reference to any dictionary too. Parameters can only be changed between 2 sessions (i.e. no compression is currently ongoing) otherwise the reset fails, and function returns an error value (which can be tested using ZSTD_isError())
Both : similar to resetting the session, followed by resetting parameters.

Returns:

Result	Description
Success	0
Fail	An error code (which can be tested using ZSTD_isError()).

size_t ZSTD_compress2(ZSTD_CCtx *cctx, void *dst, size_t dstCapacity, const void *src, size_t srcSize)#

Behave the same as ZSTD_compressCCtx(), but compression parameters are set using the advanced API.

Parameters	Direction	Description
cctx	in,out	Explicit ZSTD compression context. When compressing many times, it is recommended to allocate the context just once, and re-use it for each successive compression operation.
dst	out	Destination buffer, compressed data is kept here, memory should be allocated already.
dstCapacity	in	Size of buffer `dst` (which must be already allocated).
src	in	Source buffer, the data which you want to compress is copied/or pointed here.
srcSize	in	Size of buffer `src`.

Note

ZSTD_compress2() always starts a new frame.

Note

Should cctx hold data from a previously unfinished frame, everything about it is forgotten.

Compression parameters are pushed into CCtx before starting compression, using ZSTD_CCtx_set*()
The function is always blocking, returns when compression is completed.

Note

Compression runs faster if dstCapacity >= ZSTD_compressBound(srcSize).

Returns:

Result	Description
Success	Compressed size written into `dst` (<= `dstCapacity`),
Fail	An error code if it fails (which can be tested using ZSTD_isError()).

Bulk processing dictionary API

typedef struct ZSTD_DDict_s ZSTD_DDict#

ZSTD_CDict *ZSTD_createCDict(const void *dictBuffer, size_t dictSize, int compressionLevel)#

Creates a state from digesting a dictionary.

Parameters	Direction	Description
dictBuffer	in	Dictionary buffer.
dictSize	in	Size of the dictionary buffer.
compressionLevel	in	A measure of the compression quality expressed as an integer.

Note

When compressing multiple messages or blocks using the same dictionary, it’s recommended to digest the dictionary only once, since it’s a costly operation.

Note

ZSTD_CDict can be created once and shared by multiple threads concurrently, since its usage is read-only.

Note

dictBuffer can be released after ZSTD_CDict creation, because its content is copied within CDict.

Note

1 : Consider experimental function ZSTD_createCDict_byReference() if you prefer to not duplicate dictBuffer content.

Note

2 : A ZSTD_CDict can be created from an empty dictBuffer, in which case the only thing that it transports is the compressionLevel. This can be useful in a pipeline featuring ZSTD_compress_usingCDict() exclusively, expecting a ZSTD_CDict parameter with any data, including those without a known dictionary.

Returns:: A state that can be used for future compression operations with very limited startup cost.

size_t ZSTD_freeCDict(ZSTD_CDict *CDict)#

Function frees memory allocated by ZSTD_createCDict().

Parameters	Direction	Description
CDict	in	A state that can be used for future compression operations with very limited startup cost.

Note

If a NULL pointer is passed, no operation is performed.

Returns:: 0 on successful deallocation.

size_t ZSTD_compress_usingCDict(ZSTD_CCtx *cctx, void *dst, size_t dstCapacity, const void *src, size_t srcSize, const ZSTD_CDict *cdict)#

Compression using a digested Dictionary. Recommended when same dictionary is used multiple times.

Parameters	Direction	Description
cctx	in,out	ZSTD compression context.When compressing many times, the context is allocated just once, and re-used for each successive compression operation.
dst	out	Destination buffer, compressed data is kept here, memory should be allocated already.
dstCapacity	in	Size of buffer `dst` (which must be already allocated).
src	in	Source buffer, the data which you want to compress is copied/or pointed here.
srcSize	in	Size of the source (`src`) buffer.
cdict	in	A state that can be used for future compression operations with very limited startup cost.

Note

Compression level is decided at dictionary creation time, and frame parameters are hardcoded (dictID=yes, contentSize=yes, checksum=no)

Returns:

Result	Description
Success	The number of bytes written into `dst` (necessarily <= dstCapacity).
Fail	Error code.

ZSTD_DDict *ZSTD_createDDict(const void *dictBuffer, size_t dictSize)#

Create a digested dictionary, ready to start decompression operation without startup delay. dictBuffer can be released after DDict creation, as its content is copied inside DDict.

Parameters	Direction	Description
dictBuffer	in	Dictionary buffer.
dictSize	in	Size of the dictionary buffer.

Returns:: A dictionary that is used to decompress next frames.

size_t ZSTD_freeDDict(ZSTD_DDict *ddict)#: ZSTD_freeDDict() : Function frees memory allocated with ZSTD_createDDict() If a NULL pointer is passed, no operation is performed.

size_t ZSTD_decompress_usingDDict(ZSTD_DCtx *dctx, void *dst, size_t dstCapacity, const void *src, size_t srcSize, const ZSTD_DDict *ddict)#

Decompression using a digested Dictionary. Recommended when same dictionary is used multiple times.

Parameters	Direction	Description
dctx	in,out	ZSTD decompression context. When decompressing many times, the context is allocated just once, and re-used for each successive compression operation.
dst	out	Destination buffer, compressed data is kept here, memory should be allocated already.
dstCapacity	in	Size of buffer `dst` (which must be already allocated).
src	in	Source buffer, the data which you want to compress is copied/or pointed here.
srcSize	in	Size of the source (`src`) buffer.
ddict	in	A dictionary that is used to decompress next frames.

Returns:

Result	Description
Success	The number of bytes written into `dst` (necessarily <= dstCapacity).
Fail	Error code.

Helper functions

unsigned ZSTD_versionNumber(void)#

Library Version number. Useful to check dll version.

Returns:: Runtime library version, the value is (MAJOR*100*100 + MINOR*100 + RELEASE).

const char *ZSTD_versionString(void)#

Library Version number. Useful to check dll version.

Warning

Requires v1.3.0+.

Returns:: Runtime library version, like “1.4.5”.

size_t ZSTD_compressBound(size_t srcSize)#: Maximum compressed size in worst case single-pass scenario.

unsigned ZSTD_isError(size_t code)#: Tells if a size_t function result is an error code.

const char *ZSTD_getErrorName(size_t code)#: Provides readable string from an error code.

int ZSTD_minCLevel(void)#: Minimum negative compression level allowed, requires v1.4.0+.

int ZSTD_maxCLevel(void)#: Maximum compression level available.

int ZSTD_defaultCLevel(void)#: Default compression level, specified by ZSTD_CLEVEL_DEFAULT, requires v1.5.0+.

Simple API

size_t ZSTD_compress(void *dst, size_t dstCapacity, const void *src, size_t srcSize, int compressionLevel)#

Compresses src content as a single zstd compressed frame into already allocated dst.

Parameters	Direction	Description
dst	out	Destination buffer, compressed data is kept here, memory should be allocated already.
dstCapacity	in	Size of buffer `dst` (which must be already allocated).
src	in	Source buffer, the data which you want to compress is copied/or pointed here.
srcSize	in	Size of buffer `src`.
compressionLevel	in	A measure of the compression quality expressed as an integer.

Note

Providing dstCapacity >= ZSTD_compressBound(srcSize) guarantees that zstd will have enough space to successfully compress the data.

Returns:

Result	Description
Success	Compressed size written into `dst` (necessarily <= dstCapacity).
Fail	Error code (which can be tested using ZSTD_isError()).

size_t ZSTD_decompress(void *dst, size_t dstCapacity, const void *src, size_t compressedSize)#

Decompresses the compressed data that is pointed by src into dst.

Parameters	Direction	Description
dst	out	This is the destination buffer, the data is decompressed to this buffer.
dstCapacity	in	An upper bound of original size to regenerate.
src	in	This buffer contains compressed data.
compressedSize	in	Must be the exact size of some number of compressed and/or skippable frames.

Note

If user cannot imply a maximum upper bound, it’s better to use streaming mode to decompress data.

Note

In case of an error, the error code can be tested using ZSTD_isError().

Returns:

Result	Description
Success	The number of bytes written into `dst` (necessarily <= dstCapacity).
Fail	Error code (which can be tested using ZSTD_isError()).

unsigned long long ZSTD_getFrameContentSize(const void *src, size_t srcSize)#

Parameters	Direction	Description
src	in	Points to the start of a ZSTD encoded frame.
srcSize	in	Must be at least as large as the frame header. Any size `>= ZSTD_frameHeaderSize_max` is large enough.

Warning

ZSTD_getFrameContentSize() : requires v1.3.0+

Note

1 : A 0 return value means the frame is valid but “empty”.

Note

2 : Decompressed size is an optional field, it may not be present, typically in streaming mode. When return==ZSTD_CONTENTSIZE_UNKNOWN, data to decompress could be any size. In which case, it’s necessary to use streaming mode to decompress data. Optionally, application can rely on some implicit limit, as ZSTD_decompress() only needs an upper bound of decompressed size. (For example, data could be necessarily cut into blocks <= 16 KB).

Note

3 : Decompressed size is always present when compression is completed using single-pass functions, such as ZSTD_compress(), ZSTD_compressCCtx() ZSTD_compress_usingDict() or ZSTD_compress_usingCDict().

Note

4 : Decompressed size can be very large (64-bits value), potentially larger than what local system can handle as a single memory segment. In which case, it’s necessary to use streaming mode to decompress data.

Note

5 : If source is untrusted, decompressed size could be wrong or intentionally modified. Always ensure return value fits within application’s authorized limits. Each application can set its own limits.

Note

6 : This function replaces ZSTD_getDecompressedSize()

Returns:

Result	Description
Success	Decompressed size of `src` frame content, if known.
Success	`ZSTD_CONTENTSIZE_UNKNOWN` if the size cannot be determined.
Fail	`ZSTD_CONTENTSIZE_ERROR` if an error occurred (e.g. invalid magic number, srcSize too small).

unsigned long long ZSTD_getDecompressedSize(const void *src, size_t srcSize)#

Parameters	Direction	Description
src	in	Points to the start of a ZSTD encoded frame.
srcSize	in	It is at least as large as the frame header.

Note

This function is now obsolete, in favor of ZSTD_getFrameContentSize(). Both functions work the same way, but ZSTD_getDecompressedSize() blends “empty”, “unknown” and “error” results to the same return value (0), while ZSTD_getFrameContentSize() gives separate return values.

Returns:

Result	Description
Success	Decompressed size of `src` frame content if known and not empty.
Success	`0` if the frame is valid but empty or unknown.
Fail	`0` if an error occured.

size_t ZSTD_findFrameCompressedSize(const void *src, size_t srcSize)#

Parameters	Direction	Description
src	in	Points to the start of a ZSTD frame or skippable frame.
srcSize	in	It must be >= first frame size.

Warning

ZSTD_findFrameCompressedSize() : Requires v1.4.0+

Returns:

Result	Description
Success	Compressed size of the first frame starting at `src`, suitable to pass as `srcSize` to `ZSTD_decompress` or similar
Fail	An error code if input is invalid.

Explicit context

ZSTD_CCtx *ZSTD_createCCtx(void)#: Creates compression context.

size_t ZSTD_freeCCtx(ZSTD_CCtx *cctx)#: Releases compression context. Accept NULL pointer.

size_t ZSTD_compressCCtx(ZSTD_CCtx *cctx, void *dst, size_t dstCapacity, const void *src, size_t srcSize, int compressionLevel)#

Same as ZSTD_compress(), using an explicit ZSTD_CCtx.

Parameters	Direction	Description
cctx	in,out	Explicit ZSTD compression context.
dst	out	Destination buffer, compressed data is kept here, memory should be allocated already.
dstCapacity	in	Size of buffer `dst` (which must be already allocated).
src	in	Source buffer, the data which you want to compress is copied/or pointed here.
srcSize	in	Size of buffer `src`.
compressionLevel	in	A measure of the compression quality expressed as an integer.

Note

1 : In order to behave similarly to ZSTD_compress(), this function compresses at requested compression level, ignoring any other parameter.

Note

2 : If any advanced parameter was set using the advanced API, they will all be reset. Only compressionLevel remains.

Returns:

Result	Description
Success	The number of bytes written into `dst` (necessarily <= dstCapacity).
Fail	Error code.

ZSTD_DCtx *ZSTD_createDCtx(void)#: Creates decompression context.

size_t ZSTD_freeDCtx(ZSTD_DCtx *dctx)#: Releases decompression context. Accept NULL pointer.

size_t ZSTD_decompressDCtx(ZSTD_DCtx *dctx, void *dst, size_t dstCapacity, const void *src, size_t srcSize)#

Same as ZSTD_decompress(), requires an allocated ZSTD_DCtx. Compatible with sticky parameters.

Parameters	Direction	Description
dctx	in,out	Explicit allocated ZSTD decompression context.
dst	out	This is the destination buffer, the data is decompressed to this buffer.
dstCapacity	in	An upper bound of original size to regenerate.
src	in	This buffer contains compressed data.
srcSize	in	It is the exact size of some number of compressed and/or skippable frames.

Returns:

Result	Description
Success	The number of bytes written into `dst` (necessarily <= dstCapacity).
Fail	Error code.

Advanced decompression API (Requires v1.4.0+)

The advanced API pushes parameters one by one into an existing DCtx context. Parameters are sticky, and remain valid for all following frames using the same DCtx context. It’s possible to reset parameters to default values using ZSTD_DCtx_reset(). Note: This API is compatible with existing ZSTD_decompressDCtx() and ZSTD_decompressStream(). Therefore, no new decompression function is necessary.

ZSTD_bounds ZSTD_dParam_getBounds(ZSTD_dParameter dParam)#

Parameters	Direction	Description
dParam	in	Decompression parameter of type ZSTD_dParameter.

Warning

All parameters must belong to an interval with lower and upper bounds, otherwise they will either trigger an error or be automatically clamped.

Returns:

Result	Description
Success	A structure, ZSTD_bounds, which contains
	- an error status field, which must be tested using ZSTD_isError()
	- both lower and upper bounds, inclusive

size_t ZSTD_DCtx_setParameter(ZSTD_DCtx *dctx, ZSTD_dParameter param, int value)#

Set one compression parameter, selected by enum ZSTD_dParameter.

Parameters	Direction	Description
dctx	in,out	ZSTD decompression context. When decompressing many times, it is recommended to allocate the context only once, and re-use it for each successive compression operation.
param	in	Decompression parameter of type ZSTD_dParameter.
value	in	Compression level.

Note

All parameters have valid bounds. Bounds can be queried using ZSTD_dParam_getBounds(). Providing a value beyond bound will either clamp it, or trigger an error (depending on parameter). Setting a parameter is only possible during frame initialization (before starting decompression).

Returns:

Result	Description
Success	0
Fail	An error code (which can be tested using ZSTD_isError()).

size_t ZSTD_DCtx_reset(ZSTD_DCtx *dctx, ZSTD_ResetDirective reset)#

Return a DCtx to clean state, resets parameters to default values.

Parameters	Direction	Description
dctx	in, out	ZSTD decompression context. When decompressing many times, it is recommended to allocate the context just once, and re-use it for each successive compression operation.
reset	in	A ZSTD_ResetDirective type, indicating to reset session only, parameters only or both session and parameters.

Note

Session and parameters can be reset jointly or separately.

Note

Parameters can only be reset when no active frame is being decompressed.

Returns:

Result	Description
Success	0
Fail	An error code (which can be tested using ZSTD_isError()).

ZSTD_CStream management functions

ZSTD_CStream *ZSTD_createCStream(void)#: Used to create resource.

size_t ZSTD_freeCStream(ZSTD_CStream *zcs)#: Used to release resource. Accept NULL pointer.

Streaming compression functions

ZSTD_compressStream2() : Requires v1.4.0+ Behaves about the same as ZSTD_compressStream, with additional control on end directive.

Compression parameters are pushed into CCtx before starting compression, using ZSTD_CCtx_set*()
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 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>=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. 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.
return:

provides a minimum amount of data remaining to be flushed from internal buffers or an error code, which can be tested using ZSTD_isError(). if

return:

!= 0, flush is not fully completed, there is still some data left within internal buffers. This is useful for ZSTD_e_flush, since in this case more flushes are necessary to empty all buffers. For ZSTD_e_end,

return:

== 0 when internal buffers are fully flushed and frame is completed.
after a ZSTD_e_end directive, if internal buffer is not fully flushed (

return:

!= 0), only ZSTD_e_end or ZSTD_e_flush operations are allowed. Before starting a new compression job, or changing compression parameters, it is required to fully flush internal buffers.

size_t ZSTD_compressStream2(ZSTD_CCtx *cctx, ZSTD_outBuffer *output, ZSTD_inBuffer *input, ZSTD_EndDirective endOp)#

Behaves about the same as ZSTD_compressStream, with additional control on end directive.

Parameters	Direction	Description
cctx	in, out	ZSTD compression context. When compressing many times, it is recommended to allocate the context just once, and re-use it for each successive compression operation.
output	out	Output buffer of type `ZSTD_outBuffer` where the members
		`dst` indicates the start of the output buffer,
		`size` indicates the size of the output buffer and
		`pos` indicates position where reading is stopped. Will be updated. Necessarily `0 <= pos <= size`.
input	in	Input buffer of type `ZSTD_inBuffer` where the members
		`src` indicates the start of the input buffer,
		`size` indicates the size of the input buffer and
		`pos` indicates position where reading is stopped. Will be updated. Necessarily `0 <= pos <= size`.
endOp	in	A type ‘ZSTD_EndDirective’ indicating to collect more data [if endOp is `ZSTD_e_continue`] or flush any data provided so far [if endOp is `ZSTD_e_flush`] or flush any remaining data and close current frame [if endOp is `ZSTD_e_end`].

Note

If the value returned != 0, flush is not fully completed, there is still some data left within internal buffers. This is useful for ZSTD_e_flush, since in this case more flushes are necessary to empty all buffers.
For ZSTD_e_end, value returned == 0 when internal buffers are fully flushed and frame is completed.
After a ZSTD_e_end directive, if internal buffer is not fully flushed (return_value != 0), only ZSTD_e_end or ZSTD_e_flush operations are allowed. Before starting a new compression job, or changing compression parameters, it is required to fully flush internal buffers.

Note

1 : Compression parameters are pushed into CCtx before starting compression, using ZSTD_CCtx_set*()

Note

2 : Compression parameters cannot be changed once compression is started (save a list of exceptions in multi-threading mode)

Note

3 : output->pos must be <= dstCapacity, input->pos must be <= srcSize

Note

4 : output->pos and input->pos will be updated. They are guaranteed to remain below their respective limit.

Note

5 : endOp must be a valid directive

Note

When nbWorkers==0 (default), function is blocking : It completes its job before returning to caller.
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. 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.

Warning

ZSTD_compressStream2() : Requires v1.4.0+

Returns:

Result	Description
Success	Provides a minimum amount of data remaining to be flushed from internal buffers
Fail	An error code (which can be tested using ZSTD_isError()).

size_t ZSTD_CStreamInSize(void)#: Recommended size for input buffer.

Note

These buffer sizes are softly recommended. They are not required : ZSTD_compressStream*()
happily accepts any buffer size, for both input and output.

Respecting the recommended size just makes it a bit easier for
ZSTD_compressStream*()
, reducing the amount of memory shuffling and buffering, resulting in minor performance savings.

However, note that these recommendations are from the perspective of a C caller program. If the streaming interface is invoked from some other language, especially managed ones such as Java or Go, through a foreign function interface such as jni or cgo, a major performance rule is to reduce crossing such interface to an absolute minimum.
It’s not rare that performance ends being spent more into the interface, rather than compression itself. In which cases, prefer using large buffers, as large as practical, for both input and output, to reduce the nb of roundtrips.

size_t ZSTD_CStreamOutSize(void)#

Recommended size for output buffer.

Guarantee to successfully flush at least one complete compressed block.

Note

These buffer sizes are softly recommended. They are not required : ZSTD_compressStream*()

happily accepts any buffer size, for both input and output.

Respecting the recommended size just makes it a bit easier for

ZSTD_compressStream*()

, reducing the amount of memory shuffling and buffering, resulting in minor performance savings.

However, note that these recommendations are from the perspective of a C caller program. If the streaming interface is invoked from some other language, especially managed ones such as Java or Go, through a foreign function interface such as jni or cgo, a major performance rule is to reduce crossing such interface to an absolute minimum.

It’s not rare that performance ends being spent more into the interface, rather than compression itself. In which cases, prefer using large buffers, as large as practical, for both input and output, to reduce the nb of roundtrips.

Legacy streaming API

This following is a legacy streaming API, available since v1.0+ .

It can be replaced by

ZSTD_CCtx_reset() and ZSTD_compressStream2()

. It is redundant, but remains fully supported.

Streaming in combination with advanced parameters and dictionary compression can only be used through the new API.

size_t ZSTD_initCStream(ZSTD_CStream *zcs, int compressionLevel)#

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);

size_t ZSTD_compressStream(ZSTD_CStream *zcs, ZSTD_outBuffer *output, ZSTD_inBuffer *input)#: Alternative for ZSTD_compressStream2(zcs, output, input, ZSTD_e_continue).

Note

The return value is different.

Note

ZSTD_compressStream() returns a hint for the next read size (if non-zero and not an error).

Note

ZSTD_compressStream2() returns the minimum nb of bytes left to flush (if non-zero and not an error).

size_t ZSTD_flushStream(ZSTD_CStream *zcs, ZSTD_outBuffer *output)#: Equivalent to ZSTD_compressStream2(zcs, output, &emptyInput, ZSTD_e_flush).

size_t ZSTD_endStream(ZSTD_CStream *zcs, ZSTD_outBuffer *output)#: Equivalent to ZSTD_compressStream2(zcs, output, &emptyInput, ZSTD_e_end).

ZSTD_DStream management functions

ZSTD_DStream *ZSTD_createDStream(void)#: This is used to create ZSTD_DStream to track streaming operations which can be re-used multiple times.

size_t ZSTD_freeDStream(ZSTD_DStream *zds)#: Used to release resources. Accept NULL pointer.

Streaming decompression functions

size_t ZSTD_initDStream(ZSTD_DStream *zds)#

Used to start a new decompression operation.

Parameters	Direction	Description
zds	in, out	Is required to track streaming operations and can be re-used multiple times.

Note

This function is redundant with the advanced API and equivalent to:

- ZSTD_DCtx_reset(zds, ZSTD_reset_session_only);
- ZSTD_DCtx_refDDict(zds, NULL);

Returns:: Recommended first input size.

size_t ZSTD_decompressStream(ZSTD_DStream *zds, ZSTD_outBuffer *output, ZSTD_inBuffer *input)#

Used repetitively to consume the input.

Parameters	Direction	Description
zds	in, out	Is required to track streaming operations and can be re-used multiple times.
output	out	Output buffer of type `ZSTD_outBuffer` where the members
		`dst` indicates the start of the output buffer,
		`size` indicates the size of the output buffer and
		`pos` indicates position where reading is stopped. Will be updated. Necessarily `0 <= pos <= size`.
input	in	Input buffer of type `ZSTD_inBuffer` where the members
		`src` indicates the start of the input buffer,
		`size` indicates the size of the input buffer and
		`pos` indicates position where reading is stopped. Will be updated. Necessarily `0 <= pos <= size`.

Note

The function will update both pos fields.

If input.pos < input.size, some input has not been consumed. It’s up to the caller to present again remaining data. The function tries to flush all data decoded immediately, respecting output buffer size.
If output.pos < output.size, decoder has flushed everything it could.
But if output.pos == output.size, there might be some data left within internal buffers., in which case, call ZSTD_decompressStream() again to flush whatever remains in the buffer.

Note

With no additional input provided, amount of data flushed is necessarily <= ZSTD_BLOCKSIZE_MAX.

Returns:

Result	Description
Success	0 when a frame is completely decoded and fully flushed, or
	any other value > 0, which means there is still some decoding or flushing to do to complete current frame : the return value is a suggested next input size (just a hint for better latency) that will never request more than the remaining frame size.
Fail	An error code (which can be tested using ZSTD_isError()).

size_t ZSTD_DStreamInSize(void)#: Recommended size for input buffer.

size_t ZSTD_DStreamOutSize(void)#

Recommended size for output buffer.

Guarantee to successfully flush at least one complete block in all circumstances.

Simple dictionary API

size_t ZSTD_compress_usingDict(ZSTD_CCtx *ctx, void *dst, size_t dstCapacity, const void *src, size_t srcSize, const void *dict, size_t dictSize, int compressionLevel)#

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 zdict.h).

Parameters	Direction	Description
ctx	in,out	ZSTD compression context.When compressing many times, the context is allocated just once, and re-used for each successive compression operation.
dst	out	Destination buffer, compressed data is kept here, memory should be allocated already.
dstCapacity	in	Size of buffer `dst` (which must be already allocated).
src	in	Source buffer, the data which you want to compress is copied/or pointed here.
srcSize	in	Size of the source (`src`) buffer.
dict	in	Dictionary buffer.
dictSize	in	Size of the dictionary buffer.
compressionLevel	in	A measure of the compression quality expressed as an integer.

Note

1 : 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.

Returns:

Result	Description
Success	The number of bytes written into `dst` (necessarily <= dstCapacity).
Fail	Error code.

size_t ZSTD_decompress_usingDict(ZSTD_DCtx *dctx, void *dst, size_t dstCapacity, const void *src, size_t srcSize, const void *dict, size_t dictSize)#

Decompression using a known Dictionary.

Parameters	Direction	Description
dctx	in,out	ZSTD decompression context. When decompressing many times, the context is allocated just once, and re-used for each successive compression operation.
dst	out	Destination buffer, compressed data is kept here, memory should be allocated already.
dstCapacity	in	Size of buffer `dst` (which must be already allocated).
src	in	Source buffer, the data which you want to compress is copied/or pointed here.
srcSize	in	Size of the source (`src`) buffer.
dict	in	Dictionary buffer.
dictSize	in	Size of the dictionary buffer.

Note

1 : Dictionary must be identical to the one used during compression.

Note

2 : This function loads the dictionary, resulting in significant startup delay. It’s intended for a dictionary used only once.

Note

3 : When dict == NULL || dictSize < 8 no dictionary is used.

Returns:

Result	Description
Success	The number of bytes written into `dst` (necessarily <= dstCapacity).
Fail	Error code.

Dictionary helper functions

unsigned ZSTD_getDictID_fromDict(const void *dict, size_t dictSize)#

Provides the dictID stored within dictionary.

Parameters	Direction	Description
dict	in	Dictionary buffer.
dictSize	in	Size of the dictionary.

Warning

Requires v1.4.0+

Returns:: if return == 0, the dictionary is not conformant with Zstandard specification. It can still be loaded, but as a content-only dictionary.

unsigned ZSTD_getDictID_fromCDict(const ZSTD_CDict *cdict)#

Provides the dictID of the dictionary loaded into cdict.

Parameters	Direction	Description
cdict	in	State that can be used for future compression operations with very limited startup cost. It can be created once and shared by multiple threads concurrently, since its usage is read-only.

Warning

Requires v1.5.0+

Returns:: 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.

unsigned ZSTD_getDictID_fromDDict(const ZSTD_DDict *ddict)#

Provides the dictID of the dictionary loaded into ddict.

Parameters	Direction	Description
ddict	in	A dictionary that is used to decompress next frames.

Warning

Requires v1.4.0+

Returns:: 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.

unsigned ZSTD_getDictID_fromFrame(const void *src, size_t srcSize)#

Provides the dictID required to decompress the frame stored within src.

Parameters	Direction	Description
src	in	Source buffer, the data which you want to compress is copied/or pointed here.
srcSize	in	Size of the `src` buffer.

Note

If 0 is returned, it could be because of one of the following reasons:

The frame does not require a dictionary to be decoded (most common case).
The frame was built with dictID intentionally removed. Whatever dictionary is necessary is a hidden information. Note : this use case also happens when using a non-conformant dictionary.
srcSize is too small, and as a result, the frame header could not be decoded (only possible if srcSize < ZSTD_FRAMEHEADERSIZE_MAX).
This is not a Zstandard frame.

Note

When identifying the exact failure cause, it’s possible to use ZSTD_getFrameHeader(), which will provide a more precise error code.

Warning

Requires v1.4.0+

Returns:

Result	Description
Success	dictID required to decompress the frame stored within `src`.
Fail	0, if the dictID could not be decoded.

Advanced dictionary and prefix API (Requires v1.4.0+)

This API allows dictionaries to be used with ZSTD_compress2(), ZSTD_compressStream2(), and ZSTD_decompressDCtx(). Dictionaries are sticky, they remain valid when same context is re-used, they only reset when the context is reset with ZSTD_reset_parameters or ZSTD_reset_session_and_parameters. In contrast, Prefixes are single-use.

size_t ZSTD_CCtx_loadDictionary(ZSTD_CCtx *cctx, const void *dict, size_t dictSize)#

Create an internal CDict from dict buffer. Decompression will have to use same dictionary.

Parameters	Direction	Description
cctx	in,out	ZSTD compression context.When compressing many times, the context is allocated just once, and re-used for each successive compression operation.
dict	in	Dictionary buffer.
dictSize	in	Size of the dictionary buffer.

Special: Loading a NULL (or 0-size) dictionary invalidates previous dictionary, meaning “return to no-dictionary mode”.

Note

1 : Dictionary is sticky, it will be used for all future compressed frames. To return to “no-dictionary” situation, load a NULL dictionary (or reset parameters).

Note

2 : Loading a dictionary involves building tables. It’s also a CPU consuming operation, with non-negligible impact on latency. Tables are dependent on compression parameters, and for this reason, compression parameters can no longer be changed after loading a dictionary.

Note

3 : dict content will be copied internally. Use experimental ZSTD_CCtx_loadDictionary_byReference() to reference content instead. In such a case, dictionary buffer must outlive its users.

Note

4 : Use ZSTD_CCtx_loadDictionary_advanced() to precisely select how dictionary content must be interpreted.

Warning

Requires v1.4.0+

Returns:

Result	Description
Success	0
Fail	An error code (which can be tested using ZSTD_isError()).

size_t ZSTD_CCtx_refCDict(ZSTD_CCtx *cctx, const ZSTD_CDict *cdict)#

Reference a prepared dictionary, to be used for all next compressed frames.

Parameters	Direction	Description
cctx	in,out	ZSTD compression context.When compressing many times, the context is allocated just once, and re-used for each successive compression operation.
cdict	in	State that can be used for future compression operations with very limited startup cost.

Note

Note that compression parameters are enforced from within CDict, and supersede any compression parameter previously set within CCtx.

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.

Note

Special : Referencing a NULL CDict means “return to no-dictionary mode”.

Note

1 : Currently, only one dictionary can be managed. Referencing a new dictionary effectively “discards” any previous one.

Note

2 : CDict is just referenced, its lifetime must outlive its usage within CCtx.

Warning

Requires v1.4.0+

Returns:

Result	Description
Success	0
Fail	An error code (which can be tested using ZSTD_isError()).

size_t ZSTD_CCtx_refPrefix(ZSTD_CCtx *cctx, const void *prefix, size_t prefixSize)#

Reference a prefix (single-usage dictionary) for next compressed frame.

Parameters	Direction	Description
cctx	in,out	ZSTD compression context.When compressing many times, the context is allocated just once, and re-used for each successive compression operation.
prefix	in	prefix, a single-usage dictionary.
prefixSize	in	size of the prefix (single-usage dictionary)

Special: Adding any prefix (including NULL) invalidates any previous prefix or dictionary

Note

A prefix is only used once . Tables are discarded at end of frame (ZSTD_e_end). Decompression will need same prefix to properly regenerate data. Compressing with a prefix is similar in outcome as performing a diff and compressing it, but performs much faster, especially during decompression (compression speed is tunable with compression level).

Note

1 : Prefix buffer is referenced. It must outlive compression. Its content must remain unmodified during compression.

Note

2 : If the intention is to diff some large src data blob with some prior version of itself, ensure that the window size is large enough to contain the entire source. See ZSTD_c_windowLog.

Note

3 : Referencing a prefix involves building tables, which are dependent on compression parameters. It’s a CPU consuming operation, with non-negligible impact on latency. If there is a need to use the same prefix multiple times, consider loadDictionary instead.

Note

4 : By default, the prefix is interpreted as raw content (ZSTD_dct_rawContent). Use experimental ZSTD_CCtx_refPrefix_advanced() to alter dictionary interpretation.

Warning

Requires v1.4.0+

Returns:

Result	Description
Success	0
Fail	An error code (which can be tested using ZSTD_isError()).

size_t ZSTD_DCtx_loadDictionary(ZSTD_DCtx *dctx, const void *dict, size_t dictSize)#

Create an internal DDict from dict buffer, to be used to decompress next frames. The dictionary remains valid for all future frames, until explicitly invalidated.

Parameters	Direction	Description
dctx	in,out	ZSTD decompression context. When decompressing many times, the context is allocated just once, and re-used for each successive compression operation.
dict	in	Dictionary buffer.
dictSize	in	Size of the dictionary buffer.

Special : Adding a NULL (or 0-size) dictionary invalidates any previous dictionary, meaning “return to no-dictionary mode”.

Note

1 : Loading a dictionary involves building tables, which has a non-negligible impact on CPU usage and latency. It’s recommended to “load once, use many times”, to amortize the cost

Note

2 :dict content will be copied internally, so dict can be released after loading. Use ZSTD_DCtx_loadDictionary_byReference() to reference dictionary content instead.

Note

3 : Use ZSTD_DCtx_loadDictionary_advanced() to take control of how dictionary content is loaded and interpreted.

Warning

Requires v1.4.0+

Returns:

Result	Description
Success	0
Fail	An error code (which can be tested using ZSTD_isError()).

size_t ZSTD_DCtx_refDDict(ZSTD_DCtx *dctx, const ZSTD_DDict *ddict)#

Reference a prepared dictionary, to be used to decompress next frames. The dictionary remains active for decompression of future frames using same DCtx.

Parameters	Direction	Description
dctx	in,out	ZSTD decompression context. When decompressing many times, the context is allocated just once, and re-used for each successive compression operation.
ddict	in	A dictionary that is used to decompress next frames.

Note

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().

Note

1 : Currently, only one dictionary can be managed. Referencing a new dictionary effectively “discards” any previous one. Special: referencing a NULL DDict means “return to no-dictionary mode”.

Note

2 : DDict is just referenced, its lifetime must outlive its usage from DCtx.

Warning

Requires v1.4.0+

Returns:

Result	Description
Success	0
Fail	An error code (which can be tested using ZSTD_isError()).

size_t ZSTD_DCtx_refPrefix(ZSTD_DCtx *dctx, const void *prefix, size_t prefixSize)#

Reference a prefix (single-usage dictionary) to decompress next frame. This is the reverse operation of ZSTD_CCtx_refPrefix(), and must use the same prefix as the one used during compression.

Parameters	Direction	Description
dctx	in,out	ZSTD decompression context. When decompressing many times, the context is allocated just once, and re-used for each successive compression operation.
prefix	in	prefix, a single-usage dictionary.
prefixSize	in	size of the prefix (single-usage dictionary).

Note

Prefix is only used once . Reference is discarded at end of frame. End of frame is reached when ZSTD_decompressStream() returns 0.

Note

1 : Adding any prefix (including NULL) invalidates any previously set prefix or dictionary

Note

2 : Prefix buffer is referenced. It must outlive decompression. Prefix buffer must remain unmodified up to the end of frame, reached when ZSTD_decompressStream() returns 0.

Note

3 : By default, the prefix is treated as raw content (ZSTD_dct_rawContent). Use ZSTD_CCtx_refPrefix_advanced() to alter dictMode (Experimental section)

Note

4 : Referencing a raw content prefix has almost no cpu nor memory cost. A full dictionary is more costly, as it requires building tables.

Warning

Requires v1.4.0+

Returns:

Result	Description
Success	0
Fail	An error code (which can be tested using ZSTD_isError()).

Memory management functions

These functions give the current memory usage of selected object. Note that object memory usage can evolve (increase or decrease) over time. Note Requires v1.4.0+

size_t ZSTD_sizeof_CCtx(const ZSTD_CCtx *cctx)#: Returs the size of ZSTD_CCtx

size_t ZSTD_sizeof_DCtx(const ZSTD_DCtx *dctx)#: Returs the size of ZSTD_DCtx

size_t ZSTD_sizeof_CStream(const ZSTD_CStream *zcs)#: Returs the size of ZSTD_CStream

size_t ZSTD_sizeof_DStream(const ZSTD_DStream *zds)#: Returs the size of ZSTD_DStream

size_t ZSTD_sizeof_CDict(const ZSTD_CDict *cdict)#: Returs the size of ZSTD_CDict

size_t ZSTD_sizeof_DDict(const ZSTD_DDict *ddict)#: Returs the size of ZSTD_DDict

Typedefs

typedef struct ZSTD_CCtx_s ZSTD_CCtx#: Compression context : When compressing many times, it is recommended to allocate a context just once, and re-use it for each successive compression operation. This will make workload friendlier for system’s memory.

Note

1 : Re-using context is just a speed / resource optimization. It doesn’t change the compression ratio, which remains identical.

Note

2 : In multi-threaded environments, use one different context per thread for parallel execution.

typedef struct ZSTD_CDict_s ZSTD_CDict#

typedef ZSTD_CCtx ZSTD_CStream#

A ZSTD_CStream object is required to track streaming operation.

ZSTD_CStream objects can be reused multiple times on consecutive compression operations. It is recommended to re-use ZSTD_CStream since it will play nicer with system’s memory, by re-using already allocated memory.

Note

For parallel execution, use one separate ZSTD_CStream per thread.

Note

CCtx and CStream are now effectively same object (>= v1.3.0)

Continue to distinguish them for compatibility with older versions <= v1.2.0

typedef struct ZSTD_DCtx_s ZSTD_DCtx#: Decompression context : When decompressing many times, it is recommended to allocate a context only once, and re-use it for each successive compression operation. This will make workload friendlier for system’s memory.

Note

Use one context per thread for parallel execution.

typedef ZSTD_DCtx ZSTD_DStream#

A ZSTD_DStream object is required to track streaming operations.

ZSTD_DStream objects can be re-used multiple times.

Note

DCtx and DStream are now effectively same object (>= v1.3.0)

For compatibility with versions <= v1.2.0, prefer differentiating them.

typedef struct ZSTD_inBuffer_s ZSTD_inBuffer#

typedef struct ZSTD_outBuffer_s ZSTD_outBuffer#

Enums

enum ZSTD_cParameter#

Compression Parameters.

1. Advanced compression parameters

It’s possible to pin down compression parameters to some specific values. In which case, these values are no longer dynamically selected by the compressor

2. LDM mode parameter3. Frame parameter 4. Multi-threading parameters

These parameters are only active if multi-threading is enabled (compiled with build macro

ZSTD_MULTITHREAD). 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.

Note

Additional experimental parameters are also available within the experimental section of the API. At the time of this writing, they include :

ZSTD_c_rsyncable
ZSTD_c_format
ZSTD_c_forceMaxWindow
ZSTD_c_forceAttachDict
ZSTD_c_literalCompressionMode
ZSTD_c_targetCBlockSize
ZSTD_c_srcSizeHint
ZSTD_c_enableDedicatedDictSearch
ZSTD_c_stableInBuffer
ZSTD_c_stableOutBuffer
ZSTD_c_blockDelimiters
ZSTD_c_validateSequences
ZSTD_c_splitBlocks
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.

Note

When compressing with a ZSTD_CDict these parameters are superseded by the parameters used to construct the ZSTD_CDict. See ZSTD_CCtx_refCDict() for more info (superseded-by-cdict).

Values:

enumerator ZSTD_c_compressionLevel#: Set compression parameters according to pre-defined cLevel table. Note that exact compression parameters are dynamically determined, depending on both compression level and srcSize (when known). Default level is ZSTD_CLEVEL_DEFAULT==3. Special: value 0 means default, which is controlled by ZSTD_CLEVEL_DEFAULT.

Note

1 : it’s possible to pass a negative compression level.

Note

2 : setting a level does not automatically set all other compression parameters to default. Setting this will however eventually dynamically impact the compression parameters which have not been manually set. The manually set ones will ‘stick’.

enumerator ZSTD_c_windowLog#: Maximum allowed back-reference distance, expressed as power of 2. This will set a memory budget for streaming decompression, with larger values requiring more memory and typically compressing more. Must be clamped between ZSTD_WINDOWLOG_MIN and ZSTD_WINDOWLOG_MAX. Special: value 0 means “use default windowLog”.

Note

Using a windowLog greater than ZSTD_WINDOWLOG_LIMIT_DEFAULT requires explicitly allowing such size at streaming decompression stage.

enumerator ZSTD_c_hashLog#: Size of the initial probe table, as a power of 2. Resulting memory usage is (1 << (hashLog+2)). Must be clamped between ZSTD_HASHLOG_MIN and ZSTD_HASHLOG_MAX. Larger tables improve compression ratio of strategies <= dFast, and improve speed of strategies > dFast. Special: value 0 means “use default hashLog”.

enumerator ZSTD_c_chainLog#: Size of the multi-probe search table, as a power of 2. Resulting memory usage is (1 << (chainLog+2)). Must be clamped between ZSTD_CHAINLOG_MIN and ZSTD_CHAINLOG_MAX. Larger tables result in better and slower compression. This parameter is useless for “fast” strategy. It’s still useful when using “dfast” strategy, in which case it defines a secondary probe table. Special: value 0 means “use default chainLog”.

enumerator ZSTD_c_searchLog#: Number of search attempts, as a power of 2. More attempts result in better and slower compression. This parameter is useless for “fast” and “dFast” strategies. Special: value 0 means “use default searchLog”.

enumerator ZSTD_c_minMatch#: Minimum size of searched matches. Special: value 0 means “use default minMatchLength”.

Note

1 : Zstandard can still find matches of smaller size, it just tweaks its search algorithm to look for this size and larger. Larger values increase compression and decompression speed, but decrease ratio. Must be clamped between ZSTD_MINMATCH_MIN and ZSTD_MINMATCH_MAX.

Note

2 : Currently, for all strategies < btopt, effective minimum is 4. , for all strategies > fast, effective maximum is 6.

enumerator ZSTD_c_targetLength#

Impact of this field depends on strategy.

For strategies btopt, btultra & btultra2: Length of Match considered “good enough” to stop search. Larger values make compression stronger, and slower.
For strategy fast: Distance between match sampling. Larger values make compression faster, and weaker. Special: value 0 means “use default targetLength”.

enumerator ZSTD_c_strategy#: See ZSTD_strategy enum definition. 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”.

enumerator ZSTD_c_enableLongDistanceMatching#: Enable long distance matching. This parameter is designed to improve compression ratio for large inputs, by finding large matches at long distance. It increases memory usage and window size.

Note

1: enabling this parameter increases default ZSTD_c_windowLog to 128 MB except when expressly set to a different value.

Note

2: will be enabled by default if ZSTD_c_windowLog >= 128 MB and compression strategy >= ZSTD_btopt (== compression level 16+)

enumerator ZSTD_c_ldmHashLog#: Size of the table for long distance matching, as a power of 2. Larger values increase memory usage and compression ratio, but decrease compression speed. Must be clamped between ZSTD_HASHLOG_MIN and ZSTD_HASHLOG_MAX default: windowlog - 7. Special: value 0 means “automatically determine hashlog”.

enumerator ZSTD_c_ldmMinMatch#: Minimum match size for long distance matcher. Larger/too small values usually decrease compression ratio. Must be clamped between ZSTD_LDM_MINMATCH_MIN and ZSTD_LDM_MINMATCH_MAX. Special: value 0 means “use default value” (default: 64).

enumerator ZSTD_c_ldmBucketSizeLog#: Log size of each bucket in the LDM hash table for collision resolution. Larger values improve collision resolution but decrease compression speed. The maximum value is ZSTD_LDM_BUCKETSIZELOG_MAX. Special: value 0 means “use default value” (default: 3).

enumerator ZSTD_c_ldmHashRateLog#: Frequency of inserting/looking up entries into the LDM hash table. Must be clamped between 0 and (ZSTD_WINDOWLOG_MAX - ZSTD_HASHLOG_MIN). Default is MAX(0, (windowLog - ldmHashLog)), optimizing hash table usage. Larger values improve compression speed. Deviating far from default value will likely result in a compression ratio decrease. Special: value 0 means “automatically determine hashRateLog”.

enumerator ZSTD_c_contentSizeFlag#: Content size will be written into frame header whenever known (default:1) Content size must be known at the beginning of compression. This is automatically the case when using ZSTD_compress2(), For streaming scenarios, content size must be provided with ZSTD_CCtx_setPledgedSrcSize()

enumerator ZSTD_c_checksumFlag#: A 32-bits checksum of content is written at end of frame (default:0)

enumerator ZSTD_c_dictIDFlag#: When applicable, dictionary’s ID is written into frame header (default:1)

enumerator ZSTD_c_nbWorkers#

Select how many threads will be spawned to compress in parallel. 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, 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 : in which case, ZSTD_compressStream2() delegates to ZSTD_compress2()

, which is always a blocking call.

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, and all invocations are blocking

enumerator ZSTD_c_jobSize#

Size of a compression job. This value is enforced only when nbWorkers >= 1. 0 means default, which is dynamically determined based on compression parameters.

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.

enumerator ZSTD_c_overlapLog#

Control the overlap size, as a fraction of window size. The overlap size is an amount of data reloaded from previous job at the beginning of a new job. It helps preserve compression ratio, while each job is compressed in parallel. This value is enforced only when nbWorkers >= 1.

Larger values increase compression ratio, but decrease speed.

Possible values range from 0 to 9 :

0 means “default” : value will be determined by the library, depending on strategy
1 means “no overlap”
9 means “full overlap”, using a full window size.

Each intermediate rank increases/decreases load size by a factor 2 : 9: full window; 8: w/2; 7: w/4; 6: w/8; 5:w/16; 4: w/32; 3:w/64; 2:w/128; 1:no overlap; 0:default default value varies between 6 and 9, depending on strategy

enum ZSTD_dParameter#

Note

Additional experimental parameters are also available within the experimental section of the API. At the time of this writing, they include :

ZSTD_d_format
ZSTD_d_stableOutBuffer
ZSTD_d_forceIgnoreChecksum
ZSTD_d_refMultipleDDicts

Note

Because they are not stable, it’s necessary to define ZSTD_STATIC_LINKING_ONLY to access them.

Note

Never ever use experimentalParam names directly.

Values:

enumerator ZSTD_d_windowLogMax#: Select a size limit (in power of 2) beyond which the streaming API will refuse to allocate memory buffer in order to protect the host from unreasonable memory requirements. This parameter is only useful in streaming mode, since no internal buffer is allocated in single-pass mode. By default, a decompression context accepts window sizes <= (1 << ZSTD_WINDOWLOG_LIMIT_DEFAULT). Special: value 0 means “use default maximum windowLog”.

enum ZSTD_EndDirective#

Values:

enumerator ZSTD_e_continue#: collect more data, encoder decides when to output compressed result, for optimal compression ratio

enumerator ZSTD_e_flush#: flush any data provided so far, it creates (at least) one new block, that can be decoded immediately on reception; frame will continue: any future data can still reference previously compressed data, improving compression.

Note

Multithreaded compression will block to flush as much output as possible.

enumerator ZSTD_e_end#: flush any remaining data and close current frame. note that frame is only closed after compressed data is fully flushed (return value == 0). After that point, any additional data starts a new frame.

Note

Each frame is independent (does not reference any content from previous frame).

Note

Multithreaded compression will block to flush as much output as possible.

enum ZSTD_strategy#

Compression strategies, listed from fastest to strongest.

Note

New strategies might be added in the future. Only the order (from fast to strong) is guaranteed.

Values:

enumerator ZSTD_fast#

enumerator ZSTD_dfast#

enumerator ZSTD_greedy#

enumerator ZSTD_lazy#

enumerator ZSTD_lazy2#

enumerator ZSTD_btlazy2#

enumerator ZSTD_btopt#

enumerator ZSTD_btultra#

enumerator ZSTD_btultra2#

struct ZSTD_bounds#

Public Members

size_t error#: An error status field, that is tested using ZSTD_isError().

int lowerBound#: Lower bound of parameter. A value lower than lowerBound will either clamp it, or trigger an error (depending on parameter).

int upperBound#: Upper bound of parameter. A value higher than upperBound will either clamp it, or trigger an error (depending on parameter).

struct ZSTD_inBuffer_s#

Public Members

size_t pos#: position where reading stopped. Will be updated. Necessarily 0 <= pos <= size

size_t size#: size of input buffer

const void *src#: start of input buffer

struct ZSTD_outBuffer_s#

Public Members

void *dst#: start of output buffer

size_t pos#: position where writing stopped. Will be updated. Necessarily 0 <= pos <= size

size_t size#: size of output buffer