Use more TCL_AUTO_LENGTH, when appropriate

Add TIP #494-compatible definitions of TCL_IO_FAILURE/TCL_AUTO_LENGTH, and use it in some appropriate places.

.fossil-settings/binary-glob

@@ -4,6 +4,7 @@ compat/zlib/win64/zdll.lib
 compat/zlib/win64/zlib1.dll
 compat/zlib/win64/libz.dll.a
 compat/zlib/zlib.3.pdf
+tools/empty.zip
 *.bmp
 *.gif
 *.png

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,3 @@
+Important Note
+==========
+Please do not file issues with Tcl on Github. They are unlikely to be noticed in a timely fashion. Tcl issues are hosted in the [tcl fossil repository on core.tcl.tk](https://core.tcl.tk/tcl/tktnew); please post them there.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,3 @@
+Important Note
+==========
+Please do not file pull requests with Tcl on Github. They are unlikely to be noticed in a timely fashion. Tcl issues (including patches) are hosted in the [tcl fossil repository on core.tcl.tk](https://core.tcl.tk/tcl/tktnew); please post them there.

.project

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

README

@@ -1,5 +1,5 @@
 README:  Tcl
-    This is the Tcl 8.7a2 source distribution.
+    This is the Tcl 9.0a0 source distribution.
 	http://sourceforge.net/projects/tcl/files/Tcl/
     You can get any source release of Tcl from the URL above.
 
@@ -49,7 +49,7 @@ and selling it either in whole or in part.  See the file
 
 Extensive documentation is available at our website.
 The home page for this release, including new features, is
-	http://www.tcl.tk/software/tcltk/8.7.html
+	http://www.tcl.tk/software/tcltk/9.0.html
 
 Detailed release notes can be found at the file distributions page
 by clicking on the relevant version.
@@ -61,9 +61,9 @@ Information about Tcl itself can be found at
 There have been many Tcl books on the market.  Many are mentioned in the Wiki:
 	http://wiki.tcl.tk/_/ref?N=25206
 
-To view the complete set of reference manual entries for Tcl 8.7 online,
+To view the complete set of reference manual entries for Tcl 9.0 online,
 visit the URL:
-	http://www.tcl.tk/man/tcl8.7/
+	http://www.tcl.tk/man/tcl9.0/
 
 2a. Unix Documentation
 ----------------------

changes

@@ -8879,3 +8879,8 @@ in this changeset (new minor version) rather than bug fixes:
 2017-09-02 (bug)[0e4d88] replace command, delete trace kills namespace (porter)
 
 --- Released 8.7a1, September 8, 2017 --- http://core.tcl.tk/tcl/ for details
+
+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

compat/opendir.c

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

compat/waitpid.c

@@ -100,7 +100,7 @@ waitpid(
 	} else {
 	    prevPtr->nextPtr = waitPtr->nextPtr;
 	}
-	ckfree(waitPtr);
+	Tcl_Free(waitPtr);
 	return result;
     }
 
@@ -156,7 +156,7 @@ waitpid(
 		goto waitAgain;
 	    }
 	}
-	waitPtr = (WaitInfo *) ckalloc(sizeof(WaitInfo));
+	waitPtr = (WaitInfo *) Tcl_Alloc(sizeof(WaitInfo));
 	waitPtr->pid = result;
 	waitPtr->status = status;
 	waitPtr->nextPtr = deadList;

compat/zlib/contrib/minizip/minizip.c

@@ -12,7 +12,6 @@
          Copyright (C) 2009-2010 Mathias Svensson ( http://result42.com )
 */
 
-
 #if (!defined(_WIN32)) && (!defined(WIN32)) && (!defined(__APPLE__))
         #ifndef __USE_FILE_OFFSET64
                 #define __USE_FILE_OFFSET64
@@ -39,8 +38,7 @@
 #define FSEEKO_FUNC(stream, offset, origin) fseeko64(stream, offset, origin)
 #endif
 
-
-
+#include "tinydir.h"
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
@@ -172,6 +170,7 @@ void do_banner()
 void do_help()
 {
     printf("Usage : minizip [-o] [-a] [-0 to -9] [-p password] [-j] file.zip [files_to_add]\n\n" \
+           "  -r  Scan directories recursively\n" \
            "  -o  Overwrite existing file.zip\n" \
            "  -a  Append to existing file.zip\n" \
            "  -0  Store only\n" \
@@ -243,12 +242,153 @@ int isLargeFile(const char* filename)
  return largeFile;
 }
 
+void addFileToZip(zipFile zf, const char *filenameinzip, const char *password, int opt_exclude_path,int opt_compress_level) {
+    FILE * fin;
+    int size_read;
+    const char *savefilenameinzip;
+    zip_fileinfo zi;
+    unsigned long crcFile=0;
+    int zip64 = 0;
+    int err=0;
+    int size_buf=WRITEBUFFERSIZE;
+    unsigned char buf[WRITEBUFFERSIZE];
+    zi.tmz_date.tm_sec = zi.tmz_date.tm_min = zi.tmz_date.tm_hour =
+    zi.tmz_date.tm_mday = zi.tmz_date.tm_mon = zi.tmz_date.tm_year = 0;
+    zi.dosDate = 0;
+    zi.internal_fa = 0;
+    zi.external_fa = 0;
+    filetime(filenameinzip,&zi.tmz_date,&zi.dosDate);
+
+/*
+    err = zipOpenNewFileInZip(zf,filenameinzip,&zi,
+                     NULL,0,NULL,0,NULL / * comment * /,
+                     (opt_compress_level != 0) ? Z_DEFLATED : 0,
+                     opt_compress_level);
+*/
+    if ((password != NULL) && (err==ZIP_OK))
+        err = getFileCrc(filenameinzip,buf,size_buf,&crcFile);
+
+    zip64 = isLargeFile(filenameinzip);
+
+   /* The path name saved, should not include a leading slash. */
+   /*if it did, windows/xp and dynazip couldn't read the zip file. */
+     savefilenameinzip = filenameinzip;
+     while( savefilenameinzip[0] == '\\' || savefilenameinzip[0] == '/' )
+     {
+         savefilenameinzip++;
+     }
+
+     /*should the zip file contain any path at all?*/
+     if( opt_exclude_path )
+     {
+         const char *tmpptr;
+         const char *lastslash = 0;
+         for( tmpptr = savefilenameinzip; *tmpptr; tmpptr++)
+         {
+             if( *tmpptr == '\\' || *tmpptr == '/')
+             {
+                 lastslash = tmpptr;
+             }
+         }
+         if( lastslash != NULL )
+         {
+             savefilenameinzip = lastslash+1; // base filename follows last slash.
+         }
+     }
+
+     /**/
+    err = zipOpenNewFileInZip3_64(zf,savefilenameinzip,&zi,
+                     NULL,0,NULL,0,NULL /* comment*/,
+                     (opt_compress_level != 0) ? Z_DEFLATED : 0,
+                     opt_compress_level,0,
+                     /* -MAX_WBITS, DEF_MEM_LEVEL, Z_DEFAULT_STRATEGY, */
+                     -MAX_WBITS, DEF_MEM_LEVEL, Z_DEFAULT_STRATEGY,
+                     password,crcFile, zip64);
+
+    if (err != ZIP_OK)
+        printf("error in opening %s in zipfile\n",filenameinzip);
+    else
+    {
+        fin = FOPEN_FUNC(filenameinzip,"rb");
+        if (fin==NULL)
+        {
+            err=ZIP_ERRNO;
+            printf("error in opening %s for reading\n",filenameinzip);
+        }
+    }
+
+    if (err == ZIP_OK)
+        do
+        {
+            err = ZIP_OK;
+            size_read = (int)fread(buf,1,size_buf,fin);
+            if (size_read < size_buf)
+                if (feof(fin)==0)
+            {
+                printf("error in reading %s\n",filenameinzip);
+                err = ZIP_ERRNO;
+            }
+
+            if (size_read>0)
+            {
+                err = zipWriteInFileInZip (zf,buf,size_read);
+                if (err<0)
+                {
+                    printf("error in writing %s in the zipfile\n",
+                                     filenameinzip);
+                }
+
+            }
+        } while ((err == ZIP_OK) && (size_read>0));
+
+    if (fin)
+        fclose(fin);
+
+    if (err<0)
+        err=ZIP_ERRNO;
+    else
+    {
+        err = zipCloseFileInZip(zf);
+        if (err!=ZIP_OK)
+            printf("error in closing %s in the zipfile\n",
+                        filenameinzip);
+    }
+}
+
+
+void addPathToZip(zipFile zf, const char *filenameinzip, const char *password, int opt_exclude_path,int opt_compress_level) {
+    tinydir_dir dir;
+    int i;
+    char *newname[512];
+
+    tinydir_open_sorted(&dir, filenameinzip);
+
+    for (i = 0; i < dir.n_files; i++)
+    {
+        tinydir_file file;
+        tinydir_readfile_n(&dir, &file, i);
+        if(strcmp(file.name,".")==0) continue;
+        if(strcmp(file.name,"..")==0) continue;
+        sprintf(newname,"%s/%s",dir.path,file.name);
+        if (file.is_dir)
+        {
+            addPathToZip(zf,newname,password,opt_exclude_path,opt_compress_level);
+        } else {
+            addFileToZip(zf,newname,password,opt_exclude_path,opt_compress_level);
+        }
+    }
+
+    tinydir_close(&dir);
+}
+
+
 int main(argc,argv)
     int argc;
     char *argv[];
 {
     int i;
-    int opt_overwrite=0;
+    int opt_recursive=0;
+    int opt_overwrite=1;
     int opt_compress_level=Z_DEFAULT_COMPRESSION;
     int opt_exclude_path=0;
     int zipfilenamearg = 0;
@@ -285,7 +425,8 @@ int main(argc,argv)
                         opt_compress_level = c-'0';
                     if ((c=='j') || (c=='J'))
                         opt_exclude_path = 1;
-
+                    if ((c=='r') || (c=='R'))
+                        opt_recursive = 1;
                     if (((c=='p') || (c=='P')) && (i+1<argc))
                     {
                         password=argv[i+1];
@@ -392,117 +533,14 @@ int main(argc,argv)
                   ((argv[i][1]=='o') || (argv[i][1]=='O') ||
                    (argv[i][1]=='a') || (argv[i][1]=='A') ||
                    (argv[i][1]=='p') || (argv[i][1]=='P') ||
+                   (argv[i][1]=='r') || (argv[i][1]=='R') ||
                    ((argv[i][1]>='0') || (argv[i][1]<='9'))) &&
                   (strlen(argv[i]) == 2)))
             {
-                FILE * fin;
-                int size_read;
-                const char* filenameinzip = argv[i];
-                const char *savefilenameinzip;
-                zip_fileinfo zi;
-                unsigned long crcFile=0;
-                int zip64 = 0;
-
-                zi.tmz_date.tm_sec = zi.tmz_date.tm_min = zi.tmz_date.tm_hour =
-                zi.tmz_date.tm_mday = zi.tmz_date.tm_mon = zi.tmz_date.tm_year = 0;
-                zi.dosDate = 0;
-                zi.internal_fa = 0;
-                zi.external_fa = 0;
-                filetime(filenameinzip,&zi.tmz_date,&zi.dosDate);
-
-/*
-                err = zipOpenNewFileInZip(zf,filenameinzip,&zi,
-                                 NULL,0,NULL,0,NULL / * comment * /,
-                                 (opt_compress_level != 0) ? Z_DEFLATED : 0,
-                                 opt_compress_level);
-*/
-                if ((password != NULL) && (err==ZIP_OK))
-                    err = getFileCrc(filenameinzip,buf,size_buf,&crcFile);
-
-                zip64 = isLargeFile(filenameinzip);
-
-                                                         /* The path name saved, should not include a leading slash. */
-               /*if it did, windows/xp and dynazip couldn't read the zip file. */
-                 savefilenameinzip = filenameinzip;
-                 while( savefilenameinzip[0] == '\\' || savefilenameinzip[0] == '/' )
-                 {
-                     savefilenameinzip++;
-                 }
-
-                 /*should the zip file contain any path at all?*/
-                 if( opt_exclude_path )
-                 {
-                     const char *tmpptr;
-                     const char *lastslash = 0;
-                     for( tmpptr = savefilenameinzip; *tmpptr; tmpptr++)
-                     {
-                         if( *tmpptr == '\\' || *tmpptr == '/')
-                         {
-                             lastslash = tmpptr;
-                         }
-                     }
-                     if( lastslash != NULL )
-                     {
-                         savefilenameinzip = lastslash+1; // base filename follows last slash.
-                     }
-                 }
-
-                 /**/
-                err = zipOpenNewFileInZip3_64(zf,savefilenameinzip,&zi,
-                                 NULL,0,NULL,0,NULL /* comment*/,
-                                 (opt_compress_level != 0) ? Z_DEFLATED : 0,
-                                 opt_compress_level,0,
-                                 /* -MAX_WBITS, DEF_MEM_LEVEL, Z_DEFAULT_STRATEGY, */
-                                 -MAX_WBITS, DEF_MEM_LEVEL, Z_DEFAULT_STRATEGY,
-                                 password,crcFile, zip64);
-
-                if (err != ZIP_OK)
-                    printf("error in opening %s in zipfile\n",filenameinzip);
-                else
-                {
-                    fin = FOPEN_FUNC(filenameinzip,"rb");
-                    if (fin==NULL)
-                    {
-                        err=ZIP_ERRNO;
-                        printf("error in opening %s for reading\n",filenameinzip);
-                    }
-                }
-
-                if (err == ZIP_OK)
-                    do
-                    {
-                        err = ZIP_OK;
-                        size_read = (int)fread(buf,1,size_buf,fin);
-                        if (size_read < size_buf)
-                            if (feof(fin)==0)
-                        {
-                            printf("error in reading %s\n",filenameinzip);
-                            err = ZIP_ERRNO;
-                        }
-
-                        if (size_read>0)
-                        {
-                            err = zipWriteInFileInZip (zf,buf,size_read);
-                            if (err<0)
-                            {
-                                printf("error in writing %s in the zipfile\n",
-                                                 filenameinzip);
-                            }
-
-                        }
-                    } while ((err == ZIP_OK) && (size_read>0));
-
-                if (fin)
-                    fclose(fin);
-
-                if (err<0)
-                    err=ZIP_ERRNO;
-                else
-                {
-                    err = zipCloseFileInZip(zf);
-                    if (err!=ZIP_OK)
-                        printf("error in closing %s in the zipfile\n",
-                                    filenameinzip);
+                if(opt_recursive) {
+                    addPathToZip(zf,argv[i],password,opt_exclude_path,opt_compress_level);
+                } else {
+                    addFileToZip(zf,argv[i],password,opt_exclude_path,opt_compress_level);
                 }
             }
         }

compat/zlib/contrib/minizip/tinydir.h

@@ -0,0 +1,816 @@
+/*
+Copyright (c) 2013-2017, tinydir authors:
+- Cong Xu
+- Lautis Sun
+- Baudouin Feildel
+- Andargor <andargor@yahoo.com>
+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.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "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 COPYRIGHT OWNER OR CONTRIBUTORS 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.
+*/
+#ifndef TINYDIR_H
+#define TINYDIR_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#if ((defined _UNICODE) && !(defined UNICODE))
+#define UNICODE
+#endif
+
+#if ((defined UNICODE) && !(defined _UNICODE))
+#define _UNICODE
+#endif
+
+#include <errno.h>
+#include <stdlib.h>
+#include <string.h>
+#ifdef _MSC_VER
+# define WIN32_LEAN_AND_MEAN
+# include <windows.h>
+# include <tchar.h>
+# pragma warning(push)
+# pragma warning (disable : 4996)
+#else
+# include <dirent.h>
+# include <libgen.h>
+# include <sys/stat.h>
+# include <stddef.h>
+#endif
+#ifdef __MINGW32__
+# include <tchar.h>
+#endif
+
+
+/* types */
+
+/* Windows UNICODE wide character support */
+#if defined _MSC_VER || defined __MINGW32__
+# define _tinydir_char_t TCHAR
+# define TINYDIR_STRING(s) _TEXT(s)
+# define _tinydir_strlen _tcslen
+# define _tinydir_strcpy _tcscpy
+# define _tinydir_strcat _tcscat
+# define _tinydir_strcmp _tcscmp
+# define _tinydir_strrchr _tcsrchr
+# define _tinydir_strncmp _tcsncmp
+#else
+# define _tinydir_char_t char
+# define TINYDIR_STRING(s) s
+# define _tinydir_strlen strlen
+# define _tinydir_strcpy strcpy
+# define _tinydir_strcat strcat
+# define _tinydir_strcmp strcmp
+# define _tinydir_strrchr strrchr
+# define _tinydir_strncmp strncmp
+#endif
+
+#if (defined _MSC_VER || defined __MINGW32__)
+# include <windows.h>
+# define _TINYDIR_PATH_MAX MAX_PATH
+#elif defined  __linux__
+# include <limits.h>
+# define _TINYDIR_PATH_MAX PATH_MAX
+#elif defined(__unix__) || (defined(__APPLE__) && defined(__MACH__))
+# include <sys/param.h>
+# if defined(BSD)
+#  include <limits.h>
+#  define _TINYDIR_PATH_MAX PATH_MAX
+# endif
+#endif
+
+#ifndef _TINYDIR_PATH_MAX
+#define _TINYDIR_PATH_MAX 4096
+#endif
+
+#ifdef _MSC_VER
+/* extra chars for the "\\*" mask */
+# define _TINYDIR_PATH_EXTRA 2
+#else
+# define _TINYDIR_PATH_EXTRA 0
+#endif
+
+#define _TINYDIR_FILENAME_MAX 256
+
+#if (defined _MSC_VER || defined __MINGW32__)
+#define _TINYDIR_DRIVE_MAX 3
+#endif
+
+#ifdef _MSC_VER
+# define _TINYDIR_FUNC static __inline
+#elif !defined __STDC_VERSION__ || __STDC_VERSION__ < 199901L
+# define _TINYDIR_FUNC static __inline__
+#else
+# define _TINYDIR_FUNC static inline
+#endif
+
+/* readdir_r usage; define TINYDIR_USE_READDIR_R to use it (if supported) */
+#ifdef TINYDIR_USE_READDIR_R
+
+/* readdir_r is a POSIX-only function, and may not be available under various
+ * environments/settings, e.g. MinGW. Use readdir fallback */
+#if _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _BSD_SOURCE || _SVID_SOURCE ||\
+	_POSIX_SOURCE
+# define _TINYDIR_HAS_READDIR_R
+#endif
+#if _POSIX_C_SOURCE >= 200112L
+# define _TINYDIR_HAS_FPATHCONF
+# include <unistd.h>
+#endif
+#if _BSD_SOURCE || _SVID_SOURCE || \
+	(_POSIX_C_SOURCE >= 200809L || _XOPEN_SOURCE >= 700)
+# define _TINYDIR_HAS_DIRFD
+# include <sys/types.h>
+#endif
+#if defined _TINYDIR_HAS_FPATHCONF && defined _TINYDIR_HAS_DIRFD &&\
+	defined _PC_NAME_MAX
+# define _TINYDIR_USE_FPATHCONF
+#endif
+#if defined __MINGW32__ || !defined _TINYDIR_HAS_READDIR_R ||\
+	!(defined _TINYDIR_USE_FPATHCONF || defined NAME_MAX)
+# define _TINYDIR_USE_READDIR
+#endif
+
+/* Use readdir by default */
+#else
+# define _TINYDIR_USE_READDIR
+#endif
+
+/* MINGW32 has two versions of dirent, ASCII and UNICODE*/
+#ifndef _MSC_VER
+#if (defined __MINGW32__) && (defined _UNICODE)
+#define _TINYDIR_DIR _WDIR
+#define _tinydir_dirent _wdirent
+#define _tinydir_opendir _wopendir
+#define _tinydir_readdir _wreaddir
+#define _tinydir_closedir _wclosedir
+#else
+#define _TINYDIR_DIR DIR
+#define _tinydir_dirent dirent
+#define _tinydir_opendir opendir
+#define _tinydir_readdir readdir
+#define _tinydir_closedir closedir
+#endif
+#endif
+
+/* Allow user to use a custom allocator by defining _TINYDIR_MALLOC and _TINYDIR_FREE. */
+#if    defined(_TINYDIR_MALLOC) &&  defined(_TINYDIR_FREE)
+#elif !defined(_TINYDIR_MALLOC) && !defined(_TINYDIR_FREE)
+#else
+#error "Either define both alloc and free or none of them!"
+#endif
+
+#if !defined(_TINYDIR_MALLOC)
+	#define _TINYDIR_MALLOC(_size) malloc(_size)
+	#define _TINYDIR_FREE(_ptr)    free(_ptr)
+#endif /* !defined(_TINYDIR_MALLOC) */
+
+typedef struct tinydir_file
+{
+	_tinydir_char_t path[_TINYDIR_PATH_MAX];
+	_tinydir_char_t name[_TINYDIR_FILENAME_MAX];
+	_tinydir_char_t *extension;
+	int is_dir;
+	int is_reg;
+
+#ifndef _MSC_VER
+#ifdef __MINGW32__
+	struct _stat _s;
+#else
+	struct stat _s;
+#endif
+#endif
+} tinydir_file;
+
+typedef struct tinydir_dir
+{
+	_tinydir_char_t path[_TINYDIR_PATH_MAX];
+	int has_next;
+	size_t n_files;
+
+	tinydir_file *_files;
+#ifdef _MSC_VER
+	HANDLE _h;
+	WIN32_FIND_DATA _f;
+#else
+	_TINYDIR_DIR *_d;
+	struct _tinydir_dirent *_e;
+#ifndef _TINYDIR_USE_READDIR
+	struct _tinydir_dirent *_ep;
+#endif
+#endif
+} tinydir_dir;
+
+
+/* declarations */
+
+_TINYDIR_FUNC
+int tinydir_open(tinydir_dir *dir, const _tinydir_char_t *path);
+_TINYDIR_FUNC
+int tinydir_open_sorted(tinydir_dir *dir, const _tinydir_char_t *path);
+_TINYDIR_FUNC
+void tinydir_close(tinydir_dir *dir);
+
+_TINYDIR_FUNC
+int tinydir_next(tinydir_dir *dir);
+_TINYDIR_FUNC
+int tinydir_readfile(const tinydir_dir *dir, tinydir_file *file);
+_TINYDIR_FUNC
+int tinydir_readfile_n(const tinydir_dir *dir, tinydir_file *file, size_t i);
+_TINYDIR_FUNC
+int tinydir_open_subdir_n(tinydir_dir *dir, size_t i);
+
+_TINYDIR_FUNC
+int tinydir_file_open(tinydir_file *file, const _tinydir_char_t *path);
+_TINYDIR_FUNC
+void _tinydir_get_ext(tinydir_file *file);
+_TINYDIR_FUNC
+int _tinydir_file_cmp(const void *a, const void *b);
+#ifndef _MSC_VER
+#ifndef _TINYDIR_USE_READDIR
+_TINYDIR_FUNC
+size_t _tinydir_dirent_buf_size(_TINYDIR_DIR *dirp);
+#endif
+#endif
+
+
+/* definitions*/
+
+_TINYDIR_FUNC
+int tinydir_open(tinydir_dir *dir, const _tinydir_char_t *path)
+{
+#ifndef _MSC_VER
+#ifndef _TINYDIR_USE_READDIR
+	int error;
+	int size;	/* using int size */
+#endif
+#else
+	_tinydir_char_t path_buf[_TINYDIR_PATH_MAX];
+#endif
+	_tinydir_char_t *pathp;
+
+	if (dir == NULL || path == NULL || _tinydir_strlen(path) == 0)
+	{
+		errno = EINVAL;
+		return -1;
+	}
+	if (_tinydir_strlen(path) + _TINYDIR_PATH_EXTRA >= _TINYDIR_PATH_MAX)
+	{
+		errno = ENAMETOOLONG;
+		return -1;
+	}
+
+	/* initialise dir */
+	dir->_files = NULL;
+#ifdef _MSC_VER
+	dir->_h = INVALID_HANDLE_VALUE;
+#else
+	dir->_d = NULL;
+#ifndef _TINYDIR_USE_READDIR
+	dir->_ep = NULL;
+#endif
+#endif
+	tinydir_close(dir);
+
+	_tinydir_strcpy(dir->path, path);
+	/* Remove trailing slashes */
+	pathp = &dir->path[_tinydir_strlen(dir->path) - 1];
+	while (pathp != dir->path && (*pathp == TINYDIR_STRING('\\') || *pathp == TINYDIR_STRING('/')))
+	{
+		*pathp = TINYDIR_STRING('\0');
+		pathp++;
+	}
+#ifdef _MSC_VER
+	_tinydir_strcpy(path_buf, dir->path);
+	_tinydir_strcat(path_buf, TINYDIR_STRING("\\*"));
+#if (defined WINAPI_FAMILY) && (WINAPI_FAMILY != WINAPI_FAMILY_DESKTOP_APP)
+	dir->_h = FindFirstFileEx(path_buf, FindExInfoStandard, &dir->_f, FindExSearchNameMatch, NULL, 0);
+#else
+	dir->_h = FindFirstFile(path_buf, &dir->_f);
+#endif
+	if (dir->_h == INVALID_HANDLE_VALUE)
+	{
+		errno = ENOENT;
+#else
+	dir->_d = _tinydir_opendir(path);
+	if (dir->_d == NULL)
+	{
+#endif
+		goto bail;
+	}
+
+	/* read first file */
+	dir->has_next = 1;
+#ifndef _MSC_VER
+#ifdef _TINYDIR_USE_READDIR
+	dir->_e = _tinydir_readdir(dir->_d);
+#else
+	/* allocate dirent buffer for readdir_r */
+	size = _tinydir_dirent_buf_size(dir->_d); /* conversion to int */
+	if (size == -1) return -1;
+	dir->_ep = (struct _tinydir_dirent*)_TINYDIR_MALLOC(size);
+	if (dir->_ep == NULL) return -1;
+
+	error = readdir_r(dir->_d, dir->_ep, &dir->_e);
+	if (error != 0) return -1;
+#endif
+	if (dir->_e == NULL)
+	{
+		dir->has_next = 0;
+	}
+#endif
+
+	return 0;
+
+bail:
+	tinydir_close(dir);
+	return -1;
+}
+
+_TINYDIR_FUNC
+int tinydir_open_sorted(tinydir_dir *dir, const _tinydir_char_t *path)
+{
+	/* Count the number of files first, to pre-allocate the files array */
+	size_t n_files = 0;
+	if (tinydir_open(dir, path) == -1)
+	{
+		return -1;
+	}
+	while (dir->has_next)
+	{
+		n_files++;
+		if (tinydir_next(dir) == -1)
+		{
+			goto bail;
+		}
+	}
+	tinydir_close(dir);
+
+	if (tinydir_open(dir, path) == -1)
+	{
+		return -1;
+	}
+
+	dir->n_files = 0;
+	dir->_files = (tinydir_file *)_TINYDIR_MALLOC(sizeof *dir->_files * n_files);
+	if (dir->_files == NULL)
+	{
+		goto bail;
+	}
+	while (dir->has_next)
+	{
+		tinydir_file *p_file;
+		dir->n_files++;
+
+		p_file = &dir->_files[dir->n_files - 1];
+		if (tinydir_readfile(dir, p_file) == -1)
+		{
+			goto bail;
+		}
+
+		if (tinydir_next(dir) == -1)
+		{
+			goto bail;
+		}
+
+		/* Just in case the number of files has changed between the first and
+		second reads, terminate without writing into unallocated memory */
+		if (dir->n_files == n_files)
+		{
+			break;
+		}
+	}
+
+	qsort(dir->_files, dir->n_files, sizeof(tinydir_file), _tinydir_file_cmp);
+
+	return 0;
+
+bail:
+	tinydir_close(dir);
+	return -1;
+}
+
+_TINYDIR_FUNC
+void tinydir_close(tinydir_dir *dir)
+{
+	if (dir == NULL)
+	{
+		return;
+	}
+
+	memset(dir->path, 0, sizeof(dir->path));
+	dir->has_next = 0;
+	dir->n_files = 0;
+	_TINYDIR_FREE(dir->_files);
+	dir->_files = NULL;
+#ifdef _MSC_VER
+	if (dir->_h != INVALID_HANDLE_VALUE)
+	{
+		FindClose(dir->_h);
+	}
+	dir->_h = INVALID_HANDLE_VALUE;
+#else
+	if (dir->_d)
+	{
+		_tinydir_closedir(dir->_d);
+	}
+	dir->_d = NULL;
+	dir->_e = NULL;
+#ifndef _TINYDIR_USE_READDIR
+	_TINYDIR_FREE(dir->_ep);
+	dir->_ep = NULL;
+#endif
+#endif
+}
+
+_TINYDIR_FUNC
+int tinydir_next(tinydir_dir *dir)
+{
+	if (dir == NULL)
+	{
+		errno = EINVAL;
+		return -1;
+	}
+	if (!dir->has_next)
+	{
+		errno = ENOENT;
+		return -1;
+	}
+
+#ifdef _MSC_VER
+	if (FindNextFile(dir->_h, &dir->_f) == 0)
+#else
+#ifdef _TINYDIR_USE_READDIR
+	dir->_e = _tinydir_readdir(dir->_d);
+#else
+	if (dir->_ep == NULL)
+	{
+		return -1;
+	}
+	if (readdir_r(dir->_d, dir->_ep, &dir->_e) != 0)
+	{
+		return -1;
+	}
+#endif
+	if (dir->_e == NULL)
+#endif
+	{
+		dir->has_next = 0;
+#ifdef _MSC_VER
+		if (GetLastError() != ERROR_SUCCESS &&
+			GetLastError() != ERROR_NO_MORE_FILES)
+		{
+			tinydir_close(dir);
+			errno = EIO;
+			return -1;
+		}
+#endif
+	}
+
+	return 0;
+}
+
+_TINYDIR_FUNC
+int tinydir_readfile(const tinydir_dir *dir, tinydir_file *file)
+{
+	if (dir == NULL || file == NULL)
+	{
+		errno = EINVAL;
+		return -1;
+	}
+#ifdef _MSC_VER
+	if (dir->_h == INVALID_HANDLE_VALUE)
+#else
+	if (dir->_e == NULL)
+#endif
+	{
+		errno = ENOENT;
+		return -1;
+	}
+	if (_tinydir_strlen(dir->path) +
+		_tinydir_strlen(
+#ifdef _MSC_VER
+			dir->_f.cFileName
+#else
+			dir->_e->d_name
+#endif
+		) + 1 + _TINYDIR_PATH_EXTRA >=
+		_TINYDIR_PATH_MAX)
+	{
+		/* the path for the file will be too long */
+		errno = ENAMETOOLONG;
+		return -1;
+	}
+	if (_tinydir_strlen(
+#ifdef _MSC_VER
+			dir->_f.cFileName
+#else
+			dir->_e->d_name
+#endif
+		) >= _TINYDIR_FILENAME_MAX)
+	{
+		errno = ENAMETOOLONG;
+		return -1;
+	}
+
+	_tinydir_strcpy(file->path, dir->path);
+	_tinydir_strcat(file->path, TINYDIR_STRING("/"));
+	_tinydir_strcpy(file->name,
+#ifdef _MSC_VER
+		dir->_f.cFileName
+#else
+		dir->_e->d_name
+#endif
+	);
+	_tinydir_strcat(file->path, file->name);
+#ifndef _MSC_VER
+#ifdef __MINGW32__
+	if (_tstat(
+#else
+	if (stat(
+#endif
+		file->path, &file->_s) == -1)
+	{
+		return -1;
+	}
+#endif
+	_tinydir_get_ext(file);
+
+	file->is_dir =
+#ifdef _MSC_VER
+		!!(dir->_f.dwFileAttributes & FILE_ATTRIBUTE_DIRECTORY);
+#else
+		S_ISDIR(file->_s.st_mode);
+#endif
+	file->is_reg =
+#ifdef _MSC_VER
+		!!(dir->_f.dwFileAttributes & FILE_ATTRIBUTE_NORMAL) ||
+		(
+			!(dir->_f.dwFileAttributes & FILE_ATTRIBUTE_DEVICE) &&
+			!(dir->_f.dwFileAttributes & FILE_ATTRIBUTE_DIRECTORY) &&
+			!(dir->_f.dwFileAttributes & FILE_ATTRIBUTE_ENCRYPTED) &&
+#ifdef FILE_ATTRIBUTE_INTEGRITY_STREAM
+			!(dir->_f.dwFileAttributes & FILE_ATTRIBUTE_INTEGRITY_STREAM) &&
+#endif
+#ifdef FILE_ATTRIBUTE_NO_SCRUB_DATA
+			!(dir->_f.dwFileAttributes & FILE_ATTRIBUTE_NO_SCRUB_DATA) &&
+#endif
+			!(dir->_f.dwFileAttributes & FILE_ATTRIBUTE_OFFLINE) &&
+			!(dir->_f.dwFileAttributes & FILE_ATTRIBUTE_TEMPORARY));
+#else
+		S_ISREG(file->_s.st_mode);
+#endif
+
+	return 0;
+}
+
+_TINYDIR_FUNC
+int tinydir_readfile_n(const tinydir_dir *dir, tinydir_file *file, size_t i)
+{
+	if (dir == NULL || file == NULL)
+	{
+		errno = EINVAL;
+		return -1;
+	}
+	if (i >= dir->n_files)
+	{
+		errno = ENOENT;
+		return -1;
+	}
+
+	memcpy(file, &dir->_files[i], sizeof(tinydir_file));
+	_tinydir_get_ext(file);
+
+	return 0;
+}
+
+_TINYDIR_FUNC
+int tinydir_open_subdir_n(tinydir_dir *dir, size_t i)
+{
+	_tinydir_char_t path[_TINYDIR_PATH_MAX];
+	if (dir == NULL)
+	{
+		errno = EINVAL;
+		return -1;
+	}
+	if (i >= dir->n_files || !dir->_files[i].is_dir)
+	{
+		errno = ENOENT;
+		return -1;
+	}
+
+	_tinydir_strcpy(path, dir->_files[i].path);
+	tinydir_close(dir);
+	if (tinydir_open_sorted(dir, path) == -1)
+	{
+		return -1;
+	}
+
+	return 0;
+}
+
+/* Open a single file given its path */
+_TINYDIR_FUNC
+int tinydir_file_open(tinydir_file *file, const _tinydir_char_t *path)
+{
+	tinydir_dir dir;
+	int result = 0;
+	int found = 0;
+	_tinydir_char_t dir_name_buf[_TINYDIR_PATH_MAX];
+	_tinydir_char_t file_name_buf[_TINYDIR_FILENAME_MAX];
+	_tinydir_char_t *dir_name;
+	_tinydir_char_t *base_name;
+#if (defined _MSC_VER || defined __MINGW32__)
+	_tinydir_char_t drive_buf[_TINYDIR_PATH_MAX];
+	_tinydir_char_t ext_buf[_TINYDIR_FILENAME_MAX];
+#endif
+
+	if (file == NULL || path == NULL || _tinydir_strlen(path) == 0)
+	{
+		errno = EINVAL;
+		return -1;
+	}
+	if (_tinydir_strlen(path) + _TINYDIR_PATH_EXTRA >= _TINYDIR_PATH_MAX)
+	{
+		errno = ENAMETOOLONG;
+		return -1;
+	}
+
+	/* Get the parent path */
+#if (defined _MSC_VER || defined __MINGW32__)
+#if ((defined _MSC_VER) && (_MSC_VER >= 1400))
+		_tsplitpath_s(
+			path,
+			drive_buf, _TINYDIR_DRIVE_MAX,
+			dir_name_buf, _TINYDIR_FILENAME_MAX,
+			file_name_buf, _TINYDIR_FILENAME_MAX,
+			ext_buf, _TINYDIR_FILENAME_MAX);
+#else
+		_tsplitpath(
+			path,
+			drive_buf,
+			dir_name_buf,
+			file_name_buf,
+			ext_buf);
+#endif
+
+/* _splitpath_s not work fine with only filename and widechar support */
+#ifdef _UNICODE
+		if (drive_buf[0] == L'\xFEFE')
+			drive_buf[0] = '\0';
+		if (dir_name_buf[0] == L'\xFEFE')
+			dir_name_buf[0] = '\0';
+#endif
+
+	if (errno)
+	{
+		errno = EINVAL;
+		return -1;
+	}
+	/* Emulate the behavior of dirname by returning "." for dir name if it's
+	empty */
+	if (drive_buf[0] == '\0' && dir_name_buf[0] == '\0')
+	{
+		_tinydir_strcpy(dir_name_buf, TINYDIR_STRING("."));
+	}
+	/* Concatenate the drive letter and dir name to form full dir name */
+	_tinydir_strcat(drive_buf, dir_name_buf);
+	dir_name = drive_buf;
+	/* Concatenate the file name and extension to form base name */
+	_tinydir_strcat(file_name_buf, ext_buf);
+	base_name = file_name_buf;
+#else
+	_tinydir_strcpy(dir_name_buf, path);
+	dir_name = dirname(dir_name_buf);
+	_tinydir_strcpy(file_name_buf, path);
+	base_name =basename(file_name_buf);
+#endif
+
+	/* Open the parent directory */
+	if (tinydir_open(&dir, dir_name) == -1)
+	{
+		return -1;
+	}
+
+	/* Read through the parent directory and look for the file */
+	while (dir.has_next)
+	{
+		if (tinydir_readfile(&dir, file) == -1)
+		{
+			result = -1;
+			goto bail;
+		}
+		if (_tinydir_strcmp(file->name, base_name) == 0)
+		{
+			/* File found */
+			found = 1;
+			break;
+		}
+		tinydir_next(&dir);
+	}
+	if (!found)
+	{
+		result = -1;
+		errno = ENOENT;
+	}
+
+bail:
+	tinydir_close(&dir);
+	return result;
+}
+
+_TINYDIR_FUNC
+void _tinydir_get_ext(tinydir_file *file)
+{
+	_tinydir_char_t *period = _tinydir_strrchr(file->name, TINYDIR_STRING('.'));
+	if (period == NULL)
+	{
+		file->extension = &(file->name[_tinydir_strlen(file->name)]);
+	}
+	else
+	{
+		file->extension = period + 1;
+	}
+}
+
+_TINYDIR_FUNC
+int _tinydir_file_cmp(const void *a, const void *b)
+{
+	const tinydir_file *fa = (const tinydir_file *)a;
+	const tinydir_file *fb = (const tinydir_file *)b;
+	if (fa->is_dir != fb->is_dir)
+	{
+		return -(fa->is_dir - fb->is_dir);
+	}
+	return _tinydir_strncmp(fa->name, fb->name, _TINYDIR_FILENAME_MAX);
+}
+
+#ifndef _MSC_VER
+#ifndef _TINYDIR_USE_READDIR
+/*
+The following authored by Ben Hutchings <ben@decadent.org.uk>
+from https://womble.decadent.org.uk/readdir_r-advisory.html
+*/
+/* Calculate the required buffer size (in bytes) for directory      *
+* entries read from the given directory handle.  Return -1 if this  *
+* this cannot be done.                                              *
+*                                                                   *
+* This code does not trust values of NAME_MAX that are less than    *
+* 255, since some systems (including at least HP-UX) incorrectly    *
+* define it to be a smaller value.                                  */
+_TINYDIR_FUNC
+size_t _tinydir_dirent_buf_size(_TINYDIR_DIR *dirp)
+{
+	long name_max;
+	size_t name_end;
+	/* parameter may be unused */
+	(void)dirp;
+
+#if defined _TINYDIR_USE_FPATHCONF
+	name_max = fpathconf(dirfd(dirp), _PC_NAME_MAX);
+	if (name_max == -1)
+#if defined(NAME_MAX)
+		name_max = (NAME_MAX > 255) ? NAME_MAX : 255;
+#else
+		return (size_t)(-1);
+#endif
+#elif defined(NAME_MAX)
+ 	name_max = (NAME_MAX > 255) ? NAME_MAX : 255;
+#else
+#error "buffer size for readdir_r cannot be determined"
+#endif
+	name_end = (size_t)offsetof(struct _tinydir_dirent, d_name) + name_max + 1;
+	return (name_end > sizeof(struct _tinydir_dirent) ?
+		name_end : sizeof(struct _tinydir_dirent));
+}
+#endif
+#endif
+
+#ifdef __cplusplus
+}
+#endif
+
+# if defined (_MSC_VER)
+# pragma warning(pop)
+# endif
+
+#endif

doc/AddErrInfo.3

@@ -9,7 +9,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_GetReturnOptions, Tcl_SetReturnOptions, Tcl_AddErrorInfo, Tcl_AppendObjToErrorInfo, Tcl_AddObjErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_SetErrorLine, Tcl_GetErrorLine, Tcl_PosixError, Tcl_LogCommandInfo \- retrieve or record information about errors and other return options
+Tcl_GetReturnOptions, Tcl_SetReturnOptions, Tcl_AddErrorInfo, Tcl_AppendObjToErrorInfo, Tcl_AddObjErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tcl_SetErrorLine, Tcl_GetErrorLine, Tcl_PosixError, Tcl_LogCommandInfo \- retrieve or record information about errors and other return options
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -30,8 +30,6 @@ int
 .sp
 \fBTcl_SetErrorCode\fR(\fIinterp, element, element, ... \fB(char *) NULL\fR)
 .sp
-\fBTcl_SetErrorCodeVA\fR(\fIinterp, argList\fR)
-.sp
 \fBTcl_GetErrorLine\fR(\fIinterp\fR)
 .sp
 \fBTcl_SetErrorLine\fR(\fIinterp, lineNum\fR)
@@ -60,10 +58,10 @@ unless \fIlength\fR is negative.
 .AP Tcl_Obj *objPtr in
 A message to be appended to the \fB\-errorinfo\fR return option
 in the form of a Tcl_Obj value.
-.AP int length in
+.AP size_t length in
 The number of bytes to copy from \fImessage\fR when
 appending to the \fB\-errorinfo\fR return option.
-If negative, all bytes up to the first null byte are used.
+If (size_t)-1, all bytes up to the first null byte are used.
 .AP Tcl_Obj *errorObjPtr in
 The \fB\-errorcode\fR return option will be set to this value.
 .AP char *element in
@@ -245,9 +243,6 @@ The procedure \fBTcl_SetErrorCode\fR is also used to set the
 record instead of a value. Otherwise, it is similar to
 \fBTcl_SetObjErrorCode\fR in behavior.
 .PP
-\fBTcl_SetErrorCodeVA\fR is the same as \fBTcl_SetErrorCode\fR except that
-instead of taking a variable number of arguments it takes an argument list.
-.PP
 The procedure \fBTcl_GetErrorLine\fR is used to read the integer value
 of the \fB\-errorline\fR return option without the overhead of a full
 call to \fBTcl_GetReturnOptions\fR.  Likewise, \fBTcl_SetErrorLine\fR

doc/Alloc.3

@@ -8,7 +8,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_Alloc, Tcl_Free, Tcl_Realloc, Tcl_AttemptAlloc, Tcl_AttemptRealloc, ckalloc, ckfree, ckrealloc, attemptckalloc, attemptckrealloc \- allocate or free heap memory
+Tcl_Alloc, Tcl_Free, Tcl_Realloc, Tcl_AttemptAlloc, Tcl_AttemptRealloc \- allocate or free heap memory
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -19,29 +19,14 @@ char *
 void
 \fBTcl_Free\fR(\fIptr\fR)
 .sp
-char *
+void *
 \fBTcl_Realloc\fR(\fIptr, size\fR)
 .sp
-char *
+void *
 \fBTcl_AttemptAlloc\fR(\fIsize\fR)
 .sp
-char *
+void *
 \fBTcl_AttemptRealloc\fR(\fIptr, size\fR)
-.sp
-char *
-\fBckalloc\fR(\fIsize\fR)
-.sp
-void
-\fBckfree\fR(\fIptr\fR)
-.sp
-char *
-\fBckrealloc\fR(\fIptr, size\fR)
-.sp
-char *
-\fBattemptckalloc\fR(\fIsize\fR)
-.sp
-char *
-\fBattemptckrealloc\fR(\fIptr, size\fR)
 .SH ARGUMENTS
 .AS char *size
 .AP "unsigned int" size in
@@ -79,14 +64,10 @@ allocation fails, these functions will return NULL.  Note that on some
 platforms, but not all, attempting to allocate a zero-sized block of
 memory will also cause these functions to return NULL.
 .PP
-The procedures \fBckalloc\fR, \fBckfree\fR, \fBckrealloc\fR,
-\fBattemptckalloc\fR, and \fBattemptckrealloc\fR are implemented
-as macros.  Normally, they are synonyms for the corresponding
-procedures documented on this page.  When Tcl and all modules
-calling Tcl are compiled with \fBTCL_MEM_DEBUG\fR defined, however,
-these macros are redefined to be special debugging versions
-of these procedures.  To support Tcl's memory debugging within a
-module, use the macros rather than direct calls to \fBTcl_Alloc\fR, etc.
+When a module or Tcl itself is compiled with \fBTCL_MEM_DEBUG\fR defined,
+the procedures \fBTcl_Alloc\fR, \fBTcl_Free\fR, \fBTcl_Realloc\fR,
+\fBTcl_AttemptAlloc\fR, and \fBTcl_AttempRealloc\fR are implemented
+as macros, redefined to be special debugging versions of these procedures.
 
 .SH KEYWORDS
 alloc, allocation, free, malloc, memory, realloc, TCL_MEM_DEBUG

doc/AllowExc.3

@@ -30,8 +30,7 @@ or \fBTCL_RETURN\fR, then Tcl normally converts this into a \fBTCL_ERROR\fR
 return with an appropriate message.  The particular script
 evaluation procedures of Tcl that act in the manner are
 \fBTcl_EvalObjEx\fR, \fBTcl_EvalObjv\fR, \fBTcl_Eval\fR, \fBTcl_EvalEx\fR,
-\fBTcl_GlobalEval\fR, \fBTcl_GlobalEvalObj\fR, \fBTcl_VarEval\fR and
-\fBTcl_VarEvalVA\fR.
+\fBTcl_GlobalEval\fR, \fBTcl_GlobalEvalObj\fR and \fBTcl_VarEval\fR.
 .PP
 However, if \fBTcl_AllowExceptions\fR is invoked immediately before
 calling one of those a procedures, then arbitrary completion

doc/AssocData.3

@@ -13,7 +13,7 @@ Tcl_GetAssocData, Tcl_SetAssocData, Tcl_DeleteAssocData \- manage associations o
 .nf
 \fB#include <tcl.h>\fR
 .sp
-ClientData
+void *
 \fBTcl_GetAssocData\fR(\fIinterp, key, delProcPtr\fR)
 .sp
 \fBTcl_SetAssocData\fR(\fIinterp, key, delProc, clientData\fR)
@@ -31,7 +31,7 @@ Procedure to call when \fIinterp\fR is deleted.
 .AP Tcl_InterpDeleteProc **delProcPtr in
 Pointer to location in which to store address of current deletion procedure
 for association.  Ignored if NULL.
-.AP ClientData clientData in
+.AP void *clientData in
 Arbitrary one-word value associated with the given key in this
 interpreter.  This data is owned by the caller.
 .BE
@@ -64,7 +64,7 @@ the type \fBTcl_InterpDeleteProc\fR:
 .PP
 .CS
 typedef void \fBTcl_InterpDeleteProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
         Tcl_Interp *\fIinterp\fR);
 .CE
 .PP

doc/Async.3

@@ -30,7 +30,7 @@ int
 .AS Tcl_AsyncHandler clientData
 .AP Tcl_AsyncProc *proc in
 Procedure to invoke to handle an asynchronous event.
-.AP ClientData clientData in
+.AP void *clientData in
 One-word value to pass to \fIproc\fR.
 .AP Tcl_AsyncHandler async in
 Token for asynchronous event handler.
@@ -84,7 +84,7 @@ type \fBTcl_AsyncProc\fR:
 .PP
 .CS
 typedef int \fBTcl_AsyncProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
         Tcl_Interp *\fIinterp\fR,
         int \fIcode\fR);
 .CE

doc/Backslash.3

@@ -1,47 +0,0 @@
-'\"
-'\" Copyright (c) 1989-1993 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\"
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\"
-.TH Tcl_Backslash 3 "8.1" Tcl "Tcl Library Procedures"
-.so man.macros
-.BS
-.SH NAME
-Tcl_Backslash \- parse a backslash sequence
-.SH SYNOPSIS
-.nf
-\fB#include <tcl.h>\fR
-.sp
-char
-\fBTcl_Backslash\fR(\fIsrc, countPtr\fR)
-.SH ARGUMENTS
-.AS char *countPtr out
-.AP char *src in
-Pointer to a string starting with a backslash.
-.AP int *countPtr out
-If \fIcountPtr\fR is not NULL, \fI*countPtr\fR gets filled
-in with number of characters in the backslash sequence, including
-the backslash character.
-.BE
-
-.SH DESCRIPTION
-.PP
-The use of \fBTcl_Backslash\fR is deprecated in favor of
-\fBTcl_UtfBackslash\fR.
-.PP
-This is a utility procedure provided for backwards compatibility with
-non-internationalized Tcl extensions.  It parses a backslash sequence and
-returns the low byte of the Unicode character corresponding to the sequence.
-\fBTcl_Backslash\fR modifies \fI*countPtr\fR to contain the number of
-characters in the backslash sequence.
-.PP
-See the Tcl manual entry for information on the valid backslash sequences.
-All of the sequences described in the Tcl manual entry are supported by
-\fBTcl_Backslash\fR.
-.SH "SEE ALSO"
-Tcl(n), Tcl_UtfBackslash(3)
-
-.SH KEYWORDS
-backslash, parse

doc/ByteArrObj.3

@@ -29,8 +29,8 @@ unsigned char *
 .AP "const unsigned char" *bytes in
 The array of bytes used to initialize or set a byte-array value. May be NULL
 even if \fIlength\fR is non-zero.
-.AP int length in
-The length of the array of bytes.  It must be >= 0.
+.AP size_t length in
+The length of the array of bytes.
 .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

doc/CallDel.3

@@ -23,7 +23,7 @@ Tcl_CallWhenDeleted, Tcl_DontCallWhenDeleted \- Arrange for callback when interp
 Interpreter with which to associated callback.
 .AP Tcl_InterpDeleteProc *proc in
 Procedure to call when \fIinterp\fR is deleted.
-.AP ClientData clientData in
+.AP void *clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .BE
 .SH DESCRIPTION
@@ -38,7 +38,7 @@ type \fBTcl_InterpDeleteProc\fR:
 .PP
 .CS
 typedef void \fBTcl_InterpDeleteProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
         Tcl_Interp *\fIinterp\fR);
 .CE
 .PP

doc/Cancel.3

@@ -30,7 +30,7 @@ ORed combination of flag bits that specify additional options.
 For \fBTcl_CancelEval\fR, only \fBTCL_CANCEL_UNWIND\fR is currently
 supported.  For \fBTcl_Canceled\fR, only \fBTCL_LEAVE_ERR_MSG\fR and
 \fBTCL_CANCEL_UNWIND\fR are currently supported.
-.AP ClientData clientData in
+.AP void *clientData in
 Currently reserved for future use.
 It should be set to NULL.
 .BE

doc/ChnlStack.3

@@ -32,7 +32,7 @@ Tcl_Channel
 Interpreter for error reporting.
 .AP "const Tcl_ChannelType" *typePtr in
 The new channel I/O procedures to use for \fIchannel\fR.
-.AP ClientData clientData in
+.AP void *clientData in
 Arbitrary one-word value to pass to channel I/O procedures.
 .AP int mask in
 Conditions under which \fIchannel\fR will be used: OR-ed combination of

doc/Class.3

@@ -41,12 +41,12 @@ Tcl_Object
 int
 \fBTcl_ObjectDeleted\fR(\fIobject\fR)
 .sp
-ClientData
+void *
 \fBTcl_ObjectGetMetadata\fR(\fIobject, metaTypePtr\fR)
 .sp
 \fBTcl_ObjectSetMetadata\fR(\fIobject, metaTypePtr, metadata\fR)
 .sp
-ClientData
+void *
 \fBTcl_ClassGetMetadata\fR(\fIclass, metaTypePtr\fR)
 .sp
 \fBTcl_ClassSetMetadata\fR(\fIclass, metaTypePtr, metadata\fR)
@@ -56,7 +56,7 @@ Tcl_ObjectMapMethodNameProc
 .sp
 \fBTcl_ObjectSetMethodNameMapper\fR(\fIobject\fR, \fImethodNameMapper\fR)
 .SH ARGUMENTS
-.AS ClientData metadata in/out
+.AS void *metadata in/out
 .AP Tcl_Interp *interp in/out
 Interpreter providing the context for looking up or creating an object, and
 into whose result error messages will be written on failure.
@@ -83,7 +83,7 @@ are not arguments to any constructors.
 .AP Tcl_ObjectMetadataType *metaTypePtr in
 The type of \fImetadata\fR being set with \fBTcl_ClassSetMetadata\fR or
 retrieved with \fBTcl_ClassGetMetadata\fR.
-.AP ClientData metadata in
+.AP void *metadata in
 An item of metadata to attach to the class, or NULL to remove the metadata
 associated with a particular \fImetaTypePtr\fR.
 .AP "Tcl_ObjectMapMethodNameProc" "methodNameMapper" in
@@ -171,7 +171,7 @@ a class or object.
 .PP
 .CS
 typedef void \fBTcl_ObjectMetadataDeleteProc\fR(
-        ClientData \fImetadata\fR);
+        void *\fImetadata\fR);
 .CE
 .PP
 The \fImetadata\fR argument gives the address of the metadata to be
@@ -184,8 +184,8 @@ associated with a class or object.
 .CS
 typedef int \fBTcl_CloneProc\fR(
         Tcl_Interp *\fIinterp\fR,
-        ClientData \fIsrcMetadata\fR,
-        ClientData *\fIdstMetadataPtr\fR);
+        void *\fIsrcMetadata\fR,
+        void **\fIdstMetadataPtr\fR);
 .CE
 .PP
 The \fIinterp\fR argument gives a place to write an error message when the

doc/CrtChannel.3

@@ -17,7 +17,7 @@ Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType, Tcl_GetChanne
 Tcl_Channel
 \fBTcl_CreateChannel\fR(\fItypePtr, channelName, instanceData, mask\fR)
 .sp
-ClientData
+void *
 \fBTcl_GetChannelInstanceData\fR(\fIchannel\fR)
 .sp
 const Tcl_ChannelType *
@@ -128,7 +128,7 @@ by any other channel. Can be NULL, in which case the channel is
 created without a name. If the created channel is assigned to one
 of the standard channels (\fBstdin\fR, \fBstdout\fR or \fBstderr\fR),
 the assigned channel name will be the name of the standard channel.
-.AP ClientData instanceData in
+.AP void *instanceData in
 Arbitrary one-word value to be associated with this channel.  This
 value is passed to procedures in \fItypePtr\fR when they are invoked.
 .AP int mask in
@@ -139,7 +139,7 @@ The channel to operate on.
 .AP int direction in
 \fBTCL_READABLE\fR means the input handle is wanted; \fBTCL_WRITABLE\fR
 means the output handle is wanted.
-.AP ClientData *handlePtr out
+.AP void **handlePtr out
 Points to the location where the desired OS-specific handle should be
 stored.
 .AP int size in
@@ -399,7 +399,7 @@ the generic layer to set blocking and nonblocking mode on the device.
 .PP
 .CS
 typedef int \fBTcl_DriverBlockModeProc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
         int \fImode\fR);
 .CE
 .PP
@@ -434,7 +434,7 @@ closed. \fICloseProc\fR must match the following prototype:
 .PP
 .CS
 typedef int \fBTcl_DriverCloseProc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
         Tcl_Interp *\fIinterp\fR);
 .CE
 .PP
@@ -456,7 +456,7 @@ following prototype:
 .PP
 .CS
 typedef int \fBTcl_DriverClose2Proc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
         Tcl_Interp *\fIinterp\fR,
         int \fIflags\fR);
 .CE
@@ -487,7 +487,7 @@ internal buffer. \fIInputProc\fR must match the following prototype:
 .PP
 .CS
 typedef int \fBTcl_DriverInputProc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
         char *\fIbuf\fR,
         int \fIbufSize\fR,
         int *\fIerrorCodePtr\fR);
@@ -531,7 +531,7 @@ generic layer to transfer data from an internal buffer to the output device.
 .PP
 .CS
 typedef int \fBTcl_DriverOutputProc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
         const char *\fIbuf\fR,
         int \fItoWrite\fR,
         int *\fIerrorCodePtr\fR);
@@ -570,7 +570,7 @@ prototype:
 .PP
 .CS
 typedef int \fBTcl_DriverSeekProc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
         long \fIoffset\fR,
         int \fIseekMode\fR,
         int *\fIerrorCodePtr\fR);
@@ -600,7 +600,7 @@ following prototype:
 .PP
 .CS
 typedef Tcl_WideInt \fBTcl_DriverWideSeekProc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
         Tcl_WideInt \fIoffset\fR,
         int \fIseekMode\fR,
         int *\fIerrorCodePtr\fR);
@@ -622,7 +622,7 @@ the generic layer to set a channel type specific option on a channel.
 .PP
 .CS
 typedef int \fBTcl_DriverSetOptionProc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
         Tcl_Interp *\fIinterp\fR,
         const char *\fIoptionName\fR,
         const char *\fInewValue\fR);
@@ -663,7 +663,7 @@ channel. \fIgetOptionProc\fR must match the following prototype:
 .PP
 .CS
 typedef int \fBTcl_DriverGetOptionProc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
         Tcl_Interp *\fIinterp\fR,
         const char *\fIoptionName\fR,
         Tcl_DString *\fIoptionValue\fR);
@@ -701,7 +701,7 @@ notice events of interest on this channel.
 .PP
 .CS
 typedef void \fBTcl_DriverWatchProc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
         int \fImask\fR);
 .CE
 .PP
@@ -732,9 +732,9 @@ the generic layer to retrieve a device-specific handle from the channel.
 .PP
 .CS
 typedef int \fBTcl_DriverGetHandleProc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
         int \fIdirection\fR,
-        ClientData *\fIhandlePtr\fR);
+        void **\fIhandlePtr\fR);
 .CE
 .PP
 \fIInstanceData\fR is the same as the value passed to
@@ -761,7 +761,7 @@ It should be set to NULL.
 .PP
 .CS
 typedef int \fBTcl_DriverFlushProc\fR(
-        ClientData \fIinstanceData\fR);
+        void *\fIinstanceData\fR);
 .CE
 .PP
 This value can be retrieved with \fBTcl_ChannelFlushProc\fR, which returns
@@ -776,7 +776,7 @@ that occur on the underlying (stacked) channel.
 .PP
 .CS
 typedef int \fBTcl_DriverHandlerProc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
         int \fIinterestMask\fR);
 .CE
 .PP
@@ -805,7 +805,7 @@ might be maintaining using the calling thread as the associate. See
 .PP
 .CS
 typedef void \fBTcl_DriverThreadActionProc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
         int \fIaction\fR);
 .CE
 .PP
@@ -822,7 +822,7 @@ length. It can be NULL.
 .PP
 .CS
 typedef int \fBTcl_DriverTruncateProc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
         Tcl_WideInt \fIlength\fR);
 .CE
 .PP

doc/CrtChnlHdlr.3

@@ -32,7 +32,7 @@ a zero value to temporarily disable an existing handler.
 .AP Tcl_FileProc *proc in
 Procedure to invoke whenever the channel indicated by \fIchannel\fR meets
 the conditions specified by \fImask\fR.
-.AP ClientData clientData in
+.AP void *clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .BE
 .SH DESCRIPTION
@@ -48,7 +48,7 @@ what it means for a channel to be readable or writable.
 .PP
 .CS
 typedef void \fBTcl_ChannelProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
         int \fImask\fR);
 .CE
 .PP

doc/CrtCloseHdlr.3

@@ -26,7 +26,7 @@ void
 The channel for which to create or delete a close callback.
 .AP Tcl_CloseProc *proc in
 The procedure to call as the callback.
-.AP ClientData clientData in
+.AP void *clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .BE
 .SH DESCRIPTION
@@ -38,7 +38,7 @@ Arbitrary one-word value to pass to \fIproc\fR.
 .PP
 .CS
 typedef void \fBTcl_CloseProc\fR(
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 .CE
 .PP
 The \fIclientData\fR is the same as the value provided in the call to

doc/CrtCommand.3

@@ -25,7 +25,7 @@ Name of command.
 .AP Tcl_CmdProc *proc in
 Implementation of new command:  \fIproc\fR will be called whenever
 \fIcmdName\fR is invoked as a command.
-.AP ClientData clientData in
+.AP voie *clientData in
 Arbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR.
 .AP Tcl_CmdDeleteProc *deleteProc in
 Procedure to call before \fIcmdName\fR is deleted from the interpreter;
@@ -75,7 +75,7 @@ and it returns NULL.
 .PP
 .CS
 typedef int \fBTcl_CmdProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
         Tcl_Interp *\fIinterp\fR,
         int \fIargc\fR,
         const char *\fIargv\fR[]);
@@ -131,7 +131,7 @@ result that match the type \fBTcl_CmdDeleteProc\fR:
 .PP
 .CS
 typedef void \fBTcl_CmdDeleteProc\fR(
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 .CE
 .PP
 The \fIclientData\fR argument will be the same as the \fIclientData\fR

doc/CrtFileHdlr.3

@@ -29,7 +29,7 @@ a handler.
 .AP Tcl_FileProc *proc in
 Procedure to invoke whenever the file or device indicated
 by \fIfile\fR meets the conditions specified by \fImask\fR.
-.AP ClientData clientData in
+.AP void *clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .BE
 .SH DESCRIPTION
@@ -51,7 +51,7 @@ type \fBTcl_FileProc\fR:
 .PP
 .CS
 typedef void \fBTcl_FileProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
         int \fImask\fR);
 .CE
 .PP

doc/CrtMathFnc.3

@@ -1,162 +0,0 @@
-'\"
-'\" Copyright (c) 1989-1993 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\"
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\"
-.TH Tcl_CreateMathFunc 3 8.4 Tcl "Tcl Library Procedures"
-.so man.macros
-.BS
-.SH NAME
-Tcl_CreateMathFunc, Tcl_GetMathFuncInfo, Tcl_ListMathFuncs \- Define, query and enumerate math functions for expressions
-.SH "NOTICE OF EVENTUAL DEPRECATION"
-.PP
-The \fBTcl_CreateMathFunc\fR and \fBTcl_GetMathFuncInfo\fR functions
-are rendered somewhat obsolete by the ability to create functions for
-expressions by placing commands in the \fBtcl::mathfunc\fR namespace,
-as described in the \fBmathfunc\fR manual page; the API described on
-this page is not expected to be maintained indefinitely.
-.SH SYNOPSIS
-.nf
-\fB#include <tcl.h>\fR
-.sp
-void
-\fBTcl_CreateMathFunc\fR(\fIinterp, name, numArgs, argTypes, proc, clientData\fR)
-.sp
-int
-\fBTcl_GetMathFuncInfo\fR(\fIinterp, name, numArgsPtr, argTypesPtr, procPtr,
-                    clientDataPtr\fR)
-.sp
-Tcl_Obj *
-\fBTcl_ListMathFuncs\fR(\fIinterp, pattern\fR)
-.SH ARGUMENTS
-.AS Tcl_ValueType *clientDataPtr out
-.AP Tcl_Interp *interp in
-Interpreter in which new function will be defined.
-.AP "const char" *name in
-Name for new function.
-.AP int numArgs in
-Number of arguments to new function;  also gives size of \fIargTypes\fR array.
-.AP Tcl_ValueType *argTypes in
-Points to an array giving the permissible types for each argument to
-function.
-.AP Tcl_MathProc *proc in
-Procedure that implements the function.
-.AP ClientData clientData in
-Arbitrary one-word value to pass to \fIproc\fR when it is invoked.
-.AP int *numArgsPtr out
-Points to a variable that will be set to contain the number of
-arguments to the function.
-.AP Tcl_ValueType **argTypesPtr out
-Points to a variable that will be set to contain a pointer to an array
-giving the permissible types for each argument to the function which
-will need to be freed up using \fITcl_Free\fR.
-.AP Tcl_MathProc **procPtr out
-Points to a variable that will be set to contain a pointer to the
-implementation code for the function (or NULL if the function is
-implemented directly in bytecode).
-.AP ClientData *clientDataPtr out
-Points to a variable that will be set to contain the clientData
-argument passed to \fITcl_CreateMathFunc\fR when the function was
-created if the function is not implemented directly in bytecode.
-.AP "const char" *pattern in
-Pattern to match against function names so as to filter them (by
-passing to \fITcl_StringMatch\fR), or NULL to not apply any filter.
-.BE
-.SH DESCRIPTION
-.PP
-Tcl allows a number of mathematical functions to be used in
-expressions, such as \fBsin\fR, \fBcos\fR, and \fBhypot\fR.
-These functions are represented by commands in the namespace,
-\fBtcl::mathfunc\fR.  The \fBTcl_CreateMathFunc\fR function is
-an obsolete way for applications to add additional functions
-to those already provided by Tcl or to replace existing functions.
-It should not be used by new applications, which should create
-math functions using \fBTcl_CreateObjCommand\fR to create a command
-in the \fBtcl::mathfunc\fR namespace.
-.PP
-In the \fBTcl_CreateMathFunc\fR interface,
-\fIName\fR is the name of the function as it will appear in expressions.
-If \fIname\fR does not already exist in the \fB::tcl::mathfunc\fR
-namespace, then a new command is created in that namespace.
-If \fIname\fR does exist, then the existing function is replaced.
-\fINumArgs\fR and \fIargTypes\fR describe the arguments to the function.
-Each entry in the \fIargTypes\fR array must be
-one of \fBTCL_INT\fR, \fBTCL_DOUBLE\fR, \fBTCL_WIDE_INT\fR,
-or \fBTCL_EITHER\fR to indicate whether the corresponding argument must be an
-integer, a double-precision floating value, a wide (64-bit) integer,
-or any, respectively.
-.PP
-Whenever the function is invoked in an expression Tcl will invoke
-\fIproc\fR.  \fIProc\fR should have arguments and result that match
-the type \fBTcl_MathProc\fR:
-.PP
-.CS
-typedef int \fBTcl_MathProc\fR(
-        ClientData \fIclientData\fR,
-        Tcl_Interp *\fIinterp\fR,
-        Tcl_Value *\fIargs\fR,
-        Tcl_Value *\fIresultPtr\fR);
-.CE
-.PP
-When \fIproc\fR is invoked the \fIclientData\fR and \fIinterp\fR
-arguments will be the same as those passed to \fBTcl_CreateMathFunc\fR.
-\fIArgs\fR will point to an array of \fInumArgs\fR Tcl_Value structures,
-which describe the actual arguments to the function:
-.PP
-.CS
-typedef struct Tcl_Value {
-    Tcl_ValueType \fItype\fR;
-    long \fIintValue\fR;
-    double \fIdoubleValue\fR;
-    Tcl_WideInt \fIwideValue\fR;
-} \fBTcl_Value\fR;
-.CE
-.PP
-The \fItype\fR field indicates the type of the argument and is
-one of \fBTCL_INT\fR, \fBTCL_DOUBLE\fR or \fBTCL_WIDE_INT\fR.
-It will match the \fIargTypes\fR value specified for the function unless
-the \fIargTypes\fR value was \fBTCL_EITHER\fR. Tcl converts
-the argument supplied in the expression to the type requested in
-\fIargTypes\fR, if that is necessary.
-Depending on the value of the \fItype\fR field, the \fIintValue\fR,
-\fIdoubleValue\fR or \fIwideValue\fR
-field will contain the actual value of the argument.
-.PP
-\fIProc\fR should compute its result and store it either as an integer
-in \fIresultPtr->intValue\fR or as a floating value in
-\fIresultPtr->doubleValue\fR.
-It should set also \fIresultPtr->type\fR to one of
-\fBTCL_INT\fR, \fBTCL_DOUBLE\fR or \fBTCL_WIDE_INT\fR
-to indicate which value was set.
-Under normal circumstances \fIproc\fR should return \fBTCL_OK\fR.
-If an error occurs while executing the function, \fIproc\fR should
-return \fBTCL_ERROR\fR and leave an error message in the interpreter's result.
-.PP
-\fBTcl_GetMathFuncInfo\fR retrieves the values associated with
-function \fIname\fR that were passed to a preceding
-\fBTcl_CreateMathFunc\fR call.  Normally, the return code is
-\fBTCL_OK\fR but if the named function does not exist, \fBTCL_ERROR\fR
-is returned and an error message is placed in the interpreter's
-result.
-.PP
-If an error did not occur, the array reference placed in the variable
-pointed to by \fIargTypesPtr\fR is newly allocated, and should be
-released by passing it to \fBTcl_Free\fR.  Some functions (the
-standard set implemented in the core, and those defined by placing
-commands in the \fBtcl::mathfunc\fR namespace) do not have
-argument type information; attempting to retrieve values for
-them causes a NULL to be stored in the variable pointed to by
-\fIprocPtr\fR and the variable pointed to by \fIclientDataPtr\fR
-will not be modified.  The variable pointed to by \fInumArgsPointer\fR
-will contain -1, and no argument types will be stored in the variable
-pointed to by \fIargTypesPointer\fR.
-.PP
-\fBTcl_ListMathFuncs\fR returns a Tcl value containing a list of all
-the math functions defined in the interpreter whose name matches
-\fIpattern\fR.  The returned value has a reference count of zero.
-.SH "SEE ALSO"
-expr(n), info(n), Tcl_CreateObjCommand(3), Tcl_Free(3), Tcl_NewListObj(3)
-.SH KEYWORDS
-expression, mathematical function

doc/CrtObjCmd.3

@@ -8,7 +8,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, Tcl_GetCommandInfo, Tcl_GetCommandInfoFromToken, Tcl_SetCommandInfo, Tcl_SetCommandInfoFromToken, Tcl_GetCommandName, Tcl_GetCommandFullName, Tcl_GetCommandFromObj \- implement new commands in C
+Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, Tcl_GetCommandInfo, Tcl_GetCommandInfoFromToken, Tcl_SetCommandInfo, Tcl_SetCommandInfoFromToken, Tcl_GetCommandName, Tcl_GetCommandFullName, Tcl_GetCommandFromObj Tcl_RegisterCommandTypeName, Tcl_GetCommandTypeName \- implement new commands in C
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -42,6 +42,14 @@ void
 .sp
 Tcl_Command
 \fBTcl_GetCommandFromObj\fR(\fIinterp, objPtr\fR)
+.sp
+.VS "info cmdtype feature"
+void
+\fBTcl_RegisterCommandTypeName\fR(\fIproc, typeName\fR)
+.sp
+const char *
+\fBTcl_GetCommandTypeName\fR(\fItoken\fR)
+.VE "info cmdtype feature"
 .SH ARGUMENTS
 .AS Tcl_CmdDeleteProc *deleteProc in/out
 .AP Tcl_Interp *interp in
@@ -51,7 +59,7 @@ Name of command.
 .AP Tcl_ObjCmdProc *proc in
 Implementation of the new command: \fIproc\fR will be called whenever
 \fIcmdName\fR is invoked as a command.
-.AP ClientData clientData in
+.AP void *clientData in
 Arbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR.
 .AP Tcl_CmdDeleteProc *deleteProc in
 Procedure to call before \fIcmdName\fR is deleted from the interpreter;
@@ -65,6 +73,9 @@ Pointer to structure containing various information about a
 Tcl command.
 .AP Tcl_Obj *objPtr in
 Value containing the name of a Tcl command.
+.AP "const char" *typeName in
+Indicates the name of the type of command implementation associated
+with a particular \fIproc\fR, or NULL to break the association.
 .BE
 .SH DESCRIPTION
 .PP
@@ -91,7 +102,7 @@ and it returns NULL.
 .PP
 .CS
 typedef int \fBTcl_ObjCmdProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
         Tcl_Interp *\fIinterp\fR,
         int \fIobjc\fR,
         Tcl_Obj *const \fIobjv\fR[]);
@@ -164,7 +175,7 @@ result that match the type \fBTcl_CmdDeleteProc\fR:
 .PP
 .CS
 typedef void \fBTcl_CmdDeleteProc\fR(
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 .CE
 .PP
 The \fIclientData\fR argument will be the same as the \fIclientData\fR
@@ -206,11 +217,11 @@ A \fBTcl_CmdInfo\fR structure has the following fields:
 typedef struct Tcl_CmdInfo {
     int \fIisNativeObjectProc\fR;
     Tcl_ObjCmdProc *\fIobjProc\fR;
-    ClientData \fIobjClientData\fR;
+    void *\fIobjClientData\fR;
     Tcl_CmdProc *\fIproc\fR;
-    ClientData \fIclientData\fR;
+    void *\fIclientData\fR;
     Tcl_CmdDeleteProc *\fIdeleteProc\fR;
-    ClientData \fIdeleteData\fR;
+    void *\fIdeleteData\fR;
     Tcl_Namespace *\fInamespacePtr\fR;
 } \fBTcl_CmdInfo\fR;
 .CE
@@ -236,7 +247,7 @@ otherwise, this is a compatibility procedure
 registered by \fBTcl_CreateObjCommand\fR
 that simply calls the command's
 value-based procedure after converting its string arguments to Tcl values.
-The field \fIdeleteData\fR is the ClientData value
+The field \fIdeleteData\fR is the clientData value
 to pass to \fIdeleteProc\fR;  it is normally the same as
 \fIclientData\fR but may be set independently using the
 \fBTcl_SetCommandInfo\fR procedure.
@@ -250,7 +261,7 @@ from \fBTcl_CreateObjCommand\fR in place of the command name.  If the
 and fills in the structure designated by \fIinfoPtr\fR.
 .PP
 \fBTcl_SetCommandInfo\fR is used to modify the procedures and
-ClientData values associated with a command.
+clientData values associated with a command.
 Its \fIcmdName\fR argument is the name of a command in \fIinterp\fR.
 \fIcmdName\fR may include \fB::\fR namespace qualifiers
 to identify a command in a particular namespace.
@@ -266,9 +277,9 @@ copies the information from \fI*infoPtr\fR to Tcl's internal structure
 for the command and returns 1.
 .PP
 Note that \fBTcl_SetCommandInfo\fR and
-\fBTcl_SetCommandInfoFromToken\fR both allow the ClientData for a
+\fBTcl_SetCommandInfoFromToken\fR both allow the clientData for a
 command's deletion procedure to be given a different value than the
-ClientData for its command procedure.
+clientData for its command procedure.
 .PP
 Note that neither \fBTcl_SetCommandInfo\fR nor
 \fBTcl_SetCommandInfoFromToken\fR will change a command's namespace.
@@ -296,6 +307,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
+.VS "info cmdtype feature"
+\fBTcl_RegisterCommandTypeName\fR is used to associate a name (the
+\fItypeName\fR argument) with a particular implementation function so that it
+can then be looked up with \fBTcl_GetCommandTypeName\fR, which in turn is
+called with a command token that information is wanted for and which returns
+the name of the type that was registered for the implementation function used
+for that command. (The lookup functionality is surfaced virtually directly in Tcl via
+\fBinfo cmdtype\fR.) If there is no function registered for a particular
+function, the result will be the string literal
+.QW \fBnative\fR .
+The registration of a name can be undone by registering a mapping to NULL
+instead. The result from \fBTcl_GetCommandTypeName\fR will be exactly that
+string which was registered, and not a copy; use of a compile-time constant
+string is \fIstrongly recommended\fR.
+.VE "info cmdtype feature"
 .SH "SEE ALSO"
 Tcl_CreateCommand(3), Tcl_ResetResult(3), Tcl_SetObjResult(3)
 .SH KEYWORDS

doc/CrtTimerHdlr.3

@@ -24,7 +24,7 @@ Tcl_TimerToken
 How many milliseconds to wait before invoking \fIproc\fR.
 .AP Tcl_TimerProc *proc in
 Procedure to invoke after \fImilliseconds\fR have elapsed.
-.AP ClientData clientData in
+.AP void *clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .AP Tcl_TimerToken token in
 Token for previously created timer handler (the return value
@@ -51,7 +51,7 @@ the type \fBTcl_TimerProc\fR:
 .PP
 .CS
 typedef void \fBTcl_TimerProc\fR(
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 .CE
 .PP
 The \fIclientData\fR parameter to \fIproc\fR is a

doc/CrtTrace.3

@@ -41,7 +41,7 @@ details of the calling sequence.
 .AP Tcl_CmdTraceProc *proc in
 Procedure to call for each command that is executed.  See below for
 details on the calling sequence.
-.AP ClientData clientData in
+.AP void *clientData in
 Arbitrary one-word value to pass to \fIobjProc\fR or \fIproc\fR.
 .AP Tcl_CmdObjTraceDeleteProc *deleteProc in
 Procedure to call when the trace is deleted.  See below for details of
@@ -66,7 +66,7 @@ interpreter.
 .PP
 .CS
 typedef int \fBTcl_CmdObjTraceProc\fR(
-        \fBClientData\fR \fIclientData\fR,
+        \fBvoid *\fR \fIclientData\fR,
         \fBTcl_Interp\fR* \fIinterp\fR,
         int \fIlevel\fR,
         const char *\fIcommand\fR,
@@ -77,7 +77,7 @@ typedef int \fBTcl_CmdObjTraceProc\fR(
 .PP
 The \fIclientData\fR and \fIinterp\fR parameters are copies of the
 corresponding arguments given to \fBTcl_CreateTrace\fR.
-\fIClientData\fR typically points to an application-specific data
+\fIclientData\fR typically points to an application-specific data
 structure that describes what to do when \fIobjProc\fR is invoked.  The
 \fIlevel\fR parameter gives the nesting level of the command (1 for
 top-level commands passed to \fBTcl_Eval\fR by the application, 2 for
@@ -144,7 +144,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
@@ -160,12 +160,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

doc/DString.3

@@ -9,7 +9,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_DStringInit, Tcl_DStringAppend, Tcl_DStringAppendElement, Tcl_DStringStartSublist, Tcl_DStringEndSublist, Tcl_DStringLength, Tcl_DStringValue, Tcl_DStringSetLength, Tcl_DStringTrunc, Tcl_DStringFree, Tcl_DStringResult, Tcl_DStringGetResult \- manipulate dynamic strings
+Tcl_DStringInit, Tcl_DStringAppend, Tcl_DStringAppendElement, Tcl_DStringStartSublist, Tcl_DStringEndSublist, Tcl_DStringLength, Tcl_DStringValue, Tcl_DStringSetLength, Tcl_DStringFree, Tcl_DStringResult, Tcl_DStringGetResult \- manipulate dynamic strings
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -26,7 +26,7 @@ char *
 .sp
 \fBTcl_DStringEndSublist\fR(\fIdsPtr\fR)
 .sp
-int
+size_t
 \fBTcl_DStringLength\fR(\fIdsPtr\fR)
 .sp
 char *
@@ -34,8 +34,6 @@ char *
 .sp
 \fBTcl_DStringSetLength\fR(\fIdsPtr, newLength\fR)
 .sp
-\fBTcl_DStringTrunc\fR(\fIdsPtr, newLength\fR)
-.sp
 \fBTcl_DStringFree\fR(\fIdsPtr\fR)
 .sp
 \fBTcl_DStringResult\fR(\fIinterp, dsPtr\fR)
@@ -49,10 +47,10 @@ Pointer to structure that is used to manage a dynamic string.
 Pointer to characters to append to dynamic string.
 .AP "const char" *element in
 Pointer to characters to append as list element to dynamic string.
-.AP int length in
-Number of bytes from \fIbytes\fR to add to dynamic string.  If -1,
+.AP size_t length in
+Number of bytes from \fIbytes\fR to add to dynamic string.  If (size_t)-1,
 add all characters up to null terminating character.
-.AP int newLength in
+.AP size_t newLength in
 New length for dynamic string, not including null terminating
 character.
 .AP Tcl_Interp *interp in/out
@@ -128,10 +126,6 @@ caller to fill in the new space.
 even if the string is truncated to zero length, so \fBTcl_DStringFree\fR
 will still need to be called.
 .PP
-\fBTcl_DStringTrunc\fR changes the length of a dynamic string.
-This procedure is now deprecated.  \fBTcl_DStringSetLength\fR  should
-be used instead.
-.PP
 \fBTcl_DStringFree\fR should be called when you are finished using
 the string.  It frees up any memory that was allocated for the string
 and reinitializes the string's value to an empty string.

doc/DoWhenIdle.3

@@ -21,7 +21,7 @@ Tcl_DoWhenIdle, Tcl_CancelIdleCall \- invoke a procedure when there are no pendi
 .AS Tcl_IdleProc clientData
 .AP Tcl_IdleProc *proc in
 Procedure to invoke.
-.AP ClientData clientData in
+.AP coid *clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .BE
 .SH DESCRIPTION
@@ -43,7 +43,7 @@ type \fBTcl_IdleProc\fR:
 .PP
 .CS
 typedef void \fBTcl_IdleProc\fR(
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 .CE
 .PP
 The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR

doc/DumpActiveMemory.3

@@ -43,7 +43,7 @@ is not defined, these functions are all no-ops.
 \fBTcl_DumpActiveMemory\fR will output a list of all currently
 allocated memory to the specified file.  The information output for
 each allocated block of memory is:  starting and ending addresses
-(excluding guard zone), size, source file where \fBckalloc\fR was
+(excluding guard zone), size, source file where \fBTcl_Alloc\fR was
 called to allocate the block and line number in that file.  It is
 especially useful to call \fBTcl_DumpActiveMemory\fR after the Tcl
 interpreter has been deleted.
@@ -55,8 +55,8 @@ by \fBTcl_Main\fR.
 \fBTcl_ValidateAllMemory\fR forces a validation of the guard zones of
 all currently allocated blocks of memory.  Normally validation of a
 block occurs when its freed, unless full validation is enabled, in
-which case validation of all blocks occurs when \fBckalloc\fR and
-\fBckfree\fR are called.  This function forces the validation to occur
+which case validation of all blocks occurs when \fBTcl_Alloc\fR and
+\fBTcl_Free\fR are called.  This function forces the validation to occur
 at any point.
 
 .SH "SEE ALSO"

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_WinTCharToUtf, Tcl_WinUtfToTChar, Tcl_GetEncodingName, Tcl_SetSystemEncoding, Tcl_GetEncodingNameFromEnvironment, Tcl_GetEncodingNames, Tcl_CreateEncoding, Tcl_GetEncodingSearchPath, Tcl_SetEncodingSearchPath \- procedures for creating and using encodings
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -62,12 +62,6 @@ Tcl_Obj *
 .sp
 int
 \fBTcl_SetEncodingSearchPath\fR(\fIsearchPath\fR)
-.sp
-const char *
-\fBTcl_GetDefaultEncodingDir\fR(\fIvoid\fR)
-.sp
-void
-\fBTcl_SetDefaultEncodingDir\fR(\fIpath\fR)
 .SH ARGUMENTS
 .AS "const Tcl_EncodingType" *dstWrotePtr in/out
 .AP Tcl_Interp *interp in
@@ -89,7 +83,7 @@ specified encoding that are to be converted to UTF-8.  For the
 UTF-8 characters to be converted to the specified encoding.
 .AP "const TCHAR" *tsrc in
 An array of Windows TCHAR characters to convert to UTF-8.
-.AP int srcLen in
+.AP size_t srcLen in
 Length of \fIsrc\fR or \fItsrc\fR in bytes.  If the length is negative, the
 encoding-specific length of the string is used.
 .AP Tcl_DString *dstPtr out
@@ -287,7 +281,7 @@ the encoding name to it.  The \fBTcl_DStringValue\fR is returned.
 \fBTcl_GetEncodingNames\fR sets the \fIinterp\fR result to a list
 consisting of the names of all the encodings that are currently defined
 or can be dynamically loaded, searching the encoding path specified by
-\fBTcl_SetDefaultEncodingDir\fR.  This procedure does not ensure that the
+\fBTcl_SetEncodingSearchPath\fR.  This procedure does not ensure that the
 dynamically-loadable encoding files contain valid data, but merely that they
 exist.
 .PP
@@ -314,7 +308,7 @@ typedef struct Tcl_EncodingType {
     Tcl_EncodingConvertProc *\fItoUtfProc\fR;
     Tcl_EncodingConvertProc *\fIfromUtfProc\fR;
     Tcl_EncodingFreeProc *\fIfreeProc\fR;
-    ClientData \fIclientData\fR;
+    void *\fIclientData\fR;
     int \fInullSize\fR;
 } \fBTcl_EncodingType\fR;
 .CE
@@ -345,7 +339,7 @@ type \fBTcl_EncodingConvertProc\fR:
 .PP
 .CS
 typedef int \fBTcl_EncodingConvertProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
         const char *\fIsrc\fR,
         int \fIsrcLen\fR,
         int \fIflags\fR,
@@ -377,7 +371,7 @@ The callback procedure \fIfreeProc\fR, if non-NULL, should match the type
 .PP
 .CS
 typedef void \fBTcl_EncodingFreeProc\fR(
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 .CE
 .PP
 This \fIfreeProc\fR function is called when the encoding is deleted.  The
@@ -402,15 +396,6 @@ are not verified as existing readable filesystem directories.  When
 searching for encoding data files takes place, and non-existent or
 non-readable filesystem directories on the \fIsearchPath\fR are silently
 ignored.
-.PP
-\fBTcl_GetDefaultEncodingDir\fR and \fBTcl_SetDefaultEncodingDir\fR
-are obsolete interfaces best replaced with calls to
-\fBTcl_GetEncodingSearchPath\fR and \fBTcl_SetEncodingSearchPath\fR.
-They are called to access and set the first element of the \fIsearchPath\fR
-list.  Since Tcl searches \fIsearchPath\fR for encoding data files in
-list order, these routines establish the
-.QW default
-directory in which to find encoding data files.
 .SH "ENCODING FILES"
 Space would prohibit precompiling into Tcl every possible encoding
 algorithm, so many encodings are stored on disk as dynamically-loadable

doc/Eval.3

@@ -10,7 +10,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_EvalObjEx, Tcl_EvalFile, Tcl_EvalObjv, Tcl_Eval, Tcl_EvalEx, Tcl_GlobalEval, Tcl_GlobalEvalObj, Tcl_VarEval, Tcl_VarEvalVA \- execute Tcl scripts
+Tcl_EvalObjEx, Tcl_EvalFile, Tcl_EvalObjv, Tcl_Eval, Tcl_EvalEx, Tcl_GlobalEval, Tcl_GlobalEvalObj, Tcl_VarEval \- execute Tcl scripts
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -38,9 +38,6 @@ int
 .sp
 int
 \fBTcl_VarEval\fR(\fIinterp, part, part, ... \fB(char *) NULL\fR)
-.sp
-int
-\fBTcl_VarEvalVA\fR(\fIinterp, argList\fR)
 .SH ARGUMENTS
 .AS Tcl_Interp **termPtr
 .AP Tcl_Interp *interp in
@@ -67,9 +64,6 @@ first null byte are used.
 Points to first byte of script to execute (null-terminated and UTF-8).
 .AP char *part in
 String forming part of a Tcl script.
-.AP va_list argList in
-An argument list which must have been initialized using
-\fBva_start\fR, and cleared using \fBva_end\fR.
 .BE
 
 .SH DESCRIPTION
@@ -128,16 +122,10 @@ might be a UTF-8 special code.  The string is parsed and executed directly
 bytecodes.  In situations where it is known that the script will never be
 executed again, \fBTcl_Eval\fR may be faster than \fBTcl_EvalObjEx\fR.
  \fBTcl_Eval\fR returns a completion code and result just like
-\fBTcl_EvalObjEx\fR.  Note: for backward compatibility with versions before
-Tcl 8.0, \fBTcl_Eval\fR copies the value result in \fIinterp\fR to
-\fIinterp->result\fR (use is deprecated) where it can be accessed directly.
- This makes \fBTcl_Eval\fR somewhat slower than \fBTcl_EvalEx\fR, which
-does not do the copy.
+\fBTcl_EvalObjEx\fR.
 .PP
 \fBTcl_EvalEx\fR is an extended version of \fBTcl_Eval\fR that takes
-additional arguments \fInumBytes\fR and \fIflags\fR.  For the
-efficiency reason given above, \fBTcl_EvalEx\fR is generally preferred
-over \fBTcl_Eval\fR.
+additional arguments \fInumBytes\fR and \fIflags\fR.
 .PP
 \fBTcl_GlobalEval\fR and \fBTcl_GlobalEvalObj\fR are older procedures
 that are now deprecated.  They are similar to \fBTcl_EvalEx\fR and
@@ -153,10 +141,6 @@ It returns the result of the command and also modifies
 \fIinterp->result\fR 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.
 
 .SH "FLAG BITS"
 .PP

doc/Exit.3

@@ -42,7 +42,7 @@ usually means that an error occurred.
 Procedure to invoke before exiting application, or (for
 \fBTcl_SetExitProc\fR) NULL to uninstall the current application exit
 procedure.
-.AP ClientData clientData in
+.AP void *clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .BE
 
@@ -64,7 +64,7 @@ otherwise causes the application to terminate without calling
 returns control to its caller.
 If an application exit handler has been installed (see
 \fBTcl_SetExitProc\fR), that handler is invoked with an argument
-consisting of the exit status (cast to ClientData); the application
+consisting of the exit status (cast to void *); the application
 exit handler should not return control to Tcl.
 .PP
 \fBTcl_Finalize\fR is similar to \fBTcl_Exit\fR except that it does not
@@ -93,7 +93,7 @@ and freeing global memory.
 .PP
 .CS
 typedef void \fBTcl_ExitProc\fR(
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 .CE
 .PP
 The \fIclientData\fR parameter to \fIproc\fR is a
@@ -133,7 +133,7 @@ installed, that exit handler takes over complete responsibility for
 finalization of Tcl's subsystems via \fBTcl_Finalize\fR at an
 appropriate time.  The argument passed to \fIproc\fR when it is
 invoked will be the exit status code (as passed to \fBTcl_Exit\fR)
-cast to a ClientData value.
+cast to a void *value.
 .SH "SEE ALSO"
 exit(n)
 .SH KEYWORDS

doc/FileSystem.3

@@ -20,7 +20,7 @@ int
 int
 \fBTcl_FSUnregister\fR(\fIfsPtr\fR)
 .sp
-ClientData
+void *
 \fBTcl_FSData\fR(\fIfsPtr\fR)
 .sp
 void
@@ -125,7 +125,7 @@ Tcl_Obj *
 int
 \fBTcl_FSConvertToPathType\fR(\fIinterp, pathPtr\fR)
 .sp
-ClientData
+void *
 \fBTcl_FSGetInternalRep\fR(\fIpathPtr, fsPtr\fR)
 .sp
 Tcl_Obj *
@@ -212,7 +212,7 @@ this structure will be returned. This parameter may be NULL.
 .AP Tcl_Interp *interp in
 Interpreter to use either for results, evaluation, or reporting error
 messages.
-.AP ClientData clientData in
+.AP void *clientData in
 The native description of the path value to create.
 .AP Tcl_Obj *firstPtr in
 The first of two path values to compare. The value may be converted
@@ -249,7 +249,7 @@ Name of a procedure to look up in the file's symbol table
 Filled with the init function for this code.
 .AP Tcl_PackageInitProc **proc2Ptr out
 Filled with the safe-init function for this code.
-.AP ClientData *clientDataPtr out
+.AP void **clientDataPtr out
 Filled with the clientData value to pass to this code's unload
 function when it is called.
 .AP Tcl_LoadHandle *loadHandlePtr out
@@ -724,7 +724,7 @@ better functions to use for most purposes.
 \fBTcl_FSGetTranslatedStringPath\fR does the same as
 \fBTcl_FSGetTranslatedPath\fR, but returns a character string or NULL.
 The string returned is dynamically allocated and owned by the caller,
-which must store it or call \fBckfree\fR to ensure it is freed. Again,
+which must store it or call \fBTcl_Free\fR to ensure it is freed. Again,
 \fBTcl_FSGetNormalizedPath\fR or \fBTcl_FSGetNativePath\fR are usually
 better functions to use for most purposes.
 .PP
@@ -791,7 +791,7 @@ It returns one of \fBTCL_PATH_ABSOLUTE\fR, \fBTCL_PATH_RELATIVE\fR, or
 .SS "PORTABLE STAT RESULT API"
 .PP
 \fBTcl_AllocStatBuf\fR allocates a \fITcl_StatBuf\fR on the system heap (which
-may be deallocated by being passed to \fBckfree\fR). This allows extensions to
+may be deallocated by being passed to \fBTcl_Free\fR). This allows extensions to
 invoke \fBTcl_FSStat\fR and \fBTcl_FSLstat\fR without being dependent on the
 size of the buffer. That in turn depends on the flags used to build Tcl.
 .PP
@@ -841,7 +841,7 @@ general that is not a good thing to do). \fBTCL_OK\fR will be returned.
 the list of known filesystems, if it is known, and returns \fBTCL_OK\fR. If
 the filesystem is not currently registered, \fBTCL_ERROR\fR is returned.
 .PP
-\fBTcl_FSData\fR will return the ClientData associated with the given
+\fBTcl_FSData\fR will return the clientData associated with the given
 filesystem, if that filesystem is registered. Otherwise it will
 return NULL.
 .PP
@@ -1018,7 +1018,7 @@ Tcl's internal list of known filesystems.
 .CS
 typedef int \fBTcl_FSPathInFilesystemProc\fR(
         Tcl_Obj *\fIpathPtr\fR,
-        ClientData *\fIclientDataPtr\fR);
+        void **\fIclientDataPtr\fR);
 .CE
 .SS DUPINTERNALREPPROC
 .PP
@@ -1028,8 +1028,8 @@ simply not copy the internal representation, which may then need to be
 regenerated later.
 .PP
 .CS
-typedef ClientData \fBTcl_FSDupInternalRepProc\fR(
-        ClientData \fIclientData\fR);
+typedef void *\fBTcl_FSDupInternalRepProc\fR(
+        void *\fIclientData\fR);
 .CE
 .SS FREEINTERNALREPPROC
 Free the internal representation. This must be implemented if internal
@@ -1038,7 +1038,7 @@ internal representation is generated), but may otherwise be NULL.
 .PP
 .CS
 typedef void \fBTcl_FSFreeInternalRepProc\fR(
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 .CE
 .SS INTERNALTONORMALIZEDPROC
 .PP
@@ -1049,7 +1049,7 @@ representation is the normalized path.
 .PP
 .CS
 typedef Tcl_Obj *\fBTcl_FSInternalToNormalizedProc\fR(
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 .CE
 .SS CREATEINTERNALREPPROC
 .PP
@@ -1060,7 +1060,7 @@ the \fITcl_FSPathInFilesystemProc\fR for this filesystem always
 immediately creates an internal representation for paths it accepts.
 .PP
 .CS
-typedef ClientData \fBTcl_FSCreateInternalRepProc\fR(
+typedef void *\fBTcl_FSCreateInternalRepProc\fR(
         Tcl_Obj *\fIpathPtr\fR);
 .CE
 .SS NORMALIZEPATHPROC

doc/GetInt.3

@@ -64,12 +64,9 @@ if the first such characters are
 then \fIsrc\fR is expected to be in octal form;  otherwise,
 if the first such characters are
 .QW \fB0b\fR
-then \fIsrc\fR is expected to be in binary form;  otherwise,
-if the first such character is
-.QW \fB0\fR
 then \fIsrc\fR
-is expected to be in octal form;  otherwise, \fIsrc\fR
-is expected to be in decimal form.
+is expected to be in binary form;  otherwise, \fIsrc\fR is
+expected to be in decimal form.
 .PP
 \fBTcl_GetDouble\fR expects \fIsrc\fR to consist of a floating-point
 number, which is:  white space;  a sign; a sequence of digits;  a

doc/GetOpnFl.3

@@ -28,7 +28,7 @@ be used for reading.
 .AP int checkUsage in
 If non-zero, then an error will be generated if the file was not opened
 for the access indicated by \fIwrite\fR.
-.AP ClientData *filePtr out
+.AP void **filePtr out
 Points to word in which to store pointer to FILE structure for
 the file given by \fIchanID\fR.
 .BE

doc/GetTime.3

@@ -27,13 +27,13 @@ Pointer to handler function replacing \fBTcl_GetTime\fR's access to the OS.
 .AP Tcl_ScaleTimeProc scaleProc in
 Pointer to handler function for the conversion of time delays in the
 virtual domain to real-time.
-.AP ClientData clientData in
+.AP void *clientData in
 Value passed through to the two handler functions.
 .AP Tcl_GetTimeProc *getProcPtr out
 Pointer to place the currently registered get handler function into.
 .AP Tcl_ScaleTimeProc *scaleProcPtr out
 Pointer to place the currently registered scale handler function into.
-.AP ClientData *clientDataPtr out
+.AP void **clientDataPtr out
 Pointer to place the currently registered pass-through value into.
 .BE
 .SH DESCRIPTION
@@ -83,10 +83,10 @@ The signatures of the handler functions are as follows:
 .CS
 typedef void \fBTcl_GetTimeProc\fR(
         Tcl_Time *\fItimebuf\fR,
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 typedef void \fBTcl_ScaleTimeProc\fR(
         Tcl_Time *\fItimebuf\fR,
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 .CE
 .PP
 The \fItimebuf\fR fields contain the time to manipulate, and the

doc/Hash.3

@@ -30,7 +30,7 @@ Tcl_HashEntry *
 Tcl_HashEntry *
 \fBTcl_FindHashEntry\fR(\fItablePtr, key\fR)
 .sp
-ClientData
+void *
 \fBTcl_GetHashValue\fR(\fIentryPtr\fR)
 .sp
 \fBTcl_SetHashValue\fR(\fIentryPtr, value\fR)
@@ -66,9 +66,8 @@ The word at \fI*newPtr\fR is set to 1 if a new entry was created
 and 0 if there was already an entry for \fIkey\fR.
 .AP Tcl_HashEntry *entryPtr in
 Pointer to hash table entry.
-.AP ClientData value in
-New value to assign to hash table entry.  Need not have type
-ClientData, but must fit in same space as ClientData.
+.AP void *value in
+New value to assign to hash table entry.
 .AP Tcl_HashSearch *searchPtr in
 Pointer to record to use to keep track of progress in enumerating
 all the entries in a hash table.
@@ -186,11 +185,6 @@ instead, it returns NULL as result.
 .PP
 \fBTcl_GetHashValue\fR and \fBTcl_SetHashValue\fR are used to
 read and write an entry's value, respectively.
-Values are stored and retrieved as type
-.QW ClientData ,
-which is
-large enough to hold a pointer value.  On almost all machines this is
-large enough to hold an integer value too.
 .PP
 \fBTcl_GetHashKey\fR returns the key for a given hash table entry,
 either as a pointer to a string, a one-word
@@ -229,7 +223,7 @@ overall information about a hash table, such as the number of
 entries it contains, the number of buckets in its hash array,
 and the utilization of the buckets.
 It is the caller's responsibility to free the result string
-by passing it to \fBckfree\fR.
+by passing it to \fBTcl_Free\fR.
 .PP
 The header file \fBtcl.h\fR defines the actual data structures
 used to implement hash tables.

doc/InitStubs.3

@@ -63,9 +63,9 @@ Define the \fBUSE_TCL_STUBS\fR symbol.  Typically, you would include the
 \fB\-DUSE_TCL_STUBS\fR flag when compiling the extension.
 .IP 3) 5
 Link the extension with the Tcl stubs library instead of the standard
-Tcl library.  For example, to use the Tcl 8.6 ABI on Unix platforms,
-the library name is \fIlibtclstub8.6.a\fR; on Windows platforms, the
-library name is \fItclstub86.lib\fR.
+Tcl library.  For example, to use the Tcl 9.0 ABI on Unix platforms,
+the library name is \fIlibtclstub9.0.a\fR; on Windows platforms, the
+library name is \fItclstub90.lib\fR.
 .PP
 If the extension also requires the Tk API, it must also call
 \fBTk_InitStubs\fR to initialize the Tk stubs interface and link

doc/Interp.3

@@ -33,19 +33,6 @@ the pointer as described below is no longer supported.  The supported
 public routines \fBTcl_SetResult\fR, \fBTcl_GetResult\fR,
 \fBTcl_SetErrorLine\fR, \fBTcl_GetErrorLine\fR must be used instead.
 .PP
-For legacy programs and extensions no longer being maintained, compiles
-against the Tcl 8.6 header files are only possible with the compiler
-directives
-.CS
-#define USE_INTERP_RESULT
-.CE
-and/or
-.CS
-#define USE_INTERP_ERRORLINE
-.CE
-depending on which fields of the \fBTcl_Interp\fR struct are accessed.
-These directives may be embedded in code or supplied via compiler options.
-.PP
 The \fIresult\fR and \fIfreeProc\fR fields are used to return
 results or error messages from commands.
 This information is returned by command procedures back to \fBTcl_Eval\fR,

doc/Limit.3

@@ -83,7 +83,7 @@ the handler returns.  Many handlers may be attached to the same
 interpreter limit; their order of execution is not defined, and they
 must be identified by \fIhandlerProc\fR and \fIclientData\fR when they
 are deleted.
-.AP ClientData clientData in
+.AP void *clientData in
 Arbitrary pointer-sized word used to pass some context to the
 \fIhandlerProc\fR function.
 .AP Tcl_LimitHandlerDeleteProc *deleteProc in
@@ -162,7 +162,7 @@ following prototype:
 .PP
 .CS
 typedef void \fBTcl_LimitHandlerProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
         Tcl_Interp *\fIinterp\fR);
 .CE
 .PP
@@ -179,7 +179,7 @@ following prototype:
 .PP
 .CS
 typedef void \fBTcl_LimitHandlerDeleteProc\fR(
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 .CE
 .PP
 A limit handler may be deleted using \fBTcl_LimitRemoveHandler\fR; the

doc/LinkVar.3

@@ -190,7 +190,7 @@ Tcl errors.
 \fBTCL_LINK_STRING\fR
 The C variable is of type \fBchar *\fR.
 If its value is not NULL then it must be a pointer to a string
-allocated with \fBTcl_Alloc\fR or \fBckalloc\fR.
+allocated with \fBTcl_Alloc\fR.
 Whenever the Tcl variable is modified the current C string will be
 freed and new memory will be allocated to hold a copy of the variable's
 new value.

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)
@@ -56,7 +61,7 @@ Tcl_Object
 int
 \fBTcl_ObjectContextSkippedArgs\fR(\fIcontext\fR)
 .SH ARGUMENTS
-.AS ClientData clientData in
+.AS void *clientData in
 .AP Tcl_Interp *interp in/out
 The interpreter holding the object or class to create or update a method in.
 .AP Tcl_Object object in
@@ -66,17 +71,22 @@ 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.
-.AP ClientData clientData in
+.AP void *clientData in
 A piece of data that is passed to the implementation of the method without
 interpretation.
-.AP ClientData *clientDataPtr out
+.AP void **clientDataPtr out
 A pointer to a variable in which to write the \fIclientData\fR value supplied
 when the method was created. If NULL, the \fIclientData\fR value will not be
 retrieved.
@@ -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.
@@ -195,7 +213,7 @@ Functions matching this signature are called when the method is invoked.
 .PP
 .CS
 typedef int \fBTcl_MethodCallProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
         Tcl_Interp *\fIinterp\fR,
         Tcl_ObjectContext \fIobjectContext\fR,
         int \fIobjc\fR,
@@ -216,7 +234,7 @@ through a new method being created or because the object or class is deleted.
 .PP
 .CS
 typedef void \fBTcl_MethodDeleteProc\fR(
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 .CE
 .PP
 The \fIclientData\fR argument to a Tcl_MethodDeleteProc will be the same as
@@ -230,8 +248,8 @@ class is copied using \fBTcl_CopyObjectInstance\fR (or \fBoo::copy\fR).
 .CS
 typedef int \fBTcl_CloneProc\fR(
         Tcl_Interp *\fIinterp\fR,
-        ClientData \fIoldClientData\fR,
-        ClientData *\fInewClientDataPtr\fR);
+        void *\fIoldClientData\fR,
+        void **\fInewClientDataPtr\fR);
 .CE
 .PP
 The \fIinterp\fR argument gives a place to write an error message when the

doc/NRE.3

@@ -1,6 +1,6 @@
 .\"
 .\" Copyright (c) 2008 by Kevin B. Kenny.
-.\" Copyright (c) 2018 by Nathan Coulter. 
+.\" Copyright (c) 2018 by Nathan Coulter.
 .\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
@@ -49,7 +49,7 @@ in the same way as the \fIproc\fR argument to \fBTcl_CreateObjCommand\fR(3)
 (\fIq.v.\fR).
 .AP Tcl_ObjCmdProc *nreProc in
 Called instead of \fIproc\fR when a trampoline is already in use.
-.AP ClientData clientData in
+.AP void *clientData in
 Arbitrary one-word value passed to \fIproc\fR, \fInreProc\fR, \fIdeleteProc\fR
 and \fIobjProc\fR.
 .AP Tcl_CmdDeleteProc *deleteProc in/out
@@ -72,10 +72,10 @@ Pointer to an unshared Tcl_Obj where the result of the evaluation is stored if
 the return code is TCL_OK.
 .AP Tcl_NRPostProc *postProcPtr in
 A function to push.
-.AP ClientData data0 in
-.AP ClientData data1 in
-.AP ClientData data2 in
-.AP ClientData data3 in
+.AP void *data0 in
+.AP void *data1 in
+.AP void *data2 in
+.AP void *data3 in
 \fIdata0\fR through \fIdata3\fR are four one-word values that will be passed
 to the function designated by \fIpostProcPtr\fR when it is invoked.
 .BE
@@ -130,7 +130,7 @@ a message as the interpreter's result.
 .CS
 typedef int
 \fBTcl_NRPostProc\fR(
-        \fBClientData\fR \fIdata\fR[],
+        \fBvoid *\fR \fIdata\fR[],
         \fBTcl_Interp\fR *\fIinterp\fR,
         int \fIresult\fR);
 .CE
@@ -146,7 +146,7 @@ stack, to evalute a script:
 .CS
 int
 \fITheCmdOldObjProc\fR(
-    ClientData clientData,
+    void *clientData,
     Tcl_Interp *interp,
     int objc,
     Tcl_Obj *const objv[])
@@ -177,7 +177,7 @@ call \fITheCmdNRObjProc\fR:
 .CS
 int
 \fITheCmdOldObjProc\fR(
-    ClientData clientData,
+    void *clientData,
     Tcl_Interp *interp,
     int objc,
     Tcl_Obj *const objv[])
@@ -190,7 +190,7 @@ int
 .CS
 int
 \fITheCmdNRObjProc\fR
-    ClientData clientData,
+    void *clientData,
     Tcl_Interp *interp,
     int objc,
     Tcl_Obj *const objv[])
@@ -211,7 +211,7 @@ int
 .CS
 int
 \fITheCmdNRPostProc\fR(
-    ClientData data[],
+    void *data[],
     Tcl_Interp *interp,
     int result)
 {

doc/Namespace.3

@@ -57,7 +57,7 @@ The interpreter in which the namespace exists and where name lookups
 are performed. Also where error result messages are written.
 .AP "const char" *name in
 The name of the namespace or command to be created or accessed.
-.AP ClientData clientData in
+.AP void *clientData in
 A context pointer by the creator of the namespace.  Not interpreted by
 Tcl at all.
 .AP Tcl_NamespaceDeleteProc *deleteProc in
@@ -117,7 +117,7 @@ the global namespace.)
 .PP
 .CS
 typedef void \fBTcl_NamespaceDeleteProc\fR(
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 .CE
 .PP
 \fBTcl_DeleteNamespace\fR deletes a namespace, calling the

doc/Notifier.3

@@ -38,7 +38,7 @@ Tcl_ThreadId
 void
 \fBTcl_DeleteEvents\fR(\fIdeleteProc, clientData\fR)
 .sp
-ClientData
+void *
 \fBTcl_InitNotifier\fR()
 .sp
 void
@@ -78,7 +78,7 @@ Procedure to invoke to prepare for event wait in \fBTcl_DoOneEvent\fR.
 Procedure for \fBTcl_DoOneEvent\fR to invoke after waiting for
 events.  Checks to see if any events have occurred and, if so,
 queues them.
-.AP ClientData clientData in
+.AP void *clientData in
 Arbitrary one-word value to pass to \fIsetupProc\fR, \fIcheckProc\fR, or
 \fIdeleteProc\fR.
 .AP "const Tcl_Time" *timePtr in
@@ -89,7 +89,7 @@ is NULL, it means there is no maximum wait time:  wait forever if
 necessary.
 .AP Tcl_Event *evPtr in
 An event to add to the event queue.  The storage for the event must
-have been allocated by the caller using \fBTcl_Alloc\fR or \fBckalloc\fR.
+have been allocated by the caller using \fBTcl_Alloc\fR.
 .AP Tcl_QueuePosition position in
 Where to add the new event in the queue:  \fBTCL_QUEUE_TAIL\fR,
 \fBTCL_QUEUE_HEAD\fR, or \fBTCL_QUEUE_MARK\fR.
@@ -230,7 +230,7 @@ the event source.
 .PP
 .CS
 typedef void \fBTcl_EventSetupProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
         int \fIflags\fR);
 .CE
 .PP
@@ -308,7 +308,7 @@ following prototype:
 .PP
 .CS
 typedef void \fBTcl_EventCheckProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
         int \fIflags\fR);
 .CE
 .PP
@@ -399,7 +399,7 @@ of window events.
 When \fIproc\fR returns 1, \fBTcl_ServiceEvent\fR will remove the
 event from the event queue and free its storage.
 Note that the storage for an event must be allocated by
-the event source (using \fBTcl_Alloc\fR or the Tcl macro \fBckalloc\fR)
+the event source (using \fBTcl_Alloc\fR)
 before calling \fBTcl_QueueEvent\fR, but it
 will be freed by \fBTcl_ServiceEvent\fR, not by the event source.
 .PP
@@ -428,7 +428,7 @@ queue.  \fIProc\fR should match the following prototype:
 .CS
 typedef int \fBTcl_EventDeleteProc\fR(
         Tcl_Event *\fIevPtr\fR,
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 .CE
 .PP
 The \fIclientData\fR argument will be the same as the \fIclientData\fR

doc/Object.3

@@ -111,9 +111,9 @@ which is defined as follows.
 .PP
 .CS
 typedef struct Tcl_Obj {
-    int \fIrefCount\fR;
+    size_t \fIrefCount\fR;
     char *\fIbytes\fR;
-    int \fIlength\fR;
+    size_t \fIlength\fR;
     const Tcl_ObjType *\fItypePtr\fR;
     union {
         long \fIlongValue\fR;

doc/ObjectType.3

@@ -186,8 +186,8 @@ to be treated as conventional null character-terminated C strings.
 These restrictions are easily met by using Tcl's internal UTF encoding
 for the string representation, same as one would do for other
 Tcl routines accepting string values as arguments.
-Storage for the byte array must be allocated in the heap by \fBTcl_Alloc\fR
-or \fBckalloc\fR.  Note that \fIupdateStringProc\fRs must allocate
+Storage for the byte array must be allocated in the heap by \fBTcl_Alloc\fR.
+Note that \fIupdateStringProc\fRs must allocate
 enough storage for the string's bytes and the terminating null byte.
 .PP
 The \fIupdateStringProc\fR for Tcl's built-in double type, for example,

doc/OpenFileChnl.3

@@ -53,28 +53,28 @@ int
 int
 \fBTcl_Read\fR(\fIchannel, readBuf, bytesToRead\fR)
 .sp
-int
+size_t
 \fBTcl_GetsObj\fR(\fIchannel, lineObjPtr\fR)
 .sp
-int
+size_t
 \fBTcl_Gets\fR(\fIchannel, lineRead\fR)
 .sp
-int
+size_t
 \fBTcl_Ungets\fR(\fIchannel, input, inputLen, addAtEnd\fR)
 .sp
-int
+size_t
 \fBTcl_WriteObj\fR(\fIchannel, writeObjPtr\fR)
 .sp
-int
+size_t
 \fBTcl_WriteChars\fR(\fIchannel, charBuf, bytesToWrite\fR)
 .sp
-int
+size_t
 \fBTcl_Write\fR(\fIchannel, byteBuf, bytesToWrite\fR)
 .sp
-int
+size_t
 \fBTcl_ReadRaw\fR(\fIchannel, readBuf, bytesToRead\fR)
 .sp
-int
+size_t
 \fBTcl_WriteRaw\fR(\fIchannel, byteBuf, bytesToWrite\fR)
 .sp
 int
@@ -134,7 +134,7 @@ input of the invoking process; likewise for \fBTCL_STDOUT\fR and
 redirect stdio handles to override the stdio handles for which
 \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR and \fBTCL_STDERR\fR have been set.  If it
 is set, then such redirections cause an error.
-.AP ClientData handle in
+.AP void *handle in
 Operating system specific handle for I/O to a file. For Unix this is a
 file descriptor, for Windows it is a HANDLE.
 .AP int readOrWrite in
@@ -154,7 +154,7 @@ from a procedure such as \fBTcl_OpenFileChannel\fR.
 .AP Tcl_Obj *readObjPtr in/out
 A pointer to a Tcl value in which to store the characters read from the
 channel.
-.AP int charsToRead in
+.AP size_t charsToRead in
 The number of characters to read from the channel.  If the channel's encoding
 is \fBbinary\fR, this is equivalent to the number of bytes to read from the
 channel.
@@ -163,7 +163,7 @@ If non-zero, data read from the channel will be appended to the value.
 Otherwise, the data will replace the existing contents of the value.
 .AP char *readBuf out
 A buffer in which to store the bytes read from the channel.
-.AP int bytesToRead in
+.AP size_t bytesToRead in
 The number of bytes to read from the channel.  The buffer \fIreadBuf\fR must
 be large enough to hold this many bytes.
 .AP Tcl_Obj *lineObjPtr in/out
@@ -176,7 +176,7 @@ channel.  Must have been initialized by the caller.  The line read will be
 appended to any data already in the dynamic string.
 .AP "const char" *input in
 The input to add to a channel buffer.
-.AP int inputLen in
+.AP size_t inputLen in
 Length of the input
 .AP int addAtEnd in
 Flag indicating whether the input should be added to the end or
@@ -187,7 +187,7 @@ A pointer to a Tcl value whose contents will be output to the channel.
 A buffer containing the characters to output to the channel.
 .AP "const char" *byteBuf in
 A buffer containing the bytes to output to the channel.
-.AP int bytesToWrite in
+.AP size_t bytesToWrite in
 The number of bytes to consume from \fIcharBuf\fR or \fIbyteBuf\fR and
 output to the channel.
 .AP Tcl_WideInt offset in

doc/OpenTcp.3

@@ -50,12 +50,12 @@ If nonzero, the client socket is connected asynchronously to the server.
 .AP "unsigned int" flags in
 ORed combination of \fBTCL_TCPSERVER\fR flags that specify additional
 informations about the socket being created.
-.AP ClientData sock in
+.AP void *sock in
 Platform-specific handle for client TCP socket.
 .AP Tcl_TcpAcceptProc *proc in
 Pointer to a procedure to invoke each time a new connection is
 accepted via the socket.
-.AP ClientData clientData in
+.AP void *clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .BE
 .SH DESCRIPTION
@@ -127,7 +127,7 @@ the channel. \fIProc\fR must match the following prototype:
 .PP
 .CS
 typedef void \fBTcl_TcpAcceptProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
         Tcl_Channel \fIchannel\fR,
         char *\fIhostName\fR,
         int \fIport\fR);

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_SetPanicProc, Tcl_ConsolePanic \- report fatal error and abort
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -16,10 +16,10 @@ void
 \fBTcl_Panic\fR(\fIformat\fR, \fIarg\fR, \fIarg\fR, \fI...\fR)
 .sp
 void
-\fBTcl_PanicVA\fR(\fIformat\fR, \fIargList\fR)
+\fBTcl_SetPanicProc\fR(\fIpanicProc\fR)
 .sp
 void
-\fBTcl_SetPanicProc\fR(\fIpanicProc\fR)
+\fBTcl_ConsolePanic\fR(\fIformat\fR, \fIarg\fR, \fIarg\fR, \fI...\fR)
 .sp
 .SH ARGUMENTS
 .AS Tcl_PanicProc *panicProc
@@ -54,6 +54,14 @@ message is sent to the debugger in stead. 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 (in stead 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:
@@ -80,9 +88,6 @@ 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
 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.
 .SH "SEE ALSO"
 abort(3), printf(3), exec(n), format(n)
 .SH KEYWORDS

doc/ParseArgs.3

@@ -31,7 +31,7 @@ The array of arguments to be parsed.
 Pointer to a variable that will hold the array of unprocessed arguments.
 Should be NULL if no return of unprocessed arguments is required. If
 \fIobjcPtr\fR is updated to a non-zero value, the array returned through this
-must be deallocated using \fBckfree\fR.
+must be deallocated using \fBTcl_Free\fR.
 .BE
 .SH DESCRIPTION
 .PP
@@ -84,7 +84,7 @@ typedef struct {
     void *\fIsrcPtr\fR;
     void *\fIdstPtr\fR;
     const char *\fIhelpStr\fR;
-    ClientData \fIclientData\fR;
+    void *\fIclientData\fR;
 } \fBTcl_ArgvInfo\fR;
 .CE
 .PP
@@ -127,7 +127,7 @@ have the following signature:
 .PP
 .CS
 typedef int (\fBTcl_ArgvFuncProc\fR)(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
         Tcl_Obj *\fIobjPtr\fR,
         void *\fIdstPtr\fR);
 .CE
@@ -149,7 +149,7 @@ function will have the following signature:
 .PP
 .CS
 typedef int (\fBTcl_ArgvGenFuncProc\fR)(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
         Tcl_Interp *\fIinterp\fR,
         int \fIobjc\fR,
         Tcl_Obj *const *\fIobjv\fR,

doc/ParseCmd.3

@@ -8,7 +8,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_ParseCommand, Tcl_ParseExpr, Tcl_ParseBraces, Tcl_ParseQuotedString, Tcl_ParseVarName, Tcl_ParseVar, Tcl_FreeParse, Tcl_EvalTokens, Tcl_EvalTokensStandard \- parse Tcl scripts and expressions
+Tcl_ParseCommand, Tcl_ParseExpr, Tcl_ParseBraces, Tcl_ParseQuotedString, Tcl_ParseVarName, Tcl_ParseVar, Tcl_FreeParse, Tcl_EvalTokensStandard \- parse Tcl scripts and expressions
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -33,20 +33,16 @@ const char *
 .sp
 \fBTcl_FreeParse\fR(\fIusedParsePtr\fR)
 .sp
-Tcl_Obj *
-\fBTcl_EvalTokens\fR(\fIinterp, tokenPtr, numTokens\fR)
-.sp
 int
 \fBTcl_EvalTokensStandard\fR(\fIinterp, tokenPtr, numTokens\fR)
 .SH ARGUMENTS
 .AS Tcl_Interp *usedParsePtr out
 .AP Tcl_Interp *interp out
-For procedures other than \fBTcl_FreeParse\fR, \fBTcl_EvalTokens\fR
-and \fBTcl_EvalTokensStandard\fR, used only for error reporting;
+For procedures other than \fBTcl_FreeParse\fR and
+\fBTcl_EvalTokensStandard\fR, used only for error reporting;
 if NULL, then no error messages are left after errors.
-For \fBTcl_EvalTokens\fR and \fBTcl_EvalTokensStandard\fR,
-determines the context for evaluating the
-script and also is used for error reporting; must not be NULL.
+For \fBTcl_EvalTokensStandard\fR, determines the context for evaluating
+the script and also is used for error reporting; must not be NULL.
 .AP "const char" *start in
 Pointer to first character in string to parse.
 .AP int numBytes in
@@ -191,16 +187,6 @@ 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.
-.PP
-\fBTcl_EvalTokens\fR differs from \fBTcl_EvalTokensStandard\fR only in
-the return convention used: it returns the result in a new Tcl_Obj.
-The reference count of the value returned as result has been
-incremented, so the caller must
-invoke \fBTcl_DecrRefCount\fR when it is finished with the value.
-If an error or other exception occurs while evaluating the tokens
-(such as a reference to a non-existent variable) then the return value
-is NULL and an error message is left in \fIinterp\fR's result. The use
-of \fBTcl_EvalTokens\fR is deprecated.
 .SH "TCL_PARSE STRUCTURE"
 .PP
 \fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR,
@@ -222,8 +208,8 @@ typedef struct Tcl_Parse {
 typedef struct Tcl_Token {
     int \fItype\fR;
     const char *\fIstart\fR;
-    int \fIsize\fR;
-    int \fInumComponents\fR;
+    size_t \fIsize\fR;
+    size_t \fInumComponents\fR;
 } \fBTcl_Token\fR;
 .CE
 .PP

doc/Preserve.3

@@ -21,7 +21,7 @@ Tcl_Preserve, Tcl_Release, Tcl_EventuallyFree \- avoid freeing storage while it
 \fBTcl_EventuallyFree\fR(\fIclientData, freeProc\fR)
 .SH ARGUMENTS
 .AS Tcl_FreeProc clientData
-.AP ClientData clientData in
+.AP void *clientData in
 Token describing structure to be freed or reallocated.  Usually a pointer
 to memory for structure.
 .AP Tcl_FreeProc *freeProc in
@@ -91,7 +91,7 @@ reasons, but the value is the same.
 .PP
 When the \fIclientData\fR argument to \fBTcl_EventuallyFree\fR
 refers to storage allocated and returned by a prior call to
-\fBTcl_Alloc\fR, \fBckalloc\fR, or another function of the Tcl library,
+\fBTcl_Alloc\fR or another function of the Tcl library,
 then the \fIfreeProc\fR argument should be given the special value of
 \fBTCL_DYNAMIC\fR.
 .PP

doc/PrintDbl.3

@@ -18,10 +18,7 @@ Tcl_PrintDouble \- Convert floating value to string
 .SH ARGUMENTS
 .AS Tcl_Interp *interp out
 .AP Tcl_Interp *interp in
-Before Tcl 8.0, the \fBtcl_precision\fR variable in this interpreter
-controlled the conversion.  As of Tcl 8.0, this argument is ignored and
-the conversion is controlled by the \fBtcl_precision\fR variable
-that is now shared by all interpreters.
+This argument is ignored.
 .AP double value in
 Floating-point value to be converted.
 .AP char *dst out
@@ -41,9 +38,7 @@ so that it does not look like an integer.  Where \fB%g\fR would
 generate an integer with no decimal point, \fBTcl_PrintDouble\fR adds
 .QW .0 .
 .PP
-If the \fBtcl_precision\fR value is non-zero, the result will have
-precisely that many digits of significance.  If the value is zero
-(the default), the result will have the fewest digits needed to
+The result will have the fewest digits needed to
 represent the number in such a way that \fBTcl_NewDoubleObj\fR
 will generate the same number when presented with the given string.
 IEEE semantics of rounding to even apply to the conversion.

doc/RecEvalObj.3

@@ -31,7 +31,7 @@ the command at global level instead of the current stack level.
 .SH DESCRIPTION
 .PP
 \fBTcl_RecordAndEvalObj\fR is invoked to record a command as an event
-on the history list and then execute it using \fBTcl_EvalObjEx\fR
+on the history list and then execute it using \fBTcl_EvalObjEx\fR.
 It returns a completion code such as \fBTCL_OK\fR just like \fBTcl_EvalObjEx\fR,
 as well as a result value containing additional information
 (a result value or error message)

doc/SaveResult.3

@@ -1,6 +1,7 @@
 '\"
 '\" Copyright (c) 1997 by 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.
@@ -9,7 +10,9 @@
 .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
+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
@@ -30,91 +33,53 @@ int
 .SH ARGUMENTS
 .AS Tcl_InterpState savedPtr
 .AP Tcl_Interp *interp in
-Interpreter for which state should be saved.
+The interpreter for the operation.
 .AP int status in
-Return code value to save as part of interpreter state.
+The return code for the state.
 .AP Tcl_InterpState state in
-Saved state token to be restored or discarded.
+A token for saved state.
 .AP Tcl_SavedResult *savedPtr in
-Pointer to location where interpreter result should be saved or restored.
+A pointer to storage for saved state.
 .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.
+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
-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.
+\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
-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).
+\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
-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.
+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_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.
+\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_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.
+\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_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_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 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_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
-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.
+If a saved result is not restored, \fBTcl_DiscardResult\fR must be called to
+release it.
 .SH KEYWORDS
 result, state, interp

doc/SetRecLmt.3

@@ -29,7 +29,7 @@ New limit for nested calls to \fBTcl_Eval\fR for \fIinterp\fR.
 .PP
 At any given time Tcl enforces a limit on the number of recursive
 calls that may be active for \fBTcl_Eval\fR and related procedures
-such as \fBTcl_GlobalEval\fR.
+such as \fBTcl_EvalEx\fR.
 Any call to \fBTcl_Eval\fR that exceeds this depth is aborted with
 an error.
 By default the recursion limit is 1000.

doc/SetResult.3

@@ -9,7 +9,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult, Tcl_AppendResult, Tcl_AppendResultVA, Tcl_AppendElement, Tcl_ResetResult, Tcl_TransferResult, Tcl_FreeResult \- manipulate Tcl result
+Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult, Tcl_AppendResult, Tcl_AppendElement, Tcl_ResetResult, Tcl_TransferResult, Tcl_FreeResult \- manipulate Tcl result
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -26,8 +26,6 @@ const char *
 .sp
 \fBTcl_AppendResult\fR(\fIinterp, result, result, ... , \fB(char *) NULL\fR)
 .sp
-\fBTcl_AppendResultVA\fR(\fIinterp, argList\fR)
-.sp
 \fBTcl_ResetResult\fR(\fIinterp\fR)
 .sp
 .VS 8.6
@@ -152,9 +150,6 @@ extensions.
 Any number of \fIresult\fR arguments may be passed in a single
 call; the last argument in the list must be a NULL pointer.
 .PP
-\fBTcl_AppendResultVA\fR is the same as \fBTcl_AppendResult\fR except that
-instead of taking a variable number of arguments it takes an argument list.
-.PP
 .VS 8.6
 \fBTcl_TransferResult\fR moves a result from one interpreter to another,
 optionally (dependent on the \fIresult\fR parameter) including the error
@@ -197,19 +192,6 @@ It also sets \fIinterp->freeProc\fR to zero, but does not
 change \fIinterp->result\fR or clear error state.
 \fBTcl_FreeResult\fR is most commonly used when a procedure
 is about to replace one result value with another.
-.SS "DIRECT ACCESS TO INTERP->RESULT"
-.PP
-It used to be legal for programs to
-directly read and write \fIinterp->result\fR
-to manipulate the interpreter result.  The Tcl headers no longer
-permit this access by default, and 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

doc/SplitList.3

@@ -20,16 +20,16 @@ int
 char *
 \fBTcl_Merge\fR(\fIargc, argv\fR)
 .sp
-int
+size_t
 \fBTcl_ScanElement\fR(\fIsrc, flagsPtr\fR)
 .sp
-int
+size_t
 \fBTcl_ScanCountedElement\fR(\fIsrc, length, flagsPtr\fR)
 .sp
-int
+size_t
 \fBTcl_ConvertElement\fR(\fIsrc, dst, flags\fR)
 .sp
-int
+size_t
 \fBTcl_ConvertCountedElement\fR(\fIsrc, length, dst, flags\fR)
 .SH ARGUMENTS
 .AS "const char *const" ***argvPtr out
@@ -55,7 +55,7 @@ String that is to become an element of a list.
 .AP int *flagsPtr in
 Pointer to word to fill in with information about \fIsrc\fR.
 The value of *\fIflagsPtr\fR must be passed to \fBTcl_ConvertElement\fR.
-.AP int length in
+.AP size_t length in
 Number of bytes in string \fIsrc\fR.
 .AP char *dst in
 Place to copy converted list element.  Must contain enough characters

doc/StringObj.3

@@ -8,7 +8,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_NewStringObj, Tcl_NewUnicodeObj, Tcl_SetStringObj, Tcl_SetUnicodeObj, Tcl_GetStringFromObj, Tcl_GetString, Tcl_GetUnicodeFromObj, Tcl_GetUnicode, Tcl_GetUniChar, Tcl_GetCharLength, Tcl_GetRange, Tcl_AppendToObj, Tcl_AppendUnicodeToObj, Tcl_AppendObjToObj, Tcl_AppendStringsToObj, Tcl_AppendStringsToObjVA, Tcl_AppendLimitedToObj, Tcl_Format, Tcl_AppendFormatToObj, Tcl_ObjPrintf, Tcl_AppendPrintfToObj, Tcl_SetObjLength, Tcl_AttemptSetObjLength, Tcl_ConcatObj \- manipulate Tcl values as strings
+Tcl_NewStringObj, Tcl_NewUnicodeObj, Tcl_SetStringObj, Tcl_SetUnicodeObj, Tcl_GetStringFromObj, Tcl_GetString, Tcl_GetUnicodeFromObj, Tcl_GetUnicode, Tcl_GetUniChar, Tcl_GetCharLength, Tcl_GetRange, Tcl_AppendToObj, Tcl_AppendUnicodeToObj, Tcl_AppendObjToObj, Tcl_AppendStringsToObj, Tcl_AppendLimitedToObj, Tcl_Format, Tcl_AppendFormatToObj, Tcl_ObjPrintf, Tcl_AppendPrintfToObj, Tcl_SetObjLength, Tcl_AttemptSetObjLength, Tcl_ConcatObj \- manipulate Tcl values as strings
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -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
@@ -59,9 +59,6 @@ void
 \fBTcl_AppendStringsToObj\fR(\fIobjPtr, string, string, ... \fB(char *) NULL\fR)
 .sp
 void
-\fBTcl_AppendStringsToObjVA\fR(\fIobjPtr, argList\fR)
-.sp
-void
 \fBTcl_AppendLimitedToObj\fR(\fIobjPtr, bytes, length, limit, ellipsis\fR)
 .sp
 Tcl_Obj *
@@ -90,29 +87,29 @@ Tcl_Obj *
 Points to the first byte of an array of UTF-8-encoded bytes
 used to set or append to a string value.
 This byte array may contain embedded null characters
-unless \fInumChars\fR is negative.  (Applications needing null bytes
+unless \fInumChars\fR is (size_t)-1.  (Applications needing null bytes
 should represent them as the two-byte sequence \fI\e700\e600\fR, use
 \fBTcl_ExternalToUtf\fR to convert, or \fBTcl_NewByteArrayObj\fR if
 the string is a collection of uninterpreted bytes.)
-.AP int length in
+.AP size_t length in
 The number of bytes to copy from \fIbytes\fR when
 initializing, setting, or appending to a string value.
-If negative, all bytes up to the first null are used.
+If (size_t)-1, all bytes up to the first null are used.
 .AP "const Tcl_UniChar" *unicode in
 Points to the first byte of an array of Unicode characters
 used to set or append to a string value.
 This byte array may contain embedded null characters
 unless \fInumChars\fR is negative.
-.AP int numChars in
+.AP size_t numChars in
 The number of Unicode characters to copy from \fIunicode\fR when
 initializing, setting, or appending to a string value.
-If negative, all characters up to the first null character are used.
-.AP int index in
+If (size_t)-1, all characters up to the first null character are used.
+.AP size_t index in
 The index of the Unicode character to return.
-.AP int first in
+.AP size_t first in
 The index of the first Unicode character in the Unicode range to be
 returned as a new value.
-.AP int last in
+.AP size_t last in
 The index of the last Unicode character in the Unicode range to be
 returned as a new value.
 .AP Tcl_Obj *objPtr in/out
@@ -127,7 +124,7 @@ Null-terminated string value to append to \fIobjPtr\fR.
 .AP va_list argList in
 An argument list which must have been initialized using
 \fBva_start\fR, and cleared using \fBva_end\fR.
-.AP int limit in
+.AP size_t limit in
 Maximum number of bytes to be appended.
 .AP "const char" *ellipsis in
 Suffix to append when the limit leads to string truncation.
@@ -140,7 +137,7 @@ Format control string including % conversion specifiers.
 The number of elements to format or concatenate.
 .AP Tcl_Obj *objv[] in
 The array of values to format or concatenate.
-.AP int newLength in
+.AP size_t newLength in
 New length for the string value of \fIobjPtr\fR, not including the
 final null character.
 .BE
@@ -204,7 +201,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.
+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
@@ -246,10 +244,6 @@ values may contain internal null characters).  Any number of
 \fIstring\fR arguments may be provided, but the last argument
 must be a NULL pointer to indicate the end of the list.
 .PP
-\fBTcl_AppendStringsToObjVA\fR is the same as \fBTcl_AppendStringsToObj\fR
-except that instead of taking a variable number of arguments it takes an
-argument list.
-.PP
 \fBTcl_AppendLimitedToObj\fR is similar to \fBTcl_AppendToObj\fR
 except that it imposes a limit on how many bytes are appended.
 This can be handy when the string to be appended might be

doc/TCL_MEM_DEBUG.3

@@ -34,7 +34,7 @@ and the Tcl \fBmemory\fR command can be used to validate and examine
 memory usage.
 .SH "GUARD ZONES"
 .PP
-When memory debugging is enabled, whenever a call to \fBckalloc\fR is
+When memory debugging is enabled, whenever a call to \fBTcl_Alloc\fR is
 made, slightly more memory than requested is allocated so the memory
 debugging code can keep track of the allocated memory, and eight-byte
 .QW "guard zones"
@@ -44,7 +44,7 @@ C #define \fBLOW_GUARD_SIZE\fR and #define \fBHIGH_GUARD_SIZE\fR
 in the file \fIgeneric/tclCkalloc.c\fR \(em it can
 be extended if you suspect large overwrite problems, at some cost in
 performance.)  A known pattern is written into the guard zones and, on
-a call to \fBckfree\fR, the guard zones of the space being freed are
+a call to \fBTcl_Free\fR, the guard zones of the space being freed are
 checked to see if either zone has been modified in any way.  If one
 has been, the guard bytes and their new contents are identified, and a
 .QW "low guard failed"
@@ -53,7 +53,7 @@ or
 message is issued.  The
 .QW "guard failed"
 message includes the address of the memory packet and
-the file name and line number of the code that called \fBckfree\fR.
+the file name and line number of the code that called \fBTcl_Free\fR.
 This allows you to detect the common sorts of one-off problems, where
 not enough space was allocated to contain the data written, for
 example.
@@ -66,15 +66,15 @@ suspect (or know) that corruption is occurring before the Tcl
 interpreter comes up far enough for you to issue commands, you can set
 \fBMEM_VALIDATE\fR define, recompile tclCkalloc.c and rebuild Tcl.
 This will enable memory validation from the first call to
-\fBckalloc\fR, again, at a large performance impact.
+\fBTcl_Alloc\fR, again, at a large performance impact.
 .PP
 If you are desperate and validating memory on every call to
-\fBckalloc\fR and \fBckfree\fR is not enough, you can explicitly call
+\fBTcl_Alloc\fR and \fBTcl_Free\fR is not enough, you can explicitly call
 \fBTcl_ValidateAllMemory\fR directly at any point.  It takes a \fIchar
 *\fR and an \fIint\fR which are normally the filename and line number
 of the caller, but they can actually be anything you want.  Remember
 to remove the calls after you find the problem.
 .SH "SEE ALSO"
-ckalloc, memory, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory
+Tcl_Alloc, memory, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory
 .SH KEYWORDS
 memory, debug

doc/TclZlib.3

@@ -88,7 +88,7 @@ The initial value for the checksum algorithm.
 .AP "unsigned char" *bytes in
 An array of bytes to run the checksum algorithm over, or NULL to get the
 recommended initial value for the checksum algorithm.
-.AP int length in
+.AP size_t length in
 The number of bytes in the array.
 .AP int mode in
 What mode to operate the stream in. Should be either
@@ -107,8 +107,8 @@ if the currently compressed data must be made available for access using
 into a state where the decompressor can recover from on corruption, or
 \fBTCL_ZLIB_FINALIZE\fR to ensure that the stream is finished and that any
 trailer demanded by the format is written.
-.AP int count in
-The maximum number of bytes to get from the stream, or -1 to get all remaining
+.AP size_t count in
+The maximum number of bytes to get from the stream, or (size_t)-1 to get all remaining
 bytes from the stream's buffers.
 .AP Tcl_Obj *compDict in
 A byte array value that is the compression dictionary to use with the stream.

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.
@@ -65,7 +67,7 @@ Id of the thread waited upon.
 .AP Tcl_ThreadCreateProc *proc in
 This procedure will act as the \fBmain()\fR of the newly created
 thread. The specified \fIclientData\fR will be its sole argument.
-.AP ClientData clientData in
+.AP void *clientData in
 Arbitrary information. Passed as sole argument to the \fIproc\fR.
 .AP int stackSize in
 The size of the stack given to the new thread.
@@ -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.
@@ -202,7 +208,7 @@ value and then finishes.
 .CS
 static \fBTcl_ThreadCreateType\fR
 MyThreadImplFunc(
-    ClientData clientData)
+    void *clientData)
 {
     int i, limit = (int) clientData;
     for (i=0 ; i<limit ; i++) {
@@ -217,7 +223,7 @@ would do this:
 .PP
 .CS
 int limit = 1000000000;
-ClientData limitData = (void*)((intptr_t) limit);
+void *limitData = (void*)((intptr_t) limit);
 Tcl_ThreadId id;    \fI/* holds identity of thread created */\fR
 int result;
 

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

doc/TraceCmd.3

@@ -13,7 +13,7 @@ Tcl_CommandTraceInfo, Tcl_TraceCommand, Tcl_UntraceCommand \- monitor renames an
 .nf
 \fB#include <tcl.h>\fR
 .sp
-ClientData
+void *
 \fBTcl_CommandTraceInfo(\fIinterp, cmdName, flags, proc, prevClientData\fB)\fR
 .sp
 int
@@ -32,9 +32,9 @@ OR'ed collection of the values \fBTCL_TRACE_RENAME\fR and
 \fBTCL_TRACE_DELETE\fR.
 .AP Tcl_CommandTraceProc *proc in
 Procedure to call when specified operations occur to \fIcmdName\fR.
-.AP ClientData clientData in
+.AP void *clientData in
 Arbitrary argument to pass to \fIproc\fR.
-.AP ClientData prevClientData in
+.AP void *prevClientData in
 If non-NULL, gives last value returned by \fBTcl_CommandTraceInfo\fR,
 so this call will return information about next trace.  If NULL, this
 call will return information about first trace.
@@ -65,7 +65,7 @@ match the type \fBTcl_CommandTraceProc\fR:
 .PP
 .CS
 typedef void \fBTcl_CommandTraceProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
         Tcl_Interp *\fIinterp\fR,
         const char *\fIoldName\fR,
         const char *\fInewName\fR,
@@ -74,7 +74,7 @@ typedef void \fBTcl_CommandTraceProc\fR(
 .PP
 The \fIclientData\fR and \fIinterp\fR parameters will have the same
 values as those passed to \fBTcl_TraceCommand\fR when the trace was
-created.  \fIClientData\fR typically points to an application-specific
+created.  \fIclientData\fR typically points to an application-specific
 data structure that describes what to do when \fIproc\fR is invoked.
 \fIOldName\fR gives the name of the command being renamed, and
 \fInewName\fR gives the name that the command is being renamed to (or

doc/TraceVar.3

@@ -24,13 +24,13 @@ int
 .sp
 \fBTcl_UntraceVar2(\fIinterp, name1, name2, flags, proc, clientData\fB)\fR
 .sp
-ClientData
+void *
 \fBTcl_VarTraceInfo(\fIinterp, varName, flags, proc, prevClientData\fB)\fR
 .sp
-ClientData
+void *
 \fBTcl_VarTraceInfo2(\fIinterp, name1, name2, flags, proc, prevClientData\fB)\fR
 .SH ARGUMENTS
-.AS Tcl_VarTraceProc prevClientData
+.AS void *prevClientData
 .AP Tcl_Interp *interp in
 Interpreter containing variable.
 .AP "const char" *varName in
@@ -46,7 +46,7 @@ Not all flags are used by all
 procedures.  See below for more information.
 .AP Tcl_VarTraceProc *proc in
 Procedure to invoke whenever one of the traced operations occurs.
-.AP ClientData clientData in
+.AP void *clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .AP "const char" *name1 in
 Name of scalar or array variable (without array index).
@@ -54,7 +54,7 @@ Name of scalar or array variable (without array index).
 For a trace on an element of an array, gives the index of the
 element.  For traces on scalar variables or on whole arrays,
 is NULL.
-.AP ClientData prevClientData in
+.AP void *prevClientData in
 If non-NULL, gives last value returned by \fBTcl_VarTraceInfo\fR or
 \fBTcl_VarTraceInfo2\fR, so this call will return information about
 next trace.  If NULL, this call will return information about first
@@ -107,7 +107,7 @@ before an array set, but that will trigger write traces.
 \fBTCL_TRACE_RESULT_DYNAMIC\fR
 The result of invoking the \fIproc\fR is a dynamically allocated
 string that will be released by the Tcl library via a call to
-\fBckfree\fR.  Must not be specified at the same time as
+\fBTcl_Free\fR.  Must not be specified at the same time as
 \fBTCL_TRACE_RESULT_OBJECT\fR.
 .TP
 \fBTCL_TRACE_RESULT_OBJECT\fR
@@ -124,7 +124,7 @@ It should have arguments and result that match the type
 .PP
 .CS
 typedef char *\fBTcl_VarTraceProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
         Tcl_Interp *\fIinterp\fR,
         char *\fIname1\fR,
         char *\fIname2\fR,
@@ -134,7 +134,7 @@ typedef char *\fBTcl_VarTraceProc\fR(
 The \fIclientData\fR and \fIinterp\fR parameters will
 have the same values as those passed to \fBTcl_TraceVar\fR when the
 trace was created.
-\fIClientData\fR typically points to an application-specific
+\fIclientData\fR typically points to an application-specific
 data structure that describes what to do when \fIproc\fR
 is invoked.
 \fIName1\fR and \fIname2\fR give the name of the traced variable
@@ -312,7 +312,7 @@ The return value must be a pointer to a static character string
 containing an error message,
 unless (\fIexactly\fR one of) the \fBTCL_TRACE_RESULT_DYNAMIC\fR and
 \fBTCL_TRACE_RESULT_OBJECT\fR flags is set, which specify that the result is
-either a dynamic string (to be released with \fBckfree\fR) or a
+either a dynamic string (to be released with \fBTcl_Free\fR) or a
 Tcl_Obj* (cast to char* and to be released with
 \fBTcl_DecrRefCount\fR) containing the error message.
 If a trace procedure returns an error, no further traces are

doc/Utf.3

@@ -31,19 +31,19 @@ int
 \fBTcl_UniCharLen\fR(\fIuniStr\fR)
 .sp
 int
-\fBTcl_UniCharNcmp\fR(\fIucs, uct, numChars\fR)
+\fBTcl_UniCharNcmp\fR(\fIucs, uct, uniLength\fR)
 .sp
 int
-\fBTcl_UniCharNcasecmp\fR(\fIucs, uct, numChars\fR)
+\fBTcl_UniCharNcasecmp\fR(\fIucs, uct, uniLength\fR)
 .sp
 int
 \fBTcl_UniCharCaseMatch\fR(\fIuniStr, uniPattern, nocase\fR)
 .sp
 int
-\fBTcl_UtfNcmp\fR(\fIcs, ct, numChars\fR)
+\fBTcl_UtfNcmp\fR(\fIcs, ct, length\fR)
 .sp
 int
-\fBTcl_UtfNcasecmp\fR(\fIcs, ct, numChars\fR)
+\fBTcl_UtfNcasecmp\fR(\fIcs, ct, length\fR)
 .sp
 int
 \fBTcl_UtfCharComplete\fR(\fIsrc, length\fR)
@@ -63,13 +63,13 @@ const char *
 const char *
 \fBTcl_UtfPrev\fR(\fIsrc, start\fR)
 .sp
-Tcl_UniChar
+int
 \fBTcl_UniCharAtIndex\fR(\fIsrc, index\fR)
 .sp
 const char *
 \fBTcl_UtfAtIndex\fR(\fIsrc, index\fR)
 .sp
-int
+size_t
 \fBTcl_UtfBackslash\fR(\fIsrc, readPtr, dst\fR)
 .SH ARGUMENTS
 .AS "const Tcl_UniChar" *uniPattern in/out
@@ -94,19 +94,16 @@ A null-terminated Unicode string.
 A null-terminated Unicode string.
 .AP "const Tcl_UniChar" *uniPattern in
 A null-terminated Unicode string.
-.AP int length in
+.AP size_t 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.
+(size_t)-1, all bytes up to the first null byte are used.
+.AP size_t uniLength in
+The length of the Unicode string in characters.
 .AP "Tcl_DString" *dsPtr in/out
 A pointer to a previously initialized \fBTcl_DString\fR.
-.AP "unsigned long" numChars in
-The number of characters to compare.
 .AP "const char" *start in
 Pointer to the beginning of a UTF-8 string.
-.AP int index in
+.AP size_t index in
 The index of a character (not byte) in the UTF-8 string.
 .AP int *readPtr out
 If non-NULL, filled with the number of bytes in the backslash sequence,
@@ -121,8 +118,8 @@ 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
+These routines convert between UTF-8 strings and Unicode characters.  An
+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.
@@ -130,9 +127,12 @@ sequence consists of a lead byte followed by some number of trail bytes.
 \fBTCL_UTF_MAX\fR is the maximum number of bytes that it takes to
 represent one Unicode character in the UTF-8 representation.
 .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 an upper surrogate (range U+D800 - U+DBFF), then
+the return value will be 0 and nothing 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 using 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,6 +140,9 @@ 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 0x0000 and
 0x00ff and return 1.
@@ -169,7 +172,7 @@ the number of Unicode characters (not bytes) in that string.
 \fBTcl_UniCharNcmp\fR and \fBTcl_UniCharNcasecmp\fR correspond to
 \fBstrncmp\fR and \fBstrncasecmp\fR, respectively, for Unicode characters.
 They accept two null-terminated Unicode strings and the number of characters
-to compare.  Both strings are assumed to be at least \fInumChars\fR characters
+to compare.  Both strings are assumed to be at least \fIuniLength\fR characters
 long. \fBTcl_UniCharNcmp\fR  compares the two strings character-by-character
 according to the Unicode character ordering.  It returns an integer greater
 than, equal to, or less than 0 if the first string is greater than, equal
@@ -183,7 +186,7 @@ be case sensitive and returns whether the string matches the pattern.
 .PP
 \fBTcl_UtfNcmp\fR corresponds to \fBstrncmp\fR for UTF-8 strings. It
 accepts two null-terminated UTF-8 strings and the number of characters
-to compare.  (Both strings are assumed to be at least \fInumChars\fR
+to compare.  (Both strings are assumed to be at least \fIlength\fR
 characters long.)  \fBTcl_UtfNcmp\fR compares the two strings
 character-by-character according to the Unicode character ordering.
 It returns an integer greater than, equal to, or less than 0 if the
@@ -200,7 +203,7 @@ of \fIlength\fR bytes is long enough to be decoded by
 \fBTcl_UtfToUniChar\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.
+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 +211,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
@@ -235,12 +238,12 @@ return value will be \fIstart\fR.
 Pascal Ord() function.  It returns the Tcl_UniChar 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.
 .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_UtfNext\fR \fIindex\fR times.  If a negative \fIindex\fR is given,
+\fBTcl_UtfNext\fR \fIindex\fR times.  If \fIindex\fR is (size_t)-1,
 the return pointer points to the first character in the source string.
 .PP
 \fBTcl_UtfBackslash\fR is a utility procedure used by several of the Tcl

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 TclOO
+
+\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 \farrayName\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/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 TclOO
+
+\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/case.n

@@ -1,60 +0,0 @@
-'\"
-'\" Copyright (c) 1993 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\"
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\"
-.TH case n 7.0 Tcl "Tcl Built-In Commands"
-.so man.macros
-.BS
-'\" Note:  do not modify the .SH NAME line immediately below!
-.SH NAME
-case \- Evaluate one of several scripts, depending on a given value
-.SH SYNOPSIS
-\fBcase\fI string \fR?\fBin\fR? \fIpatList body \fR?\fIpatList body \fR...?
-.sp
-\fBcase\fI string \fR?\fBin\fR? {\fIpatList body \fR?\fIpatList body \fR...?}
-.BE
-
-.SH DESCRIPTION
-.PP
-\fINote: the \fBcase\fI command is obsolete and is supported only
-for backward compatibility.  At some point in the future it may be
-removed entirely.  You should use the \fBswitch\fI command instead.\fR
-.PP
-The \fBcase\fR command matches \fIstring\fR against each of
-the \fIpatList\fR arguments in order.
-Each \fIpatList\fR argument is a list of one or
-more patterns.  If any of these patterns matches \fIstring\fR then
-\fBcase\fR evaluates the following \fIbody\fR argument
-by passing it recursively to the Tcl interpreter and returns the result
-of that evaluation.
-Each \fIpatList\fR argument consists of a single
-pattern or list of patterns.  Each pattern may contain any of the wild-cards
-described under \fBstring match\fR.  If a \fIpatList\fR
-argument is \fBdefault\fR, the corresponding body will be evaluated
-if no \fIpatList\fR matches \fIstring\fR.  If no \fIpatList\fR argument
-matches \fIstring\fR and no default is given, then the \fBcase\fR
-command returns an empty string.
-.PP
-Two syntaxes are provided for the \fIpatList\fR and \fIbody\fR arguments.
-The first uses a separate argument for each of the patterns and commands;
-this form is convenient if substitutions are desired on some of the
-patterns or commands.
-The second form places all of the patterns and commands together into
-a single argument; the argument must have proper list structure, with
-the elements of the list being the patterns and commands.
-The second form makes it easy to construct multi-line case commands,
-since the braces around the whole list make it unnecessary to include a
-backslash at the end of each line.
-Since the \fIpatList\fR arguments are in braces in the second form,
-no command or variable substitutions are performed on them;  this makes
-the behavior of the second form different than the first form in some
-cases.
-
-.SH "SEE ALSO"
-switch(n)
-
-.SH KEYWORDS
-case, match, regular expression

doc/cd.n

@@ -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/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 TclOO
+
+\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

@@ -452,6 +452,19 @@ If this situation occurs, the first occurrence of the time is chosen.
 (For this reason, it is wise to have the input string contain the
 time zone when converting local times.  This caveat does not apply to
 UTC times.)
+.PP
+If the interpretation of the groups yields an impossible time because
+a field is out of range, enough of that field's unit will be added to
+or subtracted from the time to bring it in range. Thus, if attempting to
+scan or format day 0 of the month, one day will be subtracted from day
+1 of the month, yielding the last day of the previous month.
+.PP
+If the interpretation of the groups yields an impossible time because
+a Daylight Saving Time change skips over that time, or an ambiguous
+time because a Daylight Saving Time change skips back so that the clock
+observes the given time twice, and no time zone specifier (\fB%z\fR
+or \fB%Z\fR) is present in the format, the time is interpreted as
+if the clock had not changed.
 .SH "FORMAT GROUPS"
 .PP
 The following format groups are recognized by the \fBclock scan\fR and

doc/define.n

@@ -1,5 +1,5 @@
 '\"
-'\" Copyright (c) 2007 Donal K. Fellows
+'\" Copyright (c) 2007-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.
@@ -39,6 +39,27 @@ used as the \fIdefScript\fR argument.
 The following commands are supported in the \fIdefScript\fR for
 \fBoo::define\fR, each of which may also be used in the \fIsubcommand\fR form:
 .TP
+\fBclassmethod\fI name\fR ?\fIargList bodyScrip\fR?
+.VS TIP478
+This creates a class method, or (if \fIargList\fR and \fIbodyScript\fR are
+omitted) promotes an existing method on the class object to be a class
+method. The \fIname\fR, \fIargList\fR and \fIbodyScript\fR arguments are as in
+the \fBmethod\fR definition, below.
+.RS
+.PP
+Class methods can be called on either the class itself or on the instances of
+that class. When they are called, the current object (see the \fBself\R and
+\fBmy\fR commands) is the class on which they are called or the class of the
+instance on which they are called, depending on whether they are called on the
+class or an instance of the class, respectively. If called on a subclass or
+instance of the subclass, the current object is the subclass.
+.PP
+In a private definition context, the methods as invoked on classes are
+\fInot\fR private, but the methods as invoked on instances of classes are
+private.
+.RE
+.VE TIP478
+.TP
 \fBconstructor\fI argList bodyScript\fR
 .
 This creates or updates the constructor for a class. The formal arguments to
@@ -50,7 +71,7 @@ being constructed. Within the constructor, the \fBnext\fR command should be
 used to call the superclasses' constructors. If \fIbodyScript\fR is the empty
 string, the constructor will be deleted.
 .TP
-\fBdeletemethod\fI name\fR ?\fIname ...\fR
+\fBdeletemethod\fI name\fR ?\fIname ...\fR?
 .
 This deletes each of the methods called \fIname\fR from a class. The methods
 must have previously existed in that class. Does not affect the superclasses
@@ -82,17 +103,14 @@ by a superclass; subclass exports override superclass visibility, and may in
 turn be overridden by instances.
 .TP
 \fBfilter\fR ?\fI\-slotOperation\fR? ?\fImethodName ...\fR?
-.VS
+.
 This slot (see \fBSLOTTED DEFINITIONS\fR below)
-.VE
 sets or updates the list of method names that are used to guard whether
 method call to instances of the class may be called and what the method's
 results are. Each \fImethodName\fR names a single filtering method (which may
 be exposed or not exposed); it is not an error for a non-existent method to be
 named since they may be defined by subclasses.
-.VS
 By default, this slot works by appending.
-.VE
 .TP
 \fBforward\fI name cmdName \fR?\fIarg ...\fR?
 .
@@ -105,6 +123,22 @@ fully-qualified, the command will be searched for in each object's namespace,
 using the instances' namespace's path, or by looking in the global namespace.
 The method will be exported if \fIname\fR starts with a lower-case letter, and
 non-exported otherwise.
+.RS
+.PP
+.VS TIP500
+If in a private definition context (see the \fBprivate\fR definition command,
+below), this command creates private forwarded methods.
+.VE TIP500
+.RE
+.TP
+\fBinitialise\fI script\fR
+.TP
+\fBinitialize\fI script\fR
+.VS TIP478
+This evaluates \fIscript\fR in a context which supports local variables and
+where the current namespace is the instance namespace of the class object
+itself. This is useful for setting up, e.g., class-scoped variables.
+.VE TIP478
 .TP
 \fBmethod\fI name argList bodyScript\fR
 .
@@ -117,17 +151,40 @@ be a namespace that is unique to the current object. The method will be
 exported if \fIname\fR starts with a lower-case letter, and non-exported
 otherwise; this behavior can be overridden via \fBexport\fR and
 \fBunexport\fR.
+.RS
+.PP
+.VS TIP500
+If in a private definition context (see the \fBprivate\fR definition command,
+below), this command creates private procedure-like methods.
+.VE TIP500
+.RE
 .TP
 \fBmixin\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR?
-.VS
+.
 This slot (see \fBSLOTTED DEFINITIONS\fR below)
-.VE
 sets or updates the list of additional classes that are to be mixed into
 all the instances of the class being defined. Each \fIclassName\fR argument
 names a single class that is to be mixed in.
-.VS
 By default, this slot works by replacement.
-.VE
+.TP
+\fBprivate \fIcmd arg...\fR
+.TP
+\fBprivate \fIscript\fR
+.
+.VS TIP500
+This evaluates the \fIscript\fR (or the list of command and arguments given by
+\fIcmd\fR and \fIarg\fRs) in a context where the definitions made on the
+current class will be private definitions.
+.RS
+.PP
+The following class definition commands are affected by \fBprivate\fR:
+\fBforward\fR, \fBmethod\fR, \fBself\fR, and \fBvariable\fR. Nesting
+\fBprivate\fR inside \fBprivate\fR has no cumulative effect; the innermost
+definition context is just a private definition context. All other definition
+commands have no difference in behavior when used in a private definition
+context.
+.RE
+.VE TIP500
 .TP
 \fBrenamemethod\fI fromName toName\fR
 .
@@ -159,21 +216,23 @@ operates identically to
 If no arguments at all are used, this gives the name of the class currently
 being configured.
 .VE TIP470
+.VS TIP500
+If in a private definition context (see the \fBprivate\fR definition command,
+below), the definitions on the class object will also be made in a private
+definition context.
+.VE TIP500
 .RE
 .TP
 \fBsuperclass\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR?
-.VS
+.
 This slot (see \fBSLOTTED DEFINITIONS\fR below)
-.VE
 allows the alteration of the superclasses of the class being defined.
 Each \fIclassName\fR argument names one class that is to be a superclass of
 the defined class. Note that objects must not be changed from being classes to
 being non-classes or vice-versa, that an empty parent class is equivalent to
 \fBoo::object\fR, and that the parent classes of \fBoo::object\fR and
 \fBoo::class\fR may not be modified.
-.VS
 By default, this slot works by replacement.
-.VE
 .TP
 \fBunexport\fI name \fR?\fIname ...\fR?
 .
@@ -185,18 +244,31 @@ actually defined by a superclass; subclass unexports override superclass
 visibility, and may be overridden by instance unexports.
 .TP
 \fBvariable\fR ?\fI\-slotOperation\fR? ?\fIname ...\fR?
-.VS
+.
 This slot (see \fBSLOTTED DEFINITIONS\fR below) arranges for each of the named
 variables to be automatically made
 available in the methods, constructor and destructor declared by the class
 being defined. Each variable name must not have any namespace
 separators and must not look like an array access. All variables will be
-actually present in the instance object on which the method is executed. Note
+actually present in the namespace of the instance object on which the method
+is executed. Note
 that the variable lists declared by a superclass or subclass are completely
 disjoint, as are variable lists declared by instances; the list of variable
 names is just for methods (and constructors and destructors) declared by this
 class. By default, this slot works by appending.
-.VE
+.RS
+.PP
+.VS TIP500
+If in a private definition context (see the \fBprivate\fR definition command,
+below), this slot manipulates the list of private variable bindings for this
+class. In a private variable binding, the name of the variable within the
+instance object is different to the name given in the definition; the name
+used in the definition is the name that you use to access the variable within
+the methods of this class, and the name of the variable in the instance
+namespace has a unique prefix that makes accidental use from other classes
+extremely unlikely.
+.VE TIP500
+.RE
 .SS "CONFIGURING OBJECTS"
 .PP
 The following commands are supported in the \fIdefScript\fR for
@@ -223,18 +295,15 @@ being defined. Note that the methods themselves may be actually defined by a
 class or superclass; object exports override class visibility.
 .TP
 \fBfilter\fR ?\fI\-slotOperation\fR? ?\fImethodName ...\fR?
-.VS
+.
 This slot (see \fBSLOTTED DEFINITIONS\fR below)
-.VE
 sets or updates the list of method names that are used to guard whether a
 method call to the object may be called and what the method's results are.
 Each \fImethodName\fR names a single filtering method (which may be exposed or
 not exposed); it is not an error for a non-existent method to be named. Note
 that the actual list of filters also depends on the filters set upon any
 classes that the object is an instance of.
-.VS
 By default, this slot works by appending.
-.VE
 .TP
 \fBforward\fI name cmdName \fR?\fIarg ...\fR?
 .
@@ -244,6 +313,13 @@ additional arguments, \fIarg\fR etc., added before those arguments specified
 by the caller of the method. Forwarded methods should be deleted using the
 \fBmethod\fR subcommand. The method will be exported if \fIname\fR starts with
 a lower-case letter, and non-exported otherwise.
+.RS
+.PP
+.VS TIP500
+If in a private definition context (see the \fBprivate\fR definition command,
+below), this command creates private forwarded methods.
+.VE TIP500
+.RE
 .TP
 \fBmethod\fI name argList bodyScript\fR
 .
@@ -254,17 +330,38 @@ method will be \fIbodyScript\fR. When the body of the method is evaluated, the
 current namespace of the method will be a namespace that is unique to the
 object. The method will be exported if \fIname\fR starts with a lower-case
 letter, and non-exported otherwise.
+.RS
+.PP
+.VS TIP500
+If in a private definition context (see the \fBprivate\fR definition command,
+below), this command creates private procedure-like methods.
+.VE TIP500
+.RE
 .TP
 \fBmixin\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR?
-.VS
+.
 This slot (see \fBSLOTTED DEFINITIONS\fR below)
-.VE
 sets or updates a per-object list of additional classes that are to be
 mixed into the object. Each argument, \fIclassName\fR, names a single class
 that is to be mixed in.
-.VS
 By default, this slot works by replacement.
-.VE
+.TP
+\fBprivate \fIcmd arg...\fR
+.TP
+\fBprivate \fIscript\fR
+.VS TIP500
+This evaluates the \fIscript\fR (or the list of command and arguments given by
+\fIcmd\fR and \fIarg\fRs) in a context where the definitions made on the
+current object will be private definitions.
+.RS
+.PP
+The following class definition commands are affected by \fBprivate\fR:
+\fBforward\fR, \fBmethod\fR, and \fBvariable\fR. Nesting \fBprivate\fR inside
+\fBprivate\fR has no cumulative effect; the innermost definition context is
+just a private definition context. All other definition commands have no
+difference in behavior when used in a private definition context.
+.RE
+.VE TIP500
 .TP
 \fBrenamemethod\fI fromName toName\fR
 .
@@ -275,7 +372,6 @@ that the object is an instance of. Does not change the export status of the
 method; if it was exported before, it will be afterwards.
 .TP
 \fBself \fR
-.
 .VS TIP470
 This gives the name of the object currently being configured.
 .VE TIP470
@@ -289,36 +385,70 @@ object being defined. Note that the methods themselves may be actually defined
 by a class; instance unexports override class visibility.
 .TP
 \fBvariable\fR ?\fI\-slotOperation\fR? ?\fIname ...\fR?
-.VS
+.
 This slot (see \fBSLOTTED DEFINITIONS\fR below) arranges for each of the named
 variables to be automatically made available in the methods declared by the
 object being defined.  Each variable name must not have any namespace
 separators and must not look like an array access. All variables will be
-actually present in the object on which the method is executed. Note that the
+actually present in the namespace of the object on which the method is
+executed. Note that the
 variable lists declared by the classes and mixins of which the object is an
 instance are completely disjoint; the list of variable names is just for
 methods declared by this object. By default, this slot works by appending.
+.RS
+.PP
+.VS TIP500
+If in a private definition context (see the \fBprivate\fR definition command,
+below), this slot manipulates the list of private variable bindings for this
+object.  In a private variable binding, the name of the variable within the
+instance object is different to the name given in the definition; the name
+used in the definition is the name that you use to access the variable within
+the methods of this instance object, and the name of the variable in the
+instance namespace has a unique prefix that makes accidental use from
+superclass methods extremely unlikely.
+.VE TIP500
+.RE
+.SH "PRIVATE METHODS"
+.VS TIP500
+When a class or instance has a private method, that private method can only be
+invoked from within methods of that class or instance. Other callers of the
+object's methods \fIcannot\fR invoke private methods, it is as if the private
+methods do not exist. However, a private method of a class \fIcan\fR be
+invoked from the class's methods when those methods are being used on another
+instance object; this means that a class can use them to coordinate behaviour
+between several instances of itself without interfering with how other
+classes (especially either subclasses or superclasses) interact. Private
+methods precede all mixed in classes in the method call order (as reported by
+\fBself call\fR).
+.VE TIP500
 .SH "SLOTTED DEFINITIONS"
 Some of the configurable definitions of a class or object are \fIslotted
 definitions\fR. This means that the configuration is implemented by a slot
 object, that is an instance of the class \fBoo::Slot\fR, which manages a list
 of values (class names, variable names, etc.) that comprises the contents of
-the slot. The class defines three operations (as methods) that may be done on
+the slot. The class defines five operations (as methods) that may be done on
 the slot:
-.VE
 .TP
 \fIslot\fR \fB\-append\fR ?\fImember ...\fR?
-.VS
+.
 This appends the given \fImember\fR elements to the slot definition.
-.VE
 .TP
 \fIslot\fR \fB\-clear\fR
-.VS
+.
 This sets the slot definition to the empty list.
-.VE
+.TP
+\fIslot\fR \fB\-prepend\fR ?\fImember ...\fR?
+.VS TIP516
+This prepends the given \fImember\fR elements to the slot definition.
+.VE TIP516
+.TP
+\fIslot\fR \fB\-remove\fR ?\fImember ...\fR?
+.VS TIP516
+This removes the given \fImember\fR elements from the slot definition.
+.VE TIP516
 .TP
 \fIslot\fR \fB\-set\fR ?\fImember ...\fR?
-.VS
+.
 This replaces the slot definition with the given \fImember\fR elements.
 .PP
 A consequence of this is that any use of a slot's default operation where the
@@ -331,20 +461,55 @@ which is forwarded to the default operation of the slot (thus, for the class
 slot, this is forwarded to
 .QW "\fBmy \-append\fR" ),
 and these methods which provide the implementation interface:
-.VE
 .TP
 \fIslot\fR \fBGet\fR
-.VS
-Returns a list that is the current contents of the slot. This method must
-always be called from a stack frame created by a call to \fBoo::define\fR or
-\fBoo::objdefine\fR.
-.VE
+.
+Returns a list that is the current contents of the slot, but does not modify
+the slot. This method must always be called from a stack frame created by a
+call to \fBoo::define\fR or \fBoo::objdefine\fR. This method \fIshould not\fR
+return an error unless it is called from outside a definition context or with
+the wrong number of arguments.
+.RS
+.PP
+.VS TIP516
+The elements of the list should be fully resolved, if that is a meaningful
+concept to the slot.
+.VE TIP516
+.RE
+.TP
+\fIslot\fR \fBResolve\fR \fIslotElement\fR
+.VS TIP516
+Returns \fIslotElement\fR with a resolution operation applied to it, but does
+not modify the slot. For slots of simple strings, this is an operation that
+does nothing, whereas for slots of classes, this maps a class name to its
+fully-qualified class name.  This method must always be called from a stack
+frame created by a call to \fBoo::define\fR or \fBoo::objdefine\fR.  This
+method \fIshould not\fR return an error unless it is called from outside a
+definition context or with the wrong number of arguments; unresolvable
+arguments should be returned as is (as not all slot operations strictly
+require that values are resolvable to work).
+.RS
+.PP
+Implementations \fIshould not\fR enforce uniqueness and ordering constraints
+in this method; that is the responsibility of the \fBSet\fR method.
+.RE
+.VE TIP516
 .TP
 \fIslot\fR \fBSet \fIelementList\fR
-.VS
+.
 Sets the contents of the slot to the list \fIelementList\fR and returns the
 empty string. This method must always be called from a stack frame created by
-a call to \fBoo::define\fR or \fBoo::objdefine\fR.
+a call to \fBoo::define\fR or \fBoo::objdefine\fR. This method may return an
+error if it rejects the change to the slot contents (e.g., because of invalid
+values) as well as if it is called from outside a definition context or with
+the wrong number of arguments.
+.RS
+.PP
+This method \fImay\fR reorder and filter the elements if this is necessary in
+order to satisfy the underlying constraints of the slot. (For example, slots
+of classes enforce a uniqueness constraint that places each element in the
+earliest location in the slot that it can.)
+.RE
 .PP
 The implementation of these methods is slot-dependent (and responsible for
 accessing the correct part of the class or object definition). Slots also have
@@ -352,11 +517,18 @@ an unknown method handler to tie all these pieces together, and they hide
 their \fBdestroy\fR method so that it is not invoked inadvertently. It is
 \fIrecommended\fR that any user changes to the slot mechanism be restricted to
 defining new operations whose names start with a hyphen.
-.VE
+.PP
+.VS TIP516
+Most slot operations will initially \fBResolve\fR their argument list, combine
+it with the results of the \fBGet\fR method, and then \fBSet\fR the result.
+Some operations omit one or both of the first two steps; omitting the third
+would result in an idempotent read-only operation (but the standard mechanism
+for reading from slots is via \fBinfo class\fR and \fBinfo object\fR).
+.VE TIP516
 .SH EXAMPLES
 This example demonstrates how to use both forms of the \fBoo::define\fR and
 \fBoo::objdefine\fR commands (they work in the same way), as well as
-illustrating four of the subcommands of them.
+illustrating four of their subcommands.
 .PP
 .CS
 oo::class create c
@@ -409,6 +581,84 @@ oo::class create B {
 inst m1              \fI\(-> prints "red brick"\fR
 inst m2              \fI\(-> prints "blue brick"\fR
 .CE
+.PP
+.VS TIP478
+This example shows how to create and use class variables. It is a class that
+counts how many instances of itself have been made.
+.PP
+.CS
+oo::class create Counted
+\fBoo::define\fR Counted {
+    \fBinitialise\fR {
+        variable count 0
+    }
+
+    \fBvariable\fR number
+    \fBconstructor\fR {} {
+        classvariable count
+        set number [incr count]
+    }
+
+    \fBmethod\fR report {} {
+        classvariable 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
+.PP
+This example demonstrates how to use class methods. (Note that the constructor
+for \fBoo::class\fR calls \fBoo::define\fR on the class.)
+.PP
+.CS
+oo::class create DBTable {
+    \fBclassmethod\fR find {description} {
+        puts "DB: locate row from [self] matching $description"
+        return [my new]
+    }
+    \fBclassmethod\fR insert {description} {
+        puts "DB: create row in [self] matching $description"
+        return [my new]
+    }
+    \fBmethod\fR update {description} {
+        puts "DB: update row [self] with $description"
+    }
+    \fBmethod\fR delete {} {
+        puts "DB: delete row [self]"
+        my destroy; # Just delete the object, not the DB row
+    }
+}
+
+oo::class create Users {
+    \fBsuperclass\fR DBTable
+}
+oo::class create Groups {
+    \fBsuperclass\fR DBTable
+}
+
+set u1 [Users insert "username=abc"]
+        \fI\(-> DB: create row from ::Users matching username=abc\fR
+set u2 [Users insert "username=def"]
+        \fI\(-> DB: create row from ::Users matching username=def\fR
+$u2 update "group=NULL"
+        \fI\(-> DB: update row ::oo::Obj124 with group=NULL\fR
+$u1 delete
+        \fI\(-> DB: delete row ::oo::Obj123\fR
+set g [Group find "groupname=webadmins"]
+        \fI\(-> DB: locate row ::Group with groupname=webadmins\fR
+$g update "emailaddress=admins"
+        \fI\(-> DB: update row ::oo::Obj125 with emailaddress=admins\fR
+.CE
+.VE TIP478
 .SH "SEE ALSO"
 next(n), oo::class(n), oo::object(n)
 .SH KEYWORDS

doc/dict.n

@@ -27,6 +27,11 @@ key maps to in the dictionary value contained in the given variable,
 writing the resulting dictionary value back to that variable.
 Non-existent keys are treated as if they map to an empty string. The
 updated dictionary value is returned.
+.VS TIP508
+If \fIdictionaryVarable\fR indicates an element that does not exist of an
+array that has a default value set, the default value and will be used as the
+value of the dictionary prior to the appending operation.
+.VE TIP508
 .TP
 \fBdict create \fR?\fIkey value ...\fR?
 .
@@ -124,6 +129,11 @@ resulting dictionary value back to that variable. Non-existent keys
 are treated as if they map to 0. It is an error to increment a value
 for an existing key if that value is not an integer. The updated
 dictionary value is returned.
+.VS TIP508
+If \fIdictionaryVarable\fR indicates an element that does not exist of an
+array that has a default value set, the default value and will be used as the
+value of the dictionary prior to the incrementing operation.
+.VE TIP508
 .TP
 \fBdict info \fIdictionaryValue\fR
 .
@@ -149,6 +159,11 @@ keys are treated as if they map to an empty list, and it is legal for
 there to be no items to append to the list. It is an error for the
 value that the key maps to to not be representable as a list. The
 updated dictionary value is returned.
+.VS TIP508
+If \fIdictionaryVarable\fR indicates an element that does not exist of an
+array that has a default value set, the default value and will be used as the
+value of the dictionary prior to the list-appending operation.
+.VE TIP508
 .TP
 \fBdict map \fR{\fIkeyVariable valueVariable\fR} \fIdictionaryValue body\fR
 .
@@ -206,6 +221,11 @@ value and places an updated dictionary value in that variable
 containing a mapping from the given key to the given value. When
 multiple keys are present, this operation creates or updates a chain
 of nested dictionaries. The updated dictionary value is returned.
+.VS TIP508
+If \fIdictionaryVarable\fR indicates an element that does not exist of an
+array that has a default value set, the default value and will be used as the
+value of the dictionary prior to the value insert/update operation.
+.VE TIP508
 .TP
 \fBdict size \fIdictionaryValue\fR
 .
@@ -221,6 +241,11 @@ through nested dictionaries to the mapping to remove. At least one key
 must be specified, but the last key on the key-path need not exist.
 All other components on the path must exist. The updated dictionary
 value is returned.
+.VS TIP508
+If \fIdictionaryVarable\fR indicates an element that does not exist of an
+array that has a default value set, the default value and will be used as the
+value of the dictionary prior to the value remove operation.
+.VE TIP508
 .TP
 \fBdict update \fIdictionaryVariable key varName \fR?\fIkey varName ...\fR? \fIbody\fR
 .
@@ -236,6 +261,11 @@ are silently discarded), even if the result of \fIbody\fR is an error
 or some other kind of exceptional exit. The result of \fBdict
 update\fR is (unless some kind of error occurs) the result of the
 evaluation of \fIbody\fR.
+.VS TIP508
+If \fIdictionaryVarable\fR indicates an element that does not exist of an
+array that has a default value set, the default value and will be used as the
+value of the dictionary prior to the update operation.
+.VE TIP508
 .RS
 .PP
 Each \fIvarName\fR is mapped in the scope enclosing the \fBdict update\fR;
@@ -270,6 +300,11 @@ dictionary be discarded, and this also happens if the contents of
 dictionaries no longer exists. The result of \fBdict with\fR is
 (unless some kind of error occurs) the result of the evaluation of
 \fIbody\fR.
+.VS TIP508
+If \fIdictionaryVarable\fR indicates an element that does not exist of an
+array that has a default value set, the default value and will be used as the
+value of the dictionary prior to the updating operation.
+.VE TIP508
 .RS
 .PP
 The variables are mapped in the scope enclosing the \fBdict with\fR;

doc/eof.n

@@ -59,3 +59,7 @@ while {1} {
 file(n), open(n), close(n), fblocked(n), Tcl_StandardChannels(3)
 .SH KEYWORDS
 channel, end of file
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:

doc/exec.n

@@ -217,6 +217,19 @@ information is instead sent to the console, if one is present, or is
 discarded.
 .RS
 .PP
+Note that the current escape resp. quoting of arguments for windows works only
+with executables using CommandLineToArgv, CRT-library or similar, as well as
+with the windows batch files (excepting the newline, see below).
+Although it is the common escape algorithm, but, in fact, the way how the
+executable parses the command-line (resp. splits it into single arguments)
+is decisive.
+.PP
+Unfortunately, there is currently no way to supply newline character within
+an argument to the batch files (\fB.cmd\fR or \fB.bat\fR) or to the command
+processor (\fBcmd.exe /c\fR), because this causes truncation of command-line
+(also the argument chain) on the first newline character.
+But it works properly with an executable (using CommandLineToArgv, etc).
+.PP
 The Tk console text widget does not provide real standard IO capabilities.
 Under Tk, when redirecting from standard input, all applications will see an
 immediate end-of-file; information redirected to standard output or standard
@@ -409,6 +422,10 @@ that sometimes pop up:
 With the file \fIcmp.bat\fR looking something like:
 .PP
 .CS
+@gcc %*
+.CE
+or like another variant using single parameters:
+.CS
 @gcc %1 %2 %3 %4 %5 %6 %7 %8 %9
 .CE
 .SS "WORKING WITH COMMAND BUILT-INS"

doc/exit.n

@@ -49,3 +49,7 @@ if {[catch {main} msg options]} {
 exec(n)
 .SH KEYWORDS
 abort, exit, process
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:

doc/expr.n

@@ -50,9 +50,7 @@ An integer operand may be specified in decimal (the normal case, the optional
 first two characters are \fB0d\fR), binary
 (the first two characters are \fB0b\fR), octal
 (the first two characters are \fB0o\fR), or hexadecimal
-(the first two characters are \fB0x\fR) form.  For
-compatibility with older Tcl releases, an operand that begins with \fB0\fR is
-interpreted as an octal integer even if the second character is not \fBo\fR.
+(the first two characters are \fB0x\fR) form.
 A floating-point number may be specified in any of several
 common decimal formats, and may use the decimal point \fB.\fR,
 \fBe\fR or \fBE\fR for scientific notation, and

doc/fblocked.n

@@ -65,3 +65,7 @@ vwait forever
 gets(n), open(n), read(n), socket(n), Tcl_StandardChannels(3)
 .SH KEYWORDS
 blocking, nonblocking
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:

doc/fileevent.n

@@ -154,3 +154,7 @@ fconfigure(n), gets(n), interp(n), puts(n), read(n), Tcl_StandardChannels(3)
 .SH KEYWORDS
 asynchronous I/O, blocking, channel, event handler, nonblocking, readable,
 script, writable.
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:

doc/filename.n

@@ -176,3 +176,7 @@ file(n), glob(n)
 .SH KEYWORDS
 current directory, absolute file name, relative file name,
 volume-relative file name, portability
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:

doc/flush.n

@@ -43,3 +43,7 @@ puts "Hello there, $name!"
 file(n), open(n), socket(n), Tcl_StandardChannels(3)
 .SH KEYWORDS
 blocking, buffer, channel, flush, nonblocking, output
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:

doc/foreach.n

@@ -102,3 +102,7 @@ for(n), while(n), break(n), continue(n)
 
 .SH KEYWORDS
 foreach, iteration, list, loop
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:

doc/global.n

@@ -56,3 +56,7 @@ proc accum {string} {
 namespace(n), upvar(n), variable(n)
 .SH KEYWORDS
 global, namespace, procedure, variable
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:

doc/history.n

@@ -100,3 +100,7 @@ the \fBevent\fR operation to retrieve some event,
 and the \fBadd\fR operation to add it to history and execute it.
 .SH KEYWORDS
 event, history, record
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:

doc/http.n

@@ -6,14 +6,14 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-.TH "http" n 2.7 http "Tcl Bundled Packages"
+.TH "http" n 2.9 http "Tcl Bundled Packages"
 .so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 http \- Client-side implementation of the HTTP/1.1 protocol
 .SH SYNOPSIS
-\fBpackage require http ?2.7?\fR
+\fBpackage require http ?2.8?\fR
 .\" See Also -useragent option documentation in body!
 .sp
 \fB::http::config ?\fI\-option value\fR ...?
@@ -22,6 +22,8 @@ http \- Client-side implementation of the HTTP/1.1 protocol
 .sp
 \fB::http::formatQuery\fR \fIkey value\fR ?\fIkey value\fR ...?
 .sp
+\fB::http::quoteString\fR \fIvalue\fR
+.sp
 \fB::http::reset\fR \fItoken\fR ?\fIwhy\fR?
 .sp
 \fB::http::wait \fItoken\fR
@@ -44,12 +46,14 @@ http \- Client-side implementation of the HTTP/1.1 protocol
 .sp
 \fB::http::register \fIproto port command\fR
 .sp
+\fB::http::registerError \fIport\fR ?\fImessage\fR?
+.sp
 \fB::http::unregister \fIproto\fR
 .BE
 .SH DESCRIPTION
 .PP
 The \fBhttp\fR package provides the client side of the HTTP/1.1
-protocol, as defined in RFC 2616.
+protocol, as defined in RFC 7230 to RFC 7235, which supersede RFC 2616.
 The package implements the GET, POST, and HEAD operations
 of HTTP/1.1.  It allows configuration of a proxy host to get through
 firewalls.  The package is compatible with the \fBSafesock\fR security
@@ -95,6 +99,19 @@ comma-separated list of mime type patterns that you are
 willing to receive.  For example,
 .QW "image/gif, image/jpeg, text/*" .
 .TP
+\fB\-pipeline\fR \fIboolean\fR
+.
+Specifies whether HTTP/1.1 transactions on a persistent socket will be
+pipelined.  See the \fBPERSISTENT SOCKETS\fR section for details. The default
+is 1.
+.TP
+\fB\-postfresh\fR \fIboolean\fR
+.
+Specifies whether requests that use the \fBPOST\fR method will always use a
+fresh socket, overriding the \fB-keepalive\fR option of
+command \fBhttp::geturl\fR.  See the \fBPERSISTENT SOCKETS\fR section for details.
+The default is 0.
+.TP
 \fB\-proxyhost\fR \fIhostname\fR
 .
 The name of the proxy host, if any.  If this value is the
@@ -116,20 +133,47 @@ an empty list.  The default filter returns the values of the
 \fB\-proxyhost\fR and \fB\-proxyport\fR settings if they are
 non-empty.
 .TP
+\fB\-repost\fR \fIboolean\fR
+.
+Specifies what to do if a POST request over a persistent connection fails
+because the server has half-closed the connection.  If boolean \fBtrue\fR, the
+request
+will be automatically retried; if boolean \fBfalse\fR it will not, and the
+application
+that uses \fBhttp::geturl\fR is expected to seek user confirmation before
+retrying the POST.  The value \fBtrue\fR should be used only under certain
+conditions. See the \fBPERSISTENT SOCKETS\fR section for details. The
+default is 0.
+.TP
 \fB\-urlencoding\fR \fIencoding\fR
 .
 The \fIencoding\fR used for creating the x-url-encoded URLs with
-\fB::http::formatQuery\fR.  The default is \fButf-8\fR, as specified by RFC
+\fB::http::formatQuery\fR and \fB::http::quoteString\fR.
+The default is \fButf-8\fR, as specified by RFC
 2718.  Prior to http 2.5 this was unspecified, and that behavior can be
 returned by specifying the empty string (\fB{}\fR), although
 \fIiso8859-1\fR is recommended to restore similar behavior but without the
-\fB::http::formatQuery\fR throwing an error processing non-latin-1
-characters.
+\fB::http::formatQuery\fR or \fB::http::quoteString\fR
+throwing an error processing non-latin-1 characters.
 .TP
 \fB\-useragent\fR \fIstring\fR
 .
-The value of the User-Agent header in the HTTP request.  The default is
-.QW "\fBTcl http client package 2.7\fR" .
+The value of the User-Agent header in the HTTP request.  In an unsafe
+interpreter, the default value depends upon the operating system, and
+the version numbers of \fBhttp\fR and \fBTcl\fR, and is (for example)
+.QW "\fBMozilla/5.0 (Windows; U; Windows NT 10.0) http/2.8.12 Tcl/8.6.8\fR" .
+A safe interpreter cannot determine its operating system, and so the default
+in a safe interpreter is to use a Windows 10 value with the current version
+numbers of \fBhttp\fR and \fBTcl\fR.
+.TP
+\fB\-zip\fR \fIboolean\fR
+.
+If the value is boolean \fBtrue\fR, then by default requests will send a header
+.QW "\fBAccept-Encoding: gzip,deflate,compress\fR" .
+If the value is boolean \fBfalse\fR, then by default this header will not be sent.
+In either case the default can be overridden for an individual request by
+supplying a custom \fBAccept-Encoding\fR header in the \fB-headers\fR option
+of \fBhttp::geturl\fR. The default is 1.
 .RE
 .TP
 \fB::http::geturl\fR \fIurl\fR ?\fIoptions\fR?
@@ -227,7 +271,7 @@ Pragma: no-cache
 .TP
 \fB\-keepalive\fR \fIboolean\fR
 .
-If true, attempt to keep the connection open for servicing
+If boolean \fBtrue\fR, attempt to keep the connection open for servicing
 multiple requests.  Default is 0.
 .TP
 \fB\-method\fR \fItype\fR
@@ -334,6 +378,11 @@ encodes the keys and values, and generates one string that has the
 proper & and = separators.  The result is suitable for the
 \fB\-query\fR value passed to \fB::http::geturl\fR.
 .TP
+\fB::http::quoteString\fR \fIvalue\fR
+.
+This procedure does x-url-encoding of string.  It takes a single argument and
+encodes it.
+.TP
 \fB::http::reset\fR \fItoken\fR ?\fIwhy\fR?
 .
 This command resets the HTTP transaction identified by \fItoken\fR, if any.
@@ -415,6 +464,17 @@ set token [::http::geturl https://my.secure.site/]
 .CE
 .RE
 .TP
+\fB::http::registerError\fR \fIport\fR ?\fImessage\fR?
+.
+This procedure allows a registered protocol handler to deliver an error
+message for use by \fBhttp\fR.  Calling this command does not raise an
+error. The command is useful when a registered protocol detects an problem
+(for example, an invalid TLS certificate) that will cause an error to
+propagate to \fBhttp\fR.  The command allows \fBhttp\fR to provide a
+precise error message rather than a general one.  The command returns the
+value provided by the last call with argument \fImessage\fR, or the empty
+string if no such call has been made.
+.TP
 \fB::http::unregister\fR \fIproto\fR
 .
 This procedure unregisters a protocol handler that was previously
@@ -504,6 +564,14 @@ The following elements of
 the array are supported:
 .RS
 .TP
+\fBbinary\fR
+.
+This is boolean \fBtrue\fR if (after decoding any compression specified
+by the
+.QW "Content-Encoding"
+response header) the HTTP response is binary.  It is boolean \fBfalse\fR
+if the HTTP response is text.
+.TP
 \fBbody\fR
 .
 The contents of the URL.  This will be empty if the \fB\-channel\fR
@@ -602,6 +670,106 @@ A copy of the \fBContent-Type\fR meta-data value.
 .
 The requested URL.
 .RE
+.SH "PERSISTENT CONNECTIONS"
+.PP
+.SS "BASICS"
+.PP
+See RFC 7230 Sec 6, which supersedes RFC 2616 Sec 8.1.
+.PP
+A persistent connection allows multiple HTTP/1.1 transactions to be
+carried over the same TCP connection.  Pipelining allows a
+client to make multiple requests over a persistent connection without
+waiting for each response.  The server sends responses in the same order
+that the requests were received.
+.PP
+If a POST request fails to complete, typically user confirmation is
+needed before sending the request again.  The user may wish to verify
+whether the server was modified by the failed POST request, before
+sending the same request again.
+.PP
+A HTTP request will use a persistent socket if the call to
+\fBhttp::geturl\fR has the option \fB-keepalive true\fR. It will use
+pipelining where permitted if the \fBhttp::config\fR option
+\fB-pipeline\fR is boolean \fBtrue\fR (its default value).
+.PP
+The http package maintains no more than one persistent connection to each
+server (i.e. each value of
+.QW "domain:port" ).
+If \fBhttp::geturl\fR is called to make a request over a persistent
+connection while the connection is busy with another request, the new
+request will be held in a queue until the connection is free.
+.PP
+The http package does not support HTTP/1.0 persistent connections
+controlled by the \fBKeep-Alive\fR header.
+.SS "SPECIAL CASES"
+.PP
+This subsection discusses issues related to closure of the
+persistent connection by the server, automatic retry of failed requests,
+the special treatment necessary for POST requests, and the options for
+dealing with these cases.
+.PP
+In accordance with RFC 7230, \fBhttp::geturl\fR does not pipeline
+requests that use the POST method.  If a POST uses a persistent
+connection and is not the first request on that connection,
+\fBhttp::geturl\fR waits until it has received the response for the previous
+request; or (if \fBhttp::config\fR option \fB-postfresh\fR is boolean \fBtrue\fR) it
+uses a new connection for each POST.
+.PP
+If the server is processing a number of pipelined requests, and sends a
+response header
+.QW "\fBConnection: close\fR"
+with one of the responses (other than the last), then subsequent responses
+are unfulfilled. \fBhttp::geturl\fR will send the unfulfilled requests again
+over a new connection.
+.PP
+A difficulty arises when a HTTP client sends a request over a persistent
+connection that has been idle for a while.  The HTTP server may
+half-close an apparently idle connection while the client is sending a
+request, but before the request arrives at the server: in this case (an
+.QW "asynchronous close event" )
+the request will fail.  The difficulty arises because the client cannot
+be certain whether the POST modified the state of the server.  For HEAD or
+GET requests, \fBhttp::geturl\fR opens another connection and retransmits
+the failed request. However, if the request was a POST, RFC 7230 forbids
+automatic retry by default, suggesting either user confirmation, or
+confirmation by user-agent software that has semantic understanding of
+the application.  The \fBhttp::config\fR option \fB-repost\fR allows for
+either possibility.
+.PP
+Asynchronous close events can occur only in a short interval of time.  The
+\fBhttp\fR package monitors each persistent connection for closure by the
+server.  Upon detection, the connection is also closed at the client end,
+and subsequent requests will use a fresh connection.
+.PP
+If the \fBhttp::geturl\fR command is called with option \fB-keepalive true\fR,
+then it will both try to use an existing persistent connection
+(if one is available), and it will send the server a
+.QW "\fBConnection: keep-alive\fR"
+request header asking to keep the connection open for future requests.
+.PP
+The \fBhttp::config\fR options \fB-pipeline\fR, \fB-postfresh\fR, and
+\fB-repost\fR relate to persistent connections.
+.PP
+Option \fB-pipeline\fR, if boolean \fBtrue\fR, will pipeline GET and HEAD requests
+made
+over a persistent connection.  POST requests will not be pipelined - if the
+POST is not the first transaction on the connection, its request will not
+be sent until the previous response has finished.  GET and HEAD requests
+made after a POST will not be sent until the POST response has been
+delivered, and will not be sent if the POST fails.
+.PP
+Option \fB-postfresh\fR, if boolean \fBtrue\fR, will override the \fBhttp::geturl\fR option
+\fB-keepalive\fR, and always open a fresh connection for a POST request.
+.PP
+Option \fB-repost\fR, if \fBtrue\fR, permits automatic retry of a POST request
+that fails because it uses a persistent connection that the server has
+half-closed (an
+.QW "asynchronous close event" ).
+Subsequent GET and HEAD requests in a failed pipeline will also be retried.
+\fIThe -repost option should be used only if the application understands
+that the retry is appropriate\fR - specifically, the application must know
+that if the failed POST successfully modified the state of the server, a repeat POST
+would have no adverse effect.
 .SH EXAMPLE
 .PP
 This example creates a procedure to copy a URL to a file while printing a

doc/incr.n

@@ -27,6 +27,11 @@ and also returned as result.
 Starting with the Tcl 8.5 release, the variable \fIvarName\fR passed
 to \fBincr\fR may be unset, and in that case, it will be set to
 the value \fIincrement\fR or to the default increment value of \fB1\fR.
+.VS TIP508
+If \fIvarName\fR indicate an element that does not exist of an array that has
+a default value set, the sum of the default value and the \fIincrement\fR (or
+1) will be stored in the array element.
+.VE TIP508
 .SH EXAMPLES
 .PP
 Add one to the contents of the variable \fIx\fR:
@@ -59,3 +64,7 @@ an error if it is not):
 expr(n), set(n)
 .SH KEYWORDS
 add, increment, variable, value
+.\" Local variables:
+.\" mode: nroff
+.\" fill-column: 78
+.\" End:

doc/info.n

@@ -35,16 +35,51 @@ Returns the body of procedure \fIprocname\fR.  \fIProcname\fR must be
 the name of a Tcl command procedure.
 .TP
 \fBinfo class\fI subcommand class\fR ?\fIarg ...\fR
-.VS 8.6
+.
 Returns information about the class, \fIclass\fR. The \fIsubcommand\fRs are
 described in \fBCLASS INTROSPECTION\fR below.
-.VE 8.6
 .TP
 \fBinfo cmdcount\fR
 .
 Returns a count of the total number of commands that have been invoked
 in this interpreter.
 .TP
+\fBinfo cmdtype \fIcommandName\fR
+.VS TIP426
+Returns a description of the kind of command named by \fIcommandName\fR.  The
+supported types are:
+.RS
+.IP \fBalias\fR
+Indicates that \fIcommandName\fR was created by \fBinterp alias\fR. Note that
+safe interpreters can only see a subset of aliases (specifically those between
+two commands within themselves).
+.IP \fBcoroutine\fR
+Indicates that \fIcommandName\fR was created by \fBcoroutine\fR.
+.IP \fBensemble\fR
+Indicates that \fIcommandName\fR was created by \fBnamespace ensemble\fR.
+.IP \fBimport\fR
+Indicates that \fIcommandName\fR was created by \fBnamespace import\fR.
+.IP \fBnative\fR
+Indicates that \fIcommandName\fR was created by the \fBTcl_CreateObjProc\fR
+interface directly without further registration of the type of command.
+.IP \fBobject\fR
+Indicates that \fIcommandName\fR is the public command that represents an
+instance of \fBoo::object\fR or one of its subclasses.
+.IP \fBprivateObject\fR
+Indicates that \fIcommandName\fR is the private command (\fBmy\fR by default)
+that represents an instance of \fBoo::object\fR or one of its subclasses.
+.IP \fBproc\fR
+Indicates that \fIcommandName\fR was created by \fBproc\fR.
+.IP \fBslave\fR
+Indicates that \fIcommandName\fR was created by \fBinterp create\fR.
+.IP \fBzlibStream\fR
+Indicates that \fIcommandName\fR was created by \fBzlib stream\fR.
+.PP
+There may be other registered types as well; this is a set that is extensible
+at the implementation level with \fBTcl_RegisterCommandTypeName\fR.
+.RE
+.VE TIP426
+.TP
 \fBinfo commands \fR?\fIpattern\fR?
 .
 If \fIpattern\fR is not specified,
@@ -78,11 +113,10 @@ command is not complete, the script can delay evaluating it until additional
 lines have been typed to complete the command.
 .TP
 \fBinfo coroutine\fR
-.VS 8.6
+.
 Returns the name of the currently executing \fBcoroutine\fR, or the empty
 string if either no coroutine is currently executing, or the current coroutine
 has been deleted (but has not yet returned or yielded since deletion).
-.VE 8.6
 .TP
 \fBinfo default \fIprocname arg varname\fR
 .
@@ -93,7 +127,7 @@ Otherwise it returns \fB1\fR and places the default value of \fIarg\fR
 into variable \fIvarname\fR.
 .TP
 \fBinfo errorstack \fR?\fIinterp\fR?
-.VS 8.6
+.
 Returns, in a form that is programmatically easy to parse, the function names
 and arguments at each level from the call stack of the last error in the given
 \fIinterp\fR, or in the current one if not specified.
@@ -118,7 +152,6 @@ options dictionary returned by 3-argument \fBcatch\fR; \fBinfo errorstack\fR
 is a convenient way of retrieving it for uncaught errors at top-level in an
 interactive \fBtclsh\fR.
 .RE
-.VE 8.6
 .TP
 \fBinfo exists \fIvarName\fR
 .
@@ -329,10 +362,9 @@ was invoked.  If Tcl was unable to identify the file, then an empty
 string is returned.
 .TP
 \fBinfo object\fI subcommand object\fR ?\fIarg ...\fR
-.VS 8.6
+.
 Returns information about the object, \fIobject\fR. The \fIsubcommand\fRs are
 described in \fBOBJECT INTROSPECTION\fR below.
-.VE 8.6
 .TP
 \fBinfo patchlevel\fR
 .
@@ -399,20 +431,22 @@ Note that a currently-visible variable may not yet
 if it has not
 been set (e.g. a variable declared but not set by \fBvariable\fR).
 .SS "CLASS INTROSPECTION"
-.VS 8.6
 .PP
 The following \fIsubcommand\fR values are supported by \fBinfo class\fR:
-.VE 8.6
 .TP
 \fBinfo class call\fI class method\fR
-.VS
+.
 Returns a description of the method implementations that are used to provide a
 stereotypical instance of \fIclass\fR's implementation of \fImethod\fR
 (stereotypical instances being objects instantiated by a class without having
 any object-specific definitions added). This consists of a list of lists of
 four elements, where each sublist consists of a word that describes the
 general type of method implementation (being one of \fBmethod\fR for an
-ordinary method, \fBfilter\fR for an applied filter, and \fBunknown\fR for a
+ordinary method, \fBfilter\fR for an applied filter,
+.VS TIP500
+\fBprivate\fR for a private method,
+.VE TIP500
+and \fBunknown\fR for a
 method that is invoked as part of unknown method handling), a word giving the
 name of the particular method invoked (which is always the same as
 \fImethod\fR for the \fBmethod\fR type, and
@@ -423,122 +457,149 @@ implementation (see \fBinfo class methodtype\fR).
 .RS
 .PP
 Note that there is no inspection of whether the method implementations
-actually use \fBnext\fR to transfer control along the call chain.
+actually use \fBnext\fR to transfer control along the call chain,
+.VS TIP500
+and the call chains that this command files do not actually contain private
+methods.
+.VE TIP500
 .RE
-.VE 8.6
 .TP
 \fBinfo class constructor\fI class\fR
-.VS 8.6
+.
 This subcommand returns a description of the definition of the constructor of
 class \fIclass\fR. The definition is described as a two element list; the first
 element is the list of arguments to the constructor in a form suitable for
 passing to another call to \fBproc\fR or a method definition, and the second
 element is the body of the constructor. If no constructor is present, this
 returns the empty list.
-.VE 8.6
 .TP
 \fBinfo class definition\fI class method\fR
-.VS 8.6
+.
 This subcommand returns a description of the definition of the method named
 \fImethod\fR of class \fIclass\fR. The definition is described as a two element
 list; the first element is the list of arguments to the method in a form
 suitable for passing to another call to \fBproc\fR or a method definition, and
 the second element is the body of the method.
-.VE 8.6
 .TP
 \fBinfo class destructor\fI class\fR
-.VS 8.6
+.
 This subcommand returns the body of the destructor of class \fIclass\fR. If no
 destructor is present, this returns the empty string.
-.VE 8.6
 .TP
 \fBinfo class filters\fI class\fR
-.VS 8.6
+.
 This subcommand returns the list of filter methods set on the class.
-.VE 8.6
 .TP
 \fBinfo class forward\fI class method\fR
-.VS 8.6
+.
 This subcommand returns the argument list for the method forwarding called
 \fImethod\fR that is set on the class called \fIclass\fR.
-.VE 8.6
 .TP
 \fBinfo class instances\fI class\fR ?\fIpattern\fR?
-.VS 8.6
+.
 This subcommand returns a list of instances of class \fIclass\fR. If the
 optional \fIpattern\fR argument is present, it constrains the list of returned
 instances to those that match it according to the rules of \fBstring match\fR.
-.VE 8.6
 .TP
 \fBinfo class methods\fI class\fR ?\fIoptions...\fR?
-.VS 8.6
+.
 This subcommand returns a list of all public (i.e. exported) methods of the
 class called \fIclass\fR. Any of the following \fIoption\fRs may be
 specified, controlling exactly which method names are returned:
 .RS
-.VE 8.6
 .TP
 \fB\-all\fR
-.VS 8.6
-If the \fB\-all\fR flag is given, the list of methods will include those
+.
+If the \fB\-all\fR flag is given,
+.VS TIP500
+and the \fB\-scope\fR flag is not given,
+.VE TIP500
+the list of methods will include those
 methods defined not just by the class, but also by the class's superclasses
 and mixins.
-.VE 8.6
 .TP
 \fB\-private\fR
-.VS 8.6
-If the \fB\-private\fR flag is given, the list of methods will also include
-the private (i.e. non-exported) methods of the class (and superclasses and
+.
+If the \fB\-private\fR flag is given,
+.VS TIP500
+and the \fB\-scope\fR flag is not given,
+.VE TIP500
+the list of methods will also include
+the non-exported methods of the class (and superclasses and
 mixins, if \fB\-all\fR is also given).
+.VS TIP500
+Note that this naming is an unfortunate clash with true private methods; this
+option name is retained for backward compatibility.
+.VE TIP500
+.TP
+\fB\-scope\fI scope\fR
+.VS TIP500
+Returns a list of all methods on \fIclass\fR that have the given visibility
+\fIscope\fR.  When this option is supplied, both the \fB\-all\fR and
+\fB\-private\fR options are ignored. The valid values for \fIscope\fR are:
+.RS
+.IP \fBpublic\fR 3
+Only methods with \fIpublic\fR scope (i.e., callable from anywhere by any instance
+of this class) are to be returned.
+.IP \fBunexported\fR 3
+Only methods with \fIunexported\fR scope (i.e., only callable via \fBmy\fR) are to
+be returned.
+.IP \fBprivate\fR 3
+Only methods with \fIprivate\fR scope (i.e., only callable from within this class's
+methods) are to be returned.
+.RE
+.VE TIP500
 .RE
-.VE 8.6
 .TP
 \fBinfo class methodtype\fI class method\fR
-.VS 8.6
+.
 This subcommand returns a description of the type of implementation used for
 the method named \fImethod\fR of class \fIclass\fR. When the result is
 \fBmethod\fR, further information can be discovered with \fBinfo class
 definition\fR, and when the result is \fBforward\fR, further information can
 be discovered with \fBinfo class forward\fR.
-.VE 8.6
 .TP
 \fBinfo class mixins\fI class\fR
-.VS 8.6
+.
 This subcommand returns a list of all classes that have been mixed into the
 class named \fIclass\fR.
-.VE 8.6
 .TP
 \fBinfo class subclasses\fI class\fR ?\fIpattern\fR?
-.VS 8.6
+.
 This subcommand returns a list of direct subclasses of class \fIclass\fR. If
 the optional \fIpattern\fR argument is present, it constrains the list of
 returned classes to those that match it according to the rules of
 \fBstring match\fR.
-.VE 8.6
 .TP
 \fBinfo class superclasses\fI class\fR
-.VS 8.6
+.
 This subcommand returns a list of direct superclasses of class \fIclass\fR in
 inheritance precedence order.
-.VE 8.6
 .TP
-\fBinfo class variables\fI class\fR
-.VS 8.6
+\fBinfo class variables\fI class\fR ?\fB\-private\fR?
+.
 This subcommand returns a list of all variables that have been declared for
 the class named \fIclass\fR (i.e. that are automatically present in the
 class's methods, constructor and destructor).
+.VS TIP500
+If the \fB\-private\fR option is specified, this lists the private variables
+declared instead.
+.VE TIP500
 .SS "OBJECT INTROSPECTION"
 .PP
 The following \fIsubcommand\fR values are supported by \fBinfo object\fR:
-.VE 8.6
 .TP
 \fBinfo object call\fI object method\fR
-.VS 8.6
+.
 Returns a description of the method implementations that are used to provide
 \fIobject\fR's implementation of \fImethod\fR.  This consists of a list of
 lists of four elements, where each sublist consists of a word that describes
 the general type of method implementation (being one of \fBmethod\fR for an
-ordinary method, \fBfilter\fR for an applied filter, and \fBunknown\fR for a
+ordinary method, \fBfilter\fR for an applied filter,
+.VS TIP500
+\fBprivate\fR for a private method,
+.VE TIP500
+and \fBunknown\fR for a
 method that is invoked as part of unknown method handling), a word giving the
 name of the particular method invoked (which is always the same as
 \fImethod\fR for the \fBmethod\fR type, and
@@ -550,128 +611,160 @@ implementation (see \fBinfo object methodtype\fR).
 .RS
 .PP
 Note that there is no inspection of whether the method implementations
-actually use \fBnext\fR to transfer control along the call chain.
+actually use \fBnext\fR to transfer control along the call chain,
+.VS TIP500
+and the call chains that this command files do not actually contain private
+methods.
+.VE TIP500
 .RE
-.VE 8.6
 .TP
 \fBinfo object class\fI object\fR ?\fIclassName\fR?
-.VS 8.6
+.
 If \fIclassName\fR is unspecified, this subcommand returns class of the
 \fIobject\fR object. If \fIclassName\fR is present, this subcommand returns a
 boolean value indicating whether the \fIobject\fR is of that class.
-.VE 8.6
+.TP
+\fBinfo object creationid\fI object\fR
+.VS TIP500
+Returns the unique creation identifier for the \fIobject\fR object. This
+creation identifier is unique to the object (within a Tcl interpreter) and
+cannot be controlled at object creation time or altered afterwards.
+.RS
+.PP
+\fIImplementation note:\fR the creation identifier is used to generate unique
+identifiers associated with the object, especially for private variables.
+.RE
+.VE TIP500
 .TP
 \fBinfo object definition\fI object method\fR
-.VS 8.6
+.
 This subcommand returns a description of the definition of the method named
 \fImethod\fR of object \fIobject\fR. The definition is described as a two
 element list; the first element is the list of arguments to the method in a
 form suitable for passing to another call to \fBproc\fR or a method definition,
 and the second element is the body of the method.
-.VE 8.6
 .TP
 \fBinfo object filters\fI object\fR
-.VS 8.6
+.
 This subcommand returns the list of filter methods set on the object.
-.VE 8.6
 .TP
 \fBinfo object forward\fI object method\fR
-.VS 8.6
+.
 This subcommand returns the argument list for the method forwarding called
 \fImethod\fR that is set on the object called \fIobject\fR.
-.VE 8.6
 .TP
 \fBinfo object isa\fI category object\fR ?\fIarg\fR?
-.VS 8.6
+.
 This subcommand tests whether an object belongs to a particular category,
 returning a boolean value that indicates whether the \fIobject\fR argument
 meets the criteria for the category. The supported categories are:
-.VE 8.6
 .RS
 .TP
 \fBinfo object isa class\fI object\fR
-.VS 8.6
+.
 This returns whether \fIobject\fR is a class (i.e. an instance of
 \fBoo::class\fR or one of its subclasses).
-.VE 8.6
 .TP
 \fBinfo object isa metaclass\fI object\fR
-.VS 8.6
+.
 This returns whether \fIobject\fR is a class that can manufacture classes
 (i.e. is \fBoo::class\fR or a subclass of it).
-.VE 8.6
 .TP
 \fBinfo object isa mixin\fI object class\fR
-.VS 8.6
+.
 This returns whether \fIclass\fR is directly mixed into \fIobject\fR.
-.VE 8.6
 .TP
 \fBinfo object isa object\fI object\fR
-.VS 8.6
+.
 This returns whether \fIobject\fR really is an object.
-.VE 8.6
 .TP
 \fBinfo object isa typeof\fI object class\fR
-.VS 8.6
+.
 This returns whether \fIclass\fR is the type of \fIobject\fR (i.e. whether
 \fIobject\fR is an instance of \fIclass\fR or one of its subclasses, whether
 direct or indirect).
 .RE
-.VE 8.6
 .TP
 \fBinfo object methods\fI object\fR ?\fIoption...\fR?
-.VS 8.6
+.
 This subcommand returns a list of all public (i.e. exported) methods of the
 object called \fIobject\fR. Any of the following \fIoption\fRs may be
 specified, controlling exactly which method names are returned:
 .RS
-.VE 8.6
 .TP
 \fB\-all\fR
-.VS 8.6
-If the \fB\-all\fR flag is given, the list of methods will include those
+.
+If the \fB\-all\fR flag is given,
+.VS TIP500
+and the \fB\-scope\fR flag is not given,
+.VE TIP500
+the list of methods will include those
 methods defined not just by the object, but also by the object's class and
 mixins, plus the superclasses of those classes.
-.VE 8.6
 .TP
 \fB\-private\fR
-.VS 8.6
-If the \fB\-private\fR flag is given, the list of methods will also include
-the private (i.e. non-exported) methods of the object (and classes, if
+.
+If the \fB\-private\fR flag is given,
+.VS TIP500
+and the \fB\-scope\fR flag is not given,
+.VE TIP500
+the list of methods will also include
+the non-exported methods of the object (and classes, if
 \fB\-all\fR is also given).
+.VS TIP500
+Note that this naming is an unfortunate clash with true private methods; this
+option name is retained for backward compatibility.
+.VE TIP500
+.TP
+\fB\-scope\fI scope\fR
+.VS TIP500
+Returns a list of all methods on \fIobject\fR that have the given visibility
+\fIscope\fR.  When this option is supplied, both the \fB\-all\fR and
+\fB\-private\fR options are ignored. The valid values for \fIscope\fR are:
+.RS
+.IP \fBpublic\fR 3
+Only methods with \fIpublic\fR scope (i.e., callable from anywhere) are to be
+returned.
+.IP \fBunexported\fR 3
+Only methods with \fIunexported\fR scope (i.e., only callable via \fBmy\fR) are to
+be returned.
+.IP \fBprivate\fR 3
+Only methods with \fIprivate\fR scope (i.e., only callable from within this object's
+instance methods) are to be returned.
+.RE
+.VE TIP500
 .RE
-.VE 8.6
 .TP
 \fBinfo object methodtype\fI object method\fR
-.VS 8.6
+.
 This subcommand returns a description of the type of implementation used for
 the method named \fImethod\fR of object \fIobject\fR. When the result is
 \fBmethod\fR, further information can be discovered with \fBinfo object
 definition\fR, and when the result is \fBforward\fR, further information can
 be discovered with \fBinfo object forward\fR.
-.VE 8.6
 .TP
 \fBinfo object mixins\fI object\fR
-.VS 8.6
+.
 This subcommand returns a list of all classes that have been mixed into the
 object named \fIobject\fR.
-.VE 8.6
 .TP
 \fBinfo object namespace\fI object\fR
-.VS 8.6
+.
 This subcommand returns the name of the internal namespace of the object named
 \fIobject\fR.
-.VE 8.6
 .TP
-\fBinfo object variables\fI object\fR
-.VS 8.6
+\fBinfo object variables\fI object\fRR ?\fB\-private\fR?
+.
 This subcommand returns a list of all variables that have been declared for
 the object named \fIobject\fR (i.e. that are automatically present in the
 object's methods).
-.VE 8.6
+.VS TIP500
+If the \fB\-private\fR option is specified, this lists the private variables
+declared instead.
+.VE TIP500
 .TP
 \fBinfo object vars\fI object\fR ?\fIpattern\fR?
-.VS 8.6
+.
 This subcommand returns a list of all variables in the private namespace of
 the object named \fIobject\fR. If the optional \fIpattern\fR argument is
 given, it is a filter (in the syntax of a \fBstring match\fR glob pattern)
@@ -680,7 +773,6 @@ from the list returned by \fBinfo object variables\fR; that can include
 variables that are currently unset, whereas this can include variables that
 are not automatically included by any of \fIobject\fR's methods (or those of
 its class, superclasses or mixins).
-.VE 8.6
 .SH EXAMPLES
 .PP
 This command prints out a procedure suitable for saving in a Tcl
@@ -703,7 +795,6 @@ proc printProc {procName} {
 }
 .CE
 .SS "EXAMPLES WITH OBJECTS"
-.VS 8.6
 .PP
 Every object necessarily knows what its class is; this information is
 trivially extractable through introspection:
@@ -724,8 +815,10 @@ method and get how it is defined. This procedure illustrates how:
 proc getDef {obj method} {
     foreach inf [\fBinfo object call\fR $obj $method] {
         lassign $inf calltype name locus methodtype
+
         # Assume no forwards or filters, and hence no $calltype
         # or $methodtype checks...
+
         if {$locus eq "object"} {
             return [\fBinfo object definition\fR $obj $name]
         } else {
@@ -748,7 +841,9 @@ proc getDef {obj method} {
         # Assume no forwards
         return [\fBinfo object definition\fR $obj $method]
     }
+
     set cls [\fBinfo object class\fR $obj]
+
     while {$method ni [\fBinfo class methods\fR $cls]} {
         # Assume the simple case
         set cls [lindex [\fBinfo class superclass\fR $cls] 0]
@@ -756,22 +851,17 @@ proc getDef {obj method} {
             error "no definition for $method"
         }
     }
+
     # Assume no forwards
     return [\fBinfo class definition\fR $cls $method]
 }
 .CE
-.VE 8.6
 .SH "SEE ALSO"
-.VS 8.6
 global(n), oo::class(n), oo::define(n), oo::object(n), proc(n), self(n),
-.VE 8.6
 tcl_library(n), tcl_patchLevel(n), tcl_version(n)
 .SH KEYWORDS
 command, information, interpreter, introspection, level, namespace,
-.VS 8.6
-object,
-.VE 8.6
-procedure, variable
+object, procedure, variable
 '\" Local Variables:
 '\" mode: nroff
 '\" fill-column: 78

doc/join.n

@@ -42,3 +42,7 @@ set data {1 {2 3} 4 {5 {6 7} 8}}
 list(n), lappend(n), split(n)
 .SH KEYWORDS
 element, join, list, separator
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:

doc/lappend.n

@@ -22,6 +22,12 @@ and appends each of the \fIvalue\fR arguments to that list as a separate
 element, with spaces between elements.
 If \fIvarName\fR does not exist, it is created as a list with elements
 given by 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, list that is comprised of the default value with all the
+\fIvalue\fR arguments appended as elements will be stored in the array
+element.
+.VE TIP508
 \fBLappend\fR is similar to \fBappend\fR except that the \fIvalue\fRs
 are appended as list elements rather than raw text.
 This command provides a relatively efficient way to build up
@@ -47,3 +53,7 @@ list(n), lindex(n), linsert(n), llength(n), lset(n),
 lsort(n), lrange(n)
 .SH KEYWORDS
 append, element, list, variable
+.\" Local variables:
+.\" mode: nroff
+.\" fill-column: 78
+.\" End:

doc/link.n

@@ -0,0 +1,124 @@
+'\"
+'\" 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 link n 0.3 TclOO "TclOO Commands"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+link \- create link from command to method of object
+.SH SYNOPSIS
+.nf
+package require TclOO
+
+\fBlink\fR \fImethodName\fR ?\fI...\fR?
+\fBlink\fR \fB{\fIcommandName methodName\fB}\fR ?\fI...\fR?
+.fi
+.BE
+.SH DESCRIPTION
+The \fBlink\fR command is available within methods. It takes a series of one
+or more method names (\fImethodName ...\fR) and/or pairs of command- and
+method-name (\fB{\fIcommandName methodName\fB}\fR) and makes the named methods
+available as commands without requiring the explicit use of the name of the
+object or the \fBmy\fR command. The method does not need to exist at the time
+that the link is made; if the link command is invoked when the method does not
+exist, the standard \fBunknown\fR method handling system is used.
+.PP
+The command name under which the method becomes available defaults to the
+method name, except where explicitly specified through an alias/method pair.
+Formally, every argument must be a list; if the list has two elements, the
+first element is the name of the command to create and the second element is
+the name of the method of the current object to which the command links;
+otherwise, the name of the command and the name of the method are the same
+string (the first element of the list).
+.PP
+If the name of the command is not a fully-qualified command name, it will be
+resolved with respect to the current namespace (i.e., the object namespace).
+.SH EXAMPLES
+This demonstrates linking a single method in various ways. First it makes a
+simple link, then a renamed link, then an external link. Note that the method
+itself is unexported, but that it can still be called directly from outside
+the class.
+.PP
+.CS
+oo::class create ABC {
+    method Foo {} {
+        puts "This is Foo in [self]"
+    }
+
+    constructor {} {
+        \fBlink\fR Foo
+        # The method foo is now directly accessible as foo here
+        \fBlink\fR {bar Foo}
+        # The method foo is now directly accessible as bar
+        \fBlink\fR {::ExternalCall Foo}
+        # The method foo is now directly accessible in the global
+        # namespace as ExternalCall
+    }
+
+    method grill {} {
+        puts "Step 1:"
+        Foo
+        puts "Step 2:"
+        bar
+    }
+}
+
+ABC create abc
+abc grill
+        \fI\(-> Step 1:\fR
+        \fI\(-> This is foo in ::abc\fR
+        \fI\(-> Step 2:\fR
+        \fI\(-> This is foo in ::abc\fR
+# Direct access via the linked command
+puts "Step 3:"; ExternalCall
+        \fI\(-> Step 3:\fR
+        \fI\(-> This is foo in ::abc\fR
+.CE
+.PP
+This example shows that multiple linked commands can be made in a call to
+\fBlink\fR, and that they can handle arguments.
+.PP
+.CS
+oo::class create Ex {
+    constructor {} {
+        \fBlink\fR a b c
+        # The methods a, b, and c (defined below) are all now
+        # directly acessible within methods under their own names.
+    }
+
+    method a {} {
+        puts "This is a"
+    }
+    method b {x} {
+        puts "This is b($x)"
+    }
+    method c {y z} {
+        puts "This is c($y,$z)"
+    }
+
+    method call {p q r} {
+        a
+        b $p
+        c $q $r
+    }
+}
+
+set o [Ex new]
+$o 3 5 7
+        \fI\(-> This is a\fR
+        \fI\(-> This is b(3)\fR
+        \fI\(-> This is c(5,7)\fR
+.CE
+.SH "SEE ALSO"
+interp(n), my(n), oo::class(n), oo::define(n)
+.SH KEYWORDS
+command, method, object
+.\" Local Variables:
+.\" mode: nroff
+.\" fill-column: 78
+.\" End:

doc/llength.n

@@ -53,3 +53,7 @@ list(n), lappend(n), lindex(n), linsert(n), lsearch(n),
 lset(n), lsort(n), lrange(n), lreplace(n)
 .SH KEYWORDS
 element, list, length
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End: