view release on metacpan or  search on metacpan

ext/zstd/contrib/linux-kernel/include/linux/zstd.h  view on Meta::CPAN

 * - Caller must ensure there is enough space in `dst` to store compressed data
 *   under worst case scenario. Worst case evaluation is provided by
 *   ZSTD_compressBound().
 *   ZSTD_compressContinue() doesn't guarantee recover after a failed
 *   compression.
 * - ZSTD_compressContinue() presumes prior input ***is still accessible and
 *   unmodified*** (up to maximum distance size, see WindowLog).
 *   It remembers all previous contiguous blocks, plus one separated memory
 *   segment (which can itself consists of multiple contiguous blocks)
 * - ZSTD_compressContinue() detects that prior input has been overwritten when
 *   `src` buffer overlaps. In which case, it will "discard" the relevant memory
 *   section from its history.
 *
 * Finish a frame with ZSTD_compressEnd(), which will write the last block(s)
 * and optional checksum. It's possible to use srcSize==0, in which case, it
 * will write a final empty block to end the frame. Without last block mark,
 * frames will be considered unfinished (corrupted) by decoders.
 *
 * `ZSTD_CCtx` object can be re-used (ZSTD_compressBegin()) to compress some new
 * 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);