Store userEncoding in Thread Local Storage

Merge 9.0. Handle one-argument "encoding user" better.
Fix [9dcdddeefe]: compiler warnings. No need to put this in changelog, since it's introduced after 9.0.1.
2025-05-09 09:04:55 +00:00 · 2025-05-09 08:19:24 +00:00 · 2025-05-08 15:19:32 +00:00 · 2025-05-08 12:42:11 +00:00 · 2025-05-08 08:54:15 +00:00 · 2025-05-07 21:15:53 +00:00
1027 changed files with 167726 additions and 161969 deletions
@@ -11,14 +11,9 @@ compat/zlib/zlib.map
 libtommath/*.dsp
 libtommath/*.sln
 libtommath/*.vcproj
-tools/tcl.hpj.in
 tools/tcl.wse.in
-win/buildall.vc.bat
+win/*.bat
+win/*.vc
 win/coffbase.txt
-win/makefile.vc
-win/rules.vc
-win/rules-ext.vc
-win/targets.vc
 win/tcl.dsp
 win/tcl.dsw
-win/tcl.hpj.in
@@ -1,9 +1,7 @@
-tools/tcl.hpj.in
 tools/tcl.wse.in
 win/buildall.vc.bat
 win/coffbase.txt
 win/makefile.vc
 win/rules.vc
 win/tcl.dsp
-win/tcl.dsw
-win/tcl.hpj.in
+win/tcl.dsw
@@ -48,9 +48,11 @@ libtommath/*.tex
 macosx/configure
 unix/autoMkindex.tcl
 unix/dltest.marker
+unix/dltest/embtest
 unix/dltest/*.bundle
 unix/dltest/*.dll
 unix/dltest/*.dylib
+unix/dltest/*.exe
 unix/dltest/*.o
 unix/dltest/*.sl
 unix/dltest/*.so
@@ -58,10 +60,12 @@ unix/tcl.pc
 unix/tclIndex
 unix/Tcl-Info.plist
 unix/Tclsh-Info.plist
+unix/pkgs8/*
 unix/pkgs/*
 win/Debug*
 win/Release*
 win/*.manifest
+win/pkgs8/*
 win/pkgs/*
 win/coffbase.txt
 win/tcl.hpj
@@ -23,6 +23,8 @@
 # Declare files that will always have CRLF line endings on checkout.
 *.bat eol=crlf
 *.cs eol=crlf
+*.dsp eol=crlf
+*.dsw eol=crlf
 *.sln eol=crlf
 *.vc eol=crlf

@@ -0,0 +1,6 @@
+version: 2
+updates:
+- package-ecosystem: "github-actions"
+  directory: "/"
+  schedule:
+      interval: "weekly"
@@ -3,7 +3,7 @@ on:
  push:
    branches:
    - "main"
-    - "core-8-6-branch"
+    - "core-9-0-branch"
    tags:
    - "core-**"
 permissions:
@@ -15,13 +15,13 @@ jobs:
      matrix:
        config:
          - ""
+          - "CFLAGS=-DTCL_NO_DEPRECATED=1"
          - "--disable-shared"
+          - "--disable-zipfs"
          - "--enable-symbols"
          - "--enable-symbols=mem"
          - "--enable-symbols=all"
          - "CFLAGS=-ftrapv"
-          - "CFLAGS=-DTCL_UTF_MAX=4"
-          - "CFLAGS=-DTCL_UTF_MAX=6"
          # Duplicated below
          - "CFLAGS=-m32 CPPFLAGS=-m32 LDFLAGS=-m32 --disable-64bit"
    defaults:
@@ -40,7 +40,7 @@ jobs:
          sudo apt-get install gcc-multilib libc6-dev-i386
      - name: Prepare
        run: |
-          touch tclStubInit.c tclOOStubInit.c
+          touch tclStubInit.c tclOOStubInit.c tclOOScript.h
        working-directory: generic
      - name: Configure ${{ matrix.config }}
        run: |
@@ -3,14 +3,14 @@ on:
  push:
    branches:
    - "main"
-    - "core-8-6-branch"
+    - "core-9-0-branch"
    tags:
    - "core-**"
 permissions:
  contents: read
 jobs:
  xcode:
-    runs-on: macos-13
+    runs-on: macos-15
    defaults:
      run:
        shell: bash
@@ -21,10 +21,12 @@ jobs:
        timeout-minutes: 5
      - name: Prepare
        run: |
-          touch tclStubInit.c tclOOStubInit.c
+          touch tclStubInit.c tclOOStubInit.c tclOOScript.h
        working-directory: generic
      - name: Build
        run: make -j4 all
+        env:
+          CFLAGS: -arch x86_64 -arch arm64
        timeout-minutes: 15
      - name: Run Tests
        run: make -j4 test styles=develop
@@ -33,12 +35,13 @@ jobs:
          MAC_CI: 1
        timeout-minutes: 15
  clang:
-    runs-on: macos-13
+    runs-on: macos-15
    strategy:
      matrix:
        config:
          - ""
          - "--disable-shared"
+          - "--disable-zipfs"
          - "--enable-symbols"
          - "--enable-symbols=mem"
          - "--enable-symbols=all"
@@ -52,18 +55,21 @@ jobs:
        timeout-minutes: 5
      - name: Prepare
        run: |
-          touch tclStubInit.c tclOOStubInit.c
+          touch tclStubInit.c tclOOStubInit.c tclOOScript.h
          mkdir "$HOME/install dir"
        working-directory: generic
      - name: Configure ${{ matrix.config }}
        # Note that macOS is always a 64 bit platform
-        run: ./configure --enable-64bit --enable-dtrace --enable-framework ${CFGOPT} "--prefix=$HOME/install" || (cat config.log && exit 1)
+        run: ./configure --enable-dtrace --enable-framework ${CFGOPT} "--prefix=$HOME/install" || (cat config.log && exit 1)
        env:
+          CFLAGS: -arch x86_64 -arch arm64
          CFGOPT: ${{ matrix.config }}
        timeout-minutes: 5
      - name: Build
        run: |
          make -j4 all tcltest
+        env:
+          CFLAGS: -arch x86_64 -arch arm64
        timeout-minutes: 15
      - name: Info
        run: |
@@ -0,0 +1,244 @@
+name: Build Binaries
+on:
+  push:
+    branches:
+    - "main"
+    - "core-9-0-branch"
+    tags:
+    - "core-**"
+permissions:
+  contents: read
+jobs:
+  linux:
+    name: Linux
+    runs-on: ubuntu-22.04
+    defaults:
+      run:
+        shell: bash
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Prepare
+        run: |
+          touch generic/tclStubInit.c generic/tclOOStubInit.c
+          mkdir 1dist
+          echo "VER_PATH=$(cd tools; pwd)/addVerToFile.tcl" >> $GITHUB_ENV
+        working-directory: .
+      - name: Configure
+        run: ./configure --disable-symbols --disable-shared --enable-zipfs
+        working-directory: unix
+      - name: Build
+        run: |
+          make tclsh
+          make shell SCRIPT="$VER_PATH $GITHUB_ENV"
+          echo "TCL_ZIP=`pwd`/`echo libtcl*.zip`" >> $GITHUB_ENV
+        working-directory: unix
+      - name: Package
+        run: |
+          cp ../unix/tclsh tclsh${TCL_PATCHLEVEL}_snapshot
+          chmod +x tclsh${TCL_PATCHLEVEL}_snapshot
+          tar -cf tclsh${TCL_PATCHLEVEL}_snapshot.tar tclsh${TCL_PATCHLEVEL}_snapshot
+        working-directory: 1dist
+      - name: Info
+        run: |
+          ulimit -a || echo 'get limit failed'
+          echo 'puts exe:\t[info nameofexecutable]\nver:\t[info patchlevel]\t[if {![catch tcl::build-info ret]} {set ret}]\nlib:\t[info library]\nplat:\t[lsort -dictionary -stride 2 [array get tcl_platform]]' | make runtest || echo 'get info failed'
+      - name: Upload
+        uses: actions/upload-artifact@v4
+        with:
+          name: Tclsh ${{ env.TCL_PATCHLEVEL }} Linux single-file build (snapshot)
+          path: 1dist/*.tar
+        id: upload
+    outputs:
+      url: ${{ steps.upload.outputs.artifact-url }}
+  macos:
+    name: macOS
+    runs-on: macos-13
+    defaults:
+      run:
+        shell: bash
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Checkout create-dmg
+        uses: actions/checkout@v4
+        with:
+          repository: create-dmg/create-dmg
+          ref: v1.0.8
+          path: create-dmg
+      - name: Prepare
+        run: |
+          mkdir 1dist
+          touch generic/tclStubInit.c generic/tclOOStubInit.c || true
+          wget https://github.com/culler/macher/releases/download/v1.7/macher
+          sudo cp macher /usr/local/bin
+          sudo chmod a+x /usr/local/bin/macher
+          echo "VER_PATH=$(cd tools; pwd)/addVerToFile.tcl" >> $GITHUB_ENV
+          echo "CREATE_DMG=$(cd create-dmg;pwd)/create-dmg" >> $GITHUB_ENV
+          echo "CFLAGS=-arch x86_64 -arch arm64" >> $GITHUB_ENV
+      - name: Configure
+        run: ./configure --disable-symbols --disable-shared --enable-zipfs
+        working-directory: unix
+      - name: Build
+        run: |
+          make -j4 tclsh
+          make -j4 shell SCRIPT="$VER_PATH $GITHUB_ENV"
+          echo "TCL_BIN=`pwd`/tclsh" >> $GITHUB_ENV
+          echo "TCL_ZIP=`pwd`/`echo libtcl*.zip`" >> $GITHUB_ENV
+        working-directory: unix
+      - name: Package
+        run: |
+          mkdir contents
+          cp $TCL_BIN contents/tclsh${TCL_PATCHLEVEL}_snapshot
+          chmod +x contents/tclsh${TCL_PATCHLEVEL}_snapshot
+          cat > contents/README.txt <<EOF
+          This is a single-file executable developer preview of Tcl $TCL_PATCHLEVEL
+
+          It is not intended as an official release at all, so it is unsigned and unnotarized.
+          Use strictly at your own risk.
+
+          To run it, you need to copy the executable out and run:
+              xattr -d com.apple.quarantine tclsh${TCL_PATCHLEVEL}_snapshot
+          to mark the executable as runnable on your machine.
+          EOF
+          $CREATE_DMG \
+              --volname "Tcl $TCL_PATCHLEVEL (snapshot)" \
+              --window-pos 200 120 \
+              --window-size 800 400 \
+              "Tcl-$TCL_PATCHLEVEL-(snapshot).dmg" \
+              "contents/"
+        working-directory: 1dist
+      - name: Info
+        run: |
+          ulimit -a || echo 'get limit failed'
+          echo 'puts exe:\t[info nameofexecutable]\nver:\t[info patchlevel]\t[if {![catch tcl::build-info ret]} {set ret}]\nlib:\t[info library]\nplat:\t[lsort -dictionary -stride 2 [array get tcl_platform]]' | make runtest || echo 'get info failed'
+      - name: Upload
+        uses: actions/upload-artifact@v4
+        with:
+          name: Tclsh ${{ env.TCL_PATCHLEVEL }} macOS single-file build (snapshot)
+          path: 1dist/*.dmg
+        id: upload
+    outputs:
+      url: ${{ steps.upload.outputs.artifact-url }}
+  win:
+    name: Windows
+    runs-on: windows-2019
+    defaults:
+      run:
+        shell: msys2 {0}
+    timeout-minutes: 10
+    env:
+      CC: gcc
+      CFGOPT: --disable-symbols --disable-shared
+    steps:
+      - name: Install MSYS2
+        uses: msys2/setup-msys2@v2
+        with:
+          msystem: UCRT64
+          install: git mingw-w64-ucrt-x86_64-toolchain make zip
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Prepare
+        run: |
+          touch generic/tclStubInit.c generic/tclOOStubInit.c
+          echo "VER_PATH=$(cd tools; pwd)/addVerToFile.tcl" >> $GITHUB_ENV
+          mkdir 1dist
+        working-directory: .
+      - name: Configure
+        run: ./configure $CFGOPT
+        working-directory: win
+      - name: Build
+        run: |
+          make binaries libraries
+          echo "TCL_ZIP=`pwd`/`echo libtcl*.zip`" >> $GITHUB_ENV
+          rm tclsh*c*.exe
+        working-directory: win
+      - name: Get Exact Version
+        run: |
+          ./tclsh*.exe $VER_PATH $GITHUB_ENV
+        working-directory: win
+      - name: Set Executable Name
+        run: |
+          cp ../win/tclsh*.exe tclsh${TCL_PATCHLEVEL}_snapshot.exe
+        working-directory: 1dist
+      - name: Info
+        run: |
+          ulimit -a || echo 'get limit failed'
+          echo 'puts exe:\t[info nameofexecutable]\nver:\t[info patchlevel]\t[if {![catch tcl::build-info ret]} {set ret}]\nlib:\t[info library]\nplat:\t[lsort -dictionary -stride 2 [array get tcl_platform]]' | make runtest || echo 'get info failed'
+      - name: Upload
+        uses: actions/upload-artifact@v4
+        with:
+          name: Tclsh ${{ env.TCL_PATCHLEVEL }} Windows single-file build (snapshot)
+          path: '1dist/*_snapshot.exe'
+        id: upload
+    outputs:
+      url: ${{ steps.upload.outputs.artifact-url }}
+  combine:
+    needs:
+      - linux
+      - macos
+      - win
+    name: Combine Artifacts (prototype)
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+    timeout-minutes: 10
+    env:
+      # See also
+      # https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables
+      REMOTE_PATH: ${{ vars.PUBLISH_DROP_PATH }}/data-${{ github.sha }}
+    steps:
+      - name: Make directory
+        run: |
+          mkdir data
+      - name: Get Linux build
+        uses: actions/download-artifact@v4
+        with:
+          path: data
+          # Can't download by artifact ID; stupid missing feature!
+          merge-multiple: true
+      - name: Check data downloaded
+        run: |
+          ls -AlR
+        working-directory: data
+      - name: Transfer built files
+        # https://github.com/marketplace/actions/rsync-deployments-action
+        uses: burnett01/rsync-deployments@7.0.2
+        id: rsync
+        if: false  # Disabled... for now
+        with:
+          # I don't know what the right switches are here, BTW
+          switches: -avzr
+          path: data/
+          remote_path: ${{ env.REMOTE_PATH }}
+          remote_host: ${{ vars.PUBLISH_HOST }}
+          remote_user: ${{ vars.PUBLISH_USER }}
+          remote_key: ${{ secrets.DEPLOY_HOST_KEY }}
+          # MUST be a literal passwordless key
+      - name: Publish files
+        # https://github.com/marketplace/actions/ssh-remote-commands
+        uses: appleboy/ssh-action@v1.2.2
+        id: ssh
+        if: steps.rsync.outcome == 'success'
+        with:
+          host: ${{ vars.PUBLISH_HOST }}
+          username: ${{ vars.PUBLISH_USER }}
+          key: ${{ secrets.DEPLOY_HOST_KEY }}
+          script: |
+            ${{ vars.PUBLISHER_SCRIPT }} ${{ env.REMOTE_PATH }} ${{ github.ref_type }} ${{ github.ref_name }}
+      - name: Report what would be done
+        if: steps.rsync.outcome == 'skipped'
+        env:
+          SWITCHES: -av
+          LOCAL_PATH: data/
+          REMOTE_HOST: ${{ vars.PUBLISH_HOST }}
+          REMOTE_USER: ${{ vars.PUBLISH_USER }}
+          REMOTE_SCRIPT: |
+            ${{ vars.PUBLISHER_SCRIPT }} ${{ env.REMOTE_PATH }} ${{ github.ref_type }} ${{ github.ref_name }}
+        run: |
+          echo "would run: rsync $SWITCHES $LOCAL_PATH $REMOTE_USER@$REMOTE_HOST:$REMOTE_PATH"
+          echo "would run: ssh $REMOTE_USER@$REMOTE_HOST $REMOTE_SCRIPT"
+      # Consider https://github.com/marketplace/actions/slack-notify maybe?
@@ -3,7 +3,7 @@ on:
  push:
    branches:
    - "main"
-    - "core-8-6-branch"
+    - "core-9-0-branch"
    tags:
    - "core-**"
 permissions:
@@ -21,8 +21,9 @@ jobs:
      matrix:
        config:
          - ""
-          - "OPTS=static,msvcrt"
-          - "OPTS=static,staticpkg,msvcrt"
+          - "CHECKS=nodep"
+          - "OPTS=static"
+          - "OPTS=noembed"
          - "OPTS=symbols"
          - "OPTS=symbols STATS=compdbg,memdbg"
    # Using powershell means we need to explicitly stop on failure
@@ -64,7 +65,9 @@ jobs:
      matrix:
        config:
          - ""
+          - "CFLAGS=-DTCL_NO_DEPRECATED=1"
          - "--disable-shared"
+          - "--disable-zipfs"
          - "--enable-symbols"
          - "--enable-symbols=mem"
          - "--enable-symbols=all"
@@ -81,7 +84,7 @@ jobs:
        timeout-minutes: 5
      - name: Prepare
        run: |
-          touch tclStubInit.c tclOOStubInit.c
+          touch tclStubInit.c tclOOStubInit.c tclOOScript.h
          mkdir "${HOME}/install dir"
        working-directory: generic
      - name: Configure ${{ matrix.config }}
@@ -53,12 +53,15 @@ libtommath/*.tex
 macosx/configure
 unix/autoMkindex.tcl
 unix/dltest.marker
+unix/dltest/embtest
 unix/tcl.pc
 unix/tclIndex
+unix/pkgs8/*
 unix/pkgs/*
 win/Debug*
 win/Release*
 win/*.manifest
+win/pkgs8/*
 win/pkgs/*
 win/coffbase.txt
 win/tcl.hpj
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <projectDescription>
-	<name>tcl8.6</name>
+	<name>tcl9</name>
 	<comment></comment>
 	<projects>
 	</projects>
@@ -1,19 +1,19 @@
 # README:  Tcl

-This is the **Tcl 8.6.17** source distribution.
+This is the **Tcl 9.0.2** source distribution.

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

-9.0 (production release, daily build)
+9.1 (in development, daily build)
 [![Build Status](https://github.com/tcltk/tcl/actions/workflows/linux-build.yml/badge.svg?branch=main)](https://github.com/tcltk/tcl/actions/workflows/linux-build.yml?query=branch%3Amain)
 [![Build Status](https://github.com/tcltk/tcl/actions/workflows/win-build.yml/badge.svg?branch=main)](https://github.com/tcltk/tcl/actions/workflows/win-build.yml?query=branch%3Amain)
 [![Build Status](https://github.com/tcltk/tcl/actions/workflows/mac-build.yml/badge.svg?branch=main)](https://github.com/tcltk/tcl/actions/workflows/mac-build.yml?query=branch%3Amain)
 <br>
-8.6 (this release, daily build)
-[![Build Status](https://github.com/tcltk/tcl/actions/workflows/linux-build.yml/badge.svg?branch=core-8-6-branch)](https://github.com/tcltk/tcl/actions/workflows/linux-build.yml?query=branch%3Acore-8-6-branch)
-[![Build Status](https://github.com/tcltk/tcl/actions/workflows/win-build.yml/badge.svg?branch=core-8-6-branch)](https://github.com/tcltk/tcl/actions/workflows/win-build.yml?query=branch%3Acore-8-6-branch)
-[![Build Status](https://github.com/tcltk/tcl/actions/workflows/mac-build.yml/badge.svg?branch=core-8-6-branch)](https://github.com/tcltk/tcl/actions/workflows/mac-build.yml?query=branch%3Acore-8-6-branch)
+9.0 (production release, daily build)
+[![Build Status](https://github.com/tcltk/tcl/actions/workflows/linux-build.yml/badge.svg?branch=core-9-0-branch)](https://github.com/tcltk/tcl/actions/workflows/linux-build.yml?query=branch%3Acore-9-0-branch)
+[![Build Status](https://github.com/tcltk/tcl/actions/workflows/win-build.yml/badge.svg?branch=core-9-0-branch)](https://github.com/tcltk/tcl/actions/workflows/win-build.yml?query=branch%3Acore-9-0-branch)
+[![Build Status](https://github.com/tcltk/tcl/actions/workflows/mac-build.yml/badge.svg?branch=core-9-0-branch)](https://github.com/tcltk/tcl/actions/workflows/mac-build.yml?query=branch%3Acore-9-0-branch)

 ## Contents
 1. [Introduction](#intro)
@@ -51,7 +51,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/8.6.html).
+[here](https://www.tcl-lang.org/software/tcltk/9.0.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.
@@ -61,8 +61,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 8.6 is [online,
-here](https://www.tcl-lang.org/man/tcl8.6/).
+The complete set of reference manual entries for Tcl 9.0 is [online,
+here](https://www.tcl-lang.org/man/tcl9.0/).

 ### <a id="doc.unix">2a.</a> Unix Documentation
 The `doc` subdirectory in this release contains a complete set of
@@ -0,0 +1,214 @@
+
+The source code for Tcl is managed by fossil.  Tcl developers coordinate all
+changes to the Tcl source code at
+
+> [Tcl Source Code](https://core.tcl-lang.org/tcl/timeline)
+
+Release Tcl 9.0.2 arises from the check-in with tag `core-9-0-2`.
+
+Tcl patch releases have the primary purpose of delivering bug fixes
+to the userbase.
+
+# Bug fixes
+ - [Better error-message than "interpreter uses an incompatible stubs mechanism"](https://core.tcl-lang.org/tcl/tktview/fc3509)
+ - [\[$interp eval $lambda\] after \[eval $lambda\] or vice versa fails](https://core.tcl-lang.org/tcl/tktview/67d5f7)
+ - [tcl::mathfunc::isunordered inconsistency with some integer values](https://core.tcl-lang.org/tcl/tktview/98006f)
+ - [test lseq hangs with -Os](https://core.tcl-lang.org/tcl/tktview/d2a3c5)
+ - [exec does not handle app execution aliases on Windows](https://core.tcl-lang.org/tcl/tktview/4f0b57)
+ - [auto_execok does not find several built-in cmd commands](https://core.tcl-lang.org/tcl/tktview/4e2c8b)
+ - [Panic "Buffer Underflow, BUFFER_PADDING not enough"](https://core.tcl-lang.org/tcl/tktview/73bb42)
+ - [MS-VS build system: pckIndex.tcl when building for 9 misses "t" for TCL 8.6 part](https://core.tcl-lang.org/tcl/tktview/a77029)
+ - [clock format -locale does not look up locale children if parent locale used first](https://core.tcl-lang.org/tcl/tktview/2c0f49)
+ - [Missing libtcl?.?.dll.a in Cygwin](https://core.tcl-lang.org/tcl/tktview/dcedba)
+ - [tclEpollNotfy PlatformEventsControl panics if websocket disconnected](https://core.tcl-lang.org/tcl/tktview/010d8f)
+ - [Tcl_InitStubs compatibility for 9.1](https://core.tcl-lang.org/tcl/tktview/fd8341)
+ - [proc with more than 2**31 variables](https://core.tcl-lang.org/tcl/tktview/92aeb8)
+ - [scan "long mantissa" %g](https://core.tcl-lang.org/tcl/tktview/42d14c)
+ - ["encoding system": wrong result without manifest](https://core.tcl-lang.org/tcl/tktview/8ffd8c)
+ - [lseq crash on out-of-range index](https://core.tcl-lang.org/tcl/tktview/7d3101)
+ - [lseq crash on nested indices](https://core.tcl-lang.org/tcl/tktview/452b10)
+
+# Incompatibilities
+ - No known incompatibilities with the Tcl 9.0.0 public interface.
+
+# Updated bundled packages, libraries, standards, data
+ - sqlite3 3.49.1
+ - tzdata 2025b
+
+Release Tcl 9.0.1 arises from the check-in with tag `core-9-0-1`.
+
+Tcl patch releases have the primary purpose of delivering bug fixes
+to the userbase.  As the first patch release in the Tcl 9.0.\* series,
+Tcl 9.0.1 also includes a small number of interface changes that complete
+some incomplete features first delivered in Tcl 9.0.0.
+
+# Completed 9.0 Features and Interfaces
+ - [TIP 701 - Tcl_FSTildeExpand C API](https://core.tcl-lang.org/tips/doc/trunk/tip/701.md)
+ - [TIP 707 - ptrAndSize internal rep in Tcl_Obj](https://core.tcl-lang.org/tips/doc/trunk/tip/707.md)
+ - [Size modifiers j, q, z, t not implemented]( https://core.tcl-lang.org/tcl/info/c4f365)
+
+# Bug fixes
+ - [regression in tzdata, %z instead of offset TZ-name](https://core.tcl-lang.org/tcl/tktview/2c237b)
+ - [Tcl will not start properly if there is an init.tcl file in the current dir](https://core.tcl-lang.org/tcl/tktview/43c94f)
+ - [clock scan "24:00", ISO-8601 compatibility](https://core.tcl-lang.org/tcl/tktview/aee9f2)
+ - [Temporary folder with file "tcl9registry13.dll" remains after "exit"](https://core.tcl-lang.org/tcl/tktview/6ce3c0)
+ - [Wrong result by "lsearch -stride -subindices -inline -all"](https://core.tcl-lang.org/tcl/info/5a1aaa)
+ - [TIP 609 - required Tcl_ThreadAlert() skipped with nested event loop](https://core.tcl-lang.org/tcl/info/c7e4c4)
+ - [buffer overwrite for non-BMP characters in utf-16](https://core.tcl-lang.org/tcl/tktview/66da4d)
+ - [zipfs info on mountpoint of executable returns zero offset in field 4"](https://core.tcl-lang.org/tcl/info/aaa84f)
+ - [zlib-8.8, zlib-8.16 fail on Fedora 40, gcc 14.1.1](https://core.tcl-lang.org/tcl/tktview/73d5cb)
+ - [install registry and dde in $INSTALL_DIR\lib always](https://core.tcl-lang.org/tcl/tktview/364bd9)
+ - [cannot build .chm help file (Windows)](https://core.tcl-lang.org/tcl/tktview/bb110c)
+
+# Incompatibilities
+ - No known incompatibilities with the Tcl 9.0.0 public interface.
+
+# Updated bundled packages, libraries, standards, data
+ - Itcl 4.3.2
+ - sqlite3 3.47.2
+ - Thread 3.0.1
+ - TDBC\* 1.1.10
+ - tcltest 2.5.9
+ - tzdata 2024b, corrected
+
+Release Tcl 9.0.0 arises from the check-in with tag `core-9-0-0`.
+
+Highlighted differences between Tcl 9.0 and Tcl 8.6 are summarized below,
+with focus on changes important to programmers using the Tcl library and
+writing Tcl scripts.
+
+# Major Features
+
+## 64-bit capacity: Data values larger than 2Gb
+ - Strings can be any length (that fits in your available memory)
+ - Lists and dictionaries can have very large numbers of elements
+
+## Internationalization of text
+ - Full Unicode range of codepoints
+ - New encodings: `utf-16`/`utf-32`/`ucs-2`(`le`|`be`), `CESU-8`, etc.
+ - `encoding` options `-profile`, `-failindex` manage encoding of I/O.
+ - `msgcat` supports custom locale search list
+ - `source` defaults to `-encoding utf-8`
+
+## Zip filesystems and attached archives.
+ - Packaging of the Tcl script library with the Tcl binary library,
+   meaning that the `TCL_LIBRARY` environment variable is usually not required.
+ - Packaging of an application into a virtual filesystem is now a supported
+   core Tcl feature.
+
+## Unix notifiers available using `epoll()` or `kqueue()`
+ - This relieves limits on file descriptors imposed by legacy `select()` and fixes a performance bottleneck.
+
+# Incompatibilities
+
+## Notable incompatibilities
+ - Unqualified varnames resolved in current namespace, not global.
+   Note that in almost all cases where this causes a change, the change is actually the removal of a latent bug.
+ - No `--disable-threads` build option.  Always thread-enabled.
+ - I/O malencoding default response: raise error (`-profile strict`)
+ - Windows platform needs Windows 7 or Windows Server 2008 R2 or later
+ - Ended interpretation of `~` as home directory in pathnames.
+   (See `file home` and `file tildeexpand` for replacements when you need them.)
+ - Removed the `identity` encoding.
+   (There were only ever very few valid use cases for this; almost all uses
+   were systematically wrong.)
+ - Removed the encoding alias `binary` to `iso8859-1`.
+ - `$::tcl_precision` no longer controls string generation of doubles.
+   (If you need a particular precision, use `format`.)
+ - Removed pre-Tcl 8 legacies: `case`, `puts` and `read` variant syntaxes.
+ - Removed subcommands [`trace variable`|`vdelete`|`vinfo`]
+ - Removed `-eofchar` option for write channels.
+ - On Windows 10+ (Version 1903 or higher), system encoding is always utf-8.
+ - `%b`/`%d`/`%o`/`%x` format modifiers (without size modifier) for `format`
+   and `scan` always truncate to 32-bits on all platforms.
+ - `%L` size modifier for `scan` no longer truncates to 64-bit.
+ - Removed command `::tcl::unsupported::inject`.
+   (See `coroinject` and `coroprobe` for supported commands with significantly
+   more comprehensible semantics.)
+
+## Incompatibilities in C public interface
+ - Extensions built against Tcl 8.6 and before will not work with Tcl 9.0;
+   ABI compatibility was a non-goal for 9.0.  In _most_ cases, rebuilding
+   against Tcl 9.0 should work except when a removed API function is used.
+ - Many arguments expanded type from `int` to `Tcl_Size`, a signed integer type
+   large enough to support 64-bit sized memory objects.
+   The constant `TCL_AUTO_LENGTH` is a value of that type that indicates that
+   the length should be obtained using an appropriate function (typically `strlen()` for `char *` values).
+ - Ended support for `Tcl_ChannelTypeVersion` less than 5
+ - Introduced versioning of the `Tcl_ObjType` struct
+ - Removed macros `CONST*`: Tcl 9 support means dropping Tcl 8.3 support.
+   (Replaced with standard C `const` keyword going forward.)
+ - Removed registration of several `Tcl_ObjType`s.
+ - Removed API functions:
+
+     `Tcl_Backslash()`,
+     `Tcl_*VA()`,
+     `Tcl_*MathFunc*()`,
+     `Tcl_MakeSafe()`,
+     `Tcl_(Save|Restore|Discard|Free)Result()`,
+     `Tcl_EvalTokens()`,
+     `Tcl_(Get|Set)DefaultEncodingDir()`,
+     `Tcl_UniCharN(case)cmp()`,
+     `Tcl_UniCharCaseMatch()`
+
+ - Revised many internals; beware reliance on undocumented behaviors.
+
+# New Features
+
+## New commands
+ - `array default` — Specify default values for arrays (note that this alters the behaviour of `append`, `incr`, `lappend`).
+ - `array for` — Cheap iteration over an array's contents.
+ - `chan isbinary` — Test if a channel is configured to work with binary data.
+ - `coroinject`, `coroprobe` — Interact with paused coroutines.
+ - `clock add weekdays` — Clock arithmetic with week days.
+ - `const`, `info const*` — Commands for defining constants (variables that can't be modified).
+ - `dict getwithdefault` — Define a fallback value to use when `dict get` would otherwise fail.
+ - `file home` — Get the user home directory.
+ - `file tempdir` — Create a temporary directory.
+ - `file tildeexpand` — Expand a file path containing a `~`.
+ - `info commandtype` — Introspection for the kinds of commands.
+ - `ledit` — Equivalent to `lreplace` but on a list in a variable.
+ - `lpop` — Remove an item from a list in a variable.
+ - `lremove` — Remove a sublist from a list in a variable.
+ - `lseq` — Generate a list of numbers in a sequence.
+ - `package files` — Describe the contents of a package.
+ - `string insert` — Insert a string as a substring of another string.
+ - `string is dict` — Test whether a string is a dictionary.
+ - `tcl::process` — Commands for working with subprocesses.
+ - `*::build-info` — Obtain information about the build of Tcl.
+ - `readFile`, `writeFile`, `foreachLine` — Simple procedures for basic working with files.
+ - `tcl::idna::*` — Commands for working with encoded DNS names.
+
+## New command options
+ - `chan configure ... -inputmode ...` — Support for raw terminal input and reading passwords.
+ - `clock scan ... -validate ...`
+ - `info loaded ... ?prefix?`
+ - `lsearch ... -stride ...` — Search a list by groups of items.
+ - `regsub ... -command ...` — Generate the replacement for a regular expression by calling a command.
+ - `socket ... -nodelay ... -keepalive ...`
+ - `vwait` controlled by several new options
+ - `expr` string comparators `lt`, `gt`, `le`, `ge`
+ - `expr` supports comments inside expressions
+
+## Numbers
+ - <code>0<i>NNN</i></code> format is no longer octal interpretation. Use <code>0o<i>NNN</i></code>.
+ - <code>0d<i>NNNN</i></code> format to compel decimal interpretation.
+ - <code>NN_NNN_NNN</code>, underscores in numbers for optional readability
+ - Functions: `isinf()`, `isnan()`, `isnormal()`, `issubnormal()`, `isunordered()`
+ - Command: `fpclassify`
+ - Function `int()` no longer truncates to word size
+
+## TclOO facilities
+ - private variables and methods
+ - class variables and methods
+ - abstract and singleton classes
+ - configurable properties
+ - `method -export`, `method -unexport`
+
+# Known bugs
+ - [changed behaviour wrt command names, namespaces and resolution](https://core.tcl-lang.org/tcl/tktview/f14b33)
+ - [windows dos device paths inconsistencies and missing functionality](https://core.tcl-lang.org/tcl/tktview/d8f121)
+ - [load library (dll) from zipfs-library causes a leak in temporary folder](https://core.tcl-lang.org/tcl/tktview/a8e4f7)
+ - [lsearch -sorted -inline -subindices incorrect result](https://core.tcl-lang.org/tcl/tktview/bc4ac0)
+ - ["No error" when load fails due to a missing secondary DLL](https://core.tcl-lang.org/tcl/tktview/bc4ac0)
+
@@ -1,21 +0,0 @@
-/*
- * dirent.h --
- *
- *	This file is a replacement for <dirent.h> in systems that
- *	support the old BSD-style <sys/dir.h> with a "struct direct".
- *
- * Copyright (c) 1991 The Regents of the University of California.
- * Copyright (c) 1994 Sun Microsystems, Inc.
- *
- * See the file "license.terms" for information on usage and redistribution
- * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
- */
-
-#ifndef _DIRENT
-#define _DIRENT
-
-#include <sys/dir.h>
-
-#define dirent direct
-
-#endif /* _DIRENT */
@@ -1,53 +0,0 @@
-/*
- * dirent.h --
- *
- *	Declarations of a library of directory-reading procedures
- *	in the POSIX style ("struct dirent").
- *
- * Copyright (c) 1991 The Regents of the University of California.
- * Copyright (c) 1994 Sun Microsystems, Inc.
- *
- * See the file "license.terms" for information on usage and redistribution
- * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
- */
-
-#ifndef _DIRENT
-#define _DIRENT
-
-/*
- * Dirent structure, which holds information about a single
- * directory entry.
- */
-
-#define MAXNAMLEN 255
-#define DIRBLKSIZ 512
-
-struct dirent {
-    long d_ino;			/* Inode number of entry */
-    short d_reclen;		/* Length of this record */
-    short d_namlen;		/* Length of string in d_name */
-    char d_name[MAXNAMLEN + 1];	/* Name must be no longer than this */
-};
-
-/*
- * State that keeps track of the reading of a directory (clients
- * should never look inside this structure;  the fields should
- * only be accessed by the library procedures).
- */
-
-typedef struct _dirdesc {
-    int dd_fd;
-    long dd_loc;
-    long dd_size;
-    char dd_buf[DIRBLKSIZ];
-} DIR;
-
-/*
- * Procedures defined for reading directories:
- */
-
-extern void		closedir (DIR *dirp);
-extern DIR *		opendir (char *name);
-extern struct dirent *	readdir (DIR *dirp);
-
-#endif /* _DIRENT */
@@ -43,36 +43,37 @@ TCL_DECLARE_MUTEX(netdbMutex)
 static size_t
 strlcpy(char *dst, const char *src, size_t siz)
 {
-        char *d = dst;
-        const char *s = src;
-        size_t n = siz;
+	char *d = dst;
+	const char *s = src;
+	size_t n = siz;

-        /* Copy as many bytes as will fit */
-        if (n != 0 && --n != 0) {
-                do {
-                        if ((*d++ = *s++) == 0)
-                                break;
-                } while (--n != 0);
-        }
+	/* Copy as many bytes as will fit */
+	if (n != 0 && --n != 0) {
+		do {
+			if ((*d++ = *s++) == 0)
+				break;
+		} while (--n != 0);
+	}

-        /* Not enough room in dst, add NUL and traverse rest of src */
-        if (n == 0) {
-                if (siz != 0)
-                        *d = '\0';              /* NUL-terminate dst */
-                while (*s++)
-                        ;
-        }
+	/* Not enough room in dst, add NUL and traverse rest of src */
+	if (n == 0) {
+		if (siz != 0)
+			*d = '\0';	      /* NUL-terminate dst */
+		while (*s++)
+			;
+	}

-        return(s - src - 1);    /* count does not include NUL */
+	return(s - src - 1);    /* count does not include NUL */
 }
 #endif

 int fake_getnameinfo(const struct sockaddr *sa, size_t salen, char *host,
-                size_t hostlen, char *serv, size_t servlen, int flags)
+	size_t hostlen, char *serv, size_t servlen, int flags)
 {
 	struct sockaddr_in *sin = (struct sockaddr_in *)sa;
 	struct hostent *hp;
 	char tmpserv[16];
+	(void)salen;

 	if (sa->sa_family != AF_UNSPEC && sa->sa_family != AF_INET)
 		return (EAI_FAMILY);
@@ -153,7 +154,7 @@ addrinfo *malloc_ai(int port, u_long addr, const struct addrinfo *hints)
 {
 	struct addrinfo *ai;

-	ai = malloc(sizeof(*ai) + sizeof(struct sockaddr_in));
+	ai = (struct addrinfo *)malloc(sizeof(*ai) + sizeof(struct sockaddr_in));
 	if (ai == NULL)
 		return (NULL);

@@ -1,14 +0,0 @@
-/*
- * float.h --
- *
- *	This is a dummy header file to #include in Tcl when there
- *	is no float.h in /usr/include.  Right now this file is empty:
- *	Tcl contains #ifdefs to deal with the lack of definitions;
- *	all it needs is for the #include statement to work.
- *
- * Copyright (c) 1993 The Regents of the University of California.
- * Copyright (c) 1994 Sun Microsystems, Inc.
- *
- * See the file "license.terms" for information on usage and redistribution
- * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
- */
@@ -1,64 +0,0 @@
-/*
- * memcmp.c --
- *
- *	Source code for the "memcmp" library routine.
- *
- * Copyright (c) 1998 Sun Microsystems, Inc.
- *
- * See the file "license.terms" for information on usage and redistribution of
- * this file, and for a DISCLAIMER OF ALL WARRANTIES.
- */
-
-#include "tclPort.h"
-
-/*
- * Here is the prototype just in case it is not included in tclPort.h.
- */
-
-int		memcmp(const void *s1, const void *s2, size_t n);
-
-/*
- *----------------------------------------------------------------------
- *
- * memcmp --
- *
- *	Compares two bytes sequences.
- *
- * Results:
- *	Compares its arguments, looking at the first n bytes (each interpreted
- *	as an unsigned char), and returns an integer less than, equal to, or
- *	greater than 0, according as s1 is less than, equal to, or greater
- *	than s2 when taken to be unsigned 8 bit numbers.
- *
- * Side effects:
- *	None.
- *
- *----------------------------------------------------------------------
- */
-
-int
-memcmp(
-    const void *s1,		/* First string. */
-    const void *s2,		/* Second string. */
-    size_t n)			/* Length to compare. */
-{
-    const unsigned char *ptr1 = (const unsigned char *) s1;
-    const unsigned char *ptr2 = (const unsigned char *) s2;
-
-    for ( ; n-- ; ptr1++, ptr2++) {
-	unsigned char u1 = *ptr1, u2 = *ptr2;
-
-	if (u1 != u2) {
-	    return (u1-u2);
-	}
-    }
-    return 0;
-}
-
-/*
- * Local Variables:
- * mode: c
- * c-basic-offset: 4
- * fill-column: 78
- * End:
- */
@@ -13,6 +13,7 @@
 #include <fcntl.h>
 #include <stdlib.h>
 #include <unistd.h>
+#include <string.h>

 /*
 *----------------------------------------------------------------------
@@ -32,19 +33,19 @@

 int
 mkstemp(
-    char *template)		/* Template for filename. */
+    char *tmpl)		/* Template for filename. */
 {
    static const char alphanumerics[] =
 	"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
    char *a, *b;
    int fd, count, alphanumericsLen = strlen(alphanumerics); /* == 62 */

-    a = template + strlen(template);
-    while (a > template && *(a-1) == 'X') {
+    a = tmpl + strlen(tmpl);
+    while (a > tmpl && *(a-1) == 'X') {
 	a--;
    }

-    if (a == template) {
+    if (a == tmpl) {
 	errno = ENOENT;
 	return -1;
    }
@@ -71,7 +72,7 @@ mkstemp(
 	 * Template is now realized; try to open (with correct options).
 	 */

-	fd = open(template, O_RDWR|O_CREAT|O_EXCL, 0600);
+	fd = open(tmpl, O_RDWR|O_CREAT|O_EXCL, 0600);
    } while (fd == -1 && errno == EEXIST && --count > 0);

    return fd;
@@ -1,110 +0,0 @@
-/*
- * opendir.c --
- *
- *	This file provides dirent-style directory-reading procedures for V7
- *	Unix systems that don't have such procedures. The origin of this code
- *	is unclear, but it seems to have come originally from Larry Wall.
- */
-
-#include "tclInt.h"
-
-#undef DIRSIZ
-#define DIRSIZ(dp) \
-    ((sizeof(struct dirent) - (MAXNAMLEN+1)) + (((dp)->d_namlen+1 + 3) &~ 3))
-
-/*
- * open a directory.
- */
-
-DIR *
-opendir(
-    char *name)
-{
-    DIR *dirp;
-    int fd;
-    const char *myname;
-
-    myname = ((*name == '\0') ? "." : name);
-    if ((fd = open(myname, 0, 0)) == -1) {
-	return NULL;
-    }
-    dirp = (DIR *) attemptckalloc(sizeof(DIR));
-    if (dirp == NULL) {
-	/* unreachable? */
-	close(fd);
-	return NULL;
-    }
-    dirp->dd_fd = fd;
-    dirp->dd_loc = 0;
-    return dirp;
-}
-
-/*
- * read an old style directory entry and present it as a new one
- */
-#ifndef pyr
-#define	ODIRSIZ	14
-
-struct olddirect {
-    ino_t od_ino;
-    char od_name[ODIRSIZ];
-};
-#else	/* a Pyramid in the ATT universe */
-#define	ODIRSIZ	248
-
-struct olddirect {
-    long od_ino;
-    short od_fill1, od_fill2;
-    char od_name[ODIRSIZ];
-};
-#endif
-
-/*
- * get next entry in a directory.
- */
-
-struct dirent *
-readdir(
-    DIR *dirp)
-{
-    struct olddirect *dp;
-    static struct dirent dir;
-
-    for (;;) {
-	if (dirp->dd_loc == 0) {
-	    dirp->dd_size = read(dirp->dd_fd, dirp->dd_buf, DIRBLKSIZ);
-	    if (dirp->dd_size <= 0) {
-		return NULL;
-	    }
-	}
-	if (dirp->dd_loc >= dirp->dd_size) {
-	    dirp->dd_loc = 0;
-	    continue;
-	}
-	dp = (struct olddirect *)(dirp->dd_buf + dirp->dd_loc);
-	dirp->dd_loc += sizeof(struct olddirect);
-	if (dp->od_ino == 0) {
-	    continue;
-	}
-	dir.d_ino = dp->od_ino;
-	strncpy(dir.d_name, dp->od_name, ODIRSIZ);
-	dir.d_name[ODIRSIZ] = '\0'; /* insure null termination */
-	dir.d_namlen = strlen(dir.d_name);
-	dir.d_reclen = DIRSIZ(&dir);
-	return &dir;
-    }
-}
-
-/*
- * close a directory.
- */
-
-void
-closedir(
-    DIR *dirp)
-{
-    close(dirp->dd_fd);
-    dirp->dd_fd = -1;
-    dirp->dd_loc = 0;
-    ckfree((char *)dirp);
-}
@@ -1,39 +0,0 @@
-/*
- * stdlib.h --
- *
- *	Declares facilities exported by the "stdlib" portion of the C library.
- *	This file isn't complete in the ANSI-C sense; it only declares things
- *	that are needed by Tcl. This file is needed even on many systems with
- *	their own stdlib.h (e.g. SunOS) because not all stdlib.h files declare
- *	all the procedures needed here (such as strtol/strtoul).
- *
- * Copyright (c) 1991 The Regents of the University of California.
- * Copyright (c) 1994-1998 Sun Microsystems, Inc.
- *
- * See the file "license.terms" for information on usage and redistribution of
- * this file, and for a DISCLAIMER OF ALL WARRANTIES.
- */
-
-#ifndef _STDLIB
-#define _STDLIB
-
-extern void		abort(void);
-extern double		atof(const char *string);
-extern int		atoi(const char *string);
-extern long		atol(const char *string);
-extern void *		calloc(unsigned long numElements, unsigned long size);
-extern void		exit(int status);
-extern void		free(void *blockPtr);
-extern char *		getenv(const char *name);
-extern void *		malloc(unsigned long numBytes);
-extern void		qsort(void *base, unsigned long n, unsigned long size, int (*compar)(
-			    const void *element1, const void *element2));
-extern void *		realloc(void *ptr, unsigned long numBytes);
-extern char *		realpath(const char *path, char *resolved_path);
-extern int		mkstemps(char *templ, int suffixlen);
-extern int		mkstemp(char *templ);
-extern char *		mkdtemp(char *templ);
-extern long		strtol(const char *string, char **endPtr, int base);
-extern unsigned long	strtoul(const char *string, char **endPtr, int base);
-
-#endif /* _STDLIB */
@@ -1,57 +0,0 @@
-/*
- * string.h --
- *
- *	Declarations of ANSI C library procedures for string handling.
- *
- * Copyright (c) 1991-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.
- */
-
-#ifndef _STRING
-#define _STRING
-
-/*
- * The following #include is needed to define size_t. (This used to include
- * sys/stdtypes.h but that doesn't exist on older versions of SunOS, e.g.
- * 4.0.2, so I'm trying sys/types.h now.... hopefully it exists everywhere)
- */
-
-#include <sys/types.h>
-
-#ifdef __APPLE__
-extern void *		memchr(const void *s, int c, size_t n);
-#else
-extern char *		memchr(const void *s, int c, size_t n);
-#endif
-extern int		memcmp(const void *s1, const void *s2, size_t n);
-extern char *		memcpy(void *t, const void *f, size_t n);
-#ifdef NO_MEMMOVE
-#define memmove(d,s,n)	(bcopy((s), (d), (n)))
-#else
-extern char *		memmove(void *t, const void *f, size_t n);
-#endif
-extern char *		memset(void *s, int c, size_t n);
-
-extern int		strcasecmp(const char *s1, const char *s2);
-extern char *		strcat(char *dst, const char *src);
-extern char *		strchr(const char *string, int c);
-extern int		strcmp(const char *s1, const char *s2);
-extern char *		strcpy(char *dst, const char *src);
-extern size_t		strcspn(const char *string, const char *chars);
-extern char *		strdup(const char *string);
-extern char *		strerror(int error);
-extern size_t		strlen(const char *string);
-extern int		strncasecmp(const char *s1, const char *s2, size_t n);
-extern char *		strncat(char *dst, const char *src, size_t numChars);
-extern int		strncmp(const char *s1, const char *s2, size_t nChars);
-extern char *		strncpy(char *dst, const char *src, size_t numChars);
-extern char *		strpbrk(const char *string, const char *chars);
-extern char *		strrchr(const char *string, int c);
-extern size_t		strspn(const char *string, const char *chars);
-extern char *		strstr(const char *string, const char *substring);
-extern char *		strtok(char *s, const char *delim);
-
-#endif /* _STRING */
@@ -1,70 +0,0 @@
-/*
- * strstr.c --
- *
- *	Source code for the "strstr" library routine.
- *
- * Copyright (c) 1988-1993 The Regents of the University of California.
- * Copyright (c) 1994 Sun Microsystems, Inc.
- *
- * See the file "license.terms" for information on usage and redistribution of
- * this file, and for a DISCLAIMER OF ALL WARRANTIES.
- */
-
-#include "tcl.h"
-#ifndef NULL
-#define NULL 0
-#endif
-
-/*
- *----------------------------------------------------------------------
- *
- * strstr --
- *
- *	Locate the first instance of a substring in a string.
- *
- * Results:
- *	If string contains substring, the return value is the location of the
- *	first matching instance of substring in string. If string doesn't
- *	contain substring, the return value is 0. Matching is done on an exact
- *	character-for-character basis with no wildcards or special characters.
- *
- * Side effects:
- *	None.
- *
- *----------------------------------------------------------------------
- */
-
-char *
-strstr(
-    const char *string,		/* String to search. */
-    const char *substring)		/* Substring to try to find in string. */
-{
-    const char *a, *b;
-
-    /*
-     * First scan quickly through the two strings looking for a
-     * single-character match. When it's found, then compare the rest of the
-     * substring.
-     */
-
-    b = substring;
-    if (*b == 0) {
-	return (char *)string;
-    }
-    for ( ; *string != 0; string += 1) {
-	if (*string != *b) {
-	    continue;
-	}
-	a = string;
-	while (1) {
-	    if (*b == 0) {
-		return (char *)string;
-	    }
-	    if (*a++ != *b++) {
-		break;
-	    }
-	}
-	b = substring;
-    }
-    return NULL;
-}
@@ -1,77 +0,0 @@
-/*
- * strtol.c --
- *
- *	Source code for the "strtol" library procedure.
- *
- * Copyright (c) 1988 The Regents of the University of California.
- * Copyright (c) 1994 Sun Microsystems, Inc.
- *
- * See the file "license.terms" for information on usage and redistribution of
- * this file, and for a DISCLAIMER OF ALL WARRANTIES.
- */
-
-#include "tclInt.h"
-
-/*
- *----------------------------------------------------------------------
- *
- * strtol --
- *
- *	Convert an ASCII string into an integer.
- *
- * Results:
- *	The return value is the integer equivalent of string. If endPtr is
- *	non-NULL, then *endPtr is filled in with the character after the last
- *	one that was part of the integer. If string doesn't contain a valid
- *	integer value, then zero is returned and *endPtr is set to string.
- *
- * Side effects:
- *	None.
- *
- *----------------------------------------------------------------------
- */
-
-long int
-strtol(
-    const char *string,		/* String of ASCII digits, possibly preceded
-				 * by white space. For bases greater than 10,
-				 * either lower- or upper-case digits may be
-				 * used. */
-    char **endPtr,		/* Where to store address of terminating
-				 * character, or NULL. */
-    int base)			/* Base for conversion. Must be less than 37.
-				 * If 0, then the base is chosen from the
-				 * leading characters of string: "0x" means
-				 * hex, "0" means octal, anything else means
-				 * decimal. */
-{
-    const char *p;
-    long result;
-
-    /*
-     * Skip any leading blanks.
-     */
-
-    p = string;
-    while (isspace(UCHAR(*p))) {
-	p += 1;
-    }
-
-    /*
-     * Check for a sign.
-     */
-
-    if (*p == '-') {
-	p += 1;
-	result = -(strtoul(p, endPtr, base));
-    } else {
-	if (*p == '+') {
-	    p += 1;
-	}
-	result = strtoul(p, endPtr, base);
-    }
-    if ((result == 0) && (endPtr != 0) && (*endPtr == p)) {
-	*endPtr = (char *) string;
-    }
-    return result;
-}
@@ -1,214 +0,0 @@
-/*
- * strtoul.c --
- *
- *	Source code for the "strtoul" library procedure.
- *
- * Copyright (c) 1988 The Regents of the University of California.
- * Copyright (c) 1994 Sun Microsystems, Inc.
- *
- * See the file "license.terms" for information on usage and redistribution of
- * this file, and for a DISCLAIMER OF ALL WARRANTIES.
- */
-
-#include "tclInt.h"
-
-/*
- * The table below is used to convert from ASCII digits to a numerical
- * equivalent. It maps from '0' through 'z' to integers (100 for non-digit
- * characters).
- */
-
-static const char cvtIn[] = {
-    0, 1, 2, 3, 4, 5, 6, 7, 8, 9,		/* '0' - '9' */
-    100, 100, 100, 100, 100, 100, 100,		/* punctuation */
-    10, 11, 12, 13, 14, 15, 16, 17, 18, 19,	/* 'A' - 'Z' */
-    20, 21, 22, 23, 24, 25, 26, 27, 28, 29,
-    30, 31, 32, 33, 34, 35,
-    100, 100, 100, 100, 100, 100,		/* punctuation */
-    10, 11, 12, 13, 14, 15, 16, 17, 18, 19,	/* 'a' - 'z' */
-    20, 21, 22, 23, 24, 25, 26, 27, 28, 29,
-    30, 31, 32, 33, 34, 35};
-
-/*
- *----------------------------------------------------------------------
- *
- * strtoul --
- *
- *	Convert an ASCII string into an integer.
- *
- * Results:
- *	The return value is the integer equivalent of string. If endPtr is
- *	non-NULL, then *endPtr is filled in with the character after the last
- *	one that was part of the integer. If string doesn't contain a valid
- *	integer value, then zero is returned and *endPtr is set to string.
- *
- * Side effects:
- *	None.
- *
- *----------------------------------------------------------------------
- */
-
-unsigned long int
-strtoul(
-    const char *string,		/* String of ASCII digits, possibly preceded
-				 * by white space. For bases greater than 10,
-				 * either lower- or upper-case digits may be
-				 * used. */
-    char **endPtr,		/* Where to store address of terminating
-				 * character, or NULL. */
-    int base)			/* Base for conversion.  Must be less than 37.
-				 * If 0, then the base is chosen from the
-				 * leading characters of string: "0x" means
-				 * hex, "0" means octal, anything else means
-				 * decimal. */
-{
-    const char *p;
-    unsigned long int result = 0;
-    unsigned digit;
-    int anyDigits = 0;
-    int negative=0;
-    int overflow=0;
-
-    /*
-     * Skip any leading blanks.
-     */
-
-    p = string;
-    while (isspace(UCHAR(*p))) {
-	p += 1;
-    }
-    if (*p == '-') {
-        negative = 1;
-        p += 1;
-    } else {
-        if (*p == '+') {
-            p += 1;
-        }
-    }
-
-    /*
-     * If no base was provided, pick one from the leading characters of the
-     * string.
-     */
-
-    if (base == 0) {
-	if (*p == '0') {
-	    p += 1;
-	    if ((*p == 'x') || (*p == 'X')) {
-		p += 1;
-		base = 16;
-	    } else {
-		/*
-		 * Must set anyDigits here, otherwise "0" produces a "no
-		 * digits" error.
-		 */
-
-		anyDigits = 1;
-		base = 8;
-	    }
-	} else {
-	    base = 10;
-	}
-    } else if (base == 16) {
-	/*
-	 * Skip a leading "0x" from hex numbers.
-	 */
-
-	if ((p[0] == '0') && ((p[1] == 'x') || (p[1] == 'X'))) {
-	    p += 2;
-	}
-    }
-
-    /*
-     * Sorry this code is so messy, but speed seems important. Do different
-     * things for base 8, 10, 16, and other.
-     */
-
-    if (base == 8) {
-	unsigned long maxres = ULONG_MAX >> 3;
-
-	for ( ; ; p += 1) {
-	    digit = *p - '0';
-	    if (digit > 7) {
-		break;
-	    }
-	    if (result > maxres) { overflow = 1; }
-	    result = (result << 3);
-	    if (digit > (ULONG_MAX - result)) { overflow = 1; }
-	    result += digit;
-	    anyDigits = 1;
-	}
-    } else if (base == 10) {
-	unsigned long maxres = ULONG_MAX / 10;
-
-	for ( ; ; p += 1) {
-	    digit = *p - '0';
-	    if (digit > 9) {
-		break;
-	    }
-	    if (result > maxres) { overflow = 1; }
-	    result *= 10;
-	    if (digit > (ULONG_MAX - result)) { overflow = 1; }
-	    result += digit;
-	    anyDigits = 1;
-	}
-    } else if (base == 16) {
-	unsigned long maxres = ULONG_MAX >> 4;
-
-	for ( ; ; p += 1) {
-	    digit = *p - '0';
-	    if (digit > ('z' - '0')) {
-		break;
-	    }
-	    digit = cvtIn[digit];
-	    if (digit > 15) {
-		break;
-	    }
-	    if (result > maxres) { overflow = 1; }
-	    result = (result << 4);
-	    if (digit > (ULONG_MAX - result)) { overflow = 1; }
-	    result += digit;
-	    anyDigits = 1;
-	}
-    } else if (base >= 2 && base <= 36) {
-	unsigned long maxres = ULONG_MAX / base;
-
-	for ( ; ; p += 1) {
-	    digit = *p - '0';
-	    if (digit > ('z' - '0')) {
-		break;
-	    }
-	    digit = cvtIn[digit];
-	    if (digit >= ( (unsigned) base )) {
-		break;
-	    }
-	    if (result > maxres) { overflow = 1; }
-	    result *= base;
-	    if (digit > (ULONG_MAX - result)) { overflow = 1; }
-	    result += digit;
-	    anyDigits = 1;
-	}
-    }
-
-    /*
-     * See if there were any digits at all.
-     */
-
-    if (!anyDigits) {
-	p = string;
-    }
-
-    if (endPtr != 0) {
-	/* unsafe, but required by the strtoul prototype */
-	*endPtr = (char *) p;
-    }
-
-    if (overflow) {
-	errno = ERANGE;
-	return ULONG_MAX;
-    }
-    if (negative) {
-	return -result;
-    }
-    return result;
-}
@@ -1,76 +0,0 @@
-/*
- * unistd.h --
- *
- *      Macros, constants and prototypes for Posix conformance.
- *
- * Copyright 1989 Regents of the University of California Permission to use,
- * copy, modify, and distribute this software and its documentation for any
- * purpose and without fee is hereby granted, provided that the above
- * copyright notice appear in all copies. The University of California makes
- * no representations about the suitability of this software for any purpose.
- * It is provided "as is" without express or implied warranty.
- */
-
-#ifndef _UNISTD
-#define _UNISTD
-
-#include <sys/types.h>
-
-#ifndef NULL
-#   define NULL    0
-#endif
-
-/*
- * Strict POSIX stuff goes here. Extensions go down below, in the ifndef
- * _POSIX_SOURCE section.
- */
-
-extern void		_exit(int status);
-extern int		access(const char *path, int mode);
-extern int		chdir(const char *path);
-extern int		chown(const char *path, uid_t owner, gid_t group);
-extern int		close(int fd);
-extern int		dup(int oldfd);
-extern int		dup2(int oldfd, int newfd);
-extern int		execl(const char *path, ...);
-extern int		execle(const char *path, ...);
-extern int		execlp(const char *file, ...);
-extern int		execv(const char *path, char *const argv[]);
-extern int		execve(const char *path, char *const argv[], char *const *envp);
-extern int		execvp(const char *file, char *const argv[]);
-extern pid_t		fork(void);
-extern char *		getcwd(char *buf, size_t size);
-extern gid_t		getegid(void);
-extern uid_t		geteuid(void);
-extern gid_t		getgid(void);
-extern int		getgroups(int bufSize, int *buffer);
-extern pid_t		getpid(void);
-extern uid_t		getuid(void);
-extern int		isatty(int fd);
-extern long		lseek(int fd, long offset, int whence);
-extern int		pipe(int *fildes);
-extern int		read(int fd, char *buf, size_t size);
-extern int		setgid(gid_t group);
-extern int		setuid(uid_t user);
-extern unsigned		sleep(unsigned seconds);
-extern char *		ttyname(int fd);
-extern int		unlink(const char *path);
-extern int		write(int fd, const char *buf, size_t size);
-
-#ifndef	_POSIX_SOURCE
-extern char *		crypt(const char *, const char *);
-extern int		fchown(int fd, uid_t owner, gid_t group);
-extern int		flock(int fd, int operation);
-extern int		ftruncate(int fd, unsigned long length);
-extern int		ioctl(int fd, int request, ...);
-extern int		readlink(const char *path, char *buf, int bufsize);
-extern int		setegid(gid_t group);
-extern int		seteuid(uid_t user);
-extern int		setreuid(int ruid, int euid);
-extern int		symlink(const char *, const char *);
-extern int		ttyslot(void);
-extern int		truncate(const char *path, unsigned long length);
-extern int		vfork(void);
-#endif /* _POSIX_SOURCE */
-
-#endif /* _UNISTD */
@@ -100,7 +100,7 @@ waitpid(
 	} else {
 	    prevPtr->nextPtr = waitPtr->nextPtr;
 	}
-	ckfree((char *) waitPtr);
+	Tcl_Free(waitPtr);
 	return result;
    }

@@ -156,7 +156,7 @@ waitpid(
 		goto waitAgain;
 	    }
 	}
-	waitPtr = (WaitInfo *) attemptckalloc(sizeof(WaitInfo));
+	waitPtr = (WaitInfo *) Tcl_AttemptAlloc(sizeof(WaitInfo));
 	if (!waitPtr) {
 	    errno = ENOMEM;
 	    return -1;
@@ -18,6 +18,7 @@ int
 .sp
 int
 \fBTcl_Stat\fR(\fIpath\fR, \fIstatPtr\fR)
+.fi
 .SH ARGUMENTS
 .AS "struct stat" *statPtr out
 .AP "const char" *path in
@@ -32,7 +33,7 @@ The structure that contains the result.
 .BE
 .SH DESCRIPTION
 .PP
-As of Tcl 8.4, the object-based APIs \fBTcl_FSAccess\fR and \fBTcl_FSStat\fR
+The object-based APIs \fBTcl_FSAccess\fR and \fBTcl_FSStat\fR
 should be used in preference to \fBTcl_Access\fR and \fBTcl_Stat\fR, wherever
 possible. Those functions also support Tcl's virtual filesystem layer, which
 these do not.
@@ -9,11 +9,11 @@
 .so man.macros
 .BS
 .SH NAME
-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
+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
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
-.sp
+
 Tcl_Obj *
 \fBTcl_GetReturnOptions\fR(\fIinterp, code\fR)
 .sp
@@ -30,8 +30,7 @@ int
 .sp
 \fBTcl_SetErrorCode\fR(\fIinterp, element, element, ... \fB(char *)NULL\fR)
 .sp
-\fBTcl_SetErrorCodeVA\fR(\fIinterp, argList\fR)
-.sp
+int
 \fBTcl_GetErrorLine\fR(\fIinterp\fR)
 .sp
 \fBTcl_SetErrorLine\fR(\fIinterp, lineNum\fR)
@@ -39,8 +38,8 @@ int
 const char *
 \fBTcl_PosixError\fR(\fIinterp\fR)
 .sp
-void
 \fBTcl_LogCommandInfo\fR(\fIinterp, script, command, commandLength\fR)
+.fi
 .SH ARGUMENTS
 .AS Tcl_Interp commandLength
 .AP Tcl_Interp *interp in
@@ -60,7 +59,7 @@ 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 int length in
+.AP Tcl_Size length in
 The number of bytes to copy from \fImessage\fR when
 appending to the \fB\-errorinfo\fR return option.
 If negative, all bytes up to the first null byte are used.
@@ -69,17 +68,17 @@ The \fB\-errorcode\fR return option will be set to this value.
 .AP "const char" *element in
 String to record as one element of the \fB\-errorcode\fR return option.
 Last \fIelement\fR argument must be (char *)NULL.
-.AP va_list argList in
-An argument list which must have been initialized using
-\fBva_start\fR, and cleared using \fBva_end\fR.
 .AP int lineNum
 The line number of a script where an error occurred.
 .AP "const char" *script in
-Pointer to first character in script containing command (must be <= command)
+Pointer to first character in script containing command
+(must be <= \fIcommand\fR).
 .AP "const char" *command in
-Pointer to first character in command that generated the error
-.AP int commandLength in
-Number of bytes in command; -1 means use all bytes up to first null byte
+Pointer to first character in the command that generated the error; must
+point within the string given by \fIscript\fR.
+.AP Tcl_Size commandLength in
+Number of bytes in command; a negative value means use all bytes up to the
+first null byte.
 .BE
 .SH DESCRIPTION
 .PP
@@ -119,7 +118,7 @@ retrieve the stack trace when script evaluation returns
 \fBTCL_ERROR\fR, like so:
 .PP
 .CS
-int code = Tcl_Eval(interp, script);
+int code = Tcl_EvalEx(interp, script, -1, 0);
 if (code == TCL_ERROR) {
    Tcl_Obj *options = \fBTcl_GetReturnOptions\fR(interp, code);
    Tcl_Obj *key = Tcl_NewStringObj("-errorinfo", -1);
@@ -245,9 +244,6 @@ The procedure \fBTcl_SetErrorCode\fR is also used to set the
 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.
-.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
 call to \fBTcl_GetReturnOptions\fR.  Likewise, \fBTcl_SetErrorLine\fR
@@ -305,6 +301,22 @@ The global variables \fBerrorInfo\fR and
 \fBerrorCode\fR are not modified by \fBTcl_ResetResult\fR
 so they continue to hold a record of information about the
 most recent error seen in an interpreter.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+The result of \fBTcl_GetReturnOptions\fR will have at least one
+reference to it from the Tcl interpreter. If not using it immediately,
+you should use \fBTcl_IncrRefCount\fR to add your own reference.
+.PP
+The \fIoptions\fR argument to \fBTcl_SetReturnOptions\fR will have a
+reference added by the Tcl interpreter; it may safely be called with a
+zero-reference value.
+.PP
+\fBTcl_AppendObjToErrorInfo\fR only reads its \fIobjPtr\fR argument;
+it does not modify its reference count at all.
+.PP
+The \fIerrorObjPtr\fR argument to \fBTcl_SetObjErrorCode\fR will have a
+reference added by the Tcl interpreter; it may safely be called with a
+zero-reference value.
 .SH "SEE ALSO"
 Tcl_DecrRefCount(3), Tcl_IncrRefCount(3), Tcl_Interp(3), Tcl_ResetResult(3),
 Tcl_SetErrno(3), errorCode(n), errorInfo(n)
@@ -4,52 +4,36 @@
 '\" 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 7.5 Tcl "Tcl Library Procedures"
+.TH Tcl_Alloc 3 9.0 Tcl "Tcl Library Procedures"
 .so man.macros
 .BS
 .SH NAME
-Tcl_Alloc, Tcl_Free, Tcl_Realloc, Tcl_AttemptAlloc, Tcl_AttemptRealloc, Tcl_GetMemoryInfo, ckalloc, ckfree, ckrealloc, attemptckalloc, attemptckrealloc \- allocate or free heap memory
+Tcl_Alloc, Tcl_Free, Tcl_Realloc, Tcl_AttemptAlloc, Tcl_AttemptRealloc, Tcl_GetMemoryInfo \- allocate or free heap memory
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
 .sp
-char *
+void *
 \fBTcl_Alloc\fR(\fIsize\fR)
 .sp
-void
 \fBTcl_Free\fR(\fIptr\fR)
 .sp
-char *
+void *
 \fBTcl_Realloc\fR(\fIptr, size\fR)
 .sp
-char *
+void *
 \fBTcl_AttemptAlloc\fR(\fIsize\fR)
 .sp
-char *
+void *
 \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)
+.fi
 .SH ARGUMENTS
 .AS char *size
-.AP "unsigned int" size in
+.AP "size_t" size in
 Size in bytes of the memory block to allocate.
-.AP char *ptr in
+.AP void *ptr in
 Pointer to memory block to free or realloc.
 .AP Tcl_DString *dsPtr in
 Initialized DString pointer.
@@ -84,18 +68,17 @@ 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
-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.
-
+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.
+.PP
 \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.
+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.

 .SH KEYWORDS
 alloc, allocation, free, malloc, memory, realloc, TCL_MEM_DEBUG
@@ -15,6 +15,7 @@ Tcl_AllowExceptions \- allow all exceptions in next script evaluation
 \fB#include <tcl.h>\fR
 .sp
 \fBTcl_AllowExceptions\fR(\fIinterp\fR)
+.fi
 .SH ARGUMENTS
 .AS Tcl_Interp *interp
 .AP Tcl_Interp *interp in
@@ -30,8 +31,7 @@ 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, \fBTcl_VarEval\fR and
-\fBTcl_VarEvalVA\fR.
+\fBTcl_GlobalEval\fR, \fBTcl_GlobalEvalObj\fR and \fBTcl_VarEval\fR.
 .PP
 However, if \fBTcl_AllowExceptions\fR is invoked immediately before
 calling one of those a procedures, then arbitrary completion
@@ -16,6 +16,7 @@ Tcl_AppInit \- perform application-specific initialization
 .sp
 int
 \fBTcl_AppInit\fR(\fIinterp\fR)
+.fi
 .SH ARGUMENTS
 .AS Tcl_Interp *interp
 .AP Tcl_Interp *interp in
@@ -13,12 +13,13 @@ Tcl_GetAssocData, Tcl_SetAssocData, Tcl_DeleteAssocData \- manage associations o
 .nf
 \fB#include <tcl.h>\fR
 .sp
-ClientData
+void *
 \fBTcl_GetAssocData\fR(\fIinterp, key, delProcPtr\fR)
 .sp
 \fBTcl_SetAssocData\fR(\fIinterp, key, delProc, clientData\fR)
 .sp
 \fBTcl_DeleteAssocData\fR(\fIinterp, key\fR)
+.fi
 .SH ARGUMENTS
 .AS Tcl_InterpDeleteProc **delProcPtr
 .AP Tcl_Interp *interp in
@@ -31,7 +32,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 ClientData clientData in
+.AP void *clientData in
 Arbitrary one-word value associated with the given key in this
 interpreter.  This data is owned by the caller.
 .BE
@@ -64,7 +65,7 @@ the type \fBTcl_InterpDeleteProc\fR:
 .PP
 .CS
 typedef void \fBTcl_InterpDeleteProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
        Tcl_Interp *\fIinterp\fR);
 .CE
 .PP
@@ -9,7 +9,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_AsyncCreate, Tcl_AsyncMark, Tcl_AsyncInvoke, Tcl_AsyncDelete, Tcl_AsyncReady \- handle asynchronous events
+Tcl_AsyncCreate, Tcl_AsyncMark, Tcl_AsyncMarkFromSignal, Tcl_AsyncInvoke, Tcl_AsyncDelete, Tcl_AsyncReady \- handle asynchronous events
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -21,6 +21,9 @@ void
 \fBTcl_AsyncMark\fR(\fIasync\fR)
 .sp
 int
+\fBTcl_AsyncMarkFromSignal\fR(\fIasync\fR, \fIsigNumber\fR)
+.sp
+int
 \fBTcl_AsyncInvoke\fR(\fIinterp, code\fR)
 .sp
 void
@@ -28,14 +31,17 @@ void
 .sp
 int
 \fBTcl_AsyncReady\fR()
+.fi
 .SH ARGUMENTS
 .AS Tcl_AsyncHandler clientData
 .AP Tcl_AsyncProc *proc in
 Procedure to invoke to handle an asynchronous event.
-.AP ClientData clientData in
+.AP void *clientData in
 One-word value to pass to \fIproc\fR.
 .AP Tcl_AsyncHandler async in
 Token for asynchronous event handler.
+.AP int sigNumber in
+POSIX signal number, when used in a signal context.
 .AP Tcl_Interp *interp in
 Tcl interpreter in which command was being evaluated when handler was
 invoked, or NULL if handler was invoked when there was no interpreter
@@ -62,10 +68,11 @@ to a clean state, such as after the current Tcl command completes.
 .PP
 \fBTcl_AsyncCreate\fR, \fBTcl_AsyncDelete\fR, and \fBTcl_AsyncReady\fR
 are thread sensitive.  They access and/or set a thread-specific data
-structure in the event of a core built with \fI\-\-enable\-threads\fR.  The token
-created by \fBTcl_AsyncCreate\fR contains the needed thread information it
-was called from so that calling \fBTcl_AsyncMark\fR(\fItoken\fR) will only yield
-the origin thread into the asynchronous handler.
+structure in the event of a core built with \fI\-\-enable\-threads\fR.
+The token created by \fBTcl_AsyncCreate\fR contains the needed thread
+information it was called from so that calling \fBTcl_AsyncMarkFromSignal\fR
+or \fBTcl_AsyncMark\fR with this token will only yield the origin
+thread into the asynchronous handler.
 .PP
 \fBTcl_AsyncCreate\fR creates an asynchronous handler and returns
 a token for it.
@@ -74,19 +81,22 @@ any occurrences of the asynchronous event that it is intended
 to handle (it is not safe to create a handler at the time of
 an event).
 When an asynchronous event occurs the code that detects the event
-(such as a signal handler) should call \fBTcl_AsyncMark\fR with the
-token for the handler.
-\fBTcl_AsyncMark\fR will mark the handler as ready to execute, but it
-will not invoke the handler immediately.
-Tcl will call the \fIproc\fR associated with the handler later, when
-the world is in a safe state, and \fIproc\fR can then carry out
-the actions associated with the asynchronous event.
+(such as a POSIX signal handler) should call \fBTcl_AsyncMarkFromSignal\fR
+with the token for the handler and the POSIX signal number. The
+return value of this function is true, when the handler will be
+marked, false otherwise.
+For non-signal contexts, \fBTcl_AsyncMark\fR serves the same purpose.
+\fBTcl_AsyncMarkFromSignal\fR and \fBTcl_AsyncMark\fR will mark
+the handler as ready to execute, but will not invoke the handler
+immediately. Tcl will call the \fIproc\fR associated with the
+handler later, when the world is in a safe state, and \fIproc\fR
+can then carry out the actions associated with the asynchronous event.
 \fIProc\fR should have arguments and result that match the
 type \fBTcl_AsyncProc\fR:
 .PP
 .CS
 typedef int \fBTcl_AsyncProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
        Tcl_Interp *\fIinterp\fR,
        int \fIcode\fR);
 .CE
@@ -17,6 +17,7 @@ Tcl_BackgroundException, Tcl_BackgroundError \- report Tcl exception that occurr
 \fBTcl_BackgroundException\fR(\fIinterp, code\fR)
 .sp
 \fBTcl_BackgroundError\fR(\fIinterp\fR)
+.fi
 .SH ARGUMENTS
 .AS Tcl_Interp *interp
 .AP Tcl_Interp *interp in
@@ -1,47 +0,0 @@
-'\"
-'\" 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
@@ -9,7 +9,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_NewBooleanObj, Tcl_SetBooleanObj, Tcl_GetBooleanFromObj \- store/retrieve boolean value in a Tcl_Obj
+Tcl_NewBooleanObj, Tcl_SetBooleanObj, Tcl_GetBooleanFromObj, Tcl_GetBoolFromObj \- store/retrieve boolean value in a Tcl_Obj
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -20,7 +20,11 @@ Tcl_Obj *
 \fBTcl_SetBooleanObj\fR(\fIobjPtr, intValue\fR)
 .sp
 int
-\fBTcl_GetBooleanFromObj\fR(\fIinterp, objPtr, intPtr\fR)
+\fBTcl_GetBooleanFromObj\fR(\fIinterp, objPtr, boolPtr\fR)
+.sp
+int
+\fBTcl_GetBoolFromObj\fR(\fIinterp, objPtr, flags. charPtr\fR)
+.fi
 .SH ARGUMENTS
 .AS Tcl_Interp intValue in/out
 .AP int intValue in
@@ -32,9 +36,16 @@ retrieve a boolean value.
 If a boolean value cannot be retrieved,
 an error message is left in the interpreter's result value
 unless \fIinterp\fR is NULL.
-.AP int *intPtr out
+.AP "bool \&| int" *boolPtr out
 Points to place where \fBTcl_GetBooleanFromObj\fR
 stores the boolean value (0 or 1) obtained from \fIobjPtr\fR.
+.AP char *charPtr out
+Points to place where \fBTcl_GetBoolFromObj\fR
+stores the boolean value (0 or 1) obtained from \fIobjPtr\fR.
+.AP int flags in
+0 or TCL_NULL_OK. If TCL_NULL_OK
+is used, then the empty string or NULL will result in \fBTcl_GetBoolFromObj\fR
+return TCL_OK, the *charPtr filled with the value \fB'\exFF'\fR;
 .BE

 .SH DESCRIPTION
@@ -61,13 +72,13 @@ any former value stored in \fI*objPtr\fR.
 from the value stored in \fI*objPtr\fR.
 If \fIobjPtr\fR holds a string value recognized by \fBTcl_GetBoolean\fR,
 then the recognized boolean value is written at the address given
-by \fIintPtr\fR.
+by \fIboolPtr\fR.
 If \fIobjPtr\fR holds any value recognized as
 a number by Tcl, then if that value is zero a 0 is written at
-the address given by \fIintPtr\fR and if that
-value is non-zero a 1 is written at the address given by \fIintPtr\fR.
+the address given by \fIboolPtr\fR and if that
+value is non-zero a 1 is written at the address given by \fIboolPtr\fR.
 In all cases where a value is written at the address given
-by \fIintPtr\fR, \fBTcl_GetBooleanFromObj\fR returns \fBTCL_OK\fR.
+by \fIboolPtr\fR, \fBTcl_GetBooleanFromObj\fR returns \fBTCL_OK\fR.
 If the value of \fIobjPtr\fR does not meet any of the conditions
 above, then \fBTCL_ERROR\fR is returned and an error message is
 left in the interpreter's result unless \fIinterp\fR is NULL.
@@ -76,6 +87,11 @@ fields of \fI*objPtr\fR so that future calls to
 \fBTcl_GetBooleanFromObj\fR on the same \fIobjPtr\fR can be
 performed more efficiently.
 .PP
+\fBTcl_GetBoolFromObj\fR functions almost the same as
+\fBTcl_GetBooleanFromObj\fR, but it has an additional parameter
+\fBflags\fR, which can be used to specify whether the empty
+string or NULL is accepted as valid.
+.PP
 Note that the routines \fBTcl_GetBooleanFromObj\fR and
 \fBTcl_GetBoolean\fR are not functional equivalents.
 The set of values for which \fBTcl_GetBooleanFromObj\fR
@@ -88,6 +104,18 @@ will lead to a \fBTCL_OK\fR return (and the boolean value 1),
 while the same value passed to \fBTcl_GetBoolean\fR will lead to
 a \fBTCL_ERROR\fR return.

+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_NewBooleanObj\fR always returns a zero-reference object, much
+like \fBTcl_NewObj\fR.
+.PP
+\fBTcl_SetBooleanObj\fR does not modify the reference count of its
+\fIobjPtr\fR argument, but does require that the object be unshared.
+.PP
+\fBTcl_GetBooleanFromObj\fR does not modify the reference count of its
+\fIobjPtr\fR argument; it only reads. Note however that this function
+may set the interpreter result; if that is the only place that
+is holding a reference to the object, it will be deleted.
 .SH "SEE ALSO"
 Tcl_NewObj, Tcl_IsShared, Tcl_GetBoolean

@@ -4,88 +4,176 @@
 '\" 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 8.1 Tcl "Tcl Library Procedures"
+.TH Tcl_ByteArrayObj 3 9.0 Tcl "Tcl Library Procedures"
 .so man.macros
 .BS
 .SH NAME
-Tcl_NewByteArrayObj, Tcl_SetByteArrayObj, Tcl_GetByteArrayFromObj, Tcl_SetByteArrayLength \- manipulate Tcl values as a arrays of bytes
+Tcl_NewByteArrayObj, Tcl_SetByteArrayObj, Tcl_GetBytesFromObj, Tcl_GetByteArrayFromObj, Tcl_SetByteArrayLength \- manipulate a Tcl value as an array of bytes
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
 .sp
 Tcl_Obj *
-\fBTcl_NewByteArrayObj\fR(\fIbytes, length\fR)
+\fBTcl_NewByteArrayObj\fR(\fIbytes, numBytes\fR)
 .sp
-void
-\fBTcl_SetByteArrayObj\fR(\fIobjPtr, bytes, length\fR)
+\fBTcl_SetByteArrayObj\fR(\fIobjPtr, bytes, numBytes\fR)
+.sp
+.VS TIP568
+unsigned char *
+\fBTcl_GetBytesFromObj\fR(\fIinterp, objPtr, numBytesPtr\fR)
+.VE TIP568
 .sp
 unsigned char *
-\fBTcl_GetByteArrayFromObj\fR(\fIobjPtr, lengthPtr\fR)
+\fBTcl_GetByteArrayFromObj\fR(\fIobjPtr, numBytesPtr\fR)
 .sp
 unsigned char *
-\fBTcl_SetByteArrayLength\fR(\fIobjPtr, length\fR)
+\fBTcl_SetByteArrayLength\fR(\fIobjPtr, numBytes\fR)
+.fi
 .SH ARGUMENTS
-.AS "const unsigned char" *lengthPtr in/out
+.AS "const unsigned char" *numBytesPtr in/out
 .AP "const unsigned char" *bytes in
 The array of bytes used to initialize or set a byte-array value. May be NULL
-even if \fIlength\fR is non-zero.
-.AP int length in
-The length of the array of bytes.  It must be >= 0.
+even if \fInumBytes\fR is non-zero.
+.AP Tcl_Size numBytes in
+The number of bytes in the array.
 .AP Tcl_Obj *objPtr in/out
-For \fBTcl_SetByteArrayObj\fR, this points to the value to be converted to
-byte-array type.  For \fBTcl_GetByteArrayFromObj\fR and
-\fBTcl_SetByteArrayLength\fR, this points to the value from which to get
-the byte-array value; if \fIobjPtr\fR does not already point to a byte-array
-value, it will be converted to one.
-.AP int *lengthPtr out
-If non-NULL, filled with the length of the array of bytes in the value.
+For \fBTcl_SetByteArrayObj\fR, this points to an unshared value to be
+overwritten by a byte-array value.  For \fBTcl_GetBytesFromObj\fR,
+\fBTcl_GetByteArrayFromObj\fR and \fBTcl_SetByteArrayLength\fR, this points
+to the value from which to extract an array of bytes.
+.AP Tcl_Interp *interp in
+Interpreter to use for error reporting.
+.AP "Tcl_Size \&| int" *numBytesPtr out
+Points to space where the number of bytes in the array may be written.
+May be (Tcl_Size *)NULL when not used. If it points to a variable which
+type is not \fBTcl_Size\fR, a compiler warning will be generated.
+If your extensions is compiled with -DTCL_8_API, this function will return
+NULL for byte arrays larger than INT_MAX (which should
+trigger proper error-handling), otherwise expect it to crash.
 .BE
-
 .SH DESCRIPTION
 .PP
-These procedures are used to create, modify, and read Tcl byte-array values
-from C code.  Byte-array values are typically used to hold the
-results of binary IO operations or data structures created with the
-\fBbinary\fR command.  In Tcl, an array of bytes is not equivalent to a
-string.  Conceptually, a string is an array of Unicode characters, while a
-byte-array is an array of 8-bit quantities with no implicit meaning.
-Accessor functions are provided to get the string representation of a
-byte-array or to convert an arbitrary value to a byte-array.  Obtaining the
+These routines are used to create, modify, store, transfer, and retrieve
+arbitrary binary data in Tcl values.  Specifically, data that can be
+represented as a sequence of arbitrary byte values is supported.
+This includes data read from binary channels, values created by the
+\fBbinary\fR command, encrypted data, or other information representable as
+a finite byte sequence.
+.PP
+A byte is an 8-bit quantity with no inherent meaning.  When the 8 bits are
+interpreted as an integer value, the range of possible values is (0-255).
+The C type best suited to store a byte is the \fBunsigned char\fR.
+An \fBunsigned char\fR array of size \fIN\fR stores an arbitrary binary
+value of size \fIN\fR bytes.  We call this representation a byte-array.
+Here we document the routines that allow us to operate on Tcl values as
+byte-arrays.
+.PP
+All Tcl values must correspond to a string representation.
+When a byte-array value must be processed as a string, the sequence
+of \fIN\fR bytes is transformed into the corresponding sequence
+of \fIN\fR characters, where each byte value transforms to the same
+character codepoint value in the range (U+0000 - U+00FF).  Obtaining the
 string representation of a byte-array value (by calling
-\fBTcl_GetStringFromObj\fR) produces a properly formed UTF-8 sequence with a
-one-to-one mapping between the bytes in the internal representation and the
-UTF-8 characters in the string representation.
+\fBTcl_GetStringFromObj\fR) produces this string in Tcl's usual
+Modified UTF-8 encoding.
 .PP
-\fBTcl_NewByteArrayObj\fR and \fBTcl_SetByteArrayObj\fR will
-create a new value of byte-array type or modify an existing value to have a
-byte-array type.  Both of these procedures set the value's type to be
-byte-array and set the value's internal representation to a copy of the
-array of bytes given by \fIbytes\fR. \fBTcl_NewByteArrayObj\fR returns a
-pointer to a newly allocated value with a reference count of zero.
-\fBTcl_SetByteArrayObj\fR invalidates any old string representation and, if
-the value is not already a byte-array value, frees any old internal
-representation. If \fIbytes\fR is NULL then the new byte array contains
-arbitrary values.
+\fBTcl_NewByteArrayObj\fR and \fBTcl_SetByteArrayObj\fR
+create a new value or overwrite an existing unshared value, respectively,
+to hold a byte-array value of \fInumBytes\fR bytes.  When a caller
+passes a non-NULL value of \fIbytes\fR, it must point to memory from
+which \fInumBytes\fR bytes can be read.  These routines
+allocate \fInumBytes\fR bytes of memory, copy \fInumBytes\fR
+bytes from \fIbytes\fR into it, and keep the result in the internal
+representation of the new or overwritten value.
+When the caller passes a NULL value of \fIbytes\fR, the data copying
+step is skipped, and the bytes stored in the value are undefined.
+A \fIbytes\fR value of NULL is useful only when the caller will arrange
+to write known contents into the byte-array through a pointer retrieved
+by a call to one of the routines explained below.  \fBTcl_NewByteArrayObj\fR
+returns a pointer to the created value with a reference count of zero.
+\fBTcl_SetByteArrayObj\fR overwrites and invalidates any old contents
+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.
 .PP
-\fBTcl_GetByteArrayFromObj\fR converts a Tcl value to byte-array type and
-returns a pointer to the value's new internal representation as an array of
-bytes.  The length of this array is stored in \fIlengthPtr\fR if
-\fIlengthPtr\fR is non-NULL.  The storage for the array of bytes is owned by
-the value and should not be freed.  The contents of the array may be
-modified by the caller only if the value is not shared and the caller
-invalidates the string representation.
+\fBTcl_GetBytesFromObj\fR performs the opposite function of
+\fBTcl_SetByteArrayObj\fR, providing access to read a byte-array from
+a Tcl value that was previously written into it.  When \fIobjPtr\fR
+is a value previously produced by \fBTcl_NewByteArrayObj\fR or
+\fBTcl_SetByteArrayObj\fR, then \fBTcl_GetBytesFromObj\fR returns
+a pointer to the byte-array kept in the value's internal representation.
+If the caller provides a non-NULL value for \fInumBytesPtr\fR, it must
+point to memory where \fBTcl_GetBytesFromObj\fR can write the number
+of bytes in the value's internal byte-array.  With both pieces of
+information, the caller is able to retrieve any information about the
+contents of that byte-array that it seeks.  When \fIobjPtr\fR does
+not already contain an internal byte-array, \fBTcl_GetBytesFromObj\fR
+will try to create one from the value's string representation.  Any
+string value that does not include any character codepoints outside
+the range (U+0000 - U+00FF) will successfully translate to a unique
+byte-array value.  With the created byte-array, the routine returns
+as before.  For any string representation which does contain
+a forbidden character codepoint, the conversion fails, and
+\fBTcl_GetBytesFromObj\fR returns NULL to signal that failure.  On
+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_SetByteArrayLength\fR converts the Tcl value to byte-array type
-and changes the length of the value's internal representation as an
-array of bytes.  If \fIlength\fR is greater than the space currently
-allocated for the array, the array is reallocated to the new length; the
-newly allocated bytes at the end of the array have arbitrary values.  If
-\fIlength\fR is less than the space currently allocated for the array,
-the length of array is reduced to the new length.  The return value is a
-pointer to the value's new array of bytes.
+\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.
+.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
+has not been disturbed.  The pointer may be used to overwrite the byte
+contents of the internal representation, so long as the value is unshared
+and any string representation is invalidated.
+.PP
+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
+\fBTcl_Size\fR or of type \fBint\fR.  It is recommended that callers provide
+a \fBTcl_Size\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 9.0.
+.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
+become \fInumBytes\fR bytes.  This is most often useful after the
+bytes of the internal byte-array have been directly overwritten and it
+has been discovered that the required size differs from the first
+estimate used in the allocation. \fBTcl_SetByteArrayLength\fR returns
+a pointer to the resized byte-array.  Because resizing the byte-array
+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.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_NewByteArrayObj\fR always returns a zero-reference object, much
+like \fBTcl_NewObj\fR.
+.PP
+\fBTcl_SetByteArrayObj\fR and \fBTcl_SetByteArrayLength\fR do not modify the
+reference count of their \fIobjPtr\fR arguments, but do require that the
+object be unshared.
+.PP
+\fBTcl_GetBytesFromObj\fR and \fBTcl_GetByteArrayFromObj\fR do not modify
+the reference count of \fIobjPtr\fR; they only read.

 .SH "SEE ALSO"
 Tcl_GetStringFromObj, Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount

 .SH KEYWORDS
-value, binary data, byte array, utf, unicode, internationalization
+value, binary data, byte array, utf, unicode
@@ -17,13 +17,14 @@ Tcl_CallWhenDeleted, Tcl_DontCallWhenDeleted \- Arrange for callback when interp
 \fBTcl_CallWhenDeleted\fR(\fIinterp\fR, \fIproc\fR, \fIclientData\fR)
 .sp
 \fBTcl_DontCallWhenDeleted\fR(\fIinterp\fR, \fIproc\fR, \fIclientData\fR)
+.fi
 .SH ARGUMENTS
 .AS Tcl_InterpDeleteProc clientData
 .AP Tcl_Interp *interp in
 Interpreter with which to associated callback.
 .AP Tcl_InterpDeleteProc *proc in
 Procedure to call when \fIinterp\fR is deleted.
-.AP ClientData clientData in
+.AP void *clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .BE
 .SH DESCRIPTION
@@ -38,7 +39,7 @@ type \fBTcl_InterpDeleteProc\fR:
 .PP
 .CS
 typedef void \fBTcl_InterpDeleteProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
        Tcl_Interp *\fIinterp\fR);
 .CE
 .PP
@@ -60,7 +61,8 @@ If there is no deletion callback that matches \fIinterp\fR,
 .PP
 Note that if the callback is being used to delete a resource that \fImust\fR
 be released on exit, \fBTcl_CreateExitHandler\fR should be used to ensure that
-a callback is received even if the application terminates without deleting the interpreter.
+a callback is received even if the application terminates without deleting the
+interpreter.
 .SH "SEE ALSO"
 Tcl_CreateExitHandler(3), Tcl_CreateThreadExitHandler(3)
 .SH KEYWORDS
@@ -17,6 +17,7 @@ int
 .sp
 int
 \fBTcl_Canceled\fR(\fIinterp, flags\fR)
+.fi
 .SH ARGUMENTS
 .AS Tcl_Interp *interp
 .AP Tcl_Interp *interp in
@@ -30,7 +31,7 @@ OR'ed 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 ClientData clientData in
+.AP void *clientData in
 Currently reserved for future use.
 It should be set to NULL.
 .BE
@@ -67,8 +68,15 @@ other procedures.  If an error is returned and this bit is set in
 result, where it can be retrieved with \fBTcl_GetObjResult\fR or
 \fBTcl_GetStringResult\fR.  If this flag bit is not set then no error
 message is left and the interpreter's result will not be modified.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_CancelEval\fR always decrements the reference count of its
+\fIresultObjPtr\fR argument (if that is non-NULL). It is expected to
+be usually called with an object with zero reference count. If the
+object is shared with some other location (including the Tcl
+evaluation stack) it should have its reference count incremented
+before calling this function.
 .SH "SEE ALSO"
-interp(n), Tcl_Eval(3),
-TIP 285
+interp(n), Tcl_Eval(3)
 .SH KEYWORDS
 cancel, unwind
@@ -11,7 +11,6 @@
 Tcl_StackChannel, Tcl_UnstackChannel, Tcl_GetStackedChannel, Tcl_GetTopChannel \- manipulate stacked I/O channels
 .SH SYNOPSIS
 .nf
-.nf
 \fB#include <tcl.h>\fR
 .sp
 Tcl_Channel
@@ -25,14 +24,14 @@ Tcl_Channel
 .sp
 Tcl_Channel
 \fBTcl_GetTopChannel\fR(\fIchannel\fR)
-.sp
+.fi
 .SH ARGUMENTS
 .AS Tcl_ChannelType clientData
 .AP Tcl_Interp *interp in
 Interpreter for error reporting.
 .AP "const Tcl_ChannelType" *typePtr in
 The new channel I/O procedures to use for \fIchannel\fR.
-.AP ClientData clientData in
+.AP void *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,11 +48,8 @@ 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 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.
+The \fBTcl_ChannelType\fR version currently supported is
+\fBTCL_CHANNEL_VERSION_5\fR.  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
-ClientData
+void *
 \fBTcl_ObjectGetMetadata\fR(\fIobject, metaTypePtr\fR)
 .sp
 \fBTcl_ObjectSetMetadata\fR(\fIobject, metaTypePtr, metadata\fR)
 .sp
-ClientData
+void *
 \fBTcl_ClassGetMetadata\fR(\fIclass, metaTypePtr\fR)
 .sp
 \fBTcl_ClassSetMetadata\fR(\fIclass, metaTypePtr, metadata\fR)
@@ -55,8 +55,17 @@ Tcl_ObjectMapMethodNameProc
 \fBTcl_ObjectGetMethodNameMapper\fR(\fIobject\fR)
 .sp
 \fBTcl_ObjectSetMethodNameMapper\fR(\fIobject\fR, \fImethodNameMapper\fR)
+.sp
+.VS TIP605
+Tcl_Class
+\fBTcl_GetClassOfObject\fR(\fIobject\fR)
+.sp
+Tcl_Obj *
+\fBTcl_GetObjectClassName\fR(\fIinterp\fR, \fIobject\fR)
+.VE TIP605
+.fi
 .SH ARGUMENTS
-.AS ClientData metadata in/out
+.AS void *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.
@@ -73,11 +82,11 @@ automatically selected.
 The name of the namespace to create for the object's private use, or NULL if a
 new unused name is to be automatically selected. The namespace must not
 already exist.
-.AP int objc in
+.AP Tcl_Size objc in
 The number of elements in the \fIobjv\fR array.
 .AP "Tcl_Obj *const" *objv in
 The arguments to the command to create the instance of the class.
-.AP int skip in
+.AP Tcl_Size skip in
 The number of arguments at the start of the argument array, \fIobjv\fR, that
 are not arguments to any constructors. This allows the generation of correct
 error messages even when complicated calling patterns are used (e.g., via the
@@ -85,7 +94,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 ClientData metadata in
+.AP void *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
@@ -114,6 +123,13 @@ function. Note that the Tcl_Obj reference returned by \fBTcl_GetObjectName\fR
 is a shared reference. You can also get whether the object has been marked for
 deletion with \fBTcl_ObjectDeleted\fR (it returns true if deletion of the
 object has begun); this can be useful during the processing of methods.
+.VS TIP605
+The class of an object can be retrieved with \fBTcl_GetClassOfObject\fR, and
+the name of the class of an object with \fBTcl_GetObjectClassName\fR; note
+that these two \fImay\fR return NULL during deletion of an object (this is
+transient, and only occurs when the object is a long way through being
+deleted).
+.VE TIP605
 .PP
 Instances of classes are created using \fBTcl_NewObjectInstance\fR, which
 creates an object from any class (and which is internally called by both
@@ -185,7 +201,7 @@ a class or object.
 .PP
 .CS
 typedef void \fBTcl_ObjectMetadataDeleteProc\fR(
-        ClientData \fImetadata\fR);
+        void *\fImetadata\fR);
 .CE
 .PP
 The \fImetadata\fR argument gives the address of the metadata to be
@@ -198,8 +214,8 @@ associated with a class or object.
 .CS
 typedef int \fBTcl_CloneProc\fR(
        Tcl_Interp *\fIinterp\fR,
-        ClientData \fIsrcMetadata\fR,
-        ClientData *\fIdstMetadataPtr\fR);
+        void *\fIsrcMetadata\fR,
+        void **\fIdstMetadataPtr\fR);
 .CE
 .PP
 The \fIinterp\fR argument gives a place to write an error message when the
@@ -241,6 +257,29 @@ NULL if the whole chain is to be processed (the argument itself is never
 NULL); this variable may be updated by the callback. The \fImethodNameObj\fR
 parameter gives an unshared object containing the name of the method being
 invoked, as provided by the user; this object may be updated by the callback.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+The \fIobjPtr\fR argument to \fBTcl_GetObjectFromObj\fR will not have its
+reference count manipulated, but this function may modify the interpreter
+result (to report any error) so interpreter results should not be fed into
+this without an additional reference being used.
+.PP
+The result of \fBTcl_GetObjectName\fR is a value that is owned by the object
+that is regenerated when this function is first called after the object is
+renamed.  If the value is to be retained at all, the caller should increment
+the reference count.
+.PP
+The first \fIobjc\fR values in the \fIobjv\fR argument to
+\fBTcl_NewObjectInstance\fR are the arguments to pass to the constructor. They
+must have a reference count of at least 1, and may have their reference counts
+changed during the running of the constructor. Constructors may modify the
+interpreter result, which consequently means that interpreter results should
+not be used as arguments without an additional reference being taken.
+.PP
+The \fImethodNameObj\fR argument to a Tcl_ObjectMapMethodNameProc
+implementation will be a value with a reference count of at least 1 where at
+least one reference is not held by the interpreter result. It is expected that
+method name mappers will only read their \fImethodNameObj\fR arguments.
 .SH "SEE ALSO"
 Method(3), oo::class(n), oo::copy(n), oo::define(n), oo::object(n)
 .SH KEYWORDS
@@ -16,6 +16,7 @@ Tcl_CommandComplete \- Check for unmatched braces in a Tcl command
 .sp
 int
 \fBTcl_CommandComplete\fR(\fIcmd\fR)
+.fi
 .SH ARGUMENTS
 .AS "const char" *cmd
 .AP "const char" *cmd in
@@ -16,9 +16,10 @@ Tcl_Concat \- concatenate a collection of strings
 .sp
 const char *
 \fBTcl_Concat\fR(\fIargc, argv\fR)
+.fi
 .SH ARGUMENTS
 .AS "const char *const" argv[]
-.AP int argc in
+.AP Tcl_Size argc in
 Number of strings.
 .AP "const char *const" argv[] in
 Array of strings to concatenate.  Must have \fIargc\fR entries.
@@ -8,7 +8,7 @@
 .so man.macros
 .BS
 .SH NAME
-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
+Tcl_IsSafe, Tcl_CreateChild, Tcl_GetChild, Tcl_GetParent, Tcl_GetInterpPath, Tcl_CreateAlias, Tcl_CreateAliasObj, Tcl_GetAliasObj, Tcl_ExposeCommand, Tcl_HideCommand \- manage multiple Tcl interpreters, aliases and hidden commands
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -16,32 +16,14 @@ Tcl_IsSafe, Tcl_MakeSafe, Tcl_CreateChild, Tcl_CreateSlave, Tcl_GetChild, Tcl_Ge
 int
 \fBTcl_IsSafe\fR(\fIinterp\fR)
 .sp
-int
-\fBTcl_MakeSafe\fR(\fIinterp\fR)
-.sp
-.VS "TIP 581"
 Tcl_Interp *
 \fBTcl_CreateChild\fR(\fIinterp, name, isSafe\fR)
-.VE "TIP 581"
 .sp
 Tcl_Interp *
-\fBTcl_CreateSlave\fR(\fIinterp, name, isSafe\fR)
-.sp
-.VS "TIP 581"
-Tcl_Interp *
 \fBTcl_GetChild\fR(\fIinterp, name\fR)
-.VE "TIP 581"
 .sp
 Tcl_Interp *
-\fBTcl_GetSlave\fR(\fIinterp, name\fR)
-.sp
-.VS "TIP 581"
-Tcl_Interp *
 \fBTcl_GetParent\fR(\fIinterp\fR)
-.VE "TIP 581"
-.sp
-Tcl_Interp *
-\fBTcl_GetMaster\fR(\fIinterp\fR)
 .sp
 int
 \fBTcl_GetInterpPath\fR(\fIinterp, childInterp\fR)
@@ -55,10 +37,6 @@ int
                   objc, objv\fR)
 .sp
 int
-\fBTcl_GetAlias\fR(\fIinterp, childCmd, targetInterpPtr, targetCmdPtr,
-             argcPtr, argvPtr\fR)
-.sp
-int
 \fBTcl_GetAliasObj\fR(\fIinterp, childCmd, targetInterpPtr, targetCmdPtr,
                objcPtr, objvPtr\fR)
 .sp
@@ -67,6 +45,7 @@ int
 .sp
 int
 \fBTcl_HideCommand\fR(\fIinterp, cmdName, hiddenCmdName\fR)
+.fi
 .SH ARGUMENTS
 .AS "const char *const" **targetInterpPtr out
 .AP Tcl_Interp *interp in
@@ -87,12 +66,12 @@ Name of source command for alias.
 Interpreter that contains the target command for an alias.
 .AP "const char" *targetCmd in
 Name of target command for alias in \fItargetInterp\fR.
-.AP int argc in
+.AP Tcl_Size argc in
 Count of additional arguments to pass to the alias command.
 .AP "const char *const" *argv in
 Vector of strings, the additional arguments to pass to the alias command.
 This storage is owned by the caller.
-.AP int objc in
+.AP Tcl_Size objc in
 Count of additional value arguments to pass to the aliased command.
 .AP Tcl_Obj **objv in
 Vector of Tcl_Obj structures, the additional value arguments to pass to
@@ -104,16 +83,13 @@ command is defined for an alias.
 .AP "const char" **targetCmdPtr out
 Pointer to location to store the address of the name of the target command
 for an alias.
-.AP int *argcPtr out
-Pointer to location to store count of additional arguments to be passed to
-the alias. The location is in storage owned by the caller.
-.AP "const char" ***argvPtr out
-Pointer to location to store a vector of strings, the additional arguments
-to pass to an alias. The location is in storage owned by the caller, the
-vector of strings is owned by the called function.
-.AP int *objcPtr out
+.AP "Tcl_Size \&| int" *objcPtr out
 Pointer to location to store count of additional value arguments to be
 passed to the alias. The location is in storage owned by the caller.
+If it points to a variable which type is not \fBTcl_Size\fR, a compiler
+warning will be generated. If your extensions is compiled with -DTCL_8_API,
+this function will return TCL_ERROR for aliases with more than INT_MAX
+value arguments, otherwise expect it to crash
 .AP Tcl_Obj ***objvPtr out
 Pointer to location to store a vector of Tcl_Obj structures, the additional
 arguments to pass to an alias command. The location is in storage
@@ -136,8 +112,8 @@ interpreter. The return value for those procedures that return an \fBint\fR
 is either \fBTCL_OK\fR or \fBTCL_ERROR\fR. If \fBTCL_ERROR\fR is returned
 then the interpreter's result contains an error message.
 .PP
-\fBTcl_CreateSlave\fR creates a new interpreter as a child of \fIinterp\fR.
-It also creates a child command named \fIchildName\fR in \fIinterp\fR which
+\fBTcl_CreateChild\fR creates a new interpreter as a child of \fIinterp\fR.
+It also creates a child command named \fIname\fR in \fIinterp\fR which
 allows \fIinterp\fR to manipulate the new child.
 If \fIisSafe\fR is zero, the command creates a trusted child in which Tcl
 code has access to all the Tcl commands.
@@ -148,43 +124,19 @@ child in which Tcl code has access only to set of Tcl commands defined as
 see the manual entry for the Tcl \fBinterp\fR command for details.
 If the creation of the new child interpreter failed, \fBNULL\fR is returned.
 .PP
-.VS "TIP 581"
-\fBTcl_CreateChild\fR is a synonym for \fBTcl_CreateSlave\fR.
-.VE "TIP 581"
-.PP
 \fBTcl_IsSafe\fR returns \fB1\fR if \fIinterp\fR is
 .QW safe
 (was created with the \fBTCL_SAFE_INTERPRETER\fR flag specified),
 \fB0\fR otherwise.
 .PP
-\fBTcl_MakeSafe\fR marks \fIinterp\fR as
-.QW safe ,
-so that future
-calls to \fBTcl_IsSafe\fR will return 1.  It also removes all known
-potentially-unsafe core functionality (both commands and variables)
-from \fIinterp\fR.  However, it cannot know what parts of an extension
-or application are safe and does not make any attempt to remove those
-parts, so safety is not guaranteed after calling \fBTcl_MakeSafe\fR.
-Callers will want to take care with their use of \fBTcl_MakeSafe\fR
-to avoid false claims of safety.  For many situations, \fBTcl_CreateSlave\fR
-may be a better choice, since it creates interpreters in a known-safe state.
-.PP
-\fBTcl_GetSlave\fR returns a pointer to a child interpreter of
-\fIinterp\fR. The child interpreter is identified by \fIchildName\fR.
+\fBTcl_GetChild\fR returns a pointer to a child interpreter of
+\fIinterp\fR. The child interpreter is identified by \fIname\fR.
 If no such child interpreter exists, \fBNULL\fR is returned.
 .PP
-.VS "TIP 581"
-\fBTcl_GetChild\fR is a synonym for \fBTcl_GetSlave\fR.
-.VE "TIP 581"
-.PP
-\fBTcl_GetMaster\fR returns a pointer to the master interpreter of
-\fIinterp\fR. If \fIinterp\fR has no master (it is a
+\fBTcl_GetParent\fR returns a pointer to the parent interpreter of
+\fIinterp\fR. If \fIinterp\fR has no parent (it is a
 top-level interpreter) then \fBNULL\fR is returned.
 .PP
-.VS "TIP 581"
-\fBTcl_GetParent\fR is a synonym for \fBTcl_GetMaster\fR.
-.VE "TIP 581"
-.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
@@ -201,7 +153,7 @@ This operation returns \fBTCL_OK\fR if it succeeds, or \fBTCL_ERROR\fR if
 it fails; in that case, an error message is left in the value result
 of \fIchildInterp\fR.
 Note that there are no restrictions on the ancestry relationship (as
-created by \fBTcl_CreateSlave\fR) between \fIchildInterp\fR and
+created by \fBTcl_CreateChild\fR) between \fIchildInterp\fR and
 \fItargetInterp\fR. Any two interpreters can be used, without any
 restrictions on how they are related.
 .PP
@@ -217,10 +169,6 @@ non\-\fBNULL\fR, the address indicated is set to the corresponding datum.
 For example, if \fItargetCmdPtr\fR is non\-\fBNULL\fR it is set to a
 pointer to the string containing the name of the target command.
 .PP
-\fBTcl_GetAlias\fR is similar to \fBTcl_GetAliasObj\fR except that it
-returns a pointer to a vector of string instead of a vector of
-Tcl_Obj structures. \fBTcl_GetAlias\fR is deprecated.
-.PP
 \fBTcl_ExposeCommand\fR moves the command named \fIhiddenCmdName\fR from
 the set of hidden commands to the set of exposed commands, putting
 it under the name
@@ -256,8 +204,16 @@ any script evaluation mechanism will fail.
 .PP
 For a description of the Tcl interface to multiple interpreters, see
 \fIinterp(n)\fR.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_CreateAliasObj\fR increments the reference counts of the values
+in its \fIobjv\fR argument. (That reference lasts the same length of
+time as the owning alias.)
+.PP
+\fBTcl_GetAliasObj\fR returns (via its \fIobjvPtr\fR argument) a
+pointer to values that it holds a reference to.
 .SH "SEE ALSO"
-interp
+interp(n)

 .SH KEYWORDS
 alias, command, exposed commands, hidden commands, interpreter, invoke,
@@ -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_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
+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
 .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
-ClientData
+void *
 \fBTcl_GetChannelInstanceData\fR(\fIchannel\fR)
 .sp
 const Tcl_ChannelType *
@@ -35,6 +35,11 @@ Tcl_ThreadId
 int
 \fBTcl_GetChannelMode\fR(\fIchannel\fR)
 .sp
+.VS TIP220
+int
+\fBTcl_RemoveChannelMode\fR(\fIinterp, channel, mode\fR)
+.VE TIP220
+.sp
 int
 \fBTcl_GetChannelBufferSize\fR(\fIchannel\fR)
 .sp
@@ -54,13 +59,10 @@ int
 int
 \fBTcl_IsChannelExisting\fR(\fIchannelName\fR)
 .sp
-void
 \fBTcl_CutChannel\fR(\fIchannel\fR)
 .sp
-void
 \fBTcl_SpliceChannel\fR(\fIchannel\fR)
 .sp
-void
 \fBTcl_ClearChannelHandlers\fR(\fIchannel\fR)
 .sp
 int
@@ -75,9 +77,6 @@ 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
@@ -87,9 +86,6 @@ 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
@@ -116,7 +112,7 @@ Tcl_DriverFlushProc *
 .sp
 Tcl_DriverHandlerProc *
 \fBTcl_ChannelHandlerProc\fR(\fItypePtr\fR)
-.sp
+.fi
 .SH ARGUMENTS
 .AS "const Tcl_ChannelType" *channelName
 .AP "const Tcl_ChannelType" *typePtr in
@@ -128,7 +124,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 ClientData instanceData in
+.AP void *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
@@ -139,10 +135,10 @@ 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 ClientData *handlePtr out
+.AP void **handlePtr out
 Points to the location where the desired OS-specific handle should be
 stored.
-.AP int size in
+.AP Tcl_Size size in
 The size, in bytes, of buffers to allocate in this channel.
 .AP int mask in
 An OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR
@@ -243,6 +239,16 @@ events to the correct event queue even for a multi-threaded core.
 and \fBTCL_WRITABLE\fR, indicating whether the channel is open for input
 and output.
 .PP
+.VS TIP220
+.PP
+\fBTcl_RemoveChannelMode\fR removes an access privilege from the
+channel, either \fBTCL_READABLE\fR or \fBTCL_WRITABLE\fR, and returns
+a regular Tcl result code, \fBTCL_OK\fR, or \fBTCL_ERROR\fR. The
+function throws an error if either an invalid mode is specified or the
+result of the removal would be an inaccessible channel. In that case
+an error message is left in the interp argument, if not NULL.
+.VE TIP220
+.PP
 \fBTcl_GetChannelBufferSize\fR returns the size, in bytes, of buffers
 allocated to store input or output in \fIchannel\fR. If the value was not set
 by a previous call to \fBTcl_SetChannelBufferSize\fR, described below, then
@@ -287,16 +293,13 @@ 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 the \fBTcl_ChannelType\fR version is
-\fBTCL_CHANNEL_VERSION_4\fR (or higher), and
+Also notifies the driver if
 \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 the \fBTcl_ChannelType\fR version is
-\fBTCL_CHANNEL_VERSION_4\fR (or higher), and
-\fBTcl_DriverThreadActionProc\fR is defined for it.
+Also notifies the driver if \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
@@ -313,13 +316,13 @@ details about the old structure.
 The \fBTcl_ChannelType\fR structure contains the following fields:
 .PP
 .CS
-typedef struct Tcl_ChannelType {
+typedef struct {
        const char *\fItypeName\fR;
        Tcl_ChannelTypeVersion \fIversion\fR;
-        Tcl_DriverCloseProc *\fIcloseProc\fR;
+        void *\fIcloseProc\fR; /* Not used any more*/
        Tcl_DriverInputProc *\fIinputProc\fR;
        Tcl_DriverOutputProc *\fIoutputProc\fR;
-        Tcl_DriverSeekProc *\fIseekProc\fR;
+        void *\fIseekProc\fR; /* Not used any more */
        Tcl_DriverSetOptionProc *\fIsetOptionProc\fR;
        Tcl_DriverGetOptionProc *\fIgetOptionProc\fR;
        Tcl_DriverWatchProc *\fIwatchProc\fR;
@@ -348,9 +351,8 @@ 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_ChannelCloseProc\fR,
-\fBTcl_ChannelClose2Proc\fR, \fBTcl_ChannelInputProc\fR,
-\fBTcl_ChannelOutputProc\fR, \fBTcl_ChannelSeekProc\fR,
+\fBTcl_ChannelBlockModeProc\fR, \fBTcl_ChannelClose2Proc\fR,
+\fBTcl_ChannelInputProc\fR, \fBTcl_ChannelOutputProc\fR,
 \fBTcl_ChannelWideSeekProc\fR, \fBTcl_ChannelThreadActionProc\fR,
 \fBTcl_ChannelTruncateProc\fR,
 \fBTcl_ChannelSetOptionProc\fR, \fBTcl_ChannelGetOptionProc\fR,
@@ -371,27 +373,10 @@ This value can be retrieved with \fBTcl_ChannelName\fR, which returns
 a pointer to the string.
 .SS VERSION
 .PP
-
 The \fIversion\fR field should be set to the version of the structure
-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.
+that you require. \fBTCL_CHANNEL_VERSION_5\fR is the minimum supported.
 .PP
-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.
+This value can be retrieved with \fBTcl_ChannelVersion\fR.
 .SS BLOCKMODEPROC
 .PP
 The \fIblockModeProc\fR field contains the address of a function called by
@@ -400,7 +385,7 @@ the generic layer to set blocking and nonblocking mode on the device.
 .PP
 .CS
 typedef int \fBTcl_DriverBlockModeProc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
        int \fImode\fR);
 .CE
 .PP
@@ -427,22 +412,23 @@ 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 "CLOSEPROC AND CLOSE2PROC"
+.SS "CLOSE2PROC"
 .PP
-The \fIcloseProc\fR field contains the address of a function called by the
+The \fIclose2Proc\fR field contains the address of a function called by the
 generic layer to clean up driver-related information when the channel is
-closed. \fICloseProc\fR must match the following prototype:
+closed. \fIClose2Proc\fR must match the following prototype:
 .PP
 .CS
-typedef int \fBTcl_DriverCloseProc\fR(
-        ClientData \fIinstanceData\fR,
-        Tcl_Interp *\fIinterp\fR);
+typedef int \fBTcl_DriverClose2Proc\fR(
+        void *\fIinstanceData\fR,
+        Tcl_Interp *\fIinterp\fR,
+        int \fIflags\fR);
 .CE
 .PP
-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
+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
 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
@@ -451,35 +437,20 @@ 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 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
+independently may accept other flag values than 0.
+Then \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.  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.
+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.
 .PP
-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.
+The \fIclose2Proc\fR value can be retrieved with \fBTcl_ChannelClose2Proc\fR,
+which returns a pointer to the function.
 .SS INPUTPROC
 .PP
 The \fIinputProc\fR field contains the address of a function called by the
@@ -488,7 +459,7 @@ internal buffer. \fIInputProc\fR must match the following prototype:
 .PP
 .CS
 typedef int \fBTcl_DriverInputProc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
        char *\fIbuf\fR,
        int \fIbufSize\fR,
        int *\fIerrorCodePtr\fR);
@@ -532,7 +503,7 @@ generic layer to transfer data from an internal buffer to the output device.
 .PP
 .CS
 typedef int \fBTcl_DriverOutputProc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
        const char *\fIbuf\fR,
        int \fItoWrite\fR,
        int *\fIerrorCodePtr\fR);
@@ -562,17 +533,17 @@ without writing any data.
 .PP
 This value can be retrieved with \fBTcl_ChannelOutputProc\fR, which returns
 a pointer to the function.
-.SS "SEEKPROC AND WIDESEEKPROC"
+.SS "WIDESEEKPROC"
 .PP
-The \fIseekProc\fR field contains the address of a function called by the
+The \fIwideSeekProc\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. \fISeekProc\fR must match the following
+operations will be applied. \fIWideSeekProc\fR must match the following
 prototype:
 .PP
 .CS
-typedef int \fBTcl_DriverSeekProc\fR(
-        ClientData \fIinstanceData\fR,
-        long \fIoffset\fR,
+typedef long long \fBTcl_DriverWideSeekProc\fR(
+        void *\fIinstanceData\fR,
+        long long \fIoffset\fR,
        int \fIseekMode\fR,
        int *\fIerrorCodePtr\fR);
 .CE
@@ -591,30 +562,8 @@ 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
-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 Tcl_WideInt \fBTcl_DriverWideSeekProc\fR(
-        ClientData \fIinstanceData\fR,
-        Tcl_WideInt \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.
+The \fIwideSseekProc\fR value can be retrieved with
+\fBTcl_ChannelWideSeekProc\fR, which returns a pointer to the function.
 .SS SETOPTIONPROC
 .PP
 The \fIsetOptionProc\fR field contains the address of a function called by
@@ -623,7 +572,7 @@ the generic layer to set a channel type specific option on a channel.
 .PP
 .CS
 typedef int \fBTcl_DriverSetOptionProc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
        Tcl_Interp *\fIinterp\fR,
        const char *\fIoptionName\fR,
        const char *\fInewValue\fR);
@@ -664,7 +613,7 @@ channel. \fIgetOptionProc\fR must match the following prototype:
 .PP
 .CS
 typedef int \fBTcl_DriverGetOptionProc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
        Tcl_Interp *\fIinterp\fR,
        const char *\fIoptionName\fR,
        Tcl_DString *\fIoptionValue\fR);
@@ -702,7 +651,7 @@ notice events of interest on this channel.
 .PP
 .CS
 typedef void \fBTcl_DriverWatchProc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
        int \fImask\fR);
 .CE
 .PP
@@ -733,9 +682,9 @@ the generic layer to retrieve a device-specific handle from the channel.
 .PP
 .CS
 typedef int \fBTcl_DriverGetHandleProc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
        int \fIdirection\fR,
-        ClientData *\fIhandlePtr\fR);
+        void **\fIhandlePtr\fR);
 .CE
 .PP
 \fIInstanceData\fR is the same as the value passed to
@@ -762,7 +711,7 @@ It should be set to NULL.
 .PP
 .CS
 typedef int \fBTcl_DriverFlushProc\fR(
-        ClientData \fIinstanceData\fR);
+        void *\fIinstanceData\fR);
 .CE
 .PP
 This value can be retrieved with \fBTcl_ChannelFlushProc\fR, which returns
@@ -777,7 +726,7 @@ that occur on the underlying (stacked) channel.
 .PP
 .CS
 typedef int \fBTcl_DriverHandlerProc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
        int \fIinterestMask\fR);
 .CE
 .PP
@@ -806,7 +755,7 @@ might be maintaining using the calling thread as the associate. See
 .PP
 .CS
 typedef void \fBTcl_DriverThreadActionProc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
        int \fIaction\fR);
 .CE
 .PP
@@ -823,8 +772,8 @@ length. It can be NULL.
 .PP
 .CS
 typedef int \fBTcl_DriverTruncateProc\fR(
-        ClientData \fIinstanceData\fR,
-        Tcl_WideInt \fIlength\fR);
+        void *\fIinstanceData\fR,
+        long long \fIlength\fR);
 .CE
 .PP
 \fIInstanceData\fR is the same as the value passed to
@@ -871,58 +820,6 @@ 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
@@ -12,15 +12,12 @@
 Tcl_CreateChannelHandler, Tcl_DeleteChannelHandler \- call a procedure when a channel becomes readable or writable
 .SH SYNOPSIS
 .nf
-.nf
 \fB#include <tcl.h>\fR
 .sp
-void
 \fBTcl_CreateChannelHandler\fR(\fIchannel, mask, proc, clientData\fR)
 .sp
-void
 \fBTcl_DeleteChannelHandler\fR(\fIchannel, proc, clientData\fR)
-.sp
+.fi
 .SH ARGUMENTS
 .AS Tcl_ChannelProc clientData
 .AP Tcl_Channel channel in
@@ -29,10 +26,10 @@ Tcl channel such as returned by \fBTcl_CreateChannel\fR.
 Conditions under which \fIproc\fR should be called: OR-ed combination of
 \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR and \fBTCL_EXCEPTION\fR. Specify
 a zero value to temporarily disable an existing handler.
-.AP Tcl_FileProc *proc in
+.AP Tcl_ChannelProc *proc in
 Procedure to invoke whenever the channel indicated by \fIchannel\fR meets
 the conditions specified by \fImask\fR.
-.AP ClientData clientData in
+.AP void *clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .BE
 .SH DESCRIPTION
@@ -48,7 +45,7 @@ what it means for a channel to be readable or writable.
 .PP
 .CS
 typedef void \fBTcl_ChannelProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
        int \fImask\fR);
 .CE
 .PP
@@ -14,19 +14,17 @@ Tcl_CreateCloseHandler, Tcl_DeleteCloseHandler \- arrange for callbacks when cha
 .nf
 \fB#include <tcl.h>\fR
 .sp
-void
 \fBTcl_CreateCloseHandler\fR(\fIchannel, proc, clientData\fR)
 .sp
-void
 \fBTcl_DeleteCloseHandler\fR(\fIchannel, proc, clientData\fR)
-.sp
+.fi
 .SH ARGUMENTS
 .AS Tcl_CloseProc clientData
 .AP Tcl_Channel channel in
 The channel for which to create or delete a close callback.
 .AP Tcl_CloseProc *proc in
 The procedure to call as the callback.
-.AP ClientData clientData in
+.AP void *clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .BE
 .SH DESCRIPTION
@@ -38,7 +36,7 @@ Arbitrary one-word value to pass to \fIproc\fR.
 .PP
 .CS
 typedef void \fBTcl_CloseProc\fR(
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 .CE
 .PP
 The \fIclientData\fR is the same as the value provided in the call to
@@ -16,6 +16,7 @@ Tcl_CreateCommand \- implement new commands in C
 .sp
 Tcl_Command
 \fBTcl_CreateCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR)
+.fi
 .SH ARGUMENTS
 .AS Tcl_CmdDeleteProc *deleteProc
 .AP Tcl_Interp *interp in
@@ -25,7 +26,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 ClientData clientData in
+.AP void *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 +76,7 @@ and it returns NULL.
 .PP
 .CS
 typedef int \fBTcl_CmdProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
        Tcl_Interp *\fIinterp\fR,
        int \fIargc\fR,
        const char *\fIargv\fR[]);
@@ -92,18 +93,21 @@ the command name) and \fIargv\fR giving the values of the arguments
 as strings.  The \fIargv\fR array will contain \fIargc\fR+1 values;
 the first \fIargc\fR values point to the argument strings, and the
 last value is NULL.
+.PP
 Note that the argument strings should not be modified as they may
 point to constant strings or may be shared with other parts of the
 interpreter.
-.PP
-Note that the argument strings are encoded in normalized UTF-8 since
+Note also that the argument strings are encoded in normalized UTF-8 since
 version 8.1 of Tcl.
 .PP
 \fIProc\fR must return an integer code that is expected to be one of
 \fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or
-\fBTCL_CONTINUE\fR.  See the Tcl overview man page
-for details on what these codes mean.  Most normal commands will only
-return \fBTCL_OK\fR or \fBTCL_ERROR\fR.  In addition, \fIproc\fR must set
+\fBTCL_CONTINUE\fR. See the \fBreturn\fR man page for details on
+what these codes mean and the use of extended values for an extension's
+private use. Most normal commands will only return \fBTCL_OK\fR
+or \fBTCL_ERROR\fR.
+.PP
+In addition, \fIproc\fR must set
 the interpreter result;
 in the case of a \fBTCL_OK\fR return code this gives the result
 of the command, and in the case of \fBTCL_ERROR\fR it gives an error message.
@@ -131,7 +135,7 @@ result that match the type \fBTcl_CmdDeleteProc\fR:
 .PP
 .CS
 typedef void \fBTcl_CmdDeleteProc\fR(
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 .CE
 .PP
 The \fIclientData\fR argument will be the same as the \fIclientData\fR
@@ -17,6 +17,7 @@ Tcl_CreateFileHandler, Tcl_DeleteFileHandler \- associate procedure callbacks wi
 \fBTcl_CreateFileHandler\fR(\fIfd, mask, proc, clientData\fR)
 .sp
 \fBTcl_DeleteFileHandler\fR(\fIfd\fR)
+.fi
 .SH ARGUMENTS
 .AS Tcl_FileProc clientData
 .AP int fd in
@@ -29,7 +30,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 ClientData clientData in
+.AP void *clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .BE
 .SH DESCRIPTION
@@ -51,7 +52,7 @@ type \fBTcl_FileProc\fR:
 .PP
 .CS
 typedef void \fBTcl_FileProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
        int \fImask\fR);
 .CE
 .PP
@@ -22,10 +22,9 @@ Tcl_Interp *
 int
 \fBTcl_InterpDeleted\fR(\fIinterp\fR)
 .sp
-.VS 8.6
 int
 \fBTcl_InterpActive\fR(\fIinterp\fR)
-.VE 8.6
+.fi
 .SH ARGUMENTS
 .AS Tcl_Interp *interp
 .AP Tcl_Interp *interp in
@@ -70,14 +69,12 @@ deleted and when the whole interpreter is being deleted. In the former case
 the callback may recreate the data being deleted, but this would lead to an
 infinite loop if the interpreter were being deleted.
 .PP
-.VS 8.6
 \fBTcl_InterpActive\fR is useful for determining whether there is any
 execution of scripts ongoing in an interpreter, which is a useful piece of
 information when Tcl is embedded in a garbage-collected environment and it
 becomes necessary to determine whether the interpreter is a candidate for
 deletion. The function returns a true value if the interpreter has at least
 one active execution running inside it, and a false value otherwise.
-.VE 8.6
 .SH "INTERPRETERS AND MEMORY MANAGEMENT"
 .PP
 \fBTcl_DeleteInterp\fR can be called at any time on an interpreter that may
@@ -138,12 +135,10 @@ All uses of interpreters in Tcl and Tk have already been protected.
 Extension writers should ensure that their code also properly protects any
 additional interpreters used, as described above.
 .PP
-.VS 8.6
 Note that the protection mechanisms do not work well with conventional garbage
 collection systems. When in such a managed environment, \fBTcl_InterpActive\fR
 should be used to determine when an interpreter is a candidate for deletion
 due to inactivity.
-.VE 8.6
 .SH "SEE ALSO"
 Tcl_Preserve(3), Tcl_Release(3)
 .SH KEYWORDS
@@ -1,162 +0,0 @@
-'\"
-'\" 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 "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 \- implement new commands in C
+Tcl_CreateObjCommand, Tcl_CreateObjCommand2, 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
@@ -16,6 +16,9 @@ Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, Tcl_GetComm
 Tcl_Command
 \fBTcl_CreateObjCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR)
 .sp
+Tcl_Command
+\fBTcl_CreateObjCommand2\fR(\fIinterp, cmdName, proc2, clientData, deleteProc\fR)
+.sp
 int
 \fBTcl_DeleteCommand\fR(\fIinterp, cmdName\fR)
 .sp
@@ -37,11 +40,11 @@ int
 const char *
 \fBTcl_GetCommandName\fR(\fIinterp, token\fR)
 .sp
-void
 \fBTcl_GetCommandFullName\fR(\fIinterp, token, objPtr\fR)
 .sp
 Tcl_Command
 \fBTcl_GetCommandFromObj\fR(\fIinterp, objPtr\fR)
+.fi
 .SH ARGUMENTS
 .AS Tcl_CmdDeleteProc *deleteProc in/out
 .AP Tcl_Interp *interp in
@@ -51,7 +54,10 @@ 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 ClientData clientData in
+.AP Tcl_ObjCmdProc2 *proc2 in
+Implementation of the new command: \fIproc2\fR will be called whenever
+\fIcmdName\fR is invoked as a command.
+.AP void *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;
@@ -65,6 +71,9 @@ Pointer to structure containing various information about a
 Tcl command.
 .AP Tcl_Obj *objPtr in
 Value containing the name of a Tcl command.
+.AP "const char" *typeName in
+Indicates the name of the type of command implementation associated
+with a particular \fIproc\fR, or NULL to break the association.
 .BE
 .SH DESCRIPTION
 .PP
@@ -91,7 +100,7 @@ and it returns NULL.
 .PP
 .CS
 typedef int \fBTcl_ObjCmdProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
        Tcl_Interp *\fIinterp\fR,
        int \fIobjc\fR,
        Tcl_Obj *const \fIobjv\fR[]);
@@ -123,9 +132,10 @@ that \fIobjv\fR[\fB2\fR] points at, but will not change where
 .PP
 \fIproc\fR must return an integer code that is either \fBTCL_OK\fR,
 \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR.
-See the Tcl overview man page
-for details on what these codes mean.  Most normal commands will only
-return \fBTCL_OK\fR or \fBTCL_ERROR\fR.
+See the \fBreturn\fR man page for details on what these codes mean and the
+use of extended values for an extension's private use. Most normal commands
+will only return \fBTCL_OK\fR or \fBTCL_ERROR\fR.
+.PP
 In addition, if \fIproc\fR needs to return a non-empty result,
 it can call \fBTcl_SetObjResult\fR to set the interpreter's result.
 In the case of a \fBTCL_OK\fR return code this gives the result
@@ -164,12 +174,23 @@ result that match the type \fBTcl_CmdDeleteProc\fR:
 .PP
 .CS
 typedef void \fBTcl_CmdDeleteProc\fR(
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 .CE
 .PP
 The \fIclientData\fR argument will be the same as the \fIclientData\fR
 argument passed to \fBTcl_CreateObjCommand\fR.
 .PP
+\fBTcl_CreateObjCommand2\fR does the same as \fBTcl_CreateObjCommand\fR,
+except its \fIproc2\fR argument is of type \fBTcl_ObjCmdProc2\fR.
+.PP
+.CS
+typedef int \fBTcl_ObjCmdProc2\fR(
+        void *\fIclientData\fR,
+        Tcl_Interp *\fIinterp\fR,
+        Tcl_Size \fIobjc\fR,
+        Tcl_Obj *const \fIobjv\fR[]);
+.CE
+.PP
 \fBTcl_DeleteCommand\fR deletes a command from a command interpreter.
 Once the call completes, attempts to invoke \fIcmdName\fR in
 \fIinterp\fR will result in errors.
@@ -203,24 +224,29 @@ pointed to by \fIinfoPtr\fR and returns 1.
 A \fBTcl_CmdInfo\fR structure has the following fields:
 .PP
 .CS
-typedef struct Tcl_CmdInfo {
+typedef struct {
    int \fIisNativeObjectProc\fR;
    Tcl_ObjCmdProc *\fIobjProc\fR;
-    ClientData \fIobjClientData\fR;
+    void *\fIobjClientData\fR;
    Tcl_CmdProc *\fIproc\fR;
-    ClientData \fIclientData\fR;
+    void *\fIclientData\fR;
    Tcl_CmdDeleteProc *\fIdeleteProc\fR;
-    ClientData \fIdeleteData\fR;
+    void *\fIdeleteData\fR;
    Tcl_Namespace *\fInamespacePtr\fR;
+    Tcl_ObjCmdProc2 *\fIobjProc2\fR;
+    void *\fIobjClientData2\fR;
 } \fBTcl_CmdInfo\fR;
 .CE
 .PP
-The \fIisNativeObjectProc\fR field has the value 1
-if \fBTcl_CreateObjCommand\fR was called to register the command;
-it is 0 if only \fBTcl_CreateCommand\fR was called.
+The \fIisNativeObjectProc\fR field has the value 2 if
+\fBTcl_CreateObjCommand2\fR was called to register the command;
+it has the value 1 if \fBTcl_CreateObjCommand\fR was called to
+register the command; it is 0 if only \fBTcl_CreateCommand\fR was called.
 It allows a program to determine whether it is faster to
-call \fIobjProc\fR or \fIproc\fR:
-\fIobjProc\fR is normally faster
+call \fIobjProc2\fR, \fIobjProc\fR or \fIproc\fR:
+\fIobjProc2\fR/\fIobjProc\fR is normally faster
+if \fIisNativeObjectProc\fR has the value 2;
+\fIobjProc\fR/\fIobjProc\fR is normally faster
 if \fIisNativeObjectProc\fR has the value 1.
 The fields \fIobjProc\fR and \fIobjClientData\fR
 have the same meaning as the \fIproc\fR and \fIclientData\fR
@@ -236,7 +262,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.
@@ -250,7 +276,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.
@@ -266,11 +292,10 @@ 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.
-.PP
-Note that neither \fBTcl_SetCommandInfo\fR nor
+clientData for its command procedure.
+Note also that neither \fBTcl_SetCommandInfo\fR nor
 \fBTcl_SetCommandInfoFromToken\fR will change a command's namespace.
 Use \fBTcl_Eval\fR to call the \fBrename\fR command to do that.
 .PP
@@ -296,6 +321,22 @@ is appended to the value specified by \fIobjPtr\fR.
 specified by the name in a \fBTcl_Obj\fR.
 The command name is resolved relative to the current namespace.
 Returns NULL if the command is not found.
+.PP
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+When the \fIproc\fR passed to \fBTcl_CreateObjCommand\fR is called,
+the values in its \fIobjv\fR argument will have a reference count of
+at least 1, with that guaranteed reference being from the Tcl
+evaluation stack. You should not call \fBTcl_DecrRefCount\fR on any of
+those values unless you call \fBTcl_IncrRefCount\fR on them first.
+Also, when the \fIproc\fR is called, the interpreter result is
+guaranteed to be an empty string value with a reference count of 1.
+.PP
+\fBTcl_GetCommandFullName\fR does not modify the reference count of its
+\fIobjPtr\fR argument, but does require that the object be unshared.
+.PP
+\fBTcl_GetCommandFromObj\fR does not modify the reference count of its
+\fIobjPtr\fR argument; it only reads.
 .SH "SEE ALSO"
 Tcl_CreateCommand(3), Tcl_ResetResult(3), Tcl_SetObjResult(3)
 .SH KEYWORDS
@@ -18,13 +18,14 @@ Tcl_TimerToken
 \fBTcl_CreateTimerHandler\fR(\fImilliseconds, proc, clientData\fR)
 .sp
 \fBTcl_DeleteTimerHandler\fR(\fItoken\fR)
+.fi
 .SH ARGUMENTS
 .AS Tcl_TimerToken milliseconds
 .AP int milliseconds  in
 How many milliseconds to wait before invoking \fIproc\fR.
 .AP Tcl_TimerProc *proc in
 Procedure to invoke after \fImilliseconds\fR have elapsed.
-.AP ClientData clientData in
+.AP void *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 +52,7 @@ the type \fBTcl_TimerProc\fR:
 .PP
 .CS
 typedef void \fBTcl_TimerProc\fR(
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 .CE
 .PP
 The \fIclientData\fR parameter to \fIproc\fR is a
@@ -10,7 +10,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_CreateTrace, Tcl_CreateObjTrace, Tcl_DeleteTrace \- arrange for command execution to be traced
+Tcl_CreateTrace, Tcl_CreateObjTrace, Tcl_CreateObjTrace2, Tcl_DeleteTrace \- arrange for command execution to be traced
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -21,12 +21,16 @@ Tcl_Trace
 Tcl_Trace
 \fBTcl_CreateObjTrace\fR(\fIinterp, level, flags, objProc, clientData, deleteProc\fR)
 .sp
+Tcl_Trace
+\fBTcl_CreateObjTrace2\fR(\fIinterp, level, flags, objProc2, clientData, deleteProc\fR)
+.sp
 \fBTcl_DeleteTrace\fR(\fIinterp, trace\fR)
+.fi
 .SH ARGUMENTS
 .AS Tcl_CmdObjTraceDeleteProc *deleteProc
 .AP Tcl_Interp *interp in
 Interpreter containing command to be traced or untraced.
-.AP int level in
+.AP Tcl_Size level in
 Only commands at or below this nesting level will be traced unless
 0 is specified.  1 means
 top-level commands only, 2 means top-level commands or those that are
@@ -38,11 +42,14 @@ Flags governing the trace execution.  See below for details.
 .AP Tcl_CmdObjTraceProc *objProc in
 Procedure to call for each command that is executed.  See below for
 details of the calling sequence.
+.AP Tcl_CmdObjTraceProc2 *objProc2 in
+Procedure to call for each command that is executed.  See below for
+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 ClientData clientData in
-Arbitrary one-word value to pass to \fIobjProc\fR or \fIproc\fR.
+.AP void *clientData in
+Arbitrary one-word value to pass to \fIobjProc\fR, \fIobjProc2\fR or \fIproc\fR.
 .AP Tcl_CmdObjTraceDeleteProc *deleteProc in
 Procedure to call when the trace is deleted.  See below for details of
 the calling sequence.  A NULL pointer is permissible and results in no
@@ -66,7 +73,7 @@ interpreter.
 .PP
 .CS
 typedef int \fBTcl_CmdObjTraceProc\fR(
-        \fBClientData\fR \fIclientData\fR,
+        \fBvoid *\fR \fIclientData\fR,
        \fBTcl_Interp\fR* \fIinterp\fR,
        int \fIlevel\fR,
        const char *\fIcommand\fR,
@@ -75,9 +82,23 @@ typedef int \fBTcl_CmdObjTraceProc\fR(
        \fBTcl_Obj\fR *const \fIobjv\fR[]);
 .CE
 .PP
+\fIobjProc2\fR should have arguments and result that match the type,
+\fBTcl_CmdObjTraceProc2\fR:
+.PP
+.CS
+typedef int \fBTcl_CmdObjTraceProc2\fR(
+        \fBvoid *\fR \fIclientData\fR,
+        \fBTcl_Interp\fR* \fIinterp\fR,
+        Tcl_Size \fIlevel\fR,
+        const char *\fIcommand\fR,
+        \fBTcl_Command\fR \fIcommandToken\fR,
+        Tcl_Size \fIobjc\fR,
+        \fBTcl_Obj\fR *const \fIobjv\fR[]);
+.CE
+.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
@@ -140,7 +161,7 @@ When \fBTcl_DeleteTrace\fR is called, the interpreter invokes the
 .PP
 .CS
 typedef void \fBTcl_CmdObjTraceDeleteProc\fR(
-        \fBClientData\fR \fIclientData\fR);
+        \fBvoid *\fR \fIclientData\fR);
 .CE
 .PP
 The \fIclientData\fR parameter will be the same as the
@@ -156,12 +177,12 @@ match the type \fBTcl_CmdTraceProc\fR:
 .PP
 .CS
 typedef void \fBTcl_CmdTraceProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
        Tcl_Interp *\fIinterp\fR,
        int \fIlevel\fR,
        char *\fIcommand\fR,
        Tcl_CmdProc *\fIcmdProc\fR,
-        ClientData \fIcmdClientData\fR,
+        void *\fIcmdClientData\fR,
        int \fIargc\fR,
        const char *\fIargv\fR[]);
 .CE
@@ -183,5 +204,14 @@ There is no way to be notified when the trace created by
 \fBTcl_CreateTrace\fR is deleted.  There is no way for the \fIproc\fR
 associated with a call to \fBTcl_CreateTrace\fR to abort execution of
 \fIcommand\fR.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+When the \fIproc\fR passed to \fBTcl_CreateObjTrace\fR is called,
+the values in its \fIobjv\fR argument will have a reference count of
+at least 1, with that guaranteed reference being from the Tcl
+evaluation stack. You should not call \fBTcl_DecrRefCount\fR on any of
+those values unless you call \fBTcl_IncrRefCount\fR on them first.
+.SH "SEE ALSO"
+trace(n)
 .SH KEYWORDS
 command, create, delete, interpreter, trace
@@ -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_DStringTrunc, 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_DStringFree, Tcl_DStringResult, Tcl_DStringGetResult, Tcl_DStringToObj \- manipulate dynamic strings
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -26,7 +26,7 @@ char *
 .sp
 \fBTcl_DStringEndSublist\fR(\fIdsPtr\fR)
 .sp
-int
+Tcl_Size
 \fBTcl_DStringLength\fR(\fIdsPtr\fR)
 .sp
 char *
@@ -34,13 +34,16 @@ 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)
 .sp
 \fBTcl_DStringGetResult\fR(\fIinterp, dsPtr\fR)
+.sp
+Tcl_Obj *
+\fBTcl_DStringToObj\fR(\fIdsPtr\fR)
+.fi
+.sp
 .SH ARGUMENTS
 .AS Tcl_DString newLength in/out
 .AP Tcl_DString *dsPtr in/out
@@ -49,10 +52,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 int length in
-Number of bytes from \fIbytes\fR to add to dynamic string.  If -1,
+.AP Tcl_Size length in
+Number of bytes from \fIbytes\fR to add to dynamic string.  If negative,
 add all characters up to null terminating character.
-.AP int newLength in
+.AP Tcl_Size newLength in
 New length for dynamic string, not including null terminating
 character.
 .AP Tcl_Interp *interp in/out
@@ -128,10 +131,6 @@ 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.
@@ -142,12 +141,26 @@ a pointer from \fIdsPtr\fR to the interpreter's result.
 This saves the cost of allocating new memory and copying the string.
 \fBTcl_DStringResult\fR also reinitializes the dynamic string to
 an empty string.
+Since the dynamic string is reinitialized, there is no need to
+further call \fBTcl_DStringFree\fR on it and it can be reused without
+calling \fBTcl_DStringInit\fR. The caller must ensure that the dynamic
+string stored in \fIdsPtr\fR is encoded in Tcl's internal UTF-8 format.
 .PP
 \fBTcl_DStringGetResult\fR does the opposite of \fBTcl_DStringResult\fR.
 It sets the value of \fIdsPtr\fR to the result of \fIinterp\fR and
 it clears \fIinterp\fR's result.
 If possible it does this by moving a pointer rather than by copying
 the string.
+.PP
+\fBTcl_DStringToObj\fR returns a \fBTcl_Obj\fR containing the value of the
+dynamic string given by \fIdsPtr\fR. It does this by moving a pointer from
+\fIdsPtr\fR to a newly allocated \fBTcl_Obj\fR and reinitializing to dynamic
+string to an empty string. This saves the cost of allocating new memory and
+copying the string. Since the dynamic string is reinitialized, there is no need
+to further call \fBTcl_DStringFree\fR on it and it can be reused without calling
+\fBTcl_DStringInit\fR. The returned \fBTcl_Obj\fR has a reference count of 0.
+The caller must ensure that the dynamic string stored in \fIdsPtr\fR is encoded
+in Tcl's internal UTF-8 format.

 .SH KEYWORDS
 append, dynamic string, free, result
@@ -20,9 +20,10 @@ Tcl_DetachPids, Tcl_ReapDetachedProcs, Tcl_WaitPid \- manage child processes in
 .sp
 Tcl_Pid
 \fBTcl_WaitPid\fR(\fIpid, statusPtr, options\fR)
+.fi
 .SH ARGUMENTS
 .AS Tcl_Pid *statusPtr out
-.AP int numPids in
+.AP Tcl_Size numPids in
 Number of process ids contained in the array pointed to by \fIpidPtr\fR.
 .AP int *pidPtr in
 Address of array containing \fInumPids\fR process ids.
@@ -33,10 +33,8 @@ int
 \fBTcl_DictObjFirst\fR(\fIinterp, dictPtr, searchPtr,
                 keyPtrPtr, valuePtrPtr, donePtr\fR)
 .sp
-void
 \fBTcl_DictObjNext\fR(\fIsearchPtr, keyPtrPtr, valuePtrPtr, donePtr\fR)
 .sp
-void
 \fBTcl_DictObjDone\fR(\fIsearchPtr\fR)
 .sp
 int
@@ -44,6 +42,7 @@ int
 .sp
 int
 \fBTcl_DictObjRemoveKeyList\fR(\fIinterp, dictPtr, keyc, keyv\fR)
+.fi
 .SH ARGUMENTS
 .AS Tcl_DictSearch "**valuePtrPtr" in/out
 .AP Tcl_Interp *interp in
@@ -70,9 +69,14 @@ Points to a variable that will have the value from a key/value pair
 placed within it.  For \fBTcl_DictObjFirst\fR and
 \fBTcl_DictObjNext\fR, this may be NULL to indicate that the caller is
 not interested in the value.
-.AP int *sizePtr out
+.AP "Tcl_Size \&| int" *sizePtr out
 Points to a variable that will have the number of key/value pairs
 contained within the dictionary placed within it.
+May be (Tcl_Size *)NULL when not used. If it points to a variable which
+type is not \fBTcl_Size\fR, a compiler warning will be generated.
+If your extensions is compiled with -DTCL_8_API, this function will return
+NULL for dictionaries larger than INT_MAX (which should
+trigger proper error-handling), otherwise expect it to crash.
 .AP Tcl_DictSearch *searchPtr in/out
 Pointer to record to use to keep track of progress in enumerating all
 key/value pairs in a dictionary.  The contents of the record will be
@@ -84,7 +88,7 @@ returned, the search record \fImust\fR be passed to
 Points to a variable that will have a non-zero value written into it
 when the enumeration of the key/value pairs in a dictionary has
 completed, and a zero otherwise.
-.AP int keyc in
+.AP Tcl_Size keyc in
 Indicates the number of keys that will be supplied in the \fIkeyv\fR
 array.
 .AP "Tcl_Obj *const" *keyv in
@@ -138,7 +142,8 @@ converted to a dictionary.
 \fBTcl_DictObjSize\fR updates the given variable with the number of
 key/value pairs currently in the given dictionary. The result of this
 procedure is \fBTCL_OK\fR, or \fBTCL_ERROR\fR if the \fIdictPtr\fR cannot be
-converted to a dictionary.
+converted to a dictionary or if \fIsizePtr\fR points to a variable of type
+\fBint\fR and the dict contains more than 2**31 key/value pairs.
 .PP
 \fBTcl_DictObjFirst\fR commences an iteration across all the key/value
 pairs in the given dictionary, placing the key and value in the
@@ -190,6 +195,73 @@ path as this is easy to construct from repeated use of
 dictionaries are created for non-terminal keys where they do not
 already exist. With \fBTcl_DictObjRemoveKeyList\fR, all non-terminal
 keys must exist and have dictionaries as their values.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_NewDictObj\fR always returns a zero-reference object, much like
+\fBTcl_NewObj\fR.
+.PP
+\fBTcl_DictObjPut\fR does not modify the reference count of its \fIdictPtr\fR
+argument, but does require that the object be unshared.  If
+\fBTcl_DictObjPut\fR returns \fBTCL_ERROR\fR it does not manipulate any
+reference counts; but if it returns \fBTCL_OK\fR then it definitely increments
+the reference count of \fIvaluePtr\fR and may increment the reference count of
+\fIkeyPtr\fR; the latter case happens exactly when the key did not previously
+exist in the dictionary.  Note however that this function may set the
+interpreter result; if that is the only place that is holding a reference to
+an object, it will be deleted.
+.PP
+\fBTcl_DictObjGet\fR only reads from its \fIdictPtr\fR and \fIkeyPtr\fR
+arguments, and does not manipulate their reference counts at all.  If the
+\fIvaluePtrPtr\fR argument is not set to NULL (and the function doesn't return
+\fBTCL_ERROR\fR), it will be set to a value with a reference count of at least
+1, with a reference owned by the dictionary.  Note however that this function
+may set the interpreter result; if that is the only place that is holding a
+reference to an object, it will be deleted.
+.PP
+\fBTcl_DictObjRemove\fR does not modify the reference count of its
+\fIdictPtr\fR argument, but does require that the object be unshared. It does
+not manipulate the reference count of its \fIkeyPtr\fR argument at all.  Note
+however that this function may set the interpreter result; if that is the only
+place that is holding a reference to an object, it will be deleted.
+.PP
+\fBTcl_DictObjSize\fR does not modify the reference count of its \fIdictPtr\fR
+argument; it only reads.  Note however that this function may set the
+interpreter result; if that is the only place that is holding a reference to
+the dictionary object, it will be deleted.
+.PP
+\fBTcl_DictObjFirst\fR does not modify the reference count of its
+\fIdictPtr\fR argument; it only reads. The variables given by the
+\fIkeyPtrPtr\fR and \fIvaluePtrPtr\fR arguments (if not NULL) will be updated
+to contain references to the relevant values in the dictionary; their
+reference counts will be at least 1 (due to the dictionary holding a reference
+to them). It may also manipulate internal references; these are not exposed to
+user code, but require a matching \fBTcl_DictObjDone\fR call.  Note however
+that this function may set the interpreter result; if that is the only place
+that is holding a reference to the dictionary object, it will be deleted.
+.PP
+Similarly for \fBTcl_DictObjNext\fR; the variables given by the
+\fIkeyPtrPtr\fR and \fIvaluePtrPtr\fR arguments (if not NULL) will be updated
+to contain references to the relevant values in the dictionary; their
+reference counts will be at least 1 (due to the dictionary holding a reference
+to them).
+.PP
+\fBTcl_DictObjDone\fR does not manipulate (user-visible) reference counts.
+.PP
+\fBTcl_DictObjPutKeyList\fR is similar to \fBTcl_DictObjPut\fR; it does not
+modify the reference count of its \fIdictPtr\fR argument, but does require
+that the object be unshared. It may increment the reference count of any value
+passed in the \fIkeyv\fR argument, and will increment the reference count of
+the \fIvaluePtr\fR argument on success. It is recommended that values passed
+via \fIkeyv\fR and \fIvaluePtr\fR do not have zero reference counts.  Note
+however that this function may set the interpreter result; if that is the only
+place that is holding a reference to an object, it will be deleted.
+.PP
+\fBTcl_DictObjRemoveKeyList\fR is similar to \fBTcl_DictObjRemove\fR; it does
+not modify the reference count of its \fIdictPtr\fR argument, but does require
+that the object be unshared, and does not modify the reference counts of any
+of the values passed in the \fIkeyv\fR argument.  Note however that this
+function may set the interpreter result; if that is the only place that is
+holding a reference to an object, it will be deleted.
 .SH EXAMPLE
 Using the dictionary iteration interface to search determine if there
 is a key that maps to itself:
@@ -16,6 +16,7 @@ Tcl_DoOneEvent \- wait for events and invoke event handlers
 .sp
 int
 \fBTcl_DoOneEvent\fR(\fIflags\fR)
+.fi
 .SH ARGUMENTS
 .AS int flags
 .AP int flags in
@@ -53,24 +54,18 @@ If the \fIflags\fR argument to \fBTcl_DoOneEvent\fR is non-zero,
 it restricts the kinds of events that will be processed by
 \fBTcl_DoOneEvent\fR.
 \fIFlags\fR may be an OR-ed combination of any of the following bits:
-.TP 27
-\fBTCL_WINDOW_EVENTS\fR \-
+.IP \fBTCL_WINDOW_EVENTS\fR
 Process window system events.
-.TP 27
-\fBTCL_FILE_EVENTS\fR \-
+.IP \fBTCL_FILE_EVENTS\fR
 Process file events.
-.TP 27
-\fBTCL_TIMER_EVENTS\fR \-
+.IP \fBTCL_TIMER_EVENTS\fR
 Process timer events.
-.TP 27
-\fBTCL_IDLE_EVENTS\fR \-
+.IP \fBTCL_IDLE_EVENTS\fR
 Process idle callbacks.
-.TP 27
-\fBTCL_ALL_EVENTS\fR \-
+.IP \fBTCL_ALL_EVENTS\fR
 Process all kinds of events:  equivalent to OR-ing together all of the
 above flags or specifying none of them.
-.TP 27
-\fBTCL_DONT_WAIT\fR \-
+.IP \fBTCL_DONT_WAIT\fR
 Do not sleep:  process only events that are ready at the time of the
 call.
 .LP
@@ -17,11 +17,12 @@ Tcl_DoWhenIdle, Tcl_CancelIdleCall \- invoke a procedure when there are no pendi
 \fBTcl_DoWhenIdle\fR(\fIproc, clientData\fR)
 .sp
 \fBTcl_CancelIdleCall\fR(\fIproc, clientData\fR)
+.fi
 .SH ARGUMENTS
 .AS Tcl_IdleProc clientData
 .AP Tcl_IdleProc *proc in
 Procedure to invoke.
-.AP ClientData clientData in
+.AP void *clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .BE
 .SH DESCRIPTION
@@ -43,7 +44,7 @@ type \fBTcl_IdleProc\fR:
 .PP
 .CS
 typedef void \fBTcl_IdleProc\fR(
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 .CE
 .PP
 The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR
@@ -20,6 +20,7 @@ Tcl_Obj *
 .sp
 int
 \fBTcl_GetDoubleFromObj\fR(\fIinterp, objPtr, doublePtr\fR)
+.fi
 .SH ARGUMENTS
 .AS Tcl_Interp doubleValue in/out
 .AP double doubleValue in
@@ -58,7 +59,20 @@ and if \fIinterp\fR is non-NULL, an error message is left in \fIinterp\fR.
 The \fBTcl_ObjType\fR of \fIobjPtr\fR may be changed to make subsequent
 calls to \fBTcl_GetDoubleFromObj\fR more efficient.
 '\" TODO: add discussion of treatment of NaN value
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_NewDoubleObj\fR always returns a zero-reference object, much
+like \fBTcl_NewObj\fR.
+.PP
+\fBTcl_SetDoubleObj\fR does not modify the reference count of its
+\fIobjPtr\fR argument, but does require that the object be unshared.
+.PP
+\fBTcl_GetDoubleFromObj\fR does not modify the reference count of its
+\fIobjPtr\fR argument; it only reads. Note however that this function
+may set the interpreter result; if that is the only place that
+is holding a reference to the object, it will be deleted.
 .SH "SEE ALSO"
 Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
 .SH KEYWORDS
-double, double value, double type, internal representation, value, value type, string representation
+double, double value, double type, internal representation, value, value type,
+string representation
@@ -15,12 +15,10 @@ Tcl_DumpActiveMemory, Tcl_InitMemory, Tcl_ValidateAllMemory \- Validated memory
 int
 \fBTcl_DumpActiveMemory\fR(\fIfileName\fR)
 .sp
-void
 \fBTcl_InitMemory\fR(\fIinterp\fR)
 .sp
-void
 \fBTcl_ValidateAllMemory\fR(\fIfileName, line\fR)
-
+.fi
 .SH ARGUMENTS
 .AS Tcl_Interp *fileName
 .AP Tcl_Interp *interp in
@@ -43,7 +41,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 \fBckalloc\fR was
+(excluding guard zone), size, source file where \fBTcl_Alloc\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 +53,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 \fBckalloc\fR and
-\fBckfree\fR are called.  This function forces the validation to occur
+which case validation of all blocks occurs when \fBTcl_Alloc\fR and
+\fBTcl_Free\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_WinTCharToUtf, Tcl_WinUtfToTChar, Tcl_GetEncodingName, Tcl_SetSystemEncoding, Tcl_GetEncodingNameFromEnvironment, Tcl_GetEncodingNames, Tcl_CreateEncoding, Tcl_GetEncodingSearchPath, Tcl_SetEncodingSearchPath, Tcl_GetDefaultEncodingDir, Tcl_SetDefaultEncodingDir \- procedures for creating and using encodings
+Tcl_GetEncoding, Tcl_FreeEncoding, Tcl_GetEncodingFromObj, Tcl_ExternalToUtfDString, Tcl_ExternalToUtfDStringEx, Tcl_ExternalToUtf, Tcl_UtfToExternalDString, Tcl_UtfToExternalDStringEx, Tcl_UtfToExternal, Tcl_GetEncodingName, Tcl_SetSystemEncoding, Tcl_GetEncodingNameFromEnvironment, Tcl_GetEncodingNames, Tcl_CreateEncoding, Tcl_GetEncodingSearchPath, Tcl_SetEncodingSearchPath \- procedures for creating and using encodings
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -16,7 +16,6 @@ Tcl_GetEncoding, Tcl_FreeEncoding, Tcl_GetEncodingFromObj, Tcl_ExternalToUtfDStr
 Tcl_Encoding
 \fBTcl_GetEncoding\fR(\fIinterp, name\fR)
 .sp
-void
 \fBTcl_FreeEncoding\fR(\fIencoding\fR)
 .sp
 int
@@ -25,10 +24,16 @@ int
 char *
 \fBTcl_ExternalToUtfDString\fR(\fIencoding, src, srcLen, dstPtr\fR)
 .sp
+int
+\fBTcl_ExternalToUtfDStringEx\fR(\fIinterp, encoding, src, srcLen, flags, dstPtr, errorIdxPtr\fR)
+.sp
 char *
 \fBTcl_UtfToExternalDString\fR(\fIencoding, src, srcLen, dstPtr\fR)
 .sp
 int
+\fBTcl_UtfToExternalDStringEx\fR(\fIinterp, encoding, src, srcLen, flags, dstPtr, errorIdxPtr\fR)
+.sp
+int
 \fBTcl_ExternalToUtf\fR(\fIinterp, encoding, src, srcLen, flags, statePtr,
                  dst, dstLen, srcReadPtr, dstWrotePtr, dstCharsPtr\fR)
 .sp
@@ -36,22 +41,18 @@ 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
+Tcl_Size
+\fBTcl_GetEncodingNulLength\fR(\fIencoding\fR)
+.sp
 int
 \fBTcl_SetSystemEncoding\fR(\fIinterp, name\fR)
 .sp
 const char *
 \fBTcl_GetEncodingNameFromEnvironment\fR(\fIbufPtr\fR)
 .sp
-void
 \fBTcl_GetEncodingNames\fR(\fIinterp\fR)
 .sp
 Tcl_Encoding
@@ -62,12 +63,7 @@ Tcl_Obj *
 .sp
 int
 \fBTcl_SetEncodingSearchPath\fR(\fIsearchPath\fR)
-.sp
-const char *
-\fBTcl_GetDefaultEncodingDir\fR(\fIvoid\fR)
-.sp
-void
-\fBTcl_SetDefaultEncodingDir\fR(\fIpath\fR)
+.fi
 .SH ARGUMENTS
 .AS "const Tcl_EncodingType" *dstWrotePtr in/out
 .AP Tcl_Interp *interp in
@@ -85,18 +81,18 @@ 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 and \fBTcl_WinUtfToTChar\fR functions, an array of
+\fBTcl_UtfToExternal\fR function, 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 int srcLen in
+.AP Tcl_Size 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
 Pointer to an uninitialized or free \fBTcl_DString\fR in which the converted
 result will be stored.
 .AP int flags in
-Various flag bits OR-ed together.
+This is a bit mask passed in to control the operation of the encoding functions.
 \fBTCL_ENCODING_START\fR signifies that the
 source buffer is the first block in a (potentially multi-block) input
 stream, telling the conversion routine to reset to an initial state and
@@ -104,11 +100,15 @@ perform any initialization that needs to occur before the first byte is
 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_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.
+byte is converted and then to reset to an initial state. The
+\fBTCL_PROFILE_*\fR bits defined in the \fBPROFILES\fR section below
+control the encoding profile to be used for dealing with invalid data or
+other errors in the encoding transform.
+The flag \fBTCL_ENCODING_STOPONERROR\fR has no effect,
+it only has meaning in Tcl 8.x.
+.PP
+Some flags bits may not be usable with some functions as noted in the
+function descriptions below.
 .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
@@ -134,6 +134,9 @@ buffer as a result of the conversion.  May be NULL.
 .AP int *dstCharsPtr out
 Filled with the number of characters that correspond to the number of bytes
 stored in the output buffer.  May be NULL.
+.AP Tcl_Size *errorIdxPtr out
+Filled with the index of the byte or character that caused the encoding transform
+to fail. May be NULL.
 .AP Tcl_DString *bufPtr out
 Storage for the prescribed system encoding name.
 .AP "const Tcl_EncodingType" *typePtr in
@@ -208,6 +211,27 @@ When converting, if any of the characters in the source buffer cannot be
 represented in the target encoding, a default fallback character will be
 used.  The return value is a pointer to the value stored in the DString.
 .PP
+\fBTcl_ExternalToUtfDStringEx\fR is a more flexible version of older
+\fBTcl_ExternalToUtfDString\fR function. It takes three additional parameters,
+\fBinterp\fR, \fBflags\fR and \fBerrorIdxPtr\fR. The \fBflags\fR parameter may
+be used to specify the profile to be used for the transform. The
+\fBTCL_ENCODING_START\fR and \fBTCL_ENCODING_END\fR bits in \fBflags\fR are
+ignored as the function assumes the entire source string to be decoded is passed
+into the function. On success, the function returns \fBTCL_OK\fR with the
+converted string stored in \fB*dstPtr\fR. For errors \fIother than conversion
+errors\fR, such as invalid flags, the function returns \fBTCL_ERROR\fR with an
+error message in \fBinterp\fR if it is not NULL.
+For conversion errors, \fBTcl_ExternalToUtfDStringEx\fR returns one
+of the \fBTCL_CONVERT_*\fR errors listed below for \fBTcl_ExternalToUtf\fR.
+When one of these conversion errors is returned, an error message is stored
+in \fBinterp\fR only if \fBerrorIdxPtr\fR is NULL. Otherwise, no error message
+is stored as the function expects the caller is interested the decoded data
+up to that point and not treating this as an immediate error condition.
+The index of the error location is stored in \fB*errorIdxPtr\fR.
+.PP
+The caller must call \fBTcl_DStringFree\fR to free up the \fB*dstPtr\fR resources
+irrespective of the return value from the function.
+.PP
 \fBTcl_ExternalToUtf\fR converts a source buffer \fIsrc\fR from the specified
 \fIencoding\fR into UTF-8.  Up to \fIsrcLen\fR bytes are converted from the
 source buffer and up to \fIdstLen\fR converted bytes are stored in \fIdst\fR.
@@ -229,12 +253,12 @@ the unconverted bytes that remained in \fIsrc\fR plus some further bytes
 from the source stream to properly convert the formerly split-up multibyte
 sequence.
 .IP \fBTCL_CONVERT_SYNTAX\fR 29
-The source buffer contained an invalid character sequence.  This may occur
-if the input stream has been damaged or if the input encoding method was
+The source buffer contained an invalid byte or character sequence.  This may
+occur 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_STOPONERROR\fR was specified.
+the target encoding.
 .RE
 .LP
 \fBTcl_UtfToExternalDString\fR converts a source buffer \fIsrc\fR from UTF-8
@@ -246,6 +270,16 @@ characters in the source buffer cannot be represented in the target
 encoding, a default fallback character will be used.  The return value is
 a pointer to the value stored in the DString.
 .PP
+\fBTcl_UtfToExternalDStringEx\fR is an enhanced version of
+\fBTcl_UtfToExternalDString\fR that transforms UTF-8 encoded source data to a
+specified \fIencoding\fR. Except for the direction of the transform, the
+parameters and return values are identical to those of
+\fBTcl_ExternalToUtfDStringEx\fR. See
+that function above for details about the same.
+.PP
+Irrespective of the return code from the function, the caller must free
+resources associated with \fB*dstPtr\fR when the function returns.
+.PP
 \fBTcl_UtfToExternal\fR converts a source buffer \fIsrc\fR from UTF-8 into
 the specified \fIencoding\fR.  Up to \fIsrcLen\fR bytes are converted from
 the source buffer and up to \fIdstLen\fR converted bytes are stored in
@@ -255,18 +289,15 @@ 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.
-.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
 \fBTcl_GetEncodingName\fR is only guaranteed to persist until the
 \fIencoding\fR is deleted.  The caller must not modify this string.
 .PP
+\fBTcl_GetEncodingNulLength\fR returns the length of the terminating
+nul byte sequence for strings in the specified encoding.
+.PP
 \fBTcl_SetSystemEncoding\fR sets the default encoding that should be used
 whenever the user passes a NULL value for the \fIencoding\fR argument to
 any of the other encoding functions.  If \fIname\fR is NULL, the system
@@ -287,7 +318,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_SetDefaultEncodingDir\fR.  This procedure does not ensure that the
+\fBTcl_SetEncodingSearchPath\fR.  This procedure does not ensure that the
 dynamically-loadable encoding files contain valid data, but merely that they
 exist.
 .PP
@@ -309,13 +340,13 @@ about the name of the encoding and the procedures that will be called to
 convert between this encoding and UTF-8.  It is defined as follows:
 .PP
 .CS
-typedef struct Tcl_EncodingType {
+typedef struct {
    const char *\fIencodingName\fR;
    Tcl_EncodingConvertProc *\fItoUtfProc\fR;
    Tcl_EncodingConvertProc *\fIfromUtfProc\fR;
    Tcl_EncodingFreeProc *\fIfreeProc\fR;
-    ClientData \fIclientData\fR;
-    int \fInullSize\fR;
+    void *\fIclientData\fR;
+    Tcl_Size \fInullSize\fR;
 } \fBTcl_EncodingType\fR;
 .CE
 .PP
@@ -345,7 +376,7 @@ type \fBTcl_EncodingConvertProc\fR:
 .PP
 .CS
 typedef int \fBTcl_EncodingConvertProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
        const char *\fIsrc\fR,
        int \fIsrcLen\fR,
        int \fIflags\fR,
@@ -377,7 +408,7 @@ The callback procedure \fIfreeProc\fR, if non-NULL, should match the type
 .PP
 .CS
 typedef void \fBTcl_EncodingFreeProc\fR(
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 .CE
 .PP
 This \fIfreeProc\fR function is called when the encoding is deleted.  The
@@ -402,15 +433,6 @@ 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
@@ -524,13 +546,13 @@ encoding:
 E
 init		{}
 final		{}
-iso8859-1	\ex1b(B
-jis0201		\ex1b(J
-jis0208		\ex1b$@
-jis0208		\ex1b$B
-jis0212		\ex1b$(D
-gb2312		\ex1b$A
-ksc5601		\ex1b$(C
+iso8859-1	\ex1B(B
+jis0201		\ex1B(J
+jis0208		\ex1B$@
+jis0208		\ex1B$B
+jis0212		\ex1B$(D
+gb2312		\ex1B$A
+ksc5601		\ex1B$(C
 .CE
 .PP
 In the file, the first column represents an option and the second column
@@ -542,7 +564,7 @@ marks that encoding.  Tcl syntax is used for the values; in the above
 example, for instance,
 .QW \fB{}\fR
 represents the empty string and
-.QW \fB\ex1b\fR
+.QW \fB\ex1B\fR
 represents character 27.
 .PP
 When \fBTcl_GetEncoding\fR encounters an encoding \fIname\fR that has not
@@ -550,5 +572,28 @@ been loaded, it attempts to load an encoding file called \fIname\fB.enc\fR
 from the \fBencoding\fR subdirectory of each directory that Tcl searches
 for its script library.  If the encoding file exists, but is
 malformed, an error message will be left in \fIinterp\fR.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_GetEncodingFromObj\fR does not modify the reference count of its
+\fIobjPtr\fR argument; it only reads. Note however that this function may set
+the interpreter result; if that is the only place that is holding a reference
+to the object, it will be deleted.
+.PP
+\fBTcl_GetEncodingSearchPath\fR returns an object with a reference count of at
+least 1.
+.SH "PROFILES"
+Encoding profiles define the manner in which errors in the encoding transforms
+are handled by the encoding functions. An application can specify the profile
+to be used by OR-ing the \fBflags\fR parameter passed to the function
+with at most one of \fBTCL_ENCODING_PROFILE_TCL8\fR,
+\fBTCL_ENCODING_PROFILE_STRICT\fR or \fBTCL_ENCODING_PROFILE_REPLACE\fR.
+These correspond to the \fBtcl8\fR, \fBstrict\fR and \fBreplace\fR profiles
+respectively. If none are specified, a version-dependent default profile is used.
+For Tcl 9.0, the default profile is \fBstrict\fR.
+.PP
+For details about profiles, see the \fBPROFILES\fR section in
+the documentation of the \fBencoding\fR command.
+.SH "SEE ALSO"
+encoding(n)
 .SH KEYWORDS
 utf, encoding, convert
@@ -4,8 +4,6 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-'\" This documents the C API introduced in TIP#235
-'\"
 .TH Tcl_Ensemble 3 8.5 Tcl "Tcl Library Procedures"
 .so man.macros
 .BS
@@ -36,13 +34,11 @@ int
 int
 \fBTcl_SetEnsembleMappingDict\fR(\fIinterp, token, dictObj\fR)
 .sp
-.VS 8.6
 int
 \fBTcl_GetEnsembleParameterList\fR(\fIinterp, token, listObjPtr\fR)
 .sp
 int
 \fBTcl_SetEnsembleParameterList\fR(\fIinterp, token, listObj\fR)
-.VE 8.6
 .sp
 int
 \fBTcl_GetEnsembleSubcommandList\fR(\fIinterp, token, listObjPtr\fR)
@@ -58,6 +54,7 @@ int
 .sp
 int
 \fBTcl_GetEnsembleNamespace\fR(\fIinterp, token, namespacePtrPtr\fR)
+.fi
 .SH ARGUMENTS
 .AS Tcl_Namespace **namespacePtrPtr in/out
 .AP Tcl_Interp *interp in/out
@@ -163,7 +160,7 @@ All command names in prefixes set via \fBTcl_SetEnsembleMappingDict\fR
 must be fully qualified.
 .TP
 \fBformal pre-subcommand parameter list\fR (read-write)
-.VS 8.6
+.
 A list of formal parameter names (the names only being used when generating
 error messages) that come at invocation of the ensemble between the name of
 the ensemble and the subcommand argument. NULL (the default) is equivalent to
@@ -174,7 +171,6 @@ respectively. The result of both of those functions is a Tcl result code
 ensemble) and the
 dictionary obtained from \fBTcl_GetEnsembleParameterList\fR should always be
 treated as immutable even if it is unshared.
-.VE 8.6
 .TP
 \fBsubcommand list\fR (read-write)
 .
@@ -213,6 +209,27 @@ namespace whose list of exported commands is used if both the mapping
 dictionary and the subcommand list properties are NULL. May be read
 using \fBTcl_GetEnsembleNamespace\fR which returns a Tcl result code
 (\fBTCL_OK\fR, or \fBTCL_ERROR\fR if the token does not refer to an ensemble).
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_FindEnsemble\fR does not modify the reference count of its
+\fIcmdNameObj\fR argument; it only reads. Note however that this function may
+set the interpreter result; if that is the only place that is holding a
+reference to the object, it will be deleted.
+.PP
+The ensemble property getters (\fBTcl_GetEnsembleMappingDict\fR,
+\fBTcl_GetEnsembleParameterList\fR, \fBTcl_GetEnsembleSubcommandList\fR, and
+\fBTcl_GetEnsembleUnknownHandler\fR) do not manipulate the reference count of
+the values they provide out; if those are non-NULL, they will have a reference
+count of at least 1.  Note that these functions may set the interpreter
+result.
+.PP
+The ensemble property setters (\fBTcl_SetEnsembleMappingDict\fR,
+\fBTcl_SetEnsembleParameterList\fR, \fBTcl_SetEnsembleSubcommandList\fR, and
+\fBTcl_SetEnsembleUnknownHandler\fR) will increment the reference count of the
+new value of the property they are given if they succeed (and decrement the
+reference count of the old value of the property, if relevant). If the
+property setters return \fBTCL_ERROR\fR, the reference count of the Tcl_Obj
+argument is left unchanged.
 .SH "SEE ALSO"
 namespace(n), Tcl_DeleteCommandFromToken(3)
 .SH KEYWORDS
@@ -15,6 +15,7 @@ Tcl_PutEnv \- procedures to manipulate the environment
 .sp
 int
 \fBTcl_PutEnv\fR(\fIassignment\fR)
+.fi
 .SH ARGUMENTS
 .AS "const char" *assignment
 .AP "const char" *assignment in
@@ -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, Tcl_VarEvalVA \- execute Tcl scripts
+Tcl_EvalObjEx, Tcl_EvalFile, Tcl_EvalObjv, Tcl_Eval, Tcl_EvalEx, Tcl_GlobalEval, Tcl_GlobalEvalObj, Tcl_VarEval \- execute Tcl scripts
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -38,9 +38,7 @@ int
 .sp
 int
 \fBTcl_VarEval\fR(\fIinterp, part, part, ... \fB(char *)NULL\fR)
-.sp
-int
-\fBTcl_VarEvalVA\fR(\fIinterp, argList\fR)
+.fi
 .SH ARGUMENTS
 .AS Tcl_Interp **termPtr
 .AP Tcl_Interp *interp in
@@ -53,7 +51,7 @@ OR'ed combination of flag bits that specify additional options.
 \fBTCL_EVAL_GLOBAL\fR and \fBTCL_EVAL_DIRECT\fR are currently supported.
 .AP "const char" *fileName in
 Name of a file containing a Tcl script.
-.AP int objc in
+.AP Tcl_Size objc in
 The number of values in the array pointed to by \fIobjv\fR;
 this is also the number of words in the command.
 .AP Tcl_Obj **objv in
@@ -67,9 +65,6 @@ 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
@@ -99,13 +94,11 @@ its contents as a Tcl script.  It returns the same information as
 If the file could not be read then a Tcl error is returned to describe
 why the file could not be read.
 The eofchar for files is
-.QW \e32
+.QW \ex1A
 (^Z) for all platforms. If you require a
 .QW ^Z
 in code for string comparison, you can use
-.QW \e032
-or
-.QW \eu001a ,
+.QW \ex1A ,
 which will be safely substituted by the Tcl interpreter into
 .QW ^Z .
 .PP
@@ -128,16 +121,10 @@ 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.  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.
+\fBTcl_EvalObjEx\fR.
 .PP
 \fBTcl_EvalEx\fR is an extended version of \fBTcl_Eval\fR that takes
-additional arguments \fInumBytes\fR and \fIflags\fR.  For the
-efficiency reason given above, \fBTcl_EvalEx\fR is generally preferred
-over \fBTcl_Eval\fR.
+additional arguments \fInumBytes\fR and \fIflags\fR.
 .PP
 \fBTcl_GlobalEval\fR and \fBTcl_GlobalEvalObj\fR are older procedures
 that are now deprecated.  They are similar to \fBTcl_EvalEx\fR and
@@ -150,13 +137,9 @@ equivalent to using the \fBTCL_EVAL_GLOBAL\fR flag (see below).
 of any length, concatenates them into a single string,
 then calls \fBTcl_Eval\fR to execute that string as a Tcl command.
 It returns the result of the command and also modifies
-\fIinterp->result\fR in the same way as \fBTcl_Eval\fR.
+the interpreter result in the same way as \fBTcl_Eval\fR.
 The last argument to \fBTcl_VarEval\fR must be (char *)NULL to indicate the end
 of arguments.
-.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.  \fBTcl_VarEvalVA\fR is now deprecated.

 .SH "FLAG BITS"
 .PP
@@ -206,6 +189,20 @@ the \fBreturn\fR, \fBbreak\fR, or \fBcontinue\fR command was
 invoked in an inappropriate place.
 This means that top-level applications should never see a return code
 from \fBTcl_EvalObjEx\fR other than \fBTCL_OK\fR or \fBTCL_ERROR\fR.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_EvalObjEx\fR and \fBTcl_GlobalEvalObj\fR both increment and
+decrement the reference count of their \fIobjPtr\fR argument; you must
+not pass them any value with a reference count of zero. They also
+manipulate the interpreter result; you must not count on the
+interpreter result to hold the reference count of any value over
+these calls.
+.PP
+\fBTcl_EvalObjv\fR may increment and decrement the reference count of
+any value passed via its \fIobjv\fR argument; you must not pass any
+value with a reference count of zero. This function also manipulates
+the interpreter result; you must not count on the interpreter result
+to hold the reference count of any value over this call.

 .SH KEYWORDS
 execute, file, global, result, script, value
@@ -31,18 +31,19 @@ Tcl_Exit, Tcl_Finalize, Tcl_CreateExitHandler, Tcl_DeleteExitHandler, Tcl_ExitTh
 .sp
 Tcl_ExitProc *
 \fBTcl_SetExitProc\fR(\fIproc\fR)
+.fi
 .SH ARGUMENTS
 .AS Tcl_ExitProc clientData
 .AP int status  in
 Provides information about why the application or thread exited.
-Exact meaning may
-be platform-specific.  0 usually means a normal exit, any nonzero value
+Exact meaning may be platform-specific.
+0 usually means a normal exit, any nonzero value
 usually means that an error occurred.
 .AP Tcl_ExitProc *proc in
 Procedure to invoke before exiting application, or (for
 \fBTcl_SetExitProc\fR) NULL to uninstall the current application exit
 procedure.
-.AP ClientData clientData in
+.AP void *clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .BE

@@ -53,18 +54,18 @@ execution of a \fBTcl\fR application. Exit handlers are invoked to cleanup the
 application's state before ending the execution of \fBTcl\fR code.
 .PP
 Invoke \fBTcl_Exit\fR to end a \fBTcl\fR application and to exit from this
-process. This procedure is invoked by the \fBexit\fR command, and can be
+process. This procedure is invoked by the \fBexit\fR Tcl command, and can be
 invoked anyplace else to terminate the application.
-No-one should ever invoke the \fBexit\fR system procedure directly;  always
+No-one should ever invoke the \fBexit()\fR system call directly;  always
 invoke \fBTcl_Exit\fR instead, so that it can invoke exit handlers.
-Note that if other code invokes \fBexit\fR system procedure directly, or
+Note that if other code invokes \fBexit()\fR system call directly, or
 otherwise causes the application to terminate without calling
 \fBTcl_Exit\fR, the exit handlers will not be run.
-\fBTcl_Exit\fR internally invokes the \fBexit\fR system call, thus it never
+\fBTcl_Exit\fR internally invokes the \fBexit()\fR system call, thus it never
 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 ClientData); the application
+consisting of the exit status (cast to void *); 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 +94,7 @@ and freeing global memory.
 .PP
 .CS
 typedef void \fBTcl_ExitProc\fR(
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 .CE
 .PP
 The \fIclientData\fR parameter to \fIproc\fR is a
@@ -133,8 +134,11 @@ 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 ClientData value.
+cast to a void *value.
+.PP
+\fBTcl_SetExitProc\fR can not be used in stub-enabled extensions.
 .SH "SEE ALSO"
 exit(n)
 .SH KEYWORDS
-abort, callback, cleanup, dynamic loading, end application, exit, unloading, thread
+abort, callback, cleanup, dynamic loading, end application, exit, unloading,
+thread
@@ -25,6 +25,7 @@ int
 .sp
 int
 \fBTcl_ExprString\fR(\fIinterp, expr\fR)
+.fi
 .SH ARGUMENTS
 .AS Tcl_Interp *booleanPtr out
 .AP Tcl_Interp *interp in
@@ -24,6 +24,7 @@ int
 .sp
 int
 \fBTcl_ExprObj\fR(\fIinterp, objPtr, resultPtrPtr\fR)
+.fi
 .SH ARGUMENTS
 .AS Tcl_Interp **resultPtrPtr out
 .AP Tcl_Interp *interp in
@@ -98,6 +99,15 @@ containing the expression's value at \fI*resultPtrPtr\fR.
 In this case, the caller is responsible for calling
 \fBTcl_DecrRefCount\fR to decrement the value's reference count
 when it is finished with the value.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_ExprLongObj\fR, \fBTcl_ExprDoubleObj\fR,
+\fBTcl_ExprBooleanObj\fR, and \fBTcl_ExprObj\fR all increment and
+decrement the reference count of their \fIobjPtr\fR arguments; you
+must not pass them any value with a reference count of zero. They also
+manipulate the interpreter result; you must not count on the
+interpreter result to hold the reference count of any value over these
+calls.

 .SH "SEE ALSO"
 Tcl_ExprLong, Tcl_ExprDouble, Tcl_ExprBoolean, Tcl_ExprString, Tcl_GetObjResult
@@ -9,7 +9,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_FSRegister, Tcl_FSUnregister, Tcl_FSData, Tcl_FSMountsChanged, Tcl_FSGetFileSystemForPath, Tcl_FSGetPathType, Tcl_FSCopyFile, Tcl_FSCopyDirectory, Tcl_FSCreateDirectory, Tcl_FSDeleteFile, Tcl_FSRemoveDirectory, Tcl_FSRenameFile, Tcl_FSListVolumes, Tcl_FSEvalFile, Tcl_FSEvalFileEx, Tcl_FSLoadFile, Tcl_FSUnloadFile, Tcl_FSMatchInDirectory, Tcl_FSLink, Tcl_FSLstat, Tcl_FSUtime, Tcl_FSFileAttrsGet, Tcl_FSFileAttrsSet, Tcl_FSFileAttrStrings, Tcl_FSStat, Tcl_FSAccess, Tcl_FSOpenFileChannel, Tcl_FSGetCwd, Tcl_FSChdir, Tcl_FSPathSeparator, Tcl_FSJoinPath, Tcl_FSSplitPath, Tcl_FSEqualPaths, Tcl_FSGetNormalizedPath, Tcl_FSJoinToPath, Tcl_FSConvertToPathType, Tcl_FSGetInternalRep, Tcl_FSGetTranslatedPath, Tcl_FSGetTranslatedStringPath, Tcl_FSNewNativePath, Tcl_FSGetNativePath, Tcl_FSFileSystemInfo, Tcl_GetAccessTimeFromStat, Tcl_GetBlockSizeFromStat, Tcl_GetBlocksFromStat, Tcl_GetChangeTimeFromStat, Tcl_GetDeviceTypeFromStat, Tcl_GetFSDeviceFromStat, Tcl_GetFSInodeFromStat, Tcl_GetGroupIdFromStat, Tcl_GetLinkCountFromStat, Tcl_GetModeFromStat, Tcl_GetModificationTimeFromStat, Tcl_GetSizeFromStat, Tcl_GetUserIdFromStat, Tcl_AllocStatBuf \- procedures to interact with any filesystem
+Tcl_FSRegister, Tcl_FSUnregister, Tcl_FSData, Tcl_FSMountsChanged, Tcl_FSGetFileSystemForPath, Tcl_FSGetPathType, Tcl_FSCopyFile, Tcl_FSCopyDirectory, Tcl_FSCreateDirectory, Tcl_FSDeleteFile, Tcl_FSRemoveDirectory, Tcl_FSRenameFile, Tcl_FSListVolumes, Tcl_FSEvalFile, Tcl_FSEvalFileEx, Tcl_FSLoadFile, Tcl_FSUnloadFile, Tcl_FSMatchInDirectory, Tcl_FSLink, Tcl_FSLstat, Tcl_FSUtime, Tcl_FSFileAttrsGet, Tcl_FSFileAttrsSet, Tcl_FSFileAttrStrings, Tcl_FSStat, Tcl_FSAccess, Tcl_FSOpenFileChannel, Tcl_FSGetCwd, Tcl_FSChdir, Tcl_FSPathSeparator, Tcl_FSJoinPath, Tcl_FSSplitPath, Tcl_FSEqualPaths, Tcl_FSGetNormalizedPath, Tcl_FSJoinToPath, Tcl_FSConvertToPathType, Tcl_FSGetInternalRep, Tcl_FSGetTranslatedPath, Tcl_FSGetTranslatedStringPath, Tcl_FSNewNativePath, Tcl_FSGetNativePath, Tcl_FSFileSystemInfo, Tcl_GetAccessTimeFromStat, Tcl_GetBlockSizeFromStat, Tcl_GetBlocksFromStat, Tcl_GetChangeTimeFromStat, Tcl_GetDeviceTypeFromStat, Tcl_GetFSDeviceFromStat, Tcl_GetFSInodeFromStat, Tcl_GetGroupIdFromStat, Tcl_GetLinkCountFromStat, Tcl_GetModeFromStat, Tcl_GetModificationTimeFromStat, Tcl_GetSizeFromStat, Tcl_GetUserIdFromStat, Tcl_AllocStatBuf, Tcl_FSTildeExpand \- procedures to interact with any filesystem
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -62,10 +62,8 @@ int
 \fBTcl_FSLoadFile\fR(\fIinterp, pathPtr, sym1, sym2, proc1Ptr, proc2Ptr,
               loadHandlePtr, unloadProcPtr\fR)
 .sp
-.VS 8.6
 int
 \fBTcl_FSUnloadFile\fR(\fIinterp, loadHandle\fR)
-.VE 8.6
 .sp
 int
 \fBTcl_FSMatchInDirectory\fR(\fIinterp, resultPtr, pathPtr, pattern, types\fR)
@@ -142,20 +140,22 @@ const void *
 Tcl_Obj *
 \fBTcl_FSFileSystemInfo\fR(\fIpathPtr\fR)
 .sp
+int
+\fBTcl_FSTildeExpand\fR(\fIinterp, pathStr, dsPtr\fR)
+.sp
 Tcl_StatBuf *
 \fBTcl_AllocStatBuf\fR()
 .sp
-.VS 8.6
-Tcl_WideInt
+long long
 \fBTcl_GetAccessTimeFromStat\fR(\fIstatPtr\fR)
 .sp
 unsigned
 \fBTcl_GetBlockSizeFromStat\fR(\fIstatPtr\fR)
 .sp
-Tcl_WideUInt
+unsigned long long
 \fBTcl_GetBlocksFromStat\fR(\fIstatPtr\fR)
 .sp
-Tcl_WideInt
+long long
 \fBTcl_GetChangeTimeFromStat\fR(\fIstatPtr\fR)
 .sp
 int
@@ -176,20 +176,22 @@ int
 unsigned
 \fBTcl_GetModeFromStat\fR(\fIstatPtr\fR)
 .sp
-Tcl_WideInt
+long long
 \fBTcl_GetModificationTimeFromStat\fR(\fIstatPtr\fR)
 .sp
-Tcl_WideUInt
+unsigned long long
 \fBTcl_GetSizeFromStat\fR(\fIstatPtr\fR)
 .sp
 int
 \fBTcl_GetUserIdFromStat\fR(\fIstatPtr\fR)
-.VE 8.6
+.fi
 .SH ARGUMENTS
 .AS Tcl_GlobTypeData **srcPathPtr out
 .AP "const Tcl_Filesystem" *fsPtr in
 Points to a structure containing the addresses of procedures that
 can be called to perform the various filesystem operations.
+.AP "const char" *pathStr in
+Pointer to a NUL terminated string representing a file system path.
 .AP Tcl_Obj *pathPtr in
 The path represented by this value is used for the operation in
 question. If the value does not already have an internal \fBpath\fR
@@ -223,7 +225,7 @@ The second of two path values to compare. The value may be converted
 to \fBpath\fR type.
 .AP Tcl_Obj *listObj in
 The list of path elements to operate on with a \fBjoin\fR operation.
-.AP int elements in
+.AP Tcl_Size elements in
 The number of elements in the \fIlistObj\fR which should
 be joined together. If negative, then all elements are joined.
 .AP Tcl_Obj **errorPtr out
@@ -250,9 +252,9 @@ The structure that contains the result of a stat or lstat operation.
 Name of a procedure to look up in the file's symbol table
 .AP "const char" *sym2 in
 Name of a procedure to look up in the file's symbol table
-.AP Tcl_PackageInitProc **proc1Ptr out
+.AP Tcl_LibraryInitProc **proc1Ptr out
 Filled with the init function for this code.
-.AP Tcl_PackageInitProc **proc2Ptr out
+.AP Tcl_LibraryInitProc **proc2Ptr out
 Filled with the safe-init function for this code.
 .AP void **clientDataPtr out
 Filled with the clientData value to pass to this code's unload
@@ -272,11 +274,16 @@ allowed for the \fImode\fR argument to the Tcl \fBopen\fR command.
 .AP int permissions in
 POSIX-style permission flags such as 0644. If a new file is created, these
 permissions will be set on the created file.
-.AP int *lenPtr out
-If non-NULL, filled with the number of elements in the split path.
+.AP "Tcl_Size \&| int" *lenPtr out
+Filled with the number of elements in the split path.
+May be (Tcl_Size *)NULL when not used. If it points to a variable which
+type is not \fBTcl_Size\fR, a compiler warning will be generated.
+If your extensions is compiled with -DTCL_8_API, this function will return
+NULL for paths having more than INT_MAX elements (which should
+trigger proper error-handling), otherwise expect it to crash.
 .AP Tcl_Obj *basePtr in
 The base path on to which to join the given elements. May be NULL.
-.AP int objc in
+.AP Tcl_Size objc in
 The number of elements in \fIobjv\fR.
 .AP "Tcl_Obj *const" objv[] in
 The elements to join to the given base path.
@@ -291,6 +298,8 @@ created (will be ignored if \fItoPtr\fR is NULL). Valid bits to set
 are \fBTCL_CREATE_SYMBOLIC_LINK\fR and \fBTCL_CREATE_HARD_LINK\fR.
 When both flags are set and the underlying filesystem can do either,
 symbolic links are preferred.
+.AP Tcl_DString *dsPtr out
+Pointer to a \fBTcl_DString\fR to hold an output string result.
 .BE
 .SH DESCRIPTION
 .PP
@@ -424,7 +433,7 @@ caller (with a reference count of 0).
 the encoding identified by \fIencodingName\fR and evaluates
 its contents as a Tcl script. It returns the same information as
 \fBTcl_EvalObjEx\fR.
-If \fIencodingName\fR is NULL, the system encoding is used for
+If \fIencodingName\fR is NULL, the utf-8 encoding is used for
 reading the file contents.
 If the file could not be read then a Tcl error is returned to describe
 why the file could not be read.
@@ -438,7 +447,7 @@ in code for string comparison, you can use
 which will be safely substituted by the Tcl interpreter into
 .QW ^Z .
 \fBTcl_FSEvalFile\fR is a simpler version of
-\fBTcl_FSEvalFileEx\fR that always uses the system encoding
+\fBTcl_FSEvalFileEx\fR that always uses the utf-8 encoding
 when reading the file.
 .PP
 \fBTcl_FSLoadFile\fR dynamically loads a binary code file into memory and
@@ -448,20 +457,16 @@ belongs will be called. If that filesystem does not implement this
 function (most virtual filesystems will not, because of OS limitations
 in dynamically loading binary code), Tcl will attempt to copy the file
 to a temporary directory and load that temporary file.
-.VS 8.6
 \fBTcl_FSUnloadFile\fR reverses the operation, asking for the library
 indicated by the \fIloadHandle\fR to be removed from the process. Note that,
 unlike with the \fBunload\fR command, this does not give the library any
 opportunity to clean up.
-.VE 8.6
 .PP
 Both the above functions return a standard Tcl completion code. If an error
 occurs, an error message is left in the \fIinterp\fR's result.
 .PP
-.VS 8.6
 The token provided via the variable indicated by \fIloadHandlePtr\fR may be
 used with \fBTcl_FindSymbol\fR.
-.VE 8.6
 .PP
 \fBTcl_FSMatchInDirectory\fR is used by the globbing code to search a
 directory for all files which match a given pattern. The appropriate
@@ -687,11 +692,6 @@ of zero, they will be freed when this function returns.
 \fBTcl_FSConvertToPathType\fR tries to convert the given Tcl_Obj to a valid
 Tcl path type, taking account of the fact that the cwd may have changed
 even if this value is already supposedly of the correct type.
-The filename may begin with
-.QW ~
-(to indicate current user's home directory) or
-.QW ~<user>
-(to indicate any user's home directory).
 .PP
 If the conversion succeeds (i.e.\ the value is a valid path in one of
 the current filesystems), then \fBTCL_OK\fR is returned. Otherwise
@@ -713,14 +713,7 @@ from the given Tcl_Obj.
 .PP
 If the translation succeeds (i.e.\ the value is a valid path), then it is
 returned. Otherwise NULL will be returned, and an error message may be
-left in the interpreter. A
-.QW translated
-path is one which contains no
-.QW ~
-or
-.QW ~user
-sequences (these have been expanded to their current
-representation in the filesystem). The value returned is owned by the
+left in the interpreter. The value returned is owned by the
 caller, which must store it or call \fBTcl_DecrRefCount\fR to ensure memory is
 freed. This function is of little practical use, and
 \fBTcl_FSGetNormalizedPath\fR or \fBTcl_FSGetNativePath\fR are usually
@@ -729,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 \fBckfree\fR to ensure it is freed. Again,
+which must store it or call \fBTcl_Free\fR to ensure it is freed. Again,
 \fBTcl_FSGetNormalizedPath\fR or \fBTcl_FSGetNativePath\fR are usually
 better functions to use for most purposes.
 .PP
@@ -793,14 +786,24 @@ absolute.
 .PP
 It returns one of \fBTCL_PATH_ABSOLUTE\fR, \fBTCL_PATH_RELATIVE\fR, or
 \fBTCL_PATH_VOLUME_RELATIVE\fR
+.PP
+\fBTcl_FSTildeExpand\fR performs tilde substitution on the input path passed via
+\fBpathStr\fR as described in the documentation for the \fBfile tildeexpand\fR
+Tcl command. On success, the function returns \fBTCL_OK\fR with the result of
+the substitution in \fBdsPtr\fR which must be subsequently freed by the caller.
+The \fBdsPtr\fR structure is initialized by the function. No guarantees are made
+about the form of the returned path such as the path separators used. The
+returned result should be passed to other Tcl C API functions such as
+\fBTcl_FSGetNormalizedPath\fR or \fBTcl_FSGetNativePath\fR if necessary. On
+error, the function returns \fBTCL_ERROR\fR with an error message in
+\fBinterp\fR which may be passed as NULL if error messages are not of interest.
 .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 \fBckfree\fR). This allows extensions to
+may be deallocated by being passed to \fBTcl_Free\fR). This allows extensions to
 invoke \fBTcl_FSStat\fR and \fBTcl_FSLstat\fR without being dependent on the
 size of the buffer. That in turn depends on the flags used to build Tcl.
 .PP
-.VS 8.6
 The portable fields of a \fITcl_StatBuf\fR may be read using the following
 functions, each of which returns the value of the corresponding field listed
 in the table below. Note that on some platforms there may be other fields in
@@ -824,7 +827,6 @@ for a full description of these fields.
 \fBTcl_GetBlocksFromStat\fR	 st_blocks
 \fBTcl_GetBlockSizeFromStat\fR	 st_blksize
 .DE
-.VE 8.6
 .SH "THE VIRTUAL FILESYSTEM API"
 .PP
 A filesystem provides a \fBTcl_Filesystem\fR structure that contains
@@ -859,9 +861,9 @@ longer be correct.
 The \fBTcl_Filesystem\fR structure contains the following fields:
 .PP
 .CS
-typedef struct Tcl_Filesystem {
+typedef struct {
    const char *\fItypeName\fR;
-    int \fIstructureLength\fR;
+    Tcl_Size \fIstructureLength\fR;
    Tcl_FSVersion \fIversion\fR;
    Tcl_FSPathInFilesystemProc *\fIpathInFilesystemProc\fR;
    Tcl_FSDupInternalRepProc *\fIdupInternalRepProc\fR;
@@ -1023,7 +1025,7 @@ Tcl's internal list of known filesystems.
 .CS
 typedef int \fBTcl_FSPathInFilesystemProc\fR(
        Tcl_Obj *\fIpathPtr\fR,
-        ClientData *\fIclientDataPtr\fR);
+        void **\fIclientDataPtr\fR);
 .CE
 .SS DUPINTERNALREPPROC
 .PP
@@ -1033,8 +1035,8 @@ simply not copy the internal representation, which may then need to be
 regenerated later.
 .PP
 .CS
-typedef ClientData \fBTcl_FSDupInternalRepProc\fR(
-        ClientData \fIclientData\fR);
+typedef void *\fBTcl_FSDupInternalRepProc\fR(
+        void *\fIclientData\fR);
 .CE
 .SS FREEINTERNALREPPROC
 Free the internal representation. This must be implemented if internal
@@ -1043,7 +1045,7 @@ internal representation is generated), but may otherwise be NULL.
 .PP
 .CS
 typedef void \fBTcl_FSFreeInternalRepProc\fR(
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 .CE
 .SS INTERNALTONORMALIZEDPROC
 .PP
@@ -1054,7 +1056,7 @@ representation is the normalized path.
 .PP
 .CS
 typedef Tcl_Obj *\fBTcl_FSInternalToNormalizedProc\fR(
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 .CE
 .SS CREATEINTERNALREPPROC
 .PP
@@ -1065,7 +1067,7 @@ the \fITcl_FSPathInFilesystemProc\fR for this filesystem always
 immediately creates an internal representation for paths it accepts.
 .PP
 .CS
-typedef ClientData \fBTcl_FSCreateInternalRepProc\fR(
+typedef void *\fBTcl_FSCreateInternalRepProc\fR(
        Tcl_Obj *\fIpathPtr\fR);
 .CE
 .SS NORMALIZEPATHPROC
@@ -1079,9 +1081,7 @@ must have a single unique
 string representation. Depending on the filesystem,
 there may be more than one unnormalized string representation which
 refers to that path (e.g.\ a relative path, a path with different
-character case if the filesystem is case insensitive, a path contain a
-reference to a home directory such as
-.QW ~ ,
+character case if the filesystem is case insensitive,
 a path containing symbolic
 links, etc). If the very last component in the path is a symbolic
 link, it should not be converted into the value it points to (but
@@ -1274,7 +1274,7 @@ The \fBTcl_GlobTypeData\fR structure passed in the \fItypes\fR
 parameter contains the following fields:
 .PP
 .CS
-typedef struct Tcl_GlobTypeData {
+typedef struct {
    /* Corresponds to bcdpfls as in 'find -t' */
    int \fItype\fR;
    /* Corresponds to file permissions */
@@ -1643,6 +1643,158 @@ typedef int \fBTcl_FSChdirProc\fR(
 The \fBTcl_FSChdirProc\fR changes the applications current working
 directory to the value specified in \fIpathPtr\fR. The function returns
 -1 on error or 0 on success.
+.SH "REFERENCE COUNT MANAGEMENT"
+.SS "PUBLIC API CALLS"
+.PP
+For all of these functions, \fIpathPtr\fR (including the \fIsrcPathPtr\fR and
+\fIdestPathPtr\fR arguments to \fBTcl_FSCopyFile\fR,
+\fBTcl_FSCopyDirectory\fR, and \fBTcl_FSRenameFile\fR, the \fIfirstPtr\fR and
+\fIsecondPtr\fR arguments to \fBTcl_FSEqualPaths\fR, and the \fIlinkNamePtr\fR
+and \fItoPtr\fR arguments to \fBTcl_FSLink\fR) must not be a zero reference
+count value; references may be retained in internal caches even for
+theoretically read-only operations.  These functions may also manipulate the
+interpreter result (if they take and are given a non-NULL \fIinterp\fR
+argument); you must not count on the interpreter result to hold the reference
+count of any argument value over these calls and should manage your own
+references there. However, references held by the arguments to a Tcl command
+\fIare\fR suitable for reference count management purposes for the duration of
+the implementation of that command.
+.PP
+The \fIerrorPtr\fR argument to \fBTcl_FSCopyDirectory\fR and
+\fBTcl_FSRemoveDirectory\fR is, when an object is set into it at all, set to
+an object with a non-zero reference count that should be passed to
+\fBTcl_DecrRefCount\fR when no longer needed.
+.PP
+\fBTcl_FSListVolumes\fR always returns a zero-reference object, much
+like \fBTcl_NewObj\fR.
+.PP
+\fBTcl_FSLink\fR always returns a non-zero-reference object when it is
+asked to read; you must call \fBTcl_DecrRefCount\fR on the object
+once you no longer need it.
+.PP
+\fBTcl_FSGetCwd\fR always returns a non-zero-reference object; you
+must call \fBTcl_DecrRefCount\fR on the object once you no longer need
+it.
+.PP
+\fBTcl_FSPathSeparator\fR always returns a zero-reference object, much
+like \fBTcl_NewObj\fR.
+.PP
+\fBTcl_FSJoinPath\fR always returns a zero-reference object, much
+like \fBTcl_NewObj\fR. Its \fIlistObj\fR argument can have any reference
+count; it is only read by this function.
+.PP
+\fBTcl_FSSplitPath\fR always returns a zero-reference object, much
+like \fBTcl_NewObj\fR.
+.PP
+\fBTcl_FSGetNormalizedPath\fR returns an object with a non-zero
+reference count where Tcl is the owner. You should increment its
+reference count if you want to retain it, but do not need to if you
+are just using the value immediately.
+.PP
+\fBTcl_FSJoinToPath\fR always returns a zero-reference object, much like
+\fBTcl_NewObj\fR. Its \fIbasePtr\fR argument follows the rules above for
+\fIpathPtr\fR, as do the values in the \fIobjv\fR argument.
+.PP
+\fBTcl_FSGetTranslatedPath\fR returns a non-zero-reference object (or
+NULL in the error case); you must call \fBTcl_DecrRefCount\fR on the
+object once you no longer need it.
+.PP
+\fBTcl_FSNewNativePath\fR always returns a zero-reference object (or
+NULL), much like \fBTcl_NewObj\fR.
+.PP
+\fBTcl_FSFileSystemInfo\fR always returns a zero-reference object (or
+NULL), much like \fBTcl_NewObj\fR.
+.PP
+The \fIobjPtr\fR and \fIobjPtrRef\fR arguments to \fBTcl_FSFileAttrsGet\fR,
+\fBTcl_FSFileAttrsSet\fR and \fBTcl_FSFileAttrStrings\fR are conventional Tcl
+values; the \fIobjPtr\fR argument will be read but not retained, and the
+\fIobjPtrRef\fR argument will have (on success) a zero-reference value written
+into it (as with \fBTcl_NewObj\fR). \fBTcl_FSFileAttrsGet\fR and
+\fBTcl_FSFileAttrsSet\fR may also manipulate the interpreter result.
+.PP
+The \fIresultPtr\fR argument to \fBTcl_FSMatchInDirectory\fR will not have its
+reference count manipulated, but it should have a reference count of no more
+than 1, and should not be the current interpreter result (as the function may
+overwrite that on error).
+.SS "VIRTUAL FILESYSTEM INTERFACE"
+.PP
+For all virtual filesystem implementation functions, any \fIpathPtr\fR
+arguments should not have their reference counts manipulated. If they take an
+\fIinterp\fR argument, they may set an error message in that, but must not
+manipulate the \fIpathPtr\fR afterwards. Aside from that:
+.TP
+\fIinternalToNormalizedProc\fR
+.
+This should return a zero-reference count value, as if allocated with
+\fBTcl_NewObj\fR.
+.TP
+\fInormalizePathProc\fR
+.
+Unlike with other API implementation functions, the \fIpathPtr\fR argument
+here is guaranteed to be an unshared object that should be updated. Its
+reference count should not be modified.
+.TP
+\fIfilesystemPathTypeProc\fR
+.
+The return value (if non-NULL) either has a reference count of zero or needs
+to be maintained (on a per-thread basis) by the filesystem. Tcl will increment
+the reference count of the value if it wishes to retain it.
+.TP
+\fIfilesystemSeparatorProc\fR
+.
+The return value should be a value with reference count of zero.
+.TP
+\fImatchInDirectoryProc\fR
+.
+The \fIresultPtr\fR argument should be assumed to hold a list that can be
+appended to (i.e., that has a reference count no greater than 1). No reference
+to it should be retained.
+.TP
+\fIlinkProc\fR
+.
+If \fItoPtr\fR is NULL, this should return a value with reference count 1 that
+has just been allocated and passed to \fBTcl_IncrRefCount\fR. If \fItoPtr\fR
+is not NULL, it should be returned on success.
+.TP
+\fIlistVolumesProc\fR
+.
+The result value should be a list (if non-NULL); it will have its reference
+count decremented once (with \fBTcl_DecrRefCount\fR) by Tcl once done.
+.TP
+\fIfileAttrStringsProc\fR
+.
+If the result is NULL, the \fIobjPtrRef\fR should have a list value written to
+it; that list will have its reference count both incremented (with
+\fBTcl_IncrRefCount\fR) and decremented (with \fBTcl_DecrRefCount\fR).
+.TP
+\fIfileAttrsGetProc\fR
+.
+The \fIobjPtrRef\fR argument should have (on non-error return) a zero
+reference count value written to it (allocated as if with \fBTcl_NewObj\fR).
+.TP
+\fIfileAttrsSetProc\fR
+.
+The \fIobjPtr\fR argument should either just be read or its reference count
+incremented to retain it.
+.TP
+\fIremoveDirectoryProc\fR
+.
+If an error is being reported, the problem filename reported via
+\fIerrorPtr\fR should be newly allocated (as if with \fBTcl_NewObj\fR) and
+have a reference count of 1 (i.e., have been passed to
+\fBTcl_IncrRefCount\fR).
+.TP
+\fIcopyDirectoryProc\fR
+.
+If an error is being reported, the problem filename reported via
+\fIerrorPtr\fR should be newly allocated (as if with \fBTcl_NewObj\fR) and
+have a reference count of 1 (i.e., have been passed to
+\fBTcl_IncrRefCount\fR).
+.TP
+\fIgetCwdProc\fR
+.
+The result will be passed to \fBTcl_DecrRefCount\fR by the implementation of
+\fBTcl_FSGetCwd\fR after it has been normalized.
 .SH "SEE ALSO"
 cd(n), file(n), filename(n), load(n), open(n), pwd(n), source(n), unload(n)
 .SH KEYWORDS
@@ -13,11 +13,12 @@ Tcl_FindExecutable, Tcl_GetNameOfExecutable \- identify or return the name of th
 .nf
 \fB#include <tcl.h>\fR
 .sp
-void
+const char *
 \fBTcl_FindExecutable\fR(\fIargv0\fR)
 .sp
 const char *
 \fBTcl_GetNameOfExecutable\fR()
+.fi
 .SH ARGUMENTS
 .AS char *argv0
 .AP char *argv0 in
@@ -35,6 +36,9 @@ 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).
+.PP
 On UNIX platforms this procedure is typically invoked as the very
 first thing in the application's main program;  it must be passed
 \fIargv[0]\fR as its argument.  It is important not to change the
@@ -58,6 +62,7 @@ internal full path name of the executable file as computed by
 equivalent to the \fBinfo nameofexecutable\fR command.  NULL
 is returned if the internal full path name has not been
 computed or unknown.
-
+.PP
+\fBTcl_FindExecutable\fR can not be used in stub-enabled extensions.
 .SH KEYWORDS
 binary, executable file
@@ -18,6 +18,7 @@ char *
 .sp
 int
 \fBTcl_Chdir\fR(\fIdirName\fR)
+.fi
 .SH ARGUMENTS
 .AS Tcl_DString *bufferPtr in/out
 .AP Tcl_Interp *interp in
@@ -46,7 +47,7 @@ The format of the path is UTF\-8.
 .PP
 \fBTcl_Chdir\fR changes the applications current working directory to
 the value specified in \fIdirName\fR.  The format of the passed in string
-must be UTF\-8.  The function returns -1 on error or 0 on success.
+must be UTF\-8.  The function returns \-1 on error or 0 on success.

 .SH KEYWORDS
 pwd
@@ -13,6 +13,7 @@ Tcl_GetHostName \- get the name of the local host
 .sp
 const char *
 \fBTcl_GetHostName\fR()
+.fi
 .BE

 .SH DESCRIPTION
@@ -20,6 +20,7 @@ indexPtr\fR)
 int
 \fBTcl_GetIndexFromObjStruct\fR(\fIinterp, objPtr, structTablePtr, offset,
                          msg, flags, indexPtr\fR)
+.fi
 .SH ARGUMENTS
 .AS "const char" *structTablePtr in/out
 .AP Tcl_Interp *interp in
@@ -27,19 +28,22 @@ Interpreter to use for error reporting; if NULL, then no message is
 provided on errors.
 .AP Tcl_Obj *objPtr in/out
 The string value of this value is used to search through \fItablePtr\fR.
-The internal representation is modified to hold the index of the matching
+If the \fBTCL_INDEX_TEMP_TABLE\fR flag is not specified,
+the internal representation is modified to hold the index of the matching
 table entry.
 .AP "const char *const" *tablePtr in
 An array of null-terminated strings.  The end of the array is marked
 by a NULL string pointer.
-Note that references to the \fItablePtr\fR may be retained in the
+Note that, unless the \fBTCL_INDEX_TEMP_TABLE\fR flag is specified,
+references to the \fItablePtr\fR may be retained in the
 internal representation of \fIobjPtr\fR, so this should represent the
 address of a statically-allocated array.
 .AP "const void" *structTablePtr in
 An array of arbitrary type, typically some \fBstruct\fR type.
 The first member of the structure must be a null-terminated string.
 The size of the structure is given by \fIoffset\fR.
-Note that references to the \fIstructTablePtr\fR may be retained in the
+Note that, unless the \fBTCL_INDEX_TEMP_TABLE\fR flag is specified,
+references to the \fIstructTablePtr\fR may be retained in the
 internal representation of \fIobjPtr\fR, so this should represent the
 address of a statically-allocated array of structures.
 .AP int offset in
@@ -50,10 +54,13 @@ Null-terminated string describing what is being looked up, such as
 \fBoption\fR.  This string is included in error messages.
 .AP int flags in
 OR-ed combination of bits providing additional information for
-operation.  The only bit that is currently defined is \fBTCL_EXACT\fR.
-.AP int *indexPtr out
-The index of the string in \fItablePtr\fR that matches the value of
-\fIobjPtr\fR is returned here.
+operation.  The only bits that are currently defined are \fBTCL_EXACT\fR
+, \fBTCL_INDEX_TEMP_TABLE\fR, and \fBTCL_NULL_OK\fR.
+.AP enum|char|short|int|long *indexPtr out
+If not (int *)NULL, the index of the string in \fItablePtr\fR that
+matches the value of \fIobjPtr\fR is returned here. The variable can
+be any integer type, signed or unsigned, char, short, long or
+long long. It can also be an enum.
 .BE
 .SH DESCRIPTION
 .PP
@@ -66,8 +73,8 @@ the strings in \fItablePtr\fR to find a match.  A match occurs if
 \fItablePtr\fR, or if it is a non-empty unique abbreviation
 for exactly one of the strings in \fItablePtr\fR and the
 \fBTCL_EXACT\fR flag was not specified; in either case
-the index of the matching entry is stored at \fI*indexPtr\fR
-and \fBTCL_OK\fR is returned.
+\fBTCL_OK\fR is returned. If \fIindexPtr\fR is not NULL the index
+of the matching entry is stored at \fI*indexPtr\fR.
 .PP
 If there is no matching entry,
 \fBTCL_ERROR\fR is returned and an error message is left in \fIinterp\fR's
@@ -76,15 +83,20 @@ error message to indicate what was being looked up.  For example,
 if \fImsg\fR is \fBoption\fR the error message will have a form like
 .QW "\fBbad option \N'34'firt\N'34': must be first, second, or third\fR" .
 .PP
-If \fBTcl_GetIndexFromObj\fR completes successfully it modifies the
+If the \fBTCL_INDEX_TEMP_TABLE\fR was not specified, when
+\fBTcl_GetIndexFromObj\fR completes successfully it modifies the
 internal representation of \fIobjPtr\fR to hold the address of
 the table and the index of the matching entry.  If \fBTcl_GetIndexFromObj\fR
 is invoked again with the same \fIobjPtr\fR and \fItablePtr\fR
 arguments (e.g. during a reinvocation of a Tcl command), it returns
 the matching index immediately without having to redo the lookup
-operation.  Note: \fBTcl_GetIndexFromObj\fR assumes that the entries
+operation.  Note that \fBTcl_GetIndexFromObj\fR assumes that the entries
 in \fItablePtr\fR are static: they must not change between
-invocations.  If the value of \fIobjPtr\fR is the empty string,
+invocations.  This caching mechanism can be disallowed by specifying
+the \fBTCL_INDEX_TEMP_TABLE\fR flag.
+If the \fBTCL_NULL_OK\fR flag was specified, objPtr is allowed
+to be NULL or the empty string. The resulting index is -1.
+Otherwise, if the value of \fIobjPtr\fR is the empty string,
 \fBTcl_GetIndexFromObj\fR will treat it as a non-matching value
 and return \fBTCL_ERROR\fR.
 .PP
@@ -98,6 +110,12 @@ array of characters at \fItablePtr\fR+\fIoffset\fR bytes, etc.)
 This is particularly useful when processing things like
 \fBTk_ConfigurationSpec\fR, whose string keys are in the same place in
 each of several array elements.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_GetIndexFromObj\fR and \fBTcl_GetIndexFromObjStruct\fR do not modify
+the reference count of their \fIobjPtr\fR arguments; they only read. Note
+however that these functions may set the interpreter result; if that is the
+only place that is holding a reference to the object, it will be deleted.
 .SH "SEE ALSO"
 prefix(n), Tcl_WrongNumArgs(3)
 .SH KEYWORDS
@@ -22,6 +22,10 @@ int
 .sp
 int
 \fBTcl_GetBoolean\fR(\fIinterp, src, intPtr\fR)
+.sp
+int
+\fBTcl_GetBool\fR(\fIinterp, src, flags, charPtr\fR)
+.fi
 .SH ARGUMENTS
 .AS Tcl_Interp *doublePtr out
 .AP Tcl_Interp *interp in
@@ -33,6 +37,12 @@ Points to place to store integer value converted from \fIsrc\fR.
 .AP double *doublePtr out
 Points to place to store double-precision floating-point
 value converted from \fIsrc\fR.
+.AP char *charPtr out
+Points to place to store boolean value (0 or 1) value converted from \fIsrc\fR.
+.AP int flags in
+0 or TCL_NULL_OK. If TCL_NULL_OK
+is used, then the empty string or NULL will result in \fBTcl_GetBool\fR
+return TCL_OK, the *charPtr filled with the value \fB'\exFF'\fR;
 .BE

 .SH DESCRIPTION
@@ -55,15 +65,15 @@ after the optional white space and sign are
 .QW \fB0x\fR
 then \fIsrc\fR is expected to be in hexadecimal form;  otherwise,
 if the first such characters are
+.QW \fB0d\fR
+then \fIsrc\fR is expected to be in decimal form; otherwise,
+if the first such characters are
 .QW \fB0o\fR
 then \fIsrc\fR is expected to be in octal form;  otherwise,
 if the first such characters are
 .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 octal form;  otherwise, \fIsrc\fR is
+is expected to be in binary form;  otherwise, \fIsrc\fR is
 expected to be in decimal form.
 .PP
 \fBTcl_GetDouble\fR expects \fIsrc\fR to consist of a floating-point
@@ -94,6 +104,10 @@ If \fIsrc\fR is any of \fB1\fR, \fBtrue\fR, \fByes\fR, or \fBon\fR,
 then 1 is stored at \fI*intPtr\fR.
 Any of these values may be abbreviated, and upper-case spellings
 are also acceptable.
+.PP
+\fBTcl_GetBool\fR functions almost the same as \fBTcl_GetBoolean\fR,
+but it has an additional parameter \fBflags\fR, which can be used
+to specify whether the empty string or NULL is accepted as valid.

 .SH KEYWORDS
 boolean, conversion, double, floating-point, integer
@@ -15,7 +15,7 @@ Tcl_GetOpenFile \- Return a FILE* for a channel registered in the given interpre
 .sp
 int
 \fBTcl_GetOpenFile\fR(\fIinterp, chanID, write, checkUsage, filePtr\fR)
-.sp
+.fi
 .SH ARGUMENTS
 .AS Tcl_Interp checkUsage out
 .AP Tcl_Interp *interp in
@@ -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 ClientData *filePtr out
+.AP void **filePtr out
 Points to word in which to store pointer to FILE structure for
 the file given by \fIchanID\fR.
 .BE
@@ -18,7 +18,7 @@ Tcl_Channel
 \fBTcl_GetStdChannel\fR(\fItype\fR)
 .sp
 \fBTcl_SetStdChannel\fR(\fIchannel, type\fR)
-.sp
+.fi
 .SH ARGUMENTS
 .AS Tcl_Channel channel
 .AP int type in
@@ -18,6 +18,7 @@ Tcl_GetTime, Tcl_SetTimeProc, Tcl_QueryTimeProc \- get date and time
 \fBTcl_SetTimeProc\fR(\fIgetProc, scaleProc, clientData\fR)
 .sp
 \fBTcl_QueryTimeProc\fR(\fIgetProcPtr, scaleProcPtr, clientDataPtr\fR)
+.fi
 .SH ARGUMENTS
 .AS Tcl_GetTimeProc *getProc in
 .AP Tcl_Time *timePtr out
@@ -27,13 +28,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 ClientData clientData in
+.AP void *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 ClientData *clientDataPtr out
+.AP void **clientDataPtr out
 Pointer to place the currently registered pass-through value into.
 .BE
 .SH DESCRIPTION
@@ -43,8 +44,8 @@ The \fBTcl_GetTime\fR function retrieves the current time as a
 structure has the following definition:
 .PP
 .CS
-typedef struct Tcl_Time {
-    long \fIsec\fR;
+typedef struct {
+    long long \fIsec\fR;
    long \fIusec\fR;
 } \fBTcl_Time\fR;
 .CE
@@ -52,7 +53,7 @@ typedef struct Tcl_Time {
 On return, the \fIsec\fR member of the structure is filled in with the
 number of seconds that have elapsed since the \fIepoch:\fR the epoch
 is the point in time of 00:00 UTC, 1 January 1970.  This number does
-\fInot\fR count leap seconds \- an interval of one day advances it by
+\fInot\fR count leap seconds; an interval of one day advances it by
 86400 seconds regardless of whether a leap second has been inserted.
 .PP
 The \fIusec\fR member of the structure is filled in with the number of
@@ -83,10 +84,10 @@ The signatures of the handler functions are as follows:
 .CS
 typedef void \fBTcl_GetTimeProc\fR(
        Tcl_Time *\fItimebuf\fR,
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 typedef void \fBTcl_ScaleTimeProc\fR(
        Tcl_Time *\fItimebuf\fR,
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 .CE
 .PP
 The \fItimebuf\fR fields contain the time to manipulate, and the
@@ -14,15 +14,15 @@ Tcl_GetVersion \- get the version of the library at runtime
 \fB#include <tcl.h>\fR
 .sp
 \fBTcl_GetVersion\fR(\fImajor, minor, patchLevel, type\fR)
+.fi
 .SH ARGUMENTS
-.AS Tcl_ReleaseType *patchLevel out
 .AP int *major out
 Major version number of the Tcl library.
 .AP int *minor out
 Minor version number of the Tcl library.
 .AP int *patchLevel out
 The patch level of the Tcl library (or alpha or beta number).
-.AP Tcl_ReleaseType *type out
+.AP int *type out
 The type of release, also indicates the type of patch level. Can be
 one of \fBTCL_ALPHA_RELEASE\fR, \fBTCL_BETA_RELEASE\fR, or
 \fBTCL_FINAL_RELEASE\fR.
@@ -30,7 +30,7 @@ Tcl_HashEntry *
 Tcl_HashEntry *
 \fBTcl_FindHashEntry\fR(\fItablePtr, key\fR)
 .sp
-ClientData
+void *
 \fBTcl_GetHashValue\fR(\fIentryPtr\fR)
 .sp
 \fBTcl_SetHashValue\fR(\fIentryPtr, value\fR)
@@ -46,6 +46,7 @@ Tcl_HashEntry *
 .sp
 char *
 \fBTcl_HashStats\fR(\fItablePtr\fR)
+.fi
 .SH ARGUMENTS
 .AS "const Tcl_HashKeyType" *searchPtr out
 .AP Tcl_HashTable *tablePtr in
@@ -66,9 +67,8 @@ 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 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 void *value in
+New value to assign to hash table entry.
 .AP Tcl_HashSearch *searchPtr in
 Pointer to record to use to keep track of progress in enumerating
 all the entries in a hash table.
@@ -186,11 +186,6 @@ 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
@@ -229,7 +224,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 \fBckfree\fR.
+by passing it to \fBTcl_Free\fR.
 .PP
 The header file \fBtcl.h\fR defines the actual data structures
 used to implement hash tables.
@@ -247,7 +242,7 @@ calling \fBTcl_InitCustomHashTable\fR. The \fBTcl_HashKeyType\fR structure is
 defined as follows:
 .PP
 .CS
-typedef struct Tcl_HashKeyType {
+typedef struct {
    int \fIversion\fR;
    int \fIflags\fR;
    Tcl_HashKeyProc *\fIhashKeyProc\fR;
@@ -281,7 +276,7 @@ The \fIhashKeyProc\fR member contains the address of a function called to
 calculate a hash value for the key.
 .PP
 .CS
-typedef unsigned int \fBTcl_HashKeyProc\fR(
+typedef TCL_HASH_TYPE \fBTcl_HashKeyProc\fR(
        Tcl_HashTable *\fItablePtr\fR,
        void *\fIkeyPtr\fR);
 .CE
@@ -330,5 +325,19 @@ typedef void \fBTcl_FreeHashEntryProc\fR(
 If this is NULL then \fBTcl_Free\fR is used to free the space for the entry.
 Tcl_Obj* keys use this function to decrement the reference count on the
 value.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+When a hash table is created with \fBTcl_InitCustomHashTable\fR, the
+\fBTcl_CreateHashEntry\fR function will increment the reference count of its
+\fIkey\fR argument when it creates a key (but not if there is an existing
+matching key). The reference count of the key will be decremented when the
+corresponding hash entry is deleted, whether with \fBTcl_DeleteHashEntry\fR or
+with \fBTcl_DeleteHashTable\fR. The \fBTcl_GetHashKey\fR function will return
+the key without further modifying its reference count.
+.PP
+Custom hash tables that use a Tcl_Obj* as key will generally need to do
+something similar in their \fIallocEntryProc\fR.
+.SH "SEE ALSO"
+Dict(3)
 .SH KEYWORDS
 hash table, key, lookup, search, value
@@ -2,7 +2,7 @@
 '\" Copyright (c) 1998-2000 Scriptics Corporation.
 '\" All rights reserved.
 '\"
-.TH Tcl_Init 3 8.0 Tcl "Tcl Library Procedures"
+.TH Tcl_Init 3 9.0 Tcl "Tcl Library Procedures"
 .so man.macros
 .BS
 .SH NAME
@@ -13,10 +13,16 @@ Tcl_Init \- find and source initialization script
 .sp
 int
 \fBTcl_Init\fR(\fIinterp\fR)
+.sp
+const char *
+\fBTcl_SetPreInitScript\fR(\fIscriptPtr\fR)
+.fi
 .SH ARGUMENTS
 .AS Tcl_Interp *interp
 .AP Tcl_Interp *interp in
 Interpreter to initialize.
+.AP "const char" *scriptPtr in
+Address of the initialization script.
 .BE

 .SH DESCRIPTION
@@ -26,9 +32,19 @@ Interpreter to initialize.
 path.
 .PP
 \fBTcl_Init\fR is typically called from \fBTcl_AppInit\fR procedures.
-
+.PP
+\fBTcl_SetPreInitScript\fR registers the pre-initialization script and
+returns the former (now replaced) script pointer.
+A value of \fINULL\fR may be passed to not register any script.
+The pre-initialization script is executed by \fBTcl_Init\fR before accessing
+the file system. The purpose is to typically prepare a custom file system
+(like an embedded zip-file) to be activated before the search.
+.PP
+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
-
 .SH KEYWORDS
 application, initialization, interpreter
@@ -22,7 +22,7 @@ const char *
 Tcl interpreter handle.
 .AP "const char" *version in
 A version string, indicating which minimal version of Tcl is accepted.
-Normally just \fB"8.6"\fR. Or \fB"8.6-"\fR if both 8.6 and 9.0 are accepted.
+Normally just \fB"9.0"\fR. Or \fB"8.6-"\fR if both 8.6 and 9.0 are accepted.
 .AP int exact in
 1 means that only the particular version specified by
 \fIversion\fR is accepted.
@@ -66,9 +66,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 8.6 ABI on Unix platforms,
-the library name is \fIlibtclstub8.6.a\fR; on Windows platforms, the
-library name is \fItclstub86.lib\fR.
+Tcl library.  For example, to use the Tcl 9.0 ABI on Unix platforms,
+the library name is \fIlibtclstub.a\fR; on Windows platforms, the
+library name is \fItclstub.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
@@ -0,0 +1,36 @@
+'\"
+'\" Copyright (c) 2018 Tcl Core Team
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.so man.macros
+.TH Tcl_InitSubsystems 3 9.0 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_InitSubsystems \- initialize the Tcl library.
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+const char *
+\fBTcl_InitSubsystems\fR()
+.fi
+.BE
+.SH DESCRIPTION
+.PP
+The \fBTcl_InitSubsystems\fR procedure initializes the Tcl
+library. This procedure is typically invoked as the very
+first thing in the application's main program.
+.PP
+The result of \fBTcl_InitSubsystems\fR is the full Tcl version with
+build information (e.g., \fB9.0.0+abcdef...abcdef.gcc-1002\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,
+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.
+.SH KEYWORDS
+binary, executable file
@@ -8,7 +8,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, Tcl_GetIntFromObj, Tcl_GetLongFromObj, Tcl_GetWideIntFromObj, Tcl_NewBignumObj, Tcl_SetBignumObj, Tcl_GetBignumFromObj, Tcl_TakeBignumFromObj \- manipulate Tcl values as integers
+Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, Tcl_NewWideUIntObj, Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, Tcl_SetWideUIntObj, Tcl_GetIntFromObj, Tcl_GetIntForIndex, Tcl_GetLongFromObj, Tcl_GetSizeIntFromObj, Tcl_GetWideIntFromObj, Tcl_GetWideUIntFromObj, Tcl_NewBignumObj, Tcl_SetBignumObj, Tcl_GetBignumFromObj, Tcl_TakeBignumFromObj \- manipulate Tcl values as integers
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -22,21 +22,35 @@ Tcl_Obj *
 Tcl_Obj *
 \fBTcl_NewWideIntObj\fR(\fIwideValue\fR)
 .sp
+Tcl_Obj *
+\fBTcl_NewWideUIntObj\fR(\fIuwideValue\fR)
+.sp
 \fBTcl_SetIntObj\fR(\fIobjPtr, intValue\fR)
 .sp
 \fBTcl_SetLongObj\fR(\fIobjPtr, longValue\fR)
 .sp
 \fBTcl_SetWideIntObj\fR(\fIobjPtr, wideValue\fR)
 .sp
+\fBTcl_SetWideUIntObj\fR(\fIobjPtr, uwideValue\fR)
+.sp
 int
 \fBTcl_GetIntFromObj\fR(\fIinterp, objPtr, intPtr\fR)
 .sp
 int
+\fBTcl_GetIntForIndex\fR(\fIinterp, objPtr, endValue, indexPtr\fR)
+.sp
+int
 \fBTcl_GetLongFromObj\fR(\fIinterp, objPtr, longPtr\fR)
 .sp
 int
 \fBTcl_GetWideIntFromObj\fR(\fIinterp, objPtr, widePtr\fR)
 .sp
+int
+\fBTcl_GetWideUIntFromObj\fR(\fIinterp, objPtr, uwidePtr\fR)
+.sp
+int
+\fBTcl_GetSizeIntFromObj\fR(\fIinterp, objPtr, sizePtr\fR)
+.sp
 .sp
 \fB#include <tclTomMath.h>\fR
 .sp
@@ -53,16 +67,22 @@ int
 .sp
 int
 \fBTcl_InitBignumFromDouble\fR(\fIinterp, doubleValue, bigValue\fR)
+.fi
 .SH ARGUMENTS
 .AS Tcl_WideInt doubleValue in/out
+.AP Tcl_Size endValue in
+\fBTcl_GetIntForIndex\fR will return this when the input value is "end".
 .AP int intValue in
 Integer value used to initialize or set a Tcl value.
 .AP long longValue in
 Long integer value used to initialize or set a Tcl value.
 .AP Tcl_WideInt wideValue in
 Wide integer value used to initialize or set a Tcl value.
+.AP Tcl_WideUInt uwideValue in
+Unsigned wide integer value used to initialize or set a Tcl value.
 .AP Tcl_Obj *objPtr in/out
 For \fBTcl_SetIntObj\fR, \fBTcl_SetLongObj\fR, \fBTcl_SetWideIntObj\fR,
+\fBTcl_SetWideUIntObj\fR,
 and \fBTcl_SetBignumObj\fR, this points to the value in which to store an
 integral value.  For \fBTcl_GetIntFromObj\fR, \fBTcl_GetLongFromObj\fR,
 \fBTcl_GetWideIntFromObj\fR, \fBTcl_GetBignumFromObj\fR, and
@@ -75,8 +95,14 @@ 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 Tcl_Size *indexPtr out
+Points to place to store the Tcl_Size value retrieved from \fIobjPtr\fR.
 .AP Tcl_WideInt *widePtr out
 Points to place to store the wide integer value retrieved from \fIobjPtr\fR.
+.AP Tcl_WideUInt *uwidePtr out
+Points to place to store the unsigned wide integer value retrieved from \fIobjPtr\fR.
+.AP Tcl_Size *sizePtr out
+Points to place to store the \fBTcl_Size\fR integer value retrieved from \fIobjPtr\fR.
 .AP mp_int *bigValue in/out
 Points to a multi-precision integer structure declared by the LibTomMath
 library.
@@ -97,26 +123,42 @@ are provided by the C language standard.  The \fBTcl_WideInt\fR type is a
 typedef defined to be whatever signed integral type covers at least the
 64-bit integer range (-9223372036854775808 to 9223372036854775807).  Depending
 on the platform and the C compiler, the actual type might be
-\fBlong int\fR, \fBlong long int\fR, \fB__int64\fR, or something else.
+\fBlong long int\fR, or something else.
+The \fBTcl_Size\fR typedef is a signed integer type
+capable of holding the maximum permitted lengths of Tcl values like
+strings and lists. Correspondingly, the preprocessor constant
+\fBTCL_SIZE_MAX\fR defines the maximum value that can be stored
+in a variable of this type.
 The \fBmp_int\fR type is a multiple-precision integer type defined
 by the LibTomMath multiple-precision integer library.
 .PP
 The \fBTcl_NewIntObj\fR, \fBTcl_NewLongObj\fR, \fBTcl_NewWideIntObj\fR,
-and \fBTcl_NewBignumObj\fR routines each create and return a new
-Tcl value initialized to the integral value of the argument.  The
-returned Tcl value is unshared.
+\fBTcl_NewWideUIntObj\fR, and \fBTcl_NewBignumObj\fR
+routines each create and return a new Tcl value initialized to the
+integral value of the argument.  The returned Tcl value is unshared.
 .PP
 The \fBTcl_SetIntObj\fR, \fBTcl_SetLongObj\fR, \fBTcl_SetWideIntObj\fR,
-and \fBTcl_SetBignumObj\fR routines each set the value of an existing
-Tcl value pointed to by \fIobjPtr\fR to the integral value provided
-by the other argument.  The \fIobjPtr\fR argument must point to an
-unshared Tcl value.  Any attempt to set the value of a shared Tcl value
-violates Tcl's copy-on-write policy.  Any existing string representation
-or internal representation in the unshared Tcl value will be freed
-as a consequence of setting the new value.
+\fBTcl_SetWideUIntObj\fR, and \fBTcl_SetBignumObj\fR
+routines each set the value of an existing Tcl value pointed to by \fIobjPtr\fR
+to the integral value provided by the other argument.  The \fIobjPtr\fR
+argument must point to an unshared Tcl value.  Any attempt to set the
+value of a shared Tcl value violates Tcl's copy-on-write policy.  Any
+existing string representation or internal representation in the unshared
+Tcl value will be freed as a consequence of setting the new value.
+.PP
+The \fBTcl_GetIntForIndex\fR routine attempts to retrieve an index
+value from the Tcl value \fIobjPtr\fR.  If the attempt succeeds,
+then \fBTCL_OK\fR is returned, and the value is written to the
+storage provided by the caller.  The attempt might fail if
+\fIobjPtr\fR does not hold an index value.  If the attempt fails,
+then \fBTCL_ERROR\fR is returned, and if \fIinterp\fR is non-NULL,
+an error message is left in \fIinterp\fR.  The \fBTcl_ObjType\fR
+of \fIobjPtr\fR may be changed to make subsequent calls to the
+same routine more efficient.
 .PP
 The \fBTcl_GetIntFromObj\fR, \fBTcl_GetLongFromObj\fR,
-\fBTcl_GetWideIntFromObj\fR, \fBTcl_GetBignumFromObj\fR, and
+\fBTcl_GetWideIntFromObj\fR, \fBTcl_GetSizeIntFromObj\fR,
+\fBTcl_GetBignumFromObj\fR, and
 \fBTcl_TakeBignumFromObj\fR routines attempt to retrieve an integral
 value of the appropriate type from the Tcl value \fIobjPtr\fR.  If the
 attempt succeeds, then \fBTCL_OK\fR is returned, and the value is
@@ -145,6 +187,28 @@ If anything later in the caller requires
 The \fBTcl_InitBignumFromDouble\fR routine is a utility procedure
 that extracts the integer part of \fIdoubleValue\fR and stores that
 integer value in the \fBmp_int\fR value \fIbigValue\fR.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_NewIntObj\fR, \fBTcl_NewLongObj\fR, \fBTcl_NewWideIntObj\fR, and
+\fBTcl_NewBignumObj\fR always return a zero-reference object, much like
+\fBTcl_NewObj\fR.
+.PP
+\fBTcl_SetIntObj\fR, \fBTcl_SetLongObj\fR, \fBTcl_SetWideIntObj\fR, and
+\fBTcl_SetBignumObj\fR do not modify the reference count of their \fIobjPtr\fR
+arguments, but do require that the object be unshared.
+.PP
+\fBTcl_GetIntFromObj\fR, \fBTcl_GetIntForIndex\fR, \fBTcl_GetLongFromObj\fR,
+\fBTcl_GetWideIntFromObj\fR, \fBTcl_GetSizeIntFromObj\fR,
+\fBTcl_GetBignumFromObj\fR, and
+\fBTcl_TakeBignumFromObj\fR do not modify the reference count of their
+\fIobjPtr\fR arguments; they only read. Note however that this function may
+set the interpreter result; if that is the only place that is holding a
+reference to the object, it will be deleted. Also note that if
+\fBTcl_TakeBignumFromObj\fR is given an unshared value, the value of that
+object may be modified; it is intended to be used when the value is
+.QW consumed
+by the operation at this point.
+
 .SH "SEE ALSO"
 Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
 .SH KEYWORDS
@@ -1,134 +0,0 @@
-'\"
-'\" 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 7.5 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;
-    Tcl_FreeProc *\fIfreeProc\fR;
-    int \fIerrorLine\fR;
-} \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 Tcl_Interp
-structure.  Callers of \fBTcl_CreateInterp\fR should use this pointer
-as an opaque token, suitable for nothing other than passing back to
-other routines in the Tcl interface.  Accessing fields directly through
-the pointer as described below is no longer supported.  The supported
-public routines \fBTcl_SetResult\fR, \fBTcl_GetResult\fR,
-\fBTcl_SetErrorLine\fR, \fBTcl_GetErrorLine\fR must be used instead.
-.PP
-For legacy programs and extensions no longer being maintained, compiles
-against the Tcl 8.6 header files are only possible with the compiler
-directives
-.CS
-#define USE_INTERP_RESULT
-.CE
-and/or
-.CS
-#define USE_INTERP_ERRORLINE
-.CE
-depending on which fields of the \fBTcl_Interp\fR struct are accessed.
-These directives may be embedded in code or supplied via compiler options.
-.PP
-The \fIresult\fR and \fIfreeProc\fR fields are used to return
-results or error messages from commands.
-This information is returned by command procedures back to \fBTcl_Eval\fR,
-and by \fBTcl_Eval\fR back to its callers.
-The \fIresult\fR field points to the string that represents the
-result or error message, and the \fIfreeProc\fR field tells how
-to dispose of the storage for the string when it is not needed anymore.
-The easiest way for command procedures to manipulate these
-fields is to call procedures like \fBTcl_SetResult\fR
-or \fBTcl_AppendResult\fR;  they
-will hide all the details of managing the fields.
-The description below is for those procedures that manipulate the
-fields directly.
-.PP
-Whenever a command procedure returns, it must ensure
-that the \fIresult\fR field of its interpreter points to the string
-being returned by the command.
-The \fIresult\fR field must always point to a valid string.
-If a command wishes to return no result then \fIinterp->result\fR
-should point to an empty string.
-Normally, results are assumed to be statically allocated,
-which means that the contents will not change before the next time
-\fBTcl_Eval\fR is called or some other command procedure is invoked.
-In this case, the \fIfreeProc\fR field must be zero.
-Alternatively, a command procedure may dynamically
-allocate its return value (e.g. using \fBTcl_Alloc\fR)
-and store a pointer to it in \fIinterp->result\fR.
-In this case, the command procedure must also set \fIinterp->freeProc\fR
-to the address of a procedure that can free the value, or \fBTCL_DYNAMIC\fR
-if the storage was allocated directly by Tcl or by a call to
-\fBTcl_Alloc\fR.
-If \fIinterp->freeProc\fR is non-zero, then Tcl will call \fIfreeProc\fR
-to free the space pointed to by \fIinterp->result\fR before it
-invokes the next command.
-If a client procedure overwrites \fIinterp->result\fR when
-\fIinterp->freeProc\fR is non-zero, then it is responsible for calling
-\fIfreeProc\fR to free the old \fIinterp->result\fR (the \fBTcl_FreeResult\fR
-macro should be used for this purpose).
-.PP
-\fIFreeProc\fR should have arguments and result that match the
-\fBTcl_FreeProc\fR declaration above:  it receives a single
-argument which is a pointer to the result value to free.
-In most applications \fBTCL_DYNAMIC\fR is the only non-zero value ever
-used for \fIfreeProc\fR.
-However, an application may store a different procedure address
-in \fIfreeProc\fR in order to use an alternate memory allocator
-or in order to do other cleanup when the result memory is freed.
-.PP
-As part of processing each command, \fBTcl_Eval\fR initializes
-\fIinterp->result\fR
-and \fIinterp->freeProc\fR just before calling the command procedure for
-the command.  The \fIfreeProc\fR field will be initialized to zero,
-and \fIinterp->result\fR will point to an empty string.  Commands that
-do not return any value can simply leave the fields alone.
-Furthermore, the empty string pointed to by \fIresult\fR is actually
-part of an array of \fBTCL_RESULT_SIZE\fR characters (approximately 200).
-If a command wishes to return a short string, it can simply copy
-it to the area pointed to by \fIinterp->result\fR.  Or, it can use
-the sprintf procedure to generate a short result string at the location
-pointed to by \fIinterp->result\fR.
-.PP
-It is a general convention in Tcl-based applications that the result
-of an interpreter is normally in the initialized state described
-in the previous paragraph.
-Procedures that manipulate an interpreter's result (e.g. by
-returning an error) will generally assume that the result
-has been initialized when the procedure is called.
-If such a procedure is to be called after the result has been
-changed, then \fBTcl_ResetResult\fR should be called first to
-reset the result to its initialized state.  The direct use of
-\fIinterp->result\fR is strongly deprecated (see \fBTcl_SetResult\fR).
-.PP
-The \fIerrorLine\fR
-field is valid only after \fBTcl_Eval\fR returns
-a \fBTCL_ERROR\fR return code.  In this situation the \fIerrorLine\fR
-field identifies the line number of the command being executed when
-the error occurred.  The line numbers are relative to the command
-being executed:  1 means the first line of the command passed to
-\fBTcl_Eval\fR, 2 means the second line, and so on.
-The \fIerrorLine\fR field is typically used in conjunction with
-\fBTcl_AddErrorInfo\fR to report information about where an error
-occurred.
-\fIErrorLine\fR should not normally be modified except by \fBTcl_Eval\fR.
-
-.SH KEYWORDS
-free, initialized, interpreter, malloc, result
@@ -28,35 +28,28 @@ int
 int
 \fBTcl_LimitTypeEnabled\fR(\fIinterp, type\fR)
 .sp
-void
 \fBTcl_LimitTypeSet\fR(\fIinterp, type\fR)
 .sp
-void
 \fBTcl_LimitTypeReset\fR(\fIinterp, type\fR)
 .sp
 int
 \fBTcl_LimitGetCommands\fR(\fIinterp\fR)
 .sp
-void
 \fBTcl_LimitSetCommands\fR(\fIinterp, commandLimit\fR)
 .sp
-void
 \fBTcl_LimitGetTime\fR(\fIinterp, timeLimitPtr\fR)
 .sp
-void
 \fBTcl_LimitSetTime\fR(\fIinterp, timeLimitPtr\fR)
 .sp
 int
 \fBTcl_LimitGetGranularity\fR(\fIinterp, type\fR)
 .sp
-void
 \fBTcl_LimitSetGranularity\fR(\fIinterp, type, granularity\fR)
 .sp
-void
 \fBTcl_LimitAddHandler\fR(\fIinterp, type, handlerProc, clientData, deleteProc\fR)
 .sp
-void
 \fBTcl_LimitRemoveHandler\fR(\fIinterp, type, handlerProc, clientData\fR)
+.fi
 .SH ARGUMENTS
 .AS Tcl_LimitHandlerDeleteProc commandLimit in/out
 .AP Tcl_Interp *interp in
@@ -65,7 +58,7 @@ its limits checked.
 .AP int type in
 The type of limit that the operation refers to.  This must be either
 \fBTCL_LIMIT_COMMANDS\fR or \fBTCL_LIMIT_TIME\fR.
-.AP int commandLimit in
+.AP Tcl_Size commandLimit in
 The maximum number of commands (as reported by \fBinfo cmdcount\fR)
 that may be executed in the interpreter.
 .AP Tcl_Time *timeLimitPtr in/out
@@ -83,7 +76,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 ClientData clientData in
+.AP void *clientData in
 Arbitrary pointer-sized word used to pass some context to the
 \fIhandlerProc\fR function.
 .AP Tcl_LimitHandlerDeleteProc *deleteProc in
@@ -162,7 +155,7 @@ following prototype:
 .PP
 .CS
 typedef void \fBTcl_LimitHandlerProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
        Tcl_Interp *\fIinterp\fR);
 .CE
 .PP
@@ -179,7 +172,7 @@ following prototype:
 .PP
 .CS
 typedef void \fBTcl_LimitHandlerDeleteProc\fR(
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 .CE
 .PP
 A limit handler may be deleted using \fBTcl_LimitRemoveHandler\fR; the
@@ -9,7 +9,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar \- link Tcl variable to C variable
+Tcl_LinkArray, Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar \- link Tcl variable to C variable
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -17,27 +17,53 @@ Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar \- link Tcl variable to C variab
 int
 \fBTcl_LinkVar\fR(\fIinterp, varName, addr, type\fR)
 .sp
+.VS TIP312
+int
+\fBTcl_LinkArray\fR(\fIinterp, varName, addr, type, size\fR)
+.VE TIP312
+.sp
 \fBTcl_UnlinkVar\fR(\fIinterp, varName\fR)
 .sp
 \fBTcl_UpdateLinkedVar\fR(\fIinterp, varName\fR)
+.fi
 .SH ARGUMENTS
-.AS Tcl_Interp writable
+.AS Tcl_Interp varName in
 .AP Tcl_Interp *interp in
 Interpreter that contains \fIvarName\fR.
 Also used by \fBTcl_LinkVar\fR to return error messages.
 .AP "const char" *varName in
 Name of global variable.
-.AP char *addr in
+.AP void *addr in
 Address of C variable that is to be linked to \fIvarName\fR.
+.sp
+.VS TIP312
+In \fBTcl_LinkArray\fR, may be NULL to tell Tcl to create the storage
+for the array in the variable.
+.VE TIP312
 .AP int type in
-Type of C variable.  Must be one of \fBTCL_LINK_INT\fR,
+Type of C variable for \fBTcl_LinkVar\fR or type of array element for
+\fBTcl_LinkArray\fR.  Must be one of \fBTCL_LINK_INT\fR,
 \fBTCL_LINK_UINT\fR, \fBTCL_LINK_CHAR\fR, \fBTCL_LINK_UCHAR\fR,
 \fBTCL_LINK_SHORT\fR, \fBTCL_LINK_USHORT\fR, \fBTCL_LINK_LONG\fR,
 \fBTCL_LINK_ULONG\fR, \fBTCL_LINK_WIDE_INT\fR,
-\fBTCL_LINK_WIDE_UINT\fR, \fBTCL_LINK_FLOAT\fR,
-\fBTCL_LINK_DOUBLE\fR, \fBTCL_LINK_BOOLEAN\fR, or
-\fBTCL_LINK_STRING\fR, optionally OR'ed with \fBTCL_LINK_READ_ONLY\fR
-to make Tcl variable read-only.
+\fBTCL_LINK_WIDE_UINT\fR, \fBTCL_LINK_FLOAT\fR, \fBTCL_LINK_DOUBLE\fR,
+\fBTCL_LINK_BOOLEAN\fR, or one of the extra ones listed below.
+.sp
+In \fBTcl_LinkVar\fR, the additional linked type \fBTCL_LINK_STRING\fR may be
+used.
+.sp
+.VS TIP312
+In \fBTcl_LinkArray\fR, the additional linked types \fBTCL_LINK_CHARS\fR and
+\fBTCL_LINK_BINARY\fR may be used.
+.VE TIP312
+.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 Tcl_Size size in
+.VS TIP312
+The number of elements in the C array. Must be greater than zero.
+.VE TIP312
 .BE
 .SH DESCRIPTION
 .PP
@@ -52,130 +78,177 @@ while setting up the link (e.g. because \fIvarName\fR is the
 name of array) then \fBTCL_ERROR\fR is returned and the interpreter's result
 contains an error message.
 .PP
+.VS TIP312
+\fBTcl_LinkArray\fR is similar, but for arrays of fixed size (given by
+the \fIsize\fR argument). When asked to allocate the backing C array
+storage (via the \fIaddr\fR argument being NULL), it writes the
+address that it allocated to the Tcl interpreter result.
+.VE TIP312
+.PP
 The \fItype\fR argument specifies the type of the C variable,
+or the type of the elements of the C array,
 and must have one of the following values, optionally OR'ed with
 \fBTCL_LINK_READ_ONLY\fR:
 .TP
 \fBTCL_LINK_INT\fR
-The C variable is of type \fBint\fR.
+.
+The C variable, or each element of the C array, is of type \fBint\fR.
 Any value written into the Tcl variable must have a proper integer
 form acceptable to \fBTcl_GetIntFromObj\fR;  attempts to write
 non-integer values into \fIvarName\fR will be rejected with
 Tcl errors. Incomplete integer representations (like the empty
-string, '+', '-' or the hex/octal/binary prefix) are accepted
+string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted
 as if they are valid too.
 .TP
 \fBTCL_LINK_UINT\fR
-The C variable is of type \fBunsigned int\fR.
+.
+The C variable, or each element of the C array, is of type \fBunsigned int\fR.
 Any value written into the Tcl variable must have a proper unsigned
 integer form acceptable to \fBTcl_GetWideIntFromObj\fR and in the
 platform's defined range for the \fBunsigned int\fR type; attempts to
 write non-integer values (or values outside the range) into
 \fIvarName\fR will be rejected with Tcl errors. Incomplete integer
-representations (like the empty string, '+', '-' or the hex/octal/binary
+representations (like the empty string, '+', '-' or the hex/octal/decimal/binary
 prefix) are accepted as if they are valid too.
 .TP
 \fBTCL_LINK_CHAR\fR
-The C variable is of type \fBchar\fR.
+.
+The C variable, or each element of the C array, is of type \fBchar\fR.
 Any value written into the Tcl variable must have a proper integer
 form acceptable to \fBTcl_GetIntFromObj\fR and be in the range of the
 \fBchar\fR datatype; attempts to write non-integer or out-of-range
 values into \fIvarName\fR will be rejected with Tcl errors. Incomplete
 integer representations (like the empty string, '+', '-' or the
-hex/octal/binary prefix) are accepted as if they are valid too.
+hex/octal/decimal/binary prefix) are accepted as if they are valid too.
+.RS
+.PP
+.VS TIP312
+If using an array of these, consider using \fBTCL_LINK_CHARS\fR instead.
+.VE TIP312
+.RE
+.TP
+\fBTCL_LINK_CHARS\fR
+.VS TIP312
+The C array is of type \fBchar *\fR and is mapped into Tcl as a string.
+Any value written into the Tcl variable must have the same length as
+the underlying storage. Only supported with \fBTcl_LinkArray\fR.
+.VE TIP312
 .TP
 \fBTCL_LINK_UCHAR\fR
-The C variable is of type \fBunsigned char\fR.
+.
+The C variable, or each element of the C array, is of type \fBunsigned char\fR.
 Any value written into the Tcl variable must have a proper unsigned
 integer form acceptable to \fBTcl_GetIntFromObj\fR and in the
 platform's defined range for the \fBunsigned char\fR type; attempts to
 write non-integer values (or values outside the range) into
 \fIvarName\fR will be rejected with Tcl errors. Incomplete integer
-representations (like the empty string, '+', '-' or the hex/octal/binary
+representations (like the empty string, '+', '-' or the hex/octal/decimal/binary
 prefix) are accepted as if they are valid too.
+.RS
+.PP
+.VS TIP312
+If using an array of these, consider using \fBTCL_LINK_BINARY\fR instead.
+.VE TIP312
+.RE
+.TP
+\fBTCL_LINK_BINARY\fR
+.VS TIP312
+The C array is of type \fBunsigned char *\fR and is mapped into Tcl
+as a bytearray.
+Any value written into the Tcl variable must have the same length as
+the underlying storage. Only supported with \fBTcl_LinkArray\fR.
+.VE TIP312
 .TP
 \fBTCL_LINK_SHORT\fR
-The C variable is of type \fBshort\fR.
+.
+The C variable, or each element of the C array, is of type \fBshort\fR.
 Any value written into the Tcl variable must have a proper integer
 form acceptable to \fBTcl_GetIntFromObj\fR and be in the range of the
 \fBshort\fR datatype; attempts to write non-integer or out-of-range
 values into \fIvarName\fR will be rejected with Tcl errors. Incomplete
 integer representations (like the empty string, '+', '-' or the
-hex/octal/binary prefix) are accepted as if they are valid too.
+hex/octal/decimal/binary prefix) are accepted as if they are valid too.
 .TP
 \fBTCL_LINK_USHORT\fR
-The C variable is of type \fBunsigned short\fR.
+.
+The C variable, or each element of the C array, is of type \fBunsigned short\fR.
 Any value written into the Tcl variable must have a proper unsigned
 integer form acceptable to \fBTcl_GetIntFromObj\fR and in the
 platform's defined range for the \fBunsigned short\fR type; attempts to
 write non-integer values (or values outside the range) into
 \fIvarName\fR will be rejected with Tcl errors. Incomplete integer
-representations (like the empty string, '+', '-' or the hex/octal/binary
+representations (like the empty string, '+', '-' or the hex/octal/decimal/binary
 prefix) are accepted as if they are valid too.
 .TP
 \fBTCL_LINK_LONG\fR
-The C variable is of type \fBlong\fR.
+.
+The C variable, or each element of the C array, is of type \fBlong\fR.
 Any value written into the Tcl variable must have a proper integer
 form acceptable to \fBTcl_GetLongFromObj\fR; attempts to write
 non-integer or out-of-range
 values into \fIvarName\fR will be rejected with Tcl errors. Incomplete
 integer representations (like the empty string, '+', '-' or the
-hex/octal/binary prefix) are accepted as if they are valid too.
+hex/octal/decimal/binary prefix) are accepted as if they are valid too.
 .TP
 \fBTCL_LINK_ULONG\fR
-The C variable is of type \fBunsigned long\fR.
+.
+The C variable, or each element of the C array, is of type \fBunsigned long\fR.
 Any value written into the Tcl variable must have a proper unsigned
 integer form acceptable to \fBTcl_GetWideIntFromObj\fR and in the
 platform's defined range for the \fBunsigned long\fR type; attempts to
 write non-integer values (or values outside the range) into
 \fIvarName\fR will be rejected with Tcl errors. Incomplete integer
-representations (like the empty string, '+', '-' or the hex/octal/binary
+representations (like the empty string, '+', '-' or the hex/octal/decimal/binary
 prefix) are accepted as if they are valid too.
 .TP
 \fBTCL_LINK_DOUBLE\fR
-The C variable is of type \fBdouble\fR.
+.
+The C variable, or each element of the C array, is of type \fBdouble\fR.
 Any value written into the Tcl variable must have a proper real
 form acceptable to \fBTcl_GetDoubleFromObj\fR;  attempts to write
 non-real values into \fIvarName\fR will be rejected with
 Tcl errors. Incomplete integer or real representations (like the
-empty string, '.', '+', '-' or the hex/octal/binary prefix) are
+empty string, '.', '+', '-' or the hex/octal/decimal/binary prefix) are
 accepted as if they are valid too.
 .TP
 \fBTCL_LINK_FLOAT\fR
-The C variable is of type \fBfloat\fR.
+.
+The C variable, or each element of the C array, is of type \fBfloat\fR.
 Any value written into the Tcl variable must have a proper real
 form acceptable to \fBTcl_GetDoubleFromObj\fR and must be within the
 range acceptable for a \fBfloat\fR; attempts to
 write non-real values (or values outside the range) into
 \fIvarName\fR will be rejected with Tcl errors. Incomplete integer
 or real representations (like the empty string, '.', '+', '-' or
-the hex/octal/binary prefix) are accepted as if they are valid too.
+the hex/octal/decimal/binary prefix) are accepted as if they are valid too.
 .TP
 \fBTCL_LINK_WIDE_INT\fR
-The C variable is of type \fBTcl_WideInt\fR (which is an integer type
+.
+The C variable, or each element of the C array, is of type \fBTcl_WideInt\fR
+(which is an integer type
 at least 64-bits wide on all platforms that can support it.)
 Any value written into the Tcl variable must have a proper integer
 form acceptable to \fBTcl_GetWideIntFromObj\fR;  attempts to write
 non-integer values into \fIvarName\fR will be rejected with
 Tcl errors. Incomplete integer representations (like the empty
-string, '+', '-' or the hex/octal/binary prefix) are accepted
+string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted
 as if they are valid too.
 .TP
 \fBTCL_LINK_WIDE_UINT\fR
-The C variable is of type \fBTcl_WideUInt\fR (which is an unsigned
-integer type at least 64-bits wide on all platforms that can support
-it.)
+.
+The C variable, or each element of the C array, is of type \fBTcl_WideUInt\fR
+(which is an unsigned integer type at least 64-bits wide on all platforms that
+can support it.)
 Any value written into the Tcl variable must have a proper unsigned
-integer form acceptable to \fBTcl_GetWideIntFromObj\fR (it will be
-cast to unsigned);
-.\" FIXME! Use bignums instead.
+wideinteger form acceptable to \fBTcl_GetWideUIntFromObj\fR;
 attempts to write non-integer values into \fIvarName\fR will be
 rejected with Tcl errors. Incomplete integer representations (like
-the empty string, '+', '-' or the hex/octal/binary prefix) are accepted
+the empty string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted
 as if they are valid too.
 .TP
 \fBTCL_LINK_BOOLEAN\fR
-The C variable is of type \fBint\fR.
+.
+The C variable, or each element of the C array, is of type \fBint\fR.
 If its value is zero then it will read from Tcl as
 .QW 0 ;
 otherwise it will read from Tcl as
@@ -188,15 +261,17 @@ non-boolean values into \fIvarName\fR will be rejected with
 Tcl errors.
 .TP
 \fBTCL_LINK_STRING\fR
+.
 The C variable is of type \fBchar *\fR.
 If its value is not NULL then it must be a pointer to a string
-allocated with \fBTcl_Alloc\fR or \fBckalloc\fR.
+allocated with \fBTcl_Alloc\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.
 If the C variable contains a NULL pointer then the Tcl variable
 will read as
 .QW NULL .
+This is only supported by \fBTcl_LinkVar\fR.
 .PP
 If the \fBTCL_LINK_READ_ONLY\fR flag is present in \fItype\fR then the
 variable will be read-only from Tcl, so that its value can only be
--- a/Show More
+++ b/Show More