From 895f53d1cf9719f34b5248afe6aab33deeb8e26c Mon Sep 17 00:00:00 2001 From: Tim Ruffing Date: Wed, 20 Aug 2025 09:57:10 +0200 Subject: [PATCH 1/2] docs: Clarify that callback can be called more than once --- include/secp256k1.h | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/include/secp256k1.h b/include/secp256k1.h index f55a6ab976..ae31ff7084 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 From 4d90585feaa52711133deb0c5a3cb32fca73d042 Mon Sep 17 00:00:00 2001 From: Tim Ruffing Date: Wed, 20 Aug 2025 09:59:54 +0200 Subject: [PATCH 2/2] docs: Improve API docs of _context_set_illegal_callback --- include/secp256k1.h | 42 ++++++++++++++++++++++-------------------- 1 file changed, 22 insertions(+), 20 deletions(-) diff --git a/include/secp256k1.h b/include/secp256k1.h index ae31ff7084..b0a13b144d 100644 --- a/include/secp256k1.h +++ b/include/secp256k1.h @@ -261,7 +261,7 @@ SECP256K1_DEPRECATED("Use secp256k1_context_static instead"); * secp256k1_context_create (or secp256k1_context_preallocated_create), which will * take care of performing the self tests. * - * If the tests fail, this function will call the default error handler to abort the + * If the tests fail, this function will call the default error callback to abort the * program (see secp256k1_context_set_error_callback). */ SECP256K1_API void secp256k1_selftest(void); @@ -334,36 +334,37 @@ SECP256K1_API void secp256k1_context_destroy( * an API call. It will only trigger for violations that are mentioned * explicitly in the header. * - * The philosophy is that these shouldn't be dealt with through a - * specific return value, as calling code should not have branches to deal with - * the case that this code itself is broken. + * The philosophy is that these shouldn't be dealt with through a specific + * return value, as calling code should not have branches to deal with the case + * that this code itself is broken. * * On the other hand, during debug stage, one would want to be informed about - * such mistakes, and the default (crashing) may be inadvisable. - * 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 - * writes the message to stderr and calls abort. This default handler can be + * such mistakes, and the default (crashing) may be inadvisable. 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 fun==NULL), then the + * default callback will be used. The library provides a default callback which + * writes the message to stderr and calls abort. This default callback can be * replaced at link time if the preprocessor macro * USE_EXTERNAL_DEFAULT_CALLBACKS is defined, which is the case if the build * has been configured with --enable-external-default-callbacks. Then the * following two symbols must be provided to link against: * - void secp256k1_default_illegal_callback_fn(const char *message, void *data); * - void secp256k1_default_error_callback_fn(const char *message, void *data); - * The library can call these default handlers even before a proper callback data + * The library may call a default callback even before a proper callback data * pointer could have been set using secp256k1_context_set_illegal_callback or * secp256k1_context_set_error_callback, e.g., when the creation of a context - * fails. In this case, the corresponding default handler will be called with + * fails. In this case, the corresponding default callback will be called with * the data pointer argument set to NULL. * * Args: ctx: pointer to a context object. * In: fun: pointer to a function to call when an illegal argument is * passed to the API, taking a message and an opaque pointer. - * (NULL restores the default handler.) - * data: the opaque pointer to pass to fun above, must be NULL for the default handler. + * (NULL restores the default callback.) + * data: the opaque pointer to pass to fun above, must be NULL for the + * default callback. * * See also secp256k1_context_set_error_callback. */ @@ -380,8 +381,8 @@ SECP256K1_API void secp256k1_context_set_illegal_callback( * to abort the program. * * This can only trigger in case of a hardware failure, miscompilation, - * memory corruption, serious bug in the library, or other error would can - * otherwise result in undefined behaviour. It will not trigger due to mere + * memory corruption, serious bug in the library, or other error that would + * result in undefined behaviour. It will not trigger due to mere * incorrect usage of the API (see secp256k1_context_set_illegal_callback * for that). After this callback returns, anything may happen, including * crashing. @@ -389,9 +390,10 @@ SECP256K1_API void secp256k1_context_set_illegal_callback( * Args: ctx: pointer to a context object. * In: fun: pointer to a function to call when an internal error occurs, * taking a message and an opaque pointer (NULL restores the - * default handler, see secp256k1_context_set_illegal_callback + * default callback, see secp256k1_context_set_illegal_callback * for details). - * data: the opaque pointer to pass to fun above, must be NULL for the default handler. + * data: the opaque pointer to pass to fun above, must be NULL for the + * default callback. * * See also secp256k1_context_set_illegal_callback. */