docs: Clarify that callback can be called more than once
What the developer wrote
Authored by Tim Ruffing
docs: Clarify that callback can be called more than once
What changed, and why it matters
This commit only changes a documentation comment in a header file. It clarifies that if a user-supplied error callback returns instead of aborting, the API call's results are undefined and the callback may be triggered more than once. No code behavior was changed.
No security action required. Reviewers may optionally verify that the new documentation accurately reflects existing implementation behavior.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The diff modifies a Doxygen-style comment for the callback-setting API in include/secp256k1.h. The previous wording stated that when the callback is triggered, the API function is guaranteed not to crash but its return value and outputs are undefined. The new wording states that if the callback returns instead of crashing, the return value and outputs are undefined, and the same API call may trigger the callback again. This is a documentation-only clarification; no implementation logic was altered.
Changed components
include/secp256k1.h documentation commentInspect captured patch +3 / −3
diff --git a/include/secp256k1.h b/include/secp256k1.h
index f55a6ab..ae31ff7 100644
--- a/include/secp256k1.h
+++ b/include/secp256k1.h
@@ -340,9 +340,9 @@ SECP256K1_API void secp256k1_context_destroy(
*
* On the other hand, during debug stage, one would want to be informed about
* such mistakes, and the default (crashing) may be inadvisable.
- * When this callback is triggered, the API function called is guaranteed not
- * to cause a crash, though its return value and output arguments are
- * undefined.
+ * Should this callback return instead of crashing, the return value and output
+ * arguments of the API function call are undefined. Moreover, the same API
+ * call may trigger the callback again in this case.
*
* When this function has not been called (or called with fn==NULL), then the
* default handler will be used. The library provides a default handler which
Why this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.