TIP #661 implementation: Disable the Tcl 8 compatibility macros in Tcl 9 by default. Revert TIP #664

8 files changed, 52 insertions, 43 deletions

diff --git a/doc/ByteArrObj.3 b/doc/ByteArrObj.3
index 70ebe04..5aa541b 100644
--- a/doc/ByteArrObj.3
+++ b/doc/ByteArrObj.3
@@ -46,10 +46,10 @@ Interpreter to use for error reporting.
 .AP "Tcl_Size \&| int" *numBytesPtr out
 Points to space where the number of bytes in the array may be written.
 May be (Tcl_Size *)NULL when not used. If it points to a variable which
-type is not \fBTcl_Size\fR, a compiler warning will be generated, in
-order to indicate that when size of the byte array is larger than INT_MAX
-this function will return NULL (which should trigger proper error-handling).
-Apart from that, it will function as expected.
+type is not \fBTcl_Size\fR, a compiler warning will be generated.
+If your extensions is compiled with -DTCL_8_API, this function will return
+NULL if the size of the byte array is larger than INT_MAX (which should
+trigger proper error-handling), otherwise expect it to crash.
 .BE
 .SH DESCRIPTION
 .PP
diff --git a/doc/DictObj.3 b/doc/DictObj.3
index 8aa4ad1..7469a78 100644
--- a/doc/DictObj.3
+++ b/doc/DictObj.3
@@ -72,11 +72,12 @@ placed within it.  For \fBTcl_DictObjFirst\fR and
 not interested in the value.
 .AP "Tcl_Size \&| int" *sizePtr out
 Points to a variable that will have the number of key/value pairs
-contained within the dictionary placed within it. May be (Tcl_Size *)NULL when not used. If it points to a variable which
-type is not \fBTcl_Size\fR, a compiler warning will be generated, in
-order to indicate that when size of the dictionary is larger than INT_MAX
-this function will return TCL_ERROR (which should trigger proper error-handling).
-Apart from that, it will function as expected.
+contained within the dictionary placed within it.
+May be (Tcl_Size *)NULL when not used. If it points to a variable which
+type is not \fBTcl_Size\fR, a compiler warning will be generated.
+If your extensions is compiled with -DTCL_8_API, this function will return
+NULL if the size of the dictionary is larger than INT_MAX (which should
+trigger proper error-handling), otherwise expect it to crash.
 .AP Tcl_DictSearch *searchPtr in/out
 Pointer to record to use to keep track of progress in enumerating all
 key/value pairs in a dictionary.  The contents of the record will be
diff --git a/doc/FileSystem.3 b/doc/FileSystem.3
index 86a46c7..b8766e7 100644
--- a/doc/FileSystem.3
+++ b/doc/FileSystem.3
@@ -270,11 +270,12 @@ allowed for the \fImode\fR argument to the Tcl \fBopen\fR command.
 POSIX-style permission flags such as 0644. If a new file is created, these
 permissions will be set on the created file.
 .AP "Tcl_Size \&| int" *lenPtr out
-Filled with the number of elements in the split path. May be (Tcl_Size *)NULL when not used. If it points to a variable which
-type is not \fBTcl_Size\fR, a compiler warning will be generated, in
-order to indicate that when number of elements is larger than INT_MAX
-this function will return NULL (which should trigger proper error-handling).
-Apart from that, it will function as expected.
+Filled with the number of elements in the split path.
+May be (Tcl_Size *)NULL when not used. If it points to a variable which
+type is not \fBTcl_Size\fR, a compiler warning will be generated.
+If your extensions is compiled with -DTCL_8_API, this function will return
+NULL if the number of elements is larger than INT_MAX (which should
+trigger proper error-handling), otherwise expect it to crash.
 .AP Tcl_Obj *basePtr in
 The base path on to which to join the given elements. May be NULL.
 .AP Tcl_Size objc in
diff --git a/doc/ListObj.3 b/doc/ListObj.3
index 4445892..220cd08 100644
--- a/doc/ListObj.3
+++ b/doc/ListObj.3
@@ -61,11 +61,12 @@ this points to the Tcl value that will be converted to a list value
 containing the \fIobjc\fR elements of the array referenced by \fIobjv\fR.
 .AP "Tcl_Size \&| int" *objcPtr in
 Points to location where \fBTcl_ListObjGetElements\fR
-stores the number of element values in \fIlistPtr\fR. May be (Tcl_Size *)NULL when not used. If it points to a variable which
-type is not \fBTcl_Size\fR, a compiler warning will be generated, in
-order to indicate that when the list size is larger than INT_MAX
-this function will return TCL_ERROR (which should trigger proper error-handling).
-Apart from that, it will function as expected.
+stores the number of element values in \fIlistPtr\fR.
+May be (Tcl_Size *)NULL when not used. If it points to a variable which
+type is not \fBTcl_Size\fR, a compiler warning will be generated.
+If your extensions is compiled with -DTCL_8_API, this function will return
+NULL if the list size is larger than INT_MAX (which should
+trigger proper error-handling), otherwise expect it to crash.
 .AP Tcl_Obj ***objvPtr out
 A location where \fBTcl_ListObjGetElements\fR stores a pointer to an array
 of pointers to the element values of \fIlistPtr\fR.
@@ -82,11 +83,12 @@ and \fBTcl_ListObjReplace\fR will insert them into an existing \fIlistPtr\fR.
 Each value will become a separate list element.
 .AP "Tcl_Size \&| int" *lengthPtr out
 Points to location where \fBTcl_ListObjLength\fR
-stores the length of the list. May be (Tcl_Size *)NULL when not used. If it points to a variable which
-type is not \fBTcl_Size\fR, a compiler warning will be generated, in
-order to indicate that when the list size is larger than INT_MAX
-this function will return TCL_ERROR (which should trigger proper error-handling).
-Apart from that, it will function as expected.
+stores the length of the list.
+May be (Tcl_Size *)NULL when not used. If it points to a variable which
+type is not \fBTcl_Size\fR, a compiler warning will be generated.
+If your extensions is compiled with -DTCL_8_API, this function will return
+NULL if the list size is larger than INT_MAX (which should
+trigger proper error-handling), otherwise expect it to crash.
 .AP Tcl_Size index in
 Index of the list element that \fBTcl_ListObjIndex\fR
 is to return.
diff --git a/doc/ParseArgs.3 b/doc/ParseArgs.3
index ab3b7d8..ca6f52d 100644
--- a/doc/ParseArgs.3
+++ b/doc/ParseArgs.3
@@ -24,11 +24,12 @@ Pointer to array of option descriptors.
 .AP "Tcl_Size \&| int" *objcPtr in/out
 A pointer to variable holding number of arguments in \fIobjv\fR. Will be
 modified to hold number of arguments left in the unprocessed argument list
-stored in \fIremObjv\fR. May be (Tcl_Size *)NULL when not used. If it points to a variable which
-type is not \fBTcl_Size\fR, a compiler warning will be generated, in
-order to indicate that when the number of elements is larger than INT_MAX
-this function will return TCL_ERROR (which should trigger proper error-handling).
-Apart from that, it will function as expected.
+stored in \fIremObjv\fR.
+May be (Tcl_Size *)NULL when not used. If it points to a variable which
+type is not \fBTcl_Size\fR, a compiler warning will be generated.
+If your extensions is compiled with -DTCL_8_API, this function will return
+NULL if the number of elements is larger than INT_MAX (which should
+trigger proper error-handling), otherwise expect it to crash.
 .AP "Tcl_Obj *const" *objv in
 The array of arguments to be parsed.
 .AP Tcl_Obj ***remObjv out
diff --git a/doc/SplitList.3 b/doc/SplitList.3
index 2aa5e7c..9f43731 100644
--- a/doc/SplitList.3
+++ b/doc/SplitList.3
@@ -39,11 +39,12 @@ is left.
 .AP "const char" *list in
 Pointer to a string with proper list structure.
 .AP "Tcl_Size \&| int" *argcPtr out
-Filled in with number of elements in \fIlist\fR. May be (Tcl_Size *)NULL when not used. If it points to a variable which
-type is not \fBTcl_Size\fR, a compiler warning will be generated, in
-order to indicate that when the list size is larger than INT_MAX
-this function will return TCL_ERROR (which should trigger proper error-handling).
-Apart from that, it will function as expected.
+Filled in with number of elements in \fIlist\fR.
+May be (Tcl_Size *)NULL when not used. If it points to a variable which
+type is not \fBTcl_Size\fR, a compiler warning will be generated.
+If your extensions is compiled with -DTCL_8_API, this function will return
+NULL if the list size is larger than INT_MAX (which should
+trigger proper error-handling), otherwise expect it to crash.
 .AP "const char" ***argvPtr out
 \fI*argvPtr\fR will be filled in with the address of an array of
 pointers to the strings that are the extracted elements of \fIlist\fR.
diff --git a/doc/SplitPath.3 b/doc/SplitPath.3
index 54e33da..f55ee3c 100644
--- a/doc/SplitPath.3
+++ b/doc/SplitPath.3
@@ -26,11 +26,12 @@ Tcl_PathType
 File path in a form appropriate for the current platform (see the
 \fBfilename\fR manual entry for acceptable forms for path names).
 .AP "Tcl_Size \&| int" *argcPtr out
-Filled in with number of path elements in \fIpath\fR. May be (Tcl_Size *)NULL when not used. If it points to a variable which
-type is not \fBTcl_Size\fR, a compiler warning will be generated, in
-order to indicate that when the number of elements is larger than INT_MAX
-this function will return TCL_ERROR (which should trigger proper error-handling).
-Apart from that, it will function as expected.
+Filled in with number of path elements in \fIpath\fR.
+May be (Tcl_Size *)NULL when not used. If it points to a variable which
+type is not \fBTcl_Size\fR, a compiler warning will be generated.
+If your extensions is compiled with -DTCL_8_API, this function will return
+NULL if the number of elements is larger than INT_MAX (which should
+trigger proper error-handling), otherwise expect it to crash.
 .AP "const char" ***argvPtr out
 \fI*argvPtr\fR will be filled in with the address of an array of
 pointers to the strings that are the extracted elements of \fIpath\fR.
diff --git a/doc/StringObj.3 b/doc/StringObj.3
index 0da0e43..305af9a 100644
--- a/doc/StringObj.3
+++ b/doc/StringObj.3
@@ -120,10 +120,12 @@ A pointer to a value to read, or to an unshared value to modify.
 The value to append to \fIobjPtr\fR in \fBTcl_AppendObjToObj\fR.
 .AP "Tcl_Size \&| int" *lengthPtr out
 The location where \fBTcl_GetStringFromObj\fR will store the length
-of a value's string representation. May be (Tcl_Size *)NULL when not used. If it points to a variable which
-type is not \fBTcl_Size\fR, a compiler warning will be generated, in
-order to indicate that when the string is larger than INT_MAX
-this function will panic.
+of a value's string representation.
+May be (Tcl_Size *)NULL when not used. If it points to a variable which
+type is not \fBTcl_Size\fR, a compiler warning will be generated.
+If your extensions is compiled with -DTCL_8_API, this function will
+panic if the number of elements is larger than INT_MAX (which should
+trigger proper error-handling), otherwise expect it to crash.
 .AP "const char" *string in
 Null-terminated string value to append to \fIobjPtr\fR.
 .AP Tcl_Size limit in