Also finalize the condition variables for each notifier thread.

Don't fix eol-style for Makefile.in in "make dist", if the file system is case-insensitive/case-preserving.

.project

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

README

@@ -1,8 +1,7 @@
 README:  Tcl
-    This is the Tcl 8.4.19 source distribution.
-	http://tcl.sourceforge.net/
-    You can get any source release of Tcl from the file distributions
-    link at the above URL.
+    This is the Tcl 8.5.15 source distribution.
+	http://sourceforge.net/projects/tcl/files/Tcl/
+    You can get any source release of Tcl from the URL above.
 
 Contents
 --------
@@ -22,14 +21,19 @@ Contents
 Tcl provides a powerful platform for creating integration applications that
 tie together diverse applications, protocols, devices, and frameworks.
 When paired with the Tk toolkit, Tcl provides the fastest and most powerful
-way to create GUI applications that run on PCs, Unix, and the Macintosh.
+way to create GUI applications that run on PCs, Unix, and Mac OS X.
 Tcl can also be used for a variety of web-related tasks and for creating
 powerful command languages for applications.
 
 Tcl is maintained, enhanced, and distributed freely by the Tcl community.
-The home for Tcl/Tk releases and bug/patch database is on SourceForge:
+Source code development and tracking of bug reports and feature requests
+takes place at:
 
-	http://tcl.sourceforge.net/
+	http://core.tcl.tk/
+
+Tcl/Tk release and mailing list services are hosted by SourceForge:
+
+	http://sourceforge.net/projects/tcl/
 
 with the Tcl Developer Xchange hosted at:
 
@@ -45,11 +49,11 @@ 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.4.html
+	http://www.tcl.tk/software/tcltk/8.5.html
 
 Detailed release notes can be found at the file distributions page
 by clicking on the relevant version.
-	http://sourceforge.net/projects/tcl/files/
+	http://sourceforge.net/projects/tcl/files/Tcl/
 
 Information about Tcl itself can be found at
 	http://www.tcl.tk/about/
@@ -57,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.4 online,
+To view the complete set of reference manual entries for Tcl 8.5 online,
 visit the URL:
-	http://www.tcl.tk/man/tcl8.4/
+	http://www.tcl.tk/man/tcl8.5/
 
 2a. Unix Documentation
 ----------------------
@@ -118,8 +122,8 @@ information about Tcl, Tk, and related applications.  The newsgroup is a
 great place to ask general information questions.  For bug reports, please
 see the "Support and bug fixes" section below.
 
-6. The Tcler's Wiki
--------------------
+6. Tcl'ers Wiki
+---------------
 
 A Wiki-based open community site covering all aspects of Tcl/Tk is at:
 
@@ -146,18 +150,13 @@ and go to the Mailing Lists page.
 ------------------------
 
 We are very interested in receiving bug reports, patches, and suggestions
-for improvements.  We prefer that you send this information to us via the
-bug form at SourceForge, rather than emailing us directly.  The bug
-database is at:
+for improvements.  We prefer that you send this information to us as
+tickets entered into our tracker at:
 
-	http://tcl.sourceforge.net/
-
-The bug form was designed to give uniform structure to bug reports as
-well as to solicit enough information to minimize followup questions.
+	http://core.tcl.tk/tcl/reportlist
 
 We will log and follow-up on each bug, although we cannot promise a
-specific turn-around time.  Enhancements, reported via the Feature
-Requests form at the same web site, may take longer and may not happen
+specific turn-around time.  Enhancements may take longer and may not happen
 at all unless there is widespread support for them (we're trying to
 slow the rate at which Tcl/Tk turns into a kitchen sink).  It's very
 difficult to make incompatible changes to Tcl/Tk at this point, due to
@@ -167,7 +166,7 @@ The Tcl community is too large for us to provide much individual support
 for users.  If you need help we suggest that you post questions to
 comp.lang.tcl.  We read the newsgroup and will attempt to answer esoteric
 questions for which no one else is likely to know the answer.  In addition,
-see the following page on the Wiki for links to other organizations that offer
+see the following Web site for links to other organizations that offer
 Tcl/Tk training:
 
 	http://wiki.tcl.tk/training

compat/dirent2.h

@@ -14,10 +14,6 @@
 #ifndef _DIRENT
 #define _DIRENT
 
-#ifndef _TCL
-#include <tcl.h>
-#endif
-
 /*
  * Dirent structure, which holds information about a single
  * directory entry.
@@ -50,8 +46,8 @@ typedef struct _dirdesc {
  * Procedures defined for reading directories:
  */
 
-extern void		closedir _ANSI_ARGS_((DIR *dirp));
-extern DIR *		opendir _ANSI_ARGS_((char *name));
-extern struct dirent *	readdir _ANSI_ARGS_((DIR *dirp));
+extern void		closedir (DIR *dirp);
+extern DIR *		opendir (char *name);
+extern struct dirent *	readdir (DIR *dirp);
 
 #endif /* _DIRENT */

compat/dlfcn.h

@@ -1,4 +1,4 @@
-/* 
+/*
  * dlfcn.h --
  *
  *	This file provides a replacement for the header file "dlfcn.h"
@@ -19,7 +19,6 @@
  */
 
 /*
- * @(#)dlfcn.h	1.4 revision of 95/04/25  09:36:52
  * This is an unpublished work copyright (c) 1992 HELIOS Software GmbH
  * 30159 Hannover, Germany
  */
@@ -27,10 +26,6 @@
 #ifndef __dlfcn_h__
 #define __dlfcn_h__
 
-#ifndef _TCL
-#include <tcl.h>
-#endif
-
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -47,14 +42,14 @@ extern "C" {
  * that contains functions to be called to initialize and terminate.
  */
 struct dl_info {
-	void (*init) _ANSI_ARGS_((void));
-	void (*fini) _ANSI_ARGS_((void));
+	void (*init) (void);
+	void (*fini) (void);
 };
 
-VOID *dlopen _ANSI_ARGS_((const char *path, int mode));
-VOID *dlsym _ANSI_ARGS_((void *handle, const char *symbol));
-char *dlerror _ANSI_ARGS_((void));
-int dlclose _ANSI_ARGS_((void *handle));
+void *dlopen (const char *path, int mode);
+void *dlsym (void *handle, const char *symbol);
+char *dlerror (void);
+int dlclose (void *handle);
 
 #ifdef __cplusplus
 }

compat/fixstrtod.c

@@ -20,12 +20,12 @@
  * somes systems (e.g. SunOS 4.1.4) stdlib.h doesn't declare strtod.
  */
 
-extern double strtod();
+extern double strtod(char *, char **);
 
 double
-fixstrtod(string, endPtr)
-    char *string;
-    char **endPtr;
+fixstrtod(
+    char *string,
+    char **endPtr)
 {
     double d;
     d = strtod(string, endPtr);

compat/gettod.c

@@ -10,18 +10,18 @@
  * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  */
 
-#include "tcl.h"
 #include "tclPort.h"
 #include <sys/timeb.h>
 
 #undef timezone
 
 int
-gettimeofday(tp, tz)
-struct timeval *tp;
-struct timezone *tz;
+gettimeofday(
+    struct timeval *tp,
+    struct timezone *tz)
 {
     struct timeb t;
+
     ftime(&t);
     tp->tv_sec = t.time;
     tp->tv_usec = t. millitm * 1000;

compat/memcmp.c

@@ -1,24 +1,21 @@
-/* 
+/*
  * memcmp.c --
  *
  *	Source code for the "memcmp" library routine.
  *
  * Copyright (c) 1998 Sun Microsystems, Inc.
  *
- * See the file "license.terms" for information on usage and redistribution
- * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+ * See the file "license.terms" for information on usage and redistribution of
+ * this file, and for a DISCLAIMER OF ALL WARRANTIES.
  */
 
-#include "tcl.h"
 #include "tclPort.h"
 
 /*
- * Here is the prototype just in case it is not included
- * in tclPort.h.
+ * Here is the prototype just in case it is not included in tclPort.h.
  */
 
-int		memcmp _ANSI_ARGS_((CONST VOID *s1,
-			    CONST VOID *s2, size_t n));
+int		memcmp(CONST VOID *s1, CONST VOID *s2, size_t n);
 
 /*
  *----------------------------------------------------------------------
@@ -28,11 +25,10 @@ int		memcmp _ANSI_ARGS_((CONST VOID *s1,
  *	Compares two bytes sequences.
  *
  * Results:
- *     compares  its  arguments, looking at the first n
- *     bytes (each interpreted as an unsigned char), and  returns
- *     an integer less than, equal to, or greater than 0, accord-
- *     ing as s1 is less  than,  equal  to,  or
- *     greater than s2 when taken to be unsigned 8 bit numbers.
+ *	Compares its arguments, looking at the first n bytes (each interpreted
+ *	as an unsigned char), and returns an integer less than, equal to, or
+ *	greater than 0, according as s1 is less than, equal to, or greater
+ *	than s2 when taken to be unsigned 8 bit numbers.
  *
  * Side effects:
  *	None.
@@ -41,10 +37,10 @@ int		memcmp _ANSI_ARGS_((CONST VOID *s1,
  */
 
 int
-memcmp(s1, s2, n)
-    CONST VOID *s1;			/* First string. */
-    CONST VOID *s2;			/* Second string. */
-    size_t      n;                      /* Length to compare. */
+memcmp(
+    CONST VOID *s1,		/* First string. */
+    CONST VOID *s2,		/* Second string. */
+    size_t n)			/* Length to compare. */
 {
     CONST unsigned char *ptr1 = (CONST unsigned char *) s1;
     CONST unsigned char *ptr2 = (CONST unsigned char *) s2;
@@ -52,9 +48,17 @@ memcmp(s1, s2, n)
     for ( ; n-- ; ptr1++, ptr2++) {
 	unsigned char u1 = *ptr1, u2 = *ptr2;
 
-	if ( u1 != u2) {
+	if (u1 != u2) {
 	    return (u1-u2);
 	}
     }
     return 0;
 }
+
+/*
+ * Local Variables:
+ * mode: c
+ * c-basic-offset: 4
+ * fill-column: 78
+ * End:
+ */

compat/opendir.c

@@ -1,14 +1,12 @@
 /* 
  * opendir.c --
  *
- *	This file provides dirent-style directory-reading procedures
- *	for V7 Unix systems that don't have such procedures.  The
- *	origin of this code is unclear, but it seems to have come
- *	originally from Larry Wall.
+ *	This file provides dirent-style directory-reading procedures for V7
+ *	Unix systems that don't have such procedures. The origin of this code
+ *	is unclear, but it seems to have come originally from Larry Wall.
  */
 
 #include "tclInt.h"
-#include "tclPort.h"
 
 #undef DIRSIZ
 #define DIRSIZ(dp) \
@@ -17,24 +15,28 @@
 /*
  * open a directory.
  */
-DIR *
-opendir(name)
-char *name;
-{
-	register DIR *dirp;
-	register int fd;
-	char *myname;
 
-	myname = ((*name == '\0') ? "." : name);
-	if ((fd = open(myname, 0, 0)) == -1)
-		return NULL;
-	if ((dirp = (DIR *)ckalloc(sizeof(DIR))) == NULL) {
-		close (fd);
-		return NULL;
-	}
-	dirp->dd_fd = fd;
-	dirp->dd_loc = 0;
-	return dirp;
+DIR *
+opendir(
+    char *name)
+{
+    register DIR *dirp;
+    register int fd;
+    char *myname;
+
+    myname = ((*name == '\0') ? "." : name);
+    if ((fd = open(myname, 0, 0)) == -1) {
+	return NULL;
+    }
+    dirp = (DIR *) ckalloc(sizeof(DIR));
+    if (dirp == NULL) {
+	/* unreachable? */
+	close(fd);
+	return NULL;
+    }
+    dirp->dd_fd = fd;
+    dirp->dd_loc = 0;
+    return dirp;
 }
 
 /*
@@ -44,62 +46,65 @@ char *name;
 #define	ODIRSIZ	14
 
 struct	olddirect {
-	ino_t	od_ino;
-	char	od_name[ODIRSIZ];
+    ino_t od_ino;
+    char od_name[ODIRSIZ];
 };
 #else	/* a Pyramid in the ATT universe */
 #define	ODIRSIZ	248
 
 struct	olddirect {
-	long	od_ino;
-	short	od_fill1, od_fill2;
-	char	od_name[ODIRSIZ];
+    long od_ino;
+    short od_fill1, od_fill2;
+    char od_name[ODIRSIZ];
 };
 #endif
 
 /*
  * get next entry in a directory.
  */
-struct dirent *
-readdir(dirp)
-register DIR *dirp;
-{
-	register struct olddirect *dp;
-	static struct dirent dir;
 
-	for (;;) {
-		if (dirp->dd_loc == 0) {
-			dirp->dd_size = read(dirp->dd_fd, dirp->dd_buf,
-			    DIRBLKSIZ);
-			if (dirp->dd_size <= 0)
-				return NULL;
-		}
-		if (dirp->dd_loc >= dirp->dd_size) {
-			dirp->dd_loc = 0;
-			continue;
-		}
-		dp = (struct olddirect *)(dirp->dd_buf + dirp->dd_loc);
-		dirp->dd_loc += sizeof(struct olddirect);
-		if (dp->od_ino == 0)
-			continue;
-		dir.d_ino = dp->od_ino;
-		strncpy(dir.d_name, dp->od_name, ODIRSIZ);
-		dir.d_name[ODIRSIZ] = '\0'; /* insure null termination */
-		dir.d_namlen = strlen(dir.d_name);
-		dir.d_reclen = DIRSIZ(&dir);
-		return (&dir);
+struct dirent *
+readdir(
+    register DIR *dirp)
+{
+    register struct olddirect *dp;
+    static struct dirent dir;
+
+    for (;;) {
+	if (dirp->dd_loc == 0) {
+	    dirp->dd_size = read(dirp->dd_fd, dirp->dd_buf, DIRBLKSIZ);
+	    if (dirp->dd_size <= 0) {
+		return NULL;
+	    }
 	}
+	if (dirp->dd_loc >= dirp->dd_size) {
+	    dirp->dd_loc = 0;
+	    continue;
+	}
+	dp = (struct olddirect *)(dirp->dd_buf + dirp->dd_loc);
+	dirp->dd_loc += sizeof(struct olddirect);
+	if (dp->od_ino == 0) {
+	    continue;
+	}
+	dir.d_ino = dp->od_ino;
+	strncpy(dir.d_name, dp->od_name, ODIRSIZ);
+	dir.d_name[ODIRSIZ] = '\0'; /* insure null termination */
+	dir.d_namlen = strlen(dir.d_name);
+	dir.d_reclen = DIRSIZ(&dir);
+	return &dir;
+    }
 }
 
 /*
  * close a directory.
  */
+
 void
-closedir(dirp)
-register DIR *dirp;
+closedir(
+    register DIR *dirp)
 {
-	close(dirp->dd_fd);
-	dirp->dd_fd = -1;
-	dirp->dd_loc = 0;
-	ckfree((char *) dirp);
+    close(dirp->dd_fd);
+    dirp->dd_fd = -1;
+    dirp->dd_loc = 0;
+    ckfree((char *) dirp);
 }

compat/stdlib.h

@@ -1,43 +1,36 @@
 /*
  * stdlib.h --
  *
- *	Declares facilities exported by the "stdlib" portion of
- *	the C library.  This file isn't complete in the ANSI-C
- *	sense;  it only declares things that are needed by Tcl.
- *	This file is needed even on many systems with their own
- *	stdlib.h (e.g. SunOS) because not all stdlib.h files
- *	declare all the procedures needed here (such as strtod).
+ *	Declares facilities exported by the "stdlib" portion of the C library.
+ *	This file isn't complete in the ANSI-C sense; it only declares things
+ *	that are needed by Tcl. This file is needed even on many systems with
+ *	their own stdlib.h (e.g. SunOS) because not all stdlib.h files declare
+ *	all the procedures needed here (such as strtod).
  *
  * Copyright (c) 1991 The Regents of the University of California.
  * Copyright (c) 1994-1998 Sun Microsystems, Inc.
  *
- * See the file "license.terms" for information on usage and redistribution
- * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+ * See the file "license.terms" for information on usage and redistribution of
+ * this file, and for a DISCLAIMER OF ALL WARRANTIES.
  */
 
 #ifndef _STDLIB
 #define _STDLIB
 
-#include <tcl.h>
-
-extern void		abort _ANSI_ARGS_((void));
-extern double		atof _ANSI_ARGS_((CONST char *string));
-extern int		atoi _ANSI_ARGS_((CONST char *string));
-extern long		atol _ANSI_ARGS_((CONST char *string));
-extern char *		calloc _ANSI_ARGS_((unsigned int numElements,
-			    unsigned int size));
-extern void		exit _ANSI_ARGS_((int status));
-extern int		free _ANSI_ARGS_((char *blockPtr));
-extern char *		getenv _ANSI_ARGS_((CONST char *name));
-extern char *		malloc _ANSI_ARGS_((unsigned int numBytes));
-extern void		qsort _ANSI_ARGS_((VOID *base, int n, int size,
-			    int (*compar)(CONST VOID *element1, CONST VOID
-			    *element2)));
-extern char *		realloc _ANSI_ARGS_((char *ptr, unsigned int numBytes));
-extern double		strtod _ANSI_ARGS_((CONST char *string, char **endPtr));
-extern long		strtol _ANSI_ARGS_((CONST char *string, char **endPtr,
-			    int base));
-extern unsigned long	strtoul _ANSI_ARGS_((CONST char *string,
-			    char **endPtr, int base));
+extern void		abort(void);
+extern double		atof(const char *string);
+extern int		atoi(const char *string);
+extern long		atol(const char *string);
+extern char *		calloc(unsigned int numElements, unsigned int size);
+extern void		exit(int status);
+extern int		free(char *blockPtr);
+extern char *		getenv(const char *name);
+extern char *		malloc(unsigned int numBytes);
+extern void		qsort(void *base, int n, int size, int (*compar)(
+			    const void *element1, const void *element2));
+extern char *		realloc(char *ptr, unsigned int numBytes);
+extern double		strtod(const char *string, char **endPtr);
+extern long		strtol(const char *string, char **endPtr, int base);
+extern unsigned long	strtoul(const char *string, char **endPtr, int base);
 
 #endif /* _STDLIB */

compat/strftime.c

@@ -1,518 +0,0 @@
-/* 
- * strftime.c --
- *
- *	This file contains a modified version of the BSD 4.4 strftime
- *	function.
- *
- * This file is a modified version of the strftime.c file from the BSD 4.4
- * source.  See the copyright notice below for details on redistribution
- * restrictions.  The "license.terms" file does not apply to this file.
- *
- * Changes 2002 Copyright (c) 2002 ActiveState Corporation.
- */
-
-/*
- * Copyright (c) 1989 The Regents of the University of California.
- * All rights reserved.
- *
- * Redistribution and use in source and binary forms, with or without
- * modification, are permitted provided that the following conditions
- * are met:
- * 1. Redistributions of source code must retain the above copyright
- *    notice, this list of conditions and the following disclaimer.
- * 2. Redistributions in binary form must reproduce the above copyright
- *    notice, this list of conditions and the following disclaimer in the
- *    documentation and/or other materials provided with the distribution.
- * 3. All advertising materials mentioning features or use of this software
- *    must display the following acknowledgement:
- *	This product includes software developed by the University of
- *	California, Berkeley and its contributors.
- * 4. Neither the name of the University nor the names of its contributors
- *    may be used to endorse or promote products derived from this software
- *    without specific prior written permission.
- *
- * THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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.
- */
-
-#if defined(_WIN32) && !defined(_WIN64)
-#   define _USE_32BIT_TIME_T
-#endif
-#include <time.h>
-#include <string.h>
-#include <locale.h>
-#include "tclInt.h"
-#include "tclPort.h"
-
-#define TM_YEAR_BASE   1900
-#define IsLeapYear(x)   ((x % 4 == 0) && (x % 100 != 0 || x % 400 == 0))
-
-typedef struct {
-    const char *abday[7];
-    const char *day[7];
-    const char *abmon[12];
-    const char *mon[12];
-    const char *am_pm[2];
-    const char *d_t_fmt;
-    const char *d_fmt;
-    const char *t_fmt;
-    const char *t_fmt_ampm;
-} _TimeLocale;
-
-/*
- * This is the C locale default.  On Windows, if we wanted to make this
- * localized, we would use GetLocaleInfo to get the correct values.
- * It may be acceptable to do localization of month/day names, as the
- * numerical values would be considered the locale-independent versions.
- */
-static const _TimeLocale _DefaultTimeLocale = 
-{
-    {
-	"Sun","Mon","Tue","Wed","Thu","Fri","Sat",
-    },
-    {
-	"Sunday", "Monday", "Tuesday", "Wednesday", "Thursday",
-	"Friday", "Saturday"
-    },
-    {
-	"Jan", "Feb", "Mar", "Apr", "May", "Jun",
-	"Jul", "Aug", "Sep", "Oct", "Nov", "Dec"
-    },
-    {
-	"January", "February", "March", "April", "May", "June", "July",
-	"August", "September", "October", "November", "December"
-    },
-    {
-	"AM", "PM"
-    },
-    "%a %b %d %H:%M:%S %Y",
-    "%m/%d/%y",
-    "%H:%M:%S",
-    "%I:%M:%S %p"
-};
-
-static const _TimeLocale *_CurrentTimeLocale = &_DefaultTimeLocale;
-
-static int isGMT;
-static size_t gsize;
-static char *pt;
-static int		 _add _ANSI_ARGS_((const char* str));
-static int		_conv _ANSI_ARGS_((int n, int digits, int pad));
-static int		_secs _ANSI_ARGS_((const struct tm *t));
-static size_t		_fmt _ANSI_ARGS_((const char *format,
-			    const struct tm *t));
-static int ISO8601Week _ANSI_ARGS_((CONST struct tm* t, int *year ));
-
-size_t
-TclpStrftime(s, maxsize, format, t, useGMT)
-    char *s;
-    size_t maxsize;
-    const char *format;
-    const struct tm *t;
-    int useGMT;
-{
-    if (format[0] == '%' && format[1] == 'Q') {
-	/* Format as a stardate */
-	sprintf(s, "Stardate %2d%03d.%01d",
-		(((t->tm_year + TM_YEAR_BASE) + 377) - 2323),
-		(((t->tm_yday + 1) * 1000) /
-			(365 + IsLeapYear((t->tm_year + TM_YEAR_BASE)))),
-		(((t->tm_hour * 60) + t->tm_min)/144));
-	return(strlen(s));
-    }
-
-    isGMT = useGMT;
-    /*
-     * We may be able to skip this for useGMT, but it should be harmless.
-     * -- hobbs
-     */
-    tzset();
-
-    pt = s;
-    if ((gsize = maxsize) < 1)
-	return(0);
-    if (_fmt(format, t)) {
-	*pt = '\0';
-	return(maxsize - gsize);
-    }
-    return(0);
-}
-
-#define SUN_WEEK(t)	(((t)->tm_yday + 7 - \
-				((t)->tm_wday)) / 7)
-#define MON_WEEK(t)	(((t)->tm_yday + 7 - \
-				((t)->tm_wday ? (t)->tm_wday - 1 : 6)) / 7)
-
-static size_t
-_fmt(format, t)
-    const char *format;
-    const struct tm *t;
-{
-#ifdef WIN32
-#define BUF_SIZ 256
-    TCHAR buf[BUF_SIZ];
-    SYSTEMTIME syst = {
-	t->tm_year + 1900,
-	t->tm_mon + 1,
-	t->tm_wday,
-	t->tm_mday,
-	t->tm_hour,
-	t->tm_min,
-	t->tm_sec,
-	0,
-    };
-#endif
-    for (; *format; ++format) {
-	if (*format == '%') {
-	    ++format;
-	    if (*format == 'E') {
-				/* Alternate Era */
-		++format;
-	    } else if (*format == 'O') {
-				/* Alternate numeric symbols */
-		++format;
-	    }
-	    switch(*format) {
-		case '\0':
-		    --format;
-		    break;
-		case 'A':
-		    if (t->tm_wday < 0 || t->tm_wday > 6)
-			return(0);
-		    if (!_add(_CurrentTimeLocale->day[t->tm_wday]))
-			return(0);
-		    continue;
-		case 'a':
-		    if (t->tm_wday < 0 || t->tm_wday > 6)
-			return(0);
-		    if (!_add(_CurrentTimeLocale->abday[t->tm_wday]))
-			return(0);
-		    continue;
-		case 'B':
-		    if (t->tm_mon < 0 || t->tm_mon > 11)
-			return(0);
-		    if (!_add(_CurrentTimeLocale->mon[t->tm_mon]))
-			return(0);
-		    continue;
-		case 'b':
-		case 'h':
-		    if (t->tm_mon < 0 || t->tm_mon > 11)
-			return(0);
-		    if (!_add(_CurrentTimeLocale->abmon[t->tm_mon]))
-			return(0);
-		    continue;
-		case 'C':
-		    if (!_conv((t->tm_year + TM_YEAR_BASE) / 100,
-			    2, '0'))
-			return(0);
-		    continue;
-		case 'D':
-		    if (!_fmt("%m/%d/%y", t))
-			return(0);
-		    continue;
-		case 'd':
-		    if (!_conv(t->tm_mday, 2, '0'))
-			return(0);
-		    continue;
-		case 'e':
-		    if (!_conv(t->tm_mday, 2, ' '))
-			return(0);
-		    continue;
-	        case 'g':
-		    {
-			int year;
-			ISO8601Week( t, &year );
-			if ( !_conv( year%100, 2, '0' ) ) {
-			    return( 0 );
-			}
-			continue;
-		    }
-	        case 'G':
-		    {
-			int year;
-			ISO8601Week( t, &year );
-			if ( !_conv( year, 4, '0' ) ) {
-			    return( 0 );
-			}
-			continue;
-		    }
-		case 'H':
-		    if (!_conv(t->tm_hour, 2, '0'))
-			return(0);
-		    continue;
-		case 'I':
-		    if (!_conv(t->tm_hour % 12 ?
-			    t->tm_hour % 12 : 12, 2, '0'))
-			return(0);
-		    continue;
-		case 'j':
-		    if (!_conv(t->tm_yday + 1, 3, '0'))
-			return(0);
-		    continue;
-		case 'k':
-		    if (!_conv(t->tm_hour, 2, ' '))
-			return(0);
-		    continue;
-		case 'l':
-		    if (!_conv(t->tm_hour % 12 ?
-			    t->tm_hour % 12: 12, 2, ' '))
-			return(0);
-		    continue;
-		case 'M':
-		    if (!_conv(t->tm_min, 2, '0'))
-			return(0);
-		    continue;
-		case 'm':
-		    if (!_conv(t->tm_mon + 1, 2, '0'))
-			return(0);
-		    continue;
-		case 'n':
-		    if (!_add("\n"))
-			return(0);
-		    continue;
-		case 'p':
-		    if (!_add(_CurrentTimeLocale->am_pm[t->tm_hour >= 12]))
-			return(0);
-		    continue;
-		case 'R':
-		    if (!_fmt("%H:%M", t))
-			return(0);
-		    continue;
-		case 'r':
-		    if (!_fmt(_CurrentTimeLocale->t_fmt_ampm, t))
-			return(0);
-		    continue;
-		case 'S':
-		    if (!_conv(t->tm_sec, 2, '0'))
-			return(0);
-		    continue;
-		case 's':
-		    if (!_secs(t))
-			return(0);
-		    continue;
-		case 'T':
-		    if (!_fmt("%H:%M:%S", t))
-			return(0);
-		    continue;
-		case 't':
-		    if (!_add("\t"))
-			return(0);
-		    continue;
-		case 'U':
-		    if (!_conv(SUN_WEEK(t), 2, '0'))
-			return(0);
-		    continue;
-		case 'u':
-		    if (!_conv(t->tm_wday ? t->tm_wday : 7, 1, '0'))
-			return(0);
-		    continue;
-		case 'V':
-		{
-		    int week = ISO8601Week( t, NULL );
-		    if (!_conv(week, 2, '0'))
-			return(0);
-		    continue;
-		}
-		case 'W':
-		    if (!_conv(MON_WEEK(t), 2, '0'))
-			return(0);
-		    continue;
-		case 'w':
-		    if (!_conv(t->tm_wday, 1, '0'))
-			return(0);
-		    continue;
-#ifdef WIN32
-		/*
-		 * To properly handle the localized time routines on Windows,
-		 * we must make use of the special localized calls.
-		 */
-		case 'c':
-		    if (!GetDateFormat(LOCALE_USER_DEFAULT,
-				       DATE_LONGDATE | LOCALE_USE_CP_ACP,
-				       &syst, NULL, buf, BUF_SIZ)
-			|| !_add(buf)
-			|| !_add(" ")) {
-			return(0);
-		    }
-		    /*
-		     * %c is created with LONGDATE + " " + TIME on Windows,
-		     * so continue to %X case here.
-		     */
-		case 'X':
-		    if (!GetTimeFormat(LOCALE_USER_DEFAULT,
-				       LOCALE_USE_CP_ACP,
-				       &syst, NULL, buf, BUF_SIZ)
-			|| !_add(buf)) {
-			return(0);
-		    }
-		    continue;
-		case 'x':
-		    if (!GetDateFormat(LOCALE_USER_DEFAULT,
-				       DATE_SHORTDATE | LOCALE_USE_CP_ACP,
-				       &syst, NULL, buf, BUF_SIZ)
-			|| !_add(buf)) {
-			return(0);
-		    }
-		    continue;
-#else
-		case 'c':
-		    if (!_fmt(_CurrentTimeLocale->d_t_fmt, t))
-			return(0);
-		    continue;
-		case 'x':
-		    if (!_fmt(_CurrentTimeLocale->d_fmt, t))
-			return(0);
-		    continue;
-		case 'X':
-		    if (!_fmt(_CurrentTimeLocale->t_fmt, t))
-			return(0);
-		    continue;
-#endif
-		case 'y':
-		    if (!_conv((t->tm_year + TM_YEAR_BASE) % 100,
-			    2, '0'))
-			return(0);
-		    continue;
-		case 'Y':
-		    if (!_conv((t->tm_year + TM_YEAR_BASE), 4, '0'))
-			return(0);
-		    continue;
-		case 'Z': {
-		    char *name = (isGMT ? "GMT" : TclpGetTZName(t->tm_isdst));
-		    int wrote;
-		    Tcl_UtfToExternal(NULL, NULL, name, -1, 0, NULL,
-				      pt, gsize, NULL, &wrote, NULL);
-		    pt += wrote;
-		    gsize -= wrote;
-		    continue;
-		}
-		case '%':
-		    /*
-		     * X311J/88-090 (4.12.3.5): if conversion char is
-		     * undefined, behavior is undefined.  Print out the
-		     * character itself as printf(3) does.
-		     */
-		default:
-		    break;
-	    }
-	}
-	if (!gsize--)
-	    return(0);
-	*pt++ = *format;
-    }
-    return(gsize);
-}
-
-static int
-_secs(t)
-    const struct tm *t;
-{
-    static char buf[15];
-    register time_t s;
-    register char *p;
-    struct tm tmp;
-
-    /* Make a copy, mktime(3) modifies the tm struct. */
-    tmp = *t;
-    s = mktime(&tmp);
-    for (p = buf + sizeof(buf) - 2; s > 0 && p > buf; s /= 10)
-	*p-- = (char)(s % 10 + '0');
-    return(_add(++p));
-}
-
-static int
-_conv(n, digits, pad)
-    int n, digits;
-    int pad;
-{
-    static char buf[10];
-    register char *p;
-
-    p = buf + sizeof( buf ) - 1;
-    *p-- = '\0';
-    if ( n == 0 ) {
-	*p-- = '0'; --digits;
-    } else {
-	for (; n > 0 && p > buf; n /= 10, --digits)
-	    *p-- = (char)(n % 10 + '0');
-    }
-    while (p > buf && digits-- > 0)
-	*p-- = (char) pad;
-    return(_add(++p));
-}
-
-static int
-_add(str)
-    const char *str;
-{
-    for (;; ++pt, --gsize) {
-	if (!gsize)
-	    return(0);
-	if (!(*pt = *str++))
-	    return(1);
-    }
-}
-
-static int
-ISO8601Week( t, year )
-    CONST struct tm* t;
-    int* year;
-{
-    /* Find the day-of-year of the Thursday in
-     * the week in question. */
-    
-    int ydayThursday;
-    int week;
-    if ( t->tm_wday == 0 ) {
-	ydayThursday = t->tm_yday - 3;
-    } else {
-	ydayThursday = t->tm_yday - t->tm_wday + 4;
-    }
-    
-    if ( ydayThursday < 0 ) {
-	
-	/* This is the last week of the previous year. */
-	if ( IsLeapYear(( t->tm_year + TM_YEAR_BASE - 1 )) ) {
-	    ydayThursday += 366;
-	} else {
-	    ydayThursday += 365;
-	}
-	week = ydayThursday / 7 + 1;
-	if ( year != NULL ) {
-	    *year = t->tm_year + 1899;
-	}
-	
-    } else if ( ( IsLeapYear(( t -> tm_year + TM_YEAR_BASE ))
-		  && ydayThursday >= 366 )
-		|| ( !IsLeapYear(( t -> tm_year
-				   + TM_YEAR_BASE ))
-		     && ydayThursday >= 365 ) ) {
-	
-	/* This is week 1 of the following year */
-	
-	week = 1;
-	if ( year != NULL ) {
-	    *year = t->tm_year + 1901;
-	}
-	
-    } else {
-	
-	week = ydayThursday / 7 + 1;
-	if ( year != NULL ) {
-	    *year = t->tm_year + 1900;
-	}
-	
-    }
-
-    return week;
-    
-}

compat/string.h

@@ -6,66 +6,52 @@
  * Copyright (c) 1991-1993 The Regents of the University of California.
  * Copyright (c) 1994-1996 Sun Microsystems, Inc.
  *
- * See the file "license.terms" for information on usage and redistribution
- * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+ * See the file "license.terms" for information on usage and redistribution of
+ * this file, and for a DISCLAIMER OF ALL WARRANTIES.
  */
 
 #ifndef _STRING
 #define _STRING
 
-#include <tcl.h>
-
 /*
- * The following #include is needed to define size_t. (This used to
- * include sys/stdtypes.h but that doesn't exist on older versions
- * of SunOS, e.g. 4.0.2, so I'm trying sys/types.h now.... hopefully
- * it exists everywhere)
+ * The following #include is needed to define size_t. (This used to include
+ * sys/stdtypes.h but that doesn't exist on older versions of SunOS, e.g.
+ * 4.0.2, so I'm trying sys/types.h now.... hopefully it exists everywhere)
  */
 
 #include <sys/types.h>
 
 #ifdef __APPLE__
-extern VOID *		memchr _ANSI_ARGS_((CONST VOID *s, int c, size_t n));
+extern void *		memchr(const void *s, int c, size_t n);
 #else
-extern char *		memchr _ANSI_ARGS_((CONST VOID *s, int c, size_t n));
+extern char *		memchr(const void *s, int c, size_t n);
 #endif
-extern int		memcmp _ANSI_ARGS_((CONST VOID *s1, CONST VOID *s2,
-			    size_t n));
-extern char *		memcpy _ANSI_ARGS_((VOID *t, CONST VOID *f, size_t n));
+extern int		memcmp(const void *s1, const void *s2, size_t n);
+extern char *		memcpy(void *t, const void *f, size_t n);
 #ifdef NO_MEMMOVE
-#define memmove(d, s, n) bcopy ((s), (d), (n))
+#define memmove(d,s,n)	(bcopy((s), (d), (n)))
 #else
-extern char *		memmove _ANSI_ARGS_((VOID *t, CONST VOID *f,
-			    size_t n));
+extern char *		memmove(void *t, const void *f, size_t n);
 #endif
-extern char *		memset _ANSI_ARGS_((VOID *s, int c, size_t n));
+extern char *		memset(void *s, int c, size_t n);
 
-extern int		strcasecmp _ANSI_ARGS_((CONST char *s1,
-			    CONST char *s2));
-extern char *		strcat _ANSI_ARGS_((char *dst, CONST char *src));
-extern char *		strchr _ANSI_ARGS_((CONST char *string, int c));
-extern int		strcmp _ANSI_ARGS_((CONST char *s1, CONST char *s2));
-extern char *		strcpy _ANSI_ARGS_((char *dst, CONST char *src));
-extern size_t		strcspn _ANSI_ARGS_((CONST char *string,
-			    CONST char *chars));
-extern char *		strdup _ANSI_ARGS_((CONST char *string));
-extern char *		strerror _ANSI_ARGS_((int error));
-extern size_t		strlen _ANSI_ARGS_((CONST char *string));
-extern int		strncasecmp _ANSI_ARGS_((CONST char *s1,
-			    CONST char *s2, size_t n));
-extern char *		strncat _ANSI_ARGS_((char *dst, CONST char *src,
-			    size_t numChars));
-extern int		strncmp _ANSI_ARGS_((CONST char *s1, CONST char *s2,
-			    size_t nChars));
-extern char *		strncpy _ANSI_ARGS_((char *dst, CONST char *src,
-			    size_t numChars));
-extern char *		strpbrk _ANSI_ARGS_((CONST char *string,
-			    CONST char *chars));
-extern char *		strrchr _ANSI_ARGS_((CONST char *string, int c));
-extern size_t		strspn _ANSI_ARGS_((CONST char *string,
-			    CONST char *chars));
-extern char *		strstr _ANSI_ARGS_((CONST char *string,
-			    CONST char *substring));
-extern char *		strtok _ANSI_ARGS_((char *s, CONST char *delim));
+extern int		strcasecmp(const char *s1, const char *s2);
+extern char *		strcat(char *dst, const char *src);
+extern char *		strchr(const char *string, int c);
+extern int		strcmp(const char *s1, const char *s2);
+extern char *		strcpy(char *dst, const char *src);
+extern size_t		strcspn(const char *string, const char *chars);
+extern char *		strdup(const char *string);
+extern char *		strerror(int error);
+extern size_t		strlen(const char *string);
+extern int		strncasecmp(const char *s1, const char *s2, size_t n);
+extern char *		strncat(char *dst, const char *src, size_t numChars);
+extern int		strncmp(const char *s1, const char *s2, size_t nChars);
+extern char *		strncpy(char *dst, const char *src, size_t numChars);
+extern char *		strpbrk(const char *string, const char *chars);
+extern char *		strrchr(const char *string, int c);
+extern size_t		strspn(const char *string, const char *chars);
+extern char *		strstr(const char *string, const char *substring);
+extern char *		strtok(char *s, const char *delim);
 
 #endif /* _STRING */

compat/strncasecmp.c

@@ -6,16 +6,16 @@
  * Copyright (c) 1988-1993 The Regents of the University of California.
  * Copyright (c) 1995-1996 Sun Microsystems, Inc.
  *
- * See the file "license.terms" for information on usage and redistribution
- * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+ * See the file "license.terms" for information on usage and redistribution of
+ * this file, and for a DISCLAIMER OF ALL WARRANTIES.
  */
 
 #include "tclPort.h"
 
 /*
- * This array is designed for mapping upper and lower case letter
- * together for a case independent comparison.  The mappings are
- * based upon ASCII character sequences.
+ * This array is designed for mapping upper and lower case letter together for
+ * a case independent comparison. The mappings are based upon ASCII character
+ * sequences.
  */
 
 static unsigned char charmap[] = {
@@ -54,14 +54,11 @@ static unsigned char charmap[] = {
 };
 
 /*
- * Here are the prototypes just in case they are not included
- * in tclPort.h.
+ * Here are the prototypes just in case they are not included in tclPort.h.
  */
-int		strncasecmp _ANSI_ARGS_((CONST char *s1,
-			    CONST char *s2, size_t n));
 
-int		strcasecmp _ANSI_ARGS_((CONST char *s1,
-			    CONST char *s2));
+int		strncasecmp(CONST char *s1, CONST char *s2, size_t n);
+int		strcasecmp(CONST char *s1, CONST char *s2);
 
 /*
  *----------------------------------------------------------------------
@@ -71,9 +68,8 @@ int		strcasecmp _ANSI_ARGS_((CONST char *s1,
  *	Compares two strings, ignoring case differences.
  *
  * Results:
- *	Compares two null-terminated strings s1 and s2, returning -1, 0,
- *	or 1 if s1 is lexicographically less than, equal to, or greater
- *	than s2.
+ *	Compares two null-terminated strings s1 and s2, returning -1, 0, or 1
+ *	if s1 is lexicographically less than, equal to, or greater than s2.
  *
  * Side effects:
  *	None.
@@ -82,9 +78,9 @@ int		strcasecmp _ANSI_ARGS_((CONST char *s1,
  */
 
 int
-strcasecmp(s1, s2)
-    CONST char *s1;			/* First string. */
-    CONST char *s2;			/* Second string. */
+strcasecmp(
+    CONST char *s1,		/* First string. */
+    CONST char *s2)		/* Second string. */
 {
     unsigned char u1, u2;
 
@@ -106,9 +102,9 @@ strcasecmp(s1, s2)
  *	Compares two strings, ignoring case differences.
  *
  * Results:
- *	Compares up to length chars of s1 and s2, returning -1, 0, or 1
- *	if s1 is lexicographically less than, equal to, or greater
- *	than s2 over those characters.
+ *	Compares up to length chars of s1 and s2, returning -1, 0, or 1 if s1
+ *	is lexicographically less than, equal to, or greater than s2 over
+ *	those characters.
  *
  * Side effects:
  *	None.
@@ -117,10 +113,10 @@ strcasecmp(s1, s2)
  */
 
 int
-strncasecmp(s1, s2, length)
-    CONST char *s1;		/* First string. */
-    CONST char *s2;		/* Second string. */
-    size_t length;		/* Maximum number of characters to compare
+strncasecmp(
+    CONST char *s1,		/* First string. */
+    CONST char *s2,		/* Second string. */
+    size_t length)		/* Maximum number of characters to compare
 				 * (stop earlier if the end of either string
 				 * is reached). */
 {

compat/strstr.c

@@ -6,11 +6,11 @@
  * Copyright (c) 1988-1993 The Regents of the University of California.
  * Copyright (c) 1994 Sun Microsystems, Inc.
  *
- * See the file "license.terms" for information on usage and redistribution
- * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+ * See the file "license.terms" for information on usage and redistribution of
+ * this file, and for a DISCLAIMER OF ALL WARRANTIES.
  */
 
-#include <tcl.h>
+#include "tcl.h"
 #ifndef NULL
 #define NULL 0
 #endif
@@ -23,12 +23,10 @@
  *	Locate the first instance of a substring in a string.
  *
  * Results:
- *	If string contains substring, the return value is the
- *	location of the first matching instance of substring
- *	in string.  If string doesn't contain substring, the
- *	return value is 0.  Matching is done on an exact
- *	character-for-character basis with no wildcards or special
- *	characters.
+ *	If string contains substring, the return value is the location of the
+ *	first matching instance of substring in string. If string doesn't
+ *	contain substring, the return value is 0. Matching is done on an exact
+ *	character-for-character basis with no wildcards or special characters.
  *
  * Side effects:
  *	None.
@@ -37,15 +35,16 @@
  */
 
 char *
-strstr(string, substring)
-    register char *string;	/* String to search. */
-    char *substring;		/* Substring to try to find in string. */
+strstr(
+    register char *string,	/* String to search. */
+    char *substring)		/* Substring to try to find in string. */
 {
     register char *a, *b;
 
-    /* First scan quickly through the two strings looking for a
-     * single-character match.  When it's found, then compare the
-     * rest of the substring.
+    /*
+     * First scan quickly through the two strings looking for a
+     * single-character match. When it's found, then compare the rest of the
+     * substring.
      */
 
     b = substring;

compat/strtod.c

@@ -11,7 +11,6 @@
  */
 
 #include "tclInt.h"
-#include "tclPort.h"
 #include <ctype.h>
 
 #ifndef TRUE
@@ -61,20 +60,19 @@ static double powersOf10[] = {	/* Table giving binary powers of 10.  Entry */
  */
 
 double
-strtod(string, endPtr)
-    CONST char *string;		/* A decimal ASCII floating-point number,
-				 * optionally preceded by white space.
-				 * Must have form "-I.FE-X", where I is the
-				 * integer part of the mantissa, F is the
-				 * fractional part of the mantissa, and X
-				 * is the exponent.  Either of the signs
-				 * may be "+", "-", or omitted.  Either I
-				 * or F may be omitted, or both.  The decimal
-				 * point isn't necessary unless F is present.
-				 * The "E" may actually be an "e".  E and X
-				 * may both be omitted (but not just one).
-				 */
-    char **endPtr;		/* If non-NULL, store terminating character's
+strtod(
+    CONST char *string,		/* A decimal ASCII floating-point number,
+				 * optionally preceded by white space. Must
+				 * have form "-I.FE-X", where I is the integer
+				 * part of the mantissa, F is the fractional
+				 * part of the mantissa, and X is the
+				 * exponent. Either of the signs may be "+",
+				 * "-", or omitted. Either I or F may be
+				 * omitted, or both. The decimal point isn't
+				 * necessary unless F is present. The "E" may
+				 * actually be an "e". E and X may both be
+				 * omitted (but not just one). */
+    char **endPtr)		/* If non-NULL, store terminating character's
 				 * address here. */
 {
     int sign, expSign = FALSE;
@@ -83,19 +81,19 @@ strtod(string, endPtr)
     register int c;
     int exp = 0;		/* Exponent read from "EX" field. */
     int fracExp = 0;		/* Exponent that derives from the fractional
-				 * part.  Under normal circumstatnces, it is
+				 * part. Under normal circumstatnces, it is
 				 * the negative of the number of digits in F.
 				 * However, if I is very long, the last digits
 				 * of I get dropped (otherwise a long I with a
 				 * large negative exponent could cause an
-				 * unnecessary overflow on I alone).  In this
+				 * unnecessary overflow on I alone). In this
 				 * case, fracExp is incremented one for each
 				 * dropped digit. */
     int mantSize;		/* Number of digits in mantissa. */
     int decPt;			/* Number of mantissa digits BEFORE decimal
 				 * point. */
-    CONST char *pExp;		/* Temporarily holds location of exponent
-				 * in string. */
+    CONST char *pExp;		/* Temporarily holds location of exponent in
+				 * string. */
 
     /*
      * Strip off leading blanks and check for a sign.
@@ -134,10 +132,10 @@ strtod(string, endPtr)
     }
 
     /*
-     * Now suck up the digits in the mantissa.  Use two integers to
-     * collect 9 digits each (this is faster than using floating-point).
-     * If the mantissa has more than 18 digits, ignore the extras, since
-     * they can't affect the value anyway.
+     * Now suck up the digits in the mantissa. Use two integers to collect 9
+     * digits each (this is faster than using floating-point). If the mantissa
+     * has more than 18 digits, ignore the extras, since they can't affect the
+     * value anyway.
      */
     
     pExp  = p;
@@ -145,7 +143,7 @@ strtod(string, endPtr)
     if (decPt < 0) {
 	decPt = mantSize;
     } else {
-	mantSize -= 1;			/* One of the digits was the point. */
+	mantSize -= 1;		/* One of the digits was the point. */
     }
     if (mantSize > 18) {
 	fracExp = decPt - 18;
@@ -159,9 +157,9 @@ strtod(string, endPtr)
 	goto done;
     } else {
 	int frac1, frac2;
+
 	frac1 = 0;
-	for ( ; mantSize > 9; mantSize -= 1)
-	{
+	for ( ; mantSize > 9; mantSize -= 1) {
 	    c = *p;
 	    p += 1;
 	    if (c == '.') {
@@ -171,8 +169,7 @@ strtod(string, endPtr)
 	    frac1 = 10*frac1 + (c - '0');
 	}
 	frac2 = 0;
-	for (; mantSize > 0; mantSize -= 1)
-	{
+	for (; mantSize > 0; mantSize -= 1) {
 	    c = *p;
 	    p += 1;
 	    if (c == '.') {
@@ -216,10 +213,9 @@ strtod(string, endPtr)
     }
 
     /*
-     * Generate a floating-point number that represents the exponent.
-     * Do this by processing the exponent one bit at a time to combine
-     * many powers of 2 of 10. Then combine the exponent with the
-     * fraction.
+     * Generate a floating-point number that represents the exponent. Do this
+     * by processing the exponent one bit at a time to combine many powers of
+     * 2 of 10. Then combine the exponent with the fraction.
      */
     
     if (exp < 0) {
@@ -244,7 +240,7 @@ strtod(string, endPtr)
 	fraction *= dblExp;
     }
 
-done:
+  done:
     if (endPtr != NULL) {
 	*endPtr = (char *) p;
     }

compat/strtol.c

@@ -6,14 +6,12 @@
  * Copyright (c) 1988 The Regents of the University of California.
  * Copyright (c) 1994 Sun Microsystems, Inc.
  *
- * See the file "license.terms" for information on usage and redistribution
- * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+ * See the file "license.terms" for information on usage and redistribution of
+ * this file, and for a DISCLAIMER OF ALL WARRANTIES.
  */
 
 #include <ctype.h>
 #include "tclInt.h"
-#include "tclPort.h"
-
 
 /*
  *----------------------------------------------------------------------
@@ -23,11 +21,10 @@
  *	Convert an ASCII string into an integer.
  *
  * Results:
- *	The return value is the integer equivalent of string.  If endPtr
- *	is non-NULL, then *endPtr is filled in with the character
- *	after the last one that was part of the integer.  If string
- *	doesn't contain a valid integer value, then zero is returned
- *	and *endPtr is set to string.
+ *	The return value is the integer equivalent of string. If endPtr is
+ *	non-NULL, then *endPtr is filled in with the character after the last
+ *	one that was part of the integer. If string doesn't contain a valid
+ *	integer value, then zero is returned and *endPtr is set to string.
  *
  * Side effects:
  *	None.
@@ -36,20 +33,18 @@
  */
 
 long int
-strtol(string, endPtr, base)
-    CONST char *string;		/* String of ASCII digits, possibly
-				 * preceded by white space.  For bases
-				 * greater than 10, either lower- or
-				 * upper-case digits may be used.
-				 */
-    char **endPtr;		/* Where to store address of terminating
+strtol(
+    CONST char *string,		/* String of ASCII digits, possibly preceded
+				 * by white space. For bases greater than 10,
+				 * either lower- or upper-case digits may be
+				 * used. */
+    char **endPtr,		/* Where to store address of terminating
 				 * character, or NULL. */
-    int base;			/* Base for conversion.  Must be less
-				 * than 37.  If 0, then the base is chosen
-				 * from the leading characters of string:
-				 * "0x" means hex, "0" means octal, anything
-				 * else means decimal.
-				 */
+    int base)			/* Base for conversion. Must be less than 37.
+				 * If 0, then the base is chosen from the
+				 * leading characters of string: "0x" means
+				 * hex, "0" means octal, anything else means
+				 * decimal. */
 {
     register CONST char *p;
     long result;

compat/strtoll.c

@@ -1,109 +0,0 @@
-/* 
- * strtoll.c --
- *
- *	Source code for the "strtoll" library procedure.
- *
- * Copyright (c) 1988 The Regents of the University of California.
- * Copyright (c) 1994 Sun Microsystems, Inc.
- *
- * See the file "license.terms" for information on usage and redistribution
- * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
- */
-
-#include "tcl.h"
-#include "tclPort.h"
-#include <ctype.h>
-
-#define TCL_WIDEINT_MAX	(((Tcl_WideUInt)Tcl_LongAsWide(-1))>>1)
-
-
-/*
- *----------------------------------------------------------------------
- *
- * strtoll --
- *
- *	Convert an ASCII string into an integer.
- *
- * Results:
- *	The return value is the integer equivalent of string.  If endPtr
- *	is non-NULL, then *endPtr is filled in with the character
- *	after the last one that was part of the integer.  If string
- *	doesn't contain a valid integer value, then zero is returned
- *	and *endPtr is set to string.
- *
- * Side effects:
- *	None.
- *
- *----------------------------------------------------------------------
- */
-
-#if TCL_WIDE_INT_IS_LONG
-long long
-#else
-Tcl_WideInt
-#endif
-strtoll(string, endPtr, base)
-    CONST char *string;		/* String of ASCII digits, possibly
-				 * preceded by white space.  For bases
-				 * greater than 10, either lower- or
-				 * upper-case digits may be used.
-				 */
-    char **endPtr;		/* Where to store address of terminating
-				 * character, or NULL. */
-    int base;			/* Base for conversion.  Must be less
-				 * than 37.  If 0, then the base is chosen
-				 * from the leading characters of string:
-				 * "0x" means hex, "0" means octal, anything
-				 * else means decimal.
-				 */
-{
-    register CONST char *p;
-    Tcl_WideInt result = Tcl_LongAsWide(0);
-    Tcl_WideUInt uwResult;
-
-    /*
-     * Skip any leading blanks.
-     */
-
-    p = string;
-    while (isspace(UCHAR(*p))) {
-	p += 1;
-    }
-
-    /*
-     * Check for a sign.
-     */
-
-    errno = 0;
-    if (*p == '-') {
-	p += 1;
-	uwResult = strtoull(p, endPtr, base);
-	if (errno != ERANGE) {
-	    if (uwResult > TCL_WIDEINT_MAX+1) {
-		errno = ERANGE;
-		return Tcl_LongAsWide(-1);
-	    } else if (uwResult > TCL_WIDEINT_MAX) {
-		return ~((Tcl_WideInt)TCL_WIDEINT_MAX);
-	    } else {
-		result = -((Tcl_WideInt) uwResult);
-	    }
-	}
-    } else {
-	if (*p == '+') {
-	    p += 1;
-	}
-	uwResult = strtoull(p, endPtr, base);
-	if (errno != ERANGE) {
-	    if (uwResult > TCL_WIDEINT_MAX) {
-		errno = ERANGE;
-		return Tcl_LongAsWide(-1);
-	    } else {
-		result = uwResult;
-	    }
-	}
-    }
-    if ((result == 0) && (endPtr != 0) && (*endPtr == p)) {
-	*endPtr = (char *) string;
-    }
-    return result;
-}

compat/strtoul.c

@@ -6,17 +6,16 @@
  * Copyright (c) 1988 The Regents of the University of California.
  * Copyright (c) 1994 Sun Microsystems, Inc.
  *
- * See the file "license.terms" for information on usage and redistribution
- * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+ * See the file "license.terms" for information on usage and redistribution of
+ * this file, and for a DISCLAIMER OF ALL WARRANTIES.
  */
 
 #include "tclInt.h"
-#include "tclPort.h"
 
 /*
- * The table below is used to convert from ASCII digits to a
- * numerical equivalent.  It maps from '0' through 'z' to integers
- * (100 for non-digit characters).
+ * The table below is used to convert from ASCII digits to a numerical
+ * equivalent. It maps from '0' through 'z' to integers (100 for non-digit
+ * characters).
  */
 
 static char cvtIn[] = {
@@ -38,11 +37,10 @@ static char cvtIn[] = {
  *	Convert an ASCII string into an integer.
  *
  * Results:
- *	The return value is the integer equivalent of string.  If endPtr
- *	is non-NULL, then *endPtr is filled in with the character
- *	after the last one that was part of the integer.  If string
- *	doesn't contain a valid integer value, then zero is returned
- *	and *endPtr is set to string.
+ *	The return value is the integer equivalent of string. If endPtr is
+ *	non-NULL, then *endPtr is filled in with the character after the last
+ *	one that was part of the integer. If string doesn't contain a valid
+ *	integer value, then zero is returned and *endPtr is set to string.
  *
  * Side effects:
  *	None.
@@ -51,20 +49,18 @@ static char cvtIn[] = {
  */
 
 unsigned long int
-strtoul(string, endPtr, base)
-    CONST char *string;		/* String of ASCII digits, possibly
-				 * preceded by white space.  For bases
-				 * greater than 10, either lower- or
-				 * upper-case digits may be used.
-				 */
-    char **endPtr;		/* Where to store address of terminating
+strtoul(
+    CONST char *string,		/* String of ASCII digits, possibly preceded
+				 * by white space. For bases greater than 10,
+				 * either lower- or upper-case digits may be
+				 * used. */
+    char **endPtr,		/* Where to store address of terminating
 				 * character, or NULL. */
-    int base;			/* Base for conversion.  Must be less
-				 * than 37.  If 0, then the base is chosen
-				 * from the leading characters of string:
-				 * "0x" means hex, "0" means octal, anything
-				 * else means decimal.
-				 */
+    int base)			/* Base for conversion.  Must be less than 37.
+				 * If 0, then the base is chosen from the
+				 * leading characters of string: "0x" means
+				 * hex, "0" means octal, anything else means
+				 * decimal. */
 {
     register CONST char *p;
     register unsigned long int result = 0;
@@ -91,31 +87,29 @@ strtoul(string, endPtr, base)
     }
 
     /*
-     * If no base was provided, pick one from the leading characters
-     * of the string.
+     * If no base was provided, pick one from the leading characters of the
+     * string.
      */
     
-    if (base == 0)
-    {
+    if (base == 0) {
 	if (*p == '0') {
 	    p += 1;
 	    if ((*p == 'x') || (*p == 'X')) {
 		p += 1;
 		base = 16;
 	    } else {
-
 		/*
-		 * Must set anyDigits here, otherwise "0" produces a
-		 * "no digits" error.
+		 * Must set anyDigits here, otherwise "0" produces a "no
+		 * digits" error.
 		 */
 
 		anyDigits = 1;
 		base = 8;
 	    }
+	} else {
+	    base = 10;
 	}
-	else base = 10;
     } else if (base == 16) {
-
 	/*
 	 * Skip a leading "0x" from hex numbers.
 	 */
@@ -126,12 +120,13 @@ strtoul(string, endPtr, base)
     }
 
     /*
-     * Sorry this code is so messy, but speed seems important.  Do
-     * different things for base 8, 10, 16, and other.
+     * Sorry this code is so messy, but speed seems important. Do different
+     * things for base 8, 10, 16, and other.
      */
 
     if (base == 8) {
 	unsigned long maxres = ULONG_MAX >> 3;
+
 	for ( ; ; p += 1) {
 	    digit = *p - '0';
 	    if (digit > 7) {
@@ -145,6 +140,7 @@ strtoul(string, endPtr, base)
 	}
     } else if (base == 10) {
 	unsigned long maxres = ULONG_MAX / 10;
+
 	for ( ; ; p += 1) {
 	    digit = *p - '0';
 	    if (digit > 9) {
@@ -158,6 +154,7 @@ strtoul(string, endPtr, base)
 	}
     } else if (base == 16) {
 	unsigned long maxres = ULONG_MAX >> 4;
+
 	for ( ; ; p += 1) {
 	    digit = *p - '0';
 	    if (digit > ('z' - '0')) {
@@ -173,8 +170,9 @@ strtoul(string, endPtr, base)
 	    result += digit;
 	    anyDigits = 1;
 	}
-    } else if ( base >= 2 && base <= 36 ) {
+    } else if (base >= 2 && base <= 36) {
 	unsigned long maxres = ULONG_MAX / base;
+
 	for ( ; ; p += 1) {
 	    digit = *p - '0';
 	    if (digit > ('z' - '0')) {

compat/strtoull.c

@@ -1,259 +0,0 @@
-/* 
- * strtoull.c --
- *
- *	Source code for the "strtoull" library procedure.
- *
- * Copyright (c) 1988 The Regents of the University of California.
- * Copyright (c) 1994 Sun Microsystems, Inc.
- *
- * See the file "license.terms" for information on usage and redistribution
- * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
- */
-
-#include "tcl.h"
-#include "tclPort.h"
-#include <ctype.h>
-
-/*
- * The table below is used to convert from ASCII digits to a
- * numerical equivalent.  It maps from '0' through 'z' to integers
- * (100 for non-digit characters).
- */
-
-static char cvtIn[] = {
-    0, 1, 2, 3, 4, 5, 6, 7, 8, 9,		/* '0' - '9' */
-    100, 100, 100, 100, 100, 100, 100,		/* punctuation */
-    10, 11, 12, 13, 14, 15, 16, 17, 18, 19,	/* 'A' - 'Z' */
-    20, 21, 22, 23, 24, 25, 26, 27, 28, 29,
-    30, 31, 32, 33, 34, 35,
-    100, 100, 100, 100, 100, 100,		/* punctuation */
-    10, 11, 12, 13, 14, 15, 16, 17, 18, 19,	/* 'a' - 'z' */
-    20, 21, 22, 23, 24, 25, 26, 27, 28, 29,
-    30, 31, 32, 33, 34, 35};
-
-
-/*
- *----------------------------------------------------------------------
- *
- * strtoull --
- *
- *	Convert an ASCII string into an integer.
- *
- * Results:
- *	The return value is the integer equivalent of string.  If endPtr
- *	is non-NULL, then *endPtr is filled in with the character
- *	after the last one that was part of the integer.  If string
- *	doesn't contain a valid integer value, then zero is returned
- *	and *endPtr is set to string.
- *
- * Side effects:
- *	None.
- *
- *----------------------------------------------------------------------
- */
-
-#if TCL_WIDE_INT_IS_LONG
-unsigned long long
-#else
-Tcl_WideUInt
-#endif
-strtoull(string, endPtr, base)
-    CONST char *string;		/* String of ASCII digits, possibly
-				 * preceded by white space.  For bases
-				 * greater than 10, either lower- or
-				 * upper-case digits may be used.
-				 */
-    char **endPtr;		/* Where to store address of terminating
-				 * character, or NULL. */
-    int base;			/* Base for conversion.  Must be less
-				 * than 37.  If 0, then the base is chosen
-				 * from the leading characters of string:
-				 * "0x" means hex, "0" means octal, anything
-				 * else means decimal.
-				 */
-{
-    register CONST char *p;
-    register Tcl_WideUInt result = 0;
-    register unsigned digit;
-    register Tcl_WideUInt shifted;
-    int anyDigits = 0, negative = 0;
-
-    /*
-     * Skip any leading blanks.
-     */
-
-    p = string;
-    while (isspace(UCHAR(*p))) {	/* INTL: locale-dependent */
-	p += 1;
-    }
-
-    /*
-     * Check for a sign.
-     */
-
-    if (*p == '-') {
-	p += 1;
-	negative = 1;
-    } else {
-	if (*p == '+') {
-	    p += 1;
-	}
-    }
-
-    /*
-     * If no base was provided, pick one from the leading characters
-     * of the string.
-     */
-    
-    if (base == 0) {
-	if (*p == '0') {
-	    p += 1;
-	    if (*p == 'x' || *p == 'X') {
-		p += 1;
-		base = 16;
-	    } else {
-
-		/*
-		 * Must set anyDigits here, otherwise "0" produces a
-		 * "no digits" error.
-		 */
-
-		anyDigits = 1;
-		base = 8;
-	    }
-	} else {
-	    base = 10;
-	}
-    } else if (base == 16) {
-
-	/*
-	 * Skip a leading "0x" from hex numbers.
-	 */
-
-	if ((p[0] == '0') && (p[1] == 'x' || *p == 'X')) {
-	    p += 2;
-	}
-    }
-
-    /*
-     * Sorry this code is so messy, but speed seems important.  Do
-     * different things for base 8, 10, 16, and other.
-     */
-
-    if (base == 8) {
-	for ( ; ; p += 1) {
-	    digit = *p - '0';
-	    if (digit > 7) {
-		break;
-	    }
-	    shifted = result << 3;
-	    if ((shifted >> 3) != result) {
-		goto overflow;
-	    }
-	    result = shifted + digit;
-	    if ( result < shifted ) {
-		goto overflow;
-	    }
-	    anyDigits = 1;
-	}
-    } else if (base == 10) {
-	for ( ; ; p += 1) {
-	    digit = *p - '0';
-	    if (digit > 9) {
-		break;
-	    }
-	    shifted = 10 * result;
-	    if ((shifted / 10) != result) {
-		goto overflow;
-	    }
-	    result = shifted + digit;
-	    if ( result < shifted ) {
-		goto overflow;
-	    }
-	    anyDigits = 1;
-	}
-    } else if (base == 16) {
-	for ( ; ; p += 1) {
-	    digit = *p - '0';
-	    if (digit > ('z' - '0')) {
-		break;
-	    }
-	    digit = cvtIn[digit];
-	    if (digit > 15) {
-		break;
-	    }
-	    shifted = result << 4;
-	    if ((shifted >> 4) != result) {
-		goto overflow;
-	    }
-	    result = shifted + digit;
-	    if ( result < shifted ) {
-		goto overflow;
-	    }
-	    anyDigits = 1;
-	}
-    } else if ( base >= 2 && base <= 36 ) {
-	for ( ; ; p += 1) {
-	    digit = *p - '0';
-	    if (digit > ('z' - '0')) {
-		break;
-	    }
-	    digit = cvtIn[digit];
-	    if (digit >= (unsigned) base) {
-		break;
-	    }
-	    shifted = result * base;
-	    if ((shifted/base) != result) {
-		goto overflow;
-	    }
-	    result = shifted + digit;
-	    if ( result < shifted ) {
-		goto overflow;
-	    }
-	    anyDigits = 1;
-	}
-    }
-
-    /*
-     * Negate if we found a '-' earlier.
-     */
-
-    if (negative) {
-	result = (Tcl_WideUInt)(-((Tcl_WideInt)result));
-    }
-
-    /*
-     * See if there were any digits at all.
-     */
-
-    if (!anyDigits) {
-	p = string;
-    }
-
-    if (endPtr != 0) {
-	*endPtr = (char *) p;
-    }
-
-    return result;
-
-    /*
-     * On overflow generate the right output
-     */
-
- overflow:
-    errno = ERANGE;
-    if (endPtr != 0) {
-	for ( ; ; p += 1) {
-	    digit = *p - '0';
-	    if (digit > ('z' - '0')) {
-		break;
-	    }
-	    digit = cvtIn[digit];
-	    if (digit >= (unsigned) base) {
-		break;
-	    }
-	}
-	*endPtr = (char *) p;
-    }
-    return (Tcl_WideUInt)Tcl_LongAsWide(-1);
-}

compat/tclErrno.h

@@ -1,97 +0,0 @@
-/*
- * tclErrno.h --
- *
- *	This header file contains the various POSIX errno definitions that
- *	are used by Tcl.  This file is derived from the spec POSIX 2.4 and
- *	previous implementations for Berkeley UNIX.
- *
- * Copyright (c) 1982, 1986, 1989 Regents of the University of California.
- * Copyright (c) 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.
- */
-
-extern int errno;		/* global error number */
-
-#define	EPERM		1	/* Operation not permitted */
-#define	ENOENT		2	/* No such file or directory */
-#define	ESRCH		3	/* No such process */
-#define	EINTR		4	/* Interrupted system call */
-#define	EIO		5	/* Input/output error */
-#define	ENXIO		6	/* Device not configured */
-#define	E2BIG		7	/* Argument list too long */
-#define	ENOEXEC		8	/* Exec format error */
-#define	EBADF		9	/* Bad file descriptor */
-#define	ECHILD		10	/* No child processes */
-#define	EDEADLK		11	/* Resource deadlock avoided */
-				/* 11 was EAGAIN */
-#define	ENOMEM		12	/* Cannot allocate memory */
-#define	EACCES		13	/* Permission denied */
-#define	EFAULT		14	/* Bad address */
-#define	ENOTBLK		15	/* Block device required */
-#define	EBUSY		16	/* Device busy */
-#define	EEXIST		17	/* File exists */
-#define	EXDEV		18	/* Cross-device link */
-#define	ENODEV		19	/* Operation not supported by device */
-#define	ENOTDIR		20	/* Not a directory */
-#define	EISDIR		21	/* Is a directory */
-#define	EINVAL		22	/* Invalid argument */
-#define	ENFILE		23	/* Too many open files in system */
-#define	EMFILE		24	/* Too many open files */
-#define	ENOTTY		25	/* Inappropriate ioctl for device */
-#define	ETXTBSY		26	/* Text file busy */
-#define	EFBIG		27	/* File too large */
-#define	ENOSPC		28	/* No space left on device */
-#define	ESPIPE		29	/* Illegal seek */
-#define	EROFS		30	/* Read-only file system */
-#define	EMLINK		31	/* Too many links */
-#define	EPIPE		32	/* Broken pipe */
-#define	EDOM		33	/* Numerical argument out of domain */
-#define	ERANGE		34	/* Result too large */
-#define	EAGAIN		35	/* Resource temporarily unavailable */
-#define	EWOULDBLOCK	EAGAIN	/* Operation would block */
-#define	EINPROGRESS	36	/* Operation now in progress */
-#define	EALREADY	37	/* Operation already in progress */
-#define	ENOTSOCK	38	/* Socket operation on non-socket */
-#define	EDESTADDRREQ	39	/* Destination address required */
-#define	EMSGSIZE	40	/* Message too long */
-#define	EPROTOTYPE	41	/* Protocol wrong type for socket */
-#define	ENOPROTOOPT	42	/* Protocol not available */
-#define	EPROTONOSUPPORT	43	/* Protocol not supported */
-#define	ESOCKTNOSUPPORT	44	/* Socket type not supported */
-#define	EOPNOTSUPP	45	/* Operation not supported on socket */
-#define	EPFNOSUPPORT	46	/* Protocol family not supported */
-#define	EAFNOSUPPORT	47	/* Address family not supported by protocol family */
-#define	EADDRINUSE	48	/* Address already in use */
-#define	EADDRNOTAVAIL	49	/* Can't assign requested address */
-#define	ENETDOWN	50	/* Network is down */
-#define	ENETUNREACH	51	/* Network is unreachable */
-#define	ENETRESET	52	/* Network dropped connection on reset */
-#define	ECONNABORTED	53	/* Software caused connection abort */
-#define	ECONNRESET	54	/* Connection reset by peer */
-#define	ENOBUFS		55	/* No buffer space available */
-#define	EISCONN		56	/* Socket is already connected */
-#define	ENOTCONN	57	/* Socket is not connected */
-#define	ESHUTDOWN	58	/* Can't send after socket shutdown */
-#define	ETOOMANYREFS	59	/* Too many references: can't splice */
-#define	ETIMEDOUT	60	/* Connection timed out */
-#define	ECONNREFUSED	61	/* Connection refused */
-#define	ELOOP		62	/* Too many levels of symbolic links */
-#define	ENAMETOOLONG	63	/* File name too long */
-#define	EHOSTDOWN	64	/* Host is down */
-#define	EHOSTUNREACH	65	/* No route to host */
-#define	ENOTEMPTY	66	/* Directory not empty */
-#define	EPROCLIM	67	/* Too many processes */
-#define	EUSERS		68	/* Too many users */
-#define	EDQUOT		69	/* Disc quota exceeded */
-#define	ESTALE		70	/* Stale NFS file handle */
-#define	EREMOTE		71	/* Too many levels of remote in path */
-#define	EBADRPC		72	/* RPC struct is bad */
-#define	ERPCMISMATCH	73	/* RPC version wrong */
-#define	EPROGUNAVAIL	74	/* RPC prog. not avail */
-#define	EPROGMISMATCH	75	/* Program version wrong */
-#define	EPROCUNAVAIL	76	/* Bad procedure for program */
-#define	ENOLCK		77	/* No locks available */
-#define	ENOSYS		78	/* Function not implemented */
-#define	EOVERFLOW	79	/* Value too large to be stored in data type */

compat/tmpnam.c

@@ -1,40 +0,0 @@
-/*
- * Copyright (c) 1988 Regents of the University of California.
- * All rights reserved.
- *
- * Redistribution and use in source and binary forms are permitted
- * provided that this notice is preserved and that due credit is given
- * to the University of California at Berkeley. The name of the University
- * may not be used to endorse or promote products derived from this
- * software without specific written prior permission. This software
- * is provided ``as is'' without express or implied warranty.
- */
-
-#include <sys/param.h>
-#include <sys/stat.h>
-#include <sys/file.h>
-#include <stdio.h>
-
-/*
- * Use /tmp instead of /usr/tmp, because L_tmpname is only 14 chars
- * on some machines (like NeXT machines) and /usr/tmp will cause
- * buffer overflows.
- */
-
-#ifdef P_tmpdir
-#   undef P_tmpdir
-#endif
-#define	P_tmpdir	"/tmp"
-
-char *
-tmpnam(s)
-	char *s;
-{
-	static char name[50];
-	char *mktemp();
-
-	if (!s)
-		s = name;
-	(void)sprintf(s, "%s/XXXXXX", P_tmpdir);
-	return(mktemp(s));
-}

compat/unistd.h

@@ -1,82 +1,76 @@
 /*
  * unistd.h --
  *
- *      Macros, CONSTants and prototypes for Posix conformance.
+ *      Macros, constants and prototypes for Posix conformance.
  *
- * Copyright 1989 Regents of the University of California
- * Permission to use, copy, modify, and distribute this
- * software and its documentation for any purpose and without
- * fee is hereby granted, provided that the above copyright
- * notice appear in all copies.  The University of California
- * makes no representations about the suitability of this
- * software for any purpose.  It is provided "as is" without
- * express or implied warranty.
+ * Copyright 1989 Regents of the University of California Permission to use,
+ * copy, modify, and distribute this software and its documentation for any
+ * purpose and without fee is hereby granted, provided that the above
+ * copyright notice appear in all copies. The University of California makes
+ * no representations about the suitability of this software for any purpose.
+ * It is provided "as is" without express or implied warranty.
  */
 
 #ifndef _UNISTD
 #define _UNISTD
 
 #include <sys/types.h>
-#ifndef _TCL
-#   include "tcl.h"
-#endif
 
 #ifndef NULL
 #define NULL    0
 #endif
 
 /* 
- * Strict POSIX stuff goes here.  Extensions go down below, in the 
- * ifndef _POSIX_SOURCE section.
+ * Strict POSIX stuff goes here. Extensions go down below, in the ifndef
+ * _POSIX_SOURCE section.
  */
 
-extern void _exit _ANSI_ARGS_((int status));
-extern int access _ANSI_ARGS_((CONST char *path, int mode));
-extern int chdir _ANSI_ARGS_((CONST char *path));
-extern int chown _ANSI_ARGS_((CONST char *path, uid_t owner, gid_t group));
-extern int close _ANSI_ARGS_((int fd));
-extern int dup _ANSI_ARGS_((int oldfd));
-extern int dup2 _ANSI_ARGS_((int oldfd, int newfd));
-extern int execl _ANSI_ARGS_((CONST char *path, ...));
-extern int execle _ANSI_ARGS_((CONST char *path, ...));
-extern int execlp _ANSI_ARGS_((CONST char *file, ...));
-extern int execv _ANSI_ARGS_((CONST char *path, char **argv));
-extern int execve _ANSI_ARGS_((CONST char *path, char **argv, char **envp));
-extern int execvp _ANSI_ARGS_((CONST char *file, char **argv));
-extern pid_t fork _ANSI_ARGS_((void));
-extern char *getcwd _ANSI_ARGS_((char *buf, size_t size));
-extern gid_t getegid _ANSI_ARGS_((void));
-extern uid_t geteuid _ANSI_ARGS_((void));
-extern gid_t getgid _ANSI_ARGS_((void));
-extern int getgroups _ANSI_ARGS_((int bufSize, int *buffer));
-extern pid_t getpid _ANSI_ARGS_((void));
-extern uid_t getuid _ANSI_ARGS_((void));
-extern int isatty _ANSI_ARGS_((int fd));
-extern long lseek _ANSI_ARGS_((int fd, long offset, int whence));
-extern int pipe _ANSI_ARGS_((int *fildes));
-extern int read _ANSI_ARGS_((int fd, char *buf, size_t size));
-extern int setgid _ANSI_ARGS_((gid_t group));
-extern int setuid _ANSI_ARGS_((uid_t user));
-extern unsigned sleep _ANSI_ARGS_ ((unsigned seconds));
-extern char *ttyname _ANSI_ARGS_((int fd));
-extern int unlink _ANSI_ARGS_((CONST char *path));
-extern int write _ANSI_ARGS_((int fd, CONST char *buf, size_t size));
+extern void		_exit(int status);
+extern int		access(const char *path, int mode);
+extern int		chdir(const char *path);
+extern int		chown(const char *path, uid_t owner, gid_t group);
+extern int		close(int fd);
+extern int		dup(int oldfd);
+extern int		dup2(int oldfd, int newfd);
+extern int		execl(const char *path, ...);
+extern int		execle(const char *path, ...);
+extern int		execlp(const char *file, ...);
+extern int		execv(const char *path, char **argv);
+extern int		execve(const char *path, char **argv, char **envp);
+extern int		execvpw(const char *file, char **argv);
+extern pid_t		fork(void);
+extern char *		getcwd(char *buf, size_t size);
+extern gid_t		getegid(void);
+extern uid_t		geteuid(void);
+extern gid_t		getgid(void);
+extern int		getgroups(int bufSize, int *buffer);
+extern pid_t		getpid(void);
+extern uid_t		getuid(void);
+extern int		isatty(int fd);
+extern long		lseek(int fd, long offset, int whence);
+extern int		pipe(int *fildes);
+extern int		read(int fd, char *buf, size_t size);
+extern int		setgid(gid_t group);
+extern int		setuid(uid_t user);
+extern unsigned		sleep(unsigned seconds);
+extern char *		ttyname(int fd);
+extern int		unlink(const char *path);
+extern int		write(int fd, const char *buf, size_t size);
 
 #ifndef	_POSIX_SOURCE
-extern char *crypt _ANSI_ARGS_((CONST char *, CONST char *));
-extern int fchown _ANSI_ARGS_((int fd, uid_t owner, gid_t group));
-extern int flock _ANSI_ARGS_((int fd, int operation));
-extern int ftruncate _ANSI_ARGS_((int fd, unsigned long length));
-extern int ioctl _ANSI_ARGS_((int fd, int request, ...));
-extern int readlink _ANSI_ARGS_((CONST char *path, char *buf, int bufsize));
-extern int setegid _ANSI_ARGS_((gid_t group));
-extern int seteuid _ANSI_ARGS_((uid_t user));
-extern int setreuid _ANSI_ARGS_((int ruid, int euid));
-extern int symlink _ANSI_ARGS_((CONST char *, CONST char *));
-extern int ttyslot _ANSI_ARGS_((void));
-extern int truncate _ANSI_ARGS_((CONST char *path, unsigned long length));
-extern int vfork _ANSI_ARGS_((void));
+extern char *		crypt(const char *, const char *);
+extern int		fchown(int fd, uid_t owner, gid_t group);
+extern int		flock(int fd, int operation);
+extern int		ftruncate(int fd, unsigned long length);
+extern int		ioctl(int fd, int request, ...);
+extern int		readlink(const char *path, char *buf, int bufsize);
+extern int		setegid(gid_t group);
+extern int		seteuidw(uid_t user);
+extern int		setreuid(int ruid, int euid);
+extern int		symlink(const char *, const char *);
+extern int		ttyslot(void);
+extern int		truncate(const char *path, unsigned long length);
+extern int		vfork(void);
 #endif /* _POSIX_SOURCE */
 
 #endif /* _UNISTD */
-

compat/waitpid.c

@@ -1,19 +1,17 @@
 /* 
  * waitpid.c --
  *
- *	This procedure emulates the POSIX waitpid kernel call on
- *	BSD systems that don't have waitpid but do have wait3.
- *	This code is based on a prototype version written by
- *	Mark Diekhans and Karl Lehenbauer.
+ *	This procedure emulates the POSIX waitpid kernel call on BSD systems
+ *	that don't have waitpid but do have wait3. This code is based on a
+ *	prototype version written by Mark Diekhans and Karl Lehenbauer.
  *
  * Copyright (c) 1993 The Regents of the University of California.
  * Copyright (c) 1994 Sun Microsystems, Inc.
  *
- * See the file "license.terms" for information on usage and redistribution
- * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+ * See the file "license.terms" for information on usage and redistribution of
+ * this file, and for a DISCLAIMER OF ALL WARRANTIES.
  */
 
-#include "tclInt.h"
 #include "tclPort.h"
 
 #ifndef pid_t
@@ -21,40 +19,37 @@
 #endif
 
 /*
- * A linked list of the following structures is used to keep track
- * of processes for which we received notification from the kernel,
- * but the application hasn't waited for them yet (this can happen
- * because wait may not return the process we really want).  We
- * save the information here until the application finally does
- * wait for the process.
+ * A linked list of the following structures is used to keep track of
+ * processes for which we received notification from the kernel, but the
+ * application hasn't waited for them yet (this can happen because wait may
+ * not return the process we really want). We save the information here until
+ * the application finally does wait for the process.
  */
 
 typedef struct WaitInfo {
-    pid_t pid;				/* Pid of process that exited. */
-    WAIT_STATUS_TYPE status;		/* Status returned when child exited
-					 * or suspended. */
-    struct WaitInfo *nextPtr;		/* Next in list of exited processes. */
+    pid_t pid;			/* Pid of process that exited. */
+    WAIT_STATUS_TYPE status;	/* Status returned when child exited or
+				 * suspended. */
+    struct WaitInfo *nextPtr;	/* Next in list of exited processes. */
 } WaitInfo;
 
-static WaitInfo *deadList = NULL;	/* First in list of all dead
-					 * processes. */
+static WaitInfo *deadList = NULL;
+				/* First in list of all dead processes. */
 
 /*
  *----------------------------------------------------------------------
  *
  * waitpid --
  *
- *	This procedure emulates the functionality of the POSIX
- *	waitpid kernel call, using the BSD wait3 kernel call.
- *	Note:  it doesn't emulate absolutely all of the waitpid
- *	functionality, in that it doesn't support pid's of 0
- *	or < -1.
+ *	This procedure emulates the functionality of the POSIX waitpid kernel
+ *	call, using the BSD wait3 kernel call. Note: it doesn't emulate
+ *	absolutely all of the waitpid functionality, in that it doesn't
+ *	support pid's of 0 or < -1.
  *
  * Results:
- *	-1 is returned if there is an error in the wait kernel call.
- *	Otherwise the pid of an exited or suspended process is
- *	returned and *statusPtr is set to the status value of the
- *	process.
+ *	-1 is returned if there is an error in the wait kernel call. Otherwise
+ *	the pid of an exited or suspended process is returned and *statusPtr
+ *	is set to the status value of the process.
  *
  * Side effects:
  *	None.
@@ -67,12 +62,12 @@ static WaitInfo *deadList = NULL;	/* First in list of all dead
 #endif
 
 pid_t
-waitpid(pid, statusPtr, options)
-    pid_t pid;			/* The pid to wait on.  Must be -1 or
-				 * greater than zero. */
-    int *statusPtr;		/* Where to store wait status for the
+waitpid(
+    pid_t pid,			/* The pid to wait on. Must be -1 or greater
+				 * than zero. */
+    int *statusPtr,		/* Where to store wait status for the
 				 * process. */
-    int options;		/* OR'ed combination of WNOHANG and
+    int options)		/* OR'ed combination of WNOHANG and
 				 * WUNTRACED. */
 {
     register WaitInfo *waitPtr, *prevPtr;
@@ -85,9 +80,9 @@ waitpid(pid, statusPtr, options)
     }
 
     /*
-     * See if there's a suitable process that has already stopped or
-     * exited. If so, remove it from the list of exited processes and
-     * return its information.
+     * See if there's a suitable process that has already stopped or exited.
+     * If so, remove it from the list of exited processes and return its
+     * information.
      */
 
     for (waitPtr = deadList, prevPtr = NULL; waitPtr != NULL;
@@ -110,12 +105,12 @@ waitpid(pid, statusPtr, options)
     }
 
     /*
-     * Wait for any process to stop or exit.  If it's an acceptable one
-     * then return it to the caller;  otherwise store information about it
-     * in the list of exited processes and try again.  On systems that
-     * have only wait but not wait3, there are several situations we can't
-     * handle, but we do the best we can (e.g. can still handle some
-     * combinations of options by invoking wait instead of wait3).
+     * Wait for any process to stop or exit. If it's an acceptable one then
+     * return it to the caller; otherwise store information about it in the
+     * list of exited processes and try again. On systems that have only wait
+     * but not wait3, there are several situations we can't handle, but we do
+     * the best we can (e.g. can still handle some combinations of options by
+     * invoking wait instead of wait3).
      */
 
     while (1) {
@@ -148,13 +143,13 @@ waitpid(pid, statusPtr, options)
 	return result;
 
 	/*
-	 * Can't return this info to caller.  Save it in the list of
-	 * stopped or exited processes.  Tricky point: first check for
-	 * an existing entry for the process and overwrite it if it
-	 * exists (e.g. a previously stopped process might now be dead).
+	 * Can't return this info to caller. Save it in the list of stopped or
+	 * exited processes. Tricky point: first check for an existing entry
+	 * for the process and overwrite it if it exists (e.g. a previously
+	 * stopped process might now be dead).
 	 */
 
-	saveInfo:
+    saveInfo:
 	for (waitPtr = deadList; waitPtr != NULL; waitPtr = waitPtr->nextPtr) {
 	    if (waitPtr->pid == result) {
 		waitPtr->status = status;
@@ -167,6 +162,7 @@ waitpid(pid, statusPtr, options)
 	waitPtr->nextPtr = deadList;
 	deadList = waitPtr;
 
-	waitAgain: continue;
+    waitAgain:
+	continue;
     }
 }

doc/Access.3

@@ -19,7 +19,7 @@ int
 int
 \fBTcl_Stat\fR(\fIpath\fR, \fIstatPtr\fR)
 .SH ARGUMENTS
-.AS "struct stat" *statPtr in
+.AS "struct stat" *statPtr out
 .AP char *path in
 Native name of the file to check the attributes of.
 .AP int mode in

doc/AddErrInfo.3

@@ -6,17 +6,29 @@
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
 .so man.macros
-.TH Tcl_AddErrorInfo 3 8.0 Tcl "Tcl Library Procedures"
+.TH Tcl_AddErrorInfo 3 8.5 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_AddObjErrorInfo, Tcl_AddErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_PosixError, Tcl_LogCommandInfo \- record information about errors
+Tcl_GetReturnOptions, Tcl_SetReturnOptions, Tcl_AddErrorInfo, Tcl_AppendObjToErrorInfo, Tcl_AddObjErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_PosixError, Tcl_LogCommandInfo \- retrieve or record information about errors and other return options
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
+.VS 8.5
 .sp
-\fBTcl_AddObjErrorInfo\fR(\fIinterp, message, length\fR)
+Tcl_Obj *
+\fBTcl_GetReturnOptions\fR(\fIinterp, code\fR)
+.sp
+int 
+\fBTcl_SetReturnOptions\fR(\fIinterp, options\fR)
+.VE 8.5
 .sp
 \fBTcl_AddErrorInfo\fR(\fIinterp, message\fR)
+.VS 8.5
+.sp
+\fBTcl_AppendObjToErrorInfo\fR(\fIinterp, objPtr\fR)
+.VE 8.5
+.sp
+\fBTcl_AddObjErrorInfo\fR(\fIinterp, message, length\fR)
 .sp
 \fBTcl_SetObjErrorCode\fR(\fIinterp, errorObjPtr\fR)
 .sp
@@ -24,38 +36,47 @@ Tcl_AddObjErrorInfo, Tcl_AddErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tc
 .sp
 \fBTcl_SetErrorCodeVA\fR(\fIinterp, argList\fR)
 .sp
-CONST char *
+const char *
 \fBTcl_PosixError\fR(\fIinterp\fR)
 .sp
 void
 \fBTcl_LogCommandInfo\fR(\fIinterp, script, command, commandLength\fR)
 .SH ARGUMENTS
-.AS Tcl_Interp *message
+.AS Tcl_Interp commandLength
 .AP Tcl_Interp *interp in
 Interpreter in which to record information.
+.AP int code 
+The code returned from script evaluation.
+.AP Tcl_Obj *options
+A dictionary of return options.
 .AP char *message in
+For \fBTcl_AddErrorInfo\fR,
+this is a conventional C string to append to the \fB\-errorinfo\fR return option.
 For \fBTcl_AddObjErrorInfo\fR,
-this points to the first byte of an array of bytes
-containing a string to record in the \fBerrorInfo\fR variable.
+this points to the first byte of an array of \fIlength\fR bytes
+containing a string to append to the \fB\-errorinfo\fR return option.
 This byte array may contain embedded null bytes
 unless \fIlength\fR is negative.
-For \fBTcl_AddErrorInfo\fR,
-this is a conventional C string to record in the \fBerrorInfo\fR variable.
+.VS 8.5
+.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.
+.VE 8.5
 .AP int length in
 The number of bytes to copy from \fImessage\fR when
-setting the \fBerrorInfo\fR variable.
+appending to the \fB\-errorinfo\fR return option.
 If negative, all bytes up to the first null byte are used.
 .AP Tcl_Obj *errorObjPtr in
-This variable \fBerrorCode\fR will be set to this value.
+The \fB\-errorcode\fR return option will be set to this value.
 .AP char *element in
-String to record as one element of \fBerrorCode\fR variable.
+String to record as one element of the \fB\-errorcode\fR return option.
 Last \fIelement\fR argument must be NULL.
 .AP va_list argList in
 An argument list which must have been initialized using
-\fBTCL_VARARGS_START\fR, and cleared using \fBva_end\fR.
-.AP "CONST char" *script in
+\fBva_start\fR, and cleared using \fBva_end\fR.
+.AP "const char" *script in
 Pointer to first character in script containing command (must be <= command)
-.AP "CONST char" *command in
+.AP "const char" *command in
 Pointer to first character in command that generated the error
 .AP int commandLength in
 Number of bytes in command; -1 means use all bytes up to first null byte
@@ -63,70 +84,156 @@ Number of bytes in command; -1 means use all bytes up to first null byte
 
 .SH DESCRIPTION
 .PP
-These procedures are used to manipulate two Tcl global variables
-that hold information about errors.
-The variable \fBerrorInfo\fR holds a stack trace of the
+.VS 8.5
+The \fBTcl_SetReturnOptions\fR and \fBTcl_GetReturnOptions\fR
+routines expose the same capabilities as the \fBreturn\fR and
+\fBcatch\fR commands, respectively, in the form of a C interface.
+.PP
+\fBTcl_GetReturnOptions\fR retrieves the dictionary of return options
+from an interpreter following a script evaluation.
+Routines such as \fBTcl_Eval\fR are called to evaluate a
+script in an interpreter.  These routines return an integer
+completion code.  These routines also leave in the interpreter
+both a result and a dictionary of return options generated
+by script evaluation.  Just as \fBTcl_GetObjResult\fR retrieves
+the result, \fBTcl_GetReturnOptions\fR retrieves the dictionary
+of return options.  The integer completion code should be
+passed as the \fIcode\fR argument to \fBTcl_GetReturnOptions\fR
+so that all required options will be present in the dictionary.
+Specifically, a \fIcode\fR value of \fBTCL_ERROR\fR will
+ensure that entries for the keys \fB\-errorinfo\fR,
+\fB\-errorcode\fR, and \fB\-errorline\fR will appear in the
+dictionary.  Also, the entries for the keys \fB\-code\fR
+and \fB\-level\fR will be adjusted if necessary to agree
+with the value of \fIcode\fR.  The \fB(Tcl_Obj *)\fR returned
+by \fBTcl_GetReturnOptions\fR points to an unshared
+\fBTcl_Obj\fR with reference count of zero.  The dictionary
+may be written to, either adding, removing, or overwriting
+any entries in it, without the need to check for a shared object.
+.PP
+A typical usage for \fBTcl_GetReturnOptions\fR is to
+retrieve the stack trace when script evaluation returns
+\fBTCL_ERROR\fR, like so:
+.CS
+int code = Tcl_Eval(interp, script);
+if (code == TCL_ERROR) {
+    Tcl_Obj *options = Tcl_GetReturnOptions(interp, code);  
+    Tcl_Obj *key = Tcl_NewStringObj("-errorinfo", -1);
+    Tcl_Obj *stackTrace;
+    Tcl_IncrRefCount(key);
+    Tcl_DictObjGet(NULL, options, key, &stackTrace);
+    Tcl_DecrRefCount(key);
+    /* Do something with stackTrace */
+}
+.CE
+.PP
+\fBTcl_SetReturnOptions\fR sets the return options
+of \fIinterp\fR to be \fIoptions\fR.  If \fIoptions\fR
+contains any invalid value for any key, TCL_ERROR will
+be returned, and the interp result will be set to an
+appropriate error message.  Otherwise, a completion code
+in agreement with the \fB\-code\fR and \fB\-level\fR
+keys in \fIoptions\fR will be returned.
+.PP
+As an example, Tcl's \fBreturn\fR command itself could
+be implemented in terms of \fBTcl_SetReturnOptions\fR
+like so:
+.CS
+if ((objc % 2) == 0) { /* explicit result argument */
+    objc--;
+    Tcl_SetObjResult(interp, objv[objc]);
+}
+return Tcl_SetReturnOptions(interp, Tcl_NewListObj(objc-1, objv+1));
+.CE
+(It is not really implemented that way.  Internal access
+privileges allow for a more efficient alternative that meshes
+better with the bytecode compiler.)
+.PP
+Note that a newly created \fBTcl_Obj\fR may be passed
+in as the \fIoptions\fR argument without the need to tend
+to any reference counting.  This is analogous to
+\fBTcl_SetObjResult\fR.
+.PP
+While \fBTcl_SetReturnOptions\fR provides a general interface
+to set any collection of return options, there are a handful
+of return options that are very frequently used.  Most 
+notably the \fB\-errorinfo\fR and \fB\-errorcode\fR return
+options should be set properly when the command procedure
+of a command returns \fBTCL_ERROR\fR.  Tcl provides several
+simpler interfaces to more directly set these return options.
+.VE 8.5
+.PP
+The \fB\-errorinfo\fR option holds a stack trace of the
 operations that were in progress when an error occurred,
 and is intended to be human-readable.
-The variable \fBerrorCode\fR holds a list of items that
+The \fB\-errorcode\fR option holds a list of items that
 are intended to be machine-readable.
-The first item in \fBerrorCode\fR identifies the class of
+The first item in the \fB\-errorcode\fR value identifies the class of
 error that occurred
 (e.g. POSIX means an error occurred in a POSIX system call)
-and additional elements in \fBerrorCode\fR hold additional pieces
+and additional elements hold additional pieces
 of information that depend on the class.
-See the Tcl overview manual entry for details on the various
-formats for \fBerrorCode\fR.
+See the tclvars manual entry for details on the various
+formats for the \fB\-errorcode\fR option used by
+Tcl's built-in commands.
 .PP
-The \fBerrorInfo\fR variable is gradually built up as an
+The \fB\-errorinfo\fR option value is gradually built up as an
 error unwinds through the nested operations.
-Each time an error code is returned to \fBTcl_EvalObjEx\fR
-(or \fBTcl_Eval\fR, which calls \fBTcl_EvalObjEx\fR)
-it calls the procedure \fBTcl_AddObjErrorInfo\fR to add
-additional text to \fBerrorInfo\fR describing the
+Each time an error code is returned to \fBTcl_Eval\fR, or
+any of the routines that performs script evaluation,
+the procedure \fBTcl_AddErrorInfo\fR is called to add
+additional text to the \fB\-errorinfo\fR value describing the
 command that was being executed when the error occurred.
 By the time the error has been passed all the way back
 to the application, it will contain a complete trace
 of the activity in progress when the error occurred.
 .PP
 It is sometimes useful to add additional information to
-\fBerrorInfo\fR beyond what can be supplied automatically
-by \fBTcl_EvalObjEx\fR.
-\fBTcl_AddObjErrorInfo\fR may be used for this purpose:
-its \fImessage\fR and \fIlength\fR arguments describe an additional
-string to be appended to \fBerrorInfo\fR.
-For example, the \fBsource\fR command calls \fBTcl_AddObjErrorInfo\fR
-to record the name of the file being processed and the
-line number on which the error occurred;
-for Tcl procedures, the procedure name and line number
+the \fB\-errorinfo\fR value beyond what can be supplied automatically
+by the script evaluation routines.
+\fBTcl_AddErrorInfo\fR may be used for this purpose:
+its \fImessage\fR argument is an additional
+string to be appended to the \fB\-errorinfo\fR option.
+For example, when an error arises during the \fBsource\fR command,
+the procedure \fBTcl_AddErrorInfo\fR is called to
+record the name of the file being processed and the
+line number on which the error occurred.
+Likewise, when an error arises during evaluation of a
+Tcl procedures, the procedure name and line number
 within the procedure are recorded, and so on.
-The best time to call \fBTcl_AddObjErrorInfo\fR is just after
-\fBTcl_EvalObjEx\fR has returned \fBTCL_ERROR\fR.
-In calling \fBTcl_AddObjErrorInfo\fR, you may find it useful to
-use the \fBerrorLine\fR field of the interpreter (see the
-\fBTcl_Interp\fR manual entry for details).
+The best time to call \fBTcl_AddErrorInfo\fR is just after
+a script evaluation routine has returned \fBTCL_ERROR\fR.
+The value of the \fB\-errorline\fR return option (retrieved
+via a call to \fBTcl_GetReturnOptions\fR) often makes up
+a useful part of the \fImessage\fR passed to \fBTcl_AddErrorInfo\fR.
 .PP
-\fBTcl_AddErrorInfo\fR resembles \fBTcl_AddObjErrorInfo\fR
-but differs in initializing \fBerrorInfo\fR from the string
-value of the interpreter's result
-if the error is just starting to be logged.
-It does not use the result as a Tcl object
-so any embedded null characters in the result
-will cause information to be lost.
-It also takes a conventional C string in \fImessage\fR
-instead of \fBTcl_AddObjErrorInfo\fR's counted string.
+.VS 8.5
+\fBTcl_AppendObjToErrorInfo\fR is an alternative interface to the
+same functionality as \fBTcl_AddErrorInfo\fR.  \fBTcl_AppendObjToErrorInfo\fR
+is called when the string value to be appended to the \fB\-errorinfo\fR option
+is available as a \fBTcl_Obj\fR instead of as a \fBchar\fR array.
+.VE 8.5
+.PP
+\fBTcl_AddObjErrorInfo\fR is nearly identical
+to \fBTcl_AddErrorInfo\fR, except that it has an additional \fIlength\fR
+argument.  This allows the \fImessage\fR string to contain 
+embedded null bytes.  This is essentially never a good idea.
+If the \fImessage\fR needs to contain the null character \fBU+0000\fR,
+Tcl's usual internal encoding rules should be used to avoid
+the need for a null byte.  If the \fBTcl_AddObjErrorInfo\fR
+interface is used at all, it should be with a negative \fIlength\fR value.
 .PP
 The procedure \fBTcl_SetObjErrorCode\fR is used to set the
-\fBerrorCode\fR variable. \fIerrorObjPtr\fR contains a list object
-built up by the caller. \fBerrorCode\fR is set to this
-value. \fBTcl_SetObjErrorCode\fR is typically invoked just 
-before returning an error in an object command. If an error is
+\fB\-errorcode\fR return option to the list object \fIerrorObjPtr\fR 
+built up by the caller. 
+\fBTcl_SetObjErrorCode\fR is typically invoked just 
+before returning an error. If an error is
 returned without calling \fBTcl_SetObjErrorCode\fR or
 \fBTcl_SetErrorCode\fR the Tcl interpreter automatically sets
-\fBerrorCode\fR to \fBNONE\fR.
+the \fB\-errorcode\fR return option to \fBNONE\fR.
 .PP
 The procedure \fBTcl_SetErrorCode\fR is also used to set the
-\fBerrorCode\fR variable. However, it takes one or more strings to
+\fB\-errorcode\fR return option. However, it takes one or more strings to
 record instead of an object. Otherwise, it is similar to
 \fBTcl_SetObjErrorCode\fR in behavior.
 .PP
@@ -134,9 +241,10 @@ record instead of an object. Otherwise, it is similar to
 instead of taking a variable number of arguments it takes an argument list.
 .PP
 \fBTcl_PosixError\fR
-sets the \fBerrorCode\fR variable after an error in a POSIX kernel call.
+sets the \fB\-errorcode\fR variable after an error in a POSIX kernel call.
 It reads the value of the \fBerrno\fR C variable and calls
-\fBTcl_SetErrorCode\fR to set \fBerrorCode\fR in the \fBPOSIX\fR format.
+\fBTcl_SetErrorCode\fR to set the \fB\-errorcode\fR return
+option in the \fBPOSIX\fR format.
 The caller must previously have called \fBTcl_SetErrno\fR to set
 \fBerrno\fR; this is necessary on some platforms (e.g. Windows) where Tcl
 is linked into an application as a shared library, or when the error
@@ -146,41 +254,44 @@ occurs in a dynamically loaded extension. See the manual entry for
 \fBTcl_PosixError\fR returns a human-readable diagnostic message
 for the error
 (this is the same value that will appear as the third element
-in \fBerrorCode\fR).
+in the \fB\-errorcode\fR value).
 It may be convenient to include this string as part of the
 error message returned to the application in
 the interpreter's result.
 .PP
 \fBTcl_LogCommandInfo\fR is invoked after an error occurs in an
 interpreter.  It adds information about the command that was being
-executed when the error occurred to the \fBerrorInfo\fR variable, and
-the line number stored internally in the interpreter is set.  On the
-first call to \fBTcl_LogCommandInfo\fR or \fBTcl_AddObjErrorInfo\fR
-since an error occurred, the old information in \fBerrorInfo\fR is
-deleted.
+executed when the error occurred to the \fB\-errorinfo\fR value, and
+the line number stored internally in the interpreter is set.  
 .PP
-It is important to call the procedures described here rather than
+In older releases of Tcl, there was no \fBTcl_GetReturnOptions\fR
+routine.  In its place, the global Tcl variables \fBerrorInfo\fR
+and \fBerrorCode\fR were the only place to retrieve the error
+information.  Much existing code written for older Tcl releases
+still access this information via those global variables.
+.PP
+It is important to realize that while reading from those
+global variables remains a supported way to access these
+return option values, it is important not to assume that
+writing to those global variables will properly set the
+corresponding return options.  It has long been emphasized
+in this manual page that it is important to 
+call the procedures described here rather than
 setting \fBerrorInfo\fR or \fBerrorCode\fR directly with
 \fBTcl_ObjSetVar2\fR.
-The reason for this is that the Tcl interpreter keeps information
-about whether these procedures have been called.
-For example, the first time \fBTcl_AddObjErrorInfo\fR is called
-for an error, it clears the existing value of \fBerrorInfo\fR
-and adds the error message in the interpreter's result to the variable
-before appending \fImessage\fR;
-in subsequent calls, it just appends the new \fImessage\fR.
-When \fBTcl_SetErrorCode\fR is called, it sets a flag indicating
-that \fBerrorCode\fR has been set;
-this allows the Tcl interpreter to set \fBerrorCode\fR to \fBNONE\fR
-if it receives an error return
-when \fBTcl_SetErrorCode\fR hasn't been called.
 .PP
 If the procedure \fBTcl_ResetResult\fR is called,
-it clears all of the state associated with
-\fBerrorInfo\fR and \fBerrorCode\fR
-(but it doesn't actually modify the variables).
-If an error had occurred, this will clear the error state to
-make it appear as if no error had occurred after all.
+it clears all of the state of the interpreter associated with
+script evaluation, including the entire return options dictionary.
+In particular, the \fB\-errorinfo\fR and \fB\-errorcode\fR options
+are reset.  
+If an error had occurred, the \fBTcl_ResetResult\fR call will
+clear the error state to make it appear as if no error had
+occurred after all.
+The global variables \fBerrorInfo\fR and
+\fBerrorCode\fR are not modified by \fBTcl_ResetResult\fR
+so they continue to hold a record of information about the
+most recent error seen in an interpreter.
 
 .SH "SEE ALSO"
 Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_Interp, Tcl_ResetResult, Tcl_SetErrno

doc/Alloc.3

@@ -67,22 +67,24 @@ further allocation.
 \fBTcl_Realloc\fR changes the size of the block pointed to by
 \fIptr\fR to \fIsize\fR bytes and returns a pointer to the new block.
 The contents will be unchanged up to the lesser of the new and old
-sizes.  The returned location may be different from \fIptr\fR.
+sizes.  The returned location may be different from \fIptr\fR.  If
+\fIptr\fR is NULL, this is equivalent to calling \fBTcl_Alloc\fR with
+just the \fIsize\fR argument.
 .PP
 \fBTcl_AttemptAlloc\fR and \fBTcl_AttemptRealloc\fR are identical in
 function to \fBTcl_Alloc\fR and \fBTcl_Realloc\fR, except that
 \fBTcl_AttemptAlloc\fR and \fBTcl_AttemptRealloc\fR will not cause the Tcl
 interpreter to \fBpanic\fR if the memory allocation fails.  If the
 allocation fails, these functions will return NULL.  Note that on some
-platforms, attempting to allocate a block of memory will also cause
-these functions to return NULL.
+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 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.
 

doc/AllowExc.3

@@ -16,7 +16,7 @@ Tcl_AllowExceptions \- allow all exceptions in next script evaluation
 .sp
 \fBTcl_AllowExceptions\fR(\fIinterp\fR)
 .SH ARGUMENTS
-.AS Tcl_Interp *doublePtr
+.AS Tcl_Interp *interp
 .AP Tcl_Interp *interp in
 Interpreter in which script will be evaluated.
 .BE
@@ -25,8 +25,8 @@ Interpreter in which script will be evaluated.
 .PP
 If a script is evaluated at top-level (i.e. no other scripts are
 pending evaluation when the script is invoked), and if the script
-terminates with a completion code other than TCL_OK, TCL_ERROR
-or TCL_RETURN, then Tcl normally converts this into a TCL_ERROR
+terminates with a completion code other than \fBTCL_OK\fR, \fBTCL_ERROR\fR
+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,
@@ -38,7 +38,7 @@ calling one of those a procedures, then arbitrary completion
 codes are permitted from the script, and they are returned without
 modification.
 This is useful in cases where the caller can deal with exceptions
-such as TCL_BREAK or TCL_CONTINUE in a meaningful way.
+such as \fBTCL_BREAK\fR or \fBTCL_CONTINUE\fR in a meaningful way.
 
 .SH KEYWORDS
 continue, break, exception, interpreter

doc/AppInit.3

@@ -24,7 +24,9 @@ Interpreter for the application.
 
 .SH DESCRIPTION
 .PP
-\fBTcl_AppInit\fR is a ``hook'' procedure that is invoked by
+\fBTcl_AppInit\fR is a
+.QW hook
+procedure that is invoked by
 the main programs for Tcl applications such as \fBtclsh\fR and \fBwish\fR.
 Its purpose is to allow new Tcl applications to be created without
 modifying the main programs provided as part of Tcl and Tk.
@@ -47,8 +49,8 @@ Tcl variables \fBargv\fR and \fBargv0\fR in \fIinterp\fR.
 .IP [3]
 Invoke a startup script to initialize the application.
 .LP
-\fBTcl_AppInit\fR returns TCL_OK or TCL_ERROR.
-If it returns TCL_ERROR then it must leave an error message in
+\fBTcl_AppInit\fR returns \fBTCL_OK\fR or \fBTCL_ERROR\fR.
+If it returns \fBTCL_ERROR\fR then it must leave an error message in
 for the interpreter's result;  otherwise the result is ignored.
 .PP
 In addition to \fBTcl_AppInit\fR, your application should also contain
@@ -58,7 +60,7 @@ Tcl_Main(argc, argv, Tcl_AppInit);
 .CE
 The third argument to \fBTcl_Main\fR gives the address of the
 application-specific initialization procedure to invoke.
-This means that you don't have to use the name \fBTcl_AppInit\fR
+This means that you do not have to use the name \fBTcl_AppInit\fR
 for the procedure, but in practice the name is nearly always
 \fBTcl_AppInit\fR (in versions before Tcl 7.4 the name \fBTcl_AppInit\fR
 was implicit;  there was no way to specify the procedure explicitly).

doc/AssocData.3

@@ -8,9 +8,7 @@
 .TH Tcl_SetAssocData 3 7.5 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_GetAssocData, Tcl_SetAssocData, Tcl_DeleteAssocData \- manage
-associations of string keys and user specified data with Tcl
-interpreters.
+Tcl_GetAssocData, Tcl_SetAssocData, Tcl_DeleteAssocData \- manage associations of string keys and user specified data with Tcl interpreters
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -22,12 +20,10 @@ ClientData
 .sp
 \fBTcl_DeleteAssocData\fR(\fIinterp, key\fR)
 .SH ARGUMENTS
-.AS Tcl_InterpDeleteProc *delProcPtr
+.AS Tcl_InterpDeleteProc **delProcPtr
 .AP Tcl_Interp *interp in
 Interpreter in which to execute the specified command.
-.VS 8.4
-.AP "CONST char" *key in
-.VE
+.AP "const char" *key in
 Key for association with which to store data or from which to delete or
 retrieve data.  Typically the module prefix for a package.
 .AP Tcl_InterpDeleteProc *delProc in
@@ -67,8 +63,8 @@ is deleted.  \fIDeleteProc\fR should have arguments and result that match
 the type \fBTcl_InterpDeleteProc\fR:
 .CS
 typedef void Tcl_InterpDeleteProc(
-	ClientData \fIclientData\fR,
-	Tcl_Interp *\fIinterp\fR);
+        ClientData \fIclientData\fR,
+        Tcl_Interp *\fIinterp\fR);
 .CE
 When \fIdeleteProc\fR is invoked the \fIclientData\fR and \fIinterp\fR
 arguments will be the same as the corresponding arguments passed to

doc/Async.3

@@ -48,9 +48,9 @@ or 0 if \fIinterp\fR is NULL.
 These procedures provide a safe mechanism for dealing with
 asynchronous events such as signals.
 If an event such as a signal occurs while a Tcl script is being
-evaluated then it isn't safe to take any substantive action to
+evaluated then it is not safe to take any substantive action to
 process the event.
-For example, it isn't safe to evaluate a Tcl script since the
+For example, it is not safe to evaluate a Tcl script since the
 interpreter may already be in the middle of evaluating a script;
 it may not even be safe to allocate memory, since a memory
 allocation could have been in progress when the event occurred.
@@ -140,7 +140,6 @@ If new handlers become ready while handlers are executing,
 \fBTcl_AsyncInvoke\fR will invoke them all;  at each point it
 invokes the highest-priority (oldest) ready handler, repeating
 this over and over until there are no longer any ready handlers.
-
 .SH WARNING
 .PP
 It is almost always a bad idea for an asynchronous event
@@ -150,12 +149,11 @@ This sort of behavior can disrupt the execution of scripts in
 subtle ways and result in bugs that are extremely difficult
 to track down.
 If an asynchronous event handler needs to evaluate Tcl scripts
-then it should first save the interpreter's result plus the values
-of the variables \fBerrorInfo\fR and \fBerrorCode\fR (this can
-be done, for example, by storing them in dynamic strings).
+then it should first save the interpreter's state by calling
+\fBTcl_SaveInterpState\fR, passing in the \fIcode\fR argument.
 When the asynchronous handler is finished it should restore
-the interpreter's result, \fBerrorInfo\fR, and \fBerrorCode\fR,
-and return the \fIcode\fR argument.
+the interpreter's state by calling \fBTcl_RestoreInterpState\fR,
+and then returning the \fIcode\fR argument.
 
 .SH KEYWORDS
-asynchronous event, handler, signal
+asynchronous event, handler, signal, Tcl_SaveInterpState, thread

doc/BackgdErr.3

@@ -24,7 +24,8 @@ Interpreter in which the error occurred.
 .SH DESCRIPTION
 .PP
 This procedure is typically invoked when a Tcl error occurs during
-``background processing'' such as executing an event handler.
+.QW "background processing"
+such as executing an event handler.
 When such an error occurs, the error condition is reported to Tcl
 or to a widget or some other C code, and there is not usually any
 obvious way for that code to report the error to the user.
@@ -32,25 +33,29 @@ In these cases the code calls \fBTcl_BackgroundError\fR with an
 \fIinterp\fR argument identifying the interpreter in which the
 error occurred.  At the time \fBTcl_BackgroundError\fR is invoked,
 the interpreter's result is expected to contain an error message.
-\fBTcl_BackgroundError\fR will invoke the \fBbgerror\fR
-Tcl command to report the error in an application-specific fashion.
-If no \fBbgerror\fR command exists, or if it returns with an error condition,
-then \fBTcl_BackgroundError\fR reports the error itself by printing
-a message on the standard error file.
+\fBTcl_BackgroundError\fR will invoke the command registered
+in that interpreter to handle background errors by the
+\fBinterp bgerror\fR command.
+The registered handler command is meant to report the error
+in an application-specific fashion.  The handler command
+receives two arguments, the result of the interp, and the
+return options of the interp at the time the error occurred.
+If the application registers no handler command, the default
+handler command will attempt to call \fBbgerror\fR to report
+the error.  If an error condition arises while invoking the
+handler command, then \fBTcl_BackgroundError\fR reports the
+error itself by printing a message on the standard error file.
 .PP
-\fBTcl_BackgroundError\fR does not invoke \fBbgerror\fR immediately
+\fBTcl_BackgroundError\fR does not invoke the handler command immediately
 because this could potentially interfere with scripts that are in process
 at the time the error occurred.
-Instead, it invokes \fBbgerror\fR later as an idle callback.
-\fBTcl_BackgroundError\fR saves the values of the \fBerrorInfo\fR and
-\fBerrorCode\fR variables and restores these values just before
-invoking \fBbgerror\fR.
+Instead, it invokes the handler command later as an idle callback.
 .PP
 It is possible for many background errors to accumulate before
-\fBbgerror\fR is invoked.  When this happens, each of the errors
-is processed in order.  However, if \fBbgerror\fR returns a
+the handler command is invoked.  When this happens, each of the errors
+is processed in order.  However, if the handle command returns a
 break exception, then all remaining error reports for the
 interpreter are skipped.
 
 .SH KEYWORDS
-background, bgerror, error
+background, bgerror, error, interp

doc/Backslash.3

@@ -17,35 +17,31 @@ Tcl_Backslash \- parse a backslash sequence
 char
 \fBTcl_Backslash\fR(\fIsrc, countPtr\fR)
 .SH ARGUMENTS
-.AS char *countPtr
+.AS char *countPtr out
 .AP char *src in
 Pointer to a string starting with a backslash.
 .AP int *countPtr out
-If \fIcountPtr\fR isn't NULL, \fI*countPtr\fR gets filled
+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
-.VS 8.1
 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. 
-.VE
 \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.
-.VS 8.1 br
 .SH "SEE ALSO"
 Tcl(n), Tcl_UtfBackslash(3)
-.VE
 
 .SH KEYWORDS
 backslash, parse

doc/BoolObj.3

@@ -1,14 +1,15 @@
 '\"
 '\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
+'\" Contributions from Don Porter, NIST, 2005.  (not subject to US copyright)
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
 .so man.macros
-.TH Tcl_BooleanObj 3 8.0 Tcl "Tcl Library Procedures"
+.TH Tcl_BooleanObj 3 8.5 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_NewBooleanObj, Tcl_SetBooleanObj, Tcl_GetBooleanFromObj \- manipulate Tcl objects as boolean values
+Tcl_NewBooleanObj, Tcl_SetBooleanObj, Tcl_GetBooleanFromObj \- store/retrieve boolean value in a Tcl_Obj
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -21,20 +22,14 @@ Tcl_Obj *
 int
 \fBTcl_GetBooleanFromObj\fR(\fIinterp, objPtr, boolPtr\fR)
 .SH ARGUMENTS
-.AS Tcl_Interp *interp
+.AS Tcl_Interp boolValue in/out
 .AP int boolValue in
-Integer value used to initialize or set a boolean object.
-If the integer is nonzero, the boolean object is set to 1;
-otherwise the boolean object is set to 0.
+Integer value to be stored as a boolean value in a Tcl_Obj.
 .AP Tcl_Obj *objPtr in/out
-For \fBTcl_SetBooleanObj\fR, this points to the object to be converted
-to boolean type.
-For \fBTcl_GetBooleanFromObj\fR, this refers to the object
-from which to get a boolean value; 
-if \fIobjPtr\fR does not already point to a boolean object,
-an attempt will be made to convert it to one.
+Points to the Tcl_Obj in which to store, or from which to
+retrieve a boolean value.
 .AP Tcl_Interp *interp in/out
-If an error occurs during conversion,
+If a boolean value cannot be retrieved,
 an error message is left in the interpreter's result object
 unless \fIinterp\fR is NULL.
 .AP int *boolPtr out
@@ -44,44 +39,57 @@ stores the boolean value (0 or 1) obtained from \fIobjPtr\fR.
 
 .SH DESCRIPTION
 .PP
-These procedures are used to create, modify, and read
-boolean Tcl objects from C code.
-\fBTcl_NewBooleanObj\fR and \fBTcl_SetBooleanObj\fR
-will create a new object of boolean type
-or modify an existing object to have boolean type. 
-Both of these procedures set the object to have the
-boolean value (0 or 1) specified by \fIboolValue\fR;
-if \fIboolValue\fR is nonzero, the object is set to 1,
-otherwise to 0.
-\fBTcl_NewBooleanObj\fR returns a pointer to a newly created object
-with reference count zero.
-Both procedures set the object's type to be boolean
-and assign the boolean value to the object's internal representation
-\fIlongValue\fR member.
-\fBTcl_SetBooleanObj\fR invalidates any old string representation
-and, if the object is not already a boolean object,
-frees any old internal representation.
+These procedures are used to pass boolean values to and from
+Tcl as Tcl_Obj's.  When storing a boolean value into a Tcl_Obj,
+any non-zero integer value in \fIboolValue\fR is taken to be
+the boolean value \fB1\fR, and the integer value \fB0\fR is
+taken to be the boolean value \fB0\fR.
 .PP
-\fBTcl_GetBooleanFromObj\fR attempts to return a boolean value
-from the Tcl object \fIobjPtr\fR.
-If the object is not already a boolean object,
-it will attempt to convert it to one.
-If an error occurs during conversion, it returns \fBTCL_ERROR\fR
-and leaves an error message in the interpreter's result object
-unless \fIinterp\fR is NULL.
-Otherwise, \fBTcl_GetBooleanFromObj\fR returns \fBTCL_OK\fR
-and stores the boolean value in the address given by \fIboolPtr\fR.
-If the object is not already a boolean object,
-the conversion will free any old internal representation.
-Objects having a string representation equal to any of \fB0\fR,
-\fBfalse\fR, \fBno\fR, or \fBoff\fR have a boolean value 0; if the
-string representation is any of \fB1\fR, \fBtrue\fR, \fByes\fR, or
-\fBon\fR the boolean value is 1.
-Any of these string values may be abbreviated, and upper-case spellings
-are also acceptable.
+\fBTcl_NewBooleanObj\fR creates a new Tcl_Obj, stores the boolean
+value \fIboolValue\fR in it, and returns a pointer to the new Tcl_Obj.
+The new Tcl_Obj has reference count of zero.
+.PP
+\fBTcl_SetBooleanObj\fR accepts \fIobjPtr\fR, a pointer to
+an existing Tcl_Obj, and stores in the Tcl_Obj \fI*objPtr\fR 
+the boolean value \fIboolValue\fR.  This is a write operation
+on \fI*objPtr\fR, so \fIobjPtr\fR must be unshared.  Attempts to
+write to a shared Tcl_Obj will panic.  A successful write
+of \fIboolValue\fR into \fI*objPtr\fR implies the freeing of
+any former value stored in \fI*objPtr\fR.
+.PP
+\fBTcl_GetBooleanFromObj\fR attempts to retrieve a boolean value
+from the value stored in \fI*objPtr\fR.
+If \fIobjPtr\fR holds a string value recognized by \fBTcl_GetBoolean\fR,
+then the recognized boolean value is written at the address given
+by \fIboolPtr\fR.  
+If \fIobjPtr\fR holds any value recognized as
+a number by Tcl, then if that value is zero a 0 is written at
+the address given by \fIboolPtr\fR and if that
+value is non-zero a 1 is written at the address given by \fIboolPtr\fR.
+In all cases where a value is written at the address given
+by \fIboolPtr\fR, \fBTcl_GetBooleanFromObj\fR returns \fBTCL_OK\fR.
+If the value of \fIobjPtr\fR does not meet any of the conditions
+above, then \fBTCL_ERROR\fR is returned and an error message is 
+left in the interpreter's result unless \fIinterp\fR is NULL.
+\fBTcl_GetBooleanFromObj\fR may also make changes to the internal
+fields of \fI*objPtr\fR so that future calls to 
+\fBTcl_GetBooleanFromObj\fR on the same \fIobjPtr\fR can be
+performed more efficiently.
+.PP
+Note that the routines \fBTcl_GetBooleanFromObj\fR and
+\fBTcl_GetBoolean\fR are not functional equivalents.
+The set of values for which \fBTcl_GetBooleanFromObj\fR
+will return \fBTCL_OK\fR is strictly larger than
+the set of values for which \fBTcl_GetBoolean\fR will do the same.
+For example, the value
+.QW 5
+passed to \fBTcl_GetBooleanFromObj\fR
+will lead to a \fBTCL_OK\fR return (and the boolean value 1),
+while the same value passed to \fBTcl_GetBoolean\fR will lead to
+a \fBTCL_ERROR\fR return.
 
 .SH "SEE ALSO"
-Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
+Tcl_NewObj, Tcl_IsShared, Tcl_GetBoolean
 
 .SH KEYWORDS
-boolean, boolean object, boolean type, internal representation, object, object type, string representation
+boolean, object

doc/ByteArrObj.3

@@ -25,8 +25,8 @@ unsigned char *
 unsigned char *
 \fBTcl_SetByteArrayLength\fR(\fIobjPtr, length\fR)
 .SH ARGUMENTS
-.AS "unsigned char" *lengthPtr in/out
-.AP "CONST unsigned char" *bytes in
+.AS "const unsigned char" *lengthPtr in/out
+.AP "const unsigned char" *bytes in
 The array of bytes used to initialize or set a byte-array object.
 .AP int length in
 The length of the array of bytes.  It must be >= 0.
@@ -48,7 +48,7 @@ results of binary IO operations or data structures created with the
 \fBbinary\fR command.  In Tcl, an array of bytes is not equivalent to a
 string.  Conceptually, a string is an array of Unicode characters, while a
 byte-array is an array of 8-bit quantities with no implicit meaning.
-Accesser functions are provided to get the string representation of a
+Accessor functions are provided to get the string representation of a
 byte-array or to convert an arbitrary object to a byte-array.  Obtaining the
 string representation of a byte-array object (by calling
 \fBTcl_GetStringFromObj\fR) produces a properly formed UTF-8 sequence with a

doc/CallDel.3

@@ -38,8 +38,8 @@ time of the call.
 type \fBTcl_InterpDeleteProc\fR:
 .CS
 typedef void Tcl_InterpDeleteProc(
-	ClientData \fIclientData\fR,
-	Tcl_Interp *\fIinterp\fR);
+        ClientData \fIclientData\fR,
+        Tcl_Interp *\fIinterp\fR);
 .CE
 The \fIclientData\fR and \fIinterp\fR parameters are
 copies of the \fIclientData\fR and \fIinterp\fR arguments given
@@ -51,7 +51,7 @@ interpreter is about to go away.
 .PP
 \fBTcl_DontCallWhenDeleted\fR cancels a previous call to
 \fBTcl_CallWhenDeleted\fR with the same arguments, so that
-\fIproc\fR won't be called after all when \fIinterp\fR is
+\fIproc\fR will not be called after all when \fIinterp\fR is
 deleted.
 If there is no deletion callback that matches \fIinterp\fR,
 \fIproc\fR, and \fIclientData\fR then the call to

doc/ChnlStack.3

@@ -8,7 +8,7 @@
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-Tcl_StackChannel, Tcl_UnstackChannel, Tcl_GetStackedChannel, Tcl_GetTopChannel \- stack an I/O channel on top of another, and undo it
+Tcl_StackChannel, Tcl_UnstackChannel, Tcl_GetStackedChannel, Tcl_GetTopChannel \- manipulate stacked I/O channels
 .SH SYNOPSIS
 .nf
 .nf
@@ -27,17 +27,17 @@ Tcl_Channel
 \fBTcl_GetTopChannel\fR(\fIchannel\fR)
 .sp
 .SH ARGUMENTS
-.AS Tcl_ChannelType
+.AS Tcl_ChannelType clientData
 .AP Tcl_Interp *interp in
 Interpreter for error reporting.
 .AP Tcl_ChannelType *typePtr in
-The new channel I/O procedures to use for \fIchannel\fP.
+The new channel I/O procedures to use for \fIchannel\fR.
 .AP ClientData clientData in
 Arbitrary one-word value to pass to channel I/O procedures.
 .AP int mask in
 Conditions under which \fIchannel\fR will be used: OR-ed combination of
 \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR and \fBTCL_EXCEPTION\fR.
-This can be a subset of the operations currently allowed on \fIchannel\fP.
+This can be a subset of the operations currently allowed on \fIchannel\fR.
 .AP Tcl_Channel channel in
 An existing Tcl channel such as returned by \fBTcl_CreateChannel\fR.
 .BE
@@ -55,9 +55,9 @@ stacked channels.  Anyone using stacked channels or creating stacked
 channel drivers should update to the new \fBTCL_CHANNEL_VERSION_2\fR
 \fBTcl_ChannelType\fR structure.  See \fBTcl_CreateChannel\fR for details.
 .PP
-\fBTcl_StackChannel\fR stacks a new \fIchannel\fP on an existing channel
-with the same name that was registered for \fIchannel\fP by
-\fBTcl_RegisterChannel\fP.
+\fBTcl_StackChannel\fR stacks a new \fIchannel\fR on an existing channel
+with the same name that was registered for \fIchannel\fR by
+\fBTcl_RegisterChannel\fR.
 .PP
 \fBTcl_StackChannel\fR works by creating a new channel structure and
 placing itself on top of the channel stack.  EOL translation, encoding and
@@ -68,7 +68,7 @@ remain at the top of the channel stack.  A pointer to the new top channel
 structure is returned.  If an error occurs when stacking the channel, NULL
 is returned instead.
 .PP
-The \fImask\fP parameter specifies the operations that are allowed on the
+The \fImask\fR parameter specifies the operations that are allowed on the
 new channel.  These can be a subset of the operations allowed on the
 original channel.  For example, a read-write channel may become read-only
 after the \fBTcl_StackChannel\fR call.
@@ -77,10 +77,10 @@ Closing a channel closes the channels stacked below it.  The close of
 stacked channels is executed in a way that allows buffered data to be
 properly flushed.
 .PP
-\fBTcl_UnstackChannel\fP reverses the process.  The old channel is
+\fBTcl_UnstackChannel\fR reverses the process.  The old channel is
 associated with the channel name, and the processing module added by
 \fBTcl_StackChannel\fR is destroyed.  If there is no old channel, then
-\fBTcl_UnstackChannel\fP is equivalent to \fBTcl_Close\fP.  If an error
+\fBTcl_UnstackChannel\fR is equivalent to \fBTcl_Close\fR.  If an error
 occurs unstacking the channel, \fBTCL_ERROR\fR is returned, otherwise
 \fBTCL_OK\fR is returned.
 .PP

doc/CmdCmplt.3

@@ -17,8 +17,8 @@ Tcl_CommandComplete \- Check for unmatched braces in a Tcl command
 int
 \fBTcl_CommandComplete\fR(\fIcmd\fR)
 .SH ARGUMENTS
-.AS "CONST char" *cmd
-.AP "CONST char" *cmd in
+.AS "const char" *cmd
+.AP "const char" *cmd in
 Command string to test for completeness.
 .BE
 

doc/Concat.3

@@ -14,12 +14,13 @@ Tcl_Concat \- concatenate a collection of strings
 .nf
 \fB#include <tcl.h>\fR
 .sp
-CONST char *
+const char *
 \fBTcl_Concat\fR(\fIargc, argv\fR)
 .SH ARGUMENTS
+.AS "const char *const" argv[]
 .AP int argc in
 Number of strings.
-.AP "CONST char * CONST" argv[] in
+.AP "const char *const" argv[] in
 Array of strings to concatenate.  Must have \fIargc\fR entries.
 .BE
 
@@ -41,12 +42,9 @@ copies strings from \fBargv\fR to the result.  If an element of
 is ignored entirely.  This white-space removal was added to make
 the output of the \fBconcat\fR command cleaner-looking.
 .PP
-.VS
 The result string is dynamically allocated
 using \fBTcl_Alloc\fR;  the caller must eventually release the space
 by calling \fBTcl_Free\fR.
-.VE
-.VS
 .SH "SEE ALSO"
 Tcl_ConcatObj
 .SH KEYWORDS

doc/CrtChannel.3

@@ -9,7 +9,7 @@
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType, Tcl_GetChannelName, Tcl_GetChannelHandle, Tcl_GetChannelMode, Tcl_GetChannelBufferSize, Tcl_SetChannelBufferSize, Tcl_NotifyChannel, Tcl_BadChannelOption, Tcl_ChannelName, Tcl_ChannelVersion, Tcl_ChannelBlockModeProc, Tcl_ChannelCloseProc, Tcl_ChannelClose2Proc, Tcl_ChannelInputProc, Tcl_ChannelOutputProc, Tcl_ChannelSeekProc, Tcl_ChannelWideSeekProc, Tcl_ChannelSetOptionProc, Tcl_ChannelGetOptionProc, Tcl_ChannelWatchProc, Tcl_ChannelGetHandleProc, Tcl_ChannelFlushProc, Tcl_ChannelHandlerProc, Tcl_ChannelThreadActionProc, Tcl_IsChannelShared, Tcl_IsChannelRegistered, Tcl_CutChannel, Tcl_SpliceChannel, Tcl_IsChannelExisting, Tcl_ClearChannelHandlers, Tcl_GetChannelThread, Tcl_ChannelBuffered \- procedures for creating and manipulating channels
+Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType, Tcl_GetChannelName, Tcl_GetChannelHandle, Tcl_GetChannelMode, Tcl_GetChannelBufferSize, Tcl_SetChannelBufferSize, Tcl_NotifyChannel, Tcl_BadChannelOption, Tcl_ChannelName, Tcl_ChannelVersion, Tcl_ChannelBlockModeProc, Tcl_ChannelCloseProc, Tcl_ChannelClose2Proc, Tcl_ChannelInputProc, Tcl_ChannelOutputProc, Tcl_ChannelSeekProc, Tcl_ChannelWideSeekProc, Tcl_ChannelTruncateProc, Tcl_ChannelSetOptionProc, Tcl_ChannelGetOptionProc, Tcl_ChannelWatchProc, Tcl_ChannelGetHandleProc, Tcl_ChannelFlushProc, Tcl_ChannelHandlerProc, Tcl_ChannelThreadActionProc, Tcl_IsChannelShared, Tcl_IsChannelRegistered, Tcl_CutChannel, Tcl_SpliceChannel, Tcl_IsChannelExisting, Tcl_ClearChannelHandlers, Tcl_GetChannelThread, Tcl_ChannelBuffered \- procedures for creating and manipulating channels
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -23,16 +23,14 @@ ClientData
 Tcl_ChannelType *
 \fBTcl_GetChannelType\fR(\fIchannel\fR)
 .sp
-CONST char *
+const char *
 \fBTcl_GetChannelName\fR(\fIchannel\fR)
 .sp
 int
 \fBTcl_GetChannelHandle\fR(\fIchannel, direction, handlePtr\fR)
 .sp
-.VS 8.4
 Tcl_ThreadId
 \fBTcl_GetChannelThread\fR(\fIchannel\fR)
-.VE 8.4
 .sp
 int
 \fBTcl_GetChannelMode\fR(\fIchannel\fR)
@@ -46,7 +44,6 @@ int
 .sp
 int
 \fBTcl_BadChannelOption\fR(\fIinterp, optionName, optionList\fR)
-.VS 8.4
 .sp
 int
 \fBTcl_IsChannelShared\fR(\fIchannel\fR)
@@ -65,12 +62,11 @@ void
 .sp
 void
 \fBTcl_ClearChannelHandlers\fR(\fIchannel\fR)
-.VE 8.4
 .sp
 int
 \fBTcl_ChannelBuffered\fR(\fIchannel\fR)
 .sp
-CONST char *
+const char *
 \fBTcl_ChannelName\fR(\fItypePtr\fR)
 .sp
 Tcl_ChannelTypeVersion
@@ -94,13 +90,16 @@ Tcl_DriverOutputProc *
 Tcl_DriverSeekProc *
 \fBTcl_ChannelSeekProc\fR(\fItypePtr\fR)
 .sp
-.VS 8.4
 Tcl_DriverWideSeekProc *
 \fBTcl_ChannelWideSeekProc\fR(\fItypePtr\fR)
 .sp
 Tcl_DriverThreadActionProc *
 \fBTcl_ChannelThreadActionProc\fR(\fItypePtr\fR)
-.VE 8.4
+.sp
+.VS 8.5
+Tcl_DriverTruncateProc *
+\fBTcl_ChannelTruncateProc\fR(\fItypePtr\fR)
+.VE 8.5
 .sp
 Tcl_DriverSetOptionProc *
 \fBTcl_ChannelSetOptionProc\fR(\fItypePtr\fR)
@@ -121,11 +120,11 @@ Tcl_DriverHandlerProc *
 \fBTcl_ChannelHandlerProc\fR(\fItypePtr\fR)
 .sp
 .SH ARGUMENTS
-.AS Tcl_ChannelType *channelName in
-.AP Tcl_ChannelType *typePtr in
+.AS "const Tcl_ChannelType" *channelName
+.AP "const Tcl_ChannelType" *typePtr in
 Points to a structure containing the addresses of procedures that
 can be called to perform I/O and other functions on the channel.
-.AP "CONST char" *channelName in
+.AP "const char" *channelName in
 The name of this channel, such as \fBfile3\fR; must not be in use
 by any other channel. Can be NULL, in which case the channel is
 created without a name.
@@ -151,10 +150,11 @@ and \fBTCL_EXCEPTION\fR that indicates events that have occurred on
 this channel.
 .AP Tcl_Interp *interp in
 Current interpreter. (can be NULL)
-.AP "CONST char" *optionName in
+.AP "const char" *optionName in
 Name of the invalid option.
-.AP "CONST char" *optionList in
-Specific options list (space separated words, without "-") 
+.AP "const char" *optionList in
+Specific options list (space separated words, without
+.QW \- )
 to append to the standard generic options list.
 Can be NULL for generic options error message only.
 
@@ -178,7 +178,7 @@ driver provides a \fBTcl_ChannelType\fR structure containing pointers to
 functions implementing the various operations used by the generic layer to
 communicate with the channel driver. The \fBTcl_ChannelType\fR structure
 and the functions referenced by it are described in the section
-TCL_CHANNELTYPE, below.
+\fBTCL_CHANNELTYPE\fR, below.
 .PP
 Second, channel drivers usually provide a Tcl command to create
 instances of that type of channel. For example, the Tcl \fBopen\fR
@@ -205,7 +205,7 @@ structure to perform operations on the channel.
 \fItypePtr\fR and \fIinstanceData\fR with it. The channel is opened in the
 mode indicated by \fImask\fR.
 For a discussion of channel drivers, their operations and the
-\fBTcl_ChannelType\fR structure, see the section TCL_CHANNELTYPE, below.
+\fBTcl_ChannelType\fR structure, see the section \fBTCL_CHANNELTYPE\fR, below.
 .PP
 \fBTcl_CreateChannel\fR interacts with the code managing the standard
 channels. Once a standard channel was initialized either through a
@@ -237,11 +237,9 @@ then \fBTCL_ERROR\fR is returned instead.  Different channel drivers
 will return different types of handle.  Refer to the manual entries
 for each driver to determine what type of handle is returned.
 .PP
-.VS 8.4
 \fBTcl_GetChannelThread\fR returns the id of the thread currently managing
 the specified \fIchannel\fR. This allows channel drivers to send their file
 events to the correct event queue even for a multi-threaded core.
-.VE 8.4
 .PP
 \fBTcl_GetChannelMode\fR returns an OR-ed combination of \fBTCL_READABLE\fR
 and \fBTCL_WRITABLE\fR, indicating whether the channel is open for input
@@ -265,15 +263,15 @@ occurred on the channel.  Channel drivers are responsible for invoking
 this function whenever the channel handlers need to be called for the
 channel.  See \fBWATCHPROC\fR below for more details.
 .PP
-\fBTcl_BadChannelOption\fR is called from driver specific set or get option
-procs to generate a complete error message.
+\fBTcl_BadChannelOption\fR is called from driver specific
+\fIsetOptionProc\fR or \fIgetOptionProc\fR to generate a complete
+error message.
 .PP
 \fBTcl_ChannelBuffered\fR returns the number of bytes of input
 currently buffered in the internal buffer (push back area) of the
 channel itself. It does not report about the data in the overall
 buffers for the stack of channels the supplied channel is part of.
 .PP
-.VS 8.4
 \fBTcl_IsChannelShared\fR checks the refcount of the specified
 \fIchannel\fR and returns whether the \fIchannel\fR was shared among
 multiple interpreters (result == 1) or not (result == 0).
@@ -290,26 +288,24 @@ name is registered in the (thread)-global list of all channels (result
 (thread)global list of all channels (of the current thread).
 Application to a channel still registered in some interpreter
 is not allowed.
-.VS 8.4
+.VS 8.5
 Also notifies the driver if the \fBTcl_ChannelType\fR version is
 \fBTCL_CHANNEL_VERSION_4\fR (or higher), and
 \fBTcl_DriverThreadActionProc\fR is defined for it.
-.VE 8.4
+.VE 8.5
 .PP
 \fBTcl_SpliceChannel\fR adds the specified \fIchannel\fR to the
 (thread)global list of all channels (of the current thread).
 Application to a channel registered in some interpreter is not allowed.
-.VS 8.4
+.VS 8.5
 Also notifies the driver if the \fBTcl_ChannelType\fR version is
 \fBTCL_CHANNEL_VERSION_4\fR (or higher), and
 \fBTcl_DriverThreadActionProc\fR is defined for it.
-.VE 8.4
+.VE 8.5
 .PP
-\fBTcl_ClearChannelHandlers\fR removes all channelhandlers and event
+\fBTcl_ClearChannelHandlers\fR removes all channel handlers and event
 scripts associated with the specified \fIchannel\fR, thus shutting
 down all event processing for this channel.
-.VE 8.4
-
 .SH TCL_CHANNELTYPE
 .PP
 A channel driver provides a \fBTcl_ChannelType\fR structure that contains
@@ -322,22 +318,25 @@ details about the old structure.
 The \fBTcl_ChannelType\fR structure contains the following fields:
 .CS
 typedef struct Tcl_ChannelType {
-	char *\fItypeName\fR;
-	Tcl_ChannelTypeVersion \fIversion\fR;
-	Tcl_DriverCloseProc *\fIcloseProc\fR;
-	Tcl_DriverInputProc *\fIinputProc\fR;
-	Tcl_DriverOutputProc *\fIoutputProc\fR;
-	Tcl_DriverSeekProc *\fIseekProc\fR;
-	Tcl_DriverSetOptionProc *\fIsetOptionProc\fR;
-	Tcl_DriverGetOptionProc *\fIgetOptionProc\fR;
-	Tcl_DriverWatchProc *\fIwatchProc\fR;
-	Tcl_DriverGetHandleProc *\fIgetHandleProc\fR;
-	Tcl_DriverClose2Proc *\fIclose2Proc\fR;
-	Tcl_DriverBlockModeProc *\fIblockModeProc\fR;	
-	Tcl_DriverFlushProc *\fIflushProc\fR;	
-	Tcl_DriverHandlerProc *\fIhandlerProc\fR;	
-	Tcl_DriverWideSeekProc *\fIwideSeekProc\fR;
-	Tcl_DriverThreadActionProc *\fIthreadActionProc\fR;
+        char *\fItypeName\fR;
+        Tcl_ChannelTypeVersion \fIversion\fR;
+        Tcl_DriverCloseProc *\fIcloseProc\fR;
+        Tcl_DriverInputProc *\fIinputProc\fR;
+        Tcl_DriverOutputProc *\fIoutputProc\fR;
+        Tcl_DriverSeekProc *\fIseekProc\fR;
+        Tcl_DriverSetOptionProc *\fIsetOptionProc\fR;
+        Tcl_DriverGetOptionProc *\fIgetOptionProc\fR;
+        Tcl_DriverWatchProc *\fIwatchProc\fR;
+        Tcl_DriverGetHandleProc *\fIgetHandleProc\fR;
+        Tcl_DriverClose2Proc *\fIclose2Proc\fR;
+        Tcl_DriverBlockModeProc *\fIblockModeProc\fR;
+        Tcl_DriverFlushProc *\fIflushProc\fR;
+        Tcl_DriverHandlerProc *\fIhandlerProc\fR;
+        Tcl_DriverWideSeekProc *\fIwideSeekProc\fR;
+        Tcl_DriverThreadActionProc *\fIthreadActionProc\fR;
+.VS 8.5
+        Tcl_DriverTruncateProc *\fItruncateProc\fR;
+.VE 8.5
 } Tcl_ChannelType;
 .CE
 .PP
@@ -345,11 +344,11 @@ It is not necessary to provide implementations for all channel
 operations.  Those which are not necessary may be set to NULL in the
 struct: \fIblockModeProc\fR, \fIseekProc\fR, \fIsetOptionProc\fR,
 \fIgetOptionProc\fR, and \fIclose2Proc\fR, in addition to
-\fIflushProc\fR, \fIhandlerProc\fR, and \fIthreadActionProc\fR.  Other
-functions that cannot be implemented in a meaningful way should return
-\fBEINVAL\fR when called, to indicate that the operations they
-represent are not available. Also note that \fIwideSeekProc\fR can be
-NULL if \fIseekProc\fR is.
+\fIflushProc\fR, \fIhandlerProc\fR, \fIthreadActionProc\fR, and
+\fItruncateProc\fR.  Other functions that cannot be implemented in a
+meaningful way should return \fBEINVAL\fR when called, to indicate
+that the operations they represent are not available. Also note that
+\fIwideSeekProc\fR can be NULL if \fIseekProc\fR is.
 .PP
 The user should only use the above structure for \fBTcl_ChannelType\fR
 instantiation.  When referencing fields in a \fBTcl_ChannelType\fR
@@ -358,20 +357,19 @@ structure, the following functions should be used to obtain the values:
 \fBTcl_ChannelBlockModeProc\fR, \fBTcl_ChannelCloseProc\fR,
 \fBTcl_ChannelClose2Proc\fR, \fBTcl_ChannelInputProc\fR,
 \fBTcl_ChannelOutputProc\fR, \fBTcl_ChannelSeekProc\fR,
-.VS 8.4
-\fBTcl_ChannelWideSeekProc\fR,
-\fBTcl_ChannelThreadActionProc\fR,
-.VE 8.4
+\fBTcl_ChannelWideSeekProc\fR, \fBTcl_ChannelThreadActionProc\fR,
+.VS 8.5
+\fBTcl_ChannelTruncateProc\fR,
+.VE 8.5
 \fBTcl_ChannelSetOptionProc\fR, \fBTcl_ChannelGetOptionProc\fR,
 \fBTcl_ChannelWatchProc\fR, \fBTcl_ChannelGetHandleProc\fR,
 \fBTcl_ChannelFlushProc\fR, or \fBTcl_ChannelHandlerProc\fR.
 .PP
 The change to the structures was made in such a way that standard channel
 types are binary compatible.  However, channel types that use stacked
-channels (ie: TLS, Trf) have new versions to correspond to the above change
+channels (i.e. TLS, Trf) have new versions to correspond to the above change
 since the previous code for stacked channels had problems.
-
-.SH TYPENAME
+.SS TYPENAME
 .PP
 The \fItypeName\fR field contains a null-terminated string that
 identifies the type of the device implemented by this driver, e.g.
@@ -379,19 +377,19 @@ identifies the type of the device implemented by this driver, e.g.
 .PP
 This value can be retrieved with \fBTcl_ChannelName\fR, which returns
 a pointer to the string.
-
-.SH VERSION
+.SS VERSION
 .PP
 
 The \fIversion\fR field should be set to the version of the structure
 that you require. \fBTCL_CHANNEL_VERSION_2\fR is the minimum recommended.
-.VS 8.4
-\fBTCL_CHANNEL_VERSION_3\fR must be set to specifiy the \fIwideSeekProc\fR member.
-.VE 8.4
-.VS 8.4
-\fBTCL_CHANNEL_VERSION_4\fR must be set to specifiy the
-\fIthreadActionProc\fR member (includes \fIwideSeekProc\fR).
-.VE 8.4
+\fBTCL_CHANNEL_VERSION_3\fR must be set to specify the \fIwideSeekProc\fR member.
+\fBTCL_CHANNEL_VERSION_4\fR must be set to specify the \fIthreadActionProc\fR member
+(includes \fIwideSeekProc\fR).
+.VS 8.5
+\fBTCL_CHANNEL_VERSION_5\fR must be set to specify the
+\fItruncateProc\fR members (includes
+\fIwideSeekProc\fR and \fIthreadActionProc\fR).
+.VE 8.5
 If it is not set to any of these, then this
 \fBTcl_ChannelType\fR is assumed to have the original structure.  See
 \fBOLD CHANNEL TYPES\fR for more details.  While Tcl will recognize
@@ -399,12 +397,14 @@ and function with either structures, stacked channels must be of at
 least \fBTCL_CHANNEL_VERSION_2\fR to function correctly.
 .PP
 This value can be retrieved with \fBTcl_ChannelVersion\fR, which returns
-.VS 8.4
-one of \fBTCL_CHANNEL_VERSION_4\fR, \fBTCL_CHANNEL_VERSION_3\fR,
-.VE 8.4
-\fBTCL_CHANNEL_VERSION_2\fR, or \fBTCL_CHANNEL_VERSION_1\fR.
-
-.SH BLOCKMODEPROC
+one of
+.VS 8.5
+\fBTCL_CHANNEL_VERSION_5\fR,
+.VE 8.5
+\fBTCL_CHANNEL_VERSION_4\fR,
+\fBTCL_CHANNEL_VERSION_3\fR,
+\fBTCL_CHANNEL_VERSION_2\fR or \fBTCL_CHANNEL_VERSION_1\fR.
+.SS BLOCKMODEPROC
 .PP
 The \fIblockModeProc\fR field contains the address of a function called by
 the generic layer to set blocking and nonblocking mode on the device.
@@ -412,8 +412,8 @@ the generic layer to set blocking and nonblocking mode on the device.
 .PP
 .CS
 typedef int Tcl_DriverBlockModeProc(
-	ClientData \fIinstanceData\fR,
-	int \fImode\fR);
+        ClientData \fIinstanceData\fR,
+        int \fImode\fR);
 .CE
 .PP
 The \fIinstanceData\fR is the same as the value passed to
@@ -437,11 +437,9 @@ A channel driver \fBnot\fR supplying a \fIblockModeProc\fR has to be
 very, very careful. It has to tell the generic layer exactly which
 blocking mode is acceptable to it, and should this also document for
 the user so that the blocking mode of the channel is not changed to an
-inacceptable value. Any confusion here may lead the interpreter into a
+unacceptable value. Any confusion here may lead the interpreter into a
 (spurious and difficult to find) deadlock.
-
-
-.SH "CLOSEPROC AND CLOSE2PROC"
+.SS "CLOSEPROC AND CLOSE2PROC"
 .PP
 The \fIcloseProc\fR field contains the address of a function called by the
 generic layer to clean up driver-related information when the channel is
@@ -449,8 +447,8 @@ closed. \fICloseProc\fR must match the following prototype:
 .PP
 .CS
 typedef int Tcl_DriverCloseProc(
-	ClientData \fIinstanceData\fR,
-	Tcl_Interp *\fIinterp\fR);
+        ClientData \fIinstanceData\fR,
+        Tcl_Interp *\fIinterp\fR);
 .CE
 .PP
 The \fIinstanceData\fR argument is the same as the value provided to
@@ -471,9 +469,9 @@ following prototype:
 .PP
 .CS
 typedef int Tcl_DriverClose2Proc(
-	ClientData \fIinstanceData\fR,
-	Tcl_Interp *\fIinterp\fR,
-	int \fIflags\fR);
+        ClientData \fIinstanceData\fR,
+        Tcl_Interp *\fIinterp\fR,
+        int \fIflags\fR);
 .CE
 .PP
 The \fIclose2Proc\fR will be called with \fIflags\fR set to an OR'ed
@@ -491,11 +489,10 @@ return a nonzero POSIX error code. In addition, if an error occurs and
 \fIinterp\fR is not NULL, the procedure should store an error message
 in the interpreter's result.
 .PP
-These value can be retrieved with \fBTcl_ChannelCloseProc\fR or
-\fBTcl_ChannelClose2Proc\fR, which returns a pointer to the respective
-function.
-
-.SH INPUTPROC
+The \fIcloseProc\fR and \fIclose2Proc\fR values can be retrieved with
+\fBTcl_ChannelCloseProc\fR or \fBTcl_ChannelClose2Proc\fR, which
+return a pointer to the respective function.
+.SS INPUTPROC
 .PP
 The \fIinputProc\fR field contains the address of a function called by the
 generic layer to read data from the file or device and store it in an
@@ -503,10 +500,10 @@ internal buffer. \fIInputProc\fR must match the following prototype:
 .PP
 .CS
 typedef int Tcl_DriverInputProc(
-	ClientData \fIinstanceData\fR,
-	char *\fIbuf\fR,
-	int \fIbufSize\fR,
-	int *\fIerrorCodePtr\fR);
+        ClientData \fIinstanceData\fR,
+        char *\fIbuf\fR,
+        int \fIbufSize\fR,
+        int *\fIerrorCodePtr\fR);
 .CE
 .PP
 \fIInstanceData\fR is the same as the value passed to
@@ -539,8 +536,7 @@ blocking.
 .PP
 This value can be retrieved with \fBTcl_ChannelInputProc\fR, which returns
 a pointer to the function.
-
-.SH OUTPUTPROC
+.SS OUTPUTPROC
 .PP
 The \fIoutputProc\fR field contains the address of a function called by the
 generic layer to transfer data from an internal buffer to the output device.
@@ -548,10 +544,10 @@ generic layer to transfer data from an internal buffer to the output device.
 .PP
 .CS
 typedef int Tcl_DriverOutputProc(
-	ClientData \fIinstanceData\fR,
-	CONST char *\fIbuf\fR,
-	int \fItoWrite\fR,
-	int *\fIerrorCodePtr\fR);
+        ClientData \fIinstanceData\fR,
+        const char *\fIbuf\fR,
+        int \fItoWrite\fR,
+        int *\fIerrorCodePtr\fR);
 .CE
 .PP
 \fIInstanceData\fR is the same as the value passed to
@@ -578,8 +574,7 @@ without writing any data.
 .PP
 This value can be retrieved with \fBTcl_ChannelOutputProc\fR, which returns
 a pointer to the function.
-
-.SH "SEEKPROC AND WIDESEEKPROC"
+.SS "SEEKPROC AND WIDESEEKPROC"
 .PP
 The \fIseekProc\fR field contains the address of a function called by the
 generic layer to move the access point at which subsequent input or output
@@ -588,10 +583,10 @@ prototype:
 .PP
 .CS
 typedef int Tcl_DriverSeekProc(
-	ClientData \fIinstanceData\fR,
-	long \fIoffset\fR,
-	int \fIseekMode\fR,
-	int *\fIerrorCodePtr\fR);
+        ClientData \fIinstanceData\fR,
+        long \fIoffset\fR,
+        int \fIseekMode\fR,
+        int *\fIerrorCodePtr\fR);
 .CE
 .PP
 The \fIinstanceData\fR argument is the same as the value given to
@@ -608,7 +603,6 @@ does not implement seeking.
 The return value is the new access point or -1 in case of error. If an
 error occurred, the function should not move the access point.
 .PP
-.VS 8.4
 If there is a non-NULL \fIseekProc\fR field, the \fIwideSeekProc\fR
 field may contain the address of an alternative function to use which
 handles wide (i.e. larger than 32-bit) offsets, so allowing seeks
@@ -619,10 +613,10 @@ following prototype:
 .PP
 .CS
 typedef Tcl_WideInt Tcl_DriverWideSeekProc(
-	ClientData \fIinstanceData\fR,
-	Tcl_WideInt \fIoffset\fR,
-	int \fIseekMode\fR,
-	int *\fIerrorCodePtr\fR);
+        ClientData \fIinstanceData\fR,
+        Tcl_WideInt \fIoffset\fR,
+        int \fIseekMode\fR,
+        int *\fIerrorCodePtr\fR);
 .CE
 .PP
 The arguments and return values mean the same thing as with
@@ -633,9 +627,7 @@ The \fIseekProc\fR value can be retrieved with
 \fBTcl_ChannelSeekProc\fR, which returns a pointer to the function,
 and similarly the \fIwideSeekProc\fR can be retrieved with
 \fBTcl_ChannelWideSeekProc\fR.
-.VE 8.4
-
-.SH SETOPTIONPROC
+.SS SETOPTIONPROC
 .PP
 The \fIsetOptionProc\fR field contains the address of a function called by
 the generic layer to set a channel type specific option on a channel.
@@ -643,10 +635,10 @@ the generic layer to set a channel type specific option on a channel.
 .PP
 .CS
 typedef int Tcl_DriverSetOptionProc(
-	ClientData \fIinstanceData\fR,
-	Tcl_Interp *\fIinterp\fR,
-	CONST char *\fIoptionName\fR,
-	CONST char *\fInewValue\fR);
+        ClientData \fIinstanceData\fR,
+        Tcl_Interp *\fIinterp\fR,
+        const char *\fIoptionName\fR,
+        const char *\fInewValue\fR);
 .CE
 .PP
 \fIoptionName\fR is the name of an option to set, and \fInewValue\fR is
@@ -656,7 +648,7 @@ created. The function should do whatever channel type specific action is
 required to implement the new value of the option.
 .PP
 Some options are handled by the generic code and this function is never
-called to set them, e.g. \fB-blockmode\fR. Other options are specific to
+called to set them, e.g. \fB\-blockmode\fR. Other options are specific to
 each channel type and the \fIsetOptionProc\fR procedure of the channel
 driver will get called to implement them. The \fIsetOptionProc\fR field can
 be NULL, which indicates that this channel type supports no type specific
@@ -676,8 +668,7 @@ error code.
 .PP
 This value can be retrieved with \fBTcl_ChannelSetOptionProc\fR, which returns
 a pointer to the function.
-
-.SH GETOPTIONPROC
+.SS GETOPTIONPROC
 .PP
 The \fIgetOptionProc\fR field contains the address of a function called by
 the generic layer to get the value of a channel type specific option on a
@@ -685,10 +676,10 @@ channel. \fIgetOptionProc\fR must match the following prototype:
 .PP
 .CS
 typedef int Tcl_DriverGetOptionProc(
-	ClientData \fIinstanceData\fR,
-	Tcl_Interp *\fIinterp\fR,
-	CONST char *\fIoptionName\fR,
-	Tcl_DString *\fIoptionValue\fR);
+        ClientData \fIinstanceData\fR,
+        Tcl_Interp *\fIinterp\fR,
+        const char *\fIoptionName\fR,
+        Tcl_DString *\fIoptionValue\fR);
 .CE
 .PP
 \fIOptionName\fR is the name of an option supported by this type of
@@ -706,7 +697,7 @@ function should also call \fBTcl_SetErrno\fR to store an appropriate POSIX
 error code.
 .PP
 Some options are handled by the generic code and this function is never
-called to retrieve their value, e.g. \fB-blockmode\fR. Other options are
+called to retrieve their value, e.g. \fB\-blockmode\fR. Other options are
 specific to each channel type and the \fIgetOptionProc\fR procedure of the
 channel driver will get called to implement them. The \fIgetOptionProc\fR
 field can be NULL, which indicates that this channel type supports no type
@@ -714,8 +705,7 @@ specific options.
 .PP
 This value can be retrieved with \fBTcl_ChannelGetOptionProc\fR, which returns
 a pointer to the function.
-
-.SH WATCHPROC
+.SS WATCHPROC
 .PP
 The \fIwatchProc\fR field contains the address of a function called
 by the generic layer to initialize the event notification mechanism to
@@ -724,8 +714,8 @@ notice events of interest on this channel.
 .PP
 .CS
 typedef void Tcl_DriverWatchProc(
-	ClientData \fIinstanceData\fR,
-	int \fImask\fR);
+        ClientData \fIinstanceData\fR,
+        int \fImask\fR);
 .CE
 .PP
 The \fIinstanceData\fR is the same as the value passed to
@@ -747,8 +737,7 @@ details on how to queue an event.
 .PP
 This value can be retrieved with \fBTcl_ChannelWatchProc\fR, which returns
 a pointer to the function.
-
-.SH GETHANDLEPROC
+.SS GETHANDLEPROC
 .PP
 The \fIgetHandleProc\fR field contains the address of a function called by
 the generic layer to retrieve a device-specific handle from the channel.
@@ -756,9 +745,9 @@ the generic layer to retrieve a device-specific handle from the channel.
 .PP
 .CS
 typedef int Tcl_DriverGetHandleProc(
-	ClientData \fIinstanceData\fR,
-	int \fIdirection\fR,
-	ClientData *\fIhandlePtr\fR);
+        ClientData \fIinstanceData\fR,
+        int \fIdirection\fR,
+        ClientData *\fIhandlePtr\fR);
 .CE
 .PP
 \fIInstanceData\fR is the same as the value passed to
@@ -777,8 +766,7 @@ device handles, the function should return \fBTCL_ERROR\fR.
 .PP
 This value can be retrieved with \fBTcl_ChannelGetHandleProc\fR, which returns
 a pointer to the function.
-
-.SH FLUSHPROC
+.SS FLUSHPROC
 .PP
 The \fIflushProc\fR field is currently reserved for future use.
 It should be set to NULL.
@@ -786,13 +774,12 @@ It should be set to NULL.
 .PP
 .CS
 typedef int Tcl_DriverFlushProc(
-	ClientData \fIinstanceData\fR);
+        ClientData \fIinstanceData\fR);
 .CE
 .PP
 This value can be retrieved with \fBTcl_ChannelFlushProc\fR, which returns
 a pointer to the function.
-
-.SH HANDLERPROC
+.SS HANDLERPROC
 .PP
 The \fIhandlerProc\fR field contains the address of a function called by
 the generic layer to notify the channel that an event occurred.  It should
@@ -802,8 +789,8 @@ that occur on the underlying (stacked) channel.
 .PP
 .CS
 typedef int Tcl_DriverHandlerProc(
-	ClientData \fIinstanceData\fR,
-	int \fIinterestMask\fR);
+        ClientData \fIinstanceData\fR,
+        int \fIinterestMask\fR);
 .CE
 .PP
 \fIInstanceData\fR is the same as the value passed to \fBTcl_CreateChannel\fR
@@ -814,8 +801,7 @@ type of event occurred on this channel.
 This value can be retrieved with \fBTcl_ChannelHandlerProc\fR, which returns
 a pointer to the function.
 
-.VS 8.4
-.SH "THREADACTIONPROC"
+.SS "THREADACTIONPROC"
 .PP
 The \fIthreadActionProc\fR field contains the address of the function
 called by the generic layer when a channel is created, closed, or
@@ -832,8 +818,8 @@ might be maintaining using the calling thread as the associate. See
 .PP
 .CS
 typedef void Tcl_DriverThreadActionProc(
-	ClientData \fIinstanceData\fR,
-      int        \fIaction\fR);
+        ClientData \fIinstanceData\fR,
+        int        \fIaction\fR);
 .CE
 .PP
 \fIInstanceData\fR is the same as the value passed to
@@ -841,53 +827,79 @@ typedef void Tcl_DriverThreadActionProc(
 .PP
 These values can be retrieved with \fBTcl_ChannelThreadActionProc\fR,
 which returns a pointer to the function.
-.VE 8.4
-
+.SS "TRUNCATEPROC"
+.PP
+The \fItruncateProc\fR field contains the address of the function
+called by the generic layer when a channel is truncated to some
+length. It can be NULL.
+.PP
+.CS
+typedef int Tcl_DriverTruncateProc(
+        ClientData \fIinstanceData\fR,
+        Tcl_WideInt \fIlength\fR);
+.CE
+.PP
+\fIInstanceData\fR is the same as the value passed to
+\fBTcl_CreateChannel\fR when this channel was created, and
+\fIlength\fR is the new length of the underlying file, which should
+not be negative. The result should be 0 on success or an errno code
+(suitable for use with \fBTcl_SetErrno\fR) on failure.
+.PP
+These values can be retrieved with \fBTcl_ChannelTruncateProc\fR,
+which returns a pointer to the function.
 .SH TCL_BADCHANNELOPTION
 .PP
-This procedure generates a "bad option" error message in an
+This procedure generates a
+.QW "bad option"
+error message in an
 (optional) interpreter.  It is used by channel drivers when 
-a invalid Set/Get option is requested. Its purpose is to concatenate
+an invalid Set/Get option is requested. Its purpose is to concatenate
 the generic options list to the specific ones and factorize
 the generic options error message string.
 .PP
-It always return \fBTCL_ERROR\fR
+It always returns \fBTCL_ERROR\fR
 .PP
 An error message is generated in \fIinterp\fR's result object to
-indicate that a command was invoked with the a bad option
+indicate that a command was invoked with a bad option.
 The message has the form
 .CS
     bad option "blah": should be one of 
     <...generic options...>+<...specific options...>
+.CE
 so you get for instance:
+.CS
     bad option "-blah": should be one of -blocking,
     -buffering, -buffersize, -eofchar, -translation,
     -peername, or -sockname
-when called with \fIoptionList\fR="peername sockname"
 .CE
-``blah'' is the \fIoptionName\fR argument and ``<specific options>''
+when called with \fIoptionList\fR equal to
+.QW "peername sockname"
+.PP
+.QW blah
+is the \fIoptionName\fR argument and
+.QW "<specific options>"
 is a space separated list of specific option words.
 The function takes good care of inserting minus signs before
-each option, commas after, and an ``or'' before the last option.
-
+each option, commas after, and an
+.QW or
+before the last option.
 .SH "OLD CHANNEL TYPES"
-
 The original (8.3.1 and below) \fBTcl_ChannelType\fR structure contains
 the following fields:
 .PP
 .CS
 typedef struct Tcl_ChannelType {
-	char *\fItypeName\fR;
-	Tcl_DriverBlockModeProc *\fIblockModeProc\fR;	
-	Tcl_DriverCloseProc *\fIcloseProc\fR;
-	Tcl_DriverInputProc *\fIinputProc\fR;
-	Tcl_DriverOutputProc *\fIoutputProc\fR;
-	Tcl_DriverSeekProc *\fIseekProc\fR;
-	Tcl_DriverSetOptionProc *\fIsetOptionProc\fR;
-	Tcl_DriverGetOptionProc *\fIgetOptionProc\fR;
-	Tcl_DriverWatchProc *\fIwatchProc\fR;
-	Tcl_DriverGetHandleProc *\fIgetHandleProc\fR;
-	Tcl_DriverClose2Proc *\fIclose2Proc\fR;
+        char *\fItypeName\fR;
+        Tcl_DriverBlockModeProc *\fIblockModeProc\fR;
+        Tcl_DriverCloseProc *\fIcloseProc\fR;
+        Tcl_DriverInputProc *\fIinputProc\fR;
+        Tcl_DriverOutputProc *\fIoutputProc\fR;
+        Tcl_DriverSeekProc *\fIseekProc\fR;
+        Tcl_DriverSetOptionProc *\fIsetOptionProc\fR;
+        Tcl_DriverGetOptionProc *\fIgetOptionProc\fR;
+        Tcl_DriverWatchProc *\fIwatchProc\fR;
+        Tcl_DriverGetHandleProc *\fIgetHandleProc\fR;
+        Tcl_DriverClose2Proc *\fIclose2Proc\fR;
 } Tcl_ChannelType;
 .CE
 .PP
@@ -897,33 +909,32 @@ the new \fBTcl_ChannelType\fR structure if you are creating a stacked
 channel driver, due to problems with the earlier stacked channel
 implementation (in 8.2.0 to 8.3.1).
 .PP
-.VS 8.4
 Prior to 8.4.0 (i.e. during the later releases of 8.3 and early part
 of the 8.4 development cycle) the \fBTcl_ChannelType\fR structure
 contained the following fields:
 .PP
 .CS
 typedef struct Tcl_ChannelType {
-	char *\fItypeName\fR;
-	Tcl_ChannelTypeVersion \fIversion\fR;
-	Tcl_DriverCloseProc *\fIcloseProc\fR;
-	Tcl_DriverInputProc *\fIinputProc\fR;
-	Tcl_DriverOutputProc *\fIoutputProc\fR;
-	Tcl_DriverSeekProc *\fIseekProc\fR;
-	Tcl_DriverSetOptionProc *\fIsetOptionProc\fR;
-	Tcl_DriverGetOptionProc *\fIgetOptionProc\fR;
-	Tcl_DriverWatchProc *\fIwatchProc\fR;
-	Tcl_DriverGetHandleProc *\fIgetHandleProc\fR;
-	Tcl_DriverClose2Proc *\fIclose2Proc\fR;
-	Tcl_DriverBlockModeProc *\fIblockModeProc\fR;	
-	Tcl_DriverFlushProc *\fIflushProc\fR;	
-	Tcl_DriverHandlerProc *\fIhandlerProc\fR;	
+        char *\fItypeName\fR;
+        Tcl_ChannelTypeVersion \fIversion\fR;
+        Tcl_DriverCloseProc *\fIcloseProc\fR;
+        Tcl_DriverInputProc *\fIinputProc\fR;
+        Tcl_DriverOutputProc *\fIoutputProc\fR;
+        Tcl_DriverSeekProc *\fIseekProc\fR;
+        Tcl_DriverSetOptionProc *\fIsetOptionProc\fR;
+        Tcl_DriverGetOptionProc *\fIgetOptionProc\fR;
+        Tcl_DriverWatchProc *\fIwatchProc\fR;
+        Tcl_DriverGetHandleProc *\fIgetHandleProc\fR;
+        Tcl_DriverClose2Proc *\fIclose2Proc\fR;
+        Tcl_DriverBlockModeProc *\fIblockModeProc\fR;
+        Tcl_DriverFlushProc *\fIflushProc\fR;
+        Tcl_DriverHandlerProc *\fIhandlerProc\fR;
+        Tcl_DriverTruncateProc *\fItruncateProc\fR;
 } Tcl_ChannelType;
 .CE
 .PP
 When the above structure is registered as a channel type, the
 \fIversion\fR field should always be \fBTCL_CHANNEL_VERSION_2\fR.
-.VE 8.4
 
 .SH "SEE ALSO"
 Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3), Tcl_QueueEvent(3), Tcl_StackChannel(3), Tcl_GetStdChannel(3)

doc/CrtChnlHdlr.3

@@ -48,8 +48,8 @@ what it means for a channel to be readable or writable.
 \fIProc\fR must conform to the following prototype:
 .CS
 typedef void Tcl_ChannelProc(
-	ClientData \fIclientData\fR,
-	int \fImask\fR);
+        ClientData \fIclientData\fR,
+        int \fImask\fR);
 .CE
 .PP
 The \fIclientData\fR argument is the same as the value passed to
@@ -62,7 +62,7 @@ contain a subset of the bits from the \fImask\fR argument to
 .PP
 Each channel handler is identified by a unique combination of \fIchannel\fR,
 \fIproc\fR and \fIclientData\fR.
-There may be many handlers for a given channel as long as they don't
+There may be many handlers for a given channel as long as they do not
 have the same \fIchannel\fR, \fIproc\fR, and \fIclientData\fR.
 If \fBTcl_CreateChannelHandler\fR is invoked when there is already a handler
 for \fIchannel\fR, \fIproc\fR, and \fIclientData\fR, then no new

doc/CrtCloseHdlr.3

@@ -21,7 +21,7 @@ void
 \fBTcl_DeleteCloseHandler\fR(\fIchannel, proc, clientData\fR)
 .sp
 .SH ARGUMENTS
-.AS Tcl_CloseProc callbackData in
+.AS Tcl_CloseProc clientData
 .AP Tcl_Channel channel in
 The channel for which to create or delete a close callback.
 .AP Tcl_CloseProc *proc in
@@ -39,7 +39,7 @@ Arbitrary one-word value to pass to \fIproc\fR.
 .PP
 .CS
 typedef void Tcl_CloseProc(
-	ClientData \fIclientData\fR);
+        ClientData \fIclientData\fR);
 .CE
 .PP
 The \fIclientData\fR is the same as the value provided in the call to

doc/CrtCommand.3

@@ -17,12 +17,10 @@ Tcl_CreateCommand \- implement new commands in C
 Tcl_Command
 \fBTcl_CreateCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR)
 .SH ARGUMENTS
-.AS Tcl_CmdDeleteProc **deleteProcPtr
+.AS Tcl_CmdDeleteProc *deleteProc
 .AP Tcl_Interp *interp in
 Interpreter in which to create new command.
-.VS 8.4
-.AP "CONST char" *cmdName in
-.VE
+.AP "const char" *cmdName in
 Name of command.
 .AP Tcl_CmdProc *proc in
 Implementation of new command:  \fIproc\fR will be called whenever
@@ -79,10 +77,10 @@ and it returns NULL.
 \fBTcl_CmdProc\fR:
 .CS
 typedef int Tcl_CmdProc(
-	ClientData \fIclientData\fR,
-	Tcl_Interp *\fIinterp\fR,
-	int \fIargc\fR,
-	CONST char *\fIargv\fR[]);
+        ClientData \fIclientData\fR,
+        Tcl_Interp *\fIinterp\fR,
+        int \fIargc\fR,
+        const char *\fIargv\fR[]);
 .CE
 When \fIproc\fR is invoked the \fIclientData\fR and \fIinterp\fR
 parameters will be copies of the \fIclientData\fR and \fIinterp\fR
@@ -95,26 +93,23 @@ the command name) and \fIargv\fR giving the values of the arguments
 as strings.  The \fIargv\fR array will contain \fIargc\fR+1 values;
 the first \fIargc\fR values point to the argument strings, and the
 last value is NULL.  
-.VS
 Note that the argument strings should not be modified as they may
 point to constant strings or may be shared with other parts of the
 interpreter.
-.VE
 .PP
-.VS
 Note that the argument strings are encoded in normalized UTF-8 since
 version 8.1 of Tcl.
-.VE
 .PP
-\fIProc\fR must return an integer code that is either \fBTCL_OK\fR, \fBTCL_ERROR\fR,
-\fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR.  See the Tcl overview man page
+\fIProc\fR must return an integer code that is expected to be one of
+\fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or
+\fBTCL_CONTINUE\fR.  See the Tcl overview man page
 for details on what these codes mean.  Most normal commands will only
 return \fBTCL_OK\fR or \fBTCL_ERROR\fR.  In addition, \fIproc\fR must set
 the interpreter result to point to a string value;
 in the case of a \fBTCL_OK\fR return code this gives the result
 of the command, and in the case of \fBTCL_ERROR\fR it gives an error message.
 The \fBTcl_SetResult\fR procedure provides an easy interface for setting
-the return value;  for complete details on how the the interpreter result
+the return value;  for complete details on how the interpreter result
 field is managed, see the \fBTcl_Interp\fR man page.
 Before invoking a command procedure,
 \fBTcl_Eval\fR sets the interpreter result to point to an empty string,
@@ -135,11 +130,11 @@ application an opportunity to release any structures associated
 with the command.  \fIDeleteProc\fR should have arguments and
 result that match the type \fBTcl_CmdDeleteProc\fR:
 .CS
-typedef void Tcl_CmdDeleteProc(ClientData \fIclientData\fR);
+typedef void Tcl_CmdDeleteProc(
+        ClientData \fIclientData\fR);
 .CE
 The \fIclientData\fR argument will be the same as the \fIclientData\fR
 argument passed to \fBTcl_CreateCommand\fR.
-.PP
 
 .SH "SEE ALSO"
 Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_GetCommandInfo, Tcl_SetCommandInfo, Tcl_GetCommandName, Tcl_SetObjResult

doc/CrtFileHdlr.3

@@ -13,18 +13,14 @@ Tcl_CreateFileHandler, Tcl_DeleteFileHandler \- associate procedure callbacks wi
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
-.VS
 .sp
 \fBTcl_CreateFileHandler\fR(\fIfd, mask, proc, clientData\fR)
 .sp
 \fBTcl_DeleteFileHandler\fR(\fIfd\fR)
-.VE
 .SH ARGUMENTS
 .AS Tcl_FileProc clientData
-.VS
 .AP int fd in
 Unix file descriptor for an open file or device.
-.VE
 .AP int mask in
 Conditions under which \fIproc\fR should be called:
 OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR,
@@ -39,12 +35,10 @@ Arbitrary one-word value to pass to \fIproc\fR.
 
 .SH DESCRIPTION
 .PP
-.VS
 \fBTcl_CreateFileHandler\fR arranges for \fIproc\fR to be
 invoked in the future whenever I/O becomes possible on a file
 or an exceptional condition exists for the file.  The file
 is indicated by \fIfd\fR, and the conditions of interest
-.VE
 are indicated by \fImask\fR.  For example, if \fImask\fR
 is \fBTCL_READABLE\fR, \fIproc\fR will be called when
 the file is readable.
@@ -57,8 +51,8 @@ as \fBvwait\fR.
 type \fBTcl_FileProc\fR:
 .CS
 typedef void Tcl_FileProc(
-	ClientData \fIclientData\fR,
-	int \fImask\fR);
+        ClientData \fIclientData\fR,
+        int \fImask\fR);
 .CE
 The \fIclientData\fR parameter to \fIproc\fR is a copy
 of the \fIclientData\fR
@@ -85,14 +79,12 @@ events while waiting for files to become ready for I/O.  For this to work
 correctly, the application may need to use non-blocking I/O operations on
 the files for which handlers are declared.  Otherwise the application may
 block if it reads or writes too much data; while waiting for the I/O to
-complete the application won't be able to service other events. Use
+complete the application will not be able to service other events. Use
 \fBTcl_SetChannelOption\fR with \fB\-blocking\fR to set the channel into
 blocking or nonblocking mode as required.
 .PP
-.VS
 Note that these interfaces are only supported by the Unix
 implementation of the Tcl notifier.   
-.VE
 
 .SH KEYWORDS
 callback, file, handler

doc/CrtMathFnc.3

@@ -17,20 +17,17 @@ Tcl_CreateMathFunc, Tcl_GetMathFuncInfo, Tcl_ListMathFuncs \- Define, query and
 void
 \fBTcl_CreateMathFunc\fR(\fIinterp, name, numArgs, argTypes, proc, clientData\fR)
 .sp
-.VS 8.4
 int
-\fBTcl_GetMathFuncInfo\fR(\fIinterp, name, numArgsPtr, argTypesPtr, procPtr, clientDataPtr\fR)
+\fBTcl_GetMathFuncInfo\fR(\fIinterp, name, numArgsPtr, argTypesPtr, procPtr,
+                    clientDataPtr\fR)
 .sp
 Tcl_Obj *
 \fBTcl_ListMathFuncs\fR(\fIinterp, pattern\fR)
-.VE
 .SH ARGUMENTS
-.AS Tcl_ValueType *clientDataPtr
+.AS Tcl_ValueType *clientDataPtr out
 .AP Tcl_Interp *interp in
 Interpreter in which new function will be defined.
-.VS 8.4
-.AP "CONST char" *name in
-.VE
+.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.
@@ -51,12 +48,12 @@ 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.)
+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
+.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
@@ -65,71 +62,70 @@ passing to \fITcl_StringMatch\fR), or NULL to not apply any filter.
 .PP
 Tcl allows a number of mathematical functions to be used in
 expressions, such as \fBsin\fR, \fBcos\fR, and \fBhypot\fR.
-\fBTcl_CreateMathFunc\fR allows applications to add additional functions
+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 doesn't already exist as a function then a new function
-is created.  If it does exist, then the existing function is replaced.
+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
-.VS 8.4
-one of TCL_INT, TCL_DOUBLE, TCL_WIDE_INT,
-or TCL_EITHER to indicate whether the corresponding argument must be an
+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.
-.VE 8.4
 .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:
 .CS
 typedef int Tcl_MathProc(
-	ClientData \fIclientData\fR,
-	Tcl_Interp *\fIinterp\fR,
-	Tcl_Value *\fIargs\fR,
-	Tcl_Value *\fIresultPtr\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:
-.VS 8.4
 .CS
 typedef struct Tcl_Value {
-	Tcl_ValueType \fItype\fR;
-	long \fIintValue\fR;
-	double \fIdoubleValue\fR;
-	Tcl_WideInt \fIwideValue\fR;
+        Tcl_ValueType \fItype\fR;
+        long \fIintValue\fR;
+        double \fIdoubleValue\fR;
+        Tcl_WideInt \fIwideValue\fR;
 } Tcl_Value;
 .CE
 .PP
 The \fItype\fR field indicates the type of the argument and is
-one of TCL_INT, TCL_DOUBLE or TCL_WIDE_INT.
-.VE 8.4
+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 TCL_EITHER. Tcl converts
+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,
-.VS 8.4
 \fIdoubleValue\fR or \fIwideValue\fR
-.VE 8.4
 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
-.VS 8.4
-TCL_INT, TCL_DOUBLE or TCL_WIDE_INT
-.VE 8.4
+\fBTCL_INT\fR, \fBTCL_DOUBLE\fR or \fBTCL_WIDE_INT\fR
 to indicate which value was set.
-Under normal circumstances \fIproc\fR should return TCL_OK.
+Under normal circumstances \fIproc\fR should return \fBTCL_OK\fR.
 If an error occurs while executing the function, \fIproc\fR should
-return TCL_ERROR and leave an error message in the interpreter's result.
+return \fBTCL_ERROR\fR and leave an error message in the interpreter's result.
 .PP
-.VS 8.4
 \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
@@ -140,20 +136,21 @@ result.
 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) are implemented directly at the
-bytecode level; 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.
+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 object containing a list of all
 the math functions defined in the interpreter whose name matches
-\fIpattern\fR.  In the case of an error, NULL is returned and an error
-message is left in the interpreter result, and otherwise the returned
-object will have a reference count of zero.
-.VE
+\fIpattern\fR.  The returned object 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
-
-.SH "SEE ALSO"
-expr(n), info(n), Tcl_Free(3), Tcl_NewListObj(3)

doc/CrtObjCmd.3

@@ -28,17 +28,13 @@ int
 int
 \fBTcl_SetCommandInfo\fR(\fIinterp, cmdName, infoPtr\fR)
 .sp
-.VS 8.4
 int
 \fBTcl_GetCommandInfoFromToken\fR(\fItoken, infoPtr\fR)
 .sp
 int
 \fBTcl_SetCommandInfoFromToken\fR(\fItoken, infoPtr\fR)
-.VE
 .sp
-.VS 8.4
-CONST char *
-.VE
+const char *
 \fBTcl_GetCommandName\fR(\fIinterp, token\fR)
 .sp
 void
@@ -47,12 +43,10 @@ void
 Tcl_Command
 \fBTcl_GetCommandFromObj\fR(\fIinterp, objPtr\fR)
 .SH ARGUMENTS
-.AS Tcl_ObjCmdProc *deleteProc in/out
+.AS Tcl_CmdDeleteProc *deleteProc in/out
 .AP Tcl_Interp *interp in
 Interpreter in which to create a new command or that contains a command.
-.VS 8.4
 .AP char *cmdName in
-.VE
 Name of command.
 .AP Tcl_ObjCmdProc *proc in
 Implementation of the new command: \fIproc\fR will be called whenever
@@ -96,11 +90,10 @@ and it returns NULL.
 \fBTcl_ObjCmdProc\fR:
 .CS
 typedef int Tcl_ObjCmdProc(
-	ClientData \fIclientData\fR,
-	Tcl_Interp *\fIinterp\fR,
-	int \fIobjc\fR,
-.VS
-	Tcl_Obj *CONST \fIobjv\fR[]);
+        ClientData \fIclientData\fR,
+        Tcl_Interp *\fIinterp\fR,
+        int \fIobjc\fR,
+        Tcl_Obj *const \fIobjv\fR[]);
 .CE
 When \fIproc\fR is invoked, the \fIclientData\fR and \fIinterp\fR parameters
 will be copies of the \fIclientData\fR and \fIinterp\fR arguments given to
@@ -117,7 +110,7 @@ Additionally, when \fIproc\fR is invoked, it must not modify the contents
 of the \fIobjv\fR array by assigning new pointer values to any element of the
 array (for example, \fIobjv\fR[\fB2\fR] = \fBNULL\fR) because this will
 cause memory to be lost and the runtime stack to be corrupted.  The
-\fBCONST\fR in the declaration of \fIobjv\fR will cause ANSI-compliant
+\fBconst\fR in the declaration of \fIobjv\fR will cause ANSI-compliant
 compilers to report any such attempted assignment as an error.  However,
 it is acceptable to modify the internal representation of any individual
 object argument.  For instance, the user may call
@@ -125,7 +118,6 @@ object argument.  For instance, the user may call
 representation of that object; that call may change the type of the object
 that \fIobjv\fR[\fB2\fR] points at, but will not change where
 \fIobjv\fR[\fB2\fR] points.
-.VE
 .PP
 \fIproc\fR must return an integer code that is either \fBTCL_OK\fR,
 \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR.
@@ -168,7 +160,8 @@ application an opportunity to release any structures associated
 with the command.  \fIDeleteProc\fR should have arguments and
 result that match the type \fBTcl_CmdDeleteProc\fR:
 .CS
-typedef void Tcl_CmdDeleteProc(ClientData \fIclientData\fR);
+typedef void Tcl_CmdDeleteProc(
+        ClientData \fIclientData\fR);
 .CE
 The \fIclientData\fR argument will be the same as the \fIclientData\fR
 argument passed to \fBTcl_CreateObjCommand\fR.
@@ -176,7 +169,7 @@ argument passed to \fBTcl_CreateObjCommand\fR.
 \fBTcl_DeleteCommand\fR deletes a command from a command interpreter.
 Once the call completes, attempts to invoke \fIcmdName\fR in
 \fIinterp\fR will result in errors.
-If \fIcmdName\fR isn't bound as a command in \fIinterp\fR then
+If \fIcmdName\fR is not bound as a command in \fIinterp\fR then
 \fBTcl_DeleteCommand\fR does nothing and returns -1;  otherwise
 it returns 0.
 There are no restrictions on \fIcmdName\fR:  it may refer to
@@ -206,14 +199,14 @@ pointed to by \fIinfoPtr\fR and returns 1.
 A \fBTcl_CmdInfo\fR structure has the following fields:
 .CS
 typedef struct Tcl_CmdInfo {
-    int isNativeObjectProc;
-    Tcl_ObjCmdProc *objProc;
-    ClientData objClientData;
-    Tcl_CmdProc *proc;
-    ClientData clientData;
-    Tcl_CmdDeleteProc *deleteProc;
-    ClientData deleteData;
-    Tcl_Namespace *namespacePtr;
+    int \fIisNativeObjectProc\fR;
+    Tcl_ObjCmdProc *\fIobjProc\fR;
+    ClientData \fIobjClientData\fR;
+    Tcl_CmdProc *\fIproc\fR;
+    ClientData \fIclientData\fR;
+    Tcl_CmdDeleteProc *\fIdeleteProc\fR;
+    ClientData \fIdeleteData\fR;
+    Tcl_Namespace *\fInamespacePtr\fR;
 } Tcl_CmdInfo;
 .CE
 The \fIisNativeObjectProc\fR field has the value 1
@@ -285,16 +278,16 @@ This name does not include any \fB::\fR namespace qualifiers.
 The command corresponding to \fItoken\fR must not have been deleted.
 The string returned by \fBTcl_GetCommandName\fR is in dynamic memory
 owned by Tcl and is only guaranteed to retain its value as long as the
-command isn't deleted or renamed;  callers should copy the string if
+command is not deleted or renamed;  callers should copy the string if
 they need to keep it for a long time.
 .PP
-\fBTcl_GetCommandFullName\fR produces the fully-qualified name
+\fBTcl_GetCommandFullName\fR produces the fully qualified name
 of a command from a command token.  
 The name, including all namespace prefixes,
-is appended to the object specified by \fIobjPtr\fP.
+is appended to the object specified by \fIobjPtr\fR.
 .PP
 \fBTcl_GetCommandFromObj\fR returns a token for the command
-specified by the name in a \fBTcl_Obj\fP.
+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.
 .SH "SEE ALSO"

doc/CrtSlave.3

@@ -8,7 +8,7 @@
 .TH Tcl_CreateSlave 3 7.6 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_IsSafe, Tcl_MakeSafe, Tcl_CreateSlave, Tcl_GetSlave, Tcl_GetMaster, Tcl_GetInterpPath, Tcl_CreateAlias, Tcl_CreateAliasObj, Tcl_GetAlias, Tcl_GetAliasObj, Tcl_ExposeCommand, Tcl_HideCommand \- manage multiple Tcl interpreters, aliases and hidden commands.
+Tcl_IsSafe, Tcl_MakeSafe, Tcl_CreateSlave, Tcl_GetSlave, Tcl_GetMaster, Tcl_GetInterpPath, Tcl_CreateAlias, Tcl_CreateAliasObj, Tcl_GetAlias, Tcl_GetAliasObj, Tcl_ExposeCommand, Tcl_HideCommand \- manage multiple Tcl interpreters, aliases and hidden commands
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -31,20 +31,21 @@ Tcl_Interp *
 int
 \fBTcl_GetInterpPath\fR(\fIaskingInterp, slaveInterp\fR)
 .sp
-.VS
 int
-\fBTcl_CreateAlias\fR(\fIslaveInterp, slaveCmd, targetInterp, targetCmd, argc, argv\fR)
+\fBTcl_CreateAlias\fR(\fIslaveInterp, slaveCmd, targetInterp, targetCmd,
+                argc, argv\fR)
 .sp
 int
-\fBTcl_CreateAliasObj\fR(\fIslaveInterp, slaveCmd, targetInterp, targetCmd, objc, objv\fR)
-.VE
+\fBTcl_CreateAliasObj\fR(\fIslaveInterp, slaveCmd, targetInterp, targetCmd,
+                   objc, objv\fR)
 .sp
 int
-\fBTcl_GetAlias\fR(\fIinterp, slaveCmd, targetInterpPtr, targetCmdPtr, argcPtr, argvPtr\fR)
+\fBTcl_GetAlias\fR(\fIinterp, slaveCmd, targetInterpPtr, targetCmdPtr,
+             argcPtr, argvPtr\fR)
 .sp
-.VS
 int
-\fBTcl_GetAliasObj\fR(\fIinterp, slaveCmd, targetInterpPtr, targetCmdPtr, objcPtr, objvPtr\fR)
+\fBTcl_GetAliasObj\fR(\fIinterp, slaveCmd, targetInterpPtr, targetCmdPtr,
+                objcPtr, objvPtr\fR)
 .sp
 int
 \fBTcl_ExposeCommand\fR(\fIinterp, hiddenCmdName, cmdName\fR)
@@ -52,44 +53,46 @@ int
 int
 \fBTcl_HideCommand\fR(\fIinterp, cmdName, hiddenCmdName\fR)
 .SH ARGUMENTS
-.AS Tcl_InterpDeleteProc **hiddenCmdName
+.AS "const char *const" **targetInterpPtr out
 .AP Tcl_Interp *interp in
 Interpreter in which to execute the specified command.
-.AP "CONST char" *slaveName in
+.AP "const char" *slaveName in
 Name of slave interpreter to create or manipulate.
 .AP int isSafe in
-If non-zero, a ``safe'' slave that is suitable for running untrusted code
+If non-zero, a
+.QW safe
+slave that is suitable for running untrusted code
 is created, otherwise a trusted slave is created.
 .AP Tcl_Interp *slaveInterp in
 Interpreter to use for creating the source command for an alias (see
 below).
-.AP "CONST char" *slaveCmd in
+.AP "const char" *slaveCmd in
 Name of source command for alias.
 .AP Tcl_Interp *targetInterp in
 Interpreter that contains the target command for an alias.
-.AP "CONST char" *targetCmd in
+.AP "const char" *targetCmd in
 Name of target command for alias in \fItargetInterp\fR.
 .AP int argc in
 Count of additional arguments to pass to the alias command.
-.AP "CONST char * CONST" *argv in
+.AP "const char *const" *argv in
 Vector of strings, the additional arguments to pass to the alias command.
 This storage is owned by the caller.
 .AP int objc in
 Count of additional object arguments to pass to the alias object command.
-.AP Tcl_Object **objv in
+.AP Tcl_Obj **objv in
 Vector of Tcl_Obj structures, the additional object arguments to pass to
 the alias object command.
 This storage is owned by the caller.
 .AP Tcl_Interp **targetInterpPtr in
 Pointer to location to store the address of the interpreter where a target
 command is defined for an alias.
-.AP "CONST char" **targetCmdPtr out
+.AP "const char" **targetCmdPtr out
 Pointer to location to store the address of the name of the target command
 for an alias.
 .AP int *argcPtr out
 Pointer to location to store count of additional arguments to be passed to
 the alias. The location is in storage owned by the caller.
-.AP "CONST char" ***argvPtr out
+.AP "const char" ***argvPtr out
 Pointer to location to store a vector of strings, the additional arguments
 to pass to an alias. The location is in storage owned by the caller, the
 vector of strings is owned by the called function.
@@ -101,17 +104,11 @@ Pointer to location to store a vector of Tcl_Obj structures, the additional
 arguments to pass to an object alias command. The location is in storage
 owned by the caller, the vector of Tcl_Obj structures is owned by the
 called function.
-.VS
-.VS 8.4
-.AP "CONST char" *cmdName in
-.VE
+.AP "const char" *cmdName in
 Name of an exposed command to hide or create.
-.VS 8.4
-.AP "CONST char" *hiddenCmdName in
-.VE
+.AP "const char" *hiddenCmdName in
 Name under which a hidden command is stored and with which it can be
 exposed or invoked.
-.VE
 .BE
 
 .SH DESCRIPTION
@@ -129,16 +126,21 @@ It also creates a slave command named \fIslaveName\fR in \fIinterp\fR which
 allows \fIinterp\fR to manipulate the new slave. 
 If \fIisSafe\fR is zero, the command creates a trusted slave in which Tcl
 code has access to all the Tcl commands.
-If it is \fB1\fR, the command creates a ``safe'' slave in which Tcl code
-has access only to set of Tcl commands defined as ``Safe Tcl''; see the
-manual entry for the Tcl \fBinterp\fR command for details.
+If it is \fB1\fR, the command creates a
+.QW safe
+slave in which Tcl code has access only to set of Tcl commands defined as
+.QW "Safe Tcl" ;
+see the manual entry for the Tcl \fBinterp\fR command for details.
 If the creation of the new slave interpreter failed, \fBNULL\fR is returned.
 .PP
-\fBTcl_IsSafe\fR returns \fB1\fR if \fIinterp\fR is ``safe'' (was created
-with the \fBTCL_SAFE_INTERPRETER\fR flag specified),
+\fBTcl_IsSafe\fR returns \fB1\fR if \fIinterp\fR is
+.QW safe
+(was created with the \fBTCL_SAFE_INTERPRETER\fR flag specified),
 \fB0\fR otherwise.
 .PP
-\fBTcl_MakeSafe\fR marks \fIinterp\fR as ``safe'', so that future
+\fBTcl_MakeSafe\fR marks \fIinterp\fR as
+.QW safe ,
+so that future
 calls to \fBTcl_IsSafe\fR will return 1.  It also removes all known
 potentially-unsafe core functionality (both commands and variables)
 from \fIinterp\fR.  However, it cannot know what parts of an extension
@@ -163,7 +165,6 @@ of the relative path succeeds, \fBTCL_OK\fR is returned, else
 \fBTCL_ERROR\fR is returned and the \fIresult\fR field in
 \fIaskingInterp\fR contains the error message.
 .PP
-.VS
 \fBTcl_CreateAlias\fR creates an object command named \fIslaveCmd\fR in
 \fIslaveInterp\fR that when invoked, will cause the command \fItargetCmd\fR
 to be invoked in \fItargetInterp\fR. The arguments specified by the strings
@@ -180,7 +181,6 @@ restrictions on how they are related.
 \fBTcl_CreateAliasObj\fR is similar to \fBTcl_CreateAlias\fR except 
 that it takes a vector of objects to pass as additional arguments instead
 of a vector of strings.
-.VE
 .PP
 \fBTcl_GetAlias\fR returns information about an alias \fIaliasName\fR
 in \fIinterp\fR. Any of the result fields can be \fBNULL\fR, in
@@ -188,7 +188,6 @@ which case the corresponding datum is not returned. If a result field is
 non\-\fBNULL\fR, the address indicated is set to the corresponding datum.
 For example, if \fItargetNamePtr\fR is non\-\fBNULL\fR it is set to a
 pointer to the string containing the name of the target command.
-.VS
 .PP
 \fBTcl_GetAliasObj\fR is similar to \fBTcl_GetAlias\fR except that it
 returns a pointer to a vector of Tcl_Obj structures instead of a vector of

doc/CrtTimerHdlr.3

@@ -9,8 +9,7 @@
 .TH Tcl_CreateTimerHandler 3 7.5 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_CreateTimerHandler, Tcl_DeleteTimerHandler \- call a procedure at a
-given time
+Tcl_CreateTimerHandler, Tcl_DeleteTimerHandler \- call a procedure at a given time
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -28,7 +27,7 @@ Procedure to invoke after \fImilliseconds\fR have elapsed.
 .AP ClientData clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .AP Tcl_TimerToken token in
-Token for previously-created timer handler (the return value
+Token for previously created timer handler (the return value
 from some previous call to \fBTcl_CreateTimerHandler\fR).
 .BE
 
@@ -43,7 +42,7 @@ dispatch events through \fBTcl_DoOneEvent\fR or through Tcl commands
 such as \fBvwait\fR.
 The call to \fIproc\fR may not be made at the exact time given by
 \fImilliseconds\fR:  it will be made at the next opportunity
-after that time.  For example, if \fBTcl_DoOneEvent\fR isn't
+after that time.  For example, if \fBTcl_DoOneEvent\fR is not
 called until long after the time has elapsed, or if there
 are other pending events to process before the call to
 \fIproc\fR, then the call to \fIproc\fR will be delayed.
@@ -61,7 +60,7 @@ structure containing application-specific information about
 what to do in \fIproc\fR.
 .PP
 \fBTcl_DeleteTimerHandler\fR may be called to delete a
-previously-created timer handler.  It deletes the handler
+previously created timer handler.  It deletes the handler
 indicated by \fItoken\fR so that no call to \fIproc\fR
 will be made;  if that handler no longer exists
 (e.g. because the time period has already elapsed and \fIproc\fR

doc/CrtTrace.3

@@ -1,7 +1,7 @@
 '\"
 '\" Copyright (c) 1989-1993 The Regents of the University of California.
 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\" Copyright (c) 2002 by Kevin B. Kenny.  All rights reserved.
+'\" Copyright (c) 2002 by Kevin B. Kenny <kennykb@acm.org>.  All rights reserved.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
@@ -23,7 +23,7 @@ Tcl_Trace
 .sp
 \fBTcl_DeleteTrace\fR(\fIinterp, trace\fR)
 .SH ARGUMENTS
-.AS Tcl_CmdObjTraceDeleteProc (clientData)()
+.AS Tcl_CmdObjTraceDeleteProc *deleteProc
 .AP Tcl_Interp *interp in
 Interpreter containing command to be traced or untraced.
 .AP int level in
@@ -36,14 +36,14 @@ A value of 0 means that commands at any level are traced.
 .AP int flags in
 Flags governing the trace execution.  See below for details.
 .AP Tcl_CmdObjTraceProc *objProc in
-Procedure to call for each command that's executed.  See below for
+Procedure to call for each command that is executed.  See below for
 details of the calling sequence.
 .AP Tcl_CmdTraceProc *proc in
-Procedure to call for each command that's executed.  See below for
+Procedure to call for each command that is executed.  See below for
 details on the calling sequence.
 .AP ClientData clientData in
 Arbitrary one-word value to pass to \fIobjProc\fR or \fIproc\fR.
-.AP Tcl_CmdObjTraceDeleteProc *deleteProc
+.AP Tcl_CmdObjTraceDeleteProc *deleteProc in
 Procedure to call when the trace is deleted.  See below for details of
 the calling sequence.  A NULL pointer is permissible and results in no
 callback when the trace is deleted.
@@ -65,13 +65,13 @@ interpreter.
 \fBTcl_CmdObjTraceProc\fR:
 .CS
 typedef int \fBTcl_CmdObjTraceProc\fR( 
-    \fBClientData\fR \fIclientData\fR,
-    \fBTcl_Interp\fR* \fIinterp\fR,
-    int \fIlevel\fR,
-    CONST char* \fIcommand\fR,
-    \fBTcl_Command\fR \fIcommandToken\fR,
-    int \fIobjc\fR,
-    \fBTcl_Obj\fR *CONST \fIobjv\fR[] );
+        \fBClientData\fR \fIclientData\fR,
+        \fBTcl_Interp\fR* \fIinterp\fR,
+        int \fIlevel\fR,
+        const char *\fIcommand\fR,
+        \fBTcl_Command\fR \fIcommandToken\fR,
+        int \fIobjc\fR,
+        \fBTcl_Obj\fR *const \fIobjv\fR[] );
 .CE
 The \fIclientData\fR and \fIinterp\fR parameters are copies of the
 corresponding arguments given to \fBTcl_CreateTrace\fR.
@@ -141,8 +141,7 @@ When \fBTcl_DeleteTrace\fR is called, the interpreter invokes the
 \fBTcl_CmdObjTraceDeleteProc\fR:
 .CS
 typedef void \fBTcl_CmdObjTraceDeleteProc\fR( 
-    \fBClientData\fR \fIclientData\fR
-);
+        \fBClientData\fR \fIclientData\fR);
 .CE
 The \fIclientData\fR parameter will be the same as the
 \fIclientData\fR parameter that was originally passed to
@@ -156,14 +155,14 @@ that its \fIproc\fR parameter should have arguments and result that
 match the type \fBTcl_CmdTraceProc\fR:
 .CS
 typedef void Tcl_CmdTraceProc(
-	ClientData \fIclientData\fR,
-	Tcl_Interp *\fIinterp\fR,
-	int \fIlevel\fR,
-	char *\fIcommand\fR,
-	Tcl_CmdProc *\fIcmdProc\fR,
-	ClientData \fIcmdClientData\fR,
-	int \fIargc\fR,
-	CONST char *\fIargv\fR[]);
+        ClientData \fIclientData\fR,
+        Tcl_Interp *\fIinterp\fR,
+        int \fIlevel\fR,
+        char *\fIcommand\fR,
+        Tcl_CmdProc *\fIcmdProc\fR,
+        ClientData \fIcmdClientData\fR,
+        int \fIargc\fR,
+        const char *\fIargv\fR[]);
 .CE
 The parameters to the \fIproc\fR callback are similar to those of the
 \fIobjProc\fR callback above. The \fIcommandToken\fR is

doc/DString.3

@@ -17,10 +17,10 @@ Tcl_DStringInit, Tcl_DStringAppend, Tcl_DStringAppendElement, Tcl_DStringStartSu
 \fBTcl_DStringInit\fR(\fIdsPtr\fR)
 .sp
 char *
-\fBTcl_DStringAppend\fR(\fIdsPtr, string, length\fR)
+\fBTcl_DStringAppend\fR(\fIdsPtr, bytes, length\fR)
 .sp
 char *
-\fBTcl_DStringAppendElement\fR(\fIdsPtr, string\fR)
+\fBTcl_DStringAppendElement\fR(\fIdsPtr, element\fR)
 .sp
 \fBTcl_DStringStartSublist\fR(\fIdsPtr\fR)
 .sp
@@ -42,13 +42,15 @@ char *
 .sp
 \fBTcl_DStringGetResult\fR(\fIinterp, dsPtr\fR)
 .SH ARGUMENTS
-.AS Tcl_DString newLength
+.AS Tcl_DString newLength in/out
 .AP Tcl_DString *dsPtr in/out
 Pointer to structure that is used to manage a dynamic string.
-.AP "CONST char" *string in
-Pointer to characters to add to dynamic string.
+.AP "const char" *bytes in
+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 characters from string to add to dynamic string.  If -1,
+Number of bytes from \fIbytes\fR to add to dynamic string.  If -1,
 add all characters up to null terminating character.
 .AP int newLength in
 New length for dynamic string, not including null terminating
@@ -75,7 +77,7 @@ string.
 .PP
 \fBTcl_DStringAppend\fR adds new information to a dynamic string,
 allocating more memory for the string if needed.
-If \fIlength\fR is less than zero then everything in \fIstring\fR
+If \fIlength\fR is less than zero then everything in \fIbytes\fR
 is appended to the dynamic string;  otherwise \fIlength\fR
 specifies the number of bytes to append.
 \fBTcl_DStringAppend\fR returns a pointer to the characters of
@@ -83,14 +85,16 @@ the new string.  The string can also be retrieved from the
 \fIstring\fR field of the Tcl_DString structure.
 .PP
 \fBTcl_DStringAppendElement\fR is similar to \fBTcl_DStringAppend\fR
-except that it doesn't take a \fIlength\fR argument (it appends
-all of \fIstring\fR) and it converts the string to a proper list element
+except that it does not take a \fIlength\fR argument (it appends
+all of \fIelement\fR) and it converts the string to a proper list element
 before appending.
 \fBTcl_DStringAppendElement\fR adds a separator space before the
 new list element unless the new list element is the first in a
 list or sub-list (i.e. either the current string is empty, or it
-contains the single character ``{'', or the last two characters of
-the current string are `` {'').
+contains the single character
+.QW { ,
+or the last two characters of the current string are
+.QW " {" ).
 \fBTcl_DStringAppendElement\fR returns a pointer to the
 characters of the new string.
 .PP
@@ -128,7 +132,7 @@ will still need to be called.
 This procedure is now deprecated.  \fBTcl_DStringSetLength\fR  should
 be used instead.
 .PP
-\fBTcl_DStringFree\fR should be called when you're finished using
+\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.
 .PP

doc/DetachPids.3

@@ -19,18 +19,18 @@ Tcl_DetachPids, Tcl_ReapDetachedProcs, Tcl_WaitPid \- manage child processes in
 \fBTcl_ReapDetachedProcs\fR()
 .sp
 Tcl_Pid
-\fBTcl_WaitPid\fR(\fIpid, statPtr, options\fR)
+\fBTcl_WaitPid\fR(\fIpid, statusPtr, options\fR)
 .SH ARGUMENTS
-.AS int *statusPtr
+.AS Tcl_Pid *statusPtr out
 .AP int numPids in
 Number of process ids contained in the array pointed to by \fIpidPtr\fR.
 .AP int *pidPtr in
 Address of array containing \fInumPids\fR process ids.
 .AP Tcl_Pid pid in
 The id of the process (pipe) to wait for.
-.AP int* statPtr out
+.AP int *statusPtr out
 The result of waiting on a process (pipe). Either 0 or ECHILD.
-.AP int options
+.AP int options in
 The options controlling the wait. WNOHANG specifies not to wait when
 checking the process.
 .BE
@@ -49,16 +49,16 @@ overflow, even if all the children have exited.
 \fBTcl_DetachPids\fR may be called to ask Tcl to take responsibility
 for one or more processes whose process ids are contained in the
 \fIpidPtr\fR array passed as argument.  The caller presumably
-has started these processes running in background and doesn't
+has started these processes running in background and does not
 want to have to deal with them again.
 .PP
 \fBTcl_ReapDetachedProcs\fR invokes the \fBwaitpid\fR kernel call
 on each of the background processes so that its state can be cleaned
-up if it has exited.  If the process hasn't exited yet,
-\fBTcl_ReapDetachedProcs\fR doesn't wait for it to exit;  it will check again
+up if it has exited.  If the process has not exited yet,
+\fBTcl_ReapDetachedProcs\fR does not wait for it to exit;  it will check again
 the next time it is invoked.
 Tcl automatically calls \fBTcl_ReapDetachedProcs\fR each time the
-\fBexec\fR command is executed, so in most cases it isn't necessary
+\fBexec\fR command is executed, so in most cases it is not necessary
 for any code outside of Tcl to invoke \fBTcl_ReapDetachedProcs\fR.
 However, if you call \fBTcl_DetachPids\fR in situations where the
 \fBexec\fR command may never get executed, you may wish to call

doc/DictObj.3

@@ -0,0 +1,234 @@
+'\"
+'\" Copyright (c) 2003 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.so man.macros
+.TH Tcl_DictObj 3 8.5 Tcl "Tcl Library Procedures"
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+Tcl_NewDictObj, Tcl_DictObjPut, Tcl_DictObjGet, Tcl_DictObjRemove, Tcl_DictObjSize, Tcl_DictObjFirst, Tcl_DictObjNext, Tcl_DictObjDone, Tcl_DictObjPutKeyList, Tcl_DictObjRemoveKeyList \- manipulate Tcl objects as dictionaries
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+Tcl_Obj *
+\fBTcl_NewDictObj\fR()
+.sp
+int
+\fBTcl_DictObjGet\fR(\fIinterp, dictPtr, keyPtr, valuePtrPtr\fR)
+.sp
+int
+\fBTcl_DictObjPut\fR(\fIinterp, dictPtr, keyPtr, valuePtr\fR)
+.sp
+int
+\fBTcl_DictObjRemove\fR(\fIinterp, dictPtr, keyPtr\fR)
+.sp
+int
+\fBTcl_DictObjSize\fR(\fIinterp, dictPtr, sizePtr\fR)
+.sp
+int
+\fBTcl_DictObjFirst\fR(\fIinterp, dictPtr, searchPtr,
+                 keyPtrPtr, valuePtrPtr, donePtr\fR)
+.sp
+void
+\fBTcl_DictObjNext\fR(\fIsearchPtr, keyPtrPtr, valuePtrPtr, donePtr\fR)
+.sp
+void
+\fBTcl_DictObjDone\fR(\fIsearchPtr\fR)
+.sp
+int
+\fBTcl_DictObjPutKeyList\fR(\fIinterp, dictPtr, keyc, keyv, valuePtr\fR)
+.sp
+int
+\fBTcl_DictObjRemoveKeyList\fR(\fIinterp, dictPtr, keyc, keyv\fR)
+.SH ARGUMENTS
+.AS Tcl_DictSearch "**valuePtrPtr" in/out
+.AP Tcl_Interp *interp in
+If an error occurs while converting an object to be a dictionary object,
+an error message is left in the interpreter's result object
+unless \fIinterp\fR is NULL.
+.AP Tcl_Obj *dictPtr in/out
+Points to the dictionary object to be manipulated.
+If \fIdictPtr\fR does not already point to a dictionary object,
+an attempt will be made to convert it to one.
+.AP Tcl_Obj *keyPtr in
+Points to the key for the key/value pair being manipulated within the
+dictionary object.
+.AP Tcl_Obj **keyPtrPtr out
+Points to a variable that will have the key from a key/value pair
+placed within it.  May be NULL to indicate that the caller is not
+interested in the key.
+.AP Tcl_Obj *valuePtr in
+Points to the value for the key/value pair being manipulate within the
+dictionary object (or sub-object, in the case of
+\fBTcl_DictObjPutKeyList\fR.)
+.AP Tcl_Obj **valuePtrPtr out
+Points to a variable that will have the value from a key/value pair
+placed within it.  For \fBTcl_DictObjFirst\fR and
+\fBTcl_DictObjNext\fR, this may be NULL to indicate that the caller is
+not interested in the value.
+.AP int *sizePtr out
+Points to a variable that will have the number of key/value pairs
+contained within the dictionary placed within it.
+.AP Tcl_DictSearch *searchPtr in/out
+Pointer to record to use to keep track of progress in enumerating all
+key/value pairs in a dictionary.  The contents of the record will be
+initialized by the call to \fBTcl_DictObjFirst\fR.  If the enumerating
+is to be terminated before all values in the dictionary have been
+returned, the search record \fImust\fR be passed to
+\fBTcl_DictObjDone\fR to enable the internal locks to be released.
+.AP int *donePtr out
+Points to a variable that will have a non-zero value written into it
+when the enumeration of the key/value pairs in a dictionary has
+completed, and a zero otherwise.
+.AP int keyc in
+Indicates the number of keys that will be supplied in the \fIkeyv\fR
+array.
+.AP "Tcl_Obj *const" *keyv in
+Array of \fIkeyc\fR pointers to objects that
+\fBTcl_DictObjPutKeyList\fR and \fBTcl_DictObjRemoveKeyList\fR will
+use to locate the key/value pair to manipulate within the
+sub-dictionaries of the main dictionary object passed to them.
+.BE
+
+.SH DESCRIPTION
+.PP
+Tcl dictionary objects have an internal representation that supports
+efficient mapping from keys to values and which guarantees that the
+particular ordering of keys within the dictionary remains the same
+modulo any keys being deleted (which removes them from the order) or
+added (which adds them to the end of the order). If reinterpreted as a
+list, the values at the even-valued indices in the list will be the
+keys of the dictionary, and each will be followed (in the odd-valued
+index) by the value associated with that key.
+.PP
+The procedures described in this man page are used to
+create, modify, index, and iterate over dictionary objects from C code.
+.PP
+\fBTcl_NewDictObj\fR creates a new, empty dictionary object.  The
+string representation of the object will be invalid, and the reference
+count of the object will be zero.
+.PP
+\fBTcl_DictObjGet\fR looks up the given key within the given
+dictionary and writes a pointer to the value associated with that key
+into the variable pointed to by \fIvaluePtrPtr\fR, or a NULL if the
+key has no mapping within the dictionary.  The result of this
+procedure is \fBTCL_OK\fR, or \fBTCL_ERROR\fR if the \fIdictPtr\fR cannot be
+converted to a dictionary.
+.PP
+\fBTcl_DictObjPut\fR updates the given dictionary so that the given
+key maps to the given value; any key may exist at most once in any
+particular dictionary.  The dictionary must not be shared, but the key
+and value may be.  This procedure may increase the reference count of
+both key and value if it proves necessary to store them.  Neither key
+nor value should be NULL.  The result of this procedure is \fBTCL_OK\fR, or
+\fBTCL_ERROR\fR if the \fIdictPtr\fR cannot be converted to a dictionary.
+.PP
+\fBTcl_DictObjRemove\fR updates the given dictionary so that the given
+key has no mapping to any value.  The dictionary must not be shared,
+but the key may be.  The key actually stored in the dictionary will
+have its reference count decremented if it was present.  It is not an
+error if the key did not previously exist.  The result of this
+procedure is \fBTCL_OK\fR, or \fBTCL_ERROR\fR if the \fIdictPtr\fR cannot be
+converted to a dictionary.
+.PP
+\fBTcl_DictObjSize\fR updates the given variable with the number of
+key/value pairs currently in the given dictionary. The result of this
+procedure is \fBTCL_OK\fR, or \fBTCL_ERROR\fR if the \fIdictPtr\fR cannot be
+converted to a dictionary.
+.PP
+\fBTcl_DictObjFirst\fR commences an iteration across all the key/value
+pairs in the given dictionary, placing the key and value in the
+variables pointed to by the \fIkeyPtrPtr\fR and \fIvaluePtrPtr\fR
+arguments (which may be NULL to indicate that the caller is
+uninterested in they key or variable respectively.)  The next
+key/value pair in the dictionary may be retrieved with
+\fBTcl_DictObjNext\fR.  Concurrent updates of the dictionary's
+internal representation will not modify the iteration processing
+unless the dictionary is unshared, when this will trigger premature
+termination of the iteration instead (which Tcl scripts cannot trigger
+via the \fBdict\fR command.)  The \fIsearchPtr\fR argument points to a
+piece of context that is used to identify which particular iteration
+is being performed, and is initialized by the call to
+\fBTcl_DictObjFirst\fR.  The \fIdonePtr\fR argument points to a
+variable that is updated to be zero of there are further key/value
+pairs to be iterated over, or non-zero if the iteration is complete.
+The order of iteration is implementation-defined.  If the
+\fIdictPtr\fR argument cannot be converted to a dictionary,
+\fBTcl_DictObjFirst\fR returns \fBTCL_ERROR\fR and the iteration is not
+commenced, and otherwise it returns \fBTCL_OK\fR.
+.PP
+When \fBTcl_DictObjFirst\fR is called upon a dictionary, a lock is placed on
+the dictionary to enable that dictionary to be iterated over safely without
+regard for whether the dictionary is modified during the iteration. Because of
+this, once the iteration over a dictionary's keys has finished (whether
+because all values have been iterated over as indicated by the variable
+indicated by the \fIdonePtr\fR argument being set to one, or because no
+further values are required) the \fBTcl_DictObjDone\fR function must be called
+with the same \fIsearchPtr\fR as was passed to \fBTcl_DictObjFirst\fR so that
+the internal locks can be released. Once a particular \fIsearchPtr\fR is
+passed to \fBTcl_DictObjDone\fR, passing it to \fBTcl_DictObjNext\fR (without
+first initializing it with \fBTcl_DictObjFirst\fR) will result in no values
+being produced and the variable pointed to by \fIdonePtr\fR being set to one.
+It is safe to call \fBTcl_DictObjDone\fR multiple times on the same
+\fIsearchPtr\fR for each call to \fBTcl_DictObjFirst\fR.
+.PP
+The procedures \fBTcl_DictObjPutKeyList\fR and
+\fBTcl_DictObjRemoveKeyList\fR are the close analogues of
+\fBTcl_DictObjPut\fR and \fBTcl_DictObjRemove\fR respectively, except
+that instead of working with a single dictionary, they are designed to
+operate on a nested tree of dictionaries, with inner dictionaries
+stored as values inside outer dictionaries.  The \fIkeyc\fR and
+\fIkeyv\fR arguments specify a list of keys (with outermost keys
+first) that acts as a path to the key/value pair to be affected.  Note
+that there is no corresponding operation for reading a value for a
+path as this is easy to construct from repeated use of
+\fBTcl_DictObjGet\fR. With \fBTcl_DictObjPutKeyList\fR, nested
+dictionaries are created for non-terminal keys where they do not
+already exist. With \fBTcl_DictObjRemoveKeyList\fR, all non-terminal
+keys must exist and have dictionaries as their values.
+.SH EXAMPLE
+Using the dictionary iteration interface to search determine if there
+is a key that maps to itself:
+.PP
+.CS
+Tcl_DictSearch search;
+Tcl_Obj *key, *value;
+int done;
+
+/*
+ * Assume interp and objPtr are parameters.  This is the
+ * idiomatic way to start an iteration over the dictionary; it
+ * sets a lock on the internal representation that ensures that
+ * there are no concurrent modification issues when normal
+ * reference count management is also used.  The lock is
+ * released automatically when the loop is finished, but must
+ * be released manually when an exceptional exit from the loop
+ * is performed. However it is safe to try to release the lock
+ * even if we've finished iterating over the loop.
+ */
+if (\fBTcl_DictObjFirst\fR(interp, objPtr, &search,
+        &key, &value, &done) != TCL_OK) {
+    return TCL_ERROR;
+}
+for (; !done ; \fBTcl_DictObjNext\fR(&search, &key, &value, &done)) {
+    /*
+     * Note that strcmp() is not a good way of comparing
+     * objects and is just used here for demonstration
+     * purposes.
+     */
+    if (!strcmp(Tcl_GetString(key), Tcl_GetString(value))) {
+        break;
+    }
+}
+\fBTcl_DictObjDone\fR(&search);
+Tcl_SetObjResult(interp, Tcl_NewBooleanObj(!done));
+return TCL_OK;
+.CE
+.SH "SEE ALSO"
+Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_InitObjHashTable
+.SH KEYWORDS
+dict, dict object, dictionary, dictionary object, hash table, iteration, object

doc/DoOneEvent.3

@@ -21,9 +21,9 @@ int
 .AP int flags in
 This parameter is normally zero.  It may be an OR-ed combination
 of any of the following flag bits:  
-TCL_WINDOW_EVENTS,
-TCL_FILE_EVENTS, TCL_TIMER_EVENTS, TCL_IDLE_EVENTS, TCL_ALL_EVENTS, or
-TCL_DONT_WAIT.
+\fBTCL_WINDOW_EVENTS\fR, \fBTCL_FILE_EVENTS\fR,
+\fBTCL_TIMER_EVENTS\fR, \fBTCL_IDLE_EVENTS\fR, \fBTCL_ALL_EVENTS\fR,
+or \fBTCL_DONT_WAIT\fR.
 .BE
 
 .SH DESCRIPTION
@@ -71,7 +71,7 @@ Process all kinds of events:  equivalent to OR-ing together all of the
 above flags or specifying none of them.
 .TP 27
 \fBTCL_DONT_WAIT\fR \-
-Don't sleep:  process only events that are ready at the time of the
+Do not sleep:  process only events that are ready at the time of the
 call.
 .LP
 If any of the flags \fBTCL_WINDOW_EVENTS\fR, \fBTCL_FILE_EVENTS\fR,

doc/DoWhenIdle.3

@@ -30,7 +30,7 @@ Arbitrary one-word value to pass to \fIproc\fR.
 \fBTcl_DoWhenIdle\fR arranges for \fIproc\fR to be invoked
 when the application becomes idle.  The application is
 considered to be idle when \fBTcl_DoOneEvent\fR has been
-called, couldn't find any events to handle, and is about
+called, could not find any events to handle, and is about
 to go to sleep waiting for an event to occur.  At this
 point all pending \fBTcl_DoWhenIdle\fR handlers are
 invoked.  For each call to \fBTcl_DoWhenIdle\fR there will
@@ -59,7 +59,7 @@ all of the handlers are removed.  If no existing handlers match
 \fIproc\fR and \fIclientData\fR then nothing happens.
 .PP
 \fBTcl_DoWhenIdle\fR is most useful in situations where
-(a) a piece of work will have to be done but (b) it's
+(a) a piece of work will have to be done but (b) it is
 possible that something will happen in the near future
 that will change what has to be done or require something
 different to be done.  \fBTcl_DoWhenIdle\fR allows the

doc/DoubleObj.3

@@ -23,55 +23,42 @@ int
 .SH ARGUMENTS
 .AS Tcl_Interp doubleValue in/out
 .AP double doubleValue in
-A double-precision floating point value used to initialize or set a double object.
+A double-precision floating-point value used to initialize or set a Tcl object.
 .AP Tcl_Obj *objPtr in/out
-For \fBTcl_SetDoubleObj\fR, this points to the object to be converted
-to double type.
+For \fBTcl_SetDoubleObj\fR, this points to the object in which to store a
+double value.
 For \fBTcl_GetDoubleFromObj\fR, this refers to the object
-from which to get a double value; 
-if \fIobjPtr\fR does not already point to a double object,
-an attempt will be made to convert it to one.
+from which to retrieve a double value. 
 .AP Tcl_Interp *interp in/out
-If an error occurs during conversion,
-an error message is left in the interpreter's result object
-unless \fIinterp\fR is NULL.
+When non-NULL, an error message is left here when double value retrieval fails.
 .AP double *doublePtr out
-Points to place to store the double value
-obtained from \fIobjPtr\fR.
+Points to place to store the double value obtained from \fIobjPtr\fR.
 .BE
 
 .SH DESCRIPTION
 .PP
-These procedures are used to create, modify, and read
-double Tcl objects from C code.
-\fBTcl_NewDoubleObj\fR and \fBTcl_SetDoubleObj\fR
-will create a new object of double type
-or modify an existing object to have double type. 
-Both of these procedures set the object to have the
-double-precision floating point value given by \fIdoubleValue\fR;
-\fBTcl_NewDoubleObj\fR returns a pointer to a newly created object
-with reference count zero.
-Both procedures set the object's type to be double
-and assign the double value to the object's internal representation
-\fIdoubleValue\fR member.
-\fBTcl_SetDoubleObj\fR invalidates any old string representation
-and, if the object is not already a double object,
-frees any old internal representation.
+These procedures are used to create, modify, and read Tcl objects that
+hold double-precision floating-point values.
 .PP
-\fBTcl_GetDoubleFromObj\fR attempts to return a double value
-from the Tcl object \fIobjPtr\fR.
-If the object is not already a double object,
-it will attempt to convert it to one.
-If an error occurs during conversion, it returns \fBTCL_ERROR\fR
-and leaves an error message in the interpreter's result object
-unless \fIinterp\fR is NULL.
-Otherwise, it returns \fBTCL_OK\fR and stores the double value
-in the address given by \fIdoublePtr\fR.
-If the object is not already a double object,
-the conversion will free any old internal representation.
-
+\fBTcl_NewDoubleObj\fR creates and returns a new Tcl object initialized to
+the double value \fIdoubleValue\fR.  The returned Tcl object is unshared.
+.PP
+\fBTcl_SetDoubleObj\fR sets the value of an existing Tcl object pointed to
+by \fIobjPtr\fR to the double value \fIdoubleValue\fR.  The \fIobjPtr\fR
+argument must point to an unshared Tcl object.  Any attempt to set the value
+of a shared Tcl object violates Tcl's copy-on-write policy.  Any existing
+string representation or internal representation in the unshared Tcl object
+will be freed as a consequence of setting the new value.
+.PP
+\fBTcl_GetDoubleFromObj\fR attempts to retrieve a double value from the
+Tcl object \fIobjPtr\fR.  If the attempt succeeds, then \fBTCL_OK\fR is
+returned, and the double value is written to the storage pointed to by
+\fIdoublePtr\fR.  If the attempt fails, then \fBTCL_ERROR\fR is returned,
+and if \fIinterp\fR is non-NULL, an error message is left in \fIinterp\fR.
+The \fBTcl_ObjType\fR of \fIobjPtr\fR may be changed to make subsequent
+calls to \fBTcl_GetDoubleFromObj\fR more efficient. 
+'\" TODO: add discussion of treatment of NaN value
 .SH "SEE ALSO"
 Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
-
 .SH KEYWORDS
 double, double object, double type, internal representation, object, object type, string representation

doc/DumpActiveMemory.3

@@ -7,7 +7,7 @@
 .TH "Tcl_DumpActiveMemory" 3 8.1 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_DumpActiveMemory, Tcl_InitMemory, Tcl_ValidateAllMemory \- Validated memory allocation interface.
+Tcl_DumpActiveMemory, Tcl_InitMemory, Tcl_ValidateAllMemory \- Validated memory allocation interface
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -22,9 +22,10 @@ void
 \fBTcl_ValidateAllMemory\fR(\fIfileName, line\fR)
 
 .SH ARGUMENTS
+.AS Tcl_Interp *fileName
 .AP Tcl_Interp *interp in
 Tcl interpreter in which to add commands.
-.AP "CONST char" *fileName in
+.AP "const char" *fileName in
 For \fBTcl_DumpActiveMemory\fR, name of the file to which memory
 information will be written.  For \fBTcl_ValidateAllMemory\fR, name of
 the file from which the call is being made (normally \fB__FILE__\fR).

doc/Encoding.3

@@ -8,7 +8,7 @@
 .TH Tcl_GetEncoding 3 "8.1" Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_GetEncoding, Tcl_FreeEncoding, Tcl_ExternalToUtfDString, Tcl_ExternalToUtf, Tcl_UtfToExternalDString, Tcl_UtfToExternal, Tcl_WinTCharToUtf, Tcl_WinUtfToTChar, Tcl_GetEncodingName, Tcl_SetSystemEncoding, Tcl_GetEncodingNames, Tcl_CreateEncoding, 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, Tcl_GetDefaultEncodingDir, Tcl_SetDefaultEncodingDir \- procedures for creating and using encodings
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -19,19 +19,24 @@ Tcl_Encoding
 void
 \fBTcl_FreeEncoding\fR(\fIencoding\fR)
 .sp
+.VS 8.5
+int
+\fBTcl_GetEncodingFromObj\fR(\fIinterp, objPtr, encodingPtr\fR)
+.VE 8.5
+.sp
 char *
 \fBTcl_ExternalToUtfDString\fR(\fIencoding, src, srcLen, dstPtr\fR)
 .sp
-int
-\fBTcl_ExternalToUtf\fR(\fIinterp, encoding, src, srcLen, flags, statePtr, dst, dstLen, srcReadPtr, dstWrotePtr, 
-	dstCharsPtr\fR)
-.sp
-char * 
+char *
 \fBTcl_UtfToExternalDString\fR(\fIencoding, src, srcLen, dstPtr\fR)
 .sp
 int
-\fBTcl_UtfToExternal\fR(\fIinterp, encoding, src, srcLen, flags, statePtr, dst, dstLen, srcReadPtr, dstWrotePtr, 
-	dstCharsPtr\fR)
+\fBTcl_ExternalToUtf\fR(\fIinterp, encoding, src, srcLen, flags, statePtr,
+                  dst, dstLen, srcReadPtr, dstWrotePtr, dstCharsPtr\fR)
+.sp
+int
+\fBTcl_UtfToExternal\fR(\fIinterp, encoding, src, srcLen, flags, statePtr,
+                  dst, dstLen, srcReadPtr, dstWrotePtr, dstCharsPtr\fR)
 .sp
 char *
 \fBTcl_WinTCharToUtf\fR(\fItsrc, srcLen, dstPtr\fR)
@@ -39,41 +44,60 @@ char *
 TCHAR *
 \fBTcl_WinUtfToTChar\fR(\fIsrc, srcLen, dstPtr\fR)
 .sp
-CONST char *
+const char *
 \fBTcl_GetEncodingName\fR(\fIencoding\fR)
 .sp
 int
 \fBTcl_SetSystemEncoding\fR(\fIinterp, name\fR)
 .sp
+.VS 8.5
+const char *
+\fBTcl_GetEncodingNameFromEnvironment\fR(\fIbufPtr\fR)
+.VE 8.5
+.sp
 void
 \fBTcl_GetEncodingNames\fR(\fIinterp\fR)
 .sp
 Tcl_Encoding
 \fBTcl_CreateEncoding\fR(\fItypePtr\fR)
 .sp
-CONST char *
+.VS 8.5
+Tcl_Obj *
+\fBTcl_GetEncodingSearchPath\fR()
+.sp
+int
+\fBTcl_SetEncodingSearchPath\fR(\fIsearchPath\fR)
+.VE 8.5
+.sp
+const char *
 \fBTcl_GetDefaultEncodingDir\fR(\fIvoid\fR)
 .sp
 void
 \fBTcl_SetDefaultEncodingDir\fR(\fIpath\fR)
-
-
 .SH ARGUMENTS
-.AS Tcl_EncodingState *dstWrotePtr
+.AS "const Tcl_EncodingType" *dstWrotePtr in/out
 .AP Tcl_Interp *interp in
 Interpreter to use for error reporting, or NULL if no error reporting is
 desired.
-.AP "CONST char" *name in
+.AP "const char" *name in
 Name of encoding to load.
 .AP Tcl_Encoding encoding in
 The encoding to query, free, or use for converting text.  If \fIencoding\fR is 
 NULL, the current system encoding is used.
-.AP "CONST char" *src in
+.AP Tcl_Obj *objPtr in
+.VS 8.5
+Name of encoding to get token for.
+.VE 8.5
+.AP Tcl_Encoding *encodingPtr out
+.VS 8.5
+Points to storage where encoding token is to be written.
+.VE 8.5
+.AP "const char" *src in
 For the \fBTcl_ExternalToUtf\fR functions, an array of bytes in the
 specified encoding that are to be converted to UTF-8.  For the
 \fBTcl_UtfToExternal\fR and \fBTcl_WinUtfToTChar\fR functions, an array of
 UTF-8 characters to be converted to the specified encoding.  
-.AP "CONST TCHAR" *tsrc in
+.AP "const TCHAR" *tsrc in
 An array of Windows TCHAR characters to convert to UTF-8.
 .AP int srcLen in 
 Length of \fIsrc\fR or \fItsrc\fR in bytes.  If the length is negative, the 
@@ -83,21 +107,21 @@ Pointer to an uninitialized or free \fBTcl_DString\fR in which the converted
 result will be stored.
 .AP int flags in
 Various flag bits OR-ed together.  
-TCL_ENCODING_START signifies that the
+\fBTCL_ENCODING_START\fR signifies that the
 source buffer is the first block in a (potentially multi-block) input
 stream, telling the conversion routine to reset to an initial state and
 perform any initialization that needs to occur before the first byte is
-converted.  TCL_ENCODING_END signifies that the source buffer is the last
+converted. \fBTCL_ENCODING_END\fR signifies that the source buffer is the last
 block in a (potentially multi-block) input stream, telling the conversion
 routine to perform any finalization that needs to occur after the last
 byte is converted and then to reset to an initial state.
-TCL_ENCODING_STOPONERROR signifies that the conversion routine should
-return immediately upon reading a source character that doesn't exist in
+\fBTCL_ENCODING_STOPONERROR\fR signifies that the conversion routine should
+return immediately upon reading a source character that does not exist in
 the target encoding; otherwise a default fallback character will
 automatically be substituted.  
 .AP Tcl_EncodingState *statePtr in/out
 Used when converting a (generally long or indefinite length) byte stream
-in a piece by piece fashion.  The conversion routine stores its current
+in a piece-by-piece fashion.  The conversion routine stores its current
 state in \fI*statePtr\fR after \fIsrc\fR (the buffer containing the
 current piece) has been converted; that state information must be passed
 back when converting the next piece of the stream so the conversion
@@ -120,9 +144,17 @@ buffer as a result of the conversion.  May be NULL.
 .AP int *dstCharsPtr out
 Filled with the number of characters that correspond to the number of bytes
 stored in the output buffer.  May be NULL.
-.AP Tcl_EncodingType *typePtr in
+.AP Tcl_DString *bufPtr out
+.VS 8.5
+Storage for the prescribed system encoding name.
+.VE 8.5
+.AP "const Tcl_EncodingType" *typePtr in
 Structure that defines a new type of encoding.  
-.AP "CONST char" *path in
+.AP Tcl_Obj *searchPath in
+.VS 8.5
+List of filesystem directories in which to search for encoding data files.
+.VE 8.5
+.AP "const char" *path in
 A path to the location of the encoding file.  
 .BE
 .SH INTRODUCTION
@@ -149,7 +181,7 @@ platform-independent manner.
 .SH DESCRIPTION
 .PP
 \fBTcl_GetEncoding\fR finds an encoding given its \fIname\fR.  The name may
-refer to a builtin Tcl encoding, a user-defined encoding registered by
+refer to a built-in Tcl encoding, a user-defined encoding registered by
 calling \fBTcl_CreateEncoding\fR, or a dynamically-loadable encoding
 file.  The return value is a token that represents the encoding and can be
 used in subsequent calls to procedures such as \fBTcl_GetEncodingName\fR,
@@ -170,6 +202,20 @@ anywhere (i.e., it has been freed as many times as it has been gotten)
 \fBTcl_FreeEncoding\fR will release all storage the encoding was using
 and delete it from the database. 
 .PP
+.VS 8.5
+\fBTcl_GetEncodingFromObj\fR treats the string representation of
+\fIobjPtr\fR as an encoding name, and finds an encoding with that
+name, just as \fBTcl_GetEncoding\fR does. When an encoding is found,
+it is cached within the \fBobjPtr\fR value for future reference, the
+\fBTcl_Encoding\fR token is written to the storage pointed to by
+\fIencodingPtr\fR, and the value \fBTCL_OK\fR is returned. If no such
+encoding is found, the value \fBTCL_ERROR\fR is returned, and no
+writing to \fB*\fR\fIencodingPtr\fR takes place. Just as with
+\fBTcl_GetEncoding\fR, the caller should call \fBTcl_FreeEncoding\fR
+on the resulting encoding token when that token will no longer be
+used.
+.VE 8.5
+.PP
 \fBTcl_ExternalToUtfDString\fR converts a source buffer \fIsrc\fR from the
 specified \fIencoding\fR into UTF-8.  The converted bytes are stored in 
 \fIdstPtr\fR, which is then null-terminated.  The caller should eventually
@@ -192,7 +238,7 @@ All bytes of \fIsrc\fR were converted.
 The destination buffer was not large enough for all of the converted data; as
 many characters as could fit were converted though.
 .IP \fBTCL_CONVERT_MULTIBYTE\fR 29
-The last fews bytes in the source buffer were the beginning of a multibyte
+The last few bytes in the source buffer were the beginning of a multibyte
 sequence, but more bytes were needed to complete this sequence.  A
 subsequent call to the conversion routine should pass a buffer containing
 the unconverted bytes that remained in \fIsrc\fR plus some further bytes
@@ -204,7 +250,7 @@ if the input stream has been damaged or if the input encoding method was
 misidentified.
 .IP \fBTCL_CONVERT_UNKNOWN\fR 29
 The source buffer contained a character that could not be represented in
-the target encoding and TCL_ENCODING_STOPONERROR was specified.  
+the target encoding and \fBTCL_ENCODING_STOPONERROR\fR was specified.  
 .RE
 .LP
 \fBTcl_UtfToExternalDString\fR converts a source buffer \fIsrc\fR from UTF-8 
@@ -228,19 +274,26 @@ is filled with the corresponding number of bytes that were stored in
 \fBTcl_WinUtfToTChar\fR and \fBTcl_WinTCharToUtf\fR are
 Windows-only convenience
 functions for converting between UTF-8 and Windows strings.  On Windows 95
-(as with the Macintosh and Unix operating systems),
-all strings exchanged between Tcl and the operating system are "char"
+(as with the Unix operating system),
+all strings exchanged between Tcl and the operating system are
+.QW "char"
 based.  On Windows NT, some strings exchanged between Tcl and the
-operating system are "char" oriented while others are in Unicode.  By
+operating system are
+.QW "char"
+oriented while others are in Unicode.  By
 convention, in Windows a TCHAR is a character in the ANSI code page
 on Windows 95 and a Unicode character on Windows NT.
 .PP
-If you planned to use the same "char" based interfaces on both Windows
+If you planned to use the same
+.QW "char"
+based interfaces on both Windows
 95 and Windows NT, you could use \fBTcl_UtfToExternal\fR and
 \fBTcl_ExternalToUtf\fR (or their \fBTcl_DString\fR equivalents) with an
 encoding of NULL (the current system encoding).  On the other hand,
 if you planned to use the Unicode interface when running on Windows NT
-and the "char" interfaces when running on Windows 95, you would have
+and the
+.QW "char"
+interfaces when running on Windows 95, you would have
 to perform the following type of test over and over in your program
 (as represented in pseudo-code):
 .CS
@@ -250,6 +303,7 @@ if (running NT) {
     Tcl_FreeEncoding(encoding);
 } else {
     nativeBuffer <- Tcl_UtfToExternal(NULL, utfBuffer);
+}
 .CE
 \fBTcl_WinUtfToTChar\fR and \fBTcl_WinTCharToUtf\fR automatically
 handle this test and use the proper encoding based on the current
@@ -269,11 +323,20 @@ was used to create the encoding.  The string returned by
 whenever the user passes a NULL value for the \fIencoding\fR argument to
 any of the other encoding functions.  If \fIname\fR is NULL, the system
 encoding is reset to the default system encoding, \fBbinary\fR.  If the
-name did not refer to any known or loadable encoding, TCL_ERROR is
+name did not refer to any known or loadable encoding, \fBTCL_ERROR\fR is
 returned and an error message is left in \fIinterp\fR.  Otherwise, this
 procedure increments the reference count of the new system encoding,
 decrements the reference count of the old system encoding, and returns
-TCL_OK.
+\fBTCL_OK\fR.
+.PP
+.VS 8.5
+\fBTcl_GetEncodingNameFromEnvironment\fR provides a means for the Tcl
+library to report the encoding name it believes to be the correct one
+to use as the system encoding, based on system calls and examination of
+the environment suitable for the platform.  It accepts \fIbufPtr\fR,
+a pointer to an uninitialized or freed \fBTcl_DString\fR and writes
+the encoding name to it.  The \fBTcl_DStringValue\fR is returned.
+.VE 8.5
 .PP
 \fBTcl_GetEncodingNames\fR sets the \fIinterp\fR result to a list
 consisting of the names of all the encodings that are currently defined
@@ -301,12 +364,12 @@ convert between this encoding and UTF-8.  It is defined as follows:
 .PP
 .CS
 typedef struct Tcl_EncodingType {
-	CONST char *\fIencodingName\fR;
-	Tcl_EncodingConvertProc *\fItoUtfProc\fR;
-	Tcl_EncodingConvertProc *\fIfromUtfProc\fR;
-	Tcl_EncodingFreeProc *\fIfreeProc\fR;
-	ClientData \fIclientData\fR;
-	int \fInullSize\fR;
+        const char *\fIencodingName\fR;
+        Tcl_EncodingConvertProc *\fItoUtfProc\fR;
+        Tcl_EncodingConvertProc *\fIfromUtfProc\fR;
+        Tcl_EncodingFreeProc *\fIfreeProc\fR;
+        ClientData \fIclientData\fR;
+        int \fInullSize\fR;
 } Tcl_EncodingType;  
 .CE
 .PP
@@ -336,16 +399,16 @@ type \fBTcl_EncodingConvertProc\fR:
 .PP
 .CS
 typedef int Tcl_EncodingConvertProc(
-	ClientData \fIclientData\fR,
-	CONST char *\fIsrc\fR, 
-	int \fIsrcLen\fR, 
-	int \fIflags\fR, 
-	Tcl_Encoding *\fIstatePtr\fR,
-	char *\fIdst\fR, 
-	int \fIdstLen\fR, 
-	int *\fIsrcReadPtr\fR,
-	int *\fIdstWrotePtr\fR,
-	int *\fIdstCharsPtr\fR);
+        ClientData \fIclientData\fR,
+        const char *\fIsrc\fR, 
+        int \fIsrcLen\fR, 
+        int \fIflags\fR, 
+        Tcl_EncodingState *\fIstatePtr\fR,
+        char *\fIdst\fR, 
+        int \fIdstLen\fR, 
+        int *\fIsrcReadPtr\fR,
+        int *\fIdstWrotePtr\fR,
+        int *\fIdstCharsPtr\fR);
 .CE
 .PP
 The \fItoUtfProc\fR and \fIfromUtfProc\fR procedures are called by the
@@ -367,20 +430,42 @@ The callback procedure \fIfreeProc\fR, if non-NULL, should match the type
 \fBTcl_EncodingFreeProc\fR:
 .CS
 typedef void Tcl_EncodingFreeProc(
-	ClientData \fIclientData\fR);
+        ClientData \fIclientData\fR);
 .CE
 .PP
 This \fIfreeProc\fR function is called when the encoding is deleted.  The
 \fIclientData\fR parameter is the same as the \fIclientData\fR field
 specified to \fBTcl_CreateEncoding\fR when the encoding was created.  
 .PP
-
+.VS 8.5
+\fBTcl_GetEncodingSearchPath\fR and \fBTcl_SetEncodingSearchPath\fR
+are called to access and set the list of filesystem directories searched
+for encoding data files.  
+.PP
+The value returned by \fBTcl_GetEncodingSearchPath\fR
+is the value stored by the last successful call to
+\fBTcl_SetEncodingSearchPath\fR.  If no calls to
+\fBTcl_SetEncodingSearchPath\fR have occurred, Tcl will compute an initial
+value based on the environment.  There is one encoding search path for the
+entire process, shared by all threads in the process.
+.PP
+\fBTcl_SetEncodingSearchPath\fR stores \fIsearchPath\fR and returns
+\fBTCL_OK\fR, unless \fIsearchPath\fR is not a valid Tcl list, which
+causes \fBTCL_ERROR\fR to be returned.  The elements of \fIsearchPath\fR
+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
-access and set the directory to use when locating the default encoding
-files.  If this value is not NULL, the \fBTclpInitLibraryPath\fR routine
-appends the path to the head of the search path, and uses this path as
-the first place to look into when trying to locate the encoding file.
-
+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.
+.VE 8.5
 .SH "ENCODING FILES"
 Space would prohibit precompiling into Tcl every possible encoding
 algorithm, so many encodings are stored on disk as dynamically-loadable
@@ -392,23 +477,25 @@ external encoding may consist of single-byte, multi-byte, or double-byte
 characters.  
 .PP
 Each dynamically-loadable encoding is represented as a text file.  The
-initial line of the file, beginning with a ``#'' symbol, is a comment
+initial line of the file, beginning with a
+.QW #
+symbol, is a comment
 that provides a human-readable description of the file.  The next line
 identifies the type of encoding file.  It can be one of the following
 letters:
-.IP "[1]   \fBS\fR"
+.IP "[1] \fBS\fR"
 A single-byte encoding, where one character is always one byte long in the
 encoding.  An example is \fBiso8859-1\fR, used by many European languages.
-.IP "[2]   \fBD\fR"
+.IP "[2] \fBD\fR"
 A double-byte encoding, where one character is always two bytes long in the
 encoding.  An example is \fBbig5\fR, used for Chinese text.
-.IP "[3]   \fBM\fR"
+.IP "[3] \fBM\fR"
 A multi-byte encoding, where one character may be either one or two bytes long.
-Certain bytes are a lead bytes, indicating that another byte must follow
+Certain bytes are lead bytes, indicating that another byte must follow
 and that together the two bytes represent one character.  Other bytes are not
 lead bytes and represent themselves.  An example is \fBshiftjis\fR, used by
 many Japanese computers.
-.IP "[4]   \fBE\fR"
+.IP "[4] \fBE\fR"
 An escape-sequence encoding, specifying that certain sequences of bytes
 do not represent characters, but commands that describe how following bytes
 should be interpreted.  
@@ -478,7 +565,7 @@ and 0x8163 in \fBshiftjis\fR map to 203E and 2026 in Unicode, respectively.
 Following the first page will be all the other pages, each in the same
 format as the first: one number identifying the page followed by 256
 double-byte Unicode characters.  If a character in the encoding maps to the
-Unicode character 0000, it means that the character doesn't actually exist.
+Unicode character 0000, it means that the character does not actually exist.
 If all characters on a page would map to 0000, that page can be omitted.
 .PP
 Case [4] is the escape-sequence encoding file.  The lines in an this type of
@@ -490,13 +577,13 @@ encoding:
 E
 init		{}
 final		{}
-iso8859-1	\\x1b(B
-jis0201		\\x1b(J
-jis0208		\\x1b$@
-jis0208		\\x1b$B
-jis0212		\\x1b$(D
-gb2312		\\x1b$A
-ksc5601		\\x1b$(C
+iso8859-1	\ex1b(B
+jis0201		\ex1b(J
+jis0208		\ex1b$@
+jis0208		\ex1b$B
+jis0212		\ex1b$(D
+gb2312		\ex1b$A
+ksc5601		\ex1b$(C
 .CE
 .PP
 In the file, the first column represents an option and the second column
@@ -505,16 +592,16 @@ the first character is converted, while \fBfinal\fR is a string to emit
 or expect after the last character.  All other options are names of
 table-based encodings; the associated value is the escape-sequence that
 marks that encoding.  Tcl syntax is used for the values; in the above
-example, for instance, ``\fB{}\fR'' represents the empty string and
-``\fB\\x1b\fR'' represents character 27.
+example, for instance,
+.QW \fB{}\fR
+represents the empty string and
+.QW \fB\ex1b\fR
+represents character 27.
 .PP
 When \fBTcl_GetEncoding\fR encounters an encoding \fIname\fR that has not
 been loaded, it attempts to load an encoding file called \fIname\fB.enc\fR
-from the \fBencoding\fR subdirectory of each directory specified in the
-library path \fB$tcl_libPath\fR.  If the encoding file exists, but is
+from the \fBencoding\fR subdirectory of each directory that Tcl searches
+for its script library.  If the encoding file exists, but is
 malformed, an error message will be left in \fIinterp\fR.
 .SH KEYWORDS
 utf, encoding, convert
-
-
-

doc/Ensemble.3

@@ -0,0 +1,188 @@
+'\"
+'\" Copyright (c) 2005 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+'\" This documents the C API introduced in TIP#235
+'\" 
+.so man.macros
+.TH Tcl_Ensemble 3 8.5 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_CreateEnsemble, Tcl_FindEnsemble, Tcl_GetEnsembleFlags, Tcl_GetEnsembleMappingDict, Tcl_GetEnsembleNamespace, Tcl_GetEnsembleUnknownHandler, Tcl_GetEnsembleSubcommandList, Tcl_IsEnsemble, Tcl_SetEnsembleFlags, Tcl_SetEnsembleMappingDict, Tcl_SetEnsembleSubcommandList, Tcl_SetEnsembleUnknownHandler \- manipulate ensemble commands
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+Tcl_Command
+\fBTcl_CreateEnsemble\fR(\fIinterp, name, namespacePtr, ensFlags\fR)
+.sp
+Tcl_Command
+\fBTcl_FindEnsemble\fR(\fIinterp, cmdNameObj, flags\fR)
+.sp
+int
+\fBTcl_IsEnsemble\fR(\fItoken\fR)
+.sp
+int
+\fBTcl_GetEnsembleFlags\fR(\fIinterp, token, ensFlagsPtr\fR)
+.sp
+int
+\fBTcl_SetEnsembleFlags\fR(\fIinterp, token, ensFlags\fR)
+.sp
+int
+\fBTcl_GetEnsembleMappingDict\fR(\fIinterp, token, dictObjPtr\fR)
+.sp
+int
+\fBTcl_SetEnsembleMappingDict\fR(\fIinterp, token, dictObj\fR)
+.sp
+int
+\fBTcl_GetEnsembleSubcommandList\fR(\fIinterp, token, listObjPtr\fR)
+.sp
+int
+\fBTcl_SetEnsembleSubcommandList\fR(\fIinterp, token, listObj\fR)
+.sp
+int
+\fBTcl_GetEnsembleUnknownHandler\fR(\fIinterp, token, listObjPtr\fR)
+.sp
+int
+\fBTcl_SetEnsembleUnknownHandler\fR(\fIinterp, token, listObj\fR)
+.sp
+int
+\fBTcl_GetEnsembleNamespace\fR(\fIinterp, token, namespacePtrPtr\fR)
+.SH ARGUMENTS
+.AS Tcl_Namespace **namespacePtrPtr in/out
+.AP Tcl_Interp *interp in/out
+The interpreter in which the ensemble is to be created or found. Also
+where error result messages are written. The functions whose names
+start with \fBTcl_GetEnsemble\fR may have a NULL for the \fIinterp\fR,
+but all other functions must not.
+.AP "const char" *name in
+The name of the ensemble command to be created.
+.AP Tcl_Namespace *namespacePtr in
+The namespace to which the ensemble command is to be bound, or NULL
+for the current namespace.
+.AP int ensFlags in
+An ORed set of flag bits describing the basic configuration of the
+ensemble. Currently only one bit has meaning, TCL_ENSEMBLE_PREFIX,
+which is present when the ensemble command should also match
+unambiguous prefixes of subcommands.
+.AP Tcl_Obj *cmdNameObj in
+A value holding the name of the ensemble command to look up.
+.AP int flags in
+An ORed set of flag bits controlling the behavior of
+\fBTcl_FindEnsemble\fR. Currently only TCL_LEAVE_ERR_MSG is supported.
+.AP Tcl_Command token in
+A normal command token that refers to an ensemble command, or which
+you wish to use for testing as an ensemble command in \fBTcl_IsEnsemble\fR.
+.AP int *ensFlagsPtr out
+Pointer to a variable into which to write the current ensemble flag
+bits; currently only the bit TCL_ENSEMBLE_PREFIX is defined.
+.AP Tcl_Obj *dictObj in
+A dictionary value to use for the subcommand to implementation command
+prefix mapping dictionary in the ensemble. May be NULL if the mapping
+dictionary is to be removed.
+.AP Tcl_Obj **dictObjPtr out
+Pointer to a variable into which to write the current ensemble mapping
+dictionary.
+.AP Tcl_Obj *listObj in
+A list value to use for the defined list of subcommands in the
+dictionary or the unknown subcommmand handler command prefix. May be
+NULL if the subcommand list or unknown handler are to be removed.
+.AP Tcl_Obj **listObjPtr out
+Pointer to a variable into which to write the current defiend list of
+subcommands or the current unknown handler prefix.
+.AP Tcl_Namespace **namespacePtrPtr out
+Pointer to a variable into which to write the handle of the namespace
+to which the ensemble is bound.
+.BE
+
+.SH DESCRIPTION
+An ensemble is a command, bound to some namespace, which consists of a
+collection of subcommands implemented by other Tcl commands. The first
+argument to the ensemble command is always interpreted as a selector
+that states what subcommand to execute.
+.PP
+Ensembles are created using \fBTcl_CreateEnsemble\fR, which takes four
+arguments: the interpreter to work within, the name of the ensemble to
+create, the namespace within the interpreter to bind the ensemble to,
+and the default set of ensemble flags. The result of the function is
+the command token for the ensemble, which may be used to further
+configure the ensemble using the API described below in \fBENSEMBLE
+PROPERTIES\fR.
+.PP
+Given the name of an ensemble command, the token for that command may
+be retrieved using \fBTcl_FindEnsemble\fR. If the given command name
+(in \fIcmdNameObj\fR) does not refer to an ensemble command, the
+result of the function is NULL and (if the TCL_LEAVE_ERR_MSG bit is
+set in \fIflags\fR) an error message is left in the interpreter
+result.
+.PP
+A command token may be checked to see if it refers to an ensemble
+using \fBTcl_IsEnsemble\fR. This returns 1 if the token refers to an
+ensemble, or 0 otherwise.
+.SS "ENSEMBLE PROPERTIES"
+Every ensemble has four read-write properties and a read-only
+property. The properties are:
+.TP
+\fBflags\fR (read-write)
+The set of flags for the ensemble, expressed as a
+bit-field. Currently, the only public flag is TCL_ENSEMBLE_PREFIX
+which is set when unambiguous prefixes of subcommands are permitted to
+be resolved to implementations as well as exact matches. The flags may
+be read and written using \fBTcl_GetEnsembleFlags\fR and
+\fBTcl_SetEnsembleFlags\fR respectively. The result of both of those
+functions is a Tcl result code (TCL_OK, or TCL_ERROR if the token does
+not refer to an ensemble).
+.TP
+\fBmapping dictionary\fR (read-write)
+A dictionary containing a mapping from subcommand names to lists of
+words to use as a command prefix (replacing the first two words of the
+command which are the ensemble command itself and the subcommand
+name), or NULL if every subcommand is to be mapped to the command with
+the same unqualified name in the ensemble's bound namespace. Defaults
+to NULL. May be read and written using
+\fBTcl_GetEnsembleMappingDict\fR and \fBTcl_SetEnsembleMappingDict\fR
+respectively. The result of both of those functions is a Tcl result
+code (TCL_OK, or TCL_ERROR if the token does not refer to an
+ensemble) and the dictionary obtained from
+\fBTcl_GetEnsembleMappingDict\fR should always be treated as immutable
+even if it is unshared.
+All command names in prefixes set via \fBTcl_SetEnsembleMappingDict\fR
+must be fully qualified.
+.TP
+\fBsubcommand list\fR (read-write)
+A list of all the subcommand names for the ensemble, or NULL if this
+is to be derived from either the keys of the mapping dictionary (see
+above) or (if that is also NULL) from the set of commands exported by
+the bound namespace. May be read and written using
+\fBTcl_GetEnsembleSubcommandList\fR and
+\fBTcl_SetEnsembleSubcommandList\fR respectively. The result of both
+of those functions is a Tcl result code (TCL_OK, or TCL_ERROR if the
+token does not refer to an ensemble) and the list obtained from
+\fBTcl_GetEnsembleSubcommandList\fR should always be treated as
+immutable even if it is unshared.
+.TP
+\fBunknown subcommand handler command prefix\fR (read-write)
+A list of words to prepend on the front of any subcommand when the
+subcommand is unknown to the ensemble (according to the current prefix
+handling rule); see the \fBnamespace ensemble\fR command for more
+details. If NULL, the default behavior \- generate a suitable error
+message \- will be used when an unknown subcommand is encountered. May
+be read and written using \fBTcl_GetEnsembleUnknownHandler\fR and
+\fBTcl_SetEnsembleUnknownHandler\fR respectively. The result of both
+functions is a Tcl result code (TCL_OK, or TCL_ERROR if the token does
+not refer to an ensemble) and the list obtained from
+\fBTcl_GetEnsembleUnknownHandler\fR should always be treated as
+immutable even if it is unshared.
+.TP
+\fBbound namespace\fR (read-only)
+The namespace to which the ensemble is bound; when the namespace is
+deleted, so too will the ensemble, and this namespace is also the
+namespace whose list of exported commands is used if both the mapping
+dictionary and the subcommand list properties are NULL. May be read
+using \fBTcl_GetEnsembleNamespace\fR which returns a Tcl result code
+(TCL_OK, or TCL_ERROR if the token does not refer to an ensemble).
+
+.SH "SEE ALSO"
+namespace(n), Tcl_DeleteCommandFromToken(3)

doc/Environment.3

@@ -14,21 +14,25 @@ Tcl_PutEnv \- procedures to manipulate the environment
 \fB#include <tcl.h>\fR
 .sp
 int
-\fBTcl_PutEnv\fR(\fIstring\fR)
+\fBTcl_PutEnv\fR(\fIassignment\fR)
 .SH ARGUMENTS
-.AP "CONST char" *string in
-Info about environment variable in the form NAME=value.
-The \fIstring\fR argument is in the system encoding.
+.AS "const char" *assignment
+.AP "const char" *assignment in
+Info about environment variable in the format
+.QW \fINAME\fB=\fIvalue\fR .
+The \fIassignment\fR argument is in the system encoding.
 .BE
-
 .SH DESCRIPTION
 .PP
 \fBTcl_PutEnv\fR sets an environment variable. The information is
-passed in a single string of the form NAME=value.  This procedure is
+passed in a single string of the form
+.QW \fINAME\fB=\fIvalue\fR .
+This procedure is
 intended to be a stand-in for the UNIX \fBputenv\fR system call. All
-tcl-based applications using \fBputenv\fR should redefine it to
+Tcl-based applications using \fBputenv\fR should redefine it to
 \fBTcl_PutEnv\fR so that they will interface properly to the Tcl
 runtime.
-
+.SH "SEE ALSO"
+tclvars(n)
 .SH KEYWORDS
 environment, variable

doc/Eval.3

@@ -15,7 +15,6 @@ Tcl_EvalObjEx, Tcl_EvalFile, Tcl_EvalObjv, Tcl_Eval, Tcl_EvalEx, Tcl_GlobalEval,
 .nf
 \fB#include <tcl.h>\fR
 .sp
-.VS
 int
 \fBTcl_EvalObjEx\fR(\fIinterp, objPtr, flags\fR)
 .sp
@@ -38,12 +37,12 @@ int
 \fBTcl_GlobalEvalObj\fR(\fIinterp, objPtr\fR)
 .sp
 int
-\fBTcl_VarEval\fR(\fIinterp, string, string, ... \fB(char *) NULL\fR)
+\fBTcl_VarEval\fR(\fIinterp, part, part, ... \fB(char *) NULL\fR)
 .sp
 int
 \fBTcl_VarEvalVA\fR(\fIinterp, argList\fR)
 .SH ARGUMENTS
-.AS Tcl_Interp **termPtr;
+.AS Tcl_Interp **termPtr
 .AP Tcl_Interp *interp in
 Interpreter in which to execute the script.  The interpreter's result is
 modified to hold the result or error message from the script.
@@ -52,7 +51,7 @@ A Tcl object containing the script to execute.
 .AP int flags in
 ORed combination of flag bits that specify additional options.
 \fBTCL_EVAL_GLOBAL\fR and \fBTCL_EVAL_DIRECT\fR are currently supported.
-.AP "CONST char" *fileName in
+.AP "const char" *fileName in
 Name of a file containing a Tcl script.
 .AP int objc in
 The number of objects in the array pointed to by \fIobjPtr\fR;
@@ -64,13 +63,13 @@ value of a single word in the command to execute.
 The number of bytes in \fIscript\fR, not including any
 null terminating character.  If \-1, then all characters up to the
 first null byte are used.
-.AP "CONST char" *script in
+.AP "const char" *script in
 Points to first byte of script to execute (null-terminated and UTF-8).
-.AP char *string in
+.AP char *part in
 String forming part of a Tcl script.
 .AP va_list argList in
-An argument list which must have been initialised using
-\fBTCL_VARARGS_START\fR, and cleared using \fBva_end\fR.
+An argument list which must have been initialized using
+\fBva_start\fR, and cleared using \fBva_end\fR.
 .BE
 
 .SH DESCRIPTION
@@ -97,26 +96,33 @@ result; it can be retrieved using \fBTcl_GetObjResult\fR.
 \fBTcl_EvalFile\fR reads the file given by \fIfileName\fR and evaluates
 its contents as a Tcl script.  It returns the same information as
 \fBTcl_EvalObjEx\fR.
-If the file couldn't be read then a Tcl error is returned to describe
-why the file couldn't be read.
-.VS 8.4
-The eofchar for files is '\\32' (^Z) for all platforms.
-If you require a ``^Z'' in code for string comparison, you can use
-``\\032'' or ``\\u001a'', which will be safely substituted by the Tcl
-interpreter into ``^Z''.
-.VE 8.4
+If the file could not be read then a Tcl error is returned to describe
+why the file could not be read.
+The eofchar for files is
+.QW \e32
+(^Z) for all platforms. If you require a
+.QW ^Z
+in code for string comparison, you can use
+.QW \e032
+or
+.QW \eu001a ,
+which will be safely substituted by the Tcl interpreter into
+.QW ^Z .
 .PP
 \fBTcl_EvalObjv\fR executes a single pre-parsed command instead of a
 script.  The \fIobjc\fR and \fIobjv\fR arguments contain the values
 of the words for the Tcl command, one word in each object in
 \fIobjv\fR.  \fBTcl_EvalObjv\fR evaluates the command and returns
 a completion code and result just like \fBTcl_EvalObjEx\fR.
+The caller of \fBTcl_EvalObjv\fR has to manage the reference count of the
+elements of \fIobjv\fR, insuring that the objects are valid until
+\fBTcl_EvalObjv\fR returns.  
 .PP
 \fBTcl_Eval\fR is similar to \fBTcl_EvalObjEx\fR except that the script to
 be executed is supplied as a string instead of an object and no compilation
 occurs.  The string should be a proper UTF-8 string as converted by
 \fBTcl_ExternalToUtfDString\fR or \fBTcl_ExternalToUtf\fR when it is known
-to possibly contain upper ASCII characters who's possible combinations
+to possibly contain upper ASCII characters whose possible combinations
 might be a UTF-8 special code.  The string is parsed and executed directly
 (using \fBTcl_EvalObjv\fR) instead of compiling it and executing the
 bytecodes.  In situations where it is known that the script will never be
@@ -126,7 +132,7 @@ executed again, \fBTcl_Eval\fR may be faster than \fBTcl_EvalObjEx\fR.
 Tcl 8.0, \fBTcl_Eval\fR copies the object 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
-doesn't do the copy.
+does not do the copy.
 .PP
 \fBTcl_EvalEx\fR is an extended version of \fBTcl_Eval\fR that takes
 additional arguments \fInumBytes\fR and \fIflags\fR.  For the
@@ -163,8 +169,8 @@ compiled to bytecodes; instead it is executed directly
 as is done by \fBTcl_EvalEx\fR.  The
 \fBTCL_EVAL_DIRECT\fR flag is useful in situations where the
 contents of an object are going to change immediately, so the
-bytecodes won't be reused in a future execution.  In this case,
-it's faster to execute the script directly.
+bytecodes will not be reused in a future execution.  In this case,
+it is faster to execute the script directly.
 .TP 23
 \fBTCL_EVAL_GLOBAL\fR
 If this flag is set, the script is processed at global level.  This
@@ -197,7 +203,6 @@ the \fBreturn\fR, \fBbreak\fR, or \fBcontinue\fR command was
 invoked in an inappropriate place.
 This means that top-level applications should never see a return code
 from \fBTcl_EvalObjEx\fR other then \fBTCL_OK\fR or \fBTCL_ERROR\fR.
-.VE
 
 .SH KEYWORDS
 execute, file, global, object, result, script

doc/Exit.3

@@ -5,10 +5,10 @@
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
 .so man.macros
-.TH Tcl_Exit 3 8.1 Tcl "Tcl Library Procedures"
+.TH Tcl_Exit 3 8.5 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_Exit, Tcl_Finalize, Tcl_CreateExitHandler, Tcl_DeleteExitHandler, Tcl_ExitThread, Tcl_FinalizeThread, Tcl_CreateThreadExitHandler, Tcl_DeleteThreadExitHandler \- end the application or thread (and invoke exit handlers)
+Tcl_Exit, Tcl_Finalize, Tcl_CreateExitHandler, Tcl_DeleteExitHandler, Tcl_ExitThread, Tcl_FinalizeThread, Tcl_CreateThreadExitHandler, Tcl_DeleteThreadExitHandler, Tcl_SetExitProc \- end the application or thread (and invoke exit handlers)
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -28,6 +28,11 @@ Tcl_Exit, Tcl_Finalize, Tcl_CreateExitHandler, Tcl_DeleteExitHandler, Tcl_ExitTh
 \fBTcl_CreateThreadExitHandler\fR(\fIproc, clientData\fR)
 .sp
 \fBTcl_DeleteThreadExitHandler\fR(\fIproc, clientData\fR)
+.sp
+.VS 8.5
+Tcl_ExitProc *
+\fBTcl_SetExitProc\fR(\fIproc\fR)
+.VE 8.5
 .SH ARGUMENTS
 .AS Tcl_ExitProc clientData
 .AP int status  in
@@ -36,7 +41,9 @@ Exact meaning may
 be platform-specific.  0 usually means a normal exit, any nonzero value
 usually means that an error occurred.
 .AP Tcl_ExitProc *proc in
-Procedure to invoke before exiting application.
+Procedure to invoke before exiting application, or (for
+\fBTcl_SetExitProc\fR) NULL to uninstall the current application exit
+procedure.
 .AP ClientData clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .BE
@@ -57,6 +64,12 @@ otherwise causes the application to terminate without calling
 \fBTcl_Exit\fR, the exit handlers will not be run.
 \fBTcl_Exit\fR internally invokes the \fBexit\fR system call, thus it never
 returns control to its caller.
+.VS 8.5
+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
+exit handler should not return control to Tcl.
+.VE 8.5
 .PP
 \fBTcl_Finalize\fR is similar to \fBTcl_Exit\fR except that it does not
 exit from the current process.
@@ -71,14 +84,12 @@ However, to ensure portability, your code should always invoke
 code will work on all platforms. \fBTcl_Finalize\fR can be safely called
 more than once.
 .PP
-.VS
 \fBTcl_ExitThread\fR is used to terminate the current thread and invoke
 per-thread exit handlers.  This finalization is done by
 \fBTcl_FinalizeThread\fR, which you can call if you just want to clean
 up per-thread state and invoke the thread exit handlers.
 \fBTcl_Finalize\fR calls \fBTcl_FinalizeThread\fR for the current
 thread automatically.
-.VE
 .PP
 \fBTcl_CreateExitHandler\fR arranges for \fIproc\fR to be invoked
 by \fBTcl_Finalize\fR and \fBTcl_Exit\fR.
@@ -105,7 +116,6 @@ indicated by \fIproc\fR and \fIclientData\fR so that no call
 to \fIproc\fR will be made.  If no such handler exists then
 \fBTcl_DeleteExitHandler\fR or \fBTcl_DeleteThreadExitHandler\fR does nothing.
 .PP
-.VS
 .PP
 \fBTcl_Finalize\fR and \fBTcl_Exit\fR execute all registered exit handlers,
 in reverse order from the order in which they were registered.
@@ -115,15 +125,23 @@ unloads \fBB\fR before it itself is unloaded.
 If extension \fBA\fR registers its exit handlers before loading extension
 \fBB\fR, this ensures that any exit handlers for \fBB\fR will be executed
 before the exit handlers for \fBA\fR.
-.VE
-.VS
 .PP
 \fBTcl_Finalize\fR and \fBTcl_Exit\fR call \fBTcl_FinalizeThread\fR 
 and the thread exit handlers \fIafter\fR
 the process-wide exit handlers.  This is because thread finalization shuts
 down the I/O channel system, so any attempt at I/O by the global exit
 handlers will vanish into the bitbucket.
-.VE
+.PP
+.VS 8.5
+\fBTcl_SetExitProc\fR installs an application exit handler, returning
+the previously-installed application exit handler or NULL if no
+application handler was installed.  If an application exit handler is
+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.
+.VE 8.5
 
 .SH KEYWORDS
 callback, cleanup, dynamic loading, end application, exit, unloading, thread

doc/ExprLong.3

@@ -15,23 +15,21 @@ Tcl_ExprLong, Tcl_ExprDouble, Tcl_ExprBoolean, Tcl_ExprString \- evaluate an exp
 \fB#include <tcl.h>\fR
 .sp
 int
-\fBTcl_ExprLong\fR(\fIinterp, string, longPtr\fR)
+\fBTcl_ExprLong\fR(\fIinterp, expr, longPtr\fR)
 .sp
 int
-\fBTcl_ExprDouble\fR(\fIinterp, string, doublePtr\fR)
+\fBTcl_ExprDouble\fR(\fIinterp, expr, doublePtr\fR)
 .sp
 int
-\fBTcl_ExprBoolean\fR(\fIinterp, string, booleanPtr\fR)
+\fBTcl_ExprBoolean\fR(\fIinterp, expr, booleanPtr\fR)
 .sp
 int
-\fBTcl_ExprString\fR(\fIinterp, string\fR)
+\fBTcl_ExprString\fR(\fIinterp, expr\fR)
 .SH ARGUMENTS
-.AS Tcl_Interp *booleanPtr
+.AS Tcl_Interp *booleanPtr out
 .AP Tcl_Interp *interp in
-Interpreter in whose context to evaluate \fIstring\fR.
-.VS 8.4
-.AP "CONST char" *string in
-.VE
+Interpreter in whose context to evaluate \fIexpr\fR.
+.AP "const char" *expr in
 Expression to be evaluated.  
 .AP long *longPtr out
 Pointer to location in which to store the integer value of the
@@ -47,7 +45,7 @@ expression.
 .SH DESCRIPTION
 .PP
 These four procedures all evaluate the expression
-given by the \fIstring\fR argument
+given by the \fIexpr\fR argument
 and return the result in one of four different forms.
 The expression can have any of the forms accepted by the \fBexpr\fR command.
 Note that these procedures have been largely replaced by the
@@ -92,7 +90,11 @@ number, then they store 0 at \fI*booleanPtr\fR if
 the value was zero and 1 otherwise.
 If the expression's actual value is a non-numeric string then
 it must be one of the values accepted by \fBTcl_GetBoolean\fR
-such as ``yes'' or ``no'', or else an error occurs.
+such as
+.QW yes
+or
+.QW no ,
+or else an error occurs.
 .PP
 \fBTcl_ExprString\fR returns the value of the expression as a
 string stored in the interpreter's result.

doc/ExprLongObj.3

@@ -86,7 +86,11 @@ number, then they store 0 at \fI*booleanPtr\fR if
 the value was zero and 1 otherwise.
 If the expression's actual value is a non-numeric string then
 it must be one of the values accepted by \fBTcl_GetBoolean\fR
-such as ``yes'' or ``no'', or else an error occurs.
+such as
+.QW yes
+or
+.QW no ,
+or else an error occurs.
 .PP
 If \fBTcl_ExprObj\fR successfully evaluates the expression,
 it stores a pointer to the Tcl object

doc/FindExec.3

@@ -16,10 +16,10 @@ Tcl_FindExecutable, Tcl_GetNameOfExecutable \- identify or return the name of th
 void
 \fBTcl_FindExecutable\fR(\fIargv0\fR)
 .sp
-CONST char *
+const char *
 \fBTcl_GetNameOfExecutable\fR()
 .SH ARGUMENTS
-.AS char *argv0 in
+.AS char *argv0
 .AP char *argv0 in
 The first command-line argument to the program, which gives the
 application's name.

doc/GetCwd.3

@@ -19,7 +19,7 @@ char *
 int
 \fBTcl_Chdir\fR(\fIpath\fR)
 .SH ARGUMENTS
-.AS Tcl_DString *bufferPtr
+.AS Tcl_DString *bufferPtr in/out
 .AP Tcl_Interp *interp in
 Interpreter in which to report an error, if any.
 .AP Tcl_DString *bufferPtr in/out
@@ -39,7 +39,7 @@ the same functionality as the Tcl \fBpwd\fR command.
 .PP
 \fBTcl_GetCwd\fR returns a pointer to a string specifying the current
 directory, or NULL if the current directory could not be determined.
-If NULL is returned, an error message is left in the interp's result.
+If NULL is returned, an error message is left in the \fIinterp\fR's result.
 Storage for the result string is allocated in bufferPtr; the caller
 must call \fBTcl_DStringFree()\fR when the result is no longer needed.
 The format of the path is UTF\-8.

doc/GetHostName.3

@@ -11,7 +11,7 @@ Tcl_GetHostName \- get the name of the local host
 .nf
 \fB#include <tcl.h>\fR
 .sp
-CONST char *
+const char *
 \fBTcl_GetHostName\fR()
 .BE
 

doc/GetIndex.3

@@ -16,14 +16,12 @@ Tcl_GetIndexFromObj, Tcl_GetIndexFromObjStruct \- lookup string in table of keyw
 int
 \fBTcl_GetIndexFromObj\fR(\fIinterp, objPtr, tablePtr, msg, flags,
 indexPtr\fR)
-.VS
 .sp
 int
 \fBTcl_GetIndexFromObjStruct\fR(\fIinterp, objPtr, structTablePtr, offset,
-msg, flags, indexPtr\fR)
-.VE
+                          msg, flags, indexPtr\fR)
 .SH ARGUMENTS
-.AS "CONST char" **tablePtr
+.AS "const char" *structTablePtr in/out
 .AP Tcl_Interp *interp in
 Interpreter to use for error reporting; if NULL, then no message is
 provided on errors.
@@ -31,25 +29,23 @@ provided on errors.
 The string value of this object is used to search through \fItablePtr\fR.
 The internal representation is modified to hold the index of the matching
 table entry.
-.AP "CONST char" **tablePtr in
+.AP "const char" **tablePtr in
 An array of null-terminated strings.  The end of the array is marked
 by a NULL string pointer.
 Note that references to the \fItablePtr\fR may be retained in the
 internal representation of \fIobjPtr\fR, so this should represent the
 address of a statically-allocated array.
-.AP "CONST VOID" *structTablePtr in
-An array of arbitrary type, typically some \fBstruct\fP type.
+.AP "const void" *structTablePtr in
+An array of arbitrary type, typically some \fBstruct\fR type.
 The first member of the structure must be a null-terminated string.
-The size of the structure is given by \fIoffset\fP.
+The size of the structure is given by \fIoffset\fR.
 Note that references to the \fIstructTablePtr\fR may be retained in the
 internal representation of \fIobjPtr\fR, so this should represent the
 address of a statically-allocated array of structures.
-.VS
 .AP int offset in
 The offset to add to structTablePtr to get to the next entry.
 The end of the array is marked by a NULL string pointer.
-.VE
-.AP "CONST char" *msg in
+.AP "const char" *msg in
 Null-terminated string describing what is being looked up, such as
 \fBoption\fR.  This string is included in error messages.
 .AP int flags in
@@ -72,14 +68,14 @@ the strings in \fItablePtr\fR to find a match.  A match occurs if
 for exactly one of the strings in \fItablePtr\fR and the
 \fBTCL_EXACT\fR flag was not specified; in either case
 the index of the matching entry is stored at \fI*indexPtr\fR
-and TCL_OK is returned.
+and \fBTCL_OK\fR is returned.
 .PP
 If there is no matching entry,
-TCL_ERROR is returned and an error message is left in \fIinterp\fR's
-result if \fIinterp\fR isn't NULL.  \fIMsg\fR is included in the
+\fBTCL_ERROR\fR is returned and an error message is left in \fIinterp\fR's
+result if \fIinterp\fR is not NULL.  \fIMsg\fR is included in the
 error message to indicate what was being looked up.  For example,
 if \fImsg\fR is \fBoption\fR the error message will have a form like
-\fBbad option "firt": must be first, second, or third\fR.
+.QW "\fBbad option \N'34'firt\N'34': must be first, second, or third\fR" .
 .PP
 If \fBTcl_GetIndexFromObj\fR completes successfully it modifies the
 internal representation of \fIobjPtr\fR to hold the address of
@@ -91,17 +87,18 @@ operation.  Note: \fBTcl_GetIndexFromObj\fR assumes that the entries
 in \fItablePtr\fR are static: they must not change between
 invocations.  If the value of \fIobjPtr\fR is the empty string,
 \fBTcl_GetIndexFromObj\fR will treat it as a non-matching value
-and return TCL_ERROR.
-.VS
+and return \fBTCL_ERROR\fR.
 .PP
 \fBTcl_GetIndexFromObjStruct\fR works just like
 \fBTcl_GetIndexFromObj\fR, except that instead of treating
-\fItablePtr\fR as an array of string pointers, it treats it as the
-first in a series of string ptrs that are spaced apart by \fIoffset\fR
-bytes. This is particularly useful when processing things like
+\fItablePtr\fR as an array of string pointers, it treats it as a
+pointer to the first string in a series of strings that have
+\fIoffset\fR bytes between them (i.e. that there is a pointer to the
+first array of characters at \fItablePtr\fR, a pointer to the second
+array of characters at \fItablePtr\fR+\fIoffset\fR bytes, etc.)
+This is particularly useful when processing things like
 \fBTk_ConfigurationSpec\fR, whose string keys are in the same place in
 each of several array elements.
-.VE
 
 .SH "SEE ALSO"
 Tcl_WrongNumArgs

doc/GetInt.3

@@ -15,62 +15,69 @@ Tcl_GetInt, Tcl_GetDouble, Tcl_GetBoolean \- convert from string to integer, dou
 \fB#include <tcl.h>\fR
 .sp
 int
-\fBTcl_GetInt\fR(\fIinterp, string, intPtr\fR)
+\fBTcl_GetInt\fR(\fIinterp, src, intPtr\fR)
 .sp
 int
-\fBTcl_GetDouble\fR(\fIinterp, string, doublePtr\fR)
+\fBTcl_GetDouble\fR(\fIinterp, src, doublePtr\fR)
 .sp
 int
-\fBTcl_GetBoolean\fR(\fIinterp, string, boolPtr\fR)
+\fBTcl_GetBoolean\fR(\fIinterp, src, boolPtr\fR)
 .SH ARGUMENTS
-.AS Tcl_Interp *doublePtr
+.AS Tcl_Interp *doublePtr out
 .AP Tcl_Interp *interp in
 Interpreter to use for error reporting.
-.AP "CONST char" *string in
+.AP "const char" *src in
 Textual value to be converted.
 .AP int *intPtr out
-Points to place to store integer value converted from \fIstring\fR.
+Points to place to store integer value converted from \fIsrc\fR.
 .AP double *doublePtr out
 Points to place to store double-precision floating-point
-value converted from \fIstring\fR.
+value converted from \fIsrc\fR.
 .AP int *boolPtr out
-Points to place to store boolean value (0 or 1) converted from \fIstring\fR.
+Points to place to store boolean value (0 or 1) converted from \fIsrc\fR.
 .BE
 
 .SH DESCRIPTION
 .PP
 These procedures convert from strings to integers or double-precision
 floating-point values or booleans (represented as 0- or 1-valued
-integers).  Each of the procedures takes a \fIstring\fR argument,
+integers).  Each of the procedures takes a \fIsrc\fR argument,
 converts it to an internal form of a particular type, and stores
 the converted value at the location indicated by the procedure's
 third argument.  If all goes well, each of the procedures returns
-TCL_OK.  If \fIstring\fR doesn't have the proper syntax for the
-desired type then TCL_ERROR is returned, an error message is left
+\fBTCL_OK\fR.  If \fIsrc\fR does not have the proper syntax for the
+desired type then \fBTCL_ERROR\fR is returned, an error message is left
 in the interpreter's result, and nothing is stored at *\fIintPtr\fR
 or *\fIdoublePtr\fR or *\fIboolPtr\fR.
 .PP
-\fBTcl_GetInt\fR expects \fIstring\fR to consist of a collection
+\fBTcl_GetInt\fR expects \fIsrc\fR to consist of a collection
 of integer digits, optionally signed and optionally preceded by
-white space.  If the first two characters of \fIstring\fR are ``0x''
-then \fIstring\fR is expected to be in hexadecimal form;  otherwise,
-if the first character of \fIstring\fR is ``0'' then \fIstring\fR
-is expected to be in octal form;  otherwise, \fIstring\fR is
+white space.  If the first two characters of \fIsrc\fR
+after the optional white space and sign are
+.QW 0x
+then \fIsrc\fR is expected to be in hexadecimal form;  otherwise,
+if the first such character is
+.QW 0
+then \fIsrc\fR
+is expected to be in octal form;  otherwise, \fIsrc\fR is
 expected to be in decimal form.
 .PP
-\fBTcl_GetDouble\fR expects \fIstring\fR to consist of a floating-point
+\fBTcl_GetDouble\fR expects \fIsrc\fR to consist of a floating-point
 number, which is:  white space;  a sign; a sequence of digits;  a
-decimal point;  a sequence of digits;  the letter ``e'';  and a
-signed decimal exponent.  Any of the fields may be omitted, except that
+decimal point;  a sequence of digits;  the letter
+.QW e ;
+a signed decimal exponent;  and more white space.
+Any of the fields may be omitted, except that
 the digits either before or after the decimal point must be present
-and if the ``e'' is present then it must be followed by the
-exponent number.
+and if the
+.QW e
+is present then it must be followed by the exponent number.
 .PP
-\fBTcl_GetBoolean\fR expects \fIstring\fR to specify a boolean
-value.  If \fIstring\fR is any of \fB0\fR, \fBfalse\fR,
+\fBTcl_GetBoolean\fR expects \fIsrc\fR to specify a boolean
+value.  If \fIsrc\fR is any of \fB0\fR, \fBfalse\fR,
 \fBno\fR, or \fBoff\fR, then \fBTcl_GetBoolean\fR stores a zero
 value at \fI*boolPtr\fR.
-If \fIstring\fR is any of \fB1\fR, \fBtrue\fR, \fByes\fR, or \fBon\fR,
+If \fIsrc\fR is any of \fB1\fR, \fBtrue\fR, \fByes\fR, or \fBon\fR,
 then 1 is stored at \fI*boolPtr\fR.
 Any of these values may be abbreviated, and upper-case spellings
 are also acceptable.

doc/GetOpnFl.3

@@ -8,29 +8,29 @@
 .TH Tcl_GetOpenFile 3 8.0 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_GetOpenFile \- Get a standard IO File * handle from a channel. (Unix only)
+Tcl_GetOpenFile \- Return a FILE* for a channel registered in the given interpreter (Unix only)
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
 .sp
 int
-\fBTcl_GetOpenFile\fR(\fIinterp, string, write, checkUsage, filePtr\fR)
+\fBTcl_GetOpenFile\fR(\fIinterp, chanID, write, checkUsage, filePtr\fR)
 .sp
 .SH ARGUMENTS
-.AS Tcl_Interp checkUsage
+.AS Tcl_Interp checkUsage out
 .AP Tcl_Interp *interp in
 Tcl interpreter from which file handle is to be obtained.
-.AP "CONST char" *string in
+.AP "const char" *chanID in
 String identifying channel, such as \fBstdin\fR or \fBfile4\fR.
 .AP int write in
 Non-zero means the file will be used for writing, zero means it will
 be used for reading.
 .AP int checkUsage in
-If non-zero, then an error will be generated if the file wasn't opened
+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
 Points to word in which to store pointer to FILE structure for
-the file given by \fIstring\fR.
+the file given by \fIchanID\fR.
 .BE
 
 .SH DESCRIPTION
@@ -44,17 +44,15 @@ be used for reading or writing.
 In some cases, such as a channel that connects to a pipeline of
 subprocesses, different FILE pointers will be returned for reading
 and writing.
-\fBTcl_GetOpenFile\fR normally returns TCL_OK.
-If an error occurs in \fBTcl_GetOpenFile\fR (e.g. \fIstring\fR didn't
-make any sense or \fIcheckUsage\fR was set and the file wasn't opened
-for the access specified by \fIwrite\fR) then TCL_ERROR is returned
+\fBTcl_GetOpenFile\fR normally returns \fBTCL_OK\fR.
+If an error occurs in \fBTcl_GetOpenFile\fR (e.g. \fIchanID\fR did not
+make any sense or \fIcheckUsage\fR was set and the file was not opened
+for the access specified by \fIwrite\fR) then \fBTCL_ERROR\fR is returned
 and the interpreter's result will contain an error message.
 In the current implementation \fIcheckUsage\fR is ignored and consistency
 checks are always performed.
-.VS
 .PP
 Note that this interface is only supported on the Unix platform.
-.VE
 
 .SH KEYWORDS
 channel, file handle, permissions, pipeline, read, write

doc/GetStdChan.3

@@ -20,7 +20,7 @@ Tcl_Channel
 \fBTcl_SetStdChannel\fR(\fIchannel, type\fR)
 .sp
 .SH ARGUMENTS
-.AS Tcl_Channel channel in
+.AS Tcl_Channel channel
 .AP int type in
 The identifier for the standard channel to retrieve or modify.  Must be one of
 \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, or \fBTCL_STDERR\fR.
@@ -76,7 +76,6 @@ standard error being last.
 .PP
 See \fBTcl_StandardChannels\fR for a general treatise about standard
 channels and the behaviour of the Tcl library with regard to them.
-.PP
 
 .SH "SEE ALSO"
 Tcl_Close(3), Tcl_CreateChannel(3), Tcl_Main(3), tclsh(1)

doc/GetTime.3

@@ -1,5 +1,5 @@
 '\"
-'\" Copyright (c) 2001 by Kevin B. Kenny.
+'\" Copyright (c) 2001 by Kevin B. Kenny <kennykb@acm.org>.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
@@ -8,16 +8,39 @@
 .TH Tcl_GetTime 3 8.4 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_GetTime \- get date and time
+Tcl_GetTime, Tcl_SetTimeProc, Tcl_QueryTimeProc \- get date and time
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
 .sp
-\fBTcl_GetTime\fR(\fI timePtr \fR)
+\fBTcl_GetTime\fR(\fItimePtr\fR)
+.sp
+\fBTcl_SetTimeProc\fR(\fIgetProc, scaleProc, clientData\fR)
+.sp
+\fBTcl_QueryTimeProc\fR(\fIgetProcPtr, scaleProcPtr, clientDataPtr\fR)
 .SH ARGUMENTS
-.AS "Tcl_Time *" timePtr
+.AS "Tcl_Time *" timePtr out
 .AP "Tcl_Time *" timePtr out
 Points to memory in which to store the date and time information.
+.AS "Tcl_GetTimeProc *" getProc in
+.AP "Tcl_GetTimeProc *" getProc in
+Pointer to handler function replacing \fBTcl_GetTime\fR's access to the OS.
+.AS "Tcl_ScaleTimeProc *" scaleProc in
+.AP "Tcl_ScaleTimeProc *" scaleProc in
+Pointer to handler function for the conversion of time delays in the
+virtual domain to real-time.
+.AS "ClientData *" clientData in
+.AP "ClientData *" clientData in
+Value passed through to the two handler functions.
+.AS "Tcl_GetTimeProc **" getProcPtr inout
+.AP "Tcl_GetTimeProc **" getProcPtr inout
+Pointer to place the currently registered get handler function into.
+.AS "Tcl_ScaleTimeProc **" scaleProcPtr inout
+.AP "Tcl_ScaleTimeProc **" scaleProcPtr inout
+Pointer to place the currently registered scale handler function into.
+.AS "ClientData **" clientDataPtr inout
+.AP "ClientData **" clientDataPtr inout
+Pointer to place the currently registered pass-through value into.
 .BE
 .SH DESCRIPTION
 .PP
@@ -45,6 +68,32 @@ computer system.  On multiprocessor variants of Windows, this number
 may be limited to the 10- or 20-ms granularity of the system clock.
 (On single-processor Windows systems, the \fIusec\fR field is derived
 from a performance counter and is highly precise.)
+.PP
+The \fBTcl_SetTime\fR function registers two related handler functions
+with the core. The first handler function is a replacement for
+\fBTcl_GetTime\fR, or rather the OS access made by
+\fBTcl_GetTime\fR. The other handler function is used by the Tcl
+notifier to convert wait/block times from the virtual domain into real
+time.
+.PP
+The \fBTcl_QueryTime\fR function returns the currently registered
+handler functions. If no external handlers were set then this will
+return the standard handlers accessing and processing the native time
+of the OS. The arguments to the function are allowed to be NULL; and
+any argument which is NULL is ignored and not set.
+.PP
+Any handler pair specified has to return data which is consistent
+between them. In other words, setting one handler of the pair to
+something assuming a 10-times slowdown, and the other handler of the
+pair to something assuming a two-times slowdown is wrong and not
+allowed.
+.PP
+The set handler functions are allowed to run the delivered time
+backwards, however this should be avoided. We have to allow it as the
+native time can run backwards as the user can fiddle with the system
+time one way or other. Note that the insertion of the hooks will not
+change the behaviour of the Tcl core with regard to this situation,
+i.e. the existing behaviour is retained.
 .SH "SEE ALSO"
 clock
 .SH KEYWORDS

doc/GetVersion.3

@@ -15,6 +15,7 @@ Tcl_GetVersion \- get the version of the library at runtime
 .sp
 \fBTcl_GetVersion\fR(\fImajor, minor, patchLevel, type\fR)
 .SH ARGUMENTS
+.AS Tcl_ReleaseType *patchLevel out
 .AP int *major out
 Major version number of the Tcl library.
 .AP int *minor out

doc/Hash.3

@@ -44,21 +44,21 @@ Tcl_HashEntry *
 Tcl_HashEntry *
 \fBTcl_NextHashEntry\fR(\fIsearchPtr\fR)
 .sp
-CONST char *
+char *
 \fBTcl_HashStats\fR(\fItablePtr\fR)
 .SH ARGUMENTS
-.AS Tcl_HashSearch *searchPtr
+.AS Tcl_HashKeyType *searchPtr out
 .AP Tcl_HashTable *tablePtr in
 Address of hash table structure (for all procedures but
 \fBTcl_InitHashTable\fR, this must have been initialized by
 previous call to \fBTcl_InitHashTable\fR).
 .AP int keyType in
 Kind of keys to use for new hash table.  Must be either
-TCL_STRING_KEYS, TCL_ONE_WORD_KEYS, TCL_CUSTOM_TYPE_KEYS,
-TCL_CUSTOM_PTR_KEYS, or an integer value greater than 1.
+\fBTCL_STRING_KEYS\fR, \fBTCL_ONE_WORD_KEYS\fR, \fBTCL_CUSTOM_TYPE_KEYS\fR,
+\fBTCL_CUSTOM_PTR_KEYS\fR, or an integer value greater than 1.
 .AP Tcl_HashKeyType *typePtr in
 Address of structure which defines the behaviour of the hash table.
-.AP "CONST char" *key in
+.AP "const char" *key in
 Key to use for probe into table.  Exact form depends on
 \fIkeyType\fR used to create table.
 .AP int *newPtr out
@@ -86,7 +86,9 @@ STRUCTURE\fR below). All of the keys in a given table have the same
 form, which is specified when the table is initialized.
 .PP
 The value of a hash table entry can be anything that fits in the same
-space as a ``char *'' pointer.  Values for hash table entries are
+space as a
+.QW "char *"
+pointer.  Values for hash table entries are
 managed entirely by clients, not by the hash module itself.  Typically
 each entry's value is a pointer to a data structure managed by client
 code.
@@ -122,8 +124,10 @@ They are passed to hashing routines using the address of the
 first character of the string.
 .IP \fBTCL_ONE_WORD_KEYS\fR 25
 Keys are single-word values;  they are passed to hashing routines
-and stored in hash table entries as ``char *'' values.
-The pointer value is the key;  it need not (and usually doesn't)
+and stored in hash table entries as
+.QW "char *"
+values.
+The pointer value is the key;  it need not (and usually does not)
 actually point to a string.
 .IP \fBTCL_CUSTOM_TYPE_KEYS\fR 25
 Keys are of arbitrary type, and are stored in the entry. Hashing
@@ -138,7 +142,9 @@ structure is described in the section
 .IP \fIother\fR 25
 If \fIkeyType\fR is not one of the above,
 then it must be an integer value greater than 1.
-In this case the keys will be arrays of ``int'' values, where
+In this case the keys will be arrays of
+.QW int
+values, where
 \fIkeyType\fR gives the number of ints in each key.
 This allows structures to be used as keys.
 All keys must have the same size.
@@ -159,7 +165,7 @@ before deleting the table.
 .PP
 \fBTcl_CreateHashEntry\fR locates the entry corresponding to a
 particular key, creating a new entry in the table if there
-wasn't already one with the given key.
+was not already one with the given key.
 If an entry already existed with the given key then \fI*newPtr\fR
 is set to zero.
 If a new entry was created, then \fI*newPtr\fR is set to a non-zero
@@ -175,28 +181,34 @@ the client is responsible for any cleanup associated with the
 entry's value, such as freeing a structure that it points to.
 .PP
 \fBTcl_FindHashEntry\fR is similar to \fBTcl_CreateHashEntry\fR
-except that it doesn't create a new entry if the key doesn't exist;
+except that it does not create a new entry if the key doesn't exist;
 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 ``ClientData'', which is
+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 (``char *'') key, or
+either as a pointer to a string, a one-word
+.PQ "char *"
+key, or
 as a pointer to the first word of an array of integers, depending
 on the \fIkeyType\fR used to create a hash table.
 In all cases \fBTcl_GetHashKey\fR returns a result with type
-``char *''.
+.QW "char *" .
 When the key is a string or array, the result of \fBTcl_GetHashKey\fR
 points to information in the table entry;  this information will
 remain valid until the entry is deleted or its table is deleted.
 .PP
 \fBTcl_FirstHashEntry\fR and \fBTcl_NextHashEntry\fR may be used
 to scan all of the entries in a hash table.
-A structure of type ``Tcl_HashSearch'', provided by the client,
+A structure of type
+.QW Tcl_HashSearch ,
+provided by the client,
 is used to keep track of progress through the table.
 \fBTcl_FirstHashEntry\fR initializes the search record and
 returns the first entry in the table (or NULL if the table is
@@ -207,9 +219,10 @@ NULL if the end of the table has been reached.
 A call to \fBTcl_FirstHashEntry\fR followed by calls to
 \fBTcl_NextHashEntry\fR will return each of the entries in
 the table exactly once, in an arbitrary order.
-It is unadvisable to modify the structure of the table, e.g.
-by creating or deleting entries, while the search is in
-progress.
+It is inadvisable to modify the structure of the table, e.g.
+by creating or deleting entries, while the search is in progress,
+with the exception of deleting the entry returned by
+\fBTcl_FirstHashEntry\fR or \fBTcl_NextHashEntry\fR.
 .PP
 \fBTcl_HashStats\fR returns a dynamically-allocated string with
 overall information about a hash table, such as the number of
@@ -228,10 +241,10 @@ to any of the fields of any of the hash-related data structures;
 use the procedures and macros defined here.
 .SH "THE TCL_HASHKEYTYPE STRUCTURE"
 .PP
-Extension writers can define new hash key types by defining four
-procedures, initializing a Tcl_HashKeyType structure to describe
-the type, and calling \fBTcl_InitCustomHashTable\fR.
-The \fBTcl_HashKeyType\fR structure is defined as follows:
+Extension writers can define new hash key types by defining four procedures,
+initializing a \fBTcl_HashKeyType\fR structure to describe the type, and
+calling \fBTcl_InitCustomHashTable\fR. The \fBTcl_HashKeyType\fR structure is
+defined as follows:
 .CS
 typedef struct Tcl_HashKeyType {
     int \fIversion\fR;
@@ -243,61 +256,71 @@ typedef struct Tcl_HashKeyType {
 } Tcl_HashKeyType;
 .CE
 .PP
-The \fIversion\fR member is the version of the table. If this
-structure is extended in future then the version can be used
-to distinguish between different structures. It should be set
-to \fBTCL_HASH_KEY_TYPE_VERSION\fR.
+The \fIversion\fR member is the version of the table. If this structure is
+extended in future then the version can be used to distinguish between
+different structures. It should be set to \fBTCL_HASH_KEY_TYPE_VERSION\fR.
 .PP
-The \fIflags\fR member is one or more of the following values OR'ed together:
+The \fIflags\fR member is 0 or one or more of the following values OR'ed
+together:
 .IP \fBTCL_HASH_KEY_RANDOMIZE_HASH\fR 25
-There are some things, pointers for example which don't hash well 
-because they do not use the lower bits. If this flag is set then the
-hash table will attempt to rectify this by randomising the bits and 
-then using the upper N bits as the index into the table.
+There are some things, pointers for example which do not hash well because
+they do not use the lower bits. If this flag is set then the hash table will
+attempt to rectify this by randomizing the bits and then using the upper N
+bits as the index into the table.
+.IP \fBTCL_HASH_KEY_SYSTEM_HASH\fR 25
+.VS 8.5
+This flag forces Tcl to use the memory allocation procedures provided by the
+operating system when allocating and freeing memory used to store the hash
+table data structures, and not any of Tcl's own customized memory allocation
+routines. This is important if the hash table is to be used in the
+implementation of a custom set of allocation routines, or something that a
+custom set of allocation routines might depend on, in order to avoid any
+circular dependency.
+.VE 8.5
 .PP
-The \fIhashKeyProc\fR member contains the address of a function 
-called to calculate a hash value for the key.
+The \fIhashKeyProc\fR member contains the address of a function called to
+calculate a hash value for the key.
 .CS
 typedef unsigned int (Tcl_HashKeyProc) (
-    Tcl_HashTable *\fItablePtr\fR,
-    VOID *\fIkeyPtr\fR);
+        Tcl_HashTable *\fItablePtr\fR,
+        void *\fIkeyPtr\fR);
 .CE
-If this is NULL then \fIkeyPtr\fR is used and 
+If this is NULL then \fIkeyPtr\fR is used and
 \fBTCL_HASH_KEY_RANDOMIZE_HASH\fR is assumed.
 .PP
-The \fIcompareKeysProc\fR member contains the address of a function 
-called to compare two keys.
+The \fIcompareKeysProc\fR member contains the address of a function called to
+compare two keys.
 .CS
-typedef int (Tcl_CompareHashKeysProc) (VOID *\fIkeyPtr\fR,
-    Tcl_HashEntry *\fIhPtr\fR);
+typedef int (Tcl_CompareHashKeysProc) (
+        void *\fIkeyPtr\fR,
+        Tcl_HashEntry *\fIhPtr\fR);
 .CE
-If this is NULL then the \fIkeyPtr\fR pointers are compared.
-If the keys don't match then the function returns 0, otherwise
-it returns 1.
+If this is NULL then the \fIkeyPtr\fR pointers are compared. If the keys do
+not match then the function returns 0, otherwise it returns 1.
 .PP
-The \fIallocEntryProc\fR member contains the address of a function 
-called to allocate space for an entry and initialise the key.
+The \fIallocEntryProc\fR member contains the address of a function called to
+allocate space for an entry and initialize the key and clientData.
 .CS
 typedef Tcl_HashEntry *(Tcl_AllocHashEntryProc) (
-    Tcl_HashTable *\fItablePtr\fR, VOID *\fIkeyPtr\fR);
+        Tcl_HashTable *\fItablePtr\fR,
+        void *\fIkeyPtr\fR);
 .CE
 If this is NULL then Tcl_Alloc is used to allocate enough space for a
-Tcl_HashEntry and the key pointer is assigned to key.oneWordValue.
-String keys and array keys use this function to allocate enough 
-space for the entry and the key in one block, rather than doing
-it in two blocks. This saves space for a pointer to the key from
-the entry and another memory allocation. Tcl_Obj * keys use this 
-function to allocate enough space for an entry and increment the 
-reference count on the object.
-If 
+Tcl_HashEntry, the key pointer is assigned to key.oneWordValue and the
+clientData is set to NULL. String keys and array keys use this function to
+allocate enough space for the entry and the key in one block, rather than
+doing it in two blocks. This saves space for a pointer to the key from the
+entry and another memory allocation. Tcl_Obj* keys use this function to
+allocate enough space for an entry and increment the reference count on the
+object.
 .PP
-The \fIfreeEntryProc\fR member contains the address of a function 
-called to free space for an entry.
+The \fIfreeEntryProc\fR member contains the address of a function called to
+free space for an entry.
 .CS
 typedef void (Tcl_FreeHashEntryProc) (Tcl_HashEntry *\fIhPtr\fR);
 .CE
-If this is NULL then Tcl_Free is used to free the space for the 
-entry. Tcl_Obj * keys use this function to decrement the
-reference count on the object.
+If this is NULL then Tcl_Free is used to free the space for the entry.
+Tcl_Obj* keys use this function to decrement the reference count on the
+object.
 .SH KEYWORDS
 hash table, key, lookup, search, value

doc/Init.3

@@ -14,15 +14,16 @@ Tcl_Init \- find and source initialization script
 int
 \fBTcl_Init\fR(\fIinterp\fR)
 .SH ARGUMENTS
+.AS Tcl_Interp *interp
 .AP Tcl_Interp *interp in
 Interpreter to initialize.
 .BE
 
 .SH DESCRIPTION
 .PP
-\fBTcl_Init\fR is a helper procedure that finds and \fBsource\fR's the
+\fBTcl_Init\fR is a helper procedure that finds and \fBsource\fRs the
 \fBinit.tcl\fR script, which should exist somewhere on the Tcl library
-path.  
+path.
 .PP
 \fBTcl_Init\fR is typically called from \fBTcl_AppInit\fR procedures.
 

doc/InitStubs.3

@@ -13,13 +13,13 @@ Tcl_InitStubs \- initialize the Tcl stubs mechanism
 .nf
 \fB#include <tcl.h>\fR
 .sp
-CONST char *
+const char *
 \fBTcl_InitStubs\fR(\fIinterp, version, exact\fR)
 .SH ARGUMENTS
-.AS Tcl_Interp *interp in
+.AS Tcl_Interp *interp
 .AP Tcl_Interp *interp in
 Tcl interpreter handle.
-.AP "CONST char" *version in
+.AP "const char" *version in
 A version string consisting of one or more decimal numbers
 separated by dots.
 .AP int exact in
@@ -59,13 +59,13 @@ steps:
 Call \fBTcl_InitStubs\fR in the extension before calling any other
 Tcl functions.
 .IP 2) 5
-Define the USE_TCL_STUBS symbol.  Typically, you would include the
--DUSE_TCL_STUBS flag when compiling the extension.
+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.  On Unix platforms, the library name is
-\fIlibtclstub8.4.a\fR; on Windows platforms, the library name is
-\fItclstub84.lib\fR.
+\fIlibtclstub8.5.a\fR; on Windows platforms, the library name is
+\fItclstub85.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/IntObj.3

@@ -5,10 +5,10 @@
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
 .so man.macros
-.TH Tcl_IntObj 3 8.0 Tcl "Tcl Library Procedures"
+.TH Tcl_IntObj 3 8.5 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, Tcl_GetIntFromObj, Tcl_GetLongFromObj, Tcl_GetWideIntFromObj \- manipulate Tcl objects as integers and wide integers
+Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, Tcl_GetIntFromObj, Tcl_GetLongFromObj, Tcl_GetWideIntFromObj, Tcl_NewBignumObj, Tcl_SetBignumObj, Tcl_GetBignumFromObj, Tcl_TakeBignumFromObj \- manipulate Tcl objects as integer values
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -19,18 +19,14 @@ Tcl_Obj *
 Tcl_Obj *
 \fBTcl_NewLongObj\fR(\fIlongValue\fR)
 .sp
-.VS 8.4
 Tcl_Obj *
 \fBTcl_NewWideIntObj\fR(\fIwideValue\fR)
-.VE 8.4
 .sp
 \fBTcl_SetIntObj\fR(\fIobjPtr, intValue\fR)
 .sp
 \fBTcl_SetLongObj\fR(\fIobjPtr, longValue\fR)
 .sp
-.VS 8.4
 \fBTcl_SetWideIntObj\fR(\fIobjPtr, wideValue\fR)
-.VE 8.4
 .sp
 int
 \fBTcl_GetIntFromObj\fR(\fIinterp, objPtr, intPtr\fR)
@@ -38,110 +34,127 @@ int
 int
 \fBTcl_GetLongFromObj\fR(\fIinterp, objPtr, longPtr\fR)
 .sp
-.VS 8.4
 int
 \fBTcl_GetWideIntFromObj\fR(\fIinterp, objPtr, widePtr\fR)
-.VE 8.4
+.sp
+.sp
+.VS 8.5
+\fB#include <tclTomMath.h>\fR
+.sp
+Tcl_Obj *
+\fBTcl_NewBignumObj\fR(\fIbigValue\fR)
+.sp
+\fBTcl_SetBignumObj\fR(\fIobjPtr, bigValue\fR)
+.sp
+int
+\fBTcl_GetBignumFromObj\fR(\fIinterp, objPtr, bigValue\fR)
+.sp
+int
+\fBTcl_TakeBignumFromObj\fR(\fIinterp, objPtr, bigValue\fR)
+.sp
+int
+\fBTcl_InitBignumFromDouble\fR(\fIinterp, doubleValue, bigValue\fR)
+.VE 8.5
 .SH ARGUMENTS
-.AS Tcl_WideInt *interp
+.AS Tcl_WideInt doubleValue in/out
 .AP int intValue in
-Integer value used to initialize or set an integer object.
+Integer value used to initialize or set a Tcl object.
 .AP long longValue in
-Long integer value used to initialize or set an integer object.
+Long integer value used to initialize or set a Tcl object.
 .AP Tcl_WideInt wideValue in
-.VS 8.4
-Wide integer value (minimum 64-bits wide where supported by the
-compiler) used to initialize or set a wide integer object.
-.VE 8.4
+Wide integer value used to initialize or set a Tcl object.
 .AP Tcl_Obj *objPtr in/out
-For \fBTcl_SetIntObj\fR, \fBTcl_SetLongObj\fR, and
-.VS 8.4
-\fBTcl_SetWideIntObj\fR, this points to the object to be converted to
-integer type.  For \fBTcl_GetIntFromObj\fR, \fBTcl_GetLongFromObj\fR,
-and \fBTcl_GetWideIntFromObj\fR, this refers to the object from which
-to get an integer or long integer value; if \fIobjPtr\fR does not
-already point to an integer object (or a wide integer object in the
-case of \fBTcl_SetWideIntObj\fR and \fBTcl_GetWideIntFromObj\fR,) an
-.VE 8.4
-attempt will be made to convert it to one.
+For \fBTcl_SetIntObj\fR, \fBTcl_SetLongObj\fR, \fBTcl_SetWideIntObj\fR,
+and \fBTcl_SetBignumObj\fR, this points to the object in which to store an
+integral value.  For \fBTcl_GetIntFromObj\fR, \fBTcl_GetLongFromObj\fR,
+\fBTcl_GetWideIntFromObj\fR, \fBTcl_GetBignumFromObj\fR, and
+\fBTcl_TakeBignumFromObj\fR, this refers to the object from which
+to retrieve an integral value.
 .AP Tcl_Interp *interp in/out
-If an error occurs during conversion,
-an error message is left in the interpreter's result object
-unless \fIinterp\fR is NULL.
+When non-NULL, an error message is left here when integral value
+retrieval fails.
 .AP int *intPtr out
-Points to place to store the integer value
-obtained by \fBTcl_GetIntFromObj\fR from \fIobjPtr\fR.
+Points to place to store the integer value retrieved from \fIobjPtr\fR.
 .AP long *longPtr out
-Points to place to store the long integer value
-obtained by \fBTcl_GetLongFromObj\fR from \fIobjPtr\fR.
+Points to place to store the long integer value retrieved from \fIobjPtr\fR.
 .AP Tcl_WideInt *widePtr out
-.VS 8.4
-Points to place to store the wide integer value
-obtained by \fBTcl_GetWideIntFromObj\fR from \fIobjPtr\fR.
-.VE 8.4
+Points to place to store the wide integer value retrieved from \fIobjPtr\fR.
+.AP mp_int *bigValue in/out
+.VS 8.5
+Points to a multi-precision integer structure declared by the LibTomMath
+library.
+.VE 8.5
+.AP double doubleValue in
+.VS 8.5
+Double value from which the integer part is determined and
+used to initialize a multi-precision integer value.
+.VE 8.5
 .BE
 
 .SH DESCRIPTION
 .PP
-These procedures are used to create, modify, and read
-integer and wide integer Tcl objects from C code.
-\fBTcl_NewIntObj\fR, \fBTcl_NewLongObj\fR,
-\fBTcl_SetIntObj\fR, and \fBTcl_SetLongObj\fR
-create a new object of integer type
-or modify an existing object to have integer type,
-.VS 8.4
-and \fBTcl_NewWideIntObj\fR and \fBTcl_SetWideIntObj\fR create a new
-object of wide integer type or modify an existing object to have wide
-integer type. 
-.VE 8.4
-\fBTcl_NewIntObj\fR and \fBTcl_SetIntObj\fR set the object to have the
-integer value given by \fIintValue\fR,
-\fBTcl_NewLongObj\fR and \fBTcl_SetLongObj\fR
-set the object to have the
-long integer value given by \fIlongValue\fR,
-.VS 8.4
-and \fBTcl_NewWideIntObj\fR and \fBTcl_SetWideIntObj\fR set the object
-to have the wide integer value given by \fIwideValue\fR.
-\fBTcl_NewIntObj\fR, \fBTcl_NewLongObj\fR and \fBTcl_NewWideIntObj\fR
-return a pointer to a newly created object with reference count zero.
-These procedures set the object's type to be integer
-and assign the integer value to the object's internal representation
-\fIlongValue\fR or \fIwideValue\fR member (as appropriate).
-\fBTcl_SetIntObj\fR, \fBTcl_SetLongObj\fR
-and \fBTcl_SetWideIntObj\fR
-.VE 8.4
-invalidate any old string representation and,
-if the object is not already an integer object,
-free any old internal representation.
+.VS 8.5
+These procedures are used to create, modify, and read Tcl objects
+that hold integral values.  
 .PP
-\fBTcl_GetIntFromObj\fR and \fBTcl_GetLongFromObj\fR
-attempt to return an integer value from the Tcl object \fIobjPtr\fR,
-.VS 8.4
-and \fBTcl_GetWideIntFromObj\fR attempts to return a wide integer
-value from the Tcl object \fIobjPtr\fR.
-If the object is not already an integer object,
-or a wide integer object in the case of \fBTcl_GetWideIntFromObj\fR
-.VE 8.4
-they will attempt to convert it to one.
-If an error occurs during conversion, they return \fBTCL_ERROR\fR
-and leave an error message in the interpreter's result object
-unless \fIinterp\fR is NULL.
-Also, if the long integer held in the object's internal representation
-\fIlongValue\fR member can not be represented in a (non-long) integer,
-\fBTcl_GetIntFromObj\fR returns \fBTCL_ERROR\fR
-and leaves an error message in the interpreter's result object
-unless \fIinterp\fR is NULL.
-Otherwise, all three procedures return \fBTCL_OK\fR and
-store the integer, long integer value
-.VS 8.4
-or wide integer in the address given by \fIintPtr\fR, \fIlongPtr\fR
-and \fIwidePtr\fR
-.VE 8.4
-respectively.  If the object is not already an integer or wide integer
-object, the conversion will free any old internal representation.
-
+The different routines exist to accommodate different integral types in C
+with which values might be exchanged.  The C integral types for which Tcl
+provides value exchange routines are \fBint\fR, \fBlong int\fR,
+\fBTcl_WideInt\fR, and \fBmp_int\fR.  The \fBint\fR and \fBlong int\fR types
+are provided by the C language standard.  The \fBTcl_WideInt\fR type is a
+typedef defined to be whatever signed integral type covers at least the
+64-bit integer range (-9223372036854775808 to 9223372036854775807).  Depending
+on the platform and the C compiler, the actual type might be
+\fBlong int\fR, \fBlong long int\fR, \fBint64\fR, or something else.
+The \fBmp_int\fR type is a multiple-precision integer type defined
+by the LibTomMath multiple-precision integer library.  
+.PP
+The \fBTcl_NewIntObj\fR, \fBTcl_NewLongObj\fR, \fBTcl_NewWideIntObj\fR,
+and \fBTcl_NewBignumObj\fR routines each create and return a new
+Tcl object initialized to the integral value of the argument.  The
+returned Tcl object is unshared.
+.PP
+The \fBTcl_SetIntObj\fR, \fBTcl_SetLongObj\fR, \fBTcl_SetWideIntObj\fR,
+and \fBTcl_SetBignumObj\fR routines each set the value of an existing
+Tcl object pointed to by \fIobjPtr\fR to the integral value provided
+by the other argument.  The \fIobjPtr\fR argument must point to an
+unshared Tcl object.  Any attempt to set the value of a shared Tcl object
+violates Tcl's copy-on-write policy.  Any existing string representation
+or internal representation in the unshared Tcl object will be freed
+as a consequence of setting the new value.
+.PP
+The \fBTcl_GetIntFromObj\fR, \fBTcl_GetLongFromObj\fR,
+\fBTcl_GetWideIntFromObj\fR, \fBTcl_GetBignumFromObj\fR, and
+\fBTcl_TakeBignumFromObj\fR routines attempt to retrieve an integral
+value of the appropriate type from the Tcl object \fIobjPtr\fR.  If the
+attempt succeeds, then \fBTCL_OK\fR is returned, and the value is
+written to the storage provided by the caller.  The attempt might
+fail if \fIobjPtr\fR does not hold an integral value, or if the
+value exceeds the range of the target type.  If the attempt fails,
+then \fBTCL_ERROR\fR is returned, and if \fIinterp\fR is non-NULL,
+an error message is left in \fIinterp\fR.  The \fBTcl_ObjType\fR
+of \fIobjPtr\fR may be changed to make subsequent calls to the
+same routine more efficient. Unlike the other functions,
+\fBTcl_TakeBignumFromObj\fR may set the content of the Tcl object
+\fIobjPtr\fR to an empty string in the process of retrieving the
+multiple-precision integer value.
+.PP
+The choice between \fBTcl_GetBignumFromObj\fR and
+\fBTcl_TakeBignumFromObj\fR is governed by how the caller will
+continue to use \fIobjPtr\fR.  If after the \fBmp_int\fR value
+is retrieved from \fIobjPtr\fR, the caller will make no more
+use of \fIobjPtr\fR, then using \fBTcl_TakeBignumFromObj\fR
+permits Tcl to detect when an unshared \fIobjPtr\fR permits the
+value to be moved instead of copied, which should be more efficient.
+If anything later in the caller requires
+\fIobjPtr\fR to continue to hold the same value, then
+\fBTcl_GetBignumFromObj\fR must be chosen.
+.PP
+The \fBTcl_InitBignumFromDouble\fR routine is a utility procedure
+that extracts the integer part of \fIdoubleValue\fR and stores that
+integer value in the \fBmp_int\fR value \fIbigValue\fR.
+.VE 8.5
 .SH "SEE ALSO"
 Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
-
 .SH KEYWORDS
 integer, integer object, integer type, internal representation, object, object type, string representation

doc/Interp.3

@@ -15,9 +15,9 @@ Tcl_Interp \- client-visible fields of interpreter structures
 \fB#include <tcl.h>\fR
 .sp
 typedef struct {
-	char *\fIresult\fR;
-	Tcl_FreeProc *\fIfreeProc\fR;
-	int \fIerrorLine\fR;
+        char *\fIresult\fR;
+        Tcl_FreeProc *\fIfreeProc\fR;
+        int \fIerrorLine\fR;
 } Tcl_Interp;
 
 typedef void Tcl_FreeProc(char *\fIblockPtr\fR);
@@ -28,17 +28,23 @@ typedef void Tcl_FreeProc(char *\fIblockPtr\fR);
 The \fBTcl_CreateInterp\fR procedure returns a pointer to a Tcl_Interp
 structure.  This pointer is then passed into other Tcl procedures
 to process commands in the interpreter and perform other operations
-on the interpreter.  Interpreter structures contain many many fields
+on the interpreter.  Interpreter structures contain many fields
 that are used by Tcl, but only three that may be accessed by
 clients:  \fIresult\fR, \fIfreeProc\fR, and \fIerrorLine\fR.
 .PP
+.VS 8.5
+\fBNote that access to all three fields, \fIresult\fB, \fIfreeProc\fB and
+\fIerrorLine\fB is deprecated.\fR  Use \fBTcl_SetResult\fR,
+\fBTcl_GetResult\fR, and \fBTcl_GetReturnOptions\fR instead.
+.VE 8.5
+.PP
 The \fIresult\fR and \fIfreeProc\fR fields are used to return
 results or error messages from commands.
 This information is returned by command procedures back to \fBTcl_Eval\fR,
 and by \fBTcl_Eval\fR back to its callers.
 The \fIresult\fR field points to the string that represents the
 result or error message, and the \fIfreeProc\fR field tells how
-to dispose of the storage for the string when it isn't needed anymore.
+to dispose of the storage for the string when it is not needed anymore.
 The easiest way for command procedures to manipulate these
 fields is to call procedures like \fBTcl_SetResult\fR
 or \fBTcl_AppendResult\fR;  they
@@ -55,7 +61,6 @@ should point to an empty string.
 Normally, results are assumed to be statically allocated,
 which means that the contents will not change before the next time
 \fBTcl_Eval\fR is called or some other command procedure is invoked.
-.VS
 In this case, the \fIfreeProc\fR field must be zero.
 Alternatively, a command procedure may dynamically
 allocate its return value (e.g. using \fBTcl_Alloc\fR)
@@ -64,7 +69,6 @@ In this case, the command procedure must also set \fIinterp->freeProc\fR
 to the address of a procedure that can free the value, or \fBTCL_DYNAMIC\fR
 if the storage was allocated directly by Tcl or by a call to
 \fBTcl_Alloc\fR. 
-.VE
 If \fIinterp->freeProc\fR is non-zero, then Tcl will call \fIfreeProc\fR
 to free the space pointed to by \fIinterp->result\fR before it
 invokes the next command.
@@ -76,10 +80,8 @@ macro should be used for this purpose).
 \fIFreeProc\fR should have arguments and result that match the
 \fBTcl_FreeProc\fR declaration above:  it receives a single
 argument which is a pointer to the result value to free.
-.VS
 In most applications \fBTCL_DYNAMIC\fR is the only non-zero value ever
 used for \fIfreeProc\fR.
-.VE
 However, an application may store a different procedure address
 in \fIfreeProc\fR in order to use an alternate memory allocator
 or in order to do other cleanup when the result memory is freed.

doc/Limit.3

@@ -0,0 +1,194 @@
+'\"
+'\" Copyright (c) 2004 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.so man.macros
+.TH Tcl_LimitCheck 3 8.5 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_LimitAddHandler, Tcl_LimitCheck, Tcl_LimitExceeded, Tcl_LimitGetCommands, Tcl_LimitGetGranularity, Tcl_LimitGetTime, Tcl_LimitReady, Tcl_LimitRemoveHandler, Tcl_LimitSetCommands, Tcl_LimitSetGranularity, Tcl_LimitSetTime, Tcl_LimitTypeEnabled, Tcl_LimitTypeExceeded, Tcl_LimitTypeReset, Tcl_LimitTypeSet \- manage and check resource limits on interpreters
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+int
+\fBTcl_LimitCheck\fR(\fIinterp\fR)
+.sp
+int
+\fBTcl_LimitReady\fR(\fIinterp\fR)
+.sp
+int
+\fBTcl_LimitExceeded\fR(\fIinterp\fR)
+.sp
+int
+\fBTcl_LimitTypeExceeded\fR(\fIinterp, type\fR)
+.sp
+int
+\fBTcl_LimitTypeEnabled\fR(\fIinterp, type\fR)
+.sp
+void
+\fBTcl_LimitTypeSet\fR(\fIinterp, type\fR)
+.sp
+void
+\fBTcl_LimitTypeReset\fR(\fIinterp, type\fR)
+.sp
+int
+\fBTcl_LimitGetCommands\fR(\fIinterp\fR)
+.sp
+void
+\fBTcl_LimitSetCommands\fR(\fIinterp, commandLimit\fR)
+.sp
+void
+\fBTcl_LimitGetTime\fR(\fIinterp, timeLimitPtr\fR)
+.sp
+void
+\fBTcl_LimitSetTime\fR(\fIinterp, timeLimitPtr\fR)
+.sp
+int
+\fBTcl_LimitGetGranularity\fR(\fIinterp, type\fR)
+.sp
+void
+\fBTcl_LimitSetGranularity\fR(\fIinterp, type, granularity\fR)
+.sp
+void
+\fBTcl_LimitAddHandler\fR(\fIinterp, type, handlerProc, clientData, deleteProc\fR)
+.sp
+void
+\fBTcl_LimitRemoveHandler\fR(\fIinterp, type, handlerProc, clientData\fR)
+.SH ARGUMENTS
+.AS Tcl_LimitHandlerDeleteProc commandLimit in/out
+.AP Tcl_Interp *interp in
+Interpreter that the limit being managed applies to or that will have
+its limits checked.
+.AP int type in
+The type of limit that the operation refers to.  This must be either
+\fBTCL_LIMIT_COMMANDS\fR or \fBTCL_LIMIT_TIME\fR.
+.AP int commandLimit in
+The maximum number of commands (as reported by \fBinfo cmdcount\fR)
+that may be executed in the interpreter.
+.AP Tcl_Time *timeLimitPtr in/out
+A pointer to a structure that will either have the new time limit read
+from (\fBTcl_LimitSetTime\fR) or the current time limit written to
+(\fBTcl_LimitGetTime\fR).
+.AP int granularity in
+Divisor that indicates how often a particular limit should really be
+checked.  Must be at least 1.
+.AP Tcl_LimitHandlerProc *handlerProc in
+Function to call when a particular limit is exceeded.  If the
+\fIhandlerProc\fR removes or raises the limit during its processing,
+the limited interpreter will be permitted to continue to process after
+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
+Arbitrary pointer-sized word used to pass some context to the
+\fIhandlerProc\fR function.
+.AP Tcl_LimitHandlerDeleteProc *deleteProc in
+Function to call whenever a handler is deleted.  May be NULL if the
+\fIclientData\fR requires no deletion.
+.BE
+
+.SH DESCRIPTION
+.PP
+Tcl's interpreter resource limit subsystem allows for close control
+over how much computation time a script may use, and is useful for
+cases where a program is divided into multiple pieces where some parts
+are more trusted than others (e.g. web application servers).
+.PP
+Every interpreter may have a limit on the wall-time for execution, and
+a limit on the number of commands that the interpreter may execute.
+Since checking of these limits is potentially expensive (especially
+the time limit), each limit also has a checking granularity, which is
+a divisor for an internal count of the number of points in the core
+where a check may be performed (which is immediately before executing
+a command and at an unspecified frequency between running commands,
+which can happen in empty-bodied \fBwhile\fR loops).
+.PP
+The final component of the limit engine is a callback scheme which
+allows for notifications of when a limit has been exceeded.  These
+callbacks can just provide logging, or may allocate more resources to
+the interpreter to permit it to continue processing longer.
+.PP
+When a limit is exceeded (and the callbacks have run; the order of
+execution of the callbacks is unspecified) execution in the limited
+interpreter is stopped by raising an error and setting a flag that
+prevents the \fBcatch\fR command in that interpreter from trapping
+that error.  It is up to the context that started execution in that
+interpreter (typically a master interpreter) to handle the error.
+.SH "LIMIT CHECKING API"
+.PP
+To check the resource limits for an interpreter, call
+\fBTcl_LimitCheck\fR, which returns \fBTCL_OK\fR if the limit was not
+exceeded (after processing callbacks) and \fBTCL_ERROR\fR if the limit was
+exceeded (in which case an error message is also placed in the
+interpreter result).  That function should only be called when
+\fBTcl_LimitReady\fR returns non-zero so that granularity policy is
+enforced.  This API is designed to be similar in usage to
+\fBTcl_AsyncReady\fR and \fBTcl_AsyncInvoke\fR.
+.PP
+When writing code that may behave like \fBcatch\fR in respect of
+errors, you should only trap an error if \fBTcl_LimitExceeded\fR
+returns zero.  If it returns non-zero, the interpreter is in a
+limit-exceeded state and errors should be allowed to propagate to the
+calling context.  You can also check whether a particular type of
+limit has been exceeded using \fBTcl_LimitTypeExceeded\fR.
+.SH "LIMIT CONFIGURATION"
+.PP
+To check whether a limit has been set (but not whether it has actually
+been exceeded) on an interpreter, call \fBTcl_LimitTypeEnabled\fR with
+the type of limit you want to check.  To enable a particular limit
+call \fBTcl_LimitTypeSet\fR, and to disable a limit call
+\fBTcl_LimitTypeReset\fR.
+.PP
+The level of a command limit may be set using
+\fBTcl_LimitSetCommands\fR, and retrieved using
+\fBTcl_LimitGetCommands\fR.  Similarly for a time limit with
+\fBTcl_LimitSetTime\fR and \fBTcl_LimitGetTime\fR respectively, but
+with that API the time limit is copied from and to the Tcl_Time
+structure that the \fItimeLimitPtr\fR argument points to.
+.PP
+The checking granularity for a particular limit may be set using
+\fBTcl_LimitSetGranularity\fR and retrieved using
+\fBTcl_LimitGetGranularity\fR.  Note that granularities must always be
+positive.
+.SS "LIMIT CALLBACKS"
+.PP
+To add a handler callback to be invoked when a limit is exceeded, call
+\fBTcl_LimitAddHandler\fR.  The \fIhandlerProc\fR argument describes
+the function that will actually be called; it should have the
+following prototype:
+.PP
+.CS
+typedef void Tcl_LimitHandlerProc(
+        ClientData \fIclientData\fR,
+        Tcl_Interp *\fIinterp\fR);
+.CE
+.PP
+The \fIclientData\fR argument to the handler will be whatever is
+passed to the \fIclientData\fR argument to \fBTcl_LimitAddHandler\fR,
+and the \fIinterp\fR is the interpreter that had its limit exceeded.
+.PP
+The \fIdeleteProc\fR argument to \fBTcl_LimitAddHandler\fR is a
+function to call to delete the \fIclientData\fR value.  It may be
+\fBTCL_STATIC\fR or NULL if no deletion action is necessary, or
+\fBTCL_DYNAMIC\fR if all that is necessary is to free the structure with
+\fBTcl_Free\fR.  Otherwise, it should refer to a function with the
+following prototype:
+.PP
+.CS
+typedef void Tcl_LimitHandlerDeleteProc(
+        ClientData \fIclientData\fR);
+.CE
+.PP
+A limit handler may be deleted using \fBTcl_LimitRemoveHandler\fR; the
+handler removed will be the first one found (out of the handlers added
+with \fBTcl_LimitAddHandler\fR) with exactly matching \fItype\fR,
+\fIhandlerProc\fR and \fIclientData\fR arguments.  This function
+always invokes the \fIdeleteProc\fR on the \fIclientData\fR (unless
+the \fIdeleteProc\fR was NULL or \fBTCL_STATIC\fR).
+
+.SH KEYWORDS
+interpreter, resource, limit, commands, time, callback

doc/LinkVar.3

@@ -25,17 +25,24 @@ int
 .AP Tcl_Interp *interp in
 Interpreter that contains \fIvarName\fR.
 Also used by \fBTcl_LinkVar\fR to return error messages.
-.AP "CONST char" *varName in
-Name of global variable.  
+.AP "const char" *varName in
+Name of global variable.
 .AP char *addr in
 Address of C variable that is to be linked to \fIvarName\fR.
 .AP int type in
-Type of C variable.  Must be one of TCL_LINK_INT, TCL_LINK_DOUBLE,
-.VS 8.4
-TCL_LINK_WIDE_INT,
-.VE 8.4
-TCL_LINK_BOOLEAN, or TCL_LINK_STRING, optionally OR'ed with
-TCL_LINK_READ_ONLY to make Tcl variable read-only.
+Type of C variable.  Must be one of \fBTCL_LINK_INT\fR,
+.VS 8.5
+\fBTCL_LINK_UINT\fR, \fBTCL_LINK_CHAR\fR, \fBTCL_LINK_UCHAR\fR,
+\fBTCL_LINK_SHORT\fR, \fBTCL_LINK_USHORT\fR, \fBTCL_LINK_LONG\fR,
+\fBTCL_LINK_ULONG\fR,
+.VE 8.5
+\fBTCL_LINK_WIDE_INT\fR,
+.VS 8.5
+\fBTCL_LINK_WIDE_UINT\fR, \fBTCL_LINK_FLOAT\fR,
+.VE 8.5
+\fBTCL_LINK_DOUBLE\fR, \fBTCL_LINK_BOOLEAN\fR, or
+\fBTCL_LINK_STRING\fR, optionally OR'ed with \fBTCL_LINK_READ_ONLY\fR
+to make Tcl variable read-only.
 .BE
 
 .SH DESCRIPTION
@@ -46,14 +53,14 @@ given by \fIaddr\fR.
 Whenever the Tcl variable is read the value of the C variable will
 be returned, and whenever the Tcl variable is written the C
 variable will be updated to have the same value.
-\fBTcl_LinkVar\fR normally returns TCL_OK;  if an error occurs
+\fBTcl_LinkVar\fR normally returns \fBTCL_OK\fR;  if an error occurs
 while setting up the link (e.g. because \fIvarName\fR is the
-name of array) then TCL_ERROR is returned and the interpreter's result
+name of array) then \fBTCL_ERROR\fR is returned and the interpreter's result
 contains an error message.
 .PP
 The \fItype\fR argument specifies the type of the C variable,
 and must have one of the following values, optionally OR'ed with
-TCL_LINK_READ_ONLY:
+\fBTCL_LINK_READ_ONLY\fR:
 .TP
 \fBTCL_LINK_INT\fR
 The C variable is of type \fBint\fR.
@@ -61,6 +68,61 @@ Any value written into the Tcl variable must have a proper integer
 form acceptable to \fBTcl_GetIntFromObj\fR;  attempts to write
 non-integer values into \fIvarName\fR will be rejected with
 Tcl errors.
+.VS 8.5
+.TP
+\fBTCL_LINK_UINT\fR
+The C variable is of type \fBunsigned int\fR.
+Any value written into the Tcl variable must have a proper unsigned
+integer form acceptable to \fBTcl_GetWideIntFromObj\fR and in the
+platform's defined range for the \fBunsigned int\fR type; attempts to
+write non-integer values (or values outside the range) into
+\fIvarName\fR will be rejected with Tcl errors.
+.TP
+\fBTCL_LINK_CHAR\fR
+The C variable is of type \fBchar\fR.
+Any value written into the Tcl variable must have a proper integer
+form acceptable to \fBTcl_GetIntFromObj\fR and be in the range of the
+\fBchar\fR datatype; attempts to write non-integer or out-of-range
+values into \fIvarName\fR will be rejected with Tcl errors.
+.TP
+\fBTCL_LINK_UCHAR\fR
+The C variable is of type \fBunsigned char\fR.
+Any value written into the Tcl variable must have a proper unsigned
+integer form acceptable to \fBTcl_GetIntFromObj\fR and in the
+platform's defined range for the \fBunsigned char\fR type; attempts to
+write non-integer values (or values outside the range) into
+\fIvarName\fR will be rejected with Tcl errors.
+.TP
+\fBTCL_LINK_SHORT\fR
+The C variable is of type \fBshort\fR.
+Any value written into the Tcl variable must have a proper integer
+form acceptable to \fBTcl_GetIntFromObj\fR and be in the range of the
+\fBshort\fR datatype; attempts to write non-integer or out-of-range
+values into \fIvarName\fR will be rejected with Tcl errors.
+.TP
+\fBTCL_LINK_USHORT\fR
+The C variable is of type \fBunsigned short\fR.
+Any value written into the Tcl variable must have a proper unsigned
+integer form acceptable to \fBTcl_GetIntFromObj\fR and in the
+platform's defined range for the \fBunsigned short\fR type; attempts to
+write non-integer values (or values outside the range) into
+\fIvarName\fR will be rejected with Tcl errors.
+.TP
+\fBTCL_LINK_LONG\fR
+The C variable is of type \fBlong\fR.
+Any value written into the Tcl variable must have a proper integer
+form acceptable to \fBTcl_GetLongFromObj\fR; attempts to write
+non-integer or out-of-range
+values into \fIvarName\fR will be rejected with Tcl errors.
+.TP
+\fBTCL_LINK_ULONG\fR
+The C variable is of type \fBunsigned long\fR.
+Any value written into the Tcl variable must have a proper unsigned
+integer form acceptable to \fBTcl_GetWideIntFromObj\fR and in the
+platform's defined range for the \fBunsigned long\fR type; attempts to
+write non-integer values (or values outside the range) into
+\fIvarName\fR will be rejected with Tcl errors.
+.VE 8.5
 .TP
 \fBTCL_LINK_DOUBLE\fR
 The C variable is of type \fBdouble\fR.
@@ -68,21 +130,44 @@ Any value written into the Tcl variable must have a proper real
 form acceptable to \fBTcl_GetDoubleFromObj\fR;  attempts to write
 non-real values into \fIvarName\fR will be rejected with
 Tcl errors.
+.VS 8.5
+.TP
+\fBTCL_LINK_FLOAT\fR
+The C variable is of type \fBfloat\fR.
+Any value written into the Tcl variable must have a proper real
+form acceptable to \fBTcl_GetDoubleFromObj\fR and must be within the
+range acceptable for a \fBfloat\fR; attempts to
+write non-real values (or values outside the range) into
+\fIvarName\fR will be rejected with Tcl errors.
+.VE 8.5
 .TP
 \fBTCL_LINK_WIDE_INT\fR
-.VS 8.4
 The C variable is of type \fBTcl_WideInt\fR (which is an integer type
 at least 64-bits wide on all platforms that can support it.)
 Any value written into the Tcl variable must have a proper integer
 form acceptable to \fBTcl_GetWideIntFromObj\fR;  attempts to write
 non-integer values into \fIvarName\fR will be rejected with
 Tcl errors.
-.VE 8.4
+.VS 8.5
+.TP
+\fBTCL_LINK_WIDE_UINT\fR
+The C variable is of type \fBTcl_WideUInt\fR (which is an unsigned
+integer type at least 64-bits wide on all platforms that can support
+it.)
+Any value written into the Tcl variable must have a proper unsigned
+integer form acceptable to \fBTcl_GetWideIntFromObj\fR (it will be
+cast to unsigned);
+.\" FIXME! Use bignums instead.
+attempts to write non-integer values into \fIvarName\fR will be
+rejected with Tcl errors.
+.VE 8.5
 .TP
 \fBTCL_LINK_BOOLEAN\fR
 The C variable is of type \fBint\fR.
-If its value is zero then it will read from Tcl as ``0'';
-otherwise it will read from Tcl as ``1''.
+If its value is zero then it will read from Tcl as
+.QW 0 ;
+otherwise it will read from Tcl as
+.QW 1 .
 Whenever \fIvarName\fR is
 modified, the C variable will be set to a 0 or 1 value.
 Any value written into the Tcl variable must have a proper boolean
@@ -92,17 +177,16 @@ Tcl errors.
 .TP
 \fBTCL_LINK_STRING\fR
 The C variable is of type \fBchar *\fR.
-.VS
 If its value is not NULL then it must be a pointer to a string
 allocated with \fBTcl_Alloc\fR or \fBckalloc\fR.
-.VE
 Whenever the Tcl variable is modified the current C string will be
 freed and new memory will be allocated to hold a copy of the variable's
 new value.
 If the C variable contains a NULL pointer then the Tcl variable
-will read as ``NULL''.
+will read as
+.QW NULL .
 .PP
-If the TCL_LINK_READ_ONLY flag is present in \fItype\fR then the
+If the \fBTCL_LINK_READ_ONLY\fR flag is present in \fItype\fR then the
 variable will be read-only from Tcl, so that its value can only be
 changed by modifying the C variable.
 Attempts to write the variable from Tcl will be rejected with errors.

doc/ListObj.3

@@ -36,7 +36,7 @@ int
 int
 \fBTcl_ListObjReplace\fR(\fIinterp, listPtr, first, count, objc, objv\fR)
 .SH ARGUMENTS
-.AS Tcl_Interp "*CONST objv[]" out
+.AS "Tcl_Obj *const" *elemListPtr in/out
 .AP Tcl_Interp *interp in
 If an error occurs while converting an object to be a list object,
 an error message is left in the interpreter's result object
@@ -71,13 +71,11 @@ will insert into a new list object,
 and \fBTcl_ListObjReplace\fR will insert into \fIlistPtr\fR.
 For \fBTcl_SetListObj\fR,
 the number of Tcl objects to insert into \fIobjPtr\fR.
-.VS
-.AP Tcl_Obj	"*CONST\ objv[]" in
+.AP "Tcl_Obj *const" objv[] in
 An array of pointers to objects.
 \fBTcl_NewListObj\fR will insert these objects into a new list object
 and \fBTcl_ListObjReplace\fR will insert them into an existing \fIlistPtr\fR.
 Each object will become a separate list element.  
-.VE
 .AP int *intPtr out
 Points to location where \fBTcl_ListObjLength\fR
 stores the length of the list.
@@ -151,8 +149,9 @@ has reference count zero.
 the elements in a list object.  It returns the count by storing it in the
 address \fIobjcPtr\fR.  Similarly, it returns the array pointer by storing
 it in the address \fIobjvPtr\fR.
-The memory pointed to is managed by Tcl and should not be freed by the
-caller.
+The memory pointed to is managed by Tcl and should not be freed or written
+to by the caller. If the list is empty, 0 is stored at \fIobjcPtr\fR
+and NULL at \fIobjvPtr\fR.
 If \fIlistPtr\fR is not already a list object, \fBTcl_ListObjGetElements\fR
 will attempt to convert it to one; if the conversion fails, it returns
 \fBTCL_ERROR\fR and leaves an error message in the interpreter's result
@@ -219,27 +218,33 @@ it can be used to implement a number of list operations.
 For example, the following code inserts the \fIobjc\fR objects
 referenced by the array of object pointers \fIobjv\fR
 just before the element \fIindex\fR of the list referenced by \fIlistPtr\fR:
+.PP
 .CS
-result = Tcl_ListObjReplace(interp, listPtr, index, 0, objc, objv);
+result = Tcl_ListObjReplace(interp, listPtr, index, 0,
+        objc, objv);
 .CE
+.PP
 Similarly, the following code appends the \fIobjc\fR objects
 referenced by the array \fIobjv\fR
 to the end of the list \fIlistPtr\fR:
+.PP
 .CS
 result = Tcl_ListObjLength(interp, listPtr, &length);
 if (result == TCL_OK) {
-	result = Tcl_ListObjReplace(interp, listPtr, length, 0, objc, objv);
+    result = Tcl_ListObjReplace(interp, listPtr, length, 0,
+            objc, objv);
 }
 .CE
+.PP
 The \fIcount\fR list elements starting at \fIfirst\fR can be deleted
 by simply calling \fBTcl_ListObjReplace\fR
 with a NULL \fIobjvPtr\fR:
+.PP
 .CS
-result = Tcl_ListObjReplace(interp, listPtr, first, count, 0, NULL);
+result = Tcl_ListObjReplace(interp, listPtr, first, count,
+        0, NULL);
 .CE
-
 .SH "SEE ALSO"
 Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
-
 .SH KEYWORDS
 append, index, insert, internal representation, length, list, list object, list type, object, object type, replace, string representation

doc/Namespace.3

@@ -0,0 +1,165 @@
+'\"
+'\" Copyright (c) 2003 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+'\" Note that some of these functions do not seem to belong, but they
+'\" were all introduced with the same TIP (#139)
+'\" 
+.so man.macros
+.TH Tcl_Namespace 3 8.5 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_AppendExportList, Tcl_CreateNamespace, Tcl_DeleteNamespace, Tcl_Export, Tcl_FindCommand, Tcl_FindNamespace, Tcl_ForgetImport, Tcl_GetCurrentNamespace, Tcl_GetGlobalNamespace, Tcl_GetNamespaceUnknownHandler, Tcl_Import, Tcl_SetNamespaceUnknownHandler \- manipulate namespaces
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+Tcl_Namespace *
+\fBTcl_CreateNamespace\fR(\fIinterp, name, clientData, deleteProc\fR)
+.sp
+\fBTcl_DeleteNamespace\fR(\fInsPtr\fR)
+.sp
+int
+\fBTcl_AppendExportList\fR(\fIinterp, nsPtr, objPtr\fR)
+.sp
+int
+\fBTcl_Export\fR(\fIinterp, nsPtr, pattern, resetListFirst\fR)
+.sp
+int
+\fBTcl_Import\fR(\fIinterp, nsPtr, pattern, allowOverwrite\fR)
+.sp
+int
+\fBTcl_ForgetImport\fR(\fIinterp, nsPtr, pattern\fR)
+.sp
+Tcl_Namespace *
+\fBTcl_GetCurrentNamespace\fR(\fIinterp\fR)
+.sp
+Tcl_Namespace *
+\fBTcl_GetGlobalNamespace\fR(\fIinterp\fR)
+.sp
+Tcl_Namespace *
+\fBTcl_FindNamespace\fR(\fIinterp, name, contextNsPtr, flags\fR)
+.sp
+Tcl_Command
+\fBTcl_FindCommand\fR(\fIinterp, name, contextNsPtr, flags\fR)
+.sp
+Tcl_Obj *
+\fBTcl_GetNamespaceUnknownHandler(\fIinterp, nsPtr\fR)
+.sp
+int
+\fBTcl_SetNamespaceUnknownHandler(\fIinterp, nsPtr, handlerPtr\fR)
+.SH ARGUMENTS
+.AS Tcl_NamespaceDeleteProc allowOverwrite in/out
+.AP Tcl_Interp *interp in/out
+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
+A context pointer by the creator of the namespace.  Not interpreted by
+Tcl at all.
+.AP Tcl_NamespaceDeleteProc *deleteProc in
+A pointer to function to call when the namespace is deleted, or NULL
+if no such callback is to be performed.
+.AP Tcl_Namespace *nsPtr in
+The namespace to be manipulated, or NULL (for other than
+\fBTcl_DeleteNamespace\fR) to manipulate the current namespace.
+.AP Tcl_Obj *objPtr out
+A reference to an unshared object to which the function output will be
+written.
+.AP "const char" *pattern in
+The glob-style pattern (see \fBTcl_StringMatch\fR) that describes the
+commands to be imported or exported.
+.AP int resetListFirst in
+Whether the list of export patterns should be reset before adding the
+current pattern to it.
+.AP int allowOverwrite in
+Whether new commands created by this import action can overwrite
+existing commands.
+.AP Tcl_Namespace *contextNsPtr in
+The location in the namespace hierarchy where the search for a
+namespace or command should be conducted relative to when the search
+term is not rooted at the global namespace.  NULL indicates the
+current namespace.
+.AP int flags in
+OR-ed combination of bits controlling how the search is to be
+performed.  The following flags are supported: \fBTCL_GLOBAL_ONLY\fR
+(indicates that the search is always to be conducted relative to the
+global namespace), \fBTCL_NAMESPACE_ONLY\fR (just for \fBTcl_FindCommand\fR;
+indicates that the search is always to be conducted relative to the
+context namespace), and \fBTCL_LEAVE_ERR_MSG\fR (indicates that an error
+message should be left in the interpreter if the search fails.)
+.AP Tcl_Obj *handlerPtr in
+A script fragment to be installed as the unknown command handler for the
+namespace, or NULL to reset the handler to its default.
+.BE
+
+.SH DESCRIPTION
+.PP
+Namespaces are hierarchic naming contexts that can contain commands
+and variables.  They also maintain a list of patterns that describes
+what commands are exported, and can import commands that have been
+exported by other namespaces.  Namespaces can also be manipulated
+through the Tcl command \fBnamespace\fR.
+.PP
+The \fITcl_Namespace\fR structure encapsulates a namespace, and is
+guaranteed to have the following fields in it: \fIname\fR (the local
+name of the namespace, with no namespace separator characters in it,
+with empty denoting the global namespace), \fIfullName\fR (the fully
+specified name of the namespace), \fIclientData\fR, \fIdeleteProc\fR
+(the values specified in the call to \fBTcl_CreateNamespace\fR), and
+\fIparentPtr\fR (a pointer to the containing namespace, or NULL for
+the global namespace.)
+.PP
+\fBTcl_CreateNamespace\fR creates a new namespace.  The
+\fIdeleteProc\fR will have the following type signature:
+.CS
+typedef void (Tcl_NamespaceDeleteProc) (ClientData clientData);
+.CE
+.PP
+\fBTcl_DeleteNamespace\fR deletes a namespace.
+.PP
+\fBTcl_AppendExportList\fR retrieves the export patterns for a
+namespace given namespace and appends them (as list items) to
+\fIobjPtr\fR.
+.PP
+\fBTcl_Export\fR sets and appends to the export patterns for a
+namespace.  Patterns are appended unless the \fIresetListFirst\fR flag
+is true.
+.PP
+\fBTcl_Import\fR imports commands matching a pattern into a
+namespace.  Note that the pattern must include the name of the
+namespace to import from.  This function returns an error if
+an attempt to import a command over an existing command is made,
+unless the \fIallowOverwrite\fR flag has been set.
+.PP
+\fBTcl_ForgetImport\fR removes imports matching a pattern.
+.PP
+\fBTcl_GetCurrentNamespace\fR returns the current namespace for an
+interpreter.
+.PP
+\fBTcl_GetGlobalNamespace\fR returns the global namespace for an
+interpreter.
+.PP
+\fBTcl_FindNamespace\fR searches for a namespace named \fIname\fR
+within the context of the namespace \fIcontextNsPtr\fR.  If the
+namespace cannot be found, NULL is returned.
+.PP
+\fBTcl_FindCommand\fR searches for a command named \fIname\fR within
+the context of the namespace \fIcontextNsPtr\fR.  If the command
+cannot be found, NULL is returned.
+.PP
+\fBTcl_GetNamespaceUnknownHandler\fR returns the unknown command handler
+for the namespace, or NULL if none is set.
+.PP
+\fBTcl_SetNamespaceUnknownHandler\fR sets the unknown command handler for
+the namespace. If \fIhandlerPtr\fR is NULL, then the handler is reset to
+its default.
+
+.SH "SEE ALSO"
+Tcl_CreateCommand, Tcl_ListObjAppendElements, Tcl_SetVar
+
+.SH KEYWORDS
+namespace, command

doc/Notifier.3

@@ -25,7 +25,6 @@ void
 .sp
 void
 \fBTcl_QueueEvent\fR(\fIevPtr, position\fR)
-.VS 8.1
 .sp
 void
 \fBTcl_ThreadQueueEvent\fR(\fIthreadId, evPtr, position\fR)
@@ -63,12 +62,16 @@ int
 int
 \fBTcl_GetServiceMode\fR()
 .sp
-int		
+int
 \fBTcl_SetServiceMode\fR(\fImode\fR)
-.VE
-
+.sp
+void
+\fBTcl_ServiceModeHook\fR(\fImode\fR)
+.sp
+void
+\fBTcl_SetNotifier\fR(\fInotifierProcPtr\fR)
 .SH ARGUMENTS
-.AS Tcl_EventDeleteProc milliseconds
+.AS Tcl_EventDeleteProc *notifierProcPtr
 .AP Tcl_EventSetupProc *setupProc in
 Procedure to invoke to prepare for event wait in \fBTcl_DoOneEvent\fR.
 .AP Tcl_EventCheckProc *checkProc in
@@ -97,11 +100,13 @@ Procedure to invoke for each queued event in \fBTcl_DeleteEvents\fR.
 .AP int flags in
 What types of events to service.  These flags are the same as those
 passed to \fBTcl_DoOneEvent\fR.
-.VS 8.1
 .AP int mode in
 Indicates whether events should be serviced by \fBTcl_ServiceAll\fR.
 Must be one of \fBTCL_SERVICE_NONE\fR or \fBTCL_SERVICE_ALL\fR.
-.VE
+.AP Tcl_NotifierProcs* notifierProcPtr in
+Structure of function pointers describing notifier procedures that are
+to replace the ones installed in the executable.  See
+\fBREPLACING THE NOTIFIER\fR for details.
 .BE
 
 .SH INTRODUCTION
@@ -135,9 +140,7 @@ sources place events onto the queue so that they may be processed in
 order at appropriate times during the event loop. The event queue
 guarantees a fair discipline of event handling, so that no event
 source can starve the others.  It also allows events to be saved for
-servicing at a future time.
-.VS 8.1
-Threaded applications work in a
+servicing at a future time.  Threaded applications work in a
 similar manner, except that there is a separate event queue for
 each thread containing a Tcl interpreter.
 \fBTcl_QueueEvent\fR is used (primarily
@@ -169,7 +172,6 @@ The procedures \fBTcl_ServiceAll\fR, \fBTcl_ServiceEvent\fR,
 to help connect Tcl's event loop to an external event loop such as
 Motif's.
 .SH "NOTIFIER BASICS"
-.VE
 .PP
 The easiest way to understand how the notifier works is to consider
 what happens when \fBTcl_DoOneEvent\fR is called.
@@ -180,17 +182,13 @@ things:
 .IP [1]
 Check the event queue to see if it contains any events that can
 be serviced.  If so, service the first possible event, remove it
-.VS 8.1
 from the queue, and return.  It does this by calling
 \fBTcl_ServiceEvent\fR and passing in the \fIflags\fR argument.
-.VE
 .IP [2]
 Prepare to block for an event.  To do this, \fBTcl_DoOneEvent\fR
 invokes a \fIsetup procedure\fR in each event source.
 The event source will perform event-source specific initialization and
-.VS 8.1
 possibly call \fBTcl_SetMaxBlockTime\fR to limit how long
-.VE
 \fBTcl_WaitForEvent\fR will block if no new events occur.
 .IP [3]
 Call \fBTcl_WaitForEvent\fR.  This procedure is implemented differently
@@ -233,8 +231,8 @@ the event source.
 \fISetupProc\fR should match the following prototype:
 .CS
 typedef void Tcl_EventSetupProc(
-	ClientData \fIclientData\fR,
-	int \fIflags\fR);
+        ClientData \fIclientData\fR,
+        int \fIflags\fR);
 .CE
 The \fIclientData\fR argument will be the same as the \fIclientData\fR
 argument to \fBTcl_CreateEventSource\fR;  it is typically used to
@@ -243,7 +241,7 @@ The \fIflags\fR argument will be the same as the \fIflags\fR
 argument passed to \fBTcl_DoOneEvent\fR except that it will never
 be 0 (\fBTcl_DoOneEvent\fR replaces 0 with \fBTCL_ALL_EVENTS\fR).
 \fIFlags\fR indicates what kinds of events should be considered;
-if the bit corresponding to this event source isn't set, the event
+if the bit corresponding to this event source is not set, the event
 source should return immediately without doing anything.  For
 example, the file event source checks for the \fBTCL_FILE_EVENTS\fR
 bit.
@@ -256,7 +254,6 @@ request notification with a Windows event.  For timer-driven event
 sources such as timer events or any polled event, the event source
 can call \fBTcl_SetMaxBlockTime\fR to force the application to wake
 up after a specified time even if no events have occurred.
-.VS 8.1
 If no event source calls \fBTcl_SetMaxBlockTime\fR
 then \fBTcl_WaitForEvent\fR will wait as long as necessary for an
 event to occur; otherwise, it will only wait as long as the shortest
@@ -268,28 +265,24 @@ events already queued.  If there are, it calls
 \fBTcl_SetMaxBlockTime\fR with a 0 block time so that
 \fBTcl_WaitForEvent\fR does not block if there is no new data on the X
 connection.
-.VE
 The \fItimePtr\fR argument to \fBTcl_WaitForEvent\fR points to
 a structure that describes a time interval in seconds and
 microseconds:
 .CS
 typedef struct Tcl_Time {
-	long \fIsec\fR;
-	long \fIusec\fR;
+        long \fIsec\fR;
+        long \fIusec\fR;
 } Tcl_Time;
 .CE
 The \fIusec\fR field should be less than 1000000.
 .PP
-.VS 8.1
 Information provided to \fBTcl_SetMaxBlockTime\fR
 is only used for the next call to \fBTcl_WaitForEvent\fR; it is
 discarded after \fBTcl_WaitForEvent\fR returns.
-.VE
 The next time an event wait is done each of the event sources'
 setup procedures will be called again, and they can specify new
 information for that event wait.
 .PP
-.VS 8.1
 If the application uses an external event loop rather than
 \fBTcl_DoOneEvent\fR, the event sources may need to call
 \fBTcl_SetMaxBlockTime\fR at other times.  For example, if a new event
@@ -305,7 +298,6 @@ platform-specific procedures may also be available for
 \fIsetupProc\fR, if there is additional information needed by
 \fBTcl_WaitForEvent\fR on that platform.  For example, on Unix systems
 the \fBTcl_CreateFileHandler\fR interface can be used to wait for file events.
-.VE
 .PP
 The second procedure provided by each event source is its check
 procedure, indicated by the \fIcheckProc\fR argument to
@@ -313,8 +305,8 @@ procedure, indicated by the \fIcheckProc\fR argument to
 following prototype:
 .CS
 typedef void Tcl_EventCheckProc(
-	ClientData \fIclientData\fR,
-	int \fIflags\fR);
+        ClientData \fIclientData\fR,
+        int \fIflags\fR);
 .CE
 The arguments to this procedure are the same as those for \fIsetupProc\fR.
 \fBCheckProc\fR is invoked by \fBTcl_DoOneEvent\fR after it has waited
@@ -363,24 +355,20 @@ events at the front of the queue, such as a series of
 Enter and Leave events synthesized during a grab or ungrab operation
 in Tk.
 .PP
-.VS 8.1
 When it is time to handle an event from the queue (steps 1 and 4
 above) \fBTcl_ServiceEvent\fR will invoke the \fIproc\fR specified
-.VE
 in the first queued \fBTcl_Event\fR structure.
 \fIProc\fR must match the following prototype:
 .CS
 typedef int Tcl_EventProc(
-	Tcl_Event *\fIevPtr\fR,
-	int \fIflags\fR);
+        Tcl_Event *\fIevPtr\fR,
+        int \fIflags\fR);
 .CE
 The first argument to \fIproc\fR is a pointer to the event, which will
 be the same as the first argument to the \fBTcl_QueueEvent\fR call that
 added the event to the queue.
 The second argument to \fIproc\fR is the \fIflags\fR argument for the
-.VS 8.1
 current call to \fBTcl_ServiceEvent\fR;  this is used by the event source
-.VE
 to return immediately if its events are not relevant.
 .PP
 It is up to \fIproc\fR to handle the event, typically by invoking
@@ -389,20 +377,17 @@ Once the event source has finished handling the event it returns 1
 to indicate that the event can be removed from the queue.
 If for some reason the event source decides that the event cannot
 be handled at this time, it may return 0 to indicate that the event
-.VS 8.1
 should be deferred for processing later;  in this case \fBTcl_ServiceEvent\fR
-.VE
 will go on to the next event in the queue and attempt to service it.
 There are several reasons why an event source might defer an event.
 One possibility is that events of this type are excluded by the
 \fIflags\fR argument.
 For example, the file event source will always return 0 if the
-\fBTCL_FILE_EVENTS\fR bit isn't set in \fIflags\fR.
+\fBTCL_FILE_EVENTS\fR bit is not set in \fIflags\fR.
 Another example of deferring events happens in Tk if
 \fBTk_RestrictEvents\fR has been invoked to defer certain kinds
 of window events.
 .PP
-.VS 8.1
 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
@@ -422,8 +407,9 @@ Tcl_ThreadID for the current thread, use the \fBTcl_GetCurrentThread\fR
 procedure.  (A thread would then need to pass this identifier to other
 threads for those threads to be able to add events to its queue.)
 After adding an event to another thread's queue, you then typically
-need to call \fBTcl_ThreadAlert\fR to "wake up" that thread's notifier to
-alert it to the new event.
+need to call \fBTcl_ThreadAlert\fR to
+.QW "wake up"
+that thread's notifier to alert it to the new event.
 .PP
 \fBTcl_DeleteEvents\fR can be used to explicitly remove one or more
 events from the event queue.  \fBTcl_DeleteEvents\fR calls \fIproc\fR
@@ -432,8 +418,8 @@ returns 1.  Events for which the procedure returns 0 are left in the
 queue.  \fIProc\fR should match the following prototype:
 .CS
 typedef int Tcl_EventDeleteProc(
-	Tcl_Event *\fIevPtr\fR,
-	ClientData \fIclientData\fR);
+        Tcl_Event *\fIevPtr\fR,
+        ClientData \fIclientData\fR);
 .CE
 The \fIclientData\fR argument will be the same as the \fIclientData\fR
 argument to \fBTcl_DeleteEvents\fR; it is typically used to point to
@@ -444,23 +430,21 @@ point to the next event in the queue.
 \fIcheckProc\fR, and \fIclientData\fR arguments must exactly match those
 provided to the \fBTcl_CreateEventSource\fR for the event source to be deleted.
 If no such source exists, \fBTcl_DeleteEventSource\fR has no effect.
-.VE
 
 .SH "CREATING A NEW NOTIFIER"
 .PP
 The notifier consists of all the procedures described in this manual
 entry, plus \fBTcl_DoOneEvent\fR and \fBTcl_Sleep\fR, which are
-.VS 8.1
 available on all platforms, and \fBTcl_CreateFileHandler\fR and
 \fBTcl_DeleteFileHandler\fR, which are Unix-specific.  Most of these
 procedures are generic, in that they are the same for all notifiers.
-However, eight of the procedures are notifier-dependent:
-\fBTcl_InitNotifier\fR, \fBTcl_AlertNotifier\fR, \fBTcl_FinalizeNotifier\fR, 
-\fBTcl_SetTimer\fR, \fBTcl_Sleep\fR, \fBTcl_WaitForEvent\fR,
-\fBTcl_CreateFileHandler\fR and \fBTcl_DeleteFileHandler\fR.  To
-support a new platform or to integrate Tcl with an
-application-specific event loop, you must write new versions of these
-procedures.
+However, none of the procedures are notifier-dependent:
+\fBTcl_InitNotifier\fR, \fBTcl_AlertNotifier\fR,
+\fBTcl_FinalizeNotifier\fR, \fBTcl_SetTimer\fR, \fBTcl_Sleep\fR,
+\fBTcl_WaitForEvent\fR, \fBTcl_CreateFileHandler\fR,
+\fBTcl_DeleteFileHandler\fR and \fBTcl_ServiceModeHook\fR.  To support a
+new platform or to integrate Tcl with an application-specific event loop,
+you must write new versions of these procedures.
 .PP
 \fBTcl_InitNotifier\fR initializes the notifier state and returns
 a handle to the notifier state.  Tcl calls this
@@ -469,7 +453,9 @@ procedure when initializing a Tcl interpreter.  Similarly,
 called by \fBTcl_Finalize\fR when shutting down a Tcl interpreter.
 .PP
 \fBTcl_WaitForEvent\fR is the lowest-level procedure in the notifier;
-it is responsible for waiting for an ``interesting'' event to occur or
+it is responsible for waiting for an
+.QW interesting
+event to occur or
 for a given time to elapse.  Before \fBTcl_WaitForEvent\fR is invoked,
 each of the event sources' setup procedure will have been invoked.
 The \fItimePtr\fR argument to
@@ -483,13 +469,13 @@ to occur; it should not actually process the event in any way.
 Later on, the
 event sources will process the raw events and create Tcl_Events on
 the event queue in their \fIcheckProc\fR procedures.
-However, on some platforms (such as Windows) this isn't possible;
+However, on some platforms (such as Windows) this is not possible;
 events may be processed in \fBTcl_WaitForEvent\fR, including queuing
 Tcl_Events and more (for example, callbacks for native widgets may be
 invoked).  The return value from \fBTcl_WaitForEvent\fR must be either
 0, 1, or \-1.  On platforms such as Windows where events get processed in
 \fBTcl_WaitForEvent\fR, a return value of 1 means that there may be more
-events still pending that haven't been processed.  This is a sign to the
+events still pending that have not been processed.  This is a sign to the
 caller that it must call \fBTcl_WaitForEvent\fR again if it wants all
 pending events to be processed. A 0 return value means that calling
 \fBTcl_WaitForEvent\fR again will not have any effect: either this is a
@@ -504,7 +490,9 @@ forever because there were no active event sources and the timeout was
 infinite.
 .PP
 \fBTcl_AlertNotifier\fR is used in multithreaded applications to allow
-any thread to "wake up" the notifier to alert it to new events on its
+any thread to
+.QW "wake up"
+the notifier to alert it to new events on its
 queue.  \fBTcl_AlertNotifier\fR requires as an argument the notifier
 handle returned by \fBTcl_InitNotifier\fR.
 .PP
@@ -514,11 +502,18 @@ invoked by \fBTcl_SetMaxBlockTime\fR whenever the maximum blocking
 time has been reduced.  \fBTcl_SetTimer\fR should arrange for the
 external event loop to invoke \fBTcl_ServiceAll\fR after the specified
 interval even if no events have occurred.  This interface is needed
-because \fBTcl_WaitForEvent\fR isn't invoked when there is an external
+because \fBTcl_WaitForEvent\fR is not invoked when there is an external
 event loop.  If the
 notifier will only be used from \fBTcl_DoOneEvent\fR, then
 \fBTcl_SetTimer\fR need not do anything.
 .PP
+\fBTcl_ServiceModeHook\fR is called by the platform-independent portion
+of the notifier when client code makes a call to
+\fBTcl_SetServiceMode\fR. This hook is provided to support operating
+systems that require special event handling when the application is in
+a modal loop (the Windows notifier, for instance, uses this hook to
+create a communication window).
+.PP
 On Unix systems, the file event source also needs support from the
 notifier.  The file event source consists of the
 \fBTcl_CreateFileHandler\fR and \fBTcl_DeleteFileHandler\fR
@@ -532,6 +527,38 @@ The easiest way to create a new notifier is to look at the code
 for an existing notifier, such as the files \fBunix/tclUnixNotfy.c\fR
 or \fBwin/tclWinNotify.c\fR in the Tcl source distribution.
 
+.SH "REPLACING THE NOTIFIER"
+.PP
+A notifier that has been written according to the conventions above
+can also be installed in a running process in place of the standard
+notifier.  This mechanism is used so that a single executable can be
+used (with the standard notifier) as a stand-alone program and reused
+(with a replacement notifier in a loadable extension) as an extension
+to another program, such as a Web browser plugin.
+.PP
+To do this, the extension makes a call to \fBTcl_SetNotifier\fR
+passing a pointer to a \fBTcl_NotifierProcs\fR data structure.  The
+structure has the following layout:
+.CS
+typedef struct Tcl_NotifierProcs {
+    Tcl_SetTimerProc *setTimerProc;
+    Tcl_WaitForEventProc *waitForEventProc;
+    Tcl_CreateFileHandlerProc *createFileHandlerProc;
+    Tcl_DeleteFileHandlerProc *deleteFileHandlerProc;
+    Tcl_InitNotifierProc *initNotifierProc;
+    Tcl_FinalizeNotifierProc *finalizeNotifierProc;
+    Tcl_AlertNotifierProc *alertNotifierProc;
+    Tcl_ServiceModeHookProc *serviceModeHookProc;
+} Tcl_NotifierProcs;
+.CE
+Following the call to \fBTcl_SetNotifier\fR, the pointers given in
+the \fBTcl_NotifierProcs\fR structure replace whatever notifier had
+been installed in the process.
+.PP
+It is extraordinarily unwise to replace a running notifier. Normally,
+\fBTcl_SetNotifier\fR should be called at process initialization time
+before the first call to \fBTcl_InitNotifier\fR.
+
 .SH "EXTERNAL EVENT LOOPS"
 .PP
 The notifier interfaces are designed so that Tcl can be embedded into
@@ -592,7 +619,7 @@ then calls to \fBTcl_ServiceAll\fR will behave normally.
 mode, which should be restored when the recursive loop exits.
 \fBTcl_GetServiceMode\fR returns the current value of the service
 mode.
-.VE
+
 .SH "SEE ALSO"
 \fBTcl_CreateFileHandler\fR, \fBTcl_DeleteFileHandler\fR, \fBTcl_Sleep\fR,
 \fBTcl_DoOneEvent\fR, \fBThread(3)\fR

doc/Object.3

@@ -5,7 +5,7 @@
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
 .so man.macros
-.TH Tcl_Obj 3 8.1 Tcl "Tcl Library Procedures"
+.TH Tcl_Obj 3 8.5 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
 Tcl_NewObj, Tcl_DuplicateObj, Tcl_IncrRefCount, Tcl_DecrRefCount, Tcl_IsShared, Tcl_InvalidateStringRep \- manipulate Tcl objects
@@ -28,7 +28,7 @@ int
 .sp
 \fBTcl_InvalidateStringRep\fR(\fIobjPtr\fR)
 .SH ARGUMENTS
-.AS Tcl_Obj *objPtr in
+.AS Tcl_Obj *objPtr
 .AP Tcl_Obj *objPtr in
 Points to an object;
 must have been the result of a previous call to \fBTcl_NewObj\fR.
@@ -100,34 +100,37 @@ reclaim an object's storage.
 .PP
 Tcl objects are typed.
 An object's internal representation is controlled by its type.
-Seven types are predefined in the Tcl core
+Several types are predefined in the Tcl core
 including integer, double, list, and bytecode.
 Extension writers can extend the set of types
-by using the procedure \fBTcl_RegisterObjType\fR .
-
+by defining their own \fBTcl_ObjType\fR structs.
 .SH "THE TCL_OBJ STRUCTURE"
 .PP
 Each Tcl object is represented by a \fBTcl_Obj\fR structure
 which is defined as follows.
 .CS
 typedef struct Tcl_Obj {
-	int \fIrefCount\fR;
-	char *\fIbytes\fR;
-	int \fIlength\fR;
-	Tcl_ObjType *\fItypePtr\fR;
-	union {
-		long \fIlongValue\fR;
-		double \fIdoubleValue\fR;
-		VOID *\fIotherValuePtr\fR;
-		struct {
-			VOID *\fIptr1\fR;
-			VOID *\fIptr2\fR;
-		} \fItwoPtrValue\fR;
-	} \fIinternalRep\fR;
+        int \fIrefCount\fR;
+        char *\fIbytes\fR;
+        int \fIlength\fR;
+        Tcl_ObjType *\fItypePtr\fR;
+        union {
+                long \fIlongValue\fR;
+                double \fIdoubleValue\fR;
+                void *\fIotherValuePtr\fR;
+                Tcl_WideInt \fIwideValue\fR;
+                struct {
+                        void *\fIptr1\fR;
+                        void *\fIptr2\fR;
+                } \fItwoPtrValue\fR;
+                struct {
+                        void *\fIptr\fR;
+                        unsigned long \fIvalue\fR;
+                } \fIptrAndLongRep\fR;
+        } \fIinternalRep\fR;
 } Tcl_Obj;
 .CE
 The \fIbytes\fR and the \fIlength\fR members together hold
-.VS 8.1
 an object's UTF-8 string representation,
 which is a \fIcounted string\fR not containing null bytes (UTF-8 null
 characters should be encoded as a two byte sequence: 192, 128.)
@@ -137,7 +140,6 @@ The byte array must always have a null byte after the last data byte,
 at offset \fIlength\fR;
 this allows string representations
 to be treated as conventional null-terminated C strings.
-.VE 8.1
 C programs use \fBTcl_GetStringFromObj\fR and \fBTcl_GetString\fR to get
 an object's string representation.
 If \fIbytes\fR is NULL,
@@ -151,10 +153,11 @@ the internal representation is invalid.
 .PP
 The \fIinternalRep\fR union member holds
 an object's internal representation.
-This is either a (long) integer, a double-precision floating point number,
+This is either a (long) integer, a double-precision floating-point number,
 a pointer to a value containing additional information
-needed by the object's type to represent the object,
-or two arbitrary pointers.
+needed by the object's type to represent the object, a Tcl_WideInt
+integer, two arbitrary pointers, or a pair made up of an unsigned long
+integer and a pointer.
 .PP
 The \fIrefCount\fR member is used to tell when it is safe to free
 an object's storage.
@@ -224,7 +227,6 @@ creates a new internal representation for an object
 and changes its \fItypePtr\fR.
 See the man page for \fBTcl_RegisterObjType\fR
 to see how to create a new object type.
-
 .SH "EXAMPLE OF THE LIFETIME OF AN OBJECT"
 .PP
 As an example of the lifetime of an object,
@@ -262,9 +264,8 @@ no longer corresponds to the internal representation.
 .CE
 The string representation of \fIx\fR's object is needed
 and is recomputed.
-The string representation is now \fB124\fR.
+The string representation is now \fB124\fR
 and both representations are again valid.
-
 .SH "STORAGE MANAGEMENT OF OBJECTS"
 .PP
 Tcl objects are allocated on the heap and are shared as much as possible
@@ -281,7 +282,7 @@ if the object's reference count drops to zero, frees its storage.
 An object shared by different code or data structures has
 \fIrefCount\fR greater than 1.
 Incrementing an object's reference count ensures that
-it won't be freed too early or have its value change accidently.
+it will not be freed too early or have its value change accidentally.
 .PP
 As an example, the bytecode interpreter shares argument objects
 between calling and called Tcl procedures to avoid having to copy objects.
@@ -297,7 +298,7 @@ When an object's reference count drops less than or equal to zero,
 \fBTcl_DecrRefCount\fR reclaims its storage.
 Most command procedures do not have to be concerned about
 reference counting since they use an object's value immediately
-and don't retain a pointer to the object after they return.
+and do not retain a pointer to the object after they return.
 However, if they do retain a pointer to an object in a data structure,
 they must be careful to increment its reference count
 since the retained pointer is a new reference.
@@ -312,26 +313,29 @@ by using \fBTcl_DuplicateObj\fR;
 this returns a new duplicate of the original object
 that has \fIrefCount\fR 0.
 If the object is not shared,
-the command procedure "owns" the object and can safely modify it directly.
+the command procedure
+.QW "owns"
+the object and can safely modify it directly.
 For example, the following code appears in the command procedure
 that implements \fBlinsert\fR.
 This procedure modifies the list object passed to it in \fIobjv[1]\fR
 by inserting \fIobjc-3\fR new elements before \fIindex\fR.
+.PP
 .CS
 listPtr = objv[1];
 if (Tcl_IsShared(listPtr)) {
-	listPtr = Tcl_DuplicateObj(listPtr);
+    listPtr = Tcl_DuplicateObj(listPtr);
 }
-result = Tcl_ListObjReplace(interp, listPtr, index, 0, (objc-3), &(objv[3]));
+result = Tcl_ListObjReplace(interp, listPtr, index, 0,
+        (objc-3), &(objv[3]));
 .CE
+.PP
 As another example, \fBincr\fR's command procedure
 must check whether the variable's object is shared before
 incrementing the integer in its internal representation.
 If it is shared, it needs to duplicate the object
-in order to avoid accidently changing values in other data structures.
-
+in order to avoid accidentally changing values in other data structures.
 .SH "SEE ALSO"
-Tcl_ConvertToType, Tcl_GetIntFromObj, Tcl_ListObjAppendElement, Tcl_ListObjIndex, Tcl_ListObjReplace, Tcl_RegisterObjType
-
+Tcl_ConvertToType(3), Tcl_GetIntFromObj(3), Tcl_ListObjAppendElement(3), Tcl_ListObjIndex(3), Tcl_ListObjReplace(3), Tcl_RegisterObjType(3)
 .SH KEYWORDS
 internal representation, object, object creation, object type, reference counting, string representation, type conversion

doc/ObjectType.3

@@ -24,12 +24,12 @@ int
 int
 \fBTcl_ConvertToType\fR(\fIinterp, objPtr, typePtr\fR)
 .SH ARGUMENTS
-.AS Tcl_ObjType *typeName in
+.AS "const char" *typeName
 .AP Tcl_ObjType *typePtr in
 Points to the structure containing information about the Tcl object type.
 This storage must live forever,
 typically by being statically allocated.
-.AP "CONST char" *typeName in
+.AP "const char" *typeName in
 The name of a Tcl object type that \fBTcl_GetObjType\fR should look up.
 .AP Tcl_Interp *interp in
 Interpreter to use for error reporting.
@@ -43,12 +43,14 @@ must have been the result of a previous call to \fBTcl_NewObj\fR.
 .SH DESCRIPTION
 .PP
 The procedures in this man page manage Tcl object types.
-The are used to register new object types,
-look up types,
+They are used to register new object types, look up types,
 and force conversions from one type to another.
 .PP
 \fBTcl_RegisterObjType\fR registers a new Tcl object type
-in the table of all object types supported by Tcl.
+in the table of all object types that \fBTcl_GetObjType\fR
+can look up by name.  There are other object types supported by Tcl
+as well, which Tcl chooses not to register.  Extensions can likewise
+choose to register the object types they create or not.
 The argument \fItypePtr\fR points to a Tcl_ObjType structure that
 describes the new type by giving its name
 and by supplying pointers to four procedures
@@ -59,11 +61,11 @@ it is replaced with the new type.
 The Tcl_ObjType structure is described
 in the section \fBTHE TCL_OBJTYPE STRUCTURE\fR below.
 .PP
-\fBTcl_GetObjType\fR returns a pointer to the Tcl_ObjType
+\fBTcl_GetObjType\fR returns a pointer to the registered Tcl_ObjType
 with name \fItypeName\fR.
 It returns NULL if no type with that name is registered.
 .PP
-\fBTcl_AppendAllObjTypes\fR appends the name of each object type
+\fBTcl_AppendAllObjTypes\fR appends the name of each registered object type
 as a list element onto the Tcl object referenced by \fIobjPtr\fR.
 The return value is \fBTCL_OK\fR unless there was an error
 converting \fIobjPtr\fR to a list object;
@@ -73,7 +75,8 @@ in that case \fBTCL_ERROR\fR is returned.
 if possible.
 It creates a new internal representation for \fIobjPtr\fR
 appropriate for the target type \fItypePtr\fR
-and sets its \fItypePtr\fR member to that type.
+and sets its \fItypePtr\fR member as determined by calling the 
+\fItypePtr->setFromAnyProc\fR routine.  
 Any internal representation for \fIobjPtr\fR's old type is freed.
 If an error occurs during conversion, it returns \fBTCL_ERROR\fR
 and leaves an error message in the result object for \fIinterp\fR
@@ -81,118 +84,168 @@ unless \fIinterp\fR is NULL.
 Otherwise, it returns \fBTCL_OK\fR.
 Passing a NULL \fIinterp\fR allows this procedure to be used
 as a test whether the conversion can be done (and in fact was done).
-
+.VS 8.5
+.PP
+In many cases, the \fItypePtr->setFromAnyProc\fR routine will
+set \fIobjPtr->typePtr\fR to the argument value \fItypePtr\fR,
+but that is no longer guaranteed.  The \fIsetFromAnyProc\fR is
+free to set the internal representation for \fIobjPtr\fR to make
+use of another related Tcl_ObjType, if it sees fit.
+.VE 8.5
 .SH "THE TCL_OBJTYPE STRUCTURE"
 .PP
 Extension writers can define new object types by defining four
-procedures,
-initializing a Tcl_ObjType structure to describe the type,
-and calling \fBTcl_RegisterObjType\fR.
+procedures and
+initializing a Tcl_ObjType structure to describe the type.
+Extension writers may also pass a pointer to their Tcl_ObjType
+structure to \fBTcl_RegisterObjType\fR if they wish to permit
+other extensions to look up their Tcl_ObjType by name with
+the \fBTcl_GetObjType\fR routine.
 The \fBTcl_ObjType\fR structure is defined as follows:
+.PP
 .CS
 typedef struct Tcl_ObjType {
-	char *\fIname\fR;
-	Tcl_FreeInternalRepProc *\fIfreeIntRepProc\fR;
-	Tcl_DupInternalRepProc *\fIdupIntRepProc\fR;
-	Tcl_UpdateStringProc *\fIupdateStringProc\fR;
-	Tcl_SetFromAnyProc *\fIsetFromAnyProc\fR;
+    char *\fIname\fR;
+    Tcl_FreeInternalRepProc *\fIfreeIntRepProc\fR;
+    Tcl_DupInternalRepProc *\fIdupIntRepProc\fR;
+    Tcl_UpdateStringProc *\fIupdateStringProc\fR;
+    Tcl_SetFromAnyProc *\fIsetFromAnyProc\fR;
 } Tcl_ObjType;
 .CE
+.SS "THE NAME FIELD"
 .PP
 The \fIname\fR member describes the name of the type, e.g. \fBint\fR.
-Extension writers can look up an object type using its name
-with the \fBTcl_GetObjType\fR procedure.
+When a type is registered, this is the name used by callers
+of \fBTcl_GetObjType\fR to lookup the type.  For unregistered
+types, the \fIname\fR field is primarily of value for debugging.
 The remaining four members are pointers to procedures
 called by the generic Tcl object code:
+.SS "THE SETFROMANYPROC FIELD"
 .PP
 The \fIsetFromAnyProc\fR member contains the address of a function
 called to create a valid internal representation
 from an object's string representation.
+.PP
 .CS
-typedef int (Tcl_SetFromAnyProc) (Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIobjPtr\fR);
+typedef int (Tcl_SetFromAnyProc) (Tcl_Interp *\fIinterp\fR,
+        Tcl_Obj *\fIobjPtr\fR);
 .CE
-If an internal representation can't be created from the string,
+.PP
+If an internal representation cannot be created from the string,
 it returns \fBTCL_ERROR\fR and puts a message
 describing the error in the result object for \fIinterp\fR
 unless \fIinterp\fR is NULL.
 If \fIsetFromAnyProc\fR is successful,
 it stores the new internal representation,
 sets \fIobjPtr\fR's \fItypePtr\fR member to point to
-\fIsetFromAnyProc\fR's \fBTcl_ObjType\fR, and returns \fBTCL_OK\fR.
+the \fBTcl_ObjType\fR struct corresponding to the new
+internal representation, and returns \fBTCL_OK\fR.
 Before setting the new internal representation,
 the \fIsetFromAnyProc\fR must free any internal representation
 of \fIobjPtr\fR's old type;
 it does this by calling the old type's \fIfreeIntRepProc\fR
 if it is not NULL.
-As an example, the \fIsetFromAnyProc\fR for the builtin Tcl integer type
+.PP
+As an example, the \fIsetFromAnyProc\fR for the built-in Tcl list type
 gets an up-to-date string representation for \fIobjPtr\fR
 by calling \fBTcl_GetStringFromObj\fR.
-It parses the string to obtain an integer and,
-if this succeeds,
-stores the integer in \fIobjPtr\fR's internal representation
-and sets \fIobjPtr\fR's \fItypePtr\fR member to point to the integer type's
+It parses the string to verify it is in a valid list format and
+to obtain each element value in the list, and, if this succeeds,
+stores the list elements in \fIobjPtr\fR's internal representation
+and sets \fIobjPtr\fR's \fItypePtr\fR member to point to the list type's
 Tcl_ObjType structure.
+.PP
 Do not release \fIobjPtr\fR's old internal representation unless you
 replace it with a new one or reset the \fItypePtr\fR member to NULL.
 .PP
+The \fIsetFromAnyProc\fR member may be set to NULL, if the routines
+making use of the internal representation have no need to derive that
+internal representation from an arbitrary string value.  However, in
+this case, passing a pointer to the type to Tcl_ConvertToType() will
+lead to a panic, so to avoid this possibility, the type
+should \fInot\fR be registered.
+.SS "THE UPDATESTRINGPROC FIELD"
+.PP
 The \fIupdateStringProc\fR member contains the address of a function
 called to create a valid string representation
 from an object's internal representation.
+.PP
 .CS
 typedef void (Tcl_UpdateStringProc) (Tcl_Obj *\fIobjPtr\fR);
 .CE
+.PP
 \fIobjPtr\fR's \fIbytes\fR member is always NULL when it is called.
 It must always set \fIbytes\fR non-NULL before returning.
 We require the string representation's byte array
-to have a null after the last byte, at offset \fIlength\fR;
-this allows string representations that do not contain null bytes
+to have a null after the last byte, at offset \fIlength\fR,
+and to have no null bytes before that; this allows string representations 
 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
 enough storage for the string's bytes and the terminating null byte.
-The \fIupdateStringProc\fR for Tcl's builtin list type, for example,
-builds an array of strings for each element object
-and then calls \fBTcl_Merge\fR
-to construct a string with proper Tcl list structure.
-It stores this string as the list object's string representation.
+.PP
+The \fIupdateStringProc\fR for Tcl's built-in double type, for example,
+calls Tcl_PrintDouble to write to a buffer of size TCL_DOUBLE_SPACE,
+then allocates and copies the string representation to just enough
+space to hold it.  A pointer to the allocated space is stored in
+the \fIbytes\fR member.
+.PP
+The \fIupdateStringProc\fR member may be set to NULL, if the routines
+making use of the internal representation are written so that the
+string representation is never invalidated.  Failure to meet this
+obligation will lead to panics or crashes when \fBTcl_GetStringFromObj\fR
+or other similar routines ask for the string representation.
+.SS "THE DUPINTREPPROC FIELD"
 .PP
 The \fIdupIntRepProc\fR member contains the address of a function
 called to copy an internal representation from one object to another.
+.PP
 .CS
-typedef void (Tcl_DupInternalRepProc) (Tcl_Obj *\fIsrcPtr\fR, Tcl_Obj *\fIdupPtr\fR);
+typedef void (Tcl_DupInternalRepProc) (Tcl_Obj *\fIsrcPtr\fR,
+        Tcl_Obj *\fIdupPtr\fR);
 .CE
+.PP
 \fIdupPtr\fR's internal representation is made a copy of \fIsrcPtr\fR's
 internal representation.
 Before the call,
 \fIsrcPtr\fR's internal representation is valid and \fIdupPtr\fR's is not.
 \fIsrcPtr\fR's object type determines what
 copying its internal representation means.
+.PP
 For example, the \fIdupIntRepProc\fR for the Tcl integer type
 simply copies an integer.
-The builtin list type's \fIdupIntRepProc\fR
-allocates a new array that points at the original element objects;
-the elements are shared between the two lists
-(and their reference counts are incremented to reflect the new references).
+The built-in list type's \fIdupIntRepProc\fR uses a far more
+sophisticated scheme to continue sharing storage as much as it
+reasonably can.
+.SS "THE FREEINTREPPROC FIELD"
 .PP
 The \fIfreeIntRepProc\fR member contains the address of a function
 that is called when an object is freed.
+.PP
 .CS
 typedef void (Tcl_FreeInternalRepProc) (Tcl_Obj *\fIobjPtr\fR);
 .CE
+.PP
 The \fIfreeIntRepProc\fR function can deallocate the storage
 for the object's internal representation
 and do other type-specific processing necessary when an object is freed.
-For example, Tcl list objects have an \fIinternalRep.otherValuePtr\fR
-that points to an array of pointers to each element in the list.
-The list type's \fIfreeIntRepProc\fR decrements
-the reference count for each element object
-(since the list will no longer refer to those objects),
-then deallocates the storage for the array of pointers.
+.PP
+For example, the list type's \fIfreeIntRepProc\fR respects
+the storage sharing scheme established by the \fIdupIntRepProc\fR
+so that it only frees storage when the last object sharing it
+is being freed.
+.PP
 The \fIfreeIntRepProc\fR member can be set to NULL
 to indicate that the internal representation does not require freeing.
-
+The \fIfreeIntRepProc\fR implementation must not access the
+\fIbytes\fR member of the object, since Tcl makes its own internal
+uses of that field during object deletion.  The defined tasks for
+the \fIfreeIntRepProc\fR have no need to consult the \fIbytes\fR
+member.
 .SH "SEE ALSO"
 Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount
-
 .SH KEYWORDS
 internal representation, object, object type, string representation, type conversion

doc/OpenFileChnl.3

@@ -9,7 +9,7 @@
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-Tcl_OpenFileChannel, Tcl_OpenCommandChannel, Tcl_MakeFileChannel, Tcl_GetChannel, Tcl_GetChannelNames, Tcl_GetChannelNamesEx, Tcl_RegisterChannel, Tcl_UnregisterChannel, Tcl_DetachChannel, Tcl_IsStandardChannel, Tcl_Close, Tcl_ReadChars, Tcl_Read, Tcl_GetsObj, Tcl_Gets, Tcl_WriteObj, Tcl_WriteChars, Tcl_Write, Tcl_Flush, Tcl_Seek, Tcl_Tell, Tcl_GetChannelOption, Tcl_SetChannelOption, Tcl_Eof, Tcl_InputBlocked, Tcl_InputBuffered, Tcl_OutputBuffered, Tcl_Ungets, Tcl_ReadRaw, Tcl_WriteRaw \- buffered I/O facilities using channels
+Tcl_OpenFileChannel, Tcl_OpenCommandChannel, Tcl_MakeFileChannel, Tcl_GetChannel, Tcl_GetChannelNames, Tcl_GetChannelNamesEx, Tcl_RegisterChannel, Tcl_UnregisterChannel, Tcl_DetachChannel, Tcl_IsStandardChannel, Tcl_Close, Tcl_ReadChars, Tcl_Read, Tcl_GetsObj, Tcl_Gets, Tcl_WriteObj, Tcl_WriteChars, Tcl_Write, Tcl_Flush, Tcl_Seek, Tcl_Tell, Tcl_TruncateChannel, Tcl_GetChannelOption, Tcl_SetChannelOption, Tcl_Eof, Tcl_InputBlocked, Tcl_InputBuffered, Tcl_OutputBuffered, Tcl_Ungets, Tcl_ReadRaw, Tcl_WriteRaw \- buffered I/O facilities using channels
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -25,14 +25,12 @@ Tcl_Channel
 .sp
 Tcl_Channel
 \fBTcl_GetChannel\fR(\fIinterp, channelName, modePtr\fR)
-.VS 8.3
 .sp
 int
 \fBTcl_GetChannelNames\fR(\fIinterp\fR)
 .sp
 int
 \fBTcl_GetChannelNamesEx\fR(\fIinterp, pattern\fR)
-.VE
 .sp
 void
 \fBTcl_RegisterChannel\fR(\fIinterp, channel\fR)
@@ -49,7 +47,6 @@ int
 int
 \fBTcl_Close\fR(\fIinterp, channel\fR)
 .sp
-.VS 8.1
 int
 \fBTcl_ReadChars\fR(\fIchannel, readObjPtr, charsToRead, appendFlag\fR)
 .sp
@@ -73,15 +70,12 @@ int
 .sp
 int
 \fBTcl_Write\fR(\fIchannel, byteBuf, bytesToWrite\fR)
-.VE
-.VS 8.3.2
 .sp
 int
 \fBTcl_ReadRaw\fR(\fIchannel, readBuf, bytesToRead\fR)
 .sp
 int
 \fBTcl_WriteRaw\fR(\fIchannel, byteBuf, bytesToWrite\fR)
-.VE
 .sp
 int
 \fBTcl_Eof\fR(\fIchannel\fR)
@@ -94,19 +88,20 @@ int
 .sp
 int
 \fBTcl_InputBuffered\fR(\fIchannel\fR)
-.VS 8.4
 .sp
 int
 \fBTcl_OutputBuffered\fR(\fIchannel\fR)
-.VE
 .sp
-.VS 8.4
 Tcl_WideInt
 \fBTcl_Seek\fR(\fIchannel, offset, seekMode\fR)
 .sp
 Tcl_WideInt
 \fBTcl_Tell\fR(\fIchannel\fR)
-.VE 8.4
+.sp
+.VS 8.5
+int
+\fBTcl_TruncateChannel\fR(\fIchannel, length\fR)
+.VE 8.5
 .sp
 int
 \fBTcl_GetChannelOption\fR(\fIinterp, channel, optionName, optionValue\fR)
@@ -115,12 +110,12 @@ int
 \fBTcl_SetChannelOption\fR(\fIinterp, channel, optionName, newValue\fR)
 .sp
 .SH ARGUMENTS
-.AS Tcl_ChannelType newClientProcPtr in
+.AS Tcl_DString *channelName in/out
 .AP Tcl_Interp *interp in
 Used for error reporting and to look up a channel registered in it.
-.AP "CONST char" *fileName in
+.AP "const char" *fileName in
 The name of a local or network file.
-.AP "CONST char" *mode in
+.AP "const char" *mode in
 Specifies how the file is to be accessed.  May have any of the values
 allowed for the \fImode\fR argument to the Tcl \fBopen\fR command.  
 .AP int permissions in
@@ -128,7 +123,7 @@ POSIX-style permission flags such as 0644.  If a new file is created, these
 permissions will be set on the created file.
 .AP int argc in
 The number of elements in \fIargv\fR.
-.AP "CONST char" **argv in
+.AP "const char" **argv in
 Arguments for constructing a command pipeline.  These values have the same
 meaning as the non-switch arguments to the Tcl \fBexec\fR command.
 .AP int flags in
@@ -147,20 +142,17 @@ file descriptor, for Windows it is a HANDLE.
 .AP int readOrWrite in
 OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR to indicate
 what operations are valid on \fIhandle\fR.
-.AP "CONST char" *channelName in
+.AP "const char" *channelName in
 The name of the channel. 
 .AP int *modePtr out
 Points at an integer variable that will receive an OR-ed combination of
 \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR denoting whether the channel is
 open for reading and writing.
-.VS 8.3
-.AP "CONST char" *pattern in
+.AP "const char" *pattern in
 The pattern to match on, passed to Tcl_StringMatch, or NULL.
-.VE
 .AP Tcl_Channel channel in
 A Tcl channel for input or output.  Must have been the return value
 from a procedure such as \fBTcl_OpenFileChannel\fR.
-.VS 8.1 br
 .AP Tcl_Obj *readObjPtr in/out
 A pointer to a Tcl Object in which to store the characters read from the
 channel.
@@ -184,25 +176,22 @@ object.
 A pointer to a Tcl dynamic string in which to store the line read from the
 channel.  Must have been initialized by the caller.  The line read will be
 appended to any data already in the dynamic string.
-.VS 8.3
-.AP "CONST char" *input in
+.AP "const char" *input in
 The input to add to a channel buffer.
 .AP int inputLen in
 Length of the input
 .AP int addAtEnd in
 Flag indicating whether the input should be added to the end or
 beginning of the channel buffer.
-.VE
 .AP Tcl_Obj *writeObjPtr in
 A pointer to a Tcl Object whose contents will be output to the channel.
-.AP "CONST char" *charBuf in
+.AP "const char" *charBuf in
 A buffer containing the characters to output to the channel.
-.AP "CONST char" *byteBuf in
+.AP "const char" *byteBuf in
 A buffer containing the bytes to output to the channel.
 .AP int bytesToWrite in
 The number of bytes to consume from \fIcharBuf\fR or \fIbyteBuf\fR and
 output to the channel.
-.VE
 .AP Tcl_WideInt offset in
 How far to move the access point in the channel at which the next input or
 output operation will be applied, measured in bytes from the position
@@ -211,13 +200,15 @@ given by \fIseekMode\fR.  May be either positive or negative.
 Relative to which point to seek; used with \fIoffset\fR to calculate the new
 access point for the channel. Legal values are \fBSEEK_SET\fR,
 \fBSEEK_CUR\fR, and \fBSEEK_END\fR.
-.AP "CONST char" *optionName in
+.AP Tcl_WideInt length in
+The (non-negative) length to truncate the channel the channel to.
+.AP "const char" *optionName in
 The name of an option applicable to this channel, such as \fB\-blocking\fR.
 May have any of the values accepted by the \fBfconfigure\fR command.
 .AP Tcl_DString *optionValue in
 Where to store the value of an option or a list of all options and their
 values. Must have been initialized by the caller.
-.AP "CONST char" *newValue in
+.AP "const char" *newValue in
 New value for the option given by \fIoptionName\fR.
 .BE
 
@@ -228,7 +219,7 @@ platform-independent mechanism for performing buffered input
 and output operations on a variety of file, socket, and device
 types.
 The channel mechanism is extensible to new channel types, by
-providing a low level channel driver for the new type; the channel driver
+providing a low-level channel driver for the new type; the channel driver
 interface is described in the manual entry for \fBTcl_CreateChannel\fR. The
 channel mechanism provides a buffering scheme modeled after
 Unix's standard I/O, and it also allows for nonblocking I/O on
@@ -254,8 +245,6 @@ In addition, if \fIinterp\fR is non-NULL, \fBTcl_OpenFileChannel\fR
 leaves an error message in \fIinterp\fR's result after any error.  
 As of Tcl 8.4, the object-based API \fBTcl_FSOpenFileChannel\fR should 
 be used in preference to \fBTcl_OpenFileChannel\fR wherever possible.
-.PP
-
 .PP
 The newly created channel is not registered in the supplied interpreter; to
 register it, use \fBTcl_RegisterChannel\fR, described below.
@@ -349,7 +338,7 @@ reference to a channel that is also registered in a Tcl interpreter.
 .PP
 This procedure interacts with the code managing the standard
 channels. If no standard channels were initialized before the first
-call to \fBTcl_RegisterChannel\fR they will get initialized by that
+call to \fBTcl_RegisterChannel\fR, they will get initialized by that
 call. See \fBTcl_StandardChannels\fR for a general treatise about
 standard channels and the behaviour of the Tcl library with regard to
 them.
@@ -376,7 +365,7 @@ accessible in \fIinterp\fR. After this call, Tcl programs will no longer be
 able to use the channel's name to refer to the channel in that interpreter.
 Beyond that, this command has no further effect.  It cannot be used on
 the standard channels (stdout, stderr, stdin), and will return
-TCL_ERROR if passed one of those channels.
+\fBTCL_ERROR\fR if passed one of those channels.
 .PP
 Code not associated with a Tcl interpreter can call
 \fBTcl_DetachChannel\fR with \fIinterp\fR as NULL, to indicate to Tcl
@@ -423,7 +412,6 @@ been given as the \fBchan\fR argument in a call to
 when all calls to \fBTcl_RegisterChannel\fR have been matched by
 corresponding calls to \fBTcl_UnregisterChannel\fR.
 
-.VS 8.1 br
 .SH "TCL_READCHARS AND TCL_READ"
 .PP
 \fBTcl_ReadChars\fR consumes bytes from \fIchannel\fR, converting the bytes
@@ -434,7 +422,7 @@ that were stored in \fIreadObjPtr\fR.  If an error occurs while reading, the
 return value is \-1 and \fBTcl_ReadChars\fR records a POSIX error code that
 can be retrieved with \fBTcl_GetErrno\fR.
 .PP
-Setting \fIcharsToRead\fR to \fB-1\fR will cause the command to read
+Setting \fIcharsToRead\fR to \fB\-1\fR will cause the command to read
 all characters currently available (non-blocking) or everything until
 eof (blocking mode).
 .PP
@@ -467,7 +455,7 @@ from a channel, manipulated by calling \fBTcl_GetByteArrayFromObj\fR and
 related functions, and then written to a channel without the expense of ever
 converting to or from UTF-8.
 .PP
-\fBTcl_Read\fR is similar to \fBTcl_ReadChars\fR, except that it doesn't do
+\fBTcl_Read\fR is similar to \fBTcl_ReadChars\fR, except that it does not do
 encoding conversions, regardless of the channel's encoding.  It is deprecated
 and exists for backwards compatibility with non-internationalized Tcl
 extensions.  It consumes bytes from \fIchannel\fR and stores them in
@@ -519,9 +507,11 @@ at either the head or tail of the queue.  The pointer \fIinput\fR points
 to the data that is to be added.  The length of the input to add is given
 by \fIinputLen\fR.  A non-zero value of \fIaddAtEnd\fR indicates that the
 data is to be added at the end of queue; otherwise it will be added at the
-head of the queue.  If \fIchannel\fR has a "sticky" EOF set, no data will be
+head of the queue.  If \fIchannel\fR has a
+.QW sticky
+EOF set, no data will be
 added to the input queue.  \fBTcl_Ungets\fR returns \fIinputLen\fR or
--1 if an error occurs.
+\-1 if an error occurs.
 
 .SH "TCL_WRITECHARS, TCL_WRITEOBJ, AND TCL_WRITE"
 .PP
@@ -561,7 +551,7 @@ byte-oriented data can be read from a channel, manipulated by calling
 \fBTcl_GetByteArrayFromObj\fR and related functions, and then written to a
 channel without the expense of ever converting to or from UTF-8.
 .PP
-\fBTcl_Write\fR is similar to \fBTcl_WriteChars\fR except that it doesn't do
+\fBTcl_Write\fR is similar to \fBTcl_WriteChars\fR except that it does not do
 encoding conversions, regardless of the channel's encoding.  It is
 deprecated and exists for backwards compatibility with non-internationalized
 Tcl extensions.  It accepts \fIbytesToWrite\fR bytes of data at
@@ -577,7 +567,6 @@ not. Thus this function is \fBonly\fR usable for transformational
 channel drivers, i.e. drivers used in the middle of a stack of
 channels, to move data from the transformation into the channel below
 it.
-.VE
 
 .SH TCL_FLUSH
 .PP
@@ -609,6 +598,14 @@ After an error, the access point may or may not have been moved.
 \fBTcl_Tell\fR returns the current access point for a channel. The returned
 value is \-1 if the channel does not support seeking.
 
+.SH TCL_TRUNCATECHANNEL
+.PP
+.VS 8.5
+\fBTcl_TruncateChannel\fR truncates the file underlying \fIchannel\fR
+to a given \fIlength\fR of bytes. It returns \fBTCL_OK\fR if the
+operation succeeded, and \fBTCL_ERROR\fR otherwise.
+.VE 8.5
+
 .SH TCL_GETCHANNELOPTION
 .PP
 \fBTcl_GetChannelOption\fR retrieves, in \fIoptionValue\fR, the value of one of
@@ -658,11 +655,9 @@ buffered in the internal buffers for a channel. If the channel is not open
 for reading, this function always returns zero.
 
 .SH TCL_OUTPUTBUFFERED
-.VS 8.4
 \fBTcl_OutputBuffered\fR returns the number of bytes of output
 currently buffered in the internal buffers for a channel. If the
 channel is not open for writing, this function always returns zero.
-.VE
 
 .SH "PLATFORM ISSUES"
 .PP
@@ -673,7 +668,7 @@ call.  On Windows platforms, the handle is a file \fBHANDLE\fR when
 the channel was created with \fBTcl_OpenFileChannel\fR,
 \fBTcl_OpenCommandChannel\fR, or \fBTcl_MakeFileChannel\fR.  Other
 channel types may return a different type of handle on Windows
-platforms. 
+platforms.
 
 .SH "SEE ALSO"
 DString(3), fconfigure(n), filename(n), fopen(3), Tcl_CreateChannel(3)

doc/OpenTcp.3

@@ -24,18 +24,18 @@ Tcl_Channel
 \fBTcl_OpenTcpServer\fR(\fIinterp, port, myaddr, proc, clientData\fR)
 .sp
 .SH ARGUMENTS
-.AS Tcl_ChannelType newClientProcPtr in
+.AS Tcl_TcpAcceptProc clientData
 .AP Tcl_Interp *interp in
 Tcl interpreter to use for error reporting.  If non-NULL and an
 error occurs, an error message is left in the interpreter's result.
 .AP int port in
 A port number to connect to as a client or to listen on as a server.
-.AP "CONST char" *host in
+.AP "const char" *host in
 A string specifying a host name or address for the remote end of the connection.
 .AP int myport in
 A port number for the client's end of the socket.  If 0, a port number
 is allocated at random.
-.AP "CONST char" *myaddr in
+.AP "const char" *myaddr in
 A string specifying the host name or address for network interface to use
 for the local end of the connection.  If NULL, a default interface is
 chosen.
@@ -113,24 +113,24 @@ replacement for the standard channel.
 .PP
 \fBTcl_OpenTcpServer\fR opens a TCP socket on the local host on a specified
 \fIport\fR and uses the Tcl event mechanism to accept requests from clients
-to connect to it.  The \fImyaddr\fP argument specifies the network interface.
-If \fImyaddr\fP is NULL the special address INADDR_ANY should be used to
+to connect to it. The \fImyaddr\fR argument specifies the network interface.
+If \fImyaddr\fR is NULL the special address INADDR_ANY should be used to
 allow connections from any network interface.
 Each time a client connects to this socket, Tcl creates a channel
 for the new connection and invokes \fIproc\fR with information about
-the channel.  \fIProc\fR must match the following prototype:
+the channel. \fIProc\fR must match the following prototype:
 .CS
 typedef void Tcl_TcpAcceptProc(
-	ClientData \fIclientData\fR,
-	Tcl_Channel \fIchannel\fR,
-	char *\fIhostName\fR,
-	int \fIport\fP);
+        ClientData \fIclientData\fR,
+        Tcl_Channel \fIchannel\fR,
+        char *\fIhostName\fR,
+        int \fIport\fR);
 .CE
 .PP
 The \fIclientData\fR argument will be the same as the \fIclientData\fR
 argument to \fBTcl_OpenTcpServer\fR, \fIchannel\fR will be the handle
 for the new channel, \fIhostName\fR points to a string containing
-the name of the client host making the connection, and \fIport\fP
+the name of the client host making the connection, and \fIport\fR
 will contain the client's port number.
 The new channel
 is opened for both input and output. 
@@ -162,13 +162,11 @@ If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
 previously closed, the act of creating the new channel also assigns it as a
 replacement for the standard channel.
 
-.VS
 .SH "PLATFORM ISSUES"
 .PP
 On Unix platforms, the socket handle is a Unix file descriptor as
 returned by the \fBsocket\fR system call.  On the Windows platform, the
 socket handle is a \fBSOCKET\fR as defined in the WinSock API.
-.VE
 
 .SH "SEE ALSO"
 Tcl_OpenFileChannel(3), Tcl_RegisterChannel(3), vwait(n)

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, panic, panicVA \- report fatal error and abort
+Tcl_Panic, Tcl_PanicVA, Tcl_SetPanicProc \- report fatal error and abort
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -21,21 +21,15 @@ void
 void
 \fBTcl_SetPanicProc\fR(\fIpanicProc\fR)
 .sp
-void
-\fBpanic\fR(\fIformat\fR, \fIarg\fR, \fIarg\fR, \fI...\fR)
-.sp
-void
-\fBpanicVA\fR(\fIformat\fR, \fIargList\fR)
-.sp
 .SH ARGUMENTS
 .AS Tcl_PanicProc *panicProc
-.AP "CONST char*" format in
+.AP "const char*" format in
 A printf-style format string.
 .AP "" arg in
 Arguments matching the format string.
 .AP va_list argList in
 An argument list of arguments matching the format string.
-Must have been initialized using \fBTCL_VARARGS_START\fR,
+Must have been initialized using \fBva_start\fR,
 and cleared using \fBva_end\fR.
 .AP Tcl_PanicProc *panicProc in
 Procedure to report fatal error message and abort.
@@ -51,7 +45,7 @@ to display a message describing the error and abort the process.  The
 \fIformat\fR argument is a format string describing how to format the
 remaining arguments \fIarg\fR into an error message, according to the
 same formatting rules used by the \fBprintf\fR family of functions.  The
-same formatting rules are also used by the builtin Tcl command
+same formatting rules are also used by the built-in Tcl command
 \fBformat\fR.
 .PP
 In a freshly loaded Tcl library, \fBTcl_Panic\fR prints the formatted
@@ -65,8 +59,8 @@ type \fBTcl_PanicProc\fR:
 .PP
 .CS
 typedef void Tcl_PanicProc(
-	CONST char *\fBformat\fR,
-	\fBarg\fR, \fBarg\fR,...);
+        const char *\fBformat\fR,
+        \fBarg\fR, \fBarg\fR,...);
 .CE
 .PP
 After \fBTcl_SetPanicProc\fR returns, any future calls to
@@ -92,11 +86,7 @@ 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.  The
-procedures \fBpanic\fR and \fBpanicVA\fR are synonyms (implemented as
-macros) for \fBTcl_Panic\fR and \fBTcl_PanicVA\fR, respectively.  They
-exist to support old code; new code should use direct calls to
-\fBTcl_Panic\fR or \fBTcl_PanicVA\fR.
+taking a variable number of arguments it takes an argument list.
 
 .SH "SEE ALSO"
 abort(3), printf(3), exec(n), format(n)

doc/ParseCmd.3

@@ -14,22 +14,22 @@ Tcl_ParseCommand, Tcl_ParseExpr, Tcl_ParseBraces, Tcl_ParseQuotedString, Tcl_Par
 \fB#include <tcl.h>\fR
 .sp
 int
-\fBTcl_ParseCommand\fR(\fIinterp, string, numBytes, nested, parsePtr\fR)
+\fBTcl_ParseCommand\fR(\fIinterp, start, numBytes, nested, parsePtr\fR)
 .sp
 int
-\fBTcl_ParseExpr\fR(\fIinterp, string, numBytes, parsePtr\fR)
+\fBTcl_ParseExpr\fR(\fIinterp, start, numBytes, parsePtr\fR)
 .sp
 int
-\fBTcl_ParseBraces\fR(\fIinterp, string, numBytes, parsePtr, append, termPtr\fR)
+\fBTcl_ParseBraces\fR(\fIinterp, start, numBytes, parsePtr, append, termPtr\fR)
 .sp
 int
-\fBTcl_ParseQuotedString\fR(\fIinterp, string, numBytes, parsePtr, append, termPtr\fR)
+\fBTcl_ParseQuotedString\fR(\fIinterp, start, numBytes, parsePtr, append, termPtr\fR)
 .sp
 int
-\fBTcl_ParseVarName\fR(\fIinterp, string, numBytes, parsePtr, append\fR)
+\fBTcl_ParseVarName\fR(\fIinterp, start, numBytes, parsePtr, append\fR)
 .sp
-CONST char *
-\fBTcl_ParseVar\fR(\fIinterp, string, termPtr\fR)
+const char *
+\fBTcl_ParseVar\fR(\fIinterp, start, termPtr\fR)
 .sp
 \fBTcl_FreeParse\fR(\fIusedParsePtr\fR)
 .sp
@@ -39,7 +39,7 @@ Tcl_Obj *
 int
 \fBTcl_EvalTokensStandard\fR(\fIinterp, tokenPtr, numTokens\fR)
 .SH ARGUMENTS
-.AS Tcl_Interp *usedParsePtr
+.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;
@@ -47,12 +47,12 @@ 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.
-.AP "CONST char" *string in
+.AP "const char" *start in
 Pointer to first character in string to parse.
 .AP int numBytes in
-Number of bytes in \fIstring\fR, not including any terminating null
+Number of bytes in string to parse, not including any terminating null
 character.  If less than 0 then the script consists of all characters
-in \fIstring\fR up to the first null character.
+following \fIstart\fR up to the first null character.
 .AP int nested in
 Non-zero means that the script is part of a command substitution so an
 unquoted close bracket should be treated as a command terminator.  If zero,
@@ -69,7 +69,7 @@ Any previous information in this structure
 is ignored, unless \fIappend\fR is non-zero in a call to
 \fBTcl_ParseBraces\fR, \fBTcl_ParseQuotedString\fR,
 or \fBTcl_ParseVarName\fR.
-.AP "CONST char" **termPtr out
+.AP "const char" **termPtr out
 If not NULL, points to a location where
 \fBTcl_ParseBraces\fR, \fBTcl_ParseQuotedString\fR, and
 \fBTcl_ParseVar\fR will store a pointer to the character
@@ -90,7 +90,7 @@ and fills in the structure pointed to by \fIparsePtr\fR
 with a collection of tokens describing the information that was parsed.
 The procedures normally return \fBTCL_OK\fR.
 However, if an error occurs then they return \fBTCL_ERROR\fR,
-leave an error message in \fIinterp's\fR result
+leave an error message in \fIinterp\fR's result
 (if \fIinterp\fR is not NULL),
 and leave nothing in \fIparsePtr\fR.
 .PP
@@ -117,9 +117,9 @@ result, and no information is left at \fI*parsePtr\fR.
 .PP
 \fBTcl_ParseBraces\fR parses a string or command argument
 enclosed in braces such as
-\fB{hello}\fR or \fB{string \\t with \\t tabs}\fR
-from the beginning of its argument \fIstring\fR.
-The first character of \fIstring\fR must be \fB{\fR. 
+\fB{hello}\fR or \fB{string \et with \et tabs}\fR
+from the beginning of its argument \fIstart\fR.
+The first character of \fIstart\fR must be \fB{\fR. 
 If the braced string was parsed successfully,
 \fBTcl_ParseBraces\fR returns \fBTCL_OK\fR,
 fills in the structure pointed to by \fIparsePtr\fR
@@ -133,15 +133,15 @@ an error message is left in \fIinterp\fR's result,
 and no information is left at \fI*parsePtr\fR or \fI*termPtr\fR.
 .PP
 \fBTcl_ParseQuotedString\fR parses a double-quoted string such as
-\fB"sum is [expr $a+$b]"\fR
-from the beginning of the argument \fIstring\fR.
-The first character of \fIstring\fR must be \fB"\fR. 
+\fB"sum is [expr {$a+$b}]"\fR
+from the beginning of the argument \fIstart\fR.
+The first character of \fIstart\fR must be \fB\N'34'\fR. 
 If the double-quoted string was parsed successfully,
 \fBTcl_ParseQuotedString\fR returns \fBTCL_OK\fR,
 fills in the structure pointed to by \fIparsePtr\fR
 with information about the structure of the string
 (see below for details),
-and stores a pointer to the character just after the terminating \fB"\fR
+and stores a pointer to the character just after the terminating \fB\N'34'\fR
 in the location given by \fI*termPtr\fR.
 If an error occurs while parsing the string
 then \fBTCL_ERROR\fR is returned,
@@ -149,20 +149,20 @@ an error message is left in \fIinterp\fR's result,
 and no information is left at \fI*parsePtr\fR or \fI*termPtr\fR.
 .PP
 \fBTcl_ParseVarName\fR parses a Tcl variable reference such as
-\fB$abc\fR or \fB$x([expr $index + 1])\fR from the beginning of its
-\fIstring\fR argument.
-The first character of \fIstring\fR must be \fB$\fR. 
+\fB$abc\fR or \fB$x([expr {$index + 1}])\fR from the beginning of its
+\fIstart\fR argument.
+The first character of \fIstart\fR must be \fB$\fR. 
 If a variable name was parsed successfully, \fBTcl_ParseVarName\fR
 returns \fBTCL_OK\fR and fills in the structure pointed to by
 \fIparsePtr\fR with information about the structure of the variable name
 (see below for details).  If an error
 occurs while parsing the command then \fBTCL_ERROR\fR is returned, an
-error message is left in \fIinterp\fR's result (if \fIinterp\fR isn't
+error message is left in \fIinterp\fR's result (if \fIinterp\fR is not
 NULL), and no information is left at \fI*parsePtr\fR.
 .PP
 \fBTcl_ParseVar\fR parse a Tcl variable reference such as \fB$abc\fR
-or \fB$x([expr $index + 1])\fR from the beginning of its \fIstring\fR
-argument.  The first character of \fIstring\fR must be \fB$\fR.  If
+or \fB$x([expr {$index + 1}])\fR from the beginning of its \fIstart\fR
+argument.  The first character of \fIstart\fR must be \fB$\fR.  If
 the variable name is parsed successfully, \fBTcl_ParseVar\fR returns a
 pointer to the string value of the variable.  If an error occurs while
 parsing, then NULL is returned and an error message is left in
@@ -210,21 +210,21 @@ of \fBTcl_EvalTokens\fR is deprecated.
 return parse information in two data structures, Tcl_Parse and Tcl_Token:
 .CS
 typedef struct Tcl_Parse {
-	CONST char *\fIcommentStart\fR;
-	int \fIcommentSize\fR;
-	CONST char *\fIcommandStart\fR;
-	int \fIcommandSize\fR;
-	int \fInumWords\fR;
-	Tcl_Token *\fItokenPtr\fR;
-	int \fInumTokens\fR;
-	...
+        const char *\fIcommentStart\fR;
+        int \fIcommentSize\fR;
+        const char *\fIcommandStart\fR;
+        int \fIcommandSize\fR;
+        int \fInumWords\fR;
+        Tcl_Token *\fItokenPtr\fR;
+        int \fInumTokens\fR;
+        ...
 } Tcl_Parse;
 
 typedef struct Tcl_Token {
-    int \fItype\fR;
-    CONST char *\fIstart\fR;
-    int \fIsize\fR;
-    int \fInumComponents\fR;
+        int \fItype\fR;
+        const char *\fIstart\fR;
+        int \fIsize\fR;
+        int \fInumComponents\fR;
 } Tcl_Token;
 .CE
 .PP
@@ -285,6 +285,16 @@ This token has the same meaning as \fBTCL_TOKEN_WORD\fR, except that
 the word is guaranteed to consist of a single \fBTCL_TOKEN_TEXT\fR
 sub-token.  The \fInumComponents\fR field is always 1.
 .TP
+\fBTCL_TOKEN_EXPAND_WORD\fR
+.VS 8.5
+This token has the same meaning as \fBTCL_TOKEN_WORD\fR, except that
+the command parser notes this word began with the expansion
+prefix \fB{*}\fR, indicating that after substitution,
+the list value of this word should be expanded to form multiple
+arguments in command evaluation.  This
+token type can only be created by Tcl_ParseCommand.
+.VE 8.5
+.TP
 \fBTCL_TOKEN_TEXT\fR
 The token describes a range of literal text that is part of a word.
 The \fInumComponents\fR field is always 0.
@@ -294,7 +304,7 @@ The token describes a backslash sequence such as \fB\en\fR or \fB\e0xa3\fR.
 The \fInumComponents\fR field is always 0.
 .TP
 \fBTCL_TOKEN_COMMAND\fR
-The token describes a command whose result result must be substituted into
+The token describes a command whose result must be substituted into
 the word.  The token includes the square brackets that surround the
 command.  The \fInumComponents\fR field is always 0 (the nested command
 is not parsed; call \fBTcl_ParseCommand\fR recursively if you want to
@@ -344,7 +354,7 @@ this includes the sub-tokens for any nested \fBTCL_TOKEN_SUB_EXPR\fR tokens.
 \fBTCL_TOKEN_OPERATOR\fR
 The token describes one operator of an expression
 such as \fB&&\fR or \fBhypot\fR.
-An \fBTCL_TOKEN_OPERATOR\fR token is always preceded by a
+A \fBTCL_TOKEN_OPERATOR\fR token is always preceded by a
 \fBTCL_TOKEN_SUB_EXPR\fR token
 that describes the operator and its operands;
 the \fBTCL_TOKEN_SUB_EXPR\fR token's \fInumComponents\fR field
@@ -352,7 +362,7 @@ can be used to determine the number of operands.
 A binary operator such as \fB*\fR
 is followed by two \fBTCL_TOKEN_SUB_EXPR\fR tokens
 that describe its operands.
-A unary operator like \fB-\fR
+A unary operator like \fB\-\fR
 is followed by a single \fBTCL_TOKEN_SUB_EXPR\fR token
 for its operand.
 If the operator is a math function such as \fBlog10\fR,
@@ -373,12 +383,16 @@ is always 0.
 After \fBTcl_ParseCommand\fR returns, the first token pointed to by
 the \fItokenPtr\fR field of the
 Tcl_Parse structure always has type \fBTCL_TOKEN_WORD\fR or
-\fBTCL_TOKEN_SIMPLE_WORD\fR.  It is followed by the sub-tokens
+.VS 8.5
+\fBTCL_TOKEN_SIMPLE_WORD\fR or \fBTCL_TOKEN_EXPAND_WORD\fR.  
+It is followed by the sub-tokens
 that must be concatenated to produce the value of that word.
 The next token is the \fBTCL_TOKEN_WORD\fR or \fBTCL_TOKEN_SIMPLE_WORD\fR
-token for the second word, followed by sub-tokens for that
+of \fBTCL_TOKEN_EXPAND_WORD\fR token for the second word,
+followed by sub-tokens for that
 word, and so on until all \fInumWords\fR have been accounted
 for.
+.VE 8.5
 .PP
 After \fBTcl_ParseExpr\fR returns, the first token pointed to by
 the \fItokenPtr\fR field of the
@@ -415,7 +429,7 @@ Tcl_Parse structure depends on the contents of the quoted string.
 It will consist of one or more \fBTCL_TOKEN_TEXT\fR, \fBTCL_TOKEN_BS\fR,
 \fBTCL_TOKEN_COMMAND\fR, and \fBTCL_TOKEN_VARIABLE\fR sub-tokens.
 The array always contains at least one token;
-for example, if the argument \fIstring\fR is empty,
+for example, if the argument \fIstart\fR is empty,
 the array returned consists of a single \fBTCL_TOKEN_TEXT\fR token
 with a zero \fIsize\fR field.
 Only the token information in the Tcl_Parse structure
@@ -436,7 +450,7 @@ the \fIcommentStart\fR, \fIcommentSize\fR,
 .PP
 All of the character pointers in the
 Tcl_Parse and Tcl_Token structures refer
-to characters in the \fIstring\fR argument passed to
+to characters in the \fIstart\fR argument passed to
 \fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR,
 \fBTcl_ParseQuotedString\fR, and \fBTcl_ParseVarName\fR.
 .PP

doc/PkgRequire.3

@@ -8,21 +8,24 @@
 .TH Tcl_PkgRequire 3 7.5 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_PkgRequire, Tcl_PkgRequireEx, Tcl_PkgPresent, Tcl_PkgPresentEx, Tcl_PkgProvide, Tcl_PkgProvideEx \- package version control
+Tcl_PkgRequire, Tcl_PkgRequireEx, Tcl_PkgRequireProc, Tcl_PkgPresent, Tcl_PkgPresentEx, Tcl_PkgProvide, Tcl_PkgProvideEx \- package version control
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
 .sp
-CONST char *
+const char *
 \fBTcl_PkgRequire\fR(\fIinterp, name, version, exact\fR)
 .sp
-CONST char *
+const char *
 \fBTcl_PkgRequireEx\fR(\fIinterp, name, version, exact, clientDataPtr\fR)
 .sp
-CONST char *
+int
+\fBTcl_PkgRequireProc\fR(\fIinterp, name, objc, objv, clientDataPtr\fR)
+.sp
+const char *
 \fBTcl_PkgPresent\fR(\fIinterp, name, version, exact\fR)
 .sp
-CONST char *
+const char *
 \fBTcl_PkgPresentEx\fR(\fIinterp, name, version, exact, clientDataPtr\fR)
 .sp
 int
@@ -31,12 +34,12 @@ int
 int
 \fBTcl_PkgProvideEx\fR(\fIinterp, name, version, clientData\fR)
 .SH ARGUMENTS
-.AS ClientData clientDataPtr
+.AS ClientData clientDataPtr out
 .AP Tcl_Interp *interp in
 Interpreter where package is needed or available.
-.AP "CONST char" *name in
+.AP "const char" *name in
 Name of package.
-.AP "CONST char" *version in
+.AP "const char" *version in
 A version string consisting of one or more decimal numbers
 separated by dots.
 .AP int exact in
@@ -51,7 +54,12 @@ Arbitrary value to be associated with the package.
 Pointer to place to store the value associated with the matching
 package. It is only changed if the pointer is not NULL and the
 function completed successfully.
+.AP int objc in
+Number of requirements.
+.AP Tcl_Obj* objv[] in
+Array of requirements.
 .BE
+
 .SH DESCRIPTION
 .PP
 These procedures provide C-level interfaces to Tcl's package and
@@ -71,13 +79,18 @@ that is provided in the interpreter (which may be different than
 \fIversion\fR); if an error occurs they return NULL and leave an error 
 message in the interpreter's result.
 .PP
-\fBTcl_PkgProvide\fR returns TCL_OK if it completes successfully;
-if an error occurs it returns TCL_ERROR and leaves an error message
+\fBTcl_PkgProvide\fR returns \fBTCL_OK\fR if it completes successfully;
+if an error occurs it returns \fBTCL_ERROR\fR and leaves an error message
 in the interpreter's result.
 .PP
 \fBTcl_PkgProvideEx\fR, \fBTcl_PkgPresentEx\fR and \fBTcl_PkgRequireEx\fR
 allow the setting and retrieving of the client data associated with
 the package. In all other respects they are equivalent to the matching
 functions.
+.PP
+\fBTcl_PkgRequireProc\fR is the form of \fBpackage require\fR handling
+multiple requirements. The other forms are present for backward
+compatibility and translate their invocations to this form.
+
 .SH KEYWORDS
 package, present, provide, require, version

doc/Preserve.3

@@ -9,7 +9,7 @@
 .TH Tcl_Preserve 3 7.5 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_Preserve, Tcl_Release, Tcl_EventuallyFree \- avoid freeing storage while it's being used
+Tcl_Preserve, Tcl_Release, Tcl_EventuallyFree \- avoid freeing storage while it is being used
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -36,7 +36,7 @@ having to do with widget deletion, but are also useful in many other
 situations.  When a widget is deleted, its
 widget record (the structure holding information specific to the
 widget) must be returned to the storage allocator.
-However, it's possible that the widget record is in active use
+However, it is possible that the widget record is in active use
 by one of the procedures on the stack at the time of the deletion.
 This can happen, for example, if the command associated with a button
 widget causes the button to be destroyed:  an X event causes an