Compress-Zstd
view release on metacpan or search on metacpan
ext/zstd/contrib/linux-kernel/include/linux/zstd.h view on Meta::CPAN
size_t ZSTD_compressStream(ZSTD_CStream *zcs, ZSTD_outBuffer *output,
ZSTD_inBuffer *input);
/**
* ZSTD_flushStream() - flush internal buffers into output
* @zcs: The zstd streaming compression context.
* @output: Destination buffer. `output->pos` is updated to indicate how much
* compressed data was written.
*
* ZSTD_flushStream() must be called until it returns 0, meaning all the data
* has been flushed. Since ZSTD_flushStream() causes a block to be ended,
* calling it too often will degrade the compression ratio.
*
* Return: The number of bytes still present within internal buffers or an
* error, which can be checked using ZSTD_isError().
*/
size_t ZSTD_flushStream(ZSTD_CStream *zcs, ZSTD_outBuffer *output);
/**
* ZSTD_endStream() - flush internal buffers into output and end the frame
* @zcs: The zstd streaming compression context.
* @output: Destination buffer. `output->pos` is updated to indicate how much
* compressed data was written.
*
* ZSTD_endStream() must be called until it returns 0, meaning all the data has
* been flushed and the frame epilogue has been written.
*
* Return: The number of bytes still present within internal buffers or an
* error, which can be checked using ZSTD_isError().
*/
size_t ZSTD_endStream(ZSTD_CStream *zcs, ZSTD_outBuffer *output);
/**
* ZSTD_CStreamInSize() - recommended size for the input buffer
*
* Return: The recommended size for the input buffer.
*/
size_t ZSTD_CStreamInSize(void);
/**
* ZSTD_CStreamOutSize() - recommended size for the output buffer
*
* When the output buffer is at least this large, it is guaranteed to be large
* enough to flush at least one complete compressed block.
*
* Return: The recommended size for the output buffer.
*/
size_t ZSTD_CStreamOutSize(void);
/*-*****************************************************************************
* Streaming decompression - HowTo
*
* A ZSTD_DStream object is required to track streaming operations.
* Use ZSTD_initDStream() to initialize a ZSTD_DStream object.
* ZSTD_DStream objects can be re-used multiple times.
*
* Use ZSTD_decompressStream() repetitively to consume your input.
* 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.
* If `output->pos < output->size`, decoder has flushed everything it could.
* Returns 0 iff a frame is completely decoded and fully flushed.
* Otherwise it returns a suggested next input size that will never load more
* than the current frame.
******************************************************************************/
/**
* ZSTD_DStreamWorkspaceBound() - memory needed to initialize a ZSTD_DStream
* @maxWindowSize: The maximum window size allowed for compressed frames.
*
* Return: A lower bound on the size of the workspace that is passed to
* ZSTD_initDStream() and ZSTD_initDStream_usingDDict().
*/
size_t ZSTD_DStreamWorkspaceBound(size_t maxWindowSize);
/**
* struct ZSTD_DStream - the zstd streaming decompression context
*/
typedef struct ZSTD_DStream_s ZSTD_DStream;
/*===== ZSTD_DStream management functions =====*/
/**
* ZSTD_initDStream() - initialize a zstd streaming decompression context
* @maxWindowSize: The maximum window size allowed for compressed frames.
* @workspace: The workspace to emplace the context into. It must outlive
* the returned context.
* @workspaceSize: The size of workspace.
* Use ZSTD_DStreamWorkspaceBound(maxWindowSize) to determine
* how large the workspace must be.
*
* Return: The zstd streaming decompression context.
*/
ZSTD_DStream *ZSTD_initDStream(size_t maxWindowSize, void *workspace,
size_t workspaceSize);
/**
* ZSTD_initDStream_usingDDict() - initialize streaming decompression context
* @maxWindowSize: The maximum window size allowed for compressed frames.
* @ddict: The digested dictionary to use for decompression.
* @workspace: The workspace to emplace the context into. It must outlive
* the returned context.
* @workspaceSize: The size of workspace.
* Use ZSTD_DStreamWorkspaceBound(maxWindowSize) to determine
* how large the workspace must be.
*
* Return: The zstd streaming decompression context.
*/
ZSTD_DStream *ZSTD_initDStream_usingDDict(size_t maxWindowSize,
const ZSTD_DDict *ddict, void *workspace, size_t workspaceSize);
/*===== Streaming decompression functions =====*/
/**
* ZSTD_resetDStream() - reset the context using parameters from creation
* @zds: The zstd streaming decompression context to reset.
*
* Resets the context using the parameters from creation. Skips dictionary
* loading, since it can be reused.
*
* Return: Zero or an error, which can be checked using ZSTD_isError().
*/
size_t ZSTD_resetDStream(ZSTD_DStream *zds);
/**
* ZSTD_decompressStream() - streaming decompress some of input into output
* @zds: The zstd streaming decompression context.
* @output: Destination buffer. `output.pos` is updated to indicate how much
* decompressed data was written.
* @input: Source buffer. `input.pos` is updated to indicate how much data was
* read. Note that it may not consume the entire input, in which case
* `input.pos < input.size`, and it's up to the caller to present
* remaining data again.
*
* The `input` and `output` buffers may be any size. Guaranteed to make some
* forward progress if `input` and `output` are not empty.
* ZSTD_decompressStream() will not consume the last byte of the frame until
* the entire frame is flushed.
*
* Return: Returns 0 iff a frame is completely decoded and fully flushed.
* Otherwise returns a hint for the number of bytes to use as the input
* for the next function call or an error, which can be checked using
* ZSTD_isError(). The size hint will never load more than the frame.
*/
size_t ZSTD_decompressStream(ZSTD_DStream *zds, ZSTD_outBuffer *output,
ZSTD_inBuffer *input);
/**
* ZSTD_DStreamInSize() - recommended size for the input buffer
*
* Return: The recommended size for the input buffer.
*/
size_t ZSTD_DStreamInSize(void);
/**
* ZSTD_DStreamOutSize() - recommended size for the output buffer
*
* When the output buffer is at least this large, it is guaranteed to be large
* enough to flush at least one complete decompressed block.
*
* Return: The recommended size for the output buffer.
*/
size_t ZSTD_DStreamOutSize(void);
/* --- Constants ---*/
#define ZSTD_MAGICNUMBER 0xFD2FB528 /* >= v0.8.0 */
#define ZSTD_MAGIC_SKIPPABLE_START 0x184D2A50U
#define ZSTD_CONTENTSIZE_UNKNOWN (0ULL - 1)
#define ZSTD_CONTENTSIZE_ERROR (0ULL - 2)
#define ZSTD_WINDOWLOG_MAX_32 27
#define ZSTD_WINDOWLOG_MAX_64 27
#define ZSTD_WINDOWLOG_MAX \
((unsigned int)(sizeof(size_t) == 4 \
? ZSTD_WINDOWLOG_MAX_32 \
: ZSTD_WINDOWLOG_MAX_64))
#define ZSTD_WINDOWLOG_MIN 10
#define ZSTD_HASHLOG_MAX ZSTD_WINDOWLOG_MAX
#define ZSTD_HASHLOG_MIN 6
#define ZSTD_CHAINLOG_MAX (ZSTD_WINDOWLOG_MAX+1)
#define ZSTD_CHAINLOG_MIN ZSTD_HASHLOG_MIN
#define ZSTD_HASHLOG3_MAX 17
#define ZSTD_SEARCHLOG_MAX (ZSTD_WINDOWLOG_MAX-1)
#define ZSTD_SEARCHLOG_MIN 1
/* only for ZSTD_fast, other strategies are limited to 6 */
#define ZSTD_SEARCHLENGTH_MAX 7
/* only for ZSTD_btopt, other strategies are limited to 4 */
#define ZSTD_SEARCHLENGTH_MIN 3
#define ZSTD_TARGETLENGTH_MIN 4
#define ZSTD_TARGETLENGTH_MAX 999
/* for static allocation */
#define ZSTD_FRAMEHEADERSIZE_MAX 18
#define ZSTD_FRAMEHEADERSIZE_MIN 6
static const size_t ZSTD_frameHeaderSize_prefix = 5;
static const size_t ZSTD_frameHeaderSize_min = ZSTD_FRAMEHEADERSIZE_MIN;
static const size_t ZSTD_frameHeaderSize_max = ZSTD_FRAMEHEADERSIZE_MAX;
/* magic number + skippable frame length */
static const size_t ZSTD_skippableHeaderSize = 8;
ext/zstd/contrib/linux-kernel/include/linux/zstd.h view on Meta::CPAN
* Advanced compression functions
**************************************/
/**
* ZSTD_checkCParams() - ensure parameter values remain within authorized range
* @cParams: The zstd compression parameters.
*
* Return: Zero or an error, which can be checked using ZSTD_isError().
*/
size_t ZSTD_checkCParams(ZSTD_compressionParameters cParams);
/**
* ZSTD_adjustCParams() - optimize parameters for a given srcSize and dictSize
* @srcSize: Optionally the estimated source size, or zero if unknown.
* @dictSize: Optionally the estimated dictionary size, or zero if unknown.
*
* Return: The optimized parameters.
*/
ZSTD_compressionParameters ZSTD_adjustCParams(
ZSTD_compressionParameters cParams, unsigned long long srcSize,
size_t dictSize);
/*--- Advanced decompression functions ---*/
/**
* ZSTD_isFrame() - returns true iff the buffer starts with a valid frame
* @buffer: The source buffer to check.
* @size: The size of the source buffer, must be at least 4 bytes.
*
* Return: True iff the buffer starts with a zstd or skippable frame identifier.
*/
unsigned int ZSTD_isFrame(const void *buffer, size_t size);
/**
* ZSTD_getDictID_fromDict() - returns the dictionary id stored in a dictionary
* @dict: The dictionary buffer.
* @dictSize: The size of the dictionary buffer.
*
* Return: The dictionary id stored within the dictionary or 0 if the
* dictionary is not a zstd dictionary. If it returns 0 the
* dictionary can still be loaded as a content-only dictionary.
*/
unsigned int ZSTD_getDictID_fromDict(const void *dict, size_t dictSize);
/**
* ZSTD_getDictID_fromDDict() - returns the dictionary id stored in a ZSTD_DDict
* @ddict: The ddict to find the id of.
*
* Return: The dictionary id stored within `ddict` or 0 if the dictionary is not
* a zstd dictionary. If it returns 0 `ddict` will be loaded as a
* content-only dictionary.
*/
unsigned int ZSTD_getDictID_fromDDict(const ZSTD_DDict *ddict);
/**
* ZSTD_getDictID_fromFrame() - returns the dictionary id stored in a zstd frame
* @src: Source buffer. It must be a zstd encoded frame.
* @srcSize: The size of the source buffer. It must be at least as large as the
* frame header. `ZSTD_frameHeaderSize_max` is always large enough.
*
* Return: The dictionary id required to decompress the frame stored within
* `src` or 0 if the dictionary id could not be decoded. It can return
* 0 if the frame does not require a dictionary, the dictionary id
* wasn't stored in the frame, `src` is not a zstd frame, or `srcSize`
* is too small.
*/
unsigned int ZSTD_getDictID_fromFrame(const void *src, size_t srcSize);
/**
* struct ZSTD_frameParams - zstd frame parameters stored in the frame header
* @frameContentSize: The frame content size, or 0 if not present.
* @windowSize: The window size, or 0 if the frame is a skippable frame.
* @dictID: The dictionary id, or 0 if not present.
* @checksumFlag: Whether a checksum was used.
*/
typedef struct {
unsigned long long frameContentSize;
unsigned int windowSize;
unsigned int dictID;
unsigned int checksumFlag;
} ZSTD_frameParams;
/**
* ZSTD_getFrameParams() - extracts parameters from a zstd or skippable frame
* @fparamsPtr: On success the frame parameters are written here.
* @src: The source buffer. It must point to a zstd or skippable frame.
* @srcSize: The size of the source buffer. `ZSTD_frameHeaderSize_max` is
* always large enough to succeed.
*
* Return: 0 on success. If more data is required it returns how many bytes
* must be provided to make forward progress. Otherwise it returns
* an error, which can be checked using ZSTD_isError().
*/
size_t ZSTD_getFrameParams(ZSTD_frameParams *fparamsPtr, const void *src,
size_t srcSize);
/*-*****************************************************************************
* Buffer-less and synchronous inner streaming functions
*
* 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 many restrictions (documented below).
* Prefer using normal streaming API for an easier experience
******************************************************************************/
/*-*****************************************************************************
* Buffer-less streaming compression (synchronous mode)
*
* A ZSTD_CCtx object is required to track streaming operations.
* Use ZSTD_initCCtx() to initialize a context.
* ZSTD_CCtx object can be re-used multiple times within successive compression
* operations.
*
* Start by initializing a context.
* Use ZSTD_compressBegin(), or ZSTD_compressBegin_usingDict() for dictionary
* compression,
* or ZSTD_compressBegin_advanced(), for finer parameter control.
* It's also possible to duplicate a reference context which has already been
* initialized, using ZSTD_copyCCtx()
*
* Then, consume your input using ZSTD_compressContinue().
* There are some important considerations to keep in mind when using this
ext/zstd/contrib/linux-kernel/include/linux/zstd.h view on Meta::CPAN
* frame.
******************************************************************************/
/*===== Buffer-less streaming compression functions =====*/
size_t ZSTD_compressBegin(ZSTD_CCtx *cctx, int compressionLevel);
size_t ZSTD_compressBegin_usingDict(ZSTD_CCtx *cctx, const void *dict,
size_t dictSize, int compressionLevel);
size_t ZSTD_compressBegin_advanced(ZSTD_CCtx *cctx, const void *dict,
size_t dictSize, ZSTD_parameters params,
unsigned long long pledgedSrcSize);
size_t ZSTD_copyCCtx(ZSTD_CCtx *cctx, const ZSTD_CCtx *preparedCCtx,
unsigned long long pledgedSrcSize);
size_t ZSTD_compressBegin_usingCDict(ZSTD_CCtx *cctx, const ZSTD_CDict *cdict,
unsigned long long pledgedSrcSize);
size_t ZSTD_compressContinue(ZSTD_CCtx *cctx, void *dst, size_t dstCapacity,
const void *src, size_t srcSize);
size_t ZSTD_compressEnd(ZSTD_CCtx *cctx, void *dst, size_t dstCapacity,
const void *src, size_t srcSize);
/*-*****************************************************************************
* Buffer-less streaming decompression (synchronous mode)
*
* A ZSTD_DCtx object is required to track streaming operations.
* Use ZSTD_initDCtx() to initialize a context.
* A ZSTD_DCtx object can be re-used multiple times.
*
* First typical operation is to retrieve frame parameters, using
* ZSTD_getFrameParams(). It fills a ZSTD_frameParams structure which provide
* important information to correctly decode the frame, such as the minimum
* rolling buffer size to allocate to decompress data (`windowSize`), and the
* dictionary ID used.
* Note: content size is optional, it may not be present. 0 means unknown.
* Note that these values could be wrong, either because of data malformation,
* or because an attacker is spoofing deliberate false information. As a
* consequence, check that values remain within valid application range,
* especially `windowSize`, before allocation. Each application can set its own
* limit, depending on local restrictions. For extended interoperability, it is
* recommended to support at least 8 MB.
* Frame parameters are extracted from the beginning of the compressed frame.
* Data fragment must be large enough to ensure successful decoding, typically
* `ZSTD_frameHeaderSize_max` bytes.
* Result: 0: successful decoding, the `ZSTD_frameParams` structure is filled.
* >0: `srcSize` is too small, provide at least this many bytes.
* errorCode, which can be tested using ZSTD_isError().
*
* Start decompression, with ZSTD_decompressBegin() or
* ZSTD_decompressBegin_usingDict(). Alternatively, you can copy a prepared
* context, using ZSTD_copyDCtx().
*
* Then use ZSTD_nextSrcSizeToDecompress() and ZSTD_decompressContinue()
* alternatively.
* ZSTD_nextSrcSizeToDecompress() tells how many bytes to provide as 'srcSize'
* to ZSTD_decompressContinue().
* ZSTD_decompressContinue() requires this _exact_ amount of bytes, or it will
* fail.
*
* The result of ZSTD_decompressContinue() is the number of bytes regenerated
* within 'dst' (necessarily <= dstCapacity). It can be zero, which is not an
* error; it just means ZSTD_decompressContinue() has decoded some metadata
* item. It can also be an error code, which can be tested with ZSTD_isError().
*
* ZSTD_decompressContinue() needs previous data blocks during decompression, up
* to `windowSize`. They should preferably be located contiguously, prior to
* current block. Alternatively, a round buffer of sufficient size is also
* possible. Sufficient size is determined by frame parameters.
* ZSTD_decompressContinue() is very sensitive to contiguity, if 2 blocks don't
* follow each other, make sure that either the compressor breaks contiguity at
* the same place, or that previous contiguous segment is large enough to
* properly handle maximum back-reference.
*
* A frame is fully decoded when ZSTD_nextSrcSizeToDecompress() returns zero.
* Context can then be reset to start a new decompression.
*
* Note: it's possible to know if next input to present is a header or a block,
* using ZSTD_nextInputType(). This information is not required to properly
* decode a frame.
*
* == Special case: skippable frames ==
*
* Skippable frames allow integration of user-defined data into a flow of
* concatenated frames. Skippable frames will be ignored (skipped) by a
* decompressor. The format of skippable frames is as follows:
* a) Skippable frame ID - 4 Bytes, Little endian format, any value from
* 0x184D2A50 to 0x184D2A5F
* b) Frame Size - 4 Bytes, Little endian format, unsigned 32-bits
* c) Frame Content - any content (User Data) of length equal to Frame Size
* For skippable frames ZSTD_decompressContinue() always returns 0.
* For skippable frames ZSTD_getFrameParams() returns fparamsPtr->windowLog==0
* what means that a frame is skippable.
* Note: If fparamsPtr->frameContentSize==0, it is ambiguous: the frame might
* actually be a zstd encoded frame with no content. For purposes of
* decompression, it is valid in both cases to skip the frame using
* ZSTD_findFrameCompressedSize() to find its size in bytes.
* It also returns frame size as fparamsPtr->frameContentSize.
******************************************************************************/
/*===== Buffer-less streaming decompression functions =====*/
size_t ZSTD_decompressBegin(ZSTD_DCtx *dctx);
size_t ZSTD_decompressBegin_usingDict(ZSTD_DCtx *dctx, const void *dict,
size_t dictSize);
void ZSTD_copyDCtx(ZSTD_DCtx *dctx, const ZSTD_DCtx *preparedDCtx);
size_t ZSTD_nextSrcSizeToDecompress(ZSTD_DCtx *dctx);
size_t ZSTD_decompressContinue(ZSTD_DCtx *dctx, void *dst, size_t dstCapacity,
const void *src, size_t srcSize);
typedef enum {
ZSTDnit_frameHeader,
ZSTDnit_blockHeader,
ZSTDnit_block,
ZSTDnit_lastBlock,
ZSTDnit_checksum,
ZSTDnit_skippableFrame
} ZSTD_nextInputType_e;
ZSTD_nextInputType_e ZSTD_nextInputType(ZSTD_DCtx *dctx);
/*-*****************************************************************************
* Block functions
*
* Block functions produce and decode raw zstd blocks, without frame metadata.
* Frame metadata cost is typically ~18 bytes, which can be non-negligible for
* very small blocks (< 100 bytes). User will have to take in charge required
* information to regenerate data, such as compressed and content sizes.
*
* A few rules to respect:
* - Compressing and decompressing require a context structure
* + Use ZSTD_initCCtx() and ZSTD_initDCtx()
* - It is necessary to init context before starting
* + compression : ZSTD_compressBegin()
* + decompression : ZSTD_decompressBegin()
* + variants _usingDict() are also allowed
* + copyCCtx() and copyDCtx() work too
* - Block size is limited, it must be <= ZSTD_getBlockSizeMax()
( run in 3.366 seconds using v1.01-cache-2.11-cpan-39bf76dae61 )