Import Tcl 8.5.15 (as of svn r89086)

README

@@ -1,41 +1,185 @@
-README:  Tk
-    This is the Tk 8.6.8 source distribution.
+README:  Tcl
+    This is the Tcl 8.5.15 source distribution.
 	http://sourceforge.net/projects/tcl/files/Tcl/
-    You can get any source release of Tk from the URL above.
+    You can get any source release of Tcl from the URL above.
+
+Contents
+--------
+    1. Introduction
+    2. Documentation
+    3. Compiling and installing Tcl
+    4. Development tools
+    5. Tcl newsgroup
+    6. The Tcler's Wiki
+    7. Mailing lists
+    8. Support and Training
+    9. Tracking Development
+    10. Thank You
 
 1. Introduction
 ---------------
+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 Mac OS X.
+Tcl can also be used for a variety of web-related tasks and for creating
+powerful command languages for applications.
 
-This directory contains the sources and documentation for Tk, an X11
-toolkit implemented with the Tcl scripting language.
-
-For details on features, incompatibilities, and potential problems with
-this release, see the Tcl/Tk 8.6 Web page at
-
-	http://www.tcl.tk/software/tcltk/8.6.html
-
-or refer to the "changes" file in this directory, which contains a
-historical record of all changes to Tk.
-
-Tk is maintained, enhanced, and distributed freely by the Tcl community.
+Tcl is maintained, enhanced, and distributed freely by the Tcl community.
 Source code development and tracking of bug reports and feature requests
 takes place at:
 
-	http://core.tcl.tk/tk/
+	http://core.tcl.tk/
 
-with the Tcl Developer Xchange at:
+Tcl/Tk release and mailing list services are hosted by SourceForge:
+
+	http://sourceforge.net/projects/tcl/
+
+with the Tcl Developer Xchange hosted at:
 
 	http://www.tcl.tk/
 
-Tk is a freely available open source package.  You can do virtually
+Tcl is a freely available open source package.  You can do virtually
 anything you like with it, such as modifying it, redistributing it,
 and selling it either in whole or in part.  See the file
 "license.terms" for complete information.
 
-2. See Tcl README
------------------
+2. Documentation
+----------------
 
-Please see the README file that comes with the associated Tcl release
-for more information.  There are pointers there to extensive
-documentation.  In addition, there are additional README files
-in the subdirectories of this distribution.
+Extensive documentation is available at our website.
+The home page for this release, including new features, is
+	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/Tcl/
+
+Information about Tcl itself can be found at
+	http://www.tcl.tk/about/
+
+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.5 online,
+visit the URL:
+	http://www.tcl.tk/man/tcl8.5/
+
+2a. Unix Documentation
+----------------------
+
+The "doc" subdirectory in this release contains a complete set of
+reference manual entries for Tcl.  Files with extension ".1" are for
+programs (for example, tclsh.1); files with extension ".3" are for C
+library procedures; and files with extension ".n" describe Tcl
+commands.  The file "doc/Tcl.n" gives a quick summary of the Tcl
+language syntax.  To print any of the man pages on Unix, cd to the
+"doc" directory and invoke your favorite variant of troff using the
+normal -man macros, for example
+
+		ditroff -man Tcl.n
+
+to print Tcl.n.  If Tcl has been installed correctly and your "man" program
+supports it, you should be able to access the Tcl manual entries using the
+normal "man" mechanisms, such as
+
+		man Tcl
+
+2b. Windows Documentation
+-------------------------
+
+The "doc" subdirectory in this release contains a complete set of Windows
+help files for Tcl.  Once you install this Tcl release, a shortcut to the
+Windows help Tcl documentation will appear in the "Start" menu:
+
+	Start | Programs | Tcl | Tcl Help
+
+3. Compiling and installing Tcl
+-------------------------------
+
+There are brief notes in the unix/README, win/README, and macosx/README about
+compiling on these different platforms.  There is additional information
+about building Tcl from sources at
+
+	http://www.tcl.tk/doc/howto/compile.html
+
+4. Development tools
+---------------------------
+
+ActiveState produces a high quality set of commercial quality development
+tools that is available to accelerate your Tcl application development.
+Tcl Dev Kit builds on the earlier TclPro toolset and provides a debugger,
+static code checker, single-file wrapping utility, bytecode compiler and
+more.  More information can be found at
+
+	http://www.ActiveState.com/Tcl
+
+5. Tcl newsgroup
+----------------
+
+There is a USENET news group, "comp.lang.tcl", intended for the exchange of
+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. Tcl'ers Wiki
+---------------
+
+A Wiki-based open community site covering all aspects of Tcl/Tk is at:
+
+	http://wiki.tcl.tk/
+
+It is dedicated to the Tcl programming language and its extensions.  A
+wealth of useful information can be found there.  It contains code
+snippets, references to papers, books, and FAQs, as well as pointers to
+development tools, extensions, and applications.  You can also recommend
+additional URLs by editing the wiki yourself.
+
+7. Mailing lists
+----------------
+
+Several mailing lists are hosted at SourceForge to discuss development or
+use issues (like Macintosh and Windows topics).  For more information and
+to subscribe, visit:
+
+	http://sourceforge.net/projects/tcl/
+
+and go to the Mailing Lists page.
+
+8. Support and Training
+------------------------
+
+We are very interested in receiving bug reports, patches, and suggestions
+for improvements.  We prefer that you send this information to us as
+tickets entered into our tracker at:
+
+	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 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
+the size of the installed base.
+
+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 Web site for links to other organizations that offer
+Tcl/Tk training:
+
+	http://wiki.tcl.tk/training
+
+9. Tracking Development
+-----------------------
+
+Tcl is developed in public.  To keep an eye on how Tcl is changing, see
+	http://core.tcl.tk/
+
+10. Thank You
+-------------
+
+We'd like to express our thanks to the Tcl community for all the
+helpful suggestions, bug reports, and patches we have received.
+Tcl/Tk has improved vastly and will continue to do so with your help.

README.md

@@ -1,2 +0,0 @@
-# cpython-source-deps
-Source for packages that the cpython build process depends on

bitmaps/error.xbm

@@ -1,8 +0,0 @@
-#define error_width 17
-#define error_height 17
-static unsigned char error_bits[] = {
-   0xf0, 0x0f, 0x00, 0x58, 0x15, 0x00, 0xac, 0x2a, 0x00, 0x16, 0x50, 0x00,
-   0x2b, 0xa0, 0x00, 0x55, 0x40, 0x01, 0xa3, 0xc0, 0x00, 0x45, 0x41, 0x01,
-   0x83, 0xc2, 0x00, 0x05, 0x45, 0x01, 0x03, 0xca, 0x00, 0x05, 0x74, 0x01,
-   0x0a, 0xa8, 0x00, 0x14, 0x58, 0x00, 0xe8, 0x2f, 0x00, 0x50, 0x15, 0x00,
-   0xa0, 0x0a, 0x00};

bitmaps/gray12.xbm

@@ -1,6 +0,0 @@
-#define gray12_width 16
-#define gray12_height 16
-static unsigned char gray12_bits[] = {
-   0x00, 0x00, 0x22, 0x22, 0x00, 0x00, 0x88, 0x88, 0x00, 0x00, 0x22, 0x22,
-   0x00, 0x00, 0x88, 0x88, 0x00, 0x00, 0x22, 0x22, 0x00, 0x00, 0x88, 0x88,
-   0x00, 0x00, 0x22, 0x22, 0x00, 0x00, 0x88, 0x88};

bitmaps/gray25.xbm

@@ -1,6 +0,0 @@
-#define gray25_width 16
-#define gray25_height 16
-static unsigned char gray25_bits[] = {
-   0x88, 0x88, 0x22, 0x22, 0x88, 0x88, 0x22, 0x22, 0x88, 0x88, 0x22, 0x22,
-   0x88, 0x88, 0x22, 0x22, 0x88, 0x88, 0x22, 0x22, 0x88, 0x88, 0x22, 0x22,
-   0x88, 0x88, 0x22, 0x22, 0x88, 0x88, 0x22, 0x22};

bitmaps/gray50.xbm

@@ -1,6 +0,0 @@
-#define gray50_width 16
-#define gray50_height 16
-static unsigned char gray50_bits[] = {
-   0x55, 0x55, 0xaa, 0xaa, 0x55, 0x55, 0xaa, 0xaa, 0x55, 0x55, 0xaa, 0xaa,
-   0x55, 0x55, 0xaa, 0xaa, 0x55, 0x55, 0xaa, 0xaa, 0x55, 0x55, 0xaa, 0xaa,
-   0x55, 0x55, 0xaa, 0xaa, 0x55, 0x55, 0xaa, 0xaa};

bitmaps/gray75.xbm

@@ -1,6 +0,0 @@
-#define gray75_width 16
-#define gray75_height 16
-static unsigned char gray75_bits[] = {
-   0x77, 0x77, 0xdd, 0xdd, 0x77, 0x77, 0xdd, 0xdd, 0x77, 0x77, 0xdd, 0xdd,
-   0x77, 0x77, 0xdd, 0xdd, 0x77, 0x77, 0xdd, 0xdd, 0x77, 0x77, 0xdd, 0xdd,
-   0x77, 0x77, 0xdd, 0xdd, 0x77, 0x77, 0xdd, 0xdd};

bitmaps/hourglass.xbm

@@ -1,9 +0,0 @@
-#define hourglass_width 19
-#define hourglass_height 21
-static unsigned char hourglass_bits[] = {
-   0xff, 0xff, 0x07, 0x55, 0x55, 0x05, 0xa2, 0x2a, 0x03, 0x66, 0x15, 0x01,
-   0xa2, 0x2a, 0x03, 0x66, 0x15, 0x01, 0xc2, 0x0a, 0x03, 0x46, 0x05, 0x01,
-   0x82, 0x0a, 0x03, 0x06, 0x05, 0x01, 0x02, 0x03, 0x03, 0x86, 0x05, 0x01,
-   0xc2, 0x0a, 0x03, 0x66, 0x15, 0x01, 0xa2, 0x2a, 0x03, 0x66, 0x15, 0x01,
-   0xa2, 0x2a, 0x03, 0x66, 0x15, 0x01, 0xa2, 0x2a, 0x03, 0xff, 0xff, 0x07,
-   0xab, 0xaa, 0x02};

bitmaps/info.xbm

@@ -1,5 +0,0 @@
-#define info_width 8
-#define info_height 21
-static unsigned char info_bits[] = {
-   0x3c, 0x2a, 0x16, 0x2a, 0x14, 0x00, 0x00, 0x3f, 0x15, 0x2e, 0x14, 0x2c,
-   0x14, 0x2c, 0x14, 0x2c, 0x14, 0x2c, 0xd7, 0xab, 0x55};

bitmaps/questhead.xbm

@@ -1,9 +0,0 @@
-#define questhead_width 20
-#define questhead_height 22
-static unsigned char questhead_bits[] = {
-   0xf8, 0x1f, 0x00, 0xac, 0x2a, 0x00, 0x56, 0x55, 0x00, 0xeb, 0xaf, 0x00,
-   0xf5, 0x5f, 0x01, 0xfb, 0xbf, 0x00, 0x75, 0x5d, 0x01, 0xfb, 0xbe, 0x02,
-   0x75, 0x5d, 0x05, 0xab, 0xbe, 0x0a, 0x55, 0x5f, 0x07, 0xab, 0xaf, 0x00,
-   0xd6, 0x57, 0x01, 0xac, 0xab, 0x00, 0xd8, 0x57, 0x00, 0xb0, 0xaa, 0x00,
-   0x50, 0x55, 0x00, 0xb0, 0x0b, 0x00, 0xd0, 0x17, 0x00, 0xb0, 0x0b, 0x00,
-   0x58, 0x15, 0x00, 0xa8, 0x2a, 0x00};

bitmaps/question.xbm

@@ -1,10 +0,0 @@
-#define question_width 17
-#define question_height 27
-static unsigned char question_bits[] = {
-   0xf0, 0x0f, 0x00, 0x58, 0x15, 0x00, 0xac, 0x2a, 0x00, 0x56, 0x55, 0x00,
-   0x2b, 0xa8, 0x00, 0x15, 0x50, 0x01, 0x0b, 0xa0, 0x00, 0x05, 0x60, 0x01,
-   0x0b, 0xa0, 0x00, 0x05, 0x60, 0x01, 0x0b, 0xb0, 0x00, 0x00, 0x58, 0x01,
-   0x00, 0xaf, 0x00, 0x80, 0x55, 0x00, 0xc0, 0x2a, 0x00, 0x40, 0x15, 0x00,
-   0xc0, 0x02, 0x00, 0x40, 0x01, 0x00, 0xc0, 0x02, 0x00, 0x40, 0x01, 0x00,
-   0xc0, 0x02, 0x00, 0x00, 0x00, 0x00, 0x80, 0x01, 0x00, 0xc0, 0x02, 0x00,
-   0x40, 0x01, 0x00, 0xc0, 0x02, 0x00, 0x00, 0x01, 0x00};

bitmaps/warning.xbm

@@ -1,5 +0,0 @@
-#define warning_width 6
-#define warning_height 19
-static unsigned char warning_bits[] = {
-   0x0c, 0x16, 0x2b, 0x15, 0x2b, 0x15, 0x2b, 0x16, 0x0a, 0x16, 0x0a, 0x16,
-   0x0a, 0x00, 0x00, 0x1e, 0x0a, 0x16, 0x0a};

compat/README

@@ -0,0 +1,6 @@
+This directory contains various header and code files that are
+used make Tcl compatible with various releases of UNIX and UNIX-like
+systems.  Typically, files from this directory are used to compile
+Tcl when a system doesn't contain the corresponding files or when
+they are known to be incorrect.  When the whole world becomes POSIX-
+compliant this directory should be unnecessary.

compat/dirent.h

@@ -0,0 +1,21 @@
+/*
+ * dirent.h --
+ *
+ *	This file is a replacement for <dirent.h> in systems that
+ *	support the old BSD-style <sys/dir.h> with a "struct direct".
+ *
+ * Copyright (c) 1991 The Regents of the University of California.
+ * Copyright (c) 1994 Sun Microsystems, Inc.
+ *
+ * See the file "license.terms" for information on usage and redistribution
+ * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+ */
+
+#ifndef _DIRENT
+#define _DIRENT
+
+#include <sys/dir.h>
+
+#define dirent direct
+
+#endif /* _DIRENT */

compat/dirent2.h

@@ -0,0 +1,53 @@
+/*
+ * dirent.h --
+ *
+ *	Declarations of a library of directory-reading procedures
+ *	in the POSIX style ("struct dirent").
+ *
+ * Copyright (c) 1991 The Regents of the University of California.
+ * Copyright (c) 1994 Sun Microsystems, Inc.
+ *
+ * See the file "license.terms" for information on usage and redistribution
+ * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+ */
+
+#ifndef _DIRENT
+#define _DIRENT
+
+/*
+ * Dirent structure, which holds information about a single
+ * directory entry.
+ */
+
+#define MAXNAMLEN 255
+#define DIRBLKSIZ 512
+
+struct dirent {
+    long d_ino;			/* Inode number of entry */
+    short d_reclen;		/* Length of this record */
+    short d_namlen;		/* Length of string in d_name */
+    char d_name[MAXNAMLEN + 1];	/* Name must be no longer than this */
+};
+
+/*
+ * State that keeps track of the reading of a directory (clients
+ * should never look inside this structure;  the fields should
+ * only be accessed by the library procedures).
+ */
+
+typedef struct _dirdesc {
+    int dd_fd;
+    long dd_loc;
+    long dd_size;
+    char dd_buf[DIRBLKSIZ];
+} DIR;
+
+/*
+ * Procedures defined for reading directories:
+ */
+
+extern void		closedir (DIR *dirp);
+extern DIR *		opendir (char *name);
+extern struct dirent *	readdir (DIR *dirp);
+
+#endif /* _DIRENT */

compat/dlfcn.h

@@ -0,0 +1,58 @@
+/*
+ * dlfcn.h --
+ *
+ *	This file provides a replacement for the header file "dlfcn.h"
+ *	on systems where dlfcn.h is missing.  It's primary use is for
+ *	AIX, where Tcl emulates the dl library.
+ *
+ *	This file is subject to the following copyright notice, which is
+ *	different from the notice used elsewhere in Tcl but rougly
+ *	equivalent in meaning.
+ *
+ *	Copyright (c) 1992,1993,1995,1996, Jens-Uwe Mager, Helios Software GmbH
+ *	Not derived from licensed software.
+ *
+ *	Permission is granted to freely use, copy, modify, and redistribute
+ *	this software, provided that the author is not construed to be liable
+ *	for any results of using the software, alterations are clearly marked
+ *	as such, and this notice is not modified.
+ */
+
+/*
+ * This is an unpublished work copyright (c) 1992 HELIOS Software GmbH
+ * 30159 Hannover, Germany
+ */
+
+#ifndef __dlfcn_h__
+#define __dlfcn_h__
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*
+ * Mode flags for the dlopen routine.
+ */
+#define RTLD_LAZY	1	/* lazy function call binding */
+#define RTLD_NOW	2	/* immediate function call binding */
+#define RTLD_GLOBAL	0x100	/* allow symbols to be global */
+
+/*
+ * To be able to intialize, a library may provide a dl_info structure
+ * that contains functions to be called to initialize and terminate.
+ */
+struct dl_info {
+	void (*init) (void);
+	void (*fini) (void);
+};
+
+void *dlopen (const char *path, int mode);
+void *dlsym (void *handle, const char *symbol);
+char *dlerror (void);
+int dlclose (void *handle);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* __dlfcn_h__ */

compat/fixstrtod.c

@@ -0,0 +1,36 @@
+/* 
+ * fixstrtod.c --
+ *
+ *	Source code for the "fixstrtod" procedure.  This procedure is
+ *	used in place of strtod under Solaris 2.4, in order to fix
+ *	a bug where the "end" pointer gets set incorrectly.
+ *
+ * Copyright (c) 1995 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 <stdio.h>
+
+#undef strtod
+
+/*
+ * Declare strtod explicitly rather than including stdlib.h, since in
+ * somes systems (e.g. SunOS 4.1.4) stdlib.h doesn't declare strtod.
+ */
+
+extern double strtod(char *, char **);
+
+double
+fixstrtod(
+    char *string,
+    char **endPtr)
+{
+    double d;
+    d = strtod(string, endPtr);
+    if ((endPtr != NULL) && (*endPtr != string) && ((*endPtr)[-1] == 0)) {
+	*endPtr -= 1;
+    }
+    return d;
+}

compat/float.h

@@ -0,0 +1,14 @@
+/*
+ * float.h --
+ *
+ *	This is a dummy header file to #include in Tcl when there
+ *	is no float.h in /usr/include.  Right now this file is empty:
+ *	Tcl contains #ifdefs to deal with the lack of definitions;
+ *	all it needs is for the #include statement to work.
+ *
+ * Copyright (c) 1993 The Regents of the University of California.
+ * Copyright (c) 1994 Sun Microsystems, Inc.
+ *
+ * See the file "license.terms" for information on usage and redistribution
+ * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+ */

compat/gettod.c

@@ -0,0 +1,30 @@
+/* 
+ * gettod.c --
+ *
+ *	This file provides the gettimeofday function on systems
+ *	that only have the System V ftime function.
+ *
+ * Copyright (c) 1995 Sun Microsystems, Inc.
+ *
+ * See the file "license.terms" for information on usage and redistribution
+ * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+ */
+
+#include "tclPort.h"
+#include <sys/timeb.h>
+
+#undef timezone
+
+int
+gettimeofday(
+    struct timeval *tp,
+    struct timezone *tz)
+{
+    struct timeb t;
+
+    ftime(&t);
+    tp->tv_sec = t.time;
+    tp->tv_usec = t. millitm * 1000;
+    return 0;
+}
+

compat/license.terms

@@ -1,7 +1,7 @@
 This software is copyrighted by the Regents of the University of
 California, Sun Microsystems, Inc., Scriptics Corporation, ActiveState
-Corporation, Apple Inc. and other parties.  The following terms apply to
-all files associated with the software unless explicitly disclaimed in
+Corporation and other parties.  The following terms apply to all files
+associated with the software unless explicitly disclaimed in
 individual files.
 
 The authors hereby grant permission to use, copy, modify, distribute,

compat/limits.h

@@ -0,0 +1,22 @@
+/*
+ * limits.h --
+ *
+ *	This is a dummy header file to #include in Tcl when there
+ *	is no limits.h in /usr/include.  There are only a few
+ *	definitions here;  also see tclPort.h, which already
+ *	#defines some of the things here if they're not arleady
+ *	defined.
+ *
+ * Copyright (c) 1991 The Regents of the University of California.
+ * Copyright (c) 1994 Sun Microsystems, Inc.
+ *
+ * See the file "license.terms" for information on usage and redistribution
+ * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+ */
+
+#define LONG_MIN		0x80000000
+#define LONG_MAX		0x7fffffff
+#define INT_MIN			0x80000000
+#define INT_MAX			0x7fffffff
+#define SHRT_MIN		0x8000
+#define SHRT_MAX		0x7fff

compat/memcmp.c

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

compat/opendir.c

@@ -0,0 +1,110 @@
+/* 
+ * opendir.c --
+ *
+ *	This file provides dirent-style directory-reading procedures for V7
+ *	Unix systems that don't have such procedures. The origin of this code
+ *	is unclear, but it seems to have come originally from Larry Wall.
+ */
+
+#include "tclInt.h"
+
+#undef DIRSIZ
+#define DIRSIZ(dp) \
+    ((sizeof (struct dirent) - (MAXNAMLEN+1)) + (((dp)->d_namlen+1 + 3) &~ 3))
+
+/*
+ * open a directory.
+ */
+
+DIR *
+opendir(
+    char *name)
+{
+    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;
+}
+
+/*
+ * read an old style directory entry and present it as a new one
+ */
+#ifndef pyr
+#define	ODIRSIZ	14
+
+struct	olddirect {
+    ino_t od_ino;
+    char od_name[ODIRSIZ];
+};
+#else	/* a Pyramid in the ATT universe */
+#define	ODIRSIZ	248
+
+struct	olddirect {
+    long od_ino;
+    short od_fill1, od_fill2;
+    char od_name[ODIRSIZ];
+};
+#endif
+
+/*
+ * get next entry in a directory.
+ */
+
+struct dirent *
+readdir(
+    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(
+    register DIR *dirp)
+{
+    close(dirp->dd_fd);
+    dirp->dd_fd = -1;
+    dirp->dd_loc = 0;
+    ckfree((char *) dirp);
+}

compat/string.h

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

compat/strncasecmp.c

@@ -0,0 +1,136 @@
+/* 
+ * strncasecmp.c --
+ *
+ *	Source code for the "strncasecmp" library routine.
+ *
+ * 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.
+ */
+
+#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.
+ */
+
+static unsigned char charmap[] = {
+    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
+    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
+    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
+    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
+    0x20, 0x21, 0x22, 0x23, 0x24, 0x25, 0x26, 0x27,
+    0x28, 0x29, 0x2a, 0x2b, 0x2c, 0x2d, 0x2e, 0x2f,
+    0x30, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37,
+    0x38, 0x39, 0x3a, 0x3b, 0x3c, 0x3d, 0x3e, 0x3f,
+    0x40, 0x61, 0x62, 0x63, 0x64, 0x65, 0x66, 0x67,
+    0x68, 0x69, 0x6a, 0x6b, 0x6c, 0x6d, 0x6e, 0x6f,
+    0x70, 0x71, 0x72, 0x73, 0x74, 0x75, 0x76, 0x77,
+    0x78, 0x79, 0x7a, 0x5b, 0x5c, 0x5d, 0x5e, 0x5f,
+    0x60, 0x61, 0x62, 0x63, 0x64, 0x65, 0x66, 0x67,
+    0x68, 0x69, 0x6a, 0x6b, 0x6c, 0x6d, 0x6e, 0x6f,
+    0x70, 0x71, 0x72, 0x73, 0x74, 0x75, 0x76, 0x77,
+    0x78, 0x79, 0x7a, 0x7b, 0x7c, 0x7d, 0x7e, 0x7f,
+    0x80, 0x81, 0x82, 0x83, 0x84, 0x85, 0x86, 0x87,
+    0x88, 0x89, 0x8a, 0x8b, 0x8c, 0x8d, 0x8e, 0x8f,
+    0x90, 0x91, 0x92, 0x93, 0x94, 0x95, 0x96, 0x97,
+    0x98, 0x99, 0x9a, 0x9b, 0x9c, 0x9d, 0x9e, 0x9f,
+    0xa0, 0xa1, 0xa2, 0xa3, 0xa4, 0xa5, 0xa6, 0xa7,
+    0xa8, 0xa9, 0xaa, 0xab, 0xac, 0xad, 0xae, 0xaf,
+    0xb0, 0xb1, 0xb2, 0xb3, 0xb4, 0xb5, 0xb6, 0xb7,
+    0xb8, 0xb9, 0xba, 0xbb, 0xbc, 0xbd, 0xbe, 0xbf,
+    0xc0, 0xe1, 0xe2, 0xe3, 0xe4, 0xc5, 0xe6, 0xe7,
+    0xe8, 0xe9, 0xea, 0xeb, 0xec, 0xed, 0xee, 0xef,
+    0xf0, 0xf1, 0xf2, 0xf3, 0xf4, 0xf5, 0xf6, 0xf7,
+    0xf8, 0xf9, 0xfa, 0xdb, 0xdc, 0xdd, 0xde, 0xdf,
+    0xe0, 0xe1, 0xe2, 0xe3, 0xe4, 0xe5, 0xe6, 0xe7,
+    0xe8, 0xe9, 0xea, 0xeb, 0xec, 0xed, 0xee, 0xef,
+    0xf0, 0xf1, 0xf2, 0xf3, 0xf4, 0xf5, 0xf6, 0xf7,
+    0xf8, 0xf9, 0xfa, 0xfb, 0xfc, 0xfd, 0xfe, 0xff,
+};
+
+/*
+ * Here are the prototypes just in case they are not included in tclPort.h.
+ */
+
+int		strncasecmp(CONST char *s1, CONST char *s2, size_t n);
+int		strcasecmp(CONST char *s1, CONST char *s2);
+
+/*
+ *----------------------------------------------------------------------
+ *
+ * strcasecmp --
+ *
+ *	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.
+ *
+ * Side effects:
+ *	None.
+ *
+ *----------------------------------------------------------------------
+ */
+
+int
+strcasecmp(
+    CONST char *s1,		/* First string. */
+    CONST char *s2)		/* Second string. */
+{
+    unsigned char u1, u2;
+
+    for ( ; ; s1++, s2++) {
+	u1 = (unsigned char) *s1;
+	u2 = (unsigned char) *s2;
+	if ((u1 == '\0') || (charmap[u1] != charmap[u2])) {
+	    break;
+	}
+    }
+    return charmap[u1] - charmap[u2];
+}
+
+/*
+ *----------------------------------------------------------------------
+ *
+ * strncasecmp --
+ *
+ *	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.
+ *
+ * Side effects:
+ *	None.
+ *
+ *----------------------------------------------------------------------
+ */
+
+int
+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). */
+{
+    unsigned char u1, u2;
+
+    for (; length != 0; length--, s1++, s2++) {
+	u1 = (unsigned char) *s1;
+	u2 = (unsigned char) *s2;
+	if (charmap[u1] != charmap[u2]) {
+	    return charmap[u1] - charmap[u2];
+	}
+	if (u1 == '\0') {
+	    return 0;
+	}
+    }
+    return 0;
+}

compat/strstr.c

@@ -0,0 +1,70 @@
+/* 
+ * strstr.c --
+ *
+ *	Source code for the "strstr" library routine.
+ *
+ * Copyright (c) 1988-1993 The Regents of the University of California.
+ * Copyright (c) 1994 Sun Microsystems, Inc.
+ *
+ * See the file "license.terms" for information on usage and redistribution of
+ * this file, and for a DISCLAIMER OF ALL WARRANTIES.
+ */
+
+#include "tcl.h"
+#ifndef NULL
+#define NULL 0
+#endif
+
+/*
+ *----------------------------------------------------------------------
+ *
+ * strstr --
+ *
+ *	Locate the first instance of a substring in a string.
+ *
+ * Results:
+ *	If string contains substring, the return value is the location of the
+ *	first matching instance of substring in string. If string doesn't
+ *	contain substring, the return value is 0. Matching is done on an exact
+ *	character-for-character basis with no wildcards or special characters.
+ *
+ * Side effects:
+ *	None.
+ *
+ *----------------------------------------------------------------------
+ */
+
+char *
+strstr(
+    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.
+     */
+
+    b = substring;
+    if (*b == 0) {
+	return string;
+    }
+    for ( ; *string != 0; string += 1) {
+	if (*string != *b) {
+	    continue;
+	}
+	a = string;
+	while (1) {
+	    if (*b == 0) {
+		return string;
+	    }
+	    if (*a++ != *b++) {
+		break;
+	    }
+	}
+	b = substring;
+    }
+    return NULL;
+}

compat/strtod.c

@@ -0,0 +1,252 @@
+/* 
+ * strtod.c --
+ *
+ *	Source code for the "strtod" library procedure.
+ *
+ * Copyright (c) 1988-1993 The Regents of the University of California.
+ * Copyright (c) 1994 Sun Microsystems, Inc.
+ *
+ * See the file "license.terms" for information on usage and redistribution
+ * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+ */
+
+#include "tclInt.h"
+#include <ctype.h>
+
+#ifndef TRUE
+#define TRUE 1
+#define FALSE 0
+#endif
+#ifndef NULL
+#define NULL 0
+#endif
+
+static int maxExponent = 511;	/* Largest possible base 10 exponent.  Any
+				 * exponent larger than this will already
+				 * produce underflow or overflow, so there's
+				 * no need to worry about additional digits.
+				 */
+static double powersOf10[] = {	/* Table giving binary powers of 10.  Entry */
+    10.,			/* is 10^2^i.  Used to convert decimal */
+    100.,			/* exponents into floating-point numbers. */
+    1.0e4,
+    1.0e8,
+    1.0e16,
+    1.0e32,
+    1.0e64,
+    1.0e128,
+    1.0e256
+};
+
+/*
+ *----------------------------------------------------------------------
+ *
+ * strtod --
+ *
+ *	This procedure converts a floating-point number from an ASCII
+ *	decimal representation to internal double-precision format.
+ *
+ * Results:
+ *	The return value is the double-precision floating-point
+ *	representation of the characters in string.  If endPtr isn't
+ *	NULL, then *endPtr is filled in with the address of the
+ *	next character after the last one that was part of the
+ *	floating-point number.
+ *
+ * Side effects:
+ *	None.
+ *
+ *----------------------------------------------------------------------
+ */
+
+double
+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;
+    double fraction, dblExp, *d;
+    register CONST char *p;
+    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
+				 * 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
+				 * 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. */
+
+    /*
+     * Strip off leading blanks and check for a sign.
+     */
+
+    p = string;
+    while (isspace(UCHAR(*p))) {
+	p += 1;
+    }
+    if (*p == '-') {
+	sign = TRUE;
+	p += 1;
+    } else {
+	if (*p == '+') {
+	    p += 1;
+	}
+	sign = FALSE;
+    }
+
+    /*
+     * Count the number of digits in the mantissa (including the decimal
+     * point), and also locate the decimal point.
+     */
+
+    decPt = -1;
+    for (mantSize = 0; ; mantSize += 1)
+    {
+	c = *p;
+	if (!isdigit(c)) {
+	    if ((c != '.') || (decPt >= 0)) {
+		break;
+	    }
+	    decPt = mantSize;
+	}
+	p += 1;
+    }
+
+    /*
+     * 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;
+    p -= mantSize;
+    if (decPt < 0) {
+	decPt = mantSize;
+    } else {
+	mantSize -= 1;		/* One of the digits was the point. */
+    }
+    if (mantSize > 18) {
+	fracExp = decPt - 18;
+	mantSize = 18;
+    } else {
+	fracExp = decPt - mantSize;
+    }
+    if (mantSize == 0) {
+	fraction = 0.0;
+	p = string;
+	goto done;
+    } else {
+	int frac1, frac2;
+
+	frac1 = 0;
+	for ( ; mantSize > 9; mantSize -= 1) {
+	    c = *p;
+	    p += 1;
+	    if (c == '.') {
+		c = *p;
+		p += 1;
+	    }
+	    frac1 = 10*frac1 + (c - '0');
+	}
+	frac2 = 0;
+	for (; mantSize > 0; mantSize -= 1) {
+	    c = *p;
+	    p += 1;
+	    if (c == '.') {
+		c = *p;
+		p += 1;
+	    }
+	    frac2 = 10*frac2 + (c - '0');
+	}
+	fraction = (1.0e9 * frac1) + frac2;
+    }
+
+    /*
+     * Skim off the exponent.
+     */
+
+    p = pExp;
+    if ((*p == 'E') || (*p == 'e')) {
+	p += 1;
+	if (*p == '-') {
+	    expSign = TRUE;
+	    p += 1;
+	} else {
+	    if (*p == '+') {
+		p += 1;
+	    }
+	    expSign = FALSE;
+	}
+	if (!isdigit(UCHAR(*p))) {
+	    p = pExp;
+	    goto done;
+	}
+	while (isdigit(UCHAR(*p))) {
+	    exp = exp * 10 + (*p - '0');
+	    p += 1;
+	}
+    }
+    if (expSign) {
+	exp = fracExp - exp;
+    } else {
+	exp = fracExp + exp;
+    }
+
+    /*
+     * 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) {
+	expSign = TRUE;
+	exp = -exp;
+    } else {
+	expSign = FALSE;
+    }
+    if (exp > maxExponent) {
+	exp = maxExponent;
+	errno = ERANGE;
+    }
+    dblExp = 1.0;
+    for (d = powersOf10; exp != 0; exp >>= 1, d += 1) {
+	if (exp & 01) {
+	    dblExp *= *d;
+	}
+    }
+    if (expSign) {
+	fraction /= dblExp;
+    } else {
+	fraction *= dblExp;
+    }
+
+  done:
+    if (endPtr != NULL) {
+	*endPtr = (char *) p;
+    }
+
+    if (sign) {
+	return -fraction;
+    }
+    return fraction;
+}

compat/strtol.c

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

compat/strtoul.c

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

compat/waitpid.c

@@ -0,0 +1,168 @@
+/* 
+ * 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.
+ *
+ * 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.
+ */
+
+#include "tclPort.h"
+
+#ifndef pid_t
+#define pid_t int
+#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.
+ */
+
+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. */
+} WaitInfo;
+
+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.
+ *
+ * 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.
+ *
+ * Side effects:
+ *	None.
+ *
+ *----------------------------------------------------------------------
+ */
+
+#ifdef waitpid
+#   undef waitpid
+#endif
+
+pid_t
+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
+				 * WUNTRACED. */
+{
+    register WaitInfo *waitPtr, *prevPtr;
+    pid_t result;
+    WAIT_STATUS_TYPE status;
+
+    if ((pid < -1) || (pid == 0)) {
+	errno = EINVAL;
+	return -1;
+    }
+
+    /*
+     * 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;
+	    prevPtr = waitPtr, waitPtr = waitPtr->nextPtr) {
+	if ((pid != waitPtr->pid) && (pid != -1)) {
+	    continue;
+	}
+	if (!(options & WUNTRACED) && (WIFSTOPPED(waitPtr->status))) {
+	    continue;
+	}
+	result = waitPtr->pid;
+	*statusPtr = *((int *) &waitPtr->status);
+	if (prevPtr == NULL) {
+	    deadList = waitPtr->nextPtr;
+	} else {
+	    prevPtr->nextPtr = waitPtr->nextPtr;
+	}
+	ckfree((char *) waitPtr);
+	return result;
+    }
+
+    /*
+     * 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) {
+#if NO_WAIT3
+	if (options & WNOHANG) {
+	    return 0;
+	}
+	if (options != 0) {
+	    errno = EINVAL;
+	    return -1;
+	}
+	result = wait(&status);
+#else
+	result = wait3(&status, options, 0);
+#endif
+	if ((result == -1) && (errno == EINTR)) {
+	    continue;
+	}
+	if (result <= 0) {
+	    return result;
+	}
+
+	if ((pid != result) && (pid != -1)) {
+	    goto saveInfo;
+	}
+	if (!(options & WUNTRACED) && (WIFSTOPPED(status))) {
+	    goto saveInfo;
+	}
+	*statusPtr = *((int *) &status);
+	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).
+	 */
+
+    saveInfo:
+	for (waitPtr = deadList; waitPtr != NULL; waitPtr = waitPtr->nextPtr) {
+	    if (waitPtr->pid == result) {
+		waitPtr->status = status;
+		goto waitAgain;
+	    }
+	}
+	waitPtr = (WaitInfo *) ckalloc(sizeof(WaitInfo));
+	waitPtr->pid = result;
+	waitPtr->status = status;
+	waitPtr->nextPtr = deadList;
+	deadList = waitPtr;
+
+    waitAgain:
+	continue;
+    }
+}

doc/3DBorder.3

@@ -1,294 +0,0 @@
-'\"
-'\" Copyright (c) 1990-1993 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.
-'\" 
-.TH Tk_Alloc3DBorderFromObj 3 8.1 Tk "Tk Library Procedures"
-.so man.macros
-.BS
-.SH NAME
-Tk_Alloc3DBorderFromObj, Tk_Get3DBorder, Tk_Get3DBorderFromObj, Tk_Draw3DRectangle, Tk_Fill3DRectangle, Tk_Draw3DPolygon, Tk_Fill3DPolygon, Tk_3DVerticalBevel, Tk_3DHorizontalBevel, Tk_SetBackgroundFromBorder, Tk_NameOf3DBorder, Tk_3DBorderColor, Tk_3DBorderGC, Tk_Free3DBorderFromObj, Tk_Free3DBorder \- draw borders with three-dimensional appearance
-.SH SYNOPSIS
-.nf
-\fB#include <tk.h>\fR
-.sp
-Tk_3DBorder
-\fBTk_Alloc3DBorderFromObj(\fIinterp, tkwin, objPtr\fB)\fR
-.sp
-Tk_3DBorder
-\fBTk_Get3DBorder(\fIinterp, tkwin, colorName\fB)\fR
-.sp
-Tk_3DBorder
-\fBTk_Get3DBorderFromObj(\fItkwin, objPtr\fB)\fR
-.sp
-void
-\fBTk_Draw3DRectangle(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR
-.sp
-void
-\fBTk_Fill3DRectangle(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR
-.sp
-void
-\fBTk_Draw3DPolygon(\fItkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fB)\fR
-.sp
-void
-\fBTk_Fill3DPolygon(\fItkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fB)\fR
-.sp
-void
-\fBTk_3DVerticalBevel\fR(\fItkwin, drawable, border, x, y, width, height, leftBevel, relief\fB)\fR
-.sp
-void
-\fBTk_3DHorizontalBevel\fR(\fItkwin, drawable, border, x, y, width, height, leftIn, rightIn, topBevel, relief\fB)\fR
-.sp
-void
-\fBTk_SetBackgroundFromBorder(\fItkwin, border\fB)\fR
-.sp
-const char *
-\fBTk_NameOf3DBorder(\fIborder\fB)\fR
-.sp
-XColor *
-\fBTk_3DBorderColor(\fIborder\fB)\fR
-.sp
-GC *
-\fBTk_3DBorderGC(\fItkwin, border, which\fB)\fR
-.sp
-\fBTk_Free3DBorderFromObj(\fItkwin, objPtr\fB)\fR
-.sp
-\fBTk_Free3DBorder(\fIborder\fB)\fR
-.SH ARGUMENTS
-.AS "Tk_3DBorder" borderWidth
-.AP Tcl_Interp *interp in
-Interpreter to use for error reporting.
-.AP Tk_Window tkwin in
-Token for window (for all procedures except \fBTk_Get3DBorder\fR,
-must be the window for which the border was allocated).
-.AP Tcl_Obj *objPtr in
-Pointer to value whose value describes color corresponding to
-background (flat areas).  Illuminated edges will be brighter than
-this and shadowed edges will be darker than this.
-.AP char *colorName in
-Same as \fIobjPtr\fR except value is supplied as a string rather
-than a value.
-.AP Drawable drawable in
-X token for window or pixmap;  indicates where graphics are to be drawn.
-Must either be the X window for \fItkwin\fR or a pixmap with the
-same screen and depth as \fItkwin\fR.
-.AP Tk_3DBorder border in
-Token for border previously allocated in call to \fBTk_Get3DBorder\fR.
-.AP int x in
-X-coordinate of upper-left corner of rectangle describing border
-or bevel, in pixels.
-.AP int y in
-Y-coordinate of upper-left corner of rectangle describing border or
-bevel, in pixels.
-.AP int width in
-Width of rectangle describing border or bevel, in pixels.
-.AP int height in
-Height of rectangle describing border or bevel, in pixels.
-.AP int borderWidth in
-Width of border in pixels. Positive means border is inside rectangle
-given by \fIx\fR, \fIy\fR, \fIwidth\fR, \fIheight\fR, negative means
-border is outside rectangle.
-.AP int relief in
-Indicates 3-D position of interior of value relative to exterior;
-should be \fBTK_RELIEF_RAISED\fR, \fBTK_RELIEF_SUNKEN\fR, \fBTK_RELIEF_GROOVE\fR,
-\fBTK_RELIEF_SOLID\fR, or \fBTK_RELIEF_RIDGE\fR (may also be \fBTK_RELIEF_FLAT\fR
-for \fBTk_Fill3DRectangle\fR).
-.AP XPoint *pointPtr in
-Pointer to array of points describing the set of vertices in a polygon.
-The polygon need not be closed (it will be closed automatically if it
-is not).
-.AP int numPoints in
-Number of points at \fI*pointPtr\fR.
-.AP int polyBorderWidth in
-Width of border in pixels.  If positive, border is drawn to left of
-trajectory given by \fIpointPtr\fR;  if negative, border is drawn to
-right of trajectory.  If \fIleftRelief\fR is \fBTK_RELIEF_GROOVE\fR or
-\fBTK_RELIEF_RIDGE\fR then the border is centered on the trajectory.
-.AP int leftRelief in
-Height of left side of polygon's path relative to right.  \fBTK_RELIEF_RAISED\fR
-means left side should appear higher and \fBTK_RELIEF_SUNKEN\fR means right side
-should appear higher;
-\fBTK_RELIEF_GROOVE\fR and \fBTK_RELIEF_RIDGE\fR mean the obvious things.
-For \fBTk_Fill3DPolygon\fR, \fBTK_RELIEF_FLAT\fR may also be specified to
-indicate no difference in height.
-.AP int leftBevel in
-Non-zero means this bevel forms the left side of the value;  zero means
-it forms the right side.
-.AP int leftIn in
-Non-zero means that the left edge of the horizontal bevel angles in,
-so that the bottom of the edge is farther to the right than
-the top.
-Zero means the edge angles out, so that the bottom is farther to the
-left than the top.
-.AP int rightIn in
-Non-zero means that the right edge of the horizontal bevel angles in,
-so that the bottom of the edge is farther to the left than the top.
-Zero means the edge angles out, so that the bottom is farther to the
-right than the top.
-.AP int topBevel in
-Non-zero means this bevel forms the top side of the value;  zero means
-it forms the bottom side.
-.AP int which in
-Specifies which of the border's graphics contexts is desired.
-Must be \fBTK_3D_FLAT_GC\fR, \fBTK_3D_LIGHT_GC\fR, or \fBTK_3D_DARK_GC\fR.
-.BE
-.SH DESCRIPTION
-.PP
-These procedures provide facilities for drawing window borders in a
-way that produces a three-dimensional appearance.
-\fBTk_Alloc3DBorderFromObj\fR
-allocates colors and Pixmaps needed to draw a border in the window
-given by the \fItkwin\fR argument.  The value of \fIobjPtr\fR
-is a standard Tk color name that determines the border colors.
-The color indicated by \fIobjPtr\fR will not actually be used in
-the border;  it indicates the background color for the window
-(i.e. a color for flat surfaces).
-The illuminated portions of the border will appear brighter than indicated
-by \fIobjPtr\fR, and the shadowed portions of the border will appear
-darker than \fIobjPtr\fR.
-.PP
-\fBTk_Alloc3DBorderFromObj\fR returns a token that may be used in later calls
-to \fBTk_Draw3DRectangle\fR.  If an error occurs in allocating information
-for the border (e.g. a bogus color name was given)
-then NULL is returned and an error message is left as the result of
-interpreter \fIinterp\fR.
-If it returns successfully, \fBTk_Alloc3DBorderFromObj\fR caches
-information about the return value in \fIobjPtr\fR, which speeds up
-future calls to \fBTk_Alloc3DBorderFromObj\fR with the same \fIobjPtr\fR
-and \fItkwin\fR.
-.PP
-\fBTk_Get3DBorder\fR is identical to \fBTk_Alloc3DBorderFromObj\fR except
-that the color is specified with a string instead of a value.  This
-prevents \fBTk_Get3DBorder\fR from caching the return value, so
-\fBTk_Get3DBorder\fR is less efficient than \fBTk_Alloc3DBorderFromObj\fR.
-.PP
-\fBTk_Get3DBorderFromObj\fR returns the token for an existing border, given
-the window and color name used to create the border.
-\fBTk_Get3DBorderFromObj\fR does not actually create the border; it must
-already have been created with a previous call to
-\fBTk_Alloc3DBorderFromObj\fR or \fBTk_Get3DBorder\fR.  The return
-value is cached in \fIobjPtr\fR, which speeds up
-future calls to \fBTk_Get3DBorderFromObj\fR with the same \fIobjPtr\fR
-and \fItkwin\fR.
-.PP
-Once a border structure has been created, \fBTk_Draw3DRectangle\fR may be
-invoked to draw the border.
-The \fItkwin\fR argument specifies the
-window for which the border was allocated, and \fIdrawable\fR
-specifies a window or pixmap in which the border is to be drawn.
-\fIDrawable\fR need not refer to the same window as \fItkwin\fR, but it
-must refer to a compatible
-pixmap or window:  one associated with the same screen and with the
-same depth as \fItkwin\fR.
-The \fIx\fR, \fIy\fR, \fIwidth\fR, and
-\fIheight\fR arguments define the bounding box of the border region
-within \fIdrawable\fR (usually \fIx\fR and \fIy\fR are zero and
-\fIwidth\fR and \fIheight\fR are the dimensions of the window), and
-\fIborderWidth\fR specifies the number of pixels actually
-occupied by the border.  The \fIrelief\fR argument indicates
-which of several three-dimensional effects is desired:
-\fBTK_RELIEF_RAISED\fR means that the interior of the rectangle should
-appear raised relative to the exterior of the rectangle, and
-\fBTK_RELIEF_SUNKEN\fR means that the interior should appear depressed.
-\fBTK_RELIEF_GROOVE\fR and \fBTK_RELIEF_RIDGE\fR mean that there should appear to be
-a groove or ridge around the exterior of the rectangle.
-.PP
-\fBTk_Fill3DRectangle\fR is somewhat like \fBTk_Draw3DRectangle\fR except
-that it first fills the rectangular area with the background color
-(one corresponding
-to the color used to create \fIborder\fR).  Then it calls
-\fBTk_Draw3DRectangle\fR to draw a border just inside the outer edge of
-the rectangular area.  The argument \fIrelief\fR indicates the desired
-effect (\fBTK_RELIEF_FLAT\fR means no border should be drawn; all that
-happens is to fill the rectangle with the background color).
-.PP
-The procedure \fBTk_Draw3DPolygon\fR may be used to draw more complex
-shapes with a three-dimensional appearance.  The \fIpointPtr\fR and
-\fInumPoints\fR arguments define a trajectory, \fIpolyBorderWidth\fR
-indicates how wide the border should be (and on which side of the
-trajectory to draw it), and \fIleftRelief\fR indicates which side
-of the trajectory should appear raised.  \fBTk_Draw3DPolygon\fR
-draws a border around the given trajectory using the colors from
-\fIborder\fR to produce a three-dimensional appearance.  If the trajectory is
-non-self-intersecting, the appearance will be a raised or sunken
-polygon shape.  The trajectory may be self-intersecting, although
-it's not clear how useful this is.
-.PP
-\fBTk_Fill3DPolygon\fR is to \fBTk_Draw3DPolygon\fR what
-\fBTk_Fill3DRectangle\fR is to \fBTk_Draw3DRectangle\fR:  it fills
-the polygonal area with the background color from \fIborder\fR,
-then calls \fBTk_Draw3DPolygon\fR to draw a border around the
-area (unless \fIleftRelief\fR is \fBTK_RELIEF_FLAT\fR; in this case no
-border is drawn).
-.PP
-The procedures \fBTk_3DVerticalBevel\fR and \fBTk_3DHorizontalBevel\fR
-provide lower-level drawing primitives that are used by
-procedures such as \fBTk_Draw3DRectangle\fR.
-These procedures are also useful in their own right for drawing
-rectilinear border shapes.
-\fBTk_3DVerticalBevel\fR draws a vertical beveled edge, such as the
-left or right side of a rectangle, and \fBTk_3DHorizontalBevel\fR
-draws a horizontal beveled edge, such as the top or bottom of a
-rectangle.
-Each procedure takes \fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR
-arguments that describe the rectangular area of the beveled edge
-(e.g., \fIwidth\fR is the border width for \fBTk_3DVerticalBevel\fR).
-The \fIleftBorder\fR and \fItopBorder\fR arguments indicate the
-position of the border relative to the
-.QW inside
-of the value, and
-\fIrelief\fR indicates the relief of the inside of the value relative
-to the outside.
-\fBTk_3DVerticalBevel\fR just draws a rectangular region.
-\fBTk_3DHorizontalBevel\fR draws a trapezoidal region to generate
-mitered corners;  it should be called after \fBTk_3DVerticalBevel\fR
-(otherwise \fBTk_3DVerticalBevel\fR will overwrite the mitering in
-the corner).
-The \fIleftIn\fR and \fIrightIn\fR arguments to \fBTk_3DHorizontalBevel\fR
-describe the mitering at the corners;  a value of 1 means that the bottom
-edge of the trapezoid will be shorter than the top, 0 means it will
-be longer.
-For example, to draw a rectangular border the top bevel should be
-drawn with 1 for both \fIleftIn\fR and \fIrightIn\fR, and the
-bottom bevel should be drawn with 0 for both arguments.
-.PP
-The procedure \fBTk_SetBackgroundFromBorder\fR will modify the background
-pixel and/or pixmap of \fItkwin\fR to produce a result compatible
-with \fIborder\fR.  For color displays, the resulting background will
-just be the color specified when \fIborder\fR was created;  for monochrome
-displays, the resulting background
-will be a light stipple pattern, in order to distinguish the background from
-the illuminated portion of the border.
-.PP
-Given a token for a border, the procedure \fBTk_NameOf3DBorder\fR
-will return the color name that was used to create the border.
-.PP
-The procedure \fBTk_3DBorderColor\fR returns the XColor structure
-that will be used for flat surfaces drawn for its \fIborder\fR
-argument by procedures like \fBTk_Fill3DRectangle\fR.
-The return value corresponds to the color name that was used to
-create the border.
-The XColor, and its associated pixel value, will remain allocated
-as long as \fIborder\fR exists.
-.PP
-The procedure \fBTk_3DBorderGC\fR returns one of the X graphics contexts
-that are used to draw the border.
-The argument \fIwhich\fR selects which one of the three possible GC's:
-\fBTK_3D_FLAT_GC\fR returns the context used for flat surfaces,
-\fBTK_3D_LIGHT_GC\fR returns the context for light shadows,
-and \fBTK_3D_DARK_GC\fR returns the context for dark shadows.
-.PP
-When a border is no longer needed, \fBTk_Free3DBorderFromObj\fR
-or \fBTk_Free3DBorder\fR should
-be called to release the resources associated with it.
-For \fBTk_Free3DBorderFromObj\fR the border to release is specified
-with the window and color name used to create the
-border; for \fBTk_Free3DBorder\fR the border to release is specified
-with the Tk_3DBorder token for the border.
-There should be exactly one call to \fBTk_Free3DBorderFromObj\fR or
-\fBTk_Free3DBorder\fR for each call to \fBTk_Alloc3DBorderFromObj\fR
-or \fBTk_Get3DBorder\fR.
-.SH KEYWORDS
-3D, background, border, color, depressed, illumination, value, polygon, raised, shadow, three-dimensional effect

doc/Access.3

@@ -0,0 +1,74 @@
+'\"
+'\" Copyright (c) 1998-1999 Scriptics Corporation
+'\"
+'\" 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_Access 3 8.1 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_Access, Tcl_Stat \- check file permissions and other attributes
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+int
+\fBTcl_Access\fR(\fIpath\fR, \fImode\fR)
+.sp
+int
+\fBTcl_Stat\fR(\fIpath\fR, \fIstatPtr\fR)
+.SH ARGUMENTS
+.AS "struct stat" *statPtr out
+.AP char *path in
+Native name of the file to check the attributes of.
+.AP int mode in
+Mask consisting of one or more of R_OK, W_OK, X_OK and F_OK.  R_OK,
+W_OK and X_OK request checking whether the file exists and  has  read,
+write and  execute  permissions, respectively.  F_OK just requests
+checking for the existence of the file.
+.AP "struct stat" *statPtr out
+The structure that contains the result.
+.BE
+
+.SH DESCRIPTION
+.PP
+As of Tcl 8.4, the object-based APIs \fBTcl_FSAccess\fR and
+\fBTcl_FSStat\fR should be used in preference to \fBTcl_Access\fR and
+\fBTcl_Stat\fR, wherever possible.
+.PP
+There are two reasons for calling \fBTcl_Access\fR and \fBTcl_Stat\fR
+rather than calling system level functions \fBaccess\fR and \fBstat\fR
+directly.  First, the Windows implementation of both functions fixes
+some bugs in the system level calls.  Second, both \fBTcl_Access\fR
+and \fBTcl_Stat\fR (as well as \fBTcl_OpenFileChannelProc\fR) hook
+into a linked list of functions.  This allows the possibility to reroute
+file access to alternative media or access methods.
+.PP
+\fBTcl_Access\fR checks whether the process would be allowed to read,
+write or test for existence of the file (or other file system object)
+whose name is pathname.   If pathname is a symbolic link on Unix,
+then permissions of the file referred by this symbolic link are
+tested.
+.PP
+On success (all requested permissions granted), zero is returned.  On
+error (at least one bit in mode asked for a permission that is denied,
+or some other  error occurred), -1 is returned.
+.PP
+\fBTcl_Stat\fR fills the stat structure \fIstatPtr\fR with information
+about the specified file.  You do not need any access rights to the
+file to get this information but you need search rights to all
+directories named in the path leading to the file.  The stat structure
+includes info regarding device, inode (always 0 on Windows),
+privilege mode, nlink (always 1 on Windows), user id (always 0 on
+Windows), group id (always 0 on Windows), rdev (same as device on
+Windows), size, last access time, last modification time, and creation
+time.
+.PP
+If \fIpath\fR exists, \fBTcl_Stat\fR returns 0 and the stat structure
+is filled with data.  Otherwise, -1 is returned, and no stat info is
+given.
+
+.SH KEYWORDS
+stat, access
+

doc/AddErrInfo.3

@@ -0,0 +1,300 @@
+'\"
+'\" Copyright (c) 1989-1993 The Regents of the University of California.
+'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
+'\"
+'\" 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_AddErrorInfo 3 8.5 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+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
+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
+\fBTcl_SetErrorCode\fR(\fIinterp, element, element, ... \fB(char *) NULL\fR)
+.sp
+\fBTcl_SetErrorCodeVA\fR(\fIinterp, argList\fR)
+.sp
+const char *
+\fBTcl_PosixError\fR(\fIinterp\fR)
+.sp
+void
+\fBTcl_LogCommandInfo\fR(\fIinterp, script, command, commandLength\fR)
+.SH ARGUMENTS
+.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 \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.
+.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
+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
+The \fB\-errorcode\fR return option will be set to this value.
+.AP char *element in
+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
+\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
+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
+.BE
+
+.SH DESCRIPTION
+.PP
+.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 \fB\-errorcode\fR option holds a list of items that
+are intended to be machine-readable.
+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 hold additional pieces
+of information that depend on the class.
+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 \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_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
+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_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
+.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
+\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
+the \fB\-errorcode\fR return option to \fBNONE\fR.
+.PP
+The procedure \fBTcl_SetErrorCode\fR is also used to set the
+\fB\-errorcode\fR return option. However, it takes one or more strings to
+record instead of an object. Otherwise, it is similar to
+\fBTcl_SetObjErrorCode\fR in behavior.
+.PP
+\fBTcl_SetErrorCodeVA\fR is the same as \fBTcl_SetErrorCode\fR except that
+instead of taking a variable number of arguments it takes an argument list.
+.PP
+\fBTcl_PosixError\fR
+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 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
+occurs in a dynamically loaded extension. See the manual entry for
+\fBTcl_SetErrno\fR for more information.
+.PP
+\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 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 \fB\-errorinfo\fR value, and
+the line number stored internally in the interpreter is set.  
+.PP
+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.
+.PP
+If the procedure \fBTcl_ResetResult\fR is called,
+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
+
+.SH KEYWORDS
+error, object, object result, stack, trace, variable

doc/AddOption.3

@@ -1,50 +0,0 @@
-'\"
-'\" Copyright (c) 1998-2000 by Scriptics Corporation.
-'\" All rights reserved.
-'\"
-.TH Tk_AddOption 3 "" Tk "Tk Library Procedures"
-.so man.macros
-.BS
-.SH NAME
-Tk_AddOption \- Add an option to the option database
-.SH SYNOPSIS
-.nf
-\fB#include <tk.h>\fR
-.sp
-void
-\fBTk_AddOption\fR(\fItkwin, name, value, priority\fR)
-.SH ARGUMENTS
-.AP Tk_Window tkwin in
-Token for window.
-.AP "const char" *name in
-Multi-element name of option.
-.AP "const char" *value in
-Value of option.
-.AP int priority in
-Overall priority level to use for option.
-.BE
-.SH DESCRIPTION
-.PP
-This procedure is invoked to add an option to the database
-associated with \fItkwin\fR's main window.  \fIName\fR
-contains the option being specified and consists of names and/or
-classes separated by asterisks or dots, in the usual X format.
-\fIValue\fR contains the text string to associate with \fIname\fR;
-this value will be returned in calls to \fBTk_GetOption\fR.
-\fIPriority\fR specifies the priority of the value; when options are
-queried using \fBTk_GetOption\fR, the value with the highest priority
-is returned.  \fIPriority\fR must be between 0 and \fBTK_MAX_PRIO\fR.  Some
-common priority values are:
-.IP 20
-Used for default values hard-coded into widgets.
-.IP 40
-Used for options specified in application-specific startup files.
-.IP 60
-Used for options specified in user-specific defaults files, such as
-\fB.Xdefaults\fR, resource databases loaded into the X server, or
-user-specific startup files.
-.IP 80
-Used for options specified interactively after the application starts
-running.
-.SH KEYWORDS
-class, name, option, add

doc/Alloc.3

@@ -0,0 +1,92 @@
+'\"
+'\" 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.
+'\" 
+.so man.macros
+.TH Tcl_Alloc 3 7.5 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_Alloc, Tcl_Free, Tcl_Realloc, Tcl_AttemptAlloc, Tcl_AttemptRealloc, ckalloc, ckfree, ckrealloc, attemptckalloc, attemptckrealloc \- allocate or free heap memory
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+char *
+\fBTcl_Alloc\fR(\fIsize\fR)
+.sp
+void
+\fBTcl_Free\fR(\fIptr\fR)
+.sp
+char *
+\fBTcl_Realloc\fR(\fIptr, size\fR)
+.sp
+char *
+\fBTcl_AttemptAlloc\fR(\fIsize\fR)
+.sp
+char *
+\fBTcl_AttemptRealloc\fR(\fIptr, size\fR)
+.sp
+char *
+\fBckalloc\fR(\fIsize\fR)
+.sp
+void
+\fBckfree\fR(\fIptr\fR)
+.sp
+char *
+\fBckrealloc\fR(\fIptr, size\fR)
+.sp
+char *
+\fBattemptckalloc\fR(\fIsize\fR)
+.sp
+char *
+\fBattemptckrealloc\fR(\fIptr, size\fR)
+.SH ARGUMENTS
+.AS char *size
+.AP "unsigned int" size in
+Size in bytes of the memory block to allocate.
+.AP char *ptr in
+Pointer to memory block to free or realloc.
+.BE
+
+.SH DESCRIPTION
+.PP
+These procedures provide a platform and compiler independent interface
+for memory allocation.  Programs that need to transfer ownership of
+memory blocks between Tcl and other modules should use these routines
+rather than the native \fBmalloc()\fR and \fBfree()\fR routines
+provided by the C run-time library.
+.PP
+\fBTcl_Alloc\fR returns a pointer to a block of at least \fIsize\fR
+bytes suitably aligned for any use.
+.PP
+\fBTcl_Free\fR makes the space referred to by \fIptr\fR available for
+further allocation.
+.PP
+\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.  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, but not all, attempting to allocate a zero-sized block of
+memory will also cause these functions to return NULL.
+.PP
+The procedures \fBckalloc\fR, \fBckfree\fR, \fBckrealloc\fR,
+\fBattemptckalloc\fR, and \fBattemptckrealloc\fR are implemented
+as macros.  Normally, they are synonyms for the corresponding
+procedures documented on this page.  When Tcl and all modules
+calling Tcl are compiled with \fBTCL_MEM_DEBUG\fR defined, however,
+these macros are redefined to be special debugging versions
+of these procedures.  To support Tcl's memory debugging within a
+module, use the macros rather than direct calls to \fBTcl_Alloc\fR, etc.
+
+.SH KEYWORDS
+alloc, allocation, free, malloc, memory, realloc, TCL_MEM_DEBUG

doc/AllowExc.3

@@ -0,0 +1,44 @@
+'\"
+'\" Copyright (c) 1989-1993 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.so man.macros
+.TH Tcl_AllowExceptions 3 7.4 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_AllowExceptions \- allow all exceptions in next script evaluation
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+\fBTcl_AllowExceptions\fR(\fIinterp\fR)
+.SH ARGUMENTS
+.AS Tcl_Interp *interp
+.AP Tcl_Interp *interp in
+Interpreter in which script will be evaluated.
+.BE
+
+.SH DESCRIPTION
+.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 \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,
+\fBTcl_GlobalEval\fR, \fBTcl_GlobalEvalObj\fR, \fBTcl_VarEval\fR and
+\fBTcl_VarEvalVA\fR. 
+.PP
+However, if \fBTcl_AllowExceptions\fR is invoked immediately before
+calling one of those a procedures, then arbitrary completion
+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 \fBTCL_BREAK\fR or \fBTCL_CONTINUE\fR in a meaningful way.
+
+.SH KEYWORDS
+continue, break, exception, interpreter

doc/AppInit.3

@@ -0,0 +1,73 @@
+'\"
+'\" Copyright (c) 1993 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.so man.macros
+.TH Tcl_AppInit 3 7.0 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_AppInit \- perform application-specific initialization
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+int
+\fBTcl_AppInit\fR(\fIinterp\fR)
+.SH ARGUMENTS
+.AS Tcl_Interp *interp
+.AP Tcl_Interp *interp in
+Interpreter for the application.
+.BE
+
+.SH DESCRIPTION
+.PP
+\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.
+To create a new application you write a new version of
+\fBTcl_AppInit\fR to replace the default version provided by Tcl,
+then link your new \fBTcl_AppInit\fR with the Tcl library.
+.PP
+\fBTcl_AppInit\fR is invoked by \fBTcl_Main\fR and \fBTk_Main\fR
+after their own initialization and before entering the main loop
+to process commands.
+Here are some examples of things that \fBTcl_AppInit\fR might do:
+.IP [1]
+Call initialization procedures for various packages used by
+the application.
+Each initialization procedure adds new commands to \fIinterp\fR
+for its package and performs other package-specific initialization.
+.IP [2]
+Process command-line arguments, which can be accessed from the
+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 \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
+a procedure \fBmain\fR that calls \fBTcl_Main\fR as follows:
+.CS
+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 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).
+The best way to get started is to make a copy of the file
+\fBtclAppInit.c\fR from the Tcl library or source directory.
+It already contains a \fBmain\fR procedure and a template for
+\fBTcl_AppInit\fR that you can modify for your application.
+
+.SH KEYWORDS
+application, argument, command, initialization, interpreter

doc/AssocData.3

@@ -0,0 +1,85 @@
+'\"
+'\" 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.
+'\" 
+.so man.macros
+.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
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+ClientData
+\fBTcl_GetAssocData\fR(\fIinterp, key, delProcPtr\fR)
+.sp
+\fBTcl_SetAssocData\fR(\fIinterp, key, delProc, clientData\fR)
+.sp
+\fBTcl_DeleteAssocData\fR(\fIinterp, key\fR)
+.SH ARGUMENTS
+.AS Tcl_InterpDeleteProc **delProcPtr
+.AP Tcl_Interp *interp in
+Interpreter in which to execute the specified command.
+.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
+Procedure to call when \fIinterp\fR is deleted.
+.AP Tcl_InterpDeleteProc **delProcPtr in
+Pointer to location in which to store address of current deletion procedure
+for association.  Ignored if NULL.
+.AP ClientData clientData in
+Arbitrary one-word value associated with the given key in this
+interpreter.  This data is owned by the caller.
+.BE
+
+.SH DESCRIPTION
+.PP
+These procedures allow extensions to associate their own data with
+a Tcl interpreter.
+An association consists of a string key, typically the name of
+the extension, and a one-word value, which is typically a pointer
+to a data structure holding data specific to the extension.
+Tcl makes no interpretation of either the key or the value for
+an association.
+.PP
+Storage management is facilitated by storing with each association a
+procedure to call when the interpreter is deleted. This
+procedure can dispose of the storage occupied by the client's data in any
+way it sees fit.
+.PP
+\fBTcl_SetAssocData\fR creates an association between a string
+key and a user specified datum in the given interpreter.
+If there is already an association with the given \fIkey\fR,
+\fBTcl_SetAssocData\fR overwrites it with the new information.
+It is up to callers to organize their use of names to avoid conflicts,
+for example, by using package names as the keys.
+If the \fIdeleteProc\fR argument is non-NULL it specifies the address of a
+procedure to invoke if the interpreter is deleted before the association
+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);
+.CE
+When \fIdeleteProc\fR is invoked the \fIclientData\fR and \fIinterp\fR
+arguments will be the same as the corresponding arguments passed to
+\fBTcl_SetAssocData\fR.
+The deletion procedure will \fInot\fR be invoked if the association
+is deleted before the interpreter is deleted.
+.PP
+\fBTcl_GetAssocData\fR returns the datum stored in the association with the
+specified key in the given interpreter, and if the \fIdelProcPtr\fR field
+is non-\fBNULL\fR, the address indicated by it gets the address of the
+delete procedure stored with this association. If no association with the
+specified key exists in the given interpreter \fBTcl_GetAssocData\fR
+returns \fBNULL\fR.
+.PP
+\fBTcl_DeleteAssocData\fR deletes an association with a specified key in
+the given interpreter.  Then it calls the deletion procedure.
+.SH KEYWORDS
+association, data, deletion procedure, interpreter, key

doc/Async.3

@@ -0,0 +1,159 @@
+'\"
+'\" Copyright (c) 1989-1993 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.so man.macros
+.TH Tcl_AsyncCreate 3 7.0 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_AsyncCreate, Tcl_AsyncMark, Tcl_AsyncInvoke, Tcl_AsyncDelete, Tcl_AsyncReady \- handle asynchronous events
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+Tcl_AsyncHandler
+\fBTcl_AsyncCreate\fR(\fIproc, clientData\fR)
+.sp
+\fBTcl_AsyncMark\fR(\fIasync\fR)
+.sp
+int
+\fBTcl_AsyncInvoke\fR(\fIinterp, code\fR)
+.sp
+\fBTcl_AsyncDelete\fR(\fIasync\fR)
+.sp
+int
+\fBTcl_AsyncReady\fR()
+.SH ARGUMENTS
+.AS Tcl_AsyncHandler clientData
+.AP Tcl_AsyncProc *proc in
+Procedure to invoke to handle an asynchronous event.
+.AP ClientData clientData in
+One-word value to pass to \fIproc\fR.
+.AP Tcl_AsyncHandler async in
+Token for asynchronous event handler.
+.AP Tcl_Interp *interp in
+Tcl interpreter in which command was being evaluated when handler was
+invoked, or NULL if handler was invoked when there was no interpreter
+active.
+.AP int code in
+Completion code from command that just completed in \fIinterp\fR,
+or 0 if \fIinterp\fR is NULL.
+.BE
+
+.SH DESCRIPTION
+.PP
+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 is not safe to take any substantive action to
+process the event.
+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.
+The only safe approach is to set a flag indicating that the event
+occurred, then handle the event later when the world has returned
+to a clean state, such as after the current Tcl command completes.
+.PP
+\fBTcl_AsyncCreate\fR, \fBTcl_AsyncDelete\fR, and \fBTcl_AsyncReady\fR
+are thread sensitive.  They access and/or set a thread-specific data
+structure in the event of a core built with \fI\-\-enable\-threads\fR.  The token
+created by \fBTcl_AsyncCreate\fR contains the needed thread information it
+was called from so that calling \fBTcl_AsyncMark\fR(\fItoken\fR) will only yield
+the origin thread into the asynchronous handler.
+.PP
+\fBTcl_AsyncCreate\fR creates an asynchronous handler and returns
+a token for it.
+The asynchronous handler must be created before
+any occurrences of the asynchronous event that it is intended
+to handle (it is not safe to create a handler at the time of
+an event).
+When an asynchronous event occurs the code that detects the event
+(such as a signal handler) should call \fBTcl_AsyncMark\fR with the
+token for the handler.
+\fBTcl_AsyncMark\fR will mark the handler as ready to execute, but it
+will not invoke the handler immediately.
+Tcl will call the \fIproc\fR associated with the handler later, when
+the world is in a safe state, and \fIproc\fR can then carry out
+the actions associated with the asynchronous event.
+\fIProc\fR should have arguments and result that match the
+type \fBTcl_AsyncProc\fR:
+.CS
+typedef int Tcl_AsyncProc(
+        ClientData \fIclientData\fR,
+        Tcl_Interp *\fIinterp\fR,
+        int \fIcode\fR);
+.CE
+The \fIclientData\fR will be the same as the \fIclientData\fR
+argument passed to \fBTcl_AsyncCreate\fR when the handler was
+created.
+If \fIproc\fR is invoked just after a command has completed
+execution in an interpreter, then \fIinterp\fR will identify
+the interpreter in which the command was evaluated and
+\fIcode\fR will be the completion code returned by that
+command.
+The command's result will be present in the interpreter's result.
+When \fIproc\fR returns, whatever it leaves in the interpreter's result
+will be returned as the result of the command and the integer
+value returned by \fIproc\fR will be used as the new completion
+code for the command.
+.PP
+It is also possible for \fIproc\fR to be invoked when no interpreter
+is active.
+This can happen, for example, if an asynchronous event occurs while
+the application is waiting for interactive input or an X event.
+In this case \fIinterp\fR will be NULL and \fIcode\fR will be
+0, and the return value from \fIproc\fR will be ignored.
+.PP
+The procedure \fBTcl_AsyncInvoke\fR is called to invoke all of the
+handlers that are ready.
+The procedure \fBTcl_AsyncReady\fR will return non-zero whenever any
+asynchronous handlers are ready;  it can be checked to avoid calls
+to \fBTcl_AsyncInvoke\fR when there are no ready handlers.
+Tcl calls \fBTcl_AsyncReady\fR after each command is evaluated
+and calls \fBTcl_AsyncInvoke\fR if needed.
+Applications may also call \fBTcl_AsyncInvoke\fR at interesting
+times for that application.
+For example, Tcl's event handler calls \fBTcl_AsyncReady\fR
+after each event and calls \fBTcl_AsyncInvoke\fR if needed.
+The \fIinterp\fR and \fIcode\fR arguments to \fBTcl_AsyncInvoke\fR
+have the same meaning as for \fIproc\fR:  they identify the active
+interpreter, if any, and the completion code from the command
+that just completed.
+.PP
+\fBTcl_AsyncDelete\fR removes an asynchronous handler so that
+its \fIproc\fR will never be invoked again.
+A handler can be deleted even when ready, and it will still
+not be invoked.
+.PP
+If multiple handlers become active at the same time, the
+handlers are invoked in the order they were created (oldest
+handler first).
+The \fIcode\fR and the interpreter's result for later handlers
+reflect the values returned by earlier handlers, so that
+the most recently created handler has last say about
+the interpreter's result and completion code.
+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
+handler to modify the interpreter's result or return a code different
+from its \fIcode\fR argument.
+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 state by calling
+\fBTcl_SaveInterpState\fR, passing in the \fIcode\fR argument.
+When the asynchronous handler is finished it should restore
+the interpreter's state by calling \fBTcl_RestoreInterpState\fR,
+and then returning the \fIcode\fR argument.
+
+.SH KEYWORDS
+asynchronous event, handler, signal, Tcl_SaveInterpState, thread

doc/BackgdErr.3

@@ -0,0 +1,61 @@
+'\"
+'\" Copyright (c) 1992-1994 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.
+'\" 
+.so man.macros
+.TH Tcl_BackgroundError 3 7.5 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_BackgroundError \- report Tcl error that occurred in background processing
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+\fBTcl_BackgroundError\fR(\fIinterp\fR)
+.SH ARGUMENTS
+.AS Tcl_Interp *interp
+.AP Tcl_Interp *interp in
+Interpreter in which the error occurred.
+.BE
+
+.SH DESCRIPTION
+.PP
+This procedure is typically invoked when a Tcl error occurs during
+.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.
+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 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 the handler command immediately
+because this could potentially interfere with scripts that are in process
+at the time the error occurred.
+Instead, it invokes the handler command later as an idle callback.
+.PP
+It is possible for many background errors to accumulate before
+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, interp

doc/Backslash.3

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

doc/BindTable.3

@@ -1,153 +0,0 @@
-'\"
-'\" Copyright (c) 1994 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\"
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.TH Tk_CreateBindingTable 3 4.0 Tk "Tk Library Procedures"
-.so man.macros
-.BS
-.SH NAME
-Tk_CreateBindingTable, Tk_DeleteBindingTable, Tk_CreateBinding, Tk_DeleteBinding, Tk_GetBinding, Tk_GetAllBindings, Tk_DeleteAllBindings, Tk_BindEvent \- invoke scripts in response to X events
-.SH SYNOPSIS
-.nf
-\fB#include <tk.h>\fR
-.sp
-Tk_BindingTable
-\fBTk_CreateBindingTable(\fIinterp\fB)\fR
-.sp
-\fBTk_DeleteBindingTable(\fIbindingTable\fB)\fR
-.sp
-unsigned long
-\fBTk_CreateBinding(\fIinterp, bindingTable, object, eventString, script, append\fB)\fR
-.sp
-int
-\fBTk_DeleteBinding(\fIinterp, bindingTable, object, eventString\fB)\fR
-.sp
-const char *
-\fBTk_GetBinding(\fIinterp, bindingTable, object, eventString\fB)\fR
-.sp
-\fBTk_GetAllBindings(\fIinterp, bindingTable, object\fB)\fR
-.sp
-\fBTk_DeleteAllBindings(\fIbindingTable, object\fB)\fR
-.sp
-\fBTk_BindEvent(\fIbindingTable, eventPtr, tkwin, numObjects, objectPtr\fB)\fR
-.SH ARGUMENTS
-.AS Tk_BindingTable bindingTable
-.AP Tcl_Interp *interp in
-Interpreter to use when invoking bindings in binding table.  Also
-used for returning results and errors from binding procedures.
-.AP Tk_BindingTable bindingTable in
-Token for binding table;  must have been returned by some previous
-call to \fBTk_CreateBindingTable\fR.
-.AP ClientData object in
-Identifies object with which binding is associated.
-.AP "const char" *eventString in
-String describing event sequence.
-.AP "const char" *script in
-Tcl script to invoke when binding triggers.
-.AP int append in
-Non-zero means append \fIscript\fR to existing script for binding,
-if any; zero means replace existing script with new one.
-.AP XEvent *eventPtr in
-X event to match against bindings in \fIbindingTable\fR.
-.AP Tk_Window tkwin in
-Identifier for any window on the display where the event occurred.
-Used to find display-related information such as key maps.
-.AP int numObjects in
-Number of object identifiers pointed to by \fIobjectPtr\fR.
-.AP ClientData *objectPtr in
-Points to an array of object identifiers:  bindings will be considered
-for each of these objects in order from first to last.
-.BE
-.SH DESCRIPTION
-.PP
-These procedures provide a general-purpose mechanism for creating
-and invoking bindings.
-Bindings are organized in terms of \fIbinding tables\fR.
-A binding table consists of a collection of bindings plus a history
-of recent events.
-Within a binding table, bindings are associated with \fIobjects\fR.
-The meaning of an object is defined by clients of the binding package.
-For example, Tk keeps uses one binding table to hold all of the bindings
-created by the \fBbind\fR command.
-For this table, objects are pointers to strings such as window names, class
-names, or other binding tags such as \fBall\fR.
-Tk also keeps a separate binding table for each canvas widget, which manages
-bindings created by the canvas's \fBbind\fR widget command;  within
-this table, an object is either a pointer to the internal structure for a
-canvas item or a Tk_Uid identifying a tag.
-.PP
-The procedure \fBTk_CreateBindingTable\fR creates a new binding
-table and associates \fIinterp\fR with it (when bindings in the
-table are invoked, the scripts will be evaluated in \fIinterp\fR).
-\fBTk_CreateBindingTable\fR returns a token for the table, which
-must be used in calls to other procedures such as \fBTk_CreateBinding\fR
-or \fBTk_BindEvent\fR.
-.PP
-\fBTk_DeleteBindingTable\fR frees all of the state associated
-with a binding table.
-Once it returns the caller should not use the \fIbindingTable\fR
-token again.
-.PP
-\fBTk_CreateBinding\fR adds a new binding to an existing table.
-The \fIobject\fR argument identifies the object with which the
-binding is to be associated, and it may be any one-word value.
-Typically it is a pointer to a string or data structure.
-The \fIeventString\fR argument identifies the event or sequence
-of events for the binding;  see the documentation for the
-\fBbind\fR command for a description of its format.
-\fIscript\fR is the Tcl script to be evaluated when the binding
-triggers.
-\fIappend\fR indicates what to do if there already
-exists a binding for \fIobject\fR and \fIeventString\fR:  if \fIappend\fR
-is zero then \fIscript\fR replaces the old script;  if \fIappend\fR
-is non-zero then the new script is appended to the old one.
-\fBTk_CreateBinding\fR returns an X event mask for all the events
-associated with the bindings.
-This information may be useful to invoke \fBXSelectInput\fR to
-select relevant events, or to disallow the use of certain events
-in bindings.
-If an error occurred while creating the binding (e.g., \fIeventString\fR
-refers to a non-existent event), then 0 is returned and an error
-message is left as the result of interpreter \fIinterp\fR.
-.PP
-\fBTk_DeleteBinding\fR removes from \fIbindingTable\fR the
-binding given by \fIobject\fR and \fIeventString\fR, if
-such a binding exists.
-\fBTk_DeleteBinding\fR always returns \fBTCL_OK\fR.
-In some cases it may reset the interpreter result to the default
-empty value.
-.PP
-\fBTk_GetBinding\fR returns a pointer to the script associated
-with \fIeventString\fR and \fIobject\fR in \fIbindingTable\fR.
-If no such binding exists then NULL is returned and an error
-message is left as the result of interpreter \fIinterp\fR.
-.PP
-\fBTk_GetAllBindings\fR returns in \fIinterp\fR's result a list
-of all the event strings for which there are bindings in
-\fIbindingTable\fR associated with \fIobject\fR.
-If there are no bindings for \fIobject\fR, the result will be an empty
-string.
-.PP
-\fBTk_DeleteAllBindings\fR deletes all of the bindings in
-\fIbindingTable\fR that are associated with \fIobject\fR.
-.PP
-\fBTk_BindEvent\fR is called to process an event.
-It makes a copy of the event in an internal history list associated
-with the binding table, then it checks for bindings that match
-the event.
-\fBTk_BindEvent\fR processes each of the objects pointed to
-by \fIobjectPtr\fR in turn.
-For each object, it finds all the bindings that match the current
-event history, selects the most specific binding using the priority
-mechanism described in the documentation for \fBbind\fR,
-and invokes the script for that binding.
-If there are no matching bindings for a particular object, then
-the object is skipped.
-\fBTk_BindEvent\fR continues through all of the objects, handling
-exceptions such as errors, \fBbreak\fR, and \fBcontinue\fR as
-described in the documentation for \fBbind\fR.
-.SH KEYWORDS
-binding, event, object, script

doc/BoolObj.3

@@ -0,0 +1,95 @@
+'\"
+'\" 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.5 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_NewBooleanObj, Tcl_SetBooleanObj, Tcl_GetBooleanFromObj \- store/retrieve boolean value in a Tcl_Obj
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+Tcl_Obj *
+\fBTcl_NewBooleanObj\fR(\fIboolValue\fR)
+.sp
+\fBTcl_SetBooleanObj\fR(\fIobjPtr, boolValue\fR)
+.sp
+int
+\fBTcl_GetBooleanFromObj\fR(\fIinterp, objPtr, boolPtr\fR)
+.SH ARGUMENTS
+.AS Tcl_Interp boolValue in/out
+.AP int boolValue in
+Integer value to be stored as a boolean value in a Tcl_Obj.
+.AP Tcl_Obj *objPtr in/out
+Points to the Tcl_Obj in which to store, or from which to
+retrieve a boolean value.
+.AP Tcl_Interp *interp in/out
+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
+Points to place where \fBTcl_GetBooleanFromObj\fR
+stores the boolean value (0 or 1) obtained from \fIobjPtr\fR.
+.BE
+
+.SH DESCRIPTION
+.PP
+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_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_IsShared, Tcl_GetBoolean
+
+.SH KEYWORDS
+boolean, object

doc/ByteArrObj.3

@@ -0,0 +1,89 @@
+'\"
+'\" Copyright (c) 1997 Sun Microsystems, Inc.
+'\"
+'\" 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_ByteArrayObj 3 8.1 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_NewByteArrayObj, Tcl_SetByteArrayObj, Tcl_GetByteArrayFromObj, Tcl_SetByteArrayLength \- manipulate Tcl objects as a arrays of bytes 
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+Tcl_Obj *
+\fBTcl_NewByteArrayObj\fR(\fIbytes, length\fR)
+.sp
+void 
+\fBTcl_SetByteArrayObj\fR(\fIobjPtr, bytes, length\fR)
+.sp
+unsigned char *
+\fBTcl_GetByteArrayFromObj\fR(\fIobjPtr, lengthPtr\fR)
+.sp
+unsigned char *
+\fBTcl_SetByteArrayLength\fR(\fIobjPtr, length\fR)
+.SH ARGUMENTS
+.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.
+.AP Tcl_Obj *objPtr in/out
+For \fBTcl_SetByteArrayObj\fR, this points to the object to be converted to
+byte-array type.  For \fBTcl_GetByteArrayFromObj\fR and
+\fBTcl_SetByteArrayLength\fR, this points to the object from which to get
+the byte-array value; if \fIobjPtr\fR does not already point to a byte-array
+object, it will be converted to one.
+.AP int *lengthPtr out
+If non-NULL, filled with the length of the array of bytes in the object.
+.BE
+
+.SH DESCRIPTION
+.PP
+These procedures are used to create, modify, and read Tcl byte-array objects
+from C code.  Byte-array objects are typically used to hold the
+results of binary IO operations or data structures created with the
+\fBbinary\fR command.  In Tcl, an array of bytes is not equivalent to a
+string.  Conceptually, a string is an array of Unicode characters, while a
+byte-array is an array of 8-bit quantities with no implicit meaning.
+Accessor functions are provided to get the string representation of a
+byte-array or to convert an arbitrary 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
+one-to-one mapping between the bytes in the internal representation and the
+UTF-8 characters in the string representation.  
+.PP
+\fBTcl_NewByteArrayObj\fR and \fBTcl_SetByteArrayObj\fR will
+create a new object of byte-array type or modify an existing object to have a
+byte-array type.  Both of these procedures set the object's type to be
+byte-array and set the object's internal representation to a copy of the
+array of bytes given by \fIbytes\fR. \fBTcl_NewByteArrayObj\fR returns a
+pointer to a newly allocated object with a reference count of zero.
+\fBTcl_SetByteArrayObj\fR invalidates any old string representation and, if
+the object is not already a byte-array object, frees any old internal
+representation.
+.PP
+\fBTcl_GetByteArrayFromObj\fR converts a Tcl object to byte-array type and
+returns a pointer to the object's new internal representation as an array of
+bytes.  The length of this array is stored in \fIlengthPtr\fR if
+\fIlengthPtr\fR is non-NULL.  The storage for the array of bytes is owned by
+the object and should not be freed.  The contents of the array may be
+modified by the caller only if the object is not shared and the caller
+invalidates the string representation.  
+.PP
+\fBTcl_SetByteArrayLength\fR converts the Tcl object to byte-array type
+and changes the length of the object's internal representation as an
+array of bytes.  If \fIlength\fR is greater than the space currently
+allocated for the array, the array is reallocated to the new length; the
+newly allocated bytes at the end of the array have arbitrary values.  If
+\fIlength\fR is less than the space currently allocated for the array,
+the length of array is reduced to the new length.  The return value is a
+pointer to the object's new array of bytes.  
+
+.SH "SEE ALSO"
+Tcl_GetStringFromObj, Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount
+
+.SH KEYWORDS
+object, byte array, utf, unicode, internationalization

doc/CallDel.3

@@ -0,0 +1,61 @@
+'\"
+'\" Copyright (c) 1993 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.so man.macros
+.TH Tcl_CallWhenDeleted 3 7.0 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_CallWhenDeleted, Tcl_DontCallWhenDeleted \- Arrange for callback when interpreter is deleted
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+\fBTcl_CallWhenDeleted\fR(\fIinterp\fR, \fIproc\fR, \fIclientData\fR)
+.sp
+\fBTcl_DontCallWhenDeleted\fR(\fIinterp\fR, \fIproc\fR, \fIclientData\fR)
+.SH ARGUMENTS
+.AS Tcl_InterpDeleteProc clientData
+.AP Tcl_Interp *interp in
+Interpreter with which to associated callback.
+.AP Tcl_InterpDeleteProc *proc in
+Procedure to call when \fIinterp\fR is deleted.
+.AP ClientData clientData in
+Arbitrary one-word value to pass to \fIproc\fR.
+.BE
+
+.SH DESCRIPTION
+.PP
+\fBTcl_CallWhenDeleted\fR arranges for \fIproc\fR to be called by
+\fBTcl_DeleteInterp\fR if/when \fIinterp\fR is deleted at some future
+time.  \fIProc\fR will be invoked just before the interpreter
+is deleted, but the interpreter will still be valid at the
+time of the call.
+\fIProc\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);
+.CE
+The \fIclientData\fR and \fIinterp\fR parameters are
+copies of the \fIclientData\fR and \fIinterp\fR arguments given
+to \fBTcl_CallWhenDeleted\fR.
+Typically, \fIclientData\fR points to an application-specific
+data structure that \fIproc\fR uses to perform cleanup when an
+interpreter is about to go away.
+\fIProc\fR does not return a value.
+.PP
+\fBTcl_DontCallWhenDeleted\fR cancels a previous call to
+\fBTcl_CallWhenDeleted\fR with the same arguments, so that
+\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
+\fBTcl_DontCallWhenDeleted\fR has no effect.
+
+.SH KEYWORDS
+callback, delete, interpreter

doc/CanvPsY.3

@@ -1,121 +0,0 @@
-'\"
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\"
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.TH Tk_CanvasPs 3 4.0 Tk "Tk Library Procedures"
-.so man.macros
-.BS
-.SH NAME
-Tk_CanvasPsY, Tk_CanvasPsBitmap, Tk_CanvasPsColor, Tk_CanvasPsFont, Tk_CanvasPsPath, Tk_CanvasPsStipple \- utility procedures for generating Postscript for canvases
-.SH SYNOPSIS
-.nf
-\fB#include <tk.h>\fR
-.sp
-double
-\fBTk_CanvasPsY\fR(\fIcanvas, canvasY\fR)
-.sp
-int
-\fBTk_CanvasPsBitmap\fR(\fIinterp, canvas, bitmap, x, y, width, height\fR)
-.sp
-int
-\fBTk_CanvasPsColor\fR(\fIinterp, canvas, colorPtr\fR)
-.sp
-int
-\fBTk_CanvasPsFont\fR(\fIinterp, canvas, tkFont\fR)
-.sp
-\fBTk_CanvasPsPath\fR(\fIinterp, canvas, coordPtr, numPoints\fR)
-.sp
-int
-\fBTk_CanvasPsStipple\fR(\fIinterp, canvas, bitmap\fR)
-.SH ARGUMENTS
-.AS "unsigned int" "numPoints"
-.AP Tk_Canvas canvas in
-A token that identifies a canvas widget for which Postscript is
-being generated.
-.AP double canvasY in
-Y-coordinate in the space of the canvas.
-.AP Tcl_Interp *interp in/out
-A Tcl interpreter;  Postscript is appended to its result, or the
-result may be replaced with an error message.
-.AP Pixmap bitmap in
-Bitmap to use for generating Postscript.
-.AP int x in
-X-coordinate within \fIbitmap\fR of left edge of region to output.
-.AP int y in
-Y-coordinate within \fIbitmap\fR of top edge of region to output.
-.AP "int" width in
-Width of region of bitmap to output, in pixels.
-.AP "int" height in
-Height of region of bitmap to output, in pixels.
-.AP XColor *colorPtr in
-Information about color value to set in Postscript.
-.AP Tk_Font tkFont in
-Font for which Postscript is to be generated.
-.AP double *coordPtr in
-Pointer to an array of coordinates for one or more
-points specified in canvas coordinates.
-The order of values in \fIcoordPtr\fR is x1, y1, x2, y2, x3, y3,
-and so on.
-.AP int numPoints in
-Number of points at \fIcoordPtr\fR.
-.BE
-.SH DESCRIPTION
-.PP
-These procedures are called by canvas type managers to carry out
-common functions related to generating Postscript.
-Most of the procedures take a \fIcanvas\fR argument, which
-refers to a canvas widget for which Postscript is being
-generated.
-.PP
-\fBTk_CanvasPsY\fR takes as argument a y-coordinate in the space of
-a canvas and returns the value that should be used for that point
-in the Postscript currently being generated for \fIcanvas\fR.
-Y coordinates require transformation because Postscript uses an
-origin at the lower-left corner whereas X uses an origin at the
-upper-left corner.
-Canvas x coordinates can be used directly in Postscript without
-transformation.
-.PP
-\fBTk_CanvasPsBitmap\fR generates Postscript to describe a region
-of a bitmap.
-The Postscript is generated in proper image data format for Postscript,
-i.e., as data between angle brackets, one bit per pixel.
-The Postscript is appended to the result of interpreter \fIinterp\fR
-and \fBTCL_OK\fR is returned unless an error occurs, in which case
-\fBTCL_ERROR\fR is returned and the interpreter result is overwritten
-with an error message.
-.PP
-\fBTk_CanvasPsColor\fR generates Postscript to set the current color
-to correspond to its \fIcolorPtr\fR argument, taking into account any
-color map specified in the \fBpostscript\fR command.
-It appends the Postscript to the interpreter \fIinterp\fR's result and returns
-\fBTCL_OK\fR unless an error occurs, in which case \fBTCL_ERROR\fR is
-returned and the interpreter's result is overwritten with an error message.
-.PP
-\fBTk_CanvasPsFont\fR generates Postscript that sets the current font
-to match \fItkFont\fR as closely as possible.
-\fBTk_CanvasPsFont\fR takes into account any font map specified
-in the \fBpostscript\fR command, and it does
-the best it can at mapping X fonts to Postscript fonts.
-It appends the Postscript to interpreter \fIinterp\fR's result and
-returns \fBTCL_OK\fR unless an error occurs, in which case
-\fBTCL_ERROR\fR is returned and the interpreter's result is
-overwritten with an error message.
-.PP
-\fBTk_CanvasPsPath\fR generates Postscript to set the current path
-to the set of points given by \fIcoordPtr\fR and \fInumPoints\fR.
-It appends the resulting Postscript to the result of interpreter \fIinterp\fR.
-.PP
-\fBTk_CanvasPsStipple\fR generates Postscript that will fill the
-current path in stippled fashion.
-It uses \fIbitmap\fR as the stipple pattern and the current Postscript
-color;  ones in the stipple bitmap are drawn in the current color, and
-zeroes are not drawn at all.
-The Postscript is appended to interpreter \fIinterp\fR's result and
-\fBTCL_OK\fR is returned, unless an error occurs, in which case
-\fBTCL_ERROR\fR is returned and the interpreter's result is
-overwritten with an error message.
-.SH KEYWORDS
-bitmap, canvas, color, font, path, Postscript, stipple

doc/CanvTkwin.3

@@ -1,158 +0,0 @@
-'\"
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\"
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.TH Tk_CanvasTkwin 3 4.1 Tk "Tk Library Procedures"
-.so man.macros
-.BS
-.SH NAME
-Tk_CanvasTkwin, Tk_CanvasGetCoord, Tk_CanvasDrawableCoords, Tk_CanvasSetStippleOrigin, Tk_CanvasWindowCoords, Tk_CanvasEventuallyRedraw, Tk_CanvasTagsOption \- utility procedures for canvas type managers
-.SH SYNOPSIS
-.nf
-\fB#include <tk.h>\fR
-.sp
-Tk_Window
-\fBTk_CanvasTkwin\fR(\fIcanvas\fR)
-.sp
-int
-\fBTk_CanvasGetCoord\fR(\fIinterp, canvas, string, doublePtr\fR)
-.sp
-\fBTk_CanvasDrawableCoords\fR(\fIcanvas, x, y, drawableXPtr, drawableYPtr\fR)
-.sp
-\fBTk_CanvasSetStippleOrigin\fR(\fIcanvas, gc\fR)
-.sp
-\fBTk_CanvasWindowCoords\fR(\fIcanvas, x, y, screenXPtr, screenYPtr\fR)
-.sp
-\fBTk_CanvasEventuallyRedraw\fR(\fIcanvas, x1, y1, x2, y2\fR)
-.sp
-Tk_OptionParseProc *\fBTk_CanvasTagsParseProc\fR;
-.sp
-Tk_OptionPrintProc *\fBTk_CanvasTagsPrintProc\fR;
-.SH ARGUMENTS
-.AS Tk_ItemType *drawableXPtr
-.AP Tk_Canvas canvas in
-A token that identifies a canvas widget.
-.AP Tcl_Interp *interp in/out
-Interpreter to use for error reporting.
-.AP "const char" *string in
-Textual description of a canvas coordinate.
-.AP double *doublePtr out
-Points to place to store a converted coordinate.
-.AP double x in
-An x coordinate in the space of the canvas.
-.AP double y in
-A y coordinate in the space of the canvas.
-.AP short *drawableXPtr out
-Pointer to a location in which to store an x coordinate in the space
-of the drawable currently being used to redisplay the canvas.
-.AP short *drawableYPtr out
-Pointer to a location in which to store a y coordinate in the space
-of the drawable currently being used to redisplay the canvas.
-.AP GC gc out
-Graphics context to modify.
-.AP short *screenXPtr out
-Points to a location in which to store the screen coordinate in the
-canvas window that corresponds to \fIx\fR.
-.AP short *screenYPtr out
-Points to a location in which to store the screen coordinate in the
-canvas window that corresponds to \fIy\fR.
-.AP int x1 in
-Left edge of the region that needs redisplay.  Only pixels at or to
-the right of this coordinate need to be redisplayed.
-.AP int y1 in
-Top edge of the region that needs redisplay.  Only pixels at or below
-this coordinate need to be redisplayed.
-.AP int x2 in
-Right edge of the region that needs redisplay.  Only pixels to
-the left of this coordinate need to be redisplayed.
-.AP int y2 in
-Bottom edge of the region that needs redisplay.  Only pixels above
-this coordinate need to be redisplayed.
-.BE
-.SH DESCRIPTION
-.PP
-These procedures are called by canvas type managers to perform various
-utility functions.
-.PP
-\fBTk_CanvasTkwin\fR returns the Tk_Window associated with a particular
-canvas.
-.PP
-\fBTk_CanvasGetCoord\fR translates a string specification of a
-coordinate (such as \fB2p\fR or \fB1.6c\fR) into a double-precision
-canvas coordinate.
-If \fIstring\fR is a valid coordinate description then \fBTk_CanvasGetCoord\fR
-stores the corresponding canvas coordinate at *\fIdoublePtr\fR
-and returns \fBTCL_OK\fR.
-Otherwise it stores an error message in the interpreter result and
-returns \fBTCL_ERROR\fR.
-.PP
-\fBTk_CanvasDrawableCoords\fR is called by type managers during
-redisplay to compute where to draw things.
-Given \fIx\fR and \fIy\fR coordinates in the space of the
-canvas, \fBTk_CanvasDrawableCoords\fR computes the corresponding
-pixel in the drawable that is currently being used for redisplay;
-it returns those coordinates in *\fIdrawableXPtr\fR and *\fIdrawableYPtr\fR.
-This procedure should not be invoked except during redisplay.
-.PP
-\fBTk_CanvasSetStippleOrigin\fR is also used during redisplay.
-It sets the stipple origin in \fIgc\fR so that stipples drawn
-with \fIgc\fR in the current offscreen pixmap will line up
-with stipples drawn with origin (0,0) in the canvas's actual
-window.
-\fBTk_CanvasSetStippleOrigin\fR is needed in order to guarantee
-that stipple patterns line up properly when the canvas is
-redisplayed in small pieces.
-Redisplays are carried out in double-buffered fashion where a
-piece of the canvas is redrawn in an offscreen pixmap and then
-copied back onto the screen.
-In this approach the stipple origins in graphics contexts need to
-be adjusted during each redisplay to compensate for the position
-of the off-screen pixmap relative to the window.
-If an item is being drawn with stipples, its type manager typically
-calls \fBTk_CanvasSetStippleOrigin\fR just before using \fIgc\fR
-to draw something;  after it is finished drawing, the type manager
-calls \fBXSetTSOrigin\fR to restore the origin in \fIgc\fR back to (0,0)
-(the restore is needed because graphics contexts are shared, so
-they cannot be modified permanently).
-.PP
-\fBTk_CanvasWindowCoords\fR is similar to \fBTk_CanvasDrawableCoords\fR
-except that it returns coordinates in the canvas's window on the
-screen, instead of coordinates in an off-screen pixmap.
-.PP
-\fBTk_CanvasEventuallyRedraw\fR may be invoked by a type manager
-to inform Tk that a portion of a canvas needs to be redrawn.
-The \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR arguments
-specify the region that needs to be redrawn, in canvas coordinates.
-Type managers rarely need to invoke \fBTk_CanvasEventuallyRedraw\fR,
-since Tk can normally figure out when an item has changed and make
-the redisplay request on its behalf (this happens, for example
-whenever Tk calls a \fIconfigureProc\fR or \fIscaleProc\fR).
-The only time that a type manager needs to call
-\fBTk_CanvasEventuallyRedraw\fR is if an item has changed on its own
-without being invoked through one of the procedures in its Tk_ItemType;
-this could happen, for example, in an image item if the image is
-modified using image commands.
-.PP
-\fBTk_CanvasTagsParseProc\fR and \fBTk_CanvasTagsPrintProc\fR are
-procedures that handle the \fB\-tags\fR option for canvas items.
-The code of a canvas type manager will not call these procedures
-directly, but will use their addresses to create a \fBTk_CustomOption\fR
-structure for the \fB\-tags\fR option.   The code typically looks
-like this:
-.PP
-.CS
-static const Tk_CustomOption tagsOption = {Tk_CanvasTagsParseProc,
-    Tk_CanvasTagsPrintProc, (ClientData) NULL
-};
-
-static const Tk_ConfigSpec configSpecs[] = {
-    ...
-    {TK_CONFIG_CUSTOM, "\-tags", NULL, NULL,
-        NULL, 0, TK_CONFIG_NULL_OK, &tagsOption},
-    ...
-};
-.CE
-.SH KEYWORDS
-canvas, focus, item type, redisplay, selection, type manager

doc/CanvTxtInfo.3

@@ -1,100 +0,0 @@
-'\"
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\"
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.TH Tk_CanvasTextInfo 3 4.0 Tk "Tk Library Procedures"
-.so man.macros
-.BS
-.SH NAME
-Tk_CanvasTextInfo \- additional information for managing text items in canvases
-.SH SYNOPSIS
-.nf
-\fB#include <tk.h>\fR
-.sp
-Tk_CanvasTextInfo *
-\fBTk_CanvasGetTextInfo\fR(\fIcanvas\fR)
-.SH ARGUMENTS
-.AS Tk_Canvas canvas
-.AP Tk_Canvas canvas in
-A token that identifies a particular canvas widget.
-.BE
-.SH DESCRIPTION
-.PP
-Textual canvas items are somewhat more complicated to manage than
-other items, due to things like the selection and the input focus.
-\fBTk_CanvasGetTextInfo\fR may be invoked by a type manager
-to obtain additional information needed for items that display text.
-The return value from \fBTk_CanvasGetTextInfo\fR is a pointer to
-a structure that is shared between Tk and all the items that display
-text.
-The structure has the following form:
-.CS
-typedef struct Tk_CanvasTextInfo {
-    Tk_3DBorder \fIselBorder\fR;
-    int \fIselBorderWidth\fR;
-    XColor *\fIselFgColorPtr\fR;
-    Tk_Item *\fIselItemPtr\fR;
-    int \fIselectFirst\fR;
-    int \fIselectLast\fR;
-    Tk_Item *\fIanchorItemPtr\fR;
-    int \fIselectAnchor\fR;
-    Tk_3DBorder \fIinsertBorder\fR;
-    int \fIinsertWidth\fR;
-    int \fIinsertBorderWidth\fR;
-    Tk_Item *\fIfocusItemPtr\fR;
-    int \fIgotFocus\fR;
-    int \fIcursorOn\fR;
-} \fBTk_CanvasTextInfo\fR;
-.CE
-The \fBselBorder\fR field identifies a Tk_3DBorder that should be
-used for drawing the background under selected text.
-\fIselBorderWidth\fR gives the width of the raised border around
-selected text, in pixels.
-\fIselFgColorPtr\fR points to an XColor that describes the foreground
-color to be used when drawing selected text.
-\fIselItemPtr\fR points to the item that is currently selected, or
-NULL if there is no item selected or if the canvas does not have the
-selection.
-\fIselectFirst\fR and \fIselectLast\fR give the indices of the first
-and last selected characters in \fIselItemPtr\fR, as returned by the
-\fIindexProc\fR for that item.
-\fIanchorItemPtr\fR points to the item that currently has the selection
-anchor;  this is not necessarily the same as \fIselItemPtr\fR.
-\fIselectAnchor\fR is an index that identifies the anchor position
-within \fIanchorItemPtr\fR.
-\fIinsertBorder\fR contains a Tk_3DBorder to use when drawing the
-insertion cursor;  \fIinsertWidth\fR gives the total width of the
-insertion cursor in pixels, and \fIinsertBorderWidth\fR gives the
-width of the raised  border around the insertion cursor.
-\fIfocusItemPtr\fR identifies the item that currently has the input
-focus, or NULL if there is no such item.
-\fIgotFocus\fR is 1 if the canvas widget has the input focus and
-0 otherwise.
-\fIcursorOn\fR is 1 if the insertion cursor should be drawn in
-\fIfocusItemPtr\fR and 0 if it should not be drawn;  this field
-is toggled on and off by Tk to make the cursor blink.
-.PP
-The structure returned by \fBTk_CanvasGetTextInfo\fR
-is shared between Tk and the type managers;  typically the type manager
-calls \fBTk_CanvasGetTextInfo\fR once when an item is created and
-then saves the pointer in the item's record.
-Tk will update information in the Tk_CanvasTextInfo;  for example,
-a \fBconfigure\fR widget command might change the \fIselBorder\fR
-field, or a \fBselect\fR widget command might change the \fIselectFirst\fR
-field, or Tk might change \fIcursorOn\fR in order to make the insertion
-cursor flash on and off during successive redisplays.
-.PP
-Type managers should treat all of the fields of the Tk_CanvasTextInfo
-structure as read-only, except for \fIselItemPtr\fR, \fIselectFirst\fR,
-\fIselectLast\fR, and \fIselectAnchor\fR.
-Type managers may change \fIselectFirst\fR, \fIselectLast\fR, and
-\fIselectAnchor\fR to adjust for insertions and deletions in the
-item (but only if the item is the current owner of the selection or
-anchor, as determined by \fIselItemPtr\fR or \fIanchorItemPtr\fR).
-If all of the selected text in the item is deleted, the item should
-set \fIselItemPtr\fR to NULL to indicate that there is no longer a
-selection.
-.SH KEYWORDS
-canvas, focus, insertion cursor, selection, selection anchor, text

doc/ChnlStack.3

@@ -0,0 +1,97 @@
+'\"
+'\" Copyright (c) 1999-2000 Ajuba Solutions.
+'\"
+'\" 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_StackChannel 3 8.3 Tcl "Tcl Library Procedures"
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+Tcl_StackChannel, Tcl_UnstackChannel, Tcl_GetStackedChannel, Tcl_GetTopChannel \- manipulate stacked I/O channels
+.SH SYNOPSIS
+.nf
+.nf
+\fB#include <tcl.h>\fR
+.sp
+Tcl_Channel
+\fBTcl_StackChannel\fR(\fIinterp, typePtr, clientData, mask, channel\fR)
+.sp
+int
+\fBTcl_UnstackChannel\fR(\fIinterp, channel\fR)
+.sp
+Tcl_Channel
+\fBTcl_GetStackedChannel\fR(\fIchannel\fR)
+.sp
+Tcl_Channel
+\fBTcl_GetTopChannel\fR(\fIchannel\fR)
+.sp
+.SH ARGUMENTS
+.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\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\fR.
+.AP Tcl_Channel channel in
+An existing Tcl channel such as returned by \fBTcl_CreateChannel\fR.
+.BE
+
+.SH DESCRIPTION
+.PP
+These functions are for use by extensions that add processing layers to Tcl
+I/O channels.  Examples include compression and encryption modules.  These
+functions transparently stack and unstack a new channel on top of an
+existing one.  Any number of channels can be stacked together.
+.PP
+The implementation of the Tcl channel code was rewritten in 8.3.2 to
+correct some problems with the previous implementation with regard to
+stacked channels.  Anyone using stacked channels or creating stacked
+channel drivers should update to the new \fBTCL_CHANNEL_VERSION_2\fR
+\fBTcl_ChannelType\fR structure.  See \fBTcl_CreateChannel\fR for details.
+.PP
+\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
+buffering options are shared between all channels in the stack.  The hidden
+channel does no buffering, newline translations, or character set encoding.
+Instead, the buffering, newline translations, and encoding functions all
+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\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.
+.PP
+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\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\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
+\fBTcl_GetTopChannel\fR returns the top channel in the stack of
+channels the supplied channel is part of.
+.PP
+\fBTcl_GetStackedChannel\fR returns the channel in the stack of
+channels which is just below the supplied channel.
+
+.SH "SEE ALSO"
+Notifier(3), Tcl_CreateChannel(3), Tcl_OpenFileChannel(3), vwait(n).
+
+.SH KEYWORDS
+channel, compression

doc/Clipboard.3

@@ -1,77 +0,0 @@
-'\"
-'\" Copyright (c) 1994 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\"
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.TH Tk_ClipboardClear 3 4.0 Tk "Tk Library Procedures"
-.so man.macros
-.BS
-.SH NAME
-Tk_ClipboardClear, Tk_ClipboardAppend \- Manage the clipboard
-.SH SYNOPSIS
-.nf
-\fB#include <tk.h>\fR
-.sp
-int
-\fBTk_ClipboardClear\fR(\fIinterp, tkwin\fR)
-.sp
-int
-\fBTk_ClipboardAppend\fR(\fIinterp, tkwin, target, format, buffer\fR)
-.SH ARGUMENTS
-.AS Tk_ClipboardClear tkwin
-.AP Tcl_Interp *interp in
-Interpreter to use for reporting errors.
-.AP Tk_Window tkwin in
-Window that determines which display's clipboard to manipulate.
-.AP Atom target in
-Conversion type for this clipboard item;  has same meaning as
-\fItarget\fR argument to \fBTk_CreateSelHandler\fR.
-.AP Atom format in
-Representation to use when data is retrieved;  has same meaning as
-\fIformat\fR argument to \fBTk_CreateSelHandler\fR.
-.AP "const char" *buffer in
-Null terminated string containing the data to be appended to the clipboard.
-.BE
-.SH DESCRIPTION
-.PP
-These two procedures manage the clipboard for Tk.
-The clipboard is typically managed by calling \fBTk_ClipboardClear\fR
-once, then calling \fBTk_ClipboardAppend\fR to add data for any
-number of targets.
-.PP
-\fBTk_ClipboardClear\fR claims the CLIPBOARD selection and frees any
-data items previously stored on the clipboard in this application.
-It normally returns \fBTCL_OK\fR, but if an error occurs it returns
-\fBTCL_ERROR\fR and leaves an error message in interpreter
-\fIinterp\fR's result.
-\fBTk_ClipboardClear\fR must be called before a sequence of
-\fBTk_ClipboardAppend\fR calls can be issued.
-.PP
-\fBTk_ClipboardAppend\fR appends a buffer of data to the clipboard.
-The first buffer for a given \fItarget\fR determines the \fIformat\fR
-for that \fItarget\fR.
-Any successive appends for that \fItarget\fR must have
-the same format or an error will be returned.
-\fBTk_ClipboardAppend\fR returns \fBTCL_OK\fR if the buffer is
-successfully copied onto the clipboard.  If the clipboard is not
-currently owned by the application, either
-because \fBTk_ClipboardClear\fR has not been called or because
-ownership of the clipboard has changed since the last call to
-\fBTk_ClipboardClear\fR,
-\fBTk_ClipboardAppend\fR returns \fBTCL_ERROR\fR and leaves an error
-message in the result of interpreter \fIinterp\fR.
-.PP
-In order to guarantee atomicity, no event handling should occur
-between \fBTk_ClipboardClear\fR and the following
-\fBTk_ClipboardAppend\fR calls (otherwise someone could retrieve
-a partially completed clipboard or claim ownership away from
-this application).
-.PP
-\fBTk_ClipboardClear\fR may invoke callbacks, including arbitrary
-Tcl scripts, as a result of losing the CLIPBOARD selection, so
-any calling function should take care to be re-entrant at the point
-\fBTk_ClipboardClear\fR is invoked.
-.SH KEYWORDS
-append, clipboard, clear, format, type

doc/ClrSelect.3

@@ -1,38 +0,0 @@
-'\"
-'\" Copyright (c) 1992-1994 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\"
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.TH Tk_ClearSelection 3 4.0 Tk "Tk Library Procedures"
-.so man.macros
-.BS
-.SH NAME
-Tk_ClearSelection \- Deselect a selection
-.SH SYNOPSIS
-.nf
-\fB#include <tk.h>\fR
-.sp
-\fBTk_ClearSelection\fR(\fItkwin, selection\fR)
-.SH ARGUMENTS
-.AS Tk_Window tkwin
-.AP Tk_Window tkwin in
-The selection will be cleared from the display containing this
-window.
-.AP Atom selection in
-The name of selection to be cleared.
-.BE
-.SH DESCRIPTION
-.PP
-\fBTk_ClearSelection\fR cancels the selection specified by the atom
-\fIselection\fR for the display containing \fItkwin\fR.
-The selection need not be in \fItkwin\fR itself or even in
-\fItkwin\fR's application.
-If there is a window anywhere on \fItkwin\fR's display that
-owns \fIselection\fR, the window will be notified and the
-selection will be cleared.
-If there is no owner for \fIselection\fR on the display, then the
-procedure has no effect.
-.SH KEYWORDS
-clear, selection

doc/CmdCmplt.3

@@ -0,0 +1,34 @@
+'\"
+'\" Copyright (c) 1989-1993 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.so man.macros
+.TH Tcl_CommandComplete 3 "" Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_CommandComplete \- Check for unmatched braces in a Tcl command
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+int
+\fBTcl_CommandComplete\fR(\fIcmd\fR)
+.SH ARGUMENTS
+.AS "const char" *cmd
+.AP "const char" *cmd in
+Command string to test for completeness.
+.BE
+
+.SH DESCRIPTION
+.PP
+\fBTcl_CommandComplete\fR takes a Tcl command string
+as argument and determines whether it contains one or more
+complete commands (i.e. there are no unclosed quotes, braces,
+brackets, or variable references).
+If the command string is complete then it returns 1; otherwise it returns 0.
+
+.SH KEYWORDS
+complete command, partial command

doc/Concat.3

@@ -0,0 +1,51 @@
+'\"
+'\" Copyright (c) 1989-1993 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.so man.macros
+.TH Tcl_Concat 3 7.5 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_Concat \- concatenate a collection of strings
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+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
+Array of strings to concatenate.  Must have \fIargc\fR entries.
+.BE
+
+.SH DESCRIPTION
+.PP
+\fBTcl_Concat\fR is a utility procedure used by several of the
+Tcl commands.  Given a collection of strings, it concatenates
+them together into a single string, with the original strings
+separated by spaces.  This procedure behaves differently than
+\fBTcl_Merge\fR, in that the arguments are simply concatenated:
+no effort is made to ensure proper list structure.
+However, in most common usage the arguments will all be proper
+lists themselves;  if this is true, then the result will also have
+proper list structure.
+.PP
+\fBTcl_Concat\fR eliminates leading and trailing white space as it
+copies strings from \fBargv\fR to the result.  If an element of
+\fBargv\fR consists of nothing but white space, then that string
+is ignored entirely.  This white-space removal was added to make
+the output of the \fBconcat\fR command cleaner-looking.
+.PP
+The result string is dynamically allocated
+using \fBTcl_Alloc\fR;  the caller must eventually release the space
+by calling \fBTcl_Free\fR.
+.SH "SEE ALSO"
+Tcl_ConcatObj
+.SH KEYWORDS
+concatenate, strings

doc/ConfigWidg.3

@@ -1,631 +0,0 @@
-'\"
-'\" Copyright (c) 1990-1994 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\"
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\"
-.TH Tk_ConfigureWidget 3 4.1 Tk "Tk Library Procedures"
-.so man.macros
-.BS
-.SH NAME
-Tk_ConfigureWidget, Tk_ConfigureInfo, Tk_ConfigureValue, Tk_FreeOptions \- process configuration options for widgets
-.SH SYNOPSIS
-.nf
-\fB#include <tk.h>\fR
-.sp
-int
-\fBTk_ConfigureWidget(\fIinterp, tkwin, specs, argc, argv, widgRec, flags\fB)\fR
-.sp
-int
-\fBTk_ConfigureInfo(\fIinterp, tkwin, specs, widgRec, argvName, flags\fB)\fR
-.sp
-int
-\fBTk_ConfigureValue(\fIinterp, tkwin, specs, widgRec, argvName, flags\fB)\fR
-.sp
-\fBTk_FreeOptions(\fIspecs, widgRec, display, flags\fB)\fR
-.SH ARGUMENTS
-.AS char *widgRec in/out
-.AP Tcl_Interp *interp in
-Interpreter to use for returning error messages.
-.AP Tk_Window tkwin in
-Window used to represent widget (needed to set up X resources).
-.AP "const Tk_ConfigSpec" *specs in
-Pointer to table specifying legal configuration options for this
-widget.
-.AP int argc in
-Number of arguments in \fIargv\fR.
-.AP "const char" **argv in
-Command-line options for configuring widget.
-.AP char *widgRec in/out
-Points to widget record structure.  Fields in this structure get
-modified by \fBTk_ConfigureWidget\fR to hold configuration information.
-.AP int flags in
-If non-zero, then it specifies an OR-ed combination of flags that
-control the processing of configuration information.
-\fBTK_CONFIG_ARGV_ONLY\fR causes the option database and defaults to be
-ignored, and flag bits \fBTK_CONFIG_USER_BIT\fR and higher are used to
-selectively disable entries in \fIspecs\fR.
-.AP "type name" type in
-The name of the type of a widget record.
-.AP "field name" field in
-The name of a field in records of type \fItype\fR.
-.AP "const char" *argvName in
-The name used on Tcl command lines to refer to a particular option
-(e.g. when creating a widget or invoking the \fBconfigure\fR widget
-command).  If non-NULL, then information is returned only for this
-option.  If NULL, then information is returned for all available
-options.
-.AP Display *display in
-Display containing widget whose record is being freed;  needed in
-order to free up resources.
-.BE
-.SH DESCRIPTION
-.PP
-Note: \fBTk_ConfigureWidget\fR should be replaced with the new
-\fBTcl_Obj\fR based API \fBTk_SetOptions\fR.  The old interface is
-retained for backward compatibility.
-.PP
-\fBTk_ConfigureWidget\fR is called to configure various aspects of a
-widget, such as colors, fonts, border width, etc.
-It is intended as a convenience procedure to reduce the amount
-of code that must be written in individual widget managers to
-handle configuration information.
-It is typically
-invoked when widgets are created, and again when the \fBconfigure\fR
-command is invoked for a widget.
-Although intended primarily for widgets, \fBTk_ConfigureWidget\fR
-can be used in other situations where \fIargc-argv\fR information
-is to be used to fill in a record structure, such as configuring
-graphical elements for a canvas widget or entries of a menu.
-.PP
-\fBTk_ConfigureWidget\fR processes
-a table specifying the configuration options that are supported
-(\fIspecs\fR) and a collection of command-line arguments (\fIargc\fR and
-\fIargv\fR) to fill in fields of a record (\fIwidgRec\fR).
-It uses the option database and defaults specified in \fIspecs\fR
-to fill in fields of \fIwidgRec\fR that are not specified in \fIargv\fR.
-\fBTk_ConfigureWidget\fR normally returns the value \fBTCL_OK\fR; in this
-case it does not modify \fIinterp\fR.
-If an error
-occurs then \fBTCL_ERROR\fR is returned and \fBTk_ConfigureWidget\fR will
-leave an error message in interpreter \fIinterp\fR's result in the standard Tcl
-fashion.
-In the event of an error return, some of the fields of \fIwidgRec\fR
-could already have been set, if configuration information for them
-was successfully processed before the error occurred.
-The other fields will be set to reasonable initial values so that
-\fBTk_FreeOptions\fR can be called for cleanup.
-.PP
-The \fIspecs\fR array specifies the kinds of configuration options
-expected by the widget.  Each of its entries specifies one configuration
-option and has the following structure:
-.CS
-typedef struct {
-    int \fItype\fR;
-    const char *\fIargvName\fR;
-    const char *\fIdbName\fR;
-    const char *\fIdbClass\fR;
-    const char *\fIdefValue\fR;
-    int \fIoffset\fR;
-    int \fIspecFlags\fR;
-    const Tk_CustomOption *\fIcustomPtr\fR;
-} \fBTk_ConfigSpec\fR;
-.CE
-The \fItype\fR field indicates what type of configuration option this is
-(e.g. \fBTK_CONFIG_COLOR\fR for a color value, or \fBTK_CONFIG_INT\fR for
-an integer value).  The \fItype\fR field indicates how to use the
-value of the option (more on this below).
-The \fIargvName\fR field is a string such as
-.QW \-font
-or
-.QW \-bg ,
-which is compared with the values in \fIargv\fR (if \fIargvName\fR is
-NULL it means this is a grouped entry;  see \fBGROUPED ENTRIES\fR below).  The
-\fIdbName\fR and \fIdbClass\fR fields are used to look up a value
-for this option in the option database.  The \fIdefValue\fR field
-specifies a default value for this configuration option if no
-value is specified in either \fIargv\fR or the option database.
-\fIOffset\fR indicates where in \fIwidgRec\fR to store information
-about this option, and \fIspecFlags\fR contains additional information
-to control the processing of this configuration option (see FLAGS
-below).
-The last field, \fIcustomPtr\fR, is only used if \fItype\fR is
-\fBTK_CONFIG_CUSTOM\fR;  see CUSTOM OPTION TYPES below.
-.PP
-\fBTk_ConfigureWidget\fR first processes \fIargv\fR to see which
-(if any) configuration options are specified there.  \fIArgv\fR
-must contain an even number of fields;  the first of each pair
-of fields must match the \fIargvName\fR of some entry in \fIspecs\fR
-(unique abbreviations are acceptable),
-and the second field of the pair contains the value for that
-configuration option.  If there are entries in \fIspec\fR for which
-there were no matching entries in \fIargv\fR,
-\fBTk_ConfigureWidget\fR uses the \fIdbName\fR and \fIdbClass\fR
-fields of the \fIspecs\fR entry to probe the option database;  if
-a value is found, then it is used as the value for the option.
-Finally, if no entry is found in the option database, the
-\fIdefValue\fR field of the \fIspecs\fR entry is used as the
-value for the configuration option.  If the \fIdefValue\fR is
-NULL, or if the \fBTK_CONFIG_DONT_SET_DEFAULT\fR bit is set in
-\fIflags\fR, then there is no default value and this \fIspecs\fR entry
-will be ignored if no value is specified in \fIargv\fR or the
-option database.
-.PP
-Once a string value has been determined for a configuration option,
-\fBTk_ConfigureWidget\fR translates the string value into a more useful
-form, such as a color if \fItype\fR is \fBTK_CONFIG_COLOR\fR or an integer
-if \fItype\fR is \fBTK_CONFIG_INT\fR.  This value is then stored in the
-record pointed to by \fIwidgRec\fR.  This record is assumed to
-contain information relevant to the manager of the widget;  its exact
-type is unknown to \fBTk_ConfigureWidget\fR.  The \fIoffset\fR field
-of each \fIspecs\fR entry indicates where in \fIwidgRec\fR to store
-the information about this configuration option.  You should use the
-\fBTk_Offset\fR macro to generate \fIoffset\fR values (see below for
-a description of \fBTk_Offset\fR).  The location indicated by
-\fIwidgRec\fR and \fIoffset\fR will be referred to as the
-.QW target
-in the descriptions below.
-.PP
-The \fItype\fR field of each entry in \fIspecs\fR determines what
-to do with the string value of that configuration option.  The
-legal values for \fItype\fR, and the corresponding actions, are:
-.TP
-\fBTK_CONFIG_ACTIVE_CURSOR\fR
-The value
-must be an ASCII string identifying a cursor in a form
-suitable for passing to \fBTk_GetCursor\fR.
-The value is converted to a \fBTk_Cursor\fR by calling
-\fBTk_GetCursor\fR and the result is stored in the target.
-In addition, the resulting cursor is made the active cursor
-for \fItkwin\fR by calling \fBXDefineCursor\fR.
-If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value
-may be an empty string, in which case the target and \fItkwin\fR's
-active cursor will be set to \fBNone\fR.
-If the previous value of the target
-was not \fBNone\fR, then it is freed by passing it to \fBTk_FreeCursor\fR.
-.TP
-\fBTK_CONFIG_ANCHOR\fR
-The value must be an ASCII string identifying an anchor point in one of the ways
-accepted by \fBTk_GetAnchor\fR.
-The string is converted to a \fBTk_Anchor\fR by calling
-\fBTk_GetAnchor\fR and the result is stored in the target.
-.TP
-\fBTK_CONFIG_BITMAP\fR
-The value must be an ASCII string identifying a bitmap in a form
-suitable for passing to \fBTk_GetBitmap\fR.  The value is converted
-to a \fBPixmap\fR by calling \fBTk_GetBitmap\fR and the result
-is stored in the target.
-If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value
-may be an empty string, in which case the target is set to \fBNone\fR.
-If the previous value of the target
-was not \fBNone\fR, then it is freed by passing it to \fBTk_FreeBitmap\fR.
-.TP
-\fBTK_CONFIG_BOOLEAN\fR
-The value must be an ASCII string specifying a boolean value.  Any
-of the values
-.QW true ,
-.QW yes ,
-.QW on ,
-or
-.QW 1 ,
-or an abbreviation of one of these values, means true;
-any of the values
-.QW false ,
-.QW no ,
-.QW off ,
-or
-.QW 0 ,
-or an abbreviation of one of these values, means false.
-The target is expected to be an integer;  for true values it will
-be set to 1 and for false values it will be set to 0.
-.TP
-\fBTK_CONFIG_BORDER\fR
-The value must be an ASCII string identifying a border color in a form
-suitable for passing to \fBTk_Get3DBorder\fR.  The value is converted
-to a (\fBTk_3DBorder *\fR) by calling \fBTk_Get3DBorder\fR and the result
-is stored in the target.
-If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value
-may be an empty string, in which case the target will be set to NULL.
-If the previous value of the target
-was not NULL, then it is freed by passing it to \fBTk_Free3DBorder\fR.
-.TP
-\fBTK_CONFIG_CAP_STYLE\fR
-The value must be
-an ASCII string identifying a cap style in one of the ways
-accepted by \fBTk_GetCapStyle\fR.
-The string is converted to an integer value corresponding
-to the cap style by calling
-\fBTk_GetCapStyle\fR and the result is stored in the target.
-.TP
-\fBTK_CONFIG_COLOR\fR
-The value must be an ASCII string identifying a color in a form
-suitable for passing to \fBTk_GetColor\fR.  The value is converted
-to an (\fBXColor *\fR) by calling \fBTk_GetColor\fR and the result
-is stored in the target.
-If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value
-may be an empty string, in which case the target will be set to \fBNone\fR.
-If the previous value of the target
-was not NULL, then it is freed by passing it to \fBTk_FreeColor\fR.
-.TP
-\fBTK_CONFIG_CURSOR\fR
-This option is identical to \fBTK_CONFIG_ACTIVE_CURSOR\fR except
-that the new cursor is not made the active one for \fItkwin\fR.
-.TP
-\fBTK_CONFIG_CUSTOM\fR
-This option allows applications to define new option types.
-The \fIcustomPtr\fR field of the entry points to a structure
-defining the new option type.
-See the section \fBCUSTOM OPTION TYPES\fR below for details.
-.TP
-\fBTK_CONFIG_DOUBLE\fR
-The value must be an ASCII floating-point number in
-the format accepted by \fBstrtol\fR.  The string is converted
-to a \fBdouble\fR value, and the value is stored in the
-target.
-.TP
-\fBTK_CONFIG_END\fR
-Marks the end of the table.  The last entry in \fIspecs\fR
-must have this type;  all of its other fields are ignored and it
-will never match any arguments.
-.TP
-\fBTK_CONFIG_FONT\fR
-The value must be an ASCII string identifying a font in a form
-suitable for passing to \fBTk_GetFont\fR.  The value is converted
-to a \fBTk_Font\fR by calling \fBTk_GetFont\fR and the result
-is stored in the target.
-If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value
-may be an empty string, in which case the target will be set to NULL.
-If the previous value of the target
-was not NULL, then it is freed by passing it to \fBTk_FreeFont\fR.
-.TP
-\fBTK_CONFIG_INT\fR
-The value must be an ASCII integer string
-in the format accepted by \fBstrtol\fR (e.g.
-.QW 0
-and
-.QW 0x
-prefixes may be used to specify octal or hexadecimal
-numbers, respectively).  The string is converted to an integer
-value and the integer is stored in the target.
-.TP
-\fBTK_CONFIG_JOIN_STYLE\fR
-The value must be
-an ASCII string identifying a join style in one of the ways
-accepted by \fBTk_GetJoinStyle\fR.
-The string is converted to an integer value corresponding
-to the join style by calling
-\fBTk_GetJoinStyle\fR and the result is stored in the target.
-.TP
-\fBTK_CONFIG_JUSTIFY\fR
-The value must be
-an ASCII string identifying a justification method in one of the
-ways accepted by \fBTk_GetJustify\fR.
-The string is converted to a \fBTk_Justify\fR by calling
-\fBTk_GetJustify\fR and the result is stored in the target.
-.TP
-\fBTK_CONFIG_MM\fR
-The value must specify a screen distance in one of the forms acceptable
-to \fBTk_GetScreenMM\fR.
-The string is converted to double-precision floating-point distance
-in millimeters and the value is stored in the target.
-.TP
-\fBTK_CONFIG_PIXELS\fR
-The value must specify screen units in one of the forms acceptable
-to \fBTk_GetPixels\fR.
-The string is converted to an integer distance in pixels and the
-value is stored in the target.
-.TP
-\fBTK_CONFIG_RELIEF\fR
-The value must be an ASCII string identifying a relief in a form
-suitable for passing to \fBTk_GetRelief\fR.  The value is converted
-to an integer relief value by calling \fBTk_GetRelief\fR and the result
-is stored in the target.
-.TP
-\fBTK_CONFIG_STRING\fR
-A copy
-of the value is made by allocating memory space with
-\fBTcl_Alloc\fR and copying the value into the dynamically-allocated
-space.  A pointer to the new string is stored in the target.
-If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value
-may be an empty string, in which case the target will be set to NULL.
-If the previous value of the target was not NULL, then it is
-freed by passing it to \fBTcl_Free\fR.
-.TP
-\fBTK_CONFIG_SYNONYM\fR
-This \fItype\fR value identifies special entries in \fIspecs\fR that
-are synonyms for other entries.  If an \fIargv\fR value matches the
-\fIargvName\fR of a \fBTK_CONFIG_SYNONYM\fR entry, the entry is not used
-directly. Instead, \fBTk_ConfigureWidget\fR searches \fIspecs\fR
-for another entry whose \fIargvName\fR is the same as the \fIdbName\fR
-field in the \fBTK_CONFIG_SYNONYM\fR entry;  this new entry is used just
-as if its \fIargvName\fR had matched the \fIargv\fR value.  The
-synonym mechanism allows multiple \fIargv\fR values to be used for
-a single configuration option, such as
-.QW \-background
-and
-.QW \-bg .
-.TP
-\fBTK_CONFIG_UID\fR
-The value is translated to a \fBTk_Uid\fR
-(by passing it to \fBTk_GetUid\fR).  The resulting value
-is stored in the target.
-If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR and the value
-is an empty string then the target will be set to NULL.
-.TP
-\fBTK_CONFIG_WINDOW\fR
-The value must be a window path name.  It is translated to a
-\fBTk_Window\fR token and the token is stored in the target.
-.SH "GROUPED ENTRIES"
-.PP
-In some cases it is useful to generate multiple resources from
-a single configuration value.  For example, a color name might
-be used both to generate the background color for a widget (using
-\fBTK_CONFIG_COLOR\fR) and to generate a 3-D border to draw around the
-widget (using \fBTK_CONFIG_BORDER\fR).  In cases like this it is possible
-to specify that several consecutive entries in \fIspecs\fR are to
-be treated as a group.  The first entry is used to determine a value
-(using its \fIargvName\fR, \fIdbName\fR,
-\fIdbClass\fR, and \fIdefValue\fR fields).  The value will be processed
-several times (one for each entry in the group), generating multiple
-different resources and modifying multiple targets within \fIwidgRec\fR.
-Each of the entries after the first must have a NULL value in its
-\fIargvName\fR field;  this indicates that the entry is to be grouped
-with the entry that precedes it.  Only the \fItype\fR and \fIoffset\fR
-fields are used from these follow-on entries.
-.SH "FLAGS"
-.PP
-The \fIflags\fR argument passed to \fBTk_ConfigureWidget\fR is used
-in conjunction with the \fIspecFlags\fR fields in the entries of \fIspecs\fR
-to provide additional control over the processing of configuration
-options.  These values are used in three different ways as
-described below.
-.PP
-First, if the \fIflags\fR argument to \fBTk_ConfigureWidget\fR has
-the \fBTK_CONFIG_ARGV_ONLY\fR bit set (i.e., \fIflags\fR | \fBTK_CONFIG_ARGV_ONLY\fR != 0),
-then the option database and
-\fIdefValue\fR fields are not used.  In this case, if an entry in
-\fIspecs\fR does not match a field in \fIargv\fR then nothing happens:
-the corresponding target is not modified.  This feature is useful
-when the goal is to modify certain configuration options while
-leaving others in their current state, such as when a \fBconfigure\fR
-widget command is being processed.
-.PP
-Second, the \fIspecFlags\fR field of an entry in \fIspecs\fR may be used
-to control the processing of that entry.  Each \fIspecFlags\fR
-field may consists of an OR-ed combination of the following values:
-.TP
-\fBTK_CONFIG_COLOR_ONLY\fR
-If this bit is set then the entry will only be considered if the
-display for \fItkwin\fR has more than one bit plane.  If the display
-is monochromatic then this \fIspecs\fR entry will be ignored.
-.TP
-\fBTK_CONFIG_MONO_ONLY\fR
-If this bit is set then the entry will only be considered if the
-display for \fItkwin\fR has exactly one bit plane.  If the display
-is not monochromatic then this \fIspecs\fR entry will be ignored.
-.TP
-\fBTK_CONFIG_NULL_OK\fR
-This bit is only relevant for some types of entries (see the
-descriptions of the various entry types above).
-If this bit is set, it indicates that an empty string value
-for the field is acceptable and if it occurs then the
-target should be set to NULL or \fBNone\fR, depending
-on the type of the target.
-This flag is typically used to allow a
-feature to be turned off entirely, e.g. set a cursor value to
-\fBNone\fR so that a window simply inherits its parent's cursor.
-If this bit is not set then empty strings are processed as strings,
-which generally results in an error.
-.TP
-\fBTK_CONFIG_DONT_SET_DEFAULT\fR
-If this bit is one, it means that the \fIdefValue\fR field of the
-entry should only be used for returning the default value in
-\fBTk_ConfigureInfo\fR.
-In calls to \fBTk_ConfigureWidget\fR no default will be supplied
-for entries with this flag set;  it is assumed that the
-caller has already supplied a default value in the target location.
-This flag provides a performance optimization where it is expensive
-to process the default string:  the client can compute the default
-once, save the value, and provide it before calling
-\fBTk_ConfigureWidget\fR.
-.TP
-\fBTK_CONFIG_OPTION_SPECIFIED\fR
-This bit is
-deprecated. It used to be set and cleared by \fBTk_ConfigureWidget\fR
-so that callers could detect what entries were specified in
-\fIargv\fR, but it was removed because it was inherently
-thread-unsafe. Code that wishes to detect what options were specified
-should use \fBTk_SetOptions\fR instead.
-.PP
-The \fBTK_CONFIG_MONO_ONLY\fR and \fBTK_CONFIG_COLOR_ONLY\fR flags are typically
-used to specify different default values for
-monochrome and color displays.  This is done by creating two
-entries in \fIspecs\fR that are identical except for their
-\fIdefValue\fR and \fIspecFlags\fR fields.  One entry should have
-the value \fBTK_CONFIG_MONO_ONLY\fR in its \fIspecFlags\fR and the
-default value for monochrome displays in its \fIdefValue\fR;  the
-other entry should have the value \fBTK_CONFIG_COLOR_ONLY\fR in
-its \fIspecFlags\fR and the appropriate \fIdefValue\fR for
-color displays.
-.PP
-Third, it is possible to use \fIflags\fR and \fIspecFlags\fR
-together to selectively disable some entries.  This feature is
-not needed very often.  It is useful in cases where several
-similar kinds of widgets are implemented in one place.  It allows
-a single \fIspecs\fR table to be created with all the configuration
-options for all the widget types.  When processing a particular
-widget type, only entries relevant to that type will be used.  This
-effect is achieved by setting the high-order bits (those in positions
-equal to or greater than \fBTK_CONFIG_USER_BIT\fR) in \fIspecFlags\fR
-values or in \fIflags\fR.  In order for a particular entry in
-\fIspecs\fR to be used, its high-order bits must match exactly
-the high-order bits of the \fIflags\fR value passed to
-\fBTk_ConfigureWidget\fR.  If a \fIspecs\fR table is being used
-for N different widget types, then N of the high-order bits will
-be used.  Each \fIspecs\fR entry will have one of more of those
-bits set in its \fIspecFlags\fR field to indicate the widget types
-for which this entry is valid.  When calling \fBTk_ConfigureWidget\fR,
-\fIflags\fR will have a single one of these bits set to select the
-entries for the desired widget type.  For a working example of
-this feature, see the code in tkButton.c.
-.SH TK_OFFSET
-.PP
-The \fBTk_Offset\fR macro is provided as a safe way of generating
-the \fIoffset\fR values for entries in Tk_ConfigSpec structures.
-It takes two arguments:  the name of a type of record, and the
-name of a field in that record.  It returns the byte offset of
-the named field in records of the given type.
-.SH TK_CONFIGUREINFO
-.PP
-The \fBTk_ConfigureInfo\fR procedure may be used to obtain
-information about one or all of the options for a given widget.
-Given a token for a window (\fItkwin\fR), a table describing the
-configuration options for a class of widgets (\fIspecs\fR), a
-pointer to a widget record containing the current information for
-a widget (\fIwidgRec\fR), and a NULL \fIargvName\fR argument,
-\fBTk_ConfigureInfo\fR generates a string describing all of the
-configuration options for the window.  The string is placed
-in interpreter \fIinterp\fR's result.  Under normal circumstances
-it returns \fBTCL_OK\fR;  if an error occurs then it returns \fBTCL_ERROR\fR
-and the interpreter's result will contain an error message.
-.PP
-If \fIargvName\fR is NULL, then the value left in
-the interpreter's result by \fBTk_ConfigureInfo\fR
-consists of a list of one or more entries, each of which describes
-one configuration option (i.e. one entry in \fIspecs\fR).  Each
-entry in the list will contain either two or five values.  If the
-corresponding entry in \fIspecs\fR has type \fBTK_CONFIG_SYNONYM\fR, then
-the list will contain two values:  the \fIargvName\fR for the entry
-and the \fIdbName\fR (synonym name).  Otherwise the list will contain
-five values:  \fIargvName\fR, \fIdbName\fR, \fIdbClass\fR, \fIdefValue\fR,
-and current value.  The current value is computed from the appropriate
-field of \fIwidgRec\fR by calling procedures like \fBTk_NameOfColor\fR.
-.PP
-If the \fIargvName\fR argument to \fBTk_ConfigureInfo\fR is non-NULL,
-then it indicates a single option, and information is returned only
-for that option.  The string placed in the interpreter's result will be
-a list containing two or five values as described above;  this will
-be identical to the corresponding sublist that would have been returned
-if \fIargvName\fR had been NULL.
-.PP
-The \fIflags\fR argument to \fBTk_ConfigureInfo\fR is used to restrict
-the \fIspecs\fR entries to consider, just as for \fBTk_ConfigureWidget\fR.
-.SH TK_CONFIGUREVALUE
-.PP
-\fBTk_ConfigureValue\fR takes arguments similar to \fBTk_ConfigureInfo\fR;
-instead of returning a list of values, it just returns the current value
-of the option given by \fIargvName\fR (\fIargvName\fR must not be NULL).
-The value is returned in interpreter \fIinterp\fR's result and \fBTCL_OK\fR is
-normally returned as the procedure's result.
-If an error occurs in \fBTk_ConfigureValue\fR (e.g., \fIargvName\fR is
-not a valid option name), \fBTCL_ERROR\fR is returned and an error message
-is left in the interpreter's result.
-This procedure is typically called to implement \fBcget\fR widget
-commands.
-.SH TK_FREEOPTIONS
-.PP
-The \fBTk_FreeOptions\fR procedure may be invoked during widget cleanup
-to release all of the resources associated with configuration options.
-It scans through \fIspecs\fR and for each entry corresponding to a
-resource that must be explicitly freed (e.g. those with
-type \fBTK_CONFIG_COLOR\fR), it frees the resource in the widget record.
-If the field in the widget record does not refer to a resource (e.g.
-it contains a null pointer) then no resource is freed for that
-entry.
-After freeing a resource, \fBTk_FreeOptions\fR sets the
-corresponding field of the widget record to null.
-.SH "CUSTOM OPTION TYPES"
-.PP
-Applications can extend the built-in configuration types with additional
-configuration types by writing procedures to parse and print options
-of the a type and creating a structure pointing to those procedures:
-.CS
-typedef struct Tk_CustomOption {
-    Tk_OptionParseProc *\fIparseProc\fR;
-    Tk_OptionPrintProc *\fIprintProc\fR;
-    ClientData \fIclientData\fR;
-} \fBTk_CustomOption\fR;
-
-typedef int \fBTk_OptionParseProc\fR(
-        ClientData \fIclientData\fR,
-        Tcl_Interp *\fIinterp\fR,
-        Tk_Window \fItkwin\fR,
-        char *\fIvalue\fR,
-        char *\fIwidgRec\fR,
-        int \fIoffset\fR);
-
-typedef const char *\fBTk_OptionPrintProc\fR(
-        ClientData \fIclientData\fR,
-        Tk_Window \fItkwin\fR,
-        char *\fIwidgRec\fR,
-        int \fIoffset\fR,
-        Tcl_FreeProc **\fIfreeProcPtr\fR);
-.CE
-The Tk_CustomOption structure contains three fields, which are pointers
-to the two procedures and a \fIclientData\fR value to be passed to those
-procedures when they are invoked.  The \fIclientData\fR value typically
-points to a structure containing information that is needed by the
-procedures when they are parsing and printing options.
-.PP
-The \fIparseProc\fR procedure is invoked by
-\fBTk_ConfigureWidget\fR to parse a string and store the resulting
-value in the widget record.
-The \fIclientData\fR argument is a copy of the \fIclientData\fR
-field in the Tk_CustomOption structure.
-The \fIinterp\fR argument points to a Tcl interpreter used for
-error reporting.  \fITkwin\fR is a copy of the \fItkwin\fR argument
-to \fBTk_ConfigureWidget\fR.  The \fIvalue\fR argument is a string
-describing the value for the option;  it could have been specified
-explicitly in the call to \fBTk_ConfigureWidget\fR or it could
-come from the option database or a default.
-\fIValue\fR will never be a null pointer but it may point to
-an empty string.
-\fIRecordPtr\fR is the same as the \fIwidgRec\fR argument to
-\fBTk_ConfigureWidget\fR;  it points to the start of the widget
-record to modify.
-The last argument, \fIoffset\fR, gives the offset in bytes from the start
-of the widget record to the location where the option value is to
-be placed.  The procedure should translate the string to whatever
-form is appropriate for the option and store the value in the widget
-record.  It should normally return \fBTCL_OK\fR, but if an error occurs
-in translating the string to a value then it should return \fBTCL_ERROR\fR
-and store an error message in interpreter \fIinterp\fR's result.
-.PP
-The \fIprintProc\fR procedure is called
-by \fBTk_ConfigureInfo\fR to produce a string value describing an
-existing option.
-Its \fIclientData\fR, \fItkwin\fR, \fIwidgRec\fR, and \fIoffset\fR
-arguments all have the same meaning as for Tk_OptionParseProc
-procedures.
-The \fIprintProc\fR procedure should examine the option whose value
-is stored at \fIoffset\fR in \fIwidgRec\fR, produce a string describing
-that option, and return a pointer to the string.
-If the string is stored in dynamically-allocated memory, then
-the procedure must set \fI*freeProcPtr\fR to the address of
-a procedure to call to free the string's memory;  \fBTk_ConfigureInfo\fR
-will call this procedure when it is finished with the string.
-If the result string is stored in static memory then \fIprintProc\fR
-need not do anything with the \fIfreeProcPtr\fR argument.
-.PP
-Once \fIparseProc\fR and \fIprintProc\fR have been defined and a
-Tk_CustomOption structure has been created for them, options of this
-new type may be manipulated with Tk_ConfigSpec entries whose \fItype\fR
-fields are \fBTK_CONFIG_CUSTOM\fR and whose \fIcustomPtr\fR fields point
-to the Tk_CustomOption structure.
-.SH EXAMPLES
-.PP
-Although the explanation of \fBTk_ConfigureWidget\fR is fairly
-complicated, its actual use is pretty straightforward.
-The easiest way to get started is to copy the code
-from an existing widget.
-The library implementation of frames
-(tkFrame.c) has a simple configuration table, and the library
-implementation of buttons (tkButton.c) has a much more complex
-table that uses many of the fancy \fIspecFlags\fR mechanisms.
-.SH "SEE ALSO"
-Tk_SetOptions(3)
-.SH KEYWORDS
-anchor, bitmap, boolean, border, cap style, color, configuration options,
-cursor, custom, double, font, integer, join style, justify, millimeters,
-pixels, relief, synonym, uid

doc/ConfigWind.3

@@ -1,147 +0,0 @@
-'\"
-'\" Copyright (c) 1990-1993 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\"
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.TH Tk_ConfigureWindow 3 4.0 Tk "Tk Library Procedures"
-.so man.macros
-.BS
-.SH NAME
-Tk_ConfigureWindow, Tk_MoveWindow, Tk_ResizeWindow, Tk_MoveResizeWindow, Tk_SetWindowBorderWidth, Tk_ChangeWindowAttributes, Tk_SetWindowBackground, Tk_SetWindowBackgroundPixmap, Tk_SetWindowBorder, Tk_SetWindowBorderPixmap, Tk_SetWindowColormap, Tk_DefineCursor, Tk_UndefineCursor \- change window configuration or attributes
-.SH SYNOPSIS
-.nf
-\fB#include <tk.h>\fR
-.sp
-\fBTk_ConfigureWindow\fR(\fItkwin, valueMask, valuePtr\fR)
-.sp
-\fBTk_MoveWindow\fR(\fItkwin, x, y\fR)
-.sp
-\fBTk_ResizeWindow\fR(\fItkwin, width, height\fR)
-.sp
-\fBTk_MoveResizeWindow\fR(\fItkwin, x,  y, width, height\fR)
-.sp
-\fBTk_SetWindowBorderWidth\fR(\fItkwin, borderWidth\fR)
-.sp
-\fBTk_ChangeWindowAttributes\fR(\fItkwin, valueMask, attsPtr\fR)
-.sp
-\fBTk_SetWindowBackground\fR(\fItkwin, pixel\fR)
-.sp
-\fBTk_SetWindowBackgroundPixmap\fR(\fItkwin, pixmap\fR)
-.sp
-\fBTk_SetWindowBorder\fR(\fItkwin, pixel\fR)
-.sp
-\fBTk_SetWindowBorderPixmap\fR(\fItkwin, pixmap\fR)
-.sp
-\fBTk_SetWindowColormap\fR(\fItkwin, colormap\fR)
-.sp
-\fBTk_DefineCursor\fR(\fItkwin, cursor\fR)
-.sp
-\fBTk_UndefineCursor\fR(\fItkwin\fR)
-.SH ARGUMENTS
-.AS XSetWindowAttributes borderWidth
-.AP Tk_Window tkwin in
-Token for window.
-.AP "unsigned int" valueMask in
-OR-ed mask of values like \fBCWX\fR or \fBCWBorderPixel\fR,
-indicating which fields of \fI*valuePtr\fR or \fI*attsPtr\fR to use.
-.AP XWindowChanges *valuePtr in
-Points to a structure containing new values for the configuration
-parameters selected by \fIvalueMask\fR.  Fields not selected
-by \fIvalueMask\fR are ignored.
-.AP int x in
-New x-coordinate for \fItkwin\fR's top left pixel (including
-border, if any) within tkwin's parent.
-.AP int y in
-New y-coordinate for \fItkwin\fR's top left pixel (including
-border, if any) within tkwin's parent.
-.AP "int" width in
-New width for \fItkwin\fR (interior, not including border).
-.AP "int" height in
-New height for \fItkwin\fR (interior, not including border).
-.AP "int" borderWidth in
-New width for \fItkwin\fR's border.
-.AP XSetWindowAttributes *attsPtr in
-Points to a structure containing new values for the attributes
-given by the \fIvalueMask\fR argument.  Attributes not selected
-by \fIvalueMask\fR are ignored.
-.AP "unsigned long" pixel in
-New background or border color for window.
-.AP Pixmap pixmap in
-New pixmap to use for background or border of \fItkwin\fR.  WARNING:
-cannot necessarily be deleted immediately, as for Xlib calls.  See
-note below.
-.AP Colormap colormap in
-New colormap to use for \fItkwin\fR.
-.AP Tk_Cursor cursor in
-New cursor to use for \fItkwin\fR.  If \fBNone\fR is specified, then
-\fItkwin\fR will not have its own cursor;  it will use the cursor
-of its parent.
-.BE
-.SH DESCRIPTION
-.PP
-These procedures are analogous to the X library procedures
-with similar names, such as \fBXConfigureWindow\fR.  Each
-one of the above procedures calls the corresponding X procedure
-and also saves the configuration information in Tk's local
-structure for the window.  This allows the information to
-be retrieved quickly by the application (using macros such
-as \fBTk_X\fR and \fBTk_Height\fR) without having to contact
-the X server.  In addition, if no X window has actually been
-created for \fItkwin\fR yet, these procedures do not issue
-X operations or cause event handlers to be invoked;  they save
-the information in Tk's local
-structure for the window;  when the window is created later,
-the saved information will be used to configure the window.
-.PP
-See the X library documentation for details on what these
-procedures do and how they use their arguments.
-.PP
-In the procedures \fBTk_ConfigureWindow\fR, \fBTk_MoveWindow\fR,
-\fBTk_ResizeWindow\fR, \fBTk_MoveResizeWindow\fR, and
-\fBTk_SetWindowBorderWidth\fR,
-if \fItkwin\fR is an internal window then event handlers interested
-in configure events are invoked immediately, before the procedure
-returns.  If \fItkwin\fR is a top-level window
-then the event handlers will be invoked later, after X has seen
-the request and returned an event for it.
-.PP
-Applications using Tk should never call procedures like
-\fBXConfigureWindow\fR directly;  they should always use the
-corresponding Tk procedures.
-.PP
-The size and location of a window should only be modified by the
-appropriate geometry manager for that window and never by a window
-itself (but see \fBTk_MoveToplevelWindow\fR for moving a top-level
-window).
-.PP
-You may not use \fBTk_ConfigureWindow\fR to change the
-stacking order of a window (\fIvalueMask\fR may not contain the
-\fBCWSibling\fR or \fBCWStackMode\fR bits).
-To change the stacking order, use the procedure \fBTk_RestackWindow\fR.
-.PP
-The procedure \fBTk_SetWindowColormap\fR will automatically add
-\fItkwin\fR to the \fBTK_COLORMAP_WINDOWS\fR property of its
-nearest top-level ancestor if the new colormap is different from
-that of \fItkwin\fR's parent and \fItkwin\fR is not already in
-the \fBTK_COLORMAP_WINDOWS\fR property.
-.SH BUGS
-.PP
-\fBTk_SetWindowBackgroundPixmap\fR and \fBTk_SetWindowBorderPixmap\fR
-differ slightly from their Xlib counterparts in that the \fIpixmap\fR
-argument may not necessarily be deleted immediately after calling
-one of these procedures.  This is because \fItkwin\fR's window
-may not exist yet at the time of the call, in which case \fIpixmap\fR
-is merely saved and used later when \fItkwin\fR's window is actually
-created.  If you wish to delete \fIpixmap\fR, then call
-\fBTk_MakeWindowExist\fR first to be sure that \fItkwin\fR's window exists
-and \fIpixmap\fR has been passed to the X server.
-.PP
-A similar problem occurs for the \fIcursor\fR argument passed to
-\fBTk_DefineCursor\fR.  The solution is the same as for pixmaps above:
-call \fBTk_MakeWindowExist\fR before freeing the cursor.
-.SH "SEE ALSO"
-Tk_MoveToplevelWindow, Tk_RestackWindow
-.SH KEYWORDS
-attributes, border, color, configure, height, pixel, pixmap, width, window, x, y

doc/CoordToWin.3

@@ -1,47 +0,0 @@
-'\"
-'\" Copyright (c) 1990-1993 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\"
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.TH Tk_CoordsToWindow 3 "" Tk "Tk Library Procedures"
-.so man.macros
-.BS
-.SH NAME
-Tk_CoordsToWindow \- Find window containing a point
-.SH SYNOPSIS
-.nf
-\fB#include <tk.h>\fR
-.sp
-Tk_Window
-\fBTk_CoordsToWindow\fR(\fIrootX, rootY, tkwin\fR)
-.SH ARGUMENTS
-.AS Tk_Window tkwin
-.AP int rootX in
-X-coordinate (in root window coordinates).
-.AP int rootY in
-Y-coordinate (in root window coordinates).
-.AP Tk_Window tkwin in
-Token for window that identifies application.
-.BE
-.SH DESCRIPTION
-.PP
-\fBTk_CoordsToWindow\fR locates the window that contains a given point.
-The point is specified in root coordinates with \fIrootX\fR and
-\fIrootY\fR (if a virtual-root window manager is in use then
-\fIrootX\fR and \fIrootY\fR are in the coordinate system of the
-virtual root window).
-The return value from the procedure is a token for the window that
-contains the given point.
-If the point is not in any window, or if the containing window
-is not in the same application as \fItkwin\fR, then NULL is
-returned.
-.PP
-The containing window is decided using the same rules that determine
-which window contains the mouse cursor:  if a parent and a child both
-contain the point then the child gets preference, and if two siblings
-both contain the point then the highest one in the stacking order
-(i.e. the one that's visible on the screen) gets preference.
-.SH KEYWORDS
-containing, coordinates, root window

doc/CrtChannel.3

@@ -0,0 +1,943 @@
+'\"
+'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
+'\" Copyright (c) 1997-2000 Ajuba Solutions.
+'\"
+'\" 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_CreateChannel 3 8.4 Tcl "Tcl Library Procedures"
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType, Tcl_GetChannelName, Tcl_GetChannelHandle, Tcl_GetChannelMode, Tcl_GetChannelBufferSize, Tcl_SetChannelBufferSize, Tcl_NotifyChannel, Tcl_BadChannelOption, Tcl_ChannelName, Tcl_ChannelVersion, Tcl_ChannelBlockModeProc, Tcl_ChannelCloseProc, Tcl_ChannelClose2Proc, Tcl_ChannelInputProc, Tcl_ChannelOutputProc, Tcl_ChannelSeekProc, Tcl_ChannelWideSeekProc, Tcl_ChannelTruncateProc, Tcl_ChannelSetOptionProc, Tcl_ChannelGetOptionProc, Tcl_ChannelWatchProc, Tcl_ChannelGetHandleProc, Tcl_ChannelFlushProc, Tcl_ChannelHandlerProc, Tcl_ChannelThreadActionProc, Tcl_IsChannelShared, Tcl_IsChannelRegistered, Tcl_CutChannel, Tcl_SpliceChannel, Tcl_IsChannelExisting, Tcl_ClearChannelHandlers, Tcl_GetChannelThread, Tcl_ChannelBuffered \- procedures for creating and manipulating channels
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+Tcl_Channel
+\fBTcl_CreateChannel\fR(\fItypePtr, channelName, instanceData, mask\fR)
+.sp
+ClientData
+\fBTcl_GetChannelInstanceData\fR(\fIchannel\fR)
+.sp
+Tcl_ChannelType *
+\fBTcl_GetChannelType\fR(\fIchannel\fR)
+.sp
+const char *
+\fBTcl_GetChannelName\fR(\fIchannel\fR)
+.sp
+int
+\fBTcl_GetChannelHandle\fR(\fIchannel, direction, handlePtr\fR)
+.sp
+Tcl_ThreadId
+\fBTcl_GetChannelThread\fR(\fIchannel\fR)
+.sp
+int
+\fBTcl_GetChannelMode\fR(\fIchannel\fR)
+.sp
+int
+\fBTcl_GetChannelBufferSize\fR(\fIchannel\fR)
+.sp
+\fBTcl_SetChannelBufferSize\fR(\fIchannel, size\fR)
+.sp
+\fBTcl_NotifyChannel\fR(\fIchannel, mask\fR)
+.sp
+int
+\fBTcl_BadChannelOption\fR(\fIinterp, optionName, optionList\fR)
+.sp
+int
+\fBTcl_IsChannelShared\fR(\fIchannel\fR)
+.sp
+int
+\fBTcl_IsChannelRegistered\fR(\fIinterp, channel\fR)
+.sp
+int
+\fBTcl_IsChannelExisting\fR(\fIchannelName\fR)
+.sp
+void
+\fBTcl_CutChannel\fR(\fIchannel\fR)
+.sp
+void
+\fBTcl_SpliceChannel\fR(\fIchannel\fR)
+.sp
+void
+\fBTcl_ClearChannelHandlers\fR(\fIchannel\fR)
+.sp
+int
+\fBTcl_ChannelBuffered\fR(\fIchannel\fR)
+.sp
+const char *
+\fBTcl_ChannelName\fR(\fItypePtr\fR)
+.sp
+Tcl_ChannelTypeVersion
+\fBTcl_ChannelVersion\fR(\fItypePtr\fR)
+.sp
+Tcl_DriverBlockModeProc *
+\fBTcl_ChannelBlockModeProc\fR(\fItypePtr\fR)
+.sp
+Tcl_DriverCloseProc *
+\fBTcl_ChannelCloseProc\fR(\fItypePtr\fR)
+.sp
+Tcl_DriverClose2Proc *
+\fBTcl_ChannelClose2Proc\fR(\fItypePtr\fR)
+.sp
+Tcl_DriverInputProc *
+\fBTcl_ChannelInputProc\fR(\fItypePtr\fR)
+.sp
+Tcl_DriverOutputProc *
+\fBTcl_ChannelOutputProc\fR(\fItypePtr\fR)
+.sp
+Tcl_DriverSeekProc *
+\fBTcl_ChannelSeekProc\fR(\fItypePtr\fR)
+.sp
+Tcl_DriverWideSeekProc *
+\fBTcl_ChannelWideSeekProc\fR(\fItypePtr\fR)
+.sp
+Tcl_DriverThreadActionProc *
+\fBTcl_ChannelThreadActionProc\fR(\fItypePtr\fR)
+.sp
+.VS 8.5
+Tcl_DriverTruncateProc *
+\fBTcl_ChannelTruncateProc\fR(\fItypePtr\fR)
+.VE 8.5
+.sp
+Tcl_DriverSetOptionProc *
+\fBTcl_ChannelSetOptionProc\fR(\fItypePtr\fR)
+.sp
+Tcl_DriverGetOptionProc *
+\fBTcl_ChannelGetOptionProc\fR(\fItypePtr\fR)
+.sp
+Tcl_DriverWatchProc *
+\fBTcl_ChannelWatchProc\fR(\fItypePtr\fR)
+.sp
+Tcl_DriverGetHandleProc *
+\fBTcl_ChannelGetHandleProc\fR(\fItypePtr\fR)
+.sp
+Tcl_DriverFlushProc *
+\fBTcl_ChannelFlushProc\fR(\fItypePtr\fR)
+.sp
+Tcl_DriverHandlerProc *
+\fBTcl_ChannelHandlerProc\fR(\fItypePtr\fR)
+.sp
+.SH ARGUMENTS
+.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
+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.
+.AP ClientData instanceData in
+Arbitrary one-word value to be associated with this channel.  This
+value is passed to procedures in \fItypePtr\fR when they are invoked.
+.AP int mask in
+OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR to indicate
+whether a channel is readable and writable.
+.AP Tcl_Channel channel in
+The channel to operate on.
+.AP int direction in
+\fBTCL_READABLE\fR means the input handle is wanted; \fBTCL_WRITABLE\fR
+means the output handle is wanted.
+.AP ClientData *handlePtr out
+Points to the location where the desired OS-specific handle should be
+stored.
+.AP int size in
+The size, in bytes, of buffers to allocate in this channel.
+.AP int mask in
+An OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR
+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
+Name of the invalid option.
+.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.
+
+.BE
+
+.SH DESCRIPTION
+.PP
+Tcl uses a two-layered channel architecture. It provides a generic upper
+layer to enable C and Tcl programs to perform input and output using the
+same APIs for a variety of files, devices, sockets etc. The generic C APIs
+are described in the manual entry for \fBTcl_OpenFileChannel\fR.
+.PP
+The lower layer provides type-specific channel drivers for each type
+of device supported on each platform.  This manual entry describes the
+C APIs used to communicate between the generic layer and the
+type-specific channel drivers.  It also explains how new types of
+channels can be added by providing new channel drivers.
+.PP
+Channel drivers consist of a number of components: First, each channel
+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
+\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
+command creates channels that use the file and command channel
+drivers, and the Tcl \fBsocket\fR command creates channels that use
+TCP sockets for network communication.
+.PP
+Third, a channel driver optionally provides a C function to open
+channel instances of that type. For example, \fBTcl_OpenFileChannel\fR
+opens a channel that uses the file channel driver, and
+\fBTcl_OpenTcpClient\fR opens a channel that uses the TCP network
+protocol.  These creation functions typically use
+\fBTcl_CreateChannel\fR internally to open the channel.
+.PP
+To add a new type of channel you must implement a C API or a Tcl command
+that opens a channel by invoking \fBTcl_CreateChannel\fR.
+When your driver calls \fBTcl_CreateChannel\fR it passes in
+a \fBTcl_ChannelType\fR structure describing the driver's I/O
+procedures.
+The generic layer will then invoke the functions referenced in that
+structure to perform operations on the channel.
+.PP
+\fBTcl_CreateChannel\fR opens a new channel and associates the supplied
+\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 \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
+call to \fBTcl_GetStdChannel\fR or a call to \fBTcl_SetStdChannel\fR
+closing this standard channel will cause the next call to
+\fBTcl_CreateChannel\fR to make the new channel the new standard
+channel too. See \fBTcl_StandardChannels\fR for a general treatise
+about standard channels and the behaviour of the Tcl library with
+regard to them.
+.PP
+\fBTcl_GetChannelInstanceData\fR returns the instance data associated with
+the channel in \fIchannel\fR. This is the same as the \fIinstanceData\fR
+argument in the call to \fBTcl_CreateChannel\fR that created this channel.
+.PP
+\fBTcl_GetChannelType\fR returns a pointer to the \fBTcl_ChannelType\fR
+structure used by the channel in the \fIchannel\fR argument. This is
+the same as the \fItypePtr\fR argument in the call to
+\fBTcl_CreateChannel\fR that created this channel.
+.PP
+\fBTcl_GetChannelName\fR returns a string containing the name associated
+with the channel, or NULL if the \fIchannelName\fR argument to
+\fBTcl_CreateChannel\fR was NULL.
+.PP
+\fBTcl_GetChannelHandle\fR places the OS-specific device handle
+associated with \fIchannel\fR for the given \fIdirection\fR in the
+location specified by \fIhandlePtr\fR and returns \fBTCL_OK\fR.  If
+the channel does not have a device handle for the specified direction,
+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
+\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.
+.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
+and output.
+.PP
+\fBTcl_GetChannelBufferSize\fR returns the size, in bytes, of buffers
+allocated to store input or output in \fIchannel\fR. If the value was not set
+by a previous call to \fBTcl_SetChannelBufferSize\fR, described below, then
+the default value of 4096 is returned.
+.PP
+\fBTcl_SetChannelBufferSize\fR sets the size, in bytes, of buffers that
+will be allocated in subsequent operations on the channel to store input or
+output. The \fIsize\fR argument should be between ten and one million,
+allowing buffers of ten bytes to one million bytes. If \fIsize\fR is
+outside this range, \fBTcl_SetChannelBufferSize\fR sets the buffer size to
+4096.
+.PP
+\fBTcl_NotifyChannel\fR is called by a channel driver to indicate to
+the generic layer that the events specified by \fImask\fR have
+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
+\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
+\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).
+.PP
+\fBTcl_IsChannelRegistered\fR checks whether the specified \fIchannel\fR is
+registered in the given \fIinterp\fRreter (result == 1) or not
+(result == 0).
+.PP
+\fBTcl_IsChannelExisting\fR checks whether a channel with the specified
+name is registered in the (thread)-global list of all channels (result
+== 1) or not (result == 0).
+.PP
+\fBTcl_CutChannel\fR removes the specified \fIchannel\fR from the
+(thread)global list of all channels (of the current thread).
+Application to a channel still registered in some interpreter
+is not allowed.
+.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.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.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.5
+.PP
+\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.
+.SH TCL_CHANNELTYPE
+.PP
+A channel driver provides a \fBTcl_ChannelType\fR structure that contains
+pointers to functions that implement the various operations on a channel;
+these operations are invoked as needed by the generic layer.  The structure
+was versioned starting in Tcl 8.3.2/8.4 to correct a problem with stacked
+channel drivers.  See the \fBOLD CHANNEL TYPES\fR section below for
+details about the old structure.
+.PP
+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;
+.VS 8.5
+        Tcl_DriverTruncateProc *\fItruncateProc\fR;
+.VE 8.5
+} Tcl_ChannelType;
+.CE
+.PP
+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, \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
+structure, the following functions should be used to obtain the values:
+\fBTcl_ChannelName\fR, \fBTcl_ChannelVersion\fR,
+\fBTcl_ChannelBlockModeProc\fR, \fBTcl_ChannelCloseProc\fR,
+\fBTcl_ChannelClose2Proc\fR, \fBTcl_ChannelInputProc\fR,
+\fBTcl_ChannelOutputProc\fR, \fBTcl_ChannelSeekProc\fR,
+\fBTcl_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 (i.e. TLS, Trf) have new versions to correspond to the above change
+since the previous code for stacked channels had problems.
+.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.
+\fBfile\fR or \fBsocket\fR.
+.PP
+This value can be retrieved with \fBTcl_ChannelName\fR, which returns
+a pointer to the string.
+.SS VERSION
+.PP
+
+The \fIversion\fR field should be set to the version of the structure
+that you require. \fBTCL_CHANNEL_VERSION_2\fR is the minimum recommended.
+\fBTCL_CHANNEL_VERSION_3\fR must be set to specify the \fIwideSeekProc\fR member.
+\fBTCL_CHANNEL_VERSION_4\fR must be set to specify the \fIthreadActionProc\fR member
+(includes \fIwideSeekProc\fR).
+.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
+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
+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.
+\fIBlockModeProc\fR should match the following prototype:
+.PP
+.CS
+typedef int Tcl_DriverBlockModeProc(
+        ClientData \fIinstanceData\fR,
+        int \fImode\fR);
+.CE
+.PP
+The \fIinstanceData\fR is the same as the value passed to
+\fBTcl_CreateChannel\fR when this channel was created.  The \fImode\fR
+argument is either \fBTCL_MODE_BLOCKING\fR or \fBTCL_MODE_NONBLOCKING\fR to
+set the device into blocking or nonblocking mode. The function should
+return zero if the operation was successful, or a nonzero POSIX error code
+if the operation failed.
+.PP
+If the operation is successful, the function can modify the supplied
+\fIinstanceData\fR to record that the channel entered blocking or
+nonblocking mode and to implement the blocking or nonblocking behavior.
+For some device types, the blocking and nonblocking behavior can be
+implemented by the underlying operating system; for other device types, the
+behavior must be emulated in the channel driver.
+.PP
+This value can be retrieved with \fBTcl_ChannelBlockModeProc\fR, which returns
+a pointer to the function.
+.PP
+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
+unacceptable value. Any confusion here may lead the interpreter into a
+(spurious and difficult to find) deadlock.
+.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
+closed. \fICloseProc\fR must match the following prototype:
+.PP
+.CS
+typedef int Tcl_DriverCloseProc(
+        ClientData \fIinstanceData\fR,
+        Tcl_Interp *\fIinterp\fR);
+.CE
+.PP
+The \fIinstanceData\fR argument is the same as the value provided to
+\fBTcl_CreateChannel\fR when the channel was created. The function should
+release any storage maintained by the channel driver for this channel, and
+close the input and output devices encapsulated by this channel. All queued
+output will have been flushed to the device before this function is called,
+and no further driver operations will be invoked on this instance after
+calling the \fIcloseProc\fR. If the close operation is successful, the
+procedure should return zero; otherwise it should return a nonzero POSIX
+error code. In addition, if an error occurs and \fIinterp\fR is not NULL,
+the procedure should store an error message in the interpreter's result.
+.PP
+Alternatively, channels that support closing the read and write sides
+independently may set \fIcloseProc\fR to \fBTCL_CLOSE2PROC\fR and set
+\fIclose2Proc\fR to the address of a function that matches the
+following prototype:
+.PP
+.CS
+typedef int Tcl_DriverClose2Proc(
+        ClientData \fIinstanceData\fR,
+        Tcl_Interp *\fIinterp\fR,
+        int \fIflags\fR);
+.CE
+.PP
+The \fIclose2Proc\fR will be called with \fIflags\fR set to an OR'ed
+combination of \fBTCL_CLOSE_READ\fR or \fBTCL_CLOSE_WRITE\fR to
+indicate that the driver should close the read and/or write side of
+the channel.  The channel driver may be invoked to perform
+additional operations on the channel after \fIclose2Proc\fR is
+called to close one or both sides of the channel.  If \fIflags\fR is
+\fB0\fR (zero), the driver should close the channel in the manner
+described above for \fIcloseProc\fR.  No further operations will be
+invoked on this instance after \fIclose2Proc\fR is called with all
+flags cleared.  In all cases, the \fIclose2Proc\fR function should
+return zero if the close operation was successful; otherwise it should
+return a nonzero POSIX error code. In addition, if an error occurs and
+\fIinterp\fR is not NULL, the procedure should store an error message
+in the interpreter's result.
+.PP
+The \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
+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);
+.CE
+.PP
+\fIInstanceData\fR is the same as the value passed to
+\fBTcl_CreateChannel\fR when the channel was created.  The \fIbuf\fR
+argument points to an array of bytes in which to store input from the
+device, and the \fIbufSize\fR argument indicates how many bytes are
+available at \fIbuf\fR.
+.PP
+The \fIerrorCodePtr\fR argument points to an integer variable provided by
+the generic layer. If an error occurs, the function should set the variable
+to a POSIX error code that identifies the error that occurred.
+.PP
+The function should read data from the input device encapsulated by the
+channel and store it at \fIbuf\fR.  On success, the function should return
+a nonnegative integer indicating how many bytes were read from the input
+device and stored at \fIbuf\fR. On error, the function should return -1. If
+an error occurs after some data has been read from the device, that data is
+lost.
+.PP
+If \fIinputProc\fR can determine that the input device has some data
+available but less than requested by the \fIbufSize\fR argument, the
+function should only attempt to read as much data as is available and
+return without blocking. If the input device has no data available
+whatsoever and the channel is in nonblocking mode, the function should
+return an \fBEAGAIN\fR error. If the input device has no data available
+whatsoever and the channel is in blocking mode, the function should block
+for the shortest possible time until at least one byte of data can be read
+from the device; then, it should return as much data as it can read without
+blocking.
+.PP
+This value can be retrieved with \fBTcl_ChannelInputProc\fR, which returns
+a pointer to the function.
+.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.
+\fIOutputProc\fR must match the following prototype:
+.PP
+.CS
+typedef int Tcl_DriverOutputProc(
+        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
+\fBTcl_CreateChannel\fR when the channel was created. The \fIbuf\fR
+argument contains an array of bytes to be written to the device, and the
+\fItoWrite\fR argument indicates how many bytes are to be written from the
+\fIbuf\fR argument.
+.PP
+The \fIerrorCodePtr\fR argument points to an integer variable provided by
+the generic layer. If an error occurs, the function should set this
+variable to a POSIX error code that identifies the error.
+.PP
+The function should write the data at \fIbuf\fR to the output device
+encapsulated by the channel. On success, the function should return a
+nonnegative integer indicating how many bytes were written to the output
+device.  The return value is normally the same as \fItoWrite\fR, but may be
+less in some cases such as if the output operation is interrupted by a
+signal. If an error occurs the function should return -1.  In case of
+error, some data may have been written to the device.
+.PP
+If the channel is nonblocking and the output device is unable to absorb any
+data whatsoever, the function should return -1 with an \fBEAGAIN\fR error
+without writing any data.
+.PP
+This value can be retrieved with \fBTcl_ChannelOutputProc\fR, which returns
+a pointer to the function.
+.SS "SEEKPROC AND WIDESEEKPROC"
+.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
+operations will be applied. \fISeekProc\fR must match the following
+prototype:
+.PP
+.CS
+typedef int Tcl_DriverSeekProc(
+        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
+\fBTcl_CreateChannel\fR when this channel was created.  \fIOffset\fR and
+\fIseekMode\fR have the same meaning as for the \fBTcl_Seek\fR
+procedure (described in the manual entry for \fBTcl_OpenFileChannel\fR).
+.PP
+The \fIerrorCodePtr\fR argument points to an integer variable provided by
+the generic layer for returning \fBerrno\fR values from the function.  The
+function should set this variable to a POSIX error code if an error occurs.
+The function should store an \fBEINVAL\fR error code if the channel type
+does not implement seeking.
+.PP
+The return value is the new access point or -1 in case of error. If an
+error occurred, the function should not move the access point.
+.PP
+If there is a non-NULL \fIseekProc\fR field, the \fIwideSeekProc\fR
+field may contain the address of an alternative function to use which
+handles wide (i.e. larger than 32-bit) offsets, so allowing seeks
+within files larger than 2GB.  The \fIwideSeekProc\fR will be called
+in preference to the \fIseekProc\fR, but both must be defined if the
+\fIwideSeekProc\fR is defined.  \fIWideSeekProc\fR must match the
+following prototype:
+.PP
+.CS
+typedef Tcl_WideInt Tcl_DriverWideSeekProc(
+        ClientData \fIinstanceData\fR,
+        Tcl_WideInt \fIoffset\fR,
+        int \fIseekMode\fR,
+        int *\fIerrorCodePtr\fR);
+.CE
+.PP
+The arguments and return values mean the same thing as with
+\fIseekProc\fR above, except that the type of offsets and the return
+type are different.
+.PP
+The \fIseekProc\fR value can be retrieved with
+\fBTcl_ChannelSeekProc\fR, which returns a pointer to the function,
+and similarly the \fIwideSeekProc\fR can be retrieved with
+\fBTcl_ChannelWideSeekProc\fR.
+.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.
+\fIsetOptionProc\fR must match the following prototype:
+.PP
+.CS
+typedef int Tcl_DriverSetOptionProc(
+        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
+the new value for that option, as a string. The \fIinstanceData\fR is the
+same as the value given to \fBTcl_CreateChannel\fR when this channel was
+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
+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
+options. 
+.PP
+If the option value is successfully modified to the new value, the function
+returns \fBTCL_OK\fR.
+It should call \fBTcl_BadChannelOption\fR which itself returns
+\fBTCL_ERROR\fR if the \fIoptionName\fR is
+unrecognized. 
+If \fInewValue\fR specifies a value for the option that
+is not supported or if a system call error occurs,
+the function should leave an error message in the
+\fIresult\fR field of \fIinterp\fR if \fIinterp\fR is not NULL. The
+function should also call \fBTcl_SetErrno\fR to store an appropriate POSIX
+error code.
+.PP
+This value can be retrieved with \fBTcl_ChannelSetOptionProc\fR, which returns
+a pointer to the function.
+.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
+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);
+.CE
+.PP
+\fIOptionName\fR is the name of an option supported by this type of
+channel. If the option name is not NULL, the function stores its current
+value, as a string, in the Tcl dynamic string \fIoptionValue\fR.
+If \fIoptionName\fR is NULL, the function stores in \fIoptionValue\fR an
+alternating list of all supported options and their current values.
+On success, the function returns \fBTCL_OK\fR. 
+It should call \fBTcl_BadChannelOption\fR which itself returns
+\fBTCL_ERROR\fR if the \fIoptionName\fR is
+unrecognized. If a system call error occurs,
+the function should leave an error message in the
+result of \fIinterp\fR if \fIinterp\fR is not NULL. The
+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
+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
+specific options.
+.PP
+This value can be retrieved with \fBTcl_ChannelGetOptionProc\fR, which returns
+a pointer to the function.
+.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
+notice events of interest on this channel.
+\fIWatchProc\fR should match the following prototype:
+.PP
+.CS
+typedef void Tcl_DriverWatchProc(
+        ClientData \fIinstanceData\fR,
+        int \fImask\fR);
+.CE
+.PP
+The \fIinstanceData\fR is the same as the value passed to
+\fBTcl_CreateChannel\fR when this channel was created. The \fImask\fR
+argument is an OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR
+and \fBTCL_EXCEPTION\fR; it indicates events the caller is interested in
+noticing on this channel.
+.PP
+The function should initialize device type specific mechanisms to
+notice when an event of interest is present on the channel.  When one
+or more of the designated events occurs on the channel, the channel
+driver is responsible for calling \fBTcl_NotifyChannel\fR to inform
+the generic channel module.  The driver should take care not to starve
+other channel drivers or sources of callbacks by invoking
+Tcl_NotifyChannel too frequently.  Fairness can be insured by using
+the Tcl event queue to allow the channel event to be scheduled in sequence
+with other events.  See the description of \fBTcl_QueueEvent\fR for
+details on how to queue an event.
+.PP
+This value can be retrieved with \fBTcl_ChannelWatchProc\fR, which returns
+a pointer to the function.
+.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.
+\fIGetHandleProc\fR should match the following prototype:
+.PP
+.CS
+typedef int Tcl_DriverGetHandleProc(
+        ClientData \fIinstanceData\fR,
+        int \fIdirection\fR,
+        ClientData *\fIhandlePtr\fR);
+.CE
+.PP
+\fIInstanceData\fR is the same as the value passed to
+\fBTcl_CreateChannel\fR when this channel was created. The \fIdirection\fR
+argument is either \fBTCL_READABLE\fR to retrieve the handle used
+for input, or \fBTCL_WRITABLE\fR to retrieve the handle used for
+output.
+.PP
+If the channel implementation has device-specific handles, the
+function should retrieve the appropriate handle associated with the
+channel, according the \fIdirection\fR argument.  The handle should be
+stored in the location referred to by \fIhandlePtr\fR, and
+\fBTCL_OK\fR should be returned.  If the channel is not open for the
+specified direction, or if the channel implementation does not use
+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.
+.SS FLUSHPROC
+.PP
+The \fIflushProc\fR field is currently reserved for future use.
+It should be set to NULL.
+\fIFlushProc\fR should match the following prototype:
+.PP
+.CS
+typedef int Tcl_DriverFlushProc(
+        ClientData \fIinstanceData\fR);
+.CE
+.PP
+This value can be retrieved with \fBTcl_ChannelFlushProc\fR, which returns
+a pointer to the function.
+.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
+be defined for stacked channel drivers that wish to be notified of events
+that occur on the underlying (stacked) channel.
+\fIHandlerProc\fR should match the following prototype:
+.PP
+.CS
+typedef int Tcl_DriverHandlerProc(
+        ClientData \fIinstanceData\fR,
+        int \fIinterestMask\fR);
+.CE
+.PP
+\fIInstanceData\fR is the same as the value passed to \fBTcl_CreateChannel\fR
+when this channel was created.  The \fIinterestMask\fR is an OR-ed
+combination of \fBTCL_READABLE\fR or \fBTCL_WRITABLE\fR; it indicates what
+type of event occurred on this channel.
+.PP
+This value can be retrieved with \fBTcl_ChannelHandlerProc\fR, which returns
+a pointer to the function.
+
+.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
+going to move to a different thread, i.e. whenever thread-specific
+driver state might have to initialized or updated. It can be NULL.
+The action \fITCL_CHANNEL_THREAD_REMOVE\fR is used to notify the
+driver that it should update or remove any thread-specific data it
+might be maintaining for the channel.
+.PP
+The action \fITCL_CHANNEL_THREAD_INSERT\fR is used to notify the
+driver that it should update or initialize any thread-specific data it
+might be maintaining using the calling thread as the associate. See
+\fBTcl_CutChannel\fR and \fBTcl_SpliceChannel\fR for more detail.
+.PP
+.CS
+typedef void Tcl_DriverThreadActionProc(
+        ClientData \fIinstanceData\fR,
+        int        \fIaction\fR);
+.CE
+.PP
+\fIInstanceData\fR is the same as the value passed to
+\fBTcl_CreateChannel\fR when this channel was created.
+.PP
+These values can be retrieved with \fBTcl_ChannelThreadActionProc\fR,
+which returns a pointer to the function.
+.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
+.QW "bad option"
+error message in an
+(optional) interpreter.  It is used by channel drivers when 
+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 returns \fBTCL_ERROR\fR
+.PP
+An error message is generated in \fIinterp\fR's result object to
+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
+.CE
+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
+.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;
+} Tcl_ChannelType;
+.CE
+.PP
+It is still possible to create channel with the above structure.  The
+internal channel code will determine the version.  It is imperative to use
+the new \fBTcl_ChannelType\fR structure if you are creating a stacked
+channel driver, due to problems with the earlier stacked channel
+implementation (in 8.2.0 to 8.3.1).
+.PP
+Prior to 8.4.0 (i.e. during the later releases of 8.3 and early part
+of the 8.4 development cycle) the \fBTcl_ChannelType\fR structure
+contained the following fields:
+.PP
+.CS
+typedef struct Tcl_ChannelType {
+        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.
+
+.SH "SEE ALSO"
+Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3), Tcl_QueueEvent(3), Tcl_StackChannel(3), Tcl_GetStdChannel(3)
+
+.SH KEYWORDS
+blocking, channel driver, channel registration, channel type, nonblocking

doc/CrtChnlHdlr.3

@@ -0,0 +1,91 @@
+'\"
+'\" 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.
+'\"
+.so man.macros
+.TH Tcl_CreateChannelHandler 3 7.5 Tcl "Tcl Library Procedures"
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+Tcl_CreateChannelHandler, Tcl_DeleteChannelHandler \- call a procedure when a channel becomes readable or writable
+.SH SYNOPSIS
+.nf
+.nf
+\fB#include <tcl.h>\fR
+.sp
+void
+\fBTcl_CreateChannelHandler\fR(\fIchannel, mask, proc, clientData\fR)
+.sp
+void
+\fBTcl_DeleteChannelHandler\fR(\fIchannel, proc, clientData\fR)
+.sp
+.SH ARGUMENTS
+.AS Tcl_ChannelProc clientData
+.AP Tcl_Channel channel in
+Tcl channel such as returned by \fBTcl_CreateChannel\fR.
+.AP int mask in
+Conditions under which \fIproc\fR should be called: OR-ed combination of
+\fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR and \fBTCL_EXCEPTION\fR. Specify
+a zero value to temporarily disable an existing handler.
+.AP Tcl_FileProc *proc in
+Procedure to invoke whenever the channel indicated by \fIchannel\fR meets
+the conditions specified by \fImask\fR.
+.AP ClientData clientData in
+Arbitrary one-word value to pass to \fIproc\fR.
+.BE
+
+.SH DESCRIPTION
+.PP
+\fBTcl_CreateChannelHandler\fR arranges for \fIproc\fR to be called in the
+future whenever input or output becomes possible on the channel identified
+by \fIchannel\fR, or whenever an exceptional condition exists for
+\fIchannel\fR. The conditions of interest under which \fIproc\fR will be
+invoked are specified by the \fImask\fR argument.
+See the manual entry for \fBfileevent\fR for a precise description of
+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);
+.CE
+.PP
+The \fIclientData\fR argument is the same as the value passed to
+\fBTcl_CreateChannelHandler\fR when the handler was created. Typically,
+\fIclientData\fR points to a data structure containing application-specific
+information about the channel. \fIMask\fR is an integer mask indicating
+which of the requested conditions actually exists for the channel; it will
+contain a subset of the bits from the \fImask\fR argument to
+\fBTcl_CreateChannelHandler\fR when the handler was created.
+.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 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
+handler is created;  instead, the \fImask\fR is changed for the
+existing handler.
+.PP
+\fBTcl_DeleteChannelHandler\fR deletes a channel handler identified by
+\fIchannel\fR, \fIproc\fR and \fIclientData\fR; if no such handler exists,
+the call has no effect.
+.PP
+Channel handlers are invoked via the Tcl event mechanism, so they
+are only useful in applications that are event-driven.
+Note also that the conditions specified in the \fImask\fR argument
+to \fIproc\fR may no longer exist when \fIproc\fR is invoked:  for
+example, if there are two handlers for \fBTCL_READABLE\fR on the same
+channel, the first handler could consume all of the available input
+so that the channel is no longer readable when the second handler
+is invoked.
+For this reason it may be useful to use nonblocking I/O on channels
+for which there are event handlers.
+
+.SH "SEE ALSO"
+Notifier(3), Tcl_CreateChannel(3), Tcl_OpenFileChannel(3), vwait(n).
+
+.SH KEYWORDS
+blocking, callback, channel, events, handler, nonblocking.

doc/CrtCloseHdlr.3

@@ -0,0 +1,58 @@
+'\"
+'\" 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.
+'\"
+.so man.macros
+.TH Tcl_CreateCloseHandler 3 7.5 Tcl "Tcl Library Procedures"
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+Tcl_CreateCloseHandler, Tcl_DeleteCloseHandler \- arrange for callbacks when channels are closed
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+void
+\fBTcl_CreateCloseHandler\fR(\fIchannel, proc, clientData\fR)
+.sp
+void
+\fBTcl_DeleteCloseHandler\fR(\fIchannel, proc, clientData\fR)
+.sp
+.SH ARGUMENTS
+.AS Tcl_CloseProc clientData
+.AP Tcl_Channel channel in
+The channel for which to create or delete a close callback.
+.AP Tcl_CloseProc *proc in
+The procedure to call as the callback.
+.AP ClientData clientData in
+Arbitrary one-word value to pass to \fIproc\fR.
+.BE
+
+.SH DESCRIPTION
+.PP
+\fBTcl_CreateCloseHandler\fR arranges for \fIproc\fR to be called when
+\fIchannel\fR is closed with \fBTcl_Close\fR or
+\fBTcl_UnregisterChannel\fR, or using the Tcl \fBclose\fR command.
+\fIProc\fR should match the following prototype:
+.PP
+.CS
+typedef void Tcl_CloseProc(
+        ClientData \fIclientData\fR);
+.CE
+.PP
+The \fIclientData\fR is the same as the value provided in the call to
+\fBTcl_CreateCloseHandler\fR.
+.PP
+\fBTcl_DeleteCloseHandler\fR removes a close callback for \fIchannel\fR.
+The \fIproc\fR and \fIclientData\fR identify which close callback to
+remove; \fBTcl_DeleteCloseHandler\fR does nothing if its \fIproc\fR and
+\fIclientData\fR arguments do not match the \fIproc\fR and \fIclientData\fR
+for a  close handler for \fIchannel\fR.
+
+.SH "SEE ALSO"
+close(n), Tcl_Close(3), Tcl_UnregisterChannel(3)
+
+.SH KEYWORDS
+callback, channel closing

doc/CrtCmHdlr.3

@@ -1,64 +0,0 @@
-'\"
-'\" Copyright (c) 2000 Ajuba Solutions.
-'\"
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.TH Tk_CreateClientMessageHandler 3 "8.4" Tk "Tk Library Procedures"
-.so man.macros
-.BS
-.SH NAME
-Tk_CreateClientMessageHandler, Tk_DeleteClientMessageHandler \- associate procedure callback with ClientMessage type X events
-.SH SYNOPSIS
-.nf
-\fB#include <tk.h>\fR
-.sp
-\fBTk_CreateClientMessageHandler\fR(\fIproc\fR)
-.sp
-\fBTk_DeleteClientMessageHandler\fR(\fIproc\fR)
-.SH ARGUMENTS
-.AP Tk_ClientMessageProc *proc in
-Procedure to invoke whenever a ClientMessage X event occurs on any display.
-.BE
-.SH DESCRIPTION
-.PP
-\fBTk_CreateClientMessageHandler\fR arranges for \fIproc\fR to be invoked
-in the future whenever a ClientMessage X event occurs that is not handled by
-\fBWM_PROTOCOL\fR.  \fBTk_CreateClientMessageHandler\fR is intended for use
-by applications which need to watch X ClientMessage events, such as drag and
-drop applications.
-.PP
-The callback to \fIproc\fR will be made by \fBTk_HandleEvent\fR;
-this mechanism only works in programs that dispatch events
-through \fBTk_HandleEvent\fR (or through other Tk procedures that
-call \fBTk_HandleEvent\fR, such as \fBTk_DoOneEvent\fR or
-\fBTk_MainLoop\fR).
-.PP
-\fIProc\fR should have arguments and result that match the
-type \fBTk_ClientMessageProc\fR:
-.CS
-typedef int \fBTk_ClientMessageProc\fR(
-        Tk_Window \fItkwin\fR,
-        XEvent *\fIeventPtr\fR);
-.CE
-The \fItkwin\fR parameter to \fIproc\fR is the Tk window which is
-associated with this event.  \fIEventPtr\fR is a pointer to the X event.
-.PP
-Whenever an X ClientMessage event is processed by \fBTk_HandleEvent\fR,
-the \fIproc\fR is called if it was not handled as a \fBWM_PROTOCOL\fR.
-The return value from \fIproc\fR is normally 0.
-A non-zero return value indicates that the event is not to be handled
-further; that is, \fIproc\fR has done all processing that is to be
-allowed for the event.
-.PP
-If there are multiple ClientMessage event handlers, each one is called
-for each event, in the order in which they were established.
-.PP
-\fBTk_DeleteClientMessageHandler\fR may be called to delete a
-previously-created ClientMessage event handler: it deletes each handler it
-finds that matches the \fIproc\fR argument.  If no such handler exists,
-then \fBTk_DeleteClientMessageHandler\fR returns without doing anything.
-Although Tk supports it, it's probably a bad idea to have more than one
-callback with the same \fIproc\fR argument.
-.SH KEYWORDS
-bind, callback, event, handler

doc/CrtCommand.3

@@ -0,0 +1,143 @@
+'\"
+'\" Copyright (c) 1989-1993 The Regents of the University of California.
+'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
+'\"
+'\" 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_CreateCommand 3 "" Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_CreateCommand \- implement new commands in C
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+Tcl_Command
+\fBTcl_CreateCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR)
+.SH ARGUMENTS
+.AS Tcl_CmdDeleteProc *deleteProc
+.AP Tcl_Interp *interp in
+Interpreter in which to create new command.
+.AP "const char" *cmdName in
+Name of command.
+.AP Tcl_CmdProc *proc in
+Implementation of new command:  \fIproc\fR will be called whenever
+\fIcmdName\fR is invoked as a command.
+.AP ClientData clientData in
+Arbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR.
+.AP Tcl_CmdDeleteProc *deleteProc in
+Procedure to call before \fIcmdName\fR is deleted from the interpreter;
+allows for command-specific cleanup.  If NULL, then no procedure is
+called before the command is deleted.
+.BE
+
+.SH DESCRIPTION
+.PP
+\fBTcl_CreateCommand\fR defines a new command in \fIinterp\fR and associates
+it with procedure \fIproc\fR such that whenever \fIcmdName\fR is
+invoked as a Tcl command (via a call to \fBTcl_Eval\fR) the Tcl interpreter
+will call \fIproc\fR to process the command.
+It differs from \fBTcl_CreateObjCommand\fR in that a new string-based
+command is defined;
+that is, a command procedure is defined that takes an array of
+argument strings instead of objects.
+The object-based command procedures registered by \fBTcl_CreateObjCommand\fR
+can execute significantly faster than the string-based command procedures
+defined by \fBTcl_CreateCommand\fR.
+This is because they take Tcl objects as arguments
+and those objects can retain an internal representation that
+can be manipulated more efficiently.
+Also, Tcl's interpreter now uses objects internally.
+In order to invoke a string-based command procedure
+registered by \fBTcl_CreateCommand\fR,
+it must generate and fetch a string representation
+from each argument object before the call
+and create a new Tcl object to hold the string result returned by the
+string-based command procedure.
+New commands should be defined using \fBTcl_CreateObjCommand\fR.
+We support \fBTcl_CreateCommand\fR for backwards compatibility.
+.PP
+The procedures \fBTcl_DeleteCommand\fR, \fBTcl_GetCommandInfo\fR,
+and \fBTcl_SetCommandInfo\fR are used in conjunction with
+\fBTcl_CreateCommand\fR.
+.PP
+\fBTcl_CreateCommand\fR will delete an existing command \fIcmdName\fR,
+if one is already associated with the interpreter.
+It returns a token that may be used to refer
+to the command in subsequent calls to \fBTcl_GetCommandName\fR.
+If \fIcmdName\fR contains any \fB::\fR namespace qualifiers,
+then the command is added to the specified namespace;
+otherwise the command is added to the global namespace.
+If \fBTcl_CreateCommand\fR is called for an interpreter that is in
+the process of being deleted, then it does not create a new command
+and it returns NULL.
+\fIProc\fR should have arguments and result that match the type
+\fBTcl_CmdProc\fR:
+.CS
+typedef int Tcl_CmdProc(
+        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
+arguments given to \fBTcl_CreateCommand\fR.
+Typically, \fIclientData\fR points to an application-specific
+data structure that describes what to do when the command procedure
+is invoked.  \fIArgc\fR and \fIargv\fR describe the arguments to
+the command, \fIargc\fR giving the number of arguments (including
+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.  
+Note that the argument strings should not be modified as they may
+point to constant strings or may be shared with other parts of the
+interpreter.
+.PP
+Note that the argument strings are encoded in normalized UTF-8 since
+version 8.1 of Tcl.
+.PP
+\fIProc\fR must return an integer code that is expected to be one of
+\fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or
+\fBTCL_CONTINUE\fR.  See the Tcl overview man page
+for details on what these codes mean.  Most normal commands will only
+return \fBTCL_OK\fR or \fBTCL_ERROR\fR.  In addition, \fIproc\fR must set
+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 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,
+so simple commands can return an empty result by doing nothing at all.
+.PP
+The contents of the \fIargv\fR array belong to Tcl and are not
+guaranteed to persist once \fIproc\fR returns:  \fIproc\fR should
+not modify them, nor should it set the interpreter result to point
+anywhere within the \fIargv\fR values.
+Call \fBTcl_SetResult\fR with status \fBTCL_VOLATILE\fR if you want
+to return something from the \fIargv\fR array.
+.PP
+\fIDeleteProc\fR will be invoked when (if) \fIcmdName\fR is deleted.
+This can occur through a call to \fBTcl_DeleteCommand\fR or \fBTcl_DeleteInterp\fR,
+or by replacing \fIcmdName\fR in another call to \fBTcl_CreateCommand\fR.
+\fIDeleteProc\fR is invoked before the command is deleted, and gives the
+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);
+.CE
+The \fIclientData\fR argument will be the same as the \fIclientData\fR
+argument passed to \fBTcl_CreateCommand\fR.
+
+.SH "SEE ALSO"
+Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_GetCommandInfo, Tcl_SetCommandInfo, Tcl_GetCommandName, Tcl_SetObjResult
+
+.SH KEYWORDS
+bind, command, create, delete, interpreter, namespace

doc/CrtConsoleChan.3

@@ -1,44 +0,0 @@
-'\"
-'\" Copyright (c) 2007 ActiveState Software Inc.
-'\"
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.TH Tk_InitConsoleChannels 3 8.5 Tk "Tk Library Procedures"
-.so man.macros
-.BS
-.SH NAME
-Tk_InitConsoleChannels \- Install the console channels as standard channels
-.SH SYNOPSIS
-.nf
-\fB#include <tk.h>\fR
-.sp
-\fBTk_InitConsoleChannels\fR(\fIinterp\fR)
-.SH ARGUMENTS
-.AS Tcl_Interp *interp in
-.AP Tcl_Interp *interp in
-Interpreter in which the console channels are created.
-.BE
-.SH DESCRIPTION
-.PP
-\fBTk_InitConsoleChannels\fR is invoked to create a set of console
-channels and install them as the standard channels. All I/O on these
-channels will be discarded until \fBTk_CreateConsoleWindow\fR is
-called to attach the console to a text widget.
-.PP
-This function is for use by shell applications based on Tk, like
-\fBwish\fR, on platforms which have no standard channels in graphical
-mode, like Win32.
-.PP
-The \fIinterp\fR argument is the interpreter in which to create and
-install the console channels.
-.PP
-\fBNOTE:\fR If this function is used it has to be called before the
-first call to \fBTcl_RegisterChannel\fR, directly, or indirectly
-through other channel functions. Because otherwise the standard
-channels will be already initialized to the system defaults, which will
-be nonsensical for the case \fBTk_InitConsoleChannels\fR is for.
-.SH "SEE ALSO"
-console(n)
-.SH KEYWORDS
-standard channels, console

doc/CrtErrHdlr.3

@@ -1,140 +0,0 @@
-'\"
-'\" Copyright (c) 1990 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\"
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.TH Tk_CreateErrorHandler 3 "" Tk "Tk Library Procedures"
-.so man.macros
-.BS
-.SH NAME
-Tk_CreateErrorHandler, Tk_DeleteErrorHandler \- handle X protocol errors
-.SH SYNOPSIS
-.nf
-\fB#include <tk.h>\fR
-.sp
-Tk_ErrorHandler
-\fBTk_CreateErrorHandler\fR(\fIdisplay, error, request, minor, proc, clientData\fR)
-.sp
-\fBTk_DeleteErrorHandler\fR(\fIhandler\fR)
-.SH ARGUMENTS
-.AS "Tk_ErrorHandler" clientData
-.AP Display *display in
-Display whose errors are to be handled.
-.AP int error in
-Match only error events with this value in the \fIerror_code\fR
-field.  If \-1, then match any \fIerror_code\fR value.
-.AP int request in
-Match only error events with this value in the \fIrequest_code\fR
-field.  If \-1, then match any \fIrequest_code\fR value.
-.AP int minor in
-Match only error events with this value in the \fIminor_code\fR
-field.  If \-1, then match any \fIminor_code\fR value.
-.AP Tk_ErrorProc *proc in
-Procedure to invoke whenever an error event is received for
-\fIdisplay\fR and matches \fIerror\fR, \fIrequest\fR, and \fIminor\fR.
-NULL means ignore any matching errors.
-.AP ClientData clientData in
-Arbitrary one-word value to pass to \fIproc\fR.
-.AP Tk_ErrorHandler handler in
-Token for error handler to delete (return value from a previous
-call to \fBTk_CreateErrorHandler\fR).
-.BE
-.SH DESCRIPTION
-.PP
-\fBTk_CreateErrorHandler\fR arranges for a particular procedure
-(\fIproc\fR) to be called whenever certain protocol errors occur on a
-particular display (\fIdisplay\fR).  Protocol errors occur when
-the X protocol is used incorrectly, such as attempting to map a window
-that does not exist.  See the Xlib documentation for \fBXSetErrorHandler\fR
-for more information on the kinds of errors that can occur.
-For \fIproc\fR to be invoked
-to handle a particular error, five things must occur:
-.IP [1]
-The error must pertain to \fIdisplay\fR.
-.IP [2]
-Either the \fIerror\fR argument to \fBTk_CreateErrorHandler\fR
-must have been \-1, or the \fIerror\fR argument must match
-the \fIerror_code\fR field from the error event.
-.IP [3]
-Either the \fIrequest\fR argument to \fBTk_CreateErrorHandler\fR
-must have been \-1, or the \fIrequest\fR argument must match
-the \fIrequest_code\fR field from the error event.
-.IP [4]
-Either the \fIminor\fR argument to \fBTk_CreateErrorHandler\fR
-must have been \-1, or the \fIminor\fR argument must match
-the \fIminor_code\fR field from the error event.
-.IP [5]
-The protocol request to which the error pertains must have been
-made when the handler was active (see below for more information).
-.PP
-\fIProc\fR should have arguments and result that match the
-following type:
-.CS
-typedef int \fBTk_ErrorProc\fR(
-        ClientData \fIclientData\fR,
-        XErrorEvent *\fIerrEventPtr\fR);
-.CE
-The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR
-argument given to \fBTcl_CreateErrorHandler\fR when the callback
-was created.  Typically, \fIclientData\fR points to a data
-structure containing application-specific information that is
-needed to deal with the error.  \fIErrEventPtr\fR is
-a pointer to the X error event.
-The procedure \fIproc\fR should return an integer value.  If it
-returns 0 it means that \fIproc\fR handled the error completely and there
-is no need to take any other action for the error.  If it returns
-non-zero it means \fIproc\fR was unable to handle the error.
-.PP
-If a value of NULL is specified for \fIproc\fR, all matching errors
-will be ignored:  this will produce the same result as if a procedure
-had been specified that always returns 0.
-.PP
-If more than more than one handler matches a particular error, then
-they are invoked in turn.  The handlers will be invoked in reverse
-order of creation:  most recently declared handler first.
-If any handler returns 0, then subsequent (older) handlers will
-not be invoked.  If no handler returns 0, then Tk invokes X's
-default error handler, which prints an error message and aborts the
-program.  If you wish to have a default handler that deals with errors
-that no other handler can deal with, then declare it first.
-.PP
-The X documentation states that
-.QW "the error handler should not call any functions (directly or indirectly) on the display that will generate protocol requests or that will look for input events."
-This restriction applies to handlers declared by \fBTk_CreateErrorHandler\fR;
-disobey it at your own risk.
-.PP
-\fBTk_DeleteErrorHandler\fR may be called to delete a
-previously-created error handler.  The \fIhandler\fR argument
-identifies the error handler, and should be a value returned by
-a previous call to \fBTk_CreateEventHandler\fR.
-.PP
-A particular error handler applies to errors resulting
-from protocol requests generated between
-the call to \fBTk_CreateErrorHandler\fR and the call to
-\fBTk_DeleteErrorHandler\fR.  However, the actual callback
-to \fIproc\fR may not occur until after the \fBTk_DeleteErrorHandler\fR
-call, due to buffering in the client and server.
-If an error event pertains to
-a protocol request made just before calling \fBTk_DeleteErrorHandler\fR,
-then the error event may not have been processed
-before the \fBTk_DeleteErrorHandler\fR
-call.  When this situation arises, Tk will save information about
-the handler and
-invoke the handler's \fIproc\fR later when the error event
-finally arrives.
-If an application wishes to delete an error handler and know
-for certain that all relevant errors have been processed,
-it should first call \fBTk_DeleteErrorHandler\fR and then
-call \fBXSync\fR;  this will flush out any buffered requests and errors,
-but will result in a performance penalty because
-it requires communication to and from the X server.  After the
-\fBXSync\fR call Tk is guaranteed not to call any error
-handlers deleted before the \fBXSync\fR call.
-.PP
-For the Tk error handling mechanism to work properly, it is essential
-that application code never calls \fBXSetErrorHandler\fR directly;
-applications should use only \fBTk_CreateErrorHandler\fR.
-.SH KEYWORDS
-callback, error, event, handler

doc/CrtFileHdlr.3

@@ -0,0 +1,90 @@
+'\"
+'\" Copyright (c) 1990-1994 The Regents of the University of California.
+'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
+'\"
+'\" 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_CreateFileHandler 3 8.0 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_CreateFileHandler, Tcl_DeleteFileHandler \- associate procedure callbacks with files or devices (Unix only)
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+\fBTcl_CreateFileHandler\fR(\fIfd, mask, proc, clientData\fR)
+.sp
+\fBTcl_DeleteFileHandler\fR(\fIfd\fR)
+.SH ARGUMENTS
+.AS Tcl_FileProc clientData
+.AP int fd in
+Unix file descriptor for an open file or device.
+.AP int mask in
+Conditions under which \fIproc\fR should be called:
+OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR,
+and \fBTCL_EXCEPTION\fR.  May be set to 0 to temporarily disable
+a handler.
+.AP Tcl_FileProc *proc in
+Procedure to invoke whenever the file or device indicated
+by \fIfile\fR meets the conditions specified by \fImask\fR.
+.AP ClientData clientData in
+Arbitrary one-word value to pass to \fIproc\fR.
+.BE
+
+.SH DESCRIPTION
+.PP
+\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
+are indicated by \fImask\fR.  For example, if \fImask\fR
+is \fBTCL_READABLE\fR, \fIproc\fR will be called when
+the file is readable.
+The callback to \fIproc\fR is made by \fBTcl_DoOneEvent\fR, so
+\fBTcl_CreateFileHandler\fR is only useful in programs that dispatch
+events through \fBTcl_DoOneEvent\fR or through Tcl commands such
+as \fBvwait\fR.
+.PP
+\fIProc\fR should have arguments and result that match the
+type \fBTcl_FileProc\fR:
+.CS
+typedef void Tcl_FileProc(
+        ClientData \fIclientData\fR,
+        int \fImask\fR);
+.CE
+The \fIclientData\fR parameter to \fIproc\fR is a copy
+of the \fIclientData\fR
+argument given to \fBTcl_CreateFileHandler\fR when the callback
+was created.  Typically, \fIclientData\fR points to a data
+structure containing application-specific information about
+the file.  \fIMask\fR is an integer mask indicating which
+of the requested conditions actually exists for the file;  it
+will contain a subset of the bits in the \fImask\fR argument
+to \fBTcl_CreateFileHandler\fR.
+.PP
+.PP
+There may exist only one handler for a given file at a given time.
+If \fBTcl_CreateFileHandler\fR is called when a handler already
+exists for \fIfd\fR, then the new callback replaces the information
+that was previously recorded.
+.PP
+\fBTcl_DeleteFileHandler\fR may be called to delete the
+file handler for \fIfd\fR;  if no handler exists for the
+file given by \fIfd\fR then the procedure has no effect.
+.PP
+The purpose of file handlers is to enable an application to respond to
+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 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
+Note that these interfaces are only supported by the Unix
+implementation of the Tcl notifier.   
+
+.SH KEYWORDS
+callback, file, handler

doc/CrtGenHdlr.3

@@ -1,81 +0,0 @@
-'\"
-'\" Copyright (c) 1992-1994 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\"
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.TH Tk_CreateGenericHandler 3 "" Tk "Tk Library Procedures"
-.so man.macros
-.BS
-.SH NAME
-Tk_CreateGenericHandler, Tk_DeleteGenericHandler \- associate procedure callback with all X events
-.SH SYNOPSIS
-.nf
-\fB#include <tk.h>\fR
-.sp
-\fBTk_CreateGenericHandler\fR(\fIproc, clientData\fR)
-.sp
-\fBTk_DeleteGenericHandler\fR(\fIproc, clientData\fR)
-.SH ARGUMENTS
-.AS "Tk_GenericProc" clientData
-.AP Tk_GenericProc *proc in
-Procedure to invoke whenever any X event occurs on any display.
-.AP ClientData clientData in
-Arbitrary one-word value to pass to \fIproc\fR.
-.BE
-.SH DESCRIPTION
-.PP
-\fBTk_CreateGenericHandler\fR arranges for \fIproc\fR to be
-invoked in the future whenever any X event occurs.  This mechanism is
-\fInot\fR intended for dispatching X events on windows managed by Tk
-(you should use \fBTk_CreateEventHandler\fR for this purpose).
-\fBTk_CreateGenericHandler\fR is intended for other purposes, such
-as tracing X events, monitoring events on windows not owned by Tk,
-accessing X-related libraries that were not originally designed for
-use with Tk, and so on.
-.PP
-The callback to \fIproc\fR will be made by \fBTk_HandleEvent\fR;
-this mechanism only works in programs that dispatch events
-through \fBTk_HandleEvent\fR (or through other Tk procedures that
-call \fBTk_HandleEvent\fR, such as \fBTk_DoOneEvent\fR or
-\fBTk_MainLoop\fR).
-.PP
-\fIProc\fR should have arguments and result that match the
-type \fBTk_GenericProc\fR:
-.CS
-typedef int \fBTk_GenericProc\fR(
-        ClientData \fIclientData\fR,
-        XEvent *\fIeventPtr\fR);
-.CE
-The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR
-argument given to \fBTk_CreateGenericHandler\fR when the callback
-was created.  Typically, \fIclientData\fR points to a data
-structure containing application-specific information about
-how to handle events.
-\fIEventPtr\fR is a pointer to the X event.
-.PP
-Whenever an X event is processed by \fBTk_HandleEvent\fR, \fIproc\fR
-is called.  The return value from \fIproc\fR is normally 0.
-A non-zero return value indicates that the event is not to be handled
-further; that is, \fIproc\fR has done all processing that is to be
-allowed for the event.
-.PP
-If there are multiple generic event handlers, each one is called
-for each event, in the order in which they were established.
-.PP
-\fBTk_DeleteGenericHandler\fR may be called to delete a
-previously-created generic event handler:  it deletes each handler
-it finds that matches the \fIproc\fR and \fIclientData\fR arguments.  If
-no such handler exists, then \fBTk_DeleteGenericHandler\fR returns
-without doing anything.  Although Tk supports it, it's probably
-a bad idea to have more than one callback with the same
-\fIproc\fR and \fIclientData\fR arguments.
-.PP
-Establishing a generic event handler does nothing to ensure that the
-process will actually receive the X events that the handler wants to
-process.
-For example, it is the caller's responsibility to invoke
-\fBXSelectInput\fR to select the desired events, if that is necessary.
-.SH KEYWORDS
-bind, callback, event, handler

doc/CrtImgType.3

@@ -1,283 +0,0 @@
-'\"
-'\" Copyright (c) 1994 The Regents of the University of California.
-'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
-'\"
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.TH Tk_CreateImageType 3 8.5 Tk "Tk Library Procedures"
-.so man.macros
-.BS
-.SH NAME
-Tk_CreateImageType, Tk_GetImageMasterData, Tk_InitImageArgs \- define new kind of image
-.SH SYNOPSIS
-.nf
-\fB#include <tk.h>\fR
-.sp
-\fBTk_CreateImageType\fR(\fItypePtr\fR)
-.sp
-ClientData
-\fBTk_GetImageMasterData\fR(\fIinterp, name, typePtrPtr\fR)
-.sp
-\fBTk_InitImageArgs\fR(\fIinterp, argc, argvPtr\fR)
-.SH ARGUMENTS
-.AS "const Tk_ImageType" *typePtrPtr
-.AP "const Tk_ImageType" *typePtr in
-Structure that defines the new type of image.
-For Tk 8.4 and earlier this must be static: a
-pointer to this structure is retained by the image code.
-In Tk 8.5, this limitation was relaxed.
-.AP Tcl_Interp *interp in
-Interpreter in which image was created.
-.AP "const char" *name in
-Name of existing image.
-.AP Tk_ImageType **typePtrPtr out
-Points to word in which to store a pointer to type information for
-the given image, if it exists.
-.AP int argc in
-Number of arguments
-.AP char ***argvPtr in/out
-Pointer to argument list
-.BE
-.SH DESCRIPTION
-.PP
-\fBTk_CreateImageType\fR is invoked to define a new kind of image.
-An image type corresponds to a particular value of the \fItype\fR
-argument for the \fBimage create\fR command.  There may exist
-any number of different image types, and new types may be defined
-dynamically by calling \fBTk_CreateImageType\fR.
-For example, there might be one type for 2-color bitmaps,
-another for multi-color images, another for dithered images,
-another for video, and so on.
-.PP
-The code that implements a new image type is called an
-\fIimage manager\fR.
-It consists of a collection of procedures plus three different
-kinds of data structures.
-The first data structure is a Tk_ImageType structure, which contains
-the name of the image type and pointers to five procedures provided
-by the image manager to deal with images of this type:
-.CS
-typedef struct Tk_ImageType {
-    const char *\fIname\fR;
-    Tk_ImageCreateProc *\fIcreateProc\fR;
-    Tk_ImageGetProc *\fIgetProc\fR;
-    Tk_ImageDisplayProc *\fIdisplayProc\fR;
-    Tk_ImageFreeProc *\fIfreeProc\fR;
-    Tk_ImageDeleteProc *\fIdeleteProc\fR;
-} \fBTk_ImageType\fR;
-.CE
-The fields of this structure will be described in later subsections
-of this entry.
-.PP
-The second major data structure manipulated by an image manager
-is called an \fIimage master\fR;  it contains overall information
-about a particular image, such as the values of the configuration
-options specified in an \fBimage create\fR command.
-There will usually be one of these structures for each
-invocation of the \fBimage create\fR command.
-.PP
-The third data structure related to images is an \fIimage instance\fR.
-There will usually be one of these structures for each usage of an
-image in a particular widget.
-It is possible for a single image to appear simultaneously
-in multiple widgets, or even multiple times in the same widget.
-Furthermore, different instances may be on different screens
-or displays.
-The image instance data structure describes things that may
-vary from instance to instance, such as colors and graphics
-contexts for redisplay.
-There is usually one instance structure for each \fB\-image\fR
-option specified for a widget or canvas item.
-.PP
-The following subsections describe the fields of a Tk_ImageType
-in more detail.
-.SS NAME
-.PP
-\fItypePtr->name\fR provides a name for the image type.
-Once \fBTk_CreateImageType\fR returns, this name may be used
-in \fBimage create\fR commands to create images of the new
-type.
-If there already existed an image type by this name then
-the new image type replaces the old one.
-.SS CREATEPROC
-.PP
-\fItypePtr->createProc\fR provides the address of a procedure for
-Tk to call whenever \fBimage create\fR is invoked to create
-an image of the new type.
-\fItypePtr->createProc\fR must match the following prototype:
-.CS
-typedef int \fBTk_ImageCreateProc\fR(
-        Tcl_Interp *\fIinterp\fR,
-        const char *\fIname\fR,
-        int \fIobjc\fR,
-        Tcl_Obj *const \fIobjv\fR[],
-        const Tk_ImageType *\fItypePtr\fR,
-        Tk_ImageMaster \fImaster\fR,
-        ClientData *\fImasterDataPtr\fR);
-.CE
-The \fIinterp\fR argument is the interpreter in which the \fBimage\fR
-command was invoked, and \fIname\fR is the name for the new image,
-which was either specified explicitly in the \fBimage\fR command
-or generated automatically by the \fBimage\fR command.
-The \fIobjc\fR and \fIobjv\fR arguments describe all the configuration
-options for the new image (everything after the name argument to
-\fBimage\fR).
-The \fImaster\fR argument is a token that refers to Tk's information
-about this image;  the image manager must return this token to
-Tk when invoking the \fBTk_ImageChanged\fR procedure.
-Typically \fIcreateProc\fR will parse \fIobjc\fR and \fIobjv\fR
-and create an image master data structure for the new image.
-\fIcreateProc\fR may store an arbitrary one-word value at
-*\fImasterDataPtr\fR, which will be passed back to the
-image manager when other callbacks are invoked.
-Typically the value is a pointer to the master data
-structure for the image.
-.PP
-If \fIcreateProc\fR encounters an error, it should leave an error
-message in the interpreter result and return \fBTCL_ERROR\fR;  otherwise
-it should return \fBTCL_OK\fR.
-.PP
-\fIcreateProc\fR should call \fBTk_ImageChanged\fR in order to set the
-size of the image and request an initial redisplay.
-.SS GETPROC
-.PP
-\fItypePtr->getProc\fR is invoked by Tk whenever a widget
-calls \fBTk_GetImage\fR to use a particular image.
-This procedure must match the following prototype:
-.CS
-typedef ClientData \fBTk_ImageGetProc\fR(
-        Tk_Window \fItkwin\fR,
-        ClientData \fImasterData\fR);
-.CE
-The \fItkwin\fR argument identifies the window in which the
-image will be used and \fImasterData\fR is the value
-returned by \fIcreateProc\fR when the image master was created.
-\fIgetProc\fR will usually create a data structure for the new
-instance, including such things as the resources needed to
-display the image in the given window.
-\fIgetProc\fR returns a one-word token for the instance, which
-is typically the address of the instance data structure.
-Tk will pass this value back to the image manager when invoking
-its \fIdisplayProc\fR and \fIfreeProc\fR procedures.
-.SS DISPLAYPROC
-.PP
-\fItypePtr->displayProc\fR is invoked by Tk whenever an image needs
-to be displayed (i.e., whenever a widget calls \fBTk_RedrawImage\fR).
-\fIdisplayProc\fR must match the following prototype:
-.CS
-typedef void \fBTk_ImageDisplayProc\fR(
-        ClientData \fIinstanceData\fR,
-        Display *\fIdisplay\fR,
-        Drawable \fIdrawable\fR,
-        int \fIimageX\fR,
-        int \fIimageY\fR,
-        int \fIwidth\fR,
-        int \fIheight\fR,
-        int \fIdrawableX\fR,
-        int \fIdrawableY\fR);
-.CE
-The \fIinstanceData\fR will be the same as the value returned by
-\fIgetProc\fR when the instance was created.
-\fIdisplay\fR and \fIdrawable\fR indicate where to display the
-image;  \fIdrawable\fR may be a pixmap rather than
-the window specified to \fIgetProc\fR (this is usually the case,
-since most widgets double-buffer their redisplay to get smoother
-visual effects).
-\fIimageX\fR, \fIimageY\fR, \fIwidth\fR, and \fIheight\fR
-identify the region of the image that must be redisplayed.
-This region will always be within the size of the image
-as specified in the most recent call to \fBTk_ImageChanged\fR.
-\fIdrawableX\fR and \fIdrawableY\fR indicate where in \fIdrawable\fR
-the image should be displayed;  \fIdisplayProc\fR should display
-the given region of the image so that point (\fIimageX\fR, \fIimageY\fR)
-in the image appears at (\fIdrawableX\fR, \fIdrawableY\fR) in \fIdrawable\fR.
-.SS FREEPROC
-.PP
-\fItypePtr->freeProc\fR contains the address of a procedure that
-Tk will invoke when an image instance is released (i.e., when
-\fBTk_FreeImage\fR is invoked).
-This can happen, for example, when a widget is deleted or a image item
-in a canvas is deleted, or when the image displayed in a widget or
-canvas item is changed.
-\fIfreeProc\fR must match the following prototype:
-.CS
-typedef void \fBTk_ImageFreeProc\fR(
-        ClientData \fIinstanceData\fR,
-        Display *\fIdisplay\fR);
-.CE
-The \fIinstanceData\fR will be the same as the value returned by
-\fIgetProc\fR when the instance was created, and \fIdisplay\fR
-is the display containing the window for the instance.
-\fIfreeProc\fR should release any resources associated with the
-image instance, since the instance will never be used again.
-.SS DELETEPROC
-.PP
-\fItypePtr->deleteProc\fR is a procedure that Tk invokes when an
-image is being deleted (i.e. when the \fBimage delete\fR command
-is invoked).
-Before invoking \fIdeleteProc\fR Tk will invoke \fIfreeProc\fR for
-each of the image's instances.
-\fIdeleteProc\fR must match the following prototype:
-.CS
-typedef void \fBTk_ImageDeleteProc\fR(
-        ClientData \fImasterData\fR);
-.CE
-The \fImasterData\fR argument will be the same as the value
-stored in \fI*masterDataPtr\fR by \fIcreateProc\fR when the
-image was created.
-\fIdeleteProc\fR should release any resources associated with
-the image.
-.SH TK_GETIMAGEMASTERDATA
-.PP
-The procedure \fBTk_GetImageMasterData\fR may be invoked to retrieve
-information about an image.  For example, an image manager can use this
-procedure to locate its image master data for an image.
-If there exists an image named \fIname\fR
-in the interpreter given by \fIinterp\fR, then \fI*typePtrPtr\fR is
-filled in with type information for the image (the \fItypePtr\fR value
-passed to \fBTk_CreateImageType\fR when the image type was registered)
-and the return value is the ClientData value returned by the
-\fIcreateProc\fR when the image was created (this is typically a
-pointer to the image master data structure).  If no such image exists
-then NULL is returned and NULL is stored at \fI*typePtrPtr\fR.
-.SH "LEGACY INTERFACE SUPPORT"
-.PP
-In Tk 8.2 and earlier, the definition of \fBTk_ImageCreateProc\fR
-was incompatibly different, with the following prototype:
-.CS
-typedef int \fBTk_ImageCreateProc\fR(
-        Tcl_Interp *\fIinterp\fR,
-        char *\fIname\fR,
-        int \fIargc\fR,
-        char **\fIargv\fR,
-        Tk_ImageType *\fItypePtr\fR,
-        Tk_ImageMaster \fImaster\fR,
-        ClientData *\fImasterDataPtr\fR);
-.CE
-Legacy programs and libraries dating from those days may still
-contain code that defines extended Tk image types using the old
-interface.  The Tk header file will still support this legacy
-interface if the code is compiled with the macro \fBUSE_OLD_IMAGE\fR
-defined.
-.PP
-When the \fBUSE_OLD_IMAGE\fR legacy support is enabled, you may
-see the routine \fBTk_InitImageArgs\fR in use.  This was a migration
-tool used to create stub-enabled extensions that could be loaded
-into interps containing all versions of Tk 8.1 and later.  Tk 8.5 no longer
-provides this routine, but uses a macro to convert any attempted
-calls of this routine into an empty comment.  Any stub-enabled
-extension providing an extended image type via the legacy interface
-that is compiled against Tk 8.5 headers and linked against the
-Tk 8.5 stub library will produce a file that can be loaded only
-into interps with Tk 8.5 or later; that is, the normal stub-compatibility
-rules.  If a developer needs to generate from such code a file
-that is loadable into interps with Tk 8.4 or earlier, they must
-use Tk 8.4 headers and stub libraries to do so.
-.PP
-Any new code written today should not make use of the legacy
-interfaces.  Expect their support to go away in Tk 9.
-.SH "SEE ALSO"
-Tk_ImageChanged, Tk_GetImage, Tk_FreeImage, Tk_RedrawImage, Tk_SizeOfImage
-.SH KEYWORDS
-image manager, image type, instance, master

doc/CrtInterp.3

@@ -0,0 +1,127 @@
+'\"
+'\" Copyright (c) 1989-1993 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.so man.macros
+.TH Tcl_CreateInterp 3 7.5 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_CreateInterp, Tcl_DeleteInterp, Tcl_InterpDeleted \- create and delete Tcl command interpreters
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+Tcl_Interp *
+\fBTcl_CreateInterp\fR()
+.sp
+\fBTcl_DeleteInterp\fR(\fIinterp\fR)
+.sp
+int
+\fBTcl_InterpDeleted\fR(\fIinterp\fR)
+.SH ARGUMENTS
+.AS Tcl_Interp *interp
+.AP Tcl_Interp *interp in
+Token for interpreter to be destroyed.
+.BE
+
+.SH DESCRIPTION
+.PP
+\fBTcl_CreateInterp\fR creates a new interpreter structure and returns
+a token for it.  The token is required in calls to most other Tcl
+procedures, such as \fBTcl_CreateCommand\fR, \fBTcl_Eval\fR, and
+\fBTcl_DeleteInterp\fR.
+Clients are only allowed to access a few of the fields of
+Tcl_Interp structures;  see the \fBTcl_Interp\fR
+and \fBTcl_CreateCommand\fR man pages for details.
+The new interpreter is initialized with the built-in Tcl commands
+and with the variables documented in tclvars(n).  To bind in
+additional commands, call \fBTcl_CreateCommand\fR.
+.PP
+\fBTcl_DeleteInterp\fR marks an interpreter as deleted; the interpreter
+will eventually be deleted when all calls to \fBTcl_Preserve\fR for it have
+been matched by calls to \fBTcl_Release\fR. At that time, all of the
+resources associated with it, including variables, procedures, and
+application-specific command bindings, will be deleted.  After
+\fBTcl_DeleteInterp\fR returns any attempt to use \fBTcl_Eval\fR on the
+interpreter will fail and return \fBTCL_ERROR\fR. After the call to
+\fBTcl_DeleteInterp\fR it is safe to examine the interpreter's result,
+query or set the values of variables, define, undefine or retrieve
+procedures, and examine the runtime evaluation stack. See below, in the
+section \fBINTERPRETERS AND MEMORY MANAGEMENT\fR for details.
+.PP
+\fBTcl_InterpDeleted\fR returns nonzero if \fBTcl_DeleteInterp\fR was
+called with \fIinterp\fR as its argument; this indicates that the
+interpreter will eventually be deleted, when the last call to
+\fBTcl_Preserve\fR for it is matched by a call to \fBTcl_Release\fR. If
+nonzero is returned, further calls to \fBTcl_Eval\fR in this interpreter
+will return \fBTCL_ERROR\fR.
+.PP
+\fBTcl_InterpDeleted\fR is useful in deletion callbacks to distinguish
+between when only the memory the callback is responsible for is being
+deleted and when the whole interpreter is being deleted. In the former case
+the callback may recreate the data being deleted, but this would lead to an
+infinite loop if the interpreter were being deleted.
+
+.SH "INTERPRETERS AND MEMORY MANAGEMENT"
+.PP
+\fBTcl_DeleteInterp\fR can be called at any time on an interpreter that may
+be used by nested evaluations and C code in various extensions. Tcl
+implements a simple mechanism that allows callers to use interpreters
+without worrying about the interpreter being deleted in a nested call, and
+without requiring special code to protect the interpreter, in most cases.
+This mechanism ensures that nested uses of an interpreter can safely
+continue using it even after \fBTcl_DeleteInterp\fR is called.
+.PP
+The mechanism relies on matching up calls to \fBTcl_Preserve\fR with calls
+to \fBTcl_Release\fR. If \fBTcl_DeleteInterp\fR has been called, only when
+the last call to \fBTcl_Preserve\fR is matched by a call to
+\fBTcl_Release\fR, will the interpreter be freed. See the manual entry for
+\fBTcl_Preserve\fR for a description of these functions.
+.PP
+The rules for when the user of an interpreter must call \fBTcl_Preserve\fR
+and \fBTcl_Release\fR are simple:
+.TP
+Interpreters Passed As Arguments
+Functions that are passed an interpreter as an argument can safely use the
+interpreter without any special protection. Thus, when you write an
+extension consisting of new Tcl commands, no special code is needed to
+protect interpreters received as arguments. This covers the majority of all
+uses.
+.TP
+Interpreter Creation And Deletion
+When a new interpreter is created and used in a call to \fBTcl_Eval\fR,
+\fBTcl_VarEval\fR, \fBTcl_GlobalEval\fR, \fBTcl_SetVar\fR, or
+\fBTcl_GetVar\fR, a pair of calls to \fBTcl_Preserve\fR and
+\fBTcl_Release\fR should be wrapped around all uses of the interpreter.
+Remember that it is unsafe to use the interpreter once \fBTcl_Release\fR
+has been called. To ensure that the interpreter is properly deleted when
+it is no longer needed, call \fBTcl_InterpDeleted\fR to test if some other
+code already called \fBTcl_DeleteInterp\fR; if not, call
+\fBTcl_DeleteInterp\fR before calling \fBTcl_Release\fR in your own code.
+.TP
+Retrieving An Interpreter From A Data Structure
+When an interpreter is retrieved from a data structure (e.g. the client
+data of a callback) for use in \fBTcl_Eval\fR, \fBTcl_VarEval\fR,
+\fBTcl_GlobalEval\fR, \fBTcl_SetVar\fR, or \fBTcl_GetVar\fR, a pair of
+calls to \fBTcl_Preserve\fR and \fBTcl_Release\fR should be wrapped around
+all uses of the interpreter; it is unsafe to reuse the interpreter once
+\fBTcl_Release\fR has been called.  If an interpreter is stored inside a
+callback data structure, an appropriate deletion cleanup mechanism should
+be set up by the code that creates the data structure so that the
+interpreter is removed from the data structure (e.g. by setting the field
+to NULL) when the interpreter is deleted. Otherwise, you may be using an
+interpreter that has been freed and whose memory may already have been
+reused.
+.PP
+All uses of interpreters in Tcl and Tk have already been protected.
+Extension writers should ensure that their code also properly protects any
+additional interpreters used, as described above.
+
+.SH "SEE ALSO"
+Tcl_Preserve(3), Tcl_Release(3)
+
+.SH KEYWORDS
+command, create, delete, interpreter

doc/CrtItemType.3

@@ -1,695 +0,0 @@
-'\"
-'\" Copyright (c) 1994-1995 Sun Microsystems, Inc.
-'\"
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.TH Tk_CreateItemType 3 4.0 Tk "Tk Library Procedures"
-.so man.macros
-.BS
-.SH NAME
-Tk_CreateItemType, Tk_GetItemTypes \- define new kind of canvas item
-.SH SYNOPSIS
-.nf
-\fB#include <tk.h>\fR
-.sp
-\fBTk_CreateItemType\fR(\fItypePtr\fR)
-.sp
-Tk_ItemType *
-\fBTk_GetItemTypes\fR()
-.SH ARGUMENTS
-.AS Tk_ItemType *typePtr
-.AP Tk_ItemType *typePtr in
-Structure that defines the new type of canvas item.
-.BE
-.SH INTRODUCTION
-.PP
-\fBTk_CreateItemType\fR is invoked to define a new kind of canvas item
-described by the \fItypePtr\fR argument.
-An item type corresponds to a particular value of the \fItype\fR
-argument to the \fBcreate\fR widget command for canvases, and
-the code that implements a canvas item type is called a \fItype manager\fR.
-Tk defines several built-in item types, such as \fBrectangle\fR
-and \fBtext\fR and \fBimage\fR, but \fBTk_CreateItemType\fR
-allows additional item types to be defined.
-Once \fBTk_CreateItemType\fR returns, the new item type may be used
-in new or existing canvas widgets just like the built-in item
-types.
-.PP
-\fBTk_GetItemTypes\fR returns a pointer to the first in the list
-of all item types currently defined for canvases.
-The entries in the list are linked together through their
-\fInextPtr\fR fields, with the end of the list marked by a
-NULL \fInextPtr\fR.
-.PP
-You may find it easier to understand the rest of this manual entry
-by looking at the code for an existing canvas item type such as
-bitmap (in the file tkCanvBmap.c) or text (tkCanvText.c).
-The easiest way to create a new type manager is to copy the code
-for an existing type and modify it for the new type.
-.PP
-Tk provides a number of utility procedures for the use of canvas
-type managers, such as \fBTk_CanvasCoords\fR and \fBTk_CanvasPsColor\fR;
-these are described in separate manual entries.
-.SH "DATA STRUCTURES"
-.PP
-A type manager consists of a collection of procedures that provide a
-standard set of operations on items of that type.
-The type manager deals with three kinds of data
-structures.
-The first data structure is a Tk_ItemType; it contains
-information such as the name of the type and pointers to
-the standard procedures implemented by the type manager:
-.PP
-.CS
-typedef struct Tk_ItemType {
-    const char *\fIname\fR;
-    int \fIitemSize\fR;
-    Tk_ItemCreateProc *\fIcreateProc\fR;
-    const Tk_ConfigSpec *\fIconfigSpecs\fR;
-    Tk_ItemConfigureProc *\fIconfigProc\fR;
-    Tk_ItemCoordProc *\fIcoordProc\fR;
-    Tk_ItemDeleteProc *\fIdeleteProc\fR;
-    Tk_ItemDisplayProc *\fIdisplayProc\fR;
-    int \fIalwaysRedraw\fR;
-    Tk_ItemPointProc *\fIpointProc\fR;
-    Tk_ItemAreaProc *\fIareaProc\fR;
-    Tk_ItemPostscriptProc *\fIpostscriptProc\fR;
-    Tk_ItemScaleProc *\fIscaleProc\fR;
-    Tk_ItemTranslateProc *\fItranslateProc\fR;
-    Tk_ItemIndexProc *\fIindexProc\fR;
-    Tk_ItemCursorProc *\fIicursorProc\fR;
-    Tk_ItemSelectionProc *\fIselectionProc\fR;
-    Tk_ItemInsertProc *\fIinsertProc\fR;
-    Tk_ItemDCharsProc *\fIdCharsProc\fR;
-    Tk_ItemType *\fInextPtr\fR;
-} \fBTk_ItemType\fR;
-.CE
-.PP
-The fields of a Tk_ItemType structure are described in more detail
-later in this manual entry.
-When \fBTk_CreateItemType\fR is called, its \fItypePtr\fR
-argument must point to a structure with all of the fields initialized
-except \fInextPtr\fR, which Tk sets to link all the types together
-into a list.
-The structure must be in permanent memory (either statically
-allocated or dynamically allocated but never freed); Tk retains
-a pointer to this structure.
-.PP
-The second data structure manipulated by a type manager is an
-\fIitem record\fR.
-For each item in a canvas there exists one item record.
-All of the items of a given type generally have item records with
-the same structure, but different types usually have different
-formats for their item records.
-The first part of each item record is a header with a standard structure
-defined by Tk via the type Tk_Item; the rest of the item
-record is defined by the type manager.
-A type manager must define its item records with a Tk_Item as
-the first field.
-For example, the item record for bitmap items is defined as follows:
-.PP
-.CS
-typedef struct BitmapItem {
-    Tk_Item \fIheader\fR;
-    double \fIx\fR, \fIy\fR;
-    Tk_Anchor \fIanchor\fR;
-    Pixmap \fIbitmap\fR;
-    XColor *\fIfgColor\fR;
-    XColor *\fIbgColor\fR;
-    GC \fIgc\fR;
-} \fBBitmapItem\fR;
-.CE
-.PP
-The \fIheader\fR substructure contains information used by Tk
-to manage the item, such as its identifier, its tags, its type,
-and its bounding box.
-The fields starting with \fIx\fR belong to the type manager:
-Tk will never read or write them.
-The type manager should not need to read or write any of the
-fields in the header except for four fields
-whose names are \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR.
-These fields give a bounding box for the items using integer
-canvas coordinates: the item should not cover any pixels
-with x-coordinate lower than \fIx1\fR or y-coordinate
-lower than \fIy1\fR, nor should it cover any pixels with
-x-coordinate greater than or equal to \fIx2\fR or y-coordinate
-greater than or equal to \fIy2\fR.
-It is up to the type manager to keep the bounding box up to
-date as the item is moved and reconfigured.
-.PP
-Whenever Tk calls a procedure in a type manager it passes in a pointer
-to an item record.
-The argument is always passed as a pointer to a Tk_Item; the type
-manager will typically cast this into a pointer to its own specific
-type, such as BitmapItem.
-.PP
-The third data structure used by type managers has type
-Tk_Canvas; it serves as an opaque handle for the canvas widget
-as a whole.
-Type managers need not know anything about the contents of this
-structure.
-A Tk_Canvas handle is typically passed in to the
-procedures of a type manager, and the type manager can pass the
-handle back to library procedures such as Tk_CanvasTkwin
-to fetch information about the canvas.
-.SH "TK_ITEMTYPE FIELDS"
-.SS NAME
-.PP
-This section and the ones that follow describe each of the fields
-in a Tk_ItemType structure in detail.
-The \fIname\fR field provides a string name for the item type.
-Once \fBTk_CreateImageType\fR returns, this name may be used
-in \fBcreate\fR widget commands to create items of the new
-type.
-If there already existed an item type by this name then
-the new item type replaces the old one.
-.SS "FLAGS (IN ALWAYSREDRAW)"
-.PP
-The \fItypePtr\->alwaysRedraw\fR field (so named for historic reasons)
-contains a collection of flag bits that modify how the canvas core interacts
-with the item. The following bits are defined:
-.TP
-\fB1\fR
-.
-Indicates that the item should always be redrawn when any part of the canvas
-is redrawn, rather than only when the bounding box of the item overlaps the
-area being redrawn. This is used by window items, for example, which need to
-unmap subwindows that are not on the screen.
-.TP
-\fBTK_CONFIG_OBJS\fR
-.
-Indicates that operations which would otherwise take a string (or array of
-strings) actually take a Tcl_Obj reference (or an array of such references).
-The operations to which this applies are the \fIconfigProc\fR, the
-\fIcoordProc\fR, the \fIcreateProc\fR, the \fIindexProc\fR and the
-\fIinsertProc\fR.
-.TP
-\fBTK_MOVABLE_POINTS\fR
-.VS 8.6
-Indicates that the item supports the \fIdCharsProc\fR, \fIindexProc\fR and
-\fIinsertProc\fR with the same semantics as Tk's built-in line and polygon
-types, and that hence individual coordinate points can be moved. Must not be
-set if any of the above methods is NULL.
-.VE 8.6
-.SS ITEMSIZE
-.PP
-\fItypePtr\->itemSize\fR gives the size in bytes of item records
-of this type, including the Tk_Item header.
-Tk uses this size to allocate memory space for items of the type.
-All of the item records for a given type must have the same size.
-If variable length fields are needed for an item (such as a list
-of points for a polygon), the type manager can allocate a separate
-object of variable length and keep a pointer to it in the item record.
-.SS CREATEPROC
-.PP
-\fItypePtr\->createProc\fR points to a procedure for
-Tk to call whenever a new item of this type is created.
-\fItypePtr\->createProc\fR must match the following prototype:
-.PP
-.CS
-typedef int \fBTk_ItemCreateProc\fR(
-        Tcl_Interp *\fIinterp\fR,
-        Tk_Canvas \fIcanvas\fR,
-        Tk_Item *\fIitemPtr\fR,
-        int \fIobjc\fR,
-        Tcl_Obj *const \fIobjv\fR[]);
-.CE
-.PP
-The \fIinterp\fR argument is the interpreter in which the canvas's
-\fBcreate\fR widget command was invoked, and \fIcanvas\fR is a
-handle for the canvas widget.
-\fIitemPtr\fR is a pointer to a newly-allocated item of
-size \fItypePtr\->itemSize\fR.
-Tk has already initialized the item's header (the first
-\fBsizeof(Tk_ItemType)\fR bytes).
-The \fIobjc\fR and \fIobjv\fR arguments describe all of the
-arguments to the \fBcreate\fR command after the \fItype\fR
-argument.
-Note that if \fBTK_CONFIG_OBJS\fR is not set in the
-\fItypePtr\->alwaysRedraw\fR field, the \fIobjv\fR parameter will actually
-contain a pointer to an array of constant strings.
-For example, in the widget command:
-.PP
-.CS
-\fB\&.c create rectangle 10 20 50 50 \-fill black\fR
-.CE
-.PP
-\fIobjc\fR will be \fB6\fR and \fIobjv\fR[0] will contain the
-integer object \fB10\fR.
-.PP
-\fIcreateProc\fR should use \fIobjc\fR and \fIobjv\fR to initialize
-the type-specific parts of the item record and set an initial value
-for the bounding box in the item's header.
-It should return a standard Tcl completion code and leave an
-error message in the interpreter result if an error occurs.
-If an error occurs Tk will free the item record, so \fIcreateProc\fR
-must be sure to leave the item record in a clean state if it returns an error
-(e.g., it must free any additional memory that it allocated for
-the item).
-.SS CONFIGSPECS
-.PP
-Each type manager must provide a standard table describing its
-configuration options, in a form suitable for use with
-\fBTk_ConfigureWidget\fR.
-This table will normally be used by \fItypePtr\->createProc\fR
-and \fItypePtr\->configProc\fR, but Tk also uses it directly
-to retrieve option information in the \fBitemcget\fR and
-\fBitemconfigure\fR widget commands.
-\fItypePtr\->configSpecs\fR must point to the configuration table
-for this type.
-Note: Tk provides a custom option type \fBtk_CanvasTagsOption\fR
-for implementing the \fB\-tags\fR option; see an existing type
-manager for an example of how to use it in \fIconfigSpecs\fR.
-.SS CONFIGPROC
-.PP
-\fItypePtr\->configProc\fR is called by Tk whenever the
-\fBitemconfigure\fR widget command is invoked to change the
-configuration options for a canvas item.
-This procedure must match the following prototype:
-.PP
-.CS
-typedef int \fBTk_ItemConfigureProc\fR(
-        Tcl_Interp *\fIinterp\fR,
-        Tk_Canvas \fIcanvas\fR,
-        Tk_Item *\fIitemPtr\fR,
-        int \fIobjc\fR,
-        Tcl_Obj *const \fIobjv\fR[],
-        int \fIflags\fR);
-.CE
-.PP
-The \fIinterp\fR argument identifies the interpreter in which the
-widget command was invoked, \fIcanvas\fR is a handle for the canvas
-widget, and \fIitemPtr\fR is a pointer to the item being configured.
-\fIobjc\fR and \fIobjv\fR contain the configuration options.
-Note that if \fBTK_CONFIG_OBJS\fR is not set in the
-\fItypePtr\->alwaysRedraw\fR field, the \fIobjv\fR parameter will actually
-contain a pointer to an array of constant strings.
-For example, if the following command is invoked:
-.PP
-.CS
-\fB\&.c itemconfigure 2 \-fill red \-outline black\fR
-.CE
-.PP
-\fIobjc\fR is \fB4\fR and \fIobjv\fR contains the string objects \fB\-fill\fR
-through \fBblack\fR.
-\fIobjc\fR will always be an even value.
-The \fIflags\fR argument contains flags to pass to \fBTk_ConfigureWidget\fR;
-currently this value is always \fBTK_CONFIG_ARGV_ONLY\fR when Tk
-invokes \fItypePtr\->configProc\fR, but the type manager's \fIcreateProc\fR
-procedure will usually invoke \fIconfigProc\fR with different flag values.
-.PP
-\fItypePtr\->configProc\fR returns a standard Tcl completion code and
-leaves an error message in the interpreter result if an error occurs.
-It must update the item's bounding box to reflect the new configuration
-options.
-.SS COORDPROC
-.PP
-\fItypePtr\->coordProc\fR is invoked by Tk to implement the \fBcoords\fR
-widget command for an item.
-It must match the following prototype:
-.PP
-.CS
-typedef int \fBTk_ItemCoordProc\fR(
-        Tcl_Interp *\fIinterp\fR,
-        Tk_Canvas \fIcanvas\fR,
-        Tk_Item *\fIitemPtr\fR,
-        int \fIobjc\fR,
-        Tcl_Obj *const \fIobjv\fR[]);
-.CE
-.PP
-The arguments \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR
-all have the standard meanings, and \fIobjc\fR and \fIobjv\fR
-describe the coordinate arguments.
-Note that if \fBTK_CONFIG_OBJS\fR is not set in the
-\fItypePtr\->alwaysRedraw\fR field, the \fIobjv\fR parameter will actually
-contain a pointer to an array of constant strings.
-For example, if the following widget command is invoked:
-.PP
-.CS
-\fB\&.c coords 2 30 90\fR
-.CE
-.PP
-\fIobjc\fR will be \fB2\fR and \fBobjv\fR will contain the integer objects
-\fB30\fR and \fB90\fR.
-.PP
-The \fIcoordProc\fR procedure should process the new coordinates,
-update the item appropriately (e.g., it must reset the bounding
-box in the item's header), and return a standard Tcl completion
-code.
-If an error occurs, \fIcoordProc\fR must leave an error message in
-the interpreter result.
-.SS DELETEPROC
-.PP
-\fItypePtr\->deleteProc\fR is invoked by Tk to delete an item
-and free any resources allocated to it.
-It must match the following prototype:
-.PP
-.CS
-typedef void \fBTk_ItemDeleteProc\fR(
-        Tk_Canvas \fIcanvas\fR,
-        Tk_Item *\fIitemPtr\fR,
-        Display *\fIdisplay\fR);
-.CE
-.PP
-The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual
-interpretations, and \fIdisplay\fR identifies the X display containing
-the canvas.
-\fIdeleteProc\fR must free up any resources allocated for the item,
-so that Tk can free the item record.
-\fIdeleteProc\fR should not actually free the item record; this will
-be done by Tk when \fIdeleteProc\fR returns.
-.SS "DISPLAYPROC"
-.PP
-\fItypePtr\->displayProc\fR is invoked by Tk to redraw an item
-on the screen.
-It must match the following prototype:
-.PP
-.CS
-typedef void \fBTk_ItemDisplayProc\fR(
-        Tk_Canvas \fIcanvas\fR,
-        Tk_Item *\fIitemPtr\fR,
-        Display *\fIdisplay\fR,
-        Drawable \fIdst\fR,
-        int \fIx\fR,
-        int \fIy\fR,
-        int \fIwidth\fR,
-        int \fIheight\fR);
-.CE
-.PP
-The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning.
-\fIdisplay\fR identifies the display containing the canvas, and
-\fIdst\fR specifies a drawable in which the item should be rendered;
-typically this is an off-screen pixmap, which Tk will copy into
-the canvas's window once all relevant items have been drawn.
-\fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR specify a rectangular
-region in canvas coordinates, which is the area to be redrawn;
-only information that overlaps this area needs to be redrawn.
-Tk will not call \fIdisplayProc\fR unless the item's bounding box
-overlaps the redraw area, but the type manager may wish to use
-the redraw area to optimize the redisplay of the item.
-.PP
-Because of scrolling and the use of off-screen pixmaps for
-double-buffered redisplay, the item's coordinates in \fIdst\fR
-will not necessarily be the same as those in the canvas.
-\fIdisplayProc\fR should call \fBTk_CanvasDrawableCoords\fR
-to transform coordinates from those of the canvas to those
-of \fIdst\fR.
-.PP
-Normally an item's \fIdisplayProc\fR is only invoked if the item
-overlaps the area being displayed.
-However, if bit zero of \fItypePtr\->alwaysRedraw\fR is 1,
-(i.e.\|
-.QW "\fItypePtr\->alwaysRedraw & 1 == 1\fR" )
-then \fIdisplayProc\fR is invoked during every redisplay operation,
-even if the item does not overlap the area of redisplay; this is useful for
-cases such as window items, where the subwindow needs to be unmapped when it
-is off the screen.
-.SS POINTPROC
-.PP
-\fItypePtr\->pointProc\fR is invoked by Tk to find out how close
-a given point is to a canvas item.
-Tk uses this procedure for purposes such as locating the item
-under the mouse or finding the closest item to a given point.
-The procedure must match the following prototype:
-.PP
-.CS
-typedef double \fBTk_ItemPointProc\fR(
-        Tk_Canvas \fIcanvas\fR,
-        Tk_Item *\fIitemPtr\fR,
-        double *\fIpointPtr\fR);
-.CE
-.PP
-\fIcanvas\fR and \fIitemPtr\fR have the usual meaning.
-\fIpointPtr\fR points to an array of two numbers giving
-the x and y coordinates of a point.
-\fIpointProc\fR must return a real value giving the distance
-from the point to the item, or 0 if the point lies inside
-the item.
-.SS AREAPROC
-.PP
-\fItypePtr\->areaProc\fR is invoked by Tk to find out the relationship
-between an item and a rectangular area.
-It must match the following prototype:
-.PP
-.CS
-typedef int \fBTk_ItemAreaProc\fR(
-        Tk_Canvas \fIcanvas\fR,
-        Tk_Item *\fIitemPtr\fR,
-        double *\fIrectPtr\fR);
-.CE
-.PP
-\fIcanvas\fR and \fIitemPtr\fR have the usual meaning.
-\fIrectPtr\fR points to an array of four real numbers;
-the first two give the x and y coordinates of the upper left
-corner of a rectangle, and the second two give the x and y
-coordinates of the lower right corner.
-\fIareaProc\fR must return \-1 if the item lies entirely outside
-the given area, 0 if it lies partially inside and partially
-outside the area, and 1 if it lies entirely inside the area.
-.SS POSTSCRIPTPROC
-.PP
-\fItypePtr\->postscriptProc\fR is invoked by Tk to generate
-Postscript for an item during the \fBpostscript\fR widget command.
-If the type manager is not capable of generating Postscript then
-\fItypePtr\->postscriptProc\fR should be NULL.
-The procedure must match the following prototype:
-.PP
-.CS
-typedef int \fBTk_ItemPostscriptProc\fR(
-        Tcl_Interp *\fIinterp\fR,
-        Tk_Canvas \fIcanvas\fR,
-        Tk_Item *\fIitemPtr\fR,
-        int \fIprepass\fR);
-.CE
-.PP
-The \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR arguments all have
-standard meanings; \fIprepass\fR will be described below.
-If \fIpostscriptProc\fR completes successfully, it should append
-Postscript for the item to the information in the interpreter result
-(e.g. by calling \fBTcl_AppendResult\fR, not \fBTcl_SetResult\fR)
-and return \fBTCL_OK\fR.
-If an error occurs, \fIpostscriptProc\fR should clear the result
-and replace its contents with an error message; then it should
-return \fBTCL_ERROR\fR.
-.PP
-Tk provides a collection of utility procedures to simplify
-\fIpostscriptProc\fR.
-For example, \fBTk_CanvasPsColor\fR will generate Postscript to set
-the current color to a given Tk color and \fBTk_CanvasPsFont\fR will
-set up font information.
-When generating Postscript, the type manager is free to change the
-graphics state of the Postscript interpreter, since Tk places
-\fBgsave\fR and \fBgrestore\fR commands around the Postscript for
-the item.
-The type manager can use canvas x coordinates directly in its Postscript,
-but it must call \fBTk_CanvasPsY\fR to convert y coordinates from
-the space of the canvas (where the origin is at the
-upper left) to the space of Postscript (where the origin is at the
-lower left).
-.PP
-In order to generate Postscript that complies with the Adobe Document
-Structuring Conventions, Tk actually generates Postscript in two passes.
-It calls each item's \fIpostscriptProc\fR in each pass.
-The only purpose of the first pass is to collect font information
-(which is done by \fBTk_CanvasPsFont\fR); the actual Postscript is
-discarded.
-Tk sets the \fIprepass\fR argument to \fIpostscriptProc\fR to 1
-during the first pass; the type manager can use \fIprepass\fR to skip
-all Postscript generation except for calls to \fBTk_CanvasPsFont\fR.
-During the second pass \fIprepass\fR will be 0, so the type manager
-must generate complete Postscript.
-.SS SCALEPROC
-.PP
-\fItypePtr\->scaleProc\fR is invoked by Tk to rescale a canvas item
-during the \fBscale\fR widget command.
-The procedure must match the following prototype:
-.PP
-.CS
-typedef void \fBTk_ItemScaleProc\fR(
-        Tk_Canvas \fIcanvas\fR,
-        Tk_Item *\fIitemPtr\fR,
-        double \fIoriginX\fR,
-        double \fIoriginY\fR,
-        double \fIscaleX\fR,
-        double \fIscaleY\fR);
-.CE
-.PP
-The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning.
-\fIoriginX\fR and \fIoriginY\fR specify an origin relative to which
-the item is to be scaled, and \fIscaleX\fR and \fIscaleY\fR give the
-x and y scale factors.
-The item should adjust its coordinates so that a point in the item
-that used to have coordinates \fIx\fR and \fIy\fR will have new
-coordinates \fIx\(fm\fR and \fIy\(fm\fR, where
-.PP
-.CS
-\fIx\(fm\fR = \fIoriginX\fR + \fIscaleX\fR \(mu (\fIx\fR \(mi \fIoriginX\fR)
-\fIy\(fm\fR = \fIoriginY\fR + \fIscaleY\fR \(mu (\fIy\fR \(mi \fIoriginY\fR)
-.CE
-.PP
-\fIscaleProc\fR must also update the bounding box in the item's
-header.
-.SS TRANSLATEPROC
-.PP
-\fItypePtr\->translateProc\fR is invoked by Tk to translate a canvas item
-during the \fBmove\fR widget command.
-The procedure must match the following prototype:
-.PP
-.CS
-typedef void \fBTk_ItemTranslateProc\fR(
-        Tk_Canvas \fIcanvas\fR,
-        Tk_Item *\fIitemPtr\fR,
-        double \fIdeltaX\fR,
-        double \fIdeltaY\fR);
-.CE
-.PP
-The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning,
-and \fIdeltaX\fR and \fIdeltaY\fR give the amounts that should be
-added to each x and y coordinate within the item.
-The type manager should adjust the item's coordinates and
-update the bounding box in the item's header.
-.SS INDEXPROC
-.PP
-\fItypePtr\->indexProc\fR is invoked by Tk to translate a string
-index specification into a numerical index, for example during the
-\fBindex\fR widget command.
-It is only relevant for item types that support indexable text or coordinates;
-\fItypePtr\->indexProc\fR may be specified as NULL for non-textual
-item types if they do not support detailed coordinate addressing.
-The procedure must match the following prototype:
-.PP
-.CS
-typedef int \fBTk_ItemIndexProc\fR(
-        Tcl_Interp *\fIinterp\fR,
-        Tk_Canvas \fIcanvas\fR,
-        Tk_Item *\fIitemPtr\fR,
-        Tcl_Obj *\fIindexObj\fR,
-        int *\fIindexPtr\fR);
-.CE
-.PP
-The \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR arguments all
-have the usual meaning.
-\fIindexObj\fR contains a textual description of an index,
-and \fIindexPtr\fR points to an integer value that should be
-filled in with a numerical index.
-Note that if \fBTK_CONFIG_OBJS\fR is not set in the
-\fItypePtr\->alwaysRedraw\fR field, the \fIindexObj\fR parameter will
-actually contain a pointer to a constant string.
-It is up to the type manager to decide what forms of index
-are supported (e.g., numbers, \fBinsert\fR, \fBsel.first\fR,
-\fBend\fR, etc.).
-\fIindexProc\fR should return a Tcl completion code and set
-the interpreter result in the event of an error.
-.SS ICURSORPROC
-.PP
-\fItypePtr\->icursorProc\fR is invoked by Tk during
-the \fBicursor\fR widget command to set the position of the
-insertion cursor in a textual item.
-It is only relevant for item types that support an insertion cursor;
-\fItypePtr\->icursorProc\fR may be specified as NULL for item types
-that do not support an insertion cursor.
-The procedure must match the following prototype:
-.PP
-.CS
-typedef void \fBTk_ItemCursorProc\fR(
-        Tk_Canvas \fIcanvas\fR,
-        Tk_Item *\fIitemPtr\fR,
-        int \fIindex\fR);
-.CE
-.PP
-\fIcanvas\fR and \fIitemPtr\fR have the usual meanings, and
-\fIindex\fR is an index into the item's text, as returned by a
-previous call to \fItypePtr\->insertProc\fR.
-The type manager should position the insertion cursor in the
-item just before the character given by \fIindex\fR.
-Whether or not to actually display the insertion cursor is
-determined by other information provided by \fBTk_CanvasGetTextInfo\fR.
-.SS SELECTIONPROC
-.PP
-\fItypePtr\->selectionProc\fR is invoked by Tk during selection
-retrievals; it must return part or all of the selected text in
-the item (if any).
-It is only relevant for item types that support text;
-\fItypePtr\->selectionProc\fR may be specified as NULL for non-textual
-item types.
-The procedure must match the following prototype:
-.PP
-.CS
-typedef int \fBTk_ItemSelectionProc\fR(
-        Tk_Canvas \fIcanvas\fR,
-        Tk_Item *\fIitemPtr\fR,
-        int \fIoffset\fR,
-        char *\fIbuffer\fR,
-        int \fImaxBytes\fR);
-.CE
-.PP
-\fIcanvas\fR and \fIitemPtr\fR have the usual meanings.
-\fIoffset\fR is an offset in bytes into the selection where 0 refers
-to the first byte of the selection; it identifies
-the first character that is to be returned in this call.
-\fIbuffer\fR points to an area of memory in which to store the
-requested bytes, and \fImaxBytes\fR specifies the maximum number
-of bytes to return.
-\fIselectionProc\fR should extract up to \fImaxBytes\fR characters
-from the selection and copy them to \fImaxBytes\fR; it should
-return a count of the number of bytes actually copied, which may
-be less than \fImaxBytes\fR if there are not \fIoffset+maxBytes\fR bytes
-in the selection.
-.SS INSERTPROC
-.PP
-\fItypePtr\->insertProc\fR is invoked by Tk during
-the \fBinsert\fR widget command to insert new text or coordinates into a
-canvas item.
-It is only relevant for item types that support the \fBinsert\fR method;
-\fItypePtr\->insertProc\fR may be specified as NULL for other
-item types.
-The procedure must match the following prototype:
-.PP
-.CS
-typedef void \fBTk_ItemInsertProc\fR(
-        Tk_Canvas \fIcanvas\fR,
-        Tk_Item *\fIitemPtr\fR,
-        int \fIindex\fR,
-        Tcl_Obj *\fIobj\fR);
-.CE
-.PP
-\fIcanvas\fR and \fIitemPtr\fR have the usual meanings.
-\fIindex\fR is an index into the item's text, as returned by a
-previous call to \fItypePtr\->insertProc\fR, and \fIobj\fR
-contains new text to insert just before the character given
-by \fIindex\fR.
-Note that if \fBTK_CONFIG_OBJS\fR is not set in the
-\fItypePtr\->alwaysRedraw\fR field, the \fIobj\fR parameter will
-actually contain a pointer to a constant string to be inserted.
-If the item supports modification of the coordinates list by this
-.PP
-The type manager should insert the text and recompute the bounding
-box in the item's header.
-.SS DCHARSPROC
-.PP
-\fItypePtr\->dCharsProc\fR is invoked by Tk during the \fBdchars\fR
-widget command to delete a range of text from a canvas item or a range of
-coordinates from a pathed item.
-It is only relevant for item types that support text;
-\fItypePtr\->dCharsProc\fR may be specified as NULL for non-textual
-item types that do not want to support coordinate deletion.
-The procedure must match the following prototype:
-.PP
-.CS
-typedef void \fBTk_ItemDCharsProc\fR(
-        Tk_Canvas \fIcanvas\fR,
-        Tk_Item *\fIitemPtr\fR,
-        int \fIfirst\fR,
-        int \fIlast\fR);
-.CE
-.PP
-\fIcanvas\fR and \fIitemPtr\fR have the usual meanings.
-\fIfirst\fR and \fIlast\fR give the indices of the first and last bytes
-to be deleted, as returned by previous calls to \fItypePtr\->indexProc\fR.
-The type manager should delete the specified characters and update
-the bounding box in the item's header.
-.SH "SEE ALSO"
-Tk_CanvasPsY, Tk_CanvasTextInfo, Tk_CanvasTkwin
-.SH KEYWORDS
-canvas, focus, item type, selection, type manager

doc/CrtMathFnc.3

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

doc/CrtObjCmd.3

@@ -0,0 +1,297 @@
+'\"
+'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
+'\"
+'\" 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_CreateObjCommand 3 8.0 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, Tcl_GetCommandInfo, Tcl_GetCommandInfoFromToken, Tcl_SetCommandInfo, Tcl_SetCommandInfoFromToken, Tcl_GetCommandName, Tcl_GetCommandFullName, Tcl_GetCommandFromObj \- implement new commands in C
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+Tcl_Command
+\fBTcl_CreateObjCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR)
+.sp
+int
+\fBTcl_DeleteCommand\fR(\fIinterp, cmdName\fR)
+.sp
+int
+\fBTcl_DeleteCommandFromToken\fR(\fIinterp, token\fR)
+.sp
+int
+\fBTcl_GetCommandInfo\fR(\fIinterp, cmdName, infoPtr\fR)
+.sp
+int
+\fBTcl_SetCommandInfo\fR(\fIinterp, cmdName, infoPtr\fR)
+.sp
+int
+\fBTcl_GetCommandInfoFromToken\fR(\fItoken, infoPtr\fR)
+.sp
+int
+\fBTcl_SetCommandInfoFromToken\fR(\fItoken, infoPtr\fR)
+.sp
+const char *
+\fBTcl_GetCommandName\fR(\fIinterp, token\fR)
+.sp
+void
+\fBTcl_GetCommandFullName\fR(\fIinterp, token, objPtr\fR)
+.sp
+Tcl_Command
+\fBTcl_GetCommandFromObj\fR(\fIinterp, objPtr\fR)
+.SH ARGUMENTS
+.AS Tcl_CmdDeleteProc *deleteProc in/out
+.AP Tcl_Interp *interp in
+Interpreter in which to create a new command or that contains a command.
+.AP char *cmdName in
+Name of command.
+.AP Tcl_ObjCmdProc *proc in
+Implementation of the new command: \fIproc\fR will be called whenever
+\fIcmdName\fR is invoked as a command.
+.AP ClientData clientData in
+Arbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR.
+.AP Tcl_CmdDeleteProc *deleteProc in
+Procedure to call before \fIcmdName\fR is deleted from the interpreter;
+allows for command-specific cleanup. If NULL, then no procedure is
+called before the command is deleted.
+.AP Tcl_Command token in
+Token for command, returned by previous call to \fBTcl_CreateObjCommand\fR.
+The command must not have been deleted.
+.AP Tcl_CmdInfo *infoPtr in/out
+Pointer to structure containing various information about a
+Tcl command.
+.AP Tcl_Obj *objPtr in
+Object containing the name of a Tcl command.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTcl_CreateObjCommand\fR defines a new command in \fIinterp\fR
+and associates it with procedure \fIproc\fR
+such that whenever \fIname\fR is
+invoked as a Tcl command (e.g., via a call to \fBTcl_EvalObjEx\fR)
+the Tcl interpreter will call \fIproc\fR to process the command.
+.PP
+\fBTcl_CreateObjCommand\fR deletes any existing command
+\fIname\fR already associated with the interpreter
+(however see below for an exception where the existing command
+is not deleted).
+It returns a token that may be used to refer
+to the command in subsequent calls to \fBTcl_GetCommandName\fR.
+If \fIname\fR contains any \fB::\fR namespace qualifiers,
+then the command is added to the specified namespace;
+otherwise the command is added to the global namespace.
+If \fBTcl_CreateObjCommand\fR is called for an interpreter that is in
+the process of being deleted, then it does not create a new command
+and it returns NULL.
+\fIproc\fR should have arguments and result that match the type
+\fBTcl_ObjCmdProc\fR:
+.CS
+typedef int Tcl_ObjCmdProc(
+        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
+\fBTcl_CreateObjCommand\fR.  Typically, \fIclientData\fR points to an
+application-specific data structure that describes what to do when the
+command procedure is invoked. \fIObjc\fR and \fIobjv\fR describe the
+arguments to the command, \fIobjc\fR giving the number of argument objects
+(including the command name) and \fIobjv\fR giving the values of the
+arguments.  The \fIobjv\fR array will contain \fIobjc\fR values, pointing to
+the argument objects.  Unlike \fIargv\fR[\fIargv\fR] used in a
+string-based command procedure, \fIobjv\fR[\fIobjc\fR] will not contain NULL.
+.PP
+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
+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
+\fBTcl_GetIntFromObj\fR on \fIobjv\fR[\fB2\fR] to obtain the integer
+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.
+.PP
+\fIproc\fR must return an integer code that is either \fBTCL_OK\fR,
+\fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR.
+See the Tcl overview man page
+for details on what these codes mean.  Most normal commands will only
+return \fBTCL_OK\fR or \fBTCL_ERROR\fR.
+In addition, if \fIproc\fR needs to return a non-empty result,
+it can call \fBTcl_SetObjResult\fR to set the interpreter's result.
+In the case of a \fBTCL_OK\fR return code this gives the result
+of the command,
+and in the case of \fBTCL_ERROR\fR this gives an error message.
+Before invoking a command procedure,
+\fBTcl_EvalObjEx\fR sets interpreter's result to
+point to an object representing an empty string, so simple
+commands can return an empty result by doing nothing at all.
+.PP
+The contents of the \fIobjv\fR array belong to Tcl and are not
+guaranteed to persist once \fIproc\fR returns: \fIproc\fR should
+not modify them.
+Call \fBTcl_SetObjResult\fR if you want
+to return something from the \fIobjv\fR array.
+.PP
+Ordinarily, \fBTcl_CreateObjCommand\fR deletes any existing command
+\fIname\fR already associated with the interpreter.
+However, if the existing command was created by a previous call to
+\fBTcl_CreateCommand\fR,
+\fBTcl_CreateObjCommand\fR does not delete the command
+but instead arranges for the Tcl interpreter to call the
+\fBTcl_ObjCmdProc\fR \fIproc\fR in the future.
+The old string-based \fBTcl_CmdProc\fR associated with the command
+is retained and its address can be obtained by subsequent 
+\fBTcl_GetCommandInfo\fR calls. This is done for backwards compatibility.
+.PP
+\fIDeleteProc\fR will be invoked when (if) \fIname\fR is deleted.
+This can occur through a call to \fBTcl_DeleteCommand\fR,
+\fBTcl_DeleteCommandFromToken\fR, or \fBTcl_DeleteInterp\fR,
+or by replacing \fIname\fR in another call to \fBTcl_CreateObjCommand\fR.
+\fIDeleteProc\fR is invoked before the command is deleted, and gives the
+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);
+.CE
+The \fIclientData\fR argument will be the same as the \fIclientData\fR
+argument passed to \fBTcl_CreateObjCommand\fR.
+.PP
+\fBTcl_DeleteCommand\fR deletes a command from a command interpreter.
+Once the call completes, attempts to invoke \fIcmdName\fR in
+\fIinterp\fR will result in errors.
+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
+a built-in command, an application-specific command, or a Tcl procedure.
+If \fIname\fR contains any \fB::\fR namespace qualifiers,
+the command is deleted from the specified namespace.
+.PP
+Given a token returned by \fBTcl_CreateObjCommand\fR,
+\fBTcl_DeleteCommandFromToken\fR deletes the command
+from a command interpreter.
+It will delete a command even if that command has been renamed.
+Once the call completes, attempts to invoke the command in
+\fIinterp\fR will result in errors.
+If the command corresponding to \fItoken\fR
+has already been deleted from \fIinterp\fR then
+\fBTcl_DeleteCommand\fR does nothing and returns -1;
+otherwise it returns 0.
+.PP
+\fBTcl_GetCommandInfo\fR checks to see whether its \fIcmdName\fR argument
+exists as a command in \fIinterp\fR.
+\fIcmdName\fR may include \fB::\fR namespace qualifiers
+to identify a command in a particular namespace.
+If the command is not found, then it returns 0.
+Otherwise it places information about the command
+in the \fBTcl_CmdInfo\fR structure
+pointed to by \fIinfoPtr\fR and returns 1.
+A \fBTcl_CmdInfo\fR structure has the following fields:
+.CS
+typedef struct Tcl_CmdInfo {
+    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
+if \fBTcl_CreateObjCommand\fR was called to register the command;
+it is 0 if only \fBTcl_CreateCommand\fR was called.
+It allows a program to determine whether it is faster to
+call \fIobjProc\fR or \fIproc\fR:
+\fIobjProc\fR is normally faster
+if \fIisNativeObjectProc\fR has the value 1.
+The fields \fIobjProc\fR and \fIobjClientData\fR
+have the same meaning as the \fIproc\fR and \fIclientData\fR
+arguments to \fBTcl_CreateObjCommand\fR;
+they hold information about the object-based command procedure
+that the Tcl interpreter calls to implement the command.
+The fields \fIproc\fR and \fIclientData\fR
+hold information about the string-based command procedure
+that implements the command.
+If \fBTcl_CreateCommand\fR was called for this command,
+this is the procedure passed to it;
+otherwise, this is a compatibility procedure
+registered by \fBTcl_CreateObjCommand\fR
+that simply calls the command's
+object-based procedure after converting its string arguments to Tcl objects.
+The field \fIdeleteData\fR is the ClientData value
+to pass to \fIdeleteProc\fR;  it is normally the same as
+\fIclientData\fR but may be set independently using the
+\fBTcl_SetCommandInfo\fR procedure.
+The field \fInamespacePtr\fR holds a pointer to the
+Tcl_Namespace that contains the command.
+.PP
+\fBTcl_GetCommandInfoFromToken\fR is identical to
+\fBTcl_GetCommandInfo\fR except that it uses a command token returned
+from \fBTcl_CreateObjCommand\fR in place of the command name.  If the
+\fItoken\fR parameter is NULL, it returns 0; otherwise, it returns 1
+and fills in the structure designated by \fIinfoPtr\fR.
+.PP
+\fBTcl_SetCommandInfo\fR is used to modify the procedures and
+ClientData values associated with a command.
+Its \fIcmdName\fR argument is the name of a command in \fIinterp\fR.
+\fIcmdName\fR may include \fB::\fR namespace qualifiers
+to identify a command in a particular namespace.
+If this command does not exist then \fBTcl_SetCommandInfo\fR returns 0.
+Otherwise, it copies the information from \fI*infoPtr\fR to
+Tcl's internal structure for the command and returns 1.
+.PP
+\fBTcl_SetCommandInfoFromToken\fR is identical to
+\fBTcl_SetCommandInfo\fR except that it takes a command token as
+returned by \fBTcl_CreateObjCommand\fR instead of the command name.
+If the \fItoken\fR parameter is NULL, it returns 0.  Otherwise, it
+copies the information from \fI*infoPtr\fR to Tcl's internal structure
+for the command and returns 1.
+.PP
+Note that \fBTcl_SetCommandInfo\fR and
+\fBTcl_SetCommandInfoFromToken\fR both allow the ClientData for a
+command's deletion procedure to be given a different value than the
+ClientData for its command procedure.
+.PP
+Note that neither \fBTcl_SetCommandInfo\fR nor
+\fBTcl_SetCommandInfoFromToken\fR will change a command's namespace.
+Use \fBTcl_Eval\fR to call the \fBrename\fR command to do that.
+.PP
+\fBTcl_GetCommandName\fR provides a mechanism for tracking commands
+that have been renamed.
+Given a token returned by \fBTcl_CreateObjCommand\fR
+when the command was created, \fBTcl_GetCommandName\fR returns the
+string name of the command.  If the command has been renamed since it
+was created, then \fBTcl_GetCommandName\fR returns the current name.
+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 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
+of a command from a command token.  
+The name, including all namespace prefixes,
+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\fR.
+The command name is resolved relative to the current namespace.
+Returns NULL if the command is not found.
+.SH "SEE ALSO"
+Tcl_CreateCommand, Tcl_ResetResult, Tcl_SetObjResult
+
+.SH KEYWORDS
+bind, command, create, delete, namespace, object

doc/CrtPhImgFmt.3

@@ -1,270 +0,0 @@
-'\"
-'\" Copyright (c) 1994 The Australian National University
-'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
-'\"
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-'\" Author: Paul Mackerras (paulus@cs.anu.edu.au),
-'\"	    Department of Computer Science,
-'\"	    Australian National University.
-'\"
-.TH Tk_CreatePhotoImageFormat 3 8.5 Tk "Tk Library Procedures"
-.so man.macros
-.BS
-.SH NAME
-Tk_CreatePhotoImageFormat \- define new file format for photo images
-.SH SYNOPSIS
-.nf
-\fB#include <tk.h>\fR
-.sp
-\fBTk_CreatePhotoImageFormat\fR(\fIformatPtr\fR)
-.SH ARGUMENTS
-.AS "const Tk_PhotoImageFormat" *formatPtr
-.AP "const Tk_PhotoImageFormat" *formatPtr in
-Structure that defines the new file format.
-.BE
-.SH DESCRIPTION
-.PP
-\fBTk_CreatePhotoImageFormat\fR is invoked to define a new file format
-for image data for use with photo images.  The code that implements an
-image file format is called an image file format handler, or
-handler for short.  The photo image code
-maintains a list of handlers that can be used to read and
-write data to or from a file.  Some handlers may also
-support reading image data from a string or converting image data to a
-string format.
-The user can specify which handler to use with the \fB\-format\fR
-image configuration option or the \fB\-format\fR option to the
-\fBread\fR and \fBwrite\fR photo image subcommands.
-.PP
-An image file format handler consists of a collection of procedures
-plus a Tk_PhotoImageFormat structure, which contains the name of the
-image file format and pointers to six procedures provided by the
-handler to deal with files and strings in this format.  The
-Tk_PhotoImageFormat structure contains the following fields:
-.CS
-typedef struct Tk_PhotoImageFormat {
-    const char *\fIname\fR;
-    Tk_ImageFileMatchProc *\fIfileMatchProc\fR;
-    Tk_ImageStringMatchProc *\fIstringMatchProc\fR;
-    Tk_ImageFileReadProc *\fIfileReadProc\fR;
-    Tk_ImageStringReadProc *\fIstringReadProc\fR;
-    Tk_ImageFileWriteProc *\fIfileWriteProc\fR;
-    Tk_ImageStringWriteProc *\fIstringWriteProc\fR;
-} \fBTk_PhotoImageFormat\fR;
-.CE
-.PP
-The handler need not provide implementations of all six procedures.
-For example, the procedures that handle string data would not be
-provided for a format in which the image data are stored in binary,
-and could therefore contain null characters.  If any procedure is not
-implemented, the corresponding pointer in the Tk_PhotoImageFormat
-structure should be set to NULL.  The handler must provide the
-\fIfileMatchProc\fR procedure if it provides the \fIfileReadProc\fR
-procedure, and the \fIstringMatchProc\fR procedure if it provides the
-\fIstringReadProc\fR procedure.
-.SS NAME
-.PP
-\fIformatPtr->name\fR provides a name for the image type.
-Once \fBTk_CreatePhotoImageFormat\fR returns, this name may be used
-in the \fB\-format\fR photo image configuration and subcommand option.
-The manual page for the photo image (photo(n)) describes how image
-file formats are chosen based on their names and the value given to
-the \fB\-format\fR option. The first character of \fIformatPtr->name\fR
-must not be an uppercase character from the ASCII character set
-(that is, one of the characters \fBA\fR-\fBZ\fR).  Such names are used
-only for legacy interface support (see below).
-.SS FILEMATCHPROC
-.PP
-\fIformatPtr->fileMatchProc\fR provides the address of a procedure for
-Tk to call when it is searching for an image file format handler
-suitable for reading data in a given file.
-\fIformatPtr->fileMatchProc\fR must match the following prototype:
-.CS
-typedef int \fBTk_ImageFileMatchProc\fR(
-        Tcl_Channel \fIchan\fR,
-        const char *\fIfileName\fR,
-        Tcl_Obj *\fIformat\fR,
-        int *\fIwidthPtr\fR,
-        int *\fIheightPtr\fR,
-        Tcl_Interp *\fIinterp\fR);
-.CE
-The \fIfileName\fR argument is the name of the file containing the
-image data, which is open for reading as \fIchan\fR.  The
-\fIformat\fR argument contains the value given for the
-\fB\-format\fR option, or NULL if the option was not specified.
-If the data in the file appears to be in the format supported by this
-handler, the \fIformatPtr->fileMatchProc\fR procedure should store the
-width and height of the image in *\fIwidthPtr\fR and *\fIheightPtr\fR
-respectively, and return 1.  Otherwise it should return 0.
-.SS STRINGMATCHPROC
-.PP
-\fIformatPtr->stringMatchProc\fR provides the address of a procedure for
-Tk to call when it is searching for an image file format handler for
-suitable for reading data from a given string.
-\fIformatPtr->stringMatchProc\fR must match the following prototype:
-.CS
-typedef int \fBTk_ImageStringMatchProc\fR(
-        Tcl_Obj *\fIdata\fR,
-        Tcl_Obj *\fIformat\fR,
-        int *\fIwidthPtr\fR,
-        int *\fIheightPtr\fR,
-        Tcl_Interp *\fIinterp\fR);
-.CE
-The \fIdata\fR argument points to the object containing the image
-data.  The \fIformat\fR argument contains the value given for
-the \fB\-format\fR option, or NULL if the option was not specified.
-If the data in the string appears to be in the format supported by
-this handler, the \fIformatPtr->stringMatchProc\fR procedure should
-store the width and height of the image in *\fIwidthPtr\fR and
-*\fIheightPtr\fR respectively, and return 1.  Otherwise it should
-return 0.
-.SS FILEREADPROC
-.PP
-\fIformatPtr->fileReadProc\fR provides the address of a procedure for
-Tk to call to read data from an image file into a photo image.
-\fIformatPtr->fileReadProc\fR must match the following prototype:
-.CS
-typedef int \fBTk_ImageFileReadProc\fR(
-        Tcl_Interp *\fIinterp\fR,
-        Tcl_Channel \fIchan\fR,
-        const char *\fIfileName\fR,
-        Tcl_Obj *\fIformat\fR,
-        PhotoHandle \fIimageHandle\fR,
-        int \fIdestX\fR, int \fIdestY\fR,
-        int \fIwidth\fR, int \fIheight\fR,
-        int \fIsrcX\fR, int \fIsrcY\fR);
-.CE
-The \fIinterp\fR argument is the interpreter in which the command was
-invoked to read the image; it should be used for reporting errors.
-The image data is in the file named \fIfileName\fR, which is open for
-reading as \fIchan\fR.  The \fIformat\fR argument contains the
-value given for the \fB\-format\fR option, or NULL if the option was
-not specified.  The image data in the file, or a subimage of it, is to
-be read into the photo image identified by the handle
-\fIimageHandle\fR.  The subimage of the data in the file is of
-dimensions \fIwidth\fR x \fIheight\fR and has its top-left corner at
-coordinates (\fIsrcX\fR,\fIsrcY\fR).  It is to be stored in the photo
-image with its top-left corner at coordinates
-(\fIdestX\fR,\fIdestY\fR) using the \fBTk_PhotoPutBlock\fR procedure.
-The return value is a standard Tcl return value.
-.SS STRINGREADPROC
-.PP
-\fIformatPtr->stringReadProc\fR provides the address of a procedure for
-Tk to call to read data from a string into a photo image.
-\fIformatPtr->stringReadProc\fR must match the following prototype:
-.CS
-typedef int \fBTk_ImageStringReadProc\fR(
-        Tcl_Interp *\fIinterp\fR,
-        Tcl_Obj *\fIdata\fR,
-        Tcl_Obj *\fIformat\fR,
-        PhotoHandle \fIimageHandle\fR,
-        int \fIdestX\fR, int \fIdestY\fR,
-        int \fIwidth\fR, int \fIheight\fR,
-        int \fIsrcX\fR, int \fIsrcY\fR);
-.CE
-The \fIinterp\fR argument is the interpreter in which the command was
-invoked to read the image; it should be used for reporting errors.
-The \fIdata\fR argument points to the image data in object form.
-The \fIformat\fR argument contains the
-value given for the \fB\-format\fR option, or NULL if the option was
-not specified.  The image data in the string, or a subimage of it, is to
-be read into the photo image identified by the handle
-\fIimageHandle\fR.  The subimage of the data in the string is of
-dimensions \fIwidth\fR x \fIheight\fR and has its top-left corner at
-coordinates (\fIsrcX\fR,\fIsrcY\fR).  It is to be stored in the photo
-image with its top-left corner at coordinates
-(\fIdestX\fR,\fIdestY\fR) using the \fBTk_PhotoPutBlock\fR procedure.
-The return value is a standard Tcl return value.
-.SS FILEWRITEPROC
-.PP
-\fIformatPtr->fileWriteProc\fR provides the address of a procedure for
-Tk to call to write data from a photo image to a file.
-\fIformatPtr->fileWriteProc\fR must match the following prototype:
-.CS
-typedef int \fBTk_ImageFileWriteProc\fR(
-        Tcl_Interp *\fIinterp\fR,
-        const char *\fIfileName\fR,
-        Tcl_Obj *\fIformat\fR,
-        Tk_PhotoImageBlock *\fIblockPtr\fR);
-.CE
-The \fIinterp\fR argument is the interpreter in which the command was
-invoked to write the image; it should be used for reporting errors.
-The image data to be written are in memory and are described by the
-Tk_PhotoImageBlock structure pointed to by \fIblockPtr\fR; see the
-manual page FindPhoto(3) for details.  The \fIfileName\fR argument
-points to the string giving the name of the file in which to write the
-image data.  The \fIformat\fR argument contains the
-value given for the \fB\-format\fR option, or NULL if the option was
-not specified.  The format string can contain extra characters
-after the name of the format.  If appropriate, the
-\fIformatPtr->fileWriteProc\fR procedure may interpret these
-characters to specify further details about the image file.
-The return value is a standard Tcl return value.
-.SS STRINGWRITEPROC
-.PP
-\fIformatPtr->stringWriteProc\fR provides the address of a procedure for
-Tk to call to translate image data from a photo image into a string.
-\fIformatPtr->stringWriteProc\fR must match the following prototype:
-.CS
-typedef int \fBTk_ImageStringWriteProc\fR(
-        Tcl_Interp *\fIinterp\fR,
-        Tcl_Obj *\fIformat\fR,
-        Tk_PhotoImageBlock *\fIblockPtr\fR);
-.CE
-The \fIinterp\fR argument is the interpreter in which the command was
-invoked to convert the image; it should be used for reporting errors.
-The image data to be converted are in memory and are described by the
-Tk_PhotoImageBlock structure pointed to by \fIblockPtr\fR; see the
-manual page FindPhoto(3) for details.  The data for the string
-should be put in the interpreter \fIinterp\fR result.
-The \fIformat\fR argument contains the
-value given for the \fB\-format\fR option, or NULL if the option was
-not specified.  The format string can contain extra characters
-after the name of the format.  If appropriate, the
-\fIformatPtr->stringWriteProc\fR procedure may interpret these
-characters to specify further details about the image file.
-The return value is a standard Tcl return value.
-.SH "LEGACY INTERFACE SUPPORT"
-.PP
-In Tk 8.2 and earlier, the definition of all the function pointer
-types stored in fields of a \fBTk_PhotoImageFormat\fR struct were
-incompatibly different.  Legacy programs and libraries dating from
-those days may still contain code that defines extended Tk photo image
-formats using the old interface.  The Tk header file will still support
-this legacy interface if the code is compiled with the
-macro \fBUSE_OLD_IMAGE\fR defined.  Alternatively, the legacy interfaces
-are used if the first character of \fIformatPtr->name\fR is an
-uppercase ASCII character (\fBA\fR-\fBZ\fR), and explicit casts
-are used to forgive the type mismatch.  For example,
-.CS
-static Tk_PhotoImageFormat myFormat = {
-    "MyFormat",
-    (Tk_ImageFileMatchProc *) FileMatch,
-    NULL,
-    (Tk_ImageFileReadProc *) FileRead,
-    NULL,
-    NULL,
-    NULL
-};
-.CE
-would define a minimal \fBTk_PhotoImageFormat\fR that operates provide
-only file reading capability, where \fBFileMatch\fR and \fBFileRead\fR
-are written according to the legacy interfaces of Tk 8.2 or earlier.
-.PP
-Any stub-enabled extension providing an extended photo image format
-via the legacy interface enabled by the \fBUSE_OLD_IMAGE\fR macro
-that is compiled against Tk 8.5 headers and linked against the
-Tk 8.5 stub library will produce a file that can be loaded only
-into interps with Tk 8.5 or later; that is, the normal stub-compatibility
-rules.  If a developer needs to generate from such code a file
-that is loadable into interps with Tk 8.4 or earlier, they must
-use Tk 8.4 headers and stub libraries to do so.
-.PP
-Any new code written today should not make use of the legacy
-interfaces.  Expect their support to go away in Tk 9.
-.SH "SEE ALSO"
-Tk_FindPhoto, Tk_PhotoPutBlock
-.SH KEYWORDS
-photo image, image file

doc/CrtSelHdlr.3

@@ -1,116 +0,0 @@
-'\"
-'\" Copyright (c) 1990-1994 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\"
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\"
-.TH Tk_CreateSelHandler 3 4.0 Tk "Tk Library Procedures"
-.so man.macros
-.BS
-.SH NAME
-Tk_CreateSelHandler, Tk_DeleteSelHandler \- arrange to handle requests for a selection
-.SH SYNOPSIS
-.nf
-\fB#include <tk.h>\fR
-.sp
-\fBTk_CreateSelHandler\fR(\fItkwin, selection, target, proc, clientData, format\fR)
-.sp
-\fBTk_DeleteSelHandler\fR(\fItkwin, selection, target\fR)
-.SH ARGUMENTS
-.AS Tk_SelectionProc clientData
-.AP Tk_Window tkwin in
-Window for which \fIproc\fR will provide selection information.
-.AP Atom selection in
-The name of the selection for which \fIproc\fR will provide
-selection information.
-.AP Atom target in
-Form in which \fIproc\fR can provide the selection (e.g. STRING
-or FILE_NAME).  Corresponds to \fItype\fR arguments in \fBselection\fR
-commands.
-.AP Tk_SelectionProc *proc in
-Procedure to invoke whenever the selection is owned by \fItkwin\fR
-and the selection contents are requested in the format given by
-\fItarget\fR.
-.AP ClientData clientData in
-Arbitrary one-word value to pass to \fIproc\fR.
-.AP Atom format in
-If the selection requestor is not in this process, \fIformat\fR determines
-the representation used to transmit the selection to its
-requestor.
-.BE
-.SH DESCRIPTION
-.PP
-\fBTk_CreateSelHandler\fR arranges for a particular procedure
-(\fIproc\fR) to be called whenever \fIselection\fR is owned by
-\fItkwin\fR and the selection contents are requested in the
-form given by \fItarget\fR.
-\fITarget\fR should be one of
-the entries defined in the left column of Table 2 of the
-X Inter-Client Communication Conventions Manual (ICCCM) or
-any other form in which an application is willing to present
-the selection.  The most common form is STRING.
-.PP
-\fIProc\fR should have arguments and result that match the
-type \fBTk_SelectionProc\fR:
-.CS
-typedef int \fBTk_SelectionProc\fR(
-        ClientData \fIclientData\fR,
-        int \fIoffset\fR,
-        char *\fIbuffer\fR,
-        int \fImaxBytes\fR);
-.CE
-The \fIclientData\fR parameter to \fIproc\fR is a copy of the
-\fIclientData\fR argument given to \fBTk_CreateSelHandler\fR.
-Typically, \fIclientData\fR points to a data
-structure containing application-specific information that is
-needed to retrieve the selection.  \fIOffset\fR specifies an
-offset position into the selection, \fIbuffer\fR specifies a
-location at which to copy information about the selection, and
-\fImaxBytes\fR specifies the amount of space available at
-\fIbuffer\fR.  \fIProc\fR should place a NULL-terminated string
-at \fIbuffer\fR containing \fImaxBytes\fR or fewer characters
-(not including the terminating NULL), and it should return a
-count of the number of non-NULL characters stored at
-\fIbuffer\fR.  If the selection no longer exists (e.g. it once
-existed but the user deleted the range of characters containing
-it), then \fIproc\fR should return \-1.
-.PP
-When transferring large selections, Tk will break them up into
-smaller pieces (typically a few thousand bytes each) for more
-efficient transmission.  It will do this by calling \fIproc\fR
-one or more times, using successively higher values of \fIoffset\fR
-to retrieve successive portions of the selection.  If \fIproc\fR
-returns a count less than \fImaxBytes\fR it means that the entire
-remainder of the selection has been returned.  If \fIproc\fR's return
-value is \fImaxBytes\fR it means there may be additional information
-in the selection, so Tk must make another call to \fIproc\fR to
-retrieve the next portion.
-.PP
-\fIProc\fR always returns selection information in the form of a
-character string.  However, the ICCCM allows for information to
-be transmitted from the selection owner to the selection requestor
-in any of several formats, such as a string, an array of atoms, an
-array of integers, etc.  The \fIformat\fR argument to
-\fBTk_CreateSelHandler\fR indicates what format should be used to
-transmit the selection to its requestor (see the middle column of
-Table 2 of the ICCCM for examples).  If \fIformat\fR is not
-STRING, then Tk will take the value returned by \fIproc\fR and divided
-it into fields separated by white space.  If \fIformat\fR is ATOM,
-then Tk will return the selection as an array of atoms, with each
-field in \fIproc\fR's result treated as the name of one atom.  For
-any other value of \fIformat\fR, Tk will return the selection as an
-array of 32-bit values where each field of \fIproc\fR's result is
-treated as a number and translated to a 32-bit value.  In any event,
-the \fIformat\fR atom is returned to the selection requestor along
-with the contents of the selection.
-.PP
-If \fBTk_CreateSelHandler\fR is called when there already exists a
-handler for \fIselection\fR and \fItarget\fR on \fItkwin\fR, then the
-existing handler is replaced with a new one.
-.PP
-\fBTk_DeleteSelHandler\fR removes the handler given by \fItkwin\fR,
-\fIselection\fR, and \fItarget\fR, if such a handler exists.
-If there is no such handler then it has no effect.
-.SH KEYWORDS
-format, handler, selection, target

doc/CrtSlave.3

@@ -0,0 +1,236 @@
+'\"
+'\" 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.
+'\" 
+.so man.macros
+.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
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+int
+\fBTcl_IsSafe\fR(\fIinterp\fR)
+.sp
+int
+\fBTcl_MakeSafe\fR(\fIinterp\fR)
+.sp
+Tcl_Interp *
+\fBTcl_CreateSlave\fR(\fIinterp, slaveName, isSafe\fR)
+.sp
+Tcl_Interp *
+\fBTcl_GetSlave\fR(\fIinterp, slaveName\fR)
+.sp
+Tcl_Interp *
+\fBTcl_GetMaster\fR(\fIinterp\fR)
+.sp
+int
+\fBTcl_GetInterpPath\fR(\fIaskingInterp, slaveInterp\fR)
+.sp
+int
+\fBTcl_CreateAlias\fR(\fIslaveInterp, slaveCmd, targetInterp, targetCmd,
+                argc, argv\fR)
+.sp
+int
+\fBTcl_CreateAliasObj\fR(\fIslaveInterp, slaveCmd, targetInterp, targetCmd,
+                   objc, objv\fR)
+.sp
+int
+\fBTcl_GetAlias\fR(\fIinterp, slaveCmd, targetInterpPtr, targetCmdPtr,
+             argcPtr, argvPtr\fR)
+.sp
+int
+\fBTcl_GetAliasObj\fR(\fIinterp, slaveCmd, targetInterpPtr, targetCmdPtr,
+                objcPtr, objvPtr\fR)
+.sp
+int
+\fBTcl_ExposeCommand\fR(\fIinterp, hiddenCmdName, cmdName\fR)
+.sp
+int
+\fBTcl_HideCommand\fR(\fIinterp, cmdName, hiddenCmdName\fR)
+.SH ARGUMENTS
+.AS "const char *const" **targetInterpPtr out
+.AP Tcl_Interp *interp in
+Interpreter in which to execute the specified command.
+.AP "const char" *slaveName in
+Name of slave interpreter to create or manipulate.
+.AP int isSafe in
+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
+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
+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
+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_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
+Pointer to location to store the address of the name of the target command
+for an alias.
+.AP int *argcPtr out
+Pointer to location to store count of additional arguments to be passed to
+the alias. The location is in storage owned by the caller.
+.AP "const char" ***argvPtr out
+Pointer to location to store a vector of strings, the additional arguments
+to pass to an alias. The location is in storage owned by the caller, the
+vector of strings is owned by the called function.
+.AP int *objcPtr out
+Pointer to location to store count of additional object arguments to be
+passed to the alias. The location is in storage owned by the caller.
+.AP Tcl_Obj ***objvPtr out
+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.
+.AP "const char" *cmdName in
+Name of an exposed command to hide or create.
+.AP "const char" *hiddenCmdName in
+Name under which a hidden command is stored and with which it can be
+exposed or invoked.
+.BE
+
+.SH DESCRIPTION
+.PP
+These procedures are intended for access to the multiple interpreter
+facility from inside C programs. They enable managing multiple interpreters
+in a hierarchical relationship, and the management of aliases, commands
+that when invoked in one interpreter execute a command in another
+interpreter. The return value for those procedures that return an \fBint\fR
+is either \fBTCL_OK\fR or \fBTCL_ERROR\fR. If \fBTCL_ERROR\fR is returned
+then the \fBresult\fR field of the interpreter contains an error message.
+.PP
+\fBTcl_CreateSlave\fR creates a new interpreter as a slave of \fIinterp\fR.
+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
+.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
+.QW safe
+(was created with the \fBTCL_SAFE_INTERPRETER\fR flag specified),
+\fB0\fR otherwise.
+.PP
+\fBTcl_MakeSafe\fR marks \fIinterp\fR as
+.QW safe ,
+so that future
+calls to \fBTcl_IsSafe\fR will return 1.  It also removes all known
+potentially-unsafe core functionality (both commands and variables)
+from \fIinterp\fR.  However, it cannot know what parts of an extension
+or application are safe and does not make any attempt to remove those
+parts, so safety is not guaranteed after calling \fBTcl_MakeSafe\fR.
+Callers will want to take care with their use of \fBTcl_MakeSafe\fR
+to avoid false claims of safety.  For many situations, \fBTcl_CreateSlave\fR
+may be a better choice, since it creates interpreters in a known-safe state.
+.PP
+\fBTcl_GetSlave\fR returns a pointer to a slave interpreter of
+\fIinterp\fR. The slave interpreter is identified by \fIslaveName\fR.
+If no such slave interpreter exists, \fBNULL\fR is returned.
+.PP
+\fBTcl_GetMaster\fR returns a pointer to the master interpreter of
+\fIinterp\fR. If \fIinterp\fR has no master (it is a
+top-level interpreter) then \fBNULL\fR is returned.
+.PP
+\fBTcl_GetInterpPath\fR sets the \fIresult\fR field in \fIaskingInterp\fR
+to the relative path between \fIaskingInterp\fR and \fIslaveInterp\fR;
+\fIslaveInterp\fR must be a slave of \fIaskingInterp\fR. If the computation
+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
+\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
+contained in \fIargv\fR are always prepended to any arguments supplied in the
+invocation of \fIslaveCmd\fR and passed to \fItargetCmd\fR.
+This operation returns \fBTCL_OK\fR if it succeeds, or \fBTCL_ERROR\fR if
+it fails; in that case, an error message is left in the object result
+of \fIslaveInterp\fR.
+Note that there are no restrictions on the ancestry relationship (as
+created by \fBTcl_CreateSlave\fR) between \fIslaveInterp\fR and
+\fItargetInterp\fR. Any two interpreters can be used, without any
+restrictions on how they are related.
+.PP
+\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.
+.PP
+\fBTcl_GetAlias\fR returns information about an alias \fIaliasName\fR
+in \fIinterp\fR. Any of the result fields can be \fBNULL\fR, in
+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.
+.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
+strings.
+.PP
+\fBTcl_ExposeCommand\fR moves the command named \fIhiddenCmdName\fR from
+the set of hidden commands to the set of exposed commands, putting
+it under the name
+\fIcmdName\fR. 
+\fIHiddenCmdName\fR must be the name of an existing hidden
+command, or the operation will return \fBTCL_ERROR\fR and leave an error
+message in the \fIresult\fR field in \fIinterp\fR.
+If an exposed command named \fIcmdName\fR already exists,
+the operation returns \fBTCL_ERROR\fR and leaves an error message in the
+object result of \fIinterp\fR.
+If the operation succeeds, it returns \fBTCL_OK\fR.
+After executing this command, attempts to use \fIcmdName\fR in a call to
+\fBTcl_Eval\fR or with the Tcl \fBeval\fR command will again succeed.
+.PP
+\fBTcl_HideCommand\fR moves the command named \fIcmdName\fR from the set of
+exposed commands to the set of hidden commands, under the name
+\fIhiddenCmdName\fR.
+\fICmdName\fR must be the name of an existing exposed
+command, or the operation will return \fBTCL_ERROR\fR and leave an error
+message in the object result of \fIinterp\fR.
+Currently both \fIcmdName\fR and \fIhiddenCmdName\fR must not contain
+namespace qualifiers, or the operation will return \fBTCL_ERROR\fR and
+leave an error message in the object result of \fIinterp\fR.
+The \fICmdName\fR will be looked up in the global namespace, and not
+relative to the current namespace, even if the current namespace is not the
+global one.
+If a hidden command whose name is \fIhiddenCmdName\fR already
+exists, the operation also returns \fBTCL_ERROR\fR and the \fIresult\fR
+field in \fIinterp\fR contains an error message.
+If the operation succeeds, it returns \fBTCL_OK\fR.
+After executing this command, attempts to use \fIcmdName\fR in a call to
+\fBTcl_Eval\fR or with the Tcl \fBeval\fR command will fail.
+.PP
+For a description of the Tcl interface to multiple interpreters, see
+\fIinterp(n)\fR.
+.SH "SEE ALSO"
+interp
+
+.SH KEYWORDS
+alias, command, exposed commands, hidden commands, interpreter, invoke,
+master, slave

doc/CrtTimerHdlr.3

@@ -0,0 +1,73 @@
+'\"
+'\" Copyright (c) 1990 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.
+'\" 
+.so man.macros
+.TH Tcl_CreateTimerHandler 3 7.5 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_CreateTimerHandler, Tcl_DeleteTimerHandler \- call a procedure at a given time
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+Tcl_TimerToken
+\fBTcl_CreateTimerHandler\fR(\fImilliseconds, proc, clientData\fR)
+.sp
+\fBTcl_DeleteTimerHandler\fR(\fItoken\fR)
+.SH ARGUMENTS
+.AS Tcl_TimerToken milliseconds
+.AP int milliseconds  in
+How many milliseconds to wait before invoking \fIproc\fR.
+.AP Tcl_TimerProc *proc in
+Procedure to invoke after \fImilliseconds\fR have elapsed.
+.AP ClientData clientData in
+Arbitrary one-word value to pass to \fIproc\fR.
+.AP Tcl_TimerToken token in
+Token for previously created timer handler (the return value
+from some previous call to \fBTcl_CreateTimerHandler\fR).
+.BE
+
+.SH DESCRIPTION
+.PP
+\fBTcl_CreateTimerHandler\fR arranges for \fIproc\fR to be
+invoked at a time \fImilliseconds\fR milliseconds in the
+future.
+The callback to \fIproc\fR will be made by \fBTcl_DoOneEvent\fR,
+so \fBTcl_CreateTimerHandler\fR is only useful in programs that
+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 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.
+.PP
+\fIProc\fR should have arguments and return value that match
+the type \fBTcl_TimerProc\fR:
+.CS
+typedef void Tcl_TimerProc(ClientData \fIclientData\fR);
+.CE
+The \fIclientData\fR parameter to \fIproc\fR is a
+copy of the \fIclientData\fR argument given to
+\fBTcl_CreateTimerHandler\fR when the callback
+was created.  Typically, \fIclientData\fR points to a data
+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
+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
+has been invoked then \fBTcl_DeleteTimerHandler\fR does nothing.
+The tokens returned by \fBTcl_CreateTimerHandler\fR never have
+a value of NULL, so if NULL is passed to \fBTcl_DeleteTimerHandler\fR
+then the procedure does nothing.
+
+.SH KEYWORDS
+callback, clock, handler, timer

doc/CrtTrace.3

@@ -0,0 +1,185 @@
+'\"
+'\" 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 <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.
+'\" 
+.so man.macros
+.TH Tcl_CreateTrace 3 "" Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_CreateTrace, Tcl_CreateObjTrace, Tcl_DeleteTrace \- arrange for command execution to be traced
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+Tcl_Trace
+\fBTcl_CreateTrace\fR(\fIinterp, level, proc, clientData\fR)
+.sp
+Tcl_Trace
+\fBTcl_CreateObjTrace\fR(\fIinterp, level, flags, objProc, clientData, deleteProc\fR)
+.sp
+\fBTcl_DeleteTrace\fR(\fIinterp, trace\fR)
+.SH ARGUMENTS
+.AS Tcl_CmdObjTraceDeleteProc *deleteProc
+.AP Tcl_Interp *interp in
+Interpreter containing command to be traced or untraced.
+.AP int level in
+Only commands at or below this nesting level will be traced unless
+0 is specified.  1 means
+top-level commands only, 2 means top-level commands or those that are
+invoked as immediate consequences of executing top-level commands
+(procedure bodies, bracketed commands, etc.) and so on.
+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 is executed.  See below for
+details of the calling sequence.
+.AP Tcl_CmdTraceProc *proc in
+Procedure to call for each command that is executed.  See below for
+details on the calling sequence.
+.AP ClientData clientData in
+Arbitrary one-word value to pass to \fIobjProc\fR or \fIproc\fR.
+.AP 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.
+.AP Tcl_Trace trace in
+Token for trace to be removed (return value from previous call
+to \fBTcl_CreateTrace\fR).
+.BE
+.SH DESCRIPTION
+.PP
+\fBTcl_CreateObjTrace\fR arranges for command tracing.  After it is
+called, \fIobjProc\fR will be invoked before the Tcl interpreter calls
+any command procedure when evaluating commands in \fIinterp\fR.
+The return value from \fBTcl_CreateObjTrace\fR is a token for the trace,
+which may be passed to \fBTcl_DeleteTrace\fR to remove the trace.
+There may be many traces in effect simultaneously for the same
+interpreter.
+.PP
+\fIobjProc\fR should have arguments and result that match the type,
+\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[] );
+.CE
+The \fIclientData\fR and \fIinterp\fR parameters are copies of the
+corresponding arguments given to \fBTcl_CreateTrace\fR.
+\fIClientData\fR typically points to an application-specific data
+structure that describes what to do when \fIobjProc\fR is invoked.  The
+\fIlevel\fR parameter gives the nesting level of the command (1 for
+top-level commands passed to \fBTcl_Eval\fR by the application, 2 for
+the next-level commands passed to \fBTcl_Eval\fR as part of parsing or
+interpreting level-1 commands, and so on). The \fIcommand\fR parameter
+points to a string containing the text of the command, before any
+argument substitution.  The \fIcommandToken\fR parameter is a Tcl
+command token that identifies the command to be invoked.  The token
+may be passed to \fBTcl_GetCommandName\fR,
+\fBTcl_GetCommandInfoFromToken\fR, or \fBTcl_SetCommandInfoFromToken\fR to
+manipulate the definition of the command. The \fIobjc\fR and \fIobjv\fR
+parameters designate the final parameter count and parameter vector
+that will be passed to the command, and have had all substitutions
+performed.
+.PP
+The \fIobjProc\fR callback is expected to return a standard Tcl status
+return code.  If this code is \fBTCL_OK\fR (the normal case), then
+the Tcl interpreter will invoke the command.  Any other return code
+is treated as if the command returned that status, and the command is
+\fInot\fR invoked.
+.PP
+The \fIobjProc\fR callback must not modify \fIobjv\fR in any way.  It
+is, however, permissible to change the command by calling
+\fBTcl_SetCommandTokenInfo\fR prior to returning.  Any such change
+takes effect immediately, and the command is invoked with the new
+information.
+.PP
+Tracing will only occur for commands at nesting level less than
+or equal to the \fIlevel\fR parameter (i.e. the \fIlevel\fR
+parameter to \fIobjProc\fR will always be less than or equal to the
+\fIlevel\fR parameter to \fBTcl_CreateTrace\fR).
+.PP
+Tracing has a significant effect on runtime performance because it
+causes the bytecode compiler to refrain from generating in-line code
+for Tcl commands such as \fBif\fR and \fBwhile\fR in order that they
+may be traced.  If traces for the built-in commands are not required,
+the \fIflags\fR parameter may be set to the constant value
+\fBTCL_ALLOW_INLINE_COMPILATION\fR.  In this case, traces on built-in
+commands may or may not result in trace callbacks, depending on the
+state of the interpreter, but run-time performance will be improved
+significantly.  (This functionality is desirable, for example, when
+using \fBTcl_CreateObjTrace\fR to implement an execution time
+profiler.)
+.PP
+Calls to \fIobjProc\fR will be made by the Tcl parser immediately before
+it calls the command procedure for the command (\fIcmdProc\fR).  This
+occurs after argument parsing and substitution, so tracing for
+substituted commands occurs before tracing of the commands
+containing the substitutions.  If there is a syntax error in a
+command, or if there is no command procedure associated with a
+command name, then no tracing will occur for that command.  If a
+string passed to Tcl_Eval contains multiple commands (bracketed, or
+on different lines) then multiple calls to \fIobjProc\fR will occur,
+one for each command.
+.PP
+\fBTcl_DeleteTrace\fR removes a trace, so that no future calls will be
+made to the procedure associated with the trace.  After \fBTcl_DeleteTrace\fR
+returns, the caller should never again use the \fItrace\fR token.
+.PP
+When \fBTcl_DeleteTrace\fR is called, the interpreter invokes the
+\fIdeleteProc\fR that was passed as a parameter to
+\fBTcl_CreateObjTrace\fR.  The \fIdeleteProc\fR must match the type,
+\fBTcl_CmdObjTraceDeleteProc\fR:
+.CS
+typedef void \fBTcl_CmdObjTraceDeleteProc\fR( 
+        \fBClientData\fR \fIclientData\fR);
+.CE
+The \fIclientData\fR parameter will be the same as the
+\fIclientData\fR parameter that was originally passed to
+\fBTcl_CreateObjTrace\fR.
+.PP
+\fBTcl_CreateTrace\fR is an alternative interface for command tracing,
+\fInot recommended for new applications\fR.  It is provided for backward
+compatibility with code that was developed for older versions of the
+Tcl interpreter.  It is similar to \fBTcl_CreateObjTrace\fR, except
+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[]);
+.CE
+The parameters to the \fIproc\fR callback are similar to those of the
+\fIobjProc\fR callback above. The \fIcommandToken\fR is
+replaced with \fIcmdProc\fR, a pointer to the (string-based) command
+procedure that will be invoked; and \fIcmdClientData\fR, the client
+data that will be passed to the procedure.  The \fIobjc\fR parameter
+is replaced with an \fIargv\fR parameter, that gives the arguments to
+the command as character strings.
+\fIProc\fR must not modify the \fIcommand\fR or \fIargv\fR strings.
+.PP
+If a trace created with \fBTcl_CreateTrace\fR is in effect, inline
+compilation of Tcl commands such as \fBif\fR and \fBwhile\fR is always
+disabled.  There is no notification when a trace created with
+\fBTcl_CreateTrace\fR is deleted.
+There is no way to be notified when the trace created by
+\fBTcl_CreateTrace\fR is deleted.  There is no way for the \fIproc\fR
+associated with a call to \fBTcl_CreateTrace\fR to abort execution of
+\fIcommand\fR.
+.SH KEYWORDS
+command, create, delete, interpreter, trace

doc/CrtWindow.3

@@ -1,146 +0,0 @@
-'\"
-'\" Copyright (c) 1990 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\"
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\"
-.TH Tk_CreateWindow 3 4.2 Tk "Tk Library Procedures"
-.so man.macros
-.BS
-.SH NAME
-Tk_CreateWindow, Tk_CreateWindowFromPath, Tk_DestroyWindow, Tk_MakeWindowExist \- create or delete window
-.SH SYNOPSIS
-.nf
-\fB#include <tk.h>\fR
-.sp
-Tk_Window
-\fBTk_CreateWindow\fR(\fIinterp, parent, name, topLevScreen\fR)
-.sp
-Tk_Window
-\fBTk_CreateAnonymousWindow\fR(\fIinterp, parent, topLevScreen\fR)
-.sp
-Tk_Window
-\fBTk_CreateWindowFromPath\fR(\fIinterp, tkwin, pathName, topLevScreen\fR)
-.sp
-\fBTk_DestroyWindow\fR(\fItkwin\fR)
-.sp
-\fBTk_MakeWindowExist\fR(\fItkwin\fR)
-.SH ARGUMENTS
-.AS Tcl_Interp *topLevScreen
-.AP Tcl_Interp *interp out
-Tcl interpreter to use for error reporting.  If no error occurs,
-then \fI*interp\fR is not modified.
-.AP Tk_Window parent in
-Token for the window that is to serve as the logical parent of
-the new window.
-.AP "const char" *name in
-Name to use for this window.  Must be unique among all children of
-the same \fIparent\fR.
-.AP "const char" *topLevScreen in
-Has same format as \fIscreenName\fR.  If NULL, then new window is
-created as an internal window.  If non-NULL, new window is created as
-a top-level window on screen \fItopLevScreen\fR.  If \fItopLevScreen\fR
-is an empty string
-.PQ ""
-then new window is created as top-level window of \fIparent\fR's screen.
-.AP Tk_Window tkwin in
-Token for window.
-.AP "const char" *pathName in
-Name of new window, specified as path name within application
-(e.g. \fB.a.b.c\fR).
-.BE
-.SH DESCRIPTION
-.PP
-The procedures \fBTk_CreateWindow\fR,
-\fBTk_CreateAnonymousWindow\fR, and \fBTk_CreateWindowFromPath\fR
-are used to create new windows for
-use in Tk-based applications.  Each of the procedures returns a token
-that can be used to manipulate the window in other calls to the Tk
-library.  If the window could not be created successfully, then NULL
-is returned and the result of interpreter \fIinterp\fR is modified to
-hold an error message.
-.PP
-Tk supports two different kinds of windows:  internal
-windows and top-level windows.
-An internal window is an interior window of a Tk application, such as a
-scrollbar or menu bar or button.  A top-level window is one that is
-created as a child of a screen's root window, rather than as an
-interior window, but which is logically part of some existing main
-window.  Examples of top-level windows are pop-up menus and dialog boxes.
-.PP
-New windows may be created by calling
-\fBTk_CreateWindow\fR.  If the \fItopLevScreen\fR argument is
-NULL, then the new window will be an internal window.  If
-\fItopLevScreen\fR is non-NULL, then the new window will be a
-top-level window: \fItopLevScreen\fR indicates the name of
-a screen and the new window will be created as a child of the
-root window of \fItopLevScreen\fR.  In either case Tk will
-consider the new window to be the logical child of \fIparent\fR:
-the new window's path name will reflect this fact, options may
-be specified for the new window under this assumption, and so on.
-The only difference is that new X window for a top-level window
-will not be a child of \fIparent\fR's X window.  For example, a pull-down
-menu's \fIparent\fR would be the button-like window used to invoke it,
-which would in turn be a child of the menu bar window.  A dialog box might
-have the application's main window as its parent.
-.PP
-\fBTk_CreateAnonymousWindow\fR differs from \fBTk_CreateWindow\fR in
-that it creates an unnamed window.  This window will be manipulatable
-only using C interfaces, and will not be visible to Tcl scripts.  Both
-interior windows and top-level windows may be created with
-\fBTk_CreateAnonymousWindow\fR.
-.PP
-\fBTk_CreateWindowFromPath\fR offers an alternate way of specifying
-new windows.  In \fBTk_CreateWindowFromPath\fR the new
-window is specified with a token for any window in the target
-application (\fItkwin\fR), plus a path name for the new window.
-It produces the same effect as \fBTk_CreateWindow\fR and allows
-both top-level and internal windows to be created, depending on
-the value of \fItopLevScreen\fR.  In calls to \fBTk_CreateWindowFromPath\fR,
-as in calls to \fBTk_CreateWindow\fR, the parent of the new window
-must exist at the time of the call, but the new window must not
-already exist.
-.PP
-The window creation procedures do not
-actually issue the command to X to create a window.
-Instead, they create a local data structure associated with
-the window and defer the creation of the X window.
-The window will actually be created by the first call to
-\fBTk_MapWindow\fR.  Deferred window creation allows various
-aspects of the window (such as its size, background color,
-etc.) to be modified after its creation without incurring
-any overhead in the X server.  When the window is finally
-mapped all of the window attributes can be set while creating
-the window.
-.PP
-The value returned by a window-creation procedure is not the
-X token for the window (it cannot be, since X has not been
-asked to create the window yet).  Instead, it is a token
-for Tk's local data structure for the window.  Most
-of the Tk library procedures take Tk_Window tokens, rather
-than X identifiers.  The actual
-X window identifier can be retrieved from the local
-data structure using the \fBTk_WindowId\fR macro;  see
-the manual entry for \fBTk_WindowId\fR for details.
-.PP
-\fBTk_DestroyWindow\fR deletes a window and all the data
-structures associated with it, including any event handlers
-created with \fBTk_CreateEventHandler\fR.  In addition,
-\fBTk_DestroyWindow\fR will delete any children of \fItkwin\fR
-recursively (where children are defined in the Tk sense, consisting
-of all windows that were created with the given window as \fIparent\fR).
-If \fItkwin\fR is an internal window, then event
-handlers interested in destroy events
-are invoked immediately.  If \fItkwin\fR is a top-level or main window,
-then the event handlers will be invoked later, after X has seen
-the request and returned an event for it.
-.PP
-If a window has been created
-but has not been mapped, so no X window exists, it is
-possible to force the creation of the X window by
-calling \fBTk_MakeWindowExist\fR.  This procedure issues
-the X commands to instantiate the window given by \fItkwin\fR.
-.SH KEYWORDS
-create, deferred creation, destroy, display, internal window,
-screen, top-level window, window

doc/DString.3

@@ -0,0 +1,153 @@
+'\"
+'\" Copyright (c) 1993 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.so man.macros
+.TH Tcl_DString 3 7.4 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_DStringInit, Tcl_DStringAppend, Tcl_DStringAppendElement, Tcl_DStringStartSublist, Tcl_DStringEndSublist, Tcl_DStringLength, Tcl_DStringValue, Tcl_DStringSetLength, Tcl_DStringTrunc, Tcl_DStringFree, Tcl_DStringResult, Tcl_DStringGetResult \- manipulate dynamic strings
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+\fBTcl_DStringInit\fR(\fIdsPtr\fR)
+.sp
+char *
+\fBTcl_DStringAppend\fR(\fIdsPtr, bytes, length\fR)
+.sp
+char *
+\fBTcl_DStringAppendElement\fR(\fIdsPtr, element\fR)
+.sp
+\fBTcl_DStringStartSublist\fR(\fIdsPtr\fR)
+.sp
+\fBTcl_DStringEndSublist\fR(\fIdsPtr\fR)
+.sp
+int
+\fBTcl_DStringLength\fR(\fIdsPtr\fR)
+.sp
+char *
+\fBTcl_DStringValue\fR(\fIdsPtr\fR)
+.sp
+\fBTcl_DStringSetLength\fR(\fIdsPtr, newLength\fR)
+.sp
+\fBTcl_DStringTrunc\fR(\fIdsPtr, newLength\fR)
+.sp
+\fBTcl_DStringFree\fR(\fIdsPtr\fR)
+.sp
+\fBTcl_DStringResult\fR(\fIinterp, dsPtr\fR)
+.sp
+\fBTcl_DStringGetResult\fR(\fIinterp, dsPtr\fR)
+.SH ARGUMENTS
+.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" *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 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
+character.
+.AP Tcl_Interp *interp in/out
+Interpreter whose result is to be set from or moved to the
+dynamic string.
+.BE
+
+.SH DESCRIPTION
+.PP
+Dynamic strings provide a mechanism for building up arbitrarily long
+strings by gradually appending information.  If the dynamic string is
+short then there will be no memory allocation overhead;  as the string
+gets larger, additional space will be allocated as needed.
+.PP
+\fBTcl_DStringInit\fR initializes a dynamic string to zero length.
+The Tcl_DString structure must have been allocated by the caller.
+No assumptions are made about the current state of the structure;
+anything already in it is discarded.
+If the structure has been used previously, \fBTcl_DStringFree\fR should
+be called first to free up any memory allocated for the old
+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 \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
+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 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
+.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
+\fBTcl_DStringStartSublist\fR and \fBTcl_DStringEndSublist\fR can be
+used to create nested lists.
+To append a list element that is itself a sublist, first
+call \fBTcl_DStringStartSublist\fR, then call \fBTcl_DStringAppendElement\fR
+for each of the elements in the sublist, then call
+\fBTcl_DStringEndSublist\fR to end the sublist.
+\fBTcl_DStringStartSublist\fR appends a space character if needed,
+followed by an open brace;  \fBTcl_DStringEndSublist\fR appends
+a close brace.
+Lists can be nested to any depth.
+.PP
+\fBTcl_DStringLength\fR is a macro that returns the current length
+of a dynamic string (not including the terminating null character).
+\fBTcl_DStringValue\fR is a  macro that returns a pointer to the
+current contents of a dynamic string.
+.PP
+.PP
+\fBTcl_DStringSetLength\fR changes the length of a dynamic string.
+If \fInewLength\fR is less than the string's current length, then
+the string is truncated.
+If \fInewLength\fR is greater than the string's current length,
+then the string will become longer and new space will be allocated
+for the string if needed.
+However, \fBTcl_DStringSetLength\fR will not initialize the new
+space except to provide a terminating null character;  it is up to the
+caller to fill in the new space.
+\fBTcl_DStringSetLength\fR does not free up the string's storage space
+even if the string is truncated to zero length, so \fBTcl_DStringFree\fR
+will still need to be called.
+.PP
+\fBTcl_DStringTrunc\fR changes the length of a dynamic string.
+This procedure is now deprecated.  \fBTcl_DStringSetLength\fR  should
+be used instead.
+.PP
+\fBTcl_DStringFree\fR should be called when you are finished using
+the string.  It frees up any memory that was allocated for the string
+and reinitializes the string's value to an empty string.
+.PP
+\fBTcl_DStringResult\fR sets the result of \fIinterp\fR to the value of
+the dynamic string given by \fIdsPtr\fR.  It does this by moving
+a pointer from \fIdsPtr\fR to the interpreter's result.
+This saves the cost of allocating new memory and copying the string.
+\fBTcl_DStringResult\fR also reinitializes the dynamic string to
+an empty string.
+.PP
+\fBTcl_DStringGetResult\fR does the opposite of \fBTcl_DStringResult\fR.
+It sets the value of \fIdsPtr\fR to the result of \fIinterp\fR and
+it clears \fIinterp\fR's result.
+If possible it does this by moving a pointer rather than by copying
+the string.
+
+.SH KEYWORDS
+append, dynamic string, free, result

doc/DeleteImg.3

@@ -1,31 +0,0 @@
-'\"
-'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
-'\"
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.TH Tk_DeleteImage 3 4.0 Tk "Tk Library Procedures"
-.so man.macros
-.BS
-.SH NAME
-Tk_DeleteImage \- Destroy an image.
-.SH SYNOPSIS
-.nf
-\fB#include <tk.h>\fR
-.sp
-\fBTk_DeleteImage\fR(\fIinterp, name\fR)
-.SH ARGUMENTS
-.AS Tcl_Interp *interp
-.AP Tcl_Interp *interp in
-Interpreter for which the image was created.
-.AP "const char" *name in
-Name of the image.
-.BE
-.SH DESCRIPTION
-.PP
-\fBTk_DeleteImage\fR deletes the image given by \fIinterp\fR
-and \fIname\fR, if there is one.  All instances of that image
-will redisplay as empty regions.  If the given image does not
-exist then the procedure has no effect.
-.SH KEYWORDS
-delete image, image manager

doc/DetachPids.3

@@ -0,0 +1,75 @@
+'\"
+'\" Copyright (c) 1989-1993 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.so man.macros
+.TH Tcl_DetachPids 3 "" Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_DetachPids, Tcl_ReapDetachedProcs, Tcl_WaitPid \- manage child processes in background
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+\fBTcl_DetachPids\fR(\fInumPids, pidPtr\fR)
+.sp
+\fBTcl_ReapDetachedProcs\fR()
+.sp
+Tcl_Pid
+\fBTcl_WaitPid\fR(\fIpid, statusPtr, options\fR)
+.SH ARGUMENTS
+.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 *statusPtr out
+The result of waiting on a process (pipe). Either 0 or ECHILD.
+.AP int options in
+The options controlling the wait. WNOHANG specifies not to wait when
+checking the process.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTcl_DetachPids\fR and \fBTcl_ReapDetachedProcs\fR provide a
+mechanism for managing subprocesses that are running in background.
+These procedures are needed because the parent of a process must
+eventually invoke the \fBwaitpid\fR kernel call (or one of a few other
+similar kernel calls) to wait for the child to exit.  Until the
+parent waits for the child, the child's state cannot be completely
+reclaimed by the system.  If a parent continually creates children
+and doesn't wait on them, the system's process table will eventually
+overflow, even if all the children have exited.
+.PP
+\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 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 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 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
+\fBTcl_ReapDetachedProcs\fR from time to time so that background
+processes can be cleaned up.
+.PP
+\fBTcl_WaitPid\fR is a thin wrapper around the facilities provided by
+the operating system to wait on the end of a spawned process and to
+check a whether spawned process is still running. It is used by
+\fBTcl_ReapDetachedProcs\fR and the channel system to portably access
+the operating system.
+
+.SH KEYWORDS
+background, child, detach, process, wait

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

@@ -0,0 +1,106 @@
+'\"
+'\" Copyright (c) 1990-1992 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.
+'\" 
+.so man.macros
+.TH Tcl_DoOneEvent 3 7.5 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_DoOneEvent \- wait for events and invoke event handlers
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+int
+\fBTcl_DoOneEvent\fR(\fIflags\fR)
+.SH ARGUMENTS
+.AS int flags
+.AP int flags in
+This parameter is normally zero.  It may be an OR-ed combination
+of any of the following flag bits:  
+\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
+.PP
+This procedure is the entry point to Tcl's event loop; it is responsible for
+waiting for events and dispatching event handlers created with
+procedures such as \fBTk_CreateEventHandler\fR, \fBTcl_CreateFileHandler\fR,
+\fBTcl_CreateTimerHandler\fR, and \fBTcl_DoWhenIdle\fR.
+\fBTcl_DoOneEvent\fR checks to see if
+events are already present on the Tcl event queue; if so,
+it calls the handler(s) for the first (oldest) event, removes it from
+the queue, and returns.
+If there are no events ready to be handled, then \fBTcl_DoOneEvent\fR
+checks for new events from all possible sources.
+If any are found, it puts all of them on Tcl's event queue, calls
+handlers for the first event on the queue, and returns.
+If no events are found, \fBTcl_DoOneEvent\fR checks for \fBTcl_DoWhenIdle\fR
+callbacks; if any are found, it invokes all of them and returns.
+Finally, if no events or idle callbacks have been found, then
+\fBTcl_DoOneEvent\fR sleeps until an event occurs; then it adds any 
+new events to the Tcl event queue, calls handlers for the first event,
+and returns.
+The normal return value is 1 to signify that some event
+was processed (see below for other alternatives).
+.PP
+If the \fIflags\fR argument to \fBTcl_DoOneEvent\fR is non-zero,
+it restricts the kinds of events that will be processed by
+\fBTcl_DoOneEvent\fR.
+\fIFlags\fR may be an OR-ed combination of any of the following bits:
+.TP 27
+\fBTCL_WINDOW_EVENTS\fR \-
+Process window system events.
+.TP 27
+\fBTCL_FILE_EVENTS\fR \-
+Process file events.
+.TP 27
+\fBTCL_TIMER_EVENTS\fR \-
+Process timer events.
+.TP 27
+\fBTCL_IDLE_EVENTS\fR \-
+Process idle callbacks.
+.TP 27
+\fBTCL_ALL_EVENTS\fR \-
+Process all kinds of events:  equivalent to OR-ing together all of the
+above flags or specifying none of them.
+.TP 27
+\fBTCL_DONT_WAIT\fR \-
+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,
+\fBTCL_TIMER_EVENTS\fR, or \fBTCL_IDLE_EVENTS\fR is set, then the only
+events that will be considered are those for which flags are set.
+Setting none of these flags is equivalent to the value
+\fBTCL_ALL_EVENTS\fR, which causes all event types to be processed.
+If an application has defined additional event sources with
+\fBTcl_CreateEventSource\fR, then additional \fIflag\fR values
+may also be valid, depending on those event sources.
+.PP
+The \fBTCL_DONT_WAIT\fR flag causes \fBTcl_DoOneEvent\fR not to put
+the process to sleep:  it will check for events but if none are found
+then it returns immediately with a return value of 0 to indicate
+that no work was done.
+\fBTcl_DoOneEvent\fR will also return 0 without doing anything if
+the only alternative is to block forever (this can happen, for example,
+if \fIflags\fR is \fBTCL_IDLE_EVENTS\fR and there are no
+\fBTcl_DoWhenIdle\fR callbacks pending, or if no event handlers or
+timer handlers exist).
+.PP
+\fBTcl_DoOneEvent\fR may be invoked recursively.  For example,
+it is possible to invoke \fBTcl_DoOneEvent\fR recursively
+from a handler called by \fBTcl_DoOneEvent\fR.  This sort
+of operation is useful in some modal situations, such
+as when a
+notification dialog has been popped up and an application wishes to
+wait for the user to click a button in the dialog before
+doing anything else.
+
+.SH KEYWORDS
+callback, event, handler, idle, timer

doc/DoWhenIdle.3

@@ -0,0 +1,84 @@
+'\"
+'\" Copyright (c) 1990 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.
+'\" 
+.so man.macros
+.TH Tcl_DoWhenIdle 3 7.5 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_DoWhenIdle, Tcl_CancelIdleCall \- invoke a procedure when there are no pending events
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+\fBTcl_DoWhenIdle\fR(\fIproc, clientData\fR)
+.sp
+\fBTcl_CancelIdleCall\fR(\fIproc, clientData\fR)
+.SH ARGUMENTS
+.AS Tcl_IdleProc clientData
+.AP Tcl_IdleProc *proc in
+Procedure to invoke.
+.AP ClientData clientData in
+Arbitrary one-word value to pass to \fIproc\fR.
+.BE
+
+.SH DESCRIPTION
+.PP
+\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, 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
+be a single call to \fIproc\fR;  after \fIproc\fR is
+invoked the handler is automatically removed.
+\fBTcl_DoWhenIdle\fR is only usable in programs that
+use \fBTcl_DoOneEvent\fR to dispatch events.
+.PP
+\fIProc\fR should have arguments and result that match the
+type \fBTcl_IdleProc\fR:
+.CS
+typedef void Tcl_IdleProc(ClientData \fIclientData\fR);
+.CE
+The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR
+argument given to \fBTcl_DoWhenIdle\fR.  Typically, \fIclientData\fR
+points to a data structure containing application-specific information about
+what \fIproc\fR should do.
+.PP
+\fBTcl_CancelIdleCall\fR
+may be used to cancel one or more previous
+calls to \fBTcl_DoWhenIdle\fR:  if there is a \fBTcl_DoWhenIdle\fR
+handler registered for \fIproc\fR and \fIclientData\fR, then it
+is removed without invoking it.  If there is more than one
+handler on the idle list that refers to \fIproc\fR and \fIclientData\fR,
+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 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
+actual work to be deferred until all pending events have
+been processed.  At this point the exact work to be done
+will presumably be known and it can be done exactly once.
+.PP
+For example, \fBTcl_DoWhenIdle\fR might be used by an editor
+to defer display updates until all pending commands have
+been processed.  Without this feature, redundant redisplays
+might occur in some situations, such as the processing of
+a command file.
+.SH BUGS
+.PP
+At present it is not safe for an idle callback to reschedule itself
+continuously.  This will interact badly with certain features of Tk
+that attempt to wait for all idle callbacks to complete.  If you would
+like for an idle callback to reschedule itself continuously, it is
+better to use a timer handler with a zero timeout period.
+
+.SH KEYWORDS
+callback, defer, idle callback

doc/DoubleObj.3

@@ -0,0 +1,64 @@
+'\"
+'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
+'\"
+'\" 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_DoubleObj 3 8.0 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_NewDoubleObj, Tcl_SetDoubleObj, Tcl_GetDoubleFromObj \- manipulate Tcl objects as floating-point values
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+Tcl_Obj *
+\fBTcl_NewDoubleObj\fR(\fIdoubleValue\fR)
+.sp
+\fBTcl_SetDoubleObj\fR(\fIobjPtr, doubleValue\fR)
+.sp
+int
+\fBTcl_GetDoubleFromObj\fR(\fIinterp, objPtr, doublePtr\fR)
+.SH ARGUMENTS
+.AS Tcl_Interp doubleValue in/out
+.AP double doubleValue in
+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 in which to store a
+double value.
+For \fBTcl_GetDoubleFromObj\fR, this refers to the object
+from which to retrieve a double value. 
+.AP Tcl_Interp *interp in/out
+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.
+.BE
+
+.SH DESCRIPTION
+.PP
+These procedures are used to create, modify, and read Tcl objects that
+hold double-precision floating-point values.
+.PP
+\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/DrawFocHlt.3

@@ -1,36 +0,0 @@
-'\"
-'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
-'\"
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.TH Tk_DrawFocusHighlight 3 4.0 Tk "Tk Library Procedures"
-.so man.macros
-.BS
-.SH NAME
-Tk_DrawFocusHighlight \- draw the traversal highlight ring for a widget
-.SH SYNOPSIS
-.nf
-\fB#include <tk.h>\fR
-.sp
-\fBTk_DrawFocusHighlight(\fItkwin, gc, width, drawable\fB)\fR
-.SH ARGUMENTS
-.AS "Tcl_Interp" *joinPtr
-.AP Tk_Window tkwin in
-Window for which the highlight is being drawn.  Used to retrieve
-the window's dimensions, among other things.
-.AP GC gc in
-Graphics context to use for drawing the highlight.
-.AP int width in
-Width of the highlight ring, in pixels.
-.AP Drawable drawable in
-Drawable in which to draw the highlight;  usually an offscreen
-pixmap for double buffering.
-.BE
-.SH DESCRIPTION
-.PP
-\fBTk_DrawFocusHighlight\fR is a utility procedure that draws the
-traversal highlight ring for a widget.
-It is typically invoked by widgets during redisplay.
-.SH KEYWORDS
-focus, traversal highlight

doc/DumpActiveMemory.3

@@ -0,0 +1,68 @@
+'\"
+'\" Copyright (c) 1992-1999 Karl Lehenbauer and Mark Diekhans.
+'\" Copyright (c) 2000 by Scriptics Corporation.
+'\" All rights reserved.
+'\" 
+.so man.macros
+.TH "Tcl_DumpActiveMemory" 3 8.1 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_DumpActiveMemory, Tcl_InitMemory, Tcl_ValidateAllMemory \- Validated memory allocation interface
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+int
+\fBTcl_DumpActiveMemory\fR(\fIfileName\fR)
+.sp
+void
+\fBTcl_InitMemory\fR(\fIinterp\fR)
+.sp
+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
+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).
+.AP int line in
+Line number at which the call to \fBTcl_ValidateAllMemory\fR is made
+(normally \fB__LINE__\fR).
+.BE
+
+.SH DESCRIPTION
+These functions provide access to Tcl memory debugging information.
+They are only functional when Tcl has been compiled with
+\fBTCL_MEM_DEBUG\fR defined at compile-time.  When \fBTCL_MEM_DEBUG\fR
+is not defined, these functions are all no-ops.
+.PP 
+\fBTcl_DumpActiveMemory\fR will output a list of all currently
+allocated memory to the specified file.  The information output for
+each allocated block of memory is:  starting and ending addresses
+(excluding guard zone), size, source file where \fBckalloc\fR was
+called to allocate the block and line number in that file.  It is
+especially useful to call \fBTcl_DumpActiveMemory\fR after the Tcl
+interpreter has been deleted.
+.PP
+\fBTcl_InitMemory\fR adds the Tcl \fBmemory\fR command to the
+interpreter given by \fIinterp\fR.  \fBTcl_InitMemory\fR is called
+by \fBTcl_Main\fR.
+.PP
+\fBTcl_ValidateAllMemory\fR forces a validation of the guard zones of
+all currently allocated blocks of memory.  Normally validation of a
+block occurs when its freed, unless full validation is enabled, in
+which case validation of all blocks occurs when \fBckalloc\fR and
+\fBckfree\fR are called.  This function forces the validation to occur
+at any point.
+
+.SH "SEE ALSO"
+TCL_MEM_DEBUG, memory
+
+.SH KEYWORDS
+memory, debug
+
+

doc/Encoding.3

@@ -0,0 +1,607 @@
+'\"
+'\" Copyright (c) 1997-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.
+'\" 
+.so man.macros
+.TH Tcl_GetEncoding 3 "8.1" Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_GetEncoding, Tcl_FreeEncoding, Tcl_GetEncodingFromObj, Tcl_ExternalToUtfDString, Tcl_ExternalToUtf, Tcl_UtfToExternalDString, Tcl_UtfToExternal, Tcl_WinTCharToUtf, Tcl_WinUtfToTChar, Tcl_GetEncodingName, Tcl_SetSystemEncoding, Tcl_GetEncodingNameFromEnvironment, Tcl_GetEncodingNames, Tcl_CreateEncoding, Tcl_GetEncodingSearchPath, Tcl_SetEncodingSearchPath, Tcl_GetDefaultEncodingDir, Tcl_SetDefaultEncodingDir \- procedures for creating and using encodings
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+Tcl_Encoding
+\fBTcl_GetEncoding\fR(\fIinterp, name\fR)
+.sp
+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
+char *
+\fBTcl_UtfToExternalDString\fR(\fIencoding, src, srcLen, dstPtr\fR)
+.sp
+int
+\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)
+.sp
+TCHAR *
+\fBTcl_WinUtfToTChar\fR(\fIsrc, srcLen, dstPtr\fR)
+.sp
+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
+.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 "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
+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 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
+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 
+encoding-specific length of the string is used.
+.AP Tcl_DString *dstPtr out
+Pointer to an uninitialized or free \fBTcl_DString\fR in which the converted
+result will be stored.
+.AP int flags in
+Various flag bits OR-ed together.  
+\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. \fBTCL_ENCODING_END\fR signifies that the source buffer is the last
+block in a (potentially multi-block) input stream, telling the conversion
+routine to perform any finalization that needs to occur after the last
+byte is converted and then to reset to an initial state.
+\fBTCL_ENCODING_STOPONERROR\fR signifies that the conversion routine should
+return immediately upon reading a source character that does not exist in
+the target encoding; otherwise a default fallback character will
+automatically be substituted.  
+.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
+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
+routine knows what state it was in when it left off at the end of the
+last piece.  May be NULL, in which case the value specified for \fIflags\fR 
+is ignored and the source buffer is assumed to contain the complete string to
+convert.
+.AP char *dst out
+Buffer in which the converted result will be stored.  No more than
+\fIdstLen\fR bytes will be stored in \fIdst\fR.
+.AP int dstLen in
+The maximum length of the output buffer \fIdst\fR in bytes.
+.AP int *srcReadPtr out
+Filled with the number of bytes from \fIsrc\fR that were actually
+converted.  This may be less than the original source length if there was
+a problem converting some source characters.  May be NULL.
+.AP int *dstWrotePtr out
+Filled with the number of bytes that were actually stored in the output
+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_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 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
+.PP
+These routines convert between Tcl's internal character representation,
+UTF-8, and character representations used by various operating systems or
+file systems, such as Unicode, ASCII, or Shift-JIS.  When operating on
+strings, such as such as obtaining the names of files or displaying
+characters using international fonts, the strings must be translated into
+one or possibly multiple formats that the various system calls can use.  For
+instance, on a Japanese Unix workstation, a user might obtain a filename
+represented in the EUC-JP file encoding and then translate the characters to
+the jisx0208 font encoding in order to display the filename in a Tk widget.
+The purpose of the encoding package is to help bridge the translation gap.
+UTF-8 provides an intermediate staging ground for all the various
+encodings.  In the example above, text would be translated into UTF-8 from
+whatever file encoding the operating system is using.  Then it would be
+translated from UTF-8 into whatever font encoding the display routines
+require.
+.PP
+Some basic encodings are compiled into Tcl.  Others can be defined by the
+user or dynamically loaded from encoding files in a
+platform-independent manner.
+.SH DESCRIPTION
+.PP
+\fBTcl_GetEncoding\fR finds an encoding given its \fIname\fR.  The name may
+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,
+\fBTcl_FreeEncoding\fR, and \fBTcl_UtfToExternal\fR.  If the name did not
+refer to any known or loadable encoding, NULL is returned and an error
+message is returned in \fIinterp\fR.
+.PP
+The encoding package maintains a database of all encodings currently in use.
+The first time \fIname\fR is seen, \fBTcl_GetEncoding\fR returns an
+encoding with a reference count of 1.  If the same \fIname\fR is requested
+further times, then the reference count for that encoding is incremented
+without the overhead of allocating a new encoding and all its associated
+data structures.  
+.PP
+When an \fIencoding\fR is no longer needed, \fBTcl_FreeEncoding\fR
+should be called to release it.  When an \fIencoding\fR is no longer in use
+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
+call \fBTcl_DStringFree\fR to free any information stored in \fIdstPtr\fR.
+When converting, if any of the characters in the source buffer cannot be
+represented in the target encoding, a default fallback character will be
+used.  The return value is a pointer to the value stored in the DString.
+.PP
+\fBTcl_ExternalToUtf\fR converts a source buffer \fIsrc\fR from the specified
+\fIencoding\fR into UTF-8.  Up to \fIsrcLen\fR bytes are converted from the
+source buffer and up to \fIdstLen\fR converted bytes are stored in \fIdst\fR.
+In all cases, \fI*srcReadPtr\fR is filled with the number of bytes that were
+successfully converted from \fIsrc\fR and \fI*dstWrotePtr\fR is filled with
+the corresponding number of bytes that were stored in \fIdst\fR.  The return
+value is one of the following:
+.RS
+.IP \fBTCL_OK\fR 29
+All bytes of \fIsrc\fR were converted.
+.IP \fBTCL_CONVERT_NOSPACE\fR 29
+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 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
+from the source stream to properly convert the formerly split-up multibyte
+sequence.  
+.IP \fBTCL_CONVERT_SYNTAX\fR 29
+The source buffer contained an invalid character sequence.  This may occur
+if the input stream has been damaged or if the input encoding method was
+misidentified.
+.IP \fBTCL_CONVERT_UNKNOWN\fR 29
+The source buffer contained a character that could not be represented in
+the target encoding and \fBTCL_ENCODING_STOPONERROR\fR was specified.  
+.RE
+.LP
+\fBTcl_UtfToExternalDString\fR converts a source buffer \fIsrc\fR from UTF-8 
+into the specified \fIencoding\fR.  The converted bytes are stored in
+\fIdstPtr\fR, which is then terminated with the appropriate encoding-specific
+null.  The caller should eventually call \fBTcl_DStringFree\fR to free any
+information stored in \fIdstPtr\fR.  When converting, if any of the
+characters in the source buffer cannot be represented in the target
+encoding, a default fallback character will be used.  The return value is
+a pointer to the value stored in the DString.
+.PP
+\fBTcl_UtfToExternal\fR converts a source buffer \fIsrc\fR from UTF-8 into
+the specified \fIencoding\fR.  Up to \fIsrcLen\fR bytes are converted from
+the source buffer and up to \fIdstLen\fR converted bytes are stored in
+\fIdst\fR.  In all cases, \fI*srcReadPtr\fR is filled with the number of
+bytes that were successfully converted from \fIsrc\fR and \fI*dstWrotePtr\fR
+is filled with the corresponding number of bytes that were stored in
+\fIdst\fR.  The return values are the same as the return values for
+\fBTcl_ExternalToUtf\fR.
+.PP
+\fBTcl_WinUtfToTChar\fR and \fBTcl_WinTCharToUtf\fR are
+Windows-only convenience
+functions for converting between UTF-8 and Windows strings.  On Windows 95
+(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
+.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
+.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
+.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
+if (running NT) {
+    encoding <- Tcl_GetEncoding("unicode");
+    nativeBuffer <- Tcl_UtfToExternal(encoding, utfBuffer);
+    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
+operating system.  \fBTcl_WinUtfToTChar\fR returns a pointer to
+a TCHAR string, and \fBTcl_WinTCharToUtf\fR expects a TCHAR string
+pointer as the \fIsrc\fR string.  Otherwise, these functions
+behave identically to \fBTcl_UtfToExternalDString\fR and
+\fBTcl_ExternalToUtfDString\fR.
+.PP
+\fBTcl_GetEncodingName\fR is roughly the inverse of \fBTcl_GetEncoding\fR.
+Given an \fIencoding\fR, the return value is the \fIname\fR argument that
+was used to create the encoding.  The string returned by 
+\fBTcl_GetEncodingName\fR is only guaranteed to persist until the
+\fIencoding\fR is deleted.  The caller must not modify this string.
+.PP
+\fBTcl_SetSystemEncoding\fR sets the default encoding that should be used
+whenever the user passes a NULL value for the \fIencoding\fR argument to
+any of the other encoding functions.  If \fIname\fR is NULL, the system
+encoding is reset to the default system encoding, \fBbinary\fR.  If the
+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
+\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
+or can be dynamically loaded, searching the encoding path specified by
+\fBTcl_SetDefaultEncodingDir\fR.  This procedure does not ensure that the
+dynamically-loadable encoding files contain valid data, but merely that they
+exist.
+.PP
+\fBTcl_CreateEncoding\fR defines a new encoding and registers the C
+procedures that are called back to convert between the encoding and
+UTF-8.  Encodings created by \fBTcl_CreateEncoding\fR are thereafter
+visible in the database used by \fBTcl_GetEncoding\fR.  Just as with the
+\fBTcl_GetEncoding\fR procedure, the return value is a token that
+represents the encoding and can be used in subsequent calls to other
+encoding functions.  \fBTcl_CreateEncoding\fR returns an encoding with a
+reference count of 1. If an encoding with the specified \fIname\fR
+already exists, then its entry in the database is replaced with the new
+encoding; the token for the old encoding will remain valid and continue
+to behave as before, but users of the new token will now call the new
+encoding procedures.  
+.PP
+The \fItypePtr\fR argument to \fBTcl_CreateEncoding\fR contains information 
+about the name of the encoding and the procedures that will be called to
+convert between this encoding and UTF-8.  It is defined as follows:
+.PP
+.CS
+typedef struct Tcl_EncodingType {
+        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
+The \fIencodingName\fR provides a string name for the encoding, by
+which it can be referred in other procedures such as
+\fBTcl_GetEncoding\fR.  The \fItoUtfProc\fR refers to a callback
+procedure to invoke to convert text from this encoding into UTF-8.
+The \fIfromUtfProc\fR refers to a callback procedure to invoke to
+convert text from UTF-8 into this encoding.  The \fIfreeProc\fR refers
+to a callback procedure to invoke when this encoding is deleted.  The
+\fIfreeProc\fR field may be NULL.  The \fIclientData\fR contains an
+arbitrary one-word value passed to \fItoUtfProc\fR, \fIfromUtfProc\fR,
+and \fIfreeProc\fR whenever they are called.  Typically, this is a
+pointer to a data structure containing encoding-specific information
+that can be used by the callback procedures.  For instance, two very
+similar encodings such as \fBascii\fR and \fBmacRoman\fR may use the
+same callback procedure, but use different values of \fIclientData\fR
+to control its behavior.  The \fInullSize\fR specifies the number of
+zero bytes that signify end-of-string in this encoding.  It must be
+\fB1\fR (for single-byte or multi-byte encodings like ASCII or
+Shift-JIS) or \fB2\fR (for double-byte encodings like Unicode).
+Constant-sized encodings with 3 or more bytes per character (such as
+CNS11643) are not accepted.
+.PP
+The callback procedures \fItoUtfProc\fR and \fIfromUtfProc\fR should match the
+type \fBTcl_EncodingConvertProc\fR:
+.PP
+.CS
+typedef int Tcl_EncodingConvertProc(
+        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
+\fBTcl_ExternalToUtf\fR or \fBTcl_UtfToExternal\fR family of functions to
+perform the actual conversion.  The \fIclientData\fR parameter to these
+procedures is the same as the \fIclientData\fR field specified to
+\fBTcl_CreateEncoding\fR when the encoding was created.  The remaining
+arguments to the callback procedures are the same as the arguments,
+documented at the top, to \fBTcl_ExternalToUtf\fR or
+\fBTcl_UtfToExternal\fR, with the following exceptions.  If the
+\fIsrcLen\fR argument to one of those high-level functions is negative,
+the value passed to the callback procedure will be the appropriate
+encoding-specific string length of \fIsrc\fR.  If any of the \fIsrcReadPtr\fR, 
+\fIdstWrotePtr\fR, or \fIdstCharsPtr\fR arguments to one of the high-level
+functions is NULL, the corresponding value passed to the callback
+procedure will be a non-NULL location.
+.PP
+The callback procedure \fIfreeProc\fR, if non-NULL, should match the type 
+\fBTcl_EncodingFreeProc\fR:
+.CS
+typedef void Tcl_EncodingFreeProc(
+        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
+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
+encoding files.  This behavior also allows the user to create additional
+encoding files that can be loaded using the same mechanism.  These
+encoding files contain information about the tables and/or escape
+sequences used to map between an external encoding and Unicode.  The
+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
+.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"
+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"
+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"
+A multi-byte encoding, where one character may be either one or two bytes long.
+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"
+An escape-sequence encoding, specifying that certain sequences of bytes
+do not represent characters, but commands that describe how following bytes
+should be interpreted.  
+.PP
+The rest of the lines in the file depend on the type.  
+.PP
+Cases [1], [2], and [3] are collectively referred to as table-based encoding
+files.  The lines in a table-based encoding file are in the same
+format as this example taken from the \fBshiftjis\fR encoding (this is not
+the complete file):
+.CS
+# Encoding file: shiftjis, multi-byte
+M
+003F 0 40
+00
+0000000100020003000400050006000700080009000A000B000C000D000E000F
+0010001100120013001400150016001700180019001A001B001C001D001E001F
+0020002100220023002400250026002700280029002A002B002C002D002E002F
+0030003100320033003400350036003700380039003A003B003C003D003E003F
+0040004100420043004400450046004700480049004A004B004C004D004E004F
+0050005100520053005400550056005700580059005A005B005C005D005E005F
+0060006100620063006400650066006700680069006A006B006C006D006E006F
+0070007100720073007400750076007700780079007A007B007C007D203E007F
+0080000000000000000000000000000000000000000000000000000000000000
+0000000000000000000000000000000000000000000000000000000000000000
+0000FF61FF62FF63FF64FF65FF66FF67FF68FF69FF6AFF6BFF6CFF6DFF6EFF6F
+FF70FF71FF72FF73FF74FF75FF76FF77FF78FF79FF7AFF7BFF7CFF7DFF7EFF7F
+FF80FF81FF82FF83FF84FF85FF86FF87FF88FF89FF8AFF8BFF8CFF8DFF8EFF8F
+FF90FF91FF92FF93FF94FF95FF96FF97FF98FF99FF9AFF9BFF9CFF9DFF9EFF9F
+0000000000000000000000000000000000000000000000000000000000000000
+0000000000000000000000000000000000000000000000000000000000000000
+81
+0000000000000000000000000000000000000000000000000000000000000000
+0000000000000000000000000000000000000000000000000000000000000000
+0000000000000000000000000000000000000000000000000000000000000000
+0000000000000000000000000000000000000000000000000000000000000000
+300030013002FF0CFF0E30FBFF1AFF1BFF1FFF01309B309C00B4FF4000A8FF3E
+FFE3FF3F30FD30FE309D309E30034EDD30053006300730FC20152010FF0F005C
+301C2016FF5C2026202520182019201C201DFF08FF0930143015FF3BFF3DFF5B
+FF5D30083009300A300B300C300D300E300F30103011FF0B221200B100D70000
+00F7FF1D2260FF1CFF1E22662267221E22342642264000B0203220332103FFE5
+FF0400A200A3FF05FF03FF06FF0AFF2000A72606260525CB25CF25CE25C725C6
+25A125A025B325B225BD25BC203B301221922190219121933013000000000000
+000000000000000000000000000000002208220B2286228722822283222A2229
+000000000000000000000000000000002227222800AC21D221D4220022030000
+0000000000000000000000000000000000000000222022A52312220222072261
+2252226A226B221A223D221D2235222B222C0000000000000000000000000000
+212B2030266F266D266A2020202100B6000000000000000025EF000000000000
+.CE
+.PP
+The third line of the file is three numbers.  The first number is the
+fallback character (in base 16) to use when converting from UTF-8 to this
+encoding.  The second number is a \fB1\fR if this file represents the
+encoding for a symbol font, or \fB0\fR otherwise.  The last number (in base
+10) is how many pages of data follow.  
+.PP
+Subsequent lines in the example above are pages that describe how to map
+from the encoding into 2-byte Unicode.  The first line in a page identifies
+the page number.  Following it are 256 double-byte numbers, arranged as 16
+rows of 16 numbers.  Given a character in the encoding, the high byte of
+that character is used to select which page, and the low byte of that
+character is used as an index to select one of the double-byte numbers in
+that page \- the value obtained being the corresponding Unicode character.
+By examination of the example above, one can see that the characters 0x7E
+and 0x8163 in \fBshiftjis\fR map to 203E and 2026 in Unicode, respectively.
+.PP
+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 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
+file are in the same format as this example taken from the \fBiso2022-jp\fR
+encoding:
+.CS
+.ta 1.5i
+# Encoding file: iso2022-jp, escape-driven
+E
+init		{}
+final		{}
+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
+is the associated value.  \fBinit\fR is a string to emit or expect before
+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,
+.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 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

@@ -0,0 +1,38 @@
+'\"
+'\" Copyright (c) 1997-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.
+'\" 
+.so man.macros
+.TH Tcl_PutEnv 3 "7.5" Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_PutEnv \- procedures to manipulate the environment
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+int
+\fBTcl_PutEnv\fR(\fIassignment\fR)
+.SH ARGUMENTS
+.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
+.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
+\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

@@ -0,0 +1,208 @@
+'\"
+'\" Copyright (c) 1989-1993 The Regents of the University of California.
+'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
+'\" Copyright (c) 2000 Scriptics Corporation.
+'\"
+'\" 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_Eval 3 8.1 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_EvalObjEx, Tcl_EvalFile, Tcl_EvalObjv, Tcl_Eval, Tcl_EvalEx, Tcl_GlobalEval, Tcl_GlobalEvalObj, Tcl_VarEval, Tcl_VarEvalVA \- execute Tcl scripts
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+int
+\fBTcl_EvalObjEx\fR(\fIinterp, objPtr, flags\fR)
+.sp
+int
+\fBTcl_EvalFile\fR(\fIinterp, fileName\fR)
+.sp
+int
+\fBTcl_EvalObjv\fR(\fIinterp, objc, objv, flags\fR)
+.sp
+int
+\fBTcl_Eval\fR(\fIinterp, script\fR)
+.sp
+int
+\fBTcl_EvalEx\fR(\fIinterp, script, numBytes, flags\fR)
+.sp
+int
+\fBTcl_GlobalEval\fR(\fIinterp, script\fR)
+.sp
+int
+\fBTcl_GlobalEvalObj\fR(\fIinterp, objPtr\fR)
+.sp
+int
+\fBTcl_VarEval\fR(\fIinterp, part, part, ... \fB(char *) NULL\fR)
+.sp
+int
+\fBTcl_VarEvalVA\fR(\fIinterp, argList\fR)
+.SH ARGUMENTS
+.AS Tcl_Interp **termPtr
+.AP Tcl_Interp *interp in
+Interpreter in which to execute the script.  The interpreter's result is
+modified to hold the result or error message from the script.
+.AP Tcl_Obj *objPtr in
+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
+Name of a file containing a Tcl script.
+.AP int objc in
+The number of objects in the array pointed to by \fIobjPtr\fR;
+this is also the number of words in the command.
+.AP Tcl_Obj **objv in
+Points to an array of pointers to objects; each object holds the
+value of a single word in the command to execute.
+.AP int numBytes in
+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
+Points to first byte of script to execute (null-terminated and UTF-8).
+.AP char *part in
+String forming part of a Tcl script.
+.AP va_list argList in
+An argument list which must have been initialized using
+\fBva_start\fR, and cleared using \fBva_end\fR.
+.BE
+
+.SH DESCRIPTION
+.PP
+The procedures described here are invoked to execute Tcl scripts in
+various forms.
+\fBTcl_EvalObjEx\fR is the core procedure and is used by many of the others.
+It executes the commands in the script stored in \fIobjPtr\fR
+until either an error occurs or the end of the script is reached.
+If this is the first time \fIobjPtr\fR has been executed,
+its commands are compiled into bytecode instructions
+which are then executed.  The
+bytecodes are saved in \fIobjPtr\fR so that the compilation step
+can be skipped if the object is evaluated again in the future.
+.PP
+The return value from \fBTcl_EvalObjEx\fR (and all the other procedures
+described here) is a Tcl completion code with
+one of the values \fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR,
+\fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR, or possibly some other
+integer value originating in an extension.
+In addition, a result value or error message is left in \fIinterp\fR's
+result; it can be retrieved using \fBTcl_GetObjResult\fR.
+.PP
+\fBTcl_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 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 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
+executed again, \fBTcl_Eval\fR may be faster than \fBTcl_EvalObjEx\fR.
+ \fBTcl_Eval\fR returns a completion code and result just like 
+\fBTcl_EvalObjEx\fR.  Note: for backward compatibility with versions before
+Tcl 8.0, \fBTcl_Eval\fR copies the 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
+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
+efficiency reason given above, \fBTcl_EvalEx\fR is generally preferred
+over \fBTcl_Eval\fR.
+.PP
+\fBTcl_GlobalEval\fR and \fBTcl_GlobalEvalObj\fR are older procedures
+that are now deprecated.  They are similar to \fBTcl_EvalEx\fR and
+\fBTcl_EvalObjEx\fR except that the script is evaluated in the global
+namespace and its variable context consists of global variables only
+(it ignores any Tcl procedures that are active).  These functions are
+equivalent to using the \fBTCL_EVAL_GLOBAL\fR flag (see below).
+.PP
+\fBTcl_VarEval\fR takes any number of string arguments
+of any length, concatenates them into a single string,
+then calls \fBTcl_Eval\fR to execute that string as a Tcl command.
+It returns the result of the command and also modifies
+\fIinterp->result\fR in the same way as \fBTcl_Eval\fR.
+The last argument to \fBTcl_VarEval\fR must be NULL to indicate the end
+of arguments.  \fBTcl_VarEval\fR is now deprecated.
+.PP
+\fBTcl_VarEvalVA\fR is the same as \fBTcl_VarEval\fR except that
+instead of taking a variable number of arguments it takes an argument
+list. Like \fBTcl_VarEval\fR, \fBTcl_VarEvalVA\fR is deprecated.
+
+.SH "FLAG BITS"
+Any ORed combination of the following values may be used for the
+\fIflags\fR argument to procedures such as \fBTcl_EvalObjEx\fR:
+.TP 23
+\fBTCL_EVAL_DIRECT\fR
+This flag is only used by \fBTcl_EvalObjEx\fR; it is ignored by
+other procedures.  If this flag bit is set, the script is not
+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 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
+means that it is evaluated in the global namespace and its variable
+context consists of global variables only (it ignores any Tcl
+procedures at are active).
+
+.SH "MISCELLANEOUS DETAILS"
+.PP
+During the processing of a Tcl command it is legal to make nested
+calls to evaluate other commands (this is how procedures and
+some control structures are implemented).
+If a code other than \fBTCL_OK\fR is returned
+from a nested \fBTcl_EvalObjEx\fR invocation,
+then the caller should normally return immediately,
+passing that same return code back to its caller,
+and so on until the top-level application is reached.
+A few commands, like \fBfor\fR, will check for certain
+return codes, like \fBTCL_BREAK\fR and \fBTCL_CONTINUE\fR, and process them
+specially without returning.
+.PP
+\fBTcl_EvalObjEx\fR keeps track of how many nested \fBTcl_EvalObjEx\fR
+invocations are in progress for \fIinterp\fR.
+If a code of \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR is
+about to be returned from the topmost \fBTcl_EvalObjEx\fR
+invocation for \fIinterp\fR,
+it converts the return code to \fBTCL_ERROR\fR
+and sets \fIinterp\fR's result to an error message indicating that
+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.
+
+.SH KEYWORDS
+execute, file, global, object, result, script