From: Yann Collet <cyan@fb.com>
Date: Mon, 18 Mar 2024 19:17:41 +0000 (-0700)
Subject: add a paragraph on UB DCtx state after error
X-Git-Tag: v1.5.6^2~1^2~4
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=5d82c2b57c0f5f239ba712a7e6ec46c84a6ba02d;p=thirdparty%2Fzstd.git

add a paragraph on UB DCtx state after error
---

diff --git a/lib/zstd.h b/lib/zstd.h
index 115d7f2ac..d27e59317 100644
--- a/lib/zstd.h
+++ b/lib/zstd.h
@@ -904,6 +904,12 @@ ZSTDLIB_API size_t ZSTD_initDStream(ZSTD_DStream* zds);
  * @return : 0 when a frame is completely decoded and fully flushed,
  *           or an error code, which can be tested using ZSTD_isError(),
  *           or any other value > 0, which means there is some decoding or flushing to do to complete current frame.
+ *
+ * Note: when an operation returns with an error code, the @zds state if left in undefined state.
+ *       It's UB to invoke `ZSTD_decompressStream()` on such a state.
+ *       In order to re-use such a state, it must be reset first,
+ *       which can be done explicitly (`ZSTD_DCtx_reset()`),
+ *       or is sometimes implied (`ZSTD_initDStream`, `ZSTD_decompressDCtx()`, `ZSTD_decompress_usingDict()`)
  */
 ZSTDLIB_API size_t ZSTD_decompressStream(ZSTD_DStream* zds, ZSTD_outBuffer* output, ZSTD_inBuffer* input);