syntax cleanup

cleaned up syntax, corrected package:: -> pkg::
Remove need for "OLDROUTINENAMES" def'n in one more file...
2000-02-10 10:21:02 +00:00 · 2000-02-10 10:09:18 +00:00 · 2000-02-10 09:59:10 +00:00 · 2000-02-10 09:53:53 +00:00 · 2000-02-10 09:53:45 +00:00 · 2000-02-10 08:55:39 +00:00
781 changed files with 306848 additions and 48398 deletions
@@ -1,46 +1,76 @@
-Tcl
+README:  Tcl
+    This is the Tcl 8.3.0 source distribution.
+    You can get any release of Tcl from:
+        http://www.scriptics.com/registration/<version>.tml
+    Tcl/Tk is also available through NetCVS:
+	http://www.scriptics.com/products/tcltk/netcvs.html

-SCCS: @(#) README 1.52 97/11/20 12:43:16
+RCS: @(#) $Id: README,v 1.28 2000/02/08 10:05:09 hobbs Exp $
+
+Contents
+--------
+    1. Introduction
+    2. Documentation
+    3. Compiling and installing Tcl
+    4. Development tools
+    5. Tcl newsgroup
+    6. Tcl contributed archive
+    7. Tcl Resource Center
+    8. Mailing lists
+    9. Support and Training
+    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 the Macintosh.  Tcl can also be used for a
+variety of web-related tasks and for creating powerful command
+languages for applications.

-This directory and its descendants contain the sources and documentation
-for Tcl, an embeddable scripting language.  The information here
-corresponds to release 8.0p2, which is the second patch update for Tcl
-8.0. Tcl 8.0 is a major new release that replaces the core of the
-interpreter with an on-the-fly bytecode compiler to improve execution
-speed.  It also includes several other new features such as namespaces
-and binary I/O, plus many bug fixes.  The compiler introduces a few
-incompatibilities that may affect existing Tcl scripts; the
-incompatibilities are relatively obscure but may require modifications
-to some old scripts before they can run with this version. The compiler
-introduces many new C-level APIs, but the old APIs are still supported.
-See below for more details.  This patch release fixes various bugs in
-Tcl 8.0; there are no feature changes relative to Tcl 8.0.
+Tcl is maintained, enhanced, and distributed freely as a
+service to the Tcl community by Scriptics Corporation.
+The official home for Tcl/Tk is on the Scriptics Web site:
+
+	http://www.scriptics.com
+
+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. Documentation
----------------
+---------------

-The best way to get started with Tcl is to read one of the introductory
-books on Tcl:
+Extensive documentation is available at our website.
+The home page for this release is
+	http://www.scriptics.com/software/8.3.html

-    Practical Programming in Tcl and Tk, 2nd Edition, by Brent Welch,
-    Prentice-Hall, 1997, ISBN 0-13-616830-2
+Information about new features in 8.3 can be found at
+	http://www.scriptics.com/software/whatsnew83.html

-    Tcl and the Tk Toolkit, by John Ousterhout,
-    Addison-Wesley, 1994, ISBN 0-201-63337-X
+Detailed release notes can be found at
+	http://www.scriptics.com/software/relnotes/tcl8.3.0

-    Exploring Expect, by Don Libes,
-    O'Reilly and Associates, 1995, ISBN 1-56592-090-2
+Information about Tcl itself can be found at
+	http://www.scriptics.com/scripting/

-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, cd to the "doc" directory and invoke your favorite variant of
-troff using the normal -man macros, for example
+There are many Tcl books on the market.  Most are listed at
+	http://www.scriptics.com/resource/doc/books/
+
+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

@@ -50,219 +80,44 @@ using the normal "man" mechanisms, such as

 		man Tcl

-There is also an official home for Tcl and Tk on the Web:
-	http://sunscript.sun.com
-These Web pages include information about the latest releases, products
-related to Tcl and Tk, reports on bug fixes and porting issues, HTML
-versions of the manual pages, and pointers to many other Tcl/Tk Web
-pages at other sites.  Check them out!
+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
 -------------------------------

-This release contains everything you should need to compile and run
-Tcl under UNIX, Macintoshes, and PCs (either Windows NT, Windows 95,
-or Win 3.1 with Win32s).
+There are brief notes in the unix/README, win/README, and mac/README
+about compiling on these different platforms.  There is additional
+information about building Tcl from sources at
+    http://www.scriptics.com/support/howto/compile.html

-Before trying to compile Tcl you should do the following things:

-    (a) Check for a binary release.  Pre-compiled binary releases are
-        available now for PCs, Macintoshes, and several flavors of UNIX.
-        Binary releases are much easier to install than source releases.
-        To find out whether a binary release is available for your
-        platform, check the home page for SunScript
-        (http://sunscript.sun.com) under "Tech Corner".  Also, check in
-        the FTP directory from which you retrieved the base
-        distribution.  Some of the binary releases are available freely,
-        while others are for sale.
+4. TclPro Development tools
+--------------------

-    (b) Make sure you have the most recent patch release.  Look in the
-	FTP directory from which you retrieved this distribution to see
-	if it has been updated with patches.  Patch releases fix bugs
-	without changing any features, so you should normally use the
-	latest patch release for the version of Tcl that you want. 
-	Patch releases are available in two forms.  A file like
-	tcl8.0p2.tar.Z is a complete release for patch level 2 of Tcl
-	version 8.0.  If there is a file with a higher patch level than
-	this release, just fetch the file with the highest patch level
-	and use it.
+A high quality set of commercial development tools is now available to
+accelerate your Tcl application development.  Scriptics' TclPro
+product provides a debugger, static code checker, packaging utility,
+and bytecode compiler.  Visit the Scriptics Web site at:

-	Patches are also available in the form of patch files that just
-	contain the changes from one patch level to another.  These
-	files will have names like tcl8.0p1.patch, tcl8.0p2.patch, etc.  They
-	may also have .gz or .Z extensions to indicate compression.  To
-	use one of these files, you apply it to an existing release with
-	the "patch" program.  Patches must be applied in order:
-	tcl8.0p1.patch must be applied to an unpatched Tcl 8.0 release
-	to produce a Tcl 8.0p1 release;  tcl8.0p2.patch can then be
-	applied to Tcl8.0p1 to produce Tcl 8.0p2, and so on. To apply an
-	uncompressed patch file such as tcl8.0p1.patch, invoke a shell
-	command like the following from the directory containing this
-	file:
-	    patch -p < tcl8.0p1.patch
-	If the patch file has a .gz extension, invoke a command like the
-	following:
-	    gunzip -c tcl8.0p1.patch.gz | patch -p
-	If the patch file has a .Z extension, it was compressed with
-	compress.  To apply it, invoke a command like the following:
-	    zcat tcl8.0p1.patch.Z | patch -p
-	If you're applying a patch to a release that has already been
-	compiled, then before applying the patch you should cd to the
-	"unix" subdirectory and type "make distclean" to restore the
-	directory to a pristine state.
+	http://www.scriptics.com/tclpro

-Once you've done this, change to the "unix" subdirectory if you're
-compiling under UNIX, "win" if you're compiling under Windows, or
-"mac" if you're compiling on a Macintosh.  Then follow the instructions
-in the README file in that directory for compiling Tcl, installing it,
-and running the test suite.
-
-4. Summary of changes in Tcl 8.0
--------------------------------
-
-Here are the most significant changes in Tcl 8.0.  In addition to these
-changes, there are several smaller changes and bug fixes.  See the file
-"changes" for a complete list of all changes.
-
-    1. Bytecode compiler.  The core of the Tcl interpreter has been
-    replaced with an on-the-fly compiler that translates Tcl scripts to
-    byte codes; a new interpreter then executes the byte codes. In
-    earlier versions of Tcl, strings were used as a universal
-    representation;  in Tcl 8.0 strings are replaced with Tcl_Obj
-    structures ("objects") that can hold both a string value and an
-    internal form such as a binary integer or compiled bytecodes.  The
-    new objects make it possible to store information in efficient
-    internal forms and avoid the constant translations to and from
-    strings that occurred with the old interpreter.  We have not yet
-    converted all of Tcl to take full advantage of the compiler and
-    objects and have not converted any of Tk yet, but even so you
-    should see speedups of 2-3x on many programs and you may see
-    speedups as much as 10-20x in some cases (such as code that
-    manipulates long lists).  Future releases should achieve even
-    greater speedups.  The compiler introduces only a few minor changes
-    at the level of Tcl scripts, but it introduces many new C APIs for
-    managing objects.  See, for example, the manual entries doc/*Obj*.3.
-
-    2. Namespaces.  There is a new namespace mechanism based on the
-    namespace implementation by Michael McLennan of Lucent Technologies.
-    This includes new "namespace" and "variable" commands.  There are
-    many new C APIs associated with namespaces, but they will not be
-    exported until Tcl 8.1.  Note: the syntax of the namespace command
-    has been changed slightly since the b1 release.  See the changes
-    file for details.
-
-    3. Binary I/O.  The new object system in Tcl 8.0 supports binary
-    strings (internally, strings are counted in addition to being null
-    terminated).  There is a new "binary" command for inserting and
-    extracting data to/from binary strings.  Commands such as "puts",
-    "gets", and "read" commands now operate correctly on binary data. 
-    There is a new variable tcl_platform(byteOrder) to identify the
-    native byte order for the current host.
-
-    4. Random numbers.  The "expr" command now contains a random number
-    generator, which can be accessed via the "rand()" and "srand()" math
-    functions.
-
-    5. Safe-Tcl enhancements.  There is a new "hidden command"
-    mechanism, implemented with the Tcl commands "interp hide", "interp
-    expose", "interp invokehidden", and "interp hidden" and the C APIs
-    Tcl_HideCommand and Tcl_ExposeCommand.  There is now support for
-    safe packages and extension loading, including new library
-    procedures such as safe::interpCreate (see the manual entry safe.n
-    for details).
-
-    6. There is a new package "registry" available under Windows for
-    accessing the Windows registry.
-
-    7. There is a new command "file attributes" for getting and setting
-    things like permissions and owner.  There is also a new command
-    "file nativename" for getting back the platform-specific name for a
-    particular file.
-
-    8. There is a new "fcopy" command to copy data between channels. 
-    This replaces and improves upon the not-so-secret unsupported old
-    command "unsupported0".
-
-    9. There is a new package "http" for doing GET, POST, and HEAD
-    requests via the HTTP/1.0 protocol.  See the manual entry http.n
-    for details.
-
-    10. There are new library procedures for finding word breaks in
-    strings.  See the manual entry library.n for details.
-
-    11. There are new C APIs Tcl_Finalize (for cleaning up before
-    unloading the Tcl DLL) and Tcl_Ungets for pushing bytes back into a
-    channel's input buffer.
-
-    12. Tcl now supports serial I/O devices on Windows and Unix, with a
-    new fconfigure -mode option.  The Windows driver does not yet
-    support event-driven I/O.
-
-    13. The lsort command has new options -dictionary and -index.  The
-    -index option allows for very rapid sorting based on an element
-    of a list.
-
-    14. The event notifier has been completely rewritten (again).  It
-    should now allow Tcl to use an external event loop (like Motif's)
-    when it is embedded in other applications.  No script-level
-    interfaces have changed, but many of the C APIs have.
-
-Tcl 8.0 introduces the following incompatibilities that may affect Tcl
-scripts that worked under Tcl 7.6 and earlier releases:
-
-    1. Variable and command names may not include the character sequence
-    "::" anymore: this sequence is now used as a namespace separator.
-
-    2. The semantics of some Tcl commands have been changed slightly to
-    maximize performance under the compiler.  These incompatibilities
-    are documented on the Web so that we can keep the list up-to-date.
-    See the URL http://www.sunlabs.com/research/tcl/compiler.html.
-
-    3. 2-digit years are now parsed differently by the "clock" command
-    to handle year 2000 issues better (years 00-38 are treated as
-    2000-2038 instead of 1900-1938).
-
-    4. The old Macintosh commands "cp", "mkdir", "mv", "rm", and "rmdir"
-    are no longer supported; all of these features are now available on
-    all platforms via the "file" command.
-
-    5. The variable tcl_precision is now shared between interpreters
-    and defaults to 12 digits instead of 6; safe interpreters cannot
-    modify tcl_precision.  The new object system in Tcl 8.0 causes
-    floating-to-string conversions (and the associated rounding) to
-    occur much less often than in Tcl 7.6, which can sometimes cause
-    behavioral changes.
-
-    6. The C APIs associated with the notifier have changed substantially.
-
-    7. The procedures Tcl_CreateModalTimeout and Tcl_DeleteModalTimeout
-    have been removed.
-
-    8. Tcl_CreateFileHandler and Tcl_DeleteFileHandler now take Unix
-    fd's and are only supported on the Unix platform
-
-    9. The C APIs for creating channel drivers have changed as part of
-    the new notifier implementation.  The Tcl_File interfaces have been
-    removed.  Tcl_GetChannelFile has been replaced with
-    Tcl_GetChannelHandle.  Tcl_MakeFileChannel now takes a platform-
-    specific file handle.  Tcl_DriverGetOptionProc procedures now take
-    an additional interp argument.
+for more information on TclPro and for a free evaluation download.

 5. Tcl newsgroup
-----------------
+----------------

-There is a network news group "comp.lang.tcl" intended for the exchange
-of information about Tcl, Tk, and related applications.  Feel free to use
-the newsgroup both for general information questions and for bug reports.
-We read the newsgroup and will attempt to fix bugs and problems reported
-to it.
-
-When using comp.lang.tcl, please be sure that your e-mail return address
-is correctly set in your postings.  This allows people to respond directly
-to you, rather than the entire newsgroup, for answers that are not of
-general interest.  A bad e-mail return address may prevent you from
-getting answers to your questions.  You may have to reconfigure your news
-reading software to ensure that it is supplying valid e-mail addresses.
+There is a network 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 contributed archive
 --------------------------
@@ -270,112 +125,84 @@ reading software to ensure that it is supplying valid e-mail addresses.
 Many people have created exciting packages and applications based on Tcl
 and/or Tk and made them freely available to the Tcl community.  An archive
 of these contributions is kept on the machine ftp.neosoft.com.  You
-can access the archive using anonymous FTP;  the Tcl contributed archive is
+can access the archive using anonymous FTP; the Tcl contributed archive is
 in the directory "/pub/tcl".  The archive also contains several FAQ
 ("frequently asked questions") documents that provide solutions to problems
 that are commonly encountered by TCL newcomers.

-7. Mailing lists
+7. Tcl Resource Center
+----------------------
+
+Visit http://www.scriptics.com/resource/ to see an annotated index of
+many Tcl resources available on the World Wide Web.  This includes
+papers, books, and FAQs, as well as development tools, extensions,
+applications, binary releases, and patches.  You can also recommend
+additional URLs for the resource center using the forms labeled "Add a
+Resource".
+
+8. Mailing lists
 ----------------

 A couple of  Mailing List have been set up to discuss Macintosh or
-Windows related Tcl issues.  In order to use these Mailing Lists you
-must have access to the internet.  If you have access to the WWW the
-home pages for these mailing lists are located at the following URLs:
-
-	http://www.sunlabs.com/research/tcl/lists/mactcl-list.html
-
-		-and-
-
-	http://www.sunlabs.com/research/tcl/lists/wintcl-list.html
-
-The home pages contain information about the lists and an HTML archive
-of all the past messages on the list.  To subscribe send a message to:
+Windows related Tcl issues.  To subscribe send a message to:
 	
-	listserv@sunlabs.sun.com
+	wintcl-request@tclconsortium.org
+	mactcl-request@tclconsortium.org
 	
 In the body of the message (the subject will be ignored) put:
 	
-	subscribe mactcl Joe Blow
+	subscribe mactcl Joe Smith
 	
-Replacing Joe Blow with your real name, of course.  (Use wintcl
-instead of mactcl if your interested in the Windows list.)  If you
+Replace Joe Smith with your real name, of course.  (Use wintcl
+instead of mactcl if you're interested in the Windows list.)  If you
 would just like to receive more information about the list without
 subscribing put the line:

 	information mactcl
 	
-in the body instead (or wintcl).
+(or wintcl) in the body instead.

-8. Support and bug fixes
+9. Support and Training
 ------------------------

-We're very interested in receiving bug reports and suggestions for
-improvements.  We prefer that you send this information to the
-comp.lang.tcl newsgroup rather than to any of us at Sun.  We'll see
-anything on comp.lang.tcl, and in addition someone else who reads 
-comp.lang.tcl may be able to offer a solution.  The normal turn-around
-time for bugs is 3-6 weeks.  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 turns into a kitchen sink).  It's
-very difficult to make incompatible changes to Tcl at this point, due
-to the size of the installed base.
+Scriptics is very interested in receiving bug reports, patches, and
+suggestions for improvements.  We prefer that you send this
+information to us via the bug form on the Scriptics Web site, rather
+than emailing us directly.  The bug form is at:

-When reporting bugs, please provide a short tclsh script that we can
-use to reproduce the bug.  Make sure that the script runs with a
-bare-bones tclsh and doesn't depend on any extensions or other
-programs, particularly those that exist only at your site.  Also,
-please include three additional pieces of information with the
-script:
-    (a) how do we use the script to make the problem happen (e.g.
-	what things do we click on, in what order)?
-    (b) what happens when you do these things (presumably this is
-        undesirable)?
-    (c) what did you expect to happen instead?
+	http://www.scriptics.com/support/bugForm.html
+
+The bug form was designed to give uniform structure to bug reports as
+well as to solicit enough information to minimize followup questions.
+The bug form also includes an option to automatically post your report
+on comp.lang.tcl.  We strongly recommend that you select this option
+because someone else who reads comp.lang.tcl may be able to offer a
+solution.
+
+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, Tcl support and training are available commercially from
-NeoSoft (info@neosoft.com), Computerized Processes Unlimited
-(gwl@cpu.com), and Data Kinetics (education@dkl.com).
+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, Tcl/Tk support and training are available
+commercially from Scriptics at:

-9. Tcl version numbers
----------------------
+	http://www.scriptics.com/training

-Each Tcl release is identified by two numbers separated by a dot, e.g.
-6.7 or 7.0.  If a new release contains changes that are likely to break
-existing C code or Tcl scripts then the major release number increments
-and the minor number resets to zero: 6.0, 7.0, etc.  If a new release
-contains only bug fixes and compatible changes, then the minor number
-increments without changing the major number, e.g. 7.1, 7.2, etc.  If
-you have C code or Tcl scripts that work with release X.Y, then they
-should also work with any release X.Z as long as Z > Y.
+Also see the following Web site for links to other organizations that
+offer Tcl/Tk training:

-Alpha and beta releases have an additional suffix of the form a2 or b1.
-For example, Tcl 7.0b1 is the first beta release of Tcl version 7.0,
-Tcl 7.0b2 is the second beta release, and so on.  A beta release is an
-initial version of a new release, used to fix bugs and bad features before
-declaring the release stable.  An alpha release is like a beta release,
-except it's likely to need even more work before it's "ready for prime
-time".  New releases are normally preceded by one or more alpha and beta
-releases.  We hope that lots of people will try out the alpha and beta
-releases and report problems.  We'll make new alpha/beta releases to fix
-the problems, until eventually there is a beta release that appears to
-be stable.  Once this occurs we'll make the final release.
+	http://www.scriptics.com/resource/commercial/training

-We can't promise to maintain compatibility among alpha and beta releases.
-For example, release 7.1b2 may not be backward compatible with 7.1b1, even
-though the final 7.1 release will be backward compatible with 7.0.  This
-allows us to change new features as we find problems during beta testing.
-We'll try to minimize incompatibilities between beta releases, but if
-a major problem turns up then we'll fix it even if it introduces an
-incompatibility.  Once the official release is made then there won't
-be any more incompatibilities until the next release with a new major
-version number.
+10. Thank You
+-------------

-Patch releases have a suffix such as p1 or p2.  These releases contain
-bug fixes only.  A patch release (e.g Tcl 7.6p2) should be completely
-compatible with the base release from which it is derived (e.g. Tcl
-7.6), and you should normally use the highest available patch release.
+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.
@@ -5,4 +5,4 @@ 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.

-sccsid = SCCS: @(#) README 1.3 96/02/16 08:56:51
+RCS: @(#) $Id: README,v 1.2 1998/09/14 18:39:44 stanton Exp $
@@ -10,7 +10,7 @@
 * See the file "license.terms" for information on usage and redistribution
 * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 *
- * SCCS: @(#) dirent.h 1.4 96/02/15 14:43:50
+ * RCS: @(#) $Id: dirent.h,v 1.2 1998/09/14 18:39:44 stanton Exp $
 */

 #ifndef _DIRENT
@@ -10,7 +10,7 @@
 * See the file "license.terms" for information on usage and redistribution
 * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 *
- * SCCS: @(#) dirent2.h 1.4 96/02/15 14:43:51
+ * RCS: @(#) $Id: dirent2.h,v 1.2 1998/09/14 18:39:44 stanton Exp $
 */

 #ifndef _DIRENT
@@ -17,7 +17,7 @@
 *	for any results of using the software, alterations are clearly marked
 *	as such, and this notice is not modified.
 *
- * SCCS: @(#) dlfcn.h 1.4 96/09/17 09:05:59
+ * RCS: @(#) $Id: dlfcn.h,v 1.2 1998/09/14 18:39:44 stanton Exp $
 */

 /*
@@ -10,7 +10,7 @@
 * See the file "license.terms" for information on usage and redistribution
 * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 *
- * SCCS: @(#) fixstrtod.c 1.5 96/02/15 12:08:21
+ * RCS: @(#) $Id: fixstrtod.c,v 1.2 1998/09/14 18:39:44 stanton Exp $
 */

 #include <stdio.h>
@@ -12,5 +12,5 @@
 * See the file "license.terms" for information on usage and redistribution
 * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 *
- * SCCS: @(#) float.h 1.3 96/02/15 14:43:52
+ * RCS: @(#) $Id: float.h,v 1.2 1998/09/14 18:39:44 stanton Exp $
 */
@@ -9,7 +9,7 @@
 * See the file "license.terms" for information on usage and redistribution
 * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 *
- * SCCS: @(#) gettod.c 1.2 96/02/15 12:08:26
+ * RCS: @(#) $Id: gettod.c,v 1.2 1998/09/14 18:39:44 stanton Exp $
 */

 #include "tcl.h"
@@ -13,7 +13,7 @@
 * See the file "license.terms" for information on usage and redistribution
 * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 *
- * SCCS: @(#) limits.h 1.8 96/07/08 18:00:13
+ * RCS: @(#) $Id: limits.h,v 1.2 1998/09/14 18:39:44 stanton Exp $
 */

 #define LONG_MIN		0x80000000
@@ -0,0 +1,61 @@
+/* 
+ * 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.
+ *
+ * SCCS: @(#) memcmp.c 1.2 98/01/19 10:48:58
+ */
+
+#include "tcl.h"
+#include "tclPort.h"
+
+/*
+ * Here is the prototype just in case it is not included
+ * in tclPort.h.
+ */
+
+int		memcmp _ANSI_ARGS_((CONST VOID *s1,
+			    CONST VOID *s2, size_t n));
+
+/*
+ *----------------------------------------------------------------------
+ *
+ * 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, accord-
+ *     ing as s1 is less  than,  equal  to,  or
+ *     greater than s2 when taken to be unsigned 8 bit numbers.
+ *
+ * Side effects:
+ *	None.
+ *
+ *----------------------------------------------------------------------
+ */
+
+int
+memcmp(s1, s2, n)
+    CONST VOID *s1;			/* First string. */
+    CONST VOID *s2;			/* Second string. */
+    size_t      n;                      /* Length to compare. */
+{
+    unsigned char u1, u2;
+
+    for ( ; n-- ; s1++, s2++) {
+	u1 = * (unsigned char *) s1;
+	u2 = * (unsigned char *) s2;
+	if ( u1 != u2) {
+	    return (u1-u2);
+	}
+    }
+    return 0;
+}
@@ -7,7 +7,7 @@
 *	originally from Larry Wall.
 *
 *
- * SCCS: @(#) opendir.c 1.3 96/02/15 12:08:21
+ * RCS: @(#) $Id: opendir.c,v 1.2 1998/09/14 18:39:44 stanton Exp $
 */

 #include "tclInt.h"
@@ -9,12 +9,12 @@
 *	declare all the procedures needed here (such as strtod).
 *
 * Copyright (c) 1991 The Regents of the University of California.
- * Copyright (c) 1994 Sun Microsystems, Inc.
+ * 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.
 *
- * SCCS: @(#) stdlib.h 1.10 96/02/15 14:43:54
+ * RCS: @(#) $Id: stdlib.h,v 1.3 1999/04/16 00:46:30 stanton Exp $
 */

 #ifndef _STDLIB
@@ -8,7 +8,7 @@
 * source.  See the copyright notice below for details on redistribution
 * restrictions.  The "license.terms" file does not apply to this file.
 *
- * SCCS: @(#) strftime.c 1.4 97/08/07 17:17:02
+ * RCS: @(#) $Id: strftime.c,v 1.7 2000/01/15 01:50:43 hobbs Exp $
 */

 /*
@@ -44,10 +44,9 @@
 * SUCH DAMAGE.
 */

-#if defined(LIBC_SCCS) && !defined(lint)
-/*static char *sccsid = "from: @(#)strftime.c	5.11 (Berkeley) 2/24/91";*/
-static char *rcsid = "$Id: strftime.c,v 1.1 1998/03/26 14:46:31 rjohnson Exp $";
-#endif /* LIBC_SCCS and not lint */
+#if defined(LIBC_SCCS)
+static char *rcsid = "$Id: strftime.c,v 1.7 2000/01/15 01:50:43 hobbs Exp $";
+#endif /* LIBC_SCCS */

 #include <time.h>
 #include <string.h>
@@ -56,6 +55,7 @@ static char *rcsid = "$Id: strftime.c,v 1.1 1998/03/26 14:46:31 rjohnson Exp $";
 #include "tclPort.h"

 #define TM_YEAR_BASE   1900
+#define IsLeapYear(x)   ((x % 4 == 0) && (x % 100 != 0 || x % 400 == 0))

 typedef struct {
    const char *abday[7];
@@ -106,12 +106,22 @@ static size_t		_fmt _ANSI_ARGS_((const char *format,
 			    const struct tm *t));

 size_t
-TclStrftime(s, maxsize, format, t)
+TclpStrftime(s, maxsize, format, t)
    char *s;
    size_t maxsize;
    const char *format;
    const struct tm *t;
 {
+    if (format[0] == '%' && format[1] == 'Q') {
+	/* Format as a stardate */
+	sprintf(s, "Stardate %2d%03d.%01d",
+		(((t->tm_year + TM_YEAR_BASE) + 377) - 2323),
+		(((t->tm_yday + 1) * 1000) /
+			(365 + IsLeapYear((t->tm_year + TM_YEAR_BASE)))),
+		(((t->tm_hour * 60) + t->tm_min)/144));
+	return(strlen(s));
+    }
+
    tzset();

    pt = s;
@@ -316,7 +326,7 @@ _fmt(format, t)
 		    continue;
 #ifndef MAC_TCL
 		case 'Z': {
-		    char *name = TclpGetTZName();
+		    char *name = TclpGetTZName(t->tm_isdst);
 		    if (name && !_add(name)) {
 			return 0;
 		    }
@@ -9,7 +9,7 @@
 * See the file "license.terms" for information on usage and redistribution
 * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 *
- * SCCS: @(#) string.h 1.13 96/04/09 22:14:53
+ * RCS: @(#) $Id: string.h,v 1.3 1999/04/16 00:46:30 stanton Exp $
 */

 #ifndef _STRING
@@ -32,8 +32,12 @@ extern char *		memchr _ANSI_ARGS_((CONST VOID *s, int c, size_t n));
 extern int		memcmp _ANSI_ARGS_((CONST VOID *s1, CONST VOID *s2,
 			    size_t n));
 extern char *		memcpy _ANSI_ARGS_((VOID *t, CONST VOID *f, size_t n));
+#ifdef NO_MEMMOVE
+#define memmove(d, s, n) bcopy ((s), (d), (n))
+#else
 extern char *		memmove _ANSI_ARGS_((VOID *t, CONST VOID *f,
 			    size_t n));
+#endif
 extern char *		memset _ANSI_ARGS_((VOID *s, int c, size_t n));

 extern int		strcasecmp _ANSI_ARGS_((CONST char *s1,
@@ -9,7 +9,7 @@
 * See the file "license.terms" for information on usage and redistribution
 * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 *
- * SCCS: @(#) strncasecmp.c 1.7 96/10/24 15:23:36
+ * RCS: @(#) $Id: strncasecmp.c,v 1.2 1998/09/14 18:39:45 stanton Exp $
 */

 #include "tclPort.h"
@@ -9,7 +9,7 @@
 * See the file "license.terms" for information on usage and redistribution
 * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 *
- * SCCS: @(#) strstr.c 1.4 96/02/15 12:08:22
+ * RCS: @(#) $Id: strstr.c,v 1.2 1998/09/14 18:39:45 stanton Exp $
 */

 /*
@@ -9,7 +9,7 @@
 * See the file "license.terms" for information on usage and redistribution
 * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 *
- * SCCS: @(#) strtod.c 1.9 96/12/13 15:02:46
+ * RCS: @(#) $Id: strtod.c,v 1.2 1998/09/14 18:39:45 stanton Exp $
 */

 #include "tcl.h"
@@ -9,7 +9,7 @@
 * See the file "license.terms" for information on usage and redistribution
 * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 *
- * SCCS: @(#) strtol.c 1.4 96/02/15 12:08:23
+ * RCS: @(#) $Id: strtol.c,v 1.2 1998/09/14 18:39:45 stanton Exp $
 */

 #include <ctype.h>
@@ -9,7 +9,7 @@
 * See the file "license.terms" for information on usage and redistribution
 * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 *
- * SCCS: @(#) strtoul.c 1.5 96/02/15 12:08:24
+ * RCS: @(#) $Id: strtoul.c,v 1.2 1998/09/14 18:39:45 stanton Exp $
 */

 #include <ctype.h>
@@ -11,7 +11,7 @@
 * See the file "license.terms" for information on usage and redistribution
 * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 *
- * SCCS: @(#) tclErrno.h 1.1 96/04/29 15:25:31
+ * RCS: @(#) $Id: tclErrno.h,v 1.2 1998/09/14 18:39:45 stanton Exp $
 */

 extern int errno;			/* global error number */
@@ -9,7 +9,7 @@
 * software without specific written prior permission. This software
 * is provided ``as is'' without express or implied warranty.
 *
- * SCCS: @(#) tmpnam.c 1.3 96/02/15 12:08:25
+ * RCS: @(#) $Id: tmpnam.c,v 1.2 1998/09/14 18:39:45 stanton Exp $
 */

 #include <sys/param.h>
@@ -12,7 +12,7 @@
 * software for any purpose.  It is provided "as is" without
 * express or implied warranty.
 *
- * SCCS: @(#) unistd.h 1.7 96/02/15 14:43:57
+ * RCS: @(#) $Id: unistd.h,v 1.2 1998/09/14 18:39:45 stanton Exp $
 */

 #ifndef _UNISTD
@@ -12,12 +12,16 @@
 * See the file "license.terms" for information on usage and redistribution
 * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 *
- * SCCS: @(#) waitpid.c 1.9 96/02/15 12:08:26
+ * RCS: @(#) $Id: waitpid.c,v 1.3 2000/01/11 22:08:50 hobbs Exp $
 */

 #include "tclInt.h"
 #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,
@@ -28,7 +32,7 @@
 */

 typedef struct WaitInfo {
-    int pid;				/* Pid of process that exited. */
+    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. */
@@ -64,9 +68,9 @@ static WaitInfo *deadList = NULL;	/* First in list of all dead
 #   undef waitpid
 #endif

-int
+pid_t
 waitpid(pid, statusPtr, options)
-    int pid;			/* The pid to wait on.  Must be -1 or
+    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. */
@@ -74,7 +78,7 @@ waitpid(pid, statusPtr, options)
 				 * WUNTRACED. */
 {
    register WaitInfo *waitPtr, *prevPtr;
-    int result;
+    pid_t result;
    WAIT_STATUS_TYPE status;

    if ((pid < -1) || (pid == 0)) {
@@ -0,0 +1,71 @@
+'\"
+'\" Copyright (c) 1998-1999 Scriptics Corportation
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+'\" RCS: @(#) $Id: Access.3,v 1.3 1999/05/06 19:14:39 stanton Exp $
+'\" 
+.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 stat *statPtr in
+.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 stat *statPtr out
+The structure that contains the result.
+.BE
+
+.SH DESCRIPTION
+.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 possibity 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),
+priviledge 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
@@ -5,13 +5,13 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) AddErrInfo.3 1.28 97/06/12 13:39:53
+'\" RCS: @(#) $Id: AddErrInfo.3,v 1.3 1999/03/10 05:52:45 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_AddErrorInfo 3 7.5 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_AddObjErrorInfo, Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_PosixError \- record information about errors
+Tcl_AddObjErrorInfo, Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_PosixError \- record information about errors
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -24,6 +24,8 @@ Tcl_AddObjErrorInfo, Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_PosixError \- recor
 .sp
 \fBTcl_SetErrorCode\fR(\fIinterp, element, element, ... \fB(char *) NULL\fR)
 .sp
+\fBTcl_SetErrorCodeVA\fR(\fIinterp, argList\fR)
+.sp
 char *
 \fBTcl_PosixError\fR(\fIinterp\fR)
 .SH ARGUMENTS
@@ -47,6 +49,9 @@ This variable \fBerrorCode\fR will be set to this value.
 .AP char *element in
 String to record as one element of \fBerrorCode\fR variable.
 Last \fIelement\fR argument must be NULL.
+.AP va_list argList in
+An argument list which must have been initialised using
+\fBTCL_VARARGS_START\fR, and cleared using \fBva_end\fR.
 .BE

 .SH DESCRIPTION
@@ -118,6 +123,9 @@ The procedure \fBTcl_SetErrorCode\fR is also used to set the
 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 \fBerrorCode\fR variable after an error in a POSIX kernel call.
 It reads the value of the \fBerrno\fR C variable and calls
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) Alloc.3 1.2 96/06/05 18:00:19
+'\" RCS: @(#) $Id: Alloc.3,v 1.2 1998/09/14 18:39:45 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_Alloc 3 7.5 Tcl "Tcl Library Procedures"
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) AllowExc.3 1.5 96/03/25 19:55:47
+'\" RCS: @(#) $Id: AllowExc.3,v 1.2 1998/09/14 18:39:45 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_AllowExceptions 3 7.4 Tcl "Tcl Library Procedures"
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) AppInit.3 1.10 96/08/26 12:59:40
+'\" RCS: @(#) $Id: AppInit.3,v 1.2 1998/09/14 18:39:46 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_AppInit 3 7.0 Tcl "Tcl Library Procedures"
@@ -5,7 +5,7 @@
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
 '\" 
-'\" SCCS: @(#) AssocData.3 1.8 96/03/25 19:56:17
+'\" RCS: @(#) $Id: AssocData.3,v 1.3 1999/04/16 00:46:30 stanton Exp $
 .so man.macros
 .TH Tcl_SetAssocData 3 7.5 Tcl "Tcl Library Procedures"
 .BS
@@ -84,6 +84,6 @@ 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.  It does not call the deletion procedure.
+the given interpreter.  Then it calls the deletion procedure.
 .SH KEYWORDS
 association, data, deletion procedure, interpreter, key
@@ -5,13 +5,13 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) Async.3 1.14 96/08/26 12:59:41
+'\" RCS: @(#) $Id: Async.3,v 1.3 1999/04/16 00:46:30 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_AsyncCreate 3 7.0 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_AsyncCreate, Tcl_AsyncMark, Tcl_AsyncInvoke, Tcl_AsyncDelete \- handle asynchronous events
+Tcl_AsyncCreate, Tcl_AsyncMark, Tcl_AsyncInvoke, Tcl_AsyncDelete, Tcl_AsyncReady \- handle asynchronous events
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) BackgdErr.3 1.3 96/03/25 19:56:51
+'\" RCS: @(#) $Id: BackgdErr.3,v 1.2 1998/09/14 18:39:46 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_BackgroundError 3 7.5 Tcl "Tcl Library Procedures"
@@ -5,10 +5,10 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) Backslash.3 1.16 96/03/25 19:57:09
+'\" RCS: @(#) $Id: Backslash.3,v 1.3 1999/04/16 00:46:30 stanton Exp $
 '\" 
 .so man.macros
-.TH Tcl_Backslash 3 "" Tcl "Tcl Library Procedures"
+.TH Tcl_Backslash 3 "8.1" Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
 Tcl_Backslash \- parse a backslash sequence
@@ -30,16 +30,24 @@ the backslash character.

 .SH DESCRIPTION
 .PP
-This is a utility procedure used by several of the Tcl
-commands.  It parses a backslash sequence and returns
-the single character corresponding to the sequence.
-\fBTcl_Backslash\fR modifies \fI*countPtr\fR to contain the number
-of characters in the backslash sequence.
+.VS 8.1
+The use of \fBTcl_Backslash\fR is deprecated in favor of
+\fBTcl_UtfBackslash\fR.
 .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.
+This is a utility procedure provided for backwards compatibilty with
+non-internationalized Tcl extensions.  It parses a backslash sequence and
+returns the low byte of the Unicode character corresponding to the sequence. 
+.VE
+\fBTcl_Backslash\fR modifies \fI*countPtr\fR to contain the number of
+characters in the backslash sequence.
+.PP
+See the Tcl manual entry for information on the valid backslash sequences.
+All of the sequences described in the Tcl manual entry are supported by
+\fBTcl_Backslash\fR.
+.VS 8.1 br
+.SH "SEE ALSO"
+Tcl(n), Tcl_UtfBackslash(3)
+.VE

 .SH KEYWORDS
 backslash, parse
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) @(#) BoolObj.3 1.7 97/05/08 19:50:57
+'\" RCS: @(#) $Id: BoolObj.3,v 1.2 1998/09/14 18:39:46 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_BooleanObj 3 8.0 Tcl "Tcl Library Procedures"
@@ -0,0 +1,91 @@
+'\"
+'\" 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.
+'\" 
+'\" RCS: @(#) $Id: ByteArrObj.3,v 1.2 1999/03/03 00:38:36 stanton Exp $
+'\" 
+.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 "unsigned char" *lengthPtr in/out
+.AP "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.
+Accesser 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
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) CallDel.3 1.11 96/03/25 19:57:25
+'\" RCS: @(#) $Id: CallDel.3,v 1.2 1998/09/14 18:39:46 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_CallWhenDeleted 3 7.0 Tcl "Tcl Library Procedures"
@@ -0,0 +1,102 @@
+'\"
+'\" Copyright (c) 1999 Scriptics Corporation
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+'\" RCS: @(#) $Id: ChnlStack.3,v 1.1 1999/07/02 19:51:14 welch Exp $
+.so man.macros
+.TH Tcl_StackChannel 3 8.2 Tcl "Tcl Library Procedures"
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+Tcl_StackChannel, Tcl_UnstackChannel \- stack an I/O channel on top of another, and undo it
+.SH SYNOPSIS
+.nf
+.nf
+\fB#include <tcl.h>\fR
+.sp
+Tcl_Channel
+\fBTcl_StackChannel\fR(\fIinterp, typePtr, clientData, mask, channel\fR)
+.sp
+void
+\fBTcl_UnstackChannel\fR(\fIinterp, channel\fR)
+.sp
+Tcl_Channel
+\fBTcl_GetStackedChannel\fR(\fIchannel\fR)
+.sp
+.SH ARGUMENTS
+.AS Tcl_ChannelType
+.AP Tcl_Interp *interp in
+Interpreter for error reporting - can be NULL.
+.AP Tcl_ChannelType *typePtr in
+The new channel I/O procedures to use for \fIchannel\fP.
+.AP ClientData clientData in
+Arbitrary one-word value to pass to channel I/O procedures.
+.AP int mask in
+Conditions under which \fIchannel\fR will be used: OR-ed combination of
+\fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR and \fBTCL_EXCEPTION\fR.
+This can be a subset of the operations currently allowed on \fIchannel\fP.
+.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
+\fBTcl_StackChannel\fR
+replaces an existing \fIchannel\fP with a new channel by
+the same name that was registered for \fIchannel\fP
+with \fBTcl_RegisterChannel\fP.
+.PP
+\fBTcl_StackChannel\fR
+works by creating a new channel structure under the existing
+\fIchannel\fP and pushing the existing channel functions
+down to the newly created channel.
+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.
+The top-most channel gets changed to use the 
+I/O channel functions
+defined in \fItypePtr\fP, and the channel functions are passed
+the new \fIclientData\fP.
+The existing \fIchannel\fP structure is modified in place,
+so C applications that continue to use \fIchannel\fP will
+also see the effects of the new processing module.
+A pointer to a new channel structure is returned,
+although this new data structure is the one that has been
+pushed down below the top of the channel module stack.
+(This pointer can also be obtained with the
+\fBTcl_GetStackedChannel\fP call.)
+If an error occurs when stacking the channel,
+NULL is returned instead. 
+.PP
+The \fImask\fP parameter specifies the operations that
+are allowed on the 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\fP reverses the process.
+The old channel is associated with the channel name,
+and the processing module added by
+\fBTcl_StackChannel\fR is destroyed.
+If there is no old channel, then \fBTcl_UnstackChannel\fP 
+is equivalent to \fBTcl_Close\fP .
+
+.SH "SEE ALSO"
+Notifier(3), Tcl_CreateChannel(3), Tcl_OpenFileChannel(3), vwait(n).
+
+.SH KEYWORDS
+channel, compression
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) CmdCmplt.3 1.6 96/03/25 19:57:46
+'\" RCS: @(#) $Id: CmdCmplt.3,v 1.2 1998/09/14 18:39:46 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_CommandComplete 3 "" Tcl "Tcl Library Procedures"
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) Concat.3 1.12 97/06/11 17:54:12
+'\" RCS: @(#) $Id: Concat.3,v 1.2 1998/09/14 18:39:46 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_Concat 3 7.5 Tcl "Tcl Library Procedures"
@@ -4,13 +4,13 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-'\" SCCS: @(#) CrtChannel.3 1.29 97/06/20 13:37:45
+'\" RCS: @(#) $Id: CrtChannel.3,v 1.4 1999/08/21 19:40:47 hobbs Exp $
 .so man.macros
 .TH Tcl_CreateChannel 3 8.0 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_SetDefaultTranslation, Tcl_SetChannelBufferSize, Tcl_NotifyChannel, Tcl_BadChannelOption \- procedures for creating and manipulating channels
+Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType, Tcl_GetChannelName, Tcl_GetChannelHandle, Tcl_GetChannelMode, Tcl_GetChannelBufferSize, Tcl_SetChannelBufferSize, Tcl_NotifyChannel, Tcl_BadChannelOption \- procedures for creating and manipulating channels
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -33,11 +33,6 @@ int
 .VE
 .sp
 int
-\fBTcl_GetChannelFlags\fR(\fIchannel\fR)
-.sp
-\fBTcl_SetDefaultTranslation\fR(\fIchannel, transMode\fR)
-.sp
-int
 \fBTcl_GetChannelBufferSize\fR(\fIchannel\fR)
 .sp
 \fBTcl_SetChannelBufferSize\fR(\fIchannel, size\fR)
@@ -170,13 +165,7 @@ for each driver to determine what type of handle is returned.
 and \fBTCL_WRITABLE\fR, indicating whether the channel is open for input
 and output.
 .PP
-\fBTcl_SetDefaultTranslation\fR sets the default end of line translation
-mode. This mode will be installed as the translation mode for the channel
-if an attempt is made to output on the channel while it is still in
-\fBTCL_TRANSLATE_AUTO\fR mode. For a description of end of line translation
-modes, see the manual entry for \fBfconfigure\fR.
-.PP
-\fBTcl_GetChannelBufferSize\fR returns the size, in bytes, of buffers
+ \fBTcl_GetChannelBufferSize\fR returns the size, in bytes, of buffers
 allocated to store input or output in \fIchan\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.
@@ -221,16 +210,19 @@ typedef struct Tcl_ChannelType {
 	Tcl_DriverGetOptionProc *\fIgetOptionProc\fR;
 	Tcl_DriverWatchProc *\fIwatchProc\fR;
 	Tcl_DriverGetHandleProc *\fIgetHandleProc\fR;
+	Tcl_DriverClose2Proc *\fIclose2Proc\fR;
 } Tcl_ChannelType;
 .CE
 .VE
 .PP
 The driver must provide implementations for all functions except
-\fIblockModeProc\fR, \fIseekProc\fR, \fIsetOptionProc\fR, and
-\fIgetOptionProc\fR, which may be specified as NULL to indicate that the
-channel does not support seeking.  Other functions that can not be
-implemented for this type of device should return \fBEINVAL\fR when invoked
-to indicate that they are not implemented.
+\fIblockModeProc\fR, \fIseekProc\fR, \fIsetOptionProc\fR,
+.VS
+\fIgetOptionProc\fR, and \fIclose2Proc\fR, which may be specified as
+.VE
+NULL.  Other functions that can not be implemented for this type of
+device should return \fBEINVAL\fR when invoked to indicate that they
+are not implemented.

 .SH TYPENAME
 .PP
@@ -264,7 +256,7 @@ 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.

-.SH CLOSEPROC
+.SH "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
@@ -286,6 +278,35 @@ 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 \fIinterp->result\fR.
+.PP
+.VS
+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 \fIinterp->result\fR.
+.VE

 .SH INPUTPROC
 .PP
@@ -382,7 +403,7 @@ typedef int Tcl_DriverSeekProc(
 .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_SeekChannel\fR
+\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
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-'\" SCCS: @(#) CrtChnlHdlr.3 1.10 96/03/14 10:54:43
+'\" RCS: @(#) $Id: CrtChnlHdlr.3,v 1.2 1998/09/14 18:39:46 stanton Exp $
 .so man.macros
 .TH Tcl_CreateChannelHandler 3 7.5 Tcl "Tcl Library Procedures"
 .BS
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-'\" SCCS: @(#) CrtCloseHdlr.3 1.7 96/04/15 13:08:19
+'\" RCS: @(#) $Id: CrtCloseHdlr.3,v 1.2 1998/09/14 18:39:47 stanton Exp $
 .so man.macros
 .TH Tcl_CreateCloseHandler 3 7.5 Tcl "Tcl Library Procedures"
 .BS
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) CrtCommand.3 1.29 97/06/04 17:23:53
+'\" RCS: @(#) $Id: CrtCommand.3,v 1.3 1998/10/05 17:35:53 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_CreateCommand 3 "" Tcl "Tcl Library Procedures"
@@ -94,7 +94,12 @@ 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.
+last value is NULL.  
+.VS
+Note that the argument strings should not be modified as they may
+point to constant strings or may be shared with other parts of the
+interpreter.
+.VE
 .PP
 \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
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) CrtFileHdlr.3 1.7 97/04/23 16:11:17
+'\" RCS: @(#) $Id: CrtFileHdlr.3,v 1.2 1998/09/14 18:39:47 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_CreateFileHandler 3 8.0 Tcl "Tcl Library Procedures"
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) CrtInterp.3 1.17 97/10/31 13:05:51
+'\" RCS: @(#) $Id: CrtInterp.3,v 1.4 1999/08/21 19:40:47 hobbs Exp $
 '\" 
 .so man.macros
 .TH Tcl_CreateInterp 3 7.5 Tcl "Tcl Library Procedures"
@@ -36,7 +36,7 @@ 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 Tcl_Interp
+Tcl_Interp structures;  see the \fBTcl_Interp\fR
 and \fBTcl_CreateCommand\fR man pages for details.
 The new interpreter is initialized with no defined variables and only
 the built-in Tcl commands.  To bind in additional commands, call
@@ -124,8 +124,8 @@ 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 KEYWORDS
-command, create, delete, interpreter
-
 .SH "SEE ALSO"
 Tcl_Preserve(3), Tcl_Release(3)
+
+.SH KEYWORDS
+command, create, delete, interpreter
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) CrtMathFnc.3 1.9 96/08/26 12:59:43
+'\" RCS: @(#) $Id: CrtMathFnc.3,v 1.2 1998/09/14 18:39:47 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_CreateMathFunc 3 7.0 Tcl "Tcl Library Procedures"
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) @(#) CrtObjCmd.3 1.10 97/07/31 14:10:38
+'\" RCS: @(#) $Id: CrtObjCmd.3,v 1.3 1999/04/16 00:46:30 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_CreateObjCommand 3 8.0 Tcl "Tcl Library Procedures"
@@ -62,8 +62,10 @@ such that whenever \fIname\fR is
 invoked as a Tcl command (e.g., via a call to \fBTcl_EvalObj\fR)
 the Tcl interpreter will call \fIproc\fR to process the command.
 .PP
-\fBTcl_CreateObjCommand\fR will delete any command \fIname\fR
-already associated with the interpreter.
+\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,
@@ -101,7 +103,7 @@ cause memory to be lost and the runtime stack to be corrupted.  The
 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_GetIntFromObject\fR on \fIobjv\fR[\fB2\fR] to obtain the integer
+\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.
@@ -128,6 +130,17 @@ 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,
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) CrtSlave.3 1.26 97/07/31 18:00:14
+'\" RCS: @(#) $Id: CrtSlave.3,v 1.3 1999/08/21 19:40:47 hobbs Exp $
 '\" 
 .so man.macros
 .TH Tcl_CreateSlave 3 7.6 Tcl "Tcl Library Procedures"
@@ -170,7 +170,7 @@ 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_CreateAliasObj\fR except 
+\fBTcl_CreateAliasObj\fR is similar to \fBTcl_CreateAlias\fR except 
 that it takes a vector of objects to pass as additional arguments instead
 of a vector of strings.
 .VE
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) CrtTimerHdlr.3 1.4 96/09/17 10:54:58
+'\" RCS: @(#) $Id: CrtTimerHdlr.3,v 1.2 1998/09/14 18:39:47 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_CreateTimerHandler 3 7.5 Tcl "Tcl Library Procedures"
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) CrtTrace.3 1.14 96/03/25 20:01:10
+'\" RCS: @(#) $Id: CrtTrace.3,v 1.2 1998/09/14 18:39:47 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_CreateTrace 3 "" Tcl "Tcl Library Procedures"
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) DString.3 1.20 96/08/26 12:59:44
+'\" RCS: @(#) $Id: DString.3,v 1.4 1999/04/21 21:50:22 rjohnson Exp $
 '\" 
 .so man.macros
 .TH Tcl_DString 3 7.4 Tcl "Tcl Library Procedures"
@@ -36,6 +36,8 @@ char *
 .sp
 \fBTcl_DStringSetLength\fR(\fIdsPtr, newLength\fR)
 .sp
+\fBTcl_DStringTrunc\fR(\fIdsPtr, newLength\fR)
+.sp
 \fBTcl_DStringFree\fR(\fIdsPtr\fR)
 .sp
 \fBTcl_DStringResult\fR(\fIinterp, dsPtr\fR)
@@ -124,6 +126,10 @@ caller to fill in the new space.
 even if the string is truncated to zero length, so \fBTcl_DStringFree\fR
 will still need to be called.
 .PP
+\fBTcl_DStringTrunc\fR changes the length of a dynamic string.
+This procedure is now deprecated.  \fBTcl_DStringSetLength\fR  should
+be used instead.
+.PP
 \fBTcl_DStringFree\fR should be called when you're 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.
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) DetachPids.3 1.15 96/08/26 12:59:44
+'\" RCS: @(#) $Id: DetachPids.3,v 1.2 1998/09/14 18:39:48 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_DetachPids 3 "" Tcl "Tcl Library Procedures"
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) DoOneEvent.3 1.6 97/05/09 18:12:05
+'\" RCS: @(#) $Id: DoOneEvent.3,v 1.2 1998/09/14 18:39:48 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_DoOneEvent 3 7.5 Tcl "Tcl Library Procedures"
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) DoWhenIdle.3 1.6 97/05/09 18:18:33
+'\" RCS: @(#) $Id: DoWhenIdle.3,v 1.2 1998/09/14 18:39:48 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_DoWhenIdle 3 7.5 Tcl "Tcl Library Procedures"
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) @(#) DoubleObj.3 1.6 97/05/08 19:50:07
+'\" RCS: @(#) $Id: DoubleObj.3,v 1.2 1998/09/14 18:39:48 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_DoubleObj 3 8.0 Tcl "Tcl Library Procedures"
@@ -0,0 +1,522 @@
+'\"
+'\" 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.
+'\" 
+'\" RCS: @(#) $Id: Encoding.3,v 1.7 1999/10/13 00:32:05 hobbs Exp $
+'\" 
+.so man.macros
+.TH Tcl_GetEncoding 3 "8.1" Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_GetEncoding, Tcl_FreeEncoding, Tcl_ExternalToUtfDString, Tcl_ExternalToUtf, Tcl_UtfToExternalDString, Tcl_UtfToExternal, Tcl_WinTCharToUtf, Tcl_WinUtfToTChar, Tcl_GetEncodingName, Tcl_SetSystemEncoding, Tcl_GetEncodingNames, Tcl_CreateEncoding, Tcl_GetDefaultEncodingDir, Tcl_SetDefaultEncodingDir \- procedures for creating and using encodings.
+.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
+char *
+\fBTcl_ExternalToUtfDString\fR(\fIencoding, src, srcLen, dstPtr\fR)
+.sp
+int
+\fBTcl_ExternalToUtf\fR(\fIinterp, encoding, src, srcLen, flags, statePtr, dst, dstLen, srcReadPtr, dstWrotePtr, 
+	dstCharsPtr\fR)
+.sp
+char * 
+\fBTcl_UtfToExternalDString\fR(\fIencoding, src, srcLen, dstPtr\fR)
+.sp
+int
+\fBTcl_UtfToExternal\fR(\fIinterp, encoding, src, srcLen, flags, statePtr, dst, dstLen, srcReadPtr, dstWrotePtr, 
+	dstCharsPtr\fR)
+.sp
+char *
+\fBTcl_WinTCharToUtf\fR(\fItsrc, srcLen, dstPtr\fR)
+.sp
+TCHAR *
+\fBTcl_WinUtfToTChar\fR(\fIsrc, srcLen, dstPtr\fR)
+.sp
+char *
+\fBTcl_GetEncodingName\fR(\fIencoding\fR)
+.sp
+int
+\fBTcl_SetSystemEncoding\fR(\fIinterp, name\fR)
+.sp
+void
+\fBTcl_GetEncodingNames\fR(\fIinterp\fR)
+.sp
+Tcl_Encoding
+\fBTcl_CreateEncoding\fR(\fItypePtr\fR)
+.sp
+char *
+\fBTcl_GetDefaultEncodingDir\fR(\fIvoid\fR)
+.sp
+void
+\fBTcl_SetDefaultEncodingDir\fR(\fIpath\fR)
+
+
+.SH ARGUMENTS
+.AS Tcl_EncodingState *dstWrotePtr
+.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 "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.  
+TCL_ENCODING_START signifies that the
+source buffer is the first block in a (potentially multi-block) input
+stream, telling the conversion routine to reset to an initial state and
+perform any initialization that needs to occur before the first byte is
+converted.  TCL_ENCODING_END signifies that the source buffer is the last
+block in a (potentially multi-block) input stream, telling the conversion
+routine to perform any finalization that needs to occur after the last
+byte is converted and then to reset to an initial state.
+TCL_ENCODING_STOPONERROR signifies that the conversion routine should
+return immediately upon reading a source character that doesn't exist in
+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_EncodingType *typePtr in
+Structure that defines a new type of encoding.  
+.AP 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 builtin 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
+\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 fews 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 TCL_ENCODING_STOPONERROR 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 Macintosh and Unix operating systems),
+all strings exchanged between Tcl and the operating system are "char"
+based.  On Windows NT, some strings exchanged between Tcl and the
+operating system are "char" oriented while others are in Unicode.  By
+convention, in Windows a TCHAR is a character in the ANSI code page
+on Windows 95 and a Unicode character on Windows NT.
+.PP
+If you planned to use the same "char" based interfaces on both Windows
+95 and Windows NT, you could use \fBTcl_UtfToExternal\fR and
+\fBTcl_ExternalToUtf\fR (or their \fBTcl_DString\fR equivalents) with an
+encoding of NULL (the current system encoding).  On the other hand,
+if you planned to use the Unicode interface when running on Windows NT
+and the "char" interfaces when running on Windows 95, you would have
+to perform the following type of test over and over in your program
+(as represented in psuedo-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, TCL_ERROR is
+returned and an error message is left in \fIinterp\fR.  Otherwise, this
+procedure increments the reference count of the new system encoding,
+decrements the reference count of the old system encoding, and returns
+TCL_OK.
+.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_Encoding *\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
+
+\fBTcl_GetDefaultEncodingDir\fR and \fBTcl_SetDefaultEncodingDir\fR
+access and set the directory to use when locating the default encoding
+files.  If this value is not NULL, the \fBTclpInitLibraryPath\fR routine
+appends the path to the head of the search path, and uses this path as
+the first place to look into when trying to locate the encoding file.
+
+.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 ``#'' 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 a 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 doesn't 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	\\x1b(B
+jis0201		\\x1b(J
+jis0208		\\x1b$@
+jis0208		\\x1b$B
+jis0212		\\x1b$(D
+gb2312		\\x1b$A
+ksc5601		\\x1b$(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, ``\fB{}\fR'' represents the empty string and
+``\fB\\x1b\fR'' represents character 27.
+.PP
+When \fBTcl_GetEncoding\fR encounters an encoding \fIname\fR that has not
+been loaded, it attempts to load an encoding file called \fIname\fB.enc\fR
+from the \fBencoding\fR subdirectory of each directory specified in the
+library path \fB$tcl_libPath\fR.  If the encoding file exists, but is
+malformed, an error message will be left in \fIinterp\fR.
+.SH KEYWORDS
+utf, encoding, convert
+
+
+
@@ -5,88 +5,173 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) Eval.3 1.21 97/01/22 14:22:03
+'\" RCS: @(#) $Id: Eval.3,v 1.5 1999/08/19 02:58:34 hobbs Exp $
 '\" 
 .so man.macros
-.TH Tcl_Eval 3 7.0 Tcl "Tcl Library Procedures"
+.TH Tcl_Eval 3 8.1 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_Eval, Tcl_VarEval, Tcl_EvalFile, Tcl_GlobalEval \- execute Tcl commands
+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
+.VS
 int
-\fBTcl_Eval\fR(\fIinterp, cmd\fR)
-.sp
-int
-\fBTcl_VarEval\fR(\fIinterp, string, string, ... \fB(char *) NULL\fR)
+\fBTcl_EvalObjEx\fR(\fIinterp, objPtr, flags\fR)
 .sp
 int
 \fBTcl_EvalFile\fR(\fIinterp, fileName\fR)
 .sp
 int
-\fBTcl_GlobalEval\fR(\fIinterp, cmd\fR)
+\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, flags\fR)
+.sp
+int
+\fBTcl_VarEval\fR(\fIinterp, string, string, ... \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 command.
-A string result will be stored in \fIinterp->result\fR.
-.AP char *cmd in
-Command (or sequence of commands) to execute.  Must be in writable
-memory (\fBTcl_Eval\fR makes temporary modifications to the command).
-.AP char *string in
-String forming part of Tcl command.
+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 char *fileName in
-Name of file containing Tcl command string.
+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 char *script in
+Points to first byte of script to execute.  This script must be in
+writable memory: temporary modifications are made to it during
+parsing.
+.AP char *string in
+String forming part of a Tcl script.
+.AP va_list argList in
+An argument list which must have been initialised using
+\fBTCL_VARARGS_START\fR, and cleared using \fBva_end\fR.
 .BE

 .SH DESCRIPTION
 .PP
-All four of these procedures execute Tcl commands.
-\fBTcl_Eval\fR is the core procedure and is used by all the others.
-It executes the commands in the script held by \fIcmd\fR
-until either an error occurs or it reaches the end of the script.
+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
-Note that \fBTcl_Eval\fR and \fBTcl_GlobalEval\fR
-have been largely replaced by the
-object-based procedures \fBTcl_EvalObj\fR and \fBTcl_GlobalEvalObj\fR.
-Those object-based procedures evaluate a script held in a Tcl object
-instead of a string.
-The object argument can retain the bytecode instructions for the script
-and so avoid reparsing the script each time it is executed.
-\fBTcl_Eval\fR is implemented using \fBTcl_EvalObj\fR
-but is slower because it must reparse the script each time
-since there is no object to retain the bytecode instructions.
+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.
+In addition, a result value or error message is left in \fIinterp\fR's
+result; it can be retrieved using \fBTcl_GetObjResult\fR.
 .PP
-The return value from \fBTcl_Eval\fR is one of the Tcl return codes
-\fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or
-\fBTCL_CONTINUE\fR, and \fIinterp->result\fR will point to
-a string with additional information (a result value or error message).
-If an error occurs during compilation, this return information
-describes the error.
-Otherwise, this return information corresponds to the last command
-executed from \fIcmd\fR.
+\fBTcl_EvalFile\fR reads the file given by \fIfileName\fR and evaluates
+its contents as a Tcl script.  It returns the same information as
+\fBTcl_EvalObjEx\fR.
+If the file couldn't be read then a Tcl error is returned to describe
+why the file couldn't be read.
+.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.
+.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 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
+where it can be accessed directly.  This makes \fBTcl_Eval\fR somewhat
+slower than \fBTcl_EvalEx\fR, which doesn't 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 usual fashion for Tcl commands.
+\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.
+of arguments.  \fBTcl_VarEval\fR is now deprecated.
 .PP
-\fBTcl_EvalFile\fR reads the file given by \fIfileName\fR and evaluates
-its contents as a Tcl command by calling \fBTcl_Eval\fR.  It returns
-a standard Tcl result that reflects the result of evaluating the file.
-If the file couldn't be read then a Tcl error is returned to describe
-why the file couldn't be read.
+\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 won't be reused in a future execution.  In this case,
+it's 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_Eval\fR invocation,
+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.
@@ -94,21 +179,18 @@ 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_Eval\fR keeps track of how many nested \fBTcl_Eval\fR
+\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_Eval\fR
+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->result\fR
-to point to an error message indicating that
+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_Eval\fR other then \fBTCL_OK\fR or \fBTCL_ERROR\fR.
-
-.SH "SEE ALSO"
-Tcl_EvalObj, Tcl_GlobalEvalObj
+from \fBTcl_EvalObjEx\fR other then \fBTCL_OK\fR or \fBTCL_ERROR\fR.
+.VE

 .SH KEYWORDS
-command, execute, file, global, object, object result, variable
+execute, file, global, object, result, script
@@ -1,91 +0,0 @@
-'\"
-'\" 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.
-'\" 
-'\" SCCS: @(#) EvalObj.3 1.4 97/01/22 15:18:44
-'\" 
-.so man.macros
-.TH Tcl_EvalObj 3 8.0 Tcl "Tcl Library Procedures"
-.BS
-.SH NAME
-Tcl_EvalObj, Tcl_GlobalEvalObj \- execute Tcl commands
-.SH SYNOPSIS
-.nf
-\fB#include <tcl.h>\fR
-.sp
-int
-\fBTcl_EvalObj\fR(\fIinterp, objPtr\fR)
-.sp
-int
-\fBTcl_GlobalEvalObj\fR(\fIinterp, objPtr\fR)
-.SH ARGUMENTS
-.AS Tcl_Interp **termPtr;
-.AP Tcl_Interp *interp in
-Interpreter in which to execute the command.
-The command's result will be stored in the interpreter's result object
-and can be retrieved using \fBTcl_GetObjResult\fR.
-.AP Tcl_Obj *objPtr in
-A Tcl object containing a command string
-(or sequence of commands in a string) to execute.
-.BE
-
-.SH DESCRIPTION
-.PP
-These two procedures execute Tcl commands.
-\fBTcl_EvalObj\fR is the core procedure
-and is used by \fBTcl_GlobalEvalObj\fR.
-It executes the commands in the script held by \fIobjPtr\fR
-until either an error occurs or it reaches the end of the script.
-If this is the first time \fIobjPtr\fR has been executed,
-its commands are compiled into bytecode instructions
-that are then executed if there are no compilation errors.
-.PP
-The return value from \fBTcl_EvalObj\fR is one of the Tcl return codes
-\fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or
-\fBTCL_CONTINUE\fR,
-and a result object containing additional information
-(a result value or error message)
-that can be retrieved using \fBTcl_GetObjResult\fR.
-If an error occurs during compilation, this return information
-describes the error.
-Otherwise, this return information corresponds to the last command
-executed from \fIobjPtr\fR.
-.PP
-\fBTcl_GlobalEvalObj\fR is similar to \fBTcl_EvalObj\fR except that it
-processes the command at global level.
-This means that the variable context for the command consists of
-global variables only (it ignores any Tcl procedure that is active).
-This produces an effect similar to the Tcl command ``\fBuplevel 0\fR''.
-.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_EvalObj\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_EvalObj\fR keeps track of how many nested \fBTcl_EvalObj\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_EvalObj\fR
-invocation for \fIinterp\fR,
-it converts the return code to \fBTCL_ERROR\fR
-and sets the interpreter's result object
-to point 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_EvalObj\fR other then \fBTCL_OK\fR or \fBTCL_ERROR\fR.
-
-.SH "SEE ALSO"
-Tcl_GetObjResult, Tcl_SetObjResult
-
-.SH KEYWORDS
-command, execute, file, global, object, object result, variable
@@ -4,13 +4,13 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) Exit.3 1.8 96/12/10 07:37:23
+'\" RCS: @(#) $Id: Exit.3,v 1.3 1999/04/16 00:46:31 stanton Exp $
 '\" 
 .so man.macros
-.TH Tcl_Exit 3 7.7 Tcl "Tcl Library Procedures"
+.TH Tcl_Exit 3 8.1 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_Exit, Tcl_Finalize, Tcl_CreateExitHandler, Tcl_DeleteExitHandler \- end the application (and invoke exit handlers)
+Tcl_Exit, Tcl_Finalize, Tcl_FinalizeThread, Tcl_CreateExitHandler, Tcl_DeleteExitHandler, Tcl_CreateThreadExitHandler, Tcl_DeleteThreadExitHandler \- end the application or thread (and invoke exit handlers)
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -22,10 +22,19 @@ Tcl_Exit, Tcl_Finalize, Tcl_CreateExitHandler, Tcl_DeleteExitHandler \- end the
 \fBTcl_CreateExitHandler\fR(\fIproc, clientData\fR)
 .sp
 \fBTcl_DeleteExitHandler\fR(\fIproc, clientData\fR)
+.sp
+\fBTcl_ExitThread\fR(\fIstatus\fR)
+.sp
+\fBTcl_FinalizeThread\fR()
+.sp
+\fBTcl_CreateThreadExitHandler\fR(\fIproc, clientData\fR)
+.sp
+\fBTcl_DeleteThreadExitHandler\fR(\fIproc, clientData\fR)
 .SH ARGUMENTS
 .AS Tcl_ExitProc clientData
 .AP int status  in
-Provides information about why application exited.  Exact meaning may
+Provides information about why the application or thread exited.
+Exact meaning may
 be platform-specific.  0 usually means a normal exit, any nonzero value
 usually means that an error occurred.
 .AP Tcl_ExitProc *proc in
@@ -51,7 +60,6 @@ otherwise causes the application to terminate without calling
 \fBTcl_Exit\fR internally invokes the \fBexit\fR system call, thus it never
 returns control to its caller.
 .PP
-.VS
 \fBTcl_Finalize\fR is similar to \fBTcl_Exit\fR except that it does not
 exit from the current process.
 It is useful for cleaning up when a process is finished using \fBTcl\fR but
@@ -64,10 +72,20 @@ However, to ensure portability, your code should always invoke
 \fBTcl_Finalize\fR when \fBTcl\fR is being unloaded, to ensure that the
 code will work on all platforms. \fBTcl_Finalize\fR can be safely called
 more than once.
+.PP
+.VS
+\fBTcl_ExitThread\fR is used to terminate the current thread and invoke
+per-thread exit handlers.  This finalization is done by
+\fBTcl_FinalizeThread\fR, which you can call if you just want to clean
+up per-thread state and invoke the thread exit handlers.
+\fBTcl_Finalize\fR calls \fBTcl_FinalizeThread\fR for the current
+thread automatically.
 .VE
 .PP
 \fBTcl_CreateExitHandler\fR arranges for \fIproc\fR to be invoked
 by \fBTcl_Finalize\fR and \fBTcl_Exit\fR.
+\fBTcl_CreateThreadExitHandler\fR arranges for \fIproc\fR to be invoked
+by \fBTcl_FinalizeThread\fR and \fBTcl_ExitThread\fR.
 This provides a hook for cleanup operations such as flushing buffers
 and freeing global memory.
 \fIProc\fR should match the type \fBTcl_ExitProc\fR:
@@ -76,16 +94,18 @@ typedef void Tcl_ExitProc(ClientData \fIclientData\fR);
 .CE
 The \fIclientData\fR parameter to \fIproc\fR is a
 copy of the \fIclientData\fR argument given to
-\fBTcl_CreateExitHandler\fR when the callback
+\fBTcl_CreateExitHandler\fR or \fBTcl_CreateThreadExitHandler\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_DeleteExitHandler\fR may be called to delete a
+\fBTcl_DeleteExitHandler\fR and \fBTcl_DeleteThreadExitHandler\fR may be
+called to delete a
 previously-created exit handler.  It removes the handler
 indicated by \fIproc\fR and \fIclientData\fR so that no call
 to \fIproc\fR will be made.  If no such handler exists then
-\fBTcl_DeleteExitHandler\fR does nothing.
+\fBTcl_DeleteExitHandler\fR or \fBTcl_DeleteThreadExitHandler\fR does nothing.
 .PP
 .VS
 .PP
@@ -98,6 +118,14 @@ If extension \fBA\fR registers its exit handlers before loading extension
 \fBB\fR, this ensures that any exit handlers for \fBB\fR will be executed
 before the exit handlers for \fBA\fR.
 .VE
+.VS
+.PP
+\fBTcl_Finalize\fR and \fBTcl_Exit\fR call \fBTcl_FinalizeThread\fR 
+and the thread exit handlers \fIafter\fR
+the process-wide exit handlers.  This is because thread finalization shuts
+down the I/O channel system, so any attempt at I/O by the global exit
+handlers will vanish into the bitbucket.
+.VE

 .SH KEYWORDS
-callback, cleanup, dynamic loading, end application, exit, unloading
+callback, cleanup, dynamic loading, end application, exit, unloading, thread
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) ExprLong.3 1.26 97/06/26 13:42:47
+'\" RCS: @(#) $Id: ExprLong.3,v 1.2 1998/09/14 18:39:48 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_ExprLong 3 7.0 Tcl "Tcl Library Procedures"
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) ExprLongObj.3 1.6 97/06/26 13:41:12
+'\" RCS: @(#) $Id: ExprLongObj.3,v 1.2 1998/09/14 18:39:48 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_ExprLongObj 3 8.0 Tcl "Tcl Library Procedures"
@@ -4,19 +4,22 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) FindExec.3 1.4 96/10/09 08:29:29
+'\" RCS: @(#) $Id: FindExec.3,v 1.3 1998/09/14 18:39:48 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_FindExecutable 3 7.5 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_FindExecutable \- identify the binary file containing the application
+Tcl_FindExecutable, Tcl_GetNameOfExecutable \- identify or return the name of the binary file containing the application
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
 .sp
 char *
 \fBTcl_FindExecutable\fR(\fIargv0\fR)
+.sp
+CONST char *
+\fBTcl_GetNameOfExecutable\fR()
 .SH ARGUMENTS
 .AS char *argv0 in
 .AP char *argv0 in
@@ -26,9 +29,9 @@ application's name.

 .SH DESCRIPTION
 .PP
-This procedure computes the full path name of the executable file
-from which the application was invoked and saves it for Tcl's
-internal use.
+The \fBTcl_FindExecutable\fR procedure computes the full path name of
+the executable file from which the application was invoked and saves
+it for Tcl's internal use.
 The executable's path name is needed for several purposes in
 Tcl.  For example, it is needed on some platforms in the
 implementation of the \fBload\fR command.
@@ -41,6 +44,13 @@ along with the \fBPATH\fR environment variable to find the
 application's executable, if possible.  If it fails to find
 the binary, then future calls to \fBinfo nameofexecutable\fR
 will return an empty string.
+.PP
+\fBTcl_GetNameOfExecutable\fR simply returns a pointer to the
+internal full path name of the executable file as computed by
+\fBTcl_FindExecutable\fR.  This procedure call is the C API
+equivalent to the \fBinfo nameofexecutable\fR command.  NULL
+is returned if the internal full path name has not been
+computed or unknown.

 .SH KEYWORDS
 binary, executable file
@@ -0,0 +1,54 @@
+'\"
+'\" Copyright (c) 1998-1999 Scriptics Corportation
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+'\" RCS: @(#) $Id: GetCwd.3,v 1.2 1999/04/16 00:46:31 stanton Exp $
+'\" 
+.so man.macros
+.TH Tcl_GetCwd 3 8.1 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_GetCwd, Tcl_Chdir \- manipulate the current working directory
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+char *
+\fBTcl_GetCwd\fR(\fIinterp\fR, \fIbufferPtr\fR)
+.sp
+int
+\fBTcl_Chdir\fR(\fIpath\fR)
+.SH ARGUMENTS
+.AS Tcl_DString *bufferPtr
+.AP Tcl_Interp *interp in
+Interpreter in which to report an error, if any.
+.AP Tcl_DString *bufferPtr in/out
+This dynamic string is used to store the current working directory.
+At the time of the call it should be uninitialized or free.  The
+caller must eventually call \fBTcl_DStringFree\fR to free up
+anything stored here.
+.AP char *path in
+File path in UTF\-8 format.
+.BE
+
+.SH DESCRIPTION
+.PP
+These procedures may be used to manipulate the current working
+directory for the application.  They provide C\-level access to
+the same functionality as the Tcl \fBpwd\fR command.
+.PP
+\fBTcl_GetCwd\fR returns a pointer to a string specifying the current
+directory, or NULL if the current directory could not be determined.
+If NULL is returned, an error message is left in the interp's result.
+Storage for the result string is allocated in bufferPtr; the caller
+must call \fBTcl_DStringFree()\fR when the result is no longer needed.
+The format of the path is UTF\-8.
+.PP
+\fBTcl_Chdir\fR changes the applications current working directory to
+the value specified in \fIpath\fR.  The format of the passed in string
+must be UTF\-8.  The function returns -1 on error or 0 on success.
+
+.SH KEYWORDS
+pwd
@@ -0,0 +1,28 @@
+'\"
+'\" Copyright (c) 1998-2000 by Scriptics Corporation.
+'\" All rights reserved.
+'\" 
+'\" RCS: @(#) $Id: GetHostName.3,v 1.1 2000/01/21 18:52:07 ericm Exp $
+'\" 
+.so man.macros
+.TH Tcl_GetHostName 3 8.3 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_GetHostName \- get the name of the local host
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+char *
+\fBTcl_GetHostName\fR()
+
+.SH DESCRIPTION
+.PP
+\fBTcl_GetHostName\fR is a utility procedure used by some of the
+Tcl commands.  It returns a pointer to a string containing the name 
+for the current machine, or an empty string if the name cannot be
+determined.  The string is statically allocated, and the caller must
+not modify of free it.
+.PP
+.SH KEYWORDS
+hostname
@@ -4,10 +4,10 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) @(#) GetIndex.3 1.3 97/07/30 16:21:05
+'\" RCS: @(#) $Id: GetIndex.3,v 1.5 1999/08/13 19:01:04 welch Exp $
 '\" 
 .so man.macros
-.TH Tcl_GetIndexFromObj 3 8.0 Tcl "Tcl Library Procedures"
+.TH Tcl_GetIndexFromObj 3 8.1 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
 Tcl_GetIndexFromObj \- lookup string in table of keywords
@@ -16,7 +16,14 @@ Tcl_GetIndexFromObj \- lookup string in table of keywords
 \fB#include <tcl.h>\fR
 .sp
 int
-\fBTcl_GetIndexFromObj\fR(\fIinterp, objPtr, tablePtr, msg, flags, indexPtr\fR)
+\fBTcl_GetIndexFromObj\fR(\fIinterp, objPtr, tablePtr, msg, flags,
+indexPtr\fR)
+.VS
+.sp
+int
+\fBTcl_GetIndexFromObjStruct\fR(\fIinterp, objPtr, tablePtr, offset,
+msg, flags, indexPtr\fR)
+.VE
 .SH ARGUMENTS
 .AS Tcl_Interp **tablePtr
 .AP Tcl_Interp *interp in
@@ -29,6 +36,11 @@ table entry.
 .AP char **tablePtr in
 An array of null-terminated strings.  The end of the array is marked
 by a NULL string pointer.
+.VS
+.AP int offset in
+The offset to add to tablePtr to get to the next string in the
+list. The end of the array is marked by a NULL string pointer.
+.VE
 .AP char *msg in
 Null-terminated string describing what is being looked up, such as
 \fBoption\fR.  This string is included in error messages.
@@ -68,7 +80,20 @@ is invoked again with the same \fIobjPtr\fR and \fItablePtr\fR
 arguments (e.g. during a reinvocation of a Tcl command), it returns
 the matching index immediately without having to redo the lookup
 operation.  Note: \fBTcl_GetIndexFromObj\fR assumes that the entries
-in \fItablePtr\fR are static: they must not change between invocations.
+in \fItablePtr\fR are static: they must not change between
+invocations.  If the value of \fIobjPtr\fR is the empty string,
+\fBTcl_GetIndexFromObj\fR will treat it as a non-matching value
+and return TCL_ERROR.
+.VS
+.PP
+\fBTcl_GetIndexFromObjStruct\fR works just like
+\fBTcl_GetIndexFromObj\fR, except that instead of treating
+\fItablePtr\fR as an array of string pointers, it treats it as the
+first in a series of string ptrs that are spaced apart by \fIoffset\fR
+bytes. This is particularly useful when processing things like
+\fBTk_ConfigurationSpec\fR, whose string keys are in the same place in
+each of several array elements.
+.VE

 .SH "SEE ALSO"
 Tcl_WrongNumArgs
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) GetInt.3 1.12 96/03/25 20:03:44
+'\" RCS: @(#) $Id: GetInt.3,v 1.2 1998/09/14 18:39:48 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_GetInt 3 "" Tcl "Tcl Library Procedures"
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) GetOpnFl.3 1.3 97/04/23 16:14:43
+'\" RCS: @(#) $Id: GetOpnFl.3,v 1.2 1998/09/14 18:39:48 stanton Exp $
 .so man.macros
 .TH Tcl_GetOpenFile 3 8.0 Tcl "Tcl Library Procedures"
 .BS
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" @(#) GetStdChan.3 1.2 96/03/08 13:59:57
+'\" RCS: @(#) $Id: GetStdChan.3,v 1.2 1998/09/14 18:39:48 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_GetStdChannel 3 7.5 Tcl "Tcl Library Procedures"
@@ -0,0 +1,49 @@
+'\"
+'\" Copyright (c) 1999 Scriptics Corporation
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+'\" RCS: @(#) $Id: GetVersion.3,v 1.2 1999/04/16 00:46:32 stanton Exp $
+'\" 
+.so man.macros
+.TH Tcl_GetVersion 3 7.5 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_GetVersion \- get the version of the library at runtime
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+\fBTcl_GetVersion\fR(\fImajor, minor, patchLevel, type\fR)
+.SH ARGUMENTS
+.AP int *major out
+Major version number of the Tcl library.
+.AP int *minor out
+Minor version number of the Tcl library.
+.AP int *patchLevel out
+The patch level of the Tcl library (or alpha or beta number).
+.AP Tcl_ReleaseType *type out
+The type of release, also indicates the type of patch level. Can be
+one of \fBTCL_ALPHA_RELEASE\fR, \fBTCL_BETA_RELEASE\fR, or 
+\fBTCL_FINAL_RELEASE\fR.
+.BE
+
+.SH DESCRIPTION
+.PP
+\fBTcl_GetVersion\fR should be used to query the version number
+of the Tcl library at runtime.  This is useful when using a 
+dynamically loaded Tcl library or when writing a stubs-aware
+extension.  For instance, if you write an extension that is
+linked against the Tcl stubs library, it could be loaded into
+a program linked to an older version of Tcl than you expected.
+Use \fBTcl_GetVersion\fR to verify that fact, and possibly to
+change the behavior of your extension.
+.PP
+If may pass a NULL for any of the arguments. For instance if 
+you do not care about the \fIpatchLevel\fR of the library, pass
+a NULL for the \fIpatchLevel\fR argument.
+
+.SH KEYWORDS
+version, patchlevel, major, minor, alpha, beta, release
+
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) Hash.3 1.15 96/03/25 20:04:01
+'\" RCS: @(#) $Id: Hash.3,v 1.3 1999/12/21 23:57:33 hobbs Exp $
 '\" 
 .so man.macros
 .TH Tcl_Hash 3 "" Tcl "Tcl Library Procedures"
@@ -193,7 +193,7 @@ overall information about a hash table, such as the number of
 entries it contains, the number of buckets in its hash array,
 and the utilization of the buckets.
 It is the caller's responsibility to free the result string
-by passing it to \fBfree\fR.
+by passing it to \fBckfree\fR.
 .PP
 The header file \fBtcl.h\fR defines the actual data structures
 used to implement hash tables.
@@ -0,0 +1,91 @@
+'\"
+'\" Copyright (c) 1999 Scriptics Corportation
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+'\" RCS: @(#) $Id: InitStubs.3,v 1.4 1999/05/06 19:14:40 stanton Exp $
+'\" 
+.so man.macros
+.TH Tcl_InitStubs 3 8.1 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_InitStubs \- initialize the Tcl stubs mechanism
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+char *
+\fBTcl_InitStubs\fR(\fIinterp, version, exact\fR)
+.SH ARGUMENTS
+.AS Tcl_Interp *interp in
+.AP Tcl_Interp *interp in
+Tcl interpreter handle.
+.AP char *version in
+A version string consisting of one or more decimal numbers
+separated by dots.
+.AP int exact in
+Non-zero means that only the particular version specified by
+\fIversion\fR is acceptable.
+Zero means that versions newer than \fIversion\fR are also
+acceptable as long as they have the same major version number
+as \fIversion\fR.
+.BE
+.SH INTRODUCTION
+.PP
+The Tcl stubs mechanism defines a way to dynamically bind
+extensions to a particular Tcl implementation at run time.
+This provides two significant benefits to Tcl users:
+.IP 1) 5
+Extensions that use the stubs mechanism can be loaded into
+multiple versions of Tcl without being recompiled or
+relinked.
+.IP 2) 5
+Extensions that use the stubs mechanism can be dynamically
+loaded into statically-linked Tcl applications.
+.PP
+The stubs mechanism accomplishes this by exporting function tables
+that define an interface to the Tcl API.  The extension then accesses
+the Tcl API through offsets into the function table, so there are no
+direct references to any of the Tcl library's symbols.  This
+redirection is transparent to the extension, so an extension writer
+can continue to use all public Tcl functions as documented.
+.PP
+The stubs mechanism requires no changes to applications incorporating
+Tcl interpreters.  Only developers creating C-based Tcl extensions
+need to take steps to use the stubs mechanism with their extensions.
+.PP
+Enabling the stubs mechanism for an extension requires the following
+steps:
+.IP 1) 5
+Call \fBTcl_InitStubs\fR in the extension before calling any other
+Tcl functions.
+.IP 2) 5
+Define the USE_TCL_STUBS symbol.  Typically, you would include the
+-DUSE_TCL_STUBS flag when compiling the extension.
+.IP 3) 5
+Link the extension with the Tcl stubs library instead of the standard
+Tcl library.  On Unix platforms, the library name is
+\fIlibtclstub8.1.a\fR; on Windows platforms, the library name is
+\fItclstub81.lib\fR.
+.PP
+If the extension also requires the Tk API, it must also call
+\fBTk_InitStubs\fR to initialize the Tk stubs interface and link
+with the Tk stubs libraries.  See the \fBTk_InitStubs\fR page for
+more information.
+.SH DESCRIPTION
+\fBTcl_InitStubs\fR attempts to initialize the stub table pointers
+and ensure that the correct version of Tcl is loaded.  In addition
+to an interpreter handle, it accepts as arguments a version number
+and a Boolean flag indicating whether the extension requires
+an exact version match or not.  If \fIexact\fR is 0, then the
+extension is indicating that newer versions of Tcl are acceptable
+as long as they have the same major version number as \fIversion\fR;
+non-zero means that only the specified \fIversion\fR is acceptable.
+\fBTcl_InitStubs\fR returns a string containing the actual version
+of Tcl satisfying the request, or NULL if the Tcl version is not
+acceptable, does not support stubs, or any other error condition occurred.
+.SH "SEE ALSO"
+\fBTk_InitStubs\fR
+.SH KEYWORDS
+stubs
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) @(#) IntObj.3 1.7 97/05/08 19:49:22
+'\" RCS: @(#) $Id: IntObj.3,v 1.2 1998/09/14 18:39:49 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_IntObj 3 8.0 Tcl "Tcl Library Procedures"
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) Interp.3 1.16 96/06/06 13:48:02
+'\" RCS: @(#) $Id: Interp.3,v 1.2 1998/09/14 18:39:49 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_Interp 3 7.5 Tcl "Tcl Library Procedures"
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) LinkVar.3 1.15 96/09/05 17:16:57
+'\" RCS: @(#) $Id: LinkVar.3,v 1.2 1998/09/14 18:39:49 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_LinkVar 3 7.5 Tcl "Tcl Library Procedures"
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) @(#) ListObj.3 1.10 97/10/08 11:36:58
+'\" RCS: @(#) $Id: ListObj.3,v 1.4 2000/01/26 03:37:30 hobbs Exp $
 '\" 
 .so man.macros
 .TH Tcl_ListObj 3 8.0 Tcl "Tcl Library Procedures"
@@ -74,9 +74,7 @@ and \fBTcl_ListObjReplace\fR will insert into \fIlistPtr\fR.
 For \fBTcl_SetListObj\fR,
 the number of Tcl objects to insert into \fIobjPtr\fR.
 .VS
-.TP 
-Tcl_Obj	*CONST \fIobjv\fR[]	(in)
-.
+.AP Tcl_Obj	"*CONST\ objv[]" in
 An array of pointers to objects.
 \fBTcl_NewListObj\fR will insert these objects into a new list object
 and \fBTcl_ListObjReplace\fR will insert them into an existing \fIlistPtr\fR.
@@ -151,16 +149,16 @@ of the elements in \fIobjc\fR since the list object now refers to them.
 The new list object returned by \fBTcl_NewListObj\fR
 has reference count zero.
 .PP
-\fBTcl_ListObjGetElements\fR returns a count and
-a pointer to an array of the elements in a list object.
-It returns the count by storing it in the address \fIobjcPtr\fR.
-Similarly, it returns the array pointer by storing it
-in the address \fIobjvPtr\fR.
-If \fIlistPtr\fR is not already a list object,
-\fBTcl_ListObjGetElements\fR will attempt to convert it to one;
-if the conversion fails, it returns \fBTCL_ERROR\fR
-and leaves an error message in the interpreter's result object
-if \fIinterp\fR is not NULL.
+\fBTcl_ListObjGetElements\fR returns a count and a pointer to an array of
+the elements in a list object.  It returns the count by storing it in the
+address \fIobjcPtr\fR.  Similarly, it returns the array pointer by storing
+it in the address \fIobjvPtr\fR.
+The memory pointed to is managed by Tcl and should not be freed by the
+caller.
+If \fIlistPtr\fR is not already a list object, \fBTcl_ListObjGetElements\fR
+will attempt to convert it to one; if the conversion fails, it returns
+\fBTCL_ERROR\fR and leaves an error message in the interpreter's result
+object if \fIinterp\fR is not NULL.
 Otherwise it returns \fBTCL_OK\fR after storing the count and array pointer.
 .PP
 \fBTcl_ListObjLength\fR returns the number of elements in the list object
@@ -1,36 +1,59 @@
 '\"
+'\" Copyright (c) 1998-1999 Scriptics Corporation
 '\" Copyright (c) 1995-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.
 '\" 
-'\" SCCS: @(#) Notifier.3 1.16 97/05/17 17:03:17
+'\" RCS: @(#) $Id: Notifier.3,v 1.7 1999/05/06 20:13:22 stanton Exp $
 '\" 
 .so man.macros
-.TH Notifier 3 8.0 Tcl "Tcl Library Procedures"
+.TH Notifier 3 8.1 Tcl "Tcl Library Procedures"
 .BS
-.VS
 .SH NAME
-Tcl_CreateEventSource, Tcl_DeleteEventSource, Tcl_SetMaxBlockTime, Tcl_QueueEvent, Tcl_DeleteEvents, Tcl_WaitForEvent, Tcl_SetTimer, Tcl_ServiceAll, Tcl_ServiceEvent, Tcl_GetServiceMode, Tcl_SetServiceMode \- the event queue and notifier interfaces
-
+Tcl_CreateEventSource, Tcl_DeleteEventSource, Tcl_SetMaxBlockTime, Tcl_QueueEvent, Tcl_ThreadQueueEvent, Tcl_ThreadAlert, Tcl_GetCurrentThread, Tcl_DeleteEvents, Tcl_InitNotifier, Tcl_FinalizeNotifier, Tcl_WaitForEvent, Tcl_AlertNotifier, Tcl_SetTimer, Tcl_ServiceAll, Tcl_ServiceEvent, Tcl_GetServiceMode, Tcl_SetServiceMode \- the event queue and notifier interfaces
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
 .sp
-\fBTcl_CreateEventSource\fR(\fIsetupProc, checkProc, clientData\fB)\fR
+void
+\fBTcl_CreateEventSource\fR(\fIsetupProc, checkProc, clientData\fR)
 .sp
-\fBTcl_DeleteEventSource\fR(\fIsetupProc, checkProc, clientData\fB)\fR
+void
+\fBTcl_DeleteEventSource\fR(\fIsetupProc, checkProc, clientData\fR)
 .sp
-\fBTcl_SetMaxBlockTime\fR(\fItimePtr\fB)\fR
+void
+\fBTcl_SetMaxBlockTime\fR(\fItimePtr\fR)
 .sp
+void
 \fBTcl_QueueEvent\fR(\fIevPtr, position\fR)
-.VS
+.VS 8.1
 .sp
+void
+\fBTcl_ThreadQueueEvent\fR(\fIthreadId, evPtr, position\fR)
+.sp
+void
+\fBTcl_ThreadAlert\fR(\fIthreadId, clientData\fR)
+.sp
+Tcl_ThreadId
+\fBTcl_GetCurrentThread\fR()
+.sp
+void
 \fBTcl_DeleteEvents\fR(\fIdeleteProc, clientData\fR)
 .sp
+ClientData
+\fBTcl_InitNotifier\fR()
+.sp
+void
+\fBTcl_FinalizeNotifier\fR(\fIclientData\fR)
+.sp
 int
 \fBTcl_WaitForEvent\fR(\fItimePtr\fR)
 .sp
+void
+\fBTcl_AlertNotifier\fR(\fIclientData\fR)
+.sp
+void
 \fBTcl_SetTimer\fR(\fItimePtr\fR)
 .sp
 int
@@ -48,7 +71,6 @@ int

 .SH ARGUMENTS
 .AS Tcl_EventDeleteProc milliseconds
-.AS Tcl_EventSetupProc *setupProc
 .AP Tcl_EventSetupProc *setupProc in
 Procedure to invoke to prepare for event wait in \fBTcl_DoOneEvent\fR.
 .AP Tcl_EventCheckProc *checkProc in
@@ -70,12 +92,14 @@ have been allocated by the caller using \fBTcl_Alloc\fR or \fBckalloc\fR.
 .AP Tcl_QueuePosition position in
 Where to add the new event in the queue:  \fBTCL_QUEUE_TAIL\fR,
 \fBTCL_QUEUE_HEAD\fR, or \fBTCL_QUEUE_MARK\fR.
+.AP Tcl_ThreadId threadId in
+A unique identifier for a thread.
+.AP Tcl_EventDeleteProc *deleteProc in
+Procedure to invoke for each queued event in \fBTcl_DeleteEvents\fR.
 .AP int flags in
 What types of events to service.  These flags are the same as those
 passed to \fBTcl_DoOneEvent\fR.
-.AP Tcl_EventDeleteProc *deleteProc in
-Procedure to invoke for each queued event in \fBTcl_DeleteEvents\fR.
-.VS
+.VS 8.1
 .AP int mode in
 Inidicates whether events should be serviced by \fBTcl_ServiceAll\fR.
 Must be one of \fBTCL_SERVICE_NONE\fR or \fBTCL_SERVICE_ALL\fR.
@@ -84,13 +108,11 @@ Must be one of \fBTCL_SERVICE_NONE\fR or \fBTCL_SERVICE_ALL\fR.

 .SH INTRODUCTION
 .PP
-.VS
 The interfaces described here are used to customize the Tcl event
 loop.  The two most common customizations are to add new sources of
 events and to merge Tcl's event loop with some other event loop, such
 as one provided by an application in which Tcl is embedded.  Each of
 these tasks is described in a separate section below.
-.VE
 .PP
 The procedures in this manual entry are the building blocks out of which
 the Tcl event notifier is constructed.  The event notifier is the lowest
@@ -108,18 +130,24 @@ higher-level software that they have occurred.  The procedures
 and \fBTcl_SetMaxBlockTime\fR, \fBTcl_QueueEvent\fR, and
 \fBTcl_DeleteEvents\fR are used primarily by event sources.
 .IP [2]
-The event queue: there is a single queue for the whole application,
+The event queue: for non-threaded applications,
+there is a single queue for the whole application,
 containing events that have been detected but not yet serviced.  Event
 sources place events onto the queue so that they may be processed in
 order at appropriate times during the event loop. The event queue
 guarantees a fair discipline of event handling, so that no event
 source can starve the others.  It also allows events to be saved for
 servicing at a future time.
-.VS
+.VS 8.1
+Threaded applications work in a
+similar manner, except that there is a separate event queue for
+each thread containing a Tcl interpreter.
 \fBTcl_QueueEvent\fR is used (primarily
 by event sources) to add events to the event queue and 
 \fBTcl_DeleteEvents\fR is used to remove events from the queue without
-processing them.
+processing them.  In a threaded application, \fBTcl_QueueEvent\fR adds
+an event to the current thread's queue, and \fBTcl_ThreadQueueEvent\fR
+adds an event to a queue in a specific thread.
 .IP [3]
 The event loop: in order to detect and process events, the application
 enters a loop that waits for events to occur, places them on the event
@@ -133,7 +161,9 @@ to be retargeted either for a new platform or to use an external event
 loop (such as the Motif event loop, when Tcl is embedded in a Motif
 application).  The procedures \fBTcl_WaitForEvent\fR and
 \fBTcl_SetTimer\fR are normally implemented by Tcl, but may be
-replaced with new versions to retarget the notifier (the \fBTcl_Sleep\fR,
+replaced with new versions to retarget the notifier (the
+\fBTcl_InitNotifier\fR, \fBTcl_AlertNotifier\fR,
+\fBTcl_FinalizeNotifier\fR, \fBTcl_Sleep\fR,
 \fBTcl_CreateFileHandler\fR, and \fBTcl_DeleteFileHandler\fR must
 also be replaced; see CREATING A NEW NOTIFIER below for details).
 The procedures \fBTcl_ServiceAll\fR, \fBTcl_ServiceEvent\fR,
@@ -152,7 +182,7 @@ things:
 .IP [1]
 Check the event queue to see if it contains any events that can
 be serviced.  If so, service the first possible event, remove it
-.VS
+.VS 8.1
 from the queue, and return.  It does this by calling
 \fBTcl_ServiceEvent\fR and passing in the \fIflags\fR argument.
 .VE
@@ -160,7 +190,7 @@ from the queue, and return.  It does this by calling
 Prepare to block for an event.  To do this, \fBTcl_DoOneEvent\fR
 invokes a \fIsetup procedure\fR in each event source.
 The event source will perform event-source specific initialization and
-.VS
+.VS 8.1
 possibly call \fBTcl_SetMaxBlockTime\fR to limit how long
 .VE
 \fBTcl_WaitForEvent\fR will block if no new events occur.
@@ -228,7 +258,7 @@ request notification with a Windows event.  For timer-driven event
 sources such as timer events or any polled event, the event source
 can call \fBTcl_SetMaxBlockTime\fR to force the application to wake
 up after a specified time even if no events have occurred.
-.VS
+.VS 8.1
 If no event source calls \fBTcl_SetMaxBlockTime\fR
 then \fBTcl_WaitForEvent\fR will wait as long as necessary for an
 event to occur; otherwise, it will only wait as long as the shortest
@@ -252,7 +282,7 @@ typedef struct Tcl_Time {
 .CE
 The \fIusec\fR field should be less than 1000000.
 .PP
-.VS
+.VS 8.1
 Information provided to \fBTcl_SetMaxBlockTime\fR
 is only used for the next call to \fBTcl_WaitForEvent\fR; it is
 discarded after \fBTcl_WaitForEvent\fR returns.
@@ -261,7 +291,7 @@ The next time an event wait is done each of the event sources'
 setup procedures will be called again, and they can specify new
 information for that event wait.
 .PP
-.VS
+.VS 8.1
 If the application uses an external event loop rather than
 \fBTcl_DoOneEvent\fR, the event sources may need to call
 \fBTcl_SetMaxBlockTime\fR at other times.  For example, if a new event
@@ -335,7 +365,7 @@ events at the front of the queue, such as a series of
 Enter and Leave events synthesized during a grab or ungrab operation
 in Tk.
 .PP
-.VS
+.VS 8.1
 When it is time to handle an event from the queue (steps 1 and 4
 above) \fBTcl_ServiceEvent\fR will invoke the \fIproc\fR specified
 .VE
@@ -350,7 +380,7 @@ The first argument to \fIproc\fR is a pointer to the event, which will
 be the same as the first argument to the \fBTcl_QueueEvent\fR call that
 added the event to the queue.
 The second argument to \fIproc\fR is the \fIflags\fR argument for the
-.VS
+.VS 8.1
 current call to \fBTcl_ServiceEvent\fR;  this is used by the event source
 .VE
 to return immediately if its events are not relevant.
@@ -361,7 +391,7 @@ Once the event source has finished handling the event it returns 1
 to indicate that the event can be removed from the queue.
 If for some reason the event source decides that the event cannot
 be handled at this time, it may return 0 to indicate that the event
-.VS
+.VS 8.1
 should be deferred for processing later;  in this case \fBTcl_ServiceEvent\fR
 .VE
 will go on to the next event in the queue and attempt to service it.
@@ -374,7 +404,7 @@ Another example of deferring events happens in Tk if
 \fBTk_RestrictEvents\fR has been invoked to defer certain kinds
 of window events.
 .PP
-.VS
+.VS 8.1
 When \fIproc\fR returns 1, \fBTcl_ServiceEvent\fR will remove the
 event from the event queue and free its storage.
 Note that the storage for an event must be allocated by
@@ -382,6 +412,21 @@ the event source (using \fBTcl_Alloc\fR or the Tcl macro \fBckalloc\fR)
 before calling \fBTcl_QueueEvent\fR, but it
 will be freed by \fBTcl_ServiceEvent\fR, not by the event source.
 .PP
+Threaded applications work in a
+similar manner, except that there is a separate event queue for
+each thread containing a Tcl interpreter.
+Calling \fBTcl_QueueEvent\fR in a multithreaded application adds
+an event to the current thread's queue.
+To add an event to another thread's queue, use \fBTcl_ThreadQueueEvent\fR.
+\fBTcl_ThreadQueueEvent\fR accepts as an argument a Tcl_ThreadId argument,
+which uniquely identifies a thread in a Tcl application.  To obtain the
+Tcl_ThreadID for the current thread, use the \fBTcl_GetCurrentThread\fR
+procedure.  (A thread would then need to pass this identifier to other
+threads for those threads to be able to add events to its queue.)
+After adding an event to another thread's queue, you then typically
+need to call \fBTcl_ThreadAlert\fR to "wake up" that thread's notifier to
+alert it to the new event.
+.PP
 \fBTcl_DeleteEvents\fR can be used to explicitly remove one or more
 events from the event queue.  \fBTcl_DeleteEvents\fR calls \fIproc\fR
 for each event in the queue, deleting those for with the procedure
@@ -396,23 +441,35 @@ The \fIclientData\fR argument will be the same as the \fIclientData\fR
 argument to \fBTcl_DeleteEvents\fR; it is typically used to point to
 private information managed by the event source.  The \fIevPtr\fR will
 point to the next event in the queue.
+.PP
+\fBTcl_DeleteEventSource\fR deletes an event source.  The \fIsetupProc\fR,
+\fIcheckProc\fR, and \fIclientData\fR arguments must exactly match those
+provided to the \fBTcl_CreateEventSource\fR for the event source to be deleted.
+If no such source exists, \fBTcl_DeleteEventSource\fR has no effect.
 .VE

 .SH "CREATING A NEW NOTIFIER"
 .PP
 The notifier consists of all the procedures described in this manual
 entry, plus \fBTcl_DoOneEvent\fR and \fBTcl_Sleep\fR, which are
-.VS
+.VS 8.1
 available on all platforms, and \fBTcl_CreateFileHandler\fR and
 \fBTcl_DeleteFileHandler\fR, which are Unix-specific.  Most of these
 procedures are generic, in that they are the same for all notifiers.
-However, five of the procedures are notifier-dependent:
+However, eight of the procedures are notifier-dependent:
+\fBTcl_InitNotifier\fR, \fBTcl_AlertNotifier\fR, \fBTcl_FinalizeNotifier\fR, 
 \fBTcl_SetTimer\fR, \fBTcl_Sleep\fR, \fBTcl_WaitForEvent\fR,
 \fBTcl_CreateFileHandler\fR and \fBTcl_DeleteFileHandler\fR.  To
 support a new platform or to integrate Tcl with an
 application-specific event loop, you must write new versions of these
 procedures.
 .PP
+\fBTcl_InitNotifier\fR initializes the notifier state and returns
+a handle to the notifier state.  Tcl calls this
+procedure when intializing a Tcl interpreter.  Similarly,
+\fBTcl_FinalizeNotifier\fR shuts down the notifier, and is
+called by \fBTcl_Finalize\fR when shutting down a Tcl interpreter.
+.PP
 \fBTcl_WaitForEvent\fR is the lowest-level procedure in the notifier;
 it is responsible for waiting for an ``interesting'' event to occur or
 for a given time to elapse.  Before \fBTcl_WaitForEvent\fR is invoked,
@@ -448,6 +505,11 @@ under Unix it happens when \fBTcl_WaitForEvent\fR would have waited
 forever because there were no active event sources and the timeout was
 infinite.
 .PP
+\fBTcl_AlertNotifier\fR is used in multithreaded applications to allow
+any thread to "wake up" the notifier to alert it to new events on its
+queue.  \fBTcl_AlertNotifier\fR requires as an argument the notifier
+handle returned by \fBTcl_InitNotifier\fR.
+.PP
 If the notifier will be used with an external event loop, then it must
 also support the \fBTcl_SetTimer\fR interface.  \fBTcl_SetTimer\fR is
 invoked by \fBTcl_SetMaxBlockTime\fR whenever the maximum blocking
@@ -462,10 +524,11 @@ notifier will only be used from \fBTcl_DoOneEvent\fR, then
 On Unix systems, the file event source also needs support from the
 notifier.  The file event source consists of the
 \fBTcl_CreateFileHandler\fR and \fBTcl_DeleteFileHandler\fR
-procedures, which are described elsewhere.
+procedures, which are described in the \fBTcl_CreateFileHandler\fR
+manual page.
 .PP
 The \fBTcl_Sleep\fR and \fBTcl_DoOneEvent\fR interfaces are described
-elsewhere.
+in their respective manual pages.
 .PP
 The easiest way to create a new notifier is to look at the code
 for an existing notifier, such as the files \fBunix/tclUnixNotfy.c\fR
@@ -532,6 +595,8 @@ mode, which should be restored when the recursive loop exits.
 \fBTcl_GetServiceMode\fR returns the current value of the service
 mode.
 .VE
-
+.SH "SEE ALSO"
+\fBTcl_CreateFileHandler\fR, \fBTcl_DeleteFileHandler\fR, \fBTcl_Sleep\fR,
+\fBTcl_DoOneEvent\fR, \fBThreads.3\fR
 .SH KEYWORDS
-event, notifier, event queue, event sources, file events, timer, idle, service mode
+event, notifier, event queue, event sources, file events, timer, idle, service mode, threads
@@ -1,162 +0,0 @@
-'\"
-'\" 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.
-'\" 
-'\" SCCS: @(#) ObjSetVar.3 1.6 97/05/19 17:35:44
-'\" 
-.so man.macros
-.TH Tcl_ObjSetVar2 3 8.0 Tcl "Tcl Library Procedures"
-.BS
-.SH NAME
-Tcl_ObjSetVar2, Tcl_ObjGetVar2 \- manipulate Tcl variables
-.SH SYNOPSIS
-.nf
-\fB#include <tcl.h>\fR
-.sp
-Tcl_Obj *
-\fBTcl_ObjSetVar2\fR(\fIinterp, part1Ptr, part2Ptr, newValuePtr, flags\fR)
-.sp
-Tcl_Obj *
-\fBTcl_ObjGetVar2\fR(\fIinterp, part1Ptr, part2Ptr, flags\fR)
-.SH ARGUMENTS
-.AS Tcl_Interp *newValuePtr
-.AP Tcl_Interp *interp in
-Interpreter containing variable.
-.AP Tcl_Obj *part1Ptr in
-Points to a Tcl object containing the variable's name.
-The name may include a series of \fB::\fR namespace qualifiers
-to specify a variable in a particular namespace.
-May refer to a scalar variable or an element of an array variable.
-.AP Tcl_Obj *part2Ptr in
-If non-NULL, points to an object containing the name of an element
-within an array and \fIpart1Ptr\fR must refer to an array variable.
-.AP Tcl_Obj *newValuePtr in
-Points to a Tcl object containing the new value for the variable.
-.AP int flags in
-OR-ed combination of bits providing additional information for
-operation. See below for valid values.
-.BE
-
-.SH DESCRIPTION
-.PP
-These two procedures may be used to read and modify
-Tcl variables from C code.
-\fBTcl_ObjSetVar2\fR will create a new variable or modify an existing one.
-It sets the specified variable to
-the object referenced by \fInewValuePtr\fR
-and returns a pointer to the object which is the variable's new value.
-The returned object may not be the same one
-referenced by \fInewValuePtr\fR;
-this might happen because variable traces may modify the variable's value.
-The reference count for the variable's old value is decremented
-and the reference count for its new value is incremented.
-If the new value for the variable
-is not the same one referenced by \fInewValuePtr\fR
-(perhaps as a result of a variable trace),
-then \fInewValuePtr\fR's reference count is left unchanged.
-The reference count for the returned object is not incremented
-to reflect the returned reference.
-If the caller needs to keep a reference to the object,
-say in a data structure,
-it must increment its reference count using \fBTcl_IncrRefCount\fR.
-If an error occurs in setting the variable
-(e.g. an array variable is referenced
-without giving an index into the array),
-then NULL is returned.
-.PP
-The variable name specified to \fBTcl_ObjSetVar2\fR consists of two parts.
-\fIpart1Ptr\fR contains the name of a scalar or array variable.
-If \fIpart2Ptr\fR is NULL, the variable must be a scalar.
-If \fIpart2Ptr\fR is not NULL,
-it contains the name of an element in the array named by \fIpart2Ptr\fR.
-As a special case, if the flag TCL_PARSE_PART1 is specified,
-\fIpart1Ptr\fR may contain both an array and an element name:
-if the name contains an open parenthesis and ends with a
-close parenthesis, then the value between the parentheses is
-treated as an element name (which can have any string value) and
-the characters before the first open
-parenthesis are treated as the name of an array variable.
-If the flag TCL_PARSE_PART1 is given,
-\fIpart2Ptr\fR should be NULL since the array and element names
-are taken from \fIpart2Ptr\fR.
-.PP
-The \fIflags\fR argument may be used to specify any of several
-options to the procedures.
-It consists of an OR-ed combination of any of the following
-bits:
-.TP
-\fBTCL_GLOBAL_ONLY\fR
-Under normal circumstances the procedures look up variables as follows:
-If a procedure call is active in \fIinterp\fR,
-a variable is looked up at the current level of procedure call.
-Otherwise, a variable is looked up first in the current namespace,
-then in the global namespace.
-However, if this bit is set in \fIflags\fR then the variable
-is looked up only in the global namespace
-even if there is a procedure call active.
-If both \fBTCL_GLOBAL_ONLY\fR and \fBTCL_NAMESPACE_ONLY\fR are given,
-\fBTCL_GLOBAL_ONLY\fR is ignored.
-.TP
-\fBTCL_NAMESPACE_ONLY\fR
-Under normal circumstances the procedures look up variables as follows:
-If a procedure call is active in \fIinterp\fR,
-a variable is looked up at the current level of procedure call.
-Otherwise, a variable is looked up first in the current namespace,
-then in the global namespace.
-However, if this bit is set in \fIflags\fR then the variable
-is looked up only in the current namespace
-even if there is a procedure call active.
-.TP
-\fBTCL_LEAVE_ERR_MSG\fR
-If an error is returned and this bit is set in \fIflags\fR, then
-an error message will be left in the interpreter's result,
-where it can be retrieved with \fBTcl_GetObjResult\fR
-or \fBTcl_GetStringResult\fR.
-If this flag bit isn't set then no error message is left
-and the interpreter's result will not be modified.
-.TP
-\fBTCL_APPEND_VALUE\fR
-If this bit is set then \fInewValuePtr\fR is appended to the current
-value, instead of replacing it.
-If the variable is currently undefined, then this bit is ignored.
-.TP
-\fBTCL_LIST_ELEMENT\fR
-If this bit is set, then \fInewValuePtr\fR is converted to a valid
-Tcl list element before setting (or appending to) the variable.
-A separator space is appended before the new list element unless
-the list element is going to be the first element in a list or
-sublist (i.e. the variable's current value is empty, or contains
-the single character ``{'', or ends in `` }'').
-.TP
-\fBTCL_PARSE_PART1\fR
-If this bit is set,
-then \fBTcl_ObjGetVar2\fR and \fBTcl_ObjSetVar2\fR
-will parse \fIpart1Ptr\fR
-to obtain both an array name and an element name.
-If the name in \fIpart1Ptr\fR contains an open parenthesis
-and ends with a close parenthesis,
-the name is treated as the name of an element of an array;
-otherwise, the name in \fIpart1Ptr\fR
-is interpreted as the name of a scalar variable.
-When this bit is set,
-\fIpart2Ptr\fR is ignored.
-.PP
-\fBTcl_ObjGetVar2\fR returns the value of the specified variable.
-Its arguments are treated the same way as those for \fBTcl_ObjSetVar2\fR.
-It returns a pointer to the object which is the variable's value.
-The reference count for the returned object is not incremented.
-If the caller needs to keep a reference to the object,
-say in a data structure,
-it must increment the reference count using \fBTcl_IncrRefCount\fR.
-If an error occurs in setting the variable
-(e.g. an array variable is referenced
-without giving an index into the array),
-then NULL is returned.
-
-.SH "SEE ALSO"
-Tcl_GetObjResult, Tcl_GetStringResult, Tcl_GetVar, Tcl_GetVar2, Tcl_SetVar, Tcl_SetVar2, Tcl_TraceVar, Tcl_UnsetVar, Tcl_UnsetVar2
-
-.SH KEYWORDS
-array, interpreter, object, scalar, set, unset, variable
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) @(#) Object.3 1.10 97/07/22 11:40:10
+'\" RCS: @(#) $Id: Object.3,v 1.4 1999/08/09 16:30:34 hobbs Exp $
 '\" 
 .so man.macros
 .TH Tcl_Obj 3 8.0 Tcl "Tcl Library Procedures"
@@ -85,7 +85,7 @@ Because of this representation invalidation and regeneration,
 it is dangerous for extension writers to access
 \fBTcl_Obj\fR fields directly.
 It is better to access Tcl_Obj information using
-procedures like \fBTcl_GetStringFromObj\fR.
+procedures like \fBTcl_GetStringFromObj\fR and \fBTcl_GetString\fR.
 .PP
 Objects are allocated on the heap
 and are referenced using a pointer to their \fBTcl_Obj\fR structure.
@@ -138,7 +138,7 @@ The byte array must always have a null after the last byte,
 at offset \fIlength\fR;
 this allows string representations that do not contain nulls
 to be treated as conventional null-terminated C strings.
-C programs use \fBTcl_GetStringFromObj\fR to get
+C programs use \fBTcl_GetStringFromObj\fR and \fBTcl_GetString\fR to get
 an object's string representation.
 If \fIbytes\fR is NULL,
 the string representation is invalid.
@@ -177,7 +177,8 @@ An object typically starts out containing only a string representation:
 it is untyped and has a NULL \fItypePtr\fR.
 An object containing an empty string or a copy of a specified string
 is created using \fBTcl_NewObj\fR or \fBTcl_NewStringObj\fR respectively.
-An object's string value is gotten with \fBTcl_GetStringFromObj\fR
+An object's string value is gotten with
+\fBTcl_GetStringFromObj\fR or \fBTcl_GetString\fR
 and changed with \fBTcl_SetStringObj\fR.
 If the object is later passed to a procedure like \fBTcl_GetIntFromObj\fR
 that requires a specific internal representation,
@@ -187,7 +188,7 @@ An object's two representations are duals of each other:
 changes made to one are reflected in the other.
 For example, \fBTcl_ListObjReplace\fR will modify an object's
 internal representation and the next call to \fBTcl_GetStringFromObj\fR
-will reflect that change.
+or \fBTcl_GetString\fR will reflect that change.
 .PP
 Representations are recomputed lazily for efficiency.
 A change to one representation made by a procedure
@@ -208,7 +209,7 @@ free any storage associated with the old string representation.
 Objects usually remain one type over their life,
 but occasionally an object must be converted from one type to another.
 For example, a C program might build up a string in an object
-with repeated calls to \fBTcl_StringObjAppend\fR,
+with repeated calls to \fBTcl_AppendToObj\fR,
 and then call \fBTcl_ListObjIndex\fR to extract a list element from
 the object.
 The same object holding the same string value
@@ -292,7 +293,7 @@ reference to it from the formal parameter.
 When the called procedure returns,
 the interpreter calls \fBTcl_DecrRefCount\fR to decrement
 each argument's reference count.
-When an object's reference count drops to zero,
+When an object's reference count drops less than or equal to zero,
 \fBTcl_DecrRefCount\fR reclaims its storage.
 Most command procedures do not have to be concerned about
 reference counting since they use an object's value immediately
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) ObjectType.3 1.8 97/04/30 15:42:29
+'\" RCS: @(#) $Id: ObjectType.3,v 1.2 1998/09/14 18:39:49 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_ObjType 3 8.0 Tcl "Tcl Library Procedures"
@@ -4,13 +4,13 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-'\" SCCS: @(#) OpenFileChnl.3 1.40 97/09/29 11:22:49
+'\" RCS: @(#) $Id: OpenFileChnl.3,v 1.7 1999/08/21 19:40:47 hobbs Exp $
 .so man.macros
-.TH Tcl_OpenFileChannel 3 8.0 Tcl "Tcl Library Procedures"
+.TH Tcl_OpenFileChannel 3 8.3 Tcl "Tcl Library Procedures"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-Tcl_OpenFileChannel, Tcl_OpenCommandChannel, Tcl_MakeFileChannel, Tcl_GetChannel, Tcl_RegisterChannel, Tcl_UnregisterChannel, Tcl_Close, Tcl_Read, Tcl_Gets, Tcl_Write, Tcl_Flush, Tcl_Seek, Tcl_Tell, Tcl_Eof, Tcl_InputBlocked, Tcl_InputBuffered, Tcl_GetChannelOption, Tcl_SetChannelOption \- buffered I/O facilities using channels
+Tcl_OpenFileChannel, Tcl_OpenCommandChannel, Tcl_MakeFileChannel, Tcl_GetChannel, Tcl_GetChannelNames, Tcl_GetChannelNamesEx, Tcl_RegisterChannel, Tcl_UnregisterChannel, Tcl_Close, Tcl_ReadChars, Tcl_Read, Tcl_GetsObj, Tcl_Gets, Tcl_WriteObj, Tcl_WriteChars, Tcl_Write, Tcl_Flush, Tcl_Seek, Tcl_Tell, Tcl_GetChannelOption, Tcl_SetChannelOption, Tcl_Eof, Tcl_InputBlocked, Tcl_InputBuffered \- buffered I/O facilities using channels
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -22,7 +22,7 @@ Tcl_Channel
 .sp
 Tcl_Channel
 \fBTcl_OpenCommandChannel\fR(\fIinterp, argc, argv, flags\fR)
-.VS
+.VS 8.0
 .sp
 Tcl_Channel
 \fBTcl_MakeFileChannel\fR(\fIhandle, readOrWrite\fR)
@@ -30,6 +30,14 @@ Tcl_Channel
 .sp
 Tcl_Channel
 \fBTcl_GetChannel\fR(\fIinterp, channelName, modePtr\fR)
+.VS 8.3
+.sp
+int
+\fBTcl_GetChannelNames\fR(\fIinterp\fR)
+.sp
+int
+\fBTcl_GetChannelNamesEx\fR(\fIinterp, pattern\fR)
+.VE
 .sp
 void
 \fBTcl_RegisterChannel\fR(\fIinterp, channel\fR)
@@ -40,17 +48,28 @@ int
 int
 \fBTcl_Close\fR(\fIinterp, channel\fR)
 .sp
+.VS 8.1
 int
-\fBTcl_Read\fR(\fIchannel, buf, toRead\fR)
+\fBTcl_ReadChars\fR(\fIchannel, readObjPtr, charsToRead, appendFlag\fR)
 .sp
 int
-\fBTcl_Gets\fR(\fIchannel, lineRead\fR)
+\fBTcl_Read\fR(\fIchannel, byteBuf, bytesToRead\fR)
 .sp
 int
 \fBTcl_GetsObj\fR(\fIchannel, lineObjPtr\fR)
 .sp
 int
-\fBTcl_Write\fR(\fIchannel, buf, toWrite\fR)
+\fBTcl_Gets\fR(\fIchannel, lineRead\fR)
+.sp
+int
+\fBTcl_WriteObj\fR(\fIchannel, writeObjPtr\fR)
+.sp
+int
+\fBTcl_WriteChars\fR(\fIchannel, charBuf, bytesToWrite\fR)
+.sp
+int
+\fBTcl_Write\fR(\fIchannel, byteBuf, bytesToWrite\fR)
+.VE
 .sp
 int
 \fBTcl_Flush\fR(\fIchannel\fR)
@@ -83,37 +102,36 @@ Used for error reporting and to look up a channel registered in it.
 .AP char *fileName in
 The name of a local or network file.
 .AP char *mode in
-Specifies how the file is to be accessed.  May have any of the
-values allowed for the \fImode\fR argument to the Tcl
-\fBopen\fR command.
-For \fBTcl_OpenCommandChannel\fR, may be NULL.
+Specifies how the file is to be accessed.  May have any of the values
+allowed for the \fImode\fR argument to the Tcl \fBopen\fR command.  For
+\fBTcl_OpenCommandChannel\fR, may be NULL.
 .AP int permissions in
-POSIX-style permission flags such as 0644.
-If a new file is created, these permissions will be set on the
-created file.
+POSIX-style permission flags such as 0644.  If a new file is created, these
+permissions will be set on the created file.
 .AP int argc in
 The number of elements in \fIargv\fR.
 .AP char **argv in
-Arguments for constructing a command pipeline.
-These values have the same meaning as the non-switch arguments
-to the Tcl \fBexec\fR command.
+Arguments for constructing a command pipeline.  These values have the same
+meaning as the non-switch arguments to the Tcl \fBexec\fR command.
 .AP int flags in
 Specifies the disposition of the stdio handles in pipeline: OR-ed
-combination of \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, \fBTCL_STDERR\fR,
-and \fBTCL_ENFORCE_MODE\fR. If \fBTCL_STDIN\fR is set, stdin for
-the first child in the pipe is the pipe channel, otherwise it is the same
-as the standard input of the invoking process; likewise for
-\fBTCL_STDOUT\fR and \fBTCL_STDERR\fR. If \fBTCL_ENFORCE_MODE\fR is not set,
-then the pipe can redirect stdio handles to override the stdio handles for
-which \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR and \fBTCL_STDERR\fR have been set.
-If it is set, then such redirections cause an error.
-.VS
+combination of \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, \fBTCL_STDERR\fR, and
+\fBTCL_ENFORCE_MODE\fR. If \fBTCL_STDIN\fR is set, stdin for the first child
+in the pipe is the pipe channel, otherwise it is the same as the standard
+input of the invoking process; likewise for \fBTCL_STDOUT\fR and
+\fBTCL_STDERR\fR. If \fBTCL_ENFORCE_MODE\fR is not set, then the pipe can
+redirect stdio handles to override the stdio handles for which
+\fBTCL_STDIN\fR, \fBTCL_STDOUT\fR and \fBTCL_STDERR\fR have been set.  If it
+is set, then such redirections cause an error.
+.VS 8.0
 .AP ClientData handle in
 Operating system specific handle for I/O to a file. For Unix this is a
 file descriptor, for Windows it is a HANDLE.
 .AP int readOrWrite in
 OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR to indicate
 what operations are valid on \fIhandle\fR.
+.AP char *channelName in
+The name of the channel. 
 .VE
 .AP int *modePtr out
 Points at an integer variable that will receive an OR-ed combination of
@@ -122,26 +140,40 @@ open for reading and writing.
 .AP Tcl_Channel channel in
 A Tcl channel for input or output.  Must have been the return value
 from a procedure such as \fBTcl_OpenFileChannel\fR.
-.AP char *buf in
-An array of bytes in which to store channel input, or from which
-to read channel output.
-.AP int len in
-The length of the input or output.
-.AP int atEnd in
-If nonzero, store the input at the end of the input queue, otherwise store
-it at the head of the input queue.
-.AP int toRead in
-The number of bytes to read from the channel.
-.AP Tcl_DString *lineRead in
-A pointer to a Tcl dynamic string in which to store the line read from the
-channel.  Must have been initialized by the caller.  The line read
-will be appended to any data already in the dynamic string.
-.AP Tcl_Obj *linePtrObj in
+.VS 8.1 br
+.AP Tcl_Obj *readObjPtr in/out
+A pointer to a Tcl Object in which to store the characters read from the
+channel.
+.AP int charsToRead in
+The number of characters to read from the channel.  If the channel's encoding 
+is \fBbinary\fR, this is equivalent to the number of bytes to read from the 
+channel.
+.AP int appendFlag in
+If non-zero, data read from the channel will be appended to the object.
+Otherwise, the data will replace the existing contents of the object.
+.AP char *readBuf out
+A buffer in which to store the bytes read from the channel.
+.AP int bytesToRead in
+The number of bytes to read from the channel.  The buffer \fIreadBuf\fR must
+be large enough to hold this many bytes.
+.AP Tcl_Obj *lineObjPtr in/out
 A pointer to a Tcl object in which to store the line read from the
 channel.  The line read will be appended to the current value of the
 object. 
-.AP int toWrite in
-The number of bytes to read from \fIbuf\fR and output to the channel.
+.AP Tcl_DString *lineRead in/out
+A pointer to a Tcl dynamic string in which to store the line read from the
+channel.  Must have been initialized by the caller.  The line read will be
+appended to any data already in the dynamic string.
+.AP Tcl_Obj *writeObjPtr in
+A pointer to a Tcl Object whose contents will be output to the channel.
+.AP "CONST char" *charBuf in
+A buffer containing the characters to output to the channel.
+.AP char *byteBuf in
+A buffer containing the bytes to output to the channel.
+.AP int bytesToWrite in
+The number of bytes to consume from \fIcharBuf\fR or \fIbyteBuf\fR and
+output to the channel.
+.VE
 .AP int offset in
 How far to move the access point in the channel at which the next input or
 output operation will be applied, measured in bytes from the position
@@ -158,6 +190,10 @@ Where to store the value of an option or a list of all options and their
 values. Must have been initialized by the caller.
 .AP char *newValue in
 New value for the option given by \fIoptionName\fR.
+.VS 8.3
+.AP char *pattern in
+The pattern to match on, passed to Tcl_StringMatch, or NULL.
+.VE
 .BE

 .SH DESCRIPTION
@@ -169,7 +205,7 @@ types.
 The channel mechanism is extensible to new channel types, by
 providing a low level channel driver for the new type; the channel driver
 interface is described in the manual entry for \fBTcl_CreateChannel\fR. The
-channel mechanism provides a buffering scheme modelled after
+channel mechanism provides a buffering scheme modeled after
 Unix's standard I/O, and it also allows for nonblocking I/O on
 channels.
 .PP
@@ -182,7 +218,7 @@ channels, see the manual entry for \fBTcl_CreateChannel\fR.
 .PP
 \fBTcl_OpenFileChannel\fR opens a file specified by \fIfileName\fR and
 returns a channel handle that can be used to perform input and output on
-the file. This API is modelled after the \fBfopen\fR procedure of
+the file. This API is modeled after the \fBfopen\fR procedure of
 the Unix standard I/O library.
 The syntax and meaning of all arguments is similar to those
 given in the Tcl \fBopen\fR command when opening a file.
@@ -190,7 +226,7 @@ If an error occurs while opening the channel, \fBTcl_OpenFileChannel\fR
 returns NULL and records a POSIX error code that can be
 retrieved with \fBTcl_GetErrno\fR.
 In addition, if \fIinterp\fR is non-NULL, \fBTcl_OpenFileChannel\fR
-leaves an error message in \fIinterp->result\fR after any error.
+leaves an error message in \fIinterp\fR's result after any error.
 .PP
 The newly created channel is not registered in the supplied interpreter; to
 register it, use \fBTcl_RegisterChannel\fR, described below.
@@ -255,6 +291,14 @@ the procedure returns NULL. If the \fImode\fR argument is not NULL, it
 points at an integer variable that will receive an OR-ed combination of
 \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR describing whether the channel is
 open for reading and writing.
+.PP
+\fBTcl_GetChannelNames\fR and \fBTcl_GetChannelNamesEx\fR write the
+names of the registered channels to the interpreter's result as a
+list object.  \fBTcl_GetChannelNamesEx\fR will filter these names
+according to the \fIpattern\fR.  If \fIpattern\fR is NULL, then it
+will not do any filtering.  The return value is \fBTCL_OK\fR if no
+errors occured writing to the result, otherwise it is \fBTCL_ERROR\fR,
+and the error message is left in the interpreter's result.

 .SH TCL_REGISTERCHANNEL
 .PP
@@ -306,97 +350,140 @@ If an error occurs, \fBTcl_Close\fR returns \fBTCL_ERROR\fR and records a
 POSIX error code that can be retrieved with \fBTcl_GetErrno\fR.
 If the channel is being closed synchronously and an error occurs during
 closing of the channel and \fIinterp\fR is not NULL, an error message is
-left in \fIinterp->result\fR.
+left in the interpreter's result.
 .PP
 Note: it is not safe to call \fBTcl_Close\fR on a channel that has been
 registered using \fBTcl_RegisterChannel\fR; see the documentation for
-\fBTcl_RegisterChannel\fR, above, for details. If the channel has ever been
-given as the \fBchan\fR argument in a call to \fBTcl_RegisterChannel\fR,
-you should instead use \fBTcl_UnregisterChannel\fR, which will internally
-call \fBTcl_Close\fR when all calls to \fBTcl_RegisterChannel\fR have been
-matched by corresponding calls to \fBTcl_UnregisterChannel\fR.
+\fBTcl_RegisterChannel\fR, above, for details. If the channel has ever
+been given as the \fBchan\fR argument in a call to
+\fBTcl_RegisterChannel\fR, you should instead use
+\fBTcl_UnregisterChannel\fR, which will internally call \fBTcl_Close\fR
+when all calls to \fBTcl_RegisterChannel\fR have been matched by
+corresponding calls to \fBTcl_UnregisterChannel\fR.

-.SH TCL_READ
+.VS 8.1 br
+.SH "TCL_READCHARS AND TCL_READ"
 .PP
-\fBTcl_Read\fR consumes up to \fItoRead\fR bytes of data from
-\fIchannel\fR and stores it at \fIbuf\fR.
-The return value of \fBTcl_Read\fR is the number of characters written
-at \fIbuf\fR.
-The buffer produced by \fBTcl_Read\fR is not NULL terminated. Its contents
-are valid from the zeroth position up to and excluding the position
-indicated by the return value.
-If an error occurs, the return value is -1 and \fBTcl_Read\fR records
-a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR.
+\fBTcl_ReadChars\fR consumes bytes from \fIchannel\fR, converting the bytes
+to UTF-8 based on the channel's encoding and storing the produced data in 
+\fIreadObjPtr\fR's string representation.  The return value of
+\fBTcl_ReadChars\fR is the number of characters, up to \fIcharsToRead\fR,
+that were stored in \fIobjPtr\fR.  If an error occurs while reading, the
+return value is \-1 and \fBTcl_ReadChars\fR records a POSIX error code that
+can be retrieved with \fBTcl_GetErrno\fR.
 .PP
-The return value may be smaller than the value of \fItoRead\fR, indicating
-that less data than requested was available, also called a \fIshort
-read\fR.
-In blocking mode, this can only happen on an end-of-file.
-In nonblocking mode, a short read can also occur if there is not
-enough input currently available:  \fBTcl_Read\fR returns a short
-count rather than waiting for more data.
+The return value may be smaller than the value to read, indicating that less
+data than requested was available.  This is called a \fIshort read\fR.  In
+blocking mode, this can only happen on an end-of-file.  In nonblocking mode,
+a short read can also occur if there is not enough input currently
+available:  \fBTcl_ReadChars\fR returns a short count rather than waiting
+for more data.
 .PP
-If the channel is in blocking mode, a return value of zero indicates an end
-of file condition. If the channel is in nonblocking mode, a return value of
-zero indicates either that no input is currently available or an end of
-file condition. Use \fBTcl_Eof\fR and \fBTcl_InputBlocked\fR
-to tell which of these conditions actually occurred.
+If the channel is in blocking mode, a return value of zero indicates an
+end-of-file condition.  If the channel is in nonblocking mode, a return
+value of zero indicates either that no input is currently available or an
+end-of-file condition.  Use \fBTcl_Eof\fR and \fBTcl_InputBlocked\fR to tell
+which of these conditions actually occurred.
 .PP
-\fBTcl_Read\fR translates platform-specific end-of-line representations
-into the canonical \fB\en\fR internal representation according to the
-current end-of-line recognition mode. End-of-line recognition and the
-various platform-specific modes are described in the manual entry for the
-Tcl \fBfconfigure\fR command.
+\fBTcl_ReadChars\fR translates the various end-of-line representations into
+the canonical \fB\en\fR internal representation according to the current
+end-of-line recognition mode.  End-of-line recognition and the various
+platform-specific modes are described in the manual entry for the Tcl
+\fBfconfigure\fR command.
+.PP
+As a performance optimization, when reading from a channel with the encoding
+\fBbinary\fR, the bytes are not converted to UTF-8 as they are read.
+Instead, they are stored in \fIreadObjPtr\fR's internal representation as a
+byte-array object.  The string representation of this object will only be
+constructed if it is needed (e.g., because of a call to
+\fBTcl_GetStringFromObj\fR).  In this way, byte-oriented data can be read
+from a channel, manipulated by calling \fBTcl_GetByteArrayFromObj\fR and
+related functions, and then written to a channel without the expense of ever
+converting to or from UTF-8.
+.PP
+\fBTcl_Read\fR is similar to \fBTcl_ReadChars\fR, except that it doesn't do
+encoding conversions, regardless of the channel's encoding.  It is deprecated
+and exists for backwards compatibility with non-internationalized Tcl
+extensions.  It consumes bytes from \fIchannel\fR and stores them in
+\fIbuf\fR, performing end-of-line translations on the way.  The return value
+of \fBTcl_Read\fR is the number of bytes, up to \fItoRead\fR, written in
+\fIbuf\fR.  The buffer produced by \fBTcl_Read\fR is not NULL terminated.
+Its contents are valid from the zeroth position up to and excluding the
+position indicated by the return value.  

-.SH TCL_GETS AND TCL_GETSOBJ
+.SH "TCL_GETSOBJ AND TCL_GETS"
 .PP
-\fBTcl_Gets\fR reads a line of input from a channel and appends all of
-the characters of the line except for the terminating end-of-line character(s)
-to the dynamic string given by \fIdsPtr\fR.
-The end-of-line character(s) are read and discarded.
+\fBTcl_GetsObj\fR consumes bytes from \fIchannel\fR, converting the bytes to
+UTF-8 based on the channel's encoding, until a full line of input has been
+seen.  If the channel's encoding is \fBbinary\fR, each byte read from the
+channel is treated as an individual Unicode character.  All of the
+characters of the line except for the terminating end-of-line character(s)
+are appended to \fIlineObjPtr\fR's string representation.  The end-of-line
+character(s) are read and discarded.
 .PP
-If a line was successfully read, the return value is greater than or
-equal to zero, and it indicates the number of characters stored
-in the dynamic string.
-If an error occurs, \fBTcl_Gets\fR returns -1 and records a POSIX error
-code that can be retrieved with \fBTcl_GetErrno\fR.
-\fBTcl_Gets\fR also returns -1 if the end of the file is reached;
-the \fBTcl_Eof\fR procedure can be used to distinguish an error
-from an end-of-file condition.
+If a line was successfully read, the return value is greater than or equal
+to zero and indicates the number of bytes stored in \fIlineObjPtr\fR.  If an
+error occurs, \fBTcl_GetsObj\fR returns \-1 and records a POSIX error code
+that can be retrieved with \fBTcl_GetErrno\fR.  \fBTcl_GetsObj\fR also
+returns \-1 if the end of the file is reached; the \fBTcl_Eof\fR procedure
+can be used to distinguish an error from an end-of-file condition.
 .PP
-If the channel is in nonblocking mode, the return value can also
-be -1 if no data was available or the data that was available
-did not contain an end-of-line character.
-When -1 is returned, the \fBTcl_InputBlocked\fR procedure may be
-invoked to determine if the channel is blocked because of input
-unavailability.
+If the channel is in nonblocking mode, the return value can also be \-1 if
+no data was available or the data that was available did not contain an
+end-of-line character.  When \-1 is returned, the \fBTcl_InputBlocked\fR
+procedure may be invoked to determine if the channel is blocked because
+of input unavailability.
 .PP
-\fBTcl_GetsObj\fR is the same as \fBTcl_Gets\fR except the resulting
-characters are appended to a Tcl object \fBlineObjPtr\fR rather than a
-dynamic string.
-.SH TCL_WRITE
+\fBTcl_Gets\fR is the same as \fBTcl_GetsObj\fR except the resulting
+characters are appended to the appended to the dynamic string given by
+\fIdsPtr\fR rather than a Tcl object.
+
+.SH "TCL_WRITECHARS, TCL_WRITEOBJ, AND TCL_WRITE"
 .PP
-\fBTcl_Write\fR accepts \fItoWrite\fR bytes of data at \fIbuf\fR for output
-on \fIchannel\fR. This data may not appear on the output device
-immediately. If the data should appear immediately, call \fBTcl_Flush\fR
-after the call to \fBTcl_Write\fR, or set the \fB-buffering\fR option on
-the channel to \fBnone\fR. If you wish the data to appear as soon as an end
-of line is accepted for output, set the \fB\-buffering\fR option on the
-channel to \fBline\fR mode.
-.PP
-The \fItoWrite\fR argument specifies how many bytes of data are provided in
-the \fIbuf\fR argument. If it is negative, \fBTcl_Write\fR expects the data
+\fBTcl_WriteChars\fR accepts \fIbytesToWrite\fR bytes of character data at
+\fIcharBuf\fR.  The UTF-8 characters in the buffer are converted to the
+channel's encoding and queued for output to \fIchannel\fR.  If
+\fIbytesToWrite\fR is negative, \fBTcl_WriteChars\fR expects \fIcharBuf\fR
 to be NULL terminated and it outputs everything up to the NULL.
 .PP
-The return value of \fBTcl_Write\fR is a count of how many
-characters were accepted for output to the channel. This is either equal to
-\fItoWrite\fR or -1 to indicate that an error occurred.
-If an error occurs, \fBTcl_Write\fR also records a POSIX error code
-that may be retrieved with \fBTcl_GetErrno\fR.
+Data queued for output may not appear on the output device immediately, due
+to internal buffering.  If the data should appear immediately, call
+\fBTcl_Flush\fR after the call to \fBTcl_WriteChars\fR, or set the 
+\fB\-buffering\fR option on the channel to \fBnone\fR.  If you wish the data
+to appear as soon as a complete line is accepted for output, set the
+\fB\-buffering\fR option on the channel to \fBline\fR mode.
+.PP
+The return value of \fBTcl_WriteChars\fR is a count of how many bytes were
+accepted for output to the channel.  This is either greater than zero to
+indicate success or \-1 to indicate that an error occurred.  If an error
+occurs, \fBTcl_WriteChars\fR records a POSIX error code that may be
+retrieved with \fBTcl_GetErrno\fR.
 .PP
 Newline characters in the output data are translated to platform-specific
-end-of-line sequences according to the \fB\-translation\fR option for
-the channel.
+end-of-line sequences according to the \fB\-translation\fR option for the
+channel.  This is done even if the channel has no encoding.
+.PP
+\fBTcl_WriteObj\fR is similar to \fBTcl_WriteChars\fR except it
+accepts a Tcl object whose contents will be output to the channel.  The
+UTF-8 characters in \fIwriteObjPtr\fR's string representation are converted
+to the channel's encoding and queued for output to \fIchannel\fR.  
+As a performance optimization, when writing to a channel with the encoding
+\fBbinary\fR, UTF-8 characters are not converted as they are written.
+Instead, the bytes in \fIwriteObjPtr\fR's internal representation as a
+byte-array object are written to the channel.  The byte-array representation
+of the object will be constructed if it is needed.  In this way,
+byte-oriented data can be read from a channel, manipulated by calling
+\fBTcl_GetByteArrayFromObj\fR and related functions, and then written to a
+channel without the expense of ever converting to or from UTF-8.
+.PP
+\fBTcl_Write\fR is similar to \fBTcl_WriteChars\fR except that it doesn't do
+encoding conversions, regardless of the channel's encoding.  It is
+deprecated and exists for backwards compatibility with non-internationalized
+Tcl extensions.  It accepts \fIbytesToWrite\fR bytes of data at
+\fIbyteBuf\fR and queues them for output to \fIchannel\fR.  If
+\fIbytesToWrite\fR is negative, \fBTcl_Write\fR expects \fIbyteBuf\fR to be
+NULL terminated and it outputs everything up to the NULL.
+.VE

 .SH TCL_FLUSH
 .PP
@@ -419,14 +506,14 @@ data will be read or written. Buffered output is flushed to the channel and
 buffered input is discarded, prior to the seek operation.
 .PP
 \fBTcl_Seek\fR normally returns the new access point.
-If an error occurs, \fBTcl_Seek\fR returns -1 and records a POSIX error
+If an error occurs, \fBTcl_Seek\fR returns \-1 and records a POSIX error
 code that can be retrieved with \fBTcl_GetErrno\fR.
 After an error, the access point may or may not have been moved.

 .SH TCL_TELL
 .PP
 \fBTcl_Tell\fR returns the current access point for a channel. The returned
-value is -1 if the channel does not support seeking.
+value is \-1 if the channel does not support seeking.

 .SH TCL_GETCHANNELOPTION
 .PP
@@ -477,7 +564,7 @@ The call always returns zero if the channel is in blocking mode.
 buffered in the internal buffers for a channel. If the channel is not open
 for reading, this function always returns zero.

-.VS
+.VS 8.0
 .SH "PLATFORM ISSUES"
 .PP
 The handles returned from \fBTcl_GetChannelHandle\fR depend on the
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-'\" SCCS: @(#) OpenTcp.3 1.19 97/06/25 14:44:00
+'\" RCS: @(#) $Id: OpenTcp.3,v 1.2 1998/09/14 18:39:49 stanton Exp $
 .so man.macros
 .TH Tcl_OpenTcpClient 3 8.0 Tcl "Tcl Library Procedures"
 .BS
@@ -0,0 +1,426 @@
+'\"
+'\" 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.
+'\" 
+'\" RCS: @(#) $Id: ParseCmd.3,v 1.3 1999/08/21 19:40:47 hobbs Exp $
+'\" 
+.so man.macros
+.TH Tcl_ParseCommand 3 8.1 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_ParseCommand, Tcl_ParseExpr, Tcl_ParseBraces, Tcl_ParseQuotedString, Tcl_ParseVarName, Tcl_FreeParse, Tcl_EvalTokens \- parse Tcl scripts and expressions
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+int
+\fBTcl_ParseCommand\fR(\fIinterp, string, numBytes, nested, parsePtr\fR)
+.sp
+int
+\fBTcl_ParseExpr\fR(\fIinterp, string, numBytes, parsePtr\fR)
+.sp
+int
+\fBTcl_ParseBraces\fR(\fIinterp, string, numBytes, parsePtr, append, termPtr\fR)
+.sp
+int
+\fBTcl_ParseQuotedString\fR(\fIinterp, string, numBytes, parsePtr, append, termPtr\fR)
+.sp
+int
+\fBTcl_ParseVarName\fR(\fIinterp, string, numBytes, parsePtr, append\fR)
+.sp
+\fBTcl_FreeParse\fR(\fIusedParsePtr\fR)
+.sp
+Tcl_Obj *
+\fBTcl_EvalTokens\fR(\fIinterp, tokenPtr, numTokens\fR)
+.SH ARGUMENTS
+.AS Tcl_Interp *usedParsePtr
+.AP Tcl_Interp *interp out
+For procedures other than \fBTcl_FreeParse\fR and \fBTcl_EvalTokens\fR,
+used only for error reporting;
+if NULL, then no error messages are left after errors.
+For \fBTcl_EvalTokens\fR, determines the context for evaluating the
+script and also is used for error reporting; must not be NULL.
+.AP char *string in
+Pointer to first character in string to parse.
+.AP int numBytes in
+Number of bytes in \fIstring\fR, not including any terminating null
+character.  If less than 0 then the script consists of all characters
+in \fIstring\fR up to the first null character.
+.AP int nested in
+Non-zero means that the script is part of a command substitution so an
+unquoted close bracket should be treated as a command terminator.  If zero,
+close brackets have no special meaning. 
+.AP int append in
+Non-zero means that \fI*parsePtr\fR already contains valid tokens; the new
+tokens should be appended to those already present.  Zero means that
+\fI*parsePtr\fR is uninitialized; any information in it is ignored.
+This argument is normally 0.
+.AP Tcl_Parse *parsePtr out
+Points to structure to fill in with information about the parsed
+command, expression, variable name, etc.
+Any previous information in this structure
+is ignored, unless \fIappend\fR is non-zero in a call to
+\fBTcl_ParseBraces\fR, \fBTcl_ParseQuotedString\fR,
+or \fBTcl_ParseVarName\fR.
+.AP char **termPtr out
+If not NULL, points to a location where
+\fBTcl_ParseBraces\fR and \fBTcl_ParseQuotedString\fR
+will store a pointer to the character
+just after the terminating close-brace or close-quote (respectively)
+if the parse was successful.
+.AP Tcl_Parse *usedParsePtr in
+Points to structure that was filled in by a previous call to
+\fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseVarName\fR, etc.
+.BE
+
+.SH DESCRIPTION
+.PP
+These procedures parse Tcl commands or portions of Tcl commands such as
+expressions or references to variables.
+Each procedure takes a pointer to a script (or portion thereof)
+and fills in the structure pointed to by \fIparsePtr\fR
+with a collection of tokens describing the information that was parsed.
+The procedures normally return \fBTCL_OK\fR.
+However, if an error occurs then they return \fBTCL_ERROR\fR,
+leave an error message in \fIinterp's\fR result
+(if \fIinterp\fR is not NULL),
+and leave nothing in \fIparsePtr\fR.
+.PP
+\fBTcl_ParseCommand\fR is a procedure that parses Tcl
+scripts.  Given a pointer to a script, it
+parses the first command from the script.  If the command was parsed
+successfully, \fBTcl_ParseCommand\fR returns \fBTCL_OK\fR and fills in the
+structure pointed to by \fIparsePtr\fR with information about the
+structure of the command (see below for details).
+If an error occurred in parsing the command then
+\fBTCL_ERROR\fR is returned, an error message is left in \fIinterp\fR's
+result, and no information is left at \fI*parsePtr\fR.
+.PP
+\fBTcl_ParseExpr\fR parses Tcl expressions.
+Given a pointer to a script containing an expression,
+\fBTcl_ParseCommand\fR parses the expression.
+If the expression was parsed successfully,
+\fBTcl_ParseExpr\fR returns \fBTCL_OK\fR and fills in the
+structure pointed to by \fIparsePtr\fR with information about the
+structure of the expression (see below for details).
+If an error occurred in parsing the command then
+\fBTCL_ERROR\fR is returned, an error message is left in \fIinterp\fR's
+result, and no information is left at \fI*parsePtr\fR.
+.PP
+\fBTcl_ParseBraces\fR parses a string or command argument
+enclosed in braces such as
+\fB{hello}\fR or \fB{string \\t with \\t tabs}\fR
+from the beginning of its argument \fIstring\fR.
+The first character of \fIstring\fR must be \fB{\fR. 
+If the braced string was parsed successfully,
+\fBTcl_ParseBraces\fR returns \fBTCL_OK\fR,
+fills in the structure pointed to by \fIparsePtr\fR
+with information about the structure of the string
+(see below for details),
+and stores a pointer to the character just after the terminating \fB}\fR
+in the location given by \fI*termPtr\fR.
+If an error occurrs while parsing the string
+then \fBTCL_ERROR\fR is returned,
+an error message is left in \fIinterp\fR's result,
+and no information is left at \fI*parsePtr\fR or \fI*termPtr\fR.
+.PP
+\fBTcl_ParseQuotedString\fR parses a double-quoted string such as
+\fB"sum is [expr $a+$b]"\fR
+from the beginning of the argument \fIstring\fR.
+The first character of \fIstring\fR must be \fB"\fR. 
+If the double-quoted string was parsed successfully,
+\fBTcl_ParseQuotedString\fR returns \fBTCL_OK\fR,
+fills in the structure pointed to by \fIparsePtr\fR
+with information about the structure of the string
+(see below for details),
+and stores a pointer to the character just after the terminating \fB"\fR
+in the location given by \fI*termPtr\fR.
+If an error occurrs while parsing the string
+then \fBTCL_ERROR\fR is returned,
+an error message is left in \fIinterp\fR's result,
+and no information is left at \fI*parsePtr\fR or \fI*termPtr\fR.
+.PP
+\fBTcl_ParseVarName\fR parses a Tcl variable reference such as
+\fB$abc\fR or \fB$x([expr $index + 1])\fR from the beginning of its
+\fIstring\fR argument.
+The first character of \fIstring\fR must be \fB$\fR. 
+If a variable name was parsed successfully, \fBTcl_ParseVarName\fR
+returns \fBTCL_OK\fR and fills in the structure pointed to by
+\fIparsePtr\fR with information about the structure of the variable name
+(see below for details).  If an error
+occurrs while parsing the command then \fBTCL_ERROR\fR is returned, an
+error message is left in \fIinterp\fR's result (if \fIinterp\fR isn't
+NULL), and no information is left at \fI*parsePtr\fR.
+.PP
+The information left at \fI*parsePtr\fR
+by \fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR,
+\fBTcl_ParseQuotedString\fR, and \fBTcl_ParseVarName\fR
+may include dynamically allocated memory.
+If these five parsing procedures return \fBTCL_OK\fR
+then the caller must invoke \fBTcl_FreeParse\fR to release
+the storage at \fI*parsePtr\fR.
+These procedures ignore any existing information in
+\fI*parsePtr\fR (unless \fIappend\fR is non-zero),
+so if repeated calls are being made to any of them
+then \fBTcl_FreeParse\fR must be invoked once after each call.
+.PP
+\fBTcl_EvalTokens\fR evaluates a sequence of parse tokens from a Tcl_Parse
+structure.  The tokens typically consist
+of all the tokens in a word or all the tokens that make up the index for
+a reference to an array variable.  \fBTcl_EvalTokens\fR performs the
+substitutions requested by the tokens, concatenates the
+resulting values, and returns the result in a new Tcl_Obj.  The
+reference count of the object returned as result has been
+incremented, so the caller must
+invoke \fBTcl_DecrRefCount\fR when it is finished with the object.
+If an error occurs while evaluating the tokens (such as a reference to
+a non-existent variable) then the return value is NULL and an error
+message is left in \fIinterp\fR's result.
+
+.SH "TCL_PARSE STRUCTURE"
+.PP
+\fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR,
+\fBTcl_ParseQuotedString\fR, and \fBTcl_ParseVarName\fR
+return parse information in two data structures, Tcl_Parse and Tcl_Token:
+.CS
+typedef struct Tcl_Parse {
+	char *\fIcommentStart\fR;
+	int \fIcommentSize\fR;
+	char *\fIcommandStart\fR;
+	int \fIcommandSize\fR;
+	int \fInumWords\fR;
+	Tcl_Token *\fItokenPtr\fR;
+	int \fInumTokens\fR;
+	...
+} Tcl_Parse;
+
+typedef struct Tcl_Token {
+    int \fItype\fR;
+    char *\fIstart\fR;
+    int \fIsize\fR;
+    int \fInumComponents\fR;
+} Tcl_Token;
+.CE
+.PP
+The first five fields of a Tcl_Parse structure
+are filled in only by \fBTcl_ParseCommand\fR.
+These fields are not used by the other parsing procedures.
+.PP
+\fBTcl_ParseCommand\fR fills in a Tcl_Parse structure
+with information that describes one Tcl command and any comments that
+precede the command.
+If there are comments,
+the \fIcommentStart\fR field points to the \fB#\fR character that begins
+the first comment and \fIcommentSize\fR indicates the number of bytes
+in all of the comments preceding the command, including the newline
+character that terminates the last comment.
+If the command is not preceded by any comments, \fIcommentSize\fR is 0.
+\fBTcl_ParseCommand\fR also sets the \fIcommandStart\fR field
+to point to the first character of the first
+word in the command (skipping any comments and leading space) and 
+\fIcommandSize\fR gives the total number of bytes in the command,
+including the character pointed to by \fIcommandStart\fR up to and
+including the newline, close bracket, or semicolon character that
+terminates the command.  The \fInumWords\fR field gives the
+total number of words in the command.
+.PP
+All parsing procedures set the remaining fields,
+\fItokenPtr\fR and \fInumTokens\fR.
+The \fItokenPtr\fR field points to the first in an array of Tcl_Token
+structures that describe the components of the entity being parsed.
+The \fInumTokens\fR field gives the total number of tokens
+present in the array.
+Each token contains four fields.
+The \fItype\fR field selects one of several token types
+that are described below.  The \fIstart\fR field
+points to the first character in the token and the \fIsize\fR field
+gives the total number of characters in the token.  Some token types,
+such as \fBTCL_TOKEN_WORD\fR and \fBTCL_TOKEN_VARIABLE\fR, consist of
+several component tokens, which immediately follow the parent token;
+the \fInumComponents\fR field describes how many of these there are.
+The \fItype\fR field has one of the following values:
+.TP 20
+\fBTCL_TOKEN_WORD\fR
+This token ordinarily describes one word of a command
+but it may also describe a quoted or braced string in an expression.
+The token describes a component of the script that is
+the result of concatenating together a sequence of subcomponents,
+each described by a separate subtoken.
+The token starts with the first non-blank
+character of the component (which may be a double-quote or open brace)
+and includes all characters in the component up to but not including the
+space, semicolon, close bracket, close quote, or close brace that
+terminates the component.  The \fInumComponents\fR field counts the total
+number of sub-tokens that make up the word, including sub-tokens
+of \fBTCL_TOKEN_VARIABLE\fR and \fBTCL_TOKEN_BS\fR tokens.
+.TP
+\fBTCL_TOKEN_SIMPLE_WORD\fR
+This token has the same meaning as \fBTCL_TOKEN_WORD\fR, except that
+the word is guaranteed to consist of a single \fBTCL_TOKEN_TEXT\fR
+sub-token.  The \fInumComponents\fR field is always 1.
+.TP
+\fBTCL_TOKEN_TEXT\fR
+The token describes a range of literal text that is part of a word.
+The \fInumComponents\fR field is always 0.
+.TP
+\fBTCL_TOKEN_BS\fR
+The token describes a backslash sequence such as \fB\en\fR or \fB\e0xa3\fR.
+The \fInumComponents\fR field is always 0.
+.TP
+\fBTCL_TOKEN_COMMAND\fR
+The token describes a command whose result result must be substituted into
+the word.  The token includes the square brackets that surround the
+command.  The \fInumComponents\fR field is always 0 (the nested command
+is not parsed; call \fBTcl_ParseCommand\fR recursively if you want to
+see its tokens).
+.TP
+\fBTCL_TOKEN_VARIABLE\fR
+The token describes a variable substitution, including the
+\fB$\fR, variable name, and array index (if there is one) up through the
+close parenthesis that terminates the index.  This token is followed
+by one or more additional tokens that describe the variable name and
+array index.  If \fInumComponents\fR  is 1 then the variable is a
+scalar and the next token is a \fBTCL_TOKEN_TEXT\fR token that gives the
+variable name.  If \fInumComponents\fR is greater than 1 then the
+variable is an array: the first sub-token is a \fBTCL_TOKEN_TEXT\fR
+token giving the array name and the remaining sub-tokens are
+\fBTCL_TOKEN_TEXT\fR, \fBTCL_TOKEN_BS\fR, \fBTCL_TOKEN_COMMAND\fR, and
+\fBTCL_TOKEN_VARIABLE\fR tokens that must be concatenated to produce the
+array index. The \fInumComponents\fR field includes nested sub-tokens
+that are part of \fBTCL_TOKEN_VARIABLE\fR tokens in the array index.
+.TP
+\fBTCL_TOKEN_SUB_EXPR\fR
+The token describes one subexpression of an expression
+(or an entire expression).
+A subexpression may consist of a value
+such as an integer literal, variable substitution,
+or parenthesized subexpression;
+it may also consist of an operator and its operands.
+The token starts with the first non-blank character of the subexpression
+up to but not including the space, brace, close-paren, or bracket
+that terminates the subexpression.
+This token is followed by one or more additional tokens
+that describe the subexpression.
+If the first sub-token after the \fBTCL_TOKEN_SUB_EXPR\fR token
+is a \fBTCL_TOKEN_OPERATOR\fR token,
+the subexpression consists of an operator and its token operands.
+If the operator has no operands, the subexpression consists of
+just the \fBTCL_TOKEN_OPERATOR\fR token.
+Each operand is described by a \fBTCL_TOKEN_SUB_EXPR\fR token.
+Otherwise, the subexpression is a value described by
+one of the token types \fBTCL_TOKEN_WORD\fR, \fBTCL_TOKEN_TEXT\fR,
+\fBTCL_TOKEN_BS\fR, \fBTCL_TOKEN_COMMAND\fR, 
+\fBTCL_TOKEN_VARIABLE\fR, and \fBTCL_TOKEN_SUB_EXPR\fR.
+The \fInumComponents\fR field
+counts the total number of sub-tokens that make up the subexpression;
+this includes the sub-tokens for any nested \fBTCL_TOKEN_SUB_EXPR\fR tokens.
+.TP
+\fBTCL_TOKEN_OPERATOR\fR
+The token describes one operator of an expression
+such as \fB&&\fR or \fBhypot\fR.
+An \fBTCL_TOKEN_OPERATOR\fR token is always preceeded by a
+\fBTCL_TOKEN_SUB_EXPR\fR token
+that describes the operator and its operands;
+the \fBTCL_TOKEN_SUB_EXPR\fR token's \fInumComponents\fR field
+can be used to determine the number of operands.
+A binary operator such as \fB*\fR
+is followed by two \fBTCL_TOKEN_SUB_EXPR\fR tokens
+that describe its operands.
+A unary operator like \fB-\fR
+is followed by a single \fBTCL_TOKEN_SUB_EXPR\fR token
+for its operand.
+If the operator is a math function such as \fBlog10\fR,
+the \fBTCL_TOKEN_OPERATOR\fR token will give its name and
+the following \fBTCL_TOKEN_SUB_EXPR\fR tokens will describe
+its operands;
+if there are no operands (as with \fBrand\fR),
+no \fBTCL_TOKEN_SUB_EXPR\fR tokens follow.
+There is one trinary operator, \fB?\fR,
+that appears in if-then-else subexpressions
+such as \fIx\fB?\fIy\fB:\fIz\fR;
+in this case, the \fB?\fR \fBTCL_TOKEN_OPERATOR\fR token
+is followed by three \fBTCL_TOKEN_SUB_EXPR\fR tokens for the operands
+\fIx\fR, \fIy\fR, and \fIz\fR.
+The \fInumComponents\fR field for a \fBTCL_TOKEN_OPERATOR\fR token
+is always 0.
+.PP
+After \fBTcl_ParseCommand\fR returns, the first token pointed to by
+the \fItokenPtr\fR field of the
+Tcl_Parse structure always has type \fBTCL_TOKEN_WORD\fR or
+\fBTCL_TOKEN_SIMPLE_WORD\fR.  It is followed by the sub-tokens
+that must be concatenated to produce the value of that word.
+The next token is the \fBTCL_TOKEN_WORD\fR or \fBTCL_TOKEN_SIMPLE_WORD\fR
+token for the second word, followed by sub-tokens for that
+word, and so on until all \fInumWords\fR have been accounted
+for.
+.PP
+After \fBTcl_ParseExpr\fR returns, the first token pointed to by
+the \fItokenPtr\fR field of the
+Tcl_Parse structure always has type \fBTCL_TOKEN_SUB_EXPR\fR.
+It is followed by the sub-tokens that must be evaluated
+to produce the value of the expression.
+Only the token information in the Tcl_Parse structure
+is modified: the \fIcommentStart\fR, \fIcommentSize\fR,
+\fIcommandStart\fR, and \fIcommandSize\fR fields are not modified
+by \fBTcl_ParseExpr\fR.
+.PP
+After \fBTcl_ParseBraces\fR returns,
+the array of tokens pointed to by the \fItokenPtr\fR field of the
+Tcl_Parse structure will contain a single \fBTCL_TOKEN_TEXT\fR token
+if the braced string does not contain any backslash-newlines.
+If the string does contain backslash-newlines,
+the array of tokens will contain one or more
+\fBTCL_TOKEN_TEXT\fR or \fBTCL_TOKEN_BS\fR sub-tokens
+that must be concatenated to produce the value of the string.
+If the braced string was just \fB{}\fR
+(that is, the string was empty),
+the single \fBTCL_TOKEN_TEXT\fR token will have a \fIsize\fR field
+containing zero;
+this ensures that at least one token appears
+to describe the braced string.
+Only the token information in the Tcl_Parse structure
+is modified: the \fIcommentStart\fR, \fIcommentSize\fR,
+\fIcommandStart\fR, and \fIcommandSize\fR fields are not modified
+by \fBTcl_ParseBraces\fR.
+.PP
+After \fBTcl_ParseQuotedString\fR returns,
+the array of tokens pointed to by the \fItokenPtr\fR field of the
+Tcl_Parse structure depends on the contents of the quoted string.
+It will consist of one or more \fBTCL_TOKEN_TEXT\fR, \fBTCL_TOKEN_BS\fR,
+\fBTCL_TOKEN_COMMAND\fR, and \fBTCL_TOKEN_VARIABLE\fR sub-tokens.
+The array always contains at least one token;
+for example, if the argument \fIstring\fR is empty,
+the array returned consists of a single \fBTCL_TOKEN_TEXT\fR token
+with a zero \fIsize\fR field.
+Only the token information in the Tcl_Parse structure
+is modified: the \fIcommentStart\fR, \fIcommentSize\fR,
+\fIcommandStart\fR, and \fIcommandSize\fR fields are not modified.
+.PP
+After \fBTcl_ParseVarName\fR returns, the first token pointed to by
+the \fItokenPtr\fR field of the
+Tcl_Parse structure always has type \fBTCL_TOKEN_VARIABLE\fR.  It
+is followed by the sub-tokens that make up the variable name as
+described above.  The total length of the variable name is
+contained in the \fIsize\fR field of the first token.
+As in \fBTcl_ParseExpr\fR,
+only the token information in the Tcl_Parse structure
+is modified by \fBTcl_ParseVarName\fR:
+the \fIcommentStart\fR, \fIcommentSize\fR,
+\fIcommandStart\fR, and \fIcommandSize\fR fields are not modified.
+.PP
+All of the character pointers in the
+Tcl_Parse and Tcl_Token structures refer
+to characters in the \fIstring\fR argument passed to
+\fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR,
+\fBTcl_ParseQuotedString\fR, and \fBTcl_ParseVarName\fR.
+.PP
+There are additional fields in the Tcl_Parse structure after the
+\fInumTokens\fR field, but these are for the private use of
+\fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR,
+\fBTcl_ParseQuotedString\fR, and \fBTcl_ParseVarName\fR; they should not be
+referenced by code outside of these procedures.
+
+.SH KEYWORDS
+backslash substitution, braces, command, expression, parse, token, variable substitution
@@ -4,13 +4,13 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) PkgRequire.3 1.4 96/02/15 20:03:16
+'\" RCS: @(#) $Id: PkgRequire.3,v 1.3 1999/03/10 05:52:45 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_PkgRequire 3 7.5 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_PkgRequire, Tcl_PkgProvide \- package version control
+Tcl_PkgRequire, Tcl_PkgRequireEx, Tcl_PkgPresent, Tcl_PkgPresentEx, Tcl_PkgProvide, Tcl_PkgProvideEx \- package version control
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -18,10 +18,22 @@ Tcl_PkgRequire, Tcl_PkgProvide \- package version control
 char *
 \fBTcl_PkgRequire\fR(\fIinterp, name, version, exact\fR)
 .sp
+char *
+\fBTcl_PkgRequireEx\fR(\fIinterp, name, version, exact, clientDataPtr\fR)
+.sp
+char *
+\fBTcl_PkgPresent\fR(\fIinterp, name, version, exact\fR)
+.sp
+char *
+\fBTcl_PkgPresentEx\fR(\fIinterp, name, version, exact, clientDataPtr\fR)
+.sp
 int
 \fBTcl_PkgProvide\fR(\fIinterp, name, version\fR)
+.sp
+int
+\fBTcl_PkgProvideEx\fR(\fIinterp, name, version, clientData\fR)
 .SH ARGUMENTS
-.AS Tcl_FreeProc clientData
+.AS Tcl_FreeProc clientDataPtr
 .AP Tcl_Interp *interp in
 Interpreter where package is needed or available.
 .AP char *name in
@@ -35,25 +47,41 @@ Non-zero means that only the particular version specified by
 Zero means that newer versions than \fIversion\fR are also
 acceptable as long as they have the same major version number
 as \fIversion\fR.
+.AP ClientData clientData in
+Arbitrary value to be associated with the package.
+.AP ClientData *clientDataPtr out
+Pointer to place to store the value associated with the matching
+package. It is only changed if the pointer is not NULL and the
+function completed successfully.
 .BE

 .SH DESCRIPTION
 .PP
 These procedures provide C-level interfaces to Tcl's package and
 version management facilities.
+.PP
 \fBTcl_PkgRequire\fR is equivalent to the \fBpackage require\fR
+command, \fBTcl_PkgPresent\fR is equivalent to the \fBpackage present\fR
 command, and \fBTcl_PkgProvide\fR is equivalent to the
 \fBpackage provide\fR command.
+.PP
 See the documentation for the Tcl commands for details on what these
 procedures do.
-If \fBTcl_PkgRequire\fR completes successfully it returns a pointer
-to the version string for the version of the package that is provided
-in the interpreter (which may be different than \fIversion\fR); if
-an error occurs it returns NULL and leaves an error message in
-\fIinterp->result\fR.
+.PP
+If \fBTcl_PkgPresent\fR or \fBTcl_PkgRequire\fR complete successfully
+they return a pointer to the version string for the version of the package
+that is provided in the interpreter (which may be different than 
+\fIversion\fR); if an error occurs they return NULL and leave an error 
+message in \fIinterp->result\fR.
+.PP
 \fBTcl_PkgProvide\fR returns TCL_OK if it completes successfully;
 if an error occurs it returns TCL_ERROR and leaves an error message
 in \fIinterp->result\fR.
+.PP
+\fBTcl_PkgProvideEx\fR, \fBTcl_PkgPresentEx\fR and \fBTcl_PkgRequireEx\fR
+allow the setting and retrieving of the client data associated with
+the package. In all other respects they are equivalent to the matching
+functions.

 .SH KEYWORDS
-package, provide, require, version
+package, present, provide, require, version
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) Preserve.3 1.13 96/05/28 09:26:12
+'\" RCS: @(#) $Id: Preserve.3,v 1.2 1998/09/14 18:39:49 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_Preserve 3 7.5 Tcl "Tcl Library Procedures"
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) PrintDbl.3 1.9 97/08/22 13:30:22
+'\" RCS: @(#) $Id: PrintDbl.3,v 1.2 1998/09/14 18:39:49 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_PrintDouble 3 8.0 Tcl "Tcl Library Procedures"
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: SCCS: @(#) RecEvalObj.3 1.1 97/07/29 18:31:21
+'\" RCS: @(#) $Id: RecEvalObj.3,v 1.2 1998/09/14 18:39:49 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_RecordAndEvalObj 3 8.0 Tcl "Tcl Library Procedures"
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) RecordEval.3 1.18 97/07/29 18:25:13
+'\" RCS: @(#) $Id: RecordEval.3,v 1.2 1998/09/14 18:39:50 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_RecordAndEval 3 7.4 Tcl "Tcl Library Procedures"
@@ -1,22 +1,26 @@
 '\"
 '\" Copyright (c) 1994 The Regents of the University of California.
 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1998-1999 Scriptics Corportation
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) RegExp.3 1.9 96/08/26 12:59:48
+'\" RCS: @(#) $Id: RegExp.3,v 1.6 1999/12/21 23:57:33 hobbs Exp $
 '\" 
 .so man.macros
-.TH Tcl_RegExpMatch 3 7.4 Tcl "Tcl Library Procedures"
+.TH Tcl_RegExpMatch 3 8.1 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_RegExpMatch, Tcl_RegExpCompile, Tcl_RegExpExec, Tcl_RegExpRange \- Pattern matching with regular expressions
+Tcl_RegExpMatch, Tcl_RegExpCompile, Tcl_RegExpExec, Tcl_RegExpRange, Tcl_GetRegExpFromObj, Tcl_RegExpMatchObj, Tcl_GetRegExpInfo \- Pattern matching with regular expressions
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
 .sp
 int
+\fBTcl_RegExpMatchObj\fR(\fIinterp\fR, \fIstrObj\fR, \fIpatObj\fR)
+.sp
+int
 \fBTcl_RegExpMatch\fR(\fIinterp\fR, \fIstring\fR, \fIpattern\fR)
 .sp
 Tcl_RegExp
@@ -26,17 +30,38 @@ int
 \fBTcl_RegExpExec\fR(\fIinterp\fR, \fIregexp\fR, \fIstring\fR, \fIstart\fR)
 .sp
 \fBTcl_RegExpRange\fR(\fIregexp\fR, \fIindex\fR, \fIstartPtr\fR, \fIendPtr\fR)
+.VS 8.1
+.sp
+Tcl_RegExp
+\fBTcl_GetRegExpFromObj\fR(\fIinterp\fR, \fIpatObj\fR, \fIcflags\fR)
+.sp
+int
+\fBTcl_RegExpExecObj\fR(\fIinterp\fR, \fIregexp\fR, \fIobjPtr\fR, \fIoffset\fR, \fInmatches\fR, \fIeflags\fR)
+.sp
+\fBTcl_GetRegExpInfo\fR(\fIregexp\fR, \fIinfoPtr\fR)
+.VE 8.1
+
 .SH ARGUMENTS
 .AS Tcl_Interp *interp
 .AP Tcl_Interp *interp in
-Tcl interpreter to use for error reporting.
+Tcl interpreter to use for error reporting.  The interpreter may be
+NULL if no error reporting is desired.
+.VS 8.1
+.AP Tcl_Obj *strObj in/out
+Refers to the object from which to get the string to search.  The
+internal representation of the object may be converted to a form that
+can be efficiently searched.
+.AP Tcl_Obj *patObj in/out
+Refers to the object from which to get a regular expression. The
+compiled regular expression is cached in the object.
+.VE 8.1
 .AP char *string in
 String to check for a match with a regular expression.
 .AP char *pattern in
 String in the form of a regular expression pattern.
 .AP Tcl_RegExp regexp in
 Compiled regular expression.  Must have been returned previously
-by \fBTcl_RegExpCompile\fR.
+by \fBTcl_GetRegExpFromObj\fR or \fBTcl_RegExpCompile\fR.
 .AP char *start in
 If \fIstring\fR is just a portion of some other string, this argument
 identifies the beginning of the larger string.
@@ -52,19 +77,50 @@ NULL if there is no such range.
 .AP char **endPtr out
 The address of the character just after the last one in the range
 is stored here, or NULL if there is no such range.
+.VS 8.1
+.AP int cflags in
+OR-ed combination of compilation flags. See below for more information.
+.AP Tcl_Obj *objPtr in/out
+An object which contains the string to check for a match with a
+regular expression.
+.AP int offset in
+The character offset into the string where matching should begin.
+The value of the offset has no impact on \fB^\fR matches.  This
+behavior is controlled by \fIeflags\fR.
+.AP int nmatches in
+The number of matching subexpressions that should be remembered for
+later use.  If this value is 0, then no subexpression match
+information will be computed.  If the value is -1, then
+all of the matching subexpressions will be remembered.  Any other
+value will be taken as the maximum number of subexpressions to
+remember.
+.AP int eflags in
+OR-ed combination of the values TCL_REG_NOTBOL and TCL_REG_NOTEOL.
+See below for more information.
+.AP Tcl_RegExpInfo *infoPtr out
+The address of the location where information about a previous match
+should be stored by \fBTcl_GetRegExpInfo\fR.
+.VE 8.1
 .BE

 .SH DESCRIPTION
 .PP
 \fBTcl_RegExpMatch\fR determines whether its \fIpattern\fR argument
 matches \fIregexp\fR, where \fIregexp\fR is interpreted
-as a regular expression using the same rules as for the
-\fBregexp\fR Tcl command.
+as a regular expression using the rules in the \fBre_syntax\fR
+reference page. 
 If there is a match then \fBTcl_RegExpMatch\fR returns 1.
 If there is no match then \fBTcl_RegExpMatch\fR returns 0.
 If an error occurs in the matching process (e.g. \fIpattern\fR
 is not a valid regular expression) then \fBTcl_RegExpMatch\fR
-returns \-1 and leaves an error message in \fIinterp->result\fR.
+returns \-1 and leaves an error message in the interpreter result.
+.VS 8.1.2
+\fBTcl_RegExpMatchObj\fR is similar to \fBTcl_RegExpMatch\fR except it
+operates on the Tcl objects \fIstrObj\fR and \fIpatObj\fR instead of
+UTF strings. 
+\fBTcl_RegExpMatchObj\fR is generally more efficient than
+\fBTcl_RegExpMatch\fR, so it is the preferred interface.
+.VE 8.1.2
 .PP
 \fBTcl_RegExpCompile\fR, \fBTcl_RegExpExec\fR, and \fBTcl_RegExpRange\fR
 provide lower-level access to the regular expression pattern matcher.
@@ -74,7 +130,7 @@ The return value is a token for this compiled form, which can be
 used in subsequent calls to \fBTcl_RegExpExec\fR or \fBTcl_RegExpRange\fR.
 If an error occurs while compiling the regular expression then
 \fBTcl_RegExpCompile\fR returns NULL and leaves an error message
-in \fIinterp->result\fR.
+in the interpreter result.
 Note:  the return value from \fBTcl_RegExpCompile\fR is only valid
 up to the next call to \fBTcl_RegExpCompile\fR;  it is not safe to
 retain these values for long periods of time.
@@ -84,7 +140,7 @@ It returns 1 if \fIstring\fR contains a range of characters that
 match \fIregexp\fR, 0 if no match is found, and
 \-1 if an error occurs.
 In the case of an error, \fBTcl_RegExpExec\fR leaves an error
-message in \fIinterp->result\fR.
+message in the interpreter result.
 When searching a string for multiple matches of a pattern,
 it is important to distinguish between the start of the original
 string and the start of the current search.
@@ -111,6 +167,180 @@ information is returned about the range of characters that matched the
 \fIindex\fR'th parenthesized subexpression within the pattern.
 If there is no range corresponding to \fIindex\fR then NULL
 is stored in \fI*firstPtr\fR and \fI*lastPtr\fR.
-
+.PP
+.VS 8.1
+\fBTcl_GetRegExpFromObj\fR, \fBTcl_RegExpExecObj\fR, and
+\fBTcl_GetRegExpInfo\fR are object interfaces that provide the most
+direct control of Henry Spencer's regular expression library.  For
+users that need to modify compilation and execution options directly,
+it is recommended that you use these interfaces instead of calling the
+internal regexp functions.  These interfaces handle the details of UTF
+to Unicode translations as well as providing improved performance
+through caching in the pattern and string objects.
+.PP
+\fBTcl_GetRegExpFromObj\fR attepts to return a compiled regular
+expression from the \fIpatObj\fR.  If the object does not already
+contain a compiled regular expression it will attempt to create one
+from the string in the object and assign it to the internal
+representation of the \fIpatObj\fR.  The return value of this function
+is of type \fBTcl_RegExp\fR.  The return value is a token for this
+compiled form, which can be used in subsequent calls to
+\fBTcl_RegExpExecObj\fR or \fBTcl_GetRegExpInfo\fR.  If an error
+occurs while compiling the regular expression then
+\fBTcl_GetRegExpFromObj\fR returns NULL and leaves an error message in
+the interpreter result.  The regular expression token can be used as
+long as the internal representation of \fIpatObj\fR refers to the
+compiled form.  The \fIeflags\fR argument is a bitwise OR of
+zero or more of the following flags that control the compilation of
+\fIpatObj\fR:
+.RS 2
+.TP
+\fBTCL_REG_ADVANCED\fR
+Compile advanced regular expressions (`AREs').  This mode corresponds to
+the normal regular expression syntax accepted by the Tcl regexp and
+regsub commands.
+.TP
+\fBTCL_REG_EXTENDED\fR
+Compile extended regular expressions (`EREs').  This mode corresponds
+to the regular expression syntax recognized by Tcl 8.0 and earlier
+versions. 
+.TP
+\fBTCL_REG_BASIC\fR
+Compile basic regular expressions (`BREs').  This mode corresponds
+to the regular expression syntax recognized by common Unix utilities
+like \fBsed\fR and \fBgrep\fR.  This is the default if no flags are
+specified.
+.TP
+\fBTCL_REG_EXPANDED\fR
+Compile the regular expression (basic, extended, or advanced) using an
+expanded syntax that allows comments and whitespace.  This mode causes
+non-backslashed non-bracket-expression white
+space and #-to-end-of-line comments to be ignored.
+.TP
+\fBTCL_REG_QUOTE\fR
+Compile a literal string, with all characters treated as ordinary characters.
+.TP
+\fBTCL_REG_NOCASE\fR
+Compile for matching that ignores upper/lower case distinctions.
+.TP
+\fBTCL_REG_NEWLINE\fR
+Compile for newline-sensitive matching.  By default, newline is a
+completely ordinary character with no special meaning in either
+regular expressions or strings.  With this flag, `[^' bracket
+expressions and `.' never match newline, `^' matches an empty string
+after any newline in addition to its normal function, and `$' matches
+an empty string before any newline in addition to its normal function.
+\fBREG_NEWLINE\fR is the bitwise OR of \fBREG_NLSTOP\fR and
+\fBREG_NLANCH\fR.
+.TP
+\fBTCL_REG_NLSTOP\fR
+Compile for partial newline-sensitive matching,
+with the behavior of
+`[^' bracket expressions and `.' affected,
+but not the behavior of `^' and `$'.  In this mode, `[^' bracket
+expressions and `.' never match newline.
+.TP
+\fBTCL_REG_NLANCH\fR
+Compile for inverse partial newline-sensitive matching,
+with the behavior of
+of `^' and `$' (the ``anchors'') affected, but not the behavior of
+`[^' bracket expressions and `.'.  In this mode `^' matches an empty string
+after any newline in addition to its normal function, and `$' matches
+an empty string before any newline in addition to its normal function.
+.TP
+\fBTCL_REG_NOSUB\fR
+Compile for matching that reports only success or failure,
+not what was matched.  This reduces compile overhead and may improve
+performance.  Subsequent calls to \fBTcl_GetRegExpInfo\fR or
+\fBTcl_RegExpRange\fR will not report any match information.
+.TP
+\fBTCL_REG_CANMATCH\fR
+Compile for matching that reports the potential to complete a partial
+match given more text (see below).
+.RE
+.PP
+Only one of
+\fBTCL_REG_EXTENDED\fR,
+\fBTCL_REG_ADVANCED\fR,
+\fBTCL_REG_BASIC\fR, and
+\fBTCL_REG_QUOTE\fR may be specified.
+.PP
+\fBTcl_RegExpExecObj\fR executes the regular expression pattern
+matcher.  It returns 1 if \fIobjPtr\fR contains a range of characters
+that match \fIregexp\fR, 0 if no match is found, and \-1 if an error
+occurs.  In the case of an error, \fBTcl_RegExpExecObj\fR leaves an
+error message in the interpreter result.  The \fInmatches\fR value
+indicates to the matcher how many subexpressions are of interest.  If
+\fInmatches\fR is 0, then no subexpression match information is
+recorded, which may allow the matcher to make various optimizations.
+If the value is -1, then all of the subexpressions in the pattern are
+remembered.  If the value is a positive integer, then only that number
+of subexpressions will be remembered.  Matching begins at the
+specified Unicode character index given by \fIoffset\fR.  Unlike
+\fBTcl_RegExpExec\fR, the behavior of anchors is not affected by the
+offset value.  Instead the behavior of the anchors is explicitly
+controlled by the \fIeflags\fR argument, which is a bitwise OR of
+zero or more of the following flags:
+.RS 2
+.TP
+\fBTCL_REG_NOTBOL\fR
+The starting character will not be treated as the beginning of a
+line or the beginning of the string, so `^' will not match there.
+Note that this flag has no effect on how `\fB\eA\fR' matches.
+.TP
+\fBTCL_REG_NOTEOL\fR
+The last character in the string will not be treated as the end of a
+line or the end of the string, so '$' will not match there.
+Note that this flag has no effect on how `\fB\eZ\fR' matches.
+.RE
+.PP
+\fBTcl_GetRegExpInfo\fR retrieves information about the last match
+performed with a given regular expression \fIregexp\fR.  The
+\fIinfoPtr\fR argument contains a pointer to a structure that is
+defined as follows:
+.PP
+.CS
+typedef struct Tcl_RegExpInfo {
+	int \fInsubs\fR;
+	Tcl_RegExpIndices *\fImatches\fR;
+	long \fIextendStart\fR;
+} Tcl_RegExpInfo;
+.CE
+.PP
+The \fInsubs\fR field contains a count of the number of parenthesized
+subexpressions within the regular expression.  If the \fBTCL_REG_NOSUB\fR
+was used, then this value will be zero.  The \fImatches\fR field
+points to an array of \fInsubs\fR values that indicate the bounds of each
+subexpression matched.  The first element in the array refers to the
+range matched by the entire regular expression, and subsequent elements
+refer to the parenthesized subexpressions in the order that they
+appear in the pattern.  Each element is a structure that is defined as
+follows:
+.PP
+.CS
+typedef struct Tcl_RegExpIndices {
+	long \fIstart\fR;
+	long \fIend\fR;
+} Tcl_RegExpIndices;
+.CE
+.PP
+The \fIstart\fR and \fIend\fR values are Unicode character indices
+relative to the offset location within \fIobjPtr\fR where matching began.
+The \fIstart\fR index identifies the first character of the matched
+subexpression.  The \fIend\fR index identifies the first character
+after the matched subexpression.  If the subexpression matched the
+empty string, then \fIstart\fR and \fIend\fR will be equal.  If the
+subexpression did not participate in the match, then \fIstart\fR and
+\fIend\fR will be set to -1.
+.PP
+The \fIextendStart\fR field in \fBTcl_RegExpInfo\fR is only set if the
+\fBTCL_REG_CANMATCH\fR flag was used.  It indicates the first
+character in the string where a match could occur.  If a match was
+found, this will be the same as the beginning of the current match.
+If no match was found, then it indicates the earliest point at which a
+match might occur if additional text is appended to the string.
+.VE 8.1
+.SH "SEE ALSO"
+re_syntax(n)
 .SH KEYWORDS
-match, pattern, regular expression, string, subexpression
+match, pattern, regular expression, string, subexpression, Tcl_RegExpIndices, Tcl_RegExpInfo
@@ -0,0 +1,65 @@
+'\"
+'\" Copyright (c) 1997 by Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+'\" RCS: @(#) $Id: SaveResult.3,v 1.2 1999/04/16 00:46:33 stanton Exp $
+'\" 
+.so man.macros
+.TH Tcl_SaveResult 3 8.1 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_SaveResult, Tcl_RestoreResult, Tcl_DiscardResult \- save and restore an interpreter's result
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+\fBTcl_SaveResult(\fIinterp, statePtr\fB)\fR
+.sp
+\fBTcl_RestoreResult(\fIinterp, statePtr\fB)\fR
+.sp
+\fBTcl_DiscardResult(\fIstatePtr\fB)\fR
+.SH ARGUMENTS
+.AS Tcl_SavedResult statePtr
+.AP Tcl_Interp *interp in
+Interpreter for which state should be saved.
+.AP Tcl_SavedResult *statePtr in
+Pointer to location where interpreter result should be saved or restored.
+.BE
+
+.SH DESCRIPTION
+.PP
+These routines allows a C procedure to take a snapshot of the current
+interpreter result so that it can be restored after a call
+to \fBTcl_Eval\fR or some other routine that modifies the interpreter
+result.  These routines are passed a pointer to a structure that is
+used to store enough information to restore the interpreter result
+state.  This structure can be allocated on the stack of the calling
+procedure.  These routines do not save the state of any error
+information in the interpreter (e.g. the \fBerrorCode\fR or
+\fBerrorInfo\fR variables).
+.PP
+\fBTcl_SaveResult\fR moves the string and object results
+of \fIinterp\fR into the location specified by \fIstatePtr\fR.
+\fBTcl_SaveResult\fR clears the result for \fIinterp\fR and
+leaves the result in its normal empty initialized state.
+.PP
+\fBTcl_RestoreResult\fR moves the string and object results from
+\fIstatePtr\fR back into \fIinterp\fR.  Any result or error that was
+already in the interpreter will be cleared.  The \fIstatePtr\fR is left
+in an uninitialized state and cannot be used until another call to
+\fBTcl_SaveResult\fR.
+.PP
+\fBTcl_DiscardResult\fR releases the saved interpreter state
+stored at \fBstatePtr\fR.  The state structure is left in an
+uninitialized state and cannot be used until another call to
+\fBTcl_SaveResult\fR.
+.PP
+Once \fBTcl_SaveResult\fR is called to save the interpreter
+result, either \fBTcl_RestoreResult\fR or
+\fBTcl_DiscardResult\fR must be called to properly clean up the
+memory associated with the saved state.  
+
+.SH KEYWORDS
+result, state, interp
@@ -4,12 +4,12 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) SetErrno.3 1.5 96/02/15 20:01:31
+'\" RCS: @(#) $Id: SetErrno.3,v 1.3 2000/01/26 21:36:35 ericm Exp $
 .so man.macros
-.TH Tcl_SetErrno 3 7.5 Tcl "Tcl Library Procedures"
+.TH Tcl_SetErrno 3 8.3 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_SetErrno, Tcl_GetErrno \- manipulate errno to store and retrieve error codes
+Tcl_SetErrno, Tcl_GetErrno, Tcl_ErrnoId, Tcl_ErrnoMsg \- manipulate errno to store and retrieve error codes
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -20,6 +20,12 @@ void
 int
 \fBTcl_GetErrno\fR()
 .sp
+char *
+\fBTcl_ErrnoId\fR()
+.sp
+char *
+\fBTcl_ErrnoMsg\fR()
+.sp
 .SH ARGUMENTS
 .AS Tcl_Interp *errorCode in
 .AP int errorCode in
@@ -43,6 +49,13 @@ via \fBerrno\fR should call \fBTcl_SetErrno\fR rather than setting
 \fBTcl_GetErrno\fR returns the current value of \fBerrno\fR.
 Procedures wishing to access \fBerrno\fR should call this procedure
 instead of accessing \fBerrno\fR directly.
+.PP
+\fBTcl_ErrnoId\fR and \fBTcl_ErrnoMsg\fR return a string
+representation of the current \fBerrno\fR value.  \fBTcl_ErrnoId\fR
+returns a machine-readable textual identifier such as
+"EACCES". \fBTcl_ErrnoMsg\fR returns a human-readable string such as
+"permission denied".  The strings returned by these functions are
+statically allocated and the caller must not free or modify them.

 .SH KEYWORDS
 errno, error code, global variables
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) SetRecLmt.3 1.6 96/03/25 20:06:36
+'\" RCS: @(#) $Id: SetRecLmt.3,v 1.3 1999/04/16 00:46:33 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_SetRecursionLimit 3 7.0 Tcl "Tcl Library Procedures"
@@ -41,7 +41,7 @@ allowable nesting depth for an interpreter.
 The \fIdepth\fR argument specifies a new limit for \fIinterp\fR,
 and \fBTcl_SetRecursionLimit\fR returns the old limit.
 To read out the old limit without modifying it, invoke
-\fBTcl_SetRecursionDepth\fR with \fIdepth\fR equal to 0.
+\fBTcl_SetRecursionLimit\fR with \fIdepth\fR equal to 0.
 .PP
 The \fBTcl_SetRecursionLimit\fR only sets the size of the Tcl
 call stack:  it cannot by itself prevent stack overflows on the
@@ -5,13 +5,13 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) SetResult.3 1.23 97/06/26 14:05:57
+'\" RCS: @(#) $Id: SetResult.3,v 1.4 1999/08/21 19:40:47 hobbs Exp $
 '\" 
 .so man.macros
 .TH Tcl_SetResult 3 7.5 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult, Tcl_AppendResult, Tcl_AppendElement, Tcl_ResetResult \- manipulate Tcl result
+Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult, Tcl_AppendResult, Tcl_AppendResultVA, Tcl_AppendElement, Tcl_ResetResult \- manipulate Tcl result
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -28,6 +28,8 @@ char *
 .sp
 \fBTcl_AppendResult\fR(\fIinterp, string, string, ... , \fB(char *) NULL\fR)
 .sp
+\fBTcl_AppendResultVA\fR(\fIinterp, argList\fR)
+.sp
 \fBTcl_AppendElement\fR(\fIinterp, string\fR)
 .sp
 \fBTcl_ResetResult\fR(\fIinterp\fR)
@@ -46,6 +48,9 @@ appended to the existing result.
 Address of procedure to call to release storage at
 \fIstring\fR, or \fBTCL_STATIC\fR, \fBTCL_DYNAMIC\fR, or
 \fBTCL_VOLATILE\fR.
+.AP va_list argList in
+An argument list which must have been initialised using
+\fBTCL_VARARGS_START\fR, and cleared using \fBva_end\fR.
 .BE

 .SH DESCRIPTION
@@ -112,7 +117,7 @@ and the result is left as a empty string.
 \fBTcl_AddErrorInfo\fR, \fBTcl_AddObjErrorInfo\fR,
 and \fBTcl_SetErrorCode\fR.

-.SH OLD STRING PROCEDURES
+.SH "OLD STRING PROCEDURES"
 .PP
 Use of the following procedures is deprecated
 since they manipulate the Tcl result as a string.
@@ -137,6 +142,9 @@ to a string, if necessary, before appending the argument strings.
 Any number of \fIstring\fR arguments may be passed in a single
 call; the last argument in the list must be a NULL pointer.
 .PP
+\fBTcl_AppendResultVA\fR is the same as \fBTcl_AppendResult\fR except that
+instead of taking a variable number of arguments it takes an argument list.
+.PP
 \fBTcl_AppendElement\fR is similar to \fBTcl_AppendResult\fR in
 that it allows results to be built up in pieces.
 However, \fBTcl_AppendElement\fR takes only a single \fIstring\fR
@@ -162,7 +170,7 @@ change \fIinterp->result\fR or clear error state.
 \fBTcl_FreeResult\fR is most commonly used when a procedure
 is about to replace one result value with another.

-.SH DIRECT ACCESS TO INTERP->RESULT IS DEPRECATED
+.SH "DIRECT ACCESS TO INTERP->RESULT IS DEPRECATED"
 .PP
 It used to be legal for programs to
 directly read and write \fIinterp->result\fR
@@ -173,7 +181,7 @@ Programs should always read the result
 using the procedures \fBTcl_GetObjResult\fR or \fBTcl_GetStringResult\fR,
 and write the result using \fBTcl_SetObjResult\fR or \fBTcl_SetResult\fR.

-.SH THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT
+.SH "THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT"
 .PP
 \fBTcl_SetResult\fR's \fIfreeProc\fR argument specifies how 
 the Tcl system is to manage the storage for the \fIstring\fR argument.
@@ -5,93 +5,158 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) SetVar.3 1.30 97/10/10 16:10:36
+'\" RCS: @(#) $Id: SetVar.3,v 1.3 1999/04/16 00:46:33 stanton Exp $
 '\" 
 .so man.macros
-.TH Tcl_SetVar 3 7.4 Tcl "Tcl Library Procedures"
+.TH Tcl_SetVar 3 8.1 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_SetVar, Tcl_SetVar2, Tcl_GetVar, Tcl_GetVar2, Tcl_UnsetVar, Tcl_UnsetVar2 \- manipulate Tcl variables
+Tcl_SetVar2Ex, Tcl_SetVar, Tcl_SetVar2, Tcl_ObjSetVar2, Tcl_GetVar2Ex, Tcl_GetVar, Tcl_GetVar2, Tcl_ObjGetVar2, Tcl_UnsetVar, Tcl_UnsetVar2 \- manipulate Tcl variables
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
 .sp
+.VS 8.1
+Tcl_Obj *
+\fBTcl_SetVar2Ex\fR(\fIinterp, name1, name2, newValuePtr, flags\fR)
+.VE
+.sp
 char *
 \fBTcl_SetVar\fR(\fIinterp, varName, newValue, flags\fR)
 .sp
 char *
 \fBTcl_SetVar2\fR(\fIinterp, name1, name2, newValue, flags\fR)
 .sp
+Tcl_Obj *
+\fBTcl_ObjSetVar2\fR(\fIinterp, part1Ptr, part2Ptr, newValuePtr, flags\fR)
+.sp
+.VS 8.1
+Tcl_Obj *
+\fBTcl_GetVar2Ex\fR(\fIinterp, name1, name2, flags\fR)
+.VE
+.sp
 char *
 \fBTcl_GetVar\fR(\fIinterp, varName, flags\fR)
 .sp
 char *
 \fBTcl_GetVar2\fR(\fIinterp, name1, name2, flags\fR)
 .sp
+Tcl_Obj *
+\fBTcl_ObjGetVar2\fR(\fIinterp, part1Ptr, part2Ptr, flags\fR)
+.sp
 int
 \fBTcl_UnsetVar\fR(\fIinterp, varName, flags\fR)
 .sp
 int
 \fBTcl_UnsetVar2\fR(\fIinterp, name1, name2, flags\fR)
 .SH ARGUMENTS
-.AS Tcl_Interp *newValue
+.AS Tcl_Interp *newValuePtr
 .AP Tcl_Interp *interp in
 Interpreter containing variable.
+.AP char *name1 in
+Contains the name of an array variable (if \fIname2\fR is non-NULL)
+or (if \fIname2\fR is NULL) either the name of a scalar variable
+or a complete name including both variable name and index.
+May include \fB::\fR namespace qualifiers
+to specify a variable in a particular namespace.
+.AP char *name2 in
+If non-NULL, gives name of element within array; in this
+case \fIname1\fR must refer to an array variable.
+.AP Tcl_Obj *newValuePtr in
+.VS 8.1
+Points to a Tcl object containing the new value for the variable.
+.VE
+.AP int flags in
+OR-ed combination of bits providing additional information. See below
+for valid values.
 .AP char *varName in
 Name of variable.
-May include a series of \fB::\fR namespace qualifiers
+May include \fB::\fR namespace qualifiers
 to specify a variable in a particular namespace.
 May refer to a scalar variable or an element of
-an array variable.
-If the name references an element of an array, then it
+an array.
+If the name references an element of an array, then the name
 must be in writable memory:  Tcl will make temporary modifications 
 to it while looking up the name.
 .AP char *newValue in
-New value for variable.
-.AP int flags in
-OR-ed combination of bits providing additional information for
-operation. See below for valid values.
-.AP char *name1 in
-Name of scalar variable, or name of array variable if \fIname2\fR
-is non-NULL.
-May include a series of \fB::\fR namespace qualifiers
+New value for variable, specified as a NULL-terminated string.
+A copy of this value is stored in the variable.
+.AP Tcl_Obj *part1Ptr in
+Points to a Tcl object containing the variable's name.
+The name may include a series of \fB::\fR namespace qualifiers
 to specify a variable in a particular namespace.
-.AP char *name2 in
-If non-NULL, gives name of element within array and \fIname1\fR
-must refer to an array variable.
+May refer to a scalar variable or an element of an array variable.
+.AP Tcl_Obj *part2Ptr in
+If non-NULL, points to an object containing the name of an element
+within an array and \fIpart1Ptr\fR must refer to an array variable.
 .BE

 .SH DESCRIPTION
 .PP
-These procedures may be used to create, modify, read, and delete
+These procedures are used to create, modify, read, and delete
 Tcl variables from C code.
 .PP
-Note that \fBTcl_GetVar\fR and \fBTcl_SetVar\fR
-have been largely replaced by the
-object-based procedures \fBTcl_ObjGetVar2\fR and \fBTcl_ObjSetVar2\fR.
-Those object-based procedures read, modify, and create
-a variable whose name is held in a Tcl object instead of a string.
-They also return a pointer to the object
-which is the variable's value instead of returning a string.
-Operations on objects can be faster since objects
-hold an internal representation that can be manipulated more efficiently.
-.PP
-\fBTcl_SetVar\fR and \fBTcl_SetVar2\fR
+.VS 8.1
+\fBTcl_SetVar2Ex\fR, \fBTcl_SetVar\fR, \fBTcl_SetVar2\fR, and
+\fBTcl_ObjSetVar2\fR 
 will create a new variable or modify an existing one.
-Both of these procedures set the given variable to the value
-given by \fInewValue\fR, and they return a pointer to a
-copy of the variable's new value, which is stored in Tcl's
+These procedures set the given variable to the value
+given by \fInewValuePtr\fR or \fInewValue\fR and return a
+pointer to the variable's new value, which is stored in Tcl's
 variable structure.
-Tcl keeps a private copy of the variable's value, so the caller
-may change \fInewValue\fR after these procedures return without
-affecting the value of the variable.
+\fBTcl_SetVar2Ex\fR and \fBTcl_ObjSetVar2\fR take the new value as a
+Tcl_Obj and return
+a pointer to a Tcl_Obj.  \fBTcl_SetVar\fR and \fBTcl_SetVar2\fR
+take the new value as a string and return a string; they are
+usually less efficient than \fBTcl_ObjSetVar2\fR.  Note that the
+return value may be different than the \fInewValuePtr\fR or
+.VE
+\fInewValue\fR argument, due to modifications made by write traces.
 If an error occurs in setting the variable (e.g. an array
-variable is referenced without giving an index into the array),
-they return NULL.
+variable is referenced without giving an index into the array)
+NULL is returned and an error message is left in \fIinterp\fR's
+result if the \fBTCL_LEAVE_ERR_MSG\fR \fIflag\fR bit is set.
 .PP
-The name of the variable may be specified to
-\fBTcl_SetVar\fR and \fBTcl_SetVar2\fR in either of two ways.
-If \fBTcl_SetVar\fR is called, the variable name is given as
+.VS 8.1
+\fBTcl_GetVar2Ex\fR, \fBTcl_GetVar\fR, \fBTcl_GetVar2\fR, and
+\fBTcl_ObjGetVar2\fR
+return the current value of a variable.
+The arguments to these procedures are treated in the same way
+as the arguments to the procedures described above.
+Under normal circumstances, the return value is a pointer
+to the variable's value.  For \fBTcl_GetVar2Ex\fR and
+\fBTcl_ObjGetVar2\fR the value is
+returned as a pointer to a Tcl_Obj.  For \fBTcl_GetVar\fR and
+\fBTcl_GetVar2\fR the value is returned as a string; this is
+usually less efficient, so \fBTcl_GetVar2Ex\fR or \fBTcl_ObjGetVar2\fR
+are preferred.
+.VE
+If an error occurs while reading the variable (e.g. the variable
+doesn't exist or an array element is specified for a scalar
+variable), then NULL is returned and an error message is left
+in \fIinterp\fR's result if the \fBTCL_LEAVE_ERR_MSG\fR \fIflag\fR
+bit is set.
+.PP
+\fBTcl_UnsetVar\fR and \fBTcl_UnsetVar2\fR may be used to remove
+a variable, so that future attempts to read the variable will return
+an error.
+The arguments to these procedures are treated in the same way
+as the arguments to the procedures above.
+If the variable is successfully removed then TCL_OK is returned.
+If the variable cannot be removed because it doesn't exist then
+TCL_ERROR is returned and an error message is left
+in \fIinterp\fR's result if the \fBTCL_LEAVE_ERR_MSG\fR \fIflag\fR
+bit is set.
+If an array element is specified, the given element is removed
+but the array remains.
+If an array name is specified without an index, then the entire
+array is removed.
+.PP
+The name of a variable may be specified to these procedures in
+four ways:
+.IP [1]
+If \fBTcl_SetVar\fR, \fBTcl_GetVar\fR, or \fBTcl_UnsetVar\fR
+is invoked, the variable name is given as
 a single string, \fIvarName\fR.
 If \fIvarName\fR contains an open parenthesis and ends with a
 close parenthesis, then the value between the parentheses is
@@ -100,22 +165,31 @@ the characters before the first open
 parenthesis are treated as the name of an array variable.
 If \fIvarName\fR doesn't have parentheses as described above, then
 the entire string is treated as the name of a scalar variable.
-If \fBTcl_SetVar2\fR is called, then the array name and index
-have been separated by the caller into two separate strings,
-\fIname1\fR and \fIname2\fR respectively;  if \fIname2\fR is
-zero it means that a scalar variable is being referenced.
+.IP [2]
+If the \fIname1\fR and \fIname2\fR arguments are provided and
+\fIname2\fR is non-NULL, then an array element is specified and
+the array name and index have
+already been separated by the caller: \fIname1\fR contains the
+name and \fIname2\fR contains the index.
+.VS 8.1
+An error is generated
+if \fIname1\fR  contains an open parenthesis and ends with a
+close parenthesis (array element) and \fIname2\fR is non-NULL.
+.IP [3]
+If \fIname2\fR is NULL, \fIname1\fR is treated just like
+\fIvarName\fR in case [1] above (it can be either a scalar or an array
+element variable name).
+.VE
 .PP
 The \fIflags\fR argument may be used to specify any of several
 options to the procedures.
 It consists of an OR-ed combination of the following bits.
-Note that the flag bit TCL_PARSE_PART1 is only meaningful
-for the procedures Tcl_SetVar2 and Tcl_GetVar2.
 .TP
 \fBTCL_GLOBAL_ONLY\fR
-Under normal circumstances the procedures look up variables as follows:
+Under normal circumstances the procedures look up variables as follows.
 If a procedure call is active in \fIinterp\fR,
-a variable is looked up at the current level of procedure call.
-Otherwise, a variable is looked up first in the current namespace,
+the variable is looked up at the current level of procedure call.
+Otherwise, the variable is looked up first in the current namespace,
 then in the global namespace.
 However, if this bit is set in \fIflags\fR then the variable
 is looked up only in the global namespace
@@ -124,14 +198,10 @@ If both \fBTCL_GLOBAL_ONLY\fR and \fBTCL_NAMESPACE_ONLY\fR are given,
 \fBTCL_GLOBAL_ONLY\fR is ignored.
 .TP
 \fBTCL_NAMESPACE_ONLY\fR
-Under normal circumstances the procedures look up variables as follows:
-If a procedure call is active in \fIinterp\fR,
-a variable is looked up at the current level of procedure call.
-Otherwise, a variable is looked up first in the current namespace,
-then in the global namespace.
-However, if this bit is set in \fIflags\fR then the variable
-is looked up only in the current namespace
-even if there is a procedure call active.
+If this bit is set in \fIflags\fR then the variable
+is looked up only in the current namespace; if a procedure is active
+its variables are ignored, and the global namespace is also ignored unless
+it is the current namespace.
 .TP
 \fBTCL_LEAVE_ERR_MSG\fR
 If an error is returned and this bit is set in \fIflags\fR, then
@@ -142,9 +212,10 @@ If this flag bit isn't set then no error message is left
 and the interpreter's result will not be modified.
 .TP
 \fBTCL_APPEND_VALUE\fR
-If this bit is set then \fInewValue\fR is appended to the current
-value, instead of replacing it.
-If the variable is currently undefined, then this bit is ignored.
+If this bit is set then \fInewValuePtr\fR or \fInewValue\fR is
+appended to the current value instead of replacing it.
+If the variable is currently undefined, then the bit is ignored.
+This bit is only used by the \fBTcl_Set*\fR procedures.
 .TP
 \fBTCL_LIST_ELEMENT\fR
 If this bit is set, then \fInewValue\fR is converted to a valid
@@ -153,18 +224,6 @@ A separator space is appended before the new list element unless
 the list element is going to be the first element in a list or
 sublist (i.e. the variable's current value is empty, or contains
 the single character ``{'', or ends in `` }'').
-.TP
-\fBTCL_PARSE_PART1\fR
-If this bit is set when calling \fITcl_SetVar2\fR and \fITcl_GetVar2\fR,
-\fIname1\fR may contain both an array and an element name:
-if the name contains an open parenthesis and ends with a
-close parenthesis, then the value between the parentheses is
-treated as an element name (which can have any string value) and
-the characters before the first open
-parenthesis are treated as the name of an array variable.
-If the flag TCL_PARSE_PART1 is given,
-\fIname2\fR should be NULL since the array and element names
-are taken from \fIname1\fR.
 .PP
 \fBTcl_GetVar\fR and \fBTcl_GetVar2\fR
 return the current value of a variable.
@@ -178,8 +237,6 @@ or \fBTcl_SetVar2\fR).
 and TCL_LEAVE_ERR_MSG, both of
 which have
 the same meaning as for \fBTcl_SetVar\fR.
-In addition, \fBTcl_GetVar2\fR uses the bit TCL_PARSE_PART1,
-which has the same meaning as for \fBTcl_SetVar2\fR.
 If an error occurs in reading the variable (e.g. the variable
 doesn't exist or an array element is specified for a scalar
 variable), then NULL is returned.
@@ -198,7 +255,7 @@ If an array name is specified without an index, then the entire
 array is removed.

 .SH "SEE ALSO"
-Tcl_GetObjResult, Tcl_GetStringResult, Tcl_ObjGetVar2, Tcl_ObjSetVar2, Tcl_TraceVar
+Tcl_GetObjResult, Tcl_GetStringResult, Tcl_TraceVar

 .SH KEYWORDS
-array, interpreter, object, scalar, set, unset, variable
+array, get variable, interpreter, object, scalar, set, unset, variable
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) Sleep.3 1.3 96/03/25 20:07:21
+'\" RCS: @(#) $Id: Sleep.3,v 1.2 1998/09/14 18:39:50 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_Sleep 3 7.5 Tcl "Tcl Library Procedures"
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) SplitList.3 1.21 97/04/29 14:07:10
+'\" RCS: @(#) $Id: SplitList.3,v 1.2 1998/09/14 18:39:50 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_SplitList 3 7.5 Tcl "Tcl Library Procedures"
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) SplitPath.3 1.4 96/08/19 14:59:35
+'\" RCS: @(#) $Id: SplitPath.3,v 1.2 1998/09/14 18:39:50 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_SplitPath 3 7.5 Tcl "Tcl Library Procedures"
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) StaticPkg.3 1.4 96/09/04 11:21:26
+'\" RCS: @(#) $Id: StaticPkg.3,v 1.2 1998/09/14 18:39:50 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_StaticPackage 3 7.5 Tcl "Tcl Library Procedures"
@@ -5,25 +5,34 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) StrMatch.3 1.11 96/03/25 20:08:06
+'\" RCS: @(#) $Id: StrMatch.3,v 1.3 1999/05/22 01:20:11 stanton Exp $
 '\" 
 .so man.macros
-.TH Tcl_StringMatch 3 "" Tcl "Tcl Library Procedures"
+.TH Tcl_StringMatch 3 8.1 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_StringMatch \- test whether a string matches a pattern
+Tcl_StringMatch, Tcl_StringCaseMatch \- test whether a string matches a pattern
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
 .sp
 int
 \fBTcl_StringMatch\fR(\fIstring\fR, \fIpattern\fR)
+.VS 8.1
+.sp
+\fBTcl_StringCaseMatch\fR(\fIstring, pattern, nocase\fR)
+.VE 8.1
 .SH ARGUMENTS
 .AP char *string in
 String to test.
 .AP char *pattern in
 Pattern to match against string.  May contain special
 characters from the set *?\e[].
+.VS 8.1
+.AP int nocase in
+Specifies whether the match should be done case-sensitive (0) or
+case-insensitive (1).
+.VE 8.1
 .BE

 .SH DESCRIPTION
@@ -34,6 +43,13 @@ a given pattern.  If it does, then \fBTcl_StringMatch\fR returns
 used for matching is the same algorithm used in the ``string match''
 Tcl command and is similar to the algorithm used by the C-shell
 for file name matching;  see the Tcl manual entry for details.
+.VS 8.1
+.PP
+In \fBTcl_StringCaseMatch\fR, the algorithm is the same, but you have
+the option to make the matching case-insensitive.  If you choose this
+(by passing \fBnocase\fR as 1), then the string and pattern are
+essentially matched in the lower case.
+.VE 8.1

 .SH KEYWORDS
 match, pattern, string
@@ -4,35 +4,77 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) @(#) StringObj.3 1.13 97/06/25 13:40:25
+'\" RCS: @(#) $Id: StringObj.3,v 1.5 1999/06/15 01:16:21 hershey Exp $
 '\" 
 .so man.macros
-.TH Tcl_StringObj 3 8.0 Tcl "Tcl Library Procedures"
+.TH Tcl_StringObj 3 8.1 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_NewStringObj, Tcl_SetStringObj, Tcl_GetStringFromObj, Tcl_AppendToObj, Tcl_AppendStringsToObj, Tcl_SetObjLength, TclConcatObj \- manipulate Tcl objects as strings
+Tcl_NewStringObj, Tcl_NewUnicodeObj, Tcl_SetStringObj, Tcl_SetUnicodeObj, Tcl_GetStringFromObj, Tcl_GetString, Tcl_GetUnicode, Tcl_GetUniChar, Tcl_GetCharLength, Tcl_GetRange, Tcl_AppendToObj, Tcl_AppendUnicodeToObj, Tcl_AppendStringsToObj, Tcl_AppendStringsToObjVA, Tcl_AppendObjToObj, Tcl_SetObjLength, Tcl_ConcatObj \- manipulate Tcl objects as strings
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
 .sp
 Tcl_Obj *
 \fBTcl_NewStringObj\fR(\fIbytes, length\fR)
+.VS 8.1.2
 .sp
+Tcl_Obj *
+\fBTcl_NewUnicodeObj\fR(\fIunicode, numChars\fR)
+.VE
+.sp
+void
 \fBTcl_SetStringObj\fR(\fIobjPtr, bytes, length\fR)
+.VS 8.1.2
+.sp
+void
+\fBTcl_SetUnicodeObj\fR(\fIobjPtr, unicode, numChars\fR)
+.VE
 .sp
 char *
 \fBTcl_GetStringFromObj\fR(\fIobjPtr, lengthPtr\fR)
 .sp
-\fBTcl_AppendToObj\fR(\fIobjPtr, bytes, length\fR)
+char *
+\fBTcl_GetString\fR(\fIobjPtr\fR)
+.VS 8.1.2
 .sp
+Tcl_UniChar *
+\fBTcl_GetUnicode\fR(\fIobjPtr\fR)
+.sp
+Tcl_UniChar
+\fBTcl_GetUniChar\fR(\fIobjPtr, index\fR)
+.sp
+int
+\fBTcl_GetCharLength\fR(\fIobjPtr\fR)
+.sp
+Tcl_Obj *
+\fBTcl_GetRange\fR(\fIobjPtr, first, last\fR)
+.VE
+.sp
+void
+\fBTcl_AppendToObj\fR(\fIobjPtr, bytes, length\fR)
+.VS 8.1.2
+.sp
+void
+\fBTcl_AppendUnicodeToObj\fR(\fIobjPtr, unicode, numChars\fR)
+.VE
+.sp
+void
+\fBTcl_AppendObjToObj\fR(\fIobjPtr, appendObjPtr\fR)
+.sp
+void
 \fBTcl_AppendStringsToObj\fR(\fIobjPtr, string, string, ... \fB(char *) NULL\fR)
 .sp
+void
+\fBTcl_AppendStringsToObjVA\fR(\fIobjPtr, argList\fR)
+.sp
+void
 \fBTcl_SetObjLength\fR(\fIobjPtr, newLength\fR)
 .sp
 Tcl_Obj *
 \fBTcl_ConcatObj\fR(\fIobjc, objv\fR)
 .SH ARGUMENTS
-.AS Tcl_Interp *lengthPtr out
+.AS Tcl_Interp *appendObjPtr in/out
 .AP char *bytes in
 Points to the first byte of an array of bytes
 used to set or append to a string object.
@@ -42,13 +84,37 @@ unless \fIlength\fR is negative.
 The number of bytes to copy from \fIbytes\fR when
 initializing, setting, or appending to a string object.
 If negative, all bytes up to the first null are used.
+.AP Tcl_UniChar *unicode in
+Points to the first byte of an array of Unicode characters
+used to set or append to a string object.
+This byte array may contain embedded null characters
+unless \fInumChars\fR is negative.
+.VS 8.1.2
+.AP int numChars in
+The number of Unicode characters to copy from \fIunicode\fR when
+initializing, setting, or appending to a string object.
+If negative, all characters up to the first null character are used.
+.AP int index in
+The index of the Unicode character to return.
+.AP int first in
+The index of the first Unicode character in the Unicode range to be
+returned as a new object.
+.AP int last in
+The index of the last Unicode character in the Unicode range to be
+returned as a new object.
+.VE
 .AP Tcl_Obj *objPtr in/out
 Points to an object to manipulate.
+.AP Tcl_Obj *appendObjPtr in
+The object to append to \fIobjPtr\fR in \fBTcl_AppendObjToObj\fR.
 .AP int *lengthPtr out
 If non-NULL, the location where \fBTcl_GetStringFromObj\fR will store
 the the length of an object's string representation.
 .AP char *string in
 Null-terminated string value to append to \fIobjPtr\fR.
+.AP va_list argList in
+An argument list which must have been initialised using
+\fBTCL_VARARGS_START\fR, and cleared using \fBva_end\fR.
 .AP int newLength in
 New length for the string value of \fIobjPtr\fR, not including the
 final NULL character.
@@ -66,31 +132,75 @@ of the object to store additional information to make the string
 manipulations more efficient.  In particular, they make a series of
 append operations efficient by allocating extra storage space for the
 string so that it doesn't have to be copied for each append.
+.VS 8.1.2
+Also, indexing and length computations are optimized because the
+Unicode string representation is calculated and cached as needed.
+.VE
 .PP
+.VS 8.1.2
 \fBTcl_NewStringObj\fR and \fBTcl_SetStringObj\fR create a new object
-or modify an existing object to hold a copy of
-the string given by \fIbytes\fR and \fIlength\fR.
-\fBTcl_NewStringObj\fR returns a pointer to a newly created object
-with reference count zero.
-Both procedures set the object to hold a copy of the specified string.
-\fBTcl_SetStringObj\fR frees any old string representation
-as well as any old internal representation of the object.
+or modify an existing object to hold a copy of the string given by
+\fIbytes\fR and \fIlength\fR.  \fBTcl_NewUnicodeObj\fR and
+\fBTcl_SetUnicodeObj\fR create a new object or modify an existing
+object to hold a copy of the Unicode string given by \fIunicode\fR and
+\fInumChars\fR.  \fBTcl_NewStringObj\fR and \fBTcl_NewUnicodeObj\fR
+return a pointer to a newly created object with reference count zero.
+All four procedures set the object to hold a copy of the specified
+string.  \fBTcl_SetStringObj\fR and \fBTcl_SetUnicodeObj\fR free any
+old string representation as well as any old internal representation
+of the object.
+.VE
 .PP
-\fBTcl_GetStringFromObj\fR returns an object's string representation.
-This is given by the returned byte pointer
-and length, which is stored in \fIlengthPtr\fR if it is non-NULL.
-If the object's string representation is invalid
-(its byte pointer is NULL),
-the string representation is regenerated from the
-object's internal representation.
-The storage referenced by the returned byte pointer
-is owned by the object manager and should not be modified by the caller.
+\fBTcl_GetStringFromObj\fR and \fBTcl_GetString\fR return an object's
+string representation.  This is given by the returned byte pointer and
+(for \fBTcl_GetStringFromObj\fR) length, which is stored in
+\fIlengthPtr\fR if it is non-NULL.  If the object's UTF string
+representation is invalid (its byte pointer is NULL), the string
+representation is regenerated from the object's internal
+representation.  The storage referenced by the returned byte pointer
+is owned by the object manager and should not be modified by the
+caller.  The procedure \fBTcl_GetString\fR is used in the common case
+where the caller does not need the length of the string
+representation.
+.PP
+.VS 8.1.2
+\fBTcl_GetUnicode\fR returns an object's value as a Unicode string.
+\fBTcl_GetUniChar\fR returns the \fIindex\fR'th character in the
+object's Unicode representation.
+.PP
+\fBTcl_GetRange\fR returns a newly created object comprised of the
+characters between \fIfirst\fR and \fIlast\fR (inclusive) in the
+object's Unicode representation.  If the object's Unicode
+representation is invalid, the Unicode representation is regenerated
+from the object's string representation.
+.PP
+\fBTcl_GetCharLength\fR returns the number of characters (as opposed
+to bytes) in the string object.
 .PP
 \fBTcl_AppendToObj\fR appends the data given by \fIbytes\fR and
-\fIlength\fR to the object specified by \fIobjPtr\fR.  It does this
-in a way that handles repeated calls relatively efficiently (it
-overallocates the string space to avoid repeated reallocations
-and copies of object's string value).
+\fIlength\fR to the string representation of the object specified by
+\fIobjPtr\fR.  If the object has an invalid string representation,
+then an attempt is made to convert \fIbytes\fR is to the Unicode
+format.  If the conversion is successful, then the converted form of
+\fIbytes\fR is appended to the object's Unicode representation.
+Otherwise, the object's Unicode representation is invalidated and
+converted to the UTF format, and \fIbytes\fR is appended to the
+object's new string representation.
+.PP
+\fBTcl_AppendUnicodeToObj\fR appends the Unicode string given by
+\fIunicode\fR and \fInumChars\fR to the object specified by
+\fIobjPtr\fR.  If the object has an invalid Unicode representation,
+then \fIunicode\fR is converted to the UTF format and appended to the
+object's string representation.  Appends are optimized to handle
+repeated appends relatively efficiently (it overallocates the string
+or Unicode space to avoid repeated reallocations and copies of
+object's string value).
+.PP
+\fBTcl_AppendObjToObj\fR is similar to \fBTcl_AppendToObj\fR, but it
+appends the string or Unicode value (whichever exists and is best
+suited to be appended to \fIobjPtr\fR) of \fIappendObjPtr\fR to
+\fIobjPtr\fR.
+.VE
 .PP
 \fBTcl_AppendStringsToObj\fR is similar to \fBTcl_AppendToObj\fR
 except that it can be passed more than one value to append and
@@ -99,6 +209,10 @@ values may contain internal null characters).  Any number of
 \fIstring\fR arguments may be provided, but the last argument
 must be a NULL pointer to indicate the end of the list.
 .PP
+\fBTcl_AppendStringsToObjVA\fR is the same as \fBTcl_AppendStringsToObj\fR
+except that instead of taking a variable number of arguments it takes an
+argument list.
+.PP
 The \fBTcl_SetObjLength\fR procedure changes the length of the
 string value of its \fIobjPtr\fR argument.  If the \fInewLength\fR
 argument is greater than the space allocated for the object's
@@ -129,4 +243,4 @@ Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount

 .SH KEYWORDS
 append, internal representation, object, object type, string object,
-string type, string representation, concat, concatenate
+string type, string representation, concat, concatenate, unicode
--- a/Show More
+++ b/Show More