anil.recoil.org / unpac-myspace-ocaml
My working unpac space for OCaml projects in development
0
fork

Configure Feed

Select the types of activity you want to include in your feed.

Merge pull request #4498 from facebook/contentSize_doc

update documentation of ZSTD_getFrameContentSize()

authored by

Yann Collet and committed by
GitHub 25470b89 ece76cf9

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