From: Eric Haszlakiewicz <erh+git@nimenees.com>
Date: Sun, 21 Jun 2020 02:35:42 +0000 (+0000)
Subject: Update the json_tokener_parse_ex() docs to clarify that the final '\0' character... 
X-Git-Tag: json-c-0.15-20200726~31
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=50179fb09f5d317e7192c781ca4a6b039d7818ae;p=json-c

Update the json_tokener_parse_ex() docs to clarify that the final '\0' character is to be included in length passed in.
---

diff --git a/json_tokener.h b/json_tokener.h
index 8afa6ec..4e17dff 100644
--- a/json_tokener.h
+++ b/json_tokener.h
@@ -220,8 +220,8 @@ JSON_EXPORT void json_tokener_set_flags(struct json_tokener *tok, int flags);
  *
  * If json_tokener_parse_ex() returns NULL and the error is anything other than
  * json_tokener_continue, a fatal error has occurred and parsing must be
- * halted.  Then, the tok object must not be reused until json_tokener_reset() is
- * called.
+ * halted.  Then, the tok object must not be reused until json_tokener_reset()
+ * is called.
  *
  * When a valid JSON value is parsed, a non-NULL json_object will be
  * returned, with a reference count of one which belongs to the caller.  Also,
@@ -234,13 +234,18 @@ JSON_EXPORT void json_tokener_set_flags(struct json_tokener *tok, int flags);
  * error or to handle the additional characters, perhaps by parsing another
  * json value starting from that point.
  *
+ * If the caller knows that they are at the end of their input, the length
+ * passed MUST include the final '\0' character, so values with no inherent
+ * end (i.e. numbers) can be properly parsed, rather than just returning
+ * json_tokener_continue.
+ *
  * Extra characters can be detected by comparing the value returned by
  * json_tokener_get_parse_end() against
  * the length of the last len parameter passed in.
  *
  * The tokener does \b not maintain an internal buffer so the caller is
- * responsible for calling json_tokener_parse_ex with an appropriate str
- * parameter starting with the extra characters.
+ * responsible for a subsequent call to json_tokener_parse_ex with an 
+ * appropriate str parameter starting with the extra characters.
  *
  * This interface is presently not 64-bit clean due to the int len argument
  * so the function limits the maximum string size to INT32_MAX (2GB).
@@ -256,6 +261,8 @@ enum json_tokener_error jerr;
 do {
 	mystring = ...  // get JSON string, e.g. read from file, etc...
 	stringlen = strlen(mystring);
+	if (end_of_input)
+		stringlen++;  // Include the '\0' if we know we're at the end of input
 	jobj = json_tokener_parse_ex(tok, mystring, stringlen);
 } while ((jerr = json_tokener_get_error(tok)) == json_tokener_continue);
 if (jerr != json_tokener_success)