From: Yann Collet <cyan@fb.com>
Date: Mon, 18 Mar 2024 19:30:35 +0000 (-0700)
Subject: add doc on CCtx UB state
X-Git-Tag: v1.5.6^2~1^2~3
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=902c7ec1fe833f7f8d542fe94acba9e3a0a013a1;p=thirdparty%2Fzstd.git

add doc on CCtx UB state
---

diff --git a/lib/zstd.h b/lib/zstd.h
index d27e59317..b13e7e959 100644
--- a/lib/zstd.h
+++ b/lib/zstd.h
@@ -791,6 +791,11 @@ typedef enum {
  *            only ZSTD_e_end or ZSTD_e_flush operations are allowed.
  *            Before starting a new compression job, or changing compression parameters,
  *            it is required to fully flush internal buffers.
+ *  - note: if an operation ends with an error, it may leave @cctx in an undefined state.
+ *          Therefore, it's UB to invoke ZSTD_compressStream2() of ZSTD_compressStream() on such a state.
+ *          In order to be re-employed after an error, a state must be reset,
+ *          which can be done explicitly (ZSTD_CCtx_reset()),
+ *          or is sometimes implied by methods starting a new compression job (ZSTD_initCStream(), ZSTD_compressCCtx())
  */
 ZSTDLIB_API size_t ZSTD_compressStream2( ZSTD_CCtx* cctx,
                                          ZSTD_outBuffer* output,
@@ -905,11 +910,11 @@ ZSTDLIB_API size_t ZSTD_initDStream(ZSTD_DStream* zds);
  *           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.
+ * Note: when an operation returns with an error code, the @zds state may be 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,
+ *       In order to re-use such a state, it must be first reset,
  *       which can be done explicitly (`ZSTD_DCtx_reset()`),
- *       or is sometimes implied (`ZSTD_initDStream`, `ZSTD_decompressDCtx()`, `ZSTD_decompress_usingDict()`)
+ *       or is implied for operations starting some new decompression job (`ZSTD_initDStream`, `ZSTD_decompressDCtx()`, `ZSTD_decompress_usingDict()`)
  */
 ZSTDLIB_API size_t ZSTD_decompressStream(ZSTD_DStream* zds, ZSTD_outBuffer* output, ZSTD_inBuffer* input);