Merged revisions 72593 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk ........ r72593 | benjamin.peterson | 2009-05-12 16:06:05 -0500 (Tue, 12 May 2009) | 1 line the compiler attribute is used in setup.py; can't rename ........
author: Benjamin Peterson <benjamin@python.org> 2009-05-12 21:21:26 (GMT)
committer: Benjamin Peterson <benjamin@python.org> 2009-05-12 21:21:26 (GMT)
commit: 976faf9293aa1dd291ccd95465647f09004a52af (patch)
tree: a9e4f80a669fac50702f23b4f1670ecbc1b81c3b /Lib/distutils/command
parent: 12f29ffb9f02dd23e11d7f9a54f0c5891c15ff5d (diff)
download: cpython-976faf9293aa1dd291ccd95465647f09004a52af.zip
cpython-976faf9293aa1dd291ccd95465647f09004a52af.tar.gz
cpython-976faf9293aa1dd291ccd95465647f09004a52af.tar.bz2
1 files changed, 14 insertions, 14 deletions
diff --git a/Lib/distutils/command/build_ext.py b/Lib/distutils/command/build_ext.py
index e305bde..c39bd72 100644
--- a/Lib/distutils/command/build_ext.py
+++ b/Lib/distutils/command/build_ext.py
@@ -310,38 +310,38 @@ class build_ext(Command):
 
         # Setup the CCompiler object that we'll use to do all the
         # compiling and linking
-        self._compiler = new_compiler(compiler=self.compiler,
+        self.compiler = new_compiler(compiler=None,
                                      verbose=self.verbose,
                                      dry_run=self.dry_run,
                                      force=self.force)
-        customize_compiler(self._compiler)
+        customize_compiler(self.compiler)
         # If we are cross-compiling, init the compiler now (if we are not
         # cross-compiling, init would not hurt, but people may rely on
         # late initialization of compiler even if they shouldn't...)
         if os.name == 'nt' and self.plat_name != get_platform():
-            self._compiler.initialize(self.plat_name)
+            self.compiler.initialize(self.plat_name)
 
         # And make sure that any compile/link-related options (which might
         # come from the command-line or from the setup script) are set in
         # that CCompiler object -- that way, they automatically apply to
         # all compiling and linking done here.
         if self.include_dirs is not None:
-            self._compiler.set_include_dirs(self.include_dirs)
+            self.compiler.set_include_dirs(self.include_dirs)
         if self.define is not None:
             # 'define' option is a list of (name,value) tuples
             for (name, value) in self.define:
-                self._compiler.define_macro(name, value)
+                self.compiler.define_macro(name, value)
         if self.undef is not None:
             for macro in self.undef:
-                self._compiler.undefine_macro(macro)
+                self.compiler.undefine_macro(macro)
         if self.libraries is not None:
-            self._compiler.set_libraries(self.libraries)
+            self.compiler.set_libraries(self.libraries)
         if self.library_dirs is not None:
-            self._compiler.set_library_dirs(self.library_dirs)
+            self.compiler.set_library_dirs(self.library_dirs)
         if self.rpath is not None:
-            self._compiler.set_runtime_library_dirs(self.rpath)
+            self.compiler.set_runtime_library_dirs(self.rpath)
         if self.link_objects is not None:
-            self._compiler.set_link_objects(self.link_objects)
+            self.compiler.set_link_objects(self.link_objects)
 
         # Now actually compile and link everything.
         self.build_extensions()
@@ -502,7 +502,7 @@ class build_ext(Command):
         for undef in ext.undef_macros:
             macros.append((undef,))
 
-        objects = self._compiler.compile(sources,
+        objects = self.compiler.compile(sources,
                                          output_dir=self.build_temp,
                                          macros=macros,
                                          include_dirs=ext.include_dirs,
@@ -529,9 +529,9 @@ class build_ext(Command):
         extra_args = ext.extra_link_args or []
 
         # Detect target language, if not provided
-        language = ext.language or self._compiler.detect_language(sources)
+        language = ext.language or self.compiler.detect_language(sources)
 
-        self._compiler.link_shared_object(
+        self.compiler.link_shared_object(
             objects, ext_path,
             libraries=self.get_libraries(ext),
             library_dirs=ext.library_dirs,
@@ -689,7 +689,7 @@ class build_ext(Command):
         # Append '_d' to the python import library on debug builds.
         if sys.platform == "win32":
             from distutils.msvccompiler import MSVCCompiler
-            if not isinstance(self._compiler, MSVCCompiler):
+            if not isinstance(self.compiler, MSVCCompiler):
                 template = "python%d%d"
                 if self.debug:
                     template = template + '_d'
diff --git a/doc/AddErrInfo.3 b/doc/AddErrInfo.3
index d6580be..53f134a 100644
--- a/doc/AddErrInfo.3
+++ b/doc/AddErrInfo.3
@@ -119,7 +119,7 @@ retrieve the stack trace when script evaluation returns
 \fBTCL_ERROR\fR, like so:
 .PP
 .CS
-int code = Tcl_Eval(interp, script);
+int code = Tcl_EvalEx(interp, script, -1, 0);
 if (code == TCL_ERROR) {
     Tcl_Obj *options = \fBTcl_GetReturnOptions\fR(interp, code);
     Tcl_Obj *key = Tcl_NewStringObj("-errorinfo", -1);
@@ -247,6 +247,9 @@ record instead of a value. Otherwise, it is similar to
 .PP
 \fBTcl_SetErrorCodeVA\fR is the same as \fBTcl_SetErrorCode\fR except that
 instead of taking a variable number of arguments it takes an argument list.
+Interfaces using argument lists have been found to be nonportable in practice.
+This function is deprecated and will be removed in Tcl 9.0.
+
 .PP
 The procedure \fBTcl_GetErrorLine\fR is used to read the integer value
 of the \fB\-errorline\fR return option without the overhead of a full
@@ -305,6 +308,22 @@ The global variables \fBerrorInfo\fR and
 \fBerrorCode\fR are not modified by \fBTcl_ResetResult\fR
 so they continue to hold a record of information about the
 most recent error seen in an interpreter.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+The result of \fBTcl_GetReturnOptions\fR will have at least one
+reference to it from the Tcl interpreter. If not using it immediately,
+you should use \fBTcl_IncrRefCount\fR to add your own reference.
+.PP
+The \fIoptions\fR argument to \fBTcl_SetReturnOptions\fR will have a
+reference added by the Tcl interpreter; it may safely be called with a
+zero-reference value.
+.PP
+\fBTcl_AppendObjToErrorInfo\fR only reads its \fIobjPtr\fR argument;
+it does not modify its reference count at all.
+.PP
+The \fIerrorObjPtr\fR argument to \fBTcl_SetObjErrorCode\fR will have a
+reference added by the Tcl interpreter; it may safely be called with a
+zero-reference value.
 .SH "SEE ALSO"
 Tcl_DecrRefCount(3), Tcl_IncrRefCount(3), Tcl_Interp(3), Tcl_ResetResult(3),
 Tcl_SetErrno(3), errorCode(n), errorInfo(n)
diff --git a/doc/BoolObj.3 b/doc/BoolObj.3
index 7268e1f..9bbdc7e 100644
--- a/doc/BoolObj.3
+++ b/doc/BoolObj.3
@@ -88,6 +88,18 @@ will lead to a \fBTCL_OK\fR return (and the boolean value 1),
 while the same value passed to \fBTcl_GetBoolean\fR will lead to
 a \fBTCL_ERROR\fR return.
 
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_NewBooleanObj\fR always returns a zero-reference object, much
+like \fBTcl_NewObj\fR.
+.PP
+\fBTcl_SetBooleanObj\fR does not modify the reference count of its
+\fIobjPtr\fR argument, but does require that the object be unshared.
+.PP
+\fBTcl_GetBooleanFromObj\fR does not modify the reference count of its
+\fIobjPtr\fR argument; it only reads. Note however that this function
+may set the interpreter result; if that is the only place that
+is holding a reference to the object, it will be deleted.
 .SH "SEE ALSO"
 Tcl_NewObj, Tcl_IsShared, Tcl_GetBoolean
 
diff --git a/doc/ByteArrObj.3 b/doc/ByteArrObj.3
index ff0b4e1..2a7d7a3 100644
--- a/doc/ByteArrObj.3
+++ b/doc/ByteArrObj.3
@@ -37,8 +37,9 @@ byte-array type.  For \fBTcl_GetByteArrayFromObj\fR and
 \fBTcl_SetByteArrayLength\fR, this points to the value from which to get
 the byte-array value; if \fIobjPtr\fR does not already point to a byte-array
 value, it will be converted to one.
-.AP int *lengthPtr out
-If non-NULL, filled with the length of the array of bytes in the value.
+.AP size_t | int *lengthPtr out
+Filled with the length of the array of bytes in the value.
+May be (int *)NULL when not used.
 .BE
 
 .SH DESCRIPTION
@@ -84,6 +85,18 @@ newly allocated bytes at the end of the array have arbitrary values.  If
 the length of array is reduced to the new length.  The return value is a
 pointer to the value's new array of bytes.
 
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_NewByteArrayObj\fR always returns a zero-reference object, much
+like \fBTcl_NewObj\fR.
+.PP
+\fBTcl_SetByteArrayObj\fR and \fBTcl_SetByteArrayLength\fR do not modify the
+reference count of their \fIobjPtr\fR arguments, but do require that the
+object be unshared.
+.PP
+\fBTcl_GetByteArrayFromObj\fR does not modify the reference count of its
+\fIobjPtr\fR argument; it only reads.
+
 .SH "SEE ALSO"
 Tcl_GetStringFromObj, Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount
 
diff --git a/doc/Cancel.3 b/doc/Cancel.3
index 847707e..73edaf6 100644
--- a/doc/Cancel.3
+++ b/doc/Cancel.3
@@ -67,6 +67,14 @@ other procedures.  If an error is returned and this bit is set in
 result, where it can be retrieved with \fBTcl_GetObjResult\fR or
 \fBTcl_GetStringResult\fR.  If this flag bit is not set then no error
 message is left and the interpreter's result will not be modified.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_CancelEval\fR always decrements the reference count of its
+\fIresultObjPtr\fR argument (if that is non-NULL). It is expected to
+be usually called with an object with zero reference count. If the
+object is shared with some other location (including the Tcl
+evaluation stack) it should have its reference count incremented
+before calling this function.
 .SH "SEE ALSO"
 interp(n), Tcl_Eval(3),
 TIP 285
diff --git a/doc/Class.3 b/doc/Class.3
index 57203d5..5f8e061 100644
--- a/doc/Class.3
+++ b/doc/Class.3
@@ -241,6 +241,29 @@ NULL if the whole chain is to be processed (the argument itself is never
 NULL); this variable may be updated by the callback. The \fImethodNameObj\fR
 parameter gives an unshared object containing the name of the method being
 invoked, as provided by the user; this object may be updated by the callback.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+The \fIobjPtr\fR argument to \fBTcl_GetObjectFromObj\fR will not have its
+reference count manipulated, but this function may modify the interpreter
+result (to report any error) so interpreter results should not be fed into
+this without an additional reference being used.
+.PP
+The result of \fBTcl_GetObjectName\fR is a value that is owned by the object
+that is regenerated when this function is first called after the object is
+renamed.  If the value is to be retained at all, the caller should increment
+the reference count.
+.PP
+The first \fIobjc\fR values in the \fIobjv\fR argument to
+\fBTcl_NewObjectInstance\fR are the arguments to pass to the constructor. They
+must have a reference count of at least 1, and may have their reference counts
+changed during the running of the constructor. Constructors may modify the
+interpreter result, which consequently means that interpreter results should
+not be used as arguments without an additional reference being taken.
+.PP
+The \fImethodNameObj\fR argument to a Tcl_ObjectMapMethodNameProc
+implementation will be a value with a reference count of at least 1 where at
+least one reference is not held by the interpreter result. It is expected that
+method name mappers will only read their \fImethodNameObj\fR arguments.
 .SH "SEE ALSO"
 Method(3), oo::class(n), oo::copy(n), oo::define(n), oo::object(n)
 .SH KEYWORDS
diff --git a/doc/CrtAlias.3 b/doc/CrtAlias.3
index a642d08..2623dcd 100644
--- a/doc/CrtAlias.3
+++ b/doc/CrtAlias.3
@@ -19,30 +19,24 @@ int
 int
 \fBTcl_MakeSafe\fR(\fIinterp\fR)
 .sp
-.VS "TIP 581"
 Tcl_Interp *
 \fBTcl_CreateChild\fR(\fIinterp, name, isSafe\fR)
-.VE "TIP 581"
 .sp
 Tcl_Interp *
 \fBTcl_CreateSlave\fR(\fIinterp, name, isSafe\fR)
 .sp
-.VS "TIP 581"
-Tcl_Interp *
-\fBTcl_GetChild\fR(\fIinterp, name\fR)
-.VE "TIP 581"
-.sp
 Tcl_Interp *
 \fBTcl_GetSlave\fR(\fIinterp, name\fR)
 .sp
-.VS "TIP 581"
 Tcl_Interp *
-\fBTcl_GetParent\fR(\fIinterp\fR)
-.VE "TIP 581"
+\fBTcl_GetChild\fR(\fIinterp, name\fR)
 .sp
 Tcl_Interp *
 \fBTcl_GetMaster\fR(\fIinterp\fR)
 .sp
+Tcl_Interp *
+\fBTcl_GetParent\fR(\fIinterp\fR)
+.sp
 int
 \fBTcl_GetInterpPath\fR(\fIinterp, childInterp\fR)
 .sp
@@ -136,8 +130,8 @@ interpreter. The return value for those procedures that return an \fBint\fR
 is either \fBTCL_OK\fR or \fBTCL_ERROR\fR. If \fBTCL_ERROR\fR is returned
 then the interpreter's result contains an error message.
 .PP
-\fBTcl_CreateSlave\fR creates a new interpreter as a child of \fIinterp\fR.
-It also creates a child command named \fIchildName\fR in \fIinterp\fR which
+\fBTcl_CreateChild\fR creates a new interpreter as a child of \fIinterp\fR.
+It also creates a child command named \fIname\fR in \fIinterp\fR which
 allows \fIinterp\fR to manipulate the new child.
 If \fIisSafe\fR is zero, the command creates a trusted child in which Tcl
 code has access to all the Tcl commands.
@@ -148,9 +142,7 @@ child in which Tcl code has access only to set of Tcl commands defined as
 see the manual entry for the Tcl \fBinterp\fR command for details.
 If the creation of the new child interpreter failed, \fBNULL\fR is returned.
 .PP
-.VS "TIP 581"
-\fBTcl_CreateChild\fR is a synonym for \fBTcl_CreateSlave\fR.
-.VE "TIP 581"
+\fBTcl_CreateSlave\fR is a synonym for \fBTcl_CreateChild\fR.
 .PP
 \fBTcl_IsSafe\fR returns \fB1\fR if \fIinterp\fR is
 .QW safe
@@ -166,24 +158,20 @@ from \fIinterp\fR.  However, it cannot know what parts of an extension
 or application are safe and does not make any attempt to remove those
 parts, so safety is not guaranteed after calling \fBTcl_MakeSafe\fR.
 Callers will want to take care with their use of \fBTcl_MakeSafe\fR
-to avoid false claims of safety.  For many situations, \fBTcl_CreateSlave\fR
+to avoid false claims of safety.  For many situations, \fBTcl_CreateChild\fR
 may be a better choice, since it creates interpreters in a known-safe state.
 .PP
-\fBTcl_GetSlave\fR returns a pointer to a child interpreter of
-\fIinterp\fR. The child interpreter is identified by \fIchildName\fR.
+\fBTcl_GetChild\fR returns a pointer to a child interpreter of
+\fIinterp\fR. The child interpreter is identified by \fIname\fR.
 If no such child interpreter exists, \fBNULL\fR is returned.
 .PP
-.VS "TIP 581"
-\fBTcl_GetChild\fR is a synonym for \fBTcl_GetSlave\fR.
-.VE "TIP 581"
+\fBTcl_GetSlave\fR is a synonym for \fBTcl_GetChild\fR.
 .PP
-\fBTcl_GetMaster\fR returns a pointer to the master interpreter of
-\fIinterp\fR. If \fIinterp\fR has no master (it is a
+\fBTcl_GetParent\fR returns a pointer to the parent interpreter of
+\fIinterp\fR. If \fIinterp\fR has no parent (it is a
 top-level interpreter) then \fBNULL\fR is returned.
 .PP
-.VS "TIP 581"
-\fBTcl_GetParent\fR is a synonym for \fBTcl_GetMaster\fR.
-.VE "TIP 581"
+\fBTcl_GetMaster\fR is a synonym for \fBTcl_GetParent\fR.
 .PP
 \fBTcl_GetInterpPath\fR stores in the result of \fIinterp\fR
 the relative path between \fIinterp\fR and \fIchildInterp\fR;
@@ -201,7 +189,7 @@ This operation returns \fBTCL_OK\fR if it succeeds, or \fBTCL_ERROR\fR if
 it fails; in that case, an error message is left in the value result
 of \fIchildInterp\fR.
 Note that there are no restrictions on the ancestry relationship (as
-created by \fBTcl_CreateSlave\fR) between \fIchildInterp\fR and
+created by \fBTcl_CreateChild\fR) between \fIchildInterp\fR and
 \fItargetInterp\fR. Any two interpreters can be used, without any
 restrictions on how they are related.
 .PP
@@ -255,8 +243,16 @@ any script evaluation mechanism will fail.
 .PP
 For a description of the Tcl interface to multiple interpreters, see
 \fIinterp(n)\fR.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_CreateAliasObj\fR increments the reference counts of the values
+in its \fIobjv\fR argument. (That reference lasts the same length of
+time as the owning alias.)
+.PP
+\fBTcl_GetAliasObj\fR returns (via its \fIobjvPtr\fR argument) a
+pointer to values that it holds a reference to.
 .SH "SEE ALSO"
-interp
+interp(n)
 
 .SH KEYWORDS
 alias, command, exposed commands, hidden commands, interpreter, invoke,
diff --git a/doc/CrtChannel.3 b/doc/CrtChannel.3
index 0092cfb..02772e8 100644
--- a/doc/CrtChannel.3
+++ b/doc/CrtChannel.3
@@ -600,9 +600,9 @@ in preference to the \fIseekProc\fR, but both must be defined if the
 following prototype:
 .PP
 .CS
-typedef Tcl_WideInt \fBTcl_DriverWideSeekProc\fR(
+typedef long long \fBTcl_DriverWideSeekProc\fR(
         ClientData \fIinstanceData\fR,
-        Tcl_WideInt \fIoffset\fR,
+        long long \fIoffset\fR,
         int \fIseekMode\fR,
         int *\fIerrorCodePtr\fR);
 .CE
@@ -824,7 +824,7 @@ length. It can be NULL.
 .CS
 typedef int \fBTcl_DriverTruncateProc\fR(
         ClientData \fIinstanceData\fR,
-        Tcl_WideInt \fIlength\fR);
+        long long \fIlength\fR);
 .CE
 .PP
 \fIInstanceData\fR is the same as the value passed to
diff --git a/doc/CrtInterp.3 b/doc/CrtInterp.3
index 1d49158..aacb868 100644
--- a/doc/CrtInterp.3
+++ b/doc/CrtInterp.3
@@ -22,10 +22,8 @@ Tcl_Interp *
 int
 \fBTcl_InterpDeleted\fR(\fIinterp\fR)
 .sp
-.VS 8.6
 int
 \fBTcl_InterpActive\fR(\fIinterp\fR)
-.VE 8.6
 .SH ARGUMENTS
 .AS Tcl_Interp *interp
 .AP Tcl_Interp *interp in
@@ -70,14 +68,12 @@ deleted and when the whole interpreter is being deleted. In the former case
 the callback may recreate the data being deleted, but this would lead to an
 infinite loop if the interpreter were being deleted.
 .PP
-.VS 8.6
 \fBTcl_InterpActive\fR is useful for determining whether there is any
 execution of scripts ongoing in an interpreter, which is a useful piece of
 information when Tcl is embedded in a garbage-collected environment and it
 becomes necessary to determine whether the interpreter is a candidate for
 deletion. The function returns a true value if the interpreter has at least
 one active execution running inside it, and a false value otherwise.
-.VE 8.6
 .SH "INTERPRETERS AND MEMORY MANAGEMENT"
 .PP
 \fBTcl_DeleteInterp\fR can be called at any time on an interpreter that may
@@ -138,12 +134,10 @@ All uses of interpreters in Tcl and Tk have already been protected.
 Extension writers should ensure that their code also properly protects any
 additional interpreters used, as described above.
 .PP
-.VS 8.6
 Note that the protection mechanisms do not work well with conventional garbage
 collection systems. When in such a managed environment, \fBTcl_InterpActive\fR
 should be used to determine when an interpreter is a candidate for deletion
 due to inactivity.
-.VE 8.6
 .SH "SEE ALSO"
 Tcl_Preserve(3), Tcl_Release(3)
 .SH KEYWORDS
diff --git a/doc/CrtMathFnc.3 b/doc/CrtMathFnc.3
index acceb5b..bb96fc9 100644
--- a/doc/CrtMathFnc.3
+++ b/doc/CrtMathFnc.3
@@ -156,6 +156,10 @@ pointed to by \fIargTypesPointer\fR.
 \fBTcl_ListMathFuncs\fR returns a Tcl value containing a list of all
 the math functions defined in the interpreter whose name matches
 \fIpattern\fR.  The returned value has a reference count of zero.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_ListMathFuncs\fR always returns a zero-reference object, much
+like \fBTcl_NewObj\fR.
 .SH "SEE ALSO"
 expr(n), info(n), Tcl_CreateObjCommand(3), Tcl_Free(3), Tcl_NewListObj(3)
 .SH KEYWORDS
diff --git a/doc/CrtObjCmd.3 b/doc/CrtObjCmd.3
index 6025c68..f15e277 100644
--- a/doc/CrtObjCmd.3
+++ b/doc/CrtObjCmd.3
@@ -8,7 +8,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, Tcl_GetCommandInfo, Tcl_GetCommandInfoFromToken, Tcl_SetCommandInfo, Tcl_SetCommandInfoFromToken, Tcl_GetCommandName, Tcl_GetCommandFullName, Tcl_GetCommandFromObj \- implement new commands in C
+Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, Tcl_GetCommandInfo, Tcl_GetCommandInfoFromToken, Tcl_SetCommandInfo, Tcl_SetCommandInfoFromToken, Tcl_GetCommandName, Tcl_GetCommandFullName, Tcl_GetCommandFromObj, Tcl_RegisterCommandTypeName, Tcl_GetCommandTypeName \- implement new commands in C
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -42,6 +42,14 @@ void
 .sp
 Tcl_Command
 \fBTcl_GetCommandFromObj\fR(\fIinterp, objPtr\fR)
+.sp
+.VS "info cmdtype feature"
+void
+\fBTcl_RegisterCommandTypeName\fR(\fIproc, typeName\fR)
+.sp
+const char *
+\fBTcl_GetCommandTypeName\fR(\fItoken\fR)
+.VE "info cmdtype feature"
 .SH ARGUMENTS
 .AS Tcl_CmdDeleteProc *deleteProc in/out
 .AP Tcl_Interp *interp in
@@ -65,6 +73,9 @@ Pointer to structure containing various information about a
 Tcl command.
 .AP Tcl_Obj *objPtr in
 Value containing the name of a Tcl command.
+.AP "const char" *typeName in
+Indicates the name of the type of command implementation associated
+with a particular \fIproc\fR, or NULL to break the association.
 .BE
 .SH DESCRIPTION
 .PP
@@ -296,6 +307,37 @@ is appended to the value specified by \fIobjPtr\fR.
 specified by the name in a \fBTcl_Obj\fR.
 The command name is resolved relative to the current namespace.
 Returns NULL if the command is not found.
+.PP
+.VS "info cmdtype feature"
+\fBTcl_RegisterCommandTypeName\fR is used to associate a name (the
+\fItypeName\fR argument) with a particular implementation function so that it
+can then be looked up with \fBTcl_GetCommandTypeName\fR, which in turn is
+called with a command token that information is wanted for and which returns
+the name of the type that was registered for the implementation function used
+for that command. (The lookup functionality is surfaced virtually directly in Tcl via
+\fBinfo cmdtype\fR.) If there is no function registered for a particular
+function, the result will be the string literal
+.QW \fBnative\fR .
+The registration of a name can be undone by registering a mapping to NULL
+instead. The result from \fBTcl_GetCommandTypeName\fR will be exactly that
+string which was registered, and not a copy; use of a compile-time constant
+string is \fIstrongly recommended\fR.
+.VE "info cmdtype feature"
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+When the \fIproc\fR passed to \fBTcl_CreateObjCommand\fR is called,
+the values in its \fIobjv\fR argument will have a reference count of
+at least 1, with that guaranteed reference being from the Tcl
+evaluation stack. You should not call \fBTcl_DecrRefCount\fR on any of
+those values unless you call \fBTcl_IncrRefCount\fR on them first.
+Also, when the \fIproc\fR is called, the interpreter result is
+guaranteed to be an empty string value with a reference count of 1.
+.PP
+\fBTcl_GetCommandFullName\fR does not modify the reference count of its
+\fIobjPtr\fR argument, but does require that the object be unshared.
+.PP
+\fBTcl_GetCommandFromObj\fR does not modify the reference count of its
+\fIobjPtr\fR argument; it only reads.
 .SH "SEE ALSO"
 Tcl_CreateCommand(3), Tcl_ResetResult(3), Tcl_SetObjResult(3)
 .SH KEYWORDS
diff --git a/doc/CrtTrace.3 b/doc/CrtTrace.3
index b1e6483..bf8587d 100644
--- a/doc/CrtTrace.3
+++ b/doc/CrtTrace.3
@@ -187,5 +187,14 @@ There is no way to be notified when the trace created by
 \fBTcl_CreateTrace\fR is deleted.  There is no way for the \fIproc\fR
 associated with a call to \fBTcl_CreateTrace\fR to abort execution of
 \fIcommand\fR.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+When the \fIproc\fR passed to \fBTcl_CreateObjTrace\fR is called,
+the values in its \fIobjv\fR argument will have a reference count of
+at least 1, with that guaranteed reference being from the Tcl
+evaluation stack. You should not call \fBTcl_DecrRefCount\fR on any of
+those values unless you call \fBTcl_IncrRefCount\fR on them first.
+.SH "SEE ALSO"
+trace(n)
 .SH KEYWORDS
 command, create, delete, interpreter, trace
diff --git a/doc/DictObj.3 b/doc/DictObj.3
index 2c111c4..0b4c1ca 100644
--- a/doc/DictObj.3
+++ b/doc/DictObj.3
@@ -190,6 +190,73 @@ path as this is easy to construct from repeated use of
 dictionaries are created for non-terminal keys where they do not
 already exist. With \fBTcl_DictObjRemoveKeyList\fR, all non-terminal
 keys must exist and have dictionaries as their values.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_NewDictObj\fR always returns a zero-reference object, much like
+\fBTcl_NewObj\fR.
+.PP
+\fBTcl_DictObjPut\fR does not modify the reference count of its \fIdictPtr\fR
+argument, but does require that the object be unshared.  If
+\fBTcl_DictObjPut\fR returns \fBTCL_ERROR\fR it does not manipulate any
+reference counts; but if it returns \fBTCL_OK\fR then it definitely increments
+the reference count of \fIvaluePtr\fR and may increment the reference count of
+\fIkeyPtr\fR; the latter case happens exactly when the key did not previously
+exist in the dictionary.  Note however that this function may set the
+interpreter result; if that is the only place that is holding a reference to
+an object, it will be deleted.
+.PP
+\fBTcl_DictObjGet\fR only reads from its \fIdictPtr\fR and \fIkeyPtr\fR
+arguments, and does not manipulate their reference counts at all.  If the
+\fIvaluePtrPtr\fR argument is not set to NULL (and the function doesn't return
+\fBTCL_ERROR\fR), it will be set to a value with a reference count of at least
+1, with a reference owned by the dictionary.  Note however that this function
+may set the interpreter result; if that is the only place that is holding a
+reference to an object, it will be deleted.
+.PP
+\fBTcl_DictObjRemove\fR does not modify the reference count of its
+\fIdictPtr\fR argument, but does require that the object be unshared. It does
+not manipulate the reference count of its \fIkeyPtr\fR argument at all.  Note
+however that this function may set the interpreter result; if that is the only
+place that is holding a reference to an object, it will be deleted.
+.PP
+\fBTcl_DictObjSize\fR does not modify the reference count of its \fIdictPtr\fR
+argument; it only reads.  Note however that this function may set the
+interpreter result; if that is the only place that is holding a reference to
+the dictionary object, it will be deleted.
+.PP
+\fBTcl_DictObjFirst\fR does not modify the reference count of its
+\fIdictPtr\fR argument; it only reads. The variables given by the
+\fIkeyPtrPtr\fR and \fIvaluePtrPtr\fR arguments (if not NULL) will be updated
+to contain references to the relevant values in the dictionary; their
+reference counts will be at least 1 (due to the dictionary holding a reference
+to them). It may also manipulate internal references; these are not exposed to
+user code, but require a matching \fBTcl_DictObjDone\fR call.  Note however
+that this function may set the interpreter result; if that is the only place
+that is holding a reference to the dictionary object, it will be deleted.
+.PP
+Similarly for \fBTcl_DictObjNext\fR; the variables given by the
+\fIkeyPtrPtr\fR and \fIvaluePtrPtr\fR arguments (if not NULL) will be updated
+to contain references to the relevant values in the dictionary; their
+reference counts will be at least 1 (due to the dictionary holding a reference
+to them).
+.PP
+\fBTcl_DictObjDone\fR does not manipulate (user-visible) reference counts.
+.PP
+\fBTcl_DictObjPutKeyList\fR is similar to \fBTcl_DictObjPut\fR; it does not
+modify the reference count of its \fIdictPtr\fR argument, but does require
+that the object be unshared. It may increment the reference count of any value
+passed in the \fIkeyv\fR argument, and will increment the reference count of
+the \fIvaluePtr\fR argument on success. It is recommended that values passed
+via \fIkeyv\fR and \fIvaluePtr\fR do not have zero reference counts.  Note
+however that this function may set the interpreter result; if that is the only
+place that is holding a reference to an object, it will be deleted.
+.PP
+\fBTcl_DictObjRemoveKeyList\fR is similar to \fBTcl_DictObjRemove\fR; it does
+not modify the reference count of its \fIdictPtr\fR argument, but does require
+that the object be unshared, and does not modify the reference counts of any
+of the values passed in the \fIkeyv\fR argument.  Note however that this
+function may set the interpreter result; if that is the only place that is
+holding a reference to an object, it will be deleted.
 .SH EXAMPLE
 Using the dictionary iteration interface to search determine if there
 is a key that maps to itself:
diff --git a/doc/DoubleObj.3 b/doc/DoubleObj.3
index 85e4de5..c70f5d1 100644
--- a/doc/DoubleObj.3
+++ b/doc/DoubleObj.3
@@ -58,6 +58,18 @@ and if \fIinterp\fR is non-NULL, an error message is left in \fIinterp\fR.
 The \fBTcl_ObjType\fR of \fIobjPtr\fR may be changed to make subsequent
 calls to \fBTcl_GetDoubleFromObj\fR more efficient.
 '\" TODO: add discussion of treatment of NaN value
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_NewDoubleObj\fR always returns a zero-reference object, much
+like \fBTcl_NewObj\fR.
+.PP
+\fBTcl_SetDoubleObj\fR does not modify the reference count of its
+\fIobjPtr\fR argument, but does require that the object be unshared.
+.PP
+\fBTcl_GetDoubleFromObj\fR does not modify the reference count of its
+\fIobjPtr\fR argument; it only reads. Note however that this function
+may set the interpreter result; if that is the only place that
+is holding a reference to the object, it will be deleted.
 .SH "SEE ALSO"
 Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
 .SH KEYWORDS
diff --git a/doc/Encoding.3 b/doc/Encoding.3
index 79fca0f..c68070c 100644
--- a/doc/Encoding.3
+++ b/doc/Encoding.3
@@ -8,7 +8,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_GetEncoding, Tcl_FreeEncoding, Tcl_GetEncodingFromObj, Tcl_ExternalToUtfDString, Tcl_ExternalToUtf, Tcl_UtfToExternalDString, Tcl_UtfToExternal, Tcl_WinTCharToUtf, Tcl_WinUtfToTChar, Tcl_GetEncodingName, Tcl_SetSystemEncoding, Tcl_GetEncodingNameFromEnvironment, Tcl_GetEncodingNames, Tcl_CreateEncoding, Tcl_GetEncodingSearchPath, Tcl_SetEncodingSearchPath, Tcl_GetDefaultEncodingDir, Tcl_SetDefaultEncodingDir \- procedures for creating and using encodings
+Tcl_GetEncoding, Tcl_FreeEncoding, Tcl_GetEncodingFromObj, Tcl_ExternalToUtfDString, Tcl_ExternalToUtf, Tcl_UtfToExternalDString, Tcl_UtfToExternal, Tcl_GetEncodingName, Tcl_SetSystemEncoding, Tcl_GetEncodingNameFromEnvironment, Tcl_GetEncodingNames, Tcl_CreateEncoding, Tcl_GetEncodingSearchPath, Tcl_SetEncodingSearchPath, Tcl_GetDefaultEncodingDir, Tcl_SetDefaultEncodingDir \- procedures for creating and using encodings
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -255,11 +255,17 @@ is filled with the corresponding number of bytes that were stored in
 \fIdst\fR.  The return values are the same as the return values for
 \fBTcl_ExternalToUtf\fR.
 .PP
-\fBTcl_WinUtfToTChar\fR and \fBTcl_WinTCharToUtf\fR are
-Windows-only convenience
-functions for converting between UTF-8 and Windows strings
-based on the TCHAR type which is by convention
-a Unicode character on Windows NT.
+\fBTcl_WinUtfToTChar\fR and \fBTcl_WinTCharToUtf\fR are Windows-only
+convenience functions for converting between UTF-8 and Windows strings
+based on the TCHAR type which is by convention a Unicode character on
+Windows NT. Those functions are deprecated. You can use
+\fBTcl_UtfToWCharDString\fR resp. \fBTcl_WCharToUtfDString\fR as replacement.
+If you want compatibility with earlier Tcl releases than 8.7, use
+\fBTcl_UtfToUniCharDString\fR resp. \fBTcl_UniCharToUtfDString\fR as
+replacement, and make sure you compile your extension with -DTCL_UTF_MAX=3.
+Beware: Those replacement functions don't initialize their Tcl_DString (you'll
+have to do that yourself), and \fBTcl_UniCharToUtfDString\fR from Tcl 8.6
+doesn't accept -1 as length parameter.
 .PP
 \fBTcl_GetEncodingName\fR is roughly the inverse of \fBTcl_GetEncoding\fR.
 Given an \fIencoding\fR, the return value is the \fIname\fR argument that
@@ -550,5 +556,16 @@ been loaded, it attempts to load an encoding file called \fIname\fB.enc\fR
 from the \fBencoding\fR subdirectory of each directory that Tcl searches
 for its script library.  If the encoding file exists, but is
 malformed, an error message will be left in \fIinterp\fR.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_GetEncodingFromObj\fR does not modify the reference count of its
+\fIobjPtr\fR argument; it only reads. Note however that this function may set
+the interpreter result; if that is the only place that is holding a reference
+to the object, it will be deleted.
+.PP
+\fBTcl_GetEncodingSearchPath\fR returns an object with a reference count of at
+least 1.
+.SH "SEE ALSO"
+encoding(n)
 .SH KEYWORDS
 utf, encoding, convert
diff --git a/doc/Ensemble.3 b/doc/Ensemble.3
index 30c1d3b..b768fd6 100644
--- a/doc/Ensemble.3
+++ b/doc/Ensemble.3
@@ -36,13 +36,11 @@ int
 int
 \fBTcl_SetEnsembleMappingDict\fR(\fIinterp, token, dictObj\fR)
 .sp
-.VS 8.6
 int
 \fBTcl_GetEnsembleParameterList\fR(\fIinterp, token, listObjPtr\fR)
 .sp
 int
 \fBTcl_SetEnsembleParameterList\fR(\fIinterp, token, listObj\fR)
-.VE 8.6
 .sp
 int
 \fBTcl_GetEnsembleSubcommandList\fR(\fIinterp, token, listObjPtr\fR)
@@ -163,7 +161,6 @@ All command names in prefixes set via \fBTcl_SetEnsembleMappingDict\fR
 must be fully qualified.
 .TP
 \fBformal pre-subcommand parameter list\fR (read-write)
-.VS 8.6
 A list of formal parameter names (the names only being used when generating
 error messages) that come at invocation of the ensemble between the name of
 the ensemble and the subcommand argument. NULL (the default) is equivalent to
@@ -174,7 +171,6 @@ respectively. The result of both of those functions is a Tcl result code
 ensemble) and the
 dictionary obtained from \fBTcl_GetEnsembleParameterList\fR should always be
 treated as immutable even if it is unshared.
-.VE 8.6
 .TP
 \fBsubcommand list\fR (read-write)
 .
@@ -213,6 +209,27 @@ namespace whose list of exported commands is used if both the mapping
 dictionary and the subcommand list properties are NULL. May be read
 using \fBTcl_GetEnsembleNamespace\fR which returns a Tcl result code
 (\fBTCL_OK\fR, or \fBTCL_ERROR\fR if the token does not refer to an ensemble).
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_FindEnsemble\fR does not modify the reference count of its
+\fIcmdNameObj\fR argument; it only reads. Note however that this function may
+set the interpreter result; if that is the only place that is holding a
+reference to the object, it will be deleted.
+.PP
+The ensemble property getters (\fBTcl_GetEnsembleMappingDict\fR,
+\fBTcl_GetEnsembleParameterList\fR, \fBTcl_GetEnsembleSubcommandList\fR, and
+\fBTcl_GetEnsembleUnknownHandler\fR) do not manipulate the reference count of
+the values they provide out; if those are non-NULL, they will have a reference
+count of at least 1.  Note that these functions may set the interpreter
+result.
+.PP
+The ensemble property setters (\fBTcl_SetEnsembleMappingDict\fR,
+\fBTcl_SetEnsembleParameterList\fR, \fBTcl_SetEnsembleSubcommandList\fR, and
+\fBTcl_SetEnsembleUnknownHandler\fR) will increment the reference count of the
+new value of the property they are given if they succeed (and decrement the
+reference count of the old value of the property, if relevant). If the
+property setters return \fBTCL_ERROR\fR, the reference count of the Tcl_Obj
+argument is left unchanged.
 .SH "SEE ALSO"
 namespace(n), Tcl_DeleteCommandFromToken(3)
 .SH KEYWORDS
diff --git a/doc/Eval.3 b/doc/Eval.3
index be1598a..5929a83 100644
--- a/doc/Eval.3
+++ b/doc/Eval.3
@@ -150,13 +150,14 @@ equivalent to using the \fBTCL_EVAL_GLOBAL\fR flag (see below).
 of any length, concatenates them into a single string,
 then calls \fBTcl_Eval\fR to execute that string as a Tcl command.
 It returns the result of the command and also modifies
-\fIinterp->result\fR in the same way as \fBTcl_Eval\fR.
+the interpreter result in the same way as \fBTcl_Eval\fR.
 The last argument to \fBTcl_VarEval\fR must be NULL to indicate the end
 of arguments.  \fBTcl_VarEval\fR is now deprecated.
 .PP
 \fBTcl_VarEvalVA\fR is the same as \fBTcl_VarEval\fR except that
 instead of taking a variable number of arguments it takes an argument
-list. Like \fBTcl_VarEval\fR, \fBTcl_VarEvalVA\fR is deprecated.
+list. Interfaces using argument lists have been found to be nonportable
+in practice. This function is deprecated and will be removed in Tcl 9.0.
 
 .SH "FLAG BITS"
 .PP
@@ -206,6 +207,20 @@ the \fBreturn\fR, \fBbreak\fR, or \fBcontinue\fR command was
 invoked in an inappropriate place.
 This means that top-level applications should never see a return code
 from \fBTcl_EvalObjEx\fR other than \fBTCL_OK\fR or \fBTCL_ERROR\fR.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_EvalObjEx\fR and \fBTcl_GlobalEvalObj\fR both increment and
+decrement the reference count of their \fIobjPtr\fR argument; you must
+not pass them any value with a reference count of zero. They also
+manipulate the interpreter result; you must not count on the
+interpreter result to hold the reference count of any value over
+these calls.
+.PP
+\fBTcl_EvalObjv\fR may increment and decrement the reference count of
+any value passed via its \fIobjv\fR argument; you must not pass any
+value with a reference count of zero. This function also manipulates
+the interpreter result; you must not count on the interpreter result
+to hold the reference count of any value over this call.
 
 .SH KEYWORDS
 execute, file, global, result, script, value
diff --git a/doc/Exit.3 b/doc/Exit.3
index 9a04db3..a52b2e1 100644
--- a/doc/Exit.3
+++ b/doc/Exit.3
@@ -134,6 +134,9 @@ finalization of Tcl's subsystems via \fBTcl_Finalize\fR at an
 appropriate time.  The argument passed to \fIproc\fR when it is
 invoked will be the exit status code (as passed to \fBTcl_Exit\fR)
 cast to a ClientData value.
+.PP
+\fBTcl_SetExitProc\fR can not be used in stub-enabled extensions. Its symbol
+entry in the stub table is deprecated and it will be removed in Tcl 9.0.
 .SH "SEE ALSO"
 exit(n)
 .SH KEYWORDS
diff --git a/doc/ExprLongObj.3 b/doc/ExprLongObj.3
index 837e0a8..59413e1 100644
--- a/doc/ExprLongObj.3
+++ b/doc/ExprLongObj.3
@@ -98,6 +98,15 @@ containing the expression's value at \fI*resultPtrPtr\fR.
 In this case, the caller is responsible for calling
 \fBTcl_DecrRefCount\fR to decrement the value's reference count
 when it is finished with the value.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_ExprLongObj\fR, \fBTcl_ExprDoubleObj\fR,
+\fBTcl_ExprBooleanObj\fR, and \fBTcl_ExprObj\fR all increment and
+decrement the reference count of their \fIobjPtr\fR arguments; you
+must not pass them any value with a reference count of zero. They also
+manipulate the interpreter result; you must not count on the
+interpreter result to hold the reference count of any value over these
+calls.
 
 .SH "SEE ALSO"
 Tcl_ExprLong, Tcl_ExprDouble, Tcl_ExprBoolean, Tcl_ExprString, Tcl_GetObjResult
diff --git a/doc/FileSystem.3 b/doc/FileSystem.3
index 4a57743..4951ec5 100644
--- a/doc/FileSystem.3
+++ b/doc/FileSystem.3
@@ -45,7 +45,7 @@ int
 \fBTcl_FSDeleteFile\fR(\fIpathPtr\fR)
 .sp
 int
-\fBTcl_FSRemoveDirectory\fR(\fIpathPtr, int recursive, errorPtr\fR)
+\fBTcl_FSRemoveDirectory\fR(\fIpathPtr, recursive, errorPtr\fR)
 .sp
 int
 \fBTcl_FSRenameFile\fR(\fIsrcPathPtr, destPathPtr\fR)
@@ -63,10 +63,8 @@ int
 \fBTcl_FSLoadFile\fR(\fIinterp, pathPtr, sym1, sym2, proc1Ptr, proc2Ptr,
                loadHandlePtr, unloadProcPtr\fR)
 .sp
-.VS 8.6
 int
 \fBTcl_FSUnloadFile\fR(\fIinterp, loadHandle\fR)
-.VE 8.6
 .sp
 int
 \fBTcl_FSMatchInDirectory\fR(\fIinterp, resultPtr, pathPtr, pattern, types\fR)
@@ -81,10 +79,10 @@ int
 \fBTcl_FSUtime\fR(\fIpathPtr, tval\fR)
 .sp
 int
-\fBTcl_FSFileAttrsGet\fR(\fIinterp, int index, pathPtr, objPtrRef\fR)
+\fBTcl_FSFileAttrsGet\fR(\fIinterp, index, pathPtr, objPtrRef\fR)
 .sp
 int
-\fBTcl_FSFileAttrsSet\fR(\fIinterp, int index, pathPtr, Tcl_Obj *objPtr\fR)
+\fBTcl_FSFileAttrsSet\fR(\fIinterp, index, pathPtr, objPtr\fR)
 .sp
 const char *const *
 \fBTcl_FSFileAttrStrings\fR(\fIpathPtr, objPtrRef\fR)
@@ -146,17 +144,16 @@ Tcl_Obj *
 Tcl_StatBuf *
 \fBTcl_AllocStatBuf\fR()
 .sp
-.VS 8.6
-Tcl_WideInt
+long long
 \fBTcl_GetAccessTimeFromStat\fR(\fIstatPtr\fR)
 .sp
 unsigned
 \fBTcl_GetBlockSizeFromStat\fR(\fIstatPtr\fR)
 .sp
-Tcl_WideUInt
+unsigned long long
 \fBTcl_GetBlocksFromStat\fR(\fIstatPtr\fR)
 .sp
-Tcl_WideInt
+long long
 \fBTcl_GetChangeTimeFromStat\fR(\fIstatPtr\fR)
 .sp
 int
@@ -177,15 +174,14 @@ int
 unsigned
 \fBTcl_GetModeFromStat\fR(\fIstatPtr\fR)
 .sp
-Tcl_WideInt
+long long
 \fBTcl_GetModificationTimeFromStat\fR(\fIstatPtr\fR)
 .sp
-Tcl_WideUInt
+unsigned long long
 \fBTcl_GetSizeFromStat\fR(\fIstatPtr\fR)
 .sp
 int
 \fBTcl_GetUserIdFromStat\fR(\fIstatPtr\fR)
-.VE 8.6
 .SH ARGUMENTS
 .AS Tcl_GlobTypeData **srcPathPtr out
 .AP "const Tcl_Filesystem" *fsPtr in
@@ -201,6 +197,8 @@ rename operation.
 .AP Tcl_Obj *destPathPtr in
 As for \fIpathPtr\fR, but used for the destination filename for a copy or
 rename operation.
+.AP int recursive in
+Whether to remove subdirectories and their contents as well.
 .AP "const char" *encodingName in
 The encoding of the data stored in the
 file identified by \fIpathPtr\fR and to be evaluated.
@@ -228,6 +226,10 @@ be joined together. If negative, then all elements are joined.
 .AP Tcl_Obj **errorPtr out
 In the case of an error, filled with a value containing the name of
 the file which caused an error in the various copy/rename operations.
+.AP int index in
+The index of the attribute in question.
+.AP Tcl_Obj *objPtr in
+The value to set in the operation.
 .AP Tcl_Obj **objPtrRef out
 Filled with a value containing the result of the operation.
 .AP Tcl_Obj *resultPtr out
@@ -245,9 +247,9 @@ The structure that contains the result of a stat or lstat operation.
 Name of a procedure to look up in the file's symbol table
 .AP "const char" *sym2 in
 Name of a procedure to look up in the file's symbol table
-.AP Tcl_PackageInitProc **proc1Ptr out
+.AP Tcl_LibraryInitProc **proc1Ptr out
 Filled with the init function for this code.
-.AP Tcl_PackageInitProc **proc2Ptr out
+.AP Tcl_LibraryInitProc **proc2Ptr out
 Filled with the safe-init function for this code.
 .AP ClientData *clientDataPtr out
 Filled with the clientData value to pass to this code's unload
@@ -418,7 +420,7 @@ caller (with a reference count of 0).
 the encoding identified by \fIencodingName\fR and evaluates
 its contents as a Tcl script. It returns the same information as
 \fBTcl_EvalObjEx\fR.
-If \fIencodingName\fR is NULL, the system encoding is used for
+If \fIencodingName\fR is NULL, the utf-8 encoding is used for
 reading the file contents.
 If the file could not be read then a Tcl error is returned to describe
 why the file could not be read.
@@ -434,7 +436,7 @@ or
 which will be safely substituted by the Tcl interpreter into
 .QW ^Z .
 \fBTcl_FSEvalFile\fR is a simpler version of
-\fBTcl_FSEvalFileEx\fR that always uses the system encoding
+\fBTcl_FSEvalFileEx\fR that always uses the utf-8 encoding
 when reading the file.
 .PP
 \fBTcl_FSLoadFile\fR dynamically loads a binary code file into memory and
@@ -444,20 +446,16 @@ belongs will be called. If that filesystem does not implement this
 function (most virtual filesystems will not, because of OS limitations
 in dynamically loading binary code), Tcl will attempt to copy the file
 to a temporary directory and load that temporary file.
-.VS 8.6
 \fBTcl_FSUnloadFile\fR reverses the operation, asking for the library
 indicated by the \fIloadHandle\fR to be removed from the process. Note that,
 unlike with the \fBunload\fR command, this does not give the library any
 opportunity to clean up.
-.VE 8.6
 .PP
 Both the above functions return a standard Tcl completion code. If an error
 occurs, an error message is left in the \fIinterp\fR's result.
 .PP
-.VS 8.6
 The token provided via the variable indicated by \fIloadHandlePtr\fR may be
 used with \fBTcl_FindSymbol\fR.
-.VE 8.6
 .PP
 \fBTcl_FSMatchInDirectory\fR is used by the globbing code to search a
 directory for all files which match a given pattern. The appropriate
@@ -795,7 +793,6 @@ may be deallocated by being passed to \fBckfree\fR). This allows extensions to
 invoke \fBTcl_FSStat\fR and \fBTcl_FSLstat\fR without being dependent on the
 size of the buffer. That in turn depends on the flags used to build Tcl.
 .PP
-.VS 8.6
 The portable fields of a \fITcl_StatBuf\fR may be read using the following
 functions, each of which returns the value of the corresponding field listed
 in the table below. Note that on some platforms there may be other fields in
@@ -819,7 +816,6 @@ for a full description of these fields.
  \fBTcl_GetBlocksFromStat\fR	 st_blocks
  \fBTcl_GetBlockSizeFromStat\fR	 st_blksize
 .DE
-.VE 8.6
 .SH "THE VIRTUAL FILESYSTEM API"
 .PP
 A filesystem provides a \fBTcl_Filesystem\fR structure that contains
@@ -1638,6 +1634,158 @@ typedef int \fBTcl_FSChdirProc\fR(
 The \fBTcl_FSChdirProc\fR changes the applications current working
 directory to the value specified in \fIpathPtr\fR. The function returns
 -1 on error or 0 on success.
+.SH "REFERENCE COUNT MANAGEMENT"
+.SS "PUBLIC API CALLS"
+.PP
+For all of these functions, \fIpathPtr\fR (including the \fIsrcPathPtr\fR and
+\fIdestPathPtr\fR arguments to \fBTcl_FSCopyFile\fR,
+\fBTcl_FSCopyDirectory\fR, and \fBTcl_FSRenameFile\fR, the \fIfirstPtr\fR and
+\fIsecondPtr\fR arguments to \fBTcl_FSEqualPaths\fR, and the \fIlinkNamePtr\fR
+and \fItoPtr\fR arguments to \fBTcl_FSLink\fR) must not be a zero reference
+count value; references may be retained in internal caches even for
+theoretically read-only operations.  These functions may also manipulate the
+interpreter result (if they take and are given a non-NULL \fIinterp\fR
+argument); you must not count on the interpreter result to hold the reference
+count of any argument value over these calls and should manage your own
+references there. However, references held by the arguments to a Tcl command
+\fIare\fR suitable for reference count management purposes for the duration of
+the implementation of that command.
+.PP
+The \fIerrorPtr\fR argument to \fBTcl_FSCopyDirectory\fR and
+\fBTcl_FSRemoveDirectory\fR is, when an object is set into it at all, set to
+an object with a non-zero reference count that should be passed to
+\fBTcl_DecrRefCount\fR when no longer needed.
+.PP
+\fBTcl_FSListVolumes\fR always returns a zero-reference object, much
+like \fBTcl_NewObj\fR.
+.PP
+\fBTcl_FSLink\fR always returns a non-zero-reference object when it is
+asked to read; you must call \fBTcl_DecrRefCount\fR on the object
+once you no longer need it.
+.PP
+\fBTcl_FSGetCwd\fR always returns a non-zero-reference object; you
+must call \fBTcl_DecrRefCount\fR on the object once you no longer need
+it.
+.PP
+\fBTcl_FSPathSeparator\fR always returns a zero-reference object, much
+like \fBTcl_NewObj\fR.
+.PP
+\fBTcl_FSJoinPath\fR always returns a zero-reference object, much
+like \fBTcl_NewObj\fR. Its \fIlistObj\fR argument can have any reference
+count; it is only read by this function.
+.PP
+\fBTcl_FSSplitPath\fR always returns a zero-reference object, much
+like \fBTcl_NewObj\fR.
+.PP
+\fBTcl_FSGetNormalizedPath\fR returns an object with a non-zero
+reference count where Tcl is the owner. You should increment its
+reference count if you want to retain it, but do not need to if you
+are just using the value immediately.
+.PP
+\fBTcl_FSJoinToPath\fR always returns a zero-reference object, much like
+\fBTcl_NewObj\fR. Its \fIbasePtr\fR argument follows the rules above for
+\fIpathPtr\fR, as do the values in the \fIobjv\fR argument.
+.PP
+\fBTcl_FSGetTranslatedPath\fR returns a non-zero-reference object (or
+NULL in the error case); you must call \fBTcl_DecrRefCount\fR on the
+object once you no longer need it.
+.PP
+\fBTcl_FSNewNativePath\fR always returns a zero-reference object (or
+NULL), much like \fBTcl_NewObj\fR.
+.PP
+\fBTcl_FSFileSystemInfo\fR always returns a zero-reference object (or
+NULL), much like \fBTcl_NewObj\fR.
+.PP
+The \fIobjPtr\fR and \fIobjPtrRef\fR arguments to \fBTcl_FSFileAttrsGet\fR,
+\fBTcl_FSFileAttrsSet\fR and \fBTcl_FSFileAttrStrings\fR are conventional Tcl
+values; the \fIobjPtr\fR argument will be read but not retained, and the
+\fIobjPtrRef\fR argument will have (on success) a zero-reference value written
+into it (as with \fBTcl_NewObj\fR). \fBTcl_FSFileAttrsGet\fR and
+\fBTcl_FSFileAttrsSet\fR may also manipulate the interpreter result.
+.PP
+The \fIresultPtr\fR argument to \fBTcl_FSMatchInDirectory\fR will not have its
+reference count manipulated, but it should have a reference count of no more
+than 1, and should not be the current interpreter result (as the function may
+overwrite that on error).
+.SS "VIRTUAL FILESYSTEM INTERFACE"
+.PP
+For all virtual filesystem implementation functions, any \fIpathPtr\fR
+arguments should not have their reference counts manipulated. If they take an
+\fIinterp\fR argument, they may set an error message in that, but must not
+manipulate the \fIpathPtr\fR afterwards. Aside from that:
+.TP
+\fIinternalToNormalizedProc\fR
+.
+This should return a zero-reference count value, as if allocated with
+\fBTcl_NewObj\fR.
+.TP
+\fInormalizePathProc\fR
+.
+Unlike with other API implementation functions, the \fIpathPtr\fR argument
+here is guaranteed to be an unshared object that should be updated. Its
+reference count should not be modified.
+.TP
+\fIfilesystemPathTypeProc\fR
+.
+The return value (if non-NULL) either has a reference count of zero or needs
+to be maintained (on a per-thread basis) by the filesystem. Tcl will increment
+the reference count of the value if it wishes to retain it.
+.TP
+\fIfilesystemSeparatorProc\fR
+.
+The return value should be a value with reference count of zero.
+.TP
+\fImatchInDirectoryProc\fR
+.
+The \fIresultPtr\fR argument should be assumed to hold a list that can be
+appended to (i.e., that has a reference count no greater than 1). No reference
+to it should be retained.
+.TP
+\fIlinkProc\fR
+.
+If \fItoPtr\fR is NULL, this should return a value with reference count 1 that
+has just been allocated and passed to \fBTcl_IncrRefCount\fR. If \fItoPtr\fR
+is not NULL, it should be returned on success.
+.TP
+\fIlistVolumesProc\fR
+.
+The result value should be a list (if non-NULL); it will have its reference
+count decremented once (with \fBTcl_DecrRefCount\fR) by Tcl once done.
+.TP
+\fIfileAttrStringsProc\fR
+.
+If the result is NULL, the \fIobjPtrRef\fR should have a list value written to
+it; that list will have its reference count both incremented (with
+\fBTcl_IncrRefCount\fR) and decremented (with \fBTcl_DecrRefCount\fR).
+.TP
+\fIfileAttrsGetProc\fR
+.
+The \fIobjPtrRef\fR argument should have (on non-error return) a zero
+reference count value written to it (allocated as if with \fBTcl_NewObj\fR).
+.TP
+\fIfileAttrsSetProc\fR
+.
+The \fIobjPtr\fR argument should either just be read or its reference count
+incremented to retain it.
+.TP
+\fIremoveDirectoryProc\fR
+.
+If an error is being reported, the problem filename reported via
+\fIerrorPtr\fR should be newly allocated (as if with \fBTcl_NewObj\fR) and
+have a reference count of 1 (i.e., have been passed to
+\fBTcl_IncrRefCount\fR).
+.TP
+\fIcopyDirectoryProc\fR
+.
+If an error is being reported, the problem filename reported via
+\fIerrorPtr\fR should be newly allocated (as if with \fBTcl_NewObj\fR) and
+have a reference count of 1 (i.e., have been passed to
+\fBTcl_IncrRefCount\fR).
+.TP
+\fIgetCwdProc\fR
+.
+The result will be passed to \fBTcl_DecrRefCount\fR by the implementation of
+\fBTcl_FSGetCwd\fR after it has been normalized.
 .SH "SEE ALSO"
 cd(n), file(n), filename(n), load(n), open(n), pwd(n), source(n), unload(n)
 .SH KEYWORDS
diff --git a/doc/FindExec.3 b/doc/FindExec.3
index 1fd57db..149ef8a 100644
--- a/doc/FindExec.3
+++ b/doc/FindExec.3
@@ -58,6 +58,8 @@ internal full path name of the executable file as computed by
 equivalent to the \fBinfo nameofexecutable\fR command.  NULL
 is returned if the internal full path name has not been
 computed or unknown.
-
+.PP
+\fBTcl_FindExecutable\fR can not be used in stub-enabled extensions. Its symbol
+entry in the stub table is deprecated and it will be removed in Tcl 9.0.
 .SH KEYWORDS
 binary, executable file
diff --git a/doc/GetIndex.3 b/doc/GetIndex.3
index 17a31d4..a788848 100644
--- a/doc/GetIndex.3
+++ b/doc/GetIndex.3
@@ -27,19 +27,22 @@ Interpreter to use for error reporting; if NULL, then no message is
 provided on errors.
 .AP Tcl_Obj *objPtr in/out
 The string value of this value is used to search through \fItablePtr\fR.
-The internal representation is modified to hold the index of the matching
+If the \fBTCL_INDEX_TEMP_TABLE\fR flag is not specified,
+the internal representation is modified to hold the index of the matching
 table entry.
 .AP "const char *const" *tablePtr in
 An array of null-terminated strings.  The end of the array is marked
 by a NULL string pointer.
-Note that references to the \fItablePtr\fR may be retained in the
+Note that, unless the \fBTCL_INDEX_TEMP_TABLE\fR flag is specified,
+references to the \fItablePtr\fR may be retained in the
 internal representation of \fIobjPtr\fR, so this should represent the
 address of a statically-allocated array.
 .AP "const void" *structTablePtr in
 An array of arbitrary type, typically some \fBstruct\fR type.
 The first member of the structure must be a null-terminated string.
 The size of the structure is given by \fIoffset\fR.
-Note that references to the \fIstructTablePtr\fR may be retained in the
+Note that, unless the \fBTCL_INDEX_TEMP_TABLE\fR flag is specified,
+references to the \fIstructTablePtr\fR may be retained in the
 internal representation of \fIobjPtr\fR, so this should represent the
 address of a statically-allocated array of structures.
 .AP int offset in
@@ -50,7 +53,8 @@ Null-terminated string describing what is being looked up, such as
 \fBoption\fR.  This string is included in error messages.
 .AP int flags in
 OR-ed combination of bits providing additional information for
-operation.  The only bit that is currently defined is \fBTCL_EXACT\fR.
+operation.  The only bits that are currently defined are \fBTCL_EXACT\fR
+and \fBTCL_INDEX_TEMP_TABLE\fR.
 .AP int *indexPtr out
 The index of the string in \fItablePtr\fR that matches the value of
 \fIobjPtr\fR is returned here.
@@ -76,7 +80,8 @@ error message to indicate what was being looked up.  For example,
 if \fImsg\fR is \fBoption\fR the error message will have a form like
 .QW "\fBbad option \N'34'firt\N'34': must be first, second, or third\fR" .
 .PP
-If \fBTcl_GetIndexFromObj\fR completes successfully it modifies the
+If the \fBTCL_INDEX_TEMP_TABLE\fR was not specified, when
+\fBTcl_GetIndexFromObj\fR completes successfully it modifies the
 internal representation of \fIobjPtr\fR to hold the address of
 the table and the index of the matching entry.  If \fBTcl_GetIndexFromObj\fR
 is invoked again with the same \fIobjPtr\fR and \fItablePtr\fR
@@ -84,7 +89,9 @@ arguments (e.g. during a reinvocation of a Tcl command), it returns
 the matching index immediately without having to redo the lookup
 operation.  Note: \fBTcl_GetIndexFromObj\fR assumes that the entries
 in \fItablePtr\fR are static: they must not change between
-invocations.  If the value of \fIobjPtr\fR is the empty string,
+invocations.  This caching mechanism can be disallowed by specifying
+the \fBTCL_INDEX_TEMP_TABLE\fR flag.
+If the value of \fIobjPtr\fR is the empty string,
 \fBTcl_GetIndexFromObj\fR will treat it as a non-matching value
 and return \fBTCL_ERROR\fR.
 .PP
@@ -98,6 +105,12 @@ array of characters at \fItablePtr\fR+\fIoffset\fR bytes, etc.)
 This is particularly useful when processing things like
 \fBTk_ConfigurationSpec\fR, whose string keys are in the same place in
 each of several array elements.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_GetIndexFromObj\fR and \fBTcl_GetIndexFromObjStruct\fR do not modify
+the reference count of their \fIobjPtr\fR arguments; they only read. Note
+however that these functions may set the interpreter result; if that is the
+only place that is holding a reference to the object, it will be deleted.
 .SH "SEE ALSO"
 prefix(n), Tcl_WrongNumArgs(3)
 .SH KEYWORDS
diff --git a/doc/GetInt.3 b/doc/GetInt.3
index 5a3304a..eba549d 100644
--- a/doc/GetInt.3
+++ b/doc/GetInt.3
@@ -57,6 +57,9 @@ after the optional white space and sign are
 .QW \fB0x\fR
 then \fIsrc\fR is expected to be in hexadecimal form;  otherwise,
 if the first such characters are
+.QW \fB0d\fR
+then \fIsrc\fR is expected to be in decimal form; otherwise,
+if the first such characters are
 .QW \fB0o\fR
 then \fIsrc\fR is expected to be in octal form;  otherwise,
 if the first such characters are
@@ -65,8 +68,8 @@ then \fIsrc\fR is expected to be in binary form;  otherwise,
 if the first such character is
 .QW \fB0\fR
 then \fIsrc\fR
-is expected to be in octal form;  otherwise, \fIsrc\fR is
-expected to be in decimal form.
+is expected to be in octal form;  otherwise, \fIsrc\fR
+is expected to be in decimal form.
 .PP
 \fBTcl_GetDouble\fR expects \fIsrc\fR to consist of a floating-point
 number, which is:  white space;  a sign; a sequence of digits;  a
diff --git a/doc/Hash.3 b/doc/Hash.3
index 4dc3623..0532390 100644
--- a/doc/Hash.3
+++ b/doc/Hash.3
@@ -281,7 +281,7 @@ The \fIhashKeyProc\fR member contains the address of a function called to
 calculate a hash value for the key.
 .PP
 .CS
-typedef unsigned int \fBTcl_HashKeyProc\fR(
+typedef TCL_HASH_TYPE \fBTcl_HashKeyProc\fR(
         Tcl_HashTable *\fItablePtr\fR,
         void *\fIkeyPtr\fR);
 .CE
@@ -330,5 +330,19 @@ typedef void \fBTcl_FreeHashEntryProc\fR(
 If this is NULL then \fBTcl_Free\fR is used to free the space for the entry.
 Tcl_Obj* keys use this function to decrement the reference count on the
 value.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+When a hash table is created with \fBTcl_InitCustomHashTable\fR, the
+\fBTcl_CreateHashEntry\fR function will increment the reference count of its
+\fIkey\fR argument when it creates a key (but not if there is an existing
+matching key). The reference count of the key will be decremented when the
+corresponding hash entry is deleted, whether with \fBTcl_DeleteHashEntry\fR or
+with \fBTcl_DeleteHashTable\fR. The \fBTcl_GetHashKey\fR function will return
+the key without further modifying its reference count.
+.PP
+Custom hash tables that use a Tcl_Obj* as key will generally need to do
+something similar in their \fIallocEntryProc\fR.
+.SH "SEE ALSO"
+Dict(3)
 .SH KEYWORDS
 hash table, key, lookup, search, value
diff --git a/doc/Init.3 b/doc/Init.3
index d9fc2e1..cf17a37 100644
--- a/doc/Init.3
+++ b/doc/Init.3
@@ -2,7 +2,7 @@
 '\" Copyright (c) 1998-2000 Scriptics Corporation.
 '\" All rights reserved.
 '\"
-.TH Tcl_Init 3 8.0 Tcl "Tcl Library Procedures"
+.TH Tcl_Init 3 8.7 Tcl "Tcl Library Procedures"
 .so man.macros
 .BS
 .SH NAME
@@ -13,10 +13,15 @@ Tcl_Init \- find and source initialization script
 .sp
 int
 \fBTcl_Init\fR(\fIinterp\fR)
+.sp
+const char *
+\fBTcl_SetPreInitScript\fR(\fIscriptPtr\fR)
 .SH ARGUMENTS
 .AS Tcl_Interp *interp
 .AP Tcl_Interp *interp in
 Interpreter to initialize.
+.AP "const char" *scriptPtr in
+Address of the initialization script.
 .BE
 
 .SH DESCRIPTION
@@ -26,6 +31,13 @@ Interpreter to initialize.
 path.
 .PP
 \fBTcl_Init\fR is typically called from \fBTcl_AppInit\fR procedures.
+.PP
+\fBTcl_SetPreInitScript\fR registers the pre-initialization script and
+returns the former (now replaced) script pointer.
+A value of \fINULL\fR may be passed to not register any script.
+The pre-initialization script is executed by \fBTcl_Init\fR before accessing
+the file system. The purpose is to typically prepare a custom file system
+(like an embedded zip-file) to be activated before the search.
 
 .SH "SEE ALSO"
 Tcl_AppInit, Tcl_Main
diff --git a/doc/InitStubs.3 b/doc/InitStubs.3
index fbb3f56..4423666 100644
--- a/doc/InitStubs.3
+++ b/doc/InitStubs.3
@@ -23,11 +23,11 @@ Tcl interpreter handle.
 A version string consisting of one or more decimal numbers
 separated by dots.
 .AP int exact in
-Non-zero means that only the particular version specified by
+1 means that only the particular version specified by
 \fIversion\fR is acceptable.
-Zero means that versions newer than \fIversion\fR are also
+0 means that versions newer than \fIversion\fR are also
 acceptable as long as they have the same major version number
-as \fIversion\fR.
+as \fIversion\fR. Other bits have no effect.
 .BE
 .SH INTRODUCTION
 .PP
diff --git a/doc/InitSubSyst.3 b/doc/InitSubSyst.3
new file mode 100644
index 0000000..3c138a4
--- /dev/null
+++ b/doc/InitSubSyst.3
@@ -0,0 +1,31 @@
+'\"
+'\" Copyright (c) 2018 Tcl Core Team
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.so man.macros
+.TH Tcl_InitSubsystems 3 8.7 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_InitSubsystems \- initialize the Tcl library.
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+void
+\fBTcl_InitSubsystems\fR(\fIvoid\fR)
+.SH DESCRIPTION
+.PP
+The \fBTcl_InitSubsystems\fR procedure initializes the Tcl
+library. This procedure is typically invoked as the very
+first thing in the application's main program.
+.PP
+\fBTcl_InitSubsystems\fR is very similar in use to
+\fBTcl_FindExecutable\fR. It can be used when Tcl is
+used as utility library, no other encodings than utf8,
+iso8859-1 or unicode are used, and no interest exists in the
+value of \fBinfo nameofexecutable\fR. The system encoding will not
+be extracted from the environment, but falls back to iso8859-1.
+.SH KEYWORDS
+binary, executable file
diff --git a/doc/IntObj.3 b/doc/IntObj.3
index 2acb446..d640dbb 100644
--- a/doc/IntObj.3
+++ b/doc/IntObj.3
@@ -8,7 +8,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, Tcl_GetIntFromObj, Tcl_GetLongFromObj, Tcl_GetWideIntFromObj, Tcl_NewBignumObj, Tcl_SetBignumObj, Tcl_GetBignumFromObj, Tcl_TakeBignumFromObj \- manipulate Tcl values as integers
+Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, Tcl_GetIntFromObj, Tcl_GetIntForIndex, Tcl_GetLongFromObj, Tcl_GetWideIntFromObj, Tcl_NewBignumObj, Tcl_SetBignumObj, Tcl_GetBignumFromObj, Tcl_TakeBignumFromObj \- manipulate Tcl values as integers
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -32,6 +32,9 @@ int
 \fBTcl_GetIntFromObj\fR(\fIinterp, objPtr, intPtr\fR)
 .sp
 int
+\fBTcl_GetIntForIndex\fR(\fIinterp, objPtr, endValue, intPtr\fR)
+.sp
+int
 \fBTcl_GetLongFromObj\fR(\fIinterp, objPtr, longPtr\fR)
 .sp
 int
@@ -55,6 +58,8 @@ int
 \fBTcl_InitBignumFromDouble\fR(\fIinterp, doubleValue, bigValue\fR)
 .SH ARGUMENTS
 .AS Tcl_WideInt doubleValue in/out
+.AP int endValue in
+\fBTcl_GetIntForIndex\fR will return this when the input value is "end".
 .AP int intValue in
 Integer value used to initialize or set a Tcl value.
 .AP long longValue in
@@ -97,7 +102,7 @@ are provided by the C language standard.  The \fBTcl_WideInt\fR type is a
 typedef defined to be whatever signed integral type covers at least the
 64-bit integer range (-9223372036854775808 to 9223372036854775807).  Depending
 on the platform and the C compiler, the actual type might be
-\fBlong int\fR, \fBlong long int\fR, \fB__int64\fR, or something else.
+\fBlong long int\fR, or something else.
 The \fBmp_int\fR type is a multiple-precision integer type defined
 by the LibTomMath multiple-precision integer library.
 .PP
@@ -115,6 +120,16 @@ violates Tcl's copy-on-write policy.  Any existing string representation
 or internal representation in the unshared Tcl value will be freed
 as a consequence of setting the new value.
 .PP
+The \fBTcl_GetIntForIndex\fR routine attempts to retrieve an index
+value from the Tcl value \fIobjPtr\fR.  If the attempt succeeds,
+then \fBTCL_OK\fR is returned, and the value is written to the
+storage provided by the caller.  The attempt might fail if
+\fIobjPtr\fR does not hold an index value.  If the attempt fails,
+then \fBTCL_ERROR\fR is returned, and if \fIinterp\fR is non-NULL,
+an error message is left in \fIinterp\fR.  The \fBTcl_ObjType\fR
+of \fIobjPtr\fR may be changed to make subsequent calls to the
+same routine more efficient.
+.PP
 The \fBTcl_GetIntFromObj\fR, \fBTcl_GetLongFromObj\fR,
 \fBTcl_GetWideIntFromObj\fR, \fBTcl_GetBignumFromObj\fR, and
 \fBTcl_TakeBignumFromObj\fR routines attempt to retrieve an integral
@@ -145,6 +160,27 @@ If anything later in the caller requires
 The \fBTcl_InitBignumFromDouble\fR routine is a utility procedure
 that extracts the integer part of \fIdoubleValue\fR and stores that
 integer value in the \fBmp_int\fR value \fIbigValue\fR.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_NewIntObj\fR, \fBTcl_NewLongObj\fR, \fBTcl_NewWideIntObj\fR, and
+\fBTcl_NewBignumObj\fR always return a zero-reference object, much like
+\fBTcl_NewObj\fR.
+.PP
+\fBTcl_SetIntObj\fR, \fBTcl_SetLongObj\fR, \fBTcl_SetWideIntObj\fR, and
+\fBTcl_SetBignumObj\fR do not modify the reference count of their \fIobjPtr\fR
+arguments, but do require that the object be unshared.
+.PP
+\fBTcl_GetIntFromObj\fR, \fBTcl_GetIntForIndex\fR, \fBTcl_GetLongFromObj\fR,
+\fBTcl_GetWideIntFromObj\fR, \fBTcl_GetBignumFromObj\fR, and
+\fBTcl_TakeBignumFromObj\fR do not modify the reference count of their
+\fIobjPtr\fR arguments; they only read. Note however that this function may
+set the interpreter result; if that is the only place that is holding a
+reference to the object, it will be deleted. Also note that if
+\fBTcl_TakeBignumFromObj\fR is given an unshared value, the value of that
+object may be modified; it is intended to be used when the value is
+.QW consumed
+by the operation at this point.
+
 .SH "SEE ALSO"
 Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
 .SH KEYWORDS
diff --git a/doc/Interp.3 b/doc/Interp.3
index 731007b..c1b9803 100644
--- a/doc/Interp.3
+++ b/doc/Interp.3
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-.TH Tcl_Interp 3 7.5 Tcl "Tcl Library Procedures"
+.TH Tcl_Interp 3 8.7 Tcl "Tcl Library Procedures"
 .so man.macros
 .BS
 .SH NAME
@@ -15,9 +15,9 @@ Tcl_Interp \- client-visible fields of interpreter structures
 \fB#include <tcl.h>\fR
 .sp
 typedef struct {
-    char *\fIresult\fR;
-    Tcl_FreeProc *\fIfreeProc\fR;
-    int \fIerrorLine\fR;
+    char *\fIresult\fR;			/* NO LONGER AVAILABLE */
+    Tcl_FreeProc *\fIfreeProc\fR;	/* NO LONGER AVAILABLE */
+    int \fIerrorLine\fR;		/* NO LONGER AVAILABLE */
 } \fBTcl_Interp\fR;
 
 typedef void \fBTcl_FreeProc\fR(
@@ -25,110 +25,17 @@ typedef void \fBTcl_FreeProc\fR(
 .BE
 .SH DESCRIPTION
 .PP
-The \fBTcl_CreateInterp\fR procedure returns a pointer to a Tcl_Interp
+The \fBTcl_CreateInterp\fR procedure returns a pointer to a \fBTcl_Interp\fR
 structure.  Callers of \fBTcl_CreateInterp\fR should use this pointer
 as an opaque token, suitable for nothing other than passing back to
-other routines in the Tcl interface.  Accessing fields directly through
-the pointer as described below is no longer supported.  The supported
-public routines \fBTcl_SetResult\fR, \fBTcl_GetResult\fR,
-\fBTcl_SetErrorLine\fR, \fBTcl_GetErrorLine\fR must be used instead.
-.PP
-For legacy programs and extensions no longer being maintained, compiles
-against the Tcl 8.6 header files are only possible with the compiler
-directives
-.CS
-#define USE_INTERP_RESULT
-.CE
-and/or
-.CS
-#define USE_INTERP_ERRORLINE
-.CE
-depending on which fields of the \fBTcl_Interp\fR struct are accessed.
-These directives may be embedded in code or supplied via compiler options.
-.PP
-The \fIresult\fR and \fIfreeProc\fR fields are used to return
-results or error messages from commands.
-This information is returned by command procedures back to \fBTcl_Eval\fR,
-and by \fBTcl_Eval\fR back to its callers.
-The \fIresult\fR field points to the string that represents the
-result or error message, and the \fIfreeProc\fR field tells how
-to dispose of the storage for the string when it is not needed anymore.
-The easiest way for command procedures to manipulate these
-fields is to call procedures like \fBTcl_SetResult\fR
-or \fBTcl_AppendResult\fR;  they
-will hide all the details of managing the fields.
-The description below is for those procedures that manipulate the
-fields directly.
-.PP
-Whenever a command procedure returns, it must ensure
-that the \fIresult\fR field of its interpreter points to the string
-being returned by the command.
-The \fIresult\fR field must always point to a valid string.
-If a command wishes to return no result then \fIinterp->result\fR
-should point to an empty string.
-Normally, results are assumed to be statically allocated,
-which means that the contents will not change before the next time
-\fBTcl_Eval\fR is called or some other command procedure is invoked.
-In this case, the \fIfreeProc\fR field must be zero.
-Alternatively, a command procedure may dynamically
-allocate its return value (e.g. using \fBTcl_Alloc\fR)
-and store a pointer to it in \fIinterp->result\fR.
-In this case, the command procedure must also set \fIinterp->freeProc\fR
-to the address of a procedure that can free the value, or \fBTCL_DYNAMIC\fR
-if the storage was allocated directly by Tcl or by a call to
-\fBTcl_Alloc\fR.
-If \fIinterp->freeProc\fR is non-zero, then Tcl will call \fIfreeProc\fR
-to free the space pointed to by \fIinterp->result\fR before it
-invokes the next command.
-If a client procedure overwrites \fIinterp->result\fR when
-\fIinterp->freeProc\fR is non-zero, then it is responsible for calling
-\fIfreeProc\fR to free the old \fIinterp->result\fR (the \fBTcl_FreeResult\fR
-macro should be used for this purpose).
-.PP
-\fIFreeProc\fR should have arguments and result that match the
-\fBTcl_FreeProc\fR declaration above:  it receives a single
-argument which is a pointer to the result value to free.
-In most applications \fBTCL_DYNAMIC\fR is the only non-zero value ever
-used for \fIfreeProc\fR.
-However, an application may store a different procedure address
-in \fIfreeProc\fR in order to use an alternate memory allocator
-or in order to do other cleanup when the result memory is freed.
-.PP
-As part of processing each command, \fBTcl_Eval\fR initializes
-\fIinterp->result\fR
-and \fIinterp->freeProc\fR just before calling the command procedure for
-the command.  The \fIfreeProc\fR field will be initialized to zero,
-and \fIinterp->result\fR will point to an empty string.  Commands that
-do not return any value can simply leave the fields alone.
-Furthermore, the empty string pointed to by \fIresult\fR is actually
-part of an array of \fBTCL_RESULT_SIZE\fR characters (approximately 200).
-If a command wishes to return a short string, it can simply copy
-it to the area pointed to by \fIinterp->result\fR.  Or, it can use
-the sprintf procedure to generate a short result string at the location
-pointed to by \fIinterp->result\fR.
-.PP
-It is a general convention in Tcl-based applications that the result
-of an interpreter is normally in the initialized state described
-in the previous paragraph.
-Procedures that manipulate an interpreter's result (e.g. by
-returning an error) will generally assume that the result
-has been initialized when the procedure is called.
-If such a procedure is to be called after the result has been
-changed, then \fBTcl_ResetResult\fR should be called first to
-reset the result to its initialized state.  The direct use of
-\fIinterp->result\fR is strongly deprecated (see \fBTcl_SetResult\fR).
-.PP
-The \fIerrorLine\fR
-field is valid only after \fBTcl_Eval\fR returns
-a \fBTCL_ERROR\fR return code.  In this situation the \fIerrorLine\fR
-field identifies the line number of the command being executed when
-the error occurred.  The line numbers are relative to the command
-being executed:  1 means the first line of the command passed to
-\fBTcl_Eval\fR, 2 means the second line, and so on.
-The \fIerrorLine\fR field is typically used in conjunction with
-\fBTcl_AddErrorInfo\fR to report information about where an error
-occurred.
-\fIErrorLine\fR should not normally be modified except by \fBTcl_Eval\fR.
+other routines in the Tcl interface from the same thread that called
+\fBTcl_CreateInterp\fR.  The \fBTcl_Interp\fR struct no longer has any
+supported client-visible fields.  Supported public routines such as
+\fBTcl_SetResult\fR, \fBTcl_GetResult\fR, \fBTcl_SetErrorLine\fR,
+\fBTcl_GetErrorLine\fR must be used instead.
+.PP
+Any legacy programs and extensions trying to access the fields above
+in their source code will need conversion to compile for Tcl 8.7 and later.
 
 .SH KEYWORDS
-free, initialized, interpreter, malloc, result
+interpreter, result
diff --git a/doc/LinkVar.3 b/doc/LinkVar.3
index c80d30d..92e7d03 100644
--- a/doc/LinkVar.3
+++ b/doc/LinkVar.3
@@ -9,7 +9,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar \- link Tcl variable to C variable
+Tcl_LinkArray, Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar \- link Tcl variable to C variable
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -17,27 +17,52 @@ Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar \- link Tcl variable to C variab
 int
 \fBTcl_LinkVar\fR(\fIinterp, varName, addr, type\fR)
 .sp
+.VS "TIP 312"
+int
+\fBTcl_LinkArray\fR(\fIinterp, varName, addr, type, size\fR)
+.VE "TIP 312"
+.sp
 \fBTcl_UnlinkVar\fR(\fIinterp, varName\fR)
 .sp
 \fBTcl_UpdateLinkedVar\fR(\fIinterp, varName\fR)
 .SH ARGUMENTS
-.AS Tcl_Interp writable
+.AS Tcl_Interp varName in
 .AP Tcl_Interp *interp in
 Interpreter that contains \fIvarName\fR.
 Also used by \fBTcl_LinkVar\fR to return error messages.
 .AP "const char" *varName in
 Name of global variable.
-.AP char *addr in
+.AP void *addr in
 Address of C variable that is to be linked to \fIvarName\fR.
+.sp
+.VS "TIP 312"
+In \fBTcl_LinkArray\fR, may be NULL to tell Tcl to create the storage
+for the array in the variable.
+.VE "TIP 312"
 .AP int type in
-Type of C variable.  Must be one of \fBTCL_LINK_INT\fR,
+Type of C variable for \fBTcl_LinkVar\fR or type of array element for
+\fBTcl_LinkArray\fR.  Must be one of \fBTCL_LINK_INT\fR,
 \fBTCL_LINK_UINT\fR, \fBTCL_LINK_CHAR\fR, \fBTCL_LINK_UCHAR\fR,
 \fBTCL_LINK_SHORT\fR, \fBTCL_LINK_USHORT\fR, \fBTCL_LINK_LONG\fR,
 \fBTCL_LINK_ULONG\fR, \fBTCL_LINK_WIDE_INT\fR,
-\fBTCL_LINK_WIDE_UINT\fR, \fBTCL_LINK_FLOAT\fR,
-\fBTCL_LINK_DOUBLE\fR, \fBTCL_LINK_BOOLEAN\fR, or
-\fBTCL_LINK_STRING\fR, optionally OR'ed with \fBTCL_LINK_READ_ONLY\fR
-to make Tcl variable read-only.
+\fBTCL_LINK_WIDE_UINT\fR, \fBTCL_LINK_FLOAT\fR, \fBTCL_LINK_DOUBLE\fR,
+\fBTCL_LINK_BOOLEAN\fR, or one of the extra ones listed below.
+.sp
+In \fBTcl_LinkVar\fR, the additional linked type \fBTCL_LINK_STRING\fR may be
+used.
+.sp
+.VS "TIP 312"
+In \fBTcl_LinkArray\fR, the additional linked types \fBTCL_LINK_CHARS\fR and
+\fBTCL_LINK_BYTES\fR may be used.
+.VE "TIP 312"
+.sp
+All the above for both functions may be
+optionally OR'ed with \fBTCL_LINK_READ_ONLY\fR to make the Tcl
+variable read-only.
+.AP int size in
+.VS "TIP 312"
+The number of elements in the C array. Must be greater than zero.
+.VE "TIP 312"
 .BE
 .SH DESCRIPTION
 .PP
@@ -52,130 +77,179 @@ while setting up the link (e.g. because \fIvarName\fR is the
 name of array) then \fBTCL_ERROR\fR is returned and the interpreter's result
 contains an error message.
 .PP
+.VS "TIP 312"
+\fBTcl_LinkArray\fR is similar, but for arrays of fixed size (given by
+the \fIsize\fR argument). When asked to allocate the backing C array
+storage (via the \fIaddr\fR argument being NULL), it writes the
+address that it allocated to the Tcl interpreter result.
+.VE "TIP 312"
+.PP
 The \fItype\fR argument specifies the type of the C variable,
+or the type of the elements of the C array,
 and must have one of the following values, optionally OR'ed with
 \fBTCL_LINK_READ_ONLY\fR:
 .TP
 \fBTCL_LINK_INT\fR
-The C variable is of type \fBint\fR.
+.
+The C variable, or each element of the C array, is of type \fBint\fR.
 Any value written into the Tcl variable must have a proper integer
 form acceptable to \fBTcl_GetIntFromObj\fR;  attempts to write
 non-integer values into \fIvarName\fR will be rejected with
 Tcl errors. Incomplete integer representations (like the empty
-string, '+', '-' or the hex/octal/binary prefix) are accepted
+string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted
 as if they are valid too.
 .TP
 \fBTCL_LINK_UINT\fR
-The C variable is of type \fBunsigned int\fR.
+.
+The C variable, or each element of the C array, is of type \fBunsigned int\fR.
 Any value written into the Tcl variable must have a proper unsigned
 integer form acceptable to \fBTcl_GetWideIntFromObj\fR and in the
 platform's defined range for the \fBunsigned int\fR type; attempts to
 write non-integer values (or values outside the range) into
 \fIvarName\fR will be rejected with Tcl errors. Incomplete integer
-representations (like the empty string, '+', '-' or the hex/octal/binary
+representations (like the empty string, '+', '-' or the hex/octal/decimal/binary
 prefix) are accepted as if they are valid too.
 .TP
 \fBTCL_LINK_CHAR\fR
-The C variable is of type \fBchar\fR.
+.
+The C variable, or each element of the C array, is of type \fBchar\fR.
 Any value written into the Tcl variable must have a proper integer
 form acceptable to \fBTcl_GetIntFromObj\fR and be in the range of the
 \fBchar\fR datatype; attempts to write non-integer or out-of-range
 values into \fIvarName\fR will be rejected with Tcl errors. Incomplete
 integer representations (like the empty string, '+', '-' or the
-hex/octal/binary prefix) are accepted as if they are valid too.
+hex/octal/decimal/binary prefix) are accepted as if they are valid too.
+.RS
+.PP
+.VS "TIP 312"
+If using an array of these, consider using \fBTCL_LINK_CHARS\fR instead.
+.VE "TIP 312"
+.RE
+.TP
+\fBTCL_LINK_CHARS\fR
+.VS "TIP 312"
+The C array is of type \fBchar *\fR and is mapped into Tcl as a string.
+Any value written into the Tcl variable must have the same length as
+the underlying storage. Only supported with \fBTcl_LinkArray\fR.
+.VE "TIP 312"
 .TP
 \fBTCL_LINK_UCHAR\fR
-The C variable is of type \fBunsigned char\fR.
+.
+The C variable, or each element of the C array, is of type \fBunsigned char\fR.
 Any value written into the Tcl variable must have a proper unsigned
 integer form acceptable to \fBTcl_GetIntFromObj\fR and in the
 platform's defined range for the \fBunsigned char\fR type; attempts to
 write non-integer values (or values outside the range) into
 \fIvarName\fR will be rejected with Tcl errors. Incomplete integer
-representations (like the empty string, '+', '-' or the hex/octal/binary
+representations (like the empty string, '+', '-' or the hex/octal/decimal/binary
 prefix) are accepted as if they are valid too.
+.RS
+.PP
+.VS "TIP 312"
+If using an array of these, consider using \fBTCL_LINK_BYTES\fR instead.
+.VE "TIP 312"
+.RE
+.TP
+\fBTCL_LINK_BYTES\fR
+.VS "TIP 312"
+The C array is of type \fBunsigned char *\fR and is mapped into Tcl
+as a bytearray.
+Any value written into the Tcl variable must have the same length as
+the underlying storage. Only supported with \fBTcl_LinkArray\fR.
+.VE "TIP 312"
 .TP
 \fBTCL_LINK_SHORT\fR
-The C variable is of type \fBshort\fR.
+.
+The C variable, or each element of the C array, is of type \fBshort\fR.
 Any value written into the Tcl variable must have a proper integer
 form acceptable to \fBTcl_GetIntFromObj\fR and be in the range of the
 \fBshort\fR datatype; attempts to write non-integer or out-of-range
 values into \fIvarName\fR will be rejected with Tcl errors. Incomplete
 integer representations (like the empty string, '+', '-' or the
-hex/octal/binary prefix) are accepted as if they are valid too.
+hex/octal/decimal/binary prefix) are accepted as if they are valid too.
 .TP
 \fBTCL_LINK_USHORT\fR
-The C variable is of type \fBunsigned short\fR.
+.
+The C variable, or each element of the C array, is of type \fBunsigned short\fR.
 Any value written into the Tcl variable must have a proper unsigned
 integer form acceptable to \fBTcl_GetIntFromObj\fR and in the
 platform's defined range for the \fBunsigned short\fR type; attempts to
 write non-integer values (or values outside the range) into
 \fIvarName\fR will be rejected with Tcl errors. Incomplete integer
-representations (like the empty string, '+', '-' or the hex/octal/binary
+representations (like the empty string, '+', '-' or the hex/octal/decimal/binary
 prefix) are accepted as if they are valid too.
 .TP
 \fBTCL_LINK_LONG\fR
-The C variable is of type \fBlong\fR.
+.
+The C variable, or each element of the C array, is of type \fBlong\fR.
 Any value written into the Tcl variable must have a proper integer
 form acceptable to \fBTcl_GetLongFromObj\fR; attempts to write
 non-integer or out-of-range
 values into \fIvarName\fR will be rejected with Tcl errors. Incomplete
 integer representations (like the empty string, '+', '-' or the
-hex/octal/binary prefix) are accepted as if they are valid too.
+hex/octal/decimal/binary prefix) are accepted as if they are valid too.
 .TP
 \fBTCL_LINK_ULONG\fR
-The C variable is of type \fBunsigned long\fR.
+.
+The C variable, or each element of the C array, is of type \fBunsigned long\fR.
 Any value written into the Tcl variable must have a proper unsigned
 integer form acceptable to \fBTcl_GetWideIntFromObj\fR and in the
 platform's defined range for the \fBunsigned long\fR type; attempts to
 write non-integer values (or values outside the range) into
 \fIvarName\fR will be rejected with Tcl errors. Incomplete integer
-representations (like the empty string, '+', '-' or the hex/octal/binary
+representations (like the empty string, '+', '-' or the hex/octal/decimal/binary
 prefix) are accepted as if they are valid too.
 .TP
 \fBTCL_LINK_DOUBLE\fR
-The C variable is of type \fBdouble\fR.
+.
+The C variable, or each element of the C array, is of type \fBdouble\fR.
 Any value written into the Tcl variable must have a proper real
 form acceptable to \fBTcl_GetDoubleFromObj\fR;  attempts to write
 non-real values into \fIvarName\fR will be rejected with
 Tcl errors. Incomplete integer or real representations (like the
-empty string, '.', '+', '-' or the hex/octal/binary prefix) are
+empty string, '.', '+', '-' or the hex/octal/decimal/binary prefix) are
 accepted as if they are valid too.
 .TP
 \fBTCL_LINK_FLOAT\fR
-The C variable is of type \fBfloat\fR.
+.
+The C variable, or each element of the C array, is of type \fBfloat\fR.
 Any value written into the Tcl variable must have a proper real
 form acceptable to \fBTcl_GetDoubleFromObj\fR and must be within the
 range acceptable for a \fBfloat\fR; attempts to
 write non-real values (or values outside the range) into
 \fIvarName\fR will be rejected with Tcl errors. Incomplete integer
 or real representations (like the empty string, '.', '+', '-' or
-the hex/octal/binary prefix) are accepted as if they are valid too.
+the hex/octal/decimal/binary prefix) are accepted as if they are valid too.
 .TP
 \fBTCL_LINK_WIDE_INT\fR
-The C variable is of type \fBTcl_WideInt\fR (which is an integer type
+.
+The C variable, or each element of the C array, is of type \fBTcl_WideInt\fR
+(which is an integer type
 at least 64-bits wide on all platforms that can support it.)
 Any value written into the Tcl variable must have a proper integer
 form acceptable to \fBTcl_GetWideIntFromObj\fR;  attempts to write
 non-integer values into \fIvarName\fR will be rejected with
 Tcl errors. Incomplete integer representations (like the empty
-string, '+', '-' or the hex/octal/binary prefix) are accepted
+string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted
 as if they are valid too.
 .TP
 \fBTCL_LINK_WIDE_UINT\fR
-The C variable is of type \fBTcl_WideUInt\fR (which is an unsigned
-integer type at least 64-bits wide on all platforms that can support
-it.)
+.
+The C variable, or each element of the C array, is of type \fBTcl_WideUInt\fR
+(which is an unsigned integer type at least 64-bits wide on all platforms that
+can support it.)
 Any value written into the Tcl variable must have a proper unsigned
 integer form acceptable to \fBTcl_GetWideIntFromObj\fR (it will be
 cast to unsigned);
 .\" FIXME! Use bignums instead.
 attempts to write non-integer values into \fIvarName\fR will be
 rejected with Tcl errors. Incomplete integer representations (like
-the empty string, '+', '-' or the hex/octal/binary prefix) are accepted
+the empty string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted
 as if they are valid too.
 .TP
 \fBTCL_LINK_BOOLEAN\fR
-The C variable is of type \fBint\fR.
+.
+The C variable, or each element of the C array, is of type \fBint\fR.
 If its value is zero then it will read from Tcl as
 .QW 0 ;
 otherwise it will read from Tcl as
@@ -188,6 +262,7 @@ non-boolean values into \fIvarName\fR will be rejected with
 Tcl errors.
 .TP
 \fBTCL_LINK_STRING\fR
+.
 The C variable is of type \fBchar *\fR.
 If its value is not NULL then it must be a pointer to a string
 allocated with \fBTcl_Alloc\fR or \fBckalloc\fR.
@@ -197,6 +272,7 @@ new value.
 If the C variable contains a NULL pointer then the Tcl variable
 will read as
 .QW NULL .
+This is only supported by \fBTcl_LinkVar\fR.
 .PP
 If the \fBTCL_LINK_READ_ONLY\fR flag is present in \fItype\fR then the
 variable will be read-only from Tcl, so that its value can only be
diff --git a/doc/ListObj.3 b/doc/ListObj.3
index ab836d8..67721c9 100644
--- a/doc/ListObj.3
+++ b/doc/ListObj.3
@@ -246,6 +246,31 @@ with a NULL \fIobjvPtr\fR:
 result = \fBTcl_ListObjReplace\fR(interp, listPtr, first, count,
         0, NULL);
 .CE
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_NewListObj\fR always returns a zero-reference object, much like
+\fBTcl_NewObj\fR. If a non-NULL \fIobjv\fR argument is given, the reference
+counts of the first \fIobjc\fR values in that array are incremented.
+.PP
+\fBTcl_SetListObj\fR does not modify the reference count of its \fIobjPtr\fR
+argument, but does require that the object be unshared. The reference counts
+of the first \fIobjc\fR values in the \fIobjv\fR array are incremented.
+.PP
+\fBTcl_ListObjGetElements\fR, \fBTcl_ListObjIndex\fR, and
+\fBTcl_ListObjLength\fR do not modify the reference count of their
+\fIlistPtr\fR arguments; they only read. Note however that these three
+functions may set the interpreter result; if that is the only place that is
+holding a reference to the object, it will be deleted.
+.PP
+\fBTcl_ListObjAppendList\fR, \fBTcl_ListObjAppendElement\fR, and
+\fBTcl_ListObjReplace\fR require an unshared \fIlistPtr\fR argument.
+\fBTcl_ListObjAppendList\fR only reads its \fIelemListPtr\fR argument.
+\fBTcl_ListObjAppendElement\fR increments the reference count of its
+\fIobjPtr\fR on success. \fBTcl_ListObjReplace\fR increments the reference
+count of the first \fIobjc\fR values in the \fIobjv\fR array on success.  Note
+however that all these three functions may set the interpreter result on
+failure; if that is the only place that is holding a reference to the object,
+it will be deleted.
 .SH "SEE ALSO"
 Tcl_NewObj(3), Tcl_DecrRefCount(3), Tcl_IncrRefCount(3), Tcl_GetObjResult(3)
 .SH KEYWORDS
diff --git a/doc/Load.3 b/doc/Load.3
index 1d0d738..4533510 100644
--- a/doc/Load.3
+++ b/doc/Load.3
@@ -60,6 +60,10 @@ be unloaded with \fBTcl_FSUnloadFile\fR.
 the symbol cannot be found, it returns NULL and sets an error message in the
 given \fIinterp\fR (if that is non-NULL). Note that it is unsafe to use this
 operation on a handle that has been passed to \fBTcl_FSUnloadFile\fR.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+The reference count of the \fIpathPtr\fR argument to \fBTcl_LoadFile\fR may be
+incremented. As such, it should not be given a zero reference count value.
 .SH "SEE ALSO"
 Tcl_FSLoadFile(3), Tcl_FSUnloadFile(3), load(n), unload(n)
 .SH KEYWORDS
diff --git a/doc/Method.3 b/doc/Method.3
index 225da00..577cd54 100644
--- a/doc/Method.3
+++ b/doc/Method.3
@@ -9,18 +9,18 @@
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-Tcl_ClassSetConstructor, Tcl_ClassSetDestructor, Tcl_MethodDeclarerClass, Tcl_MethodDeclarerObject, Tcl_MethodIsPublic, Tcl_MethodIsType, Tcl_MethodName, Tcl_NewInstanceMethod, Tcl_NewMethod, Tcl_ObjectContextInvokeNext, Tcl_ObjectContextIsFiltering, Tcl_ObjectContextMethod, Tcl_ObjectContextObject, Tcl_ObjectContextSkippedArgs \- manipulate methods and method-call contexts
+Tcl_ClassSetConstructor, Tcl_ClassSetDestructor, Tcl_MethodDeclarerClass, Tcl_MethodDeclarerObject, Tcl_MethodIsPublic, Tcl_MethodIsPrivate, Tcl_MethodIsType, Tcl_MethodName, Tcl_NewInstanceMethod, Tcl_NewMethod, Tcl_ObjectContextInvokeNext, Tcl_ObjectContextIsFiltering, Tcl_ObjectContextMethod, Tcl_ObjectContextObject, Tcl_ObjectContextSkippedArgs \- manipulate methods and method-call contexts
 .SH SYNOPSIS
 .nf
 \fB#include <tclOO.h>\fR
 .sp
 Tcl_Method
-\fBTcl_NewMethod\fR(\fIinterp, class, nameObj, isPublic,
-              methodTypePtr, clientData\fR)
+\fBTcl_NewMethod\fR(\fIinterp, class, nameObj, flags, methodTypePtr,
+              clientData\fR)
 .sp
 Tcl_Method
-\fBTcl_NewInstanceMethod\fR(\fIinterp, object, nameObj, isPublic,
-                      methodTypePtr, clientData\fR)
+\fBTcl_NewInstanceMethod\fR(\fIinterp, object, nameObj, flags, methodTypePtr,
+                      clientData\fR)
 .sp
 \fBTcl_ClassSetConstructor\fR(\fIinterp, class, method\fR)
 .sp
@@ -35,8 +35,13 @@ Tcl_Object
 Tcl_Obj *
 \fBTcl_MethodName\fR(\fImethod\fR)
 .sp
+.VS TIP500
 int
 \fBTcl_MethodIsPublic\fR(\fImethod\fR)
+.VE TIP500
+.sp
+int
+\fBTcl_MethodIsPrivate\fR(\fImethod\fR)
 .sp
 int
 \fBTcl_MethodIsType\fR(\fImethod, methodTypePtr, clientDataPtr\fR)
@@ -66,10 +71,15 @@ The class to create the method in.
 .AP Tcl_Obj *nameObj in
 The name of the method to create. Should not be NULL unless creating
 constructors or destructors.
-.AP int isPublic in
-A flag saying what the visibility of the method is. The only supported public
-values of this flag are 0 for a non-exported method, and 1 for an exported
-method.
+.AP int flags in
+A flag saying (currently) what the visibility of the method is. The supported
+public values of this flag are \fBTCL_OO_METHOD_PUBLIC\fR (which is fixed at 1
+for backward compatibility) for an exported method,
+\fBTCL_OO_METHOD_UNEXPORTED\fR (which is fixed at 0 for backward
+compatibility) for a non-exported method,
+.VS TIP500
+and \fBTCL_OO_METHOD_PRIVATE\fR for a private method.
+.VE TIP500
 .AP Tcl_MethodType *methodTypePtr in
 A description of the type of the method to create, or the type of method to
 compare against.
@@ -105,8 +115,12 @@ Given a method, the entity that declared it can be found using
 attached to (or NULL if the method is not attached to any class) and
 \fBTcl_MethodDeclarerObject\fR which returns the object that the method is
 attached to (or NULL if the method is not attached to an object). The name of
-the method can be retrieved with \fBTcl_MethodName\fR and whether the method
-is exported is retrieved with \fBTcl_MethodIsPublic\fR. The type of the method
+the method can be retrieved with \fBTcl_MethodName\fR, whether the method
+is exported is retrieved with \fBTcl_MethodIsPublic\fR,
+.VS TIP500
+and whether the method is private is retrieved with \fBTcl_MethodIsPrivate\fR.
+.VE TIP500
+The type of the method
 can also be introspected upon to a limited degree; the function
 \fBTcl_MethodIsType\fR returns whether a method is of a particular type,
 assigning the per-method \fIclientData\fR to the variable pointed to by
@@ -117,8 +131,12 @@ Methods are created by \fBTcl_NewMethod\fR and \fBTcl_NewInstanceMethod\fR,
 which
 create a method attached to a class or an object respectively. In both cases,
 the \fInameObj\fR argument gives the name of the method to create, the
-\fIisPublic\fR argument states whether the method should be exported
-initially, the \fImethodTypePtr\fR argument describes the implementation of
+\fIflags\fR argument states whether the method should be exported
+initially
+.VS TIP500
+or be marked as a private method,
+.VE TIP500
+the \fImethodTypePtr\fR argument describes the implementation of
 the method (see the \fBMETHOD TYPES\fR section below) and the \fIclientData\fR
 argument gives some implementation-specific data that is passed on to the
 implementation of the method when it is called.
@@ -240,8 +258,32 @@ also return TCL_ERROR; it should return TCL_OK otherwise.
 The \fIoldClientData\fR field to a Tcl_CloneProc gives the value from the
 method being copied from, and the \fInewClientDataPtr\fR field will point to
 a variable in which to write the value for the method being copied to.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+The \fInameObj\fR argument to \fBTcl_NewMethod\fR and
+\fBTcl_NewInstanceMethod\fR (when non-NULL) will have its reference count
+incremented if there is no existing method with that name in that
+class/object.
+.PP
+The result of \fBTcl_MethodName\fR is a value with a reference count of at
+least one. It should not be modified without first duplicating it (with
+\fBTcl_DuplicateObj\fR).
+.PP
+The values in the first \fIobjc\fR values of the \fIobjv\fR argument to
+\fBTcl_ObjectContextInvokeNext\fR are assumed to have a reference count of at
+least 1; the containing array is assumed to endure until the next method
+implementation (see \fBnext\fR) returns. Be aware that methods may
+\fByield\fR; if any post-call actions are desired (e.g., decrementing the
+reference count of values passed in here), they must be scheduled with
+\fBTcl_NRAddCallback\fR.
+.PP
+The \fIcallProc\fR of the \fBTcl_MethodType\fR structure takes values of at
+least reference count 1 in its \fIobjv\fR argument. It may add its own
+references, but must not decrement the reference count below that level; the
+caller of the method will decrement the reference count once the method
+returns properly (and the reference will be held if the method \fByield\fRs).
 .SH "SEE ALSO"
-Class(3), oo::class(n), oo::define(n), oo::object(n)
+Class(3), NRE(3), oo::class(n), oo::define(n), oo::object(n)
 .SH KEYWORDS
 constructor, method, object
 
diff --git a/doc/NRE.3 b/doc/NRE.3
index 28576ba..72bb370 100644
--- a/doc/NRE.3
+++ b/doc/NRE.3
@@ -227,6 +227,25 @@ int
 Any function comprising a routine can push other functions, making it possible
 implement looping and sequencing constructs using the function stack.
 .PP
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+The first \fIobjc\fR values in the \fIobjv\fR array passed to the functions
+\fBTcl_NRCallObjProc\fR, \fBTcl_NREvalObjv\fR, and \fBTcl_NRCmdSwap\fR should
+have a reference count of at least 1; they may have additional references
+taken during the execution.
+.PP
+The \fIobjPtr\fR argument to \fBTcl_NREvalObj\fR and \fBTcl_NRExprObj\fR
+should have a reference count of at least 1, and may have additional
+references taken to it during execution.
+.PP
+The \fIresultObj\fR argument to \fBTcl_NRExprObj\fR should be an unshared
+object.
+.PP
+Use \fBTcl_NRAddCallback\fR to schedule any required final decrementing of the
+reference counts of arguments to any of the other functions on this page, as
+with any other post-processing step in the non-recursive execution engine.
+.PP
+The
 .SH "SEE ALSO"
 Tcl_CreateCommand(3), Tcl_CreateObjCommand(3), Tcl_EvalObjEx(3), Tcl_GetCommandFromObj(3), Tcl_ExprObj(3)
 .SH KEYWORDS
diff --git a/doc/Namespace.3 b/doc/Namespace.3
index a037442..49b772c 100644
--- a/doc/Namespace.3
+++ b/doc/Namespace.3
@@ -46,10 +46,10 @@ Tcl_Command
 \fBTcl_FindCommand\fR(\fIinterp, name, contextNsPtr, flags\fR)
 .sp
 Tcl_Obj *
-\fBTcl_GetNamespaceUnknownHandler(\fIinterp, nsPtr\fR)
+\fBTcl_GetNamespaceUnknownHandler\fR(\fIinterp, nsPtr\fR)
 .sp
 int
-\fBTcl_SetNamespaceUnknownHandler(\fIinterp, nsPtr, handlerPtr\fR)
+\fBTcl_SetNamespaceUnknownHandler\fR(\fIinterp, nsPtr, handlerPtr\fR)
 .SH ARGUMENTS
 .AS Tcl_NamespaceDeleteProc allowOverwrite in/out
 .AP Tcl_Interp *interp in/out
@@ -159,6 +159,18 @@ for the namespace, or NULL if none is set.
 \fBTcl_SetNamespaceUnknownHandler\fR sets the unknown command handler for
 the namespace. If \fIhandlerPtr\fR is NULL, then the handler is reset to
 its default.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+The \fIobjPtr\fR argument to \fBTcl_AppendExportList\fR should be an
+unshared object, as it will be modified by this function. The
+reference count of \fIobjPtr\fR will not be altered.
+.PP
+\fBTcl_GetNamespaceUnknownHandler\fR returns a possibly shared value.
+Its reference count should be incremented if the value is to be
+retained.
+.PP
+The \fIhandlerPtr\fR argument to \fBTcl_SetNamespaceUnknownHandler\fR
+will have its reference count incremented if it is a non-empty list.
 .SH "SEE ALSO"
 Tcl_CreateCommand(3), Tcl_ListObjAppendList(3), Tcl_SetVar(3)
 .SH KEYWORDS
diff --git a/doc/Notifier.3 b/doc/Notifier.3
index 16f9f8d..ec9f910 100644
--- a/doc/Notifier.3
+++ b/doc/Notifier.3
@@ -132,22 +132,17 @@ higher-level software that they have occurred.  The procedures
 and \fBTcl_SetMaxBlockTime\fR, \fBTcl_QueueEvent\fR, and
 \fBTcl_DeleteEvents\fR are used primarily by event sources.
 .IP [2]
-The event queue: for non-threaded applications,
-there is a single queue for the whole application,
-containing events that have been detected but not yet serviced.  Event
-sources place events onto the queue so that they may be processed in
-order at appropriate times during the event loop. The event queue
-guarantees a fair discipline of event handling, so that no event
-source can starve the others.  It also allows events to be saved for
-servicing at a future time.  Threaded applications work in a
-similar manner, except that there is a separate event queue for
-each thread containing a Tcl interpreter.
+The event queue: there is a single queue for each thread containing
+a Tcl interpreter, containing events that have been detected but not
+yet serviced.  Event sources place events onto the queue so that they
+may be processed in order at appropriate times during the event loop.
+The event queue guarantees a fair discipline of event handling, so that
+no event source can starve the others.  It also allows events to be
+saved for servicing at a future time.
 \fBTcl_QueueEvent\fR is used (primarily
-by event sources) to add events to the event queue and
+by event sources) to add events to the current thread's event queue and
 \fBTcl_DeleteEvents\fR is used to remove events from the queue without
-processing them.  In a threaded application, \fBTcl_QueueEvent\fR adds
-an event to the current thread's queue, and \fBTcl_ThreadQueueEvent\fR
-adds an event to a queue in a specific thread.
+processing them.
 .IP [3]
 The event loop: in order to detect and process events, the application
 enters a loop that waits for events to occur, places them on the event
@@ -403,11 +398,7 @@ the event source (using \fBTcl_Alloc\fR or the Tcl macro \fBckalloc\fR)
 before calling \fBTcl_QueueEvent\fR, but it
 will be freed by \fBTcl_ServiceEvent\fR, not by the event source.
 .PP
-Threaded applications work in a
-similar manner, except that there is a separate event queue for
-each thread containing a Tcl interpreter.
-Calling \fBTcl_QueueEvent\fR in a multithreaded application adds
-an event to the current thread's queue.
+Calling \fBTcl_QueueEvent\fR adds an event to the current thread's queue.
 To add an event to another thread's queue, use \fBTcl_ThreadQueueEvent\fR.
 \fBTcl_ThreadQueueEvent\fR accepts as an argument a Tcl_ThreadId argument,
 which uniquely identifies a thread in a Tcl application.  To obtain the
@@ -498,8 +489,7 @@ under Unix it happens when \fBTcl_WaitForEvent\fR would have waited
 forever because there were no active event sources and the timeout was
 infinite.
 .PP
-\fBTcl_AlertNotifier\fR is used in multithreaded applications to allow
-any thread to
+\fBTcl_AlertNotifier\fR is used to allow any thread to
 .QW "wake up"
 the notifier to alert it to new events on its
 queue.  \fBTcl_AlertNotifier\fR requires as an argument the notifier
diff --git a/doc/Object.3 b/doc/Object.3
index eadd041..2099552 100644
--- a/doc/Object.3
+++ b/doc/Object.3
@@ -283,7 +283,12 @@ to reduce storage requirements.
 Reference counting is used to determine when a value is
 no longer needed and can safely be freed.
 A value just created by \fBTcl_NewObj\fR or \fBTcl_NewStringObj\fR
-has \fIrefCount\fR 0.
+has \fIrefCount\fR 0, meaning that the object can often be given to a function
+like \fBTcl_SetObjResult\fR, \fBTcl_ListObjAppendElement\fR, or
+\fBTcl_DictObjPut\fR (as a value) without explicit reference management, all
+of which are common use cases. (The latter two require that the the target
+list or dictionary be well-formed, but that is often easy to arrange when the
+value is being initially constructed.)
 The macro \fBTcl_IncrRefCount\fR increments the reference count
 when a new reference to the value is created.
 The macro \fBTcl_DecrRefCount\fR decrements the count
diff --git a/doc/ObjectType.3 b/doc/ObjectType.3
index 67f5174..7e3cc12 100644
--- a/doc/ObjectType.3
+++ b/doc/ObjectType.3
@@ -248,6 +248,28 @@ The \fIfreeIntRepProc\fR implementation must not access the
 uses of that field during value deletion.  The defined tasks for
 the \fIfreeIntRepProc\fR have no need to consult the \fIbytes\fR
 member.
+.PP
+Note that if a subsidiary value has its reference count reduced to zero
+during the running of a \fIfreeIntRepProc\fR, that value may be not freed
+immediately, in order to limit stack usage. However, the value will be freed
+before the outermost current \fBTcl_DecrRefCount\fR returns.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+The \fIobjPtr\fR argument to \fBTcl_AppendAllObjTypes\fR should be an unshared
+value; this function will not modify the reference count of that value, but
+will modify its contents. If \fIobjPtr\fR is not (interpretable as) a list,
+this function will set the interpreter result and produce an error; using an
+unshared empty value is strongly recommended.
+.PP
+The \fIobjPtr\fR argument to \fBTcl_ConvertToType\fR can have any non-zero
+reference count; this function will not modify the reference count, but may
+write to the interpreter result on error so values that originate from there
+should have an additional reference made before calling this.
+.PP
+None of the callback functions in the \fBTcl_ObjType\fR structure should
+modify the reference count of their arguments, but if the values contain
+subsidiary values (e.g., the elements of a list or the keys of a dictionary)
+then those subsidiary values may have their reference counts modified.
 .SH "SEE ALSO"
 Tcl_NewObj(3), Tcl_DecrRefCount(3), Tcl_IncrRefCount(3)
 .SH KEYWORDS
diff --git a/doc/OpenFileChnl.3 b/doc/OpenFileChnl.3
index 82851da..4e42b93 100644
--- a/doc/OpenFileChnl.3
+++ b/doc/OpenFileChnl.3
@@ -92,10 +92,10 @@ int
 int
 \fBTcl_OutputBuffered\fR(\fIchannel\fR)
 .sp
-Tcl_WideInt
+long long
 \fBTcl_Seek\fR(\fIchannel, offset, seekMode\fR)
 .sp
-Tcl_WideInt
+long long
 \fBTcl_Tell\fR(\fIchannel\fR)
 .sp
 int
@@ -190,7 +190,7 @@ A buffer containing the bytes to output to the channel.
 .AP int bytesToWrite in
 The number of bytes to consume from \fIcharBuf\fR or \fIbyteBuf\fR and
 output to the channel.
-.AP Tcl_WideInt offset in
+.AP "long long" offset in
 How far to move the access point in the channel at which the next input or
 output operation will be applied, measured in bytes from the position
 given by \fIseekMode\fR.  May be either positive or negative.
@@ -198,7 +198,7 @@ given by \fIseekMode\fR.  May be either positive or negative.
 Relative to which point to seek; used with \fIoffset\fR to calculate the new
 access point for the channel. Legal values are \fBSEEK_SET\fR,
 \fBSEEK_CUR\fR, and \fBSEEK_END\fR.
-.AP Tcl_WideInt length in
+.AP "long long" length in
 The (non-negative) length to truncate the channel the channel to.
 .AP "const char" *optionName in
 The name of an option applicable to this channel, such as \fB\-blocking\fR.
@@ -641,6 +641,24 @@ the channel was created with \fBTcl_OpenFileChannel\fR,
 \fBTcl_OpenCommandChannel\fR, or \fBTcl_MakeFileChannel\fR.  Other
 channel types may return a different type of handle on Windows
 platforms.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+The \fIreadObjPtr\fR argument to \fBTcl_ReadChars\fR must be an unshared
+value; it will be modified by this function.  Using the interpreter result for
+this purpose is \fIstrongly\fR not recommended; the preferred pattern is to
+use a new value from \fBTcl_NewObj\fR to receive the data and only to pass it
+to \fBTcl_SetObjResult\fR if this function succeeds.
+.PP
+The \fIlineObjPtr\fR argument to \fBTcl_GetsObj\fR must be an unshared value;
+it will be modified by this function.  Using the interpreter result for this
+purpose is \fIstrongly\fR not recommended; the preferred pattern is to use a
+new value from \fBTcl_NewObj\fR to receive the data and only to pass it to
+\fBTcl_SetObjResult\fR if this function succeeds.
+.PP
+The \fIwriteObjPtr\fR argument to \fBTcl_WriteObj\fR should be a value with
+any reference count. This function will not modify the reference count. Using
+the interpreter result without adding an additional reference to it is not
+recommended.
 .SH "SEE ALSO"
 DString(3), fconfigure(n), filename(n), fopen(3), Tcl_CreateChannel(3)
 .SH KEYWORDS
diff --git a/doc/OpenTcp.3 b/doc/OpenTcp.3
index 4a7dc1e..5b941dc 100644
--- a/doc/OpenTcp.3
+++ b/doc/OpenTcp.3
@@ -4,12 +4,12 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-.TH Tcl_OpenTcpClient 3 8.0 Tcl "Tcl Library Procedures"
+.TH Tcl_OpenTcpClient 3 8.7 Tcl "Tcl Library Procedures"
 .so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-Tcl_OpenTcpClient, Tcl_MakeTcpClientChannel, Tcl_OpenTcpServer \- procedures to open channels using TCP sockets
+Tcl_OpenTcpClient, Tcl_MakeTcpClientChannel, Tcl_OpenTcpServer, Tcl_OpenTcpServerEx \- procedures to open channels using TCP sockets
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h> \fR
@@ -23,6 +23,9 @@ Tcl_Channel
 Tcl_Channel
 \fBTcl_OpenTcpServer\fR(\fIinterp, port, myaddr, proc, clientData\fR)
 .sp
+Tcl_Channel
+\fBTcl_OpenTcpServerEx\fR(\fIinterp, service, myaddr, flags, proc, clientData\fR)
+.sp
 .SH ARGUMENTS
 .AS Tcl_TcpAcceptProc clientData
 .AP Tcl_Interp *interp in
@@ -30,6 +33,9 @@ Tcl interpreter to use for error reporting.  If non-NULL and an
 error occurs, an error message is left in the interpreter's result.
 .AP int port in
 A port number to connect to as a client or to listen on as a server.
+.AP "const char" *service in
+A string specifying the port number to connect to as a client or to listen on as
+ a server.
 .AP "const char" *host in
 A string specifying a host name or address for the remote end of the connection.
 .AP int myport in
@@ -41,6 +47,9 @@ for the local end of the connection.  If NULL, a default interface is
 chosen.
 .AP int async in
 If nonzero, the client socket is connected asynchronously to the server.
+.AP "unsigned int" flags in
+ORed combination of \fBTCL_TCPSERVER\fR flags that specify additional
+informations about the socket being created.
 .AP ClientData sock in
 Platform-specific handle for client TCP socket.
 .AP Tcl_TcpAcceptProc *proc in
@@ -158,6 +167,11 @@ register it, use \fBTcl_RegisterChannel\fR.
 If one of the standard channels, \fBstdin\fR, \fBstdout\fR or \fBstderr\fR was
 previously closed, the act of creating the new channel also assigns it as a
 replacement for the standard channel.
+.SS TCL_OPENTCPSERVEREX
+.PP
+\fBTcl_OpenTcpServerEx\fR behaviour is identical to \fBTcl_OpenTcpServer\fR but
+gives more flexibility to the user by providing a mean to further customize some
+aspects of the socket via the \fIflags\fR parameter.
 .SH "PLATFORM ISSUES"
 .PP
 On Unix platforms, the socket handle is a Unix file descriptor as
diff --git a/doc/Panic.3 b/doc/Panic.3
index 5f4763f..53b84da 100644
--- a/doc/Panic.3
+++ b/doc/Panic.3
@@ -7,7 +7,7 @@
 .BS
 '\"  Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-Tcl_Panic, Tcl_PanicVA, Tcl_SetPanicProc \- report fatal error and abort
+Tcl_Panic, Tcl_PanicVA, Tcl_SetPanicProc, Tcl_ConsolePanic \- report fatal error and abort
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -21,6 +21,9 @@ void
 void
 \fBTcl_SetPanicProc\fR(\fIpanicProc\fR)
 .sp
+void
+\fBTcl_ConsolePanic\fR(\fIformat\fR, \fIarg\fR, \fIarg\fR, \fI...\fR)
+.sp
 .SH ARGUMENTS
 .AS Tcl_PanicProc *panicProc
 .AP "const char*" format in
@@ -54,6 +57,14 @@ message is sent to the debugger instead. If the windows executable
 does not have a stderr channel (e.g. \fBwish.exe\fR), then a
 system dialog box is used to display the panic message.
 .PP
+If your application doesn't use \fBTcl_Main\fR or \fBTk_Main\fR
+and you want to implicitly use the stderr channel of your
+application's C runtime (instead of the stderr channel of the
+C runtime used by Tcl), you can call \fBTcl_SetPanicProc\fR
+with \fBTcl_ConsolePanic\fR as its argument. On platforms which
+only have one C runtime (almost all platforms except Windows)
+\fBTcl_ConsolePanic\fR is equivalent to NULL.
+.PP
 \fBTcl_SetPanicProc\fR may be used to modify the behavior of
 \fBTcl_Panic\fR.  The \fIpanicProc\fR argument should match the
 type \fBTcl_PanicProc\fR:
@@ -75,6 +86,9 @@ The typical use of \fBTcl_SetPanicProc\fR arranges for the error message
 to be displayed or reported in a manner more suitable for the
 application or the platform.
 .PP
+\fBTcl_SetPanicProc\fR can not be used in stub-enabled extensions. Its symbol
+entry in the stub table is deprecated and it will be removed in Tcl 9.0.
+.PP
 Although the primary callers of \fBTcl_Panic\fR are the procedures of
 the Tcl library, \fBTcl_Panic\fR is a public function and may be called
 by any extension or application that wishes to abort the process and
@@ -82,7 +96,9 @@ have a panic message displayed the same way that panic messages from Tcl
 will be displayed.
 .PP
 \fBTcl_PanicVA\fR is the same as \fBTcl_Panic\fR except that instead of
-taking a variable number of arguments it takes an argument list.
+taking a variable number of arguments it takes an argument list. Interfaces
+using argument lists have been found to be nonportable in practice. This
+function is deprecated and will be removed in Tcl 9.0.
 .SH "SEE ALSO"
 abort(3), printf(3), exec(n), format(n)
 .SH KEYWORDS
diff --git a/doc/ParseArgs.3 b/doc/ParseArgs.3
index def55de..f29f161 100644
--- a/doc/ParseArgs.3
+++ b/doc/ParseArgs.3
@@ -189,6 +189,12 @@ will be stored at \fIdstPtr\fR; the string inside will have a lifetime linked
 to the lifetime of the string representation of the argument value that it
 came from, and so should be copied if it needs to be retained. The
 \fIsrcPtr\fR and \fIclientData\fR fields are ignored.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+The values in the \fIobjv\fR argument to \fBTcl_ParseArgsObjv\fR will not have
+their reference counts modified by this function. The interpreter result may
+be modified on error; the values passed should not be the interpreter result
+with no further reference added.
 .SH "SEE ALSO"
 Tcl_GetIndexFromObj(3), Tcl_Main(3), Tcl_CreateObjCommand(3)
 .SH KEYWORDS
diff --git a/doc/ParseCmd.3 b/doc/ParseCmd.3
author	Benjamin Peterson <benjamin@python.org>	2009-05-12 21:21:26 (GMT)
committer	Benjamin Peterson <benjamin@python.org>	2009-05-12 21:21:26 (GMT)
commit	976faf9293aa1dd291ccd95465647f09004a52af (patch)
tree	a9e4f80a669fac50702f23b4f1670ecbc1b81c3b /Lib/distutils/command
parent	12f29ffb9f02dd23e11d7f9a54f0c5891c15ff5d (diff)
download	cpython-976faf9293aa1dd291ccd95465647f09004a52af.zip cpython-976faf9293aa1dd291ccd95465647f09004a52af.tar.gz cpython-976faf9293aa1dd291ccd95465647f09004a52af.tar.bz2