Improve doc: error-handling in Dict/List when > 2**31 elements

3 files changed, 10 insertions, 4 deletions

diff --git a/doc/DictObj.3 b/doc/DictObj.3
index 73b0da8..ca9847c 100644
--- a/doc/DictObj.3
+++ b/doc/DictObj.3
@@ -138,7 +138,8 @@ converted to a dictionary.
 \fBTcl_DictObjSize\fR updates the given variable with the number of
 key/value pairs currently in the given dictionary. The result of this
 procedure is \fBTCL_OK\fR, or \fBTCL_ERROR\fR if the \fIdictPtr\fR cannot be
-converted to a dictionary.
+converted to a dictionary or if \fIsizePtr\fR points to a variable of type
+\fBint\fR and the dict contains more than 2**31 key/value pairs.
 .PP
 \fBTcl_DictObjFirst\fR commences an iteration across all the key/value
 pairs in the given dictionary, placing the key and value in the
diff --git a/doc/ListObj.3 b/doc/ListObj.3
index 09ab3b7..c4aa4bc 100644
--- a/doc/ListObj.3
+++ b/doc/ListObj.3
@@ -153,7 +153,9 @@ address \fIobjcPtr\fR.  Similarly, it returns the array pointer by storing
 it in the address \fIobjvPtr\fR.
 The memory pointed to is managed by Tcl and should not be freed or written
 to by the caller. If the list is empty, 0 is stored at \fIobjcPtr\fR
-and NULL at \fIobjvPtr\fR.
+and NULL at \fIobjvPtr\fR. If \fIobjcPtr\fR points to a variable
+of type \fBint\fR and the list contains more than 2**31 elements, the
+function returns \fBTCL_ERROR\fR.
 If \fIlistPtr\fR is not already a list value, \fBTcl_ListObjGetElements\fR
 will attempt to convert it to one; if the conversion fails, it returns
 \fBTCL_ERROR\fR and leaves an error message in the interpreter's result
@@ -163,6 +165,8 @@ Otherwise it returns \fBTCL_OK\fR after storing the count and array pointer.
 \fBTcl_ListObjLength\fR returns the number of elements in the list value
 referenced by \fIlistPtr\fR.
 It returns this count by storing a value in the address \fIlengthPtr\fR.
+If \fIlengthPtr\fR points to a variable of type \fBint\fR and the list
+contains more than 2**31 elements, the function returns \fBTCL_ERROR\fR.
 If the value is not already a list value,
 \fBTcl_ListObjLength\fR will attempt to convert it to one;
 if the conversion fails, it returns \fBTCL_ERROR\fR
diff --git a/doc/SplitList.3 b/doc/SplitList.3
index 696906c..f56330b 100644
--- a/doc/SplitList.3
+++ b/doc/SplitList.3
@@ -97,8 +97,9 @@ Tcl_Free(argv);
 .CE
 .PP
 \fBTcl_SplitList\fR normally returns \fBTCL_OK\fR, which means the list was
-successfully parsed.
-If there was a syntax error in \fIlist\fR, then \fBTCL_ERROR\fR is returned
+successfully parsed. If \fIsizePtr\fR points to a variable of type
+\fBint\fR and the list contains more than 2**31 key/value pairs, or there was
+a syntax error in \fIlist\fR, then \fBTCL_ERROR\fR is returned
 and the interpreter's result will point to an error message describing the
 problem (if \fIinterp\fR was not NULL).
 If \fBTCL_ERROR\fR is returned then no memory is allocated and \fI*argvPtr\fR