Rebase to 8.7

in system encoding discovery.  Adapted test unixInit-3.2 to stop shielding
this problem from view.

.fossil-settings/crlf-glob

@@ -10,7 +10,6 @@ compat/zlib/zlib.map
 libtommath/*.dsp
 libtommath/*.sln
 libtommath/*.vcproj
-tools/tcl.hpj.in
 tools/tcl.wse.in
 win/buildall.vc.bat
 win/coffbase.txt
@@ -20,4 +19,3 @@ win/rules-ext.vc
 win/targets.vc
 win/tcl.dsp
 win/tcl.dsw
-win/tcl.hpj.in

.fossil-settings/encoding-glob

@@ -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

.github/workflows/linux-build.yml

@@ -9,12 +9,12 @@ jobs:
       matrix:
         cfgopt:
           - ""
+          - "CFLAGS=-DTCL_UTF_MAX=3"
+          - "CFLAGS=-DTCL_NO_DEPRECATED=1"
           - "--disable-shared"
           - "--enable-symbols"
           - "--enable-symbols=mem"
           - "--enable-symbols=all"
-          - "CFLAGS=-DTCL_UTF_MAX=4"
-          - "CFLAGS=-DTCL_UTF_MAX=6"
     defaults:
       run:
         shell: bash
@@ -24,7 +24,7 @@ jobs:
         uses: actions/checkout@v3
       - name: Prepare
         run: |
-          touch tclStubInit.c tclOOStubInit.c
+          touch tclStubInit.c tclOOStubInit.c tclOOScript.h
         working-directory: generic
       - name: Configure ${{ matrix.cfgopt }}
         run: |

.github/workflows/mac-build.yml

@@ -14,10 +14,12 @@ jobs:
         uses: actions/checkout@v3
       - name: Prepare
         run: |
-          touch tclStubInit.c tclOOStubInit.c
+          touch tclStubInit.c tclOOStubInit.c tclOOScript.h
         working-directory: generic
       - name: Build
         run: make all
+        env:
+          CFLAGS: -arch x86_64 -arch arm64e
       - name: Run Tests
         run: make test styles=develop
         env:
@@ -42,17 +44,20 @@ jobs:
         uses: actions/checkout@v3
       - 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.cfgopt }}
         # 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 arm64e
           CFGOPT: ${{ matrix.cfgopt }}
       - name: Build
         run: |
           make all tcltest
+        env:
+          CFLAGS: -arch x86_64 -arch arm64e
       - name: Run Tests
         run: |
           make test

.github/workflows/onefiledist.yml

@@ -0,0 +1,146 @@
+name: Build Binaries
+on: [push]
+permissions:
+  contents: read
+jobs:
+  linux:
+    name: Linux
+    runs-on: ubuntu-20.04
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - 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: Upload
+        uses: actions/upload-artifact@v3
+        with:
+          name: Tclsh ${{ env.TCL_PATCHLEVEL }} Linux single-file build (snapshot)
+          path: 1dist/*.tar
+  macos:
+    name: macOS
+    runs-on: macos-11
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Checkout create-dmg
+        uses: actions/checkout@v3
+        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.3/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 arm64e" >> $GITHUB_ENV
+      - 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_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: Upload
+        uses: actions/upload-artifact@v3
+        with:
+          name: Tclsh ${{ env.TCL_PATCHLEVEL }} macOS single-file build (snapshot)
+          path: 1dist/*.dmg
+  win:
+    name: Windows
+    runs-on: windows-2019
+    defaults:
+      run:
+        shell: msys2 {0}
+    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@v3
+      - 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
+        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: Upload
+        uses: actions/upload-artifact@v3
+        with:
+          name: Tclsh ${{ env.TCL_PATCHLEVEL }} Windows single-file build (snapshot)
+          path: '1dist/*_snapshot.exe'

.github/workflows/win-build.yml

@@ -15,7 +15,9 @@ jobs:
       matrix:
         cfgopt:
           - ""
-          - "OPTS=static,msvcrt"
+          - "OPTS=utf16"
+          - "CHECKS=nodep"
+          - "OPTS=static"
           - "OPTS=symbols"
           - "OPTS=symbols STATS=compdbg,memdbg"
     # Using powershell means we need to explicitly stop on failure
@@ -52,6 +54,8 @@ jobs:
       matrix:
         cfgopt:
           - ""
+          - "CFLAGS=-DTCL_UTF_MAX=3"
+          - "CFLAGS=-DTCL_NO_DEPRECATED=1"
           - "--disable-shared"
           - "--enable-symbols"
           - "--enable-symbols=mem"
@@ -67,7 +71,7 @@ jobs:
         uses: actions/checkout@v3
       - 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.cfgopt }}
@@ -81,3 +85,6 @@ jobs:
         run: make tcltest
       - name: Run Tests
         run: make test
+
+# If you add builds with Wine, be sure to define the environment variable
+# CI_USING_WINE when running them so that broken tests know not to run.

.project

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <projectDescription>
-	<name>tcl8.6</name>
+	<name>tcl8</name>
 	<comment></comment>
 	<projects>
 	</projects>

.travis.yml

@@ -27,13 +27,13 @@ jobs:
       env:
         - BUILD_DIR=unix
         - CFGOPT=CFLAGS=-DTCL_UTF_MAX=4
-    - name: "Linux/GCC/Shared: UTF_MAX=6"
+    - name: "Linux/GCC/Shared: NO_DEPRECATED"
       os: linux
       dist: focal
       compiler: gcc
       env:
         - BUILD_DIR=unix
-        - CFGOPT=CFLAGS=-DTCL_UTF_MAX=6
+        - CFGOPT="CFLAGS=-DTCL_NO_DEPRECATED=1"
     - name: "Linux/GCC/Static"
       os: linux
       dist: focal
@@ -83,6 +83,13 @@ jobs:
       compiler: clang
       env:
         - BUILD_DIR=unix
+    - name: "Linux/Clang/Shared:NO_DEPRECATED"
+      os: linux
+      dist: xenial
+      compiler: clang
+      env:
+        - BUILD_DIR=unix
+        - CFGOPT="CFLAGS=-DTCL_NO_DEPRECATED=1"
     - name: "Linux/Clang/Static"
       os: linux
       dist: focal
@@ -105,7 +112,7 @@ jobs:
         - BUILD_DIR=unix
         - CFGOPT="--enable-symbols=mem"
 # Testing on Mac, various styles
-    - name: "macOS/Xcode 12/Shared"
+    - name: "macOS/Clang/Xcode 12/Shared"
       os: osx
       osx_image: xcode12.2
       env:
@@ -115,14 +122,25 @@ jobs:
         - make all
         # The styles=develop avoids some weird problems on OSX
         - make test styles=develop
-    - name: "macOS/Xcode 12/Shared/Unix-like"
+    - name: "macOS/Clang/Xcode 12/Shared/Unix-like"
       os: osx
       osx_image: xcode12.2
       env:
         - BUILD_DIR=unix
         - CFGOPT="--enable-dtrace"
+    - name: "macOS/Clang/Xcode 12/Shared/libtommath"
+      os: osx
+      osx_image: xcode12.2
+      env:
+        - BUILD_DIR=macosx
+      install: []
+      script: *mactest
+      addons:
+        homebrew:
+          packages:
+            - libtommath
 # Newer MacOS versions
-    - name: "macOS/Xcode 12/Universal Apps/Shared"
+    - name: "macOS/Clang/Xcode 12/Universal Apps/Shared"
       os: osx
       osx_image: xcode12u
       env:
@@ -130,28 +148,28 @@ jobs:
       install: []
       script: *mactest
 # Older MacOS versions
-    - name: "macOS/Xcode 11/Shared"
+    - name: "macOS/Clang/Xcode 11/Shared"
       os: osx
       osx_image: xcode11.7
       env:
         - BUILD_DIR=macosx
       install: []
       script: *mactest
-    - name: "macOS/Xcode 10/Shared"
+    - name: "macOS/Clang/Xcode 10/Shared"
       os: osx
       osx_image: xcode10.3
       env:
         - BUILD_DIR=macosx
       install: []
       script: *mactest
-    - name: "macOS/Xcode 9/Shared"
+    - name: "macOS/Clang/Xcode 9/Shared"
       os: osx
       osx_image: xcode9.4
       env:
         - BUILD_DIR=macosx
       install: []
       script: *mactest
-    - name: "macOS/Xcode 8/Shared"
+    - name: "macOS/Clang/Xcode 8/Shared"
       os: osx
       osx_image: xcode8.3
       env:
@@ -190,13 +208,31 @@ jobs:
         - BUILD_DIR=win
         - VCDIR="/C/Program Files (x86)/Microsoft Visual Studio/2017/BuildTools/VC/Auxiliary/Build"
       before_install: &vcpreinst
-        - touch generic/tclStubInit.c generic/tclOOStubInit.c
+        - touch generic/tclStubInit.c generic/tclOOStubInit.c generic/tclOOScript.h
         - PATH="$PATH:$VCDIR"
         - cd ${BUILD_DIR}
       install: []
       script:
         - cmd.exe //C vcvarsall.bat x64 '&&' nmake '-f' makefile.vc all tcltest
         - cmd.exe //C vcvarsall.bat x64 '&&' nmake '-f' makefile.vc test
+    - name: "Windows/MSVC/Shared: UTF_MAX=4"
+      os: windows
+      compiler: cl
+      env: *vcenv
+      before_install: *vcpreinst
+      install: []
+      script:
+        - cmd.exe //C vcvarsall.bat x64 '&&' nmake 'OPTS=utf16' '-f' makefile.vc all tcltest
+        - cmd.exe //C vcvarsall.bat x64 '&&' nmake 'OPTS=utf16' '-f' makefile.vc test
+    - name: "Windows/MSVC/Shared: NO_DEPRECATED"
+      os: windows
+      compiler: cl
+      env: *vcenv
+      before_install: *vcpreinst
+      install: []
+      script:
+        - cmd.exe //C vcvarsall.bat x64 '&&' nmake 'CHECKS=nodep' '-f' makefile.vc all tcltest
+        - cmd.exe //C vcvarsall.bat x64 '&&' nmake 'CHECKS=nodep' '-f' makefile.vc test
     - name: "Windows/MSVC/Static"
       os: windows
       compiler: cl
@@ -204,17 +240,8 @@ jobs:
       before_install: *vcpreinst
       install: []
       script:
-        - cmd.exe //C vcvarsall.bat x64 '&&' nmake 'OPTS=static,msvcrt' '-f' makefile.vc all tcltest
-        - cmd.exe //C vcvarsall.bat x64 '&&' nmake 'OPTS=static,msvcrt' '-f' makefile.vc test
-    - name: "Windows/MSVC/StaticPackage"
-      os: windows
-      compiler: cl
-      env: *vcenv
-      before_install: *vcpreinst
-      install: []
-      script:
-        - cmd.exe //C vcvarsall.bat x64 '&&' nmake 'OPTS=static,staticpkg,msvcrt' '-f' makefile.vc all tcltest
-        - cmd.exe //C vcvarsall.bat x64 '&&' nmake 'OPTS=static,staticpkg,msvcrt' '-f' makefile.vc test
+        - cmd.exe //C vcvarsall.bat x64 '&&' nmake 'OPTS=static' '-f' makefile.vc all tcltest
+        - cmd.exe //C vcvarsall.bat x64 '&&' nmake 'OPTS=static' '-f' makefile.vc test
     - name: "Windows/MSVC/Debug"
       os: windows
       compiler: cl
@@ -243,6 +270,24 @@ jobs:
       script:
         - cmd.exe //C vcvarsall.bat x86 '&&' nmake '-f' makefile.vc all tcltest
         - cmd.exe //C vcvarsall.bat x86 '&&' nmake '-f' makefile.vc test
+    - name: "Windows/MSVC-x86/Shared: UTF_MAX=4"
+      os: windows
+      compiler: cl
+      env: *vcenv
+      before_install: *vcpreinst
+      install: []
+      script:
+        - cmd.exe //C vcvarsall.bat x86 '&&' nmake 'OPTS=utf16' '-f' makefile.vc all tcltest
+        - cmd.exe //C vcvarsall.bat x86 '&&' nmake 'OPTS=utf16' '-f' makefile.vc test
+    - name: "Windows/MSVC-x86/Shared: NO_DEPRECATED"
+      os: windows
+      compiler: cl
+      env: *vcenv
+      before_install: *vcpreinst
+      install: []
+      script:
+        - cmd.exe //C vcvarsall.bat x86 '&&' nmake 'CHECKS=nodep' '-f' makefile.vc all tcltest
+        - cmd.exe //C vcvarsall.bat x86 '&&' nmake 'CHECKS=nodep' '-f' makefile.vc test
     - name: "Windows/MSVC-x86/Static"
       os: windows
       compiler: cl
@@ -250,8 +295,8 @@ jobs:
       before_install: *vcpreinst
       install: []
       script:
-        - cmd.exe //C vcvarsall.bat x86 '&&' nmake 'OPTS=static,msvcrt' '-f' makefile.vc all tcltest
-        - cmd.exe //C vcvarsall.bat x86 '&&' nmake 'OPTS=static,msvcrt' '-f' makefile.vc test
+        - cmd.exe //C vcvarsall.bat x86 '&&' nmake 'OPTS=static' '-f' makefile.vc all tcltest
+        - cmd.exe //C vcvarsall.bat x86 '&&' nmake 'OPTS=static' '-f' makefile.vc test
     - name: "Windows/MSVC-x86/Debug"
       os: windows
       compiler: cl
@@ -278,8 +323,8 @@ jobs:
         - BUILD_DIR=win
         - CFGOPT="--enable-64bit"
       before_install: &makepreinst
-        - touch generic/tclStubInit.c generic/tclOOStubInit.c
-        - choco install -y make
+        - touch generic/tclStubInit.c generic/tclOOStubInit.c generic/tclOOScript.h
+        - choco install -y make zip
         - cd ${BUILD_DIR}
     - name: "Windows/GCC/Shared: UTF_MAX=4"
       os: windows
@@ -288,6 +333,13 @@ jobs:
         - BUILD_DIR=win
         - CFGOPT="--enable-64bit CFLAGS=-DTCL_UTF_MAX=4"
       before_install: *makepreinst
+    - name: "Windows/GCC/Shared: NO_DEPRECATED"
+      os: windows
+      compiler: gcc
+      env:
+        - BUILD_DIR=win
+        - CFGOPT="--enable-64bit CFLAGS=-DTCL_NO_DEPRECATED=1"
+      before_install: *makepreinst
     - name: "Windows/GCC/Static"
       os: windows
       compiler: gcc
@@ -323,6 +375,13 @@ jobs:
         - BUILD_DIR=win
         - CFGOPT="CFLAGS=-DTCL_UTF_MAX=4"
       before_install: *makepreinst
+    - name: "Windows/GCC-x86/Shared: NO_DEPRECATED"
+      os: windows
+      compiler: gcc
+      env:
+        - BUILD_DIR=win
+        - CFGOPT="CFLAGS=-DTCL_NO_DEPRECATED=1"
+      before_install: *makepreinst
     - name: "Windows/GCC-x86/Static"
       os: windows
       compiler: gcc
@@ -354,7 +413,7 @@ jobs:
       script:
         - make dist
 before_install:
-  - touch generic/tclStubInit.c generic/tclOOStubInit.c
+  - touch generic/tclStubInit.c generic/tclOOStubInit.c generic/tclOOScript.h
   - cd ${BUILD_DIR}
 install:
   - mkdir "$HOME/install dir"

ChangeLog.2007

@@ -1426,7 +1426,7 @@
 	initialization assumptions of the TIP 280 code in CompileWord().
 
 	* generic/tclCompExpr.c:	Suppress the attempt to convert to
-	numeric when pre-compiling a constant expresion indicates an error.
+	numeric when pre-compiling a constant expression indicates an error.
 
 2007-08-22  Miguel Sofer  <msofer@users.sf.net>
 

ChangeLog.2008

@@ -1939,7 +1939,7 @@
 2008-07-28  Jan Nijtmans  <nijtmans@users.sf.net>
 
 	* doc/FileSystem.3:		CONSTified many functions using
-	* generic/tcl.decls:		Tcl_FileSystem which all are supposed
+	* generic/tcl.decls:		Tcl_Filesystem which all are supposed
 	* generic/tclDecls.h:		to be a constant, but this was not
 	* generic/tclFileSystem.h:	reflected in the API: Tcl_FSData,
 	* generic/tclIOUtil.c:		Tcl_FSGetInternalRep, Tcl_FSRegister,

README.md

@@ -1,13 +1,13 @@
 # README:  Tcl
 
-This is the **Tcl 8.6.12** source distribution.
+This is the **Tcl 8.7a6** source distribution.
 
 You can get any source release of Tcl from [our distribution
 site](https://sourceforge.net/projects/tcl/files/Tcl/).
 
-[![Build Status](https://github.com/tcltk/tcl/workflows/Linux/badge.svg?branch=core-8-6-branch)](https://github.com/tcltk/tcl/actions?query=workflow%3A%22Linux%22+branch%3Acore-8-6-branch)
-[![Build Status](https://github.com/tcltk/tcl/workflows/Windows/badge.svg?branch=core-8-6-branch)](https://github.com/tcltk/tcl/actions?query=workflow%3A%22Windows%22+branch%3Acore-8-6-branch)
-[![Build Status](https://github.com/tcltk/tcl/workflows/macOS/badge.svg?branch=core-8-6-branch)](https://github.com/tcltk/tcl/actions?query=workflow%3A%22macOS%22+branch%3Acore-8-6-branch)
+[![Build Status](https://github.com/tcltk/tcl/workflows/Linux/badge.svg?branch=core-8-branch)](https://github.com/tcltk/tcl/actions?query=workflow%3A%22Linux%22+branch%3Acore-8-branch)
+[![Build Status](https://github.com/tcltk/tcl/workflows/Windows/badge.svg?branch=core-8-branch)](https://github.com/tcltk/tcl/actions?query=workflow%3A%22Windows%22+branch%3Acore-8-branch)
+[![Build Status](https://github.com/tcltk/tcl/workflows/macOS/badge.svg?branch=core-8-branch)](https://github.com/tcltk/tcl/actions?query=workflow%3A%22macOS%22+branch%3Acore-8-branch)
 
 ## Contents
  1. [Introduction](#intro)
@@ -45,7 +45,7 @@ and selling it either in whole or in part.  See the file
 ## <a id="doc">2.</a> Documentation
 Extensive documentation is available on our website.
 The home page for this release, including new features, is
-[here](https://www.tcl-lang.org/software/tcltk/8.6.html).
+[here](https://www.tcl-lang.org/software/tcltk/8.7.html).
 Detailed release notes can be found at the
 [file distributions page](https://sourceforge.net/projects/tcl/files/Tcl/)
 by clicking on the relevant version.
@@ -55,8 +55,8 @@ Xchange](https://www.tcl-lang.org/about/).
 There have been many Tcl books on the market.  Many are mentioned in
 [the Wiki](https://wiki.tcl-lang.org/_/ref?N=25206).
 
-The complete set of reference manual entries for Tcl 8.6 is [online,
-here](https://www.tcl-lang.org/man/tcl8.6/).
+The complete set of reference manual entries for Tcl 8.7 is [online,
+here](https://www.tcl-lang.org/man/tcl8.7/).
 
 ### <a id="doc.unix">2a.</a> Unix Documentation
 The `doc` subdirectory in this release contains a complete set of

changes

@@ -8796,6 +8796,55 @@ improvements to regexp engine from Postgres (lane,porter,fellows,seltenreich)
 
 --- Released 8.6.7, August 9, 2017 --- https://core.tcl-lang.org/tcl/ for details
 
+Changes to 8.7a1 include all changes to the 8.6 line through 8.6.7,
+plus the following, which focuses on the high-level feature changes
+in this changeset (new minor version) rather than bug fixes:
+
+2016-03-17 (bug)[0b8c38] socket accept callbacks always in global ns (porter)
+        *** POTENTIAL INCOMPATIBILITY ***
+
+2016-07-01 Hack accommodations for legacy Itcl 3 disabled (porter)
+
+2016-07-12 Make TCL_HASH_TYPE build-time configurable (nijtmans)
+
+2016-07-19 (bug)[0363f0] Partial array search ID reform (porter)
+
+2016-07-19 (feature removed) Tcl_ObjType "array search" unregistered (porter)
+	*** POTENTIAL INCOMPATIBILITY for Tcl_GetObjType("array search") ***
+
+2016-10-04 Server socket on port 0 chooses port supporting IPv4 * IPv6 (max)
+
+2016-11-25 [array names -regexp] supports backrefs (goth)
+
+2017-01-04 (TIP 456) New routine Tcl_OpenTcpServerEx() (limeboy)
+
+2017-01-04 (TIP 459) New subcommand [package files] (nijtmans)
+
+2017-01-16 threaded allocator initialization repair (vasiljevic,nijtmans)
+
+2017-01-30 Add to Win shell builtins: assoc ftype move (ashok)
+
+2017-03-31 TCL_MEM_DEBUG facilities better support 64-bit memory (nijtmans)
+
+2017-04-13 \u escaped content in msg files converted to true utf-8 (nijtmans)
+
+2017-05-18 (TIP 458) New epoll or kqueue notifiers are default (alborboz)
+
+2017-05-31 Purge build support for SunOS-4.* (stu)
+
+2017-06-22 (TIP 463) New option [regsub ... -command ...] (fellows)
+
+2017-06-22 (TIP 470) Tcl_GetDefineContextObject();[oo::define [self]] (fellows)
+=> TclOO 1.2.0
+
+2017-06-23 (TIP 472) Support 0d as prefix of decimal numbers (iyer,griffin)
+
+2017-08-31 (bug)[2a9465] http state 100 continue handling broken (oehlmann)
+
+2017-09-02 (bug)[0e4d88] replace command, delete trace kills namespace (porter)
+
+--- Released 8.7a1, September 8, 2017 --- https://core.tcl-lang.org/tcl/ for details
+
 2017-08-10 [array names -regexp] supports backrefs (goth)
 
 2017-08-10 Fix gcc build failures due to #pragma placement (cassoff,fellows)
@@ -8946,6 +8995,138 @@ improvements to regexp engine from Postgres (lane,porter,fellows,seltenreich)
 
 - Released 8.6.10, Nov 21, 2019 - details at https://core.tcl-lang.org/tcl/ -
 
+Changes to 8.7a3 include all changes to the 8.6 line through 8.6.10,
+plus the following, which focuses on the high-level feature changes
+in this changeset (new minor version) rather than bug fixes:
+
+2017-11-01 (bug)[3c32a3] crash deleting class mixed into instance (coulter)
+
+2017-11-03 [TIP 345] eliminate the encoding 'identity' (porter)
+
+2017-11-04 (bug)[0d902e] [string first] on ASCII stored as Unicode (fellows)
+
+2017-11-17 [TIP 422] Mark all Tcl_*VA() routines deprecated. (nijtmans)
+
+2017-11-20 (support) Ended use of the obsolete values.h header (culler)
+
+2017-11-30 (bug)[8e1e31] [lsort] ordering of U+0000 (nijtmans)
+
+2017-12-07 [TIP 487] Terminate support for pre-XP Windows (nijtmans)
+
+2017-12-08 [TIP 477] Reform of nmake build (nadkarni)
+
+2017-12-20 (bug)[ba1419] Crash: complex ensemble delete, namespace-7.8 (coulter)
+
+2018-01-17 [TIP 485] Removal of many deprecated features (nijtmans)
+
+2018-01-27 (bug) Crash in [join $l $l], join-4.1 (porter)
+
+2018-02-06 [TIP 493] Cease Distribution of http 1.0 (porter)
+
+2018-02-06 [TIP 484] internal rep for native ints are all 64-bit (nijtmans)
+
+2018-02-14 [TIP 476] Scan/Printf consistency (nijtmans)
+
+2018-03-05 [TIP 351] [lsearch] striding
+
+2018-03-05 [TIPs 330,336] tighten access to Interp fields (porter)
+
+2018-03-12 [TIP 462] [::tcl::process]
+
+2018-03-12 [TIP 490] add oo support for msgcat => msgcat 1.7.0 (oehlmann)
+
+2018-03-12 [TIP 499] custom locale preference list (oehlmann)
+=> msgcat 1.7.0
+
+2018-03-20 [TIP 503] End CONST84 support for Tcl 8.3 (porter)
+
+2018-03-30 Refactored [lrange] (spjuth)
+
+2018-04-20 [TIP 389] Unicode beyond BMP (nijtmans)
+
+2018-04-20 [TIP 421] [array for]
+
+2018-05-11 [TIP 425] Windows panic callback use of UTF-8
+
+2018-05-17 [TIP 491] Phase out --disable-threads support
+
+2018-06-03 [TIP 500] TclOO Private Methods and Variables
+
+2018-07-26 (bug)[ba921a] [string cat] of bytearrays (coulter,porter)
+
+2018-09-02 [TIP 478] Many new features in TclOO (lester,fellows)
+
+2018-09-04 (bug)[540bed] [binary format w] from bignum (nijtmans)
+
+2018-09-12 [TIP 430] zipfs and embedded script library (woods)
+
+2018-09-26 [TIP 508] [array default] (bonnet,fellows)
+
+2018-09-27 [TIP 515] level value reform (nijtmans)
+
+2018-09-27 [TIP 516] More OO slot operations (fellows)
+
+2018-09-27 [TIP 426] [info cmdtype] (fellows)
+
+2018-09-28 [TIP 509] Cross platform reentrant mutex
+
+2018-10-08 [TIP 514] native integers are 64-bit
+
+2018-10-12 [TIP 502] index value reform (porter)
+
+2018-11-06 [TIP 406] http cookies (fellows)
+
+2018-11-06 [TIP 445] Tcl_ObjType utilities (migrate to Tcl 9) (porter)
+
+2018-11-06 [TIP 501] [string is dict]
+
+2018-11-06 [TIP 519] inline export/unexport option for [oo::define]
+
+2018-11-06 [TIP 523] [lpop]
+
+2018-11-06 [TIP 524] TclOO custom dialects
+
+2018-11-06 [TIP 506] Tcl_(Incr|Decr)RefCount macros -> functions (porter)
+
+2018-11-15 [TIP 512] No stub for Tcl_SetExitProc()
+
+2019-04-08 (bug)[45b9fa] crash in [try] (coulter)
+
+2019-04-14 [TIP 160] terminal and serial channel controls
+
+2019-04-14 [TIP 312] more types for Tcl_LinkVar
+
+2019-04-14 [TIP 367] [lremove]
+
+2019-04-14 [TIP 504] [string insert]
+
+2019-04-16 [TIP 342] [dict getwithdefault]
+
+2019-04-23 (bug)[67a5ea] make [chan postevent] asynchronous
+        *** POTENTIAL INCOMPATIBILITY ***
+
+2019-05-25 [TIP 431] [file tempdir]
+
+2019-05-25 [TIP 383] [coroinject], [coroprobe]
+
+2019-05-31 [TIP 544] Tcl_GetIntForIndex()
+
+2019-06-12 Replace TclOffset() with offsetof()
+
+2019-06-15 [TIP 461] string compare operators for [expr]
+
+2019-06-16 [TIP 521] floating point classification functions for [expr]
+
+2019-06-20 (bug)[6bdadf] crash multi-arg traced [lappend] (fellows)
+
+2019-06-28 [TIP 547] New encodings utf-16, ucs-2
+
+2019-09-14 [TIP 414] Tcl_InitSubsystems()
+
+2019-09-14 [TIP 548] wchar_t conversion functions
+
+- Released 8.7a3, Nov 21, 2019 --- https://core.tcl-lang.org/tcl/ for details -
+
 2019-12-03 (bug)[3cd9be] Corner case in surrogate handling (nijtmans)
 
 2019-12-09 (new) Add tcltest::(Setup|Eval|Cleanup|)Test (coulter,sebres)
@@ -9051,7 +9232,7 @@ See RFC 2045
 2020-09-17 (bug)[835c93] Support TIP 525 exit code for -singleproc 1 (nijtmans)
 => tcltest 2.5.3
 
-2020-09-25 (new) force -eofchar \032 when evaluating library scripts (nijtmans)
+2020-09-25 (new) force -eofchar \x1A when evaluating library scripts (nijtmans)
         *** POTENTIAL INCOMPATIBILITY ***
 
 2020-09-29 (bug)[0063cb] http::geturl -headers must be dict (oehlmann,nijtmans)
@@ -9075,6 +9256,84 @@ See RFC 2045
 
 - Released 8.6.11, Dec 31, 2020 - details at https://core.tcl-lang.org/tcl/ -
 
+Changes to 8.7a5 include all changes to the 8.6 line through 8.6.11,
+plus the following, which focuses on the high-level feature changes
+in this changeset (new minor version) rather than bug fixes:
+
+2019-12-13 [TIP 538] Externalize libtommath
+
+2020-01-20 [TIP 542] Support for switchable Full Unicode support
+
+2020-01-21 [TIP 543] Eliminate `TCL_INTERP_DESTROYED` flag value
+
+2020-01-24 [TIP 559] Eliminate public routine `Tcl_FreeResult
+
+2020-01-31 (new) Implement 64-bit seek on Zip channels. (nijtmans)
+
+2020-02-28 [TIP 557] C++ support for Tcl
+
+2020-02-28 [TIP 562] Deprecate channel types 1-4
+
+2020-03-11 (bug)[234d6c] Segfault in [set l {}; lpop l] (sebres)
+
+2020-03-12 (bug) Crash in tests binary-79.[12] (porter)
+
+2020-03-13 [TIP 569] Eliminate Comments That Serve Lint
+
+2020-04-06 (bug)[dd010c] [string trim*] on astral characters (porter,nijtmans)
+
+2020-05-30 [TIP 551] Permit underscore in numerical literals in source code
+
+2020-07-03 [TIP 578] Death to TCL_DBGX
+
+2020-08-11 (bug)[e87000] Win32 crash in [fconfigure stdout] (werner,nijtmans)
+
+2020-09-06 (bug)[c1a376] deletion trace on imported ensemble (coulter)
+
+2020-09-13 [TIP 585] Promote the INDEX_TEMP_TABLE flag of Tcl_GetIndexFromObj*() to the public interface
+
+2020-09-15 (bug)[b5777d] crash in [string index abcd 0-0x10000000000000000]
+
+2020-09-19 [b9ecf3] revised stork mgmt [uplevel [list $cmd ...]] (coulter)
+
+2020-10-23 [TIP 587] Default utf-8 for source command
+
+2020-10-27 (bug)[11229b] test string-31.26.* (porter)
+
+2020-11-08 [TIP 582] Comments in Expressions
+
+2020-11-16 [TIP 586] C String Parsing Support for binary scan
+
+2020-12-07 [TIP 590] Recommend lowercase Package Names
+
+2021-01-06 Bump to tcltest 2.5.4
+
+2021-01-15 [TIP 481] `Tcl_GetStringFromObj()` with `size_t` length parameter
+
+2021-01-15 [TIP 592] End support: Windows XP, Server 2003, Vista, Server 2008
+
+2021-01-25 tzdata updated to Olson's tzdata2021a (nijtmans)
+
+2021-01-29 (bug)[113be1] zipfs on mac
+
+2021-03-15 [TIP 575] Switchable Tcl_UtfCharComplete()/Tcl_UtfNext()/Tcl_UtfPrev()
+
+2021-03-19 (new)[0221b9] Drop TCL_WINDOW_EVENTS from Tcl's [update idletasks]
+
+2021-03-30 (new)[4b4830] [chan truncate] for reflected channels
+
+2021-04-30 [TIP 597] "string is unicode" and better utf-8/utf-16/cesu-8 encodings
+
+2021-04-09 [TIP 598] export TclWinConvertError
+
+2021-05-15 (bug)[463b7a] segfault from Tcl_Unload (coulter)
+
+2021-05-15 (bug)[fb2a41] tclZipfs.c free all memory (coulter)
+
+2021-05-18 (bug)[688fcc,28027d] namespace teardown reform (coulter)
+
+- Released 8.7a5, Jun 18, 2021 --- https://core.tcl-lang.org/tcl/ for details -
+
 2021-02-02 (new) support for MacOS Big Sur updates (nijtmans)
 => platform 1.0.17
 

compat/fake-rfc2553.c

@@ -73,6 +73,7 @@ int fake_getnameinfo(const struct sockaddr *sa, size_t salen, char *host,
 	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);
 

compat/float.h

@@ -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.
- */

compat/mkstemp.c

@@ -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;

compat/opendir.c

@@ -106,5 +106,5 @@ closedir(
     close(dirp->dd_fd);
     dirp->dd_fd = -1;
     dirp->dd_loc = 0;
-    ckfree((char *)dirp);
+    ckfree(dirp);
 }

compat/stdint.h

@@ -0,0 +1,919 @@
+/*  A portable stdint.h
+ ****************************************************************************
+ *  BSD License:
+ ****************************************************************************
+ *
+ *  Copyright (c) 2005-2016 Paul Hsieh
+ *  All rights reserved.
+ *
+ *  Redistribution and use in source and binary forms, with or without
+ *  modification, are permitted provided that the following conditions
+ *  are met:
+ *
+ *  1. Redistributions of source code must retain the above copyright
+ *     notice, this list of conditions and the following disclaimer.
+ *  2. Redistributions in binary form must reproduce the above copyright
+ *     notice, this list of conditions and the following disclaimer in the
+ *     documentation and/or other materials provided with the distribution.
+ *  3. The name of the author may not be used to endorse or promote products
+ *     derived from this software without specific prior written permission.
+ *
+ *  THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+ *  IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ *  OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+ *  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+ *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+ *  NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+ *  THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ ****************************************************************************
+ *
+ *  Version 0.1.16.0
+ *
+ *  The ANSI C standard committee, for the C99 standard, specified the
+ *  inclusion of a new standard include file called stdint.h.  This is
+ *  a very useful and long desired include file which contains several
+ *  very precise definitions for integer scalar types that is critically
+ *  important for making several classes of applications portable
+ *  including cryptography, hashing, variable length integer libraries
+ *  and so on.  But for most developers its likely useful just for
+ *  programming sanity.
+ *
+ *  The problem is that some compiler vendors chose to ignore the C99
+ *  standard and some older compilers have no opportunity to be updated.
+ *  Because of this situation, simply including stdint.h in your code
+ *  makes it unportable.
+ *
+ *  So that's what this file is all about.  It's an attempt to build a
+ *  single universal include file that works on as many platforms as
+ *  possible to deliver what stdint.h is supposed to.  Even compilers
+ *  that already come with stdint.h can use this file instead without
+ *  any loss of functionality.  A few things that should be noted about
+ *  this file:
+ *
+ *    1) It is not guaranteed to be portable and/or present an identical
+ *       interface on all platforms.  The extreme variability of the
+ *       ANSI C standard makes this an impossibility right from the
+ *       very get go. Its really only meant to be useful for the vast
+ *       majority of platforms that possess the capability of
+ *       implementing usefully and precisely defined, standard sized
+ *       integer scalars.  Systems which are not intrinsically 2s
+ *       complement may produce invalid constants.
+ *
+ *    2) There is an unavoidable use of non-reserved symbols.
+ *
+ *    3) Other standard include files are invoked.
+ *
+ *    4) This file may come in conflict with future platforms that do
+ *       include stdint.h.  The hope is that one or the other can be
+ *       used with no real difference.
+ *
+ *    5) In the current version, if your platform can't represent
+ *       int32_t, int16_t and int8_t, it just dumps out with a compiler
+ *       error.
+ *
+ *    6) 64 bit integers may or may not be defined.  Test for their
+ *       presence with the test: #ifdef INT64_MAX or #ifdef UINT64_MAX.
+ *       Note that this is different from the C99 specification which
+ *       requires the existence of 64 bit support in the compiler.  If
+ *       this is not defined for your platform, yet it is capable of
+ *       dealing with 64 bits then it is because this file has not yet
+ *       been extended to cover all of your system's capabilities.
+ *
+ *    7) (u)intptr_t may or may not be defined.  Test for its presence
+ *       with the test: #ifdef PTRDIFF_MAX.  If this is not defined
+ *       for your platform, then it is because this file has not yet
+ *       been extended to cover all of your system's capabilities, not
+ *       because its optional.
+ *
+ *    8) The following might not been defined even if your platform is
+ *       capable of defining it:
+ *
+ *       WCHAR_MIN
+ *       WCHAR_MAX
+ *       (u)int64_t
+ *       PTRDIFF_MIN
+ *       PTRDIFF_MAX
+ *       (u)intptr_t
+ *
+ *    9) The following have not been defined:
+ *
+ *       WINT_MIN
+ *       WINT_MAX
+ *
+ *   10) The criteria for defining (u)int_least(*)_t isn't clear,
+ *       except for systems which don't have a type that precisely
+ *       defined 8, 16, or 32 bit types (which this include file does
+ *       not support anyways). Default definitions have been given.
+ *
+ *   11) The criteria for defining (u)int_fast(*)_t isn't something I
+ *       would trust to any particular compiler vendor or the ANSI C
+ *       committee.  It is well known that "compatible systems" are
+ *       commonly created that have very different performance
+ *       characteristics from the systems they are compatible with,
+ *       especially those whose vendors make both the compiler and the
+ *       system.  Default definitions have been given, but its strongly
+ *       recommended that users never use these definitions for any
+ *       reason (they do *NOT* deliver any serious guarantee of
+ *       improved performance -- not in this file, nor any vendor's
+ *       stdint.h).
+ *
+ *   12) The following macros:
+ *
+ *       PRINTF_INTMAX_MODIFIER
+ *       PRINTF_INT64_MODIFIER
+ *       PRINTF_INT32_MODIFIER
+ *       PRINTF_INT16_MODIFIER
+ *       PRINTF_LEAST64_MODIFIER
+ *       PRINTF_LEAST32_MODIFIER
+ *       PRINTF_LEAST16_MODIFIER
+ *       PRINTF_INTPTR_MODIFIER
+ *
+ *       are strings which have been defined as the modifiers required
+ *       for the "d", "u" and "x" printf formats to correctly output
+ *       (u)intmax_t, (u)int64_t, (u)int32_t, (u)int16_t, (u)least64_t,
+ *       (u)least32_t, (u)least16_t and (u)intptr_t types respectively.
+ *       PRINTF_INTPTR_MODIFIER is not defined for some systems which
+ *       provide their own stdint.h.  PRINTF_INT64_MODIFIER is not
+ *       defined if INT64_MAX is not defined.  These are an extension
+ *       beyond what C99 specifies must be in stdint.h.
+ *
+ *       In addition, the following macros are defined:
+ *
+ *       PRINTF_INTMAX_HEX_WIDTH
+ *       PRINTF_INT64_HEX_WIDTH
+ *       PRINTF_INT32_HEX_WIDTH
+ *       PRINTF_INT16_HEX_WIDTH
+ *       PRINTF_INT8_HEX_WIDTH
+ *       PRINTF_INTMAX_DEC_WIDTH
+ *       PRINTF_INT64_DEC_WIDTH
+ *       PRINTF_INT32_DEC_WIDTH
+ *       PRINTF_INT16_DEC_WIDTH
+ *       PRINTF_UINT8_DEC_WIDTH
+ *       PRINTF_UINTMAX_DEC_WIDTH
+ *       PRINTF_UINT64_DEC_WIDTH
+ *       PRINTF_UINT32_DEC_WIDTH
+ *       PRINTF_UINT16_DEC_WIDTH
+ *       PRINTF_UINT8_DEC_WIDTH
+ *
+ *       Which specifies the maximum number of characters required to
+ *       print the number of that type in either hexadecimal or decimal.
+ *       These are an extension beyond what C99 specifies must be in
+ *       stdint.h.
+ *
+ *  Compilers tested (all with 0 warnings at their highest respective
+ *  settings): Borland Turbo C 2.0, WATCOM C/C++ 11.0 (16 bits and 32
+ *  bits), Microsoft Visual C++ 6.0 (32 bit), Microsoft Visual Studio
+ *  .net (VC7), Intel C++ 4.0, GNU gcc v3.3.3
+ *
+ *  This file should be considered a work in progress.  Suggestions for
+ *  improvements, especially those which increase coverage are strongly
+ *  encouraged.
+ *
+ *  Acknowledgements
+ *
+ *  The following people have made significant contributions to the
+ *  development and testing of this file:
+ *
+ *  Chris Howie
+ *  John Steele Scott
+ *  Dave Thorup
+ *  John Dill
+ *  Florian Wobbe
+ *  Christopher Sean Morrison
+ *  Mikkel Fahnoe Jorgensen
+ *
+ */
+
+#include <stddef.h>
+#include <limits.h>
+#include <signal.h>
+
+/*
+ *  For gcc with _STDINT_H, fill in the PRINTF_INT*_MODIFIER macros, and
+ *  do nothing else.  On the Mac OS X version of gcc this is _STDINT_H_.
+ */
+
+#if ((defined(__SUNPRO_C) && __SUNPRO_C >= 0x570) || (defined(_MSC_VER) && _MSC_VER >= 1600) || (defined(__STDC__) && __STDC__ && defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L) || (defined (__WATCOMC__) && (defined (_STDINT_H_INCLUDED) || __WATCOMC__ >= 1250)) || (defined(__GNUC__) && (__GNUC__ > 3 || defined(_STDINT_H) || defined(_STDINT_H_) || defined (__UINT_FAST64_TYPE__)) )) && !defined (_PSTDINT_H_INCLUDED)
+#include <stdint.h>
+#define _PSTDINT_H_INCLUDED
+# if defined(__GNUC__) && (defined(__x86_64__) || defined(__ppc64__)) && !(defined(__APPLE__) && defined(__MACH__))
+#  ifndef PRINTF_INT64_MODIFIER
+#   define PRINTF_INT64_MODIFIER "l"
+#  endif
+#  ifndef PRINTF_INT32_MODIFIER
+#   define PRINTF_INT32_MODIFIER ""
+#  endif
+# else
+#  ifndef PRINTF_INT64_MODIFIER
+#   define PRINTF_INT64_MODIFIER "ll"
+#  endif
+#  ifndef PRINTF_INT32_MODIFIER
+#   if (UINT_MAX == UINT32_MAX)
+#    define PRINTF_INT32_MODIFIER ""
+#   else
+#    define PRINTF_INT32_MODIFIER "l"
+#   endif
+#  endif
+# endif
+# ifndef PRINTF_INT16_MODIFIER
+#  define PRINTF_INT16_MODIFIER "h"
+# endif
+# ifndef PRINTF_INTMAX_MODIFIER
+#  define PRINTF_INTMAX_MODIFIER PRINTF_INT64_MODIFIER
+# endif
+# ifndef PRINTF_INT64_HEX_WIDTH
+#  define PRINTF_INT64_HEX_WIDTH "16"
+# endif
+# ifndef PRINTF_UINT64_HEX_WIDTH
+#  define PRINTF_UINT64_HEX_WIDTH "16"
+# endif
+# ifndef PRINTF_INT32_HEX_WIDTH
+#  define PRINTF_INT32_HEX_WIDTH "8"
+# endif
+# ifndef PRINTF_UINT32_HEX_WIDTH
+#  define PRINTF_UINT32_HEX_WIDTH "8"
+# endif
+# ifndef PRINTF_INT16_HEX_WIDTH
+#  define PRINTF_INT16_HEX_WIDTH "4"
+# endif
+# ifndef PRINTF_UINT16_HEX_WIDTH
+#  define PRINTF_UINT16_HEX_WIDTH "4"
+# endif
+# ifndef PRINTF_INT8_HEX_WIDTH
+#  define PRINTF_INT8_HEX_WIDTH "2"
+# endif
+# ifndef PRINTF_UINT8_HEX_WIDTH
+#  define PRINTF_UINT8_HEX_WIDTH "2"
+# endif
+# ifndef PRINTF_INT64_DEC_WIDTH
+#  define PRINTF_INT64_DEC_WIDTH "19"
+# endif
+# ifndef PRINTF_UINT64_DEC_WIDTH
+#  define PRINTF_UINT64_DEC_WIDTH "20"
+# endif
+# ifndef PRINTF_INT32_DEC_WIDTH
+#  define PRINTF_INT32_DEC_WIDTH "10"
+# endif
+# ifndef PRINTF_UINT32_DEC_WIDTH
+#  define PRINTF_UINT32_DEC_WIDTH "10"
+# endif
+# ifndef PRINTF_INT16_DEC_WIDTH
+#  define PRINTF_INT16_DEC_WIDTH "5"
+# endif
+# ifndef PRINTF_UINT16_DEC_WIDTH
+#  define PRINTF_UINT16_DEC_WIDTH "5"
+# endif
+# ifndef PRINTF_INT8_DEC_WIDTH
+#  define PRINTF_INT8_DEC_WIDTH "3"
+# endif
+# ifndef PRINTF_UINT8_DEC_WIDTH
+#  define PRINTF_UINT8_DEC_WIDTH "3"
+# endif
+# ifndef PRINTF_INTMAX_HEX_WIDTH
+#  define PRINTF_INTMAX_HEX_WIDTH PRINTF_UINT64_HEX_WIDTH
+# endif
+# ifndef PRINTF_UINTMAX_HEX_WIDTH
+#  define PRINTF_UINTMAX_HEX_WIDTH PRINTF_UINT64_HEX_WIDTH
+# endif
+# ifndef PRINTF_INTMAX_DEC_WIDTH
+#  define PRINTF_INTMAX_DEC_WIDTH PRINTF_UINT64_DEC_WIDTH
+# endif
+# ifndef PRINTF_UINTMAX_DEC_WIDTH
+#  define PRINTF_UINTMAX_DEC_WIDTH PRINTF_UINT64_DEC_WIDTH
+# endif
+
+/*
+ *  Something really weird is going on with Open Watcom.  Just pull some of
+ *  these duplicated definitions from Open Watcom's stdint.h file for now.
+ */
+
+# if defined (__WATCOMC__) && __WATCOMC__ >= 1250
+#  if !defined (INT64_C)
+#   define INT64_C(x)   (x + (INT64_MAX - INT64_MAX))
+#  endif
+#  if !defined (UINT64_C)
+#   define UINT64_C(x)  (x + (UINT64_MAX - UINT64_MAX))
+#  endif
+#  if !defined (INT32_C)
+#   define INT32_C(x)   (x + (INT32_MAX - INT32_MAX))
+#  endif
+#  if !defined (UINT32_C)
+#   define UINT32_C(x)  (x + (UINT32_MAX - UINT32_MAX))
+#  endif
+#  if !defined (INT16_C)
+#   define INT16_C(x)   (x)
+#  endif
+#  if !defined (UINT16_C)
+#   define UINT16_C(x)  (x)
+#  endif
+#  if !defined (INT8_C)
+#   define INT8_C(x)   (x)
+#  endif
+#  if !defined (UINT8_C)
+#   define UINT8_C(x)  (x)
+#  endif
+#  if !defined (UINT64_MAX)
+#   define UINT64_MAX  18446744073709551615ULL
+#  endif
+#  if !defined (INT64_MAX)
+#   define INT64_MAX  9223372036854775807LL
+#  endif
+#  if !defined (UINT32_MAX)
+#   define UINT32_MAX  4294967295UL
+#  endif
+#  if !defined (INT32_MAX)
+#   define INT32_MAX  2147483647L
+#  endif
+#  if !defined (INTMAX_MAX)
+#   define INTMAX_MAX INT64_MAX
+#  endif
+#  if !defined (INTMAX_MIN)
+#   define INTMAX_MIN INT64_MIN
+#  endif
+# endif
+#endif
+
+/*
+ *  I have no idea what is the truly correct thing to do on older Solaris.
+ *  From some online discussions, this seems to be what is being
+ *  recommended.  For people who actually are developing on older Solaris,
+ *  what I would like to know is, does this define all of the relevant
+ *  macros of a complete stdint.h?  Remember, in pstdint.h 64 bit is
+ *  considered optional.
+ */
+
+#if (defined(__SUNPRO_C) && __SUNPRO_C >= 0x420) && !defined(_PSTDINT_H_INCLUDED)
+#include <sys/inttypes.h>
+#define _PSTDINT_H_INCLUDED
+#endif
+
+#ifndef _PSTDINT_H_INCLUDED
+#define _PSTDINT_H_INCLUDED
+
+#ifndef SIZE_MAX
+# define SIZE_MAX ((size_t)-1)
+#endif
+
+/*
+ *  Deduce the type assignments from limits.h under the assumption that
+ *  integer sizes in bits are powers of 2, and follow the ANSI
+ *  definitions.
+ */
+
+#ifndef UINT8_MAX
+# define UINT8_MAX 0xff
+#endif
+#if !defined(uint8_t) && !defined(_UINT8_T) && !defined(vxWorks)
+# if (UCHAR_MAX == UINT8_MAX) || defined (S_SPLINT_S)
+    typedef unsigned char uint8_t;
+#   define UINT8_C(v) ((uint8_t) v)
+# else
+#   error "Platform not supported"
+# endif
+#endif
+
+#ifndef INT8_MAX
+# define INT8_MAX 0x7f
+#endif
+#ifndef INT8_MIN
+# define INT8_MIN INT8_C(0x80)
+#endif
+#if !defined(int8_t) && !defined(_INT8_T) && !defined(vxWorks)
+# if (SCHAR_MAX == INT8_MAX) || defined (S_SPLINT_S)
+    typedef signed char int8_t;
+#   define INT8_C(v) ((int8_t) v)
+# else
+#   error "Platform not supported"
+# endif
+#endif
+
+#ifndef UINT16_MAX
+# define UINT16_MAX 0xffff
+#endif
+#if !defined(uint16_t) && !defined(_UINT16_T) && !defined(vxWorks)
+#if (UINT_MAX == UINT16_MAX) || defined (S_SPLINT_S)
+  typedef unsigned int uint16_t;
+# ifndef PRINTF_INT16_MODIFIER
+#  define PRINTF_INT16_MODIFIER ""
+# endif
+# define UINT16_C(v) ((uint16_t) (v))
+#elif (USHRT_MAX == UINT16_MAX)
+  typedef unsigned short uint16_t;
+# define UINT16_C(v) ((uint16_t) (v))
+# ifndef PRINTF_INT16_MODIFIER
+#  define PRINTF_INT16_MODIFIER "h"
+# endif
+#else
+#error "Platform not supported"
+#endif
+#endif
+
+#ifndef INT16_MAX
+# define INT16_MAX 0x7fff
+#endif
+#ifndef INT16_MIN
+# define INT16_MIN INT16_C(0x8000)
+#endif
+#if !defined(int16_t) && !defined(_INT16_T) && !defined(vxWorks)
+#if (INT_MAX == INT16_MAX) || defined (S_SPLINT_S)
+  typedef signed int int16_t;
+# define INT16_C(v) ((int16_t) (v))
+# ifndef PRINTF_INT16_MODIFIER
+#  define PRINTF_INT16_MODIFIER ""
+# endif
+#elif (SHRT_MAX == INT16_MAX)
+  typedef signed short int16_t;
+# define INT16_C(v) ((int16_t) (v))
+# ifndef PRINTF_INT16_MODIFIER
+#  define PRINTF_INT16_MODIFIER "h"
+# endif
+#else
+#error "Platform not supported"
+#endif
+#endif
+
+#ifndef UINT32_MAX
+# define UINT32_MAX (0xffffffffUL)
+#endif
+#if !defined(uint32_t) && !defined(_UINT32_T) && !defined(vxWorks)
+#if (ULONG_MAX == UINT32_MAX) || defined (S_SPLINT_S)
+  typedef unsigned long uint32_t;
+# define UINT32_C(v) v ## UL
+# ifndef PRINTF_INT32_MODIFIER
+#  define PRINTF_INT32_MODIFIER "l"
+# endif
+#elif (UINT_MAX == UINT32_MAX)
+  typedef unsigned int uint32_t;
+# ifndef PRINTF_INT32_MODIFIER
+#  define PRINTF_INT32_MODIFIER ""
+# endif
+# define UINT32_C(v) v ## U
+#elif (USHRT_MAX == UINT32_MAX)
+  typedef unsigned short uint32_t;
+# define UINT32_C(v) ((unsigned short) (v))
+# ifndef PRINTF_INT32_MODIFIER
+#  define PRINTF_INT32_MODIFIER ""
+# endif
+#else
+#error "Platform not supported"
+#endif
+#endif
+
+#ifndef INT32_MAX
+# define INT32_MAX (0x7fffffffL)
+#endif
+#ifndef INT32_MIN
+# define INT32_MIN INT32_C(0x80000000)
+#endif
+#if !defined(int32_t) && !defined(_INT32_T) && !defined(vxWorks)
+#if (LONG_MAX == INT32_MAX) || defined (S_SPLINT_S)
+  typedef signed long int32_t;
+# define INT32_C(v) v ## L
+# ifndef PRINTF_INT32_MODIFIER
+#  define PRINTF_INT32_MODIFIER "l"
+# endif
+#elif (INT_MAX == INT32_MAX)
+  typedef signed int int32_t;
+# define INT32_C(v) v
+# ifndef PRINTF_INT32_MODIFIER
+#  define PRINTF_INT32_MODIFIER ""
+# endif
+#elif (SHRT_MAX == INT32_MAX)
+  typedef signed short int32_t;
+# define INT32_C(v) ((short) (v))
+# ifndef PRINTF_INT32_MODIFIER
+#  define PRINTF_INT32_MODIFIER ""
+# endif
+#else
+#error "Platform not supported"
+#endif
+#endif
+
+/*
+ *  The macro stdint_int64_defined is temporarily used to record
+ *  whether or not 64 integer support is available.  It must be
+ *  defined for any 64 integer extensions for new platforms that are
+ *  added.
+ */
+
+#undef stdint_int64_defined
+#if (defined(__STDC__) && defined(__STDC_VERSION__)) || defined (S_SPLINT_S)
+# if (__STDC__ && __STDC_VERSION__ >= 199901L) || defined (S_SPLINT_S)
+#  define stdint_int64_defined
+   typedef long long int64_t;
+   typedef unsigned long long uint64_t;
+#  define UINT64_C(v) v ## ULL
+#  define  INT64_C(v) v ## LL
+#  ifndef PRINTF_INT64_MODIFIER
+#   define PRINTF_INT64_MODIFIER "ll"
+#  endif
+# endif
+#endif
+
+#if !defined (stdint_int64_defined)
+# if defined(__GNUC__) && !defined(vxWorks)
+#  define stdint_int64_defined
+   __extension__ typedef long long int64_t;
+   __extension__ typedef unsigned long long uint64_t;
+#  define UINT64_C(v) v ## ULL
+#  define  INT64_C(v) v ## LL
+#  ifndef PRINTF_INT64_MODIFIER
+#   define PRINTF_INT64_MODIFIER "ll"
+#  endif
+# elif defined(__MWERKS__) || defined (__SUNPRO_C) || defined (__SUNPRO_CC) || defined (__APPLE_CC__) || defined (_LONG_LONG) || defined (_CRAYC) || defined (S_SPLINT_S)
+#  define stdint_int64_defined
+   typedef long long int64_t;
+   typedef unsigned long long uint64_t;
+#  define UINT64_C(v) v ## ULL
+#  define  INT64_C(v) v ## LL
+#  ifndef PRINTF_INT64_MODIFIER
+#   define PRINTF_INT64_MODIFIER "ll"
+#  endif
+# elif (defined(__WATCOMC__) && defined(__WATCOM_INT64__)) || (defined(_MSC_VER) && _INTEGRAL_MAX_BITS >= 64) || (defined (__BORLANDC__) && __BORLANDC__ > 0x460) || defined (__alpha) || defined (__DECC)
+#  define stdint_int64_defined
+   typedef __int64 int64_t;
+   typedef unsigned __int64 uint64_t;
+#  define UINT64_C(v) v ## UI64
+#  define  INT64_C(v) v ## I64
+#  ifndef PRINTF_INT64_MODIFIER
+#   define PRINTF_INT64_MODIFIER "I64"
+#  endif
+# endif
+#endif
+
+#if !defined (LONG_LONG_MAX) && defined (INT64_C)
+# define LONG_LONG_MAX INT64_C (9223372036854775807)
+#endif
+#ifndef ULONG_LONG_MAX
+# define ULONG_LONG_MAX UINT64_C (18446744073709551615)
+#endif
+
+#if !defined (INT64_MAX) && defined (INT64_C)
+# define INT64_MAX INT64_C (9223372036854775807)
+#endif
+#if !defined (INT64_MIN) && defined (INT64_C)
+# define INT64_MIN INT64_C (-9223372036854775808)
+#endif
+#if !defined (UINT64_MAX) && defined (INT64_C)
+# define UINT64_MAX UINT64_C (18446744073709551615)
+#endif
+
+/*
+ *  Width of hexadecimal for number field.
+ */
+
+#ifndef PRINTF_INT64_HEX_WIDTH
+# define PRINTF_INT64_HEX_WIDTH "16"
+#endif
+#ifndef PRINTF_INT32_HEX_WIDTH
+# define PRINTF_INT32_HEX_WIDTH "8"
+#endif
+#ifndef PRINTF_INT16_HEX_WIDTH
+# define PRINTF_INT16_HEX_WIDTH "4"
+#endif
+#ifndef PRINTF_INT8_HEX_WIDTH
+# define PRINTF_INT8_HEX_WIDTH "2"
+#endif
+#ifndef PRINTF_INT64_DEC_WIDTH
+# define PRINTF_INT64_DEC_WIDTH "19"
+#endif
+#ifndef PRINTF_INT32_DEC_WIDTH
+# define PRINTF_INT32_DEC_WIDTH "10"
+#endif
+#ifndef PRINTF_INT16_DEC_WIDTH
+# define PRINTF_INT16_DEC_WIDTH "5"
+#endif
+#ifndef PRINTF_INT8_DEC_WIDTH
+# define PRINTF_INT8_DEC_WIDTH "3"
+#endif
+#ifndef PRINTF_UINT64_DEC_WIDTH
+# define PRINTF_UINT64_DEC_WIDTH "20"
+#endif
+#ifndef PRINTF_UINT32_DEC_WIDTH
+# define PRINTF_UINT32_DEC_WIDTH "10"
+#endif
+#ifndef PRINTF_UINT16_DEC_WIDTH
+# define PRINTF_UINT16_DEC_WIDTH "5"
+#endif
+#ifndef PRINTF_UINT8_DEC_WIDTH
+# define PRINTF_UINT8_DEC_WIDTH "3"
+#endif
+
+/*
+ *  Ok, lets not worry about 128 bit integers for now.  Moore's law says
+ *  we don't need to worry about that until about 2040 at which point
+ *  we'll have bigger things to worry about.
+ */
+
+#ifdef stdint_int64_defined
+  typedef int64_t intmax_t;
+  typedef uint64_t uintmax_t;
+# define  INTMAX_MAX   INT64_MAX
+# define  INTMAX_MIN   INT64_MIN
+# define UINTMAX_MAX  UINT64_MAX
+# define UINTMAX_C(v) UINT64_C(v)
+# define  INTMAX_C(v)  INT64_C(v)
+# ifndef PRINTF_INTMAX_MODIFIER
+#   define PRINTF_INTMAX_MODIFIER PRINTF_INT64_MODIFIER
+# endif
+# ifndef PRINTF_INTMAX_HEX_WIDTH
+#  define PRINTF_INTMAX_HEX_WIDTH PRINTF_INT64_HEX_WIDTH
+# endif
+# ifndef PRINTF_INTMAX_DEC_WIDTH
+#  define PRINTF_INTMAX_DEC_WIDTH PRINTF_INT64_DEC_WIDTH
+# endif
+#else
+  typedef int32_t intmax_t;
+  typedef uint32_t uintmax_t;
+# define  INTMAX_MAX   INT32_MAX
+# define UINTMAX_MAX  UINT32_MAX
+# define UINTMAX_C(v) UINT32_C(v)
+# define  INTMAX_C(v)  INT32_C(v)
+# ifndef PRINTF_INTMAX_MODIFIER
+#   define PRINTF_INTMAX_MODIFIER PRINTF_INT32_MODIFIER
+# endif
+# ifndef PRINTF_INTMAX_HEX_WIDTH
+#  define PRINTF_INTMAX_HEX_WIDTH PRINTF_INT32_HEX_WIDTH
+# endif
+# ifndef PRINTF_INTMAX_DEC_WIDTH
+#  define PRINTF_INTMAX_DEC_WIDTH PRINTF_INT32_DEC_WIDTH
+# endif
+#endif
+
+/*
+ *  Because this file currently only supports platforms which have
+ *  precise powers of 2 as bit sizes for the default integers, the
+ *  least definitions are all trivial.  Its possible that a future
+ *  version of this file could have different definitions.
+ */
+
+#ifndef stdint_least_defined
+  typedef   int8_t   int_least8_t;
+  typedef  uint8_t  uint_least8_t;
+  typedef  int16_t  int_least16_t;
+  typedef uint16_t uint_least16_t;
+  typedef  int32_t  int_least32_t;
+  typedef uint32_t uint_least32_t;
+# define PRINTF_LEAST32_MODIFIER PRINTF_INT32_MODIFIER
+# define PRINTF_LEAST16_MODIFIER PRINTF_INT16_MODIFIER
+# define  UINT_LEAST8_MAX  UINT8_MAX
+# define   INT_LEAST8_MAX   INT8_MAX
+# define UINT_LEAST16_MAX UINT16_MAX
+# define  INT_LEAST16_MAX  INT16_MAX
+# define UINT_LEAST32_MAX UINT32_MAX
+# define  INT_LEAST32_MAX  INT32_MAX
+# define   INT_LEAST8_MIN   INT8_MIN
+# define  INT_LEAST16_MIN  INT16_MIN
+# define  INT_LEAST32_MIN  INT32_MIN
+# ifdef stdint_int64_defined
+    typedef  int64_t  int_least64_t;
+    typedef uint64_t uint_least64_t;
+#   define PRINTF_LEAST64_MODIFIER PRINTF_INT64_MODIFIER
+#   define UINT_LEAST64_MAX UINT64_MAX
+#   define  INT_LEAST64_MAX  INT64_MAX
+#   define  INT_LEAST64_MIN  INT64_MIN
+# endif
+#endif
+#undef stdint_least_defined
+
+/*
+ *  The ANSI C committee has defined *int*_fast*_t types as well.  This,
+ *  of course, defies rationality -- you can't know what will be fast
+ *  just from the type itself.  Even for a given architecture, compatible
+ *  implementations might have different performance characteristics.
+ *  Developers are warned to stay away from these types when using this
+ *  or any other stdint.h.
+ */
+
+typedef   int_least8_t   int_fast8_t;
+typedef  uint_least8_t  uint_fast8_t;
+typedef  int_least16_t  int_fast16_t;
+typedef uint_least16_t uint_fast16_t;
+typedef  int_least32_t  int_fast32_t;
+typedef uint_least32_t uint_fast32_t;
+#define  UINT_FAST8_MAX  UINT_LEAST8_MAX
+#define   INT_FAST8_MAX   INT_LEAST8_MAX
+#define UINT_FAST16_MAX UINT_LEAST16_MAX
+#define  INT_FAST16_MAX  INT_LEAST16_MAX
+#define UINT_FAST32_MAX UINT_LEAST32_MAX
+#define  INT_FAST32_MAX  INT_LEAST32_MAX
+#define   INT_FAST8_MIN   INT_LEAST8_MIN
+#define  INT_FAST16_MIN  INT_LEAST16_MIN
+#define  INT_FAST32_MIN  INT_LEAST32_MIN
+#ifdef stdint_int64_defined
+  typedef  int_least64_t  int_fast64_t;
+  typedef uint_least64_t uint_fast64_t;
+# define UINT_FAST64_MAX UINT_LEAST64_MAX
+# define  INT_FAST64_MAX  INT_LEAST64_MAX
+# define  INT_FAST64_MIN  INT_LEAST64_MIN
+#endif
+
+#undef stdint_int64_defined
+
+/*
+ *  Whatever piecemeal, per compiler thing we can do about the wchar_t
+ *  type limits.
+ */
+
+#if defined(__WATCOMC__) || defined(_MSC_VER) || defined (__GNUC__) && !defined(vxWorks)
+# include <wchar.h>
+# ifndef WCHAR_MIN
+#  define WCHAR_MIN 0
+# endif
+# ifndef WCHAR_MAX
+#  define WCHAR_MAX ((wchar_t)-1)
+# endif
+#endif
+
+/*
+ *  Whatever piecemeal, per compiler/platform thing we can do about the
+ *  (u)intptr_t types and limits.
+ */
+
+#if (defined (_MSC_VER) && defined (_UINTPTR_T_DEFINED)) || defined (_UINTPTR_T)
+# define STDINT_H_UINTPTR_T_DEFINED
+#endif
+
+#ifndef STDINT_H_UINTPTR_T_DEFINED
+# if defined (__alpha__) || defined (__ia64__) || defined (__x86_64__) || defined (_WIN64) || defined (__ppc64__)
+#  define stdint_intptr_bits 64
+# elif defined (__WATCOMC__) || defined (__TURBOC__)
+#  if defined(__TINY__) || defined(__SMALL__) || defined(__MEDIUM__)
+#    define stdint_intptr_bits 16
+#  else
+#    define stdint_intptr_bits 32
+#  endif
+# elif defined (__i386__) || defined (_WIN32) || defined (WIN32) || defined (__ppc64__)
+#  define stdint_intptr_bits 32
+# elif defined (__INTEL_COMPILER)
+/* TODO -- what did Intel do about x86-64? */
+# else
+/* #error "This platform might not be supported yet" */
+# endif
+
+# ifdef stdint_intptr_bits
+#  define stdint_intptr_glue3_i(a,b,c)  a##b##c
+#  define stdint_intptr_glue3(a,b,c)    stdint_intptr_glue3_i(a,b,c)
+#  ifndef PRINTF_INTPTR_MODIFIER
+#    define PRINTF_INTPTR_MODIFIER      stdint_intptr_glue3(PRINTF_INT,stdint_intptr_bits,_MODIFIER)
+#  endif
+#  ifndef PTRDIFF_MAX
+#    define PTRDIFF_MAX                 stdint_intptr_glue3(INT,stdint_intptr_bits,_MAX)
+#  endif
+#  ifndef PTRDIFF_MIN
+#    define PTRDIFF_MIN                 stdint_intptr_glue3(INT,stdint_intptr_bits,_MIN)
+#  endif
+#  ifndef UINTPTR_MAX
+#    define UINTPTR_MAX                 stdint_intptr_glue3(UINT,stdint_intptr_bits,_MAX)
+#  endif
+#  ifndef INTPTR_MAX
+#    define INTPTR_MAX                  stdint_intptr_glue3(INT,stdint_intptr_bits,_MAX)
+#  endif
+#  ifndef INTPTR_MIN
+#    define INTPTR_MIN                  stdint_intptr_glue3(INT,stdint_intptr_bits,_MIN)
+#  endif
+#  ifndef INTPTR_C
+#    define INTPTR_C(x)                 stdint_intptr_glue3(INT,stdint_intptr_bits,_C)(x)
+#  endif
+#  ifndef UINTPTR_C
+#    define UINTPTR_C(x)                stdint_intptr_glue3(UINT,stdint_intptr_bits,_C)(x)
+#  endif
+  typedef stdint_intptr_glue3(uint,stdint_intptr_bits,_t) uintptr_t;
+  typedef stdint_intptr_glue3( int,stdint_intptr_bits,_t)  intptr_t;
+# else
+/* TODO -- This following is likely wrong for some platforms, and does
+   nothing for the definition of uintptr_t. */
+  typedef ptrdiff_t intptr_t;
+# endif
+# define STDINT_H_UINTPTR_T_DEFINED
+#endif
+
+/*
+ *  Assumes sig_atomic_t is signed and we have a 2s complement machine.
+ */
+
+#ifndef SIG_ATOMIC_MAX
+# define SIG_ATOMIC_MAX ((((sig_atomic_t) 1) << (sizeof (sig_atomic_t)*CHAR_BIT-1)) - 1)
+#endif
+
+#endif
+
+#if defined (__TEST_PSTDINT_FOR_CORRECTNESS)
+
+/*
+ *  Please compile with the maximum warning settings to make sure macros are
+ *  not defined more than once.
+ */
+
+#include <stdlib.h>
+#include <stdio.h>
+#include <string.h>
+
+#define glue3_aux(x,y,z) x ## y ## z
+#define glue3(x,y,z) glue3_aux(x,y,z)
+
+#define DECLU(bits) glue3(uint,bits,_t) glue3(u,bits,) = glue3(UINT,bits,_C) (0);
+#define DECLI(bits) glue3(int,bits,_t) glue3(i,bits,) = glue3(INT,bits,_C) (0);
+
+#define DECL(us,bits) glue3(DECL,us,) (bits)
+
+#define TESTUMAX(bits) glue3(u,bits,) = ~glue3(u,bits,); if (glue3(UINT,bits,_MAX) != glue3(u,bits,)) printf ("Something wrong with UINT%d_MAX\n", bits)
+
+#define REPORTERROR(msg) { err_n++; if (err_first <= 0) err_first = __LINE__; printf msg; }
+
+#define X_SIZE_MAX ((size_t)-1)
+
+int main () {
+	int err_n = 0;
+	int err_first = 0;
+	DECL(I,8)
+	DECL(U,8)
+	DECL(I,16)
+	DECL(U,16)
+	DECL(I,32)
+	DECL(U,32)
+#ifdef INT64_MAX
+	DECL(I,64)
+	DECL(U,64)
+#endif
+	intmax_t imax = INTMAX_C(0);
+	uintmax_t umax = UINTMAX_C(0);
+	char str0[256], str1[256];
+
+	sprintf (str0, "%" PRINTF_INT32_MODIFIER "d", INT32_C(2147483647));
+	if (0 != strcmp (str0, "2147483647")) REPORTERROR (("Something wrong with PRINTF_INT32_MODIFIER : %s\n", str0));
+	if (atoi(PRINTF_INT32_DEC_WIDTH) != (int) strlen(str0)) REPORTERROR (("Something wrong with PRINTF_INT32_DEC_WIDTH : %s\n", PRINTF_INT32_DEC_WIDTH));
+	sprintf (str0, "%" PRINTF_INT32_MODIFIER "u", UINT32_C(4294967295));
+	if (0 != strcmp (str0, "4294967295")) REPORTERROR (("Something wrong with PRINTF_INT32_MODIFIER : %s\n", str0));
+	if (atoi(PRINTF_UINT32_DEC_WIDTH) != (int) strlen(str0)) REPORTERROR (("Something wrong with PRINTF_UINT32_DEC_WIDTH : %s\n", PRINTF_UINT32_DEC_WIDTH));
+#ifdef INT64_MAX
+	sprintf (str1, "%" PRINTF_INT64_MODIFIER "d", INT64_C(9223372036854775807));
+	if (0 != strcmp (str1, "9223372036854775807")) REPORTERROR (("Something wrong with PRINTF_INT32_MODIFIER : %s\n", str1));
+	if (atoi(PRINTF_INT64_DEC_WIDTH) != (int) strlen(str1)) REPORTERROR (("Something wrong with PRINTF_INT64_DEC_WIDTH : %s, %d\n", PRINTF_INT64_DEC_WIDTH, (int) strlen(str1)));
+	sprintf (str1, "%" PRINTF_INT64_MODIFIER "u", UINT64_C(18446744073709550591));
+	if (0 != strcmp (str1, "18446744073709550591")) REPORTERROR (("Something wrong with PRINTF_INT32_MODIFIER : %s\n", str1));
+	if (atoi(PRINTF_UINT64_DEC_WIDTH) != (int) strlen(str1)) REPORTERROR (("Something wrong with PRINTF_UINT64_DEC_WIDTH : %s, %d\n", PRINTF_UINT64_DEC_WIDTH, (int) strlen(str1)));
+#endif
+
+	sprintf (str0, "%d %x\n", 0, ~0);
+
+	sprintf (str1, "%d %x\n",  i8, ~0);
+	if (0 != strcmp (str0, str1)) REPORTERROR (("Something wrong with i8 : %s\n", str1));
+	sprintf (str1, "%u %x\n",  u8, ~0);
+	if (0 != strcmp (str0, str1)) REPORTERROR (("Something wrong with u8 : %s\n", str1));
+	sprintf (str1, "%d %x\n",  i16, ~0);
+	if (0 != strcmp (str0, str1)) REPORTERROR (("Something wrong with i16 : %s\n", str1));
+	sprintf (str1, "%u %x\n",  u16, ~0);
+	if (0 != strcmp (str0, str1)) REPORTERROR (("Something wrong with u16 : %s\n", str1));
+	sprintf (str1, "%" PRINTF_INT32_MODIFIER "d %x\n",  i32, ~0);
+	if (0 != strcmp (str0, str1)) REPORTERROR (("Something wrong with i32 : %s\n", str1));
+	sprintf (str1, "%" PRINTF_INT32_MODIFIER "u %x\n",  u32, ~0);
+	if (0 != strcmp (str0, str1)) REPORTERROR (("Something wrong with u32 : %s\n", str1));
+#ifdef INT64_MAX
+	sprintf (str1, "%" PRINTF_INT64_MODIFIER "d %x\n",  i64, ~0);
+	if (0 != strcmp (str0, str1)) REPORTERROR (("Something wrong with i64 : %s\n", str1));
+#endif
+	sprintf (str1, "%" PRINTF_INTMAX_MODIFIER "d %x\n",  imax, ~0);
+	if (0 != strcmp (str0, str1)) REPORTERROR (("Something wrong with imax : %s\n", str1));
+	sprintf (str1, "%" PRINTF_INTMAX_MODIFIER "u %x\n",  umax, ~0);
+	if (0 != strcmp (str0, str1)) REPORTERROR (("Something wrong with umax : %s\n", str1));
+
+	TESTUMAX(8);
+	TESTUMAX(16);
+	TESTUMAX(32);
+#ifdef INT64_MAX
+	TESTUMAX(64);
+#endif
+
+#define STR(v) #v
+#define Q(v) printf ("sizeof " STR(v) " = %u\n", (unsigned) sizeof (v));
+	if (err_n) {
+		printf ("pstdint.h is not correct.  Please use sizes below to correct it:\n");
+	}
+
+	Q(int)
+	Q(unsigned)
+	Q(long int)
+	Q(short int)
+	Q(int8_t)
+	Q(int16_t)
+	Q(int32_t)
+#ifdef INT64_MAX
+	Q(int64_t)
+#endif
+
+#if UINT_MAX < X_SIZE_MAX
+	printf ("UINT_MAX < X_SIZE_MAX\n");
+#else
+	printf ("UINT_MAX >= X_SIZE_MAX\n");
+#endif
+	printf ("%" PRINTF_INT64_MODIFIER "u vs %" PRINTF_INT64_MODIFIER "u\n", UINT_MAX, X_SIZE_MAX);
+
+	return EXIT_SUCCESS;
+}
+
+#endif

compat/string.h

@@ -21,19 +21,15 @@
 
 #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);
+extern void *		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 void *		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);

compat/unistd.h

@@ -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 */

compat/waitpid.c

@@ -100,7 +100,7 @@ waitpid(
 	} else {
 	    prevPtr->nextPtr = waitPtr->nextPtr;
 	}
-	ckfree((char *) waitPtr);
+	ckfree(waitPtr);
 	return result;
     }
 

doc/AddErrInfo.3

@@ -119,7 +119,7 @@ retrieve the stack trace when script evaluation returns
 \fBTCL_ERROR\fR, like so:
 .PP
 .CS
-int code = Tcl_Eval(interp, script);
+int code = Tcl_EvalEx(interp, script, -1, 0);
 if (code == TCL_ERROR) {
     Tcl_Obj *options = \fBTcl_GetReturnOptions\fR(interp, code);
     Tcl_Obj *key = Tcl_NewStringObj("-errorinfo", -1);
@@ -247,6 +247,9 @@ record instead of a value. Otherwise, it is similar to
 .PP
 \fBTcl_SetErrorCodeVA\fR is the same as \fBTcl_SetErrorCode\fR except that
 instead of taking a variable number of arguments it takes an argument list.
+Interfaces using argument lists have been found to be nonportable in practice.
+This function is deprecated and will be removed in Tcl 9.0.
+
 .PP
 The procedure \fBTcl_GetErrorLine\fR is used to read the integer value
 of the \fB\-errorline\fR return option without the overhead of a full
@@ -305,6 +308,22 @@ The global variables \fBerrorInfo\fR and
 \fBerrorCode\fR are not modified by \fBTcl_ResetResult\fR
 so they continue to hold a record of information about the
 most recent error seen in an interpreter.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+The result of \fBTcl_GetReturnOptions\fR will have at least one
+reference to it from the Tcl interpreter. If not using it immediately,
+you should use \fBTcl_IncrRefCount\fR to add your own reference.
+.PP
+The \fIoptions\fR argument to \fBTcl_SetReturnOptions\fR will have a
+reference added by the Tcl interpreter; it may safely be called with a
+zero-reference value.
+.PP
+\fBTcl_AppendObjToErrorInfo\fR only reads its \fIobjPtr\fR argument;
+it does not modify its reference count at all.
+.PP
+The \fIerrorObjPtr\fR argument to \fBTcl_SetObjErrorCode\fR will have a
+reference added by the Tcl interpreter; it may safely be called with a
+zero-reference value.
 .SH "SEE ALSO"
 Tcl_DecrRefCount(3), Tcl_IncrRefCount(3), Tcl_Interp(3), Tcl_ResetResult(3),
 Tcl_SetErrno(3), errorCode(n), errorInfo(n)

doc/Async.3

@@ -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
@@ -17,11 +17,16 @@ Tcl_AsyncCreate, Tcl_AsyncMark, Tcl_AsyncInvoke, Tcl_AsyncDelete, Tcl_AsyncReady
 Tcl_AsyncHandler
 \fBTcl_AsyncCreate\fR(\fIproc, clientData\fR)
 .sp
+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
 \fBTcl_AsyncDelete\fR(\fIasync\fR)
 .sp
 int
@@ -34,6 +39,8 @@ Procedure to invoke to handle an asynchronous event.
 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
@@ -60,10 +67,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.
@@ -72,13 +80,16 @@ 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

doc/BoolObj.3

@@ -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,10 @@ 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)
 .SH ARGUMENTS
 .AS Tcl_Interp intValue in/out
 .AP int intValue in
@@ -32,9 +35,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 +71,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 +86,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 +103,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
 

doc/ByteArrObj.3

@@ -8,84 +8,184 @@
 .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)
 .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 int numBytes in
+The number of bytes in the array.  It must be >= 0.
 .AP Tcl_Obj *objPtr in/out
-For \fBTcl_SetByteArrayObj\fR, this points to 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 "size_t | int" *numBytesPtr out
+Points to space where the number of bytes in the array may be written.
+Caller may pass NULL when it does not need this information.
 .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 aribtrary 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.
+Note that the type of the \fInumBytes\fR argument is \fBint\fR; consequently
+the largest byte-array value that can be produced by these routines is one
+holding \fBINT_MAX\fR bytes.  Note also that the string representation of
+any Tcl value is limited to \fBINT_MAX\fR bytes, so caution should be
+taken with any byte-array of more than \fBINT_MAX / 2\fR bytes.
 .PP
-\fBTcl_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 nearly the same function as
+\fBTcl_GetBytesFromObj\fR.  They differ only in the circumstance when
+a byte-array internal value must be created by transformation of
+a string representation, and that string representation contains a
+character with codepoint greater than U+00FF.  Instead of failing
+the conversion, \fBTcl_GetByteArrayFromObj\fR will use the 8 least
+significant bits of each codepoint to produce a valid byte value
+from any character codepoint value.  In any other circumstance,
+\fBTcl_GetByteArrayFromObj\fR performs just as \fBTcl_GetBytesFromObj\fR
+does.  Since the conversion cannot fail, \fBTcl_GetByteArrayFromObj\fR
+has no need for an \fIinterp\fR argument to record any errors and
+the caller can assume \fBTcl_GetByteArrayFromObj\fR does not return NULL.
+.PP
+\fBTcl_GetByteArrayFromObj\fR must be used with caution.  Because of the
+truncation on conversion, the byte-array made available to the caller
+cannot reliably complete a round-trip back to the original string
+representation.  This creates opportunities for bugs due to blindness
+to differences in values.  This routine exists in this form primarily
+for compatibility with codebases written for earlier releases of Tcl.
+It is expected this routine will incompatibly change in Tcl 9 so that
+it also signals failed conversions with a NULL return.
+.PP
+On success, both \fBTcl_GetBytesFromObj\fR and \fBTcl_GetByteArrayFromObj\fR
+return a pointer into the internal representation of a \fBTcl_Obj\fR.
+That pointer must not be freed by the caller, and should not be retained
+for use beyond the known time the internal representation of the value
+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
+\fBsize_t\fR or of type \fBint\fR.  In Tcl 8, the largest number of
+bytes possible is \fBINT_MAX\fR, so either type can receive the value.
+In codebases meant to migrate to Tcl 9, the option to write to a space
+of type \fBsize_t\fR may aid in the migration.
+.PP
+\fBTcl_SetByteArrayLength\fR enables a caller to change the size of a
+byte-array in the internal representation of an unshared \fIobjPtr\fR to
+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_GetByteArrayFromObj\fR does, with all the cautions
+that go along with that.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_NewByteArrayObj\fR always returns a zero-reference object, much
+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

doc/Cancel.3

@@ -67,6 +67,14 @@ other procedures.  If an error is returned and this bit is set in
 result, where it can be retrieved with \fBTcl_GetObjResult\fR or
 \fBTcl_GetStringResult\fR.  If this flag bit is not set then no error
 message is left and the interpreter's result will not be modified.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_CancelEval\fR always decrements the reference count of its
+\fIresultObjPtr\fR argument (if that is non-NULL). It is expected to
+be usually called with an object with zero reference count. If the
+object is shared with some other location (including the Tcl
+evaluation stack) it should have its reference count incremented
+before calling this function.
 .SH "SEE ALSO"
 interp(n), Tcl_Eval(3),
 TIP 285

doc/Class.3

@@ -55,6 +55,14 @@ Tcl_ObjectMapMethodNameProc
 \fBTcl_ObjectGetMethodNameMapper\fR(\fIobject\fR)
 .sp
 \fBTcl_ObjectSetMethodNameMapper\fR(\fIobject\fR, \fImethodNameMapper\fR)
+.sp
+.VS "TIP 605"
+Tcl_Class
+\fBTcl_GetClassOfObject\fR(\fIobject\fR)
+.sp
+Tcl_Obj *
+\fBTcl_GetObjectClassName\fR(\fIinterp\fR, \fIobject\fR)
+.VE "TIP 605"
 .SH ARGUMENTS
 .AS ClientData metadata in/out
 .AP Tcl_Interp *interp in/out
@@ -114,6 +122,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 "TIP 605"
+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 "TIP 605"
 .PP
 Instances of classes are created using \fBTcl_NewObjectInstance\fR, which
 creates an object from any class (and which is internally called by both
@@ -241,6 +256,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

doc/CrtAlias.3

@@ -19,30 +19,24 @@ int
 int
 \fBTcl_MakeSafe\fR(\fIinterp\fR)
 .sp
-.VS "TIP 581"
 Tcl_Interp *
 \fBTcl_CreateChild\fR(\fIinterp, name, isSafe\fR)
-.VE "TIP 581"
 .sp
 Tcl_Interp *
 \fBTcl_CreateSlave\fR(\fIinterp, name, isSafe\fR)
 .sp
-.VS "TIP 581"
-Tcl_Interp *
-\fBTcl_GetChild\fR(\fIinterp, name\fR)
-.VE "TIP 581"
-.sp
 Tcl_Interp *
 \fBTcl_GetSlave\fR(\fIinterp, name\fR)
 .sp
-.VS "TIP 581"
 Tcl_Interp *
-\fBTcl_GetParent\fR(\fIinterp\fR)
-.VE "TIP 581"
+\fBTcl_GetChild\fR(\fIinterp, name\fR)
 .sp
 Tcl_Interp *
 \fBTcl_GetMaster\fR(\fIinterp\fR)
 .sp
+Tcl_Interp *
+\fBTcl_GetParent\fR(\fIinterp\fR)
+.sp
 int
 \fBTcl_GetInterpPath\fR(\fIinterp, childInterp\fR)
 .sp
@@ -136,8 +130,8 @@ interpreter. The return value for those procedures that return an \fBint\fR
 is either \fBTCL_OK\fR or \fBTCL_ERROR\fR. If \fBTCL_ERROR\fR is returned
 then the interpreter's result contains an error message.
 .PP
-\fBTcl_CreateSlave\fR creates a new interpreter as a child of \fIinterp\fR.
-It also creates a child command named \fIchildName\fR in \fIinterp\fR which
+\fBTcl_CreateChild\fR creates a new interpreter as a child of \fIinterp\fR.
+It also creates a child command named \fIname\fR in \fIinterp\fR which
 allows \fIinterp\fR to manipulate the new child.
 If \fIisSafe\fR is zero, the command creates a trusted child in which Tcl
 code has access to all the Tcl commands.
@@ -148,9 +142,7 @@ child in which Tcl code has access only to set of Tcl commands defined as
 see the manual entry for the Tcl \fBinterp\fR command for details.
 If the creation of the new child interpreter failed, \fBNULL\fR is returned.
 .PP
-.VS "TIP 581"
-\fBTcl_CreateChild\fR is a synonym for \fBTcl_CreateSlave\fR.
-.VE "TIP 581"
+\fBTcl_CreateSlave\fR is a synonym for \fBTcl_CreateChild\fR.
 .PP
 \fBTcl_IsSafe\fR returns \fB1\fR if \fIinterp\fR is
 .QW safe
@@ -166,24 +158,21 @@ from \fIinterp\fR.  However, it cannot know what parts of an extension
 or application are safe and does not make any attempt to remove those
 parts, so safety is not guaranteed after calling \fBTcl_MakeSafe\fR.
 Callers will want to take care with their use of \fBTcl_MakeSafe\fR
-to avoid false claims of safety.  For many situations, \fBTcl_CreateSlave\fR
+to avoid false claims of safety.  For many situations, \fBTcl_CreateChild\fR
 may be a better choice, since it creates interpreters in a known-safe state.
+\fBTcl_MakeSafe\fR is deprecated and will be removed in Tcl 9.0.
 .PP
-\fBTcl_GetSlave\fR returns a pointer to a child interpreter of
-\fIinterp\fR. The child interpreter is identified by \fIchildName\fR.
+\fBTcl_GetChild\fR returns a pointer to a child interpreter of
+\fIinterp\fR. The child interpreter is identified by \fIname\fR.
 If no such child interpreter exists, \fBNULL\fR is returned.
 .PP
-.VS "TIP 581"
-\fBTcl_GetChild\fR is a synonym for \fBTcl_GetSlave\fR.
-.VE "TIP 581"
+\fBTcl_GetSlave\fR is a synonym for \fBTcl_GetChild\fR.
 .PP
-\fBTcl_GetMaster\fR returns a pointer to the master interpreter of
-\fIinterp\fR. If \fIinterp\fR has no master (it is a
+\fBTcl_GetParent\fR returns a pointer to the parent interpreter of
+\fIinterp\fR. If \fIinterp\fR has no parent (it is a
 top-level interpreter) then \fBNULL\fR is returned.
 .PP
-.VS "TIP 581"
-\fBTcl_GetParent\fR is a synonym for \fBTcl_GetMaster\fR.
-.VE "TIP 581"
+\fBTcl_GetMaster\fR is a synonym for \fBTcl_GetParent\fR.
 .PP
 \fBTcl_GetInterpPath\fR stores in the result of \fIinterp\fR
 the relative path between \fIinterp\fR and \fIchildInterp\fR;
@@ -201,7 +190,7 @@ This operation returns \fBTCL_OK\fR if it succeeds, or \fBTCL_ERROR\fR if
 it fails; in that case, an error message is left in the value result
 of \fIchildInterp\fR.
 Note that there are no restrictions on the ancestry relationship (as
-created by \fBTcl_CreateSlave\fR) between \fIchildInterp\fR and
+created by \fBTcl_CreateChild\fR) between \fIchildInterp\fR and
 \fItargetInterp\fR. Any two interpreters can be used, without any
 restrictions on how they are related.
 .PP
@@ -255,8 +244,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,

doc/CrtChannel.3

@@ -35,6 +35,11 @@ Tcl_ThreadId
 int
 \fBTcl_GetChannelMode\fR(\fIchannel\fR)
 .sp
+.VS 8.7
+int
+\fBTcl_RemoveChannelMode\fR(\fIinterp, channel, mode\fR)
+.VE 8.7
+.sp
 int
 \fBTcl_GetChannelBufferSize\fR(\fIchannel\fR)
 .sp
@@ -243,6 +248,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 8.7
+.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 8.7
+.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
@@ -600,9 +615,9 @@ in preference to the \fIseekProc\fR, but both must be defined if the
 following prototype:
 .PP
 .CS
-typedef Tcl_WideInt \fBTcl_DriverWideSeekProc\fR(
+typedef long long \fBTcl_DriverWideSeekProc\fR(
         ClientData \fIinstanceData\fR,
-        Tcl_WideInt \fIoffset\fR,
+        long long \fIoffset\fR,
         int \fIseekMode\fR,
         int *\fIerrorCodePtr\fR);
 .CE
@@ -824,7 +839,7 @@ length. It can be NULL.
 .CS
 typedef int \fBTcl_DriverTruncateProc\fR(
         ClientData \fIinstanceData\fR,
-        Tcl_WideInt \fIlength\fR);
+        long long \fIlength\fR);
 .CE
 .PP
 \fIInstanceData\fR is the same as the value passed to

doc/CrtInterp.3

@@ -22,10 +22,8 @@ Tcl_Interp *
 int
 \fBTcl_InterpDeleted\fR(\fIinterp\fR)
 .sp
-.VS 8.6
 int
 \fBTcl_InterpActive\fR(\fIinterp\fR)
-.VE 8.6
 .SH ARGUMENTS
 .AS Tcl_Interp *interp
 .AP Tcl_Interp *interp in
@@ -70,14 +68,12 @@ deleted and when the whole interpreter is being deleted. In the former case
 the callback may recreate the data being deleted, but this would lead to an
 infinite loop if the interpreter were being deleted.
 .PP
-.VS 8.6
 \fBTcl_InterpActive\fR is useful for determining whether there is any
 execution of scripts ongoing in an interpreter, which is a useful piece of
 information when Tcl is embedded in a garbage-collected environment and it
 becomes necessary to determine whether the interpreter is a candidate for
 deletion. The function returns a true value if the interpreter has at least
 one active execution running inside it, and a false value otherwise.
-.VE 8.6
 .SH "INTERPRETERS AND MEMORY MANAGEMENT"
 .PP
 \fBTcl_DeleteInterp\fR can be called at any time on an interpreter that may
@@ -138,12 +134,10 @@ All uses of interpreters in Tcl and Tk have already been protected.
 Extension writers should ensure that their code also properly protects any
 additional interpreters used, as described above.
 .PP
-.VS 8.6
 Note that the protection mechanisms do not work well with conventional garbage
 collection systems. When in such a managed environment, \fBTcl_InterpActive\fR
 should be used to determine when an interpreter is a candidate for deletion
 due to inactivity.
-.VE 8.6
 .SH "SEE ALSO"
 Tcl_Preserve(3), Tcl_Release(3)
 .SH KEYWORDS

doc/CrtMathFnc.3

@@ -156,6 +156,10 @@ pointed to by \fIargTypesPointer\fR.
 \fBTcl_ListMathFuncs\fR returns a Tcl value containing a list of all
 the math functions defined in the interpreter whose name matches
 \fIpattern\fR.  The returned value has a reference count of zero.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_ListMathFuncs\fR always returns a zero-reference object, much
+like \fBTcl_NewObj\fR.
 .SH "SEE ALSO"
 expr(n), info(n), Tcl_CreateObjCommand(3), Tcl_Free(3), Tcl_NewListObj(3)
 .SH KEYWORDS

doc/CrtObjCmd.3

@@ -8,7 +8,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, Tcl_GetCommandInfo, Tcl_GetCommandInfoFromToken, Tcl_SetCommandInfo, Tcl_SetCommandInfoFromToken, Tcl_GetCommandName, Tcl_GetCommandFullName, Tcl_GetCommandFromObj \- implement new commands in C
+Tcl_CreateObjCommand, Tcl_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
@@ -42,6 +45,7 @@ void
 .sp
 Tcl_Command
 \fBTcl_GetCommandFromObj\fR(\fIinterp, objPtr\fR)
+.sp
 .SH ARGUMENTS
 .AS Tcl_CmdDeleteProc *deleteProc in/out
 .AP Tcl_Interp *interp in
@@ -51,6 +55,9 @@ 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 Tcl_ObjCmdProc2 *proc2 in
+Implementation of the new command: \fIproc2\fR will be called whenever
+\fIcmdName\fR is invoked as a command.
 .AP ClientData clientData in
 Arbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR.
 .AP Tcl_CmdDeleteProc *deleteProc in
@@ -65,6 +72,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
@@ -170,6 +180,17 @@ typedef void \fBTcl_CmdDeleteProc\fR(
 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(
+        ClientData \fIclientData\fR,
+        Tcl_Interp *\fIinterp\fR,
+        size_t \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.
@@ -296,6 +317,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

doc/CrtTrace.3

@@ -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,6 +21,9 @@ 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)
 .SH ARGUMENTS
 .AS Tcl_CmdObjTraceDeleteProc *deleteProc
@@ -38,11 +41,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 +72,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,6 +81,20 @@ 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,
+        size_t \fIlevel\fR,
+        const char *\fIcommand\fR,
+        \fBTcl_Command\fR \fIcommandToken\fR,
+        size_t \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
@@ -140,7 +160,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 +176,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 +203,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

doc/DString.3

@@ -41,6 +41,10 @@ char *
 \fBTcl_DStringResult\fR(\fIinterp, dsPtr\fR)
 .sp
 \fBTcl_DStringGetResult\fR(\fIinterp, dsPtr\fR)
+.sp
+Tcl_Obj *
+\fBTcl_DStringToObj\fR(\fIdsPtr\fR)
+.sp
 .SH ARGUMENTS
 .AS Tcl_DString newLength in/out
 .AP Tcl_DString *dsPtr in/out
@@ -142,12 +146,25 @@ 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.
 .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.
 
 .SH KEYWORDS
 append, dynamic string, free, result

doc/DictObj.3

@@ -190,6 +190,73 @@ path as this is easy to construct from repeated use of
 dictionaries are created for non-terminal keys where they do not
 already exist. With \fBTcl_DictObjRemoveKeyList\fR, all non-terminal
 keys must exist and have dictionaries as their values.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_NewDictObj\fR always returns a zero-reference object, much like
+\fBTcl_NewObj\fR.
+.PP
+\fBTcl_DictObjPut\fR does not modify the reference count of its \fIdictPtr\fR
+argument, but does require that the object be unshared.  If
+\fBTcl_DictObjPut\fR returns \fBTCL_ERROR\fR it does not manipulate any
+reference counts; but if it returns \fBTCL_OK\fR then it definitely increments
+the reference count of \fIvaluePtr\fR and may increment the reference count of
+\fIkeyPtr\fR; the latter case happens exactly when the key did not previously
+exist in the dictionary.  Note however that this function may set the
+interpreter result; if that is the only place that is holding a reference to
+an object, it will be deleted.
+.PP
+\fBTcl_DictObjGet\fR only reads from its \fIdictPtr\fR and \fIkeyPtr\fR
+arguments, and does not manipulate their reference counts at all.  If the
+\fIvaluePtrPtr\fR argument is not set to NULL (and the function doesn't return
+\fBTCL_ERROR\fR), it will be set to a value with a reference count of at least
+1, with a reference owned by the dictionary.  Note however that this function
+may set the interpreter result; if that is the only place that is holding a
+reference to an object, it will be deleted.
+.PP
+\fBTcl_DictObjRemove\fR does not modify the reference count of its
+\fIdictPtr\fR argument, but does require that the object be unshared. It does
+not manipulate the reference count of its \fIkeyPtr\fR argument at all.  Note
+however that this function may set the interpreter result; if that is the only
+place that is holding a reference to an object, it will be deleted.
+.PP
+\fBTcl_DictObjSize\fR does not modify the reference count of its \fIdictPtr\fR
+argument; it only reads.  Note however that this function may set the
+interpreter result; if that is the only place that is holding a reference to
+the dictionary object, it will be deleted.
+.PP
+\fBTcl_DictObjFirst\fR does not modify the reference count of its
+\fIdictPtr\fR argument; it only reads. The variables given by the
+\fIkeyPtrPtr\fR and \fIvaluePtrPtr\fR arguments (if not NULL) will be updated
+to contain references to the relevant values in the dictionary; their
+reference counts will be at least 1 (due to the dictionary holding a reference
+to them). It may also manipulate internal references; these are not exposed to
+user code, but require a matching \fBTcl_DictObjDone\fR call.  Note however
+that this function may set the interpreter result; if that is the only place
+that is holding a reference to the dictionary object, it will be deleted.
+.PP
+Similarly for \fBTcl_DictObjNext\fR; the variables given by the
+\fIkeyPtrPtr\fR and \fIvaluePtrPtr\fR arguments (if not NULL) will be updated
+to contain references to the relevant values in the dictionary; their
+reference counts will be at least 1 (due to the dictionary holding a reference
+to them).
+.PP
+\fBTcl_DictObjDone\fR does not manipulate (user-visible) reference counts.
+.PP
+\fBTcl_DictObjPutKeyList\fR is similar to \fBTcl_DictObjPut\fR; it does not
+modify the reference count of its \fIdictPtr\fR argument, but does require
+that the object be unshared. It may increment the reference count of any value
+passed in the \fIkeyv\fR argument, and will increment the reference count of
+the \fIvaluePtr\fR argument on success. It is recommended that values passed
+via \fIkeyv\fR and \fIvaluePtr\fR do not have zero reference counts.  Note
+however that this function may set the interpreter result; if that is the only
+place that is holding a reference to an object, it will be deleted.
+.PP
+\fBTcl_DictObjRemoveKeyList\fR is similar to \fBTcl_DictObjRemove\fR; it does
+not modify the reference count of its \fIdictPtr\fR argument, but does require
+that the object be unshared, and does not modify the reference counts of any
+of the values passed in the \fIkeyv\fR argument.  Note however that this
+function may set the interpreter result; if that is the only place that is
+holding a reference to an object, it will be deleted.
 .SH EXAMPLE
 Using the dictionary iteration interface to search determine if there
 is a key that maps to itself:

doc/DoubleObj.3

@@ -58,6 +58,18 @@ and if \fIinterp\fR is non-NULL, an error message is left in \fIinterp\fR.
 The \fBTcl_ObjType\fR of \fIobjPtr\fR may be changed to make subsequent
 calls to \fBTcl_GetDoubleFromObj\fR more efficient.
 '\" TODO: add discussion of treatment of NaN value
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_NewDoubleObj\fR always returns a zero-reference object, much
+like \fBTcl_NewObj\fR.
+.PP
+\fBTcl_SetDoubleObj\fR does not modify the reference count of its
+\fIobjPtr\fR argument, but does require that the object be unshared.
+.PP
+\fBTcl_GetDoubleFromObj\fR does not modify the reference count of its
+\fIobjPtr\fR argument; it only reads. Note however that this function
+may set the interpreter result; if that is the only place that
+is holding a reference to the object, it will be deleted.
 .SH "SEE ALSO"
 Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
 .SH KEYWORDS

doc/Encoding.3

@@ -8,7 +8,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_GetEncoding, Tcl_FreeEncoding, Tcl_GetEncodingFromObj, Tcl_ExternalToUtfDString, Tcl_ExternalToUtf, Tcl_UtfToExternalDString, Tcl_UtfToExternal, Tcl_WinTCharToUtf, Tcl_WinUtfToTChar, Tcl_GetEncodingName, Tcl_SetSystemEncoding, Tcl_GetEncodingNameFromEnvironment, Tcl_GetEncodingNames, Tcl_CreateEncoding, Tcl_GetEncodingSearchPath, Tcl_SetEncodingSearchPath, Tcl_GetDefaultEncodingDir, Tcl_SetDefaultEncodingDir \- procedures for creating and using encodings
+Tcl_GetEncoding, Tcl_FreeEncoding, Tcl_GetEncodingFromObj, Tcl_ExternalToUtfDString, Tcl_ExternalToUtf, Tcl_UtfToExternalDString, Tcl_UtfToExternal, Tcl_GetEncodingName, Tcl_SetSystemEncoding, Tcl_GetEncodingNameFromEnvironment, Tcl_GetEncodingNames, Tcl_CreateEncoding, Tcl_GetEncodingSearchPath, Tcl_SetEncodingSearchPath, Tcl_GetDefaultEncodingDir, Tcl_SetDefaultEncodingDir \- procedures for creating and using encodings
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -25,10 +25,16 @@ int
 char *
 \fBTcl_ExternalToUtfDString\fR(\fIencoding, src, srcLen, dstPtr\fR)
 .sp
+int
+\fBTcl_ExternalToUtfDStringEx\fR(\fIencoding, src, srcLen, flags, dstPtr\fR)
+.sp
 char *
 \fBTcl_UtfToExternalDString\fR(\fIencoding, src, srcLen, dstPtr\fR)
 .sp
 int
+\fBTcl_UtfToExternalDStringEx\fR(\fIencoding, src, srcLen, flags, dstPtr\fR)
+.sp
+int
 \fBTcl_ExternalToUtf\fR(\fIinterp, encoding, src, srcLen, flags, statePtr,
                   dst, dstLen, srcReadPtr, dstWrotePtr, dstCharsPtr\fR)
 .sp
@@ -46,6 +52,9 @@ const char *
 \fBTcl_GetEncodingName\fR(\fIencoding\fR)
 .sp
 int
+\fBTcl_GetEncodingNulLength\fR(\fIencoding\fR)
+.sp
+int
 \fBTcl_SetSystemEncoding\fR(\fIinterp, name\fR)
 .sp
 const char *
@@ -108,7 +117,12 @@ 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.
+automatically be substituted. The flag \fBTCL_ENCODING_STRICT\fR makes the
+encoder/decoder more strict in what it considers to be an invalid byte
+sequence. The flag \fBTCL_ENCODING_NOCOMPLAIN\fR has
+no effect, it is reserved for Tcl 9.0. The flag \fBTCL_ENCODING_MODIFIED\fR makes
+\fBTcl_UtfToExternalDStringEx\fR and \fBTcl_UtfToExternal\fR produce the
+byte sequence \exC0\ex80 in stead of \ex00, for the utf-8/cesu-8 encoders.
 .AP Tcl_EncodingState *statePtr in/out
 Used when converting a (generally long or indefinite length) byte stream
 in a piece-by-piece fashion.  The conversion routine stores its current
@@ -208,6 +222,11 @@ 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 the same as \fBTcl_ExternalToUtfDString\fR,
+but it has an additional flags parameter.  The return value is the index of
+the first byte in the input string causing a conversion error.
+Or TCL_INDEX_NONE if all is OK.
+.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.
@@ -246,6 +265,11 @@ 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 the same as \fBTcl_UtfToExternalDString\fR,
+but it has an additional flags parameter.  The return value is the index of
+the first byte of an utf-8 byte-sequence in the input string causing a
+conversion error. Or TCL_INDEX_NONE if all is OK.
+.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,11 +279,17 @@ is filled with the corresponding number of bytes that were stored in
 \fIdst\fR.  The return values are the same as the return values for
 \fBTcl_ExternalToUtf\fR.
 .PP
-\fBTcl_WinUtfToTChar\fR and \fBTcl_WinTCharToUtf\fR are
-Windows-only convenience
-functions for converting between UTF-8 and Windows strings
-based on the TCHAR type which is by convention
-a Unicode character on Windows NT.
+\fBTcl_WinUtfToTChar\fR and \fBTcl_WinTCharToUtf\fR are Windows-only
+convenience functions for converting between UTF-8 and Windows strings
+based on the TCHAR type which is by convention a Unicode character on
+Windows NT. Those functions are deprecated. You can use
+\fBTcl_UtfToWCharDString\fR resp. \fBTcl_WCharToUtfDString\fR as replacement.
+If you want compatibility with earlier Tcl releases than 8.7, use
+\fBTcl_UtfToUniCharDString\fR resp. \fBTcl_UniCharToUtfDString\fR as
+replacement, and make sure you compile your extension with -DTCL_UTF_MAX=3.
+Beware: Those replacement functions don't initialize their Tcl_DString (you'll
+have to do that yourself), and \fBTcl_UniCharToUtfDString\fR from Tcl 8.6
+doesn't accept -1 as length parameter.
 .PP
 \fBTcl_GetEncodingName\fR is roughly the inverse of \fBTcl_GetEncoding\fR.
 Given an \fIencoding\fR, the return value is the \fIname\fR argument that
@@ -267,6 +297,9 @@ 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
@@ -550,5 +583,16 @@ been loaded, it attempts to load an encoding file called \fIname\fB.enc\fR
 from the \fBencoding\fR subdirectory of each directory that Tcl searches
 for its script library.  If the encoding file exists, but is
 malformed, an error message will be left in \fIinterp\fR.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_GetEncodingFromObj\fR does not modify the reference count of its
+\fIobjPtr\fR argument; it only reads. Note however that this function may set
+the interpreter result; if that is the only place that is holding a reference
+to the object, it will be deleted.
+.PP
+\fBTcl_GetEncodingSearchPath\fR returns an object with a reference count of at
+least 1.
+.SH "SEE ALSO"
+encoding(n)
 .SH KEYWORDS
 utf, encoding, convert

doc/Ensemble.3

@@ -36,13 +36,11 @@ int
 int
 \fBTcl_SetEnsembleMappingDict\fR(\fIinterp, token, dictObj\fR)
 .sp
-.VS 8.6
 int
 \fBTcl_GetEnsembleParameterList\fR(\fIinterp, token, listObjPtr\fR)
 .sp
 int
 \fBTcl_SetEnsembleParameterList\fR(\fIinterp, token, listObj\fR)
-.VE 8.6
 .sp
 int
 \fBTcl_GetEnsembleSubcommandList\fR(\fIinterp, token, listObjPtr\fR)
@@ -163,7 +161,6 @@ All command names in prefixes set via \fBTcl_SetEnsembleMappingDict\fR
 must be fully qualified.
 .TP
 \fBformal pre-subcommand parameter list\fR (read-write)
-.VS 8.6
 A list of formal parameter names (the names only being used when generating
 error messages) that come at invocation of the ensemble between the name of
 the ensemble and the subcommand argument. NULL (the default) is equivalent to
@@ -174,7 +171,6 @@ respectively. The result of both of those functions is a Tcl result code
 ensemble) and the
 dictionary obtained from \fBTcl_GetEnsembleParameterList\fR should always be
 treated as immutable even if it is unshared.
-.VE 8.6
 .TP
 \fBsubcommand list\fR (read-write)
 .
@@ -213,6 +209,27 @@ namespace whose list of exported commands is used if both the mapping
 dictionary and the subcommand list properties are NULL. May be read
 using \fBTcl_GetEnsembleNamespace\fR which returns a Tcl result code
 (\fBTCL_OK\fR, or \fBTCL_ERROR\fR if the token does not refer to an ensemble).
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_FindEnsemble\fR does not modify the reference count of its
+\fIcmdNameObj\fR argument; it only reads. Note however that this function may
+set the interpreter result; if that is the only place that is holding a
+reference to the object, it will be deleted.
+.PP
+The ensemble property getters (\fBTcl_GetEnsembleMappingDict\fR,
+\fBTcl_GetEnsembleParameterList\fR, \fBTcl_GetEnsembleSubcommandList\fR, and
+\fBTcl_GetEnsembleUnknownHandler\fR) do not manipulate the reference count of
+the values they provide out; if those are non-NULL, they will have a reference
+count of at least 1.  Note that these functions may set the interpreter
+result.
+.PP
+The ensemble property setters (\fBTcl_SetEnsembleMappingDict\fR,
+\fBTcl_SetEnsembleParameterList\fR, \fBTcl_SetEnsembleSubcommandList\fR, and
+\fBTcl_SetEnsembleUnknownHandler\fR) will increment the reference count of the
+new value of the property they are given if they succeed (and decrement the
+reference count of the old value of the property, if relevant). If the
+property setters return \fBTCL_ERROR\fR, the reference count of the Tcl_Obj
+argument is left unchanged.
 .SH "SEE ALSO"
 namespace(n), Tcl_DeleteCommandFromToken(3)
 .SH KEYWORDS

doc/Eval.3

@@ -99,13 +99,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
@@ -150,13 +148,14 @@ equivalent to using the \fBTCL_EVAL_GLOBAL\fR flag (see below).
 of any length, concatenates them into a single string,
 then calls \fBTcl_Eval\fR to execute that string as a Tcl command.
 It returns the result of the command and also modifies
-\fIinterp->result\fR in the same way as \fBTcl_Eval\fR.
+the interpreter result in the same way as \fBTcl_Eval\fR.
 The last argument to \fBTcl_VarEval\fR must be NULL to indicate the end
 of arguments.  \fBTcl_VarEval\fR is now deprecated.
 .PP
 \fBTcl_VarEvalVA\fR is the same as \fBTcl_VarEval\fR except that
 instead of taking a variable number of arguments it takes an argument
-list. Like \fBTcl_VarEval\fR, \fBTcl_VarEvalVA\fR is deprecated.
+list. Interfaces using argument lists have been found to be nonportable
+in practice. This function is deprecated and will be removed in Tcl 9.0.
 
 .SH "FLAG BITS"
 .PP
@@ -206,6 +205,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

doc/Exit.3

@@ -134,6 +134,9 @@ finalization of Tcl's subsystems via \fBTcl_Finalize\fR at an
 appropriate time.  The argument passed to \fIproc\fR when it is
 invoked will be the exit status code (as passed to \fBTcl_Exit\fR)
 cast to a ClientData value.
+.PP
+\fBTcl_SetExitProc\fR can not be used in stub-enabled extensions. Its symbol
+entry in the stub table is deprecated and it will be removed in Tcl 9.0.
 .SH "SEE ALSO"
 exit(n)
 .SH KEYWORDS

doc/ExprLongObj.3

@@ -98,6 +98,15 @@ containing the expression's value at \fI*resultPtrPtr\fR.
 In this case, the caller is responsible for calling
 \fBTcl_DecrRefCount\fR to decrement the value's reference count
 when it is finished with the value.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_ExprLongObj\fR, \fBTcl_ExprDoubleObj\fR,
+\fBTcl_ExprBooleanObj\fR, and \fBTcl_ExprObj\fR all increment and
+decrement the reference count of their \fIobjPtr\fR arguments; you
+must not pass them any value with a reference count of zero. They also
+manipulate the interpreter result; you must not count on the
+interpreter result to hold the reference count of any value over these
+calls.
 
 .SH "SEE ALSO"
 Tcl_ExprLong, Tcl_ExprDouble, Tcl_ExprBoolean, Tcl_ExprString, Tcl_GetObjResult

doc/FileSystem.3

@@ -45,7 +45,7 @@ int
 \fBTcl_FSDeleteFile\fR(\fIpathPtr\fR)
 .sp
 int
-\fBTcl_FSRemoveDirectory\fR(\fIpathPtr, int recursive, errorPtr\fR)
+\fBTcl_FSRemoveDirectory\fR(\fIpathPtr, recursive, errorPtr\fR)
 .sp
 int
 \fBTcl_FSRenameFile\fR(\fIsrcPathPtr, destPathPtr\fR)
@@ -63,10 +63,8 @@ int
 \fBTcl_FSLoadFile\fR(\fIinterp, pathPtr, sym1, sym2, proc1Ptr, proc2Ptr,
                loadHandlePtr, unloadProcPtr\fR)
 .sp
-.VS 8.6
 int
 \fBTcl_FSUnloadFile\fR(\fIinterp, loadHandle\fR)
-.VE 8.6
 .sp
 int
 \fBTcl_FSMatchInDirectory\fR(\fIinterp, resultPtr, pathPtr, pattern, types\fR)
@@ -81,10 +79,10 @@ int
 \fBTcl_FSUtime\fR(\fIpathPtr, tval\fR)
 .sp
 int
-\fBTcl_FSFileAttrsGet\fR(\fIinterp, int index, pathPtr, objPtrRef\fR)
+\fBTcl_FSFileAttrsGet\fR(\fIinterp, index, pathPtr, objPtrRef\fR)
 .sp
 int
-\fBTcl_FSFileAttrsSet\fR(\fIinterp, int index, pathPtr, Tcl_Obj *objPtr\fR)
+\fBTcl_FSFileAttrsSet\fR(\fIinterp, index, pathPtr, objPtr\fR)
 .sp
 const char *const *
 \fBTcl_FSFileAttrStrings\fR(\fIpathPtr, objPtrRef\fR)
@@ -146,17 +144,16 @@ Tcl_Obj *
 Tcl_StatBuf *
 \fBTcl_AllocStatBuf\fR()
 .sp
-.VS 8.6
-Tcl_WideInt
+long long
 \fBTcl_GetAccessTimeFromStat\fR(\fIstatPtr\fR)
 .sp
 unsigned
 \fBTcl_GetBlockSizeFromStat\fR(\fIstatPtr\fR)
 .sp
-Tcl_WideUInt
+unsigned long long
 \fBTcl_GetBlocksFromStat\fR(\fIstatPtr\fR)
 .sp
-Tcl_WideInt
+long long
 \fBTcl_GetChangeTimeFromStat\fR(\fIstatPtr\fR)
 .sp
 int
@@ -177,15 +174,14 @@ int
 unsigned
 \fBTcl_GetModeFromStat\fR(\fIstatPtr\fR)
 .sp
-Tcl_WideInt
+long long
 \fBTcl_GetModificationTimeFromStat\fR(\fIstatPtr\fR)
 .sp
-Tcl_WideUInt
+unsigned long long
 \fBTcl_GetSizeFromStat\fR(\fIstatPtr\fR)
 .sp
 int
 \fBTcl_GetUserIdFromStat\fR(\fIstatPtr\fR)
-.VE 8.6
 .SH ARGUMENTS
 .AS Tcl_GlobTypeData **srcPathPtr out
 .AP "const Tcl_Filesystem" *fsPtr in
@@ -201,6 +197,8 @@ rename operation.
 .AP Tcl_Obj *destPathPtr in
 As for \fIpathPtr\fR, but used for the destination filename for a copy or
 rename operation.
+.AP int recursive in
+Whether to remove subdirectories and their contents as well.
 .AP "const char" *encodingName in
 The encoding of the data stored in the
 file identified by \fIpathPtr\fR and to be evaluated.
@@ -228,6 +226,10 @@ be joined together. If negative, then all elements are joined.
 .AP Tcl_Obj **errorPtr out
 In the case of an error, filled with a value containing the name of
 the file which caused an error in the various copy/rename operations.
+.AP int index in
+The index of the attribute in question.
+.AP Tcl_Obj *objPtr in
+The value to set in the operation.
 .AP Tcl_Obj **objPtrRef out
 Filled with a value containing the result of the operation.
 .AP Tcl_Obj *resultPtr out
@@ -245,9 +247,9 @@ The structure that contains the result of a stat or lstat operation.
 Name of a procedure to look up in the file's symbol table
 .AP "const char" *sym2 in
 Name of a procedure to look up in the file's symbol table
-.AP Tcl_PackageInitProc **proc1Ptr out
+.AP Tcl_LibraryInitProc **proc1Ptr out
 Filled with the init function for this code.
-.AP Tcl_PackageInitProc **proc2Ptr out
+.AP Tcl_LibraryInitProc **proc2Ptr out
 Filled with the safe-init function for this code.
 .AP ClientData *clientDataPtr out
 Filled with the clientData value to pass to this code's unload
@@ -418,23 +420,21 @@ 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.
 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 .
 \fBTcl_FSEvalFile\fR is a simpler version of
-\fBTcl_FSEvalFileEx\fR that always uses the system encoding
+\fBTcl_FSEvalFileEx\fR that always uses the utf-8 encoding
 when reading the file.
 .PP
 \fBTcl_FSLoadFile\fR dynamically loads a binary code file into memory and
@@ -444,20 +444,16 @@ belongs will be called. If that filesystem does not implement this
 function (most virtual filesystems will not, because of OS limitations
 in dynamically loading binary code), Tcl will attempt to copy the file
 to a temporary directory and load that temporary file.
-.VS 8.6
 \fBTcl_FSUnloadFile\fR reverses the operation, asking for the library
 indicated by the \fIloadHandle\fR to be removed from the process. Note that,
 unlike with the \fBunload\fR command, this does not give the library any
 opportunity to clean up.
-.VE 8.6
 .PP
 Both the above functions return a standard Tcl completion code. If an error
 occurs, an error message is left in the \fIinterp\fR's result.
 .PP
-.VS 8.6
 The token provided via the variable indicated by \fIloadHandlePtr\fR may be
 used with \fBTcl_FindSymbol\fR.
-.VE 8.6
 .PP
 \fBTcl_FSMatchInDirectory\fR is used by the globbing code to search a
 directory for all files which match a given pattern. The appropriate
@@ -795,7 +791,6 @@ may be deallocated by being passed to \fBckfree\fR). This allows extensions to
 invoke \fBTcl_FSStat\fR and \fBTcl_FSLstat\fR without being dependent on the
 size of the buffer. That in turn depends on the flags used to build Tcl.
 .PP
-.VS 8.6
 The portable fields of a \fITcl_StatBuf\fR may be read using the following
 functions, each of which returns the value of the corresponding field listed
 in the table below. Note that on some platforms there may be other fields in
@@ -819,7 +814,6 @@ for a full description of these fields.
  \fBTcl_GetBlocksFromStat\fR	 st_blocks
  \fBTcl_GetBlockSizeFromStat\fR	 st_blksize
 .DE
-.VE 8.6
 .SH "THE VIRTUAL FILESYSTEM API"
 .PP
 A filesystem provides a \fBTcl_Filesystem\fR structure that contains
@@ -1638,6 +1632,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

doc/FindExec.3

@@ -13,7 +13,7 @@ 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 *
@@ -35,6 +35,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 (e.g.,
+\fB8.7.0+abcdef...abcdef.gcc-1002.utf16\fR).
+.PP
 On UNIX platforms this procedure is typically invoked as the very
 first thing in the application's main program;  it must be passed
 \fIargv[0]\fR as its argument.  It is important not to change the
@@ -58,6 +61,8 @@ internal full path name of the executable file as computed by
 equivalent to the \fBinfo nameofexecutable\fR command.  NULL
 is returned if the internal full path name has not been
 computed or unknown.
-
+.PP
+\fBTcl_FindExecutable\fR can not be used in stub-enabled extensions. Its symbol
+entry in the stub table is deprecated and it will be removed in Tcl 9.0.
 .SH KEYWORDS
 binary, executable file

doc/GetIndex.3

@@ -27,19 +27,22 @@ Interpreter to use for error reporting; if NULL, then no message is
 provided on errors.
 .AP Tcl_Obj *objPtr in/out
 The string value of this value is used to search through \fItablePtr\fR.
-The internal representation is modified to hold the index of the matching
+If the \fBTCL_INDEX_TEMP_TABLE\fR flag is not specified,
+the internal representation is modified to hold the index of the matching
 table entry.
 .AP "const char *const" *tablePtr in
 An array of null-terminated strings.  The end of the array is marked
 by a NULL string pointer.
-Note that references to the \fItablePtr\fR may be retained in the
+Note that, unless the \fBTCL_INDEX_TEMP_TABLE\fR flag is specified,
+references to the \fItablePtr\fR may be retained in the
 internal representation of \fIobjPtr\fR, so this should represent the
 address of a statically-allocated array.
 .AP "const void" *structTablePtr in
 An array of arbitrary type, typically some \fBstruct\fR type.
 The first member of the structure must be a null-terminated string.
 The size of the structure is given by \fIoffset\fR.
-Note that references to the \fIstructTablePtr\fR may be retained in the
+Note that, unless the \fBTCL_INDEX_TEMP_TABLE\fR flag is specified,
+references to the \fIstructTablePtr\fR may be retained in the
 internal representation of \fIobjPtr\fR, so this should represent the
 address of a statically-allocated array of structures.
 .AP int offset in
@@ -50,10 +53,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 +72,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,7 +82,8 @@ error message to indicate what was being looked up.  For example,
 if \fImsg\fR is \fBoption\fR the error message will have a form like
 .QW "\fBbad option \N'34'firt\N'34': must be first, second, or third\fR" .
 .PP
-If \fBTcl_GetIndexFromObj\fR completes successfully it modifies the
+If the \fBTCL_INDEX_TEMP_TABLE\fR was not specified, when
+\fBTcl_GetIndexFromObj\fR completes successfully it modifies the
 internal representation of \fIobjPtr\fR to hold the address of
 the table and the index of the matching entry.  If \fBTcl_GetIndexFromObj\fR
 is invoked again with the same \fIobjPtr\fR and \fItablePtr\fR
@@ -84,7 +91,11 @@ arguments (e.g. during a reinvocation of a Tcl command), it returns
 the matching index immediately without having to redo the lookup
 operation.  Note: \fBTcl_GetIndexFromObj\fR assumes that the entries
 in \fItablePtr\fR are static: they must not change between
-invocations.  If the value of \fIobjPtr\fR is the empty string,
+invocations.  This caching mechanism can be disallowed by specifying
+the \fBTCL_INDEX_TEMP_TABLE\fR flag.
+If the \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 +109,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

doc/GetInt.3

@@ -22,6 +22,9 @@ int
 .sp
 int
 \fBTcl_GetBoolean\fR(\fIinterp, src, intPtr\fR)
+.sp
+int
+\fBTcl_GetBool\fR(\fIinterp, src, flags, charPtr\fR)
 .SH ARGUMENTS
 .AS Tcl_Interp *doublePtr out
 .AP Tcl_Interp *interp in
@@ -33,6 +36,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,6 +64,9 @@ after the optional white space and sign are
 .QW \fB0x\fR
 then \fIsrc\fR is expected to be in hexadecimal form;  otherwise,
 if the first such characters are
+.QW \fB0d\fR
+then \fIsrc\fR is expected to be in decimal form; otherwise,
+if the first such characters are
 .QW \fB0o\fR
 then \fIsrc\fR is expected to be in octal form;  otherwise,
 if the first such characters are
@@ -63,8 +75,8 @@ then \fIsrc\fR is expected to be in binary form;  otherwise,
 if the first such character is
 .QW \fB0\fR
 then \fIsrc\fR
-is expected to be in octal form;  otherwise, \fIsrc\fR is
-expected to be in decimal form.
+is expected to be in octal form;  otherwise, \fIsrc\fR
+is expected to be in decimal form.
 .PP
 \fBTcl_GetDouble\fR expects \fIsrc\fR to consist of a floating-point
 number, which is:  white space;  a sign; a sequence of digits;  a
@@ -94,6 +106,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

doc/Hash.3

@@ -281,7 +281,7 @@ The \fIhashKeyProc\fR member contains the address of a function called to
 calculate a hash value for the key.
 .PP
 .CS
-typedef unsigned int \fBTcl_HashKeyProc\fR(
+typedef TCL_HASH_TYPE \fBTcl_HashKeyProc\fR(
         Tcl_HashTable *\fItablePtr\fR,
         void *\fIkeyPtr\fR);
 .CE
@@ -330,5 +330,19 @@ typedef void \fBTcl_FreeHashEntryProc\fR(
 If this is NULL then \fBTcl_Free\fR is used to free the space for the entry.
 Tcl_Obj* keys use this function to decrement the reference count on the
 value.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+When a hash table is created with \fBTcl_InitCustomHashTable\fR, the
+\fBTcl_CreateHashEntry\fR function will increment the reference count of its
+\fIkey\fR argument when it creates a key (but not if there is an existing
+matching key). The reference count of the key will be decremented when the
+corresponding hash entry is deleted, whether with \fBTcl_DeleteHashEntry\fR or
+with \fBTcl_DeleteHashTable\fR. The \fBTcl_GetHashKey\fR function will return
+the key without further modifying its reference count.
+.PP
+Custom hash tables that use a Tcl_Obj* as key will generally need to do
+something similar in their \fIallocEntryProc\fR.
+.SH "SEE ALSO"
+Dict(3)
 .SH KEYWORDS
 hash table, key, lookup, search, value

doc/Init.3

@@ -2,7 +2,7 @@
 '\" Copyright (c) 1998-2000 Scriptics Corporation.
 '\" All rights reserved.
 '\"
-.TH Tcl_Init 3 8.0 Tcl "Tcl Library Procedures"
+.TH Tcl_Init 3 8.7 Tcl "Tcl Library Procedures"
 .so man.macros
 .BS
 .SH NAME
@@ -13,10 +13,15 @@ Tcl_Init \- find and source initialization script
 .sp
 int
 \fBTcl_Init\fR(\fIinterp\fR)
+.sp
+const char *
+\fBTcl_SetPreInitScript\fR(\fIscriptPtr\fR)
 .SH ARGUMENTS
 .AS Tcl_Interp *interp
 .AP Tcl_Interp *interp in
 Interpreter to initialize.
+.AP "const char" *scriptPtr in
+Address of the initialization script.
 .BE
 
 .SH DESCRIPTION
@@ -26,6 +31,13 @@ Interpreter to initialize.
 path.
 .PP
 \fBTcl_Init\fR is typically called from \fBTcl_AppInit\fR procedures.
+.PP
+\fBTcl_SetPreInitScript\fR registers the pre-initialization script and
+returns the former (now replaced) script pointer.
+A value of \fINULL\fR may be passed to not register any script.
+The pre-initialization script is executed by \fBTcl_Init\fR before accessing
+the file system. The purpose is to typically prepare a custom file system
+(like an embedded zip-file) to be activated before the search.
 
 .SH "SEE ALSO"
 Tcl_AppInit, Tcl_Main

doc/InitStubs.3

@@ -23,11 +23,11 @@ Tcl interpreter handle.
 A version string consisting of one or more decimal numbers
 separated by dots.
 .AP int exact in
-Non-zero means that only the particular version specified by
+1 means that only the particular version specified by
 \fIversion\fR is acceptable.
-Zero means that versions newer than \fIversion\fR are also
+0 means that versions newer than \fIversion\fR are also
 acceptable as long as they have the same major version number
-as \fIversion\fR.
+as \fIversion\fR. Other bits have no effect.
 .BE
 .SH INTRODUCTION
 .PP

doc/InitSubSyst.3

@@ -0,0 +1,34 @@
+'\"
+'\" Copyright (c) 2018 Tcl Core Team
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.so man.macros
+.TH Tcl_InitSubsystems 3 8.7 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_InitSubsystems \- initialize the Tcl library.
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+const char *
+\fBTcl_InitSubsystems\fR(\fIvoid\fR)
+.SH DESCRIPTION
+.PP
+The \fBTcl_InitSubsystems\fR procedure initializes the Tcl
+library. This procedure is typically invoked as the very
+first thing in the application's main program.
+.PP
+The result of \fBTcl_InitSubsystems\fR is the full Tcl version (e.g.,
+\fB8.7.0+abcdef...abcdef.gcc-1002.utf16\fR).
+.PP
+\fBTcl_InitSubsystems\fR is very similar in use to
+\fBTcl_FindExecutable\fR. It can be used when Tcl is
+used as utility library, no other encodings than utf8,
+iso8859-1 or utf-16 are used, and no interest exists in the
+value of \fBinfo nameofexecutable\fR. The system encoding will not
+be extracted from the environment, but falls back to iso8859-1.
+.SH KEYWORDS
+binary, executable file

doc/IntObj.3

@@ -8,7 +8,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, Tcl_GetIntFromObj, Tcl_GetLongFromObj, Tcl_GetWideIntFromObj, Tcl_NewBignumObj, Tcl_SetBignumObj, Tcl_GetBignumFromObj, Tcl_TakeBignumFromObj \- manipulate Tcl values as integers
+Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, Tcl_NewWideUIntObj, Tcl_NewIndexObj, Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, Tcl_SetWideUIntObj, Tcl_SetIndexObj, Tcl_GetIntFromObj, Tcl_GetIntForIndex, Tcl_GetLongFromObj, 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,37 @@ Tcl_Obj *
 Tcl_Obj *
 \fBTcl_NewWideIntObj\fR(\fIwideValue\fR)
 .sp
+Tcl_Obj *
+\fBTcl_NewWideUIntObj\fR(\fIuwideValue\fR)
+.sp
+Tcl_Obj *
+\fBTcl_NewIndexObj\fR(\fIindexValue\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
+\fBTcl_SetIndexObj\fR(\fIobjPtr, indexValue\fR)
+.sp
 int
 \fBTcl_GetIntFromObj\fR(\fIinterp, objPtr, intPtr\fR)
 .sp
 int
+\fBTcl_GetIntForIndex\fR(\fIinterp, objPtr, endValue, intPtr\fR)
+.sp
+int
 \fBTcl_GetLongFromObj\fR(\fIinterp, objPtr, longPtr\fR)
 .sp
 int
 \fBTcl_GetWideIntFromObj\fR(\fIinterp, objPtr, widePtr\fR)
 .sp
+int
+\fBTcl_GetWideUIntFromObj\fR(\fIinterp, objPtr, uwidePtr\fR)
+.sp
 .sp
 \fB#include <tclTomMath.h>\fR
 .sp
@@ -55,14 +71,22 @@ int
 \fBTcl_InitBignumFromDouble\fR(\fIinterp, doubleValue, bigValue\fR)
 .SH ARGUMENTS
 .AS Tcl_WideInt doubleValue in/out
+.AP int endValue in
+\fBTcl_GetIntForIndex\fR will return this when the input value is "end".
 .AP int intValue in
 Integer value used to initialize or set a Tcl value.
 .AP long longValue in
 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_Size indexValue in
+\fTcl_Size\f value used to initialize or set a Tcl value.
+In Tcl 8.x, \fTcl_Size\f is actually the same as int.
 .AP Tcl_Obj *objPtr in/out
 For \fBTcl_SetIntObj\fR, \fBTcl_SetLongObj\fR, \fBTcl_SetWideIntObj\fR,
+\fBTcl_SetWideUIntObj\fR, \fBTcl_SetIndexObj\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
@@ -77,6 +101,8 @@ Points to place to store the integer value retrieved from \fIobjPtr\fR.
 Points to place to store the long integer 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 mp_int *bigValue in/out
 Points to a multi-precision integer structure declared by the LibTomMath
 library.
@@ -97,23 +123,33 @@ are provided by the C language standard.  The \fBTcl_WideInt\fR type is a
 typedef defined to be whatever signed integral type covers at least the
 64-bit integer range (-9223372036854775808 to 9223372036854775807).  Depending
 on the platform and the C compiler, the actual type might be
-\fBlong int\fR, \fBlong long int\fR, \fB__int64\fR, or something else.
+\fBlong long int\fR, or something else.
 The \fBmp_int\fR type is a multiple-precision integer type defined
 by the LibTomMath multiple-precision integer library.
 .PP
 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, \fBTcl_NewIndexObj\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, \fBTcl_SetIndexObj\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
@@ -145,6 +181,27 @@ If anything later in the caller requires
 The \fBTcl_InitBignumFromDouble\fR routine is a utility procedure
 that extracts the integer part of \fIdoubleValue\fR and stores that
 integer value in the \fBmp_int\fR value \fIbigValue\fR.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_NewIntObj\fR, \fBTcl_NewLongObj\fR, \fBTcl_NewWideIntObj\fR, and
+\fBTcl_NewBignumObj\fR always return a zero-reference object, much like
+\fBTcl_NewObj\fR.
+.PP
+\fBTcl_SetIntObj\fR, \fBTcl_SetLongObj\fR, \fBTcl_SetWideIntObj\fR, and
+\fBTcl_SetBignumObj\fR do not modify the reference count of their \fIobjPtr\fR
+arguments, but do require that the object be unshared.
+.PP
+\fBTcl_GetIntFromObj\fR, \fBTcl_GetIntForIndex\fR, \fBTcl_GetLongFromObj\fR,
+\fBTcl_GetWideIntFromObj\fR, \fBTcl_GetBignumFromObj\fR, and
+\fBTcl_TakeBignumFromObj\fR do not modify the reference count of their
+\fIobjPtr\fR arguments; they only read. Note however that this function may
+set the interpreter result; if that is the only place that is holding a
+reference to the object, it will be deleted. Also note that if
+\fBTcl_TakeBignumFromObj\fR is given an unshared value, the value of that
+object may be modified; it is intended to be used when the value is
+.QW consumed
+by the operation at this point.
+
 .SH "SEE ALSO"
 Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
 .SH KEYWORDS

doc/Interp.3

@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-.TH Tcl_Interp 3 7.5 Tcl "Tcl Library Procedures"
+.TH Tcl_Interp 3 8.7 Tcl "Tcl Library Procedures"
 .so man.macros
 .BS
 .SH NAME
@@ -15,9 +15,9 @@ Tcl_Interp \- client-visible fields of interpreter structures
 \fB#include <tcl.h>\fR
 .sp
 typedef struct {
-    char *\fIresult\fR;
-    Tcl_FreeProc *\fIfreeProc\fR;
-    int \fIerrorLine\fR;
+    char *\fIresult\fR;			/* NO LONGER AVAILABLE */
+    Tcl_FreeProc *\fIfreeProc\fR;	/* NO LONGER AVAILABLE */
+    int \fIerrorLine\fR;		/* NO LONGER AVAILABLE */
 } \fBTcl_Interp\fR;
 
 typedef void \fBTcl_FreeProc\fR(
@@ -25,110 +25,17 @@ typedef void \fBTcl_FreeProc\fR(
 .BE
 .SH DESCRIPTION
 .PP
-The \fBTcl_CreateInterp\fR procedure returns a pointer to a Tcl_Interp
+The \fBTcl_CreateInterp\fR procedure returns a pointer to a \fBTcl_Interp\fR
 structure.  Callers of \fBTcl_CreateInterp\fR should use this pointer
 as an opaque token, suitable for nothing other than passing back to
-other routines in the Tcl interface.  Accessing fields directly through
-the pointer as described below is no longer supported.  The supported
-public routines \fBTcl_SetResult\fR, \fBTcl_GetResult\fR,
-\fBTcl_SetErrorLine\fR, \fBTcl_GetErrorLine\fR must be used instead.
+other routines in the Tcl interface from the same thread that called
+\fBTcl_CreateInterp\fR.  The \fBTcl_Interp\fR struct no longer has any
+supported client-visible fields.  Supported public routines such as
+\fBTcl_SetResult\fR, \fBTcl_GetResult\fR, \fBTcl_SetErrorLine\fR,
+\fBTcl_GetErrorLine\fR must be used instead.
 .PP
-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.
+Any legacy programs and extensions trying to access the fields above
+in their source code will need conversion to compile for Tcl 8.7 and later.
 
 .SH KEYWORDS
-free, initialized, interpreter, malloc, result
+interpreter, result

doc/LinkVar.3

@@ -9,7 +9,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar \- link Tcl variable to C variable
+Tcl_LinkArray, Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar \- link Tcl variable to C variable
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -17,27 +17,52 @@ Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar \- link Tcl variable to C variab
 int
 \fBTcl_LinkVar\fR(\fIinterp, varName, addr, type\fR)
 .sp
+.VS "TIP 312"
+int
+\fBTcl_LinkArray\fR(\fIinterp, varName, addr, type, size\fR)
+.VE "TIP 312"
+.sp
 \fBTcl_UnlinkVar\fR(\fIinterp, varName\fR)
 .sp
 \fBTcl_UpdateLinkedVar\fR(\fIinterp, varName\fR)
 .SH ARGUMENTS
-.AS Tcl_Interp writable
+.AS Tcl_Interp varName in
 .AP Tcl_Interp *interp in
 Interpreter that contains \fIvarName\fR.
 Also used by \fBTcl_LinkVar\fR to return error messages.
 .AP "const char" *varName in
 Name of global variable.
-.AP char *addr in
+.AP void *addr in
 Address of C variable that is to be linked to \fIvarName\fR.
+.sp
+.VS "TIP 312"
+In \fBTcl_LinkArray\fR, may be NULL to tell Tcl to create the storage
+for the array in the variable.
+.VE "TIP 312"
 .AP int type in
-Type of C variable.  Must be one of \fBTCL_LINK_INT\fR,
+Type of C variable for \fBTcl_LinkVar\fR or type of array element for
+\fBTcl_LinkArray\fR.  Must be one of \fBTCL_LINK_INT\fR,
 \fBTCL_LINK_UINT\fR, \fBTCL_LINK_CHAR\fR, \fBTCL_LINK_UCHAR\fR,
 \fBTCL_LINK_SHORT\fR, \fBTCL_LINK_USHORT\fR, \fBTCL_LINK_LONG\fR,
 \fBTCL_LINK_ULONG\fR, \fBTCL_LINK_WIDE_INT\fR,
-\fBTCL_LINK_WIDE_UINT\fR, \fBTCL_LINK_FLOAT\fR,
-\fBTCL_LINK_DOUBLE\fR, \fBTCL_LINK_BOOLEAN\fR, or
-\fBTCL_LINK_STRING\fR, optionally OR'ed with \fBTCL_LINK_READ_ONLY\fR
-to make Tcl variable read-only.
+\fBTCL_LINK_WIDE_UINT\fR, \fBTCL_LINK_FLOAT\fR, \fBTCL_LINK_DOUBLE\fR,
+\fBTCL_LINK_BOOLEAN\fR, or one of the extra ones listed below.
+.sp
+In \fBTcl_LinkVar\fR, the additional linked type \fBTCL_LINK_STRING\fR may be
+used.
+.sp
+.VS "TIP 312"
+In \fBTcl_LinkArray\fR, the additional linked types \fBTCL_LINK_CHARS\fR and
+\fBTCL_LINK_BINARY\fR may be used.
+.VE "TIP 312"
+.sp
+All the above for both functions may be
+optionally OR'ed with \fBTCL_LINK_READ_ONLY\fR to make the Tcl
+variable read-only.
+.AP int size in
+.VS "TIP 312"
+The number of elements in the C array. Must be greater than zero.
+.VE "TIP 312"
 .BE
 .SH DESCRIPTION
 .PP
@@ -52,130 +77,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 "TIP 312"
+\fBTcl_LinkArray\fR is similar, but for arrays of fixed size (given by
+the \fIsize\fR argument). When asked to allocate the backing C array
+storage (via the \fIaddr\fR argument being NULL), it writes the
+address that it allocated to the Tcl interpreter result.
+.VE "TIP 312"
+.PP
 The \fItype\fR argument specifies the type of the C variable,
+or the type of the elements of the C array,
 and must have one of the following values, optionally OR'ed with
 \fBTCL_LINK_READ_ONLY\fR:
 .TP
 \fBTCL_LINK_INT\fR
-The C variable is of type \fBint\fR.
+.
+The C variable, or each element of the C array, is of type \fBint\fR.
 Any value written into the Tcl variable must have a proper integer
 form acceptable to \fBTcl_GetIntFromObj\fR;  attempts to write
 non-integer values into \fIvarName\fR will be rejected with
 Tcl errors. Incomplete integer representations (like the empty
-string, '+', '-' or the hex/octal/binary prefix) are accepted
+string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted
 as if they are valid too.
 .TP
 \fBTCL_LINK_UINT\fR
-The C variable is of type \fBunsigned int\fR.
+.
+The C variable, or each element of the C array, is of type \fBunsigned int\fR.
 Any value written into the Tcl variable must have a proper unsigned
 integer form acceptable to \fBTcl_GetWideIntFromObj\fR and in the
 platform's defined range for the \fBunsigned int\fR type; attempts to
 write non-integer values (or values outside the range) into
 \fIvarName\fR will be rejected with Tcl errors. Incomplete integer
-representations (like the empty string, '+', '-' or the hex/octal/binary
+representations (like the empty string, '+', '-' or the hex/octal/decimal/binary
 prefix) are accepted as if they are valid too.
 .TP
 \fBTCL_LINK_CHAR\fR
-The C variable is of type \fBchar\fR.
+.
+The C variable, or each element of the C array, is of type \fBchar\fR.
 Any value written into the Tcl variable must have a proper integer
 form acceptable to \fBTcl_GetIntFromObj\fR and be in the range of the
 \fBchar\fR datatype; attempts to write non-integer or out-of-range
 values into \fIvarName\fR will be rejected with Tcl errors. Incomplete
 integer representations (like the empty string, '+', '-' or the
-hex/octal/binary prefix) are accepted as if they are valid too.
+hex/octal/decimal/binary prefix) are accepted as if they are valid too.
+.RS
+.PP
+.VS "TIP 312"
+If using an array of these, consider using \fBTCL_LINK_CHARS\fR instead.
+.VE "TIP 312"
+.RE
+.TP
+\fBTCL_LINK_CHARS\fR
+.VS "TIP 312"
+The C array is of type \fBchar *\fR and is mapped into Tcl as a string.
+Any value written into the Tcl variable must have the same length as
+the underlying storage. Only supported with \fBTcl_LinkArray\fR.
+.VE "TIP 312"
 .TP
 \fBTCL_LINK_UCHAR\fR
-The C variable is of type \fBunsigned char\fR.
+.
+The C variable, or each element of the C array, is of type \fBunsigned char\fR.
 Any value written into the Tcl variable must have a proper unsigned
 integer form acceptable to \fBTcl_GetIntFromObj\fR and in the
 platform's defined range for the \fBunsigned char\fR type; attempts to
 write non-integer values (or values outside the range) into
 \fIvarName\fR will be rejected with Tcl errors. Incomplete integer
-representations (like the empty string, '+', '-' or the hex/octal/binary
+representations (like the empty string, '+', '-' or the hex/octal/decimal/binary
 prefix) are accepted as if they are valid too.
+.RS
+.PP
+.VS "TIP 312"
+If using an array of these, consider using \fBTCL_LINK_BINARY\fR instead.
+.VE "TIP 312"
+.RE
+.TP
+\fBTCL_LINK_BINARY\fR
+.VS "TIP 312"
+The C array is of type \fBunsigned char *\fR and is mapped into Tcl
+as a bytearray.
+Any value written into the Tcl variable must have the same length as
+the underlying storage. Only supported with \fBTcl_LinkArray\fR.
+.VE "TIP 312"
 .TP
 \fBTCL_LINK_SHORT\fR
-The C variable is of type \fBshort\fR.
+.
+The C variable, or each element of the C array, is of type \fBshort\fR.
 Any value written into the Tcl variable must have a proper integer
 form acceptable to \fBTcl_GetIntFromObj\fR and be in the range of the
 \fBshort\fR datatype; attempts to write non-integer or out-of-range
 values into \fIvarName\fR will be rejected with Tcl errors. Incomplete
 integer representations (like the empty string, '+', '-' or the
-hex/octal/binary prefix) are accepted as if they are valid too.
+hex/octal/decimal/binary prefix) are accepted as if they are valid too.
 .TP
 \fBTCL_LINK_USHORT\fR
-The C variable is of type \fBunsigned short\fR.
+.
+The C variable, or each element of the C array, is of type \fBunsigned short\fR.
 Any value written into the Tcl variable must have a proper unsigned
 integer form acceptable to \fBTcl_GetIntFromObj\fR and in the
 platform's defined range for the \fBunsigned short\fR type; attempts to
 write non-integer values (or values outside the range) into
 \fIvarName\fR will be rejected with Tcl errors. Incomplete integer
-representations (like the empty string, '+', '-' or the hex/octal/binary
+representations (like the empty string, '+', '-' or the hex/octal/decimal/binary
 prefix) are accepted as if they are valid too.
 .TP
 \fBTCL_LINK_LONG\fR
-The C variable is of type \fBlong\fR.
+.
+The C variable, or each element of the C array, is of type \fBlong\fR.
 Any value written into the Tcl variable must have a proper integer
 form acceptable to \fBTcl_GetLongFromObj\fR; attempts to write
 non-integer or out-of-range
 values into \fIvarName\fR will be rejected with Tcl errors. Incomplete
 integer representations (like the empty string, '+', '-' or the
-hex/octal/binary prefix) are accepted as if they are valid too.
+hex/octal/decimal/binary prefix) are accepted as if they are valid too.
 .TP
 \fBTCL_LINK_ULONG\fR
-The C variable is of type \fBunsigned long\fR.
+.
+The C variable, or each element of the C array, is of type \fBunsigned long\fR.
 Any value written into the Tcl variable must have a proper unsigned
 integer form acceptable to \fBTcl_GetWideIntFromObj\fR and in the
 platform's defined range for the \fBunsigned long\fR type; attempts to
 write non-integer values (or values outside the range) into
 \fIvarName\fR will be rejected with Tcl errors. Incomplete integer
-representations (like the empty string, '+', '-' or the hex/octal/binary
+representations (like the empty string, '+', '-' or the hex/octal/decimal/binary
 prefix) are accepted as if they are valid too.
 .TP
 \fBTCL_LINK_DOUBLE\fR
-The C variable is of type \fBdouble\fR.
+.
+The C variable, or each element of the C array, is of type \fBdouble\fR.
 Any value written into the Tcl variable must have a proper real
 form acceptable to \fBTcl_GetDoubleFromObj\fR;  attempts to write
 non-real values into \fIvarName\fR will be rejected with
 Tcl errors. Incomplete integer or real representations (like the
-empty string, '.', '+', '-' or the hex/octal/binary prefix) are
+empty string, '.', '+', '-' or the hex/octal/decimal/binary prefix) are
 accepted as if they are valid too.
 .TP
 \fBTCL_LINK_FLOAT\fR
-The C variable is of type \fBfloat\fR.
+.
+The C variable, or each element of the C array, is of type \fBfloat\fR.
 Any value written into the Tcl variable must have a proper real
 form acceptable to \fBTcl_GetDoubleFromObj\fR and must be within the
 range acceptable for a \fBfloat\fR; attempts to
 write non-real values (or values outside the range) into
 \fIvarName\fR will be rejected with Tcl errors. Incomplete integer
 or real representations (like the empty string, '.', '+', '-' or
-the hex/octal/binary prefix) are accepted as if they are valid too.
+the hex/octal/decimal/binary prefix) are accepted as if they are valid too.
 .TP
 \fBTCL_LINK_WIDE_INT\fR
-The C variable is of type \fBTcl_WideInt\fR (which is an integer type
+.
+The C variable, or each element of the C array, is of type \fBTcl_WideInt\fR
+(which is an integer type
 at least 64-bits wide on all platforms that can support it.)
 Any value written into the Tcl variable must have a proper integer
 form acceptable to \fBTcl_GetWideIntFromObj\fR;  attempts to write
 non-integer values into \fIvarName\fR will be rejected with
 Tcl errors. Incomplete integer representations (like the empty
-string, '+', '-' or the hex/octal/binary prefix) are accepted
+string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted
 as if they are valid too.
 .TP
 \fBTCL_LINK_WIDE_UINT\fR
-The C variable is of type \fBTcl_WideUInt\fR (which is an unsigned
-integer type at least 64-bits wide on all platforms that can support
-it.)
+.
+The C variable, or each element of the C array, is of type \fBTcl_WideUInt\fR
+(which is an unsigned integer type at least 64-bits wide on all platforms that
+can support it.)
 Any value written into the Tcl variable must have a proper unsigned
-integer form acceptable to \fBTcl_GetWideIntFromObj\fR (it will be
-cast to unsigned);
-.\" FIXME! Use bignums instead.
+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,6 +260,7 @@ non-boolean values into \fIvarName\fR will be rejected with
 Tcl errors.
 .TP
 \fBTCL_LINK_STRING\fR
+.
 The C variable is of type \fBchar *\fR.
 If its value is not NULL then it must be a pointer to a string
 allocated with \fBTcl_Alloc\fR or \fBckalloc\fR.
@@ -197,6 +270,7 @@ new value.
 If the C variable contains a NULL pointer then the Tcl variable
 will read as
 .QW NULL .
+This is only supported by \fBTcl_LinkVar\fR.
 .PP
 If the \fBTCL_LINK_READ_ONLY\fR flag is present in \fItype\fR then the
 variable will be read-only from Tcl, so that its value can only be

doc/ListObj.3

@@ -246,6 +246,31 @@ with a NULL \fIobjvPtr\fR:
 result = \fBTcl_ListObjReplace\fR(interp, listPtr, first, count,
         0, NULL);
 .CE
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_NewListObj\fR always returns a zero-reference object, much like
+\fBTcl_NewObj\fR. If a non-NULL \fIobjv\fR argument is given, the reference
+counts of the first \fIobjc\fR values in that array are incremented.
+.PP
+\fBTcl_SetListObj\fR does not modify the reference count of its \fIobjPtr\fR
+argument, but does require that the object be unshared. The reference counts
+of the first \fIobjc\fR values in the \fIobjv\fR array are incremented.
+.PP
+\fBTcl_ListObjGetElements\fR, \fBTcl_ListObjIndex\fR, and
+\fBTcl_ListObjLength\fR do not modify the reference count of their
+\fIlistPtr\fR arguments; they only read. Note however that these three
+functions may set the interpreter result; if that is the only place that is
+holding a reference to the object, it will be deleted.
+.PP
+\fBTcl_ListObjAppendList\fR, \fBTcl_ListObjAppendElement\fR, and
+\fBTcl_ListObjReplace\fR require an unshared \fIlistPtr\fR argument.
+\fBTcl_ListObjAppendList\fR only reads its \fIelemListPtr\fR argument.
+\fBTcl_ListObjAppendElement\fR increments the reference count of its
+\fIobjPtr\fR on success. \fBTcl_ListObjReplace\fR increments the reference
+count of the first \fIobjc\fR values in the \fIobjv\fR array on success.  Note
+however that all these three functions may set the interpreter result on
+failure; if that is the only place that is holding a reference to the object,
+it will be deleted.
 .SH "SEE ALSO"
 Tcl_NewObj(3), Tcl_DecrRefCount(3), Tcl_IncrRefCount(3), Tcl_GetObjResult(3)
 .SH KEYWORDS

doc/Load.3

@@ -60,6 +60,10 @@ be unloaded with \fBTcl_FSUnloadFile\fR.
 the symbol cannot be found, it returns NULL and sets an error message in the
 given \fIinterp\fR (if that is non-NULL). Note that it is unsafe to use this
 operation on a handle that has been passed to \fBTcl_FSUnloadFile\fR.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+The reference count of the \fIpathPtr\fR argument to \fBTcl_LoadFile\fR may be
+incremented. As such, it should not be given a zero reference count value.
 .SH "SEE ALSO"
 Tcl_FSLoadFile(3), Tcl_FSUnloadFile(3), load(n), unload(n)
 .SH KEYWORDS

doc/Method.3

@@ -9,18 +9,18 @@
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-Tcl_ClassSetConstructor, Tcl_ClassSetDestructor, Tcl_MethodDeclarerClass, Tcl_MethodDeclarerObject, Tcl_MethodIsPublic, Tcl_MethodIsType, Tcl_MethodName, Tcl_NewInstanceMethod, Tcl_NewMethod, Tcl_ObjectContextInvokeNext, Tcl_ObjectContextIsFiltering, Tcl_ObjectContextMethod, Tcl_ObjectContextObject, Tcl_ObjectContextSkippedArgs \- manipulate methods and method-call contexts
+Tcl_ClassSetConstructor, Tcl_ClassSetDestructor, Tcl_MethodDeclarerClass, Tcl_MethodDeclarerObject, Tcl_MethodIsPublic, Tcl_MethodIsPrivate, Tcl_MethodIsType, Tcl_MethodName, Tcl_NewInstanceMethod, Tcl_NewMethod, Tcl_ObjectContextInvokeNext, Tcl_ObjectContextIsFiltering, Tcl_ObjectContextMethod, Tcl_ObjectContextObject, Tcl_ObjectContextSkippedArgs \- manipulate methods and method-call contexts
 .SH SYNOPSIS
 .nf
 \fB#include <tclOO.h>\fR
 .sp
 Tcl_Method
-\fBTcl_NewMethod\fR(\fIinterp, class, nameObj, isPublic,
-              methodTypePtr, clientData\fR)
+\fBTcl_NewMethod\fR(\fIinterp, class, nameObj, flags, methodTypePtr,
+              clientData\fR)
 .sp
 Tcl_Method
-\fBTcl_NewInstanceMethod\fR(\fIinterp, object, nameObj, isPublic,
-                      methodTypePtr, clientData\fR)
+\fBTcl_NewInstanceMethod\fR(\fIinterp, object, nameObj, flags, methodTypePtr,
+                      clientData\fR)
 .sp
 \fBTcl_ClassSetConstructor\fR(\fIinterp, class, method\fR)
 .sp
@@ -35,8 +35,13 @@ Tcl_Object
 Tcl_Obj *
 \fBTcl_MethodName\fR(\fImethod\fR)
 .sp
+.VS TIP500
 int
 \fBTcl_MethodIsPublic\fR(\fImethod\fR)
+.VE TIP500
+.sp
+int
+\fBTcl_MethodIsPrivate\fR(\fImethod\fR)
 .sp
 int
 \fBTcl_MethodIsType\fR(\fImethod, methodTypePtr, clientDataPtr\fR)
@@ -66,10 +71,15 @@ The class to create the method in.
 .AP Tcl_Obj *nameObj in
 The name of the method to create. Should not be NULL unless creating
 constructors or destructors.
-.AP int isPublic in
-A flag saying what the visibility of the method is. The only supported public
-values of this flag are 0 for a non-exported method, and 1 for an exported
-method.
+.AP int flags in
+A flag saying (currently) what the visibility of the method is. The supported
+public values of this flag are \fBTCL_OO_METHOD_PUBLIC\fR (which is fixed at 1
+for backward compatibility) for an exported method,
+\fBTCL_OO_METHOD_UNEXPORTED\fR (which is fixed at 0 for backward
+compatibility) for a non-exported method,
+.VS TIP500
+and \fBTCL_OO_METHOD_PRIVATE\fR for a private method.
+.VE TIP500
 .AP Tcl_MethodType *methodTypePtr in
 A description of the type of the method to create, or the type of method to
 compare against.
@@ -105,8 +115,12 @@ Given a method, the entity that declared it can be found using
 attached to (or NULL if the method is not attached to any class) and
 \fBTcl_MethodDeclarerObject\fR which returns the object that the method is
 attached to (or NULL if the method is not attached to an object). The name of
-the method can be retrieved with \fBTcl_MethodName\fR and whether the method
-is exported is retrieved with \fBTcl_MethodIsPublic\fR. The type of the method
+the method can be retrieved with \fBTcl_MethodName\fR, whether the method
+is exported is retrieved with \fBTcl_MethodIsPublic\fR,
+.VS TIP500
+and whether the method is private is retrieved with \fBTcl_MethodIsPrivate\fR.
+.VE TIP500
+The type of the method
 can also be introspected upon to a limited degree; the function
 \fBTcl_MethodIsType\fR returns whether a method is of a particular type,
 assigning the per-method \fIclientData\fR to the variable pointed to by
@@ -117,8 +131,12 @@ Methods are created by \fBTcl_NewMethod\fR and \fBTcl_NewInstanceMethod\fR,
 which
 create a method attached to a class or an object respectively. In both cases,
 the \fInameObj\fR argument gives the name of the method to create, the
-\fIisPublic\fR argument states whether the method should be exported
-initially, the \fImethodTypePtr\fR argument describes the implementation of
+\fIflags\fR argument states whether the method should be exported
+initially
+.VS TIP500
+or be marked as a private method,
+.VE TIP500
+the \fImethodTypePtr\fR argument describes the implementation of
 the method (see the \fBMETHOD TYPES\fR section below) and the \fIclientData\fR
 argument gives some implementation-specific data that is passed on to the
 implementation of the method when it is called.
@@ -240,8 +258,32 @@ also return TCL_ERROR; it should return TCL_OK otherwise.
 The \fIoldClientData\fR field to a Tcl_CloneProc gives the value from the
 method being copied from, and the \fInewClientDataPtr\fR field will point to
 a variable in which to write the value for the method being copied to.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+The \fInameObj\fR argument to \fBTcl_NewMethod\fR and
+\fBTcl_NewInstanceMethod\fR (when non-NULL) will have its reference count
+incremented if there is no existing method with that name in that
+class/object.
+.PP
+The result of \fBTcl_MethodName\fR is a value with a reference count of at
+least one. It should not be modified without first duplicating it (with
+\fBTcl_DuplicateObj\fR).
+.PP
+The values in the first \fIobjc\fR values of the \fIobjv\fR argument to
+\fBTcl_ObjectContextInvokeNext\fR are assumed to have a reference count of at
+least 1; the containing array is assumed to endure until the next method
+implementation (see \fBnext\fR) returns. Be aware that methods may
+\fByield\fR; if any post-call actions are desired (e.g., decrementing the
+reference count of values passed in here), they must be scheduled with
+\fBTcl_NRAddCallback\fR.
+.PP
+The \fIcallProc\fR of the \fBTcl_MethodType\fR structure takes values of at
+least reference count 1 in its \fIobjv\fR argument. It may add its own
+references, but must not decrement the reference count below that level; the
+caller of the method will decrement the reference count once the method
+returns properly (and the reference will be held if the method \fByield\fRs).
 .SH "SEE ALSO"
-Class(3), oo::class(n), oo::define(n), oo::object(n)
+Class(3), NRE(3), oo::class(n), oo::define(n), oo::object(n)
 .SH KEYWORDS
 constructor, method, object
 

doc/NRE.3

@@ -9,7 +9,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_NRCreateCommand, Tcl_NRCallObjProc, Tcl_NREvalObj, Tcl_NREvalObjv, Tcl_NRCmdSwap, Tcl_NRExprObj, Tcl_NRAddCallback \- Non-Recursive (stackless) evaluation of Tcl scripts.
+Tcl_NRCreateCommand, Tcl_NRCreateCommand2, Tcl_NRCallObjProc, Tcl_NRCallObjProc2, Tcl_NREvalObj, Tcl_NREvalObjv, Tcl_NRCmdSwap, Tcl_NRExprObj, Tcl_NRAddCallback \- Non-Recursive (stackless) evaluation of Tcl scripts.
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -18,10 +18,17 @@ Tcl_Command
 \fBTcl_NRCreateCommand\fR(\fIinterp, cmdName, proc, nreProc, clientData,
                     deleteProc\fR)
 .sp
+Tcl_Command
+\fBTcl_NRCreateCommand2\fR(\fIinterp, cmdName, proc2, nreProc2, clientData,
+                    deleteProc\fR)
+.sp
 int
 \fBTcl_NRCallObjProc\fR(\fIinterp, nreProc, clientData, objc, objv\fR)
 .sp
 int
+\fBTcl_NRCallObjProc2\fR(\fIinterp, nreProc2, clientData, objc, objv\fR)
+.sp
+int
 \fBTcl_NREvalObj\fR(\fIinterp, objPtr, flags\fR)
 .sp
 int
@@ -47,8 +54,15 @@ Called in order to evaluate a command.  Is often just a small wrapper that uses
 \fBTcl_NRCallObjProc\fR to call \fInreProc\fR using a new trampoline.  Behaves
 in the same way as the \fIproc\fR argument to \fBTcl_CreateObjCommand\fR(3)
 (\fIq.v.\fR).
+.AP Tcl_ObjCmdProc2 *proc2 in
+Called in order to evaluate a command.  Is often just a small wrapper that uses
+\fBTcl_NRCallObjProc2\fR to call \fInreProc2\fR using a new trampoline.  Behaves
+in the same way as the \fIproc2\fR argument to \fBTcl_CreateObjCommand2\fR(3)
+(\fIq.v.\fR).
 .AP Tcl_ObjCmdProc *nreProc in
 Called instead of \fIproc\fR when a trampoline is already in use.
+.AP Tcl_ObjCmdProc2 *nreProc2 in
+Called instead of \fIproc2\fR when a trampoline is already in use.
 .AP ClientData clientData in
 Arbitrary one-word value passed to \fIproc\fR, \fInreProc\fR, \fIdeleteProc\fR
 and \fIobjProc\fR.
@@ -104,6 +118,9 @@ first deleted.  If \fIinterp\fR is in the process of being deleted
 \fBTcl_NRCreateCommand\fR does not create any command, does not delete any
 command, and returns NULL.
 .PP
+\fBTcl_NRCreateCommand2\fR, is an alternative to \fBTcl_NRCreateCommand\fR
+in the same way as \fBTcl_CreateObjCommand2\fR.
+.PP
 \fBTcl_NREvalObj\fR pushes a function that is like \fBTcl_EvalObjEx\fR but
 consumes no space on the C stack.
 .PP
@@ -227,6 +244,25 @@ int
 Any function comprising a routine can push other functions, making it possible
 implement looping and sequencing constructs using the function stack.
 .PP
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+The first \fIobjc\fR values in the \fIobjv\fR array passed to the functions
+\fBTcl_NRCallObjProc\fR, \fBTcl_NREvalObjv\fR, and \fBTcl_NRCmdSwap\fR should
+have a reference count of at least 1; they may have additional references
+taken during the execution.
+.PP
+The \fIobjPtr\fR argument to \fBTcl_NREvalObj\fR and \fBTcl_NRExprObj\fR
+should have a reference count of at least 1, and may have additional
+references taken to it during execution.
+.PP
+The \fIresultObj\fR argument to \fBTcl_NRExprObj\fR should be an unshared
+object.
+.PP
+Use \fBTcl_NRAddCallback\fR to schedule any required final decrementing of the
+reference counts of arguments to any of the other functions on this page, as
+with any other post-processing step in the non-recursive execution engine.
+.PP
+The
 .SH "SEE ALSO"
 Tcl_CreateCommand(3), Tcl_CreateObjCommand(3), Tcl_EvalObjEx(3), Tcl_GetCommandFromObj(3), Tcl_ExprObj(3)
 .SH KEYWORDS

doc/Namespace.3

@@ -46,10 +46,10 @@ Tcl_Command
 \fBTcl_FindCommand\fR(\fIinterp, name, contextNsPtr, flags\fR)
 .sp
 Tcl_Obj *
-\fBTcl_GetNamespaceUnknownHandler(\fIinterp, nsPtr\fR)
+\fBTcl_GetNamespaceUnknownHandler\fR(\fIinterp, nsPtr\fR)
 .sp
 int
-\fBTcl_SetNamespaceUnknownHandler(\fIinterp, nsPtr, handlerPtr\fR)
+\fBTcl_SetNamespaceUnknownHandler\fR(\fIinterp, nsPtr, handlerPtr\fR)
 .SH ARGUMENTS
 .AS Tcl_NamespaceDeleteProc allowOverwrite in/out
 .AP Tcl_Interp *interp in/out
@@ -159,6 +159,18 @@ for the namespace, or NULL if none is set.
 \fBTcl_SetNamespaceUnknownHandler\fR sets the unknown command handler for
 the namespace. If \fIhandlerPtr\fR is NULL, then the handler is reset to
 its default.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+The \fIobjPtr\fR argument to \fBTcl_AppendExportList\fR should be an
+unshared object, as it will be modified by this function. The
+reference count of \fIobjPtr\fR will not be altered.
+.PP
+\fBTcl_GetNamespaceUnknownHandler\fR returns a possibly shared value.
+Its reference count should be incremented if the value is to be
+retained.
+.PP
+The \fIhandlerPtr\fR argument to \fBTcl_SetNamespaceUnknownHandler\fR
+will have its reference count incremented if it is a non-empty list.
 .SH "SEE ALSO"
 Tcl_CreateCommand(3), Tcl_ListObjAppendList(3), Tcl_SetVar(3)
 .SH KEYWORDS

doc/Notifier.3

@@ -90,9 +90,10 @@ necessary.
 .AP Tcl_Event *evPtr in
 An event to add to the event queue.  The storage for the event must
 have been allocated by the caller using \fBTcl_Alloc\fR or \fBckalloc\fR.
-.AP Tcl_QueuePosition position in
+.AP int position in
 Where to add the new event in the queue:  \fBTCL_QUEUE_TAIL\fR,
-\fBTCL_QUEUE_HEAD\fR, or \fBTCL_QUEUE_MARK\fR.
+\fBTCL_QUEUE_HEAD\fR, \fBTCL_QUEUE_MARK\fR, and whether to do
+an alert if the queue is empty: \fBTCL_QUEUE_ALERT_IF_EMPTY\fR.
 .AP Tcl_ThreadId threadId in
 A unique identifier for a thread.
 .AP Tcl_EventDeleteProc *deleteProc in
@@ -103,7 +104,7 @@ passed to \fBTcl_DoOneEvent\fR.
 .AP int mode in
 Indicates whether events should be serviced by \fBTcl_ServiceAll\fR.
 Must be one of \fBTCL_SERVICE_NONE\fR or \fBTCL_SERVICE_ALL\fR.
-.AP Tcl_NotifierProcs* notifierProcPtr in
+.AP const Tcl_NotifierProcs* notifierProcPtr in
 Structure of function pointers describing notifier procedures that are
 to replace the ones installed in the executable.  See
 \fBREPLACING THE NOTIFIER\fR for details.
@@ -132,22 +133,17 @@ higher-level software that they have occurred.  The procedures
 and \fBTcl_SetMaxBlockTime\fR, \fBTcl_QueueEvent\fR, and
 \fBTcl_DeleteEvents\fR are used primarily by event sources.
 .IP [2]
-The event queue: for non-threaded applications,
-there is a single queue for the whole application,
-containing events that have been detected but not yet serviced.  Event
-sources place events onto the queue so that they may be processed in
-order at appropriate times during the event loop. The event queue
-guarantees a fair discipline of event handling, so that no event
-source can starve the others.  It also allows events to be saved for
-servicing at a future time.  Threaded applications work in a
-similar manner, except that there is a separate event queue for
-each thread containing a Tcl interpreter.
+The event queue: there is a single queue for each thread containing
+a Tcl interpreter, containing events that have been detected but not
+yet serviced.  Event sources place events onto the queue so that they
+may be processed in order at appropriate times during the event loop.
+The event queue guarantees a fair discipline of event handling, so that
+no event source can starve the others.  It also allows events to be
+saved for servicing at a future time.
 \fBTcl_QueueEvent\fR is used (primarily
-by event sources) to add events to the event queue and
+by event sources) to add events to the current thread's event queue and
 \fBTcl_DeleteEvents\fR is used to remove events from the queue without
-processing them.  In a threaded application, \fBTcl_QueueEvent\fR adds
-an event to the current thread's queue, and \fBTcl_ThreadQueueEvent\fR
-adds an event to a queue in a specific thread.
+processing them.
 .IP [3]
 The event loop: in order to detect and process events, the application
 enters a loop that waits for events to occur, places them on the event
@@ -345,14 +341,14 @@ and should not be modified by the event source.
 .PP
 An event may be added to the queue at any of three positions, depending
 on the \fIposition\fR argument to \fBTcl_QueueEvent\fR:
-.IP \fBTCL_QUEUE_TAIL\fR 24
+.IP \fBTCL_QUEUE_TAIL\fR 32
 Add the event at the back of the queue, so that all other pending
 events will be serviced first.  This is almost always the right
 place for new events.
-.IP \fBTCL_QUEUE_HEAD\fR 24
+.IP \fBTCL_QUEUE_HEAD\fR 32
 Add the event at the front of the queue, so that it will be serviced
 before all other queued events.
-.IP \fBTCL_QUEUE_MARK\fR 24
+.IP \fBTCL_QUEUE_MARK\fR 32
 Add the event at the front of the queue, unless there are other
 events at the front whose position is \fBTCL_QUEUE_MARK\fR;  if so,
 add the new event just after all other \fBTCL_QUEUE_MARK\fR events.
@@ -360,6 +356,10 @@ This value of \fIposition\fR is used to insert an ordered sequence of
 events at the front of the queue, such as a series of
 Enter and Leave events synthesized during a grab or ungrab operation
 in Tk.
+.IP \fBTCL_QUEUE_ALERT_IF_EMPTY\fR 32
+When used in \fBTcl_ThreadQueueEvent\fR
+arranges for an automatic call of \fBTcl_ThreadAlert\fR when the queue was
+empty.
 .PP
 When it is time to handle an event from the queue (steps 1 and 4
 above) \fBTcl_ServiceEvent\fR will invoke the \fIproc\fR specified
@@ -403,11 +403,7 @@ the event source (using \fBTcl_Alloc\fR or the Tcl macro \fBckalloc\fR)
 before calling \fBTcl_QueueEvent\fR, but it
 will be freed by \fBTcl_ServiceEvent\fR, not by the event source.
 .PP
-Threaded applications work in a
-similar manner, except that there is a separate event queue for
-each thread containing a Tcl interpreter.
-Calling \fBTcl_QueueEvent\fR in a multithreaded application adds
-an event to the current thread's queue.
+Calling \fBTcl_QueueEvent\fR adds an event to the current thread's queue.
 To add an event to another thread's queue, use \fBTcl_ThreadQueueEvent\fR.
 \fBTcl_ThreadQueueEvent\fR accepts as an argument a Tcl_ThreadId argument,
 which uniquely identifies a thread in a Tcl application.  To obtain the
@@ -498,8 +494,7 @@ under Unix it happens when \fBTcl_WaitForEvent\fR would have waited
 forever because there were no active event sources and the timeout was
 infinite.
 .PP
-\fBTcl_AlertNotifier\fR is used in multithreaded applications to allow
-any thread to
+\fBTcl_AlertNotifier\fR is used to allow any thread to
 .QW "wake up"
 the notifier to alert it to new events on its
 queue.  \fBTcl_AlertNotifier\fR requires as an argument the notifier

doc/Number.3

@@ -0,0 +1,123 @@
+'\"
+'\" Contribution from Don Porter, NIST, 2022. (not subject to US copyright)
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH Tcl_GetNumber 3 8.7 Tcl "Tcl Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tcl_GetNumber, Tcl_GetNumberFromObj \- get numeric value from Tcl value
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+\fB#include <tclTomMath.h>\fR
+.sp
+int
+\fBTcl_GetNumber\fR(\fIinterp, bytes, numBytes, clientDataPtr, typePtr\fR)
+.sp
+int
+\fBTcl_GetNumberFromObj\fR(\fIinterp, objPtr, clientDataPtr, typePtr\fR)
+.SH ARGUMENTS
+.AS Tcl_Interp clientDataPtr out
+.AP Tcl_Interp *interp out
+When non-NULL, error information is recorded here when the value is not
+in any of the numeric formats recognized by Tcl.
+.AP "const char" *bytes in
+Points to first byte of the string value to be examined.
+.AP size_t numBytes in
+The number of bytes, starting at \fIbytes\fR, that should be examined.
+If the value \fBTCL_INDEX_NONE\fR is provided, then all bytes should
+be examined until the first \fBNUL\fR byte terminates examination.
+.AP "void *" *clientDataPtr out
+Points to space where a pointer value may be written through which a numeric
+value is available to read.
+.AP int *typePtr out
+Points to space where a value may be written reporting what type of
+numeric storage is available to read.
+.AP Tcl_Obj *objPtr in
+A Tcl value to be examined.
+.BE
+.SH DESCRIPTION
+.PP
+These procedures enable callers to retrieve a numeric value from a
+Tcl value in a numeric format recognized by Tcl.
+.PP
+Tcl recognizes many values as numbers.  Several examples include:
+\fB"0"\fR, \fB" +1"\fR, \fB"-2 "\fR, \fB" 3 "\fR, \fB"0xdad1"\fR, \fB"0d09"\fR,
+\fB"1_000_000"\fR, \fB"4.0"\fR, \fB"1e-7"\fR, \fB"NaN"\fR, or \fB"Inf"\fR.
+When built-in Tcl commands act on these values as numbers, they are converted
+to a numeric representation for efficient handling in C code.  Tcl makes
+use of three C types to store these representations: \fBdouble\fR,
+\fBTcl_WideInt\fR, and \fBmp_int\fR.  The \fBdouble\fR type is provided by the
+C language standard.  The \fBTcl_WideInt\fR type is declared in the Tcl
+header file, \fBtcl.h\fR, and is equivalent to the C standard type
+\fBlong long\fR on most platforms. The \fBmp_int\fR type is declared in the
+header file \fBtclTomMath.h\fR, and implemented by the LibTomMath
+multiple-precision integer library, included with Tcl.
+.PP
+The routines \fBTcl_GetNumber\fR and \fBTcl_GetNumberFromObj\fR perform
+the same function.  They differ only in how the arguments present the Tcl
+value to be examined.  \fBTcl_GetNumber\fR accepts a counted string
+value in the arguments \fIbytes\fR and \fInumBytes\fR (or a
+\fBNUL\fR-terminated string value when \fInumBytes\fR is
+\fBTCL_INDEX_NONE\fR).  \fBTcl_GetNumberFromObj\fR accepts the Tcl value
+in \fIobjPtr\fR.
+.PP
+Both routines examine the Tcl value and determine whether Tcl recognizes
+it as a number.  If not, both routines return \fBTCL_ERROR\fR and (when
+\fIinterp\fR is not NULL) record an error message and error code
+in \fIinterp\fR.
+.PP
+If Tcl does recognize the examined value as a number, both routines return
+\fBTCL_OK\fR, and use the pointer arguments \fIclientDataPtr\fR
+and \fItypePtr\fR (which may not be NULL) to report information the
+caller can use to retrieve the numeric representation.  Both routines
+write to *\fIclientDataPtr\fR a pointer to the internal storage location
+where Tcl holds the converted numeric value.
+.PP
+When the converted numeric value is stored as a \fBdouble\fR,
+a call to math library routine \fBisnan\fR determines whether that
+value is not a number (NaN).  If so, both \fBTcl_GetNumber\fR and
+\fBTcl_GetNumberFromObj\fR write the value \fBTCL_NUMBER_NAN\fR
+to *\fItypePtr\fR. If not, both routines write the value
+\fBTCL_NUMBER_DOUBLE\fR to *\fItypePtr\fR.  These routines report
+different type values in these cases because \fBTcl_GetDoubleFromObj\fR
+raises an error on NaN values.  For both reported type values,
+the storage pointer may be cast to type \fBconst double *\fR and
+the \fBdouble\fR numeric value may be read through it.
+.PP
+When the converted numeric value is stored as a \fBTcl_WideInt\fR,
+both \fBTcl_GetNumber\fR and \fBTcl_GetNumberFromObj\fR write the
+value \fBTCL_NUMBER_INT\fR to *\fItypePtr\fR.
+The storage pointer may be cast to type \fBconst Tcl_WideInt *\fR and
+the \fBTcl_WideInt\fR numeric value may be read through it.
+.PP
+When the converted numeric value is stored as an \fBmp_int\fR,
+both \fBTcl_GetNumber\fR and \fBTcl_GetNumberFromObj\fR write the
+value \fBTCL_NUMBER_BIG\fR to *\fItypePtr\fR.
+The storage pointer may be cast to type \fBconst mp_int *\fR and
+the \fBmp_int\fR numeric value may be read through it.
+.PP
+Future releases of Tcl might expand or revise the recognition of
+values as numbers.  If additional storage representations are
+adopted, these routines will add new values to be written to
+*\fItypePtr\fR to identify them.  Callers should consider how
+they should react to unknown values written to *\fItypePtr\fR.
+.PP
+When callers of these routines read numeric values through the
+reported storage pointer, they are accessing memory that belongs
+to the Tcl library.  The Tcl library has the power to overwrite
+or free this memory.  The storage pointer reported by a call to
+\fBTcl_GetNumber\fR or \fBTcl_GetNumberFromObj\fR should not be
+used after the same thread has possibly returned control to the
+Tcl library.  If longer term access to the numeric value is needed,
+it should be copied into memory controlled by the caller.  Callers
+must not attempt to write through or free the storage pointer.
+.SH "SEE ALSO"
+Tcl_GetDouble, Tcl_GetDoubleFromObj, Tcl_GetWideIntFromObj
+.SH KEYWORDS
+double, double value, double type, integer, integer value, integer type,
+internal representation, value, value type, string representation

doc/Object.3

@@ -283,7 +283,12 @@ to reduce storage requirements.
 Reference counting is used to determine when a value is
 no longer needed and can safely be freed.
 A value just created by \fBTcl_NewObj\fR or \fBTcl_NewStringObj\fR
-has \fIrefCount\fR 0.
+has \fIrefCount\fR 0, meaning that the object can often be given to a function
+like \fBTcl_SetObjResult\fR, \fBTcl_ListObjAppendElement\fR, or
+\fBTcl_DictObjPut\fR (as a value) without explicit reference management, all
+of which are common use cases. (The latter two require that the the target
+list or dictionary be well-formed, but that is often easy to arrange when the
+value is being initially constructed.)
 The macro \fBTcl_IncrRefCount\fR increments the reference count
 when a new reference to the value is created.
 The macro \fBTcl_DecrRefCount\fR decrements the count

doc/ObjectType.3

@@ -248,6 +248,28 @@ The \fIfreeIntRepProc\fR implementation must not access the
 uses of that field during value deletion.  The defined tasks for
 the \fIfreeIntRepProc\fR have no need to consult the \fIbytes\fR
 member.
+.PP
+Note that if a subsidiary value has its reference count reduced to zero
+during the running of a \fIfreeIntRepProc\fR, that value may be not freed
+immediately, in order to limit stack usage. However, the value will be freed
+before the outermost current \fBTcl_DecrRefCount\fR returns.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+The \fIobjPtr\fR argument to \fBTcl_AppendAllObjTypes\fR should be an unshared
+value; this function will not modify the reference count of that value, but
+will modify its contents. If \fIobjPtr\fR is not (interpretable as) a list,
+this function will set the interpreter result and produce an error; using an
+unshared empty value is strongly recommended.
+.PP
+The \fIobjPtr\fR argument to \fBTcl_ConvertToType\fR can have any non-zero
+reference count; this function will not modify the reference count, but may
+write to the interpreter result on error so values that originate from there
+should have an additional reference made before calling this.
+.PP
+None of the callback functions in the \fBTcl_ObjType\fR structure should
+modify the reference count of their arguments, but if the values contain
+subsidiary values (e.g., the elements of a list or the keys of a dictionary)
+then those subsidiary values may have their reference counts modified.
 .SH "SEE ALSO"
 Tcl_NewObj(3), Tcl_DecrRefCount(3), Tcl_IncrRefCount(3)
 .SH KEYWORDS

doc/OpenFileChnl.3

@@ -92,10 +92,10 @@ int
 int
 \fBTcl_OutputBuffered\fR(\fIchannel\fR)
 .sp
-Tcl_WideInt
+long long
 \fBTcl_Seek\fR(\fIchannel, offset, seekMode\fR)
 .sp
-Tcl_WideInt
+long long
 \fBTcl_Tell\fR(\fIchannel\fR)
 .sp
 int
@@ -190,7 +190,7 @@ A buffer containing the bytes to output to the channel.
 .AP int bytesToWrite in
 The number of bytes to consume from \fIcharBuf\fR or \fIbyteBuf\fR and
 output to the channel.
-.AP Tcl_WideInt offset in
+.AP "long long" offset in
 How far to move the access point in the channel at which the next input or
 output operation will be applied, measured in bytes from the position
 given by \fIseekMode\fR.  May be either positive or negative.
@@ -198,7 +198,7 @@ given by \fIseekMode\fR.  May be either positive or negative.
 Relative to which point to seek; used with \fIoffset\fR to calculate the new
 access point for the channel. Legal values are \fBSEEK_SET\fR,
 \fBSEEK_CUR\fR, and \fBSEEK_END\fR.
-.AP Tcl_WideInt length in
+.AP "long long" length in
 The (non-negative) length to truncate the channel the channel to.
 .AP "const char" *optionName in
 The name of an option applicable to this channel, such as \fB\-blocking\fR.
@@ -406,10 +406,10 @@ to UTF-8 based on the channel's encoding and storing the produced data in
 \fIreadObjPtr\fR's string representation.  The return value of
 \fBTcl_ReadChars\fR is the number of characters, up to \fIcharsToRead\fR,
 that were stored in \fIreadObjPtr\fR.  If an error occurs while reading, the
-return value is \-1 and \fBTcl_ReadChars\fR records a POSIX error code that
+return value is TCL_INDEX_NONE and \fBTcl_ReadChars\fR records a POSIX error code that
 can be retrieved with \fBTcl_GetErrno\fR.
 .PP
-Setting \fIcharsToRead\fR to \fB\-1\fR will cause the command to read
+Setting \fIcharsToRead\fR to TCL_INDEX_NONE will cause the command to read
 all characters currently available (non-blocking) or everything until
 eof (blocking mode).
 .PP
@@ -471,14 +471,14 @@ character(s) are read and discarded.
 .PP
 If a line was successfully read, the return value is greater than or equal
 to zero and indicates the number of bytes stored in \fIlineObjPtr\fR.  If an
-error occurs, \fBTcl_GetsObj\fR returns \-1 and records a POSIX error code
+error occurs, \fBTcl_GetsObj\fR returns TCL_INDEX_NONE and records a POSIX error code
 that can be retrieved with \fBTcl_GetErrno\fR.  \fBTcl_GetsObj\fR also
-returns \-1 if the end of the file is reached; the \fBTcl_Eof\fR procedure
+returns TCL_INDEX_NONE if the end of the file is reached; the \fBTcl_Eof\fR procedure
 can be used to distinguish an error from an end-of-file condition.
 .PP
-If the channel is in nonblocking mode, the return value can also be \-1 if
-no data was available or the data that was available did not contain an
-end-of-line character.  When \-1 is returned, the \fBTcl_InputBlocked\fR
+If the channel is in nonblocking mode, the return value can also be TCL_INDEX_NONE
+if no data was available or the data that was available did not contain an
+end-of-line character.  When TCL_INDEX_NONE is returned, the \fBTcl_InputBlocked\fR
 procedure may be invoked to determine if the channel is blocked because
 of input unavailability.
 .PP
@@ -496,7 +496,7 @@ head of the queue.  If \fIchannel\fR has a
 .QW sticky
 EOF set, no data will be
 added to the input queue.  \fBTcl_Ungets\fR returns \fIinputLen\fR or
-\-1 if an error occurs.
+TCL_INDEX_NONE if an error occurs.
 .SH "TCL_WRITECHARS, TCL_WRITEOBJ, AND TCL_WRITE"
 .PP
 \fBTcl_WriteChars\fR accepts \fIbytesToWrite\fR bytes of character data at
@@ -513,10 +513,10 @@ to appear as soon as a complete line is accepted for output, set the
 \fB\-buffering\fR option on the channel to \fBline\fR mode.
 .PP
 The return value of \fBTcl_WriteChars\fR is a count of how many bytes were
-accepted for output to the channel.  This is either greater than zero to
-indicate success or \-1 to indicate that an error occurred.  If an error
-occurs, \fBTcl_WriteChars\fR records a POSIX error code that may be
-retrieved with \fBTcl_GetErrno\fR.
+accepted for output to the channel.  This is either TCL_INDEX_NONE to
+indicate that an error occurred or another number greater than
+zero to indicate success.  If an error occurs, \fBTcl_WriteChars\fR records
+a POSIX error code that may be retrieved with \fBTcl_GetErrno\fR.
 .PP
 Newline characters in the output data are translated to platform-specific
 end-of-line sequences according to the \fB\-translation\fR option for the
@@ -641,6 +641,24 @@ the channel was created with \fBTcl_OpenFileChannel\fR,
 \fBTcl_OpenCommandChannel\fR, or \fBTcl_MakeFileChannel\fR.  Other
 channel types may return a different type of handle on Windows
 platforms.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+The \fIreadObjPtr\fR argument to \fBTcl_ReadChars\fR must be an unshared
+value; it will be modified by this function.  Using the interpreter result for
+this purpose is \fIstrongly\fR not recommended; the preferred pattern is to
+use a new value from \fBTcl_NewObj\fR to receive the data and only to pass it
+to \fBTcl_SetObjResult\fR if this function succeeds.
+.PP
+The \fIlineObjPtr\fR argument to \fBTcl_GetsObj\fR must be an unshared value;
+it will be modified by this function.  Using the interpreter result for this
+purpose is \fIstrongly\fR not recommended; the preferred pattern is to use a
+new value from \fBTcl_NewObj\fR to receive the data and only to pass it to
+\fBTcl_SetObjResult\fR if this function succeeds.
+.PP
+The \fIwriteObjPtr\fR argument to \fBTcl_WriteObj\fR should be a value with
+any reference count. This function will not modify the reference count. Using
+the interpreter result without adding an additional reference to it is not
+recommended.
 .SH "SEE ALSO"
 DString(3), fconfigure(n), filename(n), fopen(3), Tcl_CreateChannel(3)
 .SH KEYWORDS

doc/OpenTcp.3

@@ -4,12 +4,12 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-.TH Tcl_OpenTcpClient 3 8.0 Tcl "Tcl Library Procedures"
+.TH Tcl_OpenTcpClient 3 8.7 Tcl "Tcl Library Procedures"
 .so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-Tcl_OpenTcpClient, Tcl_MakeTcpClientChannel, Tcl_OpenTcpServer \- procedures to open channels using TCP sockets
+Tcl_OpenTcpClient, Tcl_MakeTcpClientChannel, Tcl_OpenTcpServer, Tcl_OpenTcpServerEx \- procedures to open channels using TCP sockets
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h> \fR
@@ -23,6 +23,9 @@ Tcl_Channel
 Tcl_Channel
 \fBTcl_OpenTcpServer\fR(\fIinterp, port, myaddr, proc, clientData\fR)
 .sp
+Tcl_Channel
+\fBTcl_OpenTcpServerEx\fR(\fIinterp, service, myaddr, flags, backlog, proc, clientData\fR)
+.sp
 .SH ARGUMENTS
 .AS Tcl_TcpAcceptProc clientData
 .AP Tcl_Interp *interp in
@@ -30,6 +33,9 @@ Tcl interpreter to use for error reporting.  If non-NULL and an
 error occurs, an error message is left in the interpreter's result.
 .AP int port in
 A port number to connect to as a client or to listen on as a server.
+.AP "const char" *service in
+A string specifying the port number to connect to as a client or to listen on as
+ a server.
 .AP "const char" *host in
 A string specifying a host name or address for the remote end of the connection.
 .AP int myport in
@@ -41,6 +47,11 @@ for the local end of the connection.  If NULL, a default interface is
 chosen.
 .AP int async in
 If nonzero, the client socket is connected asynchronously to the server.
+.AP int backlog in
+Length of OS listen backlog queue. Use -1 for default value.
+.AP "unsigned int" flags in
+ORed combination of \fBTCL_TCPSERVER\fR flags that specify additional
+informations about the socket being created.
 .AP ClientData sock in
 Platform-specific handle for client TCP socket.
 .AP Tcl_TcpAcceptProc *proc in
@@ -158,6 +169,11 @@ register it, use \fBTcl_RegisterChannel\fR.
 If one of the standard channels, \fBstdin\fR, \fBstdout\fR or \fBstderr\fR was
 previously closed, the act of creating the new channel also assigns it as a
 replacement for the standard channel.
+.SS TCL_OPENTCPSERVEREX
+.PP
+\fBTcl_OpenTcpServerEx\fR behaviour is identical to \fBTcl_OpenTcpServer\fR but
+gives more flexibility to the user by providing a mean to further customize some
+aspects of the socket via the \fIflags\fR parameter.
 .SH "PLATFORM ISSUES"
 .PP
 On Unix platforms, the socket handle is a Unix file descriptor as

doc/Panic.3

@@ -7,7 +7,7 @@
 .BS
 '\"  Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-Tcl_Panic, Tcl_PanicVA, Tcl_SetPanicProc \- report fatal error and abort
+Tcl_Panic, Tcl_PanicVA, Tcl_SetPanicProc, Tcl_ConsolePanic \- report fatal error and abort
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -18,9 +18,12 @@ void
 void
 \fBTcl_PanicVA\fR(\fIformat\fR, \fIargList\fR)
 .sp
-void
+const char *
 \fBTcl_SetPanicProc\fR(\fIpanicProc\fR)
 .sp
+void
+\fBTcl_ConsolePanic\fR(\fIformat\fR, \fIarg\fR, \fIarg\fR, \fI...\fR)
+.sp
 .SH ARGUMENTS
 .AS Tcl_PanicProc *panicProc
 .AP "const char*" format in
@@ -54,6 +57,14 @@ message is sent to the debugger instead. If the windows executable
 does not have a stderr channel (e.g. \fBwish.exe\fR), then a
 system dialog box is used to display the panic message.
 .PP
+If your application doesn't use \fBTcl_Main\fR or \fBTk_Main\fR
+and you want to implicitly use the stderr channel of your
+application's C runtime (instead of the stderr channel of the
+C runtime used by Tcl), you can call \fBTcl_SetPanicProc\fR
+with \fBTcl_ConsolePanic\fR as its argument. On platforms which
+only have one C runtime (almost all platforms except Windows)
+\fBTcl_ConsolePanic\fR is equivalent to NULL.
+.PP
 \fBTcl_SetPanicProc\fR may be used to modify the behavior of
 \fBTcl_Panic\fR.  The \fIpanicProc\fR argument should match the
 type \fBTcl_PanicProc\fR:
@@ -71,10 +82,16 @@ making calls into the Tcl library, or into other libraries that may
 call the Tcl library, since the original call to \fBTcl_Panic\fR
 indicates the Tcl library is not in a state of reliable operation.
 .PP
+The result of \fBTcl_SetPanicProc\fR is the full Tcl version (e.g.,
+\fB8.7.0+abcdef...abcdef.gcc-1002.utf16\fR).
+.PP
 The typical use of \fBTcl_SetPanicProc\fR arranges for the error message
 to be displayed or reported in a manner more suitable for the
 application or the platform.
 .PP
+\fBTcl_SetPanicProc\fR can not be used in stub-enabled extensions. Its symbol
+entry in the stub table is deprecated and it will be removed in Tcl 9.0.
+.PP
 Although the primary callers of \fBTcl_Panic\fR are the procedures of
 the Tcl library, \fBTcl_Panic\fR is a public function and may be called
 by any extension or application that wishes to abort the process and
@@ -82,7 +99,9 @@ have a panic message displayed the same way that panic messages from Tcl
 will be displayed.
 .PP
 \fBTcl_PanicVA\fR is the same as \fBTcl_Panic\fR except that instead of
-taking a variable number of arguments it takes an argument list.
+taking a variable number of arguments it takes an argument list. Interfaces
+using argument lists have been found to be nonportable in practice. This
+function is deprecated and will be removed in Tcl 9.0.
 .SH "SEE ALSO"
 abort(3), printf(3), exec(n), format(n)
 .SH KEYWORDS

doc/ParseArgs.3

@@ -189,6 +189,12 @@ will be stored at \fIdstPtr\fR; the string inside will have a lifetime linked
 to the lifetime of the string representation of the argument value that it
 came from, and so should be copied if it needs to be retained. The
 \fIsrcPtr\fR and \fIclientData\fR fields are ignored.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+The values in the \fIobjv\fR argument to \fBTcl_ParseArgsObjv\fR will not have
+their reference counts modified by this function. The interpreter result may
+be modified on error; the values passed should not be the interpreter result
+with no further reference added.
 .SH "SEE ALSO"
 Tcl_GetIndexFromObj(3), Tcl_Main(3), Tcl_CreateObjCommand(3)
 .SH KEYWORDS

doc/ParseCmd.3

@@ -191,6 +191,7 @@ code with one of the values \fBTCL_OK\fR, \fBTCL_ERROR\fR,
 some other integer value originating in an extension.
 In addition, a result value or error message is left in \fIinterp\fR's
 result; it can be retrieved using \fBTcl_GetObjResult\fR.
+.SS "DEPRECATED FUNCTIONS"
 .PP
 \fBTcl_EvalTokens\fR differs from \fBTcl_EvalTokensStandard\fR only in
 the return convention used: it returns the result in a new Tcl_Obj.
@@ -463,5 +464,12 @@ There are additional fields in the Tcl_Parse structure after the
 \fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR,
 \fBTcl_ParseQuotedString\fR, and \fBTcl_ParseVarName\fR; they should not be
 referenced by code outside of these procedures.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+The result of \fBTcl_EvalTokens\fR is an unshared value with a reference count
+of 1; the caller of that function should call \fBTcl_DecrRefCount\fR on the
+result value to dispose of it. (The equivalent with
+\fBTcl_EvalTokenStandard\fR is just the interpreter result, which can be
+retrieved with \fBTcl_GetObjResult\fR.)
 .SH KEYWORDS
 backslash substitution, braces, command, expression, parse, token, variable substitution

doc/PkgRequire.3

@@ -91,7 +91,11 @@ functions.
 \fBTcl_PkgRequireProc\fR is the form of \fBpackage require\fR handling
 multiple requirements. The other forms are present for backward
 compatibility and translate their invocations to this form.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+The requirements values given (in the \fIobjv\fR argument) to
+\fBTcl_PkgRequireProc\fR must have non-zero reference counts.
 .SH KEYWORDS
 package, present, provide, require, version
 .SH "SEE ALSO"
-package(n), Tcl_StaticPackage(3)
+package(n), Tcl_StaticLibrary(3)

doc/RecEvalObj.3

@@ -32,8 +32,6 @@ the command at global level instead of the current stack level.
 .PP
 \fBTcl_RecordAndEvalObj\fR is invoked to record a command as an event
 on the history list and then execute it using \fBTcl_EvalObjEx\fR
-(or \fBTcl_GlobalEvalObj\fR if the \fBTCL_EVAL_GLOBAL\fR bit is set
-in \fIflags\fR).
 It returns a completion code such as \fBTCL_OK\fR just like \fBTcl_EvalObjEx\fR,
 as well as a result value containing additional information
 (a result value or error message)
@@ -46,6 +44,12 @@ allow the user to re-issue recently invoked commands.
 If the \fIflags\fR argument contains the \fBTCL_NO_EVAL\fR bit then
 the command is recorded without being evaluated.
 
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+The reference count of the \fIcmdPtr\fR argument to \fBTcl_RecordAndEvalObj\fR
+must be at least 1. This function will modify the interpreter result; do not
+use an existing result as \fIcmdPtr\fR directly without incrementing its
+reference count.
 .SH "SEE ALSO"
 Tcl_EvalObjEx, Tcl_GetObjResult
 

doc/RegConfig.3

@@ -28,7 +28,7 @@ configuration as ASCII string. This means that this information is in
 UTF-8 too. Must not be NULL.
 .AP "const Tcl_Config" *configuration in
 Refers to an array of Tcl_Config entries containing the information
-embedded in the binary library. Must not be NULL. The end of the array
+embedded in the library. Must not be NULL. The end of the array
 is signaled by either a key identical to NULL, or a key referring to
 the empty string.
 .AP "const char" *valEncoding in
@@ -40,10 +40,10 @@ too. Must not be NULL.
 .PP
 The function described here has its base in TIP 59 and provides
 extensions with support for the embedding of configuration
-information into their binary library and the generation of a
+information into their library and the generation of a
 Tcl-level interface for querying this information.
 .PP
-To embed configuration information into their binary library an
+To embed configuration information into their library an
 extension has to define a non-volatile array of Tcl_Config entries in
 one if its source files and then call \fBTcl_RegisterConfig\fR to
 register that information.
@@ -108,4 +108,4 @@ typedef struct Tcl_Config {
 .\" No cross references yet.
 .\" .SH "SEE ALSO"
 .SH KEYWORDS
-embedding, configuration, binary library
+embedding, configuration, library

doc/RegExp.3

@@ -377,6 +377,22 @@ If no match was found, then it indicates the earliest point at which a
 match might occur if additional text is appended to the string.  If it
 is no match is possible even with further text, this field will be set
 to \-1.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+The \fItextObj\fR and \fIpatObj\fR arguments to \fBTcl_RegExpMatchObj\fR must
+have reference counts of at least 1.  Note however that this function may set
+the interpreter result; neither argument should be the direct interpreter
+result without an additional reference being taken.
+.PP
+The \fIpatObj\fR argument to \fBTcl_GetRegExpFromObj\fR must have a reference
+count of at least 1.  Note however that this function may set the interpreter
+result; the argument should not be the direct interpreter result without an
+additional reference being taken.
+.PP
+The \fItextObj\fR argument to \fBTcl_RegExpExecObj\fR must have a reference
+count of at least 1.  Note however that this function may set the interpreter
+result; the argument should not be the direct interpreter result without an
+additional reference being taken.
 .SH "SEE ALSO"
 re_syntax(n)
 .SH KEYWORDS

doc/SaveInterpState.3

@@ -0,0 +1,85 @@
+'\"
+'\" Copyright (c) 1997 Sun Microsystems, Inc.
+'\" Contributions from Don Porter, NIST, 2004. (not subject to US copyright)
+'\" Copyright (c) 2018 Nathan Coulter.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH Tcl_SaveResult 3 8.1 Tcl "Tcl Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tcl_SaveInterpState, Tcl_RestoreInterpState, Tcl_DiscardInterpState,
+Tcl_SaveResult, Tcl_RestoreResult, Tcl_DiscardResult \- Save and restore the
+state of an an interpreter.
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+Tcl_InterpState
+\fBTcl_SaveInterpState\fR(\fIinterp, status\fR)
+.sp
+int
+\fBTcl_RestoreInterpState\fR(\fIinterp, state\fR)
+.sp
+\fBTcl_DiscardInterpState\fR(\fIstate\fR)
+.sp
+\fBTcl_SaveResult\fR(\fIinterp, savedPtr\fR)
+.sp
+\fBTcl_RestoreResult\fR(\fIinterp, savedPtr\fR)
+.sp
+\fBTcl_DiscardResult\fR(\fIsavedPtr\fR)
+.SH ARGUMENTS
+.AS Tcl_InterpState savedPtr
+.AP Tcl_Interp *interp in
+The interpreter for the operation.
+.AP int status in
+The return code for the state.
+.AP Tcl_InterpState state in
+A token for saved state.
+.AP Tcl_SavedResult *savedPtr in
+A pointer to storage for saved state.
+.BE
+.SH DESCRIPTION
+.PP
+These routines save the state of an interpreter before a call to a routine such
+as \fBTcl_Eval\fR, and restore the state afterwards.
+.PP
+\fBTcl_SaveInterpState\fR saves the parts of \fIinterp\fR that comprise the
+result of a script, including the resulting value, the return code passed as
+\fIstatus\fR, and any options such as \fB\-errorinfo\fR and \fB\-errorcode\fR.
+It returns a token for the saved state.  The interpreter result is not reset
+and no interpreter state is changed.
+.PP
+\fBTcl_RestoreInterpState\fR restores the state indicated by \fIstate\fR and
+returns the \fIstatus\fR originally passed in the corresponding call to
+\fBTcl_SaveInterpState\fR.
+.PP
+If a saved state is not restored, \fBTcl_DiscardInterpState\fR must be called
+to release it.  A token used to discard or restore state must not be used
+again.
+.PP
+\fBTcl_SaveResult\fR, \fBTcl_RestoreResult\fR, and \fBTcl_DiscardResult\fR are
+deprecated.  Instead use \fBTcl_SaveInterpState\fR,
+\fBTcl_RestoreInterpState\fR, and \fBTcl_DiscardInterpState\fR, which are more
+capable.
+.PP
+\fBTcl_SaveResult\fR moves the result of \fIinterp\fR to the location
+\fIstatePtr\fR points to and returns the interpreter result to its initial
+state.  It does not save options such as \fB\-errorcode\fR or
+\fB\-errorinfo\fR.
+.PP
+\fBTcl_RestoreResult\fR clears any existing result or error in \fIinterp\fR and
+moves the result from \fIstatePtr\fR back to \fIinterp\fR.  \fIstatePtr\fR is
+then in an undefined state and must not be used until passed again to
+\fBTcl_SaveResult\fR.
+.PP
+\fBTcl_DiscardResult\fR releases the state stored at \fBstatePtr\fR, which is
+then in an undefined state and must not be used until passed again to
+\fBTcl_SaveResult\fR.
+.PP
+If a saved result is not restored, \fBTcl_DiscardResult\fR must be called to
+release it.
+.SH KEYWORDS
+result, state, interp

doc/SaveResult.3

@@ -1,120 +0,0 @@
-'\"
-'\" Copyright (c) 1997 Sun Microsystems, Inc.
-'\" Contributions from Don Porter, NIST, 2004. (not subject to US copyright)
-'\"
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\"
-.TH Tcl_SaveResult 3 8.1 Tcl "Tcl Library Procedures"
-.so man.macros
-.BS
-.SH NAME
-Tcl_SaveInterpState, Tcl_RestoreInterpState, Tcl_DiscardInterpState, Tcl_SaveResult, Tcl_RestoreResult, Tcl_DiscardResult \- save and restore an interpreter's state
-.SH SYNOPSIS
-.nf
-\fB#include <tcl.h>\fR
-.sp
-Tcl_InterpState
-\fBTcl_SaveInterpState\fR(\fIinterp, status\fR)
-.sp
-int
-\fBTcl_RestoreInterpState\fR(\fIinterp, state\fR)
-.sp
-\fBTcl_DiscardInterpState\fR(\fIstate\fR)
-.sp
-\fBTcl_SaveResult\fR(\fIinterp, savedPtr\fR)
-.sp
-\fBTcl_RestoreResult\fR(\fIinterp, savedPtr\fR)
-.sp
-\fBTcl_DiscardResult\fR(\fIsavedPtr\fR)
-.SH ARGUMENTS
-.AS Tcl_InterpState savedPtr
-.AP Tcl_Interp *interp in
-Interpreter for which state should be saved.
-.AP int status in
-Return code value to save as part of interpreter state.
-.AP Tcl_InterpState state in
-Saved state token to be restored or discarded.
-.AP Tcl_SavedResult *savedPtr in
-Pointer to location where interpreter result should be saved or restored.
-.BE
-.SH DESCRIPTION
-.PP
-These routines allows a C procedure to take a snapshot of the current
-state of an interpreter so that it can be restored after a call
-to \fBTcl_Eval\fR or some other routine that modifies the interpreter
-state.  There are two triplets of routines meant to work together.
-.PP
-The first triplet stores the snapshot of interpreter state in
-an opaque token returned by \fBTcl_SaveInterpState\fR.  That token
-value may then be passed back to one of \fBTcl_RestoreInterpState\fR
-or \fBTcl_DiscardInterpState\fR, depending on whether the interp
-state is to be restored.  So long as one of the latter two routines
-is called, Tcl will take care of memory management.
-.PP
-The second triplet stores the snapshot of only the interpreter
-result (not its complete state) in memory allocated by the caller.
-These routines are passed a pointer to \fBTcl_SavedResult\fR
-that is used to store enough information to restore the interpreter result.
-\fBTcl_SavedResult\fR can be allocated on the stack of the calling
-procedure.  These routines do not save the state of any error
-information in the interpreter (e.g. the \fB\-errorcode\fR or
-\fB\-errorinfo\fR return options, when an error is in progress).
-.PP
-Because the routines \fBTcl_SaveInterpState\fR,
-\fBTcl_RestoreInterpState\fR, and \fBTcl_DiscardInterpState\fR perform
-a superset of the functions provided by the other routines,
-any new code should only make use of the more powerful routines.
-The older, weaker routines \fBTcl_SaveResult\fR, \fBTcl_RestoreResult\fR,
-and \fBTcl_DiscardResult\fR continue to exist only for the sake
-of existing programs that may already be using them.
-.PP
-\fBTcl_SaveInterpState\fR takes a snapshot of those portions of
-interpreter state that make up the full result of script evaluation.
-This include the interpreter result, the return code (passed in
-as the \fIstatus\fR argument, and any return options, including
-\fB\-errorinfo\fR and \fB\-errorcode\fR when an error is in progress.
-This snapshot is returned as an opaque token of type \fBTcl_InterpState\fR.
-The call to \fBTcl_SaveInterpState\fR does not itself change the
-state of the interpreter.  Unlike \fBTcl_SaveResult\fR, it does
-not reset the interpreter.
-.PP
-\fBTcl_RestoreInterpState\fR accepts a \fBTcl_InterpState\fR token
-previously returned by \fBTcl_SaveInterpState\fR and restores the
-state of the interp to the state held in that snapshot.  The return
-value of \fBTcl_RestoreInterpState\fR is the status value originally
-passed to \fBTcl_SaveInterpState\fR when the snapshot token was
-created.
-.PP
-\fBTcl_DiscardInterpState\fR is called to release a \fBTcl_InterpState\fR
-token previously returned by \fBTcl_SaveInterpState\fR when that
-snapshot is not to be restored to an interp.
-.PP
-The \fBTcl_InterpState\fR token returned by \fBTcl_SaveInterpState\fR
-must eventually be passed to either \fBTcl_RestoreInterpState\fR
-or \fBTcl_DiscardInterpState\fR to avoid a memory leak.  Once
-the \fBTcl_InterpState\fR token is passed to one of them, the
-token is no longer valid and should not be used anymore.
-.PP
-\fBTcl_SaveResult\fR moves the string and value results
-of \fIinterp\fR into the location specified by \fIstatePtr\fR.
-\fBTcl_SaveResult\fR clears the result for \fIinterp\fR and
-leaves the result in its normal empty initialized state.
-.PP
-\fBTcl_RestoreResult\fR moves the string and value results from
-\fIstatePtr\fR back into \fIinterp\fR.  Any result or error that was
-already in the interpreter will be cleared.  The \fIstatePtr\fR is left
-in an uninitialized state and cannot be used until another call to
-\fBTcl_SaveResult\fR.
-.PP
-\fBTcl_DiscardResult\fR releases the saved interpreter state
-stored at \fBstatePtr\fR.  The state structure is left in an
-uninitialized state and cannot be used until another call to
-\fBTcl_SaveResult\fR.
-.PP
-Once \fBTcl_SaveResult\fR is called to save the interpreter
-result, either \fBTcl_RestoreResult\fR or
-\fBTcl_DiscardResult\fR must be called to properly clean up the
-memory associated with the saved state.
-.SH KEYWORDS
-result, state, interp

doc/SetChanErr.3

@@ -35,20 +35,20 @@ Refers to the Tcl interpreter whose bypass area is accessed.
 .AP Tcl_Obj* msg in
 Error message put into a bypass area. A list of return options and values,
 followed by a string message. Both message and the option/value information
-are optional.
+are optional. This \fImust\fR be a well-formed list.
 .AP Tcl_Obj** msgPtr out
 Reference to a place where the message stored in the accessed bypass area can
 be stored in.
 .BE
 .SH DESCRIPTION
 .PP
-The current definition of a Tcl channel driver does not permit the direct
+The standard definition of a Tcl channel driver does not permit the direct
 return of arbitrary error messages, except for the setting and retrieval of
 channel options. All other functions are restricted to POSIX error codes.
 .PP
 The functions described here overcome this limitation. Channel drivers are
 allowed to use \fBTcl_SetChannelError\fR and \fBTcl_SetChannelErrorInterp\fR
-to place arbitrary error messages in \fBbypass areas\fR defined for channels
+to place arbitrary error messages in \fIbypass areas\fR defined for channels
 and interpreters. And the generic I/O layer uses \fBTcl_GetChannelError\fR and
 \fBTcl_GetChannelErrorInterp\fR to look for messages in the bypass areas and
 arrange for their return as errors. The POSIX error codes set by a driver are
@@ -134,6 +134,15 @@ leave all their error information in the interpreter result.
 .ta 1.9i 4i
 \fBTcl_Close\fR	\fBTcl_UnstackChannel\fR	\fBTcl_UnregisterChannel\fR
 .DE
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+The \fImsg\fR argument to \fBTcl_SetChannelError\fR and
+\fBTcl_SetChannelErrorInterp\fR, if not NULL, may have any reference count;
+these functions will copy.
+.PP
+\fBTcl_GetChannelError\fR and \fBTcl_GetChannelErrorInterp\fR write a value
+reference into their \fImsgPtr\fR, but do not manipulate its reference count.
+The reference count will be at least 1 (unless the reference is NULL).
 .SH "SEE ALSO"
 Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3)
 .SH KEYWORDS

doc/SetResult.3

@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-.TH Tcl_SetResult 3 8.6 Tcl "Tcl Library Procedures"
+.TH Tcl_SetResult 3 8.7 Tcl "Tcl Library Procedures"
 .so man.macros
 .BS
 .SH NAME
@@ -30,9 +30,7 @@ const char *
 .sp
 \fBTcl_ResetResult\fR(\fIinterp\fR)
 .sp
-.VS 8.6
 \fBTcl_TransferResult\fR(\fIsourceInterp, code, targetInterp\fR)
-.VE 8.6
 .sp
 \fBTcl_AppendElement\fR(\fIinterp, element\fR)
 .sp
@@ -57,17 +55,11 @@ Address of procedure to call to release storage at
 An argument list which must have been initialized using
 \fBva_start\fR, and cleared using \fBva_end\fR.
 .AP Tcl_Interp *sourceInterp in
-.VS 8.6
 Interpreter that the result and return options should be transferred from.
-.VE 8.6
 .AP Tcl_Interp *targetInterp in
-.VS 8.6
 Interpreter that the result and return options should be transferred to.
-.VE 8.6
 .AP int code in
-.VS 8.6
 Return code value that controls transfer of return options.
-.VE 8.6
 .BE
 .SH DESCRIPTION
 .PP
@@ -153,8 +145,9 @@ call; the last argument in the list must be a NULL pointer.
 .PP
 \fBTcl_AppendResultVA\fR is the same as \fBTcl_AppendResult\fR except that
 instead of taking a variable number of arguments it takes an argument list.
+Interfaces using argument lists have been found to be nonportable in practice.
+This function is deprecated and will be removed in Tcl 9.0.
 .PP
-.VS 8.6
 \fBTcl_TransferResult\fR transfers interpreter state from \fIsourceInterp\fR
 to \fItargetInterp\fR. The two interpreters must have been created in the
 same thread.  If \fIsourceInterp\fR and \fItargetInterp\fR are the same,
@@ -163,7 +156,6 @@ from \fIsourceInterp\fR to \fItargetInterp\fR, and resets the result
 in \fIsourceInterp\fR. It also moves the return options dictionary as
 controlled by the return code value \fIcode\fR in the same manner
 as \fBTcl_GetReturnOptions\fR.
-.VE 8.6
 .SH "DEPRECATED INTERFACES"
 .SS "OLD STRING PROCEDURES"
 .PP
@@ -205,14 +197,9 @@ is about to replace one result value with another.
 It used to be legal for programs to
 directly read and write \fIinterp->result\fR
 to manipulate the interpreter result.  The Tcl headers no longer
-permit this access by default, and C code still doing this must
+permit this access. C code still doing this must
 be updated to use supported routines \fBTcl_GetObjResult\fR,
 \fBTcl_GetStringResult\fR, \fBTcl_SetObjResult\fR, and \fBTcl_SetResult\fR.
-As a migration aid, access can be restored with the compiler directive
-.CS
-#define USE_INTERP_RESULT
-.CE
-but this is meant only to offer life support to otherwise dead code.
 .SH "THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT"
 .PP
 \fBTcl_SetResult\fR's \fIfreeProc\fR argument specifies how
@@ -252,6 +239,33 @@ typedef void \fBTcl_FreeProc\fR(
 .PP
 When \fIfreeProc\fR is called, its \fIblockPtr\fR will be set to
 the value of \fIresult\fR passed to \fBTcl_SetResult\fR.
+
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+The interpreter result is one of the main places that owns references to
+values, along with the bytecode execution stack, argument lists, variables,
+and the list and dictionary collection values.
+.PP
+\fBTcl_SetObjResult\fR takes a value with an arbitrary reference count
+\fI(specifically including zero)\fR and guarantees to increment the reference
+count. If code wishes to continue using the value after setting it as the
+result, it should add its own reference to it with \fBTcl_IncrRefCount\fR.
+.PP
+\fBTcl_GetObjResult\fR returns the current interpreter result value. This will
+have a reference count of at least 1. If the caller wishes to keep the
+interpreter result value, it should increment its reference count.
+.PP
+\fBTcl_GetStringResult\fR does not manipulate reference counts, but the string
+it returns is owned by (and has a lifetime controlled by) the current
+interpreter result value; it should be copied instead of being relied upon to
+persist after the next Tcl API call, as most Tcl operations can modify the
+interpreter result.
+.PP
+\fBTcl_SetResult\fR, \fBTcl_AppendResult\fR, \fBTcl_AppendResultVA\fR,
+\fBTcl_AppendElement\fR, and \fBTcl_ResetResult\fR all modify the interpreter
+result. They may cause the old interpreter result to have its reference count
+decremented and a new interpreter result to be allocated. After they have been
+called, the reference count of the interpreter result is guaranteed to be 1.
 .SH "SEE ALSO"
 Tcl_AddErrorInfo, Tcl_CreateObjCommand, Tcl_SetErrorCode, Tcl_Interp,
 Tcl_GetReturnOptions

doc/SetVar.3

@@ -242,6 +242,27 @@ but the array remains.
 If an array name is specified without an index, then the entire
 array is removed.
 
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+The result of \fBTcl_SetVar2Ex\fR, \fBTcl_ObjSetVar2\fR, \fBTcl_GetVar2Ex\fR,
+and \fBTcl_ObjGetVar2\fR is (if non-NULL) a value with a reference of at least
+1, where that reference is held by the variable that the function has just
+operated upon.
+.PP
+The \fInewValuePtr\fR argument to \fBTcl_SetVar2Ex\fR and \fBTcl_ObjSetVar2\fR
+may be an arbitrary reference count value; its reference count will be
+incremented on success. However, it is recommended to not use a zero reference
+count value, as that makes correct handling of the error case tricky.
+.PP
+The \fIpart1\fR argument to \fBTcl_ObjSetVar2\fR and \fBTcl_ObjGetVar2\fR can
+have any reference count; these functions never modify it. It is recommended
+to not use a zero reference count for this argument.
+.PP
+The \fIpart2\fR argument to \fBTcl_ObjSetVar2\fR and \fBTcl_ObjGetVar2\fR, if
+non-NULL, should not have a zero reference count as these functions may
+retain a reference to it (particularly when it is used to create an array
+element that did not previously exist).
+
 .SH "SEE ALSO"
 Tcl_GetObjResult, Tcl_GetStringResult, Tcl_TraceVar
 

doc/StaticLibrary.3

@@ -0,0 +1,78 @@
+'\"
+'\" Copyright (c) 1995-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_StaticLibrary 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tcl_StaticLibrary, Tcl_StaticPackage \- make a statically linked library available via the 'load' command
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+\fBTcl_StaticLibrary\fR(\fIinterp, prefix, initProc, safeInitProc\fR)
+.sp
+\fBTcl_StaticPackage\fR(\fIinterp, prefix, initProc, safeInitProc\fR)
+.SH ARGUMENTS
+.AS Tcl_LibraryInitProc *safeInitProc
+.AP Tcl_Interp *interp in
+If not NULL, points to an interpreter into which the library has
+already been incorporated (i.e., the caller has already invoked the
+appropriate initialization procedure).  NULL means the library
+has not yet been incorporated into any interpreter.
+.AP "const char" *prefix in
+Prefix for library initialization function;  should be properly
+capitalized (first letter upper-case, all others lower-case).
+.AP Tcl_LibraryInitProc *initProc in
+Procedure to invoke to incorporate this library into a trusted
+interpreter.
+.AP Tcl_LibraryInitProc *safeInitProc in
+Procedure to call to incorporate this library into a safe interpreter
+(one that will execute untrusted scripts).  NULL means the library
+cannot be used in safe interpreters.
+.BE
+.SH DESCRIPTION
+.PP
+This procedure may be invoked to announce that a library has been
+linked statically with a Tcl application and, optionally, that it
+has already been incorporated into an interpreter.
+Once \fBTcl_StaticLibrary\fR has been invoked for a library, it
+may be incorporated into interpreters using the \fBload\fR command.
+\fBTcl_StaticLibrary\fR is normally invoked only by the \fBTcl_AppInit\fR
+procedure for the application, not by libraries for themselves
+(\fBTcl_StaticLibrary\fR should only be invoked for statically
+linked libraries, and code in the library itself should not need
+to know whether the library is dynamically loaded or statically linked).
+.PP
+When the \fBload\fR command is used later to incorporate the library into
+an interpreter, one of \fIinitProc\fR and \fIsafeInitProc\fR will
+be invoked, depending on whether the target interpreter is safe
+or not.
+\fIinitProc\fR and \fIsafeInitProc\fR must both match the
+following prototype:
+.PP
+.CS
+typedef int \fBTcl_LibraryInitProc\fR(
+        Tcl_Interp *\fIinterp\fR);
+.CE
+.PP
+The \fIinterp\fR argument identifies the interpreter in which the library
+is to be incorporated.  The initialization procedure must return \fBTCL_OK\fR or
+\fBTCL_ERROR\fR to indicate whether or not it completed successfully; in
+the event of an error it should set the interpreter's result to point to an
+error message.  The result or error from the initialization procedure will
+be returned as the result of the \fBload\fR command that caused the
+initialization procedure to be invoked.
+.PP
+\fBTcl_StaticLibrary\fR was named \fBTcl_StaticPackage\fR in Tcl 8.6 and
+earlier, but the old name is deprecated now.
+.PP
+\fBTcl_StaticLibrary\fR can not be used in stub-enabled extensions. Its symbol
+entry in the stub table is deprecated and it will be removed in Tcl 9.0.
+.SH KEYWORDS
+initialization procedure, package, static linking
+.SH "SEE ALSO"
+load(n), package(n), Tcl_PkgRequire(3)

doc/StaticPkg.3

@@ -1,70 +0,0 @@
-'\"
-'\" Copyright (c) 1995-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_StaticPackage 3 7.5 Tcl "Tcl Library Procedures"
-.so man.macros
-.BS
-.SH NAME
-Tcl_StaticPackage \- make a statically linked package available via the 'load' command
-.SH SYNOPSIS
-.nf
-\fB#include <tcl.h>\fR
-.sp
-\fBTcl_StaticPackage\fR(\fIinterp, prefix, initProc, safeInitProc\fR)
-.SH ARGUMENTS
-.AS Tcl_PackageInitProc *safeInitProc
-.AP Tcl_Interp *interp in
-If not NULL, points to an interpreter into which the package has
-already been loaded (i.e., the caller has already invoked the
-appropriate initialization procedure).  NULL means the package
-has not yet been incorporated into any interpreter.
-.AP "const char" *prefix in
-Prefix for library initialization function;  should be properly
-capitalized (first letter upper-case, all others lower-case).
-.AP Tcl_PackageInitProc *initProc in
-Procedure to invoke to incorporate this package into a trusted
-interpreter.
-.AP Tcl_PackageInitProc *safeInitProc in
-Procedure to call to incorporate this package into a safe interpreter
-(one that will execute untrusted scripts).  NULL means the package
-cannot be used in safe interpreters.
-.BE
-.SH DESCRIPTION
-.PP
-This procedure may be invoked to announce that a package has been
-linked statically with a Tcl application and, optionally, that it
-has already been loaded into an interpreter.
-Once \fBTcl_StaticPackage\fR has been invoked for a package, it
-may be loaded into interpreters using the \fBload\fR command.
-\fBTcl_StaticPackage\fR is normally invoked only by the \fBTcl_AppInit\fR
-procedure for the application, not by packages for themselves
-(\fBTcl_StaticPackage\fR should only be invoked for statically
-loaded packages, and code in the package itself should not need
-to know whether the package is dynamically or statically loaded).
-.PP
-When the \fBload\fR command is used later to load the package into
-an interpreter, one of \fIinitProc\fR and \fIsafeInitProc\fR will
-be invoked, depending on whether the target interpreter is safe
-or not.
-\fIinitProc\fR and \fIsafeInitProc\fR must both match the
-following prototype:
-.PP
-.CS
-typedef int \fBTcl_PackageInitProc\fR(
-        Tcl_Interp *\fIinterp\fR);
-.CE
-.PP
-The \fIinterp\fR argument identifies the interpreter in which the package
-is to be loaded.  The initialization procedure must return \fBTCL_OK\fR or
-\fBTCL_ERROR\fR to indicate whether or not it completed successfully; in
-the event of an error it should set the interpreter's result to point to an
-error message.  The result or error from the initialization procedure will
-be returned as the result of the \fBload\fR command that caused the
-initialization procedure to be invoked.
-.SH KEYWORDS
-initialization procedure, package, static linking
-.SH "SEE ALSO"
-load(n), package(n), Tcl_PkgRequire(3)

doc/StringObj.3

@@ -37,7 +37,7 @@ Tcl_UniChar *
 Tcl_UniChar *
 \fBTcl_GetUnicode\fR(\fIobjPtr\fR)
 .sp
-Tcl_UniChar
+int
 \fBTcl_GetUniChar\fR(\fIobjPtr, index\fR)
 .sp
 int
@@ -111,17 +111,19 @@ If negative, all characters up to the first null character are used.
 The index of the Unicode character to return.
 .AP int first in
 The index of the first Unicode character in the Unicode range to be
-returned as a new value.
+returned as a new value. If negative, behave the same as if the
+value was 0.
 .AP int last in
 The index of the last Unicode character in the Unicode range to be
-returned as a new value.
+returned as a new value. If negative, take all characters up to
+the last one available.
 .AP Tcl_Obj *objPtr in/out
 Points to a value to manipulate.
 .AP Tcl_Obj *appendObjPtr in
 The value to append to \fIobjPtr\fR in \fBTcl_AppendObjToObj\fR.
 .AP int *lengthPtr out
-If non-NULL, the location where \fBTcl_GetStringFromObj\fR will store
-the length of a value's string representation.
+The location where \fBTcl_GetStringFromObj\fR will store the length
+of a value's string representation. May be (int *)NULL when not used.
 .AP "const char" *string in
 Null-terminated string value to append to \fIobjPtr\fR.
 .AP va_list argList in
@@ -204,8 +206,8 @@ where the caller does not need the length of the unicode string
 representation.
 .PP
 \fBTcl_GetUniChar\fR returns the \fIindex\fR'th character in the
-value's Unicode representation. The index is assumed to be in the
-appropriate range.
+value's Unicode representation. If the index is out of range or
+it references a low surrogate preceded by a high surrogate, it returns -1;
 .PP
 \fBTcl_GetRange\fR returns a newly created value comprised of the
 characters between \fIfirst\fR and \fIlast\fR (inclusive) in the
@@ -251,7 +253,9 @@ must be a NULL pointer to indicate the end of the list.
 .PP
 \fBTcl_AppendStringsToObjVA\fR is the same as \fBTcl_AppendStringsToObj\fR
 except that instead of taking a variable number of arguments it takes an
-argument list.
+argument list.  Interfaces using argument lists have been found to be
+nonportable in practice. This function is deprecated and will be removed
+in Tcl 9.0.
 .PP
 \fBTcl_AppendLimitedToObj\fR is similar to \fBTcl_AppendToObj\fR
 except that it imposes a limit on how many bytes are appended.
@@ -383,6 +387,33 @@ white space, then that value is ignored entirely. This white-space
 removal was added to make the output of the \fBconcat\fR command
 cleaner-looking. \fBTcl_ConcatObj\fR returns a pointer to a
 newly-created value whose ref count is zero.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_NewStringObj\fR, \fBTcl_NewUnicodeObj\fR, \fBTcl_Format\fR,
+\fBTcl_ObjPrintf\fR, and \fBTcl_ConcatObj\fR always return a zero-reference
+object, much like \fBTcl_NewObj\fR.
+.PP
+\fBTcl_GetStringFromObj\fR, \fBTcl_GetString\fR, \fBTcl_GetUnicodeFromObj\fR,
+\fBTcl_GetUnicode\fR, \fBTcl_GetUniChar\fR, \fBTcl_GetCharLength\fR, and
+\fBTcl_GetRange\fR all only work with an existing value; they do not
+manipulate its reference count in any way.
+.PP
+\fBTcl_SetStringObj\fR, \fBTcl_SetUnicodeObj\fR, \fBTcl_AppendToObj\fR,
+\fBTcl_AppendUnicodeToObj\fR, \fBTcl_AppendObjToObj\fR,
+\fBTcl_AppendStringsToObj\fR, \fBTcl_AppendStringsToObjVA\fR,
+\fBTcl_AppendLimitedToObj\fR, \fBTcl_AppendFormatToObj\fR,
+\fBTcl_AppendPrintfToObj\fR, \fBTcl_SetObjLength\fR, and
+\fBTcl_AttemptSetObjLength\fR and require their \fIobjPtr\fR to be an unshared
+value (i.e, a reference count no more than 1) as they will modify it.
+.PP
+Additional arguments to the above functions (the \fIappendObjPtr\fR argument
+to \fBTcl_AppendObjToObj\fR, values in the \fIobjv\fR argument to
+\fBTcl_Format\fR, \fBTcl_AppendFormatToObj\fR, and \fBTcl_ConcatObj\fR) can
+have any reference count, but reference counts of zero are not recommended.
+.PP
+\fBTcl_Format\fR and \fBTcl_AppendFormatToObj\fR may modify the interpreter
+result, which involves changing the reference count of a value.
+
 .SH "SEE ALSO"
 Tcl_NewObj(3), Tcl_IncrRefCount(3), Tcl_DecrRefCount(3), format(n), sprintf(3)
 .SH KEYWORDS

doc/SubstObj.3

@@ -62,6 +62,13 @@ result of the whole substitution on \fIobjPtr\fR will be truncated at
 the point immediately before the start of the command substitution,
 and no characters will be added to the result or substitutions
 performed after that point.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+The \fIobjPtr\fR argument to \fBTcl_SubstObj\fR must not have a reference
+count of zero. This function modifies the interpreter result, both on success
+and on failure; the result of this function on success is exactly the current
+interpreter result. Successful results should have their reference count
+incremented if they are to be retained.
 .SH "SEE ALSO"
 subst(n)
 .SH KEYWORDS

doc/Tcl.n

@@ -28,10 +28,10 @@ First, the Tcl interpreter breaks the command into \fIwords\fR
 and performs substitutions as described below.
 These substitutions are performed in the same way for all
 commands.
-Secondly, the first word is used to locate a command procedure to
-carry out the command, then all of the words of the command are
-passed to the command procedure.
-The command procedure is free to interpret each of its words
+Secondly, the first word is used to locate a routine to
+carry out the command, and the remaining words of the command are
+passed to that routine.
+The routine is free to interpret each of its words
 in any way it likes, such as an integer, variable name, list,
 or Tcl script.
 Different commands interpret their words differently.
@@ -223,7 +223,10 @@ before this range overflows, or when the maximum of eight digits
 is reached.  The upper bits of the Unicode character will be 0.
 .RS
 .PP
-The range U+010000\(enU+10FFFD is reserved for the future.
+The range U+00D800\(enU+00DFFF is reserved for surrogates, which
+are illegal on their own. Therefore, such sequences will result in
+the replacement character U+FFFD. Surrogate pairs should be
+encoded as single \e\fBU\fIhhhhhhhh\fR character.
 .RE
 .PP
 Backslash substitution is not performed on words enclosed in braces,

doc/TclZlib.3

@@ -262,6 +262,31 @@ file named by the \fBfilename\fR field was modified. Suitable for use with
 .
 The type of the uncompressed data (either \fBbinary\fR or \fBtext\fR) if
 known.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_ZlibDeflate\fR and \fBTcl_ZlibInflate\fR take a value with arbitrary
+reference count for their \fIdataObj\fR and \fIdictObj\fR arguments (the
+latter often being NULL instead), and set the interpreter result with their
+output value (or an error).  The existing interpreter result should not be
+passed as any argument value unless an additional reference is held.
+.PP
+\fBTcl_ZlibStreamInit\fR takes a value with arbitrary reference count for its
+\fIdictObj\fR argument; it only reads from it. The existing interpreter result
+should not be passed unless an additional reference is held.
+.PP
+\fBTcl_ZlibStreamGetCommandName\fR returns a zero reference count value, much
+like \fBTcl_NewObj\fR.
+.PP
+The \fIdataObj\fR argument to \fBTcl_ZlibStreamPut\fR is a value with
+arbitrary reference count; it is only ever read from.
+.PP
+The \fIdataObj\fR argument to \fBTcl_ZlibStreamGet\fR is an unshared value
+(see \fBTcl_IsShared\fR) that will be updated by the function.
+.PP
+The \fIcompDict\fR argument to \fBTcl_ZlibStreamSetCompressionDictionary\fR,
+if non-NULL, may be duplicated or may have its reference count incremented.
+Using a zero reference count value is not recommended.
+
 .SH "PORTABILITY NOTES"
 These functions will fail gracefully if Tcl is not linked with the zlib
 library.

doc/Tcl_Main.3

@@ -85,8 +85,10 @@ that does nothing but invoke \fBTcl_Main\fR.
 .PP
 \fBTcl_Main\fR is not provided by the public interface of Tcl's
 stub library.  Programs that call \fBTcl_Main\fR must be linked
-against the standard Tcl library.  Extensions (stub-enabled or
-not) are not intended to call \fBTcl_Main\fR.
+against the standard Tcl library.  If the standard Tcl library is
+a dll (so, not a static .lib/.a) , then the program must be linked
+against the stub library as well. Extensions
+(stub-enabled or not) are not intended to call \fBTcl_Main\fR.
 .PP
 \fBTcl_Main\fR is not thread-safe.  It should only be called by
 a single main thread of a multi-threaded application.  This
@@ -199,6 +201,17 @@ procedure (if any) returns.  In non-interactive mode, after
 \fBTcl_Main\fR evaluates the startup script, and the main loop
 procedure (if any) returns, \fBTcl_Main\fR will also evaluate
 the \fBexit\fR command.
+.PP
+\fBTcl_Main\fR can not be used in stub-enabled extensions.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_SetStartupScript\fR takes a value (or NULL) for its \fIpath\fR
+argument, and will increment the reference count of it.
+.PP
+\fBTcl_GetStartupScript\fR returns a value with reference count at least 1, or
+NULL. It's \fIencodingPtr\fR is also used (if non-NULL) to return a value with
+a reference count at least 1, or NULL. In both cases, the owner of the values
+is the current thread.
 .SH "SEE ALSO"
 tclsh(1), Tcl_GetStdChannel(3), Tcl_StandardChannels(3), Tcl_AppInit(3),
 exit(n), encoding(n)

doc/Thread.3

@@ -45,7 +45,9 @@ int
 .AP Tcl_Condition *condPtr in
 A condition variable, which must be associated with a mutex lock.
 .AP Tcl_Mutex *mutexPtr in
-A mutex lock.
+.VS TIP509
+A recursive mutex lock.
+.VE TIP509
 .AP "const Tcl_Time" *timePtr in
 A time limit on the condition wait.  NULL to wait forever.
 Note that a polling value of 0 seconds does not make much sense.
@@ -140,8 +142,12 @@ of code by calling \fBTcl_MutexLock\fR and \fBTcl_MutexUnlock\fR.
 If one thread holds a mutex, any other thread calling \fBTcl_MutexLock\fR will
 block until \fBTcl_MutexUnlock\fR is called.
 A mutex can be destroyed after its use by calling \fBTcl_MutexFinalize\fR.
-The result of locking a mutex twice from the same thread is undefined.
-On some platforms it will result in a deadlock.
+.VS TIP509
+Mutexes are reentrant: they can be locked several times from the same
+thread. However there must be exactly one call to
+\fBTcl_MutexUnlock\fR for each call to \fBTcl_MutexLock\fR in order
+for a thread to release a mutex completely.
+.VE TIP509
 The \fBTcl_MutexLock\fR, \fBTcl_MutexUnlock\fR and \fBTcl_MutexFinalize\fR
 procedures are defined as empty macros if not compiling with threads enabled.
 For declaration of mutexes the \fBTCL_DECLARE_MUTEX\fR macro should be used.

doc/ToUpper.3

@@ -13,13 +13,13 @@ Tcl_UniCharToUpper, Tcl_UniCharToLower, Tcl_UniCharToTitle, Tcl_UtfToUpper, Tcl_
 .nf
 \fB#include <tcl.h>\fR
 .sp
-Tcl_UniChar
+int
 \fBTcl_UniCharToUpper\fR(\fIch\fR)
 .sp
-Tcl_UniChar
+int
 \fBTcl_UniCharToLower\fR(\fIch\fR)
 .sp
-Tcl_UniChar
+int
 \fBTcl_UniCharToTitle\fR(\fIch\fR)
 .sp
 int
@@ -78,12 +78,5 @@ turns each character in the string into its lower-case equivalent.
 turns the first character in the string into its title-case equivalent
 and all following characters into their lower-case equivalents.
 
-.SH BUGS
-.PP
-At this time, the case conversions are only defined for the Unicode
-plane 0 characters.  The result for Unicode characters above 0xFFFF
-is undefined, but - actually - only the lower 16 bits of the
-character value is handled.
-
 .SH KEYWORDS
 utf, unicode, toupper, tolower, totitle, case

doc/TraceVar.3

@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-.TH Tcl_TraceVar 3 7.4 Tcl "Tcl Library Procedures"
+.TH Tcl_TraceVar 3 8.7 Tcl "Tcl Library Procedures"
 .so man.macros
 .BS
 .SH NAME
@@ -95,7 +95,7 @@ Invoke \fIproc\fR whenever an attempt is made to modify the variable.
 Invoke \fIproc\fR whenever the variable is unset.
 A variable may be unset either explicitly by an \fBunset\fR command,
 or implicitly when a procedure returns (its local variables are
-automatically unset) or when the interpreter is deleted (all
+automatically unset) or when the interpreter or namespace is deleted (all
 variables are automatically unset).
 .TP
 \fBTCL_TRACE_ARRAY\fR
@@ -160,10 +160,6 @@ The bit \fBTCL_TRACE_DESTROYED\fR will be set in \fIflags\fR if the trace is
 about to be destroyed;  this information may be useful to \fIproc\fR
 so that it can clean up its own internal data structures (see
 the section \fBTCL_TRACE_DESTROYED\fR below for more details).
-Lastly, the bit \fBTCL_INTERP_DESTROYED\fR will be set if the entire
-interpreter is being destroyed.
-When this bit is set, \fIproc\fR must be especially careful in
-the things it does (see the section \fBTCL_INTERP_DESTROYED\fR below).
 The trace procedure's return value should normally be NULL;  see
 \fBERROR RETURNS\fR below for information on other possibilities.
 .PP
@@ -330,6 +326,15 @@ During unset traces, the return value is ignored and all relevant
 trace procedures will always be invoked.
 .SH "RESTRICTIONS"
 .PP
+Because operations on variables may take place as part of the deletion
+of the interp that contains them, \fIproc\fR must be careful about checking
+what the \fIinterp\fR parameter can be used to do.
+The routine \fBTcl_InterpDeleted\fR is an important tool for this.
+When \fBTcl_InterpDeleted\fR returns 1, \fIproc\fR will not be able
+to invoke any scripts in \fIinterp\fR. You may encounter old code using
+a deprecated flag value \fBTCL_INTERP_DESTROYED\fR to signal this
+condition, but any supported code should be converted to stop using it.
+.PP
 A trace procedure can be called at any time, even when there
 are partially formed results stored in the interpreter.  If
 the trace procedure does anything that could damage this result (such
@@ -354,24 +359,16 @@ Traces on a variable are always removed whenever the variable
 is deleted;  the only time \fBTCL_TRACE_DESTROYED\fR is not set is for
 a whole-array trace invoked when only a single element of an
 array is unset.
-.SH "TCL_INTERP_DESTROYED"
+.SH "REFERENCE COUNT MANAGEMENT"
 .PP
-When an interpreter is destroyed, unset traces are called for
-all of its variables.
-The \fBTCL_INTERP_DESTROYED\fR bit will be set in the \fIflags\fR
-argument passed to the trace procedures.
-Trace procedures must be extremely careful in what they do if
-the \fBTCL_INTERP_DESTROYED\fR bit is set.
-It is not safe for the procedures to invoke any Tcl procedures
-on the interpreter, since its state is partially deleted.
-All that trace procedures should do under these circumstances is
-to clean up and free their own internal data structures.
+When a \fIproc\fR callback is invoked, and that callback was installed with
+the \fBTCL_TRACE_RESULT_OBJECT\fR flag, the result of the callback is a
+Tcl_Obj reference when there is an error. The result will have its reference
+count decremented once when no longer needed, or may have additional
+references made to it (e.g., by setting it as the interpreter result with
+\fBTcl_SetObjResult\fR).
 .SH BUGS
 .PP
-Tcl does not do any error checking to prevent trace procedures
-from misusing the interpreter during traces with \fBTCL_INTERP_DESTROYED\fR
-set.
-.PP
 Array traces are not yet integrated with the Tcl \fBinfo exists\fR command,
 nor is there Tcl-level access to array traces.
 .SH "SEE ALSO"

doc/UniCharIsAlpha.3

@@ -8,7 +8,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_UniCharIsAlnum, Tcl_UniCharIsAlpha, Tcl_UniCharIsControl, Tcl_UniCharIsDigit, Tcl_UniCharIsGraph, Tcl_UniCharIsLower, Tcl_UniCharIsPrint, Tcl_UniCharIsPunct, Tcl_UniCharIsSpace, Tcl_UniCharIsUpper, Tcl_UniCharIsWordChar \- routines for classification of Tcl_UniChar characters
+Tcl_UniCharIsAlnum, Tcl_UniCharIsAlpha, Tcl_UniCharIsControl, Tcl_UniCharIsDigit, Tcl_UniCharIsGraph, Tcl_UniCharIsLower, Tcl_UniCharIsPrint, Tcl_UniCharIsPunct, Tcl_UniCharIsSpace, Tcl_UniCharIsUpper, Tcl_UniCharIsUnicode, Tcl_UniCharIsWordChar \- routines for classification of Tcl_UniChar characters
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -44,11 +44,14 @@ int
 \fBTcl_UniCharIsUpper\fR(\fIch\fR)
 .sp
 int
+\fBTcl_UniCharIsUnicode\fR(\fIch\fR)
+.sp
+int
 \fBTcl_UniCharIsWordChar\fR(\fIch\fR)
 .SH ARGUMENTS
 .AS int ch
 .AP int ch in
-The Tcl_UniChar to be examined.
+The Unicode character to be examined.
 .BE
 
 .SH DESCRIPTION
@@ -81,6 +84,9 @@ with the various routines.
 .PP
 \fBTcl_UniCharIsUpper\fR tests if the character is an uppercase Unicode character.
 .PP
+\fBTcl_UniCharIsUnicode\fR tests if the character is a Unicode character, not being
+a surrogate or noncharacter.
+.PP
 \fBTcl_UniCharIsWordChar\fR tests if the character is alphanumeric or
 a connector punctuation mark.
 

doc/Utf.3

@@ -8,7 +8,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_UniChar, Tcl_UniCharToUtf, Tcl_UtfToUniChar, Tcl_UniCharToUtfDString, Tcl_UtfToUniCharDString, Tcl_UniCharLen, Tcl_UniCharNcmp, Tcl_UniCharNcasecmp, Tcl_UniCharCaseMatch, Tcl_UtfNcmp, Tcl_UtfNcasecmp, Tcl_UtfCharComplete, Tcl_NumUtfChars, Tcl_UtfFindFirst, Tcl_UtfFindLast, Tcl_UtfNext, Tcl_UtfPrev, Tcl_UniCharAtIndex, Tcl_UtfAtIndex, Tcl_UtfBackslash \- routines for manipulating UTF-8 strings
+Tcl_UniChar, Tcl_UniCharToUtf, Tcl_UtfToUniChar, Tcl_UtfToChar16, Tcl_UtfToWChar, Tcl_UniCharToUtfDString, Tcl_UtfToUniCharDString, Tcl_Char16ToUtfDString, Tcl_UtfToWCharDString, Tcl_UtfToChar16DString, Tcl_WCharLen, Tcl_Char16Len, Tcl_UniCharLen, Tcl_UniCharNcmp, Tcl_UniCharNcasecmp, Tcl_UniCharCaseMatch, Tcl_UtfNcmp, Tcl_UtfNcasecmp, Tcl_UtfCharComplete, Tcl_NumUtfChars, Tcl_UtfFindFirst, Tcl_UtfFindLast, Tcl_UtfNext, Tcl_UtfPrev, Tcl_UniCharAtIndex, Tcl_UtfAtIndex, Tcl_UtfBackslash \- routines for manipulating UTF-8 strings
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -21,12 +21,36 @@ int
 int
 \fBTcl_UtfToUniChar\fR(\fIsrc, chPtr\fR)
 .sp
+int
+\fBTcl_UtfToChar16\fR(\fIsrc, uPtr\fR)
+.sp
+int
+\fBTcl_UtfToWChar\fR(\fIsrc, wPtr\fR)
+.sp
 char *
 \fBTcl_UniCharToUtfDString\fR(\fIuniStr, uniLength, dsPtr\fR)
 .sp
+char *
+\fBTcl_Char16ToUtfDString\fR(\fIuStr, uniLength, dsPtr\fR)
+.sp
+char *
+\fBTcl_WCharToUtfDString\fR(\fIwStr, uniLength, dsPtr\fR)
+.sp
 Tcl_UniChar *
 \fBTcl_UtfToUniCharDString\fR(\fIsrc, length, dsPtr\fR)
 .sp
+unsigned short *
+\fBTcl_UtfToChar16DString\fR(\fIsrc, length, dsPtr\fR)
+.sp
+wchar_t *
+\fBTcl_UtfToWCharDString\fR(\fIsrc, length, dsPtr\fR)
+.sp
+int
+\fBTcl_Char16Len\fR(\fIuniStr\fR)
+.sp
+int
+\fBTcl_WCharLen\fR(\fIuniStr\fR)
+.sp
 int
 \fBTcl_UniCharLen\fR(\fIuniStr\fR)
 .sp
@@ -63,7 +87,7 @@ const char *
 const char *
 \fBTcl_UtfPrev\fR(\fIsrc, start\fR)
 .sp
-Tcl_UniChar
+int
 \fBTcl_UniCharAtIndex\fR(\fIsrc, index\fR)
 .sp
 const char *
@@ -75,11 +99,15 @@ int
 .AS "const Tcl_UniChar" *uniPattern in/out
 .AP char *buf out
 Buffer in which the UTF-8 representation of the Tcl_UniChar is stored.  At most
-\fBTCL_UTF_MAX\fR bytes are stored in the buffer.
+4 bytes are stored in the buffer.
 .AP int ch in
 The Unicode character to be converted or examined.
 .AP Tcl_UniChar *chPtr out
 Filled with the Tcl_UniChar represented by the head of the UTF-8 string.
+.AP unsigned short *uPtr out
+Filled with the utf-16 represented by the head of the UTF-8 string.
+.AP wchar_t *wPtr out
+Filled with the wchar_t represented by the head of the UTF-8 string.
 .AP "const char" *src in
 Pointer to a UTF-8 string.
 .AP "const char" *cs in
@@ -94,12 +122,21 @@ A null-terminated Unicode string.
 A null-terminated Unicode string.
 .AP "const Tcl_UniChar" *uniPattern in
 A null-terminated Unicode string.
+.AP "const unsigned short" *uStr in
+A null-terminated UTF-16 string.
+.AP "const wchar_t" *wStr in
+A null-terminated wchar_t string.
+.AP "const unsigned short" *utf16s in
+A null-terminated utf-16 string.
+.AP "const unsigned short" *utf16t in
+A null-terminated utf-16 string.
+.AP "const unsigned short" *utf16Pattern in
+A null-terminated utf-16 string.
 .AP int length in
 The length of the UTF-8 string in bytes (not UTF-8 characters).  If
 negative, all bytes up to the first null byte are used.
 .AP int uniLength in
-The length of the Unicode string in characters.  Must be greater than or
-equal to 0.
+The length of the Unicode string in characters.
 .AP "Tcl_DString" *dsPtr in/out
 A pointer to a previously initialized \fBTcl_DString\fR.
 .AP "unsigned long" numChars in
@@ -113,7 +150,7 @@ If non-NULL, filled with the number of bytes in the backslash sequence,
 including the backslash character.
 .AP char *dst out
 Buffer in which the bytes represented by the backslash sequence are stored.
-At most \fBTCL_UTF_MAX\fR bytes are stored in the buffer.
+At most 4 bytes are stored in the buffer.
 .AP int nocase in
 Specifies whether the match should be done case-sensitive (0) or
 case-insensitive (1).
@@ -121,18 +158,21 @@ case-insensitive (1).
 
 .SH DESCRIPTION
 .PP
-These routines convert between UTF-8 strings and Tcl_UniChars.  A
-Tcl_UniChar is a Unicode character represented as an unsigned, fixed-size
-quantity.  A UTF-8 character is a Unicode character represented as
-a varying-length sequence of up to \fBTCL_UTF_MAX\fR bytes.  A multibyte UTF-8
-sequence consists of a lead byte followed by some number of trail bytes.
+These routines convert between UTF-8 strings and Unicode/Utf-16 characters.
+A UTF-8 character is a Unicode character represented as a varying-length
+sequence of up to \fB4\fR bytes.  A multibyte UTF-8 sequence
+consists of a lead byte followed by some number of trail bytes.
 .PP
-\fBTCL_UTF_MAX\fR is the maximum number of bytes that it takes to
-represent one Unicode character in the UTF-8 representation.
+\fBTCL_UTF_MAX\fR is the maximum number of bytes that \fBTcl_UtfToUniChar\fR
+can consume in a single call.
 .PP
-\fBTcl_UniCharToUtf\fR stores the Tcl_UniChar \fIch\fR as a UTF-8 string
+\fBTcl_UniCharToUtf\fR stores the character \fIch\fR as a UTF-8 string
 in starting at \fIbuf\fR.  The return value is the number of bytes stored
-in \fIbuf\fR.
+in \fIbuf\fR. If ch is a high surrogate (range U+D800 - U+DBFF), then
+the return value will be 1 and a single byte in the range 0xF0 - 0xF4
+will be stored. If you still want to produce UTF-8 output for it (even
+though knowing it's an illegal code-point on its own), just call
+\fBTcl_UniCharToUtf\fR again specifying ch = -1.
 .PP
 \fBTcl_UtfToUniChar\fR reads one UTF-8 character starting at \fIsrc\fR
 and stores it as a Tcl_UniChar in \fI*chPtr\fR.  The return value is the
@@ -140,13 +180,15 @@ number of bytes read from \fIsrc\fR.  The caller must ensure that the
 source buffer is long enough such that this routine does not run off the
 end and dereference non-existent or random memory; if the source buffer
 is known to be null-terminated, this will not happen.  If the input is
+a byte in the range 0x80 - 0x9F, \fBTcl_UtfToUniChar\fR assumes the
+cp1252 encoding, stores the corresponding Tcl_UniChar in \fI*chPtr\fR
+and returns 1. If the input is otherwise
 not in proper UTF-8 format, \fBTcl_UtfToUniChar\fR will store the first
-byte of \fIsrc\fR in \fI*chPtr\fR as a Tcl_UniChar between 0x80 and
-0xFF and return 1.
+byte of \fIsrc\fR in \fI*chPtr\fR as a Tcl_UniChar between 0x00A0 and
+0x00FF and return 1.
 .PP
 \fBTcl_UniCharToUtfDString\fR converts the given Unicode string
 to UTF-8, storing the result in a previously initialized \fBTcl_DString\fR.
-You must specify \fIuniLength\fR, the length of the given Unicode string.
 The return value is a pointer to the UTF-8 representation of the
 Unicode string.  Storage for the return value is appended to the
 end of the \fBTcl_DString\fR.
@@ -162,6 +204,14 @@ representation of the UTF-8 string.  Storage for the return value
 is appended to the end of the \fBTcl_DString\fR.  The Unicode string
 is terminated with a Unicode null character.
 .PP
+\fBTcl_Char16Len\fR corresponds to \fBstrlen\fR for UTF-16
+characters.  It accepts a null-terminated Unicode string and returns
+the number of Unicode characters (not bytes) in that string.
+.PP
+\fBTcl_WCharLen\fR corresponds to \fBstrlen\fR for wchar_t
+characters.  It accepts a null-terminated Unicode string and returns
+the number of Unicode characters (not bytes) in that string.
+.PP
 \fBTcl_UniCharLen\fR corresponds to \fBstrlen\fR for Unicode
 characters.  It accepts a null-terminated Unicode string and returns
 the number of Unicode characters (not bytes) in that string.
@@ -200,7 +250,7 @@ of \fIlength\fR bytes is long enough to be decoded by
 \fBTcl_UtfToUniChar\fR/\fBTcl_UtfNext\fR, or 0 otherwise.  This function
 does not guarantee that the UTF-8 string is properly formed.  This routine
 is used by procedures that are operating on a byte at a time and need to
-know if a full Tcl_UniChar has been seen.
+know if a full Unicode character has been seen.
 .PP
 \fBTcl_NumUtfChars\fR corresponds to \fBstrlen\fR for UTF-8 strings.  It
 returns the number of Tcl_UniChars that are represented by the UTF-8 string
@@ -208,12 +258,12 @@ returns the number of Tcl_UniChars that are represented by the UTF-8 string
 length is negative, all bytes up to the first null byte are used.
 .PP
 \fBTcl_UtfFindFirst\fR corresponds to \fBstrchr\fR for UTF-8 strings.  It
-returns a pointer to the first occurrence of the Tcl_UniChar \fIch\fR
+returns a pointer to the first occurrence of the Unicode character \fIch\fR
 in the null-terminated UTF-8 string \fIsrc\fR.  The null terminator is
 considered part of the UTF-8 string.
 .PP
 \fBTcl_UtfFindLast\fR corresponds to \fBstrrchr\fR for UTF-8 strings.  It
-returns a pointer to the last occurrence of the Tcl_UniChar \fIch\fR
+returns a pointer to the last occurrence of the Unicode character \fIch\fR
 in the null-terminated UTF-8 string \fIsrc\fR.  The null terminator is
 considered part of the UTF-8 string.
 .PP
@@ -239,29 +289,33 @@ always a pointer to a location in the string. It always returns a pointer to
 a byte that begins a character when scanning for characters beginning
 from \fIstart\fR. When \fIsrc\fR is greater than \fIstart\fR, it
 always returns a pointer less than \fIsrc\fR and greater than or
-equal to (\fIsrc\fR - \fBTCL_UTF_MAX\fR).  The character that begins
+equal to (\fIsrc\fR - 4).  The character that begins
 at the returned pointer is the first one that either includes the
 byte \fIsrc[-1]\fR, or might include it if the right trail bytes are
 present at \fIsrc\fR and greater. \fBTcl_UtfPrev\fR never reads the
 byte \fIsrc[0]\fR nor the byte \fIstart[-1]\fR nor the byte
-\fIsrc[-\fBTCL_UTF_MAX\fI-1]\fR.
+\fIsrc[-5]\fR.
 .PP
 \fBTcl_UniCharAtIndex\fR corresponds to a C string array dereference or the
-Pascal Ord() function.  It returns the Tcl_UniChar represented at the
+Pascal Ord() function.  It returns the Unicode character represented at the
 specified character (not byte) \fIindex\fR in the UTF-8 string
 \fIsrc\fR.  The source string must contain at least \fIindex\fR
-characters.  Behavior is undefined if a negative \fIindex\fR is given.
+characters.  If a negative \fIindex\fR is given or \fIindex\fR points
+to the second half of a surrogate pair, it returns -1.
 .PP
 \fBTcl_UtfAtIndex\fR returns a pointer to the specified character (not
 byte) \fIindex\fR in the UTF-8 string \fIsrc\fR.  The source string must
 contain at least \fIindex\fR characters.  This is equivalent to calling
-\fBTcl_UtfToUniChar\fR \fIindex\fR times.  If a negative \fIindex\fR is given,
-the return pointer points to the first character in the source string.
+\fBTcl_UtfToUniChar\fR \fIindex\fR times, except if that would return
+a pointer to the second byte of a valid 4-byte UTF-8 sequence, in which
+case, \fBTcl_UtfToUniChar\fR will be called once more to find the end
+of the sequence. If a negative \fIindex\fR is given, the returned pointer
+points to the first character in the source string.
 .PP
 \fBTcl_UtfBackslash\fR is a utility procedure used by several of the Tcl
 commands.  It parses a backslash sequence and stores the properly formed
 UTF-8 character represented by the backslash sequence in the output
-buffer \fIdst\fR.  At most \fBTCL_UTF_MAX\fR bytes are stored in the buffer.
+buffer \fIdst\fR.  At most 4 bytes are stored in the buffer.
 \fBTcl_UtfBackslash\fR modifies \fI*readPtr\fR to contain the number
 of bytes in the backslash sequence, including the backslash character.
 The return value is the number of bytes stored in the output buffer.

doc/WrongNumArgs.3

@@ -73,6 +73,12 @@ is now an \fIindexObject\fR because it was passed to
 .CS
 wrong # args: should be "foo barfly fileName count"
 .CE
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+The \fIobjv\fR argument to \fBTcl_WrongNumArgs\fR should be the exact
+arguments passed to the command or method implementation function that is
+calling \fBTcl_WrongNumArgs\fR. As such, all values referenced in it should
+have reference counts greater than zero; this is usually a non-issue.
 .SH "SEE ALSO"
 Tcl_GetIndexFromObj(3)
 .SH KEYWORDS

doc/abstract.n

@@ -0,0 +1,77 @@
+'\"
+'\" Copyright (c) 2018 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH abstract n 0.3 TclOO "TclOO Commands"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+oo::abstract \- a class that does not allow direct instances of itself
+.SH SYNOPSIS
+.nf
+package require tcl::oo
+
+\fBoo::abstract\fI method \fR?\fIarg ...\fR?
+.fi
+.SH "CLASS HIERARCHY"
+.nf
+\fBoo::object\fR
+   \(-> \fBoo::class\fR
+       \(-> \fBoo::abstract\fR
+.fi
+.BE
+.SH DESCRIPTION
+Abstract classes are classes that can contain definitions, but which cannot be
+directly manufactured; they are intended to only ever be inherited from and
+instantiated indirectly. The characteristic methods of \fBoo::class\fR
+(\fBcreate\fR and \fBnew\fR) are not exported by an instance of
+\fBoo::abstract\fR.
+.PP
+Note that \fBoo::abstract\fR is not itself an instance of \fBoo::abstract\fR.
+.SS CONSTRUCTOR
+The \fBoo::abstract\fR class does not define an explicit constructor; this
+means that it is effectively the same as the constructor of the
+\fBoo::class\fR class.
+.SS DESTRUCTOR
+The \fBoo::abstract\fR class does not define an explicit destructor;
+destroying an instance of it is just like destroying an ordinary class (and
+will destroy all its subclasses).
+.SS "EXPORTED METHODS"
+The \fBoo::abstract\fR class defines no new exported methods.
+.SS "NON-EXPORTED METHODS"
+The \fBoo::abstract\fR class explicitly states that \fBcreate\fR,
+\fBcreateWithNamespace\fR, and \fBnew\fR are unexported.
+.SH EXAMPLES
+.PP
+This example defines a simple class hierarchy and creates a new instance of
+it. It then invokes a method of the object before destroying the hierarchy and
+showing that the destruction is transitive.
+.PP
+.CS
+\fBoo::abstract\fR create fruit {
+    method eat {} {
+        puts "yummy!"
+    }
+}
+oo::class create banana {
+    superclass fruit
+    method peel {} {
+        puts "skin now off"
+    }
+}
+set b [banana \fBnew\fR]
+$b peel              \fI\(-> prints 'skin now off'\fR
+$b eat               \fI\(-> prints 'yummy!'\fR
+set f [fruit new]    \fI\(-> error 'unknown method "new"...'\fR
+.CE
+.SH "SEE ALSO"
+oo::define(n), oo::object(n)
+.SH KEYWORDS
+abstract class, class, metaclass, object
+.\" Local variables:
+.\" mode: nroff
+.\" fill-column: 78
+.\" End:

doc/append.n

@@ -20,6 +20,11 @@ Append all of the \fIvalue\fR arguments to the current value
 of variable \fIvarName\fR.  If \fIvarName\fR does not exist,
 it is given a value equal to the concatenation of all the
 \fIvalue\fR arguments.
+.VS TIP508
+If \fIvarName\fR indicate an element that does not exist of an array that has
+a default value set, the concatenation of the default value and all the
+\fIvalue\fR arguments will be stored in the array element.
+.VE TIP508
 The result of this command is the new value stored in variable
 \fIvarName\fR.
 This command provides an efficient way to build up long
@@ -44,6 +49,7 @@ puts $var
 concat(n), lappend(n)
 .SH KEYWORDS
 append, variable
-'\" Local Variables:
-'\" mode: nroff
-'\" End:
+.\" Local variables:
+.\" mode: nroff
+.\" fill-column: 78
+.\" End:

doc/array.n

@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-.TH array n 8.3 Tcl "Tcl Built-In Commands"
+.TH array n 8.7 Tcl "Tcl Built-In Commands"
 .so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
@@ -36,6 +36,53 @@ with an empty name, since the return value from
 \fBarray nextelement\fR will not indicate whether the search
 has been completed.
 .TP
+\fBarray default \fIsubcommand arrayName args...\fR
+.VS TIP508
+Manages the default value of the array. Arrays initially have no default
+value, but this command allows you to set one; the default value will be
+returned when reading from an element of the array \fIarrayName\fR if the read
+would otherwise result in an error. Note that this may cause the \fBappend\fR,
+\fBdict\fR, \fBincr\fR and \fBlappend\fR commands to change their behavior in
+relation to non-existing array elements.
+.RS
+.PP
+The \fIsubcommand\fR argument controls what exact operation will be performed
+on the default value of \fIarrayName\fR. Supported \fIsubcommand\fRs are:
+.VE TIP508
+.TP
+\fBarray default exists \fIarrayName\fR
+.VS TIP508
+This returns a boolean value indicating whether a default value has been set
+for the array \fIarrayName\fR. Returns a false value if \fIarrayName\fR does
+not exist. Raises an error if \fIarrayName\fR is an existing variable that is
+not an array.
+.VE TIP508
+.TP
+\fBarray default get \fIarrayName\fR
+.VS TIP508
+This returns the current default value for the array \fIarrayName\fR.  Raises
+an error if \fIarrayName\fR is an existing variable that is not an array, or
+if \fIarrayName\fR is an array without a default value.
+.VE TIP508
+.TP
+\fBarray default set \fIarrayName value\fR
+.VS TIP508
+This sets the default value for the array \fIarrayName\fR to \fIvalue\fR.
+Returns the empty string. Raises an error if \fIarrayName\fR is an existing
+variable that is not an array, or if \fIarrayName\fR is an illegal name for an
+array. If \fIarrayName\fR does not currently exist, it is created as an empty
+array as well as having its default value set.
+.VE TIP508
+.TP
+\fBarray default unset \fIarrayName\fR
+.VS TIP508
+This removes the default value for the array \fIarrayName\fR and returns the
+empty string. Does nothing if \fIarrayName\fR does not have a default
+value. Raises an error if \fIarrayName\fR is an existing variable that is not
+an array.
+.VE TIP508
+.RE
+.TP
 \fBarray donesearch \fIarrayName searchId\fR
 This command terminates an array search and destroys all the
 state associated with that search.  \fISearchId\fR indicates
@@ -47,6 +94,15 @@ been the return value from a previous invocation of
 Returns 1 if \fIarrayName\fR is an array variable, 0 if there
 is no variable by that name or if it is a scalar variable.
 .TP
+\fBarray for {\fIkeyVariable valueVariable\fB} \fIarrayName body\fP
+The first argument is a two element list of variable names for the
+key and value of each entry in the array.  The second argument is the
+array name to iterate over.  The third argument is the body to execute
+for each key and value returned.
+The ordering of the returned keys is undefined.
+If an array element is deleted or a new array element is inserted during
+the \fIarray for\fP process, the command will terminate with an error.
+.TP
 \fBarray get \fIarrayName\fR ?\fIpattern\fR?
 Returns a list containing pairs of elements.  The first
 element in each pair is the name of an element in \fIarrayName\fR
@@ -185,3 +241,7 @@ foreach color [lsort [\fBarray names\fR colorcount]] {
 list(n), string(n), variable(n), trace(n), foreach(n)
 .SH KEYWORDS
 array, element names, search
+.\" Local variables:
+.\" mode: nroff
+.\" fill-column: 78
+.\" End:

doc/binary.n

@@ -12,12 +12,10 @@
 .SH NAME
 binary \- Insert and extract fields from binary strings
 .SH SYNOPSIS
-.VS 8.6
 \fBbinary decode \fIformat\fR ?\fI\-option value ...\fR? \fIdata\fR
 .br
 \fBbinary encode \fIformat\fR ?\fI\-option value ...\fR? \fIdata\fR
 .br
-.VE 8.6
 \fBbinary format \fIformatString \fR?\fIarg arg ...\fR?
 .br
 \fBbinary scan \fIstring formatString \fR?\fIvarName varName ...\fR?
@@ -31,11 +29,9 @@ architecture, it might produce an 8-byte binary string consisting of
 two 4-byte integers, one for each of the numbers.  The subcommand
 \fBbinary scan\fR, does the opposite: it extracts data
 from a binary string and returns it as ordinary Tcl string values.
-.VS 8.6
 The \fBbinary encode\fR and \fBbinary decode\fR subcommands convert
 binary data to or from string encodings such as base64 (used in MIME
 messages for example).
-.VE 8.6
 .PP
 Note that other operations on binary data, such as taking a subsequence of it,
 getting its length, or reinterpreting it as a string in some encoding, are
@@ -44,7 +40,6 @@ done by other Tcl commands (respectively \fBstring range\fR,
 binary string in Tcl is merely one where all the characters it contains are in
 the range \eu0000\-\eu00FF.
 .SH "BINARY ENCODE AND DECODE"
-.VS 8.6
 .PP
 When encoding binary data as a readable string, the starting binary data is
 passed to the \fBbinary encode\fR command, together with the name of the
@@ -137,7 +132,6 @@ between the encoder and decoder.
 Note that neither the encoder nor the decoder handle the header and footer of
 the uuencode format.
 .RE
-.VE 8.6
 .SH "BINARY FORMAT"
 .PP
 The \fBbinary format\fR command generates a binary string whose layout
@@ -152,7 +146,9 @@ Most field specifiers consume one argument to obtain the value to be
 formatted.  The type character specifies how the value is to be
 formatted.  The \fIcount\fR typically indicates how many items of the
 specified type are taken from the value.  If present, the \fIcount\fR
-is a non-negative decimal integer or \fB*\fR, which normally indicates
+is a non-negative decimal integer or
+.QW \fB*\fR ,
+which normally indicates
 that all of the items in the value are to be used.  If the number of
 arguments does not match the number of fields in the format string
 that consume arguments, then an error is generated. The flag character
@@ -160,6 +156,7 @@ is ignored for \fBbinary format\fR.
 .PP
 Here is a small example to clarify the relation between the field
 specifiers and the arguments:
+.PP
 .CS
 \fBbinary format\fR d3d {1.0 2.0 3.0 4.0} 0.1
 .CE
@@ -187,29 +184,63 @@ not part of the ISO 8859\-1 character set.)
 If \fIarg\fR has fewer than \fIcount\fR bytes, then additional zero
 bytes are used to pad out the field.  If \fIarg\fR is longer than the
 specified length, the extra characters will be ignored.  If
-\fIcount\fR is \fB*\fR, then all of the bytes in \fIarg\fR will be
+\fIcount\fR is
+.QW \fB*\fR ,
+then all of the bytes in \fIarg\fR will be
 formatted.  If \fIcount\fR is omitted, then one character will be
-formatted.  For example,
+formatted.  For example, the command:
 .RS
+.PP
 .CS
 \fBbinary format\fR a7a*a alpha bravo charlie
 .CE
-will return a string equivalent to \fBalpha\e000\e000bravoc\fR,
+.PP
+will return a binary string equivalent to:
+.PP
+.CS
+\fBalpha\e000\e000bravoc\fR
+.CE
+.PP
+the command:
+.PP
 .CS
 \fBbinary format\fR a* [encoding convertto utf-8 \eu20ac]
 .CE
-will return a string equivalent to \fB\e342\e202\e254\fR (which is the
-UTF-8 byte sequence for a Euro-currency character) and
+.PP
+will return a binary string equivalent to:
+.PP
+.CS
+\fB\e342\e202\e254\fR
+.CE
+.PP
+(which is the
+UTF-8 byte sequence for a Euro-currency character), and the command:
+.PP
 .CS
 \fBbinary format\fR a* [encoding convertto iso8859-15 \eu20ac]
 .CE
-will return a string equivalent to \fB\e244\fR (which is the ISO
+.PP
+will return a binary string equivalent to:
+.PP
+.CS
+\fB\e244\fR
+.CE
+.PP
+(which is the ISO
 8859\-15 byte sequence for a Euro-currency character). Contrast these
 last two with:
+.PP
 .CS
 \fBbinary format\fR a* \eu20ac
 .CE
-which returns a string equivalent to \fB\e254\fR (i.e. \fB\exac\fR) by
+.PP
+which returns a binary string equivalent to:
+.PP
+.CS
+\fB\e254\fR
+.CE
+.PP
+(i.e. \fB\exac\fR) by
 truncating the high-bits of the character, and which is probably not
 what is desired.
 .RE
@@ -217,42 +248,62 @@ what is desired.
 This form is the same as \fBa\fR except that spaces are used for
 padding instead of nulls.  For example,
 .RS
+.PP
 .CS
 \fBbinary format\fR A6A*A alpha bravo charlie
 .CE
-will return \fBalpha bravoc\fR.
+.PP
+will return
+.PP
+.CS
+\fBalpha bravoc\fR
+.CE
 .RE
 .IP \fBb\fR 5
 Stores a string of \fIcount\fR binary digits in low-to-high order
-within each byte in the output string.  \fIArg\fR must contain a
+within each byte in the output binary string.  \fIArg\fR must contain a
 sequence of \fB1\fR and \fB0\fR characters.  The resulting bytes are
 emitted in first to last order with the bits being formatted in
 low-to-high order within each byte.  If \fIarg\fR has fewer than
 \fIcount\fR digits, then zeros will be used for the remaining bits.
 If \fIarg\fR has more than the specified number of digits, the extra
-digits will be ignored.  If \fIcount\fR is \fB*\fR, then all of the
+digits will be ignored.  If \fIcount\fR is
+.QW \fB*\fR ,
+then all of the
 digits in \fIarg\fR will be formatted.  If \fIcount\fR is omitted,
 then one digit will be formatted.  If the number of bits formatted
 does not end at a byte boundary, the remaining bits of the last byte
 will be zeros.  For example,
 .RS
+.PP
 .CS
 \fBbinary format\fR b5b* 11100 111000011010
 .CE
-will return a string equivalent to \fB\ex07\ex87\ex05\fR.
+.PP
+will return a binary string equivalent to:
+.PP
+.CS
+\fB\ex07\ex87\ex05\fR
+.CE
 .RE
 .IP \fBB\fR 5
 This form is the same as \fBb\fR except that the bits are stored in
 high-to-low order within each byte.  For example,
 .RS
+.PP
 .CS
 \fBbinary format\fR B5B* 11100 111000011010
 .CE
-will return a string equivalent to \fB\exe0\exe1\exa0\fR.
+.PP
+will return a binary string equivalent to:
+.PP
+.CS
+\fB\exe0\exe1\exa0\fR
+.CE
 .RE
 .IP \fBH\fR 5
 Stores a string of \fIcount\fR hexadecimal digits in high-to-low
-within each byte in the output string.  \fIArg\fR must contain a
+within each byte in the output binary string.  \fIArg\fR must contain a
 sequence of characters in the set
 .QW 0123456789abcdefABCDEF .
 The resulting bytes are emitted in first to last order with the hex digits
@@ -260,43 +311,66 @@ being formatted in high-to-low order within each byte.  If \fIarg\fR
 has fewer than \fIcount\fR digits, then zeros will be used for the
 remaining digits.  If \fIarg\fR has more than the specified number of
 digits, the extra digits will be ignored.  If \fIcount\fR is
-\fB*\fR, then all of the digits in \fIarg\fR will be formatted.  If
+.QW \fB*\fR ,
+then all of the digits in \fIarg\fR will be formatted.  If
 \fIcount\fR is omitted, then one digit will be formatted.  If the
 number of digits formatted does not end at a byte boundary, the
 remaining bits of the last byte will be zeros.  For example,
 .RS
+.PP
 .CS
 \fBbinary format\fR H3H*H2 ab DEF 987
 .CE
-will return a string equivalent to \fB\exab\ex00\exde\exf0\ex98\fR.
+.PP
+will return a binary string equivalent to:
+.PP
+.CS
+\fB\exab\ex00\exde\exf0\ex98\fR
+.CE
 .RE
 .IP \fBh\fR 5
 This form is the same as \fBH\fR except that the digits are stored in
 low-to-high order within each byte. This is seldom required. For example,
 .RS
+.PP
 .CS
 \fBbinary format\fR h3h*h2 AB def 987
 .CE
-will return a string equivalent to \fB\exba\ex00\exed\ex0f\ex89\fR.
+.PP
+will return a binary string equivalent to:
+.PP
+.CS
+\fB\exba\ex00\exed\ex0f\ex89\fR
+.CE
 .RE
 .IP \fBc\fR 5
 Stores one or more 8-bit integer values in the output string.  If no
 \fIcount\fR is specified, then \fIarg\fR must consist of an integer
 value. If \fIcount\fR is specified, \fIarg\fR must consist of a list
 containing at least that many integers. The low-order 8 bits of each integer
-are stored as a one-byte value at the cursor position.  If \fIcount\fR
-is \fB*\fR, then all of the integers in the list are formatted. If the
+are stored as a one-byte value at the cursor position.  If \fIcount\fR is
+.QW \fB*\fR ,
+then all of the integers in the list are formatted. If the
 number of elements in the list is greater
 than \fIcount\fR, then the extra elements are ignored.  For example,
 .RS
+.PP
 .CS
 \fBbinary format\fR c3cc* {3 -3 128 1} 260 {2 5}
 .CE
-will return a string equivalent to
-\fB\ex03\exfd\ex80\ex04\ex02\ex05\fR, whereas
+.PP
+will return a binary string equivalent to:
+.PP
+.CS
+\fB\ex03\exfd\ex80\ex04\ex02\ex05\fR
+.CE
+.PP
+whereas:
+.PP
 .CS
 \fBbinary format\fR c {2 5}
 .CE
+.PP
 will generate an error.
 .RE
 .IP \fBs\fR 5
@@ -306,22 +380,32 @@ low-order 16-bits of each integer are stored as a two-byte value at
 the cursor position with the least significant byte stored first.  For
 example,
 .RS
+.PP
 .CS
 \fBbinary format\fR s3 {3 -3 258 1}
 .CE
-will return a string equivalent to
-\fB\ex03\ex00\exfd\exff\ex02\ex01\fR.
+.PP
+will return a binary string equivalent to:
+.PP
+.CS
+\fB\ex03\ex00\exfd\exff\ex02\ex01\fR
+.CE
 .RE
 .IP \fBS\fR 5
 This form is the same as \fBs\fR except that it stores one or more
 16-bit integers in big-endian byte order in the output string.  For
 example,
 .RS
+.PP
 .CS
 \fBbinary format\fR S3 {3 -3 258 1}
 .CE
-will return a string equivalent to
-\fB\ex00\ex03\exff\exfd\ex01\ex02\fR.
+.PP
+will return a binary string equivalent to:
+.PP
+.CS
+\fB\ex00\ex03\exff\exfd\ex01\ex02\fR
+.CE
 .RE
 .IP \fBt\fR 5
 This form (mnemonically \fItiny\fR) is the same as \fBs\fR and \fBS\fR
@@ -336,22 +420,32 @@ low-order 32-bits of each integer are stored as a four-byte value at
 the cursor position with the least significant byte stored first.  For
 example,
 .RS
+.PP
 .CS
 \fBbinary format\fR i3 {3 -3 65536 1}
 .CE
-will return a string equivalent to
+.PP
+will return a binary string equivalent to:
+.PP
+.CS
 \fB\ex03\ex00\ex00\ex00\exfd\exff\exff\exff\ex00\ex00\ex01\ex00\fR
+.CE
 .RE
 .IP \fBI\fR 5
 This form is the same as \fBi\fR except that it stores one or more one
 or more 32-bit integers in big-endian byte order in the output string.
 For example,
 .RS
+.PP
 .CS
 \fBbinary format\fR I3 {3 -3 65536 1}
 .CE
-will return a string equivalent to
+.PP
+will return a binary string equivalent to:
+.PP
+.CS
 \fB\ex00\ex00\ex00\ex03\exff\exff\exff\exfd\ex00\ex01\ex00\ex00\fR
+.CE
 .RE
 .IP \fBn\fR 5
 This form (mnemonically \fInumber\fR or \fInormal\fR) is the same as
@@ -367,20 +461,24 @@ low-order 64-bits of each integer are stored as an eight-byte value at
 the cursor position with the least significant byte stored first.  For
 example,
 .RS
+.PP
 .CS
 \fBbinary format\fR w 7810179016327718216
 .CE
-will return the string \fBHelloTcl\fR
+.PP
+will return the binary string \fBHelloTcl\fR.
 .RE
 .IP \fBW\fR 5
 This form is the same as \fBw\fR except that it stores one or more one
 or more 64-bit integers in big-endian byte order in the output string.
 For example,
 .RS
+.PP
 .CS
 \fBbinary format\fR Wc 4785469626960341345 110
 .CE
-will return the string \fBBigEndian\fR
+.PP
+will return the binary string \fBBigEndian\fR
 .RE
 .IP \fBm\fR 5
 This form (mnemonically the mirror of \fBw\fR) is the same as \fBw\fR
@@ -403,11 +501,16 @@ double-precision floating point numbers internally, there may be some
 loss of precision in the conversion to single-precision.  For example,
 on a Windows system running on an Intel Pentium processor,
 .RS
+.PP
 .CS
 \fBbinary format\fR f2 {1.6 3.4}
 .CE
-will return a string equivalent to
-\fB\excd\excc\excc\ex3f\ex9a\ex99\ex59\ex40\fR.
+.PP
+will return a binary string equivalent to:
+.PP
+.CS
+\fB\excd\excc\excc\ex3f\ex9a\ex99\ex59\ex40\fR
+.CE
 .RE
 .IP \fBr\fR 5
 This form (mnemonically \fIreal\fR) is the same as \fBf\fR except that
@@ -424,11 +527,16 @@ or more double-precision floating point numbers in the machine's native
 representation in the output string.  For example, on a
 Windows system running on an Intel Pentium processor,
 .RS
+.PP
 .CS
 \fBbinary format\fR d1 {1.6}
 .CE
-will return a string equivalent to
-\fB\ex9a\ex99\ex99\ex99\ex99\ex99\exf9\ex3f\fR.
+.PP
+will return a binary string equivalent to:
+.PP
+.CS
+\fB\ex9a\ex99\ex99\ex99\ex99\ex99\exf9\ex3f\fR
+.CE
 .RE
 .IP \fBq\fR 5
 This form (mnemonically the mirror of \fBd\fR) is the same as \fBd\fR
@@ -441,26 +549,37 @@ This form is the same as \fBq\fR except that it stores the
 double-precision floating point numbers in big-endian order.
 .IP \fBx\fR 5
 Stores \fIcount\fR null bytes in the output string.  If \fIcount\fR is
-not specified, stores one null byte.  If \fIcount\fR is \fB*\fR,
+not specified, stores one null byte.  If \fIcount\fR is
+.QW \fB*\fR ,
 generates an error.  This type does not consume an argument.  For
 example,
 .RS
+.PP
 .CS
 \fBbinary format\fR a3xa3x2a3 abc def ghi
 .CE
-will return a string equivalent to \fBabc\e000def\e000\e000ghi\fR.
+.PP
+will return a binary string equivalent to:
+.PP
+.CS
+\fBabc\e000def\e000\e000ghi\fR
+.CE
 .RE
 .IP \fBX\fR 5
 Moves the cursor back \fIcount\fR bytes in the output string.  If
-\fIcount\fR is \fB*\fR or is larger than the current cursor position,
+\fIcount\fR is
+.QW \fB*\fR
+or is larger than the current cursor position,
 then the cursor is positioned at location 0 so that the next byte
 stored will be the first byte in the result string.  If \fIcount\fR is
 omitted then the cursor is moved back one byte.  This type does not
 consume an argument.  For example,
 .RS
+.PP
 .CS
 \fBbinary format\fR a3X*a3X2a3 abc def ghi
 .CE
+.PP
 will return \fBdghi\fR.
 .RE
 .IP \fB@\fR 5
@@ -469,14 +588,22 @@ specified by \fIcount\fR.  Position 0 refers to the first byte in the
 output string.  If \fIcount\fR refers to a position beyond the last
 byte stored so far, then null bytes will be placed in the uninitialized
 locations and the cursor will be placed at the specified location.  If
-\fIcount\fR is \fB*\fR, then the cursor is moved to the current end of
+\fIcount\fR is
+.QW \fB*\fR ,
+then the cursor is moved to the current end of
 the output string.  If \fIcount\fR is omitted, then an error will be
 generated.  This type does not consume an argument. For example,
 .RS
+.PP
 .CS
 \fBbinary format\fR a5@2a1@*a3@10a1 abcde f ghi j
 .CE
-will return \fBabfdeghi\e000\e000j\fR.
+.PP
+will return
+.PP
+.CS
+\fBabfdeghi\e000\e000j\fR
+.CE
 .RE
 .SH "BINARY SCAN"
 .PP
@@ -498,8 +625,9 @@ argument to obtain the variable into which the scanned values should
 be placed.  The type character specifies how the binary data is to be
 interpreted.  The \fIcount\fR typically indicates how many items of
 the specified type are taken from the data.  If present, the
-\fIcount\fR is a non-negative decimal integer or \fB*\fR, which
-normally indicates that all of the remaining items in the data are to
+\fIcount\fR is a non-negative decimal integer or
+.QW \fB*\fR ,
+which normally indicates that all of the remaining items in the data are to
 be used.  If there are not enough bytes left after the current cursor
 position to satisfy the current field specifier, then the
 corresponding variable is left untouched and \fBbinary scan\fR returns
@@ -513,6 +641,7 @@ is accepted for all field types but is ignored for non-integer fields.
 A similar example as with \fBbinary format\fR should explain the
 relation between field specifiers and arguments in case of the binary
 scan subcommand:
+.PP
 .CS
 \fBbinary scan\fR $bytes s3s first second
 .CE
@@ -524,12 +653,15 @@ If \fIbytes\fR contains fewer than 8 bytes (i.e. four 2-byte
 integers), no assignment to \fIsecond\fR will be made, and if
 \fIbytes\fR contains fewer than 6 bytes (i.e. three 2-byte integers),
 no assignment to \fIfirst\fR will be made.  Hence:
+.PP
 .CS
 puts [\fBbinary scan\fR abcdefg s3s first second]
 puts $first
 puts $second
 .CE
+.PP
 will print (assuming neither variable is set previously):
+.PP
 .CS
 1
 25185 25699 26213
@@ -541,14 +673,17 @@ It is \fIimportant\fR to note that the \fBc\fR, \fBs\fR, and \fBS\fR
 long data size values.  In doing this, values that have their high
 bit set (0x80 for chars, 0x8000 for shorts, 0x80000000 for ints),
 will be sign extended.  Thus the following will occur:
+.PP
 .CS
 set signShort [\fBbinary format\fR s1 0x8000]
 \fBbinary scan\fR $signShort s1 val; \fI# val == 0xFFFF8000\fR
 .CE
+.PP
 If you require unsigned values you can include the
 .QW u
 flag character following
 the field type. For example, to read an unsigned short value:
+.PP
 .CS
 set signShort [\fBbinary format\fR s1 0x8000]
 \fBbinary scan\fR $signShort su1 val; \fI# val == 0x00008000\fR
@@ -559,8 +694,9 @@ reading bytes from the current position.  The cursor is initially
 at position 0 at the beginning of the data.  The type may be any one of
 the following characters:
 .IP \fBa\fR 5
-The data is a byte string of length \fIcount\fR.  If \fIcount\fR
-is \fB*\fR, then all of the remaining bytes in \fIstring\fR will be
+The data is a byte string of length \fIcount\fR.  If \fIcount\fR is
+.QW \fB*\fR ,
+then all of the remaining bytes in \fIstring\fR will be
 scanned into the variable.  If \fIcount\fR is omitted, then one
 byte will be scanned.
 All bytes scanned will be interpreted as being characters in the
@@ -569,24 +705,30 @@ needed if the string is not a binary string or a string encoded in ISO
 8859\-1.
 For example,
 .RS
+.PP
 .CS
 \fBbinary scan\fR abcde\e000fghi a6a10 var1 var2
 .CE
+.PP
 will return \fB1\fR with the string equivalent to \fBabcde\e000\fR
 stored in \fIvar1\fR and \fIvar2\fR left unmodified, and
+.PP
 .CS
 \fBbinary scan\fR \e342\e202\e254 a* var1
 set var2 [encoding convertfrom utf-8 $var1]
 .CE
+.PP
 will store a Euro-currency character in \fIvar2\fR.
 .RE
 .IP \fBA\fR 5
 This form is the same as \fBa\fR, except trailing blanks and nulls are stripped from
 the scanned value before it is stored in the variable.  For example,
 .RS
+.PP
 .CS
 \fBbinary scan\fR "abc efghi  \e000" A* var1
 .CE
+.PP
 will return \fB1\fR with \fBabc efghi\fR stored in \fIvar1\fR.
 .RE
 .IP \fBb\fR 5
@@ -597,13 +739,16 @@ and
 .QW 0
 characters.  The data bytes are scanned in first to last order with
 the bits being taken in low-to-high order within each byte.  Any extra
-bits in the last byte are ignored.  If \fIcount\fR is \fB*\fR, then
-all of the remaining bits in \fIstring\fR will be scanned.  If
+bits in the last byte are ignored.  If \fIcount\fR is
+.QW \fB*\fR ,
+then all of the remaining bits in \fIstring\fR will be scanned.  If
 \fIcount\fR is omitted, then one bit will be scanned.  For example,
 .RS
+.PP
 .CS
 \fBbinary scan\fR \ex07\ex87\ex05 b5b* var1 var2
 .CE
+.PP
 will return \fB2\fR with \fB11100\fR stored in \fIvar1\fR and
 \fB1110000110100000\fR stored in \fIvar2\fR.
 .RE
@@ -611,12 +756,23 @@ will return \fB2\fR with \fB11100\fR stored in \fIvar1\fR and
 This form is the same as \fBb\fR, except the bits are taken in
 high-to-low order within each byte.  For example,
 .RS
+.PP
 .CS
 \fBbinary scan\fR \ex70\ex87\ex05 B5B* var1 var2
 .CE
+.PP
 will return \fB2\fR with \fB01110\fR stored in \fIvar1\fR and
 \fB1000011100000101\fR stored in \fIvar2\fR.
 .RE
+.IP \fBC\fR 5
+This form is similar to \fBA\fR, except that it scans the data from start
+and terminates at the first null (C string semantics). For example,
+.RS
+.CS
+\fBbinary scan\fR "abc\e000efghi" C* var1
+.CE
+will return \fB1\fR with \fBabc\fR stored in \fIvar1\fR.
+.RE
 .IP \fBH\fR 5
 The data is turned into a string of \fIcount\fR hexadecimal digits in
 high-to-low order represented as a sequence of characters in the set
@@ -624,13 +780,16 @@ high-to-low order represented as a sequence of characters in the set
 The data bytes are scanned in first to last
 order with the hex digits being taken in high-to-low order within each
 byte. Any extra bits in the last byte are ignored. If \fIcount\fR is
-\fB*\fR, then all of the remaining hex digits in \fIstring\fR will be
+.QW \fB*\fR ,
+then all of the remaining hex digits in \fIstring\fR will be
 scanned. If \fIcount\fR is omitted, then one hex digit will be
 scanned. For example,
 .RS
+.PP
 .CS
 \fBbinary scan\fR \ex07\exC6\ex05\ex1f\ex34 H3H* var1 var2
 .CE
+.PP
 will return \fB2\fR with \fB07c\fR stored in \fIvar1\fR and
 \fB051f34\fR stored in \fIvar2\fR.
 .RE
@@ -638,9 +797,11 @@ will return \fB2\fR with \fB07c\fR stored in \fIvar1\fR and
 This form is the same as \fBH\fR, except the digits are taken in
 reverse (low-to-high) order within each byte. For example,
 .RS
+.PP
 .CS
 \fBbinary scan\fR \ex07\ex86\ex05\ex12\ex34 h3h* var1 var2
 .CE
+.PP
 will return \fB2\fR with \fB706\fR stored in \fIvar1\fR and
 \fB502143\fR stored in \fIvar2\fR.
 .PP
@@ -649,135 +810,151 @@ multiple bytes in order should use the \fBH\fR format.
 .RE
 .IP \fBc\fR 5
 The data is turned into \fIcount\fR 8-bit signed integers and stored
-in the corresponding variable as a list. If \fIcount\fR is \fB*\fR,
+in the corresponding variable as a list, or as unsigned if \fBu\fR is placed
+immediately after the \fBc\fR. If \fIcount\fR is
+.QW \fB*\fR ,
 then all of the remaining bytes in \fIstring\fR will be scanned.  If
 \fIcount\fR is omitted, then one 8-bit integer will be scanned.  For
 example,
 .RS
+.PP
 .CS
 \fBbinary scan\fR \ex07\ex86\ex05 c2c* var1 var2
 .CE
+.PP
 will return \fB2\fR with \fB7 -122\fR stored in \fIvar1\fR and \fB5\fR
-stored in \fIvar2\fR.  Note that the integers returned are signed, but
-they can be converted to unsigned 8-bit quantities using an expression
-like:
-.CS
-set num [expr { $num & 0xFF }]
-.CE
+stored in \fIvar2\fR.  Note that the integers returned are signed unless
+\fBcu\fR in place of \fBc\fR.
 .RE
 .IP \fBs\fR 5
 The data is interpreted as \fIcount\fR 16-bit signed integers
-represented in little-endian byte order.  The integers are stored in
-the corresponding variable as a list.  If \fIcount\fR is \fB*\fR, then
-all of the remaining bytes in \fIstring\fR will be scanned.  If
+represented in little-endian byte order, or as unsigned if \fBu\fR is placed
+immediately after the \fBs\fR.  The integers are stored in
+the corresponding variable as a list.  If \fIcount\fR is
+.QW \fB*\fR ,
+then all of the remaining bytes in \fIstring\fR will be scanned.  If
 \fIcount\fR is omitted, then one 16-bit integer will be scanned.  For
 example,
 .RS
+.PP
 .CS
 \fBbinary scan\fR \ex05\ex00\ex07\ex00\exf0\exff s2s* var1 var2
 .CE
+.PP
 will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB\-16\fR
-stored in \fIvar2\fR.  Note that the integers returned are signed, but
-they can be converted to unsigned 16-bit quantities using an expression
-like:
-.CS
-set num [expr { $num & 0xFFFF }]
-.CE
+stored in \fIvar2\fR.  Note that the integers returned are signed unless
+\fBsu\fR is used in place of \fBs\fR.
 .RE
 .IP \fBS\fR 5
 This form is the same as \fBs\fR except that the data is interpreted
-as \fIcount\fR 16-bit signed integers represented in big-endian byte
+as \fIcount\fR 16-bit integers represented in big-endian byte
 order.  For example,
 .RS
+.PP
 .CS
 \fBbinary scan\fR \ex00\ex05\ex00\ex07\exff\exf0 S2S* var1 var2
 .CE
+.PP
 will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB\-16\fR
 stored in \fIvar2\fR.
 .RE
 .IP \fBt\fR 5
 The data is interpreted as \fIcount\fR 16-bit signed integers
 represented in the native byte order of the machine running the Tcl
-script.  It is otherwise identical to \fBs\fR and \fBS\fR.
+script, or as unsigned if \fBu\fR is placed
+immediately after the \fBt\fR.  It is otherwise identical to \fBs\fR and \fBS\fR.
 To determine what the native byte order of the machine is, refer to
 the \fBbyteOrder\fR element of the \fBtcl_platform\fR array.
 .IP \fBi\fR 5
 The data is interpreted as \fIcount\fR 32-bit signed integers
-represented in little-endian byte order.  The integers are stored in
-the corresponding variable as a list.  If \fIcount\fR is \fB*\fR, then
-all of the remaining bytes in \fIstring\fR will be scanned.  If
+represented in little-endian byte order, or as unsigned if \fBu\fR is placed
+immediately after the \fBi\fR.  The integers are stored in
+the corresponding variable as a list.  If \fIcount\fR is
+.QW \fB*\fR ,
+then all of the remaining bytes in \fIstring\fR will be scanned.  If
 \fIcount\fR is omitted, then one 32-bit integer will be scanned.  For
 example,
 .RS
+.PP
 .CS
 set str \ex05\ex00\ex00\ex00\ex07\ex00\ex00\ex00\exf0\exff\exff\exff
 \fBbinary scan\fR $str i2i* var1 var2
 .CE
+.PP
 will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB\-16\fR
-stored in \fIvar2\fR.  Note that the integers returned are signed, but
-they can be converted to unsigned 32-bit quantities using an expression
-like:
-.CS
-set num [expr { $num & 0xFFFFFFFF }]
-.CE
+stored in \fIvar2\fR.  Note that the integers returned are signed unless
+\fBiu\fR is used in place of \fBi\fR.
 .RE
 .IP \fBI\fR 5
 This form is the same as \fBI\fR except that the data is interpreted
 as \fIcount\fR 32-bit signed integers represented in big-endian byte
-order.  For example,
+order, or as unsigned if \fBu\fR is placed
+immediately after the \fBI\fR.  For example,
 .RS
+.PP
 .CS
 set str \ex00\ex00\ex00\ex05\ex00\ex00\ex00\ex07\exff\exff\exff\exf0
 \fBbinary scan\fR $str I2I* var1 var2
 .CE
+.PP
 will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB\-16\fR
 stored in \fIvar2\fR.
 .RE
 .IP \fBn\fR 5
 The data is interpreted as \fIcount\fR 32-bit signed integers
 represented in the native byte order of the machine running the Tcl
-script.  It is otherwise identical to \fBi\fR and \fBI\fR.
+script, or as unsigned if \fBu\fR is placed
+immediately after the \fBn\fR.  It is otherwise identical to \fBi\fR and \fBI\fR.
 To determine what the native byte order of the machine is, refer to
 the \fBbyteOrder\fR element of the \fBtcl_platform\fR array.
 .IP \fBw\fR 5
 The data is interpreted as \fIcount\fR 64-bit signed integers
-represented in little-endian byte order.  The integers are stored in
-the corresponding variable as a list.  If \fIcount\fR is \fB*\fR, then
-all of the remaining bytes in \fIstring\fR will be scanned.  If
+represented in little-endian byte order, or as unsigned if \fBu\fR is placed
+immediately after the \fBw\fR.  The integers are stored in
+the corresponding variable as a list.  If \fIcount\fR is
+.QW \fB*\fR ,
+then all of the remaining bytes in \fIstring\fR will be scanned.  If
 \fIcount\fR is omitted, then one 64-bit integer will be scanned.  For
 example,
 .RS
+.PP
 .CS
 set str \ex05\ex00\ex00\ex00\ex07\ex00\ex00\ex00\exf0\exff\exff\exff
 \fBbinary scan\fR $str wi* var1 var2
 .CE
+.PP
 will return \fB2\fR with \fB30064771077\fR stored in \fIvar1\fR and
-\fB\-16\fR stored in \fIvar2\fR.  Note that the integers returned are
-signed and cannot be represented by Tcl as unsigned values.
+\fB\-16\fR stored in \fIvar2\fR.
 .RE
 .IP \fBW\fR 5
 This form is the same as \fBw\fR except that the data is interpreted
 as \fIcount\fR 64-bit signed integers represented in big-endian byte
-order.  For example,
+order, or as unsigned if \fBu\fR is placed
+immediately after the \fBW\fR.  For example,
 .RS
+.PP
 .CS
 set str \ex00\ex00\ex00\ex05\ex00\ex00\ex00\ex07\exff\exff\exff\exf0
 \fBbinary scan\fR $str WI* var1 var2
 .CE
+.PP
 will return \fB2\fR with \fB21474836487\fR stored in \fIvar1\fR and \fB\-16\fR
 stored in \fIvar2\fR.
 .RE
 .IP \fBm\fR 5
 The data is interpreted as \fIcount\fR 64-bit signed integers
 represented in the native byte order of the machine running the Tcl
-script.  It is otherwise identical to \fBw\fR and \fBW\fR.
+script, or as unsigned if \fBu\fR is placed
+immediately after the \fBm\fR.  It is otherwise identical to \fBw\fR and \fBW\fR.
 To determine what the native byte order of the machine is, refer to
 the \fBbyteOrder\fR element of the \fBtcl_platform\fR array.
 .IP \fBf\fR 5
 The data is interpreted as \fIcount\fR single-precision floating point
 numbers in the machine's native representation.  The floating point
 numbers are stored in the corresponding variable as a list.  If
-\fIcount\fR is \fB*\fR, then all of the remaining bytes in
+\fIcount\fR is
+.QW \fB*\fR ,
+then all of the remaining bytes in
 \fIstring\fR will be scanned.  If \fIcount\fR is omitted, then one
 single-precision floating point number will be scanned.  The size of a
 floating point number may vary across architectures, so the number of
@@ -786,9 +963,11 @@ valid floating point number, the resulting value is undefined and
 compiler dependent.  For example, on a Windows system running on an
 Intel Pentium processor,
 .RS
+.PP
 .CS
 \fBbinary scan\fR \ex3f\excc\excc\excd f var1
 .CE
+.PP
 will return \fB1\fR with \fB1.6000000238418579\fR stored in
 \fIvar1\fR.
 .RE
@@ -808,9 +987,11 @@ as \fIcount\fR double-precision floating point numbers in the
 machine's native representation. For example, on a Windows system
 running on an Intel Pentium processor,
 .RS
+.PP
 .CS
 \fBbinary scan\fR \ex9a\ex99\ex99\ex99\ex99\ex99\exf9\ex3f d var1
 .CE
+.PP
 will return \fB1\fR with \fB1.6000000000000001\fR
 stored in \fIvar1\fR.
 .RE
@@ -826,28 +1007,36 @@ order.  This conversion is not portable to the minority of systems not
 using IEEE floating point representations.
 .IP \fBx\fR 5
 Moves the cursor forward \fIcount\fR bytes in \fIstring\fR.  If
-\fIcount\fR is \fB*\fR or is larger than the number of bytes after the
+\fIcount\fR is
+.QW \fB*\fR
+or is larger than the number of bytes after the
 current cursor position, then the cursor is positioned after
 the last byte in \fIstring\fR.  If \fIcount\fR is omitted, then the
 cursor is moved forward one byte.  Note that this type does not
 consume an argument.  For example,
 .RS
+.PP
 .CS
 \fBbinary scan\fR \ex01\ex02\ex03\ex04 x2H* var1
 .CE
+.PP
 will return \fB1\fR with \fB0304\fR stored in \fIvar1\fR.
 .RE
 .IP \fBX\fR 5
 Moves the cursor back \fIcount\fR bytes in \fIstring\fR.  If
-\fIcount\fR is \fB*\fR or is larger than the current cursor position,
+\fIcount\fR is
+.QW \fB*\fR
+or is larger than the current cursor position,
 then the cursor is positioned at location 0 so that the next byte
 scanned will be the first byte in \fIstring\fR.  If \fIcount\fR
 is omitted then the cursor is moved back one byte.  Note that this
 type does not consume an argument.  For example,
 .RS
+.PP
 .CS
 \fBbinary scan\fR \ex01\ex02\ex03\ex04 c2XH* var1 var2
 .CE
+.PP
 will return \fB2\fR with \fB1 2\fR stored in \fIvar1\fR and \fB020304\fR
 stored in \fIvar2\fR.
 .RE
@@ -858,9 +1047,11 @@ by \fIcount\fR.  Note that position 0 refers to the first byte in
 \fIstring\fR, then the cursor is positioned after the last byte.  If
 \fIcount\fR is omitted, then an error will be generated.  For example,
 .RS
+.PP
 .CS
 \fBbinary scan\fR \ex01\ex02\ex03\ex04 c2@1H* var1 var2
 .CE
+.PP
 will return \fB2\fR with \fB1 2\fR stored in \fIvar1\fR and \fB020304\fR
 stored in \fIvar2\fR.
 .RE

doc/callback.n

@@ -0,0 +1,88 @@
+'\"
+'\" Copyright (c) 2018 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH callback n 0.3 TclOO "TclOO Commands"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+callback, mymethod \- generate callbacks to methods
+.SH SYNOPSIS
+.nf
+package require tcl::oo
+
+\fBcallback\fR \fImethodName\fR ?\fIarg ...\fR?
+\fBmymethod\fR \fImethodName\fR ?\fIarg ...\fR?
+.fi
+.BE
+.SH DESCRIPTION
+The \fBcallback\fR command,
+'\" Based on notes in the tcllib docs, we know the provenance of mymethod
+also called \fBmymethod\fR for compatibility with the ooutil and snit packages
+of Tcllib,
+and which should only be used from within the context of a call to a method
+(i.e. inside a method, constructor or destructor body) is used to generate a
+script fragment that will invoke the method, \fImethodName\fR, on the current
+object (as reported by \fBself\fR) when executed. Any additional arguments
+provided will be provided as leading arguments to the callback. The resulting
+script fragment shall be a proper list.
+.PP
+Note that it is up to the caller to ensure that the current object is able to
+handle the call of \fImethodName\fR; this command does not check that.
+\fImethodName\fR may refer to any exported or unexported method, but may not
+refer to a private method as those can only be invoked directly from within
+methods. If there is no such method present at the point when the callback is
+invoked, the standard \fBunknown\fR method handler will be called.
+.SH EXAMPLE
+This is a simple echo server class. The \fBcallback\fR command is used in two
+places, to arrange for the incoming socket connections to be handled by the
+\fIAccept\fR method, and to arrange for the incoming bytes on those
+connections to be handled by the \fIReceive\fR method.
+.PP
+.CS
+oo::class create EchoServer {
+    variable server clients
+    constructor {port} {
+        set server [socket -server [\fBcallback\fR Accept] $port]
+        set clients {}
+    }
+    destructor {
+        chan close $server
+        foreach client [dict keys $clients] {
+            chan close $client
+        }
+    }
+
+    method Accept {channel clientAddress clientPort} {
+        dict set clients $channel [dict create \e
+                address $clientAddress port $clientPort]
+        chan event $channel readable [\fBcallback\fR Receive $channel]
+    }
+    method Receive {channel} {
+        if {[chan gets $channel line] >= 0} {
+            my echo $channel $line
+        } else {
+            chan close $channel
+            dict unset clients $channel
+        }
+    }
+
+    method echo {channel line} {
+        dict with clients $channel {
+            chan puts $channel \e
+                    [format {[%s:%d] %s} $address $port $line]
+        }
+    }
+}
+.CE
+.SH "SEE ALSO"
+chan(n), fileevent(n), my(n), self(n), socket(n), trace(n)
+.SH KEYWORDS
+callback, object
+.\" Local Variables:
+.\" mode: nroff
+.\" fill-column: 78
+.\" End:

doc/catch.n

@@ -56,9 +56,7 @@ When the return code from evaluation of \fIscript\fR is
 \fBTCL_ERROR\fR, four additional entries are defined in the dictionary
 of return options stored in \fIoptionsVarName\fR: \fB\-errorinfo\fR,
 \fB\-errorcode\fR, \fB\-errorline\fR, and
-.VS 8.6
 \fB\-errorstack\fR.
-.VE 8.6
 The value of the \fB\-errorinfo\fR entry is a formatted stack trace containing
 more information about the context in which the error happened.  The formatted
 stack trace is meant to be read by a person.  The value of the
@@ -67,7 +65,6 @@ list.  The \fB\-errorcode\fR value is meant to be further processed by
 programs, and may not be particularly readable by people.  The value of the
 \fB\-errorline\fR entry is an integer indicating which line of \fIscript\fR
 was being evaluated when the error occurred.
-.VS 8.6
 The value of the \fB\-errorstack\fR entry is an
 even-sized list made of token-parameter pairs accumulated while
 unwinding the stack. The token may be
@@ -87,14 +84,11 @@ the static text of the calling sites, and
 .IP [3]
 it is coarser-grained, with only one element per stack frame (like procs; no
 separate elements for \fBforeach\fR constructs for example).
-.VE 8.6
 .PP
 The values of the \fB\-errorinfo\fR and \fB\-errorcode\fR entries of
 the most recent error are also available as values of the global
 variables \fB::errorInfo\fR and \fB::errorCode\fR respectively.
-.VS 8.6
 The value of the \fB\-errorstack\fR entry surfaces as \fBinfo errorstack\fR.
-.VE 8.6
 .PP
 Tcl packages may provide commands that set other entries in the
 dictionary of return options, and the \fBreturn\fR command may be

doc/cd.n

@@ -22,7 +22,7 @@ home directory (as specified in the HOME environment variable) if
 Returns an empty string.
 Note that the current working directory is a per-process resource; the
 \fBcd\fR command changes the working directory for all interpreters
-and (in a threaded environment) all threads.
+and all threads.
 .SH EXAMPLES
 .PP
 Change to the home directory of the user \fBfred\fR:
@@ -41,3 +41,7 @@ current one:
 filename(n), glob(n), pwd(n)
 .SH KEYWORDS
 working directory
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:

doc/class.n

@@ -12,7 +12,7 @@
 oo::class \- class of all classes
 .SH SYNOPSIS
 .nf
-package require TclOO
+package require tcl::oo
 
 \fBoo::class\fI method \fR?\fIarg ...\fR?
 .fi

doc/classvariable.n

@@ -0,0 +1,78 @@
+'\"
+'\" Copyright (c) 2011-2015 Andreas Kupries
+'\" Copyright (c) 2018 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH classvariable n 0.3 TclOO "TclOO Commands"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+classvariable \- create link from local variable to variable in class
+.SH SYNOPSIS
+.nf
+package require tcl::oo
+
+\fBclassvariable\fR \fIvariableName\fR ?\fI...\fR?
+.fi
+.BE
+.SH DESCRIPTION
+The \fBclassvariable\fR command is available within methods. It takes a series
+of one or more variable names and makes them available in the method's scope;
+those variable names must not be qualified and must not refer to array
+elements. The originating scope for the variables is the namespace of the
+class that the method was defined by. In other words, the referenced variables
+are shared between all instances of that class.
+.PP
+Note: This command is equivalent to the command \fBtypevariable\fR provided by
+the snit package in tcllib for approximately the same purpose. If used in a
+method defined directly on a class instance (e.g., through the
+\fBoo::objdefine\fR \fBmethod\fR definition) this is very much like just
+using:
+.PP
+.CS
+namespace upvar [namespace current] $var $var
+.CE
+.PP
+for each variable listed to \fBclassvariable\fR.
+.SH EXAMPLE
+This class counts how many instances of it have been made.
+.PP
+.CS
+oo::class create Counted {
+    initialise {
+        variable count 0
+    }
+
+    variable number
+    constructor {} {
+        \fBclassvariable\fR count
+        set number [incr count]
+    }
+
+    method report {} {
+        \fBclassvariable\fR count
+        puts "This is instance $number of $count"
+    }
+}
+
+set a [Counted new]
+set b [Counted new]
+$a report
+        \fI\(-> This is instance 1 of 2\fR
+set c [Counted new]
+$b report
+        \fI\(-> This is instance 2 of 3\fR
+$c report
+        \fI\(-> This is instance 3 of 3\fR
+.CE
+.SH "SEE ALSO"
+global(n), namespace(n), oo::class(n), oo::define(n), upvar(n), variable(n)
+.SH KEYWORDS
+class, class variable, variable
+.\" Local Variables:
+.\" mode: nroff
+.\" fill-column: 78
+.\" End:

doc/clock.n

@@ -8,7 +8,7 @@
 .SH NAME
 clock \- Obtain and manipulate dates and times
 .SH "SYNOPSIS"
-package require \fBTcl 8.5\fR
+package require \fBTcl 8.5-\fR
 .sp
 \fBclock add\fR \fItimeVal\fR ?\fIcount unit...\fR? ?\fI\-option value\fR?
 .sp
@@ -89,10 +89,9 @@ have 59 or 61 seconds.
 .TP
 \fIunit\fR
 One of the words, \fBseconds\fR, \fBminutes\fR, \fBhours\fR,
-\fBdays\fR, \fBweeks\fR, \fBmonths\fR, or \fByears\fR, or
-any unique prefix of such a word. Used in conjunction with \fIcount\fR
-to identify an interval of time, for example, \fI3 seconds\fR or
-\fI1 year\fR.
+\fBdays\fR, \fBweekdays\fR, \fBweeks\fR, \fBmonths\fR, or \fByears\fR.
+Used in conjunction with \fIcount\fR to identify an interval of time,
+for example, \fI3 seconds\fR or \fI1 year\fR.
 .SS "OPTIONS"
 .TP
 \fB\-base\fR time
@@ -175,8 +174,7 @@ given as its first argument.  The remaining arguments (other than the
 possible \fB\-timezone\fR, \fB\-locale\fR and \fB\-gmt\fR options)
 are integers and keywords in alternation, where the keywords are chosen
 from \fBseconds\fR, \fBminutes\fR, \fBhours\fR,
-\fBdays\fR, \fBweeks\fR, \fBmonths\fR, or \fByears\fR, or
-any unique prefix of such a word.
+\fBdays\fR, \fBweekdays\fR, \fBweeks\fR, \fBmonths\fR, or \fByears\fR.
 .PP
 Addition of seconds, minutes and hours is fairly straightforward;
 the given time increment (times sixty for minutes, or 3600 for hours)
@@ -213,7 +211,8 @@ the given time to a calendar day and time of day in the appropriate
 time zone and locale.  The requisite number of days (weeks are converted
 to days by multiplying by seven) is added to the calendar day, and
 the date and time are then converted back to a count of seconds from
-the epoch time.
+the epoch time.  The \fBweekdays\fR keyword is similar to \fBdays\fR,
+with the only difference that weekends - Saturdays and Sundays - are skipped.
 .PP
 Adding and subtracting a given number of days across the point that
 the time changes at the start or end of summer time (Daylight Saving Time)
@@ -887,41 +886,47 @@ The \fIinputString\fR argument consists of zero or more specifications of the
 following form:
 .TP
 \fItime\fR
-A time of day, which is of the form: \fBhh?:mm?:ss?? ?meridian? ?zone?\fR
-or \fBhhmm ?meridian? ?zone?\fR
-If no meridian is specified, \fBhh\fR is interpreted on
+.
+A time of day, which is of the form:
+.QW "\fIhh\fR?\fB:\fImm\fR?\fB:\fIss\fR?? ?\fImeridian\fR? ?\fIzone\fR?"
+or
+.QW "\fBhhmm \fR?\fBmeridian\fR? ?\fBzone\fR?" .
+If no \fImeridian\fR is specified, \fIhh\fR is interpreted on
 a 24-hour clock.
 .TP
 \fIdate\fR
+.
 A specific month and day with optional year.  The
 acceptable formats are
-.QW "\fBmm/dd\fR?\fB/yy\fR?" ,
-.QW "\fBmonthname dd\fR?\fB, yy\fR?" ,
-.QW "\fBday, dd monthname \fR?\fByy\fR?" ,
-.QW "\fBdd monthname yy\fR" ,
-.QW "?\fBCC\fR?\fByymmdd\fR" ,
+.QW "\fImm\fB/\fIdd\fR?\fB/\fIyy\fR?" ,
+.QW "\fImonthname dd\fR?\fB, \fIyy\fR?" ,
+.QW "\fIday\fB, \fIdd monthname \fR?\fIyy\fR?" ,
+.QW "\fIdd monthname yy\fR" ,
+.QW "?\fICC\fR?\fIyymmdd\fR" ,
 and
-.QW "\fBdd-monthname-\fR?\fBCC\fR?\fByy\fR" .
+.QW "\fIdd\fB-\fImonthname\fB-\fR?\fICC\fR?\fIyy\fR" .
 The default year is the current year.  If the year is less
 than 100, we treat the years 00-68 as 2000-2068 and the years 69-99
 as 1969-1999.  Not all platforms can represent the years 38-70, so
 an error may result if these years are used.
 .TP
 \fIISO 8601 point-in-time\fR
+.
 An ISO 8601 point-in-time specification, such as
-.QW \fICCyymmdd\fBT\fIhhmmss\fR,
+.QW "\fICCyymmdd\fBT\fIhhmmss\fR",
 where \fBT\fR is the literal
 .QW T ,
 .QW "\fICCyymmdd hhmmss\fR" ,
-.QW \fICCyymmdd\fBT\fIhh:mm:ss\fR ,
+.QW "\fICCyymmdd\fBT\fIhh:mm:ss\fR" ,
 or
-.QW \fICCyy-mm-dd\fBT\fIhh:mm:ss\fR.
+.QW "\fICCyy-mm-dd\fBT\fIhh\fB:\fImm\fB:\fIss\fR".
 Note that only these four formats are accepted.
 The command does \fInot\fR accept the full range of point-in-time
 specifications specified in ISO8601.  Other formats can be recognized by
 giving an explicit \fB\-format\fR option to the \fBclock scan\fR command.
 .TP
 \fIrelative time\fR
+.
 A specification relative to the current time.  The format is \fBnumber
 unit\fR. Acceptable units are \fByear\fR, \fBfortnight\fR,
 \fBmonth\fR, \fBweek\fR, \fBday\fR,