sharpetronics/zstd
1
0
Fork 0
mirror of https://github.com/facebook/zstd.git synced 2025-10-04 00:02:33 -04:00
Code Issues Projects Releases Wiki Activity

Merge pull request #4498 from facebook/contentSize_doc

Browse Source 
update documentation of ZSTD_getFrameContentSize()
This commit is contained in:
Yann Collet 2025-09-23 23:59:34 -07:00 committed by GitHub
commit a8f732e50f
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 24 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
lib/zstd.h
View File

@ -176,30 +176,30 @@ ZSTDLIB_API size_t ZSTD_decompress( void* dst, size_t dstCapacity,
/*====== Decompression helper functions ======*/ /*====== Decompression helper functions ======*/
/*! ZSTD_getFrameContentSize() : requires v1.3.0+ /*! @brief Returns the decompressed content size stored in a ZSTD frame header.
* `src` should point to the start of a ZSTD encoded frame. *
* `srcSize` must be at least as large as the frame header. * @since v1.3.0
* hint : any size >= `ZSTD_frameHeaderSize_max` is large enough. *
* @return : - decompressed size of `src` frame content, if known * @param src Pointer to the beginning of a ZSTD encoded frame.
* - ZSTD_CONTENTSIZE_UNKNOWN if the size cannot be determined * @param srcSize Size of the buffer pointed to by @p src. It must be at least as large as the frame header.
* - ZSTD_CONTENTSIZE_ERROR if an error occurred (e.g. invalid magic number, srcSize too small) * Any value greater than or equal to `ZSTD_frameHeaderSize_max` is sufficient.
* note 1 : a 0 return value means the frame is valid but "empty". * @return The decompressed size in bytes when the value is available in the frame header.
* When invoking this method on a skippable frame, it will return 0. * @retval ZSTD_CONTENTSIZE_UNKNOWN The frame does not encode a decompressed size (typical for streaming).
* note 2 : decompressed size is an optional field, it may not be present (typically in streaming mode). * @retval ZSTD_CONTENTSIZE_ERROR An error occurred (e.g. invalid magic number, @p srcSize too small).
* 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. * @note The return value is not compatible with `ZSTD_isError()`.
* Optionally, application can rely on some implicit limit, * @note A return value of 0 denotes a valid but empty frame. Skippable frames also report 0.
* as ZSTD_decompress() only needs an upper bound of decompressed size. * @note The decompressed size field is optional. When it is absent (the function returns @c ZSTD_CONTENTSIZE_UNKNOWN),
* (For example, data could be necessarily cut into blocks <= 16 KB). * the caller must rely on streaming decompression or an application-specific upper bound. `ZSTD_decompress()`
* note 3 : decompressed size is always present when compression is completed using single-pass functions, * only requires an upper bound, so applications may enforce their own block limits (for example 16 KB).
* such as ZSTD_compress(), ZSTD_compressCCtx() ZSTD_compress_usingDict() or ZSTD_compress_usingCDict(). * @note The decompressed size is guaranteed to be present when compression was performed with single-pass APIs such as
* note 4 : decompressed size can be very large (64-bits value), * `ZSTD_compress()`, `ZSTD_compressCCtx()`, `ZSTD_compress_usingDict()`, or `ZSTD_compress_usingCDict()`.
* potentially larger than what local system can handle as a single memory segment. * @note The decompressed size is a 64-bit value and may exceed the addressable space of the system. Use streaming
* In which case, it's necessary to use streaming mode to decompress data. * decompression when the value is too large to materialize in contiguous memory.
* note 5 : If source is untrusted, decompressed size could be wrong or intentionally modified. * @warning When processing untrusted input, validate the returned size against the application's limits; attackers may
* Always ensure return value fits within application's authorized limits. * forge an arbitrarily large value.
* Each application can set its own limits. * @note This function replaces `ZSTD_getDecompressedSize()`.
* note 6 : This function replaces ZSTD_getDecompressedSize() */ */
#define ZSTD_CONTENTSIZE_UNKNOWN (0ULL - 1) #define ZSTD_CONTENTSIZE_UNKNOWN (0ULL - 1)
#define ZSTD_CONTENTSIZE_ERROR (0ULL - 2) #define ZSTD_CONTENTSIZE_ERROR (0ULL - 2)
ZSTDLIB_API unsigned long long ZSTD_getFrameContentSize(const void *src, size_t srcSize); ZSTDLIB_API unsigned long long ZSTD_getFrameContentSize(const void *src, size_t srcSize);