From a850c17c374d03259483e799b09326d255e17487 Mon Sep 17 00:00:00 2001 From: Ian Roxborough Date: Sun, 9 Sep 2001 22:40:53 +0000 Subject: Tcl 8.3 upgrade --- tcl/ChangeLog | 4625 ++++++++++++++- tcl/Makefile.in | 9 +- tcl/README | 471 +- tcl/changes | 1317 ++++- tcl/compat/README | 1 + tcl/compat/getcwd.c | 47 + tcl/compat/stdlib.h | 2 +- tcl/compat/strftime.c | 15 +- tcl/compat/string.h | 4 + tcl/compat/waitpid.c | 12 +- tcl/configure | 38 +- tcl/configure.in | 10 +- tcl/cygtcl.m4 | 310 + tcl/doc/Access.3 | 71 + tcl/doc/AddErrInfo.3 | 37 +- tcl/doc/AppInit.3 | 2 +- tcl/doc/AssocData.3 | 2 +- tcl/doc/Async.3 | 14 +- tcl/doc/BackgdErr.3 | 2 +- tcl/doc/Backslash.3 | 28 +- tcl/doc/ByteArrObj.3 | 91 + tcl/doc/ChnlStack.3 | 90 + tcl/doc/CrtChannel.3 | 299 +- tcl/doc/CrtInterp.3 | 16 +- tcl/doc/CrtMathFnc.3 | 2 +- tcl/doc/CrtObjCmd.3 | 24 +- tcl/doc/CrtSlave.3 | 2 +- tcl/doc/DString.3 | 8 +- tcl/doc/DumpActiveMemory.3 | 68 + tcl/doc/Encoding.3 | 522 ++ tcl/doc/Eval.3 | 189 +- tcl/doc/Exit.3 | 45 +- tcl/doc/ExprLong.3 | 7 +- tcl/doc/FindExec.3 | 5 +- tcl/doc/GetCwd.3 | 54 + tcl/doc/GetHostName.3 | 29 + tcl/doc/GetIndex.3 | 34 +- tcl/doc/GetInt.3 | 3 +- tcl/doc/GetOpnFl.3 | 3 +- tcl/doc/GetVersion.3 | 49 + tcl/doc/Hash.3 | 2 +- tcl/doc/Init.3 | 37 + tcl/doc/InitStubs.3 | 91 + tcl/doc/Interp.3 | 4 +- tcl/doc/LinkVar.3 | 3 +- tcl/doc/ListObj.3 | 24 +- tcl/doc/Notifier.3 | 136 +- tcl/doc/Object.3 | 16 +- tcl/doc/OpenFileChnl.3 | 383 +- tcl/doc/OpenTcp.3 | 9 +- tcl/doc/ParseCmd.3 | 439 ++ tcl/doc/PkgRequire.3 | 47 +- tcl/doc/RecEvalObj.3 | 9 +- tcl/doc/RecordEval.3 | 3 +- tcl/doc/RegExp.3 | 253 +- tcl/doc/SaveResult.3 | 65 + tcl/doc/SetErrno.3 | 17 +- tcl/doc/SetRecLmt.3 | 2 +- tcl/doc/SetResult.3 | 19 +- tcl/doc/SetVar.3 | 209 +- tcl/doc/SourceRCFile.3 | 38 + tcl/doc/SplitList.3 | 23 +- tcl/doc/StaticPkg.3 | 14 +- tcl/doc/StrMatch.3 | 20 +- tcl/doc/StringObj.3 | 162 +- tcl/doc/TCL_MEM_DEBUG.3 | 81 + tcl/doc/Tcl.n | 66 +- tcl/doc/TclInitStubs.3 | 91 + tcl/doc/Thread.3 | 195 + tcl/doc/ToUpper.3 | 90 + tcl/doc/TraceVar.3 | 43 +- tcl/doc/Translate.3 | 11 +- tcl/doc/UpVar.3 | 4 +- tcl/doc/Utf.3 | 233 + tcl/doc/WrongNumArgs.3 | 3 +- tcl/doc/array.n | 15 +- tcl/doc/binary.n | 37 +- tcl/doc/catch.n | 56 +- tcl/doc/clock.n | 41 +- tcl/doc/dde.n | 135 + tcl/doc/encoding.n | 79 + tcl/doc/exec.n | 64 +- tcl/doc/expr.n | 97 +- tcl/doc/fconfigure.n | 193 +- tcl/doc/file.n | 75 +- tcl/doc/filename.n | 8 +- tcl/doc/format.n | 6 +- tcl/doc/glob.n | 89 +- tcl/doc/http.n | 184 +- tcl/doc/info.n | 4 +- tcl/doc/interp.n | 26 +- tcl/doc/library.n | 169 +- tcl/doc/lindex.n | 6 +- tcl/doc/linsert.n | 20 +- tcl/doc/load.n | 18 +- tcl/doc/lreplace.n | 34 +- tcl/doc/lsearch.n | 3 +- tcl/doc/lsort.n | 35 +- tcl/doc/man.macros | 2 +- tcl/doc/memory.n | 82 + tcl/doc/msgcat.n | 244 + tcl/doc/namespace.n | 61 +- tcl/doc/open.n | 44 +- tcl/doc/package.n | 12 +- tcl/doc/packagens.n | 53 + tcl/doc/pkgMkIndex.n | 81 +- tcl/doc/puts.n | 4 +- tcl/doc/re_syntax.n | 932 +++ tcl/doc/read.n | 34 +- tcl/doc/regexp.n | 177 +- tcl/doc/registry.n | 8 +- tcl/doc/regsub.n | 40 +- tcl/doc/resource.n | 12 +- tcl/doc/safe.n | 17 +- tcl/doc/scan.n | 103 +- tcl/doc/seek.n | 8 +- tcl/doc/socket.n | 13 +- tcl/doc/string.n | 269 +- tcl/doc/switch.n | 11 +- tcl/doc/tclsh.1 | 3 +- tcl/doc/tcltest.n | 759 +++ tcl/doc/tclvars.n | 70 +- tcl/doc/tell.n | 10 +- tcl/doc/trace.n | 4 +- tcl/doc/update.n | 3 +- tcl/doc/upvar.n | 22 +- tcl/doc/variable.n | 4 +- tcl/doc/vwait.n | 6 +- tcl/generic/patchlevel.h | 23 + tcl/generic/regc_color.c | 778 +++ tcl/generic/regc_cvec.c | 198 + tcl/generic/regc_lex.c | 1061 ++++ tcl/generic/regc_locale.c | 930 +++ tcl/generic/regc_nfa.c | 1575 +++++ tcl/generic/regcomp.c | 2175 +++++++ tcl/generic/regcustom.h | 114 + tcl/generic/rege_dfa.c | 677 +++ tcl/generic/regerror.c | 109 + tcl/generic/regerrs.h | 18 + tcl/generic/regex.h | 341 ++ tcl/generic/regexec.c | 1038 ++++ tcl/generic/regfree.c | 53 + tcl/generic/regfronts.c | 83 + tcl/generic/regguts.h | 418 ++ tcl/generic/tcl.decls | 1489 +++++ tcl/generic/tcl.h | 1417 +++-- tcl/generic/tclAlloc.c | 312 +- tcl/generic/tclAsync.c | 15 + tcl/generic/tclBasic.c | 1517 ++--- tcl/generic/tclBinary.c | 900 ++- tcl/generic/tclCkalloc.c | 375 +- tcl/generic/tclClock.c | 126 +- tcl/generic/tclCmdAH.c | 1534 +++-- tcl/generic/tclCmdIL.c | 653 ++- tcl/generic/tclCmdMZ.c | 2876 ++++++---- tcl/generic/tclCompCmds.c | 2023 +++++++ tcl/generic/tclCompExpr.c | 2664 +++------ tcl/generic/tclCompile.c | 9299 ++++++++---------------------- tcl/generic/tclCompile.h | 500 +- tcl/generic/tclDate.c | 664 ++- tcl/generic/tclDecls.h | 3462 +++++++++++ tcl/generic/tclEncoding.c | 2767 +++++++++ tcl/generic/tclEnv.c | 463 +- tcl/generic/tclEvent.c | 584 +- tcl/generic/tclExecute.c | 2443 ++++---- tcl/generic/tclExpr.c | 2061 +++++++ tcl/generic/tclFCmd.c | 117 +- tcl/generic/tclFHandle.c | 259 + tcl/generic/tclFileName.c | 1083 +++- tcl/generic/tclGet.c | 72 +- tcl/generic/tclGetDate.y | 396 +- tcl/generic/tclHash.c | 5 + tcl/generic/tclHistory.c | 24 +- tcl/generic/tclIO.c | 10188 ++++++++++++++++++++------------- tcl/generic/tclIO.h | 379 ++ tcl/generic/tclIOCmd.c | 734 ++- tcl/generic/tclIOGT.c | 1359 +++++ tcl/generic/tclIOSock.c | 35 +- tcl/generic/tclIOUtil.c | 154 +- tcl/generic/tclIndexObj.c | 174 +- tcl/generic/tclInitScript.h | 93 +- tcl/generic/tclInt.decls | 870 +++ tcl/generic/tclInt.h | 1026 ++-- tcl/generic/tclIntDecls.h | 1394 +++++ tcl/generic/tclIntPlatDecls.h | 535 ++ tcl/generic/tclInterp.c | 4840 ++++++---------- tcl/generic/tclLink.c | 39 +- tcl/generic/tclListObj.c | 13 +- tcl/generic/tclLiteral.c | 1062 ++++ tcl/generic/tclLoad.c | 259 +- tcl/generic/tclLoadNone.c | 38 +- tcl/generic/tclMain.c | 206 +- tcl/generic/tclNamesp.c | 270 +- tcl/generic/tclNotify.c | 537 +- tcl/generic/tclObj.c | 374 +- tcl/generic/tclPanic.c | 123 + tcl/generic/tclParse.c | 2738 ++++++--- tcl/generic/tclParseExpr.c | 1852 ++++++ tcl/generic/tclPatch.h | 23 + tcl/generic/tclPipe.c | 125 +- tcl/generic/tclPkg.c | 631 +- tcl/generic/tclPlatDecls.h | 152 + tcl/generic/tclPort.h | 8 +- tcl/generic/tclPosixStr.c | 11 +- tcl/generic/tclPreserve.c | 215 +- tcl/generic/tclProc.c | 216 +- tcl/generic/tclRegexp.c | 1029 ++++ tcl/generic/tclRegexp.h | 69 +- tcl/generic/tclResult.c | 1052 ++++ tcl/generic/tclScan.c | 1133 ++++ tcl/generic/tclStringObj.c | 1261 +++- tcl/generic/tclStubInit.c | 817 +++ tcl/generic/tclStubLib.c | 117 + tcl/generic/tclStubs.c | 3267 +++++++++++ tcl/generic/tclTest.c | 2050 ++++++- tcl/generic/tclTestObj.c | 254 +- tcl/generic/tclThread.c | 580 ++ tcl/generic/tclThreadTest.c | 967 ++++ tcl/generic/tclTimer.c | 386 +- tcl/generic/tclUniData.c | 586 ++ tcl/generic/tclUtf.c | 1586 +++++ tcl/generic/tclUtil.c | 1764 +++--- tcl/generic/tclVar.c | 1124 ++-- tcl/library/auto.tcl | 587 ++ tcl/library/dde1.0/pkgIndex.tcl | 1 + tcl/library/dde1.1/pkgIndex.tcl | 5 + tcl/library/encoding/ascii.enc | 20 + tcl/library/encoding/big5.enc | 1516 +++++ tcl/library/encoding/cp1250.enc | 20 + tcl/library/encoding/cp1251.enc | 20 + tcl/library/encoding/cp1252.enc | 20 + tcl/library/encoding/cp1253.enc | 20 + tcl/library/encoding/cp1254.enc | 20 + tcl/library/encoding/cp1255.enc | 20 + tcl/library/encoding/cp1256.enc | 20 + tcl/library/encoding/cp1257.enc | 20 + tcl/library/encoding/cp1258.enc | 20 + tcl/library/encoding/cp437.enc | 20 + tcl/library/encoding/cp737.enc | 20 + tcl/library/encoding/cp775.enc | 20 + tcl/library/encoding/cp850.enc | 20 + tcl/library/encoding/cp852.enc | 20 + tcl/library/encoding/cp855.enc | 20 + tcl/library/encoding/cp857.enc | 20 + tcl/library/encoding/cp860.enc | 20 + tcl/library/encoding/cp861.enc | 20 + tcl/library/encoding/cp862.enc | 20 + tcl/library/encoding/cp863.enc | 20 + tcl/library/encoding/cp864.enc | 20 + tcl/library/encoding/cp865.enc | 20 + tcl/library/encoding/cp866.enc | 20 + tcl/library/encoding/cp869.enc | 20 + tcl/library/encoding/cp874.enc | 20 + tcl/library/encoding/cp932.enc | 785 +++ tcl/library/encoding/cp936.enc | 2162 +++++++ tcl/library/encoding/cp949.enc | 2128 +++++++ tcl/library/encoding/cp950.enc | 1499 +++++ tcl/library/encoding/dingbats.enc | 20 + tcl/library/encoding/euc-cn.enc | 1397 +++++ tcl/library/encoding/euc-jp.enc | 1346 +++++ tcl/library/encoding/euc-kr.enc | 1533 +++++ tcl/library/encoding/gb12345.enc | 1414 +++++ tcl/library/encoding/gb1988.enc | 20 + tcl/library/encoding/gb2312.enc | 1380 +++++ tcl/library/encoding/iso2022-jp.enc | 12 + tcl/library/encoding/iso2022-kr.enc | 7 + tcl/library/encoding/iso2022.enc | 16 + tcl/library/encoding/iso8859-1.enc | 20 + tcl/library/encoding/iso8859-2.enc | 20 + tcl/library/encoding/iso8859-3.enc | 20 + tcl/library/encoding/iso8859-4.enc | 20 + tcl/library/encoding/iso8859-5.enc | 20 + tcl/library/encoding/iso8859-6.enc | 20 + tcl/library/encoding/iso8859-7.enc | 20 + tcl/library/encoding/iso8859-8.enc | 20 + tcl/library/encoding/iso8859-9.enc | 20 + tcl/library/encoding/jis0201.enc | 20 + tcl/library/encoding/jis0208.enc | 1312 +++++ tcl/library/encoding/jis0212.enc | 1159 ++++ tcl/library/encoding/koi8-r.enc | 20 + tcl/library/encoding/ksc5601.enc | 1516 +++++ tcl/library/encoding/macCentEuro.enc | 20 + tcl/library/encoding/macCroatian.enc | 20 + tcl/library/encoding/macCyrillic.enc | 20 + tcl/library/encoding/macDingbats.enc | 20 + tcl/library/encoding/macGreek.enc | 20 + tcl/library/encoding/macIceland.enc | 20 + tcl/library/encoding/macJapan.enc | 785 +++ tcl/library/encoding/macRoman.enc | 20 + tcl/library/encoding/macRomania.enc | 20 + tcl/library/encoding/macThai.enc | 20 + tcl/library/encoding/macTurkish.enc | 20 + tcl/library/encoding/macUkraine.enc | 20 + tcl/library/encoding/shiftjis.enc | 683 +++ tcl/library/encoding/symbol.enc | 20 + tcl/library/history.tcl | 4 +- tcl/library/http1.0/http.tcl | 2 +- tcl/library/init.tcl | 1125 +--- tcl/library/ldAout.tcl | 365 +- tcl/library/msgcat1.0/msgcat.tcl | 202 + tcl/library/msgcat1.0/pkgIndex.tcl | 1 + tcl/library/opt0.4/optparse.tcl | 1090 ++++ tcl/library/opt0.4/pkgIndex.tcl | 11 + tcl/library/package.tcl | 632 ++ tcl/library/reg1.0/pkgIndex.tcl | 7 + tcl/library/safe.tcl | 355 +- tcl/library/safeinit.tcl | 461 ++ tcl/library/tclIndex | 59 + tcl/library/tcltest1.0/pkgIndex.tcl | 18 + tcl/library/tcltest1.0/tcltest.tcl | 1906 ++++++ tcl/library/word.tcl | 28 +- tcl/mac/MW_TclAppleScriptHeader.h | 7 + tcl/mac/MW_TclAppleScriptHeader.pch | 8 +- tcl/mac/MW_TclHeader.h | 7 + tcl/mac/MW_TclHeader.pch | 2 + tcl/mac/MW_TclTestHeader.h | 7 + tcl/mac/MW_TclTestHeader.pch | 54 + tcl/mac/README | 172 +- tcl/mac/bugs.doc | 12 + tcl/mac/tclMac.h | 65 +- tcl/mac/tclMacAlloc.c | 2 +- tcl/mac/tclMacAppInit.c | 10 +- tcl/mac/tclMacApplication.r | 6 +- tcl/mac/tclMacBOAAppInit.c | 2 +- tcl/mac/tclMacBOAMain.c | 25 +- tcl/mac/tclMacChan.c | 172 +- tcl/mac/tclMacExit.c | 2 +- tcl/mac/tclMacFCmd.c | 497 +- tcl/mac/tclMacFile.c | 881 +-- tcl/mac/tclMacInit.c | 648 ++- tcl/mac/tclMacInt.h | 51 +- tcl/mac/tclMacLibrary.c | 8 +- tcl/mac/tclMacLibrary.r | 10 +- tcl/mac/tclMacLoad.c | 61 +- tcl/mac/tclMacNotify.c | 170 +- tcl/mac/tclMacOSA.c | 34 +- tcl/mac/tclMacOSA.r | 4 +- tcl/mac/tclMacPort.h | 269 +- tcl/mac/tclMacProjects.sea.hqx | 4765 +++++++++------ tcl/mac/tclMacResource.c | 85 +- tcl/mac/tclMacResource.r | 8 +- tcl/mac/tclMacShLib.exp | 11 +- tcl/mac/tclMacSock.c | 377 +- tcl/mac/tclMacTclCode.r | 37 + tcl/mac/tclMacTest.c | 29 - tcl/mac/tclMacThrd.c | 829 +++ tcl/mac/tclMacThrd.h | 20 + tcl/mac/tclMacTime.c | 3 +- tcl/mac/tclMacUnix.c | 143 +- tcl/mac/tclMacUtil.c | 11 +- tcl/tests/README | 231 +- tcl/tests/all.tcl | 56 + tcl/tests/append.test | 28 +- tcl/tests/assocd.test | 24 +- tcl/tests/async.test | 25 +- tcl/tests/autoMkindex.tcl | 21 + tcl/tests/autoMkindex.test | 190 +- tcl/tests/basic.test | 230 +- tcl/tests/binary.test | 40 +- tcl/tests/case.test | 23 +- tcl/tests/clock.test | 278 +- tcl/tests/cmdAH.test | 863 ++- tcl/tests/cmdIL.test | 63 +- tcl/tests/cmdInfo.test | 26 +- tcl/tests/cmdMZ.test | 413 +- tcl/tests/compExpr-old.test | 691 +++ tcl/tests/compExpr.test | 342 ++ tcl/tests/compile.test | 65 +- tcl/tests/concat.test | 23 +- tcl/tests/dcall.test | 26 +- tcl/tests/defs.tcl | 1091 ++++ tcl/tests/dstring.test | 25 +- tcl/tests/encoding.test | 318 + tcl/tests/env.test | 162 +- tcl/tests/error.test | 23 +- tcl/tests/eval.test | 23 +- tcl/tests/event.test | 610 +- tcl/tests/exec.test | 432 +- tcl/tests/execute.test | 516 +- tcl/tests/expr-old.test | 47 +- tcl/tests/expr.test | 96 +- tcl/tests/fCmd.test | 577 +- tcl/tests/fileName.test | 422 +- tcl/tests/for-old.test | 22 +- tcl/tests/for.test | 179 +- tcl/tests/foreach.test | 38 +- tcl/tests/format.test | 274 +- tcl/tests/get.test | 41 +- tcl/tests/history.test | 25 +- tcl/tests/http.test | 380 +- tcl/tests/httpd | 215 + tcl/tests/httpold.test | 189 +- tcl/tests/if-old.test | 23 +- tcl/tests/if.test | 602 +- tcl/tests/incr-old.test | 23 +- tcl/tests/incr.test | 279 +- tcl/tests/indexObj.test | 24 +- tcl/tests/info.test | 311 +- tcl/tests/init.test | 39 +- tcl/tests/interp.test | 209 +- tcl/tests/io.test | 2709 +++++++-- tcl/tests/ioCmd.test | 84 +- tcl/tests/ioUtil.test | 320 ++ tcl/tests/iogt.test | 940 +++ tcl/tests/join.test | 21 +- tcl/tests/lindex.test | 13 +- tcl/tests/link.test | 27 +- tcl/tests/linsert.test | 15 +- tcl/tests/list.test | 23 +- tcl/tests/listObj.test | 33 +- tcl/tests/llength.test | 23 +- tcl/tests/load.test | 110 +- tcl/tests/lrange.test | 15 +- tcl/tests/lreplace.test | 16 +- tcl/tests/lsearch.test | 29 +- tcl/tests/macFCmd.test | 166 +- tcl/tests/misc.test | 30 +- tcl/tests/msgcat.test | 413 ++ tcl/tests/namespace-old.test | 23 +- tcl/tests/namespace.test | 70 +- tcl/tests/obj.test | 176 +- tcl/tests/opt.test | 48 +- tcl/tests/osa.test | 41 +- tcl/tests/package.test | 72 + tcl/tests/parse.test | 1264 ++-- tcl/tests/parseExpr.test | 639 +++ tcl/tests/parseOld.test | 552 ++ tcl/tests/pid.test | 28 +- tcl/tests/pkg.test | 107 +- tcl/tests/pkg/import.tcl | 16 + tcl/tests/pkg/license.terms | 39 + tcl/tests/pkg/magicchar.tcl | 6 + tcl/tests/pkg/magicchar2.tcl | 1 + tcl/tests/pkg/samename.tcl | 25 + tcl/tests/pkg/spacename.tcl | 3 + tcl/tests/pkgMkIndex.test | 128 +- tcl/tests/platform.test | 41 + tcl/tests/proc-old.test | 22 +- tcl/tests/proc.test | 23 +- tcl/tests/pwd.test | 23 +- tcl/tests/reg.test | 995 ++++ tcl/tests/regexp.test | 265 +- tcl/tests/registry.test | 330 +- tcl/tests/remote.tcl | 11 + tcl/tests/rename.test | 21 +- tcl/tests/resource.test | 142 +- tcl/tests/result.test | 103 + tcl/tests/safe.test | 111 +- tcl/tests/scan.test | 541 +- tcl/tests/security.test | 55 + tcl/tests/set-old.test | 36 +- tcl/tests/set.test | 294 +- tcl/tests/socket.test | 554 +- tcl/tests/source.test | 56 +- tcl/tests/split.test | 23 +- tcl/tests/stack.test | 12 +- tcl/tests/string.test | 1176 +++- tcl/tests/stringObj.test | 258 +- tcl/tests/subst.test | 25 +- tcl/tests/switch.test | 27 +- tcl/tests/tcltest.test | 407 ++ tcl/tests/thread.test | 236 + tcl/tests/timer.test | 103 +- tcl/tests/trace.test | 28 +- tcl/tests/unixFCmd.test | 197 +- tcl/tests/unixFile.test | 53 +- tcl/tests/unixInit.test | 209 + tcl/tests/unixNotfy.test | 77 +- tcl/tests/unknown.test | 23 +- tcl/tests/uplevel.test | 23 +- tcl/tests/upvar.test | 23 +- tcl/tests/utf.test | 294 + tcl/tests/util.test | 230 +- tcl/tests/var.test | 304 +- tcl/tests/while-old.test | 23 +- tcl/tests/while.test | 324 +- tcl/tests/winConsole.test | 53 + tcl/tests/winDde.test | 169 + tcl/tests/winFCmd.test | 427 +- tcl/tests/winFile.test | 80 + tcl/tests/winNotify.test | 56 +- tcl/tests/winPipe.test | 314 +- tcl/tests/winTime.test | 51 + tcl/tools/Makefile.in | 69 + tcl/tools/README | 28 + tcl/tools/checkLibraryDoc.tcl | 296 + tcl/tools/configure | 749 +++ tcl/tools/configure.in | 33 + tcl/tools/cvtEOL.tcl | 35 + tcl/tools/genStubs.tcl | 894 +++ tcl/tools/genWinImage.tcl | 158 + tcl/tools/index.tcl | 202 + tcl/tools/man2help.tcl | 130 + tcl/tools/man2help2.tcl | 970 ++++ tcl/tools/man2html.tcl | 181 + tcl/tools/man2html1.tcl | 269 + tcl/tools/man2html2.tcl | 871 +++ tcl/tools/man2tcl.c | 405 ++ tcl/tools/regexpTestLib.tcl | 266 + tcl/tools/tcl.hpj.in | 19 + tcl/tools/tcl.wse.in | 2356 ++++++++ tcl/tools/tclSplash.bmp | Bin 0 -> 162030 bytes tcl/tools/tcltk-man2html.tcl | 1675 ++++++ tcl/tools/uniClass.tcl | 61 + tcl/tools/uniParse.tcl | 386 ++ tcl/tools/white.bmp | Bin 0 -> 20522 bytes tcl/unix/ChangeLog | 12 +- tcl/unix/Makefile.in | 698 ++- tcl/unix/README | 77 +- tcl/unix/aclocal.m4 | 537 +- tcl/unix/bp.c | 127 + tcl/unix/configure | 4303 +++++++++----- tcl/unix/configure.in | 1110 +--- tcl/unix/dltest/Makefile.in | 22 +- tcl/unix/dltest/README | 3 +- tcl/unix/dltest/configure | 23 +- tcl/unix/dltest/configure.in | 16 +- tcl/unix/dltest/pkga.c | 64 +- tcl/unix/dltest/pkgb.c | 77 +- tcl/unix/dltest/pkgc.c | 69 +- tcl/unix/dltest/pkgd.c | 71 +- tcl/unix/dltest/pkge.c | 19 +- tcl/unix/dltest/pkgf.c | 9 +- tcl/unix/ldAix | 13 +- tcl/unix/mkLinks | 1208 ++-- tcl/unix/porting.old | 384 ++ tcl/unix/tcl.m4 | 1882 ++++++ tcl/unix/tcl.spec | 53 + tcl/unix/tclAppInit.c | 63 +- tcl/unix/tclConfig.sh.in | 59 +- tcl/unix/tclLoadAix.c | 5 +- tcl/unix/tclLoadAout.c | 75 +- tcl/unix/tclLoadDl.c | 81 +- tcl/unix/tclLoadDl2.c | 113 + tcl/unix/tclLoadDld.c | 46 +- tcl/unix/tclLoadDyld.c | 171 + tcl/unix/tclLoadNext.c | 40 +- tcl/unix/tclLoadOSF.c | 41 +- tcl/unix/tclLoadShl.c | 56 +- tcl/unix/tclMtherr.c | 12 +- tcl/unix/tclUnixChan.c | 608 +- tcl/unix/tclUnixEvent.c | 3 +- tcl/unix/tclUnixFCmd.c | 933 ++- tcl/unix/tclUnixFile.c | 758 ++- tcl/unix/tclUnixInit.c | 647 ++- tcl/unix/tclUnixNotfy.c | 679 ++- tcl/unix/tclUnixPipe.c | 137 +- tcl/unix/tclUnixPort.h | 177 +- tcl/unix/tclUnixSock.c | 56 +- tcl/unix/tclUnixTest.c | 116 +- tcl/unix/tclUnixThrd.c | 726 +++ tcl/unix/tclUnixThrd.h | 21 + tcl/unix/tclUnixTime.c | 74 + tcl/unix/tclXtNotify.c | 1322 ++--- tcl/unix/tclXtTest.c | 10 +- tcl/win/Makefile.in | 1076 ++-- tcl/win/README | 174 +- tcl/win/aclocal.m4 | 2 + tcl/win/cat.c | 2 + tcl/win/configure | 2253 ++++++-- tcl/win/configure.in | 295 +- tcl/win/license.terms | 2 + tcl/win/makefile.vc | 473 +- tcl/win/mkd.bat | 5 +- tcl/win/rmd.bat | 4 +- tcl/win/stub16.c | 5 +- tcl/win/tcl.m4 | 637 +++ tcl/win/tcl.rc | 19 +- tcl/win/tclAppInit.c | 71 +- tcl/win/tclConfig.sh.in | 185 + tcl/win/tclWin32Dll.c | 484 +- tcl/win/tclWinChan.c | 658 +-- tcl/win/tclWinConsole.c | 1269 ++++ tcl/win/tclWinDde.c | 1351 +++++ tcl/win/tclWinError.c | 5 +- tcl/win/tclWinFCmd.c | 1065 ++-- tcl/win/tclWinFile.c | 1119 ++-- tcl/win/tclWinInit.c | 687 ++- tcl/win/tclWinInt.h | 71 +- tcl/win/tclWinLoad.c | 121 +- tcl/win/tclWinMtherr.c | 15 +- tcl/win/tclWinNotify.c | 371 +- tcl/win/tclWinPipe.c | 2174 +++---- tcl/win/tclWinPort.h | 437 +- tcl/win/tclWinReg.c | 482 +- tcl/win/tclWinSerial.c | 1206 ++++ tcl/win/tclWinSock.c | 1097 ++-- tcl/win/tclWinTest.c | 72 +- tcl/win/tclWinThrd.c | 914 +++ tcl/win/tclWinThrd.h | 23 + tcl/win/tclWinTime.c | 129 +- tcl/win/tclWinUtil.c | 66 + tcl/win/tclsh.ico | Bin 0 -> 3630 bytes tcl/win/tclsh.rc | 19 +- 594 files changed, 177904 insertions(+), 49259 deletions(-) create mode 100644 tcl/compat/getcwd.c create mode 100644 tcl/cygtcl.m4 create mode 100644 tcl/doc/Access.3 create mode 100644 tcl/doc/ByteArrObj.3 create mode 100644 tcl/doc/ChnlStack.3 create mode 100644 tcl/doc/DumpActiveMemory.3 create mode 100644 tcl/doc/Encoding.3 create mode 100644 tcl/doc/GetCwd.3 create mode 100644 tcl/doc/GetHostName.3 create mode 100644 tcl/doc/GetVersion.3 create mode 100644 tcl/doc/Init.3 create mode 100644 tcl/doc/InitStubs.3 create mode 100644 tcl/doc/ParseCmd.3 create mode 100644 tcl/doc/SaveResult.3 create mode 100644 tcl/doc/SourceRCFile.3 create mode 100644 tcl/doc/TCL_MEM_DEBUG.3 create mode 100644 tcl/doc/TclInitStubs.3 create mode 100644 tcl/doc/Thread.3 create mode 100644 tcl/doc/ToUpper.3 create mode 100644 tcl/doc/Utf.3 create mode 100644 tcl/doc/dde.n create mode 100644 tcl/doc/encoding.n create mode 100644 tcl/doc/memory.n create mode 100644 tcl/doc/msgcat.n create mode 100644 tcl/doc/packagens.n create mode 100644 tcl/doc/re_syntax.n create mode 100644 tcl/doc/tcltest.n create mode 100644 tcl/generic/patchlevel.h create mode 100644 tcl/generic/regc_color.c create mode 100644 tcl/generic/regc_cvec.c create mode 100644 tcl/generic/regc_lex.c create mode 100644 tcl/generic/regc_locale.c create mode 100644 tcl/generic/regc_nfa.c create mode 100644 tcl/generic/regcomp.c create mode 100644 tcl/generic/regcustom.h create mode 100644 tcl/generic/rege_dfa.c create mode 100644 tcl/generic/regerror.c create mode 100644 tcl/generic/regerrs.h create mode 100644 tcl/generic/regex.h create mode 100644 tcl/generic/regexec.c create mode 100644 tcl/generic/regfree.c create mode 100644 tcl/generic/regfronts.c create mode 100644 tcl/generic/regguts.h create mode 100644 tcl/generic/tcl.decls create mode 100644 tcl/generic/tclCompCmds.c create mode 100644 tcl/generic/tclDecls.h create mode 100644 tcl/generic/tclEncoding.c create mode 100644 tcl/generic/tclExpr.c create mode 100644 tcl/generic/tclFHandle.c create mode 100644 tcl/generic/tclIO.h create mode 100644 tcl/generic/tclIOGT.c create mode 100644 tcl/generic/tclInt.decls create mode 100644 tcl/generic/tclIntDecls.h create mode 100644 tcl/generic/tclIntPlatDecls.h create mode 100644 tcl/generic/tclLiteral.c create mode 100644 tcl/generic/tclPanic.c create mode 100644 tcl/generic/tclParseExpr.c create mode 100644 tcl/generic/tclPatch.h create mode 100644 tcl/generic/tclPlatDecls.h create mode 100644 tcl/generic/tclRegexp.c create mode 100644 tcl/generic/tclResult.c create mode 100644 tcl/generic/tclScan.c create mode 100644 tcl/generic/tclStubInit.c create mode 100644 tcl/generic/tclStubLib.c create mode 100644 tcl/generic/tclStubs.c create mode 100644 tcl/generic/tclThread.c create mode 100644 tcl/generic/tclThreadTest.c create mode 100644 tcl/generic/tclUniData.c create mode 100644 tcl/generic/tclUtf.c create mode 100644 tcl/library/auto.tcl create mode 100755 tcl/library/dde1.0/pkgIndex.tcl create mode 100644 tcl/library/dde1.1/pkgIndex.tcl create mode 100644 tcl/library/encoding/ascii.enc create mode 100644 tcl/library/encoding/big5.enc create mode 100644 tcl/library/encoding/cp1250.enc create mode 100644 tcl/library/encoding/cp1251.enc create mode 100644 tcl/library/encoding/cp1252.enc create mode 100644 tcl/library/encoding/cp1253.enc create mode 100644 tcl/library/encoding/cp1254.enc create mode 100644 tcl/library/encoding/cp1255.enc create mode 100644 tcl/library/encoding/cp1256.enc create mode 100644 tcl/library/encoding/cp1257.enc create mode 100644 tcl/library/encoding/cp1258.enc create mode 100644 tcl/library/encoding/cp437.enc create mode 100644 tcl/library/encoding/cp737.enc create mode 100644 tcl/library/encoding/cp775.enc create mode 100644 tcl/library/encoding/cp850.enc create mode 100644 tcl/library/encoding/cp852.enc create mode 100644 tcl/library/encoding/cp855.enc create mode 100644 tcl/library/encoding/cp857.enc create mode 100644 tcl/library/encoding/cp860.enc create mode 100644 tcl/library/encoding/cp861.enc create mode 100644 tcl/library/encoding/cp862.enc create mode 100644 tcl/library/encoding/cp863.enc create mode 100644 tcl/library/encoding/cp864.enc create mode 100644 tcl/library/encoding/cp865.enc create mode 100644 tcl/library/encoding/cp866.enc create mode 100644 tcl/library/encoding/cp869.enc create mode 100644 tcl/library/encoding/cp874.enc create mode 100644 tcl/library/encoding/cp932.enc create mode 100644 tcl/library/encoding/cp936.enc create mode 100644 tcl/library/encoding/cp949.enc create mode 100644 tcl/library/encoding/cp950.enc create mode 100644 tcl/library/encoding/dingbats.enc create mode 100644 tcl/library/encoding/euc-cn.enc create mode 100644 tcl/library/encoding/euc-jp.enc create mode 100644 tcl/library/encoding/euc-kr.enc create mode 100644 tcl/library/encoding/gb12345.enc create mode 100644 tcl/library/encoding/gb1988.enc create mode 100644 tcl/library/encoding/gb2312.enc create mode 100644 tcl/library/encoding/iso2022-jp.enc create mode 100644 tcl/library/encoding/iso2022-kr.enc create mode 100644 tcl/library/encoding/iso2022.enc create mode 100644 tcl/library/encoding/iso8859-1.enc create mode 100644 tcl/library/encoding/iso8859-2.enc create mode 100644 tcl/library/encoding/iso8859-3.enc create mode 100644 tcl/library/encoding/iso8859-4.enc create mode 100644 tcl/library/encoding/iso8859-5.enc create mode 100644 tcl/library/encoding/iso8859-6.enc create mode 100644 tcl/library/encoding/iso8859-7.enc create mode 100644 tcl/library/encoding/iso8859-8.enc create mode 100644 tcl/library/encoding/iso8859-9.enc create mode 100644 tcl/library/encoding/jis0201.enc create mode 100644 tcl/library/encoding/jis0208.enc create mode 100644 tcl/library/encoding/jis0212.enc create mode 100644 tcl/library/encoding/koi8-r.enc create mode 100644 tcl/library/encoding/ksc5601.enc create mode 100644 tcl/library/encoding/macCentEuro.enc create mode 100644 tcl/library/encoding/macCroatian.enc create mode 100644 tcl/library/encoding/macCyrillic.enc create mode 100644 tcl/library/encoding/macDingbats.enc create mode 100644 tcl/library/encoding/macGreek.enc create mode 100644 tcl/library/encoding/macIceland.enc create mode 100644 tcl/library/encoding/macJapan.enc create mode 100644 tcl/library/encoding/macRoman.enc create mode 100644 tcl/library/encoding/macRomania.enc create mode 100644 tcl/library/encoding/macThai.enc create mode 100644 tcl/library/encoding/macTurkish.enc create mode 100644 tcl/library/encoding/macUkraine.enc create mode 100644 tcl/library/encoding/shiftjis.enc create mode 100644 tcl/library/encoding/symbol.enc create mode 100644 tcl/library/msgcat1.0/msgcat.tcl create mode 100644 tcl/library/msgcat1.0/pkgIndex.tcl create mode 100644 tcl/library/opt0.4/optparse.tcl create mode 100644 tcl/library/opt0.4/pkgIndex.tcl create mode 100644 tcl/library/package.tcl create mode 100755 tcl/library/reg1.0/pkgIndex.tcl create mode 100644 tcl/library/safeinit.tcl create mode 100644 tcl/library/tcltest1.0/pkgIndex.tcl create mode 100644 tcl/library/tcltest1.0/tcltest.tcl create mode 100644 tcl/mac/MW_TclAppleScriptHeader.h create mode 100644 tcl/mac/MW_TclHeader.h create mode 100644 tcl/mac/MW_TclTestHeader.h create mode 100644 tcl/mac/MW_TclTestHeader.pch create mode 100644 tcl/mac/tclMacTclCode.r create mode 100644 tcl/mac/tclMacThrd.c create mode 100644 tcl/mac/tclMacThrd.h create mode 100644 tcl/tests/all.tcl create mode 100644 tcl/tests/compExpr-old.test create mode 100644 tcl/tests/compExpr.test create mode 100644 tcl/tests/defs.tcl create mode 100644 tcl/tests/encoding.test create mode 100644 tcl/tests/httpd create mode 100644 tcl/tests/ioUtil.test create mode 100644 tcl/tests/iogt.test create mode 100644 tcl/tests/msgcat.test create mode 100644 tcl/tests/package.test create mode 100644 tcl/tests/parseExpr.test create mode 100644 tcl/tests/parseOld.test create mode 100644 tcl/tests/pkg/import.tcl create mode 100644 tcl/tests/pkg/license.terms create mode 100644 tcl/tests/pkg/magicchar.tcl create mode 100644 tcl/tests/pkg/magicchar2.tcl create mode 100644 tcl/tests/pkg/samename.tcl create mode 100644 tcl/tests/pkg/spacename.tcl create mode 100644 tcl/tests/platform.test create mode 100644 tcl/tests/reg.test create mode 100644 tcl/tests/result.test create mode 100644 tcl/tests/security.test create mode 100644 tcl/tests/tcltest.test create mode 100644 tcl/tests/thread.test create mode 100644 tcl/tests/unixInit.test create mode 100644 tcl/tests/utf.test create mode 100644 tcl/tests/winConsole.test create mode 100644 tcl/tests/winDde.test create mode 100644 tcl/tests/winFile.test create mode 100644 tcl/tests/winTime.test create mode 100644 tcl/tools/Makefile.in create mode 100644 tcl/tools/README create mode 100644 tcl/tools/checkLibraryDoc.tcl create mode 100755 tcl/tools/configure create mode 100644 tcl/tools/configure.in create mode 100644 tcl/tools/cvtEOL.tcl create mode 100644 tcl/tools/genStubs.tcl create mode 100644 tcl/tools/genWinImage.tcl create mode 100644 tcl/tools/index.tcl create mode 100644 tcl/tools/man2help.tcl create mode 100644 tcl/tools/man2help2.tcl create mode 100644 tcl/tools/man2html.tcl create mode 100644 tcl/tools/man2html1.tcl create mode 100644 tcl/tools/man2html2.tcl create mode 100644 tcl/tools/man2tcl.c create mode 100644 tcl/tools/regexpTestLib.tcl create mode 100644 tcl/tools/tcl.hpj.in create mode 100644 tcl/tools/tcl.wse.in create mode 100644 tcl/tools/tclSplash.bmp create mode 100755 tcl/tools/tcltk-man2html.tcl create mode 100644 tcl/tools/uniClass.tcl create mode 100644 tcl/tools/uniParse.tcl create mode 100644 tcl/tools/white.bmp create mode 100644 tcl/unix/bp.c create mode 100644 tcl/unix/porting.old create mode 100644 tcl/unix/tcl.m4 create mode 100644 tcl/unix/tcl.spec create mode 100644 tcl/unix/tclLoadDl2.c create mode 100644 tcl/unix/tclLoadDyld.c create mode 100644 tcl/unix/tclUnixThrd.c create mode 100644 tcl/unix/tclUnixThrd.h create mode 100644 tcl/win/aclocal.m4 create mode 100644 tcl/win/tcl.m4 create mode 100644 tcl/win/tclConfig.sh.in create mode 100644 tcl/win/tclWinConsole.c create mode 100644 tcl/win/tclWinDde.c create mode 100644 tcl/win/tclWinSerial.c create mode 100644 tcl/win/tclWinThrd.c create mode 100644 tcl/win/tclWinThrd.h create mode 100644 tcl/win/tclWinUtil.c create mode 100644 tcl/win/tclsh.ico diff --git a/tcl/ChangeLog b/tcl/ChangeLog index c217f8dc24c..17a6b9308bd 100644 --- a/tcl/ChangeLog +++ b/tcl/ChangeLog @@ -1,179 +1,4567 @@ -2000-01-26 DJ Delorie +2001-08-08 Mo DeJong + + * cygtcl.m4 (TCL_TOOL_PATH, TCL_TOOL_SHARED_LIB_LONGNAME): + Raise an error if the CYGPATH variable is not defined when + TCL_TOOL_PATH is invoked. Add cygwin to the list of hosts + that do not use a "lib" prefix for shared library names. + * unix/configure: Regen. + * win/configure: Regen. + +2001-08-06 Mo DeJong + + * cygtcl.m4 (TCL_TOOL_STATIC_LIB_LONGNAME, + TCL_TOOL_SHARED_LIB_LONGNAME, + TCL_TOOL_LIB_SHORTNAME): Use TCL_VENDOR_PREFIX instead + of VENDORPREFIX to support using these macros in + extensions that load tclConfig.sh. + * unix/configure: Regen. + * unix/configure.in: Subst VENDORPREFIX into tclConfig.sh. + * unix/tclConfig.sh.in: Add TCL_VENDOR_PREFIX. + * win/configure: Regen. + * win/tcl.m4 (SC_CONFIG_CFLAGS): Set vendor prefix to "rh" + instead of "sn" when compiling with VC++ or gcc. When + compiling with Cygwin set the prefix to "cyg". Set the + TCL_VENDOR_PREFIX to support the tcl tool macros in Tcl. + * win/tclConfig.sh.in: Add TCL_VENDOR_PREFIX. + +2001-08-06 Mo DeJong + + * win/Makefile.in: Subst DDE_DLL_FILE, DDE_LIB_FILE, REG_DLL_FILE, + REG_LIB_FILE, and PIPE_DLL_FILE from the configure script instead + of figuring them out in the Makefile. + * win/configure: Regen. + * win/configure.in: Use TCL_TOOL_STATIC_LIB_LONGNAME and + TCL_TOOL_SHARED_LIB_LONGNAME macros to figure out values for + DDE_DLL_FILE, DDE_LIB_FILE, REG_DLL_FILE, REG_LIB_FILE, and + PIPE_DLL_FILE and subst them into the Makefile. + +2001-08-01 Mo DeJong + + * cygtcl.m4 (TCL_TOOL_STATIC_LIB_LONGNAME, + TCL_TOOL_SHARED_LIB_LONGNAME): Rename + TCL_TOOL_LIB_LONGNAME to TCL_TOOL_STATIC_LIB_LONGNAME. + Add new TCL_TOOL_SHARED_LIB_LONGNAME to construct + shared library names in a cross platform way. + * unix/configure: Regen. + * unix/configure.in: Use TCL_TOOL_SHARED_LIB_LONGNAME + and TCL_TOOL_STATIC_LIB_LONGNAME to generate lib names. + * win/configure: Regen. + * win/configure.in: Use TCL_TOOL_SHARED_LIB_LONGNAME + and TCL_TOOL_STATIC_LIB_LONGNAME to generate lib names. + +2001-07-24 Mo DeJong + + * win/configure: + * win/tcl.m4 (SC_CONFIG_CFLAGS): Don't pass explicit + Cygwin libs on the command line since linking is now + done using $CC and not $LD. + +2001-07-24 Mo DeJong + + * win/tclWinThrd.c (Tcl_CreateThread, TclpThreadExit): + When building under Cygwin, call CreateThread instead + of _beginthreadex and call ExitThread instead of + _endthreadex. Cygwin does not support these msvcrt + methods and does not suffer from the memory leak + problems that prompted their use. + +2001-07-24 Mo DeJong + + * win/configure: Regen. + * win/tcl.m4 (SC_CONFIG_CFLAGS): Check for bug in + Cygwin version of windres and work around that + case by passing a POSIX path instead of a Windows + native path. One can't always pass a POSIX path + because the mingw native toolchain accepts only + Windows native paths. + +2001-07-24 Mo DeJong + + * win/tclWinThrd.c (Tcl_CreateThread): Close Windows + HANDLE returned by _beginthreadex. The MS documentation + states that this handle is not closed by a later call to + _endthreadex. + +2001-07-16 Mo DeJong + + * generic/tcl.h: Define __WIN32__ when + __CYGWIN__ or __MINGW32__ is defined. + * generic/tclAlloc.c: Define caddr_t when + compiling with VC++ or mingw. This type is + already defined when compiling with Cygwin. + +2001-07-16 Mo DeJong + + * win/tclWinConsole.c: + * win/tclWinPipe.c: + * win/tclWinPort.h: + * win/tclWinThrd.c: + Remove unnecessary #includes of dos.h, direct.h, + and tchar.h. This will help the Cygwin porting + effort since these headers do not exist under Cygwin. + +2001-07-12 Mo DeJong + + * unix/Makefile.in: + * unix/configure: Regen. + * unix/configure.in: + * unix/tcl.m4: + * win/Makefile.in: + * win/configure: Regen. + * win/configure.in: + * win/tcl.m4: + Revert ill-conceived EXTRA_CFLAGS changes made on 2001-07-09. + The change ended up causing big problems with the + tclConfig.sh file since it exported EXTRA_CFLAGS and did + not deal with the debug/non-debug case. + +2001-07-11 Mo DeJong + + * unix/configure: Regen. + * unix/tcl.m4 (SC_CONFIG_CFLAGS): Avoid using AC_CHECK_TOOL + since Tcl's configure script is not setup properly. + +2001-07-11 Mo DeJong + + * unix/Makefile.in: Add AR variable for use in STLIB_LD. + * unix/configure: Regen. + * unix/configure.in: Use STLIB_LD when defining MAKE_LIB + and MAKE_STUB_LIB. Subst RANLIB and AR. + * unix/tcl.m4 (SC_CONFIG_CFLAGS): Add doc comment about + STLIB_LD command. Check ${AR} env var when setting + STLIB_LD and delay evaluation until make time. + * win/configure: Regen. + * win/tcl.m4 (SC_CONFIG_CFLAGS): Pass AR arguments in + STLIB_LD to better match the Unix implementation. Don't + bother defining AR when using VC++ since it is not used. + +2001-07-10 Mo DeJong + + * win/configure: + * win/tcl.m4 (SC_CONFIG_CFLAGS): Use STLIB_LD in MAKE_LIB instead + of AR which can be overridden on the make command line. + +2001-07-09 Mo DeJong + + * win/configure: + * win/tcl.m4 (SC_CONFIG_CFLAGS): Fix quoting of CYGPATH + argument to AC_CHECK_PROG. + +2001-07-09 Mo DeJong + + * unix/Makefile.in: Add EXTRA_CFLAGS_DEBUG and EXTRA_CFLAGS_OPTIMIZE + variables. These two do not actually differ in the unix version + but are there to keep in sync with the Windows version. + * unix/configure: Regen. + * unix/configure.in: Don't subst EXTRA_CFLAGS. Subst EXTRA_CFLAGS_DEFAULT, + EXTRA_CFLAGS_DEBUG, and EXTRA_CFLAGS_OPTIMIZE. + * unix/tcl.m4 (SC_ENABLE_SYMBOLS, SC_CONFIG_CFLAGS): Define + EXTRA_CFLAGS_DEFAULT based on the --enable-smbols option. + Set EXTRA_CFLAGS_DEBUG instead of EXTRA_CFLAGS and then set + EXTRA_CFLAGS_OPTIMIZE to the value of EXTRA_CFLAGS_DEBUG since + they are the same under Unix. + * win/Makefile.in: Add EXTRA_CFLAGS_DEBUG and EXTRA_CFLAGS_OPTIMIZE + variables. This is needed so that the proper runtime lib gets linked + into VC++ produced .obj files when CFLAGS is reset on the command line. + * win/configure: Regen. + * win/configure.in: Don't subst EXTRA_CFLAGS. Subst EXTRA_CFLAGS_DEFAULT, + EXTRA_CFLAGS_DEBUG, and EXTRA_CFLAGS_OPTIMIZE. + * win/tcl.m4 :(SC_ENABLE_SYMBOLS, SC_CONFIG_CFLAGS): Define + EXTRA_CFLAGS_DEFAULT based on the --enable-smbols option. Set + EXTRA_CFLAGS_DEBUG and EXTRA_CFLAGS_OPTIMIZE based on the runtime + option when compiled with VC++. + +2001-07-06 Mo DeJong + + * win/configure: Regen. + * win/tcl.m4 (SC_CONFIG_CFLAGS): Pass -e _WinMain@16 in + addition to the -mwindows flag to work around a problem + with ld when it incorrectly uses main() as the executable + entry point when both WinMain() and main() are available. + +2001-07-06 Mo DeJong + + * unix/configure: Regen. + * unix/configure.in: Replace call to SC_ENABLE_GCC with + AC_PROG_CC so that CC passed in from the caller is respected. + * unix/tcl.m4: Remove the unused SC_ENABLE_GCC macro. + * win/configure: Regen. + * win/configure.in: Replace call to SC_ENABLE_GCC with + AC_PROG_CC so that CC passed in from the caller is respected. + * win/tcl.m4: Remove unused SC_ENABLE_GCC macro. + +2001-07-06 Mo DeJong + + * win/Makefile.in: Subst DEPARG directly instead + of relying on a variable. This will make Cygwin + builds faster since an extra exec will be avoided. + * win/configure: Regen. + * win/configure.in: Subst DEPARG. + * win/tcl.m4 (SC_CONFIG_CFLAGS): Set DEPARG based + on CYGPATH. + +2001-06-26 Mo DeJong + + * cygtcl.m4 (TCL_TOOL_PATH): Use CYGPATH variable instead of + invoking cygpath directly. Handle cross compile by not + using CYGPATH when set to echo. + * unix/configure: Regen. + * win/Makefile.in: Remove PATHTYPE variable. + * win/configure: regen. + * win/configure.in: Remove PATHTYPE subst + extra CYGPATH subst. + * win/tcl.m4 (SC_CONFIG_CFLAGS): Remove PATHTYPE variable. Search + for cygpath in the PATH and set CYGPATH="cygpath -w" if found. + Remove old cross compiling hack. + +2001-06-26 Mo DeJong + + * win/Makefile.in: Don't use VPSEP in the VPATH, + just use : as the spearator. + * win/configure: Regen. + * win/configure.in: Don't subst VPSEP. + * win/tcl.m4 (SC_CONFIG_CFLAGS): Remove VPSEP. + +2001-06-25 Mo DeJong + + * win/configure: Regen. + * win/tcl.m4 (SC_CONFIG_CFLAGS): When building with + gcc, don't attempt to link with LD or support dllwrap. + Simply require a recent version of Cygwin gcc or Mingw + gcc that supports -shared. When linking, use gcc instead + of ld since gcc automatically includes libs like -lmsvcrt. + +2001-06-22 Mo DeJong + + * unix/Makefile.in: Set CFLAGS to @CFLAGS@ and @CFLAGS_DEFAULT@. + Set LDFLAGS to @LDFLAGS@ and @LDFLAGS_DEFAULT@. Add LDFLAGS_DEBUG + and LDFLAGS_OPTIMIZE to match the way CFLAGS_DEFAULT works. + This will support user set CFLAGS or LDFLAGS at configure time. + * unix/configure: Regen. + * unix/configure.in: Don't set CFLAGS to CFLAGS_DEFAULT, instead + subst CFLAGS_DEFAULT into the Makefile. Add AC_SUBST for CFLAGS_DEFAULT, + LDFLAGS_DEFAULT, LDFLAGS_DEBUG, and LDFLAGS_OPTIMIZE. + * unix/tcl.m4 (SC_ENABLE_SYMBOLS): Modify LDFLAGS_DEFAULT so that + it uses a Makefile variable just like CFLAGS_DEFAULT. + * win/Makefile.in: Set CFLAGS to @CFLAGS@ and @CFLAGS_DEFAULT@. + Set LDFLAGS to @LDFLAGS@ and @LDFLAGS_DEFAULT@. + This will support user set CFLAGS or LDFLAGS at configure time. + * win/configure: Regen. + * win/configure.in: Don't set CFLAGS or LDFLAGS, instead subst + CFLAGS_DEFAULT and LDFLAGS_DEFAULT into the Makefile. + * win/tcl.m4 (SC_ENABLE_SYMBOLS): Modify LDFLAGS_DEFAULT so that + it uses a Makefile variable just like CFLAGS_DEFAULT. + +2001-06-22 Mo DeJong + + * configure: Regen. + * configure.in: When a windows32 host is detected + configure in the win subdirectory. + * cygtcl.m4 (TCL_TOOL_PATH, TCL_TOOL_LIB_LONGNAME, + TCL_TOOL_LIB_SHORTNAME, TCL_TOOL_LIB_SPEC): + Add support for mingw32 and windows32 hosts. Remove + check for cygwin since we are really cross compiling + when building win32 executables. + * unix/configure: Regen. + * win/configure: Regen. + +2001-06-22 Mo DeJong + + * win/configure: + * win/tcl.m4 (SC_CONFIG_CFLAGS): Don't set LDFLAGS_DEBUG + to -g or LDFLAGS_OPTIMIZE to -O when compiling with gcc. + These flags are not needed and can cause problems with + the Cygwin version of ld. + +2001-06-20 Mo DeJong + + * generic/tcl.h: Define __WIN32__ when __MINGW32__ + is defined to support building under Cygwin gcc + with the -mno-cygwin flag. + +2001-06-14 Mo DeJong + + * unix/Makefile.in: Avoid burning install TCL_LIBRARY into + tclUnixInit.o at compile time. + * unix/tclUnixInit.c (TclpInitLibraryPath): Fix location + independence by searching for Tcl library in share/tclX.X + instead of lib/tclX.X. This logic is no longer effected by a + burned in TCL_LIBRARY. + * win/tclWinInit.c (TclpInitLibraryPath): Search for Tcl library + in share/tclX.X instead of lib/tclX.X. Remove a couple of + Cygnus local hacks since they were not doing anything useful. + +2001-06-08 Mo DeJong + + * win/Makefile.in: Set TCL_LIBRARY to + $INSTALL/share/tcl8.3 instead of + $INSTALL/lib/tcl8.3. + +2001-06-08 Mo DeJong + + * win/tclConfig.sh.in: Correct the definition + of TCL_LIB_FULL_PATH. It was inclosed in ` + characters instead of ' characters. + +2001-06-05 Mo DeJong + + * unix/configure: Regen. + * unix/tcl.m4 (SC_CONFIG_CFLAGS): Add a TCL_LIB_SUFFIX variable + to make the TCL_TOOL_LIB_SHORTNAME macro happy. + * unix/tclConfig.sh.in: Add TCL_LIB_SUFFIX variable. + +2001-06-05 Mo DeJong + + * cygtcl.m4 (TCL_TOOL_LIB_PATH): Call TCL_TOOL_PATH so that a + Windows native path is generated for PATH variables. + * unix/configure: Regen. + * win/configure: Regen. + +2001-06-01 Mo DeJong + + * cygtcl.m4 (TCL_TOOL_PATH, TCL_TOOL_LIB_SHORTNAME): Check that argument to + TCL_TOOL_PATH is not "". Use new TCL_LIB_SUFFIX variable in the + TCL_TOOL_LIB_SHORTNAME macro under Windows. + * unix/configure: Regen. + * win/configure: Regen. + * win/configure.in: Don't subst SHLIB_SUFFIX. + * win/tcl.m4 (SC_CONFIG_CFLAGS): Set TCL_LIB_SUFFIX so that Tcl + sees the same variable name that an extension will. + * win/tclConfig.sh.in: Set the TCL_SHLIB_SUFFIX and TCL_LIB_SUFFIX vars. + +2001-05-30 Mo DeJong + + * unix/configure: Regen. + * unix/tcl.m4 (SC_PATH_TCLCONFIG, SC_PATH_TKCONFIG): + Check in win subdirectory in addition to unix subdirectory for + tclConfig.sh and tkConfig.sh files. + +2001-05-30 Mo DeJong + + * cygtcl.m4: Add FIXME note. + * unix/configure: Regen. + * unix/tcl.m4 (SC_PATH_TCLCONFIG, SC_PATH_TKCONFIG): + Generate an error instead of a warning if the Tcl, or Tk + configuration files cannot be found. + +2001-05-26 Mo DeJong + + * cygtcl.m4 (TCL_TOOL_PATH, TCL_TOOL_LIB_LONGNAME, + TCL_TOOL_LIB_SHORTNAME, TCL_TOOL_LIB_SPEC): Create cross + platform versions of the TCL_TOOL* macros. + * unix/aclocal.m4: Include ../cygtcl.m4. + * unix/configure: Regen. + * unix/tcl.m4 (TCL_TOOL_PATH, TCL_TOOL_LIB_LONGNAME, + TCL_TOOL_LIB_SHORTNAME, TCL_TOOL_LIB_SPEC): Remove macros. + * win/aclocal.m4: Include ../cygtcl.m4. + * win/configure: Regen. + * win/tcl.m4 (TCL_TOOL_PATH, TCL_TOOL_LIB_LONGNAME, + TCL_TOOL_LIB_SHORTNAME, TCL_TOOL_LIB_SPEC): Remove macros. + +2001-05-24 Mo DeJong + + * unix/configure: Regen. + * unix/configure.in: Add missing TCL_LIB_FULL_PATH + variable. + +2001-05-11 Mo DeJong + + * unix/configure: + * unix/tcl.m4 (SC_ENABLE_SYMBOLS): + * win/configure: + * win/tcl.m4 (SC_ENABLE_SYMBOLS): Back port of CFLAGS_DEFAULT fix + from Tcl 8.4. A Makefile variable name is now used for the CFLAGS. + +2001-05-09 Mo DeJong + + * win/tcl.m4 (TCL_TOOL_PATH): Assign literal macro + value to a tmp variable before running cygpath + thus avoiding a problem with a quoted argument. + +2001-05-09 Mo DeJong + + * unix/Makefile.in: Use TCL_STUB_LIB_FILE instead of + STUB_LIB_FILE subst when defining STUB_LIB_FILE. + * unix/configure: Regen. + * unix/configure.in: Use new path macros. + * unix/tcl.m4 (TCL_TOOL_LIB_LONGNAME, TCL_TOOL_LIB_SHORTNAME, + TCL_TOOL_LIB_SPEC, TCL_TOOL_LIB_PATH): Add macros + to deal with library path translations. + * win/Makefile.in: Add FIXME note. + * win/configure: Regen. + * win/configure.in: Use new path macros. + * win/tcl.m4 (TCL_TOOL_LIB_LONGNAME, TCL_TOOL_LIB_SHORTNAME, + TCL_TOOL_LIB_SPEC, TCL_TOOL_LIB_PATH): Add macros + to deal with library path translations. + +2001-04-09 Mo DeJong + + * unix/configure: Regen. + * unix/tcl.m4: Add placeholder TCL_TOOL_PATH macro. + * win/configure: Regen. + * win/configure.in: Set TCL_LIB_FLAG, TCL_BUILD_LIB_SPEC, + TCL_LIB_SPEC, TCL_LIB_FULL_PATH and subst them. + * win/tcl.m4: Add TCL_TOOL_PATH macro, it will call + cygpath -w and replace \ with / to create a native + Windows path that VC++ will understand. + * win/tclConfig.sh.in: Add TCL_LIB_FULL_PATH variable. + +2001-04-05 Mo DeJong + + * win/configure: Regen. + * win/configure.in: Subst the TCL_LIB_VERSIONS_OK variable. + * win/tcl.m4: Add Cygnus local search for tcl8.1/win directory. Add + TCL_LIB_VERSIONS_OK variable, it will get substituted into the + tclConfig.sh file. Remve the SC_PROG_TCLSH macro. + +2001-04-05 Mo DeJong + + * generic/tclAlloc.c: + * win/tclWinPort.h: + Check for #define of WIN32 instead of VC++ specific symbol. + +2001-03-31 Mo DeJong + + * unix/Makefile.in: Remove second + assignment to SCRIPT_INSTALL_DIR + variable. This seems to have been + a merge error. It was installing + Tcl lib files in the lib directory + instead of share/tcl8.3. + +2001-03-28 Ian Roxborough + + * unix/tclConfig.sh.in: Set TCL_CFLAGS to CFLAGS, + otherwise tclConfig.sh won't work correctly. + +2000-09-15 Syd Polk + + * Updated for the 8.3.2 release. + +2000-08-08 Jeff Hobbs + + 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 + + * 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 + + * 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 + + * 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 + + * 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-26 Syd Polk + + * win/tcl.m4: Building libraries is significantly different on Cygwin + now; rewhacked. + * win/configure.in: Ditto. + * win/Makefile.in: Ditto. + * win/configure: Regenerated. + * win/tclWinPort.h: tchar.h and direct.h are not defined on Cygwin, + nor or they needed. + + +2000-07-25 Brent Welch + + * unix/Makefile.in: Need to install all the Tcl headers because + Itcl depends on internal headers. + +2000-07-25 Andreas Kupries + + * 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 + + * 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 + + * win/Makefile.in: Added rules for static tcldde and tclreg libraries. + +2000-07-17 Jeff Hobbs + + * 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 + + * 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 + + * win/tclConfig.sh.in: Cleaned up unix-specific autoconf variables. + +2000-07-11 Jeff Hobbs + + * 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 + + * 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 + + * 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-16 Syd Polk + + * generic/tclEnv.c win/tclWin32Dll.c: Fix impurePtr to work with + modern Cygwin. + * win/tcl.m4: Use --compat-implib. + * win/configure: Regenerate. + +2000-06-02 Jeff Hobbs + + * 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 + + * 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 + + * 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 + + 8.3.1 RELEASE + + * README: + * mac/README: + * tools/tcl.wse.in: + * unix/README: + * unix/tcl.spec: + * win/README: + * win/README.binary: Updating URLs to reference dev.scriptics.com + +2000-04-25 Jeff Hobbs + + * unix/Makefile.in: + * win/Makefile.in: + * win/makefile.vc: updated for http change and some cleanup + * library/http2.[13]: moved dir http2.1 to http2.3 to match version + + * doc/Utf.3: clarified docs for Tcl_(UniChar|Utf)AtIndex + + * unix/tclUnixThrd.c: removed {}s around PTHREAD_MUTEX_INITIALIZER + [Bug: 5254] + + * unix/tclLoadDyld.c (TclpLoadFile): removed use of interp->result + +2000-04-25 Eric Melski + + * unix/mkLinks: + * doc/AddErrInfo.3: Added information about Tcl_LogCommandInfo + [Bug: 1818]. + +2000-04-24 Eric Melski + + * unix/mkLinks: + * doc/OpenFileChnl.3: Added man entry for Tcl_Ungets [Bug: 1834]. + + * unix/mkLinks: + * doc/SourceRCFile.3: Man page for Tcl_SourceRCFile [Bug: 1833]. + + * unix/mkLinks: + * doc/ParseCmd.3: Added documentation for Tcl_ParseVar [Bug: 1828]. + +2000-04-24 Jeff Hobbs + + * unix/tclUnixNotfy.c (Tcl_FinalizeNotifier, NotifierThreadProc): + added write of 'q' into triggerPipe for notifier in threaded case, + so that Tcl doesn't hang when children are still running [Bug: 4139] + + * unix/tclUnixThrd.c (Tcl_MutexLock): minor comment fixes. + +2000-04-23 Jim Ingham + + These changes make some error handling marginally better for Mac + sockets. It is still somewhat flakey, however. + + * mac/tclMacSock.c (TcpClose): Add timeouts to the close - these + don't seem to be honored, however. + Use a separate PB for the release, since an async connect socket + will still be using the original buffer. + Make sure TCPRelease returns noErr before freeing the recvBuff. + If the call returns an error, then the buffer is not right. + * mac/tclMacSock.c (CreateSocket): Add timeouts to the async + create. These don't seem to trigger, however. Sigh... + * mac/tclMacSock.c (WaitForSocketEvent): If an TCP_ASYNC_CONNECT + socket errors out, then return EWOULDBLOCK & error out. + * mac/tclMacSock.c (NotifyRoutine): Added a NotifyRoutine for + experimenting with MacTCP. + +2000-04-22 Jim Ingham + + * library/package.tcl (tclPkgUnknown): Fixed a typo in the Mac package + search part of tclPkgUnknown. + +2000-04-21 Sandeep Tamhankar + + * library/http2.1/http.tcl: Fixed a newly introduced bug where if + there's a -command callback and something goes wrong, geturl threw + an exception, called the callback, and unset the token. I changed + it so that it will not call the callback when throwing an + exception (so the caller only finds out about a given error from + one place). Also, fixed http::ncode so that it actually gives you + back the http return code (i.e. 200, 404, etc.) instead of the + first digit of the version of HTTP being used (i.e. 1). + +2000-04-21 Brent Welch + + * library/http2.1/http.tcl: More thrashing with the "server closes + without reading post data" scenario. Reverted to the previous + filevent configuratiuon, which seems to work better with small + amounts of post data. + +2000-04-20 Jeff Hobbs + + * generic/tclAlloc.c: wrapped caddr_t define to not be done on Unix + * unix/tclUnixPort.h: added Tclp*Alloc defines to allow the use of + USE_TCLALLOC on Unix. [Bug: 4731] + +2000-04-19 Jeff Hobbs + + * library/dde1.1/pkgIndex.tcl: + * library/reg1.0/pkgIndex.tcl: + * win/tclWinChan.c: + * win/tclWinThrd.c: converted CRLF to LF the */tcl.hpj.in files + were not converted, as it confuses hcw locally. [Bug: 5096] + + * win/Makefile.in: expanded cleanup target for help files + + * doc/Thread.3: minor macro cleanup + + * generic/tclFileName.c (SplitUnixPath): added support for QNX + node ids. + +2000-04-18 Jeff Hobbs + + * README: + * generic/tcl.h: + * tools/tcl.wse.in: + * unix/configure.in: + * unix/tcl.spec: + * win/configure.in: + * win/README.binary: bumped version to 8.3.1 + + * win/tcl.hpj.in: updated copyright date + + * generic/tclEnv.c: environment support for Mac OS/X + * unix/tclUnixPort.h: environment support for Mac OS/X + * unix/tclLoadDyld.c: new file for Mac OS/X dl functions + * unix/Makefile.in: added install-strip target; bindir, libdir, + mandir, includedir vars; tclLoadDyld.c target [Bug: 2527] + + * unix/tclUnixChan.c (CreateSocket): force a socket back into + blocking mode (default state) after a -async connect succeeds. + [Bug: 4388] + + * generic/tclEvent.c (TclInitSubsystems): Moved tclLibraryPath to + thread-local storage to prevent thread-related race condition. + [Bug: 5033] + * unix/tclAppInit.c (main): removed #ifdef TCL_TEST that sets the + library path as it was unnecessary and conflicts with move of + tclLibraryPath to thread-local storage. + +2000-04-18 Scott Redman + + * win/Makefile.in: + * win/tcl.rc: + * win/tclsh.rc: + * win/tclsh.ico: Modified copyright dates in Windows resource + files. Added an icon for tclsh.exe. + +2000-04-17 Brent Welch + + * generic/tcl.h, generic/tclThreadTest.c, unix/tclUnixThrd.c, + win/tclWinThread.c, mac/tclMacThread.c: + Added Tcl_CreateThreadType and TCL_RETURN_THREAD_TYPE + macros for declaring the NewThread callback proc. + +2000-04-14 Jeff Hobbs + + * unix/tclUnixChan.c (TtyParseMode): Only allow setting mark/space + parity on platforms that support it [Bug: 5089] + + * generic/tclBasic.c (Tcl_GetVersion): adjusted use of major/minor + to not conflict with global decl on some systems [Bug: 2882] + + * doc/AppInit.3: + * doc/Async.3: + * doc/BackgdErr.3: + * doc/CrtChannel.3: + * doc/CrtInterp.3: + * doc/CrtMathFnc.3: + * doc/DString.3: + * doc/Eval.3: + * doc/ExprLong.3: + * doc/GetInt.3: + * doc/GetOpnFl.3: + * doc/Interp.3: + * doc/LinkVar.3: + * doc/OpenFileChnl.3: + * doc/OpenTcp.3: + * doc/PkgRequire.3: + * doc/RecordEval.3: + * doc/SetResult.3: + * doc/SplitList.3: + * doc/StaticPkg.3: + * doc/TraceVar.3: + * doc/Translate.3: + * doc/UpVar.3: + * doc/load.n: removed or updated references to interp->result use. + +2000-04-13 Jeff Hobbs + + * doc/regexp.n: doc clarification [Bug: 5037] + * doc/update.n: typo fix [Bug: 4996] + + * unix/tcl.m4 (SC_ENABLE_THREADS): enhanced the detection of + pthread_mutex_init [Bug: 4359] and (SC_CONFIG_CFLAGS) added + --enable-64bit-vis switch for Sparc VIS compilation [Bug: 4995] + +2000-04-12 Jeff Hobbs + + * doc/dde.n: corrected dde poke docs. [Bug: 4991] + +2000-04-11 Eric Melski + + * win/tclWinPipe.c: Added "CONST" keyword to declaration of char + *native in TclpCreateTempFile, to supress compiler warnings. + +2000-04-10 Brent Welch + + * generic/tcl.h: Fixed Tcl_CreateThread declaration. + * library/tcltest1.0/tcltest.tcl: Fixed the "mainThread" + initialization to work with either testthread or the thread extension + * unix/tclUnixThrd.c: Fixed compiler warning when compiling + with -DTCL_THREADS + +2000-04-10 Eric Melski + + * win/tclWinPipe.c (TclpCreateTempFile): Added conversion of + contents string from UTF to native encoding [Bug: 4030]. + + * tests/regexp.test: Added tests for infinite looping in [regexp + -all]. + + * generic/tclCmdMZ.c: Fixed infinite loop bug with [regexp -all] + [Bug: 4981]. + + * tests/*.test: Changed all occurances of "namespace import + ::tcltest" to "namespace import -force ::tcltest" [Bug: 3948]. + +2000-04-09 Brent Welch + + * lib/httpd2.1/http.tcl: Worked on the "server closes before + reading post data" case, which unfortunately causes different + error cases on Solaris, which can read the reply, and Linux + and Windows, which cannot read anything. This is all in the + loop-back case - client and server on the same host. Also + unified the error handling so the "ioerror" status goes away + and errors are reflected in a more uniform way. Updated the + man page to document the behavior. + +2000-04-09 Jeff Hobbs + + * tests/reg.test (matchexpected): corrected tests to use tcltest + constraint types to skip certain tests. + + * generic/tclBasic.c (Tcl_SetCommandInfo): comment fix + + * unix/tclUnixThrd.c (Tcl_CreateThread): moved TCL_THREADS ifdef + inside of func as it is declared for non-threads builds as well. + In the non-threads case, it always returns TCL_ERROR (couldn't + create thread). + +2000-04-08 Andreas Kupries + + * Overall change: Definition of a public API for the creation of + new threads. + + * generic/tclInt.h (line 1802f): Removed the definition of + 'TclpThreadCreate'. (line 793f) Removed the definition of + 'Tcl_ThreadCreateProc'. + + * generic/tcl.h (line 388f): Readded the definition of + 'Tcl_ThreadCreateProc'. Added Win32 stuff send in by David + Graveraux to that too (__stdcall, + ...). Added macros for the default stacksize and allowed flags. + + * generic/tcl.decls (line 1356f): Added definition of + 'Tcl_CreateThread', slot 393 of the stub table. Two new + arguments in the public API, for stacksize and flags. + + * win/tclWinThrd.c: + * mac/tclMacThrd.c: Renamed TclpThreadCreate to Tcl_CreateThread, + added handling of the stacksize. Flags are currently ignored. + + * unix/tclUnixThrd.c: See above, but handles joinable + flag. Ignores the specified stacksize if the macro + HAVE_PTHREAD_ATTR_SETSTACKSIZE is not defined. + + * generic/tclThreadTest.c (line 363): See below. + + * unix/tclUnixNotfy.c (line 210): Adapted to the changes + above. Uses default stacksize and no flags now. + + * unic/tcl.m4 (line 382f): Added a check for + 'pthread_attr_setstacksize' to detect platforms not implementing + this feature of pthreads. If it is implemented, configure will + define the macro HAVE_PTHREAD_ATTR_SETSTACKSIZE (See + unix/tclUnixThrd.c too). + + * doc/Thread.3: Added Tcl_CreateThread and its arguments to the + list of described functions. Removed stuff about not providing a + public C-API for thread-creation. + +2000-04-07 Jeff Hobbs + + * doc/binary.n: clarified docs on sign extension in binary scan + [Bug: 3466] + + * library/tcltest1.0/tcltest.tcl (initConstraints): removed win32s + references (no longer supported) + + * tests/fCmd.test: marked test 8.1 knownBug because it is + dangerous on poorly configured systems [Bug: 3881] + and added 8.2 to keep essence of 8.1 tested. + +2000-04-05 Andreas Kupries + + * generic/tclIO.c (Tcl_UnstackChannel, line 1831): Forcing + interest mask to the correct value after an unstack and + re-initialization of the notifier via the watchProc. Without this + the first fileevent after an unstack will come through and be + processed, but no more. [Bug: ??]. + +2000-03-04 Brent Welch + + * {win,unix}/Makefile.in: added dependency of tclStubInit.c on + tcl.decls and tclInt.decls + * generic/tclThread.c: Tweak so this compiles w/out TCL_THREADS + * generic/{tcl.decls,tclStubInit.c}: Just touched the tcl.decls and + regenerated the tclStubInit.c file + +2000-03-29 Sandeep Tamhankar + + * library/http2.1/http.tcl: For the -querychannel option, + fconfigure the socket to be binary so that we don't translate + anything while reading the data. This is because we determine the + content length of the data on the channel by using seek (to the end + of the file) and tell on the file handle, and we need the + content-length to match the amount of data actually sent, and + translation can affect the number of bytes posted. + +2000-04-03 Andreas Kupries + + * Overall change: Definition of public API's for the finalization + of conditions and mutexes. [Bug: 4199]. + + * generic/tclInt.h: Removed definitions of TclFinalizeMutex and + TclFinalizeCondition. + + * generic/tcl.decls: Added declarations of Tcl_MutexFinalize and + Tcl_ConditionFinalize. + + * generic/tclThread.c: Renamed TclFinalizeMutex to + Tcl_MutexFinalize. Renamed TclFinalizeCondition to + Tcl_ConditionFinalize. + + * generic/tclNotify.c: Changed usage of TclFinalizeMutex to + Tcl_MutexFinalize. + + * unix/tclUnixNotfy.c: + * generic/tclThreadTest.c: Changed usages of TclFinalizeCondition to + Tcl_ConditionFinalize. + + * generic/tcl.h: Added empty macros for Tcl_MutexFinalize and + Tcl_ConditionFinalize, to be used when the core is compiled + without threads. + + * doc/Thread.3: Added description the new API's. + +2000-04-03 Jeff Hobbs + + * generic/tclCmdIL.c (InfoVarsCmd): checked for non-NULL procPtr + to prevent itcl info override crash [Bug: 4064] + + * tests/foreach.test: + * tests/namespace.test: + * tests/var.test: Added lsorts to avoid random sorted return + problems. [Bug: 2682] + + * tests/fileName.test: fixed 14.1 test fragility [Bug: 1482] + + * tools/man2help2.tcl: fixed winhelp cross-linking error [Bug: 4156] + improved translation to winhelp [Bug: 3679] + + * unix/Makefile.in (MAN_INSTALL_DIR): patch to accept --mandir + correctly [Bug: 4085] + + * unix/dltest/pkg[a-e].c: Cleaned up test packages [Bug: 2293] + +2000-04-03 Eric Melski + + * unix/tclUnixFCmd.c (SetGroupAttribute): + * unix/tclUnixFCmd.c (SetOwnerAttribute): Added (uid_t) and (gid_t) + casts to avoid compiler warnings. + +2000-03-31 Eric Melski + + * generic/tclGet.c (Tcl_GetDouble): Added additional conditions to + error test (previously only errno was checked, but the return + value of strtod() should be checked as well). [Bug: 4118]. + + * tests/exec.test: Added test for proper conversion of UTF data + when used with "<< $dataWithUTF" on exec's. + + * unix/tclUnixPipe.c (TclpCreateTempFile): Added + Tcl_UtfToExternalDString call, so that if there is UTF content in + the string it will be properly converted to the system encoding + before being written [Bug: 4030]. + (TclpCreateTempFile): Added a check on the return value of tmpnam; + some systems (Linux, for example) will start to return NULL after + tmpnam has been called TMP_MAX times; not checking for this can + have bad results (overwriting temp files, core dumps, etc.) + +2000-03-30 Jeff Hobbs + + * generic/tclBasic.c (Tcl_DeleteCommandFromToken): Added comments + noting the need to pair ckalloc with ckfree. [Bug: 4262] + + * generic/tclInt.decls: + * generic/tclIntPlatDecls.h: + * generic/tclStubInit.c: + * win/tclWin32Dll.c: removed TclWinSynchSpawn (vestige of Win32s + support). + + * win/tclWinReg.c: made use of TclWinGetPlatformId instead of + getting info again + + * win/tclWinPort.h: + * win/Makefile.in: + * win/configure.in: + * win/tcl.m4: Added support for gcc/mingw on Windows [Bug: 4234] + +2000-03-29 Jeff Hobbs + + * generic/tclCompile.c (TclCleanupByteCode): made ByteCode cleanup + more aware of TCL_BYTECODE_PRECOMPILED flagged structs (gen'd by + tbcload), to correctly clean them up. + + * generic/tclClock.c (FormatClock): moved check for empty format + earlier, commented 0 result return value + +2000-03-29 Sandeep Tamhankar + + * library/http2.1/http.tcl: Removed an unnecessary fileevent + statement from the error processing part of the Write method. + Also, fixed two potential memory leaks in wait and reset, in which + the state array wasn't being unset before throwing an exception. + Prior to this version, Brent checked in a fix to catch a + fileevent statement that was sometimes causing a stack trace when + geturl was called with -timeout. I believe Brent's fix is + necessary because TLS closes bad sockets for secure connections, + and the fileevent was trying to act on a socket that no longer + existed. + +2000-03-27 Jeff Hobbs + + * tests/httpd: removed unnecessary 'puts stderr "Post Dispatch"' + + * tests/namespace.test: + * generic/tclNamesp.c (Tcl_Export): added a uniq'ing test to the + export list so only one instance of each export pattern would + exist in the list. + + * generic/tclExecute.c (TclExecuteByteCode): optimized case for + the empty string in ==/!= comparisons + +2000-03-27 Eric Melski + + * unix/tclUnixChan.c: Added (off_t) type casts in lseek() call + [Bug: 4409]. + + * unix/tclLoadAout.c: + * unix/tclUnixPipe.c: Added (off_t) type casts in lseek() calls + [Bug: 4410]. + +2000-03-22 Sandeep Tamhankar + + * library/http2.1/http.tcl: Fixed a bug where string query data + that was bigger than queryblocksize would get duplicate characters + at block boundaries. + +2000-03-22 Sandeep Tamhankar + + * library/http2.1/http.tcl: Fixed bug 4463, where we were getting + a stack trace if we tried to publish a project to a good host but + a port where there was no server listening. It turned out the + problem was a stray fileevent that needed to be cleared. Also, + fixed a bug where http::code could stack trace if called on a bad + token (one which didn't represent a successful geturl) by adding + an http element to the state array in geturl. + +2000-03-21 Eric Melski + + * tests/clock.test: Modified some tests that were not robust with + respect to the time zone in which they were run and were thus + failing. + + * doc/clock.n: Clarified meaning of -gmt with respect to -base + when used with [clock scan] (-gmt does not affect the + interpretation of -base). + +2000-03-19 Sandeep Tamhankar + + * library/http2.1/http.tcl: geturl used to throw an exception when + the connection failed; I accidentally returned a token with the + error info, breaking backwards compatibility. I changed it back + to throwing an exception, but unsetting the state array first + (thus still eliminating the original memory leak problem). + +2000-03-19 Sandeep Tamhankar + + * library/http2.1/http.tcl: Added -querychannel option and altered + some of Brent's modifications to allow asynchronous posts (via + -command). Also modified -queryprogress so that it calls the + query callback as + to be consistent with -progress. Added -queryblocksize option + with default 8192 bytes for post blocksize. Fixed a bunch of + potential memory leaks for the case when geturl receives bad args + or can't open a socket, etc. Overall, the package really rocks + now. + + * doc/http.n: Added -queryblocksize, -querychannel, and + -queryprogress. Also, changed the description of -blocksize, + which states that the -progress callback will be called for each + block, to now qualify that with an "if -progress is specified". + + * tests/http.test: Added a querychannel test for synchronous and + asynchronous posts, altered the queryprogress test such that the + callback conforms to the -progress format. Also, had to use the + -queryblocksize option to do the post 16K at a time to match + Brent's expected results (and to test that -queryblocksize works). + +2000-03-15 Brent Welch + + * library/http2.1/http.tcl: Added -queryprogress callback to + http::geturl and also changed it so that writing the post data + is event driven if the queryprogress callback or a timeout is given. + This allows a timeout to occur when writing lots of post data. + The queryprogress callback is called after each block of query + data is posted. It has the same signature as the -progress callback. + +2000-03-06 Eric Melski + + * library/package.tcl: Applied patch from Bug: 2570; rather than + setting geometry of slave interp to 0x0 when Tk was loaded, it now + does "wm withdraw .". Both remove the main window from the + display, but the former caused some internal structures to get + initialized to zero, which caused crashes with some extensions. + +2000-03-02 Jeff Hobbs + + * library/package.tcl (tclPkgUnknown): extended to allow + recognizes changes in the auto_path while sourcing in other + pkgIndex.tcl files + + * doc/FindExec.3: fixed doc for declaration of Tcl_FindExecutable + [Bug: 4275] + + * generic/tclFileName.c (Tcl_TranslateFileName): Applied patch + from Newman to significantly speedup file split/join on Windows + (replaces regexp with custom parser). [Bug: 2867] + + * win/README.binary: change mailing lists from @consortium.org + to @scriptics.com [Bug: 4173] + +2000-02-28 Eric Melski + + * tests/clock.test: Added test for ISO bases < 100000 + + * generic/tclDate.c: (generated on Solaris) + * generic/tclGetDate.y: Changed condition for deciding if a number + is an ISO 8601 base from number >= 100000 to numberOfDigits >= 6. + Previously it would fail to recognize 000000 as an ISO base. + +2000-02-14 Eric Melski + + * unix/Makefile.in: Added rpm target to generate Tcl binary RPM. + + * unix/tcl.spec: RPM specification file for a Tcl binary RPM for + Linux. + +2000-02-10 Jeff Hobbs + + 8.3.0 RELEASE + + * changes: updated for 8.3.0 release + + * doc/load.n: added notes about dll load errors on Windows + + * unix/README: + * unix/Makefile.in (dist): removed porting.notes and porting.old + from distribution and CVS. The information was very outdated. Now + refer to http://dev.scriptics.com/services/support/platforms.html + + * tests/unixInit.test: fixed japanese LANG encoding test [Bug: 3549] + + * unix/configure.in: + * unix/tcl.m4: correct CFLAG_WARNING setting, + fixed gcc config for AIX, + added -export-dynamic to LDFLAGS for FreeBSD-3+ [Bug: 2998] + + * win/tclWinLoad.c (TclpLoadFile): improved error message for load + failures, could perhaps be even more intelligent. + +2000-02-09 Jim Ingham + + * mac/tclMacSock.c: Don't panic when you get an error closing an async + socket. This doesn't seem to hurt anything, and we return the error so + the caller can do the right thing. + + New Files: + * mac/MW_TclHeader.h: + * mac/MW_TclTestHeader.h: + * mac/MW_TclTestHeader.pch: + * mac/MW_TclAppleScriptHeader.h: More convenient to use .h prefix files + in the preference panels... + + The above are curtesy of Daniel Steffen (steffen@math.mq.edu.au) + +2000-02-08 Eric Melski + + * tests/clock.test: Added tests for "next monthname" constructs. + * generic/tclDate.c: + * generic/tclGetDate.y (Message): Added a grammar rule for "next + monthname" so that we can handle "next january" and similar + constructs (bug #4146). + +2000-02-08 Jeff Hobbs + + * README: + * tools/tcl.wse.in: + * unix/configure.in: + * win/configure.in: + * win/README: + * win/README.binary: + * generic/tcl.h (TCL_RELEASE_SERIAL): Moved to 8.3.0 patchlevel + + * doc/library.n: + * library/auto.tcl: fixed crufty puts code and docs [Bug: 4122] + + * library/tcltest1.0/tcltest.tcl: correctly protected searchDirectory + list to allow dirnames with spaces + + * unix/tcl.m4: changed all -fpic to -fPIC + + * generic/tclDecls.h: + * generic/tcl.decls: change Tcl_GetOpenFile to use decl of 'int + forWriting' instead of 'int write' to avoid shadowing [Bug: 4121] + + * tests/httpold.test: changed test script to source in the httpd + server procs from httpd instead of having its own set. + + * tests/httpd: improved query support in test httpd to handle fix + in http.tcl. [Bug: 4089 change 2000-02-01] + + * unix/README: fixed notes about --enable-shared and add note + about --disable-shared. + +2000-02-07 Eric Melski + + * tests/package.test: + * library/tclIndex: + * library/package.tcl: Renamed ::package namespace to ::pkg. + +2000-02-03 Eric Melski + + * doc/Package.n: + * doc/packagens.n: Renamed Package.n -> packagens.n because Windows + can't deal with case-sensitive names. + +2000-02-02 Jeff Hobbs + + * tests/regexp.test: added tests for -all and -inline switches + * doc/regexp.n: added docs for -all and -inline switches + * generic/tclCmdMZ.c (Tcl_RegexpObjCmd): added extra comments for + new -all and -inline switches to regexp command + +2000-02-01 Eric Melski + + * library/init.tcl: Applied patch from rfe 1734 regarding + auto_load errors not setting error message and errorInfo properly. + +2000-02-01 Jeff Hobbs + + * win/Makefile.in (install-*): reduced verbosity of install + + * generic/tclFileName.c (Tcl_JoinPath): improved support for special + QNX node id prefixes in pathnames [Bug: 4053] + + * library/http1.0/http.tcl: + * library/http2.1/http.tcl: The query data POSTed was newline + terminated when it shouldn't be altered [Bug: 4089] + +2000-01-31 Eric Melski + + * tests/package.test: + * library/tclIndex: + * library/package.tcl: Added ::package namespace and + ::package::create function. + + * library/init.tcl: Fixed problem with auto_load and determining + if commands were loaded. + + * library/auto.tcl: "Fixed" issues with $ in files to be auto indexed. + + * doc/Package.n: New man page for package::create function. + + * doc/pkgMkIndex.n: Added additional information. + + * doc/library.n: Added additional qualification regarding auto_mkindex. + +2000-01-28 Eric Melski + + * tests/pkg/magicchar2.tcl: + * tests/autoMkindex.test: Test for auto loader fix (bug #2480). + + * library/init.tcl: auto_load was using [info commands $name] to + determine if a given command was available; if the command name + had * or [] it, this would fail because info commands uses + glob-style matching. This is fixed. (Bug #2480). + + * tests/pkg/spacename.tcl: + * tests/pkgMkIndex.test: Tests for fix for bug #2360. + + * library/package.tcl: Fixed to extract only the first element of + the list returned by auto_qualify (bug #2360). + + * tests/pkg/magicchar.tcl: + * tests/autoMkindex.test: Test for fix for bug #2611. + + * library/auto.tcl: Fixed the regular expression that performs $ + escaping before sourcing a file to index. It was erroneously + adding \ escapes even to $'s that were already escaped, + effectively "un-escaping" those $'s. (bug #2611). + +2000-01-27 Eric Melski + + * tests/autoMkindex.test: + * library/auto.tcl: Applied patch (with slight modification) from + bug #2701: auto_mkIndex uses platform dependent file paths. + Added test for fix. + +2000-01-27 Jennifer Hom + + * library/tcltest1.0/tcltest.tcl: Changed NormalizePath to + normalizePath and exported it as a public proc. This proc + creates an absolute path given the name of the variable containing + the path to modify. The path is modified in place. + * library/tcltest1.0/pkgIndex.tcl: Added normalizePath. + * tests/all.tcl: Changed code to use normalizePath. + +2000-01-27 Eric Melski + + * tests/pkg/samename.tcl: test file for bug #1983 + + * tests/pkgMkIndex.test: + * doc/pkgMkIndex.n: + * library/package.tcl: Per rfe #4097, optimized creation of direct + load packages to bypass computing the list of commands added by + the new package. Also made direct loading the default, and added + a -lazy option. + Fixed bug #1983, dealing with pkg_mkIndex incorrectly handling + situations with two procs by the same name but in different + namespaces (ie, foo::baz and bar::baz). + +2000-01-26 Eric Melski + + * generic/tclNamesp.c: Undid fix for #956, which broke backwards + compatibility. + + * doc/variable.n: + * doc/trace.n: + * doc/namespace.n: + * doc/info.n: Added further information about differences between + "namespace which" and "info exists". + + * doc/SetErrno.3: Added descriptions of ErrnoId() and ErrnoMsg() + functions. + +2000-01-25 Jeff Hobbs + + * unix/tcl.m4: modified EXTRA_CFLAGS to add -DHAVE_TZSET for + OSF1-V* and ULTRIX-4.* when not using gcc. Also added higher min + stack size for OSF1-V* when building with threads. [Bug: 4063] + + * generic/tclClock.c (FormatClock): inlined resultPtr, as it + conflicted with var creation for HAVE_TZSET #def [Bug: 4063] + + * generic/tclCmdIL.c (Tcl_LsortObjCmd): fixed potential leak + when calling lsort -command with bad command [Bug: 4067] + + * generic/tclFileName.c (Tcl_JoinPath): added support for special + QNX node id prefixes in pathnames [Bug: 4053] + + * doc/ListObj.3: clarified Tcl_ListObjGetElements docs [Bug: 4080] + + * doc/glob.n: clarified Mac path separator determination docs. + + * win/makefile.vc: added some support for building helpfile on Windows + +2000-01-23 Jeff Hobbs + + * library/init.tcl (auto_execok): added 'start' to list of + recognized built-in commands for COMSPEC on NT. [Bug: 2858] + + * unix/tclUnixPort.h: moved include of lower since some + systems (UTS) require sys/types.h to be included first [Bug: 4031] + + * unix/tclUnixChan.c (CreateSocketAddress): changed comparison + with -1 to 0xFFFFFFFF, to ensure 32 bit comparison even on 64 bit + systems. [Bug: 3878] + + * generic/tclFileName.c: improved guessing of path separator + for the Mac. (Darley) + + * generic/tclInt.h: + * generic/tcl.decls: moved Tcl_ProcObjCmd to stubs table [Bug: 3827] + and removed 'register' from stub definition of + Tcl_AppendUnicodeToObj [Bug: 4038] + +2000-01-21 Eric Melski + + * unix/mkLinks: + * doc/GetHostName.3: Man page for Tcl_GetHostName (bug #1817). + + * doc/lreplace.n: Corrected man page with respect to treatment of + empty lists, and "prettied up" the page. (bug #1705). + +2000-01-20 Eric Melski + + * tests/namespace.test: Added test for undefined variables with + namespace which (bug #956). + + * generic/tclNamesp.c: Added check for undefined variables in + NamespaceWhichCmd (bug #956). + + * tests/var.test: Added tests for corrected variable behavior + (bug #981). + + * doc/upvar.n: Expanded explanation of upvar behavior with respect to + variable traces. (bugs 3917 1433 2110). + + * generic/tclVar.c: Changed behavior of variable command when name + refers to an element in an array (ie, "variable foo(x)") to always + return an error, regardless of existance of that element in the + array (now behavior is consistant with docs too) (bug #981). + +2000-01-20 Jeff Hobbs + + * generic/tclCmdIL.c (InfoBodyCmd): made [info body] return a + string if the body has been bytecompiled. + * generic/tclBasic.c (Tcl_EvalObjEx): added pedantic check for + originating proc body of bytecompiled code, #def'd out as the + change for [info body] should make it unnecessary + + * unix/tclUnixNotfy.c (Tcl_InitNotifier): added cast for tsdPtr + + * tests/set.test: added test for complex array elem name compiling + * generic/tclCompCmds.c (TclCompileSetCmd): Fixed parsing of array + elements during compiling, and slightly optimised same [Bug: 3889] + + * doc/tclvars.n: added definitions for tcl_(non)wordchars + + * doc/vwait.n: added notes about requirement for vwait var being + globally scoped [Bug: 3329] + + * library/word.tcl: changed tcl_(non)wordchars settings to use + new unicode regexp char class escapes instead of char sequences + +2000-01-14 Eric Melski + + * tests/var.test: Added a test for the array multiple delete + protection in Tcl_UnsetVar2. + + * generic/tclVar.c: Added protection in Tcl_UnsetVar2 against + attempts to multiply delete arrays when unsetting them (bug + #3453). This could happen if there was an unset trace on an array + element and the trace proc made a global or upvar link to the + array, and then the array was unset at the global level. See the + bug reference for more information. + + * unix/tclUnixTime.c: New clock format format. + + * compat/strftime.c: New clock format format. + + * generic/tclGetDate.y: New clock scan format. + +2000-01-13 Jeff Hobbs + + * changes: updated changes file to reflect 8.3b2 mods + + * README: + * generic/tcl.h: + * tools/tcl.wse.in: + * unix/configure.in: + * unix/tcl.m4: + * win/README.binary: + * win/configure.in: updated to patchlevel 8.3b2 + + * generic/regexec.c: added var initialization to prevent compiler + warning + +2000-01-13 Eric Melski + + * tests/cmdIL.test: Added tests for lsort -dictionary with + characters that occur between Z and a in ASCII. + + * generic/tclCmdIL.c: Modified DictionaryCompare function (used by + lsort -dictionary) to do upper/lower case equivalency before doing + character comparisons, instead of after. This fixes bug #1357, in + which lsort -dictionary [list ` AA c CC] and lsort -dictionary + [list AA c ` CC] gave different (and both wrong) results. + +2000-01-12 Eric Melski + + * tests/clock.test: Added tests for "next " and + "" + Added tests for "monday 1 week ago", etc, from RFE #3671. + + * doc/tests/clock.test: Added numerous tests for clock scan. + + * doc/generic/tclGetDate.y: Fixed some shift/reduce conflicts in + clock grammar. + + * doc/doc/clock.n: Added documentation for new supported clock + scan formats and additional explanation of daylight savings time + correction algorithm. + +2000-01-12 Jeff Hobbs + + * doc/file.n: + * tests/unixFCmd.test: + * unix/tclUnixFCmd.c: added support for symbolic permissions + setting in SetPermissionsAttribute (file attr $file -perm ...) + [Bug: 3970] + + * generic/tclClock.c: fixed support for 64bit handling of clock + values [Bug: 1806] + + * generic/tclThreadTest.c: upped a buffer size to hold double + + * tests/info.test: + * generic/tclCmdIL.c: fixed 'info procs ::namesp::*' behavior (Dejong) + + * generic/tclNamesp.c: made imported commands also import their + compile proc [Bug: 2100] + + * tests/expr.test: + * unix/Makefile.in: + * unix/configure.in: + * unix/tcl.m4: recognize strtod bug on Tru64 v5.0 [Bug: 3378] + and added tests to prevent unnecessary chmod +x in sources while + installing, as well as more intelligent setsockopt/gethostbyname + checks [Bug: 3366, 3389] + + * unix/tclUnixThrd.c: added compile time support (through use of + the TCL_THREAD_STACK_MIN define) for increasing the default stack + size for a thread. [Bug: 3797, 1966] + +2000-01-11 Eric Melski + + * generic/tclGetDate.y: Added comments for the Convert function. + Added a fix for daylight savings time handling for relative time + spans of days, weeks or fortnights. (bug 3441, 3868). + + * generic/tclDate.c: Fixed compiler warning issues. + +2000-01-10 Jeff Hobbs + + * compat/waitpid.c: use pid_t type instead of int [Bug: 3999] + + * tests/utf.test: fixed test that allowed \8 as octal value + * generic/tclUtf.c: changed Tcl_UtfBackslash to not allow + non-octal digits (8,9) in \ooo substs. [Bug: 3975] + + * generic/tcl.h: noted need to change win/tcl.m4 and + tools/tclSplash.bmp for minor version changes + + * library/http2.1/http.tcl: trim value for $state(meta) key + + * unix/tclUnixFile.c: fixed signature style on functions + + * unix/Makefile.in: made sure tcl.m4 would be installed with dist + + * unix/tcl.m4: added ELF support for NetBSD [Bug: 3959] + +2000-01-10 Eric Melski + + * generic/tclGetDate.y: Added rules for ISO 8601 formats (BUG #847): + CCYY-MM-DD + CCYYMMDD + YY-MM-DD + YYMMDD + CCYYMMDDTHHMMSS + CCYYMMDD HHMMSS + CCYYMMDDTHH:MM:SS + Fixed "clock scan " to scan the number as an hour for the + current day, rather than a minute after 00:00 for the current day + (bug #2732). + + +2000-01-07 Eric Melski + + * generic/tclClock.c: Changed switch in Tcl_ClockObjCmd to use + enumerated values instead of constants. (ie, COMMAND_SCAN instead + of 3). + +1999-12-22 Jeff Hobbs + + * changes: updated changes file + * tools/tclSplash.bmp: updated to show 8.3 + +1999-12-21 Jeff Hobbs + + * README: + * generic/tcl.h: + * mac/README: + * unix/configure.in: + * tools/tcl.wse.in: + * win/README.binary: + * win/configure.in: updated to patch level 8.3b1 + + * unix/Makefile.in: added -srcdir=... for 'make html' + + * doc/Hash.3: fixed reference to ckfree [Bug: 3912] + * doc/RegExp.3: fixed calling params for Tcl_RegExecFromObj + * doc/open.n: fixed minor formatting errors + * doc/string.n: fixed minor formatting errors + + * doc/lsort.n: added -unique docs + * tests/cmdIL.test: + * generic/tclCmdIL.c: added -unique option to lsort + + * generic/tclThreadTest.c: changed thread ids to longs [Bug: 3902] + + * mac/tclMacOSA.c: fixed applescript for I18N [Bug: 3644] + + * win/mkd.bat: + * win/rmd.bat: removed necessity of tag.txt [Bug: 3874] + + * win/tclWinThrd.c: changed CreateThread to _beginthreadex and + ExitThread to _endthreadex + +1999-12-12 Jeff Hobbs + + * doc/glob.n: + * tests/fileName.test: + * generic/tclInt.decls: + * generic/tclInt.h: + * generic/tclIntDecls.h: + * generic/tclStubInit.c: + * generic/tclEncoding.c: + * generic/tclFileName.c: + * mac/tclMacFile.c: + * unix/tclUnixFile.c: + * win/tclWinFile.c: enhanced the glob command with the new options + -types -path -directory and -join. Deprecated TclpMatchFiles with + TclpMatchFilesTypes, extended TclGlob and TclDoGlob and added + GlobTypeData structure. [Bug: 2363] + +1999-12-10 Jeff Hobbs + + * tests/var.test: + * generic/tclCompile.c: fixed problem where setting to {} array + would intermittently not work. (Fontaine) [Bug: 3339] + + * generic/tclCmdMZ.c: + * generic/tclExecute.c: optimized INST_TRY_CVT_TO_NUMERIC to + recognize boolean objects. (Spjuth) [Bug: 2815] + + * tests/info.test: + * tests/parseOld.test: + * generic/tclCmdAH.c: + * generic/tclProc.c: changed Tcl_UplevelObjCmd (uplevel) and + Tcl_EvalObjCmd (eval) to use TCL_EVAL_DIRECT in the single arg + case as well, to take advantage of potential pure list input + optimization. This means that it won't get byte compiled though, + which should be acceptable. + * generic/tclBasic.c: made Tcl_EvalObjEx pure list object aware in + the TCL_EVAL_DIRECT case for efficiency. + * generic/tclUtil.c: made Tcl_ConcatObj pure list object aware, + and return a list object in that case [Bug: 2098 2257] + + * generic/tclMain.c: changed Tcl_Main to not constantly reuse the + commandPtr object (interactive case) as it could be shared. (Fellows) + + * unix/configure.in: + * unix/tcl.m4: + * unix/tclUnixPipe.c: removed checking for compatible vfork + function and use of the vfork function. Modern VM systems rarely + suffer any performance degradation when fork is used, and it + solves multiple problems with vfork. Users that still want vfork + can add -Dfork=vfork to the compile flags. [Bug: 942 2228 1312] + +1999-12-09 Jeff Hobbs + + * win/aclocal.m4: made it just include tcl.m4 + + * doc/exec.n: + * doc/open.n: + * win/tclWin32Dll.c: + * win/tclWinChan.c: + * win/tclWinFCmd.c: + * win/tclWinInit.c: + * win/tclWinPipe.c: + * win/tclWinSock.c: removed all code that supported Win32s. It + was no longer officially supported, and likely didn't work anyway. + * win/makefile.vc: removed 16 bit stuff, cleaned up. + + * win/tcl16.rc: + * win/tclWin16.c: + * win/winDumpExts.c: these files have been removed from the + source tree (no longer necessary to build) + +1999-12-07 Jeff Hobbs + + * tests/io.test: removed 'knownBug' tests that were for + unsupported0, which is now fcopy (that already has tests) + + * mac/tclMacPort.h: added utime.h include + + * generic/tclDate.c: + * unix/Makefile.in: fixed make gendate to swap const with CONST + so it uses the Tcl defined CONST type [Bug: 3521] + + * generic/tclIO.c: removed panic that could occur in FlushChannel + when a "blocking" channel would receive EAGAIN, instead treating + it the same as non-blocking. [Bug: 3773] + + * generic/tclUtil.c: fixed Tcl_ScanCountedElement to not step + beyond the end of the counted string [Bug: 3336] + +1999-12-03 Jeff Hobbs + + * doc/load.n: added note about NT's buggy handling of './' with + LoadLibrary + + * library/http2.1/http.tcl: fixed error handling in http::Event + [Bug: 3752] + + * tests/env.test: removed knownBug limitation from working test + * tests/all.tcl: ensured that ::tcltest::testsDirectory would be + set to an absolute path + + * tests/expr-old.test: + * tests/parseExpr.test: + * tests/string.test: + * generic/tclGet.c: + * generic/tclInt.h: + * generic/tclObj.c: + * generic/tclParseExpr.c: + * generic/tclUtil.c: + * generic/tclExecute.c: added TclCheckBadOctal routine to enhance + error message checking for when users use invalid octal numbers + (like 08), as well as replumbed the Expr*Funcs with a new + VerifyExprObjType to simplify type handling. [Bug: 2467] + + * tests/expr.test: + * generic/tclCompile.c: fixed 'bad code length' error for + 'expr + {[incr]}' case, with new test case [Bug: 3736] + and seg fault on 'expr + {[error]}' (different cause) that + was caused by a correct optimization that didn't correctly + track how it was modifying the source string in the opt. + The optimization was removed, which means that: + expr 1 + {[string length abc]} + will be not be compiled inline as before, but this should be + written: + expr {1 + [string length abc]} + which will be compiled inline for speed. This prevents + expr 1 + {[mindless error]} + from seg faulting, and only affects optimizations for + degenerate cases [Bug: 3737] + +1999-12-01 Scott Redman + + * generic/tcl.decls : + * generic/tclMain.c : + * unix/tclAppInit.c: + * win/tclAppInit.c: Added two new internal functions, + TclSetStartupScriptFileName() and TclGetStartupScriptFileName() + and added hooks into the main() code for supporting TclPro and + other "big" shells more easily without requiring a copy of the + main() code. + + * generic/tclEncoding.c: + * generic/tclEvent.c: Moved encoding-related startup code from + tclEvent.c into the more appropriate tclEncoding.c. + +1999-11-30 Jeff Hobbs + + * generic/tclIO.c: fix from Kupries for Tcl_UnstackChannel that + correctly handles resetting translation and encoding. + + * generic/tclLoad.c: #def'd out the unloading of DLLs at finalize + time for Unix in TclFinalizeLoad. [Bug: 2560 3373] Should be + parametrized to allow for user to specify unload or not. + + * win/tclWinTime.c: fixed handling of %Z on NT for time zones + that don't have DST. + +1999-11-29 Jeff Hobbs + + * library/dde1.1/pkgIndex.tcl: + * library/reg1.0/pkgIndex.tcl: added supported for debugged + versions of the libraries + + * unix/tclUnixPipe.c: fixed PipeBlockModeProc to properly set + isNonBlocking flag on pipe. [Bug: 1356 710] + removed spurious fcntl call from PipeBlockModeProc + + * tests/scan.test: + * generic/tclScan.c: fixed scan where %[..] didn't match anything + and added test case [Bug: 3700] + +1999-11-24 Jeff Hobbs + + * doc/open.n: + * win/tclWinSerial.c: adopted patch from Schroedter to handle + fconfigure $sock -lasterror on Windows. [RFE: 3368] + + * generic/tclCmdIL.c: made SORTMODE_INTEGER work with Longs + [Bug: 3652] + +1999-11-23 Scott Stanton + + * library/tcltest1.0/tcltest.tcl: Fixed bug where tcltest output + went to stdout instead of the specified output file in some + cases. + +1999-11-19 Jeff Hobbs + + * generic/tclProc.c: backed out change from 1999-11-18 as it + could affect return string from upvar as well. + + * tools/tcl.wse.in: added tcltest1.0 library to distribution list + + * doc/http.n: + * library/http2.1/http.tcl: + * library/http2.1/pkgIndex.tcl: updated http package to 2.2 + +1999-11-18 Jeff Hobbs + + * unix/tcl.m4: added defined for _THREAD_SAFE in --enable-threads + case; added check for pthread_mutex_init in libc; in AIX case, + with --enable-threads ${CC}_r is used; fixed flags when using gcc + on SCO + + * generic/tclProc.c: corrected error reporting for default case + at the global level for uplevel command. + + * generic/tclIOSock.c: changed int to size_t type for len + in TclSockMinimumBuffers. + + * generic/tclCkalloc.c: fixed Tcl_DbCkfree to return a value + on NULL input. [Bug: 3400] + + * generic/tclStringObj.c: fixed support for passing in negative + length to Tcl_SetUnicodeObj, et al handling routines. [Bug: 3380] + + * doc/scan.n: + * tests/scan.test: + * generic/tclScan.c: finished support for inline scan by + supporting XPG identifiers. + + * doc/http.n: + * library/http2.1/http.tcl: added register and unregister + commands to http:: package (better support for tls/SSL), + as well as -type argument to http::geturl. [RFE: 2617] + + * generic/tclBasic.c: removed extra decr of numLevels in + Tcl_EvalObjEx that could cause seg fault. (mjansen@wendt.de) + + * generic/tclEvent.c: fixed possible lack of MutexUnlock in + Tcl_DeleteExitHandler [Bug: 3545] + + * unix/tcl.m4: Added better pthreads library check and inclusion + of _THREAD_SAFE in --enable-threads case + Added support for gcc config on SCO + + * doc/glob.n: added note about ..../ glob behavior on Win9* + * doc/tcltest.n: fixed minor example errors [Bug: 3551] + +1999-11-17 Brent Welch + * library/http2.1/http.tcl: Correctly fixed the -timeout + problem mentioned in the 10-29 change. Also added error + handling for failed writes on the socket during the protocol. + +1999-11-09 Jeff Hobbs + + * doc/open.n: corrected docs for 'a' open mode. + + * generic/tclIOUtil.c: changed Tcl_Alloc to ckalloc + + * generic/tclInt.h: + * generic/tclObj.c: rolled back changes from 1999-10-29 + Purify noted new leaks with that code + + * generic/tclParse.c: added code in Tcl_ParseBraces to test for + possible unbalanced open brace in a comment + + * library/init.tcl: removed the installed binary directory from + the auto_path variable + + * tools/tcl.wse.in: updated to 8.3a1, fixed install of twind.tcl + and koi8-r.enc files + + * unix/tcl.m4: added recognition of pthreads library for AIX + +1999-10-29 Brent Welch + * generic/tclInt.h: Modified the TclNewObj and TclDecrRefCount + in two ways. First, in the case of TCL_THREADS, we do not use + the special Tcl_Obj allocator because that is a source of + lock contention. Second, general code cleanup to eliminate + duplicated code. In particular, TclDecrRefCount now uses + TclFreeObj instead of duplicating that code, so it is now + identical to Tcl_DecrRefCount. + + * generic/tclObj.c: Changed Tcl_NewObj so it uses the + TclNewObj macro instead of duplicating the code. Adjusted + TclFreeObj so it understands the TCL_THREADS case described + above. + + * library/http2.1/http.tcl: Fixed a bug in the handling of + the state(status) variable when the -timeout flag is specified. + Previously it was possible to leave the status undefined + instead of empty, which caused errors in http::status + +1999-10-28 Jeff Hobbs + + * unix/aclocal.m4: made it just include tcl.m4 + + * library/tcltest1.0/tcltest.tcl: updated makeFile to return + full pathname of file created + + * generic/tclStringObj.c: fixed Tcl_AppendStringsToObjVA so it only + iterates once over the va_list (avoiding a memcpy of it, + which is not portable). + + * generic/tclEnv.c: fixed possible ABR error in environ array + + * tests/scan.test: + * generic/tclScan.c: added support for use of inline scan, + XPG3 currently not included + + * tests/incr.test: + * tests/set.test: + * generic/tclCompCmds.c: fixed improper bytecode handling of + 'eval {set array($unknownvar) 5}' (also for incr) [Bug: 3184] + + * win/tclWinTest.c: added testvolumetype command, as atime is + completely ignored for Windows FAT file systems + * win/tclWinPort.h: added sys/utime.h to includes + * unix/tclUnixPort.h: added utime.h to includes + * doc/file.n: + * tests/cmdAH.test: + * generic/tclCmdAH.c: added time arguments to atime and mtime + file command methods (support 'touch' functionality) + +1999-10-20 Jeff Hobbs + + * unix/tclUnixNotfy.c: fixed event/io threading problems by + making triggerPipe non-blocking [Bug: 2792] + + * library/tcltest1.0/tcltest.tcl: + * generic/tclThreadTest.c: fixed mem leaks in threads + + * generic/tclResult.c: fixed Tcl_AppendResultVA so it only + iterates once over the va_list (avoiding a memcpy of it, + which is not portable). + + * generic/regc_color.c: fixed mem leak and assertion, from HS + + * generic/tclCompile.c: removed savedChar trick that appeared to + be causing a segv when the literal table was released + + * tests/string.test: + * generic/tclCmdMZ.c: fixed [string index] to return ByteArrayObj + when indexing into one (test case string-5.16) [Bug: 2871] + + * library/http2.1/http.tcl: protected gets with catch [Bug: 2665] + +1999-10-19 Jennifer Hom + + * tests/tcltest.test: + * doc/tcltest.n: + * library/tcltest1.0/tcltest.tcl: Removed the extra return at the + end of the tcltest.tcl file, added version information about tcl. + + Applied patches sent in by Andreas Kupries to add helper procs for + debug output, add 3 new flags (-testsdir, -load, -loadfile), and + internally refactors common code for dealing with paths into + separate procedures. [Bug: 2838, 2842] + + Merged code from core-8-2-1 branch that changes the checks for the + value of tcl_interactive to also incorporate a check for the + existence of the variable. + + * tests/autoMkindex.test: + * tests/pkgMkIndex.test: Explicitly cd to + ::tcltest::testsDirectory at the beginning of the test run + + * tests/basic.test: Use version information defined in tcltest + instead of hardcoded version number + + * tests/socket.test: package require tcltest before attempting to + use variable defined in tcltest namespace + + * tests/unixInit.test: + * tests/unixNotfy.test: Added explicit exits needed to avoid + problems when the tests area run in wish. + +1999-10-12 Jim Ingham + + * mac/tclMacLoad.c: Stupid bug - we converted the filename to + external, but used the unconverted version. + * mac/tclMacFCmd.c: Fix a merge error in the bug fix for [Bug: 2869] + +1999-10-12 Jeff Hobbs + + * generic/regc_color.c: + * generic/regc_cvec.c: + * generic/regc_lex.c: + * generic/regc_locale.c: + * generic/regcomp.c: + * generic/regcustom.h: + * generic/regerrs.h: + * generic/regex.h: + * generic/regexec.c: + * generic/regguts.h: + * generic/tclRegexp.c: + * generic/tclTest.c: + * tests/reg.test: updated to Henry Spencer's new regexp engine + (mid-Sept 99). Should greatly reduce stack space reqs. + + * library/tcltest1.0/pkgIndex.tcl: fixed procs in pkgIndex.tcl file + + * generic/tclEnv.c: fixed mem leak with putenv and DStrings + * doc/Encoding.3: corrected docs + * tests/basic.test: updated test cases for 8.3 + * tests/encoding.test: fixed test case that change system + encoding to a double-byte one (this causes a bogus mem read + error for purify) + * unix/Makefile.in: purify has to use -best-effort to instrument + * unix/tclAppInit.c: identified potential mem leak when compiling + tcltest (not critical) + * unix/tclUnixPipe.c: fixed mem leak in TclpCreateProcess when + doing alloc between vfork and execvp. + * unix/tclUnixTest.c: fixed mem leak in findexecutable test command + +1999-10-05 Jeff Hobbs + + * {win,mac,unix,tools,}/README: + * win/README.binary: + * win/makefile.vc: + * {win,unix}/configure.in: + * generic/tcl.h: + * library/init.tcl: updated to 8.3a1 from 8.2.0. + + * library/http2.1/http.tcl: fixed possible use of global c var. + + * win/tclWinReg.c: fixed registry command to properly 'get' + HKEY_PERFORMANCE_DATA root key data. Needs more work. + + * generic/tclNamesp.c: + * generic/tclVar.c: + * generic/tclCmdIL.c: fixed comment typos + + * mac/tclMacFCmd.c: fixed filename stuff to support UTF-8 [Bug: 2869] + + * win/tclWinSerial.c: changed SerialSetOptionProc to return + TCL_OK by default. (patch from Rolf Schroedter) + +1999-09-21 Jennifer Hom + + * library/tcltest1.0/tcltest.tcl: Applied patches sent in by + Andreas Kupries to fix typos in comments and ::tcltest::grep, + fix hook redefinition problems, and change "string compare" to + "string equal." [Bug: 2836, 2837, 2839, 2840] + +1999-09-20 Jeff Hobbs + + * tests/env.test: + * unix/Makefile.in: added support for AIX LIBPATH env var [Bug: 2793] + removed second definition of INCLUDE_INSTALL_DIR (the one that + referenced @includedir@) [Bug: 2805] + * unix/dltest/Makefile.in: added -lc to LIBS [Bug: 2794] + +1999-09-16 Jeff Hobbs + + * tests/timer.test: changed after delay in timer test 6.29 from + 1 to 10. [Bug: 2796] + + * tests/pkg.test: + * generic/tclPkg.c: fixed package version check to disallow 1.2..3 + [Bug: 2539] + + * unix/Makefile.in: fixed gendate target - this never worked + since RCS was intro'd. + * generic/tclGetDate.y: updated to reflect previous changes + to tclDate.c (leap year calc) and added CEST and UCT time zone + recognition. Fixed 4 missing UCHAR() casts. [Bug: 2717, 954, + 1245, 1249] + + * generic/tclCkalloc.c: changed Tcl_DumpActiveMemory to really + dump to stderr and close it [Bug: 725] and changed Tcl_Ckrealloc + and Tcl_Ckfree to not bomb when NULL was passed in [Bug: 1719] + and changed Tcl_Alloc, et al to not panic when a alloc request + for zero came through and NULL was returned (valid on AIX, Tru64) + [Bug: 2795, etc] + + * tests/clock.test: + * doc/clock.n: + * generic/tclClock.c: added -milliseconds switch to clock clicks + to guarantee that the return value of clicks is in the millisecs + granularity [Bug: 2682, 1332] + +1999-09-15 Jeff Hobbs + + * generic/tclIOCmd.c: fixed potential core dump in conjunction + with stacked channels with result obj manipulation in + Tcl_ReadChars [Bug: 2623] + + * tests/format.test: + * generic/tclCmdAH.c: fixed translation of %0#s in format [Bug: 2605] + + * doc/msgcat.n: fixed \\ bug in example [Bug: 2548] + + * unix/tcl.m4: + * unix/aclocal.m4: added fix for FreeBSD-[1-2] recognition + [Bug: 2070] and fix for IRIX SHLIB_LB_LIBS. [Bug: 2610] + + * doc/array.n: + * tests/var.test: + * tests/set.test: + * generic/tclVar.c: added an array unset operation, with docs + and tests. Variation of [Bug: 1775]. Added fix in TclArraySet + to check when trying to set in a non-existent namespace. [Bug: 2613] + +1999-09-14 Jeff Hobbs + + * tests/linsert.test: + * doc/linsert.n: + * generic/tclCmdIL.c: fixed end-int interpretation of linsert + to correctly calculate value for end, added test and docs [Bug: 2693] + + * doc/regexp.n: + * doc/regsub.n: + * tests/regexp.test: + * generic/tclCmdMZ.c: add -start switch to regexp and regsub + with docs and tests + + * doc/switch.n: added proper use of comments to example. + * generic/tclCmdMZ.c: changed switch to complain when an error + occurs that seems to be due to a misplaced comment. + + * generic/tclCmdMZ.c: fixed illegal ref for \[0-9] substitutions + in regsub [Bug: 2723] + + * generic/tclCmdMZ.c: changed [string equal] to return an Int + type object (was a Boolean) + +1999-09-01 Jennifer Hom + + * library/tcltest1.0/tcltest.tcl: Process command-line arguments + only ::tcltest doesn't have a child namespace (requires that + command-line args are processed in that namespace) + +1999-09-01 Jeff Hobbs + + * generic/tclParseExpr.c: changed '"' to '\"' to make FreeBSD + happy [Bug: 2625] + * generic/tclProc.c: moved static buf to better location and + changed static msg that would overflow in ProcessProcResultCode + [Bug: 2483] and added Tcl_DStringFree to Tcl_ProcObjCmd. + Also reworked size of static buffers. + * tests/stringObj.test: added test 9.11 + * generic/tclStringObj.c: changed Tcl_AppendObjToObj to + properly handle the 1-byte dest and mixed src case where + both had had Unicode string len checks made on them. [Bug: 2678] + * unix/aclocal.m4: + * unix/tcl.m4: adjusted fix from 8-21 to add -bnoentry to the + AIX-* case and readjusted the range + +1999-08-31 Jennifer Hom + + * library/tcltest1.0/tcltest.tcl: + * doc/tcltest.n: + * tests/README: Modified testConstraints variable so that it isn't + unset every time ::tcltest::initConstraints is called and cleaned up + documentation in the README file and the man page. + +1999-08-27 Jennifer Hom + + * tests/env.test: + * tests/exec.test: + * tests/io.test: + * tests/event.test: + * tests/tcltest.test: Added 'exit' calls to scripts that the tests + themselves write, and removed accidental checkin of knownBugThreaded + constraints for Solaris and Linux. + + * library/tcltest1.0/tcltest.tcl: Modified tcltest so that + variables are only initialized to their default values if they did + not previously exist. + +1999-08-26 Jennifer Hom + + * tests/tcltest.test: + * library/tcltest1.0/tcltest.tcl: Added a -args flag that sets a + variable named ::tcltest::parameters based on whatever's being + sent in as the argument to the -args flag. + +1999-08-23 Jennifer Hom + + * tests/tcltest.test: Added additional tests for -tmpdir, marked + all tests that use exec as unixOrPc. + + * tests/encoding.test: + * tests/interp.test: + * tests/macFCmd.test: + * tests/parseOld.test: + * tests/regexp.test: Applied patches from Jim Ingham to add + encoding to a Mac only interp test, change an error message in + macFCmd.tet, put a comment in parseOld.test, fix tests using the + testencoding path command, and put unixOrPc constraints on tests + that use exec. + +1999-08-21 Jeff Hobbs + + * unix/aclocal.m4: Changed AIX-4.[2-9] check to AIX-4.[1-9] + [Bug: 1909] + +1999-08-20 Jeff Hobbs + + * generic/tclPosixStr.c: fixed typo [Bug: 2592] + + * doc/*: fixed various nroff bugs in man pages [Bug: 2503 2588] + +1999-08-19 Jeff Hobbs + + * win/README.binary: fixed version info and some typos [Bug: 2561] + + * doc/interp.n: updated list of commands available in a safe + interpreter [Bug: 2526] + + * generic/tclIO.c: changed Tcl_GetChannelNames* to use style guide + headers (pleases HP cc) + +1999-08-18 Jeff Hobbs + + * doc/Eval.3: fixed doc on input args [Bug: 2114] + + * doc/OpenFileChnl.3: + * doc/file.n: + * tests/cmdAH.test: + * tclIO.c: + * tclCmdAH.c: added "file channels ?pattern?" tcl command, with + associated Tcl_GetChannelNames and Tcl_GetChannelNamesEx public + C APIs (added to tcl.decls as well), with docs and tests. + + * tests/expr.test: + * generic/tclCompile.c: add TCL_TOKEN_VARIABLE to the part types + that cause differed compilation for exprs, to correct the expr + double-evaluation problem for vars. Added test cases. + Related to [Bug: 732] + + * unix/Makefile.in: changed the dependency structure so that + install-* is dependent on * (ie - install-binaries is dependent + on binaries). + + * library/auto.tcl: + * library/init.tcl: + * library/ldAout.tcl: + * library/package.tcl: + * library/safe.tcl: + * library/word.tcl: + * library/http2.1/http.tcl: + * library/msgcat1.0/msgcat.tcl: updated libraries to better + Tcl style guide (no more string comparisons with == or !=, spacing + changes). + +1999-08-05 Jim Ingham + + * mac/tclMacProjects.sea.hqx: Rearrange the projects so that the build + directory is separate from the sources. Much more convenient! + +1999-08-13 Scott Redman + + * /: 8.2.0 tagged for final release + +1999-08-12 Scott Stanton + + * win/Makefile.in: Added COMPILE_DEBUG_FLAGS macro to make it + easier to turn on compiler tracing. + + * tests/parse.test: + * generic/tclParse.c: Fixed bug in Tcl_EvalEx where the termOffset + was not being updated in cases where the evaluation returned a non + TCL_OK error code. [Bug: 2535] + +1999-08-12 Scott Redman + + * win/tclWinSerial.c: Applied patch from Petteri Kettunen to + remove compiler warning. + +1999-08-10 Scott Redman + + * generic/tclAlloc.c: + * generic/tclCmdIL.c: + * generic/tclIO.c: + * generic/tclThread.c: + * win/tclWinThrd.c: + * unix/tclUnixThrd.c: Fixed Brent's changes so that they work on + Windows (and he fixed the bug in the Unix thread implementation). + +1999-08-09 Brent Welch + + * generic/tcl.decls: + * generic/tclAlloc.c: + * generic/tclCkalloc.c: + * generic/tclCmdIL.c: + * generic/tclDecls.h: + * generic/tclIO.c: + * generic/tclInt.decls: + * generic/tclIntDecls.h: + * generic/tclStubInit.c: + * generic/tclVar.c: + * mac/tclMacThrd.c: + * unix/tclUnixThrd.c: + * win/tclWinThrd.c: Added use of Tcl_GetAllocMutex to tclAlloc.c + and tclCkalloc.c so they can be linked against alternate thread + packages. Added Tcl_GetChannelNames to tclIO.c. Added + TclVarTraceExists hook so "info exists" triggers read traces + exactly like it did in Tcl 7.6. Stubs table changes to reflect new + internal and external APIs. + +1999-08-09 Jeff Hobbs + + * tests/string.test: added largest_int proc to adapt for >32 bit + machines and int overflow testing. + * tests/tcltest.test: fixed minor error in 8.2 result (from dgp) + + * doc/Object.3: clarified Tcl_DecrRefCount docs [Bug: 1952] + * doc/array.n: clarified array pattern docs [Bug: 1330] + * doc/clock.n: fixed clock docs [Bug: 693] + * doc/lindex.n: clarified to account for new end-int behavior. + * doc/string.n: fixed formatting errors [Bug: 2188 2189] + * doc/tclvars.n: fixed doc error [Bug: 2042] + * library/init.tcl: fixed path handling in auto_execok (it could + miss including the normal path on some Windows machines) [Bug: 1276] + +1999-08-05 Jeff Hobbs + + * doc/tclvars.n: Made it clear that tcl_pkgPath was not set + for Windows (already mentioned in init.tcl) [Bug: 2455] + * generic/tclLiteral.c: fixed reference to bytes that might + not be null terminated (using objPtr->bytes, which is) [Bug: 2496] + * library/http2.1/http.tcl: Made use of "i" in init section use + local var and start at 0 (was 1). [Bug: 2502] + +1999-08-04 Scott Stanton + + * tests/reg.test: Added test for REG_EXPECT bug fixed by Henry's + patch. + + * generic/regc_nfa.c: + * generic/regcomp.c: + * generic/rege_dfa.c: + * generic/regexec.c: + * generic/regguts.h: Applied patches supplied by Henry Spencer to + greatly enhance the performance of certain classes of regular + expressions. [Bug: 2440, 2447] + +1999-08-03 Scott Redman + + * win/tclWinInt.h: Remove function declarations in header that was + moved to tclInt.decls file in previous changes. + +1999-08-02 Scott Redman + + * unix/configure.in: + * win/configure.in: Change beta level to b2. + + * generic/tcl.h: + * generic/tcl.decls: + * generic/tclDecls.h: + * generic/tclInt.h: + * generic/tclInt.decls: + * generic/tclIntDecls.h: + * generic/tclRegexp.h: + * generic/tclStubInit.c: Move some exported public and internal + functions to the stub tables. Removed functions that are in the + stub tables (from this and previous changes) from the original + header files. + +1999-08-01 Scott Redman + + * win/tclWinSock.c: Added comment block to SocketThread() + function. Added code to avoid calling TerminateThread(), but + instead to send a message to the socket event window to tell it to + terminate its thread. + +1999-07-30 Jennifer Hom + + * tests/tcltest.test: + * library/tcltest1.0/tcltest.tcl: Exit with non-zero status if + there were problems with the way the test suite was started + (e.g. wrong # arguments). + +1999-07-30 Jeff Hobbs + + * generic/tclInt.decls: added declaractions necessary for the + Tcl test code to work wth stubs [Bug: 2445] + +1999-07-30 + + * win/tclWinPipe.c: + * win/Makefile.in: Fixing launching of 16-bit apps on Win9x from + wish. The command line was primed with tclpip82.dll, but it was + ignored. Fixed that, then fixed the gmake makefile to build + tclpip82.dll as an executable. + + * win/tclWinSock.c: Applied small patch to get thread-specific + data after initializing the socket driver. + + * unix/tclUnixThrd.c: Applied patch to fix threads on Irix 6.5. + Patch from James Dennett. [Bug: 2450] + + * tests/info.test: Enable test for tclParse.c change (info + complete). + +1999-07-30 + + * tclIO.c: added fix for Kupries' trf patch [Bug: 2386] - * win/tclWin32Dll.c (DllMain): Use standard _imp__reent_data, - not old-style __imp_reent_data - * generic/tclEnv.c (environ): ditto for _imp____cygwin_environ + * tclParse.c: fixed bug in info complete regarding nested square + brackets [Bug: 2382, 2466] + +1999-07-29 + + * win/tclWinChan.c: Allow tcl to open CON and NUL, even for std + channels. Checking for bad/unusable std channels was moved to Tk + since its only purpose was to check whether to use the Tk Console + Window for the std channels. [Bug: 2393 2392 2209 2458] -2000-01-17 Drew Moseley + * unix/mkLinks.tcl: Applied patch to avoid linking pack.n to + pack-old.n. Patch from Don Porter. [Bug: 2469] - * cygwin/configure.in: Fixed bug in setting of shell variable which - caused it to be interpreted as a subcommand rather than a variable. - * cygwin/configure: Regenerated. + * doc/Encoding.n: Applied patch to fix typo in .SH NAME line. + Patch from Don Porter. [Bug: 2451] + + * win/tclWinSock.c: Free Win32 Event handles when destroying + the socket helper thread. -1999-11-09 DJ Delorie +1999-07-28 - * cygwin/*: redone with automake for cygwin-specific info (from cgf) - to support cross-host builds + * tests/tcltest.test: + * library/tcltest1.0/tcltest.tcl: Fixed the condition under which + ::tcltest::PrintError had an infinite loop problem and added a + test case for it. Added an optional argument to + ::tcltest::getMatchingFiles telling it where to search for test + files. -1999-10-26 DJ Delorie +1999-07-27 - * cygwin/*: new; replicate unix/* setup (other modules look - in unix/* for "local" builds; we don't want them to find the - cygwin version) - * unix/Makefile.in: undo - * configure.in: For cygwin, build win and cygwin - * Makefile.in: re-enable multi-dir support + * tools/tclSplash.bmp: Updated Windows installer bitmap + to ready Tcl/Tk Version 8.2. -Tue Oct 26 13:16:09 1999 Christopher Faylor +1999-07-26 - * win/configure.in: Add better detection of cross-compilation - environment. - * win/configure: Regenerate. + * tests/tcltest.test: Need to close the new core file, there + seems to be a hang in threaded WinNT if the file isn't closed. + Open issue, need to fix that hang. + + * tests/httpold.test: Add time delay in response from Http server + so that test cases can properly detect timeout conditions with + threads enabled on multi-CPU WinNT. + + * tests/winFCmd.test: Test case winFcmd-1.33 was looking for + c:\windows, which may not exist. Instead, create a new directory + on c:\ and use it for the test. + + * win/tclWinConsole.c: + * win/tclWinPipe.c: + * win/tclWinSock.c: Fix terminating helper threads by holding any + mutexes from the primary thread while waiting for the helper + thread to terminate. Without these changes, the test suite hangs + on WinNT with 2 CPUs and threads enabled. Open issue, seems to be + a sporadic hang on dual CPU systems still (very rare). + +1999-07-26 Jennifer Hom + + * tests/tcltest.test: + * library/tcltest1.0/tcltest.tcl: + * doc/tcltest.n: Cleaned up code in ::tcltest::PrintError, revised + documentation, and added tests for the tcltest package. + +1999-07-23 + + * tests/info.test: + * generic/tclParse.c: Removed patch for info command, breaks test + cases on Unix. Patch was bad and needs to be redone + properly. [Bug: 2382] + +1999-07-22 + + * Changed version to 8.2b2. + + * win/tclWinSock.c: Fixed hang with threads enabled, fixed + semaphores with threads disabled. + + * win/safe.test: Fixed safe-6.3 with threads enabled. + + * win/Makefile.in: Fixed calling of tcltest to fix safe.test + failures due to path TCL_LIBRARY path. + + * win/tclWinPort.h: Block out include of sys/*.h in order to + build extensions with MetroWerks compiler for Win32. [Bug: 2385] + + * generic/tclCmdMZ.c: + * generic/tclIO.c: Fix ANSI-style prototypes based on patch from + Ulrich Ring. [Bug: 2391] + + * unix/Makefile.in: Need to make install-sh executable before + calling (with chmod +x). [Bug: 2413] + + * tests/var.test: + * generic/tclVar.c: Fixed bug that caused a seg. fault when using + "array set a(b) {}", which is a bad array name anyway. Now the + "array set" command will return an error in this case. Added test + case and fixed existing test. [Bug: 2427] + +1999-07-21 + + * tests/info.test: + * generic/tclParse.c: Applied patch to fix "info complete" + for the string {[a [b]}. Patch from Peter Spjuth. [Bug: 2382] + + * doc/Utf.3: + * generic/tcl.decls: + * generic/tclDecls.h: + * generic/tclUtf.c: Changed function declarations in + non-platform-specific public APIs to use "unsigned long" instead of + "size_t", which may not be defined on certain compilers (rather + than include sys/types.h, which may not exist). + + * unix/Makefile.in: Added the Windows configure script to the + distribution file list, already shipping configure.in and the .m4 + files, but needed the configure script itself. + + * win/makefile.vc: Changed version number of DDE package in VC++ + makefile to use 1.1 instead of 1.0. + + * doc/open.n: Added documentation of \\.\comX notation for opening + serial ports on Windows (alternative to comX:). + + * tests/ioCmd.test: + * doc/open.n: + * win/tclWinSerial.c: Applied patch from Rolf Schroedter to add + -pollinterval option to fconfigure to modify the maxblocktime used + in the fileevent polling. Added documentation and fixed the test + case as well. + + * win/tclWinSock.c: Modified 8.1.0 version of the Win32 socket + driver to move the handling of the socket event window in a + separate thread. It also turned out that Win95 & Win98 were, in + some cases, getting multiple FD_ACCEPTs but only handling one. + Added a count for the FD_ACCEPT to take care of this. Tested on + NT4 SP3, NT4 SP4, Win95, and Win98. + [Bug: 2178 2256 2259 2329 2323 2355] + +1999-07-21 + + * README: Small tweaks to clean up typos and wording. + +1999-07-20 Melissa Hirschl + + * generic/tclInitScript.h: + * unix/tclUnixInit.c: merged code with 8.0.5. We now use an + intermediate global tcl var "tclDefaultLibrary" to keep the + "tcl_library" var from being set by the default value in the + Makefile. Also fixed a bug in which caused the value of + TCL_LIBRARY env var to be ignored. + * unix/tclWinInit.c: just updated some comments. + +1999-07-19 Melissa Hirschl + + * library/http2.1/http.tcl: updated -useragent text to say version + 2.1. + +1999-07-16 + + * generic/tcl.decls: + * generic/tclDecls.h: + * generic/tclStubInit.c: Add Tcl_SetNotifier to stub table. + [Bug: 2364] + + * unix/aclocal.m4: + * unix/tcl.m4: Add check for Alpha/Linux to correct the IEEE + floating flag to the compiler, should be -mieee. Patch from Don + Porter. + + * tools/tcl.hpj.in: Change version number of .cnt file referenced + in .HPJ file. + +1999-07-15 + + * tools/tcl.wse.in: Fixed naming of target files for Windows. + +1999-07-14 + + * doc/re_syntax.n: Deleted sentence as suggested by Scott S. + +1999-07-12 + + * doc/re_syntax.n: Removed two notes to myself (oops), cleaned + up wording, fixed changebars, made two examples easier to read. + +1999-07-11 + + * win/makefile.vc: Since the makefile.vc should continue to work + while we're working out bugs/issues in the new TEA-style + autoconf/configure/gmake build mechanism for Windows, the version + numbers of the Tcl libraries need to remain in sync. Modified the + version numbers in the makefile to reflect the change to 8.2b1. + +1999-07-09 + + * win/configure.in: Eval DLLSUFFIX, LIBSUFFIX, and EXESUFFIX in + the configure script so that substitutions get expanded before + being placed in the Makefile. The "d" portion for debug libraries + and DLLs was not being set properly. + +1999-07-08 + + * tests/string.test: + * generic/tclCmdMZ.c: Fixed bug in string range bounds checking + code. + +1999-07-08 Jennifer Hom + + * doc/tcltest.n: + * library/tcltest1.0/tcltest.tcl: Removed -asidefromdir and + -relateddir flags, removed unused ::tcltest::dotests proc, cleaned + up implementation of core file checking, and fixed the code that + checks for 1-letter flag abbreviations. + +1999-07-08 + + * win/Makefile.in: Added tcltest target so runtest works + properly. Added missing names to the clean/distclean targets. + + * tests/reg.test: + * generic/rege_dfa.c: Applied fix supplied by Henry Spencer for + bug in DFA state caching under lookahead conditions. [Bug: 2318] + +1999-07-07 + + * doc/fconfigure.n: Clarified default buffering behavior for the + standard channels. [Bug: 2335] + +1999-07-06 + + * win/tclWinSerial.c: New implementation of serial port driver + from Rolf Shroedter (Rolf.Schroedter@dlr.de) that allows more than + one byte to be read from the port. Implemented using polling + instead of threads, there is a max. 10ms latency between checking the + port for file events. [Bug: 1980 2217] + +1999-07-06 + + * library/http2.0/http.tcl: Fixed the -timeout option so it + handles timeouts that occur during connection attempts to + hosts that are down (the only case that really matters!) + +1999-07-03 + + * doc/ChnlStack.3: + * generic/tcl.decls: + * generic/tclIO.c: Added a new variant of the "Trf patch" + from Andreas Kupres that adds new C APIs Tcl_StackChannel, + Tcl_UnstackChannel, and Tcl_GetStackedChannel. + +1999-07-03 + + * generic/tclNotify.c: + * unix/tclUnixNotfy.c: + * unix/tclXtTest.c: + * unix/tclXtNotify.c: + * win/tclWinNotify.c: + * mac/tclMacNotify.c: Added Tcl_SetNotifier and the associated + hook points in the notifiers to be able to replace the notifier + calls at runtime The Xt notifier and test program use this hook. + +1999-07-03 + + * generic/tclParse.c: Changed parsing of variable names to + allow empty array names. Now "$(foo)" is a variable reference! + Previous you had to use something like $::(foo), which is slower. + This change is requested by Jean-Luc Fontaine for his STOOOP + package. + +1999-07-01 + + * generic/tclCmdAH.c: + * generic/tclFCmd.c: Call TclStat instead of TclpStat in order to + allow Tcl_Stat hooks to work properly. + +1999-06-29 Jennifer Hom + + * library/tcltest1.0/pkgIndex.tcl: + * library/tcltest1.0/tcltest.tcl: + * doc/tcltest.n: + * tests/all.tcl: Added -preservecore, -limitconstraints, -help, + -file, -notfile, -relateddir and -asidefromdir flags to the + tcltest package along with exported proc + ::tcltest::getMatchingFiles. The documentation was modified to + match and all.tcl was modified to use the new functionality + instead of implementing -file itself. + +1999-06-28 + + * generic/tclIndexObj.c: + * doc/GetIndex.3: + * tests/binary.test: + * tests/winDde.test: Applied patch from Peter Hardie (with + changes) to fix problem with Tcl_GetIndexFromObj() when the key + being passed is the empty string. It used to match "" and return + TCL_OK, but it should have returned TCL_ERROR instead. Added test + case to "binary" and "dde" commands to check the behavior. Added + documentation note as well. + +1999-06-26 + + * win/tclWinDde.c: Applied patch from Peter Hardie to add poke + command to dde. Also rev'd version of dde package to 1.1. + [Bug: 1738] + +1999-06-25 Jennifer Hom + + * unix/Makefile.in: + * win/Makefile.in: + * library/tcltest1.0/pkgIndex.tcl: + * library/tcltest1.0/tcltest.tcl: + * library/tcltest1.0: Added initial implementation of the Tcl test + harness package. This package was based on the defs.tcl file that + was part of the tests directory. Reversed the way that tests were + evaluated to fix a problem with false passes. + + * doc/tcltest.n: Added documentation for the tcltest package. + + * tests/README: + * tests/defs.tcl: + * tests/all.tcl: Modified all test files (tests/*.test) and + all.tcl to use the new tcltest package and removed references to + the defs.tcl file. Modified the README file to point to the man + page for tcltest. + +1999-06-25 + + * tests/reg.test: + * generic/regexec.c: Fixed bugs in non-greedy quantifiers. + +1999-06-23 + + * doc/re_syntax.n: + * doc/switch.n: + * doc/lsearch.n: + * doc/RegExp.3: + * doc/regexp.n: + * doc/regsub.n: Moved information about syntax of 8.1 regular + expressions from regexp(n) manpage into new re_syntax(n) page. + Added pointers from other manpages to new re_syntax(n) page. + +1999-06-23 + + * unix/Makefile.in: Changed install-doc to install-man. + + * tools/uniParse.tcl: + * tools/uniClass.tcl: + * tools/README: + * tests/string.test: + * generic/regc_locale.c: + * generic/tclUniData.c: + * generic/tclUtf.c: + * doc/string.n: Updated Unicode character tables to reflect latest + Unicode 2.1 data. Also rationalized "regexp" and "string is" + definitions of character classes. + +1999-06-21 + + * unix/tclUnixThrd.c (TclpThreadCreate): Fixed memory leak where + thread attributes were not being released. [Bug: 2254] + +1999-06-17 + + * tests/regexp.test: + * generic/tclCmdMZ.c: + * generic/tclCmdIL.c: Changed to use new regexp interfaces. Added + -expanded, -line, -linestop, and -lineanchor switches to regsub. + + * doc/RegExp.3: Documented the new regexp interfaces and + the compile/execute flags. + + * generic/tclTest.c: + * generic/tclRegexp.h: + * generic/tclRegexp.c: + * generic/tcl.h: + * generic/tcl.decls: Renamed Tcl_RegExpMatchObj to + Tcl_RegExpExecObj and added a new Tcl_RegExpMatchObj that is + equivalent to Tcl_RegExpMatch. Added public macros for the regexp + compile/execute flags. Changed to store either an object pointer + or a string pointer in the TclRegexp structure. Changed to avoid + adding a reference to the object or copying the string. + + * generic/regcomp.c: lint + + * tests/reg.test: + * generic/regex.h: + * generic/regc_lex.c: Added REG_BOSONLY flag to allow Expect to + iterate through a string an only find matches that start at the + current position within the string. + +1999-06-16 + + * unix/configure.in: + * unix/Makefile.in: + * unix/tcl.m4: + * unix/aclocal.m4: Numerous build changes to make Tcl conform to the + proposed TEA spec + +1999-06-16 Melissa Hirschl + + * generic/tclVar.c (Tcl_VariableObjCmd): fixed premature increment + in loop that was causing out-of-bounds reads on array "varName". + +1999-06-16 + + * tests/execute.test: + * generic/tclExecute.c (TclExecuteByteCode): Fixed crash caused by + a bug in INST_LOAD_SCALAR1 where the scalar index was read as + a signed 1 byte value instead of unsigned. [Bug: 2243] + +1999-06-14 Melissa Hirschl + + * doc/StringObj.3 + * test/stringObj.test + * unix/Makefile.in + * win/Makefile.in + * win/makefile.vc + * generic/tclStringObj.c: + Merged String and Unicode object types. Added new functions to + the puplic API: Tcl_NewUnicodeObj, Tcl_SetUnicodeObj, + Tcl_GetUnicode, Tcl_GetUniChar, Tcl_GetCharLength, Tcl_GetRange, + Tcl_AppendUnicodeToObj. + +1999-06-09 + + * generic/tclUnicodeObj.c: Lots of cleanup and simplification. + Fixed several memory bugs. Added TclAppendUnicodeToObj. + + * generic/tclInt.h: Added declarations for various Unicode string + functions. + + * generic/tclRegexp.c: + * generic/tclCmdMZ.c: Changed to use new Unicode string interfaces + for better performance. + + * generic/tclRegexp.h: + * generic/tclRegexp.c: + * generic/tcl.h: + * generic/tcl.decls: Added Tcl_RegExpMatchObj and + Tcl_RegExpGetInfo calls to access lower level regexp API. These + features are needed by Expect. This is a preliminary + implementation pending final review and cleanup. + + * generic/tclCmdMZ.c: + * tests/string.test: Fixed bug where string map failed on null + strings. + + * generic/regexec.c: + * unix/tclUnixNotfy.c: lint + + * tools/genStubs.tcl: Changed to always write output in LF mode. + +1999-06-08 + + * win/tclWinSock.c: Rolled back to the 8.1.0 implementation + because of serious problems with the new driver. Basically no + incoming socket connections would be reported to a server port. + The 8.1.1 code needs to be redesigned and fixed correctly. + +1999-06-07 Melissa Hirschl + + * tests/string.test: + * generic/tclVar.c (Tcl_SetVar2Ex): + * generic/tclStringObj.c (Tcl_AppendObjToObj): + * generic/tclCmdMZ.c (Tcl_StringObjCmd): optimized the string + index, string length, string range, and append command in cases + where the object's internal rep is a bytearray. Objects with + other internal reps are converted to have the new unicode internal + rep. + + * unix/Makefile.in: + * win/Makefile.in: + * win/Makefile.vc: + * tests/unicode.test: + * generic/tclInt.h: + * generic/tclObj.c: + * generic/tclUnicodeObj.c: added a new object type to store the + unicode representation of a string. + + * generic/tclTestObj.c: added the objtype option to the testobj + command. This option returns the name of the type of internal rep + an object has. + +1999-06-04 + + * win/configure.in: + * win/Makefile.in: Windows build now handles static/dynamic + debug/nodebug builds and supports the standard targets using + Cygwin user tools plus GNU make and autoconf. + +1999-06-03 + + * generic/tclCmdMZ.c (Tcl_StringObjCmd): + * tests/string.test: Fixed bug where string equal/compare -nocase + reported wrong result on null strings. [Bug: 2138] + +1999-06-02 + + * generic/tclUtf.c (Tcl_UtfNcasecmp): Fixed incorrect computation + of relative ordering. [Bug: 2135] + +1999-06-01 + + * unix/configure.in: Fixed various small configure.in patches + submitted by Jan Nijtmans. [Bug: 2121] + + * tests/reg.test: + * generic/regc_color.c: + * generic/regc_cvec.c: + * generic/regc_lex.c: + * generic/regc_locale.c: + * generic/regc_nfa.c: + * generic/regcomp.c: + * generic/regcustom.h: + * generic/rege_dfa.c: + * generic/regerror.c: + * generic/regerrs.h: + * generic/regex.h: + * generic/regexec.c: + * generic/regfree.c: + * generic/regfronts.c: + * generic/regguts.h: + * generic/tclCmdMZ.c: + * generic/tclRegexp.c: + * generic/tclRegexp.h: + * generic/tclTest.c: Applied Henry Spencer's latest regexp patches + that fix an infinite loop bug and add support for testing whether + a string could match with additional input. [Bug: 2117] + +1999-05-28 + + * generic/tclObj.c: Changed to eliminate use of isupper/tolower in + favor of the Unicode versions. + + * win/Makefile.in: + * win/configure.in: Added preliminary TEA implementation. + + * win/tclWinDde.c: Fixed bug where dde calls were being passed an + invalid dde handle because Initialize had not been called. + [Bug: 2124] + +1999-05-26 + + * generic/tclThreadTest.c: Fixed race condition in testthread + code that showed up in the WinNT test suite intermittently. + + * win/tclWinSock.c: Fixed a hang in the WinNT socket driver, wake + up the socket thread every 100ms to check for events on the + sockets that did not wake up the thread (race condition). + +1999-05-24 + + * tools/genStubs.tcl: Changed to allow a list of platforms instead + of just one at a time. + + * generic/tcl.decls: + * generic/tclCmdMZ.c: + * generic/tclDecls.h: + * generic/tclInt.decls: + * generic/tclIntDecls.h: + * generic/tclPort.h: + * generic/tclStubInit.c: + * generic/tclStubLib.c: Various header file related changes and other + lint to try to get the Mac builds working. + +1999-05-21 + + * win/tclWinPipe.c: Fix bug when launching command.com on + Win95/98. Need to wait for the procInfo.hProcess of the process that + was created, not the hProcess of the current process. [Bug: 2105] + +1999-05-20 + + * library/init.tcl: Add the directory where the executable is, and + the ../lib directory relative to that, to the auto_path variable. + +1999-05-19 + + Merged in various changes submitted by Jeff Hobbs: + + * generic/tcl.decls: + * generic/tclUtf.c: Added Tcl_UniCharIs* functions for control, + graph, print, and punct classes. + + * generic/tclUtil.c: + * doc/StrMatch.3: Added Tcl_StringCaseMatch() implementation to + support case-insensitive globbing. + + * doc/string.n: + * unix/mkLinks: + * tests/string.test: + * generic/tclCmdMZ.c: Added additional character class tests, + added -nocase switch to "string match", changed string first/last + to use offsets. + +1999-05-19 + + * generic/tcl.h: Add extern "C" block around entire header file for + C++ compilers to fix linkage issues. Submitted by Don Porter and + Paul Duffin. + + * generic/tclRegexp.c: Fix bug when the regexp cache is empty + and an empty pattern is used in regexp ( such as {} or "" ). + +1999-05-18 + + * win/tclWinChan.c: Modified initialization code to avoid + inherenting closed or invalid channels. If the standard input is + anything other than a console, file, serial port, or pipe, then we + fall back to the standard Tk window console. + +1999-05-14 + + * generic/tclCmdAH.c (Tcl_ForObjCmd): Fixed crash caused by + failure to reset the result before evaluating the test + expression. + +1999-05-14 + + * generic/tclBasic.c (Tcl_CreateInterp): Added introspection + variable for threaded interps. If the interp was compiled with + threads enabled, the tcl_platform(threaded) variable will exist. + +1999-05-14 + + * generic/tclDate.c: Applied patch to fix 100-year and 400-year + boundaries in leap year code, from Isaac Hollander. [Bug: 2066] + +1999-05-13 + + * unix/Makefile.in: + * unix/tclAppInit.c: Minor cleanup related to Xt notifier. + + * unix/tclUnixInit.c (TclpSetInitialEncodings): Tcl now looks for + an encoding subfield in the LANG/LC_ALL variables in cases where + the locale is not found in the locale table. Ensure that + setlocale() is called at least once so X11 will initialize + properly. Also, forces the LC_NUMERIC locale to be "C" so numeric + processing in scripts is not affected by the current locale + setting. [Bug: 1989] + + * generic/tclRegexp.c: Increased per-thread regexp cache to 30 + slots. This seems to be about the right number for larger + applications like exmh. [Bug: 1063] + +1999-05-12 + + * doc/tclsh.1: Updated references to rc script names to accurately + reflect the platform differences on Windows. + + * tests/regexp.test: + * generic/tclInt.h: + * generic/tclBasic.c: + * generic/tclRegexp.h: + * generic/tclRegexp.c: Replaced the per-interpreter regexp cache + with a per-thread cache. Changed the Regexp object to take + advantage of this extra cache. Added a reference count to the + TclRegexp type so regexps can be shared by multiple objects. + Removed the per-interp regexp cache from the interpreter. Now + regexps can be used with no need for an interpreter. [Bug: 1063] + + * win/tclWinInit.c (TclpSetVariables): Avoid calling GetUserName + if the value can be determined from the USERNAME environment + variable. GetUserName is very slow. + +1999-05-07 + + * win/winDumpExts.c: + * win/makefile.vc: Removed incorrect patch. [Bug: 1998] + + * generic/tcl.decls: Replaced const with CONST. + + * generic/tclResult.c (Tcl_AppendResultVA): + * generic/tclStringObj.c (Tcl_AppendStringsToObjVA): Fixed to copy + arglist using memcpy instead of assignment so it works properly on + OS/390. [Bug: 1997] + + * generic/tclLoadNone.c: Updated to use current interfaces, added + TclpUnloadFile. [Bug: 2003] + + * win/winDumpExts.c: + * win/makefile.vc: Changed to emit library name in defs + file. [Bug: 1998] + + * unix/configure.in: Added fix for OS/390. [Bug: 1976] + +1999-05-06 + + * tests/string.test: + * generic/tclCmdMZ.c: + * doc/string.n: Fixed bug in string equal/compare code when using + -length option. Cleaned up docs a bit more. + + * tests/http.test: Unset "data" array before running tests to + avoid failures due to previous tests. + + * doc/string.n: + * tests/cmdIL.test: + * tests/cmdMZ.test: + * tests/error.test: + * tests/ioCmd.test: + * tests/lindex.test: + * tests/linsert.test: + * tests/lrange.test: + * tests/lreplace.test: + * tests/string.test: + * tests/cmdIL.test: + * generic/tclUtil.c: + * generic/tclCmdMZ.c: Replaced "string icompare/iequal" with + -nocase and -length switches to "string compare/equal". Added a + -nocase option to "string map". Changed index syntax to allow + integer or end?-integer? instead of a full expression. This is + much simpler with safeTcl scripts since it avoids double + substitution issues. + + * doc/Utf.3: + * generic/tclStubInit.c: + * generic/tclDecls.h: + * generic/tclUtf.c: + * generic/tcl.decls: Added Tcl_UtfNcmp and Tcl_UtfNcasecmp. + +1999-05-05 + + * win/makefile.vc: Added encoding directory to install-libraries + target. + +1999-05-03 + + * doc/string.n: + * tests/cmdMZ.test: + * tests/string.test: + * generic/tclCmdMZ.c (Tcl_StringObjCmd): Changed "string length" + to avoid regenerating the string rep of a ByteArray object. + + * tests/cmdIL.test: + * tests/cmdMZ.test: + * tests/error.test: + * tests/lindex.test: + * tests/linsert.test: + * tests/lrange.test: + * tests/lreplace.test: + * tests/string.test: + * generic/tclCmdMZ.c (Tcl_StringObjCmd): + * generic/tclUtil.c (TclGetIntForIndex): Applied Jeff Hobbs's + string patch which includes the following changes [Bug: 1845]: + + - string compare now takes optional length arg (for strncmp + behavior) + + - added string equal (just a few lines of code blended + in with string compare) + + - added string icompare/iequal for case-insensitive comparisons + + - string index's index can now be ?end[+-]?expression + I made this change in the private TclGetIntForIndex, + which means that the list commands also benefit, as + well as string range, et al. + + - added [string repeat string count] + Repeats given string number of times + + - added string replace, string equiv to lreplace + (quasi opposite of string range): + string replace first last ?string? + Example of use, replacing end of string with ... + should the string be more than 16 chars long: + string replace $string 16 end "..." + This just returns the string len < 16, so it + will only affect the long strings. + + - added optional first and last args to string to* + This allows you to just affect certain regions of + a string with the command (like just capping the + first letter). I found the original totitle to + be too draconian to be useful. + + - added [string map charMap string] + where charMap is a {from to from to} list that equates to + what one might get from [array get]. Each and + can be multiple chars (or none at all). For Tcl/CGI users, + this is a MAJOR speed booster. + + * generic/tclParse.c (Tcl_ParseCommand): Changed to avoid + modifying eval'ed strings that are already null terminated. + [Bug: 1793] + + * tests/binary.test: + * generic/tclBinary.c (DupByteArrayInternalRep): Fixed bug where + type was not being set in duplicated object. [Bug: 1975, 2047] + +1999-04-30 + + * Changed version to 8.1.1. + +1999-04-30 + + * Merged changes from 8.1.0 branch: + + * generic/tclParse.c: Fixed memory leak in CommandComplete. + + * generic/tclPlatDecls.h: + * generic/tclIntPlatDecls.h: + * generic/tclIntDecls.h: + * generic/tclDecls.h: + * tools/genStubs.tcl: Added 'extern "C" {}' block around the stub + table pointer declaration so the stub library can be used from + C++. [Bug: 1934] + + * Lots of documentation and other release engineering fixes. + +1999-04-28 + + * mac/tclMacResource.c: + * generic/tclListObj.c: + * generic/tclObj.c: + * generic/tclStringObj.c: Changed to avoid freeing the string + representation before freeing the internal rep. This helps with + debugging since the string rep will still be valid when the free + proc is invoked. + +1999-04-27 + + * generic/tclLiteral.c (TclHideLiteral): Fixed so hidden literals + get duplicated to avoid accidental sharing in the global object + table. + +1999-04-23 + + * generic/tclStubInit.c: + * tools/genStubs.tcl: Changed to avoid the need for forward + declarations in stub initializers. + +1999-04-23 + + * library/encoding/koi8-r.enc: + * tools/encoding/koi8-r.txt: Added support for the koi8-r Cyrillic + encoding. [Bug: 1771] + +1999-04-22 + + * win/tclWinFCmd.c: + * win/tclWin32Dll.c: Changed uses of "try" to "__try", since that + is the actual keyword. This eliminates the need for some -D flags + from the makefile. + + * generic/tclPort.h: Added include of tcl.h since it defines + various Windows macros that are needed before deciding which + platform porting file to use. + + * generic/tclEvent.c: lint + + * win/tclWinInit.c (TclpInitPlatform): Added call to TclWinInit + when building a static library since DllMain will not be invoked. + This could break old code that explicitly called TclWinInit, but + should be simpler in the long run. + +1999-04-22 Scott Stanton + + * generic/tclInt.h: + * generic/tclInt.decls: + * generic/tclCompile.c: Added TclSetByteCodeFromAny that takes a + hook procedure to invoke after compilation but before the byte + codes are emitted. This makes it possible to do postprocessing on + the compiled byte codes before the ByteCode is generated. + + * generic/tclLiteral.c: Added TclHideLiteral and TclAddLiteralObj + to make it possible to create local unshared literal objects. + + * win/tclWinInit.c: + * unix/tclUnixInit.c: Changed initial search path to match that + found used by tcl_findLibrary. + +1999-04-22 + + * win/tclWinPort.h: + * win/tclWinSock.c: Added code to use WinSock 2.0 API on NT to + avoid creating a window to handle sockets. API not available on + Win95 and needs to be fixed on Win98, until then continue to use + the older (window-based) scheme on those two OSes. + +1999-04-15 + + * Merged 8.1 back into the main trunk + +1999-04-13 + + * library/encoding/gb2312.enc: + * library/encoding/euc-cn.enc: + * tools/encoding/gb2312.txt: + * tools/encoding/cp950.txt: + * tools/encoding/Makefile: Restored the double byte definition of + GB2312 and added the EUC-CN encoding. EUC-CN is a variant of + GB2312 that shifts the characters into bytes with the high bit set + and includes ASCII as a subset. [Bug: 632] + +1999-04-13 + + * win/tclWinSock.c: Apply patch to allow write access to a socket + if FD_WRITE is sent but FD_CONNECT is not. Some strange problem + with either Win32 or a socket driver. [Bug: 1664 1776] + +1999-04-09 + + * unix/tclUnixNotfy.c: Fixed notifier deadlock situation when the + pipe used to talk back notifier thread is filled with data. When + calling the write() function to feed data down that pipe, unlock + the notifierMutex to allow the notifier to wake up again. Found + as a result of the focus.test for Tk hanging. [Bug: 1700] + +1999-04-06 + + * tests/unixNotfy.test: Fixed hang in tests when built with thread + support. + + * tests/httpold.test: Fixed broken test that didn't wait long + enough for events to arrive. -1999-10-20 DJ Delorie + * tests/unixInit.test: Fixed race condition in test. + + * tests/unixInit.test: + * tests/fileName.test: Minor test nits. + + * unix/tclUnixInit.c (TclpSetInitialEncodings): Fixed bad initial + encoding string. + +1999-04-06 + + * generic/tclVar.c: + * generic/tclEnv.c: Moved the "array set" C level code into a + common routine (TclArraySet). The TclSetupEnv routine now uses + this API to create an env array w/ no elements. + + * generic/tclEnv.c: + * generic/tclWinInit.h: + * generic/tclUnixInit.h: + * generic/tclInt.h: Made the Env module I18N compliant. Changed the + FindVariable routine to TclpFindVariable, that now does a case + insensitive string comparison on Windows, and not on UNIX. [Bug: + 1299, 1500] + +1999-04-05 + + * tests/io.test: Minor test cleanup. + + * generic/tclEncoding.c (Tcl_CreateEncoding): Minor lint to make + it easier to compile on Digital-unix. [Bug: 1659] + + * unix/configure.in: + * unix/tclUnixPort.h: Applied patch for OS/390 to handle lack of + sys/param.h. [Bug: 1725] + + * unix/configure.in: Fixed BSD/OS 4.* configuration to support + shared libraries properly. [Bug: 1730] + +1999-04-05 + + * win/tclWinDde.c: decrease timeout value for DDE calls to 30k + [Bug: 1639] + + * generic/tcl.decls: + * generic/tcl.h: + * generic/tclDecls.h: + * generic/tclInt.decls: + * generic/tclInt.h: + * generic/tclIntDecls.h: + * generic/tclStubInit.c: + * generic/tclUtil.c: Added more functions to the Tcl stubs table, + including all Tcl_ functions not already in it (except Cmd + functions) and Tcl_GetCwd() and Tcl_Chdir() (new functions). + + * tests/safe.test: + * doc/safe.n: + * generic/tclBasic.c: + * library/safe.tcl: The encoding command is not safe as-is, so + create a safe alias to mask out the "encoding system " but + allow all other uses including "encoding system". Added test cases + and updated the man page for Safe Tcl. + +1999-04-05 + + * tests/winTime.test: + * win/tclWinTime.c: Fixed crash in clock command that occurred + when manipulating negative time values in timezones east of + GMT. [Bug: 1142, 1458] + + * tests/platform.test: + * tests/fileName.test: Fixed broken tests. + + * generic/tclFileName.c: Moved global regexps into thread local + storage. + + * tests/socket.test: Changed so tests don't reuse sockets, + since Windows is slow to release sockets. + + * win/tclWinConsole.c: + * win/tclWinPipe.c: + * win/tclWinSerial.c: Fixed race condition where background + threads were terminated while they still held a lock in the + notifier. + +1999-04-02 + + * tests/http.test: Fixed bad test initialization code. + + * generic/tclThreadTest.c (ThreadExitProc): Fixed bug where static + memory was being returned instead of a dynamically allocated + result in error cases. + +1999-04-02 + + * doc/dde.n: + * tools/tcl.wse.in: + * win/makefile.vc: + * win/pkgIndex.tcl: + * win/tclWinDde.c: Add new DDE package, code removed from Tk now + separated into its own package. Changed DDE-based send code into + "dde eval" command. Can be loaded into tclsh (not just wish). + Windows only. + +1999-04-02 + + * tests/expr.test: + * tests/for-old.test: + * tests/for.test: + * tests/foreach.test: + * tests/format.test: + * tests/httpold.test: + * tests/if.test: + * tests/init.test: + * tests/interp.test: + * tests/while.test: Added some tests for known bugs (marked with + knownBug constraint), and cleaned up a few bad tests. + + * generic/regc_locale.c: + * generic/regcustom.h: + * generic/tcl.decls: + * generic/tclCmdIL.c: + * generic/tclCmdMZ.c: + * generic/tclInt.h: + * generic/tclRegexp.c: + * generic/tclScan.c: + * generic/tclTest.c: + * generic/tclUtf.c: + * win/tclWinFCmd.c: + * win/tclWinFile.c: Made various Unicode utility functions + public. The following functions were made public and added to the + stubs table: + Tcl_UtfToUniCharDString, Tcl_UniCharToUtfDString, + Tcl_UniCharLen, Tcl_UniCharNcmp, Tcl_UniCharIsAlnum, + Tcl_UniCharIsAlpha, Tcl_UniCharIsDigit, Tcl_UniCharIsLower, + Tcl_UniCharIsSpace, Tcl_UniCharIsUpper, Tcl_UniCharIsWordChar + +1999-04-01 + + * tests/registry.test: + * win/tclWinReg.c: Internationalized the registry code. It now + uses Unicode interfaces on NT. [Bug: 1197] + + * tests/parse.test: + * generic/tclParse.c: Fixed crash due to multiple frees in parser + during error cleanup when parsing commands with more tokens than + will fit in the static area of the parse structure. [Bug: 1681] + + * generic/tclInt.h: Removed duplicate declarations. + + * generic/tclInt.decls: + * generic/tcl.decls: Added Tcl_WinUtfToTChar and Tcl_WinTCharToUtf + to the tclPlat table. + +1999-04-01 + + * generic/tcl.decls: + * generic/tcl.h: + * generic/tclBasic.c: + * generic/tclDecls.h: + * generic/StubInit.c: + * tools/genStubs.tcl: + * unix/Makefile.in: + * win/makefile.vc: Applied patch from Jan Nijtmans to fix Ultrix + multiple symbol definition problem. Now, even Tcl includes a copy + of the Tcl stub library. Also fixed TCL_MEM_DEBUG mode (for Tk). + +1999-03-31 + + * win/tclWinConsole.c: WinNT has a bug when reading a single + character from the console. Rewrote the code for the console to + read an entire line at a time using the reader thread. + +1999-03-30 + + * unix/Makefile.in: Removed trailing backslash that broke the + "depend" target. + + * unix/tclUnixInit.c (TclpSetInitialEncodings): Changed to avoid + calling setlocale(). We now look directly at env(LANG) and + env(LC_CTYPE) instead. [Bug: 1636] + + * generic/tclFileName.c: + * generic/tclDecls.h: + * generic/tcl.decls: Removed CONST from Tcl_JoinPath and + Tcl_TranslateFileName because it changes the signature of + Tcl_JoinPath in an incompatible manner. + + * generic/tclInt.h: + * generic/tclLoad.c (TclFinalizeLoad): + * generic/tclEvent.c (Tcl_Finalize): Defer unloading of loadable + modules until all exit handlers have been invoked. + [Bug: 998, 1273, 1573, 1593] + +1999-03-29 + + * generic/tclFileName.c: + * generic/tclDecls.h: + * generic/tcl.decls: Added CONST to Tcl_JoinPath and + Tcl_TranslateFileName. + +1999-03-29 + + * tools/genStubs.tcl: + * unix/configure.in: + * unix/Makefile.in: + * win/makefile.vc: + * generic/tcl.h: + * generic/tclBasic.c: + * generic/tclDecls.h: + * generic/tclIntDecls.h: + * generic/tclPlatDecls.h: + * generic/tclIntPlatDecls.h: Removed the stub functions and + changed the stub macros to just use the name without params. Pass + &tclStubs into the interp (don't use tclStubsPtr because of + collisions with the stubs on Solaris). + +1999-03-27 + + * win/makefile.bc: Removed makefile for Borland compiler, no + longer supported. + +1999-03-26 + + * win/tclWinSerial.c: + * win/tclWinConsole.c: + * win/tclWinPipe.c: Don't close the Win32 handle for a channel if + it's a stdio handle (GetStdHandle()) during shutdown of a thread + to prevent it from destroying the stdio of other threads. + +1999-03-26 + + * unix/configure.in + --nameble-shared is now the default and build Tcl as a shared + library; specify --disable-shared to build a static Tcl library + and shell. + +1999-03-25 + + * tests/interp.test: + * generic/tclInterp.c (AliasObjCmd): Changed so aliases are + invoked at current scope in the target interpreter instead of at + the global scope. This was an incompatibility introduced in 8.1 + that is being removed. [Bug: 1153, 1556] + + * library/encoding/big5.enc: + * library/encoding/gb2312.enc: + * tools/encoding/big5.enc: + * tools/encoding/gb2312.enc: Added ASCII to big5 and gb2312 + encodings. [Bug: 632] + + * generic/tclPkg.c (Tcl_PkgRequireEx): Fixed broken clientData + initialization in package code. + + * unix/Makefile.in (dist): Added tcl.decls and tclInt.decls to + source distribution. [Bug: 1571] + + * doc/Thread.3: Updated documentation of Tcl_MutexLock to indicate + that the recursive locking behavior is undefined. On Windows, it + does not block, on Unix it deadlocks. [Bug: 1275] + +1999-03-24 + + * tests/execute.test: + * generic/tclExecute.c (TclExecuteByteCode): Fixed expression code + that incorrectly returned floating point values for integers if + the internal rep happened to be a double. Now we check to see if + the object has a string rep that looks like an integer before + using the double internal rep. [Bug: 1516] + +1999-03-24 + + * generic/tclAlloc.c: + * generic/tclEncoding.c: + * generic/tclProc.c: + * unix/tclUnixTime.c: + * win/tclWinSerial.c: Fixed compilation warnings/errors for VC++ + 5.0 and 6.0 and HP-UX native compiler without -Aa or -Ae. + [Bug: 1323 1518 1324 1583 1585 1586] + + * win/tclWinSock.c: Make sockets thread-safe on Windows. The + current implementation uses windows to handle events on the + socket, one for each thread (thread local storage). Previously, + there was only one window shared between threads, which didn't + work. [Bug: 1326] + +1999-03-23 + + * tools/tcl.wse: Fixed file association to look in the right place + for the wish icon. [Bug: 1544] + + * tests/winNotify.test: + * tests/ioCmd.test: + * tests/event.test: Changed to use new style conditionals. + + * tests/encoding.test: Fixed nonportable test. + + * unix/dltest/configure.in: + * unix/dltest/Makefile.in: Added missing DBGX macros. [Bug: 1564] + + * tests/winNotify.test: + * mac/tclMacNotify.c: + * win/tclWinNotify.c: + * unix/tclUnixNotfy.c: + * generic/tclNotify.c: Added a new Tcl_ServiceModeHook interface + that is invoked whenever the service mode changes. This is needed + to allow the Windows notifier to create a communication window the + first time Tcl is about to enter an external modal event loop + instead of at startup time. This will avoid the various problems + that people have been seeing where the system hangs when tclsh + is running outside of the event loop. [Bug: 783] + + * generic/tclInt.h: + * generic/tcl.decls: Renamed TclpAlertNotifier back to + Tcl_AlertNotifier since it is part of the public notifier driver + API. + +1999-03-23 + + * win/tclWinSerial.c: Fixed problem with fileevent on the serial + port and nonblocking mode. Gets no longer hangs, fileevents fire + whenever there is any character data on the port. + + * tests/winConsole.test: + * win/tclWinConsole.c: Fixed problem with fileevents and gets from + a console stdin. Previously, fileevents were firing before an + entire line was available for reading, which meant that when you + did a gets or read, it blocked (even in nonblocking mode). Now, it + should work the same as Unix: fileevents fire when an entire line + is ready, and gets and read do not block in non-blocking mode. + Added an interactive test case to check for this. + +1999-03-22 + + * tests/reg.test: + * generic/regc_color.c: Applied regexp bug fix from Henry Spencer. + +1999-03-19 + + * generic/tclCmdIL.c: Fixed the initialization of an array so that + the Sun 5.0 C compiler wouldn't complain. + + * unix/configure.in: Added support for --enable-64bit. For now, + this is only supported on Solaris 7 64bit (SunOS 5.7) using the Sun + compiler (not gcc). + +1999-03-18 + + * win/tclWinChan.c (TclpOpenFileChannel, Tcl_MakeFileChannel): + Changed to only test for console or comm handles when the type is + FILE_TYPE_CHAR to avoid useless tests on simple files. Also + reordered tests so consoles are tested first as this is more + common. + + * win/makefile.vc: Regularized usage of mkd and rmd and rm. + + * library/encoding/shiftjis.enc: + * tools/encoding/shiftjis.txt: Missing/incorrect characters in + shift-jis table. [Bug: 1008, 1526] + + * generic/tclInt.decls: + * generic/tcl.decls: Eliminated use of "string" and "list" from + argument lists to avoid conflicts with C++ STL. [Bug: 1181] + + * win/tclWinFile.c (TclpMatchFiles): Changed to ignore the + FS_CASE_IS_PRESERVED bit and always return exactly what we get + from the system. + +1999-03-17 + + * win/README.binary: + * win/README: + * unix/configure.in: + * generic/tcl.h: + * README: Updated version to 8.1b3. + +1999-03-14 + + * win/tclWinConsole.c: + * win/tclWinPipe.c: + * win/tclWinSerial.c: Changed so channel drivers wait for the + reader/writer threads to exit before returning during a close + operation. This ensures that the main thread is the last thread + to exit, so the process return value is set properly. + + * generic/tclIntDecls.h: + * generic/tclIntPlatDecls.h: + * generic/tclIntPlatStubs.c: + * generic/tclIntStubs.c: + * generic/tclPlatDecls.h: + * generic/tclPlatStubs.c: + * generic/tclStubInit.c: + * generic/tclStubs.c: Fixed bad eol characters. + + * generic/tclInt.decls: Changed "const" to "CONST" in + declarations for better portability. + + * generic/tcl.decls: Renamed panic and panicVA to Tcl_Panic and + Tcl_PanicVA in the stub files. + + * generic/tclInterp.c (Tcl_MakeSafe): Remove tcl_platform(user) + from safe interps. + +1999-03-11 + + * unix/Makefile.in: + * unix/configure.in: Include compat files in the stub library in + addition to the main library. Compat files are now built for + dynamic use in all cases. + + * generic/tcl.h: Changed magic number so it doesn't match the plus + patch, at Jan's request. + + * unix/tclConfig.sh.in: + * unix/dltest/Makefile.in: + * unix/dltest/configure.in: + * unix/dltest/pkga.c: + * unix/dltest/pkgb.c: + * unix/dltest/pkgc.c: + * unix/dltest/pkgd.c: + * unix/dltest/pkge.c: + * unix/dltest/pkgf.c: Changed package tests to build against the + stubs library. + +1999-03-10 + + * generic/tcl.h: + * generic/tcl.decls: Changed Tcl_ReleaseType from an enum to + macros so it can be used in .rc files. + Added Tcl_GetString. + + * mac/tclMacNotify.c: + * generic/tclNotify.c: + * generic/tclInt.h: + * win/tclWinNotify.c: + * generic/tcl.h: Renamed Tcl_AlertNotifier to TclpAlertNotifier. + + * generic/tclInt.decls: Added TclWinAddProcess to make it possible + for expect to use Tcl_WaitForPid(). This patch is from Gordon + Chaffee. + + * mac/tclMacPort.h: + * win/tclWinInit.c: + * unix/tclUnixPort.h: + * generic/tclAsync.c: Added TclpAsyncMark to fix bug in async + handling on Windows where async events don't wake up the event + loop. This patch comes from Gordon Chaffee. + + * generic/tcl.decls: Fixed declarations of reserved slots. + +1999-03-10 + + * generic/tclCompile.h: Ensure that the ByteCode struct is binary + compatible with the version in 8.0.6. + + * generic/tcl.h: + * generic/tclBasic.c: Add Tcl_GetVersion() function to the public + C API to allow programs to check the version number of the Tcl + library at runtime. Also added an enum to clarify the release + level (alpha, beta, final). + +1999-03-09 + + * Integrated changes from Tcl 8.0 including: + stubs mechanism + configure patches from Jan Nijtmans + rename of panic to Tcl_Panic + +1999-03-08 + + * win/tclWin32Dll.c: Removed Dll instance from thread-local + storage. + +1999-03-08 + + * generic/tcl.h: Moved Tcl_Mutex, etc. macros above the inclusion + of tclDecls.h to avoid macro conflicts. + + * generic/tclInt.h: + * generic/regc_color.c: + * generic/regcomp.c: + * generic/tclCmdIL.c: + * generic/tclCmdAH.c: + * generic/tclIOCmd.c: + * generic/tclParse.c: + * generic/tclStringObj.c: + * unix/tclUnixNotfy.c: Cleaned up various compiler warnings, + eliminated UCHAR bugs. + + * unix/tclUnixNotfy.c: + * unix/tclUnixThrd.c: + * generic/tclThreadTest.c: + * mac/tclMacThrd.c: Changed TclpCondition*() to Tcl_Condition*(). + + * INTEGRATED PATCHES FROM 8.0.6: + + * generic/tcl.decls: + * generic/tcl.h: + * generic/tclBasic.c: + * generic/tclDecls.h: + * generic/tclInt.decls: + * generic/tclInt.h: + * generic/tclIntDecls.h: + * generic/tclIntPlatDecls.h: + * generic/tclIntPlatStubs.c: + * generic/tclIntStubs.c: + * generic/tclPlatDecls.h: + * generic/tclPlatStubs.c: + * generic/tclStubInit.c: + * generic/tclStubLib.c: + * generic/tclStubs.c: + * tools/genStubs.tcl: + * unix/configure.in: + * unix/Makefile.in: + * unix/tclConfig.sh.in: + * win/makefile.vc: + * win/tclWinPort.h: Added Tcl stubs implementation. There are + now two new macros USE_TCL_STUBS and USE_TCL_STUB_PROCS that + enable use of stubs and disable stub macros respectively. All of + the public and private function declarations from tcl.h and + tclInt.h have moved into the *.decls files and the *Stubs.c and + *Decls.h files are generated using the genStubs.tcl script. + + * unix/Makefile.in: + * unix/configure.in: + * unix/ldAix: Enhanced AIX shared library support. + + * win/tclWinSock.c: Removed a bunch of extraneous PASCAL FAR + attributes from internal functions. + + * win/tclWinReg.c: Changed registry package to use stubs mechanism + so it no longer depends on the specific version of Tcl. + + * doc/AddErrInfo.3: + * doc/Eval.3: + * doc/PkgRequire.3: + * doc/SetResult.3: + * doc/StringObj.3: + * generic/tcl.h: + * generic/tclBasic.c: + * generic/tclPanic.c: + * generic/tclStringObj.c: + * generic/tclUtil.c: + * unix/mkLinks: Added va_list versions of all VARARGS + functions so they can be invoked from the stub functions. + + * doc/package.n: + * doc/PkgRequire.3: + * generic/tclPkg.c: Added Tcl_PkgProvideEx, Tcl_RequireEx, + Tcl_PresentEx, and Tcl_PkgPresent. Added "package present" + command. + + * generic/tclFileName.c: + * mac/tclMacFile.c: + * mac/tclMacShLib.exp: + * unix/tclUnixFile.c: + * win/tclWinFile.c: Changed so TclGetUserHome is defined on + all platforms, even though it is currently a noop on mac and + windows, and renamed it to TclpGetUserHome. + + * generic/tclPanic.c: + * generic/panic.c: Renamed panic to Tcl_Panic. + +1999-02-25 + + * win/makefile.vc: Added tclWinConsole.c and tclWinSerial.c + + * win/tclWinConsole.c: New code to properly deal with fileevents + and nonblocking mode on consoles. + + * win/tclWinSerial.c: New code to properly deal with fileevents + and nonblocking mode on serial ports. + + * win/tclWinPipe.c: + * win/tclWinPort.h: Exported functions to allow creation of pipe + channels from tclWinChan.c + + * win/tclWinChan.c: Check the type of a channel, including for the + standard (stdin/stdout/stderr), and use the correct channel type + to create the channel (file, serial, console, or pipe). + +1999-02-11 + + * README: + * generic/tcl.h: + * win/README.binary: + * win/README: + * unix/configure.in: + * mac/README: Updated version numbers to 8.1b2. + +1999-02-10 + + * library/auto.tcl: Fixed auto_mkindex so it handles .tbc files. + Did some general cleanup to handle bad eval statements that didn't + use "list". + + * unix/mkLinks: + * doc/SetVar.3: + * generic/tcl.h: + * generic/tclVar.c: Restored Tcl_ObjGetVar2 and Tcl_ObjSetVar2 + from 8.0. Renamed Tcl_Get/SetObjVar2 to Tcl_GetVar2Ex and + Tcl_SetVar2Ex. + +1999-02-10 + + INTEGRATED PATCHES FROM 8.0.5b2: + + * test/winPipe.test: Changed to remove echoArgs.tcl temporary file + when done. + + * tests/cmdAH.test: + * generic/tclFileName.c (TclGetExtension): Changed behavior so the + split happens at the last period in the name instead of the first + period of the last run of periods. So, "foo..o" is split into + "foo." and ".o" now. [Bug: 1126] + + * win/makefile.vc: Added better support for paths with spaces in + the name. Added .lib and support .dlls to the install-binaries + target. Added generate of a pkgIndex.tcl script to the + install-libraries target. + + * win/tclAppInit.c: + * unix/tclAppInit.c: + * mac/tclMacAppInit.c: + * generic/tclTest.c: Changed some EXTERN declarations to extern + since they are not defining exported interfaces. This avoids + generating useless declspec() attributes and makes the windows + makefile simpler. + + * generic/tcl.h: Moved Tcl_AppInit declaration to end and cleared + out TCL_STORAGE_CLASS so it is not declared with a declspec(). + + * tests/interp.test: + * generic/tclInterp.c (DeleteAlias): Changed to use + Tcl_DeleteCommandFromToken so we handle renames properly. This + avoids senseless panic. [Bug: 736] + + * unix/tclUnixChan.c: + * win/tclWinSock.c: + * doc/socket.n: Applied Gordon Chaffee's patch to handle failures + during asynchronous socket connection operations. This adds a new + "-error" fconfgure option to socket channels. [Bug: 893] + + * generic/tclProc.c: + * generic/tclNamesp.c: + * generic/tclInt.h: + * generic/tclCmdIL.c: + * generic/tclBasic.c: + * generic/tclVar.c: Applied patch from Viktor Dukhovni to + rationalize TCL_LEAVE_ERR_MSG behavior when creating variables. + + * generic/tclVar.c: Fixed bug in namespace tail computation. + Fixed bug where upvar could resurrect a namespace variable whose + namespace had been deleted. + + * generic/tclCompile.c (TclCompileExprCmd): Eliminated yet another + bogus optimization in expression compilation. + + * unix/configure.in: Added branch for BSD/OS-4* to shared library + case statement. [Bug: 975] + Fixed to correctly handle IRIX 6.5 n32 library support. [Bug: 1117] + + * win/winDumpExts.c: Patched to be pickier about stripping + @'s. [Bug: 920] + + * library/http2.0/http.tcl: Added catch around eof test in + CopyDone since the user may have already called http::reset. + [Bug: 1108] + + * unix/configure.in: Changed Linux and IRIX to set SHLIB_LIBS to + LIBS so shared libraries are linked with the system + libraries. [Bug: 1018] + + * generic/tclCompile.c (CompileExprWord): Fixed exception stack + overflow bug caused by missing statement. [Bug: 928] + + * generic/tclIOCmd.c: + * generic/tclBasic.c: Objectified the "open" command. [Bug: 1113] + + * generic/tclPosixStr.c (Tcl_ErrnoId, Tcl_ErrnoMsg): When using + egcs, ENOTSUP and EOPNOTSUPP are the same, so now we handle that + case. [Bug: 1137] + + * library/init.tcl: Various small changes requested by Jan Nijtmans. + - If the variable $tcl_library contains the empty string, this + empty string will be put in $auto_path. This is not useful at all, + it only slows down later package processing. + - If the variable tcl_pkgPath is not set, the "unset __dir" + fails. Thich makes init.tcl totally unusable. Better put a "catch" + around it. + - In the function tcl_findLibraries, the "string match" function + only works correctly if $tcl_patchLevel is in one of the forms + "?.?a?", "?.?b?" or "?.?.?". Could a "regexp" be used instead, + then it allows anything to be appended to the patchLevel + string. And it is more efficient. + - The tclPkgSetup function assumes that if $type != "load" then + the type must be "source". This needn't be true. Some users want + to add their own setup types. + [RFE: 1138] [Bug: 978] + + * win/tclWinReg.c: + * doc/registry.n: Added support for HKEY_PERFORMANCE_DATA and + HKEY_DYN_DATA keys. [Bug: 1109] + + * win/tclWinInit.c (TclPlatformInit): Added code to ensure + tcl_pkgPath is set to "" when no registry entry is found. [Bug: 978] + +1999-02-01 + + * generic/tclBasic.c: + * generic/tclCmdAH.c: + * generic/tclCmdIL.c: + * generic/tclCmdMZ.c: + * generic/tclExecute.c: + * generic/tclHistory.c: + * generic/tclIO.c: + * generic/tclIOUtil.c: + * generic/tclInterp.c: + * generic/tclMain.c: + * generic/tclNamesp.c: + * generic/tclParse.c: + * generic/tclProc.c: + * generic/tclTest.c: + * generic/tclTimer.c: + * generic/tcl.h: Made eval interfaces compatible with 8.0 by + renaming Tcl_EvalObj to Tcl_EvalObjEx, renaming Tcl_Eval2 to + Tcl_EvalEx and restoring Tcl_EvalObj and Tcl_GlobalEvalObj + interfaces so they match Tcl 8.0. + +1999-01-28 + + * Merged Tcl 8.0.5b1 changes. + + * generic/tclUtil.c (Tcl_DStringSetLength): Changed so the buffer + overallocates in a manner similar to Tcl_DStringAppend. This + should improve performance for TclUniCharToUtfDString. + +1998-12-11 === Tcl 8.1b1 Release === + +1998-12-10 - * Makefile.in: temporarily disable second subdirectory +2000-03-21 Syd Polk -1999-10-19 DJ Delorie + * configure.in: Check for cygwin, not cygwin32. + * configure: Regenerate. + + * generic/tclInitScript.h: Added newline at end of file to make + current gcc happy. - * Makefile.in: support two subdirectories - * configure[.in]: for Cygwin, build both win and unix variants - * generic/tclEnv.c: include windows.h for cygwin - * generic/tclPort.h: If building the unix variant for cygwin, - pretend we're a unix machine instead of a windows machine. - * unix/Makefile.in: don't list -lc; it breaks on cygwin. - * unix/tclUnixFCmd.c: don't support fifos on cygwin +1999-12-06 Mo DeJong -1999-08-05 DJ Delorie + * win/Makefile.in: added cl flags needed for VC++ 6.0 - * win/tclWinInit.c (TclPlatformInit): add tcl_pkgPath hack +1999-06-21 Syd Polk -1999-05-18 Fred Fish + * generic/tclIO.c: Bug fixes from Scriptics to get exit status + correct on pipe channels. - * generic/tclPosixStr.c (Tcl_ErrnoId): Avoid duplicate case when - ENOTSUP and EOPNOTSUPP are defined to the same thing. - (Tcl_ErrnoMsg): Ditto. +1999-04-22 Syd Polk -Fri Feb 26 17:40:55 1999 Geoffrey Noer + * unix/Makefile.in: Don't install tcl.h for install-libaries. - * win/configure.in: change "cygwin32*" to "cygwin*" - * win/configure: Regenerated. - * configure.in: Change "cygwin32*" to "cygwin*" - * configure: Regenerate. +1999-02-16 Syd Polk + + * win/configure.in: TCL_SRC_DIR needs to have forward slashes + for the MS build. + * win/configure: Regenerate. + * win/tclWinInit.c: Stupid Visual C++ compiler has limit on + number of characters in string constant. 1999-02-11 Syd Polk - * unix/configure.in: Forgot to AC_SUBST TCL_LIB_FULL_PATH - * unix/configure: Regenerated. + * generic/tclInitScript.h: The tclInit proc that Jim Ingham wrote + blew MS's string buffer away, so I hacked the original in for the + Microsoft build, which only SN is using anyway. Yuck. -1999-02-10 Syd Polk +1999-02-08 Syd Polk - * unix/configure.in unix/tclConfig.sh.in: Export TCL_LIB_FULL_PATH - for dependencies. + * unix/configure.in: Fixed problem with test in --enable-symbols. * unix/configure: Regenerated. + * library/auto.tcl: Fixed a problem with the regsub inside of + auto_mkindex since the regsub semantics changed. -1999-01-27 James Ingham +1999-02-04 James Ingham - * generic/tclInitScript.h: Added two missing \n\'s to initScript - *generic/tclCmdIL.c: Fixed #ifdef that was giving gcc warning. + * generic/tclInitScript.h: Change the tclInit proc to find the Tcl + library in both build & install trees. + * library/auto.tcl (tcl_findLibrary): Change tcl_findLibrary to + search around the executible for the tclConfig.sh, and then use + this to find the source tree. This works in many more cases than + the Scriptics version. -1999-01-20 James Ingham + * configure.in: If no value is given for --enable-symbols, use the + value from AC_PROG_CC, this adds -g for gcc. - * library/init.tcl (auto_mkindex_parser::mkindex): Clean out the parser - interpreter completely between each file, rather than - trying to remove imports by hand. The latter method loses with - IncrTcl, since that imports the class command by hand, and if you - ever do "namespace import itcl::*" in your code, this will get - undone. +1999-01-19 Ben Elliston -Tue Nov 24 18:27:40 1998 Jim Ingham jingham@cygnus.com + * tools/encoding/shiftjis.txt: Map tilde in ShiftJIS to tilde in + Unicode. - * Import of Tcl8.0.4 from Scriptics. + * library/encoding/shiftjis.enc: Regenerate. -Thu Sep 17 17:03:18 1998 Martin M. Hunt +1998-12-21 Syd Polk - * configure: Rebuilt - * unix/configure: Rebuilt + * generic/tclCompExpr.c: Remove another instance of string + blasting. -Tue Aug 25 18:13:30 1998 Jim Ingham + * generic/tclLiteral.c (TclDeleteLiteralTable): Make code + that detects infinite loops exit gracefully in production + build and panic in development build. - * init.tcl (tcl_findLibrary): Added an argument determining - whether to source a packages init file into the TclPro - debugger or not. +1998-12-21 Khamis Abuelkomboz -Thu Aug 20 14:32:59 1998 Jim Ingham jingham@cygnus.com + * generic/tclLiteral.c (TclDeleteLiteralTable): added a daemon to catch + a hanging bug by deleteing a literal. - * Import of Tcl 8.0.3 from Scriptics, with our modifications. - I also changed the Sciptics startup code so it can find our - libraries whether in the build tree or the install tree. +1998-12-19 Syd Polk -1998-07-03 Ben Elliston + * generic/tclCompile.c (tclCompileScript): Localize modifying + the compiled string to the call which needs it. This prevents + the string getting hashed incorrectly later. - Patches from Ian Roxborough . - * generic/tclCmdIL.c (Tcl_LsearchObjCmd): Additional test when - compiling with Microsoft Visual C++. + * generic/tclAlloc.c: Latest patch from Scriptics. - * win/configure.in: Add AC_OBJEXT macro invocation. +1998-12-16 Syd Polk - * win/configure: Regenerate. + * tools/encoding/shiftjis.txt: Unicode character 0xFF5E + was missing from the shiftjis table. + * library/encoding/shiftjis.enc: Regnerated. + +1998-12-16 Ben Elliston + + * generic/tclBasic.c (builtInCmds): Add `encoding'. Patch from + Scriptics. + + * generic/tclCmdAH.c (Tcl_EncodingObjCmd): New function. Patch + from Scriptics. - * win/Makefile.in: Don't assume object files end in `.o'. + * generic/tclEncoding.c: Changed at the same time as the rest of + these files, so it might be important. Patch from Scriptics. - * win/tclWinPort.h (PASCAL): Define when compiling with Microsoft - Visual C++. + * doc/encoding.n: New file. From Scriptics. - * win/tclWinSock.c (PASCAL): Likewise. +1998-12-03 Syd Polk + + * generic/tclIO.c: Integrated more complete fix to + channel problem from Scott Stanton at Scriptics. + +1998-12-02 Syd Polk + + * generic/tclIO.c: Fixed problem when writing out to a + channel set to -crlf translations. + +1998-12-02 Ian Roxborough + + * win/tclWinChan.c: Merged in WishCon0.1 Changes to + support pipe IO at console level of a WishShell. + +1998-11-24 Syd Polk + + * win/Makefile.in: Under MSVC, use the Tcl dumpexts method + to generate exports. + * win/tclWinPort.h tclWinSock.c: Do not #define PASCAL away. + It is needed in calls to DLLs. + +1998-11-18 Syd Polk + + * generic/tclAlloc.c: Made sure that blocks are allocated on + eight-byte boundaries. + * unix/tclUnixPort.h: Added a CYGNUS LOCAL comment. + +1998-11-09 Ben Elliston + + * generic/tclVar.c (TclGetIndexedScalar): Fix a general problem + with compiled local variables that are upvar'ed. Contributed by + Scott Stanton . + +1998-11-04 Ian Roxborough -Tue Jun 30 18:56:27 1998 Jim Ingham + * win/tclWinPort.h: #endif in the wrong place and missing ')'. + +1998-11-06 Syd Polk + + * win/tclWinPort.h: Updated from Scriptics. Tcl_Realloc no longer + fails with blocks that are more than 64K. + +1998-11-04 Ian Roxborough + + * generic/panic.c (panic): Removed a #define _DEBUG, + under MSVC if you want an exception Breakpoint instead + of a panic dialog, CFLAGS must contain -D_DEBUG. - * generic/tclListObj.c (Tcl_SetListObj, SetListFromAny) Import a - change to the list code from tcl8.1 which prevents a crash - when you do Tcl_SetListObj(obj, 0, NULL) on an object which - has been created with Tcl_NewObj, but never written into. +1998-11-03 Ian Roxborough -Thu Jun 18 10:25:00 1998 Syd Polk + * generic/panic.c (panic): If compiling with Microsoft, have this + generate an exception Breakpoint. + +1998-11-03 Syd Polk + + * generic/panic.c: If compiling with Microsoft, have this generate + a core dump so that we can actually see where it is happening when + we have co stdout/stderr. + +1998-10-29 Syd Polk + + * win/configure.in: Removed check for caddr_t. This configure.in + is not really ready for autoheader and the other garbage. + * win/configure: Regenerated. + * generic/tclAlloc.c: Put declaration of caddr_t inside of + #ifdef _MSC_VER. It appears that this is the only compiler that + is missing this typedef. + +1998-10-29 Syd Polk + + * win/Makefile.in: The directory for encodings is called 'encoding', + not 'encodings'. + +1998-10-29 Syd Polk + + * unix/configure.in: Fix merge problem with socket libraries. Run + autoconf test for caddr_t. + * unix/configure: Regenerate. + * win/configure.in Run autoconf test for caddr_t. + * win/configure: Regnerate. + * generic/tclAlloc.c: Remove declaration of caddr_t. Should be + provided by configure now. + +1998-10-28 Syd Polk + + * unix/Makefile.in: Install encodings from make install. + * win/Makefile.in: Install encodings from make install. + +1998-10-28 Ben Elliston + + * win/configure.in (TCL_BUILD_INCLUDES): Remove. Do not subst. + * win/configure: Regenerate. + +1998-10-26 Syd Polk + + * win/Makefile.in: Fix references to old opt0.1 library. + +1998-10-20 Syd Polk + + * unix/Makefile.in: Fix references to old opt0.1 library. + +1998-10-19 Ben Elliston + + * unix/configure.in: Compute a value for @TCL_BUILD_INCLUDES@. + + * unix/configure: Regenerate. + + * unix/tclConfig.sh.in (TCL_BUILD_INCLUDES): Set. - * The import from Tcl 8.1a2 created all of the files that wer - in the Tcl 8.1a2 distribution but not in devo. Since they - are on their own branch, I removed them from devo. + * win/configure.in: Compute a value for @TCL_BUILD_INCLUDES@. + + * win/configure: Regenerate. -Fri Jun 12 11:42:30 1998 Ian Lance Taylor +1998-10-14 Syd Polk - * win/install-sh: Remove. + * win/configure.in Makefile.in: More fixes for the tcl8.l build + * win/configure: Regenerated -Fri Jun 12 11:42:10 1998 Mumit Khan +1998-10-14 Syd Polk - * configure.in (*-*-mingw32*): Support. - * win/Makefile.in (TCL_ALLOC_OBJ, DLL_LDLIBS, DLL_LDFLAGS): New - variables. - (TCLOBJS): Use TCL_ALLOC_OBJ. - ($(TMPDIR)/tclcyg.def): Ignore errors. - ($(TMPDIR)/tclplugin.def): Likewise. - ($(TCLDLL),$(TCLPLUGINDLL,$(TCLREGDLL)): Cleanup DLL build flags - and use TCL_ALLOC_OBJ, DLL_LDLIBS and DLL_LDFLAGS. - * win/configure.in: Call AC_CANONICAL_HOST. - (TCL_ALLOC_OBJ, DLL_LDLIBS, DLL_LDFLAGS): Define and substitute. - (TCL_PATCH_LEVEL): Bump to p2. - * win/tclWinPort.h (environ, hypot, exception): Define for Mingw32. - (EDEADLOCK): Undefine for Mingw32. - * win/configure: Rebuild. + * generic/tclCmdIL.c (SortCompare}: Support as much of the old + comparison semantics as possible. It is now possible to do + lsort -command {foo bar} {1 3 45}. + * tests/cmdIL.test (cmdIL-3.16}: Restore test. -Fri May 29 17:11:01 1998 Ian Lance Taylor +1998-10-08 Syd Polk - * win/Makefile.in (install-minimal): Don't create - INCLUDE_INSTALL_DIR. + * generic/tclCmdIL.c (SortCompare): Make the comparison callback + object based for performance. + * tests/cmdIL.test (cmdIL-3.16): Test relied on incorrect behavior + of old string based comparison callback, which was a bug. Corrected + test. + * unix/configure.in: Minor fixes for gcc + * unix/configure: Regenerated + * unix/dltest/configure.in: GCC needs -f writeable-strings + * unix/dltest/Makefile.in: Fixed invalid TCL_CFLAGS reference + * unix/dltest/configure: Regenerated. -Sun May 24 11:18:28 1998 Khamis Abuelkomboz +1998-10-01 Ben Elliston - * generic/tclCmdIL.c (Tcl_LsearchObjCmd): using strnicmp for MSVC, - strncasecmp otherwise. + * generic/tclCmdIL.c (InfoEncodingsCmd): New function. Implement a + Tcl ``info encodings'' command. + (Tcl_InfoObjCmd): Detect ``encodings'' subcommand. -Fri May 22 16:56:53 1998 Khamis Abuelkomboz + * doc/info.n: Update documentation. + +1998-09-29 Syd Polk + + * win/Makefile.in: Still some hard-coded references to 8.0. + Fix problems with try and except + * win/configure.in: Likewise + * win/configure: Regenerated + * win/tclWin32Dll.c: try and except not supported under gcc. + +1998-09-28 Syd Polk + + * generic/tclClock.c: timezone needs to be declared somewhere + * win/Makefile.in: Fixed OBJEXT problems + * win/tclWinFile.c win/tclWinInit.c: Fixed merge problems + * win/tclWinPipe.c: Removed Cygnus thread stuff to use the tcl 8.1 + thread stuff instead. - * generic/tclCmdIL.c (NOCASE): let lsearch accept "-nocase" - (DICTIONARY): likewise, a synonym for "nocase". - So you can call lsearch with a "-nocase" or "-dictionary" flag to - use strcasecmp to find an item. +1998-09-28 Syd Polk + + * win/configure.in: Merged from 4.2 branch + * win/configure: Regenerated + * win/Makefile.in: Updated for tcl8.1. + +Wed Aut 19 17:48:00 PDT 1998 Syd Polk + + * 8.1 integration continues. Thu Apr 30 18:10:15 1998 Geoffrey Noer @@ -869,3 +5257,4 @@ Sun Nov 8 21:56:26 1992 david d `zoo' zuhn (zoo at cirdan.cygnus.com) * New file for GNU/Cygnus distribution of TCL. + diff --git a/tcl/Makefile.in b/tcl/Makefile.in index bbe52909b5b..983d674c32a 100644 --- a/tcl/Makefile.in +++ b/tcl/Makefile.in @@ -3,7 +3,6 @@ # Tom Tromey CONFIGDIR=@CONFIGDIR@ -CONFIGDIR2=@CONFIGDIR2@ VPATH = @srcdir@ SHELL = @SHELL@ @@ -11,17 +10,12 @@ SRC_DIR = @srcdir@ @SET_MAKE@ -all: - @cd $(CONFIGDIR) && $(MAKE) $@ - @test x"$(CONFIGDIR2)" = x"" || (cd "$(CONFIGDIR2)" && $(MAKE) $@) - -install test install-binaries install-libraries install-minimal: +all install test install-binaries install-libraries install-minimal: @cd $(CONFIGDIR) && $(MAKE) $@ mostlyclean-recursive clean-recursive distclean-recursive \ maintainer-clean-recursive: @cd $(CONFIGDIR) && $(MAKE) `echo $@ | sed 's/-recursive//'` - @test x"$(CONFIGDIR2)" = x"" || (cd "$(CONFIGDIR2)" && $(MAKE) `echo $@ | sed 's/-recursive//'`) configure: cd $(SRC_DIR) && autoconf @@ -70,3 +64,4 @@ Makefile: Makefile.in config.status config.status: configure $(SHELL) config.status --recheck + diff --git a/tcl/README b/tcl/README index c2ba9689946..55ae9576f02 100644 --- a/tcl/README +++ b/tcl/README @@ -1,52 +1,73 @@ -Tcl +README: Tcl + This is the Tcl 8.3.2 source distribution. + You can get any release of Tcl from: + http://dev.scriptics.com/registration/.tml + Tcl/Tk is also available through NetCVS: + http://dev.scriptics.com/software/tcltk/netcvs.html RCS: @(#) $Id$ +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 as a +service to the Tcl community by Scriptics Corporation. +The official home for Tcl/Tk is on the Scriptics Web site: -This directory and its descendants contain the sources and documentation -for Tcl, an embeddable scripting language. The information here -corresponds to release 8.0.4, which is the fourth patch update for Tcl -8.0. This patch provides compatibility with [incr Tcl] 3.0. -Tcl 8.0 is a major new release that replaces the core of the -interpreter with an on-the-fly bytecode compiler to improve execution -speed. It also includes several other new features such as namespaces -and binary I/O, plus many bug fixes. The compiler introduces a few -incompatibilities that may affect existing Tcl scripts; the -incompatibilities are relatively obscure but may require modifications -to some old scripts before they can run with this version. The compiler -introduces many new C-level APIs, but the old APIs are still supported. -See below for more details. This patch release fixes various bugs in -Tcl 8.0, plus it adds a few minor features to support the TclPro 1.0 -tool set and [incr Tcl] 3.0. Please check the changes file for details. + 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 ----------------- +--------------- -The best way to get started with Tcl is to read one of the introductory -books on Tcl: +Extensive documentation is available at our website. +The home page for this release, including new features, is + http://dev.scriptics.com/software/tcltk/8.3.html - Practical Programming in Tcl and Tk, 2nd Edition, by Brent Welch, - Prentice-Hall, 1997, ISBN 0-13-616830-2 +Detailed release notes can be found at + http://dev.scriptics.com/software/tcltk/relnotes/tcl8.3.2.txt - Tcl and the Tk Toolkit, by John Ousterhout, - Addison-Wesley, 1994, ISBN 0-201-63337-X +Information about Tcl itself can be found at + http://dev.scriptics.com/scripting/ - Exploring Expect, by Don Libes, - O'Reilly and Associates, 1995, ISBN 1-56592-090-2 +There are many Tcl books on the market. Most are listed at + http://dev.scriptics.com/resource/doc/books/ -Other books are listed at -http://www.scriptics.com/resource/doc/books/ -http://www.tclconsortium.org/resources/books.html +2a. Unix Documentation +---------------------- -The "doc" subdirectory in this release contains a complete set of reference -manual entries for Tcl. Files with extension ".1" are for programs (for -example, tclsh.1); files with extension ".3" are for C library procedures; -and files with extension ".n" describe Tcl commands. The file "doc/Tcl.n" -gives a quick summary of the Tcl language syntax. To print any of the man -pages, cd to the "doc" directory and invoke your favorite variant of -troff using the normal -man macros, for example +The "doc" subdirectory in this release contains a complete set of +reference manual entries for Tcl. Files with extension ".1" are for +programs (for example, tclsh.1); files with extension ".3" are for C +library procedures; and files with extension ".n" describe Tcl +commands. The file "doc/Tcl.n" gives a quick summary of the Tcl +language syntax. To print any of the man pages on Unix, cd to the +"doc" directory and invoke your favorite variant of troff using the +normal -man macros, for example ditroff -man Tcl.n @@ -56,218 +77,44 @@ using the normal "man" mechanisms, such as man Tcl -There is also an official home for Tcl and Tk on the Web: - http://www.scriptics.com -These Web pages include information about the latest releases, products -related to Tcl and Tk, reports on bug fixes and porting issues, HTML -versions of the manual pages, and pointers to many other Tcl/Tk Web -pages at other sites. Check them out! +2b. Windows Documentation +------------------------- + +The "doc" subdirectory in this release contains a complete set of +Windows help files for Tcl. Once you install this Tcl release, a +shortcut to the Windows help Tcl documentation will appear in the +"Start" menu: + + Start | Programs | Tcl | Tcl Help 3. Compiling and installing Tcl ------------------------------- -This release contains everything you should need to compile and run -Tcl under UNIX, Macintoshes, and PCs (either Windows NT, Windows 95, -or Win 3.1 with Win32s). - -Before trying to compile Tcl you should do the following things: - - (a) Check for a binary release. Pre-compiled binary releases are - available now for PCs, Macintoshes, and several flavors of UNIX. - Binary releases are much easier to install than source releases. - To find out whether a binary release is available for your - platform, check the Scriptics Tcl Resource Center - (http://www.scriptics.com/resource). Also, check in - the FTP directory from which you retrieved the base - distribution. - - (b) Make sure you have the most recent patch release. Look in the - FTP directory from which you retrieved this distribution to see - if it has been updated with patches. Patch releases fix bugs - without changing any features, so you should normally use the - latest patch release for the version of Tcl that you want. - Patch releases are available in two forms. A file like - tcl8.0.4.tar.Z is a complete release for patch level 4 of Tcl - version 8.0. If there is a file with a higher patch level than - this release, just fetch the file with the highest patch level - and use it. - - Patches are also available in the form of patch files that just - contain the changes from one patch level to another. These - files will have names like tcl8.0p1.patch, tcl8.0p2.patch, etc. They - may also have .gz or .Z extensions to indicate compression. To - use one of these files, you apply it to an existing release with - the "patch" program. Patches must be applied in order: - tcl8.0p1.patch must be applied to an unpatched Tcl 8.0 release - to produce a Tcl 8.0p1 release; tcl8.0p2.patch can then be - applied to Tcl8.0p1 to produce Tcl 8.0p2, and so on. To apply an - uncompressed patch file such as tcl8.0p1.patch, invoke a shell - command like the following from the directory containing this - file (some versions of patch require "-p0"): - patch -p < tcl8.0p1.patch - If the patch file has a .gz extension, invoke a command like the - following: - gunzip -c tcl8.0p1.patch.gz | patch -p - If the patch file has a .Z extension, it was compressed with - compress. To apply it, invoke a command like the following: - zcat tcl8.0p1.patch.Z | patch -p - If you're applying a patch to a release that has already been - compiled, then before applying the patch you should cd to the - "unix" subdirectory and type "make distclean" to restore the - directory to a pristine state. - -Once you've done this, change to the "unix" subdirectory if you're -compiling under UNIX, "win" if you're compiling under Windows, or -"mac" if you're compiling on a Macintosh. Then follow the instructions -in the README file in that directory for compiling Tcl, installing it, -and running the test suite. - -4. Summary of changes in Tcl 8.0 --------------------------------- - -Here are the most significant changes in Tcl 8.0. In addition to these -changes, there are several smaller changes and bug fixes. See the file -"changes" for a complete list of all changes. - - 1. Bytecode compiler. The core of the Tcl interpreter has been - replaced with an on-the-fly compiler that translates Tcl scripts to - byte codes; a new interpreter then executes the byte codes. In - earlier versions of Tcl, strings were used as a universal - representation; in Tcl 8.0 strings are replaced with Tcl_Obj - structures ("objects") that can hold both a string value and an - internal form such as a binary integer or compiled bytecodes. The - new objects make it possible to store information in efficient - internal forms and avoid the constant translations to and from - strings that occurred with the old interpreter. We have not yet - converted all of Tcl to take full advantage of the compiler and - objects and have not converted any of Tk yet, but even so you - should see speedups of 2-3x on many programs and you may see - speedups as much as 10-20x in some cases (such as code that - manipulates long lists). Future releases should achieve even - greater speedups. The compiler introduces only a few minor changes - at the level of Tcl scripts, but it introduces many new C APIs for - managing objects. See, for example, the manual entries doc/*Obj*.3. - - 2. Namespaces. There is a new namespace mechanism based on the - namespace implementation by Michael McLennan of Lucent Technologies. - This includes new "namespace" and "variable" commands. There are - many new C APIs associated with namespaces, but they will not be - exported until Tcl 8.1. Note: the syntax of the namespace command - has been changed slightly since the b1 release. See the changes - file for details. - - 3. Binary I/O. The new object system in Tcl 8.0 supports binary - strings (internally, strings are counted in addition to being null - terminated). There is a new "binary" command for inserting and - extracting data to/from binary strings. Commands such as "puts", - "gets", and "read" commands now operate correctly on binary data. - There is a new variable tcl_platform(byteOrder) to identify the - native byte order for the current host. - - 4. Random numbers. The "expr" command now contains a random number - generator, which can be accessed via the "rand()" and "srand()" math - functions. - - 5. Safe-Tcl enhancements. There is a new "hidden command" - mechanism, implemented with the Tcl commands "interp hide", "interp - expose", "interp invokehidden", and "interp hidden" and the C APIs - Tcl_HideCommand and Tcl_ExposeCommand. There is now support for - safe packages and extension loading, including new library - procedures such as safe::interpCreate (see the manual entry safe.n - for details). - - 6. There is a new package "registry" available under Windows for - accessing the Windows registry. - - 7. There is a new command "file attributes" for getting and setting - things like permissions and owner. There is also a new command - "file nativename" for getting back the platform-specific name for a - particular file. - - 8. There is a new "fcopy" command to copy data between channels. - This replaces and improves upon the not-so-secret unsupported old - command "unsupported0". - - 9. There is a new package "http" for doing GET, POST, and HEAD - requests via the HTTP/1.0 protocol. See the manual entry http.n - for details. - - 10. There are new library procedures for finding word breaks in - strings. See the manual entry library.n for details. - - 11. There are new C APIs Tcl_Finalize (for cleaning up before - unloading the Tcl DLL) and Tcl_Ungets for pushing bytes back into a - channel's input buffer. - - 12. Tcl now supports serial I/O devices on Windows and Unix, with a - new fconfigure -mode option. The Windows driver does not yet - support event-driven I/O. - - 13. The lsort command has new options -dictionary and -index. The - -index option allows for very rapid sorting based on an element - of a list. - - 14. The event notifier has been completely rewritten (again). It - should now allow Tcl to use an external event loop (like Motif's) - when it is embedded in other applications. No script-level - interfaces have changed, but many of the C APIs have. - -Tcl 8.0 introduces the following incompatibilities that may affect Tcl -scripts that worked under Tcl 7.6 and earlier releases: - - 1. Variable and command names may not include the character sequence - "::" anymore: this sequence is now used as a namespace separator. - - 2. The semantics of some Tcl commands have been changed slightly to - maximize performance under the compiler. These incompatibilities - are documented on the Web so that we can keep the list up-to-date. - See the URL http://www.sunlabs.com/research/tcl/compiler.html. - - 3. 2-digit years are now parsed differently by the "clock" command - to handle year 2000 issues better (years 00-38 are treated as - 2000-2038 instead of 1900-1938). - - 4. The old Macintosh commands "cp", "mkdir", "mv", "rm", and "rmdir" - are no longer supported; all of these features are now available on - all platforms via the "file" command. - - 5. The variable tcl_precision is now shared between interpreters - and defaults to 12 digits instead of 6; safe interpreters cannot - modify tcl_precision. The new object system in Tcl 8.0 causes - floating-to-string conversions (and the associated rounding) to - occur much less often than in Tcl 7.6, which can sometimes cause - behavioral changes. - - 6. The C APIs associated with the notifier have changed substantially. - - 7. The procedures Tcl_CreateModalTimeout and Tcl_DeleteModalTimeout - have been removed. - - 8. Tcl_CreateFileHandler and Tcl_DeleteFileHandler now take Unix - fd's and are only supported on the Unix platform - - 9. The C APIs for creating channel drivers have changed as part of - the new notifier implementation. The Tcl_File interfaces have been - removed. Tcl_GetChannelFile has been replaced with - Tcl_GetChannelHandle. Tcl_MakeFileChannel now takes a platform- - specific file handle. Tcl_DriverGetOptionProc procedures now take - an additional interp argument. +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/support/howto/compile.html -5. Tcl newsgroup ------------------ -There is a network news group "comp.lang.tcl" intended for the exchange -of information about Tcl, Tk, and related applications. Feel free to use -the newsgroup both for general information questions and for bug reports. -We read the newsgroup and will attempt to fix bugs and problems reported -to it. +4. TclPro Development tools +-------------------- + +A high quality set of commercial development tools is now available to +accelerate your Tcl application development. Scriptics' TclPro +product provides a debugger, static code checker, packaging utility, +and bytecode compiler. Visit the Scriptics Web site at: + + http://dev.scriptics.com/tclpro + +for more information on TclPro and for a free evaluation download. + +5. Tcl newsgroup +---------------- -When using comp.lang.tcl, please be sure that your e-mail return address -is correctly set in your postings. This allows people to respond directly -to you, rather than the entire newsgroup, for answers that are not of -general interest. A bad e-mail return address may prevent you from -getting answers to your questions. You may have to reconfigure your news -reading software to ensure that it is supplying valid e-mail addresses. +There is a network news group "comp.lang.tcl" intended for the +exchange of information about Tcl, Tk, and related applications. The +newsgroup is a great place to ask general information questions. For +bug reports, please see the "Support and bug fixes" section below. 6. Tcl contributed archive -------------------------- @@ -275,126 +122,86 @@ reading software to ensure that it is supplying valid e-mail addresses. Many people have created exciting packages and applications based on Tcl and/or Tk and made them freely available to the Tcl community. An archive of these contributions is kept on the machine ftp.neosoft.com. You -can access the archive using anonymous FTP; the Tcl contributed archive is +can access the archive using anonymous FTP; the Tcl contributed archive is in the directory "/pub/tcl". The archive also contains several FAQ ("frequently asked questions") documents that provide solutions to problems that are commonly encountered by TCL newcomers. 7. Tcl Resource Center ---------------------- -Visit http://www.scritics.com/resource/ to see an annotated index of + +Visit http://dev.scriptics.com/resource/ to see an annotated index of many Tcl resources available on the World Wide Web. This includes -papers, books, and FAQs, as well as extensions, applications, binary -releases, and patches. You can contribute patches by sending them -to . You can also recommend more URLs for the -resource center using the forms labeled "Add a Resource". +papers, books, and FAQs, as well as development tools, extensions, +applications, binary releases, and patches. You can also recommend +additional URLs for the resource center using the forms labeled "Add a +Resource". 8. Mailing lists ---------------- A couple of Mailing List have been set up to discuss Macintosh or -Windows related Tcl issues. In order to use these Mailing Lists you -must have access to the internet. To subscribe send a message to: +Windows related Tcl issues. To subscribe send a message to: wintcl-request@tclconsortium.org mactcl-request@tclconsortium.org In the body of the message (the subject will be ignored) put: - subscribe mactcl Joe Blow + subscribe mactcl Joe Smith -Replacing Joe Blow with your real name, of course. (Use wintcl -instead of mactcl if your interested in the Windows list.) If you +Replace Joe Smith with your real name, of course. (Use wintcl +instead of mactcl if you're interested in the Windows list.) If you would just like to receive more information about the list without subscribing put the line: information mactcl -in the body instead (or wintcl). +(or wintcl) in the body instead. -9. Support and bug fixes +9. Support and Training ------------------------ -We're very interested in receiving bug reports and suggestions for -improvements. We prefer that you send this information to the -comp.lang.tcl newsgroup rather than to any of us at Scriptics. We'll see -anything on comp.lang.tcl, and in addition someone else who reads -comp.lang.tcl may be able to offer a solution. The normal turn-around -time for bugs is 3-6 weeks. Enhancements may take longer and may not +Scriptics is very interested in receiving bug reports, patches, and +suggestions for improvements. We prefer that you send this +information to us via the bug form on the Scriptics Web site, rather +than emailing us directly. The bug form is at: + + http://dev.scriptics.com/ticket/ + +The bug form was designed to give uniform structure to bug reports as +well as to solicit enough information to minimize followup questions. +The bug form also includes an option to automatically post your report +on comp.lang.tcl. We strongly recommend that you select this option +because someone else who reads comp.lang.tcl may be able to offer a +solution. + +We will log and follow-up on each bug, although we cannot promise a +specific turn-around time. Enhancements may take longer and may not happen at all unless there is widespread support for them (we're -trying to slow the rate at which Tcl turns into a kitchen sink). It's -very difficult to make incompatible changes to Tcl at this point, due -to the size of the installed base. - -When reporting bugs, please provide a short tclsh script that we can -use to reproduce the bug. Make sure that the script runs with a -bare-bones tclsh and doesn't depend on any extensions or other -programs, particularly those that exist only at your site. Also, -please include three additional pieces of information with the -script: - (a) how do we use the script to make the problem happen (e.g. - what things do we click on, in what order)? - (b) what happens when you do these things (presumably this is - undesirable)? - (c) what did you expect to happen instead? +trying to slow the rate at which Tcl/Tk turns into a kitchen sink). +It's very difficult to make incompatible changes to Tcl/Tk at this +point, due to the size of the installed base. The Tcl community is too large for us to provide much individual -support for users. If you need help we suggest that you post questions -to comp.lang.tcl. We read the newsgroup and will attempt to answer -esoteric questions for which no-one else is likely to know the answer. -In addition, Tcl support and training are available commercially from -Scriptics (info@scriptics.com), NeoSoft (info@neosoft.com), -Computerized Processes Unlimited (gwl@cpu.com), -and Data Kinetics (education@dkl.com). - -10. Tcl version numbers ----------------------- +support for users. If you need help we suggest that you post +questions to comp.lang.tcl. We read the newsgroup and will attempt to +answer esoteric questions for which no-one else is likely to know the +answer. In addition, Tcl/Tk support and training are available +commercially from Scriptics at: + + http://dev.scriptics.com/training + +Also 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. + -You can test the current version of Tcl by examining the -tcl_version and tcl_patchLevel variables. The tcl_patchLevel -variable follows the naming rules outlined below (e.g., 8.0.4). -The tcl_version just has the major.minor numbers in it (e.g., 8.0) - -Each Tcl release is identified by two numbers separated by a dot, e.g. -6.7 or 7.0. If a new release contains changes that are likely to break -existing C code or Tcl scripts then the major release number increments -and the minor number resets to zero: 6.0, 7.0, etc. If a new release -contains only bug fixes and compatible changes, then the minor number -increments without changing the major number, e.g. 7.1, 7.2, etc. If -you have C code or Tcl scripts that work with release X.Y, then they -should also work with any release X.Z as long as Z > Y. - -Alpha and beta releases have an additional suffix of the form a2 or b1. -For example, Tcl 7.0b1 is the first beta release of Tcl version 7.0, -Tcl 7.0b2 is the second beta release, and so on. A beta release is an -initial version of a new release, used to fix bugs and bad features before -declaring the release stable. An alpha release is like a beta release, -except it's likely to need even more work before it's "ready for prime -time". New releases are normally preceded by one or more alpha and beta -releases. We hope that lots of people will try out the alpha and beta -releases and report problems. We'll make new alpha/beta releases to fix -the problems, until eventually there is a beta release that appears to -be stable. Once this occurs we'll make the final release. - -We can't promise to maintain compatibility among alpha and beta releases. -For example, release 7.1b2 may not be backward compatible with 7.1b1, even -though the final 7.1 release will be backward compatible with 7.0. This -allows us to change new features as we find problems during beta testing. -We'll try to minimize incompatibilities between beta releases, but if -a major problem turns up then we'll fix it even if it introduces an -incompatibility. Once the official release is made then there won't -be any more incompatibilities until the next release with a new major -version number. - -(Note: This compatibility is true for Tcl scripts, but historically the Tcl -C APIs have changed enough between releases that you may need to work a bit to -upgrade extensions.) - -Patch releases have a suffix such as p1 or p2. These releases contain -bug fixes only. A patch release (e.g Tcl 7.6p2) should be completely -compatible with the base release from which it is derived (e.g. Tcl -7.6), and you should normally use the highest available patch release. - -As of 8.0.3, the patch releases use a second . instead of 'p'. So, the -8.0 release went to 8.0p1, 8.0p2, 8.0.3, and 8.0.4. The alphas and betas -will still use the 'a' and 'b' letters in their tcl_patchLevel. diff --git a/tcl/changes b/tcl/changes index 0c52f738e43..29e46fd66c6 100644 --- a/tcl/changes +++ b/tcl/changes @@ -1,6 +1,6 @@ Recent user-visible changes to Tcl: -SCCS: @(#) changes 1.338 97/11/25 08:30:52 +RCS: @(#) $Id$ 1. No more [command1] [command2] construct for grouping multiple commands on a single command line. @@ -1337,7 +1337,7 @@ to platform, which messes up Tcl tests. Tcl_ErrnoMsg uses the standard POSIX messages for all the common signals, and calls strerror for signals it doesn't understand. ------------------ Released patch 7.5p2, 9/15/95 ----------------------- +----------------- Released patch 7.4p2, 9/15/95 ----------------------- ----------------- Released 7.5a1, 9/15/95 ----------------------- @@ -2547,7 +2547,7 @@ changes are to expressions and lists. incorrect programs that took advantage of behavior of the old implementation that was not documented in the man pages. Other changes to Tcl scripts are discussed in the web page at -http://www.sunlabs.com/research/tcl/compiler.html. (BL) +http://www.scriptics.com/doc/compiler.html. (BL) *** POTENTIAL INCOMPATIBILITY *** 10/21/96 (new feature) In earlier versions of Tcl, strings were used as a @@ -3115,7 +3115,7 @@ activity. A refcount bug triggered a panic in Tcl_ListObjAppendElement. (BW) 7/8/97 (bug fix) Relaxed the pattern matching on http_get so you do not need a trailing path component. You can now get away with just -http_get sunscript.sun.com (BW) +http_get www.scriptics.com (BW) 7/9/97 (bug fix) Creating anonymous interpreters no longer smashes existing commands with names similar to the generated name. Previously creating an @@ -3451,7 +3451,7 @@ Universal Headers V.3.0, so that Tcl will compile with CW Pro 2. -gmt flag set. Thanks to Jan Nijtmans for reporting the problem. (RJ) ----------------- Released 8.0p2, 11/25/97 ----------------------- - + 12/3/97 (bug fix/optimization) Removed uneeded and potentially dangerous instances of double evaluations if "if" and "expr" statements from the library files. It is recommended that unless you need a double @@ -3605,3 +3605,1310 @@ the import links move to the new name, and if you delete a command then the import links get lost. These semantics have not changed.) (MC) -------- Released 8.0.3 to the Tcl Consortium CD-ROM project, 8/10/98 ------ + +9/3/98 (bug fix) Tcl_Realloc was failing under Windows because the +GlobalReAlloc API was not correctly re-allocating blocks that were +32k+. The fix was to use newer Win32 APIs (HeapAlloc, HeapFree, and +HeapReAlloc.) (BS) + +10/5/98 (bug fix) Fixed bug in pkg_mkIndex that caused some files that do +a "package require" of packages in the Tcl libraries to give a warning like + warning: "xx.tcl" provides more than one package ({xx 2.0} {yy 0.3}) +and generate a broken pkgIndex.tcl file. (EMS) + +10/5/98 (bug fix) Pkg_mkIndex was not doing a case-insensitive comparison +of extensions to determine whether to load or source a file. Thus, under +Windows, MYDLLNAME.DLL was sourced, and mydllname.dll loaded. (EMS) + +10/5/98 (new feature) Created a new Tcl_Obj type, "procbody". This object's +internal representation holds a pointer to a Proc structure. Extended +TclCreateProc to take both strings and "procbody". (EMS) + +10/13/98 (bug fix) The "info complete" command can now handle strings +with NULLs embedded. Thanks to colin@field.medicine.adelaide.edu.au +for providing this fix. (RJ) + +10/13/98 (bug fix) The "lsort -dictionary" command did not properly +handle some numbers starting with 0. Thanks to Richard Hipp + for submitting the fix to Scriptics. (RJ) + +10/13/98 (bug fix) The function Tcl_SetListObj was creating an invalid +Tcl_Obj if the list had zero elements (despite what the comments said +it would do). Thanks to Sebastian Wangnick for reporting the +problem. (RJ) + +10/20/98 (new feature) Added tcl_platform(debug) element to the +tcl_platform array on Windows platform. The existence of the debug +element of the tcl_platform array indicates that the particular Tcl +shell has been compiled with debug information. Using +"info exists tcl_platform(debug)" a Tcl script can direct the +interpreter to load debug versions of DLLs with the load +command. (SKS) + +10/20/98 (feature change) The Makefile and configure scripts have been +changed for IRIX to build n32 binaries instead of the old 32 abi +format. If you have extensions built with the o32 abi's you will need +to update them to n32 for them to work with Tcl. (RJ) +*** POTENTIAL INCOMPATIBILITY *** + +10/23/98 (bug fix) tcl_findLibrary had a stray ] in one of the +pathnames it searched for the initialization script. tclInitScript.h +was incorrectly adding the parent of tcl_library to tcl_pkgPath. This +logic was moved into init.tcl, and the initialization of auto_path was +documented. Thanks to Donald Porter and Tom Silva for related +patches. (BW) + +10/29/98 (bug fix) Fixed Tcl_NotifyChannel to use Tcl_Preserve instead +of Tcl_RegisterChannel so that 1) unregistered channels do not get +closed after their first fileevent, and 2) errors that occur during +close in a fileevent script are actually reflected by the close +command. (BW) + +10/30/98 (bug fix) Overhaul of pkg_mkIndex to deal with transitive +package requires and packages split among scripts and binary files. +Also fixed ommision of global for errorInfo in tcl_findLibrary. (BW) + +11/08/98 (bug fix) Fixed the resource command to always detect +the case where a file is opened a second time with the same +permissions. IM claims that this will always cause the same +FileRef to be returned, but in MacOS 8.1+, this is no longer the case, +so we have to test for this explicitly. (JI) + +11/10/98 (feature change) When compiling with Metrowerk's MSL, use the +exit function from MSL rather than ExitToShell. This allows MSL to +clean up its temporary files. Thanks to Vince Darley for this +improvement. (JI) + +----------------- Released 8.0.4, 11/19/98 ------------------------- + +11/20/98 (bug fix) Handle possible NULL return in TclGetStdFiles. (RJ) + +11/20/98 (bug fix) The dltests would not build on SGI. They reported +that you could not mix n32 with 032 binaries. The configure script +has been modified to get the EXTRA_CFLAGS from the tcl configure +script. [Bug id: 840] (RJ) + +12/3/98 (bug fix) Windows NT creates sockets so they are inheritable +by default. Fixed socket code so it turns off this bit right after +creation so sockets aren't kept open by exec'ed processes. [Bug: 892] +Thanks to Kevin Kenny for this fix. (SS) + +1/11/98 (bug fix) On HP, "info sharedlibextension" was returning +empty string on static apps. It now always returns ".sl". (RJ) + +1/28/99 (configure change) Now support -pipe option on gcc. (RJ) + +2/2/99 (bug fix) Fixed initialization problem on Windows where no +searching for init.tcl would be performed if the registry keys were +missing. (stanton) + +2/2/99 (bug fix) Added support for HKEY_PERFORMANCE_DATA and +HKEY_DYN_DATA keys in the "registry" command. (stanton) + +2/2/99 (bug fix) ENOTSUP and EOPNOTSUPP clashed on some Linux +variants. (stanton) + +2/2/99 (enhancement) The "open" command has been changed to use the +object interfaces. (stanton) + +2/2/99 (bug fix) In some cases Tcl would crash due to an overflow of +the exception stack resulting from a missing byte code in some +expressions. (stanton) + +2/2/99 (bug fix) Changed configure so Linux and IRIX shared libraries +are linked with the system libraries. (stanton) + +2/2/99 (bug fix) Added support for BSDI 4.x (BSD/OS-4*) to the +configure script. (stanton) + +2/2/99 (bug fix) Fixed bug where upvar could resurrect a namespace +variable after the namespace had been deleted. (stanton) + +2/2/99 (bug fix) In some cases when creating variables, the +interpreter result was being modified even if the TCL_LEAVE_ERR_MSG +flag was set. (stanton) + +2/2/99 (bug fix & new feature) Changed the socket drivers to properly +handle failures during an async socket connection. Added a new +fconfigure option "-error" to retrieve the failure message. See the +socket.n manual entry for details. (stanton) + +2/2/99 (bug fix) Deleting a renamed interp alias could result in a +panic. (stanton) + +2/2/99 (feature change/bug fix) Changed the behavior of "file +extension" so that it splits at the last period. Now the extension of +a file like "foo..o" is ".o" instead of "..o" as in previous versions. +*** POTENTIAL INCOMPATIBILITY *** + +----------------- Released 8.0.5, 3/9/99 ------------------------- + +======== Changes for 8.0 go above this line ======== +======== Changes for 8.1 go below this line ======== + +6/18/97 (new feature) Tcl now supports international character sets: + - All C APIs now accept UTF-8 strings instead of iso8859-1 strings, + wherever you see "char *", unless explicitly noted otherwise. + - All Tcl strings represented in UTF-8, which is a convenient + multi-byte encoding of Unicode. Variable names, procedure names, + and all other values in Tcl may include arbitrary Unicode characters. + For example, the Tcl command "string length" returns how many + Unicode characters are in the argument string. + - For Java compatibility, embedded null bytes in C strings are + represented as \xC080 in UTF-8 strings, but the null byte at the end + of a UTF-8 string remains \0. Thus Tcl strings once again do not + contain null bytes, except for termination bytes. + - For Java compatibility, "\uXXXX" is used in Tcl to enter a Unicode + character. "\u0000" through "\uffff" are acceptable Unicode + characters. + - "\xXX" is used to enter a small Unicode character (between 0 and 255) + in Tcl. + - Tcl automatically translates between UTF-8 and the normal encoding for + the platform during interactions with the system. + - The fconfigure command now supports a -encoding option for specifying + the encoding of an open file or socket. Tcl will automatically + translate between the specified encoding and UTF-8 during I/O. + See the directory library/encoding to find out what encodings are + supported (eventually there will be an "encoding" command that + makes this information more accessible). + - There are several new C APIs that support UTF-8 and various encodings. + See Utf.3 for procedures that translate between Unicode and UTF-8 + and manipulate UTF-8 strings. See Encoding.3 for procedures that + create new encodings and translate between encodings. See + ToUpper.3 for procedures that perform case conversions on UTF-8 + strings. + +9/18/97 (enhancement) Literal objects are now shared by the ByteCode +structures created when compiled different scripts. This saves up to 45% +of the total memory needed for all literals. (BL) + +9/24/97 (bug fixes) Fixed Tcl_ParseCommand parsing of backslash-newline +sequences at start of command words. Suppressed Tcl_EvalDirect error logging +if non-TCL_OK result wasn't an error. (BL) + +10/17/97 (feature enhancement) "~username" now refers to the users' home +directory on Windows (previously always returned failure). (CCS) + +10/20/97 (implementation change) The Tcl parser has been completely rewritten +to make it more modular. It can now be used to parse a script without actually +executing it. The APIs for the new parser are not correctly exported, but +they will eventually be exported and augmented with Tcl commands so that +Tcl scripts can parse other Tcl scripts. (JO) + +10/21/97 (API change) Added "flags" argument to Tcl_EvalObj, removed +Tcl_GlobalEvalObj procedure. Added new procedures Tcl_Eval2 and +Tcl_EvalObjv. (JO) +*** POTENTIAL INCOMPATIBILITY *** + +10/22/97 (API change) Renamed Tcl_ObjSetVar2 and Tcl_ObjGetVar2 to +Tcl_SetObjVar2 and Tcl_GetObjVar2 (for consistency with other C APIs) +and changed the name arguments to be strings instead of objects. (JO) +*** POTENTIAL INCOMPATIBILITY *** + +10/27/97 (enhancement) Bytecode compiler rewritten to use the new Tcl +parser. (BL) + +11/3/97 (New routines) Added Tcl_AppendObjToObj, which appends the +string rep of one Tcl_Obj to another. Added Tcl_GetIndexFromObjStruct, +which is similar to Tcl_GetIndexFromObj, except that you can give an +offset between strings. This allows Tcl_GetIndexFromObjStruct to be +called with a table of records which have strings in them. (SRP) + +12/4/97 (enhancement) New Tcl expression parser added. Added new procedure +Tcl_ParseExpr and new token types TCL_TOKEN_SUB_EXPR and +TCL_TOKEN_OPERATOR. Expression compiler is reimplemented to use this +parser. (BL) + +12/9/97 (bug fix) Tcl_EvalObj() increments/decrements the refcount of the +script object to prevent the object from deleting itself while in the +middle of being evaluated. (CCS) + +12/9/97 (bug fix) Memory leak in Tcl_GetsObjCmd(). (CCS) + +12/11/97 (bug fix) Environment array leaked memory when compiled with +Visual C++. (SS) + +12/11/97 (bug fix) File events and non-blocking I/O did not work on +pipes under Windows. Changed to use threads to achieve non-blocking +behavior. (SS) + +12/18/97 (bug fixes) Fixed segfault in "namespace import"; importing a +procedure that causes a cycle now returns an error. Modified "info procs", +"info args", "info body", and "info default" to return information about +imported procedures as well as procedures defined in a namespace. (BL) + +12/19/97 (enhancement) Added new Tcl_GetString() procedure that can be used +in place of Tcl_GetStringFromObj() if the string representation's length +isn't needed. (BL) + +12/18/97 (bug fix) In the opt argument parsing package: if the description +had only flags, the "too many arguments" case was not detected. The default +value was not used for the special "args" ending argument. (DL) + +1/7/98 (clean up) Moved everything not absolutly necessary out of init.tcl +procs now in auto.tcl and package.tcl can be autoloaded if needed. (DL) + +1/7/98 (enhancement) tcltest made at install time will search for it's +init.tcl where it is, even when using virtual path compilation. (DL) + +1/8/98 (os bug workaround) when needed, using a replacement for memcmp so +string compare "char with high bit set" "char w/o high bit set" returns +the expected value on all platforms. (DL) + +1/8/98 (unix portability/configure) building from .../unix/targetName/ +subdirectories and simply using "../configure" should now work fine. (DL) + +1/14/98 (enhancement) Added new regular expression package that +supports AREs, EREs, and BREs. The new package includes new escape +characters, meta-syntax, and character classes inside brackets. +Regexps involving backslashes may behave differently. (MH) +*** POTENTIAL INCOMPATIBILITY *** + +1/16/98 (os workaround) Under windows, "file volume" was causing chatter +and/or several seconds of hanging when querying empty floppy drives. +Changed implementation to call an empirically-derived function that doesn't +cause this. (CCS) + +1/16/98 (enhancement) Converted regular expressions to a Tcl_Obj type so +their compiled form gets cached automatically. Reduced NSUBEXP from 100 +to 20. (BW) + +1/16/98 (documentation) Change unclear documentation and comments for +functions like Tcl_TranslateFileName() and Tcl_ExternalToUtfDString(). Now +it explicitly says they take an uninitialized or free DString. A DString +that is "empty" or "not holding anything" could have been interpreted as one +currently with a zero length, but with a large dynamically allocated buffer. +(CCS) + +----------------- Released 8.1a1, 1/22/98 ----------------------- + +1/28/98 (new feature) Added a "-direct" optional flag to pkg_mkIndex +to generate direct loading package indexes (such those you need +if you use namespaces and plan on using namespace import just after +package require). pkg_mkIndex still has limitations regarding +package dependencies but errors are now ignored and with -direct, correct +package indexes can be generated even if there are dependencies as long +as the "package provide" are done early enough in the files. (DL) + +1/28/98 (enhancement) Performance tuning of regexp and regsub. (CCS) + +1/28/98 (bug fix) regexp and regsub with "-indices" returned the byte-offsets +of the characters in the UTF-8 representation, not the character offsets +themselves. (CCS) + +1/28/98 (bug fix) "clock format 0 -format %Z -gmt 1" would return the local +timezone string instead of "GMT" on Solaris and Windows. + +1/28/98 (bug fix) Restore tty settings when closing serial device on Unix. +This is good behavior when closing real serial devices, essential when +closing the pseudo-device /dev/tty because the user's terminal settings +would be left useless, in raw mode, when tcl quit. (CCS) + +1/28/98 (bug fix) Tcl_OpenCommandChannel() was modifying the contents of the +argv array passed to it, causing problems for any caller that wanted to +continue to use the argv array after calling Tcl_OpenCommandChannel(). (CCS) + +2/1/98 (bug fix) More bugs with %Z in format string argument to strftime(): +1. Borland always returned empty string. +2. MSVC always returned the timezone string for the current time, not the + timezone string for the specified time. +3. With MSVC, "clock format 0 -format %Z -gmt 1" would return "GMT" the first + time it was called, but would return the current timezone string on all + subsequent calls. (CCS) + +2/1/98 (bug fix) "file stat" was broken on Windows. +1. "file stat" of a root directory (local or network) or a relative path that + resolved to a root directory (c:. when in pwd was c:/) was returning error. +2. "file stat" on a regular file (S_IFREG), the st_mode was sign extended to + a negative int if the platform-dependant type "mode_t" was declared as a + short instead of an unsigned short. +3. "file stat" of a network directory, the st_dev was incorrectly reported + as the id of the last accessed local drive rather than the id of the + network drive. (CCS) + +2/1/98 (bug fix) "file attributes" of a relative path that resolved to a +root directory was returning error. (CCS) + +2/1/98 (bug fix) Change error message when "file attribute" could not +determine the attributes for a file. Previously it would return different +error messages on Unix vs. Windows vs. Mac. (CCS) + +2/4/98 (bug fixes) Fixed several instances of bugs where the parser/compiler +would reach outside the range of allocated memory. Improved the array +lookup algorithm in set compilation. (DL) + +2/5/98 (change) The TCL_PARSE_PART1 flag for Set/Get(Obj)Var2 C APIs is now +deprecated and ignored. The part1 is always parsed when the part2 argument +is NULL. This is to avoid a pattern of errors for extension writers converting +from string based Tcl_SetVar() to new Tcl_SetObjVar2() and who could easily +forget to provide the flag and thus get code working for normal variables +but not for array elements. The performance hit is minimal. A side effect +of that change is that is is no longer possible to create scalar variables +that can't be accessed by tcl scripts because of their invalid name +(ending with parenthesis). Likewise it is also parsed and checked to +ensure that you don't create array elements of array whose name is a valid +array element because they would not be accessible from scripts anyway. +Note: There is still duplicate array elements parsing code. (DL) +*** POTENTIAL INCOMPATIBILITY *** + +2/11/98 (bug fix) Sharing objects between interps, such as by "interp +eval" or "send" could cause a crash later when dereferencing an interp +that had been deleted, given code such as: + set a {set x y} + interp create foo + interp eval foo $a + interp delete foo + unset a +Interp "foo" was gone, but "a" had a internal rep consisting of bytecodes +containing a dangling pointer to "foo". Unsetting "a" would attempt to +return resources back to "foo", causing a crash as random memory was +accessed. The lesson is that that if an object's internal rep depends on +an interp (or any other data structure) it must preserve that data in +some fashion. (CCS) + +2/11/98 (enhancement) The "interp" command was returning inconsistent error +messages when the specified slave interp could not be found. (CCS) + +2/11/98 (bug fix) Result codes like TCL_BREAK and TCL_CONTINUE were not +propagating through the master/slave interp boundaries, such as "interp +eval" and "interp alias". TCL_OK, TCL_ERROR, and non-standard codes like +teh integer 57 work. There is still a question as to whether TCL_RETURN +can/should propagate. (CCS) + +2/11/98 (bug fix) TclCompileScript() was derefering memory 1 byte before +start of the string to compile, looking for ']'. (CCS,DL) + +2/11/98 (bug fix) Tcl_Eval2() was derefering memory 1 byte before start +of the string to eval, looking for ']'. (CCS,DL) + +2/11/98 (bug fix) Compiling "set a(b" was running off end of string. (CCS,DL) + +2/11/98 (bug fix) Windows initialization code was dereferencing +uninitialized memory if TCL_LIBRARY environment didn't exist. (CCS) + +2/11/98 (bug fix) Windows "registry" command was dereferencing +uninitialized memory when constructing the $errorCode for a failed +registry call. (CCS) + +2/11/98 (enhancement) Eliminate the TCL_USE_TIMEZONE_VAR definition from +configure.in, because it was the same information as the already existing +HAVE_TM_ZONE definition. The lack of HAVE_TM_ZONE is used to work around a +Solaris and Windows bug where "clock format [clock sec] -format %Z -gmt 1" +produces the local timezone string instead of "GMT". (CCS) + +2/11/98 (bug fix) Memleaks and dereferencing of uninitialized memory in +regexp if an error occurred while compiling a regular expression. (CCS). + +2/18/98 (new feature) Added mutexes and thread local storage in order +to make Tcl thread safe. For testing purposes, there is a testthread +command that creates a new thread and an interpreter inside it. See +thread.test for examples, but this script-level interface is not fixed. +Each thread has its own notifier instance to manage its own events, +and threads can post messages to each other's message queue. +This uses pthreads on UNIX, and native thread support on other platforms. +You enable this by configuring with --enable-threads. Note that at +this time *Tk* is still not thread safe. Special thanks to +Richard Hipp: his earlier implementation inspired this work. (BW, SS, JI) + +2/18/98 (hidden feature change) The way the env() array is shared among +interpreters changed. Updates to env used to trigger write traces in +other interpreters. This undocumented feature is no longer implemented. +Instead, variable tracing is used to keep the C-level environ array in sync +with the Tcl-level env array. This required adding TCL_TRACE_ARRAY support +to Tcl_TraceVar2 so that array names works properly. (BW) +*** POTENTIAL INCOMPATIBILITY *** + +2/18/98 (enhancement) Conditional compilation for unix systems (e.g., +IRIX, SCO) that use f_bsize instead of st_blksize to determine disk block +size. (CCS) + +2/23/98 (bug fix) Fixed the emulation of polling selects in the threaded +version of the Unix notifier. The bug was showing up on a multiprocessor +as starvation of the notifier thread. (BW) + +----------------- Released 8.1a2, Feb 23 1998 ----------------------- + +9/22/98 (bug fix) Changed the value of TCL_TRACE_ARRAY so it no longer +conflicts with the deprecated TCL_PARSE_PART1 flag. This should +improve portability of C code. (stanton) + +10/6/98 (bug fix) The compile procedure for "if" incorrectly attempted +to match against the literal string "if", resulting in a stack +overflow when "::if" was compiled. It also would incorrectly accept +"if" instead of "elsif" in later clauses. (stanton) + +10/15/98 (new feature) Added a "totitle" subcommand to the "string" +command to convert strings to capitalize the first character of a string +and lowercase all of the other characters. (stanton) + +10/15/98 (bug fix) Changed regexp and string commands to properly +handle case folding according to the Unicode character +tables. (stanton) + +10/21/98 (new feature) Added an "encoding" command to facilitate +translations of strings between different character encodings. See +the encoding.n manual entry for more details. (stanton) + +11/3/98 (bug fix) The regular expression character classification +syntax now includes Unicode characters in the supported +classes. (stanton) + +11/6/98 (bug fix) Variable traces were causing crashes when upvar +variables went out of scope. [Bug: 796] (stanton) + +11/9/98 (bug fix) "format" now correctly handles multibyte characters +in %s format strings. (stanton) + +11/10/98 (new feature) "regexp" now accepts three new switches +("-line", "-lineanchor", and "-linestop") that control how regular +expressions treat line breaks. See the regexp manual entry for more +details. (stanton) + +11/17/98 (bug fix) "scan" now correctly handles Unicode +characters. (stanton) + +11/17/98 (new feature) "scan" now supports XPG3 position specifiers +and the "%n" conversion character. See the "scan" manual entry for +more details. (stanton) + +11/17/98 (bug fix) The Tcl memory allocator now returns 8-byte aligned +chunks of memory which improves performance on Windows and avoids +crashes on other platforms. [Bug: 834] (stanton) + +11/23/98 (bug fix) Applied various regular expression performance bug +fixes supplied by Henry Spencer. (stanton) + +11/30/98 (bug fix) Fixed various thread related race conditions. [Bug: +880 & 607] (stanton) + +11/30/98 (bug fix) Fixed a number of memory overflow and leak +bugs. [Bug: 584] (stanton) + +12/1/98 (new feaure) Added support for Korean encodings. (stanton) + +12/1/98 (feature change) Changed the Tcl_EvalObjv interface to remove +the string and length arguments. +*** POTENTIAL INCOMPATIBILITY with previous alpha releases *** + +12/2/98 (bug fix) Fixed various bugs related to line feed +translation. [Bug: 887] (stanton) + +12/4/98 (new feature) Added a message catalog facility to help with +localizing Tcl scripts. Thanks to Mark Harrison for contributing the +initial implementation of the "msgcat" package. (stanton) + +12/7/98 (bug fix) The memory allocator was failing to update the +block list for large memory blocks that were reallocated into a +different address. [Bug: 933] (stanton) + +----------------- Released 8.1b1, Dec 10 1998 ----------------------- + +12/22/98 (performance improvement) Improved the -command option of the +lsort command to better use the object system for improved +performance (about 5x speed up). Thanks to Syd Polk for suppling the +patch. [RFE: 726] (rjohnson) + +2/10/99 (bug fix) Restored the Tcl_ObjSetVar2/Tcl_ObjGetVar2 +interfaces from 8.0 and renamed the Tcl_GetObjVar2/Tcl_SetObjVar2 +interfaces to Tcl_GetVar2Ex and Tcl_SetVar2Ex. This should provide +better compatibility with 8.0. (stanton) +*** POTENTIAL INCOMPATIBILITY with previous alpha/beta releases *** + +2/10/99 (bug fix) Made the eval interfaces compatible with 8.0 by +renaming Tcl_EvalObj to Tcl_EvalObjEx, renaming Tcl_Eval2 to +Tcl_EvalEx and restoring Tcl_EvalObj and Tcl_GlobalEvalObj interfaces +so they match Tcl 8.0. (stanton) +*** POTENTIAL INCOMPATIBILITY with previous alpha/beta releases *** + +2/25/99 (bug fix/new feature) On Windows, the channel drivers for +consoles and serial ports now completely support file events. (redman) + +3/5/99 (bug fix) Integrated patches to fix various configure problems +that affected HP-UX-11, 64-bit IRIX, Linux, and Solaris. (stanton) + +3/9/99 (bug fix) Integrated various AIX related patches to improve +support for shared libraries. (stanton) + +3/9/99 (new feature) Added tcl_platform(user) to provide a portable +way to get the name of the current user. (welch) + +3/9/99 (new feature) Integrated the stub library mechanism contributed +by Jan Nijtmans, Paul Duffin, and Jean-Claude Wippler. This feature +should make it possible to write extensions that support multiple +versions of Tcl simultaneously. It also makes it possible to +dynamically load extensions into statically linked interpreters. This +patch includes the following changes: + - Added a Tcl_InitStubs() interface + - Added Tcl_PkgProvideEx, Tcl_PkgRequireEx, Tcl_PkgPresentEx, + and Tcl_PkgPresent. + - Added va_list versions of all VARARGS functions so they can be + invoked from wrapper functions. +See the manual for more information. (stanton) + + +3/10/99 (feature change) Replaced Tcl_AlertNotifier with +Tcl_ThreadAlert since the Tcl_AlertNotifier function relied on passing +internal data structures. (stanton) +*** POTENTIAL INCOMPATIBILITY with previous alpha/beta releases *** + +3/10/99 (new feature) Added a Tcl_GetVersion API to make it easier to +check the Tcl version and patch level from C. (redman) + +3/14/99 (feature change) Tried to unify the TclpInitLibrary path +routines to look in similar places from Windows to UNIX. The new +library search path is: TCL_LIBRARY, TCL_LIBRARY/../tcl8.1, relative +to DLL (Windows Only) relative to installed executable, relative to +develop executable, and relative to compiled-in in location (UNIX +Only.) This fix included: + - Defining a TclpFindExecutable + - Moving Tcl_FindExecutable to a common area in tclEncoding.c + - Modifying the TclpInitLibraryPath routines. +(surles) + +3/14/99 (feature change) Added hooks for TclPro Wrapper to initialize +the location of the encoding files and libraries. This fix included: + - Adding the TclSetPerInitScript routine. + - Modifying the Tcl_Init routines to evaluate the non-NULL + pre-init script. + - Adding the Tcl_SetdefaultEncodingDir and Tcl_GetDefaultEncodingDir + routines. + - Modifying the TclpInitLibrary routines to append the default + encoding dir. +(surles) + +3/14/99 (feature change) Test suite now uses "test" namespace to +define the test procedure and other auxiliary procedures as well as +global variables. + - Global array testConfige is now called ::test::testConfig. + - Global variable VERBOSE is now called ::test::verbose, and + ::test::verbose no longer works with numerical values. We've + switched to a bitwise character string. You can set + ::test::verbose by using the -verbose option on the Tcl command + line. + - Global variable TESTS is now called ::test::matchingTests, and + can be set on the Tcl command line via the -match option. + - There is now a ::test::skipTests variable (works similarly to + ::test::matchTests) that can be set on the Tcl command line via + the -match option. + - The test suite can now be run in any working directory. When + you run "make test", the working directory is nolonger switched + to ../tests. +(hirschl) +*** POTENTIAL INCOMPATIBILITY *** + +--------------- Released 8.1b2, March 16, 1999 ---------------------- + +3/18/99 (bug fix) Fixed missing/incorrect characters in shift-jis table +(stanton) + +3/18/99 (feature change) The glob command ignores the +FS_CASE_IS_PRESERVED bit on file systesm and always returns +exactly what it gets from the system. (stanton) +*** POTENTIAL INCOMPATIBILITY *** + +3/19/99 (new feature) Added support for --enable-64bit. For now, +this is only supported on Solaris 7 64bit (SunOS 5.7) using the Sun +compiler. (redman) + +3/23/99 (bug fix) Fixed fileevents and gets on Windows consoles and +serial devices so that non-blocking channels do not block on partial +input lines. (redman) + +3/23/99 (bug fix) Added a new Tcl_ServiceModeHook interface. +This is used on Windows to avoid the various problems that people +have been seeing where the system hangs when tclsh is running +outside of the event loop. As part of this, renamed +TclpAlertNotifier back to Tcl_AlertNotifier since it is public. +(stanton) + +3/23/99 (feature change) Test suite now uses "tcltest" namespace to +define the test procedure and other auxiliary procedures as well as +global variables. The previously chosen "test" namespace was thought +to be too generic and likely to create conflits. +(hirschl) +*** POTENTIAL INCOMPATIBILITY *** + +3/24/99 (bug fix) Make sockets thread safe on Windows. +(redman) + +3/24/99 (bug fix) Fix cases where expr would incorrect return +a floating point value instead of an integer. (stanton) + +3/25/99 (bug fix) Added ASCII to big5 and gb2312 encodings. +(stanton) + +3/25/99 (feature change) Changed so aliases are invoked at current +scope in the target interpreter instead of at the global scope. This +was an incompatibility introduced in 8.1 that is being removed. +(stanton) +*** POTENTIAL INCOMPATIBILITY with previous beta releases *** + +3/26/99 (feature change) --enable-shared is now the default and build +Tcl as a shared library; specify --disable-shared to build a static Tcl +library and shell. +*** POTENTIAL INCOMPATIBILITY *** + +3/29/99 (bug fix) Removed the stub functions and changed the stub +macros to just use the name without params. Pass &tclStubs into the +interp (don't use tclStubsPtr because of collisions with the stubs on +Solaris). (redman) + +3/30/99 (bug fix) Loadable modules are now unloaded at the last +possible moment during Tcl_Finalize to fix various exit-time crashes. +(welch) + +3/30/99 (bug fix) Tcl no longer calls setlocale(). It looks at +env(LANG) and env(LC_TYPE) instead. (stanton) + +4/1/99 (bug fix) Fixed the Ultrix multiple symbol definition problem. +Now, even Tcl includes a copy of the Tcl stub library. (redman) + +4/1/99 (bug fix) Internationalized the registry package. + +4/1/99 (bug fix) Changed the implemenation of Tcl_ConditionWait and +Tcl_ConditionNotify on Windows. The new algorithm eliminates a race +condition and was suggested by Jim Davidson. (welch) + +4/2/99 (new apis) Made various Unicode utility functions public. +Tcl_UtfToUniCharDString, Tcl_UniCharToUtfDString, Tcl_UniCharLen, +Tcl_UniCharNcmp, Tcl_UniCharIsAlnum, Tcl_UniCharIsAlpha, +Tcl_UniCharIsDigit, Tcl_UniCharIsLower, Tcl_UniCharIsSpace, +Tcl_UniCharIsUpper, Tcl_UniCharIsWordChar, Tcl_WinUtfToTChar, +Tcl_WinTCharToUtf (stanton) + +4/2/99 (feature change) Add new DDE package and removed the Tk +send command from the Windows version. Changed DDE-based send +code into "dde eval" command. The DDE package can be loaded +into tclsh, not just wish. Windows only. (redman) + +4/5/99 (bug fix) Changed safe-tcl so that the encoding command +is an alias that masks out the "encoding system" subcommand. +(redman) + +4/5/99 (bug fix) Configure patches to improve support for +OS/390 and BSD/OS 4.*. (stanton) + +4/5/99 (bug fix) Fixed crash in the clock command that occurred +with negative time values in timezones east of GMT. (stanton) + +4/6/99 (bug fix) Moved the "array set" C level code into a common +routine (TclArraySet). The TclSetupEnv routine now uses this API to +create an env array w/ no elements. This fixes the bug caused when +every environ varaible is removed, and the Tcl env variable is +synched. If no environ vars existed, the Tcl env var would never be +created. (surles) + +4/6/99 (bug fix) Made the Env module I18N compliant. (surles) + +4/6/99 (bug fix) Changed the FindVariable routine to TclpFindVariable, +that now does a case insensitive string comparison on Windows, and not +on UNIX. (surles) + +--------------- Released 8.1b3, April 6, 1999 ---------------------- + +4/9/99 (bug fix) Fixed notifier deadlock situation when the pipe used +to talk back notifier thread is filled with data. Found as a result of the +focus.test for Tk hanging. (redman) + +4/13/99 (bug fix) Fixed bug where socket -async combined with +fileevent for writing did not work under Windows NT. (redman) + +4/13/99 (encoding fix) Restored the double byte definition of GB2312 +and added the EUC-CN encoding. EUC-CN is a variant of GB2312 that +shifts the characters into bytes with the high bit set and includes +ASCII as a subset. (stanton) + +4/27/99 (bug fix) Added 'extern "C" {}' block around the stub table +pointer declaration so the stub library can be used from C++. (stanton) + +--------------- Released 8.1 final, April 29, 1999 ---------------------- + +4/22/99 (bug fix) Changed Windows NT socket implementation to avoid +creating a communication window. This avoids the problem where the +system hangs waiting for tclsh to respond to a system-wide synchronous +broadcast (e.g. if you change system colors). (redman) + +4/22/99 (bug fix) Added call to TclWinInit from TclpInitPlatform when +building a static library since DllMain will not be invoked. This +could break old code that explicitly called TclWinInit, but should be +simpler in the long run. (stanton) +*** POTENTIAL INCOMPATIBILITY *** + +4/23/99 (bug fix) Added support for the koi8-r Cyrillic +encoding. [Bug: 1771] (stanton) + +4/28/99 (bug fix) Changed internal Tcl_Obj usage to avoid freeing the +internal representation after the string representation has been +freed. This makes it easier to debug extensions. (stanton) + +4/30/99 (bug fix) Fixed a memory leak in CommandComplete. (stanton) + +5/3/99 (bug fix) Fixed a bug where the Tcl_ObjType was not being set +in a duplicated Tcl_Obj. [Bug: 1975, 2047] (stanton) + +5/3/99 (bug fix) Changed Tcl_ParseCommand to avoid modifying eval'ed +strings that are already null terminated. [Bug: 1793] (stanton) + +5/3/99 (new feature) Applied Jeff Hobbs's string patch which includes +the following changes: + - added new subcommands: equal, repeat, map, is, replace + - added -length option to "string compare|equal" + - added -nocase option to "string compare|equal|match" + - string and list indices can be an integer or end?-integer?. + - added optional first and last index args to string toupper, et al. +See the string.n manual entry for more details about the new string +features. [Bug: 1845] (stanton) + +5/6/99 (new feature) Added Tcl_UtfNcmp and Tcl_UtfNcasecmp to make Utf +string comparision easier. (stanton) + +5/7/99 (bug fix) Improved OS/390 support. [Bug: 1976, 1997] (stanton) + +5/12/99 (bug fix) Changed Windows initialization code to avoid using +GetUserName system call in favor of the env(USERNAME) variable. This +provides a significant startup speed improvement. (stanton) + +5/12/99 (bug fix) Replaced the per-interpreter regexp cache with a +per-thread cache. Changed the Regexp object to take advantage of this +extra cache. Added a reference count to the TclRegexp type so regexps +can be shared by multiple objects. Removed the per-interp regexp cache +from the interpreter. Now regexps can be used with no need for an +interpreter. This set of changes should provide significant speed +improvements for many Tcl scripts. [Bug: 1063] (stanton) + +5/14/99 (bug fix) Durining initialization on Unix, Tcl now extracts the +encoding subfield from the LANG/LC_ALL environment variables in cases +where the locale is not found in the built-in locale table. It also +attempts to initialize the locale subsystem so X11 is happy. [Bug: 1989] +(stanton) + +5/14/99 (bug fix) Applied the patch to fix 100-year and 400-year +boundaries in leap year code, from Isaac Hollander. [Bug: 2066] (redman) + +5/14/99 (bug fix) Fixed a crash caused by a failure to reset the result +before evaluating the test expression in an uncompiled for +statement. (stanton) + +5/18/99 (bug fix) Modified initialization code on Windows to avoid +inherenting closed or invalid channels. If the standard input is +anything other than a console, file, serial port, or pipe, then we fall +back to the standard Tk window console. (stanton) + +5/19/99 (bug fix) Added an extern "C" block around the entire tcl.h +header file to avoid C++ linkage issues. (redman) + +5/19/99 (new feature) Applied Jeff Hobb's patch to add +Tcl_StringCaseMatch to support case insensitive glob style matching and +Tcl_UniCharIs* character classification functions. (stanton) + +5/20/99 (bug fix) Added the directory containing the executuble and the +../lib directory relative to that to the auto_path variable. (redman) + +--------------- Released 8.1.1, May 25, 1999 ---------------------- + +5/21/99 (bug fix) Fixed launching command.com on Win95/98, no longer +hangs. [Bug: 2105] (redman) + +5/28/99 (bug fix) Fixed bug where dde calls were being passed an +invalid dde handle. [Bug: 2124] (stanton) + +6/1/99 (bug fix) Small configure.in patches. [Bug: 2121] (stanton) + +6/1/99 (bug fix) Applied latest regular expression patches to fix an +infinite loop bug and add support for testing whether a string could +match with additional input. [Bug: 2117] (stanton) + +6/2/99 (bug fix) Fixed incorrect computation of relative ordering in +Utf case-insensitive comparison. [Bug: 2135] (stanton) + +6/3/99 (bug fix) Fxied bug where string equal/compare -nocase +reported wrong result on null strings. [Bug: 2138] (stanton) + +6/4/99 (new feature) Windows build now uses Cygwin tools plus GNU +make and autoconf to build static/dynamic and debug/nodebug. (stanton) + +6/7/99 (new feature) Optimized string index, length, range, and +append commands. Added a new Unicode object type. (hershey) + +6/8/99 (bug fix) Rolled back Windows socket driver to 8.1.0 +version. (stanton) + +6/9/99 (new feature) Added Tcl_RegExpMatchObj and Tcl_RegExpGetInfo +to public Tcl API, these functions are needed by Expect. Changed +tools/genStubs.tcl to always write output in LF mode. (stanton) + +6/14/99 (new feature) Merged string and Unicode object types. Added +new public Tcl API functions: Tcl_NewUnicodeObj, Tcl_SetUnicodeObj, +Tcl_GetUnicode, Tcl_GetUniChar, Tcl_GetCharLength, Tcl_GetRange, +Tcl_AppendUnicodeToObj. (hershey) + +6/16/99 (new feature) Changed to conform to TEA specification, added +tcl.m4 and aclocal.m4 macro libraries for configure. (wart) + +6/17/99 (new feature) Added new regexp interfaces: -expanded, -line, +-linestop, and -lineanchor switches. Renamed Tcl_RegExpMatchObj to +Tcl_RegExpExecObj and added new Tcl_RegExpMatchObj that is equivalent +to Tcl_RegExpMatch. Added public macros for regexp flags. Added +REG_BOSONLY flag to allow Expect to iterate through a string and only +find matches that start at the current position within the +string. (stanton) + +6/21/99 (bug fix) Fixed memory leak in TclpThreadCreate where thread +attributes were not being released. [Bug: 2254] (stanton) + +6/23/99 (new feature) Updated Unicode character tables to reflect +Unicode 2.1 data. (stanton) + +6/25/99 (new feature) Fixed bugs in non-greedy quantifiers for regular +expression code. (stanton) + +6/25/99 (new feature) Added initial implementation of new Tcl test +harness package. Modified test files to use new tcltest package. +(jenn) + +6/26/99 (new feature) Applied patch from Peter Hardie to add poke +command to dde and changed the dde package version number to +1.1. (redman) + +6/28/99 (bug fix) Applied patch from Peter Hardie to fix problem in +Tcl_GetIndexFromObj() when the key being passed is the empty string. +[Bug: 1738] (redman) + +6/29/99 (new feature) Added options to tcltest package: -preservecore, +-limitconstraints, -help, -file, -notfile, and flags. (jenn) + +7/3/99 (new feature) Changed parsing of variable names to allow empty +array names. Now "$(foo)" is a variable reference. Previously you +had to use something line $::(foo), which is slower. This change was +requested by Jean-Luc Fontaine for his STOOOP package. (welch) + +7/3/99 (new feature) Added Tcl_SetNotifier (public API) and +associated hook points in the notifiers to be able to replace the +notifier calls at runtime. The Xt notifier and test program use this +hook. (welch) + +7/3/99 (new feature) Added a new variant of the "Trf core patch" from +Andreas Kupries that adds new C APIs Tcl_StackChannel, +Tcl_UnstackChannel, and Tcl_GetStackedChannel. This allows the Trf +extension to work without applying patches to the Tcl core. (welch) + +7/6/99 (new feature) Added -timeout option to http.tcl to handle +timeouts that occur during connection attempts to hosts that are +down. (welch) + +7/6/99 (bug fix) Applied new implementation of the Windows serial +port driver from Rolf Schroedter that fixes reading only one byte from +the port at a time. Uses polling every 10ms to implement +fileevents. [Bug: 1980 2217] (redman) + +7/8/99 (bug fix) Applied fix for bug in DFA state caching under +lookahead conditions (regular expressions). [Bug: 2318] (stanton) + +7/8/99 (bug fix) Fixed bug in string range bounds checking +code. (stanton) + +--------------- Released 8.2b1, July 14, 1999 ---------------------- + +7/16/99 (bug fix) Added Tcl_SetNotifier to stub table. [Bug: 2364] +Added check for Alpha/Linux to correct the IEEE floating point flag, +patch from Don Porter. (redman) + +7/20/99 (bug fix) Merged 8.0.5 code to handle tcl_library properly, +also fixed a bug that caused TCL_LIBRARY to be ignored. (hershey) + +7/21/99 (bug fix) Implemented modified socket driver for Windows that +uses a thread to manage the socket event window. Code works the same +on all supported versions of Windows and was based on original 8.1.0 +code. [Bug: 2178 2256 2259 2329 2323 2355] (redman) + +7/21/99 (new feature) Applied patch from Rolf Schroedter to add +-pollinterval option to fconfigure for Windows serial ports. Allows +the maxblocktime to be modified to control how often serial ports are +checked for fileevents. Also added documentation for \\.\comX +notation for opening serial ports on Windows. (redman) + +7/21/99 (bug fix) Changed APIs in stub tables to use "unsigned long" +instead of the platform-specific "size_t", primarily after SunOS 4 +users could no longer compile. (redman) + +7/22/99 (bug fix) Fixed crashing during "array set a(b) {}". +[Bug: 2427] (redman) + +7/22/99 (bug fix) The install-sh script must be given execute +permissions prior to running. [Bug: 2413] (redman) + +7/22/99 (bug fix) Applied patch from Ulrich Ring to remove ANSI-style +prototypes in the code. [Bug: 2391] (redman) + +7/22/99 (bug fix) Added #if blocks around #includes of sys/*.h header +files, to allow an extension author on Windows to use the MetroWerks +compiler. [Bug: 2385] (redman) + +7/22/99 (bug fix) Fixed running the safe.test test suite, one change +to the Windows Makefile.in to fix paths and another in safe.test to +check for the tcl_platform(threaded) variable properly. (redman) + +7/22/99 (bug fix) Fixed hanging in new Win32 socket driver with +threads enabled. (redman) + +7/26/99 (bug fix) Fixed terminating of helper threads by holding any +mutexes from the primary thread while waiting for the helper thread to +terminate. Fixes dual-CPU WinNT hangs, only one rare sporadic hang +that still exists with dual-CPU WinNT. Also fixed test cases so that +they would not depend as much on timing for dual-CPU WinNT. (redman) + +7/27/99 (bug fix) Some test suite cleanup. (jenn) + +7/29/99 (bug fix) Applied patch to fix typo in .SH NAME line in +doc/Encoding.n [Bug: 2451]. Applied patch to avoid linking pack.n to +pack-old.n [Bug: 2469]. Patches from Don Porter. (redman) + +7/29/99 (bug fix) Allow tcl to open CON and NUL, even for redirection +of std channels. [Bug: 2393 2392 2209 2458] (redman) + +7/30/99 (bug fix) Applied fixed Trf patch from Andreas Kupries. +[Bug: 2386] (hobbs) + +7/30/99 (bug fix) Fixed bug in info complete. [Bug: 2383 2466] (hobbs) + +7/30/99 (bug fix) Applied patch to fix threading on Irix 6.5, patch +provided by James Dennett. [Bug: 2450] (redman) + +7/30/99 (bug fix) Fixed launching of 16bit applications on Win9x from +wish. The command line was being primed with tclpip82.dll, but it was +ignored later. + +7/30/99 (bug fix) Added functions to stub table, patch provided by Jan +Nijtmans. [Bug: 2445] (hobbs) + +8/1/99 (bug fix) Changed Windows socket driver to terminate threads +by sending a message to the window rather than calling +TerminateThread(), which seems to leak about 4k from the helper +thread's stack space. (redman) + +--------------- Released 8.2b2, August 5, 1999 ---------------------- + +8/4/99 (bug fix) Applied patches supplied by Henry Spencer to greatly +enhance performance of certain classes of regular expressions. +[Bug: 2440 2447] (stanton) + +8/5/99 (doc change) Made it clear that tcl_pkgPath was not set for +Windows. [Bug: 2455] (hobbs) + +8/5/99 (bug fix) Fixed reference to bytes that might not be null +terminated in tclLiteral.c. [Bug: 2496] (hobbs) + +8/5/99 (bug fix) Fixed typo in http.tcl. [Bug: 2502] (hobbs) + +8/9/99 (bug fix) Fixed test suite to handle larger integers +(64bit). Patch from Don Porter. (hobbs) + +8/9/99 (documentation fix) Clarified Tcl_DecrRefCount docs +[Bug: 1952]. Clarified array pattern docs [Bug: 1330]. Fixed clock docs +[Bug: 693]. Fixed formatting errors [Bug: 2188 2189]. Fixed doc error +in tclvars.n [Bug: 2042]. (hobbs) + +8/9/99 (bug fix) Fixed path handling in auto_execok [Bug: 1276] (hobbs) + +8/9/99 (internal api change) Removed the TclpMutexLock and TclpMutexUnlock +APIs and added a new exported api, Tcl_GetAllocMutex. These APIs are all for +the mutex used in the simple memory allocators. By making this change +we are able to substitute different implementations of the thread-related +APIs without having to recompile the Tcl core. (welch) + +8/9/99 (new C API) Tcl_GetChannelNames returns a list of open channel +names in the interpreter result. Still no Tcl-level version of this, +but server-like applications can use this to clean up files without +deleting interpreters. (welch) + +8/9/99 (bug fix) Traces were not firing on "info exists", which used to +happen in Tcl 7.6 and earlier. An "info exists" now fires a read trace, +if defined. This makes it possible to fully implement variables that +are defined via traces. (welch) + +8/10/99 (bug fix) Fixed Brent's changes so that they work on +Windows. (redman) + +--------------- Released 8.2b3, August 11, 1999 ---------------------- + +8/12/99 (Mac) Rearrange projects in tclMacProjects.sea.hqx so that the +build directory is separate from the sources. (Jim Ingham) + +8/12/99 (bug fix) Fixed bug in Tcl_EvalEx where the termOffset was not +being updated in cases where the evaluation returned a non TCL_OK +error code. [Bug: 2535] (stanton) + +--------------- Released 8.2.0, August 17, 1999 ---------------------- + +9/21/99 (config fixes) fixed several AIX configuration issues. gcc and +threading may still cause problems on AIX. (hobbs) + +9/21/99 (bug fix) fixed expr double-eval problem. [Bug: 732] (hobbs) + +9/21/99 (bug fix) fixed static buffer overflow problem. [Bug: 2483] (hobbs) + +9/21/99 (bug fix) fixed end-int linsert interpretation. [Bug: 2693] (hobbs) + +9/21/99 (bug fix) fixed bug when setting array in non-existent +namespace. [Bug: 2613] (hobbs) + +--- Released 8.2.1, October 04, 1999 --- See ChangeLog for details --- + +10/30/99 (feature enhancement) new regexp engine from Henry Spencer +was patched in - should greatly reduce stack space usage. (spencer) + +10/30/99 (bug fix) fixed Purify reported memory leaks in findexecutable +test command, TclpCreateProcess on Unix, in handling of C environ array, +and in testthread code. No more known (reported) mem leaks for Tcl +built using gcc on Solaris 2.5.1. Also none reported for Tcl on NT +(using Purify 6.0). (hobbs) + +10/30/99 (bug fix) fixed improper bytecode handling of +'eval {set array($unknownvar) 5}' (also for incr) (hobbs) + +10/30/99 (bug fix) fixed event/io threading problems by making +triggerPipe non-blocking (nick kisserbeth) + +10/30/99 (bug fix) fixed Tcl_AppendStringsToObjVA and Tcl_AppendResultVA +to only iterates once over the va_list (avoiding non-portable memcpy). +(joe english, hobbs) + +10/30/99 (bug fix) removed savedChar trick in tclCompile.c that appeared +to be causing a segv when the literal table was released. +[Bug: 2459, 2515] (David Whitehouse) + +10/30/99 (bug fix) fixed [string index] to return ByteArrayObj +when indexing into one (test case string-5.16) [Bug: 2871] (hobbs) + +10/30/99 (bug fix) fixes for mac UTF filename handling (ingham) + +--- Released 8.2.2, November 04, 1999 --- See ChangeLog for details --- + +11/19/99 (feature enhancement) bug fixes for http package as well as +patch required by TLS (SSL) extension that adds http::(un)register +and -type to http::geturl. Up'd http pkg version to 2.2. + +11/19/99 (bug fix) removed extra decr of numLevels in Tcl_EvalObjEx +that could cause seg fault (mjansen@wendt.de) + +11/19/99 (bug fixes) numerous minor big fixes, including correcting the +installation of the koi8-r encoding and tcltest1.0 on Windows. + +11/30/99 (bug fix) fixes scan where %[..] didn't match anything + +11/30/99 (bug fix) fixed setting of isNonBlocking flag in PipeBlockModeProc +so you can now close a non-blocking channel without waiting. + +11/30/99 (bug work-around) prevented the unloading of DLLs for Unix in +TclFinalizeLoad. This stops the seg fault on exit that some users would +see (ie with oratcl) when using DLLs that do nasty things like register +atexit handlers. + +12/07/99 (bug fix) fixes for 'expr + {[incr]}' and 'expr + {[error]}' +cases (different causes). + +--- Released 8.2.3, December 16, 1999 --- See ChangeLog for details --- + +1999-09-14 (feature enhancement) added -start switch to regexp and regsub. + +1999-09-15 (feature enhancement) add 'array unset' command. + +1999-09-15 (feature enhancement) rewrote runtime libraries to use new +string functions + +1999-08-18 (feature enhancement) added 'file channels' command, along with +Tcl_GetChannelNames(Ex) public C APIs. + +1999-10-19 (feature enhancement) enhanced tcltest package + +1999-09-16 (feature enhancement) added -milliseconds switch to 'clock clicks' + +1999-10-28 (feature enhancement) added support for inline 'scan' + +1999-10-28 (feature enhancement) added support for touch functionality by +extendeding 'file atime' and 'file mtime' to take an optional time argument + +1999-11-24 (feature enhancement) added 'fconfigure $sock -lasterror' +command to Windows to query the last error received on a serial socket. + +1999-11-30 (bug fix) fixed handling of %Z on NT for timezones that don't +have DST + +1999-12-03 (feature enhancement) improved error message in bad octal cases +and improper use of comments. (hobbs) + +1999-12-07 (bug fix) fixed Tcl_ScanCountedElement to not step +beyond the end of the counted string + +1999-12-09 (feature enhancement) removed all references to 16 bit +compatibility code for Windows (hobbs) + +1999-12-10 (bug fix) removed check for vfork - Tcl now uses only fork in +exec. (hobbs) + +1999-12-10 (optimization) changed Tcl_ConcatObj to return a list +object when it receives all pure list objects as input (used by 'concat'), +added optimizations in Tcl_EvalObjEx for pure list case, and optimized +INST_TRY_CVT_TO_NUMERIC in TclExecuteByteCode for boolean objects. +(oakley, hobbs) + +1999-12-12 (feature enhancement) enhanced glob command with -type, -path, +-directory and -join switches. (darley, hobbs) + +1999-12-21 (bug fix) changed CreateThread to _beginthreadex and +ExitThread to _endthreadex to prevent 4K mem leak (gravereaux) + +1999-12-21 (bug fix) fixed applescript for I18N + +1999-12-21 (feature enhancement) added -unique option to lsort (hobbs) + +1999-12-21 (bug fix) changed thread ids to longs (for 64bit systems) + +--- Released 8.3b1, December 22, 1999 --- See ChangeLog for details --- + +2000-01-10 (feature enhancement) clock scan now supports the common +ISO 8601 date/time formats. See docs for details. (melski) + +2000-01-10 (bug fix) prevented \ooo substitution from accepting +non-octal digits [Bug: 3975] (hobbs) + +2000-01-11 (bug fix) fixed improper handling of DST by clock when +using relative times (like "1 month" or "tomorrow"). (melski) + +2000-01-12 (bug fix) improved build support for Tru64 v5, NetBSD +and Reliant Unix (hobbs) + +2000-01-12 (bug fix) made imported commands also import their +compile procedure (duffin) + +2000-01-12 (bug fix) fixed 'info procs ::namesp::*' behavior to return +procs in a namespace (dejong) + +2000-01-12 (feature enhancement) added support for setting permissions +symbolicly (like chmod) in [file attributes $file -permissions ...] (schoebel) + +2000-01-13 (bug fix) fixed lsort -dictionary problem when sorting +characters between 'Z' and 'a' (flawed upper/lower comparison logic) (melski) + +--- Released 8.3b2, January 13, 2000 --- See ChangeLog for details --- + +2000-01-14 (feature enhancement) clock format %Q added, clock scan updated + +2000-01-20 (bug fix) corrected complex array elem compiling (Spjuth) + +2000-01-20 (bug fix) made [info body] always return a string type arg, +to prevent possible misuse of bytecodes in the wrong context (hobbs) + +2000-01-20 (bug fixes) several fixes to variable handling to prevent +possible crashes, and further definition of correct behavior (melski) + +2000-01-25 (bug fixes) improved QNX, Ultrix and OSF1 (Tru64) config and +compatibility (edge, furukawa) + +2000-01-25 (bug fix) fixed mem leak when calling lsort with a bad -command +argument (hobbs) + +2000-01-27 (feature enhancement) package mechanism overhaul: changed +behavior of pkg_mkIndex to do -direct by default, added -lazy option. +Fixed pkg_mkIndex to handle odd proc names and auto_mkIndex to use platform +independent file paths. Other fixes for odd package quirks. Added +::pkg namespace and ::pkg::create helper function. (melski) + +2000-02-01 (bug fix) fixed problem where http POST would send one extra +newline (vasiljevic) + +2000-02-02 (feature enhancement) added docs for new regexp -inline and +-all switches. (hobbs) + +2000-02-08 (bug fix) corrected handling of "next monthname" in clock scan +(melski) + +2000-02-09 (bug fix) restored Mac source to build readiness and prevented +mac panic from an error when closing an async socket (steffen, ingham) + +2000-02-10 (feature enhancement) improved error reporting for failed +loads on Windows (dejong, hobbs) + +--- Released 8.3.0, February 10, 2000 --- See ChangeLog for details --- + +2000-03 (bug fixes, feature enhancement) overhaul of http package for +proper handling of async callbacks (new options), version is now at 2.3 +(tamhankar, welch) + +2000-03 (speed improvements) speedup in Windows filename handling (newman) +and ==/!= empty string in exprs. (hobbs) + +2000-03-27 (bug fix) added uniq'ing test to namespace export list to +prevent unnecessary mem growth (hobbs) + +2000-03-29 (bug fix) fixed mem leak when repeatedly sourcing the same +bytecompiled (tbc) code repeatedly across different interpreters (hobbs) + +2000-03-29 (config enhancement) improved build support for gcc/mingw on +Windows (nijtmans, hobbs) and added RPM target (melski) + +2000-03-31 (bug fix) corrected data encoding problem when using +"exec << $data" construct (melski) + +2000-04 (feature enhancement) overhaul of threading mechanism to better +support tcl level thread command (new APIs Tcl_ConditionFinalize, +Tcl_MutexFinalize, Tcl_CreateThread, etc, all docs in Thread.3). +(kupries, graveraux) +This enables the tcl level thread extension. (welch) + +2000-04-10 (bug fix) fixed infinite loop case in regexp -all (melski) + +2000-04-13 (config enhancement) added support for --enable-64bit-vis +Sparc target. (hobbs) + +2000-04-18 (bug fix) moved tclLibraryPath to thread-local storage to fix +possible race condition on MP machines (hobbs) + +2000-04-18 (config enhancement) added MacOS X build target and +tclLoadDyld.c dl type. (sanchez) + +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 --- diff --git a/tcl/compat/README b/tcl/compat/README index 5bbf04179aa..28d50a36541 100644 --- a/tcl/compat/README +++ b/tcl/compat/README @@ -6,3 +6,4 @@ they are known to be incorrect. When the whole world becomes POSIX- compliant this directory should be unnecessary. RCS: @(#) $Id$ + diff --git a/tcl/compat/getcwd.c b/tcl/compat/getcwd.c new file mode 100644 index 00000000000..e4340c155e9 --- /dev/null +++ b/tcl/compat/getcwd.c @@ -0,0 +1,47 @@ +/* + * getcwd.c -- + * + * This file provides an implementation of the getcwd procedure + * that uses getwd, for systems with getwd but without getcwd. + * + * Copyright (c) 1993 The Regents of the University of California. + * Copyright (c) 1994 Sun Microsystems, Inc. + * + * See the file "license.terms" for information on usage and redistribution + * of this file, and for a DISCLAIMER OF ALL WARRANTIES. + * + * SCCS: @(#) getcwd.c 1.5 96/02/15 12:08:20 + */ + +#include "tclInt.h" +#include "tclPort.h" + +extern char *getwd _ANSI_ARGS_((char *pathname)); + +char * +getcwd(buf, size) + char *buf; /* Where to put path for current directory. */ + size_t size; /* Number of bytes at buf. */ +{ + char realBuffer[MAXPATHLEN+1]; + int length; + + if (getwd(realBuffer) == NULL) { + /* + * There's not much we can do besides guess at an errno to + * use for the result (the error message in realBuffer isn't + * much use...). + */ + + errno = EACCES; + return NULL; + } + length = strlen(realBuffer); + if (length >= size) { + errno = ERANGE; + return NULL; + } + strcpy(buf, realBuffer); + return buf; +} + diff --git a/tcl/compat/stdlib.h b/tcl/compat/stdlib.h index 0dabdaf8392..45f39551de6 100644 --- a/tcl/compat/stdlib.h +++ b/tcl/compat/stdlib.h @@ -9,7 +9,7 @@ * declare all the procedures needed here (such as strtod). * * Copyright (c) 1991 The Regents of the University of California. - * Copyright (c) 1994 Sun Microsystems, Inc. + * Copyright (c) 1994-1998 Sun Microsystems, Inc. * * See the file "license.terms" for information on usage and redistribution * of this file, and for a DISCLAIMER OF ALL WARRANTIES. diff --git a/tcl/compat/strftime.c b/tcl/compat/strftime.c index 65b687b23c8..38ba41457cd 100644 --- a/tcl/compat/strftime.c +++ b/tcl/compat/strftime.c @@ -55,6 +55,7 @@ static char *rcsid = "$Id$"; #include "tclPort.h" #define TM_YEAR_BASE 1900 +#define IsLeapYear(x) ((x % 4 == 0) && (x % 100 != 0 || x % 400 == 0)) typedef struct { const char *abday[7]; @@ -105,12 +106,22 @@ static size_t _fmt _ANSI_ARGS_((const char *format, const struct tm *t)); size_t -TclStrftime(s, maxsize, format, t) +TclpStrftime(s, maxsize, format, t) char *s; size_t maxsize; const char *format; const struct tm *t; { + if (format[0] == '%' && format[1] == 'Q') { + /* Format as a stardate */ + sprintf(s, "Stardate %2d%03d.%01d", + (((t->tm_year + TM_YEAR_BASE) + 377) - 2323), + (((t->tm_yday + 1) * 1000) / + (365 + IsLeapYear((t->tm_year + TM_YEAR_BASE)))), + (((t->tm_hour * 60) + t->tm_min)/144)); + return(strlen(s)); + } + tzset(); pt = s; @@ -315,7 +326,7 @@ _fmt(format, t) continue; #ifndef MAC_TCL case 'Z': { - char *name = TclpGetTZName(); + char *name = TclpGetTZName(t->tm_isdst); if (name && !_add(name)) { return 0; } diff --git a/tcl/compat/string.h b/tcl/compat/string.h index c9894783b8d..8b998f552b0 100644 --- a/tcl/compat/string.h +++ b/tcl/compat/string.h @@ -32,8 +32,12 @@ extern char * memchr _ANSI_ARGS_((CONST VOID *s, int c, size_t n)); extern int memcmp _ANSI_ARGS_((CONST VOID *s1, CONST VOID *s2, size_t n)); extern char * memcpy _ANSI_ARGS_((VOID *t, CONST VOID *f, size_t n)); +#ifdef NO_MEMMOVE +#define memmove(d, s, n) bcopy ((s), (d), (n)) +#else extern char * memmove _ANSI_ARGS_((VOID *t, CONST VOID *f, size_t n)); +#endif extern char * memset _ANSI_ARGS_((VOID *s, int c, size_t n)); extern int strcasecmp _ANSI_ARGS_((CONST char *s1, diff --git a/tcl/compat/waitpid.c b/tcl/compat/waitpid.c index e9adb632b06..e30c8882013 100644 --- a/tcl/compat/waitpid.c +++ b/tcl/compat/waitpid.c @@ -18,6 +18,10 @@ #include "tclInt.h" #include "tclPort.h" +#ifndef pid_t +#define pid_t int +#endif + /* * A linked list of the following structures is used to keep track * of processes for which we received notification from the kernel, @@ -28,7 +32,7 @@ */ typedef struct WaitInfo { - int pid; /* Pid of process that exited. */ + pid_t pid; /* Pid of process that exited. */ WAIT_STATUS_TYPE status; /* Status returned when child exited * or suspended. */ struct WaitInfo *nextPtr; /* Next in list of exited processes. */ @@ -64,9 +68,9 @@ static WaitInfo *deadList = NULL; /* First in list of all dead # undef waitpid #endif -int +pid_t waitpid(pid, statusPtr, options) - int pid; /* The pid to wait on. Must be -1 or + pid_t pid; /* The pid to wait on. Must be -1 or * greater than zero. */ int *statusPtr; /* Where to store wait status for the * process. */ @@ -74,7 +78,7 @@ waitpid(pid, statusPtr, options) * WUNTRACED. */ { register WaitInfo *waitPtr, *prevPtr; - int result; + pid_t result; WAIT_STATUS_TYPE status; if ((pid < -1) || (pid == 0)) { diff --git a/tcl/configure b/tcl/configure index c7b3e661c15..e60aab80775 100755 --- a/tcl/configure +++ b/tcl/configure @@ -28,6 +28,7 @@ program_suffix=NONE program_transform_name=s,x,x, silent= site= +sitefile= srcdir= target=NONE verbose= @@ -142,6 +143,7 @@ Configuration: --help print this message --no-create do not create output files --quiet, --silent do not print \`checking...' messages + --site-file=FILE use FILE as the site file --version print the version of autoconf that created configure Directory and file names: --prefix=PREFIX install architecture-independent files in PREFIX @@ -312,6 +314,11 @@ EOF -site=* | --site=* | --sit=*) site="$ac_optarg" ;; + -site-file | --site-file | --site-fil | --site-fi | --site-f) + ac_prev=sitefile ;; + -site-file=* | --site-file=* | --site-fil=* | --site-fi=* | --site-f=*) + sitefile="$ac_optarg" ;; + -srcdir | --srcdir | --srcdi | --srcd | --src | --sr) ac_prev=srcdir ;; -srcdir=* | --srcdir=* | --srcdi=* | --srcd=* | --src=* | --sr=*) @@ -477,12 +484,16 @@ fi srcdir=`echo "${srcdir}" | sed 's%\([^/]\)/*$%\1%'` # Prefer explicitly selected file to automatically selected ones. -if test -z "$CONFIG_SITE"; then - if test "x$prefix" != xNONE; then - CONFIG_SITE="$prefix/share/config.site $prefix/etc/config.site" - else - CONFIG_SITE="$ac_default_prefix/share/config.site $ac_default_prefix/etc/config.site" +if test -z "$sitefile"; then + if test -z "$CONFIG_SITE"; then + if test "x$prefix" != xNONE; then + CONFIG_SITE="$prefix/share/config.site $prefix/etc/config.site" + else + CONFIG_SITE="$ac_default_prefix/share/config.site $ac_default_prefix/etc/config.site" + fi fi +else + CONFIG_SITE="$sitefile" fi for ac_site_file in $CONFIG_SITE; do if test -r "$ac_site_file"; then @@ -548,7 +559,7 @@ else { echo "configure: error: can not run $ac_config_sub" 1>&2; exit 1; } fi echo $ac_n "checking host system type""... $ac_c" 1>&6 -echo "configure:552: checking host system type" >&5 +echo "configure:563: checking host system type" >&5 host_alias=$host case "$host_alias" in @@ -570,13 +581,7 @@ echo "$ac_t""$host" 1>&6 case "${host}" in -*-*-cygwin*) - CONFIGDIR="win" - - CONFIGDIR2="cygwin" - - ;; -*-*-mingw32*) +*cygwin* | *mingw32* | *windows32*) CONFIGDIR="win" ;; @@ -606,7 +611,7 @@ ac_configure=$ac_aux_dir/configure # This should be Cygnus configure. esac echo $ac_n "checking whether ${MAKE-make} sets \${MAKE}""... $ac_c" 1>&6 -echo "configure:610: checking whether ${MAKE-make} sets \${MAKE}" >&5 +echo "configure:615: checking whether ${MAKE-make} sets \${MAKE}" >&5 set dummy ${MAKE-make}; ac_make=`echo "$2" | sed 'y%./+-%__p_%'` if eval "test \"`echo '$''{'ac_cv_prog_make_${ac_make}_set'+set}'`\" = set"; then echo $ac_n "(cached) $ac_c" 1>&6 @@ -632,7 +637,7 @@ else SET_MAKE="MAKE=${MAKE-make}" fi -subdirs="$CONFIGDIR $CONFIGDIR2" +subdirs="$CONFIGDIR" trap '' 1 2 15 cat > confcache <<\EOF @@ -784,7 +789,6 @@ s%@host_cpu@%$host_cpu%g s%@host_vendor@%$host_vendor%g s%@host_os@%$host_os%g s%@CONFIGDIR@%$CONFIGDIR%g -s%@CONFIGDIR2@%$CONFIGDIR2%g s%@SET_MAKE@%$SET_MAKE%g s%@subdirs@%$subdirs%g @@ -919,7 +923,7 @@ if test "$no_recursion" != yes; then esac done - for ac_config_dir in $CONFIGDIR $CONFIGDIR2; do + for ac_config_dir in $CONFIGDIR; do # Do not complain, so a configure script can configure whichever # parts of a large source tree are present. diff --git a/tcl/configure.in b/tcl/configure.in index 4286ff547fd..322de8e3dfd 100644 --- a/tcl/configure.in +++ b/tcl/configure.in @@ -11,13 +11,7 @@ AC_INIT(generic/tcl.h) AC_CANONICAL_HOST case "${host}" in -*-*-cygwin*) - CONFIGDIR="win" - AC_SUBST(CONFIGDIR) - CONFIGDIR2="cygwin" - AC_SUBST(CONFIGDIR2) - ;; -*-*-mingw32*) +*cygwin* | *mingw32* | *windows32*) CONFIGDIR="win" AC_SUBST(CONFIGDIR) ;; @@ -29,5 +23,5 @@ case "${host}" in esac AC_PROG_MAKE_SET -AC_CONFIG_SUBDIRS($CONFIGDIR $CONFIGDIR2) +AC_CONFIG_SUBDIRS($CONFIGDIR) AC_OUTPUT(Makefile) diff --git a/tcl/cygtcl.m4 b/tcl/cygtcl.m4 new file mode 100644 index 00000000000..b74c2be7aca --- /dev/null +++ b/tcl/cygtcl.m4 @@ -0,0 +1,310 @@ +# CYGNUS LOCAL +# +# This entire file is Cygnus local, it contains a set of cross +# platform autoconf macros to be used by Tcl extensions. + +# FIXME: There seems to be a problem with variable +# names that still need an expansion (like $foo_FILE) +# since another eval might be needed in these macros. + +#-------------------------------------------------------------------- +# TCL_TOOL_PATH +# +# Return a file path that the build system tool will understand. +# This path might be different than the path used in the +# Makefiles. +# +# Arguments: +# +# VAR +# PATH +# +# Results: +# +# +# Example: +# +# TCL_TOOL_PATH(TCL_CC_PATH, /usr/local/compiler) +# +#-------------------------------------------------------------------- + +AC_DEFUN(TCL_TOOL_PATH, [ + val=$2 + + if test "$val" = "" ; then + AC_MSG_ERROR([Empty value for variable $1]) + fi + + case "${host}" in + *windows32* | *mingw32*) + if test "${CYGPATH}" = ""; then + AC_MSG_ERROR([CYGPATH variable is not defined.]) + elif test "${CYGPATH}" = "echo"; then + # No cygpath when cross compiling + $1=$val + else + # store literal argument text in a variable + val=$val + # Convert Cygwin to Windows path (/tmp/foo -> C:\Tmp\foo) + val="`${CYGPATH} $val`" + # Convert path like C:\Tmp\foo to C:/Tmp/foo + $1="`echo $val | sed -e s#\\\\\\\\#/#g`" + fi + ;; + *) + # Default to a no-op under Unix or Cygwin gcc + $1=$val + ;; + esac +]) + +# FIXME: It would simplify things if no SUFFIX had to be passed +# into these LONGNAME macros. Using the TCL_SHARED_LIB_SUFFIX +# and TCL_UNSHARED_LIB_SUFFIX from tclConfig.sh might do the trick! + +#-------------------------------------------------------------------- +# TCL_TOOL_STATIC_LIB_LONGNAME +# +# Return static library name in the "long format" understood by +# the build tools. This might involve prepending a suffix +# and appending version information to the library name. +# +# Arguments: +# +# VAR +# LIBNAME +# SUFFIX +# +# Depends on: +# TCL_DBGX +# TCL_VENDOR_PREFIX +# +# Example: +# +# TCL_TOOL_STATIC_LIB_LONGNAME(TCL_LIB, tcl, $TCL_UNSHARED_LIB_SUFFIX) +# +# Results: +# +# TCL_LIB=libtcl83.a +# +# or +# +# TCL_LIB=tcl83.lib +# +#-------------------------------------------------------------------- + +AC_DEFUN(TCL_TOOL_STATIC_LIB_LONGNAME, [ + libname=$2 + suffix=$3 + + case "${host}" in + *windows32* | *mingw32*) + if test "$GCC" != yes; then + eval "long_libname=\"${TCL_VENDOR_PREFIX}${libname}${suffix}\"" + else + eval "long_libname=\"lib${TCL_VENDOR_PREFIX}${libname}${suffix}\"" + fi + ;; + *) + eval "long_libname=\"lib${TCL_VENDOR_PREFIX}${libname}${suffix}\"" + ;; + esac + + eval "long_libname=${long_libname}" + + # Trick to replace DBGX with TCL_DBGX + DBGX='${TCL_DBGX}' + eval "long_libname=${long_libname}" + + $1=$long_libname +]) + +#-------------------------------------------------------------------- +# TCL_TOOL_SHARED_LIB_LONGNAME +# +# Return the shared library name in the "long format" understood by +# the build tools. This might involve prepending a suffix +# and appending version information to the shared library name. +# +# Arguments: +# +# VAR +# LIBNAME +# SUFFIX +# +# Depends on: +# TCL_DBGX +# TCL_VENDOR_PREFIX +# +# Example: +# +# TCL_TOOL_SHARED_LIB_LONGNAME(TCL_SHLIB, tcl, $TCL_SHARED_LIB_SUFFIX) +# +# Results: +# The above example could result in the following. +# +# TCL_SHLIB=libtcl83.so +# +# or +# +# TCL_SHLIB=tcl83.dll +# +#-------------------------------------------------------------------- + +AC_DEFUN(TCL_TOOL_SHARED_LIB_LONGNAME, [ + libname=$2 + suffix=$3 + + case "${host}" in + *windows32* | *mingw32* | *cygwin*) + eval "long_libname=\"${TCL_VENDOR_PREFIX}${libname}${suffix}\"" + ;; + *) + eval "long_libname=\"lib${TCL_VENDOR_PREFIX}${libname}${suffix}\"" + ;; + esac + + eval "long_libname=${long_libname}" + + # Trick to replace DBGX with TCL_DBGX + DBGX='${TCL_DBGX}' + eval "long_libname=${long_libname}" + + $1=$long_libname +]) + +#-------------------------------------------------------------------- +# TCL_TOOL_LIB_SHORTNAME +# +# Return the library name in the "short format" understood by +# the build tools. This might involve prepending a suffix +# and appending version information to the library name. +# The VC++ compiler does not support short library names +# so we just use the static import lib name in that case. +# +# Arguments: +# +# VAR +# LIBNAME +# VERSION +# +# Depends on: +# TCL_LIB_VERSIONS_OK +# TCL_DBGX +# SHARED_BUILD +# +# +# Example: +# +# TCL_TOOL_LIB_SHORTNAME(TCL_LIB, tcl, 8.3) +# +# Results: +# The above example could result in the following. +# +# TCL_LIB=-ltcl83 +# +# or +# +# TCL_LIB=tcl83.lib +# +#-------------------------------------------------------------------- + +AC_DEFUN(TCL_TOOL_LIB_SHORTNAME, [ + libname=$2 + version=$3 + + if test "$TCL_LIB_SUFFIX" = "" ; then + AC_MSG_ERROR([The TCL_LIB_SUFFIX variable is not defined]) + fi + + # If the . character is not allowed in lib name, remove it from version + if test "${TCL_LIB_VERSIONS_OK}" != "ok"; then + version=`echo $version | tr -d .` + fi + + case "${host}" in + *windows32* | *mingw32*) + if test "$GCC" != yes; then + eval "short_libname=\"${TCL_VENDOR_PREFIX}${libname}${version}${TCL_LIB_SUFFIX}\"" + else + short_libname="-l${TCL_VENDOR_PREFIX}${libname}${version}${TCL_DBGX}" + fi + ;; + *) + short_libname="-l${TCL_VENDOR_PREFIX}${libname}${version}\${TCL_DBGX}" + ;; + esac + + $1=$short_libname +]) + +#-------------------------------------------------------------------- +# TCL_TOOL_LIB_SPEC +# +# Return the "lib spec format" understood by the build tools. +# +# Arguments: +# +# VAR +# DIR +# LIBARG +# +# Depends on: +# +# +# Example: +# +# TCL_TOOL_LIB_SPEC(SPEC, /usr/lib, -ltcl) +# +# Results: +# The above example could result in the following. +# +# SPEC="-L/usr/lib -ltcl83" +# +#-------------------------------------------------------------------- + +AC_DEFUN(TCL_TOOL_LIB_SPEC, [ + case "${host}" in + *windows32* | *mingw32*) + if test "$GCC" != yes; then + TCL_TOOL_PATH($1, "$2/$3") + else + TCL_TOOL_PATH(dirname, $2) + $1="-L${dirname} $3" + fi + ;; + *) + $1="-L$2 $3" + ;; + esac +]) + +#-------------------------------------------------------------------- +# TCL_TOOL_LIB_PATH +# +# Return the "lib path format" understood by the build tools. +# Typically, this is the fully qualified path name of the library. +# +# Arguments: +# +# VAR +# DIR +# LIBARG +# +# Depends on: +# +# +# Example: +# +# TCL_TOOL_LIB_PATH(TMP_PATH, /usr/lib, libtcl83.a) +# +# Results: +# The above example could result in the following. +# +# TMP_PATH="/usr/lib/libtcl83.a" +# +#-------------------------------------------------------------------- + +AC_DEFUN(TCL_TOOL_LIB_PATH, [ + TCL_TOOL_PATH($1, "$2/$3") +]) diff --git a/tcl/doc/Access.3 b/tcl/doc/Access.3 new file mode 100644 index 00000000000..ae68cb9e6a7 --- /dev/null +++ b/tcl/doc/Access.3 @@ -0,0 +1,71 @@ +'\" +'\" Copyright (c) 1998-1999 Scriptics Corportation +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id$ +'\" +.so man.macros +.TH Tcl_Access 3 8.1 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_Access, Tcl_Stat \- check file permissions and other attributes +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +int +\fBTcl_Access\fR(\fIpath\fR, \fImode\fR) +.sp +int +\fBTcl_Stat\fR(\fIpath\fR, \fIstatPtr\fR) +.SH ARGUMENTS +.AS stat *statPtr in +.AP char *path in +Native name of the file to check the attributes of. +.AP int mode in +Mask consisting of one or more of R_OK, W_OK, X_OK and F_OK. R_OK, +W_OK and X_OK request checking whether the file exists and has read, +write and execute permissions, respectively. F_OK just requests +checking for the existence of the file. +.AP stat *statPtr out +The structure that contains the result. +.BE + +.SH DESCRIPTION +.PP +There are two reasons for calling \fBTcl_Access\fR and \fBTcl_Stat\fR +rather than calling system level functions \fBaccess\fR and \fBstat\fR +directly. First, the Windows implementation of both functions fixes +some bugs in the system level calls. Second, both \fBTcl_Access\fR +and \fBTcl_Stat\fR (as well as \fBTcl_OpenFileChannelProc\fR) hook +into a linked list of functions. This allows the possibity to reroute +file access to alternative media or access methods. +.PP +\fBTcl_Access\fR checks whether the process would be allowed to read, +write or test for existence of the file (or other file system object) +whose name is pathname. If pathname is a symbolic link on Unix, +then permissions of the file referred by this symbolic link are +tested. +.PP +On success (all requested permissions granted), zero is returned. On +error (at least one bit in mode asked for a permission that is denied, +or some other error occurred), -1 is returned. +.PP +\fBTcl_Stat\fR fills the stat structure \fIstatPtr\fR with information +about the specified file. You do not need any access rights to the +file to get this information but you need search rights to all +directories named in the path leading to the file. The stat structure +includes info regarding device, inode (always 0 on Windows), +priviledge mode, nlink (always 1 on Windows), user id (always 0 on +Windows), group id (always 0 on Windows), rdev (same as device on +Windows), size, last access time, last modification time, and creation +time. +.PP +If \fIpath\fR exists, \fBTcl_Stat\fR returns 0 and the stat structure +is filled with data. Otherwise, -1 is returned, and no stat info is +given. + +.SH KEYWORDS +stat access diff --git a/tcl/doc/AddErrInfo.3 b/tcl/doc/AddErrInfo.3 index 993b5dc62a9..58635d8b25c 100644 --- a/tcl/doc/AddErrInfo.3 +++ b/tcl/doc/AddErrInfo.3 @@ -8,10 +8,10 @@ '\" RCS: @(#) $Id$ '\" .so man.macros -.TH Tcl_AddErrorInfo 3 7.5 Tcl "Tcl Library Procedures" +.TH Tcl_AddErrorInfo 3 8.0 Tcl "Tcl Library Procedures" .BS .SH NAME -Tcl_AddObjErrorInfo, Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_PosixError \- record information about errors +Tcl_AddObjErrorInfo, Tcl_AddErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_PosixError, Tcl_LogCommandInfo \- record information about errors .SH SYNOPSIS .nf \fB#include \fR @@ -24,8 +24,13 @@ Tcl_AddObjErrorInfo, Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_PosixError \- recor .sp \fBTcl_SetErrorCode\fR(\fIinterp, element, element, ... \fB(char *) NULL\fR) .sp +\fBTcl_SetErrorCodeVA\fR(\fIinterp, argList\fR) +.sp char * \fBTcl_PosixError\fR(\fIinterp\fR) +.sp +void +\fBTcl_LogCommandInfo\fR(\fIinterp, script, command, commandLength\fR) .SH ARGUMENTS .AS Tcl_Interp *message .AP Tcl_Interp *interp in @@ -47,6 +52,15 @@ This variable \fBerrorCode\fR will be set to this value. .AP char *element in String to record as one element of \fBerrorCode\fR variable. Last \fIelement\fR argument must be NULL. +.AP va_list argList in +An argument list which must have been initialised using +\fBTCL_VARARGS_START\fR, and cleared using \fBva_end\fR. +.AP char *script in +Pointer to first character in script containing command (must be <= command) +.AP char *command in +Pointer to first character in command that generated the error +.AP int commandLength in +Number of bytes in command; -1 means use all bytes up to first NULL byte .BE .SH DESCRIPTION @@ -68,8 +82,8 @@ 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_EvalObj\fR -(or \fBTcl_Eval\fR, which calls \fBTcl_EvalObj\fR) +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. @@ -79,7 +93,7 @@ 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_EvalObj\fR. +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. @@ -89,7 +103,7 @@ 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_EvalObj\fR has returned \fBTCL_ERROR\fR. +\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). @@ -118,6 +132,9 @@ The procedure \fBTcl_SetErrorCode\fR is also used to set the record instead of an object. Otherwise, it is similar to \fBTcl_SetObjErrorCode\fR in behavior. .PP +\fBTcl_SetErrorCodeVA\fR is the same as \fBTcl_SetErrorCode\fR except that +instead of taking a variable number of arguments it takes an argument list. +.PP \fBTcl_PosixError\fR sets the \fBerrorCode\fR variable after an error in a POSIX kernel call. It reads the value of the \fBerrno\fR C variable and calls @@ -136,6 +153,14 @@ It may be convenient to include this string as part of the error message returned to the application in the interpreter's result. .PP +\fBTcl_LogCommandInfo\fR is invoked after an error occurs in an +interpreter. It adds information about the command that was being +executed when the error occured to the \fBerrorInfo\fR variable, and +the line number stored internally in the interpreter is set. On the +first call to \fBTcl_LogCommandInfo\fR or \fBTcl_AddObjErrorInfo\fR +since an error occurred, the old information in \fBerrorInfo\fR is +deleted. +.PP It is important to call the procedures described here rather than setting \fBerrorInfo\fR or \fBerrorCode\fR directly with \fBTcl_ObjSetVar2\fR. diff --git a/tcl/doc/AppInit.3 b/tcl/doc/AppInit.3 index 66295a760fb..031e4df41af 100644 --- a/tcl/doc/AppInit.3 +++ b/tcl/doc/AppInit.3 @@ -51,7 +51,7 @@ Invoke a startup script to initialize the application. .LP \fBTcl_AppInit\fR returns TCL_OK or TCL_ERROR. If it returns TCL_ERROR then it must leave an error message in -\fIinterp->result\fR; otherwise the result is ignored. +for the interpreter's result; otherwise the result is ignored. .PP In addition to \fBTcl_AppInit\fR, your application should also contain a procedure \fBmain\fR that calls \fBTcl_Main\fR as follows: diff --git a/tcl/doc/AssocData.3 b/tcl/doc/AssocData.3 index 8636597f04e..9acc9eb0f86 100644 --- a/tcl/doc/AssocData.3 +++ b/tcl/doc/AssocData.3 @@ -84,6 +84,6 @@ specified key exists in the given interpreter \fBTcl_GetAssocData\fR returns \fBNULL\fR. .PP \fBTcl_DeleteAssocData\fR deletes an association with a specified key in -the given interpreter. It does not call the deletion procedure. +the given interpreter. Then it calls the deletion procedure. .SH KEYWORDS association, data, deletion procedure, interpreter, key diff --git a/tcl/doc/Async.3 b/tcl/doc/Async.3 index 0d6658677fe..702e474293e 100644 --- a/tcl/doc/Async.3 +++ b/tcl/doc/Async.3 @@ -11,7 +11,7 @@ .TH Tcl_AsyncCreate 3 7.0 Tcl "Tcl Library Procedures" .BS .SH NAME -Tcl_AsyncCreate, Tcl_AsyncMark, Tcl_AsyncInvoke, Tcl_AsyncDelete \- handle asynchronous events +Tcl_AsyncCreate, Tcl_AsyncMark, Tcl_AsyncInvoke, Tcl_AsyncDelete, Tcl_AsyncReady \- handle asynchronous events .SH SYNOPSIS .nf \fB#include \fR @@ -90,8 +90,8 @@ execution in an interpreter, then \fIinterp\fR will identify the interpreter in which the command was evaluated and \fIcode\fR will be the completion code returned by that command. -The command's result will be present in \fIinterp->result\fR. -When \fIproc\fR returns, whatever it leaves in \fIinterp->result\fR +The command's result will be present in the interpreter's result. +When \fIproc\fR returns, whatever it leaves in the interpreter's result will be returned as the result of the command and the integer value returned by \fIproc\fR will be used as the new completion code for the command. @@ -127,7 +127,7 @@ not be invoked. If multiple handlers become active at the same time, the handlers are invoked in the order they were created (oldest handler first). -The \fIcode\fR and \fIinterp->result\fR for later handlers +The \fIcode\fR and the interpreter's result for later handlers reflect the values returned by earlier handlers, so that the most recently created handler has last say about the interpreter's result and completion code. @@ -139,17 +139,17 @@ this over and over until there are no longer any ready handlers. .SH WARNING .PP It is almost always a bad idea for an asynchronous event -handler to modify \fIinterp->result\fR or return a code different +handler to modify the interpreter's result or return a code different from its \fIcode\fR argument. This sort of behavior can disrupt the execution of scripts in subtle ways and result in bugs that are extremely difficult to track down. If an asynchronous event handler needs to evaluate Tcl scripts -then it should first save \fIinterp->result\fR plus the values +then it should first save the interpreter's result plus the values of the variables \fBerrorInfo\fR and \fBerrorCode\fR (this can be done, for example, by storing them in dynamic strings). When the asynchronous handler is finished it should restore -\fIinterp->result\fR, \fBerrorInfo\fR, and \fBerrorCode\fR, +the interpreter's result, \fBerrorInfo\fR, and \fBerrorCode\fR, and return the \fIcode\fR argument. .SH KEYWORDS diff --git a/tcl/doc/BackgdErr.3 b/tcl/doc/BackgdErr.3 index 3fa59f8ef61..5716a9e4d81 100644 --- a/tcl/doc/BackgdErr.3 +++ b/tcl/doc/BackgdErr.3 @@ -33,7 +33,7 @@ obvious way for that code to report the error to the user. In these cases the code calls \fBTcl_BackgroundError\fR with an \fIinterp\fR argument identifying the interpreter in which the error occurred. At the time \fBTcl_BackgroundError\fR is invoked, -\fIinterp->result\fR is expected to contain an error message. +the interpreter's result is expected to contain an error message. \fBTcl_BackgroundError\fR will invoke the \fBbgerror\fR Tcl command to report the error in an application-specific fashion. If no \fBbgerror\fR command exists, or if it returns with an error condition, diff --git a/tcl/doc/Backslash.3 b/tcl/doc/Backslash.3 index ceeddea3323..071bf97702d 100644 --- a/tcl/doc/Backslash.3 +++ b/tcl/doc/Backslash.3 @@ -8,7 +8,7 @@ '\" RCS: @(#) $Id$ '\" .so man.macros -.TH Tcl_Backslash 3 "" Tcl "Tcl Library Procedures" +.TH Tcl_Backslash 3 "8.1" Tcl "Tcl Library Procedures" .BS .SH NAME Tcl_Backslash \- parse a backslash sequence @@ -30,16 +30,24 @@ the backslash character. .SH DESCRIPTION .PP -This is a utility procedure used by several of the Tcl -commands. It parses a backslash sequence and returns -the single character corresponding to the sequence. -\fBTcl_Backslash\fR modifies \fI*countPtr\fR to contain the number -of characters in the backslash sequence. +.VS 8.1 +The use of \fBTcl_Backslash\fR is deprecated in favor of +\fBTcl_UtfBackslash\fR. .PP -See the Tcl manual entry for information on the valid -backslash sequences. -All of the sequences described in the Tcl -manual entry are supported by \fBTcl_Backslash\fR. +This is a utility procedure provided for backwards compatibilty with +non-internationalized Tcl extensions. It parses a backslash sequence and +returns the low byte of the Unicode character corresponding to the sequence. +.VE +\fBTcl_Backslash\fR modifies \fI*countPtr\fR to contain the number of +characters in the backslash sequence. +.PP +See the Tcl manual entry for information on the valid backslash sequences. +All of the sequences described in the Tcl manual entry are supported by +\fBTcl_Backslash\fR. +.VS 8.1 br +.SH "SEE ALSO" +Tcl(n), Tcl_UtfBackslash(3) +.VE .SH KEYWORDS backslash, parse diff --git a/tcl/doc/ByteArrObj.3 b/tcl/doc/ByteArrObj.3 new file mode 100644 index 00000000000..ae3261b993d --- /dev/null +++ b/tcl/doc/ByteArrObj.3 @@ -0,0 +1,91 @@ +'\" +'\" Copyright (c) 1997 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id$ +'\" +.so man.macros +.TH Tcl_ByteArrayObj 3 8.1 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_NewByteArrayObj, Tcl_SetByteArrayObj, Tcl_GetByteArrayFromObj, Tcl_SetByteArrayLength \- manipulate Tcl objects as a arrays of bytes +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +Tcl_Obj * +\fBTcl_NewByteArrayObj\fR(\fIbytes, length\fR) +.sp +void +\fBTcl_SetByteArrayObj\fR(\fIobjPtr, bytes, length\fR) +.sp +unsigned char * +\fBTcl_GetByteArrayFromObj\fR(\fIobjPtr, lengthPtr\fR) +.sp +unsigned char * +\fBTcl_SetByteArrayLength\fR(\fIobjPtr, length\fR) +.SH ARGUMENTS +.AS "unsigned char" *lengthPtr in/out +.AP "unsigned char" *bytes in +The array of bytes used to initialize or set a byte-array object. +.AP int length in +The length of the array of bytes. It must be >= 0. +.AP Tcl_Obj *objPtr in/out +For \fBTcl_SetByteArrayObj\fR, this points to the object to be converted to +byte-array type. For \fBTcl_GetByteArrayFromObj\fR and +\fBTcl_SetByteArrayLength\fR, this points to the object from which to get +the byte-array value; if \fIobjPtr\fR does not already point to a byte-array +object, it will be converted to one. +.AP int *lengthPtr out +If non-NULL, filled with the length of the array of bytes in the object. +.BE + +.SH DESCRIPTION +.PP +These procedures are used to create, modify, and read Tcl byte-array objects +from C code. Byte-array objects are typically used to hold the +results of binary IO operations or data structures created with the +\fBbinary\fR command. In Tcl, an array of bytes is not equivalent to a +string. Conceptually, a string is an array of Unicode characters, while a +byte-array is an array of 8-bit quantities with no implicit meaning. +Accesser functions are provided to get the string representation of a +byte-array or to convert an arbitrary object to a byte-array. Obtaining the +string representation of a byte-array object (by calling +\fBTcl_GetStringFromObj\fR) produces a properly formed UTF-8 sequence with a +one-to-one mapping between the bytes in the internal representation and the +UTF-8 characters in the string representation. +.PP +\fBTcl_NewByteArrayObj\fR and \fBTcl_SetByteArrayObj\fR will +create a new object of byte-array type or modify an existing object to have a +byte-array type. Both of these procedures set the object's type to be +byte-array and set the object's internal representation to a copy of the +array of bytes given by \fIbytes\fR. \fBTcl_NewByteArrayObj\fR returns a +pointer to a newly allocated object with a reference count of zero. +\fBTcl_SetByteArrayObj\fR invalidates any old string representation and, if +the object is not already a byte-array object, frees any old internal +representation. +.PP +\fBTcl_GetByteArrayFromObj\fR converts a Tcl object to byte-array type and +returns a pointer to the object's new internal representation as an array of +bytes. The length of this array is stored in \fIlengthPtr\fR if +\fIlengthPtr\fR is non-NULL. The storage for the array of bytes is owned by +the object and should not be freed. The contents of the array may be +modified by the caller only if the object is not shared and the caller +invalidates the string representation. +.PP +\fBTcl_SetByteArrayLength\fR converts the Tcl object to byte-array type +and changes the length of the object's internal representation as an +array of bytes. If \fIlength\fR is greater than the space currently +allocated for the array, the array is reallocated to the new length; the +newly allocated bytes at the end of the array have arbitrary values. If +\fIlength\fR is less than the space currently allocated for the array, +the length of array is reduced to the new length. The return value is a +pointer to the object's new array of bytes. + +.SH "SEE ALSO" +Tcl_GetStringFromObj, Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount + +.SH KEYWORDS +object, byte array, utf, unicode, internationalization diff --git a/tcl/doc/ChnlStack.3 b/tcl/doc/ChnlStack.3 new file mode 100644 index 00000000000..a99e2848e69 --- /dev/null +++ b/tcl/doc/ChnlStack.3 @@ -0,0 +1,90 @@ +'\" +'\" 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$ +.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 \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 +.AP Tcl_Interp *interp in +Interpreter for error reporting - can be NULL. +.AP Tcl_ChannelType *typePtr in +The new channel I/O procedures to use for \fIchannel\fP. +.AP ClientData clientData in +Arbitrary one-word value to pass to channel I/O procedures. +.AP int mask in +Conditions under which \fIchannel\fR will be used: OR-ed combination of +\fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR and \fBTCL_EXCEPTION\fR. +This can be a subset of the operations currently allowed on \fIchannel\fP. +.AP Tcl_Channel channel in +An existing Tcl channel such as returned by \fBTcl_CreateChannel\fR. +.BE + +.SH DESCRIPTION +.PP +These functions are for use by extensions that add processing layers to Tcl +I/O channels. Examples include compression and encryption modules. These +functions transparently stack and unstack a new channel on top of an +existing one. Any number of channels can be stacked together. +.PP +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 diff --git a/tcl/doc/CrtChannel.3 b/tcl/doc/CrtChannel.3 index 17e9079bb64..0030b7f61d4 100644 --- a/tcl/doc/CrtChannel.3 +++ b/tcl/doc/CrtChannel.3 @@ -1,16 +1,17 @@ '\" '\" 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$ .so man.macros -.TH Tcl_CreateChannel 3 8.0 Tcl "Tcl Library Procedures" +.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_SetDefaultTranslation, Tcl_SetChannelBufferSize, Tcl_NotifyChannel, Tcl_BadChannelOption \- procedures for creating and manipulating channels +Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType, Tcl_GetChannelName, Tcl_GetChannelHandle, Tcl_GetChannelMode, Tcl_GetChannelBufferSize, Tcl_SetChannelBufferSize, Tcl_NotifyChannel, Tcl_BadChannelOption, 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 \fR @@ -26,27 +27,62 @@ Tcl_ChannelType * .sp char * \fBTcl_GetChannelName\fR(\fIchannel\fR) -.VS .sp int \fBTcl_GetChannelHandle\fR(\fIchannel, direction, handlePtr\fR) -.VE -.sp -int -\fBTcl_GetChannelFlags\fR(\fIchannel\fR) -.sp -\fBTcl_SetDefaultTranslation\fR(\fIchannel, transMode\fR) .sp int \fBTcl_GetChannelBufferSize\fR(\fIchannel\fR) .sp \fBTcl_SetChannelBufferSize\fR(\fIchannel, size\fR) .sp -.VS \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 @@ -66,20 +102,17 @@ 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. -.VS .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. -.VE .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. -.VS .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 @@ -92,7 +125,6 @@ Name of the invalid option. Specific options list (space separated words, without "-") to append to the standard generic options list. Can be NULL for generic options error message only. -.VE .BE @@ -156,7 +188,6 @@ the same as the \fItypePtr\fR argument in the call to with the channel, or NULL if the \fIchannelName\fR argument to \fBTcl_CreateChannel\fR was NULL. .PP -.VS \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 @@ -164,19 +195,12 @@ 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. -.VE .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_SetDefaultTranslation\fR sets the default end of line translation -mode. This mode will be installed as the translation mode for the channel -if an attempt is made to output on the channel while it is still in -\fBTCL_TRANSLATE_AUTO\fR mode. For a description of end of line translation -modes, see the manual entry for \fBfconfigure\fR. -.PP -\fBTcl_GetChannelBufferSize\fR returns the size, in bytes, of buffers + \fBTcl_GetChannelBufferSize\fR returns the size, in bytes, of buffers allocated to store input or output in \fIchan\fR. If the value was not set by a previous call to \fBTcl_SetChannelBufferSize\fR, described below, then the default value of 4096 is returned. @@ -188,31 +212,29 @@ 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 -.VS \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. -.VE .PP -.VS \fBTcl_BadChannelOption\fR is called from driver specific set or get option procs to generate a complete error message. -.VE .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 -\fBTcl_ChannelType\fR structure contains the following fields: +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 -.VS +The \fBTcl_ChannelType\fR structure contains the following fields: .CS typedef struct Tcl_ChannelType { char *\fItypeName\fR; - Tcl_DriverBlockModeProc *\fIblockModeProc\fR; + Tcl_ChannelTypeVersion \fIversion\fR; Tcl_DriverCloseProc *\fIcloseProc\fR; Tcl_DriverInputProc *\fIinputProc\fR; Tcl_DriverOutputProc *\fIoutputProc\fR; @@ -221,22 +243,63 @@ typedef struct Tcl_ChannelType { 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 -.VE .PP The driver must provide implementations for all functions except -\fIblockModeProc\fR, \fIseekProc\fR, \fIsetOptionProc\fR, and -\fIgetOptionProc\fR, which may be specified as NULL to indicate that the -channel does not support seeking. Other functions that can not be -implemented for this type of device should return \fBEINVAL\fR when invoked -to indicate that they are not implemented. +\fIblockModeProc\fR, \fIseekProc\fR, \fIsetOptionProc\fR, +\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 retried 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 retried with \fBTcl_ChannelVersion\fR, which returns +either \fBTCL_CHANNEL_VERSION_2\fR or \fBTCL_CHANNEL_VERSION_1\fR. +.VE .SH BLOCKMODEPROC .PP @@ -263,8 +326,13 @@ 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 retried with \fBTcl_ChannelBlockModeProc\fR, which returns +a pointer to the function. +.VE -.SH CLOSEPROC +.SH "CLOSEPROC AND CLOSE2PROC" .PP The \fIcloseProc\fR field contains the address of a function called by the generic layer to clean up driver-related information when the channel is @@ -285,7 +353,40 @@ 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 \fIinterp->result\fR. +the procedure should store an error message in the interpreter's result. +.PP +Alternatively, channels that support closing the read and write sides +independently may set \fIcloseProc\fR to \fBTCL_CLOSE2PROC\fR and set +\fIclose2Proc\fR to the address of a function that matches the +following prototype: +.PP +.CS +typedef int Tcl_DriverClose2Proc( + ClientData \fIinstanceData\fR, + Tcl_Interp *\fIinterp\fR, + int \fIflags\fR); +.CE +.PP +The \fIclose2Proc\fR will be called with \fIflags\fR set to an OR'ed +combination of \fBTCL_CLOSE_READ\fR or \fBTCL_CLOSE_WRITE\fR to +indicate that the driver should close the read and/or write side of +the channel. The channel driver may be invoked to perform +additional operations on the channel after \fIclose2Proc\fR is +called to close one or both sides of the channel. If \fIflags\fR is +\fB0\fR (zero), the driver should close the channel in the manner +described above for \fIcloseProc\fR. No further operations will be +invoked on this instance after \fIclose2Proc\fR is called with all +flags cleared. In all cases, the \fIclose2Proc\fR function should +return zero if the close operation was successful; otherwise it should +return a nonzero POSIX error code. In addition, if an error occurs and +\fIinterp\fR is not NULL, the procedure should store an error message +in the interpreter's result. +.PP +.VS 8.3.2 +These value can be retried with \fBTcl_ChannelCloseProc\fR or +\fBTcl_ChannelClose2Proc\fR, which returns a pointer to the respective +function. +.VE .SH INPUTPROC .PP @@ -328,6 +429,11 @@ 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 retried with \fBTcl_ChannelInputProc\fR, which returns +a pointer to the function. +.VE .SH OUTPUTPROC .PP @@ -364,6 +470,11 @@ error, some data may have been written to the device. 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 retried with \fBTcl_ChannelOutputProc\fR, which returns +a pointer to the function. +.VE .SH SEEKPROC .PP @@ -382,7 +493,7 @@ typedef int Tcl_DriverSeekProc( .PP The \fIinstanceData\fR argument is the same as the value given to \fBTcl_CreateChannel\fR when this channel was created. \fIOffset\fR and -\fIseekMode\fR have the same meaning as for the \fBTcl_SeekChannel\fR +\fIseekMode\fR have the same meaning as for the \fBTcl_Seek\fR procedure (described in the manual entry for \fBTcl_OpenFileChannel\fR). .PP The \fIerrorCodePtr\fR argument points to an integer variable provided by @@ -393,6 +504,11 @@ 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 retried with \fBTcl_ChannelSeekProc\fR, which returns +a pointer to the function. +.VE .SH SETOPTIONPROC .PP @@ -423,17 +539,20 @@ options. .PP If the option value is successfully modified to the new value, the function returns \fBTCL_OK\fR. -.VS It should call \fBTcl_BadChannelOption\fR which itself returns \fBTCL_ERROR\fR if the \fIoptionName\fR is unrecognized. -.VE 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 retried with \fBTcl_ChannelSetOptionProc\fR, which returns +a pointer to the function. +.VE .SH GETOPTIONPROC .PP @@ -444,9 +563,7 @@ channel. \fIgetOptionProc\fR must match the following prototype: .CS typedef int Tcl_DriverGetOptionProc( ClientData \fIinstanceData\fR, -.VS Tcl_Interp *\fIinterp\fR, -.VE char *\fIoptionName\fR, Tcl_DString *\fIdsPtr\fR); .CE @@ -457,7 +574,6 @@ 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. -.VS It should call \fBTcl_BadChannelOption\fR which itself returns \fBTCL_ERROR\fR if the \fIoptionName\fR is unrecognized. If a system call error occurs, @@ -465,7 +581,6 @@ 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. -.VE .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 @@ -473,9 +588,13 @@ 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 retried with \fBTcl_ChannelGetOptionProc\fR, which returns +a pointer to the function. +.VE .SH WATCHPROC -.VS .PP The \fIwatchProc\fR field contains the address of a function called by the generic layer to initialize the event notification mechanism to @@ -487,7 +606,6 @@ typedef void Tcl_DriverWatchProc( ClientData \fIinstanceData\fR, int \fImask\fR); .CE -.VE .PP The \fIinstanceData\fR is the same as the value passed to \fBTcl_CreateChannel\fR when this channel was created. The \fImask\fR @@ -495,7 +613,6 @@ 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 -.VS 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 @@ -506,6 +623,11 @@ 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 retried with \fBTcl_ChannelWatchProc\fR, which returns +a pointer to the function. +.VE .SH GETHANDLEPROC .PP @@ -520,7 +642,7 @@ typedef int Tcl_DriverGetHandleProc( ClientData *\fIhandlePtr\fR); .CE .PP -\fIInstanceData is the same as the value passed to +\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 @@ -533,9 +655,50 @@ 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 retried 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 retried 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 retried with \fBTcl_ChannelHandlerProc\fR, which returns +a pointer to the function. .VE -.VS .SH TCL_BADCHANNELOPTION .PP This procedure generates a "bad option" error message in an @@ -558,14 +721,40 @@ so you get for instance: -peername, or -sockname when called with optionList="peername sockname" .CE -"blah" is the optionName argument and "" +``blah'' is the optionName argument and ``'' 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. -.VE +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_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3), Tcl_QueueEvent(3), Tcl_StackChannel(3) .SH KEYWORDS blocking, channel driver, channel registration, channel type, nonblocking diff --git a/tcl/doc/CrtInterp.3 b/tcl/doc/CrtInterp.3 index bc7e9cca53a..4347736413d 100644 --- a/tcl/doc/CrtInterp.3 +++ b/tcl/doc/CrtInterp.3 @@ -36,7 +36,7 @@ a token for it. The token is required in calls to most other Tcl procedures, such as \fBTcl_CreateCommand\fR, \fBTcl_Eval\fR, and \fBTcl_DeleteInterp\fR. Clients are only allowed to access a few of the fields of -Tcl_Interp structures; see the Tcl_Interp +Tcl_Interp structures; see the \fBTcl_Interp\fR and \fBTcl_CreateCommand\fR man pages for details. The new interpreter is initialized with no defined variables and only the built-in Tcl commands. To bind in additional commands, call @@ -49,10 +49,10 @@ resources associated with it, including variables, procedures, and application-specific command bindings, will be deleted. After \fBTcl_DeleteInterp\fR returns any attempt to use \fBTcl_Eval\fR on the interpreter will fail and return \fBTCL_ERROR\fR. After the call to -\fBTcl_DeleteInterp\fR it is safe to examine \fIinterp->result\fR, query or -set the values of variables, define, undefine or retrieve procedures, and -examine the runtime evaluation stack. See below, in the section -\fBINTERPRETERS AND MEMORY MANAGEMENT\fR for details. +\fBTcl_DeleteInterp\fR it is safe to examine the interpreter's result, +query or set the values of variables, define, undefine or retrieve +procedures, and examine the runtime evaluation stack. See below, in the +section \fBINTERPRETERS AND MEMORY MANAGEMENT\fR for details. .PP \fBTcl_InterpDeleted\fR returns nonzero if \fBTcl_DeleteInterp\fR was called with \fIinterp\fR as its argument; this indicates that the @@ -124,8 +124,8 @@ All uses of interpreters in Tcl and Tk have already been protected. Extension writers should ensure that their code also properly protects any additional interpreters used, as described above. -.SH KEYWORDS -command, create, delete, interpreter - .SH "SEE ALSO" Tcl_Preserve(3), Tcl_Release(3) + +.SH KEYWORDS +command, create, delete, interpreter diff --git a/tcl/doc/CrtMathFnc.3 b/tcl/doc/CrtMathFnc.3 index b35b883cf58..253c10cafc8 100644 --- a/tcl/doc/CrtMathFnc.3 +++ b/tcl/doc/CrtMathFnc.3 @@ -87,7 +87,7 @@ It should set also \fIresultPtr->type\fR to either TCL_INT or TCL_DOUBLE to indicate which value was set. Under normal circumstances \fIproc\fR should return TCL_OK. If an error occurs while executing the function, \fIproc\fR should -return TCL_ERROR and leave an error message in \fIinterp->result\fR. +return TCL_ERROR and leave an error message in the interpreter's result. .SH KEYWORDS expression, mathematical function diff --git a/tcl/doc/CrtObjCmd.3 b/tcl/doc/CrtObjCmd.3 index 74ec90bf6c0..2b97779c7f7 100644 --- a/tcl/doc/CrtObjCmd.3 +++ b/tcl/doc/CrtObjCmd.3 @@ -59,11 +59,13 @@ Tcl command. \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_EvalObj\fR) +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 will delete any command \fIname\fR -already associated with the interpreter. +\fBTcl_CreateObjCommand\fR deletes any existing command +\fIname\fR already associated with the interpreter +(however see below for an exception where the existing command +is not deleted). It returns a token that may be used to refer to the command in subsequent calls to \fBTcl_GetCommandName\fR. If \fIname\fR contains any \fB::\fR namespace qualifiers, @@ -101,7 +103,7 @@ cause memory to be lost and the runtime stack to be corrupted. The compilers to report any such attempted assignment as an error. However, it is acceptable to modify the internal representation of any individual object argument. For instance, the user may call -\fBTcl_GetIntFromObject\fR on \fIobjv\fR[\fB2\fR] to obtain the integer +\fBTcl_GetIntFromObj\fR on \fIobjv\fR[\fB2\fR] to obtain the integer representation of that object; that call may change the type of the object that \fIobjv\fR[\fB2\fR] points at, but will not change where \fIobjv\fR[\fB2\fR] points. @@ -118,7 +120,7 @@ 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_EvalObj\fR sets interpreter's result to +\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 @@ -128,6 +130,17 @@ not modify them. Call \fBTcl_SetObjResult\fR if you want to return something from the \fIobjv\fR array. .PP +Ordinarily, \fBTcl_CreateObjCommand\fR deletes any existing command +\fIname\fR already associated with the interpreter. +However, if the existing command was created by a previous call to +\fBTcl_CreateCommand\fR, +\fBTcl_CreateObjCommand\fR does not delete the command +but instead arranges for the Tcl interpreter to call the +\fBTcl_ObjCmdProc\fR \fIproc\fR in the future. +The old string-based \fBTcl_CmdProc\fR associated with the command +is retained and its address can be obtained by subsequent +\fBTcl_GetCommandInfo\fR calls. This is done for backwards compatibility. +.PP \fIDeleteProc\fR will be invoked when (if) \fIname\fR is deleted. This can occur through a call to \fBTcl_DeleteCommand\fR, \fBTcl_DeleteCommandFromToken\fR, or \fBTcl_DeleteInterp\fR, @@ -239,7 +252,6 @@ 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. -.PP .SH "SEE ALSO" Tcl_CreateCommand, Tcl_ResetResult, Tcl_SetObjResult diff --git a/tcl/doc/CrtSlave.3 b/tcl/doc/CrtSlave.3 index 3c99cff1cf3..88767a12a87 100644 --- a/tcl/doc/CrtSlave.3 +++ b/tcl/doc/CrtSlave.3 @@ -170,7 +170,7 @@ created by \fBTcl_CreateSlave\fR) between \fIslaveInterp\fR and \fItargetInterp\fR. Any two interpreters can be used, without any restrictions on how they are related. .PP -\fBTcl_CreateAliasObj\fR is similar to \fBTcl_CreateAliasObj\fR except +\fBTcl_CreateAliasObj\fR is similar to \fBTcl_CreateAlias\fR except that it takes a vector of objects to pass as additional arguments instead of a vector of strings. .VE diff --git a/tcl/doc/DString.3 b/tcl/doc/DString.3 index 00b76bde315..ae73fe83ef7 100644 --- a/tcl/doc/DString.3 +++ b/tcl/doc/DString.3 @@ -36,6 +36,8 @@ char * .sp \fBTcl_DStringSetLength\fR(\fIdsPtr, newLength\fR) .sp +\fBTcl_DStringTrunc\fR(\fIdsPtr, newLength\fR) +.sp \fBTcl_DStringFree\fR(\fIdsPtr\fR) .sp \fBTcl_DStringResult\fR(\fIinterp, dsPtr\fR) @@ -124,13 +126,17 @@ caller to fill in the new space. even if the string is truncated to zero length, so \fBTcl_DStringFree\fR will still need to be called. .PP +\fBTcl_DStringTrunc\fR changes the length of a dynamic string. +This procedure is now deprecated. \fBTcl_DStringSetLength\fR should +be used instead. +.PP \fBTcl_DStringFree\fR should be called when you're finished using the string. It frees up any memory that was allocated for the string and reinitializes the string's value to an empty string. .PP \fBTcl_DStringResult\fR sets the result of \fIinterp\fR to the value of the dynamic string given by \fIdsPtr\fR. It does this by moving -a pointer from \fIdsPtr\fR to \fIinterp->result\fR. +a pointer from \fIdsPtr\fR to the interpreter's result. This saves the cost of allocating new memory and copying the string. \fBTcl_DStringResult\fR also reinitializes the dynamic string to an empty string. diff --git a/tcl/doc/DumpActiveMemory.3 b/tcl/doc/DumpActiveMemory.3 new file mode 100644 index 00000000000..285c0f3fffb --- /dev/null +++ b/tcl/doc/DumpActiveMemory.3 @@ -0,0 +1,68 @@ +'\" +'\" Copyright (c) 1992-1999 Karl Lehenbauer and Mark Diekhans. +'\" Copyright (c) 2000 by Scriptics Corporation. +'\" All rights reserved. +'\" +'\" RCS: @(#) $Id$ +'\" +.so man.macros +.TH "Tcl_DumpActiveMemory" 3 8.1 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_DumpActiveMemory, Tcl_InitMemory, Tcl_ValidateAllMemory \- Validated memory allocation interface. +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +int +\fBTcl_DumpActiveMemory\fR(\fIfileName\fR) +.sp +void +\fBTcl_InitMemory\fR(\fIinterp\fR) +.sp +void +\fBTcl_ValidateAllMemory\fR(\fIfileName, line\fR) + +.SH ARGUMENTS +.AP Tcl_Interp *interp in +Tcl interpreter in which to add commands. +.AP char *fileName in +For \fBTcl_DumpActiveMemory\fR, name of the file to which memory +information will be written. For \fBTcl_ValidateAllMemory\fR, name of +the file from which the call is being made (normally \fB__FILE__\fR). +.AP int line in +Line number at which the call to \fBTcl_ValidateAllMemory\fR is made +(normally \fB__LINE__\fR). +.BE + +.SH DESCRIPTION +These functions provide access to Tcl memory debugging information. +They are only available when Tcl has been compiled with +\fBTCL_MEM_DEBUG\fR defined at compile-time. +.PP +\fBTcl_DumpActiveMemory\fR will output a list of all currently +allocated memory to the specified file. The information output for +each allocated block of memory is: starting and ending addresses +(excluding guard zone), size, source file where \fBckalloc\fR was +called to allocate the block and line number in that file. It is +especially useful to call \fBTcl_DumpActiveMemory\fR after the Tcl +interpreter has been deleted. +.PP +\fBTcl_InitMemory\fR adds the Tcl \fBmemory\fR command to the +interpreter given by \fIinterp\fR. It is called by \fBTcl_Main\fR +when Tcl has been compiled with \fBTCL_MEM_DEBUG\fR defined. +.PP +\fBTcl_ValidateAllMemory\fR forces a validation of the guard zones of +all currently allocated blocks of memory. Normally validation of a +block occurs when its freed, unless full validation is enabled, in +which case validation of all blocks occurs when \fBckalloc\fR and +\fBckfree\fR are called. This function forces the validation to occur +at any point. + +.SH "SEE ALSO" +TCL_MEM_DEBUG, memory + +.SH KEYWORDS +memory, debug + + diff --git a/tcl/doc/Encoding.3 b/tcl/doc/Encoding.3 new file mode 100644 index 00000000000..146007f5782 --- /dev/null +++ b/tcl/doc/Encoding.3 @@ -0,0 +1,522 @@ +'\" +'\" Copyright (c) 1997-1998 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id$ +'\" +.so man.macros +.TH Tcl_GetEncoding 3 "8.1" Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_GetEncoding, Tcl_FreeEncoding, Tcl_ExternalToUtfDString, Tcl_ExternalToUtf, Tcl_UtfToExternalDString, Tcl_UtfToExternal, Tcl_WinTCharToUtf, Tcl_WinUtfToTChar, Tcl_GetEncodingName, Tcl_SetSystemEncoding, Tcl_GetEncodingNames, Tcl_CreateEncoding, Tcl_GetDefaultEncodingDir, Tcl_SetDefaultEncodingDir \- procedures for creating and using encodings. +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +Tcl_Encoding +\fBTcl_GetEncoding\fR(\fIinterp, name\fR) +.sp +void +\fBTcl_FreeEncoding\fR(\fIencoding\fR) +.sp +char * +\fBTcl_ExternalToUtfDString\fR(\fIencoding, src, srcLen, dstPtr\fR) +.sp +int +\fBTcl_ExternalToUtf\fR(\fIinterp, encoding, src, srcLen, flags, statePtr, dst, dstLen, srcReadPtr, dstWrotePtr, + dstCharsPtr\fR) +.sp +char * +\fBTcl_UtfToExternalDString\fR(\fIencoding, src, srcLen, dstPtr\fR) +.sp +int +\fBTcl_UtfToExternal\fR(\fIinterp, encoding, src, srcLen, flags, statePtr, dst, dstLen, srcReadPtr, dstWrotePtr, + dstCharsPtr\fR) +.sp +char * +\fBTcl_WinTCharToUtf\fR(\fItsrc, srcLen, dstPtr\fR) +.sp +TCHAR * +\fBTcl_WinUtfToTChar\fR(\fIsrc, srcLen, dstPtr\fR) +.sp +char * +\fBTcl_GetEncodingName\fR(\fIencoding\fR) +.sp +int +\fBTcl_SetSystemEncoding\fR(\fIinterp, name\fR) +.sp +void +\fBTcl_GetEncodingNames\fR(\fIinterp\fR) +.sp +Tcl_Encoding +\fBTcl_CreateEncoding\fR(\fItypePtr\fR) +.sp +char * +\fBTcl_GetDefaultEncodingDir\fR(\fIvoid\fR) +.sp +void +\fBTcl_SetDefaultEncodingDir\fR(\fIpath\fR) + + +.SH ARGUMENTS +.AS Tcl_EncodingState *dstWrotePtr +.AP Tcl_Interp *interp in +Interpreter to use for error reporting, or NULL if no error reporting is +desired. +.AP "CONST char" *name in +Name of encoding to load. +.AP Tcl_Encoding encoding in +The encoding to query, free, or use for converting text. If \fIencoding\fR is +NULL, the current system encoding is used. +.AP "CONST char" *src in +For the \fBTcl_ExternalToUtf\fR functions, an array of bytes in the +specified encoding that are to be converted to UTF-8. For the +\fBTcl_UtfToExternal\fR and \fBTcl_WinUtfToTChar\fR functions, an array of +UTF-8 characters to be converted to the specified encoding. +.AP "CONST TCHAR" *tsrc in +An array of Windows TCHAR characters to convert to UTF-8. +.AP int srcLen in +Length of \fIsrc\fR or \fItsrc\fR in bytes. If the length is negative, the +encoding-specific length of the string is used. +.AP Tcl_DString *dstPtr out +Pointer to an uninitialized or free \fBTcl_DString\fR in which the converted +result will be stored. +.AP int flags in +Various flag bits OR-ed together. +TCL_ENCODING_START signifies that the +source buffer is the first block in a (potentially multi-block) input +stream, telling the conversion routine to reset to an initial state and +perform any initialization that needs to occur before the first byte is +converted. TCL_ENCODING_END signifies that the source buffer is the last +block in a (potentially multi-block) input stream, telling the conversion +routine to perform any finalization that needs to occur after the last +byte is converted and then to reset to an initial state. +TCL_ENCODING_STOPONERROR signifies that the conversion routine should +return immediately upon reading a source character that doesn't exist in +the target encoding; otherwise a default fallback character will +automatically be substituted. +.AP Tcl_EncodingState *statePtr in/out +Used when converting a (generally long or indefinite length) byte stream +in a piece by piece fashion. The conversion routine stores its current +state in \fI*statePtr\fR after \fIsrc\fR (the buffer containing the +current piece) has been converted; that state information must be passed +back when converting the next piece of the stream so the conversion +routine knows what state it was in when it left off at the end of the +last piece. May be NULL, in which case the value specified for \fIflags\fR +is ignored and the source buffer is assumed to contain the complete string to +convert. +.AP char *dst out +Buffer in which the converted result will be stored. No more than +\fIdstLen\fR bytes will be stored in \fIdst\fR. +.AP int dstLen in +The maximum length of the output buffer \fIdst\fR in bytes. +.AP int *srcReadPtr out +Filled with the number of bytes from \fIsrc\fR that were actually +converted. This may be less than the original source length if there was +a problem converting some source characters. May be NULL. +.AP int *dstWrotePtr out +Filled with the number of bytes that were actually stored in the output +buffer as a result of the conversion. May be NULL. +.AP int *dstCharsPtr out +Filled with the number of characters that correspond to the number of bytes +stored in the output buffer. May be NULL. +.AP Tcl_EncodingType *typePtr in +Structure that defines a new type of encoding. +.AP char *path in +A path to the location of the encoding file. +.BE +.SH INTRODUCTION +.PP +These routines convert between Tcl's internal character representation, +UTF-8, and character representations used by various operating systems or +file systems, such as Unicode, ASCII, or Shift-JIS. When operating on +strings, such as such as obtaining the names of files or displaying +characters using international fonts, the strings must be translated into +one or possibly multiple formats that the various system calls can use. For +instance, on a Japanese Unix workstation, a user might obtain a filename +represented in the EUC-JP file encoding and then translate the characters to +the jisx0208 font encoding in order to display the filename in a Tk widget. +The purpose of the encoding package is to help bridge the translation gap. +UTF-8 provides an intermediate staging ground for all the various +encodings. In the example above, text would be translated into UTF-8 from +whatever file encoding the operating system is using. Then it would be +translated from UTF-8 into whatever font encoding the display routines +require. +.PP +Some basic encodings are compiled into Tcl. Others can be defined by the +user or dynamically loaded from encoding files in a +platform-independent manner. +.SH DESCRIPTION +.PP +\fBTcl_GetEncoding\fR finds an encoding given its \fIname\fR. The name may +refer to a builtin Tcl encoding, a user-defined encoding registered by +calling \fBTcl_CreateEncoding\fR, or a dynamically-loadable encoding +file. The return value is a token that represents the encoding and can be +used in subsequent calls to procedures such as \fBTcl_GetEncodingName\fR, +\fBTcl_FreeEncoding\fR, and \fBTcl_UtfToExternal\fR. If the name did not +refer to any known or loadable encoding, NULL is returned and an error +message is returned in \fIinterp\fR. +.PP +The encoding package maintains a database of all encodings currently in use. +The first time \fIname\fR is seen, \fBTcl_GetEncoding\fR returns an +encoding with a reference count of 1. If the same \fIname\fR is requested +further times, then the reference count for that encoding is incremented +without the overhead of allocating a new encoding and all its associated +data structures. +.PP +When an \fIencoding\fR is no longer needed, \fBTcl_FreeEncoding\fR +should be called to release it. When an \fIencoding\fR is no longer in use +anywhere (i.e., it has been freed as many times as it has been gotten) +\fBTcl_FreeEncoding\fR will release all storage the encoding was using +and delete it from the database. +.PP +\fBTcl_ExternalToUtfDString\fR converts a source buffer \fIsrc\fR from the +specified \fIencoding\fR into UTF-8. The converted bytes are stored in +\fIdstPtr\fR, which is then NULL terminated. The caller should eventually +call \fBTcl_DStringFree\fR to free any information stored in \fIdstPtr\fR. +When converting, if any of the characters in the source buffer cannot be +represented in the target encoding, a default fallback character will be +used. The return value is a pointer to the value stored in the DString. +.PP +\fBTcl_ExternalToUtf\fR converts a source buffer \fIsrc\fR from the specified +\fIencoding\fR into UTF-8. Up to \fIsrcLen\fR bytes are converted from the +source buffer and up to \fIdstLen\fR converted bytes are stored in \fIdst\fR. +In all cases, \fI*srcReadPtr\fR is filled with the number of bytes that were +successfully converted from \fIsrc\fR and \fI*dstWrotePtr\fR is filled with +the corresponding number of bytes that were stored in \fIdst\fR. The return +value is one of the following: +.RS +.IP \fBTCL_OK\fR 29 +All bytes of \fIsrc\fR were converted. +.IP \fBTCL_CONVERT_NOSPACE\fR 29 +The destination buffer was not large enough for all of the converted data; as +many characters as could fit were converted though. +.IP \fBTCL_CONVERT_MULTIBYTE\fR 29 +The last fews bytes in the source buffer were the beginning of a multibyte +sequence, but more bytes were needed to complete this sequence. A +subsequent call to the conversion routine should pass a buffer containing +the unconverted bytes that remained in \fIsrc\fR plus some further bytes +from the source stream to properly convert the formerly split-up multibyte +sequence. +.IP \fBTCL_CONVERT_SYNTAX\fR 29 +The source buffer contained an invalid character sequence. This may occur +if the input stream has been damaged or if the input encoding method was +misidentified. +.IP \fBTCL_CONVERT_UNKNOWN\fR 29 +The source buffer contained a character that could not be represented in +the target encoding and TCL_ENCODING_STOPONERROR was specified. +.RE +.LP +\fBTcl_UtfToExternalDString\fR converts a source buffer \fIsrc\fR from UTF-8 +into the specified \fIencoding\fR. The converted bytes are stored in +\fIdstPtr\fR, which is then terminated with the appropriate encoding-specific +NULL. The caller should eventually call \fBTcl_DStringFree\fR to free any +information stored in \fIdstPtr\fR. When converting, if any of the +characters in the source buffer cannot be represented in the target +encoding, a default fallback character will be used. The return value is +a pointer to the value stored in the DString. +.PP +\fBTcl_UtfToExternal\fR converts a source buffer \fIsrc\fR from UTF-8 into +the specified \fIencoding\fR. Up to \fIsrcLen\fR bytes are converted from +the source buffer and up to \fIdstLen\fR converted bytes are stored in +\fIdst\fR. In all cases, \fI*srcReadPtr\fR is filled with the number of +bytes that were successfully converted from \fIsrc\fR and \fI*dstWrotePtr\fR +is filled with the corresponding number of bytes that were stored in +\fIdst\fR. The return values are the same as the return values for +\fBTcl_ExternalToUtf\fR. +.PP +\fBTcl_WinUtfToTChar\fR and \fBTcl_WinTCharToUtf\fR are +Windows-only convenience +functions for converting between UTF-8 and Windows strings. On Windows 95 +(as with the Macintosh and Unix operating systems), +all strings exchanged between Tcl and the operating system are "char" +based. On Windows NT, some strings exchanged between Tcl and the +operating system are "char" oriented while others are in Unicode. By +convention, in Windows a TCHAR is a character in the ANSI code page +on Windows 95 and a Unicode character on Windows NT. +.PP +If you planned to use the same "char" based interfaces on both Windows +95 and Windows NT, you could use \fBTcl_UtfToExternal\fR and +\fBTcl_ExternalToUtf\fR (or their \fBTcl_DString\fR equivalents) with an +encoding of NULL (the current system encoding). On the other hand, +if you planned to use the Unicode interface when running on Windows NT +and the "char" interfaces when running on Windows 95, you would have +to perform the following type of test over and over in your program +(as represented in psuedo-code): +.CS +if (running NT) { + encoding <- Tcl_GetEncoding("unicode"); + nativeBuffer <- Tcl_UtfToExternal(encoding, utfBuffer); + Tcl_FreeEncoding(encoding); +} else { + nativeBuffer <- Tcl_UtfToExternal(NULL, utfBuffer); +.CE +\fBTcl_WinUtfToTChar\fR and \fBTcl_WinTCharToUtf\fR automatically +handle this test and use the proper encoding based on the current +operating system. \fBTcl_WinUtfToTChar\fR returns a pointer to +a TCHAR string, and \fBTcl_WinTCharToUtf\fR expects a TCHAR string +pointer as the \fIsrc\fR string. Otherwise, these functions +behave identically to \fBTcl_UtfToExternalDString\fR and +\fBTcl_ExternalToUtfDString\fR. +.PP +\fBTcl_GetEncodingName\fR is roughly the inverse of \fBTcl_GetEncoding\fR. +Given an \fIencoding\fR, the return value is the \fIname\fR argument that +was used to create the encoding. The string returned by +\fBTcl_GetEncodingName\fR is only guaranteed to persist until the +\fIencoding\fR is deleted. The caller must not modify this string. +.PP +\fBTcl_SetSystemEncoding\fR sets the default encoding that should be used +whenever the user passes a NULL value for the \fIencoding\fR argument to +any of the other encoding functions. If \fIname\fR is NULL, the system +encoding is reset to the default system encoding, \fBbinary\fR. If the +name did not refer to any known or loadable encoding, TCL_ERROR is +returned and an error message is left in \fIinterp\fR. Otherwise, this +procedure increments the reference count of the new system encoding, +decrements the reference count of the old system encoding, and returns +TCL_OK. +.PP +\fBTcl_GetEncodingNames\fR sets the \fIinterp\fR result to a list +consisting of the names of all the encodings that are currently defined +or can be dynamically loaded, searching the encoding path specified by +\fBTcl_SetDefaultEncodingDir\fR. This procedure does not ensure that the +dynamically-loadable encoding files contain valid data, but merely that they +exist. +.PP +\fBTcl_CreateEncoding\fR defines a new encoding and registers the C +procedures that are called back to convert between the encoding and +UTF-8. Encodings created by \fBTcl_CreateEncoding\fR are thereafter +visible in the database used by \fBTcl_GetEncoding\fR. Just as with the +\fBTcl_GetEncoding\fR procedure, the return value is a token that +represents the encoding and can be used in subsequent calls to other +encoding functions. \fBTcl_CreateEncoding\fR returns an encoding with a +reference count of 1. If an encoding with the specified \fIname\fR +already exists, then its entry in the database is replaced with the new +encoding; the token for the old encoding will remain valid and continue +to behave as before, but users of the new token will now call the new +encoding procedures. +.PP +The \fItypePtr\fR argument to \fBTcl_CreateEncoding\fR contains information +about the name of the encoding and the procedures that will be called to +convert between this encoding and UTF-8. It is defined as follows: +.PP +.CS +typedef struct Tcl_EncodingType { + CONST char *\fIencodingName\fR; + Tcl_EncodingConvertProc *\fItoUtfProc\fR; + Tcl_EncodingConvertProc *\fIfromUtfProc\fR; + Tcl_EncodingFreeProc *\fIfreeProc\fR; + ClientData \fIclientData\fR; + int \fInullSize\fR; +} Tcl_EncodingType; +.CE +.PP +The \fIencodingName\fR provides a string name for the encoding, by +which it can be referred in other procedures such as +\fBTcl_GetEncoding\fR. The \fItoUtfProc\fR refers to a callback +procedure to invoke to convert text from this encoding into UTF-8. +The \fIfromUtfProc\fR refers to a callback procedure to invoke to +convert text from UTF-8 into this encoding. The \fIfreeProc\fR refers +to a callback procedure to invoke when this encoding is deleted. The +\fIfreeProc\fR field may be NULL. The \fIclientData\fR contains an +arbitrary one-word value passed to \fItoUtfProc\fR, \fIfromUtfProc\fR, +and \fIfreeProc\fR whenever they are called. Typically, this is a +pointer to a data structure containing encoding-specific information +that can be used by the callback procedures. For instance, two very +similar encodings such as \fBascii\fR and \fBmacRoman\fR may use the +same callback procedure, but use different values of \fIclientData\fR +to control its behavior. The \fInullSize\fR specifies the number of +zero bytes that signify end-of-string in this encoding. It must be +\fB1\fR (for single-byte or multi-byte encodings like ASCII or +Shift-JIS) or \fB2\fR (for double-byte encodings like Unicode). +Constant-sized encodings with 3 or more bytes per character (such as +CNS11643) are not accepted. +.PP +The callback procedures \fItoUtfProc\fR and \fIfromUtfProc\fR should match the +type \fBTcl_EncodingConvertProc\fR: +.PP +.CS +typedef int Tcl_EncodingConvertProc( + ClientData \fIclientData\fR, + CONST char *\fIsrc\fR, + int \fIsrcLen\fR, + int \fIflags\fR, + Tcl_Encoding *\fIstatePtr\fR, + char *\fIdst\fR, + int \fIdstLen\fR, + int *\fIsrcReadPtr\fR, + int *\fIdstWrotePtr\fR, + int *\fIdstCharsPtr\fR); +.CE +.PP +The \fItoUtfProc\fR and \fIfromUtfProc\fR procedures are called by the +\fBTcl_ExternalToUtf\fR or \fBTcl_UtfToExternal\fR family of functions to +perform the actual conversion. The \fIclientData\fR parameter to these +procedures is the same as the \fIclientData\fR field specified to +\fBTcl_CreateEncoding\fR when the encoding was created. The remaining +arguments to the callback procedures are the same as the arguments, +documented at the top, to \fBTcl_ExternalToUtf\fR or +\fBTcl_UtfToExternal\fR, with the following exceptions. If the +\fIsrcLen\fR argument to one of those high-level functions is negative, +the value passed to the callback procedure will be the appropriate +encoding-specific string length of \fIsrc\fR. If any of the \fIsrcReadPtr\fR, +\fIdstWrotePtr\fR, or \fIdstCharsPtr\fR arguments to one of the high-level +functions is NULL, the corresponding value passed to the callback +procedure will be a non-NULL location. +.PP +The callback procedure \fIfreeProc\fR, if non-NULL, should match the type +\fBTcl_EncodingFreeProc\fR: +.CS +typedef void Tcl_EncodingFreeProc( + ClientData \fIclientData\fR); +.CE +.PP +This \fIfreeProc\fR function is called when the encoding is deleted. The +\fIclientData\fR parameter is the same as the \fIclientData\fR field +specified to \fBTcl_CreateEncoding\fR when the encoding was created. +.PP + +\fBTcl_GetDefaultEncodingDir\fR and \fBTcl_SetDefaultEncodingDir\fR +access and set the directory to use when locating the default encoding +files. If this value is not NULL, the \fBTclpInitLibraryPath\fR routine +appends the path to the head of the search path, and uses this path as +the first place to look into when trying to locate the encoding file. + +.SH "ENCODING FILES" +Space would prohibit precompiling into Tcl every possible encoding +algorithm, so many encodings are stored on disk as dynamically-loadable +encoding files. This behavior also allows the user to create additional +encoding files that can be loaded using the same mechanism. These +encoding files contain information about the tables and/or escape +sequences used to map between an external encoding and Unicode. The +external encoding may consist of single-byte, multi-byte, or double-byte +characters. +.PP +Each dynamically-loadable encoding is represented as a text file. The +initial line of the file, beginning with a ``#'' symbol, is a comment +that provides a human-readable description of the file. The next line +identifies the type of encoding file. It can be one of the following +letters: +.IP "[1] \fBS\fR" +A single-byte encoding, where one character is always one byte long in the +encoding. An example is \fBiso8859-1\fR, used by many European languages. +.IP "[2] \fBD\fR" +A double-byte encoding, where one character is always two bytes long in the +encoding. An example is \fBbig5\fR, used for Chinese text. +.IP "[3] \fBM\fR" +A multi-byte encoding, where one character may be either one or two bytes long. +Certain bytes are a lead bytes, indicating that another byte must follow +and that together the two bytes represent one character. Other bytes are not +lead bytes and represent themselves. An example is \fBshiftjis\fR, used by +many Japanese computers. +.IP "[4] \fBE\fR" +An escape-sequence encoding, specifying that certain sequences of bytes +do not represent characters, but commands that describe how following bytes +should be interpreted. +.PP +The rest of the lines in the file depend on the type. +.PP +Cases [1], [2], and [3] are collectively referred to as table-based encoding +files. The lines in a table-based encoding file are in the same +format as this example taken from the \fBshiftjis\fR encoding (this is not +the complete file): +.CS +# Encoding file: shiftjis, multi-byte +M +003F 0 40 +00 +0000000100020003000400050006000700080009000A000B000C000D000E000F +0010001100120013001400150016001700180019001A001B001C001D001E001F +0020002100220023002400250026002700280029002A002B002C002D002E002F +0030003100320033003400350036003700380039003A003B003C003D003E003F +0040004100420043004400450046004700480049004A004B004C004D004E004F +0050005100520053005400550056005700580059005A005B005C005D005E005F +0060006100620063006400650066006700680069006A006B006C006D006E006F +0070007100720073007400750076007700780079007A007B007C007D203E007F +0080000000000000000000000000000000000000000000000000000000000000 +0000000000000000000000000000000000000000000000000000000000000000 +0000FF61FF62FF63FF64FF65FF66FF67FF68FF69FF6AFF6BFF6CFF6DFF6EFF6F +FF70FF71FF72FF73FF74FF75FF76FF77FF78FF79FF7AFF7BFF7CFF7DFF7EFF7F +FF80FF81FF82FF83FF84FF85FF86FF87FF88FF89FF8AFF8BFF8CFF8DFF8EFF8F +FF90FF91FF92FF93FF94FF95FF96FF97FF98FF99FF9AFF9BFF9CFF9DFF9EFF9F +0000000000000000000000000000000000000000000000000000000000000000 +0000000000000000000000000000000000000000000000000000000000000000 +81 +0000000000000000000000000000000000000000000000000000000000000000 +0000000000000000000000000000000000000000000000000000000000000000 +0000000000000000000000000000000000000000000000000000000000000000 +0000000000000000000000000000000000000000000000000000000000000000 +300030013002FF0CFF0E30FBFF1AFF1BFF1FFF01309B309C00B4FF4000A8FF3E +FFE3FF3F30FD30FE309D309E30034EDD30053006300730FC20152010FF0F005C +301C2016FF5C2026202520182019201C201DFF08FF0930143015FF3BFF3DFF5B +FF5D30083009300A300B300C300D300E300F30103011FF0B221200B100D70000 +00F7FF1D2260FF1CFF1E22662267221E22342642264000B0203220332103FFE5 +FF0400A200A3FF05FF03FF06FF0AFF2000A72606260525CB25CF25CE25C725C6 +25A125A025B325B225BD25BC203B301221922190219121933013000000000000 +000000000000000000000000000000002208220B2286228722822283222A2229 +000000000000000000000000000000002227222800AC21D221D4220022030000 +0000000000000000000000000000000000000000222022A52312220222072261 +2252226A226B221A223D221D2235222B222C0000000000000000000000000000 +212B2030266F266D266A2020202100B6000000000000000025EF000000000000 +.CE +.PP +The third line of the file is three numbers. The first number is the +fallback character (in base 16) to use when converting from UTF-8 to this +encoding. The second number is a \fB1\fR if this file represents the +encoding for a symbol font, or \fB0\fR otherwise. The last number (in base +10) is how many pages of data follow. +.PP +Subsequent lines in the example above are pages that describe how to map +from the encoding into 2-byte Unicode. The first line in a page identifies +the page number. Following it are 256 double-byte numbers, arranged as 16 +rows of 16 numbers. Given a character in the encoding, the high byte of +that character is used to select which page, and the low byte of that +character is used as an index to select one of the double-byte numbers in +that page \- the value obtained being the corresponding Unicode character. +By examination of the example above, one can see that the characters 0x7E +and 0x8163 in \fBshiftjis\fR map to 203E and 2026 in Unicode, respectively. +.PP +Following the first page will be all the other pages, each in the same +format as the first: one number identifying the page followed by 256 +double-byte Unicode characters. If a character in the encoding maps to the +Unicode character 0000, it means that the character doesn't actually exist. +If all characters on a page would map to 0000, that page can be omitted. +.PP +Case [4] is the escape-sequence encoding file. The lines in an this type of +file are in the same format as this example taken from the \fBiso2022-jp\fR +encoding: +.CS +.ta 1.5i +# Encoding file: iso2022-jp, escape-driven +E +init {} +final {} +iso8859-1 \\x1b(B +jis0201 \\x1b(J +jis0208 \\x1b$@ +jis0208 \\x1b$B +jis0212 \\x1b$(D +gb2312 \\x1b$A +ksc5601 \\x1b$(C +.CE +.PP +In the file, the first column represents an option and the second column +is the associated value. \fBinit\fR is a string to emit or expect before +the first character is converted, while \fBfinal\fR is a string to emit +or expect after the last character. All other options are names of +table-based encodings; the associated value is the escape-sequence that +marks that encoding. Tcl syntax is used for the values; in the above +example, for instance, ``\fB{}\fR'' represents the empty string and +``\fB\\x1b\fR'' represents character 27. +.PP +When \fBTcl_GetEncoding\fR encounters an encoding \fIname\fR that has not +been loaded, it attempts to load an encoding file called \fIname\fB.enc\fR +from the \fBencoding\fR subdirectory of each directory specified in the +library path \fB$tcl_libPath\fR. If the encoding file exists, but is +malformed, an error message will be left in \fIinterp\fR. +.SH KEYWORDS +utf, encoding, convert + + + diff --git a/tcl/doc/Eval.3 b/tcl/doc/Eval.3 index 6a374bb9fdc..080d0ae7be6 100644 --- a/tcl/doc/Eval.3 +++ b/tcl/doc/Eval.3 @@ -8,85 +8,170 @@ '\" RCS: @(#) $Id$ '\" .so man.macros -.TH Tcl_Eval 3 7.0 Tcl "Tcl Library Procedures" +.TH Tcl_Eval 3 8.1 Tcl "Tcl Library Procedures" .BS .SH NAME -Tcl_Eval, Tcl_VarEval, Tcl_EvalFile, Tcl_GlobalEval \- execute Tcl commands +Tcl_EvalObjEx, Tcl_EvalFile, Tcl_EvalObjv, Tcl_Eval, Tcl_EvalEx, Tcl_GlobalEval, Tcl_GlobalEvalObj, Tcl_VarEval, Tcl_VarEvalVA \- execute Tcl scripts .SH SYNOPSIS .nf \fB#include \fR .sp +.VS int -\fBTcl_Eval\fR(\fIinterp, cmd\fR) +\fBTcl_EvalObjEx\fR(\fIinterp, objPtr, flags\fR) .sp int -\fBTcl_VarEval\fR(\fIinterp, string, string, ... \fB(char *) NULL\fR) +\fBTcl_EvalFile\fR(\fIinterp, fileName\fR) .sp int -\fBTcl_EvalFile\fR(\fIinterp, fileName\fR) +\fBTcl_EvalObjv\fR(\fIinterp, objc, objv, flags\fR) +.sp +int +\fBTcl_Eval\fR(\fIinterp, script\fR) +.sp +int +\fBTcl_EvalEx\fR(\fIinterp, script, numBytes, flags\fR) .sp int -\fBTcl_GlobalEval\fR(\fIinterp, cmd\fR) +\fBTcl_GlobalEval\fR(\fIinterp, script\fR) +.sp +int +\fBTcl_GlobalEvalObj\fR(\fIinterp, objPtr, flags\fR) +.sp +int +\fBTcl_VarEval\fR(\fIinterp, string, string, ... \fB(char *) NULL\fR) +.sp +int +\fBTcl_VarEvalVA\fR(\fIinterp, argList\fR) .SH ARGUMENTS .AS Tcl_Interp **termPtr; .AP Tcl_Interp *interp in -Interpreter in which to execute the command. -A string result will be stored in \fIinterp->result\fR. -.AP char *cmd in -Command (or sequence of commands) to execute. Must be in writable -memory (\fBTcl_Eval\fR makes temporary modifications to the command). -.AP char *string in -String forming part of Tcl command. +Interpreter in which to execute the script. The interpreter's result is +modified to hold the result or error message from the script. +.AP Tcl_Obj *objPtr in +A Tcl object containing the script to execute. +.AP int flags in +ORed combination of flag bits that specify additional options. +\fBTCL_EVAL_GLOBAL\fR and \fBTCL_EVAL_DIRECT\fR are currently supported. .AP char *fileName in -Name of file containing Tcl command string. +Name of a file containing a Tcl script. +.AP int objc in +The number of objects in the array pointed to by \fIobjPtr\fR; +this is also the number of words in the command. +.AP Tcl_Obj **objv in +Points to an array of pointers to objects; each object holds the +value of a single word in the command to execute. +.AP int numBytes in +The number of bytes in \fIscript\fR, not including any +null terminating character. If \-1, then all characters up to the +first null byte are used. +.AP char *script in +Points to first byte of script to execute. This script must be in +writable memory: temporary modifications are made to it during +parsing. +.AP char *string in +String forming part of a Tcl script. +.AP va_list argList in +An argument list which must have been initialised using +\fBTCL_VARARGS_START\fR, and cleared using \fBva_end\fR. .BE .SH DESCRIPTION .PP -All four of these procedures execute Tcl commands. -\fBTcl_Eval\fR is the core procedure and is used by all the others. -It executes the commands in the script held by \fIcmd\fR -until either an error occurs or it reaches the end of the script. +The procedures described here are invoked to execute Tcl scripts in +various forms. +\fBTcl_EvalObjEx\fR is the core procedure and is used by many of the others. +It executes the commands in the script stored in \fIobjPtr\fR +until either an error occurs or the end of the script is reached. +If this is the first time \fIobjPtr\fR has been executed, +its commands are compiled into bytecode instructions +which are then executed. The +bytecodes are saved in \fIobjPtr\fR so that the compilation step +can be skipped if the object is evaluated again in the future. +.PP +The return value from \fBTcl_EvalObjEx\fR (and all the other procedures +described here) is a Tcl completion code with +one of the values \fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, +\fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR. +In addition, a result value or error message is left in \fIinterp\fR's +result; it can be retrieved using \fBTcl_GetObjResult\fR. +.PP +\fBTcl_EvalFile\fR reads the file given by \fIfileName\fR and evaluates +its contents as a Tcl script. It returns the same information as +\fBTcl_EvalObjEx\fR. +If the file couldn't be read then a Tcl error is returned to describe +why the file couldn't be read. +.PP +\fBTcl_EvalObjv\fR executes a single pre-parsed command instead of a +script. The \fIobjc\fR and \fIobjv\fR arguments contain the values +of the words for the Tcl command, one word in each object in +\fIobjv\fR. \fBTcl_EvalObjv\fR evaluates the command and returns +a completion code and result just like \fBTcl_EvalObjEx\fR. +.PP +\fBTcl_Eval\fR is similar to \fBTcl_EvalObjEx\fR except that the script to +be executed is supplied as a string instead of an object and no compilation +occurs. The string is parsed and executed directly (using +\fBTcl_EvalObjv\fR) instead of compiling it and executing the bytecodes. +In situations where it is known that the script will never be executed +again, \fBTcl_Eval\fR may be faster than \fBTcl_EvalObjEx\fR. +\fBTcl_Eval\fR returns a completion code and result just like +\fBTcl_EvalObjEx\fR. Note: for backward compatibility with versions before +Tcl 8.0, \fBTcl_Eval\fR copies the object result in \fIinterp\fR to +\fIinterp->result\fR (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 -Note that \fBTcl_Eval\fR and \fBTcl_GlobalEval\fR -have been largely replaced by the -object-based procedures \fBTcl_EvalObj\fR and \fBTcl_GlobalEvalObj\fR. -Those object-based procedures evaluate a script held in a Tcl object -instead of a string. -The object argument can retain the bytecode instructions for the script -and so avoid reparsing the script each time it is executed. -\fBTcl_Eval\fR is implemented using \fBTcl_EvalObj\fR -but is slower because it must reparse the script each time -since there is no object to retain the bytecode instructions. +\fBTcl_EvalEx\fR is an extended version of \fBTcl_Eval\fR that takes +additional arguments \fInumBytes\fR and \fIflags\fR. For the +efficiency reason given above, \fBTcl_EvalEx\fR is generally preferred +over \fBTcl_Eval\fR. .PP -The return value from \fBTcl_Eval\fR is one of the Tcl return codes -\fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or -\fBTCL_CONTINUE\fR, and \fIinterp->result\fR will point to -a string with additional information (a result value or error message). -If an error occurs during compilation, this return information -describes the error. -Otherwise, this return information corresponds to the last command -executed from \fIcmd\fR. +\fBTcl_GlobalEval\fR and \fBTcl_GlobalEvalObj\fR are older procedures +that are now deprecated. They are similar to \fBTcl_EvalEx\fR and +\fBTcl_EvalObjEx\fR except that the script is evaluated in the global +namespace and its variable context consists of global variables only +(it ignores any Tcl procedures that are active). These functions are +equivalent to using the \fBTCL_EVAL_GLOBAL\fR flag (see below). .PP \fBTcl_VarEval\fR takes any number of string arguments of any length, concatenates them into a single string, then calls \fBTcl_Eval\fR to execute that string as a Tcl command. It returns the result of the command and also modifies -\fIinterp->result\fR in the usual fashion for Tcl commands. +\fIinterp->result\fR in the same way as \fBTcl_Eval\fR. The last argument to \fBTcl_VarEval\fR must be NULL to indicate the end -of arguments. +of arguments. \fBTcl_VarEval\fR is now deprecated. .PP -\fBTcl_EvalFile\fR reads the file given by \fIfileName\fR and evaluates -its contents as a Tcl command by calling \fBTcl_Eval\fR. It returns -a standard Tcl result that reflects the result of evaluating the file. -If the file couldn't be read then a Tcl error is returned to describe -why the file couldn't be read. +\fBTcl_VarEvalVA\fR is the same as \fBTcl_VarEval\fR except that +instead of taking a variable number of arguments it takes an argument +list. Like \fBTcl_VarEval\fR, \fBTcl_VarEvalVA\fR is deprecated. + +.SH "FLAG BITS" +Any ORed combination of the following values may be used for the +\fIflags\fR argument to procedures such as \fBTcl_EvalObjEx\fR: +.TP 23 +\fBTCL_EVAL_DIRECT\fR +This flag is only used by \fBTcl_EvalObjEx\fR; it is ignored by +other procedures. If this flag bit is set, the script is not +compiled to bytecodes; instead it is executed directly +as is done by \fBTcl_EvalEx\fR. The +\fBTCL_EVAL_DIRECT\fR flag is useful in situations where the +contents of an object are going to change immediately, so the +bytecodes won't be reused in a future execution. In this case, +it's faster to execute the script directly. +.TP 23 +\fBTCL_EVAL_GLOBAL\fR +If this flag is set, the script is processed at global level. This +means that it is evaluated in the global namespace and its variable +context consists of global variables only (it ignores any Tcl +procedures at are active). + +.SH "MISCELLANEOUS DETAILS" .PP During the processing of a Tcl command it is legal to make nested calls to evaluate other commands (this is how procedures and some control structures are implemented). If a code other than \fBTCL_OK\fR is returned -from a nested \fBTcl_Eval\fR invocation, +from a nested \fBTcl_EvalObjEx\fR invocation, then the caller should normally return immediately, passing that same return code back to its caller, and so on until the top-level application is reached. @@ -94,21 +179,19 @@ A few commands, like \fBfor\fR, will check for certain return codes, like \fBTCL_BREAK\fR and \fBTCL_CONTINUE\fR, and process them specially without returning. .PP -\fBTcl_Eval\fR keeps track of how many nested \fBTcl_Eval\fR +\fBTcl_EvalObjEx\fR keeps track of how many nested \fBTcl_EvalObjEx\fR invocations are in progress for \fIinterp\fR. If a code of \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR is -about to be returned from the topmost \fBTcl_Eval\fR +about to be returned from the topmost \fBTcl_EvalObjEx\fR invocation for \fIinterp\fR, it converts the return code to \fBTCL_ERROR\fR -and sets \fIinterp->result\fR -to point to an error message indicating that +and sets \fIinterp\fR's result to an error message indicating that the \fBreturn\fR, \fBbreak\fR, or \fBcontinue\fR command was invoked in an inappropriate place. This means that top-level applications should never see a return code -from \fBTcl_Eval\fR other then \fBTCL_OK\fR or \fBTCL_ERROR\fR. - -.SH "SEE ALSO" -Tcl_EvalObj, Tcl_GlobalEvalObj +from \fBTcl_EvalObjEx\fR other then \fBTCL_OK\fR or \fBTCL_ERROR\fR. +.VE .SH KEYWORDS -command, execute, file, global, object, object result, variable +execute, file, global, object, result, script + diff --git a/tcl/doc/Exit.3 b/tcl/doc/Exit.3 index 34cf336347b..3cb74c9f6a8 100644 --- a/tcl/doc/Exit.3 +++ b/tcl/doc/Exit.3 @@ -7,10 +7,10 @@ '\" RCS: @(#) $Id$ '\" .so man.macros -.TH Tcl_Exit 3 7.7 Tcl "Tcl Library Procedures" +.TH Tcl_Exit 3 8.1 Tcl "Tcl Library Procedures" .BS .SH NAME -Tcl_Exit, Tcl_Finalize, Tcl_CreateExitHandler, Tcl_DeleteExitHandler \- end the application (and invoke exit handlers) +Tcl_Exit, Tcl_Finalize, Tcl_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 \fR @@ -22,10 +22,19 @@ Tcl_Exit, Tcl_Finalize, Tcl_CreateExitHandler, Tcl_DeleteExitHandler \- end the \fBTcl_CreateExitHandler\fR(\fIproc, clientData\fR) .sp \fBTcl_DeleteExitHandler\fR(\fIproc, clientData\fR) +.sp +\fBTcl_ExitThread\fR(\fIstatus\fR) +.sp +\fBTcl_FinalizeThread\fR() +.sp +\fBTcl_CreateThreadExitHandler\fR(\fIproc, clientData\fR) +.sp +\fBTcl_DeleteThreadExitHandler\fR(\fIproc, clientData\fR) .SH ARGUMENTS .AS Tcl_ExitProc clientData .AP int status in -Provides information about why application exited. Exact meaning may +Provides information about why the application or thread exited. +Exact meaning may be platform-specific. 0 usually means a normal exit, any nonzero value usually means that an error occurred. .AP Tcl_ExitProc *proc in @@ -51,7 +60,6 @@ otherwise causes the application to terminate without calling \fBTcl_Exit\fR internally invokes the \fBexit\fR system call, thus it never returns control to its caller. .PP -.VS \fBTcl_Finalize\fR is similar to \fBTcl_Exit\fR except that it does not exit from the current process. It is useful for cleaning up when a process is finished using \fBTcl\fR but @@ -64,10 +72,20 @@ However, to ensure portability, your code should always invoke \fBTcl_Finalize\fR when \fBTcl\fR is being unloaded, to ensure that the code will work on all platforms. \fBTcl_Finalize\fR can be safely called more than once. +.PP +.VS +\fBTcl_ExitThread\fR is used to terminate the current thread and invoke +per-thread exit handlers. This finalization is done by +\fBTcl_FinalizeThread\fR, which you can call if you just want to clean +up per-thread state and invoke the thread exit handlers. +\fBTcl_Finalize\fR calls \fBTcl_FinalizeThread\fR for the current +thread automatically. .VE .PP \fBTcl_CreateExitHandler\fR arranges for \fIproc\fR to be invoked by \fBTcl_Finalize\fR and \fBTcl_Exit\fR. +\fBTcl_CreateThreadExitHandler\fR arranges for \fIproc\fR to be invoked +by \fBTcl_FinalizeThread\fR and \fBTcl_ExitThread\fR. This provides a hook for cleanup operations such as flushing buffers and freeing global memory. \fIProc\fR should match the type \fBTcl_ExitProc\fR: @@ -76,16 +94,18 @@ typedef void Tcl_ExitProc(ClientData \fIclientData\fR); .CE The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR argument given to -\fBTcl_CreateExitHandler\fR when the callback +\fBTcl_CreateExitHandler\fR or \fBTcl_CreateThreadExitHandler\fR when +the callback was created. Typically, \fIclientData\fR points to a data structure containing application-specific information about what to do in \fIproc\fR. .PP -\fBTcl_DeleteExitHandler\fR may be called to delete a +\fBTcl_DeleteExitHandler\fR and \fBTcl_DeleteThreadExitHandler\fR may be +called to delete a previously-created exit handler. It removes the handler indicated by \fIproc\fR and \fIclientData\fR so that no call to \fIproc\fR will be made. If no such handler exists then -\fBTcl_DeleteExitHandler\fR does nothing. +\fBTcl_DeleteExitHandler\fR or \fBTcl_DeleteThreadExitHandler\fR does nothing. .PP .VS .PP @@ -98,6 +118,15 @@ If extension \fBA\fR registers its exit handlers before loading extension \fBB\fR, this ensures that any exit handlers for \fBB\fR will be executed before the exit handlers for \fBA\fR. .VE +.VS +.PP +\fBTcl_Finalize\fR and \fBTcl_Exit\fR call \fBTcl_FinalizeThread\fR +and the thread exit handlers \fIafter\fR +the process-wide exit handlers. This is because thread finalization shuts +down the I/O channel system, so any attempt at I/O by the global exit +handlers will vanish into the bitbucket. +.VE .SH KEYWORDS -callback, cleanup, dynamic loading, end application, exit, unloading +callback, cleanup, dynamic loading, end application, exit, unloading, thread + diff --git a/tcl/doc/ExprLong.3 b/tcl/doc/ExprLong.3 index 903017488c2..8b4603736aa 100644 --- a/tcl/doc/ExprLong.3 +++ b/tcl/doc/ExprLong.3 @@ -63,15 +63,13 @@ that is more efficient to execute. The \fIinterp\fR argument refers to an interpreter used to evaluate the expression (e.g. for variables and nested Tcl commands) and to return error information. -\fIinterp->result\fR is assumed to be initialized -in the standard fashion when they are invoked. .PP For all of these procedures the return value is a standard Tcl result: \fBTCL_OK\fR means the expression was successfully evaluated, and \fBTCL_ERROR\fR means that an error occurred while evaluating the expression. If \fBTCL_ERROR\fR is returned then -\fIinterp->result\fR will hold a message describing the error. +the interpreter's result will hold a message describing the error. If an error occurs while executing a Tcl command embedded in the expression then that error will be returned. .PP @@ -99,7 +97,7 @@ it must be one of the values accepted by \fBTcl_GetBoolean\fR such as ``yes'' or ``no'', or else an error occurs. .PP \fBTcl_ExprString\fR returns the value of the expression as a -string stored in \fIinterp->result\fR. +string stored in the interpreter's result. If the expression's actual value is an integer then \fBTcl_ExprString\fR converts it to a string using \fBsprintf\fR with a ``%d'' converter. @@ -112,3 +110,4 @@ Tcl_ExprLongObj, Tcl_ExprDoubleObj, Tcl_ExprBooleanObj, Tcl_ExprObj .SH KEYWORDS boolean, double, evaluate, expression, integer, object, string + diff --git a/tcl/doc/FindExec.3 b/tcl/doc/FindExec.3 index a79c6f33b72..33f123b2aa2 100644 --- a/tcl/doc/FindExec.3 +++ b/tcl/doc/FindExec.3 @@ -7,7 +7,7 @@ '\" RCS: @(#) $Id$ '\" .so man.macros -.TH Tcl_FindExecutable 3 7.5 Tcl "Tcl Library Procedures" +.TH Tcl_FindExecutable 3 8.1 Tcl "Tcl Library Procedures" .BS .SH NAME Tcl_FindExecutable, Tcl_GetNameOfExecutable \- identify or return the name of the binary file containing the application @@ -15,7 +15,7 @@ Tcl_FindExecutable, Tcl_GetNameOfExecutable \- identify or return the name of th .nf \fB#include \fR .sp -char * +void \fBTcl_FindExecutable\fR(\fIargv0\fR) .sp CONST char * @@ -54,3 +54,4 @@ computed or unknown. .SH KEYWORDS binary, executable file + diff --git a/tcl/doc/GetCwd.3 b/tcl/doc/GetCwd.3 new file mode 100644 index 00000000000..eb8278f5269 --- /dev/null +++ b/tcl/doc/GetCwd.3 @@ -0,0 +1,54 @@ +'\" +'\" Copyright (c) 1998-1999 Scriptics Corportation +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id$ +'\" +.so man.macros +.TH Tcl_GetCwd 3 8.1 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_GetCwd, Tcl_Chdir \- manipulate the current working directory +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +char * +\fBTcl_GetCwd\fR(\fIinterp\fR, \fIbufferPtr\fR) +.sp +int +\fBTcl_Chdir\fR(\fIpath\fR) +.SH ARGUMENTS +.AS Tcl_DString *bufferPtr +.AP Tcl_Interp *interp in +Interpreter in which to report an error, if any. +.AP Tcl_DString *bufferPtr in/out +This dynamic string is used to store the current working directory. +At the time of the call it should be uninitialized or free. The +caller must eventually call \fBTcl_DStringFree\fR to free up +anything stored here. +.AP char *path in +File path in UTF\-8 format. +.BE + +.SH DESCRIPTION +.PP +These procedures may be used to manipulate the current working +directory for the application. They provide C\-level access to +the same functionality as the Tcl \fBpwd\fR command. +.PP +\fBTcl_GetCwd\fR returns a pointer to a string specifying the current +directory, or NULL if the current directory could not be determined. +If NULL is returned, an error message is left in the interp's result. +Storage for the result string is allocated in bufferPtr; the caller +must call \fBTcl_DStringFree()\fR when the result is no longer needed. +The format of the path is UTF\-8. +.PP +\fBTcl_Chdir\fR changes the applications current working directory to +the value specified in \fIpath\fR. The format of the passed in string +must be UTF\-8. The function returns -1 on error or 0 on success. + +.SH KEYWORDS +pwd diff --git a/tcl/doc/GetHostName.3 b/tcl/doc/GetHostName.3 new file mode 100644 index 00000000000..576c867196c --- /dev/null +++ b/tcl/doc/GetHostName.3 @@ -0,0 +1,29 @@ +'\" +'\" Copyright (c) 1998-2000 by Scriptics Corporation. +'\" All rights reserved. +'\" +'\" RCS: @(#) $Id$ +'\" +.so man.macros +.TH Tcl_GetHostName 3 8.3 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_GetHostName \- get the name of the local host +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +char * +\fBTcl_GetHostName\fR() + +.SH DESCRIPTION +.PP +\fBTcl_GetHostName\fR is a utility procedure used by some of the +Tcl commands. It returns a pointer to a string containing the name +for the current machine, or an empty string if the name cannot be +determined. The string is statically allocated, and the caller must +not modify of free it. +.PP +.SH KEYWORDS +hostname + diff --git a/tcl/doc/GetIndex.3 b/tcl/doc/GetIndex.3 index 53ac14baf47..b138cda6dc3 100644 --- a/tcl/doc/GetIndex.3 +++ b/tcl/doc/GetIndex.3 @@ -7,16 +7,23 @@ '\" RCS: @(#) $Id$ '\" .so man.macros -.TH Tcl_GetIndexFromObj 3 8.0 Tcl "Tcl Library Procedures" +.TH Tcl_GetIndexFromObj 3 8.1 Tcl "Tcl Library Procedures" .BS .SH NAME -Tcl_GetIndexFromObj \- lookup string in table of keywords +Tcl_GetIndexFromObj, Tcl_GetIndexFromObjStruct \- lookup string in table of keywords .SH SYNOPSIS .nf \fB#include \fR .sp int -\fBTcl_GetIndexFromObj\fR(\fIinterp, objPtr, tablePtr, msg, flags, indexPtr\fR) +\fBTcl_GetIndexFromObj\fR(\fIinterp, objPtr, tablePtr, msg, flags, +indexPtr\fR) +.VS +.sp +int +\fBTcl_GetIndexFromObjStruct\fR(\fIinterp, objPtr, tablePtr, offset, +msg, flags, indexPtr\fR) +.VE .SH ARGUMENTS .AS Tcl_Interp **tablePtr .AP Tcl_Interp *interp in @@ -29,6 +36,11 @@ table entry. .AP char **tablePtr in An array of null-terminated strings. The end of the array is marked by a NULL string pointer. +.VS +.AP int offset in +The offset to add to tablePtr to get to the next string in the +list. The end of the array is marked by a NULL string pointer. +.VE .AP char *msg in Null-terminated string describing what is being looked up, such as \fBoption\fR. This string is included in error messages. @@ -68,10 +80,24 @@ is invoked again with the same \fIobjPtr\fR and \fItablePtr\fR arguments (e.g. during a reinvocation of a Tcl command), it returns the matching index immediately without having to redo the lookup operation. Note: \fBTcl_GetIndexFromObj\fR assumes that the entries -in \fItablePtr\fR are static: they must not change between invocations. +in \fItablePtr\fR are static: they must not change between +invocations. If the value of \fIobjPtr\fR is the empty string, +\fBTcl_GetIndexFromObj\fR will treat it as a non-matching value +and return TCL_ERROR. +.VS +.PP +\fBTcl_GetIndexFromObjStruct\fR works just like +\fBTcl_GetIndexFromObj\fR, except that instead of treating +\fItablePtr\fR as an array of string pointers, it treats it as the +first in a series of string ptrs that are spaced apart by \fIoffset\fR +bytes. This is particularly useful when processing things like +\fBTk_ConfigurationSpec\fR, whose string keys are in the same place in +each of several array elements. +.VE .SH "SEE ALSO" Tcl_WrongNumArgs .SH KEYWORDS index, object, table lookup + diff --git a/tcl/doc/GetInt.3 b/tcl/doc/GetInt.3 index cceca7c080d..221ba070657 100644 --- a/tcl/doc/GetInt.3 +++ b/tcl/doc/GetInt.3 @@ -49,7 +49,7 @@ the converted value at the location indicated by the procedure's third argument. If all goes well, each of the procedures returns TCL_OK. If \fIstring\fR doesn't have the proper syntax for the desired type then TCL_ERROR is returned, an error message is left -in \fIinterp->result\fR, and nothing is stored at *\fIintPtr\fR +in the interpreter's result, and nothing is stored at *\fIintPtr\fR or *\fIdoublePtr\fR or *\fIboolPtr\fR. .PP \fBTcl_GetInt\fR expects \fIstring\fR to consist of a collection @@ -79,3 +79,4 @@ are also acceptable. .SH KEYWORDS boolean, conversion, double, floating-point, integer + diff --git a/tcl/doc/GetOpnFl.3 b/tcl/doc/GetOpnFl.3 index d8366d06aa0..8d9e0d7b17f 100644 --- a/tcl/doc/GetOpnFl.3 +++ b/tcl/doc/GetOpnFl.3 @@ -49,7 +49,7 @@ and writing. If an error occurs in \fBTcl_GetOpenFile\fR (e.g. \fIstring\fR didn't make any sense or \fIcheckUsage\fR was set and the file wasn't opened for the access specified by \fIwrite\fR) then TCL_ERROR is returned -and \fIinterp->result\fR will contain an error message. +and the interpreter's result will contain an error message. In the current implementation \fIcheckUsage\fR is ignored and consistency checks are always performed. .VS @@ -59,3 +59,4 @@ Note that this interface is only supported on the Unix platform. .SH KEYWORDS channel, file handle, permissions, pipeline, read, write + diff --git a/tcl/doc/GetVersion.3 b/tcl/doc/GetVersion.3 new file mode 100644 index 00000000000..5abec5b6aae --- /dev/null +++ b/tcl/doc/GetVersion.3 @@ -0,0 +1,49 @@ +'\" +'\" Copyright (c) 1999 Scriptics Corporation +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id$ +'\" +.so man.macros +.TH Tcl_GetVersion 3 7.5 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_GetVersion \- get the version of the library at runtime +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +\fBTcl_GetVersion\fR(\fImajor, minor, patchLevel, type\fR) +.SH ARGUMENTS +.AP int *major out +Major version number of the Tcl library. +.AP int *minor out +Minor version number of the Tcl library. +.AP int *patchLevel out +The patch level of the Tcl library (or alpha or beta number). +.AP Tcl_ReleaseType *type out +The type of release, also indicates the type of patch level. Can be +one of \fBTCL_ALPHA_RELEASE\fR, \fBTCL_BETA_RELEASE\fR, or +\fBTCL_FINAL_RELEASE\fR. +.BE + +.SH DESCRIPTION +.PP +\fBTcl_GetVersion\fR should be used to query the version number +of the Tcl library at runtime. This is useful when using a +dynamically loaded Tcl library or when writing a stubs-aware +extension. For instance, if you write an extension that is +linked against the Tcl stubs library, it could be loaded into +a program linked to an older version of Tcl than you expected. +Use \fBTcl_GetVersion\fR to verify that fact, and possibly to +change the behavior of your extension. +.PP +If may pass a NULL for any of the arguments. For instance if +you do not care about the \fIpatchLevel\fR of the library, pass +a NULL for the \fIpatchLevel\fR argument. + +.SH KEYWORDS +version, patchlevel, major, minor, alpha, beta, release + diff --git a/tcl/doc/Hash.3 b/tcl/doc/Hash.3 index 13de0b9fcc2..e3fb971989d 100644 --- a/tcl/doc/Hash.3 +++ b/tcl/doc/Hash.3 @@ -193,7 +193,7 @@ overall information about a hash table, such as the number of entries it contains, the number of buckets in its hash array, and the utilization of the buckets. It is the caller's responsibility to free the result string -by passing it to \fBfree\fR. +by passing it to \fBckfree\fR. .PP The header file \fBtcl.h\fR defines the actual data structures used to implement hash tables. diff --git a/tcl/doc/Init.3 b/tcl/doc/Init.3 new file mode 100644 index 00000000000..587a79614a1 --- /dev/null +++ b/tcl/doc/Init.3 @@ -0,0 +1,37 @@ +'\" +'\" Copyright (c) 1998-2000 by Scriptics Corporation. +'\" All rights reserved. +'\" +'\" RCS: @(#) $Id$ +'\" +.so man.macros +.TH Tcl_Init 3 8.0 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_Init \- find and source initialization script +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +int +\fBTcl_Init\fR(\fIinterp\fR) +.SH ARGUMENTS +.AP Tcl_Interp *interp in +Interpreter to initialize. +.BE + +.SH DESCRIPTION +.PP +\fBTcl_Init\fR is a helper procedure that finds and \fBsource\fR's the +\fBinit.tcl\fR script, which should exist somewhere on the Tcl library +path. On Macintosh systems, it additionally checks for an \fBInit\fR +resource and sources the contents of that resource if \fBinit.tcl\fR +cannot be found. +.PP +\fBTcl_Init\fR is typically called from \fBTcl_AppInit\fR procedures. + +.SH "SEE ALSO" +Tcl_AppInit, Tcl_Main + +.SH KEYWORDS +application, initialization, interpreter diff --git a/tcl/doc/InitStubs.3 b/tcl/doc/InitStubs.3 new file mode 100644 index 00000000000..aa12b8e6589 --- /dev/null +++ b/tcl/doc/InitStubs.3 @@ -0,0 +1,91 @@ +'\" +'\" Copyright (c) 1999 Scriptics Corportation +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id$ +'\" +.so man.macros +.TH Tcl_InitStubs 3 8.1 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_InitStubs \- initialize the Tcl stubs mechanism +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +char * +\fBTcl_InitStubs\fR(\fIinterp, version, exact\fR) +.SH ARGUMENTS +.AS Tcl_Interp *interp in +.AP Tcl_Interp *interp in +Tcl interpreter handle. +.AP char *version in +A version string consisting of one or more decimal numbers +separated by dots. +.AP int exact in +Non-zero means that only the particular version specified by +\fIversion\fR is acceptable. +Zero means that versions newer than \fIversion\fR are also +acceptable as long as they have the same major version number +as \fIversion\fR. +.BE +.SH INTRODUCTION +.PP +The Tcl stubs mechanism defines a way to dynamically bind +extensions to a particular Tcl implementation at run time. +This provides two significant benefits to Tcl users: +.IP 1) 5 +Extensions that use the stubs mechanism can be loaded into +multiple versions of Tcl without being recompiled or +relinked. +.IP 2) 5 +Extensions that use the stubs mechanism can be dynamically +loaded into statically-linked Tcl applications. +.PP +The stubs mechanism accomplishes this by exporting function tables +that define an interface to the Tcl API. The extension then accesses +the Tcl API through offsets into the function table, so there are no +direct references to any of the Tcl library's symbols. This +redirection is transparent to the extension, so an extension writer +can continue to use all public Tcl functions as documented. +.PP +The stubs mechanism requires no changes to applications incorporating +Tcl interpreters. Only developers creating C-based Tcl extensions +need to take steps to use the stubs mechanism with their extensions. +.PP +Enabling the stubs mechanism for an extension requires the following +steps: +.IP 1) 5 +Call \fBTcl_InitStubs\fR in the extension before calling any other +Tcl functions. +.IP 2) 5 +Define the USE_TCL_STUBS symbol. Typically, you would include the +-DUSE_TCL_STUBS flag when compiling the extension. +.IP 3) 5 +Link the extension with the Tcl stubs library instead of the standard +Tcl library. On Unix platforms, the library name is +\fIlibtclstub8.1.a\fR; on Windows platforms, the library name is +\fItclstub81.lib\fR. +.PP +If the extension also requires the Tk API, it must also call +\fBTk_InitStubs\fR to initialize the Tk stubs interface and link +with the Tk stubs libraries. See the \fBTk_InitStubs\fR page for +more information. +.SH DESCRIPTION +\fBTcl_InitStubs\fR attempts to initialize the stub table pointers +and ensure that the correct version of Tcl is loaded. In addition +to an interpreter handle, it accepts as arguments a version number +and a Boolean flag indicating whether the extension requires +an exact version match or not. If \fIexact\fR is 0, then the +extension is indicating that newer versions of Tcl are acceptable +as long as they have the same major version number as \fIversion\fR; +non-zero means that only the specified \fIversion\fR is acceptable. +\fBTcl_InitStubs\fR returns a string containing the actual version +of Tcl satisfying the request, or NULL if the Tcl version is not +acceptable, does not support stubs, or any other error condition occurred. +.SH "SEE ALSO" +\fBTk_InitStubs\fR +.SH KEYWORDS +stubs diff --git a/tcl/doc/Interp.3 b/tcl/doc/Interp.3 index d608f7f5943..b3d5f7b7330 100644 --- a/tcl/doc/Interp.3 +++ b/tcl/doc/Interp.3 @@ -107,7 +107,8 @@ returning an error) will generally assume that the result has been initialized when the procedure is called. If such a procedure is to be called after the result has been changed, then \fBTcl_ResetResult\fR should be called first to -reset the result to its initialized state. +reset the result to its initialized state. The direct use of +\fIinterp->result\fR is strongly deprecated (see \fBTcl_SetResult\fR). .PP The \fIerrorLine\fR field is valid only after \fBTcl_Eval\fR returns @@ -123,3 +124,4 @@ occurred. .SH KEYWORDS free, initialized, interpreter, malloc, result + diff --git a/tcl/doc/LinkVar.3 b/tcl/doc/LinkVar.3 index b5c25dc5c53..abc031ab639 100644 --- a/tcl/doc/LinkVar.3 +++ b/tcl/doc/LinkVar.3 @@ -48,7 +48,7 @@ be returned, and whenever the Tcl variable is written the C variable will be updated to have the same value. \fBTcl_LinkVar\fR normally returns TCL_OK; if an error occurs while setting up the link (e.g. because \fIvarName\fR is the -name of array) then TCL_ERROR is returned and \fIinterp->result\fR +name of array) then TCL_ERROR is returned and the interpreter's result contains an error message. .PP The \fItype\fR argument specifies the type of the C variable, @@ -113,3 +113,4 @@ variable are invoked. .SH KEYWORDS boolean, integer, link, read-only, real, string, traces, variable + diff --git a/tcl/doc/ListObj.3 b/tcl/doc/ListObj.3 index 7ae02ae82a5..9fec124243c 100644 --- a/tcl/doc/ListObj.3 +++ b/tcl/doc/ListObj.3 @@ -74,9 +74,7 @@ and \fBTcl_ListObjReplace\fR will insert into \fIlistPtr\fR. For \fBTcl_SetListObj\fR, the number of Tcl objects to insert into \fIobjPtr\fR. .VS -.TP -Tcl_Obj *CONST \fIobjv\fR[] (in) -. +.AP Tcl_Obj "*CONST\ objv[]" in An array of pointers to objects. \fBTcl_NewListObj\fR will insert these objects into a new list object and \fBTcl_ListObjReplace\fR will insert them into an existing \fIlistPtr\fR. @@ -151,16 +149,16 @@ of the elements in \fIobjc\fR since the list object now refers to them. The new list object returned by \fBTcl_NewListObj\fR has reference count zero. .PP -\fBTcl_ListObjGetElements\fR returns a count and -a pointer to an array of the elements in a list object. -It returns the count by storing it in the address \fIobjcPtr\fR. -Similarly, it returns the array pointer by storing it -in the address \fIobjvPtr\fR. -If \fIlistPtr\fR is not already a list object, -\fBTcl_ListObjGetElements\fR will attempt to convert it to one; -if the conversion fails, it returns \fBTCL_ERROR\fR -and leaves an error message in the interpreter's result object -if \fIinterp\fR is not NULL. +\fBTcl_ListObjGetElements\fR returns a count and a pointer to an array of +the elements in a list object. It returns the count by storing it in the +address \fIobjcPtr\fR. Similarly, it returns the array pointer by storing +it in the address \fIobjvPtr\fR. +The memory pointed to is managed by Tcl and should not be freed by the +caller. +If \fIlistPtr\fR is not already a list object, \fBTcl_ListObjGetElements\fR +will attempt to convert it to one; if the conversion fails, it returns +\fBTCL_ERROR\fR and leaves an error message in the interpreter's result +object if \fIinterp\fR is not NULL. Otherwise it returns \fBTCL_OK\fR after storing the count and array pointer. .PP \fBTcl_ListObjLength\fR returns the number of elements in the list object diff --git a/tcl/doc/Notifier.3 b/tcl/doc/Notifier.3 index 29b94e03a93..58a29db5903 100644 --- a/tcl/doc/Notifier.3 +++ b/tcl/doc/Notifier.3 @@ -1,4 +1,5 @@ '\" +'\" Copyright (c) 1998-1999 Scriptics Corporation '\" Copyright (c) 1995-1997 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution @@ -7,30 +8,52 @@ '\" RCS: @(#) $Id$ '\" .so man.macros -.TH Notifier 3 8.0 Tcl "Tcl Library Procedures" +.TH Notifier 3 8.1 Tcl "Tcl Library Procedures" .BS -.VS .SH NAME -Tcl_CreateEventSource, Tcl_DeleteEventSource, Tcl_SetMaxBlockTime, Tcl_QueueEvent, Tcl_DeleteEvents, Tcl_WaitForEvent, Tcl_SetTimer, Tcl_ServiceAll, Tcl_ServiceEvent, Tcl_GetServiceMode, Tcl_SetServiceMode \- the event queue and notifier interfaces - +Tcl_CreateEventSource, Tcl_DeleteEventSource, Tcl_SetMaxBlockTime, Tcl_QueueEvent, Tcl_ThreadQueueEvent, Tcl_ThreadAlert, Tcl_GetCurrentThread, Tcl_DeleteEvents, Tcl_InitNotifier, Tcl_FinalizeNotifier, Tcl_WaitForEvent, Tcl_AlertNotifier, Tcl_SetTimer, Tcl_ServiceAll, Tcl_ServiceEvent, Tcl_GetServiceMode, Tcl_SetServiceMode \- the event queue and notifier interfaces .SH SYNOPSIS .nf \fB#include \fR .sp -\fBTcl_CreateEventSource\fR(\fIsetupProc, checkProc, clientData\fB)\fR +void +\fBTcl_CreateEventSource\fR(\fIsetupProc, checkProc, clientData\fR) .sp -\fBTcl_DeleteEventSource\fR(\fIsetupProc, checkProc, clientData\fB)\fR +void +\fBTcl_DeleteEventSource\fR(\fIsetupProc, checkProc, clientData\fR) .sp -\fBTcl_SetMaxBlockTime\fR(\fItimePtr\fB)\fR +void +\fBTcl_SetMaxBlockTime\fR(\fItimePtr\fR) .sp +void \fBTcl_QueueEvent\fR(\fIevPtr, position\fR) -.VS +.VS 8.1 +.sp +void +\fBTcl_ThreadQueueEvent\fR(\fIthreadId, evPtr, position\fR) +.sp +void +\fBTcl_ThreadAlert\fR(\fIthreadId, clientData\fR) .sp +Tcl_ThreadId +\fBTcl_GetCurrentThread\fR() +.sp +void \fBTcl_DeleteEvents\fR(\fIdeleteProc, clientData\fR) .sp +ClientData +\fBTcl_InitNotifier\fR() +.sp +void +\fBTcl_FinalizeNotifier\fR(\fIclientData\fR) +.sp int \fBTcl_WaitForEvent\fR(\fItimePtr\fR) .sp +void +\fBTcl_AlertNotifier\fR(\fIclientData\fR) +.sp +void \fBTcl_SetTimer\fR(\fItimePtr\fR) .sp int @@ -48,7 +71,6 @@ int .SH ARGUMENTS .AS Tcl_EventDeleteProc milliseconds -.AS Tcl_EventSetupProc *setupProc .AP Tcl_EventSetupProc *setupProc in Procedure to invoke to prepare for event wait in \fBTcl_DoOneEvent\fR. .AP Tcl_EventCheckProc *checkProc in @@ -70,12 +92,14 @@ have been allocated by the caller using \fBTcl_Alloc\fR or \fBckalloc\fR. .AP Tcl_QueuePosition position in Where to add the new event in the queue: \fBTCL_QUEUE_TAIL\fR, \fBTCL_QUEUE_HEAD\fR, or \fBTCL_QUEUE_MARK\fR. +.AP Tcl_ThreadId threadId in +A unique identifier for a thread. +.AP Tcl_EventDeleteProc *deleteProc in +Procedure to invoke for each queued event in \fBTcl_DeleteEvents\fR. .AP int flags in What types of events to service. These flags are the same as those passed to \fBTcl_DoOneEvent\fR. -.AP Tcl_EventDeleteProc *deleteProc in -Procedure to invoke for each queued event in \fBTcl_DeleteEvents\fR. -.VS +.VS 8.1 .AP int mode in Inidicates whether events should be serviced by \fBTcl_ServiceAll\fR. Must be one of \fBTCL_SERVICE_NONE\fR or \fBTCL_SERVICE_ALL\fR. @@ -84,13 +108,11 @@ Must be one of \fBTCL_SERVICE_NONE\fR or \fBTCL_SERVICE_ALL\fR. .SH INTRODUCTION .PP -.VS The interfaces described here are used to customize the Tcl event loop. The two most common customizations are to add new sources of events and to merge Tcl's event loop with some other event loop, such as one provided by an application in which Tcl is embedded. Each of these tasks is described in a separate section below. -.VE .PP The procedures in this manual entry are the building blocks out of which the Tcl event notifier is constructed. The event notifier is the lowest @@ -108,18 +130,24 @@ higher-level software that they have occurred. The procedures and \fBTcl_SetMaxBlockTime\fR, \fBTcl_QueueEvent\fR, and \fBTcl_DeleteEvents\fR are used primarily by event sources. .IP [2] -The event queue: there is a single queue for the whole application, +The event queue: for non-threaded applications, +there is a single queue for the whole application, containing events that have been detected but not yet serviced. Event sources place events onto the queue so that they may be processed in order at appropriate times during the event loop. The event queue guarantees a fair discipline of event handling, so that no event source can starve the others. It also allows events to be saved for servicing at a future time. -.VS +.VS 8.1 +Threaded applications work in a +similar manner, except that there is a separate event queue for +each thread containing a Tcl interpreter. \fBTcl_QueueEvent\fR is used (primarily by event sources) to add events to the event queue and \fBTcl_DeleteEvents\fR is used to remove events from the queue without -processing them. +processing them. In a threaded application, \fBTcl_QueueEvent\fR adds +an event to the current thread's queue, and \fBTcl_ThreadQueueEvent\fR +adds an event to a queue in a specific thread. .IP [3] The event loop: in order to detect and process events, the application enters a loop that waits for events to occur, places them on the event @@ -133,7 +161,9 @@ to be retargeted either for a new platform or to use an external event loop (such as the Motif event loop, when Tcl is embedded in a Motif application). The procedures \fBTcl_WaitForEvent\fR and \fBTcl_SetTimer\fR are normally implemented by Tcl, but may be -replaced with new versions to retarget the notifier (the \fBTcl_Sleep\fR, +replaced with new versions to retarget the notifier (the +\fBTcl_InitNotifier\fR, \fBTcl_AlertNotifier\fR, +\fBTcl_FinalizeNotifier\fR, \fBTcl_Sleep\fR, \fBTcl_CreateFileHandler\fR, and \fBTcl_DeleteFileHandler\fR must also be replaced; see CREATING A NEW NOTIFIER below for details). The procedures \fBTcl_ServiceAll\fR, \fBTcl_ServiceEvent\fR, @@ -152,7 +182,7 @@ things: .IP [1] Check the event queue to see if it contains any events that can be serviced. If so, service the first possible event, remove it -.VS +.VS 8.1 from the queue, and return. It does this by calling \fBTcl_ServiceEvent\fR and passing in the \fIflags\fR argument. .VE @@ -160,7 +190,7 @@ from the queue, and return. It does this by calling Prepare to block for an event. To do this, \fBTcl_DoOneEvent\fR invokes a \fIsetup procedure\fR in each event source. The event source will perform event-source specific initialization and -.VS +.VS 8.1 possibly call \fBTcl_SetMaxBlockTime\fR to limit how long .VE \fBTcl_WaitForEvent\fR will block if no new events occur. @@ -228,7 +258,7 @@ request notification with a Windows event. For timer-driven event sources such as timer events or any polled event, the event source can call \fBTcl_SetMaxBlockTime\fR to force the application to wake up after a specified time even if no events have occurred. -.VS +.VS 8.1 If no event source calls \fBTcl_SetMaxBlockTime\fR then \fBTcl_WaitForEvent\fR will wait as long as necessary for an event to occur; otherwise, it will only wait as long as the shortest @@ -252,7 +282,7 @@ typedef struct Tcl_Time { .CE The \fIusec\fR field should be less than 1000000. .PP -.VS +.VS 8.1 Information provided to \fBTcl_SetMaxBlockTime\fR is only used for the next call to \fBTcl_WaitForEvent\fR; it is discarded after \fBTcl_WaitForEvent\fR returns. @@ -261,7 +291,7 @@ The next time an event wait is done each of the event sources' setup procedures will be called again, and they can specify new information for that event wait. .PP -.VS +.VS 8.1 If the application uses an external event loop rather than \fBTcl_DoOneEvent\fR, the event sources may need to call \fBTcl_SetMaxBlockTime\fR at other times. For example, if a new event @@ -307,10 +337,10 @@ 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_Event { +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. @@ -335,7 +365,7 @@ events at the front of the queue, such as a series of Enter and Leave events synthesized during a grab or ungrab operation in Tk. .PP -.VS +.VS 8.1 When it is time to handle an event from the queue (steps 1 and 4 above) \fBTcl_ServiceEvent\fR will invoke the \fIproc\fR specified .VE @@ -350,7 +380,7 @@ The first argument to \fIproc\fR is a pointer to the event, which will be the same as the first argument to the \fBTcl_QueueEvent\fR call that added the event to the queue. The second argument to \fIproc\fR is the \fIflags\fR argument for the -.VS +.VS 8.1 current call to \fBTcl_ServiceEvent\fR; this is used by the event source .VE to return immediately if its events are not relevant. @@ -361,7 +391,7 @@ Once the event source has finished handling the event it returns 1 to indicate that the event can be removed from the queue. If for some reason the event source decides that the event cannot be handled at this time, it may return 0 to indicate that the event -.VS +.VS 8.1 should be deferred for processing later; in this case \fBTcl_ServiceEvent\fR .VE will go on to the next event in the queue and attempt to service it. @@ -374,7 +404,7 @@ Another example of deferring events happens in Tk if \fBTk_RestrictEvents\fR has been invoked to defer certain kinds of window events. .PP -.VS +.VS 8.1 When \fIproc\fR returns 1, \fBTcl_ServiceEvent\fR will remove the event from the event queue and free its storage. Note that the storage for an event must be allocated by @@ -382,6 +412,21 @@ the event source (using \fBTcl_Alloc\fR or the Tcl macro \fBckalloc\fR) before calling \fBTcl_QueueEvent\fR, but it will be freed by \fBTcl_ServiceEvent\fR, not by the event source. .PP +Threaded applications work in a +similar manner, except that there is a separate event queue for +each thread containing a Tcl interpreter. +Calling \fBTcl_QueueEvent\fR in a multithreaded application adds +an event to the current thread's queue. +To add an event to another thread's queue, use \fBTcl_ThreadQueueEvent\fR. +\fBTcl_ThreadQueueEvent\fR accepts as an argument a Tcl_ThreadId argument, +which uniquely identifies a thread in a Tcl application. To obtain the +Tcl_ThreadID for the current thread, use the \fBTcl_GetCurrentThread\fR +procedure. (A thread would then need to pass this identifier to other +threads for those threads to be able to add events to its queue.) +After adding an event to another thread's queue, you then typically +need to call \fBTcl_ThreadAlert\fR to "wake up" that thread's notifier to +alert it to the new event. +.PP \fBTcl_DeleteEvents\fR can be used to explicitly remove one or more events from the event queue. \fBTcl_DeleteEvents\fR calls \fIproc\fR for each event in the queue, deleting those for with the procedure @@ -396,23 +441,35 @@ The \fIclientData\fR argument will be the same as the \fIclientData\fR argument to \fBTcl_DeleteEvents\fR; it is typically used to point to private information managed by the event source. The \fIevPtr\fR will point to the next event in the queue. +.PP +\fBTcl_DeleteEventSource\fR deletes an event source. The \fIsetupProc\fR, +\fIcheckProc\fR, and \fIclientData\fR arguments must exactly match those +provided to the \fBTcl_CreateEventSource\fR for the event source to be deleted. +If no such source exists, \fBTcl_DeleteEventSource\fR has no effect. .VE .SH "CREATING A NEW NOTIFIER" .PP The notifier consists of all the procedures described in this manual entry, plus \fBTcl_DoOneEvent\fR and \fBTcl_Sleep\fR, which are -.VS +.VS 8.1 available on all platforms, and \fBTcl_CreateFileHandler\fR and \fBTcl_DeleteFileHandler\fR, which are Unix-specific. Most of these procedures are generic, in that they are the same for all notifiers. -However, five of the procedures are notifier-dependent: +However, eight of the procedures are notifier-dependent: +\fBTcl_InitNotifier\fR, \fBTcl_AlertNotifier\fR, \fBTcl_FinalizeNotifier\fR, \fBTcl_SetTimer\fR, \fBTcl_Sleep\fR, \fBTcl_WaitForEvent\fR, \fBTcl_CreateFileHandler\fR and \fBTcl_DeleteFileHandler\fR. To support a new platform or to integrate Tcl with an application-specific event loop, you must write new versions of these procedures. .PP +\fBTcl_InitNotifier\fR initializes the notifier state and returns +a handle to the notifier state. Tcl calls this +procedure when intializing a Tcl interpreter. Similarly, +\fBTcl_FinalizeNotifier\fR shuts down the notifier, and is +called by \fBTcl_Finalize\fR when shutting down a Tcl interpreter. +.PP \fBTcl_WaitForEvent\fR is the lowest-level procedure in the notifier; it is responsible for waiting for an ``interesting'' event to occur or for a given time to elapse. Before \fBTcl_WaitForEvent\fR is invoked, @@ -448,6 +505,11 @@ under Unix it happens when \fBTcl_WaitForEvent\fR would have waited forever because there were no active event sources and the timeout was infinite. .PP +\fBTcl_AlertNotifier\fR is used in multithreaded applications to allow +any thread to "wake up" the notifier to alert it to new events on its +queue. \fBTcl_AlertNotifier\fR requires as an argument the notifier +handle returned by \fBTcl_InitNotifier\fR. +.PP If the notifier will be used with an external event loop, then it must also support the \fBTcl_SetTimer\fR interface. \fBTcl_SetTimer\fR is invoked by \fBTcl_SetMaxBlockTime\fR whenever the maximum blocking @@ -462,10 +524,11 @@ notifier will only be used from \fBTcl_DoOneEvent\fR, then On Unix systems, the file event source also needs support from the notifier. The file event source consists of the \fBTcl_CreateFileHandler\fR and \fBTcl_DeleteFileHandler\fR -procedures, which are described elsewhere. +procedures, which are described in the \fBTcl_CreateFileHandler\fR +manual page. .PP The \fBTcl_Sleep\fR and \fBTcl_DoOneEvent\fR interfaces are described -elsewhere. +in their respective manual pages. .PP The easiest way to create a new notifier is to look at the code for an existing notifier, such as the files \fBunix/tclUnixNotfy.c\fR @@ -532,6 +595,9 @@ 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 +event, notifier, event queue, event sources, file events, timer, idle, service mode, threads + diff --git a/tcl/doc/Object.3 b/tcl/doc/Object.3 index ca828188e03..6b62eccd935 100644 --- a/tcl/doc/Object.3 +++ b/tcl/doc/Object.3 @@ -10,7 +10,7 @@ .TH Tcl_Obj 3 8.0 Tcl "Tcl Library Procedures" .BS .SH NAME -Tcl_NewObj, Tcl_DuplicateObj, Tcl_IncrRefCount, Tcl_DecrRefCount, Tcl_IsShared \- manipulate Tcl objects +Tcl_NewObj, Tcl_DuplicateObj, Tcl_IncrRefCount, Tcl_DecrRefCount, Tcl_IsShared, Tcl_InvalidateStringRep \- manipulate Tcl objects .SH SYNOPSIS .nf \fB#include \fR @@ -85,7 +85,7 @@ Because of this representation invalidation and regeneration, it is dangerous for extension writers to access \fBTcl_Obj\fR fields directly. It is better to access Tcl_Obj information using -procedures like \fBTcl_GetStringFromObj\fR. +procedures like \fBTcl_GetStringFromObj\fR and \fBTcl_GetString\fR. .PP Objects are allocated on the heap and are referenced using a pointer to their \fBTcl_Obj\fR structure. @@ -138,7 +138,7 @@ The byte array must always have a null after the last byte, at offset \fIlength\fR; this allows string representations that do not contain nulls to be treated as conventional null-terminated C strings. -C programs use \fBTcl_GetStringFromObj\fR to get +C programs use \fBTcl_GetStringFromObj\fR and \fBTcl_GetString\fR to get an object's string representation. If \fIbytes\fR is NULL, the string representation is invalid. @@ -177,7 +177,8 @@ An object typically starts out containing only a string representation: it is untyped and has a NULL \fItypePtr\fR. An object containing an empty string or a copy of a specified string is created using \fBTcl_NewObj\fR or \fBTcl_NewStringObj\fR respectively. -An object's string value is gotten with \fBTcl_GetStringFromObj\fR +An object's string value is gotten with +\fBTcl_GetStringFromObj\fR or \fBTcl_GetString\fR and changed with \fBTcl_SetStringObj\fR. If the object is later passed to a procedure like \fBTcl_GetIntFromObj\fR that requires a specific internal representation, @@ -187,7 +188,7 @@ An object's two representations are duals of each other: changes made to one are reflected in the other. For example, \fBTcl_ListObjReplace\fR will modify an object's internal representation and the next call to \fBTcl_GetStringFromObj\fR -will reflect that change. +or \fBTcl_GetString\fR will reflect that change. .PP Representations are recomputed lazily for efficiency. A change to one representation made by a procedure @@ -208,7 +209,7 @@ free any storage associated with the old string representation. Objects usually remain one type over their life, but occasionally an object must be converted from one type to another. For example, a C program might build up a string in an object -with repeated calls to \fBTcl_StringObjAppend\fR, +with repeated calls to \fBTcl_AppendToObj\fR, and then call \fBTcl_ListObjIndex\fR to extract a list element from the object. The same object holding the same string value @@ -292,7 +293,7 @@ reference to it from the formal parameter. When the called procedure returns, the interpreter calls \fBTcl_DecrRefCount\fR to decrement each argument's reference count. -When an object's reference count drops to zero, +When an object's reference count drops less than or equal to zero, \fBTcl_DecrRefCount\fR reclaims its storage. Most command procedures do not have to be concerned about reference counting since they use an object's value immediately @@ -334,3 +335,4 @@ Tcl_ConvertToType, Tcl_GetIntFromObj, Tcl_ListObjAppendElement, Tcl_ListObjIndex .SH KEYWORDS internal representation, object, object creation, object type, reference counting, string representation, type conversion + diff --git a/tcl/doc/OpenFileChnl.3 b/tcl/doc/OpenFileChnl.3 index 3a73c173586..b0728185ea1 100644 --- a/tcl/doc/OpenFileChnl.3 +++ b/tcl/doc/OpenFileChnl.3 @@ -6,11 +6,11 @@ '\" '\" RCS: @(#) $Id$ .so man.macros -.TH Tcl_OpenFileChannel 3 8.0 Tcl "Tcl Library Procedures" +.TH Tcl_OpenFileChannel 3 8.3 Tcl "Tcl Library Procedures" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -Tcl_OpenFileChannel, Tcl_OpenCommandChannel, Tcl_MakeFileChannel, Tcl_GetChannel, Tcl_RegisterChannel, Tcl_UnregisterChannel, Tcl_Close, Tcl_Read, Tcl_Gets, Tcl_Write, Tcl_Flush, Tcl_Seek, Tcl_Tell, Tcl_Eof, Tcl_InputBlocked, Tcl_InputBuffered, Tcl_GetChannelOption, Tcl_SetChannelOption \- buffered I/O facilities using channels +Tcl_OpenFileChannel, Tcl_OpenCommandChannel, Tcl_MakeFileChannel, Tcl_GetChannel, Tcl_GetChannelNames, Tcl_GetChannelNamesEx, Tcl_RegisterChannel, Tcl_UnregisterChannel, Tcl_Close, Tcl_ReadChars, Tcl_Read, Tcl_GetsObj, Tcl_Gets, Tcl_WriteObj, Tcl_WriteChars, Tcl_Write, Tcl_Flush, Tcl_Seek, Tcl_Tell, Tcl_GetChannelOption, Tcl_SetChannelOption, Tcl_Eof, Tcl_InputBlocked, Tcl_InputBuffered, Tcl_Ungets \- buffered I/O facilities using channels .SH SYNOPSIS .nf \fB#include \fR @@ -22,7 +22,7 @@ Tcl_Channel .sp Tcl_Channel \fBTcl_OpenCommandChannel\fR(\fIinterp, argc, argv, flags\fR) -.VS +.VS 8.0 .sp Tcl_Channel \fBTcl_MakeFileChannel\fR(\fIhandle, readOrWrite\fR) @@ -30,6 +30,14 @@ Tcl_Channel .sp Tcl_Channel \fBTcl_GetChannel\fR(\fIinterp, channelName, modePtr\fR) +.VS 8.3 +.sp +int +\fBTcl_GetChannelNames\fR(\fIinterp\fR) +.sp +int +\fBTcl_GetChannelNamesEx\fR(\fIinterp, pattern\fR) +.VE .sp void \fBTcl_RegisterChannel\fR(\fIinterp, channel\fR) @@ -40,35 +48,37 @@ int int \fBTcl_Close\fR(\fIinterp, channel\fR) .sp +.VS 8.1 int -\fBTcl_Read\fR(\fIchannel, buf, toRead\fR) +\fBTcl_ReadChars\fR(\fIchannel, readObjPtr, charsToRead, appendFlag\fR) .sp int -\fBTcl_Gets\fR(\fIchannel, lineRead\fR) +\fBTcl_Read\fR(\fIchannel, byteBuf, bytesToRead\fR) .sp int \fBTcl_GetsObj\fR(\fIchannel, lineObjPtr\fR) .sp int -\fBTcl_Write\fR(\fIchannel, buf, toWrite\fR) +\fBTcl_Gets\fR(\fIchannel, lineRead\fR) .sp int -\fBTcl_Flush\fR(\fIchannel\fR) +\fBTcl_Ungets\fR(\fIchannel, input, inputLen, addAtEnd\fR) .sp int -\fBTcl_Seek\fR(\fIchannel, offset, seekMode\fR) +\fBTcl_WriteObj\fR(\fIchannel, writeObjPtr\fR) .sp int -\fBTcl_Tell\fR(\fIchannel\fR) +\fBTcl_WriteChars\fR(\fIchannel, charBuf, bytesToWrite\fR) .sp int -\fBTcl_GetChannelOption\fR(\fIinterp, channel, optionName, optionValue\fR) +\fBTcl_Write\fR(\fIchannel, byteBuf, bytesToWrite\fR) +.VE .sp int -\fBTcl_SetChannelOption\fR(\fIinterp, channel, optionName, newValue\fR) +\fBTcl_Eof\fR(\fIchannel\fR) .sp int -\fBTcl_Eof\fR(\fIchannel\fR) +\fBTcl_Flush\fR(\fIchannel\fR) .sp int \fBTcl_InputBlocked\fR(\fIchannel\fR) @@ -76,6 +86,18 @@ int int \fBTcl_InputBuffered\fR(\fIchannel\fR) .sp +int +\fBTcl_Seek\fR(\fIchannel, offset, seekMode\fR) +.sp +int +\fBTcl_Tell\fR(\fIchannel\fR) +.sp +int +\fBTcl_GetChannelOption\fR(\fIinterp, channel, optionName, optionValue\fR) +.sp +int +\fBTcl_SetChannelOption\fR(\fIinterp, channel, optionName, newValue\fR) +.sp .SH ARGUMENTS .AS Tcl_ChannelType newClientProcPtr in .AP Tcl_Interp *interp in @@ -83,37 +105,36 @@ Used for error reporting and to look up a channel registered in it. .AP char *fileName in The name of a local or network file. .AP char *mode in -Specifies how the file is to be accessed. May have any of the -values allowed for the \fImode\fR argument to the Tcl -\fBopen\fR command. -For \fBTcl_OpenCommandChannel\fR, may be NULL. +Specifies how the file is to be accessed. May have any of the values +allowed for the \fImode\fR argument to the Tcl \fBopen\fR command. For +\fBTcl_OpenCommandChannel\fR, may be NULL. .AP int permissions in -POSIX-style permission flags such as 0644. -If a new file is created, these permissions will be set on the -created file. +POSIX-style permission flags such as 0644. If a new file is created, these +permissions will be set on the created file. .AP int argc in The number of elements in \fIargv\fR. .AP char **argv in -Arguments for constructing a command pipeline. -These values have the same meaning as the non-switch arguments -to the Tcl \fBexec\fR command. +Arguments for constructing a command pipeline. These values have the same +meaning as the non-switch arguments to the Tcl \fBexec\fR command. .AP int flags in Specifies the disposition of the stdio handles in pipeline: OR-ed -combination of \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, \fBTCL_STDERR\fR, -and \fBTCL_ENFORCE_MODE\fR. If \fBTCL_STDIN\fR is set, stdin for -the first child in the pipe is the pipe channel, otherwise it is the same -as the standard input of the invoking process; likewise for -\fBTCL_STDOUT\fR and \fBTCL_STDERR\fR. If \fBTCL_ENFORCE_MODE\fR is not set, -then the pipe can redirect stdio handles to override the stdio handles for -which \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR and \fBTCL_STDERR\fR have been set. -If it is set, then such redirections cause an error. -.VS +combination of \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, \fBTCL_STDERR\fR, and +\fBTCL_ENFORCE_MODE\fR. If \fBTCL_STDIN\fR is set, stdin for the first child +in the pipe is the pipe channel, otherwise it is the same as the standard +input of the invoking process; likewise for \fBTCL_STDOUT\fR and +\fBTCL_STDERR\fR. If \fBTCL_ENFORCE_MODE\fR is not set, then the pipe can +redirect stdio handles to override the stdio handles for which +\fBTCL_STDIN\fR, \fBTCL_STDOUT\fR and \fBTCL_STDERR\fR have been set. If it +is set, then such redirections cause an error. +.VS 8.0 .AP ClientData handle in Operating system specific handle for I/O to a file. For Unix this is a file descriptor, for Windows it is a HANDLE. .AP int readOrWrite in OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR to indicate what operations are valid on \fIhandle\fR. +.AP char *channelName in +The name of the channel. .VE .AP int *modePtr out Points at an integer variable that will receive an OR-ed combination of @@ -122,26 +143,40 @@ open for reading and writing. .AP Tcl_Channel channel in A Tcl channel for input or output. Must have been the return value from a procedure such as \fBTcl_OpenFileChannel\fR. -.AP char *buf in -An array of bytes in which to store channel input, or from which -to read channel output. -.AP int len in -The length of the input or output. -.AP int atEnd in -If nonzero, store the input at the end of the input queue, otherwise store -it at the head of the input queue. -.AP int toRead in -The number of bytes to read from the channel. -.AP Tcl_DString *lineRead in -A pointer to a Tcl dynamic string in which to store the line read from the -channel. Must have been initialized by the caller. The line read -will be appended to any data already in the dynamic string. -.AP Tcl_Obj *linePtrObj in +.VS 8.1 br +.AP Tcl_Obj *readObjPtr in/out +A pointer to a Tcl Object in which to store the characters read from the +channel. +.AP int charsToRead in +The number of characters to read from the channel. If the channel's encoding +is \fBbinary\fR, this is equivalent to the number of bytes to read from the +channel. +.AP int appendFlag in +If non-zero, data read from the channel will be appended to the object. +Otherwise, the data will replace the existing contents of the object. +.AP char *readBuf out +A buffer in which to store the bytes read from the channel. +.AP int bytesToRead in +The number of bytes to read from the channel. The buffer \fIreadBuf\fR must +be large enough to hold this many bytes. +.AP Tcl_Obj *lineObjPtr in/out A pointer to a Tcl object in which to store the line read from the channel. The line read will be appended to the current value of the object. -.AP int toWrite in -The number of bytes to read from \fIbuf\fR and output to the channel. +.AP Tcl_DString *lineRead in/out +A pointer to a Tcl dynamic string in which to store the line read from the +channel. Must have been initialized by the caller. The line read will be +appended to any data already in the dynamic string. +.AP Tcl_Obj *writeObjPtr in +A pointer to a Tcl Object whose contents will be output to the channel. +.AP "CONST char" *charBuf in +A buffer containing the characters to output to the channel. +.AP char *byteBuf in +A buffer containing the bytes to output to the channel. +.AP int bytesToWrite in +The number of bytes to consume from \fIcharBuf\fR or \fIbyteBuf\fR and +output to the channel. +.VE .AP int offset in How far to move the access point in the channel at which the next input or output operation will be applied, measured in bytes from the position @@ -158,6 +193,17 @@ Where to store the value of an option or a list of all options and their values. Must have been initialized by the caller. .AP char *newValue in New value for the option given by \fIoptionName\fR. +.VS 8.3 +.AP char *pattern in +The pattern to match on, passed to Tcl_StringMatch, or NULL. +.AP char *input in +The input to add to a channel buffer. +.AP int inputLen in +Length of the input +.AP int addToEnd in +Flag indicating whether the input should be added to the end or +beginning of the channel buffer. +.VE .BE .SH DESCRIPTION @@ -169,7 +215,7 @@ types. The channel mechanism is extensible to new channel types, by providing a low level channel driver for the new type; the channel driver interface is described in the manual entry for \fBTcl_CreateChannel\fR. The -channel mechanism provides a buffering scheme modelled after +channel mechanism provides a buffering scheme modeled after Unix's standard I/O, and it also allows for nonblocking I/O on channels. .PP @@ -182,7 +228,7 @@ channels, see the manual entry for \fBTcl_CreateChannel\fR. .PP \fBTcl_OpenFileChannel\fR opens a file specified by \fIfileName\fR and returns a channel handle that can be used to perform input and output on -the file. This API is modelled after the \fBfopen\fR procedure of +the file. This API is modeled after the \fBfopen\fR procedure of the Unix standard I/O library. The syntax and meaning of all arguments is similar to those given in the Tcl \fBopen\fR command when opening a file. @@ -190,7 +236,7 @@ If an error occurs while opening the channel, \fBTcl_OpenFileChannel\fR returns NULL and records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR. In addition, if \fIinterp\fR is non-NULL, \fBTcl_OpenFileChannel\fR -leaves an error message in \fIinterp->result\fR after any error. +leaves an error message in \fIinterp\fR's result after any error. .PP The newly created channel is not registered in the supplied interpreter; to register it, use \fBTcl_RegisterChannel\fR, described below. @@ -228,7 +274,7 @@ If an error occurs while opening the channel, \fBTcl_OpenCommandChannel\fR returns NULL and records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR. In addition, \fBTcl_OpenCommandChannel\fR leaves an error message in -\fIinterp->result\fR if \fIinterp\fR is not NULL. +the interpreter's result if \fIinterp\fR is not NULL. .PP The newly created channel is not registered in the supplied interpreter; to register it, use \fBTcl_RegisterChannel\fR, described below. @@ -255,6 +301,14 @@ the procedure returns NULL. If the \fImode\fR argument is not NULL, it points at an integer variable that will receive an OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR describing whether the channel is open for reading and writing. +.PP +\fBTcl_GetChannelNames\fR and \fBTcl_GetChannelNamesEx\fR write the +names of the registered channels to the interpreter's result as a +list object. \fBTcl_GetChannelNamesEx\fR will filter these names +according to the \fIpattern\fR. If \fIpattern\fR is NULL, then it +will not do any filtering. The return value is \fBTCL_OK\fR if no +errors occured writing to the result, otherwise it is \fBTCL_ERROR\fR, +and the error message is left in the interpreter's result. .SH TCL_REGISTERCHANNEL .PP @@ -306,97 +360,151 @@ If an error occurs, \fBTcl_Close\fR returns \fBTCL_ERROR\fR and records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR. If the channel is being closed synchronously and an error occurs during closing of the channel and \fIinterp\fR is not NULL, an error message is -left in \fIinterp->result\fR. +left in the interpreter's result. .PP Note: it is not safe to call \fBTcl_Close\fR on a channel that has been registered using \fBTcl_RegisterChannel\fR; see the documentation for -\fBTcl_RegisterChannel\fR, above, for details. If the channel has ever been -given as the \fBchan\fR argument in a call to \fBTcl_RegisterChannel\fR, -you should instead use \fBTcl_UnregisterChannel\fR, which will internally -call \fBTcl_Close\fR when all calls to \fBTcl_RegisterChannel\fR have been -matched by corresponding calls to \fBTcl_UnregisterChannel\fR. +\fBTcl_RegisterChannel\fR, above, for details. If the channel has ever +been given as the \fBchan\fR argument in a call to +\fBTcl_RegisterChannel\fR, you should instead use +\fBTcl_UnregisterChannel\fR, which will internally call \fBTcl_Close\fR +when all calls to \fBTcl_RegisterChannel\fR have been matched by +corresponding calls to \fBTcl_UnregisterChannel\fR. -.SH TCL_READ -.PP -\fBTcl_Read\fR consumes up to \fItoRead\fR bytes of data from -\fIchannel\fR and stores it at \fIbuf\fR. -The return value of \fBTcl_Read\fR is the number of characters written -at \fIbuf\fR. -The buffer produced by \fBTcl_Read\fR is not NULL terminated. Its contents -are valid from the zeroth position up to and excluding the position -indicated by the return value. -If an error occurs, the return value is -1 and \fBTcl_Read\fR records -a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR. -.PP -The return value may be smaller than the value of \fItoRead\fR, indicating -that less data than requested was available, also called a \fIshort -read\fR. -In blocking mode, this can only happen on an end-of-file. -In nonblocking mode, a short read can also occur if there is not -enough input currently available: \fBTcl_Read\fR returns a short -count rather than waiting for more data. -.PP -If the channel is in blocking mode, a return value of zero indicates an end -of file condition. If the channel is in nonblocking mode, a return value of -zero indicates either that no input is currently available or an end of -file condition. Use \fBTcl_Eof\fR and \fBTcl_InputBlocked\fR -to tell which of these conditions actually occurred. -.PP -\fBTcl_Read\fR translates platform-specific end-of-line representations -into the canonical \fB\en\fR internal representation according to the -current end-of-line recognition mode. End-of-line recognition and the -various platform-specific modes are described in the manual entry for the -Tcl \fBfconfigure\fR command. +.VS 8.1 br +.SH "TCL_READCHARS AND TCL_READ" +.PP +\fBTcl_ReadChars\fR consumes bytes from \fIchannel\fR, converting the bytes +to UTF-8 based on the channel's encoding and storing the produced data in +\fIreadObjPtr\fR's string representation. The return value of +\fBTcl_ReadChars\fR is the number of characters, up to \fIcharsToRead\fR, +that were stored in \fIobjPtr\fR. If an error occurs while reading, the +return value is \-1 and \fBTcl_ReadChars\fR records a POSIX error code that +can be retrieved with \fBTcl_GetErrno\fR. +.PP +The return value may be smaller than the value to read, indicating that less +data than requested was available. This is called a \fIshort read\fR. In +blocking mode, this can only happen on an end-of-file. In nonblocking mode, +a short read can also occur if there is not enough input currently +available: \fBTcl_ReadChars\fR returns a short count rather than waiting +for more data. +.PP +If the channel is in blocking mode, a return value of zero indicates an +end-of-file condition. If the channel is in nonblocking mode, a return +value of zero indicates either that no input is currently available or an +end-of-file condition. Use \fBTcl_Eof\fR and \fBTcl_InputBlocked\fR to tell +which of these conditions actually occurred. +.PP +\fBTcl_ReadChars\fR translates the various end-of-line representations into +the canonical \fB\en\fR internal representation according to the current +end-of-line recognition mode. End-of-line recognition and the various +platform-specific modes are described in the manual entry for the Tcl +\fBfconfigure\fR command. +.PP +As a performance optimization, when reading from a channel with the encoding +\fBbinary\fR, the bytes are not converted to UTF-8 as they are read. +Instead, they are stored in \fIreadObjPtr\fR's internal representation as a +byte-array object. The string representation of this object will only be +constructed if it is needed (e.g., because of a call to +\fBTcl_GetStringFromObj\fR). In this way, byte-oriented data can be read +from a channel, manipulated by calling \fBTcl_GetByteArrayFromObj\fR and +related functions, and then written to a channel without the expense of ever +converting to or from UTF-8. +.PP +\fBTcl_Read\fR is similar to \fBTcl_ReadChars\fR, except that it doesn't do +encoding conversions, regardless of the channel's encoding. It is deprecated +and exists for backwards compatibility with non-internationalized Tcl +extensions. It consumes bytes from \fIchannel\fR and stores them in +\fIbuf\fR, performing end-of-line translations on the way. The return value +of \fBTcl_Read\fR is the number of bytes, up to \fItoRead\fR, written in +\fIbuf\fR. The buffer produced by \fBTcl_Read\fR is not NULL terminated. +Its contents are valid from the zeroth position up to and excluding the +position indicated by the return value. -.SH TCL_GETS AND TCL_GETSOBJ -.PP -\fBTcl_Gets\fR reads a line of input from a channel and appends all of -the characters of the line except for the terminating end-of-line character(s) -to the dynamic string given by \fIdsPtr\fR. -The end-of-line character(s) are read and discarded. +.SH "TCL_GETSOBJ AND TCL_GETS" +.PP +\fBTcl_GetsObj\fR consumes bytes from \fIchannel\fR, converting the bytes to +UTF-8 based on the channel's encoding, until a full line of input has been +seen. If the channel's encoding is \fBbinary\fR, each byte read from the +channel is treated as an individual Unicode character. All of the +characters of the line except for the terminating end-of-line character(s) +are appended to \fIlineObjPtr\fR's string representation. The end-of-line +character(s) are read and discarded. +.PP +If a line was successfully read, the return value is greater than or equal +to zero and indicates the number of bytes stored in \fIlineObjPtr\fR. If an +error occurs, \fBTcl_GetsObj\fR returns \-1 and records a POSIX error code +that can be retrieved with \fBTcl_GetErrno\fR. \fBTcl_GetsObj\fR also +returns \-1 if the end of the file is reached; the \fBTcl_Eof\fR procedure +can be used to distinguish an error from an end-of-file condition. +.PP +If the channel is in nonblocking mode, the return value can also be \-1 if +no data was available or the data that was available did not contain an +end-of-line character. When \-1 is returned, the \fBTcl_InputBlocked\fR +procedure may be invoked to determine if the channel is blocked because +of input unavailability. +.PP +\fBTcl_Gets\fR is the same as \fBTcl_GetsObj\fR except the resulting +characters are appended to the appended to the dynamic string given by +\fIdsPtr\fR rather than a Tcl object. + +.SH "TCL_UNGETS" +.PP +\fBTcl_Ungets\fR is used to add data to the input queue of a channel, +at either the head or tail of the queue. \fIInput\fR is a pointer to +the data that is to be added. \fIInputLen\fR gives the length of the +input to add. \fIAddAtEnd\fR, in non-zero, indicates that the data is +to be added at the end of queue; otherwise it will be added at the +head of the queue. If \fIchannel\fR has a "sticky" EOF set, no data will be +added to the input queue. \fBTcl_Ungets\fR returns \fIinputLen\fR or +-1 if an error occurs. + +.SH "TCL_WRITECHARS, TCL_WRITEOBJ, AND TCL_WRITE" .PP -If a line was successfully read, the return value is greater than or -equal to zero, and it indicates the number of characters stored -in the dynamic string. -If an error occurs, \fBTcl_Gets\fR returns -1 and records a POSIX error -code that can be retrieved with \fBTcl_GetErrno\fR. -\fBTcl_Gets\fR also returns -1 if the end of the file is reached; -the \fBTcl_Eof\fR procedure can be used to distinguish an error -from an end-of-file condition. -.PP -If the channel is in nonblocking mode, the return value can also -be -1 if no data was available or the data that was available -did not contain an end-of-line character. -When -1 is returned, the \fBTcl_InputBlocked\fR procedure may be -invoked to determine if the channel is blocked because of input -unavailability. -.PP -\fBTcl_GetsObj\fR is the same as \fBTcl_Gets\fR except the resulting -characters are appended to a Tcl object \fBlineObjPtr\fR rather than a -dynamic string. -.SH TCL_WRITE -.PP -\fBTcl_Write\fR accepts \fItoWrite\fR bytes of data at \fIbuf\fR for output -on \fIchannel\fR. This data may not appear on the output device -immediately. If the data should appear immediately, call \fBTcl_Flush\fR -after the call to \fBTcl_Write\fR, or set the \fB-buffering\fR option on -the channel to \fBnone\fR. If you wish the data to appear as soon as an end -of line is accepted for output, set the \fB\-buffering\fR option on the -channel to \fBline\fR mode. -.PP -The \fItoWrite\fR argument specifies how many bytes of data are provided in -the \fIbuf\fR argument. If it is negative, \fBTcl_Write\fR expects the data +\fBTcl_WriteChars\fR accepts \fIbytesToWrite\fR bytes of character data at +\fIcharBuf\fR. The UTF-8 characters in the buffer are converted to the +channel's encoding and queued for output to \fIchannel\fR. If +\fIbytesToWrite\fR is negative, \fBTcl_WriteChars\fR expects \fIcharBuf\fR to be NULL terminated and it outputs everything up to the NULL. .PP -The return value of \fBTcl_Write\fR is a count of how many -characters were accepted for output to the channel. This is either equal to -\fItoWrite\fR or -1 to indicate that an error occurred. -If an error occurs, \fBTcl_Write\fR also records a POSIX error code -that may be retrieved with \fBTcl_GetErrno\fR. +Data queued for output may not appear on the output device immediately, due +to internal buffering. If the data should appear immediately, call +\fBTcl_Flush\fR after the call to \fBTcl_WriteChars\fR, or set the +\fB\-buffering\fR option on the channel to \fBnone\fR. If you wish the data +to appear as soon as a complete line is accepted for output, set the +\fB\-buffering\fR option on the channel to \fBline\fR mode. +.PP +The return value of \fBTcl_WriteChars\fR is a count of how many bytes were +accepted for output to the channel. This is either greater than zero to +indicate success or \-1 to indicate that an error occurred. If an error +occurs, \fBTcl_WriteChars\fR records a POSIX error code that may be +retrieved with \fBTcl_GetErrno\fR. .PP Newline characters in the output data are translated to platform-specific -end-of-line sequences according to the \fB\-translation\fR option for -the channel. +end-of-line sequences according to the \fB\-translation\fR option for the +channel. This is done even if the channel has no encoding. +.PP +\fBTcl_WriteObj\fR is similar to \fBTcl_WriteChars\fR except it +accepts a Tcl object whose contents will be output to the channel. The +UTF-8 characters in \fIwriteObjPtr\fR's string representation are converted +to the channel's encoding and queued for output to \fIchannel\fR. +As a performance optimization, when writing to a channel with the encoding +\fBbinary\fR, UTF-8 characters are not converted as they are written. +Instead, the bytes in \fIwriteObjPtr\fR's internal representation as a +byte-array object are written to the channel. The byte-array representation +of the object will be constructed if it is needed. In this way, +byte-oriented data can be read from a channel, manipulated by calling +\fBTcl_GetByteArrayFromObj\fR and related functions, and then written to a +channel without the expense of ever converting to or from UTF-8. +.PP +\fBTcl_Write\fR is similar to \fBTcl_WriteChars\fR except that it doesn't do +encoding conversions, regardless of the channel's encoding. It is +deprecated and exists for backwards compatibility with non-internationalized +Tcl extensions. It accepts \fIbytesToWrite\fR bytes of data at +\fIbyteBuf\fR and queues them for output to \fIchannel\fR. If +\fIbytesToWrite\fR is negative, \fBTcl_Write\fR expects \fIbyteBuf\fR to be +NULL terminated and it outputs everything up to the NULL. +.VE .SH TCL_FLUSH .PP @@ -419,14 +527,14 @@ data will be read or written. Buffered output is flushed to the channel and buffered input is discarded, prior to the seek operation. .PP \fBTcl_Seek\fR normally returns the new access point. -If an error occurs, \fBTcl_Seek\fR returns -1 and records a POSIX error +If an error occurs, \fBTcl_Seek\fR returns \-1 and records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR. After an error, the access point may or may not have been moved. .SH TCL_TELL .PP \fBTcl_Tell\fR returns the current access point for a channel. The returned -value is -1 if the channel does not support seeking. +value is \-1 if the channel does not support seeking. .SH TCL_GETCHANNELOPTION .PP @@ -457,7 +565,7 @@ error code. set. The procedure normally returns \fBTCL_OK\fR. If an error occurs, it returns \fBTCL_ERROR\fR; in addition, if \fIinterp\fR is non-NULL, -\fBTcl_SetChannelOption\fR leaves an error message in \fIinterp->result\fR. +\fBTcl_SetChannelOption\fR leaves an error message in the interpreter's result. .SH TCL_EOF .PP @@ -477,7 +585,7 @@ The call always returns zero if the channel is in blocking mode. buffered in the internal buffers for a channel. If the channel is not open for reading, this function always returns zero. -.VS +.VS 8.0 .SH "PLATFORM ISSUES" .PP The handles returned from \fBTcl_GetChannelHandle\fR depend on the @@ -497,3 +605,4 @@ DString(3), fconfigure(n), filename(n), fopen(2), Tcl_CreateChannel(3) .SH KEYWORDS access point, blocking, buffered I/O, channel, channel driver, end of file, flush, input, nonblocking, output, read, seek, write + diff --git a/tcl/doc/OpenTcp.3 b/tcl/doc/OpenTcp.3 index 7d3c997f27f..a16e0de95b2 100644 --- a/tcl/doc/OpenTcp.3 +++ b/tcl/doc/OpenTcp.3 @@ -28,7 +28,7 @@ Tcl_Channel .AS Tcl_ChannelType newClientProcPtr in .AP Tcl_Interp *interp in Tcl interpreter to use for error reporting. If non-NULL and an -error occurs, an error message is left in \fIinterp->result\fR. +error occurs, an error message is left in the interpreter's result. .AP int port in A port number to connect to as a client or to listen on as a server. .AP char *host in @@ -91,7 +91,7 @@ If an error occurs in opening the socket, \fBTcl_OpenTcpClient\fR returns NULL and records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR. In addition, if \fIinterp\fR is non-NULL, an error message -is left in \fIinterp->result\fR. +is left in the interpreter's result. .PP The newly created channel is not registered in the supplied interpreter; to register it, use \fBTcl_RegisterChannel\fR. @@ -143,8 +143,8 @@ connection it can close \fIchannel\fR. representing the server socket. If an error occurs, \fBTcl_OpenTcpServer\fR returns NULL and records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR. -In addition, if \fIinterp->result\fR is non-NULL, an error message -is left in \fIinterp->result\fR. +In addition, if the interpreter is non-NULL, an error message +is left in the interpreter's result. .PP The channel returned by \fBTcl_OpenTcpServer\fR cannot be used for either input or output. @@ -177,3 +177,4 @@ Tcl_OpenFileChannel(3), Tcl_RegisterChannel(3), vwait(n) .SH KEYWORDS client, server, TCP + diff --git a/tcl/doc/ParseCmd.3 b/tcl/doc/ParseCmd.3 new file mode 100644 index 00000000000..a9c0fb2e634 --- /dev/null +++ b/tcl/doc/ParseCmd.3 @@ -0,0 +1,439 @@ +'\" +'\" 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$ +'\" +.so man.macros +.TH Tcl_ParseCommand 3 8.3 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_ParseCommand, Tcl_ParseExpr, Tcl_ParseBraces, Tcl_ParseQuotedString, Tcl_ParseVarName, Tcl_ParseVar, Tcl_FreeParse, Tcl_EvalTokens \- parse Tcl scripts and expressions +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +int +\fBTcl_ParseCommand\fR(\fIinterp, string, numBytes, nested, parsePtr\fR) +.sp +int +\fBTcl_ParseExpr\fR(\fIinterp, string, numBytes, parsePtr\fR) +.sp +int +\fBTcl_ParseBraces\fR(\fIinterp, string, numBytes, parsePtr, append, termPtr\fR) +.sp +int +\fBTcl_ParseQuotedString\fR(\fIinterp, string, numBytes, parsePtr, append, termPtr\fR) +.sp +int +\fBTcl_ParseVarName\fR(\fIinterp, string, numBytes, parsePtr, append\fR) +.sp +char * +\fBTcl_ParseVar\fR(\fIinterp, string, termPtr\fR) +.sp +\fBTcl_FreeParse\fR(\fIusedParsePtr\fR) +.sp +Tcl_Obj * +\fBTcl_EvalTokens\fR(\fIinterp, tokenPtr, numTokens\fR) +.SH ARGUMENTS +.AS Tcl_Interp *usedParsePtr +.AP Tcl_Interp *interp out +For procedures other than \fBTcl_FreeParse\fR and \fBTcl_EvalTokens\fR, +used only for error reporting; +if NULL, then no error messages are left after errors. +For \fBTcl_EvalTokens\fR, determines the context for evaluating the +script and also is used for error reporting; must not be NULL. +.AP char *string in +Pointer to first character in string to parse. +.AP int numBytes in +Number of bytes in \fIstring\fR, not including any terminating null +character. If less than 0 then the script consists of all characters +in \fIstring\fR up to the first null character. +.AP int nested in +Non-zero means that the script is part of a command substitution so an +unquoted close bracket should be treated as a command terminator. If zero, +close brackets have no special meaning. +.AP int append in +Non-zero means that \fI*parsePtr\fR already contains valid tokens; the new +tokens should be appended to those already present. Zero means that +\fI*parsePtr\fR is uninitialized; any information in it is ignored. +This argument is normally 0. +.AP Tcl_Parse *parsePtr out +Points to structure to fill in with information about the parsed +command, expression, variable name, etc. +Any previous information in this structure +is ignored, unless \fIappend\fR is non-zero in a call to +\fBTcl_ParseBraces\fR, \fBTcl_ParseQuotedString\fR, +or \fBTcl_ParseVarName\fR. +.AP char **termPtr out +If not NULL, points to a location where +\fBTcl_ParseBraces\fR, \fBTcl_ParseQuotedString\fR, and +\fBTcl_ParseVar\fR will store a pointer to the character +just after the terminating character (the close-brace, the last +character of the variable name, or the close-quote (respectively)) +if the parse was successful. +.AP Tcl_Parse *usedParsePtr in +Points to structure that was filled in by a previous call to +\fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseVarName\fR, etc. +.BE + +.SH DESCRIPTION +.PP +These procedures parse Tcl commands or portions of Tcl commands such as +expressions or references to variables. +Each procedure takes a pointer to a script (or portion thereof) +and fills in the structure pointed to by \fIparsePtr\fR +with a collection of tokens describing the information that was parsed. +The procedures normally return \fBTCL_OK\fR. +However, if an error occurs then they return \fBTCL_ERROR\fR, +leave an error message in \fIinterp's\fR result +(if \fIinterp\fR is not NULL), +and leave nothing in \fIparsePtr\fR. +.PP +\fBTcl_ParseCommand\fR is a procedure that parses Tcl +scripts. Given a pointer to a script, it +parses the first command from the script. If the command was parsed +successfully, \fBTcl_ParseCommand\fR returns \fBTCL_OK\fR and fills in the +structure pointed to by \fIparsePtr\fR with information about the +structure of the command (see below for details). +If an error occurred in parsing the command then +\fBTCL_ERROR\fR is returned, an error message is left in \fIinterp\fR's +result, and no information is left at \fI*parsePtr\fR. +.PP +\fBTcl_ParseExpr\fR parses Tcl expressions. +Given a pointer to a script containing an expression, +\fBTcl_ParseCommand\fR parses the expression. +If the expression was parsed successfully, +\fBTcl_ParseExpr\fR returns \fBTCL_OK\fR and fills in the +structure pointed to by \fIparsePtr\fR with information about the +structure of the expression (see below for details). +If an error occurred in parsing the command then +\fBTCL_ERROR\fR is returned, an error message is left in \fIinterp\fR's +result, and no information is left at \fI*parsePtr\fR. +.PP +\fBTcl_ParseBraces\fR parses a string or command argument +enclosed in braces such as +\fB{hello}\fR or \fB{string \\t with \\t tabs}\fR +from the beginning of its argument \fIstring\fR. +The first character of \fIstring\fR must be \fB{\fR. +If the braced string was parsed successfully, +\fBTcl_ParseBraces\fR returns \fBTCL_OK\fR, +fills in the structure pointed to by \fIparsePtr\fR +with information about the structure of the string +(see below for details), +and stores a pointer to the character just after the terminating \fB}\fR +in the location given by \fI*termPtr\fR. +If an error occurrs while parsing the string +then \fBTCL_ERROR\fR is returned, +an error message is left in \fIinterp\fR's result, +and no information is left at \fI*parsePtr\fR or \fI*termPtr\fR. +.PP +\fBTcl_ParseQuotedString\fR parses a double-quoted string such as +\fB"sum is [expr $a+$b]"\fR +from the beginning of the argument \fIstring\fR. +The first character of \fIstring\fR must be \fB"\fR. +If the double-quoted string was parsed successfully, +\fBTcl_ParseQuotedString\fR returns \fBTCL_OK\fR, +fills in the structure pointed to by \fIparsePtr\fR +with information about the structure of the string +(see below for details), +and stores a pointer to the character just after the terminating \fB"\fR +in the location given by \fI*termPtr\fR. +If an error occurrs while parsing the string +then \fBTCL_ERROR\fR is returned, +an error message is left in \fIinterp\fR's result, +and no information is left at \fI*parsePtr\fR or \fI*termPtr\fR. +.PP +\fBTcl_ParseVarName\fR parses a Tcl variable reference such as +\fB$abc\fR or \fB$x([expr $index + 1])\fR from the beginning of its +\fIstring\fR argument. +The first character of \fIstring\fR must be \fB$\fR. +If a variable name was parsed successfully, \fBTcl_ParseVarName\fR +returns \fBTCL_OK\fR and fills in the structure pointed to by +\fIparsePtr\fR with information about the structure of the variable name +(see below for details). If an error +occurrs while parsing the command then \fBTCL_ERROR\fR is returned, an +error message is left in \fIinterp\fR's result (if \fIinterp\fR isn't +NULL), and no information is left at \fI*parsePtr\fR. +.PP +\fBTcl_ParseVar\fR parse a Tcl variable reference such as \fB$abc\fR +or \fB$x([expr $index + 1])\fR from the beginning of its \fIstring\fR +argument. The first character of \fIstring\fR must be \fB$\fR. If +the variable name is parsed successfully, \fBTcl_ParseVar\fR returns a +pointer to the string value of the variable. If an error occurs while +parsing, then NULL is returned and an error message is left in +\fIinterp\fR's result. +.PP +The information left at \fI*parsePtr\fR +by \fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR, +\fBTcl_ParseQuotedString\fR, and \fBTcl_ParseVarName\fR +may include dynamically allocated memory. +If these five parsing procedures return \fBTCL_OK\fR +then the caller must invoke \fBTcl_FreeParse\fR to release +the storage at \fI*parsePtr\fR. +These procedures ignore any existing information in +\fI*parsePtr\fR (unless \fIappend\fR is non-zero), +so if repeated calls are being made to any of them +then \fBTcl_FreeParse\fR must be invoked once after each call. +.PP +\fBTcl_EvalTokens\fR evaluates a sequence of parse tokens from a Tcl_Parse +structure. The tokens typically consist +of all the tokens in a word or all the tokens that make up the index for +a reference to an array variable. \fBTcl_EvalTokens\fR performs the +substitutions requested by the tokens, concatenates the +resulting values, and returns the result in a new Tcl_Obj. The +reference count of the object returned as result has been +incremented, so the caller must +invoke \fBTcl_DecrRefCount\fR when it is finished with the object. +If an error occurs while evaluating the tokens (such as a reference to +a non-existent variable) then the return value is NULL and an error +message is left in \fIinterp\fR's result. + +.SH "TCL_PARSE STRUCTURE" +.PP +\fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR, +\fBTcl_ParseQuotedString\fR, and \fBTcl_ParseVarName\fR +return parse information in two data structures, Tcl_Parse and Tcl_Token: +.CS +typedef struct Tcl_Parse { + char *\fIcommentStart\fR; + int \fIcommentSize\fR; + char *\fIcommandStart\fR; + int \fIcommandSize\fR; + int \fInumWords\fR; + Tcl_Token *\fItokenPtr\fR; + int \fInumTokens\fR; + ... +} Tcl_Parse; + +typedef struct Tcl_Token { + int \fItype\fR; + char *\fIstart\fR; + int \fIsize\fR; + int \fInumComponents\fR; +} Tcl_Token; +.CE +.PP +The first five fields of a Tcl_Parse structure +are filled in only by \fBTcl_ParseCommand\fR. +These fields are not used by the other parsing procedures. +.PP +\fBTcl_ParseCommand\fR fills in a Tcl_Parse structure +with information that describes one Tcl command and any comments that +precede the command. +If there are comments, +the \fIcommentStart\fR field points to the \fB#\fR character that begins +the first comment and \fIcommentSize\fR indicates the number of bytes +in all of the comments preceding the command, including the newline +character that terminates the last comment. +If the command is not preceded by any comments, \fIcommentSize\fR is 0. +\fBTcl_ParseCommand\fR also sets the \fIcommandStart\fR field +to point to the first character of the first +word in the command (skipping any comments and leading space) and +\fIcommandSize\fR gives the total number of bytes in the command, +including the character pointed to by \fIcommandStart\fR up to and +including the newline, close bracket, or semicolon character that +terminates the command. The \fInumWords\fR field gives the +total number of words in the command. +.PP +All parsing procedures set the remaining fields, +\fItokenPtr\fR and \fInumTokens\fR. +The \fItokenPtr\fR field points to the first in an array of Tcl_Token +structures that describe the components of the entity being parsed. +The \fInumTokens\fR field gives the total number of tokens +present in the array. +Each token contains four fields. +The \fItype\fR field selects one of several token types +that are described below. The \fIstart\fR field +points to the first character in the token and the \fIsize\fR field +gives the total number of characters in the token. Some token types, +such as \fBTCL_TOKEN_WORD\fR and \fBTCL_TOKEN_VARIABLE\fR, consist of +several component tokens, which immediately follow the parent token; +the \fInumComponents\fR field describes how many of these there are. +The \fItype\fR field has one of the following values: +.TP 20 +\fBTCL_TOKEN_WORD\fR +This token ordinarily describes one word of a command +but it may also describe a quoted or braced string in an expression. +The token describes a component of the script that is +the result of concatenating together a sequence of subcomponents, +each described by a separate subtoken. +The token starts with the first non-blank +character of the component (which may be a double-quote or open brace) +and includes all characters in the component up to but not including the +space, semicolon, close bracket, close quote, or close brace that +terminates the component. The \fInumComponents\fR field counts the total +number of sub-tokens that make up the word, including sub-tokens +of \fBTCL_TOKEN_VARIABLE\fR and \fBTCL_TOKEN_BS\fR tokens. +.TP +\fBTCL_TOKEN_SIMPLE_WORD\fR +This token has the same meaning as \fBTCL_TOKEN_WORD\fR, except that +the word is guaranteed to consist of a single \fBTCL_TOKEN_TEXT\fR +sub-token. The \fInumComponents\fR field is always 1. +.TP +\fBTCL_TOKEN_TEXT\fR +The token describes a range of literal text that is part of a word. +The \fInumComponents\fR field is always 0. +.TP +\fBTCL_TOKEN_BS\fR +The token describes a backslash sequence such as \fB\en\fR or \fB\e0xa3\fR. +The \fInumComponents\fR field is always 0. +.TP +\fBTCL_TOKEN_COMMAND\fR +The token describes a command whose result result must be substituted into +the word. The token includes the square brackets that surround the +command. The \fInumComponents\fR field is always 0 (the nested command +is not parsed; call \fBTcl_ParseCommand\fR recursively if you want to +see its tokens). +.TP +\fBTCL_TOKEN_VARIABLE\fR +The token describes a variable substitution, including the +\fB$\fR, variable name, and array index (if there is one) up through the +close parenthesis that terminates the index. This token is followed +by one or more additional tokens that describe the variable name and +array index. If \fInumComponents\fR is 1 then the variable is a +scalar and the next token is a \fBTCL_TOKEN_TEXT\fR token that gives the +variable name. If \fInumComponents\fR is greater than 1 then the +variable is an array: the first sub-token is a \fBTCL_TOKEN_TEXT\fR +token giving the array name and the remaining sub-tokens are +\fBTCL_TOKEN_TEXT\fR, \fBTCL_TOKEN_BS\fR, \fBTCL_TOKEN_COMMAND\fR, and +\fBTCL_TOKEN_VARIABLE\fR tokens that must be concatenated to produce the +array index. The \fInumComponents\fR field includes nested sub-tokens +that are part of \fBTCL_TOKEN_VARIABLE\fR tokens in the array index. +.TP +\fBTCL_TOKEN_SUB_EXPR\fR +The token describes one subexpression of an expression +(or an entire expression). +A subexpression may consist of a value +such as an integer literal, variable substitution, +or parenthesized subexpression; +it may also consist of an operator and its operands. +The token starts with the first non-blank character of the subexpression +up to but not including the space, brace, close-paren, or bracket +that terminates the subexpression. +This token is followed by one or more additional tokens +that describe the subexpression. +If the first sub-token after the \fBTCL_TOKEN_SUB_EXPR\fR token +is a \fBTCL_TOKEN_OPERATOR\fR token, +the subexpression consists of an operator and its token operands. +If the operator has no operands, the subexpression consists of +just the \fBTCL_TOKEN_OPERATOR\fR token. +Each operand is described by a \fBTCL_TOKEN_SUB_EXPR\fR token. +Otherwise, the subexpression is a value described by +one of the token types \fBTCL_TOKEN_WORD\fR, \fBTCL_TOKEN_TEXT\fR, +\fBTCL_TOKEN_BS\fR, \fBTCL_TOKEN_COMMAND\fR, +\fBTCL_TOKEN_VARIABLE\fR, and \fBTCL_TOKEN_SUB_EXPR\fR. +The \fInumComponents\fR field +counts the total number of sub-tokens that make up the subexpression; +this includes the sub-tokens for any nested \fBTCL_TOKEN_SUB_EXPR\fR tokens. +.TP +\fBTCL_TOKEN_OPERATOR\fR +The token describes one operator of an expression +such as \fB&&\fR or \fBhypot\fR. +An \fBTCL_TOKEN_OPERATOR\fR token is always preceeded by a +\fBTCL_TOKEN_SUB_EXPR\fR token +that describes the operator and its operands; +the \fBTCL_TOKEN_SUB_EXPR\fR token's \fInumComponents\fR field +can be used to determine the number of operands. +A binary operator such as \fB*\fR +is followed by two \fBTCL_TOKEN_SUB_EXPR\fR tokens +that describe its operands. +A unary operator like \fB-\fR +is followed by a single \fBTCL_TOKEN_SUB_EXPR\fR token +for its operand. +If the operator is a math function such as \fBlog10\fR, +the \fBTCL_TOKEN_OPERATOR\fR token will give its name and +the following \fBTCL_TOKEN_SUB_EXPR\fR tokens will describe +its operands; +if there are no operands (as with \fBrand\fR), +no \fBTCL_TOKEN_SUB_EXPR\fR tokens follow. +There is one trinary operator, \fB?\fR, +that appears in if-then-else subexpressions +such as \fIx\fB?\fIy\fB:\fIz\fR; +in this case, the \fB?\fR \fBTCL_TOKEN_OPERATOR\fR token +is followed by three \fBTCL_TOKEN_SUB_EXPR\fR tokens for the operands +\fIx\fR, \fIy\fR, and \fIz\fR. +The \fInumComponents\fR field for a \fBTCL_TOKEN_OPERATOR\fR token +is always 0. +.PP +After \fBTcl_ParseCommand\fR returns, the first token pointed to by +the \fItokenPtr\fR field of the +Tcl_Parse structure always has type \fBTCL_TOKEN_WORD\fR or +\fBTCL_TOKEN_SIMPLE_WORD\fR. It is followed by the sub-tokens +that must be concatenated to produce the value of that word. +The next token is the \fBTCL_TOKEN_WORD\fR or \fBTCL_TOKEN_SIMPLE_WORD\fR +token for the second word, followed by sub-tokens for that +word, and so on until all \fInumWords\fR have been accounted +for. +.PP +After \fBTcl_ParseExpr\fR returns, the first token pointed to by +the \fItokenPtr\fR field of the +Tcl_Parse structure always has type \fBTCL_TOKEN_SUB_EXPR\fR. +It is followed by the sub-tokens that must be evaluated +to produce the value of the expression. +Only the token information in the Tcl_Parse structure +is modified: the \fIcommentStart\fR, \fIcommentSize\fR, +\fIcommandStart\fR, and \fIcommandSize\fR fields are not modified +by \fBTcl_ParseExpr\fR. +.PP +After \fBTcl_ParseBraces\fR returns, +the array of tokens pointed to by the \fItokenPtr\fR field of the +Tcl_Parse structure will contain a single \fBTCL_TOKEN_TEXT\fR token +if the braced string does not contain any backslash-newlines. +If the string does contain backslash-newlines, +the array of tokens will contain one or more +\fBTCL_TOKEN_TEXT\fR or \fBTCL_TOKEN_BS\fR sub-tokens +that must be concatenated to produce the value of the string. +If the braced string was just \fB{}\fR +(that is, the string was empty), +the single \fBTCL_TOKEN_TEXT\fR token will have a \fIsize\fR field +containing zero; +this ensures that at least one token appears +to describe the braced string. +Only the token information in the Tcl_Parse structure +is modified: the \fIcommentStart\fR, \fIcommentSize\fR, +\fIcommandStart\fR, and \fIcommandSize\fR fields are not modified +by \fBTcl_ParseBraces\fR. +.PP +After \fBTcl_ParseQuotedString\fR returns, +the array of tokens pointed to by the \fItokenPtr\fR field of the +Tcl_Parse structure depends on the contents of the quoted string. +It will consist of one or more \fBTCL_TOKEN_TEXT\fR, \fBTCL_TOKEN_BS\fR, +\fBTCL_TOKEN_COMMAND\fR, and \fBTCL_TOKEN_VARIABLE\fR sub-tokens. +The array always contains at least one token; +for example, if the argument \fIstring\fR is empty, +the array returned consists of a single \fBTCL_TOKEN_TEXT\fR token +with a zero \fIsize\fR field. +Only the token information in the Tcl_Parse structure +is modified: the \fIcommentStart\fR, \fIcommentSize\fR, +\fIcommandStart\fR, and \fIcommandSize\fR fields are not modified. +.PP +After \fBTcl_ParseVarName\fR returns, the first token pointed to by +the \fItokenPtr\fR field of the +Tcl_Parse structure always has type \fBTCL_TOKEN_VARIABLE\fR. It +is followed by the sub-tokens that make up the variable name as +described above. The total length of the variable name is +contained in the \fIsize\fR field of the first token. +As in \fBTcl_ParseExpr\fR, +only the token information in the Tcl_Parse structure +is modified by \fBTcl_ParseVarName\fR: +the \fIcommentStart\fR, \fIcommentSize\fR, +\fIcommandStart\fR, and \fIcommandSize\fR fields are not modified. +.PP +All of the character pointers in the +Tcl_Parse and Tcl_Token structures refer +to characters in the \fIstring\fR argument passed to +\fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR, +\fBTcl_ParseQuotedString\fR, and \fBTcl_ParseVarName\fR. +.PP +There are additional fields in the Tcl_Parse structure after the +\fInumTokens\fR field, but these are for the private use of +\fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR, +\fBTcl_ParseQuotedString\fR, and \fBTcl_ParseVarName\fR; they should not be +referenced by code outside of these procedures. + +.SH KEYWORDS +backslash substitution, braces, command, expression, parse, token, variable substitution + diff --git a/tcl/doc/PkgRequire.3 b/tcl/doc/PkgRequire.3 index 30ef5bea84e..e797c51f1dd 100644 --- a/tcl/doc/PkgRequire.3 +++ b/tcl/doc/PkgRequire.3 @@ -10,7 +10,7 @@ .TH Tcl_PkgRequire 3 7.5 Tcl "Tcl Library Procedures" .BS .SH NAME -Tcl_PkgRequire, Tcl_PkgProvide \- package version control +Tcl_PkgRequire, Tcl_PkgRequireEx, Tcl_PkgPresent, Tcl_PkgPresentEx, Tcl_PkgProvide, Tcl_PkgProvideEx \- package version control .SH SYNOPSIS .nf \fB#include \fR @@ -18,10 +18,22 @@ Tcl_PkgRequire, Tcl_PkgProvide \- package version control char * \fBTcl_PkgRequire\fR(\fIinterp, name, version, exact\fR) .sp +char * +\fBTcl_PkgRequireEx\fR(\fIinterp, name, version, exact, clientDataPtr\fR) +.sp +char * +\fBTcl_PkgPresent\fR(\fIinterp, name, version, exact\fR) +.sp +char * +\fBTcl_PkgPresentEx\fR(\fIinterp, name, version, exact, clientDataPtr\fR) +.sp int \fBTcl_PkgProvide\fR(\fIinterp, name, version\fR) +.sp +int +\fBTcl_PkgProvideEx\fR(\fIinterp, name, version, clientData\fR) .SH ARGUMENTS -.AS Tcl_FreeProc clientData +.AS Tcl_FreeProc clientDataPtr .AP Tcl_Interp *interp in Interpreter where package is needed or available. .AP char *name in @@ -35,25 +47,42 @@ Non-zero means that only the particular version specified by Zero means that newer versions than \fIversion\fR are also acceptable as long as they have the same major version number as \fIversion\fR. +.AP ClientData clientData in +Arbitrary value to be associated with the package. +.AP ClientData *clientDataPtr out +Pointer to place to store the value associated with the matching +package. It is only changed if the pointer is not NULL and the +function completed successfully. .BE .SH DESCRIPTION .PP These procedures provide C-level interfaces to Tcl's package and version management facilities. +.PP \fBTcl_PkgRequire\fR is equivalent to the \fBpackage require\fR +command, \fBTcl_PkgPresent\fR is equivalent to the \fBpackage present\fR command, and \fBTcl_PkgProvide\fR is equivalent to the \fBpackage provide\fR command. +.PP See the documentation for the Tcl commands for details on what these procedures do. -If \fBTcl_PkgRequire\fR completes successfully it returns a pointer -to the version string for the version of the package that is provided -in the interpreter (which may be different than \fIversion\fR); if -an error occurs it returns NULL and leaves an error message in -\fIinterp->result\fR. +.PP +If \fBTcl_PkgPresent\fR or \fBTcl_PkgRequire\fR complete successfully +they return a pointer to the version string for the version of the package +that is provided in the interpreter (which may be different than +\fIversion\fR); if an error occurs they return NULL and leave an error +message in the interpreter's result. +.PP \fBTcl_PkgProvide\fR returns TCL_OK if it completes successfully; if an error occurs it returns TCL_ERROR and leaves an error message -in \fIinterp->result\fR. +in the interpreter's result. +.PP +\fBTcl_PkgProvideEx\fR, \fBTcl_PkgPresentEx\fR and \fBTcl_PkgRequireEx\fR +allow the setting and retrieving of the client data associated with +the package. In all other respects they are equivalent to the matching +functions. .SH KEYWORDS -package, provide, require, version +package, present, provide, require, version + diff --git a/tcl/doc/RecEvalObj.3 b/tcl/doc/RecEvalObj.3 index 4697a886817..d3b301da4a0 100644 --- a/tcl/doc/RecEvalObj.3 +++ b/tcl/doc/RecEvalObj.3 @@ -33,15 +33,15 @@ the command at global level instead of the current stack level. .SH DESCRIPTION .PP \fBTcl_RecordAndEvalObj\fR is invoked to record a command as an event -on the history list and then execute it using \fBTcl_EvalObj\fR +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_EvalObj\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_EvalObj\fR instead of \fBTcl_RecordAndEvalObj\fR. +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. @@ -49,7 +49,8 @@ If the \fIflags\fR argument contains the TCL_NO_EVAL bit then the command is recorded without being evaluated. .SH "SEE ALSO" -Tcl_EvalObj, Tcl_GetObjResult +Tcl_EvalObjEx, Tcl_GetObjResult .SH KEYWORDS command, event, execute, history, interpreter, object, record + diff --git a/tcl/doc/RecordEval.3 b/tcl/doc/RecordEval.3 index 9cbba275f7c..6a52832542b 100644 --- a/tcl/doc/RecordEval.3 +++ b/tcl/doc/RecordEval.3 @@ -36,7 +36,7 @@ the command at global level instead of the current stack level. on the history list and then execute it using \fBTcl_Eval\fR (or \fBTcl_GlobalEval\fR if the TCL_EVAL_GLOBAL bit is set in \fIflags\fR). It returns a completion code such as TCL_OK just like \fBTcl_Eval\fR -and it leaves information in \fIinterp->result\fR. +and it leaves information in the interpreter's result. If you don't want the command recorded on the history list then you should invoke \fBTcl_Eval\fR instead of \fBTcl_RecordAndEval\fR. Normally \fBTcl_RecordAndEval\fR is only called with top-level @@ -55,3 +55,4 @@ Tcl_RecordAndEvalObj .SH KEYWORDS command, event, execute, history, interpreter, record + diff --git a/tcl/doc/RegExp.3 b/tcl/doc/RegExp.3 index 4aabc933a55..a9774546249 100644 --- a/tcl/doc/RegExp.3 +++ b/tcl/doc/RegExp.3 @@ -1,6 +1,7 @@ '\" '\" 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. @@ -8,15 +9,18 @@ '\" RCS: @(#) $Id$ '\" .so man.macros -.TH Tcl_RegExpMatch 3 7.4 Tcl "Tcl Library Procedures" +.TH Tcl_RegExpMatch 3 8.1 Tcl "Tcl Library Procedures" .BS .SH NAME -Tcl_RegExpMatch, Tcl_RegExpCompile, Tcl_RegExpExec, Tcl_RegExpRange \- Pattern matching with regular expressions +Tcl_RegExpMatch, Tcl_RegExpCompile, Tcl_RegExpExec, Tcl_RegExpRange, Tcl_GetRegExpFromObj, Tcl_RegExpMatchObj, Tcl_RegExpExecObj, Tcl_RegExpGetInfo \- Pattern matching with regular expressions .SH SYNOPSIS .nf \fB#include \fR .sp int +\fBTcl_RegExpMatchObj\fR(\fIinterp\fR, \fIstrObj\fR, \fIpatObj\fR) +.sp +int \fBTcl_RegExpMatch\fR(\fIinterp\fR, \fIstring\fR, \fIpattern\fR) .sp Tcl_RegExp @@ -26,17 +30,38 @@ int \fBTcl_RegExpExec\fR(\fIinterp\fR, \fIregexp\fR, \fIstring\fR, \fIstart\fR) .sp \fBTcl_RegExpRange\fR(\fIregexp\fR, \fIindex\fR, \fIstartPtr\fR, \fIendPtr\fR) +.VS 8.1 +.sp +Tcl_RegExp +\fBTcl_GetRegExpFromObj\fR(\fIinterp\fR, \fIpatObj\fR, \fIcflags\fR) +.sp +int +\fBTcl_RegExpExecObj\fR(\fIinterp\fR, \fIregexp\fR, \fIobjPtr\fR, \fIoffset\fR, \fInmatches\fR, \fIeflags\fR) +.sp +\fBTcl_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. +Tcl interpreter to use for error reporting. The interpreter may be +NULL if no error reporting is desired. +.VS 8.1 +.AP Tcl_Obj *strObj in/out +Refers to the object from which to get the string to search. The +internal representation of the object may be converted to a form that +can be efficiently searched. +.AP Tcl_Obj *patObj in/out +Refers to the object from which to get a regular expression. The +compiled regular expression is cached in the object. +.VE 8.1 .AP char *string in String to check for a match with a regular expression. .AP char *pattern in String in the form of a regular expression pattern. .AP Tcl_RegExp regexp in Compiled regular expression. Must have been returned previously -by \fBTcl_RegExpCompile\fR. +by \fBTcl_GetRegExpFromObj\fR or \fBTcl_RegExpCompile\fR. .AP char *start in If \fIstring\fR is just a portion of some other string, this argument identifies the beginning of the larger string. @@ -52,19 +77,50 @@ NULL if there is no such range. .AP char **endPtr out The address of the character just after the last one in the range is stored here, or NULL if there is no such range. +.VS 8.1 +.AP int cflags in +OR-ed combination of compilation flags. See below for more information. +.AP Tcl_Obj *objPtr in/out +An object which contains the string to check for a match with a +regular expression. +.AP int offset in +The character offset into the string where matching should begin. +The value of the offset has no impact on \fB^\fR matches. This +behavior is controlled by \fIeflags\fR. +.AP int nmatches in +The number of matching subexpressions that should be remembered for +later use. If this value is 0, then no subexpression match +information will be computed. If the value is -1, then +all of the matching subexpressions will be remembered. Any other +value will be taken as the maximum number of subexpressions to +remember. +.AP int eflags in +OR-ed combination of the values TCL_REG_NOTBOL and TCL_REG_NOTEOL. +See below for more information. +.AP Tcl_RegExpInfo *infoPtr out +The address of the location where information about a previous match +should be stored by \fBTcl_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 -as a regular expression using the same rules as for the -\fBregexp\fR Tcl command. +as a regular expression using the rules in the \fBre_syntax\fR +reference page. If there is a match then \fBTcl_RegExpMatch\fR returns 1. If there is no match then \fBTcl_RegExpMatch\fR returns 0. If an error occurs in the matching process (e.g. \fIpattern\fR is not a valid regular expression) then \fBTcl_RegExpMatch\fR -returns \-1 and leaves an error message in \fIinterp->result\fR. +returns \-1 and leaves an error message in the interpreter result. +.VS 8.1.2 +\fBTcl_RegExpMatchObj\fR is similar to \fBTcl_RegExpMatch\fR except it +operates on the Tcl objects \fIstrObj\fR and \fIpatObj\fR instead of +UTF strings. +\fBTcl_RegExpMatchObj\fR is generally more efficient than +\fBTcl_RegExpMatch\fR, so it is the preferred interface. +.VE 8.1.2 .PP \fBTcl_RegExpCompile\fR, \fBTcl_RegExpExec\fR, and \fBTcl_RegExpRange\fR provide lower-level access to the regular expression pattern matcher. @@ -74,7 +130,7 @@ The return value is a token for this compiled form, which can be used in subsequent calls to \fBTcl_RegExpExec\fR or \fBTcl_RegExpRange\fR. If an error occurs while compiling the regular expression then \fBTcl_RegExpCompile\fR returns NULL and leaves an error message -in \fIinterp->result\fR. +in the interpreter result. Note: the return value from \fBTcl_RegExpCompile\fR is only valid up to the next call to \fBTcl_RegExpCompile\fR; it is not safe to retain these values for long periods of time. @@ -84,7 +140,7 @@ It returns 1 if \fIstring\fR contains a range of characters that match \fIregexp\fR, 0 if no match is found, and \-1 if an error occurs. In the case of an error, \fBTcl_RegExpExec\fR leaves an error -message in \fIinterp->result\fR. +message in the interpreter result. When searching a string for multiple matches of a pattern, it is important to distinguish between the start of the original string and the start of the current search. @@ -111,6 +167,181 @@ 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: +.RS 2 +.TP +\fBTCL_REG_ADVANCED\fR +Compile advanced regular expressions (`AREs'). This mode corresponds to +the normal regular expression syntax accepted by the Tcl regexp and +regsub commands. +.TP +\fBTCL_REG_EXTENDED\fR +Compile extended regular expressions (`EREs'). This mode corresponds +to the regular expression syntax recognized by Tcl 8.0 and earlier +versions. +.TP +\fBTCL_REG_BASIC\fR +Compile basic regular expressions (`BREs'). This mode corresponds +to the regular expression syntax recognized by common Unix utilities +like \fBsed\fR and \fBgrep\fR. This is the default if no flags are +specified. +.TP +\fBTCL_REG_EXPANDED\fR +Compile the regular expression (basic, extended, or advanced) using an +expanded syntax that allows comments and whitespace. This mode causes +non-backslashed non-bracket-expression white +space and #-to-end-of-line comments to be ignored. +.TP +\fBTCL_REG_QUOTE\fR +Compile a literal string, with all characters treated as ordinary characters. +.TP +\fBTCL_REG_NOCASE\fR +Compile for matching that ignores upper/lower case distinctions. +.TP +\fBTCL_REG_NEWLINE\fR +Compile for newline-sensitive matching. By default, newline is a +completely ordinary character with no special meaning in either +regular expressions or strings. With this flag, `[^' bracket +expressions and `.' never match newline, `^' matches an empty string +after any newline in addition to its normal function, and `$' matches +an empty string before any newline in addition to its normal function. +\fBREG_NEWLINE\fR is the bitwise OR of \fBREG_NLSTOP\fR and +\fBREG_NLANCH\fR. +.TP +\fBTCL_REG_NLSTOP\fR +Compile for partial newline-sensitive matching, +with the behavior of +`[^' bracket expressions and `.' affected, +but not the behavior of `^' and `$'. In this mode, `[^' bracket +expressions and `.' never match newline. +.TP +\fBTCL_REG_NLANCH\fR +Compile for inverse partial newline-sensitive matching, +with the behavior of +of `^' and `$' (the ``anchors'') affected, but not the behavior of +`[^' bracket expressions and `.'. In this mode `^' matches an empty string +after any newline in addition to its normal function, and `$' matches +an empty string before any newline in addition to its normal function. +.TP +\fBTCL_REG_NOSUB\fR +Compile for matching that reports only success or failure, +not what was matched. This reduces compile overhead and may improve +performance. Subsequent calls to \fBTcl_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 +Only one of +\fBTCL_REG_EXTENDED\fR, +\fBTCL_REG_ADVANCED\fR, +\fBTCL_REG_BASIC\fR, and +\fBTCL_REG_QUOTE\fR may be specified. +.PP +\fBTcl_RegExpExecObj\fR executes the regular expression pattern +matcher. It returns 1 if \fIobjPtr\fR contains a range of characters +that match \fIregexp\fR, 0 if no match is found, and \-1 if an error +occurs. In the case of an error, \fBTcl_RegExpExecObj\fR leaves an +error message in the interpreter result. The \fInmatches\fR value +indicates to the matcher how many subexpressions are of interest. If +\fInmatches\fR is 0, then no subexpression match information is +recorded, which may allow the matcher to make various optimizations. +If the value is -1, then all of the subexpressions in the pattern are +remembered. If the value is a positive integer, then only that number +of subexpressions will be remembered. Matching begins at the +specified Unicode character index given by \fIoffset\fR. Unlike +\fBTcl_RegExpExec\fR, the behavior of anchors is not affected by the +offset value. Instead the behavior of the anchors is explicitly +controlled by the \fIeflags\fR argument, which is a bitwise OR of +zero or more of the following flags: +.RS 2 +.TP +\fBTCL_REG_NOTBOL\fR +The starting character will not be treated as the beginning of a +line or the beginning of the string, so `^' will not match there. +Note that this flag has no effect on how `\fB\eA\fR' matches. +.TP +\fBTCL_REG_NOTEOL\fR +The last character in the string will not be treated as the end of a +line or the end of the string, so '$' will not match there. +Note that this flag has no effect on how `\fB\eZ\fR' matches. +.RE +.PP +\fBTcl_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; + Tcl_RegExpIndices *\fImatches\fR; + long \fIextendStart\fR; +} Tcl_RegExpInfo; +.CE +.PP +The \fInsubs\fR field contains a count of the number of parenthesized +subexpressions within the regular expression. If the \fBTCL_REG_NOSUB\fR +was used, then this value will be zero. The \fImatches\fR field +points to an array of \fInsubs\fR values that indicate the bounds of each +subexpression matched. The first element in the array refers to the +range matched by the entire regular expression, and subsequent elements +refer to the parenthesized subexpressions in the order that they +appear in the pattern. Each element is a structure that is defined as +follows: +.PP +.CS +typedef struct Tcl_RegExpIndices { + long \fIstart\fR; + long \fIend\fR; +} Tcl_RegExpIndices; +.CE +.PP +The \fIstart\fR and \fIend\fR values are Unicode character indices +relative to the offset location within \fIobjPtr\fR where matching began. +The \fIstart\fR index identifies the first character of the matched +subexpression. The \fIend\fR index identifies the first character +after the matched subexpression. If the subexpression matched the +empty string, then \fIstart\fR and \fIend\fR will be equal. If the +subexpression did not participate in the match, then \fIstart\fR and +\fIend\fR will be set to -1. +.PP +The \fIextendStart\fR field in \fBTcl_RegExpInfo\fR is only set if the +\fBTCL_REG_CANMATCH\fR flag was used. It indicates the first +character in the string where a match could occur. If a match was +found, this will be the same as the beginning of the current match. +If no match was found, then it indicates the earliest point at which a +match might occur if additional text is appended to the string. +.VE 8.1 +.SH "SEE ALSO" +re_syntax(n) .SH KEYWORDS -match, pattern, regular expression, string, subexpression +match, pattern, regular expression, string, subexpression, Tcl_RegExpIndices, Tcl_RegExpInfo + diff --git a/tcl/doc/SaveResult.3 b/tcl/doc/SaveResult.3 new file mode 100644 index 00000000000..ba6e257f175 --- /dev/null +++ b/tcl/doc/SaveResult.3 @@ -0,0 +1,65 @@ +'\" +'\" Copyright (c) 1997 by Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id$ +'\" +.so man.macros +.TH Tcl_SaveResult 3 8.1 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_SaveResult, Tcl_RestoreResult, Tcl_DiscardResult \- save and restore an interpreter's result +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +\fBTcl_SaveResult(\fIinterp, statePtr\fB)\fR +.sp +\fBTcl_RestoreResult(\fIinterp, statePtr\fB)\fR +.sp +\fBTcl_DiscardResult(\fIstatePtr\fB)\fR +.SH ARGUMENTS +.AS Tcl_SavedResult statePtr +.AP Tcl_Interp *interp in +Interpreter for which state should be saved. +.AP Tcl_SavedResult *statePtr in +Pointer to location where interpreter result should be saved or restored. +.BE + +.SH DESCRIPTION +.PP +These routines allows a C procedure to take a snapshot of the current +interpreter result so that it can be restored after a call +to \fBTcl_Eval\fR or some other routine that modifies the interpreter +result. These routines are passed a pointer to a structure that is +used to store enough information to restore the interpreter result +state. This structure can be allocated on the stack of the calling +procedure. These routines do not save the state of any error +information in the interpreter (e.g. the \fBerrorCode\fR or +\fBerrorInfo\fR variables). +.PP +\fBTcl_SaveResult\fR moves the string and object results +of \fIinterp\fR into the location specified by \fIstatePtr\fR. +\fBTcl_SaveResult\fR clears the result for \fIinterp\fR and +leaves the result in its normal empty initialized state. +.PP +\fBTcl_RestoreResult\fR moves the string and object results from +\fIstatePtr\fR back into \fIinterp\fR. Any result or error that was +already in the interpreter will be cleared. The \fIstatePtr\fR is left +in an uninitialized state and cannot be used until another call to +\fBTcl_SaveResult\fR. +.PP +\fBTcl_DiscardResult\fR releases the saved interpreter state +stored at \fBstatePtr\fR. The state structure is left in an +uninitialized state and cannot be used until another call to +\fBTcl_SaveResult\fR. +.PP +Once \fBTcl_SaveResult\fR is called to save the interpreter +result, either \fBTcl_RestoreResult\fR or +\fBTcl_DiscardResult\fR must be called to properly clean up the +memory associated with the saved state. + +.SH KEYWORDS +result, state, interp diff --git a/tcl/doc/SetErrno.3 b/tcl/doc/SetErrno.3 index 2385c484036..a764ed558ec 100644 --- a/tcl/doc/SetErrno.3 +++ b/tcl/doc/SetErrno.3 @@ -6,10 +6,10 @@ '\" '\" RCS: @(#) $Id$ .so man.macros -.TH Tcl_SetErrno 3 7.5 Tcl "Tcl Library Procedures" +.TH Tcl_SetErrno 3 8.3 Tcl "Tcl Library Procedures" .BS .SH NAME -Tcl_SetErrno, Tcl_GetErrno \- manipulate errno to store and retrieve error codes +Tcl_SetErrno, Tcl_GetErrno, Tcl_ErrnoId, Tcl_ErrnoMsg \- manipulate errno to store and retrieve error codes .SH SYNOPSIS .nf \fB#include \fR @@ -20,6 +20,12 @@ void int \fBTcl_GetErrno\fR() .sp +char * +\fBTcl_ErrnoId\fR() +.sp +char * +\fBTcl_ErrnoMsg\fR() +.sp .SH ARGUMENTS .AS Tcl_Interp *errorCode in .AP int errorCode in @@ -43,6 +49,13 @@ via \fBerrno\fR should call \fBTcl_SetErrno\fR rather than setting \fBTcl_GetErrno\fR returns the current value of \fBerrno\fR. Procedures wishing to access \fBerrno\fR should call this procedure instead of accessing \fBerrno\fR directly. +.PP +\fBTcl_ErrnoId\fR and \fBTcl_ErrnoMsg\fR return a string +representation of the current \fBerrno\fR value. \fBTcl_ErrnoId\fR +returns a machine-readable textual identifier such as +"EACCES". \fBTcl_ErrnoMsg\fR returns a human-readable string such as +"permission denied". The strings returned by these functions are +statically allocated and the caller must not free or modify them. .SH KEYWORDS errno, error code, global variables diff --git a/tcl/doc/SetRecLmt.3 b/tcl/doc/SetRecLmt.3 index 33ab852f35c..164782378eb 100644 --- a/tcl/doc/SetRecLmt.3 +++ b/tcl/doc/SetRecLmt.3 @@ -41,7 +41,7 @@ allowable nesting depth for an interpreter. The \fIdepth\fR argument specifies a new limit for \fIinterp\fR, and \fBTcl_SetRecursionLimit\fR returns the old limit. To read out the old limit without modifying it, invoke -\fBTcl_SetRecursionDepth\fR with \fIdepth\fR equal to 0. +\fBTcl_SetRecursionLimit\fR with \fIdepth\fR equal to 0. .PP The \fBTcl_SetRecursionLimit\fR only sets the size of the Tcl call stack: it cannot by itself prevent stack overflows on the diff --git a/tcl/doc/SetResult.3 b/tcl/doc/SetResult.3 index 918843c1224..6a571ceee3d 100644 --- a/tcl/doc/SetResult.3 +++ b/tcl/doc/SetResult.3 @@ -8,10 +8,10 @@ '\" RCS: @(#) $Id$ '\" .so man.macros -.TH Tcl_SetResult 3 7.5 Tcl "Tcl Library Procedures" +.TH Tcl_SetResult 3 8.0 Tcl "Tcl Library Procedures" .BS .SH NAME -Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult, Tcl_AppendResult, Tcl_AppendElement, Tcl_ResetResult \- manipulate Tcl result +Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult, Tcl_AppendResult, Tcl_AppendResultVA, Tcl_AppendElement, Tcl_ResetResult, Tcl_FreeResult \- manipulate Tcl result .SH SYNOPSIS .nf \fB#include \fR @@ -28,6 +28,8 @@ char * .sp \fBTcl_AppendResult\fR(\fIinterp, string, string, ... , \fB(char *) NULL\fR) .sp +\fBTcl_AppendResultVA\fR(\fIinterp, argList\fR) +.sp \fBTcl_AppendElement\fR(\fIinterp, string\fR) .sp \fBTcl_ResetResult\fR(\fIinterp\fR) @@ -46,6 +48,9 @@ appended to the existing result. Address of procedure to call to release storage at \fIstring\fR, or \fBTCL_STATIC\fR, \fBTCL_DYNAMIC\fR, or \fBTCL_VOLATILE\fR. +.AP va_list argList in +An argument list which must have been initialised using +\fBTCL_VARARGS_START\fR, and cleared using \fBva_end\fR. .BE .SH DESCRIPTION @@ -112,7 +117,7 @@ and the result is left as a empty string. \fBTcl_AddErrorInfo\fR, \fBTcl_AddObjErrorInfo\fR, and \fBTcl_SetErrorCode\fR. -.SH OLD STRING PROCEDURES +.SH "OLD STRING PROCEDURES" .PP Use of the following procedures is deprecated since they manipulate the Tcl result as a string. @@ -137,6 +142,9 @@ to a string, if necessary, before appending the argument strings. Any number of \fIstring\fR arguments may be passed in a single call; the last argument in the list must be a NULL pointer. .PP +\fBTcl_AppendResultVA\fR is the same as \fBTcl_AppendResult\fR except that +instead of taking a variable number of arguments it takes an argument list. +.PP \fBTcl_AppendElement\fR is similar to \fBTcl_AppendResult\fR in that it allows results to be built up in pieces. However, \fBTcl_AppendElement\fR takes only a single \fIstring\fR @@ -162,7 +170,7 @@ change \fIinterp->result\fR or clear error state. \fBTcl_FreeResult\fR is most commonly used when a procedure is about to replace one result value with another. -.SH DIRECT ACCESS TO INTERP->RESULT IS DEPRECATED +.SH "DIRECT ACCESS TO INTERP->RESULT IS DEPRECATED" .PP It used to be legal for programs to directly read and write \fIinterp->result\fR @@ -173,7 +181,7 @@ Programs should always read the result using the procedures \fBTcl_GetObjResult\fR or \fBTcl_GetStringResult\fR, and write the result using \fBTcl_SetObjResult\fR or \fBTcl_SetResult\fR. -.SH THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT +.SH "THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT" .PP \fBTcl_SetResult\fR's \fIfreeProc\fR argument specifies how the Tcl system is to manage the storage for the \fIstring\fR argument. @@ -215,3 +223,4 @@ Tcl_AddErrorInfo, Tcl_CreateObjCommand, Tcl_SetErrorCode, Tcl_Interp .SH KEYWORDS append, command, element, list, object, result, return value, interpreter + diff --git a/tcl/doc/SetVar.3 b/tcl/doc/SetVar.3 index 7de2f44651d..ce2b4ed7a62 100644 --- a/tcl/doc/SetVar.3 +++ b/tcl/doc/SetVar.3 @@ -8,90 +8,155 @@ '\" RCS: @(#) $Id$ '\" .so man.macros -.TH Tcl_SetVar 3 7.4 Tcl "Tcl Library Procedures" +.TH Tcl_SetVar 3 8.1 Tcl "Tcl Library Procedures" .BS .SH NAME -Tcl_SetVar, Tcl_SetVar2, Tcl_GetVar, Tcl_GetVar2, Tcl_UnsetVar, Tcl_UnsetVar2 \- manipulate Tcl variables +Tcl_SetVar2Ex, Tcl_SetVar, Tcl_SetVar2, Tcl_ObjSetVar2, Tcl_GetVar2Ex, Tcl_GetVar, Tcl_GetVar2, Tcl_ObjGetVar2, Tcl_UnsetVar, Tcl_UnsetVar2 \- manipulate Tcl variables .SH SYNOPSIS .nf \fB#include \fR .sp +.VS 8.1 +Tcl_Obj * +\fBTcl_SetVar2Ex\fR(\fIinterp, name1, name2, newValuePtr, flags\fR) +.VE +.sp char * \fBTcl_SetVar\fR(\fIinterp, varName, newValue, flags\fR) .sp char * \fBTcl_SetVar2\fR(\fIinterp, name1, name2, newValue, flags\fR) .sp +Tcl_Obj * +\fBTcl_ObjSetVar2\fR(\fIinterp, part1Ptr, part2Ptr, newValuePtr, flags\fR) +.sp +.VS 8.1 +Tcl_Obj * +\fBTcl_GetVar2Ex\fR(\fIinterp, name1, name2, flags\fR) +.VE +.sp char * \fBTcl_GetVar\fR(\fIinterp, varName, flags\fR) .sp char * \fBTcl_GetVar2\fR(\fIinterp, name1, name2, flags\fR) .sp +Tcl_Obj * +\fBTcl_ObjGetVar2\fR(\fIinterp, part1Ptr, part2Ptr, flags\fR) +.sp int \fBTcl_UnsetVar\fR(\fIinterp, varName, flags\fR) .sp int \fBTcl_UnsetVar2\fR(\fIinterp, name1, name2, flags\fR) .SH ARGUMENTS -.AS Tcl_Interp *newValue +.AS Tcl_Interp *newValuePtr .AP Tcl_Interp *interp in Interpreter containing variable. +.AP char *name1 in +Contains the name of an array variable (if \fIname2\fR is non-NULL) +or (if \fIname2\fR is NULL) either the name of a scalar variable +or a complete name including both variable name and index. +May include \fB::\fR namespace qualifiers +to specify a variable in a particular namespace. +.AP char *name2 in +If non-NULL, gives name of element within array; in this +case \fIname1\fR must refer to an array variable. +.AP Tcl_Obj *newValuePtr in +.VS 8.1 +Points to a Tcl object containing the new value for the variable. +.VE +.AP int flags in +OR-ed combination of bits providing additional information. See below +for valid values. .AP char *varName in Name of variable. -May include a series of \fB::\fR namespace qualifiers +May include \fB::\fR namespace qualifiers to specify a variable in a particular namespace. May refer to a scalar variable or an element of -an array variable. -If the name references an element of an array, then it +an array. +If the name references an element of an array, then the name must be in writable memory: Tcl will make temporary modifications to it while looking up the name. .AP char *newValue in -New value for variable. -.AP int flags in -OR-ed combination of bits providing additional information for -operation. See below for valid values. -.AP char *name1 in -Name of scalar variable, or name of array variable if \fIname2\fR -is non-NULL. -May include a series of \fB::\fR namespace qualifiers +New value for variable, specified as a NULL-terminated string. +A copy of this value is stored in the variable. +.AP Tcl_Obj *part1Ptr in +Points to a Tcl object containing the variable's name. +The name may include a series of \fB::\fR namespace qualifiers to specify a variable in a particular namespace. -.AP char *name2 in -If non-NULL, gives name of element within array and \fIname1\fR -must refer to an array variable. +May refer to a scalar variable or an element of an array variable. +.AP Tcl_Obj *part2Ptr in +If non-NULL, points to an object containing the name of an element +within an array and \fIpart1Ptr\fR must refer to an array variable. .BE .SH DESCRIPTION .PP -These procedures may be used to create, modify, read, and delete +These procedures are used to create, modify, read, and delete Tcl variables from C code. .PP -Note that \fBTcl_GetVar\fR and \fBTcl_SetVar\fR -have been largely replaced by the -object-based procedures \fBTcl_ObjGetVar2\fR and \fBTcl_ObjSetVar2\fR. -Those object-based procedures read, modify, and create -a variable whose name is held in a Tcl object instead of a string. -They also return a pointer to the object -which is the variable's value instead of returning a string. -Operations on objects can be faster since objects -hold an internal representation that can be manipulated more efficiently. -.PP -\fBTcl_SetVar\fR and \fBTcl_SetVar2\fR +.VS 8.1 +\fBTcl_SetVar2Ex\fR, \fBTcl_SetVar\fR, \fBTcl_SetVar2\fR, and +\fBTcl_ObjSetVar2\fR will create a new variable or modify an existing one. -Both of these procedures set the given variable to the value -given by \fInewValue\fR, and they return a pointer to a -copy of the variable's new value, which is stored in Tcl's +These procedures set the given variable to the value +given by \fInewValuePtr\fR or \fInewValue\fR and return a +pointer to the variable's new value, which is stored in Tcl's variable structure. -Tcl keeps a private copy of the variable's value, so the caller -may change \fInewValue\fR after these procedures return without -affecting the value of the variable. +\fBTcl_SetVar2Ex\fR and \fBTcl_ObjSetVar2\fR take the new value as a +Tcl_Obj and return +a pointer to a Tcl_Obj. \fBTcl_SetVar\fR and \fBTcl_SetVar2\fR +take the new value as a string and return a string; they are +usually less efficient than \fBTcl_ObjSetVar2\fR. Note that the +return value may be different than the \fInewValuePtr\fR or +.VE +\fInewValue\fR argument, due to modifications made by write traces. If an error occurs in setting the variable (e.g. an array -variable is referenced without giving an index into the array), -they return NULL. +variable is referenced without giving an index into the array) +NULL is returned and an error message is left in \fIinterp\fR's +result if the \fBTCL_LEAVE_ERR_MSG\fR \fIflag\fR bit is set. +.PP +.VS 8.1 +\fBTcl_GetVar2Ex\fR, \fBTcl_GetVar\fR, \fBTcl_GetVar2\fR, and +\fBTcl_ObjGetVar2\fR +return the current value of a variable. +The arguments to these procedures are treated in the same way +as the arguments to the procedures described above. +Under normal circumstances, the return value is a pointer +to the variable's value. For \fBTcl_GetVar2Ex\fR and +\fBTcl_ObjGetVar2\fR the value is +returned as a pointer to a Tcl_Obj. For \fBTcl_GetVar\fR and +\fBTcl_GetVar2\fR the value is returned as a string; this is +usually less efficient, so \fBTcl_GetVar2Ex\fR or \fBTcl_ObjGetVar2\fR +are preferred. +.VE +If an error occurs while reading the variable (e.g. the variable +doesn't exist or an array element is specified for a scalar +variable), then NULL is returned and an error message is left +in \fIinterp\fR's result if the \fBTCL_LEAVE_ERR_MSG\fR \fIflag\fR +bit is set. .PP -The name of the variable may be specified to -\fBTcl_SetVar\fR and \fBTcl_SetVar2\fR in either of two ways. -If \fBTcl_SetVar\fR is called, the variable name is given as +\fBTcl_UnsetVar\fR and \fBTcl_UnsetVar2\fR may be used to remove +a variable, so that future attempts to read the variable will return +an error. +The arguments to these procedures are treated in the same way +as the arguments to the procedures above. +If the variable is successfully removed then TCL_OK is returned. +If the variable cannot be removed because it doesn't exist then +TCL_ERROR is returned and an error message is left +in \fIinterp\fR's result if the \fBTCL_LEAVE_ERR_MSG\fR \fIflag\fR +bit is set. +If an array element is specified, the given element is removed +but the array remains. +If an array name is specified without an index, then the entire +array is removed. +.PP +The name of a variable may be specified to these procedures in +four ways: +.IP [1] +If \fBTcl_SetVar\fR, \fBTcl_GetVar\fR, or \fBTcl_UnsetVar\fR +is invoked, the variable name is given as a single string, \fIvarName\fR. If \fIvarName\fR contains an open parenthesis and ends with a close parenthesis, then the value between the parentheses is @@ -100,22 +165,31 @@ the characters before the first open parenthesis are treated as the name of an array variable. If \fIvarName\fR doesn't have parentheses as described above, then the entire string is treated as the name of a scalar variable. -If \fBTcl_SetVar2\fR is called, then the array name and index -have been separated by the caller into two separate strings, -\fIname1\fR and \fIname2\fR respectively; if \fIname2\fR is -zero it means that a scalar variable is being referenced. +.IP [2] +If the \fIname1\fR and \fIname2\fR arguments are provided and +\fIname2\fR is non-NULL, then an array element is specified and +the array name and index have +already been separated by the caller: \fIname1\fR contains the +name and \fIname2\fR contains the index. +.VS 8.1 +An error is generated +if \fIname1\fR contains an open parenthesis and ends with a +close parenthesis (array element) and \fIname2\fR is non-NULL. +.IP [3] +If \fIname2\fR is NULL, \fIname1\fR is treated just like +\fIvarName\fR in case [1] above (it can be either a scalar or an array +element variable name). +.VE .PP The \fIflags\fR argument may be used to specify any of several options to the procedures. It consists of an OR-ed combination of the following bits. -Note that the flag bit TCL_PARSE_PART1 is only meaningful -for the procedures Tcl_SetVar2 and Tcl_GetVar2. .TP \fBTCL_GLOBAL_ONLY\fR -Under normal circumstances the procedures look up variables as follows: +Under normal circumstances the procedures look up variables as follows. If a procedure call is active in \fIinterp\fR, -a variable is looked up at the current level of procedure call. -Otherwise, a variable is looked up first in the current namespace, +the variable is looked up at the current level of procedure call. +Otherwise, the variable is looked up first in the current namespace, then in the global namespace. However, if this bit is set in \fIflags\fR then the variable is looked up only in the global namespace @@ -124,14 +198,10 @@ If both \fBTCL_GLOBAL_ONLY\fR and \fBTCL_NAMESPACE_ONLY\fR are given, \fBTCL_GLOBAL_ONLY\fR is ignored. .TP \fBTCL_NAMESPACE_ONLY\fR -Under normal circumstances the procedures look up variables as follows: -If a procedure call is active in \fIinterp\fR, -a variable is looked up at the current level of procedure call. -Otherwise, a variable is looked up first in the current namespace, -then in the global namespace. -However, if this bit is set in \fIflags\fR then the variable -is looked up only in the current namespace -even if there is a procedure call active. +If this bit is set in \fIflags\fR then the variable +is looked up only in the current namespace; if a procedure is active +its variables are ignored, and the global namespace is also ignored unless +it is the current namespace. .TP \fBTCL_LEAVE_ERR_MSG\fR If an error is returned and this bit is set in \fIflags\fR, then @@ -142,9 +212,10 @@ If this flag bit isn't set then no error message is left and the interpreter's result will not be modified. .TP \fBTCL_APPEND_VALUE\fR -If this bit is set then \fInewValue\fR is appended to the current -value, instead of replacing it. -If the variable is currently undefined, then this bit is ignored. +If this bit is set then \fInewValuePtr\fR or \fInewValue\fR is +appended to the current value instead of replacing it. +If the variable is currently undefined, then the bit is ignored. +This bit is only used by the \fBTcl_Set*\fR procedures. .TP \fBTCL_LIST_ELEMENT\fR If this bit is set, then \fInewValue\fR is converted to a valid @@ -153,18 +224,6 @@ A separator space is appended before the new list element unless the list element is going to be the first element in a list or sublist (i.e. the variable's current value is empty, or contains the single character ``{'', or ends in `` }''). -.TP -\fBTCL_PARSE_PART1\fR -If this bit is set when calling \fITcl_SetVar2\fR and \fITcl_GetVar2\fR, -\fIname1\fR may contain both an array and an element name: -if the name contains an open parenthesis and ends with a -close parenthesis, then the value between the parentheses is -treated as an element name (which can have any string value) and -the characters before the first open -parenthesis are treated as the name of an array variable. -If the flag TCL_PARSE_PART1 is given, -\fIname2\fR should be NULL since the array and element names -are taken from \fIname1\fR. .PP \fBTcl_GetVar\fR and \fBTcl_GetVar2\fR return the current value of a variable. @@ -178,8 +237,6 @@ or \fBTcl_SetVar2\fR). and TCL_LEAVE_ERR_MSG, both of which have the same meaning as for \fBTcl_SetVar\fR. -In addition, \fBTcl_GetVar2\fR uses the bit TCL_PARSE_PART1, -which has the same meaning as for \fBTcl_SetVar2\fR. If an error occurs in reading the variable (e.g. the variable doesn't exist or an array element is specified for a scalar variable), then NULL is returned. @@ -198,7 +255,7 @@ If an array name is specified without an index, then the entire array is removed. .SH "SEE ALSO" -Tcl_GetObjResult, Tcl_GetStringResult, Tcl_ObjGetVar2, Tcl_ObjSetVar2, Tcl_TraceVar +Tcl_GetObjResult, Tcl_GetStringResult, Tcl_TraceVar .SH KEYWORDS -array, interpreter, object, scalar, set, unset, variable +array, get variable, interpreter, object, scalar, set, unset, variable diff --git a/tcl/doc/SourceRCFile.3 b/tcl/doc/SourceRCFile.3 new file mode 100644 index 00000000000..8991763fafb --- /dev/null +++ b/tcl/doc/SourceRCFile.3 @@ -0,0 +1,38 @@ +'\" +'\" Copyright (c) 1998-2000 by Scriptics Corporation. +'\" All rights reserved. +'\" +'\" RCS: @(#) $Id$ +'\" +'\" +.so man.macros +.TH Tcl_SourceRCFile 3 8.3 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_SourceRCFile \- source the Tcl rc file +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +void +\fBTcl_SourceRCFile\fR(\fIinterp\fR) +.SH ARGUMENTS +.AP Tcl_Interp *interp in +Tcl interpreter to source rc file into. +.BE + +.SH DESCRIPTION +.PP +\fBTcl_SourceRCFile\fR is used to source the Tcl rc file at startup. +It is typically invoked by Tcl_Main or Tk_Main. The name of the file +sourced is obtained from the global variable \fBtcl_rcFileName\fR in +the interpreter given by \fIinterp\fR. If this variable is not +defined, or if the file it indicates cannot be found, no action is +taken. +.PP +On the Macintosh, after sourcing the rc file, this function will +additionally source the TEXT resource indicated by the global variable +\fBtcl_rcRsrcName\fR in \fIinterp\fR. + +.SH KEYWORDS +application-specific initialization, main program, rc file diff --git a/tcl/doc/SplitList.3 b/tcl/doc/SplitList.3 index 8db202d2117..0dd0c023ab0 100644 --- a/tcl/doc/SplitList.3 +++ b/tcl/doc/SplitList.3 @@ -8,10 +8,10 @@ '\" RCS: @(#) $Id$ '\" .so man.macros -.TH Tcl_SplitList 3 7.5 Tcl "Tcl Library Procedures" +.TH Tcl_SplitList 3 8.0 Tcl "Tcl Library Procedures" .BS .SH NAME -Tcl_SplitList, Tcl_Merge, Tcl_ScanElement, Tcl_ConvertElement \- manipulate Tcl lists +Tcl_SplitList, Tcl_Merge, Tcl_ScanElement, Tcl_ConvertElement, Tcl_ScanCountedElement, Tcl_ConvertCountedElement \- manipulate Tcl lists .SH SYNOPSIS .nf \fB#include \fR @@ -24,26 +24,20 @@ char * .sp int \fBTcl_ScanElement\fR(\fIsrc, flagsPtr\fR) -.VS .sp int \fBTcl_ScanCountedElement\fR(\fIsrc, length, flagsPtr\fR) -.VE .sp int \fBTcl_ConvertElement\fR(\fIsrc, dst, flags\fR) -.VS .sp int \fBTcl_ConvertCountedElement\fR(\fIsrc, length, dst, flags\fR) -.VE .SH ARGUMENTS .AS Tcl_Interp ***argvPtr .AP Tcl_Interp *interp out -.VS Interpreter to use for error reporting. If NULL, then no error message is left. -.VE .AP char *list in Pointer to a string with proper list structure. .AP int *argcPtr out @@ -63,10 +57,8 @@ String that is to become an element of a list. .AP int *flagsPtr in Pointer to word to fill in with information about \fIsrc\fR. The value of *\fIflagsPtr\fR must be passed to \fBTcl_ConvertElement\fR. -.VS .AP int length in Number of bytes in string \fIsrc\fR. -.VE .AP char *dst in Place to copy converted list element. Must contain enough characters to hold converted string. @@ -99,19 +91,15 @@ code = Tcl_SplitList(interp, string, &argc, &argv); .CE Then you should eventually free the storage with a call like the following: -.VS .CS Tcl_Free((char *) argv); .CE -.VE .PP \fBTcl_SplitList\fR normally returns \fBTCL_OK\fR, which means the list was successfully parsed. If there was a syntax error in \fIlist\fR, then \fBTCL_ERROR\fR is returned -and \fIinterp->result\fR will point to an error message describing the -.VS +and the interpreter's result will point to an error message describing the problem (if \fIinterp\fR was not NULL). -.VE If \fBTCL_ERROR\fR is returned then no memory is allocated and \fI*argvPtr\fR is not modified. .PP @@ -126,11 +114,9 @@ it will be parsed into \fIargc\fR words whose values will be the same as the \fIargv\fR strings passed to \fBTcl_Merge\fR. \fBTcl_Merge\fR will modify the list elements with braces and/or backslashes in order to produce proper Tcl list structure. -.VS The result string is dynamically allocated using \fBTcl_Alloc\fR; the caller must eventually release the space using \fBTcl_Free\fR. -.VE .PP If the result of \fBTcl_Merge\fR is passed to \fBTcl_SplitList\fR, the elements returned by \fBTcl_SplitList\fR will be identical to @@ -180,12 +166,11 @@ used to generate a portion of an argument for a Tcl command. In this case, surrounding \fIsrc\fR with curly braces would cause the command not to be parsed correctly. .PP -.VS \fBTcl_ScanCountedElement\fR and \fBTcl_ConvertCountedElement\fR are the same as \fBTcl_ScanElement\fR and \fBTcl_ConvertElement\fR, except the length of string \fIsrc\fR is specified by the \fIlength\fR argument, and the string may contain embedded nulls. -.VE .SH KEYWORDS backslash, convert, element, list, merge, split, strings + diff --git a/tcl/doc/StaticPkg.3 b/tcl/doc/StaticPkg.3 index f5295d215bb..d19d2f15642 100644 --- a/tcl/doc/StaticPkg.3 +++ b/tcl/doc/StaticPkg.3 @@ -57,14 +57,14 @@ following prototype: .CS typedef int Tcl_PackageInitProc(Tcl_Interp *\fIinterp\fR); .CE -The \fIinterp\fR argument identifies the interpreter in which the -package is to be loaded. The initialization procedure must return -\fBTCL_OK\fR or \fBTCL_ERROR\fR to indicate whether or not it completed -successfully; in the event of an error it should set \fIinterp->result\fR -to point to an error message. -The result or error from the initialization procedure will be returned -as the result of the \fBload\fR command that caused the +The \fIinterp\fR argument identifies the interpreter in which the package +is to be loaded. The initialization procedure must return \fBTCL_OK\fR or +\fBTCL_ERROR\fR to indicate whether or not it completed successfully; in +the event of an error it should set the interpreter's result to point to an +error message. The result or error from the initialization procedure will +be returned as the result of the \fBload\fR command that caused the initialization procedure to be invoked. .SH KEYWORDS initialization procedure, package, static linking + diff --git a/tcl/doc/StrMatch.3 b/tcl/doc/StrMatch.3 index ea17d0b17f1..f291d96823c 100644 --- a/tcl/doc/StrMatch.3 +++ b/tcl/doc/StrMatch.3 @@ -8,22 +8,31 @@ '\" RCS: @(#) $Id$ '\" .so man.macros -.TH Tcl_StringMatch 3 "" Tcl "Tcl Library Procedures" +.TH Tcl_StringMatch 3 8.1 Tcl "Tcl Library Procedures" .BS .SH NAME -Tcl_StringMatch \- test whether a string matches a pattern +Tcl_StringMatch, Tcl_StringCaseMatch \- test whether a string matches a pattern .SH SYNOPSIS .nf \fB#include \fR .sp int \fBTcl_StringMatch\fR(\fIstring\fR, \fIpattern\fR) +.VS 8.1 +.sp +\fBTcl_StringCaseMatch\fR(\fIstring, pattern, nocase\fR) +.VE 8.1 .SH ARGUMENTS .AP char *string in String to test. .AP char *pattern in Pattern to match against string. May contain special characters from the set *?\e[]. +.VS 8.1 +.AP int nocase in +Specifies whether the match should be done case-sensitive (0) or +case-insensitive (1). +.VE 8.1 .BE .SH DESCRIPTION @@ -34,6 +43,13 @@ a given pattern. If it does, then \fBTcl_StringMatch\fR returns used for matching is the same algorithm used in the ``string match'' Tcl command and is similar to the algorithm used by the C-shell for file name matching; see the Tcl manual entry for details. +.VS 8.1 +.PP +In \fBTcl_StringCaseMatch\fR, the algorithm is the same, but you have +the option to make the matching case-insensitive. If you choose this +(by passing \fBnocase\fR as 1), then the string and pattern are +essentially matched in the lower case. +.VE 8.1 .SH KEYWORDS match, pattern, string diff --git a/tcl/doc/StringObj.3 b/tcl/doc/StringObj.3 index e3766ca5284..1d366b6135a 100644 --- a/tcl/doc/StringObj.3 +++ b/tcl/doc/StringObj.3 @@ -7,32 +7,74 @@ '\" RCS: @(#) $Id$ '\" .so man.macros -.TH Tcl_StringObj 3 8.0 Tcl "Tcl Library Procedures" +.TH Tcl_StringObj 3 8.1 Tcl "Tcl Library Procedures" .BS .SH NAME -Tcl_NewStringObj, Tcl_SetStringObj, Tcl_GetStringFromObj, Tcl_AppendToObj, Tcl_AppendStringsToObj, Tcl_SetObjLength, TclConcatObj \- manipulate Tcl objects as strings +Tcl_NewStringObj, Tcl_NewUnicodeObj, Tcl_SetStringObj, Tcl_SetUnicodeObj, Tcl_GetStringFromObj, Tcl_GetString, Tcl_GetUnicode, Tcl_GetUniChar, Tcl_GetCharLength, Tcl_GetRange, Tcl_AppendToObj, Tcl_AppendUnicodeToObj, Tcl_AppendStringsToObj, Tcl_AppendStringsToObjVA, Tcl_AppendObjToObj, Tcl_SetObjLength, Tcl_ConcatObj \- manipulate Tcl objects as strings .SH SYNOPSIS .nf \fB#include \fR .sp Tcl_Obj * \fBTcl_NewStringObj\fR(\fIbytes, length\fR) +.VS 8.1.2 .sp +Tcl_Obj * +\fBTcl_NewUnicodeObj\fR(\fIunicode, numChars\fR) +.VE +.sp +void \fBTcl_SetStringObj\fR(\fIobjPtr, bytes, length\fR) +.VS 8.1.2 +.sp +void +\fBTcl_SetUnicodeObj\fR(\fIobjPtr, unicode, numChars\fR) +.VE .sp char * \fBTcl_GetStringFromObj\fR(\fIobjPtr, lengthPtr\fR) .sp +char * +\fBTcl_GetString\fR(\fIobjPtr\fR) +.VS 8.1.2 +.sp +Tcl_UniChar * +\fBTcl_GetUnicode\fR(\fIobjPtr\fR) +.sp +Tcl_UniChar +\fBTcl_GetUniChar\fR(\fIobjPtr, index\fR) +.sp +int +\fBTcl_GetCharLength\fR(\fIobjPtr\fR) +.sp +Tcl_Obj * +\fBTcl_GetRange\fR(\fIobjPtr, first, last\fR) +.VE +.sp +void \fBTcl_AppendToObj\fR(\fIobjPtr, bytes, length\fR) +.VS 8.1.2 +.sp +void +\fBTcl_AppendUnicodeToObj\fR(\fIobjPtr, unicode, numChars\fR) +.VE .sp +void +\fBTcl_AppendObjToObj\fR(\fIobjPtr, appendObjPtr\fR) +.sp +void \fBTcl_AppendStringsToObj\fR(\fIobjPtr, string, string, ... \fB(char *) NULL\fR) .sp +void +\fBTcl_AppendStringsToObjVA\fR(\fIobjPtr, argList\fR) +.sp +void \fBTcl_SetObjLength\fR(\fIobjPtr, newLength\fR) .sp Tcl_Obj * \fBTcl_ConcatObj\fR(\fIobjc, objv\fR) .SH ARGUMENTS -.AS Tcl_Interp *lengthPtr out +.AS Tcl_Interp *appendObjPtr in/out .AP char *bytes in Points to the first byte of an array of bytes used to set or append to a string object. @@ -42,13 +84,37 @@ unless \fIlength\fR is negative. The number of bytes to copy from \fIbytes\fR when initializing, setting, or appending to a string object. If negative, all bytes up to the first null are used. +.AP Tcl_UniChar *unicode in +Points to the first byte of an array of Unicode characters +used to set or append to a string object. +This byte array may contain embedded null characters +unless \fInumChars\fR is negative. +.VS 8.1.2 +.AP int numChars in +The number of Unicode characters to copy from \fIunicode\fR when +initializing, setting, or appending to a string object. +If negative, all characters up to the first null character are used. +.AP int index in +The index of the Unicode character to return. +.AP int first in +The index of the first Unicode character in the Unicode range to be +returned as a new object. +.AP int last in +The index of the last Unicode character in the Unicode range to be +returned as a new object. +.VE .AP Tcl_Obj *objPtr in/out Points to an object to manipulate. +.AP Tcl_Obj *appendObjPtr in +The object to append to \fIobjPtr\fR in \fBTcl_AppendObjToObj\fR. .AP int *lengthPtr out If non-NULL, the location where \fBTcl_GetStringFromObj\fR will store the the length of an object's string representation. .AP char *string in Null-terminated string value to append to \fIobjPtr\fR. +.AP va_list argList in +An argument list which must have been initialised using +\fBTCL_VARARGS_START\fR, and cleared using \fBva_end\fR. .AP int newLength in New length for the string value of \fIobjPtr\fR, not including the final NULL character. @@ -66,31 +132,75 @@ of the object to store additional information to make the string manipulations more efficient. In particular, they make a series of append operations efficient by allocating extra storage space for the string so that it doesn't have to be copied for each append. +.VS 8.1.2 +Also, indexing and length computations are optimized because the +Unicode string representation is calculated and cached as needed. +.VE .PP +.VS 8.1.2 \fBTcl_NewStringObj\fR and \fBTcl_SetStringObj\fR create a new object -or modify an existing object to hold a copy of -the string given by \fIbytes\fR and \fIlength\fR. -\fBTcl_NewStringObj\fR returns a pointer to a newly created object -with reference count zero. -Both procedures set the object to hold a copy of the specified string. -\fBTcl_SetStringObj\fR frees any old string representation -as well as any old internal representation of the object. +or modify an existing object to hold a copy of the string given by +\fIbytes\fR and \fIlength\fR. \fBTcl_NewUnicodeObj\fR and +\fBTcl_SetUnicodeObj\fR create a new object or modify an existing +object to hold a copy of the Unicode string given by \fIunicode\fR and +\fInumChars\fR. \fBTcl_NewStringObj\fR and \fBTcl_NewUnicodeObj\fR +return a pointer to a newly created object with reference count zero. +All four procedures set the object to hold a copy of the specified +string. \fBTcl_SetStringObj\fR and \fBTcl_SetUnicodeObj\fR free any +old string representation as well as any old internal representation +of the object. +.VE +.PP +\fBTcl_GetStringFromObj\fR and \fBTcl_GetString\fR return an object's +string representation. This is given by the returned byte pointer and +(for \fBTcl_GetStringFromObj\fR) length, which is stored in +\fIlengthPtr\fR if it is non-NULL. If the object's UTF string +representation is invalid (its byte pointer is NULL), the string +representation is regenerated from the object's internal +representation. The storage referenced by the returned byte pointer +is owned by the object manager and should not be modified by the +caller. The procedure \fBTcl_GetString\fR is used in the common case +where the caller does not need the length of the string +representation. .PP -\fBTcl_GetStringFromObj\fR returns an object's string representation. -This is given by the returned byte pointer -and length, which is stored in \fIlengthPtr\fR if it is non-NULL. -If the object's string representation is invalid -(its byte pointer is NULL), -the string representation is regenerated from the -object's internal representation. -The storage referenced by the returned byte pointer -is owned by the object manager and should not be modified by the caller. +.VS 8.1.2 +\fBTcl_GetUnicode\fR returns an object's value as a Unicode string. +\fBTcl_GetUniChar\fR returns the \fIindex\fR'th character in the +object's Unicode representation. +.PP +\fBTcl_GetRange\fR returns a newly created object comprised of the +characters between \fIfirst\fR and \fIlast\fR (inclusive) in the +object's Unicode representation. If the object's Unicode +representation is invalid, the Unicode representation is regenerated +from the object's string representation. +.PP +\fBTcl_GetCharLength\fR returns the number of characters (as opposed +to bytes) in the string object. .PP \fBTcl_AppendToObj\fR appends the data given by \fIbytes\fR and -\fIlength\fR to the object specified by \fIobjPtr\fR. It does this -in a way that handles repeated calls relatively efficiently (it -overallocates the string space to avoid repeated reallocations -and copies of object's string value). +\fIlength\fR to the string representation of the object specified by +\fIobjPtr\fR. If the object has an invalid string representation, +then an attempt is made to convert \fIbytes\fR is to the Unicode +format. If the conversion is successful, then the converted form of +\fIbytes\fR is appended to the object's Unicode representation. +Otherwise, the object's Unicode representation is invalidated and +converted to the UTF format, and \fIbytes\fR is appended to the +object's new string representation. +.PP +\fBTcl_AppendUnicodeToObj\fR appends the Unicode string given by +\fIunicode\fR and \fInumChars\fR to the object specified by +\fIobjPtr\fR. If the object has an invalid Unicode representation, +then \fIunicode\fR is converted to the UTF format and appended to the +object's string representation. Appends are optimized to handle +repeated appends relatively efficiently (it overallocates the string +or Unicode space to avoid repeated reallocations and copies of +object's string value). +.PP +\fBTcl_AppendObjToObj\fR is similar to \fBTcl_AppendToObj\fR, but it +appends the string or Unicode value (whichever exists and is best +suited to be appended to \fIobjPtr\fR) of \fIappendObjPtr\fR to +\fIobjPtr\fR. +.VE .PP \fBTcl_AppendStringsToObj\fR is similar to \fBTcl_AppendToObj\fR except that it can be passed more than one value to append and @@ -99,6 +209,10 @@ values may contain internal null characters). Any number of \fIstring\fR arguments may be provided, but the last argument must be a NULL pointer to indicate the end of the list. .PP +\fBTcl_AppendStringsToObjVA\fR is the same as \fBTcl_AppendStringsToObj\fR +except that instead of taking a variable number of arguments it takes an +argument list. +.PP The \fBTcl_SetObjLength\fR procedure changes the length of the string value of its \fIobjPtr\fR argument. If the \fInewLength\fR argument is greater than the space allocated for the object's @@ -129,4 +243,4 @@ Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount .SH KEYWORDS append, internal representation, object, object type, string object, -string type, string representation, concat, concatenate +string type, string representation, concat, concatenate, unicode diff --git a/tcl/doc/TCL_MEM_DEBUG.3 b/tcl/doc/TCL_MEM_DEBUG.3 new file mode 100644 index 00000000000..1950d149a15 --- /dev/null +++ b/tcl/doc/TCL_MEM_DEBUG.3 @@ -0,0 +1,81 @@ +'\" +'\" Copyright (c) 1992-1999 Karl Lehenbauer and Mark Diekhans. +'\" Copyright (c) 2000 by Scriptics Corporation. +'\" All rights reserved. +'\" +'\" RCS: @(#) $Id$ +'\" +.so man.macros +.TH TCL_MEM_DEBUG 3 8.1 Tcl "Tcl Library Procedures" +.BS +.SH NAME +TCL_MEM_DEBUG \- Compile-time flag to enable Tcl memory debugging. + +.SH DESCRIPTION +When Tcl is compiled with \fBTCL_MEM_DEBUG\fR defined, a powerful set +of memory debugging aids are included in the compiled binary. This +includes C and Tcl functions which can aid with debugging +memory leaks, memory allocation overruns, and other memory related +errors. + +.SH ENABLING MEMORY DEBUGGING +.PP +To enable memory debugging, Tcl should be recompiled from scratch with +\fBTCL_MEM_DEBUG\fR defined. This will also compile in a non-stub +version of \fBTcl_InitMemory\fR to add the \fBmemory\fR command to Tcl. +.PP +\fBTCL_MEM_DEBUG\fR must be either left defined for all modules or undefined +for all modules that are going to be linked together. If they are not, link +errors will occur, with either \fBTclDbCkfree\fR and \fBTcl_DbCkalloc\fR or +\fBTcl_Ckalloc\fR and \fBTcl_Ckfree\fR being undefined. +.PP +Once memory debugging support has been compiled into Tcl, the C +functions \fBTcl_ValidateAllMemory\fR, and \fBTcl_DumpActiveMemory\fR, +and the Tcl \fBmemory\fR command can be used to validate and examine +memory usage. + +.SH GUARD ZONES +.PP +When memory debugging is enabled, whenever a call to \fBckalloc\fR is +made, slightly more memory than requested is allocated so the memory debugging +code can keep track of the allocated memory, and eight-byte ``guard +zones'' are placed in front of and behind the space that will be +returned to the caller. (The size of the guard zone is defined by the +C #define \fBGUARD_SIZE\fR in \fIbaseline/src/ckalloc.c\fR -- it can +be extended if you suspect large overwrite problems, at some cost in +performance.) A known pattern is written into the guard zones and, on +a call to \fBckfree\fR, the guard zones of the space being freed are +checked to see if either zone has been modified in any way. If one +has been, the guard bytes and their new contents are identified, and a +``low guard failed'' or ``high guard failed'' message is issued. The +``guard failed'' message includes the address of the memory packet and +the file name and line number of the code that called \fBckfree\fR. +This allows you to detect the common sorts of one-off problems, where +not enough space was allocated to contain the data written, for +example. + +.SH DEBUGGING DIFFICULT MEMORY CORRUPTION PROBLEMS +.PP +Normally, Tcl compiled with memory debugging enabled will make it easy +to isolate a corruption problem. Turning on memory validation with +the memory command can help isolate difficult problems. If you +suspect (or know) that corruption is occurring before the Tcl +interpreter comes up far enough for you to issue commands, you can set +\fBMEM_VALIDATE\fR define, recompile tclCkalloc.c and rebuild Tcl. +This will enable memory validation from the first call to +\fBckalloc\fR, again, at a large performance impact. +.PP +If you are desperate and validating memory on every call to +\fBckalloc\fR and \fBckfree\fR isn't enough, you can explicitly call +\fBTcl_ValidateAllMemory\fR directly at any point. It takes a \fIchar +*\fR and an \fIint\fR which are normally the filename and line number +of the caller, but they can actually be anything you want. Remember +to remove the calls after you find the problem. + +.SH "SEE ALSO" +memory, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory + +.SH KEYWORDS +memory, debug + + diff --git a/tcl/doc/Tcl.n b/tcl/doc/Tcl.n index 47f2faa3012..5462083de37 100644 --- a/tcl/doc/Tcl.n +++ b/tcl/doc/Tcl.n @@ -6,9 +6,9 @@ '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" '\" RCS: @(#) $Id$ -' +'\" .so man.macros -.TH Tcl n "" Tcl "Tcl Built-In Commands" +.TH Tcl n "8.1" Tcl "Tcl Built-In Commands" .BS .SH NAME Tcl \- Summary of Tcl language syntax. @@ -111,47 +111,61 @@ special processing. The following table lists the backslash sequences that are handled specially, along with the value that replaces each sequence. .RS -.TP 6 +.TP 7 \e\fBa\fR Audible alert (bell) (0x7). -.TP 6 +.TP 7 \e\fBb\fR Backspace (0x8). -.TP 6 +.TP 7 \e\fBf\fR Form feed (0xc). -.TP 6 +.TP 7 \e\fBn\fR Newline (0xa). -.TP 6 +.TP 7 \e\fBr\fR Carriage-return (0xd). -.TP 6 +.TP 7 \e\fBt\fR Tab (0x9). -.TP 6 +.TP 7 \e\fBv\fR Vertical tab (0xb). -.TP 6 +.TP 7 \e\fB\fIwhiteSpace\fR -A single space character replaces the backslash, newline, and all -spaces and tabs after the newline. -This backslash sequence is unique in that it is replaced in a separate -pre-pass before the command is actually parsed. -This means that it will be replaced even when it occurs between -braces, and the resulting space will be treated as a word separator -if it isn't in braces or quotes. -.TP 6 +. +A single space character replaces the backslash, newline, and all spaces +and tabs after the newline. This backslash sequence is unique in that it +is replaced in a separate pre-pass before the command is actually parsed. +This means that it will be replaced even when it occurs between braces, +and the resulting space will be treated as a word separator if it isn't +in braces or quotes. +.TP 7 \e\e Backslash (``\e''). -.TP 6 -\e\fIooo\fR -The digits \fIooo\fR (one, two, or three of them) give the octal value of -the character. -.TP 6 -\e\fBx\fIhh\fR -The hexadecimal digits \fIhh\fR give the hexadecimal value of -the character. Any number of digits may be present. +.VS 8.1 br +.TP 7 +\e\fIooo\fR +. +The digits \fIooo\fR (one, two, or three of them) give an eight-bit octal +value for the Unicode character that will be inserted. The upper bits of the +Unicode character will be 0. +.TP 7 +\e\fBx\fIhh\fR +. +The hexadecimal digits \fIhh\fR give an eight-bit hexadecimal value for the +Unicode character that will be inserted. Any number of hexadecimal digits +may be present; however, all but the last two are ignored (the result is +always a one-byte quantity). The upper bits of the Unicode character will +be 0. +.TP 7 +\e\fBu\fIhhhh\fR +. +The hexadecimal digits \fIhhhh\fR (one, two, three, or four of them) give a +sixteen-bit hexadecimal value for the Unicode character that will be +inserted. +.VE .LP Backslash substitution is not performed on words enclosed in braces, except for backslash-newline as described above. diff --git a/tcl/doc/TclInitStubs.3 b/tcl/doc/TclInitStubs.3 new file mode 100644 index 00000000000..aa12b8e6589 --- /dev/null +++ b/tcl/doc/TclInitStubs.3 @@ -0,0 +1,91 @@ +'\" +'\" Copyright (c) 1999 Scriptics Corportation +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id$ +'\" +.so man.macros +.TH Tcl_InitStubs 3 8.1 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_InitStubs \- initialize the Tcl stubs mechanism +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +char * +\fBTcl_InitStubs\fR(\fIinterp, version, exact\fR) +.SH ARGUMENTS +.AS Tcl_Interp *interp in +.AP Tcl_Interp *interp in +Tcl interpreter handle. +.AP char *version in +A version string consisting of one or more decimal numbers +separated by dots. +.AP int exact in +Non-zero means that only the particular version specified by +\fIversion\fR is acceptable. +Zero means that versions newer than \fIversion\fR are also +acceptable as long as they have the same major version number +as \fIversion\fR. +.BE +.SH INTRODUCTION +.PP +The Tcl stubs mechanism defines a way to dynamically bind +extensions to a particular Tcl implementation at run time. +This provides two significant benefits to Tcl users: +.IP 1) 5 +Extensions that use the stubs mechanism can be loaded into +multiple versions of Tcl without being recompiled or +relinked. +.IP 2) 5 +Extensions that use the stubs mechanism can be dynamically +loaded into statically-linked Tcl applications. +.PP +The stubs mechanism accomplishes this by exporting function tables +that define an interface to the Tcl API. The extension then accesses +the Tcl API through offsets into the function table, so there are no +direct references to any of the Tcl library's symbols. This +redirection is transparent to the extension, so an extension writer +can continue to use all public Tcl functions as documented. +.PP +The stubs mechanism requires no changes to applications incorporating +Tcl interpreters. Only developers creating C-based Tcl extensions +need to take steps to use the stubs mechanism with their extensions. +.PP +Enabling the stubs mechanism for an extension requires the following +steps: +.IP 1) 5 +Call \fBTcl_InitStubs\fR in the extension before calling any other +Tcl functions. +.IP 2) 5 +Define the USE_TCL_STUBS symbol. Typically, you would include the +-DUSE_TCL_STUBS flag when compiling the extension. +.IP 3) 5 +Link the extension with the Tcl stubs library instead of the standard +Tcl library. On Unix platforms, the library name is +\fIlibtclstub8.1.a\fR; on Windows platforms, the library name is +\fItclstub81.lib\fR. +.PP +If the extension also requires the Tk API, it must also call +\fBTk_InitStubs\fR to initialize the Tk stubs interface and link +with the Tk stubs libraries. See the \fBTk_InitStubs\fR page for +more information. +.SH DESCRIPTION +\fBTcl_InitStubs\fR attempts to initialize the stub table pointers +and ensure that the correct version of Tcl is loaded. In addition +to an interpreter handle, it accepts as arguments a version number +and a Boolean flag indicating whether the extension requires +an exact version match or not. If \fIexact\fR is 0, then the +extension is indicating that newer versions of Tcl are acceptable +as long as they have the same major version number as \fIversion\fR; +non-zero means that only the specified \fIversion\fR is acceptable. +\fBTcl_InitStubs\fR returns a string containing the actual version +of Tcl satisfying the request, or NULL if the Tcl version is not +acceptable, does not support stubs, or any other error condition occurred. +.SH "SEE ALSO" +\fBTk_InitStubs\fR +.SH KEYWORDS +stubs diff --git a/tcl/doc/Thread.3 b/tcl/doc/Thread.3 new file mode 100644 index 00000000000..d2e2972b553 --- /dev/null +++ b/tcl/doc/Thread.3 @@ -0,0 +1,195 @@ +'\" +'\" 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$ +'\" +.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 \fR +.sp +void +\fBTcl_ConditionNotify\fR(\fIcondPtr\fR) +.sp +void +\fBTcl_ConditionWait\fR(\fIcondPtr, mutexPtr, timePtr\fR) +.sp +void +\fBTcl_ConditionFinalize\fR(\fIcondPtr\fR) +.sp +Void * +\fBTcl_GetThreadData\fR(\fIkeyPtr, size\fR) +.sp +void +\fBTcl_MutexLock\fR(\fImutexPtr\fR) +.sp +void +\fBTcl_MutexUnlock\fR(\fImutexPtr\fR) +.sp +void +\fBTcl_MutexFinalize\fR(\fImutexPtr\fR) +.sp +int +\fBTcl_CreateThread\fR(\fIidPtr, threadProc, clientData, stackSize, flags\fR) +.SH ARGUMENTS +.AS Tcl_ThreadDataKey *keyPtr +.AP Tcl_Condition *condPtr in +A condition variable, which must be associated with a mutex lock. +.AP Tcl_Condition *mutexPtr in +A mutex lock. +.AP Tcl_Time *timePtr in +A time limit on the condition wait. NULL to wait forever. +Note that a polling value of 0 seconds doesn't make much sense. +.AP Tcl_ThreadDataKey *keyPtr in +This identifies a block of thread local storage. The key should be +static and process-wide, yet each thread will end up associating +a different block of storage with this key. +.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. +.PP +An important contstraint of the Tcl threads implementation is that +\fIonly the thread that created a Tcl interpreter can use that +interpreter\fR. In other words, multiple threads can not access +the same Tcl interpreter. (However, as was the case in previous +releases, a single thread can safely create and use multiple +interpreters.) +.PP +.VS 8.3.1 +Tcl does provide \fBTcl_CreateThread\fR for creating threads. The +caller can determine the size of the stack given to the new thread and +modify the behaviour through the supplied \fIflags\fR. The value +\fBTCL_THREAD_STACK_DEFAULT\fR for the \fIstackSize\fR indicates that +the default size as specified by the operating system is to be used +for the new thread. As for the flags, currently are only the values +\fBTCL_THREAD_NOFLAGS\fR and \fBTCL_THREAD_JOINABLE\fR defined. The +first of them invokes the default behaviour with no +specialities. Using the second value marks the new thread as +\fIjoinable\fR. This means that another thread can wait for the such +marked thread to exit and join it. +.PP +Restrictions: On some unix systems the pthread-library does not +contain the functionality to specify the stacksize of a thread. The +specified value for the stacksize is ignored on these systems. Both +Windows and Macintosh currently do not support joinable threads. This +flag value is therefore ignored on these platforms. +.VE +.PP +Tcl does provide \fBTcl_ExitThread\fR and \fBTcl_FinalizeThread\fR +for terminating threads and invoking optional per-thread exit +handlers. See the \fBTcl_Exit\fR page for more information on these +procedures. +.PP +Tcl provides \fBTcl_ThreadQueueEvent\fR and \fBTcl_ThreadAlert\fR +for handling event queueing in multithreaded applications. See +the \fBNotifier\fR manual page for more information on these procedures. +.PP +In this release, the Tcl language itself provides no support for +creating multithreaded scripts (for example, scripts that could spawn +a Tcl interpreter in a separate thread). If you need to add this +feature at this time, see the \fItclThreadTest.c\fR +file in the Tcl source distribution for an experimental implementation +of a Tcl "Thread" package implementing thread creation and management +commands at the script level. + +.SH DESCRIPTION +A mutex is a lock that is used to serialize all threads through a piece +of code by calling \fBTcl_MutexLock\fR and \fBTcl_MutexUnlock\fR. +If one thread holds a mutex, any other thread calling \fBTcl_MutexLock\fR will +block until \fBTcl_MutexUnlock\fR is called. +.VS +A mutex can be destroyed after its use by calling \fBTcl_MutexFinalize\fR. +The result of locking a mutex twice from the same thread is undefined. +On some platforms it will result in a deadlock. +.VE +The \fBTcl_MutexLock\fR, \fBTcl_MutexUnlock\fR and \fBTcl_MutexFinalize\fR +procedures are defined as empty macros if not compiling with threads enabled. +.PP +A condition variable is used as a signaling mechanism: +a thread can lock a mutex and then wait on a condition variable +with \fBTcl_ConditionWait\fR. This atomically releases the mutex lock +and blocks the waiting thread until another thread calls +\fBTcl_ConditionNotify\fR. The caller of \fBTcl_ConditionNotify\fR should +have the associated mutex held by previously calling \fBTcl_MutexLock\fR, +but this is not enforced. Notifying the +condition variable unblocks all threads waiting on the condition variable, +but they do not proceed until the mutex is released with \fBTcl_MutexUnlock\fR. +The implementation of \fBTcl_ConditionWait\fR automatically locks +the mutex before returning. +.PP +The caller of \fBTcl_ConditionWait\fR should be prepared for spurious +notifications by calling \fBTcl_ConditionWait\fR within a while loop +that tests some invariant. +.PP +.VS +A condition variable can be destroyed after its use by calling +\fBTcl_ConditionFinalize\fR. +.PP +The \fBTcl_ConditionNotify\fR, \fBTcl_ConditionWait\fR and +\fBTcl_ConditionFinalize\fR procedures are defined as empty macros if +not compiling with threads enabled. +.VE +.PP +The \fBTcl_GetThreadData\fR call returns a pointer to a block of +thread-private data. Its argument is a key that is shared by all threads +and a size for the block of storage. The storage is automatically +allocated and initialized to all zeros the first time each thread asks for it. +The storage is automatically deallocated by \fBTcl_FinalizeThread\fR. +.SH INITIALIZATION +.PP +All of these synchronization objects are self initializing. +They are implemented as opaque pointers that should be NULL +upon first use. +The mutexes and condition variables are +.VS +either cleaned up by process exit handlers (if living that long) or +explicitly by calls to \fBTcl_MutexFinalize\fR or +\fBTcl_ConditionFinalize\fR. +.VE +Thread local storage is reclaimed during \fBTcl_FinalizeThread\fR. +.SH "CREATING THREADS" +The API to create threads is not finalized at this time. +There are private facilities to create threads that contain a new +Tcl interpreter, and to send scripts among threads. +Dive into tclThreadTest.c and tclThread.c for examples. +.SH "SEE ALSO" +Tcl_GetCurrentThread, Tcl_ThreadQueueEvent, Tcl_ThreadAlert, +Tcl_ExitThread, Tcl_FinalizeThread, +Tcl_CreateThreadExitHandler, Tcl_DeleteThreadExitHandler +.SH KEYWORDS +thread, mutex, condition variable, thread local storage + diff --git a/tcl/doc/ToUpper.3 b/tcl/doc/ToUpper.3 new file mode 100644 index 00000000000..285c8917fc0 --- /dev/null +++ b/tcl/doc/ToUpper.3 @@ -0,0 +1,90 @@ +'\" +'\" 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$ +'\" +.so man.macros +.TH Tcl_UtfToUpper 3 "8.1" Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_UniCharToUpper, Tcl_UniCharToLower, Tcl_UniCharToTitle, Tcl_UtfToUpper, Tcl_UtfToLower, Tcl_UtfToTitle \- routines for manipulating the case of Unicode characters and UTF-8 strings. +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +Tcl_UniChar +\fBTcl_UniCharToUpper\fR(\fIch\fR) +.sp +Tcl_UniChar +\fBTcl_UniCharToLower\fR(\fIch\fR) +.sp +Tcl_UniChar +\fBTcl_UniCharToTitle\fR(\fIch\fR) +.sp +int +\fBTcl_UtfToUpper\fR(\fIstr\fR) +.sp +int +\fBTcl_UtfToLower\fR(\fIstr\fR) +.sp +int +\fBTcl_UtfToTitle\fR(\fIstr\fR) +.SH ARGUMENTS +.AS char *str in/out +.AP int ch in +The Tcl_UniChar to be converted. +.AP char *str in/out +Pointer to UTF-8 string to be converted in place. +.BE + +.SH DESCRIPTION +.PP +The first three routines convert the case of individual Unicode characters: +.PP +If \fIch\fR represents a lower-case character, +\fBTcl_UniCharToUpper\fR returns the corresponding upper-case +character. If no upper-case character is defined, it returns the +character unchanged. +.PP +If \fIch\fR represents an upper-case character, +\fBTcl_UniCharToLower\fR returns the corresponding lower-case +character. If no lower-case character is defined, it returns the +character unchanged. +.PP +If \fIch\fR represents a lower-case character, +\fBTcl_UniCharToTitle\fR returns the corresponding title-case +character. If no title-case character is defined, it returns the +corresponding upper-case character. If no upper-case character is +defined, it returns the character unchanged. Title-case is defined +for a small number of characters that have a different appearance when +they are at the beginning of a capitalized word. +.PP +The next three routines convert the case of UTF-8 strings in place in +memory: +.PP +\fBTcl_UtfToUpper\fR changes every UTF-8 character in \fIstr\fR to +upper-case. Because changing the case of a character may change its +size, the byte offset of each character in the resulting string may +differ from its original location. \fBTcl_UtfToUpper\fR writes a null +byte at the end of the converted string. \fBTcl_UtfToUpper\fR returns +the new length of the string in bytes. This new length is guaranteed +to be no longer than the original string length. +.PP +\fBTcl_UtfToLower\fR is the same as \fBTcl_UtfToUpper\fR except it +turns each character in the string into its lower-case equivalent. +.PP +\fBTcl_UtfToTitle\fR is the same as \fBTcl_UtfToUpper\fR except it +turns the first character in the string into its title-case equivalent +and all following characters into their lower-case equivalents. + +.SH BUGS +.PP +At this time, the case conversions are only defined for the ISO8859-1 +characters. Unicode characters above 0x00ff are not modified by these +routines. + +.SH KEYWORDS +utf, unicode, toupper, tolower, totitle, case diff --git a/tcl/doc/TraceVar.3 b/tcl/doc/TraceVar.3 index b45e754f3c8..3048d18713c 100644 --- a/tcl/doc/TraceVar.3 +++ b/tcl/doc/TraceVar.3 @@ -44,7 +44,7 @@ must be in writable memory: Tcl will make temporary modifications to it while looking up the name. .AP int flags in OR-ed combination of the values TCL_TRACE_READS, TCL_TRACE_WRITES, and -TCL_TRACE_UNSETS, TCL_PARSE_PART1, and TCL_GLOBAL_ONLY. +TCL_TRACE_UNSETS, TCL_TRACE_ARRAY, and TCL_GLOBAL_ONLY. Not all flags are used by all procedures. See below for more information. .AP Tcl_VarTraceProc *proc in @@ -72,7 +72,7 @@ whenever the variable is read or written or unset. If the trace is created successfully then \fBTcl_TraceVar\fR returns TCL_OK. If an error occurred (e.g. \fIvarName\fR specifies an element of an array, but the actual variable isn't an array) then TCL_ERROR -is returned and an error message is left in \fIinterp->result\fR. +is returned and an error message is left in the interpreter's result. .PP The \fIflags\fR argument to \fBTcl_TraceVar\fR indicates when the trace procedure is to be invoked and provides information @@ -96,6 +96,12 @@ A variable may be unset either explicitly by an \fBunset\fR command, or implicitly when a procedure returns (its local variables are automatically unset) or when the interpreter is deleted (all variables are automatically unset). +.TP +\fBTCL_TRACE_ARRAY\fR +Invoke \fIproc\fR whenever the array command is invoked. +This gives the trace procedure a chance to update the array before +array names or array get is called. Note that this is called +before an array set, but that will trigger write traces. .PP Whenever one of the specified operations occurs on the variable, \fIproc\fR will be invoked. @@ -120,7 +126,8 @@ in the normal two-part form (see the description of \fBTcl_TraceVar2\fR below for details). \fIFlags\fR is an OR-ed combination of bits providing several pieces of information. -One of the bits TCL_TRACE_READS, TCL_TRACE_WRITES, or TCL_TRACE_UNSETS +One of the bits TCL_TRACE_READS, TCL_TRACE_WRITES, TCL_TRACE_ARRAY, +or TCL_TRACE_UNSETS will be set in \fIflags\fR to indicate which operation is being performed on the variable. The bit TCL_GLOBAL_ONLY will be set whenever the variable being @@ -175,24 +182,26 @@ The procedures \fBTcl_TraceVar2\fR, \fBTcl_UntraceVar2\fR, and except that the name of the variable consists of two parts. \fIName1\fR gives the name of a scalar variable or array, and \fIname2\fR gives the name of an element within an array. -If \fIname2\fR is NULL it means that either the variable is -a scalar or the trace is to be set on the entire array rather -than an individual element (see WHOLE-ARRAY TRACES below for -more information). -As a special case, if the flag TCL_PARSE_PART1 is specified, +.VS 8.1 +When \fIname2\fR is NULL, \fIname1\fR may contain both an array and an element name: if the name contains an open parenthesis and ends with a close parenthesis, then the value between the parentheses is treated as an element name (which can have any string value) and the characters before the first open parenthesis are treated as the name of an array variable. -If the flag TCL_PARSE_PART1 is given, -\fIname2\fR should be NULL since the array and element names -are taken from \fIname1\fR. +If \fIname2\fR is NULL and \fIname1\fR does not refer +to an array element +.VE +it means that either the variable is +a scalar or the trace is to be set on the entire array rather +than an individual element (see WHOLE-ARRAY TRACES below for +more information). + .SH "ACCESSING VARIABLES DURING TRACES" .PP -During read and write traces, the +During read, write, and array traces, the trace procedure can read, write, or unset the traced variable using \fBTcl_GetVar2\fR, \fBTcl_SetVar2\fR, and other procedures. @@ -245,6 +254,12 @@ access. If it deletes the variable then the traced access will return an empty string. .PP +When array tracing has been specified, the trace procedure +will be invoked at the beginning of the array command implementation, +before any of the operations like get, set, or names have been invoked. +The trace procedure can modify the array elements with \fBTcl_SetVar\fR +and \fBTcl_SetVar2\fR. +.PP When unset tracing has been specified, the trace procedure will be invoked whenever the variable is destroyed. The traces will be called after the variable has been @@ -343,6 +358,10 @@ to clean up and free their own internal data structures. Tcl doesn't do any error checking to prevent trace procedures from misusing the interpreter during traces with TCL_INTERP_DESTROYED set. +.PP +Array traces are not yet integrated with the Tcl "info exists" command, +nor is there Tcl-level access to array traces. .SH KEYWORDS clientData, trace, variable + diff --git a/tcl/doc/Translate.3 b/tcl/doc/Translate.3 index 9ebf1d16404..68b1edd6317 100644 --- a/tcl/doc/Translate.3 +++ b/tcl/doc/Translate.3 @@ -1,6 +1,6 @@ '\" '\" Copyright (c) 1989-1993 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" Copyright (c) 1994-1998 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. @@ -8,7 +8,7 @@ '\" RCS: @(#) $Id$ '\" .so man.macros -.TH Tcl_TranslateFileName 3 7.5 Tcl "Tcl Library Procedures" +.TH Tcl_TranslateFileName 3 8.1 Tcl "Tcl Library Procedures" .BS .SH NAME Tcl_TranslateFileName \- convert file name to native form and replace tilde with home directory @@ -26,7 +26,7 @@ Interpreter in which to report an error, if any. File name, which may start with a ``~''. .AP Tcl_DString *bufferPtr in/out If needed, this dynamic string is used to store the new file name. -At the time of the call it should be uninitialized or empty. The +At the time of the call it should be uninitialized or free. The caller must eventually call \fBTcl_DStringFree\fR to free up anything stored here. .BE @@ -51,12 +51,12 @@ initializes \fI*bufferPtr\fR even if it doesn't use it, so the call to .PP If an error occurs (e.g. because there was no user by the given name) then NULL is returned and an error message will be left -at \fIinterp->result\fR. +in the interpreter's result. When an error occurs, \fBTcl_TranslateFileName\fR frees the dynamic string itself so that the caller need not call \fBTcl_DStringFree\fR. .PP -The caller is responsible for making sure that \fIinterp->result\fR +The caller is responsible for making sure that the interpreter's result has its default empty value when \fBTcl_TranslateFileName\fR is invoked. .SH "SEE ALSO" @@ -64,3 +64,4 @@ filename .SH KEYWORDS file name, home directory, tilde, translate, user + diff --git a/tcl/doc/UpVar.3 b/tcl/doc/UpVar.3 index 1594d3b9f4b..6e60d2a7182 100644 --- a/tcl/doc/UpVar.3 +++ b/tcl/doc/UpVar.3 @@ -64,8 +64,7 @@ The destination variable name is specified in a single string; it may not be an array element. .PP Both procedures return either TCL_OK or TCL_ERROR, and they -leave an error message in \fIinterp->result\fR if an error -occurs. +leave an error message in the interpreter's result if an error occurs. .PP As with the \fBupvar\fR command, the source variable need not exist; if it does exist, unsetting it later does not destroy the link. The @@ -74,3 +73,4 @@ it must exist as a linked variable. .SH KEYWORDS linked variable, upvar, variable + diff --git a/tcl/doc/Utf.3 b/tcl/doc/Utf.3 new file mode 100644 index 00000000000..db954f7e6b7 --- /dev/null +++ b/tcl/doc/Utf.3 @@ -0,0 +1,233 @@ +'\" +'\" 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$ +'\" +.so man.macros +.TH Utf 3 "8.1" Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_UniChar, Tcl_UniCharToUtf, Tcl_UtfToUniChar, Tcl_UniCharToUtfDString, Tcl_UtfToUniCharDString, Tcl_UniCharLen, Tcl_UniCharNcmp, Tcl_UtfCharComplete, Tcl_NumUtfChars, Tcl_UtfFindFirst, Tcl_UtfFindLast, Tcl_UtfNext, Tcl_UtfPrev, Tcl_UniCharAtIndex, Tcl_UtfAtIndex, Tcl_UtfBackslash \- routines for manipulating UTF-8 strings. +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +typedef ... Tcl_UniChar; +.sp +int +\fBTcl_UniCharToUtf\fR(\fIch, buf\fR) +.sp +int +\fBTcl_UtfToUniChar\fR(\fIsrc, chPtr\fR) +.sp +char * +\fBTcl_UniCharToUtfDString\fR(\fIuniStr, numChars, dstPtr\fR) +.sp +Tcl_UniChar * +\fBTcl_UtfToUniCharDString\fR(\fIsrc, len, dstPtr\fR) +.sp +int +\fBTcl_UniCharLen\fR(\fIuniStr\fR) +.sp +int +\fBTcl_UniCharNcmp\fR(\fIuniStr, uniStr, num\fR) +.sp +int +\fBTcl_UtfNcmp\fR(\fIsrc, src, num\fR) +.sp +int +\fBTcl_UtfNcasecmp\fR(\fIsrc, src, num\fR) +.sp +int +\fBTcl_UtfCharComplete\fR(\fIsrc, len\fR) +.sp +int +\fBTcl_NumUtfChars\fR(\fIsrc, len\fR) +.sp +char * +\fBTcl_UtfFindFirst\fR(\fIsrc, ch\fR) +.sp +char * +\fBTcl_UtfFindLast\fR(\fIsrc, ch\fR) +.sp +char * +\fBTcl_UtfNext\fR(\fIsrc\fR) +.sp +char * +\fBTcl_UtfPrev\fR(\fIsrc, start\fR) +.sp +Tcl_UniChar +\fBTcl_UniCharAtIndex\fR(\fIsrc, index\fR) +.sp +char * +\fBTcl_UtfAtIndex\fR(\fIsrc, index\fR) +.sp +int +\fBTcl_UtfBackslash\fR(\fIsrc, readPtr, dst\fR) +.SH ARGUMENTS +.AS "CONST Tcl_UniChar" numChars in/out +.AP char *buf out +Buffer in which the UTF-8 representation of the Tcl_UniChar is stored. At most +TCL_UTF_MAX bytes are stored in the buffer. +.AP int ch in +The Tcl_UniChar to be converted or examined. +.AP Tcl_UniChar *chPtr out +Filled with the Tcl_UniChar represented by the head of the UTF-8 string. +.AP "CONST char" *src in +Pointer to a UTF-8 string. +.AP "CONST Tcl_UniChar" *uniStr in +A NULL-terminated Unicode string. +.AP int len in +The length of the UTF-8 string in bytes (not UTF-8 characters). If +negative, all bytes up to the first null byte are used. +.AP int numChars in +The length of the Unicode string in characters. Must be greater than or +equal to 0. +.AP "Tcl_DString" *dstPtr in/out +A pointer to a previously-initialized \fBTcl_DString\fR. +.AP "unsigned long" num in +The number of characters to compare. +.AP "CONST char" *start in +Pointer to the beginning of a UTF-8 string. +.AP int index in +The index of a character (not byte) in the UTF-8 string. +.AP int *readPtr out +If non-NULL, filled with the number of bytes in the backslash sequence, +including the backslash character. +.AP char *dst out +Buffer in which the bytes represented by the backslash sequence are stored. +At most TCL_UTF_MAX bytes are stored in the buffer. +.BE + +.SH DESCRIPTION +.PP +These routines convert between UTF-8 strings and Tcl_UniChars. A +Tcl_UniChar is a Unicode character represented as an unsigned, fixed-size +quantity. A UTF-8 character is a Unicode character represented as +a varying-length sequence of up to TCL_UTF_MAX bytes. A multibyte UTF-8 +sequence consists of a lead byte followed by some number of trail bytes. +.PP +\fBTCL_UTF_MAX\fR is the maximum number of bytes that it takes to +represent one Unicode character in the UTF-8 representation. +.PP +\fBTcl_UniCharToUtf\fR stores the Tcl_UniChar \fIch\fR as a UTF-8 string +in starting at \fIbuf\fR. The return value is the number of bytes stored +in \fIbuf\fR. +.PP +\fBTcl_UtfToUniChar\fR reads one UTF-8 character starting at \fIsrc\fR +and stores it as a Tcl_UniChar in \fI*chPtr\fR. The return value is the +number of bytes read from \fIsrc\fR.. The caller must ensure that the +source buffer is long enough such that this routine does not run off the +end and dereference non-existent or random memory; if the source buffer +is known to be null terminated, this will not happen. If the input is +not in proper UTF-8 format, \fBTcl_UtfToUniChar\fR will store the first +byte of \fIsrc\fR in \fI*chPtr\fR as a Tcl_UniChar between 0x0000 and +0x00ff and return 1. +.PP +\fBTcl_UniCharToUtfDString\fR converts the given Unicode string +to UTF-8, storing the result in a previously-initialized \fBTcl_DString\fR. +You must specify the length of the given Unicode string. +The return value is a pointer to the UTF-8 representation of the +Unicode string. Storage for the return value is appended to the +end of the \fBTcl_DString\fR. +.PP +\fBTcl_UtfToUniCharDString\fR coverts the given UTF-8 string to Unicode, +storing the result in the previously-initialized \fBTcl_Dstring\fR. +you may either specify the length of the given UTF-8 string or "-1", +in which case \fBTcl_UtfToUniCharDString\fR uses \fBstrlen\fR to +calculate the length. The return value is a pointer to the Unicode +representation of the UTF-8 string. Storage for the return value +is appended to the end of the \fBTcl_DString\fR. The Unicode string +is terminated with a Unicode NULL character. +.PP +\fBTcl_UniCharLen\fR corresponds to \fBstrlen\fR for Unicode +characters. It accepts a NULL-terminated Unicode string and returns +the number of Unicode characters (not bytes) in that string. +.PP +\fBTcl_UniCharNcmp\fR corresponds to \fBstrncmp\fR for Unicode +characters. It accepts two NULL-terminated Unicode strings +and the number of characters to compare. (Both strings are +assumed to be at least \fIlen\fR characters long.) +\fBTcl_UniCharNcmp\fR compares the two strings character-by-character +according to the Unicode character ordering. It returns an integer +greater than, equal to, +or less than 0 if the first string is greater than, equal to, or +less than the second string respectively. +.PP +\fBTcl_UtfNcmp\fR corresponds to \fBstrncmp\fR for UTF-8 strings. It +accepts two NULL-terminated UTF-8 strings and the number of characters +to compare. (Both strings are assumed to be at least \fIlen\fR +characters long.) \fBTcl_UtfNcmp\fR compares the two strings +character-by-character according to the Unicode character ordering. +It returns an integer greater than, equal to, or less than 0 if the +first string is greater than, equal to, or less than the second string +respectively. +.PP +\fBTcl_UtfNcasecmp\fR corresponds to \fBstrncasecmp\fR for UTF-8 +strings. It is similar to \fBTcl_UtfNcmp\fR except comparisons ignore +differences in case when comparing upper, lower or title case +characters. +.PP +\fBTcl_UtfCharComplete\fR returns 1 if the source UTF-8 string \fIsrc\fR +of length \fIlen\fR bytes is long enough to be decoded by +\fBTcl_UtfToUniChar\fR, or 0 otherwise. This function does not guarantee +that the UTF-8 string is properly formed. This routine is used by +procedures that are operating on a byte at a time and need to know if a +full Tcl_UniChar has been seen. +.PP +\fBTcl_NumUtfChars\fR corresponds to \fBstrlen\fR for UTF-8 strings. It +returns the number of Tcl_UniChars that are represented by the UTF-8 string +\fIsrc\fR. The length of the source string is \fIlen\fR bytes. If the +length is negative, all bytes up to the first NULL byte are used. +.PP +\fBTcl_UtfFindFirst\fR corresponds to \fBstrchr\fR for UTF-8 strings. It +returns a pointer to the first occurance of the Tcl_UniChar \fIch\fR +in the NULL-terminated UTF-8 string \fIsrc\fR. The NULL terminator is +considered part of the UTF-8 string. +.PP +\fBTcl_UtfFindLast\fR corresponds to \fBstrrchr\fR for UTF-8 strings. It +returns a pointer to the last occurance of the Tcl_UniChar \fIch\fR +in the NULL terminated UTF-8 string \fIsrc\fR. The NULL terminator is +considered part of the UTF-8 string. +.PP +Given \fIsrc\fR, a pointer to some location in a UTF-8 string, +\fBTcl_UtfNext\fR returns a pointer to the next UTF-8 character in the +string. The caller must not ask for the next character after the last +character in the string. +.PP +Given \fIsrc\fR, a pointer to some location in a UTF-8 string, +\fBTcl_UtfPrev\fR returns a pointer to the previous UTF-8 character in the +string. This function will not back up to a position before \fIstart\fR, +the start of the UTF-8 string. If \fIsrc\fR was already at \fIstart\fR, the +return value will be \fIstart\fR. +.PP +\fBTcl_UniCharAtIndex\fR corresponds to a C string array dereference or the +Pascal Ord() function. It returns the Tcl_UniChar represented at the +specified character (not byte) \fIindex\fR in the UTF-8 string +\fIsrc\fR. The source string must contain at least \fIindex\fR +characters. Behavior is undefined if a negative \fIindex\fR is given. +.PP +\fBTcl_UtfAtIndex\fR returns a pointer to the specified character (not +byte) \fIindex\fR in the UTF-8 string \fIsrc\fR. The source string must +contain at least \fIindex\fR characters. This is equivalent to calling +\fBTcl_UtfNext\fR \fIindex\fR times. If a negative \fIindex\fR is given, +the return pointer points to the first character in the source string. +.PP +\fBTcl_UtfBackslash\fR is a utility procedure used by several of the Tcl +commands. It parses a backslash sequence and stores the properly formed +UTF-8 character represented by the backslash sequence in the output +buffer \fIdst\fR. At most TCL_UTF_MAX bytes are stored in the buffer. +\fBTcl_UtfBackslash\fR modifies \fI*readPtr\fR to contain the number +of bytes in the backslash sequence, including the backslash character. +The return value is the number of bytes stored in the output buffer. +.PP +See the \fBTcl\fR manual entry for information on the valid backslash +sequences. All of the sequences described in the Tcl manual entry are +supported by \fBTcl_UtfBackslash\fR. + +.SH KEYWORDS +utf, unicode, backslash + diff --git a/tcl/doc/WrongNumArgs.3 b/tcl/doc/WrongNumArgs.3 index d8185f03130..26b8bf8bc0e 100644 --- a/tcl/doc/WrongNumArgs.3 +++ b/tcl/doc/WrongNumArgs.3 @@ -24,8 +24,7 @@ in its result object. .AP int objc in Number of leading arguments from \fIobjv\fR to include in error message. -.TP -Tcl_Obj *CONST \fIobjv\fR[] (in) +.AP Tcl_Obj "*CONST\ objv[]" in Arguments to command that had the wrong number of arguments. .AP char *message in Additional error information to print after leading arguments diff --git a/tcl/doc/array.n b/tcl/doc/array.n index bcf30918a5f..288e95b05e0 100644 --- a/tcl/doc/array.n +++ b/tcl/doc/array.n @@ -8,7 +8,7 @@ '\" RCS: @(#) $Id$ '\" .so man.macros -.TH array n 7.4 Tcl "Tcl Built-In Commands" +.TH array n 8.3 Tcl "Tcl Built-In Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -58,14 +58,14 @@ array element. The order of the pairs is undefined. If \fIpattern\fR is not specified, then all of the elements of the array are included in the result. If \fIpattern\fR is specified, then only those elements whose names -match \fIpattern\fR (using the glob-style matching rules of +match \fIpattern\fR (using the matching rules of \fBstring match\fR) are included. If \fIarrayName\fR isn't the name of an array variable, or if the array contains no elements, then an empty list is returned. .TP \fBarray names \fIarrayName\fR ?\fIpattern\fR? Returns a list containing the names of all of the elements in -the array that match \fIpattern\fR (using the glob-style matching +the array that match \fIpattern\fR (using the matching rules of \fBstring match\fR). If \fIpattern\fR is omitted then the command returns all of the element names in the array. @@ -111,6 +111,15 @@ The return value is a search identifier that must be used in \fBarray nextelement\fR and \fBarray donesearch\fR commands; it allows multiple searches to be underway simultaneously for the same array. +.VS 8.3 +.TP +\fBarray unset \fIarrayName\fR ?\fIpattern\fR? +Unsets all of the elements in the array that match \fIpattern\fR (using the +matching rules of \fBstring match\fR). If \fIarrayName\fR isn't the name +of an array variable or there are no matching elements in the array, then +an empty string is returned. If \fIpattern\fR is omitted and is it an +array variable, then the command unsets the entire array. +.VE 8.3 .SH KEYWORDS array, element names, search diff --git a/tcl/doc/binary.n b/tcl/doc/binary.n index e03924688a8..f21d691e4ae 100644 --- a/tcl/doc/binary.n +++ b/tcl/doc/binary.n @@ -119,7 +119,7 @@ remaining bits of the last byte will be zeros. For example, .CS \fBbinary format h3h* AB def\fR .CE -will return a string equivalent to \fB\\xba\\xed\\x0f\fR. +will return a string equivalent to \fB\\xba\\x00\\xed\\x0f\fR. .RE .IP \fBH\fR 5 This form is the same as \fBh\fR except that the digits are stored in @@ -128,7 +128,7 @@ high-to-low order within each byte. For example, .CS \fBbinary format H3H* ab DEF\fR .CE -will return a string equivalent to \fB\\xab\\xde\\xf0\fR. +will return a string equivalent to \fB\\xab\\x00\\xde\\xf0\fR. .RE .IP \fBc\fR 5 Stores one or more 8-bit integer values in the output string. If no @@ -142,10 +142,10 @@ error is generated. If the number of elements in the list is greater than \fIcount\fR, then the extra elements are ignored. For example, .RS .CS -\fBbinary format c3cc* {3 -3 128 1} 257 {2 5}\fR +\fBbinary format c3cc* {3 -3 128 1} 260 {2 5}\fR .CE will return a string equivalent to -\fB\\x03\\xfd\\x80\\x01\\x02\\x05\fR, whereas +\fB\\x03\\xfd\\x80\\x04\\x02\\x05\fR, whereas .CS \fBbinary format c {2 5}\fR .CE @@ -186,7 +186,7 @@ example, \fBbinary format i3 {3 -3 65536 1}\fR .CE will return a string equivalent to -\fB\\x03\\x00\\x00\\x00\\xfd\\xff\\xff\\xff\\x00\\x00\\x10\\x00\fR. +\fB\\x03\\x00\\x00\\x00\\xfd\\xff\\xff\\xff\\x00\\x00\\x01\\x00\fR .RE .IP \fBI\fR 5 This form is the same as \fBi\fR except that it stores one or more one @@ -197,7 +197,7 @@ For example, \fBbinary format I3 {3 -3 65536 1}\fR .CE will return a string equivalent to -\fB\\x00\\x00\\x00\\x03\\xff\\xff\\xff\\xfd\\x00\\x10\\x00\\x00\fR. +\fB\\x00\\x00\\x00\\x03\\xff\\xff\\xff\\xfd\\x00\\x01\\x00\\x00\fR .RE .IP \fBf\fR 5 This form is the same as \fBc\fR except that it stores one or more one @@ -297,6 +297,22 @@ immediately with the number of variables that were set. If there are not enough arguments for all of the fields in the format string that consume arguments, then an error is generated. .PP +It is \fBimportant\fR to note that the \fBc\fR, \fBs\fR, and \fBS\fR +(and \fBi\fR and \fBI\fR on 64bit systems) will be scanned into +long data size values. In doing this, values that have their high +bit set (0x80 for chars, 0x8000 for shorts, 0x80000000 for ints), +will be sign extended. Thus the following will occur: +.CS +\fBset signShort [binary format s1 0x8000]\fR +\fBbinary scan $signShort s1 val; \fI# val == 0xFFFF8000\fR +.CE +If you want to produce an unsigned value, then you can mask the return +value to the desired size. For example, to produce an unsigned short +value: +.CS +\fBset val [expr {$val & 0xFFFF}]; \fI# val == 0x8000\fR +.CE +.PP Each type-count pair moves an imaginary cursor through the binary data, reading bytes from the current position. The cursor is initially at position 0 at the beginning of the data. The type may be any one of @@ -318,7 +334,7 @@ This form is the same as \fBa\fR, except trailing blanks and nulls are stripped the scanned value before it is stored in the variable. For example, .RS .CS -\fBbinary scan "abc efghi \\000" a* var1\fR +\fBbinary scan "abc efghi \\000" A* var1\fR .CE will return \fB1\fR with \fBabc efghi\fR stored in \fBvar1\fR. .RE @@ -338,11 +354,11 @@ will return \fB2\fR with \fB11100\fR stored in \fBvar1\fR and \fB1110000110100000\fR stored in \fBvar2\fR. .RE .IP \fBB\fR 5 -This form is the same as \fBB\fR, except the bits are taken in +This form is the same as \fBb\fR, except the bits are taken in high-to-low order within each byte. For example, .RS .CS -\fBbinary scan \\x70\\x87\\x05 b5b* var1 var2\fR +\fBbinary scan \\x70\\x87\\x05 B5B* var1 var2\fR .CE will return \fB2\fR with \fB01110\fR stored in \fBvar1\fR and \fB1000011100000101\fR stored in \fBvar2\fR. @@ -365,7 +381,7 @@ will return \fB2\fR with \fB706\fR stored in \fBvar1\fR and .RE .IP \fBH\fR 5 This form is the same as \fBh\fR, except the digits are taken in -low-to-high order within each byte. For example, +high-to-low order within each byte. For example, .RS .CS \fBbinary scan \\x07\\x86\\x05 H3H* var1 var2\fR @@ -530,3 +546,4 @@ format, scan, tclvars .SH KEYWORDS binary, format, scan + diff --git a/tcl/doc/catch.n b/tcl/doc/catch.n index 73f8c50e9da..c38c4a53113 100644 --- a/tcl/doc/catch.n +++ b/tcl/doc/catch.n @@ -8,7 +8,7 @@ '\" RCS: @(#) $Id$ '\" .so man.macros -.TH catch n "" Tcl "Tcl Built-In Commands" +.TH catch n "8.0" Tcl "Tcl Built-In Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -19,22 +19,48 @@ catch \- Evaluate script and trap exceptional returns .SH DESCRIPTION .PP -The \fBcatch\fR command may be used to prevent errors from aborting -command interpretation. \fBCatch\fR calls the Tcl interpreter recursively -to execute \fIscript\fR, and always returns a TCL_OK code, regardless of -any errors that might occur while executing \fIscript\fR. The return -value from \fBcatch\fR is a decimal string giving the -code returned by the Tcl interpreter after executing \fIscript\fR. -This will be \fB0\fR (TCL_OK) if there were no errors in \fIscript\fR; -otherwise -it will have a non-zero value corresponding to one of the exceptional -return codes (see tcl.h for the definitions of code values). If the -\fIvarName\fR argument is given, then it gives the name of a variable; -\fBcatch\fR will set the variable to the string returned -from \fIscript\fR (either a result or an error message). +The \fBcatch\fR command may be used to prevent errors from aborting command +interpretation. \fBCatch\fR calls the Tcl interpreter recursively to +execute \fIscript\fR, and always returns without raising an error, +regardless of any errors that might occur while executing \fIscript\fR. +.PP +If \fIscript\fR raises an error, \fBcatch\fR will return a non-zero integer +value corresponding to one of the exceptional return codes (see tcl.h +for the definitions of code values). If the \fIvarName\fR argument is +given, then the variable it names is set to the error message from +interpreting \fIscript\fR. +.PP +If \fIscript\fR does not raise an error, \fBcatch\fR will return 0 +(TCL_OK) and set the variable to the value returned from \fIscript\fR. .PP Note that \fBcatch\fR catches all exceptions, including those -generated by \fBbreak\fR and \fBcontinue\fR as well as errors. +generated by \fBbreak\fR and \fBcontinue\fR as well as errors. The +only errors that are not caught are syntax errors found when the +script is compiled. This is because the catch command only catches +errors during runtime. When the catch statement is compiled, the +script is compiled as well and any syntax errors will generate a Tcl +error. + +.SH EXAMPLES + +The \fBcatch\fR command may be used in an \fBif\fR to branch based on +the success of a script. + +.CS +if { [catch {open $someFile w} fid] } { + puts stderr "Could not open $someFile for writing\\n$fid" + exit 1 +} +.CE +The \fBcatch\fR command will not catch compiled syntax errors. The +first time proc \fBfoo\fR is called, the body will be compiled and a +Tcl error will be generated. + +.CS +proc foo {} { + catch {expr {1 +- }} +} +.CE .SH KEYWORDS catch, error diff --git a/tcl/doc/clock.n b/tcl/doc/clock.n index 2af5b6e08f1..d43f590d8a0 100644 --- a/tcl/doc/clock.n +++ b/tcl/doc/clock.n @@ -1,6 +1,7 @@ '\" '\" Copyright (c) 1992-1995 Karl Lehenbauer and Mark Diekhans. '\" Copyright (c) 1995-1997 Sun Microsystems, Inc. +'\" Copyright (c) 1998-1999 Scriptics Corporation '\" '\" This documentation is derived from the time and date facilities of '\" TclX, by Mark Diekhans and Karl Lehenbauer. @@ -11,7 +12,7 @@ '\" RCS: @(#) $Id$ '\" .so man.macros -.TH clock n 7.4 Tcl "Tcl Built-In Commands" +.TH clock n 8.3 Tcl "Tcl Built-In Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -28,12 +29,16 @@ time. The \fIoption\fR argument determines what action is carried out by the command. The legal \fIoptions\fR (which may be abbreviated) are: .TP -\fBclock clicks\fR +.VS 8.3 +\fBclock clicks\fR ?\fB\-milliseconds\fR? Return a high-resolution time value as a system-dependent integer value. The unit of the value is system-dependent but should be the highest resolution clock available on the system such as a CPU cycle -counter. This value should only be used for the relative measurement +counter. If \fB\-milliseconds\fR is specified, then the value is +guaranteed to be of millisecond granularity. +This value should only be used for the relative measurement of elapsed time. +.VE 8.3 .TP \fBclock format \fIclockValue\fR ?\fB\-format \fIstring\fR? ?\fB\-gmt \fIboolean\fR? Converts an integer time value, typically returned by @@ -74,11 +79,11 @@ AM/PM indicator. .IP \fB%S\fR Seconds (00 - 59). .IP \fB%U\fR -Week of year (01 - 52), Sunday is the first day of the week. +Week of year (00 - 52), Sunday is the first day of the week. .IP \fB%w\fR Weekday number (Sunday = 0). .IP \fB%W\fR -Week of year (01 - 52), Monday is the first day of the week. +Week of year (00 - 52), Monday is the first day of the week. .IP \fB%x\fR Locale specific date format. .IP \fB%X\fR @@ -129,6 +134,8 @@ specified, the current date is assumed. If the string does not contain a time zone mnemonic, the local time zone is assumed, unless the \fB\-gmt\fR argument is true, in which case the clock value is calculated assuming that the specified time is relative to Greenwich Mean Time. +\fB-gmt\fR, if specified, affects only the computed time value; it does not +impact the interpretation of \fB-base\fR. .sp If the \fB\-base\fR flag is specified, the next argument should contain an integer clock value. Only the date in this value is used, not the @@ -148,14 +155,20 @@ a 24-hour clock. \fIdate\fR A specific month and day with optional year. The acceptable formats are \fImm/dd\fR?\fI/yy\fR?, \fImonthname dd\fR -?, \fIyy\fR?, \fIdd monthname \fR?\fIyy\fR? and \fIday, dd monthname -yy\fR. The default year is the current year. If the year is less +?, \fIyy\fR?, \fIdd monthname \fR?\fIyy\fR?, \fIday, dd monthname +yy\fR, \fI?CC?yymmdd\fR, \fI?CC?yy-mm-dd\fR, \fIdd-monthname-?CC?yy\fR. +The default year is the current year. If the year is less .VS than 100, we treat the years 00-68 as 2000-2068 and the years 69-99 as 1969-1999. Not all platforms can represent the years 38-70, so an error may result if these years are used. .VE .TP +\fIISO 8601 point-in-time\fR +An ISO 8601 point-in-time specification, such as \fICCyymmddThhmmss\fR, where +T is the literal T, \fICCyymmdd hhmmss\fR, or +\fICCyymmddThh:mm:ss\fR. +.TP \fIrelative time\fR A specification relative to the current time. The format is \fInumber unit\fR acceptable units are \fByear\fR, \fBfortnight\fR, \fBmonth\fR, \fBweek\fR, \fBday\fR, @@ -176,6 +189,19 @@ used. Finally, a correction is applied so that the correct hour of the day is produced after allowing for daylight savings time differences and the correct date is given when going from the end of a long month to a short month. +.sp +Daylight savings time correction is applied only when the relative time +is specified in units of days or more, ie, days, weeks, fortnights, months or +years. This means that when crossing the daylight savings time boundary, +different results will be given for \fBclock scan "1 day"\fR and +\fBclock scan "24 hours"\fR: +.CS +.ta 6c +\fB% clock scan "1 day" -base [clock scan 1999-10-31] +941443200 +% clock scan "24 hours" -base [clock scan 1999-10-31] +941439600\fR +.CE .RE .TP \fBclock seconds\fR @@ -186,3 +212,4 @@ an ``epoch''. You shouldn't assume the value of the epoch. .SH KEYWORDS clock, date, time + diff --git a/tcl/doc/dde.n b/tcl/doc/dde.n new file mode 100644 index 00000000000..3a8015afa79 --- /dev/null +++ b/tcl/doc/dde.n @@ -0,0 +1,135 @@ +'\" +'\" 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$ +'\" +.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 +.SH SYNOPSIS +.sp +\fBpackage require dde 1.1\fR +.sp +\fBdde \fIservername \fR?\fItopic\fR? +.sp +\fBdde ?\-async?\fR \fIcommand service topic \fR?\fIdata\fR? +.BE + +.SH DESCRIPTION +.PP +This command allows an application to send Dynamic Data Exchange (DDE) +command when running under Microsoft Windows. Dynamic Data Exchange is +a mechanism where applications can exchange raw data. Each DDE +transaction needs a \fIservice name\fR and a \fItopic\fR. Both the +\fIservice name\fR and \fItopic\fR are application defined; Tcl uses +the service name \fBTclEval\fR, while the topic name is the name of the +interpreter given by \fBdde servername\fR. Other applications have their +own \fIservice names\fR and \fItopics\fR. For instance, Microsoft Excel +has the service name \fBExcel\fR. +.PP +The only option to the \fBdde\fR command is: +.TP +\fB\-async\fR +Requests asynchronous invocation. This is valid only for the +\fBexecute\fR subcommand. Normally, the \fBdde execute\fR subcommand +waits until the command completes, returning appropriate error +messages. When the \fB\-async\fR option is used, the command returns +immediately, and no error information is available. +.SH "DDE COMMANDS" +.PP +The following commands are a subset of the full Dynamic Data Exchange +set of commands. +.TP +\fBdde servername \fR?\fItopic\fR? +\fBdde servername\fR registers the interpreter as a DDE server with +the service name \fBTclEval\fR and the topic name specified by \fItopic\fR. +If no \fItopic\fR is given, \fBdde servername\fR returns the name +of the current topic or the empty string if it is not registered as a service. +.TP +\fBdde execute \fIservice topic data\fR +\fBdde execute\fR takes the \fIdata\fR and sends it to the server +indicated by \fIservice\fR with the topic indicated by +\fItopic\fR. Typically, \fIservice\fR is the name of an application, +and \fItopic\fR is a file to work on. The \fIdata\fR field is given +to the remote application. Typically, the application treats the +\fIdata\fR field as a script, and the script is run in the +application. The command returns an error if the script did not +run. If the \fB\-async\fR flag was used, the command +returns immediately with no error. +.TP +\fBdde poke \fIservice topic item data\fR +\fBdde poke\fR passes the \fIdata\fR to the server indicated by +\fIservice\fR using the \fItopic\fR and \fIitem\fR specified. Typically, +\fIservice\fR is the name of an application. \fItopic\fR is application +specific but can be a command to the server or the name of a file to work +on. The \fIitem\fR is also application specific and is often not used, but +it must always be non-null. The \fIdata\fR field is given to the remote +application. +.TP +\fBdde request \fIservice topic item\fR +\fBdde request\fR is typically used to get the value of something; the +value of a cell in Microsoft Excel or the text of a selection in +Microsoft Word. \fIservice\fR is typically the name of an application, +\fItopic\fR is typically the name of the file, and \fIitem\fR is +application-specific. The command returns the value of \fIitem\fR as +defined in the application. +.TP +\fBdde services \fIservice topic\fR +\fBdde services\fR returns a list of service-topic pairs that +currently exist on the machine. If \fIservice\fR and \fItopic\fR are +both null strings ({}), then all service-topic pairs currently +available on the system are returned. If \fIservice\fR is null and +\fItopic\fR is not, then all services with the specified topic are +returned. If \fIservice\fR is not null and \fItopic\fR is, all topics +for a given service are returned. If both are not null, if that +service-topic pair currently exists, it is returned; otherwise, null +is returned. +.TP +\fBdde eval \fItopic cmd \fR?\fIarg arg ...\fR? +\fBdde eval\fR evaluates a command and its arguments using the +interpreter specified by \fItopic\fR. The DDE service must be the +\fBTclEval\fR service. This command can be used to replace send on +Windows. +.SH "DDE AND TCL" +A Tcl interpreter always has a service name of \fBTclEval\fR. Each +different interpreter of all running Tcl applications must be +given a unique +name specified by \fBdde servername\fR. Each interp is available as a +DDE topic only if the \fBdde servername\fR command was used to set the +name of the topic for each interp. So a \fBdde services TclEval {}\fR +command will return a list of service-topic pairs, where each of the +currently running interps will be a topic. +.PP +When Tcl processes a \fBdde execute\fR command, the data for the +execute is run as a script in the interp named by the topic of the +\fBdde execute\fR command. +.PP +When Tcl processes a \fBdde request\fR command, it returns the value of the +variable given in the dde command in the context of the interp named by the +dde topic. Tcl reserves the variable \fB$TCLEVAL$EXECUTE$RESULT\fR for +internal use, and \fBdde request\fR commands for that variable will give +unpredictable results. +.PP +An external application which wishes to run a script in Tcl should have +that script store its result in a variable, run the \fBdde execute\fR +command, and the run \fBdde request\fR to get the value of the +variable. +.PP +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, winfo, send +.SH KEYWORDS +application, dde, name, remote execution + diff --git a/tcl/doc/encoding.n b/tcl/doc/encoding.n new file mode 100644 index 00000000000..740b9dfadf3 --- /dev/null +++ b/tcl/doc/encoding.n @@ -0,0 +1,79 @@ +'\" +'\" 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$ +'\" +.so man.macros +.TH encoding n "8.1" Tcl "Tcl Built-In Commands" +.BS +.SH NAME +encoding \- Manipulate encodings +.SH SYNOPSIS +\fBencoding \fIoption\fR ?\fIarg arg ...\fR? +.BE + +.SH INTRODUCTION +.PP +Strings in Tcl are encoded using 16-bit Unicode characters. Different +operating system interfaces or applications may generate strings in +other encodings such as Shift-JIS. The \fBencoding\fR command helps +to bridge the gap between Unicode and these other formats. + +.SH DESCRIPTION +.PP +Performs one of several encoding related operations, depending on +\fIoption\fR. The legal \fIoption\fRs are: +.TP +\fBencoding convertfrom ?\fIencoding\fR? \fIdata\fR +Convert \fIdata\fR to Unicode from the specified \fIencoding\fR. The +characters in \fIdata\fR are treated as binary data where the lower +8-bits of each character is taken as a single byte. The resulting +sequence of bytes is treated as a string in the specified +\fIencoding\fR. If \fIencoding\fR is not specified, the current +system encoding is used. +.TP +\fBencoding convertto ?\fIencoding\fR? \fIstring\fR +Convert \fIstring\fR from Unicode to the specified \fIencoding\fR. +The result is a sequence of bytes that represents the converted +string. Each byte is stored in the lower 8-bits of a Unicode +character. If \fIencoding\fR is not specified, the current +system encoding is used. +.TP +\fBencoding names\fR +Returns a list containing the names of all of the encodings that are +currently available. +.TP +\fBencoding system\fR ?\fIencoding\fR? +Set the system encoding to \fIencoding\fR. If \fIencoding\fR is +omitted then the command returns the current system encoding. The +system encoding is used whenever Tcl passes strings to system calls. + +.SH EXAMPLE +.PP +It is common practice to write script files using a text editor that +produces output in the euc-jp encoding, which represents the ASCII +characters as singe bytes and Japanese characters as two bytes. This +makes it easy to embed literal strings that correspond to non-ASCII +characters by simply typing the strings in place in the script. +However, because the \fBsource\fR command always reads files using the +ISO8859-1 encoding, Tcl will treat each byte in the file as a separate +character that maps to the 00 page in Unicode. The +resulting Tcl strings will not contain the expected Japanese +characters. Instead, they will contain a sequence of Latin-1 +characters that correspond to the bytes of the original string. The +\fBencoding\fR command can be used to convert this string to the +expected Japanese Unicode characters. For example, +.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 + +.SH KEYWORDS +encoding diff --git a/tcl/doc/exec.n b/tcl/doc/exec.n index 8fc72c1195e..dc85e3754f1 100644 --- a/tcl/doc/exec.n +++ b/tcl/doc/exec.n @@ -202,10 +202,11 @@ instead of ``applbakery.default''). Two or more forward or backward slashes in a row in a path refer to a network path. For example, a simple concatenation of the root directory \fBc:/\fR with a subdirectory \fB/windows/system\fR will yield -\fBc://windows/system\fR (two slashes together), which refers to the -directory \fB/system\fR on the machine \fBwindows\fR (and the \fBc:/\fR is -ignored), and is not equivalent to \fBc:/windows/system\fR, which describes -a directory on the current computer. +\fBc://windows/system\fR (two slashes together), which refers to the mount +point called \fBsystem\fR on the machine called \fBwindows\fR (and the +\fBc:/\fR is ignored), and is not equivalent to \fBc:/windows/system\fR, +which describes a directory on the current computer. The \fBfile join\fR +command should be used to concatenate path components. .TP \fBWindows NT\fR . @@ -264,7 +265,7 @@ the caller must prepend ``\fBcommand.com /c\0\fR'' to the desired command. Once a 16-bit DOS application has read standard input from a console and then quit, all subsequently run 16-bit DOS applications will see the standard input as already closed. 32-bit applications do not have this -problem and will run correctly even after a 16-bit DOS application thinks +problem and will run correctly, even after a 16-bit DOS application thinks that standard input is closed. There is no known workaround for this bug at this time. .sp @@ -282,8 +283,8 @@ other end of the pipe must be closed before the 16-bit DOS application begins executing. All standard output or error from a 16-bit DOS application to a pipe is collected into temporary files; the application must terminate before the temporary files are redirected to the next stage -of the pipeline. This is due to a workaround for a Windows 95 bug in the -implementation of pipes, and is how the Windows 95 command line interpreter +of the pipeline. This is due to a workaround for a Windows 95 bug in the +implementation of pipes, and is how the standard Windows 95 DOS shell handles pipes itself. .sp Certain applications, such as \fBcommand.com\fR, should not be executed @@ -293,55 +294,6 @@ output may fail, hang Tcl, or even hang the system if their own private console window is not available to them. .RE .TP -\fBWindows 3.X\fR -. -When attempting to execute an application, \fBexec\fR first searches for the -name as it was specified. Then, in order, \fB.com\fR, \fB.exe\fR, and \fB.bat\fR -are appended to the end of the specified name and it searches for -the longer name. If a directory name was not specified as part of the -application name, the following directories are automatically searched in -order when attempting to locate the application: -.sp -.RS -.RS -The directory from which the Tcl executable was loaded. -.br -The current directory. -.br -The Windows 3.X system directory. -.br -The Windows 3.X home directory. -.br -The directories listed in the path. -.RE -.sp -In order to execute the shell builtin commands like \fBdir\fR and \fBcopy\fR, -the caller must prepend ``\fBcommand.com /c\0\fR'' to the desired command. -.sp -16-bit and 32-bit DOS and Windows applications may be executed. However, -redirection and piping of standard IO only works with 16-bit DOS -applications. 32-bit applications always see standard input as already -closed, and any standard output or error is discarded, no matter where in the -pipeline the application occurs or what redirection symbols are used by the -caller. Additionally, for 16-bit applications, standard error is always -sent to the same place as standard output; it cannot be redirected to a -separate location. In order to achieve pseudo-redirection for 32-bit -applications, the 32-bit application must instead be written to take command -line arguments that specify the files that it should read from and write to -and open those files itself. -.sp -All applications, both 16-bit and 32-bit, run synchronously; each application -runs to completion before the next one in the pipeline starts. Temporary files -are used to simulate piping between applications. The \fBexec\fR -command cannot be used to start an application in the background. -.sp -When standard input is redirected from an open file using the -``\fB@\0\fIfileId\fR'' notation, the open file is completely read up to its -end. This is slightly different than under Windows 95 or NT, where the child -application consumes from the open file only as much as it wants. -Redirecting to an open file is supported as normal. -.RE -.TP \fBMacintosh\fR The \fBexec\fR command is not implemented and does not exist under Macintosh. .TP diff --git a/tcl/doc/expr.n b/tcl/doc/expr.n index 27545611cff..0827aed933d 100644 --- a/tcl/doc/expr.n +++ b/tcl/doc/expr.n @@ -1,6 +1,6 @@ '\" '\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. +'\" 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. @@ -8,7 +8,7 @@ '\" RCS: @(#) $Id$ '\" .so man.macros -.TH expr n 8.0 Tcl "Tcl Built-In Commands" +.TH expr n 8.3 Tcl "Tcl Built-In Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -184,30 +184,80 @@ invoking the \fBexpr\fR command. Tcl supports the following mathematical functions in expressions: .DS .ta 3c 6c 9c -\fBacos\fR \fBcos\fR \fBhypot\fR \fBsinh\fR -\fBasin\fR \fBcosh\fR \fBlog\fR \fBsqrt\fR -\fBatan\fR \fBexp\fR \fBlog10\fR \fBtan\fR -\fBatan2\fR \fBfloor\fR \fBpow\fR \fBtanh\fR -\fBceil\fR \fBfmod\fR \fBsin\fR +\fBabs\fR \fBcosh\fR \fBlog\fR \fBsqrt\fR +\fBacos\fR \fBdouble\fR \fBlog10\fR \fBsrand\fR +\fBasin\fR \fBexp\fR \fBpow\fR \fBtan\fR +\fBatan\fR \fBfloor\fR \fBrand\fR \fBtanh\fR +\fBatan2\fR \fBfmod\fR \fBround\fR +\fBceil\fR \fBhypot\fR \fBsin\fR +\fBcos\fR \fBint\fR \fBsinh\fR .DE -Each of these functions invokes the math library function of the same -name; see the manual entries for the library functions for details -on what they do. Tcl also implements the following functions for -conversion between integers and floating-point numbers and the -generation of random numbers: +.PP .TP \fBabs(\fIarg\fB)\fR Returns the absolute value of \fIarg\fR. \fIArg\fR may be either integer or floating-point, and the result is returned in the same form. .TP +\fBacos(\fIarg\fB)\fR +Returns the arc cosine of \fIarg\fR, in the range [0,pi] +radians. \fIArg\fR should be in the range [-1,1]. +.TP +\fBasin(\fIarg\fB)\fR +Returns the arc sine of \fIarg\fR, in the range [-pi/2,pi/2] radians. +\fIArg\fR should be in the range [-1,1]. +.TP +\fBatan(\fIarg\fB)\fR +Returns the arc tangent of \fIarg\fR, in the range [-pi/2,pi/2] radians. +.TP +\fBatan2(\fIx, y\fB)\fR +Returns the arc tangent of \fIy\fR/\fIx\fR, in the range [-pi,pi] +radians. \fIx\fR and \fIy\fR cannot both be 0. +.TP +\fBceil(\fIarg\fB)\fR +Returns the smallest integer value not less than \fIarg\fR. +.TP +\fBcos(\fIarg\fB)\fR +Returns the cosine of \fIarg\fR, measured in radians. +.TP +\fBcosh(\fIarg\fB)\fR +Returns the hyperbolic cosine of \fIarg\fR. If the result would cause +an overflow, an error is returned. +.TP \fBdouble(\fIarg\fB)\fR If \fIarg\fR is a floating value, returns \fIarg\fR, otherwise converts \fIarg\fR to floating and returns the converted value. .TP +\fBexp(\fIarg\fB)\fR +Returns the exponential of \fIarg\fR, defined as e**\fIarg\fR. If the +result would cause an overflow, an error is returned. +.TP +\fBfloor(\fIarg\fB)\fR +Returns the largest integral value not greater than \fIarg\fR. +.TP +\fBfmod(\fIx, y\fB)\fR +Returns the floating-point remainder of the division of \fIx\fR by +\fIy\fR. If \fIy\fR is 0, an error is returned. +.TP +\fBhypot(\fIx, y\fB)\fR +Computes the length of the hypotenuse of a right-angled triangle +(\fIx\fR*\fIx\fR+\fIy\fR*\fIy\fR). +.TP \fBint(\fIarg\fB)\fR If \fIarg\fR is an integer value, returns \fIarg\fR, otherwise converts \fIarg\fR to integer by truncation and returns the converted value. .TP +\fBlog(\fIarg\fB)\fR +Returns the natural logarithm of \fIarg\fR. \fIArg\fR must be a +positive value. +.TP +\fBlog10(\fIarg\fB)\fR +Returns the base 10 logarithm of \fIarg\fR. \fIArg\fR must be a +positive value. +.TP +\fBpow(\fIx, y\fB)\fR +Computes the value of \fIx\fR raised to the power \fIy\fR. If \fIx\fR +is negative, \fIy\fR must be an integer value. +.TP \fBrand()\fR Returns a floating point number from zero to just less than one or, in mathematical terms, the range [0,1). The seed comes from the @@ -218,10 +268,26 @@ function. If \fIarg\fR is an integer value, returns \fIarg\fR, otherwise converts \fIarg\fR to integer by rounding and returns the converted value. .TP +\fBsin(\fIarg\fB)\fR +Returns the sine of \fIarg\fR, measured in radians. +.TP +\fBsinh(\fIarg\fB)\fR +Returns the hyperbolic sine of \fIarg\fR. If the result would cause +an overflow, an error is returned. +.TP +\fBsqrt(\fIarg\fB)\fR +Returns the square root of \fIarg\fR. \fIArg\fR must be non-negative. +.TP \fBsrand(\fIarg\fB)\fR The \fIarg\fR, which must be an integer, is used to reset the seed for the random number generator. Returns the first random number from that seed. Each interpreter has it's own seed. +.TP +\fBtan(\fIarg\fB)\fR +Returns the tangent of \fIarg\fR, measured in radians. +.TP +\fBtanh(\fIarg\fB)\fR +Returns the hyperbolic tangent of \fIarg\fR. .PP In addition to these predefined functions, applications may define additional functions using \fBTcl_CreateMathFunc\fR(). @@ -282,11 +348,10 @@ 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 compare\fR command instead. +operands could be arbitrary; it's better in these cases to use +the \fBstring\fR command instead. .SH "PERFORMANCE CONSIDERATIONS" -.VS .PP Enclose expressions in braces for the best speed and the smallest storage requirements. @@ -317,7 +382,7 @@ 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. -.VE .SH KEYWORDS arithmetic, boolean, compare, expression, fuzzy comparison + diff --git a/tcl/doc/fconfigure.n b/tcl/doc/fconfigure.n index 80301fb672a..dc84a52dd9d 100644 --- a/tcl/doc/fconfigure.n +++ b/tcl/doc/fconfigure.n @@ -7,7 +7,7 @@ '\" RCS: @(#) $Id$ '\" .so man.macros -.TH fconfigure n 7.5 Tcl "Tcl Built-In Commands" +.TH fconfigure n 8.1 Tcl "Tcl Built-In Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -51,122 +51,144 @@ using the Tcl event loop (e.g. by calling \fBTcl_DoOneEvent\fR or invoking the \fBvwait\fR command). .TP \fB\-buffering\fR \fInewValue\fR +. If \fInewValue\fR is \fBfull\fR then the I/O system will buffer output until its internal buffer is full or until the \fBflush\fR command is invoked. If \fInewValue\fR is \fBline\fR, then the I/O system will automatically flush output for the channel whenever a newline character is output. If \fInewValue\fR is \fBnone\fR, the I/O system will flush -automatically after every output operation. -The default is for \fB\-buffering\fR to be set to \fBfull\fR except for -channels that connect to terminal-like devices; for these channels the -initial setting is \fBline\fR. +automatically after every output operation. The default is for +\fB\-buffering\fR to be set to \fBfull\fR except for channels that +connect to terminal-like devices; for these channels the initial setting +is \fBline\fR. Additionally, \fBstdin\fR and \fBstdout\fR are +intially set to \fBline\fR, and \fBstderr\fR is set to \fBnone\fR. .TP \fB\-buffersize\fR \fInewSize\fR +. \fINewvalue\fR must be an integer; its value is used to set the size of buffers, in bytes, subsequently allocated for this channel to store input or output. \fINewvalue\fR must be between ten and one million, allowing buffers of ten to one million bytes in size. +.VS 8.1 br +.TP +\fB\-encoding\fR \fIname\fR +. +This option is used to specify the encoding of the channel, so that the data +can be converted to and from Unicode for use in Tcl. For instance, in +order for Tcl to read characters from a Japanese file in \fBshiftjis\fR +and properly process and display the contents, the encoding would be set +to \fBshiftjis\fR. Thereafter, when reading from the channel, the bytes in +the Japanese file would be converted to Unicode as they are read. +Writing is also supported \- as Tcl strings are written to the channel they +will automatically be converted to the specified encoding on output. +.RS +.PP +If a file contains pure binary data (for instance, a JPEG image), the +encoding for the channel should be configured to be \fBbinary\fR. Tcl +will then assign no interpretation to the data in the file and simply read or +write raw bytes. The Tcl \fBbinary\fR command can be used to manipulate this +byte-oriented data. +.PP +The default encoding for newly opened channels is the same platform- and +locale-dependent system encoding used for interfacing with the operating +system. +.RE +.VE .TP \fB\-eofchar\fR \fIchar\fR .TP \fB\-eofchar\fR \fB{\fIinChar outChar\fB}\fR -This option supports DOS file systems that use Control-z (\ex1a) as -an end of file marker. -If \fIchar\fR is not an empty string, then this character signals -end of file when it is encountered during input. -For output, the end of file character is output when -the channel is closed. -If \fIchar\fR is the empty string, then there is no special -end of file character marker. -For read-write channels, a two-element list specifies -the end of file marker for input and output, respectively. -As a convenience, when setting the end-of-file character -for a read-write channel -you can specify a single value that will apply to both reading and writing. -When querying the end-of-file character of a read-write channel, -a two-element list will always be returned. -The default value for \fB\-eofchar\fR is the empty string in all -cases except for files under Windows. In that case the \fB\-eofchar\fR -is Control-z (\ex1a) for reading and the empty string for writing. +. +This option supports DOS file systems that use Control-z (\ex1a) as an +end of file marker. If \fIchar\fR is not an empty string, then this +character signals end-of-file when it is encountered during input. For +output, the end-of-file character is output when the channel is closed. +If \fIchar\fR is the empty string, then there is no special end of file +character marker. For read-write channels, a two-element list specifies +the end of file marker for input and output, respectively. As a +convenience, when setting the end-of-file character for a read-write +channel you can specify a single value that will apply to both reading +and writing. When querying the end-of-file character of a read-write +channel, a two-element list will always be returned. The default value +for \fB\-eofchar\fR is the empty string in all cases except for files +under Windows. In that case the \fB\-eofchar\fR is Control-z (\ex1a) for +reading and the empty string for writing. .TP \fB\-translation\fR \fImode\fR .TP -\fB\-translation\fR \fB{\fIinMode outMode\fB}\fR -In Tcl scripts the end of a line is always represented using a -single newline character (\en). -However, in actual files and devices the end of a line may be -represented differently on different platforms, or even for -different devices on the same platform. For example, under UNIX -newlines are used in files, whereas carriage-return-linefeed -sequences are normally used in network connections. -On input (i.e., with \fBgets\fP and \fBread\fP) -the Tcl I/O system automatically translates the external end-of-line -representation into newline characters. -Upon output (i.e., with \fBputs\fP), -the I/O system translates newlines to the external -end-of-line representation. -The default translation mode, \fBauto\fP, handles all the common -cases automatically, but the \fB\-translation\fR option provides -explicit control over the end of line translations. +\fB\-translation\fR \fB{\fIinMode outMode\fB}\fR +. +In Tcl scripts the end of a line is always represented using a single +newline character (\en). However, in actual files and devices the end of +a line may be represented differently on different platforms, or even for +different devices on the same platform. For example, under UNIX newlines +are used in files, whereas carriage-return-linefeed sequences are +normally used in network connections. On input (i.e., with \fBgets\fP +and \fBread\fP) the Tcl I/O system automatically translates the external +end-of-line representation into newline characters. Upon output (i.e., +with \fBputs\fP), the I/O system translates newlines to the external +end-of-line representation. The default translation mode, \fBauto\fP, +handles all the common cases automatically, but the \fB\-translation\fR +option provides explicit control over the end of line translations. .RS .PP The value associated with \fB\-translation\fR is a single item for -read-only and write-only channels. -The value is a two-element list for read-write channels; -the read translation mode is the first element of the list, -and the write translation mode is the second element. -As a convenience, when setting the translation mode for a read-write channel -you can specify a single value that will apply to both reading and writing. -When querying the translation mode of a read-write channel, -a two-element list will always be returned. -The following values are currently supported: +read-only and write-only channels. The value is a two-element list for +read-write channels; the read translation mode is the first element of +the list, and the write translation mode is the second element. As a +convenience, when setting the translation mode for a read-write channel +you can specify a single value that will apply to both reading and +writing. When querying the translation mode of a read-write channel, a +two-element list will always be returned. The following values are +currently supported: .TP \fBauto\fR -As the input translation mode, \fBauto\fR treats any of newline (\fBlf\fP), -carriage return (\fBcr\fP), or carriage return followed by a newline (\fBcrlf\fP) -as the end of line representation. The end of line representation can -even change from line-to-line, and all cases are translated to a newline. -As the output translation mode, \fBauto\fR chooses a platform specific -representation; for sockets on all platforms Tcl -chooses \fBcrlf\fR, for all Unix flavors, it chooses \fBlf\fR, for the +. +As the input translation mode, \fBauto\fR treats any of newline +(\fBlf\fP), carriage return (\fBcr\fP), or carriage return followed by a +newline (\fBcrlf\fP) as the end of line representation. The end of line +representation can even change from line-to-line, and all cases are +translated to a newline. As the output translation mode, \fBauto\fR +chooses a platform specific representation; for sockets on all platforms +Tcl chooses \fBcrlf\fR, for all Unix flavors, it chooses \fBlf\fR, for the Macintosh platform it chooses \fBcr\fR and for the various flavors of -Windows it chooses \fBcrlf\fR. -The default setting for \fB\-translation\fR is \fBauto\fR for both -input and output. +Windows it chooses \fBcrlf\fR. The default setting for +\fB\-translation\fR is \fBauto\fR for both input and output. +.VS 8.1 br .TP -\fBbinary\fR +\fBbinary\fR +. No end-of-line translations are performed. This is nearly identical to \fBlf\fP mode, except that in addition \fBbinary\fP mode also sets the -end of file character to the empty string, which disables it. -See the description of -\fB\-eofchar\fP for more information. +end-of-file character to the empty string (which disables it) and sets the +encoding to \fBbinary\fR (which disables encoding filtering). See the +description of \fB\-eofchar\fR and \fB\-encoding\fR for more information. +.VE .TP \fBcr\fR -The end of a line in the underlying file or device is represented -by a single carriage return character. -As the input translation mode, \fBcr\fP mode converts carriage returns -to newline characters. -As the output translation mode, \fBcr\fP mode -translates newline characters to carriage returns. -This mode is typically used on Macintosh platforms. +. +The end of a line in the underlying file or device is represented by a +single carriage return character. As the input translation mode, +\fBcr\fP mode converts carriage returns to newline characters. As the +output translation mode, \fBcr\fP mode translates newline characters to +carriage returns. This mode is typically used on Macintosh platforms. .TP \fBcrlf\fR -The end of a line in the underlying file or device is represented -by a carriage return character followed by a linefeed character. -As the input translation mode, \fBcrlf\fP mode converts -carriage-return-linefeed sequences -to newline characters. -As the output translation mode, \fBcrlf\fP mode -translates newline characters to -carriage-return-linefeed sequences. -This mode is typically used on Windows platforms and for network -connections. +. +The end of a line in the underlying file or device is represented by a +carriage return character followed by a linefeed character. As the input +translation mode, \fBcrlf\fP mode converts carriage-return-linefeed +sequences to newline characters. As the output translation mode, +\fBcrlf\fP mode translates newline characters to carriage-return-linefeed +sequences. This mode is typically used on Windows platforms and for +network connections. .TP \fBlf\fR -The end of a line in the underlying file or device is represented -by a single newline (linefeed) character. -In this mode no translations occur during either input or output. -This mode is typically used on UNIX platforms. +. +The end of a line in the underlying file or device is represented by a +single newline (linefeed) character. In this mode no translations occur +during either input or output. This mode is typically used on UNIX +platforms. .RE .PP @@ -175,4 +197,5 @@ close(n), flush(n), gets(n), puts(n), read(n), socket(n) .SH KEYWORDS blocking, buffering, carriage return, end of line, flushing, linemode, -newline, nonblocking, platform, translation +newline, nonblocking, platform, translation, encoding, filter, byte array, +binary diff --git a/tcl/doc/file.n b/tcl/doc/file.n index 530b9ffacf7..886e32f9c3e 100644 --- a/tcl/doc/file.n +++ b/tcl/doc/file.n @@ -8,7 +8,7 @@ '\" RCS: @(#) $Id$ '\" .so man.macros -.TH file n 7.6 Tcl "Tcl Built-In Commands" +.TH file n 8.3 Tcl "Tcl Built-In Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -26,14 +26,14 @@ substitution is done before executing the command (see the manual entry for file name. Any unique abbreviation for \fIoption\fR is acceptable. The valid options are: .TP -\fBfile atime \fIname\fR +\fBfile atime \fIname\fR ?\fBtime\fR? . -Returns a decimal string giving the time at which file \fIname\fR -was last accessed. The time is measured in the standard POSIX -fashion as seconds from a fixed starting time (often January 1, 1970). -If the file doesn't exist or its access time cannot be queried then an -error is generated. -.VS +Returns a decimal string giving the time at which file \fIname\fR was last +accessed. If \fItime\fR is specified, it is an access time to set +for the file. The time is measured in the standard POSIX fashion as +seconds from a fixed starting time (often January 1, 1970). If the file +doesn't exist or its access time cannot be queried or set then an error is +generated. On Windows, FAT file systems do not support access time. .TP \fBfile attributes \fIname\fR .br @@ -47,13 +47,18 @@ flags and their values. The second form returns the value for the specific option. The third form sets one or more of the values. The values are as follows: .PP -On Unix, \fB-group\fR gets or sets the group name for the file. A group id can -be given to the command, but it returns a group name. \fB-owner\fR -gets or sets the user name of the owner of the file. The command -returns the owner name, but the numerical id can be passed when -setting the owner. \fB-permissions\fR sets or retrieves the octal code -that chmod(1) uses. This command does not support the symbolic -attributes for chmod(1) at this time. +On Unix, \fB-group\fR gets or sets the group name for the file. A group id +can be given to the command, but it returns a group name. \fB-owner\fR gets +or sets the user name of the owner of the file. The command returns the +owner name, but the numerical id can be passed when setting the +owner. \fB-permissions\fR sets or retrieves the octal code that chmod(1) +uses. This command does also has limited support for setting using the +symbolic attributes for chmod(1), of the form [ugo]?[[+\-=][rwxst],[...]], +where multiple symbolic attributes can be separated by commas (example: +\fBu+s,go\-rw\fR add sticky bit for user, remove read and write +permissions for group and other). A simplified \fBls\fR style string, +of the form rwxrwxrwx (must be 9 characters), is also supported +(example: \fBrwxr\-xr\-t\fR is equivalent to 01755). .PP On Windows, \fB-archive\fR gives the value or sets or clears the archive attribute of the file. \fB-hidden\fR gives the value or sets @@ -72,8 +77,16 @@ attribute of the file. Note that directories can only be locked if File Sharing is turned on. \fB-type\fR gives or sets the Finder file type for the file. .RE +.VS +.TP +\fBfile channels ?\fIpattern\fR? +. +If \fIpattern\fR isn't specified, returns a list of names of all +registered open channels in this interpreter. If \fIpattern\fR is +specified, only those names matching \fIpattern\fR are returned. Matching +is determined using the same rules as for \fBstring match\fR. .VE -.PP +.TP \fBfile copy \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR \fItarget\fR .br \fBfile copy \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR ?\fIsource\fR ...? \fItargetDir\fR @@ -188,21 +201,20 @@ no action is taken and no error is returned. Trying to overwrite an existing file with a directory will result in an error. Arguments are processed in the order specified, halting at the first error, if any. .TP -\fBfile mtime \fIname\fR +\fBfile mtime \fIname\fR ?\fItime\fR? . -Returns a decimal string giving the time at which file \fIname\fR was -last modified. The time is measured in the standard POSIX fashion as -seconds from a fixed starting time (often January 1, 1970). If the file -doesn't exist or its modified time cannot be queried then an error is -generated. -.VS +Returns a decimal string giving the time at which file \fIname\fR was last +modified. If \fItime\fR is specified, it is a modification time to set for +the file (equivalent to Unix \fBtouch\fR). The time is measured in the +standard POSIX fashion as seconds from a fixed starting time (often January +1, 1970). If the file doesn't exist or its modified time cannot be queried +or set then an error is generated. .TP \fBfile nativename \fIname\fR . Returns the platform-specific name of the file. This is useful if the filename is needed to pass to a platform-specific call, such as exec under Windows or AppleScript on the Macintosh. -.VE .TP \fBfile owned \fIname\fR . @@ -305,13 +317,14 @@ Returns a string giving the type of file \fIname\fR, which will be one of .TP \fBfile volume\fR . -Returns the absolute paths to the volumes mounted on the system, as a proper -Tcl list. On the Macintosh, this will be a list of the mounted drives, -both local and network. N.B. if two drives have the same name, they will -both appear on the volume list, but there is currently no way, from Tcl, to -access any but the first of these drives. On UNIX, the command will always return -"/", since all filesystems are locally mounted. On Windows, it will return -a list of the available local drives (e.g. {a:/ c:/}). +Returns the absolute paths to the volumes mounted on the system, as a +proper Tcl list. On the Macintosh, this will be a list of the mounted +drives, both local and network. N.B. if two drives have the same name, +they will both appear on the volume list, but there is currently no way, +from Tcl, to access any but the first of these drives. On UNIX, the +command will always return "/", since all filesystems are locally mounted. +On Windows, it will return a list of the available local drives +(e.g. {a:/ c:/}). .TP \fBfile writable \fIname\fR . diff --git a/tcl/doc/filename.n b/tcl/doc/filename.n index b0a979aa084..31001e41c61 100644 --- a/tcl/doc/filename.n +++ b/tcl/doc/filename.n @@ -26,7 +26,7 @@ Instead, portable scripts must use the \fBfile split\fR and \fBfile join\fR commands to manipulate file names (see the \fBfile\fR manual entry for more details). -.SH PATH TYPES +.SH "PATH TYPES" .PP File names are grouped into three general types based on the starting point for the path used to specify the file: absolute, relative, and @@ -39,7 +39,7 @@ current volume, or relative to the current directory of the specified volume. The \fBfile pathtype\fR command can be used to determine the type of a given path. -.SH PATH SYNTAX +.SH "PATH SYNTAX" .PP The rules for native names depend on the value reported in the Tcl array element \fBtcl_platform(platform)\fR: @@ -163,7 +163,7 @@ Volume-relative path to a file \fBfoo\fR in the root directory of the current volume. .RE -.SH TILDE SUBSTITUTION +.SH "TILDE SUBSTITUTION" .PP In addition to the file name rules described above, Tcl also supports \fIcsh\fR-style tilde substitution. If a file name starts with a @@ -181,7 +181,7 @@ use a tilde followed by a user name will generate an error. File names that have a tilde without a user name will be substituted using the \fB$HOME\fR environment variable, just like for Unix. -.SH PORTABILITY ISSUES +.SH "PORTABILITY ISSUES" .PP Not all file systems are case sensitive, so scripts should avoid code that depends on the case of characters in a file name. In addition, diff --git a/tcl/doc/format.n b/tcl/doc/format.n index d8d55622a20..9d196e204b1 100644 --- a/tcl/doc/format.n +++ b/tcl/doc/format.n @@ -8,7 +8,7 @@ '\" RCS: @(#) $Id$ '\" .so man.macros -.TH format n "" Tcl "Tcl Built-In Commands" +.TH format n 8.1 Tcl "Tcl Built-In Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -154,9 +154,11 @@ Convert integer to unsigned octal string. \fBx\fR or \fBX\fR Convert integer to unsigned hexadecimal string, using digits ``0123456789abcdef'' for \fBx\fR and ``0123456789ABCDEF'' for \fBX\fR). +.VS .TP 10 \fBc\fR -Convert integer to the 8-bit character it represents. +Convert integer to the Unicode character it represents. +.VE .TP 10 \fBs\fR No conversion; just insert string. diff --git a/tcl/doc/glob.n b/tcl/doc/glob.n index bfad9e4da32..458e1ff6121 100644 --- a/tcl/doc/glob.n +++ b/tcl/doc/glob.n @@ -8,7 +8,7 @@ '\" RCS: @(#) $Id$ '\" .so man.macros -.TH glob n 7.5 Tcl "Tcl Built-In Commands" +.TH glob n 8.3 Tcl "Tcl Built-In Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -26,11 +26,70 @@ of the \fIpattern\fR arguments. If the initial arguments to \fBglob\fR start with \fB\-\fR then they are treated as switches. The following switches are currently supported: -.TP 15 +.VS 8.3 +.TP +\fB\-directory\fR \fIdirectory\fR +Search for files which match the given patterns starting in the given +\fIdirectory\fR. This allows searching of directories whose name +contains glob-sensitive characters without the need to quote such +characters explicitly. This option may not be used in conjunction with +\fB\-path\fR. +.TP +\fB\-join\fR +The remaining pattern arguments are treated as a single pattern +obtained by joining the arguments with directory separators. +.VE 8.3 +.TP \fB\-nocomplain\fR Allows an empty list to be returned without error; without this switch an error is returned if the result list would be empty. -.TP 15 +.VS 8.3 +.TP +\fB\-path\fR \fIpathPrefix\fR +Search for files with the given \fIpathPrefix\fR where the rest of the name +matches the given patterns. This allows searching for files with names +similar to a given file even when the names contain glob-sensitive +characters. This option may not be used in conjunction with +\fB\-directory\fR. +.TP +\fB\-types\fR \fItypeList\fR +Only list files or directories which match \fItypeList\fR, where the items +in the list have two forms. The first form is like the \-type option of +the Unix find command: +\fIb\fR (block special file), +\fIc\fR (character special file), +\fId\fR (directory), +\fIf\fR (plain file), +\fIl\fR (symbolic link), +\fIp\fR (named pipe), +or \fIs\fR (socket), where multiple types may be specified in the list. +\fBGlob\fR will return all files which match at least one of the types given. +.RS +.PP +The second form specifies types where all the types given must match. +These are \fIr\fR, \fIw\fR, \fIx\fR as file permissions, and +\fIreadonly\fR, \fIhidden\fR as special permission cases. On the +Macintosh, MacOS types and creators are also supported, where any item +which is four characters long is assumed to be a MacOS type +(e.g. \fBTEXT\fR). Items which are of the form \fI{macintosh type XXXX}\fR +or \fI{macintosh creator XXXX}\fR will match types or creators +respectively. Unrecognised types, or specifications of multiple MacOS +types/creators will signal an error. +.PP +The two forms may be mixed, so \fB\-types {d f r w}\fR will find all +regular files OR directories that have both read AND write permissions. +The following are equivalent: +.RS +.CS +\fBglob \-type d *\fR +\fBglob */\fR +.CE +.RE +except that the first case doesn't return the trailing ``/'' and +is more platform independent. +.RE +.VE 8.3 +.TP \fB\-\|\-\fR Marks the end of switches. The argument following this one will be treated as a \fIpattern\fR even if it starts with a \fB\-\fR. @@ -71,14 +130,30 @@ Second, \fBglob\fR only returns the names of files that actually exist; in csh no check for existence is made unless a pattern contains a ?, *, or [] construct. -.SH PORTABILITY ISSUES +.SH "PORTABILITY ISSUES" .PP Unlike other Tcl commands that will accept both network and native style names (see the \fBfilename\fR manual entry for details on how native and network names are specified), the \fBglob\fR command only -accepts native names. Also, for Windows UNC names, the servername and -sharename components of the path may not contain ?, *, or [] -constructs. +accepts native names. +.TP +\fBWindows\fR +. +For Windows UNC names, the servername and sharename components of the path +may not contain ?, *, or [] constructs. On Windows NT, if \fIpattern\fR is +of the form ``\fB~\fIusername\fB@\fIdomain\fR'' it refers to the home +directory of the user whose account information resides on the specified NT +domain server. Otherwise, user account information is obtained from +the local computer. On Windows 95 and 98, \fBglob\fR accepts patterns +like ``.../'' and ``..../'' for successively higher up parent directories. +.TP +\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 KEYWORDS exist, file, glob, pattern diff --git a/tcl/doc/http.n b/tcl/doc/http.n index 18ffc89f88f..fb2de76392e 100644 --- a/tcl/doc/http.n +++ b/tcl/doc/http.n @@ -1,5 +1,6 @@ '\" '\" 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. @@ -7,13 +8,13 @@ '\" RCS: @(#) $Id$ '\" .so man.macros -.TH "Http" n 8.0 Tcl "Tcl Built-In Commands" +.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.0?\fP +\fBpackage require http ?2.3?\fP .sp \fB::http::config \fI?options?\fR .sp @@ -31,7 +32,17 @@ Http \- Client-side implementation of the HTTP/1.0 protocol. .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 .SH DESCRIPTION @@ -41,16 +52,17 @@ protocol. The package implements the GET, POST, and HEAD operations of HTTP/1.0. It allows configuration of a proxy host to get through firewalls. The package is compatible with the \fBSafesock\fR security policy, so it can be used by untrusted applets to do URL fetching from -a restricted set of hosts. +a restricted set of hosts. This package can be extened to support +additional HTTP transport protocols, such as HTTPS, by providing +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. +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. @@ -98,7 +110,7 @@ non-empty. .TP \fB\-useragent\fP \fIstring\fP The value of the User-Agent header in the HTTP request. The default -is \fB"Tcl http client package 2.0."\fR +is \fB"Tcl http client package 2.2."\fR .RE .TP \fB::http::geturl\fP \fIurl\fP ?\fIoptions\fP? @@ -107,7 +119,7 @@ The \fB\-query\fR option causes a POST operation and the \fB\-validate\fR option causes a HEAD operation; otherwise, a GET operation is performed. The \fB::http::geturl\fR command returns a \fItoken\fR value that can be used to get -information about the transaction. See the STATE ARRAY section for +information about the transaction. See the STATE ARRAY and ERRORS section for details. The \fB::http::geturl\fR command blocks until the operation completes, unless the \fB\-command\fR option specifies a callback that is invoked when the HTTP transaction completes. @@ -120,7 +132,7 @@ At most \fIsize\fR bytes are read at once. After each block, a call to the \fB\-progress\fR -callback is made. +callback is made (if that option is specified). .TP \fB\-channel\fP \fIname\fP Copy the URL contents to channel \fIname\fR instead of saving it in @@ -196,6 +208,28 @@ This flag causes \fB::http::geturl\fR to do a POST request that passes the formatted query. The \fB::http::formatQuery\fR procedure can be used to do the formatting. .TP +\fB\-queryblocksize\fP \fIsize\fP +The blocksize used when posting query data to the URL. +At most +\fIsize\fR +bytes are written at once. After each block, a call to the +\fB\-queryprogress\fR +callback is made (if that option is specified). +.TP +\fB\-querychannel\fP \fIchannelID\fP +This flag causes \fB::http::geturl\fR to do a POST request that passes the +data contained in \fIchannelID\fR to the server. The data contained in \fIchannelID\fR must be a x-url-encoding +formatted query unless the \fB\-type\fP option below is used. +If a Content-Length header is not specified via the \fB\-headers\fR options, +\fB::http::geturl\fR attempts to determine the size of the post data +in order to create that header. If it is +unable to determine the size, it returns an error. +.TP +\fB\-queryprogress\fP \fIcallback\fP +The \fIcallback\fR is made after each transfer of data to the URL +(i.e. POST) and acts exactly like the \fB\-progress\fR option (the +callback format is the same). +.TP \fB\-timeout\fP \fImilliseconds\fP If \fImilliseconds\fR is non-zero, then \fB::http::geturl\fR sets up a timeout to occur after the specified number of milliseconds. @@ -204,6 +238,11 @@ the \fB-command\fP callback, if specified. The return value of \fB::http::status\fP is \fBtimeout\fP after a timeout has occurred. .TP +\fB\-type\fP \fImime-type\fP +Use \fImime-type\fR as the \fBContent-Type\fR value, instead of the +default value (\fBapplication/x-www-form-urlencoded\fR) during a +POST operation. +.TP \fB\-validate\fP \fIboolean\fP If \fIboolean\fR is non-zero, then \fB::http::geturl\fR does an HTTP HEAD request. This request returns meta information about the URL, but the @@ -226,12 +265,20 @@ any. This sets the \fBstate(status)\fP value to \fIwhy\fP, which defaults to \f \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. +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. @@ -240,9 +287,108 @@ the state array. 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. +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 +package require http +package require tls + +http::register https 443 ::tls::socket + +set token [http::geturl https://my.secure.site/] +.CE +.RE +.TP +\fB::http::unregister\fP \fIproto\fP +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. +If it can read the server's response +it will end up with an \fBok\fP status, otherwise it will have +an \fBeof\fP status. + .SH "STATE ARRAY" The \fB::http::geturl\fR procedure returns a \fItoken\fR that can be used to get to the state of the HTTP transaction in the form of a Tcl array. @@ -250,7 +396,11 @@ Use this construct to create an easy-to-use array variable: .CS upvar #0 $token state .CE -The following elements of the array are supported: +Once the data associated with the url is no longer needed, the state +array should be unset to free up storage. +The \fBhttp::cleanup\fP procedure is provided for that purpose. +The following elements of +the array are supported: .RS .TP \fBbody\fR @@ -270,7 +420,7 @@ The HTTP status reply from the server. This value is returned by the \fB::http::code\fP command. The format of this value is: .RS .CS -\fIcode string\fP +\fIHTTP/1.0 code string\fP .CE The \fIcode\fR is a three-digit number defined in the HTTP standard. A code of 200 is OK. Codes beginning with 4 or 5 indicate errors. @@ -304,9 +454,14 @@ The advertised size of the contents. The actual size obtained by An alternate URL that contains the requested data. .RE .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, or \fBerror\fR for an error condition. During the +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 @@ -358,3 +513,4 @@ safe(n), socket(n), safesock(n) security policy, socket + diff --git a/tcl/doc/info.n b/tcl/doc/info.n index e538086f077..44df52f37bf 100644 --- a/tcl/doc/info.n +++ b/tcl/doc/info.n @@ -72,8 +72,8 @@ into variable \fIvarname\fR. .TP \fBinfo exists \fIvarName\fR Returns \fB1\fR if the variable named \fIvarName\fR exists in the -current context (either as a global or local variable), returns \fB0\fR -otherwise. +current context (either as a global or local variable) and has been +defined by being given a value, returns \fB0\fR otherwise. .TP \fBinfo globals \fR?\fIpattern\fR? If \fIpattern\fR isn't specified, returns a list of all the names diff --git a/tcl/doc/interp.n b/tcl/doc/interp.n index 1f603c26a8b..ee29c11e110 100644 --- a/tcl/doc/interp.n +++ b/tcl/doc/interp.n @@ -375,21 +375,23 @@ A safe interpreter is created with exactly the following set of built-in commands: .DS .ta 1.2i 2.4i 3.6i -\fBafter append array break -case catch clock close -concat continue eof error -eval expr fblocked fileevent -flush for foreach format -gets global history if -incr info interp join -lappend lindex linsert list -llength lower lrange lreplace -lsearch lsort package pid -proc puts read rename +\fBafter append array binary +break case catch clock +close concat continue eof +error eval expr fblocked +fcopy fileevent flush for +foreach format gets global +history if incr info +interp join lappend lindex +linsert list llength lrange +lreplace lsearch lsort namespace +package pid proc puts +read regexp regsub rename return scan seek set split string subst switch tell trace unset update -uplevel upvar vwait while\fR +uplevel upvar variable vwait +while\fR .DE .VS "" BR The following commands are hidden by \fBinterp create\fR when it diff --git a/tcl/doc/library.n b/tcl/doc/library.n index 5b9c59d7ef5..54ef6ad50da 100644 --- a/tcl/doc/library.n +++ b/tcl/doc/library.n @@ -10,13 +10,15 @@ .TH library n "8.0" Tcl "Tcl Built-In Commands" .BS .SH NAME -library \- standard library of Tcl procedures +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 \fBauto_execok \fIcmd\fR +\fBauto_import \fIpattern\fR \fBauto_load \fIcmd\fR \fBauto_mkindex \fIdir pattern pattern ...\fR \fBauto_mkindex_old \fIdir pattern pattern ...\fR +\fBauto_qualify \fIcommand namespace\fR \fBauto_reset\fR \fBtcl_findLibrary \fIbasename version patch initScript enVarName varName\fR \fBparray \fIarrayName\fR @@ -60,76 +62,74 @@ the auto-load mechanism defined below. The following procedures are provided in the Tcl library: .TP \fBauto_execok \fIcmd\fR -Determines whether there is an executable file by the name \fIcmd\fR. -This command examines the directories in the current search path -(given by the PATH environment variable) to see if there is an -executable file named \fIcmd\fR in any of those directories. -If so, it returns 1; if not it returns 0. \fBAuto_exec\fR -remembers information about previous searches in an array -named \fBauto_execs\fR; this avoids the path search in -future calls for the same \fIcmd\fR. The command \fBauto_reset\fR -may be used to force \fBauto_execok\fR to forget its cached -information. +Determines whether there is an executable file or shell builtin +by the name \fIcmd\fR. If so, it returns a list of arguments to be +passed to \fBexec\fR to execute the executable file or shell builtin +named by \fIcmd\fR. If not, it returns an empty string. This command +examines the directories in the current search path (given by the PATH +environment variable) in its search for an executable file named +\fIcmd\fR. On Windows platforms, the search is expanded with the same +directories and file extensions as used by \fBexec\fR. \fBAuto_exec\fR +remembers information about previous searches in an array named +\fBauto_execs\fR; this avoids the path search in future calls for the +same \fIcmd\fR. The command \fBauto_reset\fR may be used to force +\fBauto_execok\fR to forget its cached information. +.TP +\fBauto_import \fIpattern\fR +\fBAuto_import\fR is invoked during \fBnamespace import\fR to see if +the imported commands specified by \fIpattern\fR reside in an +autoloaded library. If so, the commands are loaded so that they will +be available to the interpreter for creating the import links. If the +commands do not reside in an autoloaded library, \fBauto_import\fR +does nothing. .TP \fBauto_load \fIcmd\fR This command attempts to load the definition for a Tcl command named -\fIcmd\fR. -To do this, it searches an \fIauto-load path\fR, which is a list of -one or more directories. -The auto-load path is given by the global variable \fB$auto_path\fR -if it exists. -If there is no \fB$auto_path\fR variable, then the TCLLIBPATH environment -variable is used, if it exists. -Otherwise the auto-load path consists of just the Tcl library directory. -Within each directory in the auto-load path there must be a file -\fBtclIndex\fR that describes one -or more commands defined in that directory -and a script to evaluate to load each of the commands. -The \fBtclIndex\fR file should be generated with the -\fBauto_mkindex\fR command. -If \fIcmd\fR is found in an index file, then the appropriate -script is evaluated to create the command. -The \fBauto_load\fR command returns 1 if \fIcmd\fR was successfully -created. -The command returns 0 if there was no index entry for \fIcmd\fR -or if the script didn't actually define \fIcmd\fR (e.g. because -index information is out of date). -If an error occurs while processing the script, then that error -is returned. -\fBAuto_load\fR only reads the index information once and saves it -in the array \fBauto_index\fR; future calls to \fBauto_load\fR -check for \fIcmd\fR in the array rather than re-reading the index -files. -The cached index information may be deleted with the command -\fBauto_reset\fR. -This will force the next \fBauto_load\fR command to reload the -index database from disk. +\fIcmd\fR. To do this, it searches an \fIauto-load path\fR, which is +a list of one or more directories. The auto-load path is given by the +global variable \fB$auto_path\fR if it exists. If there is no +\fB$auto_path\fR variable, then the TCLLIBPATH environment variable is +used, if it exists. Otherwise the auto-load path consists of just the +Tcl library directory. Within each directory in the auto-load path +there must be a file \fBtclIndex\fR that describes one or more +commands defined in that directory and a script to evaluate to load +each of the commands. The \fBtclIndex\fR file should be generated +with the \fBauto_mkindex\fR command. If \fIcmd\fR is found in an +index file, then the appropriate script is evaluated to create the +command. The \fBauto_load\fR command returns 1 if \fIcmd\fR was +successfully created. The command returns 0 if there was no index +entry for \fIcmd\fR or if the script didn't actually define \fIcmd\fR +(e.g. because index information is out of date). If an error occurs +while processing the script, then that error is returned. +\fBAuto_load\fR only reads the index information once and saves it in +the array \fBauto_index\fR; future calls to \fBauto_load\fR check for +\fIcmd\fR in the array rather than re-reading the index files. The +cached index information may be deleted with the command +\fBauto_reset\fR. This will force the next \fBauto_load\fR command to +reload the index database from disk. .TP \fBauto_mkindex \fIdir pattern pattern ...\fR -Generates an index suitable for use by \fBauto_load\fR. -The command searches \fIdir\fR for all files whose names match -any of the \fIpattern\fR arguments -(matching is done with the \fBglob\fR command), -generates an index of all the Tcl command -procedures defined in all the matching files, and stores the -index information in a file named \fBtclIndex\fR in \fIdir\fR. -If no pattern is given a pattern of \fB*.tcl\fR will be assumed. -For example, the command +Generates an index suitable for use by \fBauto_load\fR. The command +searches \fIdir\fR for all files whose names match any of the +\fIpattern\fR arguments (matching is done with the \fBglob\fR +command), generates an index of all the Tcl command procedures defined +in all the matching files, and stores the index information in a file +named \fBtclIndex\fR in \fIdir\fR. If no pattern is given a pattern of +\fB*.tcl\fR will be assumed. For example, the command .RS .CS \fBauto_mkindex foo *.tcl\fR .CE .LP -will read all the \fB.tcl\fR files in subdirectory \fBfoo\fR -and generate a new index file \fBfoo/tclIndex\fR. +will read all the \fB.tcl\fR files in subdirectory \fBfoo\fR and +generate a new index file \fBfoo/tclIndex\fR. .PP -\fBAuto_mkindex\fR parses the Tcl scripts by sourcing them -into a slave interpreter and monitoring the proc and -namespace commands that are executed. -Extensions can use the (undocumented) -auto_mkindex_parser package to register other commands that -can contribute to the auto_load index. -You will have to read through init.tcl to see how this works. +\fBAuto_mkindex\fR parses the Tcl scripts by sourcing them into a +slave interpreter and monitoring the proc and namespace commands that +are executed. Extensions can use the (undocumented) +auto_mkindex_parser package to register other commands that can +contribute to the auto_load index. You will have to read through +auto.tcl to see how this works. .PP \fBAuto_mkindex_old\fR parses the Tcl scripts in a relatively unsophisticated way: if any line contains the word \fBproc\fR @@ -137,17 +137,37 @@ as its first characters then it is assumed to be a procedure definition and the next word of the line is taken as the procedure's name. Procedure definitions that don't appear in this way (e.g. they -have spaces before the \fBproc\fR) will not be indexed. +have spaces before the \fBproc\fR) will not be indexed. If your +script contains "dangerous" code, such as global initialization +code or procedure names with special characters like \fB$\fR, +\fB*\fR, \fB[\fR or \fB]\fR, you are safer using auto_mkindex_old. .RE .TP \fBauto_reset\fR Destroys all the information cached by \fBauto_execok\fR and -\fBauto_load\fR. -This information will be re-read from disk the next time it is -needed. -\fBAuto_reset\fR also deletes any procedures listed in the auto-load -index, so that fresh copies of them will be loaded the next time -that they're used. +\fBauto_load\fR. This information will be re-read from disk the next +time it is needed. \fBAuto_reset\fR also deletes any procedures +listed in the auto-load index, so that fresh copies of them will be +loaded the next time that they're used. +.TP +\fBauto_qualify \fIcommand namespace\fR +Computes a list of fully qualified names for \fIcommand\fR. This list +mirrors the path a standard Tcl interpreter follows for command +lookups: first it looks for the command in the current namespace, and +then in the global namespace. Accordingly, if \fIcommand\fR is +relative and \fInamespace\fR is not \fB::\fR, the list returned has +two elements: \fIcommand\fR scoped by \fInamespace\fR, as if it were +a command in the \fInamespace\fR namespace; and \fIcommand\fR as if it +were a command in the global namespace. Otherwise, if either +\fIcommand\fR is absolute (it begins with \fB::\fR), or +\fInamespace\fR is \fB::\fR, the list contains only \fIcommand\fR as +if it were a command in the global namespace. +.RS +.PP +\fBAuto_qualify\fR is used by the auto-loading facilities in Tcl, both +for producing auto-loading indexes such as \fIpkgIndex.tcl\fR, and for +performing the actual auto-loading of functions at runtime. +.RE .TP \fBtcl_findLibrary \fIbasename version patch initScript enVarName varName\fR This is a standard search procedure for use by extensions during @@ -253,9 +273,9 @@ a default value is used. .TP \fBenv(TCLLIBPATH)\fR If set, then it must contain a valid Tcl list giving directories to -search during auto-load operations. -This variable is only used when -initializing the \fBauto_path\fR variable. +search during auto-load operations. Directories must be specified in +Tcl format, using "/" as the path separator, regardless of platform. +This variable is only used when initializing the \fBauto_path\fR variable. .TP \fBtcl_nonwordchars\fR .VS @@ -276,11 +296,16 @@ comprised of any character that is not a space, tab, or newline. Under Unix, words are comprised of numbers, letters or underscores. .VE .TP -\fBunknown_active\fR -This variable is set by \fBunknown\fR to indicate that it is active. +\fBunknown_pending\fR +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" +re_syntax(n) + .SH KEYWORDS auto-exec, auto-load, library, unknown, word, whitespace + diff --git a/tcl/doc/lindex.n b/tcl/doc/lindex.n index 0771b53dfad..ec18d168a58 100644 --- a/tcl/doc/lindex.n +++ b/tcl/doc/lindex.n @@ -8,7 +8,7 @@ '\" RCS: @(#) $Id$ '\" .so man.macros -.TH lindex n 7.4 Tcl "Tcl Built-In Commands" +.TH lindex n 8.2 Tcl "Tcl Built-In Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -29,7 +29,9 @@ 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. +in the list, and \fBend\-\fIinteger\fR refers to the last element in +the list minus the specified integer offset. + .SH KEYWORDS element, index, list diff --git a/tcl/doc/linsert.n b/tcl/doc/linsert.n index a325e4e3f2f..a44bfbcd3b8 100644 --- a/tcl/doc/linsert.n +++ b/tcl/doc/linsert.n @@ -8,7 +8,7 @@ '\" RCS: @(#) $Id$ '\" .so man.macros -.TH linsert n 7.4 Tcl "Tcl Built-In Commands" +.TH linsert n 8.2 Tcl "Tcl Built-In Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -19,15 +19,15 @@ linsert \- Insert elements into a list .SH DESCRIPTION .PP -This command produces a new list from \fIlist\fR by inserting all -of the \fIelement\fR arguments just before the \fIindex\fRth -element of \fIlist\fR. Each \fIelement\fR argument will become -a separate element of 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. +This command produces a new list from \fIlist\fR by inserting all of the +\fIelement\fR arguments just before the \fIindex\fRth element of +\fIlist\fR. Each \fIelement\fR argument will become a separate element of +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 KEYWORDS element, insert, list diff --git a/tcl/doc/load.n b/tcl/doc/load.n index 52538c9b06b..e57e54c3aa1 100644 --- a/tcl/doc/load.n +++ b/tcl/doc/load.n @@ -64,7 +64,7 @@ typedef int Tcl_PackageInitProc(Tcl_Interp *\fIinterp\fR); The \fIinterp\fR argument identifies the interpreter in which the package is to be loaded. The initialization procedure must return \fBTCL_OK\fR or \fBTCL_ERROR\fR to indicate whether or not it completed -successfully; in the event of an error it should set \fIinterp->result\fR +successfully; in the event of an error it should set the interpreter's result to point to an error message. The result of the \fBload\fR command will be the result returned by the initialization procedure. .PP @@ -106,6 +106,21 @@ different files have been \fBload\fRed with different versions of the package, Tcl picks the file that was loaded first. .VE +.SH "PORTABILITY ISSUES" +.TP +\fBWindows\fR\0\0\0\0\0 +. +When a load fails with "library not found" error, it is also possible +that a dependent library was not found. To see the dependent libraries, +type ``dumpbin -imports '' in a DOS console to see what the +library must import. +When loading a DLL in the current directory, Windows will ignore ``./'' as +a path specifier and use a search heuristic to find the DLL instead. +To avoid this, load the DLL with +.CS + load [file join [pwd] mylib.DLL] +.CE + .SH BUGS .PP If the same file is \fBload\fRed by different \fIfileName\fRs, it will @@ -118,3 +133,4 @@ detect the redundant loads, others may not). .SH KEYWORDS binary code, loading, safe interpreter, shared library + diff --git a/tcl/doc/lreplace.n b/tcl/doc/lreplace.n index c34ff74d5c0..3f357e92d7c 100644 --- a/tcl/doc/lreplace.n +++ b/tcl/doc/lreplace.n @@ -19,25 +19,29 @@ lreplace \- Replace elements in a list with new elements .SH DESCRIPTION .PP -\fBLreplace\fR returns a new list formed by replacing one or more elements of +\fBlreplace\fR returns a new list formed by replacing one or more elements of \fIlist\fR with the \fIelement\fR arguments. -\fIFirst\fR gives the index in \fIlist\fR of the first element -to be replaced (0 refers to the first element). -If \fIfirst\fR is less than zero then it refers to the first -element of \fIlist\fR; the element indicated by \fIfirst\fR -must exist in the list. -\fILast\fR gives the index in \fIlist\fR of the last element -to be replaced. -If \fIlast\fR is less than \fIfirst\fR then no elements are deleted; -the new elements are simply inserted before \fIfirst\fR. -\fIFirst\fR or \fIlast\fR may be \fBend\fR -(or any abbreviation of it) to refer to the last element of the list. +\fIfirst\fR and \fIlast\fR specify the first and last index of the +range of elements to replace. 0 refers to the first element of the +list, and \fBend\fR (or any abbreviation of it) may be used to refer +to the last element of the list. If \fIlist\fR is empty, then +\fIfirst\fR and \fIlast\fR are ignored. + +If \fIfirst\fR is less than zero, it is considered to refer to the +first element of the list. For non-empty lists, the element indicated +by \fIfirst\fR must exist. + +If \fIlast\fR is less than zero but greater than \fIfirst\fR, then any +specified elements will be prepended to the list. If \fIlast\fR is +less than \fIfirst\fR then no elements are deleted; the new elements +are simply inserted before \fIfirst\fR. + 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. +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 KEYWORDS element, list, replace diff --git a/tcl/doc/lsearch.n b/tcl/doc/lsearch.n index c0646dde878..b44cc142877 100644 --- a/tcl/doc/lsearch.n +++ b/tcl/doc/lsearch.n @@ -37,7 +37,8 @@ element using the same rules as the \fBstring match\fR command. .TP \fB\-regexp\fR \fIPattern\fR is treated as a regular expression and matched against -each list element using the same rules as the \fBregexp\fR command. +each list element using the rules described in the \fBre_syntax\fR +reference page. .PP If \fImode\fR is omitted then it defaults to \fB\-glob\fR. diff --git a/tcl/doc/lsort.n b/tcl/doc/lsort.n index bd3ed1e1a46..6f609384db5 100644 --- a/tcl/doc/lsort.n +++ b/tcl/doc/lsort.n @@ -1,6 +1,7 @@ '\" '\" 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. @@ -8,7 +9,7 @@ '\" RCS: @(#) $Id$ '\" .so man.macros -.TH lsort n 8.0 Tcl "Tcl Built-In Commands" +.TH lsort n 8.3 Tcl "Tcl Built-In Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -20,16 +21,17 @@ lsort \- Sort the elements of a list .SH DESCRIPTION .PP This command sorts the elements of \fIlist\fR, returning a new -list in sorted order. By default ASCII sorting is used with -the result returned in increasing order. -However, any of the -following options may be specified before \fIlist\fR to -control the sorting process (unique abbreviations are accepted): +list in sorted order. The implementation of the \fBlsort\fR command +uses the merge\-sort algorithm which is a stable sort that has O(n log +n) performance characteristics. +.PP +By default ASCII sorting is used with the result returned in +increasing order. However, any of the following options may be +specified before \fIlist\fR to control the sorting process (unique +abbreviations are accepted): .TP 20 \fB\-ascii\fR -Use string comparison with ASCII collation order. This is -the default. -.VS 8.0 br +Use string comparison with ASCII collation order. This is the default. .TP 20 \fB\-dictionary\fR Use dictionary-style comparison. This is the same as \fB\-ascii\fR @@ -38,14 +40,12 @@ strings contain embedded numbers, the numbers compare as integers, not characters. For example, in \fB\-dictionary\fR mode, \fBbigBoy\fR sorts between \fBbigbang\fR and \fBbigboy\fR, and \fBx10y\fR sorts between \fBx9y\fR and \fBx11y\fR. -.VE .TP 20 \fB\-integer\fR Convert list elements to integers and use integer comparison. .TP 20 \fB\-real\fR -Convert list elements to floating-point values and use floating -comparison. +Convert list elements to floating-point values and use floating comparison. .TP 20 \fB\-command\0\fIcommand\fR Use \fIcommand\fR as a comparison command. @@ -62,7 +62,6 @@ This is the default. .TP 20 \fB\-decreasing\fR Sort the list in decreasing order (``largest'' items first). -.VS 8.0 br .TP 20 \fB\-index\0\fIindex\fR If this option is specified, each of the elements of \fIlist\fR must @@ -78,8 +77,16 @@ 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 +.VS 8.3 +.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. .VE - .SH KEYWORDS element, list, order, sort diff --git a/tcl/doc/man.macros b/tcl/doc/man.macros index 6f3016f492f..ae66ef928af 100644 --- a/tcl/doc/man.macros +++ b/tcl/doc/man.macros @@ -72,8 +72,8 @@ . ie !"\\$2"" .TP \\n()Cu . el .TP 15 .\} -.ie !"\\$3"" \{\ .ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ \&\\$1 \\fI\\$2\\fP (\\$3) .\".b .\} diff --git a/tcl/doc/memory.n b/tcl/doc/memory.n new file mode 100644 index 00000000000..df412f34287 --- /dev/null +++ b/tcl/doc/memory.n @@ -0,0 +1,82 @@ +'\" +'\" Copyright (c) 1992-1999 by Karl Lehenbauer and Mark Diekhans +'\" Copyright (c) 2000 by Scriptics Corporation. +'\" All rights reserved. +'\" +'\" RCS: @(#) $Id$ +'\" +.so man.macros +.TH memory n 8.1 Tcl "Tcl Built-In Commands" +.BS +.SH NAME +memory \- Control Tcl memory debugging capabilities. +.SH SYNOPSIS +\fBmemory \fIoption \fR?\fIarg arg ...\fR? + +.SH DESCRIPTION +.PP +The \fBmemory\fR command gives the Tcl developer control of Tcl's memory +debugging capabilities. The memory command has several suboptions, which are +described below. It is only available when Tcl has been compiled with +memory debugging enabled (when \fBTCL_MEM_DEBUG\fR is defined at +compile time). +.TP +\fBmemory info\fR +Produces a report containing the total allocations and frees since +Tcl began, the current packets allocated (the current +number of calls to \fBckalloc\fR not met by a corresponding call +to \fBckfree\fR), the current bytes allocated, and the maximum number +of packets and bytes allocated. +.TP +\fBmemory trace [on|off]\fR +.br +Turns memory tracing on or off. When memory tracing is on, every call +to \fBckalloc\fR causes a line of trace information to be written to +\fIstderr\fR, consisting of the word \fIckalloc\fR, followed by the +address returned, the amount of memory allocated, and the C filename +and line number of the code performing the allocation. For example: +.CS +ckalloc 40e478 98 tclProc.c 1406 +.CE +Calls to \fBckfree\fR are traced in the same manner. +.TP +\fBmemory validate [on|off]\fR +Turns memory validation on or off. When memory validation is enabled, +on every call to \fBckalloc\fR or \fBckfree\fR, the guard zones are +checked for every piece of memory currently in existence that was +allocated by \fBckalloc\fR. This has a large performance impact and +should only be used when overwrite problems are strongly suspected. +The advantage of enabling memory validation is that a guard zone +overwrite can be detected on the first call to \fBckalloc\fR or +\fBckfree\fR after the overwrite occurred, rather than when the +specific memory with the overwritten guard zone(s) is freed, which may +occur long after the overwrite occurred. +.TP +\fBmemory trace_on_at_malloc\fR \fIcount\fR +Enable memory tracing after \fIcount\fR \fBckalloc\fR's have been performed. +For example, if you enter \fBmemory trace_on_at_malloc 100\fR, +after the 100th call to \fBckalloc\fR, memory trace information will begin +being displayed for all allocations and frees. Since there can be a lot +of memory activity before a problem occurs, judicious use of this option +can reduce the slowdown caused by tracing (and the amount of trace information +produced), if you can identify a number of allocations that occur before +the problem sets in. The current number of memory allocations that have +occurred since Tcl started is printed on a guard zone failure. +.TP +\fBmemory break_on_malloc\fR \fIcount\fR +After the \fBcount\fR allocations have been performed, \fBckalloc\fR's +output a message to this effect and that it is now attempting to enter +the C debugger. Tcl will then issue a \fISIGINT\fR signal against itself. +If you are running Tcl under a C debugger, it should then enter the debugger +command mode. +.TP +\fB memory display\fR \fIfile\fR +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 + + diff --git a/tcl/doc/msgcat.n b/tcl/doc/msgcat.n new file mode 100644 index 00000000000..37c2a76fcd5 --- /dev/null +++ b/tcl/doc/msgcat.n @@ -0,0 +1,244 @@ +'\" +'\" Copyright (c) 1998 Mark Harrison. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) msgcat.n +'\" +.so man.macros +.TH "msgcat" n 8.1 Tcl "Tcl Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +msgcat \- Tcl message catalog +.SH SYNOPSIS +\fB::msgcat::mc \fIsrc-string\fR +.sp +\fB::msgcat::mclocale \fR?\fInewLocale\fR? +.sp +\fB::msgcat::mcpreferences\fR +.sp +\fB::msgcat::mcload \fIdirname\fR +.sp +\fB::msgcat::mcset \fIlocale src-string \fR?\fItranslate-string\fR? +.sp +\fB::msgcat::mcunknown \fIlocale src-string\fR +.BE + +.SH DESCRIPTION +.PP +The \fBmsgcat\fR package provides a set of functions +that can be used to manage multi-lingual user interfaces. +Text strings are defined in a ``message catalog'' which +is independent from the application, and +which can be edited or localized without modifying +the application source code. New languages +or locales are provided by adding a new file to +the message catalog. +.PP +Use of the message catalog is optional by any application +or package, but is encouraged if the application or package +wishes to be enabled for multi-lingual applications. + +.SH COMMANDS +.TP +\fB::msgcat::mc \fIsrc-string\fR ?\fIarg arg ...\fR? +Returns a translation of \fIsrc-string\fR according to the +user's current locale. If additional arguments past \fIsrc-string\fR +are given, the \fBformat\fR command is used to substitute the +additional arguments in the translation of \fIsrc-string\fR. + +\fB::msgcat::mc\fR will search the messages defined +in the current namespace for a translation of \fIsrc-string\fR; if +none is found, it will search in the parent of the current namespace, +and so on until it reaches the global namespace. If no translation +string exists, \fB::msgcat::mcunknown\fR is called and the string +returned from \fB::msgcat::mcunknown\fR is returned. +.PP +\fB::msgcat::mc\fR is the main function used to localize an +application. Instead of using an English string directly, an +applicaton can pass the English string through \fB::msgcat::mc\fR and +use the result. If an application is written for a single language in +this fashion, then it is easy to add support for additional languages +later simply by defining new message catalog entries. +.TP +\fB::msgcat::mclocale \fR?\fInewLocale\fR? +This function sets the locale to \fInewLocale\fR. If \fInewLocale\fR +is omitted, the current locale is returned, otherwise the current locale +is set to \fInewLocale\fR. +The initial locale defaults to the locale specified in +the user's environment. See \fBLOCALE AND SUBLOCALE SPECIFICATION\fR +below for a description of the locale string format. +.TP +\fB::msgcat::mcpreferences\fR +Returns an ordered list of the locales preferred by +the user, based on the user's language specification. +The list is ordered from most specific to least +preference. If the user has specified LANG=en_US_funky, +this procedure would return {en_US_funky en_US en}. +.TP +\fB::msgcat::mcload \fIdirname\fR +Searches the specified directory for files that match +the language specifications returned by \fB::msgcat::mcpreferences\fR. +Each file located is sourced. The file extension is ``.msg''. +The number of message files which matched the specification +and were loaded is returned. +.TP +\fB::msgcat::mcset \fIlocale src-string \fR?\fItranslate-string\fR? +Sets the translation for \fIsrc-string\fR to \fItranslate-string\fR +in the specified \fIlocale\fR. If \fItranslate-string\fR is not +specified, \fIsrc-string\fR is used for both. The function +returns \fItranslate-string\fR. +.TP +\fB::msgcat::mcunknown \fIlocale src-string\fR +This routine is called by \fB::msgcat::mc\fR in the case when +a translation for \fIsrc-string\fR is not defined in the +current locale. The default action is to return +\fIsrc-string\fR. This procedure can be redefined by the +application, for example to log error messages for each unknown +string. The \fB::msgcat::mcunknown\fR procedure is invoked at the +same stack context as the call to \fB::msgcat::mc\fR. The return vaue +of \fB::msgcat::mcunknown\fR is used as the return vaue for the call +to \fB::msgcat::mc\fR. + +.SH "LOCALE AND SUBLOCALE SPECIFICATION" +.PP +The locale is specified by a locale string. +The locale string consists of +a language code, an optional country code, and an optional +system-specific code, each separated by ``_''. The country and language +codes are specified in standards ISO-639 and ISO-3166. +For example, the locale ``en'' specifies English and + ``en_US'' specifes U.S. English. +.PP +The locale defaults to the value in \fBenv(LANG)\fR at the time the +\fBmsgcat\fR package is loaded. If \fBenv(LANG)\fR is not defined, then the +locale defaults to ``C''. +.PP +When a locale is specified by the user, a ``best match'' search is +performed during string translation. For example, if a user specifies +en_UK_Funky, the locales ``en_UK_Funky'', ``en_UK'', and ``en'' are +searched in order until a matching translation string is found. If no +translation string is available, then \fB::msgcat::unknown\fR is +called. + +.SH "NAMESPACES AND MESSAGE CATALOGS" +.PP +Strings stored in the message catalog are stored relative +to the namespace from which they were added. This allows +multiple packages to use the same strings without fear +of collisions with other packages. It also allows the +source string to be shorter and less prone to typographical +error. +.PP +For example, executing the code +.CS +mcset en hello "hello from ::" +namespace eval foo {mcset en hello "hello from ::foo"} +puts [mc hello] +namespace eval foo {puts [mc hello]} +.CE +will print +.CS +hello from :: +hello from ::foo +.CE +.PP +When searching for a translation of a message, the +message catalog will search first the current namespace, +then the parent of the current namespace, and so on until +the global namespace is reached. This allows child namespaces +to "inherit" messages from their parent namespace. +.PP +For example, executing the code +.CS +mcset en m1 ":: message1" +mcset en m2 ":: message2" +mcset en m3 ":: message3" +namespace eval ::foo { + mcset en m2 "::foo message2" + mcset en m3 "::foo message3" +} +namespace eval ::foo::bar { + mcset en m3 "::foo::bar message3" +} +puts "[mc m1]; [mc m2]; [mc m3]" +namespace eval ::foo {puts "[mc m1]; [mc m2]; [mc m3]"} +namespace eval ::foo::bar {puts "[mc m1]; [mc m2]; [mc m3]"} +.CE +will print +.CS +:: message1; :: message2; :: message3 +:: message1; ::foo message2; ::foo message3 +:: message1; ::foo message2; ::foo::bar message3 +.CE + +.SH "LOCATION AND FORMAT OF MESSAGE FILES" +.PP +Message files can be located in any directory, subject +to the following conditions: +.IP [1] +All message files for a package are in the same directory. +.IP [2] +The message file name is a locale specifier followed +by ``.msg''. For example: +.CS +es.msg -- spanish +en_UK.msg -- UK English +.CE +.IP [3] +The file contains a series of calls to mcset, setting the +necessary translation strings for the language. For example: +.CS +::msgcat::mcset es "Free Beer!" "Cerveza Gracias!" +.CE + +.SH "RECOMMENDED MESSAGE SETUP FOR PACKAGES" +.PP +If a package is installed into a subdirectory of the +\fBtcl_pkgPath\fR and loaded via \fBpackage require\fR, the +following procedure is recommended. +.IP [1] +During package installation, create a subdirectory +\fBmsgs\fR under your package directory. +.IP [2] +Copy your *.msg files into that directory. +.IP [3] + Add the following command to your package +initialization script: +.CS +# load language files, stored in msgs subdirectory +::msgcat::mcload [file join [file dirname [info script]] msgs] +.CE + +.SH "POSTITIONAL CODES FOR FORMAT AND SCAN COMMANDS" +.PP +It is possible that a message string used as an argument +to \fBformat\fR might have positionally dependent parameters that +might need to be repositioned. For example, it might be +syntactically desirable to rearrange the sentence structure +while translating. +.CS +format "We produced %d units in location %s" $num $city +format "In location %s we produced %d units" $city $num +.CE +.PP +This can be handled by using the positional +parameters: +.CS +format "We produced %1\\$d units in location %2\\$s" $num $city +format "In location %2\\$s we produced %1\\$d units" $num $city +.CE +.PP +Similarly, positional parameters can be used with \fBscan\fR to +extract values from internationalized strings. + +.SH CREDITS +.PP +The message catalog code was developed by Mark Harrison. + +.SH "SEE ALSO" +format(n), scan(n), namespace(n), package(n) +.SH KEYWORDS +internationalization, i18n, localization, l10n, message, text, translation diff --git a/tcl/doc/namespace.n b/tcl/doc/namespace.n index 6451a3b50df..85adcdadd76 100644 --- a/tcl/doc/namespace.n +++ b/tcl/doc/namespace.n @@ -205,7 +205,7 @@ Returns any leading namespace qualifiers for \fIstring\fR. Qualifiers are namespace names separated by \fB::\fRs. For the \fIstring\fR \fB::foo::bar::x\fR, this command returns \fB::foo::bar\fR, -and for \fB::\fR it returns \fB``''\fR (an empty string). +and for \fB::\fR it returns an empty string. This command is the complement of the \fBnamespace tail\fR command. Note that it does not check whether the namespace names are, in fact, @@ -216,7 +216,7 @@ Returns the simple name at the end of a qualified string. Qualifiers are namespace names separated by \fB::\fRs. For the \fIstring\fR \fB::foo::bar::x\fR, this command returns \fBx\fR, -and for \fB::\fR it returns \fB``''\fR (an empty string). +and for \fB::\fR it returns an empty string. This command is the complement of the \fBnamespace qualifiers\fR command. It does not check whether the namespace names are, in fact, the names of currently defined namespaces. @@ -228,7 +228,10 @@ For example, if \fIname\fR does not exist in the current namespace but does exist in the global namespace, this command returns a fully-qualified name in the global namespace. If the command or variable does not exist, -this command returns an empty string. +this command returns an empty string. If the variable has been +created but not defined, such as with the \fBvariable\fR command +or through a \fBtrace\fR on the variable, this command will return the +fully-qualified name of the variable. If no flag is given, \fIname\fR is treated as a command name. See the section \fBNAME RESOLUTION\fR below for an explanation of the rules regarding name resolution. @@ -245,21 +248,21 @@ The \fBnamespace eval\fR command lets you create new namespaces. For example, .CS \fBnamespace eval Counter { - namespace export Bump + namespace export bump variable num 0 - proc Bump {} { + proc bump {} { variable num incr num } }\fR .CE creates a new namespace containing the variable \fBnum\fR and -the procedure \fBBump\fR. +the procedure \fBbump\fR. The commands and variables in this namespace are separate from other commands and variables in the same program. -If there is a command named \fBBump\fR in the global namespace, -for example, it will be different from the command \fBBump\fR +If there is a command named \fBbump\fR in the global namespace, +for example, it will be different from the command \fBbump\fR in the \fBCounter\fR namespace. .PP Namespace variables resemble global variables in Tcl. @@ -276,7 +279,7 @@ as the namespace definition shown above: .CS \fBnamespace eval Counter { variable num 0 - proc Bump {} { + proc bump {} { variable num return [incr num] } @@ -322,7 +325,7 @@ Names must be qualified by the namespace that contains them. From the global namespace, we might access the \fBCounter\fR procedures like this: .CS -\fBCounter::Bump 5 +\fBCounter::bump 5 Counter::Reset\fR .CE We could access the current count like this: @@ -332,10 +335,10 @@ We could access the current count like this: When one namespace contains another, you may need more than one qualifier to reach its elements. If we had a namespace \fBFoo\fR that contained the namespace \fBCounter\fR, -you could invoke its \fBBump\fR procedure +you could invoke its \fBbump\fR procedure from the global namespace like this: .CS -\fBFoo::Counter::Bump 3\fR +\fBFoo::Counter::bump 3\fR .CE .PP You can also use qualified names when you create and rename commands. @@ -517,36 +520,36 @@ the command is automatically removed from all namespaces that import it. You can export commands from a namespace like this: .CS \fBnamespace eval Counter { - namespace export Bump Reset - variable num 0 - variable max 100 + namespace export bump reset + variable Num 0 + variable Max 100 - proc Bump {{by 1}} { - variable num - incr num $by - check - return $num + proc bump {{by 1}} { + variable Num + incr Num $by + Check + return $Num } - proc Reset {} { - variable num - set num 0 + proc reset {} { + variable Num + set Num 0 } - proc check {} { - variable num - variable max - if {$num > $max} { + proc Check {} { + variable Num + variable Max + if {$Num > $Max} { error "too high!" } } }\fR .CE -The procedures \fBBump\fR and \fBReset\fR are exported, +The procedures \fBbump\fR and \fBreset\fR are exported, so they are included when you import from the \fBCounter\fR namespace, like this: .CS \fBnamespace import Counter::*\fR .CE -However, the \fBcheck\fR procedure is not exported, +However, the \fBCheck\fR procedure is not exported, so it is ignored by the import operation. .PP The \fBnamespace import\fR command only imports commands diff --git a/tcl/doc/open.n b/tcl/doc/open.n index 39121b6c3e1..833ae11ef30 100644 --- a/tcl/doc/open.n +++ b/tcl/doc/open.n @@ -55,8 +55,9 @@ Open the file for reading and writing. Truncate it if it exists. If it doesn't exist, create a new file. .TP 15 \fBa\fR -Open the file for writing only. The file must already exist, and the file -is positioned so that new data is appended to the file. +Open the file for writing only. If the file doesn't exist, +create a new empty file. +Set the initial access position to the end of the file. .TP 15 \fBa+\fR Open the file for reading and writing. If the file doesn't exist, @@ -144,6 +145,23 @@ number of data bits, and number of stop bits for this serial port. The ``odd'', ``even'', ``mark'', or ``space''. \fIData\fR is the number of data bits and should be an integer from 5 to 8, while \fIstop\fR is the number of stop bits and should be the integer 1 or 2. +.TP +\fB\-pollinterval \fImsec\fR +. +This option, available only on Windows for serial ports, is used to +set the maximum time between polling for fileevents. This affects the +time interval between checking for events throughout the Tcl +interpreter (the smallest value always wins). Use this option only if +you want to poll the serial port more often than 10 msec (the default). +.TP +\fB\-lasterror\fR +. +This option is available only on Windows for serial ports, and is +query only (will only be reported when directly requested). +In case of a serial communication error, \fBread\fR or \fBputs\fR +returns a general Tcl file I/O error. +\fBfconfigure -lasterror\fR can be called to get a list +of error details (e.g. FRAME RXOVER). .VE .VS @@ -153,8 +171,13 @@ number of stop bits and should be the integer 1 or 2. \fBWindows \fR(all versions) . Valid values for \fIfileName\fR to open a serial port are of the form -\fBcom\fIX\fB:\fR, where \fIX\fR is a number, generally from 1 to 4. An -attempt to open a serial port that does not exist will fail. +\fBcom\fIX\fB:\fR, where \fIX\fR is a number, generally from 1 to 4. +This notation only works for serial ports from 1 to 9, if the system +happens to have more than four. An attempt to open a serial port that +does not exist or has a number greater than 9 will fail. An alternate +form of opening serial ports is to use the filename \fB\e\e.\ecomX\fR, +where X is any number that corresponds to a serial port; please note +that this method is considerably slower on Windows 95 and Windows 98. .TP \fBWindows NT\fR . @@ -202,19 +225,6 @@ application, no data will be sent to the command pipeline's standard output until the pipe is actually closed. This problem occurs because 16-bit DOS applications are run synchronously, as described above. .TP -\fBWindows 3.X\fR -. -A command pipeline can execute 16-bit or 32-bit DOS or Windows -applications, but the call to \fBopen\fR will not return until the last -program in the pipeline has finished executing; command pipelines run -synchronously. If the pipeline is opened with write access (either just -writing or both reading and writing) the first application in the -pipeline will instead see an immediate end-of-file; any data the caller -writes to the open pipe will instead be discarded. -.sp -Since Tcl cannot be run with a real console under Windows 3.X, there are -no interactions between command pipelines and the console. -.TP \fBMacintosh\fR . Opening a serial port is not currently implemented under Macintosh. diff --git a/tcl/doc/package.n b/tcl/doc/package.n index 9a7b4983c2f..d0c7e61e9fe 100644 --- a/tcl/doc/package.n +++ b/tcl/doc/package.n @@ -14,9 +14,10 @@ package \- Facilities for package loading and version control .SH SYNOPSIS .nf -\fBpackage forget \fIpackage\fR +\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? @@ -42,8 +43,8 @@ primarily by system scripts that maintain the package database. The behavior of the \fBpackage\fR command is determined by its first argument. The following forms are permitted: .TP -\fBpackage forget \fIpackage\fR -Removes all information about \fIpackage\fR from this interpreter, +\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 @@ -75,6 +76,10 @@ interpreter for which a version has been provided (via script is available. The order of elements in the list is arbitrary. .TP +\fBpackage present \fR?\fB\-exact\fR? \fIpackage \fR?\fIversion\fR? +This command is equivalent to \fBpackage require\fR except that it +does not try and load the package if it is not already loaded. +.TP \fBpackage provide \fIpackage \fR?\fIversion\fR? This command is invoked to indicate that version \fIversion\fR of package \fIpackage\fR is now present in the interpreter. @@ -186,3 +191,4 @@ See the documentation for \fBpkg_mkIndex\fR for details. .SH KEYWORDS package, version + diff --git a/tcl/doc/packagens.n b/tcl/doc/packagens.n new file mode 100644 index 00000000000..3854b675adf --- /dev/null +++ b/tcl/doc/packagens.n @@ -0,0 +1,53 @@ +'\" +'\" Copyright (c) 1998-2000 by Scriptics Corporation. +'\" All rights reserved. +'\" +'\" RCS: @(#) $Id$ +'\" +.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 +command for a given package specification +.SH SYNOPSIS +\fB::pkg::create \fI\-name packageName\fR \fI\-version packageVersion\fR ?\fI\-load filespec\fR? ... ?\fI\-source filespec\fR? ... +.BE + +.SH DESCRIPTION +.PP +\fB::pkg::create\fR is a utility procedure that is part of the standard Tcl +library. It is used to create an appropriate \fBpackage ifneeded\fR +command for a given package specification. It can be used to construct a +\fBpkgIndex.tcl\fR file for use with the \fBpackage\fR mechanism. + +.SH OPTIONS +The parameters supported are: +.TP +\fB\-name\fR\0\fIpackageName\fR +This parameter specifies the name of the package. It is required. +.TP +\fB\-version\fR\0\fIpackageVersion\fR +This parameter specifies the version of the package. It is required. +.TP +\fB\-load\fR\0\fIfilespec\fR +This parameter specifies a binary library that must be loaded with the +\fBload\fR command. \fIfilespec\fR is a list with two elements. The +first element is the name of the file to load. The second, optional +element is a list of commands supplied by loading that file. If the +list of procedures is empty or omitted, \fB::pkg::create\fR will +set up the library for direct loading (see \fBpkg_mkIndex\fR). Any +number of \fB\-load\fR parameters may be specified. +.TP +\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 KEYWORDS +auto-load, index, package, version + diff --git a/tcl/doc/pkgMkIndex.n b/tcl/doc/pkgMkIndex.n index 71683e48f4c..9980d108296 100644 --- a/tcl/doc/pkgMkIndex.n +++ b/tcl/doc/pkgMkIndex.n @@ -7,15 +7,15 @@ '\" RCS: @(#) $Id$ '\" .so man.macros -.TH pkg_mkIndex n 8.0 Tcl "Tcl Built-In Commands" +.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 .SH SYNOPSIS .nf -.VS 8.0.3 -\fBpkg_mkIndex ?\fI-direct\fR? ?\fI-load pkgPat\fR? ?\fI-verbose\fR? \fIdir\fR ?\fIpattern pattern ...\fR? +.VS 8.3.0 +\fBpkg_mkIndex ?\fI\-lazy\fR? ?\fI\-load pkgPat\fR? ?\fI\-verbose\fR? \fIdir\fR ?\fIpattern pattern ...\fR? .VE .fi .BE @@ -43,28 +43,8 @@ The \fIdir\fR argument gives the name of a directory and each script or binary files in \fIdir\fR. .VS 8.0.3 The default pattern is \fB*.tcl\fR and \fB*.[info sharedlibextension]\fR. -The optional switches are: -.TP 15 -\fB\-direct\fR -The generated index -will manage to load the package immediately upon \fBpackage require\fR -instead of delaying loading until actual use of one of the commands. -.TP 15 -\fB\-load \fIpkgPat\fR -The index process will pre-load any packages that exist in the -current interpreter and match \fIpkgPat\fP into the slave interpreter used to -generate the index. The pattern match uses string match rules. -See COMPLEX CASES below. -.TP 15 -\fB\-verbose\fR -Generate output during the indexing process. Output is via -the \fBtclLog\fP procedure, which by default prints to stderr. -.TP 15 -\fB\-\-\fR -End of the flags, in case \fIdir\fP begins with a dash. .VE -.LP -.RS +.br \fBPkg_mkIndex\fR will create a file \fBpkgIndex.tcl\fR in \fIdir\fR with package information about all the files given by the \fIpattern\fR arguments. @@ -75,10 +55,10 @@ and new commands appear (this is why it is essential to have in the files, as described above). If you have a package split among scripts and binary files, or if you have dependencies among files, -you may have to use the \fB-load\fP option +you may have to use the \fB\-load\fP option or adjust the order in which \fBpkg_mkIndex\fR processes the files. See COMPLEX CASES below. -.RE + .IP [3] Install the package as a subdirectory of one of the directories given by the \fBtcl_pkgPath\fR variable. If \fB$tcl_pkgPath\fR contains more @@ -92,7 +72,7 @@ the package's script and/or binary files as well as the \fBpkgIndex.tcl\fR file. As long as the package is installed as a subdirectory of a directory in \fB$tcl_pkgPath\fR it will automatically be found during \fBpackage require\fR commands. -.IP +.br If you install the package anywhere else, then you must ensure that the directory containing the package is in the \fBauto_path\fR global variable or an immediate subdirectory of one of the directories in \fBauto_path\fR. @@ -119,6 +99,27 @@ interpreter, based on the first call to \fBpackage require\fR. Different versions of a package may be loaded in different interpreters. +.SH OPTIONS +The optional switches are: +.TP 15 +\fB\-lazy\fR +The generated index will manage to delay loading the package until the +use of one of the commands provided by the package, instead of loading +it immediately upon \fBpackage require\fR. +.TP 15 +\fB\-load \fIpkgPat\fR +The index process will pre-load any packages that exist in the +current interpreter and match \fIpkgPat\fP into the slave interpreter used to +generate the index. The pattern match uses string match rules. +See COMPLEX CASES below. +.TP 15 +\fB\-verbose\fR +Generate output during the indexing process. Output is via +the \fBtclLog\fP procedure, which by default prints to stderr. +.TP 15 +\fB\-\-\fR +End of the flags, in case \fIdir\fP begins with a dash. + .SH "PACKAGES AND THE AUTO-LOADER" .PP The package management facilities overlap somewhat with the auto-loader, @@ -153,30 +154,26 @@ commands for each version of each available package; these commands invoke \fBpackage provide\fR commands to announce the availability of the package, and they setup auto-loader information to load the files of the package. -.VS 8.0.3 -Unless the \fI-direct\fR flag was provided when the \fBpkgIndex.tcl\fR +.VS 8.3 +If the \fI\-lazy\fR flag was provided when the \fBpkgIndex.tcl\fR was generated, .VE a given file of a given version of a given package isn't actually loaded until the first time one of its commands is invoked. -Thus, after invoking \fBpackage require\fR you -.VS 8.0.3 -may -.VE -not see -the package's commands in the interpreter, but you will be able +Thus, after invoking \fBpackage require\fR you may +not see the package's commands in the interpreter, but you will be able to invoke the commands and they will be auto-loaded. -.VS 8.0.3 +.VS 8.3 .SH "DIRECT LOADING" .PP Some packages, for instance packages which use namespaces and export commands or those which require special initialization, might select that their package files be loaded immediately upon \fBpackage require\fR instead of delaying the actual loading to the first use of one of the -package's command. This mode is enabled when generating the package -index by specifying the \fI-direct\fR argument. +package's command. This is the default mode when generating the package +index. It can be overridden by specifying the \fI\-lazy\fR argument. .VE .SH "COMPLEX CASES" @@ -210,7 +207,7 @@ For example, suppose the BLT package requires Tk, and expresses this with a call to \fBTcl_PkgRequire\fP in its \fBBlt_Init\fP routine. To support this, you must run \fBpkg_mkIndex\fR in an interpreter that has Tk loaded. You can achieve this with the -\fB-load \fIpkgPat\fR option. If you specify this option, +\fB\-load \fIpkgPat\fR option. If you specify this option, \fBpkg_mkIndex\fR will load any packages listed by \fBinfo loaded\fP and that match \fIpkgPat\fP into the interpreter used to process files. @@ -224,14 +221,14 @@ and then the package it provides will be available when the second file is processed. You may also need to load the first package into the temporary interpreter used to create the index by using -the \fB-load\fP flag; +the \fB\-load\fP flag; it won't hurt to specify package patterns that are not yet loaded. .PP 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 +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, +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. diff --git a/tcl/doc/puts.n b/tcl/doc/puts.n index 1c5113ab48b..88e3a42dc0d 100644 --- a/tcl/doc/puts.n +++ b/tcl/doc/puts.n @@ -34,8 +34,8 @@ value of the \fB\-translation\fR option for the channel (for example, on PCs newlines are normally replaced with carriage-return-linefeed sequences; on Macintoshes newlines are normally replaced with carriage-returns). -See the \fBfconfigure\fR manual entry for a discussion of end-of-line -translations. +See the \fBfconfigure\fR manual entry for a discussion on ways in +which \fBfconfigure\fR will alter output. .PP Tcl buffers output internally, so characters written with \fBputs\fR may not appear immediately on the output file or device; Tcl will diff --git a/tcl/doc/re_syntax.n b/tcl/doc/re_syntax.n new file mode 100644 index 00000000000..cb6b15ad2a0 --- /dev/null +++ b/tcl/doc/re_syntax.n @@ -0,0 +1,932 @@ +'\" +'\" Copyright (c) 1998 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$ +'\" +.so man.macros +.TH re_syntax n "8.1" Tcl "Tcl Built-In Commands" +.BS +.SH NAME +re_syntax \- Syntax of Tcl regular expressions. +.BE + +.SH DESCRIPTION +.PP +A \fIregular expression\fR describes strings of characters. +It's a pattern that matches certain strings and doesn't match others. + +.SH "DIFFERENT FLAVORS OF REs" +Regular expressions (``RE''s), as defined by POSIX, come in two +flavors: \fIextended\fR REs (``EREs'') and \fIbasic\fR REs (``BREs''). +EREs are roughly those of the traditional \fIegrep\fR, while BREs are +roughly those of the traditional \fIed\fR. This implementation adds +a third flavor, \fIadvanced\fR REs (``AREs''), basically EREs with +some significant extensions. +.PP +This manual page primarily describes AREs. BREs mostly exist for +backward compatibility in some old programs; they will be discussed at +the end. POSIX EREs are almost an exact subset of AREs. Features of +AREs that are not present in EREs will be indicated. + +.SH "REGULAR EXPRESSION SYNTAX" +.PP +Tcl regular expressions are implemented using the package written by +Henry Spencer, based on the 1003.2 spec and some (not quite all) of +the Perl5 extensions (thanks, Henry!). Much of the description of +regular expressions below is copied verbatim from his manual entry. +.PP +An ARE is one or more \fIbranches\fR, +separated by `\fB|\fR', +matching anything that matches any of the branches. +.PP +A branch is zero or more \fIconstraints\fR or \fIquantified atoms\fR, +concatenated. +It matches a match for the first, followed by a match for the second, etc; +an empty branch matches the empty string. +.PP +A quantified atom is an \fIatom\fR possibly followed +by a single \fIquantifier\fR. +Without a quantifier, it matches a match for the atom. +The quantifiers, +and what a so-quantified atom matches, are: +.RS 2 +.TP 6 +\fB*\fR +a sequence of 0 or more matches of the atom +.TP +\fB+\fR +a sequence of 1 or more matches of the atom +.TP +\fB?\fR +a sequence of 0 or 1 matches of the atom +.TP +\fB{\fIm\fB}\fR +a sequence of exactly \fIm\fR matches of the atom +.TP +\fB{\fIm\fB,}\fR +a sequence of \fIm\fR or more matches of the atom +.TP +\fB{\fIm\fB,\fIn\fB}\fR +a sequence of \fIm\fR through \fIn\fR (inclusive) matches of the atom; +\fIm\fR may not exceed \fIn\fR +.TP +\fB*? +? ?? {\fIm\fB}? {\fIm\fB,}? {\fIm\fB,\fIn\fB}?\fR +\fInon-greedy\fR quantifiers, +which match the same possibilities, +but prefer the smallest number rather than the largest number +of matches (see MATCHING) +.RE +.PP +The forms using +\fB{\fR and \fB}\fR +are known as \fIbound\fRs. +The numbers +\fIm\fR and \fIn\fR are unsigned decimal integers +with permissible values from 0 to 255 inclusive. +.PP +An atom is one of: +.RS 2 +.TP 6 +\fB(\fIre\fB)\fR +(where \fIre\fR is any regular expression) +matches a match for +\fIre\fR, with the match noted for possible reporting +.TP +\fB(?:\fIre\fB)\fR +as previous, +but does no reporting +(a ``non-capturing'' set of parentheses) +.TP +\fB()\fR +matches an empty string, +noted for possible reporting +.TP +\fB(?:)\fR +matches an empty string, +without reporting +.TP +\fB[\fIchars\fB]\fR +a \fIbracket expression\fR, +matching any one of the \fIchars\fR (see BRACKET EXPRESSIONS for more detail) +.TP + \fB.\fR +matches any single character +.TP +\fB\e\fIk\fR +(where \fIk\fR is a non-alphanumeric character) +matches that character taken as an ordinary character, +e.g. \e\e matches a backslash character +.TP +\fB\e\fIc\fR +where \fIc\fR is alphanumeric +(possibly followed by other characters), +an \fIescape\fR (AREs only), +see ESCAPES below +.TP +\fB{\fR +when followed by a character other than a digit, +matches the left-brace character `\fB{\fR'; +when followed by a digit, it is the beginning of a +\fIbound\fR (see above) +.TP +\fIx\fR +where \fIx\fR is +a single character with no other significance, matches that character. +.RE +.PP +A \fIconstraint\fR matches an empty string when specific conditions +are met. +A constraint may not be followed by a quantifier. +The simple constraints are as follows; some more constraints are +described later, under ESCAPES. +.RS 2 +.TP 8 +\fB^\fR +matches at the beginning of a line +.TP +\fB$\fR +matches at the end of a line +.TP +\fB(?=\fIre\fB)\fR +\fIpositive lookahead\fR (AREs only), matches at any point +where a substring matching \fIre\fR begins +.TP +\fB(?!\fIre\fB)\fR +\fInegative lookahead\fR (AREs only), matches at any point +where no substring matching \fIre\fR begins +.RE +.PP +The lookahead constraints may not contain back references (see later), +and all parentheses within them are considered non-capturing. +.PP +An RE may not end with `\fB\e\fR'. + +.SH "BRACKET EXPRESSIONS" +A \fIbracket expression\fR is a list of characters enclosed in `\fB[\|]\fR'. +It normally matches any single character from the list (but see below). +If the list begins with `\fB^\fR', +it matches any single character +(but see below) \fInot\fR from the rest of the list. +.PP +If two characters in the list are separated by `\fB\-\fR', +this is shorthand +for the full \fIrange\fR of characters between those two (inclusive) in the +collating sequence, +e.g. +\fB[0\-9]\fR +in ASCII matches any decimal digit. +Two ranges may not share an +endpoint, so e.g. +\fBa\-c\-e\fR +is illegal. +Ranges are very collating-sequence-dependent, +and portable programs should avoid relying on them. +.PP +To include a literal +\fB]\fR +or +\fB\-\fR +in the list, +the simplest method is to +enclose it in +\fB[.\fR and \fB.]\fR +to make it a collating element (see below). +Alternatively, +make it the first character +(following a possible `\fB^\fR'), +or (AREs only) precede it with `\fB\e\fR'. +Alternatively, for `\fB\-\fR', +make it the last character, +or the second endpoint of a range. +To use a literal +\fB\-\fR +as the first endpoint of a range, +make it a collating element +or (AREs only) precede it with `\fB\e\fR'. +With the exception of these, some combinations using +\fB[\fR +(see next +paragraphs), and escapes, +all other special characters lose their +special significance within a bracket expression. +.PP +Within a bracket expression, a collating element (a character, +a multi-character sequence that collates as if it were a single character, +or a collating-sequence name for either) +enclosed in +\fB[.\fR and \fB.]\fR +stands for the +sequence of characters of that collating element. +The sequence is a single element of the bracket expression's list. +A bracket expression in a locale that has +multi-character collating elements +can thus match more than one character. +.VS 8.2 +So (insidiously), a bracket expression that starts with \fB^\fR +can match multi-character collating elements even if none of them +appear in the bracket expression! +(\fINote:\fR Tcl currently has no multi-character collating elements. +This information is only for illustration.) +.PP +For example, assume the collating sequence includes a \fBch\fR +multi-character collating element. +Then the RE \fB[[.ch.]]*c\fR (zero or more \fBch\fP's followed by \fBc\fP) +matches the first five characters of `\fBchchcc\fR'. +Also, the RE \fB[^c]b\fR matches all of `\fBchb\fR' +(because \fB[^c]\fR matches the multi-character \fBch\fR). +.VE 8.2 +.PP +Within a bracket expression, a collating element enclosed in +\fB[=\fR +and +\fB=]\fR +is an equivalence class, standing for the sequences of characters +of all collating elements equivalent to that one, including itself. +(If there are no other equivalent collating elements, +the treatment is as if the enclosing delimiters were `\fB[.\fR'\& +and `\fB.]\fR'.) +For example, if +\fBo\fR +and +\fB\o'o^'\fR +are the members of an equivalence class, +then `\fB[[=o=]]\fR', `\fB[[=\o'o^'=]]\fR', +and `\fB[o\o'o^']\fR'\& +are all synonymous. +An equivalence class may not be an endpoint +of a range. +.VS 8.2 +(\fINote:\fR +Tcl currently implements only the Unicode locale. +It doesn't define any equivalence classes. +The examples above are just illustrations.) +.VE 8.2 +.PP +Within a bracket expression, the name of a \fIcharacter class\fR enclosed +in +\fB[:\fR +and +\fB:]\fR +stands for the list of all characters +(not all collating elements!) +belonging to that +class. +Standard character classes are: +.PP +.RS +.ne 5 +.nf +.ta 3c +\fBalpha\fR A letter. +\fBupper\fR An upper-case letter. +\fBlower\fR A lower-case letter. +\fBdigit\fR A decimal digit. +\fBxdigit\fR A hexadecimal digit. +\fBalnum\fR An alphanumeric (letter or digit). +\fBprint\fR An alphanumeric (same as alnum). +\fBblank\fR A space or tab character. +\fBspace\fR A character producing white space in displayed text. +\fBpunct\fR A punctuation character. +\fBgraph\fR A character with a visible representation. +\fBcntrl\fR A control character. +.fi +.RE +.PP +A locale may provide others. +.VS 8.2 +(Note that the current Tcl implementation has only one locale: +the Unicode locale.) +.VE 8.2 +A character class may not be used as an endpoint of a range. +.PP +There are two special cases of bracket expressions: +the bracket expressions +\fB[[:<:]]\fR +and +\fB[[:>:]]\fR +are constraints, matching empty strings at +the beginning and end of a word respectively. +'\" note, discussion of escapes below references this definition of word +A word is defined as a sequence of +word characters +that is neither preceded nor followed by +word characters. +A word character is an +\fIalnum\fR +character +or an underscore +(\fB_\fR). +These special bracket expressions are deprecated; +users of AREs should use constraint escapes instead (see below). +.SH ESCAPES +Escapes (AREs only), which begin with a +\fB\e\fR +followed by an alphanumeric character, +come in several varieties: +character entry, class shorthands, constraint escapes, and back references. +A +\fB\e\fR +followed by an alphanumeric character but not constituting +a valid escape is illegal in AREs. +In EREs, there are no escapes: +outside a bracket expression, +a +\fB\e\fR +followed by an alphanumeric character merely stands for that +character as an ordinary character, +and inside a bracket expression, +\fB\e\fR +is an ordinary character. +(The latter is the one actual incompatibility between EREs and AREs.) +.PP +Character-entry escapes (AREs only) exist to make it easier to specify +non-printing and otherwise inconvenient characters in REs: +.RS 2 +.TP 5 +\fB\ea\fR +alert (bell) character, as in C +.TP +\fB\eb\fR +backspace, as in C +.TP +\fB\eB\fR +synonym for +\fB\e\fR +to help reduce backslash doubling in some +applications where there are multiple levels of backslash processing +.TP +\fB\ec\fIX\fR +(where X is any character) the character whose +low-order 5 bits are the same as those of +\fIX\fR, +and whose other bits are all zero +.TP +\fB\ee\fR +the character whose collating-sequence name +is `\fBESC\fR', +or failing that, the character with octal value 033 +.TP +\fB\ef\fR +formfeed, as in C +.TP +\fB\en\fR +newline, as in C +.TP +\fB\er\fR +carriage return, as in C +.TP +\fB\et\fR +horizontal tab, as in C +.TP +\fB\eu\fIwxyz\fR +(where +\fIwxyz\fR +is exactly four hexadecimal digits) +the Unicode character +\fBU+\fIwxyz\fR +in the local byte ordering +.TP +\fB\eU\fIstuvwxyz\fR +(where +\fIstuvwxyz\fR +is exactly eight hexadecimal digits) +reserved for a somewhat-hypothetical Unicode extension to 32 bits +.TP +\fB\ev\fR +vertical tab, as in C +are all available. +.TP +\fB\ex\fIhhh\fR +(where +\fIhhh\fR +is any sequence of hexadecimal digits) +the character whose hexadecimal value is +\fB0x\fIhhh\fR +(a single character no matter how many hexadecimal digits are used). +.TP +\fB\e0\fR +the character whose value is +\fB0\fR +.TP +\fB\e\fIxy\fR +(where +\fIxy\fR +is exactly two octal digits, +and is not a +\fIback reference\fR (see below)) +the character whose octal value is +\fB0\fIxy\fR +.TP +\fB\e\fIxyz\fR +(where +\fIxyz\fR +is exactly three octal digits, +and is not a +back reference (see below)) +the character whose octal value is +\fB0\fIxyz\fR +.RE +.PP +Hexadecimal digits are `\fB0\fR'-`\fB9\fR', `\fBa\fR'-`\fBf\fR', +and `\fBA\fR'-`\fBF\fR'. +Octal digits are `\fB0\fR'-`\fB7\fR'. +.PP +The character-entry escapes are always taken as ordinary characters. +For example, +\fB\e135\fR +is +\fB]\fR +in ASCII, +but +\fB\e135\fR +does not terminate a bracket expression. +Beware, however, that some applications (e.g., C compilers) interpret +such sequences themselves before the regular-expression package +gets to see them, which may require doubling (quadrupling, etc.) the `\fB\e\fR'. +.PP +Class-shorthand escapes (AREs only) provide shorthands for certain commonly-used +character classes: +.RS 2 +.TP 10 +\fB\ed\fR +\fB[[:digit:]]\fR +.TP +\fB\es\fR +\fB[[:space:]]\fR +.TP +\fB\ew\fR +\fB[[:alnum:]_]\fR +(note underscore) +.TP +\fB\eD\fR +\fB[^[:digit:]]\fR +.TP +\fB\eS\fR +\fB[^[:space:]]\fR +.TP +\fB\eW\fR +\fB[^[:alnum:]_]\fR +(note underscore) +.RE +.PP +Within bracket expressions, `\fB\ed\fR', `\fB\es\fR', +and `\fB\ew\fR'\& +lose their outer brackets, +and `\fB\eD\fR', `\fB\eS\fR', +and `\fB\eW\fR'\& +are illegal. +.VS 8.2 +(So, for example, \fB[a-c\ed]\fR is equivalent to \fB[a-c[:digit:]]\fR. +Also, \fB[a-c\eD]\fR, which is equivalent to \fB[a-c^[:digit:]]\fR, is illegal.) +.VE 8.2 +.PP +A constraint escape (AREs only) is a constraint, +matching the empty string if specific conditions are met, +written as an escape: +.RS 2 +.TP 6 +\fB\eA\fR +matches only at the beginning of the string +(see MATCHING, below, for how this differs from `\fB^\fR') +.TP +\fB\em\fR +matches only at the beginning of a word +.TP +\fB\eM\fR +matches only at the end of a word +.TP +\fB\ey\fR +matches only at the beginning or end of a word +.TP +\fB\eY\fR +matches only at a point that is not the beginning or end of a word +.TP +\fB\eZ\fR +matches only at the end of the string +(see MATCHING, below, for how this differs from `\fB$\fR') +.TP +\fB\e\fIm\fR +(where +\fIm\fR +is a nonzero digit) a \fIback reference\fR, see below +.TP +\fB\e\fImnn\fR +(where +\fIm\fR +is a nonzero digit, and +\fInn\fR +is some more digits, +and the decimal value +\fImnn\fR +is not greater than the number of closing capturing parentheses seen so far) +a \fIback reference\fR, see below +.RE +.PP +A word is defined as in the specification of +\fB[[:<:]]\fR +and +\fB[[:>:]]\fR +above. +Constraint escapes are illegal within bracket expressions. +.PP +A back reference (AREs only) matches the same string matched by the parenthesized +subexpression specified by the number, +so that (e.g.) +\fB([bc])\e1\fR +matches +\fBbb\fR +or +\fBcc\fR +but not `\fBbc\fR'. +The subexpression must entirely precede the back reference in the RE. +Subexpressions are numbered in the order of their leading parentheses. +Non-capturing parentheses do not define subexpressions. +.PP +There is an inherent historical ambiguity between octal character-entry +escapes and back references, which is resolved by heuristics, +as hinted at above. +A leading zero always indicates an octal escape. +A single non-zero digit, not followed by another digit, +is always taken as a back reference. +A multi-digit sequence not starting with a zero is taken as a back +reference if it comes after a suitable subexpression +(i.e. the number is in the legal range for a back reference), +and otherwise is taken as octal. +.SH "METASYNTAX" +In addition to the main syntax described above, there are some special +forms and miscellaneous syntactic facilities available. +.PP +Normally the flavor of RE being used is specified by +application-dependent means. +However, this can be overridden by a \fIdirector\fR. +If an RE of any flavor begins with `\fB***:\fR', +the rest of the RE is an ARE. +If an RE of any flavor begins with `\fB***=\fR', +the rest of the RE is taken to be a literal string, +with all characters considered ordinary characters. +.PP +An ARE may begin with \fIembedded options\fR: +a sequence +\fB(?\fIxyz\fB)\fR +(where +\fIxyz\fR +is one or more alphabetic characters) +specifies options affecting the rest of the RE. +These supplement, and can override, +any options specified by the application. +The available option letters are: +.RS 2 +.TP 3 +\fBb\fR +rest of RE is a BRE +.TP 3 +\fBc\fR +case-sensitive matching (usual default) +.TP 3 +\fBe\fR +rest of RE is an ERE +.TP 3 +\fBi\fR +case-insensitive matching (see MATCHING, below) +.TP 3 +\fBm\fR +historical synonym for +\fBn\fR +.TP 3 +\fBn\fR +newline-sensitive matching (see MATCHING, below) +.TP 3 +\fBp\fR +partial newline-sensitive matching (see MATCHING, below) +.TP 3 +\fBq\fR +rest of RE is a literal (``quoted'') string, all ordinary characters +.TP 3 +\fBs\fR +non-newline-sensitive matching (usual default) +.TP 3 +\fBt\fR +tight syntax (usual default; see below) +.TP 3 +\fBw\fR +inverse partial newline-sensitive (``weird'') matching (see MATCHING, below) +.TP 3 +\fBx\fR +expanded syntax (see below) +.RE +.PP +Embedded options take effect at the +\fB)\fR +terminating the sequence. +They are available only at the start of an ARE, +and may not be used later within it. +.PP +In addition to the usual (\fItight\fR) RE syntax, in which all characters are +significant, there is an \fIexpanded\fR syntax, +available in all flavors of RE +with the \fB-expanded\fR switch, or in AREs with the embedded x option. +In the expanded syntax, +white-space characters are ignored +and all characters between a +\fB#\fR +and the following newline (or the end of the RE) are ignored, +permitting paragraphing and commenting a complex RE. +There are three exceptions to that basic rule: +.RS 2 +.PP +a white-space character or `\fB#\fR' preceded by `\fB\e\fR' is retained +.PP +white space or `\fB#\fR' within a bracket expression is retained +.PP +white space and comments are illegal within multi-character symbols +like the ARE `\fB(?:\fR' or the BRE `\fB\e(\fR' +.RE +.PP +Expanded-syntax white-space characters are blank, tab, newline, and +.VS 8.2 +any character that belongs to the \fIspace\fR character class. +.VE 8.2 +.PP +Finally, in an ARE, +outside bracket expressions, the sequence `\fB(?#\fIttt\fB)\fR' +(where +\fIttt\fR +is any text not containing a `\fB)\fR') +is a comment, +completely ignored. +Again, this is not allowed between the characters of +multi-character symbols like `\fB(?:\fR'. +Such comments are more a historical artifact than a useful facility, +and their use is deprecated; +use the expanded syntax instead. +.PP +\fINone\fR of these metasyntax extensions is available if the application +(or an initial +\fB***=\fR +director) +has specified that the user's input be treated as a literal string +rather than as an RE. +.SH MATCHING +In the event that an RE could match more than one substring of a given +string, +the RE matches the one starting earliest in the string. +If the RE could match more than one substring starting at that point, +its choice is determined by its \fIpreference\fR: +either the longest substring, or the shortest. +.PP +Most atoms, and all constraints, have no preference. +A parenthesized RE has the same preference (possibly none) as the RE. +A quantified atom with quantifier +\fB{\fIm\fB}\fR +or +\fB{\fIm\fB}?\fR +has the same preference (possibly none) as the atom itself. +A quantified atom with other normal quantifiers (including +\fB{\fIm\fB,\fIn\fB}\fR +with +\fIm\fR +equal to +\fIn\fR) +prefers longest match. +A quantified atom with other non-greedy quantifiers (including +\fB{\fIm\fB,\fIn\fB}?\fR +with +\fIm\fR +equal to +\fIn\fR) +prefers shortest match. +A branch has the same preference as the first quantified atom in it +which has a preference. +An RE consisting of two or more branches connected by the +\fB|\fR +operator prefers longest match. +.PP +Subject to the constraints imposed by the rules for matching the whole RE, +subexpressions also match the longest or shortest possible substrings, +based on their preferences, +with subexpressions starting earlier in the RE taking priority over +ones starting later. +Note that outer subexpressions thus take priority over +their component subexpressions. +.PP +Note that the quantifiers +\fB{1,1}\fR +and +\fB{1,1}?\fR +can be used to force longest and shortest preference, respectively, +on a subexpression or a whole RE. +.PP +Match lengths are measured in characters, not collating elements. +An empty string is considered longer than no match at all. +For example, +\fBbb*\fR +matches the three middle characters of `\fBabbbc\fR', +\fB(week|wee)(night|knights)\fR +matches all ten characters of `\fBweeknights\fR', +when +\fB(.*).*\fR +is matched against +\fBabc\fR +the parenthesized subexpression +matches all three characters, and +when +\fB(a*)*\fR +is matched against +\fBbc\fR +both the whole RE and the parenthesized +subexpression match an empty string. +.PP +If case-independent matching is specified, +the effect is much as if all case distinctions had vanished from the +alphabet. +When an alphabetic that exists in multiple cases appears as an +ordinary character outside a bracket expression, it is effectively +transformed into a bracket expression containing both cases, +so that +\fBx\fR +becomes `\fB[xX]\fR'. +When it appears inside a bracket expression, all case counterparts +of it are added to the bracket expression, so that +\fB[x]\fR +becomes +\fB[xX]\fR +and +\fB[^x]\fR +becomes `\fB[^xX]\fR'. +.PP +If newline-sensitive matching is specified, \fB.\fR +and bracket expressions using +\fB^\fR +will never match the newline character +(so that matches will never cross newlines unless the RE +explicitly arranges it) +and +\fB^\fR +and +\fB$\fR +will match the empty string after and before a newline +respectively, in addition to matching at beginning and end of string +respectively. +ARE +\fB\eA\fR +and +\fB\eZ\fR +continue to match beginning or end of string \fIonly\fR. +.PP +If partial newline-sensitive matching is specified, +this affects \fB.\fR +and bracket expressions +as with newline-sensitive matching, but not +\fB^\fR +and `\fB$\fR'. +.PP +If inverse partial newline-sensitive matching is specified, +this affects +\fB^\fR +and +\fB$\fR +as with +newline-sensitive matching, +but not \fB.\fR +and bracket expressions. +This isn't very useful but is provided for symmetry. +.SH "LIMITS AND COMPATIBILITY" +No particular limit is imposed on the length of REs. +Programs intended to be highly portable should not employ REs longer +than 256 bytes, +as a POSIX-compliant implementation can refuse to accept such REs. +.PP +The only feature of AREs that is actually incompatible with +POSIX EREs is that +\fB\e\fR +does not lose its special +significance inside bracket expressions. +All other ARE features use syntax which is illegal or has +undefined or unspecified effects in POSIX EREs; +the +\fB***\fR +syntax of directors likewise is outside the POSIX +syntax for both BREs and EREs. +.PP +Many of the ARE extensions are borrowed from Perl, but some have +been changed to clean them up, and a few Perl extensions are not present. +Incompatibilities of note include `\fB\eb\fR', `\fB\eB\fR', +the lack of special treatment for a trailing newline, +the addition of complemented bracket expressions to the things +affected by newline-sensitive matching, +the restrictions on parentheses and back references in lookahead constraints, +and the longest/shortest-match (rather than first-match) matching semantics. +.PP +The matching rules for REs containing both normal and non-greedy quantifiers +have changed since early beta-test versions of this package. +(The new rules are much simpler and cleaner, +but don't work as hard at guessing the user's real intentions.) +.PP +Henry Spencer's original 1986 \fIregexp\fR package, +still in widespread use (e.g., in pre-8.1 releases of Tcl), +implemented an early version of today's EREs. +There are four incompatibilities between \fIregexp\fR's near-EREs +(`RREs' for short) and AREs. +In roughly increasing order of significance: +.PP +.RS +In AREs, +\fB\e\fR +followed by an alphanumeric character is either an +escape or an error, +while in RREs, it was just another way of writing the +alphanumeric. +This should not be a problem because there was no reason to write +such a sequence in RREs. +.PP +\fB{\fR +followed by a digit in an ARE is the beginning of a bound, +while in RREs, +\fB{\fR +was always an ordinary character. +Such sequences should be rare, +and will often result in an error because following characters +will not look like a valid bound. +.PP +In AREs, +\fB\e\fR +remains a special character within `\fB[\|]\fR', +so a literal +\fB\e\fR +within +\fB[\|]\fR +must be written `\fB\e\e\fR'. +\fB\e\e\fR +also gives a literal +\fB\e\fR +within +\fB[\|]\fR +in RREs, +but only truly paranoid programmers routinely doubled the backslash. +.PP +AREs report the longest/shortest match for the RE, +rather than the first found in a specified search order. +This may affect some RREs which were written in the expectation that +the first match would be reported. +(The careful crafting of RREs to optimize the search order for fast +matching is obsolete (AREs examine all possible matches +in parallel, and their performance is largely insensitive to their +complexity) but cases where the search order was exploited to deliberately +find a match which was \fInot\fR the longest/shortest will need rewriting.) +.RE + +.SH "BASIC REGULAR EXPRESSIONS" +BREs differ from EREs in several respects. `\fB|\fR', `\fB+\fR', +and +\fB?\fR +are ordinary characters and there is no equivalent +for their functionality. +The delimiters for bounds are +\fB\e{\fR +and `\fB\e}\fR', +with +\fB{\fR +and +\fB}\fR +by themselves ordinary characters. +The parentheses for nested subexpressions are +\fB\e(\fR +and `\fB\e)\fR', +with +\fB(\fR +and +\fB)\fR +by themselves ordinary characters. +\fB^\fR +is an ordinary character except at the beginning of the +RE or the beginning of a parenthesized subexpression, +\fB$\fR +is an ordinary character except at the end of the +RE or the end of a parenthesized subexpression, +and +\fB*\fR +is an ordinary character if it appears at the beginning of the +RE or the beginning of a parenthesized subexpression +(after a possible leading `\fB^\fR'). +Finally, +single-digit back references are available, +and +\fB\e<\fR +and +\fB\e>\fR +are synonyms for +\fB[[:<:]]\fR +and +\fB[[:>:]]\fR +respectively; +no other escapes are available. + +.SH "SEE ALSO" +RegExp(3), regexp(n), regsub(n), lsearch(n), switch(n), text(n) + +.SH KEYWORDS +match, regular expression, string diff --git a/tcl/doc/read.n b/tcl/doc/read.n index f294a8bff04..113c9c61626 100644 --- a/tcl/doc/read.n +++ b/tcl/doc/read.n @@ -8,7 +8,7 @@ '\" RCS: @(#) $Id$ '\" .so man.macros -.TH read n 7.5 Tcl "Tcl Built-In Commands" +.TH read n 8.1 Tcl "Tcl Built-In Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -16,7 +16,7 @@ read \- Read from a channel .SH SYNOPSIS \fBread \fR?\fB\-nonewline\fR? \fIchannelId\fR .sp -\fBread \fIchannelId numBytes\fR +\fBread \fIchannelId numChars\fR .BE .SH DESCRIPTION @@ -25,26 +25,34 @@ In the first form, the \fBread\fR command reads all of the data from \fIchannelId\fR up to the end of the file. If the \fB\-nonewline\fR switch is specified then the last character of the file is discarded if it is a newline. -In the second form, the extra argument specifies how many bytes to -read. Exactly that many bytes will be read and returned, unless -there are fewer than \fInumBytes\fR left in the file; in this case -all the remaining bytes are returned. +.VS 8.1 +In the second form, the extra argument specifies how many characters to +read. Exactly that many characters will be read and returned, unless +there are fewer than \fInumChars\fR left in the file; in this case +all the remaining characters are returned. If the channel is +configured to use a multi-byte encoding, then the number of characters +read may not be the same as the number of bytes read. .PP -If \fIchannelId\fR is in nonblocking mode, the command may not read -as many bytes as requested: once all available input has been read, -the command will return the data that is available rather than blocking -for more input. +If \fIchannelId\fR is in nonblocking mode, the command may not read as +many characters as requested: once all available input has been read, +the command will return the data that is available rather than +blocking for more input. If the channel is configured to use a +multi-byte encoding, then there may actually be some bytes remaining +in the internal buffers that do not form a complete character. These +bytes will not be returned until a complete character is available or +end-of-file is reached. +.VE 8.1 The \fB\-nonewline\fR switch is ignored if the command returns before reaching the end of the file. .PP \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 manual entry for \fBfconfigure\fR for details on the -\fB\-translation\fR option. +See the \fBfconfigure\fR manual entry for a discussion on ways in +which \fBfconfigure\fR will alter input. .SH "SEE ALSO" eof(n), fblocked(n), fconfigure(n) .SH KEYWORDS -blocking, channel, end of line, end of file, nonblocking, read, translation +blocking, channel, end of line, end of file, nonblocking, read, translation, encoding diff --git a/tcl/doc/regexp.n b/tcl/doc/regexp.n index af39c918314..6e598903ff6 100644 --- a/tcl/doc/regexp.n +++ b/tcl/doc/regexp.n @@ -1,6 +1,5 @@ '\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" 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. @@ -8,11 +7,12 @@ '\" RCS: @(#) $Id$ '\" .so man.macros -.TH regexp n "" Tcl "Tcl Built-In Commands" +.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 + .SH SYNOPSIS \fBregexp \fR?\fIswitches\fR? \fIexp string \fR?\fImatchVar\fR? ?\fIsubMatchVar subMatchVar ...\fR? .BE @@ -20,7 +20,10 @@ regexp \- Match a regular expression against a string .SH DESCRIPTION .PP Determines whether the regular expression \fIexp\fR matches part or -all of \fIstring\fR and returns 1 if it does, 0 if it doesn't. +all of \fIstring\fR and returns 1 if it does, 0 if it doesn't, unless +\fB-inline\fR is specified (see below). +(Regular expression matching is described in the \fBre_syntax\fR +reference page.) .LP If additional arguments are specified after \fIstring\fR then they are treated as the names of variables in which to return @@ -31,27 +34,91 @@ the characters in \fIstring\fR that matched the leftmost parenthesized subexpression within \fIexp\fR, the next \fIsubMatchVar\fR will contain the characters that matched the next parenthesized subexpression to the right in \fIexp\fR, and so on. -.LP +.PP If the initial arguments to \fBregexp\fR start with \fB\-\fR then they are treated as switches. The following switches are currently supported: -.TP 10 -\fB\-nocase\fR -Causes upper-case characters in \fIstring\fR to be treated as -lower case during the matching process. -.TP 10 +.TP 15 +\fB\-about\fR +Instead of attempting to match the regular expression, returns a list +containing information about the regular expression. The first +element of the list is a subexpression count. The second element is a +list of property names that describe various attributes of the regular +expression. This switch is primarily intended for debugging purposes. +.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\-indices\fR Changes what is stored in the \fIsubMatchVar\fRs. -Instead of storing the matching characters from \fBstring\fR, +Instead of storing the matching characters from \fIstring\fR, each variable will contain a list of two decimal strings giving the indices in \fIstring\fR of the first and last characters in the matching range of characters. -.TP 10 +.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 15 +\fB\-nocase\fR +Causes upper-case characters in \fIstring\fR to be treated as +lower case during the matching process. +.VS 8.3 +.TP 15 +\fB\-all\fR +Causes the regular expression to be matched as many times as possible +in the string, returning the total number of matches found. If this +is specified with match variables, they will continue information for +the last match only. +.TP 15 +\fB\-inline\fR +Causes the command to return, as a list, the data that would otherwise +be placed in match variables. When using \fB-inline\fR, +match variables may not be specified. If used with \fB-all\fR, the +list will be concatenated at each iteration, such that a flat list is +always returned. For each match iteration, the command will append the +overall match data, plus one element for each subexpression in the +regular expression. Examples are: +.CS + regexp -inline -- {\\w(\\w)} " inlined " + => {in n} + regexp -all -inline -- {\\w(\\w)} " inlined " + => {in n li i ne e} +.CE +.TP 15 +\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. If \fB\-indices\fR +is specified, the indices will be indexed starting from the +absolute beginning of the input string. +\fIindex\fR will be constrained to the bounds of the input string. +.VE 8.3 +.TP 15 \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. -.LP +.PP If there are more \fIsubMatchVar\fR's than parenthesized subexpressions within \fIexp\fR, or if a particular subexpression in \fIexp\fR doesn't match the string (e.g. because it was in a @@ -59,87 +126,9 @@ 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 "REGULAR EXPRESSIONS" -.PP -Regular expressions are implemented using Henry Spencer's package -(thanks, Henry!), -and much of the description of regular expressions below is copied verbatim -from his manual entry. -.PP -A regular expression is zero or more \fIbranches\fR, separated by ``|''. -It matches anything that matches one of the branches. -.PP -A branch is zero or more \fIpieces\fR, concatenated. -It matches a match for the first, followed by a match for the second, etc. -.PP -A piece is an \fIatom\fR possibly followed by ``*'', ``+'', or ``?''. -An atom followed by ``*'' matches a sequence of 0 or more matches of the atom. -An atom followed by ``+'' matches a sequence of 1 or more matches of the atom. -An atom followed by ``?'' matches a match of the atom, or the null string. -.PP -An atom is a regular expression in parentheses (matching a match for the -regular expression), a \fIrange\fR (see below), ``.'' -(matching any single character), ``^'' (matching the null string at the -beginning of the input string), ``$'' (matching the null string at the -end of the input string), a ``\e'' followed by a single character (matching -that character), or a single character with no other significance -(matching that character). -.PP -A \fIrange\fR is a sequence of characters enclosed in ``[]''. -It normally matches any single character from the sequence. -If the sequence begins with ``^'', -it matches any single character \fInot\fR from the rest of the sequence. -If two characters in the sequence are separated by ``\-'', this is shorthand -for the full list of ASCII characters between them -(e.g. ``[0-9]'' matches any decimal digit). -To include a literal ``]'' in the sequence, make it the first character -(following a possible ``^''). -To include a literal ``\-'', make it the first or last character. - -.SH "CHOOSING AMONG ALTERNATIVE MATCHES" -.PP -In general there may be more than one way to match a regular expression -to an input string. For example, consider the command -.CS -\fBregexp (a*)b* aabaaabb x y\fR -.CE -Considering only the rules given so far, \fBx\fR and \fBy\fR could -end up with the values \fBaabb\fR and \fBaa\fR, \fBaaab\fR and \fBaaa\fR, -\fBab\fR and \fBa\fR, or any of several other combinations. -To resolve this potential ambiguity \fBregexp\fR chooses among -alternatives using the rule ``first then longest''. -In other words, it considers the possible matches in order working -from left to right across the input string and the pattern, and it -attempts to match longer pieces of the input string before shorter -ones. More specifically, the following rules apply in decreasing -order of priority: -.IP [1] -If a regular expression could match two different parts of an input string -then it will match the one that begins earliest. -.IP [2] -If a regular expression contains \fB|\fR operators then the leftmost -matching sub-expression is chosen. -.IP [3] -In \fB*\fR, \fB+\fR, and \fB?\fR constructs, longer matches are chosen -in preference to shorter ones. -.IP [4] -In sequences of expression components the components are considered -from left to right. -.LP -In the example from above, \fB(a*)b*\fR matches \fBaab\fR: the \fB(a*)\fR -portion of the pattern is matched first and it consumes the leading -\fBaa\fR; then the \fBb*\fR portion of the pattern consumes the -next \fBb\fR. Or, consider the following example: -.CS -\fBregexp (ab|a)(b*)c abc x y z\fR -.CE -After this command \fBx\fR will be \fBabc\fR, \fBy\fR will be -\fBab\fR, and \fBz\fR will be an empty string. -Rule 4 specifies that \fB(ab|a)\fR gets first shot at the input -string and Rule 2 specifies that the \fBab\fR sub-expression -is checked before the \fBa\fR sub-expression. -Thus the \fBb\fR has already been claimed before the \fB(b*)\fR -component is checked and \fB(b*)\fR must match an empty string. +.SH "SEE ALSO" +re_syntax(n) .SH KEYWORDS match, regular expression, string + diff --git a/tcl/doc/registry.n b/tcl/doc/registry.n index f1b48b2146e..d205f606ccf 100644 --- a/tcl/doc/registry.n +++ b/tcl/doc/registry.n @@ -39,8 +39,11 @@ one of the following forms: \fIHostname\fR specifies the name of any valid Windows host that exports its registry. The \fIrootname\fR component must be one of \fBHKEY_LOCAL_MACHINE\fR, \fBHKEY_USERS\fR, -\fBHKEY_CLASSES_ROOT\fR, \fBHKEY_CURRENT_USER\fR, or -\fBHKEY_CURRENT_CONFIG\fR. The \fIkeypath\fR can be one or more +.VS +\fBHKEY_CLASSES_ROOT\fR, \fBHKEY_CURRENT_USER\fR, +\fBHKEY_CURRENT_CONFIG\fR, \fBHKEY_PERFORMANCE_DATA\fR, or +\fBHKEY_DYN_DATA\fR. The \fIkeypath\fR can be one or more +.VE registry key names separated by backslash (\fB\e\fR) characters. .PP \fIOption\fR indicates what to do with the registry key name. Any @@ -109,7 +112,6 @@ registry command: . The registry value contains arbitrary binary data. The data is represented exactly in Tcl, including any embedded nulls. -Tcl .TP \fBnone\fR . diff --git a/tcl/doc/regsub.n b/tcl/doc/regsub.n index a6605d1bfca..0e0f60b69ed 100644 --- a/tcl/doc/regsub.n +++ b/tcl/doc/regsub.n @@ -1,6 +1,7 @@ '\" '\" 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. @@ -8,7 +9,7 @@ '\" RCS: @(#) $Id$ '\" .so man.macros -.TH regsub n 7.4 Tcl "Tcl Built-In Commands" +.TH regsub n 8.3 Tcl "Tcl Built-In Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -23,6 +24,8 @@ This command matches the regular expression \fIexp\fR against \fIstring\fR, and it copies \fIstring\fR to the variable whose name is given by \fIvarName\fR. +(Regular expression matching is described in the \fBre_syntax\fR +reference page.) If there is a match, then while copying \fIstring\fR to \fIvarName\fR the portion of \fIstring\fR that matched \fIexp\fR is replaced with \fIsubSpec\fR. @@ -53,11 +56,45 @@ 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 @@ -70,3 +107,4 @@ of regular expressions. .SH KEYWORDS match, pattern, regular expression, substitute + diff --git a/tcl/doc/resource.n b/tcl/doc/resource.n index 3bedadad09f..3a1748bd0e8 100644 --- a/tcl/doc/resource.n +++ b/tcl/doc/resource.n @@ -55,7 +55,7 @@ If the \fB-file\fR option is specified then the resource will be deleted from the file pointed to by \fIresourceRef\fR. Otherwise the first resource with the given \fIresourceName\fR and or \fIresourceId\fR which is found on the resource file path will be -deleted. To inspect the file path, use the \fIresource files\fB command. +deleted. To inspect the file path, use the \fIresource files\fR command. .RE .TP \fBresource files ?\fIresourceRef\fR? @@ -75,8 +75,8 @@ A Tcl list of either the resource name's or resource id's of the found resources will be returned. See the RESOURCE IDS section below for more details about what a resource id is. .TP -\fBresource open \fIfileName\fR ?\fIpermissions\fR? -Open the resource for the file \fIfileName\fR. Standard file +\fBresource open \fIfileName\fR ?\fIaccess\fR? +Open the resource for the file \fIfileName\fR. Standard file access permissions may also be specified (see the manual entry for \fBopen\fR for details). A resource reference (\fIresourceRef\fR) is returned that can be used by the other resource commands. An error can occur @@ -145,11 +145,11 @@ always searched or returned in preference to numbers. For example, the \fBresource list\fR command will return names if they exist or numbers if the name is NULL. -.SH "SEE ALSO" -open - .SH "PORTABILITY ISSUES" The resource command is only available on Macintosh. +.SH "SEE ALSO" +open + .SH KEYWORDS open, resource diff --git a/tcl/doc/safe.n b/tcl/doc/safe.n index ae6847f45c2..08f32a5a810 100644 --- a/tcl/doc/safe.n +++ b/tcl/doc/safe.n @@ -11,9 +11,8 @@ .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -Safe Base \- A mechanism for creating and manipulating safe interpreters. +Safe\ Base \- A mechanism for creating and manipulating safe interpreters. .SH SYNOPSIS -.PP \fB::safe::interpCreate\fR ?\fIslave\fR? ?\fIoptions...\fR? .sp \fB::safe::interpInit\fR \fIslave\fR ?\fIoptions...\fR? @@ -50,7 +49,7 @@ hosting application to any party. .PP The Safe Base allows a master interpreter to create safe, restricted interpreters that contain a set of predefined aliases for the \fBsource\fR, -\fBload\fR, \fBfile\fR and \fBexit\fR commands and +\fBload\fR, \fBfile\fR, \fBencoding\fR, and \fBexit\fR commands and are able to use the auto-loading and package mechanisms. .PP No knowledge of the file system structure is leaked to the @@ -246,6 +245,12 @@ the \fBfile\fR command; it allows only \fBdirname\fR, \fBjoin\fR, subcommands. For more details on what these subcommands do see the manual page for the \fBfile\fR command. .TP +\fBencoding\fR ?\fIsubCmd args...\fR? +The \fBenconding\fR alias provides access to a safe subset of the +subcommands of the \fBencoding\fR command; it disallows setting of +the system encoding, but allows all other subcommands including +\fBsystem\fR to check the current encoding. +.TP \fBexit\fR The calling interpreter is deleted and its computation is stopped, but the Tcl process in which this interpreter exists is not terminated. @@ -262,9 +267,9 @@ is to prevent. .PP The commands available in a safe interpreter, in addition to the safe set as defined in \fBinterp\fR manual page, are mediated aliases -for \fBsource\fR, \fBload\fR, \fBexit\fR, and a safe subset of \fBfile\fR. -The safe interpreter can also auto-load code and it can request that -packages be loaded. +for \fBsource\fR, \fBload\fR, \fBexit\fR, and safe subsets of +\fBfile\fR and \fBencoding\fR. The safe interpreter can also auto-load +code and it can request that packages be loaded. .PP Because some of these commands access the local file system, there is a potential for information leakage about its directory structure. diff --git a/tcl/doc/scan.n b/tcl/doc/scan.n index 6ad163d6843..55628609cdd 100644 --- a/tcl/doc/scan.n +++ b/tcl/doc/scan.n @@ -1,6 +1,7 @@ '\" '\" 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. @@ -8,48 +9,71 @@ '\" RCS: @(#) $Id$ '\" .so man.macros -.TH scan n "" Tcl "Tcl Built-In Commands" +.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 varName \fR?\fIvarName ...\fR? +\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 before any conversions have been performed. -\fIString\fR gives the input to be parsed and \fIformat\fR indicates -how to parse it, using \fB%\fR conversion specifiers as in \fBsscanf\fR. -Each \fIvarName\fR gives the name of a variable; when a field is -scanned from \fIstring\fR the result is converted back into a string -and assigned to the corresponding variable. +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 +before any conversions have been performed. \fIString\fR gives the input +to be parsed and \fIformat\fR indicates how to parse it, using \fB%\fR +conversion specifiers as in \fBsscanf\fR. Each \fIvarName\fR gives the +name of a variable; when a field is scanned from \fIstring\fR the result is +converted back into a string and assigned to the corresponding variable. +.VS 8.3 +If no \fIvarName\fR variables are specified, then \fBscan\fR works in an +inline manner, returning the data that would otherwise be stored in the +variables as a list. In the inline case, an empty string is returned when +the end of the input string is reached before any conversions have been +performed. +.VE 8.3 .SH "DETAILS ON SCANNING" .PP -\fBScan\fR operates by scanning \fIstring\fR and \fIformatString\fR together. -If the next character in \fIformatString\fR is a blank or tab then it +\fBScan\fR operates by scanning \fIstring\fR and \fIformat\fR together. +If the next character in \fIformat\fR is a blank or tab then it matches any number of white space characters in \fIstring\fR (including 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 \fIformatString\fR, it indicates +When a \fB%\fR is encountered in \fIformat\fR, it indicates the start of a conversion specifier. -A conversion specifier contains three fields after the \fB%\fR: +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 number indicating a maximum field -width; and a conversion character. +.VS 8.1 +instead of assigned to a variable; a XPG3 position specifier; a number +.VE 8.1 +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 \fIformatString\fR, it -first skips any white-space characters in \fIstring\fR. +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. +.VS 8.1 +.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. +.VE 8.1 +.PP The following conversion characters are supported: .TP 10 \fBd\fR @@ -63,6 +87,17 @@ value is stored in the variable as a decimal string. \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.1 +.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. +.VE 8.1 .TP 10 \fBc\fR A single character is read in and its binary value is stored in @@ -92,6 +127,13 @@ 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. +.VS 8.1 +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. +.VE 8.1 .TP 10 \fB[^\fIchars\fB]\fR The input field consists of any number of characters not in @@ -100,6 +142,18 @@ 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. +.VS 8.1 +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. +.VE 8.1 .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. @@ -115,9 +169,10 @@ then no variable is assigned and the next scan argument is not consumed. .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: +.VS 8.1 .IP [1] -\fB%p\fR and \fB%n\fR conversion specifiers are not currently -supported. +\fB%p\fR conversion specifier is not currently supported. +.VE 8.1 .IP [2] For \fB%c\fR conversions a single character value is converted to a decimal string, which is then assigned to the @@ -129,6 +184,12 @@ 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). +.VS 8.3 +.IP [4] +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 KEYWORDS conversion specifier, parse, scan + diff --git a/tcl/doc/seek.n b/tcl/doc/seek.n index bd87e3c75df..7c3bb818ae7 100644 --- a/tcl/doc/seek.n +++ b/tcl/doc/seek.n @@ -8,7 +8,7 @@ '\" RCS: @(#) $Id$ '\" .so man.macros -.TH seek n 7.5 Tcl "Tcl Built-In Commands" +.TH seek n 8.1 Tcl "Tcl Built-In Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -50,6 +50,12 @@ It also discards any buffered and unread input. This command returns an empty string. An error occurs if this command is applied to channels whose underlying file or device does not support seeking. +.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 KEYWORDS access position, file, seek diff --git a/tcl/doc/socket.n b/tcl/doc/socket.n index 289512fd91a..7a7486722e5 100644 --- a/tcl/doc/socket.n +++ b/tcl/doc/socket.n @@ -1,12 +1,13 @@ '\" '\" Copyright (c) 1996 Sun Microsystems, Inc. +'\" 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$ .so man.macros -.TH socket n 7.5 Tcl "Tcl Built-In Commands" +.TH socket n 8.0 Tcl "Tcl Built-In Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -100,9 +101,17 @@ event loop, for example by invoking the \fBvwait\fR command or calling the C procedure \fBTcl_DoOneEvent\fR, then no connections will be accepted. -.SH CONFIGURATION OPTIONS +.SH "CONFIGURATION OPTIONS" The \fBfconfigure\fR command can be used to query several readonly configuration options for socket channels: +.VS 8.0.5 +.TP +\fB\-error\fR +This option gets the current error status of the given socket. This +is useful when you need to determine if an asynchronous connect +operation succeeded. If there was an error, the error message is +returned. If there was no error, an empty string is returned. +.VE 8.0.5 .TP \fB\-sockname\fR This option returns a list of three elements, the address, the host name diff --git a/tcl/doc/string.n b/tcl/doc/string.n index 2b93d4c268b..2aaec95474b 100644 --- a/tcl/doc/string.n +++ b/tcl/doc/string.n @@ -8,7 +8,7 @@ '\" RCS: @(#) $Id$ '\" .so man.macros -.TH string n 7.6 Tcl "Tcl Built-In Commands" +.TH string n 8.1 Tcl "Tcl Built-In Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -21,40 +21,197 @@ string \- Manipulate strings .PP Performs one of several string operations, depending on \fIoption\fR. The legal \fIoption\fRs (which may be abbreviated) are: +.VS 8.1 .TP -\fBstring compare \fIstring1 string2\fR +\fBstring bytelength \fIstring\fR +Returns a decimal string giving the number of bytes used to represent +\fIstring\fR in memory. Because UTF\-8 uses one to three bytes to +represent Unicode characters, the byte length will not be the same as +the character length in general. The cases where a script cares about +the byte length are rare. In almost all cases, you should use the +\fBstring length\fR operation. Refer to the \fBTcl_NumUtfChars\fR +manual entry for more details on the UTF\-8 representation. +.TP +\fBstring compare\fR ?\fB\-nocase\fR? ?\fB\-length int\fR? \fIstring1 string2\fR +.VE 8.1 Perform a character-by-character comparison of strings \fIstring1\fR and -\fIstring2\fR in the same way as the C \fBstrcmp\fR procedure. Return +\fIstring2\fR. Returns \-1, 0, or 1, depending on whether \fIstring1\fR is lexicographically less than, equal to, or greater than \fIstring2\fR. +.VS 8.1 +If \fB\-length\fR is specified, then only the first \fIlength\fR characters +are used in the comparison. If \fB\-length\fR is negative, it is +ignored. If \fB\-nocase\fR is specified, then the strings are +compared in a case-insensitive manner. +.TP +\fBstring equal\fR ?\fB\-nocase\fR? ?\fB-length int\fR? \fIstring1 string2\fR +Perform a character-by-character comparison of strings +\fIstring1\fR and \fIstring2\fR. Returns 1 if \fIstring1\fR and +\fIstring2\fR are identical, or 0 when not. If \fB\-length\fR is +specified, then only the first \fIlength\fR characters are used in the +comparison. If \fB\-length\fR is negative, it is ignored. If +\fB\-nocase\fR is specified, then the strings are compared in a +case-insensitive manner. .TP -\fBstring first \fIstring1 string2\fR +\fBstring first \fIstring1 string2\fR ?\fIstartIndex\fR? +.VE 8.1 Search \fIstring2\fR for a sequence of characters that exactly match the characters in \fIstring1\fR. If found, return the index of the first character in the first such match within \fIstring2\fR. If not found, return \-1. +.VS 8.1 +If \fIstartIndex\fR is specified (in any of the forms accepted by the +\fBindex\fR method), then the search is constrained to start with the +character in \fIstring2\fR specified by the index. For example, +.RS +.CS +\fBstring first a 0a23456789abcdef 5\fR +.CE +will return \fB10\fR, but +.CS +\fBstring first a 0123456789abcdef 11\fR +.CE +will return \fB\-1\fR. +.RE +.VE 8.1 .TP \fBstring index \fIstring charIndex\fR Returns the \fIcharIndex\fR'th character of the \fIstring\fR argument. A \fIcharIndex\fR of 0 corresponds to the first -character of the string. +character of the string. +.VS 8.1 +\fIcharIndex\fR may be specified as +follows: +.RS +.IP \fIinteger\fR 10 +The char specified at this integral index +.IP \fBend\fR 10 +The last char of the string. +.IP \fBend\-\fIinteger\fR 10 +The last char of the string minus the specified integer +offset (e.g. \fBend\-1\fR would refer to the "c" in "abcd"). +.PP +.VE 8.1 If \fIcharIndex\fR is less than 0 or greater than or equal to the length of the string then an empty string is returned. +.VS 8.1 +.RE +.TP +\fBstring is \fIclass\fR ?\fB\-strict\fR? ?\fB\-failindex \fIvarname\fR? \fIstring\fR +Returns 1 if \fIstring\fR is a valid member of the specified character +class, otherwise returns 0. If \fB\-strict\fR is specified, then an +empty string returns 0, otherwise and empty string will return 1 on +any class. If \fB\-failindex\fR is specified, then if the function +returns 0, the index in the string where the class was no longer valid +will be stored in the variable named \fIvarname\fR. The \fIvarname\fR +will not be set if the function returns 1. The following character classes +are recognized (the class name can be abbreviated): +.RS +.IP \fBalnum\fR 10 +Any Unicode alphabet or digit character. +.IP \fBalpha\fR 10 +Any Unicode alphabet character. +.IP \fBascii\fR 10 +Any character with a value less than \\u0080 (those that +are in the 7\-bit ascii range). +.IP \fBboolean\fR 10 +Any of the forms allowed to \fBTcl_GetBoolean\fR. +.IP \fBcontrol\fR 10 +Any Unicode control character. +.IP \fBdigit\fR 10 +Any Unicode digit character. Note that this includes characters +outside of the [0\-9] range. +.IP \fBdouble\fR 10 +Any of the valid forms for a double in Tcl, with optional surrounding +whitespace. In case of under/overflow in the value, 0 is returned +and the \fIvarname\fR will contain \-1. +.IP \fBfalse\fR 10 +Any of the forms allowed to \fBTcl_GetBoolean\fR where the value is false. +.IP \fBgraph\fR 10 +Any Unicode printing character, except space. +.IP \fBinteger\fR 10 +Any of the valid forms for an integer in Tcl, with optional surrounding +whitespace. In case of under/overflow in the value, 0 is returned +and the \fIvarname\fR will contain \-1. +.IP \fBlower\fR 10 +Any Unicode lower case alphabet character. +.IP \fBprint\fR 10 +Any Unicode printing character, including space. +.IP \fBpunct\fR 10 +Any Unicode punctuation character. +.IP \fBspace\fR 10 +Any Unicode space character. +.IP \fBtrue\fR 10 +Any of the forms allowed to \fBTcl_GetBoolean\fR where the value is true. +.IP \fBupper\fR 10 +Any upper case alphabet character in the Unicode character set. +.IP \fBwordchar\fR 10 +Any Unicode word character. That is any alphanumeric character, +and any Unicode connector punctuation characters (e.g. underscore). +.IP \fBxdigit\fR 10 +Any hexadecimal digit character ([0\-9A\-Fa\-f]). +.PP +In the case of \fBboolean\fR, \fBtrue\fR and \fBfalse\fR, if the +function will return 0, then the \fIvarname\fR will always be set to 0, +due to the varied nature of a valid boolean value. +.RE .TP -\fBstring last \fIstring1 string2\fR +\fBstring last \fIstring1 string2\fR ?\fIstartIndex\fR? +.VE 8.1 Search \fIstring2\fR for a sequence of characters that exactly match the characters in \fIstring1\fR. If found, return the index of the first character in the last such match within \fIstring2\fR. If there is no match, then return \-1. +.VS 8.1 +If \fIstartIndex\fR is specified (in any of the forms accepted by the +\fBindex\fR method), then only the characters in \fIstring2\fR at or before the +specified \fIstartIndex\fR will be considered by the search. For example, +.RS +.CS +\fBstring last a 0a23456789abcdef 15\fR +.CE +will return \fB10\fR, but +.CS +\fBstring last a 0a23456789abcdef 9\fR +.CE +will return \fB1\fR. +.RE +.VE 8.1 .TP \fBstring length \fIstring\fR -Returns a decimal string giving the number of characters in \fIstring\fR. +Returns a decimal string giving the number of characters in +\fIstring\fR. Note that this is not necessarily the same as the +number of bytes used to store the string. +.VS 8.1 +.TP +\fBstring map\fR ?\fB\-nocase\fR? \fIcharMap string\fR +Replaces characters in \fIstring\fR based on the key-value pairs in +\fIcharMap\fR. \fIcharMap\fR is a list of \fIkey value key value\fR ... +as in the form returned by \fBarray get\fR. Each instance of a +key in the string will be replaced with its corresponding value. If +\fB\-nocase\fR is specified, then matching is done without regard to +case differences. Both \fIkey\fR and \fIvalue\fR may be multiple +characters. Replacement is done in an ordered manner, so the key appearing +first in the list will be checked first, and so on. \fIstring\fR is +only iterated over once, so earlier key replacements will have no +affect for later key matches. For example, +.RS +.CS +\fBstring map {abc 1 ab 2 a 3 1 0} 1abcaababcabababc\fR +.CE +will return the string \fB01321221\fR. +.RE .TP -\fBstring match \fIpattern\fR \fIstring\fR +\fBstring match\fR ?\fB\-nocase\fR? \fIpattern\fR \fIstring\fR +.VE 8.1 See if \fIpattern\fR matches \fIstring\fR; return 1 if it does, 0 -if it doesn't. Matching is done in a fashion similar to that -used by the C-shell. For the two strings to match, their contents +if it doesn't. +.VS 8.1 +If \fB\-nocase\fR is specified, then the pattern attempts to match +against the string in a case insensitive manner. +.VE 8.1 +For the two strings to match, their contents must be identical except that the following special sequences may appear in \fIpattern\fR: .RS @@ -68,6 +225,13 @@ Matches any character in the set given by \fIchars\fR. If a sequence of the form \fIx\fB\-\fIy\fR appears in \fIchars\fR, then any character between \fIx\fR and \fIy\fR, inclusive, will match. +.VS 8.1 +When used with \fB\-nocase\fR, the end points of the range are converted +to lower case first. Whereas {[A\-z]} matches '_' when matching +case-sensitively ('_' falls between the 'Z' and 'a'), with \fB\-nocase\fR +this is considered like {[A\-Za\-z]} (and probably what was meant in the +first place). +.VE 8.1 .IP \fB\e\fIx\fR 10 Matches the single character \fIx\fR. This provides a way of avoiding the special interpretation of the characters @@ -78,21 +242,58 @@ avoiding the special interpretation of the characters Returns a range of consecutive characters from \fIstring\fR, starting with the character whose index is \fIfirst\fR and ending with the character whose index is \fIlast\fR. An index of 0 refers to the -first character of the string. -An index of \fBend\fR (or any -abbreviation of it) refers to the last character of the string. +.VS 8.1 +first character of the string. \fIfirst\fR and \fIlast\fR may be +specified as for the \fBindex\fR method. +.VE 8.1 If \fIfirst\fR is less than zero then it is treated as if it were zero, and if \fIlast\fR is greater than or equal to the length of the string then it is treated as if it were \fBend\fR. If \fIfirst\fR is greater than \fIlast\fR then an empty string is returned. +.VS 8.1 +.TP +\fBstring repeat \fIstring count\fR +Returns \fIstring\fR repeated \fIcount\fR number of times. +.TP +\fBstring replace \fIstring first last\fR ?\fInewstring\fR? +Removes a range of consecutive characters from \fIstring\fR, starting +with the character whose index is \fIfirst\fR and ending with the +character whose index is \fIlast\fR. An index of 0 refers to the +first character of the string. \fIFirst\fR and \fIlast\fR may be +specified as for the \fBindex\fR method. If \fInewstring\fR is +specified, then it is placed in the removed character range. +If \fIfirst\fR is less than zero then it is treated as if it were zero, and +if \fIlast\fR is greater than or equal to the length of the string then +it is treated as if it were \fBend\fR. If \fIfirst\fR is greater than +\fIlast\fR or the length of the initial string, or \fIlast\fR is less +than 0, then the initial string is returned untouched. +.TP +\fBstring tolower \fIstring\fR ?\fIfirst\fR? ?\fIlast\fR? +Returns a value equal to \fIstring\fR except that all upper (or title) case +letters have been converted to lower case. If \fIfirst\fR is specified, it +refers to the first char index in the string to start modifying. If +\fIlast\fR is specified, it refers to the char index in the string to stop +at (inclusive). \fIfirst\fR and \fIlast\fR may be +specified as for the \fBindex\fR method. .TP -\fBstring tolower \fIstring\fR -Returns a value equal to \fIstring\fR except that all upper case -letters have been converted to lower case. +\fBstring totitle \fIstring\fR ?\fIfirst\fR? ?\fIlast\fR? +Returns a value equal to \fIstring\fR except that the first character +in \fIstring\fR is converted to its Unicode title case variant (or upper +case if there is no title case variant) and the rest of the string is +converted to lower case. If \fIfirst\fR is specified, it +refers to the first char index in the string to start modifying. If +\fIlast\fR is specified, it refers to the char index in the string to stop +at (inclusive). \fIfirst\fR and \fIlast\fR may be +specified as for the \fBindex\fR method. .TP -\fBstring toupper \fIstring\fR -Returns a value equal to \fIstring\fR except that all lower case -letters have been converted to upper case. +\fBstring toupper \fIstring\fR ?\fIfirst\fR? ?\fIlast\fR? +Returns a value equal to \fIstring\fR except that all lower (or title) case +letters have been converted to upper case. If \fIfirst\fR is specified, it +refers to the first char index in the string to start modifying. If +\fIlast\fR is specified, it refers to the char index in the string to stop +at (inclusive). \fIfirst\fR and \fIlast\fR may be specified as for the +\fBindex\fR method. +.VE 8.1 .TP \fBstring trim \fIstring\fR ?\fIchars\fR? Returns a value equal to \fIstring\fR except that any leading @@ -114,18 +315,24 @@ trailing characters from the set given by \fIchars\fR are removed. If \fIchars\fR is not specified then white space is removed (spaces, tabs, newlines, and carriage returns). +.VS 8.1 +.TP +\fBstring wordend \fIstring charIndex\fR +Returns the index of the character just after the last one in the word +containing 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. .TP -\fBstring wordend \fIstring index\fR -Returns the index of the character just after the last one in the -word containing character \fIindex\fR of \fIstring\fR. -A word is considered to be any contiguous range of alphanumeric -or underscore characters, or any single character other than these. -.TP -\fBstring wordstart \fIstring index\fR -Returns the index of the first character in the -word containing character \fIindex\fR of \fIstring\fR. -A word is considered to be any contiguous range of alphanumeric -or underscore characters, or any single character other than these. +\fBstring wordstart \fIstring charIndex\fR +Returns the index of the first character in the word containing +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 KEYWORDS -case conversion, compare, index, match, pattern, string, word +case conversion, compare, index, match, pattern, string, word, equal, ctype diff --git a/tcl/doc/switch.n b/tcl/doc/switch.n index c0aecfa369f..f71ed5f0cd4 100644 --- a/tcl/doc/switch.n +++ b/tcl/doc/switch.n @@ -47,7 +47,7 @@ When matching \fIstring\fR to the patterns, use glob-style matching \fB\-regexp\fR When matching \fIstring\fR to the patterns, use regular expression matching -(i.e. the same as implemented by the \fBregexp\fR command). +(as described in the \fBre_syntax\fR reference page). .TP 10 \fB\-\|\-\fR Marks the end of options. The argument following this one will @@ -75,6 +75,10 @@ then the body after that is used, and so on). This feature makes it possible to share a single \fIbody\fR among several patterns. .PP +Beware of how you place comments in \fBswitch\fR commands. Comments +should only be placed \fBinside\fR the execution body of one of the +patterns, and not intermingled with the patterns. +.PP Below are some examples of \fBswitch\fR commands: .CS \fBswitch\0abc\0a\0\-\0b\0{format 1}\0abc\0{format 2}\0default\0{format 3}\fR @@ -94,7 +98,10 @@ will return \fB1\fR, and a \- b - {format 1} + { + # Correct Comment Placement + format 1 + } a* {format 2} default diff --git a/tcl/doc/tclsh.1 b/tcl/doc/tclsh.1 index a429d82e8dc..3ecfa211ab4 100644 --- a/tcl/doc/tclsh.1 +++ b/tcl/doc/tclsh.1 @@ -26,7 +26,8 @@ Tcl commands from standard input and printing command results and error messages to standard output. It runs until the \fBexit\fR command is invoked or until it reaches end-of-file on its standard input. -If there exists a file \fB.tclshrc\fR in the home directory of +If there exists a file \fB.tclshrc\fR (or \fBtclshrc.tcl\fR on +the Windows platforms) in the home directory of the user, \fBtclsh\fR evaluates the file as a Tcl script just before reading the first command from standard input. diff --git a/tcl/doc/tcltest.n b/tcl/doc/tcltest.n new file mode 100644 index 00000000000..1a515653541 --- /dev/null +++ b/tcl/doc/tcltest.n @@ -0,0 +1,759 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California +'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. +'\" Copyright (c) 1998-1999 Scriptics Corporation +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id$ +'\" +.so man.macros +.TH "Tcltest" n 8.2 Tcl "Tcl Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +Tcltest \- Test harness support code and utilities +.SH SYNOPSIS +\fBpackage require tcltest ?1.0?\fP +.sp +\fB::tcltest::test \fIname desc ?constraint? script expectedAnswer\fR +.sp +\fB::tcltest::cleanupTests \fI?runningMultipleTests?\fR +.sp +\fB::tcltest::getMatchingTestFiles\fR +.sp +\fB::tcltest::loadTestedCommands\fR +.sp +\fB::tcltest::makeFile \fIcontents name\fR +.sp +\fB::tcltest::removeFile \fIname\fR +.sp +\fB::tcltest::makeDirectory \fIname\fR +.sp +\fB::tcltest::removeDirectory \fIname\fR +.sp +\fB::tcltest::viewFile \fIname\fR +.sp +\fB::tcltest::normalizeMsg \fImsg\fR +.sp +\fB::tcltest::bytestring \fIstring\fR +.sp +\fB::tcltest::saveState\fR +.sp +\fB::tcltest::restoreState\fR +.sp +\fB::tcltest::threadReap\fR +.BE +.SH DESCRIPTION +.PP +The \fBtcltest\fR package provides the user with utility tools for +writing and running tests in the Tcl test suite. It can also be used +to create a customized test harness for an extension. +.PP +The Tcl test suite consists of multiple .test files, each of which +contains multiple test cases. Each test case consists of a call to +the test command, which specifies the name of test, a short +description, any constraints that apply to the test case, the script +to be run, and expected results. See the sections \fI"Tests,"\fR +\fI"Test Constraints,"\fR and \fI"Test Files and How to Run Them"\fR +for more details. +.PP +It is also possible to add to this test harness to create your own +customized test harness implementation. For more defails, see the +section \fI"How to Customize the Test Harness"\fR. +.PP +This approach to testing was designed and initially implemented by +Mary Ann May-Pumphrey of Sun Microsystems in the early 1990's. Many +thanks to her for donating her work back to the public Tcl release. +.SH COMMANDS +.TP +\fB::tcltest::test\fP \fIname desc ?constraints? script expectedAnswer\fR +The \fB::tcltest::test\fR command runs\fIscript\fR and compares +its result to \fIexpectedAnswer\fR. It prints an error message if the two do +not match. If \fB::tcltest::verbose\fR contains "p" or "s", it also prints +out a message if the test passed or was skipped. The test will be +skipped if it doesn't match the \fB::tcltest::match\fR variable, if it +matches an element in \fB::tcltest::skip\fR, or if one of the elements +of \fIconstraint\fR turns out not to be true. The +\fB::tcltest::test\fR command has no defined return values. See the +\fI"Writing a new test"\fR section for more details on this command. +.TP +\fB::tcltest::cleanupTests\fP \fI?runningMultipleTests?\fR +This command should be called at the end of a test file. It prints +statistics about the tests run and removes files that were created by +\fB::tcltest::makeDirectory\fR and \fB::tcltest::makeFile\fR. Names +of files and directories created outside of +\fB::tcltest::makeFile\fR and \fB::tcltest::makeDirectory\fR and +never deleted are printed to \fB::tcltest::outputChannel\fR. This command +also restores the original shell environment, as described by the ::env +array. \fIcalledFromAll\fR should be specified when +\fB::tcltest::cleanupTests\fR is called from an "all.tcl" file. Tcl files +files are generally used to run multiple tests. For more details on how to +run multiple tests, please see the section \fI"Running test files"\fR. +This proc has no defined return value. +.TP +\fB::tcltest::getMatchingTestFiles\fP +This command is used when you want to run multiple test files. It returns +the list of tests that should be sourced in an 'all.tcl' file. See the +section \fI"Running test files"\fR for more information. +.TP +\fB::tcltest::loadTestedCommands\fP +This command uses the script specified via the \fI-load\fR or +\fI-loadfile\fR to load the commands checked by the test suite. +Allowed to be empty, as the tested commands could have been compiled +into the interpreter running the test suite. +.TP +\fB::tcltest::makeFile\fP \fIcontents name\fR +Create a file that will be automatically be removed by +\fB::tcltest::cleanupTests\fR at the end of a test file. +This proc has no defined return value. +.TP +\fB::tcltest::removeFile\fP \fIname\fR +Force the file referenced by \fIname\fR to be removed. This file name +should be relative to \fI::tcltest::temporaryDirectory\fR. This proc has no +defined return values. +.TP +\fB::tcltest::makeDirectory\fP \fIname\fR +Create a directory named \fIname\fR that will automatically be removed +by \fB::tcltest::cleanupTests\fR at the end of a test file. This proc +has no defined return value. +.TP +\fB::tcltest::removeDirectory\fP \fIname\fR +Force the directory referenced by \fIname\fR to be removed. This proc +has no defined return value. +.TP +\fB::tcltest::viewFile\fP \fIfile\fR +Returns the contents of \fIfile\fR. +.TP +\fB::tcltest::normalizeMsg\fP \fImsg\fR +Remove extra newlines from \fImsg\fR. +.TP +\fB::tcltest::bytestring\fP \fIstring\fR +Construct a string that consists of the requested sequence of bytes, +as opposed to a string of properly formed UTF-8 characters using the +value supplied in \fIstring\fR. This allows the tester to create +denormalized or improperly formed strings to pass to C procedures that +are supposed to accept strings with embedded NULL types and confirm +that a string result has a certain pattern of bytes. +.TP +\fB::tcltest::saveState\fP +\fB::tcltest::restoreState\fP +Save and restore the procedure and global variable names. +A test file might contain calls to \fB::tcltest::saveState\fR and +\fB::tcltest:restoreState\fR if it creates or deletes global variables +or procs. +.TP +\fB::tcltest::threadReap\fP +\fB::tcltest::threadReap\fR only works if \fItestthread\fR is +defined, generally by compiling tcltest. If \fItestthread\fR is +defined, \fB::tcltest::threadReap\fR kills all threads except for the +main thread. It gets the ID of the main thread by calling +\fItestthread names\fR during initialization. This value is stored in +\fI::tcltest::mainThread\fR. \fB::tcltest::threadReap\fR returns the +number of existing threads at completion. +.SH TESTS +The \fBtest\fR procedure runs a test script and prints an error +message if the script's result does not match the expected result. +The following is the spec for the \fBtest\fR command: +.DS +test ??