Merged core-8-branch

Bypass reader thread for blocking reads.
Merge 8.6
2022-07-10 13:56:38 +00:00 · 2022-07-10 10:21:06 +00:00 · 2022-07-07 11:01:39 +00:00 · 2022-07-07 10:59:46 +00:00 · 2022-07-05 15:54:00 +00:00 · 2022-07-05 12:18:17 +00:00
363 changed files with 23692 additions and 11353 deletions
@@ -24,7 +24,8 @@
 */versions.vc
 */version.vc
 */libtcl.vfs
-*/libtcl_*.zip
+*/libtcl*.zip
+*/tclUuid.h
 html
 libtommath/bn.ilg
 libtommath/bn.ind
@@ -1,5 +1,7 @@
 name: Linux
 on: [push]
+permissions:
+  contents: read
 jobs:
  gcc:
    runs-on: ubuntu-20.04
@@ -19,7 +21,7 @@ jobs:
        working-directory: unix
    steps:
      - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
      - name: Prepare
        run: |
          touch tclStubInit.c tclOOStubInit.c tclOOScript.h
@@ -1,5 +1,7 @@
 name: macOS
 on: [push]
+permissions:
+  contents: read
 jobs:
  xcode:
    runs-on: macos-11
@@ -9,7 +11,7 @@ jobs:
        working-directory: macosx
    steps:
      - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
      - name: Prepare
        run: |
          touch tclStubInit.c tclOOStubInit.c tclOOScript.h
@@ -39,7 +41,7 @@ jobs:
        working-directory: unix
    steps:
      - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
      - name: Prepare
        run: |
          touch tclStubInit.c tclOOStubInit.c tclOOScript.h
@@ -1,5 +1,7 @@
 name: Build Binaries
 on: [push]
+permissions:
+  contents: read
 jobs:
  linux:
    name: Linux
@@ -9,7 +11,7 @@ jobs:
        shell: bash
    steps:
      - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
      - name: Prepare
        run: |
          touch generic/tclStubInit.c generic/tclOOStubInit.c
@@ -32,7 +34,7 @@ jobs:
          tar -cf tclsh${TCL_PATCHLEVEL}_snapshot.tar tclsh${TCL_PATCHLEVEL}_snapshot
        working-directory: 1dist
      - name: Upload
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v3
        with:
          name: Tclsh ${{ env.TCL_PATCHLEVEL }} Linux single-file build (snapshot)
          path: 1dist/*.tar
@@ -44,9 +46,9 @@ jobs:
        shell: bash
    steps:
      - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
      - name: Checkout create-dmg
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
        with:
          repository: create-dmg/create-dmg
          ref: v1.0.8
@@ -94,7 +96,7 @@ jobs:
              "contents/"
        working-directory: 1dist
      - name: Upload
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v3
        with:
          name: Tclsh ${{ env.TCL_PATCHLEVEL }} macOS single-file build (snapshot)
          path: 1dist/*.dmg
@@ -114,7 +116,7 @@ jobs:
          msystem: UCRT64
          install: git mingw-w64-ucrt-x86_64-toolchain make zip
      - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
      - name: Prepare
        run: |
          touch generic/tclStubInit.c generic/tclOOStubInit.c
@@ -138,7 +140,7 @@ jobs:
          cp ../win/tclsh*.exe tclsh${TCL_PATCHLEVEL}_snapshot.exe
        working-directory: 1dist
      - name: Upload
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v3
        with:
          name: Tclsh ${{ env.TCL_PATCHLEVEL }} Windows single-file build (snapshot)
          path: '1dist/*_snapshot.exe'
@@ -1,5 +1,7 @@
 name: Windows
 on: [push]
+permissions:
+  contents: read
 env:
  ERROR_ON_FAILURES: 1
 jobs:
@@ -21,7 +23,7 @@ jobs:
    # Using powershell means we need to explicitly stop on failure
    steps:
      - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
      - name: Init MSVC
        uses: ilammy/msvc-dev-cmd@v1
      - name: Build ${{ matrix.cfgopt }}
@@ -66,7 +68,7 @@ jobs:
          msystem: MINGW64
          install: git mingw-w64-x86_64-toolchain make
      - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
      - name: Prepare
        run: |
          touch tclStubInit.c tclOOStubInit.c tclOOScript.h
@@ -30,7 +30,8 @@ _FOSSIL_
 */versions.vc
 */version.vc
 */libtcl.vfs
-*/libtcl_*.zip
+*/libtcl*.zip
+*/tclUuid.h
 libtommath/bn.ilg
 libtommath/bn.ind
 libtommath/pretty.build
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <projectDescription>
-	<name>tcl9</name>
+	<name>tcl8</name>
 	<comment></comment>
 	<projects>
 	</projects>
@@ -20,13 +20,13 @@ jobs:
      compiler: gcc
      env:
        - BUILD_DIR=unix
-    - name: "Linux/GCC/Shared: UTF_MAX=3"
+    - name: "Linux/GCC/Shared: UTF_MAX=4"
      os: linux
      dist: focal
      compiler: gcc
      env:
        - BUILD_DIR=unix
-        - CFGOPT="CFLAGS=-DTCL_UTF_MAX=3"
+        - CFGOPT=CFLAGS=-DTCL_UTF_MAX=4
    - name: "Linux/GCC/Shared: NO_DEPRECATED"
      os: linux
      dist: focal
@@ -83,6 +83,13 @@ jobs:
      compiler: clang
      env:
        - BUILD_DIR=unix
+    - name: "Linux/Clang/Shared:NO_DEPRECATED"
+      os: linux
+      dist: xenial
+      compiler: clang
+      env:
+        - BUILD_DIR=unix
+        - CFGOPT="CFLAGS=-DTCL_NO_DEPRECATED=1"
    - name: "Linux/Clang/Static"
      os: linux
      dist: focal
@@ -208,6 +215,15 @@ jobs:
      script:
        - cmd.exe //C vcvarsall.bat x64 '&&' nmake '-f' makefile.vc all tcltest
        - cmd.exe //C vcvarsall.bat x64 '&&' nmake '-f' makefile.vc test
+    - name: "Windows/MSVC/Shared: UTF_MAX=4"
+      os: windows
+      compiler: cl
+      env: *vcenv
+      before_install: *vcpreinst
+      install: []
+      script:
+        - cmd.exe //C vcvarsall.bat x64 '&&' nmake 'OPTS=utf16' '-f' makefile.vc all tcltest
+        - cmd.exe //C vcvarsall.bat x64 '&&' nmake 'OPTS=utf16' '-f' makefile.vc test
    - name: "Windows/MSVC/Shared: NO_DEPRECATED"
      os: windows
      compiler: cl
@@ -254,6 +270,15 @@ jobs:
      script:
        - cmd.exe //C vcvarsall.bat x86 '&&' nmake '-f' makefile.vc all tcltest
        - cmd.exe //C vcvarsall.bat x86 '&&' nmake '-f' makefile.vc test
+    - name: "Windows/MSVC-x86/Shared: UTF_MAX=4"
+      os: windows
+      compiler: cl
+      env: *vcenv
+      before_install: *vcpreinst
+      install: []
+      script:
+        - cmd.exe //C vcvarsall.bat x86 '&&' nmake 'OPTS=utf16' '-f' makefile.vc all tcltest
+        - cmd.exe //C vcvarsall.bat x86 '&&' nmake 'OPTS=utf16' '-f' makefile.vc test
    - name: "Windows/MSVC-x86/Shared: NO_DEPRECATED"
      os: windows
      compiler: cl
@@ -301,12 +326,12 @@ jobs:
        - touch generic/tclStubInit.c generic/tclOOStubInit.c generic/tclOOScript.h
        - choco install -y make zip
        - cd ${BUILD_DIR}
-    - name: "Windows/GCC/Shared: UTF_MAX=3"
+    - name: "Windows/GCC/Shared: UTF_MAX=4"
      os: windows
      compiler: gcc
      env:
        - BUILD_DIR=win
-        - CFGOPT="--enable-64bit CFLAGS=-DTCL_UTF_MAX=3"
+        - CFGOPT="--enable-64bit CFLAGS=-DTCL_UTF_MAX=4"
      before_install: *makepreinst
    - name: "Windows/GCC/Shared: NO_DEPRECATED"
      os: windows
@@ -343,12 +368,12 @@ jobs:
      env:
        - BUILD_DIR=win
      before_install: *makepreinst
-    - name: "Windows/GCC-x86/Shared: UTF_MAX=3"
+    - name: "Windows/GCC-x86/Shared: UTF_MAX=4"
      os: windows
      compiler: gcc
      env:
        - BUILD_DIR=win
-        - CFGOPT="CFLAGS=-DTCL_UTF_MAX=3"
+        - CFGOPT="CFLAGS=-DTCL_UTF_MAX=4"
      before_install: *makepreinst
    - name: "Windows/GCC-x86/Shared: NO_DEPRECATED"
      os: windows
@@ -1,24 +1,13 @@
 # README:  Tcl

-This is the **Tcl 9.0a4** source distribution.
+This is the **Tcl 8.7a6** source distribution.

 You can get any source release of Tcl from [our distribution
 site](https://sourceforge.net/projects/tcl/files/Tcl/).

-8.6 (production release, daily build)
-[![Build Status](https://github.com/tcltk/tcl/workflows/Linux/badge.svg?branch=core-8-6-branch)](https://github.com/tcltk/tcl/actions?query=workflow%3A%22Linux%22+branch%3Acore-8-6-branch)
-[![Build Status](https://github.com/tcltk/tcl/workflows/Windows/badge.svg?branch=core-8-6-branch)](https://github.com/tcltk/tcl/actions?query=workflow%3A%22Windows%22+branch%3Acore-8-6-branch)
-[![Build Status](https://github.com/tcltk/tcl/workflows/macOS/badge.svg?branch=core-8-6-branch)](https://github.com/tcltk/tcl/actions?query=workflow%3A%22macOS%22+branch%3Acore-8-6-branch)
-<br>
-8.7 (in development, daily build))
 [![Build Status](https://github.com/tcltk/tcl/workflows/Linux/badge.svg?branch=core-8-branch)](https://github.com/tcltk/tcl/actions?query=workflow%3A%22Linux%22+branch%3Acore-8-branch)
 [![Build Status](https://github.com/tcltk/tcl/workflows/Windows/badge.svg?branch=core-8-branch)](https://github.com/tcltk/tcl/actions?query=workflow%3A%22Windows%22+branch%3Acore-8-branch)
 [![Build Status](https://github.com/tcltk/tcl/workflows/macOS/badge.svg?branch=core-8-branch)](https://github.com/tcltk/tcl/actions?query=workflow%3A%22macOS%22+branch%3Acore-8-branch)
-<br>
-9.0 (in development, daily build))
-[![Build Status](https://github.com/tcltk/tcl/workflows/Linux/badge.svg?branch=main)](https://github.com/tcltk/tcl/actions?query=workflow%3A%22Linux%22+branch%3Amain)
-[![Build Status](https://github.com/tcltk/tcl/workflows/Windows/badge.svg?branch=main)](https://github.com/tcltk/tcl/actions?query=workflow%3A%22Windows%22+branch%3Amain)
-[![Build Status](https://github.com/tcltk/tcl/workflows/macOS/badge.svg?branch=main)](https://github.com/tcltk/tcl/actions?query=workflow%3A%22macOS%22+branch%3Amain)

 ## Contents
 1. [Introduction](#intro)
@@ -56,7 +45,7 @@ and selling it either in whole or in part.  See the file
 ## <a id="doc">2.</a> Documentation
 Extensive documentation is available on our website.
 The home page for this release, including new features, is
-[here](https://www.tcl-lang.org/software/tcltk/9.0.html).
+[here](https://www.tcl-lang.org/software/tcltk/8.7.html).
 Detailed release notes can be found at the
 [file distributions page](https://sourceforge.net/projects/tcl/files/Tcl/)
 by clicking on the relevant version.
@@ -66,8 +55,8 @@ Xchange](https://www.tcl-lang.org/about/).
 There have been many Tcl books on the market.  Many are mentioned in
 [the Wiki](https://wiki.tcl-lang.org/_/ref?N=25206).

-The complete set of reference manual entries for Tcl 9.0 is [online,
-here](https://www.tcl-lang.org/man/tcl9.0/).
+The complete set of reference manual entries for Tcl 8.7 is [online,
+here](https://www.tcl-lang.org/man/tcl8.7/).

 ### <a id="doc.unix">2a.</a> Unix Documentation
 The `doc` subdirectory in this release contains a complete set of
@@ -9127,26 +9127,6 @@ in this changeset (new minor version) rather than bug fixes:

 - Released 8.7a3, Nov 21, 2019 --- https://core.tcl-lang.org/tcl/ for details -

-Changes to 9.0a1 include all changes to the 8.7 line through 8.7a3,
-plus the following, which focuses on the high-level feature changes
-in this changeset (new minor version) rather than bug fixes:
-
-2017-11-03 [TIP 114] Leading zero integer no longer means octal
-
-2017-11-03 [TIP 278] Revise variable name resolution, solve "Creative Writing"
-
-2017-11-03 [TIPs 330,336] Encapsulate struct Tcl_Interp
-
-2017-11-17 [TIP 422] Remove all Tcl_*VA() routines
-
-2017-12-15 [TIP 488] Disable magic $::tcl_precision
-
-2018-10-08 [TIP 494] Increased support for size_t value ranges
-
-2019-05-31 [TIP 537] 64-bit indices in regexp matching
-
- Released 9.0a1, Nov 25, 2019 --- https://core.tcl-lang.org/tcl/ for details -
-
 2019-12-03 (bug)[3cd9be] Corner case in surrogate handling (nijtmans)

 2019-12-09 (new) Add tcltest::(Setup|Eval|Cleanup|)Test (coulter,sebres)
@@ -9354,24 +9334,6 @@ in this changeset (new minor version) rather than bug fixes:

 - Released 8.7a5, Jun 18, 2021 --- https://core.tcl-lang.org/tcl/ for details -

-Changes to 9.0a3 include all changes to the 8.7 line through 8.7a5,
-plus the following, which focuses on the high-level feature changes
-in this changeset (new major version) rather than bug fixes:
-
-Many of the TIPs in Tcl 8.7 mentioned above are extended further in 9.0
-
-2020-02-28 [TIP 497] Full support for Unicode planes 1-16
-
-2020-08-21 (bug)[43b434] improper calls to stat64()
-
-2021-04-08 [TIP 595] Unicode-aware loadable library handling.
-
-2021-04-30 [TIP 596] Stubs support for embedding Tcl in apps
-
-Many internal changes to broaden support for sizes beyond 32-bits.
-
- Released 9.0a3, Jun 23, 2021 --- https://core.tcl-lang.org/tcl/ for details -
-
 2021-02-02 (new) support for MacOS Big Sur updates (nijtmans)
 => platform 1.0.17

@@ -28,7 +28,7 @@ opendir(
    if ((fd = open(myname, 0, 0)) == -1) {
 	return NULL;
    }
-    dirp = (DIR *) Tcl_Alloc(sizeof(DIR));
+    dirp = (DIR *) ckalloc(sizeof(DIR));
    if (dirp == NULL) {
 	/* unreachable? */
 	close(fd);
@@ -106,5 +106,5 @@ closedir(
    close(dirp->dd_fd);
    dirp->dd_fd = -1;
    dirp->dd_loc = 0;
-    Tcl_Free(dirp);
+    ckfree(dirp);
 }
@@ -100,7 +100,7 @@ waitpid(
 	} else {
 	    prevPtr->nextPtr = waitPtr->nextPtr;
 	}
-	Tcl_Free(waitPtr);
+	ckfree(waitPtr);
 	return result;
    }

@@ -156,7 +156,7 @@ waitpid(
 		goto waitAgain;
 	    }
 	}
-	waitPtr = (WaitInfo *) Tcl_Alloc(sizeof(WaitInfo));
+	waitPtr = (WaitInfo *) ckalloc(sizeof(WaitInfo));
 	waitPtr->pid = result;
 	waitPtr->status = status;
 	waitPtr->nextPtr = deadList;
@@ -174,7 +174,10 @@ if test -z "$CC"; then
  else
    cc=${CROSS_PREFIX}cc
  fi
+else
+  cc=${CC}
 fi
+
 cflags=${CFLAGS-"-O3"}
 # to force the asm version use: CFLAGS="-O3 -DASMV" ./configure
 case "$cc" in
@@ -64,7 +64,7 @@ unsigned short FAR *work;
    static const unsigned short lext[31] = { /* Length codes 257..285 extra */
        128, 128, 128, 128, 128, 128, 128, 128, 129, 129, 129, 129,
        130, 130, 130, 130, 131, 131, 131, 131, 132, 132, 132, 132,
-        133, 133, 133, 133, 144, 199, 202};
+        133, 133, 133, 133, 144, 76, 202};
    static const unsigned short dbase[32] = { /* Distance codes 0..31 base */
        1, 2, 3, 4, 5, 7, 9, 13, 17, 25, 33, 49,
        65, 97, 129, 193, 257, 385, 513, 769, 1025, 1537, 2049, 3073,
@@ -28,6 +28,11 @@

 // see Include/shared/winapifamily.h in the Windows Kit
 #if defined(WINAPI_FAMILY_PARTITION) && (!(defined(IOWIN32_USING_WINRT_API)))
+
+#if !defined(WINAPI_FAMILY_ONE_PARTITION)
+#define WINAPI_FAMILY_ONE_PARTITION(PartitionSet, Partition) ((WINAPI_FAMILY & PartitionSet) == Partition)
+#endif
+
 #if WINAPI_FAMILY_ONE_PARTITION(WINAPI_FAMILY, WINAPI_PARTITION_APP)
 #define IOWIN32_USING_WINRT_API 1
 #endif
@@ -630,7 +630,7 @@ unsigned long ZEXPORT crc32_z(crc, buf, len)
 #endif /* DYNAMIC_CRC_TABLE */

    /* Pre-condition the CRC */
-    crc ^= 0xffffffff;
+    crc = (~crc) & 0xffffffff;

    /* Compute the CRC up to a word boundary. */
    while (len && ((z_size_t)buf & 7) != 0) {
@@ -749,7 +749,7 @@ unsigned long ZEXPORT crc32_z(crc, buf, len)
 #endif /* DYNAMIC_CRC_TABLE */

    /* Pre-condition the CRC */
-    crc ^= 0xffffffff;
+    crc = (~crc) & 0xffffffff;

 #ifdef W

@@ -1077,7 +1077,7 @@ uLong ZEXPORT crc32_combine64(crc1, crc2, len2)
 #ifdef DYNAMIC_CRC_TABLE
    once(&made, make_crc_table);
 #endif /* DYNAMIC_CRC_TABLE */
-    return multmodp(x2nmodp(len2, 3), crc1) ^ crc2;
+    return multmodp(x2nmodp(len2, 3), crc1) ^ (crc2 & 0xffffffff);
 }

 /* ========================================================================= */
@@ -1112,5 +1112,5 @@ uLong crc32_combine_op(crc1, crc2, op)
    uLong crc2;
    uLong op;
 {
-    return multmodp(op, crc1) ^ crc2;
+    return multmodp(op, crc1) ^ (crc2 & 0xffffffff);
 }
@@ -329,8 +329,8 @@ void ZLIB_INTERNAL _tr_stored_block OF((deflate_state *s, charf *buf,
 # define _tr_tally_dist(s, distance, length, flush) \
  { uch len = (uch)(length); \
    ush dist = (ush)(distance); \
-    s->sym_buf[s->sym_next++] = dist; \
-    s->sym_buf[s->sym_next++] = dist >> 8; \
+    s->sym_buf[s->sym_next++] = (uch)dist; \
+    s->sym_buf[s->sym_next++] = (uch)(dist >> 8); \
    s->sym_buf[s->sym_next++] = len; \
    dist--; \
    s->dyn_ltree[_length_code[len]+LITERALS+1].Freq++; \
@@ -62,7 +62,7 @@ unsigned short FAR *work;
        35, 43, 51, 59, 67, 83, 99, 115, 131, 163, 195, 227, 258, 0, 0};
    static const unsigned short lext[31] = { /* Length codes 257..285 extra */
        16, 16, 16, 16, 16, 16, 16, 16, 17, 17, 17, 17, 18, 18, 18, 18,
-        19, 19, 19, 19, 20, 20, 20, 20, 21, 21, 21, 21, 16, 199, 202};
+        19, 19, 19, 19, 20, 20, 20, 20, 21, 21, 21, 21, 16, 76, 202};
    static const unsigned short dbase[32] = { /* Distance codes 0..29 base */
        1, 2, 3, 4, 5, 7, 9, 13, 17, 25, 33, 49, 65, 97, 129, 193,
        257, 385, 513, 769, 1025, 1537, 2049, 3073, 4097, 6145,
@@ -1017,9 +1017,9 @@ int ZLIB_INTERNAL _tr_tally (s, dist, lc)
    unsigned dist;  /* distance of matched string */
    unsigned lc;    /* match length-MIN_MATCH or unmatched char (if dist==0) */
 {
-    s->sym_buf[s->sym_next++] = dist;
-    s->sym_buf[s->sym_next++] = dist >> 8;
-    s->sym_buf[s->sym_next++] = lc;
+    s->sym_buf[s->sym_next++] = (uch)dist;
+    s->sym_buf[s->sym_next++] = (uch)(dist >> 8);
+    s->sym_buf[s->sym_next++] = (uch)lc;
    if (dist == 0) {
        /* lc is the unmatched char */
        s->dyn_ltree[lc].Freq++;
@@ -9,7 +9,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_GetReturnOptions, Tcl_SetReturnOptions, Tcl_AddErrorInfo, Tcl_AppendObjToErrorInfo, Tcl_AddObjErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tcl_SetErrorLine, Tcl_GetErrorLine, Tcl_PosixError, Tcl_LogCommandInfo \- retrieve or record information about errors and other return options
+Tcl_GetReturnOptions, Tcl_SetReturnOptions, Tcl_AddErrorInfo, Tcl_AppendObjToErrorInfo, Tcl_AddObjErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_SetErrorLine, Tcl_GetErrorLine, Tcl_PosixError, Tcl_LogCommandInfo \- retrieve or record information about errors and other return options
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -30,6 +30,8 @@ int
 .sp
 \fBTcl_SetErrorCode\fR(\fIinterp, element, element, ... \fB(char *) NULL\fR)
 .sp
+\fBTcl_SetErrorCodeVA\fR(\fIinterp, argList\fR)
+.sp
 \fBTcl_GetErrorLine\fR(\fIinterp\fR)
 .sp
 \fBTcl_SetErrorLine\fR(\fIinterp, lineNum\fR)
@@ -58,10 +60,10 @@ unless \fIlength\fR is negative.
 .AP Tcl_Obj *objPtr in
 A message to be appended to the \fB\-errorinfo\fR return option
 in the form of a Tcl_Obj value.
-.AP size_t length in
+.AP int length in
 The number of bytes to copy from \fImessage\fR when
 appending to the \fB\-errorinfo\fR return option.
-If TCL_INDEX_NONE, all bytes up to the first null byte are used.
+If negative, all bytes up to the first null byte are used.
 .AP Tcl_Obj *errorObjPtr in
 The \fB\-errorcode\fR return option will be set to this value.
 .AP "const char" *element in
@@ -242,6 +244,12 @@ The procedure \fBTcl_SetErrorCode\fR is also used to set the
 \fB\-errorcode\fR return option. However, it takes one or more strings to
 record instead of a value. Otherwise, it is similar to
 \fBTcl_SetObjErrorCode\fR in behavior.
+.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
@@ -4,11 +4,11 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-.TH Tcl_Alloc 3 9.0 Tcl "Tcl Library Procedures"
+.TH Tcl_Alloc 3 7.5 Tcl "Tcl Library Procedures"
 .so man.macros
 .BS
 .SH NAME
-Tcl_Alloc, Tcl_Free, Tcl_Realloc, Tcl_AttemptAlloc, Tcl_AttemptRealloc, Tcl_GetMemoryInfo \- allocate or free heap memory
+Tcl_Alloc, Tcl_Free, Tcl_Realloc, Tcl_AttemptAlloc, Tcl_AttemptRealloc, Tcl_GetMemoryInfo, ckalloc, ckfree, ckrealloc, attemptckalloc, attemptckrealloc \- allocate or free heap memory
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -19,17 +19,32 @@ char *
 void
 \fBTcl_Free\fR(\fIptr\fR)
 .sp
-void *
+char *
 \fBTcl_Realloc\fR(\fIptr, size\fR)
 .sp
-void *
+char *
 \fBTcl_AttemptAlloc\fR(\fIsize\fR)
 .sp
-void *
+char *
 \fBTcl_AttemptRealloc\fR(\fIptr, size\fR)
 .sp
 void
 \fBTcl_GetMemoryInfo\fR(\fIdsPtr\fR)
+.sp
+char *
+\fBckalloc\fR(\fIsize\fR)
+.sp
+void
+\fBckfree\fR(\fIptr\fR)
+.sp
+char *
+\fBckrealloc\fR(\fIptr, size\fR)
+.sp
+char *
+\fBattemptckalloc\fR(\fIsize\fR)
+.sp
+char *
+\fBattemptckrealloc\fR(\fIptr, size\fR)
 .SH ARGUMENTS
 .AS char *size
 .AP "unsigned int" size in
@@ -69,17 +84,18 @@ allocation fails, these functions will return NULL.  Note that on some
 platforms, but not all, attempting to allocate a zero-sized block of
 memory will also cause these functions to return NULL.
 .PP
-When a module or Tcl itself is compiled with \fBTCL_MEM_DEBUG\fR defined,
-the procedures \fBTcl_Alloc\fR, \fBTcl_Free\fR, \fBTcl_Realloc\fR,
-\fBTcl_AttemptAlloc\fR, and \fBTcl_AttempRealloc\fR are implemented
-as macros, redefined to be special debugging versions of these procedures.
+The procedures \fBckalloc\fR, \fBckfree\fR, \fBckrealloc\fR,
+\fBattemptckalloc\fR, and \fBattemptckrealloc\fR are implemented
+as macros.  Normally, they are synonyms for the corresponding
+procedures documented on this page.  When Tcl and all modules
+calling Tcl are compiled with \fBTCL_MEM_DEBUG\fR defined, however,
+these macros are redefined to be special debugging versions
+of these procedures.  To support Tcl's memory debugging within a
+module, use the macros rather than direct calls to \fBTcl_Alloc\fR, etc.

 \fBTcl_GetMemoryInfo\fR appends a list-of-lists of memory stats to the
 provided DString. This function cannot be used in stub-enabled extensions,
-and it is only available if Tcl is compiled with the threaded memory allocator
-When used in stub-enabled embedders, the stubs table must be first initialized
-using one of \fBTcl_InitSubsystems\fR, \fBTcl_SetPanicProc\fR,
-\fBTcl_FindExecutable\fR or \fBTclZipfs_AppHook\fR.
+and it is only available if Tcl is compiled with the threaded memory allocator.

 .SH KEYWORDS
 alloc, allocation, free, malloc, memory, realloc, TCL_MEM_DEBUG
@@ -30,7 +30,8 @@ or \fBTCL_RETURN\fR, then Tcl normally converts this into a \fBTCL_ERROR\fR
 return with an appropriate message.  The particular script
 evaluation procedures of Tcl that act in the manner are
 \fBTcl_EvalObjEx\fR, \fBTcl_EvalObjv\fR, \fBTcl_Eval\fR, \fBTcl_EvalEx\fR,
-\fBTcl_GlobalEval\fR, \fBTcl_GlobalEvalObj\fR and \fBTcl_VarEval\fR.
+\fBTcl_GlobalEval\fR, \fBTcl_GlobalEvalObj\fR, \fBTcl_VarEval\fR and
+\fBTcl_VarEvalVA\fR.
 .PP
 However, if \fBTcl_AllowExceptions\fR is invoked immediately before
 calling one of those a procedures, then arbitrary completion
@@ -13,7 +13,7 @@ Tcl_GetAssocData, Tcl_SetAssocData, Tcl_DeleteAssocData \- manage associations o
 .nf
 \fB#include <tcl.h>\fR
 .sp
-void *
+ClientData
 \fBTcl_GetAssocData\fR(\fIinterp, key, delProcPtr\fR)
 .sp
 \fBTcl_SetAssocData\fR(\fIinterp, key, delProc, clientData\fR)
@@ -31,7 +31,7 @@ Procedure to call when \fIinterp\fR is deleted.
 .AP Tcl_InterpDeleteProc **delProcPtr in
 Pointer to location in which to store address of current deletion procedure
 for association.  Ignored if NULL.
-.AP void *clientData in
+.AP ClientData clientData in
 Arbitrary one-word value associated with the given key in this
 interpreter.  This data is owned by the caller.
 .BE
@@ -64,7 +64,7 @@ the type \fBTcl_InterpDeleteProc\fR:
 .PP
 .CS
 typedef void \fBTcl_InterpDeleteProc\fR(
-        void *\fIclientData\fR,
+        ClientData \fIclientData\fR,
        Tcl_Interp *\fIinterp\fR);
 .CE
 .PP
@@ -35,7 +35,7 @@ int
 .AS Tcl_AsyncHandler clientData
 .AP Tcl_AsyncProc *proc in
 Procedure to invoke to handle an asynchronous event.
-.AP void *clientData in
+.AP ClientData clientData in
 One-word value to pass to \fIproc\fR.
 .AP Tcl_AsyncHandler async in
 Token for asynchronous event handler.
@@ -95,7 +95,7 @@ type \fBTcl_AsyncProc\fR:
 .PP
 .CS
 typedef int \fBTcl_AsyncProc\fR(
-        void *\fIclientData\fR,
+        ClientData \fIclientData\fR,
        Tcl_Interp *\fIinterp\fR,
        int \fIcode\fR);
 .CE
@@ -0,0 +1,47 @@
+'\"
+'\" Copyright (c) 1989-1993 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH Tcl_Backslash 3 "8.1" Tcl "Tcl Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tcl_Backslash \- parse a backslash sequence
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+char
+\fBTcl_Backslash\fR(\fIsrc, countPtr\fR)
+.SH ARGUMENTS
+.AS char *countPtr out
+.AP "const char" *src in
+Pointer to a string starting with a backslash.
+.AP int *countPtr out
+If \fIcountPtr\fR is not NULL, \fI*countPtr\fR gets filled
+in with number of characters in the backslash sequence, including
+the backslash character.
+.BE
+
+.SH DESCRIPTION
+.PP
+The use of \fBTcl_Backslash\fR is deprecated in favor of
+\fBTcl_UtfBackslash\fR.
+.PP
+This is a utility procedure provided for backwards compatibility with
+non-internationalized Tcl extensions.  It parses a backslash sequence and
+returns the low byte of the Unicode character corresponding to the sequence.
+\fBTcl_Backslash\fR modifies \fI*countPtr\fR to contain the number of
+characters in the backslash sequence.
+.PP
+See the Tcl manual entry for information on the valid backslash sequences.
+All of the sequences described in the Tcl manual entry are supported by
+\fBTcl_Backslash\fR.
+.SH "SEE ALSO"
+Tcl(n), Tcl_UtfBackslash(3)
+
+.SH KEYWORDS
+backslash, parse
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-.TH Tcl_ByteArrayObj 3 9.0 Tcl "Tcl Library Procedures"
+.TH Tcl_ByteArrayObj 3 8.1 Tcl "Tcl Library Procedures"
 .so man.macros
 .BS
 .SH NAME
@@ -34,8 +34,8 @@ unsigned char *
 .AP "const unsigned char" *bytes in
 The array of bytes used to initialize or set a byte-array value. May be NULL
 even if \fInumBytes\fR is non-zero.
-.AP size_t numBytes in
-The number of bytes in the array.
+.AP int numBytes in
+The number of bytes in the array.  It must be >= 0.
 .AP Tcl_Obj *objPtr in/out
 For \fBTcl_SetByteArrayObj\fR, this points to an unshared value to be
 overwritten by a byte-array value.  For \fBTcl_GetBytesFromObj\fR,
@@ -92,6 +92,11 @@ returns a pointer to the created value with a reference count of zero.
 of the unshared \fIobjPtr\fR as appropriate, and keeps its reference
 count (0 or 1) unchanged.  The value produced by these routines has no
 string representation.  Any memory allocation failure may cause a panic.
+Note that the type of the \fInumBytes\fR argument is \fBint\fR; consequently
+the largest byte-array value that can be produced by these routines is one
+holding \fBINT_MAX\fR bytes.  Note also that the string representation of
+any Tcl value is limited to \fBINT_MAX\fR bytes, so caution should be
+taken with any byte-array of more than \fBINT_MAX / 2\fR bytes.
 .PP
 \fBTcl_GetBytesFromObj\fR performs the opposite function of
 \fBTcl_SetByteArrayObj\fR, providing access to read a byte-array from
@@ -116,14 +121,29 @@ failure, nothing will be written to \fInumBytesPtr\fR, and if
 the \fIinterp\fR argument is non-NULL, then error messages and
 codes are left in it recording the error.
 .PP
-\fBTcl_GetByteArrayFromObj\fR performs exactly the same function as
-\fBTcl_GetBytesFromObj\fR does when called with the \fIinterp\fR
-argument passed the value NULL.  This is incompatible with the
-way \fBTcl_GetByteArrayFromObj\fR functioned in Tcl 8.
-\fBTcl_GetBytesFromObj\fR is the more capable interface and should
-usually be favored for use over \fBTcl_GetByteArrayFromObj\fR.
+\fBTcl_GetByteArrayFromObj\fR performs nearly the same function as
+\fBTcl_GetBytesFromObj\fR.  They differ only in the circumstance when
+a byte-array internal value must be created by transformation of
+a string representation, and that string representation contains a
+character with codepoint greater than U+00FF.  Instead of failing
+the conversion, \fBTcl_GetByteArrayFromObj\fR will use the 8 least
+significant bits of each codepoint to produce a valid byte value
+from any character codepoint value.  In any other circumstance,
+\fBTcl_GetByteArrayFromObj\fR performs just as \fBTcl_GetBytesFromObj\fR
+does.  Since the conversion cannot fail, \fBTcl_GetByteArrayFromObj\fR
+has no need for an \fIinterp\fR argument to record any errors and
+the caller can assume \fBTcl_GetByteArrayFromObj\fR does not return NULL.
 .PP
-On success, both \fBTcl_GetByteFromObj\fR and \fBTcl_GetByteArrayFromObj\fR
+\fBTcl_GetByteArrayFromObj\fR must be used with caution.  Because of the
+truncation on conversion, the byte-array made available to the caller
+cannot reliably complete a round-trip back to the original string
+representation.  This creates opportunities for bugs due to blindness
+to differences in values.  This routine exists in this form primarily
+for compatibility with codebases written for earlier releases of Tcl.
+It is expected this routine will incompatibly change in Tcl 9 so that
+it also signals failed conversions with a NULL return.
+.PP
+On success, both \fBTcl_GetBytesFromObj\fR and \fBTcl_GetByteArrayFromObj\fR
 return a pointer into the internal representation of a \fBTcl_Obj\fR.
 That pointer must not be freed by the caller, and should not be retained
 for use beyond the known time the internal representation of the value
@@ -134,14 +154,10 @@ and any string representation is invalidated.
 On success, both \fBTcl_GetBytesFromObj\fR and \fBTcl_GetByteArrayFromObj\fR
 write the number of bytes in the byte-array value of \fIobjPtr\fR
 to the space pointed to by \fInumBytesPtr\fR.  This space may be of type
-\fBsize_t\fR or of type \fBint\fR.  It is recommended that callers provide
-a \fBsize_t\fR space for this purpose.  If the caller provides only
-an \fBint\fR space and the number of bytes in the byte-array value of
-\fIobjPtr\fR is greater than \fBINT_MAX\fR, the routine will fail due
-to being unable to correctly report the byte-array size to the caller.
-The ability to provide an \fBint\fR space is best considered a migration
-aid for codebases constrained to continue operating with Tcl releases
-older than 8.7.
+\fBsize_t\fR or of type \fBint\fR.  In Tcl 8, the largest number of
+bytes possible is \fBINT_MAX\fR, so either type can receive the value.
+In codebases meant to migrate to Tcl 9, the option to write to a space
+of type \fBsize_t\fR may aid in the migration.
 .PP
 \fBTcl_SetByteArrayLength\fR enables a caller to change the size of a
 byte-array in the internal representation of an unshared \fIobjPtr\fR to
@@ -154,9 +170,8 @@ changes the internal representation, \fBTcl_SetByteArrayLength\fR
 also invalidates any string representation in \fIobjPtr\fR.  If resizing
 grows the byte-array, the new byte values are undefined.  If \fIobjPtr\fR
 does not already possess an internal byte-array, one is produced in the
-same way that \fBTcl_GetBytesFromObj\fR does, also returning NULL
-when any characters of the value in \fIobjPtr\fR (up to
-\fInumBytes\fR of them) are not valid bytes.
+same way that \fBTcl_GetByteArrayFromObj\fR does, with all the cautions
+that go along with that.
 .SH "REFERENCE COUNT MANAGEMENT"
 .PP
 \fBTcl_NewByteArrayObj\fR always returns a zero-reference object, much
@@ -23,7 +23,7 @@ Tcl_CallWhenDeleted, Tcl_DontCallWhenDeleted \- Arrange for callback when interp
 Interpreter with which to associated callback.
 .AP Tcl_InterpDeleteProc *proc in
 Procedure to call when \fIinterp\fR is deleted.
-.AP void *clientData in
+.AP ClientData clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .BE
 .SH DESCRIPTION
@@ -38,7 +38,7 @@ type \fBTcl_InterpDeleteProc\fR:
 .PP
 .CS
 typedef void \fBTcl_InterpDeleteProc\fR(
-        void *\fIclientData\fR,
+        ClientData \fIclientData\fR,
        Tcl_Interp *\fIinterp\fR);
 .CE
 .PP
@@ -30,7 +30,7 @@ ORed combination of flag bits that specify additional options.
 For \fBTcl_CancelEval\fR, only \fBTCL_CANCEL_UNWIND\fR is currently
 supported.  For \fBTcl_Canceled\fR, only \fBTCL_LEAVE_ERR_MSG\fR and
 \fBTCL_CANCEL_UNWIND\fR are currently supported.
-.AP void *clientData in
+.AP ClientData clientData in
 Currently reserved for future use.
 It should be set to NULL.
 .BE
@@ -32,7 +32,7 @@ Tcl_Channel
 Interpreter for error reporting.
 .AP "const Tcl_ChannelType" *typePtr in
 The new channel I/O procedures to use for \fIchannel\fR.
-.AP void *clientData in
+.AP ClientData clientData in
 Arbitrary one-word value to pass to channel I/O procedures.
 .AP int mask in
 Conditions under which \fIchannel\fR will be used: OR-ed combination of
@@ -49,8 +49,11 @@ I/O channels.  Examples include compression and encryption modules.  These
 functions transparently stack and unstack a new channel on top of an
 existing one.  Any number of channels can be stacked together.
 .PP
-The \fBTcl_ChannelType\fR version currently supported is
-\fBTCL_CHANNEL_VERSION_5\fR.  See \fBTcl_CreateChannel\fR for details.
+The implementation of the Tcl channel code was rewritten in 8.3.2 to
+correct some problems with the previous implementation with regard to
+stacked channels.  Anyone using stacked channels or creating stacked
+channel drivers should update to the new \fBTCL_CHANNEL_VERSION_2\fR
+\fBTcl_ChannelType\fR structure.  See \fBTcl_CreateChannel\fR for details.
 .PP
 \fBTcl_StackChannel\fR stacks a new \fIchannel\fR on an existing channel
 with the same name that was registered for \fIchannel\fR by
@@ -41,12 +41,12 @@ Tcl_Object
 int
 \fBTcl_ObjectDeleted\fR(\fIobject\fR)
 .sp
-void *
+ClientData
 \fBTcl_ObjectGetMetadata\fR(\fIobject, metaTypePtr\fR)
 .sp
 \fBTcl_ObjectSetMetadata\fR(\fIobject, metaTypePtr, metadata\fR)
 .sp
-void *
+ClientData
 \fBTcl_ClassGetMetadata\fR(\fIclass, metaTypePtr\fR)
 .sp
 \fBTcl_ClassSetMetadata\fR(\fIclass, metaTypePtr, metadata\fR)
@@ -64,7 +64,7 @@ Tcl_Obj *
 \fBTcl_GetObjectClassName\fR(\fIinterp\fR, \fIobject\fR)
 .VE "TIP 605"
 .SH ARGUMENTS
-.AS void *metadata in/out
+.AS ClientData metadata in/out
 .AP Tcl_Interp *interp in/out
 Interpreter providing the context for looking up or creating an object, and
 into whose result error messages will be written on failure.
@@ -93,7 +93,7 @@ error messages even when complicated calling patterns are used (e.g., via the
 .AP Tcl_ObjectMetadataType *metaTypePtr in
 The type of \fImetadata\fR being set with \fBTcl_ClassSetMetadata\fR or
 retrieved with \fBTcl_ClassGetMetadata\fR.
-.AP void *metadata in
+.AP ClientData metadata in
 An item of metadata to attach to the class, or NULL to remove the metadata
 associated with a particular \fImetaTypePtr\fR.
 .AP "Tcl_ObjectMapMethodNameProc" "methodNameMapper" in
@@ -200,7 +200,7 @@ a class or object.
 .PP
 .CS
 typedef void \fBTcl_ObjectMetadataDeleteProc\fR(
-        void *\fImetadata\fR);
+        ClientData \fImetadata\fR);
 .CE
 .PP
 The \fImetadata\fR argument gives the address of the metadata to be
@@ -213,8 +213,8 @@ associated with a class or object.
 .CS
 typedef int \fBTcl_CloneProc\fR(
        Tcl_Interp *\fIinterp\fR,
-        void *\fIsrcMetadata\fR,
-        void **\fIdstMetadataPtr\fR);
+        ClientData \fIsrcMetadata\fR,
+        ClientData *\fIdstMetadataPtr\fR);
 .CE
 .PP
 The \fIinterp\fR argument gives a place to write an error message when the
@@ -8,7 +8,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_IsSafe, Tcl_MakeSafe, Tcl_CreateChild, Tcl_GetChild, Tcl_GetParent, Tcl_GetInterpPath, Tcl_CreateAlias, Tcl_CreateAliasObj, Tcl_GetAlias, Tcl_GetAliasObj, Tcl_ExposeCommand, Tcl_HideCommand \- manage multiple Tcl interpreters, aliases and hidden commands
+Tcl_IsSafe, Tcl_MakeSafe, Tcl_CreateChild, Tcl_CreateSlave, Tcl_GetChild, Tcl_GetSlave, Tcl_GetParent, Tcl_GetMaster, Tcl_GetInterpPath, Tcl_CreateAlias, Tcl_CreateAliasObj, Tcl_GetAlias, Tcl_GetAliasObj, Tcl_ExposeCommand, Tcl_HideCommand \- manage multiple Tcl interpreters, aliases and hidden commands
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -23,9 +23,18 @@ Tcl_Interp *
 \fBTcl_CreateChild\fR(\fIinterp, name, isSafe\fR)
 .sp
 Tcl_Interp *
+\fBTcl_CreateSlave\fR(\fIinterp, name, isSafe\fR)
+.sp
+Tcl_Interp *
+\fBTcl_GetSlave\fR(\fIinterp, name\fR)
+.sp
+Tcl_Interp *
 \fBTcl_GetChild\fR(\fIinterp, name\fR)
 .sp
 Tcl_Interp *
+\fBTcl_GetMaster\fR(\fIinterp\fR)
+.sp
+Tcl_Interp *
 \fBTcl_GetParent\fR(\fIinterp\fR)
 .sp
 int
@@ -133,6 +142,8 @@ 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
+\fBTcl_CreateSlave\fR is a synonym for \fBTcl_CreateChild\fR.
+.PP
 \fBTcl_IsSafe\fR returns \fB1\fR if \fIinterp\fR is
 .QW safe
 (was created with the \fBTCL_SAFE_INTERPRETER\fR flag specified),
@@ -154,10 +165,14 @@ may be a better choice, since it creates interpreters in a known-safe state.
 \fIinterp\fR. The child interpreter is identified by \fIname\fR.
 If no such child interpreter exists, \fBNULL\fR is returned.
 .PP
+\fBTcl_GetSlave\fR is a synonym for \fBTcl_GetChild\fR.
+.PP
 \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
+\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;
 \fIchildInterp\fR must be a child of \fIinterp\fR. If the computation
@@ -9,7 +9,7 @@
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType, Tcl_GetChannelName, Tcl_GetChannelHandle, Tcl_GetChannelMode, Tcl_GetChannelBufferSize, Tcl_SetChannelBufferSize, Tcl_NotifyChannel, Tcl_BadChannelOption, Tcl_ChannelName, Tcl_ChannelVersion, Tcl_ChannelBlockModeProc, Tcl_ChannelClose2Proc, Tcl_ChannelInputProc, Tcl_ChannelOutputProc, Tcl_ChannelWideSeekProc, Tcl_ChannelTruncateProc, Tcl_ChannelSetOptionProc, Tcl_ChannelGetOptionProc, Tcl_ChannelWatchProc, Tcl_ChannelGetHandleProc, Tcl_ChannelFlushProc, Tcl_ChannelHandlerProc, Tcl_ChannelThreadActionProc, Tcl_IsChannelShared, Tcl_IsChannelRegistered, Tcl_CutChannel, Tcl_SpliceChannel, Tcl_IsChannelExisting, Tcl_ClearChannelHandlers, Tcl_GetChannelThread, Tcl_ChannelBuffered \- procedures for creating and manipulating channels
+Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType, Tcl_GetChannelName, Tcl_GetChannelHandle, Tcl_GetChannelMode, Tcl_GetChannelBufferSize, Tcl_SetChannelBufferSize, Tcl_NotifyChannel, Tcl_BadChannelOption, Tcl_ChannelName, Tcl_ChannelVersion, Tcl_ChannelBlockModeProc, Tcl_ChannelCloseProc, Tcl_ChannelClose2Proc, Tcl_ChannelInputProc, Tcl_ChannelOutputProc, Tcl_ChannelSeekProc, Tcl_ChannelWideSeekProc, Tcl_ChannelTruncateProc, Tcl_ChannelSetOptionProc, Tcl_ChannelGetOptionProc, Tcl_ChannelWatchProc, Tcl_ChannelGetHandleProc, Tcl_ChannelFlushProc, Tcl_ChannelHandlerProc, Tcl_ChannelThreadActionProc, Tcl_IsChannelShared, Tcl_IsChannelRegistered, Tcl_CutChannel, Tcl_SpliceChannel, Tcl_IsChannelExisting, Tcl_ClearChannelHandlers, Tcl_GetChannelThread, Tcl_ChannelBuffered \- procedures for creating and manipulating channels
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -17,7 +17,7 @@ Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType, Tcl_GetChanne
 Tcl_Channel
 \fBTcl_CreateChannel\fR(\fItypePtr, channelName, instanceData, mask\fR)
 .sp
-void *
+ClientData
 \fBTcl_GetChannelInstanceData\fR(\fIchannel\fR)
 .sp
 const Tcl_ChannelType *
@@ -75,6 +75,9 @@ Tcl_ChannelTypeVersion
 Tcl_DriverBlockModeProc *
 \fBTcl_ChannelBlockModeProc\fR(\fItypePtr\fR)
 .sp
+Tcl_DriverCloseProc *
+\fBTcl_ChannelCloseProc\fR(\fItypePtr\fR)
+.sp
 Tcl_DriverClose2Proc *
 \fBTcl_ChannelClose2Proc\fR(\fItypePtr\fR)
 .sp
@@ -84,6 +87,9 @@ Tcl_DriverInputProc *
 Tcl_DriverOutputProc *
 \fBTcl_ChannelOutputProc\fR(\fItypePtr\fR)
 .sp
+Tcl_DriverSeekProc *
+\fBTcl_ChannelSeekProc\fR(\fItypePtr\fR)
+.sp
 Tcl_DriverWideSeekProc *
 \fBTcl_ChannelWideSeekProc\fR(\fItypePtr\fR)
 .sp
@@ -122,7 +128,7 @@ by any other channel. Can be NULL, in which case the channel is
 created without a name. If the created channel is assigned to one
 of the standard channels (\fBstdin\fR, \fBstdout\fR or \fBstderr\fR),
 the assigned channel name will be the name of the standard channel.
-.AP void *instanceData in
+.AP ClientData instanceData in
 Arbitrary one-word value to be associated with this channel.  This
 value is passed to procedures in \fItypePtr\fR when they are invoked.
 .AP int mask in
@@ -133,7 +139,7 @@ The channel to operate on.
 .AP int direction in
 \fBTCL_READABLE\fR means the input handle is wanted; \fBTCL_WRITABLE\fR
 means the output handle is wanted.
-.AP void **handlePtr out
+.AP ClientData *handlePtr out
 Points to the location where the desired OS-specific handle should be
 stored.
 .AP int size in
@@ -281,13 +287,16 @@ name is registered in the (thread)-global list of all channels (result
 (thread)global list of all channels (of the current thread).
 Application to a channel still registered in some interpreter
 is not allowed.
-Also notifies the driver if
+Also notifies the driver if the \fBTcl_ChannelType\fR version is
+\fBTCL_CHANNEL_VERSION_4\fR (or higher), and
 \fBTcl_DriverThreadActionProc\fR is defined for it.
 .PP
 \fBTcl_SpliceChannel\fR adds the specified \fIchannel\fR to the
 (thread)global list of all channels (of the current thread).
 Application to a channel registered in some interpreter is not allowed.
-Also notifies the driver if \fBTcl_DriverThreadActionProc\fR is defined for it.
+Also notifies the driver if the \fBTcl_ChannelType\fR version is
+\fBTCL_CHANNEL_VERSION_4\fR (or higher), and
+\fBTcl_DriverThreadActionProc\fR is defined for it.
 .PP
 \fBTcl_ClearChannelHandlers\fR removes all channel handlers and event
 scripts associated with the specified \fIchannel\fR, thus shutting
@@ -307,10 +316,10 @@ The \fBTcl_ChannelType\fR structure contains the following fields:
 typedef struct Tcl_ChannelType {
        const char *\fItypeName\fR;
        Tcl_ChannelTypeVersion \fIversion\fR;
-        void *\fIcloseProc\fR; /* Not used any more*/
+        Tcl_DriverCloseProc *\fIcloseProc\fR;
        Tcl_DriverInputProc *\fIinputProc\fR;
        Tcl_DriverOutputProc *\fIoutputProc\fR;
-        void *\fIseekProc\fR; /* Not used any more */
+        Tcl_DriverSeekProc *\fIseekProc\fR;
        Tcl_DriverSetOptionProc *\fIsetOptionProc\fR;
        Tcl_DriverGetOptionProc *\fIgetOptionProc\fR;
        Tcl_DriverWatchProc *\fIwatchProc\fR;
@@ -339,8 +348,9 @@ The user should only use the above structure for \fBTcl_ChannelType\fR
 instantiation.  When referencing fields in a \fBTcl_ChannelType\fR
 structure, the following functions should be used to obtain the values:
 \fBTcl_ChannelName\fR, \fBTcl_ChannelVersion\fR,
-\fBTcl_ChannelBlockModeProc\fR, \fBTcl_ChannelClose2Proc\fR,
-\fBTcl_ChannelInputProc\fR, \fBTcl_ChannelOutputProc\fR,
+\fBTcl_ChannelBlockModeProc\fR, \fBTcl_ChannelCloseProc\fR,
+\fBTcl_ChannelClose2Proc\fR, \fBTcl_ChannelInputProc\fR,
+\fBTcl_ChannelOutputProc\fR, \fBTcl_ChannelSeekProc\fR,
 \fBTcl_ChannelWideSeekProc\fR, \fBTcl_ChannelThreadActionProc\fR,
 \fBTcl_ChannelTruncateProc\fR,
 \fBTcl_ChannelSetOptionProc\fR, \fBTcl_ChannelGetOptionProc\fR,
@@ -363,9 +373,25 @@ a pointer to the string.
 .PP

 The \fIversion\fR field should be set to the version of the structure
-that you require. \fBTCL_CHANNEL_VERSION_5\fR is the minimum supported.
+that you require. \fBTCL_CHANNEL_VERSION_2\fR is the minimum recommended.
+\fBTCL_CHANNEL_VERSION_3\fR must be set to specify the \fIwideSeekProc\fR member.
+\fBTCL_CHANNEL_VERSION_4\fR must be set to specify the \fIthreadActionProc\fR member
+(includes \fIwideSeekProc\fR).
+\fBTCL_CHANNEL_VERSION_5\fR must be set to specify the
+\fItruncateProc\fR members (includes
+\fIwideSeekProc\fR and \fIthreadActionProc\fR).
+If it is not set to any of these, then this
+\fBTcl_ChannelType\fR is assumed to have the original structure.  See
+\fBOLD CHANNEL TYPES\fR for more details.  While Tcl will recognize
+and function with either structures, stacked channels must be of at
+least \fBTCL_CHANNEL_VERSION_2\fR to function correctly.
 .PP
-This value can be retrieved with \fBTcl_ChannelVersion\fR.
+This value can be retrieved with \fBTcl_ChannelVersion\fR, which returns
+one of
+\fBTCL_CHANNEL_VERSION_5\fR,
+\fBTCL_CHANNEL_VERSION_4\fR,
+\fBTCL_CHANNEL_VERSION_3\fR,
+\fBTCL_CHANNEL_VERSION_2\fR or \fBTCL_CHANNEL_VERSION_1\fR.
 .SS BLOCKMODEPROC
 .PP
 The \fIblockModeProc\fR field contains the address of a function called by
@@ -374,7 +400,7 @@ the generic layer to set blocking and nonblocking mode on the device.
 .PP
 .CS
 typedef int \fBTcl_DriverBlockModeProc\fR(
-        void *\fIinstanceData\fR,
+        ClientData \fIinstanceData\fR,
        int \fImode\fR);
 .CE
 .PP
@@ -401,23 +427,22 @@ blocking mode is acceptable to it, and should this also document for
 the user so that the blocking mode of the channel is not changed to an
 unacceptable value. Any confusion here may lead the interpreter into a
 (spurious and difficult to find) deadlock.
-.SS "CLOSE2PROC"
+.SS "CLOSEPROC AND CLOSE2PROC"
 .PP
-The \fIclose2Proc\fR field contains the address of a function called by the
+The \fIcloseProc\fR field contains the address of a function called by the
 generic layer to clean up driver-related information when the channel is
-closed. \fIClose2Proc\fR must match the following prototype:
+closed. \fICloseProc\fR must match the following prototype:
 .PP
 .CS
-typedef int \fBTcl_DriverClose2Proc\fR(
-        void *\fIinstanceData\fR,
-        Tcl_Interp *\fIinterp\fR,
-        int \fIflags\fR);
+typedef int \fBTcl_DriverCloseProc\fR(
+        ClientData \fIinstanceData\fR,
+        Tcl_Interp *\fIinterp\fR);
 .CE
 .PP
-If \fIflags\fR is 0, the \fIinstanceData\fR argument is the same as the value
-provided to \fBTcl_CreateChannel\fR when the channel was created. The function
-should release any storage maintained by the channel driver for this channel,
-and close the input and output devices encapsulated by this channel. All queued
+The \fIinstanceData\fR argument is the same as the value provided to
+\fBTcl_CreateChannel\fR when the channel was created. The function should
+release any storage maintained by the channel driver for this channel, and
+close the input and output devices encapsulated by this channel. All queued
 output will have been flushed to the device before this function is called,
 and no further driver operations will be invoked on this instance after
 calling the \fIcloseProc\fR. If the close operation is successful, the
@@ -426,20 +451,35 @@ error code. In addition, if an error occurs and \fIinterp\fR is not NULL,
 the procedure should store an error message in the interpreter's result.
 .PP
 Alternatively, channels that support closing the read and write sides
-independently may accept other flag values than 0.
-Then \fIclose2Proc\fR will be called with \fIflags\fR set to an OR'ed
+independently may set \fIcloseProc\fR to \fBTCL_CLOSE2PROC\fR and set
+\fIclose2Proc\fR to the address of a function that matches the
+following prototype:
+.PP
+.CS
+typedef int \fBTcl_DriverClose2Proc\fR(
+        ClientData \fIinstanceData\fR,
+        Tcl_Interp *\fIinterp\fR,
+        int \fIflags\fR);
+.CE
+.PP
+The \fIclose2Proc\fR will be called with \fIflags\fR set to an OR'ed
 combination of \fBTCL_CLOSE_READ\fR or \fBTCL_CLOSE_WRITE\fR to
 indicate that the driver should close the read and/or write side of
 the channel.  The channel driver may be invoked to perform
 additional operations on the channel after \fIclose2Proc\fR is
-called to close one or both sides of the channel.  In all cases, the
-\fIclose2Proc\fR function should return zero if the close operation was
-successful; otherwise it should return a nonzero POSIX error code.
-In addition, if an error occurs and \fIinterp\fR is not NULL, the procedure
-should store an error message in the interpreter's result.
+called to close one or both sides of the channel.  If \fIflags\fR is
+\fB0\fR (zero), the driver should close the channel in the manner
+described above for \fIcloseProc\fR.  No further operations will be
+invoked on this instance after \fIclose2Proc\fR is called with all
+flags cleared.  In all cases, the \fIclose2Proc\fR function should
+return zero if the close operation was successful; otherwise it should
+return a nonzero POSIX error code. In addition, if an error occurs and
+\fIinterp\fR is not NULL, the procedure should store an error message
+in the interpreter's result.
 .PP
-The \fIclose2Proc\fR value can be retrieved with \fBTcl_ChannelClose2Proc\fR,
-which returns a pointer to the function.
+The \fIcloseProc\fR and \fIclose2Proc\fR values can be retrieved with
+\fBTcl_ChannelCloseProc\fR or \fBTcl_ChannelClose2Proc\fR, which
+return a pointer to the respective function.
 .SS INPUTPROC
 .PP
 The \fIinputProc\fR field contains the address of a function called by the
@@ -448,7 +488,7 @@ internal buffer. \fIInputProc\fR must match the following prototype:
 .PP
 .CS
 typedef int \fBTcl_DriverInputProc\fR(
-        void *\fIinstanceData\fR,
+        ClientData \fIinstanceData\fR,
        char *\fIbuf\fR,
        int \fIbufSize\fR,
        int *\fIerrorCodePtr\fR);
@@ -492,7 +532,7 @@ generic layer to transfer data from an internal buffer to the output device.
 .PP
 .CS
 typedef int \fBTcl_DriverOutputProc\fR(
-        void *\fIinstanceData\fR,
+        ClientData \fIinstanceData\fR,
        const char *\fIbuf\fR,
        int \fItoWrite\fR,
        int *\fIerrorCodePtr\fR);
@@ -522,17 +562,17 @@ without writing any data.
 .PP
 This value can be retrieved with \fBTcl_ChannelOutputProc\fR, which returns
 a pointer to the function.
-.SS "WIDESEEKPROC"
+.SS "SEEKPROC AND WIDESEEKPROC"
 .PP
-The \fIwideSeekProc\fR field contains the address of a function called by the
+The \fIseekProc\fR field contains the address of a function called by the
 generic layer to move the access point at which subsequent input or output
-operations will be applied. \fIWideSeekProc\fR must match the following
+operations will be applied. \fISeekProc\fR must match the following
 prototype:
 .PP
 .CS
-typedef Tcl_WideInt \fBTcl_DriverWideSeekProc\fR(
-        void *\fIinstanceData\fR,
-        Tcl_WideInt \fIoffset\fR,
+typedef int \fBTcl_DriverSeekProc\fR(
+        ClientData \fIinstanceData\fR,
+        long \fIoffset\fR,
        int \fIseekMode\fR,
        int *\fIerrorCodePtr\fR);
 .CE
@@ -551,8 +591,30 @@ does not implement seeking.
 The return value is the new access point or -1 in case of error. If an
 error occurred, the function should not move the access point.
 .PP
-The \fIwideSseekProc\fR value can be retrieved with
-\fBTcl_ChannelWideSeekProc\fR, which returns a pointer to the function.
+If there is a non-NULL \fIseekProc\fR field, the \fIwideSeekProc\fR
+field may contain the address of an alternative function to use which
+handles wide (i.e. larger than 32-bit) offsets, so allowing seeks
+within files larger than 2GB.  The \fIwideSeekProc\fR will be called
+in preference to the \fIseekProc\fR, but both must be defined if the
+\fIwideSeekProc\fR is defined.  \fIWideSeekProc\fR must match the
+following prototype:
+.PP
+.CS
+typedef long long \fBTcl_DriverWideSeekProc\fR(
+        ClientData \fIinstanceData\fR,
+        long long \fIoffset\fR,
+        int \fIseekMode\fR,
+        int *\fIerrorCodePtr\fR);
+.CE
+.PP
+The arguments and return values mean the same thing as with
+\fIseekProc\fR above, except that the type of offsets and the return
+type are different.
+.PP
+The \fIseekProc\fR value can be retrieved with
+\fBTcl_ChannelSeekProc\fR, which returns a pointer to the function,
+and similarly the \fIwideSeekProc\fR can be retrieved with
+\fBTcl_ChannelWideSeekProc\fR.
 .SS SETOPTIONPROC
 .PP
 The \fIsetOptionProc\fR field contains the address of a function called by
@@ -561,7 +623,7 @@ the generic layer to set a channel type specific option on a channel.
 .PP
 .CS
 typedef int \fBTcl_DriverSetOptionProc\fR(
-        void *\fIinstanceData\fR,
+        ClientData \fIinstanceData\fR,
        Tcl_Interp *\fIinterp\fR,
        const char *\fIoptionName\fR,
        const char *\fInewValue\fR);
@@ -602,7 +664,7 @@ channel. \fIgetOptionProc\fR must match the following prototype:
 .PP
 .CS
 typedef int \fBTcl_DriverGetOptionProc\fR(
-        void *\fIinstanceData\fR,
+        ClientData \fIinstanceData\fR,
        Tcl_Interp *\fIinterp\fR,
        const char *\fIoptionName\fR,
        Tcl_DString *\fIoptionValue\fR);
@@ -640,7 +702,7 @@ notice events of interest on this channel.
 .PP
 .CS
 typedef void \fBTcl_DriverWatchProc\fR(
-        void *\fIinstanceData\fR,
+        ClientData \fIinstanceData\fR,
        int \fImask\fR);
 .CE
 .PP
@@ -671,9 +733,9 @@ the generic layer to retrieve a device-specific handle from the channel.
 .PP
 .CS
 typedef int \fBTcl_DriverGetHandleProc\fR(
-        void *\fIinstanceData\fR,
+        ClientData \fIinstanceData\fR,
        int \fIdirection\fR,
-        void **\fIhandlePtr\fR);
+        ClientData *\fIhandlePtr\fR);
 .CE
 .PP
 \fIInstanceData\fR is the same as the value passed to
@@ -700,7 +762,7 @@ It should be set to NULL.
 .PP
 .CS
 typedef int \fBTcl_DriverFlushProc\fR(
-        void *\fIinstanceData\fR);
+        ClientData \fIinstanceData\fR);
 .CE
 .PP
 This value can be retrieved with \fBTcl_ChannelFlushProc\fR, which returns
@@ -715,7 +777,7 @@ that occur on the underlying (stacked) channel.
 .PP
 .CS
 typedef int \fBTcl_DriverHandlerProc\fR(
-        void *\fIinstanceData\fR,
+        ClientData \fIinstanceData\fR,
        int \fIinterestMask\fR);
 .CE
 .PP
@@ -744,7 +806,7 @@ might be maintaining using the calling thread as the associate. See
 .PP
 .CS
 typedef void \fBTcl_DriverThreadActionProc\fR(
-        void *\fIinstanceData\fR,
+        ClientData \fIinstanceData\fR,
        int \fIaction\fR);
 .CE
 .PP
@@ -761,7 +823,7 @@ length. It can be NULL.
 .PP
 .CS
 typedef int \fBTcl_DriverTruncateProc\fR(
-        void *\fIinstanceData\fR,
+        ClientData \fIinstanceData\fR,
        long long \fIlength\fR);
 .CE
 .PP
@@ -809,6 +871,58 @@ The function takes good care of inserting minus signs before
 each option, commas after, and an
 .QW or
 before the last option.
+.SH "OLD CHANNEL TYPES"
+The original (8.3.1 and below) \fBTcl_ChannelType\fR structure contains
+the following fields:
+.PP
+.CS
+typedef struct Tcl_ChannelType {
+    const char *\fItypeName\fR;
+    Tcl_DriverBlockModeProc *\fIblockModeProc\fR;
+    Tcl_DriverCloseProc *\fIcloseProc\fR;
+    Tcl_DriverInputProc *\fIinputProc\fR;
+    Tcl_DriverOutputProc *\fIoutputProc\fR;
+    Tcl_DriverSeekProc *\fIseekProc\fR;
+    Tcl_DriverSetOptionProc *\fIsetOptionProc\fR;
+    Tcl_DriverGetOptionProc *\fIgetOptionProc\fR;
+    Tcl_DriverWatchProc *\fIwatchProc\fR;
+    Tcl_DriverGetHandleProc *\fIgetHandleProc\fR;
+    Tcl_DriverClose2Proc *\fIclose2Proc\fR;
+} \fBTcl_ChannelType\fR;
+.CE
+.PP
+It is still possible to create channel with the above structure.  The
+internal channel code will determine the version.  It is imperative to use
+the new \fBTcl_ChannelType\fR structure if you are creating a stacked
+channel driver, due to problems with the earlier stacked channel
+implementation (in 8.2.0 to 8.3.1).
+.PP
+Prior to 8.4.0 (i.e. during the later releases of 8.3 and early part
+of the 8.4 development cycle) the \fBTcl_ChannelType\fR structure
+contained the following fields:
+.PP
+.CS
+typedef struct Tcl_ChannelType {
+    const char *\fItypeName\fR;
+    Tcl_ChannelTypeVersion \fIversion\fR;
+    Tcl_DriverCloseProc *\fIcloseProc\fR;
+    Tcl_DriverInputProc *\fIinputProc\fR;
+    Tcl_DriverOutputProc *\fIoutputProc\fR;
+    Tcl_DriverSeekProc *\fIseekProc\fR;
+    Tcl_DriverSetOptionProc *\fIsetOptionProc\fR;
+    Tcl_DriverGetOptionProc *\fIgetOptionProc\fR;
+    Tcl_DriverWatchProc *\fIwatchProc\fR;
+    Tcl_DriverGetHandleProc *\fIgetHandleProc\fR;
+    Tcl_DriverClose2Proc *\fIclose2Proc\fR;
+    Tcl_DriverBlockModeProc *\fIblockModeProc\fR;
+    Tcl_DriverFlushProc *\fIflushProc\fR;
+    Tcl_DriverHandlerProc *\fIhandlerProc\fR;
+    Tcl_DriverTruncateProc *\fItruncateProc\fR;
+} \fBTcl_ChannelType\fR;
+.CE
+.PP
+When the above structure is registered as a channel type, the
+\fIversion\fR field should always be \fBTCL_CHANNEL_VERSION_2\fR.
 .SH "SEE ALSO"
 Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3), Tcl_QueueEvent(3), Tcl_StackChannel(3), Tcl_GetStdChannel(3)
 .SH KEYWORDS
@@ -32,7 +32,7 @@ a zero value to temporarily disable an existing handler.
 .AP Tcl_FileProc *proc in
 Procedure to invoke whenever the channel indicated by \fIchannel\fR meets
 the conditions specified by \fImask\fR.
-.AP void *clientData in
+.AP ClientData clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .BE
 .SH DESCRIPTION
@@ -48,7 +48,7 @@ what it means for a channel to be readable or writable.
 .PP
 .CS
 typedef void \fBTcl_ChannelProc\fR(
-        void *\fIclientData\fR,
+        ClientData \fIclientData\fR,
        int \fImask\fR);
 .CE
 .PP
@@ -26,7 +26,7 @@ void
 The channel for which to create or delete a close callback.
 .AP Tcl_CloseProc *proc in
 The procedure to call as the callback.
-.AP void *clientData in
+.AP ClientData clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .BE
 .SH DESCRIPTION
@@ -38,7 +38,7 @@ Arbitrary one-word value to pass to \fIproc\fR.
 .PP
 .CS
 typedef void \fBTcl_CloseProc\fR(
-        void *\fIclientData\fR);
+        ClientData \fIclientData\fR);
 .CE
 .PP
 The \fIclientData\fR is the same as the value provided in the call to
@@ -25,7 +25,7 @@ Name of command.
 .AP Tcl_CmdProc *proc in
 Implementation of new command:  \fIproc\fR will be called whenever
 \fIcmdName\fR is invoked as a command.
-.AP voie *clientData in
+.AP ClientData clientData in
 Arbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR.
 .AP Tcl_CmdDeleteProc *deleteProc in
 Procedure to call before \fIcmdName\fR is deleted from the interpreter;
@@ -75,7 +75,7 @@ and it returns NULL.
 .PP
 .CS
 typedef int \fBTcl_CmdProc\fR(
-        void *\fIclientData\fR,
+        ClientData \fIclientData\fR,
        Tcl_Interp *\fIinterp\fR,
        int \fIargc\fR,
        const char *\fIargv\fR[]);
@@ -131,7 +131,7 @@ result that match the type \fBTcl_CmdDeleteProc\fR:
 .PP
 .CS
 typedef void \fBTcl_CmdDeleteProc\fR(
-        void *\fIclientData\fR);
+        ClientData \fIclientData\fR);
 .CE
 .PP
 The \fIclientData\fR argument will be the same as the \fIclientData\fR
@@ -29,7 +29,7 @@ a handler.
 .AP Tcl_FileProc *proc in
 Procedure to invoke whenever the file or device indicated
 by \fIfile\fR meets the conditions specified by \fImask\fR.
-.AP void *clientData in
+.AP ClientData clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .BE
 .SH DESCRIPTION
@@ -51,7 +51,7 @@ type \fBTcl_FileProc\fR:
 .PP
 .CS
 typedef void \fBTcl_FileProc\fR(
-        void *\fIclientData\fR,
+        ClientData \fIclientData\fR,
        int \fImask\fR);
 .CE
 .PP
@@ -0,0 +1,166 @@
+'\"
+'\" Copyright (c) 1989-1993 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH Tcl_CreateMathFunc 3 8.4 Tcl "Tcl Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tcl_CreateMathFunc, Tcl_GetMathFuncInfo, Tcl_ListMathFuncs \- Define, query and enumerate math functions for expressions
+.SH "NOTICE OF EVENTUAL DEPRECATION"
+.PP
+The \fBTcl_CreateMathFunc\fR and \fBTcl_GetMathFuncInfo\fR functions
+are rendered somewhat obsolete by the ability to create functions for
+expressions by placing commands in the \fBtcl::mathfunc\fR namespace,
+as described in the \fBmathfunc\fR manual page; the API described on
+this page is not expected to be maintained indefinitely.
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+void
+\fBTcl_CreateMathFunc\fR(\fIinterp, name, numArgs, argTypes, proc, clientData\fR)
+.sp
+int
+\fBTcl_GetMathFuncInfo\fR(\fIinterp, name, numArgsPtr, argTypesPtr, procPtr,
+                    clientDataPtr\fR)
+.sp
+Tcl_Obj *
+\fBTcl_ListMathFuncs\fR(\fIinterp, pattern\fR)
+.SH ARGUMENTS
+.AS Tcl_ValueType *clientDataPtr out
+.AP Tcl_Interp *interp in
+Interpreter in which new function will be defined.
+.AP "const char" *name in
+Name for new function.
+.AP int numArgs in
+Number of arguments to new function;  also gives size of \fIargTypes\fR array.
+.AP Tcl_ValueType *argTypes in
+Points to an array giving the permissible types for each argument to
+function.
+.AP Tcl_MathProc *proc in
+Procedure that implements the function.
+.AP ClientData clientData in
+Arbitrary one-word value to pass to \fIproc\fR when it is invoked.
+.AP int *numArgsPtr out
+Points to a variable that will be set to contain the number of
+arguments to the function.
+.AP Tcl_ValueType **argTypesPtr out
+Points to a variable that will be set to contain a pointer to an array
+giving the permissible types for each argument to the function which
+will need to be freed up using \fITcl_Free\fR.
+.AP Tcl_MathProc **procPtr out
+Points to a variable that will be set to contain a pointer to the
+implementation code for the function (or NULL if the function is
+implemented directly in bytecode).
+.AP ClientData *clientDataPtr out
+Points to a variable that will be set to contain the clientData
+argument passed to \fITcl_CreateMathFunc\fR when the function was
+created if the function is not implemented directly in bytecode.
+.AP "const char" *pattern in
+Pattern to match against function names so as to filter them (by
+passing to \fITcl_StringMatch\fR), or NULL to not apply any filter.
+.BE
+.SH DESCRIPTION
+.PP
+Tcl allows a number of mathematical functions to be used in
+expressions, such as \fBsin\fR, \fBcos\fR, and \fBhypot\fR.
+These functions are represented by commands in the namespace,
+\fBtcl::mathfunc\fR.  The \fBTcl_CreateMathFunc\fR function is
+an obsolete way for applications to add additional functions
+to those already provided by Tcl or to replace existing functions.
+It should not be used by new applications, which should create
+math functions using \fBTcl_CreateObjCommand\fR to create a command
+in the \fBtcl::mathfunc\fR namespace.
+.PP
+In the \fBTcl_CreateMathFunc\fR interface,
+\fIName\fR is the name of the function as it will appear in expressions.
+If \fIname\fR does not already exist in the \fB::tcl::mathfunc\fR
+namespace, then a new command is created in that namespace.
+If \fIname\fR does exist, then the existing function is replaced.
+\fINumArgs\fR and \fIargTypes\fR describe the arguments to the function.
+Each entry in the \fIargTypes\fR array must be
+one of \fBTCL_INT\fR, \fBTCL_DOUBLE\fR, \fBTCL_WIDE_INT\fR,
+or \fBTCL_EITHER\fR to indicate whether the corresponding argument must be an
+integer, a double-precision floating value, a wide (64-bit) integer,
+or any, respectively.
+.PP
+Whenever the function is invoked in an expression Tcl will invoke
+\fIproc\fR.  \fIProc\fR should have arguments and result that match
+the type \fBTcl_MathProc\fR:
+.PP
+.CS
+typedef int \fBTcl_MathProc\fR(
+        ClientData \fIclientData\fR,
+        Tcl_Interp *\fIinterp\fR,
+        Tcl_Value *\fIargs\fR,
+        Tcl_Value *\fIresultPtr\fR);
+.CE
+.PP
+When \fIproc\fR is invoked the \fIclientData\fR and \fIinterp\fR
+arguments will be the same as those passed to \fBTcl_CreateMathFunc\fR.
+\fIArgs\fR will point to an array of \fInumArgs\fR Tcl_Value structures,
+which describe the actual arguments to the function:
+.PP
+.CS
+typedef struct Tcl_Value {
+    Tcl_ValueType \fItype\fR;
+    long \fIintValue\fR;
+    double \fIdoubleValue\fR;
+    Tcl_WideInt \fIwideValue\fR;
+} \fBTcl_Value\fR;
+.CE
+.PP
+The \fItype\fR field indicates the type of the argument and is
+one of \fBTCL_INT\fR, \fBTCL_DOUBLE\fR or \fBTCL_WIDE_INT\fR.
+It will match the \fIargTypes\fR value specified for the function unless
+the \fIargTypes\fR value was \fBTCL_EITHER\fR. Tcl converts
+the argument supplied in the expression to the type requested in
+\fIargTypes\fR, if that is necessary.
+Depending on the value of the \fItype\fR field, the \fIintValue\fR,
+\fIdoubleValue\fR or \fIwideValue\fR
+field will contain the actual value of the argument.
+.PP
+\fIProc\fR should compute its result and store it either as an integer
+in \fIresultPtr->intValue\fR or as a floating value in
+\fIresultPtr->doubleValue\fR.
+It should set also \fIresultPtr->type\fR to one of
+\fBTCL_INT\fR, \fBTCL_DOUBLE\fR or \fBTCL_WIDE_INT\fR
+to indicate which value was set.
+Under normal circumstances \fIproc\fR should return \fBTCL_OK\fR.
+If an error occurs while executing the function, \fIproc\fR should
+return \fBTCL_ERROR\fR and leave an error message in the interpreter's result.
+.PP
+\fBTcl_GetMathFuncInfo\fR retrieves the values associated with
+function \fIname\fR that were passed to a preceding
+\fBTcl_CreateMathFunc\fR call.  Normally, the return code is
+\fBTCL_OK\fR but if the named function does not exist, \fBTCL_ERROR\fR
+is returned and an error message is placed in the interpreter's
+result.
+.PP
+If an error did not occur, the array reference placed in the variable
+pointed to by \fIargTypesPtr\fR is newly allocated, and should be
+released by passing it to \fBTcl_Free\fR.  Some functions (the
+standard set implemented in the core, and those defined by placing
+commands in the \fBtcl::mathfunc\fR namespace) do not have
+argument type information; attempting to retrieve values for
+them causes a NULL to be stored in the variable pointed to by
+\fIprocPtr\fR and the variable pointed to by \fIclientDataPtr\fR
+will not be modified.  The variable pointed to by \fInumArgsPointer\fR
+will contain -1, and no argument types will be stored in the variable
+pointed to by \fIargTypesPointer\fR.
+.PP
+\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
+expression, mathematical function
@@ -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, Tcl_RegisterCommandTypeName, Tcl_GetCommandTypeName \- 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 \- implement new commands in C
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -43,13 +43,6 @@ void
 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
@@ -59,7 +52,7 @@ Name of command.
 .AP Tcl_ObjCmdProc *proc in
 Implementation of the new command: \fIproc\fR will be called whenever
 \fIcmdName\fR is invoked as a command.
-.AP void *clientData in
+.AP ClientData clientData in
 Arbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR.
 .AP Tcl_CmdDeleteProc *deleteProc in
 Procedure to call before \fIcmdName\fR is deleted from the interpreter;
@@ -102,7 +95,7 @@ and it returns NULL.
 .PP
 .CS
 typedef int \fBTcl_ObjCmdProc\fR(
-        void *\fIclientData\fR,
+        ClientData \fIclientData\fR,
        Tcl_Interp *\fIinterp\fR,
        int \fIobjc\fR,
        Tcl_Obj *const \fIobjv\fR[]);
@@ -175,7 +168,7 @@ result that match the type \fBTcl_CmdDeleteProc\fR:
 .PP
 .CS
 typedef void \fBTcl_CmdDeleteProc\fR(
-        void *\fIclientData\fR);
+        ClientData \fIclientData\fR);
 .CE
 .PP
 The \fIclientData\fR argument will be the same as the \fIclientData\fR
@@ -217,11 +210,11 @@ A \fBTcl_CmdInfo\fR structure has the following fields:
 typedef struct Tcl_CmdInfo {
    int \fIisNativeObjectProc\fR;
    Tcl_ObjCmdProc *\fIobjProc\fR;
-    void *\fIobjClientData\fR;
+    ClientData \fIobjClientData\fR;
    Tcl_CmdProc *\fIproc\fR;
-    void *\fIclientData\fR;
+    ClientData \fIclientData\fR;
    Tcl_CmdDeleteProc *\fIdeleteProc\fR;
-    void *\fIdeleteData\fR;
+    ClientData \fIdeleteData\fR;
    Tcl_Namespace *\fInamespacePtr\fR;
 } \fBTcl_CmdInfo\fR;
 .CE
@@ -247,7 +240,7 @@ otherwise, this is a compatibility procedure
 registered by \fBTcl_CreateObjCommand\fR
 that simply calls the command's
 value-based procedure after converting its string arguments to Tcl values.
-The field \fIdeleteData\fR is the clientData value
+The field \fIdeleteData\fR is the ClientData value
 to pass to \fIdeleteProc\fR;  it is normally the same as
 \fIclientData\fR but may be set independently using the
 \fBTcl_SetCommandInfo\fR procedure.
@@ -261,7 +254,7 @@ from \fBTcl_CreateObjCommand\fR in place of the command name.  If the
 and fills in the structure designated by \fIinfoPtr\fR.
 .PP
 \fBTcl_SetCommandInfo\fR is used to modify the procedures and
-clientData values associated with a command.
+ClientData values associated with a command.
 Its \fIcmdName\fR argument is the name of a command in \fIinterp\fR.
 \fIcmdName\fR may include \fB::\fR namespace qualifiers
 to identify a command in a particular namespace.
@@ -277,9 +270,9 @@ copies the information from \fI*infoPtr\fR to Tcl's internal structure
 for the command and returns 1.
 .PP
 Note that \fBTcl_SetCommandInfo\fR and
-\fBTcl_SetCommandInfoFromToken\fR both allow the clientData for a
+\fBTcl_SetCommandInfoFromToken\fR both allow the ClientData for a
 command's deletion procedure to be given a different value than the
-clientData for its command procedure.
+ClientData for its command procedure.
 .PP
 Note that neither \fBTcl_SetCommandInfo\fR nor
 \fBTcl_SetCommandInfoFromToken\fR will change a command's namespace.
@@ -308,21 +301,6 @@ 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,
@@ -24,7 +24,7 @@ Tcl_TimerToken
 How many milliseconds to wait before invoking \fIproc\fR.
 .AP Tcl_TimerProc *proc in
 Procedure to invoke after \fImilliseconds\fR have elapsed.
-.AP void *clientData in
+.AP ClientData clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .AP Tcl_TimerToken token in
 Token for previously created timer handler (the return value
@@ -51,7 +51,7 @@ the type \fBTcl_TimerProc\fR:
 .PP
 .CS
 typedef void \fBTcl_TimerProc\fR(
-        void *\fIclientData\fR);
+        ClientData \fIclientData\fR);
 .CE
 .PP
 The \fIclientData\fR parameter to \fIproc\fR is a
@@ -41,7 +41,7 @@ details of the calling sequence.
 .AP Tcl_CmdTraceProc *proc in
 Procedure to call for each command that is executed.  See below for
 details on the calling sequence.
-.AP void *clientData in
+.AP ClientData clientData in
 Arbitrary one-word value to pass to \fIobjProc\fR or \fIproc\fR.
 .AP Tcl_CmdObjTraceDeleteProc *deleteProc in
 Procedure to call when the trace is deleted.  See below for details of
@@ -66,7 +66,7 @@ interpreter.
 .PP
 .CS
 typedef int \fBTcl_CmdObjTraceProc\fR(
-        \fBvoid *\fR \fIclientData\fR,
+        \fBClientData\fR \fIclientData\fR,
        \fBTcl_Interp\fR* \fIinterp\fR,
        int \fIlevel\fR,
        const char *\fIcommand\fR,
@@ -77,7 +77,7 @@ typedef int \fBTcl_CmdObjTraceProc\fR(
 .PP
 The \fIclientData\fR and \fIinterp\fR parameters are copies of the
 corresponding arguments given to \fBTcl_CreateTrace\fR.
-\fIclientData\fR typically points to an application-specific data
+\fIClientData\fR typically points to an application-specific data
 structure that describes what to do when \fIobjProc\fR is invoked.  The
 \fIlevel\fR parameter gives the nesting level of the command (1 for
 top-level commands passed to \fBTcl_Eval\fR by the application, 2 for
@@ -99,11 +99,7 @@ the Tcl interpreter will invoke the command.  Any other return code
 is treated as if the command returned that status, and the command is
 \fInot\fR invoked.
 .PP
-The \fIobjProc\fR callback must not modify \fIobjv\fR in any way.  It
-is, however, permissible to change the command by calling
-\fBTcl_SetCommandTokenInfo\fR prior to returning.  Any such change
-takes effect immediately, and the command is invoked with the new
-information.
+The \fIobjProc\fR callback must not modify \fIobjv\fR in any way.
 .PP
 Tracing will only occur for commands at nesting level less than
 or equal to the \fIlevel\fR parameter (i.e. the \fIlevel\fR
@@ -144,7 +140,7 @@ When \fBTcl_DeleteTrace\fR is called, the interpreter invokes the
 .PP
 .CS
 typedef void \fBTcl_CmdObjTraceDeleteProc\fR(
-        \fBvoid *\fR \fIclientData\fR);
+        \fBClientData\fR \fIclientData\fR);
 .CE
 .PP
 The \fIclientData\fR parameter will be the same as the
@@ -160,12 +156,12 @@ match the type \fBTcl_CmdTraceProc\fR:
 .PP
 .CS
 typedef void \fBTcl_CmdTraceProc\fR(
-        void *\fIclientData\fR,
+        ClientData \fIclientData\fR,
        Tcl_Interp *\fIinterp\fR,
        int \fIlevel\fR,
        char *\fIcommand\fR,
        Tcl_CmdProc *\fIcmdProc\fR,
-        void *\fIcmdClientData\fR,
+        ClientData \fIcmdClientData\fR,
        int \fIargc\fR,
        const char *\fIargv\fR[]);
 .CE
@@ -9,7 +9,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_DStringInit, Tcl_DStringAppend, Tcl_DStringAppendElement, Tcl_DStringStartSublist, Tcl_DStringEndSublist, Tcl_DStringLength, Tcl_DStringValue, Tcl_DStringSetLength, Tcl_DStringFree, Tcl_DStringResult, Tcl_DStringGetResult \- manipulate dynamic strings
+Tcl_DStringInit, Tcl_DStringAppend, Tcl_DStringAppendElement, Tcl_DStringStartSublist, Tcl_DStringEndSublist, Tcl_DStringLength, Tcl_DStringValue, Tcl_DStringSetLength, Tcl_DStringTrunc, Tcl_DStringFree, Tcl_DStringResult, Tcl_DStringGetResult \- manipulate dynamic strings
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -26,7 +26,7 @@ char *
 .sp
 \fBTcl_DStringEndSublist\fR(\fIdsPtr\fR)
 .sp
-size_t
+int
 \fBTcl_DStringLength\fR(\fIdsPtr\fR)
 .sp
 char *
@@ -34,6 +34,8 @@ char *
 .sp
 \fBTcl_DStringSetLength\fR(\fIdsPtr, newLength\fR)
 .sp
+\fBTcl_DStringTrunc\fR(\fIdsPtr, newLength\fR)
+.sp
 \fBTcl_DStringFree\fR(\fIdsPtr\fR)
 .sp
 \fBTcl_DStringResult\fR(\fIinterp, dsPtr\fR)
@@ -47,10 +49,10 @@ Pointer to structure that is used to manage a dynamic string.
 Pointer to characters to append to dynamic string.
 .AP "const char" *element in
 Pointer to characters to append as list element to dynamic string.
-.AP size_t length in
-Number of bytes from \fIbytes\fR to add to dynamic string.  If TCL_INDEX_NONE,
+.AP int length in
+Number of bytes from \fIbytes\fR to add to dynamic string.  If -1,
 add all characters up to null terminating character.
-.AP size_t newLength in
+.AP int newLength in
 New length for dynamic string, not including null terminating
 character.
 .AP Tcl_Interp *interp in/out
@@ -126,6 +128,10 @@ caller to fill in the new space.
 even if the string is truncated to zero length, so \fBTcl_DStringFree\fR
 will still need to be called.
 .PP
+\fBTcl_DStringTrunc\fR changes the length of a dynamic string.
+This procedure is now deprecated.  \fBTcl_DStringSetLength\fR  should
+be used instead.
+.PP
 \fBTcl_DStringFree\fR should be called when you are finished using
 the string.  It frees up any memory that was allocated for the string
 and reinitializes the string's value to an empty string.
@@ -21,7 +21,7 @@ Tcl_DoWhenIdle, Tcl_CancelIdleCall \- invoke a procedure when there are no pendi
 .AS Tcl_IdleProc clientData
 .AP Tcl_IdleProc *proc in
 Procedure to invoke.
-.AP coid *clientData in
+.AP ClientData clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .BE
 .SH DESCRIPTION
@@ -43,7 +43,7 @@ type \fBTcl_IdleProc\fR:
 .PP
 .CS
 typedef void \fBTcl_IdleProc\fR(
-        void *\fIclientData\fR);
+        ClientData \fIclientData\fR);
 .CE
 .PP
 The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR
@@ -43,7 +43,7 @@ is not defined, these functions are all no-ops.
 \fBTcl_DumpActiveMemory\fR will output a list of all currently
 allocated memory to the specified file.  The information output for
 each allocated block of memory is:  starting and ending addresses
-(excluding guard zone), size, source file where \fBTcl_Alloc\fR was
+(excluding guard zone), size, source file where \fBckalloc\fR was
 called to allocate the block and line number in that file.  It is
 especially useful to call \fBTcl_DumpActiveMemory\fR after the Tcl
 interpreter has been deleted.
@@ -55,8 +55,8 @@ by \fBTcl_Main\fR.
 \fBTcl_ValidateAllMemory\fR forces a validation of the guard zones of
 all currently allocated blocks of memory.  Normally validation of a
 block occurs when its freed, unless full validation is enabled, in
-which case validation of all blocks occurs when \fBTcl_Alloc\fR and
-\fBTcl_Free\fR are called.  This function forces the validation to occur
+which case validation of all blocks occurs when \fBckalloc\fR and
+\fBckfree\fR are called.  This function forces the validation to occur
 at any point.

 .SH "SEE ALSO"
@@ -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_GetEncodingName, Tcl_SetSystemEncoding, Tcl_GetEncodingNameFromEnvironment, Tcl_GetEncodingNames, Tcl_CreateEncoding, Tcl_GetEncodingSearchPath, Tcl_SetEncodingSearchPath \- 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
@@ -25,13 +25,13 @@ int
 char *
 \fBTcl_ExternalToUtfDString\fR(\fIencoding, src, srcLen, dstPtr\fR)
 .sp
-size_t
+int
 \fBTcl_ExternalToUtfDStringEx\fR(\fIencoding, src, srcLen, flags, dstPtr\fR)
 .sp
 char *
 \fBTcl_UtfToExternalDString\fR(\fIencoding, src, srcLen, dstPtr\fR)
 .sp
-size_t
+int
 \fBTcl_UtfToExternalDStringEx\fR(\fIencoding, src, srcLen, flags, dstPtr\fR)
 .sp
 int
@@ -42,6 +42,12 @@ int
 \fBTcl_UtfToExternal\fR(\fIinterp, encoding, src, srcLen, flags, statePtr,
                  dst, dstLen, srcReadPtr, dstWrotePtr, dstCharsPtr\fR)
 .sp
+char *
+\fBTcl_WinTCharToUtf\fR(\fItsrc, srcLen, dstPtr\fR)
+.sp
+TCHAR *
+\fBTcl_WinUtfToTChar\fR(\fIsrc, srcLen, dstPtr\fR)
+.sp
 const char *
 \fBTcl_GetEncodingName\fR(\fIencoding\fR)
 .sp
@@ -62,6 +68,12 @@ Tcl_Obj *
 .sp
 int
 \fBTcl_SetEncodingSearchPath\fR(\fIsearchPath\fR)
+.sp
+const char *
+\fBTcl_GetDefaultEncodingDir\fR(\fIvoid\fR)
+.sp
+void
+\fBTcl_SetDefaultEncodingDir\fR(\fIpath\fR)
 .SH ARGUMENTS
 .AS "const Tcl_EncodingType" *dstWrotePtr in/out
 .AP Tcl_Interp *interp in
@@ -79,11 +91,11 @@ Points to storage where encoding token is to be written.
 .AP "const char" *src in
 For the \fBTcl_ExternalToUtf\fR functions, an array of bytes in the
 specified encoding that are to be converted to UTF-8.  For the
-\fBTcl_UtfToExternal\fR function, an array of
+\fBTcl_UtfToExternal\fR and \fBTcl_WinUtfToTChar\fR functions, an array of
 UTF-8 characters to be converted to the specified encoding.
 .AP "const TCHAR" *tsrc in
 An array of Windows TCHAR characters to convert to UTF-8.
-.AP size_t srcLen in
+.AP int srcLen in
 Length of \fIsrc\fR or \fItsrc\fR in bytes.  If the length is negative, the
 encoding-specific length of the string is used.
 .AP Tcl_DString *dstPtr out
@@ -99,13 +111,13 @@ converted. \fBTCL_ENCODING_END\fR signifies that the source buffer is the last
 block in a (potentially multi-block) input stream, telling the conversion
 routine to perform any finalization that needs to occur after the last
 byte is converted and then to reset to an initial state.
-\fBTCL_ENCODING_NOCOMPLAIN\fR signifies that the conversion routine should
-not return immediately upon reading a source character that does not exist in
-the target encoding, but it will substitute a default fallback character for
-all of such characters. The flag \fBTCL_ENCODING_STOPONERROR\fR has no effect,
-it only has meaning in Tcl 8.x. The flag \fBTCL_ENCODING_MODIFIED\fR makes
-\fBTcl_UtfToExternalDStringEx\fR and \fBTcl_UtfToExternal\fR produce the byte
-sequence \exC0\ex80 in stead of \ex00, for the utf-8/cesu-8 encoders.
+\fBTCL_ENCODING_STOPONERROR\fR signifies that the conversion routine should
+return immediately upon reading a source character that does not exist in
+the target encoding; otherwise a default fallback character will
+automatically be substituted. The flag \fBTCL_ENCODING_NOCOMPLAIN\fR has
+no effect, it is reserved for Tcl 9.0. The flag \fBTCL_ENCODING_MODIFIED\fR makes
+\fBTcl_UtfToExternalDStringEx\fR and \fBTcl_UtfToExternal\fR produce the
+byte sequence \exC0\ex80 in stead of \ex00, for the utf-8/cesu-8 encoders.
 .AP Tcl_EncodingState *statePtr in/out
 Used when converting a (generally long or indefinite length) byte stream
 in a piece-by-piece fashion.  The conversion routine stores its current
@@ -236,7 +248,7 @@ if the input stream has been damaged or if the input encoding method was
 misidentified.
 .IP \fBTCL_CONVERT_UNKNOWN\fR 29
 The source buffer contained a character that could not be represented in
-the target encoding and \fBTCL_ENCODING_NOCOMPLAIN\fR was not specified.
+the target encoding and \fBTCL_ENCODING_STOPONERROR\fR was specified.
 .RE
 .LP
 \fBTcl_UtfToExternalDString\fR converts a source buffer \fIsrc\fR from UTF-8
@@ -262,6 +274,18 @@ 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. 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
 was used to create the encoding.  The string returned by
@@ -288,7 +312,7 @@ the encoding name to it.  The \fBTcl_DStringValue\fR is returned.
 \fBTcl_GetEncodingNames\fR sets the \fIinterp\fR result to a list
 consisting of the names of all the encodings that are currently defined
 or can be dynamically loaded, searching the encoding path specified by
-\fBTcl_SetEncodingSearchPath\fR.  This procedure does not ensure that the
+\fBTcl_SetDefaultEncodingDir\fR.  This procedure does not ensure that the
 dynamically-loadable encoding files contain valid data, but merely that they
 exist.
 .PP
@@ -315,7 +339,7 @@ typedef struct Tcl_EncodingType {
    Tcl_EncodingConvertProc *\fItoUtfProc\fR;
    Tcl_EncodingConvertProc *\fIfromUtfProc\fR;
    Tcl_EncodingFreeProc *\fIfreeProc\fR;
-    void *\fIclientData\fR;
+    ClientData \fIclientData\fR;
    int \fInullSize\fR;
 } \fBTcl_EncodingType\fR;
 .CE
@@ -346,7 +370,7 @@ type \fBTcl_EncodingConvertProc\fR:
 .PP
 .CS
 typedef int \fBTcl_EncodingConvertProc\fR(
-        void *\fIclientData\fR,
+        ClientData \fIclientData\fR,
        const char *\fIsrc\fR,
        int \fIsrcLen\fR,
        int \fIflags\fR,
@@ -378,7 +402,7 @@ The callback procedure \fIfreeProc\fR, if non-NULL, should match the type
 .PP
 .CS
 typedef void \fBTcl_EncodingFreeProc\fR(
-        void *\fIclientData\fR);
+        ClientData \fIclientData\fR);
 .CE
 .PP
 This \fIfreeProc\fR function is called when the encoding is deleted.  The
@@ -403,6 +427,15 @@ are not verified as existing readable filesystem directories.  When
 searching for encoding data files takes place, and non-existent or
 non-readable filesystem directories on the \fIsearchPath\fR are silently
 ignored.
+.PP
+\fBTcl_GetDefaultEncodingDir\fR and \fBTcl_SetDefaultEncodingDir\fR
+are obsolete interfaces best replaced with calls to
+\fBTcl_GetEncodingSearchPath\fR and \fBTcl_SetEncodingSearchPath\fR.
+They are called to access and set the first element of the \fIsearchPath\fR
+list.  Since Tcl searches \fIsearchPath\fR for encoding data files in
+list order, these routines establish the
+.QW default
+directory in which to find encoding data files.
 .SH "ENCODING FILES"
 Space would prohibit precompiling into Tcl every possible encoding
 algorithm, so many encodings are stored on disk as dynamically-loadable
@@ -10,7 +10,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_EvalObjEx, Tcl_EvalFile, Tcl_EvalObjv, Tcl_Eval, Tcl_EvalEx, Tcl_GlobalEval, Tcl_GlobalEvalObj, Tcl_VarEval \- execute Tcl scripts
+Tcl_EvalObjEx, Tcl_EvalFile, Tcl_EvalObjv, Tcl_Eval, Tcl_EvalEx, Tcl_GlobalEval, Tcl_GlobalEvalObj, Tcl_VarEval, Tcl_VarEvalVA \- execute Tcl scripts
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -38,6 +38,9 @@ int
 .sp
 int
 \fBTcl_VarEval\fR(\fIinterp, part, part, ... \fB(char *) NULL\fR)
+.sp
+int
+\fBTcl_VarEvalVA\fR(\fIinterp, argList\fR)
 .SH ARGUMENTS
 .AS Tcl_Interp **termPtr
 .AP Tcl_Interp *interp in
@@ -64,6 +67,9 @@ first null byte are used.
 Points to first byte of script to execute (null-terminated and UTF-8).
 .AP "const char" *part in
 String forming part of a Tcl script.
+.AP va_list argList in
+An argument list which must have been initialized using
+\fBva_start\fR, and cleared using \fBva_end\fR.
 .BE

 .SH DESCRIPTION
@@ -122,10 +128,16 @@ might be a UTF-8 special code.  The string is parsed and executed directly
 bytecodes.  In situations where it is known that the script will never be
 executed again, \fBTcl_Eval\fR may be faster than \fBTcl_EvalObjEx\fR.
 \fBTcl_Eval\fR returns a completion code and result just like
-\fBTcl_EvalObjEx\fR.
+\fBTcl_EvalObjEx\fR.  Note: for backward compatibility with versions before
+Tcl 8.0, \fBTcl_Eval\fR copies the value result in \fIinterp\fR to
+\fIinterp->result\fR (use is deprecated) where it can be accessed directly.
+ This makes \fBTcl_Eval\fR somewhat slower than \fBTcl_EvalEx\fR, which
+does not do the copy.
 .PP
 \fBTcl_EvalEx\fR is an extended version of \fBTcl_Eval\fR that takes
-additional arguments \fInumBytes\fR and \fIflags\fR.
+additional arguments \fInumBytes\fR and \fIflags\fR.  For the
+efficiency reason given above, \fBTcl_EvalEx\fR is generally preferred
+over \fBTcl_Eval\fR.
 .PP
 \fBTcl_GlobalEval\fR and \fBTcl_GlobalEvalObj\fR are older procedures
 that are now deprecated.  They are similar to \fBTcl_EvalEx\fR and
@@ -141,6 +153,11 @@ It returns the result of the command and also modifies
 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. 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
@@ -42,7 +42,7 @@ usually means that an error occurred.
 Procedure to invoke before exiting application, or (for
 \fBTcl_SetExitProc\fR) NULL to uninstall the current application exit
 procedure.
-.AP void *clientData in
+.AP ClientData clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .BE

@@ -64,7 +64,7 @@ otherwise causes the application to terminate without calling
 returns control to its caller.
 If an application exit handler has been installed (see
 \fBTcl_SetExitProc\fR), that handler is invoked with an argument
-consisting of the exit status (cast to void *); the application
+consisting of the exit status (cast to ClientData); the application
 exit handler should not return control to Tcl.
 .PP
 \fBTcl_Finalize\fR is similar to \fBTcl_Exit\fR except that it does not
@@ -93,7 +93,7 @@ and freeing global memory.
 .PP
 .CS
 typedef void \fBTcl_ExitProc\fR(
-        void *\fIclientData\fR);
+        ClientData \fIclientData\fR);
 .CE
 .PP
 The \fIclientData\fR parameter to \fIproc\fR is a
@@ -133,9 +133,10 @@ installed, that exit handler takes over complete responsibility for
 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 void *value.
+cast to a ClientData value.
 .PP
-\fBTcl_SetExitProc\fR can not be used in stub-enabled extensions.
+\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
@@ -20,7 +20,7 @@ int
 int
 \fBTcl_FSUnregister\fR(\fIfsPtr\fR)
 .sp
-void *
+ClientData
 \fBTcl_FSData\fR(\fIfsPtr\fR)
 .sp
 void
@@ -123,7 +123,7 @@ Tcl_Obj *
 int
 \fBTcl_FSConvertToPathType\fR(\fIinterp, pathPtr\fR)
 .sp
-void *
+ClientData
 \fBTcl_FSGetInternalRep\fR(\fIpathPtr, fsPtr\fR)
 .sp
 Tcl_Obj *
@@ -210,7 +210,7 @@ this structure will be returned. This parameter may be NULL.
 .AP Tcl_Interp *interp in
 Interpreter to use either for results, evaluation, or reporting error
 messages.
-.AP void *clientData in
+.AP ClientData clientData in
 The native description of the path value to create.
 .AP Tcl_Obj *firstPtr in
 The first of two path values to compare. The value may be converted
@@ -251,7 +251,7 @@ Name of a procedure to look up in the file's symbol table
 Filled with the init function for this code.
 .AP Tcl_LibraryInitProc **proc2Ptr out
 Filled with the safe-init function for this code.
-.AP void **clientDataPtr out
+.AP ClientData *clientDataPtr out
 Filled with the clientData value to pass to this code's unload
 function when it is called.
 .AP Tcl_LoadHandle *loadHandlePtr out
@@ -722,7 +722,7 @@ better functions to use for most purposes.
 \fBTcl_FSGetTranslatedStringPath\fR does the same as
 \fBTcl_FSGetTranslatedPath\fR, but returns a character string or NULL.
 The string returned is dynamically allocated and owned by the caller,
-which must store it or call \fBTcl_Free\fR to ensure it is freed. Again,
+which must store it or call \fBckfree\fR to ensure it is freed. Again,
 \fBTcl_FSGetNormalizedPath\fR or \fBTcl_FSGetNativePath\fR are usually
 better functions to use for most purposes.
 .PP
@@ -789,7 +789,7 @@ It returns one of \fBTCL_PATH_ABSOLUTE\fR, \fBTCL_PATH_RELATIVE\fR, or
 .SS "PORTABLE STAT RESULT API"
 .PP
 \fBTcl_AllocStatBuf\fR allocates a \fITcl_StatBuf\fR on the system heap (which
-may be deallocated by being passed to \fBTcl_Free\fR). This allows extensions to
+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
@@ -837,7 +837,7 @@ general that is not a good thing to do). \fBTCL_OK\fR will be returned.
 the list of known filesystems, if it is known, and returns \fBTCL_OK\fR. If
 the filesystem is not currently registered, \fBTCL_ERROR\fR is returned.
 .PP
-\fBTcl_FSData\fR will return the clientData associated with the given
+\fBTcl_FSData\fR will return the ClientData associated with the given
 filesystem, if that filesystem is registered. Otherwise it will
 return NULL.
 .PP
@@ -1014,7 +1014,7 @@ Tcl's internal list of known filesystems.
 .CS
 typedef int \fBTcl_FSPathInFilesystemProc\fR(
        Tcl_Obj *\fIpathPtr\fR,
-        void **\fIclientDataPtr\fR);
+        ClientData *\fIclientDataPtr\fR);
 .CE
 .SS DUPINTERNALREPPROC
 .PP
@@ -1024,8 +1024,8 @@ simply not copy the internal representation, which may then need to be
 regenerated later.
 .PP
 .CS
-typedef void *\fBTcl_FSDupInternalRepProc\fR(
-        void *\fIclientData\fR);
+typedef ClientData \fBTcl_FSDupInternalRepProc\fR(
+        ClientData \fIclientData\fR);
 .CE
 .SS FREEINTERNALREPPROC
 Free the internal representation. This must be implemented if internal
@@ -1034,7 +1034,7 @@ internal representation is generated), but may otherwise be NULL.
 .PP
 .CS
 typedef void \fBTcl_FSFreeInternalRepProc\fR(
-        void *\fIclientData\fR);
+        ClientData \fIclientData\fR);
 .CE
 .SS INTERNALTONORMALIZEDPROC
 .PP
@@ -1045,7 +1045,7 @@ representation is the normalized path.
 .PP
 .CS
 typedef Tcl_Obj *\fBTcl_FSInternalToNormalizedProc\fR(
-        void *\fIclientData\fR);
+        ClientData \fIclientData\fR);
 .CE
 .SS CREATEINTERNALREPPROC
 .PP
@@ -1056,7 +1056,7 @@ the \fITcl_FSPathInFilesystemProc\fR for this filesystem always
 immediately creates an internal representation for paths it accepts.
 .PP
 .CS
-typedef void *\fBTcl_FSCreateInternalRepProc\fR(
+typedef ClientData \fBTcl_FSCreateInternalRepProc\fR(
        Tcl_Obj *\fIpathPtr\fR);
 .CE
 .SS NORMALIZEPATHPROC
@@ -35,8 +35,8 @@ Tcl.  For example, it is needed on some platforms in the
 implementation of the \fBload\fR command.
 It is also returned by the \fBinfo nameofexecutable\fR command.
 .PP
-The result of \fBTcl_FindExecutable\fR is the full Tcl version with
-build information (e.g., \fB9.0.0+abcdef...abcdef.gcc-1002\fR).
+The result of \fBTcl_FindExecutable\fR is the full Tcl version (e.g.,
+\fB8.7.0+abcdef...abcdef.gcc-1002.utf16\fR).
 .PP
 On UNIX platforms this procedure is typically invoked as the very
 first thing in the application's main program;  it must be passed
@@ -62,6 +62,7 @@ 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.
+\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
@@ -62,9 +62,12 @@ if the first such characters are
 then \fIsrc\fR is expected to be in octal form;  otherwise,
 if the first such characters are
 .QW \fB0b\fR
+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 binary 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
@@ -28,7 +28,7 @@ be used for reading.
 .AP int checkUsage in
 If non-zero, then an error will be generated if the file was not opened
 for the access indicated by \fIwrite\fR.
-.AP void **filePtr out
+.AP ClientData *filePtr out
 Points to word in which to store pointer to FILE structure for
 the file given by \fIchanID\fR.
 .BE
@@ -27,13 +27,13 @@ Pointer to handler function replacing \fBTcl_GetTime\fR's access to the OS.
 .AP Tcl_ScaleTimeProc scaleProc in
 Pointer to handler function for the conversion of time delays in the
 virtual domain to real-time.
-.AP void *clientData in
+.AP ClientData clientData in
 Value passed through to the two handler functions.
 .AP Tcl_GetTimeProc *getProcPtr out
 Pointer to place the currently registered get handler function into.
 .AP Tcl_ScaleTimeProc *scaleProcPtr out
 Pointer to place the currently registered scale handler function into.
-.AP void **clientDataPtr out
+.AP ClientData *clientDataPtr out
 Pointer to place the currently registered pass-through value into.
 .BE
 .SH DESCRIPTION
@@ -83,10 +83,10 @@ The signatures of the handler functions are as follows:
 .CS
 typedef void \fBTcl_GetTimeProc\fR(
        Tcl_Time *\fItimebuf\fR,
-        void *\fIclientData\fR);
+        ClientData \fIclientData\fR);
 typedef void \fBTcl_ScaleTimeProc\fR(
        Tcl_Time *\fItimebuf\fR,
-        void *\fIclientData\fR);
+        ClientData \fIclientData\fR);
 .CE
 .PP
 The \fItimebuf\fR fields contain the time to manipulate, and the
@@ -30,7 +30,7 @@ Tcl_HashEntry *
 Tcl_HashEntry *
 \fBTcl_FindHashEntry\fR(\fItablePtr, key\fR)
 .sp
-void *
+ClientData
 \fBTcl_GetHashValue\fR(\fIentryPtr\fR)
 .sp
 \fBTcl_SetHashValue\fR(\fIentryPtr, value\fR)
@@ -66,8 +66,9 @@ The word at \fI*newPtr\fR is set to 1 if a new entry was created
 and 0 if there was already an entry for \fIkey\fR.
 .AP Tcl_HashEntry *entryPtr in
 Pointer to hash table entry.
-.AP void *value in
-New value to assign to hash table entry.
+.AP ClientData value in
+New value to assign to hash table entry.  Need not have type
+ClientData, but must fit in same space as ClientData.
 .AP Tcl_HashSearch *searchPtr in
 Pointer to record to use to keep track of progress in enumerating
 all the entries in a hash table.
@@ -185,6 +186,11 @@ instead, it returns NULL as result.
 .PP
 \fBTcl_GetHashValue\fR and \fBTcl_SetHashValue\fR are used to
 read and write an entry's value, respectively.
+Values are stored and retrieved as type
+.QW ClientData ,
+which is
+large enough to hold a pointer value.  On almost all machines this is
+large enough to hold an integer value too.
 .PP
 \fBTcl_GetHashKey\fR returns the key for a given hash table entry,
 either as a pointer to a string, a one-word
@@ -223,7 +229,7 @@ overall information about a hash table, such as the number of
 entries it contains, the number of buckets in its hash array,
 and the utilization of the buckets.
 It is the caller's responsibility to free the result string
-by passing it to \fBTcl_Free\fR.
+by passing it to \fBckfree\fR.
 .PP
 The header file \fBtcl.h\fR defines the actual data structures
 used to implement hash tables.
@@ -2,7 +2,7 @@
 '\" Copyright (c) 1998-2000 Scriptics Corporation.
 '\" All rights reserved.
 '\"
-.TH Tcl_Init 3 9.0 Tcl "Tcl Library Procedures"
+.TH Tcl_Init 3 8.7 Tcl "Tcl Library Procedures"
 .so man.macros
 .BS
 .SH NAME
@@ -39,10 +39,6 @@ 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.

-When used in stub-enabled embedders, the stubs table must be first initialized
-using one of \fBTcl_InitSubsystems\fR, \fBTcl_SetPanicProc\fR, \fBTcl_FindExecutable\fR
-or \fBTclZipfs_AppHook\fR before \fBTcl_SetPreInitScript\fR may be called.
-
 .SH "SEE ALSO"
 Tcl_AppInit, Tcl_Main

@@ -63,9 +63,9 @@ Define the \fBUSE_TCL_STUBS\fR symbol.  Typically, you would include the
 \fB\-DUSE_TCL_STUBS\fR flag when compiling the extension.
 .IP 3) 5
 Link the extension with the Tcl stubs library instead of the standard
-Tcl library.  For example, to use the Tcl 9.0 ABI on Unix platforms,
-the library name is \fIlibtclstub9.0.a\fR; on Windows platforms, the
-library name is \fItclstub90.lib\fR.
+Tcl library.  For example, to use the Tcl 8.6 ABI on Unix platforms,
+the library name is \fIlibtclstub8.6.a\fR; on Windows platforms, the
+library name is \fItclstub86.lib\fR.
 .PP
 If the extension also requires the Tk API, it must also call
 \fBTk_InitStubs\fR to initialize the Tk stubs interface and link
@@ -21,14 +21,14 @@ 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
-The result of \fBTcl_InitSubsystems\fR is the full Tcl version with
-build information (e.g., \fB9.0.0+abcdef...abcdef.gcc-1002\fR).
+The result of \fBTcl_InitSubsystems\fR is the full Tcl version (e.g.,
+\fB8.7.0+abcdef...abcdef.gcc-1002.utf16\fR).
 .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 utf-8,
+used as utility library, no other encodings than utf8,
 iso8859-1 or utf-16 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 utf-8.
+be extracted from the environment, but falls back to iso8859-1.
 .SH KEYWORDS
 binary, executable file
@@ -32,7 +32,7 @@ int
 \fBTcl_GetIntFromObj\fR(\fIinterp, objPtr, intPtr\fR)
 .sp
 int
-\fBTcl_GetIntForIndex\fR(\fIinterp, objPtr, endValue, indexPtr\fR)
+\fBTcl_GetIntForIndex\fR(\fIinterp, objPtr, endValue, intPtr\fR)
 .sp
 int
 \fBTcl_GetLongFromObj\fR(\fIinterp, objPtr, longPtr\fR)
@@ -58,7 +58,7 @@ int
 \fBTcl_InitBignumFromDouble\fR(\fIinterp, doubleValue, bigValue\fR)
 .SH ARGUMENTS
 .AS Tcl_WideInt doubleValue in/out
-.AP size_t endValue in
+.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.
@@ -80,8 +80,6 @@ retrieval fails.
 Points to place to store the integer value retrieved from \fIobjPtr\fR.
 .AP long *longPtr out
 Points to place to store the long integer value retrieved from \fIobjPtr\fR.
-.AP size_t *indexPtr out
-Points to place to store the size_t value retrieved from \fIobjPtr\fR.
 .AP Tcl_WideInt *widePtr out
 Points to place to store the wide integer value retrieved from \fIobjPtr\fR.
 .AP mp_int *bigValue in/out
@@ -0,0 +1,41 @@
+'\"
+'\" Copyright (c) 1989-1993 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" 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 8.7 Tcl "Tcl Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tcl_Interp \- client-visible fields of interpreter structures
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+typedef struct {
+    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(
+        char *\fIblockPtr\fR);
+.BE
+.SH DESCRIPTION
+.PP
+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 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
+interpreter, result
@@ -83,7 +83,7 @@ the handler returns.  Many handlers may be attached to the same
 interpreter limit; their order of execution is not defined, and they
 must be identified by \fIhandlerProc\fR and \fIclientData\fR when they
 are deleted.
-.AP void *clientData in
+.AP ClientData clientData in
 Arbitrary pointer-sized word used to pass some context to the
 \fIhandlerProc\fR function.
 .AP Tcl_LimitHandlerDeleteProc *deleteProc in
@@ -162,7 +162,7 @@ following prototype:
 .PP
 .CS
 typedef void \fBTcl_LimitHandlerProc\fR(
-        void *\fIclientData\fR,
+        ClientData \fIclientData\fR,
        Tcl_Interp *\fIinterp\fR);
 .CE
 .PP
@@ -179,7 +179,7 @@ following prototype:
 .PP
 .CS
 typedef void \fBTcl_LimitHandlerDeleteProc\fR(
-        void *\fIclientData\fR);
+        ClientData \fIclientData\fR);
 .CE
 .PP
 A limit handler may be deleted using \fBTcl_LimitRemoveHandler\fR; the
@@ -53,13 +53,13 @@ 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.
+\fBTCL_LINK_BINARY\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 size_t size in
+.AP int size in
 .VS "TIP 312"
 The number of elements in the C array. Must be greater than zero.
 .VE "TIP 312"
@@ -146,11 +146,11 @@ 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.
+If using an array of these, consider using \fBTCL_LINK_BINARY\fR instead.
 .VE "TIP 312"
 .RE
 .TP
-\fBTCL_LINK_BYTES\fR
+\fBTCL_LINK_BINARY\fR
 .VS "TIP 312"
 The C array is of type \fBunsigned char *\fR and is mapped into Tcl
 as a bytearray.
@@ -265,7 +265,7 @@ Tcl errors.
 .
 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.
+allocated with \fBTcl_Alloc\fR or \fBckalloc\fR.
 Whenever the Tcl variable is modified the current C string will be
 freed and new memory will be allocated to hold a copy of the variable's
 new value.
@@ -61,7 +61,7 @@ Tcl_Object
 int
 \fBTcl_ObjectContextSkippedArgs\fR(\fIcontext\fR)
 .SH ARGUMENTS
-.AS void *clientData in
+.AS ClientData clientData in
 .AP Tcl_Interp *interp in/out
 The interpreter holding the object or class to create or update a method in.
 .AP Tcl_Object object in
@@ -83,10 +83,10 @@ and \fBTCL_OO_METHOD_PRIVATE\fR for a private method.
 .AP Tcl_MethodType *methodTypePtr in
 A description of the type of the method to create, or the type of method to
 compare against.
-.AP void *clientData in
+.AP ClientData clientData in
 A piece of data that is passed to the implementation of the method without
 interpretation.
-.AP void **clientDataPtr out
+.AP ClientData *clientDataPtr out
 A pointer to a variable in which to write the \fIclientData\fR value supplied
 when the method was created. If NULL, the \fIclientData\fR value will not be
 retrieved.
@@ -213,7 +213,7 @@ Functions matching this signature are called when the method is invoked.
 .PP
 .CS
 typedef int \fBTcl_MethodCallProc\fR(
-        void *\fIclientData\fR,
+        ClientData \fIclientData\fR,
        Tcl_Interp *\fIinterp\fR,
        Tcl_ObjectContext \fIobjectContext\fR,
        int \fIobjc\fR,
@@ -234,7 +234,7 @@ through a new method being created or because the object or class is deleted.
 .PP
 .CS
 typedef void \fBTcl_MethodDeleteProc\fR(
-        void *\fIclientData\fR);
+        ClientData \fIclientData\fR);
 .CE
 .PP
 The \fIclientData\fR argument to a Tcl_MethodDeleteProc will be the same as
@@ -248,8 +248,8 @@ class is copied using \fBTcl_CopyObjectInstance\fR (or \fBoo::copy\fR).
 .CS
 typedef int \fBTcl_CloneProc\fR(
        Tcl_Interp *\fIinterp\fR,
-        void *\fIoldClientData\fR,
-        void **\fInewClientDataPtr\fR);
+        ClientData \fIoldClientData\fR,
+        ClientData *\fInewClientDataPtr\fR);
 .CE
 .PP
 The \fIinterp\fR argument gives a place to write an error message when the
@@ -49,7 +49,7 @@ in the same way as the \fIproc\fR argument to \fBTcl_CreateObjCommand\fR(3)
 (\fIq.v.\fR).
 .AP Tcl_ObjCmdProc *nreProc in
 Called instead of \fIproc\fR when a trampoline is already in use.
-.AP void *clientData in
+.AP ClientData clientData in
 Arbitrary one-word value passed to \fIproc\fR, \fInreProc\fR, \fIdeleteProc\fR
 and \fIobjProc\fR.
 .AP Tcl_CmdDeleteProc *deleteProc in/out
@@ -72,10 +72,10 @@ Pointer to an unshared Tcl_Obj where the result of the evaluation is stored if
 the return code is TCL_OK.
 .AP Tcl_NRPostProc *postProcPtr in
 A function to push.
-.AP void *data0 in
-.AP void *data1 in
-.AP void *data2 in
-.AP void *data3 in
+.AP ClientData data0 in
+.AP ClientData data1 in
+.AP ClientData data2 in
+.AP ClientData data3 in
 \fIdata0\fR through \fIdata3\fR are four one-word values that will be passed
 to the function designated by \fIpostProcPtr\fR when it is invoked.
 .BE
@@ -130,7 +130,7 @@ a message as the interpreter's result.
 .CS
 typedef int
 \fBTcl_NRPostProc\fR(
-        \fBvoid *\fR \fIdata\fR[],
+        \fBClientData\fR \fIdata\fR[],
        \fBTcl_Interp\fR *\fIinterp\fR,
        int \fIresult\fR);
 .CE
@@ -146,7 +146,7 @@ stack, to evalute a script:
 .CS
 int
 \fITheCmdOldObjProc\fR(
-    void *clientData,
+    ClientData clientData,
    Tcl_Interp *interp,
    int objc,
    Tcl_Obj *const objv[])
@@ -177,7 +177,7 @@ call \fITheCmdNRObjProc\fR:
 .CS
 int
 \fITheCmdOldObjProc\fR(
-    void *clientData,
+    ClientData clientData,
    Tcl_Interp *interp,
    int objc,
    Tcl_Obj *const objv[])
@@ -190,7 +190,7 @@ int
 .CS
 int
 \fITheCmdNRObjProc\fR
-    void *clientData,
+    ClientData clientData,
    Tcl_Interp *interp,
    int objc,
    Tcl_Obj *const objv[])
@@ -211,7 +211,7 @@ int
 .CS
 int
 \fITheCmdNRPostProc\fR(
-    void *data[],
+    ClientData data[],
    Tcl_Interp *interp,
    int result)
 {
@@ -57,7 +57,7 @@ The interpreter in which the namespace exists and where name lookups
 are performed. Also where error result messages are written.
 .AP "const char" *name in
 The name of the namespace or command to be created or accessed.
-.AP void *clientData in
+.AP ClientData clientData in
 A context pointer by the creator of the namespace.  Not interpreted by
 Tcl at all.
 .AP Tcl_NamespaceDeleteProc *deleteProc in
@@ -117,7 +117,7 @@ the global namespace.)
 .PP
 .CS
 typedef void \fBTcl_NamespaceDeleteProc\fR(
-        void *\fIclientData\fR);
+        ClientData \fIclientData\fR);
 .CE
 .PP
 \fBTcl_DeleteNamespace\fR deletes a namespace, calling the
@@ -38,7 +38,7 @@ Tcl_ThreadId
 void
 \fBTcl_DeleteEvents\fR(\fIdeleteProc, clientData\fR)
 .sp
-void *
+ClientData
 \fBTcl_InitNotifier\fR()
 .sp
 void
@@ -78,7 +78,7 @@ Procedure to invoke to prepare for event wait in \fBTcl_DoOneEvent\fR.
 Procedure for \fBTcl_DoOneEvent\fR to invoke after waiting for
 events.  Checks to see if any events have occurred and, if so,
 queues them.
-.AP void *clientData in
+.AP ClientData clientData in
 Arbitrary one-word value to pass to \fIsetupProc\fR, \fIcheckProc\fR, or
 \fIdeleteProc\fR.
 .AP "const Tcl_Time" *timePtr in
@@ -89,10 +89,11 @@ is NULL, it means there is no maximum wait time:  wait forever if
 necessary.
 .AP Tcl_Event *evPtr in
 An event to add to the event queue.  The storage for the event must
-have been allocated by the caller using \fBTcl_Alloc\fR.
-.AP Tcl_QueuePosition position in
+have been allocated by the caller using \fBTcl_Alloc\fR or \fBckalloc\fR.
+.AP int position in
 Where to add the new event in the queue:  \fBTCL_QUEUE_TAIL\fR,
-\fBTCL_QUEUE_HEAD\fR, or \fBTCL_QUEUE_MARK\fR.
+\fBTCL_QUEUE_HEAD\fR, \fBTCL_QUEUE_MARK\fR, and whether to do
+an alert if the queue is empty: \fBTCL_QUEUE_ALERT_IF_EMPTY\fR.
 .AP Tcl_ThreadId threadId in
 A unique identifier for a thread.
 .AP Tcl_EventDeleteProc *deleteProc in
@@ -225,7 +226,7 @@ the event source.
 .PP
 .CS
 typedef void \fBTcl_EventSetupProc\fR(
-        void *\fIclientData\fR,
+        ClientData \fIclientData\fR,
        int \fIflags\fR);
 .CE
 .PP
@@ -303,7 +304,7 @@ following prototype:
 .PP
 .CS
 typedef void \fBTcl_EventCheckProc\fR(
-        void *\fIclientData\fR,
+        ClientData \fIclientData\fR,
        int \fIflags\fR);
 .CE
 .PP
@@ -340,14 +341,14 @@ and should not be modified by the event source.
 .PP
 An event may be added to the queue at any of three positions, depending
 on the \fIposition\fR argument to \fBTcl_QueueEvent\fR:
-.IP \fBTCL_QUEUE_TAIL\fR 24
+.IP \fBTCL_QUEUE_TAIL\fR 32
 Add the event at the back of the queue, so that all other pending
 events will be serviced first.  This is almost always the right
 place for new events.
-.IP \fBTCL_QUEUE_HEAD\fR 24
+.IP \fBTCL_QUEUE_HEAD\fR 32
 Add the event at the front of the queue, so that it will be serviced
 before all other queued events.
-.IP \fBTCL_QUEUE_MARK\fR 24
+.IP \fBTCL_QUEUE_MARK\fR 32
 Add the event at the front of the queue, unless there are other
 events at the front whose position is \fBTCL_QUEUE_MARK\fR;  if so,
 add the new event just after all other \fBTCL_QUEUE_MARK\fR events.
@@ -355,6 +356,10 @@ This value of \fIposition\fR is used to insert an ordered sequence of
 events at the front of the queue, such as a series of
 Enter and Leave events synthesized during a grab or ungrab operation
 in Tk.
+.IP \fBTCL_QUEUE_ALERT_IF_EMPTY\fR 32
+When used in \fBTcl_ThreadQueueEvent\fR
+arranges for an automatic call of \fBTcl_ThreadAlert\fR when the queue was
+empty.
 .PP
 When it is time to handle an event from the queue (steps 1 and 4
 above) \fBTcl_ServiceEvent\fR will invoke the \fIproc\fR specified
@@ -394,7 +399,7 @@ of window events.
 When \fIproc\fR returns 1, \fBTcl_ServiceEvent\fR will remove the
 event from the event queue and free its storage.
 Note that the storage for an event must be allocated by
-the event source (using \fBTcl_Alloc\fR)
+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
@@ -419,7 +424,7 @@ queue.  \fIProc\fR should match the following prototype:
 .CS
 typedef int \fBTcl_EventDeleteProc\fR(
        Tcl_Event *\fIevPtr\fR,
-        void *\fIclientData\fR);
+        ClientData \fIclientData\fR);
 .CE
 .PP
 The \fIclientData\fR argument will be the same as the \fIclientData\fR
@@ -111,9 +111,9 @@ which is defined as follows.
 .PP
 .CS
 typedef struct Tcl_Obj {
-    size_t \fIrefCount\fR;
+    int \fIrefCount\fR;
    char *\fIbytes\fR;
-    size_t \fIlength\fR;
+    int \fIlength\fR;
    const Tcl_ObjType *\fItypePtr\fR;
    union {
        long \fIlongValue\fR;
@@ -184,8 +184,8 @@ to be treated as conventional null character-terminated C strings.
 These restrictions are easily met by using Tcl's internal UTF encoding
 for the string representation, same as one would do for other
 Tcl routines accepting string values as arguments.
-Storage for the byte array must be allocated in the heap by \fBTcl_Alloc\fR.
-Note that \fIupdateStringProc\fRs must allocate
+Storage for the byte array must be allocated in the heap by \fBTcl_Alloc\fR
+or \fBckalloc\fR.  Note that \fIupdateStringProc\fRs must allocate
 enough storage for the string's bytes and the terminating null byte.
 .PP
 The \fIupdateStringProc\fR for Tcl's built-in double type, for example,
@@ -53,28 +53,28 @@ int
 int
 \fBTcl_Read\fR(\fIchannel, readBuf, bytesToRead\fR)
 .sp
-size_t
+int
 \fBTcl_GetsObj\fR(\fIchannel, lineObjPtr\fR)
 .sp
-size_t
+int
 \fBTcl_Gets\fR(\fIchannel, lineRead\fR)
 .sp
-size_t
+int
 \fBTcl_Ungets\fR(\fIchannel, input, inputLen, addAtEnd\fR)
 .sp
-size_t
+int
 \fBTcl_WriteObj\fR(\fIchannel, writeObjPtr\fR)
 .sp
-size_t
+int
 \fBTcl_WriteChars\fR(\fIchannel, charBuf, bytesToWrite\fR)
 .sp
-size_t
+int
 \fBTcl_Write\fR(\fIchannel, byteBuf, bytesToWrite\fR)
 .sp
-size_t
+int
 \fBTcl_ReadRaw\fR(\fIchannel, readBuf, bytesToRead\fR)
 .sp
-size_t
+int
 \fBTcl_WriteRaw\fR(\fIchannel, byteBuf, bytesToWrite\fR)
 .sp
 int
@@ -134,7 +134,7 @@ input of the invoking process; likewise for \fBTCL_STDOUT\fR and
 redirect stdio handles to override the stdio handles for which
 \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR and \fBTCL_STDERR\fR have been set.  If it
 is set, then such redirections cause an error.
-.AP void *handle in
+.AP ClientData handle in
 Operating system specific handle for I/O to a file. For Unix this is a
 file descriptor, for Windows it is a HANDLE.
 .AP int readOrWrite in
@@ -154,7 +154,7 @@ from a procedure such as \fBTcl_OpenFileChannel\fR.
 .AP Tcl_Obj *readObjPtr in/out
 A pointer to a Tcl value in which to store the characters read from the
 channel.
-.AP size_t charsToRead in
+.AP int charsToRead in
 The number of characters to read from the channel.  If the channel's encoding
 is \fBbinary\fR, this is equivalent to the number of bytes to read from the
 channel.
@@ -163,7 +163,7 @@ If non-zero, data read from the channel will be appended to the value.
 Otherwise, the data will replace the existing contents of the value.
 .AP char *readBuf out
 A buffer in which to store the bytes read from the channel.
-.AP size_t bytesToRead in
+.AP int bytesToRead in
 The number of bytes to read from the channel.  The buffer \fIreadBuf\fR must
 be large enough to hold this many bytes.
 .AP Tcl_Obj *lineObjPtr in/out
@@ -176,7 +176,7 @@ channel.  Must have been initialized by the caller.  The line read will be
 appended to any data already in the dynamic string.
 .AP "const char" *input in
 The input to add to a channel buffer.
-.AP size_t inputLen in
+.AP int inputLen in
 Length of the input
 .AP int addAtEnd in
 Flag indicating whether the input should be added to the end or
@@ -187,7 +187,7 @@ A pointer to a Tcl value whose contents will be output to the channel.
 A buffer containing the characters to output to the channel.
 .AP "const char" *byteBuf in
 A buffer containing the bytes to output to the channel.
-.AP size_t bytesToWrite in
+.AP int bytesToWrite in
 The number of bytes to consume from \fIcharBuf\fR or \fIbyteBuf\fR and
 output to the channel.
 .AP "long long" offset in
@@ -50,12 +50,12 @@ 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 void *sock in
+.AP ClientData sock in
 Platform-specific handle for client TCP socket.
 .AP Tcl_TcpAcceptProc *proc in
 Pointer to a procedure to invoke each time a new connection is
 accepted via the socket.
-.AP void *clientData in
+.AP ClientData clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .BE
 .SH DESCRIPTION
@@ -127,7 +127,7 @@ the channel. \fIProc\fR must match the following prototype:
 .PP
 .CS
 typedef void \fBTcl_TcpAcceptProc\fR(
-        void *\fIclientData\fR,
+        ClientData \fIclientData\fR,
        Tcl_Channel \fIchannel\fR,
        char *\fIhostName\fR,
        int \fIport\fR);
@@ -7,7 +7,7 @@
 .BS
 '\"  Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-Tcl_Panic, Tcl_SetPanicProc, Tcl_ConsolePanic \- 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
@@ -15,6 +15,9 @@ Tcl_Panic, Tcl_SetPanicProc, Tcl_ConsolePanic \- report fatal error and abort
 void
 \fBTcl_Panic\fR(\fIformat\fR, \fIarg\fR, \fIarg\fR, \fI...\fR)
 .sp
+void
+\fBTcl_PanicVA\fR(\fIformat\fR, \fIargList\fR)
+.sp
 const char *
 \fBTcl_SetPanicProc\fR(\fIpanicProc\fR)
 .sp
@@ -79,14 +82,15 @@ making calls into the Tcl library, or into other libraries that may
 call the Tcl library, since the original call to \fBTcl_Panic\fR
 indicates the Tcl library is not in a state of reliable operation.
 .PP
-The result of \fBTcl_SetPanicProc\fR is the full Tcl version with build
-information (e.g., \fB9.0.0+abcdef...abcdef.gcc-1002\fR).
+The result of \fBTcl_SetPanicProc\fR is the full Tcl version (e.g.,
+\fB8.7.0+abcdef...abcdef.gcc-1002.utf16\fR).
 .PP
 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.
+\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
@@ -94,6 +98,10 @@ by any extension or application that wishes to abort the process and
 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. 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
@@ -31,7 +31,7 @@ The array of arguments to be parsed.
 Pointer to a variable that will hold the array of unprocessed arguments.
 Should be NULL if no return of unprocessed arguments is required. If
 \fIobjcPtr\fR is updated to a non-zero value, the array returned through this
-must be deallocated using \fBTcl_Free\fR.
+must be deallocated using \fBckfree\fR.
 .BE
 .SH DESCRIPTION
 .PP
@@ -84,7 +84,7 @@ typedef struct {
    void *\fIsrcPtr\fR;
    void *\fIdstPtr\fR;
    const char *\fIhelpStr\fR;
-    void *\fIclientData\fR;
+    ClientData \fIclientData\fR;
 } \fBTcl_ArgvInfo\fR;
 .CE
 .PP
@@ -127,7 +127,7 @@ have the following signature:
 .PP
 .CS
 typedef int (\fBTcl_ArgvFuncProc\fR)(
-        void *\fIclientData\fR,
+        ClientData \fIclientData\fR,
        Tcl_Obj *\fIobjPtr\fR,
        void *\fIdstPtr\fR);
 .CE
@@ -149,7 +149,7 @@ function will have the following signature:
 .PP
 .CS
 typedef int (\fBTcl_ArgvGenFuncProc\fR)(
-        void *\fIclientData\fR,
+        ClientData \fIclientData\fR,
        Tcl_Interp *\fIinterp\fR,
        int \fIobjc\fR,
        Tcl_Obj *const *\fIobjv\fR,
@@ -8,7 +8,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_ParseCommand, Tcl_ParseExpr, Tcl_ParseBraces, Tcl_ParseQuotedString, Tcl_ParseVarName, Tcl_ParseVar, Tcl_FreeParse, Tcl_EvalTokensStandard \- parse Tcl scripts and expressions
+Tcl_ParseCommand, Tcl_ParseExpr, Tcl_ParseBraces, Tcl_ParseQuotedString, Tcl_ParseVarName, Tcl_ParseVar, Tcl_FreeParse, Tcl_EvalTokens, Tcl_EvalTokensStandard \- parse Tcl scripts and expressions
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -33,16 +33,20 @@ const char *
 .sp
 \fBTcl_FreeParse\fR(\fIusedParsePtr\fR)
 .sp
+Tcl_Obj *
+\fBTcl_EvalTokens\fR(\fIinterp, tokenPtr, numTokens\fR)
+.sp
 int
 \fBTcl_EvalTokensStandard\fR(\fIinterp, tokenPtr, numTokens\fR)
 .SH ARGUMENTS
 .AS Tcl_Interp *usedParsePtr out
 .AP Tcl_Interp *interp out
-For procedures other than \fBTcl_FreeParse\fR and
-\fBTcl_EvalTokensStandard\fR, used only for error reporting;
+For procedures other than \fBTcl_FreeParse\fR, \fBTcl_EvalTokens\fR
+and \fBTcl_EvalTokensStandard\fR, used only for error reporting;
 if NULL, then no error messages are left after errors.
-For \fBTcl_EvalTokensStandard\fR, determines the context for evaluating
-the script and also is used for error reporting; must not be NULL.
+For \fBTcl_EvalTokens\fR and \fBTcl_EvalTokensStandard\fR,
+determines the context for evaluating the
+script and also is used for error reporting; must not be NULL.
 .AP "const char" *start in
 Pointer to first character in string to parse.
 .AP int numBytes in
@@ -187,6 +191,17 @@ code with one of the values \fBTCL_OK\fR, \fBTCL_ERROR\fR,
 some other integer value originating in an extension.
 In addition, a result value or error message is left in \fIinterp\fR's
 result; it can be retrieved using \fBTcl_GetObjResult\fR.
+.SS "DEPRECATED FUNCTIONS"
+.PP
+\fBTcl_EvalTokens\fR differs from \fBTcl_EvalTokensStandard\fR only in
+the return convention used: it returns the result in a new Tcl_Obj.
+The reference count of the value returned as result has been
+incremented, so the caller must
+invoke \fBTcl_DecrRefCount\fR when it is finished with the value.
+If an error or other exception occurs while evaluating the tokens
+(such as a reference to a non-existent variable) then the return value
+is NULL and an error message is left in \fIinterp\fR's result. The use
+of \fBTcl_EvalTokens\fR is deprecated.
 .SH "TCL_PARSE STRUCTURE"
 .PP
 \fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR,
@@ -208,8 +223,8 @@ typedef struct Tcl_Parse {
 typedef struct Tcl_Token {
    int \fItype\fR;
    const char *\fIstart\fR;
-    size_t \fIsize\fR;
-    size_t \fInumComponents\fR;
+    int \fIsize\fR;
+    int \fInumComponents\fR;
 } \fBTcl_Token\fR;
 .CE
 .PP
@@ -449,5 +464,12 @@ There are additional fields in the Tcl_Parse structure after the
 \fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR,
 \fBTcl_ParseQuotedString\fR, and \fBTcl_ParseVarName\fR; they should not be
 referenced by code outside of these procedures.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+The result of \fBTcl_EvalTokens\fR is an unshared value with a reference count
+of 1; the caller of that function should call \fBTcl_DecrRefCount\fR on the
+result value to dispose of it. (The equivalent with
+\fBTcl_EvalTokenStandard\fR is just the interpreter result, which can be
+retrieved with \fBTcl_GetObjResult\fR.)
 .SH KEYWORDS
 backslash substitution, braces, command, expression, parse, token, variable substitution
@@ -21,7 +21,7 @@ Tcl_Preserve, Tcl_Release, Tcl_EventuallyFree \- avoid freeing storage while it
 \fBTcl_EventuallyFree\fR(\fIclientData, freeProc\fR)
 .SH ARGUMENTS
 .AS Tcl_FreeProc clientData
-.AP void *clientData in
+.AP ClientData clientData in
 Token describing structure to be freed or reallocated.  Usually a pointer
 to memory for structure.
 .AP Tcl_FreeProc *freeProc in
@@ -91,7 +91,7 @@ reasons, but the value is the same.
 .PP
 When the \fIclientData\fR argument to \fBTcl_EventuallyFree\fR
 refers to storage allocated and returned by a prior call to
-\fBTcl_Alloc\fR or another function of the Tcl library,
+\fBTcl_Alloc\fR, \fBckalloc\fR, or another function of the Tcl library,
 then the \fIfreeProc\fR argument should be given the special value of
 \fBTCL_DYNAMIC\fR.
 .PP
@@ -18,7 +18,10 @@ Tcl_PrintDouble \- Convert floating value to string
 .SH ARGUMENTS
 .AS Tcl_Interp *interp out
 .AP Tcl_Interp *interp in
-This argument is ignored.
+Before Tcl 8.0, the \fBtcl_precision\fR variable in this interpreter
+controlled the conversion.  As of Tcl 8.0, this argument is ignored and
+the conversion is controlled by the \fBtcl_precision\fR variable
+that is now shared by all interpreters.
 .AP double value in
 Floating-point value to be converted.
 .AP char *dst out
@@ -38,7 +41,9 @@ so that it does not look like an integer.  Where \fB%g\fR would
 generate an integer with no decimal point, \fBTcl_PrintDouble\fR adds
 .QW .0 .
 .PP
-The result will have the fewest digits needed to
+If the \fBtcl_precision\fR value is non-zero, the result will have
+precisely that many digits of significance.  If the value is zero
+(the default), the result will have the fewest digits needed to
 represent the number in such a way that \fBTcl_NewDoubleObj\fR
 will generate the same number when presented with the given string.
 IEEE semantics of rounding to even apply to the conversion.
@@ -31,7 +31,7 @@ the command at global level instead of the current stack level.
 .SH DESCRIPTION
 .PP
 \fBTcl_RecordAndEvalObj\fR is invoked to record a command as an event
-on the history list and then execute it using \fBTcl_EvalObjEx\fR.
+on the history list and then execute it using \fBTcl_EvalObjEx\fR
 It returns a completion code such as \fBTCL_OK\fR just like \fBTcl_EvalObjEx\fR,
 as well as a result value containing additional information
 (a result value or error message)
@@ -64,7 +64,7 @@ identifies the beginning of the larger string.
 If it is not the same as \fItext\fR, then no
 .QW \fB^\fR
 matches will be allowed.
-.AP size_t index in
+.AP int index in
 Specifies which range is desired:  0 means the range of the entire
 match, 1 or greater means the range that matched a parenthesized
 sub-expression.
@@ -80,14 +80,14 @@ OR-ed combination of the compilation flags \fBTCL_REG_ADVANCED\fR,
 \fBTCL_REG_QUOTE\fR, \fBTCL_REG_NOCASE\fR, \fBTCL_REG_NEWLINE\fR,
 \fBTCL_REG_NLSTOP\fR, \fBTCL_REG_NLANCH\fR, \fBTCL_REG_NOSUB\fR, and
 \fBTCL_REG_CANMATCH\fR. See below for more information.
-.AP size_t offset in
+.AP int offset in
 The character offset into the text where matching should begin.
 The value of the offset has no impact on \fB^\fR matches.  This
 behavior is controlled by \fIeflags\fR.
-.AP size_t nmatches in
+.AP int nmatches in
 The number of matching subexpressions that should be remembered for
 later use.  If this value is 0, then no subexpression match
-information will be computed.  If the value is TCL_INDEX_NONE, then
+information will be computed.  If the value is \-1, then
 all of the matching subexpressions will be remembered.  Any other
 value will be taken as the maximum number of subexpressions to
 remember.
@@ -337,9 +337,9 @@ defined as follows:
 .PP
 .CS
 typedef struct Tcl_RegExpInfo {
-    size_t \fInsubs\fR;
+    int \fInsubs\fR;
    Tcl_RegExpIndices *\fImatches\fR;
-    size_t \fIextendStart\fR;
+    long \fIextendStart\fR;
 } \fBTcl_RegExpInfo\fR;
 .CE
 .PP
@@ -355,8 +355,8 @@ follows:
 .PP
 .CS
 typedef struct Tcl_RegExpIndices {
-    size_t \fIstart\fR;
-    size_t \fIend\fR;
+    long \fIstart\fR;
+    long \fIend\fR;
 } \fBTcl_RegExpIndices\fR;
 .CE
 .PP
@@ -87,10 +87,14 @@ the value.
 Which functions of a channel driver are allowed to use which bypass function
 is listed below, as is which functions of the public channel API may leave a
 messages in the bypass areas.
+.IP \fBTcl_DriverCloseProc\fR
+May use \fBTcl_SetChannelErrorInterp\fR, and only this function.
 .IP \fBTcl_DriverInputProc\fR
 May use \fBTcl_SetChannelError\fR, and only this function.
 .IP \fBTcl_DriverOutputProc\fR
 May use \fBTcl_SetChannelError\fR, and only this function.
+.IP \fBTcl_DriverSeekProc\fR
+May use \fBTcl_SetChannelError\fR, and only this function.
 .IP \fBTcl_DriverWideSeekProc\fR
 May use \fBTcl_SetChannelError\fR, and only this function.
 .IP \fBTcl_DriverSetOptionProc\fR
@@ -29,7 +29,7 @@ New limit for nested calls to \fBTcl_Eval\fR for \fIinterp\fR.
 .PP
 At any given time Tcl enforces a limit on the number of recursive
 calls that may be active for \fBTcl_Eval\fR and related procedures
-such as \fBTcl_EvalEx\fR.
+such as \fBTcl_GlobalEval\fR.
 Any call to \fBTcl_Eval\fR that exceeds this depth is aborted with
 an error.
 By default the recursion limit is 1000.
@@ -9,7 +9,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult, Tcl_AppendResult, Tcl_AppendElement, Tcl_ResetResult, Tcl_TransferResult \- manipulate Tcl result
+Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult, Tcl_AppendResult, Tcl_AppendResultVA, Tcl_AppendElement, Tcl_ResetResult, Tcl_TransferResult, Tcl_FreeResult \- manipulate Tcl result
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -26,11 +26,15 @@ const char *
 .sp
 \fBTcl_AppendResult\fR(\fIinterp, result, result, ... , \fB(char *) NULL\fR)
 .sp
+\fBTcl_AppendResultVA\fR(\fIinterp, argList\fR)
+.sp
 \fBTcl_ResetResult\fR(\fIinterp\fR)
 .sp
 \fBTcl_TransferResult\fR(\fIsourceInterp, code, targetInterp\fR)
 .sp
 \fBTcl_AppendElement\fR(\fIinterp, element\fR)
+.sp
+\fBTcl_FreeResult\fR(\fIinterp\fR)
 .SH ARGUMENTS
 .AS Tcl_FreeProc sourceInterp out
 .AP Tcl_Interp *interp out
@@ -139,6 +143,11 @@ extensions.
 Any number of \fIresult\fR arguments may be passed in a single
 call; the last argument in the list must be a NULL pointer.
 .PP
+\fBTcl_AppendResultVA\fR is the same as \fBTcl_AppendResult\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
 \fBTcl_TransferResult\fR transfers interpreter state from \fIsourceInterp\fR
 to \fItargetInterp\fR. The two interpreters must have been created in the
 same thread.  If \fIsourceInterp\fR and \fItargetInterp\fR are the same,
@@ -175,6 +184,22 @@ single character
 or ends in the characters
 .QW " {" )
 then no space is added.
+.PP
+\fBTcl_FreeResult\fR performs part of the work
+of \fBTcl_ResetResult\fR.
+It frees up the memory associated with \fIinterp\fR's result.
+It also sets \fIinterp->freeProc\fR to zero, but does not
+change \fIinterp->result\fR or clear error state.
+\fBTcl_FreeResult\fR is most commonly used when a procedure
+is about to replace one result value with another.
+.SS "DIRECT ACCESS TO INTERP->RESULT"
+.PP
+It used to be legal for programs to
+directly read and write \fIinterp->result\fR
+to manipulate the interpreter result.  The Tcl headers no longer
+permit this access. C code still doing this must
+be updated to use supported routines \fBTcl_GetObjResult\fR,
+\fBTcl_GetStringResult\fR, \fBTcl_SetObjResult\fR, and \fBTcl_SetResult\fR.
 .SH "THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT"
 .PP
 \fBTcl_SetResult\fR's \fIfreeProc\fR argument specifies how
@@ -20,16 +20,16 @@ int
 char *
 \fBTcl_Merge\fR(\fIargc, argv\fR)
 .sp
-size_t
+int
 \fBTcl_ScanElement\fR(\fIsrc, flagsPtr\fR)
 .sp
-size_t
+int
 \fBTcl_ScanCountedElement\fR(\fIsrc, length, flagsPtr\fR)
 .sp
-size_t
+int
 \fBTcl_ConvertElement\fR(\fIsrc, dst, flags\fR)
 .sp
-size_t
+int
 \fBTcl_ConvertCountedElement\fR(\fIsrc, length, dst, flags\fR)
 .SH ARGUMENTS
 .AS "const char *const" ***argvPtr out
@@ -55,7 +55,7 @@ String that is to become an element of a list.
 .AP int *flagsPtr in
 Pointer to word to fill in with information about \fIsrc\fR.
 The value of *\fIflagsPtr\fR must be passed to \fBTcl_ConvertElement\fR.
-.AP size_t length in
+.AP int length in
 Number of bytes in string \fIsrc\fR.
 .AP char *dst in
 Place to copy converted list element.  Must contain enough characters
@@ -24,8 +24,8 @@ already been incorporated (i.e., the caller has already invoked the
 appropriate initialization procedure).  NULL means the library
 has not yet been incorporated into any interpreter.
 .AP "const char" *prefix in
-Prefix for library initialization function. Normally in titlecase (first
-letter upper-case, all others lower-case), but this is no longer required.
+Prefix for library initialization function;  should be properly
+capitalized (first letter upper-case, all others lower-case).
 .AP Tcl_LibraryInitProc *initProc in
 Procedure to invoke to incorporate this library into a trusted
 interpreter.
@@ -70,7 +70,8 @@ initialization procedure to be invoked.
 \fBTcl_StaticLibrary\fR was named \fBTcl_StaticPackage\fR in Tcl 8.6 and
 earlier, but the old name is deprecated now.
 .PP
-\fBTcl_StaticLibrary\fR can not be used in stub-enabled extensions.
+\fBTcl_StaticLibrary\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
 initialization procedure, package, static linking
 .SH "SEE ALSO"
@@ -8,7 +8,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_NewStringObj, Tcl_NewUnicodeObj, Tcl_SetStringObj, Tcl_SetUnicodeObj, Tcl_GetStringFromObj, Tcl_GetString, Tcl_GetUnicodeFromObj, Tcl_GetUnicode, Tcl_GetUniChar, Tcl_GetCharLength, Tcl_GetRange, Tcl_AppendToObj, Tcl_AppendUnicodeToObj, Tcl_AppendObjToObj, Tcl_AppendStringsToObj, Tcl_AppendLimitedToObj, Tcl_Format, Tcl_AppendFormatToObj, Tcl_ObjPrintf, Tcl_AppendPrintfToObj, Tcl_SetObjLength, Tcl_AttemptSetObjLength, Tcl_ConcatObj \- manipulate Tcl values as strings
+Tcl_NewStringObj, Tcl_NewUnicodeObj, Tcl_SetStringObj, Tcl_SetUnicodeObj, Tcl_GetStringFromObj, Tcl_GetString, Tcl_GetUnicodeFromObj, Tcl_GetUnicode, Tcl_GetUniChar, Tcl_GetCharLength, Tcl_GetRange, Tcl_AppendToObj, Tcl_AppendUnicodeToObj, Tcl_AppendObjToObj, Tcl_AppendStringsToObj, Tcl_AppendStringsToObjVA, Tcl_AppendLimitedToObj, Tcl_Format, Tcl_AppendFormatToObj, Tcl_ObjPrintf, Tcl_AppendPrintfToObj, Tcl_SetObjLength, Tcl_AttemptSetObjLength, Tcl_ConcatObj \- manipulate Tcl values as strings
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -59,6 +59,9 @@ void
 \fBTcl_AppendStringsToObj\fR(\fIobjPtr, string, string, ... \fB(char *) NULL\fR)
 .sp
 void
+\fBTcl_AppendStringsToObjVA\fR(\fIobjPtr, argList\fR)
+.sp
+void
 \fBTcl_AppendLimitedToObj\fR(\fIobjPtr, bytes, length, limit, ellipsis\fR)
 .sp
 Tcl_Obj *
@@ -87,38 +90,38 @@ Tcl_Obj *
 Points to the first byte of an array of UTF-8-encoded bytes
 used to set or append to a string value.
 This byte array may contain embedded null characters
-unless \fInumChars\fR is \fBTCL_INDEX_NONE\fR.  (Applications needing null bytes
+unless \fInumChars\fR is negative.  (Applications needing null bytes
 should represent them as the two-byte sequence \fI\e300\e200\fR, use
 \fBTcl_ExternalToUtf\fR to convert, or \fBTcl_NewByteArrayObj\fR if
 the string is a collection of uninterpreted bytes.)
-.AP size_t length in
+.AP int length in
 The number of bytes to copy from \fIbytes\fR when
 initializing, setting, or appending to a string value.
-If \fBTCL_INDEX_NONE\fR, all bytes up to the first null are used.
+If negative, all bytes up to the first null are used.
 .AP "const Tcl_UniChar" *unicode in
 Points to the first byte of an array of Unicode characters
 used to set or append to a string value.
 This byte array may contain embedded null characters
-unless \fInumChars\fR is \fBTCL_INDEX_NONE\fR.
-.AP size_t numChars in
+unless \fInumChars\fR is negative.
+.AP int numChars in
 The number of Unicode characters to copy from \fIunicode\fR when
 initializing, setting, or appending to a string value.
-If \fBTCL_INDEX_NONE\fR, all characters up to the first null character are used.
-.AP size_t index in
+If negative, all characters up to the first null character are used.
+.AP int index in
 The index of the Unicode character to return.
-.AP size_t first in
+.AP int first in
 The index of the first Unicode character in the Unicode range to be
-returned as a new value. If \fBTCL_INDEX_NONE\fR, behave the same as if the
+returned as a new value. If negative, behave the same as if the
 value was 0.
-.AP size_t last in
+.AP int last in
 The index of the last Unicode character in the Unicode range to be
-returned as a new value. If \fBTCL_INDEX_NONE\fR, take all characters up to
+returned as a new value. If negative, take all characters up to
 the last one available.
 .AP Tcl_Obj *objPtr in/out
 Points to a value to manipulate.
 .AP Tcl_Obj *appendObjPtr in
 The value to append to \fIobjPtr\fR in \fBTcl_AppendObjToObj\fR.
-.AP size_t | int *lengthPtr out
+.AP int *lengthPtr out
 The location where \fBTcl_GetStringFromObj\fR will store the length
 of a value's string representation. May be (int *)NULL when not used.
 .AP "const char" *string in
@@ -126,7 +129,7 @@ Null-terminated string value to append to \fIobjPtr\fR.
 .AP va_list argList in
 An argument list which must have been initialized using
 \fBva_start\fR, and cleared using \fBva_end\fR.
-.AP size_t limit in
+.AP int limit in
 Maximum number of bytes to be appended.
 .AP "const char" *ellipsis in
 Suffix to append when the limit leads to string truncation.
@@ -139,7 +142,7 @@ Format control string including % conversion specifiers.
 The number of elements to format or concatenate.
 .AP Tcl_Obj *objv[] in
 The array of values to format or concatenate.
-.AP size_t newLength in
+.AP int newLength in
 New length for the string value of \fIobjPtr\fR, not including the
 final null character.
 .BE
@@ -246,6 +249,12 @@ values may contain internal null characters).  Any number of
 \fIstring\fR arguments may be provided, but the last argument
 must be a NULL pointer to indicate the end of the list.
 .PP
+\fBTcl_AppendStringsToObjVA\fR is the same as \fBTcl_AppendStringsToObj\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
 \fBTcl_AppendLimitedToObj\fR is similar to \fBTcl_AppendToObj\fR
 except that it imposes a limit on how many bytes are appended.
 This can be handy when the string to be appended might be
@@ -258,7 +267,7 @@ all \fIlength\fR bytes that are available from being appended, then the
 appending is done so that the last bytes appended are from the
 string \fIellipsis\fR. This allows for an indication of the truncation
 to be left in the string.
-When \fIlength\fR is \fBTCL_INDEX_NONE\fR, all bytes up to the first zero byte are appended,
+When \fIlength\fR is \fB-1\fR, all bytes up to the first zero byte are appended,
 subject to the limit. When \fIellipsis\fR is NULL, the default
 string \fB...\fR is used. When \fIellipsis\fR is non-NULL, it must point
 to a zero-byte-terminated string in Tcl's internal UTF encoding.
@@ -301,7 +310,7 @@ functionality is needed.
 .CS
 char buf[SOME_SUITABLE_LENGTH];
 sprintf(buf, format, ...);
-\fBTcl_NewStringObj\fR(buf, \fBTCL_INDEX_NONE\fR);
+\fBTcl_NewStringObj\fR(buf, -1);
 .CE
 .PP
 but with greater convenience and no need to
@@ -34,7 +34,7 @@ and the Tcl \fBmemory\fR command can be used to validate and examine
 memory usage.
 .SH "GUARD ZONES"
 .PP
-When memory debugging is enabled, whenever a call to \fBTcl_Alloc\fR is
+When memory debugging is enabled, whenever a call to \fBckalloc\fR is
 made, slightly more memory than requested is allocated so the memory
 debugging code can keep track of the allocated memory, and eight-byte
 .QW "guard zones"
@@ -44,7 +44,7 @@ C #define \fBLOW_GUARD_SIZE\fR and #define \fBHIGH_GUARD_SIZE\fR
 in the file \fIgeneric/tclCkalloc.c\fR \(em it can
 be extended if you suspect large overwrite problems, at some cost in
 performance.)  A known pattern is written into the guard zones and, on
-a call to \fBTcl_Free\fR, the guard zones of the space being freed are
+a call to \fBckfree\fR, the guard zones of the space being freed are
 checked to see if either zone has been modified in any way.  If one
 has been, the guard bytes and their new contents are identified, and a
 .QW "low guard failed"
@@ -53,7 +53,7 @@ or
 message is issued.  The
 .QW "guard failed"
 message includes the address of the memory packet and
-the file name and line number of the code that called \fBTcl_Free\fR.
+the file name and line number of the code that called \fBckfree\fR.
 This allows you to detect the common sorts of one-off problems, where
 not enough space was allocated to contain the data written, for
 example.
@@ -66,15 +66,15 @@ suspect (or know) that corruption is occurring before the Tcl
 interpreter comes up far enough for you to issue commands, you can set
 \fBMEM_VALIDATE\fR define, recompile tclCkalloc.c and rebuild Tcl.
 This will enable memory validation from the first call to
-\fBTcl_Alloc\fR, again, at a large performance impact.
+\fBckalloc\fR, again, at a large performance impact.
 .PP
 If you are desperate and validating memory on every call to
-\fBTcl_Alloc\fR and \fBTcl_Free\fR is not enough, you can explicitly call
+\fBckalloc\fR and \fBckfree\fR is not enough, you can explicitly call
 \fBTcl_ValidateAllMemory\fR directly at any point.  It takes a \fIchar
 *\fR and an \fIint\fR which are normally the filename and line number
 of the caller, but they can actually be anything you want.  Remember
 to remove the calls after you find the problem.
 .SH "SEE ALSO"
-Tcl_Alloc, memory, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory
+ckalloc, memory, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory
 .SH KEYWORDS
 memory, debug
@@ -88,7 +88,7 @@ The initial value for the checksum algorithm.
 .AP "unsigned char" *bytes in
 An array of bytes to run the checksum algorithm over, or NULL to get the
 recommended initial value for the checksum algorithm.
-.AP size_t length in
+.AP int length in
 The number of bytes in the array.
 .AP int mode in
 What mode to operate the stream in. Should be either
@@ -107,9 +107,9 @@ if the currently compressed data must be made available for access using
 into a state where the decompressor can recover from on corruption, or
 \fBTCL_ZLIB_FINALIZE\fR to ensure that the stream is finished and that any
 trailer demanded by the format is written.
-.AP size_t count in
-The maximum number of bytes to get from the stream, or TCL_INDEX_NONE to get
-all remaining bytes from the stream's buffers.
+.AP int count in
+The maximum number of bytes to get from the stream, or -1 to get all remaining
+bytes from the stream's buffers.
 .AP Tcl_Obj *compDict in
 A byte array value that is the compression dictionary to use with the stream.
 Note that this is \fInot a Tcl dictionary\fR, and it is recommended that this
@@ -6,7 +6,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-.TH Tcl_Main 3 9.0 Tcl "Tcl Library Procedures"
+.TH Tcl_Main 3 8.4 Tcl "Tcl Library Procedures"
 .so man.macros
 .BS
 .SH NAME
@@ -85,8 +85,10 @@ that does nothing but invoke \fBTcl_Main\fR.
 .PP
 \fBTcl_Main\fR is not provided by the public interface of Tcl's
 stub library.  Programs that call \fBTcl_Main\fR must be linked
-against the standard Tcl library.  Extensions (stub-enabled or
-not) are not intended to call \fBTcl_Main\fR.
+against the standard Tcl library.  If the standard Tcl library is
+a dll (so, not a static .lib/.a) , then the program must be linked
+against the stub library as well. Extensions
+(stub-enabled or not) are not intended to call \fBTcl_Main\fR.
 .PP
 \fBTcl_Main\fR is not thread-safe.  It should only be called by
 a single main thread of a multi-threaded application.  This
@@ -201,11 +203,6 @@ procedure (if any) returns, \fBTcl_Main\fR will also evaluate
 the \fBexit\fR command.
 .PP
 \fBTcl_Main\fR can not be used in stub-enabled extensions.
-.PP
-The difference between Tcl_MainEx and Tcl_MainExW is that the arguments
-are passed as characters or wide characters. When used in stub-enabled
-embedders, the stubs table must be first initialized using one of
-\fBTcl_InitSubsystems\fR, \fBTcl_SetPanicProc\fR, \fBTcl_FindExecutable\fR or \fBTclZipfs_AppHook\fR.
 .SH "REFERENCE COUNT MANAGEMENT"
 .PP
 \fBTcl_SetStartupScript\fR takes a value (or NULL) for its \fIpath\fR
@@ -67,7 +67,7 @@ Id of the thread waited upon.
 .AP Tcl_ThreadCreateProc *proc in
 This procedure will act as the \fBmain()\fR of the newly created
 thread. The specified \fIclientData\fR will be its sole argument.
-.AP void *clientData in
+.AP ClientData clientData in
 Arbitrary information. Passed as sole argument to the \fIproc\fR.
 .AP int stackSize in
 The size of the stack given to the new thread.
@@ -208,7 +208,7 @@ value and then finishes.
 .CS
 static \fBTcl_ThreadCreateType\fR
 MyThreadImplFunc(
-    void *clientData)
+    ClientData clientData)
 {
    int i, limit = (int) clientData;
    for (i=0 ; i<limit ; i++) {
@@ -223,7 +223,7 @@ would do this:
 .PP
 .CS
 int limit = 1000000000;
-void *limitData = (void*)((intptr_t) limit);
+ClientData limitData = (void*)((intptr_t) limit);
 Tcl_ThreadId id;    \fI/* holds identity of thread created */\fR
 int result;

@@ -13,7 +13,7 @@ Tcl_CommandTraceInfo, Tcl_TraceCommand, Tcl_UntraceCommand \- monitor renames an
 .nf
 \fB#include <tcl.h>\fR
 .sp
-void *
+ClientData
 \fBTcl_CommandTraceInfo(\fIinterp, cmdName, flags, proc, prevClientData\fB)\fR
 .sp
 int
@@ -32,9 +32,9 @@ OR'ed collection of the values \fBTCL_TRACE_RENAME\fR and
 \fBTCL_TRACE_DELETE\fR.
 .AP Tcl_CommandTraceProc *proc in
 Procedure to call when specified operations occur to \fIcmdName\fR.
-.AP void *clientData in
+.AP ClientData clientData in
 Arbitrary argument to pass to \fIproc\fR.
-.AP void *prevClientData in
+.AP ClientData prevClientData in
 If non-NULL, gives last value returned by \fBTcl_CommandTraceInfo\fR,
 so this call will return information about next trace.  If NULL, this
 call will return information about first trace.
@@ -65,7 +65,7 @@ match the type \fBTcl_CommandTraceProc\fR:
 .PP
 .CS
 typedef void \fBTcl_CommandTraceProc\fR(
-        void *\fIclientData\fR,
+        ClientData \fIclientData\fR,
        Tcl_Interp *\fIinterp\fR,
        const char *\fIoldName\fR,
        const char *\fInewName\fR,
@@ -74,7 +74,7 @@ typedef void \fBTcl_CommandTraceProc\fR(
 .PP
 The \fIclientData\fR and \fIinterp\fR parameters will have the same
 values as those passed to \fBTcl_TraceCommand\fR when the trace was
-created.  \fIclientData\fR typically points to an application-specific
+created.  \fIClientData\fR typically points to an application-specific
 data structure that describes what to do when \fIproc\fR is invoked.
 \fIOldName\fR gives the name of the command being renamed, and
 \fInewName\fR gives the name that the command is being renamed to (or
@@ -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_TraceVar 3 9.0 Tcl "Tcl Library Procedures"
+.TH Tcl_TraceVar 3 8.7 Tcl "Tcl Library Procedures"
 .so man.macros
 .BS
 .SH NAME
@@ -24,13 +24,13 @@ int
 .sp
 \fBTcl_UntraceVar2(\fIinterp, name1, name2, flags, proc, clientData\fB)\fR
 .sp
-void *
+ClientData
 \fBTcl_VarTraceInfo(\fIinterp, varName, flags, proc, prevClientData\fB)\fR
 .sp
-void *
+ClientData
 \fBTcl_VarTraceInfo2(\fIinterp, name1, name2, flags, proc, prevClientData\fB)\fR
 .SH ARGUMENTS
-.AS void *prevClientData
+.AS Tcl_VarTraceProc prevClientData
 .AP Tcl_Interp *interp in
 Interpreter containing variable.
 .AP "const char" *varName in
@@ -46,7 +46,7 @@ Not all flags are used by all
 procedures.  See below for more information.
 .AP Tcl_VarTraceProc *proc in
 Procedure to invoke whenever one of the traced operations occurs.
-.AP void *clientData in
+.AP ClientData clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .AP "const char" *name1 in
 Name of scalar or array variable (without array index).
@@ -54,7 +54,7 @@ Name of scalar or array variable (without array index).
 For a trace on an element of an array, gives the index of the
 element.  For traces on scalar variables or on whole arrays,
 is NULL.
-.AP void *prevClientData in
+.AP ClientData prevClientData in
 If non-NULL, gives last value returned by \fBTcl_VarTraceInfo\fR or
 \fBTcl_VarTraceInfo2\fR, so this call will return information about
 next trace.  If NULL, this call will return information about first
@@ -107,7 +107,7 @@ before an array set, but that will trigger write traces.
 \fBTCL_TRACE_RESULT_DYNAMIC\fR
 The result of invoking the \fIproc\fR is a dynamically allocated
 string that will be released by the Tcl library via a call to
-\fBTcl_Free\fR.  Must not be specified at the same time as
+\fBckfree\fR.  Must not be specified at the same time as
 \fBTCL_TRACE_RESULT_OBJECT\fR.
 .TP
 \fBTCL_TRACE_RESULT_OBJECT\fR
@@ -124,7 +124,7 @@ It should have arguments and result that match the type
 .PP
 .CS
 typedef char *\fBTcl_VarTraceProc\fR(
-        void *\fIclientData\fR,
+        ClientData \fIclientData\fR,
        Tcl_Interp *\fIinterp\fR,
        char *\fIname1\fR,
        char *\fIname2\fR,
@@ -134,7 +134,7 @@ typedef char *\fBTcl_VarTraceProc\fR(
 The \fIclientData\fR and \fIinterp\fR parameters will
 have the same values as those passed to \fBTcl_TraceVar\fR when the
 trace was created.
-\fIclientData\fR typically points to an application-specific
+\fIClientData\fR typically points to an application-specific
 data structure that describes what to do when \fIproc\fR
 is invoked.
 \fIName1\fR and \fIname2\fR give the name of the traced variable
@@ -308,7 +308,7 @@ The return value must be a pointer to a static character string
 containing an error message,
 unless (\fIexactly\fR one of) the \fBTCL_TRACE_RESULT_DYNAMIC\fR and
 \fBTCL_TRACE_RESULT_OBJECT\fR flags is set, which specify that the result is
-either a dynamic string (to be released with \fBTcl_Free\fR) or a
+either a dynamic string (to be released with \fBckfree\fR) or a
 Tcl_Obj* (cast to char* and to be released with
 \fBTcl_DecrRefCount\fR) containing the error message.
 If a trace procedure returns an error, no further traces are
@@ -333,8 +333,7 @@ The routine \fBTcl_InterpDeleted\fR is an important tool for this.
 When \fBTcl_InterpDeleted\fR returns 1, \fIproc\fR will not be able
 to invoke any scripts in \fIinterp\fR. You may encounter old code using
 a deprecated flag value \fBTCL_INTERP_DESTROYED\fR to signal this
-condition, but Tcl 9 no longer supports this. Any supported code
-must be converted to stop using it.
+condition, but any supported code should be converted to stop using it.
 .PP
 A trace procedure can be called at any time, even when there
 are partially formed results stored in the interpreter.  If
@@ -55,19 +55,19 @@ int
 \fBTcl_UniCharLen\fR(\fIuniStr\fR)
 .sp
 int
-\fBTcl_UniCharNcmp\fR(\fIucs, uct, uniLength\fR)
+\fBTcl_UniCharNcmp\fR(\fIucs, uct, numChars\fR)
 .sp
 int
-\fBTcl_UniCharNcasecmp\fR(\fIucs, uct, uniLength\fR)
+\fBTcl_UniCharNcasecmp\fR(\fIucs, uct, numChars\fR)
 .sp
 int
 \fBTcl_UniCharCaseMatch\fR(\fIuniStr, uniPattern, nocase\fR)
 .sp
 int
-\fBTcl_UtfNcmp\fR(\fIcs, ct, length\fR)
+\fBTcl_UtfNcmp\fR(\fIcs, ct, numChars\fR)
 .sp
 int
-\fBTcl_UtfNcasecmp\fR(\fIcs, ct, length\fR)
+\fBTcl_UtfNcasecmp\fR(\fIcs, ct, numChars\fR)
 .sp
 int
 \fBTcl_UtfCharComplete\fR(\fIsrc, length\fR)
@@ -93,7 +93,7 @@ int
 const char *
 \fBTcl_UtfAtIndex\fR(\fIsrc, index\fR)
 .sp
-size_t
+int
 \fBTcl_UtfBackslash\fR(\fIsrc, readPtr, dst\fR)
 .SH ARGUMENTS
 .AS "const Tcl_UniChar" *uniPattern in/out
@@ -132,16 +132,18 @@ A null-terminated utf-16 string.
 A null-terminated utf-16 string.
 .AP "const unsigned short" *utf16Pattern in
 A null-terminated utf-16 string.
-.AP size_t length in
+.AP int length in
 The length of the UTF-8 string in bytes (not UTF-8 characters).  If
 negative, all bytes up to the first null byte are used.
-.AP size_t uniLength in
+.AP int uniLength in
 The length of the Unicode string in characters.
 .AP "Tcl_DString" *dsPtr in/out
 A pointer to a previously initialized \fBTcl_DString\fR.
+.AP "unsigned long" numChars in
+The number of characters to compare.
 .AP "const char" *start in
 Pointer to the beginning of a UTF-8 string.
-.AP size_t index in
+.AP int index in
 The index of a character (not byte) in the UTF-8 string.
 .AP int *readPtr out
 If non-NULL, filled with the number of bytes in the backslash sequence,
@@ -217,7 +219,7 @@ the number of Unicode characters (not bytes) in that string.
 \fBTcl_UniCharNcmp\fR and \fBTcl_UniCharNcasecmp\fR correspond to
 \fBstrncmp\fR and \fBstrncasecmp\fR, respectively, for Unicode characters.
 They accept two null-terminated Unicode strings and the number of characters
-to compare.  Both strings are assumed to be at least \fIuniLength\fR characters
+to compare.  Both strings are assumed to be at least \fInumChars\fR characters
 long. \fBTcl_UniCharNcmp\fR  compares the two strings character-by-character
 according to the Unicode character ordering.  It returns an integer greater
 than, equal to, or less than 0 if the first string is greater than, equal
@@ -231,7 +233,7 @@ be case sensitive and returns whether the string matches the pattern.
 .PP
 \fBTcl_UtfNcmp\fR corresponds to \fBstrncmp\fR for UTF-8 strings. It
 accepts two null-terminated UTF-8 strings and the number of characters
-to compare.  (Both strings are assumed to be at least \fIlength\fR
+to compare.  (Both strings are assumed to be at least \fInumChars\fR
 characters long.)  \fBTcl_UtfNcmp\fR compares the two strings
 character-by-character according to the Unicode character ordering.
 It returns an integer greater than, equal to, or less than 0 if the
@@ -298,14 +300,17 @@ byte \fIsrc[0]\fR nor the byte \fIstart[-1]\fR nor the byte
 Pascal Ord() function.  It returns the Unicode character represented at the
 specified character (not byte) \fIindex\fR in the UTF-8 string
 \fIsrc\fR.  The source string must contain at least \fIindex\fR
-characters.  If \fIindex\fR is TCL_INDEX_NONE or \fIindex\fR points
+characters.  If a negative \fIindex\fR is given or \fIindex\fR points
 to the second half of a surrogate pair, it returns -1.
 .PP
 \fBTcl_UtfAtIndex\fR returns a pointer to the specified character (not
 byte) \fIindex\fR in the UTF-8 string \fIsrc\fR.  The source string must
 contain at least \fIindex\fR characters.  This is equivalent to calling
-\fBTcl_UtfToUniChar\fR \fIindex\fR times.  If \fIindex\fR is TCL_INDEX_NONE,
-the return pointer points to the first character in the source string.
+\fBTcl_UtfToUniChar\fR \fIindex\fR times, except if that would return
+a pointer to the second byte of a valid 4-byte UTF-8 sequence, in which
+case, \fBTcl_UtfToUniChar\fR will be called once more to find the end
+of the sequence. If a negative \fIindex\fR is given, the returned pointer
+points to the first character in the source string.
 .PP
 \fBTcl_UtfBackslash\fR is a utility procedure used by several of the Tcl
 commands.  It parses a backslash sequence and stores the properly formed
@@ -44,9 +44,8 @@ the range \eu0000\-\eu00FF.
 When encoding binary data as a readable string, the starting binary data is
 passed to the \fBbinary encode\fR command, together with the name of the
 encoding to use and any encoding-specific options desired. Data which has been
-encoded can be converted back to binary form using \fBbinary decode\fR.
-The \fBbinary encode\fR command raises an error if the \fIdata\fR argument
-is not binary data. The following formats and options are supported.
+encoded can be converted back to binary form using \fBbinary decode\fR. The
+following formats and options are supported.
 .TP
 \fBbase64\fR
 .
@@ -610,9 +609,9 @@ will return
 .PP
 The \fBbinary scan\fR command parses fields from a binary string,
 returning the number of conversions performed.  \fIString\fR gives the
-input bytes to be parsed and \fIformatString\fR indicates how to parse it.
-An error is raised if \fIstring\fR is anything other than a valid binary
-data value.
+input bytes to be parsed (one byte per character, and characters not
+representable as a byte have their high bits chopped)
+and \fIformatString\fR indicates how to parse it.
 Each \fIvarName\fR gives the name of a variable; when a field is
 scanned from \fIstring\fR the result is assigned to the corresponding
 variable.
@@ -0,0 +1,60 @@
+'\"
+'\" Copyright (c) 1993 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH case n 7.0 Tcl "Tcl Built-In Commands"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+case \- Evaluate one of several scripts, depending on a given value
+.SH SYNOPSIS
+\fBcase\fI string \fR?\fBin\fR? \fIpatList body \fR?\fIpatList body \fR...?
+.sp
+\fBcase\fI string \fR?\fBin\fR? {\fIpatList body \fR?\fIpatList body \fR...?}
+.BE
+
+.SH DESCRIPTION
+.PP
+\fINote: the \fBcase\fI command is obsolete and is supported only
+for backward compatibility.  At some point in the future it may be
+removed entirely.  You should use the \fBswitch\fI command instead.\fR
+.PP
+The \fBcase\fR command matches \fIstring\fR against each of
+the \fIpatList\fR arguments in order.
+Each \fIpatList\fR argument is a list of one or
+more patterns.  If any of these patterns matches \fIstring\fR then
+\fBcase\fR evaluates the following \fIbody\fR argument
+by passing it recursively to the Tcl interpreter and returns the result
+of that evaluation.
+Each \fIpatList\fR argument consists of a single
+pattern or list of patterns.  Each pattern may contain any of the wild-cards
+described under \fBstring match\fR.  If a \fIpatList\fR
+argument is \fBdefault\fR, the corresponding body will be evaluated
+if no \fIpatList\fR matches \fIstring\fR.  If no \fIpatList\fR argument
+matches \fIstring\fR and no default is given, then the \fBcase\fR
+command returns an empty string.
+.PP
+Two syntaxes are provided for the \fIpatList\fR and \fIbody\fR arguments.
+The first uses a separate argument for each of the patterns and commands;
+this form is convenient if substitutions are desired on some of the
+patterns or commands.
+The second form places all of the patterns and commands together into
+a single argument; the argument must have proper list structure, with
+the elements of the list being the patterns and commands.
+The second form makes it easy to construct multi-line case commands,
+since the braces around the whole list make it unnecessary to include a
+backslash at the end of each line.
+Since the \fIpatList\fR arguments are in braces in the second form,
+no command or variable substitutions are performed on them;  this makes
+the behavior of the second form different than the first form in some
+cases.
+
+.SH "SEE ALSO"
+switch(n)
+
+.SH KEYWORDS
+case, match, regular expression
@@ -588,7 +588,7 @@ for reading from slots is via \fBinfo class\fR and \fBinfo object\fR).
 .SH EXAMPLES
 This example demonstrates how to use both forms of the \fBoo::define\fR and
 \fBoo::objdefine\fR commands (they work in the same way), as well as
-illustrating four of their subcommands.
+illustrating four of the subcommands of them.
 .PP
 .CS
 oo::class create c
@@ -14,16 +14,10 @@ encoding \- Manipulate encodings
 .BE
 .SH INTRODUCTION
 .PP
-Strings in Tcl are logically a sequence of 16-bit Unicode characters.
+Strings in Tcl are logically a sequence of Unicode characters.
 These strings are represented in memory as a sequence of bytes that
-may be in one of several encodings: modified UTF\-8 (which uses 1 to 3
-bytes per character), 16-bit
-.QW Unicode
-(which uses 2 bytes per character, with an endianness that is
-dependent on the host architecture), and binary (which uses a single
-byte per character but only handles a restricted range of characters).
-Tcl does not guarantee to always use the same encoding for the same
-string.
+may be in one of several encodings: modified UTF\-8 (which uses 1 to 4
+bytes per character), or a custom encoding start as 8 bit binary data.
 .PP
 Different operating system interfaces or applications may generate
 strings in other encodings such as Shift\-JIS.  The \fBencoding\fR
@@ -34,16 +28,30 @@ formats.
 Performs one of several encoding related operations, depending on
 \fIoption\fR.  The legal \fIoption\fRs are:
 .TP
-\fBencoding convertfrom\fR ?\fIencoding\fR? \fIdata\fR
+\fBencoding convertfrom\fR ?\fB-nocomplain\fR? ?\fB-failindex var\fR?
+?\fIencoding\fR? \fIdata\fR
 .
-Convert \fIdata\fR to Unicode from the specified \fIencoding\fR.  The
-characters in \fIdata\fR are treated as binary data where the lower
-8-bits of each character is taken as a single byte.  The resulting
-sequence of bytes is treated as a string in the specified
-\fIencoding\fR.  If \fIencoding\fR is not specified, the current
+Convert \fIdata\fR to a Unicode string from the specified \fIencoding\fR.  The
+characters in \fIdata\fR are 8 bit binary data.  The resulting
+sequence of bytes is a string created by applying the given \fIencoding\fR
+to the data. If \fIencoding\fR is not specified, the current
 system encoding is used.
+.
+The call fails on convertion errors, like an incomplete utf-8 sequence.
+The option \fB-failindex\fR is followed by a variable name. The variable
+is set to \fI-1\fR if no conversion error occured. It is set to the
+first error location in \fIdata\fR in case of a conversion error. All data
+until this error location is transformed and retured. This option may not
+be used together with \fB-nocomplain\fR.
+.
+The call does not fail on conversion errors, if the option
+\fB-nocomplain\fR is given. In this case, any error locations are replaced
+by \fB?\fR. Incomplete sequences are written verbatim to the output string.
+The purpose of this switch is to gain compatibility to prior versions of TCL.
+It is not recommended for any other usage.
 .TP
-\fBencoding convertto\fR ?\fIencoding\fR? \fIstring\fR
+\fBencoding convertto\fR ?\fB-nocomplain\fR? ?\fB-failindex var\fR?
+?\fIencoding\fR? \fIstring\fR
 .
 Convert \fIstring\fR from Unicode to the specified \fIencoding\fR.
 The result is a sequence of bytes that represents the converted
@@ -51,6 +59,21 @@ string.  Each byte is stored in the lower 8-bits of a Unicode
 character (indeed, the resulting string is a binary string as far as
 Tcl is concerned, at least initially).  If \fIencoding\fR is not
 specified, the current system encoding is used.
+.
+The call fails on convertion errors, like a Unicode character not representable
+in the given \fIencoding\fR.
+.
+The option \fB-failindex\fR is followed by a variable name. The variable
+is set to \fI-1\fR if no conversion error occured. It is set to the
+first error location in \fIdata\fR in case of a conversion error. All data
+until this error location is transformed and retured. This option may not
+be used together with \fB-nocomplain\fR.
+.
+The call does not fail on conversion errors, if the option
+\fB-nocomplain\fR is given. In this case, any error locations are replaced
+by \fB?\fR. Incomplete sequences are written verbatim to the output string.
+The purpose of this switch is to gain compatibility to prior versions of TCL.
+It is not recommended for any other usage.
 .TP
 \fBencoding dirs\fR ?\fIdirectoryList\fR?
 .
@@ -90,6 +113,26 @@ set s [\fBencoding convertfrom\fR euc-jp "\exA4\exCF"]
 The result is the unicode codepoint:
 .QW "\eu306F" ,
 which is the Hiragana letter HA.
+.PP
+The following example detects the error location in an incomplete UTF-8 sequence:
+.PP
+.CS
+% set s [\fBencoding convertfrom\fR -failindex i utf-8 "A\xc3"]
+A
+% set i
+1
+.CE
+.PP
+The following example detects the error location while transforming to ISO8859-1
+(ISO-Latin 1):
+.PP
+.CS
+% set s [\fBencoding convertto\fR -failindex i utf-8 "A\u0141"]
+A
+% set i
+1
+.CE
+.PP
 .SH "SEE ALSO"
 Tcl_GetEncoding(3)
 .SH KEYWORDS
@@ -62,7 +62,9 @@ A \fBnumeric value\fR
 .
 Either integer or floating-point.  The first two characters of an integer may
 also be \fB0d\fR for decimal, \fB0b\fR for binary, \fB0o\fR for octal or
-\fB0x\fR for hexadicimal.
+\fB0x\fR for hexadicimal.  For compatibility with older Tcl releases, an
+operand that begins with \fB0\fR is interpreted as an octal integer even if the
+second character is not \fBo\fR.
 .PP
 A floating-point number may be take any of several
 common decimal formats, and may use the decimal point \fB.\fR,
@@ -76,7 +76,7 @@ This command depends on the \fBfpclassify\fR() C macro conforming to
 (i.e., to ISO/IEC 9899:1999).
 .SH COPYRIGHT
 .nf
-Copyright \(co 2018 Kevin B. Kenny <kennykb@acm.org>. All rights reserved
+Copyright \(co 2018 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved
 .fi
 '\" Local Variables:
 '\" mode: nroff
@@ -49,6 +49,14 @@ http \- Client-side implementation of the HTTP/1.1 protocol
 \fB::http::registerError \fIport\fR ?\fImessage\fR?
 .sp
 \fB::http::unregister \fIproto\fR
+.SH "EXPORTED COMMANDS"
+.PP
+Namespace \fBhttp\fR exports the commands \fBconfig\fR, \fBformatQuery\fR,
+\fBgeturl\fR, \fBquoteString\fR, \fBregister\fR, \fBregisterError\fR,
+\fBreset\fR, \fBunregister\fR, and \fBwait\fR.
+.PP
+It does not export the commands \fBcleanup\fR, \fBcode\fR, \fBdata\fR,
+\fBerror\fR, \fBmeta\fR, \fBncode\fR, \fBsize\fR, or \fBstatus\fR.
 .BE
 .SH DESCRIPTION
 .PP
@@ -79,8 +87,9 @@ must be active.  In Tk applications this is always true.  For pure-Tcl
 applications, the caller can use \fB::http::wait\fR after calling
 \fB::http::geturl\fR to start the event loop.
 .PP
-\fBNote:\fR The event queue is even used without the \fB-command\fR option.
-As a side effect, arbitrary commands may be processed while \fBhttp::geturl\fR is running.
+\fBNote:\fR The event queue is even used without the \fB\-command\fR option.
+As a side effect, arbitrary commands may be processed while \fBhttp::geturl\fR
+is running.
 .SH COMMANDS
 .TP
 \fB::http::config\fR ?\fIoptions\fR?
@@ -120,9 +129,9 @@ is 1.
 \fB\-postfresh\fR \fIboolean\fR
 .
 Specifies whether requests that use the \fBPOST\fR method will always use a
-fresh socket, overriding the \fB-keepalive\fR option of
-command \fBhttp::geturl\fR.  See the \fBPERSISTENT SOCKETS\fR section for details.
-The default is 0.
+fresh socket, overriding the \fB\-keepalive\fR option of
+command \fBhttp::geturl\fR.  See the \fBPERSISTENT SOCKETS\fR section for
+details. The default is 0.
 .TP
 \fB\-proxyhost\fR \fIhostname\fR
 .
@@ -144,6 +153,13 @@ the proxy server and proxy port.  Otherwise the filter should return
 an empty list.  The default filter returns the values of the
 \fB\-proxyhost\fR and \fB\-proxyport\fR settings if they are
 non-empty.
+.RS
+.PP
+The \fB::http::geturl\fR command runs the \fB\-proxyfilter\fR callback inside
+a \fBcatch\fR command.  Therefore an error in the callback command does
+not call the \fBbgerror\fR handler.  See the \fBERRORS\fR section for
+details.
+.RE
 .TP
 \fB\-repost\fR \fIboolean\fR
 .
@@ -161,12 +177,7 @@ default is 0.
 .
 The \fIencoding\fR used for creating the x-url-encoded URLs with
 \fB::http::formatQuery\fR and \fB::http::quoteString\fR.
-The default is \fButf-8\fR, as specified by RFC
-2718.  Prior to http 2.5 this was unspecified, and that behavior can be
-returned by specifying the empty string (\fB{}\fR), although
-\fIiso8859-1\fR is recommended to restore similar behavior but without the
-\fB::http::formatQuery\fR or \fB::http::quoteString\fR
-throwing an error processing non-latin-1 characters.
+The default is \fButf-8\fR, as specified by RFC 2718.
 .TP
 \fB\-useragent\fR \fIstring\fR
 .
@@ -182,9 +193,9 @@ numbers of \fBhttp\fR and \fBTcl\fR.
 .
 If the value is boolean \fBtrue\fR, then by default requests will send a header
 .QW "\fBAccept-Encoding: gzip,deflate,compress\fR" .
-If the value is boolean \fBfalse\fR, then by default this header will not be sent.
-In either case the default can be overridden for an individual request by
-supplying a custom \fBAccept-Encoding\fR header in the \fB-headers\fR option
+If the value is boolean \fBfalse\fR, then by default this header will not be
+sent.  In either case the default can be overridden for an individual request by
+supplying a custom \fBAccept-Encoding\fR header in the \fB\-headers\fR option
 of \fBhttp::geturl\fR. The default is 1.
 .RE
 .TP
@@ -237,6 +248,11 @@ proc httpCallback {token} {
    # Access state as a Tcl array
 }
 .CE
+.PP
+The \fB::http::geturl\fR command runs the \fB\-command\fR callback inside
+a \fBcatch\fR command.  Therefore an error in the callback command does
+not call the \fBbgerror\fR handler.  See the \fBERRORS\fR section for
+details.
 .RE
 .TP
 \fB\-handler\fR \fIcallback\fR
@@ -263,9 +279,21 @@ proc httpHandlerCallback {socket token} {
 }
 .CE
 .PP
-The \fBhttp::geturl\fR code for the \fB-handler\fR option is not compatible with either compression or chunked transfer-encoding.  If \fB-handler\fR is specified, then to work around these issues \fBhttp::geturl\fR will reduce the HTTP protocol to 1.0, and override the \fB-zip\fR option (i.e. it will not send the header "\fBAccept-Encoding: gzip,deflate,compress\fR").
+The \fBhttp::geturl\fR code for the \fB\-handler\fR option is not compatible
+with either compression or chunked transfer-encoding.  If \fB\-handler\fR is
+specified, then to work around these issues \fBhttp::geturl\fR will reduce the
+HTTP protocol to 1.0, and override the \fB\-zip\fR option (i.e. it will not
+send the header "\fBAccept-Encoding: gzip,deflate,compress\fR").
 .PP
-If options \fB-handler\fR and \fB-channel\fR are used together, the handler is responsible for copying the data from the HTTP socket to the specified channel.  The name of the channel is available to the handler as element \fB-channel\fR of the token array.
+If options \fB\-handler\fR and \fB\-channel\fR are used together, the handler
+is responsible for copying the data from the HTTP socket to the specified
+channel.  The name of the channel is available to the handler as element
+\fB\-channel\fR of the token array.
+.PP
+The \fB::http::geturl\fR command runs the \fB\-handler\fR callback inside
+a \fBcatch\fR command.  Therefore an error in the callback command does
+not call the \fBbgerror\fR handler.  See the \fBERRORS\fR section for
+details.
 .RE
 .TP
 \fB\-headers\fR \fIkeyvaluelist\fR
@@ -293,8 +321,16 @@ multiple requests.  Default is 0.
 \fB\-method\fR \fItype\fR
 .
 Force the HTTP request method to \fItype\fR. \fB::http::geturl\fR will
-auto-select GET, POST or HEAD based on other options, but this option
-enables choices like PUT and DELETE for webdav support.
+auto-select GET, POST or HEAD based on other options, but this option overrides
+that selection and enables choices like PUT and DELETE for WebDAV support.
+.RS
+.PP
+It is the caller's responsibility to ensure that the headers and request body
+(if any) conform to the requirements of the request method.  For example, if
+using \fB\-method\fR \fIPOST\fR to send a POST with an empty request body, the
+caller must also supply the option
+.QW "\-headers {Content-Length 0}" .
+.RE
 .TP
 \fB\-myaddr\fR \fIaddress\fR
 .
@@ -327,12 +363,21 @@ otherwise complain about HTTP/1.1.
 .TP
 \fB\-query\fR \fIquery\fR
 .
-This flag causes \fB::http::geturl\fR to do a POST request that passes the
-\fIquery\fR as payload verbatim to the server.
-The content format (and encoding) of \fIquery\fR is announced by the header
-field \fBcontent-type\fR set by the option \fB-type\fR.
-\fIquery\fR is an x-url-encoding formatted query, if used for html forms.
-The \fB::http::formatQuery\fR procedure can be used to do the formatting.
+This flag (if the value is non-empty) causes \fB::http::geturl\fR to do a
+POST request that passes the string
+\fIquery\fR verbatim to the server as the request payload.
+The content format (and encoding) of \fIquery\fR is announced by the request
+header \fBContent-Type\fR which is set by the option \fB\-type\fR.  Any value
+of \fB\-type\fR is permitted, and it is the responsibility of the caller to
+supply \fIquery\fR in the correct format.
+.RS
+.PP
+If \fB\-type\fR is not specified, it defaults to
+\fIapplication/x-www-form-urlencoded\fR, which requires \fIquery\fR to be an
+x-url-encoding formatted query-string (this \fB\-type\fR and query format are
+used in a POST submitted from an html form).  The \fB::http::formatQuery\fR
+procedure can be used to do the formatting.
+.RE
 .TP
 \fB\-queryblocksize\fR \fIsize\fR
 .
@@ -531,6 +576,14 @@ to know the result of the asynchronous HTTP request, it can call
 \fB::http::wait\fR and then check status and error, just as the
 callback does.
 .PP
+The \fB::http::geturl\fR command runs the \fB\-command\fR, \fB\-handler\fR,
+and \fB\-proxyfilter\fR callbacks inside a \fBcatch\fR command.  Therefore
+an error in the callback command does not call the \fBbgerror\fR handler.
+When debugging one of these
+callbacks, it may be convenient to report errors by using a
+\fBcatch\fR command within the callback command itself, e.g. to write
+an error message to stdout.
+.PP
 In any case, you must still call
 \fB::http::cleanup\fR to delete the state array when you are done.
 .PP
@@ -601,7 +654,8 @@ if the HTTP response is text.
 \fBbody\fR
 .
 The contents of the URL.  This will be empty if the \fB\-channel\fR
-option has been specified.  This value is returned by the \fB::http::data\fR command.
+option has been specified.  This value is returned by the \fB::http::data\fR
+command.
 .TP
 \fBcharset\fR
 .
@@ -713,9 +767,9 @@ whether the server was modified by the failed POST request, before
 sending the same request again.
 .PP
 A HTTP request will use a persistent socket if the call to
-\fBhttp::geturl\fR has the option \fB-keepalive true\fR. It will use
+\fBhttp::geturl\fR has the option \fB\-keepalive true\fR. It will use
 pipelining where permitted if the \fBhttp::config\fR option
-\fB-pipeline\fR is boolean \fBtrue\fR (its default value).
+\fB\-pipeline\fR is boolean \fBtrue\fR (its default value).
 .PP
 The http package maintains no more than one persistent connection to each
 server (i.e. each value of
@@ -737,8 +791,8 @@ In accordance with RFC 7230, \fBhttp::geturl\fR does not pipeline
 requests that use the POST method.  If a POST uses a persistent
 connection and is not the first request on that connection,
 \fBhttp::geturl\fR waits until it has received the response for the previous
-request; or (if \fBhttp::config\fR option \fB-postfresh\fR is boolean \fBtrue\fR) it
-uses a new connection for each POST.
+request; or (if \fBhttp::config\fR option \fB\-postfresh\fR is boolean
+\fBtrue\fR) it uses a new connection for each POST.
 .PP
 If the server is processing a number of pipelined requests, and sends a
 response header
@@ -758,7 +812,7 @@ GET requests, \fBhttp::geturl\fR opens another connection and retransmits
 the failed request. However, if the request was a POST, RFC 7230 forbids
 automatic retry by default, suggesting either user confirmation, or
 confirmation by user-agent software that has semantic understanding of
-the application.  The \fBhttp::config\fR option \fB-repost\fR allows for
+the application.  The \fBhttp::config\fR option \fB\-repost\fR allows for
 either possibility.
 .PP
 Asynchronous close events can occur only in a short interval of time.  The
@@ -766,35 +820,36 @@ Asynchronous close events can occur only in a short interval of time.  The
 server.  Upon detection, the connection is also closed at the client end,
 and subsequent requests will use a fresh connection.
 .PP
-If the \fBhttp::geturl\fR command is called with option \fB-keepalive true\fR,
+If the \fBhttp::geturl\fR command is called with option \fB\-keepalive true\fR,
 then it will both try to use an existing persistent connection
 (if one is available), and it will send the server a
 .QW "\fBConnection: keep-alive\fR"
 request header asking to keep the connection open for future requests.
 .PP
-The \fBhttp::config\fR options \fB-pipeline\fR, \fB-postfresh\fR, and
-\fB-repost\fR relate to persistent connections.
+The \fBhttp::config\fR options \fB\-pipeline\fR, \fB\-postfresh\fR, and
+\fB\-repost\fR relate to persistent connections.
 .PP
-Option \fB-pipeline\fR, if boolean \fBtrue\fR, will pipeline GET and HEAD requests
-made
-over a persistent connection.  POST requests will not be pipelined - if the
+Option \fB\-pipeline\fR, if boolean \fBtrue\fR, will pipeline GET and HEAD
+requests made over a persistent connection.  POST requests will not be
+pipelined - if the
 POST is not the first transaction on the connection, its request will not
 be sent until the previous response has finished.  GET and HEAD requests
 made after a POST will not be sent until the POST response has been
 delivered, and will not be sent if the POST fails.
 .PP
-Option \fB-postfresh\fR, if boolean \fBtrue\fR, will override the \fBhttp::geturl\fR option
-\fB-keepalive\fR, and always open a fresh connection for a POST request.
+Option \fB\-postfresh\fR, if boolean \fBtrue\fR, will override the
+\fBhttp::geturl\fR option \fB\-keepalive\fR, and always open a fresh connection
+for a POST request.
 .PP
-Option \fB-repost\fR, if \fBtrue\fR, permits automatic retry of a POST request
+Option \fB\-repost\fR, if \fBtrue\fR, permits automatic retry of a POST request
 that fails because it uses a persistent connection that the server has
 half-closed (an
 .QW "asynchronous close event" ).
 Subsequent GET and HEAD requests in a failed pipeline will also be retried.
-\fIThe -repost option should be used only if the application understands
+\fIThe \-repost option should be used only if the application understands
 that the retry is appropriate\fR - specifically, the application must know
-that if the failed POST successfully modified the state of the server, a repeat POST
-would have no adverse effect.
+that if the failed POST successfully modified the state of the server, a repeat
+POST would have no adverse effect.
 .VS TIP406
 .SH "COOKIE JAR PROTOCOL"
 .PP
@@ -897,6 +952,40 @@ request.
 Other keys may always be ignored; they have no meaning in this protocol.
 .RE
 .VE TIP406
+.SH "PROTOCOL UPGRADES"
+.PP
+The HTTP/1.1 \fBConnection\fR and \fBUpgrade\fR client headers inform the server
+that the client wishes to change the protocol used over the existing connection
+(RFC 7230).  This mechanism can be used to request a WebSocket (RFC 6455), a
+higher version of the HTTP protocol (HTTP 2), or TLS encryption.  If the
+server accepts the upgrade request, its response code will be 101.
+.PP
+To request a protocol upgrade when calling \fBhttp::geturl\fR, the \fB\-headers\fR
+option must supply appropriate values for \fBConnection\fR and \fBUpgrade\fR, and
+the \fB\-command\fR option must supply a command that implements the requested
+protocol and can also handle the server response if the server refuses the
+protocol upgrade.  For upgrade requests \fBhttp::geturl\fR ignores the value of
+option \fB\-keepalive\fR, and always uses the value \fB0\fR so that the upgrade
+request is not made over a connection that is intended for multiple HTTP requests.
+.PP
+The Tcllib library \fBwebsocket\fR implements WebSockets, and makes the necessary
+calls to commands in the \fBhttp\fR package.
+.PP
+There is currently no native Tcl client library for HTTP/2.
+.PP
+The \fBUpgrade\fR mechanism is not used to request TLS in web browsers, because
+\fBhttp\fR and \fBhttps\fR are served over different ports.  It is used by
+protocols such as Internet Printing Protocol (IPP) that are built on top of
+\fBhttp(s)\fR and use the same TCP port number for both secure and insecure
+traffic.
+.PP
+In browsers, opportunistic encryption is instead implemented by the
+\fBUpgrade-Insecure-Requests\fR client header.  If a secure service is available,
+the server response code is a 307 redirect, and the response header
+\fBLocation\fR specifies the target URL.  The browser must call \fBhttp::geturl\fR
+again in order to fetch this URL.
+See https://w3c.github.io/webappsec-upgrade-insecure-requests/
+.PP
 .SH EXAMPLE
 .PP
 This example creates a procedure to copy a URL to a file while printing a
@@ -932,7 +1021,7 @@ proc httpcopy { url file {chunk 4096} } {
    return $token
 }
 proc httpCopyProgress {args} {
-    puts -nonewline stderr .
+    puts \-nonewline stderr .
    flush stderr
 }
 .CE
@@ -68,8 +68,6 @@ that represents an instance of \fBoo::object\fR or one of its subclasses.
 \fIcommandName\fR was created by \fBinterp create\fR.
 .IP \fBzlibStream\fR
 \fIcommandName\fR was created by \fBzlib stream\fR.
-.PP
-Other types may be also registered as well.  See \fBTcl_RegisterCommandTypeName\fR.
 .RE
 .VE TIP426
 .TP
@@ -375,6 +375,10 @@ Returns a Tcl list of the names of all the child interpreters associated
 with the interpreter identified by \fIpath\fR. If \fIpath\fR is omitted,
 the invoking interpreter is used.
 .TP
+\fBinterp\fR \fBslaves\fR ?\fIpath\fR?
+.
+Synonym for . \fBinterp\fR \fBchildren\fR ?\fIpath\fR?
+.TP
 \fBinterp\fR \fBtarget\fR \fIpath alias\fR
 .
 Returns a Tcl list describing the target interpreter for an alias. The
@@ -38,14 +38,17 @@ Tcl interpreter.
 The name of the initialization procedure is determined by
 \fIprefix\fR and whether or not the target interpreter
 is a safe one.  For normal interpreters the name of the initialization
-procedure will have the form \fIprefix\fB_Init\fR.  For example, if
-\fIprefix\fR is \fBFoo\fR, the initialization procedure's name will
+procedure will have the form \fIpfx\fB_Init\fR, where \fIpfx\fR
+is the same as \fIprefix\fR except that the first letter is
+converted to upper case and all other letters
+are converted to lower case.  For example, if \fIprefix\fR is
+\fBfoo\fR or \fBFOo\fR, the initialization procedure's name will
 be \fBFoo_Init\fR.
 .PP
 If the target interpreter is a safe interpreter, then the name
-of the initialization procedure will be \fIprefix\fB_SafeInit\fR
-instead of \fIprefix\fB_Init\fR.
-The \fIprefix\fB_SafeInit\fR function should be written carefully, so that it
+of the initialization procedure will be \fIpfx\fB_SafeInit\fR
+instead of \fIpfx\fB_Init\fR.
+The \fIpfx\fB_SafeInit\fR function should be written carefully, so that it
 initializes the safe interpreter only with partial functionality provided
 by the library that is safe for use by untrusted code. For more information
 on Safe\-Tcl, see the \fBsafe\fR manual entry.
@@ -81,11 +84,13 @@ If \fIfileName\fR is an empty string, then \fIprefix\fR must
 be specified.
 .PP
 If \fIprefix\fR is omitted or specified as an empty string,
-Tcl tries to guess the prefix by taking the last element of
+Tcl tries to guess the prefix. This may be done differently on
+different platforms. The default guess, which is used on most
+UNIX platforms, is to take the last element of
 \fIfileName\fR, strip off the first three characters if they
-are \fBlib\fR, then strip off the next three characters if
-they are \fBtcl9\fR, and use any following wordchars but not digits,
-converted to titlecase as the prefix.
+are \fBlib\fR, then strip off the next three characters if they
+are \fBtcl\fR, and use any following alphabetic and
+underline characters, converted to titlecase as the prefix.
 For example, the command \fBload libxyz4.2.so\fR uses the prefix
 \fBXyz\fR and the command \fBload bin/last.so {}\fR uses the
 prefix \fBLast\fR.
--- a/Show More
+++ b/Show More