2001-08-07  Miguel Sofer <msofer@users.sourceforge.net>

	* generic/tclExecute.c: Avoid panic when there are extra items in
	  the tcl stack [Bugs #406709 and 439843, Patch #414470]
	* tests/foreach.test: test to exercise the patch

2001-08-06  Jeff Hobbs  <jeffh@ActiveState.com>

	* generic/tclCmdMZ.c (Tcl_RegexpObjCmd, Tcl_RegsubObjCmd):
	reordered the retrieval of arguments to avoid shimmering bug when
	the pattern and string referenced the same object.

	* unix/configure: regenerated
	* unix/tcl.m4: added GNU (HURD) configuration target. (brinkmann)
	[Patch: #442974]

2001-08-03  Jeff Hobbs  <jeffh@ActiveState.com>

	* win/configure: regenerated
	* win/tcl.m4: fixed DLLSUFFIX definition to always be ${DBGX}.dll.
	This is necessary for TEA compliant builds that build shared
	against a static-built Tcl.
	* win/Makefile.in ($(TCLSH)): added $(TCL_STUB_LIB_FILE) to build
	target, otherwise it wouldn't get generated in a static build.

2001-08-06  Andreas Kupries <andreas_kupries@users.sourceforge.net>

	* generic/tclIOCmd.c (Tcl_GetsObjCmd): Applied patch from SF item
	  [442665] to fix the bug reported by it. The function can corrupt
	  a freed object if it is called with objc == 3. This is because
	  it retrieves resultPtr and does not increment its reference
	  count, but then calls Tcl_ObjSetVar2, which causes the retrieved
	  resultPtr object to be released.

2001-07-18  Andreas Kupries <andreas_kupries@users.sourceforge.net>

	* doc/bgerror.n: Fixed Tk! Bug #415757.

2001-07-18  Andreas Kupries <andreas_kupries@users.sourceforge.net>

	* generic/tclIO.c: Aftermath to [SF #427196]. Squash empty buffers
	  if they are smaller than the requested buffersize, to prevent
	  reusage of old buffers and to honor changes in the requested
	  buffersize made by the user.

2001-07-17  Andreas Kupries <andreas_kupries@users.sourceforge.net>

	* generic/tclIO.c (GetInput): Fixed [SF #427196]. Memory was
	  overwritten because a buffer was used after a change of the
	  requested buffersize together with that requested buffersize and
	  not its actual size, which was smaller. Note that the continous
	  reuse of the smaller buffer negatively impacts performance. The
	  system never allocates a buffer with the newly requested bigger
	  buffersize.

2001-07-16  Jeff Hobbs  <jeffh@ActiveState.com>

	* win/tclWinPipe.c (PipeClose2Proc): constrained the mutex lock to
	just the TerminateThread call and waiting for termination. (jsmith)

2001-07-02  Jeff Hobbs  <jeffh@ActiveState.com>

	* tests/util.test: added util-4.6
	* generic/tclUtil.c (Tcl_ConcatObj): Corrected walking backwards
	over utf-8 chars. [Bug #227512]

2001-06-27  Jeff Hobbs  <jeffh@ActiveState.com>

	* generic/tclUtf.c (Tcl_UtfBackslash): Corrected backslash
	handling of multibyte utf-8 chars. [Bug #217987]

	* generic/tclCmdIL.c (InfoProcsCmd): fixed potential mem leak in
	info procs that created objects without using them.

	* generic/tclCompCmds.c (TclCompileStringCmd): fixed mem leak when
	string command failed to parse the subcommand.

2001-05-22  Jeff Hobbs  <jeffh@ActiveState.com>

	* generic/tclObj.c (TclAllocateFreeObjects): simplified
	objSizePlusPadding to use sizeof(Tcl_Obj) (max)

2001-05-04  Daniel Steffen <das@users.sourceforge.net>

        ** Mac 8.3.3 binary release 

	**  detailed change log for changes to mac code for 8.3.3 
	**  (expands on log entries below marked 2001-04-04  Jeff Hobbs)

	* generic/tcl.h: MAC_TCL: addition of ConditionalMacros.h and use of
	DLLIMPORT and DLLEXPORT like on other platforms.  ( => no longer need
	the .exp files and can remove use of #pragma export that never worked
	well)

	* mac/tclMacShLib.exp:
	* mac/tclMacOSA.exp:
	* mac/tclMacMSLPrefix.h: removed files

	* mac/MW_TclBuildLibHeader.h:
	* mac/MW_TclBuildLibHeader.pch:
	* mac/MW_TclHeaderCommon.h:
	* mac/MW_TclStaticHeader.h:
	* mac/MW_TclStaticHeader.pch: new precompiled header files

	* mac/MW_TclAppleScriptHeader.pch:
	* mac/MW_TclHeader.pch:
	* mac/MW_TclTestHeader.pch:
	* mac/tclMacCommonPch.h: revised precompiled header handling: now
	include a common header file 'MW_TclHeaderCommon.h' from all .pch
	files, the .pch files themselves now only setup #defines (e.g.
	BUILD_tcl, STATIC_BUILD, TCL_DEBUG, TCL_THREADS) like in makefiles on
	other platforms.

	* mac/tclMac.h:
	* mac/tclMacPort.h:
	* mac/tclMacInt.h: use of BUILD_tcl and TCL_STORAGE_CLASS like on other
	platforms, standardize #include'd files to what's done on other
	platforms, removed use of #pragma export.

	* mac/tcltkMacBuildSupport.sea.hqx: new archive of mac build support
	files & suggested build environment directory hierarchy: 
	- 'Building MacTclTk' & 'CW Pro6 changes' readme's.
	- projects for MoreFiles 1.5.1 static & shared libraries.
	- project & sources for 'pseudoCarbonSupport', see below.

	* mac/tclMacProjects.sea.hqx: updated mac build project files:
	- build support for CodeWarrior Pro6, UnivIntf 3.4 & shared runtime
	libraries: the MSL libraries and MoreFiles are no longer compiled into
	Tcl.shlb, all non-static binaries now use the Pro6 shared runtime
	libraries and MoreFiles.shlb.  These shlbs are merged into the standard
	Wish and TclShell, but 3rd party applications linking with Tcl.shlb or
	Tk.shlb need to setup access to them.  (see the "(sh-ppc)" targets
	for how to do this.)
	- Merging the full MSL.shlb and the other shlbs into Wish & TclShell
	makes them a bit larger than before, use unmerged binaries to avoid
	copying the shared code with every application, e.g. when deploying
	numerous Wish based droplets.
	- Note that using CW Pro5 to compile extensions is in principle still
	possible, but need to link with Pro6 runtime libraries.
	- Tclapplescript now loads and runs on CFM68k.
	- Highly experimental "pseudoCarbon" support for Tcl only on OS 8/9:
	binaries in "Build:(Carbon):" link against CarbonLib instead of
	InterfaceLib, however the actual code has not been carbonized! i.e. it
	will not run on OSX and may not even run properly with CarbonLib. 
	This should in principle allow you to build & test OS9 CFM Carbon
	binaries that need to link with Tcl.shlb.  On OSX you can use the
	native Tcl.framework, but you have to build a MachO binary as there
	is no CFM glue lib for Tcl.framework.
	the library pseudoCarbonSupport.shlb manually loads the symbols
	from InterfaceLib that are not in CarbonLib but are needed by the
	uncarbonized code in Tcl.shlb and TclShell.

	* generic/tclMain.c: MAC_TCL: workaround for broken/non-standard isatty
	on MW Pro6, #include <unistd.h> instead of defining isatty

	* mac/tclMacPort.h: MW Pro6 changes for MSL fcntl.h, stat.h & isatty

	* mac/tclMacAppInit.c: add EXTERN to InstallConsole to enable DLL
	export via the TCL_STORAGE_CLASS mechanism.

	* mac/tclMacFCmd.c: fix for FSpDirectoryCopy API change

	* mac/tclMacLibrary.c: emit compile time error when
	TCL_REGISTER_LIBRARY and USE_TCL_STUBS are both defined at the same
	time in an extension, this use is not currently supported and will
	result in a crash when dynamically loading the extension.

	* mac/tclMacApplication.r:
	* mac/tclMacLibrary.r:
	* mac/tclMacOSA.r:
	* mac/tclMacResource.r: fixed obsolete copyrights/dates in version
	strings; updated version strings to standard usage; added support for
	'(Support Libraries)' subfolder for shared runtime libraries in
	unmerged binaries; commented out demo setting of "Tcl Environment
	Variables"

	* mac/tclMacChan.c:
	* mac/tclMacSock.c: cast for *BlockMode

	* mac/tclMacUtil.c:
	* mac/tclMacMath.h: removed obsolete hypot() definition

	* generic/tclIntPlatDecls.h:
	* generic/tclInt.decls:
	* generic/tclStubInit.c:
	* mac/tclMacNotify.c:
	* mac/tclMacOSA.c:
	* mac/tclMacUtil.c:
	* generic/tclThreadTest.c: renamed routines conflicting with standard
	Apple or MoreFiles headers (at compile or link time):
	    GetGlobalMouse         -> GetGlobalMouseTcl
    	FSpGetDirectoryID      -> FSpGetDirectoryIDTcl
    	FSpOpenResFileCompat   -> FSpOpenResFileCompatTcl
    	FSpCreateResFileCompat -> FSpCreateResFileCompatTcl
		NewThread              -> NewTestThread
	the renamed MoreFiles *Tcl routines are just wrappers calling into the
	MoreFiles DLL.

	* mac/tclMacCommonPch.h:
	* mac/tclMacThrd.c:
	* mac/tclMacPanic.c: removed OLDROUTINENAMES define, renamed obsolete
	apple API names to modern equivalents; UH3.4 support: added #include
	<ControlDefinitions.h>, updated New*Proc() calls to New*UPP().

	* mac/tclMacUnix.c: added missing (Tcl_Obj ***) cast to
	Tcl_ListObjGetElements call

	* mac/tclMacAlloc.c: modernized TclpSysAlloc() to use temporary
	memory instead of system heap memory when available (MacOS
	>= 7.5 and possibly earlier, use of system heap has been
	discouraged for a long time and has many disadvantages, e.g. memory
	isn't paged out, and errors can very easily bring the system down);
	fixed crashing bug in TclpSysRealloc() and CleanUpExitProc() where
	memory was being accessed after having been deallocated; fixed
	memory leak in (de)allocation code (for every block ever allocated
	with TclpSysAlloc, a Ptr was leaked), if temporary memory is
	available, don't track allocated memory, instead use
	RecoverHandle() to get Handle from Ptr, otherwise use doubly linked
	list to correctly track memory and free all allocated memory; added
	new option for ConfigureMemory: MEMORY_DONT_USE_TEMPMEM, disables
	use of temporary memory even when it would be available, only
	necessary when writing e.g. a driver (using tcl??); increased
	fraction of application heap reserved for OS routines to 512K

2001-04-06  Jeff Hobbs  <jeffh@ActiveState.com>

	* unix/install-sh: added -S option
	* unix/tcl.m4: added Rhapsody/Darwin target
	* unix/tclLoadDyld.c (TclpLoadFile): 
	* unix/tclMtherr.c (matherr): added support for Mac OS X

2001-04-05  Jeff Hobbs  <jeffh@ActiveState.com>

	* generic/tclObj.c (TclAllocateFreeObjects): simplified
	objSizePlusPadding to use sizeof(Tcl_Obj) (max)

	* win/README:
	* win/README.binary: removed note about use of registry (hasn't
	been used for loading since 8.0).

	* win/configure:
	* win/tcl.m4: added -link50compat

	* mac/tclMacProjects.sea.hqx: fixed accidental swap with Tk
	project files.

2001-04-04  Jeff Hobbs  <jeffh@ActiveState.com>

	** Start changes for improved mac build (steffen)  **

	* mac/tclMacShLib.exp:
	* mac/tclMacMSLPrefix.h: removed files

	* generic/tcl.h: addition of ConditionalMacros.h and use of
	DLLIMPORT and DLLEXPORT.

	* generic/tclIntPlatDecls.h:
	* generic/tclInt.decls:
	* generic/tclMain.c:
	* generic/tclStubInit.c:
	* generic/tclThreadTest.c: NewThread -> NewTestThread
	* mac/MW_TclAppleScriptHeader.pch:
	* mac/MW_TclHeader.pch:
	* mac/MW_TclTestHeader.pch:
	* mac/tclMac.h:
	* mac/tclMacAppInit.c:
	* mac/tclMacApplication.r:
	* mac/tclMacChan.c: cast for *BlockMode
	* mac/tclMacCommonPch.h:
	* mac/tclMacFCmd.c:
	* mac/tclMacInt.h:
	* mac/tclMacLibrary.c:
	* mac/tclMacLibrary.r:
	* mac/tclMacMath.h:
	* mac/tclMacNotify.c:
	* mac/tclMacOSA.c:
	* mac/tclMacOSA.r:
	* mac/tclMacPanic.c:
	* mac/tclMacPort.h:
	* mac/tclMacResource.r:
	* mac/tclMacSock.c: cast for *BlockMode
	* mac/tclMacThrd.c:
	* mac/tclMacUnix.c:
	* mac/tclMacUtil.c: changed mac declarations to use Tcl ending,
	fixed copyrights, updated headers, fixed comments, updated
	resource files.  Mac builds are now meant to be build with
	MetroWerks CW 6.

	* mac/MW_TclBuildLibHeader.h:
	* mac/MW_TclBuildLibHeader.pch:
	* mac/MW_TclHeaderCommon.h:
	* mac/MW_TclStaticHeader.h:
	* mac/MW_TclStaticHeader.pch:
	* mac/tcltkMacBuildSupport.sea.hqx: new files

	* mac/tclMacProjects.sea.hqx: new mac build project files.

	** End changes for improved mac build (steffen) **

	* unix/configure:
	* unix/tcl.m4: extended test of termios vs. termio vs. sgtty to
	better detect result on Linux and when certain configure
	redirections are being used. (max) [Patch #402923; Bug #227412,
	#219194]

2001-04-03  Jeff Hobbs  <jeffh@ActiveState.com>

	* generic/tclListObj.c (Tcl_SetListObj): set objPtr->length = 0 in
	empty object case to maintain sanctity of Tcl_Obj bytes/length
	pairing. (porter) [Patch #405998]

	* README:
	* mac/README:
	* win/README:
	* win/README.binary:
	* unix/README: updated patchlevel information to 8.3.3 and
	updated links and notes.

	* generic/tcl.h:
	* tools/tcl.wse.in:
	* win/configure.in (TCL_PATCH_LEVEL):
	* win/configure:
	* unix/configure:
	* unix/configure.in (TCL_PATCH_LEVEL):
	* unix/tcl.spec: updated patchlevel information to 8.3.3

	***************************************************************
	** START OF ASYNC BACKPORT LOG (8.4aCVS 2001-04-03 -> 8.3.3) **
	***************************************************************

	* doc/CrtChannel.3:
	* doc/CrtSlave.3:
	* doc/DetachPids.3:
	* doc/Eval.3:
	* doc/ObjectType.3:
	* doc/StrMatch.3:
	* doc/after.n:
	* doc/append.n:
	* doc/bgerror.n:
	* doc/binary.n:
	* doc/break.n:
	* doc/case.n:
	* doc/cd.n:
	* doc/close.n:
	* doc/concat.n:
	* doc/continue.n:
	* doc/dde.n:
	* doc/encoding.n:
	* doc/eof.n:
	* doc/error.n:
	* doc/eval.n:
	* doc/exec.n:
	* doc/exit.n:
	* doc/fblocked.n:
	* doc/fileevent.n:
	* doc/filename.n:
	* doc/flush.n:
	* doc/for.n:
	* doc/foreach.n:
	* doc/format.n:
	* doc/gets.n:
	* doc/glob.n:
	* doc/global.n:
	* doc/http.n:
	* doc/if.n:
	* doc/incr.n:
	* doc/join.n:
	* doc/lappend.n:
	* doc/library.n:
	* doc/lindex.n:
	* doc/linsert.n:
	* doc/list.n:
	* doc/llength.n:
	* doc/load.n:
	* doc/lrange.n:
	* doc/lreplace.n:
	* doc/lsort.n:
	* doc/man.macros:
	* doc/memory.n:
	* doc/open.n:
	* doc/package.n:
	* doc/packagens.n:
	* doc/pid.n:
	* doc/pkgMkIndex.n:
	* doc/proc.n:
	* doc/puts.n:
	* doc/pwd.n:
	* doc/read.n:
	* doc/regexp.n:
	* doc/regsub.n:
	* doc/rename.n:
	* doc/resource.n:
	* doc/return.n:
	* doc/scan.n:
	* doc/seek.n:
	* doc/set.n:
	* doc/split.n:
	* doc/string.n:
	* doc/subst.n:
	* doc/switch.n:
	* doc/tclvars.n:
	* doc/tell.n:
	* doc/time.n:
	* doc/unknown.n:
	* doc/update.n:
	* doc/uplevel.n:
	* doc/upvar.n:
	* doc/variable.n:
	* doc/vwait.n:
	* doc/while.n: doc clarifications and cleanup from 8.4aCVS docs

2001-04-02  Jeff Hobbs  <jeffh@ActiveState.com>

	* win/configure:
	* win/tcl.m4 (SHLIB_LD):  added -incremental:no. [Bug #219381]

2001-03-30  Jeff Hobbs  <jeffh@ActiveState.com>

	* generic/tclCkalloc.c (TclFinalizeMemorySubsystem): set curTagPtr
	to NULL to allow for reuse.
	* generic/tclEvent.c (Tcl_Finalize): moved the tsdPtr
	initialization inside the subsystemsInitialized check to prevent
	it potentially getting called twice during finalization.  (wu)
	[Patch #403532, Bug #219391]

	* win/tclWinSock.c (SocketEventProc): Fixed race condition in
	readability of socket on Windows.
	[Patch #410674, Bug #219205 #219333]

	* win/tcl.m4: added imm32.lib to LIBS_GUI for Tk IME support.

	* win/Makefile.in (install-doc): improved install-* targets to use
	their base build dependency.

2001-03-29  Mo DeJong  <mdejong@redhat.com>

	* tests/interp.test: Print out warning when
	testinterpdelete command is not defined.
	Add tests that checks to make sure a
	child interp inherits the parent's cwd.

2001-03-29  Jeff Hobbs  <jeffh@activestate.com>

	* unix/tclUnixPipe.c (TclpCreateTempFile): prevent potential race
	condition and security leak in tmp filename creation.
 	(max) [Patch #402924]

	* unix/configure:
	* unix/tcl.m4: corrected IRIX-5.x config to not use -n32.
 	(english) [Patch #403626]

	* unix/tclUnixThrd.c (Tcl_ConditionWait): fixed handling of
	timeout for threads (corrects excessive CPU usage issue for Tk on
	Unix in threaded Tcl environment). (ruppert) [Bug #411603]

2001-03-26  Donal K. Fellows  <fellowsd@cs.man.ac.uk>

	* win/tclWinInt.h (tclWinTCharEncoding): Removed as now a static
	variable in win/tclWin32Dll.c instead.

2001-03-23  Jeff Hobbs  <jeffh@activestate.com>

	* generic/tclVar.c (Tcl_ArrayObjCmd): Corrected retrieval of
	resultPtr to prevent possible corruption.

	* generic/tclNamesp.c (Tcl_Import): Correctly freed a DString.
 	(lavana) [Patch #403755]

2001-03-14  Don Porter  <dgp@users.sourceforge.net>
	* library/package.tcl (pkg_mkIndex):  Added patch from Vince
	Darley to make [pkg_mkIndex -verbose] even more verbose.
	[Bug 219349, Patch 403529]

2001-03-13  Donal K. Fellows  <fellowsd@cs.man.ac.uk>

	* generic/tclCmdMZ.c (Tcl_StringObjCmd): A missing
	{return TCL_OK;} was causing memory corruption.  [Bug #408002]

	* generic/tclExecute.c (TclDeleteExecEnv, GrowEvaluationStack,
	TclExecuteByteCode): Added some casts to ClientData that are
	apparently needed on some architectures.

2001-03-02  Donal K. Fellows  <fellowsd@cs.man.ac.uk>

	* generic/tclExecute.c (TclExecuteByteCode): Fixed bug that could
	pass pointers to freed memory to command implementations, which
	most obviously caused some weird behaviour with [info level], but
	could have caused problems with user code and command traces too.
	[Bug 404865, Patch 405436]

2001-02-15  Donal K. Fellows  <fellowsd@cs.man.ac.uk>

	* generic/tclCmdMZ.c (Tcl_SplitObjCmd): Improved efficiency of
	splitting strings into individual characters by adding hash so
	that only one Tcl_Obj per character is created.  Improves
	performance of splitting of short strings and makes a huge
	difference to splitting of long strings, such as is done in the
	mime package in tcllib.  [Bug #131523]

2001-01-30  Don Porter  <dgp@users.sourceforge.net>
	* generic/tclIO.c (CopyData): Moved code that updates the count
	of how many bytes are left to copy.  Corrects bug that when
	writing occurs in the background, the copy loop could be
	escaped without updating the count, causing CopyData() to try
	to copy more bytes than the toRead value originally passed to
	TclCopyChannel(), leading to hangs and misreporting of number
	of bytes copied. [Bug 118203, Patch 103432]

2001-01-04  Don Porter  <dgp@users.sourceforge.net>
	* tests/unixInit.test:
	* unix/tclUnixInit.c (TclpInitLibraryPath):
	* win/tclWinInit.c (TclpInitLibraryPath):  Several entries in
	the library path ($tcl_libPath) are determined relative to the
	absolute path of the executable.  When the executable is
	installed in or near the root directory of the file system,
	relative pathnames were being incorrectly generated, and in
	the worst case, memory access violations were crashing the program.
	[Bug 119416, Patch 102972]

2000-12-14  Don Porter  <dgp@users.sourceforge.net>

	* generic/tclExecute.c:
	* tests/expr-old.test:  Re-wrote Tcl's [expr rand()] and
	[expr srand($seed)] implementations, fixing a range error
	on some 64-bit platforms.  Added tests that detect the bug.
	The rewrite changes the seed -> sequence map on 64-bit
	platforms, only for seed >= 2^31, a slight incompatibility.
	[Bug 121072, Patch 102781]

2000-12-10  Don Porter  <dgp@users.sourceforge.net>

	* library/init.tcl:
	* library/msgcat/msgcat.tcl:
	* library/msgcat/pkgIndex.tcl:
	* library/opt/optparse.tcl:
	* library/opt/pkgIndex.tcl: Where [uplevel] is used in a proc
	to evaluate a Tcl built-in command in the caller's context,
	the built-in commands are now fully namespace-qualified.  This
	prevents problems when the caller context is in a namespace where
	the built-in command name has been used by a command in the
	namespace.  (For example, [::ns::set] might be called instead
	of the intended [::set]).  [Bug #119422, Patch #102545]

2000-12-09  jeff hobbs  <jhobbs@interwoven.com>

	* docs/scan.n:
	* tests/scan.test:
	* generic/tclScan.c (Tcl_ScanObjCmd): changed %o and %x to use
	strtoul instead of strtol to correctly preserve scan<>format
	conversion of large integers.  [Patch #102663, Bug #124600]

	* generic/tclExecute.c (TclExecuteByteCode): Commited patch fixing
	handling of {!<boolean>} in expressions. [Patch #102702]

2000-12-08  jeff hobbs  <jhobbs@interwoven.com>

	* library/init.tcl: Added support for PATHEXT variable in
	auto_execok, recognizing the proper set of executable extensions
	on Windows.  [Patch #102719]

2000-12-08  Andreas Kupries  <a.kupries@westend.com>

	* generic/tclEncoding.c (LoadTableEncoding): Changed dangerous
	  code to something less critical. This fixes bug 119417, part A
	  without affecting the speed when loading encodings.

2000-11-24  Donal K. Fellows  <fellowsd@cs.man.ac.uk>

	* generic/tclExecute.c (TclExecuteByteCode): Logical negation "!"
	  can now handle string booleans, provided those values are placed
	  in variables.

	* tests/expr.test (expr-13.17): Check that [expr {!$var}] can
	  negate the string-versions of booleans "yes", "false", etc.

	* library/tcltest/tcltest.tcl (getMatchingFiles,
	  getMatchingDirectories):
	* tools/man2html.tcl (doDir): 
	* tools/man2help.tcl (doDir): 
	* library/package.tcl (tclPkgUnknown,tclMacPkgSearch): 
	* library/safe.tcl (AddSubDirs): [glob] uses -directory instead of
	  unsafe [file join] to fix Bug #123313

	* generic/tclIndexObj.c:
	* generic/tclTestObj.c (TestindexobjCmd): Changed internal
	  representation of index objects to fix Bug #119082; fix
	  shouldn't be visible to outside world...

	* generic/tclTest.c (TestGetIndexFromObjStructObjCmd): 
	* tests/indexObj.test: (indexObj-6.*) Added to test for presence
	  of Bug #119082.

2000-11-23  Donal K. Fellows  <fellowsd@cs.man.ac.uk>

	* generic/tclCmdIL.c (Tcl_LsortObjCmd): Fixed memory leak from Bug
	  #119398

	* library/init.tcl (unknown): Added specific level parameters to
	  all uplevel invokations to boost performance; didn't dare touch
	  the "namespace inscope" stuff though, since it looks sensitive
	  to me!  Should fix Bug #123217, though testing is tricky...

2000-11-16  Andreas Kupries  <a.kupries@westend.com>

	* win/tclWinPort.h (line 69): Changed reference to winsock2.h into
 	  winsock.h. This was a leftover from a foray into using winsock
 	  version 2 (History lesson from Scott Redman and Jeff
 	  Hobbs). This code was no problem when compiling Tcl itself, but
 	  could trip extensions. Fixes bug 122568.

2000-11-02  David Gravereaux  <davygrvy@ajubasolutions.com>

	* generic/tclEvent.c: tclLibraryPath Tcl_Obj didn't have a way
	to share its data among threads.  This caused Tcl_Init() to
	always fail in threads.  Added a way to pass the data around
	with a global char*.  [BUG: 5301]

2000-11-02  Jeff Hobbs  <hobbs@ajubasolutions.com>

	* unix/configure:
	* unix/dltest/configure:
	* win/configure:
	* tools/configure: checked in configure scripts so people doing
	CVS checkouts aren't required to have autoconf.  Changes to
	configure.in in the future will require the corresponding
	configure script to also be re-autoconf'ed and checked in.

	* win/makefile.vc:
	* win/tcl.m4: makefile fixes for Win64 support

	* generic/tclIndexObj.c (Tcl_GetIndexFromObjStruct): minor cast
	changes.

2000-11-01  Jeff Hobbs  <hobbs@ajubasolutions.com>

	* unix/tcl.m4: removed use of -lbsd and -ldl for AIX-5.

	* tests/subst.test: added tests for non-zero return code handling
	by subst.
	* generic/tclParse.c (Tcl_EvalEx): corrected handling of non-zero,
	non-error return code cases for subst. [BUG: 119829]

	* generic/tclVar.c (TclVarTraceExists): Corrected excessive mem
	use when info exists was called on a non-existent array element.
	[BUG: 119213, 119336]

2000-10-30  David Gravereaux  <davygrvy@ajubasolutions.com>

	* win/configure.in:
	* win/Makefile.in:
	* win/makefile.vc:
	* win/tcl.rc:
	* win/tclsh.rc: Added logic to derive filenames better in the resource
	scripts based on compile options.

2000-10-30  Jeff Hobbs  <hobbs@ajubasolutions.com>

	* unix/tclUnixInit.c: added default encoding map from
	"ja_JP.eucJP" to "euc-jp". (takahashi)

	* tests/clock.test: corrected clock-2.* test numbering

	* unix/configure.in (SC_TCL_LINK_LIBS): removed code that was
	commented out (it had been moved to tcl.m4's SC_TCL_LINK_LIBS
	already).

	* unix/tcl.m4: consolidated gettimeofday check for AIX.

2000-10-27  Jeff Hobbs  <hobbs@ajubasolutions.com>

	* unix/configure.in:
	* unix/tcl.m4: added support for AIX-5.

	* generic/tclIO.c (Tcl_NotifyChannel): removed #ifdef around code
	for old channel structures, placed preserve/release around statePtr
	* generic/tclIO.c (CloseChannel): the statePtr for a channel was
	not being freed when the last channel in a stack was freed,
	causing a mem leak.

	* unix/tclUnixChan.c: updated channel types to strict
	TCL_CHANNEL_VERSION_2 style to avoid compiler warnings.  They work
	either way, but this avoids compiler warnings (that worries people).

2000-10-26  David Gravereaux <davygrvy@ajubasolutions.com>

	* win/tclWinFile.c (TclpMatchFilesTypes): NULL was being set to
	"attr" which was a DWORD.  Changed NULL to zero because a 'void *'
	can't be set to a DWORD to avoid the compiler warning.

2000-10-20  Jeff Hobbs  <hobbs@ajubasolutions.com>

	* win/tclWinFile.c (TclpMatchFilesTypes): made the stat call only
	occur when necessary (for 'glob' command).  Significantly speeds
	up glob command from 8.3. [BUG: 6216]

2000-10-06  David Gravereaux  <davygrvy@ajubasolutions.com>

	* win/tclWinChan.c: moved Win2K bug case test with GetStdHandle()
	from TclpGetDefaultStdChannel into Tcl_MakeFileChannel to enable
	a more general method in detecting invalid OS handles rather than
	just a specific known case. [BUG: 5971]

2000-10-06  Jeff Hobbs  <hobbs@ajubasolutions.com>

	* tests/cmdAH.test: extra tests for 'file channels' that include
	multiple interpreter tests and channel sharing
	* generic/tclIO.c (Tcl_GetChannelNamesEx): corrected function (and
	consequently 'file channels') to return channels that are actually
	registered for this specific interp, rather than this thread.

2000-09-29  Jeff Hobbs  <hobbs@scriptics.com>

	* win/tclWinSerial.c (SerialGetOptionProc): corrected reporting of
	space parity on Windows (Eason) [Bug 6057].

	* win/Makefile.in: commented use of TESTFLAGS
	* unix/Makefile.in: added TESTFLAGS to test target to
	conform with Windows makefile and TEA style.

	* tests/stack.test: prevented possible crash on systems with low
	default stacksize (Tru64, AIX) in infinite recursion test.  A
	solution to check remaining stack space in the core is best, but
	hard to do in a cross-platform manner.

	* generic/tclIOGT.c (FLUSH_DELAY): renamed DELAY define to
	FLUSH_DELAY to avoid defn conflict using Tru64's cc.

2000-09-28  Jeff Hobbs  <hobbs@ajubasolutions.com>

	* tools/tcl.wse.in: added tclPlatDecls.h and tkPlatDecls.h to the
	Windows .exe install.

	* tests/fCmd.test (fCmd-6.20): corrected test to remove
	c:/tcl8975@ after creating it.

	* tests/fileName.test: cleaned up the testing of glob patterns for
	c:/globTest (Windows) to directly create/remove directory.
2000-09-27  Jeff Hobbs  <hobbs@ajubasolutions.com>

	* generic/tclIO.c (StopCopy): fixed a bug introduced by a partial
	fix in 8.3.2 that didn't set nonBlocking correctly when resetting
	the flags for the write side.  [Bug: 6261]

	***************************************************************
	**  END OF ASYNC BACKPORT LOG (8.4aCVS 2001-04-03 -> 8.3.3)  **
	***************************************************************

2000-08-08  Jeff Hobbs  <hobbs@ajubasolutions.com>

	8.3.2 RELEASE finalized

	* changes: updated for release notes version of ChangeLog

	* library/msgcat1.0/pkgIndex.tcl: 
	* library/msgcat1.0/msgcat.tcl: bumped msgcat version to 1.1.

2000-08-07  Jeff Hobbs  <hobbs@ajubasolutions.com>

	* doc/ChnlStack.3:
	* doc/CrtChannel.3: updated the docs to be aware of the
	TCL_CHANNEL_VERSION_2 style of Tcl channels.

	* generic/tclIO.c (Tcl_CreateChannel): added assertion to verify
	that the new channel versioning will be binary compatible with
	older channel drivers.

	* BACKPORTED FROM 8.4 (HEAD) BRANCH:

	* doc/memory.n: Man page for Tcl "memory" command, which is
	created when TCL_MEM_DEBUG is defined at compile time.

	* doc/TCL_MEM_DEBUG.3: Man page with overall information about
	TCL_MEM_DEBUG usage.

	* doc/DumpActiveMemory.3: Man page for Tcl_DumpActiveMemory,
	Tcl_InitMemory, and Tcl_ValidateAllMemory [Bug: 1816, 1835].

	* doc/Init.3: Man page for Tcl_Init [Bug: 1820].

	* unix/Makefile.in: add tclsh.ico and tcl.spec to dist target

	* unix/mkLinks: Regen'd with new mkLinks.tcl.

	* unix/mkLinks.tcl: Fixed indentation, made link setup more
	intelligent (only do one existance test per man page, instead of
	one per function).

	* doc/AddErrInfo.3:
	* doc/ChnlStack.3:
	* doc/Exit.3:
	* doc/GetIndex.3:
	* doc/Notifier.3:
	* doc/Object.3:
	* doc/RegExp.3:
	* doc/SetResult.3:
	* doc/SplitList.3:
	* doc/Thread.3:  Added missing entries to NAME section.

	* doc/AddErrInfo.3:
	* doc/CrtObjCmd.3:
	* doc/RecEvalObj.3: Changed Tcl_EvalObj to Tcl_EvalObjEx

	* doc/library.n: Added entries for auto_qualify and auto_import
	[Bug: 1271].
	* doc/library.n: Fixed .SH NAME macro to include each function
	documented on the page, so that mkLinks will know about the
	functions listed there, and so that the Windows help file index
	will get set up correctly [Bug: 1898, 5273].

	* doc/expr.n: Added documentation for each of the math library
	functions that expr supports [Bug: 1054].

	* doc/regsub.n: correct regsub docs [Bug: 5346]

	* doc/scan.n: minor doc fixes [Bug: 5396]

	* doc/RegExp.3: Replaced instances of "Tcl_GetRegExpInfo" with
	"Tcl_RegExpGetInfo", the correct name of the function [Bug: 5901].

	* doc/package.n: Corrected information about [package forget]
	arguments [Bug: 5418].

	* generic/tclCkalloc.c: Fixed some function headers.

	* tests/clock.test: Added test for "2 days 2 hours ago" style
	specifications.

	* generic/tclDate.c: Regenerated from tclGetDate.y.

	* generic/tclGetDate.y: Tweaked grammar to properly handle the
	"ago" keyword when it follows multiple relative unit specifiers,
	as in "2 days 2 hours ago".  [Bug: 5497].

	* generic/tclClock.c (FormatClock): correct code to handle locale
	specific return values from strftime, if any. [Bug: 3345]

	* unix/tclUnixInit.c (TclpSetInitialEncodings): attempt to
	correct setlocale calls for XIM support and locale issues.
	[BUG: 5422 3345 4236 2522 2521]

	* library/init.tcl (auto_import): added check to see if a valid
	pattern was coming in, to avoid simple error cases [Bug: 3326]

	* library/history.tcl: Corrected an off-by-one error in HistIndex,
	which was causing [history redo] to start its search at the wrong
	event index. [Bug: 1269].

	* generic/tclPosixStr.c (Tcl_SignalMsg): clarified #defines for
	Linux on Sparc to compile correctly. [Bug: 5364]

	* generic/tclEnv.c: cast cleanup [Bug: 5624]
	* win/tclWinFCmd.c: cast cleanup [Bug: 5627]

	* generic/tclIndexObj.c (Tcl_GetIndexFromObjStruct): Corrected
	caching of the index ptr to account for offsets != sizeof(char *).
	[Bug: 5153]

	* tests/opt.test:
	* library/opt0.4/optparse.tcl: Applied patch from [Bug: 5922], which 
	corrected an incorrect use of [string match].

	* tests/stringObj.test: Tweaked tests to avoid hardcoded
	high-ASCII characters (which will fail in multibyte locales);
	instead used \uXXXX syntax. [Bug: 3842].

2000-08-05  Jeff Hobbs  <hobbs@scriptics.com>

	* generic/tclIOGT.c (TclChannelTransform): fixed segfault that
	would occur when transforming a channel with a proc that did not
	yet exist. (Kupries)

	* generic/tclTest.c (TestChannelCmd): added some lint init'ing of
	statePtr and chan vars.

2000-07-28  Mo DeJong  <mdejong@redhat.com>

	* win/Makefile.in:
	* win/configure.in:
	* win/tcl.m4:
	* win/tclConfig.sh.in: Back port of gcc for windows
	build system from 8.4.

2000-07-26  Jeff Hobbs  <hobbs@scriptics.com>

	* merged core-8-3-1-io-rewrite back into core-8-3-1-branch.
	The core-8-3-1-io-rewrite branch should now be considered defunct.

	* generic/tclStubInit.c:
	* generic/tclDecls.h:
	* generic/tcl.decls:
	* generic/tcl.h:
	* generic/tclIO.c: moved the Tcl_Channel* macros from tcl.h to
	tclIO.c and made them proper stubbed functions.  These are:
	Tcl_ChannelName, Tcl_ChannelVersion, Tcl_ChannelBlockModeProc,
	Tcl_ChannelCloseProc, Tcl_ChannelClose2Proc, Tcl_ChannelInputProc,
	Tcl_ChannelOutputProc, Tcl_ChannelSeekProc, Tcl_ChannelSetOptionProc,
	Tcl_ChannelGetOptionProc, Tcl_ChannelWatchProc,
	Tcl_ChannelGetHandleProc, Tcl_ChannelFlushProc,
	and Tcl_ChannelHandlerProc.  These should be used to access the
	Tcl_ChannelType structure instead of direct pointer dereferencing.

	* unix/Makefile.in: undid 07-25 Makefile.in changes because we
	don't really want to force all private makefiles on everyone.
	This needs to be addressed again in the future.  Best possible
	solution is to create a tcl/ subdir in the installing include dir
	(as is done already with the lib dir).

	* tests/iogt.test: added RCS string, marked tests 2.* to be
	unixOnly due to underlying system differences.

	* tests/all.tcl: corrected additional sets by Kupries for testing.

2000-07-25 Brent Welch	<welch@ajubasolutions.com>

	* unix/Makefile.in: Need to install all the Tcl headers because
	Itcl depends on internal headers.

2000-07-25 Andreas Kupries <a.kupries@westend.com>

	* tests/iogt.test: (line 866f) New tests iogt-6.[01], highlighting
 	  buffering trouble when stacking and unstacking transformations.
	  iogt-6.0 is solved, see the changes below. iogt-6.1 remains, for
 	  now, due to the perceived complexity of solutions.

	* generic/tclIO.h: (line 139f) struct Channel, added a buffer
	  queue, to hold data pushed back when stacking a transformation.

	* generic/tclIO.c:
	  (line 91f, line 7434f) New internal function 'CopyBuffer'.
	  Derived from 'CopyAndTranslateBuffer', with translation
	  removed.
	  (line 1025f, line 1212f): Initialization of new queue.
	  (line 1164f, Tcl_StackChannel): Pushback of input queue.
	  (line 1293f, Tcl_UnstackChannel): Discard input and pushback.
	  (line 3748f, Tcl_ReadRaw): Modified to use data in the push back
	  area before going to the driver. Uses 'CopyBuffer', s.a.
	  (line 4702f, GetInput): Modified to use data in the push back
	  area before going to the driver.
 	  (line 4867f, Tcl_Seek): Modified to take pushback of the topmost
	  channel in a stack into account.
	  (line 5620f, Tcl_InputBuffered): See above. Added
	  'Tcl_ChannelBuffered'. Analogue to 'Tcl_InputBuffered' but for
	  the buffer area in the channel.

	* generic/tcl.decls: New public API 'Tcl_ChannelBuffered'. S.a.

2000-07-19  Jeff Hobbs  <hobbs@scriptics.com>

	* tests/socket.test: removed doTestsWithRemoteServer constraint
	from socket-12.*.  It requires 'exec', not a remote server.
	Cleaned up some coding errors.

2000-07-18 Brent Welch	<welch@ajubasolutions.com>

	* win/Makefile.in: Added rules for static tcldde and tclreg libraries.

2000-07-17  Jeff Hobbs  <hobbs@scriptics.com>

	* README:
	* win/README:
	* win/README.binary:
	* win/configure.in:
	* unix/configure.in:
	* unix/tcl.spec:
	* tools/tcl.wse.in:
	* generic/tcl.h (TCL_RELEASE_SERIAL): updated to patchlevel 8.3.2

	* unix/Makefile.in:
	* win/Makefile.in:
	* win/makefile.vc: added tclIOGT.c to objects list to compile.

	* generic/tclStubInit.c:
	* generic/tclIntDecls.h:
	* generic/tclInt.decls: commented out internal decls for
	TclTestChannelCmd and TclTestChannelEventCmd as they were moved to
	tclTest.c.  Added new decls for TclChannelEventScriptInvoker and
	TclChannelTransform.

	* generic/tclIO.h: new file that contains the main internal
	structures of Tcl_Channel code to allow for multiple files to
	access them.
	* generic/tclTest.c:
	* generic/tclIO.c: broke into 3 files - tclIO.c core code, tclIO.h
	header code, and tclIOGT.c - the giot test code from Kupries.  The
	channel test code also moved to tclTest.c.
	* generic/tclIO.c (CloseChannel): stopped masking out of the
	TCL_READABLE|TCL_WRITABLE bits from the state flags in
	CloseChannel, instead adding extra intelligence to
	CheckChannelErrors with a new CHANNEL_RAW_MODE bit for special
	behavior when called from Raw channel APIs.

2000-07-13  Jeff Hobbs  <hobbs@scriptics.com>

	* generic/tclIO.c (StackSetBlockMode): moved set of chanPtr
	outside of blockModeProc check to avoid infinite loop when
	blockModeProc was NULL (Kupries).  updated TransformSeekProc to
	not call Tcl_Seek directly (Kupries).

	* win/tclWinChan.c: updated fileChannelType to v2 channel struct
	* win/tclWinConsole.c: updated consoleChannelType to v2 channel struct
	* win/tclWinPipe.c: updated pipeChannelType to v2 channel struct
	* win/tclWinSerial.c: updated serialChannelType to v2 channel struct
	* win/tclWinSock.c: updated tcpChannelType to v2 channel struct

2000-07-11  Brent Welch	<welch@ajubasolutions.com>

	* win/tclConfig.sh.in: Cleaned up unix-specific autoconf variables.

2000-07-11  Jeff Hobbs  <hobbs@scriptics.com>

	* tests/iogt.test: made tests [345].0 not run by default as they
	were failing in the new design, but I'm not convinced that the
	returned result isn't correct.

	* generic/tclDecls.h:
	* generic/tclStubInit.c:
	* generic/tcl.decls: added Tcl_GetTopChannel C API that returns
	the current top channel of a channel stack.  Tcl_GetChannel was
	changed earlier to return the bottommost channel of a stack
	because that is the one that is guaranteed to stay around the
	longest, and this was needed to compensate for certain
	operations that want to look at the state of the main channel.
	Most channel APIs already compensate for grabbing the top, so it
	shouldn't be needed often.

	* generic/tclIO.c (Tcl_StackChannel, Tcl_UnstackChannel): Added
	flushing of buffers (Kupries), removed use of DownChannel macro,
	added Tcl_GetTopChannel public API to get to the top channel of
	the channel stack (necessary for TLS).  Rewrote Tcl_NotifyChannel
	for new channel design (Kupries).  Did some code cleanup in the
	transform code.  tclIO.c must still be broken into bits (separate
	out test code and giot code, create tclIO.h).

2000-07-10  Andreas Kupries <a.kupries@westend.com>

	* tests/iogt.test: Reverted some earlier changes as a fix by Jeff
	  revived the original and correct behaviour. IOW, the tests showed
	  a genuine error and I didn't see it :(.

	* generic/tclIO.c (Tcl_Read|Write_Raw): Changed to directly use
 	  the drivers and not DoRead|DoWrite. The latter use the buffering
 	  system, encoding and eol-translation and this wreaks havoc with
 	  the data going through the transformations. Both procedures use
 	  CheckForchannelErrors and let it believe that there is no
 	  background copy in progress or else stacked channels could not
	  be used for that.

	* generic/tclIO.c (TclCopyChannel, CopyData): Moved access to the
 	  topmost channel from the first to the second procedure to make
 	  the decision about that at the last possible time (Callbacks can
 	  change the stacking).

	test suite: failures of iogt-[345].0
	
2000-07-06  Jeff Hobbs  <hobbs@scriptics.com>

	* tests/iogt.test: new tests for stacked channel stuff based off
	new 'testchannel transform|unstack' code (Kupries IOGT extension).
	* generic/tcl.decls:
	* generic/tcl.h:
	* generic/tclDecls.h:
	* generic/tclStubsInit.c:
	* generic/tclIO.c: complete rewrite of Tcl Channel code for
	stacked channels.  Channels are now designed to work in a more
	stacked fashion with a shared ChannelState data structure.

2000-06-02  Jeff Hobbs  <hobbs@scriptics.com>

	* generic/tclIO.c (CloseChannel): removed the &ing out of
	(TCL_READABLE|TCL_WRITABLE) from the flags, as CloseChannel does
	this on the next pass through for the top channel, and it appeared
	to be causing hangs by not allowing the final flush.

2000-06-01  Jeff Hobbs  <hobbs@scriptics.com>

	* generic/tclIO.c (CloseChannel): Rewrote CloseChannel code to
	unstack a channel during the close process.  Fixed a refcount bug
	in Tcl_UnstackChannel.  [Bug: 5623]
	(CloseChannel): further extended CloseChannel in the stacked case
	to effect certain operations on the next channel that would have
	been done in Tcl_Close.  Also added CHANNEL_CLOSED and removed
	(TCL_READABLE|TCL_WRITABLE) bits from chanPtr->flags.  Changed
	final reset of the WatchProc to check the chanDownPtr's (next)
	interestMask.

2000-05-29  Sandeep Tamhankar <sandeep@scriptics.com>

	* tests/http.test
	* doc/http.n
	* library/http2.3/http.tcl: Fixed bug 5741, where unsuccessful
	geturl calls sometimes leaked memory and resources (sockets).  
	Also, switched around some of the logic so that http::wait never 
	throws an exception.  This is because in an asynchronous geturl, 
	the command callback will probably end up doing all the error 
	handling anyway, and in an asynchronous situation, the user
	expects to check the state when the transaction completes, as
	opposed to being thrown an exception.	For the http package, this
	menas the user can check http::status for "error" and http::error
	for the error message after doing the http::wait.

2000-04-26  Jeff Hobbs  <hobbs@scriptics.com>

	8.3.1 RELEASE

	* README:
	* mac/README:

README:  Tcl
    This is the Tcl 8.3.3 source distribution.
    You can get any release of Tcl from:
        ftp://ftp.scriptics.com/pub/tcl/
    Tcl/Tk is also available through NetCVS:
	http://tcl.sourceforge.net/

RCS: @(#) $Id: README,v 1.31.2.2 2001/04/03 22:08:32 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.

Tcl is maintained, enhanced, and distributed freely by the Tcl community.
The home for Tcl/Tk sources and bug/patch database is on SourceForge:

	http://tcl.sourceforge.net/

with the Tcl Developer Xchange hosted at:

	http://dev.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
----------------

Extensive documentation is available at our website.
The home page for this release, including new features, is
	http://dev.scriptics.com/software/tcltk/8.3.html

Detailed release notes can be found at
	http://dev.scriptics.com/software/tcltk/relnotes/tcl8.3.3.txt

Information about Tcl itself can be found at
	http://dev.scriptics.com/scripting/

There are many Tcl books on the market.  Most are listed at
	http://dev.scriptics.com/resource/doc/books/

commands.  The file "doc/Tcl.n" gives a quick summary of the Tcl
language syntax.  To print any of the man pages on Unix, cd to the
"doc" directory and invoke your favorite variant of troff using the
normal -man macros, for example

		ditroff -man Tcl.n

to print Tcl.n.  If Tcl has been installed correctly and your "man" program
supports it, you should be able to access the Tcl manual entries using the
normal "man" mechanisms, such as

		man Tcl

2b. Windows Documentation
-------------------------

The "doc" subdirectory in this release contains a complete set of Windows
help files for Tcl.  Once you install this Tcl release, a shortcut to the
Windows help Tcl documentation will appear in the "Start" menu:


	Start | Programs | Tcl | Tcl Help

3. Compiling and installing Tcl
-------------------------------

There are brief notes in the unix/README, win/README, and mac/README about
compiling on these different platforms.  There is additional information
about building Tcl from sources at


	http://dev.scriptics.com/doc/howto/compile.html

4. TclPro Development tools
--------------------

A high quality set of commercial quality development tools is available to
accelerate your Tcl application development.  The TclPro product provides a
debugger, static code checker, packaging utility, and bytecode compiler.
TclPro was open-sourced when Scriptics/Ajuba was acquired by Interwoven.
Visit its home at SourceForge for more information and source/binaries:



	http://tclpro.sourceforge.net/

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

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

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

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



Several mailing lists are hosted at SourceForge to discuss development or


use issues (like Macintosh and Windows topics).  For more information and
to subscribe, visit:


	http://sourceforge.net/projects/tcl/






and go to the Mailing Lists page.


9. Support and Training
------------------------

We are very interested in receiving bug reports, patches, and suggestions
for improvements.  We prefer that you send this information to us via the

bug form at SourceForge, rather than emailing us directly.  The bug
database is at:

	http://tcl.sourceforge.net/

The bug form was designed to give uniform structure to bug reports as
well as to solicit enough information to minimize followup questions.





We will log and follow-up on each bug, although we cannot promise a
specific turn-around time.  Enhancements may take longer and may not happen
at all unless there is widespread support for them (we're trying to slow
the rate at which Tcl/Tk turns into a kitchen sink).  It's very difficult
to make incompatible changes to Tcl/Tk at this point, due to the size of
the installed base.

The Tcl community is too large for us to provide much individual support
for users.  If you need help we suggest that you post questions to
comp.lang.tcl.  We read the newsgroup and will attempt to answer esoteric
questions for which no-one else is likely to know the answer.  In addition,





see the following Web site for links to other organizations that offer
Tcl/Tk training:

	http://www.scriptics.com/resource/community/commercial/training

10. Thank You
-------------

We'd like to express our thanks to the Tcl community for all the
helpful suggestions, bug reports, and patches we have received.
Tcl/Tk has improved vastly and will continue to do so with your help.

Recent user-visible changes to Tcl:

RCS: @(#) $Id: changes,v 1.56.2.3 2001/04/04 23:05:06 hobbs Exp $

1. No more [command1] [command2] construct for grouping multiple
commands on a single command line.

2. Semi-colon now available for grouping commands on a line.

3. For a command to span multiple lines, must now use backslash-return

2000-04-23 (bug fix) several Mac socket fixes (ingham)

2000-04-24 (bug fix) fixed hang in threaded Unix case when backgrounded
exec process was running (dejong)

--- Released 8.3.1, April 26, 2000 --- See ChangeLog for details ---

2000-05-29 (bug fix) corrected resource cleanup in http error cases.
Improved handling of error cases in http. (tamhankar)

2000-07 (feature rewrite) complete rewrite of the Tcl IO channel subsystem
to correct problems (hangs, core dumps) with the initial stacked channel
implementation.  The new system has many more tests for robustness and
scalability.  There are new C APIs (see Tcl_CreateChannel), but only
stacked channel drivers are affected (ie: TLS, Trf, iogt).  The iogt
extension has been added to the core test code to test the system.
(hobbs, kupries)
	**** POTENTIAL INCOMPATABILITY ****

2000-07 (build improvements) cleanup of the makefiles and configure scripts
to correct support for building under gcc for Windows. (dejong)

2000-08-07 (bug fix) corrected sizeof error in Tcl_GetIndexFromObjStruct.
(perkins)

2000-08-07 (bug fix) correct off-by-one error in HistIndex, which was
causing [history redo] to start its search at the wrong event index. (melski)

2000-08-07 (bug fix) corrected setlocale calls for XIM support and locale
issues in startup. (takahashi)

2000-08-07 (bug fix) correct code to handle locale specific return values
from strftime, if any. (wagner)

2000-08-07 (bug fix) tweaked grammar to properly handle the "ago" keyword
when it follows multiple relative unit specifiers, as in
"2 days 2 hours ago". (melski)

2000-08-07 (doc fixes) numerous doc fixes to correct SEE ALSO and NAME
sections. (english)

2000-08-07 (bug fix) new man pages memory.n, TCL_MEM_DEBUG.3, Init.3 and
DumpActiveMemory.3. (melski)

--- Released 8.3.2, August 9, 2000 --- See ChangeLog for details ---

2001-04-04 (build improvements) redid Mac build structure (steffen)
Corrected IRIX-5* configure (english).  Added support for AIX-5 (hobbs).
Added support for Win64 (hobbs).

2001-04-03 (doc fixes) numerous doc corrections and clarifications.
Update of READMEs.

2001-03-30 (bug fix) corrected Windows memory error on exit (wu)
Fixed race condition in	readability of socket on Windows.

2001-03-29 (bug fix) prevent potential race condition and security leak in
tmp filename creation on Unix. (max)
Fixed handling of timeout for threads (corrects excessive CPU usage issue
for Tk on Unix in threaded Tcl environment). (ruppert)

2001-03-13 (bug fix) Correctly possible memory corruption in string map {}
$str (fellows)

2001-02-15 (feature enhancement) improved efficiency of [string split]
(fellows)

2001-01-30 (bug fix) Fixed possible hangs in fcopy. (porter)

2001-01-04 (bug fix) corrected parsing of $tcl_libPath at startup on
Windows (porter)

2000-12-14 (feature enhancement) improved (s)rand for 64-bit platforms
(porter)

2000-12-09 (feature enhancement) changed %o and %x to use strtoul instead
of strtol to correctly preserve scan<>format conversion of large integers
(hobbs)
Fixed handling of {!<boolean>} in expressions (hobbs, fellows)

2000-11-23 (mem leak) fixed potential memory leak in error case of lsort
(fellows)

2000-11-02 (bug fix) Corrected sharing of tclLibraryPath in threaded
environment (gravereaux)

2000-11-01 (mem leak) Corrected excessive mem use of info exists on a
non-existent array element (hobbs)

2000-10-20 (feature enhancement) call stat only when necessary in 'glob' to
speed up command significantly in base cases (hobbs)

2000-10-06 (bug fix) corrected [file channels] to only return channels in
the current interpreter (hobbs)

2000-09-29 (bug fix) corrected reporting of space parity on Windows (Eason)

2000-09-27 (bug fix) fixed a bug introduced by a partial fix in 8.3.2 that
didn't set nonBlocking correctly when resetting the flags for the write
side (mem leak) Correct mem leak in channels when statePtr was released
(hobbs)

--- Released 8.3.3, April 6, 2001 --- See ChangeLog for details ---

/*
 * string.h --
 *
 *	Declarations of ANSI C library procedures for string handling.
 *
 * Copyright (c) 1991-1993 The Regents of the University of California.
 * Copyright (c) 1994-1996 Sun Microsystems, Inc.
 *
 * See the file "license.terms" for information on usage and redistribution
 * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 *
 * RCS: @(#) $Id: string.h,v 1.3.12.1 2001/04/03 22:54:36 hobbs Exp $
 */

#ifndef _STRING
#define _STRING

#include <tcl.h>

			    CONST char *s2, size_t n));
extern char *		strncat _ANSI_ARGS_((char *dst, CONST char *src,
			    size_t numChars));
extern int		strncmp _ANSI_ARGS_((CONST char *s1, CONST char *s2,
			    size_t nChars));
extern char *		strncpy _ANSI_ARGS_((char *dst, CONST char *src,
			    size_t numChars));
extern char *		strpbrk _ANSI_ARGS_((CONST char *string,
			    CONST char *chars));
extern char *		strrchr _ANSI_ARGS_((CONST char *string, int c));
extern size_t		strspn _ANSI_ARGS_((CONST char *string,
			    CONST char *chars));
extern char *		strstr _ANSI_ARGS_((CONST char *string,
			    CONST char *substring));
extern char *		strtok _ANSI_ARGS_((char *s, CONST char *delim));

#endif /* _STRING */

'\"
'\" Copyright (c) 1989-1993 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: AddErrInfo.3,v 1.4.2.1 2000/08/07 21:29:36 hobbs Exp $
'\" 
.so man.macros
.TH Tcl_AddErrorInfo 3 8.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_AddObjErrorInfo, Tcl_AddErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_PosixError, Tcl_LogCommandInfo \- record information about errors
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
\fBTcl_AddObjErrorInfo\fR(\fIinterp, message, length\fR)
.sp
\fBTcl_AddErrorInfo\fR(\fIinterp, message\fR)

and additional elements in \fBerrorCode\fR hold additional pieces
of information that depend on the class.
See the Tcl overview manual entry for details on the various
formats for \fBerrorCode\fR.
.PP
The \fBerrorInfo\fR variable is gradually built up as an
error unwinds through the nested operations.
Each time an error code is returned to \fBTcl_EvalObjEx\fR
(or \fBTcl_Eval\fR, which calls \fBTcl_EvalObjEx\fR)
it calls the procedure \fBTcl_AddObjErrorInfo\fR to add
additional text to \fBerrorInfo\fR describing the
command that was being executed when the error occurred.
By the time the error has been passed all the way back
to the application, it will contain a complete trace
of the activity in progress when the error occurred.
.PP
It is sometimes useful to add additional information to
\fBerrorInfo\fR beyond what can be supplied automatically
by \fBTcl_EvalObjEx\fR.
\fBTcl_AddObjErrorInfo\fR may be used for this purpose:
its \fImessage\fR and \fIlength\fR arguments describe an additional
string to be appended to \fBerrorInfo\fR.
For example, the \fBsource\fR command calls \fBTcl_AddObjErrorInfo\fR
to record the name of the file being processed and the
line number on which the error occurred;
for Tcl procedures, the procedure name and line number
within the procedure are recorded, and so on.
The best time to call \fBTcl_AddObjErrorInfo\fR is just after
\fBTcl_EvalObjEx\fR has returned \fBTCL_ERROR\fR.
In calling \fBTcl_AddObjErrorInfo\fR, you may find it useful to
use the \fBerrorLine\fR field of the interpreter (see the
\fBTcl_Interp\fR manual entry for details).
.PP
\fBTcl_AddErrorInfo\fR resembles \fBTcl_AddObjErrorInfo\fR
but differs in initializing \fBerrorInfo\fR from the string
value of the interpreter's result

'\"
'\" Copyright (c) 1999-2000 Ajuba Solutions.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" RCS: @(#) $Id: ChnlStack.3,v 1.1.10.2 2000/08/08 00:57:52 hobbs Exp $
.so man.macros
.TH Tcl_StackChannel 3 8.3 Tcl "Tcl Library Procedures"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
Tcl_StackChannel, Tcl_UnstackChannel, Tcl_GetStackedChannel \- 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
int
\fBTcl_UnstackChannel\fR(\fIinterp, channel\fR)
.sp
Tcl_Channel
\fBTcl_GetStackedChannel\fR(\fIchannel\fR)
.sp
.SH ARGUMENTS
.AS Tcl_ChannelType

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
The implementation of the Tcl channel code was rewritten in 8.3.2 to
correct some problems with the previous implementation with regard to
stacked channels.  Anyone using stacked channels or creating stacked
channel drivers should update to the new \fBTCL_CHANNEL_VERSION_2\fR
\fBTcl_ChannelType\fR structure.  See \fBTcl_CreateChannel\fR for details.
.PP
\fBTcl_StackChannel\fR stacks a new \fIchannel\fP on an existing channel













with the same name that was registered for \fIchannel\fP by
\fBTcl_RegisterChannel\fP.
.PP
\fBTcl_StackChannel\fR works by creating a new channel structure and

placing itself on top of the channel stack.  EOL translation, encoding and
buffering options are shared between all channels in the stack.  The hidden
channel does no buffering, newline translations, or character set encoding.
Instead, the buffering, newline translations, and encoding functions all
remain at the top of the channel stack.  A pointer to the new top channel


structure is returned.  If an error occurs when stacking the channel, NULL
is returned instead.
.PP
The \fImask\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.  If an error
occurs unstacking the channel, \fBTCL_ERROR\fR is returned, otherwise
\fBTCL_OK\fR is returned.

.SH "SEE ALSO"
Notifier(3), Tcl_CreateChannel(3), Tcl_OpenFileChannel(3), vwait(n).

.SH KEYWORDS
channel, compression

'\"
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
'\" Copyright (c) 1997-2000 Ajuba Solutions.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" RCS: @(#) $Id: CrtChannel.3,v 1.5.2.2 2001/04/03 22:06:43 hobbs Exp $
.so man.macros
.TH Tcl_CreateChannel 3 8.3 Tcl "Tcl Library Procedures"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType, Tcl_GetChannelName, Tcl_GetChannelHandle, Tcl_GetChannelMode, Tcl_GetChannelBufferSize, Tcl_SetChannelBufferSize, Tcl_NotifyChannel, Tcl_BadChannelOption, Tcl_ChannelName, Tcl_ChannelVersion, Tcl_ChannelBlockModeProc, Tcl_ChannelCloseProc, Tcl_ChannelClose2Proc, Tcl_ChannelInputProc, Tcl_ChannelOutputProc, Tcl_ChannelSeekProc, Tcl_ChannelSetOptionProc, Tcl_ChannelGetOptionProc, Tcl_ChannelWatchProc, Tcl_ChannelGetHandleProc, Tcl_ChannelFlushProc, Tcl_ChannelHandlerProc, \- procedures for creating and manipulating channels
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
Tcl_Channel
\fBTcl_CreateChannel\fR(\fItypePtr, channelName, instanceData, mask\fR)
.sp
ClientData
\fBTcl_GetChannelInstanceData\fR(\fIchannel\fR)
.sp
Tcl_ChannelType *
\fBTcl_GetChannelType\fR(\fIchannel\fR)
.sp
char *
\fBTcl_GetChannelName\fR(\fIchannel\fR)

.sp
int
\fBTcl_GetChannelHandle\fR(\fIchannel, direction, handlePtr\fR)

.sp
int
\fBTcl_GetChannelBufferSize\fR(\fIchannel\fR)
.sp
\fBTcl_SetChannelBufferSize\fR(\fIchannel, size\fR)
.sp

\fBTcl_NotifyChannel\fR(\fIchannel, mask\fR)
.sp
int
\fBTcl_BadChannelOption\fR(\fIinterp, optionName, optionList\fR)
.VS 8.3.2
.sp
char *
\fBTcl_ChannelName\fR(\fItypePtr\fR)
.sp
Tcl_ChannelTypeVersion
\fBTcl_ChannelVersion\fR(\fItypePtr\fR)
.sp
Tcl_DriverBlockModeProc *
\fBTcl_ChannelBlockModeProc\fR(\fItypePtr\fR)
.sp
Tcl_DriverCloseProc *
\fBTcl_ChannelCloseProc\fR(\fItypePtr\fR)
.sp
Tcl_DriverClose2Proc *
\fBTcl_ChannelClose2Proc\fR(\fItypePtr\fR)
.sp
Tcl_DriverInputProc *
\fBTcl_ChannelInputProc\fR(\fItypePtr\fR)
.sp
Tcl_DriverOutputProc *
\fBTcl_ChannelOutputProc\fR(\fItypePtr\fR)
.sp
Tcl_DriverSeekProc *
\fBTcl_ChannelSeekProc\fR(\fItypePtr\fR)
.sp
Tcl_DriverSetOptionProc *
\fBTcl_ChannelSetOptionProc\fR(\fItypePtr\fR)
.sp
Tcl_DriverGetOptionProc *
\fBTcl_ChannelGetOptionProc\fR(\fItypePtr\fR)
.sp
Tcl_DriverWatchProc *
\fBTcl_ChannelWatchProc\fR(\fItypePtr\fR)
.sp
Tcl_DriverGetHandleProc *
\fBTcl_ChannelGetHandleProc\fR(\fItypePtr\fR)
.sp
Tcl_DriverFlushProc *
\fBTcl_ChannelFlushProc\fR(\fItypePtr\fR)
.sp
Tcl_DriverHandlerProc *
\fBTcl_ChannelHandlerProc\fR(\fItypePtr\fR)
.VE
.sp
.SH ARGUMENTS
.AS Tcl_EolTranslation *channelName in
.AP Tcl_ChannelType *typePtr in
Points to a structure containing the addresses of procedures that
can be called to perform I/O and other functions on the channel.
.AP char *channelName in
The name of this channel, such as \fBfile3\fR; must not be in use
by any other channel. Can be NULL, in which case the channel is
created without a name.
.AP ClientData instanceData in
Arbitrary one-word value to be associated with this channel.  This
value is passed to procedures in \fItypePtr\fR when they are invoked.
.AP int mask in
OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR to indicate
whether a channel is readable and writable.
.AP Tcl_Channel channel in
The channel to operate on.

.AP int direction in
\fBTCL_READABLE\fR means the input handle is wanted; \fBTCL_WRITABLE\fR
means the output handle is wanted.
.AP ClientData *handlePtr out
Points to the location where the desired OS-specific handle should be
stored.

.AP Tcl_EolTranslation transMode in
The translation mode; one of the constants \fBTCL_TRANSLATE_AUTO\fR,
\fBTCL_TRANSLATE_CR\fR, \fBTCL_TRANSLATE_LF\fR and \fBTCL_TRANSLATE_CRLF\fR.
.AP int size in
The size, in bytes, of buffers to allocate in this channel.

.AP int mask in
An OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR
and \fBTCL_EXCEPTION\fR that indicates events that have occurred on
this channel.
.AP Tcl_Interp *interp in
Current interpreter. (can be NULL)
.AP char *optionName in
Name of the invalid option.
.AP char *optionList in
Specific options list (space separated words, without "-") 
to append to the standard generic options list.
Can be NULL for generic options error message only.


.BE

.SH DESCRIPTION
.PP
Tcl uses a two-layered channel architecture. It provides a generic upper
layer to enable C and Tcl programs to perform input and output using the

the same as the \fItypePtr\fR argument in the call to
\fBTcl_CreateChannel\fR that created this channel.
.PP
\fBTcl_GetChannelName\fR returns a string containing the name associated
with the channel, or NULL if the \fIchannelName\fR argument to
\fBTcl_CreateChannel\fR was NULL.
.PP

\fBTcl_GetChannelHandle\fR places the OS-specific device handle
associated with \fIchannel\fR for the given \fIdirection\fR in the
location specified by \fIhandlePtr\fR and returns \fBTCL_OK\fR.  If
the channel does not have a device handle for the specified direction,
then \fBTCL_ERROR\fR is returned instead.  Different channel drivers
will return different types of handle.  Refer to the manual entries
for each driver to determine what type of handle is returned.

.PP
\fBTcl_GetChannelMode\fR returns an OR-ed combination of \fBTCL_READABLE\fR
and \fBTCL_WRITABLE\fR, indicating whether the channel is open for input
and output.
.PP
 \fBTcl_GetChannelBufferSize\fR returns the size, in bytes, of buffers
allocated to store input or output in \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.
.PP
\fBTcl_SetChannelBufferSize\fR sets the size, in bytes, of buffers that
will be allocated in subsequent operations on the channel to store input or
output. The \fIsize\fR argument should be between ten and one million,
allowing buffers of ten bytes to one million bytes. If \fIsize\fR is
outside this range, \fBTcl_SetChannelBufferSize\fR sets the buffer size to
4096.
.PP

\fBTcl_NotifyChannel\fR is called by a channel driver to indicate to
the generic layer that the events specified by \fImask\fR have
occurred on the channel.  Channel drivers are responsible for invoking
this function whenever the channel handlers need to be called for the
channel.  See \fBWATCHPROC\fR below for more details.

.PP

\fBTcl_BadChannelOption\fR is called from driver specific set or get option
procs to generate a complete error message.


.SH TCL_CHANNELTYPE
.PP
A channel driver provides a \fBTcl_ChannelType\fR structure that contains
pointers to functions that implement the various operations on a channel;
these operations are invoked as needed by the generic layer.  The structure
was versioned starting in Tcl 8.3.2/8.4 to correct a problem with stacked
channel drivers.  See the \fBOLD_CHANNEL\fR section below for details about
the old structure.
.PP

The \fBTcl_ChannelType\fR structure contains the following fields:
.CS
typedef struct Tcl_ChannelType {
	char *\fItypeName\fR;
	Tcl_ChannelTypeVersion \fIversion\fR;
	Tcl_DriverCloseProc *\fIcloseProc\fR;
	Tcl_DriverInputProc *\fIinputProc\fR;
	Tcl_DriverOutputProc *\fIoutputProc\fR;
	Tcl_DriverSeekProc *\fIseekProc\fR;
	Tcl_DriverSetOptionProc *\fIsetOptionProc\fR;
	Tcl_DriverGetOptionProc *\fIgetOptionProc\fR;
	Tcl_DriverWatchProc *\fIwatchProc\fR;
	Tcl_DriverGetHandleProc *\fIgetHandleProc\fR;
	Tcl_DriverClose2Proc *\fIclose2Proc\fR;
	Tcl_DriverBlockModeProc *\fIblockModeProc\fR;	
	Tcl_DriverFlushProc *\fIflushProc\fR;	
	Tcl_DriverHandlerProc *\fIhandlerProc\fR;	
} Tcl_ChannelType;
.CE

.PP
The driver must provide implementations for all functions except
\fIblockModeProc\fR, \fIseekProc\fR, \fIsetOptionProc\fR,

\fIgetOptionProc\fR, and \fIclose2Proc\fR, which may be specified as

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, except in the case of \fIflushProc\fR and
\fIhandlerProc\fR, which should specified as NULL if not otherwise defined.
.PP
.VS 8.3.2
The user should only use the above structure for \fBTcl_ChannelType\fR
instantiation.  When referencing fields in a \fBTcl_ChannelType\fR
structure, the following functions should be used to obtain the values:
\fBTcl_ChannelName\fR, \fBTcl_ChannelVersion\fR,
\fBTcl_ChannelBlockModeProc\fR, \fBTcl_ChannelCloseProc\fR,
\fBTcl_ChannelClose2Proc\fR, \fBTcl_ChannelInputProc\fR,
\fBTcl_ChannelOutputProc\fR, \fBTcl_ChannelSeekProc\fR,
\fBTcl_ChannelSetOptionProc\fR, \fBTcl_ChannelGetOptionProc\fR,
\fBTcl_ChannelWatchProc\fR, \fBTcl_ChannelGetHandleProc\fR,
\fBTcl_ChannelFlushProc\fR, or \fBTcl_ChannelHandlerProc\fR.
.PP
The change to the structures was made in such a way that standard channel
types are binary compatible.  However, channel types that use stacked
channels (ie: TLS, Trf) have new versions to correspond to the above change
since the previous code for stacked channels had problems.
.VE

.SH TYPENAME
.PP
The \fItypeName\fR field contains a null-terminated string that
identifies the type of the device implemented by this driver, e.g.
\fBfile\fR or \fBsocket\fR.
.PP
.VS 8.3.2
This value can be retrieved with \fBTcl_ChannelName\fR, which returns
a pointer to the string.
.VE

.VS 8.3.2
.SH VERSION
.PP
The \fIversion\fR field should be set to \fBTCL_CHANNEL_VERSION_2\fR.
If it is not set to this value \fBTCL_CHANNEL_VERSION_2\fR, then this
\fBTcl_ChannelType\fR is assumed to have the older structure.  See
\fBOLD_CHANNEL\fR for more details.  While Tcl will recognize and
function with either structure, stacked channels must be of the newer
style to function correctly.
.PP
This value can be retrieved with \fBTcl_ChannelVersion\fR, which returns
either \fBTCL_CHANNEL_VERSION_2\fR or \fBTCL_CHANNEL_VERSION_1\fR.
.VE

.SH BLOCKMODEPROC
.PP
The \fIblockModeProc\fR field contains the address of a function called by
the generic layer to set blocking and nonblocking mode on the device.
\fIBlockModeProc\fR should match the following prototype:
.PP

.PP
If the operation is successful, the function can modify the supplied
\fIinstanceData\fR to record that the channel entered blocking or
nonblocking mode and to implement the blocking or nonblocking behavior.
For some device types, the blocking and nonblocking behavior can be
implemented by the underlying operating system; for other device types, the
behavior must be emulated in the channel driver.
.PP
.VS 8.3.2
This value can be retrieved with \fBTcl_ChannelBlockModeProc\fR, which returns
a pointer to the function.
.VE

.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
closed. \fICloseProc\fR must match the following prototype:
.PP

output will have been flushed to the device before this function is called,
and no further driver operations will be invoked on this instance after
calling the \fIcloseProc\fR. If the close operation is successful, the
procedure should return zero; otherwise it should return a nonzero POSIX
error code. In addition, if an error occurs and \fIinterp\fR is not NULL,
the procedure should store an error message in the interpreter's result.
.PP

Alternatively, channels that support closing the read and write sides
independently may set \fIcloseProc\fR to \fBTCL_CLOSE2PROC\fR and set
\fIclose2Proc\fR to the address of a function that matches the
following prototype:
.PP
.CS
typedef int Tcl_DriverClose2Proc(

described above for \fIcloseProc\fR.  No further operations will be
invoked on this instance after \fIclose2Proc\fR is called with all
flags cleared.  In all cases, the \fIclose2Proc\fR function should
return zero if the close operation was successful; otherwise it should
return a nonzero POSIX error code. In addition, if an error occurs and
\fIinterp\fR is not NULL, the procedure should store an error message
in the interpreter's result.
.PP
.VS 8.3.2
These value can be retrieved with \fBTcl_ChannelCloseProc\fR or
\fBTcl_ChannelClose2Proc\fR, which returns a pointer to the respective
function.
.VE

.SH INPUTPROC
.PP
The \fIinputProc\fR field contains the address of a function called by the
generic layer to read data from the file or device and store it in an
internal buffer. \fIInputProc\fR must match the following prototype:

return without blocking. If the input device has no data available
whatsoever and the channel is in nonblocking mode, the function should
return an \fBEAGAIN\fR error. If the input device has no data available
whatsoever and the channel is in blocking mode, the function should block
for the shortest possible time until at least one byte of data can be read
from the device; then, it should return as much data as it can read without
blocking.
.PP
.VS 8.3.2
This value can be retrieved with \fBTcl_ChannelInputProc\fR, which returns
a pointer to the function.
.VE

.SH OUTPUTPROC
.PP
The \fIoutputProc\fR field contains the address of a function called by the
generic layer to transfer data from an internal buffer to the output device.
\fIOutputProc\fR must match the following prototype:
.PP

less in some cases such as if the output operation is interrupted by a
signal. If an error occurs the function should return -1.  In case of
error, some data may have been written to the device.
.PP
If the channel is nonblocking and the output device is unable to absorb any
data whatsoever, the function should return -1 with an \fBEAGAIN\fR error
without writing any data.
.PP
.VS 8.3.2
This value can be retrieved with \fBTcl_ChannelOutputProc\fR, which returns
a pointer to the function.
.VE

.SH SEEKPROC
.PP
The \fIseekProc\fR field contains the address of a function called by the
generic layer to move the access point at which subsequent input or output
operations will be applied. \fISeekProc\fR must match the following
prototype:

the generic layer for returning \fBerrno\fR values from the function.  The
function should set this variable to a POSIX error code if an error occurs.
The function should store an \fBEINVAL\fR error code if the channel type
does not implement seeking.
.PP
The return value is the new access point or -1 in case of error. If an
error occurred, the function should not move the access point.
.PP
.VS 8.3.2
This value can be retrieved with \fBTcl_ChannelSeekProc\fR, which returns
a pointer to the function.
.VE

.SH SETOPTIONPROC
.PP
The \fIsetOptionProc\fR field contains the address of a function called by
the generic layer to set a channel type specific option on a channel.
\fIsetOptionProc\fR must match the following prototype:
.PP

each channel type and the \fIsetOptionProc\fR procedure of the channel
driver will get called to implement them. The \fIsetOptionProc\fR field can
be NULL, which indicates that this channel type supports no type specific
options. 
.PP
If the option value is successfully modified to the new value, the function
returns \fBTCL_OK\fR.

It should call \fBTcl_BadChannelOption\fR which itself returns
\fBTCL_ERROR\fR if the \fIoptionName\fR is
unrecognized. 

If \fIoptionValue\fR specifies a value for the option that
is not supported or if a system call error occurs,
the function should leave an error message in the
\fIresult\fR field of \fIinterp\fR if \fIinterp\fR is not NULL. The
function should also call \fBTcl_SetErrno\fR to store an appropriate POSIX
error code.
.PP
.VS 8.3.2
This value can be retrieved with \fBTcl_ChannelSetOptionProc\fR, which returns
a pointer to the function.
.VE

.SH GETOPTIONPROC
.PP
The \fIgetOptionProc\fR field contains the address of a function called by
the generic layer to get the value of a channel type specific option on a
channel. \fIgetOptionProc\fR must match the following prototype:
.PP
.CS
typedef int Tcl_DriverGetOptionProc(
	ClientData \fIinstanceData\fR,

	Tcl_Interp *\fIinterp\fR,

	char *\fIoptionName\fR,
	Tcl_DString *\fIdsPtr\fR);
.CE
.PP
\fIOptionName\fR is the name of an option supported by this type of
channel. If the option name is not NULL, the function stores its current
value, as a string, in the Tcl dynamic string \fIdsPtr\fR.
If \fIoptionName\fR is NULL, the function stores in \fIdsPtr\fR an
alternating list of all supported options and their current values.
On success, the function returns \fBTCL_OK\fR. 

It should call \fBTcl_BadChannelOption\fR which itself returns
\fBTCL_ERROR\fR if the \fIoptionName\fR is
unrecognized. If a system call error occurs,
the function should leave an error message in the
\fIresult\fR field of \fIinterp\fR if \fIinterp\fR is not NULL. The
function should also call \fBTcl_SetErrno\fR to store an appropriate POSIX
error code.

.PP
Some options are handled by the generic code and this function is never
called to retrieve their value, e.g. \fB-blockmode\fR. Other options are
specific to each channel type and the \fIgetOptionProc\fR procedure of the
channel driver will get called to implement them. The \fIgetOptionProc\fR
field can be NULL, which indicates that this channel type supports no type
specific options.
.PP
.VS 8.3.2
This value can be retrieved with \fBTcl_ChannelGetOptionProc\fR, which returns
a pointer to the function.
.VE

.SH WATCHPROC

.PP
The \fIwatchProc\fR field contains the address of a function called
by the generic layer to initialize the event notification mechanism to
notice events of interest on this channel.
\fIWatchProc\fR should match the following prototype:
.PP
.CS
typedef void Tcl_DriverWatchProc(
	ClientData \fIinstanceData\fR,
	int \fImask\fR);
.CE

.PP
The \fIinstanceData\fR is the same as the value passed to
\fBTcl_CreateChannel\fR when this channel was created. The \fImask\fR
argument is an OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR
and \fBTCL_EXCEPTION\fR; it indicates events the caller is interested in
noticing on this channel.
.PP

The function should initialize device type specific mechanisms to
notice when an event of interest is present on the channel.  When one
or more of the designated events occurs on the channel, the channel
driver is responsible for calling \fBTcl_NotifyChannel\fR to inform
the generic channel module.  The driver should take care not to starve
other channel drivers or sources of callbacks by invoking
Tcl_NotifyChannel too frequently.  Fairness can be insured by using
the Tcl event queue to allow the channel event to be scheduled in sequence
with other events.  See the description of \fBTcl_QueueEvent\fR for
details on how to queue an event.
.PP
.VS 8.3.2
This value can be retrieved with \fBTcl_ChannelWatchProc\fR, which returns
a pointer to the function.
.VE

.SH GETHANDLEPROC
.PP
The \fIgetHandleProc\fR field contains the address of a function called by
the generic layer to retrieve a device-specific handle from the channel.
\fIGetHandleProc\fR should match the following prototype:
.PP
.CS
typedef int Tcl_DriverGetHandleProc(
	ClientData \fIinstanceData\fR,
	int \fIdirection\fR,
	ClientData *\fIhandlePtr\fR);
.CE
.PP
\fIInstanceData\fR is the same as the value passed to
\fBTcl_CreateChannel\fR when this channel was created. The \fIdirection\fR
argument is either \fBTCL_READABLE\fR to retrieve the handle used
for input, or \fBTCL_WRITABLE\fR to retrieve the handle used for
output.
.PP
If the channel implementation has device-specific handles, the
function should retrieve the appropriate handle associated with the
channel, according the \fIdirection\fR argument.  The handle should be
stored in the location referred to by \fIhandlePtr\fR, and
\fBTCL_OK\fR should be returned.  If the channel is not open for the
specified direction, or if the channel implementation does not use
device handles, the function should return \fBTCL_ERROR\fR.
.PP
.VS 8.3.2
This value can be retrieved with \fBTcl_ChannelGetHandleProc\fR, which returns
a pointer to the function.
.VE

.VS 8.3.2
.SH FLUSHPROC
.PP
The \fIflushProc\fR field is currently reserved for future use.
It should be set to NULL.
\fIFlushProc\fR should match the following prototype:
.PP
.CS
typedef int Tcl_DriverFlushProc(
	ClientData \fIinstanceData\fR);
.CE
.PP
This value can be retrieved with \fBTcl_ChannelFlushProc\fR, which returns
a pointer to the function.

.SH HANDLERPROC
.PP
The \fIhandlerProc\fR field contains the address of a function called by
the generic layer to notify the channel that an event occured.  It should
be defined for stacked channel drivers that wish to be notified of events
that occur on the underlying (stacked) channel.
\fIHandlerProc\fR should match the following prototype:
.PP
.CS
typedef int Tcl_DriverHandlerProc(
	ClientData \fIinstanceData\fR,
	int \fIinterestMask\fR);
.CE
.PP
\fIInstanceData\fR is the same as the value passed to \fBTcl_CreateChannel\fR
when this channel was created.  The \fIinterestMask\fR is an OR-ed
combination of \fBTCL_READABLE\fR or \fBTCL_WRITABLE\fR; it indicates what
type of event occured on this channel.
.PP
This value can be retrieved with \fBTcl_ChannelHandlerProc\fR, which returns
a pointer to the function.
.VE

.SH TCL_BADCHANNELOPTION
.PP
This procedure generates a "bad option" error message in an
(optional) interpreter.  It is used by channel drivers when 
a invalid Set/Get option is requested. Its purpose is to concatenate
the generic options list to the specific ones and factorize
the generic options error message string.

    <...generic options...>+<...specific options...>
so you get for instance:
    bad option "-blah": should be one of -blocking,
    -buffering, -buffersize, -eofchar, -translation,
    -peername, or -sockname
when called with optionList="peername sockname"
.CE
``blah'' is the optionName argument and ``<specific options>''
is a space separated list of specific option words.
The function takes good care of inserting minus signs before
each option, commas after, and an ``or'' before the last option.

.SH OLD_CHANNEL

The original (8.3.1 and below) \fBTcl_ChannelType\fR structure contains
the following fields:
.PP
.CS
typedef struct Tcl_ChannelType {
	char *\fItypeName\fR;
	Tcl_DriverBlockModeProc *\fIblockModeProc\fR;	
	Tcl_DriverCloseProc *\fIcloseProc\fR;
	Tcl_DriverInputProc *\fIinputProc\fR;
	Tcl_DriverOutputProc *\fIoutputProc\fR;
	Tcl_DriverSeekProc *\fIseekProc\fR;
	Tcl_DriverSetOptionProc *\fIsetOptionProc\fR;
	Tcl_DriverGetOptionProc *\fIgetOptionProc\fR;
	Tcl_DriverWatchProc *\fIwatchProc\fR;
	Tcl_DriverGetHandleProc *\fIgetHandleProc\fR;
	Tcl_DriverClose2Proc *\fIclose2Proc\fR;
} Tcl_ChannelType;
.CE
.PP
It is still possible to create channel with the above structure.  The
internal channel code will determine the version.  It is imperative to use
the new \fBTcl_ChannelType\fR structure if you are creating a stacked
channel driver, due to problems with the earlier stacked channel
implementation (in 8.2.0 to 8.3.1).

.SH "SEE ALSO"
Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3), Tcl_QueueEvent(3), Tcl_StackChannel(3)

.SH KEYWORDS
blocking, channel driver, channel registration, channel type, nonblocking

'\"
'\" 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.
'\" 
'\" RCS: @(#) $Id: CrtObjCmd.3,v 1.3.12.1 2000/08/07 21:29:37 hobbs Exp $
'\" 
.so man.macros
.TH Tcl_CreateObjCommand 3 8.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, Tcl_GetCommandInfo, Tcl_SetCommandInfo, Tcl_GetCommandName \- implement new commands in C
.SH SYNOPSIS

Tcl command.
.BE
.SH DESCRIPTION
.PP
\fBTcl_CreateObjCommand\fR defines a new command in \fIinterp\fR
and associates it with procedure \fIproc\fR
such that whenever \fIname\fR is
invoked as a Tcl command (e.g., via a call to \fBTcl_EvalObjEx\fR)
the Tcl interpreter will call \fIproc\fR to process the command.
.PP
\fBTcl_CreateObjCommand\fR deletes any existing command
\fIname\fR already associated with the interpreter
(however see below for an exception where the existing command
is not deleted).
It returns a token that may be used to refer

return \fBTCL_OK\fR or \fBTCL_ERROR\fR.
In addition, if \fIproc\fR needs to return a non-empty result,
it can call \fBTcl_SetObjResult\fR to set the interpreter's result.
In the case of a \fBTCL_OK\fR return code this gives the result
of the command,
and in the case of \fBTCL_ERROR\fR this gives an error message.
Before invoking a command procedure,
\fBTcl_EvalObjEx\fR sets interpreter's result to
point to an object representing an empty string, so simple
commands can return an empty result by doing nothing at all.
.PP
The contents of the \fIobjv\fR array belong to Tcl and are not
guaranteed to persist once \fIproc\fR returns: \fIproc\fR should
not modify them.
Call \fBTcl_SetObjResult\fR if you want

was created, then \fBTcl_GetCommandName\fR returns the current name.
This name does not include any \fB::\fR namespace qualifiers.
The command corresponding to \fItoken\fR must not have been deleted.
The string returned by \fBTcl_GetCommandName\fR is in dynamic memory
owned by Tcl and is only guaranteed to retain its value as long as the
command isn't deleted or renamed;  callers should copy the string if
they need to keep it for a long time.


.SH "SEE ALSO"
Tcl_CreateCommand, Tcl_ResetResult, Tcl_SetObjResult

.SH KEYWORDS
bind, command, create, delete, namespace, object

'\"
'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: CrtSlave.3,v 1.3.2.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH Tcl_CreateSlave 3 7.6 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_IsSafe, Tcl_MakeSafe, Tcl_CreateSlave, Tcl_GetSlave, Tcl_GetMaster, Tcl_GetInterpPath, Tcl_CreateAlias, Tcl_CreateAliasObj, Tcl_GetAlias, Tcl_GetAliasObj, Tcl_ExposeCommand, Tcl_HideCommand \- manage multiple Tcl interpreters, aliases and hidden commands.
.SH SYNOPSIS

If a hidden command whose name is \fIhiddenCmdName\fR already
exists, the operation also returns \fBTCL_ERROR\fR and the \fIresult\fR
field in \fIinterp\fR contains an error message.
If the operation succeeds, it returns \fBTCL_OK\fR.
After executing this command, attempts to use \fIcmdName\fR in a call to
\fBTcl_Eval\fR or with the Tcl \fBeval\fR command will fail.
.PP

For a description of the Tcl interface to multiple interpreters, see
\fIinterp(n)\fR.
.SH "SEE ALSO"
interp

.SH KEYWORDS
alias, command, exposed commands, hidden commands, interpreter, invoke,
master, slave, 

'\"
'\" Copyright (c) 1989-1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: DetachPids.3,v 1.2.18.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH Tcl_DetachPids 3 "" Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_DetachPids, Tcl_ReapDetachedProcs, Tcl_WaitPid \- manage child processes in background
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
\fBTcl_DetachPids\fR(\fInumPids, pidPtr\fR)
.sp
\fBTcl_ReapDetachedProcs\fR()
.sp
Tcl_Pid
\fBTcl_WaitPid\fR(\fIpid, statPtr, options\fR)
.SH ARGUMENTS
.AS int *statusPtr
.AP int numPids in
Number of process ids contained in the array pointed to by \fIpidPtr\fR.
.AP int *pidPtr in
Address of array containing \fInumPids\fR process ids.
.AP Tcl_Pid pid in
The id of the process (pipe) to wait for.
.AP int* statPtr out
The result of waiting on a process (pipe). Either 0 or ECHILD.
.AP int options
The options controlling the wait. WNOHANG specifies not to wait when
checking the process.
.BE

.SH DESCRIPTION
.PP
\fBTcl_DetachPids\fR and \fBTcl_ReapDetachedProcs\fR provide a
mechanism for managing subprocesses that are running in background.
These procedures are needed because the parent of a process must
eventually invoke the \fBwaitpid\fR kernel call (or one of a few other
similar kernel calls) to wait for the child to exit.  Until the

Tcl automatically calls \fBTcl_ReapDetachedProcs\fR each time the
\fBexec\fR command is executed, so in most cases it isn't necessary
for any code outside of Tcl to invoke \fBTcl_ReapDetachedProcs\fR.
However, if you call \fBTcl_DetachPids\fR in situations where the
\fBexec\fR command may never get executed, you may wish to call
\fBTcl_ReapDetachedProcs\fR from time to time so that background
processes can be cleaned up.
.PP
\fBTcl_WaitPid\fR is a thin wrapper around the facilities provided by
the operating system to wait on the end of a spawned process and to
check a whether spawned process is still running. It is used by
\fBTcl_ReapDetachedProcs\fR and the channel system to portably access
the operating system.

.SH KEYWORDS
background, child, detach, process, wait

'\"
'\" Copyright (c) 1989-1993 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: Eval.3,v 1.6.2.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH Tcl_Eval 3 8.1 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_EvalObjEx, Tcl_EvalFile, Tcl_EvalObjv, Tcl_Eval, Tcl_EvalEx, Tcl_GlobalEval, Tcl_GlobalEvalObj, Tcl_VarEval, Tcl_VarEvalVA \- execute Tcl scripts
.SH SYNOPSIS

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 (NULL terminated and UTF-8).
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

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 should be a proper UTF-8 string as converted by
\fBTcl_ExternalToUtfDString\fR or \fBTcl_ExternalToUtf\fR when it is known
to possibly contain upper ascii characters who's possible combinations
might be a UTF-8 special code.  The string is parsed and executed directly
(using \fBTcl_EvalObjv\fR) instead of compiling it and executing the
bytecodes.  In situations where it is known that the script will never be
executed again, \fBTcl_Eval\fR may be faster than \fBTcl_EvalObjEx\fR.
\fBTcl_Eval\fR returns a completion code and result just like 
\fBTcl_EvalObjEx\fR.  Note: for backward compatibility with versions before
Tcl 8.0, \fBTcl_Eval\fR copies the object result in \fIinterp\fR to
\fIinterp->result\fR (use is deprecated) where it can be accessed directly.
This makes \fBTcl_Eval\fR somewhat slower than \fBTcl_EvalEx\fR, which
doesn't do the copy.
.PP
\fBTcl_EvalEx\fR is an extended version of \fBTcl_Eval\fR that takes

'\"
'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: Exit.3,v 1.3.12.1 2000/08/07 21:29:37 hobbs Exp $
'\" 
.so man.macros
.TH Tcl_Exit 3 8.1 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_Exit, Tcl_Finalize, Tcl_CreateExitHandler, Tcl_DeleteExitHandler, Tcl_ExitThread, Tcl_FinalizeThread, Tcl_CreateThreadExitHandler, Tcl_DeleteThreadExitHandler \- end the application or thread (and invoke exit handlers)
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
\fBTcl_Exit\fR(\fIstatus\fR)
.sp
\fBTcl_Finalize\fR()

'\"
'\" 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: GetIndex.3,v 1.5.8.1 2000/08/07 21:29:37 hobbs Exp $
'\" 
.so man.macros
.TH Tcl_GetIndexFromObj 3 8.1 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_GetIndexFromObj, Tcl_GetIndexFromObjStruct \- lookup string in table of keywords
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
int
\fBTcl_GetIndexFromObj\fR(\fIinterp, objPtr, tablePtr, msg, flags,
indexPtr\fR)

'\"
'\" 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.
'\" 
'\" RCS: @(#) $Id: Notifier.3,v 1.7.12.1 2000/08/07 21:29:37 hobbs Exp $
'\" 
.so man.macros
.TH Notifier 3 8.1 Tcl "Tcl Library Procedures"
.BS
.SH NAME
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

more information on memory management issues).  Each event source can
define its own event structure with whatever information is relevant
to that event source.  However, the first element of the structure
must be a structure of type \fBTcl_Event\fR, and the address of this
structure is used when communicating between the event source and the
rest of the notifier.  A \fBTcl_Event\fR has the following definition:
.CS
typedef struct {
    Tcl_EventProc *\fIproc\fR;
    struct Tcl_Event *\fInextPtr\fR;
} Tcl_Event;
.CE
The event source must fill in the \fIproc\fR field of
the event before calling \fBTcl_QueueEvent\fR.
The \fInextPtr\fR is used to link together the events in the queue
and should not be modified by the event source.
.PP
An event may be added to the queue at any of three positions, depending

\fBTcl_SetServiceMode\fR returns the previous value of the service
mode, which should be restored when the recursive loop exits.
\fBTcl_GetServiceMode\fR returns the current value of the service
mode.
.VE
.SH "SEE ALSO"
\fBTcl_CreateFileHandler\fR, \fBTcl_DeleteFileHandler\fR, \fBTcl_Sleep\fR,
\fBTcl_DoOneEvent\fR, \fBThread(3)\fR
.SH KEYWORDS
event, notifier, event queue, event sources, file events, timer, idle, service mode, threads

'\"
'\" 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.
'\" 
'\" RCS: @(#) $Id: Object.3,v 1.4.10.1 2000/08/07 21:29:38 hobbs Exp $
'\" 
.so man.macros
.TH Tcl_Obj 3 8.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_NewObj, Tcl_DuplicateObj, Tcl_IncrRefCount, Tcl_DecrRefCount, Tcl_IsShared, Tcl_InvalidateStringRep \- manipulate Tcl objects
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
Tcl_Obj *
\fBTcl_NewObj\fR()
.sp

'\"
'\" 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.
'\" 
'\" RCS: @(#) $Id: ObjectType.3,v 1.2.18.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH Tcl_ObjType 3 8.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_RegisterObjType, Tcl_GetObjType, Tcl_AppendAllObjTypes, Tcl_ConvertToType  \- manipulate Tcl object types
.SH SYNOPSIS

.PP
\fBTcl_RegisterObjType\fR registers a new Tcl object type
in the table of all object types supported by Tcl.
The argument \fItypePtr\fR points to a Tcl_ObjType structure that
describes the new type by giving its name
and by supplying pointers to four procedures
that implement the type.
If the type table already contains a type
with the same name as in \fItypePtr\fR,
it is replaced with the new type.
The Tcl_ObjType structure is described
in the section \fBTHE TCL_OBJTYPE STRUCTURE\fR below.
.PP
\fBTcl_GetObjType\fR returns a pointer to the Tcl_ObjType
with name \fItypeName\fR.

'\"
'\" 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: RecEvalObj.3,v 1.2.18.1 2000/08/07 21:29:38 hobbs Exp $
'\" 
.so man.macros
.TH Tcl_RecordAndEvalObj 3 8.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_RecordAndEvalObj \- save command on history list before evaluating
.SH SYNOPSIS

command but don't evaluate it.  TCL_EVAL_GLOBAL means evaluate
the command at global level instead of the current stack level.
.BE

.SH DESCRIPTION
.PP
\fBTcl_RecordAndEvalObj\fR is invoked to record a command as an event
on the history list and then execute it using \fBTcl_EvalObjEx\fR
(or \fBTcl_GlobalEvalObj\fR if the TCL_EVAL_GLOBAL bit is set
in \fIflags\fR).
It returns a completion code such as TCL_OK just like \fBTcl_EvalObjEx\fR,
as well as a result object containing additional information
(a result value or error message)
that can be retrieved using \fBTcl_GetObjResult\fR.
If you don't want the command recorded on the history list then
you should invoke \fBTcl_EvalObjEx\fR instead of \fBTcl_RecordAndEvalObj\fR.
Normally \fBTcl_RecordAndEvalObj\fR is only called with top-level
commands typed by the user, since the purpose of history is to
allow the user to re-issue recently-invoked commands.
If the \fIflags\fR argument contains the TCL_NO_EVAL bit then
the command is recorded without being evaluated.

.SH "SEE ALSO"
Tcl_EvalObjEx, Tcl_GetObjResult

.SH KEYWORDS
command, event, execute, history, interpreter, object, record

'\"
'\" 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.
'\" 
'\" RCS: @(#) $Id: RegExp.3,v 1.6.2.1 2000/08/07 21:29:38 hobbs Exp $
'\" 
.so man.macros
.TH Tcl_RegExpMatch 3 8.1 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_RegExpMatch, Tcl_RegExpCompile, Tcl_RegExpExec, Tcl_RegExpRange, Tcl_GetRegExpFromObj, Tcl_RegExpMatchObj, Tcl_RegExpExecObj, Tcl_RegExpGetInfo \- 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

.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_RegExpGetInfo\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.  The interpreter may be
NULL if no error reporting is desired.

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_RegExpGetInfo\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

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_RegExpGetInfo\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_RegExpGetInfo\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:

`[^' 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_RegExpGetInfo\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

.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_RegExpGetInfo\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;

'\"
'\" Copyright (c) 1989-1993 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: SetResult.3,v 1.5.2.1 2000/08/07 21:29:38 hobbs Exp $
'\" 
.so man.macros
.TH Tcl_SetResult 3 8.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult, Tcl_AppendResult, Tcl_AppendResultVA, Tcl_AppendElement, Tcl_ResetResult, Tcl_FreeResult \- manipulate Tcl result
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
\fBTcl_SetObjResult\fR(\fIinterp, objPtr\fR)
.sp
Tcl_Obj *

'\"
'\" Copyright (c) 1989-1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: SplitList.3,v 1.3.2.1 2000/08/07 21:29:38 hobbs Exp $
'\" 
.so man.macros
.TH Tcl_SplitList 3 8.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_SplitList, Tcl_Merge, Tcl_ScanElement, Tcl_ConvertElement, Tcl_ScanCountedElement, Tcl_ConvertCountedElement \- manipulate Tcl lists
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
int
\fBTcl_SplitList\fR(\fIinterp, list, argcPtr, argvPtr\fR)
.sp

'\"
'\" Copyright (c) 1989-1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: StrMatch.3,v 1.3.10.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH Tcl_StringMatch 3 8.1 Tcl "Tcl Library Procedures"
.BS
.SH NAME
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)

.sp
int
\fBTcl_StringCaseMatch\fR(\fIstring\fR, \fIpattern\fR, \fInocase\fR)

.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[].

.AP int nocase in
Specifies whether the match should be done case-sensitive (0) or
case-insensitive (1).

.BE

.SH DESCRIPTION
.PP
This utility procedure determines whether a string matches
a given pattern.  If it does, then \fBTcl_StringMatch\fR returns
1.  Otherwise \fBTcl_StringMatch\fR returns 0.  The algorithm

'\"
'\" Copyright (c) 1999 Scriptics Corporation
'\" 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.
'\" 
'\" RCS: @(#) $Id: Thread.3,v 1.11.2.1 2000/08/07 21:29:38 hobbs Exp $
'\" 
.so man.macros
.TH Threads 3 "8.1" Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_ConditionNotify, Tcl_ConditionWait, Tcl_ConditionFinalize, Tcl_GetThreadData, Tcl_MutexLock, Tcl_MutexUnlock, Tcl_MutexFinalize, Tcl_CreateThread \- Tcl thread support.
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
void
\fBTcl_ConditionNotify\fR(\fIcondPtr\fR)
.sp

.AP int *size in
The size of the thread local storage block.  This amount of data
is allocated and initialized to zero the first time each thread
calls \fBTcl_GetThreadData\fR.
.AP Tcl_ThreadId *idPtr out
The refered storage will contain the id of the newly created thread as
returned by the operating system.
.AP Tcl_ThreadId id in
Id of the thread waited upon.
.AP Tcl_ThreadCreateProc threadProc in
This procedure will act as the \fBmain()\fR of the newly created
thread. The specified \fIclientData\fR will be its sole argument.
.AP ClientData clientData in
Arbitrary information. Passed as sole argument to the \fIthreadProc\fR.
.AP int stackSize in
The size of the stack given to the new thread.
.AP int flags in
Bitmask containing flags allowing the caller to modify behaviour of
the new thread.
.AP int *result out
The refered storage is used to place the exit code of the thread
waited upon into it.
.BE
.SH INTRODUCTION
Beginning with the 8.1 release, the Tcl core is thread safe, which
allows you to incorporate Tcl into multithreaded applications without
customizing the Tcl core.  To enable Tcl multithreading support,
you must include the \fB--enable-threads\fR option to \fBconfigure\fR
when you configure and compile your Tcl core.

'\"
'\" Copyright (c) 1990-1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: after.n,v 1.2.18.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH after n 7.5 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
after \- Execute a command after a time delay

assume that the application is event driven:  the delayed commands
will not be executed unless the application enters the event loop.
In applications that are not normally event-driven, such as
\fBtclsh\fR, the event loop can be entered with the \fBvwait\fR
and \fBupdate\fR commands.

.SH "SEE ALSO"
bgerror(n), concat(n), update(n), vwait(n)

.SH KEYWORDS
cancel, delay, idle callback, sleep, time

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: append.n,v 1.2.18.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH append n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
append \- Append to variable

it is given a value equal to the concatenation of all the
\fIvalue\fR arguments.
This command provides an efficient way to build up long
variables incrementally.
For example, ``\fBappend a $b\fR'' is much more efficient than
``\fBset a $a$b\fR'' if \fB$a\fR is long.

.SH "SEE ALSO"
concat(n), lappend(n)

.SH KEYWORDS
append, variable

'\"
'\" Copyright (c) 1990-1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: bgerror.n,v 1.2.18.2 2001/08/06 22:24:11 andreas_kupries Exp $
'\" 
.so man.macros
.TH bgerror n 7.5 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
bgerror \- Command invoked to process background errors

A background error is one that occurs in an event handler or some
other command that didn't originate with the application.
For example, if an error occurs while executing a command specified
with the \fBafter\fR command, then it is a background error.
For a non-background error, the error can simply be returned up
through nested Tcl command evaluations until it reaches the top-level
code in the application; then the application can report the error
in whatever way it wishes.  When a background error occurs, the

unwinding ends in the Tcl library and there is no obvious way for Tcl
to report the error.
.PP
When Tcl detects a background error, it saves information about the
error and invokes the \fBbgerror\fR command later as an idle event
handler. Before invoking \fBbgerror\fR, Tcl restores the
\fBerrorInfo\fR and \fBerrorCode\fR variables to their values at the
time the error occurred, then it invokes \fBbgerror\fR with the error
message as its only argument.  Tcl assumes that the application has
implemented the \fBbgerror\fR command, and that the command will
report the error in a way that makes sense for the application.  Tcl
will ignore any result returned by the \fBbgerror\fR command as long
as no error is generated.
.PP
If another Tcl error occurs within the \fBbgerror\fR command (for
example, because no \fBbgerror\fR command has been defined) then Tcl
reports the error itself by writing a message to stderr.
.PP
If several background errors accumulate before \fBbgerror\fR is
invoked to process them, \fBbgerror\fR will be invoked once for each
error, in the order they occurred.  However, if \fBbgerror\fR returns
with a break exception, then any remaining errors are skipped without
calling \fBbgerror\fR.
.PP
Tcl has no default implementation for \fBbgerror\fR. However, in
applications using Tk there is a default \fBbgerror\fR procedure which


posts a dialog box containing the error message and offers the user a
chance to see a stack trace showing where the error occurred.
.SH "SEE ALSO"
after(n), tclvars(n)

.SH KEYWORDS
background error, reporting

'\"
'\" 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: binary.n,v 1.4.2.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH binary n 8.0 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
binary \- Insert and extract fields from binary strings
.SH SYNOPSIS
\fBbinary format \fIformatString \fR?\fIarg arg ...\fR?
.br
\fBbinary scan \fIstring formatString \fR?\fIvarName varName ...\fR?
.BE

.SH DESCRIPTION
.PP
This command provides facilities for manipulating binary data.  The
first form, \fBbinary format\fR, creates a binary string from normal
Tcl values.  For example, given the values 16 and 22, on a 32 bit
architecture, it might produce an 8-byte binary string consisting of
two 4-byte integers, one for each of the numbers.  The second form of
the command, \fBbinary scan\fR, does the opposite: it extracts data
from a binary string and returns it as ordinary Tcl string values.

.SH "BINARY FORMAT"
.PP
The \fBbinary format\fR command generates a binary string whose layout
is specified by the \fIformatString\fR and whose contents come from
the additional arguments.  The resulting binary value is returned.
.PP

.SH "PLATFORM ISSUES"
Sometimes it is desirable to format or scan integer values in the
native byte order for the machine.  Refer to the \fBbyteOrder\fR
element of the \fBtcl_platform\fR array to decide which type character
to use when formatting or scanning integers.

.SH "SEE ALSO"
format(n), scan(n), tclvars(n)

.SH KEYWORDS
binary, format, scan

'\"
'\" Copyright (c) 1993-1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: break.n,v 1.2.18.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH break n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
break \- Abort looping command

The exception causes the current script to be aborted
out to the innermost containing loop command, which then
aborts its execution and returns normally.
Break exceptions are also handled in a few other situations, such
as the \fBcatch\fR command, Tk event bindings, and the outermost
scripts of procedure bodies.

.SH "SEE ALSO"
catch(n), continue(n), for(n), foreach(n), while(n)

.SH KEYWORDS
abort, break, loop

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: case.n,v 1.2.18.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH case n 7.0 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
case \- Evaluate one of several scripts, depending on a given value

The second form makes it easy to construct multi-line case commands,
since the braces around the whole list make it unnecessary to include a
backslash at the end of each line.
Since the \fIpatList\fR arguments are in braces in the second form,
no command or variable substitutions are performed on them;  this makes
the behavior of the second form different than the first form in some
cases.

.SH "SEE ALSO"
switch(n)

.SH KEYWORDS
case, match, regular expression

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: cd.n,v 1.2.18.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH cd n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
cd \- Change working directory
.SH SYNOPSIS
\fBcd \fR?\fIdirName\fR?
.BE

.SH DESCRIPTION
.PP
Change the current working directory to \fIdirName\fR, or to the
home directory (as specified in the HOME environment variable) if
\fIdirName\fR is not given.
Returns an empty string.

.SH "SEE ALSO"
filename(n), glob(n), pwd(n)

.SH KEYWORDS
working directory

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: close.n,v 1.2.18.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH close n 7.5 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
close \- Close an open channel.

when the process exits.  Channels are switched to blocking mode, to ensure
that all output is correctly flushed before the process exits.
.VE
.PP
The command returns an empty string, and may generate an error if
an error occurs while flushing output.

.SH "SEE ALSO"
file(n), open(n), socket(n), eof(n)

.SH KEYWORDS
blocking, channel, close, nonblocking

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: concat.n,v 1.2.18.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH concat n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
concat \- Join lists together

.CS
\fBa b c d e f {g h}\fR
.CE
as its result.
.PP
If no \fIarg\fRs are supplied, the result is an empty string.

.SH "SEE ALSO"
append(n), eval(n)

.SH KEYWORDS
concatenate, join, lists

'\"
'\" Copyright (c) 1993-1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: continue.n,v 1.2.18.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH continue n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
continue \- Skip to the next iteration of a loop

The exception causes the current script to be aborted
out to the innermost containing loop command, which then
continues with the next iteration of the loop.
Catch exceptions are also handled in a few other situations, such
as the \fBcatch\fR command and the outermost scripts of procedure
bodies.

.SH "SEE ALSO"
break(n), for(n), foreach(n), while(n)

.SH KEYWORDS
continue, iteration, loop

'\"
'\" 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: dde.n,v 1.5.2.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH dde n 8.1 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
dde \- Execute a Dynamic Data Exchange command

When using DDE, be careful to ensure that the event queue is flushed
using either \fBupdate\fR or \fBvwait\fR.  This happens by default
when using \fBwish\fR unless a blocking command is called (such as \fBexec\fR
without adding the \fB&\fR to place the process in the background).
If for any reason the event queue is not flushed, DDE commands may
hang until the event queue is flushed.  This can create a deadlock
situation.

.SH "SEE ALSO"
tk(n), winfo(n), send(n)

.SH KEYWORDS
application, dde, name, remote execution

'\"
'\" Copyright (c) 1998 by 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: encoding.n,v 1.2.12.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH encoding n "8.1" Tcl "Tcl Built-In Commands"
.BS
.SH NAME
encoding \- Manipulate encodings
.SH SYNOPSIS

.CS
	set s [encoding convertfrom euc-jp "\\xA4\\xCF"]
.CE
would return the Unicode string "\\u306F", which is the Hiragana
letter HA.

.SH "SEE ALSO"
Tcl_GetEncoding(3)

.SH KEYWORDS
encoding

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: eof.n,v 1.2.18.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH eof n 7.5 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
eof \- Check for end of file condition on channel
.SH SYNOPSIS
\fBeof \fIchannelId\fR
.BE

.SH DESCRIPTION
.PP
Returns 1 if an end of file condition occurred during the most
recent input operation on \fIchannelId\fR (such as \fBgets\fR),
0 otherwise.

.SH "SEE ALSO"
file(n), open(n), close(n), fblocked(n)

.SH KEYWORDS
channel, end of file

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: error.n,v 1.2.18.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH error n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
error \- Generate an error

such information is available; see the \fBtclvars\fR manual
page for information on the proper format for the variable.
If the \fIcode\fR argument is not
present, then \fBerrorCode\fR is automatically reset to
``NONE'' by the Tcl interpreter as part of processing the
error generated by the command.

.SH "SEE ALSO"
catch(n), tclvars(n)

.SH KEYWORDS
error, errorCode, errorInfo

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: eval.n,v 1.2.18.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH eval n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
eval \- Evaluate a Tcl script

\fBEval\fR concatenates all its arguments in the same
fashion as the \fBconcat\fR command, passes the concatenated string to the
Tcl interpreter recursively, and returns the result of that
evaluation (or any error generated by it).

.SH KEYWORDS
concatenate, evaluate, script

.SH "SEE ALSO"
catch(n), concat(n), error(n), subs(n), tclvars(n)

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: exec.n,v 1.4.2.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH exec n 7.6 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
exec \- Invoke subprocess(es)

\fBMacintosh\fR
The \fBexec\fR command is not implemented and does not exist under Macintosh.
.TP
\fBUnix\fR\0\0\0\0\0\0\0
The \fBexec\fR command is fully functional and works as described.

.SH "SEE ALSO"
error(n), open(n)


.SH KEYWORDS
execute, pipeline, redirection, subprocess

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: exit.n,v 1.2.18.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH exit n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
exit \- End the application
.SH SYNOPSIS
\fBexit \fR?\fIreturnCode\fR?
.BE

.SH DESCRIPTION
.PP
Terminate the process, returning \fIreturnCode\fR to the
system as the exit status.
If \fIreturnCode\fR isn't specified then it defaults
to 0.

.SH "SEE ALSO"
exec(n), tclvars(n)

.SH KEYWORDS
exit, process

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-2000 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: expr.n,v 1.2.18.1 2000/08/07 21:29:39 hobbs Exp $
'\" 
.so man.macros
.TH expr n 8.3 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
expr \- Evaluate an expression
.SH SYNOPSIS
\fBexpr \fIarg \fR?\fIarg arg ...\fR?
.BE

.CE
both return 1.  The first comparison is done using integer
comparison, and the second is done using string comparison after
the second operand is converted to the string \fB18\fR.
Because of Tcl's tendency to treat values as numbers whenever
possible, it isn't generally a good idea to use operators like \fB==\fR
when you really want string comparison and the values of the
operands could be arbitrary;  it's better in these cases to use
the \fBstring\fR command instead.

.SH "PERFORMANCE CONSIDERATIONS"

.PP
Enclose expressions in braces for the best speed and the smallest
storage requirements.
This allows the Tcl bytecode compiler to generate the best code.
.PP
As mentioned above, expressions are substituted twice:
once by the Tcl parser and once by the \fBexpr\fR command.

need two rounds of substitutions,
the bytecode compiler must emit
additional instructions to handle this situation.
The most expensive code is required for
unbraced expressions that contain command substitutions.
These expressions must be implemented by generating new code
each time the expression is executed.


.SH KEYWORDS
arithmetic, boolean, compare, expression, fuzzy comparison

'\" 
'\" Copyright (c) 1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" RCS: @(#) $Id: fblocked.n,v 1.2.18.1 2001/04/03 22:06:43 hobbs Exp $
.so man.macros
.TH fblocked n 7.5 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
fblocked \- Test whether the last input operation exhausted all available input
.SH SYNOPSIS
\fBfblocked \fIchannelId\fR
.BE

.SH DESCRIPTION
.PP
The \fBfblocked\fR command returns 1 if the most recent input operation
on \fIchannelId\fR returned less information than requested because all
available input was exhausted.
For example, if \fBgets\fR is invoked when there are only three
characters available for input and no end-of-line sequence, \fBgets\fR
returns an empty string and a subsequent call to \fBfblocked\fR will
return 1.
.PP

.SH "SEE ALSO"
gets(n), open(n), read(n)

.SH KEYWORDS
blocking, nonblocking

'\"
'\" Copyright (c) 1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: fileevent.n,v 1.2.18.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH fileevent n 7.5 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
fileevent \- Execute a script when a channel becomes readable or writable

.SH CREDITS
.PP
\fBfileevent\fR is based on the \fBaddinput\fR command created
by Mark Diekhans.

.SH "SEE ALSO"
bgerror(n), fconfigure(n), gets(n), puts(n), read(n)

.SH KEYWORDS
asynchronous I/O, blocking, channel, event handler, nonblocking, readable,
script, writable.

'\"
'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: filename.n,v 1.3.2.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH filename n 7.5 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
filename \- File name conventions supported by Tcl commands

alphanumeric characters only.  Also Windows 3.1 only supports file
names with a root of no more than 8 characters and an extension of no
more than 3 characters.

.SH KEYWORDS
current directory, absolute file name, relative file name,
volume-relative file name, portability

.SH "SEE ALSO"
file(n), glob(n)

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: flush.n,v 1.2.18.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH flush n 7.5 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
flush \- Flush buffered output for a channel

If the channel is in blocking mode the command does not return until all the
buffered output has been flushed to the channel. If the channel is in
nonblocking mode, the command may return before all buffered output has been
flushed; the remainder will be flushed in the background as fast as the
underlying file or device is able to absorb it.

.SH "SEE ALSO"
file(n), open(n), socket(n)

.SH KEYWORDS
blocking, buffer, channel, flush, nonblocking, output

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: for.n,v 1.2.18.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH for n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
for \- ``For'' loop

around \fB$x<10\fR:
.CS
for {set x 0} {$x<10} {incr x} {
	puts "x is $x"
}
.CE

.SH "SEE ALSO"
break, continue, foreach, while

.SH KEYWORDS
for, iteration, looping

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: foreach.n,v 1.2.18.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH foreach n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
foreach \- Iterate over all elements in one or more lists

set x {}
foreach i {a b c} {j k} {d e f g} {
    lappend x $i $j $k
}
# The value of x is "a d e b f g c {} {}"
# There are 3 iterations of the loop.
.DE

.SH "SEE ALSO"
for(n), while(n), break(n), continue(n)

.SH KEYWORDS
foreach, iteration, list, looping

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: format.n,v 1.4.2.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH format n 8.1 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
format \- Format a string in the style of sprintf

The \fBl\fR modifier is ignored;  integer values are always converted
as if there were no modifier present and real values are always
converted as if the \fBl\fR modifier were present (i.e. type
\fBdouble\fR is used for the internal representation).
If the \fBh\fR modifier is specified then integer values are truncated
to \fBshort\fR before conversion.

.SH "SEE ALSO"
sprintf(3), string(n)

.SH KEYWORDS
conversion specifier, format, sprintf, string, substitution

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: gets.n,v 1.2.18.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH gets n 7.5 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
gets \- Read a line from a channel

and no-full-line-available cases can
produce the same results as if there were an input line consisting
only of the end-of-line character(s).
The \fBeof\fR and \fBfblocked\fR commands can be used to distinguish
these three cases.

.SH "SEE ALSO"
file(n), eof(n), fblocked(n)

.SH KEYWORDS
blocking, channel, end of file, end of line, line, nonblocking, read

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: glob.n,v 1.7.2.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH glob n 8.3 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
glob \- Return names of files that match patterns

\fBMacintosh\fR 
. 
When using the options, \fB\-dir\fR, \fB\-join\fR or \fB\-path\fR, glob
assumes the directory separator for the entire pattern is the standard
``:''.  When not using these options, glob examines each pattern argument
and uses ``/'' unless the pattern contains a ``:''.

.SH "SEE ALSO"
file(n)

.SH KEYWORDS
exist, file, glob, pattern

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: global.n,v 1.2.18.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH global n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
global \- Access global variables

If so then it declares the given \fIvarname\fR's to be global variables
rather than local ones.
Global variables are variables in the global namespace.
For the duration of the current procedure
(and only while executing in the current procedure),
any reference to any of the \fIvarname\fRs
will refer to the global variable by the same name.
.PP
Please note that this is done by creating local variables that are
linked to the global variables, and therefore that these variables
will be listed by \fBinfo locals\fR like all other local variables.

.SH "SEE ALSO"
namespace(n), upvar(n), variable(n)

.SH KEYWORDS
global, namespace, procedure, variable

'\"
'\" Copyright (c) 1995-1997 Sun Microsystems, Inc.
'\" Copyright (c) 1998-2000 by Ajuba Solutions.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: http.n,v 1.10.2.2 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH "Http" n 8.3 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
Http \- Client-side implementation of the HTTP/1.0 protocol.
.SH SYNOPSIS
\fBpackage require http ?2.3?\fP
.sp
\fB::http::config \fI?options?\fR
.sp
\fB::http::geturl \fIurl ?options?\fR
.sp
\fB::http::formatQuery \fIlist\fR
.sp
\fB::http::reset \fItoken\fR
.sp
\fB::http::wait \fItoken\fR
.sp
\fB::http::status \fItoken\fR
.sp
\fB::http::size \fItoken\fR
.sp
\fB::http::code \fItoken\fR
.sp
\fB::http::ncode \fItoken\fR
.sp
\fB::http::data \fItoken\fR
.sp
\fB::http::error \fItoken\fR
.sp
\fB::http::cleanup \fItoken\fR
.sp
\fB::http::register \fIproto port command\fR
.sp
\fB::http::unregister \fIproto\fR
.BE

a custom \fBsocket\fR command, via \fBhttp::register\fR.
.PP
The \fB::http::geturl\fR procedure does a HTTP transaction.
Its \fIoptions \fR determine whether a GET, POST, or HEAD transaction
is performed.  
The return value of \fB::http::geturl\fR is a token for the transaction.
The value is also the name of an array in the ::http namespace

that contains state information about the transaction.  The elements
of this array are described in the STATE ARRAY section.
.PP
If the \fB-command\fP option is specified, then
the HTTP operation is done in the background.
\fB::http::geturl\fR returns immediately after generating the
HTTP request and the callback is invoked
when the transaction completes.  For this to work, the Tcl event loop
must be active.  In Tk applications this is always true.  For pure-Tcl

\fB::http::reset\fP \fItoken\fP ?\fIwhy\fP?
This command resets the HTTP transaction identified by \fItoken\fR, if
any.  This sets the \fBstate(status)\fP value to \fIwhy\fP, which defaults to \fBreset\fR, and then calls the registered \fB\-command\fR callback.
.TP
\fB::http::wait\fP \fItoken\fP
This is a convenience procedure that blocks and waits for the
transaction to complete.  This only works in trusted code because it
uses \fBvwait\fR.  Also, it's not useful for the case where
\fB::http::geturl\fP is called \fIwithout\fP the \fB-command\fP option
because in this case the \fB::http::geturl\fP call doesn't return
until the HTTP transaction is complete, and thus there's nothing to
wait for.
.TP
\fB::http::data\fP \fItoken\fP
This is a convenience procedure that returns the \fBbody\fP element
(i.e., the URL data) of the state array.
.TP
\fB::http::error\fP \fItoken\fP
This is a convenience procedure that returns the \fBerror\fP element
of the state array.
.TP
\fB::http::status\fP \fItoken\fP
This is a convenience procedure that returns the \fBstatus\fP element of
the state array.
.TP
\fB::http::code\fP \fItoken\fP
This is a convenience procedure that returns the \fBhttp\fP element of the
state array.
.TP
\fB::http::ncode\fP \fItoken\fP
This is a convenience procedure that returns just the numeric return
code (200, 404, etc.) from the \fBhttp\fP element of the state array.
.TP
\fB::http::size\fP \fItoken\fP
This is a convenience procedure that returns the \fBcurrentsize\fP
element of the state array, which represents the number of bytes
received from the URL in the \fB::http::geturl\fP call.
.TP
\fB::http::cleanup\fP \fItoken\fP
This procedure cleans up the state associated with the connection
identified by \fItoken\fP.  After this call, the procedures
like \fB::http::data\fP cannot be used to get information
about the operation.  It is \fIstrongly\fP recommended that you call
this function after you're done with a given HTTP request.  Not doing
so will result in memory not being freed, and if your app calls
\fB::http::geturl\fP enough times, the memory leak could cause a
performance hit...or worse.
.TP
\fB::http::register\fP \fIproto port command\fP
This procedure allows one to provide custom HTTP transport types
such as HTTPS, by registering a prefix, the default port, and the
command to execute to create the Tcl \fBchannel\fR. E.g.:
.RS
.CS

This procedure unregisters a protocol handler that was previously
registered via \fBhttp::register\fR.

.SH "ERRORS"
The \fBhttp::geturl\fP procedure will raise errors in the following cases:
invalid command line options,
an invalid URL,
a URL on a non-existent host,
or a URL at a bad port on an existing host.
These errors mean that it
cannot even start the network transaction.
It will also raise an error if it gets an I/O error while
writing out the HTTP request header.
For synchronous \fB::http::geturl\fP calls (where \fB-command\fP is
not specified), it will raise an error if it gets an I/O error while
reading the HTTP reply headers or data.  Because \fB::http::geturl\fP
doesn't return a token in these cases, it does all the required
cleanup and there's no issue of your app having to call
\fB::http::cleanup\fP.
.PP

For asynchronous \fB::http::geturl\fP calls, all of the above error
situations apply, except that if there's any error while 
reading the
HTTP reply headers or data, no exception is thrown.  This is because
after writing the HTTP headers, \fB::http::geturl\fP returns, and the
rest of the HTTP transaction occurs in the background.  The command
callback can check if any error occurred during the read by calling
\fB::http::status\fP to check the status and if it's \fIerror\fP,
calling \fB::http::error\fP to get the error message.
.PP
Alternatively, if the main program flow reaches a point where it needs
to know the result of the asynchronous HTTP request, it can call
\fB::http::wait\fP and then check status and error, just as the

callback does.
.PP
In any case, you must still call
\fBhttp::cleanup\fP to delete the state array when you're done.
.PP
There are other possible results of the HTTP transaction
determined by examining the status from \fBhttp::status\fP.
These are described below.
.TP
ok
If the HTTP transaction completes entirely, then status will be \fBok\fP.
However, you should still check the \fBhttp::code\fP value to get
the HTTP status.  The \fBhttp::ncode\fP procedure provides just
the numeric error (e.g., 200, 404 or 500) while the \fBhttp::code\fP
procedure returns a value like "HTTP 404 File not found".
.TP
eof
If the server closes the socket without replying, then no error
is raised, but the status of the transaction will be \fBeof\fP.
.TP
error

The error message will also be stored in the \fBerror\fP status
array element, accessible via \fB::http::error\fP.
.PP
Another error possibility is that \fBhttp::geturl\fP is unable to
write all the post query data to the server before the server
responds and closes the socket.
The error message is saved in the \fBposterror\fP status array
element and then  \fBhttp::geturl\fP attempts to complete the
transaction.

.TP
\fBposterror\fR
The error, if any, that occurred while writing
the post query data to the server.
.TP
\fBstatus\fR
Either \fBok\fR, for successful completion, \fBreset\fR for
user-reset, \fBtimeout\fP if a timeout occurred before the transaction
could complete, or \fBerror\fR for an error condition.  During the
transaction this value is the empty string.
.TP
\fBtotalsize\fR
A copy of the \fBContent-Length\fR meta-data value.
.TP
\fBtype\fR
A copy of the \fBContent-Type\fR meta-data value.

    }

    return $token
}
proc ::http::Progress {args} {
    puts -nonewline stderr . ; flush stderr
}

.DE

.SH "SEE ALSO"
safe(n), socket(n), safesock(n)

.SH KEYWORDS
security policy, socket

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: if.n,v 1.2.18.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH if n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
if \- Execute scripts conditionally

``noise words'' to make the command easier to read.
There may be any number of \fBelseif\fR clauses, including zero.
\fIBodyN\fR may also be omitted as long as \fBelse\fR is omitted too.
The return value from the command is the result of the body script
that was executed, or an empty string
if none of the expressions was non-zero and there was no \fIbodyN\fR.

.SH "SEE ALSO"
expr(n), for(n), foreach(n)

.SH KEYWORDS
boolean, conditional, else, false, if, true

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: incr.n,v 1.2.18.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH incr n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
incr \- Increment the value of a variable
.SH SYNOPSIS
\fBincr \fIvarName \fR?\fIincrement\fR?
.BE

.SH DESCRIPTION
.PP
Increments the value stored in the variable whose name is \fIvarName\fR.
The value of the variable must be an integer.
If \fIincrement\fR is supplied then its value (which must be an
integer) is added to the value of variable \fIvarName\fR;  otherwise
1 is added to \fIvarName\fR.
The new value is stored as a decimal string in variable \fIvarName\fR
and also returned as result.

.SH "SEE ALSO"
expr(n)

.SH KEYWORDS
add, increment, variable, value

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: join.n,v 1.2.18.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH join n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
join \- Create a string by joining together list elements
.SH SYNOPSIS
\fBjoin \fIlist \fR?\fIjoinString\fR?
.BE

.SH DESCRIPTION
.PP
The \fIlist\fR argument must be a valid Tcl list.
This command returns the string
formed by joining all of the elements of \fIlist\fR together with
\fIjoinString\fR separating each adjacent pair of elements.
The \fIjoinString\fR argument defaults to a space character.

.SH "SEE ALSO"
list(n), lappend(n)

.SH KEYWORDS
element, join, list, separator

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: lappend.n,v 1.2.18.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH lappend n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
lappend \- Append list elements onto a variable

\fBLappend\fR is similar to \fBappend\fR except that the \fIvalue\fRs
are appended as list elements rather than raw text.
This command provides a relatively efficient way to build up
large lists.  For example, ``\fBlappend a $b\fR'' is much
more efficient than ``\fBset a [concat $a [list $b]]\fR'' when
\fB$a\fR is long.

.SH "SEE ALSO"
list(n), lindex(n), linsert(n), llength(n), lsort(n), lrange(n)

.SH KEYWORDS
append, element, list, variable

'\"
'\" Copyright (c) 1991-1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: library.n,v 1.11.2.2 2001/04/03 22:06:43 hobbs Exp $
.so man.macros
.TH library n "8.0" Tcl "Tcl Built-In Commands"
.BS
.SH NAME
auto_execok, auto_import, auto_load, auto_mkindex, auto_mkindex_old, auto_qualify, auto_reset, tcl_findLibrary, parray, tcl_endOfWord, tcl_startOfNextWord, tcl_startOfPreviousWord, tcl_wordBreakAfter, tcl_wordBreakBefore \- standard library of Tcl procedures
.SH SYNOPSIS
.nf

Used by \fBunknown\fR to record the command(s) for which it is
searching.
It is used to detect errors where \fBunknown\fR recurses on itself
infinitely.
The variable is unset before \fBunknown\fR returns.

.SH "SEE ALSO"
info(n), re_syntax(n)

.SH KEYWORDS
auto-exec, auto-load, library, unknown, word, whitespace 

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: lindex.n,v 1.4.2.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH lindex n 8.2 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
lindex \- Retrieve an element from a list

If \fIindex\fR is negative or greater than or equal to the number
of elements in \fIvalue\fR, then an empty
string is returned.
If \fIindex\fR has the value \fBend\fR, it refers to the last element
in the list, and \fBend\-\fIinteger\fR refers to the last element in
the list minus the specified integer offset.

.SH "SEE ALSO"
list(n), lappend(n), linsert(n), llength(n), lsearch(n), lsort(n),
lrange(n), lreplace(n)

.SH KEYWORDS
element, index, list

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: linsert.n,v 1.3.2.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH linsert n 8.2 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
linsert \- Insert elements into a list

the new list.  If \fIindex\fR is less than or equal to zero, then the new
elements are inserted at the beginning of the list.  If \fIindex\fR has the
value \fBend\fR, or if it is greater than or equal to the number of
elements in the list, then the new elements are appended to the list.
\fBend\-\fIinteger\fR refers to the last element in the list minus the
specified integer offset.

.SH "SEE ALSO"
list(n), lappend(n), llength(n)

.SH KEYWORDS
element, insert, list

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: list.n,v 1.2.18.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH list n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
list \- Create a list

\fBa b {c d e} {f {g h}}\fR
.CE
while \fBconcat\fR with the same arguments will return
.CS
\fBa b c d e f {g h}\fR
.CE

.SH "SEE ALSO"
lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), lsort(n),
lrange(n), lreplace(n)

.SH KEYWORDS
element, list

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: llength.n,v 1.2.18.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH llength n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
llength \- Count the number of elements in a list
.SH SYNOPSIS
\fBllength \fIlist\fR
.BE

.SH DESCRIPTION
.PP
Treats \fIlist\fR as a list and returns a decimal string giving
the number of elements in it.

.SH "SEE ALSO"
list(n), lindex(n), lrange(n)

.SH KEYWORDS
element, list, length

'\"
'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: load.n,v 1.5.2.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH load n 7.5 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
load \- Load machine code and initialize new commands.

.PP
If the same file is \fBload\fRed by different \fIfileName\fRs, it will
be loaded into the process's address space multiple times.  The
behavior of this varies from system to system (some systems may
detect the redundant loads, others may not).

.SH "SEE ALSO"
\fBinfo sharedlibextension\fR, Tcl_StaticPackage(3), safe(n)

.SH KEYWORDS
binary code, loading, safe interpreter, shared library

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: lrange.n,v 1.2.18.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH lrange n 7.4 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
lrange \- Return one or more adjacent elements from a list

If \fIfirst\fR is greater than \fIlast\fR then an empty string
is returned.
Note: ``\fBlrange \fIlist first first\fR'' does not always produce the
same result as ``\fBlindex \fIlist first\fR'' (although it often does
for simple fields that aren't enclosed in braces); it does, however,
produce exactly the same results as ``\fBlist [lindex \fIlist first\fB]\fR''

.SH "SEE ALSO"
lappend(n), lindex(n), linsert(n), list(n), llength(n), lreplace(n)

.SH KEYWORDS
element, list, range, sublist

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: lreplace.n,v 1.4.2.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH lreplace n 7.4 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
lreplace \- Replace elements in a list with new elements

The \fIelement\fR arguments specify zero or more new arguments to
be added to the list in place of those that were deleted.
Each \fIelement\fR argument will become a separate element of
the list.  If no \fIelement\fR arguments are specified, then the elements
between \fIfirst\fR and \fIlast\fR are simply deleted.  If \fIlist\fR
is empty, any \fIelement\fR arguments are added to the end of the list.

.SH "SEE ALSO"
lappend(n), lindex(n), linsert(n), list(n), llength(n), lrange(n),
lsearch(n), lsort(n)

.SH KEYWORDS
element, list, replace

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\" 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: lsort.n,v 1.5.2.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH lsort n 8.3 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
lsort \- Sort the elements of a list

.CS
lsort -integer -index 1 {{First 24} {Second 18} {Third 30}}
.CE
returns \fB{Second 18} {First 24} {Third 30}\fR.
This option is much more efficient than using \fB\-command\fR
to achieve the same effect.
.RE

.TP 20
\fB\-unique\fR
If this option is specified, then only the last set of duplicate
elements found in the list will be retained.  Note that duplicates are
determined relative to the comparison used in the sort.  Thus if 
\fI-index 0\fR is used, \fB{1 a}\fR and \fB{1 b}\fR would be
considered duplicates and only the second element, \fB{1 b}\fR, would
be retained.

.SH "NOTES"
.PP
The options to \fBlsort\fR only control what sort of comparison is
used, and do not necessarily constrain what the values themselves
actually are.  This distinction is only noticeable when the list to be
sorted has fewer than two elements.
.PP
The \fBlsort\fR command is reentrant, meaning it is safe to use as
part of the implementation of a command used in the \fB\-command\fR
option.

.SH "EXAMPLES"

.PP
Sorting a list using ASCII sorting:
.CS
% lsort {a10 B2 b1 a1 a2}
B2 a1 a10 a2 b1
.CE

.PP
Sorting a list using Dictionary sorting:
.CS
% lsort -dictionary {a10 B2 b1 a1 a2}
a1 a2 a10 b1 B2
.CE

.PP
Sorting lists of integers:
.CS
% lsort -integer {5 3 1 2 11 4}
1 2 3 4 5 11
% lsort -integer {1 2 0x5 7 0 4 -1}
-1 0 1 2 4 0x5 7
.CE

.PP
Sorting lists of floating-point numbers:
.CS
% lsort -real {5 3 1 2 11 4}
1 2 3 4 5 11
% lsort -real {.5 0.07e1 0.4 6e-1}
0.4 .5 6e-1 0.07e1
.CE

.PP
Sorting using indices:
.CS
% # Note the space character before the c
% lsort {{a 5} { c 3} {b 4} {e 1} {d 2}}
{ c 3} {a 5} {b 4} {d 2} {e 1}
% lsort -index 0 {{a 5} { c 3} {b 4} {e 1} {d 2}}
{a 5} {b 4} { c 3} {d 2} {e 1}
% lsort -index 1 {{a 5} { c 3} {b 4} {e 1} {d 2}}
{e 1} {d 2} { c 3} {b 4} {a 5}
.CE

.PP
Stripping duplicate values using sorting:
.CS
% lsort -unique {a b c a b c a b c}
a b c
.CE

.PP
More complex sorting using a comparison function:
.CS
% proc compare {a b} {
    set a0 [lindex $a 0]
    set b0 [lindex $b 0]
    if {$a0 < $b0} {
        return -1
    } elseif {$a0 > $b0} {
        return 1
    }
    return [string compare [lindex $a 1] [lindex $b 1]]
}
% lsort -command compare \\
        {{3 apple} {0x2 carrot} {1 dingo} {2 banana}}
{1 dingo} {2 banana} {0x2 carrot} {3 apple}
.CE

.SH "SEE ALSO"
lappend(n), lindex(n), linsert(n), list(n), llength(n), lrange(n),
lreplace(n), lsearch(n)

.SH KEYWORDS
element, list, order, sort

'\"	option's name as specified in the class command, dbName gives
'\"	the option's name in the option database, and dbClass gives
'\"	the option's class in the option database.
'\"
'\" .UL arg1 arg2
'\"	Print arg1 underlined, then print arg2 normally.
'\"
'\" RCS: @(#) $Id: man.macros,v 1.3.12.1 2001/04/03 22:06:43 hobbs Exp $
'\"
'\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
'\"	# Start an argument description
.de AP

.sp
..
'\"	# SO - start of list of standard options
.de SO
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
'\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP

'\"
'\" Copyright (c) 1992-1999 by Karl Lehenbauer and Mark Diekhans
'\" Copyright (c) 2000 by Scriptics Corporation.
'\" All rights reserved.
'\" 
'\" RCS: @(#) $Id: memory.n,v 1.2.2.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH memory n 8.1 Tcl "Tcl Built-In Commands"
.BS
.SH NAME
memory \- Control Tcl memory debugging capabilities.
.SH SYNOPSIS

Write a list of all currently allocated memory to the specified file.

.SH "SEE ALSO"
ckalloc, ckfree, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory, TCL_MEM_DEBUG

.SH KEYWORDS
memory, debug

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: open.n,v 1.9.2.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH open n 7.6 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
open \- Open a file-based or command pipeline channel

\fBTRUNC\fR
If the file exists it is truncated to zero length.
.PP
If a new file is created as part of opening it, \fIpermissions\fR
(an integer) is used to set the permissions for the new file in
conjunction with the process's file mode creation mask.
\fIPermissions\fR defaults to 0666.
.PP
'\" Not versioned as advice applies to all recent versions of Tcl.
'\" Prior to that, Tcl didn't really support binary files anyway...
.VS
Note that if you are going to be reading or writing binary data from
the channel created by this command, you should use the
\fBfconfigure\fR command to change the \fB-translation\fR option of
the channel to \fBbinary\fR before transferring any binary data.  This
is in contrast to the ``b'' character passed as part of the equivalent
of the \fIaccess\fR parameter to some versions of the C library
\fIfopen()\fR function.
.VE
.SH "COMMAND PIPELINES"
.PP
If the first character of \fIfileName\fR is ``|'' then the
remaining characters of \fIfileName\fR are treated as a list of arguments
that describe a command pipeline to invoke, in the same style as the
arguments for \fBexec\fR.
In this case, the channel identifier returned by \fBopen\fR may be used

same time.  If the command pipeline is started from a script, so that Tcl is
not accessing the console, or if the command pipeline does not use standard
input, but is redirected from a file, then the above problem does not occur.  
.LP
See the PORTABILITY ISSUES section of the \fBexec\fR command for additional
information not specific to command pipelines about executing
applications on the various platforms

.SH "SEE ALSO"
file(n), close(n), filename(n), fconfigure(n), gets(n), read(n),
puts(n), exec(n), fopen(1)

.SH KEYWORDS
access mode, append, create, file, non-blocking, open, permissions,
pipeline, process, serial

'\"
'\" Copyright (c) 1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: package.n,v 1.3.14.2 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH package n 7.5 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
package \- Facilities for package loading and version control
.SH SYNOPSIS
.nf
\fBpackage forget ?\fIpackage package ...\fR?
\fBpackage ifneeded \fIpackage version\fR ?\fIscript\fR?
\fBpackage names\fR
\fBpackage present \fR?\fB\-exact\fR? \fIpackage \fR?\fIversion\fR?
\fBpackage provide \fIpackage \fR?\fIversion\fR?
\fBpackage require \fR?\fB\-exact\fR? \fIpackage \fR?\fIversion\fR?
\fBpackage unknown \fR?\fIcommand\fR?
\fBpackage vcompare \fIversion1 version2\fR

Typically, only the \fBpackage require\fR and \fBpackage provide\fR
commands are invoked in normal Tcl scripts;  the other commands are used
primarily by system scripts that maintain the package database.
.PP
The behavior of the \fBpackage\fR command is determined by its first argument.
The following forms are permitted:
.TP
\fBpackage forget ?\fIpackage package ...\fR?
Removes all information about each specified package from this interpreter,
including information provided by both \fBpackage ifneeded\fR and
\fBpackage provide\fR.
.TP
\fBpackage ifneeded \fIpackage version\fR ?\fIscript\fR?
This command typically appears only in system configuration
scripts to set up the package database.
It indicates that a particular version of

The recommended way to use packages in Tcl is to invoke \fBpackage require\fR
and \fBpackage provide\fR commands in scripts, and use the procedure
\fBpkg_mkIndex\fR to create package index files.
Once you've done this, packages will be loaded automatically
in response to \fBpackage require\fR commands.
See the documentation for \fBpkg_mkIndex\fR for details.

.SH "SEE ALSO"
msgcat(n), packagens(n), pkgMkIndex(n)

.SH KEYWORDS
package, version

'\"
'\" Copyright (c) 1998-2000 by Scriptics Corporation.
'\" All rights reserved.
'\" 
'\" RCS: @(#) $Id: packagens.n,v 1.2.2.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH pkg::create n 8.3 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
pkg::create \- Construct an appropriate \fBpackage ifneeded\fR

\fB\-source\fR\0\fIfilespec\fR
This parameter is similar to the \fB\-load\fR parameter, except that it
specifies a Tcl library that must be loaded with the
\fBsource\fR command.  Any number of \fB\-source\fR parameters may be
specified.
.PP
At least one \fB\-load\fR or \fB\-source\fR paramter must be given.

.SH "SEE ALSO"
package(n)

.SH KEYWORDS
auto-load, index, package, version

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: pid.n,v 1.2.18.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH pid n 7.0 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
pid \- Retrieve process id(s)

in order.
The list will be empty if \fIfileId\fR refers to an open file
that isn't a process pipeline.
If no \fIfileId\fR argument is given then \fBpid\fR returns the process
identifier of the current process.
All process identifiers are returned as decimal strings.

.SH "SEE ALSO"
exec(n), open(n)

.SH KEYWORDS
file, pipeline, process identifier

'\"
'\" Copyright (c) 1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: pkgMkIndex.n,v 1.9.2.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH pkg_mkIndex n 8.3 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
pkg_mkIndex \- Build an index for automatic loading of packages

If you have a package that is split across scripts and a binary file,
then you should avoid the \fB\-load\fP flag. The problem is that
if you load a package before computing the index it masks any
other files that provide part of the same package.
If you must use \fB\-load\fP,
then you must specify the scripts first; otherwise the package loaded from
the binary file may mask the package defined by the scripts.

.SH "SEE ALSO"
package(n)

.SH KEYWORDS
auto-load, index, package, version

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: proc.n,v 1.2.18.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH proc n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
proc \- Create a Tcl procedure

invoked, the procedure's return value is the value specified in a
\fBreturn\fR command.  If the procedure doesn't execute an explicit
\fBreturn\fR, then its return value is the value of the last command
executed in the procedure's body.
If an error occurs while executing the procedure
body, then the procedure-as-a-whole will return that same error.

.SH "SEE ALSO"
info(n), unknown(n)

.SH KEYWORDS
argument, procedure

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: puts.n,v 1.3.12.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH puts n 7.5 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
puts \- Write to a channel

large amount of memory.
To avoid wasting memory, nonblocking I/O should normally
be used in an event-driven fashion with the \fBfileevent\fR command
(don't invoke \fBputs\fR unless you have recently been notified
via a file event that the channel is ready for more output data).

.SH "SEE ALSO"
file(n), fileevent(n)

.SH KEYWORDS
channel, newline, output, write

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: pwd.n,v 1.2.18.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH pwd n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
pwd \- Return the current working directory
.SH SYNOPSIS
\fBpwd\fR
.BE

.SH DESCRIPTION
.PP
Returns the path name of the current working directory.

.SH "SEE ALSO"
file(n), cd(n), glob(n), filename(n)

.SH KEYWORDS
working directory

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: read.n,v 1.4.12.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH read n 8.1 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
read \- Read from a channel

\fBRead\fR translates end-of-line sequences in the input into
newline characters according to the \fB\-translation\fR option
for the channel.
See the \fBfconfigure\fR manual entry for a discussion on ways in
which \fBfconfigure\fR will alter input.

.SH "SEE ALSO"
file(n), eof(n), fblocked(n), fconfigure(n)

.SH KEYWORDS
blocking, channel, end of line, end of file, nonblocking, read, translation, encoding

'\"
'\" 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.
'\" 
'\" RCS: @(#) $Id: regexp.n,v 1.9.2.1 2001/04/03 22:06:43 hobbs Exp $
'\" 
.so man.macros
.TH regexp n 8.3 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
regexp \- Match a regular expression against a string

subexpressions within \fIexp\fR, or if a particular subexpression
in \fIexp\fR doesn't match the string (e.g. because it was in a
portion of the expression that wasn't matched), then the corresponding
\fIsubMatchVar\fR will be set to ``\fB\-1 \-1\fR'' if \fB\-indices\fR
has been specified or to an empty string otherwise.

.SH "SEE ALSO"
re_syntax(n), regsub(n)

.SH KEYWORDS
match, regular expression, string

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\" Copyright (c) 2000 Scriptics Corporation.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: regsub.n,v 1.4.2.2 2001/04/03 22:06:44 hobbs Exp $
'\" 
.so man.macros
.TH regsub n 8.3 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
regsub \- Perform substitutions based on regular expression pattern matching

All ranges in \fIstring\fR that match \fIexp\fR are found and
substitution is performed for each of these ranges.
Without this switch only the first
matching range is found and substituted.
If \fB\-all\fR is specified, then ``&'' and ``\e\fIn\fR''
sequences are handled for each substitution using the information
from the corresponding match.
.TP 15
\fB\-expanded\fR
Enables use of the expanded regular expression syntax where
whitespace and comments are ignored.  This is the same as specifying
the \fB(?x)\fR embedded option (see METASYNTAX, below).
.TP 15
\fB\-line\fR
Enables newline-sensitive matching.  By default, newline is a
completely ordinary character with no special meaning.  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.  This flag is equivalent to
specifying both \fB\-linestop\fR and \fB\-lineanchor\fR, or the
\fB(?n)\fR embedded option (see METASYNTAX, below).
.TP 15
\fB\-linestop\fR
Changes the behavior of `[^' bracket expressions and `.' so that they
stop at newlines.  This is the same as specifying the \fB(?p)\fR
embedded option (see METASYNTAX, below).
.TP 15
\fB\-lineanchor\fR
Changes the behavior of `^' and `$' (the ``anchors'') so they match the
beginning and end of a line respectively.  This is the same as
specifying the \fB(?w)\fR embedded option (see METASYNTAX, below).
.TP 10
\fB\-nocase\fR
Upper-case characters in \fIstring\fR will be converted to lower-case
before matching against \fIexp\fR;  however, substitutions specified
by \fIsubSpec\fR use the original unconverted form of \fIstring\fR.
.VS 8.3
.TP 10
\fB\-start\fR \fIindex\fR
Specifies a character index offset into the string to start
matching the regular expression at.  When using this switch, `^'
will not match the beginning of the line, and \\A will still
match the start of the string at \fIindex\fR.


\fIindex\fR will be constrained to the bounds of the input string.
.VE 8.3
.TP 10
\fB\-\|\-\fR
Marks the end of switches.  The argument following this one will
be treated as \fIexp\fR even if it starts with a \fB\-\fR.
.PP
The command returns a count of the number of matching ranges that
were found and replaced.
See the manual entry for \fBregexp\fR for details on the interpretation
of regular expressions.

.SH "SEE ALSO"
regexp(n), re_syntax(n)

.SH KEYWORDS
match, pattern, regular expression, substitute

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: rename.n,v 1.2.18.1 2001/04/03 22:06:44 hobbs Exp $
'\" 
.so man.macros
.TH rename n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
rename \- Rename or delete a command

If \fInewName\fR is an empty string then \fIoldName\fR is deleted.
\fIoldName\fR and \fInewName\fR may include namespace qualifiers
(names of containing namespaces).
If a command is renamed into a different namespace,
future invocations of it will execute in the new namespace.
The \fBrename\fR command returns an empty string as result.

.SH "SEE ALSO"
namespace(n), proc(n)

.SH KEYWORDS
command, delete, namespace, rename

'\"
'\" 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: resource.n,v 1.5.2.1 2001/04/03 22:06:44 hobbs Exp $
'\" 
.so man.macros
.TH resource n 8.0 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
resource \- Manipulate Macintosh resources

the \fBresource list\fR command will return names if they exist or
numbers if the name is NULL.

.SH "PORTABILITY ISSUES"
The resource command is only available on Macintosh.

.SH "SEE ALSO"
open(n)

.SH KEYWORDS
open, resource

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: return.n,v 1.2.18.1 2001/04/03 22:06:44 hobbs Exp $
'\" 
.so man.macros
.TH return n 7.0 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
return \- Return from a procedure

the procedure.
.PP
If the \fB\-errorcode\fR option is specified then \fIcode\fR provides
a value for the \fBerrorCode\fR variable.
If the option is not specified then \fBerrorCode\fR will
default to \fBNONE\fR.

.SH "SEE ALSO"
break(n), continue(n), error(n), proc(n)

.SH KEYWORDS
break, continue, error, procedure, return

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\" Copyright (c) 2000 Scriptics Corporation.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: scan.n,v 1.4.2.3 2001/04/03 22:06:44 hobbs Exp $
'\" 
.so man.macros
.TH scan n 8.3 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
scan \- Parse string using conversion specifiers in the style of sscanf
.SH SYNOPSIS
\fBscan \fIstring format \fR?\fIvarName varName ...\fR?
.BE

.SH INTRODUCTION
.PP
This command parses fields from an input string in the same fashion as the
ANSI C \fBsscanf\fR procedure and returns a count of the number of
conversions performed, or -1 if the end of the input string is reached

zero).
Otherwise, if it isn't a \fB%\fR character then it 
must match the next character of \fIstring\fR.
When a \fB%\fR is encountered in \fIformat\fR, it indicates
the start of a conversion specifier.
A conversion specifier contains up to four fields after the \fB%\fR:
a \fB*\fR, which indicates that the converted value is to be discarded 

instead of assigned to a variable; a XPG3 position specifier; a number

indicating a maximum field width; and a conversion character.
All of these fields are optional except for the conversion character.
The fields that are present must appear in the order given above.
.PP
When \fBscan\fR finds a conversion specifier in \fIformat\fR, it
first skips any white-space characters in \fIstring\fR (unless the
specifier is \fB[\fR or \fBc\fR).
Then it converts the next input characters according to the 
conversion specifier and stores the result in the variable given
by the next argument to \fBscan\fR.

.PP
If the \fB%\fR is followed by a decimal number and a \fB$\fR, as in
``\fB%2$d\fR'', then the variable to use is not taken from the next
sequential argument.  Instead, it is taken from the argument indicated
by the number, where 1 corresponds to the first \fIvarName\fR.  If
there are any positional specifiers in \fIformat\fR then all of the
specifiers must be positional.  Every \fIvarName\fR on the argument
list must correspond to exactly one conversion specifier or an error
is generated, or in the inline case, any position can be specified
at most once and the empty positions will be filled in with empty strings.

.PP
The following conversion characters are supported:
.TP 10
\fBd\fR
The input field must be a decimal integer.
It is read in and the value is stored in the variable as a decimal string.
.TP 10
\fBo\fR
The input field must be an octal integer. It is read in and the 
value is stored in the variable as a decimal string.
.VS 8.4
If the value exceeds MAX_INT (017777777777 on platforms using 32-bit
integers), it will be truncated to a signed integer.  Hence, 037777777777
will appear as -1 on a 32-bit machine.
.VE 8.4
.TP 10
\fBx\fR
The input field must be a hexadecimal integer. It is read in 
and the value is stored in the variable as a decimal string.
.VS 8.4
If the value exceeds MAX_INT (0x7FFFFFFF on platforms using 32-bit
integers), it will be truncated to a signed integer.  Hence, 0xFFFFFFFF
will appear as -1 on a 32-bit machine.
.VE 8.4
.TP 10
\fBu\fR
The input field must be a decimal integer.  The value is stored in the
variable as an unsigned decimal integer string.
.TP 10
\fBi\fR 
The input field must be an integer.  The base (i.e. decimal, octal, or
hexadecimal) is determined in the same fashion as described in
\fBexpr\fR.  The value is stored in the variable as a decimal string.

.TP 10
\fBc\fR
A single character is read in and its binary value is stored in 
the variable as a decimal string.
Initial white space is not skipped in this case, so the input
field may be a white-space character.
This conversion is different from the ANSI standard in that the

\fB[\fIchars\fB]\fR
The input field consists of any number of characters in 
\fIchars\fR.
The matching string is stored in the variable.
If the first character between the brackets is a \fB]\fR then
it is treated as part of \fIchars\fR rather than the closing
bracket for the set.

If \fIchars\fR
contains a sequence of the form \fIa\fB\-\fIb\fR then any
character between \fIa\fR and \fIb\fR (inclusive) will match.
If the first or last character between the brackets is a \fB\-\fR, then
it is treated as part of \fIchars\fR rather than indicating a range.

.TP 10
\fB[^\fIchars\fB]\fR
The input field consists of any number of characters not in 
\fIchars\fR.
The matching string is stored in the variable.
If the character immediately following the \fB^\fR is a \fB]\fR then it is 
treated as part of the set rather than the closing bracket for 
the set.

If \fIchars\fR
contains a sequence of the form \fIa\fB\-\fIb\fR then any
character between \fIa\fR and \fIb\fR (inclusive) will be excluded
from the set.
If the first or last character between the brackets is a \fB\-\fR, then
it is treated as part of \fIchars\fR rather than indicating a range.
.TP 10
\fBn\fR
No input is consumed from the input string.  Instead, the total number
of chacters scanned from the input string so far is stored in the variable.

.LP
The number of characters read from the input for a conversion is the
largest number that makes sense for that particular conversion (e.g.
as many decimal digits as possible for \fB%d\fR, as 
many octal digits as possible for \fB%o\fR, and so on).
The input field for a given conversion terminates either when a
white-space character is encountered or when the maximum field 
width has been reached, whichever comes first.
If a \fB*\fR is present in the conversion specifier 
then no variable is assigned and the next scan argument is not consumed.

.SH "DIFFERENCES FROM ANSI SSCANF"
.PP
The behavior of the \fBscan\fR command is the same as the behavior of
the ANSI C \fBsscanf\fR procedure except for the following differences:

.IP [1]
\fB%p\fR conversion specifier is not currently supported.

.IP [2]
For \fB%c\fR conversions a single character value is
converted to a decimal string, which is then assigned to the
corresponding \fIvarName\fR;
no field width may be specified for this conversion.
.IP [3]
The \fBl\fR, \fBh\fR, and \fBL\fR modifiers are ignored;  integer
values are always converted as if there were no modifier present
and real values are always converted as if the \fBl\fR modifier
were present (i.e. type \fBdouble\fR is used for the internal
representation).

.IP [4]
.VS 8.3
If the end of the input string is reached before any conversions have been
performed and no variables are given, and empty string is returned.
.VE 8.3

.SH "SEE ALSO"
format(n), sscanf(3)

.SH KEYWORDS
conversion specifier, parse, scan

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: seek.n,v 1.3.12.1 2001/04/03 22:06:44 hobbs Exp $
'\" 
.so man.macros
.TH seek n 8.1 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
seek \- Change the access position for an open channel

.PP
.VS 8.1
Note that \fIoffset\fR values are byte offsets, not character
offsets.  Both \fBseek\fR and \fBtell\fR operate in terms of bytes,
not characters, unlike \fBread\fR.
.VE 8.1

.SH "SEE ALSO"
file(n), open(n), close(n), gets(n), tell(n)
 
.SH KEYWORDS
access position, file, seek

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: set.n,v 1.2.18.1 2001/04/03 22:06:44 hobbs Exp $
'\" 
.so man.macros
.TH set n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
set \- Read and write variables

(global variable if the current namespace is the global namespace).
If a procedure is active, then \fIvarName\fR refers to a parameter
or local variable of the procedure unless the \fBglobal\fR command
was invoked to declare \fIvarName\fR to be global,
or unless a \fBvariable\fR command
was invoked to declare \fIvarName\fR to be a namespace variable.

.SH "SEE ALSO"
expr(n), proc(n), trace(n), unset(n)

.SH KEYWORDS
read, write, variable

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: split.n,v 1.2.18.1 2001/04/03 22:06:44 hobbs Exp $
'\" 
.so man.macros
.TH split n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
split \- Split a string into a proper Tcl list

.CE
returns \fB"comp unix misc"\fR and
.CS
\fBsplit "Hello world" {}\fR
.CE
returns \fB"H e l l o { } w o r l d"\fR.

.SH "SEE ALSO"
join(n), list(n), string(n)

.SH KEYWORDS
list, split, string

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: string.n,v 1.13.2.1 2001/04/03 22:06:44 hobbs Exp $
'\" 
.so man.macros
.TH string n 8.1 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
string \- Manipulate strings

character \fIcharIndex\fR of \fIstring\fR.  \fIcharIndex\fR may be
specified as for the \fBindex\fR method.  A word is considered to be any
contiguous range of alphanumeric (Unicode letters or decimal digits)
or underscore (Unicode connector punctuation) characters, or any
single character other than these.
.VE 8.1

.SH "SEE ALSO"
expr(n), list(n)

.SH KEYWORDS
case conversion, compare, index, match, pattern, string, word, equal, ctype

'\"
'\" Copyright (c) 1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: subst.n,v 1.2.18.1 2001/04/03 22:06:44 hobbs Exp $
'\" 
.so man.macros
.TH subst n 7.4 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
subst \- Perform backslash, command, and variable substitutions

give any special treatment to double quotes or curly braces.  For
example, the script
.CS
\fBset a 44
subst {xyz {$a}}\fR
.CE
returns ``\fBxyz {44}\fR'', not ``\fBxyz {$a}\fR''.

.SH "SEE ALSO"
eval(n)

.SH KEYWORDS
backslash substitution, command substitution, variable substitution

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: switch.n,v 1.4.2.1 2001/04/03 22:06:44 hobbs Exp $
'\" 
.so man.macros
.TH switch n 7.0 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
switch \- Evaluate one of several scripts, depending on a given value

		{format 2}
	default
		{format 3}
}\fR
.CE
will return \fB3\fR.

.SH "SEE ALSO"
for(n), if(n), regexp(n)

.SH KEYWORDS
switch, match, regular expression

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: tclvars.n,v 1.7.2.1 2001/04/03 22:06:44 hobbs Exp $
'\" 
.so man.macros
.TH tclvars n 8.0 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
tclvars \- Variables used by Tcl

When an interpreter is created Tcl initializes this variable to
hold the version number for this version of Tcl in the form \fIx.y\fR.
Changes to \fIx\fR represent major changes with probable
incompatibilities and changes to \fIy\fR represent small enhancements and
bug fixes that retain backward compatibility.
The value of this variable is returned by the \fBinfo tclversion\fR
command.

.SH "SEE ALSO"
eval(n)

.SH KEYWORDS
arithmetic, bytecode, compiler, error, environment, POSIX, precision, subprocess, variables

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: tell.n,v 1.3.12.1 2001/04/03 22:06:44 hobbs Exp $
'\" 
.so man.macros
.TH tell n 8.1 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
tell \- Return current access position for an open channel

\fIchannelId\fR.  This value returned is a byte offset that can be passed to
\fBseek\fR in order to set the channel to a particular position.  Note
that this value is in terms of bytes, not characters like \fBread\fR.
.VE 8.1
The value returned is -1 for channels that do not support
seeking.

.SH "SEE ALSO"
file(n), open(n), close(n), gets(n), seek(n)

.SH KEYWORDS
access position, channel, seeking

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: time.n,v 1.2.18.1 2001/04/03 22:06:44 hobbs Exp $
'\" 
.so man.macros
.TH time n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
time \- Time the execution of a script

specified).  It will then return a string of the form
.CS
\fB503 microseconds per iteration\fR
.CE
which indicates the average amount of time required per iteration,
in microseconds.
Time is measured in elapsed time, not CPU time.

.SH "SEE ALSO"
clock(n)

.SH KEYWORDS
script, time

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: unknown.n,v 1.2.18.1 2001/04/03 22:06:44 hobbs Exp $
'\" 
.so man.macros
.TH unknown n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
unknown \- Handle attempts to use non-existent commands

step is skipped.
If the global variable \fBauto_noexec\fR is defined then the
auto-exec step is skipped.
Under normal circumstances the return value from \fBunknown\fR
is the return value from the command that was eventually
executed.

.SH "SEE ALSO"
info(n), proc(n)

.SH KEYWORDS
error, non-existent command

'\"
'\" Copyright (c) 1990-1992 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: update.n,v 1.3.2.1 2001/04/03 22:06:44 hobbs Exp $
'\" 
.so man.macros
.TH update n 7.5 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
update \- Process pending events and idle callbacks

.PP
The \fBupdate\fR command with no options is useful in scripts where
you are performing a long-running computation but you still want
the application to respond to events such as user interactions;  if
you occasionally call \fBupdate\fR then user input will be processed
during the next call to \fBupdate\fR.

.SH "SEE ALSO"
after(n), bgerror(n)

.SH KEYWORDS
event, flush, handler, idle, update

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: uplevel.n,v 1.2.18.1 2001/04/03 22:06:44 hobbs Exp $
'\" 
.so man.macros
.TH uplevel n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
uplevel \- Execute a script in a different stack frame

For example, \fBinfo level 1\fR will return a list
describing a command that is either
the outermost procedure call or the outermost \fBnamespace eval\fR command.
Also, \fBuplevel #0\fR evaluates a script
at top-level in the outermost namespace (the global namespace).

.SH "SEE ALSO"
namespace(n), upvar(n)

.SH KEYWORDS
context, level, namespace, stack frame, variables

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: upvar.n,v 1.3.2.1 2001/04/03 22:06:44 hobbs Exp $
'\" 
.so man.macros
.TH upvar n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
upvar \- Create link to variable in a different stack frame

traces set for the entire array will not be invoked when \fImyVar\fR
is accessed (but traces on the particular element will still be
invoked).  In particular, if the array is \fBenv\fR, then changes
made to \fImyVar\fR will not be passed to subprocesses correctly.
.VE

.SH "SEE ALSO"
global(n), namespace(n), uplevel(n), variable(n)

.SH KEYWORDS
context, frame, global, level, namespace, procedure, variable

'\"
'\" Copyright (c) 1993-1997 Bell Labs Innovations for Lucent Technologies
'\" 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: variable.n,v 1.3.2.1 2001/04/03 22:06:44 hobbs Exp $
'\" 
.so man.macros
.TH variable n 8.0 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
variable \- create and initialize a namespace variable

If \fIname\fR includes any namespace qualifiers,
the variable is created in the specified namespace.  If the variable
is not defined, it will be visible to the \fBnamespace which\fR
command, but not to the \fBinfo exists\fR command.
.PP
If the \fBvariable\fR command is executed inside a Tcl procedure,
it creates local variables
linked to the corresponding namespace variables (and therefore these
variables are listed by \fBinfo locals\fR.)
In this way the \fBvariable\fR command resembles the \fBglobal\fR command,
although the \fBglobal\fR command
only links to variables in the global namespace.
If any \fIvalue\fRs are given,
they are used to modify the values of the associated namespace variables.
If a namespace variable does not exist,
it is created and optionally initialized.
.PP
A \fIname\fR argument cannot reference an element within an array.
Instead, \fIname\fR should reference the entire array,
and the initialization \fIvalue\fR should be left off.
After the variable has been declared,
elements within the array can be set using ordinary
\fBset\fR or \fBarray\fR commands.

.SH "SEE ALSO"
global(n), namespace(n), upvar(n)

.SH KEYWORDS
global, namespace, procedure, variable

'\"
'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: vwait.n,v 1.3.2.1 2001/04/03 22:06:44 hobbs Exp $
'\" 
.so man.macros
.TH vwait n 8.0 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
vwait \- Process events until a variable is written

after \fIvarName\fR is set.  This can happen if the event handler
that sets \fIvarName\fR does not complete immediately.  For example,
if an event handler sets \fIvarName\fR and then itself calls
\fBvwait\fR to wait for a different variable, then it may not return
for a long time.  During this time the top-level \fBvwait\fR is
blocked waiting for the event handler to complete, so it cannot
return either.

.SH "SEE ALSO"
global(n)

.SH KEYWORDS
event, variable, wait

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: while.n,v 1.2.18.1 2001/04/03 22:06:44 hobbs Exp $
'\" 
.so man.macros
.TH while n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
while \- Execute script repeatedly as long as a condition is met

set x 0
while {$x<10} {
	puts "x is $x"
	incr x
}
.CE

.SH "SEE ALSO"
break(n), continue(n), for(n), foreach(n)

.SH KEYWORDS
boolean value, loop, test, while

# tcl.decls --
#
#	This file contains the declarations for all supported public
#	functions that are exported by the Tcl library via the stubs table.
#	This file is used to generate the tclDecls.h, tclPlatDecls.h,
#	tclStub.c, and tclPlatStub.c files.
#	
#
# Copyright (c) 1998-1999 by 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: tcl.decls,v 1.33.2.1 2000/07/27 01:39:14 hobbs Exp $

library tcl

# Define the tcl interface with several sub interfaces:
#     tclPlat	 - platform specific public
#     tclInt	 - generic private
#     tclPlatInt - platform specific private

declare 281 generic {
    Tcl_Channel Tcl_StackChannel(Tcl_Interp *interp, \
	    Tcl_ChannelType *typePtr, ClientData instanceData, \
	    int mask, Tcl_Channel prevChan)
}
declare 282 generic {
    int Tcl_UnstackChannel(Tcl_Interp *interp, Tcl_Channel chan)
}
declare 283 generic {
    Tcl_Channel Tcl_GetStackedChannel(Tcl_Channel chan)
}
# Reserved for future use (8.0.x vs. 8.1)
#  declare 284 generic {
#  }

declare 392 generic {
    void Tcl_MutexFinalize (Tcl_Mutex *mutex)
}
declare 393 generic {
    int Tcl_CreateThread (Tcl_ThreadId *idPtr, Tcl_ThreadCreateProc proc, \
	    ClientData clientData, int stackSize, int flags)
}

declare 394 generic {
    int Tcl_ReadRaw (Tcl_Channel chan, char *dst, int bytesToRead)
}
declare 395 generic {
    int Tcl_WriteRaw (Tcl_Channel chan, char *src, int srcLen)
}
declare 396 generic {
    Tcl_Channel Tcl_GetTopChannel (Tcl_Channel chan)
}
declare 397 generic {
    int Tcl_ChannelBuffered (Tcl_Channel chan)
}
declare 398 generic {
    char * Tcl_ChannelName(Tcl_ChannelType *chanTypePtr)
}
declare 399 generic {
    Tcl_ChannelTypeVersion Tcl_ChannelVersion(Tcl_ChannelType *chanTypePtr)
}
declare 400 generic {
    Tcl_DriverBlockModeProc * Tcl_ChannelBlockModeProc(Tcl_ChannelType \
	    *chanTypePtr)
}
declare 401 generic {
    Tcl_DriverCloseProc * Tcl_ChannelCloseProc(Tcl_ChannelType *chanTypePtr)
}
declare 402 generic {
    Tcl_DriverClose2Proc * Tcl_ChannelClose2Proc(Tcl_ChannelType *chanTypePtr)
}
declare 403 generic {
    Tcl_DriverInputProc * Tcl_ChannelInputProc(Tcl_ChannelType *chanTypePtr)
}
declare 404 generic {
    Tcl_DriverOutputProc * Tcl_ChannelOutputProc(Tcl_ChannelType *chanTypePtr)
}
declare 405 generic {
    Tcl_DriverSeekProc * Tcl_ChannelSeekProc(Tcl_ChannelType *chanTypePtr)
}
declare 406 generic {
    Tcl_DriverSetOptionProc * Tcl_ChannelSetOptionProc(Tcl_ChannelType \
	    *chanTypePtr)
}
declare 407 generic {
    Tcl_DriverGetOptionProc * Tcl_ChannelGetOptionProc(Tcl_ChannelType \
	    *chanTypePtr)
}
declare 408 generic {
    Tcl_DriverWatchProc * Tcl_ChannelWatchProc(Tcl_ChannelType *chanTypePtr)
}
declare 409 generic {
    Tcl_DriverGetHandleProc * Tcl_ChannelGetHandleProc(Tcl_ChannelType \
	    *chanTypePtr)
}
declare 410 generic {
    Tcl_DriverFlushProc * Tcl_ChannelFlushProc(Tcl_ChannelType *chanTypePtr)
}
declare 411 generic {
    Tcl_DriverHandlerProc * Tcl_ChannelHandlerProc(Tcl_ChannelType \
	    *chanTypePtr)
}

##############################################################################

# Define the platform specific public Tcl interface.  These functions are
# only available on the designated platform.

interface tclPlat

 * Copyright (c) 1993-1996 Lucent Technologies.
 * Copyright (c) 1994-1998 Sun Microsystems, Inc.
 * Copyright (c) 1998-2000 by 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: tcl.h,v 1.70.2.3 2001/04/04 21:22:17 hobbs Exp $
 */

#ifndef _TCL
#define _TCL

/*
 * For C++ compilers, use extern "C"

 * tools/tcl.wse.in	(for windows installer)
 * tools/tclSplash.bmp	(not patchlevel)
 */

#define TCL_MAJOR_VERSION   8
#define TCL_MINOR_VERSION   3
#define TCL_RELEASE_LEVEL   TCL_FINAL_RELEASE
#define TCL_RELEASE_SERIAL  3

#define TCL_VERSION	    "8.3"
#define TCL_PATCH_LEVEL	    "8.3.3"

/*
 * The following definitions set up the proper options for Windows
 * compilers.  We use this method because there is no autoconf equivalent.
 */

#ifndef __WIN32__