From 4e091d595208ad208e432d57589f806794888c12 Mon Sep 17 00:00:00 2001 From: Yikun Wei Date: Sat, 14 Nov 2026 12:42:32 +0800 Subject: [PATCH] Docs: document cJSON_Version non-reentrant return value cJSON_Version() returns a pointer to a static internal buffer that is overwritten on every call, so the returned pointer is only valid until the next call and must not be shared between threads. This was not documented anywhere (the existing Thread Safety section only covered cJSON_GetErrorPtr, cJSON_InitHooks and setlocale). Add a note to the cJSON_Version declaration in cJSON.h, extend the "Thread Safety" section in README.md, and add a regression test in tests/misc_tests.c that captures the reused-buffer contract. --- README.md | 1 + cJSON.h | 6 +++++- tests/misc_tests.c | 16 ++++++++++++++++ 3 files changed, 22 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 9c7ed142c..1ada889b5 100644 --- a/README.md +++ b/README.md @@ -573,6 +573,7 @@ However it is thread safe under the following conditions: * `cJSON_GetErrorPtr` is never used (the `return_parse_end` parameter of `cJSON_ParseWithOpts` can be used instead) * `cJSON_InitHooks` is only ever called before using cJSON in any threads. +* `cJSON_Version` is not called concurrently from multiple threads. Note that `cJSON_Version` returns a pointer to an internal buffer that is overwritten on every call, so the returned pointer is only valid until the next call to `cJSON_Version` and must not be shared between threads (copy the string if you need to keep it). * `setlocale` is never called before all calls to cJSON functions have returned. #### Case Sensitivity diff --git a/cJSON.h b/cJSON.h index cab5feb42..a4460749e 100644 --- a/cJSON.h +++ b/cJSON.h @@ -143,7 +143,11 @@ typedef int cJSON_bool; #define CJSON_CIRCULAR_LIMIT 10000 #endif -/* returns the version of cJSON as a string */ +/* returns the version of cJSON as a string. + * NOTE: the returned pointer references an internal static buffer that is + * overwritten on every call. The pointer is only valid until the next call to + * cJSON_Version, and the function is not thread safe, so do not share the + * returned pointer between threads. Copy the string if you need to keep it. */ CJSON_PUBLIC(const char*) cJSON_Version(void); /* Supply malloc, realloc and free functions to cJSON */ diff --git a/tests/misc_tests.c b/tests/misc_tests.c index fe2325e96..5233d5a1d 100644 --- a/tests/misc_tests.c +++ b/tests/misc_tests.c @@ -799,6 +799,21 @@ static void cjson_parse_big_numbers_should_not_report_error(void) cJSON_Delete(valid_big_number_json_object2); } +static void cjson_version_should_return_reused_static_buffer(void) +{ + /* cJSON_Version returns a pointer to an internal static buffer that is + * overwritten on every call. The pointer is only valid until the next call + * to cJSON_Version and must not be shared between threads. This captures + * the documented non-reentrant contract (see issue E in the static review). */ + const char *first = cJSON_Version(); + const char *second = cJSON_Version(); + + TEST_ASSERT_NOT_NULL(first); + TEST_ASSERT_NOT_NULL(second); + /* both calls return the same static buffer */ + TEST_ASSERT_EQUAL_PTR(first, second); +} + int CJSON_CDECL main(void) { UNITY_BEGIN(); @@ -833,6 +848,7 @@ int CJSON_CDECL main(void) RUN_TEST(cjson_set_valuestring_to_object_should_not_leak_memory); RUN_TEST(cjson_set_bool_value_must_not_break_objects); RUN_TEST(cjson_parse_big_numbers_should_not_report_error); + RUN_TEST(cjson_version_should_return_reused_static_buffer); return UNITY_END(); }