summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorKevin B Kenny <kennykb@acm.org>2007-04-20 06:10:56 (GMT)
committerKevin B Kenny <kennykb@acm.org>2007-04-20 06:10:56 (GMT)
commit2e1d6b21db75a43a44e02272dce97955e9aecde1 (patch)
tree103cdcd515ae38406063be74a3bb942be25c9ebd
parent19d1741894fc2c56ad61073c9004a90afabf2e56 (diff)
downloadtcl-2e1d6b21db75a43a44e02272dce97955e9aecde1.zip
tcl-2e1d6b21db75a43a44e02272dce97955e9aecde1.tar.gz
tcl-2e1d6b21db75a43a44e02272dce97955e9aecde1.tar.bz2
Replaced commas in varargs with string concatenation where possible [Patch 1515234]
-rw-r--r--ChangeLog18
-rw-r--r--generic/tclIOUtil.c6
-rw-r--r--generic/tclNamesp.c4
-rw-r--r--generic/tclObj.c8
-rw-r--r--generic/tclPathObj.c8
-rw-r--r--generic/tclPipe.c6
-rw-r--r--generic/tclPkg.c8
-rw-r--r--generic/tclResult.c6
-rw-r--r--generic/tclTest.c62
-rw-r--r--generic/tclTestObj.c4
-rw-r--r--generic/tclVar.c6
-rw-r--r--unix/tclUnixChan.c8
-rw-r--r--unix/tclUnixTest.c4
-rw-r--r--win/tclWinLoad.c12
-rw-r--r--win/tclWinSerial.c10
15 files changed, 92 insertions, 78 deletions
diff --git a/ChangeLog b/ChangeLog
index 06099a1..599870c 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -35,9 +35,23 @@
* generic/tclCmdMZ.c:
* generic/tclFCmd.c:
* generic/tclFileName.c:
+ * generic/tclInterp.c:
* generic/tclIO.c:
- * generic/tclInterp.c: Replaced commas in varargs with string
- concatenation where possible. [Patch 1515234]
+ * generic/tclIOUtil.c:
+ * generic/tclNamesp.c:
+ * generic/tclObj.c:
+ * generic/tclPathObj.c:
+ * generic/tclPipe.c:
+ * generic/tclPkg.c:
+ * generic/tclResult.c:
+ * generic/tclTest.c:
+ * generic/tclTestObj.c:
+ * generic/tclVar.c:
+ * unix/tclUnixChan.c:
+ * unix/tclUnixTest.c:
+ * win/tclWinLoad.c:
+ * win/tclWinSerial.c: Replaced commas in varargs with string
+ concatenation where possible. [Patch 1515234]
2007-04-19 Donal K. Fellows <donal.k.fellows@manchester.ac.uk>
diff --git a/generic/tclIOUtil.c b/generic/tclIOUtil.c
index 8e3a3f2..a2b0555 100644
--- a/generic/tclIOUtil.c
+++ b/generic/tclIOUtil.c
@@ -17,7 +17,7 @@
* See the file "license.terms" for information on usage and redistribution of
* this file, and for a DISCLAIMER OF ALL WARRANTIES.
*
- * RCS: @(#) $Id: tclIOUtil.c,v 1.143 2007/04/10 14:47:15 dkf Exp $
+ * RCS: @(#) $Id: tclIOUtil.c,v 1.144 2007/04/20 06:10:57 kennykb Exp $
*/
#include "tclInt.h"
@@ -1697,7 +1697,7 @@ TclGetOpenModeEx(
if (!gotRW) {
if (interp != NULL) {
- Tcl_AppendResult(interp, "access mode must include either",
+ Tcl_AppendResult(interp, "access mode must include either"
" RDONLY, WRONLY, or RDWR", NULL);
}
return -1;
@@ -2243,7 +2243,7 @@ Tcl_FSOpenFileChannel(
if (seekFlag && Tcl_Seek(retVal, (Tcl_WideInt)0,
SEEK_END) < (Tcl_WideInt)0) {
if (interp != NULL) {
- Tcl_AppendResult(interp, "could not seek to end ",
+ Tcl_AppendResult(interp, "could not seek to end "
"of file while opening \"", Tcl_GetString(pathPtr),
"\": ", Tcl_PosixError(interp), NULL);
}
diff --git a/generic/tclNamesp.c b/generic/tclNamesp.c
index 676f164..b4c7a4a 100644
--- a/generic/tclNamesp.c
+++ b/generic/tclNamesp.c
@@ -22,7 +22,7 @@
* See the file "license.terms" for information on usage and redistribution of
* this file, and for a DISCLAIMER OF ALL WARRANTIES.
*
- * RCS: @(#) $Id: tclNamesp.c,v 1.131 2007/04/10 14:47:16 dkf Exp $
+ * RCS: @(#) $Id: tclNamesp.c,v 1.132 2007/04/20 06:10:58 kennykb Exp $
*/
#include "tclInt.h"
@@ -771,7 +771,7 @@ Tcl_CreateNamespace(
simpleName = "";
} else if (*name == '\0') {
Tcl_ResetResult(interp);
- Tcl_AppendResult(interp, "can't create namespace \"\": ",
+ Tcl_AppendResult(interp, "can't create namespace \"\": "
"only global namespace can have empty name", NULL);
return NULL;
} else {
diff --git a/generic/tclObj.c b/generic/tclObj.c
index e478d6b..05f3990 100644
--- a/generic/tclObj.c
+++ b/generic/tclObj.c
@@ -12,7 +12,7 @@
* See the file "license.terms" for information on usage and redistribution of
* this file, and for a DISCLAIMER OF ALL WARRANTIES.
*
- * RCS: @(#) $Id: tclObj.c,v 1.120 2007/04/10 22:04:31 dkf Exp $
+ * RCS: @(#) $Id: tclObj.c,v 1.121 2007/04/20 06:10:58 kennykb Exp $
*/
#include "tclInt.h"
@@ -3075,7 +3075,7 @@ Tcl_DbIncrRefCount(
hPtr = Tcl_FindHashEntry(tablePtr, (char *) objPtr);
if (!hPtr) {
Tcl_Panic("%s%s",
- "Trying to incr ref count of ",
+ "Trying to incr ref count of "
"Tcl_Obj allocated in another thread");
}
}
@@ -3140,7 +3140,7 @@ Tcl_DbDecrRefCount(
hPtr = Tcl_FindHashEntry(tablePtr, (char *) objPtr);
if (!hPtr) {
Tcl_Panic("%s%s",
- "Trying to decr ref count of ",
+ "Trying to decr ref count of "
"Tcl_Obj allocated in another thread");
}
@@ -3210,7 +3210,7 @@ Tcl_DbIsShared(
hPtr = Tcl_FindHashEntry(tablePtr, (char *) objPtr);
if (!hPtr) {
Tcl_Panic("%s%s",
- "Trying to check shared status of",
+ "Trying to check shared status of"
"Tcl_Obj allocated in another thread");
}
}
diff --git a/generic/tclPathObj.c b/generic/tclPathObj.c
index 174ac22..8744da8 100644
--- a/generic/tclPathObj.c
+++ b/generic/tclPathObj.c
@@ -10,7 +10,7 @@
* See the file "license.terms" for information on usage and redistribution of
* this file, and for a DISCLAIMER OF ALL WARRANTIES.
*
- * RCS: @(#) $Id: tclPathObj.c,v 1.61 2007/04/20 02:23:31 kennykb Exp $
+ * RCS: @(#) $Id: tclPathObj.c,v 1.62 2007/04/20 06:10:58 kennykb Exp $
*/
#include "tclInt.h"
@@ -1327,7 +1327,7 @@ TclFSMakePathRelative(
if (pathPtr->typePtr->updateStringProc == NULL) {
if (interp != NULL) {
Tcl_ResetResult(interp);
- Tcl_AppendResult(interp, "can't find object",
+ Tcl_AppendResult(interp, "can't find object"
"string representation", (char *) NULL);
}
return NULL;
@@ -1449,7 +1449,7 @@ TclFSMakePathFromNormalized(
if (pathPtr->typePtr->updateStringProc == NULL) {
if (interp != NULL) {
Tcl_ResetResult(interp);
- Tcl_AppendResult(interp, "can't find object",
+ Tcl_AppendResult(interp, "can't find object"
"string representation", (char *) NULL);
}
return TCL_ERROR;
@@ -2318,7 +2318,7 @@ SetFsPathFromAny(
if (dir == NULL) {
if (interp) {
Tcl_ResetResult(interp);
- Tcl_AppendResult(interp, "couldn't find HOME environment ",
+ Tcl_AppendResult(interp, "couldn't find HOME environment "
"variable to expand path", (char *) NULL);
}
return TCL_ERROR;
diff --git a/generic/tclPipe.c b/generic/tclPipe.c
index bd66ca6..561d390 100644
--- a/generic/tclPipe.c
+++ b/generic/tclPipe.c
@@ -9,7 +9,7 @@
* See the file "license.terms" for information on usage and redistribution of
* this file, and for a DISCLAIMER OF ALL WARRANTIES.
*
- * RCS: @(#) $Id: tclPipe.c,v 1.18 2006/03/16 00:38:50 andreas_kupries Exp $
+ * RCS: @(#) $Id: tclPipe.c,v 1.19 2007/04/20 06:10:58 kennykb Exp $
*/
#include "tclInt.h"
@@ -1055,12 +1055,12 @@ Tcl_OpenCommandChannel(
if (flags & TCL_ENFORCE_MODE) {
if ((flags & TCL_STDOUT) && (outPipe == NULL)) {
- Tcl_AppendResult(interp, "can't read output from command:",
+ Tcl_AppendResult(interp, "can't read output from command:"
" standard output was redirected", NULL);
goto error;
}
if ((flags & TCL_STDIN) && (inPipe == NULL)) {
- Tcl_AppendResult(interp, "can't write input to command:",
+ Tcl_AppendResult(interp, "can't write input to command:"
" standard input was redirected", NULL);
goto error;
}
diff --git a/generic/tclPkg.c b/generic/tclPkg.c
index 5426bc7..dff6090 100644
--- a/generic/tclPkg.c
+++ b/generic/tclPkg.c
@@ -10,7 +10,7 @@
* See the file "license.terms" for information on usage and redistribution of
* this file, and for a DISCLAIMER OF ALL WARRANTIES.
*
- * RCS: @(#) $Id: tclPkg.c,v 1.26 2006/12/05 15:36:12 dgp Exp $
+ * RCS: @(#) $Id: tclPkg.c,v 1.27 2007/04/20 06:10:58 kennykb Exp $
*
* TIP #268.
* Heavily rewritten to handle the extend version numbers, and extended
@@ -286,7 +286,7 @@ Tcl_PkgRequireEx(
tclEmptyStringRep = &tclEmptyString;
Tcl_AppendResult(interp, "Cannot load package \"", name,
- "\" in standalone executable: This package is not ",
+ "\" in standalone executable: This package is not "
"compiled with stub support", NULL);
return NULL;
}
@@ -380,7 +380,7 @@ Tcl_PkgRequireProc(
*/
if (pkgPtr->clientData != NULL) {
- Tcl_AppendResult(interp, "circular package dependency: ",
+ Tcl_AppendResult(interp, "circular package dependency: "
"attempt to provide ", name, " ",
(char *) pkgPtr->clientData, " requires ", name, NULL);
AddRequirementsToResult(interp, reqc, reqv);
@@ -532,7 +532,7 @@ Tcl_PkgRequireProc(
Tcl_Obj *codePtr = Tcl_NewIntObj(code);
Tcl_ResetResult(interp);
Tcl_AppendResult(interp, "attempt to provide package ",
- name, " ", versionToProvide, " failed: ",
+ name, " ", versionToProvide, " failed: "
"bad return code: ", TclGetString(codePtr), NULL);
TclDecrRefCount(codePtr);
code = TCL_ERROR;
diff --git a/generic/tclResult.c b/generic/tclResult.c
index d60f06f..9512989 100644
--- a/generic/tclResult.c
+++ b/generic/tclResult.c
@@ -8,7 +8,7 @@
* See the file "license.terms" for information on usage and redistribution of
* this file, and for a DISCLAIMER OF ALL WARRANTIES.
*
- * RCS: @(#) $Id: tclResult.c,v 1.35 2007/04/10 22:16:42 dkf Exp $
+ * RCS: @(#) $Id: tclResult.c,v 1.36 2007/04/20 06:10:58 kennykb Exp $
*/
#include "tclInt.h"
@@ -1341,7 +1341,7 @@ TclMergeReturnOptions(
Tcl_ResetResult(interp);
Tcl_AppendResult(interp, "bad completion code \"",
TclGetString(valuePtr),
- "\": must be ok, error, return, break, ",
+ "\": must be ok, error, return, break, "
"continue, or an integer", NULL);
goto error;
}
@@ -1361,7 +1361,7 @@ TclMergeReturnOptions(
*/
Tcl_ResetResult(interp);
- Tcl_AppendResult(interp, "bad -level value: ",
+ Tcl_AppendResult(interp, "bad -level value: "
"expected non-negative integer but got \"",
TclGetString(valuePtr), "\"", NULL);
goto error;
diff --git a/generic/tclTest.c b/generic/tclTest.c
index 43deff7..bbfff88 100644
--- a/generic/tclTest.c
+++ b/generic/tclTest.c
@@ -14,7 +14,7 @@
* See the file "license.terms" for information on usage and redistribution of
* this file, and for a DISCLAIMER OF ALL WARRANTIES.
*
- * RCS: @(#) $Id: tclTest.c,v 1.107 2007/04/16 13:36:35 dkf Exp $
+ * RCS: @(#) $Id: tclTest.c,v 1.108 2007/04/20 06:10:59 kennykb Exp $
*/
#define TCL_TEST
@@ -1685,7 +1685,7 @@ TestdstringCmd(
Tcl_DStringStartSublist(&dstring);
} else {
Tcl_AppendResult(interp, "bad option \"", argv[1],
- "\": must be append, element, end, free, get, length, ",
+ "\": must be append, element, end, free, get, length, "
"result, trunc, or start", NULL);
return TCL_ERROR;
}
@@ -2638,7 +2638,7 @@ TestlinkCmd(
if (argc < 2) {
Tcl_AppendResult(interp, "wrong # args: should be \"", argv[0],
- " option ?arg arg arg arg arg arg arg arg arg arg arg arg",
+ " option ?arg arg arg arg arg arg arg arg arg arg arg arg"
" arg arg?\"", NULL);
return TCL_ERROR;
}
@@ -2646,7 +2646,7 @@ TestlinkCmd(
if (argc != 16) {
Tcl_AppendResult(interp, "wrong # args: should be \"",
argv[0], " ", argv[1],
- " intRO realRO boolRO stringRO wideRO charRO ucharRO shortRO",
+ " intRO realRO boolRO stringRO wideRO charRO ucharRO shortRO"
" ushortRO uintRO longRO ulongRO floatRO uwideRO\"", NULL);
return TCL_ERROR;
}
@@ -2837,8 +2837,8 @@ TestlinkCmd(
if (argc != 16) {
Tcl_AppendResult(interp, "wrong # args: should be \"",
argv[0], " ", argv[1],
- " intValue realValue boolValue stringValue wideValue",
- " charValue ucharValue shortValue ushortValue uintValue",
+ " intValue realValue boolValue stringValue wideValue"
+ " charValue ucharValue shortValue ushortValue uintValue"
" longValue ulongValue floatValue uwideValue\"", NULL);
return TCL_ERROR;
}
@@ -2941,8 +2941,8 @@ TestlinkCmd(
if (argc != 16) {
Tcl_AppendResult(interp, "wrong # args: should be \"",
argv[0], " ", argv[1],
- " intValue realValue boolValue stringValue wideValue",
- " charValue ucharValue shortValue ushortValue uintValue",
+ " intValue realValue boolValue stringValue wideValue"
+ " charValue ucharValue shortValue ushortValue uintValue"
" longValue ulongValue floatValue uwideValue\"", NULL);
return TCL_ERROR;
}
@@ -4042,7 +4042,7 @@ TestsetplatformCmd(
} else if (strncmp(argv[1], "windows", length) == 0) {
*platform = TCL_PLATFORM_WINDOWS;
} else {
- Tcl_AppendResult(interp, "unsupported platform: should be one of ",
+ Tcl_AppendResult(interp, "unsupported platform: should be one of "
"unix, or windows", NULL);
return TCL_ERROR;
}
@@ -4973,16 +4973,16 @@ TeststatprocCmd(
} else if (strcmp(argv[2], "TestStatProc3") == 0) {
proc = TestStatProc3;
} else {
- Tcl_AppendResult(interp, "bad arg \"", argv[1], "\": ",
- "must be TclpStat, ",
+ Tcl_AppendResult(interp, "bad arg \"", argv[1], "\": "
+ "must be TclpStat, "
"TestStatProc1, TestStatProc2, or TestStatProc3", NULL);
return TCL_ERROR;
}
if (strcmp(argv[1], "insert") == 0) {
if (proc == PretendTclpStat) {
- Tcl_AppendResult(interp, "bad arg \"", argv[1], "\": ",
- "must be ",
+ Tcl_AppendResult(interp, "bad arg \"", argv[1], "\": "
+ "must be "
"TestStatProc1, TestStatProc2, or TestStatProc3", NULL);
return TCL_ERROR;
}
@@ -4990,13 +4990,13 @@ TeststatprocCmd(
} else if (strcmp(argv[1], "delete") == 0) {
retVal = TclStatDeleteProc(proc);
} else {
- Tcl_AppendResult(interp, "bad option \"", argv[1], "\": ",
+ Tcl_AppendResult(interp, "bad option \"", argv[1], "\": "
"must be insert or delete", NULL);
return TCL_ERROR;
}
if (retVal == TCL_ERROR) {
- Tcl_AppendResult(interp, "\"", argv[2], "\": ",
+ Tcl_AppendResult(interp, "\"", argv[2], "\": "
"could not be ", argv[1], "ed", NULL);
}
@@ -5283,16 +5283,16 @@ TestaccessprocCmd(
} else if (strcmp(argv[2], "TestAccessProc3") == 0) {
proc = TestAccessProc3;
} else {
- Tcl_AppendResult(interp, "bad arg \"", argv[1], "\": ",
- "must be TclpAccess, ",
+ Tcl_AppendResult(interp, "bad arg \"", argv[1], "\": "
+ "must be TclpAccess, "
"TestAccessProc1, TestAccessProc2, or TestAccessProc3", NULL);
return TCL_ERROR;
}
if (strcmp(argv[1], "insert") == 0) {
if (proc == PretendTclpAccess) {
- Tcl_AppendResult(interp, "bad arg \"", argv[1], "\": must be ",
- "TestAccessProc1, TestAccessProc2, or TestAccessProc3",
+ Tcl_AppendResult(interp, "bad arg \"", argv[1], "\": must be "
+ "TestAccessProc1, TestAccessProc2, or TestAccessProc3"
NULL);
return TCL_ERROR;
}
@@ -5300,13 +5300,13 @@ TestaccessprocCmd(
} else if (strcmp(argv[1], "delete") == 0) {
retVal = TclAccessDeleteProc(proc);
} else {
- Tcl_AppendResult(interp, "bad option \"", argv[1], "\": ",
+ Tcl_AppendResult(interp, "bad option \"", argv[1], "\": "
"must be insert or delete", NULL);
return TCL_ERROR;
}
if (retVal == TCL_ERROR) {
- Tcl_AppendResult(interp, "\"", argv[2], "\": ",
+ Tcl_AppendResult(interp, "\"", argv[2], "\": "
"could not be ", argv[1], "ed", NULL);
}
@@ -5393,18 +5393,18 @@ TestopenfilechannelprocCmd(
} else if (strcmp(argv[2], "TestOpenFileChannelProc3") == 0) {
proc = TestOpenFileChannelProc3;
} else {
- Tcl_AppendResult(interp, "bad arg \"", argv[1], "\": ",
- "must be TclpOpenFileChannel, ",
- "TestOpenFileChannelProc1, TestOpenFileChannelProc2, or ",
+ Tcl_AppendResult(interp, "bad arg \"", argv[1], "\": "
+ "must be TclpOpenFileChannel, "
+ "TestOpenFileChannelProc1, TestOpenFileChannelProc2, or "
"TestOpenFileChannelProc3", NULL);
return TCL_ERROR;
}
if (strcmp(argv[1], "insert") == 0) {
if (proc == PretendTclpOpenFileChannel) {
- Tcl_AppendResult(interp, "bad arg \"", argv[1], "\": ",
- "must be ",
- "TestOpenFileChannelProc1, TestOpenFileChannelProc2, or ",
+ Tcl_AppendResult(interp, "bad arg \"", argv[1], "\": "
+ "must be "
+ "TestOpenFileChannelProc1, TestOpenFileChannelProc2, or "
"TestOpenFileChannelProc3", NULL);
return TCL_ERROR;
}
@@ -5412,13 +5412,13 @@ TestopenfilechannelprocCmd(
} else if (strcmp(argv[1], "delete") == 0) {
retVal = TclOpenFileChannelDeleteProc(proc);
} else {
- Tcl_AppendResult(interp, "bad option \"", argv[1], "\": ",
+ Tcl_AppendResult(interp, "bad option \"", argv[1], "\": "
"must be insert or delete", NULL);
return TCL_ERROR;
}
if (retVal == TCL_ERROR) {
- Tcl_AppendResult(interp, "\"", argv[2], "\": ",
+ Tcl_AppendResult(interp, "\"", argv[2], "\": "
"could not be ", argv[1], "ed", NULL);
}
@@ -6006,7 +6006,7 @@ TestChannelCmd(
return Tcl_UnstackChannel(interp, chan);
}
- Tcl_AppendResult(interp, "bad option \"", cmdName, "\": should be ",
+ Tcl_AppendResult(interp, "bad option \"", cmdName, "\": should be "
"cut, clearchannelhandlers, info, isshared, mode, open, "
"readable, splice, writable, transform, unstack", NULL);
return TCL_ERROR;
@@ -6221,7 +6221,7 @@ TestChannelEventCmd(
TclChannelEventScriptInvoker, (ClientData) esPtr);
return TCL_OK;
}
- Tcl_AppendResult(interp, "bad command ", cmd, ", must be one of ",
+ Tcl_AppendResult(interp, "bad command ", cmd, ", must be one of "
"add, delete, list, set, or removeall", NULL);
return TCL_ERROR;
}
diff --git a/generic/tclTestObj.c b/generic/tclTestObj.c
index a7d51fd..0553005 100644
--- a/generic/tclTestObj.c
+++ b/generic/tclTestObj.c
@@ -13,7 +13,7 @@
* See the file "license.terms" for information on usage and redistribution of
* this file, and for a DISCLAIMER OF ALL WARRANTIES.
*
- * RCS: @(#) $Id: tclTestObj.c,v 1.18 2007/04/16 13:36:35 dkf Exp $
+ * RCS: @(#) $Id: tclTestObj.c,v 1.19 2007/04/20 06:10:59 kennykb Exp $
*/
#include "tclInt.h"
@@ -1025,7 +1025,7 @@ TestobjCmd(
} else {
Tcl_AppendStringsToObj(Tcl_GetObjResult(interp),
"bad option \"", Tcl_GetString(objv[1]),
- "\": must be assign, convert, duplicate, freeallvars, ",
+ "\": must be assign, convert, duplicate, freeallvars, "
"newobj, objcount, objtype, refcount, type, or types", NULL);
return TCL_ERROR;
}
diff --git a/generic/tclVar.c b/generic/tclVar.c
index c723e84..1582c26 100644
--- a/generic/tclVar.c
+++ b/generic/tclVar.c
@@ -15,7 +15,7 @@
* See the file "license.terms" for information on usage and redistribution of
* this file, and for a DISCLAIMER OF ALL WARRANTIES.
*
- * RCS: @(#) $Id: tclVar.c,v 1.129 2007/04/03 01:34:39 msofer Exp $
+ * RCS: @(#) $Id: tclVar.c,v 1.130 2007/04/20 06:10:59 kennykb Exp $
*/
#include "tclInt.h"
@@ -3249,7 +3249,7 @@ ObjMakeUpvar(
|| !HasLocalVars(varFramePtr)
|| (strstr(myName, "::") != NULL))) {
Tcl_AppendResult((Tcl_Interp *) iPtr, "bad variable name \"",
- myName, "\": upvar won't create namespace variable that ",
+ myName, "\": upvar won't create namespace variable that "
"refers to procedure variable", NULL);
return TCL_ERROR;
}
@@ -3319,7 +3319,7 @@ TclPtrMakeUpvar(
*/
Tcl_AppendResult((Tcl_Interp *) iPtr, "bad variable name \"",
- myName, "\": upvar won't create a scalar variable ",
+ myName, "\": upvar won't create a scalar variable "
"that looks like an array element", NULL);
return TCL_ERROR;
}
diff --git a/unix/tclUnixChan.c b/unix/tclUnixChan.c
index 12ddaad..904a991 100644
--- a/unix/tclUnixChan.c
+++ b/unix/tclUnixChan.c
@@ -10,7 +10,7 @@
* See the file "license.terms" for information on usage and redistribution of
* this file, and for a DISCLAIMER OF ALL WARRANTIES.
*
- * RCS: @(#) $Id: tclUnixChan.c,v 1.76 2007/02/20 23:24:07 nijtmans Exp $
+ * RCS: @(#) $Id: tclUnixChan.c,v 1.77 2007/04/20 06:11:00 kennykb Exp $
*/
#include "tclInt.h" /* Internal definitions for Tcl. */
@@ -947,7 +947,7 @@ TtySetOptionProc(
return TCL_ERROR;
} else {
if (interp) {
- Tcl_AppendResult(interp, "bad value for -handshake: ",
+ Tcl_AppendResult(interp, "bad value for -handshake: "
"must be one of xonxoff, rtscts, dtrdsr or none",
NULL);
}
@@ -1012,7 +1012,7 @@ TtySetOptionProc(
if ((argc % 2) == 1) {
if (interp) {
Tcl_AppendResult(interp,
- "bad value for -ttycontrol: should be a list of",
+ "bad value for -ttycontrol: should be a list of"
"signal,value pairs", NULL);
}
ckfree((char *) argv);
@@ -1060,7 +1060,7 @@ TtySetOptionProc(
} else {
if (interp) {
Tcl_AppendResult(interp, "bad signal \"", argv[i],
- "\" for -ttycontrol: must be ",
+ "\" for -ttycontrol: must be "
"DTR, RTS or BREAK", NULL);
}
ckfree((char *) argv);
diff --git a/unix/tclUnixTest.c b/unix/tclUnixTest.c
index acfa5fc..a894d4d 100644
--- a/unix/tclUnixTest.c
+++ b/unix/tclUnixTest.c
@@ -9,7 +9,7 @@
* See the file "license.terms" for information on usage and redistribution of
* this file, and for a DISCLAIMER OF ALL WARRANTIES.
*
- * RCS: @(#) $Id: tclUnixTest.c,v 1.25 2007/04/17 14:49:53 dkf Exp $
+ * RCS: @(#) $Id: tclUnixTest.c,v 1.26 2007/04/20 06:11:00 kennykb Exp $
*/
#include "tclInt.h"
@@ -324,7 +324,7 @@ TestfilehandlerCmd(
Tcl_DoOneEvent(TCL_WINDOW_EVENTS|TCL_DONT_WAIT);
} else {
Tcl_AppendResult(interp, "bad option \"", argv[1],
- "\": must be close, clear, counts, create, empty, fill, ",
+ "\": must be close, clear, counts, create, empty, fill, "
"fillpartial, oneevent, wait, or windowevent", NULL);
return TCL_ERROR;
}
diff --git a/win/tclWinLoad.c b/win/tclWinLoad.c
index 7079571..30bc750 100644
--- a/win/tclWinLoad.c
+++ b/win/tclWinLoad.c
@@ -10,7 +10,7 @@
* See the file "license.terms" for information on usage and redistribution of
* this file, and for a DISCLAIMER OF ALL WARRANTIES.
*
- * RCS: @(#) $Id: tclWinLoad.c,v 1.19 2005/11/04 00:06:50 dkf Exp $
+ * RCS: @(#) $Id: tclWinLoad.c,v 1.20 2007/04/20 06:11:00 kennykb Exp $
*/
#include "tclWinInt.h"
@@ -108,20 +108,20 @@ TclpDlopen(
switch (lastError) {
case ERROR_MOD_NOT_FOUND:
case ERROR_DLL_NOT_FOUND:
- Tcl_AppendResult(interp, "this library or a dependent library",
+ Tcl_AppendResult(interp, "this library or a dependent library"
" could not be found in library path", NULL);
break;
case ERROR_PROC_NOT_FOUND:
- Tcl_AppendResult(interp, "A function specified in the import",
- " table could not be resolved by the system. Windows",
+ Tcl_AppendResult(interp, "A function specified in the import"
+ " table could not be resolved by the system. Windows"
" is not telling which one, I'm sorry.", NULL);
break;
case ERROR_INVALID_DLL:
- Tcl_AppendResult(interp, "this library or a dependent library",
+ Tcl_AppendResult(interp, "this library or a dependent library"
" is damaged", NULL);
break;
case ERROR_DLL_INIT_FAILED:
- Tcl_AppendResult(interp, "the library initialization",
+ Tcl_AppendResult(interp, "the library initialization"
" routine failed", NULL);
break;
default:
diff --git a/win/tclWinSerial.c b/win/tclWinSerial.c
index a2846b3..7a4ee94 100644
--- a/win/tclWinSerial.c
+++ b/win/tclWinSerial.c
@@ -11,7 +11,7 @@
*
* Serial functionality implemented by Rolf.Schroedter@dlr.de
*
- * RCS: @(#) $Id: tclWinSerial.c,v 1.34 2006/03/27 18:08:51 andreas_kupries Exp $
+ * RCS: @(#) $Id: tclWinSerial.c,v 1.35 2007/04/20 06:11:00 kennykb Exp $
*/
#include "tclWinInt.h"
@@ -1758,7 +1758,7 @@ SerialSetOptionProc(
} else {
if (interp != NULL) {
Tcl_AppendResult(interp, "bad value \"", value,
- "\" for -handshake: must be one of xonxoff, rtscts, ",
+ "\" for -handshake: must be one of xonxoff, rtscts, "
"dtrdsr or none", NULL);
}
return TCL_ERROR;
@@ -1791,7 +1791,7 @@ SerialSetOptionProc(
if (argc != 2) {
badXchar:
if (interp != NULL) {
- Tcl_AppendResult(interp, "bad value for -xchar: should be ",
+ Tcl_AppendResult(interp, "bad value for -xchar: should be "
"a list of two elements with each a single character",
NULL);
}
@@ -1850,7 +1850,7 @@ SerialSetOptionProc(
if ((argc % 2) == 1) {
if (interp != NULL) {
Tcl_AppendResult(interp, "bad value \"", value,
- "\" for -ttycontrol: should be a list of ",
+ "\" for -ttycontrol: should be a list of "
"signal,value pairs", NULL);
}
ckfree((char *) argv);
@@ -1931,7 +1931,7 @@ SerialSetOptionProc(
if ((argc < 1) || (argc > 2) || (inSize <= 0) || (outSize <= 0)) {
if (interp != NULL) {
Tcl_AppendResult(interp, "bad value \"", value,
- "\" for -sysbuffer: should be a list of one or two ",
+ "\" for -sysbuffer: should be a list of one or two "
"integers > 0", NULL);
}
return TCL_ERROR;
2c3b5b2b2dd4953c12c5384'>doc/bgerror.n41
-rw-r--r--doc/binary.n489
-rw-r--r--doc/catch.n66
-rw-r--r--doc/chan.n736
-rw-r--r--doc/clock.n1089
-rw-r--r--doc/close.n8
-rw-r--r--doc/concat.n34
-rw-r--r--doc/dde.n63
-rw-r--r--doc/dict.n389
-rw-r--r--doc/encoding.n20
-rw-r--r--doc/error.n48
-rw-r--r--doc/eval.n50
-rw-r--r--doc/exec.n194
-rw-r--r--doc/exit.n10
-rw-r--r--doc/expr.n366
-rw-r--r--doc/fblocked.n2
-rw-r--r--doc/fconfigure.n50
-rw-r--r--doc/fcopy.n93
-rw-r--r--doc/file.n235
-rw-r--r--doc/fileevent.n12
-rw-r--r--doc/filename.n95
-rw-r--r--doc/flush.n2
-rw-r--r--doc/for.n2
-rw-r--r--doc/foreach.n29
-rw-r--r--doc/format.n94
-rw-r--r--doc/gets.n2
-rw-r--r--doc/glob.n105
-rw-r--r--doc/global.n6
-rw-r--r--doc/history.n22
-rw-r--r--doc/http.n271
-rw-r--r--doc/if.n3
-rw-r--r--doc/incr.n8
-rw-r--r--doc/info.n160
-rw-r--r--doc/interp.n402
-rw-r--r--doc/join.n4
-rw-r--r--doc/lappend.n17
-rw-r--r--doc/lassign.n55
-rw-r--r--doc/library.n48
-rw-r--r--doc/lindex.n55
-rw-r--r--doc/linsert.n18
-rw-r--r--doc/list.n11
-rw-r--r--doc/llength.n4
-rw-r--r--doc/load.n29
-rw-r--r--doc/lrange.n27
-rw-r--r--doc/lrepeat.n39
-rw-r--r--doc/lreplace.n55
-rw-r--r--doc/lreverse.n31
-rw-r--r--doc/lsearch.n221
-rw-r--r--[-rwxr-xr-x]doc/lset.n53
-rw-r--r--doc/lsort.n67
-rw-r--r--doc/man.macros201
-rw-r--r--doc/mathfunc.n271
-rw-r--r--doc/mathop.n305
-rw-r--r--doc/memory.n34
-rw-r--r--doc/msgcat.n183
-rw-r--r--doc/namespace.n328
-rw-r--r--doc/open.n99
-rw-r--r--doc/package.n195
-rw-r--r--doc/packagens.n5
-rw-r--r--doc/pid.n2
-rw-r--r--doc/pkgMkIndex.n60
-rw-r--r--doc/platform.n66
-rw-r--r--doc/platform_shell.n57
-rw-r--r--doc/proc.n22
-rw-r--r--doc/puts.n6
-rw-r--r--doc/pwd.n3
-rw-r--r--doc/re_syntax.n1254
-rw-r--r--doc/read.n4
-rw-r--r--doc/refchan.n340
-rw-r--r--doc/regexp.n96
-rw-r--r--doc/registry.n57
-rw-r--r--doc/regsub.n107
-rw-r--r--doc/return.n234
-rw-r--r--doc/safe.n60
-rw-r--r--doc/scan.n169
-rw-r--r--doc/seek.n4
-rw-r--r--doc/set.n7
-rw-r--r--doc/socket.n18
-rw-r--r--doc/source.n34
-rw-r--r--doc/split.n14
-rw-r--r--doc/string.n145
-rw-r--r--doc/subst.n72
-rw-r--r--doc/switch.n94
-rw-r--r--doc/tclsh.145
-rw-r--r--doc/tcltest.n651
-rw-r--r--doc/tclvars.n236
-rw-r--r--doc/tell.n4
-rw-r--r--doc/time.n2
-rw-r--r--doc/tm.n293
-rw-r--r--doc/trace.n246
-rw-r--r--doc/unknown.n28
-rw-r--r--doc/unload.n162
-rw-r--r--doc/unset.n7
-rw-r--r--doc/update.n5
-rw-r--r--doc/uplevel.n13
-rw-r--r--doc/upvar.n32
-rw-r--r--doc/vwait.n2
200 files changed, 13014 insertions, 5844 deletions
diff --git a/doc/Access.3 b/doc/Access.3
index cab6466..98d6635 100644
--- a/doc/Access.3
+++ b/doc/Access.3
@@ -19,7 +19,7 @@ int
int
\fBTcl_Stat\fR(\fIpath\fR, \fIstatPtr\fR)
.SH ARGUMENTS
-.AS "struct stat" *statPtr in
+.AS "struct stat" *statPtr out
.AP char *path in
Native name of the file to check the attributes of.
.AP int mode in
diff --git a/doc/AddErrInfo.3 b/doc/AddErrInfo.3
index 7351dce..136a16f 100644
--- a/doc/AddErrInfo.3
+++ b/doc/AddErrInfo.3
@@ -6,17 +6,29 @@
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.so man.macros
-.TH Tcl_AddErrorInfo 3 8.0 Tcl "Tcl Library Procedures"
+.TH Tcl_AddErrorInfo 3 8.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
-Tcl_AddObjErrorInfo, Tcl_AddErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_PosixError, Tcl_LogCommandInfo \- record information about errors
+Tcl_GetReturnOptions, Tcl_SetReturnOptions, Tcl_AddErrorInfo, Tcl_AppendObjToErrorInfo, Tcl_AddObjErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_PosixError, Tcl_LogCommandInfo \- retrieve or record information about errors and other return options
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
+.VS 8.5
.sp
-\fBTcl_AddObjErrorInfo\fR(\fIinterp, message, length\fR)
+Tcl_Obj *
+\fBTcl_GetReturnOptions\fR(\fIinterp, code\fR)
+.sp
+int
+\fBTcl_SetReturnOptions\fR(\fIinterp, options\fR)
+.VE 8.5
.sp
\fBTcl_AddErrorInfo\fR(\fIinterp, message\fR)
+.VS 8.5
+.sp
+\fBTcl_AppendObjToErrorInfo\fR(\fIinterp, objPtr\fR)
+.VE 8.5
+.sp
+\fBTcl_AddObjErrorInfo\fR(\fIinterp, message, length\fR)
.sp
\fBTcl_SetObjErrorCode\fR(\fIinterp, errorObjPtr\fR)
.sp
@@ -24,38 +36,47 @@ Tcl_AddObjErrorInfo, Tcl_AddErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tc
.sp
\fBTcl_SetErrorCodeVA\fR(\fIinterp, argList\fR)
.sp
-CONST char *
+const char *
\fBTcl_PosixError\fR(\fIinterp\fR)
.sp
void
\fBTcl_LogCommandInfo\fR(\fIinterp, script, command, commandLength\fR)
.SH ARGUMENTS
-.AS Tcl_Interp *message
+.AS Tcl_Interp commandLength
.AP Tcl_Interp *interp in
Interpreter in which to record information.
+.AP int code
+The code returned from script evaluation.
+.AP Tcl_Obj *options
+A dictionary of return options.
.AP char *message in
+For \fBTcl_AddErrorInfo\fR,
+this is a conventional C string to append to the \fB\-errorinfo\fR return option.
For \fBTcl_AddObjErrorInfo\fR,
-this points to the first byte of an array of bytes
-containing a string to record in the \fBerrorInfo\fR variable.
+this points to the first byte of an array of \fIlength\fR bytes
+containing a string to append to the \fB\-errorinfo\fR return option.
This byte array may contain embedded null bytes
unless \fIlength\fR is negative.
-For \fBTcl_AddErrorInfo\fR,
-this is a conventional C string to record in the \fBerrorInfo\fR variable.
+.VS 8.5
+.AP Tcl_Obj *objPtr in
+A message to be appended to the \fB\-errorinfo\fR return option
+in the form of a Tcl_Obj value.
+.VE 8.5
.AP int length in
The number of bytes to copy from \fImessage\fR when
-setting the \fBerrorInfo\fR variable.
+appending to the \fB\-errorinfo\fR return option.
If negative, all bytes up to the first null byte are used.
.AP Tcl_Obj *errorObjPtr in
-This variable \fBerrorCode\fR will be set to this value.
+The \fB\-errorcode\fR return option will be set to this value.
.AP char *element in
-String to record as one element of \fBerrorCode\fR variable.
+String to record as one element of the \fB\-errorcode\fR return option.
Last \fIelement\fR argument must be NULL.
.AP va_list argList in
An argument list which must have been initialized using
-\fBTCL_VARARGS_START\fR, and cleared using \fBva_end\fR.
-.AP "CONST char" *script in
+\fBva_start\fR, and cleared using \fBva_end\fR.
+.AP "const char" *script in
Pointer to first character in script containing command (must be <= command)
-.AP "CONST char" *command in
+.AP "const char" *command in
Pointer to first character in command that generated the error
.AP int commandLength in
Number of bytes in command; -1 means use all bytes up to first null byte
@@ -63,70 +84,156 @@ Number of bytes in command; -1 means use all bytes up to first null byte
.SH DESCRIPTION
.PP
-These procedures are used to manipulate two Tcl global variables
-that hold information about errors.
-The variable \fBerrorInfo\fR holds a stack trace of the
+.VS 8.5
+The \fBTcl_SetReturnOptions\fR and \fBTcl_GetReturnOptions\fR
+routines expose the same capabilities as the \fBreturn\fR and
+\fBcatch\fR commands, respectively, in the form of a C interface.
+.PP
+\fBTcl_GetReturnOptions\fR retrieves the dictionary of return options
+from an interpreter following a script evaluation.
+Routines such as \fBTcl_Eval\fR are called to evaluate a
+script in an interpreter. These routines return an integer
+completion code. These routines also leave in the interpreter
+both a result and a dictionary of return options generated
+by script evaluation. Just as \fBTcl_GetObjResult\fR retrieves
+the result, \fBTcl_GetReturnOptions\fR retrieves the dictionary
+of return options. The integer completion code should be
+passed as the \fIcode\fR argument to \fBTcl_GetReturnOptions\fR
+so that all required options will be present in the dictionary.
+Specifically, a \fIcode\fR value of \fBTCL_ERROR\fR will
+ensure that entries for the keys \fB\-errorinfo\fR,
+\fB\-errorcode\fR, and \fB\-errorline\fR will appear in the
+dictionary. Also, the entries for the keys \fB\-code\fR
+and \fB\-level\fR will be adjusted if necessary to agree
+with the value of \fIcode\fR. The \fB(Tcl_Obj *)\fR returned
+by \fBTcl_GetReturnOptions\fR points to an unshared
+\fBTcl_Obj\fR with reference count of zero. The dictionary
+may be written to, either adding, removing, or overwriting
+any entries in it, without the need to check for a shared object.
+.PP
+A typical usage for \fBTcl_GetReturnOptions\fR is to
+retrieve the stack trace when script evaluation returns
+\fBTCL_ERROR\fR, like so:
+.CS
+int code = Tcl_Eval(interp, script);
+if (code == TCL_ERROR) {
+ Tcl_Obj *options = Tcl_GetReturnOptions(interp, code);
+ Tcl_Obj *key = Tcl_NewStringObj("-errorinfo", -1);
+ Tcl_Obj *stackTrace;
+ Tcl_IncrRefCount(key);
+ Tcl_DictObjGet(NULL, options, key, &stackTrace);
+ Tcl_DecrRefCount(key);
+ /* Do something with stackTrace */
+}
+.CE
+.PP
+\fBTcl_SetReturnOptions\fR sets the return options
+of \fIinterp\fR to be \fIoptions\fR. If \fIoptions\fR
+contains any invalid value for any key, TCL_ERROR will
+be returned, and the interp result will be set to an
+appropriate error message. Otherwise, a completion code
+in agreement with the \fB\-code\fR and \fB\-level\fR
+keys in \fIoptions\fR will be returned.
+.PP
+As an example, Tcl's \fBreturn\fR command itself could
+be implemented in terms of \fBTcl_SetReturnOptions\fR
+like so:
+.CS
+if ((objc % 2) == 0) { /* explicit result argument */
+ objc--;
+ Tcl_SetObjResult(interp, objv[objc]);
+}
+return Tcl_SetReturnOptions(interp, Tcl_NewListObj(objc-1, objv+1));
+.CE
+(It is not really implemented that way. Internal access
+privileges allow for a more efficient alternative that meshes
+better with the bytecode compiler.)
+.PP
+Note that a newly created \fBTcl_Obj\fR may be passed
+in as the \fIoptions\fR argument without the need to tend
+to any reference counting. This is analogous to
+\fBTcl_SetObjResult\fR.
+.PP
+While \fBTcl_SetReturnOptions\fR provides a general interface
+to set any collection of return options, there are a handful
+of return options that are very frequently used. Most
+notably the \fB\-errorinfo\fR and \fB\-errorcode\fR return
+options should be set properly when the command procedure
+of a command returns \fBTCL_ERROR\fR. Tcl provides several
+simpler interfaces to more directly set these return options.
+.VE 8.5
+.PP
+The \fB\-errorinfo\fR option holds a stack trace of the
operations that were in progress when an error occurred,
and is intended to be human-readable.
-The variable \fBerrorCode\fR holds a list of items that
+The \fB\-errorcode\fR option holds a list of items that
are intended to be machine-readable.
-The first item in \fBerrorCode\fR identifies the class of
+The first item in the \fB\-errorcode\fR value identifies the class of
error that occurred
(e.g. POSIX means an error occurred in a POSIX system call)
-and additional elements in \fBerrorCode\fR hold additional pieces
+and additional elements hold additional pieces
of information that depend on the class.
-See the Tcl overview manual entry for details on the various
-formats for \fBerrorCode\fR.
+See the tclvars manual entry for details on the various
+formats for the \fB\-errorcode\fR option used by
+Tcl's built-in commands.
.PP
-The \fBerrorInfo\fR variable is gradually built up as an
+The \fB\-errorinfo\fR option value is gradually built up as an
error unwinds through the nested operations.
-Each time an error code is returned to \fBTcl_EvalObjEx\fR
-(or \fBTcl_Eval\fR, which calls \fBTcl_EvalObjEx\fR)
-it calls the procedure \fBTcl_AddObjErrorInfo\fR to add
-additional text to \fBerrorInfo\fR describing the
+Each time an error code is returned to \fBTcl_Eval\fR, or
+any of the routines that performs script evaluation,
+the procedure \fBTcl_AddErrorInfo\fR is called to add
+additional text to the \fB\-errorinfo\fR value describing the
command that was being executed when the error occurred.
By the time the error has been passed all the way back
to the application, it will contain a complete trace
of the activity in progress when the error occurred.
.PP
It is sometimes useful to add additional information to
-\fBerrorInfo\fR beyond what can be supplied automatically
-by \fBTcl_EvalObjEx\fR.
-\fBTcl_AddObjErrorInfo\fR may be used for this purpose:
-its \fImessage\fR and \fIlength\fR arguments describe an additional
-string to be appended to \fBerrorInfo\fR.
-For example, the \fBsource\fR command calls \fBTcl_AddObjErrorInfo\fR
-to record the name of the file being processed and the
-line number on which the error occurred;
-for Tcl procedures, the procedure name and line number
+the \fB\-errorinfo\fR value beyond what can be supplied automatically
+by the script evaluation routines.
+\fBTcl_AddErrorInfo\fR may be used for this purpose:
+its \fImessage\fR argument is an additional
+string to be appended to the \fB\-errorinfo\fR option.
+For example, when an error arises during the \fBsource\fR command,
+the procedure \fBTcl_AddErrorInfo\fR is called to
+record the name of the file being processed and the
+line number on which the error occurred.
+Likewise, when an error arises during evaluation of a
+Tcl procedures, the procedure name and line number
within the procedure are recorded, and so on.
-The best time to call \fBTcl_AddObjErrorInfo\fR is just after
-\fBTcl_EvalObjEx\fR has returned \fBTCL_ERROR\fR.
-In calling \fBTcl_AddObjErrorInfo\fR, you may find it useful to
-use the \fBerrorLine\fR field of the interpreter (see the
-\fBTcl_Interp\fR manual entry for details).
-.PP
-\fBTcl_AddErrorInfo\fR resembles \fBTcl_AddObjErrorInfo\fR
-but differs in initializing \fBerrorInfo\fR from the string
-value of the interpreter's result
-if the error is just starting to be logged.
-It does not use the result as a Tcl object
-so any embedded null characters in the result
-will cause information to be lost.
-It also takes a conventional C string in \fImessage\fR
-instead of \fBTcl_AddObjErrorInfo\fR's counted string.
+The best time to call \fBTcl_AddErrorInfo\fR is just after
+a script evaluation routine has returned \fBTCL_ERROR\fR.
+The value of the \fB\-errorline\fR return option (retrieved
+via a call to \fBTcl_GetReturnOptions\fR) often makes up
+a useful part of the \fImessage\fR passed to \fBTcl_AddErrorInfo\fR.
+.PP
+.VS 8.5
+\fBTcl_AppendObjToErrorInfo\fR is an alternative interface to the
+same functionality as \fBTcl_AddErrorInfo\fR. \fBTcl_AppendObjToErrorInfo\fR
+is called when the string value to be appended to the \fB\-errorinfo\fR option
+is available as a \fBTcl_Obj\fR instead of as a \fBchar\fR array.
+.VE 8.5
+.PP
+\fBTcl_AddObjErrorInfo\fR is nearly identical
+to \fBTcl_AddErrorInfo\fR, except that it has an additional \fIlength\fR
+argument. This allows the \fImessage\fR string to contain
+embedded null bytes. This is essentially never a good idea.
+If the \fImessage\fR needs to contain the null character \fBU+0000\fR,
+Tcl's usual internal encoding rules should be used to avoid
+the need for a null byte. If the \fBTcl_AddObjErrorInfo\fR
+interface is used at all, it should be with a negative \fIlength\fR value.
.PP
The procedure \fBTcl_SetObjErrorCode\fR is used to set the
-\fBerrorCode\fR variable. \fIerrorObjPtr\fR contains a list object
-built up by the caller. \fBerrorCode\fR is set to this
-value. \fBTcl_SetObjErrorCode\fR is typically invoked just
-before returning an error in an object command. If an error is
+\fB\-errorcode\fR return option to the list object \fIerrorObjPtr\fR
+built up by the caller.
+\fBTcl_SetObjErrorCode\fR is typically invoked just
+before returning an error. If an error is
returned without calling \fBTcl_SetObjErrorCode\fR or
\fBTcl_SetErrorCode\fR the Tcl interpreter automatically sets
-\fBerrorCode\fR to \fBNONE\fR.
+the \fB\-errorcode\fR return option to \fBNONE\fR.
.PP
The procedure \fBTcl_SetErrorCode\fR is also used to set the
-\fBerrorCode\fR variable. However, it takes one or more strings to
+\fB\-errorcode\fR return option. However, it takes one or more strings to
record instead of an object. Otherwise, it is similar to
\fBTcl_SetObjErrorCode\fR in behavior.
.PP
@@ -134,9 +241,10 @@ record instead of an object. Otherwise, it is similar to
instead of taking a variable number of arguments it takes an argument list.
.PP
\fBTcl_PosixError\fR
-sets the \fBerrorCode\fR variable after an error in a POSIX kernel call.
+sets the \fB\-errorcode\fR variable after an error in a POSIX kernel call.
It reads the value of the \fBerrno\fR C variable and calls
-\fBTcl_SetErrorCode\fR to set \fBerrorCode\fR in the \fBPOSIX\fR format.
+\fBTcl_SetErrorCode\fR to set the \fB\-errorcode\fR return
+option in the \fBPOSIX\fR format.
The caller must previously have called \fBTcl_SetErrno\fR to set
\fBerrno\fR; this is necessary on some platforms (e.g. Windows) where Tcl
is linked into an application as a shared library, or when the error
@@ -146,41 +254,44 @@ occurs in a dynamically loaded extension. See the manual entry for
\fBTcl_PosixError\fR returns a human-readable diagnostic message
for the error
(this is the same value that will appear as the third element
-in \fBerrorCode\fR).
+in the \fB\-errorcode\fR value).
It may be convenient to include this string as part of the
error message returned to the application in
the interpreter's result.
.PP
\fBTcl_LogCommandInfo\fR is invoked after an error occurs in an
interpreter. It adds information about the command that was being
-executed when the error occurred to the \fBerrorInfo\fR variable, and
-the line number stored internally in the interpreter is set. On the
-first call to \fBTcl_LogCommandInfo\fR or \fBTcl_AddObjErrorInfo\fR
-since an error occurred, the old information in \fBerrorInfo\fR is
-deleted.
+executed when the error occurred to the \fB\-errorinfo\fR value, and
+the line number stored internally in the interpreter is set.
+.PP
+In older releases of Tcl, there was no \fBTcl_GetReturnOptions\fR
+routine. In its place, the global Tcl variables \fBerrorInfo\fR
+and \fBerrorCode\fR were the only place to retrieve the error
+information. Much existing code written for older Tcl releases
+still access this information via those global variables.
.PP
-It is important to call the procedures described here rather than
+It is important to realize that while reading from those
+global variables remains a supported way to access these
+return option values, it is important not to assume that
+writing to those global variables will properly set the
+corresponding return options. It has long been emphasized
+in this manual page that it is important to
+call the procedures described here rather than
setting \fBerrorInfo\fR or \fBerrorCode\fR directly with
\fBTcl_ObjSetVar2\fR.
-The reason for this is that the Tcl interpreter keeps information
-about whether these procedures have been called.
-For example, the first time \fBTcl_AddObjErrorInfo\fR is called
-for an error, it clears the existing value of \fBerrorInfo\fR
-and adds the error message in the interpreter's result to the variable
-before appending \fImessage\fR;
-in subsequent calls, it just appends the new \fImessage\fR.
-When \fBTcl_SetErrorCode\fR is called, it sets a flag indicating
-that \fBerrorCode\fR has been set;
-this allows the Tcl interpreter to set \fBerrorCode\fR to \fBNONE\fR
-if it receives an error return
-when \fBTcl_SetErrorCode\fR hasn't been called.
.PP
If the procedure \fBTcl_ResetResult\fR is called,
-it clears all of the state associated with
-\fBerrorInfo\fR and \fBerrorCode\fR
-(but it doesn't actually modify the variables).
-If an error had occurred, this will clear the error state to
-make it appear as if no error had occurred after all.
+it clears all of the state of the interpreter associated with
+script evaluation, including the entire return options dictionary.
+In particular, the \fB\-errorinfo\fR and \fB\-errorcode\fR options
+are reset.
+If an error had occurred, the \fBTcl_ResetResult\fR call will
+clear the error state to make it appear as if no error had
+occurred after all.
+The global variables \fBerrorInfo\fR and
+\fBerrorCode\fR are not modified by \fBTcl_ResetResult\fR
+so they continue to hold a record of information about the
+most recent error seen in an interpreter.
.SH "SEE ALSO"
Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_Interp, Tcl_ResetResult, Tcl_SetErrno
diff --git a/doc/Alloc.3 b/doc/Alloc.3
index e90114d..ca4f949 100644
--- a/doc/Alloc.3
+++ b/doc/Alloc.3
@@ -67,22 +67,24 @@ further allocation.
\fBTcl_Realloc\fR changes the size of the block pointed to by
\fIptr\fR to \fIsize\fR bytes and returns a pointer to the new block.
The contents will be unchanged up to the lesser of the new and old
-sizes. The returned location may be different from \fIptr\fR.
+sizes. The returned location may be different from \fIptr\fR. If
+\fIptr\fR is NULL, this is equivalent to calling \fBTcl_Alloc\fR with
+just the \fIsize\fR argument.
.PP
\fBTcl_AttemptAlloc\fR and \fBTcl_AttemptRealloc\fR are identical in
function to \fBTcl_Alloc\fR and \fBTcl_Realloc\fR, except that
\fBTcl_AttemptAlloc\fR and \fBTcl_AttemptRealloc\fR will not cause the Tcl
interpreter to \fBpanic\fR if the memory allocation fails. If the
allocation fails, these functions will return NULL. Note that on some
-platforms, attempting to allocate a block of memory will also cause
-these functions to return NULL.
+platforms, but not all, attempting to allocate a zero-sized block of
+memory will also cause these functions to return NULL.
.PP
The procedures \fBckalloc\fR, \fBckfree\fR, \fBckrealloc\fR,
\fBattemptckalloc\fR, and \fBattemptckrealloc\fR are implemented
as macros. Normally, they are synonyms for the corresponding
procedures documented on this page. When Tcl and all modules
calling Tcl are compiled with \fBTCL_MEM_DEBUG\fR defined, however,
-these macros are redefined to be special debugging versions of
+these macros are redefined to be special debugging versions
of these procedures. To support Tcl's memory debugging within a
module, use the macros rather than direct calls to \fBTcl_Alloc\fR, etc.
diff --git a/doc/AllowExc.3 b/doc/AllowExc.3
index 621ea47..ae595f1 100644
--- a/doc/AllowExc.3
+++ b/doc/AllowExc.3
@@ -16,7 +16,7 @@ Tcl_AllowExceptions \- allow all exceptions in next script evaluation
.sp
\fBTcl_AllowExceptions\fR(\fIinterp\fR)
.SH ARGUMENTS
-.AS Tcl_Interp *doublePtr
+.AS Tcl_Interp *interp
.AP Tcl_Interp *interp in
Interpreter in which script will be evaluated.
.BE
@@ -25,8 +25,8 @@ Interpreter in which script will be evaluated.
.PP
If a script is evaluated at top-level (i.e. no other scripts are
pending evaluation when the script is invoked), and if the script
-terminates with a completion code other than TCL_OK, TCL_ERROR
-or TCL_RETURN, then Tcl normally converts this into a TCL_ERROR
+terminates with a completion code other than \fBTCL_OK\fR, \fBTCL_ERROR\fR
+or \fBTCL_RETURN\fR, then Tcl normally converts this into a \fBTCL_ERROR\fR
return with an appropriate message. The particular script
evaluation procedures of Tcl that act in the manner are
\fBTcl_EvalObjEx\fR, \fBTcl_EvalObjv\fR, \fBTcl_Eval\fR, \fBTcl_EvalEx\fR,
@@ -38,7 +38,7 @@ calling one of those a procedures, then arbitrary completion
codes are permitted from the script, and they are returned without
modification.
This is useful in cases where the caller can deal with exceptions
-such as TCL_BREAK or TCL_CONTINUE in a meaningful way.
+such as \fBTCL_BREAK\fR or \fBTCL_CONTINUE\fR in a meaningful way.
.SH KEYWORDS
continue, break, exception, interpreter
diff --git a/doc/AppInit.3 b/doc/AppInit.3
index 14d30cf..0473090 100644
--- a/doc/AppInit.3
+++ b/doc/AppInit.3
@@ -24,7 +24,9 @@ Interpreter for the application.
.SH DESCRIPTION
.PP
-\fBTcl_AppInit\fR is a ``hook'' procedure that is invoked by
+\fBTcl_AppInit\fR is a
+.QW hook
+procedure that is invoked by
the main programs for Tcl applications such as \fBtclsh\fR and \fBwish\fR.
Its purpose is to allow new Tcl applications to be created without
modifying the main programs provided as part of Tcl and Tk.
@@ -47,8 +49,8 @@ Tcl variables \fBargv\fR and \fBargv0\fR in \fIinterp\fR.
.IP [3]
Invoke a startup script to initialize the application.
.LP
-\fBTcl_AppInit\fR returns TCL_OK or TCL_ERROR.
-If it returns TCL_ERROR then it must leave an error message in
+\fBTcl_AppInit\fR returns \fBTCL_OK\fR or \fBTCL_ERROR\fR.
+If it returns \fBTCL_ERROR\fR then it must leave an error message in
for the interpreter's result; otherwise the result is ignored.
.PP
In addition to \fBTcl_AppInit\fR, your application should also contain
@@ -58,7 +60,7 @@ Tcl_Main(argc, argv, Tcl_AppInit);
.CE
The third argument to \fBTcl_Main\fR gives the address of the
application-specific initialization procedure to invoke.
-This means that you don't have to use the name \fBTcl_AppInit\fR
+This means that you do not have to use the name \fBTcl_AppInit\fR
for the procedure, but in practice the name is nearly always
\fBTcl_AppInit\fR (in versions before Tcl 7.4 the name \fBTcl_AppInit\fR
was implicit; there was no way to specify the procedure explicitly).
diff --git a/doc/AssocData.3 b/doc/AssocData.3
index 105ebd6..e4c7bab 100644
--- a/doc/AssocData.3
+++ b/doc/AssocData.3
@@ -8,9 +8,7 @@
.TH Tcl_SetAssocData 3 7.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
-Tcl_GetAssocData, Tcl_SetAssocData, Tcl_DeleteAssocData \- manage
-associations of string keys and user specified data with Tcl
-interpreters.
+Tcl_GetAssocData, Tcl_SetAssocData, Tcl_DeleteAssocData \- manage associations of string keys and user specified data with Tcl interpreters
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
@@ -22,12 +20,10 @@ ClientData
.sp
\fBTcl_DeleteAssocData\fR(\fIinterp, key\fR)
.SH ARGUMENTS
-.AS Tcl_InterpDeleteProc *delProcPtr
+.AS Tcl_InterpDeleteProc **delProcPtr
.AP Tcl_Interp *interp in
Interpreter in which to execute the specified command.
-.VS 8.4
-.AP "CONST char" *key in
-.VE
+.AP "const char" *key in
Key for association with which to store data or from which to delete or
retrieve data. Typically the module prefix for a package.
.AP Tcl_InterpDeleteProc *delProc in
@@ -67,8 +63,8 @@ is deleted. \fIDeleteProc\fR should have arguments and result that match
the type \fBTcl_InterpDeleteProc\fR:
.CS
typedef void Tcl_InterpDeleteProc(
- ClientData \fIclientData\fR,
- Tcl_Interp *\fIinterp\fR);
+ ClientData \fIclientData\fR,
+ Tcl_Interp *\fIinterp\fR);
.CE
When \fIdeleteProc\fR is invoked the \fIclientData\fR and \fIinterp\fR
arguments will be the same as the corresponding arguments passed to
diff --git a/doc/Async.3 b/doc/Async.3
index cc3354b..c4439a4 100644
--- a/doc/Async.3
+++ b/doc/Async.3
@@ -48,9 +48,9 @@ or 0 if \fIinterp\fR is NULL.
These procedures provide a safe mechanism for dealing with
asynchronous events such as signals.
If an event such as a signal occurs while a Tcl script is being
-evaluated then it isn't safe to take any substantive action to
+evaluated then it is not safe to take any substantive action to
process the event.
-For example, it isn't safe to evaluate a Tcl script since the
+For example, it is not safe to evaluate a Tcl script since the
interpreter may already be in the middle of evaluating a script;
it may not even be safe to allocate memory, since a memory
allocation could have been in progress when the event occurred.
@@ -140,7 +140,6 @@ If new handlers become ready while handlers are executing,
\fBTcl_AsyncInvoke\fR will invoke them all; at each point it
invokes the highest-priority (oldest) ready handler, repeating
this over and over until there are no longer any ready handlers.
-
.SH WARNING
.PP
It is almost always a bad idea for an asynchronous event
@@ -150,12 +149,11 @@ This sort of behavior can disrupt the execution of scripts in
subtle ways and result in bugs that are extremely difficult
to track down.
If an asynchronous event handler needs to evaluate Tcl scripts
-then it should first save the interpreter's result plus the values
-of the variables \fBerrorInfo\fR and \fBerrorCode\fR (this can
-be done, for example, by storing them in dynamic strings).
+then it should first save the interpreter's state by calling
+\fBTcl_SaveInterpState\fR, passing in the \fIcode\fR argument.
When the asynchronous handler is finished it should restore
-the interpreter's result, \fBerrorInfo\fR, and \fBerrorCode\fR,
-and return the \fIcode\fR argument.
+the interpreter's state by calling \fBTcl_RestoreInterpState\fR,
+and then returning the \fIcode\fR argument.
.SH KEYWORDS
-asynchronous event, handler, signal
+asynchronous event, handler, signal, Tcl_SaveInterpState, thread
diff --git a/doc/BackgdErr.3 b/doc/BackgdErr.3
index 532bb44..1e46b03 100644
--- a/doc/BackgdErr.3
+++ b/doc/BackgdErr.3
@@ -24,7 +24,8 @@ Interpreter in which the error occurred.
.SH DESCRIPTION
.PP
This procedure is typically invoked when a Tcl error occurs during
-``background processing'' such as executing an event handler.
+.QW "background processing"
+such as executing an event handler.
When such an error occurs, the error condition is reported to Tcl
or to a widget or some other C code, and there is not usually any
obvious way for that code to report the error to the user.
@@ -32,25 +33,29 @@ In these cases the code calls \fBTcl_BackgroundError\fR with an
\fIinterp\fR argument identifying the interpreter in which the
error occurred. At the time \fBTcl_BackgroundError\fR is invoked,
the interpreter's result is expected to contain an error message.
-\fBTcl_BackgroundError\fR will invoke the \fBbgerror\fR
-Tcl command to report the error in an application-specific fashion.
-If no \fBbgerror\fR command exists, or if it returns with an error condition,
-then \fBTcl_BackgroundError\fR reports the error itself by printing
-a message on the standard error file.
+\fBTcl_BackgroundError\fR will invoke the command registered
+in that interpreter to handle background errors by the
+\fBinterp bgerror\fR command.
+The registered handler command is meant to report the error
+in an application-specific fashion. The handler command
+receives two arguments, the result of the interp, and the
+return options of the interp at the time the error occurred.
+If the application registers no handler command, the default
+handler command will attempt to call \fBbgerror\fR to report
+the error. If an error condition arises while invoking the
+handler command, then \fBTcl_BackgroundError\fR reports the
+error itself by printing a message on the standard error file.
.PP
-\fBTcl_BackgroundError\fR does not invoke \fBbgerror\fR immediately
+\fBTcl_BackgroundError\fR does not invoke the handler command immediately
because this could potentially interfere with scripts that are in process
at the time the error occurred.
-Instead, it invokes \fBbgerror\fR later as an idle callback.
-\fBTcl_BackgroundError\fR saves the values of the \fBerrorInfo\fR and
-\fBerrorCode\fR variables and restores these values just before
-invoking \fBbgerror\fR.
+Instead, it invokes the handler command later as an idle callback.
.PP
It is possible for many background errors to accumulate before
-\fBbgerror\fR is invoked. When this happens, each of the errors
-is processed in order. However, if \fBbgerror\fR returns a
+the handler command is invoked. When this happens, each of the errors
+is processed in order. However, if the handle command returns a
break exception, then all remaining error reports for the
interpreter are skipped.
.SH KEYWORDS
-background, bgerror, error
+background, bgerror, error, interp
diff --git a/doc/Backslash.3 b/doc/Backslash.3
index eb859d7..8b399fc 100644
--- a/doc/Backslash.3
+++ b/doc/Backslash.3
@@ -17,35 +17,31 @@ Tcl_Backslash \- parse a backslash sequence
char
\fBTcl_Backslash\fR(\fIsrc, countPtr\fR)
.SH ARGUMENTS
-.AS char *countPtr
+.AS char *countPtr out
.AP char *src in
Pointer to a string starting with a backslash.
.AP int *countPtr out
-If \fIcountPtr\fR isn't NULL, \fI*countPtr\fR gets filled
+If \fIcountPtr\fR is not NULL, \fI*countPtr\fR gets filled
in with number of characters in the backslash sequence, including
the backslash character.
.BE
.SH DESCRIPTION
.PP
-.VS 8.1
The use of \fBTcl_Backslash\fR is deprecated in favor of
\fBTcl_UtfBackslash\fR.
.PP
This is a utility procedure provided for backwards compatibility with
non-internationalized Tcl extensions. It parses a backslash sequence and
returns the low byte of the Unicode character corresponding to the sequence.
-.VE
\fBTcl_Backslash\fR modifies \fI*countPtr\fR to contain the number of
characters in the backslash sequence.
.PP
See the Tcl manual entry for information on the valid backslash sequences.
All of the sequences described in the Tcl manual entry are supported by
\fBTcl_Backslash\fR.
-.VS 8.1 br
.SH "SEE ALSO"
Tcl(n), Tcl_UtfBackslash(3)
-.VE
.SH KEYWORDS
backslash, parse
diff --git a/doc/BoolObj.3 b/doc/BoolObj.3
index 2814e4e..395d159 100644
--- a/doc/BoolObj.3
+++ b/doc/BoolObj.3
@@ -1,14 +1,15 @@
'\"
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
+'\" Contributions from Don Porter, NIST, 2005. (not subject to US copyright)
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.so man.macros
-.TH Tcl_BooleanObj 3 8.0 Tcl "Tcl Library Procedures"
+.TH Tcl_BooleanObj 3 8.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
-Tcl_NewBooleanObj, Tcl_SetBooleanObj, Tcl_GetBooleanFromObj \- manipulate Tcl objects as boolean values
+Tcl_NewBooleanObj, Tcl_SetBooleanObj, Tcl_GetBooleanFromObj \- store/retrieve boolean value in a Tcl_Obj
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
@@ -21,20 +22,14 @@ Tcl_Obj *
int
\fBTcl_GetBooleanFromObj\fR(\fIinterp, objPtr, boolPtr\fR)
.SH ARGUMENTS
-.AS Tcl_Interp *interp
+.AS Tcl_Interp boolValue in/out
.AP int boolValue in
-Integer value used to initialize or set a boolean object.
-If the integer is nonzero, the boolean object is set to 1;
-otherwise the boolean object is set to 0.
+Integer value to be stored as a boolean value in a Tcl_Obj.
.AP Tcl_Obj *objPtr in/out
-For \fBTcl_SetBooleanObj\fR, this points to the object to be converted
-to boolean type.
-For \fBTcl_GetBooleanFromObj\fR, this refers to the object
-from which to get a boolean value;
-if \fIobjPtr\fR does not already point to a boolean object,
-an attempt will be made to convert it to one.
+Points to the Tcl_Obj in which to store, or from which to
+retrieve a boolean value.
.AP Tcl_Interp *interp in/out
-If an error occurs during conversion,
+If a boolean value cannot be retrieved,
an error message is left in the interpreter's result object
unless \fIinterp\fR is NULL.
.AP int *boolPtr out
@@ -44,44 +39,57 @@ stores the boolean value (0 or 1) obtained from \fIobjPtr\fR.
.SH DESCRIPTION
.PP
-These procedures are used to create, modify, and read
-boolean Tcl objects from C code.
-\fBTcl_NewBooleanObj\fR and \fBTcl_SetBooleanObj\fR
-will create a new object of boolean type
-or modify an existing object to have boolean type.
-Both of these procedures set the object to have the
-boolean value (0 or 1) specified by \fIboolValue\fR;
-if \fIboolValue\fR is nonzero, the object is set to 1,
-otherwise to 0.
-\fBTcl_NewBooleanObj\fR returns a pointer to a newly created object
-with reference count zero.
-Both procedures set the object's type to be boolean
-and assign the boolean value to the object's internal representation
-\fIlongValue\fR member.
-\fBTcl_SetBooleanObj\fR invalidates any old string representation
-and, if the object is not already a boolean object,
-frees any old internal representation.
+These procedures are used to pass boolean values to and from
+Tcl as Tcl_Obj's. When storing a boolean value into a Tcl_Obj,
+any non-zero integer value in \fIboolValue\fR is taken to be
+the boolean value \fB1\fR, and the integer value \fB0\fR is
+taken to be the boolean value \fB0\fR.
.PP
-\fBTcl_GetBooleanFromObj\fR attempts to return a boolean value
-from the Tcl object \fIobjPtr\fR.
-If the object is not already a boolean object,
-it will attempt to convert it to one.
-If an error occurs during conversion, it returns \fBTCL_ERROR\fR
-and leaves an error message in the interpreter's result object
-unless \fIinterp\fR is NULL.
-Otherwise, \fBTcl_GetBooleanFromObj\fR returns \fBTCL_OK\fR
-and stores the boolean value in the address given by \fIboolPtr\fR.
-If the object is not already a boolean object,
-the conversion will free any old internal representation.
-Objects having a string representation equal to any of \fB0\fR,
-\fBfalse\fR, \fBno\fR, or \fBoff\fR have a boolean value 0; if the
-string representation is any of \fB1\fR, \fBtrue\fR, \fByes\fR, or
-\fBon\fR the boolean value is 1.
-Any of these string values may be abbreviated, and upper-case spellings
-are also acceptable.
+\fBTcl_NewBooleanObj\fR creates a new Tcl_Obj, stores the boolean
+value \fIboolValue\fR in it, and returns a pointer to the new Tcl_Obj.
+The new Tcl_Obj has reference count of zero.
+.PP
+\fBTcl_SetBooleanObj\fR accepts \fIobjPtr\fR, a pointer to
+an existing Tcl_Obj, and stores in the Tcl_Obj \fI*objPtr\fR
+the boolean value \fIboolValue\fR. This is a write operation
+on \fI*objPtr\fR, so \fIobjPtr\fR must be unshared. Attempts to
+write to a shared Tcl_Obj will panic. A successful write
+of \fIboolValue\fR into \fI*objPtr\fR implies the freeing of
+any former value stored in \fI*objPtr\fR.
+.PP
+\fBTcl_GetBooleanFromObj\fR attempts to retrieve a boolean value
+from the value stored in \fI*objPtr\fR.
+If \fIobjPtr\fR holds a string value recognized by \fBTcl_GetBoolean\fR,
+then the recognized boolean value is written at the address given
+by \fIboolPtr\fR.
+If \fIobjPtr\fR holds any value recognized as
+a number by Tcl, then if that value is zero a 0 is written at
+the address given by \fIboolPtr\fR and if that
+value is non-zero a 1 is written at the address given by \fIboolPtr\fR.
+In all cases where a value is written at the address given
+by \fIboolPtr\fR, \fBTcl_GetBooleanFromObj\fR returns \fBTCL_OK\fR.
+If the value of \fIobjPtr\fR does not meet any of the conditions
+above, then \fBTCL_ERROR\fR is returned and an error message is
+left in the interpreter's result unless \fIinterp\fR is NULL.
+\fBTcl_GetBooleanFromObj\fR may also make changes to the internal
+fields of \fI*objPtr\fR so that future calls to
+\fBTcl_GetBooleanFromObj\fR on the same \fIobjPtr\fR can be
+performed more efficiently.
+.PP
+Note that the routines \fBTcl_GetBooleanFromObj\fR and
+\fBTcl_GetBoolean\fR are not functional equivalents.
+The set of values for which \fBTcl_GetBooleanFromObj\fR
+will return \fBTCL_OK\fR is strictly larger than
+the set of values for which \fBTcl_GetBoolean\fR will do the same.
+For example, the value
+.QW 5
+passed to \fBTcl_GetBooleanFromObj\fR
+will lead to a \fBTCL_OK\fR return (and the boolean value 1),
+while the same value passed to \fBTcl_GetBoolean\fR will lead to
+a \fBTCL_ERROR\fR return.
.SH "SEE ALSO"
-Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
+Tcl_NewObj, Tcl_IsShared, Tcl_GetBoolean
.SH KEYWORDS
-boolean, boolean object, boolean type, internal representation, object, object type, string representation
+boolean, object
diff --git a/doc/ByteArrObj.3 b/doc/ByteArrObj.3
index 51c4363..738da32 100644
--- a/doc/ByteArrObj.3
+++ b/doc/ByteArrObj.3
@@ -25,8 +25,8 @@ unsigned char *
unsigned char *
\fBTcl_SetByteArrayLength\fR(\fIobjPtr, length\fR)
.SH ARGUMENTS
-.AS "unsigned char" *lengthPtr in/out
-.AP "CONST unsigned char" *bytes in
+.AS "const unsigned char" *lengthPtr in/out
+.AP "const unsigned char" *bytes in
The array of bytes used to initialize or set a byte-array object.
.AP int length in
The length of the array of bytes. It must be >= 0.
@@ -48,7 +48,7 @@ results of binary IO operations or data structures created with the
\fBbinary\fR command. In Tcl, an array of bytes is not equivalent to a
string. Conceptually, a string is an array of Unicode characters, while a
byte-array is an array of 8-bit quantities with no implicit meaning.
-Accesser functions are provided to get the string representation of a
+Accessor functions are provided to get the string representation of a
byte-array or to convert an arbitrary object to a byte-array. Obtaining the
string representation of a byte-array object (by calling
\fBTcl_GetStringFromObj\fR) produces a properly formed UTF-8 sequence with a
diff --git a/doc/CallDel.3 b/doc/CallDel.3
index 02bb445..8e6445b 100644
--- a/doc/CallDel.3
+++ b/doc/CallDel.3
@@ -38,8 +38,8 @@ time of the call.
type \fBTcl_InterpDeleteProc\fR:
.CS
typedef void Tcl_InterpDeleteProc(
- ClientData \fIclientData\fR,
- Tcl_Interp *\fIinterp\fR);
+ ClientData \fIclientData\fR,
+ Tcl_Interp *\fIinterp\fR);
.CE
The \fIclientData\fR and \fIinterp\fR parameters are
copies of the \fIclientData\fR and \fIinterp\fR arguments given
@@ -51,7 +51,7 @@ interpreter is about to go away.
.PP
\fBTcl_DontCallWhenDeleted\fR cancels a previous call to
\fBTcl_CallWhenDeleted\fR with the same arguments, so that
-\fIproc\fR won't be called after all when \fIinterp\fR is
+\fIproc\fR will not be called after all when \fIinterp\fR is
deleted.
If there is no deletion callback that matches \fIinterp\fR,
\fIproc\fR, and \fIclientData\fR then the call to
diff --git a/doc/ChnlStack.3 b/doc/ChnlStack.3
index ebd8d63..8ac5a0d 100644
--- a/doc/ChnlStack.3
+++ b/doc/ChnlStack.3
@@ -8,7 +8,7 @@
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
-Tcl_StackChannel, Tcl_UnstackChannel, Tcl_GetStackedChannel, Tcl_GetTopChannel \- stack an I/O channel on top of another, and undo it
+Tcl_StackChannel, Tcl_UnstackChannel, Tcl_GetStackedChannel, Tcl_GetTopChannel \- manipulate stacked I/O channels
.SH SYNOPSIS
.nf
.nf
@@ -27,17 +27,17 @@ Tcl_Channel
\fBTcl_GetTopChannel\fR(\fIchannel\fR)
.sp
.SH ARGUMENTS
-.AS Tcl_ChannelType
+.AS Tcl_ChannelType clientData
.AP Tcl_Interp *interp in
Interpreter for error reporting.
.AP Tcl_ChannelType *typePtr in
-The new channel I/O procedures to use for \fIchannel\fP.
+The new channel I/O procedures to use for \fIchannel\fR.
.AP ClientData clientData in
Arbitrary one-word value to pass to channel I/O procedures.
.AP int mask in
Conditions under which \fIchannel\fR will be used: OR-ed combination of
\fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR and \fBTCL_EXCEPTION\fR.
-This can be a subset of the operations currently allowed on \fIchannel\fP.
+This can be a subset of the operations currently allowed on \fIchannel\fR.
.AP Tcl_Channel channel in
An existing Tcl channel such as returned by \fBTcl_CreateChannel\fR.
.BE
@@ -55,9 +55,9 @@ stacked channels. Anyone using stacked channels or creating stacked
channel drivers should update to the new \fBTCL_CHANNEL_VERSION_2\fR
\fBTcl_ChannelType\fR structure. See \fBTcl_CreateChannel\fR for details.
.PP
-\fBTcl_StackChannel\fR stacks a new \fIchannel\fP on an existing channel
-with the same name that was registered for \fIchannel\fP by
-\fBTcl_RegisterChannel\fP.
+\fBTcl_StackChannel\fR stacks a new \fIchannel\fR on an existing channel
+with the same name that was registered for \fIchannel\fR by
+\fBTcl_RegisterChannel\fR.
.PP
\fBTcl_StackChannel\fR works by creating a new channel structure and
placing itself on top of the channel stack. EOL translation, encoding and
@@ -68,7 +68,7 @@ remain at the top of the channel stack. A pointer to the new top channel
structure is returned. If an error occurs when stacking the channel, NULL
is returned instead.
.PP
-The \fImask\fP parameter specifies the operations that are allowed on the
+The \fImask\fR parameter specifies the operations that are allowed on the
new channel. These can be a subset of the operations allowed on the
original channel. For example, a read-write channel may become read-only
after the \fBTcl_StackChannel\fR call.
@@ -77,10 +77,10 @@ Closing a channel closes the channels stacked below it. The close of
stacked channels is executed in a way that allows buffered data to be
properly flushed.
.PP
-\fBTcl_UnstackChannel\fP reverses the process. The old channel is
+\fBTcl_UnstackChannel\fR reverses the process. The old channel is
associated with the channel name, and the processing module added by
\fBTcl_StackChannel\fR is destroyed. If there is no old channel, then
-\fBTcl_UnstackChannel\fP is equivalent to \fBTcl_Close\fP. If an error
+\fBTcl_UnstackChannel\fR is equivalent to \fBTcl_Close\fR. If an error
occurs unstacking the channel, \fBTCL_ERROR\fR is returned, otherwise
\fBTCL_OK\fR is returned.
.PP
diff --git a/doc/CmdCmplt.3 b/doc/CmdCmplt.3
index e2a7064..eeae039 100644
--- a/doc/CmdCmplt.3
+++ b/doc/CmdCmplt.3
@@ -17,8 +17,8 @@ Tcl_CommandComplete \- Check for unmatched braces in a Tcl command
int
\fBTcl_CommandComplete\fR(\fIcmd\fR)
.SH ARGUMENTS
-.AS "CONST char" *cmd
-.AP "CONST char" *cmd in
+.AS "const char" *cmd
+.AP "const char" *cmd in
Command string to test for completeness.
.BE
diff --git a/doc/Concat.3 b/doc/Concat.3
index fdb479e..c38bf82 100644
--- a/doc/Concat.3
+++ b/doc/Concat.3
@@ -14,12 +14,13 @@ Tcl_Concat \- concatenate a collection of strings
.nf
\fB#include <tcl.h>\fR
.sp
-CONST char *
+const char *
\fBTcl_Concat\fR(\fIargc, argv\fR)
.SH ARGUMENTS
+.AS "const char *const" argv[]
.AP int argc in
Number of strings.
-.AP "CONST char * CONST" argv[] in
+.AP "const char *const" argv[] in
Array of strings to concatenate. Must have \fIargc\fR entries.
.BE
@@ -41,12 +42,9 @@ copies strings from \fBargv\fR to the result. If an element of
is ignored entirely. This white-space removal was added to make
the output of the \fBconcat\fR command cleaner-looking.
.PP
-.VS
The result string is dynamically allocated
using \fBTcl_Alloc\fR; the caller must eventually release the space
by calling \fBTcl_Free\fR.
-.VE
-.VS
.SH "SEE ALSO"
Tcl_ConcatObj
.SH KEYWORDS
diff --git a/doc/CrtChannel.3 b/doc/CrtChannel.3
index fc034a0..212a239 100644
--- a/doc/CrtChannel.3
+++ b/doc/CrtChannel.3
@@ -9,7 +9,7 @@
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
-Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType, Tcl_GetChannelName, Tcl_GetChannelHandle, Tcl_GetChannelMode, Tcl_GetChannelBufferSize, Tcl_SetChannelBufferSize, Tcl_NotifyChannel, Tcl_BadChannelOption, Tcl_ChannelName, Tcl_ChannelVersion, Tcl_ChannelBlockModeProc, Tcl_ChannelCloseProc, Tcl_ChannelClose2Proc, Tcl_ChannelInputProc, Tcl_ChannelOutputProc, Tcl_ChannelSeekProc, Tcl_ChannelWideSeekProc, Tcl_ChannelSetOptionProc, Tcl_ChannelGetOptionProc, Tcl_ChannelWatchProc, Tcl_ChannelGetHandleProc, Tcl_ChannelFlushProc, Tcl_ChannelHandlerProc, Tcl_ChannelThreadActionProc, Tcl_IsChannelShared, Tcl_IsChannelRegistered, Tcl_CutChannel, Tcl_SpliceChannel, Tcl_IsChannelExisting, Tcl_ClearChannelHandlers, Tcl_GetChannelThread, Tcl_ChannelBuffered \- procedures for creating and manipulating channels
+Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType, Tcl_GetChannelName, Tcl_GetChannelHandle, Tcl_GetChannelMode, Tcl_GetChannelBufferSize, Tcl_SetChannelBufferSize, Tcl_NotifyChannel, Tcl_BadChannelOption, Tcl_ChannelName, Tcl_ChannelVersion, Tcl_ChannelBlockModeProc, Tcl_ChannelCloseProc, Tcl_ChannelClose2Proc, Tcl_ChannelInputProc, Tcl_ChannelOutputProc, Tcl_ChannelSeekProc, Tcl_ChannelWideSeekProc, Tcl_ChannelTruncateProc, Tcl_ChannelSetOptionProc, Tcl_ChannelGetOptionProc, Tcl_ChannelWatchProc, Tcl_ChannelGetHandleProc, Tcl_ChannelFlushProc, Tcl_ChannelHandlerProc, Tcl_ChannelThreadActionProc, Tcl_IsChannelShared, Tcl_IsChannelRegistered, Tcl_CutChannel, Tcl_SpliceChannel, Tcl_IsChannelExisting, Tcl_ClearChannelHandlers, Tcl_GetChannelThread, Tcl_ChannelBuffered \- procedures for creating and manipulating channels
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
@@ -23,16 +23,14 @@ ClientData
Tcl_ChannelType *
\fBTcl_GetChannelType\fR(\fIchannel\fR)
.sp
-CONST char *
+const char *
\fBTcl_GetChannelName\fR(\fIchannel\fR)
.sp
int
\fBTcl_GetChannelHandle\fR(\fIchannel, direction, handlePtr\fR)
.sp
-.VS 8.4
Tcl_ThreadId
\fBTcl_GetChannelThread\fR(\fIchannel\fR)
-.VE 8.4
.sp
int
\fBTcl_GetChannelMode\fR(\fIchannel\fR)
@@ -46,7 +44,6 @@ int
.sp
int
\fBTcl_BadChannelOption\fR(\fIinterp, optionName, optionList\fR)
-.VS 8.4
.sp
int
\fBTcl_IsChannelShared\fR(\fIchannel\fR)
@@ -65,12 +62,11 @@ void
.sp
void
\fBTcl_ClearChannelHandlers\fR(\fIchannel\fR)
-.VE 8.4
.sp
int
\fBTcl_ChannelBuffered\fR(\fIchannel\fR)
.sp
-CONST char *
+const char *
\fBTcl_ChannelName\fR(\fItypePtr\fR)
.sp
Tcl_ChannelTypeVersion
@@ -94,13 +90,16 @@ Tcl_DriverOutputProc *
Tcl_DriverSeekProc *
\fBTcl_ChannelSeekProc\fR(\fItypePtr\fR)
.sp
-.VS 8.4
Tcl_DriverWideSeekProc *
\fBTcl_ChannelWideSeekProc\fR(\fItypePtr\fR)
.sp
Tcl_DriverThreadActionProc *
\fBTcl_ChannelThreadActionProc\fR(\fItypePtr\fR)
-.VE 8.4
+.sp
+.VS 8.5
+Tcl_DriverTruncateProc *
+\fBTcl_ChannelTruncateProc\fR(\fItypePtr\fR)
+.VE 8.5
.sp
Tcl_DriverSetOptionProc *
\fBTcl_ChannelSetOptionProc\fR(\fItypePtr\fR)
@@ -121,11 +120,11 @@ Tcl_DriverHandlerProc *
\fBTcl_ChannelHandlerProc\fR(\fItypePtr\fR)
.sp
.SH ARGUMENTS
-.AS Tcl_ChannelType *channelName in
-.AP Tcl_ChannelType *typePtr in
+.AS "const Tcl_ChannelType" *channelName
+.AP "const Tcl_ChannelType" *typePtr in
Points to a structure containing the addresses of procedures that
can be called to perform I/O and other functions on the channel.
-.AP "CONST char" *channelName in
+.AP "const char" *channelName in
The name of this channel, such as \fBfile3\fR; must not be in use
by any other channel. Can be NULL, in which case the channel is
created without a name.
@@ -151,10 +150,11 @@ and \fBTCL_EXCEPTION\fR that indicates events that have occurred on
this channel.
.AP Tcl_Interp *interp in
Current interpreter. (can be NULL)
-.AP "CONST char" *optionName in
+.AP "const char" *optionName in
Name of the invalid option.
-.AP "CONST char" *optionList in
-Specific options list (space separated words, without "-")
+.AP "const char" *optionList in
+Specific options list (space separated words, without
+.QW \- )
to append to the standard generic options list.
Can be NULL for generic options error message only.
@@ -178,7 +178,7 @@ driver provides a \fBTcl_ChannelType\fR structure containing pointers to
functions implementing the various operations used by the generic layer to
communicate with the channel driver. The \fBTcl_ChannelType\fR structure
and the functions referenced by it are described in the section
-TCL_CHANNELTYPE, below.
+\fBTCL_CHANNELTYPE\fR, below.
.PP
Second, channel drivers usually provide a Tcl command to create
instances of that type of channel. For example, the Tcl \fBopen\fR
@@ -205,7 +205,7 @@ structure to perform operations on the channel.
\fItypePtr\fR and \fIinstanceData\fR with it. The channel is opened in the
mode indicated by \fImask\fR.
For a discussion of channel drivers, their operations and the
-\fBTcl_ChannelType\fR structure, see the section TCL_CHANNELTYPE, below.
+\fBTcl_ChannelType\fR structure, see the section \fBTCL_CHANNELTYPE\fR, below.
.PP
\fBTcl_CreateChannel\fR interacts with the code managing the standard
channels. Once a standard channel was initialized either through a
@@ -237,11 +237,9 @@ then \fBTCL_ERROR\fR is returned instead. Different channel drivers
will return different types of handle. Refer to the manual entries
for each driver to determine what type of handle is returned.
.PP
-.VS 8.4
\fBTcl_GetChannelThread\fR returns the id of the thread currently managing
the specified \fIchannel\fR. This allows channel drivers to send their file
events to the correct event queue even for a multi-threaded core.
-.VE 8.4
.PP
\fBTcl_GetChannelMode\fR returns an OR-ed combination of \fBTCL_READABLE\fR
and \fBTCL_WRITABLE\fR, indicating whether the channel is open for input
@@ -265,15 +263,15 @@ occurred on the channel. Channel drivers are responsible for invoking
this function whenever the channel handlers need to be called for the
channel. See \fBWATCHPROC\fR below for more details.
.PP
-\fBTcl_BadChannelOption\fR is called from driver specific set or get option
-procs to generate a complete error message.
+\fBTcl_BadChannelOption\fR is called from driver specific
+\fIsetOptionProc\fR or \fIgetOptionProc\fR to generate a complete
+error message.
.PP
\fBTcl_ChannelBuffered\fR returns the number of bytes of input
currently buffered in the internal buffer (push back area) of the
channel itself. It does not report about the data in the overall
buffers for the stack of channels the supplied channel is part of.
.PP
-.VS 8.4
\fBTcl_IsChannelShared\fR checks the refcount of the specified
\fIchannel\fR and returns whether the \fIchannel\fR was shared among
multiple interpreters (result == 1) or not (result == 0).
@@ -290,26 +288,24 @@ name is registered in the (thread)-global list of all channels (result
(thread)global list of all channels (of the current thread).
Application to a channel still registered in some interpreter
is not allowed.
-.VS 8.4
+.VS 8.5
Also notifies the driver if the \fBTcl_ChannelType\fR version is
\fBTCL_CHANNEL_VERSION_4\fR (or higher), and
\fBTcl_DriverThreadActionProc\fR is defined for it.
-.VE 8.4
+.VE 8.5
.PP
\fBTcl_SpliceChannel\fR adds the specified \fIchannel\fR to the
(thread)global list of all channels (of the current thread).
Application to a channel registered in some interpreter is not allowed.
-.VS 8.4
+.VS 8.5
Also notifies the driver if the \fBTcl_ChannelType\fR version is
\fBTCL_CHANNEL_VERSION_4\fR (or higher), and
\fBTcl_DriverThreadActionProc\fR is defined for it.
-.VE 8.4
+.VE 8.5
.PP
-\fBTcl_ClearChannelHandlers\fR removes all channelhandlers and event
+\fBTcl_ClearChannelHandlers\fR removes all channel handlers and event
scripts associated with the specified \fIchannel\fR, thus shutting
down all event processing for this channel.
-.VE 8.4
-
.SH TCL_CHANNELTYPE
.PP
A channel driver provides a \fBTcl_ChannelType\fR structure that contains
@@ -322,22 +318,25 @@ details about the old structure.
The \fBTcl_ChannelType\fR structure contains the following fields:
.CS
typedef struct Tcl_ChannelType {
- char *\fItypeName\fR;
- Tcl_ChannelTypeVersion \fIversion\fR;
- Tcl_DriverCloseProc *\fIcloseProc\fR;
- Tcl_DriverInputProc *\fIinputProc\fR;
- Tcl_DriverOutputProc *\fIoutputProc\fR;
- Tcl_DriverSeekProc *\fIseekProc\fR;
- Tcl_DriverSetOptionProc *\fIsetOptionProc\fR;
- Tcl_DriverGetOptionProc *\fIgetOptionProc\fR;
- Tcl_DriverWatchProc *\fIwatchProc\fR;
- Tcl_DriverGetHandleProc *\fIgetHandleProc\fR;
- Tcl_DriverClose2Proc *\fIclose2Proc\fR;
- Tcl_DriverBlockModeProc *\fIblockModeProc\fR;
- Tcl_DriverFlushProc *\fIflushProc\fR;
- Tcl_DriverHandlerProc *\fIhandlerProc\fR;
- Tcl_DriverWideSeekProc *\fIwideSeekProc\fR;
- Tcl_DriverThreadActionProc *\fIthreadActionProc\fR;
+ char *\fItypeName\fR;
+ Tcl_ChannelTypeVersion \fIversion\fR;
+ Tcl_DriverCloseProc *\fIcloseProc\fR;
+ Tcl_DriverInputProc *\fIinputProc\fR;
+ Tcl_DriverOutputProc *\fIoutputProc\fR;
+ Tcl_DriverSeekProc *\fIseekProc\fR;
+ Tcl_DriverSetOptionProc *\fIsetOptionProc\fR;
+ Tcl_DriverGetOptionProc *\fIgetOptionProc\fR;
+ Tcl_DriverWatchProc *\fIwatchProc\fR;
+ Tcl_DriverGetHandleProc *\fIgetHandleProc\fR;
+ Tcl_DriverClose2Proc *\fIclose2Proc\fR;
+ Tcl_DriverBlockModeProc *\fIblockModeProc\fR;
+ Tcl_DriverFlushProc *\fIflushProc\fR;
+ Tcl_DriverHandlerProc *\fIhandlerProc\fR;
+ Tcl_DriverWideSeekProc *\fIwideSeekProc\fR;
+ Tcl_DriverThreadActionProc *\fIthreadActionProc\fR;
+.VS 8.5
+ Tcl_DriverTruncateProc *\fItruncateProc\fR;
+.VE 8.5
} Tcl_ChannelType;
.CE
.PP
@@ -345,11 +344,11 @@ It is not necessary to provide implementations for all channel
operations. Those which are not necessary may be set to NULL in the
struct: \fIblockModeProc\fR, \fIseekProc\fR, \fIsetOptionProc\fR,
\fIgetOptionProc\fR, and \fIclose2Proc\fR, in addition to
-\fIflushProc\fR, \fIhandlerProc\fR, and \fIthreadActionProc\fR. Other
-functions that cannot be implemented in a meaningful way should return
-\fBEINVAL\fR when called, to indicate that the operations they
-represent are not available. Also note that \fIwideSeekProc\fR can be
-NULL if \fIseekProc\fR is.
+\fIflushProc\fR, \fIhandlerProc\fR, \fIthreadActionProc\fR, and
+\fItruncateProc\fR. Other functions that cannot be implemented in a
+meaningful way should return \fBEINVAL\fR when called, to indicate
+that the operations they represent are not available. Also note that
+\fIwideSeekProc\fR can be NULL if \fIseekProc\fR is.
.PP
The user should only use the above structure for \fBTcl_ChannelType\fR
instantiation. When referencing fields in a \fBTcl_ChannelType\fR
@@ -358,20 +357,19 @@ structure, the following functions should be used to obtain the values:
\fBTcl_ChannelBlockModeProc\fR, \fBTcl_ChannelCloseProc\fR,
\fBTcl_ChannelClose2Proc\fR, \fBTcl_ChannelInputProc\fR,
\fBTcl_ChannelOutputProc\fR, \fBTcl_ChannelSeekProc\fR,
-.VS 8.4
-\fBTcl_ChannelWideSeekProc\fR,
-\fBTcl_ChannelThreadActionProc\fR,
-.VE 8.4
+\fBTcl_ChannelWideSeekProc\fR, \fBTcl_ChannelThreadActionProc\fR,
+.VS 8.5
+\fBTcl_ChannelTruncateProc\fR,
+.VE 8.5
\fBTcl_ChannelSetOptionProc\fR, \fBTcl_ChannelGetOptionProc\fR,
\fBTcl_ChannelWatchProc\fR, \fBTcl_ChannelGetHandleProc\fR,
\fBTcl_ChannelFlushProc\fR, or \fBTcl_ChannelHandlerProc\fR.
.PP
The change to the structures was made in such a way that standard channel
types are binary compatible. However, channel types that use stacked
-channels (ie: TLS, Trf) have new versions to correspond to the above change
+channels (i.e. TLS, Trf) have new versions to correspond to the above change
since the previous code for stacked channels had problems.
-
-.SH TYPENAME
+.SS TYPENAME
.PP
The \fItypeName\fR field contains a null-terminated string that
identifies the type of the device implemented by this driver, e.g.
@@ -379,19 +377,19 @@ identifies the type of the device implemented by this driver, e.g.
.PP
This value can be retrieved with \fBTcl_ChannelName\fR, which returns
a pointer to the string.
-
-.SH VERSION
+.SS VERSION
.PP
The \fIversion\fR field should be set to the version of the structure
that you require. \fBTCL_CHANNEL_VERSION_2\fR is the minimum recommended.
-.VS 8.4
-\fBTCL_CHANNEL_VERSION_3\fR must be set to specifiy the \fIwideSeekProc\fR member.
-.VE 8.4
-.VS 8.4
-\fBTCL_CHANNEL_VERSION_4\fR must be set to specifiy the
-\fIthreadActionProc\fR member (includes \fIwideSeekProc\fR).
-.VE 8.4
+\fBTCL_CHANNEL_VERSION_3\fR must be set to specify the \fIwideSeekProc\fR member.
+\fBTCL_CHANNEL_VERSION_4\fR must be set to specify the \fIthreadActionProc\fR member
+(includes \fIwideSeekProc\fR).
+.VS 8.5
+\fBTCL_CHANNEL_VERSION_5\fR must be set to specify the
+\fItruncateProc\fR members (includes
+\fIwideSeekProc\fR and \fIthreadActionProc\fR).
+.VE 8.5
If it is not set to any of these, then this
\fBTcl_ChannelType\fR is assumed to have the original structure. See
\fBOLD CHANNEL TYPES\fR for more details. While Tcl will recognize
@@ -399,12 +397,14 @@ and function with either structures, stacked channels must be of at
least \fBTCL_CHANNEL_VERSION_2\fR to function correctly.
.PP
This value can be retrieved with \fBTcl_ChannelVersion\fR, which returns
-.VS 8.4
-one of \fBTCL_CHANNEL_VERSION_4\fR, \fBTCL_CHANNEL_VERSION_3\fR,
-.VE 8.4
-\fBTCL_CHANNEL_VERSION_2\fR, or \fBTCL_CHANNEL_VERSION_1\fR.
-
-.SH BLOCKMODEPROC
+one of
+.VS 8.5
+\fBTCL_CHANNEL_VERSION_5\fR,
+.VE 8.5
+\fBTCL_CHANNEL_VERSION_4\fR,
+\fBTCL_CHANNEL_VERSION_3\fR,
+\fBTCL_CHANNEL_VERSION_2\fR or \fBTCL_CHANNEL_VERSION_1\fR.
+.SS BLOCKMODEPROC
.PP
The \fIblockModeProc\fR field contains the address of a function called by
the generic layer to set blocking and nonblocking mode on the device.
@@ -412,8 +412,8 @@ the generic layer to set blocking and nonblocking mode on the device.
.PP
.CS
typedef int Tcl_DriverBlockModeProc(
- ClientData \fIinstanceData\fR,
- int \fImode\fR);
+ ClientData \fIinstanceData\fR,
+ int \fImode\fR);
.CE
.PP
The \fIinstanceData\fR is the same as the value passed to
@@ -437,11 +437,9 @@ A channel driver \fBnot\fR supplying a \fIblockModeProc\fR has to be
very, very careful. It has to tell the generic layer exactly which
blocking mode is acceptable to it, and should this also document for
the user so that the blocking mode of the channel is not changed to an
-inacceptable value. Any confusion here may lead the interpreter into a
+unacceptable value. Any confusion here may lead the interpreter into a
(spurious and difficult to find) deadlock.
-
-
-.SH "CLOSEPROC AND CLOSE2PROC"
+.SS "CLOSEPROC AND CLOSE2PROC"
.PP
The \fIcloseProc\fR field contains the address of a function called by the
generic layer to clean up driver-related information when the channel is
@@ -449,8 +447,8 @@ closed. \fICloseProc\fR must match the following prototype:
.PP
.CS
typedef int Tcl_DriverCloseProc(
- ClientData \fIinstanceData\fR,
- Tcl_Interp *\fIinterp\fR);
+ ClientData \fIinstanceData\fR,
+ Tcl_Interp *\fIinterp\fR);
.CE
.PP
The \fIinstanceData\fR argument is the same as the value provided to
@@ -471,9 +469,9 @@ following prototype:
.PP
.CS
typedef int Tcl_DriverClose2Proc(
- ClientData \fIinstanceData\fR,
- Tcl_Interp *\fIinterp\fR,
- int \fIflags\fR);
+ ClientData \fIinstanceData\fR,
+ Tcl_Interp *\fIinterp\fR,
+ int \fIflags\fR);
.CE
.PP
The \fIclose2Proc\fR will be called with \fIflags\fR set to an OR'ed
@@ -491,11 +489,10 @@ return a nonzero POSIX error code. In addition, if an error occurs and
\fIinterp\fR is not NULL, the procedure should store an error message
in the interpreter's result.
.PP
-These value can be retrieved with \fBTcl_ChannelCloseProc\fR or
-\fBTcl_ChannelClose2Proc\fR, which returns a pointer to the respective
-function.
-
-.SH INPUTPROC
+The \fIcloseProc\fR and \fIclose2Proc\fR values can be retrieved with
+\fBTcl_ChannelCloseProc\fR or \fBTcl_ChannelClose2Proc\fR, which
+return a pointer to the respective function.
+.SS INPUTPROC
.PP
The \fIinputProc\fR field contains the address of a function called by the
generic layer to read data from the file or device and store it in an
@@ -503,10 +500,10 @@ internal buffer. \fIInputProc\fR must match the following prototype:
.PP
.CS
typedef int Tcl_DriverInputProc(
- ClientData \fIinstanceData\fR,
- char *\fIbuf\fR,
- int \fIbufSize\fR,
- int *\fIerrorCodePtr\fR);
+ ClientData \fIinstanceData\fR,
+ char *\fIbuf\fR,
+ int \fIbufSize\fR,
+ int *\fIerrorCodePtr\fR);
.CE
.PP
\fIInstanceData\fR is the same as the value passed to
@@ -539,8 +536,7 @@ blocking.
.PP
This value can be retrieved with \fBTcl_ChannelInputProc\fR, which returns
a pointer to the function.
-
-.SH OUTPUTPROC
+.SS OUTPUTPROC
.PP
The \fIoutputProc\fR field contains the address of a function called by the
generic layer to transfer data from an internal buffer to the output device.
@@ -548,10 +544,10 @@ generic layer to transfer data from an internal buffer to the output device.
.PP
.CS
typedef int Tcl_DriverOutputProc(
- ClientData \fIinstanceData\fR,
- CONST char *\fIbuf\fR,
- int \fItoWrite\fR,
- int *\fIerrorCodePtr\fR);
+ ClientData \fIinstanceData\fR,
+ const char *\fIbuf\fR,
+ int \fItoWrite\fR,
+ int *\fIerrorCodePtr\fR);
.CE
.PP
\fIInstanceData\fR is the same as the value passed to
@@ -578,8 +574,7 @@ without writing any data.
.PP
This value can be retrieved with \fBTcl_ChannelOutputProc\fR, which returns
a pointer to the function.
-
-.SH "SEEKPROC AND WIDESEEKPROC"
+.SS "SEEKPROC AND WIDESEEKPROC"
.PP
The \fIseekProc\fR field contains the address of a function called by the
generic layer to move the access point at which subsequent input or output
@@ -588,10 +583,10 @@ prototype:
.PP
.CS
typedef int Tcl_DriverSeekProc(
- ClientData \fIinstanceData\fR,
- long \fIoffset\fR,
- int \fIseekMode\fR,
- int *\fIerrorCodePtr\fR);
+ ClientData \fIinstanceData\fR,
+ long \fIoffset\fR,
+ int \fIseekMode\fR,
+ int *\fIerrorCodePtr\fR);
.CE
.PP
The \fIinstanceData\fR argument is the same as the value given to
@@ -608,7 +603,6 @@ does not implement seeking.
The return value is the new access point or -1 in case of error. If an
error occurred, the function should not move the access point.
.PP
-.VS 8.4
If there is a non-NULL \fIseekProc\fR field, the \fIwideSeekProc\fR
field may contain the address of an alternative function to use which
handles wide (i.e. larger than 32-bit) offsets, so allowing seeks
@@ -619,10 +613,10 @@ following prototype:
.PP
.CS
typedef Tcl_WideInt Tcl_DriverWideSeekProc(
- ClientData \fIinstanceData\fR,
- Tcl_WideInt \fIoffset\fR,
- int \fIseekMode\fR,
- int *\fIerrorCodePtr\fR);
+ ClientData \fIinstanceData\fR,
+ Tcl_WideInt \fIoffset\fR,
+ int \fIseekMode\fR,
+ int *\fIerrorCodePtr\fR);
.CE
.PP
The arguments and return values mean the same thing as with
@@ -633,9 +627,7 @@ The \fIseekProc\fR value can be retrieved with
\fBTcl_ChannelSeekProc\fR, which returns a pointer to the function,
and similarly the \fIwideSeekProc\fR can be retrieved with
\fBTcl_ChannelWideSeekProc\fR.
-.VE 8.4
-
-.SH SETOPTIONPROC
+.SS SETOPTIONPROC
.PP
The \fIsetOptionProc\fR field contains the address of a function called by
the generic layer to set a channel type specific option on a channel.
@@ -643,10 +635,10 @@ the generic layer to set a channel type specific option on a channel.
.PP
.CS
typedef int Tcl_DriverSetOptionProc(
- ClientData \fIinstanceData\fR,
- Tcl_Interp *\fIinterp\fR,
- CONST char *\fIoptionName\fR,
- CONST char *\fInewValue\fR);
+ ClientData \fIinstanceData\fR,
+ Tcl_Interp *\fIinterp\fR,
+ const char *\fIoptionName\fR,
+ const char *\fInewValue\fR);
.CE
.PP
\fIoptionName\fR is the name of an option to set, and \fInewValue\fR is
@@ -656,7 +648,7 @@ created. The function should do whatever channel type specific action is
required to implement the new value of the option.
.PP
Some options are handled by the generic code and this function is never
-called to set them, e.g. \fB-blockmode\fR. Other options are specific to
+called to set them, e.g. \fB\-blockmode\fR. Other options are specific to
each channel type and the \fIsetOptionProc\fR procedure of the channel
driver will get called to implement them. The \fIsetOptionProc\fR field can
be NULL, which indicates that this channel type supports no type specific
@@ -676,8 +668,7 @@ error code.
.PP
This value can be retrieved with \fBTcl_ChannelSetOptionProc\fR, which returns
a pointer to the function.
-
-.SH GETOPTIONPROC
+.SS GETOPTIONPROC
.PP
The \fIgetOptionProc\fR field contains the address of a function called by
the generic layer to get the value of a channel type specific option on a
@@ -685,10 +676,10 @@ channel. \fIgetOptionProc\fR must match the following prototype:
.PP
.CS
typedef int Tcl_DriverGetOptionProc(
- ClientData \fIinstanceData\fR,
- Tcl_Interp *\fIinterp\fR,
- CONST char *\fIoptionName\fR,
- Tcl_DString *\fIoptionValue\fR);
+ ClientData \fIinstanceData\fR,
+ Tcl_Interp *\fIinterp\fR,
+ const char *\fIoptionName\fR,
+ Tcl_DString *\fIoptionValue\fR);
.CE
.PP
\fIOptionName\fR is the name of an option supported by this type of
@@ -706,7 +697,7 @@ function should also call \fBTcl_SetErrno\fR to store an appropriate POSIX
error code.
.PP
Some options are handled by the generic code and this function is never
-called to retrieve their value, e.g. \fB-blockmode\fR. Other options are
+called to retrieve their value, e.g. \fB\-blockmode\fR. Other options are
specific to each channel type and the \fIgetOptionProc\fR procedure of the
channel driver will get called to implement them. The \fIgetOptionProc\fR
field can be NULL, which indicates that this channel type supports no type
@@ -714,8 +705,7 @@ specific options.
.PP
This value can be retrieved with \fBTcl_ChannelGetOptionProc\fR, which returns
a pointer to the function.
-
-.SH WATCHPROC
+.SS WATCHPROC
.PP
The \fIwatchProc\fR field contains the address of a function called
by the generic layer to initialize the event notification mechanism to
@@ -724,8 +714,8 @@ notice events of interest on this channel.
.PP
.CS
typedef void Tcl_DriverWatchProc(
- ClientData \fIinstanceData\fR,
- int \fImask\fR);
+ ClientData \fIinstanceData\fR,
+ int \fImask\fR);
.CE
.PP
The \fIinstanceData\fR is the same as the value passed to
@@ -747,8 +737,7 @@ details on how to queue an event.
.PP
This value can be retrieved with \fBTcl_ChannelWatchProc\fR, which returns
a pointer to the function.
-
-.SH GETHANDLEPROC
+.SS GETHANDLEPROC
.PP
The \fIgetHandleProc\fR field contains the address of a function called by
the generic layer to retrieve a device-specific handle from the channel.
@@ -756,9 +745,9 @@ the generic layer to retrieve a device-specific handle from the channel.
.PP
.CS
typedef int Tcl_DriverGetHandleProc(
- ClientData \fIinstanceData\fR,
- int \fIdirection\fR,
- ClientData *\fIhandlePtr\fR);
+ ClientData \fIinstanceData\fR,
+ int \fIdirection\fR,
+ ClientData *\fIhandlePtr\fR);
.CE
.PP
\fIInstanceData\fR is the same as the value passed to
@@ -777,8 +766,7 @@ device handles, the function should return \fBTCL_ERROR\fR.
.PP
This value can be retrieved with \fBTcl_ChannelGetHandleProc\fR, which returns
a pointer to the function.
-
-.SH FLUSHPROC
+.SS FLUSHPROC
.PP
The \fIflushProc\fR field is currently reserved for future use.
It should be set to NULL.
@@ -786,13 +774,12 @@ It should be set to NULL.
.PP
.CS
typedef int Tcl_DriverFlushProc(
- ClientData \fIinstanceData\fR);
+ ClientData \fIinstanceData\fR);
.CE
.PP
This value can be retrieved with \fBTcl_ChannelFlushProc\fR, which returns
a pointer to the function.
-
-.SH HANDLERPROC
+.SS HANDLERPROC
.PP
The \fIhandlerProc\fR field contains the address of a function called by
the generic layer to notify the channel that an event occurred. It should
@@ -802,8 +789,8 @@ that occur on the underlying (stacked) channel.
.PP
.CS
typedef int Tcl_DriverHandlerProc(
- ClientData \fIinstanceData\fR,
- int \fIinterestMask\fR);
+ ClientData \fIinstanceData\fR,
+ int \fIinterestMask\fR);
.CE
.PP
\fIInstanceData\fR is the same as the value passed to \fBTcl_CreateChannel\fR
@@ -814,8 +801,7 @@ type of event occurred on this channel.
This value can be retrieved with \fBTcl_ChannelHandlerProc\fR, which returns
a pointer to the function.
-.VS 8.4
-.SH "THREADACTIONPROC"
+.SS "THREADACTIONPROC"
.PP
The \fIthreadActionProc\fR field contains the address of the function
called by the generic layer when a channel is created, closed, or
@@ -832,8 +818,8 @@ might be maintaining using the calling thread as the associate. See
.PP
.CS
typedef void Tcl_DriverThreadActionProc(
- ClientData \fIinstanceData\fR,
- int \fIaction\fR);
+ ClientData \fIinstanceData\fR,
+ int \fIaction\fR);
.CE
.PP
\fIInstanceData\fR is the same as the value passed to
@@ -841,53 +827,79 @@ typedef void Tcl_DriverThreadActionProc(
.PP
These values can be retrieved with \fBTcl_ChannelThreadActionProc\fR,
which returns a pointer to the function.
-.VE 8.4
-
+.SS "TRUNCATEPROC"
+.PP
+The \fItruncateProc\fR field contains the address of the function
+called by the generic layer when a channel is truncated to some
+length. It can be NULL.
+.PP
+.CS
+typedef int Tcl_DriverTruncateProc(
+ ClientData \fIinstanceData\fR,
+ Tcl_WideInt \fIlength\fR);
+.CE
+.PP
+\fIInstanceData\fR is the same as the value passed to
+\fBTcl_CreateChannel\fR when this channel was created, and
+\fIlength\fR is the new length of the underlying file, which should
+not be negative. The result should be 0 on success or an errno code
+(suitable for use with \fBTcl_SetErrno\fR) on failure.
+.PP
+These values can be retrieved with \fBTcl_ChannelTruncateProc\fR,
+which returns a pointer to the function.
.SH TCL_BADCHANNELOPTION
.PP
-This procedure generates a "bad option" error message in an
+This procedure generates a
+.QW "bad option"
+error message in an
(optional) interpreter. It is used by channel drivers when
-a invalid Set/Get option is requested. Its purpose is to concatenate
+an invalid Set/Get option is requested. Its purpose is to concatenate
the generic options list to the specific ones and factorize
the generic options error message string.
.PP
-It always return \fBTCL_ERROR\fR
+It always returns \fBTCL_ERROR\fR
.PP
An error message is generated in \fIinterp\fR's result object to
-indicate that a command was invoked with the a bad option
+indicate that a command was invoked with a bad option.
The message has the form
.CS
bad option "blah": should be one of
<...generic options...>+<...specific options...>
+.CE
so you get for instance:
+.CS
bad option "-blah": should be one of -blocking,
-buffering, -buffersize, -eofchar, -translation,
-peername, or -sockname
-when called with \fIoptionList\fR="peername sockname"
.CE
-``blah'' is the \fIoptionName\fR argument and ``<specific options>''
+when called with \fIoptionList\fR equal to
+.QW "peername sockname"
+.PP
+.QW blah
+is the \fIoptionName\fR argument and
+.QW "<specific options>"
is a space separated list of specific option words.
The function takes good care of inserting minus signs before
-each option, commas after, and an ``or'' before the last option.
-
+each option, commas after, and an
+.QW or
+before the last option.
.SH "OLD CHANNEL TYPES"
-
The original (8.3.1 and below) \fBTcl_ChannelType\fR structure contains
the following fields:
.PP
.CS
typedef struct Tcl_ChannelType {
- char *\fItypeName\fR;
- Tcl_DriverBlockModeProc *\fIblockModeProc\fR;
- Tcl_DriverCloseProc *\fIcloseProc\fR;
- Tcl_DriverInputProc *\fIinputProc\fR;
- Tcl_DriverOutputProc *\fIoutputProc\fR;
- Tcl_DriverSeekProc *\fIseekProc\fR;
- Tcl_DriverSetOptionProc *\fIsetOptionProc\fR;
- Tcl_DriverGetOptionProc *\fIgetOptionProc\fR;
- Tcl_DriverWatchProc *\fIwatchProc\fR;
- Tcl_DriverGetHandleProc *\fIgetHandleProc\fR;
- Tcl_DriverClose2Proc *\fIclose2Proc\fR;
+ char *\fItypeName\fR;
+ Tcl_DriverBlockModeProc *\fIblockModeProc\fR;
+ Tcl_DriverCloseProc *\fIcloseProc\fR;
+ Tcl_DriverInputProc *\fIinputProc\fR;
+ Tcl_DriverOutputProc *\fIoutputProc\fR;
+ Tcl_DriverSeekProc *\fIseekProc\fR;
+ Tcl_DriverSetOptionProc *\fIsetOptionProc\fR;
+ Tcl_DriverGetOptionProc *\fIgetOptionProc\fR;
+ Tcl_DriverWatchProc *\fIwatchProc\fR;
+ Tcl_DriverGetHandleProc *\fIgetHandleProc\fR;
+ Tcl_DriverClose2Proc *\fIclose2Proc\fR;
} Tcl_ChannelType;
.CE
.PP
@@ -897,33 +909,32 @@ the new \fBTcl_ChannelType\fR structure if you are creating a stacked
channel driver, due to problems with the earlier stacked channel
implementation (in 8.2.0 to 8.3.1).
.PP
-.VS 8.4
Prior to 8.4.0 (i.e. during the later releases of 8.3 and early part
of the 8.4 development cycle) the \fBTcl_ChannelType\fR structure
contained the following fields:
.PP
.CS
typedef struct Tcl_ChannelType {
- char *\fItypeName\fR;
- Tcl_ChannelTypeVersion \fIversion\fR;
- Tcl_DriverCloseProc *\fIcloseProc\fR;
- Tcl_DriverInputProc *\fIinputProc\fR;
- Tcl_DriverOutputProc *\fIoutputProc\fR;
- Tcl_DriverSeekProc *\fIseekProc\fR;
- Tcl_DriverSetOptionProc *\fIsetOptionProc\fR;
- Tcl_DriverGetOptionProc *\fIgetOptionProc\fR;
- Tcl_DriverWatchProc *\fIwatchProc\fR;
- Tcl_DriverGetHandleProc *\fIgetHandleProc\fR;
- Tcl_DriverClose2Proc *\fIclose2Proc\fR;
- Tcl_DriverBlockModeProc *\fIblockModeProc\fR;
- Tcl_DriverFlushProc *\fIflushProc\fR;
- Tcl_DriverHandlerProc *\fIhandlerProc\fR;
+ char *\fItypeName\fR;
+ Tcl_ChannelTypeVersion \fIversion\fR;
+ Tcl_DriverCloseProc *\fIcloseProc\fR;
+ Tcl_DriverInputProc *\fIinputProc\fR;
+ Tcl_DriverOutputProc *\fIoutputProc\fR;
+ Tcl_DriverSeekProc *\fIseekProc\fR;
+ Tcl_DriverSetOptionProc *\fIsetOptionProc\fR;
+ Tcl_DriverGetOptionProc *\fIgetOptionProc\fR;
+ Tcl_DriverWatchProc *\fIwatchProc\fR;
+ Tcl_DriverGetHandleProc *\fIgetHandleProc\fR;
+ Tcl_DriverClose2Proc *\fIclose2Proc\fR;
+ Tcl_DriverBlockModeProc *\fIblockModeProc\fR;
+ Tcl_DriverFlushProc *\fIflushProc\fR;
+ Tcl_DriverHandlerProc *\fIhandlerProc\fR;
+ Tcl_DriverTruncateProc *\fItruncateProc\fR;
} Tcl_ChannelType;
.CE
.PP
When the above structure is registered as a channel type, the
\fIversion\fR field should always be \fBTCL_CHANNEL_VERSION_2\fR.
-.VE 8.4
.SH "SEE ALSO"
Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3), Tcl_QueueEvent(3), Tcl_StackChannel(3), Tcl_GetStdChannel(3)
diff --git a/doc/CrtChnlHdlr.3 b/doc/CrtChnlHdlr.3
index ea07ef2..f5fd1bd 100644
--- a/doc/CrtChnlHdlr.3
+++ b/doc/CrtChnlHdlr.3
@@ -48,8 +48,8 @@ what it means for a channel to be readable or writable.
\fIProc\fR must conform to the following prototype:
.CS
typedef void Tcl_ChannelProc(
- ClientData \fIclientData\fR,
- int \fImask\fR);
+ ClientData \fIclientData\fR,
+ int \fImask\fR);
.CE
.PP
The \fIclientData\fR argument is the same as the value passed to
@@ -62,7 +62,7 @@ contain a subset of the bits from the \fImask\fR argument to
.PP
Each channel handler is identified by a unique combination of \fIchannel\fR,
\fIproc\fR and \fIclientData\fR.
-There may be many handlers for a given channel as long as they don't
+There may be many handlers for a given channel as long as they do not
have the same \fIchannel\fR, \fIproc\fR, and \fIclientData\fR.
If \fBTcl_CreateChannelHandler\fR is invoked when there is already a handler
for \fIchannel\fR, \fIproc\fR, and \fIclientData\fR, then no new
diff --git a/doc/CrtCloseHdlr.3 b/doc/CrtCloseHdlr.3
index 35f8261..c8804b1 100644
--- a/doc/CrtCloseHdlr.3
+++ b/doc/CrtCloseHdlr.3
@@ -21,7 +21,7 @@ void
\fBTcl_DeleteCloseHandler\fR(\fIchannel, proc, clientData\fR)
.sp
.SH ARGUMENTS
-.AS Tcl_CloseProc callbackData in
+.AS Tcl_CloseProc clientData
.AP Tcl_Channel channel in
The channel for which to create or delete a close callback.
.AP Tcl_CloseProc *proc in
@@ -39,7 +39,7 @@ Arbitrary one-word value to pass to \fIproc\fR.
.PP
.CS
typedef void Tcl_CloseProc(
- ClientData \fIclientData\fR);
+ ClientData \fIclientData\fR);
.CE
.PP
The \fIclientData\fR is the same as the value provided in the call to
diff --git a/doc/CrtCommand.3 b/doc/CrtCommand.3
index da0da22..fcc04d5 100644
--- a/doc/CrtCommand.3
+++ b/doc/CrtCommand.3
@@ -17,12 +17,10 @@ Tcl_CreateCommand \- implement new commands in C
Tcl_Command
\fBTcl_CreateCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR)
.SH ARGUMENTS
-.AS Tcl_CmdDeleteProc **deleteProcPtr
+.AS Tcl_CmdDeleteProc *deleteProc
.AP Tcl_Interp *interp in
Interpreter in which to create new command.
-.VS 8.4
-.AP "CONST char" *cmdName in
-.VE
+.AP "const char" *cmdName in
Name of command.
.AP Tcl_CmdProc *proc in
Implementation of new command: \fIproc\fR will be called whenever
@@ -79,10 +77,10 @@ and it returns NULL.
\fBTcl_CmdProc\fR:
.CS
typedef int Tcl_CmdProc(
- ClientData \fIclientData\fR,
- Tcl_Interp *\fIinterp\fR,
- int \fIargc\fR,
- CONST char *\fIargv\fR[]);
+ ClientData \fIclientData\fR,
+ Tcl_Interp *\fIinterp\fR,
+ int \fIargc\fR,
+ const char *\fIargv\fR[]);
.CE
When \fIproc\fR is invoked the \fIclientData\fR and \fIinterp\fR
parameters will be copies of the \fIclientData\fR and \fIinterp\fR
@@ -95,26 +93,23 @@ the command name) and \fIargv\fR giving the values of the arguments
as strings. The \fIargv\fR array will contain \fIargc\fR+1 values;
the first \fIargc\fR values point to the argument strings, and the
last value is NULL.
-.VS
Note that the argument strings should not be modified as they may
point to constant strings or may be shared with other parts of the
interpreter.
-.VE
.PP
-.VS
Note that the argument strings are encoded in normalized UTF-8 since
version 8.1 of Tcl.
-.VE
.PP
-\fIProc\fR must return an integer code that is either \fBTCL_OK\fR, \fBTCL_ERROR\fR,
-\fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR. See the Tcl overview man page
+\fIProc\fR must return an integer code that is expected to be one of
+\fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or
+\fBTCL_CONTINUE\fR. See the Tcl overview man page
for details on what these codes mean. Most normal commands will only
return \fBTCL_OK\fR or \fBTCL_ERROR\fR. In addition, \fIproc\fR must set
the interpreter result to point to a string value;
in the case of a \fBTCL_OK\fR return code this gives the result
of the command, and in the case of \fBTCL_ERROR\fR it gives an error message.
The \fBTcl_SetResult\fR procedure provides an easy interface for setting
-the return value; for complete details on how the the interpreter result
+the return value; for complete details on how the interpreter result
field is managed, see the \fBTcl_Interp\fR man page.
Before invoking a command procedure,
\fBTcl_Eval\fR sets the interpreter result to point to an empty string,
@@ -135,11 +130,11 @@ application an opportunity to release any structures associated
with the command. \fIDeleteProc\fR should have arguments and
result that match the type \fBTcl_CmdDeleteProc\fR:
.CS
-typedef void Tcl_CmdDeleteProc(ClientData \fIclientData\fR);
+typedef void Tcl_CmdDeleteProc(
+ ClientData \fIclientData\fR);
.CE
The \fIclientData\fR argument will be the same as the \fIclientData\fR
argument passed to \fBTcl_CreateCommand\fR.
-.PP
.SH "SEE ALSO"
Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_GetCommandInfo, Tcl_SetCommandInfo, Tcl_GetCommandName, Tcl_SetObjResult
diff --git a/doc/CrtFileHdlr.3 b/doc/CrtFileHdlr.3
index af21f0b..5627bd4 100644
--- a/doc/CrtFileHdlr.3
+++ b/doc/CrtFileHdlr.3
@@ -13,18 +13,14 @@ Tcl_CreateFileHandler, Tcl_DeleteFileHandler \- associate procedure callbacks wi
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
-.VS
.sp
\fBTcl_CreateFileHandler\fR(\fIfd, mask, proc, clientData\fR)
.sp
\fBTcl_DeleteFileHandler\fR(\fIfd\fR)
-.VE
.SH ARGUMENTS
.AS Tcl_FileProc clientData
-.VS
.AP int fd in
Unix file descriptor for an open file or device.
-.VE
.AP int mask in
Conditions under which \fIproc\fR should be called:
OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR,
@@ -39,12 +35,10 @@ Arbitrary one-word value to pass to \fIproc\fR.
.SH DESCRIPTION
.PP
-.VS
\fBTcl_CreateFileHandler\fR arranges for \fIproc\fR to be
invoked in the future whenever I/O becomes possible on a file
or an exceptional condition exists for the file. The file
is indicated by \fIfd\fR, and the conditions of interest
-.VE
are indicated by \fImask\fR. For example, if \fImask\fR
is \fBTCL_READABLE\fR, \fIproc\fR will be called when
the file is readable.
@@ -57,8 +51,8 @@ as \fBvwait\fR.
type \fBTcl_FileProc\fR:
.CS
typedef void Tcl_FileProc(
- ClientData \fIclientData\fR,
- int \fImask\fR);
+ ClientData \fIclientData\fR,
+ int \fImask\fR);
.CE
The \fIclientData\fR parameter to \fIproc\fR is a copy
of the \fIclientData\fR
@@ -85,14 +79,12 @@ events while waiting for files to become ready for I/O. For this to work
correctly, the application may need to use non-blocking I/O operations on
the files for which handlers are declared. Otherwise the application may
block if it reads or writes too much data; while waiting for the I/O to
-complete the application won't be able to service other events. Use
+complete the application will not be able to service other events. Use
\fBTcl_SetChannelOption\fR with \fB\-blocking\fR to set the channel into
blocking or nonblocking mode as required.
.PP
-.VS
Note that these interfaces are only supported by the Unix
implementation of the Tcl notifier.
-.VE
.SH KEYWORDS
callback, file, handler
diff --git a/doc/CrtMathFnc.3 b/doc/CrtMathFnc.3
index 43ba8fd..9629912 100644
--- a/doc/CrtMathFnc.3
+++ b/doc/CrtMathFnc.3
@@ -17,20 +17,17 @@ Tcl_CreateMathFunc, Tcl_GetMathFuncInfo, Tcl_ListMathFuncs \- Define, query and
void
\fBTcl_CreateMathFunc\fR(\fIinterp, name, numArgs, argTypes, proc, clientData\fR)
.sp
-.VS 8.4
int
-\fBTcl_GetMathFuncInfo\fR(\fIinterp, name, numArgsPtr, argTypesPtr, procPtr, clientDataPtr\fR)
+\fBTcl_GetMathFuncInfo\fR(\fIinterp, name, numArgsPtr, argTypesPtr, procPtr,
+ clientDataPtr\fR)
.sp
Tcl_Obj *
\fBTcl_ListMathFuncs\fR(\fIinterp, pattern\fR)
-.VE
.SH ARGUMENTS
-.AS Tcl_ValueType *clientDataPtr
+.AS Tcl_ValueType *clientDataPtr out
.AP Tcl_Interp *interp in
Interpreter in which new function will be defined.
-.VS 8.4
-.AP "CONST char" *name in
-.VE
+.AP "const char" *name in
Name for new function.
.AP int numArgs in
Number of arguments to new function; also gives size of \fIargTypes\fR array.
@@ -51,12 +48,12 @@ will need to be freed up using \fITcl_Free\fR.
.AP Tcl_MathProc **procPtr out
Points to a variable that will be set to contain a pointer to the
implementation code for the function (or NULL if the function is
-implemented directly in bytecode.)
+implemented directly in bytecode).
.AP ClientData *clientDataPtr out
Points to a variable that will be set to contain the clientData
argument passed to \fITcl_CreateMathFunc\fR when the function was
created if the function is not implemented directly in bytecode.
-.AP "CONST char" *pattern in
+.AP "const char" *pattern in
Pattern to match against function names so as to filter them (by
passing to \fITcl_StringMatch\fR), or NULL to not apply any filter.
.BE
@@ -65,71 +62,70 @@ passing to \fITcl_StringMatch\fR), or NULL to not apply any filter.
.PP
Tcl allows a number of mathematical functions to be used in
expressions, such as \fBsin\fR, \fBcos\fR, and \fBhypot\fR.
-\fBTcl_CreateMathFunc\fR allows applications to add additional functions
+These functions are represented by commands in the namespace,
+\fBtcl::mathfunc\fR. The \fBTcl_CreateMathFunc\fR function is
+an obsolete way for applications to add additional functions
to those already provided by Tcl or to replace existing functions.
+It should not be used by new applications, which should create
+math functions using \fBTcl_CreateObjCommand\fR to create a command
+in the \fBtcl::mathfunc\fR namespace.
+.PP
+In the \fBTcl_CreateMathFunc\fR interface,
\fIName\fR is the name of the function as it will appear in expressions.
-If \fIname\fR doesn't already exist as a function then a new function
-is created. If it does exist, then the existing function is replaced.
+If \fIname\fR does not already exist in the \fB::tcl::mathfunc\fR
+namespace, then a new command is created in that namespace.
+If \fIname\fR does exist, then the existing function is replaced.
\fINumArgs\fR and \fIargTypes\fR describe the arguments to the function.
Each entry in the \fIargTypes\fR array must be
-.VS 8.4
-one of TCL_INT, TCL_DOUBLE, TCL_WIDE_INT,
-or TCL_EITHER to indicate whether the corresponding argument must be an
+one of \fBTCL_INT\fR, \fBTCL_DOUBLE\fR, \fBTCL_WIDE_INT\fR,
+or \fBTCL_EITHER\fR to indicate whether the corresponding argument must be an
integer, a double-precision floating value, a wide (64-bit) integer,
or any, respectively.
-.VE 8.4
.PP
Whenever the function is invoked in an expression Tcl will invoke
\fIproc\fR. \fIProc\fR should have arguments and result that match
the type \fBTcl_MathProc\fR:
.CS
typedef int Tcl_MathProc(
- ClientData \fIclientData\fR,
- Tcl_Interp *\fIinterp\fR,
- Tcl_Value *\fIargs\fR,
- Tcl_Value *\fIresultPtr\fR);
+ ClientData \fIclientData\fR,
+ Tcl_Interp *\fIinterp\fR,
+ Tcl_Value *\fIargs\fR,
+ Tcl_Value *\fIresultPtr\fR);
.CE
.PP
When \fIproc\fR is invoked the \fIclientData\fR and \fIinterp\fR
arguments will be the same as those passed to \fBTcl_CreateMathFunc\fR.
\fIArgs\fR will point to an array of \fInumArgs\fR Tcl_Value structures,
which describe the actual arguments to the function:
-.VS 8.4
.CS
typedef struct Tcl_Value {
- Tcl_ValueType \fItype\fR;
- long \fIintValue\fR;
- double \fIdoubleValue\fR;
- Tcl_WideInt \fIwideValue\fR;
+ Tcl_ValueType \fItype\fR;
+ long \fIintValue\fR;
+ double \fIdoubleValue\fR;
+ Tcl_WideInt \fIwideValue\fR;
} Tcl_Value;
.CE
.PP
The \fItype\fR field indicates the type of the argument and is
-one of TCL_INT, TCL_DOUBLE or TCL_WIDE_INT.
-.VE 8.4
+one of \fBTCL_INT\fR, \fBTCL_DOUBLE\fR or \fBTCL_WIDE_INT\fR.
It will match the \fIargTypes\fR value specified for the function unless
-the \fIargTypes\fR value was TCL_EITHER. Tcl converts
+the \fIargTypes\fR value was \fBTCL_EITHER\fR. Tcl converts
the argument supplied in the expression to the type requested in
\fIargTypes\fR, if that is necessary.
Depending on the value of the \fItype\fR field, the \fIintValue\fR,
-.VS 8.4
\fIdoubleValue\fR or \fIwideValue\fR
-.VE 8.4
field will contain the actual value of the argument.
.PP
\fIProc\fR should compute its result and store it either as an integer
in \fIresultPtr->intValue\fR or as a floating value in
\fIresultPtr->doubleValue\fR.
It should set also \fIresultPtr->type\fR to one of
-.VS 8.4
-TCL_INT, TCL_DOUBLE or TCL_WIDE_INT
-.VE 8.4
+\fBTCL_INT\fR, \fBTCL_DOUBLE\fR or \fBTCL_WIDE_INT\fR
to indicate which value was set.
-Under normal circumstances \fIproc\fR should return TCL_OK.
+Under normal circumstances \fIproc\fR should return \fBTCL_OK\fR.
If an error occurs while executing the function, \fIproc\fR should
-return TCL_ERROR and leave an error message in the interpreter's result.
+return \fBTCL_ERROR\fR and leave an error message in the interpreter's result.
.PP
-.VS 8.4
\fBTcl_GetMathFuncInfo\fR retrieves the values associated with
function \fIname\fR that were passed to a preceding
\fBTcl_CreateMathFunc\fR call. Normally, the return code is
@@ -140,20 +136,21 @@ result.
If an error did not occur, the array reference placed in the variable
pointed to by \fIargTypesPtr\fR is newly allocated, and should be
released by passing it to \fBTcl_Free\fR. Some functions (the
-standard set implemented in the core) are implemented directly at the
-bytecode level; attempting to retrieve values for them causes a NULL
-to be stored in the variable pointed to by \fIprocPtr\fR and the
-variable pointed to by \fIclientDataPtr\fR will not be modified.
+standard set implemented in the core, and those defined by placing
+commands in the \fBtcl::mathfunc\fR namespace) do not have
+argument type information; attempting to retrieve values for
+them causes a NULL to be stored in the variable pointed to by
+\fIprocPtr\fR and the variable pointed to by \fIclientDataPtr\fR
+will not be modified. The variable pointed to by \fInumArgsPointer\fR
+will contain -1, and no argument types will be stored in the variable
+pointed to by \fIargTypesPointer\fR.
.PP
\fBTcl_ListMathFuncs\fR returns a Tcl object containing a list of all
the math functions defined in the interpreter whose name matches
-\fIpattern\fR. In the case of an error, NULL is returned and an error
-message is left in the interpreter result, and otherwise the returned
-object will have a reference count of zero.
-.VE
+\fIpattern\fR. The returned object has a reference count of zero.
+
+.SH "SEE ALSO"
+expr(n), info(n), Tcl_CreateObjCommand(3), Tcl_Free(3), Tcl_NewListObj(3)
.SH KEYWORDS
expression, mathematical function
-
-.SH "SEE ALSO"
-expr(n), info(n), Tcl_Free(3), Tcl_NewListObj(3)
diff --git a/doc/CrtObjCmd.3 b/doc/CrtObjCmd.3
index bcb57f3..a05efc2 100644
--- a/doc/CrtObjCmd.3
+++ b/doc/CrtObjCmd.3
@@ -28,17 +28,13 @@ int
int
\fBTcl_SetCommandInfo\fR(\fIinterp, cmdName, infoPtr\fR)
.sp
-.VS 8.4
int
\fBTcl_GetCommandInfoFromToken\fR(\fItoken, infoPtr\fR)
.sp
int
\fBTcl_SetCommandInfoFromToken\fR(\fItoken, infoPtr\fR)
-.VE
.sp
-.VS 8.4
-CONST char *
-.VE
+const char *
\fBTcl_GetCommandName\fR(\fIinterp, token\fR)
.sp
void
@@ -47,12 +43,10 @@ void
Tcl_Command
\fBTcl_GetCommandFromObj\fR(\fIinterp, objPtr\fR)
.SH ARGUMENTS
-.AS Tcl_ObjCmdProc *deleteProc in/out
+.AS Tcl_CmdDeleteProc *deleteProc in/out
.AP Tcl_Interp *interp in
Interpreter in which to create a new command or that contains a command.
-.VS 8.4
.AP char *cmdName in
-.VE
Name of command.
.AP Tcl_ObjCmdProc *proc in
Implementation of the new command: \fIproc\fR will be called whenever
@@ -96,11 +90,10 @@ and it returns NULL.
\fBTcl_ObjCmdProc\fR:
.CS
typedef int Tcl_ObjCmdProc(
- ClientData \fIclientData\fR,
- Tcl_Interp *\fIinterp\fR,
- int \fIobjc\fR,
-.VS
- Tcl_Obj *CONST \fIobjv\fR[]);
+ ClientData \fIclientData\fR,
+ Tcl_Interp *\fIinterp\fR,
+ int \fIobjc\fR,
+ Tcl_Obj *const \fIobjv\fR[]);
.CE
When \fIproc\fR is invoked, the \fIclientData\fR and \fIinterp\fR parameters
will be copies of the \fIclientData\fR and \fIinterp\fR arguments given to
@@ -117,7 +110,7 @@ Additionally, when \fIproc\fR is invoked, it must not modify the contents
of the \fIobjv\fR array by assigning new pointer values to any element of the
array (for example, \fIobjv\fR[\fB2\fR] = \fBNULL\fR) because this will
cause memory to be lost and the runtime stack to be corrupted. The
-\fBCONST\fR in the declaration of \fIobjv\fR will cause ANSI-compliant
+\fBconst\fR in the declaration of \fIobjv\fR will cause ANSI-compliant
compilers to report any such attempted assignment as an error. However,
it is acceptable to modify the internal representation of any individual
object argument. For instance, the user may call
@@ -125,7 +118,6 @@ object argument. For instance, the user may call
representation of that object; that call may change the type of the object
that \fIobjv\fR[\fB2\fR] points at, but will not change where
\fIobjv\fR[\fB2\fR] points.
-.VE
.PP
\fIproc\fR must return an integer code that is either \fBTCL_OK\fR,
\fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR.
@@ -168,7 +160,8 @@ application an opportunity to release any structures associated
with the command. \fIDeleteProc\fR should have arguments and
result that match the type \fBTcl_CmdDeleteProc\fR:
.CS
-typedef void Tcl_CmdDeleteProc(ClientData \fIclientData\fR);
+typedef void Tcl_CmdDeleteProc(
+ ClientData \fIclientData\fR);
.CE
The \fIclientData\fR argument will be the same as the \fIclientData\fR
argument passed to \fBTcl_CreateObjCommand\fR.
@@ -176,7 +169,7 @@ argument passed to \fBTcl_CreateObjCommand\fR.
\fBTcl_DeleteCommand\fR deletes a command from a command interpreter.
Once the call completes, attempts to invoke \fIcmdName\fR in
\fIinterp\fR will result in errors.
-If \fIcmdName\fR isn't bound as a command in \fIinterp\fR then
+If \fIcmdName\fR is not bound as a command in \fIinterp\fR then
\fBTcl_DeleteCommand\fR does nothing and returns -1; otherwise
it returns 0.
There are no restrictions on \fIcmdName\fR: it may refer to
@@ -206,14 +199,14 @@ pointed to by \fIinfoPtr\fR and returns 1.
A \fBTcl_CmdInfo\fR structure has the following fields:
.CS
typedef struct Tcl_CmdInfo {
- int isNativeObjectProc;
- Tcl_ObjCmdProc *objProc;
- ClientData objClientData;
- Tcl_CmdProc *proc;
- ClientData clientData;
- Tcl_CmdDeleteProc *deleteProc;
- ClientData deleteData;
- Tcl_Namespace *namespacePtr;
+ int \fIisNativeObjectProc\fR;
+ Tcl_ObjCmdProc *\fIobjProc\fR;
+ ClientData \fIobjClientData\fR;
+ Tcl_CmdProc *\fIproc\fR;
+ ClientData \fIclientData\fR;
+ Tcl_CmdDeleteProc *\fIdeleteProc\fR;
+ ClientData \fIdeleteData\fR;
+ Tcl_Namespace *\fInamespacePtr\fR;
} Tcl_CmdInfo;
.CE
The \fIisNativeObjectProc\fR field has the value 1
@@ -285,16 +278,16 @@ This name does not include any \fB::\fR namespace qualifiers.
The command corresponding to \fItoken\fR must not have been deleted.
The string returned by \fBTcl_GetCommandName\fR is in dynamic memory
owned by Tcl and is only guaranteed to retain its value as long as the
-command isn't deleted or renamed; callers should copy the string if
+command is not deleted or renamed; callers should copy the string if
they need to keep it for a long time.
.PP
-\fBTcl_GetCommandFullName\fR produces the fully-qualified name
+\fBTcl_GetCommandFullName\fR produces the fully qualified name
of a command from a command token.
The name, including all namespace prefixes,
-is appended to the object specified by \fIobjPtr\fP.
+is appended to the object specified by \fIobjPtr\fR.
.PP
\fBTcl_GetCommandFromObj\fR returns a token for the command
-specified by the name in a \fBTcl_Obj\fP.
+specified by the name in a \fBTcl_Obj\fR.
The command name is resolved relative to the current namespace.
Returns NULL if the command is not found.
.SH "SEE ALSO"
diff --git a/doc/CrtSlave.3 b/doc/CrtSlave.3
index f87a4e0..3863373 100644
--- a/doc/CrtSlave.3
+++ b/doc/CrtSlave.3
@@ -8,7 +8,7 @@
.TH Tcl_CreateSlave 3 7.6 Tcl "Tcl Library Procedures"
.BS
.SH NAME
-Tcl_IsSafe, Tcl_MakeSafe, Tcl_CreateSlave, Tcl_GetSlave, Tcl_GetMaster, Tcl_GetInterpPath, Tcl_CreateAlias, Tcl_CreateAliasObj, Tcl_GetAlias, Tcl_GetAliasObj, Tcl_ExposeCommand, Tcl_HideCommand \- manage multiple Tcl interpreters, aliases and hidden commands.
+Tcl_IsSafe, Tcl_MakeSafe, Tcl_CreateSlave, Tcl_GetSlave, Tcl_GetMaster, Tcl_GetInterpPath, Tcl_CreateAlias, Tcl_CreateAliasObj, Tcl_GetAlias, Tcl_GetAliasObj, Tcl_ExposeCommand, Tcl_HideCommand \- manage multiple Tcl interpreters, aliases and hidden commands
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
@@ -31,20 +31,21 @@ Tcl_Interp *
int
\fBTcl_GetInterpPath\fR(\fIaskingInterp, slaveInterp\fR)
.sp
-.VS
int
-\fBTcl_CreateAlias\fR(\fIslaveInterp, slaveCmd, targetInterp, targetCmd, argc, argv\fR)
+\fBTcl_CreateAlias\fR(\fIslaveInterp, slaveCmd, targetInterp, targetCmd,
+ argc, argv\fR)
.sp
int
-\fBTcl_CreateAliasObj\fR(\fIslaveInterp, slaveCmd, targetInterp, targetCmd, objc, objv\fR)
-.VE
+\fBTcl_CreateAliasObj\fR(\fIslaveInterp, slaveCmd, targetInterp, targetCmd,
+ objc, objv\fR)
.sp
int
-\fBTcl_GetAlias\fR(\fIinterp, slaveCmd, targetInterpPtr, targetCmdPtr, argcPtr, argvPtr\fR)
+\fBTcl_GetAlias\fR(\fIinterp, slaveCmd, targetInterpPtr, targetCmdPtr,
+ argcPtr, argvPtr\fR)
.sp
-.VS
int
-\fBTcl_GetAliasObj\fR(\fIinterp, slaveCmd, targetInterpPtr, targetCmdPtr, objcPtr, objvPtr\fR)
+\fBTcl_GetAliasObj\fR(\fIinterp, slaveCmd, targetInterpPtr, targetCmdPtr,
+ objcPtr, objvPtr\fR)
.sp
int
\fBTcl_ExposeCommand\fR(\fIinterp, hiddenCmdName, cmdName\fR)
@@ -52,44 +53,46 @@ int
int
\fBTcl_HideCommand\fR(\fIinterp, cmdName, hiddenCmdName\fR)
.SH ARGUMENTS
-.AS Tcl_InterpDeleteProc **hiddenCmdName
+.AS "const char *const" **targetInterpPtr out
.AP Tcl_Interp *interp in
Interpreter in which to execute the specified command.
-.AP "CONST char" *slaveName in
+.AP "const char" *slaveName in
Name of slave interpreter to create or manipulate.
.AP int isSafe in
-If non-zero, a ``safe'' slave that is suitable for running untrusted code
+If non-zero, a
+.QW safe
+slave that is suitable for running untrusted code
is created, otherwise a trusted slave is created.
.AP Tcl_Interp *slaveInterp in
Interpreter to use for creating the source command for an alias (see
below).
-.AP "CONST char" *slaveCmd in
+.AP "const char" *slaveCmd in
Name of source command for alias.
.AP Tcl_Interp *targetInterp in
Interpreter that contains the target command for an alias.
-.AP "CONST char" *targetCmd in
+.AP "const char" *targetCmd in
Name of target command for alias in \fItargetInterp\fR.
.AP int argc in
Count of additional arguments to pass to the alias command.
-.AP "CONST char * CONST" *argv in
+.AP "const char *const" *argv in
Vector of strings, the additional arguments to pass to the alias command.
This storage is owned by the caller.
.AP int objc in
Count of additional object arguments to pass to the alias object command.
-.AP Tcl_Object **objv in
+.AP Tcl_Obj **objv in
Vector of Tcl_Obj structures, the additional object arguments to pass to
the alias object command.
This storage is owned by the caller.
.AP Tcl_Interp **targetInterpPtr in
Pointer to location to store the address of the interpreter where a target
command is defined for an alias.
-.AP "CONST char" **targetCmdPtr out
+.AP "const char" **targetCmdPtr out
Pointer to location to store the address of the name of the target command
for an alias.
.AP int *argcPtr out
Pointer to location to store count of additional arguments to be passed to
the alias. The location is in storage owned by the caller.
-.AP "CONST char" ***argvPtr out
+.AP "const char" ***argvPtr out
Pointer to location to store a vector of strings, the additional arguments
to pass to an alias. The location is in storage owned by the caller, the
vector of strings is owned by the called function.
@@ -101,17 +104,11 @@ Pointer to location to store a vector of Tcl_Obj structures, the additional
arguments to pass to an object alias command. The location is in storage
owned by the caller, the vector of Tcl_Obj structures is owned by the
called function.
-.VS
-.VS 8.4
-.AP "CONST char" *cmdName in
-.VE
+.AP "const char" *cmdName in
Name of an exposed command to hide or create.
-.VS 8.4
-.AP "CONST char" *hiddenCmdName in
-.VE
+.AP "const char" *hiddenCmdName in
Name under which a hidden command is stored and with which it can be
exposed or invoked.
-.VE
.BE
.SH DESCRIPTION
@@ -129,16 +126,21 @@ It also creates a slave command named \fIslaveName\fR in \fIinterp\fR which
allows \fIinterp\fR to manipulate the new slave.
If \fIisSafe\fR is zero, the command creates a trusted slave in which Tcl
code has access to all the Tcl commands.
-If it is \fB1\fR, the command creates a ``safe'' slave in which Tcl code
-has access only to set of Tcl commands defined as ``Safe Tcl''; see the
-manual entry for the Tcl \fBinterp\fR command for details.
+If it is \fB1\fR, the command creates a
+.QW safe
+slave in which Tcl code has access only to set of Tcl commands defined as
+.QW "Safe Tcl" ;
+see the manual entry for the Tcl \fBinterp\fR command for details.
If the creation of the new slave interpreter failed, \fBNULL\fR is returned.
.PP
-\fBTcl_IsSafe\fR returns \fB1\fR if \fIinterp\fR is ``safe'' (was created
-with the \fBTCL_SAFE_INTERPRETER\fR flag specified),
+\fBTcl_IsSafe\fR returns \fB1\fR if \fIinterp\fR is
+.QW safe
+(was created with the \fBTCL_SAFE_INTERPRETER\fR flag specified),
\fB0\fR otherwise.
.PP
-\fBTcl_MakeSafe\fR marks \fIinterp\fR as ``safe'', so that future
+\fBTcl_MakeSafe\fR marks \fIinterp\fR as
+.QW safe ,
+so that future
calls to \fBTcl_IsSafe\fR will return 1. It also removes all known
potentially-unsafe core functionality (both commands and variables)
from \fIinterp\fR. However, it cannot know what parts of an extension
@@ -163,7 +165,6 @@ of the relative path succeeds, \fBTCL_OK\fR is returned, else
\fBTCL_ERROR\fR is returned and the \fIresult\fR field in
\fIaskingInterp\fR contains the error message.
.PP
-.VS
\fBTcl_CreateAlias\fR creates an object command named \fIslaveCmd\fR in
\fIslaveInterp\fR that when invoked, will cause the command \fItargetCmd\fR
to be invoked in \fItargetInterp\fR. The arguments specified by the strings
@@ -180,7 +181,6 @@ restrictions on how they are related.
\fBTcl_CreateAliasObj\fR is similar to \fBTcl_CreateAlias\fR except
that it takes a vector of objects to pass as additional arguments instead
of a vector of strings.
-.VE
.PP
\fBTcl_GetAlias\fR returns information about an alias \fIaliasName\fR
in \fIinterp\fR. Any of the result fields can be \fBNULL\fR, in
@@ -188,7 +188,6 @@ which case the corresponding datum is not returned. If a result field is
non\-\fBNULL\fR, the address indicated is set to the corresponding datum.
For example, if \fItargetNamePtr\fR is non\-\fBNULL\fR it is set to a
pointer to the string containing the name of the target command.
-.VS
.PP
\fBTcl_GetAliasObj\fR is similar to \fBTcl_GetAlias\fR except that it
returns a pointer to a vector of Tcl_Obj structures instead of a vector of
diff --git a/doc/CrtTimerHdlr.3 b/doc/CrtTimerHdlr.3
index 9018ae2..e948728 100644
--- a/doc/CrtTimerHdlr.3
+++ b/doc/CrtTimerHdlr.3
@@ -9,8 +9,7 @@
.TH Tcl_CreateTimerHandler 3 7.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
-Tcl_CreateTimerHandler, Tcl_DeleteTimerHandler \- call a procedure at a
-given time
+Tcl_CreateTimerHandler, Tcl_DeleteTimerHandler \- call a procedure at a given time
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
@@ -28,7 +27,7 @@ Procedure to invoke after \fImilliseconds\fR have elapsed.
.AP ClientData clientData in
Arbitrary one-word value to pass to \fIproc\fR.
.AP Tcl_TimerToken token in
-Token for previously-created timer handler (the return value
+Token for previously created timer handler (the return value
from some previous call to \fBTcl_CreateTimerHandler\fR).
.BE
@@ -43,7 +42,7 @@ dispatch events through \fBTcl_DoOneEvent\fR or through Tcl commands
such as \fBvwait\fR.
The call to \fIproc\fR may not be made at the exact time given by
\fImilliseconds\fR: it will be made at the next opportunity
-after that time. For example, if \fBTcl_DoOneEvent\fR isn't
+after that time. For example, if \fBTcl_DoOneEvent\fR is not
called until long after the time has elapsed, or if there
are other pending events to process before the call to
\fIproc\fR, then the call to \fIproc\fR will be delayed.
@@ -61,7 +60,7 @@ structure containing application-specific information about
what to do in \fIproc\fR.
.PP
\fBTcl_DeleteTimerHandler\fR may be called to delete a
-previously-created timer handler. It deletes the handler
+previously created timer handler. It deletes the handler
indicated by \fItoken\fR so that no call to \fIproc\fR
will be made; if that handler no longer exists
(e.g. because the time period has already elapsed and \fIproc\fR
diff --git a/doc/CrtTrace.3 b/doc/CrtTrace.3
index e11bd55..076f47b 100644
--- a/doc/CrtTrace.3
+++ b/doc/CrtTrace.3
@@ -1,7 +1,7 @@
'\"
'\" Copyright (c) 1989-1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\" Copyright (c) 2002 by Kevin B. Kenny. All rights reserved.
+'\" Copyright (c) 2002 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
@@ -23,7 +23,7 @@ Tcl_Trace
.sp
\fBTcl_DeleteTrace\fR(\fIinterp, trace\fR)
.SH ARGUMENTS
-.AS Tcl_CmdObjTraceDeleteProc (clientData)()
+.AS Tcl_CmdObjTraceDeleteProc *deleteProc
.AP Tcl_Interp *interp in
Interpreter containing command to be traced or untraced.
.AP int level in
@@ -36,14 +36,14 @@ A value of 0 means that commands at any level are traced.
.AP int flags in
Flags governing the trace execution. See below for details.
.AP Tcl_CmdObjTraceProc *objProc in
-Procedure to call for each command that's executed. See below for
+Procedure to call for each command that is executed. See below for
details of the calling sequence.
.AP Tcl_CmdTraceProc *proc in
-Procedure to call for each command that's executed. See below for
+Procedure to call for each command that is executed. See below for
details on the calling sequence.
.AP ClientData clientData in
Arbitrary one-word value to pass to \fIobjProc\fR or \fIproc\fR.
-.AP Tcl_CmdObjTraceDeleteProc *deleteProc
+.AP Tcl_CmdObjTraceDeleteProc *deleteProc in
Procedure to call when the trace is deleted. See below for details of
the calling sequence. A NULL pointer is permissible and results in no
callback when the trace is deleted.
@@ -65,13 +65,13 @@ interpreter.
\fBTcl_CmdObjTraceProc\fR:
.CS
typedef int \fBTcl_CmdObjTraceProc\fR(
- \fBClientData\fR \fIclientData\fR,
- \fBTcl_Interp\fR* \fIinterp\fR,
- int \fIlevel\fR,
- CONST char* \fIcommand\fR,
- \fBTcl_Command\fR \fIcommandToken\fR,
- int \fIobjc\fR,
- \fBTcl_Obj\fR *CONST \fIobjv\fR[] );
+ \fBClientData\fR \fIclientData\fR,
+ \fBTcl_Interp\fR* \fIinterp\fR,
+ int \fIlevel\fR,
+ const char *\fIcommand\fR,
+ \fBTcl_Command\fR \fIcommandToken\fR,
+ int \fIobjc\fR,
+ \fBTcl_Obj\fR *const \fIobjv\fR[] );
.CE
The \fIclientData\fR and \fIinterp\fR parameters are copies of the
corresponding arguments given to \fBTcl_CreateTrace\fR.
@@ -141,8 +141,7 @@ When \fBTcl_DeleteTrace\fR is called, the interpreter invokes the
\fBTcl_CmdObjTraceDeleteProc\fR:
.CS
typedef void \fBTcl_CmdObjTraceDeleteProc\fR(
- \fBClientData\fR \fIclientData\fR
-);
+ \fBClientData\fR \fIclientData\fR);
.CE
The \fIclientData\fR parameter will be the same as the
\fIclientData\fR parameter that was originally passed to
@@ -156,14 +155,14 @@ that its \fIproc\fR parameter should have arguments and result that
match the type \fBTcl_CmdTraceProc\fR:
.CS
typedef void Tcl_CmdTraceProc(
- ClientData \fIclientData\fR,
- Tcl_Interp *\fIinterp\fR,
- int \fIlevel\fR,
- char *\fIcommand\fR,
- Tcl_CmdProc *\fIcmdProc\fR,
- ClientData \fIcmdClientData\fR,
- int \fIargc\fR,
- CONST char *\fIargv\fR[]);
+ ClientData \fIclientData\fR,
+ Tcl_Interp *\fIinterp\fR,
+ int \fIlevel\fR,
+ char *\fIcommand\fR,
+ Tcl_CmdProc *\fIcmdProc\fR,
+ ClientData \fIcmdClientData\fR,
+ int \fIargc\fR,
+ const char *\fIargv\fR[]);
.CE
The parameters to the \fIproc\fR callback are similar to those of the
\fIobjProc\fR callback above. The \fIcommandToken\fR is
diff --git a/doc/DString.3 b/doc/DString.3
index 8c6f516..a85b1cf 100644
--- a/doc/DString.3
+++ b/doc/DString.3
@@ -17,10 +17,10 @@ Tcl_DStringInit, Tcl_DStringAppend, Tcl_DStringAppendElement, Tcl_DStringStartSu
\fBTcl_DStringInit\fR(\fIdsPtr\fR)
.sp
char *
-\fBTcl_DStringAppend\fR(\fIdsPtr, string, length\fR)
+\fBTcl_DStringAppend\fR(\fIdsPtr, bytes, length\fR)
.sp
char *
-\fBTcl_DStringAppendElement\fR(\fIdsPtr, string\fR)
+\fBTcl_DStringAppendElement\fR(\fIdsPtr, element\fR)
.sp
\fBTcl_DStringStartSublist\fR(\fIdsPtr\fR)
.sp
@@ -42,13 +42,15 @@ char *
.sp
\fBTcl_DStringGetResult\fR(\fIinterp, dsPtr\fR)
.SH ARGUMENTS
-.AS Tcl_DString newLength
+.AS Tcl_DString newLength in/out
.AP Tcl_DString *dsPtr in/out
Pointer to structure that is used to manage a dynamic string.
-.AP "CONST char" *string in
-Pointer to characters to add to dynamic string.
+.AP "const char" *bytes in
+Pointer to characters to append to dynamic string.
+.AP "const char" *element in
+Pointer to characters to append as list element to dynamic string.
.AP int length in
-Number of characters from string to add to dynamic string. If -1,
+Number of bytes from \fIbytes\fR to add to dynamic string. If -1,
add all characters up to null terminating character.
.AP int newLength in
New length for dynamic string, not including null terminating
@@ -75,7 +77,7 @@ string.
.PP
\fBTcl_DStringAppend\fR adds new information to a dynamic string,
allocating more memory for the string if needed.
-If \fIlength\fR is less than zero then everything in \fIstring\fR
+If \fIlength\fR is less than zero then everything in \fIbytes\fR
is appended to the dynamic string; otherwise \fIlength\fR
specifies the number of bytes to append.
\fBTcl_DStringAppend\fR returns a pointer to the characters of
@@ -83,14 +85,16 @@ the new string. The string can also be retrieved from the
\fIstring\fR field of the Tcl_DString structure.
.PP
\fBTcl_DStringAppendElement\fR is similar to \fBTcl_DStringAppend\fR
-except that it doesn't take a \fIlength\fR argument (it appends
-all of \fIstring\fR) and it converts the string to a proper list element
+except that it does not take a \fIlength\fR argument (it appends
+all of \fIelement\fR) and it converts the string to a proper list element
before appending.
\fBTcl_DStringAppendElement\fR adds a separator space before the
new list element unless the new list element is the first in a
list or sub-list (i.e. either the current string is empty, or it
-contains the single character ``{'', or the last two characters of
-the current string are `` {'').
+contains the single character
+.QW { ,
+or the last two characters of the current string are
+.QW " {" ).
\fBTcl_DStringAppendElement\fR returns a pointer to the
characters of the new string.
.PP
@@ -128,7 +132,7 @@ will still need to be called.
This procedure is now deprecated. \fBTcl_DStringSetLength\fR should
be used instead.
.PP
-\fBTcl_DStringFree\fR should be called when you're finished using
+\fBTcl_DStringFree\fR should be called when you are finished using
the string. It frees up any memory that was allocated for the string
and reinitializes the string's value to an empty string.
.PP
diff --git a/doc/DetachPids.3 b/doc/DetachPids.3
index 17b57eb..0535cd8 100644
--- a/doc/DetachPids.3
+++ b/doc/DetachPids.3
@@ -19,18 +19,18 @@ Tcl_DetachPids, Tcl_ReapDetachedProcs, Tcl_WaitPid \- manage child processes in
\fBTcl_ReapDetachedProcs\fR()
.sp
Tcl_Pid
-\fBTcl_WaitPid\fR(\fIpid, statPtr, options\fR)
+\fBTcl_WaitPid\fR(\fIpid, statusPtr, options\fR)
.SH ARGUMENTS
-.AS int *statusPtr
+.AS Tcl_Pid *statusPtr out
.AP int numPids in
Number of process ids contained in the array pointed to by \fIpidPtr\fR.
.AP int *pidPtr in
Address of array containing \fInumPids\fR process ids.
.AP Tcl_Pid pid in
The id of the process (pipe) to wait for.
-.AP int* statPtr out
+.AP int *statusPtr out
The result of waiting on a process (pipe). Either 0 or ECHILD.
-.AP int options
+.AP int options in
The options controlling the wait. WNOHANG specifies not to wait when
checking the process.
.BE
@@ -49,16 +49,16 @@ overflow, even if all the children have exited.
\fBTcl_DetachPids\fR may be called to ask Tcl to take responsibility
for one or more processes whose process ids are contained in the
\fIpidPtr\fR array passed as argument. The caller presumably
-has started these processes running in background and doesn't
+has started these processes running in background and does not
want to have to deal with them again.
.PP
\fBTcl_ReapDetachedProcs\fR invokes the \fBwaitpid\fR kernel call
on each of the background processes so that its state can be cleaned
-up if it has exited. If the process hasn't exited yet,
-\fBTcl_ReapDetachedProcs\fR doesn't wait for it to exit; it will check again
+up if it has exited. If the process has not exited yet,
+\fBTcl_ReapDetachedProcs\fR does not wait for it to exit; it will check again
the next time it is invoked.
Tcl automatically calls \fBTcl_ReapDetachedProcs\fR each time the
-\fBexec\fR command is executed, so in most cases it isn't necessary
+\fBexec\fR command is executed, so in most cases it is not necessary
for any code outside of Tcl to invoke \fBTcl_ReapDetachedProcs\fR.
However, if you call \fBTcl_DetachPids\fR in situations where the
\fBexec\fR command may never get executed, you may wish to call
diff --git a/doc/DictObj.3 b/doc/DictObj.3
new file mode 100644
index 0000000..74b8dd1
--- /dev/null
+++ b/doc/DictObj.3
@@ -0,0 +1,234 @@
+'\"
+'\" Copyright (c) 2003 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.so man.macros
+.TH Tcl_DictObj 3 8.5 Tcl "Tcl Library Procedures"
+.BS
+'\" Note: do not modify the .SH NAME line immediately below!
+.SH NAME
+Tcl_NewDictObj, Tcl_DictObjPut, Tcl_DictObjGet, Tcl_DictObjRemove, Tcl_DictObjSize, Tcl_DictObjFirst, Tcl_DictObjNext, Tcl_DictObjDone, Tcl_DictObjPutKeyList, Tcl_DictObjRemoveKeyList \- manipulate Tcl objects as dictionaries
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+Tcl_Obj *
+\fBTcl_NewDictObj\fR()
+.sp
+int
+\fBTcl_DictObjGet\fR(\fIinterp, dictPtr, keyPtr, valuePtrPtr\fR)
+.sp
+int
+\fBTcl_DictObjPut\fR(\fIinterp, dictPtr, keyPtr, valuePtr\fR)
+.sp
+int
+\fBTcl_DictObjRemove\fR(\fIinterp, dictPtr, keyPtr\fR)
+.sp
+int
+\fBTcl_DictObjSize\fR(\fIinterp, dictPtr, sizePtr\fR)
+.sp
+int
+\fBTcl_DictObjFirst\fR(\fIinterp, dictPtr, searchPtr,
+ keyPtrPtr, valuePtrPtr, donePtr\fR)
+.sp
+void
+\fBTcl_DictObjNext\fR(\fIsearchPtr, keyPtrPtr, valuePtrPtr, donePtr\fR)
+.sp
+void
+\fBTcl_DictObjDone\fR(\fIsearchPtr\fR)
+.sp
+int
+\fBTcl_DictObjPutKeyList\fR(\fIinterp, dictPtr, keyc, keyv, valuePtr\fR)
+.sp
+int
+\fBTcl_DictObjRemoveKeyList\fR(\fIinterp, dictPtr, keyc, keyv\fR)
+.SH ARGUMENTS
+.AS Tcl_DictSearch "**valuePtrPtr" in/out
+.AP Tcl_Interp *interp in
+If an error occurs while converting an object to be a dictionary object,
+an error message is left in the interpreter's result object
+unless \fIinterp\fR is NULL.
+.AP Tcl_Obj *dictPtr in/out
+Points to the dictionary object to be manipulated.
+If \fIdictPtr\fR does not already point to a dictionary object,
+an attempt will be made to convert it to one.
+.AP Tcl_Obj *keyPtr in
+Points to the key for the key/value pair being manipulated within the
+dictionary object.
+.AP Tcl_Obj **keyPtrPtr out
+Points to a variable that will have the key from a key/value pair
+placed within it. May be NULL to indicate that the caller is not
+interested in the key.
+.AP Tcl_Obj *valuePtr in
+Points to the value for the key/value pair being manipulate within the
+dictionary object (or sub-object, in the case of
+\fBTcl_DictObjPutKeyList\fR.)
+.AP Tcl_Obj **valuePtrPtr out
+Points to a variable that will have the value from a key/value pair
+placed within it. For \fBTcl_DictObjFirst\fR and
+\fBTcl_DictObjNext\fR, this may be NULL to indicate that the caller is
+not interested in the value.
+.AP int *sizePtr out
+Points to a variable that will have the number of key/value pairs
+contained within the dictionary placed within it.
+.AP Tcl_DictSearch *searchPtr in/out
+Pointer to record to use to keep track of progress in enumerating all
+key/value pairs in a dictionary. The contents of the record will be
+initialized by the call to \fBTcl_DictObjFirst\fR. If the enumerating
+is to be terminated before all values in the dictionary have been
+returned, the search record \fImust\fR be passed to
+\fBTcl_DictObjDone\fR to enable the internal locks to be released.
+.AP int *donePtr out
+Points to a variable that will have a non-zero value written into it
+when the enumeration of the key/value pairs in a dictionary has
+completed, and a zero otherwise.
+.AP int keyc in
+Indicates the number of keys that will be supplied in the \fIkeyv\fR
+array.
+.AP "Tcl_Obj *const" *keyv in
+Array of \fIkeyc\fR pointers to objects that
+\fBTcl_DictObjPutKeyList\fR and \fBTcl_DictObjRemoveKeyList\fR will
+use to locate the key/value pair to manipulate within the
+sub-dictionaries of the main dictionary object passed to them.
+.BE
+
+.SH DESCRIPTION
+.PP
+Tcl dictionary objects have an internal representation that supports
+efficient mapping from keys to values and which guarantees that the
+particular ordering of keys within the dictionary remains the same
+modulo any keys being deleted (which removes them from the order) or
+added (which adds them to the end of the order). If reinterpreted as a
+list, the values at the even-valued indices in the list will be the
+keys of the dictionary, and each will be followed (in the odd-valued
+index) by the value associated with that key.
+.PP
+The procedures described in this man page are used to
+create, modify, index, and iterate over dictionary objects from C code.
+.PP
+\fBTcl_NewDictObj\fR creates a new, empty dictionary object. The
+string representation of the object will be invalid, and the reference
+count of the object will be zero.
+.PP
+\fBTcl_DictObjGet\fR looks up the given key within the given
+dictionary and writes a pointer to the value associated with that key
+into the variable pointed to by \fIvaluePtrPtr\fR, or a NULL if the
+key has no mapping within the dictionary. The result of this
+procedure is \fBTCL_OK\fR, or \fBTCL_ERROR\fR if the \fIdictPtr\fR cannot be
+converted to a dictionary.
+.PP
+\fBTcl_DictObjPut\fR updates the given dictionary so that the given
+key maps to the given value; any key may exist at most once in any
+particular dictionary. The dictionary must not be shared, but the key
+and value may be. This procedure may increase the reference count of
+both key and value if it proves necessary to store them. Neither key
+nor value should be NULL. The result of this procedure is \fBTCL_OK\fR, or
+\fBTCL_ERROR\fR if the \fIdictPtr\fR cannot be converted to a dictionary.
+.PP
+\fBTcl_DictObjRemove\fR updates the given dictionary so that the given
+key has no mapping to any value. The dictionary must not be shared,
+but the key may be. The key actually stored in the dictionary will
+have its reference count decremented if it was present. It is not an
+error if the key did not previously exist. The result of this
+procedure is \fBTCL_OK\fR, or \fBTCL_ERROR\fR if the \fIdictPtr\fR cannot be
+converted to a dictionary.
+.PP
+\fBTcl_DictObjSize\fR updates the given variable with the number of
+key/value pairs currently in the given dictionary. The result of this
+procedure is \fBTCL_OK\fR, or \fBTCL_ERROR\fR if the \fIdictPtr\fR cannot be
+converted to a dictionary.
+.PP
+\fBTcl_DictObjFirst\fR commences an iteration across all the key/value
+pairs in the given dictionary, placing the key and value in the
+variables pointed to by the \fIkeyPtrPtr\fR and \fIvaluePtrPtr\fR
+arguments (which may be NULL to indicate that the caller is
+uninterested in they key or variable respectively.) The next
+key/value pair in the dictionary may be retrieved with
+\fBTcl_DictObjNext\fR. Concurrent updates of the dictionary's
+internal representation will not modify the iteration processing
+unless the dictionary is unshared, when this will trigger premature
+termination of the iteration instead (which Tcl scripts cannot trigger
+via the \fBdict\fR command.) The \fIsearchPtr\fR argument points to a
+piece of context that is used to identify which particular iteration
+is being performed, and is initialized by the call to
+\fBTcl_DictObjFirst\fR. The \fIdonePtr\fR argument points to a
+variable that is updated to be zero of there are further key/value
+pairs to be iterated over, or non-zero if the iteration is complete.
+The order of iteration is implementation-defined. If the
+\fIdictPtr\fR argument cannot be converted to a dictionary,
+\fBTcl_DictObjFirst\fR returns \fBTCL_ERROR\fR and the iteration is not
+commenced, and otherwise it returns \fBTCL_OK\fR.
+.PP
+When \fBTcl_DictObjFirst\fR is called upon a dictionary, a lock is placed on
+the dictionary to enable that dictionary to be iterated over safely without
+regard for whether the dictionary is modified during the iteration. Because of
+this, once the iteration over a dictionary's keys has finished (whether
+because all values have been iterated over as indicated by the variable
+indicated by the \fIdonePtr\fR argument being set to one, or because no
+further values are required) the \fBTcl_DictObjDone\fR function must be called
+with the same \fIsearchPtr\fR as was passed to \fBTcl_DictObjFirst\fR so that
+the internal locks can be released. Once a particular \fIsearchPtr\fR is
+passed to \fBTcl_DictObjDone\fR, passing it to \fBTcl_DictObjNext\fR (without
+first initializing it with \fBTcl_DictObjFirst\fR) will result in no values
+being produced and the variable pointed to by \fIdonePtr\fR being set to one.
+It is safe to call \fBTcl_DictObjDone\fR multiple times on the same
+\fIsearchPtr\fR for each call to \fBTcl_DictObjFirst\fR.
+.PP
+The procedures \fBTcl_DictObjPutKeyList\fR and
+\fBTcl_DictObjRemoveKeyList\fR are the close analogues of
+\fBTcl_DictObjPut\fR and \fBTcl_DictObjRemove\fR respectively, except
+that instead of working with a single dictionary, they are designed to
+operate on a nested tree of dictionaries, with inner dictionaries
+stored as values inside outer dictionaries. The \fIkeyc\fR and
+\fIkeyv\fR arguments specify a list of keys (with outermost keys
+first) that acts as a path to the key/value pair to be affected. Note
+that there is no corresponding operation for reading a value for a
+path as this is easy to construct from repeated use of
+\fBTcl_DictObjGet\fR. With \fBTcl_DictObjPutKeyList\fR, nested
+dictionaries are created for non-terminal keys where they do not
+already exist. With \fBTcl_DictObjRemoveKeyList\fR, all non-terminal
+keys must exist and have dictionaries as their values.
+.SH EXAMPLE
+Using the dictionary iteration interface to search determine if there
+is a key that maps to itself:
+.PP
+.CS
+Tcl_DictSearch search;
+Tcl_Obj *key, *value;
+int done;
+
+/*
+ * Assume interp and objPtr are parameters. This is the
+ * idiomatic way to start an iteration over the dictionary; it
+ * sets a lock on the internal representation that ensures that
+ * there are no concurrent modification issues when normal
+ * reference count management is also used. The lock is
+ * released automatically when the loop is finished, but must
+ * be released manually when an exceptional exit from the loop
+ * is performed. However it is safe to try to release the lock
+ * even if we've finished iterating over the loop.
+ */
+if (\fBTcl_DictObjFirst\fR(interp, objPtr, &search,
+ &key, &value, &done) != TCL_OK) {
+ return TCL_ERROR;
+}
+for (; !done ; \fBTcl_DictObjNext\fR(&search, &key, &value, &done)) {
+ /*
+ * Note that strcmp() is not a good way of comparing
+ * objects and is just used here for demonstration
+ * purposes.
+ */
+ if (!strcmp(Tcl_GetString(key), Tcl_GetString(value))) {
+ break;
+ }
+}
+\fBTcl_DictObjDone\fR(&search);
+Tcl_SetObjResult(interp, Tcl_NewBooleanObj(!done));
+return TCL_OK;
+.CE
+.SH "SEE ALSO"
+Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_InitObjHashTable
+.SH KEYWORDS
+dict, dict object, dictionary, dictionary object, hash table, iteration, object
diff --git a/doc/DoOneEvent.3 b/doc/DoOneEvent.3
index 058307d..9bdf926 100644
--- a/doc/DoOneEvent.3
+++ b/doc/DoOneEvent.3
@@ -21,9 +21,9 @@ int
.AP int flags in
This parameter is normally zero. It may be an OR-ed combination
of any of the following flag bits:
-TCL_WINDOW_EVENTS,
-TCL_FILE_EVENTS, TCL_TIMER_EVENTS, TCL_IDLE_EVENTS, TCL_ALL_EVENTS, or
-TCL_DONT_WAIT.
+\fBTCL_WINDOW_EVENTS\fR, \fBTCL_FILE_EVENTS\fR,
+\fBTCL_TIMER_EVENTS\fR, \fBTCL_IDLE_EVENTS\fR, \fBTCL_ALL_EVENTS\fR,
+or \fBTCL_DONT_WAIT\fR.
.BE
.SH DESCRIPTION
@@ -71,7 +71,7 @@ Process all kinds of events: equivalent to OR-ing together all of the
above flags or specifying none of them.
.TP 27
\fBTCL_DONT_WAIT\fR \-
-Don't sleep: process only events that are ready at the time of the
+Do not sleep: process only events that are ready at the time of the
call.
.LP
If any of the flags \fBTCL_WINDOW_EVENTS\fR, \fBTCL_FILE_EVENTS\fR,
diff --git a/doc/DoWhenIdle.3 b/doc/DoWhenIdle.3
index a15f1cb..bfc19fb 100644
--- a/doc/DoWhenIdle.3
+++ b/doc/DoWhenIdle.3
@@ -30,7 +30,7 @@ Arbitrary one-word value to pass to \fIproc\fR.
\fBTcl_DoWhenIdle\fR arranges for \fIproc\fR to be invoked
when the application becomes idle. The application is
considered to be idle when \fBTcl_DoOneEvent\fR has been
-called, couldn't find any events to handle, and is about
+called, could not find any events to handle, and is about
to go to sleep waiting for an event to occur. At this
point all pending \fBTcl_DoWhenIdle\fR handlers are
invoked. For each call to \fBTcl_DoWhenIdle\fR there will
@@ -59,7 +59,7 @@ all of the handlers are removed. If no existing handlers match
\fIproc\fR and \fIclientData\fR then nothing happens.
.PP
\fBTcl_DoWhenIdle\fR is most useful in situations where
-(a) a piece of work will have to be done but (b) it's
+(a) a piece of work will have to be done but (b) it is
possible that something will happen in the near future
that will change what has to be done or require something
different to be done. \fBTcl_DoWhenIdle\fR allows the
diff --git a/doc/DoubleObj.3 b/doc/DoubleObj.3
index b65af58..12818b0 100644
--- a/doc/DoubleObj.3
+++ b/doc/DoubleObj.3
@@ -23,55 +23,42 @@ int
.SH ARGUMENTS
.AS Tcl_Interp doubleValue in/out
.AP double doubleValue in
-A double-precision floating point value used to initialize or set a double object.
+A double-precision floating-point value used to initialize or set a Tcl object.
.AP Tcl_Obj *objPtr in/out
-For \fBTcl_SetDoubleObj\fR, this points to the object to be converted
-to double type.
+For \fBTcl_SetDoubleObj\fR, this points to the object in which to store a
+double value.
For \fBTcl_GetDoubleFromObj\fR, this refers to the object
-from which to get a double value;
-if \fIobjPtr\fR does not already point to a double object,
-an attempt will be made to convert it to one.
+from which to retrieve a double value.
.AP Tcl_Interp *interp in/out
-If an error occurs during conversion,
-an error message is left in the interpreter's result object
-unless \fIinterp\fR is NULL.
+When non-NULL, an error message is left here when double value retrieval fails.
.AP double *doublePtr out
-Points to place to store the double value
-obtained from \fIobjPtr\fR.
+Points to place to store the double value obtained from \fIobjPtr\fR.
.BE
.SH DESCRIPTION
.PP
-These procedures are used to create, modify, and read
-double Tcl objects from C code.
-\fBTcl_NewDoubleObj\fR and \fBTcl_SetDoubleObj\fR
-will create a new object of double type
-or modify an existing object to have double type.
-Both of these procedures set the object to have the
-double-precision floating point value given by \fIdoubleValue\fR;
-\fBTcl_NewDoubleObj\fR returns a pointer to a newly created object
-with reference count zero.
-Both procedures set the object's type to be double
-and assign the double value to the object's internal representation
-\fIdoubleValue\fR member.
-\fBTcl_SetDoubleObj\fR invalidates any old string representation
-and, if the object is not already a double object,
-frees any old internal representation.
+These procedures are used to create, modify, and read Tcl objects that
+hold double-precision floating-point values.
.PP
-\fBTcl_GetDoubleFromObj\fR attempts to return a double value
-from the Tcl object \fIobjPtr\fR.
-If the object is not already a double object,
-it will attempt to convert it to one.
-If an error occurs during conversion, it returns \fBTCL_ERROR\fR
-and leaves an error message in the interpreter's result object
-unless \fIinterp\fR is NULL.
-Otherwise, it returns \fBTCL_OK\fR and stores the double value
-in the address given by \fIdoublePtr\fR.
-If the object is not already a double object,
-the conversion will free any old internal representation.
-
+\fBTcl_NewDoubleObj\fR creates and returns a new Tcl object initialized to
+the double value \fIdoubleValue\fR. The returned Tcl object is unshared.
+.PP
+\fBTcl_SetDoubleObj\fR sets the value of an existing Tcl object pointed to
+by \fIobjPtr\fR to the double value \fIdoubleValue\fR. The \fIobjPtr\fR
+argument must point to an unshared Tcl object. Any attempt to set the value
+of a shared Tcl object violates Tcl's copy-on-write policy. Any existing
+string representation or internal representation in the unshared Tcl object
+will be freed as a consequence of setting the new value.
+.PP
+\fBTcl_GetDoubleFromObj\fR attempts to retrieve a double value from the
+Tcl object \fIobjPtr\fR. If the attempt succeeds, then \fBTCL_OK\fR is
+returned, and the double value is written to the storage pointed to by
+\fIdoublePtr\fR. If the attempt fails, then \fBTCL_ERROR\fR is returned,
+and if \fIinterp\fR is non-NULL, an error message is left in \fIinterp\fR.
+The \fBTcl_ObjType\fR of \fIobjPtr\fR may be changed to make subsequent
+calls to \fBTcl_GetDoubleFromObj\fR more efficient.
+'\" TODO: add discussion of treatment of NaN value
.SH "SEE ALSO"
Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
-
.SH KEYWORDS
double, double object, double type, internal representation, object, object type, string representation
diff --git a/doc/DumpActiveMemory.3 b/doc/DumpActiveMemory.3
index 6e00eb3..1f6cb46 100644
--- a/doc/DumpActiveMemory.3
+++ b/doc/DumpActiveMemory.3
@@ -7,7 +7,7 @@
.TH "Tcl_DumpActiveMemory" 3 8.1 Tcl "Tcl Library Procedures"
.BS
.SH NAME
-Tcl_DumpActiveMemory, Tcl_InitMemory, Tcl_ValidateAllMemory \- Validated memory allocation interface.
+Tcl_DumpActiveMemory, Tcl_InitMemory, Tcl_ValidateAllMemory \- Validated memory allocation interface
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
@@ -22,9 +22,10 @@ void
\fBTcl_ValidateAllMemory\fR(\fIfileName, line\fR)
.SH ARGUMENTS
+.AS Tcl_Interp *fileName
.AP Tcl_Interp *interp in
Tcl interpreter in which to add commands.
-.AP "CONST char" *fileName in
+.AP "const char" *fileName in
For \fBTcl_DumpActiveMemory\fR, name of the file to which memory
information will be written. For \fBTcl_ValidateAllMemory\fR, name of
the file from which the call is being made (normally \fB__FILE__\fR).
diff --git a/doc/Encoding.3 b/doc/Encoding.3
index 913d4fa..a940a5b 100644
--- a/doc/Encoding.3
+++ b/doc/Encoding.3
@@ -8,7 +8,7 @@
.TH Tcl_GetEncoding 3 "8.1" Tcl "Tcl Library Procedures"
.BS
.SH NAME
-Tcl_GetEncoding, Tcl_FreeEncoding, Tcl_ExternalToUtfDString, Tcl_ExternalToUtf, Tcl_UtfToExternalDString, Tcl_UtfToExternal, Tcl_WinTCharToUtf, Tcl_WinUtfToTChar, Tcl_GetEncodingName, Tcl_SetSystemEncoding, Tcl_GetEncodingNames, Tcl_CreateEncoding, Tcl_GetDefaultEncodingDir, Tcl_SetDefaultEncodingDir \- procedures for creating and using encodings.
+Tcl_GetEncoding, Tcl_FreeEncoding, Tcl_GetEncodingFromObj, Tcl_ExternalToUtfDString, Tcl_ExternalToUtf, Tcl_UtfToExternalDString, Tcl_UtfToExternal, Tcl_WinTCharToUtf, Tcl_WinUtfToTChar, Tcl_GetEncodingName, Tcl_SetSystemEncoding, Tcl_GetEncodingNameFromEnvironment, Tcl_GetEncodingNames, Tcl_CreateEncoding, Tcl_GetEncodingSearchPath, Tcl_SetEncodingSearchPath, Tcl_GetDefaultEncodingDir, Tcl_SetDefaultEncodingDir \- procedures for creating and using encodings
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
@@ -19,19 +19,24 @@ Tcl_Encoding
void
\fBTcl_FreeEncoding\fR(\fIencoding\fR)
.sp
+.VS 8.5
+int
+\fBTcl_GetEncodingFromObj\fR(\fIinterp, objPtr, encodingPtr\fR)
+.VE 8.5
+.sp
char *
\fBTcl_ExternalToUtfDString\fR(\fIencoding, src, srcLen, dstPtr\fR)
.sp
-int
-\fBTcl_ExternalToUtf\fR(\fIinterp, encoding, src, srcLen, flags, statePtr, dst, dstLen, srcReadPtr, dstWrotePtr,
- dstCharsPtr\fR)
-.sp
-char *
+char *
\fBTcl_UtfToExternalDString\fR(\fIencoding, src, srcLen, dstPtr\fR)
.sp
int
-\fBTcl_UtfToExternal\fR(\fIinterp, encoding, src, srcLen, flags, statePtr, dst, dstLen, srcReadPtr, dstWrotePtr,
- dstCharsPtr\fR)
+\fBTcl_ExternalToUtf\fR(\fIinterp, encoding, src, srcLen, flags, statePtr,
+ dst, dstLen, srcReadPtr, dstWrotePtr, dstCharsPtr\fR)
+.sp
+int
+\fBTcl_UtfToExternal\fR(\fIinterp, encoding, src, srcLen, flags, statePtr,
+ dst, dstLen, srcReadPtr, dstWrotePtr, dstCharsPtr\fR)
.sp
char *
\fBTcl_WinTCharToUtf\fR(\fItsrc, srcLen, dstPtr\fR)
@@ -39,41 +44,60 @@ char *
TCHAR *
\fBTcl_WinUtfToTChar\fR(\fIsrc, srcLen, dstPtr\fR)
.sp
-CONST char *
+const char *
\fBTcl_GetEncodingName\fR(\fIencoding\fR)
.sp
int
\fBTcl_SetSystemEncoding\fR(\fIinterp, name\fR)
.sp
+.VS 8.5
+const char *
+\fBTcl_GetEncodingNameFromEnvironment\fR(\fIbufPtr\fR)
+.VE 8.5
+.sp
void
\fBTcl_GetEncodingNames\fR(\fIinterp\fR)
.sp
Tcl_Encoding
\fBTcl_CreateEncoding\fR(\fItypePtr\fR)
.sp
-CONST char *
+.VS 8.5
+Tcl_Obj *
+\fBTcl_GetEncodingSearchPath\fR()
+.sp
+int
+\fBTcl_SetEncodingSearchPath\fR(\fIsearchPath\fR)
+.VE 8.5
+.sp
+const char *
\fBTcl_GetDefaultEncodingDir\fR(\fIvoid\fR)
.sp
void
\fBTcl_SetDefaultEncodingDir\fR(\fIpath\fR)
-
-
.SH ARGUMENTS
-.AS Tcl_EncodingState *dstWrotePtr
+.AS "const Tcl_EncodingType" *dstWrotePtr in/out
.AP Tcl_Interp *interp in
Interpreter to use for error reporting, or NULL if no error reporting is
desired.
-.AP "CONST char" *name in
+.AP "const char" *name in
Name of encoding to load.
.AP Tcl_Encoding encoding in
The encoding to query, free, or use for converting text. If \fIencoding\fR is
NULL, the current system encoding is used.
-.AP "CONST char" *src in
+.AP Tcl_Obj *objPtr in
+.VS 8.5
+Name of encoding to get token for.
+.VE 8.5
+.AP Tcl_Encoding *encodingPtr out
+.VS 8.5
+Points to storage where encoding token is to be written.
+.VE 8.5
+.AP "const char" *src in
For the \fBTcl_ExternalToUtf\fR functions, an array of bytes in the
specified encoding that are to be converted to UTF-8. For the
\fBTcl_UtfToExternal\fR and \fBTcl_WinUtfToTChar\fR functions, an array of
UTF-8 characters to be converted to the specified encoding.
-.AP "CONST TCHAR" *tsrc in
+.AP "const TCHAR" *tsrc in
An array of Windows TCHAR characters to convert to UTF-8.
.AP int srcLen in
Length of \fIsrc\fR or \fItsrc\fR in bytes. If the length is negative, the
@@ -83,21 +107,21 @@ Pointer to an uninitialized or free \fBTcl_DString\fR in which the converted
result will be stored.
.AP int flags in
Various flag bits OR-ed together.
-TCL_ENCODING_START signifies that the
+\fBTCL_ENCODING_START\fR signifies that the
source buffer is the first block in a (potentially multi-block) input
stream, telling the conversion routine to reset to an initial state and
perform any initialization that needs to occur before the first byte is
-converted. TCL_ENCODING_END signifies that the source buffer is the last
+converted. \fBTCL_ENCODING_END\fR signifies that the source buffer is the last
block in a (potentially multi-block) input stream, telling the conversion
routine to perform any finalization that needs to occur after the last
byte is converted and then to reset to an initial state.
-TCL_ENCODING_STOPONERROR signifies that the conversion routine should
-return immediately upon reading a source character that doesn't exist in
+\fBTCL_ENCODING_STOPONERROR\fR signifies that the conversion routine should
+return immediately upon reading a source character that does not exist in
the target encoding; otherwise a default fallback character will
automatically be substituted.
.AP Tcl_EncodingState *statePtr in/out
Used when converting a (generally long or indefinite length) byte stream
-in a piece by piece fashion. The conversion routine stores its current
+in a piece-by-piece fashion. The conversion routine stores its current
state in \fI*statePtr\fR after \fIsrc\fR (the buffer containing the
current piece) has been converted; that state information must be passed
back when converting the next piece of the stream so the conversion
@@ -120,9 +144,17 @@ buffer as a result of the conversion. May be NULL.
.AP int *dstCharsPtr out
Filled with the number of characters that correspond to the number of bytes
stored in the output buffer. May be NULL.
-.AP Tcl_EncodingType *typePtr in
+.AP Tcl_DString *bufPtr out
+.VS 8.5
+Storage for the prescribed system encoding name.
+.VE 8.5
+.AP "const Tcl_EncodingType" *typePtr in
Structure that defines a new type of encoding.
-.AP "CONST char" *path in
+.AP Tcl_Obj *searchPath in
+.VS 8.5
+List of filesystem directories in which to search for encoding data files.
+.VE 8.5
+.AP "const char" *path in
A path to the location of the encoding file.
.BE
.SH INTRODUCTION
@@ -149,7 +181,7 @@ platform-independent manner.
.SH DESCRIPTION
.PP
\fBTcl_GetEncoding\fR finds an encoding given its \fIname\fR. The name may
-refer to a builtin Tcl encoding, a user-defined encoding registered by
+refer to a built-in Tcl encoding, a user-defined encoding registered by
calling \fBTcl_CreateEncoding\fR, or a dynamically-loadable encoding
file. The return value is a token that represents the encoding and can be
used in subsequent calls to procedures such as \fBTcl_GetEncodingName\fR,
@@ -170,6 +202,20 @@ anywhere (i.e., it has been freed as many times as it has been gotten)
\fBTcl_FreeEncoding\fR will release all storage the encoding was using
and delete it from the database.
.PP
+.VS 8.5
+\fBTcl_GetEncodingFromObj\fR treats the string representation of
+\fIobjPtr\fR as an encoding name, and finds an encoding with that
+name, just as \fBTcl_GetEncoding\fR does. When an encoding is found,
+it is cached within the \fBobjPtr\fR value for future reference, the
+\fBTcl_Encoding\fR token is written to the storage pointed to by
+\fIencodingPtr\fR, and the value \fBTCL_OK\fR is returned. If no such
+encoding is found, the value \fBTCL_ERROR\fR is returned, and no
+writing to \fB*\fR\fIencodingPtr\fR takes place. Just as with
+\fBTcl_GetEncoding\fR, the caller should call \fBTcl_FreeEncoding\fR
+on the resulting encoding token when that token will no longer be
+used.
+.VE 8.5
+.PP
\fBTcl_ExternalToUtfDString\fR converts a source buffer \fIsrc\fR from the
specified \fIencoding\fR into UTF-8. The converted bytes are stored in
\fIdstPtr\fR, which is then null-terminated. The caller should eventually
@@ -192,7 +238,7 @@ All bytes of \fIsrc\fR were converted.
The destination buffer was not large enough for all of the converted data; as
many characters as could fit were converted though.
.IP \fBTCL_CONVERT_MULTIBYTE\fR 29
-The last fews bytes in the source buffer were the beginning of a multibyte
+The last few bytes in the source buffer were the beginning of a multibyte
sequence, but more bytes were needed to complete this sequence. A
subsequent call to the conversion routine should pass a buffer containing
the unconverted bytes that remained in \fIsrc\fR plus some further bytes
@@ -204,7 +250,7 @@ if the input stream has been damaged or if the input encoding method was
misidentified.
.IP \fBTCL_CONVERT_UNKNOWN\fR 29
The source buffer contained a character that could not be represented in
-the target encoding and TCL_ENCODING_STOPONERROR was specified.
+the target encoding and \fBTCL_ENCODING_STOPONERROR\fR was specified.
.RE
.LP
\fBTcl_UtfToExternalDString\fR converts a source buffer \fIsrc\fR from UTF-8
@@ -228,19 +274,26 @@ is filled with the corresponding number of bytes that were stored in
\fBTcl_WinUtfToTChar\fR and \fBTcl_WinTCharToUtf\fR are
Windows-only convenience
functions for converting between UTF-8 and Windows strings. On Windows 95
-(as with the Macintosh and Unix operating systems),
-all strings exchanged between Tcl and the operating system are "char"
+(as with the Unix operating system),
+all strings exchanged between Tcl and the operating system are
+.QW "char"
based. On Windows NT, some strings exchanged between Tcl and the
-operating system are "char" oriented while others are in Unicode. By
+operating system are
+.QW "char"
+oriented while others are in Unicode. By
convention, in Windows a TCHAR is a character in the ANSI code page
on Windows 95 and a Unicode character on Windows NT.
.PP
-If you planned to use the same "char" based interfaces on both Windows
+If you planned to use the same
+.QW "char"
+based interfaces on both Windows
95 and Windows NT, you could use \fBTcl_UtfToExternal\fR and
\fBTcl_ExternalToUtf\fR (or their \fBTcl_DString\fR equivalents) with an
encoding of NULL (the current system encoding). On the other hand,
if you planned to use the Unicode interface when running on Windows NT
-and the "char" interfaces when running on Windows 95, you would have
+and the
+.QW "char"
+interfaces when running on Windows 95, you would have
to perform the following type of test over and over in your program
(as represented in pseudo-code):
.CS
@@ -250,6 +303,7 @@ if (running NT) {
Tcl_FreeEncoding(encoding);
} else {
nativeBuffer <- Tcl_UtfToExternal(NULL, utfBuffer);
+}
.CE
\fBTcl_WinUtfToTChar\fR and \fBTcl_WinTCharToUtf\fR automatically
handle this test and use the proper encoding based on the current
@@ -269,11 +323,20 @@ was used to create the encoding. The string returned by
whenever the user passes a NULL value for the \fIencoding\fR argument to
any of the other encoding functions. If \fIname\fR is NULL, the system
encoding is reset to the default system encoding, \fBbinary\fR. If the
-name did not refer to any known or loadable encoding, TCL_ERROR is
+name did not refer to any known or loadable encoding, \fBTCL_ERROR\fR is
returned and an error message is left in \fIinterp\fR. Otherwise, this
procedure increments the reference count of the new system encoding,
decrements the reference count of the old system encoding, and returns
-TCL_OK.
+\fBTCL_OK\fR.
+.PP
+.VS 8.5
+\fBTcl_GetEncodingNameFromEnvironment\fR provides a means for the Tcl
+library to report the encoding name it believes to be the correct one
+to use as the system encoding, based on system calls and examination of
+the environment suitable for the platform. It accepts \fIbufPtr\fR,
+a pointer to an uninitialized or freed \fBTcl_DString\fR and writes
+the encoding name to it. The \fBTcl_DStringValue\fR is returned.
+.VE 8.5
.PP
\fBTcl_GetEncodingNames\fR sets the \fIinterp\fR result to a list
consisting of the names of all the encodings that are currently defined
@@ -301,12 +364,12 @@ convert between this encoding and UTF-8. It is defined as follows:
.PP
.CS
typedef struct Tcl_EncodingType {
- CONST char *\fIencodingName\fR;
- Tcl_EncodingConvertProc *\fItoUtfProc\fR;
- Tcl_EncodingConvertProc *\fIfromUtfProc\fR;
- Tcl_EncodingFreeProc *\fIfreeProc\fR;
- ClientData \fIclientData\fR;
- int \fInullSize\fR;
+ const char *\fIencodingName\fR;
+ Tcl_EncodingConvertProc *\fItoUtfProc\fR;
+ Tcl_EncodingConvertProc *\fIfromUtfProc\fR;
+ Tcl_EncodingFreeProc *\fIfreeProc\fR;
+ ClientData \fIclientData\fR;
+ int \fInullSize\fR;
} Tcl_EncodingType;
.CE
.PP
@@ -336,16 +399,16 @@ type \fBTcl_EncodingConvertProc\fR:
.PP
.CS
typedef int Tcl_EncodingConvertProc(
- ClientData \fIclientData\fR,
- CONST char *\fIsrc\fR,
- int \fIsrcLen\fR,
- int \fIflags\fR,
- Tcl_Encoding *\fIstatePtr\fR,
- char *\fIdst\fR,
- int \fIdstLen\fR,
- int *\fIsrcReadPtr\fR,
- int *\fIdstWrotePtr\fR,
- int *\fIdstCharsPtr\fR);
+ ClientData \fIclientData\fR,
+ const char *\fIsrc\fR,
+ int \fIsrcLen\fR,
+ int \fIflags\fR,
+ Tcl_EncodingState *\fIstatePtr\fR,
+ char *\fIdst\fR,
+ int \fIdstLen\fR,
+ int *\fIsrcReadPtr\fR,
+ int *\fIdstWrotePtr\fR,
+ int *\fIdstCharsPtr\fR);
.CE
.PP
The \fItoUtfProc\fR and \fIfromUtfProc\fR procedures are called by the
@@ -367,20 +430,42 @@ The callback procedure \fIfreeProc\fR, if non-NULL, should match the type
\fBTcl_EncodingFreeProc\fR:
.CS
typedef void Tcl_EncodingFreeProc(
- ClientData \fIclientData\fR);
+ ClientData \fIclientData\fR);
.CE
.PP
This \fIfreeProc\fR function is called when the encoding is deleted. The
\fIclientData\fR parameter is the same as the \fIclientData\fR field
specified to \fBTcl_CreateEncoding\fR when the encoding was created.
.PP
-
+.VS 8.5
+\fBTcl_GetEncodingSearchPath\fR and \fBTcl_SetEncodingSearchPath\fR
+are called to access and set the list of filesystem directories searched
+for encoding data files.
+.PP
+The value returned by \fBTcl_GetEncodingSearchPath\fR
+is the value stored by the last successful call to
+\fBTcl_SetEncodingSearchPath\fR. If no calls to
+\fBTcl_SetEncodingSearchPath\fR have occurred, Tcl will compute an initial
+value based on the environment. There is one encoding search path for the
+entire process, shared by all threads in the process.
+.PP
+\fBTcl_SetEncodingSearchPath\fR stores \fIsearchPath\fR and returns
+\fBTCL_OK\fR, unless \fIsearchPath\fR is not a valid Tcl list, which
+causes \fBTCL_ERROR\fR to be returned. The elements of \fIsearchPath\fR
+are not verified as existing readable filesystem directories. When
+searching for encoding data files takes place, and non-existent or
+non-readable filesystem directories on the \fIsearchPath\fR are silently
+ignored.
+.PP
\fBTcl_GetDefaultEncodingDir\fR and \fBTcl_SetDefaultEncodingDir\fR
-access and set the directory to use when locating the default encoding
-files. If this value is not NULL, the \fBTclpInitLibraryPath\fR routine
-appends the path to the head of the search path, and uses this path as
-the first place to look into when trying to locate the encoding file.
-
+are obsolete interfaces best replaced with calls to
+\fBTcl_GetEncodingSearchPath\fR and \fBTcl_SetEncodingSearchPath\fR.
+They are called to access and set the first element of the \fIsearchPath\fR
+list. Since Tcl searches \fIsearchPath\fR for encoding data files in
+list order, these routines establish the
+.QW default
+directory in which to find encoding data files.
+.VE 8.5
.SH "ENCODING FILES"
Space would prohibit precompiling into Tcl every possible encoding
algorithm, so many encodings are stored on disk as dynamically-loadable
@@ -392,23 +477,25 @@ external encoding may consist of single-byte, multi-byte, or double-byte
characters.
.PP
Each dynamically-loadable encoding is represented as a text file. The
-initial line of the file, beginning with a ``#'' symbol, is a comment
+initial line of the file, beginning with a
+.QW #
+symbol, is a comment
that provides a human-readable description of the file. The next line
identifies the type of encoding file. It can be one of the following
letters:
-.IP "[1] \fBS\fR"
+.IP "[1] \fBS\fR"
A single-byte encoding, where one character is always one byte long in the
encoding. An example is \fBiso8859-1\fR, used by many European languages.
-.IP "[2] \fBD\fR"
+.IP "[2] \fBD\fR"
A double-byte encoding, where one character is always two bytes long in the
encoding. An example is \fBbig5\fR, used for Chinese text.
-.IP "[3] \fBM\fR"
+.IP "[3] \fBM\fR"
A multi-byte encoding, where one character may be either one or two bytes long.
-Certain bytes are a lead bytes, indicating that another byte must follow
+Certain bytes are lead bytes, indicating that another byte must follow
and that together the two bytes represent one character. Other bytes are not
lead bytes and represent themselves. An example is \fBshiftjis\fR, used by
many Japanese computers.
-.IP "[4] \fBE\fR"
+.IP "[4] \fBE\fR"
An escape-sequence encoding, specifying that certain sequences of bytes
do not represent characters, but commands that describe how following bytes
should be interpreted.
@@ -478,7 +565,7 @@ and 0x8163 in \fBshiftjis\fR map to 203E and 2026 in Unicode, respectively.
Following the first page will be all the other pages, each in the same
format as the first: one number identifying the page followed by 256
double-byte Unicode characters. If a character in the encoding maps to the
-Unicode character 0000, it means that the character doesn't actually exist.
+Unicode character 0000, it means that the character does not actually exist.
If all characters on a page would map to 0000, that page can be omitted.
.PP
Case [4] is the escape-sequence encoding file. The lines in an this type of
@@ -490,13 +577,13 @@ encoding:
E
init {}
final {}
-iso8859-1 \\x1b(B
-jis0201 \\x1b(J
-jis0208 \\x1b$@
-jis0208 \\x1b$B
-jis0212 \\x1b$(D
-gb2312 \\x1b$A
-ksc5601 \\x1b$(C
+iso8859-1 \ex1b(B
+jis0201 \ex1b(J
+jis0208 \ex1b$@
+jis0208 \ex1b$B
+jis0212 \ex1b$(D
+gb2312 \ex1b$A
+ksc5601 \ex1b$(C
.CE
.PP
In the file, the first column represents an option and the second column
@@ -505,16 +592,16 @@ the first character is converted, while \fBfinal\fR is a string to emit
or expect after the last character. All other options are names of
table-based encodings; the associated value is the escape-sequence that
marks that encoding. Tcl syntax is used for the values; in the above
-example, for instance, ``\fB{}\fR'' represents the empty string and
-``\fB\\x1b\fR'' represents character 27.
+example, for instance,
+.QW \fB{}\fR
+represents the empty string and
+.QW \fB\ex1b\fR
+represents character 27.
.PP
When \fBTcl_GetEncoding\fR encounters an encoding \fIname\fR that has not
been loaded, it attempts to load an encoding file called \fIname\fB.enc\fR
-from the \fBencoding\fR subdirectory of each directory specified in the
-library path \fB$tcl_libPath\fR. If the encoding file exists, but is
+from the \fBencoding\fR subdirectory of each directory that Tcl searches
+for its script library. If the encoding file exists, but is
malformed, an error message will be left in \fIinterp\fR.
.SH KEYWORDS
utf, encoding, convert
-
-
-
diff --git a/doc/Ensemble.3 b/doc/Ensemble.3
new file mode 100644
index 0000000..bc743c2
--- /dev/null
+++ b/doc/Ensemble.3
@@ -0,0 +1,188 @@
+'\"
+'\" Copyright (c) 2005 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+'\" This documents the C API introduced in TIP#235
+'\"
+.so man.macros
+.TH Tcl_Ensemble 3 8.5 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_CreateEnsemble, Tcl_FindEnsemble, Tcl_GetEnsembleFlags, Tcl_GetEnsembleMappingDict, Tcl_GetEnsembleNamespace, Tcl_GetEnsembleUnknownHandler, Tcl_GetEnsembleSubcommandList, Tcl_IsEnsemble, Tcl_SetEnsembleFlags, Tcl_SetEnsembleMappingDict, Tcl_SetEnsembleSubcommandList, Tcl_SetEnsembleUnknownHandler \- manipulate ensemble commands
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+Tcl_Command
+\fBTcl_CreateEnsemble\fR(\fIinterp, name, namespacePtr, ensFlags\fR)
+.sp
+Tcl_Command
+\fBTcl_FindEnsemble\fR(\fIinterp, cmdNameObj, flags\fR)
+.sp
+int
+\fBTcl_IsEnsemble\fR(\fItoken\fR)
+.sp
+int
+\fBTcl_GetEnsembleFlags\fR(\fIinterp, token, ensFlagsPtr\fR)
+.sp
+int
+\fBTcl_SetEnsembleFlags\fR(\fIinterp, token, ensFlags\fR)
+.sp
+int
+\fBTcl_GetEnsembleMappingDict\fR(\fIinterp, token, dictObjPtr\fR)
+.sp
+int
+\fBTcl_SetEnsembleMappingDict\fR(\fIinterp, token, dictObj\fR)
+.sp
+int
+\fBTcl_GetEnsembleSubcommandList\fR(\fIinterp, token, listObjPtr\fR)
+.sp
+int
+\fBTcl_SetEnsembleSubcommandList\fR(\fIinterp, token, listObj\fR)
+.sp
+int
+\fBTcl_GetEnsembleUnknownHandler\fR(\fIinterp, token, listObjPtr\fR)
+.sp
+int
+\fBTcl_SetEnsembleUnknownHandler\fR(\fIinterp, token, listObj\fR)
+.sp
+int
+\fBTcl_GetEnsembleNamespace\fR(\fIinterp, token, namespacePtrPtr\fR)
+.SH ARGUMENTS
+.AS Tcl_Namespace **namespacePtrPtr in/out
+.AP Tcl_Interp *interp in/out
+The interpreter in which the ensemble is to be created or found. Also
+where error result messages are written. The functions whose names
+start with \fBTcl_GetEnsemble\fR may have a NULL for the \fIinterp\fR,
+but all other functions must not.
+.AP "const char" *name in
+The name of the ensemble command to be created.
+.AP Tcl_Namespace *namespacePtr in
+The namespace to which the ensemble command is to be bound, or NULL
+for the current namespace.
+.AP int ensFlags in
+An ORed set of flag bits describing the basic configuration of the
+ensemble. Currently only one bit has meaning, TCL_ENSEMBLE_PREFIX,
+which is present when the ensemble command should also match
+unambiguous prefixes of subcommands.
+.AP Tcl_Obj *cmdNameObj in
+A value holding the name of the ensemble command to look up.
+.AP int flags in
+An ORed set of flag bits controlling the behavior of
+\fBTcl_FindEnsemble\fR. Currently only TCL_LEAVE_ERR_MSG is supported.
+.AP Tcl_Command token in
+A normal command token that refers to an ensemble command, or which
+you wish to use for testing as an ensemble command in \fBTcl_IsEnsemble\fR.
+.AP int *ensFlagsPtr out
+Pointer to a variable into which to write the current ensemble flag
+bits; currently only the bit TCL_ENSEMBLE_PREFIX is defined.
+.AP Tcl_Obj *dictObj in
+A dictionary value to use for the subcommand to implementation command
+prefix mapping dictionary in the ensemble. May be NULL if the mapping
+dictionary is to be removed.
+.AP Tcl_Obj **dictObjPtr out
+Pointer to a variable into which to write the current ensemble mapping
+dictionary.
+.AP Tcl_Obj *listObj in
+A list value to use for the defined list of subcommands in the
+dictionary or the unknown subcommmand handler command prefix. May be
+NULL if the subcommand list or unknown handler are to be removed.
+.AP Tcl_Obj **listObjPtr out
+Pointer to a variable into which to write the current defiend list of
+subcommands or the current unknown handler prefix.
+.AP Tcl_Namespace **namespacePtrPtr out
+Pointer to a variable into which to write the handle of the namespace
+to which the ensemble is bound.
+.BE
+
+.SH DESCRIPTION
+An ensemble is a command, bound to some namespace, which consists of a
+collection of subcommands implemented by other Tcl commands. The first
+argument to the ensemble command is always interpreted as a selector
+that states what subcommand to execute.
+.PP
+Ensembles are created using \fBTcl_CreateEnsemble\fR, which takes four
+arguments: the interpreter to work within, the name of the ensemble to
+create, the namespace within the interpreter to bind the ensemble to,
+and the default set of ensemble flags. The result of the function is
+the command token for the ensemble, which may be used to further
+configure the ensemble using the API described below in \fBENSEMBLE
+PROPERTIES\fR.
+.PP
+Given the name of an ensemble command, the token for that command may
+be retrieved using \fBTcl_FindEnsemble\fR. If the given command name
+(in \fIcmdNameObj\fR) does not refer to an ensemble command, the
+result of the function is NULL and (if the TCL_LEAVE_ERR_MSG bit is
+set in \fIflags\fR) an error message is left in the interpreter
+result.
+.PP
+A command token may be checked to see if it refers to an ensemble
+using \fBTcl_IsEnsemble\fR. This returns 1 if the token refers to an
+ensemble, or 0 otherwise.
+.SS "ENSEMBLE PROPERTIES"
+Every ensemble has four read-write properties and a read-only
+property. The properties are:
+.TP
+\fBflags\fR (read-write)
+The set of flags for the ensemble, expressed as a
+bit-field. Currently, the only public flag is TCL_ENSEMBLE_PREFIX
+which is set when unambiguous prefixes of subcommands are permitted to
+be resolved to implementations as well as exact matches. The flags may
+be read and written using \fBTcl_GetEnsembleFlags\fR and
+\fBTcl_SetEnsembleFlags\fR respectively. The result of both of those
+functions is a Tcl result code (TCL_OK, or TCL_ERROR if the token does
+not refer to an ensemble).
+.TP
+\fBmapping dictionary\fR (read-write)
+A dictionary containing a mapping from subcommand names to lists of
+words to use as a command prefix (replacing the first two words of the
+command which are the ensemble command itself and the subcommand
+name), or NULL if every subcommand is to be mapped to the command with
+the same unqualified name in the ensemble's bound namespace. Defaults
+to NULL. May be read and written using
+\fBTcl_GetEnsembleMappingDict\fR and \fBTcl_SetEnsembleMappingDict\fR
+respectively. The result of both of those functions is a Tcl result
+code (TCL_OK, or TCL_ERROR if the token does not refer to an
+ensemble) and the dictionary obtained from
+\fBTcl_GetEnsembleMappingDict\fR should always be treated as immutable
+even if it is unshared.
+All command names in prefixes set via \fBTcl_SetEnsembleMappingDict\fR
+must be fully qualified.
+.TP
+\fBsubcommand list\fR (read-write)
+A list of all the subcommand names for the ensemble, or NULL if this
+is to be derived from either the keys of the mapping dictionary (see
+above) or (if that is also NULL) from the set of commands exported by
+the bound namespace. May be read and written using
+\fBTcl_GetEnsembleSubcommandList\fR and
+\fBTcl_SetEnsembleSubcommandList\fR respectively. The result of both
+of those functions is a Tcl result code (TCL_OK, or TCL_ERROR if the
+token does not refer to an ensemble) and the list obtained from
+\fBTcl_GetEnsembleSubcommandList\fR should always be treated as
+immutable even if it is unshared.
+.TP
+\fBunknown subcommand handler command prefix\fR (read-write)
+A list of words to prepend on the front of any subcommand when the
+subcommand is unknown to the ensemble (according to the current prefix
+handling rule); see the \fBnamespace ensemble\fR command for more
+details. If NULL, the default behavior \- generate a suitable error
+message \- will be used when an unknown subcommand is encountered. May
+be read and written using \fBTcl_GetEnsembleUnknownHandler\fR and
+\fBTcl_SetEnsembleUnknownHandler\fR respectively. The result of both
+functions is a Tcl result code (TCL_OK, or TCL_ERROR if the token does
+not refer to an ensemble) and the list obtained from
+\fBTcl_GetEnsembleUnknownHandler\fR should always be treated as
+immutable even if it is unshared.
+.TP
+\fBbound namespace\fR (read-only)
+The namespace to which the ensemble is bound; when the namespace is
+deleted, so too will the ensemble, and this namespace is also the
+namespace whose list of exported commands is used if both the mapping
+dictionary and the subcommand list properties are NULL. May be read
+using \fBTcl_GetEnsembleNamespace\fR which returns a Tcl result code
+(TCL_OK, or TCL_ERROR if the token does not refer to an ensemble).
+
+.SH "SEE ALSO"
+namespace(n), Tcl_DeleteCommandFromToken(3)
diff --git a/doc/Environment.3 b/doc/Environment.3
index 7f92d48..3753f43 100644
--- a/doc/Environment.3
+++ b/doc/Environment.3
@@ -14,21 +14,25 @@ Tcl_PutEnv \- procedures to manipulate the environment
\fB#include <tcl.h>\fR
.sp
int
-\fBTcl_PutEnv\fR(\fIstring\fR)
+\fBTcl_PutEnv\fR(\fIassignment\fR)
.SH ARGUMENTS
-.AP "CONST char" *string in
-Info about environment variable in the form NAME=value.
-The \fIstring\fR argument is in the system encoding.
+.AS "const char" *assignment
+.AP "const char" *assignment in
+Info about environment variable in the format
+.QW \fINAME\fB=\fIvalue\fR .
+The \fIassignment\fR argument is in the system encoding.
.BE
-
.SH DESCRIPTION
.PP
\fBTcl_PutEnv\fR sets an environment variable. The information is
-passed in a single string of the form NAME=value. This procedure is
+passed in a single string of the form
+.QW \fINAME\fB=\fIvalue\fR .
+This procedure is
intended to be a stand-in for the UNIX \fBputenv\fR system call. All
-tcl-based applications using \fBputenv\fR should redefine it to
+Tcl-based applications using \fBputenv\fR should redefine it to
\fBTcl_PutEnv\fR so that they will interface properly to the Tcl
runtime.
-
+.SH "SEE ALSO"
+tclvars(n)
.SH KEYWORDS
environment, variable
diff --git a/doc/Eval.3 b/doc/Eval.3
index 1efe270..f232cad 100644
--- a/doc/Eval.3
+++ b/doc/Eval.3
@@ -15,7 +15,6 @@ Tcl_EvalObjEx, Tcl_EvalFile, Tcl_EvalObjv, Tcl_Eval, Tcl_EvalEx, Tcl_GlobalEval,
.nf
\fB#include <tcl.h>\fR
.sp
-.VS
int
\fBTcl_EvalObjEx\fR(\fIinterp, objPtr, flags\fR)
.sp
@@ -38,12 +37,12 @@ int
\fBTcl_GlobalEvalObj\fR(\fIinterp, objPtr\fR)
.sp
int
-\fBTcl_VarEval\fR(\fIinterp, string, string, ... \fB(char *) NULL\fR)
+\fBTcl_VarEval\fR(\fIinterp, part, part, ... \fB(char *) NULL\fR)
.sp
int
\fBTcl_VarEvalVA\fR(\fIinterp, argList\fR)
.SH ARGUMENTS
-.AS Tcl_Interp **termPtr;
+.AS Tcl_Interp **termPtr
.AP Tcl_Interp *interp in
Interpreter in which to execute the script. The interpreter's result is
modified to hold the result or error message from the script.
@@ -52,7 +51,7 @@ A Tcl object containing the script to execute.
.AP int flags in
ORed combination of flag bits that specify additional options.
\fBTCL_EVAL_GLOBAL\fR and \fBTCL_EVAL_DIRECT\fR are currently supported.
-.AP "CONST char" *fileName in
+.AP "const char" *fileName in
Name of a file containing a Tcl script.
.AP int objc in
The number of objects in the array pointed to by \fIobjPtr\fR;
@@ -64,13 +63,13 @@ value of a single word in the command to execute.
The number of bytes in \fIscript\fR, not including any
null terminating character. If \-1, then all characters up to the
first null byte are used.
-.AP "CONST char" *script in
+.AP "const char" *script in
Points to first byte of script to execute (null-terminated and UTF-8).
-.AP char *string in
+.AP char *part in
String forming part of a Tcl script.
.AP va_list argList in
-An argument list which must have been initialised using
-\fBTCL_VARARGS_START\fR, and cleared using \fBva_end\fR.
+An argument list which must have been initialized using
+\fBva_start\fR, and cleared using \fBva_end\fR.
.BE
.SH DESCRIPTION
@@ -97,26 +96,33 @@ result; it can be retrieved using \fBTcl_GetObjResult\fR.
\fBTcl_EvalFile\fR reads the file given by \fIfileName\fR and evaluates
its contents as a Tcl script. It returns the same information as
\fBTcl_EvalObjEx\fR.
-If the file couldn't be read then a Tcl error is returned to describe
-why the file couldn't be read.
-.VS 8.4
-The eofchar for files is '\\32' (^Z) for all platforms.
-If you require a ``^Z'' in code for string comparison, you can use
-``\\032'' or ``\\u001a'', which will be safely substituted by the Tcl
-interpreter into ``^Z''.
-.VE 8.4
+If the file could not be read then a Tcl error is returned to describe
+why the file could not be read.
+The eofchar for files is
+.QW \e32
+(^Z) for all platforms. If you require a
+.QW ^Z
+in code for string comparison, you can use
+.QW \e032
+or
+.QW \eu001a ,
+which will be safely substituted by the Tcl interpreter into
+.QW ^Z .
.PP
\fBTcl_EvalObjv\fR executes a single pre-parsed command instead of a
script. The \fIobjc\fR and \fIobjv\fR arguments contain the values
of the words for the Tcl command, one word in each object in
\fIobjv\fR. \fBTcl_EvalObjv\fR evaluates the command and returns
a completion code and result just like \fBTcl_EvalObjEx\fR.
+The caller of \fBTcl_EvalObjv\fR has to manage the reference count of the
+elements of \fIobjv\fR, insuring that the objects are valid until
+\fBTcl_EvalObjv\fR returns.
.PP
\fBTcl_Eval\fR is similar to \fBTcl_EvalObjEx\fR except that the script to
be executed is supplied as a string instead of an object and no compilation
occurs. The string should be a proper UTF-8 string as converted by
\fBTcl_ExternalToUtfDString\fR or \fBTcl_ExternalToUtf\fR when it is known
-to possibly contain upper ASCII characters who's possible combinations
+to possibly contain upper ASCII characters whose possible combinations
might be a UTF-8 special code. The string is parsed and executed directly
(using \fBTcl_EvalObjv\fR) instead of compiling it and executing the
bytecodes. In situations where it is known that the script will never be
@@ -126,7 +132,7 @@ executed again, \fBTcl_Eval\fR may be faster than \fBTcl_EvalObjEx\fR.
Tcl 8.0, \fBTcl_Eval\fR copies the object result in \fIinterp\fR to
\fIinterp->result\fR (use is deprecated) where it can be accessed directly.
This makes \fBTcl_Eval\fR somewhat slower than \fBTcl_EvalEx\fR, which
-doesn't do the copy.
+does not do the copy.
.PP
\fBTcl_EvalEx\fR is an extended version of \fBTcl_Eval\fR that takes
additional arguments \fInumBytes\fR and \fIflags\fR. For the
@@ -163,8 +169,8 @@ compiled to bytecodes; instead it is executed directly
as is done by \fBTcl_EvalEx\fR. The
\fBTCL_EVAL_DIRECT\fR flag is useful in situations where the
contents of an object are going to change immediately, so the
-bytecodes won't be reused in a future execution. In this case,
-it's faster to execute the script directly.
+bytecodes will not be reused in a future execution. In this case,
+it is faster to execute the script directly.
.TP 23
\fBTCL_EVAL_GLOBAL\fR
If this flag is set, the script is processed at global level. This
@@ -197,7 +203,6 @@ the \fBreturn\fR, \fBbreak\fR, or \fBcontinue\fR command was
invoked in an inappropriate place.
This means that top-level applications should never see a return code
from \fBTcl_EvalObjEx\fR other then \fBTCL_OK\fR or \fBTCL_ERROR\fR.
-.VE
.SH KEYWORDS
execute, file, global, object, result, script
diff --git a/doc/Exit.3 b/doc/Exit.3
index a281829..aa69b47 100644
--- a/doc/Exit.3
+++ b/doc/Exit.3
@@ -5,10 +5,10 @@
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.so man.macros
-.TH Tcl_Exit 3 8.1 Tcl "Tcl Library Procedures"
+.TH Tcl_Exit 3 8.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
-Tcl_Exit, Tcl_Finalize, Tcl_CreateExitHandler, Tcl_DeleteExitHandler, Tcl_ExitThread, Tcl_FinalizeThread, Tcl_CreateThreadExitHandler, Tcl_DeleteThreadExitHandler \- end the application or thread (and invoke exit handlers)
+Tcl_Exit, Tcl_Finalize, Tcl_CreateExitHandler, Tcl_DeleteExitHandler, Tcl_ExitThread, Tcl_FinalizeThread, Tcl_CreateThreadExitHandler, Tcl_DeleteThreadExitHandler, Tcl_SetExitProc \- end the application or thread (and invoke exit handlers)
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
@@ -28,6 +28,11 @@ Tcl_Exit, Tcl_Finalize, Tcl_CreateExitHandler, Tcl_DeleteExitHandler, Tcl_ExitTh
\fBTcl_CreateThreadExitHandler\fR(\fIproc, clientData\fR)
.sp
\fBTcl_DeleteThreadExitHandler\fR(\fIproc, clientData\fR)
+.sp
+.VS 8.5
+Tcl_ExitProc *
+\fBTcl_SetExitProc\fR(\fIproc\fR)
+.VE 8.5
.SH ARGUMENTS
.AS Tcl_ExitProc clientData
.AP int status in
@@ -36,7 +41,9 @@ Exact meaning may
be platform-specific. 0 usually means a normal exit, any nonzero value
usually means that an error occurred.
.AP Tcl_ExitProc *proc in
-Procedure to invoke before exiting application.
+Procedure to invoke before exiting application, or (for
+\fBTcl_SetExitProc\fR) NULL to uninstall the current application exit
+procedure.
.AP ClientData clientData in
Arbitrary one-word value to pass to \fIproc\fR.
.BE
@@ -57,6 +64,12 @@ otherwise causes the application to terminate without calling
\fBTcl_Exit\fR, the exit handlers will not be run.
\fBTcl_Exit\fR internally invokes the \fBexit\fR system call, thus it never
returns control to its caller.
+.VS 8.5
+If an application exit handler has been installed (see
+\fBTcl_SetExitProc\fR), that handler is invoked with an argument
+consisting of the exit status (cast to ClientData); the application
+exit handler should not return control to Tcl.
+.VE 8.5
.PP
\fBTcl_Finalize\fR is similar to \fBTcl_Exit\fR except that it does not
exit from the current process.
@@ -71,14 +84,12 @@ However, to ensure portability, your code should always invoke
code will work on all platforms. \fBTcl_Finalize\fR can be safely called
more than once.
.PP
-.VS
\fBTcl_ExitThread\fR is used to terminate the current thread and invoke
per-thread exit handlers. This finalization is done by
\fBTcl_FinalizeThread\fR, which you can call if you just want to clean
up per-thread state and invoke the thread exit handlers.
\fBTcl_Finalize\fR calls \fBTcl_FinalizeThread\fR for the current
thread automatically.
-.VE
.PP
\fBTcl_CreateExitHandler\fR arranges for \fIproc\fR to be invoked
by \fBTcl_Finalize\fR and \fBTcl_Exit\fR.
@@ -105,7 +116,6 @@ indicated by \fIproc\fR and \fIclientData\fR so that no call
to \fIproc\fR will be made. If no such handler exists then
\fBTcl_DeleteExitHandler\fR or \fBTcl_DeleteThreadExitHandler\fR does nothing.
.PP
-.VS
.PP
\fBTcl_Finalize\fR and \fBTcl_Exit\fR execute all registered exit handlers,
in reverse order from the order in which they were registered.
@@ -115,15 +125,23 @@ unloads \fBB\fR before it itself is unloaded.
If extension \fBA\fR registers its exit handlers before loading extension
\fBB\fR, this ensures that any exit handlers for \fBB\fR will be executed
before the exit handlers for \fBA\fR.
-.VE
-.VS
.PP
\fBTcl_Finalize\fR and \fBTcl_Exit\fR call \fBTcl_FinalizeThread\fR
and the thread exit handlers \fIafter\fR
the process-wide exit handlers. This is because thread finalization shuts
down the I/O channel system, so any attempt at I/O by the global exit
handlers will vanish into the bitbucket.
-.VE
+.PP
+.VS 8.5
+\fBTcl_SetExitProc\fR installs an application exit handler, returning
+the previously-installed application exit handler or NULL if no
+application handler was installed. If an application exit handler is
+installed, that exit handler takes over complete responsibility for
+finalization of Tcl's subsystems via \fBTcl_Finalize\fR at an
+appropriate time. The argument passed to \fIproc\fR when it is
+invoked will be the exit status code (as passed to \fBTcl_Exit\fR)
+cast to a ClientData value.
+.VE 8.5
.SH KEYWORDS
callback, cleanup, dynamic loading, end application, exit, unloading, thread
diff --git a/doc/ExprLong.3 b/doc/ExprLong.3
index ead98f5..ef93284 100644
--- a/doc/ExprLong.3
+++ b/doc/ExprLong.3
@@ -15,23 +15,21 @@ Tcl_ExprLong, Tcl_ExprDouble, Tcl_ExprBoolean, Tcl_ExprString \- evaluate an exp
\fB#include <tcl.h>\fR
.sp
int
-\fBTcl_ExprLong\fR(\fIinterp, string, longPtr\fR)
+\fBTcl_ExprLong\fR(\fIinterp, expr, longPtr\fR)
.sp
int
-\fBTcl_ExprDouble\fR(\fIinterp, string, doublePtr\fR)
+\fBTcl_ExprDouble\fR(\fIinterp, expr, doublePtr\fR)
.sp
int
-\fBTcl_ExprBoolean\fR(\fIinterp, string, booleanPtr\fR)
+\fBTcl_ExprBoolean\fR(\fIinterp, expr, booleanPtr\fR)
.sp
int
-\fBTcl_ExprString\fR(\fIinterp, string\fR)
+\fBTcl_ExprString\fR(\fIinterp, expr\fR)
.SH ARGUMENTS
-.AS Tcl_Interp *booleanPtr
+.AS Tcl_Interp *booleanPtr out
.AP Tcl_Interp *interp in
-Interpreter in whose context to evaluate \fIstring\fR.
-.VS 8.4
-.AP "CONST char" *string in
-.VE
+Interpreter in whose context to evaluate \fIexpr\fR.
+.AP "const char" *expr in
Expression to be evaluated.
.AP long *longPtr out
Pointer to location in which to store the integer value of the
@@ -47,7 +45,7 @@ expression.
.SH DESCRIPTION
.PP
These four procedures all evaluate the expression
-given by the \fIstring\fR argument
+given by the \fIexpr\fR argument
and return the result in one of four different forms.
The expression can have any of the forms accepted by the \fBexpr\fR command.
Note that these procedures have been largely replaced by the
@@ -92,7 +90,11 @@ number, then they store 0 at \fI*booleanPtr\fR if
the value was zero and 1 otherwise.
If the expression's actual value is a non-numeric string then
it must be one of the values accepted by \fBTcl_GetBoolean\fR
-such as ``yes'' or ``no'', or else an error occurs.
+such as
+.QW yes
+or
+.QW no ,
+or else an error occurs.
.PP
\fBTcl_ExprString\fR returns the value of the expression as a
string stored in the interpreter's result.
diff --git a/doc/ExprLongObj.3 b/doc/ExprLongObj.3
index c3e9697..c8a564d 100644
--- a/doc/ExprLongObj.3
+++ b/doc/ExprLongObj.3
@@ -86,7 +86,11 @@ number, then they store 0 at \fI*booleanPtr\fR if
the value was zero and 1 otherwise.
If the expression's actual value is a non-numeric string then
it must be one of the values accepted by \fBTcl_GetBoolean\fR
-such as ``yes'' or ``no'', or else an error occurs.
+such as
+.QW yes
+or
+.QW no ,
+or else an error occurs.
.PP
If \fBTcl_ExprObj\fR successfully evaluates the expression,
it stores a pointer to the Tcl object
diff --git a/doc/FileSystem.3 b/doc/FileSystem.3
index 3cb2c7e..c4a28c2 100644
--- a/doc/FileSystem.3
+++ b/doc/FileSystem.3
@@ -8,7 +8,7 @@
.TH Filesystem 3 8.4 Tcl "Tcl Library Procedures"
.BS
.SH NAME
-Tcl_FSRegister, Tcl_FSUnregister, Tcl_FSData, Tcl_FSMountsChanged, Tcl_FSGetFileSystemForPath, Tcl_FSGetPathType, Tcl_FSCopyFile, Tcl_FSCopyDirectory, Tcl_FSCreateDirectory, Tcl_FSDeleteFile, Tcl_FSRemoveDirectory, Tcl_FSRenameFile, Tcl_FSListVolumes, Tcl_FSEvalFile, Tcl_FSLoadFile, Tcl_FSMatchInDirectory, Tcl_FSLink, Tcl_FSLstat, Tcl_FSUtime, Tcl_FSFileAttrsGet, Tcl_FSFileAttrsSet, Tcl_FSFileAttrStrings, Tcl_FSStat, Tcl_FSAccess, Tcl_FSOpenFileChannel, Tcl_FSGetCwd, Tcl_FSChdir, Tcl_FSPathSeparator, Tcl_FSJoinPath, Tcl_FSSplitPath, Tcl_FSEqualPaths, Tcl_FSGetNormalizedPath, Tcl_FSJoinToPath, Tcl_FSConvertToPathType, Tcl_FSGetInternalRep, Tcl_FSGetTranslatedPath, Tcl_FSGetTranslatedStringPath, Tcl_FSNewNativePath, Tcl_FSGetNativePath, Tcl_FSFileSystemInfo, Tcl_AllocStatBuf \- procedures to interact with any filesystem
+Tcl_FSRegister, Tcl_FSUnregister, Tcl_FSData, Tcl_FSMountsChanged, Tcl_FSGetFileSystemForPath, Tcl_FSGetPathType, Tcl_FSCopyFile, Tcl_FSCopyDirectory, Tcl_FSCreateDirectory, Tcl_FSDeleteFile, Tcl_FSRemoveDirectory, Tcl_FSRenameFile, Tcl_FSListVolumes, Tcl_FSEvalFile, Tcl_FSEvalFileEx, Tcl_FSLoadFile, Tcl_FSMatchInDirectory, Tcl_FSLink, Tcl_FSLstat, Tcl_FSUtime, Tcl_FSFileAttrsGet, Tcl_FSFileAttrsSet, Tcl_FSFileAttrStrings, Tcl_FSStat, Tcl_FSAccess, Tcl_FSOpenFileChannel, Tcl_FSGetCwd, Tcl_FSChdir, Tcl_FSPathSeparator, Tcl_FSJoinPath, Tcl_FSSplitPath, Tcl_FSEqualPaths, Tcl_FSGetNormalizedPath, Tcl_FSJoinToPath, Tcl_FSConvertToPathType, Tcl_FSGetInternalRep, Tcl_FSGetTranslatedPath, Tcl_FSGetTranslatedStringPath, Tcl_FSNewNativePath, Tcl_FSGetNativePath, Tcl_FSFileSystemInfo, Tcl_AllocStatBuf \- procedures to interact with any filesystem
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
@@ -26,10 +26,10 @@ void
\fBTcl_FSMountsChanged\fR(\fIfsPtr\fR)
.sp
Tcl_Filesystem*
-\fBTcl_FSGetFileSystemForPath\fR(\fIpathObjPtr\fR)
+\fBTcl_FSGetFileSystemForPath\fR(\fIpathPtr\fR)
.sp
Tcl_PathType
-\fBTcl_FSGetPathType\fR(\fIpathObjPtr\fR)
+\fBTcl_FSGetPathType\fR(\fIpathPtr\fR)
.sp
int
\fBTcl_FSCopyFile\fR(\fIsrcPathPtr, destPathPtr\fR)
@@ -52,6 +52,11 @@ int
Tcl_Obj*
\fBTcl_FSListVolumes\fR(\fIvoid\fR)
.sp
+.VS 8.5
+int
+\fBTcl_FSEvalFileEx\fR(\fIinterp, pathPtr, encodingName\fR)
+.VE 8.5
+.sp
int
\fBTcl_FSEvalFile\fR(\fIinterp, pathPtr\fR)
.sp
@@ -60,7 +65,7 @@ int
handlePtr, unloadProcPtr\fR)
.sp
int
-\fBTcl_FSMatchInDirectory\fR(\fIinterp, result, pathPtr, pattern, types\fR)
+\fBTcl_FSMatchInDirectory\fR(\fIinterp, resultPtr, pathPtr, pattern, types\fR)
.sp
Tcl_Obj*
\fBTcl_FSLink\fR(\fIlinkNamePtr, toPtr, linkAction\fR)
@@ -77,7 +82,7 @@ int
int
\fBTcl_FSFileAttrsSet\fR(\fIinterp, int index, pathPtr, Tcl_Obj *objPtr\fR)
.sp
-CONST char**
+const char**
\fBTcl_FSFileAttrStrings\fR(\fIpathPtr, objPtrRef\fR)
.sp
int
@@ -86,7 +91,7 @@ int
int
\fBTcl_FSAccess\fR(\fIpathPtr, mode\fR)
.sp
-Tcl_Channel
+Tcl_Channel
\fBTcl_FSOpenFileChannel\fR(\fIinterp, pathPtr, modeString, permissions\fR)
.sp
Tcl_Obj*
@@ -116,19 +121,19 @@ Tcl_Obj*
int
\fBTcl_FSConvertToPathType\fR(\fIinterp, pathPtr\fR)
.sp
-ClientData
+ClientData
\fBTcl_FSGetInternalRep\fR(\fIpathPtr, fsPtr\fR)
.sp
-Tcl_Obj*
+Tcl_Obj *
\fBTcl_FSGetTranslatedPath\fR(\fIinterp, pathPtr\fR)
.sp
-CONST char*
+const char *
\fBTcl_FSGetTranslatedStringPath\fR(\fIinterp, pathPtr\fR)
.sp
Tcl_Obj*
\fBTcl_FSNewNativePath\fR(\fIfsPtr, clientData\fR)
.sp
-CONST char*
+const char *
\fBTcl_FSGetNativePath\fR(\fIpathPtr\fR)
.sp
Tcl_Obj*
@@ -137,7 +142,7 @@ Tcl_Obj*
Tcl_StatBuf*
\fBTcl_AllocStatBuf\fR()
.SH ARGUMENTS
-.AS Tcl_Filesystem *fsPtr in
+.AS Tcl_FSUnloadFileProc **unloadProcPtr out
.AP Tcl_Filesystem *fsPtr in
Points to a structure containing the addresses of procedures that
can be called to perform the various filesystem operations.
@@ -146,21 +151,21 @@ The path represented by this object is used for the operation in
question. If the object does not already have an internal \fBpath\fR
representation, it will be converted to have one.
.AP Tcl_Obj *srcPathPtr in
-As for \fBpathPtr\fR, but used for the source file for a copy or
+As for \fIpathPtr\fR, but used for the source file for a copy or
rename operation.
.AP Tcl_Obj *destPathPtr in
-As for \fBpathPtr\fR, but used for the destination filename for a copy or
+As for \fIpathPtr\fR, but used for the destination filename for a copy or
rename operation.
-.AP "CONST char" *pattern in
-Only files or directories matching this pattern will be returned by
-\fBTcl_FSMatchInDirectory\fR.
-.AP GlobTypeData *types in
+.AP "const char" *encodingName in
+The encoding of the data stored in the
+file identified by \fIpathPtr\fR and to be evaluated.
+.AP "const char" *pattern in
+Only files or directories matching this pattern will be returned.
+.AP Tcl_GlobTypeData *types in
Only files or directories matching the type descriptions contained in
-this structure will be returned by \fBTcl_FSMatchInDirectory\fR. It
-is very important that the 'directory' flag is properly handled.
-This parameter may be NULL.
+this structure will be returned. This parameter may be NULL.
.AP Tcl_Interp *interp in
-Interpreter to use either for results, evaluation, or reporting error
+Interpreter to use either for results, evaluation, or reporting error
messages.
.AP ClientData clientData in
The native description of the path object to create.
@@ -173,17 +178,17 @@ to \fBpath\fR type.
.AP Tcl_Obj *listObj in
The list of path elements to operate on with a \fBjoin\fR operation.
.AP int elements in
-If non-negative, the number of elements in the listObj which should
+If non-negative, the number of elements in the \fIlistObj\fR which should
be joined together. If negative, then all elements are joined.
.AP Tcl_Obj **errorPtr out
In the case of an error, filled with an object containing the name of
the file which caused an error in the various copy/rename operations.
.AP Tcl_Obj **objPtrRef out
Filled with an object containing the result of the operation.
-.AP Tcl_Obj *result out
-Pre-allocated object in which to store (by lappending) the list of
-files or directories which are successfully matched in
-\fBTcl_FSMatchInDirectory\fR.
+.AP Tcl_Obj *resultPtr out
+Pre-allocated object in which to store (using
+\fBTcl_ListObjAppendElement\fR) the list of
+files or directories which are successfully matched.
.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,
@@ -191,25 +196,25 @@ write and execute permissions, respectively. F_OK just requests
checking for the existence of the file.
.AP Tcl_StatBuf *statPtr out
The structure that contains the result of a stat or lstat operation.
-.AP "CONST char" *sym1 in
+.AP "const char" *sym1 in
Name of a procedure to look up in the file's symbol table
-.AP "CONST char" *sym2 in
+.AP "const char" *sym2 in
Name of a procedure to look up in the file's symbol table
.AP Tcl_PackageInitProc **proc1Ptr out
Filled with the init function for this code.
.AP Tcl_PackageInitProc **proc2Ptr out
Filled with the safe-init function for this code.
-.AP Tcl_LoadHandle *handlePtr out
-Filled with an abstract token representing the loaded file.
.AP ClientData *clientDataPtr out
Filled with the clientData value to pass to this code's unload
function when it is called.
-.AP TclfsUnloadFileProc_ **unloadProcPtr out
+.AP Tcl_LoadHandle *handlePtr out
+Filled with an abstract token representing the loaded file.
+.AP Tcl_FSUnloadFileProc **unloadProcPtr out
Filled with the function to use to unload this piece of code.
.AP utimbuf *tval in
-The access and modification times in this structure are read and
+The access and modification times in this structure are read and
used to set those values for a given file.
-.AP "CONST char" *modeString in
+.AP "const char" *modeString in
Specifies how the file is to be accessed. May have any of the values
allowed for the \fImode\fR argument to the Tcl \fBopen\fR command.
.AP int permissions in
@@ -221,151 +226,215 @@ If non-NULL, filled with the number of elements in the split path.
The base path on to which to join the given elements. May be NULL.
.AP int objc in
The number of elements in \fIobjv\fR.
-.AP "Tcl_Obj *CONST" objv[] in
+.AP "Tcl_Obj *const" objv[] in
The elements to join to the given base path.
+.AP Tcl_Obj *linkNamePtr in
+The name of the link to be created or read.
+.AP Tcl_Obj *toPtr in
+What the link called \fIlinkNamePtr\fR should be linked to, or NULL if
+the symbolic link specified by \fIlinkNamePtr\fR is to be read.
+.AP int linkAction in
+OR-ed combination of flags indicating what kind of link should be
+created (will be ignored if \fItoPtr\fR is NULL). Valid bits to set
+are \fBTCL_CREATE_SYMBOLIC_LINK\fR and \fBTCL_CREATE_HARD_LINK\fR.
+When both flags are set and the underlying filesystem can do either,
+symbolic links are preferred.
.BE
.SH DESCRIPTION
.PP
-There are several reasons for calling the \fBTcl_FS...\fR functions
+There are several reasons for calling the \fBTcl_FS\fR API functions
+(e.g. \fBTcl_FSAccess\fR and \fBTcl_FSStat\fR)
rather than calling system level functions like \fBaccess\fR and
\fBstat\fR directly. First, they will work cross-platform, so an
-extension which calls them should work unmodified on Unix, MacOS and
+extension which calls them should work unmodified on Unix and
Windows. Second, the Windows implementation of some of these functions
fixes some bugs in the system level calls. Third, these function calls
-deal with any 'Utf to platform-native' path conversions which may be
+deal with any
+.QW "Utf to platform-native"
+path conversions which may be
required (and may cache the results of such conversions for greater
efficiency on subsequent calls). Fourth, and perhaps most importantly,
-all of these functions are 'virtual filesystem aware'. Any virtual
-filesystem which has been registered (through
+all of these functions are
+.QW "virtual filesystem aware" .
+Any virtual filesystem (VFS for short) which has been registered (through
\fBTcl_FSRegister\fR) may reroute file access to alternative
media or access methods. This means that all of these functions (and
therefore the corresponding \fBfile\fR, \fBglob\fR, \fBpwd\fR, \fBcd\fR,
-\fBopen\fR, etc. Tcl commands) may be operate on 'files' which are not
+\fBopen\fR, etc. Tcl commands) may be operate on
+.QW files
+which are not
native files in the native filesystem. This also means that any Tcl
-extension which accesses the filesystem through this API is
-automatically 'virtual filesystem aware'. Of course, if an extension
+extension which accesses the filesystem (FS for short) through this API is
+automatically
+.QW "virtual filesystem aware" .
+Of course, if an extension
accesses the native filesystem directly (through platform-specific
-APIs, for example), then Tcl cannot intercept such calls.
+APIs, for example), then Tcl cannot intercept such calls.
.PP
-If appropriate vfs's have been registered, the 'files' may, to give two
+If appropriate VFSes have been registered, the
+.QW files
+may, to give two
examples, be remote (e.g. situated on a remote ftp server) or archived
(e.g. lying inside a .zip archive). Such registered filesystems provide
a lookup table of functions to implement all or some of the functionality
listed here. Finally, the \fBTcl_FSStat\fR and \fBTcl_FSLstat\fR calls
-abstract away from what the 'struct stat' buffer buffer is actually
+abstract away from what the
+.QW "struct stat"
+buffer is actually
declared to be, allowing the same code to be used both on systems with
and systems without support for files larger than 2GB in size.
.PP
-The \fBTcl_FS...\fR are objectified and may cache internal
+The \fBTcl_FS\fR API is objectified and may cache internal
representations and other path-related strings (e.g. the current working
directory). One side-effect of this is that one must not pass in objects
-with a refCount of zero to any of these functions. If such calls were
+with a reference count of zero to any of these functions. If such calls were
handled, they might result
in memory leaks (under some circumstances, the filesystem code may wish
to retain a reference to the passed in object, and so one must not assume
-that after any of these calls return, the object still has a refCount of
-zero - it may have been incremented), or in a direct segfault
+that after any of these calls return, the object still has a reference count of
+zero - it may have been incremented) or in a direct segmentation fault
+(or other memory access error)
due to the object being freed part way through the complex object
manipulation required to ensure that the path is fully normalized and
absolute for filesystem determination. The practical lesson to learn
-from this is that \fBTcl_Obj *path = Tcl_NewStringObj(...) ;
-Tcl_FS...(path) ; Tcl_DecrRefCount(path)\fR is wrong, and may segfault.
-The 'path' must have its refCount incremented before passing it in, or
-decrementing it. For this reason, objects with a refCount of zero are
+from this is that
+.CS
+Tcl_Obj *path = Tcl_NewStringObj(...);
+Tcl_FS\fIWhatever\fR(path);
+Tcl_DecrRefCount(path);
+.CE
+is wrong, and may cause memory errors. The \fIpath\fR must have its
+reference count incremented before passing it in, or
+decrementing it. For this reason, objects with a reference count of zero are
considered not to be valid filesystem paths and calling any Tcl_FS API
-with such an object will result in no action being taken.
-.PP
-\fBTcl_FSCopyFile\fR attempts to copy the file given by srcPathPtr to the
-path name given by destPathPtr. If the two paths given lie in the same
+function with such an object will result in no action being taken.
+.SS "FS API FUNCTIONS"
+\fBTcl_FSCopyFile\fR attempts to copy the file given by \fIsrcPathPtr\fR to the
+path name given by \fIdestPathPtr\fR. If the two paths given lie in the same
filesystem (according to \fBTcl_FSGetFileSystemForPath\fR) then that
-filesystem's 'copy file' function is called (if it is non-NULL).
-Otherwise the function returns -1 and sets Tcl's errno to the 'EXDEV'
-posix error code (which signifies a 'cross-domain link').
-.PP
-\fBTcl_FSCopyDirectory\fR attempts to copy the directory given by srcPathPtr to the
-path name given by destPathPtr. If the two paths given lie in the same
+filesystem's
+.QW "copy file"
+function is called (if it is non-NULL).
+Otherwise the function returns -1 and sets the \fBerrno\fR global C
+variable to the
+.QW EXDEV
+POSIX error code (which signifies a
+.QW "cross-domain link" ).
+.PP
+\fBTcl_FSCopyDirectory\fR attempts to copy the directory given by \fIsrcPathPtr\fR to the
+path name given by \fIdestPathPtr\fR. If the two paths given lie in the same
filesystem (according to \fBTcl_FSGetFileSystemForPath\fR) then that
-filesystem's 'copy file' function is called (if it is non-NULL).
-Otherwise the function returns -1 and sets Tcl's errno to the 'EXDEV'
-posix error code (which signifies a 'cross-domain link').
+filesystem's
+.QW "copy file"
+function is called (if it is non-NULL).
+Otherwise the function returns -1 and sets the \fBerrno\fR global C
+variable to the
+.QW EXDEV
+POSIX error code (which signifies a
+.QW "cross-domain link" ).
.PP
\fBTcl_FSCreateDirectory\fR attempts to create the directory given by
-pathPtr by calling the owning filesystem's 'create directory'
+\fIpathPtr\fR by calling the owning filesystem's
+.QW "create directory"
function.
.PP
\fBTcl_FSDeleteFile\fR attempts to delete the file given by
-pathPtr by calling the owning filesystem's 'delete file'
+\fIpathPtr\fR by calling the owning filesystem's
+.QW "delete file"
function.
.PP
\fBTcl_FSRemoveDirectory\fR attempts to remove the directory given by
-pathPtr by calling the owning filesystem's 'remove directory'
+\fIpathPtr\fR by calling the owning filesystem's
+.QW "remove directory"
function.
.PP
\fBTcl_FSRenameFile\fR attempts to rename the file or directory given by
-srcPathPtr to the path name given by destPathPtr. If the two paths
+\fIsrcPathPtr\fR to the path name given by \fIdestPathPtr\fR. If the two paths
given lie in the same filesystem (according to
-\fBTcl_FSGetFileSystemForPath\fR) then that filesystem's 'rename file'
+\fBTcl_FSGetFileSystemForPath\fR) then that filesystem's
+.QW "rename file"
function is called (if it is non-NULL). Otherwise the function returns -1
-and sets Tcl's errno to the 'EXDEV' posix error code (which signifies
-a ``cross-domain link'').
-.PP
-\fBTcl_FSListVolumes\fR calls each filesystem which has a non-NULL 'list
-volumes' function and asks them to return their list of root volumes. It
+and sets the \fBerrno\fR global C variable to the
+.QW EXDEV
+POSIX error code (which signifies a
+.QW "cross-domain link" ).
+.PP
+\fBTcl_FSListVolumes\fR calls each filesystem which has a non-NULL
+.QW "list volumes"
+function and asks them to return their list of root volumes. It
accumulates the return values in a list which is returned to the
-caller (with a refCount of 0).
+caller (with a reference count of 0).
.PP
-\fBTcl_FSEvalFile\fR reads the file given by \fIpathPtr\fR and evaluates
+.VS 8.5
+\fBTcl_FSEvalFileEx\fR reads the file given by \fIpathPtr\fR using
+the encoding identified by \fIencodingName\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.
-The eofchar for files is '\\32' (^Z) for all platforms.
-If you require a ``^Z'' in code for string comparison, you can use
-``\\032'' or ``\\u001a'', which will be safely substituted by the Tcl
-interpreter into ``^Z''.
+If \fIencodingName\fR is NULL, the system encoding is used for
+reading the file contents.
+If the file could not be read then a Tcl error is returned to describe
+why the file could not be read.
+The eofchar for files is
+.QW \e32
+(^Z) for all platforms.
+If you require a
+.QW ^Z
+in code for string comparison, you can use
+.QW \e032
+or
+.QW \eu001a ,
+which will be safely substituted by the Tcl interpreter into
+.QW ^Z .
+\fBTcl_FSEvalFile\fR is a simpler version of
+\fBTcl_FSEvalFileEx\fR that always uses the system encoding
+when reading the file.
+.VE 8.5
.PP
\fBTcl_FSLoadFile\fR dynamically loads a binary code file into memory and
returns the addresses of two procedures within that file, if they are
-defined. The appropriate function for the filesystem to which pathPtr
+defined. The appropriate function for the filesystem to which \fIpathPtr\fR
belongs will be called. If that filesystem does not implement this
function (most virtual filesystems will not, because of OS limitations
in dynamically loading binary code), Tcl will attempt to copy the file
to a temporary directory and load that temporary file.
.PP
Returns a standard Tcl completion code. If an error occurs, an error
-message is left in the interp's result.
+message is left in the \fIinterp\fR's result.
.PP
\fBTcl_FSMatchInDirectory\fR is used by the globbing code to search a
directory for all files which match a given pattern. The appropriate
-function for the filesystem to which pathPtr belongs will be called.
+function for the filesystem to which \fIpathPtr\fR belongs will be called.
.PP
The return value is a standard Tcl result indicating whether an error
-occurred in globbing. Error messages are placed in interp, but good
-results are placed in the resultPtr given.
-
-Note that the 'glob' code implements recursive patterns internally, so
+occurred in globbing. Error messages are placed in interp (unless
+interp is NULL, which is allowed), but good results are placed in the
+resultPtr given.
+.PP
+Note that the \fBglob\fR code implements recursive patterns internally, so
this function will only ever be passed simple patterns, which can be
-matched using the logic of 'string match'. To handle recursion, Tcl
+matched using the logic of \fBstring match\fR. To handle recursion, Tcl
will call this function frequently asking only for directories to be
-returned.
+returned. A special case of being called with a NULL pattern indicates
+that the path needs to be checked only for the correct type.
.PP
-\fBTcl_FSLink\fR replaces the library version of readlink(), and
-extends it to support the creation of links. The appropriate function
-for the filesystem to which linkNamePtr belongs will be called.
+\fBTcl_FSLink\fR replaces the library version of \fBreadlink\fR, and
+extends it to support the creation of links. The appropriate function
+for the filesystem to which \fIlinkNamePtr\fR belongs will be called.
.PP
-If the \fItoPtr\fR is NULL, a readlink action is performed. The result
+If the \fItoPtr\fR is NULL, a
+.QW "read link"
+action is performed. The result
is a Tcl_Obj specifying the contents of the symbolic link given by
\fIlinkNamePtr\fR, or NULL if the link could not be read. The result is owned
by the caller, which should call Tcl_DecrRefCount when the result is no
longer needed. If the \fItoPtr\fR is not NULL, Tcl should create a link
of one of the types passed in in the \fIlinkAction\fR flag. This flag is
-an or'd combination of TCL_CREATE_SYMBOLIC_LINK and TCL_CREATE_HARD_LINK.
+an ORed combination of \fBTCL_CREATE_SYMBOLIC_LINK\fR and \fBTCL_CREATE_HARD_LINK\fR.
Where a choice exists (i.e. more than one flag is passed in), the Tcl
convention is to prefer symbolic links. When a link is successfully
created, the return value should be \fItoPtr\fR (which is therefore
-already owned by the caller). If unsuccessful, NULL should be
-returned.
+already owned by the caller). If unsuccessful, NULL is returned.
.PP
\fBTcl_FSLstat\fR fills the stat structure \fIstatPtr\fR with information
about the specified file. You do not need any access rights to the
@@ -381,43 +450,49 @@ If \fIpath\fR exists, \fBTcl_FSLstat\fR returns 0 and the stat structure
is filled with data. Otherwise, -1 is returned, and no stat info is
given.
.PP
-\fBTcl_FSUtime\fR replaces the library version of utime.
+\fBTcl_FSUtime\fR replaces the library version of utime.
+.PP
+This returns 0 on success and -1 on error (as per the \fButime\fR
+documentation). If successful, the function
+will update the
+.QW atime
+and
+.QW mtime
+values of the file given.
.PP
-For results see 'utime' documentation. If successful, the function
-will update the 'atime' and 'mtime' values of the file given.
+\fBTcl_FSFileAttrsGet\fR implements read access for the hookable \fBfile
+attributes\fR subcommand. The appropriate function for the filesystem to
+which \fIpathPtr\fR belongs will be called.
.PP
-\fBTcl_FSFileAttrsGet\fR implements read access for the hookable 'file
-attributes' subcommand. The appropriate function for the filesystem to
-which pathPtr belongs will be called.
+If the result is \fBTCL_OK\fR, then an object was placed in
+\fIobjPtrRef\fR, which
+will only be temporarily valid (unless \fBTcl_IncrRefCount\fR is called).
.PP
-If the result is TCL_OK, then an object was placed in objPtrRef, which
-will only be temporarily valid (unless Tcl_IncrRefCount is called).
+\fBTcl_FSFileAttrsSet\fR implements write access for the hookable \fBfile
+attributes\fR subcommand. The appropriate function for the filesystem to
+which \fIpathPtr\fR belongs will be called.
.PP
-\fBTcl_FSFileAttrsSet\fR implements write access for the hookable 'file
-attributes' subcommand. The appropriate function for the filesystem to
-which pathPtr belongs will be called.
+\fBTcl_FSFileAttrStrings\fR implements part of the hookable \fBfile
+attributes\fR subcommand. The appropriate function for the filesystem
+to which \fIpathPtr\fR belongs will be called.
.PP
-\fBTcl_FSFileAttrStrings\fR implements part of the hookable 'file attributes'
-subcommand. The appropriate function for the filesystem to which
-pathPtr belongs will be called.
-.PP
The called procedure may either return an array of strings, or may
-instead return NULL and place a Tcl list into the given objPtrRef. Tcl
-will take that list and first increment its refCount before using it.
-On completion of that use, Tcl will decrement its refCount. Hence if
+instead return NULL and place a Tcl list into the given \fIobjPtrRef\fR. Tcl
+will take that list and first increment its reference count before using it.
+On completion of that use, Tcl will decrement its reference count. Hence if
the list should be disposed of by Tcl when done, it should have a
-refCount of zero, and if the list should not be disposed of, the
-filesystem should ensure it retains a refCount on the object.
+reference count of zero, and if the list should not be disposed of, the
+filesystem should ensure it retains a reference count to the object.
.PP
\fBTcl_FSAccess\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,
+write or test for existence of the file (or other filesystem object)
+whose name is \fIpathname\fR. If \fIpathname\fR 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.
+or some other error occurred), -1 is returned.
.PP
\fBTcl_FSStat\fR fills the stat structure \fIstatPtr\fR with information
about the specified file. You do not need any access rights to the
@@ -451,87 +526,110 @@ If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
previously closed, the act of creating the new channel also assigns it as a
replacement for the standard channel.
.PP
-\fBTcl_FSGetCwd\fR replaces the library version of getcwd().
+\fBTcl_FSGetCwd\fR replaces the library version of \fBgetcwd\fR.
.PP
It returns the Tcl library's current working directory. This may be
-different to the native platform's working directory, in the case for
-which the cwd is not in the native filesystem.
+different to the native platform's working directory, which happens when
+the current working directory is not in the native filesystem.
.PP
The result is a pointer to a Tcl_Obj 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.
-
-The result already has its refCount incremented for the caller. When
-it is no longer needed, that refCount should be decremented. This is
+returned, an error message is left in the \fIinterp\fR's result.
+.PP
+The result already has its reference count incremented for the caller. When
+it is no longer needed, that reference count should be decremented. This is
needed for thread-safety purposes, to allow multiple threads to access
this and related functions, while ensuring the results are always
valid.
.PP
-\fBTcl_FSChdir\fR replaces the library version of chdir(). The path is
+\fBTcl_FSChdir\fR replaces the library version of \fBchdir\fR. The path is
normalized and then passed to the filesystem which claims it. If that
-filesystem does not implement this function, Tcl will fallback to a
-combination of stat and access to check whether the directory exists
-and has appropriate permissions.
-.PP
-For results, see chdir() documentation. If successful, we keep a
-record of the successful path in cwdPathPtr for subsequent calls to
-getcwd.
-.PP
-\fBTcl_FSPathSeparator\fR returns the separator character to be used for
-most specific element of the path specified by pathPtr (i.e. the last
+filesystem does not implement this function, Tcl will fallback to a
+combination of \fBstat\fR and \fBaccess\fR to check whether the directory
+exists and has appropriate permissions.
+.PP
+For results, see \fBchdir\fR documentation. If successful, we keep a
+record of the successful path in \fIcwdPathPtr\fR for subsequent calls to
+\fBTcl_FSGetCwd\fR.
+.PP
+\fBTcl_FSPathSeparator\fR returns the separator character to be used for
+most specific element of the path specified by \fIpathPtr\fR (i.e. the last
part of the path).
.PP
The separator is returned as a Tcl_Obj containing a string of length
1. If the path is invalid, NULL is returned.
.PP
-\fBTcl_FSJoinPath\fR takes the given Tcl_Obj, which should be a valid list,
-and returns the path object given by considering the first 'elements'
-elements as valid path segments. If elements < 0, we use the entire
-list.
-.PP
-Returns object with refCount of zero, containing the joined path.
+\fBTcl_FSJoinPath\fR takes the given Tcl_Obj, which must be a valid
+list (which is allowed to have a reference count of zero), and returns the path
+object given by considering the first \fIelements\fR elements as valid path
+segments (each path segment may be a complete path, a partial path or
+just a single possible directory or file name). If any path segment is
+actually an absolute path, then all prior path segments are discarded.
+If \fIelements\fR is less than 0, we use the entire list.
+.PP
+It is possible that the returned object is actually an element
+of the given list, so the caller should be careful to increment the
+reference count of the result before freeing the list.
+.PP
+The returned object, typically with a reference count of zero (but it
+could be shared
+under some conditions), contains the joined path. The caller must
+add a reference count to the object before using it. In particular, the
+returned object could be an element of the given list, so freeing the
+list might free the object prematurely if no reference count has been taken.
+If the number of elements is zero, then the returned object will be
+an empty-string Tcl_Obj.
.PP
\fBTcl_FSSplitPath\fR takes the given Tcl_Obj, which should be a valid path,
-and returns a Tcl List object containing each segment of that path as
+and returns a Tcl list object containing each segment of that path as
an element.
-.PP
-Returns list object with refCount of zero. If the passed in lenPtr is
-non-NULL, we use it to return the number of elements in the returned
-list.
+It returns a list object with a reference count of zero. If the
+passed in \fIlenPtr\fR is non-NULL, the variable it points to will be
+updated to contain the number of elements in the returned list.
.PP
\fBTcl_FSEqualPaths\fR tests whether the two paths given represent the same
filesystem object
.PP
-It returns 1 if the paths are equal, and 0 if they are different. If
+It returns 1 if the paths are equal, and 0 if they are different. If
either path is NULL, 0 is always returned.
.PP
\fBTcl_FSGetNormalizedPath\fR this important function attempts to extract
from the given Tcl_Obj a unique normalized path representation, whose
string value can be used as a unique identifier for the file.
.PP
-It returns the normalized path object, with refCount of zero, or NULL
-if the path was invalid or could otherwise not be successfully
-converted. Extraction of absolute, normalized paths is very
-efficient (because the filesystem operates on these representations
-internally), although the result when the filesystem contains
-numerous symbolic links may not be the most user-friendly
-version of a path.
+It returns the normalized path object, owned by Tcl, or NULL if the path
+was invalid or could otherwise not be successfully converted.
+Extraction of absolute, normalized paths is very efficient (because the
+filesystem operates on these representations internally), although the
+result when the filesystem contains numerous symbolic links may not be
+the most user-friendly version of a path. The return value is owned by
+Tcl and has a lifetime equivalent to that of the \fIpathPtr\fR passed in
+(unless that is a relative path, in which case the normalized path
+object may be freed any time the cwd changes) - the caller can of
+course increment the refCount if it wishes to maintain a copy for longer.
.PP
\fBTcl_FSJoinToPath\fR takes the given object, which should usually be a
valid path or NULL, and joins onto it the array of paths segments
given.
.PP
-Returns object with refCount of zero, containing the joined path.
+Returns object, typically with refCount of zero (but it could be shared
+under some conditions), containing the joined path. The caller must
+add a refCount to the object before using it. If any of the objects
+passed into this function (pathPtr or path elements) have a refCount
+of zero, they will be freed when this function returns.
.PP
\fBTcl_FSConvertToPathType\fR tries to convert the given Tcl_Obj to a valid
Tcl path type, taking account of the fact that the cwd may have changed
even if this object is already supposedly of the correct type.
-The filename may begin with "~" (to indicate current user's home
-directory) or "~<user>" (to indicate any user's home directory).
-.PP
-If the conversion succeeds (i.e. the object is a valid path in one of
-the current filesystems), then TCL_OK is returned. Otherwise
-TCL_ERROR is returned, and an error message may
+The filename may begin with
+.QW ~
+(to indicate current user's home directory) or
+.QW ~<user>
+(to indicate any user's home directory).
+.PP
+If the conversion succeeds (i.e. the object is a valid path in one of
+the current filesystems), then \fBTCL_OK\fR is returned. Otherwise
+\fBTCL_ERROR\fR is returned, and an error message may
be left in the interpreter.
.PP
\fBTcl_FSGetInternalRep\fR extracts the internal representation of a given
@@ -545,12 +643,17 @@ representation is cached, so that repeated calls to this function will
not require additional conversions.
.PP
\fBTcl_FSGetTranslatedPath\fR attempts to extract the translated path
-from the given Tcl_Obj.
+from the given Tcl_Obj.
.PP
If the translation succeeds (i.e. the object is a valid path), then it is
returned. Otherwise NULL will be returned, and an error message may be
-left in the interpreter. A "translated" path is one which contains no
-"~" or "~user" sequences (these have been expanded to their current
+left in the interpreter. A
+.QW translated
+path is one which contains no
+.QW ~
+or
+.QW ~user
+sequences (these have been expanded to their current
representation in the filesystem). The object returned is owned by the
caller, which must store it or call Tcl_DecrRefCount to ensure memory is
freed. This function is of little practical use, and
@@ -560,37 +663,53 @@ better functions to use for most purposes.
\fBTcl_FSGetTranslatedStringPath\fR does the same as
\fBTcl_FSGetTranslatedPath\fR, but returns a character string or NULL.
The string returned is dynamically allocated and owned by the caller,
-which must store it or call ckfree to ensure it is freed. Again,
+which must store it or call \fBckfree\fR to ensure it is freed. Again,
\fBTcl_FSGetNormalizedPath\fR or \fBTcl_GetNativePath\fR are usually
better functions to use for most purposes.
.PP
-\fBTcl_FSNewNativePath\fR performs something like that reverse of the
+\fBTcl_FSNewNativePath\fR performs something like the reverse of the
usual obj->path->nativerep conversions. If some code retrieves a path
-in native form (from, e.g. readlink or a native dialog), and that path
+in native form (from, e.g. \fBreadlink\fR or a native dialog), and that path
is to be used at the Tcl level, then calling this function is an
efficient way of creating the appropriate path object type.
.PP
-The resulting object is a pure 'path' object, which will only receive
-a Utf-8 string representation if that is required by some Tcl code.
+The resulting object is a pure
+.QW path
+object, which will only receive
+a UTF-8 string representation if that is required by some Tcl code.
.PP
-\fBTcl_FSGetNativePath\fR is for use by the Win/Unix/MacOS native
+\fBTcl_FSGetNativePath\fR is for use by the Win/Unix native
filesystems, so that they can easily retrieve the native (char* or
TCHAR*) representation of a path. This function is a convenience
wrapper around \fBTcl_FSGetInternalRep\fR, and assumes the native
-representation is string-based. It may be desirable in the future
-to have non-string-based native representations (for example, on
-MacOS, a representation using a fileSpec of FSRef structure would
-probably be more efficient). On Windows a full Unicode
-representation would allow for paths of unlimited length. Currently
-the representation is simply a character string containing the
-complete, absolute path in the native encoding.
+representation is string-based. It may be desirable in the future to
+have non-string-based native representations (for example, on MacOSX, a
+representation using a fileSpec of FSRef structure would probably be
+more efficient). On Windows a full Unicode representation would allow
+for paths of unlimited length. Currently the representation is simply a
+character string which may contain either the relative path or a
+complete, absolute normalized path in the native encoding (complex
+conditions dictate which of these will be provided, so neither can be
+relied upon, unless the path is known to be absolute). If you need a
+native path which must be absolute, then you should ask for the native
+version of a normalized path. If for some reason a non-absolute,
+non-normalized version of the path is needed, that must be constructed
+separately (e.g. using \fBTcl_FSGetTranslatedPath\fR).
.PP
The native representation is cached so that repeated calls to this
-function will not require additional conversions.
+function will not require additional conversions. The return value is
+owned by Tcl and has a lifetime equivalent to that of the \fIpathPtr\fR
+passed in (unless that is a relative path, in which case the native
+representation may be freed any time the cwd changes).
.PP
\fBTcl_FSFileSystemInfo\fR returns a list of two elements. The first
-element is the name of the filesystem (e.g. "native" or "vfs" or "zip"
-or "prowrap", perhaps), and the second is the particular type of the
+element is the name of the filesystem (e.g.
+.QW native ,
+.QW vfs ,
+.QW zip ,
+or
+.QW prowrap ,
+perhaps), and the second is the particular type of the
given path within that filesystem (which is filesystem dependent). The
second element may be empty if the filesystem does not provide a
further categorization of files.
@@ -603,25 +722,24 @@ recognized, when NULL will be returned.
.PP
If no filesystem will accept the path, NULL is returned.
.PP
-\fBTcl_FSGetPathType\fR determines whether the given path is relative
+\fBTcl_FSGetPathType\fR determines whether the given path is relative
to the current directory, relative to the current volume, or
absolute.
.PP
-It returns one of TCL_PATH_ABSOLUTE, TCL_PATH_RELATIVE, or
-TCL_PATH_VOLUME_RELATIVE
+It returns one of \fBTCL_PATH_ABSOLUTE\fR, \fBTCL_PATH_RELATIVE\fR, or
+\fBTCL_PATH_VOLUME_RELATIVE\fR
.PP
\fBTcl_AllocStatBuf\fR allocates a \fITcl_StatBuf\fR on the system
heap (which may be deallocated by being passed to \fBckfree\fR.) This
allows extensions to invoke \fBTcl_FSStat\fR and \fBTcl_FSLStat\fR
without being dependent on the size of the buffer. That in turn
depends on the flags used to build Tcl.
-.PP
-.SH TCL_FILESYSTEM
+.SH "THE VIRTUAL FILESYSTEM API"
.PP
A filesystem provides a \fBTcl_Filesystem\fR structure that contains
pointers to functions that implement the various operations on a
filesystem; these operations are invoked as needed by the generic
-layer, which generally occurs through the functions listed above.
+layer, which generally occurs through the functions listed above.
.PP
The \fBTcl_Filesystem\fR structures are manipulated using the following
methods.
@@ -631,13 +749,13 @@ optional piece of data to associated with that filesystem. On calling
this function, Tcl will attach the filesystem to the list of known
filesystems, and it will become fully functional immediately. Tcl does
not check if the same filesystem is registered multiple times (and in
-general that is not a good thing to do). TCL_OK will be returned.
+general that is not a good thing to do). \fBTCL_OK\fR will be returned.
.PP
\fBTcl_FSUnregister\fR removes the given filesystem structure from
-the list of known filesystems, if it is known, and returns TCL_OK. If
-the filesystem is not currently registered, TCL_ERROR is returned.
+the list of known filesystems, if it is known, and returns \fBTCL_OK\fR. If
+the filesystem is not currently registered, \fBTCL_ERROR\fR is returned.
.PP
-\fBTcl_FSData\fR will return the ClientData associated with the given
+\fBTcl_FSData\fR will return the ClientData associated with the given
filesystem, if that filesystem is registered. Otherwise it will
return NULL.
.PP
@@ -645,41 +763,42 @@ return NULL.
the set of mount points for the given (already registered) filesystem
have changed, and that cached file representations may therefore no
longer be correct.
+.SS "THE TCL_FILESYSTEM STRUCTURE"
.PP
The \fBTcl_Filesystem\fR structure contains the following fields:
.CS
typedef struct Tcl_Filesystem {
- CONST char *\fItypeName\fR;
- int \fIstructureLength\fR;
- Tcl_FSVersion \fIversion\fR;
+ const char *\fItypeName\fR;
+ int \fIstructureLength\fR;
+ Tcl_FSVersion \fIversion\fR;
Tcl_FSPathInFilesystemProc *\fIpathInFilesystemProc\fR;
Tcl_FSDupInternalRepProc *\fIdupInternalRepProc\fR;
Tcl_FSFreeInternalRepProc *\fIfreeInternalRepProc\fR;
Tcl_FSInternalToNormalizedProc *\fIinternalToNormalizedProc\fR;
Tcl_FSCreateInternalRepProc *\fIcreateInternalRepProc\fR;
- Tcl_FSNormalizePathProc *\fInormalizePathProc\fR;
+ Tcl_FSNormalizePathProc *\fInormalizePathProc\fR;
Tcl_FSFilesystemPathTypeProc *\fIfilesystemPathTypeProc\fR;
Tcl_FSFilesystemSeparatorProc *\fIfilesystemSeparatorProc\fR;
- Tcl_FSStatProc *\fIstatProc\fR;
- Tcl_FSAccessProc *\fIaccessProc\fR;
- Tcl_FSOpenFileChannelProc *\fIopenFileChannelProc\fR;
- Tcl_FSMatchInDirectoryProc *\fImatchInDirectoryProc\fR;
- Tcl_FSUtimeProc *\fIutimeProc\fR;
- Tcl_FSLinkProc *\fIlinkProc\fR;
- Tcl_FSListVolumesProc *\fIlistVolumesProc\fR;
+ Tcl_FSStatProc *\fIstatProc\fR;
+ Tcl_FSAccessProc *\fIaccessProc\fR;
+ Tcl_FSOpenFileChannelProc *\fIopenFileChannelProc\fR;
+ Tcl_FSMatchInDirectoryProc *\fImatchInDirectoryProc\fR;
+ Tcl_FSUtimeProc *\fIutimeProc\fR;
+ Tcl_FSLinkProc *\fIlinkProc\fR;
+ Tcl_FSListVolumesProc *\fIlistVolumesProc\fR;
Tcl_FSFileAttrStringsProc *\fIfileAttrStringsProc\fR;
Tcl_FSFileAttrsGetProc *\fIfileAttrsGetProc\fR;
Tcl_FSFileAttrsSetProc *\fIfileAttrsSetProc\fR;
- Tcl_FSCreateDirectoryProc *\fIcreateDirectoryProc\fR;
- Tcl_FSRemoveDirectoryProc *\fIremoveDirectoryProc\fR;
- Tcl_FSDeleteFileProc *\fIdeleteFileProc\fR;
- Tcl_FSCopyFileProc *\fIcopyFileProc\fR;
- Tcl_FSRenameFileProc *\fIrenameFileProc\fR;
- Tcl_FSCopyDirectoryProc *\fIcopyDirectoryProc\fR;
- Tcl_FSLstatProc *\fIlstatProc\fR;
- Tcl_FSLoadFileProc *\fIloadFileProc\fR;
- Tcl_FSGetCwdProc *\fIgetCwdProc\fR;
- Tcl_FSChdirProc *\fIchdirProc\fR;
+ Tcl_FSCreateDirectoryProc *\fIcreateDirectoryProc\fR;
+ Tcl_FSRemoveDirectoryProc *\fIremoveDirectoryProc\fR;
+ Tcl_FSDeleteFileProc *\fIdeleteFileProc\fR;
+ Tcl_FSCopyFileProc *\fIcopyFileProc\fR;
+ Tcl_FSRenameFileProc *\fIrenameFileProc\fR;
+ Tcl_FSCopyDirectoryProc *\fIcopyDirectoryProc\fR;
+ Tcl_FSLstatProc *\fIlstatProc\fR;
+ Tcl_FSLoadFileProc *\fIloadFileProc\fR;
+ Tcl_FSGetCwdProc *\fIgetCwdProc\fR;
+ Tcl_FSChdirProc *\fIchdirProc\fR;
} Tcl_Filesystem;
.CE
.PP
@@ -697,20 +816,26 @@ side-effects which are required by the filesystem; Tcl has less
efficient emulations it can fall back on). It is important to note
that, in the current version of Tcl, most of these fallbacks are only
used to handle commands initiated in Tcl, not in C. What this means is,
-that if a 'file rename' command is issued in Tcl, and the relevant
+that if a \fBfile rename\fR command is issued in Tcl, and the relevant
filesystem(s) do not implement their \fITcl_FSRenameFileProc\fR, Tcl's
core will instead fallback on a combination of other filesystem
functions (it will use \fITcl_FSCopyFileProc\fR followed by
\fITcl_FSDeleteFileProc\fR, and if \fITcl_FSCopyFileProc\fR is not
implemented there is a further fallback). However, if a
-\fITcl_FSRenameFile\fR command is issued at the C level, no such
+\fITcl_FSRenameFileProc\fR command is issued at the C level, no such
fallbacks occur. This is true except for the last four entries in the
-filesystem table (lstat, load, getcwd and chdir)
+filesystem table (\fBlstat\fR, \fBload\fR, \fBgetcwd\fR and \fBchdir\fR)
for which fallbacks do in fact occur at the C level.
.PP
-As an example, here is the filesystem lookup table used by the
-"vfs" extension which allows filesystem actions to be implemented
-in Tcl.
+Any functions which take path names in Tcl_Obj form take
+those names in UTF\-8 form. The filesystem infrastructure API is
+designed to support efficient, cached conversion of these UTF\-8 paths
+to other native representations.
+.SS "EXAMPLE FILESYSTEM DEFINITION"
+.PP
+Here is the filesystem lookup table used by the
+.QW vfs
+extension which allows filesystem actions to be implemented in Tcl.
.CS
static Tcl_Filesystem vfsFilesystem = {
"tclvfs",
@@ -719,14 +844,15 @@ static Tcl_Filesystem vfsFilesystem = {
&VfsPathInFilesystem,
&VfsDupInternalRep,
&VfsFreeInternalRep,
- /* No internal to normalized, since we don't create any
- * pure 'internal' Tcl_Obj path representations */
+ /* No internal to normalized, since we don't create
+ * any pure 'internal' Tcl_Obj path representations */
NULL,
- /* No create native rep function, since we don't use it
- * and don't choose to support uses of 'Tcl_FSNewNativePath' */
+ /* No create native rep function, since we don't use
+ * it and don't choose to support uses of
+ * Tcl_FSNewNativePath */
NULL,
- /* Normalize path isn't needed - we assume paths only have
- * one representation */
+ /* Normalize path isn't needed - we assume paths only
+ * have one representation */
NULL,
&VfsFilesystemPathType,
&VfsFilesystemSeparator,
@@ -735,57 +861,57 @@ static Tcl_Filesystem vfsFilesystem = {
&VfsOpenFileChannel,
&VfsMatchInDirectory,
&VfsUtime,
- /* We choose not to support symbolic links inside our vfs's */
+ /* We choose not to support symbolic links inside our
+ * VFS's */
NULL,
&VfsListVolumes,
&VfsFileAttrStrings,
&VfsFileAttrsGet,
&VfsFileAttrsSet,
&VfsCreateDirectory,
- &VfsRemoveDirectory,
+ &VfsRemoveDirectory,
&VfsDeleteFile,
- /* No copy file - fallback will occur at Tcl level */
+ /* No copy file; use the core fallback mechanism */
NULL,
- /* No rename file - fallback will occur at Tcl level */
+ /* No rename file; use the core fallback mechanism */
+ NULL,
+ /* No copy directory; use the core fallback mechanism */
NULL,
- /* No copy directory - fallback will occur at Tcl level */
- NULL,
/* Core will use stat for lstat */
NULL,
- /* No load - fallback on core implementation */
+ /* No load; use the core fallback mechanism */
NULL,
- /* We don't need a getcwd or chdir - fallback on Tcl's versions */
+ /* We don't need a getcwd or chdir; the core's own
+ * internal value is suitable */
NULL,
NULL
};
.CE
+.SH "FILESYSTEM INFRASTRUCTURE"
.PP
-Any functions which take path names in Tcl_Obj form take
-those names in UTF\-8 form. The filesystem infrastructure API is
-designed to support efficient, cached conversion of these UTF\-8 paths
-to other native representations.
-.SH TYPENAME
+These fields contain basic information about the filesystem structure
+and addresses of functions which are used to associate
+a particular filesystem with a file path, and deal with the internal
+handling of path representations, for example copying and freeing such
+representations.
+.SS TYPENAME
.PP
The \fItypeName\fR field contains a null-terminated string that
identifies the type of the filesystem implemented, e.g.
-\fBnative\fR or \fBzip\fR or \fBvfs\fR.
-.PP
-.SH "STRUCTURE LENGTH"
+.QW native ,
+.QW zip
+or
+.QW vfs .
+.SS "STRUCTURE LENGTH"
.PP
The \fIstructureLength\fR field is generally implemented as
\fIsizeof(Tcl_Filesystem)\fR, and is there to allow easier
binary backwards compatibility if the size of the structure
changes in a future Tcl release.
-.SH VERSION
+.SS VERSION
.PP
The \fIversion\fR field should be set to \fBTCL_FILESYSTEM_VERSION_1\fR.
-.SH "FILESYSTEM INFRASTRUCTURE"
-.PP
-These fields contain addresses of functions which are used to associate
-a particular filesystem with a file path, and deal with the internal
-handling of path representations, for example copying and freeing such
-representations.
-.SH PATHINFILESYSTEMPROC
+.SS PATHINFILESYSTEMPROC
.PP
The \fIpathInFilesystemProc\fR field contains the address of a function
which is called to determine whether a given path object belongs to this
@@ -793,7 +919,7 @@ filesystem or not. Tcl will only call the rest of the filesystem
functions with a path for which this function has returned \fBTCL_OK\fR.
If the path does not belong, -1 should be returned (the behaviour of Tcl
for any other return value is not defined). If \fBTCL_OK\fR is returned,
-then the optional \fBclientDataPtr\fR output parameter can be used to
+then the optional \fIclientDataPtr\fR output parameter can be used to
return an internal (filesystem specific) representation of the path,
which will be cached inside the path object, and may be retrieved
efficiently by the other filesystem functions. Tcl will simultaneously
@@ -803,10 +929,10 @@ Tcl's internal list of known filesystems.
.PP
.CS
typedef int Tcl_FSPathInFilesystemProc(
- Tcl_Obj *\fIpathPtr\fR,
- ClientData *\fIclientDataPtr\fR);
+ Tcl_Obj *\fIpathPtr\fR,
+ ClientData *\fIclientDataPtr\fR);
.CE
-.SH DUPINTERNALREPPROC
+.SS DUPINTERNALREPPROC
.PP
This function makes a copy of a path's internal representation, and is
called when Tcl needs to duplicate a path object. If NULL, Tcl will
@@ -815,18 +941,18 @@ regenerated later.
.PP
.CS
typedef ClientData Tcl_FSDupInternalRepProc(
- ClientData \fIclientData\fR);
+ ClientData \fIclientData\fR);
.CE
-.SH FREEINTERNALREPPROC
+.SS FREEINTERNALREPPROC
Free the internal representation. This must be implemented if internal
representations need freeing (i.e. if some memory is allocated when an
internal representation is generated), but may otherwise be NULL.
.PP
.CS
typedef void Tcl_FSFreeInternalRepProc(
- ClientData \fIclientData\fR);
+ ClientData \fIclientData\fR);
.CE
-.SH INTERNALTONORMALIZEDPROC
+.SS INTERNALTONORMALIZEDPROC
.PP
Function to convert internal representation to a normalized path. Only
required if the filesystem creates pure path objects with no string/path
@@ -835,9 +961,9 @@ representation is the normalized path.
.PP
.CS
typedef Tcl_Obj* Tcl_FSInternalToNormalizedProc(
- ClientData \fIclientData\fR);
+ ClientData \fIclientData\fR);
.CE
-.SH CREATEINTERNALREPPROC
+.SS CREATEINTERNALREPPROC
.PP
Function to take a path object, and calculate an internal
representation for it, and store that native representation in the
@@ -847,36 +973,41 @@ immediately creates an internal representation for paths it accepts.
.PP
.CS
typedef ClientData Tcl_FSCreateInternalRepProc(
- Tcl_Obj *\fIpathPtr\fR);
+ Tcl_Obj *\fIpathPtr\fR);
.CE
-.SH NORMALIZEPATHPROC
+.SS NORMALIZEPATHPROC
.PP
Function to normalize a path. Should be implemented for all
filesystems which can have multiple string representations for the same
-path object. In Tcl, every 'path' must have a single unique 'normalized'
+path object. In Tcl, every
+.QW path
+must have a single unique
+.QW normalized
string representation. Depending on the filesystem,
there may be more than one unnormalized string representation which
refers to that path (e.g. a relative path, a path with different
character case if the filesystem is case insensitive, a path contain a
-reference to a home directory such as '~', a path containing symbolic
+reference to a home directory such as
+.QW ~ ,
+a path containing symbolic
links, etc). If the very last component in the path is a symbolic
link, it should not be converted into the object it points to (but
its case or other aspects should be made unique). All other path
components should be converted from symbolic links. This one
-exception is required to agree with Tcl's semantics with 'file
-delete', 'file rename', 'file copy' operating on symbolic links.
-This function may be called with 'nextCheckpoint' either
+exception is required to agree with Tcl's semantics with \fBfile
+delete\fR, \fBfile rename\fR, \fBfile copy\fR operating on symbolic links.
+This function may be called with \fInextCheckpoint\fR either
at the beginning of the path (i.e. zero), at the end of the path, or
at any intermediate file separator in the path. It will never
point to any other arbitrary position in the path. In the last of
-the three valid cases, the implementation can assume that the path
+the three valid cases, the implementation can assume that the path
up to and including the file separator is known and normalized.
.PP
.CS
typedef int Tcl_FSNormalizePathProc(
- Tcl_Interp *\fIinterp\fR,
- Tcl_Obj *\fIpathPtr\fR,
- int \fInextCheckpoint\fR);
+ Tcl_Interp *\fIinterp\fR,
+ Tcl_Obj *\fIpathPtr\fR,
+ int \fInextCheckpoint\fR);
.CE
.SH "FILESYSTEM OPERATIONS"
.PP
@@ -890,43 +1021,52 @@ this may be desirable (for example, a read-only filesystem should not
implement the last four functions, and a filesystem which does not
support symbolic links need not implement the \fBreadlink\fR function,
etc. The Tcl core expects filesystems to behave in this way).
-.SH FILESYSTEMPATHTYPEPROC
+.SS FILESYSTEMPATHTYPEPROC
.PP
Function to determine the type of a path in this filesystem. May be
NULL, in which case no type information will be available to users of
-the filesystem. The 'type' is used only for informational purposes,
+the filesystem. The
+.QW type
+is used only for informational purposes,
and should be returned as the string representation of the Tcl_Obj
-which is returned. A typical return value might be "networked", "zip"
-or "ftp". The Tcl_Obj result is owned by the filesystem and so Tcl will
-increment the refCount of that object if it wishes to retain a reference
+which is returned. A typical return value might be
+.QW networked ,
+.QW zip
+or
+.QW ftp .
+The Tcl_Obj result is owned by the filesystem and so Tcl will
+increment the refCount of that object if it wishes to retain a reference
to it.
.PP
.CS
typedef Tcl_Obj* Tcl_FSFilesystemPathTypeProc(
- Tcl_Obj *\fIpathPtr\fR);
+ Tcl_Obj *\fIpathPtr\fR);
.CE
-.SH FILESYSTEMSEPARATORPROC
+.SS FILESYSTEMSEPARATORPROC
.PP
Function to return the separator character(s) for this filesystem.
-Must be implemented, otherwise the \fBfile separator\fR command will not
-function correctly. The usual return value will be a Tcl_Obj
-containing the string "/".
+This need only be implemented if the filesystem wishes to use a
+different separator than the standard string
+.QW / .
+Amongst other
+uses, it is returned by the \fBfile separator\fR command. The
+return value should be an object with refCount of zero.
.PP
.CS
typedef Tcl_Obj* Tcl_FSFilesystemSeparatorProc(
- Tcl_Obj *\fIpathPtr\fR);
+ Tcl_Obj *\fIpathPtr\fR);
.CE
-.SH STATPROC
+.SS STATPROC
.PP
-Function to process a \fBTcl_FSStat()\fR call. Must be implemented for any
-reasonable filesystem, since many Tcl level commands depend crucially
+Function to process a \fBTcl_FSStat\fR call. Must be implemented for any
+reasonable filesystem, since many Tcl level commands depend crucially
upon it (e.g. \fBfile atime\fR, \fBfile isdirectory\fR, \fBfile size\fR,
\fBglob\fR).
.PP
.CS
typedef int Tcl_FSStatProc(
- Tcl_Obj *\fIpathPtr\fR,
- Tcl_StatBuf *\fIstatPtr\fR);
+ Tcl_Obj *\fIpathPtr\fR,
+ Tcl_StatBuf *\fIstatPtr\fR);
.CE
.PP
The \fBTcl_FSStatProc\fR fills the stat structure \fIstatPtr\fR with
@@ -942,40 +1082,40 @@ last metadata change time.
If the file represented by \fIpathPtr\fR exists, the
\fBTcl_FSStatProc\fR returns 0 and the stat structure is filled with
data. Otherwise, -1 is returned, and no stat info is given.
-.SH ACCESSPROC
+.SS ACCESSPROC
.PP
-Function to process a \fBTcl_FSAccess()\fR call. Must be implemented for
-any reasonable filesystem, since many Tcl level commands depend crucially
+Function to process a \fBTcl_FSAccess\fR call. Must be implemented for
+any reasonable filesystem, since many Tcl level commands depend crucially
upon it (e.g. \fBfile exists\fR, \fBfile readable\fR).
.PP
.CS
typedef int Tcl_FSAccessProc(
- Tcl_Obj *\fIpathPtr\fR,
- int \fImode\fR);
+ Tcl_Obj *\fIpathPtr\fR,
+ int \fImode\fR);
.CE
.PP
The \fBTcl_FSAccessProc\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, then
+to read, write or test for existence of the file (or other filesystem
+object) whose name is in \fIpathPtr\fR. If the pathname refers to a
+symbolic link, then the
permissions of the file referred by this symbolic link should be 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.
+.SS OPENFILECHANNELPROC
.PP
-.SH OPENFILECHANNELPROC
-.PP
-Function to process a \fBTcl_FSOpenFileChannel()\fR call. Must be
+Function to process a \fBTcl_FSOpenFileChannel\fR call. Must be
implemented for any reasonable filesystem, since any operations
-which require open or accessing a file's contents will use it
+which require open or accessing a file's contents will use it
(e.g. \fBopen\fR, \fBencoding\fR, and many Tk commands).
.PP
.CS
typedef Tcl_Channel Tcl_FSOpenFileChannelProc(
- Tcl_Interp *\fIinterp\fR,
- Tcl_Obj *\fIpathPtr\fR,
- int \fImode\fR,
- int \fIpermissions\fR);
+ Tcl_Interp *\fIinterp\fR,
+ Tcl_Obj *\fIpathPtr\fR,
+ int \fImode\fR,
+ int \fIpermissions\fR);
.CE
.PP
The \fBTcl_FSOpenFileChannelProc\fR opens a file specified by
@@ -997,20 +1137,20 @@ interpreter; that task is up to the caller of
the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
previously closed, the act of creating the new channel also assigns it
as a replacement for the standard channel.
-.SH MATCHINDIRECTORYPROC
+.SS MATCHINDIRECTORYPROC
.PP
-Function to process a \fBTcl_FSMatchInDirectory()\fR call. If not
+Function to process a \fBTcl_FSMatchInDirectory\fR call. If not
implemented, then glob and recursive copy functionality will be lacking
-in the filesystem (and this may impact commands like 'encoding names'
+in the filesystem (and this may impact commands like \fBencoding names\fR
which use glob functionality internally).
.PP
.CS
typedef int Tcl_FSMatchInDirectoryProc(
- Tcl_Interp* \fIinterp\fR,
- Tcl_Obj *\fIresult\fR,
- Tcl_Obj *\fIpathPtr\fR,
- CONST char *\fIpattern\fR,
- Tcl_GlobTypeData * \fItypes\fR);
+ Tcl_Interp* \fIinterp\fR,
+ Tcl_Obj *\fIresultPtr\fR,
+ Tcl_Obj *\fIpathPtr\fR,
+ const char *\fIpattern\fR,
+ Tcl_GlobTypeData *\fItypes\fR);
.CE
.PP
The function should return all files or directories (or other filesystem
@@ -1027,12 +1167,13 @@ not, so code should be flexible to both possibilities.
.PP
The return value is a standard Tcl result indicating whether an error
occurred in the matching process. Error messages are placed in
-\fIinterp\fR; on a \fBTCL_OK\fR result, results should be added to the
-\fIresult\fR object given (which can be assumed to be a valid
-unshared Tcl list). The matches added
-to \fIresult\fR should include any path prefix given in \fIpathPtr\fR
-(this usually means they will be absolute path specifications).
-Note that if no matches are found, that simply leads to an empty
+\fIinterp\fR, unless \fIinterp\fR in NULL in which case no error
+message need be generated; on a \fBTCL_OK\fR result, results should be
+added to the \fIresultPtr\fR object given (which can be assumed to be a
+valid unshared Tcl list). The matches added
+to \fIresultPtr\fR should include any path prefix given in \fIpathPtr\fR
+(this usually means they will be absolute path specifications).
+Note that if no matches are found, that simply leads to an empty
result; errors are only signaled for actual file or filesystem
problems which may occur during the matching process.
.PP
@@ -1040,14 +1181,14 @@ The \fBTcl_GlobTypeData\fR structure passed in the \fItypes\fR
parameter contains the following fields:
.CS
typedef struct Tcl_GlobTypeData {
- /* Corresponds to bcdpfls as in 'find -t' */
- int \fItype\fR;
- /* Corresponds to file permissions */
- int \fIperm\fR;
- /* Acceptable mac type */
- Tcl_Obj *\fImacType\fR;
- /* Acceptable mac creator */
- Tcl_Obj *\fImacCreator\fR;
+ /* Corresponds to bcdpfls as in 'find -t' */
+ int \fItype\fR;
+ /* Corresponds to file permissions */
+ int \fIperm\fR;
+ /* Acceptable mac type */
+ Tcl_Obj *\fImacType\fR;
+ /* Acceptable mac creator */
+ Tcl_Obj *\fImacCreator\fR;
} Tcl_GlobTypeData;
.CE
.PP
@@ -1063,50 +1204,52 @@ which lie within the given \fIpathPtr\fR (and in this case, \fIpathPtr\fR
need not lie within the same filesystem - different to all other cases in
which this function is called). Support for this is critical if Tcl is
to have seamless transitions between from one filesystem to another.
-.SH UTIMEPROC
+.SS UTIMEPROC
.PP
-Function to process a \fBTcl_FSUtime()\fR call. Required to allow setting
-(not reading) of times with 'file mtime', 'file atime' and the
-open-r/open-w/fcopy implementation of 'file copy'.
+Function to process a \fBTcl_FSUtime\fR call. Required to allow setting
+(not reading) of times with \fBfile mtime\fR, \fBfile atime\fR and the
+open-r/open-w/fcopy implementation of \fBfile copy\fR.
.PP
.CS
typedef int Tcl_FSUtimeProc(
- Tcl_Obj *\fIpathPtr\fR,
- struct utimbuf *\fItval\fR);
+ Tcl_Obj *\fIpathPtr\fR,
+ struct utimbuf *\fItval\fR);
.CE
.PP
The access and modification times of the file specified by \fIpathPtr\fR
should be changed to the values given in the \fItval\fR structure.
.PP
-The return value is a standard Tcl result indicating whether an error
-occurred in the process.
-.SH LINKPROC
+The return value should be 0 on success and -1 on an error, as
+with the system \fButime\fR.
+.SS LINKPROC
.PP
-Function to process a \fBTcl_FSLink()\fR call. Should be implemented
+Function to process a \fBTcl_FSLink\fR call. Should be implemented
only if the filesystem supports links, and may otherwise be NULL.
.PP
.CS
typedef Tcl_Obj* Tcl_FSLinkProc(
- Tcl_Obj *\fIlinkNamePtr\fR,
- Tcl_Obj *\fItoPtr\fR,
- int \fIlinkAction\fR);
+ Tcl_Obj *\fIlinkNamePtr\fR,
+ Tcl_Obj *\fItoPtr\fR,
+ int \fIlinkAction\fR);
.CE
.PP
If \fItoPtr\fR is NULL, the function is being asked to read the
contents of a link. The result is a Tcl_Obj specifying the contents of
the link given by \fIlinkNamePtr\fR, or NULL if the link could
-not be read. The result is owned by the caller, which should call
-Tcl_DecrRefCount when the result is no longer needed. If \fItoPtr\fR
-is not NULL, the function should attempt to create a link. The result
-in this case should be \fItoPtr\fR if the link was successful and NULL
-otherwise. In this case the result is not owned by the caller. See
+not be read. The result is owned by the caller (and should therefore
+have its ref count incremented before being returned). Any callers
+should call Tcl_DecrRefCount on this result when it is no longer needed.
+If \fItoPtr\fR is not NULL, the function should attempt to create a link.
+The result in this case should be \fItoPtr\fR if the link was successful
+and NULL otherwise. In this case the result is not owned by the caller
+(i.e. no ref count manipulation on either end is needed). See
the documentation for \fBTcl_FSLink\fR for the correct interpretation
of the \fIlinkAction\fR flags.
-.SH LISTVOLUMESPROC
+.SS LISTVOLUMESPROC
.PP
Function to list any filesystem volumes added by this filesystem.
Should be implemented only if the filesystem adds volumes at the head
-of the filesystem, so that they can be returned by 'file volumes'.
+of the filesystem, so that they can be returned by \fBfile volumes\fR.
.PP
.CS
typedef Tcl_Obj* Tcl_FSListVolumesProc(void);
@@ -1117,7 +1260,9 @@ NULL (or an empty list) if no volumes are provided. The result object
is considered to be owned by the filesystem (not by Tcl's core), but
should be given a refCount for Tcl. Tcl will use the contents of the
list and then decrement that refCount. This allows filesystems to
-choose whether they actually want to retain a 'master list' of volumes
+choose whether they actually want to retain a
+.QW "master list"
+of volumes
or not (if not, they generate the list on the fly and pass it to Tcl
with a refCount of 1 and then forget about the list, if yes, then
they simply increment the refCount of their master list and pass it
@@ -1125,8 +1270,7 @@ to Tcl which will copy the contents and then decrement the count back
to where it was).
.PP
Therefore, Tcl considers return values from this proc to be read-only.
-.PP
-.SH FILEATTRSTRINGSPROC
+.SS FILEATTRSTRINGSPROC
.PP
Function to list all attribute strings which are valid for this
filesystem. If not implemented the filesystem will not support
@@ -1136,94 +1280,98 @@ not implemented, there is no need to implement the \fBget\fR and \fBset\fR
methods.
.PP
.CS
-typedef CONST char** Tcl_FSFileAttrStringsProc(
- Tcl_Obj *\fIpathPtr\fR,
- Tcl_Obj** \fIobjPtrRef\fR);
+typedef const char** Tcl_FSFileAttrStringsProc(
+ Tcl_Obj *\fIpathPtr\fR,
+ Tcl_Obj** \fIobjPtrRef\fR);
.CE
.PP
The called function may either return an array of strings, or may
-instead return NULL and place a Tcl list into the given objPtrRef. Tcl
-will take that list and first increment its refCount before using it.
-On completion of that use, Tcl will decrement its refCount. Hence if
+instead return NULL and place a Tcl list into the given \fIobjPtrRef\fR. Tcl
+will take that list and first increment its reference count before using it.
+On completion of that use, Tcl will decrement its reference count. Hence if
the list should be disposed of by Tcl when done, it should have a
-refCount of zero, and if the list should not be disposed of, the
-filesystem should ensure it retains a refCount on the object.
-.SH FILEATTRSGETPROC
+reference count of zero, and if the list should not be disposed of, the
+filesystem should ensure it returns an object with a reference count
+of at least one.
+.SS FILEATTRSGETPROC
.PP
-Function to process a \fBTcl_FSFileAttrsGet()\fR call, used by 'file
-attributes'.
+Function to process a \fBTcl_FSFileAttrsGet\fR call, used by \fBfile
+attributes\fR.
.PP
.CS
typedef int Tcl_FSFileAttrsGetProc(
- Tcl_Interp *\fIinterp\fR,
- int \fIindex\fR,
- Tcl_Obj *\fIpathPtr\fR,
- Tcl_Obj **\fIobjPtrRef\fR);
+ Tcl_Interp *\fIinterp\fR,
+ int \fIindex\fR,
+ Tcl_Obj *\fIpathPtr\fR,
+ Tcl_Obj **\fIobjPtrRef\fR);
.CE
.PP
Returns a standard Tcl return code. The attribute value retrieved,
which corresponds to the \fIindex\fR'th element in the list returned by
-the Tcl_FSFileAttrStringsProc, is a Tcl_Obj placed in objPtrRef (if
-TCL_OK was returned) and is likely to have a refCount of zero. Either
+the \fBTcl_FSFileAttrStringsProc\fR, is a Tcl_Obj placed in \fIobjPtrRef\fR (if
+\fBTCL_OK\fR was returned) and is likely to have a reference count of zero. Either
way we must either store it somewhere (e.g. the Tcl result), or
-Incr/Decr its refCount to ensure it is properly freed.
-.SH FILEATTRSSETPROC
+Incr/Decr its reference count to ensure it is properly freed.
+.SS FILEATTRSSETPROC
.PP
-Function to process a \fBTcl_FSFileAttrsSet()\fR call, used by 'file
-attributes'. If the filesystem is read-only, there is no need
+Function to process a \fBTcl_FSFileAttrsSet\fR call, used by \fBfile
+attributes\fR. If the filesystem is read-only, there is no need
to implement this.
.PP
.CS
typedef int Tcl_FSFileAttrsSetProc(
- Tcl_Interp *\fIinterp\fR,
- int \fIindex\fR,
- Tcl_Obj *\fIpathPtr\fR,
- Tcl_Obj *\fIobjPtr\fR);
+ Tcl_Interp *\fIinterp\fR,
+ int \fIindex\fR,
+ Tcl_Obj *\fIpathPtr\fR,
+ Tcl_Obj *\fIobjPtr\fR);
.CE
.PP
The attribute value of the \fIindex\fR'th element in the list returned by
the Tcl_FSFileAttrStringsProc should be set to the \fIobjPtr\fR given.
-.SH CREATEDIRECTORYPROC
+.SS CREATEDIRECTORYPROC
.PP
-Function to process a \fBTcl_FSCreateDirectory()\fR call. Should be
+Function to process a \fBTcl_FSCreateDirectory\fR call. Should be
implemented unless the FS is read-only.
.PP
.CS
typedef int Tcl_FSCreateDirectoryProc(
- Tcl_Obj *\fIpathPtr\fR);
+ Tcl_Obj *\fIpathPtr\fR);
.CE
.PP
The return value is a standard Tcl result indicating whether an error
occurred in the process. If successful, a new directory should have
been added to the filesystem in the location specified by
\fIpathPtr\fR.
-.SH REMOVEDIRECTORYPROC
+.SS REMOVEDIRECTORYPROC
.PP
-Function to process a 'Tcl_FSRemoveDirectory()' call. Should be
+Function to process a \fBTcl_FSRemoveDirectory\fR call. Should be
implemented unless the FS is read-only.
.PP
.CS
typedef int Tcl_FSRemoveDirectoryProc(
- Tcl_Obj *\fIpathPtr\fR,
- int \fIrecursive\fR,
- Tcl_Obj **\fIerrorPtr\fR);
+ Tcl_Obj *\fIpathPtr\fR,
+ int \fIrecursive\fR,
+ Tcl_Obj **\fIerrorPtr\fR);
.CE
.PP
The return value is a standard Tcl result indicating whether an error
occurred in the process. If successful, the directory specified by
\fIpathPtr\fR should have been removed from the filesystem. If the
-\fIrecursive\fR flag is given, then a non-empty directory should
-be deleted without error. If an error does occur, the name of
-the file or directory which caused the error should be placed in
-\fIerrorPtr\fR.
-.SH DELETEFILEPROC
-.PP
-Function to process a \fBTcl_FSDeleteFile()\fR call. Should be implemented
+\fIrecursive\fR flag is given, then a non-empty directory should be
+deleted without error. If this flag is not given, then and the
+directory is non-empty a POSIX
+.QW EEXIST
+error should be signaled. If an
+error does occur, the name of the file or directory which caused the
+error should be placed in \fIerrorPtr\fR.
+.SS DELETEFILEPROC
+.PP
+Function to process a \fBTcl_FSDeleteFile\fR call. Should be implemented
unless the FS is read-only.
.PP
.CS
typedef int Tcl_FSDeleteFileProc(
- Tcl_Obj *\fIpathPtr\fR);
+ Tcl_Obj *\fIpathPtr\fR);
.CE
.PP
The return value is a standard Tcl result indicating whether an error
@@ -1234,73 +1382,82 @@ function and not Tcl_FSRemoveDirectoryProc when needed to delete them
(even if they are symbolic links to directories).
.SH "FILESYSTEM EFFICIENCY"
.PP
-.SH LSTATPROC
+These functions need not be implemented for a particular filesystem
+because the core has a fallback implementation available. See each
+individual description for the consequences of leaving the field NULL.
+.SS LSTATPROC
.PP
-Function to process a \fBTcl_FSLstat()\fR call. If not implemented, Tcl
+Function to process a \fBTcl_FSLstat\fR call. If not implemented, Tcl
will attempt to use the \fIstatProc\fR defined above instead. Therefore
it need only be implemented if a filesystem can differentiate between
\fBstat\fR and \fBlstat\fR calls.
.PP
.CS
typedef int Tcl_FSLstatProc(
- Tcl_Obj *\fIpathPtr\fR,
- Tcl_StatBuf *\fIstatPtr\fR);
+ Tcl_Obj *\fIpathPtr\fR,
+ Tcl_StatBuf *\fIstatPtr\fR);
.CE
.PP
-The behavior of this function is very similar to that of the
-Tcl_FSStatProc defined above, except that if it is applied
+The behavior of this function is very similar to that of the
+\fBTcl_FSStatProc\fR defined above, except that if it is applied
to a symbolic link, it returns information about the link, not
about the target file.
+.SS COPYFILEPROC
.PP
-.SH COPYFILEPROC
-.PP
-Function to process a \fBTcl_FSCopyFile()\fR call. If not implemented Tcl
-will fall back on open-r, open-w and fcopy as a copying mechanism.
+Function to process a \fBTcl_FSCopyFile\fR call. If not implemented Tcl
+will fall back on \fBopen\fR-r, \fBopen\fR-w and \fBfcopy\fR as a
+copying mechanism.
Therefore it need only be implemented if the filesystem can perform
that action more efficiently.
.PP
.CS
typedef int Tcl_FSCopyFileProc(
- Tcl_Obj *\fIsrcPathPtr\fR,
- Tcl_Obj *\fIdestPathPtr\fR);
+ Tcl_Obj *\fIsrcPathPtr\fR,
+ Tcl_Obj *\fIdestPathPtr\fR);
.CE
.PP
The return value is a standard Tcl result indicating whether an error
occurred in the copying process. Note that, \fIdestPathPtr\fR is the
name of the file which should become the copy of \fIsrcPathPtr\fR. It
is never the name of a directory into which \fIsrcPathPtr\fR could be
-copied (i.e. the function is much simpler than the Tcl level 'file
-copy' subcommand). Note that,
+copied (i.e. the function is much simpler than the Tcl level \fBfile
+copy\fR subcommand). Note that,
if the filesystem supports symbolic links, Tcl will always call this
-function and not Tcl_FSCopyDirectoryProc when needed to copy them
-(even if they are symbolic links to directories).
-.SH RENAMEFILEPROC
-.PP
-Function to process a \fBTcl_FSRenameFile()\fR call. If not implemented,
+function and not \fIcopyDirectoryProc\fR when needed to copy them
+(even if they are symbolic links to directories). Finally, if the
+filesystem determines it cannot support the \fBfile copy\fR action,
+calling \fBTcl_SetErrno(EXDEV)\fR and returning a non-\fBTCL_OK\fR
+result will tell Tcl to use its standard fallback mechanisms.
+.SS RENAMEFILEPROC
+.PP
+Function to process a \fBTcl_FSRenameFile\fR call. If not implemented,
Tcl will fall back on a copy and delete mechanism. Therefore it need
only be implemented if the filesystem can perform that action more
efficiently.
.PP
.CS
typedef int Tcl_FSRenameFileProc(
- Tcl_Obj *\fIsrcPathPtr\fR,
- Tcl_Obj *\fIdestPathPtr\fR);
+ Tcl_Obj *\fIsrcPathPtr\fR,
+ Tcl_Obj *\fIdestPathPtr\fR);
.CE
.PP
The return value is a standard Tcl result indicating whether an error
-occurred in the renaming process.
-.SH COPYDIRECTORYPROC
-.PP
-Function to process a \fBTcl_FSCopyDirectory()\fR call. If not
-implemented, Tcl will fall back on a recursive create-dir, file copy
+occurred in the renaming process. If the
+filesystem determines it cannot support the \fBfile rename\fR action,
+calling \fBTcl_SetErrno(EXDEV)\fR and returning a non-\fBTCL_OK\fR
+result will tell Tcl to use its standard fallback mechanisms.
+.SS COPYDIRECTORYPROC
+.PP
+Function to process a \fBTcl_FSCopyDirectory\fR call. If not
+implemented, Tcl will fall back on a recursive \fBfile mkdir\fR, \fBfile copy\fR
mechanism. Therefore it need only be implemented if the filesystem can
perform that action more efficiently.
.PP
.CS
typedef int Tcl_FSCopyDirectoryProc(
- Tcl_Obj *\fIsrcPathPtr\fR,
- Tcl_Obj *\fIdestPathPtr\fR,
- Tcl_Obj **\fIerrorPtr\fR);
+ Tcl_Obj *\fIsrcPathPtr\fR,
+ Tcl_Obj *\fIdestPathPtr\fR,
+ Tcl_Obj **\fIerrorPtr\fR);
.CE
.PP
The return value is a standard Tcl result indicating whether an error
@@ -1310,33 +1467,42 @@ the file or directory which caused the error should be placed in
directory-name which should become the mirror-image of
\fIsrcPathPtr\fR. It is not the name of a directory into which
\fIsrcPathPtr\fR should be copied (i.e. the function is much simpler
-than the Tcl level 'file copy' subcommand).
-.SH LOADFILEPROC
-.PP
-Function to process a \fBTcl_FSLoadFile()\fR call. If not implemented, Tcl
-will fall back on a copy to native-temp followed by a Tcl_FSLoadFile on
+than the Tcl level \fBfile copy\fR subcommand). Finally, if the
+filesystem determines it cannot support the directory copy action,
+calling \fBTcl_SetErrno(EXDEV)\fR and returning a non-\fBTCL_OK\fR
+result will tell Tcl to use its standard fallback mechanisms.
+.SS LOADFILEPROC
+.PP
+Function to process a \fBTcl_FSLoadFile\fR call. If not implemented, Tcl
+will fall back on a copy to native-temp followed by a \fBTcl_FSLoadFile\fR on
that temporary copy. Therefore it need only be implemented if the
filesystem can load code directly, or it can be implemented simply to
-return TCL_ERROR to disable load functionality in this filesystem
+return \fBTCL_ERROR\fR to disable load functionality in this filesystem
entirely.
.PP
.CS
typedef int Tcl_FSLoadFileProc(
- Tcl_Interp * \fIinterp\fR,
- Tcl_Obj *\fIpathPtr\fR,
- Tcl_LoadHandle * \fIhandlePtr\fR,
- Tcl_FSUnloadFileProc * \fIunloadProcPtr\fR);
+ Tcl_Interp *\fIinterp\fR,
+ Tcl_Obj *\fIpathPtr\fR,
+ Tcl_LoadHandle *\fIhandlePtr\fR,
+ Tcl_FSUnloadFileProc *\fIunloadProcPtr\fR);
.CE
.PP
Returns a standard Tcl completion code. If an error occurs, an error
-message is left in the interp's result. The function dynamically loads
-a binary code file into memory. On a successful
-load, the \fIhandlePtr\fR should be filled with a token for
-the dynamically loaded file, and the \fIunloadProcPtr\fR should be
-filled in with the address of a procedure. The procedure will be
-called with the given Tcl_LoadHandle as its only parameter when Tcl
-needs to unload the file.
-.SH UNLOADFILEPROC
+message is left in the \fIinterp\fR's result. The function dynamically loads a
+binary code file into memory. On a successful load, the \fIhandlePtr\fR
+should be filled with a token for the dynamically loaded file, and the
+\fIunloadProcPtr\fR should be filled in with the address of a procedure.
+The unload procedure will be called with the given \fBTcl_LoadHandle\fR as its
+only parameter when Tcl needs to unload the file. For example, for the
+native filesystem, the \fBTcl_LoadHandle\fR returned is currently a token
+which can be used in the private \fBTclpFindSymbol\fR to access functions
+in the new code. Each filesystem is free to define the
+\fBTcl_LoadHandle\fR as it requires. Finally, if the
+filesystem determines it cannot support the file load action,
+calling \fBTcl_SetErrno(EXDEV)\fR and returning a non-\fBTCL_OK\fR
+result will tell Tcl to use its standard fallback mechanisms.
+.SS UNLOADFILEPROC
.PP
Function to unload a previously successfully loaded file. If load was
implemented, then this should also be implemented, if there is any
@@ -1344,17 +1510,17 @@ cleanup action required.
.PP
.CS
typedef void Tcl_FSUnloadFileProc(
- Tcl_LoadHandle \fIloadHandle\fR);
+ Tcl_LoadHandle \fIloadHandle\fR);
.CE
-.SH GETCWDPROC
+.SS GETCWDPROC
.PP
-Function to process a \fBTcl_FSGetCwd()\fR call. Most filesystems need not
-implement this. It will usually only be called once, if 'getcwd' is
-called before 'chdir'. May be NULL.
+Function to process a \fBTcl_FSGetCwd\fR call. Most filesystems need not
+implement this. It will usually only be called once, if \fBgetcwd\fR is
+called before \fBchdir\fR. May be NULL.
.PP
.CS
typedef Tcl_Obj* Tcl_FSGetCwdProc(
- Tcl_Interp *\fIinterp\fR);
+ Tcl_Interp *\fIinterp\fR);
.CE
.PP
If the filesystem supports a native notion of a current working
@@ -1362,26 +1528,28 @@ directory (which might perhaps change independent of Tcl), this
function should return that cwd as the result, or NULL if the current
directory could not be determined (e.g. the user does not have
appropriate permissions on the cwd directory). If NULL is returned, an
-error message is left in the interp's result.
-.PP
-.SH CHDIRPROC
+error message is left in the \fIinterp\fR's result.
+.SS CHDIRPROC
.PP
-Function to process a \fBTcl_FSChdir()\fR call. If filesystems do not
+Function to process a \fBTcl_FSChdir\fR call. If filesystems do not
implement this, it will be emulated by a series of directory access
checks. Otherwise, virtual filesystems which do implement it need only
-respond with a positive return result if the dirName is a valid,
+respond with a positive return result if the \fIpathPtr\fR is a valid,
accessible directory in their filesystem. They need not remember the
-result, since that will be automatically remembered for use by GetCwd.
+result, since that will be automatically remembered for use by
+\fBTcl_FSGetCwd\fR.
Real filesystems should carry out the correct action (i.e. call the
-correct system 'chdir' api).
+correct system \fBchdir\fR API).
.PP
.CS
typedef int Tcl_FSChdirProc(
- Tcl_Obj *\fIpathPtr\fR);
+ Tcl_Obj *\fIpathPtr\fR);
.CE
.PP
The \fBTcl_FSChdirProc\fR changes the applications current working
directory to the value specified in \fIpathPtr\fR. The function returns
-1 on error or 0 on success.
+.SH "SEE ALSO"
+cd(n), file(n), load(n), open(n), pwd(n), unload(n)
.SH KEYWORDS
-stat access filesystem vfs
+stat, access, filesystem, vfs, virtual
diff --git a/doc/FindExec.3 b/doc/FindExec.3
index 9c42f9a..0e225e9 100644
--- a/doc/FindExec.3
+++ b/doc/FindExec.3
@@ -16,10 +16,10 @@ Tcl_FindExecutable, Tcl_GetNameOfExecutable \- identify or return the name of th
void
\fBTcl_FindExecutable\fR(\fIargv0\fR)
.sp
-CONST char *
+const char *
\fBTcl_GetNameOfExecutable\fR()
.SH ARGUMENTS
-.AS char *argv0 in
+.AS char *argv0
.AP char *argv0 in
The first command-line argument to the program, which gives the
application's name.
diff --git a/doc/GetCwd.3 b/doc/GetCwd.3
index f8fce52..964e237 100755..100644
--- a/doc/GetCwd.3
+++ b/doc/GetCwd.3
@@ -19,7 +19,7 @@ char *
int
\fBTcl_Chdir\fR(\fIpath\fR)
.SH ARGUMENTS
-.AS Tcl_DString *bufferPtr
+.AS Tcl_DString *bufferPtr in/out
.AP Tcl_Interp *interp in
Interpreter in which to report an error, if any.
.AP Tcl_DString *bufferPtr in/out
@@ -39,7 +39,7 @@ the same functionality as the Tcl \fBpwd\fR command.
.PP
\fBTcl_GetCwd\fR returns a pointer to a string specifying the current
directory, or NULL if the current directory could not be determined.
-If NULL is returned, an error message is left in the interp's result.
+If NULL is returned, an error message is left in the \fIinterp\fR's result.
Storage for the result string is allocated in bufferPtr; the caller
must call \fBTcl_DStringFree()\fR when the result is no longer needed.
The format of the path is UTF\-8.
diff --git a/doc/GetHostName.3 b/doc/GetHostName.3
index 694ac4a..28f3a4f 100644
--- a/doc/GetHostName.3
+++ b/doc/GetHostName.3
@@ -11,7 +11,7 @@ Tcl_GetHostName \- get the name of the local host
.nf
\fB#include <tcl.h>\fR
.sp
-CONST char *
+const char *
\fBTcl_GetHostName\fR()
.BE
diff --git a/doc/GetIndex.3 b/doc/GetIndex.3
index 54ac034..45d4e9c 100644
--- a/doc/GetIndex.3
+++ b/doc/GetIndex.3
@@ -16,14 +16,12 @@ Tcl_GetIndexFromObj, Tcl_GetIndexFromObjStruct \- lookup string in table of keyw
int
\fBTcl_GetIndexFromObj\fR(\fIinterp, objPtr, tablePtr, msg, flags,
indexPtr\fR)
-.VS
.sp
int
\fBTcl_GetIndexFromObjStruct\fR(\fIinterp, objPtr, structTablePtr, offset,
-msg, flags, indexPtr\fR)
-.VE
+ msg, flags, indexPtr\fR)
.SH ARGUMENTS
-.AS "CONST char" **tablePtr
+.AS "const char" *structTablePtr in/out
.AP Tcl_Interp *interp in
Interpreter to use for error reporting; if NULL, then no message is
provided on errors.
@@ -31,25 +29,23 @@ provided on errors.
The string value of this object is used to search through \fItablePtr\fR.
The internal representation is modified to hold the index of the matching
table entry.
-.AP "CONST char" **tablePtr in
+.AP "const char" **tablePtr in
An array of null-terminated strings. The end of the array is marked
by a NULL string pointer.
Note that references to the \fItablePtr\fR may be retained in the
internal representation of \fIobjPtr\fR, so this should represent the
address of a statically-allocated array.
-.AP "CONST VOID" *structTablePtr in
-An array of arbitrary type, typically some \fBstruct\fP type.
+.AP "const void" *structTablePtr in
+An array of arbitrary type, typically some \fBstruct\fR type.
The first member of the structure must be a null-terminated string.
-The size of the structure is given by \fIoffset\fP.
+The size of the structure is given by \fIoffset\fR.
Note that references to the \fIstructTablePtr\fR may be retained in the
internal representation of \fIobjPtr\fR, so this should represent the
address of a statically-allocated array of structures.
-.VS
.AP int offset in
The offset to add to structTablePtr to get to the next entry.
The end of the array is marked by a NULL string pointer.
-.VE
-.AP "CONST char" *msg in
+.AP "const char" *msg in
Null-terminated string describing what is being looked up, such as
\fBoption\fR. This string is included in error messages.
.AP int flags in
@@ -72,14 +68,14 @@ the strings in \fItablePtr\fR to find a match. A match occurs if
for exactly one of the strings in \fItablePtr\fR and the
\fBTCL_EXACT\fR flag was not specified; in either case
the index of the matching entry is stored at \fI*indexPtr\fR
-and TCL_OK is returned.
+and \fBTCL_OK\fR is returned.
.PP
If there is no matching entry,
-TCL_ERROR is returned and an error message is left in \fIinterp\fR's
-result if \fIinterp\fR isn't NULL. \fIMsg\fR is included in the
+\fBTCL_ERROR\fR is returned and an error message is left in \fIinterp\fR's
+result if \fIinterp\fR is not NULL. \fIMsg\fR is included in the
error message to indicate what was being looked up. For example,
if \fImsg\fR is \fBoption\fR the error message will have a form like
-\fBbad option "firt": must be first, second, or third\fR.
+.QW "\fBbad option \N'34'firt\N'34': must be first, second, or third\fR" .
.PP
If \fBTcl_GetIndexFromObj\fR completes successfully it modifies the
internal representation of \fIobjPtr\fR to hold the address of
@@ -91,17 +87,18 @@ operation. Note: \fBTcl_GetIndexFromObj\fR assumes that the entries
in \fItablePtr\fR are static: they must not change between
invocations. If the value of \fIobjPtr\fR is the empty string,
\fBTcl_GetIndexFromObj\fR will treat it as a non-matching value
-and return TCL_ERROR.
-.VS
+and return \fBTCL_ERROR\fR.
.PP
\fBTcl_GetIndexFromObjStruct\fR works just like
\fBTcl_GetIndexFromObj\fR, except that instead of treating
-\fItablePtr\fR as an array of string pointers, it treats it as the
-first in a series of string ptrs that are spaced apart by \fIoffset\fR
-bytes. This is particularly useful when processing things like
+\fItablePtr\fR as an array of string pointers, it treats it as a
+pointer to the first string in a series of strings that have
+\fIoffset\fR bytes between them (i.e. that there is a pointer to the
+first array of characters at \fItablePtr\fR, a pointer to the second
+array of characters at \fItablePtr\fR+\fIoffset\fR bytes, etc.)
+This is particularly useful when processing things like
\fBTk_ConfigurationSpec\fR, whose string keys are in the same place in
each of several array elements.
-.VE
.SH "SEE ALSO"
Tcl_WrongNumArgs
diff --git a/doc/GetInt.3 b/doc/GetInt.3
index 677527a..f77d337 100644
--- a/doc/GetInt.3
+++ b/doc/GetInt.3
@@ -15,62 +15,69 @@ Tcl_GetInt, Tcl_GetDouble, Tcl_GetBoolean \- convert from string to integer, dou
\fB#include <tcl.h>\fR
.sp
int
-\fBTcl_GetInt\fR(\fIinterp, string, intPtr\fR)
+\fBTcl_GetInt\fR(\fIinterp, src, intPtr\fR)
.sp
int
-\fBTcl_GetDouble\fR(\fIinterp, string, doublePtr\fR)
+\fBTcl_GetDouble\fR(\fIinterp, src, doublePtr\fR)
.sp
int
-\fBTcl_GetBoolean\fR(\fIinterp, string, boolPtr\fR)
+\fBTcl_GetBoolean\fR(\fIinterp, src, boolPtr\fR)
.SH ARGUMENTS
-.AS Tcl_Interp *doublePtr
+.AS Tcl_Interp *doublePtr out
.AP Tcl_Interp *interp in
Interpreter to use for error reporting.
-.AP "CONST char" *string in
+.AP "const char" *src in
Textual value to be converted.
.AP int *intPtr out
-Points to place to store integer value converted from \fIstring\fR.
+Points to place to store integer value converted from \fIsrc\fR.
.AP double *doublePtr out
Points to place to store double-precision floating-point
-value converted from \fIstring\fR.
+value converted from \fIsrc\fR.
.AP int *boolPtr out
-Points to place to store boolean value (0 or 1) converted from \fIstring\fR.
+Points to place to store boolean value (0 or 1) converted from \fIsrc\fR.
.BE
.SH DESCRIPTION
.PP
These procedures convert from strings to integers or double-precision
floating-point values or booleans (represented as 0- or 1-valued
-integers). Each of the procedures takes a \fIstring\fR argument,
+integers). Each of the procedures takes a \fIsrc\fR argument,
converts it to an internal form of a particular type, and stores
the converted value at the location indicated by the procedure's
third argument. If all goes well, each of the procedures returns
-TCL_OK. If \fIstring\fR doesn't have the proper syntax for the
-desired type then TCL_ERROR is returned, an error message is left
+\fBTCL_OK\fR. If \fIsrc\fR does not have the proper syntax for the
+desired type then \fBTCL_ERROR\fR is returned, an error message is left
in the interpreter's result, and nothing is stored at *\fIintPtr\fR
or *\fIdoublePtr\fR or *\fIboolPtr\fR.
.PP
-\fBTcl_GetInt\fR expects \fIstring\fR to consist of a collection
+\fBTcl_GetInt\fR expects \fIsrc\fR to consist of a collection
of integer digits, optionally signed and optionally preceded by
-white space. If the first two characters of \fIstring\fR are ``0x''
-then \fIstring\fR is expected to be in hexadecimal form; otherwise,
-if the first character of \fIstring\fR is ``0'' then \fIstring\fR
-is expected to be in octal form; otherwise, \fIstring\fR is
+white space. If the first two characters of \fIsrc\fR
+after the optional white space and sign are
+.QW 0x
+then \fIsrc\fR is expected to be in hexadecimal form; otherwise,
+if the first such character is
+.QW 0
+then \fIsrc\fR
+is expected to be in octal form; otherwise, \fIsrc\fR is
expected to be in decimal form.
.PP
-\fBTcl_GetDouble\fR expects \fIstring\fR to consist of a floating-point
+\fBTcl_GetDouble\fR expects \fIsrc\fR to consist of a floating-point
number, which is: white space; a sign; a sequence of digits; a
-decimal point; a sequence of digits; the letter ``e''; and a
-signed decimal exponent. Any of the fields may be omitted, except that
+decimal point; a sequence of digits; the letter
+.QW e ;
+a signed decimal exponent; and more white space.
+Any of the fields may be omitted, except that
the digits either before or after the decimal point must be present
-and if the ``e'' is present then it must be followed by the
-exponent number.
+and if the
+.QW e
+is present then it must be followed by the exponent number.
.PP
-\fBTcl_GetBoolean\fR expects \fIstring\fR to specify a boolean
-value. If \fIstring\fR is any of \fB0\fR, \fBfalse\fR,
+\fBTcl_GetBoolean\fR expects \fIsrc\fR to specify a boolean
+value. If \fIsrc\fR is any of \fB0\fR, \fBfalse\fR,
\fBno\fR, or \fBoff\fR, then \fBTcl_GetBoolean\fR stores a zero
value at \fI*boolPtr\fR.
-If \fIstring\fR is any of \fB1\fR, \fBtrue\fR, \fByes\fR, or \fBon\fR,
+If \fIsrc\fR is any of \fB1\fR, \fBtrue\fR, \fByes\fR, or \fBon\fR,
then 1 is stored at \fI*boolPtr\fR.
Any of these values may be abbreviated, and upper-case spellings
are also acceptable.
diff --git a/doc/GetOpnFl.3 b/doc/GetOpnFl.3
index e914b8f..38aa976 100644
--- a/doc/GetOpnFl.3
+++ b/doc/GetOpnFl.3
@@ -8,29 +8,29 @@
.TH Tcl_GetOpenFile 3 8.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
-Tcl_GetOpenFile \- Get a standard IO File * handle from a channel. (Unix only)
+Tcl_GetOpenFile \- Return a FILE* for a channel registered in the given interpreter (Unix only)
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
int
-\fBTcl_GetOpenFile\fR(\fIinterp, string, write, checkUsage, filePtr\fR)
+\fBTcl_GetOpenFile\fR(\fIinterp, chanID, write, checkUsage, filePtr\fR)
.sp
.SH ARGUMENTS
-.AS Tcl_Interp checkUsage
+.AS Tcl_Interp checkUsage out
.AP Tcl_Interp *interp in
Tcl interpreter from which file handle is to be obtained.
-.AP "CONST char" *string in
+.AP "const char" *chanID in
String identifying channel, such as \fBstdin\fR or \fBfile4\fR.
.AP int write in
Non-zero means the file will be used for writing, zero means it will
be used for reading.
.AP int checkUsage in
-If non-zero, then an error will be generated if the file wasn't opened
+If non-zero, then an error will be generated if the file was not opened
for the access indicated by \fIwrite\fR.
.AP ClientData *filePtr out
Points to word in which to store pointer to FILE structure for
-the file given by \fIstring\fR.
+the file given by \fIchanID\fR.
.BE
.SH DESCRIPTION
@@ -44,17 +44,15 @@ be used for reading or writing.
In some cases, such as a channel that connects to a pipeline of
subprocesses, different FILE pointers will be returned for reading
and writing.
-\fBTcl_GetOpenFile\fR normally returns TCL_OK.
-If an error occurs in \fBTcl_GetOpenFile\fR (e.g. \fIstring\fR didn't
-make any sense or \fIcheckUsage\fR was set and the file wasn't opened
-for the access specified by \fIwrite\fR) then TCL_ERROR is returned
+\fBTcl_GetOpenFile\fR normally returns \fBTCL_OK\fR.
+If an error occurs in \fBTcl_GetOpenFile\fR (e.g. \fIchanID\fR did not
+make any sense or \fIcheckUsage\fR was set and the file was not opened
+for the access specified by \fIwrite\fR) then \fBTCL_ERROR\fR is returned
and the interpreter's result will contain an error message.
In the current implementation \fIcheckUsage\fR is ignored and consistency
checks are always performed.
-.VS
.PP
Note that this interface is only supported on the Unix platform.
-.VE
.SH KEYWORDS
channel, file handle, permissions, pipeline, read, write
diff --git a/doc/GetStdChan.3 b/doc/GetStdChan.3
index e0f754a..045d15a 100644
--- a/doc/GetStdChan.3
+++ b/doc/GetStdChan.3
@@ -20,7 +20,7 @@ Tcl_Channel
\fBTcl_SetStdChannel\fR(\fIchannel, type\fR)
.sp
.SH ARGUMENTS
-.AS Tcl_Channel channel in
+.AS Tcl_Channel channel
.AP int type in
The identifier for the standard channel to retrieve or modify. Must be one of
\fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, or \fBTCL_STDERR\fR.
@@ -76,7 +76,6 @@ standard error being last.
.PP
See \fBTcl_StandardChannels\fR for a general treatise about standard
channels and the behaviour of the Tcl library with regard to them.
-.PP
.SH "SEE ALSO"
Tcl_Close(3), Tcl_CreateChannel(3), Tcl_Main(3), tclsh(1)
diff --git a/doc/GetTime.3 b/doc/GetTime.3
index 92457bd..14a9e8c 100644
--- a/doc/GetTime.3
+++ b/doc/GetTime.3
@@ -1,5 +1,5 @@
'\"
-'\" Copyright (c) 2001 by Kevin B. Kenny.
+'\" Copyright (c) 2001 by Kevin B. Kenny <kennykb@acm.org>.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
@@ -8,16 +8,39 @@
.TH Tcl_GetTime 3 8.4 Tcl "Tcl Library Procedures"
.BS
.SH NAME
-Tcl_GetTime \- get date and time
+Tcl_GetTime, Tcl_SetTimeProc, Tcl_QueryTimeProc \- get date and time
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
-\fBTcl_GetTime\fR(\fI timePtr \fR)
+\fBTcl_GetTime\fR(\fItimePtr\fR)
+.sp
+\fBTcl_SetTimeProc\fR(\fIgetProc, scaleProc, clientData\fR)
+.sp
+\fBTcl_QueryTimeProc\fR(\fIgetProcPtr, scaleProcPtr, clientDataPtr\fR)
.SH ARGUMENTS
-.AS "Tcl_Time *" timePtr
+.AS "Tcl_Time *" timePtr out
.AP "Tcl_Time *" timePtr out
Points to memory in which to store the date and time information.
+.AS "Tcl_GetTimeProc *" getProc in
+.AP "Tcl_GetTimeProc *" getProc in
+Pointer to handler function replacing \fBTcl_GetTime\fR's access to the OS.
+.AS "Tcl_ScaleTimeProc *" scaleProc in
+.AP "Tcl_ScaleTimeProc *" scaleProc in
+Pointer to handler function for the conversion of time delays in the
+virtual domain to real-time.
+.AS "ClientData *" clientData in
+.AP "ClientData *" clientData in
+Value passed through to the two handler functions.
+.AS "Tcl_GetTimeProc **" getProcPtr inout
+.AP "Tcl_GetTimeProc **" getProcPtr inout
+Pointer to place the currently registered get handler function into.
+.AS "Tcl_ScaleTimeProc **" scaleProcPtr inout
+.AP "Tcl_ScaleTimeProc **" scaleProcPtr inout
+Pointer to place the currently registered scale handler function into.
+.AS "ClientData **" clientDataPtr inout
+.AP "ClientData **" clientDataPtr inout
+Pointer to place the currently registered pass-through value into.
.BE
.SH DESCRIPTION
.PP
@@ -45,6 +68,32 @@ computer system. On multiprocessor variants of Windows, this number
may be limited to the 10- or 20-ms granularity of the system clock.
(On single-processor Windows systems, the \fIusec\fR field is derived
from a performance counter and is highly precise.)
+.PP
+The \fBTcl_SetTime\fR function registers two related handler functions
+with the core. The first handler function is a replacement for
+\fBTcl_GetTime\fR, or rather the OS access made by
+\fBTcl_GetTime\fR. The other handler function is used by the Tcl
+notifier to convert wait/block times from the virtual domain into real
+time.
+.PP
+The \fBTcl_QueryTime\fR function returns the currently registered
+handler functions. If no external handlers were set then this will
+return the standard handlers accessing and processing the native time
+of the OS. The arguments to the function are allowed to be NULL; and
+any argument which is NULL is ignored and not set.
+.PP
+Any handler pair specified has to return data which is consistent
+between them. In other words, setting one handler of the pair to
+something assuming a 10-times slowdown, and the other handler of the
+pair to something assuming a two-times slowdown is wrong and not
+allowed.
+.PP
+The set handler functions are allowed to run the delivered time
+backwards, however this should be avoided. We have to allow it as the
+native time can run backwards as the user can fiddle with the system
+time one way or other. Note that the insertion of the hooks will not
+change the behaviour of the Tcl core with regard to this situation,
+i.e. the existing behaviour is retained.
.SH "SEE ALSO"
clock
.SH KEYWORDS
diff --git a/doc/GetVersion.3 b/doc/GetVersion.3
index 4fa26f4..47034d0 100755..100644
--- a/doc/GetVersion.3
+++ b/doc/GetVersion.3
@@ -15,6 +15,7 @@ Tcl_GetVersion \- get the version of the library at runtime
.sp
\fBTcl_GetVersion\fR(\fImajor, minor, patchLevel, type\fR)
.SH ARGUMENTS
+.AS Tcl_ReleaseType *patchLevel out
.AP int *major out
Major version number of the Tcl library.
.AP int *minor out
diff --git a/doc/Hash.3 b/doc/Hash.3
index 1f6040a..78b8459 100644
--- a/doc/Hash.3
+++ b/doc/Hash.3
@@ -44,21 +44,21 @@ Tcl_HashEntry *
Tcl_HashEntry *
\fBTcl_NextHashEntry\fR(\fIsearchPtr\fR)
.sp
-CONST char *
+char *
\fBTcl_HashStats\fR(\fItablePtr\fR)
.SH ARGUMENTS
-.AS Tcl_HashSearch *searchPtr
+.AS Tcl_HashKeyType *searchPtr out
.AP Tcl_HashTable *tablePtr in
Address of hash table structure (for all procedures but
\fBTcl_InitHashTable\fR, this must have been initialized by
previous call to \fBTcl_InitHashTable\fR).
.AP int keyType in
Kind of keys to use for new hash table. Must be either
-TCL_STRING_KEYS, TCL_ONE_WORD_KEYS, TCL_CUSTOM_TYPE_KEYS,
-TCL_CUSTOM_PTR_KEYS, or an integer value greater than 1.
+\fBTCL_STRING_KEYS\fR, \fBTCL_ONE_WORD_KEYS\fR, \fBTCL_CUSTOM_TYPE_KEYS\fR,
+\fBTCL_CUSTOM_PTR_KEYS\fR, or an integer value greater than 1.
.AP Tcl_HashKeyType *typePtr in
Address of structure which defines the behaviour of the hash table.
-.AP "CONST char" *key in
+.AP "const char" *key in
Key to use for probe into table. Exact form depends on
\fIkeyType\fR used to create table.
.AP int *newPtr out
@@ -86,7 +86,9 @@ STRUCTURE\fR below). All of the keys in a given table have the same
form, which is specified when the table is initialized.
.PP
The value of a hash table entry can be anything that fits in the same
-space as a ``char *'' pointer. Values for hash table entries are
+space as a
+.QW "char *"
+pointer. Values for hash table entries are
managed entirely by clients, not by the hash module itself. Typically
each entry's value is a pointer to a data structure managed by client
code.
@@ -122,8 +124,10 @@ They are passed to hashing routines using the address of the
first character of the string.
.IP \fBTCL_ONE_WORD_KEYS\fR 25
Keys are single-word values; they are passed to hashing routines
-and stored in hash table entries as ``char *'' values.
-The pointer value is the key; it need not (and usually doesn't)
+and stored in hash table entries as
+.QW "char *"
+values.
+The pointer value is the key; it need not (and usually does not)
actually point to a string.
.IP \fBTCL_CUSTOM_TYPE_KEYS\fR 25
Keys are of arbitrary type, and are stored in the entry. Hashing
@@ -138,7 +142,9 @@ structure is described in the section
.IP \fIother\fR 25
If \fIkeyType\fR is not one of the above,
then it must be an integer value greater than 1.
-In this case the keys will be arrays of ``int'' values, where
+In this case the keys will be arrays of
+.QW int
+values, where
\fIkeyType\fR gives the number of ints in each key.
This allows structures to be used as keys.
All keys must have the same size.
@@ -159,7 +165,7 @@ before deleting the table.
.PP
\fBTcl_CreateHashEntry\fR locates the entry corresponding to a
particular key, creating a new entry in the table if there
-wasn't already one with the given key.
+was not already one with the given key.
If an entry already existed with the given key then \fI*newPtr\fR
is set to zero.
If a new entry was created, then \fI*newPtr\fR is set to a non-zero
@@ -175,28 +181,34 @@ the client is responsible for any cleanup associated with the
entry's value, such as freeing a structure that it points to.
.PP
\fBTcl_FindHashEntry\fR is similar to \fBTcl_CreateHashEntry\fR
-except that it doesn't create a new entry if the key doesn't exist;
+except that it does not create a new entry if the key doesn't exist;
instead, it returns NULL as result.
.PP
\fBTcl_GetHashValue\fR and \fBTcl_SetHashValue\fR are used to
read and write an entry's value, respectively.
-Values are stored and retrieved as type ``ClientData'', which is
+Values are stored and retrieved as type
+.QW ClientData ,
+which is
large enough to hold a pointer value. On almost all machines this is
large enough to hold an integer value too.
.PP
\fBTcl_GetHashKey\fR returns the key for a given hash table entry,
-either as a pointer to a string, a one-word (``char *'') key, or
+either as a pointer to a string, a one-word
+.PQ "char *"
+key, or
as a pointer to the first word of an array of integers, depending
on the \fIkeyType\fR used to create a hash table.
In all cases \fBTcl_GetHashKey\fR returns a result with type
-``char *''.
+.QW "char *" .
When the key is a string or array, the result of \fBTcl_GetHashKey\fR
points to information in the table entry; this information will
remain valid until the entry is deleted or its table is deleted.
.PP
\fBTcl_FirstHashEntry\fR and \fBTcl_NextHashEntry\fR may be used
to scan all of the entries in a hash table.
-A structure of type ``Tcl_HashSearch'', provided by the client,
+A structure of type
+.QW Tcl_HashSearch ,
+provided by the client,
is used to keep track of progress through the table.
\fBTcl_FirstHashEntry\fR initializes the search record and
returns the first entry in the table (or NULL if the table is
@@ -207,9 +219,10 @@ NULL if the end of the table has been reached.
A call to \fBTcl_FirstHashEntry\fR followed by calls to
\fBTcl_NextHashEntry\fR will return each of the entries in
the table exactly once, in an arbitrary order.
-It is unadvisable to modify the structure of the table, e.g.
-by creating or deleting entries, while the search is in
-progress.
+It is inadvisable to modify the structure of the table, e.g.
+by creating or deleting entries, while the search is in progress,
+with the exception of deleting the entry returned by
+\fBTcl_FirstHashEntry\fR or \fBTcl_NextHashEntry\fR.
.PP
\fBTcl_HashStats\fR returns a dynamically-allocated string with
overall information about a hash table, such as the number of
@@ -228,10 +241,10 @@ to any of the fields of any of the hash-related data structures;
use the procedures and macros defined here.
.SH "THE TCL_HASHKEYTYPE STRUCTURE"
.PP
-Extension writers can define new hash key types by defining four
-procedures, initializing a Tcl_HashKeyType structure to describe
-the type, and calling \fBTcl_InitCustomHashTable\fR.
-The \fBTcl_HashKeyType\fR structure is defined as follows:
+Extension writers can define new hash key types by defining four procedures,
+initializing a \fBTcl_HashKeyType\fR structure to describe the type, and
+calling \fBTcl_InitCustomHashTable\fR. The \fBTcl_HashKeyType\fR structure is
+defined as follows:
.CS
typedef struct Tcl_HashKeyType {
int \fIversion\fR;
@@ -243,61 +256,71 @@ typedef struct Tcl_HashKeyType {
} Tcl_HashKeyType;
.CE
.PP
-The \fIversion\fR member is the version of the table. If this
-structure is extended in future then the version can be used
-to distinguish between different structures. It should be set
-to \fBTCL_HASH_KEY_TYPE_VERSION\fR.
+The \fIversion\fR member is the version of the table. If this structure is
+extended in future then the version can be used to distinguish between
+different structures. It should be set to \fBTCL_HASH_KEY_TYPE_VERSION\fR.
.PP
-The \fIflags\fR member is one or more of the following values OR'ed together:
+The \fIflags\fR member is 0 or one or more of the following values OR'ed
+together:
.IP \fBTCL_HASH_KEY_RANDOMIZE_HASH\fR 25
-There are some things, pointers for example which don't hash well
-because they do not use the lower bits. If this flag is set then the
-hash table will attempt to rectify this by randomising the bits and
-then using the upper N bits as the index into the table.
+There are some things, pointers for example which do not hash well because
+they do not use the lower bits. If this flag is set then the hash table will
+attempt to rectify this by randomizing the bits and then using the upper N
+bits as the index into the table.
+.IP \fBTCL_HASH_KEY_SYSTEM_HASH\fR 25
+.VS 8.5
+This flag forces Tcl to use the memory allocation procedures provided by the
+operating system when allocating and freeing memory used to store the hash
+table data structures, and not any of Tcl's own customized memory allocation
+routines. This is important if the hash table is to be used in the
+implementation of a custom set of allocation routines, or something that a
+custom set of allocation routines might depend on, in order to avoid any
+circular dependency.
+.VE 8.5
.PP
-The \fIhashKeyProc\fR member contains the address of a function
-called to calculate a hash value for the key.
+The \fIhashKeyProc\fR member contains the address of a function called to
+calculate a hash value for the key.
.CS
typedef unsigned int (Tcl_HashKeyProc) (
- Tcl_HashTable *\fItablePtr\fR,
- VOID *\fIkeyPtr\fR);
+ Tcl_HashTable *\fItablePtr\fR,
+ void *\fIkeyPtr\fR);
.CE
-If this is NULL then \fIkeyPtr\fR is used and
+If this is NULL then \fIkeyPtr\fR is used and
\fBTCL_HASH_KEY_RANDOMIZE_HASH\fR is assumed.
.PP
-The \fIcompareKeysProc\fR member contains the address of a function
-called to compare two keys.
+The \fIcompareKeysProc\fR member contains the address of a function called to
+compare two keys.
.CS
-typedef int (Tcl_CompareHashKeysProc) (VOID *\fIkeyPtr\fR,
- Tcl_HashEntry *\fIhPtr\fR);
+typedef int (Tcl_CompareHashKeysProc) (
+ void *\fIkeyPtr\fR,
+ Tcl_HashEntry *\fIhPtr\fR);
.CE
-If this is NULL then the \fIkeyPtr\fR pointers are compared.
-If the keys don't match then the function returns 0, otherwise
-it returns 1.
+If this is NULL then the \fIkeyPtr\fR pointers are compared. If the keys do
+not match then the function returns 0, otherwise it returns 1.
.PP
-The \fIallocEntryProc\fR member contains the address of a function
-called to allocate space for an entry and initialise the key.
+The \fIallocEntryProc\fR member contains the address of a function called to
+allocate space for an entry and initialize the key and clientData.
.CS
typedef Tcl_HashEntry *(Tcl_AllocHashEntryProc) (
- Tcl_HashTable *\fItablePtr\fR, VOID *\fIkeyPtr\fR);
+ Tcl_HashTable *\fItablePtr\fR,
+ void *\fIkeyPtr\fR);
.CE
If this is NULL then Tcl_Alloc is used to allocate enough space for a
-Tcl_HashEntry and the key pointer is assigned to key.oneWordValue.
-String keys and array keys use this function to allocate enough
-space for the entry and the key in one block, rather than doing
-it in two blocks. This saves space for a pointer to the key from
-the entry and another memory allocation. Tcl_Obj * keys use this
-function to allocate enough space for an entry and increment the
-reference count on the object.
-If
+Tcl_HashEntry, the key pointer is assigned to key.oneWordValue and the
+clientData is set to NULL. String keys and array keys use this function to
+allocate enough space for the entry and the key in one block, rather than
+doing it in two blocks. This saves space for a pointer to the key from the
+entry and another memory allocation. Tcl_Obj* keys use this function to
+allocate enough space for an entry and increment the reference count on the
+object.
.PP
-The \fIfreeEntryProc\fR member contains the address of a function
-called to free space for an entry.
+The \fIfreeEntryProc\fR member contains the address of a function called to
+free space for an entry.
.CS
typedef void (Tcl_FreeHashEntryProc) (Tcl_HashEntry *\fIhPtr\fR);
.CE
-If this is NULL then Tcl_Free is used to free the space for the
-entry. Tcl_Obj * keys use this function to decrement the
-reference count on the object.
+If this is NULL then Tcl_Free is used to free the space for the entry.
+Tcl_Obj* keys use this function to decrement the reference count on the
+object.
.SH KEYWORDS
hash table, key, lookup, search, value
diff --git a/doc/Init.3 b/doc/Init.3
index fdc66c7..f421479 100644
--- a/doc/Init.3
+++ b/doc/Init.3
@@ -14,15 +14,16 @@ Tcl_Init \- find and source initialization script
int
\fBTcl_Init\fR(\fIinterp\fR)
.SH ARGUMENTS
+.AS Tcl_Interp *interp
.AP Tcl_Interp *interp in
Interpreter to initialize.
.BE
.SH DESCRIPTION
.PP
-\fBTcl_Init\fR is a helper procedure that finds and \fBsource\fR's the
+\fBTcl_Init\fR is a helper procedure that finds and \fBsource\fRs the
\fBinit.tcl\fR script, which should exist somewhere on the Tcl library
-path.
+path.
.PP
\fBTcl_Init\fR is typically called from \fBTcl_AppInit\fR procedures.
diff --git a/doc/InitStubs.3 b/doc/InitStubs.3
index 2cfbb70..318c564 100644
--- a/doc/InitStubs.3
+++ b/doc/InitStubs.3
@@ -13,13 +13,13 @@ Tcl_InitStubs \- initialize the Tcl stubs mechanism
.nf
\fB#include <tcl.h>\fR
.sp
-CONST char *
+const char *
\fBTcl_InitStubs\fR(\fIinterp, version, exact\fR)
.SH ARGUMENTS
-.AS Tcl_Interp *interp in
+.AS Tcl_Interp *interp
.AP Tcl_Interp *interp in
Tcl interpreter handle.
-.AP "CONST char" *version in
+.AP "const char" *version in
A version string consisting of one or more decimal numbers
separated by dots.
.AP int exact in
@@ -59,8 +59,8 @@ steps:
Call \fBTcl_InitStubs\fR in the extension before calling any other
Tcl functions.
.IP 2) 5
-Define the USE_TCL_STUBS symbol. Typically, you would include the
--DUSE_TCL_STUBS flag when compiling the extension.
+Define the \fBUSE_TCL_STUBS\fR symbol. Typically, you would include the
+\fB\-DUSE_TCL_STUBS\fR flag when compiling the extension.
.IP 3) 5
Link the extension with the Tcl stubs library instead of the standard
Tcl library. On Unix platforms, the library name is
diff --git a/doc/IntObj.3 b/doc/IntObj.3
index 15b6bd9..5cf677d 100644
--- a/doc/IntObj.3
+++ b/doc/IntObj.3
@@ -5,10 +5,10 @@
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.so man.macros
-.TH Tcl_IntObj 3 8.0 Tcl "Tcl Library Procedures"
+.TH Tcl_IntObj 3 8.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
-Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, Tcl_GetIntFromObj, Tcl_GetLongFromObj, Tcl_GetWideIntFromObj \- manipulate Tcl objects as integers and wide integers
+Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, Tcl_GetIntFromObj, Tcl_GetLongFromObj, Tcl_GetWideIntFromObj, Tcl_NewBignumObj, Tcl_SetBignumObj, Tcl_GetBignumFromObj, Tcl_TakeBignumFromObj \- manipulate Tcl objects as integer values
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
@@ -19,18 +19,14 @@ Tcl_Obj *
Tcl_Obj *
\fBTcl_NewLongObj\fR(\fIlongValue\fR)
.sp
-.VS 8.4
Tcl_Obj *
\fBTcl_NewWideIntObj\fR(\fIwideValue\fR)
-.VE 8.4
.sp
\fBTcl_SetIntObj\fR(\fIobjPtr, intValue\fR)
.sp
\fBTcl_SetLongObj\fR(\fIobjPtr, longValue\fR)
.sp
-.VS 8.4
\fBTcl_SetWideIntObj\fR(\fIobjPtr, wideValue\fR)
-.VE 8.4
.sp
int
\fBTcl_GetIntFromObj\fR(\fIinterp, objPtr, intPtr\fR)
@@ -38,110 +34,127 @@ int
int
\fBTcl_GetLongFromObj\fR(\fIinterp, objPtr, longPtr\fR)
.sp
-.VS 8.4
int
\fBTcl_GetWideIntFromObj\fR(\fIinterp, objPtr, widePtr\fR)
-.VE 8.4
+.sp
+.sp
+.VS 8.5
+\fB#include <tclTomMath.h>\fR
+.sp
+Tcl_Obj *
+\fBTcl_NewBignumObj\fR(\fIbigValue\fR)
+.sp
+\fBTcl_SetBignumObj\fR(\fIobjPtr, bigValue\fR)
+.sp
+int
+\fBTcl_GetBignumFromObj\fR(\fIinterp, objPtr, bigValue\fR)
+.sp
+int
+\fBTcl_TakeBignumFromObj\fR(\fIinterp, objPtr, bigValue\fR)
+.sp
+int
+\fBTcl_InitBignumFromDouble\fR(\fIinterp, doubleValue, bigValue\fR)
+.VE 8.5
.SH ARGUMENTS
-.AS Tcl_WideInt *interp
+.AS Tcl_WideInt doubleValue in/out
.AP int intValue in
-Integer value used to initialize or set an integer object.
+Integer value used to initialize or set a Tcl object.
.AP long longValue in
-Long integer value used to initialize or set an integer object.
+Long integer value used to initialize or set a Tcl object.
.AP Tcl_WideInt wideValue in
-.VS 8.4
-Wide integer value (minimum 64-bits wide where supported by the
-compiler) used to initialize or set a wide integer object.
-.VE 8.4
+Wide integer value used to initialize or set a Tcl object.
.AP Tcl_Obj *objPtr in/out
-For \fBTcl_SetIntObj\fR, \fBTcl_SetLongObj\fR, and
-.VS 8.4
-\fBTcl_SetWideIntObj\fR, this points to the object to be converted to
-integer type. For \fBTcl_GetIntFromObj\fR, \fBTcl_GetLongFromObj\fR,
-and \fBTcl_GetWideIntFromObj\fR, this refers to the object from which
-to get an integer or long integer value; if \fIobjPtr\fR does not
-already point to an integer object (or a wide integer object in the
-case of \fBTcl_SetWideIntObj\fR and \fBTcl_GetWideIntFromObj\fR,) an
-.VE 8.4
-attempt will be made to convert it to one.
+For \fBTcl_SetIntObj\fR, \fBTcl_SetLongObj\fR, \fBTcl_SetWideIntObj\fR,
+and \fBTcl_SetBignumObj\fR, this points to the object in which to store an
+integral value. For \fBTcl_GetIntFromObj\fR, \fBTcl_GetLongFromObj\fR,
+\fBTcl_GetWideIntFromObj\fR, \fBTcl_GetBignumFromObj\fR, and
+\fBTcl_TakeBignumFromObj\fR, this refers to the object from which
+to retrieve an integral value.
.AP Tcl_Interp *interp in/out
-If an error occurs during conversion,
-an error message is left in the interpreter's result object
-unless \fIinterp\fR is NULL.
+When non-NULL, an error message is left here when integral value
+retrieval fails.
.AP int *intPtr out
-Points to place to store the integer value
-obtained by \fBTcl_GetIntFromObj\fR from \fIobjPtr\fR.
+Points to place to store the integer value retrieved from \fIobjPtr\fR.
.AP long *longPtr out
-Points to place to store the long integer value
-obtained by \fBTcl_GetLongFromObj\fR from \fIobjPtr\fR.
+Points to place to store the long integer value retrieved from \fIobjPtr\fR.
.AP Tcl_WideInt *widePtr out
-.VS 8.4
-Points to place to store the wide integer value
-obtained by \fBTcl_GetWideIntFromObj\fR from \fIobjPtr\fR.
-.VE 8.4
+Points to place to store the wide integer value retrieved from \fIobjPtr\fR.
+.AP mp_int *bigValue in/out
+.VS 8.5
+Points to a multi-precision integer structure declared by the LibTomMath
+library.
+.VE 8.5
+.AP double doubleValue in
+.VS 8.5
+Double value from which the integer part is determined and
+used to initialize a multi-precision integer value.
+.VE 8.5
.BE
.SH DESCRIPTION
.PP
-These procedures are used to create, modify, and read
-integer and wide integer Tcl objects from C code.
-\fBTcl_NewIntObj\fR, \fBTcl_NewLongObj\fR,
-\fBTcl_SetIntObj\fR, and \fBTcl_SetLongObj\fR
-create a new object of integer type
-or modify an existing object to have integer type,
-.VS 8.4
-and \fBTcl_NewWideIntObj\fR and \fBTcl_SetWideIntObj\fR create a new
-object of wide integer type or modify an existing object to have wide
-integer type.
-.VE 8.4
-\fBTcl_NewIntObj\fR and \fBTcl_SetIntObj\fR set the object to have the
-integer value given by \fIintValue\fR,
-\fBTcl_NewLongObj\fR and \fBTcl_SetLongObj\fR
-set the object to have the
-long integer value given by \fIlongValue\fR,
-.VS 8.4
-and \fBTcl_NewWideIntObj\fR and \fBTcl_SetWideIntObj\fR set the object
-to have the wide integer value given by \fIwideValue\fR.
-\fBTcl_NewIntObj\fR, \fBTcl_NewLongObj\fR and \fBTcl_NewWideIntObj\fR
-return a pointer to a newly created object with reference count zero.
-These procedures set the object's type to be integer
-and assign the integer value to the object's internal representation
-\fIlongValue\fR or \fIwideValue\fR member (as appropriate).
-\fBTcl_SetIntObj\fR, \fBTcl_SetLongObj\fR
-and \fBTcl_SetWideIntObj\fR
-.VE 8.4
-invalidate any old string representation and,
-if the object is not already an integer object,
-free any old internal representation.
+.VS 8.5
+These procedures are used to create, modify, and read Tcl objects
+that hold integral values.
.PP
-\fBTcl_GetIntFromObj\fR and \fBTcl_GetLongFromObj\fR
-attempt to return an integer value from the Tcl object \fIobjPtr\fR,
-.VS 8.4
-and \fBTcl_GetWideIntFromObj\fR attempts to return a wide integer
-value from the Tcl object \fIobjPtr\fR.
-If the object is not already an integer object,
-or a wide integer object in the case of \fBTcl_GetWideIntFromObj\fR
-.VE 8.4
-they will attempt to convert it to one.
-If an error occurs during conversion, they return \fBTCL_ERROR\fR
-and leave an error message in the interpreter's result object
-unless \fIinterp\fR is NULL.
-Also, if the long integer held in the object's internal representation
-\fIlongValue\fR member can not be represented in a (non-long) integer,
-\fBTcl_GetIntFromObj\fR returns \fBTCL_ERROR\fR
-and leaves an error message in the interpreter's result object
-unless \fIinterp\fR is NULL.
-Otherwise, all three procedures return \fBTCL_OK\fR and
-store the integer, long integer value
-.VS 8.4
-or wide integer in the address given by \fIintPtr\fR, \fIlongPtr\fR
-and \fIwidePtr\fR
-.VE 8.4
-respectively. If the object is not already an integer or wide integer
-object, the conversion will free any old internal representation.
-
+The different routines exist to accommodate different integral types in C
+with which values might be exchanged. The C integral types for which Tcl
+provides value exchange routines are \fBint\fR, \fBlong int\fR,
+\fBTcl_WideInt\fR, and \fBmp_int\fR. The \fBint\fR and \fBlong int\fR types
+are provided by the C language standard. The \fBTcl_WideInt\fR type is a
+typedef defined to be whatever signed integral type covers at least the
+64-bit integer range (-9223372036854775808 to 9223372036854775807). Depending
+on the platform and the C compiler, the actual type might be
+\fBlong int\fR, \fBlong long int\fR, \fBint64\fR, or something else.
+The \fBmp_int\fR type is a multiple-precision integer type defined
+by the LibTomMath multiple-precision integer library.
+.PP
+The \fBTcl_NewIntObj\fR, \fBTcl_NewLongObj\fR, \fBTcl_NewWideIntObj\fR,
+and \fBTcl_NewBignumObj\fR routines each create and return a new
+Tcl object initialized to the integral value of the argument. The
+returned Tcl object is unshared.
+.PP
+The \fBTcl_SetIntObj\fR, \fBTcl_SetLongObj\fR, \fBTcl_SetWideIntObj\fR,
+and \fBTcl_SetBignumObj\fR routines each set the value of an existing
+Tcl object pointed to by \fIobjPtr\fR to the integral value provided
+by the other argument. The \fIobjPtr\fR argument must point to an
+unshared Tcl object. Any attempt to set the value of a shared Tcl object
+violates Tcl's copy-on-write policy. Any existing string representation
+or internal representation in the unshared Tcl object will be freed
+as a consequence of setting the new value.
+.PP
+The \fBTcl_GetIntFromObj\fR, \fBTcl_GetLongFromObj\fR,
+\fBTcl_GetWideIntFromObj\fR, \fBTcl_GetBignumFromObj\fR, and
+\fBTcl_TakeBignumFromObj\fR routines attempt to retrieve an integral
+value of the appropriate type from the Tcl object \fIobjPtr\fR. If the
+attempt succeeds, then \fBTCL_OK\fR is returned, and the value is
+written to the storage provided by the caller. The attempt might
+fail if \fIobjPtr\fR does not hold an integral value, or if the
+value exceeds the range of the target type. If the attempt fails,
+then \fBTCL_ERROR\fR is returned, and if \fIinterp\fR is non-NULL,
+an error message is left in \fIinterp\fR. The \fBTcl_ObjType\fR
+of \fIobjPtr\fR may be changed to make subsequent calls to the
+same routine more efficient. Unlike the other functions,
+\fBTcl_TakeBignumFromObj\fR may set the content of the Tcl object
+\fIobjPtr\fR to an empty string in the process of retrieving the
+multiple-precision integer value.
+.PP
+The choice between \fBTcl_GetBignumFromObj\fR and
+\fBTcl_TakeBignumFromObj\fR is governed by how the caller will
+continue to use \fIobjPtr\fR. If after the \fBmp_int\fR value
+is retrieved from \fIobjPtr\fR, the caller will make no more
+use of \fIobjPtr\fR, then using \fBTcl_TakeBignumFromObj\fR
+permits Tcl to detect when an unshared \fIobjPtr\fR permits the
+value to be moved instead of copied, which should be more efficient.
+If anything later in the caller requires
+\fIobjPtr\fR to continue to hold the same value, then
+\fBTcl_GetBignumFromObj\fR must be chosen.
+.PP
+The \fBTcl_InitBignumFromDouble\fR routine is a utility procedure
+that extracts the integer part of \fIdoubleValue\fR and stores that
+integer value in the \fBmp_int\fR value \fIbigValue\fR.
+.VE 8.5
.SH "SEE ALSO"
Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
-
.SH KEYWORDS
integer, integer object, integer type, internal representation, object, object type, string representation
diff --git a/doc/Interp.3 b/doc/Interp.3
index 7d1f515..0b1de03 100644
--- a/doc/Interp.3
+++ b/doc/Interp.3
@@ -15,9 +15,9 @@ Tcl_Interp \- client-visible fields of interpreter structures
\fB#include <tcl.h>\fR
.sp
typedef struct {
- char *\fIresult\fR;
- Tcl_FreeProc *\fIfreeProc\fR;
- int \fIerrorLine\fR;
+ char *\fIresult\fR;
+ Tcl_FreeProc *\fIfreeProc\fR;
+ int \fIerrorLine\fR;
} Tcl_Interp;
typedef void Tcl_FreeProc(char *\fIblockPtr\fR);
@@ -28,17 +28,23 @@ typedef void Tcl_FreeProc(char *\fIblockPtr\fR);
The \fBTcl_CreateInterp\fR procedure returns a pointer to a Tcl_Interp
structure. This pointer is then passed into other Tcl procedures
to process commands in the interpreter and perform other operations
-on the interpreter. Interpreter structures contain many many fields
+on the interpreter. Interpreter structures contain many fields
that are used by Tcl, but only three that may be accessed by
clients: \fIresult\fR, \fIfreeProc\fR, and \fIerrorLine\fR.
.PP
+.VS 8.5
+\fBNote that access to all three fields, \fIresult\fB, \fIfreeProc\fB and
+\fIerrorLine\fB is deprecated.\fR Use \fBTcl_SetResult\fR,
+\fBTcl_GetResult\fR, and \fBTcl_GetReturnOptions\fR instead.
+.VE 8.5
+.PP
The \fIresult\fR and \fIfreeProc\fR fields are used to return
results or error messages from commands.
This information is returned by command procedures back to \fBTcl_Eval\fR,
and by \fBTcl_Eval\fR back to its callers.
The \fIresult\fR field points to the string that represents the
result or error message, and the \fIfreeProc\fR field tells how
-to dispose of the storage for the string when it isn't needed anymore.
+to dispose of the storage for the string when it is not needed anymore.
The easiest way for command procedures to manipulate these
fields is to call procedures like \fBTcl_SetResult\fR
or \fBTcl_AppendResult\fR; they
@@ -55,7 +61,6 @@ should point to an empty string.
Normally, results are assumed to be statically allocated,
which means that the contents will not change before the next time
\fBTcl_Eval\fR is called or some other command procedure is invoked.
-.VS
In this case, the \fIfreeProc\fR field must be zero.
Alternatively, a command procedure may dynamically
allocate its return value (e.g. using \fBTcl_Alloc\fR)
@@ -64,7 +69,6 @@ In this case, the command procedure must also set \fIinterp->freeProc\fR
to the address of a procedure that can free the value, or \fBTCL_DYNAMIC\fR
if the storage was allocated directly by Tcl or by a call to
\fBTcl_Alloc\fR.
-.VE
If \fIinterp->freeProc\fR is non-zero, then Tcl will call \fIfreeProc\fR
to free the space pointed to by \fIinterp->result\fR before it
invokes the next command.
@@ -76,10 +80,8 @@ macro should be used for this purpose).
\fIFreeProc\fR should have arguments and result that match the
\fBTcl_FreeProc\fR declaration above: it receives a single
argument which is a pointer to the result value to free.
-.VS
In most applications \fBTCL_DYNAMIC\fR is the only non-zero value ever
used for \fIfreeProc\fR.
-.VE
However, an application may store a different procedure address
in \fIfreeProc\fR in order to use an alternate memory allocator
or in order to do other cleanup when the result memory is freed.
diff --git a/doc/Limit.3 b/doc/Limit.3
new file mode 100644
index 0000000..928ebe1
--- /dev/null
+++ b/doc/Limit.3
@@ -0,0 +1,194 @@
+'\"
+'\" Copyright (c) 2004 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.so man.macros
+.TH Tcl_LimitCheck 3 8.5 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_LimitAddHandler, Tcl_LimitCheck, Tcl_LimitExceeded, Tcl_LimitGetCommands, Tcl_LimitGetGranularity, Tcl_LimitGetTime, Tcl_LimitReady, Tcl_LimitRemoveHandler, Tcl_LimitSetCommands, Tcl_LimitSetGranularity, Tcl_LimitSetTime, Tcl_LimitTypeEnabled, Tcl_LimitTypeExceeded, Tcl_LimitTypeReset, Tcl_LimitTypeSet \- manage and check resource limits on interpreters
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+int
+\fBTcl_LimitCheck\fR(\fIinterp\fR)
+.sp
+int
+\fBTcl_LimitReady\fR(\fIinterp\fR)
+.sp
+int
+\fBTcl_LimitExceeded\fR(\fIinterp\fR)
+.sp
+int
+\fBTcl_LimitTypeExceeded\fR(\fIinterp, type\fR)
+.sp
+int
+\fBTcl_LimitTypeEnabled\fR(\fIinterp, type\fR)
+.sp
+void
+\fBTcl_LimitTypeSet\fR(\fIinterp, type\fR)
+.sp
+void
+\fBTcl_LimitTypeReset\fR(\fIinterp, type\fR)
+.sp
+int
+\fBTcl_LimitGetCommands\fR(\fIinterp\fR)
+.sp
+void
+\fBTcl_LimitSetCommands\fR(\fIinterp, commandLimit\fR)
+.sp
+void
+\fBTcl_LimitGetTime\fR(\fIinterp, timeLimitPtr\fR)
+.sp
+void
+\fBTcl_LimitSetTime\fR(\fIinterp, timeLimitPtr\fR)
+.sp
+int
+\fBTcl_LimitGetGranularity\fR(\fIinterp, type\fR)
+.sp
+void
+\fBTcl_LimitSetGranularity\fR(\fIinterp, type, granularity\fR)
+.sp
+void
+\fBTcl_LimitAddHandler\fR(\fIinterp, type, handlerProc, clientData, deleteProc\fR)
+.sp
+void
+\fBTcl_LimitRemoveHandler\fR(\fIinterp, type, handlerProc, clientData\fR)
+.SH ARGUMENTS
+.AS Tcl_LimitHandlerDeleteProc commandLimit in/out
+.AP Tcl_Interp *interp in
+Interpreter that the limit being managed applies to or that will have
+its limits checked.
+.AP int type in
+The type of limit that the operation refers to. This must be either
+\fBTCL_LIMIT_COMMANDS\fR or \fBTCL_LIMIT_TIME\fR.
+.AP int commandLimit in
+The maximum number of commands (as reported by \fBinfo cmdcount\fR)
+that may be executed in the interpreter.
+.AP Tcl_Time *timeLimitPtr in/out
+A pointer to a structure that will either have the new time limit read
+from (\fBTcl_LimitSetTime\fR) or the current time limit written to
+(\fBTcl_LimitGetTime\fR).
+.AP int granularity in
+Divisor that indicates how often a particular limit should really be
+checked. Must be at least 1.
+.AP Tcl_LimitHandlerProc *handlerProc in
+Function to call when a particular limit is exceeded. If the
+\fIhandlerProc\fR removes or raises the limit during its processing,
+the limited interpreter will be permitted to continue to process after
+the handler returns. Many handlers may be attached to the same
+interpreter limit; their order of execution is not defined, and they
+must be identified by \fIhandlerProc\fR and \fIclientData\fR when they
+are deleted.
+.AP ClientData clientData in
+Arbitrary pointer-sized word used to pass some context to the
+\fIhandlerProc\fR function.
+.AP Tcl_LimitHandlerDeleteProc *deleteProc in
+Function to call whenever a handler is deleted. May be NULL if the
+\fIclientData\fR requires no deletion.
+.BE
+
+.SH DESCRIPTION
+.PP
+Tcl's interpreter resource limit subsystem allows for close control
+over how much computation time a script may use, and is useful for
+cases where a program is divided into multiple pieces where some parts
+are more trusted than others (e.g. web application servers).
+.PP
+Every interpreter may have a limit on the wall-time for execution, and
+a limit on the number of commands that the interpreter may execute.
+Since checking of these limits is potentially expensive (especially
+the time limit), each limit also has a checking granularity, which is
+a divisor for an internal count of the number of points in the core
+where a check may be performed (which is immediately before executing
+a command and at an unspecified frequency between running commands,
+which can happen in empty-bodied \fBwhile\fR loops).
+.PP
+The final component of the limit engine is a callback scheme which
+allows for notifications of when a limit has been exceeded. These
+callbacks can just provide logging, or may allocate more resources to
+the interpreter to permit it to continue processing longer.
+.PP
+When a limit is exceeded (and the callbacks have run; the order of
+execution of the callbacks is unspecified) execution in the limited
+interpreter is stopped by raising an error and setting a flag that
+prevents the \fBcatch\fR command in that interpreter from trapping
+that error. It is up to the context that started execution in that
+interpreter (typically a master interpreter) to handle the error.
+.SH "LIMIT CHECKING API"
+.PP
+To check the resource limits for an interpreter, call
+\fBTcl_LimitCheck\fR, which returns \fBTCL_OK\fR if the limit was not
+exceeded (after processing callbacks) and \fBTCL_ERROR\fR if the limit was
+exceeded (in which case an error message is also placed in the
+interpreter result). That function should only be called when
+\fBTcl_LimitReady\fR returns non-zero so that granularity policy is
+enforced. This API is designed to be similar in usage to
+\fBTcl_AsyncReady\fR and \fBTcl_AsyncInvoke\fR.
+.PP
+When writing code that may behave like \fBcatch\fR in respect of
+errors, you should only trap an error if \fBTcl_LimitExceeded\fR
+returns zero. If it returns non-zero, the interpreter is in a
+limit-exceeded state and errors should be allowed to propagate to the
+calling context. You can also check whether a particular type of
+limit has been exceeded using \fBTcl_LimitTypeExceeded\fR.
+.SH "LIMIT CONFIGURATION"
+.PP
+To check whether a limit has been set (but not whether it has actually
+been exceeded) on an interpreter, call \fBTcl_LimitTypeEnabled\fR with
+the type of limit you want to check. To enable a particular limit
+call \fBTcl_LimitTypeSet\fR, and to disable a limit call
+\fBTcl_LimitTypeReset\fR.
+.PP
+The level of a command limit may be set using
+\fBTcl_LimitSetCommands\fR, and retrieved using
+\fBTcl_LimitGetCommands\fR. Similarly for a time limit with
+\fBTcl_LimitSetTime\fR and \fBTcl_LimitGetTime\fR respectively, but
+with that API the time limit is copied from and to the Tcl_Time
+structure that the \fItimeLimitPtr\fR argument points to.
+.PP
+The checking granularity for a particular limit may be set using
+\fBTcl_LimitSetGranularity\fR and retrieved using
+\fBTcl_LimitGetGranularity\fR. Note that granularities must always be
+positive.
+.SS "LIMIT CALLBACKS"
+.PP
+To add a handler callback to be invoked when a limit is exceeded, call
+\fBTcl_LimitAddHandler\fR. The \fIhandlerProc\fR argument describes
+the function that will actually be called; it should have the
+following prototype:
+.PP
+.CS
+typedef void Tcl_LimitHandlerProc(
+ ClientData \fIclientData\fR,
+ Tcl_Interp *\fIinterp\fR);
+.CE
+.PP
+The \fIclientData\fR argument to the handler will be whatever is
+passed to the \fIclientData\fR argument to \fBTcl_LimitAddHandler\fR,
+and the \fIinterp\fR is the interpreter that had its limit exceeded.
+.PP
+The \fIdeleteProc\fR argument to \fBTcl_LimitAddHandler\fR is a
+function to call to delete the \fIclientData\fR value. It may be
+\fBTCL_STATIC\fR or NULL if no deletion action is necessary, or
+\fBTCL_DYNAMIC\fR if all that is necessary is to free the structure with
+\fBTcl_Free\fR. Otherwise, it should refer to a function with the
+following prototype:
+.PP
+.CS
+typedef void Tcl_LimitHandlerDeleteProc(
+ ClientData \fIclientData\fR);
+.CE
+.PP
+A limit handler may be deleted using \fBTcl_LimitRemoveHandler\fR; the
+handler removed will be the first one found (out of the handlers added
+with \fBTcl_LimitAddHandler\fR) with exactly matching \fItype\fR,
+\fIhandlerProc\fR and \fIclientData\fR arguments. This function
+always invokes the \fIdeleteProc\fR on the \fIclientData\fR (unless
+the \fIdeleteProc\fR was NULL or \fBTCL_STATIC\fR).
+
+.SH KEYWORDS
+interpreter, resource, limit, commands, time, callback
diff --git a/doc/LinkVar.3 b/doc/LinkVar.3
index a1dfcca..6361fb4 100644
--- a/doc/LinkVar.3
+++ b/doc/LinkVar.3
@@ -25,17 +25,24 @@ int
.AP Tcl_Interp *interp in
Interpreter that contains \fIvarName\fR.
Also used by \fBTcl_LinkVar\fR to return error messages.
-.AP "CONST char" *varName in
-Name of global variable.
+.AP "const char" *varName in
+Name of global variable.
.AP char *addr in
Address of C variable that is to be linked to \fIvarName\fR.
.AP int type in
-Type of C variable. Must be one of TCL_LINK_INT, TCL_LINK_DOUBLE,
-.VS 8.4
-TCL_LINK_WIDE_INT,
-.VE 8.4
-TCL_LINK_BOOLEAN, or TCL_LINK_STRING, optionally OR'ed with
-TCL_LINK_READ_ONLY to make Tcl variable read-only.
+Type of C variable. Must be one of \fBTCL_LINK_INT\fR,
+.VS 8.5
+\fBTCL_LINK_UINT\fR, \fBTCL_LINK_CHAR\fR, \fBTCL_LINK_UCHAR\fR,
+\fBTCL_LINK_SHORT\fR, \fBTCL_LINK_USHORT\fR, \fBTCL_LINK_LONG\fR,
+\fBTCL_LINK_ULONG\fR,
+.VE 8.5
+\fBTCL_LINK_WIDE_INT\fR,
+.VS 8.5
+\fBTCL_LINK_WIDE_UINT\fR, \fBTCL_LINK_FLOAT\fR,
+.VE 8.5
+\fBTCL_LINK_DOUBLE\fR, \fBTCL_LINK_BOOLEAN\fR, or
+\fBTCL_LINK_STRING\fR, optionally OR'ed with \fBTCL_LINK_READ_ONLY\fR
+to make Tcl variable read-only.
.BE
.SH DESCRIPTION
@@ -46,14 +53,14 @@ given by \fIaddr\fR.
Whenever the Tcl variable is read the value of the C variable will
be returned, and whenever the Tcl variable is written the C
variable will be updated to have the same value.
-\fBTcl_LinkVar\fR normally returns TCL_OK; if an error occurs
+\fBTcl_LinkVar\fR normally returns \fBTCL_OK\fR; if an error occurs
while setting up the link (e.g. because \fIvarName\fR is the
-name of array) then TCL_ERROR is returned and the interpreter's result
+name of array) then \fBTCL_ERROR\fR is returned and the interpreter's result
contains an error message.
.PP
The \fItype\fR argument specifies the type of the C variable,
and must have one of the following values, optionally OR'ed with
-TCL_LINK_READ_ONLY:
+\fBTCL_LINK_READ_ONLY\fR:
.TP
\fBTCL_LINK_INT\fR
The C variable is of type \fBint\fR.
@@ -61,6 +68,61 @@ Any value written into the Tcl variable must have a proper integer
form acceptable to \fBTcl_GetIntFromObj\fR; attempts to write
non-integer values into \fIvarName\fR will be rejected with
Tcl errors.
+.VS 8.5
+.TP
+\fBTCL_LINK_UINT\fR
+The C variable is of type \fBunsigned int\fR.
+Any value written into the Tcl variable must have a proper unsigned
+integer form acceptable to \fBTcl_GetWideIntFromObj\fR and in the
+platform's defined range for the \fBunsigned int\fR type; attempts to
+write non-integer values (or values outside the range) into
+\fIvarName\fR will be rejected with Tcl errors.
+.TP
+\fBTCL_LINK_CHAR\fR
+The C variable is of type \fBchar\fR.
+Any value written into the Tcl variable must have a proper integer
+form acceptable to \fBTcl_GetIntFromObj\fR and be in the range of the
+\fBchar\fR datatype; attempts to write non-integer or out-of-range
+values into \fIvarName\fR will be rejected with Tcl errors.
+.TP
+\fBTCL_LINK_UCHAR\fR
+The C variable is of type \fBunsigned char\fR.
+Any value written into the Tcl variable must have a proper unsigned
+integer form acceptable to \fBTcl_GetIntFromObj\fR and in the
+platform's defined range for the \fBunsigned char\fR type; attempts to
+write non-integer values (or values outside the range) into
+\fIvarName\fR will be rejected with Tcl errors.
+.TP
+\fBTCL_LINK_SHORT\fR
+The C variable is of type \fBshort\fR.
+Any value written into the Tcl variable must have a proper integer
+form acceptable to \fBTcl_GetIntFromObj\fR and be in the range of the
+\fBshort\fR datatype; attempts to write non-integer or out-of-range
+values into \fIvarName\fR will be rejected with Tcl errors.
+.TP
+\fBTCL_LINK_USHORT\fR
+The C variable is of type \fBunsigned short\fR.
+Any value written into the Tcl variable must have a proper unsigned
+integer form acceptable to \fBTcl_GetIntFromObj\fR and in the
+platform's defined range for the \fBunsigned short\fR type; attempts to
+write non-integer values (or values outside the range) into
+\fIvarName\fR will be rejected with Tcl errors.
+.TP
+\fBTCL_LINK_LONG\fR
+The C variable is of type \fBlong\fR.
+Any value written into the Tcl variable must have a proper integer
+form acceptable to \fBTcl_GetLongFromObj\fR; attempts to write
+non-integer or out-of-range
+values into \fIvarName\fR will be rejected with Tcl errors.
+.TP
+\fBTCL_LINK_ULONG\fR
+The C variable is of type \fBunsigned long\fR.
+Any value written into the Tcl variable must have a proper unsigned
+integer form acceptable to \fBTcl_GetWideIntFromObj\fR and in the
+platform's defined range for the \fBunsigned long\fR type; attempts to
+write non-integer values (or values outside the range) into
+\fIvarName\fR will be rejected with Tcl errors.
+.VE 8.5
.TP
\fBTCL_LINK_DOUBLE\fR
The C variable is of type \fBdouble\fR.
@@ -68,21 +130,44 @@ Any value written into the Tcl variable must have a proper real
form acceptable to \fBTcl_GetDoubleFromObj\fR; attempts to write
non-real values into \fIvarName\fR will be rejected with
Tcl errors.
+.VS 8.5
+.TP
+\fBTCL_LINK_FLOAT\fR
+The C variable is of type \fBfloat\fR.
+Any value written into the Tcl variable must have a proper real
+form acceptable to \fBTcl_GetDoubleFromObj\fR and must be within the
+range acceptable for a \fBfloat\fR; attempts to
+write non-real values (or values outside the range) into
+\fIvarName\fR will be rejected with Tcl errors.
+.VE 8.5
.TP
\fBTCL_LINK_WIDE_INT\fR
-.VS 8.4
The C variable is of type \fBTcl_WideInt\fR (which is an integer type
at least 64-bits wide on all platforms that can support it.)
Any value written into the Tcl variable must have a proper integer
form acceptable to \fBTcl_GetWideIntFromObj\fR; attempts to write
non-integer values into \fIvarName\fR will be rejected with
Tcl errors.
-.VE 8.4
+.VS 8.5
+.TP
+\fBTCL_LINK_WIDE_UINT\fR
+The C variable is of type \fBTcl_WideUInt\fR (which is an unsigned
+integer type at least 64-bits wide on all platforms that can support
+it.)
+Any value written into the Tcl variable must have a proper unsigned
+integer form acceptable to \fBTcl_GetWideIntFromObj\fR (it will be
+cast to unsigned);
+.\" FIXME! Use bignums instead.
+attempts to write non-integer values into \fIvarName\fR will be
+rejected with Tcl errors.
+.VE 8.5
.TP
\fBTCL_LINK_BOOLEAN\fR
The C variable is of type \fBint\fR.
-If its value is zero then it will read from Tcl as ``0'';
-otherwise it will read from Tcl as ``1''.
+If its value is zero then it will read from Tcl as
+.QW 0 ;
+otherwise it will read from Tcl as
+.QW 1 .
Whenever \fIvarName\fR is
modified, the C variable will be set to a 0 or 1 value.
Any value written into the Tcl variable must have a proper boolean
@@ -92,17 +177,16 @@ Tcl errors.
.TP
\fBTCL_LINK_STRING\fR
The C variable is of type \fBchar *\fR.
-.VS
If its value is not NULL then it must be a pointer to a string
allocated with \fBTcl_Alloc\fR or \fBckalloc\fR.
-.VE
Whenever the Tcl variable is modified the current C string will be
freed and new memory will be allocated to hold a copy of the variable's
new value.
If the C variable contains a NULL pointer then the Tcl variable
-will read as ``NULL''.
+will read as
+.QW NULL .
.PP
-If the TCL_LINK_READ_ONLY flag is present in \fItype\fR then the
+If the \fBTCL_LINK_READ_ONLY\fR flag is present in \fItype\fR then the
variable will be read-only from Tcl, so that its value can only be
changed by modifying the C variable.
Attempts to write the variable from Tcl will be rejected with errors.
diff --git a/doc/ListObj.3 b/doc/ListObj.3
index 2adea4e..443eafe 100644
--- a/doc/ListObj.3
+++ b/doc/ListObj.3
@@ -36,7 +36,7 @@ int
int
\fBTcl_ListObjReplace\fR(\fIinterp, listPtr, first, count, objc, objv\fR)
.SH ARGUMENTS
-.AS Tcl_Interp "*CONST objv[]" out
+.AS "Tcl_Obj *const" *elemListPtr in/out
.AP Tcl_Interp *interp in
If an error occurs while converting an object to be a list object,
an error message is left in the interpreter's result object
@@ -71,13 +71,11 @@ will insert into a new list object,
and \fBTcl_ListObjReplace\fR will insert into \fIlistPtr\fR.
For \fBTcl_SetListObj\fR,
the number of Tcl objects to insert into \fIobjPtr\fR.
-.VS
-.AP Tcl_Obj "*CONST\ objv[]" in
+.AP "Tcl_Obj *const" objv[] in
An array of pointers to objects.
\fBTcl_NewListObj\fR will insert these objects into a new list object
and \fBTcl_ListObjReplace\fR will insert them into an existing \fIlistPtr\fR.
Each object will become a separate list element.
-.VE
.AP int *intPtr out
Points to location where \fBTcl_ListObjLength\fR
stores the length of the list.
@@ -151,8 +149,9 @@ has reference count zero.
the elements in a list object. It returns the count by storing it in the
address \fIobjcPtr\fR. Similarly, it returns the array pointer by storing
it in the address \fIobjvPtr\fR.
-The memory pointed to is managed by Tcl and should not be freed by the
-caller.
+The memory pointed to is managed by Tcl and should not be freed or written
+to by the caller. If the list is empty, 0 is stored at \fIobjcPtr\fR
+and NULL at \fIobjvPtr\fR.
If \fIlistPtr\fR is not already a list object, \fBTcl_ListObjGetElements\fR
will attempt to convert it to one; if the conversion fails, it returns
\fBTCL_ERROR\fR and leaves an error message in the interpreter's result
@@ -219,27 +218,33 @@ it can be used to implement a number of list operations.
For example, the following code inserts the \fIobjc\fR objects
referenced by the array of object pointers \fIobjv\fR
just before the element \fIindex\fR of the list referenced by \fIlistPtr\fR:
+.PP
.CS
-result = Tcl_ListObjReplace(interp, listPtr, index, 0, objc, objv);
+result = Tcl_ListObjReplace(interp, listPtr, index, 0,
+ objc, objv);
.CE
+.PP
Similarly, the following code appends the \fIobjc\fR objects
referenced by the array \fIobjv\fR
to the end of the list \fIlistPtr\fR:
+.PP
.CS
result = Tcl_ListObjLength(interp, listPtr, &length);
if (result == TCL_OK) {
- result = Tcl_ListObjReplace(interp, listPtr, length, 0, objc, objv);
+ result = Tcl_ListObjReplace(interp, listPtr, length, 0,
+ objc, objv);
}
.CE
+.PP
The \fIcount\fR list elements starting at \fIfirst\fR can be deleted
by simply calling \fBTcl_ListObjReplace\fR
with a NULL \fIobjvPtr\fR:
+.PP
.CS
-result = Tcl_ListObjReplace(interp, listPtr, first, count, 0, NULL);
+result = Tcl_ListObjReplace(interp, listPtr, first, count,
+ 0, NULL);
.CE
-
.SH "SEE ALSO"
Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
-
.SH KEYWORDS
append, index, insert, internal representation, length, list, list object, list type, object, object type, replace, string representation
diff --git a/doc/Namespace.3 b/doc/Namespace.3
new file mode 100644
index 0000000..5477329
--- /dev/null
+++ b/doc/Namespace.3
@@ -0,0 +1,165 @@
+'\"
+'\" Copyright (c) 2003 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+'\" Note that some of these functions do not seem to belong, but they
+'\" were all introduced with the same TIP (#139)
+'\"
+.so man.macros
+.TH Tcl_Namespace 3 8.5 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_AppendExportList, Tcl_CreateNamespace, Tcl_DeleteNamespace, Tcl_Export, Tcl_FindCommand, Tcl_FindNamespace, Tcl_ForgetImport, Tcl_GetCurrentNamespace, Tcl_GetGlobalNamespace, Tcl_GetNamespaceUnknownHandler, Tcl_Import, Tcl_SetNamespaceUnknownHandler \- manipulate namespaces
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+Tcl_Namespace *
+\fBTcl_CreateNamespace\fR(\fIinterp, name, clientData, deleteProc\fR)
+.sp
+\fBTcl_DeleteNamespace\fR(\fInsPtr\fR)
+.sp
+int
+\fBTcl_AppendExportList\fR(\fIinterp, nsPtr, objPtr\fR)
+.sp
+int
+\fBTcl_Export\fR(\fIinterp, nsPtr, pattern, resetListFirst\fR)
+.sp
+int
+\fBTcl_Import\fR(\fIinterp, nsPtr, pattern, allowOverwrite\fR)
+.sp
+int
+\fBTcl_ForgetImport\fR(\fIinterp, nsPtr, pattern\fR)
+.sp
+Tcl_Namespace *
+\fBTcl_GetCurrentNamespace\fR(\fIinterp\fR)
+.sp
+Tcl_Namespace *
+\fBTcl_GetGlobalNamespace\fR(\fIinterp\fR)
+.sp
+Tcl_Namespace *
+\fBTcl_FindNamespace\fR(\fIinterp, name, contextNsPtr, flags\fR)
+.sp
+Tcl_Command
+\fBTcl_FindCommand\fR(\fIinterp, name, contextNsPtr, flags\fR)
+.sp
+Tcl_Obj *
+\fBTcl_GetNamespaceUnknownHandler(\fIinterp, nsPtr\fR)
+.sp
+int
+\fBTcl_SetNamespaceUnknownHandler(\fIinterp, nsPtr, handlerPtr\fR)
+.SH ARGUMENTS
+.AS Tcl_NamespaceDeleteProc allowOverwrite in/out
+.AP Tcl_Interp *interp in/out
+The interpreter in which the namespace exists and where name lookups
+are performed. Also where error result messages are written.
+.AP "const char" *name in
+The name of the namespace or command to be created or accessed.
+.AP ClientData clientData in
+A context pointer by the creator of the namespace. Not interpreted by
+Tcl at all.
+.AP Tcl_NamespaceDeleteProc *deleteProc in
+A pointer to function to call when the namespace is deleted, or NULL
+if no such callback is to be performed.
+.AP Tcl_Namespace *nsPtr in
+The namespace to be manipulated, or NULL (for other than
+\fBTcl_DeleteNamespace\fR) to manipulate the current namespace.
+.AP Tcl_Obj *objPtr out
+A reference to an unshared object to which the function output will be
+written.
+.AP "const char" *pattern in
+The glob-style pattern (see \fBTcl_StringMatch\fR) that describes the
+commands to be imported or exported.
+.AP int resetListFirst in
+Whether the list of export patterns should be reset before adding the
+current pattern to it.
+.AP int allowOverwrite in
+Whether new commands created by this import action can overwrite
+existing commands.
+.AP Tcl_Namespace *contextNsPtr in
+The location in the namespace hierarchy where the search for a
+namespace or command should be conducted relative to when the search
+term is not rooted at the global namespace. NULL indicates the
+current namespace.
+.AP int flags in
+OR-ed combination of bits controlling how the search is to be
+performed. The following flags are supported: \fBTCL_GLOBAL_ONLY\fR
+(indicates that the search is always to be conducted relative to the
+global namespace), \fBTCL_NAMESPACE_ONLY\fR (just for \fBTcl_FindCommand\fR;
+indicates that the search is always to be conducted relative to the
+context namespace), and \fBTCL_LEAVE_ERR_MSG\fR (indicates that an error
+message should be left in the interpreter if the search fails.)
+.AP Tcl_Obj *handlerPtr in
+A script fragment to be installed as the unknown command handler for the
+namespace, or NULL to reset the handler to its default.
+.BE
+
+.SH DESCRIPTION
+.PP
+Namespaces are hierarchic naming contexts that can contain commands
+and variables. They also maintain a list of patterns that describes
+what commands are exported, and can import commands that have been
+exported by other namespaces. Namespaces can also be manipulated
+through the Tcl command \fBnamespace\fR.
+.PP
+The \fITcl_Namespace\fR structure encapsulates a namespace, and is
+guaranteed to have the following fields in it: \fIname\fR (the local
+name of the namespace, with no namespace separator characters in it,
+with empty denoting the global namespace), \fIfullName\fR (the fully
+specified name of the namespace), \fIclientData\fR, \fIdeleteProc\fR
+(the values specified in the call to \fBTcl_CreateNamespace\fR), and
+\fIparentPtr\fR (a pointer to the containing namespace, or NULL for
+the global namespace.)
+.PP
+\fBTcl_CreateNamespace\fR creates a new namespace. The
+\fIdeleteProc\fR will have the following type signature:
+.CS
+typedef void (Tcl_NamespaceDeleteProc) (ClientData clientData);
+.CE
+.PP
+\fBTcl_DeleteNamespace\fR deletes a namespace.
+.PP
+\fBTcl_AppendExportList\fR retrieves the export patterns for a
+namespace given namespace and appends them (as list items) to
+\fIobjPtr\fR.
+.PP
+\fBTcl_Export\fR sets and appends to the export patterns for a
+namespace. Patterns are appended unless the \fIresetListFirst\fR flag
+is true.
+.PP
+\fBTcl_Import\fR imports commands matching a pattern into a
+namespace. Note that the pattern must include the name of the
+namespace to import from. This function returns an error if
+an attempt to import a command over an existing command is made,
+unless the \fIallowOverwrite\fR flag has been set.
+.PP
+\fBTcl_ForgetImport\fR removes imports matching a pattern.
+.PP
+\fBTcl_GetCurrentNamespace\fR returns the current namespace for an
+interpreter.
+.PP
+\fBTcl_GetGlobalNamespace\fR returns the global namespace for an
+interpreter.
+.PP
+\fBTcl_FindNamespace\fR searches for a namespace named \fIname\fR
+within the context of the namespace \fIcontextNsPtr\fR. If the
+namespace cannot be found, NULL is returned.
+.PP
+\fBTcl_FindCommand\fR searches for a command named \fIname\fR within
+the context of the namespace \fIcontextNsPtr\fR. If the command
+cannot be found, NULL is returned.
+.PP
+\fBTcl_GetNamespaceUnknownHandler\fR returns the unknown command handler
+for the namespace, or NULL if none is set.
+.PP
+\fBTcl_SetNamespaceUnknownHandler\fR sets the unknown command handler for
+the namespace. If \fIhandlerPtr\fR is NULL, then the handler is reset to
+its default.
+
+.SH "SEE ALSO"
+Tcl_CreateCommand, Tcl_ListObjAppendElements, Tcl_SetVar
+
+.SH KEYWORDS
+namespace, command
diff --git a/doc/Notifier.3 b/doc/Notifier.3
index bb2fef4..7858a8c 100644
--- a/doc/Notifier.3
+++ b/doc/Notifier.3
@@ -25,7 +25,6 @@ void
.sp
void
\fBTcl_QueueEvent\fR(\fIevPtr, position\fR)
-.VS 8.1
.sp
void
\fBTcl_ThreadQueueEvent\fR(\fIthreadId, evPtr, position\fR)
@@ -63,12 +62,16 @@ int
int
\fBTcl_GetServiceMode\fR()
.sp
-int
+int
\fBTcl_SetServiceMode\fR(\fImode\fR)
-.VE
-
+.sp
+void
+\fBTcl_ServiceModeHook\fR(\fImode\fR)
+.sp
+void
+\fBTcl_SetNotifier\fR(\fInotifierProcPtr\fR)
.SH ARGUMENTS
-.AS Tcl_EventDeleteProc milliseconds
+.AS Tcl_EventDeleteProc *notifierProcPtr
.AP Tcl_EventSetupProc *setupProc in
Procedure to invoke to prepare for event wait in \fBTcl_DoOneEvent\fR.
.AP Tcl_EventCheckProc *checkProc in
@@ -97,11 +100,13 @@ Procedure to invoke for each queued event in \fBTcl_DeleteEvents\fR.
.AP int flags in
What types of events to service. These flags are the same as those
passed to \fBTcl_DoOneEvent\fR.
-.VS 8.1
.AP int mode in
Indicates whether events should be serviced by \fBTcl_ServiceAll\fR.
Must be one of \fBTCL_SERVICE_NONE\fR or \fBTCL_SERVICE_ALL\fR.
-.VE
+.AP Tcl_NotifierProcs* notifierProcPtr in
+Structure of function pointers describing notifier procedures that are
+to replace the ones installed in the executable. See
+\fBREPLACING THE NOTIFIER\fR for details.
.BE
.SH INTRODUCTION
@@ -135,9 +140,7 @@ sources place events onto the queue so that they may be processed in
order at appropriate times during the event loop. The event queue
guarantees a fair discipline of event handling, so that no event
source can starve the others. It also allows events to be saved for
-servicing at a future time.
-.VS 8.1
-Threaded applications work in a
+servicing at a future time. Threaded applications work in a
similar manner, except that there is a separate event queue for
each thread containing a Tcl interpreter.
\fBTcl_QueueEvent\fR is used (primarily
@@ -169,7 +172,6 @@ The procedures \fBTcl_ServiceAll\fR, \fBTcl_ServiceEvent\fR,
to help connect Tcl's event loop to an external event loop such as
Motif's.
.SH "NOTIFIER BASICS"
-.VE
.PP
The easiest way to understand how the notifier works is to consider
what happens when \fBTcl_DoOneEvent\fR is called.
@@ -180,17 +182,13 @@ things:
.IP [1]
Check the event queue to see if it contains any events that can
be serviced. If so, service the first possible event, remove it
-.VS 8.1
from the queue, and return. It does this by calling
\fBTcl_ServiceEvent\fR and passing in the \fIflags\fR argument.
-.VE
.IP [2]
Prepare to block for an event. To do this, \fBTcl_DoOneEvent\fR
invokes a \fIsetup procedure\fR in each event source.
The event source will perform event-source specific initialization and
-.VS 8.1
possibly call \fBTcl_SetMaxBlockTime\fR to limit how long
-.VE
\fBTcl_WaitForEvent\fR will block if no new events occur.
.IP [3]
Call \fBTcl_WaitForEvent\fR. This procedure is implemented differently
@@ -233,8 +231,8 @@ the event source.
\fISetupProc\fR should match the following prototype:
.CS
typedef void Tcl_EventSetupProc(
- ClientData \fIclientData\fR,
- int \fIflags\fR);
+ ClientData \fIclientData\fR,
+ int \fIflags\fR);
.CE
The \fIclientData\fR argument will be the same as the \fIclientData\fR
argument to \fBTcl_CreateEventSource\fR; it is typically used to
@@ -243,7 +241,7 @@ The \fIflags\fR argument will be the same as the \fIflags\fR
argument passed to \fBTcl_DoOneEvent\fR except that it will never
be 0 (\fBTcl_DoOneEvent\fR replaces 0 with \fBTCL_ALL_EVENTS\fR).
\fIFlags\fR indicates what kinds of events should be considered;
-if the bit corresponding to this event source isn't set, the event
+if the bit corresponding to this event source is not set, the event
source should return immediately without doing anything. For
example, the file event source checks for the \fBTCL_FILE_EVENTS\fR
bit.
@@ -256,7 +254,6 @@ request notification with a Windows event. For timer-driven event
sources such as timer events or any polled event, the event source
can call \fBTcl_SetMaxBlockTime\fR to force the application to wake
up after a specified time even if no events have occurred.
-.VS 8.1
If no event source calls \fBTcl_SetMaxBlockTime\fR
then \fBTcl_WaitForEvent\fR will wait as long as necessary for an
event to occur; otherwise, it will only wait as long as the shortest
@@ -268,28 +265,24 @@ events already queued. If there are, it calls
\fBTcl_SetMaxBlockTime\fR with a 0 block time so that
\fBTcl_WaitForEvent\fR does not block if there is no new data on the X
connection.
-.VE
The \fItimePtr\fR argument to \fBTcl_WaitForEvent\fR points to
a structure that describes a time interval in seconds and
microseconds:
.CS
typedef struct Tcl_Time {
- long \fIsec\fR;
- long \fIusec\fR;
+ long \fIsec\fR;
+ long \fIusec\fR;
} Tcl_Time;
.CE
The \fIusec\fR field should be less than 1000000.
.PP
-.VS 8.1
Information provided to \fBTcl_SetMaxBlockTime\fR
is only used for the next call to \fBTcl_WaitForEvent\fR; it is
discarded after \fBTcl_WaitForEvent\fR returns.
-.VE
The next time an event wait is done each of the event sources'
setup procedures will be called again, and they can specify new
information for that event wait.
.PP
-.VS 8.1
If the application uses an external event loop rather than
\fBTcl_DoOneEvent\fR, the event sources may need to call
\fBTcl_SetMaxBlockTime\fR at other times. For example, if a new event
@@ -305,7 +298,6 @@ platform-specific procedures may also be available for
\fIsetupProc\fR, if there is additional information needed by
\fBTcl_WaitForEvent\fR on that platform. For example, on Unix systems
the \fBTcl_CreateFileHandler\fR interface can be used to wait for file events.
-.VE
.PP
The second procedure provided by each event source is its check
procedure, indicated by the \fIcheckProc\fR argument to
@@ -313,8 +305,8 @@ procedure, indicated by the \fIcheckProc\fR argument to
following prototype:
.CS
typedef void Tcl_EventCheckProc(
- ClientData \fIclientData\fR,
- int \fIflags\fR);
+ ClientData \fIclientData\fR,
+ int \fIflags\fR);
.CE
The arguments to this procedure are the same as those for \fIsetupProc\fR.
\fBCheckProc\fR is invoked by \fBTcl_DoOneEvent\fR after it has waited
@@ -363,24 +355,20 @@ events at the front of the queue, such as a series of
Enter and Leave events synthesized during a grab or ungrab operation
in Tk.
.PP
-.VS 8.1
When it is time to handle an event from the queue (steps 1 and 4
above) \fBTcl_ServiceEvent\fR will invoke the \fIproc\fR specified
-.VE
in the first queued \fBTcl_Event\fR structure.
\fIProc\fR must match the following prototype:
.CS
typedef int Tcl_EventProc(
- Tcl_Event *\fIevPtr\fR,
- int \fIflags\fR);
+ Tcl_Event *\fIevPtr\fR,
+ int \fIflags\fR);
.CE
The first argument to \fIproc\fR is a pointer to the event, which will
be the same as the first argument to the \fBTcl_QueueEvent\fR call that
added the event to the queue.
The second argument to \fIproc\fR is the \fIflags\fR argument for the
-.VS 8.1
current call to \fBTcl_ServiceEvent\fR; this is used by the event source
-.VE
to return immediately if its events are not relevant.
.PP
It is up to \fIproc\fR to handle the event, typically by invoking
@@ -389,20 +377,17 @@ Once the event source has finished handling the event it returns 1
to indicate that the event can be removed from the queue.
If for some reason the event source decides that the event cannot
be handled at this time, it may return 0 to indicate that the event
-.VS 8.1
should be deferred for processing later; in this case \fBTcl_ServiceEvent\fR
-.VE
will go on to the next event in the queue and attempt to service it.
There are several reasons why an event source might defer an event.
One possibility is that events of this type are excluded by the
\fIflags\fR argument.
For example, the file event source will always return 0 if the
-\fBTCL_FILE_EVENTS\fR bit isn't set in \fIflags\fR.
+\fBTCL_FILE_EVENTS\fR bit is not set in \fIflags\fR.
Another example of deferring events happens in Tk if
\fBTk_RestrictEvents\fR has been invoked to defer certain kinds
of window events.
.PP
-.VS 8.1
When \fIproc\fR returns 1, \fBTcl_ServiceEvent\fR will remove the
event from the event queue and free its storage.
Note that the storage for an event must be allocated by
@@ -422,8 +407,9 @@ Tcl_ThreadID for the current thread, use the \fBTcl_GetCurrentThread\fR
procedure. (A thread would then need to pass this identifier to other
threads for those threads to be able to add events to its queue.)
After adding an event to another thread's queue, you then typically
-need to call \fBTcl_ThreadAlert\fR to "wake up" that thread's notifier to
-alert it to the new event.
+need to call \fBTcl_ThreadAlert\fR to
+.QW "wake up"
+that thread's notifier to alert it to the new event.
.PP
\fBTcl_DeleteEvents\fR can be used to explicitly remove one or more
events from the event queue. \fBTcl_DeleteEvents\fR calls \fIproc\fR
@@ -432,8 +418,8 @@ returns 1. Events for which the procedure returns 0 are left in the
queue. \fIProc\fR should match the following prototype:
.CS
typedef int Tcl_EventDeleteProc(
- Tcl_Event *\fIevPtr\fR,
- ClientData \fIclientData\fR);
+ Tcl_Event *\fIevPtr\fR,
+ ClientData \fIclientData\fR);
.CE
The \fIclientData\fR argument will be the same as the \fIclientData\fR
argument to \fBTcl_DeleteEvents\fR; it is typically used to point to
@@ -444,23 +430,21 @@ point to the next event in the queue.
\fIcheckProc\fR, and \fIclientData\fR arguments must exactly match those
provided to the \fBTcl_CreateEventSource\fR for the event source to be deleted.
If no such source exists, \fBTcl_DeleteEventSource\fR has no effect.
-.VE
.SH "CREATING A NEW NOTIFIER"
.PP
The notifier consists of all the procedures described in this manual
entry, plus \fBTcl_DoOneEvent\fR and \fBTcl_Sleep\fR, which are
-.VS 8.1
available on all platforms, and \fBTcl_CreateFileHandler\fR and
\fBTcl_DeleteFileHandler\fR, which are Unix-specific. Most of these
procedures are generic, in that they are the same for all notifiers.
-However, eight of the procedures are notifier-dependent:
-\fBTcl_InitNotifier\fR, \fBTcl_AlertNotifier\fR, \fBTcl_FinalizeNotifier\fR,
-\fBTcl_SetTimer\fR, \fBTcl_Sleep\fR, \fBTcl_WaitForEvent\fR,
-\fBTcl_CreateFileHandler\fR and \fBTcl_DeleteFileHandler\fR. To
-support a new platform or to integrate Tcl with an
-application-specific event loop, you must write new versions of these
-procedures.
+However, none of the procedures are notifier-dependent:
+\fBTcl_InitNotifier\fR, \fBTcl_AlertNotifier\fR,
+\fBTcl_FinalizeNotifier\fR, \fBTcl_SetTimer\fR, \fBTcl_Sleep\fR,
+\fBTcl_WaitForEvent\fR, \fBTcl_CreateFileHandler\fR,
+\fBTcl_DeleteFileHandler\fR and \fBTcl_ServiceModeHook\fR. To support a
+new platform or to integrate Tcl with an application-specific event loop,
+you must write new versions of these procedures.
.PP
\fBTcl_InitNotifier\fR initializes the notifier state and returns
a handle to the notifier state. Tcl calls this
@@ -469,7 +453,9 @@ procedure when initializing a Tcl interpreter. Similarly,
called by \fBTcl_Finalize\fR when shutting down a Tcl interpreter.
.PP
\fBTcl_WaitForEvent\fR is the lowest-level procedure in the notifier;
-it is responsible for waiting for an ``interesting'' event to occur or
+it is responsible for waiting for an
+.QW interesting
+event to occur or
for a given time to elapse. Before \fBTcl_WaitForEvent\fR is invoked,
each of the event sources' setup procedure will have been invoked.
The \fItimePtr\fR argument to
@@ -483,13 +469,13 @@ to occur; it should not actually process the event in any way.
Later on, the
event sources will process the raw events and create Tcl_Events on
the event queue in their \fIcheckProc\fR procedures.
-However, on some platforms (such as Windows) this isn't possible;
+However, on some platforms (such as Windows) this is not possible;
events may be processed in \fBTcl_WaitForEvent\fR, including queuing
Tcl_Events and more (for example, callbacks for native widgets may be
invoked). The return value from \fBTcl_WaitForEvent\fR must be either
0, 1, or \-1. On platforms such as Windows where events get processed in
\fBTcl_WaitForEvent\fR, a return value of 1 means that there may be more
-events still pending that haven't been processed. This is a sign to the
+events still pending that have not been processed. This is a sign to the
caller that it must call \fBTcl_WaitForEvent\fR again if it wants all
pending events to be processed. A 0 return value means that calling
\fBTcl_WaitForEvent\fR again will not have any effect: either this is a
@@ -504,7 +490,9 @@ forever because there were no active event sources and the timeout was
infinite.
.PP
\fBTcl_AlertNotifier\fR is used in multithreaded applications to allow
-any thread to "wake up" the notifier to alert it to new events on its
+any thread to
+.QW "wake up"
+the notifier to alert it to new events on its
queue. \fBTcl_AlertNotifier\fR requires as an argument the notifier
handle returned by \fBTcl_InitNotifier\fR.
.PP
@@ -514,11 +502,18 @@ invoked by \fBTcl_SetMaxBlockTime\fR whenever the maximum blocking
time has been reduced. \fBTcl_SetTimer\fR should arrange for the
external event loop to invoke \fBTcl_ServiceAll\fR after the specified
interval even if no events have occurred. This interface is needed
-because \fBTcl_WaitForEvent\fR isn't invoked when there is an external
+because \fBTcl_WaitForEvent\fR is not invoked when there is an external
event loop. If the
notifier will only be used from \fBTcl_DoOneEvent\fR, then
\fBTcl_SetTimer\fR need not do anything.
.PP
+\fBTcl_ServiceModeHook\fR is called by the platform-independent portion
+of the notifier when client code makes a call to
+\fBTcl_SetServiceMode\fR. This hook is provided to support operating
+systems that require special event handling when the application is in
+a modal loop (the Windows notifier, for instance, uses this hook to
+create a communication window).
+.PP
On Unix systems, the file event source also needs support from the
notifier. The file event source consists of the
\fBTcl_CreateFileHandler\fR and \fBTcl_DeleteFileHandler\fR
@@ -532,6 +527,38 @@ The easiest way to create a new notifier is to look at the code
for an existing notifier, such as the files \fBunix/tclUnixNotfy.c\fR
or \fBwin/tclWinNotify.c\fR in the Tcl source distribution.
+.SH "REPLACING THE NOTIFIER"
+.PP
+A notifier that has been written according to the conventions above
+can also be installed in a running process in place of the standard
+notifier. This mechanism is used so that a single executable can be
+used (with the standard notifier) as a stand-alone program and reused
+(with a replacement notifier in a loadable extension) as an extension
+to another program, such as a Web browser plugin.
+.PP
+To do this, the extension makes a call to \fBTcl_SetNotifier\fR
+passing a pointer to a \fBTcl_NotifierProcs\fR data structure. The
+structure has the following layout:
+.CS
+typedef struct Tcl_NotifierProcs {
+ Tcl_SetTimerProc *setTimerProc;
+ Tcl_WaitForEventProc *waitForEventProc;
+ Tcl_CreateFileHandlerProc *createFileHandlerProc;
+ Tcl_DeleteFileHandlerProc *deleteFileHandlerProc;
+ Tcl_InitNotifierProc *initNotifierProc;
+ Tcl_FinalizeNotifierProc *finalizeNotifierProc;
+ Tcl_AlertNotifierProc *alertNotifierProc;
+ Tcl_ServiceModeHookProc *serviceModeHookProc;
+} Tcl_NotifierProcs;
+.CE
+Following the call to \fBTcl_SetNotifier\fR, the pointers given in
+the \fBTcl_NotifierProcs\fR structure replace whatever notifier had
+been installed in the process.
+.PP
+It is extraordinarily unwise to replace a running notifier. Normally,
+\fBTcl_SetNotifier\fR should be called at process initialization time
+before the first call to \fBTcl_InitNotifier\fR.
+
.SH "EXTERNAL EVENT LOOPS"
.PP
The notifier interfaces are designed so that Tcl can be embedded into
@@ -592,7 +619,7 @@ then calls to \fBTcl_ServiceAll\fR will behave normally.
mode, which should be restored when the recursive loop exits.
\fBTcl_GetServiceMode\fR returns the current value of the service
mode.
-.VE
+
.SH "SEE ALSO"
\fBTcl_CreateFileHandler\fR, \fBTcl_DeleteFileHandler\fR, \fBTcl_Sleep\fR,
\fBTcl_DoOneEvent\fR, \fBThread(3)\fR
diff --git a/doc/Object.3 b/doc/Object.3
index 4e8fa6f..4817b9b 100644
--- a/doc/Object.3
+++ b/doc/Object.3
@@ -5,7 +5,7 @@
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.so man.macros
-.TH Tcl_Obj 3 8.1 Tcl "Tcl Library Procedures"
+.TH Tcl_Obj 3 8.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_NewObj, Tcl_DuplicateObj, Tcl_IncrRefCount, Tcl_DecrRefCount, Tcl_IsShared, Tcl_InvalidateStringRep \- manipulate Tcl objects
@@ -28,7 +28,7 @@ int
.sp
\fBTcl_InvalidateStringRep\fR(\fIobjPtr\fR)
.SH ARGUMENTS
-.AS Tcl_Obj *objPtr in
+.AS Tcl_Obj *objPtr
.AP Tcl_Obj *objPtr in
Points to an object;
must have been the result of a previous call to \fBTcl_NewObj\fR.
@@ -100,34 +100,37 @@ reclaim an object's storage.
.PP
Tcl objects are typed.
An object's internal representation is controlled by its type.
-Seven types are predefined in the Tcl core
+Several types are predefined in the Tcl core
including integer, double, list, and bytecode.
Extension writers can extend the set of types
-by using the procedure \fBTcl_RegisterObjType\fR .
-
+by defining their own \fBTcl_ObjType\fR structs.
.SH "THE TCL_OBJ STRUCTURE"
.PP
Each Tcl object is represented by a \fBTcl_Obj\fR structure
which is defined as follows.
.CS
typedef struct Tcl_Obj {
- int \fIrefCount\fR;
- char *\fIbytes\fR;
- int \fIlength\fR;
- Tcl_ObjType *\fItypePtr\fR;
- union {
- long \fIlongValue\fR;
- double \fIdoubleValue\fR;
- VOID *\fIotherValuePtr\fR;
- struct {
- VOID *\fIptr1\fR;
- VOID *\fIptr2\fR;
- } \fItwoPtrValue\fR;
- } \fIinternalRep\fR;
+ int \fIrefCount\fR;
+ char *\fIbytes\fR;
+ int \fIlength\fR;
+ Tcl_ObjType *\fItypePtr\fR;
+ union {
+ long \fIlongValue\fR;
+ double \fIdoubleValue\fR;
+ void *\fIotherValuePtr\fR;
+ Tcl_WideInt \fIwideValue\fR;
+ struct {
+ void *\fIptr1\fR;
+ void *\fIptr2\fR;
+ } \fItwoPtrValue\fR;
+ struct {
+ void *\fIptr\fR;
+ unsigned long \fIvalue\fR;
+ } \fIptrAndLongRep\fR;
+ } \fIinternalRep\fR;
} Tcl_Obj;
.CE
The \fIbytes\fR and the \fIlength\fR members together hold
-.VS 8.1
an object's UTF-8 string representation,
which is a \fIcounted string\fR not containing null bytes (UTF-8 null
characters should be encoded as a two byte sequence: 192, 128.)
@@ -137,7 +140,6 @@ The byte array must always have a null byte after the last data byte,
at offset \fIlength\fR;
this allows string representations
to be treated as conventional null-terminated C strings.
-.VE 8.1
C programs use \fBTcl_GetStringFromObj\fR and \fBTcl_GetString\fR to get
an object's string representation.
If \fIbytes\fR is NULL,
@@ -151,10 +153,11 @@ the internal representation is invalid.
.PP
The \fIinternalRep\fR union member holds
an object's internal representation.
-This is either a (long) integer, a double-precision floating point number,
+This is either a (long) integer, a double-precision floating-point number,
a pointer to a value containing additional information
-needed by the object's type to represent the object,
-or two arbitrary pointers.
+needed by the object's type to represent the object, a Tcl_WideInt
+integer, two arbitrary pointers, or a pair made up of an unsigned long
+integer and a pointer.
.PP
The \fIrefCount\fR member is used to tell when it is safe to free
an object's storage.
@@ -224,7 +227,6 @@ creates a new internal representation for an object
and changes its \fItypePtr\fR.
See the man page for \fBTcl_RegisterObjType\fR
to see how to create a new object type.
-
.SH "EXAMPLE OF THE LIFETIME OF AN OBJECT"
.PP
As an example of the lifetime of an object,
@@ -262,9 +264,8 @@ no longer corresponds to the internal representation.
.CE
The string representation of \fIx\fR's object is needed
and is recomputed.
-The string representation is now \fB124\fR.
+The string representation is now \fB124\fR
and both representations are again valid.
-
.SH "STORAGE MANAGEMENT OF OBJECTS"
.PP
Tcl objects are allocated on the heap and are shared as much as possible
@@ -281,7 +282,7 @@ if the object's reference count drops to zero, frees its storage.
An object shared by different code or data structures has
\fIrefCount\fR greater than 1.
Incrementing an object's reference count ensures that
-it won't be freed too early or have its value change accidently.
+it will not be freed too early or have its value change accidentally.
.PP
As an example, the bytecode interpreter shares argument objects
between calling and called Tcl procedures to avoid having to copy objects.
@@ -297,7 +298,7 @@ When an object's reference count drops less than or equal to zero,
\fBTcl_DecrRefCount\fR reclaims its storage.
Most command procedures do not have to be concerned about
reference counting since they use an object's value immediately
-and don't retain a pointer to the object after they return.
+and do not retain a pointer to the object after they return.
However, if they do retain a pointer to an object in a data structure,
they must be careful to increment its reference count
since the retained pointer is a new reference.
@@ -312,26 +313,29 @@ by using \fBTcl_DuplicateObj\fR;
this returns a new duplicate of the original object
that has \fIrefCount\fR 0.
If the object is not shared,
-the command procedure "owns" the object and can safely modify it directly.
+the command procedure
+.QW "owns"
+the object and can safely modify it directly.
For example, the following code appears in the command procedure
that implements \fBlinsert\fR.
This procedure modifies the list object passed to it in \fIobjv[1]\fR
by inserting \fIobjc-3\fR new elements before \fIindex\fR.
+.PP
.CS
listPtr = objv[1];
if (Tcl_IsShared(listPtr)) {
- listPtr = Tcl_DuplicateObj(listPtr);
+ listPtr = Tcl_DuplicateObj(listPtr);
}
-result = Tcl_ListObjReplace(interp, listPtr, index, 0, (objc-3), &(objv[3]));
+result = Tcl_ListObjReplace(interp, listPtr, index, 0,
+ (objc-3), &(objv[3]));
.CE
+.PP
As another example, \fBincr\fR's command procedure
must check whether the variable's object is shared before
incrementing the integer in its internal representation.
If it is shared, it needs to duplicate the object
-in order to avoid accidently changing values in other data structures.
-
+in order to avoid accidentally changing values in other data structures.
.SH "SEE ALSO"
-Tcl_ConvertToType, Tcl_GetIntFromObj, Tcl_ListObjAppendElement, Tcl_ListObjIndex, Tcl_ListObjReplace, Tcl_RegisterObjType
-
+Tcl_ConvertToType(3), Tcl_GetIntFromObj(3), Tcl_ListObjAppendElement(3), Tcl_ListObjIndex(3), Tcl_ListObjReplace(3), Tcl_RegisterObjType(3)
.SH KEYWORDS
internal representation, object, object creation, object type, reference counting, string representation, type conversion
diff --git a/doc/ObjectType.3 b/doc/ObjectType.3
index cc84fd1..974ea6c 100644
--- a/doc/ObjectType.3
+++ b/doc/ObjectType.3
@@ -24,12 +24,12 @@ int
int
\fBTcl_ConvertToType\fR(\fIinterp, objPtr, typePtr\fR)
.SH ARGUMENTS
-.AS Tcl_ObjType *typeName in
+.AS "const char" *typeName
.AP Tcl_ObjType *typePtr in
Points to the structure containing information about the Tcl object type.
This storage must live forever,
typically by being statically allocated.
-.AP "CONST char" *typeName in
+.AP "const char" *typeName in
The name of a Tcl object type that \fBTcl_GetObjType\fR should look up.
.AP Tcl_Interp *interp in
Interpreter to use for error reporting.
@@ -43,12 +43,14 @@ must have been the result of a previous call to \fBTcl_NewObj\fR.
.SH DESCRIPTION
.PP
The procedures in this man page manage Tcl object types.
-The are used to register new object types,
-look up types,
+They are used to register new object types, look up types,
and force conversions from one type to another.
.PP
\fBTcl_RegisterObjType\fR registers a new Tcl object type
-in the table of all object types supported by Tcl.
+in the table of all object types that \fBTcl_GetObjType\fR
+can look up by name. There are other object types supported by Tcl
+as well, which Tcl chooses not to register. Extensions can likewise
+choose to register the object types they create or not.
The argument \fItypePtr\fR points to a Tcl_ObjType structure that
describes the new type by giving its name
and by supplying pointers to four procedures
@@ -59,11 +61,11 @@ it is replaced with the new type.
The Tcl_ObjType structure is described
in the section \fBTHE TCL_OBJTYPE STRUCTURE\fR below.
.PP
-\fBTcl_GetObjType\fR returns a pointer to the Tcl_ObjType
+\fBTcl_GetObjType\fR returns a pointer to the registered Tcl_ObjType
with name \fItypeName\fR.
It returns NULL if no type with that name is registered.
.PP
-\fBTcl_AppendAllObjTypes\fR appends the name of each object type
+\fBTcl_AppendAllObjTypes\fR appends the name of each registered object type
as a list element onto the Tcl object referenced by \fIobjPtr\fR.
The return value is \fBTCL_OK\fR unless there was an error
converting \fIobjPtr\fR to a list object;
@@ -73,7 +75,8 @@ in that case \fBTCL_ERROR\fR is returned.
if possible.
It creates a new internal representation for \fIobjPtr\fR
appropriate for the target type \fItypePtr\fR
-and sets its \fItypePtr\fR member to that type.
+and sets its \fItypePtr\fR member as determined by calling the
+\fItypePtr->setFromAnyProc\fR routine.
Any internal representation for \fIobjPtr\fR's old type is freed.
If an error occurs during conversion, it returns \fBTCL_ERROR\fR
and leaves an error message in the result object for \fIinterp\fR
@@ -81,118 +84,168 @@ unless \fIinterp\fR is NULL.
Otherwise, it returns \fBTCL_OK\fR.
Passing a NULL \fIinterp\fR allows this procedure to be used
as a test whether the conversion can be done (and in fact was done).
-
+.VS 8.5
+.PP
+In many cases, the \fItypePtr->setFromAnyProc\fR routine will
+set \fIobjPtr->typePtr\fR to the argument value \fItypePtr\fR,
+but that is no longer guaranteed. The \fIsetFromAnyProc\fR is
+free to set the internal representation for \fIobjPtr\fR to make
+use of another related Tcl_ObjType, if it sees fit.
+.VE 8.5
.SH "THE TCL_OBJTYPE STRUCTURE"
.PP
Extension writers can define new object types by defining four
-procedures,
-initializing a Tcl_ObjType structure to describe the type,
-and calling \fBTcl_RegisterObjType\fR.
+procedures and
+initializing a Tcl_ObjType structure to describe the type.
+Extension writers may also pass a pointer to their Tcl_ObjType
+structure to \fBTcl_RegisterObjType\fR if they wish to permit
+other extensions to look up their Tcl_ObjType by name with
+the \fBTcl_GetObjType\fR routine.
The \fBTcl_ObjType\fR structure is defined as follows:
+.PP
.CS
typedef struct Tcl_ObjType {
- char *\fIname\fR;
- Tcl_FreeInternalRepProc *\fIfreeIntRepProc\fR;
- Tcl_DupInternalRepProc *\fIdupIntRepProc\fR;
- Tcl_UpdateStringProc *\fIupdateStringProc\fR;
- Tcl_SetFromAnyProc *\fIsetFromAnyProc\fR;
+ char *\fIname\fR;
+ Tcl_FreeInternalRepProc *\fIfreeIntRepProc\fR;
+ Tcl_DupInternalRepProc *\fIdupIntRepProc\fR;
+ Tcl_UpdateStringProc *\fIupdateStringProc\fR;
+ Tcl_SetFromAnyProc *\fIsetFromAnyProc\fR;
} Tcl_ObjType;
.CE
+.SS "THE NAME FIELD"
.PP
The \fIname\fR member describes the name of the type, e.g. \fBint\fR.
-Extension writers can look up an object type using its name
-with the \fBTcl_GetObjType\fR procedure.
+When a type is registered, this is the name used by callers
+of \fBTcl_GetObjType\fR to lookup the type. For unregistered
+types, the \fIname\fR field is primarily of value for debugging.
The remaining four members are pointers to procedures
called by the generic Tcl object code:
+.SS "THE SETFROMANYPROC FIELD"
.PP
The \fIsetFromAnyProc\fR member contains the address of a function
called to create a valid internal representation
from an object's string representation.
+.PP
.CS
-typedef int (Tcl_SetFromAnyProc) (Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIobjPtr\fR);
+typedef int (Tcl_SetFromAnyProc) (Tcl_Interp *\fIinterp\fR,
+ Tcl_Obj *\fIobjPtr\fR);
.CE
-If an internal representation can't be created from the string,
+.PP
+If an internal representation cannot be created from the string,
it returns \fBTCL_ERROR\fR and puts a message
describing the error in the result object for \fIinterp\fR
unless \fIinterp\fR is NULL.
If \fIsetFromAnyProc\fR is successful,
it stores the new internal representation,
sets \fIobjPtr\fR's \fItypePtr\fR member to point to
-\fIsetFromAnyProc\fR's \fBTcl_ObjType\fR, and returns \fBTCL_OK\fR.
+the \fBTcl_ObjType\fR struct corresponding to the new
+internal representation, and returns \fBTCL_OK\fR.
Before setting the new internal representation,
the \fIsetFromAnyProc\fR must free any internal representation
of \fIobjPtr\fR's old type;
it does this by calling the old type's \fIfreeIntRepProc\fR
if it is not NULL.
-As an example, the \fIsetFromAnyProc\fR for the builtin Tcl integer type
+.PP
+As an example, the \fIsetFromAnyProc\fR for the built-in Tcl list type
gets an up-to-date string representation for \fIobjPtr\fR
by calling \fBTcl_GetStringFromObj\fR.
-It parses the string to obtain an integer and,
-if this succeeds,
-stores the integer in \fIobjPtr\fR's internal representation
-and sets \fIobjPtr\fR's \fItypePtr\fR member to point to the integer type's
+It parses the string to verify it is in a valid list format and
+to obtain each element value in the list, and, if this succeeds,
+stores the list elements in \fIobjPtr\fR's internal representation
+and sets \fIobjPtr\fR's \fItypePtr\fR member to point to the list type's
Tcl_ObjType structure.
+.PP
Do not release \fIobjPtr\fR's old internal representation unless you
replace it with a new one or reset the \fItypePtr\fR member to NULL.
.PP
+The \fIsetFromAnyProc\fR member may be set to NULL, if the routines
+making use of the internal representation have no need to derive that
+internal representation from an arbitrary string value. However, in
+this case, passing a pointer to the type to Tcl_ConvertToType() will
+lead to a panic, so to avoid this possibility, the type
+should \fInot\fR be registered.
+.SS "THE UPDATESTRINGPROC FIELD"
+.PP
The \fIupdateStringProc\fR member contains the address of a function
called to create a valid string representation
from an object's internal representation.
+.PP
.CS
typedef void (Tcl_UpdateStringProc) (Tcl_Obj *\fIobjPtr\fR);
.CE
+.PP
\fIobjPtr\fR's \fIbytes\fR member is always NULL when it is called.
It must always set \fIbytes\fR non-NULL before returning.
We require the string representation's byte array
-to have a null after the last byte, at offset \fIlength\fR;
-this allows string representations that do not contain null bytes
+to have a null after the last byte, at offset \fIlength\fR,
+and to have no null bytes before that; this allows string representations
to be treated as conventional null character-terminated C strings.
+These restrictions are easily met by using Tcl's internal UTF encoding
+for the string representation, same as one would do for other
+Tcl routines accepting string values as arguments.
Storage for the byte array must be allocated in the heap by \fBTcl_Alloc\fR
or \fBckalloc\fR. Note that \fIupdateStringProc\fRs must allocate
enough storage for the string's bytes and the terminating null byte.
-The \fIupdateStringProc\fR for Tcl's builtin list type, for example,
-builds an array of strings for each element object
-and then calls \fBTcl_Merge\fR
-to construct a string with proper Tcl list structure.
-It stores this string as the list object's string representation.
+.PP
+The \fIupdateStringProc\fR for Tcl's built-in double type, for example,
+calls Tcl_PrintDouble to write to a buffer of size TCL_DOUBLE_SPACE,
+then allocates and copies the string representation to just enough
+space to hold it. A pointer to the allocated space is stored in
+the \fIbytes\fR member.
+.PP
+The \fIupdateStringProc\fR member may be set to NULL, if the routines
+making use of the internal representation are written so that the
+string representation is never invalidated. Failure to meet this
+obligation will lead to panics or crashes when \fBTcl_GetStringFromObj\fR
+or other similar routines ask for the string representation.
+.SS "THE DUPINTREPPROC FIELD"
.PP
The \fIdupIntRepProc\fR member contains the address of a function
called to copy an internal representation from one object to another.
+.PP
.CS
-typedef void (Tcl_DupInternalRepProc) (Tcl_Obj *\fIsrcPtr\fR, Tcl_Obj *\fIdupPtr\fR);
+typedef void (Tcl_DupInternalRepProc) (Tcl_Obj *\fIsrcPtr\fR,
+ Tcl_Obj *\fIdupPtr\fR);
.CE
+.PP
\fIdupPtr\fR's internal representation is made a copy of \fIsrcPtr\fR's
internal representation.
Before the call,
\fIsrcPtr\fR's internal representation is valid and \fIdupPtr\fR's is not.
\fIsrcPtr\fR's object type determines what
copying its internal representation means.
+.PP
For example, the \fIdupIntRepProc\fR for the Tcl integer type
simply copies an integer.
-The builtin list type's \fIdupIntRepProc\fR
-allocates a new array that points at the original element objects;
-the elements are shared between the two lists
-(and their reference counts are incremented to reflect the new references).
+The built-in list type's \fIdupIntRepProc\fR uses a far more
+sophisticated scheme to continue sharing storage as much as it
+reasonably can.
+.SS "THE FREEINTREPPROC FIELD"
.PP
The \fIfreeIntRepProc\fR member contains the address of a function
that is called when an object is freed.
+.PP
.CS
typedef void (Tcl_FreeInternalRepProc) (Tcl_Obj *\fIobjPtr\fR);
.CE
+.PP
The \fIfreeIntRepProc\fR function can deallocate the storage
for the object's internal representation
and do other type-specific processing necessary when an object is freed.
-For example, Tcl list objects have an \fIinternalRep.otherValuePtr\fR
-that points to an array of pointers to each element in the list.
-The list type's \fIfreeIntRepProc\fR decrements
-the reference count for each element object
-(since the list will no longer refer to those objects),
-then deallocates the storage for the array of pointers.
+.PP
+For example, the list type's \fIfreeIntRepProc\fR respects
+the storage sharing scheme established by the \fIdupIntRepProc\fR
+so that it only frees storage when the last object sharing it
+is being freed.
+.PP
The \fIfreeIntRepProc\fR member can be set to NULL
to indicate that the internal representation does not require freeing.
-
+The \fIfreeIntRepProc\fR implementation must not access the
+\fIbytes\fR member of the object, since Tcl makes its own internal
+uses of that field during object deletion. The defined tasks for
+the \fIfreeIntRepProc\fR have no need to consult the \fIbytes\fR
+member.
.SH "SEE ALSO"
Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount
-
.SH KEYWORDS
internal representation, object, object type, string representation, type conversion
diff --git a/doc/OpenFileChnl.3 b/doc/OpenFileChnl.3
index 33c57fa..0d722f6 100644
--- a/doc/OpenFileChnl.3
+++ b/doc/OpenFileChnl.3
@@ -9,7 +9,7 @@
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
-Tcl_OpenFileChannel, Tcl_OpenCommandChannel, Tcl_MakeFileChannel, Tcl_GetChannel, Tcl_GetChannelNames, Tcl_GetChannelNamesEx, Tcl_RegisterChannel, Tcl_UnregisterChannel, Tcl_DetachChannel, Tcl_IsStandardChannel, Tcl_Close, Tcl_ReadChars, Tcl_Read, Tcl_GetsObj, Tcl_Gets, Tcl_WriteObj, Tcl_WriteChars, Tcl_Write, Tcl_Flush, Tcl_Seek, Tcl_Tell, Tcl_GetChannelOption, Tcl_SetChannelOption, Tcl_Eof, Tcl_InputBlocked, Tcl_InputBuffered, Tcl_OutputBuffered, Tcl_Ungets, Tcl_ReadRaw, Tcl_WriteRaw \- buffered I/O facilities using channels
+Tcl_OpenFileChannel, Tcl_OpenCommandChannel, Tcl_MakeFileChannel, Tcl_GetChannel, Tcl_GetChannelNames, Tcl_GetChannelNamesEx, Tcl_RegisterChannel, Tcl_UnregisterChannel, Tcl_DetachChannel, Tcl_IsStandardChannel, Tcl_Close, Tcl_ReadChars, Tcl_Read, Tcl_GetsObj, Tcl_Gets, Tcl_WriteObj, Tcl_WriteChars, Tcl_Write, Tcl_Flush, Tcl_Seek, Tcl_Tell, Tcl_TruncateChannel, Tcl_GetChannelOption, Tcl_SetChannelOption, Tcl_Eof, Tcl_InputBlocked, Tcl_InputBuffered, Tcl_OutputBuffered, Tcl_Ungets, Tcl_ReadRaw, Tcl_WriteRaw \- buffered I/O facilities using channels
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
@@ -25,14 +25,12 @@ Tcl_Channel
.sp
Tcl_Channel
\fBTcl_GetChannel\fR(\fIinterp, channelName, modePtr\fR)
-.VS 8.3
.sp
int
\fBTcl_GetChannelNames\fR(\fIinterp\fR)
.sp
int
\fBTcl_GetChannelNamesEx\fR(\fIinterp, pattern\fR)
-.VE
.sp
void
\fBTcl_RegisterChannel\fR(\fIinterp, channel\fR)
@@ -49,7 +47,6 @@ int
int
\fBTcl_Close\fR(\fIinterp, channel\fR)
.sp
-.VS 8.1
int
\fBTcl_ReadChars\fR(\fIchannel, readObjPtr, charsToRead, appendFlag\fR)
.sp
@@ -73,15 +70,12 @@ int
.sp
int
\fBTcl_Write\fR(\fIchannel, byteBuf, bytesToWrite\fR)
-.VE
-.VS 8.3.2
.sp
int
\fBTcl_ReadRaw\fR(\fIchannel, readBuf, bytesToRead\fR)
.sp
int
\fBTcl_WriteRaw\fR(\fIchannel, byteBuf, bytesToWrite\fR)
-.VE
.sp
int
\fBTcl_Eof\fR(\fIchannel\fR)
@@ -94,19 +88,20 @@ int
.sp
int
\fBTcl_InputBuffered\fR(\fIchannel\fR)
-.VS 8.4
.sp
int
\fBTcl_OutputBuffered\fR(\fIchannel\fR)
-.VE
.sp
-.VS 8.4
Tcl_WideInt
\fBTcl_Seek\fR(\fIchannel, offset, seekMode\fR)
.sp
Tcl_WideInt
\fBTcl_Tell\fR(\fIchannel\fR)
-.VE 8.4
+.sp
+.VS 8.5
+int
+\fBTcl_TruncateChannel\fR(\fIchannel, length\fR)
+.VE 8.5
.sp
int
\fBTcl_GetChannelOption\fR(\fIinterp, channel, optionName, optionValue\fR)
@@ -115,12 +110,12 @@ int
\fBTcl_SetChannelOption\fR(\fIinterp, channel, optionName, newValue\fR)
.sp
.SH ARGUMENTS
-.AS Tcl_ChannelType newClientProcPtr in
+.AS Tcl_DString *channelName in/out
.AP Tcl_Interp *interp in
Used for error reporting and to look up a channel registered in it.
-.AP "CONST char" *fileName in
+.AP "const char" *fileName in
The name of a local or network file.
-.AP "CONST char" *mode in
+.AP "const char" *mode in
Specifies how the file is to be accessed. May have any of the values
allowed for the \fImode\fR argument to the Tcl \fBopen\fR command.
.AP int permissions in
@@ -128,7 +123,7 @@ POSIX-style permission flags such as 0644. If a new file is created, these
permissions will be set on the created file.
.AP int argc in
The number of elements in \fIargv\fR.
-.AP "CONST char" **argv in
+.AP "const char" **argv in
Arguments for constructing a command pipeline. These values have the same
meaning as the non-switch arguments to the Tcl \fBexec\fR command.
.AP int flags in
@@ -147,20 +142,17 @@ file descriptor, for Windows it is a HANDLE.
.AP int readOrWrite in
OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR to indicate
what operations are valid on \fIhandle\fR.
-.AP "CONST char" *channelName in
+.AP "const char" *channelName in
The name of the channel.
.AP int *modePtr out
Points at an integer variable that will receive an OR-ed combination of
\fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR denoting whether the channel is
open for reading and writing.
-.VS 8.3
-.AP "CONST char" *pattern in
+.AP "const char" *pattern in
The pattern to match on, passed to Tcl_StringMatch, or NULL.
-.VE
.AP Tcl_Channel channel in
A Tcl channel for input or output. Must have been the return value
from a procedure such as \fBTcl_OpenFileChannel\fR.
-.VS 8.1 br
.AP Tcl_Obj *readObjPtr in/out
A pointer to a Tcl Object in which to store the characters read from the
channel.
@@ -184,25 +176,22 @@ object.
A pointer to a Tcl dynamic string in which to store the line read from the
channel. Must have been initialized by the caller. The line read will be
appended to any data already in the dynamic string.
-.VS 8.3
-.AP "CONST char" *input in
+.AP "const char" *input in
The input to add to a channel buffer.
.AP int inputLen in
Length of the input
.AP int addAtEnd in
Flag indicating whether the input should be added to the end or
beginning of the channel buffer.
-.VE
.AP Tcl_Obj *writeObjPtr in
A pointer to a Tcl Object whose contents will be output to the channel.
-.AP "CONST char" *charBuf in
+.AP "const char" *charBuf in
A buffer containing the characters to output to the channel.
-.AP "CONST char" *byteBuf in
+.AP "const char" *byteBuf in
A buffer containing the bytes to output to the channel.
.AP int bytesToWrite in
The number of bytes to consume from \fIcharBuf\fR or \fIbyteBuf\fR and
output to the channel.
-.VE
.AP Tcl_WideInt offset in
How far to move the access point in the channel at which the next input or
output operation will be applied, measured in bytes from the position
@@ -211,13 +200,15 @@ given by \fIseekMode\fR. May be either positive or negative.
Relative to which point to seek; used with \fIoffset\fR to calculate the new
access point for the channel. Legal values are \fBSEEK_SET\fR,
\fBSEEK_CUR\fR, and \fBSEEK_END\fR.
-.AP "CONST char" *optionName in
+.AP Tcl_WideInt length in
+The (non-negative) length to truncate the channel the channel to.
+.AP "const char" *optionName in
The name of an option applicable to this channel, such as \fB\-blocking\fR.
May have any of the values accepted by the \fBfconfigure\fR command.
.AP Tcl_DString *optionValue in
Where to store the value of an option or a list of all options and their
values. Must have been initialized by the caller.
-.AP "CONST char" *newValue in
+.AP "const char" *newValue in
New value for the option given by \fIoptionName\fR.
.BE
@@ -228,7 +219,7 @@ platform-independent mechanism for performing buffered input
and output operations on a variety of file, socket, and device
types.
The channel mechanism is extensible to new channel types, by
-providing a low level channel driver for the new type; the channel driver
+providing a low-level channel driver for the new type; the channel driver
interface is described in the manual entry for \fBTcl_CreateChannel\fR. The
channel mechanism provides a buffering scheme modeled after
Unix's standard I/O, and it also allows for nonblocking I/O on
@@ -255,8 +246,6 @@ leaves an error message in \fIinterp\fR's result after any error.
As of Tcl 8.4, the object-based API \fBTcl_FSOpenFileChannel\fR should
be used in preference to \fBTcl_OpenFileChannel\fR wherever possible.
.PP
-
-.PP
The newly created channel is not registered in the supplied interpreter; to
register it, use \fBTcl_RegisterChannel\fR, described below.
If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
@@ -349,7 +338,7 @@ reference to a channel that is also registered in a Tcl interpreter.
.PP
This procedure interacts with the code managing the standard
channels. If no standard channels were initialized before the first
-call to \fBTcl_RegisterChannel\fR they will get initialized by that
+call to \fBTcl_RegisterChannel\fR, they will get initialized by that
call. See \fBTcl_StandardChannels\fR for a general treatise about
standard channels and the behaviour of the Tcl library with regard to
them.
@@ -376,7 +365,7 @@ accessible in \fIinterp\fR. After this call, Tcl programs will no longer be
able to use the channel's name to refer to the channel in that interpreter.
Beyond that, this command has no further effect. It cannot be used on
the standard channels (stdout, stderr, stdin), and will return
-TCL_ERROR if passed one of those channels.
+\fBTCL_ERROR\fR if passed one of those channels.
.PP
Code not associated with a Tcl interpreter can call
\fBTcl_DetachChannel\fR with \fIinterp\fR as NULL, to indicate to Tcl
@@ -423,7 +412,6 @@ been given as the \fBchan\fR argument in a call to
when all calls to \fBTcl_RegisterChannel\fR have been matched by
corresponding calls to \fBTcl_UnregisterChannel\fR.
-.VS 8.1 br
.SH "TCL_READCHARS AND TCL_READ"
.PP
\fBTcl_ReadChars\fR consumes bytes from \fIchannel\fR, converting the bytes
@@ -434,7 +422,7 @@ that were stored in \fIreadObjPtr\fR. If an error occurs while reading, the
return value is \-1 and \fBTcl_ReadChars\fR records a POSIX error code that
can be retrieved with \fBTcl_GetErrno\fR.
.PP
-Setting \fIcharsToRead\fR to \fB-1\fR will cause the command to read
+Setting \fIcharsToRead\fR to \fB\-1\fR will cause the command to read
all characters currently available (non-blocking) or everything until
eof (blocking mode).
.PP
@@ -467,7 +455,7 @@ from a channel, manipulated by calling \fBTcl_GetByteArrayFromObj\fR and
related functions, and then written to a channel without the expense of ever
converting to or from UTF-8.
.PP
-\fBTcl_Read\fR is similar to \fBTcl_ReadChars\fR, except that it doesn't do
+\fBTcl_Read\fR is similar to \fBTcl_ReadChars\fR, except that it does not do
encoding conversions, regardless of the channel's encoding. It is deprecated
and exists for backwards compatibility with non-internationalized Tcl
extensions. It consumes bytes from \fIchannel\fR and stores them in
@@ -519,9 +507,11 @@ at either the head or tail of the queue. The pointer \fIinput\fR points
to the data that is to be added. The length of the input to add is given
by \fIinputLen\fR. A non-zero value of \fIaddAtEnd\fR indicates that the
data is to be added at the end of queue; otherwise it will be added at the
-head of the queue. If \fIchannel\fR has a "sticky" EOF set, no data will be
+head of the queue. If \fIchannel\fR has a
+.QW sticky
+EOF set, no data will be
added to the input queue. \fBTcl_Ungets\fR returns \fIinputLen\fR or
--1 if an error occurs.
+\-1 if an error occurs.
.SH "TCL_WRITECHARS, TCL_WRITEOBJ, AND TCL_WRITE"
.PP
@@ -561,7 +551,7 @@ byte-oriented data can be read from a channel, manipulated by calling
\fBTcl_GetByteArrayFromObj\fR and related functions, and then written to a
channel without the expense of ever converting to or from UTF-8.
.PP
-\fBTcl_Write\fR is similar to \fBTcl_WriteChars\fR except that it doesn't do
+\fBTcl_Write\fR is similar to \fBTcl_WriteChars\fR except that it does not do
encoding conversions, regardless of the channel's encoding. It is
deprecated and exists for backwards compatibility with non-internationalized
Tcl extensions. It accepts \fIbytesToWrite\fR bytes of data at
@@ -577,7 +567,6 @@ not. Thus this function is \fBonly\fR usable for transformational
channel drivers, i.e. drivers used in the middle of a stack of
channels, to move data from the transformation into the channel below
it.
-.VE
.SH TCL_FLUSH
.PP
@@ -609,6 +598,14 @@ After an error, the access point may or may not have been moved.
\fBTcl_Tell\fR returns the current access point for a channel. The returned
value is \-1 if the channel does not support seeking.
+.SH TCL_TRUNCATECHANNEL
+.PP
+.VS 8.5
+\fBTcl_TruncateChannel\fR truncates the file underlying \fIchannel\fR
+to a given \fIlength\fR of bytes. It returns \fBTCL_OK\fR if the
+operation succeeded, and \fBTCL_ERROR\fR otherwise.
+.VE 8.5
+
.SH TCL_GETCHANNELOPTION
.PP
\fBTcl_GetChannelOption\fR retrieves, in \fIoptionValue\fR, the value of one of
@@ -658,11 +655,9 @@ buffered in the internal buffers for a channel. If the channel is not open
for reading, this function always returns zero.
.SH TCL_OUTPUTBUFFERED
-.VS 8.4
\fBTcl_OutputBuffered\fR returns the number of bytes of output
currently buffered in the internal buffers for a channel. If the
channel is not open for writing, this function always returns zero.
-.VE
.SH "PLATFORM ISSUES"
.PP
@@ -673,7 +668,7 @@ call. On Windows platforms, the handle is a file \fBHANDLE\fR when
the channel was created with \fBTcl_OpenFileChannel\fR,
\fBTcl_OpenCommandChannel\fR, or \fBTcl_MakeFileChannel\fR. Other
channel types may return a different type of handle on Windows
-platforms.
+platforms.
.SH "SEE ALSO"
DString(3), fconfigure(n), filename(n), fopen(3), Tcl_CreateChannel(3)
diff --git a/doc/OpenTcp.3 b/doc/OpenTcp.3
index df14f44..98d8cb0 100644
--- a/doc/OpenTcp.3
+++ b/doc/OpenTcp.3
@@ -24,18 +24,18 @@ Tcl_Channel
\fBTcl_OpenTcpServer\fR(\fIinterp, port, myaddr, proc, clientData\fR)
.sp
.SH ARGUMENTS
-.AS Tcl_ChannelType newClientProcPtr in
+.AS Tcl_TcpAcceptProc clientData
.AP Tcl_Interp *interp in
Tcl interpreter to use for error reporting. If non-NULL and an
error occurs, an error message is left in the interpreter's result.
.AP int port in
A port number to connect to as a client or to listen on as a server.
-.AP "CONST char" *host in
+.AP "const char" *host in
A string specifying a host name or address for the remote end of the connection.
.AP int myport in
A port number for the client's end of the socket. If 0, a port number
is allocated at random.
-.AP "CONST char" *myaddr in
+.AP "const char" *myaddr in
A string specifying the host name or address for network interface to use
for the local end of the connection. If NULL, a default interface is
chosen.
@@ -113,24 +113,24 @@ replacement for the standard channel.
.PP
\fBTcl_OpenTcpServer\fR opens a TCP socket on the local host on a specified
\fIport\fR and uses the Tcl event mechanism to accept requests from clients
-to connect to it. The \fImyaddr\fP argument specifies the network interface.
-If \fImyaddr\fP is NULL the special address INADDR_ANY should be used to
+to connect to it. The \fImyaddr\fR argument specifies the network interface.
+If \fImyaddr\fR is NULL the special address INADDR_ANY should be used to
allow connections from any network interface.
Each time a client connects to this socket, Tcl creates a channel
for the new connection and invokes \fIproc\fR with information about
-the channel. \fIProc\fR must match the following prototype:
+the channel. \fIProc\fR must match the following prototype:
.CS
typedef void Tcl_TcpAcceptProc(
- ClientData \fIclientData\fR,
- Tcl_Channel \fIchannel\fR,
- char *\fIhostName\fR,
- int \fIport\fP);
+ ClientData \fIclientData\fR,
+ Tcl_Channel \fIchannel\fR,
+ char *\fIhostName\fR,
+ int \fIport\fR);
.CE
.PP
The \fIclientData\fR argument will be the same as the \fIclientData\fR
argument to \fBTcl_OpenTcpServer\fR, \fIchannel\fR will be the handle
for the new channel, \fIhostName\fR points to a string containing
-the name of the client host making the connection, and \fIport\fP
+the name of the client host making the connection, and \fIport\fR
will contain the client's port number.
The new channel
is opened for both input and output.
@@ -162,13 +162,11 @@ If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
previously closed, the act of creating the new channel also assigns it as a
replacement for the standard channel.
-.VS
.SH "PLATFORM ISSUES"
.PP
On Unix platforms, the socket handle is a Unix file descriptor as
returned by the \fBsocket\fR system call. On the Windows platform, the
socket handle is a \fBSOCKET\fR as defined in the WinSock API.
-.VE
.SH "SEE ALSO"
Tcl_OpenFileChannel(3), Tcl_RegisterChannel(3), vwait(n)
diff --git a/doc/Panic.3 b/doc/Panic.3
index 3fb0c83..b53ca11 100644
--- a/doc/Panic.3
+++ b/doc/Panic.3
@@ -7,7 +7,7 @@
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
-Tcl_Panic, Tcl_PanicVA, Tcl_SetPanicProc, panic, panicVA \- report fatal error and abort
+Tcl_Panic, Tcl_PanicVA, Tcl_SetPanicProc \- report fatal error and abort
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
@@ -21,21 +21,15 @@ void
void
\fBTcl_SetPanicProc\fR(\fIpanicProc\fR)
.sp
-void
-\fBpanic\fR(\fIformat\fR, \fIarg\fR, \fIarg\fR, \fI...\fR)
-.sp
-void
-\fBpanicVA\fR(\fIformat\fR, \fIargList\fR)
-.sp
.SH ARGUMENTS
.AS Tcl_PanicProc *panicProc
-.AP "CONST char*" format in
+.AP "const char*" format in
A printf-style format string.
.AP "" arg in
Arguments matching the format string.
.AP va_list argList in
An argument list of arguments matching the format string.
-Must have been initialized using \fBTCL_VARARGS_START\fR,
+Must have been initialized using \fBva_start\fR,
and cleared using \fBva_end\fR.
.AP Tcl_PanicProc *panicProc in
Procedure to report fatal error message and abort.
@@ -51,7 +45,7 @@ to display a message describing the error and abort the process. The
\fIformat\fR argument is a format string describing how to format the
remaining arguments \fIarg\fR into an error message, according to the
same formatting rules used by the \fBprintf\fR family of functions. The
-same formatting rules are also used by the builtin Tcl command
+same formatting rules are also used by the built-in Tcl command
\fBformat\fR.
.PP
In a freshly loaded Tcl library, \fBTcl_Panic\fR prints the formatted
@@ -65,8 +59,8 @@ type \fBTcl_PanicProc\fR:
.PP
.CS
typedef void Tcl_PanicProc(
- CONST char *\fBformat\fR,
- \fBarg\fR, \fBarg\fR,...);
+ const char *\fBformat\fR,
+ \fBarg\fR, \fBarg\fR,...);
.CE
.PP
After \fBTcl_SetPanicProc\fR returns, any future calls to
@@ -92,11 +86,7 @@ have a panic message displayed the same way that panic messages from Tcl
will be displayed.
.PP
\fBTcl_PanicVA\fR is the same as \fBTcl_Panic\fR except that instead of
-taking a variable number of arguments it takes an argument list. The
-procedures \fBpanic\fR and \fBpanicVA\fR are synonyms (implemented as
-macros) for \fBTcl_Panic\fR and \fBTcl_PanicVA\fR, respectively. They
-exist to support old code; new code should use direct calls to
-\fBTcl_Panic\fR or \fBTcl_PanicVA\fR.
+taking a variable number of arguments it takes an argument list.
.SH "SEE ALSO"
abort(3), printf(3), exec(n), format(n)
diff --git a/doc/ParseCmd.3 b/doc/ParseCmd.3
index af6b02e..b5fc6d0 100644
--- a/doc/ParseCmd.3
+++ b/doc/ParseCmd.3
@@ -14,22 +14,22 @@ Tcl_ParseCommand, Tcl_ParseExpr, Tcl_ParseBraces, Tcl_ParseQuotedString, Tcl_Par
\fB#include <tcl.h>\fR
.sp
int
-\fBTcl_ParseCommand\fR(\fIinterp, string, numBytes, nested, parsePtr\fR)
+\fBTcl_ParseCommand\fR(\fIinterp, start, numBytes, nested, parsePtr\fR)
.sp
int
-\fBTcl_ParseExpr\fR(\fIinterp, string, numBytes, parsePtr\fR)
+\fBTcl_ParseExpr\fR(\fIinterp, start, numBytes, parsePtr\fR)
.sp
int
-\fBTcl_ParseBraces\fR(\fIinterp, string, numBytes, parsePtr, append, termPtr\fR)
+\fBTcl_ParseBraces\fR(\fIinterp, start, numBytes, parsePtr, append, termPtr\fR)
.sp
int
-\fBTcl_ParseQuotedString\fR(\fIinterp, string, numBytes, parsePtr, append, termPtr\fR)
+\fBTcl_ParseQuotedString\fR(\fIinterp, start, numBytes, parsePtr, append, termPtr\fR)
.sp
int
-\fBTcl_ParseVarName\fR(\fIinterp, string, numBytes, parsePtr, append\fR)
+\fBTcl_ParseVarName\fR(\fIinterp, start, numBytes, parsePtr, append\fR)
.sp
-CONST char *
-\fBTcl_ParseVar\fR(\fIinterp, string, termPtr\fR)
+const char *
+\fBTcl_ParseVar\fR(\fIinterp, start, termPtr\fR)
.sp
\fBTcl_FreeParse\fR(\fIusedParsePtr\fR)
.sp
@@ -39,7 +39,7 @@ Tcl_Obj *
int
\fBTcl_EvalTokensStandard\fR(\fIinterp, tokenPtr, numTokens\fR)
.SH ARGUMENTS
-.AS Tcl_Interp *usedParsePtr
+.AS Tcl_Interp *usedParsePtr out
.AP Tcl_Interp *interp out
For procedures other than \fBTcl_FreeParse\fR, \fBTcl_EvalTokens\fR
and \fBTcl_EvalTokensStandard\fR, used only for error reporting;
@@ -47,12 +47,12 @@ if NULL, then no error messages are left after errors.
For \fBTcl_EvalTokens\fR and \fBTcl_EvalTokensStandard\fR,
determines the context for evaluating the
script and also is used for error reporting; must not be NULL.
-.AP "CONST char" *string in
+.AP "const char" *start in
Pointer to first character in string to parse.
.AP int numBytes in
-Number of bytes in \fIstring\fR, not including any terminating null
+Number of bytes in string to parse, not including any terminating null
character. If less than 0 then the script consists of all characters
-in \fIstring\fR up to the first null character.
+following \fIstart\fR up to the first null character.
.AP int nested in
Non-zero means that the script is part of a command substitution so an
unquoted close bracket should be treated as a command terminator. If zero,
@@ -69,7 +69,7 @@ Any previous information in this structure
is ignored, unless \fIappend\fR is non-zero in a call to
\fBTcl_ParseBraces\fR, \fBTcl_ParseQuotedString\fR,
or \fBTcl_ParseVarName\fR.
-.AP "CONST char" **termPtr out
+.AP "const char" **termPtr out
If not NULL, points to a location where
\fBTcl_ParseBraces\fR, \fBTcl_ParseQuotedString\fR, and
\fBTcl_ParseVar\fR will store a pointer to the character
@@ -90,7 +90,7 @@ and fills in the structure pointed to by \fIparsePtr\fR
with a collection of tokens describing the information that was parsed.
The procedures normally return \fBTCL_OK\fR.
However, if an error occurs then they return \fBTCL_ERROR\fR,
-leave an error message in \fIinterp's\fR result
+leave an error message in \fIinterp\fR's result
(if \fIinterp\fR is not NULL),
and leave nothing in \fIparsePtr\fR.
.PP
@@ -117,9 +117,9 @@ result, and no information is left at \fI*parsePtr\fR.
.PP
\fBTcl_ParseBraces\fR parses a string or command argument
enclosed in braces such as
-\fB{hello}\fR or \fB{string \\t with \\t tabs}\fR
-from the beginning of its argument \fIstring\fR.
-The first character of \fIstring\fR must be \fB{\fR.
+\fB{hello}\fR or \fB{string \et with \et tabs}\fR
+from the beginning of its argument \fIstart\fR.
+The first character of \fIstart\fR must be \fB{\fR.
If the braced string was parsed successfully,
\fBTcl_ParseBraces\fR returns \fBTCL_OK\fR,
fills in the structure pointed to by \fIparsePtr\fR
@@ -133,15 +133,15 @@ an error message is left in \fIinterp\fR's result,
and no information is left at \fI*parsePtr\fR or \fI*termPtr\fR.
.PP
\fBTcl_ParseQuotedString\fR parses a double-quoted string such as
-\fB"sum is [expr $a+$b]"\fR
-from the beginning of the argument \fIstring\fR.
-The first character of \fIstring\fR must be \fB"\fR.
+\fB"sum is [expr {$a+$b}]"\fR
+from the beginning of the argument \fIstart\fR.
+The first character of \fIstart\fR must be \fB\N'34'\fR.
If the double-quoted string was parsed successfully,
\fBTcl_ParseQuotedString\fR returns \fBTCL_OK\fR,
fills in the structure pointed to by \fIparsePtr\fR
with information about the structure of the string
(see below for details),
-and stores a pointer to the character just after the terminating \fB"\fR
+and stores a pointer to the character just after the terminating \fB\N'34'\fR
in the location given by \fI*termPtr\fR.
If an error occurs while parsing the string
then \fBTCL_ERROR\fR is returned,
@@ -149,20 +149,20 @@ an error message is left in \fIinterp\fR's result,
and no information is left at \fI*parsePtr\fR or \fI*termPtr\fR.
.PP
\fBTcl_ParseVarName\fR parses a Tcl variable reference such as
-\fB$abc\fR or \fB$x([expr $index + 1])\fR from the beginning of its
-\fIstring\fR argument.
-The first character of \fIstring\fR must be \fB$\fR.
+\fB$abc\fR or \fB$x([expr {$index + 1}])\fR from the beginning of its
+\fIstart\fR argument.
+The first character of \fIstart\fR must be \fB$\fR.
If a variable name was parsed successfully, \fBTcl_ParseVarName\fR
returns \fBTCL_OK\fR and fills in the structure pointed to by
\fIparsePtr\fR with information about the structure of the variable name
(see below for details). If an error
occurs while parsing the command then \fBTCL_ERROR\fR is returned, an
-error message is left in \fIinterp\fR's result (if \fIinterp\fR isn't
+error message is left in \fIinterp\fR's result (if \fIinterp\fR is not
NULL), and no information is left at \fI*parsePtr\fR.
.PP
\fBTcl_ParseVar\fR parse a Tcl variable reference such as \fB$abc\fR
-or \fB$x([expr $index + 1])\fR from the beginning of its \fIstring\fR
-argument. The first character of \fIstring\fR must be \fB$\fR. If
+or \fB$x([expr {$index + 1}])\fR from the beginning of its \fIstart\fR
+argument. The first character of \fIstart\fR must be \fB$\fR. If
the variable name is parsed successfully, \fBTcl_ParseVar\fR returns a
pointer to the string value of the variable. If an error occurs while
parsing, then NULL is returned and an error message is left in
@@ -210,21 +210,21 @@ of \fBTcl_EvalTokens\fR is deprecated.
return parse information in two data structures, Tcl_Parse and Tcl_Token:
.CS
typedef struct Tcl_Parse {
- CONST char *\fIcommentStart\fR;
- int \fIcommentSize\fR;
- CONST char *\fIcommandStart\fR;
- int \fIcommandSize\fR;
- int \fInumWords\fR;
- Tcl_Token *\fItokenPtr\fR;
- int \fInumTokens\fR;
- ...
+ const char *\fIcommentStart\fR;
+ int \fIcommentSize\fR;
+ const char *\fIcommandStart\fR;
+ int \fIcommandSize\fR;
+ int \fInumWords\fR;
+ Tcl_Token *\fItokenPtr\fR;
+ int \fInumTokens\fR;
+ ...
} Tcl_Parse;
typedef struct Tcl_Token {
- int \fItype\fR;
- CONST char *\fIstart\fR;
- int \fIsize\fR;
- int \fInumComponents\fR;
+ int \fItype\fR;
+ const char *\fIstart\fR;
+ int \fIsize\fR;
+ int \fInumComponents\fR;
} Tcl_Token;
.CE
.PP
@@ -285,6 +285,16 @@ This token has the same meaning as \fBTCL_TOKEN_WORD\fR, except that
the word is guaranteed to consist of a single \fBTCL_TOKEN_TEXT\fR
sub-token. The \fInumComponents\fR field is always 1.
.TP
+\fBTCL_TOKEN_EXPAND_WORD\fR
+.VS 8.5
+This token has the same meaning as \fBTCL_TOKEN_WORD\fR, except that
+the command parser notes this word began with the expansion
+prefix \fB{*}\fR, indicating that after substitution,
+the list value of this word should be expanded to form multiple
+arguments in command evaluation. This
+token type can only be created by Tcl_ParseCommand.
+.VE 8.5
+.TP
\fBTCL_TOKEN_TEXT\fR
The token describes a range of literal text that is part of a word.
The \fInumComponents\fR field is always 0.
@@ -294,7 +304,7 @@ The token describes a backslash sequence such as \fB\en\fR or \fB\e0xa3\fR.
The \fInumComponents\fR field is always 0.
.TP
\fBTCL_TOKEN_COMMAND\fR
-The token describes a command whose result result must be substituted into
+The token describes a command whose result must be substituted into
the word. The token includes the square brackets that surround the
command. The \fInumComponents\fR field is always 0 (the nested command
is not parsed; call \fBTcl_ParseCommand\fR recursively if you want to
@@ -344,7 +354,7 @@ this includes the sub-tokens for any nested \fBTCL_TOKEN_SUB_EXPR\fR tokens.
\fBTCL_TOKEN_OPERATOR\fR
The token describes one operator of an expression
such as \fB&&\fR or \fBhypot\fR.
-An \fBTCL_TOKEN_OPERATOR\fR token is always preceded by a
+A \fBTCL_TOKEN_OPERATOR\fR token is always preceded by a
\fBTCL_TOKEN_SUB_EXPR\fR token
that describes the operator and its operands;
the \fBTCL_TOKEN_SUB_EXPR\fR token's \fInumComponents\fR field
@@ -352,7 +362,7 @@ can be used to determine the number of operands.
A binary operator such as \fB*\fR
is followed by two \fBTCL_TOKEN_SUB_EXPR\fR tokens
that describe its operands.
-A unary operator like \fB-\fR
+A unary operator like \fB\-\fR
is followed by a single \fBTCL_TOKEN_SUB_EXPR\fR token
for its operand.
If the operator is a math function such as \fBlog10\fR,
@@ -373,12 +383,16 @@ is always 0.
After \fBTcl_ParseCommand\fR returns, the first token pointed to by
the \fItokenPtr\fR field of the
Tcl_Parse structure always has type \fBTCL_TOKEN_WORD\fR or
-\fBTCL_TOKEN_SIMPLE_WORD\fR. It is followed by the sub-tokens
+.VS 8.5
+\fBTCL_TOKEN_SIMPLE_WORD\fR or \fBTCL_TOKEN_EXPAND_WORD\fR.
+It is followed by the sub-tokens
that must be concatenated to produce the value of that word.
The next token is the \fBTCL_TOKEN_WORD\fR or \fBTCL_TOKEN_SIMPLE_WORD\fR
-token for the second word, followed by sub-tokens for that
+of \fBTCL_TOKEN_EXPAND_WORD\fR token for the second word,
+followed by sub-tokens for that
word, and so on until all \fInumWords\fR have been accounted
for.
+.VE 8.5
.PP
After \fBTcl_ParseExpr\fR returns, the first token pointed to by
the \fItokenPtr\fR field of the
@@ -415,7 +429,7 @@ Tcl_Parse structure depends on the contents of the quoted string.
It will consist of one or more \fBTCL_TOKEN_TEXT\fR, \fBTCL_TOKEN_BS\fR,
\fBTCL_TOKEN_COMMAND\fR, and \fBTCL_TOKEN_VARIABLE\fR sub-tokens.
The array always contains at least one token;
-for example, if the argument \fIstring\fR is empty,
+for example, if the argument \fIstart\fR is empty,
the array returned consists of a single \fBTCL_TOKEN_TEXT\fR token
with a zero \fIsize\fR field.
Only the token information in the Tcl_Parse structure
@@ -436,7 +450,7 @@ the \fIcommentStart\fR, \fIcommentSize\fR,
.PP
All of the character pointers in the
Tcl_Parse and Tcl_Token structures refer
-to characters in the \fIstring\fR argument passed to
+to characters in the \fIstart\fR argument passed to
\fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR,
\fBTcl_ParseQuotedString\fR, and \fBTcl_ParseVarName\fR.
.PP
diff --git a/doc/PkgRequire.3 b/doc/PkgRequire.3
index fcccd58..810947d 100644
--- a/doc/PkgRequire.3
+++ b/doc/PkgRequire.3
@@ -8,21 +8,24 @@
.TH Tcl_PkgRequire 3 7.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
-Tcl_PkgRequire, Tcl_PkgRequireEx, Tcl_PkgPresent, Tcl_PkgPresentEx, Tcl_PkgProvide, Tcl_PkgProvideEx \- package version control
+Tcl_PkgRequire, Tcl_PkgRequireEx, Tcl_PkgRequireProc, Tcl_PkgPresent, Tcl_PkgPresentEx, Tcl_PkgProvide, Tcl_PkgProvideEx \- package version control
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
-CONST char *
+const char *
\fBTcl_PkgRequire\fR(\fIinterp, name, version, exact\fR)
.sp
-CONST char *
+const char *
\fBTcl_PkgRequireEx\fR(\fIinterp, name, version, exact, clientDataPtr\fR)
.sp
-CONST char *
+int
+\fBTcl_PkgRequireProc\fR(\fIinterp, name, objc, objv, clientDataPtr\fR)
+.sp
+const char *
\fBTcl_PkgPresent\fR(\fIinterp, name, version, exact\fR)
.sp
-CONST char *
+const char *
\fBTcl_PkgPresentEx\fR(\fIinterp, name, version, exact, clientDataPtr\fR)
.sp
int
@@ -31,12 +34,12 @@ int
int
\fBTcl_PkgProvideEx\fR(\fIinterp, name, version, clientData\fR)
.SH ARGUMENTS
-.AS ClientData clientDataPtr
+.AS ClientData clientDataPtr out
.AP Tcl_Interp *interp in
Interpreter where package is needed or available.
-.AP "CONST char" *name in
+.AP "const char" *name in
Name of package.
-.AP "CONST char" *version in
+.AP "const char" *version in
A version string consisting of one or more decimal numbers
separated by dots.
.AP int exact in
@@ -51,7 +54,12 @@ Arbitrary value to be associated with the package.
Pointer to place to store the value associated with the matching
package. It is only changed if the pointer is not NULL and the
function completed successfully.
+.AP int objc in
+Number of requirements.
+.AP Tcl_Obj* objv[] in
+Array of requirements.
.BE
+
.SH DESCRIPTION
.PP
These procedures provide C-level interfaces to Tcl's package and
@@ -71,13 +79,18 @@ that is provided in the interpreter (which may be different than
\fIversion\fR); if an error occurs they return NULL and leave an error
message in the interpreter's result.
.PP
-\fBTcl_PkgProvide\fR returns TCL_OK if it completes successfully;
-if an error occurs it returns TCL_ERROR and leaves an error message
+\fBTcl_PkgProvide\fR returns \fBTCL_OK\fR if it completes successfully;
+if an error occurs it returns \fBTCL_ERROR\fR and leaves an error message
in the interpreter's result.
.PP
\fBTcl_PkgProvideEx\fR, \fBTcl_PkgPresentEx\fR and \fBTcl_PkgRequireEx\fR
allow the setting and retrieving of the client data associated with
the package. In all other respects they are equivalent to the matching
functions.
+.PP
+\fBTcl_PkgRequireProc\fR is the form of \fBpackage require\fR handling
+multiple requirements. The other forms are present for backward
+compatibility and translate their invocations to this form.
+
.SH KEYWORDS
package, present, provide, require, version
diff --git a/doc/Preserve.3 b/doc/Preserve.3
index b5d608e..2b3edc0 100644
--- a/doc/Preserve.3
+++ b/doc/Preserve.3
@@ -9,7 +9,7 @@
.TH Tcl_Preserve 3 7.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
-Tcl_Preserve, Tcl_Release, Tcl_EventuallyFree \- avoid freeing storage while it's being used
+Tcl_Preserve, Tcl_Release, Tcl_EventuallyFree \- avoid freeing storage while it is being used
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
@@ -36,7 +36,7 @@ having to do with widget deletion, but are also useful in many other
situations. When a widget is deleted, its
widget record (the structure holding information specific to the
widget) must be returned to the storage allocator.
-However, it's possible that the widget record is in active use
+However, it is possible that the widget record is in active use
by one of the procedures on the stack at the time of the deletion.
This can happen, for example, if the command associated with a button
widget causes the button to be destroyed: an X event causes an
diff --git a/doc/PrintDbl.3 b/doc/PrintDbl.3
index 75e7663..279b4d5 100644
--- a/doc/PrintDbl.3
+++ b/doc/PrintDbl.3
@@ -16,19 +16,17 @@ Tcl_PrintDouble \- Convert floating value to string
.sp
\fBTcl_PrintDouble\fR(\fIinterp, value, dst\fR)
.SH ARGUMENTS
-.AS Tcl_Interp *interp
+.AS Tcl_Interp *interp out
.AP Tcl_Interp *interp in
-.VS
Before Tcl 8.0, the \fBtcl_precision\fR variable in this interpreter
controlled the conversion. As of Tcl 8.0, this argument is ignored and
the conversion is controlled by the \fBtcl_precision\fR variable
that is now shared by all interpreters.
-.VE
.AP double value in
Floating-point value to be converted.
.AP char *dst out
-Where to store string representing \fIvalue\fR. Must have at
-least TCL_DOUBLE_SPACE characters of storage.
+Where to store the string representing \fIvalue\fR. Must have at
+least \fBTCL_DOUBLE_SPACE\fR characters of storage.
.BE
.SH DESCRIPTION
@@ -36,10 +34,22 @@ least TCL_DOUBLE_SPACE characters of storage.
\fBTcl_PrintDouble\fR generates a string that represents the value
of \fIvalue\fR and stores it in memory at the location given by
\fIdst\fR. It uses \fB%g\fR format to generate the string, with one
-special twist: the string is guaranteed to contain either
-a ``.'' or an ``e'' so that it doesn't look like an integer. Where
-\fB%g\fR would generate an integer with no decimal point, \fBTcl_PrintDouble\fR
-adds ``.0''.
+special twist: the string is guaranteed to contain either a
+.QW .
+or an
+.QW e
+so that it does not look like an integer. Where \fB%g\fR would
+generate an integer with no decimal point, \fBTcl_PrintDouble\fR adds
+.QW .0 .
+.VS 8.5
+.PP
+If the \fBtcl_precision\fR value is non-zero, the result will have
+precisely that many digits of significance. If the value is zero
+(the default), the result will have the fewest digits needed to
+represent the number in such a way that \fBTcl_NewDoubleObj\fR
+will generate the same number when presented with the given string.
+IEEE semantics of rounding to even apply to the conversion.
+.VE
.SH KEYWORDS
conversion, double-precision, floating-point, string
diff --git a/doc/RecEvalObj.3 b/doc/RecEvalObj.3
index 25982c8..2eed471 100644
--- a/doc/RecEvalObj.3
+++ b/doc/RecEvalObj.3
@@ -16,15 +16,15 @@ Tcl_RecordAndEvalObj \- save command on history list before evaluating
int
\fBTcl_RecordAndEvalObj\fR(\fIinterp, cmdPtr, flags\fR)
.SH ARGUMENTS
-.AS Tcl_Interp *interp;
+.AS Tcl_Interp *interp
.AP Tcl_Interp *interp in
Tcl interpreter in which to evaluate command.
.AP Tcl_Obj *cmdPtr in
Points to a Tcl object containing a command (or sequence of commands)
to execute.
.AP int flags in
-An OR'ed combination of flag bits. TCL_NO_EVAL means record the
-command but don't evaluate it. TCL_EVAL_GLOBAL means evaluate
+An OR'ed combination of flag bits. \fBTCL_NO_EVAL\fR means record the
+command but do not evaluate it. \fBTCL_EVAL_GLOBAL\fR means evaluate
the command at global level instead of the current stack level.
.BE
@@ -32,18 +32,18 @@ the command at global level instead of the current stack level.
.PP
\fBTcl_RecordAndEvalObj\fR is invoked to record a command as an event
on the history list and then execute it using \fBTcl_EvalObjEx\fR
-(or \fBTcl_GlobalEvalObj\fR if the TCL_EVAL_GLOBAL bit is set
+(or \fBTcl_GlobalEvalObj\fR if the \fBTCL_EVAL_GLOBAL\fR bit is set
in \fIflags\fR).
-It returns a completion code such as TCL_OK just like \fBTcl_EvalObjEx\fR,
+It returns a completion code such as \fBTCL_OK\fR 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
+If you do not want the command recorded on the history list then
you should invoke \fBTcl_EvalObjEx\fR instead of \fBTcl_RecordAndEvalObj\fR.
Normally \fBTcl_RecordAndEvalObj\fR is only called with top-level
commands typed by the user, since the purpose of history is to
-allow the user to re-issue recently-invoked commands.
-If the \fIflags\fR argument contains the TCL_NO_EVAL bit then
+allow the user to re-issue recently invoked commands.
+If the \fIflags\fR argument contains the \fBTCL_NO_EVAL\fR bit then
the command is recorded without being evaluated.
.SH "SEE ALSO"
diff --git a/doc/RecordEval.3 b/doc/RecordEval.3
index 4ca030d..a8f3087 100644
--- a/doc/RecordEval.3
+++ b/doc/RecordEval.3
@@ -17,14 +17,14 @@ Tcl_RecordAndEval \- save command on history list before evaluating
int
\fBTcl_RecordAndEval\fR(\fIinterp, cmd, flags\fR)
.SH ARGUMENTS
-.AS Tcl_Interp *interp;
+.AS Tcl_Interp *interp
.AP Tcl_Interp *interp in
Tcl interpreter in which to evaluate command.
-.AP "CONST char" *cmd in
+.AP "const char" *cmd in
Command (or sequence of commands) to execute.
.AP int flags in
-An OR'ed combination of flag bits. TCL_NO_EVAL means record the
-command but don't evaluate it. TCL_EVAL_GLOBAL means evaluate
+An OR'ed combination of flag bits. \fBTCL_NO_EVAL\fR means record the
+command but do not evaluate it. \fBTCL_EVAL_GLOBAL\fR means evaluate
the command at global level instead of the current stack level.
.BE
@@ -32,15 +32,15 @@ the command at global level instead of the current stack level.
.PP
\fBTcl_RecordAndEval\fR is invoked to record a command as an event
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
+(or \fBTcl_GlobalEval\fR if the \fBTCL_EVAL_GLOBAL\fR bit is set in \fIflags\fR).
+It returns a completion code such as \fBTCL_OK\fR just like \fBTcl_Eval\fR
and it leaves information in the interpreter's result.
-If you don't want the command recorded on the history list then
+If you do not 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
commands typed by the user, since the purpose of history is to
allow the user to re-issue recently-invoked commands.
-If the \fIflags\fR argument contains the TCL_NO_EVAL bit then
+If the \fIflags\fR argument contains the \fBTCL_NO_EVAL\fR bit then
the command is recorded without being evaluated.
.PP
Note that \fBTcl_RecordAndEval\fR has been largely replaced by the
diff --git a/doc/RegConfig.3 b/doc/RegConfig.3
new file mode 100644
index 0000000..19c0bb0
--- /dev/null
+++ b/doc/RegConfig.3
@@ -0,0 +1,112 @@
+'\"
+'\" Copyright (c) 2002 Andreas Kupries <andreas_kupries@users.sourceforge.net>
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.so man.macros
+.TH Tcl_RegisterConfig 3 8.4 Tcl "Tcl Library Procedures"
+.BS
+'\" Note: do not modify the .SH NAME line immediately below!
+.SH NAME
+Tcl_RegisterConfig \- procedures to register embedded configuration information
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+void
+\fBTcl_RegisterConfig\fR(\fIinterp, pkgName, configuration, valEncoding\fR)
+.sp
+.SH ARGUMENTS
+.AS Tcl_Interp *configuration
+.AP Tcl_Interp *interp in
+Refers to the interpreter the embedded configuration information is
+registered for. Must not be NULL.
+.AP "const char" *pkgName in
+Contains the name of the package registering the embedded
+configuration as ASCII string. This means that this information is in
+UTF-8 too. Must not be NULL.
+.AP Tcl_Config *configuration in
+Refers to an array of Tcl_Config entries containing the information
+embedded in the binary library. Must not be NULL. The end of the array
+is signaled by either a key identical to NULL, or a key referring to
+the empty string.
+.AP "const char" *valEncoding in
+Contains the name of the encoding used to store the configuration
+values as ASCII string. This means that this information is in UTF-8
+too. Must not be NULL.
+.BE
+
+.SH DESCRIPTION
+.PP
+The function described here has its base in TIP 59 and provides
+extensions with support for the embedding of configuration
+information into their binary library and the generation of a
+Tcl-level interface for querying this information.
+.PP
+To embed configuration information into their binary library an
+extension has to define a non-volatile array of Tcl_Config entries in
+one if its source files and then call \fBTcl_RegisterConfig\fR to
+register that information.
+.PP
+\fBTcl_RegisterConfig\fR takes four arguments; first, a reference to
+the interpreter we are registering the information with, second, the
+name of the package registering its configuration information, third,
+a pointer to an array of structures, and fourth a string declaring the
+encoding used by the configuration values.
+.PP
+The string \fIvalEncoding\fR contains the name of an encoding known to
+Tcl. All these names are use only characters in the ASCII subset of
+UTF-8 and are thus implicitly in the UTF-8 encoding. It is expected
+that keys are legible English text and therefore using the ASCII
+subset of UTF-8. In other words, they are expected to be in UTF-8
+too. The values associated with the keys can be any string
+however. For these the contents of \fIvalEncoding\fR define which
+encoding was used to represent the characters of the strings.
+.PP
+Each element of the \fIconfiguration\fR array refers to two strings
+containing the key and the value associated with that key. The end of
+the array is signaled by either an empty key or a key identical to
+NULL. The function makes \fBno\fR copy of the \fIconfiguration\fR
+array. This means that the caller has to make sure that the memory
+holding this array is never released. This is the meaning behind the
+word \fBnon-volatile\fR used earlier. The easiest way to accomplish
+this is to define a global static array of Tcl_Config entries. See the file
+.QW generic/tclPkgConfig.c
+in the sources of the Tcl core for an example.
+.PP
+When called \fBTcl_RegisterConfig\fR will
+.IP (1)
+create a namespace having the provided \fIpkgName\fR, if not yet
+existing.
+.IP (2)
+create the command \fBpkgconfig\fR in that namespace and link it to
+the provided information so that the keys from _configuration_ and
+their associated values can be retrieved through calls to
+\fBpkgconfig\fR.
+.PP
+The command \fBpkgconfig\fR will provide two subcommands, \fBlist\fR
+and \fBget\fR:
+.RS
+.TP
+::\fIpkgName\fR::\fBpkgconfig\fR list
+Returns a list containing the names of all defined keys.
+.TP
+::\fIpkgName\fR::\fBpkgconfig\fR get \fIkey\fR
+Returns the configuration value associated with the specified
+\fIkey\fR.
+.RE
+.SH TCL_CONFIG
+.PP
+The \fBTcl_Config\fR structure contains the following fields:
+.PP
+.CS
+typedef struct Tcl_Config {
+ const char* key;
+ const char* value;
+} Tcl_Config;
+.CE
+.\" No cross references yet.
+.\" .SH "SEE ALSO"
+.SH KEYWORDS
+embedding, configuration, binary library
diff --git a/doc/RegExp.3 b/doc/RegExp.3
index d2163f2..0ac091c 100644
--- a/doc/RegExp.3
+++ b/doc/RegExp.3
@@ -16,93 +16,88 @@ Tcl_RegExpMatch, Tcl_RegExpCompile, Tcl_RegExpExec, Tcl_RegExpRange, Tcl_GetRegE
\fB#include <tcl.h>\fR
.sp
int
-\fBTcl_RegExpMatchObj\fR(\fIinterp\fR, \fIstrObj\fR, \fIpatObj\fR)
+\fBTcl_RegExpMatchObj\fR(\fIinterp\fR, \fItextObj\fR, \fIpatObj\fR)
.sp
int
-\fBTcl_RegExpMatch\fR(\fIinterp\fR, \fIstring\fR, \fIpattern\fR)
+\fBTcl_RegExpMatch\fR(\fIinterp\fR, \fItext\fR, \fIpattern\fR)
.sp
Tcl_RegExp
\fBTcl_RegExpCompile\fR(\fIinterp\fR, \fIpattern\fR)
.sp
int
-\fBTcl_RegExpExec\fR(\fIinterp\fR, \fIregexp\fR, \fIstring\fR, \fIstart\fR)
+\fBTcl_RegExpExec\fR(\fIinterp\fR, \fIregexp\fR, \fItext\fR, \fIstart\fR)
.sp
+void
\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)
+\fBTcl_RegExpExecObj\fR(\fIinterp\fR, \fIregexp\fR, \fItextObj\fR, \fIoffset\fR, \fInmatches\fR, \fIeflags\fR)
.sp
+void
\fBTcl_RegExpGetInfo\fR(\fIregexp\fR, \fIinfoPtr\fR)
-.VE 8.1
-
+.fi
.SH ARGUMENTS
-.AS Tcl_Interp *interp
+.AS Tcl_RegExpInfo *interp in/out
.AP Tcl_Interp *interp in
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
+.AP Tcl_Obj *textObj in/out
+Refers to the object from which to get the text 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 "CONST char" *pattern in
+.AP char *text in
+Text to search for a match with a regular expression.
+.AP "const 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_GetRegExpFromObj\fR or \fBTcl_RegExpCompile\fR.
.AP char *start in
-If \fIstring\fR is just a portion of some other string, this argument
+If \fItext\fR is just a portion of some other string, this argument
identifies the beginning of the larger string.
-If it isn't the same as \fIstring\fR, then no \fB^\fR matches
-will be allowed.
+If it is not the same as \fItext\fR, then no
+.QW \fB^\fR
+matches will be allowed.
.AP int index in
Specifies which range is desired: 0 means the range of the entire
match, 1 or greater means the range that matched a parenthesized
sub-expression.
-.VS 8.4
-.AP "CONST char" **startPtr out
+.AP "const char" **startPtr out
The address of the first character in the range is stored here, or
NULL if there is no such range.
-.AP "CONST char" **endPtr out
+.AP "const 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.
-.VE 8.4
-.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.
+OR-ed combination of the compilation flags \fBTCL_REG_ADVANCED\fR,
+\fBTCL_REG_EXTENDED\fR, \fBTCL_REG_BASIC\fR, \fBTCL_REG_EXPANDED\fR,
+\fBTCL_REG_QUOTE\fR, \fBTCL_REG_NOCASE\fR, \fBTCL_REG_NEWLINE\fR,
+\fBTCL_REG_NLSTOP\fR, \fBTCL_REG_NLANCH\fR, \fBTCL_REG_NOSUB\fR, and
+\fBTCL_REG_CANMATCH\fR. See below for more information.
.AP int offset in
-The character offset into the string where matching should begin.
+The character offset into the text 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
+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.
+OR-ed combination of the execution flags \fBTCL_REG_NOTBOL\fR and
+\fBTCL_REG_NOTEOL\fR. 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
@@ -114,13 +109,11 @@ 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 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
+operates on the Tcl objects \fItextObj\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.
@@ -136,7 +129,7 @@ up to the next call to \fBTcl_RegExpCompile\fR; it is not safe to
retain these values for long periods of time.
.PP
\fBTcl_RegExpExec\fR executes the regular expression pattern matcher.
-It returns 1 if \fIstring\fR contains a range of characters that
+It returns 1 if \fItext\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
@@ -145,14 +138,16 @@ 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.
For example, when searching for the second occurrence of a
-match, the \fIstring\fR argument might point to the character
+match, the \fItext\fR argument might point to the character
just after the first match; however, it is important for the
pattern matcher to know that this is not the start of the entire string,
-so that it doesn't allow \fB^\fR atoms in the pattern to match.
+so that it does not allow
+.QW \fB^\fR
+atoms in the pattern to match.
The \fIstart\fR argument provides this information by pointing
-to the start of the overall string containing \fIstring\fR.
-\fIStart\fR will be less than or equal to \fIstring\fR; if it
-is less than \fIstring\fR then no \fB^\fR matches will be allowed.
+to the start of the overall string containing \fItext\fR.
+\fIStart\fR will be less than or equal to \fItext\fR; if it
+is less than \fItext\fR then no \fB^\fR matches will be allowed.
.PP
\fBTcl_RegExpRange\fR may be invoked after \fBTcl_RegExpExec\fR
returns; it provides detailed information about what ranges of
@@ -168,7 +163,6 @@ information is returned about the range of characters that matched the
If there is no range corresponding to \fIindex\fR then NULL
is stored in \fI*startPtr\fR and \fI*endPtr\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
@@ -190,23 +184,29 @@ 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
+compiled form. The \fIcflags\fR argument is a bit-wise 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.
+Compile advanced regular expressions
+.PQ ARE s .
+This mode corresponds to
+the normal regular expression syntax accepted by the Tcl \fBregexp\fR and
+\fBregsub\fR commands.
.TP
\fBTCL_REG_EXTENDED\fR
-Compile extended regular expressions (`EREs'). This mode corresponds
+Compile extended regular expressions
+.PQ ERE s .
+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
+Compile basic regular expressions
+.PQ BRE s .
+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.
@@ -226,26 +226,54 @@ Compile for matching that ignores upper/lower case distinctions.
\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
+regular expressions or strings. With this flag,
+.QW [^
+bracket expressions and
+.QW .
+never match newline,
+.QW ^
+matches an empty string
+after any newline in addition to its normal function, and
+.QW $
+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_NEWLINE\fR is the bit-wise 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.
+.QW [^
+bracket expressions and
+.QW .
+affected, but not the behavior of
+.QW ^
+and
+.QW $ .
+In this mode,
+.QW [^
+bracket expressions and
+.QW .
+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
+.QW ^
+and
+.QW $
+(the
+.QW anchors )
+affected, but not the behavior of
+.QW [^
+bracket expressions and
+.QW . .
+In this mode
+.QW ^
+matches an empty string
+after any newline in addition to its normal function, and
+.QW $
+matches
an empty string before any newline in addition to its normal function.
.TP
\fBTCL_REG_NOSUB\fR
@@ -273,25 +301,33 @@ 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
+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
+controlled by the \fIeflags\fR argument, which is a bit-wise 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.
+line or the beginning of the string, so
+.QW ^
+will not match there.
+Note that this flag has no effect on how
+.QW \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.
+line or the end of the string, so
+.QW $
+will not match there.
+Note that this flag has no effect on how
+.QW \fB\eZ\fR
+matches.
.RE
.PP
\fBTcl_RegExpGetInfo\fR retrieves information about the last match
@@ -301,16 +337,16 @@ defined as follows:
.PP
.CS
typedef struct Tcl_RegExpInfo {
- int \fInsubs\fR;
- Tcl_RegExpIndices *\fImatches\fR;
- long \fIextendStart\fR;
+ 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
+points to an array of \fInsubs\fR+1 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
@@ -319,8 +355,8 @@ follows:
.PP
.CS
typedef struct Tcl_RegExpIndices {
- long \fIstart\fR;
- long \fIend\fR;
+ long \fIstart\fR;
+ long \fIend\fR;
} Tcl_RegExpIndices;
.CE
.PP
@@ -331,7 +367,7 @@ 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.
+\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
@@ -340,8 +376,7 @@ 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. If it
is no match is possible even with further text, this field will be set
-to -1.
-.VE 8.1
+to \-1.
.SH "SEE ALSO"
re_syntax(n)
.SH KEYWORDS
diff --git a/doc/SaveResult.3 b/doc/SaveResult.3
index 8eb9b46..f47500e 100644
--- a/doc/SaveResult.3
+++ b/doc/SaveResult.3
@@ -1,5 +1,6 @@
'\"
'\" Copyright (c) 1997 by Sun Microsystems, Inc.
+'\" Contributions from Don Porter, NIST, 2004. (not subject to US copyright)
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
@@ -8,35 +9,95 @@
.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
+Tcl_SaveInterpState, Tcl_RestoreInterpState, Tcl_DiscardInterpState, Tcl_SaveResult, Tcl_RestoreResult, Tcl_DiscardResult \- save and restore an interpreter's state
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
-\fBTcl_SaveResult(\fIinterp, statePtr\fB)\fR
+Tcl_InterpState
+\fBTcl_SaveInterpState\fR(\fIinterp, status\fR)
.sp
-\fBTcl_RestoreResult(\fIinterp, statePtr\fB)\fR
+int
+\fBTcl_RestoreInterpState\fR(\fIinterp, state\fR)
.sp
-\fBTcl_DiscardResult(\fIstatePtr\fB)\fR
+\fBTcl_DiscardInterpState\fR(\fIstate\fR)
+.sp
+\fBTcl_SaveResult\fR(\fIinterp, savedPtr\fR)
+.sp
+\fBTcl_RestoreResult\fR(\fIinterp, savedPtr\fR)
+.sp
+\fBTcl_DiscardResult\fR(\fIsavedPtr\fR)
.SH ARGUMENTS
-.AS Tcl_SavedResult statePtr
+.AS Tcl_InterpState savedPtr
.AP Tcl_Interp *interp in
Interpreter for which state should be saved.
-.AP Tcl_SavedResult *statePtr in
+.AP int status in
+Return code value to save as part of interpreter state.
+.AP Tcl_InterpState state in
+Saved state token to be restored or discarded.
+.AP Tcl_SavedResult *savedPtr in
Pointer to location where interpreter result should be saved or restored.
.BE
.SH DESCRIPTION
.PP
+.VS 8.5
These routines allows a C procedure to take a snapshot of the current
-interpreter result so that it can be restored after a call
+state of an interpreter 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
+state. There are two triplets of routines meant to work together.
+.PP
+The first triplet stores the snapshot of interpreter state in
+an opaque token returned by \fBTcl_SaveInterpState\fR. That token
+value may then be passed back to one of \fBTcl_RestoreInterpState\fR
+or \fBTcl_DiscardInterpState\fR, depending on whether the interp
+state is to be restored. So long as one of the latter two routines
+is called, Tcl will take care of memory management.
+.PP
+The second triplet stores the snapshot of only the interpreter
+result (not its complete state) in memory allocated by the caller.
+These routines are passed a pointer to a \fBTcl_SavedResult\fR structure
+that is used to store enough information to restore the interpreter result.
+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).
+information in the interpreter (e.g. the \fB\-errorcode\fR or
+\fB\-errorinfo\fR return options, when an error is in progress).
+.PP
+Because the routines \fBTcl_SaveInterpState\fR,
+\fBTcl_RestoreInterpState\fR, and \fBTcl_DiscardInterpState\fR perform
+a superset of the functions provided by the other routines,
+any new code should only make use of the more powerful routines.
+The older, weaker routines \fBTcl_SaveResult\fR, \fBTcl_RestoreResult\fR,
+and \fBTcl_DiscardResult\fR continue to exist only for the sake
+of existing programs that may already be using them.
+.PP
+\fBTcl_SaveInterpState\fR takes a snapshot of those portions of
+interpreter state that make up the full result of script evaluation.
+This include the interpreter result, the return code (passed in
+as the \fIstatus\fR argument, and any return options, including
+\fB\-errorinfo\fR and \fB\-errorcode\fR when an error is in progress.
+This snapshot is returned as an opaque token of type \fBTcl_InterpState\fR.
+The call to \fBTcl_SaveInterpState\fR does not itself change the
+state of the interpreter. Unlike \fBTcl_SaveResult\fR, it does
+not reset the interpreter.
+.PP
+\fBTcl_RestoreInterpState\fR accepts a \fBTcl_InterpState\fR token
+previously returned by \fBTcl_SaveInterpState\fR and restores the
+state of the interp to the state held in that snapshot. The return
+value of \fBTcl_RestoreInterpState\fR is the status value originally
+passed to \fBTcl_SaveInterpState\fR when the snapshot token was
+created.
+.PP
+\fBTcl_DiscardInterpState\fR is called to release a \fBTcl_InterpState\fR
+token previously returned by \fBTcl_SaveInterpState\fR when that
+snapshot is not to be restored to an interp.
+.PP
+The \fBTcl_InterpState\fR token returned by \fBTcl_SaveInterpState\fR
+must eventually be passed to either \fBTcl_RestoreInterpState\fR
+or \fBTcl_DiscardInterpState\fR to avoid a memory leak. Once
+the \fBTcl_InterpState\fR token is passed to one of them, the
+token is no longer valid and should not be used anymore.
+.VE 8.5
.PP
\fBTcl_SaveResult\fR moves the string and object results
of \fIinterp\fR into the location specified by \fIstatePtr\fR.
diff --git a/doc/SetChanErr.3 b/doc/SetChanErr.3
new file mode 100644
index 0000000..13bd94a
--- /dev/null
+++ b/doc/SetChanErr.3
@@ -0,0 +1,153 @@
+'\"
+'\" Copyright (c) 2005 Andreas Kupries <andreas_kupries@users.sourceforge.net>
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.so man.macros
+.TH Tcl_SetChannelError 3 8.5 Tcl "Tcl Library Procedures"
+.BS
+'\" Note: do not modify the .SH NAME line immediately below!
+.SH NAME
+Tcl_SetChannelError, Tcl_SetChannelErrorInterp, Tcl_GetChannelError, Tcl_GetChannelErrorInterp \- functions to create/intercept Tcl errors by channel drivers.
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+void
+\fBTcl_SetChannelError\fR(\fIchan, msg\fR)
+.sp
+void
+\fBTcl_SetChannelErrorInterp\fR(\fIinterp, msg\fR)
+.sp
+void
+\fBTcl_GetChannelError\fR(\fIchan, msgPtr\fR)
+.sp
+void
+\fBTcl_GetChannelErrorInterp\fR(\fIinterp, msgPtr\fR)
+.sp
+.SH ARGUMENTS
+.AS Tcl_Channel chan
+.AP Tcl_Channel chan in
+Refers to the Tcl channel whose bypass area is accessed.
+.AP Tcl_Interp* interp in
+Refers to the Tcl interpreter whose bypass area is accessed.
+.AP Tcl_Obj* msg in
+Error message put into a bypass area. A list of return options and
+values, followed by a string message. Both message and the
+option/value information are optional.
+.AP Tcl_Obj** msgPtr out
+Reference to a place where the message stored in the accessed bypass
+area can be stored in.
+.BE
+.SH DESCRIPTION
+.PP
+The current definition of a Tcl channel driver does not permit the
+direct return of arbitrary error messages, except for the setting and
+retrieval of channel options. All other functions are restricted to
+POSIX error codes.
+.PP
+The functions described here overcome this limitation. Channel drivers
+are allowed to use \fBTcl_SetChannelError\fR and
+\fBTcl_SetChannelErrorInterp\fR to place arbitrary error messages in
+\fBbypass areas\fI defined for channels and interpreters. And the
+generic I/O layer uses \fBTcl_GetChannelError\fR and
+\fBTcl_GetChannelErrorInterp\fR to look for messages in the bypass
+areas and arrange for their return as errors. The posix error codes
+set by a driver are used now if and only if no messages are present.
+.PP
+\fBTcl_SetChannelError\fR stores error information in the bypass area
+of the specified channel. The number of references to the \fBmsg\fR
+object goes up by one. Previously stored information will be
+discarded, by releasing the reference held by the channel. The channel
+reference must not be NULL.
+.PP
+\fBTcl_SetChannelErrorInterp\fR stores error information in the bypass
+area of the specified interpreter. The number of references to the
+\fBmsg\fR object goes up by one. Previously stored information will be
+discarded, by releasing the reference held by the interpreter. The
+interpreter reference must not be NULL.
+.PP
+\fBTcl_GetChannelError\fR places either the error message held in the
+bypass area of the specified channel into \fImsgPtr\fR, or NULL; and
+resets the bypass. I.e. after an invocation all following invocations
+will return NULL, until an intervening invocation of
+\fBTcl_SetChannelError\fR with a non-NULL message. The \fImsgPtr\fR
+must not be NULL. The reference count of the message is not touched.
+The reference previously held by the channel is now held by the caller
+of the function and it is its responsibility to release that reference
+when it is done with the object.
+.PP
+\fBTcl_GetChannelErrorInterp\fR places either the error message held
+in the bypass area of the specified interpreter into \fImsgPtr\fR, or
+NULL; and resets the bypass. I.e. after an invocation all following
+invocations will return NULL, until an intervening invocation of
+\fBTcl_SetChannelErrorInterp\fR with a non-NULL message. The
+\fImsgPtr\fR must not be NULL. The reference count of the message is
+not touched. The reference previously held by the interpreter is now
+held by the caller of the function and it is its responsibility to
+release that reference when it is done with the object.
+.PP
+Which functions of a channel driver are allowed to use which bypass
+function is listed below, as is which functions of the public channel
+API may leave a messages in the bypass areas.
+.PP
+.IP \fBTcl_DriverCloseProc\fR
+May use \fBTcl_SetChannelErrorInterp\fR, and only this function.
+.IP \fBTcl_DriverInputProc\fR
+May use \fBTcl_SetChannelError\fR, and only this function.
+.IP \fBTcl_DriverOutputProc\fR
+May use \fBTcl_SetChannelError\fR, and only this function.
+.IP \fBTcl_DriverSeekProc\fR
+May use \fBTcl_SetChannelError\fR, and only this function.
+.IP \fBTcl_DriverWideSeekProc\fR
+May use \fBTcl_SetChannelError\fR, and only this function.
+.IP \fBTcl_DriverSetOptionProc\fR
+Has already the ability to pass arbitrary error messages. Must
+\fBnot\fR use any of the new functions.
+.IP \fBTcl_DriverGetOptionProc\fR
+Has already the ability to pass arbitrary error messages. Must
+\fBnot\fR use any of the new functions.
+.IP \fBTcl_DriverWatchProc\fR
+Must \fBnot\fR use any of the new functions. Is internally called and
+has no ability to return any type of error whatsoever.
+.IP \fBTcl_DriverBlockModeProc\fR
+May use \fBTcl_SetChannelError\fR, and only this function.
+.IP \fBTcl_DriverGetHandleProc\fR
+Must \fBnot\fR use any of the new functions. It is only a low-level
+function, and not used by Tcl commands.
+.IP \fBTcl_DriverHandlerProc\fR
+Must \fBnot\fR use any of the new functions. Is internally called and
+has no ability to return any type of error whatsoever.
+.PP
+Given the information above the following public functions of the Tcl
+C API are affected by these changes. I.e. when these functions are
+called the channel may now contain a stored arbitrary error message
+requiring processing by the caller.
+.PP
+.IP \fBTcl_StackChannel\fR
+.IP \fBTcl_Seek\fR
+.IP \fBTcl_Tell\fR
+.IP \fBTcl_ReadRaw\fR
+.IP \fBTcl_Read\fR
+.IP \fBTcl_ReadChars\fR
+.IP \fBTcl_Gets\fR
+.IP \fBTcl_GetsObj\fR
+.IP \fBTcl_Flush\fR
+.IP \fBTcl_WriteRaw\fR
+.IP \fBTcl_WriteObj\fR
+.IP \fBTcl_Write\fR
+.IP \fBTcl_WriteChars\fR
+.PP
+All other API functions are unchanged. Especially the functions below
+leave all their error information in the interpreter result.
+.PP
+.IP \fBTcl_Close\fR
+.IP \fBTcl_UnregisterChannel\fR
+.IP \fBTcl_UnstackChannel\fR
+
+.SH "SEE ALSO"
+Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3)
+
+.SH KEYWORDS
+channel driver, error messages, channel type
diff --git a/doc/SetErrno.3 b/doc/SetErrno.3
index f29345a..1735952 100644
--- a/doc/SetErrno.3
+++ b/doc/SetErrno.3
@@ -19,14 +19,14 @@ void
int
\fBTcl_GetErrno\fR()
.sp
-CONST char *
+const char *
\fBTcl_ErrnoId\fR()
.sp
-CONST char *
+const char *
\fBTcl_ErrnoMsg\fR(\fIerrorCode\fR)
.sp
.SH ARGUMENTS
-.AS int errorCode in
+.AS int errorCode
.AP int errorCode in
A POSIX error code such as \fBENOENT\fR.
.BE
@@ -52,9 +52,11 @@ instead of accessing \fBerrno\fR directly.
\fBTcl_ErrnoId\fR and \fBTcl_ErrnoMsg\fR return string
representations of \fBerrno\fR values. \fBTcl_ErrnoId\fR
returns a machine-readable textual identifier such as
-"EACCES" that corresponds to the current value of \fBerrno\fR.
+.QW EACCES
+that corresponds to the current value of \fBerrno\fR.
\fBTcl_ErrnoMsg\fR returns a human-readable string such as
-"permission denied" that corresponds to the value of its
+.QW "permission denied"
+that corresponds to the value of its
\fIerrorCode\fR argument. The \fIerrorCode\fR argument is
typically the value returned by \fBTcl_GetErrno\fR.
The strings returned by these functions are
diff --git a/doc/SetResult.3 b/doc/SetResult.3
index 9844251..2245794 100644
--- a/doc/SetResult.3
+++ b/doc/SetResult.3
@@ -19,38 +19,40 @@ Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult, Tcl_Appe
Tcl_Obj *
\fBTcl_GetObjResult\fR(\fIinterp\fR)
.sp
-\fBTcl_SetResult\fR(\fIinterp, string, freeProc\fR)
+\fBTcl_SetResult\fR(\fIinterp, result, freeProc\fR)
.sp
-CONST char *
+const char *
\fBTcl_GetStringResult\fR(\fIinterp\fR)
.sp
-\fBTcl_AppendResult\fR(\fIinterp, string, string, ... , \fB(char *) NULL\fR)
+\fBTcl_AppendResult\fR(\fIinterp, result, result, ... , \fB(char *) NULL\fR)
.sp
\fBTcl_AppendResultVA\fR(\fIinterp, argList\fR)
.sp
-\fBTcl_AppendElement\fR(\fIinterp, string\fR)
+\fBTcl_AppendElement\fR(\fIinterp, element\fR)
.sp
\fBTcl_ResetResult\fR(\fIinterp\fR)
.sp
\fBTcl_FreeResult\fR(\fIinterp\fR)
.SH ARGUMENTS
-.AS Tcl_FreeProc freeProc
+.AS Tcl_FreeProc freeProc out
.AP Tcl_Interp *interp out
Interpreter whose result is to be modified or read.
.AP Tcl_Obj *objPtr in
Object value to become result for \fIinterp\fR.
-.AP char *string in
+.AP char *result in
String value to become result for \fIinterp\fR or to be
appended to the existing result.
+.AP char *element in
+String value to append as a list element
+to the existing result of \fIinterp\fR.
.AP Tcl_FreeProc *freeProc in
Address of procedure to call to release storage at
-\fIstring\fR, or \fBTCL_STATIC\fR, \fBTCL_DYNAMIC\fR, or
+\fIresult\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.
+An argument list which must have been initialized using
+\fBva_start\fR, and cleared using \fBva_end\fR.
.BE
-
.SH DESCRIPTION
.PP
The procedures described here are utilities for manipulating the
@@ -82,20 +84,20 @@ references to it remain.
The object's reference count is not incremented;
if the caller needs to retain a long-term pointer to the object
they should use \fBTcl_IncrRefCount\fR to increment its reference count
-in order to keep it from being freed too early or accidently changed.
+in order to keep it from being freed too early or accidentally changed.
.PP
\fBTcl_SetResult\fR
-arranges for \fIstring\fR to be the result for the current Tcl
+arranges for \fIresult\fR to be the result for the current Tcl
command in \fIinterp\fR, replacing any existing result.
The \fIfreeProc\fR argument specifies how to manage the storage
-for the \fIstring\fR argument;
+for the \fIresult\fR argument;
it is discussed in the section
\fBTHE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT\fR below.
-If \fIstring\fR is \fBNULL\fR, then \fIfreeProc\fR is ignored
+If \fIresult\fR is \fBNULL\fR, then \fIfreeProc\fR is ignored
and \fBTcl_SetResult\fR
re-initializes \fIinterp\fR's result to point to an empty string.
.PP
-\fBTcl_GetStringResult\fR returns the result for \fIinterp\fR as an string.
+\fBTcl_GetStringResult\fR returns the result for \fIinterp\fR as a string.
If the result was set to an object by a \fBTcl_SetObjResult\fR call,
the object form will be converted to a string and returned.
If the object's string representation contains null bytes,
@@ -114,60 +116,62 @@ and the result is left as a empty string.
\fBTcl_ResetResult\fR also clears the error state managed by
\fBTcl_AddErrorInfo\fR, \fBTcl_AddObjErrorInfo\fR,
and \fBTcl_SetErrorCode\fR.
-
-.SH "OLD STRING PROCEDURES"
-.PP
-Use of the following procedures is deprecated
-since they manipulate the Tcl result as a string.
-Procedures such as \fBTcl_SetObjResult\fR
-that manipulate the result as an object
-can be significantly more efficient.
.PP
\fBTcl_AppendResult\fR makes it easy to build up Tcl results in pieces.
-It takes each of its \fIstring\fR arguments and appends them in order
+It takes each of its \fIresult\fR arguments and appends them in order
to the current result associated with \fIinterp\fR.
If the result is in its initialized empty state (e.g. a command procedure
was just invoked or \fBTcl_ResetResult\fR was just called),
then \fBTcl_AppendResult\fR sets the result to the concatenation of
-its \fIstring\fR arguments.
+its \fIresult\fR arguments.
\fBTcl_AppendResult\fR may be called repeatedly as additional pieces
of the result are produced.
\fBTcl_AppendResult\fR takes care of all the
storage management issues associated with managing \fIinterp\fR's
result, such as allocating a larger result area if necessary.
-It also converts the current interpreter result from an object
-to a string, if necessary, before appending the argument strings.
-Any number of \fIstring\fR arguments may be passed in a single
+It also manages conversion to and from the \fIresult\fR field of the
+\fIinterp\fR so as to handle backward-compatibility with old-style
+extensions.
+Any number of \fIresult\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.
+.SH "OLD STRING PROCEDURES"
+.PP
+Use of the following procedures (is deprecated
+since they manipulate the Tcl result as a string.
+Procedures such as \fBTcl_SetObjResult\fR
+that manipulate the result as an object
+can be significantly more efficient.
.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
+However, \fBTcl_AppendElement\fR takes only a single \fIelement\fR
argument and it appends that argument to the current result
as a proper Tcl list element.
\fBTcl_AppendElement\fR adds backslashes or braces if necessary
to ensure that \fIinterp\fR's result can be parsed as a list and that
-\fIstring\fR will be extracted as a single element.
+\fIelement\fR will be extracted as a single element.
Under normal conditions, \fBTcl_AppendElement\fR will add a space
character to \fIinterp\fR's result just before adding the new
list element, so that the list elements in the result are properly
separated.
However if the new list element is the first in a list or sub-list
(i.e. \fIinterp\fR's current result is empty, or consists of the
-single character ``{'', or ends in the characters `` {'') then no
-space is added.
+single character
+.QW { ,
+or ends in the characters
+.QW " {" )
+then no space is added.
.PP
\fBTcl_FreeResult\fR performs part of the work
of \fBTcl_ResetResult\fR.
It frees up the memory associated with \fIinterp\fR's result.
-It also sets \fIinterp->freeProc\fR to zero, but doesn't
+It also sets \fIinterp->freeProc\fR to zero, but does not
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"
.PP
It used to be legal for programs to
@@ -178,32 +182,31 @@ because it can make the result's string and object forms inconsistent.
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"
.PP
\fBTcl_SetResult\fR's \fIfreeProc\fR argument specifies how
-the Tcl system is to manage the storage for the \fIstring\fR argument.
+the Tcl system is to manage the storage for the \fIresult\fR argument.
If \fBTcl_SetResult\fR or \fBTcl_SetObjResult\fR are called
at a time when \fIinterp\fR holds a string result,
they do whatever is necessary to dispose of the old string result
(see the \fBTcl_Interp\fR manual entry for details on this).
.PP
-If \fIfreeProc\fR is \fBTCL_STATIC\fR it means that \fIstring\fR
+If \fIfreeProc\fR is \fBTCL_STATIC\fR it means that \fIresult\fR
refers to an area of static storage that is guaranteed not to be
modified until at least the next call to \fBTcl_Eval\fR.
If \fIfreeProc\fR
-is \fBTCL_DYNAMIC\fR it means that \fIstring\fR was allocated with a call
+is \fBTCL_DYNAMIC\fR it means that \fIresult\fR was allocated with a call
to \fBTcl_Alloc\fR and is now the property of the Tcl system.
\fBTcl_SetResult\fR will arrange for the string's storage to be
released by calling \fBTcl_Free\fR when it is no longer needed.
-If \fIfreeProc\fR is \fBTCL_VOLATILE\fR it means that \fIstring\fR
+If \fIfreeProc\fR is \fBTCL_VOLATILE\fR it means that \fIresult\fR
points to an area of memory that is likely to be overwritten when
\fBTcl_SetResult\fR returns (e.g. it points to something in a stack frame).
In this case \fBTcl_SetResult\fR will make a copy of the string in
dynamically allocated storage and arrange for the copy to be the
result for the current Tcl command.
.PP
-If \fIfreeProc\fR isn't one of the values \fBTCL_STATIC\fR,
+If \fIfreeProc\fR is not one of the values \fBTCL_STATIC\fR,
\fBTCL_DYNAMIC\fR, and \fBTCL_VOLATILE\fR, then it is the address
of a procedure that Tcl should call to free the string.
This allows applications to use non-standard storage allocators.
@@ -214,10 +217,8 @@ result that match the type \fBTcl_FreeProc\fR:
typedef void Tcl_FreeProc(char *\fIblockPtr\fR);
.CE
When \fIfreeProc\fR is called, its \fIblockPtr\fR will be set to
-the value of \fIstring\fR passed to \fBTcl_SetResult\fR.
-
+the value of \fIresult\fR passed to \fBTcl_SetResult\fR.
.SH "SEE ALSO"
Tcl_AddErrorInfo, Tcl_CreateObjCommand, Tcl_SetErrorCode, Tcl_Interp
-
.SH KEYWORDS
append, command, element, list, object, result, return value, interpreter
diff --git a/doc/SetVar.3 b/doc/SetVar.3
index 9391e3e..ce47a73 100644
--- a/doc/SetVar.3
+++ b/doc/SetVar.3
@@ -14,29 +14,25 @@ Tcl_SetVar2Ex, Tcl_SetVar, Tcl_SetVar2, Tcl_ObjSetVar2, Tcl_GetVar2Ex, Tcl_GetVa
.nf
\fB#include <tcl.h>\fR
.sp
-.VS 8.1
Tcl_Obj *
\fBTcl_SetVar2Ex\fR(\fIinterp, name1, name2, newValuePtr, flags\fR)
-.VE
.sp
-CONST char *
+const char *
\fBTcl_SetVar\fR(\fIinterp, varName, newValue, flags\fR)
.sp
-CONST char *
+const 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
-CONST char *
+const char *
\fBTcl_GetVar\fR(\fIinterp, varName, flags\fR)
.sp
-CONST char *
+const char *
\fBTcl_GetVar2\fR(\fIinterp, name1, name2, flags\fR)
.sp
Tcl_Obj *
@@ -51,29 +47,27 @@ int
.AS Tcl_Interp *newValuePtr
.AP Tcl_Interp *interp in
Interpreter containing variable.
-.AP "CONST char" *name1 in
+.AP "const 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 "CONST char" *name2 in
+.AP "const 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 "CONST char" *varName in
+.AP "const char" *varName in
Name of variable.
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.
-.AP "CONST char" *newValue in
+.AP "const char" *newValue in
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
@@ -91,7 +85,6 @@ within an array and \fIpart1Ptr\fR must refer to an array variable.
These procedures are used to create, modify, read, and delete
Tcl variables from C code.
.PP
-.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.
@@ -105,14 +98,12 @@ 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)
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.
@@ -125,9 +116,8 @@ 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
+does not 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.
@@ -137,9 +127,9 @@ 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
+If the variable is successfully removed then \fBTCL_OK\fR is returned.
+If the variable cannot be removed because it does not exist then
+\fBTCL_ERROR\fR 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
@@ -158,23 +148,20 @@ close parenthesis, then the value between the parentheses is
treated as an index (which can have any string value) and
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
+If \fIvarName\fR does not have parentheses as described above, then
the entire string is treated as the name of a scalar variable.
.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
+name and \fIname2\fR contains the index. 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.
@@ -203,7 +190,7 @@ If an error is returned and this bit is set in \fIflags\fR, then
an error message will be left in the interpreter's result,
where it can be retrieved with \fBTcl_GetObjResult\fR
or \fBTcl_GetStringResult\fR.
-If this flag bit isn't set then no error message is left
+If this flag bit is not set then no error message is left
and the interpreter's result will not be modified.
.TP
\fBTCL_APPEND_VALUE\fR
@@ -218,7 +205,10 @@ Tcl list element before setting (or appending to) the variable.
A separator space is appended before the new list element unless
the list element is going to be the first element in a list or
sublist (i.e. the variable's current value is empty, or contains
-the single character ``{'', or ends in `` }'').
+the single character
+.QW { ,
+or ends in
+.QW " }" ).
When appending, the original value of the variable must also be
a valid list, so that the operation is the appending of a new
list element onto a list.
@@ -231,12 +221,12 @@ Under normal circumstances, the return value is a pointer
to the variable's value (which is stored in Tcl's variable
structure and will not change before the next call to \fBTcl_SetVar\fR
or \fBTcl_SetVar2\fR).
-\fBTcl_GetVar\fR and \fBTcl_GetVar2\fR use the flag bits TCL_GLOBAL_ONLY
-and TCL_LEAVE_ERR_MSG, both of
+\fBTcl_GetVar\fR and \fBTcl_GetVar2\fR use the flag bits \fBTCL_GLOBAL_ONLY\fR
+and \fBTCL_LEAVE_ERR_MSG\fR, both of
which have
the same meaning as for \fBTcl_SetVar\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
+does not exist or an array element is specified for a scalar
variable), then NULL is returned.
.PP
\fBTcl_UnsetVar\fR and \fBTcl_UnsetVar2\fR may be used to remove
@@ -244,9 +234,9 @@ a variable, so that future calls to \fBTcl_GetVar\fR or \fBTcl_GetVar2\fR
for the variable will return an error.
The arguments to these procedures are treated in the same way
as the arguments to \fBTcl_GetVar\fR and \fBTcl_GetVar2\fR.
-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.
+If the variable is successfully removed then \fBTCL_OK\fR is returned.
+If the variable cannot be removed because it does not exist then
+\fBTCL_ERROR\fR is returned.
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
diff --git a/doc/Signal.3 b/doc/Signal.3
index f8eafd0..5b12654 100644
--- a/doc/Signal.3
+++ b/doc/Signal.3
@@ -13,13 +13,14 @@ Tcl_SignalId, Tcl_SignalMsg \- Convert signal codes
.nf
\fB#include <tcl.h>\fR
.sp
-CONST char *
+const char *
\fBTcl_SignalId\fR(\fIsig\fR)
.sp
-CONST char *
+const char *
\fBTcl_SignalMsg\fR(\fIsig\fR)
.sp
.SH ARGUMENTS
+.AS int sig
.AP int sig in
A POSIX signal number such as \fBSIGPIPE\fR.
.BE
@@ -29,8 +30,11 @@ A POSIX signal number such as \fBSIGPIPE\fR.
\fBTcl_SignalId\fR and \fBTcl_SignalMsg\fR return a string
representation of the provided signal number (\fIsig\fR).
\fBTcl_SignalId\fR returns a machine-readable textual identifier such
-as "SIGPIPE". \fBTcl_SignalMsg\fR returns a human-readable string such
-as "bus error". The strings returned by these functions are
+as
+.QW SIGPIPE .
+\fBTcl_SignalMsg\fR returns a human-readable string such as
+.QW "bus error" .
+The strings returned by these functions are
statically allocated and the caller must not free or modify them.
.SH KEYWORDS
diff --git a/doc/Sleep.3 b/doc/Sleep.3
index 1abd2e6..2423ba1 100644
--- a/doc/Sleep.3
+++ b/doc/Sleep.3
@@ -16,20 +16,19 @@ Tcl_Sleep \- delay execution for a given number of milliseconds
.sp
\fBTcl_Sleep\fR(\fIms\fR)
.SH ARGUMENTS
+.AS int ms
.AP int ms in
Number of milliseconds to sleep.
.BE
-
.SH DESCRIPTION
.PP
This procedure delays the calling process by the number of
milliseconds given by the \fIms\fR parameter and returns
after that time has elapsed. It is typically used for things
like flashing a button, where the delay is short and the
-application needn't do anything while it waits. For longer
+application need not do anything while it waits. For longer
delays where the application needs to respond to other events
during the delay, the procedure \fBTcl_CreateTimerHandler\fR
should be used instead of \fBTcl_Sleep\fR.
-
.SH KEYWORDS
sleep, time, wait
diff --git a/doc/SourceRCFile.3 b/doc/SourceRCFile.3
index 5eb5472..eabc47c 100644
--- a/doc/SourceRCFile.3
+++ b/doc/SourceRCFile.3
@@ -14,6 +14,7 @@ Tcl_SourceRCFile \- source the Tcl rc file
void
\fBTcl_SourceRCFile\fR(\fIinterp\fR)
.SH ARGUMENTS
+.AS Tcl_Interp *interp
.AP Tcl_Interp *interp in
Tcl interpreter to source rc file into.
.BE
diff --git a/doc/SplitList.3 b/doc/SplitList.3
index b1a298d..fd6ec8b 100644
--- a/doc/SplitList.3
+++ b/doc/SplitList.3
@@ -32,7 +32,7 @@ int
int
\fBTcl_ConvertCountedElement\fR(\fIsrc, length, dst, flags\fR)
.SH ARGUMENTS
-.AS "CONST char * CONST" ***argvPtr
+.AS "const char *const" ***argvPtr out
.AP Tcl_Interp *interp out
Interpreter to use for error reporting. If NULL, then no error message
is left.
@@ -40,17 +40,17 @@ is left.
Pointer to a string with proper list structure.
.AP int *argcPtr out
Filled in with number of elements in \fIlist\fR.
-.AP "CONST char" ***argvPtr out
+.AP "const char" ***argvPtr out
\fI*argvPtr\fR will be filled in with the address of an array of
pointers to the strings that are the extracted elements of \fIlist\fR.
There will be \fI*argcPtr\fR valid entries in the array, followed by
a NULL entry.
.AP int argc in
Number of elements in \fIargv\fR.
-.AP "CONST char * CONST" *argv in
+.AP "const char *const" *argv in
Array of strings to merge together into a single list.
Each string will become a separate element of the list.
-.AP "CONST char" *src in
+.AP "const char" *src in
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.
@@ -151,7 +151,7 @@ include spaces between adjacent list elements.
\fBTcl_ConvertElement\fR uses one of two different approaches to
handle the special characters in \fIsrc\fR. Wherever possible, it
handles special characters by surrounding the string with braces.
-This produces clean-looking output, but can't be used in some situations,
+This produces clean-looking output, but cannot be used in some situations,
such as when \fIsrc\fR contains unmatched braces.
In these situations, \fBTcl_ConvertElement\fR handles special
characters by generating backslash sequences for them.
@@ -164,6 +164,20 @@ 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 8.5
+By default, \fBTcl_ConvertElement\fR will use quoting in its output
+to be sure the first character of an element is not the hash
+character
+.PQ # .
+This is to be sure the first element of any list
+passed to \fBeval\fR is not mis-parsed as the beginning of a comment.
+When a list element is not the first element of a list, this quoting
+is not necessary. When the caller can be sure that the element is
+not the first element of a list, it can disable quoting of the leading
+hash character by OR-ing the flag value returned by \fBTcl_ScanElement\fR
+with \fBTCL_DONT_QUOTE_HASH\fR.
+.VE 8.5
+.PP
\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
diff --git a/doc/SplitPath.3 b/doc/SplitPath.3
index 9bc6acb..6578e3d 100644
--- a/doc/SplitPath.3
+++ b/doc/SplitPath.3
@@ -21,20 +21,20 @@ char *
Tcl_PathType
\fBTcl_GetPathType\fR(\fIpath\fR)
.SH ARGUMENTS
-.AS Tcl_DString ***argvPtr
-.AP "CONST char * CONST" *argvPtr in
+.AS "const char *const" ***argvPtr in/out
+.AP "const char" *path in
File path in a form appropriate for the current platform (see the
\fBfilename\fR manual entry for acceptable forms for path names).
.AP int *argcPtr out
Filled in with number of path elements in \fIpath\fR.
-.AP "CONST char" ***argvPtr out
+.AP "const char" ***argvPtr out
\fI*argvPtr\fR will be filled in with the address of an array of
pointers to the strings that are the extracted elements of \fIpath\fR.
There will be \fI*argcPtr\fR valid entries in the array, followed by
a NULL entry.
.AP int argc in
Number of elements in \fIargv\fR.
-.AP "CONST char * CONST" *argv in
+.AP "const char *const" *argv in
Array of path elements to merge together into a single path.
.AP Tcl_DString *resultPtr in/out
A pointer to an initialized \fBTcl_DString\fR to which the result of
diff --git a/doc/StaticPkg.3 b/doc/StaticPkg.3
index f4c279c..0dd67d1 100644
--- a/doc/StaticPkg.3
+++ b/doc/StaticPkg.3
@@ -8,7 +8,7 @@
.TH Tcl_StaticPackage 3 7.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
-Tcl_StaticPackage \- make a statically linked package available via the \fBload\fR command
+Tcl_StaticPackage \- make a statically linked package available via the 'load' command
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
@@ -20,8 +20,8 @@ Tcl_StaticPackage \- make a statically linked package available via the \fBload\
If not NULL, points to an interpreter into which the package has
already been loaded (i.e., the caller has already invoked the
appropriate initialization procedure). NULL means the package
-hasn't yet been incorporated into any interpreter.
-.AP "CONST char" *pkgName in
+has not yet been incorporated into any interpreter.
+.AP "const char" *pkgName in
Name of the package; should be properly capitalized (first letter
upper-case, all others lower-case).
.AP Tcl_PackageInitProc *initProc in
@@ -30,7 +30,7 @@ interpreter.
.AP Tcl_PackageInitProc *safeInitProc in
Procedure to call to incorporate this package into a safe interpreter
(one that will execute untrusted scripts). NULL means the package
-can't be used in safe interpreters.
+cannot be used in safe interpreters.
.BE
.SH DESCRIPTION
diff --git a/doc/StdChannels.3 b/doc/StdChannels.3
index 2a7dd05..b5b020e 100644
--- a/doc/StdChannels.3
+++ b/doc/StdChannels.3
@@ -26,8 +26,7 @@ output and the other for error messages.
.PP
Tcl generalizes this concept in a cross-platform way and
exposes standard channels to the script level.
-
-.SH APIs
+.SS "APPLICATION PROGRAMMING INTERFACES"
.PP
The public API procedures dealing directly with standard channels are
\fBTcl_GetStdChannel\fR and \fBTcl_SetStdChannel\fR. Additional public
@@ -41,17 +40,21 @@ channel information, or when implicitly required during registration
of a new channel.
.PP
These cases differ in how they handle unavailable platform- specific
-standard channels. (A channel is not ``available'' if it could not be
+standard channels. (A channel is not
+.QW available
+if it could not be
successfully opened; for example, in a Tcl application run as a
Windows NT service.)
.TP
1)
A single standard channel is initialized when it is explicitly
-specified in a call to \fBTcl_SetStdChannel\fR. The state of the
+specified in a call to \fBTcl_SetStdChannel\fR. The states of the
other standard channels are unaffected.
-.sp
+.RS
+.PP
Missing platform-specific standard channels do not matter here. This
approach is not available at the script level.
+.RE
.TP
2)
All uninitialized standard channels are initialized to
@@ -67,9 +70,7 @@ when information about any standard channel is requested with a call
to \fBTcl_GetStdChannel\fR, or with a call to \fBTcl_GetChannel\fR
which specifies one of the standard names (\fBstdin\fR, \fBstdout\fR
and \fBstderr\fR).
-.RE
-.sp
-.RS
+.PP
In case of missing platform-specific standard channels, the Tcl
standard channels are considered as initialized and then immediately
closed. This means that the first three Tcl channels then opened by
@@ -80,14 +81,13 @@ the application are designated as the Tcl standard channels.
All uninitialized standard channels are initialized to
platform-specific default values when a user-requested channel is
registered with \fBTcl_RegisterChannel\fR.
-.sp
+.PP
In case of unavailable platform-specific standard channels the channel
whose creation caused the initialization of the Tcl standard channels
is made a normal channel. The next three Tcl channels opened by the
application are designated as the Tcl standard channels. In other
words, of the first four Tcl channels opened by the application the
second to fourth are designated as the Tcl standard channels.
-.PP
.SH "RE-INITIALIZATION OF TCL STANDARD CHANNELS"
.PP
Once a Tcl standard channel is initialized through one of the methods
@@ -101,21 +101,20 @@ channel, too. If more than one Tcl standard channel was closed
that slot was not initialized before. It is this behavior which
enables an application to employ method 1 of initialization, i.e. to
create and designate their own Tcl standard channels.
-
-.SH tclsh
+.SH "SHELL-SPECIFIC DETAILS"
+.SS tclsh
.PP
-The Tcl shell (or rather \fBTcl_Main\fR) uses method 2 to initialize
+The Tcl shell (or rather the function \fBTcl_Main\fR, which forms the
+core of the shell's implementation) uses method 2 to initialize
the standard channels.
-
-.SH wish
+.SS wish
.PP
-The windowing shell (or rather \fBTk_MainEx\fR) uses method 1 to
+The windowing shell (or rather the function \fBTk_MainEx\fR, which
+forms the core of the shell's implementation) uses method 1 to
initialize the standard channels (See \fBTk_InitConsoleChannels\fR)
on non-Unix platforms. On Unix platforms, \fBTk_MainEx\fR implicitly
uses method 2 to initialize the standard channels.
-
.SH "SEE ALSO"
Tcl_CreateChannel(3), Tcl_RegisterChannel(3), Tcl_GetChannel(3), Tcl_GetStdChannel(3), Tcl_SetStdChannel(3), Tk_InitConsoleChannels(3), tclsh(1), wish(1), Tcl_Main(3), Tk_MainEx(3)
-
.SH KEYWORDS
standard channels
diff --git a/doc/StrMatch.3 b/doc/StrMatch.3
index f490c19..5adaf6e 100644
--- a/doc/StrMatch.3
+++ b/doc/StrMatch.3
@@ -6,7 +6,7 @@
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.so man.macros
-.TH Tcl_StringMatch 3 8.1 Tcl "Tcl Library Procedures"
+.TH Tcl_StringMatch 3 8.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_StringMatch, Tcl_StringCaseMatch \- test whether a string matches a pattern
@@ -15,19 +15,20 @@ Tcl_StringMatch, Tcl_StringCaseMatch \- test whether a string matches a pattern
\fB#include <tcl.h>\fR
.sp
int
-\fBTcl_StringMatch\fR(\fIstring\fR, \fIpattern\fR)
+\fBTcl_StringMatch\fR(\fIstr\fR, \fIpattern\fR)
.sp
int
-\fBTcl_StringCaseMatch\fR(\fIstring\fR, \fIpattern\fR, \fInocase\fR)
+\fBTcl_StringCaseMatch\fR(\fIstr\fR, \fIpattern\fR, \fIflags\fR)
.SH ARGUMENTS
-.AP char *string in
+.AS "const char" *pattern
+.AP "const char" *str in
String to test.
-.AP char *pattern in
+.AP "const char" *pattern in
Pattern to match against string. May contain special
characters from the set *?\e[].
-.AP int nocase in
-Specifies whether the match should be done case-sensitive (0) or
-case-insensitive (1).
+.AP int flags in
+OR-ed combination of match flags, currently only \fBTCL_MATCH_NOCASE\fR.
+0 specifies a case-sensitive search.
.BE
.SH DESCRIPTION
@@ -35,16 +36,14 @@ case-insensitive (1).
This utility procedure determines whether a string matches
a given pattern. If it does, then \fBTcl_StringMatch\fR returns
1. Otherwise \fBTcl_StringMatch\fR returns 0. The algorithm
-used for matching is the same algorithm used in the ``string match''
+used for matching is the same algorithm used in the \fBstring match\fR
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
+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 \fBTCL_MATCH_NOCASE\fR), then the string and
+pattern are essentially matched in the lower case.
.SH KEYWORDS
match, pattern, string
diff --git a/doc/StringObj.3 b/doc/StringObj.3
index 6a624db..e451c61 100644
--- a/doc/StringObj.3
+++ b/doc/StringObj.3
@@ -8,7 +8,7 @@
.TH Tcl_StringObj 3 8.1 Tcl "Tcl Library Procedures"
.BS
.SH NAME
-Tcl_NewStringObj, Tcl_NewUnicodeObj, Tcl_SetStringObj, Tcl_SetUnicodeObj, Tcl_GetStringFromObj, Tcl_GetString, Tcl_GetUnicodeFromObj, Tcl_GetUnicode, Tcl_GetUniChar, Tcl_GetCharLength, Tcl_GetRange, Tcl_AppendToObj, Tcl_AppendUnicodeToObj, Tcl_AppendStringsToObj, Tcl_AppendStringsToObjVA, Tcl_AppendObjToObj, Tcl_SetObjLength, Tcl_ConcatObj, Tcl_AttemptSetObjLength \- manipulate Tcl objects as strings
+Tcl_NewStringObj, Tcl_NewUnicodeObj, Tcl_SetStringObj, Tcl_SetUnicodeObj, Tcl_GetStringFromObj, Tcl_GetString, Tcl_GetUnicodeFromObj, Tcl_GetUnicode, Tcl_GetUniChar, Tcl_GetCharLength, Tcl_GetRange, Tcl_AppendToObj, Tcl_AppendUnicodeToObj, Tcl_AppendObjToObj, Tcl_AppendStringsToObj, Tcl_AppendStringsToObjVA, Tcl_AppendLimitedToObj, Tcl_Format, Tcl_AppendFormatToObj, Tcl_ObjPrintf, Tcl_AppendPrintfToObj, Tcl_SetObjLength, Tcl_AttemptSetObjLength, Tcl_ConcatObj \- manipulate Tcl objects as strings
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
@@ -60,6 +60,23 @@ void
.sp
void
\fBTcl_AppendStringsToObjVA\fR(\fIobjPtr, argList\fR)
+.VS 8.5
+.sp
+void
+\fBTcl_AppendLimitedToObj\fR(\fIobjPtr, bytes, length, limit, ellipsis\fR)
+.sp
+Tcl_Obj *
+\fBTcl_Format\fR(\fIinterp, format, objc, objv\fR)
+.sp
+int
+\fBTcl_AppendFormatToObj\fR(\fIinterp, objPtr, format, objc, objv\fR)
+.sp
+Tcl_Obj *
+\fBTcl_ObjPrintf\fR(\fIformat, ...\fR)
+.sp
+int
+\fBTcl_AppendPrintfToObj\fR(\fIobjPtr, format, ...\fR)
+.VE 8.5
.sp
void
\fBTcl_SetObjLength\fR(\fIobjPtr, newLength\fR)
@@ -70,22 +87,20 @@ int
Tcl_Obj *
\fBTcl_ConcatObj\fR(\fIobjc, objv\fR)
.SH ARGUMENTS
-.AS "CONST Tcl_UniChar" *appendObjPtr in/out
-.AP "CONST char" *bytes in
-.VS 8.1
+.AS "const Tcl_UniChar" *appendObjPtr in/out
+.AP "const char" *bytes in
Points to the first byte of an array of UTF-8-encoded bytes
used to set or append to a string object.
-This byte array should not contain embedded null bytes
-unless \fIlength\fR is negative. (Applications needing null bytes
-should represent them as the two-byte sequence \fI\\700\\600\fR, use
+This byte array may contain embedded null characters
+unless \fInumChars\fR is negative. (Applications needing null bytes
+should represent them as the two-byte sequence \fI\e700\e600\fR, use
\fBTcl_ExternalToUtf\fR to convert, or \fBTcl_NewByteArrayObj\fR if
the string is a collection of uninterpreted bytes.)
-.VE 8.1
.AP int length in
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 "CONST Tcl_UniChar" *unicode in
+.AP "const 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
@@ -108,19 +123,26 @@ Points to an object to manipulate.
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 "CONST char" *string in
+the length of an object's string representation.
+.AP "const 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.
+\fBva_start\fR, and cleared using \fBva_end\fR.
+.AP int limit in
+Maximum number of bytes to be appended.
+.AP "const char" *ellipsis in
+Suffix to append when the limit leads to string truncation.
+If NULL is passed then the suffix "..." is used.
+.AP "const char" *format in
+Format control string including % conversion specifiers.
+.AP int objc in
+The number of elements to format or concatenate.
+.AP Tcl_Obj *objv[] in
+The array of objects to format or concatenate.
.AP int newLength in
New length for the string value of \fIobjPtr\fR, not including the
final null character.
-.AP int objc in
-The number of elements to concatenate.
-.AP Tcl_Obj *objv[] in
-The array of objects to concatenate.
.BE
.SH DESCRIPTION
@@ -130,7 +152,7 @@ be manipulated as string values. They use the internal representation
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.
+string so that it does not have to be copied for each append.
Also, indexing and length computations are optimized because the
Unicode string representation is calculated and cached as needed.
When using the \fBTcl_Append*\fR family of functions where the
@@ -163,7 +185,7 @@ will be able to modify the string representation within the
\fBTcl_UpdateStringProc\fR of their \fBTcl_ObjType\fR. Except for that
limited purpose, the pointer returned by \fBTcl_GetStringFromObj\fR
or \fBTcl_GetString\fR should be treated as read-only. It is
-recommended that this pointer be assigned to a (CONST char *) variable.
+recommended that this pointer be assigned to a (const char *) variable.
Even in the limited situations where writing to this pointer is
acceptable, one should take care to respect the copy-on-write
semantics required by \fBTcl_Obj\fR's, with appropriate calls
@@ -229,6 +251,88 @@ must be a NULL pointer to indicate the end of the list.
except that instead of taking a variable number of arguments it takes an
argument list.
.PP
+.VS 8.5
+\fBTcl_AppendLimitedToObj\fR is similar to \fBTcl_AppendToObj\fR
+except that it imposes a limit on how many bytes are appended.
+This can be handy when the string to be appended might be
+very large, but the value being constructed should not be allowed to grow
+without bound. A common usage is when constructing an error message, where the
+end result should be kept short enough to be read.
+Bytes from \fIbytes\fR are appended to \fIobjPtr\fR, but no more
+than \fIlimit\fR bytes total are to be appended. If the limit prevents
+all \fIlength\fR bytes that are available from being appended, then the
+appending is done so that the last bytes appended are from the
+string \fIellipsis\fR. This allows for an indication of the truncation
+to be left in the string.
+When \fIlength\fR is \fB-1\fR, all bytes up to the first zero byte are appended,
+subject to the limit. When \fIellipsis\fR is NULL, the default
+string \fB...\fR is used. When \fIellipsis\fR is non-NULL, it must point
+to a zero-byte-terminated string in Tcl's internal UTF encoding.
+The number of bytes appended can be less than the lesser
+of \fIlength\fR and \fIlimit\fR when appending fewer
+bytes is necessary to append only whole multi-byte characters.
+.PP
+\fBTcl_Format\fR is the C-level interface to the engine of the \fBformat\fR
+command. The actual command procedure for \fBformat\fR is little more
+than
+.CS
+Tcl_Format(interp, Tcl_GetString(objv[1]), objc-2, objv+2);
+.CE
+The \fIobjc\fR Tcl_Obj values in \fIobjv\fR are formatted into a string
+according to the conversion specification in \fIformat\fR argument, following
+the documentation for the \fBformat\fR command. The resulting formatted
+string is converted to a new Tcl_Obj with refcount of zero and returned.
+If some error happens during production of the formatted string, NULL is
+returned, and an error message is recorded in \fIinterp\fR, if \fIinterp\fR
+is non-NULL.
+.PP
+\fBTcl_AppendFormatToObj\fR is an appending alternative form
+of \fBTcl_Format\fR with functionality equivalent to
+.CS
+Tcl_Obj *newPtr = Tcl_Format(interp, format, objc, objv);
+if (newPtr == NULL) return TCL_ERROR;
+Tcl_AppendObjToObj(objPtr, newPtr);
+return TCL_OK;
+.CE
+but with greater convenience and efficiency when the appending
+functionality is needed.
+.PP
+\fBTcl_ObjPrintf\fR serves as a replacement for the common sequence
+.CS
+char buf[SOME_SUITABLE_LENGTH];
+sprintf(buf, format, ...);
+Tcl_NewStringObj(buf, -1);
+.CE
+but with greater convenience and no need to
+determine \fBSOME_SUITABLE_LENGTH\fR. The formatting is done with the same
+core formatting engine used by \fBTcl_Format\fR. This means the set of
+supported conversion specifiers is that of the \fBformat\fR command and
+not that of the \fBsprintf\fR routine where the two sets differ. When a
+conversion specifier passed to \fBTcl_ObjPrintf\fR includes a precision,
+the value is taken as a number of bytes, as \fBsprintf\fR does, and not
+as a number of characters, as \fBformat\fR does. This is done on the
+assumption that C code is more likely to know how many bytes it is
+passing around than the number of encoded characters those bytes happen
+to represent. The variable number of arguments passed in should be of
+the types that would be suitable for passing to \fBsprintf\fR. Note in
+this example usage, \fIx\fR is of type \fBlong\fR.
+.CS
+long x = 5;
+Tcl_Obj *objPtr = Tcl_ObjPrintf("Value is %d", x);
+.CE
+If the value of \fIformat\fR contains internal inconsistencies or invalid
+specifier formats, the formatted string result produced by
+\fBTcl_ObjPrintf\fR will be an error message describing the error.
+.PP
+\fBTcl_AppendPrintfToObj\fR is an appending alternative form
+of \fBTcl_ObjPrintf\fR with functionality equivalent to
+.CS
+Tcl_AppendObjToObj(objPtr, Tcl_ObjPrintf(format, ...));
+.CE
+but with greater convenience and efficiency when the appending
+functionality is needed.
+.VE 8.5
+.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
@@ -265,7 +369,7 @@ cleaner-looking. \fBTcl_ConcatObj\fR returns a pointer to a
newly-created object whose ref count is zero.
.SH "SEE ALSO"
-Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount
+Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount, format, sprintf
.SH KEYWORDS
append, internal representation, object, object type, string object,
diff --git a/doc/SubstObj.3 b/doc/SubstObj.3
index 9f016c0..786b595 100644
--- a/doc/SubstObj.3
+++ b/doc/SubstObj.3
@@ -16,7 +16,7 @@ Tcl_SubstObj \- perform substitutions on Tcl objects
Tcl_Obj *
\fBTcl_SubstObj\fR(\fIinterp, objPtr, flags\fR)
.SH ARGUMENTS
-.AS Tcl_Interp **termPtr;
+.AS Tcl_Interp **termPtr
.AP Tcl_Interp *interp in
Interpreter in which to execute Tcl scripts and lookup variables. If
an error occurs, the interpreter's result is modified to hold an error
@@ -30,7 +30,6 @@ perform. The flags \fBTCL_SUBST_COMMANDS\fR,
currently supported, and \fBTCL_SUBST_ALL\fR is provided as a
convenience for the common case where all substitutions are desired.
.BE
-
.SH DESCRIPTION
.PP
The \fBTcl_SubstObj\fR function is used to perform substitutions on
@@ -51,19 +50,19 @@ When the \fBTCL_SUBST_VARIABLES\fR bit is set in \fIflags\fR,
sequences that look like variable substitutions for Tcl commands are
replaced by the contents of the named variable.
.PP
-When th \fBTCL_SUBST_COMMANDS\fR bit is set in \fIflags\fR, sequences
+When the \fBTCL_SUBST_COMMANDS\fR bit is set in \fIflags\fR, sequences
that look like command substitutions for Tcl commands are replaced by
-the result of evaluating that script. Where an uncaught continue
-exception occurs during the evaluation of a command substitution, an
-empty string is substituted for the command. Where an uncaught break
-exception occurs during the evaluation of a command substitution, the
+the result of evaluating that script. Where an uncaught
+.QW "continue exception"
+occurs during the evaluation of a command substitution, an
+empty string is substituted for the command. Where an uncaught
+.QW "break exception"
+occurs during the evaluation of a command substitution, the
result of the whole substitution on \fIobjPtr\fR will be truncated at
the point immediately before the start of the command substitution,
and no characters will be added to the result or substitutions
performed after that point.
-
.SH "SEE ALSO"
subst(n)
-
.SH KEYWORDS
backslash substitution, command substitution, variable substitution
diff --git a/doc/TCL_MEM_DEBUG.3 b/doc/TCL_MEM_DEBUG.3
index def44c1..5a3e08a 100644
--- a/doc/TCL_MEM_DEBUG.3
+++ b/doc/TCL_MEM_DEBUG.3
@@ -7,53 +7,56 @@
.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.
+TCL_MEM_DEBUG \- Compile-time flag to enable Tcl memory debugging
.BE
-
.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
+of memory debugging aids is 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
+\fBTCL_MEM_DEBUG\fR defined (e.g. by passing the
+\fI\-\-enable\-symbols=mem\fR flag to the \fIconfigure\fR script when
+building). 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
+errors will occur, with either \fBTcl_DbCkfree\fR and \fBTcl_DbCkalloc\fR or
\fBTcl_Alloc\fR and \fBTcl_Free\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
+made, slightly more memory than requested is allocated so the memory
+debugging code can keep track of the allocated memory, and eight-byte
+.QW "guard zones"
+are placed in front of and behind the space that will be
returned to the caller. (The sizes of the guard zones are defined by the
C #define \fBLOW_GUARD_SIZE\fR and #define \fBHIGH_GUARD_SIZE\fR
-in the file \fIgeneric/tclCkalloc.c\fR -- it can
+in the file \fIgeneric/tclCkalloc.c\fR \(em 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
+.QW "low guard failed"
+or
+.QW "high guard failed"
+message is issued. The
+.QW "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
@@ -66,16 +69,12 @@ 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
+\fBckalloc\fR and \fBckfree\fR is not 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"
ckalloc, memory, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory
-
.SH KEYWORDS
memory, debug
-
-
diff --git a/doc/Tcl.n b/doc/Tcl.n
index d329bb9..8b5b501 100644
--- a/doc/Tcl.n
+++ b/doc/Tcl.n
@@ -6,7 +6,7 @@
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.so man.macros
-.TH Tcl n "8.1" Tcl "Tcl Built-In Commands"
+.TH Tcl n "8.5" Tcl "Tcl Built-In Commands"
.BS
.SH NAME
Tcl \- Tool Command Language
@@ -39,17 +39,37 @@ Different commands interpret their words differently.
Words of a command are separated by white space (except for
newlines, which are command separators).
.IP "[4] \fBDouble quotes.\fR"
-If the first character of a word is double-quote (``"'') then
-the word is terminated by the next double-quote character.
+If the first character of a word is double-quote
+.PQ \N'34'
+then the word is terminated by the next double-quote character.
If semi-colons, close brackets, or white space characters
(including newlines) appear between the quotes then they are treated
as ordinary characters and included in the word.
Command substitution, variable substitution, and backslash substitution
are performed on the characters between the quotes as described below.
The double-quotes are not retained as part of the word.
-.IP "[5] \fBBraces.\fR"
-If the first character of a word is an open brace (``{'') then
-the word is terminated by the matching close brace (``}'').
+.VS 8.5 br
+.IP "[5] \fBArgument expansion.\fR"
+If a word starts with the string
+.QW {*}
+followed by a non-whitespace character, then the leading
+.QW {*}
+is removed and the rest of the word is parsed and substituted as any other
+word. After substitution, the word is parsed as a list (without command or
+variable substitutions; backslash substitutions are performed as is normal for
+a list and individual internal words may be surrounded by either braces or
+double-quote characters), and its words are added to the command being
+substituted. For instance,
+.QW "cmd a {*}{b [c]} d {*}{$e f \N'34'g h\N'34'}"
+is equivalent to
+.QW "cmd a b {[c]} d {$e} f \N'34'g h\N'34'" .
+.VE 8.5
+.IP "[6] \fBBraces.\fR"
+If the first character of a word is an open brace
+.PQ {
+and rule [5] does not apply, then
+the word is terminated by the matching close brace
+.PQ } "" .
Braces nest within the word: for each additional open
brace there must be an additional close brace (however,
if an open brace or close brace within the word is
@@ -61,20 +81,24 @@ below, nor do semi-colons, newlines, close brackets,
or white space receive any special interpretation.
The word will consist of exactly the characters between the
outer braces, not including the braces themselves.
-.IP "[6] \fBCommand substitution.\fR"
-If a word contains an open bracket (``['') then Tcl performs
-\fIcommand substitution\fR.
+.IP "[7] \fBCommand substitution.\fR"
+If a word contains an open bracket
+.PQ [
+then Tcl performs \fIcommand substitution\fR.
To do this it invokes the Tcl interpreter recursively to process
the characters following the open bracket as a Tcl script.
The script may contain any number of commands and must be terminated
-by a close bracket (``]'').
+by a close bracket
+.PQ ] "" .
The result of the script (i.e. the result of its last command) is
substituted into the word in place of the brackets and all of the
characters between them.
There may be any number of command substitutions in a single word.
Command substitution is not performed on words enclosed in braces.
-.IP "[7] \fBVariable substitution.\fR"
-If a word contains a dollar-sign (``$'') followed by one of the forms
+.IP "[8] \fBVariable substitution.\fR"
+If a word contains a dollar-sign
+.PQ $
+followed by one of the forms
described below, then Tcl performs \fIvariable
substitution\fR: the dollar-sign and the following characters are
replaced in the word by the value of a variable.
@@ -101,9 +125,10 @@ characters whatsoever except for close braces.
There may be any number of variable substitutions in a single word.
Variable substitution is not performed on words enclosed in braces.
.RE
-.IP "[8] \fBBackslash substitution.\fR"
-If a backslash (``\e'') appears within a word then
-\fIbackslash substitution\fR occurs.
+.IP "[9] \fBBackslash substitution.\fR"
+If a backslash
+.PQ \e
+appears within a word then \fIbackslash substitution\fR occurs.
In all cases but those described below the backslash is dropped and
the following character is treated as an ordinary
character and included in the word.
@@ -141,12 +166,12 @@ 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
+and the resulting space will be treated as a word separator if it is not
in braces or quotes.
.TP 7
\e\e
-Backslash (``\e'').
-.VS 8.1 br
+Backslash
+.PQ \e "" .
.TP 7
\e\fIooo\fR
.
@@ -167,19 +192,20 @@ be 0.
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.
.RE
-.IP "[9] \fBComments.\fR"
-If a hash character (``#'') appears at a point where Tcl is
+.IP "[10] \fBComments.\fR"
+If a hash character
+.PQ #
+appears at a point where Tcl is
expecting the first character of the first word of a command,
then the hash character and the characters that follow it, up
through the next newline, are treated as a comment and ignored.
The comment character only has significance when it appears
at the beginning of a command.
-.IP "[10] \fBOrder of substitution.\fR"
+.IP "[11] \fBOrder of substitution.\fR"
Each character is processed exactly once by the Tcl interpreter
as part of creating the words of a command.
For example, if variable substitution occurs then no further
@@ -200,8 +226,9 @@ set y [set x 0][incr x][incr x]
.CE
will always set the variable \fIy\fR to the value, \fI012\fR.
.RE
-.IP "[11] \fBSubstitution and word boundaries.\fR"
-Substitutions do not affect the word boundaries of a command.
+.IP "[12] \fBSubstitution and word boundaries.\fR"
+Substitutions do not affect the word boundaries of a command,
+except for argument expansion as specified in rule [5].
For example, during variable substitution the entire value of
the variable becomes part of a single word, even if the variable's
value contains spaces.
diff --git a/doc/Tcl_Main.3 b/doc/Tcl_Main.3
index 4f29c82..54b2e84 100644
--- a/doc/Tcl_Main.3
+++ b/doc/Tcl_Main.3
@@ -19,7 +19,7 @@ Tcl_Main, Tcl_SetMainLoop \- main program and event loop definition for Tcl-base
.sp
\fBTcl_SetMainLoop\fR(\fImainLoopProc\fR)
.SH ARGUMENTS
-.AS Tcl_AppInitProc *appInitProc
+.AS Tcl_MainLoopProc *mainLoopProc
.AP int argc in
Number of elements in \fIargv\fR.
.AP char *argv[] in
@@ -34,7 +34,9 @@ Address of an application-specific event loop procedure.
.SH DESCRIPTION
.PP
\fBTcl_Main\fR can serve as the main program for Tcl-based shell
-applications. A ``shell application'' is a program
+applications. A
+.QW "shell application"
+is a program
like tclsh or wish that supports both interactive interpretation
of Tcl and evaluation of a script contained in a file given as
a command line argument. \fBTcl_Main\fR is offered as a convenience
@@ -74,9 +76,12 @@ channels to their default values. See \fBTcl_StandardChannels\fR for
more information.
.PP
\fBTcl_Main\fR supports two modes of operation, depending on the
-values of \fIargc\fR and \fIargv\fR. If \fIargv[1]\fR exists and
-does not begin with the character \fI-\fR, it is taken to be the
-name of a file containing a \fIstartup script\fR, which \fBTcl_Main\fR
+values of \fIargc\fR and \fIargv\fR. If the first few arguments
+in \fIargv\fR match ?\fB\-encoding \fIname\fR? \fIfileName\fR,
+where \fIfileName\fR does not begin with the character \fI\-\fR,
+then \fIfileName\fR is taken to be the name of a file containing
+a \fIstartup script\fR, and \fIname\fR is taken to be the name
+of the encoding of the contents of that file, which \fBTcl_Main\fR
will attempt to evaluate. Otherwise, \fBTcl_Main\fR will enter an
interactive mode.
.PP
@@ -86,8 +91,9 @@ the Tcl variables \fIargc\fR, \fIargv\fR, \fIargv0\fR, and
.PP
When it has finished its own initialization, but before it processes
commands, \fBTcl_Main\fR calls the procedure given by the
-\fIappInitProc\fR argument. This procedure provides a ``hook'' for
-the application to perform its own initialization of the interpreter
+\fIappInitProc\fR argument. This procedure provides a
+.QW hook
+for the application to perform its own initialization of the interpreter
created by \fBTcl_Main\fR, such as defining application-specific
commands. The procedure must have an interface that matches the
type \fBTcl_AppInitProc\fR:
@@ -114,7 +120,6 @@ The prompts and command evaluation results are written to the standard
output channel only if the Tcl variable \fItcl_interactive\fR in the
master interpreter holds a non-zero integer value.
.PP
-.VS 8.4
\fBTcl_SetMainLoop\fR allows setting an event loop procedure to be run.
This allows, for example, Tk to be dynamically loaded and set its event
loop. The event loop will run following the startup script. If you
@@ -127,7 +132,6 @@ The main loop procedure must have an interface that matches the type
.CS
typedef void Tcl_MainLoopProc(void);
.CE
-.VE 8.4
.PP
\fBTcl_Main\fR does not return. Normally a program based on
\fBTcl_Main\fR will terminate when the \fBexit\fR command is
diff --git a/doc/Thread.3 b/doc/Thread.3
index 2ffd6ef..80d34ad 100644
--- a/doc/Thread.3
+++ b/doc/Thread.3
@@ -9,7 +9,7 @@
.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_JoinThread \- Tcl thread support.
+Tcl_ConditionNotify, Tcl_ConditionWait, Tcl_ConditionFinalize, Tcl_GetThreadData, Tcl_MutexLock, Tcl_MutexUnlock, Tcl_MutexFinalize, Tcl_CreateThread, Tcl_JoinThread \- Tcl thread support
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
@@ -41,14 +41,14 @@ int
int
\fBTcl_JoinThread\fR(\fIid, result\fR)
.SH ARGUMENTS
-.AS Tcl_ThreadDataKey *keyPtr
+.AS Tcl_CreateThreadProc threadProc out
.AP Tcl_Condition *condPtr in
A condition variable, which must be associated with a mutex lock.
.AP Tcl_Mutex *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.
+Note that a polling value of 0 seconds does not 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
@@ -80,42 +80,38 @@ waited upon into it.
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
+you must include the \fB\-\|\-enable-threads\fR option to \fBconfigure\fR
when you configure and compile your Tcl core.
.PP
An important constraint 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
+the same Tcl interpreter. (However, a single thread can safely create
+and use multiple interpreters.)
+.SH DESCRIPTION
+Tcl provides \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
+for the new thread. As for the flags, currently only the values
+\fBTCL_THREAD_NOFLAGS\fR and \fBTCL_THREAD_JOINABLE\fR are defined. The
first of them invokes the default behaviour with no
specialties. 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
+Restrictions: On some UNIX systems the pthread-library does not
+contain the functionality to specify the stack size of a thread. The
+specified value for the stack size is ignored on these systems.
+Windows currently does not support joinable threads. This
+flag value is therefore ignored on this platform.
.PP
-Tcl does provide \fBTcl_ExitThread\fR and \fBTcl_FinalizeThread\fR
+Tcl provides the \fBTcl_ExitThread\fR and \fBTcl_FinalizeThread\fR functions
for terminating threads and invoking optional per-thread exit
handlers. See the \fBTcl_Exit\fR page for more information on these
procedures.
.PP
-.VS
The \fBTcl_JoinThread\fR function is provided to allow threads to wait
upon the exit of another thread, which must have been marked as
joinable through usage of the \fBTCL_THREAD_JOINABLE\fR-flag during
@@ -127,36 +123,29 @@ thread which already exited is possible, the system will retain the
necessary information until after the call to \fBTcl_JoinThread\fR.
This means that not calling \fBTcl_JoinThread\fR for a joinable thread
will cause a memory leak.
-.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.
+.SS "SYNCHRONIZATION AND COMMUNICATION"
Tcl provides \fBTcl_ThreadQueueEvent\fR and \fBTcl_ThreadAlert\fR
-for handling event queueing in multithreaded applications. See
+for handling event queuing 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
-or use the Tcl "Threading Extension" 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.
For declaration of mutexes the \fBTCL_DECLARE_MUTEX\fR macro should be used.
This macro assures correct mutex handling even when the core is compiled
-without threads enabled.
+without 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
@@ -174,40 +163,33 @@ 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
+.SS INITIALIZATION
.PP
-All of these synchronization objects are self initializing.
+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 "SCRIPT-LEVEL ACCESS TO THREADS"
+.VS 8.5
+Tcl provides no built-in commands for scripts to use to create,
+manage, or join threads, nor any script-level access to mutex or
+condition variables. It provides such facilities only via C
+interfaces, and leaves it up to packages to expose these matters to
+the script level. One such package is the \fBThread\fR package.
+.VE 8.5
.SH "SEE ALSO"
-Tcl_GetCurrentThread, Tcl_ThreadQueueEvent, Tcl_ThreadAlert,
-Tcl_ExitThread, Tcl_FinalizeThread,
-Tcl_CreateThreadExitHandler, Tcl_DeleteThreadExitHandler
+Tcl_GetCurrentThread(3), Tcl_ThreadQueueEvent(3), Tcl_ThreadAlert(3),
+Tcl_ExitThread(3), Tcl_FinalizeThread(3), Tcl_CreateThreadExitHandler(3),
+Tcl_DeleteThreadExitHandler(3), Thread
.SH KEYWORDS
thread, mutex, condition variable, thread local storage
diff --git a/doc/ToUpper.3 b/doc/ToUpper.3
index ece0fb2..d6b3006 100644
--- a/doc/ToUpper.3
+++ b/doc/ToUpper.3
@@ -8,7 +8,7 @@
.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.
+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 <tcl.h>\fR
diff --git a/doc/TraceCmd.3 b/doc/TraceCmd.3
index 5c84249..020f1ca 100644
--- a/doc/TraceCmd.3
+++ b/doc/TraceCmd.3
@@ -25,10 +25,11 @@ void
.AS Tcl_CommandTraceProc prevClientData
.AP Tcl_Interp *interp in
Interpreter containing the command.
-.AP "CONST char" *cmdName in
+.AP "const char" *cmdName in
Name of command.
.AP int flags in
-OR-ed collection of the value TCL_TRACE_RENAME and TCL_TRACE_DELETE.
+OR'ed collection of the values \fBTCL_TRACE_RENAME\fR and
+\fBTCL_TRACE_DELETE\fR.
.AP Tcl_CommandTraceProc *proc in
Procedure to call when specified operations occur to \fIcmdName\fR.
.AP ClientData clientData in
@@ -38,19 +39,18 @@ If non-NULL, gives last value returned by \fBTcl_CommandTraceInfo\fR,
so this call will return information about next trace. If NULL, this
call will return information about first trace.
.BE
-
.SH DESCRIPTION
.PP
\fBTcl_TraceCommand\fR allows a C procedure to monitor operations
performed on a Tcl command, so that the C procedure is invoked
whenever the command is renamed or deleted. If the trace is created
-successfully then \fBTcl_TraceCommand\fR returns TCL_OK. If an error
+successfully then \fBTcl_TraceCommand\fR returns \fBTCL_OK\fR. If an error
occurred (e.g. \fIcmdName\fR specifies a non-existent command) then
-TCL_ERROR is returned and an error message is left in the
+\fBTCL_ERROR\fR is returned and an error message is left in the
interpreter's result.
.PP
The \fIflags\fR argument to \fBTcl_TraceCommand\fR indicates when the
-trace procedure is to be invoked. It consists of an OR-ed combination
+trace procedure is to be invoked. It consists of an OR'ed combination
of any of the following values:
.TP
\fBTCL_TRACE_RENAME\fR
@@ -64,10 +64,10 @@ Whenever one of the specified operations occurs to the command,
match the type \fBTcl_CommandTraceProc\fR:
.CS
typedef void Tcl_CommandTraceProc(
- ClientData \fIclientData\fR,
+ ClientData \fIclientData\fR,
Tcl_Interp *\fIinterp\fR,
- CONST char *\fIoldName\fR,
- CONST char *\fInewName\fR,
+ const char *\fIoldName\fR,
+ const char *\fInewName\fR,
int \fIflags\fR);
.CE
The \fIclientData\fR and \fIinterp\fR parameters will have the same
@@ -77,17 +77,17 @@ data structure that describes what to do when \fIproc\fR is invoked.
\fIOldName\fR gives the name of the command being renamed, and
\fInewName\fR gives the name that the command is being renamed to (or
an empty string or NULL when the command is being deleted.)
-\fIFlags\fR is an OR-ed combination of bits potentially providing
-several pieces of information. One of the bits TCL_TRACE_RENAME and
-TCL_TRACE_DELETE will be set in \fIflags\fR to indicate which
+\fIFlags\fR is an OR'ed combination of bits potentially providing
+several pieces of information. One of the bits \fBTCL_TRACE_RENAME\fR and
+\fBTCL_TRACE_DELETE\fR will be set in \fIflags\fR to indicate which
operation is being performed on the command. The bit
-TCL_TRACE_DESTROYED will be set in \fIflags\fR if the trace is about
+\fBTCL_TRACE_DESTROYED\fR will be set in \fIflags\fR if the trace is about
to be destroyed; this information may be useful to \fIproc\fR so that
it can clean up its own internal data structures (see the section
-TCL_TRACE_DESTROYED below for more details). Lastly, the bit
-TCL_INTERP_DESTROYED will be set if the entire interpreter is being
+\fBTCL_TRACE_DESTROYED\fR below for more details). Lastly, the bit
+\fBTCL_INTERP_DESTROYED\fR will be set if the entire interpreter is being
destroyed. When this bit is set, \fIproc\fR must be especially
-careful in the things it does (see the section TCL_INTERP_DESTROYED
+careful in the things it does (see the section \fBTCL_INTERP_DESTROYED\fR
below).
.PP
\fBTcl_UntraceCommand\fR may be used to remove a trace. If the
@@ -109,7 +109,7 @@ argument.
If the \fIprevClientData\fR argument is NULL then the return
value corresponds to the first (most recently created) matching
trace, or NULL if there are no matching traces.
-If the \fIprevClientData\fR argument isn't NULL, then it should
+If the \fIprevClientData\fR argument is not NULL, then it should
be the return value from a previous call to \fBTcl_CommandTraceInfo\fR.
In this case, the new return value will correspond to the next
matching trace after the one whose \fIclientData\fR matches
@@ -117,15 +117,13 @@ matching trace after the one whose \fIclientData\fR matches
or if there are no more matching traces after it.
This mechanism makes it possible to step through all of the
traces for a given command that have the same \fIproc\fR.
-
.SH "CALLING COMMANDS DURING TRACES"
.PP
During rename traces, the command being renamed is visible with both
names simultaneously, and the command still exists during delete
-traces (if TCL_INTERP_DESTROYED is not set). However, there is no
+traces (if \fBTCL_INTERP_DESTROYED\fR is not set). However, there is no
mechanism for signaling that an error occurred in a trace procedure,
so great care should be taken that errors do not get silently lost.
-
.SH "MULTIPLE TRACES"
.PP
It is possible for multiple traces to exist on the same command.
@@ -137,32 +135,27 @@ If the command being renamed is renamed by one of its rename traces,
that renaming takes precedence over the one that triggered the trace
and the collection of traces will not be reexecuted; if several traces
rename the command, the last renaming takes precedence.
-
.SH "TCL_TRACE_DESTROYED FLAG"
.PP
-In a delete callback to \fIproc\fR, the TCL_TRACE_DESTROYED bit
+In a delete callback to \fIproc\fR, the \fBTCL_TRACE_DESTROYED\fR bit
is set in \fIflags\fR.
-
-'\" Perhaps need some more comments here? - DKF
-
+.\" Perhaps need some more comments here? - DKF
.SH "TCL_INTERP_DESTROYED"
.PP
When an interpreter is destroyed, unset traces are called for
all of its commands.
-The TCL_INTERP_DESTROYED bit will be set in the \fIflags\fR
+The \fBTCL_INTERP_DESTROYED\fR bit will be set in the \fIflags\fR
argument passed to the trace procedures.
Trace procedures must be extremely careful in what they do if
-the TCL_INTERP_DESTROYED bit is set.
+the \fBTCL_INTERP_DESTROYED\fR bit is set.
It is not safe for the procedures to invoke any Tcl procedures
on the interpreter, since its state is partially deleted.
All that trace procedures should do under these circumstances is
to clean up and free their own internal data structures.
-
.SH BUGS
.PP
-Tcl doesn't do any error checking to prevent trace procedures
-from misusing the interpreter during traces with TCL_INTERP_DESTROYED
+Tcl does not do any error checking to prevent trace procedures
+from misusing the interpreter during traces with \fBTCL_INTERP_DESTROYED\fR
set.
-
.SH KEYWORDS
clientData, trace, command
diff --git a/doc/TraceVar.3 b/doc/TraceVar.3
index 98b242e..f80d86f 100644
--- a/doc/TraceVar.3
+++ b/doc/TraceVar.3
@@ -33,23 +33,24 @@ ClientData
.AS Tcl_VarTraceProc prevClientData
.AP Tcl_Interp *interp in
Interpreter containing variable.
-.AP "CONST char" *varName in
+.AP "const char" *varName in
Name of variable. May refer to a scalar variable, to
an array variable with no index, or to an array variable
with a parenthesized index.
.AP int flags in
-OR-ed combination of the values TCL_TRACE_READS, TCL_TRACE_WRITES,
-TCL_TRACE_UNSETS, TCL_TRACE_ARRAY, TCL_GLOBAL_ONLY, TCL_NAMESPACE_ONLY,
-TCL_TRACE_RESULT_DYNAMIC and TCL_TRACE_RESULT_OBJECT.
+OR-ed combination of the values \fBTCL_TRACE_READS\fR,
+\fBTCL_TRACE_WRITES\fR, \fBTCL_TRACE_UNSETS\fR, \fBTCL_TRACE_ARRAY\fR,
+\fBTCL_GLOBAL_ONLY\fR, \fBTCL_NAMESPACE_ONLY\fR,
+\fBTCL_TRACE_RESULT_DYNAMIC\fR and \fBTCL_TRACE_RESULT_OBJECT\fR.
Not all flags are used by all
procedures. See below for more information.
.AP Tcl_VarTraceProc *proc in
Procedure to invoke whenever one of the traced operations occurs.
.AP ClientData clientData in
Arbitrary one-word value to pass to \fIproc\fR.
-.AP "CONST char" *name1 in
+.AP "const char" *name1 in
Name of scalar or array variable (without array index).
-.AP "CONST char" *name2 in
+.AP "const char" *name2 in
For a trace on an element of an array, gives the index of the
element. For traces on scalar variables or on whole arrays,
is NULL.
@@ -59,15 +60,14 @@ If non-NULL, gives last value returned by \fBTcl_VarTraceInfo\fR or
next trace. If NULL, this call will return information about first
trace.
.BE
-
.SH DESCRIPTION
.PP
\fBTcl_TraceVar\fR allows a C procedure to monitor and control
access to a Tcl variable, so that the C procedure is invoked
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
+\fBTCL_OK\fR. If an error occurred (e.g. \fIvarName\fR specifies an element
+of an array, but the actual variable is not an array) then \fBTCL_ERROR\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
@@ -103,21 +103,19 @@ 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.
-.VS 8.4
.TP
\fBTCL_TRACE_RESULT_DYNAMIC\fR
The result of invoking the \fIproc\fR is a dynamically allocated
string that will be released by the Tcl library via a call to
\fBckfree\fR. Must not be specified at the same time as
-TCL_TRACE_RESULT_OBJECT.
+\fBTCL_TRACE_RESULT_OBJECT\fR.
.TP
\fBTCL_TRACE_RESULT_OBJECT\fR
The result of invoking the \fIproc\fR is a Tcl_Obj* (cast to a char*)
with a reference count of at least one. The ownership of that
reference will be transferred to the Tcl core for release (when the
core has finished with it) via a call to \fBTcl_DecrRefCount\fR. Must
-not be specified at the same time as TCL_TRACE_RESULT_DYNAMIC.
-.VE 8.4
+not be specified at the same time as \fBTCL_TRACE_RESULT_DYNAMIC\fR.
.PP
Whenever one of the specified operations occurs on the variable,
\fIproc\fR will be invoked.
@@ -125,11 +123,11 @@ It should have arguments and result that match the type
\fBTcl_VarTraceProc\fR:
.CS
typedef char *Tcl_VarTraceProc(
- ClientData \fIclientData\fR,
- Tcl_Interp *\fIinterp\fR,
- char *\fIname1\fR,
- char *\fIname2\fR,
- int \fIflags\fR);
+ ClientData \fIclientData\fR,
+ Tcl_Interp *\fIinterp\fR,
+ char *\fIname1\fR,
+ char *\fIname2\fR,
+ int \fIflags\fR);
.CE
The \fIclientData\fR and \fIinterp\fR parameters will
have the same values as those passed to \fBTcl_TraceVar\fR when the
@@ -142,30 +140,30 @@ 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, TCL_TRACE_ARRAY,
-or TCL_TRACE_UNSETS
+One of the bits \fBTCL_TRACE_READS\fR, \fBTCL_TRACE_WRITES\fR,
+\fBTCL_TRACE_ARRAY\fR, or \fBTCL_TRACE_UNSETS\fR
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
+The bit \fBTCL_GLOBAL_ONLY\fR will be set whenever the variable being
accessed is a global one not accessible from the current level of
procedure call: the trace procedure will need to pass this flag
back to variable-related procedures like \fBTcl_GetVar\fR if it
attempts to access the variable.
-The bit TCL_NAMESPACE_ONLY will be set whenever the variable being
+The bit \fBTCL_NAMESPACE_ONLY\fR will be set whenever the variable being
accessed is a namespace one not accessible from the current level of
procedure call: the trace procedure will need to pass this flag
back to variable-related procedures like \fBTcl_GetVar\fR if it
attempts to access the variable.
-The bit TCL_TRACE_DESTROYED will be set in \fIflags\fR if the trace is
+The bit \fBTCL_TRACE_DESTROYED\fR will be set in \fIflags\fR if the trace is
about to be destroyed; this information may be useful to \fIproc\fR
so that it can clean up its own internal data structures (see
-the section TCL_TRACE_DESTROYED below for more details).
-Lastly, the bit TCL_INTERP_DESTROYED will be set if the entire
+the section \fBTCL_TRACE_DESTROYED\fR below for more details).
+Lastly, the bit \fBTCL_INTERP_DESTROYED\fR will be set if the entire
interpreter is being destroyed.
When this bit is set, \fIproc\fR must be especially careful in
-the things it does (see the section TCL_INTERP_DESTROYED below).
+the things it does (see the section \fBTCL_INTERP_DESTROYED\fR below).
The trace procedure's return value should normally be NULL; see
-ERROR RETURNS below for information on other possibilities.
+\fBERROR RETURNS\fR below for information on other possibilities.
.PP
\fBTcl_UntraceVar\fR may be used to remove a trace.
If the variable specified by \fIinterp\fR, \fIvarName\fR, and \fIflags\fR
@@ -180,14 +178,14 @@ traces set on a given variable.
The return value from \fBTcl_VarTraceInfo\fR is the \fIclientData\fR
associated with a particular trace.
The trace must be on the variable specified by the \fIinterp\fR,
-\fIvarName\fR, and \fIflags\fR arguments (only the TCL_GLOBAL_ONLY and
-TCL_NAMESPACE_ONLY bits from \fIflags\fR is used; other bits are
+\fIvarName\fR, and \fIflags\fR arguments (only the \fBTCL_GLOBAL_ONLY\fR and
+\fBTCL_NAMESPACE_ONLY\fR bits from \fIflags\fR is used; other bits are
ignored) and its trace procedure must the same as the \fIproc\fR
argument.
If the \fIprevClientData\fR argument is NULL then the return
value corresponds to the first (most recently created) matching
trace, or NULL if there are no matching traces.
-If the \fIprevClientData\fR argument isn't NULL, then it should
+If the \fIprevClientData\fR argument is not NULL, then it should
be the return value from a previous call to \fBTcl_VarTraceInfo\fR.
In this case, the new return value will correspond to the next
matching trace after the one whose \fIclientData\fR matches
@@ -195,7 +193,6 @@ matching trace after the one whose \fIclientData\fR matches
or if there are no more matching traces after it.
This mechanism makes it possible to step through all of the
traces for a given variable that have the same \fIproc\fR.
-
.SH "TWO-PART NAMES"
.PP
The procedures \fBTcl_TraceVar2\fR, \fBTcl_UntraceVar2\fR, and
@@ -204,7 +201,6 @@ 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.
-.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
@@ -213,14 +209,10 @@ 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 \fIname2\fR is NULL and \fIname1\fR does not refer
-to an array element
-.VE
-it means that either the variable is
+to an array element 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, write, and array traces, the
@@ -246,7 +238,6 @@ from the variable before any trace procedures are invoked.
If new traces are set by unset trace procedures, these traces
will be invoked on accesses to the variable by the trace
procedures.
-
.SH "CALLBACK TIMING"
.PP
When read tracing has been specified for a variable, the trace
@@ -286,7 +277,6 @@ 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
completely unset.
-
.SH "WHOLE-ARRAY TRACES"
.PP
If a call to \fBTcl_TraceVar\fR or \fBTcl_TraceVar2\fR specifies
@@ -299,7 +289,6 @@ When an array is unset, a whole-array trace will be invoked
just once, with \fIname1\fR equal to the name of the array
and \fIname2\fR NULL; it will not be invoked once for each
element.
-
.SH "MULTIPLE TRACES"
.PP
It is possible for multiple traces to exist on the same variable.
@@ -311,7 +300,6 @@ before the individual-element traces.
If a read or write trace unsets the variable then all of the unset
traces will be invoked but the remainder of the read and write traces
will be skipped.
-
.SH "ERROR RETURNS"
.PP
Under normal conditions trace procedures should return NULL, indicating
@@ -320,13 +308,11 @@ If \fIproc\fR returns a non-NULL value it signifies that an
error occurred.
The return value must be a pointer to a static character string
containing an error message,
-.VS 8.4
-unless (\fIexactly\fR one of) the TCL_TRACE_RESULT_DYNAMIC and
-TCL_TRACE_RESULT_OBJECT flags is set, which specify that the result is
+unless (\fIexactly\fR one of) the \fBTCL_TRACE_RESULT_DYNAMIC\fR and
+\fBTCL_TRACE_RESULT_OBJECT\fR flags is set, which specify that the result is
either a dynamic string (to be released with \fBckfree\fR) or a
Tcl_Obj* (cast to char* and to be released with
\fBTcl_DecrRefCount\fR) containing the error message.
-.VE 8.4
If a trace procedure returns an error, no further traces are
invoked for the access and the traced access aborts with the
given message.
@@ -340,56 +326,51 @@ The return value from \fIproc\fR is only used during read and
write tracing.
During unset traces, the return value is ignored and all relevant
trace procedures will always be invoked.
-
.SH "RESTRICTIONS"
.PP
A trace procedure can be called at any time, even when there
-is a partially-formed result in the interpreter's result area. If
+is a partially formed result in the interpreter's result area. If
the trace procedure does anything that could damage this result (such
as calling \fBTcl_Eval\fR) then it must save the original values of
the interpreter's \fBresult\fR and \fBfreeProc\fR fields and restore
them before it returns.
-
.SH "UNDEFINED VARIABLES"
.PP
It is legal to set a trace on an undefined variable.
The variable will still appear to be undefined until the
first time its value is set.
If an undefined variable is traced and then unset, the unset will fail
-with an error (``no such variable''), but the trace
-procedure will still be invoked.
-
+with an error
+.PQ "no such variable" "" ,
+but the trace procedure will still be invoked.
.SH "TCL_TRACE_DESTROYED FLAG"
.PP
-In an unset callback to \fIproc\fR, the TCL_TRACE_DESTROYED bit
+In an unset callback to \fIproc\fR, the \fBTCL_TRACE_DESTROYED\fR bit
is set in \fIflags\fR if the trace is being removed as part
of the deletion.
Traces on a variable are always removed whenever the variable
-is deleted; the only time TCL_TRACE_DESTROYED isn't set is for
+is deleted; the only time \fBTCL_TRACE_DESTROYED\fR is not set is for
a whole-array trace invoked when only a single element of an
array is unset.
-
.SH "TCL_INTERP_DESTROYED"
.PP
When an interpreter is destroyed, unset traces are called for
all of its variables.
-The TCL_INTERP_DESTROYED bit will be set in the \fIflags\fR
+The \fBTCL_INTERP_DESTROYED\fR bit will be set in the \fIflags\fR
argument passed to the trace procedures.
Trace procedures must be extremely careful in what they do if
-the TCL_INTERP_DESTROYED bit is set.
+the \fBTCL_INTERP_DESTROYED\fR bit is set.
It is not safe for the procedures to invoke any Tcl procedures
on the interpreter, since its state is partially deleted.
All that trace procedures should do under these circumstances is
to clean up and free their own internal data structures.
-
.SH BUGS
.PP
-Tcl doesn't do any error checking to prevent trace procedures
-from misusing the interpreter during traces with TCL_INTERP_DESTROYED
+Tcl does not do any error checking to prevent trace procedures
+from misusing the interpreter during traces with \fBTCL_INTERP_DESTROYED\fR
set.
.PP
-Array traces are not yet integrated with the Tcl "info exists" command,
+Array traces are not yet integrated with the Tcl \fBinfo exists\fR command,
nor is there Tcl-level access to array traces.
-
.SH KEYWORDS
clientData, trace, variable
diff --git a/doc/Translate.3 b/doc/Translate.3
index 59a64ea..d434cda 100644
--- a/doc/Translate.3
+++ b/doc/Translate.3
@@ -17,11 +17,12 @@ Tcl_TranslateFileName \- convert file name to native form and replace tilde with
char *
\fBTcl_TranslateFileName\fR(\fIinterp\fR, \fIname\fR, \fIbufferPtr\fR)
.SH ARGUMENTS
-.AS Tcl_DString *bufferPtr
+.AS Tcl_DString *bufferPtr in/out
.AP Tcl_Interp *interp in
Interpreter in which to report an error, if any.
-.AP "CONST char" *name in
-File name, which may start with a ``~''.
+.AP "const char" *name in
+File name, which may start with a
+.QW ~ .
.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 free. The
@@ -31,9 +32,18 @@ anything stored here.
.SH DESCRIPTION
.PP
-This utility procedure translates a file name to a form suitable for
-passing to the local operating system. It converts network names into
-native form and does tilde substitution.
+This utility procedure translates a file name to a platform-specific form
+which, after being converted to the appropriate encoding, is suitable for
+passing to the local operating system. In particular, it converts
+network names into native form and does tilde substitution.
+.PP
+However, with the advent of the newer \fBTcl_FSGetNormalizedPath\fR and
+\fBTcl_GetNativePath\fR, there is no longer any need to use this
+procedure. In particular, \fBTcl_GetNativePath\fR performs all the
+necessary translation and encoding conversion, is virtual-filesystem
+aware, and caches the native result for faster repeated calls.
+Finally \fBTcl_GetNativePath\fR does not require you to free anything
+afterwards.
.PP
If
\fBTcl_TranslateFileName\fR has to do tilde substitution or translate
@@ -44,7 +54,7 @@ After \fBTcl_TranslateFileName\fR returns a non-NULL result, the caller must
eventually invoke \fBTcl_DStringFree\fR to free any information
placed in \fI*bufferPtr\fR. The caller need not know whether or
not \fBTcl_TranslateFileName\fR actually used the string; \fBTcl_TranslateFileName\fR
-initializes \fI*bufferPtr\fR even if it doesn't use it, so the call to
+initializes \fI*bufferPtr\fR even if it does not use it, so the call to
\fBTcl_DStringFree\fR will be safe in either case.
.PP
If an error occurs (e.g. because there was no user by the given
diff --git a/doc/UniCharIsAlpha.3 b/doc/UniCharIsAlpha.3
index 22b81c1..6029b2d 100644
--- a/doc/UniCharIsAlpha.3
+++ b/doc/UniCharIsAlpha.3
@@ -46,6 +46,7 @@ int
int
\fBTcl_UniCharIsWordChar\fR(\fIch\fR)
.SH ARGUMENTS
+.AS int ch
.AP int ch in
The Tcl_UniChar to be examined.
.BE
@@ -61,7 +62,7 @@ with the various routines.
Note: A Tcl_UniChar is a Unicode character represented as an unsigned,
fixed-size quantity.
-.SH CHARACTER CLASSES
+.SH "CHARACTER CLASSES"
.PP
\fBTcl_UniCharIsAlnum\fR tests if the character is an alphanumeric Unicode character.
.PP
diff --git a/doc/UpVar.3 b/doc/UpVar.3
index 95c4a9a..f1e6fe4 100644
--- a/doc/UpVar.3
+++ b/doc/UpVar.3
@@ -20,30 +20,31 @@ int
int
\fBTcl_UpVar2(\fIinterp, frameName, name1, name2, destName, flags\fB)\fR
.SH ARGUMENTS
-.AS Tcl_VarTraceProc prevClientData
+.AS "const char" *sourceName
.AP Tcl_Interp *interp in
Interpreter containing variables; also used for error reporting.
-.AP "CONST char" *frameName in
+.AP "const char" *frameName in
Identifies the stack frame containing source variable.
May have any of the forms accepted by
the \fBupvar\fR command, such as \fB#0\fR or \fB1\fR.
-.AP "CONST char" *sourceName in
+.AP "const char" *sourceName in
Name of source variable, in the frame given by \fIframeName\fR.
May refer to a scalar variable or to an array variable with a
parenthesized index.
-.AP "CONST char" *destName in
+.AP "const char" *destName in
Name of destination variable, which is to be linked to source
variable so that references to \fIdestName\fR
refer to the other variable. Must not currently exist except as
an upvar-ed variable.
.AP int flags in
-Either TCL_GLOBAL_ONLY or 0; if non-zero, then \fIdestName\fR is
-a global variable; otherwise it is a local to the current procedure
-(or global if no procedure is active).
-.AP "CONST char" *name1 in
+One of \fBTCL_GLOBAL_ONLY\fR, \fBTCL_NAMESPACE_ONLY\fR or 0; if non-zero,
+then \fIdestName\fR is a global or namespace variable; otherwise it is
+local to the current procedure (or current namespace if no procedure is
+active).
+.AP "const char" *name1 in
First part of source variable's name (scalar name, or name of array
without array index).
-.AP "CONST char" *name2 in
+.AP "const char" *name2 in
If source variable is an element of an array, gives the index of the element.
For scalar source variables, is NULL.
.BE
@@ -61,7 +62,7 @@ element name (by calling \fBTcl_UpVar2\fR).
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
+Both procedures return either \fBTCL_OK\fR or \fBTCL_ERROR\fR, and they
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;
diff --git a/doc/Utf.3 b/doc/Utf.3
index af472ae..8e39fef 100644
--- a/doc/Utf.3
+++ b/doc/Utf.3
@@ -8,7 +8,7 @@
.TH Utf 3 "8.1" Tcl "Tcl Library Procedures"
.BS
.SH NAME
-Tcl_UniChar, Tcl_UniCharCaseMatch, Tcl_UniCharNcasecmp, 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.
+Tcl_UniChar, Tcl_UniCharCaseMatch, Tcl_UniCharNcasecmp, 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 <tcl.h>\fR
@@ -20,91 +20,91 @@ int
.sp
int
\fBTcl_UtfToUniChar\fR(\fIsrc, chPtr\fR)
-.VS 8.4
.sp
char *
-\fBTcl_UniCharToUtfDString\fR(\fIuniStr, numChars, dstPtr\fR)
+\fBTcl_UniCharToUtfDString\fR(\fIuniStr, uniLength, dsPtr\fR)
.sp
Tcl_UniChar *
-\fBTcl_UtfToUniCharDString\fR(\fIsrc, len, dstPtr\fR)
-.VE 8.4
+\fBTcl_UtfToUniCharDString\fR(\fIsrc, length, dsPtr\fR)
.sp
int
\fBTcl_UniCharLen\fR(\fIuniStr\fR)
.sp
int
-\fBTcl_UniCharNcmp\fR(\fIuniStr, uniStr, num\fR)
-.VS 8.4
+\fBTcl_UniCharNcmp\fR(\fIucs, uct, numChars\fR)
.sp
int
-\fBTcl_UniCharNcasecmp\fR(\fIuniStr, uniStr, num\fR)
+\fBTcl_UniCharNcasecmp\fR(\fIucs, uct, numChars\fR)
.sp
int
\fBTcl_UniCharCaseMatch\fR(\fIuniStr, uniPattern, nocase\fR)
-.VE 8.4
.sp
int
-\fBTcl_UtfNcmp\fR(\fIsrc, src, num\fR)
+\fBTcl_UtfNcmp\fR(\fIcs, ct, numChars\fR)
.sp
int
-\fBTcl_UtfNcasecmp\fR(\fIsrc, src, num\fR)
+\fBTcl_UtfNcasecmp\fR(\fIcs, ct, numChars\fR)
.sp
int
-\fBTcl_UtfCharComplete\fR(\fIsrc, len\fR)
+\fBTcl_UtfCharComplete\fR(\fIsrc, length\fR)
.sp
int
-\fBTcl_NumUtfChars\fR(\fIsrc, len\fR)
-.VS 8.4
+\fBTcl_NumUtfChars\fR(\fIsrc, length\fR)
.sp
-CONST char *
+const char *
\fBTcl_UtfFindFirst\fR(\fIsrc, ch\fR)
.sp
-CONST char *
+const char *
\fBTcl_UtfFindLast\fR(\fIsrc, ch\fR)
.sp
-CONST char *
+const char *
\fBTcl_UtfNext\fR(\fIsrc\fR)
.sp
-CONST char *
+const char *
\fBTcl_UtfPrev\fR(\fIsrc, start\fR)
-.VE 8.4
.sp
Tcl_UniChar
\fBTcl_UniCharAtIndex\fR(\fIsrc, index\fR)
-.VS 8.4
.sp
-CONST char *
+const char *
\fBTcl_UtfAtIndex\fR(\fIsrc, index\fR)
-.VE 8.4
.sp
int
\fBTcl_UtfBackslash\fR(\fIsrc, readPtr, dst\fR)
.SH ARGUMENTS
-.AS "CONST Tcl_UniChar" numChars in/out
+.AS "const Tcl_UniChar" *uniPattern 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.
+\fBTCL_UTF_MAX\fR 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
+.AP "const char" *src in
Pointer to a UTF-8 string.
-.AP "CONST Tcl_UniChar" *uniStr in
+.AP "const char" *cs in
+Pointer to a UTF-8 string.
+.AP "const char" *ct in
+Pointer to a UTF-8 string.
+.AP "const Tcl_UniChar" *uniStr in
+A null-terminated Unicode string.
+.AP "const Tcl_UniChar" *ucs in
+A null-terminated Unicode string.
+.AP "const Tcl_UniChar" *uct in
A null-terminated Unicode string.
-.AP "CONST Tcl_UniChar" *uniPattern in
+.AP "const Tcl_UniChar" *uniPattern in
A null-terminated Unicode string.
-.AP int len in
+.AP int length 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
+.AP int uniLength 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
+.AP "Tcl_DString" *dsPtr in/out
+A pointer to a previously initialized \fBTcl_DString\fR.
+.AP "unsigned long" numChars in
The number of characters to compare.
-.AP "CONST char" *start in
+.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.
@@ -113,12 +113,10 @@ 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.
-.VS 8.4
+At most \fBTCL_UTF_MAX\fR bytes are stored in the buffer.
.AP int nocase in
Specifies whether the match should be done case-sensitive (0) or
case-insensitive (1).
-.VE 8.4
.BE
.SH DESCRIPTION
@@ -126,7 +124,7 @@ case-insensitive (1).
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
+a varying-length sequence of up to \fBTCL_UTF_MAX\fR 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
@@ -138,7 +136,7 @@ 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
+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
@@ -147,15 +145,17 @@ 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.
+to UTF-8, storing the result in a previously initialized \fBTcl_DString\fR.
+You must specify \fIuniLength\fR, 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 converts 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",
+storing the result in the previously initialized \fBTcl_DString\fR.
+In the argument \fIlength\fR, you may either specify the length of
+the given UTF-8 string in bytes or
+.QW \-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
@@ -168,24 +168,22 @@ the number of Unicode characters (not bytes) in that string.
.PP
\fBTcl_UniCharNcmp\fR and \fBTcl_UniCharNcasecmp\fR correspond to
\fBstrncmp\fR and \fBstrncasecmp\fR, respectively, for Unicode characters.
-They accepts two null-terminated Unicode strings and the number of characters
-to compare. Both strings are assumed to be at least \fIlen\fR characters
+They accept two null-terminated Unicode strings and the number of characters
+to compare. Both strings are assumed to be at least \fInumChars\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. \fBTcl_UniCharNcasecmp\fR
is the Unicode case insensitive version.
.PP
-.VS 8.4
\fBTcl_UniCharCaseMatch\fR is the Unicode equivalent to
\fBTcl_StringCaseMatch\fR. It accepts a null-terminated Unicode string,
a Unicode pattern, and a boolean value specifying whether the match should
be case sensitive and returns whether the string matches the pattern.
-.VE 8.4
.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
+to compare. (Both strings are assumed to be at least \fInumChars\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
@@ -198,7 +196,7 @@ 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
+of \fIlength\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
@@ -206,7 +204,7 @@ 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
+\fIsrc\fR. The length of the source string is \fIlength\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
@@ -248,7 +246,7 @@ the return pointer points to the first character in the source string.
\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.
+buffer \fIdst\fR. At most \fBTCL_UTF_MAX\fR 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.
diff --git a/doc/WrongNumArgs.3 b/doc/WrongNumArgs.3
index 00aa653..2175858 100644
--- a/doc/WrongNumArgs.3
+++ b/doc/WrongNumArgs.3
@@ -15,16 +15,16 @@ Tcl_WrongNumArgs \- generate standard error message for wrong number of argument
.sp
\fBTcl_WrongNumArgs\fR(\fIinterp, objc, objv, message\fR)
.SH ARGUMENTS
-.AS Tcl_Interp "*CONST objv[]"
+.AS "Tcl_Obj *const" *message
.AP Tcl_Interp interp in
Interpreter in which error will be reported: error message gets stored
in its result object.
.AP int objc in
Number of leading arguments from \fIobjv\fR to include in error
message.
-.AP Tcl_Obj "*CONST\ objv[]" in
+.AP "Tcl_Obj *const" objv[] in
Arguments to command that had the wrong number of arguments.
-.AP "CONST char" *message in
+.AP "const char" *message in
Additional error information to print after leading arguments
from \fIobjv\fR. This typically gives the acceptable syntax
of the command. This argument may be NULL.
@@ -39,7 +39,8 @@ standard error message and stores it in the result object of
\fIinterp\fR. The message includes the \fIobjc\fR initial
elements of \fIobjv\fR plus \fImessage\fR. For example, if
\fIobjv\fR consists of the values \fBfoo\fR and \fBbar\fR,
-\fIobjc\fR is 1, and \fImessage\fR is ``\fBfileName count\fR''
+\fIobjc\fR is 1, and \fImessage\fR is
+.QW "\fBfileName count\fR"
then \fIinterp\fR's result object will be set to the following
string:
.CS
@@ -61,7 +62,7 @@ subcommand we would like to use the full subcommand name rather than
the abbreviation. If the \fBTcl_WrongNumArgs\fR command finds any
\fIindexObjects\fR in the \fIobjv\fR array it will use the full subcommand
name in the error message instead of the abbreviated name that was
-originally passed in. Using the above example, lets assume that
+originally passed in. Using the above example, let us assume that
\fIbar\fR is actually an abbreviation for \fIbarfly\fR and the object
is now an indexObject because it was passed to
\fBTcl_GetIndexFromObj\fR. In this case the error message would be:
diff --git a/doc/after.n b/doc/after.n
index dbe0783..21961d3 100644
--- a/doc/after.n
+++ b/doc/after.n
@@ -46,8 +46,9 @@ The delayed command is formed by concatenating all the \fIscript\fR
arguments in the same fashion as the \fBconcat\fR command.
The command will be executed at global level (outside the context
of any Tcl procedure).
-If an error occurs while executing the delayed command then the
-\fBbgerror\fR mechanism is used to report the error.
+If an error occurs while executing the delayed command then
+the background error will be reported by the command
+registered with \fB interp bgerror\fR.
The \fBafter\fR command returns an identifier that can be used
to cancel the delayed command using \fBafter cancel\fR.
.TP
@@ -76,7 +77,8 @@ loop is entered and there are no events to process.
The command returns an identifier that can be used
to cancel the delayed command using \fBafter cancel\fR.
If an error occurs while executing the script then the
-\fBbgerror\fR mechanism is used to report the error.
+background error will be reported by the command
+registered with \fB interp bgerror\fR.
.TP
\fBafter info \fR?\fIid\fR?
This command returns information about existing event handlers.
@@ -134,7 +136,7 @@ doOneStep
.CE
.SH "SEE ALSO"
-bgerror(n), concat(n), update(n), vwait(n)
+concat(n), interp(n), update(n), vwait(n)
.SH KEYWORDS
cancel, delay, idle callback, sleep, time
diff --git a/doc/append.n b/doc/append.n
index 1ff43ee..dc9adbe 100644
--- a/doc/append.n
+++ b/doc/append.n
@@ -18,15 +18,18 @@ append \- Append to variable
.SH DESCRIPTION
.PP
Append all of the \fIvalue\fR arguments to the current value
-of variable \fIvarName\fR. If \fIvarName\fR doesn't exist,
+of variable \fIvarName\fR. If \fIvarName\fR does not exist,
it is given a value equal to the concatenation of all the
\fIvalue\fR arguments.
The result of this command is the new value stored in variable
\fIvarName\fR.
This command provides an efficient way to build up long
variables incrementally.
-For example, ``\fBappend a $b\fR'' is much more efficient than
-``\fBset a $a$b\fR'' if \fB$a\fR is long.
+For example,
+.QW "\fBappend a $b\fR"
+is much more efficient than
+.QW "\fBset a $a$b\fR"
+if \fB$a\fR is long.
.SH EXAMPLE
Building a string of comma-separated numbers piecemeal using a loop.
.CS
diff --git a/doc/apply.n b/doc/apply.n
new file mode 100644
index 0000000..8a38aac
--- /dev/null
+++ b/doc/apply.n
@@ -0,0 +1,96 @@
+'\"
+'\" Copyright (c) 2006 Miguel Sofer
+'\" Copyright (c) 2006 Donal K. Fellows
+'\"
+.so man.macros
+.TH apply n "" Tcl "Tcl Built-In Commands"
+.BS
+'\" Note: do not modify the .SH NAME line immediately below!
+.SH NAME
+apply \- Apply an anonymous function
+.SH SYNOPSIS
+\fBapply \fIfunc\fR ?\fIarg1 arg2 ...\fR?
+.BE
+.SH DESCRIPTION
+.PP
+The command \fBapply\fR applies the function \fIfunc\fR to the arguments
+\fIarg1 arg2 ...\fR and returns the result.
+.PP
+The function \fIfunc\fR is a two element list \fI{args body}\fR or a three
+element list \fI{args body namespace}\fR (as if the
+\fBlist\fR command had been used).
+The first element \fIargs\fR specifies the formal arguments to
+\fIfunc\fR. The specification of the formal arguments \fIargs\fR
+is shared with the \fBproc\fR command, and is described in detail in the
+corresponding manual page.
+.PP
+The contents of \fIbody\fR are executed by the Tcl interpreter
+after the local variables corresponding to the formal arguments are given
+the values of the actual parameters \fIarg1 arg2 ...\fR.
+When \fIbody\fR is being executed, variable names normally refer to
+local variables, which are created automatically when referenced and
+deleted when \fBapply\fR returns. One local variable is automatically
+created for each of the function's arguments.
+Global variables can only be accessed by invoking
+the \fBglobal\fR command or the \fBupvar\fR command.
+Namespace variables can only be accessed by invoking
+the \fBvariable\fR command or the \fBupvar\fR command.
+.PP
+The invocation of \fBapply\fR adds a call frame to Tcl's evaluation stack
+(the stack of frames accessed via \fBuplevel\fR). The execution of \fIbody\fR
+proceeds in this call frame, in the namespace given by \fInamespace\fR or
+in the global namespace if none was specified. If given, \fInamespace\fR is
+interpreted relative to the global namespace even if its name does not start
+with
+.QW :: .
+.PP
+The semantics of \fBapply\fR can also be described by:
+.PP
+.CS
+proc apply {fun args} {
+ set len [llength $fun]
+ if {($len < 2) || ($len > 3)} {
+ error "can't interpret \e"$fun\e" as anonymous function"
+ }
+ lassign $fun argList body ns
+ set name ::$ns::[getGloballyUniqueName]
+ set body0 {
+ rename [lindex [info level 0] 0] {}
+ }
+ proc $name $argList ${body0}$body
+ set code [catch {uplevel 1 $name $args} res opt]
+ return -options $opt $res
+}
+.CE
+.SH EXAMPLES
+This shows how to make a simple general command that applies a transformation
+to each element of a list.
+.CS
+proc map {lambda list} {
+ set result {}
+ foreach item $list {
+ lappend result [\fBapply\fR $lambda $item]
+ }
+ return $result
+}
+map {x {return [string length $x]:$x}} {a bb ccc dddd}
+ \fI\(-> 1:a 2:bb 3:ccc 4:dddd\fR
+map {x {expr {$x**2 + 3*$x - 2}}} {-4 -3 -2 -1 0 1 2 3 4}
+ \fI\(-> 2 -2 -4 -4 -2 2 8 16 26\fR
+.CE
+.PP
+The \fBapply\fR command is also useful for defining callbacks for use in the
+\fBtrace\fR command:
+.CS
+set vbl "123abc"
+trace add variable vbl write {\fBapply\fR {{v1 v2 op} {
+ upvar 1 $v1 v
+ puts "updated variable to \e"$v\e""
+}}}
+set vbl 123
+set vbl abc
+.CE
+.SH "SEE ALSO"
+proc(n), uplevel(n)
+.SH KEYWORDS
+argument, procedure, anonymous function
diff --git a/doc/array.n b/doc/array.n
index 7713f8c..e112c23 100644
--- a/doc/array.n
+++ b/doc/array.n
@@ -14,7 +14,6 @@ array \- Manipulate array variables
.SH SYNOPSIS
\fBarray \fIoption arrayName\fR ?\fIarg arg ...\fR?
.BE
-
.SH DESCRIPTION
.PP
This command performs one of several operations on the
@@ -34,7 +33,7 @@ check, and must have been the return value from a previous
invocation of \fBarray startsearch\fR.
This option is particularly useful if an array has an element
with an empty name, since the return value from
-\fBarray nextelement\fR won't indicate whether the search
+\fBarray nextelement\fR will not indicate whether the search
has been completed.
.TP
\fBarray donesearch \fIarrayName searchId\fR
@@ -58,21 +57,24 @@ array are included in the result.
If \fIpattern\fR is specified, then only those elements whose names
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
+If \fIarrayName\fR is not the name of an array variable, or if
the array contains no elements, then an empty list is returned.
+If traces on the array modify the list of elements, the elements
+returned are those that exist both before and after the call to
+\fBarray get\fR.
.TP
\fBarray names \fIarrayName\fR ?\fImode\fR? ?\fIpattern\fR?
Returns a list containing the names of all of the elements in
the array that match \fIpattern\fR. \fIMode\fR may be one of
-\fB-exact\fR, \fB-glob\fR, or \fB-regexp\fR. If specified, \fImode\fR
+\fB\-exact\fR, \fB\-glob\fR, or \fB\-regexp\fR. If specified, \fImode\fR
designates which matching rules to use to match \fIpattern\fR against
the names of the elements in the array. If not specified, \fImode\fR
-defaults to \fB-glob\fR. See the documentation for \fBstring match\fR
+defaults to \fB\-glob\fR. See the documentation for \fBstring match\fR
for information on glob style matching, and the documentation for
\fBregexp\fR for information on regexp matching.
If \fIpattern\fR is omitted then the command returns all of
the element names in the array. If there are no (matching) elements
-in the array, or if \fIarrayName\fR isn't the name of an array
+in the array, or if \fIarrayName\fR is not the name of an array
variable, then an empty string is returned.
.TP
\fBarray nextelement \fIarrayName searchId\fR
@@ -100,7 +102,7 @@ and \fIlist\fR is empty,
\fBarray size \fIarrayName\fR
Returns a decimal string giving the number of elements in the
array.
-If \fIarrayName\fR isn't the name of an array then 0 is returned.
+If \fIarrayName\fR is not the name of an array then 0 is returned.
.TP
\fBarray startsearch \fIarrayName\fR
This command initializes an element-by-element search through the
@@ -117,59 +119,55 @@ It is currently more efficient and easier to use either the \fBarray
get\fR or \fBarray names\fR, together with \fBforeach\fR, to iterate
over all but very large arrays. See the examples below for how to do
this.
-.VS 8.4
.TP
\fBarray statistics \fIarrayName\fR
Returns statistics about the distribution of data within the hashtable
that represents the array. This information includes the number of
entries in the table, the number of buckets, and the utilization of
the buckets.
-.VE 8.4
-.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
+matching rules of \fBstring match\fR). If \fIarrayName\fR is not the name
of an array variable or there are no matching elements in the array, no
error will be raised. If \fIpattern\fR is omitted and \fIarrayName\fR is
an array variable, then the command unsets the entire array.
The command always returns an empty string.
-.VE 8.3
.SH EXAMPLES
.CS
\fBarray set\fR colorcount {
- red 1
- green 5
- blue 4
- white 9
+ red 1
+ green 5
+ blue 4
+ white 9
}
foreach {color count} [\fBarray get\fR colorcount] {
- puts "Color: $color Count: $count"
+ puts "Color: $color Count: $count"
}
- => Color: blue Count: 4
+ \fB\(->\fR Color: blue Count: 4
Color: white Count: 9
Color: green Count: 5
Color: red Count: 1
foreach color [\fBarray names\fR colorcount] {
- puts "Color: $color Count: $colorcount($color)"
+ puts "Color: $color Count: $colorcount($color)"
}
- => Color: blue Count: 4
+ \fB\(->\fR Color: blue Count: 4
Color: white Count: 9
Color: green Count: 5
Color: red Count: 1
-foreach color [lsort [array names colorcount]] {
- puts "Color: $color Count: $colorcount($color)"
+foreach color [lsort [\fBarray names\fR colorcount]] {
+ puts "Color: $color Count: $colorcount($color)"
}
- => Color: blue Count: 4
+ \fB\(->\fR Color: blue Count: 4
Color: green Count: 5
Color: red Count: 1
Color: white Count: 9
\fBarray statistics\fR colorcount
- => 4 entries in table, 4 buckets
+ \fB\(->\fR 4 entries in table, 4 buckets
number of buckets with 0 entries: 1
number of buckets with 1 entries: 2
number of buckets with 2 entries: 1
@@ -183,9 +181,7 @@ foreach color [lsort [array names colorcount]] {
number of buckets with 10 or more entries: 0
average search distance for entry: 1.2
.CE
-
.SH "SEE ALSO"
list(n), string(n), variable(n), trace(n), foreach(n)
-
.SH KEYWORDS
array, element names, search
diff --git a/doc/bgerror.n b/doc/bgerror.n
index 5b42766..cb91351 100644
--- a/doc/bgerror.n
+++ b/doc/bgerror.n
@@ -16,14 +16,27 @@ bgerror \- Command invoked to process background errors
.BE
.SH DESCRIPTION
+.VS 8.5
+Release 8.5 of Tcl supports the \fBinterp bgerror\fR command,
+which allows applications to register in an interpreter the command
+that will handle background errors in that interpreter. In older
+releases of Tcl, this level of control was not available, and applications
+could control the handling of background errors only by creating
+a command with the particular command name \fBbgerror\fR in the
+global namespace of an interpreter. The following documentation
+describes the interface requirements of the \fBbgerror\fR command
+an application might define to retain compatibility with pre-8.5
+releases of Tcl. Applications intending to support only
+Tcl releases 8.5 and later should simply make use of \fBinterp bgerror\fR.
+.VE 8.5
.PP
-The \fBbgerror\fR command doesn't exist as built-in part of Tcl. Instead,
+The \fBbgerror\fR command does not exist as built-in part of Tcl. Instead,
individual applications or users can define a \fBbgerror\fR
command (e.g. as a Tcl procedure) if they wish to handle background
errors.
.PP
A background error is one that occurs in an event handler or some
-other command that didn't originate with the application.
+other command that did not originate with the application.
For example, if an error occurs while executing a command specified
with the \fBafter\fR command, then it is a background error.
For a non-background error, the error can simply be returned up
@@ -34,8 +47,10 @@ unwinding ends in the Tcl library and there is no obvious way for Tcl
to report the error.
.PP
When Tcl detects a background error, it saves information about the
-error and invokes the \fBbgerror\fR command later as an idle event
-handler. Before invoking \fBbgerror\fR, Tcl restores the
+error and invokes a handler command registered by \fBinterp bgerror\fR
+later as an idle event handler. The default handler command in turn
+calls the \fBbgerror\fR command .
+Before invoking \fBbgerror\fR, Tcl restores the
\fBerrorInfo\fR and \fBerrorCode\fR variables to their values at the
time the error occurred, then it invokes \fBbgerror\fR with the error
message as its only argument. Tcl assumes that the application has
@@ -54,22 +69,6 @@ error, in the order they occurred. However, if \fBbgerror\fR returns
with a break exception, then any remaining errors are skipped without
calling \fBbgerror\fR.
.PP
-Tcl has no default implementation for \fBbgerror\fR. However, in
-applications using Tk there is a default \fBbgerror\fR procedure which
-posts a dialog box containing the error message and offers the user a
-chance to see a stack trace showing where the error occurred. In
-addition to allowing the user to view the stack trace, the dialog
-provides an additional application configurable button which may be
-used, for example, to save the stack trace to a file. By default,
-this is the behavior associated with that button. This behavior can
-be redefined by setting the option database values
-\fB*ErrorDialog.function.text\fR, to specify the caption for the
-function button, and \fB*ErrorDialog.function.command\fR, to specify
-the command to be run. The text of the stack trace is appended to the
-command when it is evaluated. If either of these options is set to
-the empty string, then the additional button will not be displayed in
-the dialog.
-.PP
If you are writing code that will be used by others as part of a
package or other kind of library, consider avoiding \fBbgerror\fR.
The reason for this is that the application programmer may also want
@@ -87,7 +86,7 @@ proc bgerror {message} {
.CE
.SH "SEE ALSO"
-after(n), tclvars(n)
+after(n), interp(n), tclvars(n)
.SH KEYWORDS
background error, reporting
diff --git a/doc/binary.n b/doc/binary.n
index fbe1a8c..6b2150e 100644
--- a/doc/binary.n
+++ b/doc/binary.n
@@ -15,17 +15,15 @@ binary \- Insert and extract fields from binary strings
.br
\fBbinary scan \fIstring formatString \fR?\fIvarName varName ...\fR?
.BE
-
.SH DESCRIPTION
.PP
This command provides facilities for manipulating binary data. The
first form, \fBbinary format\fR, creates a binary string from normal
-Tcl values. For example, given the values 16 and 22, on a 32 bit
+Tcl values. For example, given the values 16 and 22, on a 32-bit
architecture, it might produce an 8-byte binary string consisting of
two 4-byte integers, one for each of the numbers. The second form of
the command, \fBbinary scan\fR, does the opposite: it extracts data
from a binary string and returns it as ordinary Tcl string values.
-
.SH "BINARY FORMAT"
.PP
The \fBbinary format\fR command generates a binary string whose layout
@@ -34,7 +32,8 @@ the additional arguments. The resulting binary value is returned.
.PP
The \fIformatString\fR consists of a sequence of zero or more field
specifiers separated by zero or more spaces. Each field specifier is
-a single type character followed by an optional numeric \fIcount\fR.
+a single type character followed by an optional flag character followed
+by an optional numeric \fIcount\fR.
Most field specifiers consume one argument to obtain the value to be
formatted. The type character specifies how the value is to be
formatted. The \fIcount\fR typically indicates how many items of the
@@ -42,12 +41,13 @@ specified type are taken from the value. If present, the \fIcount\fR
is a non-negative decimal integer or \fB*\fR, which normally indicates
that all of the items in the value are to be used. If the number of
arguments does not match the number of fields in the format string
-that consume arguments, then an error is generated.
+that consume arguments, then an error is generated. The flag character
+is ignored for for \fBbinary format\fR.
.PP
Here is a small example to clarify the relation between the field
specifiers and the arguments:
.CS
-\fBbinary format d3d {1.0 2.0 3.0 4.0} 0.1\fR
+\fBbinary format\fR d3d {1.0 2.0 3.0 4.0} 0.1
.CE
.PP
The first argument is a list of four numbers, but because of the count
@@ -62,13 +62,14 @@ to just after the last byte stored. The cursor is initially at
position 0 at the beginning of the data. The type may be any one of
the following characters:
.IP \fBa\fR 5
-Stores a character string of length \fIcount\fR in the output string.
+Stores a byte string of length \fIcount\fR in the output string.
Every character is taken as modulo 256 (i.e. the low byte of every
character is used, and the high byte discarded) so when storing
-character strings not wholly expressible using the characters \\u0000-\\u00ff,
-the \fBencoding convertto\fR command should be used
-first if this truncation is not desired (i.e. if the characters are
-not part of the ISO 8859-1 character set.)
+character strings not wholly expressible using the characters \eu0000-\eu00ff,
+the \fBencoding convertto\fR command should be used first to change
+the string into an external representation
+if this truncation is not desired (i.e. if the characters are
+not part of the ISO 8859\-1 character set.)
If \fIarg\fR has fewer than \fIcount\fR bytes, then additional zero
bytes are used to pad out the field. If \fIarg\fR is longer than the
specified length, the extra characters will be ignored. If
@@ -77,16 +78,33 @@ formatted. If \fIcount\fR is omitted, then one character will be
formatted. For example,
.RS
.CS
-\fBbinary format a7a*a alpha bravo charlie\fR
+\fBbinary format\fR a7a*a alpha bravo charlie
.CE
-will return a string equivalent to \fBalpha\\000\\000bravoc\fR.
+will return a string equivalent to \fBalpha\e000\e000bravoc\fR,
+.CS
+\fBbinary format\fR a* [encoding convertto utf-8 \eu20ac]
+.CE
+will return a string equivalent to \fB\e342\e202\e254\fR (which is the
+UTF-8 byte sequence for a Euro-currency character) and
+.CS
+\fBbinary format\fR a* [encoding convertto iso8859-15 \eu20ac]
+.CE
+will return a string equivalent to \fB\e244\fR (which is the ISO
+8859\-15 byte sequence for a Euro-currency character). Contrast these
+last two with:
+.CS
+\fBbinary format\fR a* \eu20ac
+.CE
+which returns a string equivalent to \fB\e254\fR (i.e. \fB\exac\fR) by
+truncating the high-bits of the character, and which is probably not
+what is desired.
.RE
.IP \fBA\fR 5
This form is the same as \fBa\fR except that spaces are used for
padding instead of nulls. For example,
.RS
.CS
-\fBbinary format A6A*A alpha bravo charlie\fR
+\fBbinary format\fR A6A*A alpha bravo charlie
.CE
will return \fBalpha bravoc\fR.
.RE
@@ -105,25 +123,26 @@ does not end at a byte boundary, the remaining bits of the last byte
will be zeros. For example,
.RS
.CS
-\fBbinary format b5b* 11100 111000011010\fR
+\fBbinary format\fR b5b* 11100 111000011010
.CE
-will return a string equivalent to \fB\\x07\\x87\\x05\fR.
+will return a string equivalent to \fB\ex07\ex87\ex05\fR.
.RE
.IP \fBB\fR 5
This form is the same as \fBb\fR except that the bits are stored in
high-to-low order within each byte. For example,
.RS
.CS
-\fBbinary format B5B* 11100 111000011010\fR
+\fBbinary format\fR B5B* 11100 111000011010
.CE
-will return a string equivalent to \fB\\xe0\\xe1\\xa0\fR.
+will return a string equivalent to \fB\exe0\exe1\exa0\fR.
.RE
-.IP \fBh\fR 5
-Stores a string of \fIcount\fR hexadecimal digits in low-to-high
+.IP \fBH\fR 5
+Stores a string of \fIcount\fR hexadecimal digits in high-to-low
within each byte in the output string. \fIArg\fR must contain a
-sequence of characters in the set ``0123456789abcdefABCDEF''. The
-resulting bytes are emitted in first to last order with the hex digits
-being formatted in low-to-high order within each byte. If \fIarg\fR
+sequence of characters in the set
+.QW 0123456789abcdefABCDEF .
+The resulting bytes are emitted in first to last order with the hex digits
+being formatted in high-to-low order within each byte. If \fIarg\fR
has fewer than \fIcount\fR digits, then zeros will be used for the
remaining digits. If \fIarg\fR has more than the specified number of
digits, the extra digits will be ignored. If \fIcount\fR is
@@ -133,37 +152,36 @@ number of digits formatted does not end at a byte boundary, the
remaining bits of the last byte will be zeros. For example,
.RS
.CS
-\fBbinary format h3h* AB def\fR
+\fBbinary format\fR H3H*H2 ab DEF 987
.CE
-will return a string equivalent to \fB\\xba\\x00\\xed\\x0f\fR.
+will return a string equivalent to \fB\exab\ex00\exde\exf0\ex98\fR.
.RE
-.IP \fBH\fR 5
-This form is the same as \fBh\fR except that the digits are stored in
-high-to-low order within each byte. For example,
+.IP \fBh\fR 5
+This form is the same as \fBH\fR except that the digits are stored in
+low-to-high order within each byte. This is seldom required. For example,
.RS
.CS
-\fBbinary format H3H* ab DEF\fR
+\fBbinary format\fR h3h*h2 AB def 987
.CE
-will return a string equivalent to \fB\\xab\\x00\\xde\\xf0\fR.
+will return a string equivalent to \fB\exba\ex00\exed\ex0f\ex89\fR.
.RE
.IP \fBc\fR 5
Stores one or more 8-bit integer values in the output string. If no
\fIcount\fR is specified, then \fIarg\fR must consist of an integer
-value; otherwise \fIarg\fR must consist of a list containing at least
-\fIcount\fR integer elements. The low-order 8 bits of each integer
+value. If \fIcount\fR is specified, \fIarg\fR must consist of a list
+containing at least that many integers. The low-order 8 bits of each integer
are stored as a one-byte value at the cursor position. If \fIcount\fR
-is \fB*\fR, then all of the integers in the list are formatted. If
-the number of elements in the list is fewer than \fIcount\fR, then an
-error is generated. If the number of elements in the list is greater
+is \fB*\fR, then all of the integers in the list are formatted. 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} 260 {2 5}\fR
+\fBbinary format\fR c3cc* {3 -3 128 1} 260 {2 5}
.CE
will return a string equivalent to
-\fB\\x03\\xfd\\x80\\x04\\x02\\x05\fR, whereas
+\fB\ex03\exfd\ex80\ex04\ex02\ex05\fR, whereas
.CS
-\fBbinary format c {2 5}\fR
+\fBbinary format\fR c {2 5}
.CE
will generate an error.
.RE
@@ -175,10 +193,10 @@ the cursor position with the least significant byte stored first. For
example,
.RS
.CS
-\fBbinary format s3 {3 -3 258 1}\fR
+\fBbinary format\fR s3 {3 -3 258 1}
.CE
will return a string equivalent to
-\fB\\x03\\x00\\xfd\\xff\\x02\\x01\fR.
+\fB\ex03\ex00\exfd\exff\ex02\ex01\fR.
.RE
.IP \fBS\fR 5
This form is the same as \fBs\fR except that it stores one or more
@@ -186,11 +204,19 @@ This form is the same as \fBs\fR except that it stores one or more
example,
.RS
.CS
-\fBbinary format S3 {3 -3 258 1}\fR
+\fBbinary format\fR S3 {3 -3 258 1}
.CE
will return a string equivalent to
-\fB\\x00\\x03\\xff\\xfd\\x01\\x02\fR.
-.RE
+\fB\ex00\ex03\exff\exfd\ex01\ex02\fR.
+.RE
+.IP \fBt\fR 5
+.VS 8.5
+This form (mnemonically \fItiny\fR) is the same as \fBs\fR and \fBS\fR
+except that it stores the 16-bit integers in the output string in the
+native byte order of the machine where the Tcl script is running.
+To determine what the native byte order of the machine is, refer to
+the \fBbyteOrder\fR element of the \fBtcl_platform\fR array.
+.VE 8.5
.IP \fBi\fR 5
This form is the same as \fBc\fR except that it stores one or more
32-bit integers in little-endian byte order in the output string. The
@@ -199,10 +225,10 @@ the cursor position with the least significant byte stored first. For
example,
.RS
.CS
-\fBbinary format i3 {3 -3 65536 1}\fR
+\fBbinary format\fR i3 {3 -3 65536 1}
.CE
will return a string equivalent to
-\fB\\x03\\x00\\x00\\x00\\xfd\\xff\\xff\\xff\\x00\\x00\\x01\\x00\fR
+\fB\ex03\ex00\ex00\ex00\exfd\exff\exff\exff\ex00\ex00\ex01\ex00\fR
.RE
.IP \fBI\fR 5
This form is the same as \fBi\fR except that it stores one or more one
@@ -210,13 +236,21 @@ or more 32-bit integers in big-endian byte order in the output string.
For example,
.RS
.CS
-\fBbinary format I3 {3 -3 65536 1}\fR
+\fBbinary format\fR I3 {3 -3 65536 1}
.CE
will return a string equivalent to
-\fB\\x00\\x00\\x00\\x03\\xff\\xff\\xff\\xfd\\x00\\x01\\x00\\x00\fR
-.RE
+\fB\ex00\ex00\ex00\ex03\exff\exff\exff\exfd\ex00\ex01\ex00\ex00\fR
+.RE
+.IP \fBn\fR 5
+.VS 8.5
+This form (mnemonically \fInumber\fR or \fInormal\fR) is the same as
+\fBi\fR and \fBI\fR except that it stores the 32-bit integers in the
+output string in the native byte order of the machine where the Tcl
+script is running.
+To determine what the native byte order of the machine is, refer to
+the \fBbyteOrder\fR element of the \fBtcl_platform\fR array.
+.VE 8.5
.IP \fBw\fR 5
-.VS 8.4
This form is the same as \fBc\fR except that it stores one or more
64-bit integers in little-endian byte order in the output string. The
low-order 64-bits of each integer are stored as an eight-byte value at
@@ -224,7 +258,7 @@ the cursor position with the least significant byte stored first. For
example,
.RS
.CS
-\fBbinary format w 7810179016327718216\fR
+\fBbinary format\fR w 7810179016327718216
.CE
will return the string \fBHelloTcl\fR
.RE
@@ -234,14 +268,22 @@ or more 64-bit integers in big-endian byte order in the output string.
For example,
.RS
.CS
-\fBbinary format Wc 4785469626960341345 110\fR
+\fBbinary format\fR Wc 4785469626960341345 110
.CE
will return the string \fBBigEndian\fR
-.VE
.RE
+.IP \fBm\fR 5
+.VS 8.5
+This form (mnemonically the mirror of \fBw\fR) is the same as \fBw\fR
+and \fBW\fR except that it stores the 64-bit integers in the output
+string in the native byte order of the machine where the Tcl script is
+running.
+To determine what the native byte order of the machine is, refer to
+the \fBbyteOrder\fR element of the \fBtcl_platform\fR array.
+.VE 8.5
.IP \fBf\fR 5
This form is the same as \fBc\fR except that it stores one or more one
-or more single-precision floating in the machine's native
+or more single-precision floating point numbers in the machine's native
representation in the output string. This representation is not
portable across architectures, so it should not be used to communicate
floating point numbers across the network. The size of a floating
@@ -249,28 +291,54 @@ point number may vary across architectures, so the number of bytes
that are generated may vary. If the value overflows the
machine's native representation, then the value of FLT_MAX
as defined by the system will be used instead. Because Tcl uses
-double-precision floating-point numbers internally, there may be some
+double-precision floating point numbers internally, there may be some
loss of precision in the conversion to single-precision. For example,
on a Windows system running on an Intel Pentium processor,
.RS
.CS
-\fBbinary format f2 {1.6 3.4}\fR
+\fBbinary format\fR f2 {1.6 3.4}
.CE
will return a string equivalent to
-\fB\\xcd\\xcc\\xcc\\x3f\\x9a\\x99\\x59\\x40\fR.
-.RE
+\fB\excd\excc\excc\ex3f\ex9a\ex99\ex59\ex40\fR.
+.RE
+.IP \fBr\fR 5
+.VS 8.5
+This form (mnemonically \fIreal\fR) is the same as \fBf\fR except that
+it stores the single-precision floating point numbers in little-endian
+order. This conversion only produces meaningful output when used on
+machines which use the IEEE floating point representation (very
+common, but not universal.)
+.VE 8.5
+.IP \fBR\fR 5
+.VS 8.5
+This form is the same as \fBr\fR except that it stores the
+single-precision floating point numbers in big-endian order.
+.VE 8.5
.IP \fBd\fR 5
This form is the same as \fBf\fR except that it stores one or more one
-or more double-precision floating in the machine's native
+or more double-precision floating point numbers in the machine's native
representation in the output string. For example, on a
Windows system running on an Intel Pentium processor,
.RS
.CS
-\fBbinary format d1 {1.6}\fR
+\fBbinary format\fR d1 {1.6}
.CE
will return a string equivalent to
-\fB\\x9a\\x99\\x99\\x99\\x99\\x99\\xf9\\x3f\fR.
-.RE
+\fB\ex9a\ex99\ex99\ex99\ex99\ex99\exf9\ex3f\fR.
+.RE
+.IP \fBq\fR 5
+.VS 8.5
+This form (mnemonically the mirror of \fBd\fR) is the same as \fBd\fR
+except that it stores the double-precision floating point numbers in
+little-endian order. This conversion only produces meaningful output
+when used on machines which use the IEEE floating point representation
+(very common, but not universal.)
+.VE 8.5
+.IP \fBQ\fR 5
+.VS 8.5
+This form is the same as \fBq\fR except that it stores the
+double-precision floating point numbers in big-endian order.
+.VE 8.5
.IP \fBx\fR 5
Stores \fIcount\fR null bytes in the output string. If \fIcount\fR is
not specified, stores one null byte. If \fIcount\fR is \fB*\fR,
@@ -278,9 +346,9 @@ generates an error. This type does not consume an argument. For
example,
.RS
.CS
-\fBbinary format a3xa3x2a3 abc def ghi\fR
+\fBbinary format\fR a3xa3x2a3 abc def ghi
.CE
-will return a string equivalent to \fBabc\\000def\\000\\000ghi\fR.
+will return a string equivalent to \fBabc\e000def\e000\e000ghi\fR.
.RE
.IP \fBX\fR 5
Moves the cursor back \fIcount\fR bytes in the output string. If
@@ -291,7 +359,7 @@ omitted then the cursor is moved back one byte. This type does not
consume an argument. For example,
.RS
.CS
-\fBbinary format a3X*a3X2a3 abc def ghi\fR
+\fBbinary format\fR a3X*a3X2a3 abc def ghi
.CE
will return \fBdghi\fR.
.RE
@@ -306,16 +374,17 @@ the output string. If \fIcount\fR is omitted, then an error will be
generated. This type does not consume an argument. For example,
.RS
.CS
-\fBbinary format a5@2a1@*a3@10a1 abcde f ghi j\fR
+\fBbinary format\fR a5@2a1@*a3@10a1 abcde f ghi j
.CE
-will return \fBabfdeghi\\000\\000j\fR.
+will return \fBabfdeghi\e000\e000j\fR.
.RE
-
.SH "BINARY SCAN"
.PP
The \fBbinary scan\fR command parses fields from a binary string,
returning the number of conversions performed. \fIString\fR gives the
-input to be parsed and \fIformatString\fR indicates how to parse it.
+input bytes to be parsed (one byte per character, and characters not
+representable as a byte have their high bits chopped)
+and \fIformatString\fR indicates how to parse it.
Each \fIvarName\fR gives the name of a variable; when a field is
scanned from \fIstring\fR the result is assigned to the corresponding
variable.
@@ -323,7 +392,8 @@ variable.
As with \fBbinary format\fR, the \fIformatString\fR consists of a
sequence of zero or more field specifiers separated by zero or more
spaces. Each field specifier is a single type character followed by
-an optional numeric \fIcount\fR. Most field specifiers consume one
+an optional flag character followed by an optional numeric \fIcount\fR.
+Most field specifiers consume one
argument to obtain the variable into which the scanned values should
be placed. The type character specifies how the binary data is to be
interpreted. The \fIcount\fR typically indicates how many items of
@@ -335,13 +405,16 @@ position to satisfy the current field specifier, then the
corresponding variable is left untouched and \fBbinary scan\fR returns
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.
+consume arguments, then an error is generated. The flag character
+.QW u
+may be given to cause some types to be read as unsigned values. The flag
+is accepted for all field types but is ignored for non-integer fields.
.PP
A similar example as with \fBbinary format\fR should explain the
relation between field specifiers and arguments in case of the binary
scan subcommand:
.CS
-\fBbinary scan $bytes s3s first second\fR
+\fBbinary scan\fR $bytes s3s first second
.CE
.PP
This command (provided the binary string in the variable \fIbytes\fR
@@ -352,31 +425,33 @@ integers), no assignment to \fIsecond\fR will be made, and if
\fIbytes\fR contains fewer than 6 bytes (i.e. three 2-byte integers),
no assignment to \fIfirst\fR will be made. Hence:
.CS
-\fBputs [binary scan abcdefg s3s first second]\fR
-\fBputs $first\fR
-\fBputs $second\fR
+puts [\fBbinary scan\fR abcdefg s3s first second]
+puts $first
+puts $second
.CE
will print (assuming neither variable is set previously):
.CS
-\fB1\fR
-\fB25185 25699 26213\fR
-\fIcan't read "second": no such variable\fR
+1
+25185 25699 26213
+can't read "second": no such variable
.CE
.PP
-It is \fBimportant\fR to note that the \fBc\fR, \fBs\fR, and \fBS\fR
+It is \fIimportant\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
+set signShort [\fBbinary format\fR s1 0x8000]
+\fBbinary scan\fR $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:
+If you require unsigned values you can include the
+.QW u
+flag character following
+the field type. For example, to read an unsigned short value:
.CS
-\fBset val [expr {$val & 0xFFFF}]; \fI# val == 0x8000\fR
+set signShort [\fBbinary format\fR s1 0x8000]
+\fBbinary scan\fR $signShort su1 val; \fI# val == 0x00008000\fR
.CE
.PP
Each type-count pair moves an imaginary cursor through the binary data,
@@ -384,116 +459,128 @@ 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
the following characters:
.IP \fBa\fR 5
-The data is a character string of length \fIcount\fR. If \fIcount\fR
+The data is a byte string of length \fIcount\fR. If \fIcount\fR
is \fB*\fR, then all of the remaining bytes in \fIstring\fR will be
scanned into the variable. If \fIcount\fR is omitted, then one
-character will be scanned.
-All characters scanned will be interpreted as being in the
-range \\u0000-\\u00ff so the \fBencoding convertfrom\fR command might be
-needed if the string is not an ISO 8859\-1 string.
+byte will be scanned.
+All bytes scanned will be interpreted as being characters in the
+range \eu0000-\eu00ff so the \fBencoding convertfrom\fR command will be
+needed if the string is not a binary string or a string encoded in ISO
+8859\-1.
For example,
.RS
.CS
-\fBbinary scan abcde\\000fghi a6a10 var1 var2\fR
+\fBbinary scan\fR abcde\e000fghi a6a10 var1 var2
+.CE
+will return \fB1\fR with the string equivalent to \fBabcde\e000\fR
+stored in \fIvar1\fR and \fIvar2\fR left unmodified, and
+.CS
+\fBbinary scan\fR \e342\e202\e254 a* var1
+set var2 [encoding convertfrom utf-8 $var1]
.CE
-will return \fB1\fR with the string equivalent to \fBabcde\\000\fR
-stored in \fBvar1\fR and \fBvar2\fR left unmodified.
+will store a Euro-currency character in \fIvar2\fR.
.RE
.IP \fBA\fR 5
This form is the same as \fBa\fR, except trailing blanks and nulls are stripped from
the scanned value before it is stored in the variable. For example,
.RS
.CS
-\fBbinary scan "abc efghi \\000" A* var1\fR
+\fBbinary scan\fR "abc efghi \e000" A* var1
.CE
-will return \fB1\fR with \fBabc efghi\fR stored in \fBvar1\fR.
+will return \fB1\fR with \fBabc efghi\fR stored in \fIvar1\fR.
.RE
.IP \fBb\fR 5
The data is turned into a string of \fIcount\fR binary digits in
-low-to-high order represented as a sequence of ``1'' and ``0''
+low-to-high order represented as a sequence of
+.QW 1
+and
+.QW 0
characters. The data bytes are scanned in first to last order with
the bits being taken in low-to-high order within each byte. Any extra
bits in the last byte are ignored. If \fIcount\fR is \fB*\fR, then
-all of the remaining bits in \fBstring\fR will be scanned. If
+all of the remaining bits in \fIstring\fR will be scanned. If
\fIcount\fR is omitted, then one bit will be scanned. For example,
.RS
.CS
-\fBbinary scan \\x07\\x87\\x05 b5b* var1 var2\fR
+\fBbinary scan\fR \ex07\ex87\ex05 b5b* var1 var2
.CE
-will return \fB2\fR with \fB11100\fR stored in \fBvar1\fR and
-\fB1110000110100000\fR stored in \fBvar2\fR.
+will return \fB2\fR with \fB11100\fR stored in \fIvar1\fR and
+\fB1110000110100000\fR stored in \fIvar2\fR.
.RE
.IP \fBB\fR 5
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\fR \ex70\ex87\ex05 B5B* var1 var2
.CE
-will return \fB2\fR with \fB01110\fR stored in \fBvar1\fR and
-\fB1000011100000101\fR stored in \fBvar2\fR.
+will return \fB2\fR with \fB01110\fR stored in \fIvar1\fR and
+\fB1000011100000101\fR stored in \fIvar2\fR.
.RE
-.IP \fBh\fR 5
+.IP \fBH\fR 5
The data is turned into a string of \fIcount\fR hexadecimal digits in
-low-to-high order represented as a sequence of characters in the set
-``0123456789abcdef''. The data bytes are scanned in first to last
-order with the hex digits being taken in low-to-high order within each
-byte. Any extra bits in the last byte are ignored. If \fIcount\fR
-is \fB*\fR, then all of the remaining hex digits in \fBstring\fR will be
-scanned. If \fIcount\fR is omitted, then one hex digit will be
-scanned. For example,
+high-to-low order represented as a sequence of characters in the set
+.QW 0123456789abcdef .
+The data bytes are scanned in first to last
+order with the hex digits being taken in high-to-low order within each
+byte. Any extra bits in the last byte are ignored. If \fIcount\fR is
+\fB*\fR, then all of the remaining hex digits in \fIstring\fR will be
+scanned. If \fIcount\fR is omitted, then one hex digit will be
+scanned. For example,
.RS
.CS
-\fBbinary scan \\x07\\x86\\x05 h3h* var1 var2\fR
+\fBbinary scan\fR \ex07\exC6\ex05\ex1f\ex34 H3H* var1 var2
.CE
-will return \fB2\fR with \fB706\fR stored in \fBvar1\fR and
-\fB50\fR stored in \fBvar2\fR.
+will return \fB2\fR with \fB07c\fR stored in \fIvar1\fR and
+\fB051f34\fR stored in \fIvar2\fR.
.RE
-.IP \fBH\fR 5
-This form is the same as \fBh\fR, except the digits are taken in
-high-to-low order within each byte. For example,
+.IP \fBh\fR 5
+This form is the same as \fBH\fR, except the digits are taken in
+reverse (low-to-high) order within each byte. For example,
.RS
.CS
-\fBbinary scan \\x07\\x86\\x05 H3H* var1 var2\fR
+\fBbinary scan\fR \ex07\ex86\ex05\ex12\ex34 h3h* var1 var2
.CE
-will return \fB2\fR with \fB078\fR stored in \fBvar1\fR and
-\fB05\fR stored in \fBvar2\fR.
+will return \fB2\fR with \fB706\fR stored in \fIvar1\fR and
+\fB502143\fR stored in \fIvar2\fR.
.RE
+Note that most code that wishes to parse the hexadecimal digits from
+multiple bytes in order should use the \fBH\fR format.
.IP \fBc\fR 5
The data is turned into \fIcount\fR 8-bit signed integers and stored
in the corresponding variable as a list. If \fIcount\fR is \fB*\fR,
-then all of the remaining bytes in \fBstring\fR will be scanned. If
+then all of the remaining bytes in \fIstring\fR will be scanned. If
\fIcount\fR is omitted, then one 8-bit integer will be scanned. For
example,
.RS
.CS
-\fBbinary scan \\x07\\x86\\x05 c2c* var1 var2\fR
+\fBbinary scan\fR \ex07\ex86\ex05 c2c* var1 var2
.CE
-will return \fB2\fR with \fB7 -122\fR stored in \fBvar1\fR and \fB5\fR
-stored in \fBvar2\fR. Note that the integers returned are signed, but
+will return \fB2\fR with \fB7 -122\fR stored in \fIvar1\fR and \fB5\fR
+stored in \fIvar2\fR. Note that the integers returned are signed, but
they can be converted to unsigned 8-bit quantities using an expression
like:
.CS
-\fBexpr { $num & 0xff }\fR
+set num [expr { $num & 0xff }]
.CE
.RE
.IP \fBs\fR 5
The data is interpreted as \fIcount\fR 16-bit signed integers
represented in little-endian byte order. The integers are stored in
the corresponding variable as a list. If \fIcount\fR is \fB*\fR, then
-all of the remaining bytes in \fBstring\fR will be scanned. If
+all of the remaining bytes in \fIstring\fR will be scanned. If
\fIcount\fR is omitted, then one 16-bit integer will be scanned. For
example,
.RS
.CS
-\fBbinary scan \\x05\\x00\\x07\\x00\\xf0\\xff s2s* var1 var2\fR
+\fBbinary scan\fR \ex05\ex00\ex07\ex00\exf0\exff s2s* var1 var2
.CE
-will return \fB2\fR with \fB5 7\fR stored in \fBvar1\fR and \fB-16\fR
-stored in \fBvar2\fR. Note that the integers returned are signed, but
+will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB\-16\fR
+stored in \fIvar2\fR. Note that the integers returned are signed, but
they can be converted to unsigned 16-bit quantities using an expression
like:
.CS
-\fBexpr { $num & 0xffff }\fR
+set num [expr { $num & 0xffff }]
.CE
.RE
.IP \fBS\fR 5
@@ -502,28 +589,37 @@ as \fIcount\fR 16-bit signed integers represented in big-endian byte
order. For example,
.RS
.CS
-\fBbinary scan \\x00\\x05\\x00\\x07\\xff\\xf0 S2S* var1 var2\fR
+\fBbinary scan\fR \ex00\ex05\ex00\ex07\exff\exf0 S2S* var1 var2
.CE
-will return \fB2\fR with \fB5 7\fR stored in \fBvar1\fR and \fB-16\fR
-stored in \fBvar2\fR.
+will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB\-16\fR
+stored in \fIvar2\fR.
.RE
+.IP \fBt\fR 5
+.VS 8.5
+The data is interpreted as \fIcount\fR 16-bit signed integers
+represented in the native byte order of the machine running the Tcl
+script. It is otherwise identical to \fBs\fR and \fBS\fR.
+To determine what the native byte order of the machine is, refer to
+the \fBbyteOrder\fR element of the \fBtcl_platform\fR array.
+.VE 8.5
.IP \fBi\fR 5
The data is interpreted as \fIcount\fR 32-bit signed integers
represented in little-endian byte order. The integers are stored in
the corresponding variable as a list. If \fIcount\fR is \fB*\fR, then
-all of the remaining bytes in \fBstring\fR will be scanned. If
+all of the remaining bytes in \fIstring\fR will be scanned. If
\fIcount\fR is omitted, then one 32-bit integer will be scanned. For
example,
.RS
.CS
-\fBbinary scan \\x05\\x00\\x00\\x00\\x07\\x00\\x00\\x00\\xf0\\xff\\xff\\xff i2i* var1 var2\fR
+set str \ex05\ex00\ex00\ex00\ex07\ex00\ex00\ex00\exf0\exff\exff\exff
+\fBbinary scan\fR $str i2i* var1 var2
.CE
-will return \fB2\fR with \fB5 7\fR stored in \fBvar1\fR and \fB-16\fR
-stored in \fBvar2\fR. Note that the integers returned are signed, but
+will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB\-16\fR
+stored in \fIvar2\fR. Note that the integers returned are signed, but
they can be converted to unsigned 32-bit quantities using an expression
like:
.CS
-\fBexpr { $num & 0xffffffff }\fR
+set num [expr { $num & 0xffffffff }]
.CE
.RE
.IP \fBI\fR 5
@@ -532,25 +628,34 @@ as \fIcount\fR 32-bit signed integers represented in big-endian byte
order. For example,
.RS
.CS
-\fBbinary scan \\x00\\x00\\x00\\x05\\x00\\x00\\x00\\x07\\xff\\xff\\xff\\xf0 I2I* var1 var2\fR
+set str \ex00\ex00\ex00\ex05\ex00\ex00\ex00\ex07\exff\exff\exff\exf0
+\fBbinary scan\fR $str I2I* var1 var2
.CE
-will return \fB2\fR with \fB5 7\fR stored in \fBvar1\fR and \fB-16\fR
-stored in \fBvar2\fR.
+will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB\-16\fR
+stored in \fIvar2\fR.
.RE
+.IP \fBn\fR 5
+.VS 8.5
+The data is interpreted as \fIcount\fR 32-bit signed integers
+represented in the native byte order of the machine running the Tcl
+script. It is otherwise identical to \fBi\fR and \fBI\fR.
+To determine what the native byte order of the machine is, refer to
+the \fBbyteOrder\fR element of the \fBtcl_platform\fR array.
+.VE 8.5
.IP \fBw\fR 5
-.VS 8.4
The data is interpreted as \fIcount\fR 64-bit signed integers
represented in little-endian byte order. The integers are stored in
the corresponding variable as a list. If \fIcount\fR is \fB*\fR, then
-all of the remaining bytes in \fBstring\fR will be scanned. If
+all of the remaining bytes in \fIstring\fR will be scanned. If
\fIcount\fR is omitted, then one 64-bit integer will be scanned. For
example,
.RS
.CS
-\fBbinary scan \\x05\\x00\\x00\\x00\\x07\\x00\\x00\\x00\\xf0\\xff\\xff\\xff wi* var1 var2\fR
+set str \ex05\ex00\ex00\ex00\ex07\ex00\ex00\ex00\exf0\exff\exff\exff
+\fBbinary scan\fR $str wi* var1 var2
.CE
-will return \fB2\fR with \fB30064771077\fR stored in \fBvar1\fR and
-\fB-16\fR stored in \fBvar2\fR. Note that the integers returned are
+will return \fB2\fR with \fB30064771077\fR stored in \fIvar1\fR and
+\fB\-16\fR stored in \fIvar2\fR. Note that the integers returned are
signed and cannot be represented by Tcl as unsigned values.
.RE
.IP \fBW\fR 5
@@ -559,18 +664,26 @@ as \fIcount\fR 64-bit signed integers represented in big-endian byte
order. For example,
.RS
.CS
-\fBbinary scan \\x00\\x00\\x00\\x05\\x00\\x00\\x00\\x07\\xff\\xff\\xff\\xf0 WI* var1 var2\fR
+set str \ex00\ex00\ex00\ex05\ex00\ex00\ex00\ex07\exff\exff\exff\exf0
+\fBbinary scan\fR $str WI* var1 var2
.CE
-will return \fB2\fR with \fB21474836487\fR stored in \fBvar1\fR and \fB-16\fR
-stored in \fBvar2\fR.
-.VE
+will return \fB2\fR with \fB21474836487\fR stored in \fIvar1\fR and \fB\-16\fR
+stored in \fIvar2\fR.
.RE
+.IP \fBm\fR 5
+.VS 8.5
+The data is interpreted as \fIcount\fR 64-bit signed integers
+represented in the native byte order of the machine running the Tcl
+script. It is otherwise identical to \fBw\fR and \fBW\fR.
+To determine what the native byte order of the machine is, refer to
+the \fBbyteOrder\fR element of the \fBtcl_platform\fR array.
+.VE 8.5
.IP \fBf\fR 5
The data is interpreted as \fIcount\fR single-precision floating point
numbers in the machine's native representation. The floating point
numbers are stored in the corresponding variable as a list. If
\fIcount\fR is \fB*\fR, then all of the remaining bytes in
-\fBstring\fR will be scanned. If \fIcount\fR is omitted, then one
+\fIstring\fR will be scanned. If \fIcount\fR is omitted, then one
single-precision floating point number will be scanned. The size of a
floating point number may vary across architectures, so the number of
bytes that are scanned may vary. If the data does not represent a
@@ -579,11 +692,25 @@ compiler dependent. For example, on a Windows system running on an
Intel Pentium processor,
.RS
.CS
-\fBbinary scan \\x3f\\xcc\\xcc\\xcd f var1\fR
+\fBbinary scan\fR \ex3f\excc\excc\excd f var1
.CE
will return \fB1\fR with \fB1.6000000238418579\fR stored in
-\fBvar1\fR.
+\fIvar1\fR.
.RE
+.IP \fBr\fR 5
+.VS 8.5
+This form is the same as \fBf\fR except that the data is interpreted
+as \fIcount\fR single-precision floating point number in little-endian
+order. This conversion is not portable to the minority of systems not
+using IEEE floating point representations.
+.VE 8.5
+.IP \fBR\fR 5
+.VS 8.5
+This form is the same as \fBf\fR except that the data is interpreted
+as \fIcount\fR single-precision floating point number in big-endian
+order. This conversion is not portable to the minority of systems not
+using IEEE floating point representations.
+.VE 8.5
.IP \fBd\fR 5
This form is the same as \fBf\fR except that the data is interpreted
as \fIcount\fR double-precision floating point numbers in the
@@ -591,23 +718,37 @@ machine's native representation. For example, on a Windows system
running on an Intel Pentium processor,
.RS
.CS
-\fBbinary scan \\x9a\\x99\\x99\\x99\\x99\\x99\\xf9\\x3f d var1\fR
+\fBbinary scan\fR \ex9a\ex99\ex99\ex99\ex99\ex99\exf9\ex3f d var1
.CE
will return \fB1\fR with \fB1.6000000000000001\fR
-stored in \fBvar1\fR.
-.RE
+stored in \fIvar1\fR.
+.RE
+.IP \fBq\fR 5
+.VS 8.5
+This form is the same as \fBd\fR except that the data is interpreted
+as \fIcount\fR double-precision floating point number in little-endian
+order. This conversion is not portable to the minority of systems not
+using IEEE floating point representations.
+.VE 8.5
+.IP \fBQ\fR 5
+.VS 8.5
+This form is the same as \fBd\fR except that the data is interpreted
+as \fIcount\fR double-precision floating point number in big-endian
+order. This conversion is not portable to the minority of systems not
+using IEEE floating point representations.
+.VE 8.5
.IP \fBx\fR 5
Moves the cursor forward \fIcount\fR bytes in \fIstring\fR. If
\fIcount\fR is \fB*\fR or is larger than the number of bytes after the
-current cursor cursor position, then the cursor is positioned after
+current cursor position, then the cursor is positioned after
the last byte in \fIstring\fR. If \fIcount\fR is omitted, then the
cursor is moved forward one byte. Note that this type does not
consume an argument. For example,
.RS
.CS
-\fBbinary scan \\x01\\x02\\x03\\x04 x2H* var1\fR
+\fBbinary scan\fR \ex01\ex02\ex03\ex04 x2H* var1
.CE
-will return \fB1\fR with \fB0304\fR stored in \fBvar1\fR.
+will return \fB1\fR with \fB0304\fR stored in \fIvar1\fR.
.RE
.IP \fBX\fR 5
Moves the cursor back \fIcount\fR bytes in \fIstring\fR. If
@@ -618,10 +759,10 @@ is omitted then the cursor is moved back one byte. Note that this
type does not consume an argument. For example,
.RS
.CS
-\fBbinary scan \\x01\\x02\\x03\\x04 c2XH* var1 var2\fR
+\fBbinary scan\fR \ex01\ex02\ex03\ex04 c2XH* var1 var2
.CE
-will return \fB2\fR with \fB1 2\fR stored in \fBvar1\fR and \fB020304\fR
-stored in \fBvar2\fR.
+will return \fB2\fR with \fB1 2\fR stored in \fIvar1\fR and \fB020304\fR
+stored in \fIvar2\fR.
.RE
.IP \fB@\fR 5
Moves the cursor to the absolute location in the data string specified
@@ -631,21 +772,23 @@ by \fIcount\fR. Note that position 0 refers to the first byte in
\fIcount\fR is omitted, then an error will be generated. For example,
.RS
.CS
-\fBbinary scan \\x01\\x02\\x03\\x04 c2@1H* var1 var2\fR
+\fBbinary scan\fR \ex01\ex02\ex03\ex04 c2@1H* var1 var2
.CE
-will return \fB2\fR with \fB1 2\fR stored in \fBvar1\fR and \fB020304\fR
-stored in \fBvar2\fR.
+will return \fB2\fR with \fB1 2\fR stored in \fIvar1\fR and \fB020304\fR
+stored in \fIvar2\fR.
.RE
-.SH "PLATFORM ISSUES"
-Sometimes it is desirable to format or scan integer values in the
-native byte order for the machine. Refer to the \fBbyteOrder\fR
-element of the \fBtcl_platform\fR array to decide which type character
-to use when formatting or scanning integers.
+.SH "PORTABILITY ISSUES"
+The \fBr\fR, \fBR\fR, \fBq\fR and \fBQ\fR conversions will only work
+reliably for transferring data between computers which are all using
+IEEE floating point representations. This is very common, but not
+universal. To transfer floating-point numbers portably between all
+architectures, use their textual representation (as produced by
+\fBformat\fR) instead.
.SH EXAMPLES
This is a procedure to write a Tcl string to a binary-encoded channel as
UTF-8 data preceded by a length word:
.CS
-proc writeString {channel string} {
+proc \fIwriteString\fR {channel string} {
set data [encoding convertto utf-8 $string]
puts -nonewline [\fBbinary format\fR Ia* \e
[string length $data] $data]
@@ -653,9 +796,9 @@ proc writeString {channel string} {
.CE
.PP
This procedure reads a string from a channel that was written by the
-previously presented \fBwriteString\fR procedure:
+previously presented \fIwriteString\fR procedure:
.CS
-proc readString {channel} {
+proc \fIreadString\fR {channel} {
if {![\fBbinary scan\fR [read $channel 4] I length]} {
error "missing length"
}
@@ -663,9 +806,7 @@ proc readString {channel} {
return [encoding convertfrom utf-8 $data]
}
.CE
-
.SH "SEE ALSO"
format(n), scan(n), tclvars(n)
-
.SH KEYWORDS
binary, format, scan
diff --git a/doc/catch.n b/doc/catch.n
index f2d5533..0e2ec04 100644
--- a/doc/catch.n
+++ b/doc/catch.n
@@ -1,18 +1,19 @@
'\"
'\" Copyright (c) 1993-1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Contributions from Don Porter, NIST, 2003. (not subject to US copyright)
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.so man.macros
-.TH catch n "8.0" Tcl "Tcl Built-In Commands"
+.TH catch n "8.5" Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
catch \- Evaluate script and trap exceptional returns
.SH SYNOPSIS
-\fBcatch\fI script \fR?\fIvarName\fR?
+\fBcatch\fI script \fR?\fIresultVarName\fR? ?\fIoptionsVarName\fR?
.BE
.SH DESCRIPTION
@@ -35,44 +36,61 @@ new commands that return other integer values as return codes as well,
and scripts that make use of the \fBreturn -code\fR command can also
have return codes other than the five defined by Tcl.
.PP
-If the \fIvarName\fR argument is given, then the variable it names is
+If the \fIresultVarName\fR argument is given, then the variable it names is
set to the result of the script evaluation. When the return code from
-the script is 1 (\fBTCL_ERROR\fR), the value stored in \fIvarName\fR is an error
+the script is 1 (\fBTCL_ERROR\fR), the value stored in \fIresultVarName\fR is an error
message. When the return code from the script is 0 (\fBTCL_OK\fR), the value
stored in \fIresultVarName\fR is the value returned from \fIscript\fR.
.PP
-If \fIscript\fR does not raise an error, \fBcatch\fR will return 0
-(\fBTCL_OK\fR) and set the variable to the value returned from \fIscript\fR.
+.VS 8.5
+If the \fIoptionsVarName\fR argument is given, then the variable it
+names is set to a dictionary of return options returned by evaluation
+of \fIscript\fR. Tcl specifies two entries that are always
+defined in the dictionary: \fB\-code\fR and \fB\-level\fR. When
+the return code from evaluation of \fIscript\fR is not \fBTCL_RETURN\fR,
+the value of the \fB\-level\fR entry will be 0, and the value
+of the \fB\-code\fR entry will be the same as the return code.
+Only when the return code is \fBTCL_RETURN\fR will the values of
+the \fB\-level\fR and \fB\-code\fR entries be something else, as
+further described in the documentation for the \fBreturn\fR command.
.PP
-Note that \fBcatch\fR catches all exceptions, including those
-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.
-
+When the return code from evaluation of \fIscript\fR is \fBTCL_ERROR\fR,
+three additional entries are defined in the dictionary of return options
+stored in \fIoptionsVarName\fR: \fB\-errorinfo\fR, \fB\-errorcode\fR,
+and \fB\-errorline\fR. The value of the \fB\-errorinfo\fR entry
+is a formatted stack trace containing more information about
+the context in which the error happened. The formatted stack
+trace is meant to be read by a person. The value of
+the \fB\-errorcode\fR entry is additional information about the
+error stored as a list. The \fB\-errorcode\fR value is meant to
+be further processed by programs, and may not be particularly
+readable by people. The value of the \fB\-errorline\fR entry
+is an integer indicating which line of \fIscript\fR was being
+evaluated when the error occurred. The values of the \fB\-errorinfo\fR
+and \fB\-errorcode\fR entries of the most recent error are also
+available as values of the global variables \fB::errorInfo\fR
+and \fB::errorCode\fR respectively.
+.PP
+Tcl packages may provide commands that set other entries in the
+dictionary of return options, and the \fBreturn\fR command may be
+used by scripts to set return options in addition to those defined
+above.
+.VE 8.5
.SH EXAMPLES
The \fBcatch\fR command may be used in an \fBif\fR to branch based on
the success of a script.
.CS
if { [\fBcatch\fR {open $someFile w} fid] } {
- puts stderr "Could not open $someFile for writing\\n$fid"
+ puts stderr "Could not open $someFile for writing\en$fid"
exit 1
}
.CE
.PP
-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 {} {
- \fBcatch\fR {expr {1 +- }}
-}
-.CE
+There are more complex examples of \fBcatch\fR usage in the
+documentation for the \fBreturn\fR command.
.SH "SEE ALSO"
-break(n), continue(n), error(n), return(n), tclvars(n)
+break(n), continue(n), dict(n), error(n), return(n), tclvars(n)
.SH KEYWORDS
catch, error
diff --git a/doc/chan.n b/doc/chan.n
new file mode 100644
index 0000000..f5d3d54
--- /dev/null
+++ b/doc/chan.n
@@ -0,0 +1,736 @@
+'\"
+'\" Copyright (c) 2005-2006 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+.so man.macros
+.TH chan n 8.5 Tcl "Tcl Built-In Commands"
+.BS
+'\" Note: do not modify the .SH NAME line immediately below!
+.SH NAME
+chan \- Read, write and manipulate channels
+.SH SYNOPSIS
+\fBchan \fIoption\fR ?\fIarg arg ...\fR?
+.BE
+.SH DESCRIPTION
+.PP
+This command provides several operations for reading from, writing to
+and otherwise manipulating open channels (such as have been created
+with the \fBopen\fR and \fBsocket\fR commands, or the default named
+channels \fBstdin\fR, \fBstdout\fR or \fBstderr\fR which correspond to
+the process's standard input, output and error streams respectively).
+\fIOption\fR indicates what to do with the channel; any unique
+abbreviation for \fIoption\fR is acceptable. Valid options are:
+.TP
+\fBchan blocked \fIchannelId\fR
+.
+This tests whether the last input operation on the channel called
+\fIchannelId\fR failed because it would have otherwise caused the
+process to block, and returns 1 if that was the case. It returns 0
+otherwise. Note that this only ever returns 1 when the channel has
+been configured to be non-blocking; all Tcl channels have blocking
+turned on by default.
+.TP
+\fBchan close \fIchannelId\fR
+.
+Close and destroy the channel called \fIchannelId\fR. Note that this
+deletes all existing file-events registered on the channel.
+.RS
+.PP
+As part of closing the channel, all buffered output is flushed to the
+channel's output device, any buffered input is discarded, the
+underlying operating system resource is closed and \fIchannelId\fR
+becomes unavailable for future use.
+.PP
+If the channel is blocking, the command does not return until all
+output is flushed. If the channel is nonblocking and there is
+unflushed output, the channel remains open and the command returns
+immediately; output will be flushed in the background and the channel
+will be closed when all the flushing is complete.
+.PP
+If \fIchannelId\fR is a blocking channel for a command pipeline then
+\fBchan close\fR waits for the child processes to complete.
+.PP
+If the channel is shared between interpreters, then \fBchan close\fR
+makes \fIchannelId\fR unavailable in the invoking interpreter but has
+no other effect until all of the sharing interpreters have closed the
+channel. When the last interpreter in which the channel is registered
+invokes \fBchan close\fR (or \fBclose\fR), the cleanup actions
+described above occur. See the \fBinterp\fR command for a description
+of channel sharing.
+.PP
+Channels are automatically closed when an interpreter is destroyed and
+when the process exits. Channels are switched to blocking mode, to
+ensure that all output is correctly flushed before the process exits.
+.PP
+The command returns an empty string, and may generate an error if
+an error occurs while flushing output. If a command in a command
+pipeline created with \fBopen\fR returns an error, \fBchan close\fR
+generates an error (similar to the \fBexec\fR command.)
+.RE
+.TP
+\fBchan configure \fIchannelId\fR ?\fIoptionName\fR? ?\fIvalue\fR? ?\fIoptionName value\fR?...
+.
+Query or set the configuration options of the channel named
+\fIchannelId\fR.
+.RS
+.PP
+If no \fIoptionName\fR or \fIvalue\fR arguments are supplied, the
+command returns a list containing alternating option names and values
+for the channel. If \fIoptionName\fR is supplied but no \fIvalue\fR
+then the command returns the current value of the given option. If
+one or more pairs of \fIoptionName\fR and \fIvalue\fR are supplied,
+the command sets each of the named options to the corresponding
+\fIvalue\fR; in this case the return value is an empty string.
+.PP
+The options described below are supported for all channels. In
+addition, each channel type may add options that only it supports. See
+the manual entry for the command that creates each type of channels
+for the options that that specific type of channel supports. For
+example, see the manual entry for the \fBsocket\fR command for its
+additional options.
+.TP
+\fB\-blocking\fR \fIboolean\fR
+.
+The \fB\-blocking\fR option determines whether I/O operations on the
+channel can cause the process to block indefinitely. The value of the
+option must be a proper boolean value. Channels are normally in
+blocking mode; if a channel is placed into nonblocking mode it will
+affect the operation of the \fBchan gets\fR, \fBchan read\fR, \fBchan
+puts\fR, \fBchan flush\fR, and \fBchan close\fR commands; see the
+documentation for those commands for details. For nonblocking mode to
+work correctly, the application must be 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 \fBchan flush\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. Additionally, \fBstdin\fR and
+\fBstdout\fR are initially 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 a number of no more than one
+million, allowing buffers of up to one million bytes in size.
+.TP
+\fB\-encoding\fR \fIname\fR
+.
+This option is used to specify the encoding of the channel as one of
+the named encodings returned by \fBencoding names\fR or the special
+value \fBbinary\fR, 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. It is usually better to set the
+\fB\-translation\fR option to \fBbinary\fR when you want to transfer
+binary data, as this turns off the other automatic interpretations of
+the bytes in the stream as well.
+.PP
+The default encoding for newly opened channels is the same platform-
+and locale-dependent system encoding used for interfacing with the
+operating system, as returned by \fBencoding system\fR.
+.RE
+.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.
+The acceptable range for \fB\-eofchar\fR values is \ex01 - \ex7f;
+attempting to set \fB\-eofchar\fR to a value outside of this range will
+generate an error.
+.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 \fBchan gets\fR and \fBchan read\fR) the Tcl I/O system
+automatically translates the external end-of-line representation into
+newline characters. Upon output (i.e., with \fBchan puts\fR), the I/O
+system translates newlines to the external end-of-line representation.
+The default translation mode, \fBauto\fR, 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:
+.TP
+\fBauto\fR
+.
+As the input translation mode, \fBauto\fR treats any of newline
+(\fBlf\fR), carriage return (\fBcr\fR), or carriage return followed by
+a newline (\fBcrlf\fR) 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, 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.
+.TP
+\fBbinary\fR
+.
+No end-of-line translations are performed. This is nearly identical
+to \fBlf\fR mode, except that in addition \fBbinary\fR mode also sets
+the 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.
+.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\fR mode converts carriage returns to newline characters. As the
+output translation mode, \fBcr\fR mode translates newline characters
+to carriage returns.
+.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\fR mode converts
+carriage-return-linefeed sequences to newline characters. As the
+output translation mode, \fBcrlf\fR 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.
+.RE
+.RE
+.TP
+\fBchan copy \fIinputChan outputChan\fR ?\fB\-size \fIsize\fR? ?\fB\-command \fIcallback\fR?
+.
+Copy data from the channel \fIinputChan\fR, which must have been
+opened for reading, to the channel \fIoutputChan\fR, which must have
+been opened for writing. The \fBchan copy\fR command leverages the
+buffering in the Tcl I/O system to avoid extra copies and to avoid
+buffering too much data in main memory when copying large files to
+slow destinations like network sockets.
+.RS
+.PP
+The \fBchan copy\fR command transfers data from \fIinputChan\fR until
+end of file or \fIsize\fR bytes have been transferred. If no
+\fB\-size\fR argument is given, then the copy goes until end of file.
+All the data read from \fIinputChan\fR is copied to \fIoutputChan\fR.
+Without the \fB\-command\fR option, \fBchan copy\fR blocks until the
+copy is complete and returns the number of bytes written to
+\fIoutputChan\fR.
+.PP
+The \fB\-command\fR argument makes \fBchan copy\fR work in the
+background. In this case it returns immediately and the
+\fIcallback\fR is invoked later when the copy completes. The
+\fIcallback\fR is called with one or two additional arguments that
+indicates how many bytes were written to \fIoutputChan\fR. If an
+error occurred during the background copy, the second argument is the
+error string associated with the error. With a background copy, it is
+not necessary to put \fIinputChan\fR or \fIoutputChan\fR into
+non-blocking mode; the \fBchan copy\fR command takes care of that
+automatically. However, it is necessary to enter the event loop by
+using the \fBvwait\fR command or by using Tk.
+.PP
+You are not allowed to do other I/O operations with \fIinputChan\fR or
+\fIoutputChan\fR during a background \fBchan copy\fR. If either
+\fIinputChan\fR or \fIoutputChan\fR get closed while the copy is in
+progress, the current copy is stopped and the command callback is
+\fInot\fR made. If \fIinputChan\fR is closed, then all data already
+queued for \fIoutputChan\fR is written out.
+.PP
+Note that \fIinputChan\fR can become readable during a background
+copy. You should turn off any \fBchan event\fR or \fBfileevent\fR
+handlers during a background copy so those handlers do not interfere
+with the copy. Any I/O attempted by a \fBchan event\fR or
+\fBfileevent\fR handler will get a
+.QW "channel busy"
+error.
+.PP
+\fBChan copy\fR translates end-of-line sequences in \fIinputChan\fR
+and \fIoutputChan\fR according to the \fB\-translation\fR option for
+these channels (see \fBchan configure\fR above). The translations
+mean that the number of bytes read from \fIinputChan\fR can be
+different than the number of bytes written to \fIoutputChan\fR. Only
+the number of bytes written to \fIoutputChan\fR is reported, either as
+the return value of a synchronous \fBchan copy\fR or as the argument
+to the callback for an asynchronous \fBchan copy\fR.
+.PP
+\fBChan copy\fR obeys the encodings and character translations
+configured for the channels. This means that the incoming characters
+are converted internally first UTF-8 and then into the encoding of the
+channel \fBchan copy\fR writes to (see \fBchan configure\fR above for
+details on the \fB\-encoding\fR and \fB\-translation\fR options). No
+conversion is done if both channels are set to encoding \fBbinary\fR
+and have matching translations. If only the output channel is set to
+encoding \fBbinary\fR the system will write the internal UTF-8
+representation of the incoming characters. If only the input channel
+is set to encoding \fBbinary\fR the system will assume that the
+incoming bytes are valid UTF-8 characters and convert them according
+to the output encoding. The behaviour of the system for bytes which
+are not valid UTF-8 characters is undefined in this case.
+.RE
+.TP
+\fBchan create \fImode cmdPrefix\fR
+.
+This subcommand creates a new script level channel using the command
+prefix \fIcmdPrefix\fR as its handler. Any such channel is called a
+\fBreflected\fR channel. The specified command prefix, \fBcmdPrefix\fR,
+must be a non-empty list, and should provide the API described in the
+\fBreflectedchan\fR manual page. The handle of the new channel is
+returned as the result of the \fBchan create\fR command, and the
+channel is open. Use either \fBclose\fR or \fBchan close\fR to remove
+the channel.
+.RS
+.PP
+The argument \fImode\fR specifies if the new channel is opened for
+reading, writing, or both. It has to be a list containing any of the
+strings
+.QW \fBread\fR
+or
+.QW \fBwrite\fR .
+The list must have at least one
+element, as a channel you can neither write to nor read from makes no
+sense. The handler command for the new channel must support the chosen
+mode, or an error is thrown.
+.PP
+The command prefix is executed in the global namespace, at the top of
+call stack, following the appending of arguments as described in the
+\fBreflectedchan\fR manual page. Command resolution happens at the
+time of the call. Renaming the command, or destroying it means that
+the next call of a handler method may fail, causing the channel
+command invoking the handler to fail as well. Depending on the
+subcommand being invoked, the error message may not be able to explain
+the reason for that failure.
+.PP
+Every channel created with this subcommand knows which interpreter it
+was created in, and only ever executes its handler command in that
+interpreter, even if the channel was shared with and/or was moved into
+a different interpreter. Each reflected channel also knows the thread
+it was created in, and executes its handler command only in that
+thread, even if the channel was moved into a different thread. To this
+end all invocations of the handler are forwarded to the original
+thread by posting special events to it. This means that the original
+thread (i.e. the thread that executed the \fBchan create\fR command)
+must have an active event loop, i.e. it must be able to process such
+events. Otherwise the thread sending them will \fIblock
+indefinitely\fR. Deadlock may occur.
+.PP
+Note that this permits the creation of a channel whose two endpoints
+live in two different threads, providing a stream-oriented bridge
+between these threads. In other words, we can provide a way for
+regular stream communication between threads instead of having to send
+commands.
+.PP
+When a thread or interpreter is deleted, all channels created with
+this subcommand and using this thread/interpreter as their computing
+base are deleted as well, in all interpreters they have been shared
+with or moved into, and in whatever thread they have been transfered
+to. While this pulls the rug out under the other thread(s) and/or
+interpreter(s), this cannot be avoided. Trying to use such a channel
+will cause the generation of a regular error about unknown channel
+handles.
+.PP
+This subcommand is \fBsafe\fR and made accessible to safe
+interpreters. While it arranges for the execution of arbitrary Tcl
+code the system also makes sure that the code is always executed
+within the safe interpreter.
+.RE
+.TP
+\fBchan eof \fIchannelId\fR
+.
+Test whether the last input operation on the channel called
+\fIchannelId\fR failed because the end of the data stream was reached,
+returning 1 if end-of-file was reached, and 0 otherwise.
+.TP
+\fBchan event \fIchannelId event\fR ?\fIscript\fR?
+.
+Arrange for the Tcl script \fIscript\fR to be installed as a \fIfile
+event handler\fR to be called whenever the channel called
+\fIchannelId\fR enters the state described by \fIevent\fR (which must
+be either \fBreadable\fR or \fBwritable\fR); only one such handler may
+be installed per event per channel at a time. If \fIscript\fR is the
+empty string, the current handler is deleted (this also happens if the
+channel is closed or the interpreter deleted). If \fIscript\fR is
+omitted, the currently installed script is returned (or an empty
+string if no such handler is installed). The callback is only
+performed if the event loop is being serviced (e.g. via \fBvwait\fR or
+\fBupdate\fR).
+.RS
+.PP
+A file event handler is a binding between a channel and a script, such
+that the script is evaluated whenever the channel becomes readable or
+writable. File event handlers are most commonly used to allow data to
+be received from another process on an event-driven basis, so that the
+receiver can continue to interact with the user or with other channels
+while waiting for the data to arrive. If an application invokes
+\fBchan gets\fR or \fBchan read\fR on a blocking channel when there is
+no input data available, the process will block; until the input data
+arrives, it will not be able to service other events, so it will
+appear to the user to
+.QW "freeze up" .
+With \fBchan event\fR, the
+process can tell when data is present and only invoke \fBchan gets\fR
+or \fBchan read\fR when they will not block.
+.PP
+A channel is considered to be readable if there is unread data
+available on the underlying device. A channel is also considered to
+be readable if there is unread data in an input buffer, except in the
+special case where the most recent attempt to read from the channel
+was a \fBchan gets\fR call that could not find a complete line in the
+input buffer. This feature allows a file to be read a line at a time
+in nonblocking mode using events. A channel is also considered to be
+readable if an end of file or error condition is present on the
+underlying file or device. It is important for \fIscript\fR to check
+for these conditions and handle them appropriately; for example, if
+there is no special check for end of file, an infinite loop may occur
+where \fIscript\fR reads no data, returns, and is immediately invoked
+again.
+.PP
+A channel is considered to be writable if at least one byte of data
+can be written to the underlying file or device without blocking, or
+if an error condition is present on the underlying file or device.
+Note that client sockets opened in asynchronous mode become writable
+when they become connected or if the connection fails.
+.PP
+Event-driven I/O works best for channels that have been placed into
+nonblocking mode with the \fBchan configure\fR command. In blocking
+mode, a \fBchan puts\fR command may block if you give it more data
+than the underlying file or device can accept, and a \fBchan gets\fR
+or \fBchan read\fR command will block if you attempt to read more data
+than is ready; no events will be processed while the commands block.
+In nonblocking mode \fBchan puts\fR, \fBchan read\fR, and \fBchan
+gets\fR never block.
+.PP
+The script for a file event is executed at global level (outside the
+context of any Tcl procedure) in the interpreter in which the \fBchan
+event\fR command was invoked. If an error occurs while executing the
+script then the command registered with \fBinterp bgerror\fR is used
+to report the error. In addition, the file event handler is deleted
+if it ever returns an error; this is done in order to prevent infinite
+loops due to buggy handlers.
+.RE
+.TP
+\fBchan flush \fIchannelId\fR
+.
+Ensures that all pending output for the channel called \fIchannelId\fR
+is written.
+.RS
+.PP
+If the channel is in blocking mode the command does not return until
+all the buffered output has been flushed to the channel. If the
+channel is in nonblocking mode, the command may return before all
+buffered output has been flushed; the remainder will be flushed in the
+background as fast as the underlying file or device is able to absorb
+it.
+.RE
+.TP
+\fBchan gets \fIchannelId\fR ?\fIvarName\fR?
+.
+Reads the next line from the channel called \fIchannelId\fR. If
+\fIvarName\fR is not specified, the result of the command will be the
+line that has been read (without a trailing newline character) or an
+empty string upon end-of-file or, in non-blocking mode, if the data
+available is exhausted. If \fIvarName\fR is specified, the line that
+has been read will be written to the variable called \fIvarName\fR and
+result will be the number of characters that have been read or -1 if
+end-of-file was reached or, in non-blocking mode, if the data
+available is exhausted.
+.RS
+.PP
+If an end-of-file occurs while part way through reading a line, the
+partial line will be returned (or written into \fIvarName\fR). When
+\fIvarName\fR is not specified, the end-of-file case can be
+distinguished from an empty line using the \fBchan eof\fR command, and
+the partial-line-but-nonblocking case can be distinguished with the
+\fBchan blocked\fR command.
+.RE
+.TP
+\fBchan names\fR ?\fIpattern\fR?
+.
+Produces a list of all channel names. If \fIpattern\fR is specified,
+only those channel names that match it (according to the rules of
+\fBstring match\fR) will be returned.
+.TP
+\fBchan pending \fImode channelId\fR
+.
+Depending on whether \fImode\fR is \fBinput\fR or \fBoutput\fR,
+returns the number of
+bytes of input or output (respectively) currently buffered
+internally for \fIchannelId\fR (especially useful in a readable event
+callback to impose application-specific limits on input line lengths to avoid
+a potential denial-of-service attack where a hostile user crafts
+an extremely long line that exceeds the available memory to buffer it).
+Returns -1 if the channel was not opened for the mode in question.
+.TP
+\fBchan postevent \fIchannelId eventSpec\fR
+.
+This subcommand is used by command handlers specified with \fBchan
+create\fR. It notifies the channel represented by the handle
+\fIchannelId\fR that the event(s) listed in the \fIeventSpec\fR have
+occurred. The argument has to be a list containing any of the strings
+\fBread\fR and \fBwrite\fR. The list must contain at least one
+element as it does not make sense to invoke the command if there are
+no events to post.
+.RS
+.PP
+Note that this subcommand can only be used with channel handles that
+were created/opened by \fBchan create\fR. All other channels will
+cause this subcommand to report an error.
+.PP
+As only the Tcl level of a channel, i.e. its command handler, should
+post events to it we also restrict the usage of this command to the
+interpreter that created the channel. In other words, posting events
+to a reflected channel from an interpreter that does not contain it's
+implementation is not allowed. Attempting to post an event from any
+other interpreter will cause this subcommand to report an error.
+.PP
+Another restriction is that it is not possible to post events that the
+I/O core has not registered an interest in. Trying to do so will cause
+the method to throw an error. See the command handler method
+\fBwatch\fR described in \fBreflectedchan\fR, the document specifying
+the API of command handlers for reflected channels.
+.PP
+This command is \fBsafe\fR and made accessible to safe interpreters.
+It can trigger the execution of \fBchan event\fR handlers, whether in the
+current interpreter or in other interpreters or other threads, even
+where the event is posted from a safe interpreter and listened for by
+a trusted interpreter. \fBChan event\fR handlers are \fIalways\fR
+executed in the interpreter that set them up.
+.RE
+.TP
+\fBchan puts\fR ?\fB\-nonewline\fR? ?\fIchannelId\fR? \fIstring\fR
+.
+Writes \fIstring\fR to the channel named \fIchannelId\fR followed by a
+newline character. A trailing newline character is written unless the
+optional flag \fB\-nonewline\fR is given. If \fIchannelId\fR is
+omitted, the string is written to the standard output channel,
+\fBstdout\fR.
+.RS
+.PP
+Newline characters in the output are translated by \fBchan puts\fR to
+platform-specific end-of-line sequences according to the currently
+configured value of the \fB\-translation\fR option for the channel
+(for example, on PCs newlines are normally replaced with
+carriage-return-linefeed sequences; see \fBchan configure\fR above for
+details).
+.PP
+Tcl buffers output internally, so characters written with \fBchan
+puts\fR may not appear immediately on the output file or device; Tcl
+will normally delay output until the buffer is full or the channel is
+closed. You can force output to appear immediately with the \fBchan
+flush\fR command.
+.PP
+When the output buffer fills up, the \fBchan puts\fR command will
+normally block until all the buffered data has been accepted for
+output by the operating system. If \fIchannelId\fR is in nonblocking
+mode then the \fBchan puts\fR command will not block even if the
+operating system cannot accept the data. Instead, Tcl continues to
+buffer the data and writes it in the background as fast as the
+underlying file or device can accept it. The application must use the
+Tcl event loop for nonblocking output to work; otherwise Tcl never
+finds out that the file or device is ready for more output data. It
+is possible for an arbitrarily large amount of data to be buffered for
+a channel in nonblocking mode, which could consume a large amount of
+memory. To avoid wasting memory, nonblocking I/O should normally be
+used in an event-driven fashion with the \fBchan event\fR command
+(do not invoke \fBchan puts\fR unless you have recently been notified
+via a file event that the channel is ready for more output data).
+.RE
+.TP
+\fBchan read \fIchannelId\fR ?\fInumChars\fR?
+.TP
+\fBchan read \fR?\fB\-nonewline\fR? \fIchannelId\fR
+.
+In the first form, the result will be the next \fInumChars\fR
+characters read from the channel named \fIchannelId\fR; if
+\fInumChars\fR is omitted, all characters up to the point when the
+channel would signal a failure (whether an end-of-file, blocked or
+other error condition) are read. In the second form (i.e. when
+\fInumChars\fR has been omitted) the flag \fB\-nonewline\fR may be
+given to indicate that any trailing newline in the string that has
+been read should be trimmed.
+.RS
+.PP
+If \fIchannelId\fR is in nonblocking mode, \fBchan read\fR 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. The \fB\-nonewline\fR switch is ignored if
+the command returns before reaching the end of the file.
+.PP
+\fBChan read\fR translates end-of-line sequences in the input into
+newline characters according to the \fB\-translation\fR option for the
+channel (see \fBchan configure\fR above for a discussion on the ways
+in which \fBchan configure\fR will alter input).
+.PP
+When reading from a serial port, most applications should configure
+the serial port channel to be nonblocking, like this:
+.CS
+\fBchan configure \fIchannelId \fB\-blocking \fI0\fR.
+.CE
+Then \fBchan read\fR behaves much like described above. Note that
+most serial ports are comparatively slow; it is entirely possible to
+get a \fBreadable\fR event for each character read from them. Care
+must be taken when using \fBchan read\fR on blocking serial ports:
+.TP
+\fBchan read \fIchannelId numChars\fR
+.
+In this form \fBchan read\fR blocks until \fInumChars\fR have been
+received from the serial port.
+.TP
+\fBchan read \fIchannelId\fR
+.
+In this form \fBchan read\fR blocks until the reception of the
+end-of-file character, see \fBchan configure -eofchar\fR. If there no
+end-of-file character has been configured for the channel, then
+\fBchan read\fR will block forever.
+.RE
+.TP
+\fBchan seek \fIchannelId offset\fR ?\fIorigin\fR?
+.
+Sets the current access position within the underlying data stream for
+the channel named \fIchannelId\fR to be \fIoffset\fR bytes relative to
+\fIorigin\fR. \fIOffset\fR must be an integer (which may be negative)
+and \fIorigin\fR must be one of the following:
+.RS
+.TP 10
+\fBstart\fR
+.
+The new access position will be \fIoffset\fR bytes from the start
+of the underlying file or device.
+.TP 10
+\fBcurrent\fR
+.
+The new access position will be \fIoffset\fR bytes from the current
+access position; a negative \fIoffset\fR moves the access position
+backwards in the underlying file or device.
+.TP 10
+\fBend\fR
+.
+The new access position will be \fIoffset\fR bytes from the end of the
+file or device. A negative \fIoffset\fR places the access position
+before the end of file, and a positive \fIoffset\fR places the access
+position after the end of file.
+.PP
+The \fIorigin\fR argument defaults to \fBstart\fR.
+.PP
+\fBChan seek\fR flushes all buffered output for the channel before the
+command returns, even if the channel is in nonblocking mode. 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
+Note that \fIoffset\fR values are byte offsets, not character offsets.
+Both \fBchan seek\fR and \fBchan tell\fR operate in terms of bytes,
+not characters, unlike \fBchan read\fR.
+.RE
+.TP
+\fBchan tell \fIchannelId\fR
+.
+Returns a number giving the current access position within the
+underlying data stream for the channel named \fIchannelId\fR. This
+value returned is a byte offset that can be passed to \fBchan seek\fR
+in order to set the channel to a particular position. Note that this
+value is in terms of bytes, not characters like \fBchan read\fR. The
+value returned is -1 for channels that do not support seeking.
+.TP
+\fBchan truncate \fIchannelId\fR ?\fIlength\fR?
+.
+Sets the byte length of the underlying data stream for the channel
+named \fIchannelId\fR to be \fIlength\fR (or to the current byte
+offset within the underlying data stream if \fIlength\fR is
+omitted). The channel is flushed before truncation.
+.SH EXAMPLE
+This opens a file using a known encoding (CP1252, a very common encoding
+on Windows), searches for a string, rewrites that part, and truncates the
+file after a further two lines.
+.PP
+.CS
+set f [open somefile.txt r+]
+\fBchan configure\fR $f -encoding cp1252
+set offset 0
+
+\fI# Search for string "FOOBAR" in the file\fR
+while {[\fBchan gets\fR $f line] >= 0} {
+ set idx [string first FOOBAR $line]
+ if {$idx > -1} {
+ \fI# Found it; rewrite line\fR
+
+ \fBchan seek\fR $f [expr {$offset + $idx}]
+ \fBchan puts\fR -nonewline $f BARFOO
+
+ \fI# Skip to end of following line, and truncate\fR
+ \fBchan gets\fR $f
+ \fBchan gets\fR $f
+ \fBchan truncate\fR $f
+
+ \fI# Stop searching the file now\fR
+ break
+ }
+
+ \fI# Save offset of start of next line for later\fR
+ set offset [\fBchan tell\fR $f]
+}
+\fBchan close\fR $f
+.CE
+.SH "SEE ALSO"
+close(n), eof(n), fblocked(n), fconfigure(n), fcopy(n), file(n),
+fileevent(n), flush(n), gets(n), open(n), puts(n), read(n), seek(n),
+socket(n), tell(n), refchan(n)
+.SH KEYWORDS
+channel, input, output, events, offset
diff --git a/doc/clock.n b/doc/clock.n
index 8e00c43..600722b 100644
--- a/doc/clock.n
+++ b/doc/clock.n
@@ -1,259 +1,890 @@
'\"
-'\" Copyright (c) 1992-1995 Karl Lehenbauer and Mark Diekhans.
-'\" Copyright (c) 1995-1997 Sun Microsystems, Inc.
-'\" Copyright (c) 1998-1999 Scriptics Corporation
-'\" Copyright (c) 2002 ActiveState Corporation
+'\" Generated from file './doc/clock.dt' by tcllib/doctools with format 'nroff'
+'\" Copyright (c) 2004 Kevin B. Kenny <kennykb@acm.org>. All rights reserved.
'\"
-'\" This documentation is derived from the time and date facilities of
-'\" TclX, by Mark Diekhans and Karl Lehenbauer.
-'\"
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\"
.so man.macros
-.TH clock n 8.4 Tcl "Tcl Built-In Commands"
+.TH "clock" n 8.5 Tcl "Tcl Built-In Commands"
.BS
-'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
-clock \- Obtain and manipulate time
-.SH SYNOPSIS
-\fBclock \fIoption\fR ?\fIarg arg ...\fR?
+clock \- Obtain and manipulate dates and times
+.SH "SYNOPSIS"
+package require \fBTcl 8.5\fR
+.sp
+\fBclock add\fR \fItimeVal\fR ?\fIcount unit...\fR? ?\fI\-option value\fR?
+.sp
+\fBclock clicks\fR ?\fI\-option\fR?
+.sp
+\fBclock format\fR \fItimeVal\fR ?\fI\-option value\fR...?
+.sp
+\fBclock microseconds\fR
+.sp
+\fBclock milliseconds\fR
+.sp
+\fBclock scan\fR \fIinputString\fR ?\fI\-option value\fR...?
+.sp
+\fBclock seconds\fR
+.sp
.BE
-
-.SH DESCRIPTION
-.PP
-This command performs one of several operations that may obtain
-or manipulate strings or values that represent some notion of
-time. The \fIoption\fR argument determines what action is carried
-out by the command. The legal \fIoptions\fR (which may be
-abbreviated) are:
-.VS 8.3
-.TP
-\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. 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
-\fBclock seconds\fR, \fBclock scan\fR, or the \fBatime\fR or \fBmtime\fR
-options of the \fBfile\fR command, to human-readable
-form. If the \fB\-format\fR argument is present the next argument is a
-string that describes how the date and time are to be formatted.
-Field descriptors consist of a \fB%\fR followed by a field
-descriptor character. All other characters are copied into the result.
-Valid field descriptors are:
+.SH "DESCRIPTION"
+.PP
+The \fBclock\fR command performs several operations that obtain and
+manipulate values that represent times. The command supports several
+subcommands that determine what action is carried out by the command.
+.TP
+\fBclock add\fR \fItimeVal\fR ?\fIcount unit...\fR? ?\fI\-option value\fR?
+Adds a (possibly negative) offset to a time that is expressed as an
+integer number of seconds. See \fBCLOCK ARITHMETIC\fR for a full description.
+.TP
+\fBclock clicks\fR ?\fI\-option\fR?
+If no \fI\-option\fR argument is supplied, returns 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. See \fBHIGH RESOLUTION TIMERS\fR for a full description.
.RS
-.IP \fB%%\fR
-Insert a %.
-.IP \fB%a\fR
-Abbreviated weekday name (Mon, Tue, etc.).
-.IP \fB%A\fR
-Full weekday name (Monday, Tuesday, etc.).
-.IP \fB%b\fR
-Abbreviated month name (Jan, Feb, etc.).
-.IP \fB%B\fR
-Full month name.
-.VS 8.4
-.IP \fB%c\fR
-Locale specific date and time. The format for date and time
-in the default "C" locale on Unix/Mac is "%a %b %d %H:%M:%S %Y".
-On Windows, this value is the locale specific long date and time, as
-specified in the Regional Options control panel settings.
-.IP \fB%C\fR
-First two digits of the four-digit year (19 or 20).
-.VE 8.4
-.IP \fB%d\fR
-Day of month (01 - 31).
-.VS 8.4
-'\" Since the inclusion of compat/strftime.c, %D, %e, %h should work on all
-'\" platforms.
-.IP \fB%D\fR
-Date as %m/%d/%y.
-.IP \fB%e\fR
-Day of month (1 - 31), no leading zeros.
-.IP \fB%g\fR
-The ISO8601 year number corresponding to the ISO8601 week (%V), expressed
-as a two-digit year-of-the-century, with leading zero if necessary.
-.IP \fB%G\fR
-The ISO8601 year number corresponding to the ISO8601 week (%V), expressed
-as a four-digit number.
-.IP \fB%h\fR
-Abbreviated month name.
-.VE 8.4
-.IP \fB%H\fR
-Hour in 24-hour format (00 - 23).
-.VS 8.4
-.IP \fB%I\fR
-Hour in 12-hour format (01 - 12).
-.VE 8.4
-.IP \fB%j\fR
-Day of year (001 - 366).
-.VS 8.4
-.IP \fB%k\fR
-Hour in 24-hour format, without leading zeros (0 - 23).
-.IP \fB%l\fR
-Hour in 12-hour format, without leading zeros (1 - 12).
-.VE 8.4
-.IP \fB%m\fR
-Month number (01 - 12).
-.IP \fB%M\fR
-Minute (00 - 59).
-.VS 8.4
-.IP \fB%n\fR
-Insert a newline.
-.VE 8.4
-.IP \fB%p\fR
-AM/PM indicator.
-.VS 8.4
-.IP \fB%r\fR
-Time in a locale-specific "meridian" format. The "meridian"
-format in the default "C" locale is "%I:%M:%S %p".
-.IP \fB%R\fR
-Time as %H:%M.
-.IP \fB%s\fR
-Count of seconds since the epoch, expressed as a decimal integer.
-.VE 8.4
-.IP \fB%S\fR
-Seconds (00 - 59).
-.VS 8.4
-.IP \fB%t\fR
-Insert a tab.
-.IP \fB%T\fR
-Time as %H:%M:%S.
-.IP \fB%u\fR
-Weekday number (Monday = 1, Sunday = 7).
-.VE 8.4
-.IP \fB%U\fR
-Week of year (00 - 52), Sunday is the first day of the week.
-.VS 8.4
-.IP \fB%V\fR
-Week of year according to ISO-8601 rules. Week 1 of a given
-year is the week containing 4 January.
-.IP \fB%w\fR
-Weekday number (Sunday = 0, Saturday = 6).
-.VE 8.4
-.IP \fB%W\fR
-Week of year (00 - 52), Monday is the first day of the week.
-.VS 8.4
-.IP \fB%x\fR
-Locale specific date format. The format for a date in the default "C"
-locale for Unix/Mac is "%m/%d/%y".
-On Windows, this value is the locale specific short date format, as
-specified in the Regional Options control panel settings.
-.IP \fB%X\fR
-Locale specific 24-hour time format. The format for a
-24-hour time in the default "C" locale for Unix/Mac is "%H:%M:%S".
-On Windows, this value is the locale specific time format, as
-specified in the Regional Options control panel settings.
-.VE 8.4
-.IP \fB%y\fR
-Year without century (00 - 99).
-.IP \fB%Y\fR
-Year with century (e.g. 1990)
-.IP \fB%Z\fR
-Time zone name.
+.PP
+If the \fI\-option\fR argument is \fI\-milliseconds\fR, then the command
+is synonymous with \fBclock milliseconds\fR (see below). This
+usage is obsolete, and \fBclock milliseconds\fR is to be
+considered the preferred way of obtaining a count of milliseconds.
+.PP
+If the \fI\-option\fR argument is \fI\-microseconds\fR, then the command
+is synonymous with \fBclock microseconds\fR (see below). This
+usage is obsolete, and \fBclock microseconds\fR is to be
+considered the preferred way of obtaining a count of microseconds.
.RE
-.VS 8.4
-.sp
-'\" All the field descriptors should be portable now that
-'\" compat/strftime.c is in place, with the possible exception
-'\" of the time zone name.
-'\".RS
-'\"In addition, the following field descriptors may be supported on some
-'\"systems (e.g. Unix but not Windows):
-'\".IP \fB%D\fR
-'\"Date as %m/%d/%y.
-'\".IP \fB%e\fR
-'\"Day of month (1 - 31), no leading zeros.
-'\".IP \fB%h\fR
-'\"Abbreviated month name.
-'\".IP \fB%n\fR
-'\"Insert a newline.
-'\".IP \fB%r\fR
-'\"Time as %I:%M:%S %p.
-'\".IP \fB%R\fR
-'\"Time as %H:%M.
-'\".IP \fB%t\fR
-'\"Insert a tab.
-'\".IP \fB%T\fR
-'\"Time as %H:%M:%S.
-'\".RE
-'\".sp
-.VE 8.4
+.TP
+\fBclock format\fR \fItimeVal\fR ?\fI\-option value\fR...?
+Formats a time that is expressed as an integer number of seconds into a format
+intended for consumption by users or external programs.
+See \fBFORMATTING TIMES\fR for a full description.
+.TP
+\fBclock microseconds\fR
+Returns the current time as an integer number of microseconds. See \fBHIGH RESOLUTION TIMERS\fR for a full description.
+.TP
+\fBclock milliseconds\fR
+Returns the current time as an integer number of milliseconds. See \fBHIGH RESOLUTION TIMERS\fR for a full description.
+.TP
+\fBclock scan\fR \fIinputString\fR ?\fI\-option value\fR...?
+Scans a time that is expressed as a character string and produces an
+integer number of seconds.
+See \fBSCANNING TIMES\fR for a full description.
+.TP
+\fBclock seconds\fR
+Returns the current time as an integer number of seconds.
+.SS "PARAMETERS"
+.TP
+\fIcount\fR
+An integer representing a count of some unit of time. See
+\fBCLOCK ARITHMETIC\fR for the details.
+.TP
+\fItimeVal\fR
+An integer value passed to the \fBclock\fR command that represents an
+absolute time as a number of seconds from the \fIepoch time\fR of
+1 January 1970, 00:00 UTC. Note that the count of seconds does not
+include any leap seconds; seconds are counted as if each UTC day has
+exactly 86400 seconds. Tcl responds to leap seconds by speeding or
+slowing its clock by a tiny fraction for some minutes until it is
+back in sync with UTC; its data model does not represent minutes that
+have 59 or 61 seconds.
+.TP
+\fIunit\fR
+One of the words, \fBseconds\fR, \fBminutes\fR, \fBhours\fR,
+\fBdays\fR, \fBweeks\fR, \fBmonths\fR, or \fByears\fR, or
+any unique prefix of such a word. Used in conjunction with \fIcount\fR
+to identify an interval of time, for example, \fI3 seconds\fR or
+\fI1 year\fR.
+.SS "OPTIONS"
+.TP
+\fB\-base\fR time
+Specifies that any relative times present in a \fBclock scan\fR command
+are to be given relative to \fItime\fR. \fItime\fR must be expressed as
+a count of nominal seconds from the epoch time of 1 January 1970, 00:00 UTC.
+.TP
+\fB\-format\fR format
+Specifies the desired output format for \fBclock format\fR or the
+expected input format for \fBclock scan\fR. The \fIformat\fR string consists
+of any number of characters other than the per-cent sign
+.PQ \fB%\fR
+interspersed with any number of \fIformat groups\fR, which are two-character
+sequences beginning with the per-cent sign. The permissible format groups,
+and their interpretation, are described under \fBFORMAT GROUPS\fR.
+.RS
+.PP
+On \fBclock format\fR, the default format is
+.CS
+%a %b %d %H:%M:%S %z %Y
+.CE
+.PP
+On \fBclock scan\fR, the lack of a \fI\-format\fR option indicates that a
+.QW "free format scan"
+is requested; see \fBFREE FORM SCAN\fR for a description of what happens.
+.RE
+.TP
+\fB\-gmt\fR boolean
+If \fIboolean\fR is true, specifies that a time specified to \fBclock add\fR,
+\fBclock format\fR or \fBclock scan\fR should be processed in
+UTC. If \fIboolean\fR is false, the processing defaults to the local time
+zone. This usage is obsolete; the correct current usage is to
+specify the UTC time zone with
+.QW "\fB\-timezone\fR \fI:UTC\fR"
+or any of the equivalent ways to specify it.
+.TP
+\fB\-locale\fR localeName
+Specifies that locale-dependent scanning and formatting (and date arithmetic
+for dates preceding the adoption of the Gregorian calendar) is to be done in
+the locale identified by \fIlocaleName\fR. The locale name may be any of
+the locales acceptable to the \fBmsgcat\fR package, or it may be the special
+name \fIsystem\fR, which represents the current locale of the process, or
+the null string, which represents Tcl's default locale.
+.RS
+.PP
+The effect of locale on scanning and formatting is discussed in the
+descriptions of the individual format groups under \fBFORMAT GROUPS\fR.
+The effect of locale on clock arithmetic is discussed under
+\fBCLOCK ARITHMETIC\fR.
+.RE
+.TP
+\fB\-timezone\fR zoneName
+Specifies that clock arithmetic, formatting, and scanning are to be done
+according to the rules for the time zone specified by \fIzoneName\fR.
+The permissible values, and their interpretation, are discussed under
+\fBTIME ZONES\fR.
+On subcommands that expect a \fB\-timezone\fR argument, the default
+is to use the \fIcurrent time zone\fR. The current time zone is
+determined, in order of preference, by:
.RS
-If the \fB\-format\fR argument is not specified, the format string
-\fB"%a %b %d %H:%M:%S %Z %Y"\fR is used. If the \fB\-gmt\fR argument
-is present the next argument must be a boolean which if true specifies
-that the time will be formatted as Greenwich Mean Time. If false
-then the local timezone will be used as defined by the operating
-environment.
+.IP [1]
+the environment variable \fBTCL_TZ\fR.
+.IP [2]
+the environment variable \fBTZ\fR.
+.IP [3]
+on Windows systems, the time zone settings from the Control Panel.
.RE
+If none of these is present, the C \fBlocaltime\fR and \fBmktime\fR
+functions are used to attempt to convert times between local and
+Greenwich. On 32-bit systems, this approach is likely to have bugs,
+particularly for times that lie outside the window (approximately the
+years 1902 to 2037) that can be represented in a 32-bit integer.
+.SH "CLOCK ARITHMETIC"
+The \fBclock add\fR command performs clock arithmetic on a value
+(expressed as nominal seconds from the epoch time of 1 January 1970, 00:00 UTC)
+given as its first argument. The remaining arguments (other than the
+possible \fB\-timezone\fR, \fB\-locale\fR and \fB\-gmt\fR options)
+are integers and keywords in alternation, where the keywords are chosen
+from \fBseconds\fR, \fBminutes\fR, \fBhours\fR,
+\fBdays\fR, \fBweeks\fR, \fBmonths\fR, or \fByears\fR, or
+any unique prefix of such a word.
+.PP
+Addition of seconds, minutes and hours is fairly straightforward;
+the given time increment (times sixty for minutes, or 3600 for hours)
+is simply added to the \fItimeVal\fR given
+to the \fBclock add\fR command. The result is interpreted as
+a nominal number of seconds from the Epoch.
+.PP
+Surprising results
+may be obtained when crossing a point at which a leap second is
+inserted or removed; the \fBclock add\fR command simply ignores
+leap seconds and therefore assumes that times come in sequence,
+23:59:58, 23:59:59, 00:00:00. (This assumption is handled by
+the fact that Tcl's model of time reacts to leap seconds by speeding
+or slowing the clock by a minuscule amount until Tcl's time
+is back in step with the world.
+.PP
+The fact that adding and subtracting hours is defined in terms of
+absolute time means that it will add fixed amounts of time in time zones
+that observe summer time (Daylight Saving Time). For example,
+the following code sets the value of \fBx\fR to \fB04:00:00\fR because
+the clock has changed in the interval in question.
+.CS
+set s [\fBclock scan\fR {2004-10-30 05:00:00} \e
+ -format {%Y-%m-%d %H:%M:%S} \e
+ -timezone :America/New_York]
+set a [\fBclock add\fR $s 24 hours -timezone :America/New_York]
+set x [\fBclock format\fR $a \e
+ -format {%H:%M:%S} -timezone :America/New_York]
+.CE
+.PP
+Adding and subtracting days and weeks is accomplished by converting
+the given time to a calendar day and time of day in the appropriate
+time zone and locale. The requisite number of days (weeks are converted
+to days by multiplying by seven) is added to the calendar day, and
+the date and time are then converted back to a count of seconds from
+the epoch time.
+.PP
+Adding and subtracting a given number of days across the point that
+the time changes at the start or end of summer time (Daylight Saving Time)
+results in the \fIsame local time\fR on the day in question. For
+instance, the following code sets the value of \fBx\fR to \fB05:00:00\fR.
+.CS
+set s [\fBclock scan\fR {2004-10-30 05:00:00} \e
+ -format {%Y-%m-%d %H:%M:%S} \e
+ -timezone :America/New_York]
+set a [\fBclock add\fR $s 1 day -timezone :America/New_York]
+set x [\fBclock format\fR $a \e
+ -format {%H:%M:%S} -timezone :America/New_York]
+.CE
+.PP
+In cases of ambiguity, where the same local time happens twice
+on the same day, the earlier time is used. In cases where the conversion
+yields an impossible time (for instance, 02:30 during the Spring
+Daylight Saving Time change using US rules), the time is converted
+as if the clock had not changed. Thus, the following code
+will set the value of \fBx\fR to \fB03:30:00\fR.
+.CS
+set s [\fBclock scan\fR {2004-04-03 02:30:00} \e
+ -format {%Y-%m-%d %H:%M:%S} \e
+ -timezone :America/New_York]
+set a [\fBclock add\fR $s 1 day -timezone :America/New_York]
+set x [\fBclock format\fR $a \e
+ -format {%H:%M:%S} -timezone :America/New_York]
+.CE
+.PP
+Adding a given number of days or weeks works correctly across the conversion
+between the Julian and Gregorian calendars; the omitted days are skipped.
+The following code sets \fBz\fR to \fB1752-09-14\fR.
+.CS
+set x [\fBclock scan\fR 1752-09-02 -format %Y-%m-%d -locale en_US]
+set y [\fBclock add\fR $x 1 day -locale en_US]
+set z [\fBclock format\fR $y -format %Y-%m-%d -locale en_US]
+.CE
+.PP
+In the bizarre case that adding the given number of days yields a date
+that does not exist because it falls within the dropped days of the
+Julian-to-Gregorian conversion, the date is converted as if it was
+on the Julian calendar.
+.PP
+Adding a number of months, or a number of years, is similar; it
+converts the given time to a calendar date and time of day. It then
+adds the requisite number of months or years, and reconverts the resulting
+date and time of day to an absolute time.
+.PP
+If the resulting date is impossible because the month has too few days
+(for example, when adding 1 month to 31 January), the last day of the
+month is substituted. Thus, adding 1 month to 31 January will result in
+28 February in a common year or 29 February in a leap year.
+.PP
+The rules for handling anomalies relating to summer time and to the
+Gregorian calendar are the same when adding/subtracting months and
+years as they are when adding/subtracting days and weeks.
+.PP
+If multiple \fIcount unit\fR pairs are present on the command, they
+are evaluated consecutively, from left to right.
+.SH "HIGH RESOLUTION TIMERS"
+Most of the subcommands supported by the \fBclock\fR command deal with
+times represented as a count of seconds from the epoch time, and this is the
+representation that \fBclock seconds\fR returns. There are three exceptions,
+which are all intended for use where higher-resolution times are required.
+\fBclock milliseconds\fR returns the count of milliseconds from the
+epoch time, and \fBclock microseconds\fR returns the count of microseconds
+from the epoch time. In addition, there is a \fBclock clicks\fR command
+that returns a platform-dependent high-resolution timer. Unlike
+\fBclock seconds\fR and \fBclock milliseconds\fR, the value
+of \fBclock clicks\fR is not guaranteed to be tied to any fixed
+epoch; it is simply intended to be the most precise interval timer
+available, and is intended only for relative timing studies such as
+benchmarks.
+.SH "FORMATTING TIMES"
+The \fBclock format\fR command produces times for display to a user
+or writing to an external medium. The command accepts times that are
+expressed in seconds from the epoch time of 1 January 1970, 00:00 UTC,
+as returned by \fBclock seconds\fR, \fBclock scan\fR, \fBclock add\fR,
+\fBfile atime\fR or \fBfile mtime\fR.
+.PP
+If a \fB\-format\fR option is present, the following argument is
+a string that specifies how the date and time are to be formatted.
+The string consists
+of any number of characters other than the per-cent sign
+.PQ \fB%\fR
+interspersed with any number of \fIformat groups\fR, which are two-character
+sequences beginning with the per-cent sign. The permissible format groups,
+and their interpretation, are described under \fBFORMAT GROUPS\fR.
+.PP
+If a \fB\-timezone\fR option is present, the following
+argument is a string that specifies the time zone in which the date and time
+are to be formatted. As an alternative to
+.QW "\fB\-timezone\fR \fI:UTC\fR" ,
+the obsolete usage
+.QW "\fB\-gmt\fR \fItrue\fR"
+may be used. See
+\fBTIME ZONES\fR for the permissible variants for the time zone.
+.PP
+If a \fB\-locale\fR option is present, the following argument is
+a string that specifies the locale in which the time is to be formatted,
+in the same format that is used for the \fBmsgcat\fR package. Note
+that the default, if \fB\-locale\fR is not specified, is the root locale
+\fB{}\fR rather than the current locale. The current locale may
+be obtained by using \fB\-locale\fR \fBcurrent\fR.
+In addition, some platforms support a \fBsystem\fR locale that
+reflects the user's current choices. For instance, on Windows, the
+format that the user has selected from dates and times in the Control
+Panel can be obtained by using the \fBsystem\fR locale. On
+platforms that do not define a user selection of date and time formats
+separate from \fBLC_TIME\fR, \fB\-locale\fR \fBsystem\fR is
+synonymous with \fB\-locale\fR \fBcurrent\fR.
+.SH "SCANNING TIMES"
+The \fBclock scan\fR command accepts times that are formatted as
+strings and converts them to counts of seconds from the epoch time
+of 1 January 1970, 00:00 UTC. It normally takes a \fB\-format\fR
+option that is followed by a string describing
+the expected format of the input. (See
+\fBFREE FORM SCAN\fR for the effect of \fBclock scan\fR
+without such an argument.) The string consists of any number of
+characters other than the per-cent sign
+.PQ \fB%\fR "" ,
+interspersed with any number of \fIformat groups\fR, which are two-character
+sequences beginning with the per-cent sign. The permissible format groups,
+and their interpretation, are described under \fBFORMAT GROUPS\fR.
+.PP
+If a \fB\-timezone\fR option is present, the following
+argument is a string that specifies the time zone in which the date and time
+are to be interpreted. As an alternative to \fB\-timezone\fR \fI:UTC\fR,
+the obsolete usage \fB\-gmt\fR \fItrue\fR may be used. See
+\fBTIME ZONES\fR for the permissible variants for the time zone.
+.PP
+If a \fB\-locale\fR option is present, the following argument is
+a string that specifies the locale in which the time is to be interpreted,
+in the same format that is used for the \fBmsgcat\fR package. Note
+that the default, if \fB\-locale\fR is not specified, is the root locale
+\fB{}\fR rather than the current locale. The current locale may
+be obtained by using \fB\-locale\fR \fBcurrent\fR.
+In addition, some platforms support a \fBsystem\fR locale that
+reflects the user's current choices. For instance, on Windows, the
+format that the user has selected from dates and times in the Control
+Panel can be obtained by using the \fBsystem\fR locale. On
+platforms that do not define a user selection of date and time formats
+separate from \fBLC_TIME\fR, \fB\-locale\fR \fBsystem\fR is
+synonymous with \fB\-locale\fR \fBcurrent\fR.
+.PP
+If a \fB\-base\fR option is present, the following argument is
+a time (expressed in seconds from the epoch time) that is used as
+a \fIbase time\fR for interpreting relative times. If no
+\fB\-base\fR option is present, the base time is the current time.
+.PP
+Scanning of times in fixed format works by determining three things:
+the date, the time of day, and the time zone. These three are then
+combined into a point in time, which is returned as the number of seconds
+from the epoch.
+.PP
+Before scanning begins, the format string is preprocessed
+to replace \fB%c\fR, \fB%Ec\fR, \fB%x\fR, \fB%Ex\fR,
+\fB%X\fR. \fB%Ex\fR, \fB%r\fR, \fB%R\fR, \fB%T\fR,
+\fB%D\fR, \fB%EY\fR and \fB%+\fR format groups with counterparts
+that are appropriate to the current locale and contain none of the
+above groups. For instance, \fB%D\fR will (in the \fBen_US\fR locale)
+be replaced with \fB%m/%d/%Y\fR.
+.PP
+The date is determined according to the fields that are present in the
+preprocessed format string. In order of preference:
+.IP [1]
+If the string contains a \fB%s\fR format group, representing
+seconds from the epoch, that group is used to determine the date.
+.IP [2]
+If the string contains a \fB%J\fR format group, representing
+the Julian Day Number, that group is used to determine the date.
+.IP [3]
+If the string contains a complete set of format groups specifying
+century, year, month, and day of month; century, year, and day of year;
+or ISO8601 fiscal year, week of year, and day of week; those groups are
+combined and used to determine the date. If more than one complete
+set is present, the one at the rightmost position in the string is
+used.
+.IP [4]
+If the string lacks a century but contains a set of format
+groups specifying year of century, month and day of month; year of
+century and day of year; or two-digit ISO8601 fiscal year, week of year,
+and day of week; those groups are
+combined and used to determine the date. If more than one complete
+set is present, the one at the rightmost position in the string is
+used. The year is presumed to lie in the range 1938 to 2037 inclusive.
+.IP [5]
+If the string entirely lacks any specification for the year
+(or contains the year only on the locale's alternative calendar)
+and contains a set of format groups specifying month and day of month,
+day of year, or week of year and day of week, those groups are
+combined and used to determine the date. If more than one complete
+set is present, the one at the rightmost position in the string is
+used. The year is determined by interpreting the base time in the given
+time zone.
+.IP [6]
+If the string contains none of the above sets, but has a day
+of the month or day of the week, the day of the month or day of the week
+are used to determine the date by interpreting the base time in the
+given time zone and returning the given day of the current week or month.
+(The week runs from Monday to Sunday, ISO8601-fashion.) If both day
+of month and day of week are present, the day of the month takes
+priority.
+.IP [7]
+If none of the above rules results in a usable date, the date
+of the base time in the given time zone is used.
+.PP
+The time is also determined according to the fields that are present in the
+preprocessed format string. In order of preference:
+.IP [1]
+If the string contains a \fB%s\fR format group, representing
+seconds from the epoch, that group determines the time of day.
+.IP [2]
+If the string contains either an hour on the 24-hour clock
+or an hour on the 12-hour clock plus an AM/PM indicator, that hour determines
+the hour of the day. If the string further contains a group specifying
+the minute of the hour, that group combines with the hour. If the string
+further contains a group specifying the second of the minute, that group
+combines with the hour and minute.
+.IP [3]
+If the string contains neither a \fB%s\fR format group nor
+a group specifying the hour of the day, then midnight (\fB00:00\fR, the start
+of the given date) is used.
+The time zone is determined by either the \fB\-timezone\fR or \fB\-gmt\fR
+options, or by using the current time zone.
+.PP
+If a format string lacks a \fB%z\fR or \fB%Z\fR format group,
+it is possible for the time to be ambiguous because it appears twice
+in the same day, once without and once with Daylight Saving Time.
+If this situation occurs, the first occurrence of the time is chosen.
+(For this reason, it is wise to have the input string contain the
+time zone when converting local times. This caveat does not apply to
+UTC times.)
+.SH "FORMAT GROUPS"
+The following format groups are recognized by the \fBclock scan\fR and
+\fBclock format\fR commands.
+.TP
+\fB%a\fR
+On output, receives an abbreviation (\fIe.g.,\fR \fBMon\fR) for the day
+of the week in the given locale. On input, matches the name of the day
+of the week in the given locale (in either abbreviated or full form, or
+any unique prefix of either form).
+.TP
+\fB%A\fR
+On output, receives the full name (\fIe.g.,\fR \fBMonday\fR) of the day
+of the week in the given locale. On input, matches the name of the day
+of the week in the given locale (in either abbreviated or full form, or
+any unique prefix of either form).
+.TP
+\fB%b\fR
+On output, receives an abbreviation (\fIe.g.,\fR \fBJan\fR) for the name
+of the month in the given locale. On input, matches the name of the month
+in the given locale (in either abbreviated or full form, or
+any unique prefix of either form).
+.TP
+\fB%B\fR
+On output, receives the full name (\fIe.g.,\fR \fBJanuary\fR)
+of the month in the given locale. On input, matches the name of the month
+in the given locale (in either abbreviated or full form, or
+any unique prefix of either form).
+.TP
+\fB%c\fR
+On output, receives a localized representation of date and time of day;
+the localized representation is expected to use the Gregorian calendar.
+On input, matches whatever \fB%c\fR produces.
.TP
-\fBclock scan \fIdateString\fR ?\fB\-base \fIclockVal\fR? ?\fB\-gmt \fIboolean\fR?
-Convert \fIdateString\fR to an integer clock value (see \fBclock seconds\fR).
-This command can parse and convert virtually any standard date and/or time
-string, which can include standard time zone mnemonics. If only a time is
-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
+\fB%C\fR
+On output, receives the number of the century in Indo-Arabic numerals.
+On input, matches one or two digits, possibly with leading whitespace,
+that are expected to be the number of the century.
+.TP
+\fB%d\fR
+On output, produces the number of the day of the month, as two decimal
+digits. On input, matches one or two digits, possibly with leading
+whitespace, that are expected to be the number of the day of the month.
+.TP
+\fB%D\fR
+This format group is synonymous with \fB%m/%d/%Y\fR. It should be
+used only in exchanging data within the \fBen_US\fR locale, since
+other locales typically do not use this order for the fields of the date.
+.TP
+\fB%e\fR
+On output, produces the number of the day of the month, as one or
+two decimal digits (with a leading blank for one-digit dates).
+On input, matches one or two digits, possibly with leading
+whitespace, that are expected to be the number of the day of the month.
+.TP
+\fB%Ec\fR
+On output, produces a locale-dependent representation of the date and
+time of day in the locale's alternative calendar. On input, matches
+whatever \fB%Ec\fR produces. The locale's alternative calendar need not
+be the Gregorian calendar.
+.TP
+\fB%EC\fR
+On output, produces a locale-dependent name of an era in the locale's
+alternative calendar. On input, matches the name of the era or any
+unique prefix.
+.TP
+\fB%EE\fR
+On output, produces the string \fBB.C.E.\fR or \fBC.E.\fR, or a
+string of the same meaning in the locale, to indicate whether \fB%Y\fR refers
+to years before or after Year 1 of the Common Era. On input, accepts
+the string \fBB.C.E.\fR, \fBB.C.\fR, \fBC.E.\fR, \fBA.D.\fR, or the
+abbreviation appropriate to the current locale, and uses it to fix
+whether \fB%Y\fR refers to years before or after Year 1 of the
+Common Era.
+.TP
+\fB%Ex\fR
+On output, produces a locale-dependent representation of the date
+in the locale's alternative calendar. On input, matches
+whatever \fB%Ex\fR produces. The locale's alternative calendar need not
+be the Gregorian calendar.
+.TP
+\fB%EX\fR
+On output, produces a locale-dependent representation of the
+time of day in the locale's alternative numerals. On input, matches
+whatever \fB%EX\fR produces.
+.TP
+\fB%Ey\fR
+On output, produces a locale-dependent number of the year of the era
+in the locale's alternative calendar and numerals. On input, matches
+such a number.
+.TP
+\fB%EY\fR
+On output, produces a representation of the year in the locale's
+alternative calendar and numerals. On input, matches what \fB%EY\fR
+produces. Often synonymous with \fB%EC%Ey\fR.
+.TP
+\fB%g\fR
+On output, produces a two-digit year number suitable for use with
+the week-based ISO8601 calendar; that is, the year number corresponds
+to the week number produced by \fB%V\fR. On input, accepts such
+a two-digit year number, possibly with leading whitespace.
+.TP
+\fB%G\fR
+On output, produces a four-digit year number suitable for use with
+the week-based ISO8601 calendar; that is, the year number corresponds
+to the week number produced by \fB%V\fR. On input, accepts such
+a four-digit year number, possibly with leading whitespace.
+.TP
+\fB%h\fR
+This format group is synonymous with \fB%b\fR.
+.TP
+\fB%H\fR
+On output, produces a two-digit number giving the hour of the day
+(00-23) on a 24-hour clock. On input, accepts such a number.
+.TP
+\fB%I\fR
+On output, produces a two-digit number giving the hour of the day
+(12-11) on a 12-hour clock. On input, accepts such a number.
+.TP
+\fB%j\fR
+On output, produces a three-digit number giving the day of the year
+(001-366). On input, accepts such a number.
+.TP
+\fB%J\fR
+On output, produces a string of digits giving the Julian Day Number.
+On input, accepts a string of digits and interprets it as a Julian Day Number.
+The Julian Day Number is a count of the number of calendar days
+that have elapsed since 1 January, 4713 BCE of the proleptic
+Julian calendar. The epoch time of 1 January 1970 corresponds
+to Julian Day Number 2440588.
+.TP
+\fB%k\fR
+On output, produces a one- or two-digit number giving the hour of the day
+(0-23) on a 24-hour clock. On input, accepts such a number.
+.TP
+\fB%l\fR
+On output, produces a one- or two-digit number giving the hour of the day
+(12-11) on a 12-hour clock. On input, accepts such a number.
+.TP
+\fB%m\fR
+On output, produces the number of the month (01-12) with exactly two
+digits. On input, accepts two digits and interprets them as the number
+of the month.
+.TP
+\fB%M\fR
+On output, produces the number of the minute of the hour (00-59)
+with exactly two digits. On input, accepts two digits and interprets them
+as the number of the minute of the hour.
+.TP
+\fB%N\fR
+On output, produces the number of the month (1-12) with one or two digits,
+and a leading blank for one-digit dates.
+On input, accepts one or two digits, possibly with leading whitespace,
+and interprets them as the number of the month.
+.TP
+\fB%Od\fR, \fB%Oe\fR, \fB%OH\fR, \fB%OI\fR, \fB%Ok\fR, \fB%Ol\fR, \fB%Om\fR, \fB%OM\fR, \fB%OS\fR, \fB%Ou\fR, \fB%Ow\fR, \fB%Oy\fR
+All of these format groups are synonymous with their counterparts
+without the
+.QW \fBO\fR ,
+except that the string is produced and parsed in the
+locale-dependent alternative numerals.
+.TP
+\fB%p\fR
+On output, produces an indicator for the part of the day, \fBAM\fR
+or \fBPM\fR, appropriate to the given locale. If the script of the
+given locale supports multiple letterforms, lowercase is preferred.
+On input, matches the representation \fBAM\fR or \fBPM\fR in
+the given locale, in either case.
+.TP
+\fB%P\fR
+On output, produces an indicator for the part of the day, \fBam\fR
+or \fBpm\fR, appropriate to the given locale. If the script of the
+given locale supports multiple letterforms, uppercase is preferred.
+On input, matches the representation \fBAM\fR or \fBPM\fR in
+the given locale, in either case.
+.TP
+\fB%Q\fR
+This format group is reserved for internal use within the Tcl library.
+.TP
+\fB%r\fR
+On output, produces a locale-dependent time of day representation on a
+12-hour clock. On input, accepts whatever \fB%r\fR produces.
+.TP
+\fB%R\fR
+On output, produces a locale-dependent time of day representation on a
+24-hour clock. On input, accepts whatever \fB%R\fR produces.
+.TP
+\fB%s\fR
+On output, simply formats the \fItimeVal\fR argument as a decimal
+integer and inserts it into the output string. On input, accepts
+a decimal integer and uses is as the time value without any further
+processing. Since \fB%s\fR uniquely determines a point in time, it
+overrides all other input formats.
+.TP
+\fB%S\fR
+On output, produces a two-digit number of the second of the minute
+(00-59). On input, accepts two digits and uses them as the second of the
+minute.
+.TP
+\fB%t\fR
+On output, produces a TAB character. On input, matches a TAB character.
+.TP
+\fB%T\fR
+Synonymous with \fB%H:%M:%S\fR.
+.TP
+\fB%u\fR
+On output, produces the number of the day of the week
+(\fB1\fR\(->Monday, \fB7\fR\(->Sunday). On input, accepts a single digit and
+interprets it as the day of the week. Sunday may be either \fB0\fR or
+\fB7\fR.
+.TP
+\fB%U\fR
+On output, produces the ordinal number of the week of the year
+(00-53). The first Sunday of the year is the first day of week 01. On
+input accepts two digits which are otherwise ignored. This format
+group is never used in determining an input date. This interpretation
+of the week of the year was once common in US banking but is now
+largely obsolete. See \fB%V\fR for the ISO8601 week number.
+.TP
+\fB%V\fR
+On output, produces the number of the ISO8601 week as a two digit
+number (01-53). Week 01 is the week containing January 4; or the first
+week of the year containing at least 4 days; or the week containing
+the first Thursday of the year (the three statements are
+equivalent). Each week begins on a Monday. On input, accepts the
+ISO8601 week number.
+.TP
+\fB%w\fR
+On output, produces the ordinal number of the day of the week
+(Sunday==0; Saturday==6). On input, accepts a single digit and
+interprets it as the day of the week; Sunday may be represented as
+either 0 or 7. Note that \fB%w\fR is not the ISO8601 weekday number,
+which is produced and accepted by \fB%u\fR.
+.TP
+\fB%W\fR
+On output, produces a week number (00-53) within the year; week 01
+begins on the first Monday of the year. On input, accepts two digits,
+which are otherwise ignored. This format group is never used in
+determining an input date. It is not the ISO8601 week number; that
+week is produced and accepted by \fB%V\fR.
+.TP
+\fB%x\fR
+On output, produces the date in a locale-dependent representation. On
+input, accepts whatever \fB%x\fR produces and is used to determine
+calendar date.
+.TP
+\fB%X\fR
+On output, produces the time of day in a locale-dependent
+representation. On input, accepts whatever \fB%X\fR produces and is used
+to determine time of day.
+.TP
+\fB%y\fR
+On output, produces the two-digit year of the century. On input,
+accepts two digits, and is used to determine calendar date. The
+date is presumed to lie between 1938 and 2037 inclusive. Note
+that \fB%y\fR does not yield a year appropriate for use with the ISO8601
+week number \fB%V\fR; programs should use \fB%g\fR for that purpose.
+.TP
+\fB%Y\fR
+On output, produces the four-digit calendar year. On input,
+accepts four digits and may be used to determine calendar date. Note
+that \fB%Y\fR does not yield a year appropriate for use with the ISO8601
+week number \fB%V\fR; programs should use \fB%G\fR for that purpose.
+.TP
+\fB%z\fR
+On output, produces the current time zone, expressed in hours and
+minutes east (+hhmm) or west (\-hhmm) of Greenwich. On input, accepts a
+time zone specifier (see \fBTIME ZONES\fR below) that will be used to
+determine the time zone.
+.TP
+\fB%Z\fR
+On output, produces the current time zone's name, possibly
+translated to the given locale. On input, accepts a time zone
+specifier (see \fBTIME ZONES\fR below) that will be used to determine the
+time zone. This option should, in general, be used on input only when
+parsing RFC822 dates. Other uses are fraught with ambiguity; for
+instance, the string \fBBST\fR may represent British Summer Time or
+Brazilian Standard Time. It is recommended that date/time strings for
+use by computers use numeric time zones instead.
+.TP
+\fB%%\fR
+On output, produces a literal
+.QW \fB%\fR
+character. On input, matches a literal
+.QW \fB%\fR
+character.
+.TP
+\fB%+\fR
+Synonymous with
+.QW "\fB%a %b %e %H:%M:%S %Z %Y\fR" .
+.SH "TIME ZONES"
+When the \fBclock\fR command is processing a local time, it has several
+possible sources for the time zone to use. In order of preference, they
+are:
+.IP [1]
+A time zone specified inside a string being parsed and matched by a \fB%z\fR
+or \fB%Z\fR format group.
+.IP [2]
+A time zone specified with the \fB\-timezone\fR option to the \fBclock\fR
+command (or, equivalently, by \fB\-gmt\fR \fB1\fR).
+.IP [3]
+A time zone specified in an environment variable \fBTCL_TZ\fR.
+.IP [4]
+A time zone specified in an environment variable \fBTZ\fR.
+.IP [5]
+The local time zone from the Control Panel on Windows systems.
+.IP [6]
+The C library's idea of the local time zone, as defined by the
+\fBmktime\fR and \fBlocaltime\fR functions.
+.PP
+In case [1] \fIonly,\fR the string is tested to see if it is one
+of the strings:
+.CS
+ gmt ut utc bst wet wat at
+ nft nst ndt ast adt est edt
+ cst cdt mst mdt pst pdt yst
+ ydt hst hdt cat ahst nt idlw
+ cet cest met mewt mest swt sst
+ eet eest bt it zp4 zp5 ist
+ zp6 wast wadt jt cct jst cast
+ cadt east eadt gst nzt nzst nzdt
+ idle
+.CE
+If it is a string in the above list, it designates a known
+time zone, and is interpreted as such.
+.PP
+For time zones in case [1] that do not match any of the above strings,
+and always for cases [2]-[6], the following rules apply.
+.PP
+If the time zone begins with a colon, it is one of a
+standardized list of names like \fB:America/New_York\fR
+that give the rules for various locales. A complete list
+of the location names is too lengthy to be listed here.
+On most Tcl installations, the definitions of the locations
+are to be found in named files in the directory
+.QW "\fI/no_backup/tools/lib/tcl8.5/clock/tzdata\fR" .
+On some Unix systems, these files are omitted, and the definitions are
+instead obtained from system files in
+.QW "\fI/usr/share/zoneinfo\fR" ,
+.QW "\fI/usr/share/lib/zoneinfo\fR"
+or
+.QW "\fI/usr/local/etc/zoneinfo\fR" .
+As a special case, the name \fB:localtime\fR refers to
+the local time zone as defined by the C library.
+.PP
+A time zone string consisting of a plus or minus sign followed by
+four or six decimal digits is interpreted as an offset in
+hours, minutes, and seconds (if six digits are present) from
+UTC. The plus sign denotes a sign east of Greenwich;
+the minus sign one west of Greenwich.
+.PP
+A time zone string conforming to the Posix specification of the \fBTZ\fR
+environment variable will be recognized. The specification
+may be found at
+\fIhttp://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html\fR.
+.PP
+Any other time zone string is processed by prefixing a colon and attempting
+to use it as a location name, as above.
+.SH "LOCALIZATION"
+Developers wishing to localize the date and time formatting and parsing
+are referred to \fIhttp://tip.tcl.tk/173\fR for a
+specification.
+.SH "FREE FORM SCAN"
+If the \fBclock scan\fR command is invoked without a \fB\-format\fR
+option, then it requests a \fIfree-form scan.\fR \fI
+This form of scan is deprecated.\fR The reason for the deprecation
+is that there are too many ambiguities. (Does the string
+.QW 2000
+represent a year, a time of day, or a quantity?) No set of rules
+for interpreting free-form dates and times has been found to
+give unsurprising results in all cases.
+.PP
+If free-form scan is used, only the \fB\-base\fR and \fB\-gmt\fR
+options are accepted. The \fB\-timezone\fR and \fB\-locale\fR
+options will result in an error if \fB\-format\fR is not supplied.
+.PP
+For the benefit of users who need to understand legacy code that
+uses free-form scan, the documentation for how free-form scan
+interprets a string is included here:
+.PP
+If only a time is
+specified, the current date is assumed. If the \fIinputString\fR
+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
+\fB\-gmt\fR, if specified, affects only the computed time value; it does not
+impact the interpretation of \fB\-base\fR.
+.PP
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
time. This is useful for determining the time on a specific day or
doing other date-relative conversions.
-.sp
-The \fIdateString\fR consists of zero or more specifications of the
+.PP
+The \fIinputString\fR argument consists of zero or more specifications of the
following form:
-.RS
.TP
\fItime\fR
-A time of day, which is of the form: \fIhh\fR?\fI:mm\fR?\fI:ss\fR??
-?\fImeridian\fR? ?\fIzone\fR? or \fIhhmm \fR?\fImeridian\fR?
-?\fIzone\fR?. If no meridian is specified, \fIhh\fR is interpreted on
+A time of day, which is of the form: \fBhh?:mm?:ss?? ?meridian? ?zone?\fR
+or \fBhhmm ?meridian? ?zone?\fR
+If no meridian is specified, \fBhh\fR is interpreted on
a 24-hour clock.
.TP
\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?, \fIday, dd monthname
-yy\fR, \fI?CC?yymmdd\fR, \fI?CC?yy-mm-dd\fR, \fIdd-monthname-?CC?yy\fR.
+acceptable formats are
+.QW "\fBmm/dd\fR?\fB/yy\fR?" ,
+.QW "\fBmonthname dd\fR?\fB, yy\fR?" ,
+.QW "\fBday, dd monthname \fR?\fByy\fR?" ,
+.QW "\fBdd monthname yy\fR" ,
+.QW "?\fBCC\fR?\fByymmdd\fR" ,
+and
+.QW "\fBdd-monthname-\fR?\fBCC\fR?\fByy\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. Note that only these three formats are accepted.
+An ISO 8601 point-in-time specification, such as
+.QW \fICCyymmdd\fBT\fIhhmmss\fR,
+where \fBT\fR is the literal
+.QW T ,
+.QW "\fICCyymmdd hhmmss\fR" ,
+or
+.QW \fICCyymmdd\fBT\fIhh:mm:ss\fR .
+Note that only these three formats are accepted.
The command does \fInot\fR accept the full range of point-in-time
specifications specified in ISO8601. Other formats can be recognized by
-using commands such as \fBregexp\fR to extract their fields and reorganize
-them into a form accepted by the \fBclock scan\fR command.
+giving an explicit \fI\-format\fR option to the \fBclock scan\fR command.
.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,
+A specification relative to the current time. The format is \fBnumber
+unit\fR. Acceptable units are \fByear\fR, \fBfortnight\fR,
+\fBmonth\fR, \fBweek\fR, \fBday\fR,
\fBhour\fR, \fBminute\fR (or \fBmin\fR), and \fBsecond\fR (or \fBsec\fR). The
unit can be specified as a singular or plural, as in \fB3 weeks\fR.
These modifiers may also be specified:
\fBtomorrow\fR, \fByesterday\fR, \fBtoday\fR, \fBnow\fR,
\fBlast\fR, \fBthis\fR, \fBnext\fR, \fBago\fR.
-.RE
-.sp
-.RS
+.PP
The actual date is calculated according to the following steps.
+.PP
First, any absolute date and/or time is processed and converted.
Using that time as the base, day-of-week specifications are added.
Next, relative specifications are used. If a date or day is
@@ -262,29 +893,9 @@ 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
-% \fBclock scan\fR "1 day" -base [\fBclock scan\fR 1999-10-31]
-941443200
-% \fBclock scan\fR "24 hours" -base [\fBclock scan\fR 1999-10-31]
-941439600
-.CE
-.RE
-.TP
-\fBclock seconds\fR
-Return the current date and time as a system-dependent integer value. The
-unit of the value is seconds, allowing it to be used for relative time
-calculations. The value is usually defined as total elapsed time from
-an ``epoch''. You shouldn't assume the value of the epoch.
-
.SH "SEE ALSO"
-date(1), time(n)
-
+msgcat(n)
.SH KEYWORDS
clock, date, time
+.SH "COPYRIGHT"
+Copyright (c) 2004 Kevin B. Kenny <kennykb@acm.org>. All rights reserved.
diff --git a/doc/close.n b/doc/close.n
index a1c5f01..4ef3c7d 100644
--- a/doc/close.n
+++ b/doc/close.n
@@ -10,7 +10,7 @@
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
-close \- Close an open channel.
+close \- Close an open channel
.SH SYNOPSIS
\fBclose \fIchannelId\fR
.BE
@@ -19,17 +19,14 @@ close \- Close an open channel.
.PP
Closes the channel given by \fIchannelId\fR.
.PP
-.VS
\fIChannelId\fR must be an identifier for an open channel such as a
Tcl standard channel (\fBstdin\fR, \fBstdout\fR, or \fBstderr\fR),
the return value from an invocation of \fBopen\fR or \fBsocket\fR, or
the result of a channel creation command provided by a Tcl extension.
-.VE
.PP
All buffered output is flushed to the channel's output device,
any buffered input is discarded, the underlying file or device is closed,
and \fIchannelId\fR becomes unavailable for use.
-.VS "" br
.PP
If the channel is blocking, the command does not return until all output
is flushed.
@@ -37,11 +34,9 @@ If the channel is nonblocking and there is unflushed output, the
channel remains open and the command
returns immediately; output will be flushed in the background and the
channel will be closed when all the flushing is complete.
-.VE
.PP
If \fIchannelId\fR is a blocking channel for a command pipeline then
\fBclose\fR waits for the child processes to complete.
-.VS "" br
.PP
If the channel is shared between interpreters, then \fBclose\fR
makes \fIchannelId\fR unavailable in the invoking interpreter but has no
@@ -54,7 +49,6 @@ When the last interpreter in which the channel is registered invokes
Channels are automatically closed when an interpreter is destroyed and
when the process exits. Channels are switched to blocking mode, to ensure
that all output is correctly flushed before the process exits.
-.VE
.PP
The command returns an empty string, and may generate an error if
an error occurs while flushing output. If a command in a command
diff --git a/doc/concat.n b/doc/concat.n
index e52d978..f7317c4 100644
--- a/doc/concat.n
+++ b/doc/concat.n
@@ -24,27 +24,33 @@ into a single list.
It permits any number of arguments;
if no \fIarg\fRs are supplied, the result is an empty string.
.SH EXAMPLES
-Although \fBconcat\fR will concatenate lists (so the command:
+Although \fBconcat\fR will concatenate lists, flattening them in the process
+(so giving the following interactive session):
+.PP
.CS
-\fBconcat\fR a b {c d e} {f {g h}}
+\fI%\fR \fBconcat\fR a b {c d e} {f {g h}}
+\fIa b c d e f {g h}\fR
.CE
-will return "\fBa b c d e f {g h}\fR" as its result), it will also
-concatenate things that are not lists, and hence the command:
+.PP
+it will also concatenate things that are not lists, as can be seen from this
+session:
+.PP
.CS
-\fBconcat\fR " a b {c " d " e} f"
+\fI%\fR \fBconcat\fR " a b {c " d " e} f"
+\fIa b {c d e} f\fR
.CE
-will return "\fBa b {c d e} f\fR" as its result.
.PP
-Note that the concatenation does not remove spaces from the middle of
-its arguments, so the command:
+Note also that the concatenation does not remove spaces from the middle of
+values, as can be seen here:
+.PP
.CS
-\fBconcat\fR "a b c" { d e f }
+\fI%\fR \fBconcat\fR "a b c" { d e f }
+\fIa b c d e f\fR
.CE
-will return "\fBa b c d e f\fR" (i.e. with three spaces between
-the \fBa\fR, the \fBb\fR and the \fBc\fR).
-
+.PP
+(i.e., there are three spaces between each of the \fBa\fR, the \fBb\fR and the
+\fBc\fR).
.SH "SEE ALSO"
-append(n), eval(n)
-
+append(n), eval(n), join(n)
.SH KEYWORDS
concatenate, join, lists
diff --git a/doc/dde.n b/doc/dde.n
index 5dbbee5..2e3c883 100644
--- a/doc/dde.n
+++ b/doc/dde.n
@@ -6,26 +6,26 @@
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.so man.macros
-.TH dde n 1.2 dde "Tcl Bundled Packages"
+.TH dde n 1.3 dde "Tcl Bundled Packages"
.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.2\fR
+\fBpackage require dde 1.3\fR
.sp
-\fBdde eval\fR ?\fB\-async\fR? \fIservice cmd\fR ?\fIarg ...\fR?
+\fBdde servername\fR ?\fB\-force\fR? ?\fB\-handler \fIproc\fR? ?\fB\-\|\-\fR? ?\fItopic\fR?
.sp
\fBdde execute\fR ?\fB\-async\fR? \fIservice topic data\fR
.sp
-\fBdde poke \fIservice topic item data\fR
-.sp
-\fBdde request\fR ?\fB\-binary\fR? \fIservice topic data\fR
+\fBdde poke\fR \fIservice topic item data\fR
.sp
-\fBdde servername\fR ?\fItopic\fR?
+\fBdde request\fR ?\fB\-binary\fR? \fIservice topic item\fR
.sp
\fBdde services \fIservice topic\fR
+.sp
+\fBdde eval\fR ?\fB\-async\fR? \fItopic cmd \fR?\fIarg arg ...\fR?
.BE
.SH DESCRIPTION
@@ -37,23 +37,40 @@ 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 name\fRs and \fItopic\fRs. For instance, Microsoft Excel
+own \fIservice names\fR and \fItopics\fR. For instance, Microsoft Excel
has the service name \fBExcel\fR.
.PP
-The \fBeval\fR and \fBexecute\fR commands accept the option \fB\-async\fR:
-
.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?\fB\-force\fR? ?\fB\-handler \fIproc\fR? ?\fB\-\|\-\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.
+of the current topic or the empty string if it is not registered as a
+service. If the given \fItopic\fR name is already in use, then a
+suffix of the form
+.QW " #2"
+or
+.QW " #3"
+is appended to the name to make it
+unique. The command's result will be the name actually used. The
+\fB\-force\fR option is used to force registration of precisely the
+given \fItopic\fR name.
+.RS
+.PP
+The \fB\-handler\fR option specifies a Tcl procedure that will be called to
+process calls to the dde server. If the package has been loaded into a
+safe interpreter then a \fB\-handler\fR procedure must be defined. The
+procedure is called with all the arguments provided by the remote
+call.
+.RE
.TP
\fBdde execute\fR ?\fB\-async\fR? \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
@@ -65,6 +82,7 @@ script did not run, unless the \fB\-async\fR flag was used, in which case
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
@@ -74,6 +92,7 @@ it must always be non-null. The \fIdata\fR field is given to the remote
application.
.TP
\fBdde request\fR ?\fB\-binary\fR? \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,
@@ -84,24 +103,25 @@ string with terminating null. If \fB\-binary\fR is specified, the
result is returned as a byte array.
.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
+both empty strings ({}), then all service-topic pairs currently
+available on the system are returned. If \fIservice\fR is empty 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.
+returned. If \fIservice\fR is non-empty and \fItopic\fR is, all topics
+for a given service are returned. If both are non-empty, if that
+service-topic pair currently exists, it is returned; otherwise, an
+empty string is returned.
.TP
\fBdde eval\fR ?\fB\-async\fR? \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. The \fB\-async\fR option requests asynchronous invocation. The
command returns an error message if the script did not run, unless the
\fB\-async\fR flag was used, in which case the command returns immediately
-with no error. This command can be used to replace \fBsend\fR on Windows.
-
+with no error. 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
@@ -134,7 +154,6 @@ 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 EXAMPLE
This asks Internet Explorer (which must already be running) to go to a
particularly important website:
@@ -142,9 +161,7 @@ particularly important website:
package require dde
\fBdde execute\fR -async iexplore WWW_OpenURL http://www.tcl.tk/
.CE
-
.SH "SEE ALSO"
tk(n), winfo(n), send(n)
-
.SH KEYWORDS
application, dde, name, remote execution
diff --git a/doc/dict.n b/doc/dict.n
new file mode 100644
index 0000000..28c4f7c
--- /dev/null
+++ b/doc/dict.n
@@ -0,0 +1,389 @@
+'\"
+'\" Copyright (c) 2003 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.so man.macros
+.TH dict n 8.5 Tcl "Tcl Built-In Commands"
+.BS
+'\" Note: do not modify the .SH NAME line immediately below!
+.SH NAME
+dict \- Manipulate dictionaries
+.SH SYNOPSIS
+\fBdict \fIoption arg \fR?\fIarg ...\fR?
+.BE
+.SH DESCRIPTION
+.PP
+Performs one of several operations on dictionary values or variables
+containing dictionary values (see the \fBDICTIONARY VALUES\fR section
+below for a description), depending on \fIoption\fR. The legal
+\fIoption\fRs (which may be abbreviated) are:
+.TP
+\fBdict append \fIdictionaryVariable key \fR?\fIstring ...\fR?
+This appends the given string (or strings) to the value that the given
+key maps to in the dictionary value contained in the given variable,
+writing the resulting dictionary value back to that variable.
+Non-existent keys are treated as if they map to an empty string.
+.TP
+\fBdict create \fR?\fIkey value ...\fR?
+Create a new dictionary that contains each of the key/value mappings
+listed as arguments (keys and values alternating, with each key being
+followed by its associated value.)
+.TP
+\fBdict exists \fIdictionaryValue key \fR?\fIkey ...\fR?
+This returns a boolean value indicating whether the given key (or path
+of keys through a set of nested dictionaries) exists in the given
+dictionary value. This returns a true value exactly when \fBdict
+get\fR on that path will succeed.
+.TP
+\fBdict filter \fIdictionaryValue filterType arg \fR?\fIarg ...\fR?
+This takes a dictionary value and returns a new dictionary that
+contains just those key/value pairs that match the specified filter
+type (which may be abbreviated.) Supported filter types are:
+.RS
+.TP
+\fBdict filter \fIdictionaryValue \fBkey \fIglobPattern\fR
+The key rule only matches those key/value pairs whose keys match the
+given pattern (in the style of \fBstring match\fR.)
+.TP
+\fBdict filter \fIdictionaryValue \fBscript {\fIkeyVar valueVar\fB} \fIscript\fR
+The script rule tests for matching by assigning the key to the
+\fIkeyVar\fR and the value to the \fIvalueVar\fR, and then evaluating
+the given script which should return a boolean value (with the
+key/value pair only being included in the result of the \fBdict
+filter\fR when a true value is returned.) Note that the first
+argument after the rule selection word is a two-element list. If the
+\fIscript\fR returns with a condition of \fBTCL_BREAK\fR, no further
+key/value pairs are considered for inclusion in the resulting
+dictionary, and a condition of \fBTCL_CONTINUE\fR is equivalent to a false
+result. The key/value pairs are tested in the order in which the keys
+were inserted into the dictionary.
+.TP
+\fBdict filter \fIdictionaryValue \fBvalue \fIglobPattern\fR
+The value rule only matches those key/value pairs whose values match
+the given pattern (in the style of \fBstring match\fR.)
+.RE
+.TP
+\fBdict for {\fIkeyVar valueVar\fB} \fIdictionaryValue body\fR
+This command takes three arguments, the first a two-element list of
+variable names (for the key and value respectively of each mapping in
+the dictionary), the second the dictionary value to iterate across,
+and the third a script to be evaluated for each mapping with the key
+and value variables set appropriately (in the manner of \fBforeach\fR.)
+The result of the command is an empty string. If any evaluation of the
+body generates a \fBTCL_BREAK\fR result, no further pairs from the
+dictionary will be iterated over and the \fBdict for\fR command will
+terminate successfully immediately. If any evaluation of the body
+generates a \fBTCL_CONTINUE\fR result, this shall be treated exactly like a
+normal \fBTCL_OK\fR result. The order of iteration is the order in
+which the keys were inserted into the dictionary.
+.TP
+\fBdict get \fIdictionaryValue \fR?\fIkey ...\fR?
+Given a dictionary value (first argument) and a key (second argument),
+this will retrieve the value for that key. Where several keys are
+supplied, the behaviour of the command shall be as if the result of
+\fBdict get $dictVal $key\fR was passed as the first argument to
+\fBdict get\fR with the remaining arguments as second (and possibly
+subsequent) arguments. This facilitates lookups in nested
+dictionaries. For example, the following two commands are equivalent:
+.RS
+.PP
+.CS
+dict get $dict foo bar spong
+dict get [dict get [dict get $dict foo] bar] spong
+.CE
+.PP
+If no keys are provided, \fBdict get\fR will return a list containing pairs of
+elements in a manner similar to \fBarray get\fR. That is, the first
+element of each pair would be the key and the second element would be
+the value for that key.
+.PP
+It is an error to attempt to retrieve a value for a key that is not
+present in the dictionary.
+.RE
+.TP
+\fBdict incr \fIdictionaryVariable key \fR?\fIincrement\fR?
+This adds the given increment value (an integer that defaults to 1 if
+not specified) to the value that the given key maps to in the
+dictionary value contained in the given variable, writing the
+resulting dictionary value back to that variable. Non-existent keys
+are treated as if they map to 0. It is an error to increment a value
+for an existing key if that value is not an integer.
+.TP
+\fBdict info \fIdictionaryValue\fR
+This returns information (intended for display to people) about the
+given dictionary though the format of this data is dependent on the
+implementation of the dictionary. For dictionaries that are
+implemented by hash tables, it is expected that this will return the
+string produced by \fBTcl_HashStats\fR, similar to \fBarray statistics\fR.
+.TP
+\fBdict keys \fIdictionaryValue \fR?\fIglobPattern\fR?
+Return a list of all keys in the given dictionary value. If a pattern
+is supplied, only those keys that match it (according to the rules of
+\fBstring match\fR) will be returned. The returned keys will be in the
+order that they were inserted into the dictionary.
+.TP
+\fBdict lappend \fIdictionaryVariable key \fR?\fIvalue ...\fR?
+This appends the given items to the list value that the given key maps
+to in the dictionary value contained in the given variable, writing
+the resulting dictionary value back to that variable. Non-existent
+keys are treated as if they map to an empty list, and it is legal for
+there to be no items to append to the list. It is an error for the
+value that the key maps to to not be representable as a list.
+.TP
+\fBdict merge \fR?\fIdictionaryValue ...\fR?
+Return a dictionary that contains the contents of each of the
+\fIdictionaryValue\fR arguments. Where two (or more) dictionaries
+contain a mapping for the same key, the resulting dictionary maps that
+key to the value according to the last dictionary on the command line
+containing a mapping for that key.
+.TP
+\fBdict remove \fIdictionaryValue \fR?\fIkey ...\fR?
+Return a new dictionary that is a copy of an old one passed in as
+first argument except without mappings for each of the keys listed.
+It is legal for there to be no keys to remove, and it also legal for
+any of the keys to be removed to not be present in the input
+dictionary in the first place.
+.TP
+\fBdict replace \fIdictionaryValue \fR?\fIkey value ...\fR?
+Return a new dictionary that is a copy of an old one passed in as
+first argument except with some values different or some extra
+key/value pairs added. It is legal for this command to be called with
+no key/value pairs, but illegal for this command to be called with a
+key but no value.
+.TP
+\fBdict set \fIdictionaryVariable key \fR?\fIkey ...\fR? \fIvalue\fR
+This operation takes the name of a variable containing a dictionary
+value and places an updated dictionary value in that variable
+containing a mapping from the given key to the given value. When
+multiple keys are present, this operation creates or updates a chain
+of nested dictionaries.
+.TP
+\fBdict size \fIdictionaryValue\fR
+Return the number of key/value mappings in the given dictionary value.
+.TP
+\fBdict unset \fIdictionaryVariable key \fR?\fIkey ...\fR?
+This operation (the companion to \fBdict set\fR) takes the name of a
+variable containing a dictionary value and places an updated
+dictionary value in that variable that does not contain a mapping for
+the given key. Where multiple keys are present, this describes a path
+through nested dictionaries to the mapping to remove. At least one key
+must be specified, but the last key on the key-path need not exist.
+All other components on the path must exist.
+.TP
+\fBdict update \fIdictionaryVariable key varName \fR?\fIkey varName ...\fR? \fIbody\fR
+Execute the Tcl script in \fIbody\fR with the value for each \fIkey\fR
+(as found by reading the dictionary value in \fIdictionaryVariable\fR)
+mapped to the variable \fIvarName\fR. There may be multiple
+\fIkey\fR/\fIvarName\fR pairs. If a \fIkey\fR does not have a mapping,
+that corresponds to an unset \fIvarName\fR. When \fIbody\fR
+terminates, any changes made to the \fIvarName\fRs is reflected back
+to the dictionary within \fIdictionaryVariable\fR (unless
+\fIdictionaryVariable\fR itself becomes unreadable, when all updates
+are silently discarded), even if the result of \fIbody\fR is an error
+or some other kind of exceptional exit. The result of \fBdict
+update\fR is (unless some kind of error occurs) the result of the
+evaluation of \fIbody\fR.
+.RS
+.PP
+Each \fIvarName\fR is mapped in the scope enclosing the \fBdict update\fR;
+it is recommended that this command only be used in a local scope
+(\fBproc\fRedure or lambda term for \fBapply\fR). Because of
+this, the variables set by \fBdict update\fR will continue to
+exist after the command finishes (unless explicitly \fBunset\fR).
+Note that the mapping of values to variables
+does not use traces; changes to the \fIdictionaryVariable\fR's
+contents only happen when \fIbody\fR terminates.
+.RE
+.TP
+\fBdict values \fIdictionaryValue \fR?\fIglobPattern\fR?
+Return a list of all values in the given dictionary value. If a
+pattern is supplied, only those values that match it (according to the
+rules of \fBstring match\fR) will be returned. The returned values
+will be in the order of that the keys associated with those values
+were inserted into the dictionary.
+.TP
+\fBdict with \fIdictionaryVariable \fR?\fIkey ...\fR? \fIbody\fR
+Execute the Tcl script in \fIbody\fR with the value for each key in
+\fIdictionaryVariable\fR mapped (in a manner similarly to \fBdict
+update\fR) to a variable with the same name. Where one or more
+\fIkey\fRs are available, these indicate a chain of nested
+dictionaries, with the innermost dictionary being the one opened out
+for the execution of \fIbody\fR. As with \fBdict update\fR, making
+\fIdictionaryVariable\fR unreadable will make the updates to the
+dictionary be discarded, and this also happens if the contents of
+\fIdictionaryVariable\fR are adjusted so that the chain of
+dictionaries no longer exists. The result of \fBdict with\fR is
+(unless some kind of error occurs) the result of the evaluation of
+\fIbody\fR.
+.RS
+.PP
+The variables are mapped in the scope enclosing the \fBdict with\fR;
+it is recommended that this command only be used in a local scope
+(\fBproc\fRedure or lambda term for \fBapply\fR). Because of
+this, the variables set by \fBdict with\fR will continue to
+exist after the command finishes (unless explicitly \fBunset\fR).
+Note that the mapping of values to variables does not use
+traces; changes to the \fIdictionaryVariable\fR's contents only happen
+when \fIbody\fR terminates.
+.PP
+If the \fIdictionaryVariable\fR contains a value that is not a dictionary at
+the point when the \fIbody\fR terminates (which can easily happen if the name
+is the same as any of the keys in dictionary) then an error occurs at that
+point. This command is thus not recommended for use when the keys in the
+dictionary are expected to clash with the \fIdictionaryVariable\fR name
+itself. Where the contained key does map to a dictionary, the net effect is to
+combine that inner dictionary into the outer dictionary; see the
+\fBEXAMPLES\fR below for an illustration of this.
+.RE
+.SH "DICTIONARY VALUES"
+.PP
+Dictionaries are values that contain an efficient, order-preserving
+mapping from arbitrary keys to arbitrary values.
+Each key in the dictionary maps to a single value.
+They have a textual format that is exactly that of any list with an
+even number of elements, with each mapping in the dictionary being
+represented as two items in the list. When a command takes a
+dictionary and produces a new dictionary based on it (either returning
+it or writing it back into the variable that the starting dictionary
+was read from) the new dictionary will have the same order of keys,
+modulo any deleted keys and with new keys added on to the end.
+When a string is interpreted as a dictionary and it would otherwise
+have duplicate keys, only the last value for a particular key is used;
+the others are ignored, meaning that,
+.QW "apple banana"
+and
+.QW "apple carrot apple banana"
+are equivalent dictionaries (with different string representations).
+.PP
+Operations that derive a new dictionary from an old one (e.g., updates
+like \fBdict set\fR and \fBdict unset\fR) preserve the order of keys
+in the dictionary. The exceptions to this are for any new keys they
+add, which are appended to the sequence, and any keys that are
+removed, which are excised from the order.
+.SH EXAMPLES
+.PP
+Basic dictionary usage:
+.PP
+.CS
+# Make a dictionary to map extensions to descriptions
+set filetypes [\fBdict create\fR .txt "Text File" .tcl "Tcl File"]
+
+# Add/update the dictionary
+\fBdict set\fR filetypes .tcl "Tcl Script"
+\fBdict set\fR filetypes .tm "Tcl Module"
+\fBdict set\fR filetypes .gif "GIF Image"
+\fBdict set\fR filetypes .png "PNG Image"
+
+# Simple read from the dictionary
+set ext ".tcl"
+set desc [\fBdict get\fR $filetypes $ext]
+puts "$ext is for a $desc"
+
+# Somewhat more complex, with existence test
+foreach filename [glob *] {
+ set ext [file extension $filename]
+ if {[\fBdict exists\fR $filetypes $ext]} {
+ puts "$filename is a [\fBdict get\fR $filetypes $ext]"
+ }
+}
+.CE
+.PP
+Constructing and using nested dictionaries:
+.PP
+.CS
+# Data for one employee
+\fBdict set\fR employeeInfo 12345-A forenames "Joe"
+\fBdict set\fR employeeInfo 12345-A surname "Schmoe"
+\fBdict set\fR employeeInfo 12345-A street "147 Short Street"
+\fBdict set\fR employeeInfo 12345-A city "Springfield"
+\fBdict set\fR employeeInfo 12345-A phone "555-1234"
+# Data for another employee
+\fBdict set\fR employeeInfo 98372-J forenames "Anne"
+\fBdict set\fR employeeInfo 98372-J surname "Other"
+\fBdict set\fR employeeInfo 98372-J street "32995 Oakdale Way"
+\fBdict set\fR employeeInfo 98372-J city "Springfield"
+\fBdict set\fR employeeInfo 98372-J phone "555-8765"
+# The above data probably ought to come from a database...
+
+# Print out some employee info
+set i 0
+puts "There are [\fBdict size\fR $employeeInfo] employees"
+\fBdict for\fR {id info} $employeeInfo {
+ puts "Employee #[incr i]: $id"
+ \fBdict with\fR info {
+ puts " Name: $forenames $surname"
+ puts " Address: $street, $city"
+ puts " Telephone: $phone"
+ }
+}
+# Another way to iterate and pick out names...
+foreach id [\fBdict keys\fR $employeeInfo] {
+ puts "Hello, [\fBdict get\fR $employeeInfo $id forenames]!"
+}
+.CE
+.PP
+A localizable version of \fBstring toupper\fR:
+.PP
+.CS
+# Set up the basic C locale
+set capital [\fBdict create\fR C [\fBdict create\fR]]
+foreach c [split {abcdefghijklmnopqrstuvwxyz} ""] {
+ \fBdict set\fR capital C $c [string toupper $c]
+}
+
+# English locales can luckily share the "C" locale
+\fBdict set\fR capital en [\fBdict get\fR $capital C]
+\fBdict set\fR capital en_US [\fBdict get\fR $capital C]
+\fBdict set\fR capital en_GB [\fBdict get\fR $capital C]
+
+# ... and so on for other supported languages ...
+
+# Now get the mapping for the current locale and use it.
+set upperCaseMap [\fBdict get\fR $capital $env(LANG)]
+set upperCase [string map $upperCaseMap $string]
+.CE
+.PP
+Showing the detail of \fBdict with\fR:
+.PP
+.CS
+proc sumDictionary {varName} {
+ upvar 1 $varName vbl
+ foreach key [\fBdict keys\fR $vbl] {
+ # Manufacture an entry in the subdictionary
+ \fBdict set\fR vbl $key total 0
+ # Add the values and remove the old
+ \fBdict with\fR vbl $key {
+ set total [expr {$x + $y + $z}]
+ unset x y z
+ }
+ }
+ puts "last total was $total, for key $key"
+}
+
+set myDict {
+ a {x 1 y 2 z 3}
+ b {x 6 y 5 z 4}
+}
+
+sumDictionary myDict
+# prints: \fIlast total was 15, for key b\fR
+
+puts "dictionary is now \\"$myDict\\""
+# prints: \fIdictionary is now "a {total 6} b {total 15}"\fR
+.CE
+.PP
+When \fBdict with\fR is used with a key that clashes with the name of the
+dictionary variable:
+.PP
+.CS
+set foo {foo {a b} bar 2 baz 3}
+\fBdict with\fR foo {}
+puts $foo
+# prints: \fIa b foo {a b} bar 2 baz 3\fR
+.CE
+.SH "SEE ALSO"
+append(n), array(n), foreach(n), incr(n), list(n), lappend(n), set(n)
+.SH KEYWORDS
+dictionary, create, update, lookup, iterate, filter
diff --git a/doc/encoding.n b/doc/encoding.n
index 5950246..f8f3d54 100644
--- a/doc/encoding.n
+++ b/doc/encoding.n
@@ -39,6 +39,19 @@ 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 dirs\fR ?\fIdirectoryList\fR?
+.VS 8.5
+Tcl can load encoding data files from the file system that describe
+additional encodings for it to work with. This command sets the search
+path for \fB*.enc\fR encoding data files to the list of directories
+\fIdirectoryList\fR. If \fIdirectoryList\fR is omitted then the
+command returns the current list of directories that make up the
+search path. It is an error for \fIdirectoryList\fR to not be a valid
+list. If, when a search for an encoding data file is happening, an
+element in \fIdirectoryList\fR does not refer to a readable,
+searchable directory, that element is ignored.
+.VE 8.5
+.TP
\fBencoding names\fR
Returns a list containing the names of all of the encodings that are
currently available.
@@ -67,10 +80,11 @@ 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 [\fBencoding convertfrom\fR euc-jp "\\xA4\\xCF"]
+set s [\fBencoding convertfrom\fR euc-jp "\exA4\exCF"]
.CE
-would return the Unicode string "\\u306F", which is the Hiragana
-letter HA.
+would return the Unicode string
+.QW "\eu306F" ,
+which is the Hiragana letter HA.
.SH "SEE ALSO"
Tcl_GetEncoding(3)
diff --git a/doc/error.n b/doc/error.n
index 8c47ba3..77391e5 100644
--- a/doc/error.n
+++ b/doc/error.n
@@ -21,36 +21,42 @@ Returns a \fBTCL_ERROR\fR code, which causes command interpretation to be
unwound. \fIMessage\fR is a string that is returned to the application
to indicate what went wrong.
.PP
-If the \fIinfo\fR argument is provided and is non-empty,
-it is used to initialize the global variable \fBerrorInfo\fR.
-\fBerrorInfo\fR is used to accumulate a stack trace of what
-was in progress when an error occurred; as nested commands unwind,
-the Tcl interpreter adds information to \fBerrorInfo\fR. If the
-\fIinfo\fR argument is present, it is used to initialize
-\fBerrorInfo\fR and the first increment of unwind information
-will not be added by the Tcl interpreter. In other
+The \fB\-errorinfo\fR return option of an interpreter is used
+to accumulate a stack trace of what was in progress when an
+error occurred; as nested commands unwind,
+the Tcl interpreter adds information to the \fB\-errorinfo\fR
+return option. If the \fIinfo\fR argument is present, it is
+used to initialize the \fB\-errorinfo\fR return options and
+the first increment of unwind information
+will not be added by the Tcl interpreter.
+In other
words, the command containing the \fBerror\fR command will not appear
-in \fBerrorInfo\fR; in its place will be \fIinfo\fR.
-This feature is most useful in conjunction with the \fBcatch\fR command:
+in the stack trace; in its place will be \fIinfo\fR.
+Historically, this feature had been most useful in conjunction
+with the \fBcatch\fR command:
if a caught error cannot be handled successfully, \fIinfo\fR can be used
to return a stack trace reflecting the original point of occurrence
of the error:
.CS
\fBcatch {...} errMsg
-set savedInfo $errorInfo
+set savedInfo $::errorInfo
\&...
error $errMsg $savedInfo\fR
.CE
+When working with Tcl 8.5 or later, the following code
+should be used instead:
+.CS
+\fBcatch {...} errMsg options
+\&...
+return -options $options $errMsg\fR
+.CE
.PP
If the \fIcode\fR argument is present, then its value is stored
-in the \fBerrorCode\fR global variable. This variable is intended
-to hold a machine-readable description of the error in cases where
-such information is available; see the \fBtclvars\fR manual
-page for information on the proper format for the variable.
-If the \fIcode\fR argument is not
-present, then \fBerrorCode\fR is automatically reset to
-``NONE'' by the Tcl interpreter as part of processing the
-error generated by the command.
+in the \fB\-errorcode\fR return option. The \fB\-errorcode\fR
+return option is intended to hold a machine-readable description
+of the error in cases where such information is available; see
+the \fBreturn\fR manual page for information on the proper format
+for this option's value.
.SH EXAMPLE
Generate an error if a basic mathematical operation fails:
.CS
@@ -60,7 +66,7 @@ if {1+2 != 3} {
.CE
.SH "SEE ALSO"
-catch(n), return(n), tclvars(n)
+catch(n), return(n)
.SH KEYWORDS
-error, errorCode, errorInfo
+error
diff --git a/doc/eval.n b/doc/eval.n
index 81b9b1f..a642d23 100644
--- a/doc/eval.n
+++ b/doc/eval.n
@@ -25,10 +25,39 @@ Tcl interpreter recursively, and returns the result of that
evaluation (or any error generated by it).
Note that the \fBlist\fR command quotes sequences of words in such a
way that they are not further expanded by the \fBeval\fR command.
-.SH EXAMPLE
-This procedure acts in a way that is analogous to the \fBlappend\fR
-command, except it inserts the argument values at the start of the
-list in the variable:
+.SH EXAMPLES
+Often, it is useful to store a fragment of a script in a variable and
+execute it later on with extra values appended. This technique is used
+in a number of places throughout the Tcl core (e.g. in \fBfcopy\fR,
+\fBlsort\fR and \fBtrace\fR command callbacks). This example shows how
+to do this using core Tcl commands:
+.CS
+set script {
+ puts "logging now"
+ lappend $myCurrentLogVar
+}
+set myCurrentLogVar log1
+# Set up a switch of logging variable part way through!
+after 20000 set myCurrentLogVar log2
+
+for {set i 0} {$i<10} {incr i} {
+ # Introduce a random delay
+ after [expr {int(5000 * rand())}]
+ update ;# Check for the asynch log switch
+ \fBeval\fR $script $i [clock clicks]
+}
+.CE
+.PP
+.VS 8.5
+Note that in the most common case (where the script fragment is
+actually just a list of words forming a command prefix), it is better
+to use \fB{*}$script\fR when doing this sort of invocation
+pattern. It is less general than the \fBeval\fR command, and hence
+easier to make robust in practice.
+.VE 8.5
+The following procedure acts in a way that is analogous to the
+\fBlappend\fR command, except it inserts the argument values at the
+start of the list in the variable:
.CS
proc lprepend {varName args} {
upvar 1 $varName var
@@ -38,9 +67,16 @@ proc lprepend {varName args} {
set var [\fBeval\fR [list linsert $var 0] $args]
}
.CE
+.VS 8.5
+However, the last line would now normally be written without
+\fBeval\fR, like this:
+.CS
+set var [linsert $var 0 {*}$args]
+.CE
+.VE 8.5
+
+.SH "SEE ALSO"
+catch(n), concat(n), error(n), interp(n), list(n), namespace(n), subst(n), tclvars(n), uplevel(n)
.SH KEYWORDS
concatenate, evaluate, script
-
-.SH "SEE ALSO"
-catch(n), concat(n), error(n), list(n), subst(n), tclvars(n)
diff --git a/doc/exec.n b/doc/exec.n
index c5a2307..fd4e9cf 100644
--- a/doc/exec.n
+++ b/doc/exec.n
@@ -1,12 +1,13 @@
'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 2006 Donal K. Fellows.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.so man.macros
-.TH exec n 7.6 Tcl "Tcl Built-In Commands"
+.TH exec n 8.5 Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
@@ -28,6 +29,12 @@ they are treated as command-line switches and are not part
of the pipeline specification. The following switches are
currently supported:
.TP 13
+\fB\-ignorestderr\fR
+.VS 8.5
+Stops the \fBexec\fR command from treating the output of messages to the
+pipeline's standard error channel as an error case.
+.VE 8.5
+.TP 13
\fB\-keepnewline\fR
Retains a trailing newline in the pipeline's output.
Normally a trailing newline will be deleted.
@@ -40,76 +47,84 @@ If an \fIarg\fR (or pair of \fIarg\fRs) has one of the forms
described below then it is used by \fBexec\fR to control the
flow of input and output among the subprocess(es).
Such arguments will not be passed to the subprocess(es). In forms
-such as ``< \fIfileName\fR'' \fIfileName\fR may either be in a
-separate argument from ``<'' or in the same argument with no
-intervening space (i.e. ``<\fIfileName\fR'').
+such as
+.QW "\fB<\fR \fIfileName\fR" ,
+\fIfileName\fR may either be in a separate argument from
+.QW \fB<\fR
+or in the same argument with no intervening space (i.e.
+.QW \fB<\fIfileName\fR ).
.TP 15
-|
+\fB|\fR
Separates distinct commands in the pipeline. The standard output
of the preceding command will be piped into the standard input
of the next command.
.TP 15
-|&
+\fB|&\fR
Separates distinct commands in the pipeline. Both standard output
and standard error of the preceding command will be piped into
the standard input of the next command.
This form of redirection overrides forms such as 2> and >&.
.TP 15
-<\0\fIfileName\fR
+\fB<\0\fIfileName\fR
The file named by \fIfileName\fR is opened and used as the standard
input for the first command in the pipeline.
.TP 15
-<@\0\fIfileId\fR
+\fB<@\0\fIfileId\fR
\fIFileId\fR must be the identifier for an open file, such as the return
value from a previous call to \fBopen\fR.
It is used as the standard input for the first command in the pipeline.
\fIFileId\fR must have been opened for reading.
.TP 15
-<<\0\fIvalue\fR
+\fB<<\0\fIvalue\fR
\fIValue\fR is passed to the first command as its standard input.
.TP 15
->\0\fIfileName\fR
+\fB>\0\fIfileName\fR
Standard output from the last command is redirected to the file named
\fIfileName\fR, overwriting its previous contents.
.TP 15
-2>\0\fIfileName\fR
+\fB2>\0\fIfileName\fR
Standard error from all commands in the pipeline is redirected to the
file named \fIfileName\fR, overwriting its previous contents.
.TP 15
->&\0\fIfileName\fR
+\fB>&\0\fIfileName\fR
Both standard output from the last command and standard error from all
commands are redirected to the file named \fIfileName\fR, overwriting
its previous contents.
.TP 15
->>\0\fIfileName\fR
+\fB>>\0\fIfileName\fR
Standard output from the last command is
redirected to the file named \fIfileName\fR, appending to it rather
than overwriting it.
.TP 15
-2>>\0\fIfileName\fR
+\fB2>>\0\fIfileName\fR
Standard error from all commands in the pipeline is
redirected to the file named \fIfileName\fR, appending to it rather
than overwriting it.
.TP 15
->>&\0\fIfileName\fR
+\fB>>&\0\fIfileName\fR
Both standard output from the last command and standard error from
all commands are redirected to the file named \fIfileName\fR,
appending to it rather than overwriting it.
.TP 15
->@\0\fIfileId\fR
+\fB>@\0\fIfileId\fR
\fIFileId\fR must be the identifier for an open file, such as the return
value from a previous call to \fBopen\fR.
Standard output from the last command is redirected to \fIfileId\fR's
file, which must have been opened for writing.
.TP 15
-2>@\0\fIfileId\fR
+\fB2>@\0\fIfileId\fR
\fIFileId\fR must be the identifier for an open file, such as the return
value from a previous call to \fBopen\fR.
Standard error from all commands in the pipeline is
redirected to \fIfileId\fR's file.
The file must have been opened for writing.
.TP 15
->&@\0\fIfileId\fR
+\fB2>@1\0\fR
+Standard error from all commands in the pipeline is redirected to the
+command result. This operator is only valid at the end of the command
+pipeline.
+.TP 15
+\fB>&@\0\fIfileId\fR
\fIFileId\fR must be the identifier for an open file, such as the return
value from a previous call to \fBopen\fR.
Both standard output from the last command and standard error from
@@ -118,15 +133,23 @@ The file must have been opened for writing.
.PP
If standard output has not been redirected then the \fBexec\fR
command returns the standard output from the last command
-in the pipeline.
+in the pipeline,
+.VS 8.5
+unless
+.QW 2>@1
+was specified, in which case standard error is included as well.
+.VE 8.5
If any of the commands in the pipeline exit abnormally or
are killed or suspended, then \fBexec\fR will return an error
and the error message will include the pipeline's output followed by
error messages describing the abnormal terminations; the
-\fBerrorCode\fR variable will contain additional information
+\fB\-errorcode\fR return option will contain additional information
about the last abnormal termination encountered.
If any of the commands writes to its standard error file and that
-standard error isn't redirected,
+standard error is not redirected
+.VS 8.5
+and \fB\-ignorestderr\fR is not specified,
+.VE 8.5
then \fBexec\fR will return an error; the error message
will include the pipeline's standard output, followed by messages
about abnormal terminations (if any), followed by the standard error
@@ -135,22 +158,27 @@ output.
If the last character of the result or error message
is a newline then that character is normally deleted
from the result or error message.
-This is consistent with other Tcl return values, which don't
+This is consistent with other Tcl return values, which do not
normally end with newlines.
However, if \fB\-keepnewline\fR is specified then the trailing
newline is retained.
.PP
-If standard input isn't redirected with ``<'' or ``<<''
-or ``<@'' then the standard input for the first command in the
+If standard input is not redirected with
+.QW < ,
+.QW <<
+or
+.QW <@
+then the standard input for the first command in the
pipeline is taken from the application's current standard input.
.PP
-If the last \fIarg\fR is ``&'' then the pipeline will be
-executed in background.
+If the last \fIarg\fR is
+.QW &
+then the pipeline will be executed in background.
In this case the \fBexec\fR command will return a list whose
elements are the process identifiers for all of the subprocesses
in the pipeline.
The standard output from the last command in the pipeline will
-go to the application's standard output if it hasn't been
+go to the application's standard output if it has not been
redirected, and error output from all of
the commands in the pipeline will go to the application's
standard error file unless redirected.
@@ -162,26 +190,28 @@ in the PATH environment variable are searched for
an executable by the given name.
If the name contains a slash then it must refer to an executable
reachable from the current directory.
-No ``glob'' expansion or other shell-like substitutions
+No
+.QW glob
+expansion or other shell-like substitutions
are performed on the arguments to commands.
-
-.VS
.SH "PORTABILITY ISSUES"
.TP
\fBWindows\fR (all versions)
.
-Reading from or writing to a socket, using the ``\fB@\0\fIfileId\fR''
+Reading from or writing to a socket, using the
+.QW \fB@\0\fIfileId\fR
notation, does not work. When reading from a socket, a 16-bit DOS
application will hang and a 32-bit application will return immediately with
end-of-file. When either type of application writes to a socket, the
information is instead sent to the console, if one is present, or is
discarded.
-.sp
+.RS
+.PP
The Tk console text widget does not provide real standard IO capabilities.
Under Tk, when redirecting from standard input, all applications will see an
immediate end-of-file; information redirected to standard output or standard
error will be discarded.
-.sp
+.PP
Either forward or backward slashes are accepted as path separators for
arguments to Tcl commands. When executing an application, the path name
specified for the application may also contain forward or backward slashes
@@ -192,12 +222,16 @@ path name with forward slashes will not automatically be converted to use
the backslash character. If an argument contains forward slashes as the
path separator, it may or may not be recognized as a path name, depending on
the program.
-.sp
+.PP
Additionally, when calling a 16-bit DOS or Windows 3.X application, all path
-names must use the short, cryptic, path format (e.g., using ``applba~1.def''
-instead of ``applbakery.default''), which can be obtained with the
-\fBfile attributes $fileName -shortname\fR command.
-.sp
+names must use the short, cryptic, path format (e.g., using
+.QW applba~1.def
+instead of
+.QW applbakery.default ),
+which can be obtained with the
+.QW "\fBfile attributes \fIfileName \fB\-shortname\fR"
+command.
+.PP
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
@@ -206,25 +240,25 @@ 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.
-.sp
-.RS
+.PP
Note that there are two general types of Win32 console applications:
.RS
-1) CLI -- CommandLine Interface, simple stdio exchange. \fBnetstat.exe\fR for
+.IP [1]
+CLI \(em CommandLine Interface, simple stdio exchange. \fBnetstat.exe\fR for
example.
-.br
-2) TUI -- Textmode User Interface, any application that accesses the console
+.IP [2]
+TUI \(em Textmode User Interface, any application that accesses the console
API for doing such things as cursor movement, setting text color, detecting
key presses and mouse movement, etc. An example would be \fBtelnet.exe\fR
from Windows 2000. These types of applications are not common in a windows
environment, but do exist.
.RE
+.PP
\fBexec\fR will not work well with TUI applications when a console is not
present, as is done when launching applications under wish. It is desirable
to have console applications hidden and detached. This is a designed-in
limitation as \fBexec\fR wants to communicate over pipes. The Expect
extension addresses this issue when communicating with a TUI application.
-.sp
.RE
.TP
\fBWindows NT\fR
@@ -235,26 +269,24 @@ the name as it was specified. Then, in order, \fB.com\fR, \fB.exe\fR, and
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
+.IP \(bu
The directory from which the Tcl executable was loaded.
-.br
+.IP \(bu
The current directory.
-.br
+.IP \(bu
The Windows NT 32-bit system directory.
-.br
+.IP \(bu
The Windows NT 16-bit system directory.
-.br
+.IP \(bu
The Windows NT home directory.
-.br
+.IP \(bu
The directories listed in the path.
-.RE
-.sp
+.PP
In order to execute shell built-in commands like \fBdir\fR and \fBcopy\fR,
-the caller must prepend the desired command with ``\fBcmd.exe /c\0\fR''
+the caller must prepend the desired command with
+.QW "\fBcmd.exe /c\0\fR"
because built-in commands are not implemented using executables.
-.sp
.RE
.TP
\fBWindows 9x\fR
@@ -265,39 +297,42 @@ the name as it was specified. Then, in order, \fB.com\fR, \fB.exe\fR, and
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
+.IP \(bu
The directory from which the Tcl executable was loaded.
-.br
+.IP \(bu
The current directory.
-.br
+.IP \(bu
The Windows 9x system directory.
-.br
+.IP \(bu
The Windows 9x home directory.
-.br
+.IP \(bu
The directories listed in the path.
.RE
-.sp
+.RS
+.PP
In order to execute shell built-in commands like \fBdir\fR and \fBcopy\fR,
-the caller must prepend the desired command with ``\fBcommand.com /c\0\fR''
+the caller must prepend the desired command with
+.QW "\fBcommand.com /c\0\fR"
because built-in commands are not implemented using executables.
-.sp
+.PP
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
that standard input is closed. There is no known workaround for this bug
at this time.
-.sp
+.PP
Redirection between the \fBNUL:\fR device and a 16-bit application does not
always work. When redirecting from \fBNUL:\fR, some applications may hang,
-others will get an infinite stream of ``0x01'' bytes, and some will actually
+others will get an infinite stream of
+.QW 0x01
+bytes, and some will actually
correctly get an immediate end-of-file; the behavior seems to depend upon
something compiled into the application itself. When redirecting greater than
4K or so to \fBNUL:\fR, some applications will hang. The above problems do not
happen with 32-bit applications.
-.sp
+.PP
All DOS 16-bit applications are run synchronously. All standard input from
a pipe to a 16-bit DOS application is collected into a temporary file; the
other end of the pipe must be closed before the 16-bit DOS application
@@ -307,7 +342,7 @@ 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 standard Windows 95 DOS shell
handles pipes itself.
-.sp
+.PP
Certain applications, such as \fBcommand.com\fR, should not be executed
interactively. Applications which directly access the console window,
rather than reading from their standard input and writing to their standard
@@ -317,7 +352,6 @@ console window is not available to them.
.TP
\fBUnix\fR\0\0\0\0\0\0\0
The \fBexec\fR command is fully functional and works as described.
-
.SH "UNIX EXAMPLES"
Here are some examples of the use of the \fBexec\fR command on Unix.
.PP
@@ -327,13 +361,14 @@ To execute a simple program and get its result:
.CE
.PP
To execute a program that can return a non-zero result, you should
-wrap the call to \fBexec\fR in \fBcatch\fR and check what the contents
-of the global \fBerrorCode\fR variable is if you have an error:
+wrap the call to \fBexec\fR in \fBcatch\fR and check the contents
+of the \fB\-errorcode\fR return option if you have an error:
.CS
set status 0
-if {[catch {\fBexec\fR grep foo bar.txt} results]} {
- if {[lindex $::errorCode 0] eq "CHILDSTATUS"} {
- set status [lindex $::errorCode 2]
+if {[catch {\fBexec\fR grep foo bar.txt} results options]} {
+ set details [dict get $options -errorcode]
+ if {[lindex $details 0] eq "CHILDSTATUS"} {
+ set status [lindex $details 2]
} else {
# Some kind of unexpected failure
}
@@ -356,9 +391,8 @@ remember that Tcl does not handle globbing or expand things into
multiple arguments by default. Instead you should write things like
this:
.CS
-eval [list \fBexec\fR ls -l] [glob *.tcl]
+\fBexec\fR ls -l {*}[glob *.tcl]
.CE
-.PP
.SH "WINDOWS EXAMPLES"
Here are some examples of the use of the \fBexec\fR command on Windows.
.PP
@@ -392,15 +426,15 @@ differences in behaviour between \fBexec\fR and DOS batch files.
.PP
When in doubt, use the command \fBauto_execok\fR: it will return the
complete path to the program as seen by the \fBexec\fR command. This
-applies especially when you want to run "internal" commands like
+applies especially when you want to run
+.QW internal
+commands like
\fIdir\fR from a Tcl script (if you just want to list filenames, use
the \fBglob\fR command.) To do that, use this:
.CS
-eval [list \fBexec\fR] [auto_execok dir] [list *.tcl]
+\fBexec\fR {*}[auto_execok dir] *.tcl
.CE
-
.SH "SEE ALSO"
error(n), open(n)
-
.SH KEYWORDS
execute, pipeline, redirection, subprocess
diff --git a/doc/exit.n b/doc/exit.n
index 5d1dc0b..eccd635 100644
--- a/doc/exit.n
+++ b/doc/exit.n
@@ -19,23 +19,23 @@ exit \- End the application
.PP
Terminate the process, returning \fIreturnCode\fR to the
system as the exit status.
-If \fIreturnCode\fR isn't specified then it defaults
+If \fIreturnCode\fR is not specified then it defaults
to 0.
.SH EXAMPLE
Since non-zero exit codes are usually interpreted as error cases by
the calling process, the \fBexit\fR command is an important part of
-signalling that something fatal has gone wrong. This code fragment is
+signaling that something fatal has gone wrong. This code fragment is
useful in scripts to act as a general problem trap:
.CS
proc main {} {
# ... put the real main code in here ...
}
-if {[catch {main} msg]} {
+if {[catch {main} msg options]} {
puts stderr "unexpected script error: $msg"
if {[info exist env(DEBUG)]} {
puts stderr "---- BEGIN TRACE ----"
- puts stderr $errorInfo
+ puts stderr [dict get $options -errorinfo]
puts stderr "---- END TRACE ----"
}
@@ -45,7 +45,7 @@ if {[catch {main} msg]} {
.CE
.SH "SEE ALSO"
-exec(n), tclvars(n)
+exec(n)
.SH KEYWORDS
exit, process
diff --git a/doc/expr.n b/doc/expr.n
index 4c8903a..dbc9026 100644
--- a/doc/expr.n
+++ b/doc/expr.n
@@ -1,12 +1,13 @@
'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-2000 Sun Microsystems, Inc.
+'\" Copyright (c) 2005 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.so man.macros
-.TH expr n 8.4 Tcl "Tcl Built-In Commands"
+.TH expr n 8.5 Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
@@ -14,14 +15,14 @@ expr \- Evaluate an expression
.SH SYNOPSIS
\fBexpr \fIarg \fR?\fIarg arg ...\fR?
.BE
-
.SH DESCRIPTION
.PP
Concatenates \fIarg\fRs (adding separator spaces between them),
evaluates the result as a Tcl expression, and returns the value.
-The operators permitted in Tcl expressions are a subset of
-the operators permitted in C expressions, and they have the
-same meaning and precedence as the corresponding C operators.
+The operators permitted in Tcl expressions include a subset of
+the operators permitted in C expressions. For those operators
+common to both Tcl and C, Tcl applies the same meaning and precedence
+as the corresponding C operators.
Expressions almost always yield numeric results
(integer or floating-point values).
For example, the expression
@@ -31,36 +32,38 @@ For example, the expression
evaluates to 14.2.
Tcl expressions differ from C expressions in the way that
operands are specified. Also, Tcl expressions support
-non-numeric operands and string comparisons.
-.SH OPERANDS
+non-numeric operands and string comparisons, as well as some
+additional operators not found in C.
+.SS OPERANDS
.PP
A Tcl expression consists of a combination of operands, operators,
and parentheses.
White space may be used between the operands and operators and
parentheses; it is ignored by the expression's instructions.
Where possible, operands are interpreted as integer values.
-Integer values may be specified in decimal (the normal case), in octal (if the
-first character of the operand is \fB0\fR), or in hexadecimal (if the first
-two characters of the operand are \fB0x\fR).
+.VS 8.5
+Integer values may be specified in decimal (the normal case), in binary
+(if the first two characters of the operand are \fB0b\fR), in octal
+(if the first two characters of the operand are \fB0o\fR), or in hexadecimal
+(if the first two characters of the operand are \fB0x\fR). For
+compatibility with older Tcl releases, an octal integer value is also
+indicated simply when the first character of the operand is \fB0\fR,
+whether or not the second character is also \fBo\fR.
If an operand does not have one of the integer formats given
above, then it is treated as a floating-point number if that is
-possible. Floating-point numbers may be specified in any of the
-ways accepted by an ANSI-compliant C compiler (except that the
-\fBf\fR, \fBF\fR, \fBl\fR, and \fBL\fR suffixes will not be permitted in
-most installations). For example, all of the
+possible. Floating-point numbers may be specified in any of several
+common formats making use of the decimal digits, the decimal point \fB.\fR,
+the characters \fBe\fR or \fBE\fR indicating scientific notation, and
+the sign characters \fB+\fR or \fB\-\fR. For example, all of the
following are valid floating-point numbers: 2.1, 3., 6e4, 7.91e+16.
+Also recognized as floating point values are the strings \fBInf\fR
+and \fBNaN\fR making use of any case for each character.
+.VE 8.5
If no numeric interpretation is possible (note that all literal
operands that are not numeric or boolean must be quoted with either
braces or with double quotes), then an operand is left as a string
(and only a limited set of operators may be applied to it).
.PP
-.VS 8.4
-On 32-bit systems, integer values MAX_INT (0x7FFFFFFF) and MIN_INT
-(-0x80000000) will be represented as 32-bit values, and integer values
-outside that range will be represented as 64-bit values (if that is
-possible at all.)
-.VE 8.4
-.PP
Operands may be specified in any of the following ways:
.IP [1]
As a numeric value, either integer or floating-point.
@@ -84,8 +87,8 @@ The command will be executed and its result will be used as
the operand.
.IP [7]
As a mathematical function whose arguments have any of the above
-forms for operands, such as \fBsin($x)\fR. See below for a list of defined
-functions.
+forms for operands, such as \fBsin($x)\fR. See \fBMATH FUNCTIONS\fR below for
+a discussion of how mathematical functions are handled.
.LP
Where the above substitutions occur (e.g. inside quoted strings), they
are performed by the expression's instructions.
@@ -102,27 +105,46 @@ Then the command on the left side of each of the lines below
will produce the value on the right side of the line:
.CS
.ta 6c
-\fBexpr 3.1 + $a 6.1
-expr 2 + "$a.$b" 5.6
-expr 4*[llength "6 2"] 8
-expr {{word one} < "word $a"} 0\fR
+\fBexpr\fR 3.1 + $a \fI6.1\fR
+\fBexpr\fR 2 + "$a.$b" \fI5.6\fR
+\fBexpr\fR 4*[llength "6 2"] \fI8\fR
+\fBexpr\fR {{word one} < "word $a"} \fI0\fR
.CE
-.SH OPERATORS
+.SS OPERATORS
.PP
-The valid operators are listed below, grouped in decreasing order
-of precedence:
+The valid operators (most of which are also available as commands in
+the \fBtcl::mathop\fR namespace; see the \fBmathop\fR(n) manual page
+for details) are listed below, grouped in decreasing order of precedence:
.TP 20
\fB\-\0\0+\0\0~\0\0!\fR
Unary minus, unary plus, bit-wise NOT, logical NOT. None of these operators
may be applied to string operands, and bit-wise NOT may be
applied only to integers.
.TP 20
+\fB**\fR
+.VS 8.5
+Exponentiation. Valid for any numeric operands.
+.VE 8.5
+.TP 20
\fB*\0\0/\0\0%\fR
Multiply, divide, remainder. None of these operators may be
applied to string operands, and remainder may be applied only
to integers.
The remainder will always have the same sign as the divisor and
-an absolute value smaller than the divisor.
+an absolute value smaller than the absolute value of the divisor.
+.RS
+.PP
+When applied to integers, the division and remainder operators can be
+considered to partition the number line into a sequence of equal-sized
+adjacent non-overlapping pieces where each piece is the size of the divisor;
+the division result identifies which piece the divisor lay within, and the
+remainder result identifies where within that piece the divisor lay. A
+consequence of this is that the result of
+.QW "-57 \fB/\fR 10"
+is always -6, and the result of
+.QW "-57 \fB%\fR 10"
+is always 3.
+.RE
.TP 20
\fB+\0\0\-\fR
Add and subtract. Valid for any numeric operands.
@@ -140,12 +162,19 @@ in which case string comparison is used.
\fB==\0\0!=\fR
Boolean equal and not equal. Each operator produces a zero/one result.
Valid for all operand types.
-.VS 8.4
.TP 20
\fBeq\0\0ne\fR
Boolean string equal and string not equal. Each operator produces a
zero/one result. The operand types are interpreted only as strings.
-.VE 8.4
+.TP 20
+\fBin\0\0ni\fR
+.VS 8.5
+List containment and negated list containment. Each operator produces
+a zero/one result and treats its first argument as a string and its
+second argument as a Tcl list. The \fBin\fR operator indicates
+whether the first argument is a member of the second argument list;
+the \fBni\fR operator inverts the sense of the result.
+.VE 8.5
.TP 20
\fB&\fR
Bit-wise AND. Valid for integer operands only.
@@ -173,168 +202,84 @@ The \fIx\fR operand must have a boolean or numeric value.
.LP
See the C manual for more details on the results
produced by each operator.
+.VS 8.5
+The exponentiation operator promotes types like the multiply and
+divide operators, and produces a result that is the same as the output
+of the \fBpow\fR function (after any type conversions.)
+.VE 8.5
All of the binary operators group left-to-right within the same
precedence level. For example, the command
.CS
-\fBexpr 4*2 < 7\fR
+\fBexpr\fR {4*2 < 7}
.CE
returns 0.
.PP
-The \fB&&\fR, \fB||\fR, and \fB?:\fR operators have ``lazy
-evaluation'', just as in C,
-which means that operands are not evaluated if they are
+The \fB&&\fR, \fB||\fR, and \fB?:\fR operators have
+.QW "lazy evaluation" ,
+just as in C, which means that operands are not evaluated if they are
not needed to determine the outcome. For example, in the command
.CS
\fBexpr {$v ? [a] : [b]}\fR
.CE
-only one of \fB[a]\fR or \fB[b]\fR will actually be evaluated,
+only one of
+.QW \fB[a]\fR
+or
+.QW \fB[b]\fR
+will actually be evaluated,
depending on the value of \fB$v\fR. Note, however, that this is
only true if the entire expression is enclosed in braces; otherwise
-the Tcl parser will evaluate both \fB[a]\fR and \fB[b]\fR before
-invoking the \fBexpr\fR command.
-.SH "MATH FUNCTIONS"
+the Tcl parser will evaluate both
+.QW \fB[a]\fR
+and
+.QW \fB[b]\fR
+before invoking the \fBexpr\fR command.
+.SS "MATH FUNCTIONS"
+.PP
+.VS 8.5
+When the expression parser encounters a mathematical function
+such as \fBsin($x)\fR, it replaces it with a call to an ordinary
+Tcl function in the \fBtcl::mathfunc\fR namespace. The processing
+of an expression such as:
+.CS
+\fBexpr {sin($x+$y)}\fR
+.CE
+is the same in every way as the processing of:
+.CS
+\fBexpr {[tcl::mathfunc::sin [expr {$x+$y}]]}\fR
+.CE
+which in turn is the same as the processing of:
+.CS
+\fBtcl::mathfunc::sin [expr {$x+$y}]\fR
+.CE
.PP
-Tcl supports the following mathematical functions in expressions, all
-of which work solely with floating-point numbers unless otherwise noted:
-.DS
-.ta 3c 6c 9c
-\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 \fBwide\fR
-\fBceil\fR \fBhypot\fR \fBsin\fR
-\fBcos\fR \fBint\fR \fBsinh\fR
-.DE
+The executor will search for \fBtcl::mathfunc::sin\fR using the usual
+rules for resolving functions in namespaces. Either
+\fB::tcl::mathfunc::sin\fR or \fB[namespace
+current]::tcl::mathfunc::sin\fR will satisfy the request, and others
+may as well (depending on the current \fBnamespace path\fR setting).
.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 [\fI0\fR,\fIpi\fR]
-radians. \fIArg\fR should be in the range [\fI-1\fR,\fI1\fR].
-.TP
-\fBasin(\fIarg\fB)\fR
-Returns the arc sine of \fIarg\fR, in the range [\fI-pi/2\fR,\fIpi/2\fR]
-radians. \fIArg\fR should be in the range [\fI-1\fR,\fI1\fR].
-.TP
-\fBatan(\fIarg\fB)\fR
-Returns the arc tangent of \fIarg\fR, in the range [\fI-pi/2\fR,\fIpi/2\fR]
-radians.
-.TP
-\fBatan2(\fIy, x\fB)\fR
-Returns the arc tangent of \fIy\fR/\fIx\fR, in the range [\fI-pi\fR,\fIpi\fR]
-radians. \fIx\fR and \fIy\fR cannot both be 0. If \fIx\fR is greater
-than \fI0\fR, this is equivalent to \fBatan(\fIy/x\fB)\fR.
-.TP
-\fBceil(\fIarg\fB)\fR
-Returns the smallest integral floating-point value (i.e. with a zero
-fractional part) 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-point value, returns \fIarg\fR, otherwise converts
-\fIarg\fR to floating-point and returns the converted value.
-.TP
-\fBexp(\fIarg\fB)\fR
-Returns the exponential of \fIarg\fR, defined as \fIe\fR**\fIarg\fR.
-If the result would cause an overflow, an error is returned.
-.TP
-\fBfloor(\fIarg\fB)\fR
-Returns the largest integral floating-point value (i.e. with a zero
-fractional part) 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
-\fBsqrt(\fIx\fR*\fIx\fR+\fIy\fR*\fIy\fB)\fR.
-.TP
-\fBint(\fIarg\fB)\fR
-.VS 8.4
-If \fIarg\fR is an integer value of the same width as the machine
-word, returns \fIarg\fR, otherwise
-converts \fIarg\fR to an integer (of the same size as a machine word,
-i.e. 32-bits on 32-bit systems, and 64-bits on 64-bit systems) by
-truncation and returns the converted value.
-.VE 8.4
-.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 pseudo-random floating-point value in the range (\fI0\fR,\fI1\fR).
-The generator algorithm is a simple linear congruential generator that
-is not cryptographically secure. Each result from \fBrand\fR completely
-determines all future results from subsequent calls to \fBrand\fR, so
-\fBrand\fR should not be used to generate a sequence of secrets, such as
-one-time passwords. The seed of the generator is initialized from the
-internal clock of the machine or may be set with the \fBsrand\fR function.
-.TP
-\fBround(\fIarg\fB)\fR
-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 of \fBrand\fR. Returns the first random
-number (see \fBrand()\fR) from that seed. Each interpreter has its 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.
-.TP
-\fBwide(\fIarg\fB)\fR
-.VS 8.4
-Converts \fIarg\fR to an integer value at least 64-bits wide (by sign-extension
-if \fIarg\fR is a 32-bit number) if it is not one already.
-.VE 8.4
+See the \fBmathfunc\fR(n) manual page for the math functions that are
+available by default.
+.VE 8.5
+.SS "TYPES, OVERFLOW, AND PRECISION"
.PP
-In addition to these predefined functions, applications may
-define additional functions using \fBTcl_CreateMathFunc\fR().
-.SH "TYPES, OVERFLOW, AND PRECISION"
+.VS 8.5
+All internal computations involving integers are done calling on the
+LibTomMath multiple precision integer library as required so that all
+integer calculations are performed exactly. Note that in Tcl releases
+prior to 8.5, integer calculations were performed with one of the C types
+\fIlong int\fR or \fITcl_WideInt\fR, causing implicit range truncation
+in those calculations where values overflowed the range of those types.
+Any code that relied on these implicit truncations will need to explicitly
+add \fBint()\fR or \fBwide()\fR function calls to expressions at the points
+where such truncation is required to take place.
+.VE 8.5
.PP
-All internal computations involving integers are done with the C type
-\fIlong\fR, and all internal computations involving floating-point are
+All internal computations involving floating-point are
done with the C type \fIdouble\fR.
When converting a string to floating-point, exponent overflow is
-detected and results in a Tcl error.
-For conversion to integer from string, detection of overflow depends
-on the behavior of some routines in the local C library, so it should
-be regarded as unreliable.
-In any case, integer overflow and underflow are generally not detected
-reliably for intermediate results. Floating-point overflow and underflow
+detected and results in the \fIdouble\fR value of \fBInf\fR or
+\fB\-Inf\fR as appropriate. Floating-point overflow and underflow
are detected to the degree supported by the hardware, which is generally
pretty reliable.
.PP
@@ -344,35 +289,37 @@ For arithmetic computations, integers are used until some
floating-point number is introduced, after which floating-point is used.
For example,
.CS
-\fBexpr 5 / 4\fR
+\fBexpr\fR {5 / 4}
.CE
returns 1, while
.CS
-\fBexpr 5 / 4.0\fR
-\fBexpr 5 / ( [string length "abcd"] + 0.0 )\fR
+\fBexpr\fR {5 / 4.0}
+\fBexpr\fR {5 / ( [string length "abcd"] + 0.0 )}
.CE
both return 1.25.
-Floating-point values are always returned with a ``\fB.\fR''
-or an \fBe\fR so that they will not look like integer values. For
-example,
+Floating-point values are always returned with a
+.QW \fB.\fR
+or an
+.QW \fBe\fR
+so that they will not look like integer values. For example,
.CS
-\fBexpr 20.0/5.0\fR
+\fBexpr\fR {20.0/5.0}
.CE
returns \fB4.0\fR, not \fB4\fR.
-.SH "STRING OPERATIONS"
+.SS "STRING OPERATIONS"
.PP
String values may be used as operands of the comparison operators,
although the expression evaluator tries to do comparisons as integer
or floating-point when it can,
i.e., when all arguments to the operator allow numeric interpretations,
-.VS 8.4
except in the case of the \fBeq\fR and \fBne\fR operators.
-.VE 8.4
If one of the operands of a comparison is a string and the other
-has a numeric value, the numeric operand is converted back to
-a string using the C \fIsprintf\fR format specifier
-\fB%d\fR for integers and \fB%g\fR for floating-point values.
-For example, the commands
+has a numeric value, a canonical string representation of the numeric
+operand value is generated to compare with the string operand.
+Canonical string representation for integer values is a decimal string
+format. Canonical string representation for floating-point values
+is that produced by the \fB%g\fR format specifier of Tcl's
+\fBformat\fR command. For example, the commands
.CS
\fBexpr {"0x03" > "2"}\fR
\fBexpr {"0y" > "0x12"}\fR
@@ -380,14 +327,10 @@ For example, the commands
both return 1. The first comparison is done using integer
comparison, and the second is done using string comparison.
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
+possible, it is not 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
-.VS 8.4
-the \fBeq\fR or \fBne\fR operators, or
-.VE 8.4
-the \fBstring\fR command instead.
-
+operands could be arbitrary; it is better in these cases to use
+the \fBeq\fR or \fBne\fR operators, or the \fBstring\fR command instead.
.SH "PERFORMANCE CONSIDERATIONS"
.PP
Enclose expressions in braces for the best speed and the smallest
@@ -410,7 +353,7 @@ then the \fBexpr\fR command will evaluate the expression \fB$a + 2*4\fR.
Most expressions do not require a second round of substitutions.
Either they are enclosed in braces or, if not,
their variable and command substitutions yield numbers or strings
-that don't themselves require substitutions.
+that do not themselves require substitutions.
However, because a few unbraced expressions
need two rounds of substitutions,
the bytecode compiler must emit
@@ -419,12 +362,18 @@ 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.
+.VS 8.5
+When the expression is unbraced to allow the substitution of a function or
+operator, consider using the commands documented in the \fBmathfunc\fR(n) or
+\fBmathop\fR(n) manual pages directly instead.
+.VE 8.5
.SH EXAMPLES
-Define a procedure that computes an "interesting" mathematical
-function:
+Define a procedure that computes an
+.QW interesting
+mathematical function:
.CS
-proc calc {x y} {
- \fBexpr\fR { ($x*$x - $y*$y) / exp($x*$x + $y*$y) }
+proc tcl::mathfunc::calc {x y} {
+ \fBexpr\fR { ($x**2 - $y**2) / exp($x**2 + $y**2) }
}
.CE
.PP
@@ -461,9 +410,14 @@ Generate a random integer in the range 0..99 inclusive:
.CS
set randNum [\fBexpr\fR { int(100 * rand()) }]
.CE
-
.SH "SEE ALSO"
-array(n), for(n), if(n), string(n), Tcl(n), while(n)
-
+array(n), for(n), if(n), mathfunc(n), mathop(n), namespace(n), proc(n),
+string(n), Tcl(n), while(n)
.SH KEYWORDS
arithmetic, boolean, compare, expression, fuzzy comparison
+.SH COPYRIGHT
+.nf
+Copyright (c) 1993 The Regents of the University of California.
+Copyright (c) 1994-2000 Sun Microsystems Incorporated.
+Copyright (c) 2005 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved.
+.fi
diff --git a/doc/fblocked.n b/doc/fblocked.n
index 08d8054..d8e8af7 100644
--- a/doc/fblocked.n
+++ b/doc/fblocked.n
@@ -24,12 +24,10 @@ characters available for input and no end-of-line sequence, \fBgets\fR
returns an empty string and a subsequent call to \fBfblocked\fR will
return 1.
.PP
-.VS
\fIChannelId\fR must be an identifier for an open channel such as a
Tcl standard channel (\fBstdin\fR, \fBstdout\fR, or \fBstderr\fR),
the return value from an invocation of \fBopen\fR or \fBsocket\fR, or
the result of a channel creation command provided by a Tcl extension.
-.VE
.SH EXAMPLE
The \fBfblocked\fR command is particularly useful when writing network
servers, as it allows you to write your code in a line-by-line style
diff --git a/doc/fconfigure.n b/doc/fconfigure.n
index 19c8a61..0763232 100644
--- a/doc/fconfigure.n
+++ b/doc/fconfigure.n
@@ -47,7 +47,8 @@ channel can cause the process to block indefinitely.
The value of the option must be a proper boolean value.
Channels are normally in blocking mode; if a channel is placed into
nonblocking mode it will affect the operation of the \fBgets\fR,
-\fBread\fR, \fBputs\fR, \fBflush\fR, and \fBclose\fR commands;
+\fBread\fR, \fBputs\fR, \fBflush\fR, and \fBclose\fR commands by
+allowing them to operate asynchronously;
see the documentation for those commands for details.
For nonblocking mode to work correctly, the application must be
using the Tcl event loop (e.g. by calling \fBTcl_DoOneEvent\fR or
@@ -89,11 +90,14 @@ 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.
+byte-oriented data. It is usually better to set the
+\fB\-translation\fR option to \fBbinary\fR when you want to transfer
+binary data, as this turns off the other automatic interpretations of
+the bytes in the stream as well.
.PP
The default encoding for newly opened channels is the same platform- and
locale-dependent system encoding used for interfacing with the operating
-system.
+system, as returned by \fBencoding system\fR.
.RE
.TP
\fB\-eofchar\fR \fIchar\fR
@@ -114,6 +118,9 @@ 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.
+The acceptable range for \fB\-eofchar\fR values is \ex01 - \ex7f;
+attempting to set \fB\-eofchar\fR to a value outside of this range will
+generate an error.
.TP
\fB\-translation\fR \fImode\fR
.TP
@@ -124,11 +131,11 @@ 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
+normally used in network connections. On input (i.e., with \fBgets\fR
+and \fBread\fR) 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,
+with \fBputs\fR), the I/O system translates newlines to the external
+end-of-line representation. The default translation mode, \fBauto\fR,
handles all the common cases automatically, but the \fB\-translation\fR
option provides explicit control over the end of line translations.
.RS
@@ -146,25 +153,24 @@ currently supported:
\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
+(\fBlf\fR), carriage return (\fBcr\fR), or carriage return followed by a
+newline (\fBcrlf\fR) 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 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.
+Tcl chooses \fBcrlf\fR, for all Unix flavors, it chooses \fBlf\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.
.TP
\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
+\fBlf\fR mode, except that in addition \fBbinary\fR mode also sets the
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.
-.PP
.RS
+.PP
Internally, i.e. when it comes to the actual behaviour of the
translator this value \fBis\fR identical to \fBlf\fR and is therefore
reported as such when queried. Even if \fBbinary\fR was used to set
@@ -175,17 +181,17 @@ the translation.
.
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.
+\fBcr\fR mode converts carriage returns to newline characters. As the
+output translation mode, \fBcr\fR mode translates newline characters to
+carriage returns.
.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
+translation mode, \fBcrlf\fR mode converts carriage-return-linefeed
sequences to newline characters. As the output translation mode,
-\fBcrlf\fP mode translates newline characters to carriage-return-linefeed
+\fBcrlf\fR mode translates newline characters to carriage-return-linefeed
sequences. This mode is typically used on Windows platforms and for
network connections.
.TP
@@ -251,12 +257,12 @@ set words {}
while {[llength $words] < 3} {
gets $f line
if {[string match "#*" $line]} continue
- lappend words [eval concat [scan $line %d%d%d]]
+ lappend words {*}[join [scan $line %d%d%d]]
}
# Those words supply the size of the image and its
# overall depth per channel. Assign to variables.
-foreach {xSize ySize depth} $words {break}
+lassign $words xSize ySize depth
# Now switch to binary mode to pull in the data,
# one byte per channel (red,green,blue) per pixel.
diff --git a/doc/fcopy.n b/doc/fcopy.n
index 3702f15..d583cf0 100644
--- a/doc/fcopy.n
+++ b/doc/fcopy.n
@@ -10,54 +10,56 @@
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
-fcopy \- Copy data from one channel to another.
+fcopy \- Copy data from one channel to another
.SH SYNOPSIS
\fBfcopy \fIinchan\fR \fIoutchan\fR ?\fB\-size \fIsize\fR? ?\fB\-command \fIcallback\fR?
.BE
.SH DESCRIPTION
.PP
-The \fBfcopy\fP command copies data from one I/O channel, \fIinchan\fR to another I/O channel, \fIoutchan\fR.
-The \fBfcopy\fP command leverages the buffering in the Tcl I/O system to
+The \fBfcopy\fR command copies data from one I/O channel, \fIinchan\fR to another I/O channel, \fIoutchan\fR.
+The \fBfcopy\fR command leverages the buffering in the Tcl I/O system to
avoid extra copies and to avoid buffering too much data in
main memory when copying large files to slow destinations like
network sockets.
.PP
-The \fBfcopy\fP
+The \fBfcopy\fR
command transfers data from \fIinchan\fR until end of file
-or \fIsize\fP bytes have been
-transferred. If no \fB\-size\fP argument is given,
+or \fIsize\fR bytes have been
+transferred. If no \fB\-size\fR argument is given,
then the copy goes until end of file.
All the data read from \fIinchan\fR is copied to \fIoutchan\fR.
-Without the \fB\-command\fP option, \fBfcopy\fP blocks until the copy is complete
+Without the \fB\-command\fR option, \fBfcopy\fR blocks until the copy is complete
and returns the number of bytes written to \fIoutchan\fR.
.PP
-The \fB\-command\fP argument makes \fBfcopy\fP work in the background.
-In this case it returns immediately and the \fIcallback\fP is invoked
+The \fB\-command\fR argument makes \fBfcopy\fR work in the background.
+In this case it returns immediately and the \fIcallback\fR is invoked
later when the copy completes.
-The \fIcallback\fP is called with
+The \fIcallback\fR is called with
one or two additional
arguments that indicates how many bytes were written to \fIoutchan\fR.
If an error occurred during the background copy, the second argument is the
error string associated with the error.
With a background copy,
it is not necessary to put \fIinchan\fR or \fIoutchan\fR into
-non-blocking mode; the \fBfcopy\fP command takes care of that automatically.
+non-blocking mode; the \fBfcopy\fR command takes care of that automatically.
However, it is necessary to enter the event loop by using
-the \fBvwait\fP command or by using Tk.
+the \fBvwait\fR command or by using Tk.
.PP
You are not allowed to do other I/O operations with
-\fIinchan\fR or \fIoutchan\fR during a background fcopy.
+\fIinchan\fR or \fIoutchan\fR during a background \fBfcopy\fR.
If either \fIinchan\fR or \fIoutchan\fR get closed
while the copy is in progress, the current copy is stopped
-and the command callback is \fInot\fP made.
+and the command callback is \fInot\fR made.
If \fIinchan\fR is closed,
then all data already queued for \fIoutchan\fR is written out.
.PP
Note that \fIinchan\fR can become readable during a background copy.
-You should turn off any \fBfileevent\fP handlers during a background
+You should turn off any \fBfileevent\fR handlers during a background
copy so those handlers do not interfere with the copy.
-Any I/O attempted by a \fBfileevent\fP handler will get a "channel busy" error.
+Any I/O attempted by a \fBfileevent\fR handler will get a
+.QW "channel busy"
+error.
.PP
\fBFcopy\fR translates end-of-line sequences in \fIinchan\fR and \fIoutchan\fR
according to the \fB\-translation\fR option
@@ -67,30 +69,46 @@ See the manual entry for \fBfconfigure\fR for details on the
The translations mean that the number of bytes read from \fIinchan\fR
can be different than the number of bytes written to \fIoutchan\fR.
Only the number of bytes written to \fIoutchan\fR is reported,
-either as the return value of a synchronous \fBfcopy\fP or
-as the argument to the callback for an asynchronous \fBfcopy\fP.
+either as the return value of a synchronous \fBfcopy\fR or
+as the argument to the callback for an asynchronous \fBfcopy\fR.
.PP
-\fBFcopy\fR obeys the encodings configured for the channels. This
+\fBFcopy\fR obeys the encodings and character translations configured
+for the channels. This
means that the incoming characters are converted internally first
UTF-8 and then into the encoding of the channel \fBfcopy\fR writes
to. See the manual entry for \fBfconfigure\fR for details on the
-\fB\-encoding\fR option. No conversion is done if both channels are
-set to encoding "binary". If only the output channel is set to
-encoding "binary" the system will write the internal UTF-8
-representation of the incoming characters. If only the input channel
-is set to encoding "binary" the system will assume that the incoming
+\fB\-encoding\fR and \fB\-translation\fR options. No conversion is
+done if both channels are
+set to encoding
+.QW binary
+and have matching translations. If only the output channel is set to encoding
+.QW binary
+the system will write the internal UTF-8 representation of the incoming
+characters. If only the input channel is set to encoding
+.QW binary
+the system will assume that the incoming
bytes are valid UTF-8 characters and convert them according to the
output encoding. The behaviour of the system for bytes which are not
valid UTF-8 characters is undefined in this case.
-.SH EXAMPLE
+.SH EXAMPLES
.PP
-This first example shows how the callback gets
+The first example transfers the contents of one channel exactly to
+another. Note that when copying one file to another, it is better to
+use \fBfile copy\fR which also copies file metadata (e.g. the file
+access permissions) where possible.
+.CS
+fconfigure $in -translation binary
+fconfigure $out -translation binary
+\fBfcopy\fR $in $out
+.CE
+.PP
+This second example shows how the callback gets
passed the number of bytes transferred.
It also uses vwait to put the application into the event loop.
Of course, this simplified example could be done without the command
callback.
-.DS
+.CS
proc Cleanup {in out bytes {error {}}} {
global total
set total $bytes
@@ -102,14 +120,13 @@ proc Cleanup {in out bytes {error {}}} {
}
set in [open $file1]
set out [socket $server $port]
-fcopy $in $out -command [list Cleanup $in $out]
+\fBfcopy\fR $in $out -command [list Cleanup $in $out]
vwait total
-
-.DE
+.CE
.PP
-The second example copies in chunks and tests for end of file
+The third example copies in chunks and tests for end of file
in the command callback
-.DS
+.CS
proc CopyMore {in out chunk bytes {error {}}} {
global total done
incr total $bytes
@@ -118,21 +135,21 @@ proc CopyMore {in out chunk bytes {error {}}} {
close $in
close $out
} else {
- fcopy $in $out -command [list CopyMore $in $out $chunk] \\
- -size $chunk
+ \fBfcopy\fR $in $out -size $chunk \e
+ -command [list CopyMore $in $out $chunk]
}
}
set in [open $file1]
set out [socket $server $port]
set chunk 1024
set total 0
-fcopy $in $out -command [list CopyMore $in $out $chunk] -size $chunk
+\fBfcopy\fR $in $out -size $chunk \e
+ -command [list CopyMore $in $out $chunk]
vwait done
-
-.DE
+.CE
.SH "SEE ALSO"
-eof(n), fblocked(n), fconfigure(n)
+eof(n), fblocked(n), fconfigure(n), file(n)
.SH KEYWORDS
blocking, channel, end of line, end of file, nonblocking, read, translation
diff --git a/doc/file.n b/doc/file.n
index 6aeec52..b62d252 100644
--- a/doc/file.n
+++ b/doc/file.n
@@ -14,7 +14,6 @@ file \- Manipulate file names and attributes
.SH SYNOPSIS
\fBfile \fIoption\fR \fIname\fR ?\fIarg arg ...\fR?
.BE
-
.SH DESCRIPTION
.PP
This command provides several operations on a file's name or attributes.
@@ -30,7 +29,7 @@ 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
+does not 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
@@ -38,18 +37,19 @@ generated. On Windows, FAT file systems do not support access time.
\fBfile attributes \fIname\fR ?\fBoption\fR?
.TP
\fBfile attributes \fIname\fR ?\fBoption value option value...\fR?
-.RS
+.
This subcommand returns or sets platform specific values associated
with a file. The first form returns a list of the platform specific
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:
+.RS
.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
+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)
+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:
@@ -57,38 +57,49 @@ where multiple symbolic attributes can be separated by commas (example:
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).
+On versions of Unix supporting file flags, \fB\-readonly\fR gives the
+value or sets or clears the readonly attribute of the file,
+i.e. the user immutable flag \fBuchg\fR to chflags(1).
.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
-or clears the hidden attribute of the file. \fB-longname\fR will
+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
+or clears the hidden attribute of the file. \fB\-longname\fR will
expand each path element to its long version. This attribute cannot be
-set. \fB-readonly\fR gives the value or sets or clears the readonly
-attribute of the file. \fB-shortname\fR gives a string where every
+set. \fB\-readonly\fR gives the value or sets or clears the readonly
+attribute of the file. \fB\-shortname\fR gives a string where every
path element is replaced with its short (8.3) version of the
-name. This attribute cannot be set. \fB-system\fR gives or sets or
+name. This attribute cannot be set. \fB\-system\fR gives or sets or
clears the value of the system attribute of the file.
+.PP
+On Mac OS X and Darwin, \fB\-creator\fR gives or sets the
+Finder creator type of the file. \fB\-hidden\fR gives or sets or clears
+the hidden attribute of the file. \fB\-readonly\fR gives or sets or
+clears the readonly attribute of the file. \fB\-rsrclength\fR gives
+the length of the resource fork of the file, this attribute can only be
+set to the value 0, which results in the resource fork being stripped
+off the file.
.RE
-.VS
.TP
\fBfile channels ?\fIpattern\fR?
.
-If \fIpattern\fR isn't specified, returns a list of names of all
+If \fIpattern\fR is not 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
.TP
\fBfile copy \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR \fItarget\fR
.TP
\fBfile copy \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR ?\fIsource\fR ...? \fItargetDir\fR
-.RS
+.
The first form makes a copy of the file or directory \fIsource\fR under
the pathname \fItarget\fR. If \fItarget\fR is an existing directory,
then the second form is used. The second form makes a copy inside
\fItargetDir\fR of each \fIsource\fR file listed. If a directory is
specified as a \fIsource\fR, then the contents of the directory will be
recursively copied into \fItargetDir\fR. Existing files will not be
-overwritten unless the \fB\-force\fR option is specified. When copying
+overwritten unless the \fB\-force\fR option is specified (when Tcl will
+also attempt to adjust permissions on the destination file or directory
+if that is necessary to allow the copy to proceed). When copying
within a single filesystem, \fIfile copy\fR will copy soft links (i.e.
the links themselves are copied, not the things they point to). Trying
to overwrite a non-empty directory, overwrite a directory with a file,
@@ -97,7 +108,6 @@ or overwrite a file with a directory will all result in errors even if
specified, halting at the first error, if any. A \fB\-\|\-\fR marks
the end of switches; the argument following the \fB\-\|\-\fR will be
treated as a \fIsource\fR even if it starts with a \fB\-\fR.
-.RE
.TP
\fBfile delete \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIpathname\fR ?\fIpathname\fR ... ?
.
@@ -109,9 +119,11 @@ Trying to delete a non-existent file is not considered an error.
Trying to delete a read-only file will cause the file to be deleted,
even if the \fB\-force\fR flags is not specified. If the \fB\-force\fR
option is specified on a directory, Tcl will attempt both to change
-permissions and move the current directory 'pwd' out of the given path
-if that is necessary to allow the deletion to proceed. Arguments are
-processed in the order specified, halting at the first error, if any.
+permissions and move the current directory
+.QW pwd
+out of the given path if that is necessary to allow the deletion to
+proceed. Arguments are processed in the order specified, halting at
+the first error, if any.
A \fB\-\|\-\fR marks the end of switches; the argument following the
\fB\-\|\-\fR will be treated as a \fIpathname\fR even if it starts with
a \fB\-\fR.
@@ -119,9 +131,10 @@ a \fB\-\fR.
\fBfile dirname \fIname\fR
Returns a name comprised of all of the path components in \fIname\fR
excluding the last element. If \fIname\fR is a relative file name and
-only contains one path element, then returns ``\fB.\fR''.
-If \fIname\fR refers to a root directory, then the
-root directory is returned. For example,
+only contains one path element, then returns
+.QW \fB.\fR .
+If \fIname\fR refers to a root directory, then the root directory is
+returned. For example,
.RS
.CS
\fBfile dirname c:/\fR
@@ -182,36 +195,50 @@ is always canonical for the current platform: \fB/\fR for Unix and
Windows.
.RE
.TP
-\fBfile link ?\fI-linktype\fR? \fIlinkName\fR ?\fItarget\fR?
+\fBfile link ?\fI\-linktype\fR? \fIlinkName\fR ?\fItarget\fR?
.
If only one argument is given, that argument is assumed to be
\fIlinkName\fR, and this command returns the value of the link given by
\fIlinkName\fR (i.e. the name of the file it points to). If
-\fIlinkName\fR isn't a link or its value cannot be read (as, for example,
+\fIlinkName\fR is not a link or its value cannot be read (as, for example,
seems to be the case with hard links, which look just like ordinary
files), then an error is returned.
-.
+.RS
+.PP
If 2 arguments are given, then these are assumed to be \fIlinkName\fR
and \fItarget\fR. If \fIlinkName\fR already exists, or if \fItarget\fR
-doesn't exist, an error will be returned. Otherwise, Tcl creates a new
-link called \fIlinkName\fR which points to the existing filesystem object
-at \fItarget\fR, where the type of the link is platform-specific (on Unix
-a symbolic link will be the default). This is useful for the case where
-the user wishes to create a link in a cross-platform way, and doesn't
-care what type of link is created.
-.
+does not exist, an error will be returned. Otherwise, Tcl creates a new
+link called \fIlinkName\fR which points to the existing filesystem
+object at \fItarget\fR (which is also the returned value), where the
+type of the link is platform-specific (on Unix a symbolic link will be
+the default). This is useful for the case where the user wishes to
+create a link in a cross-platform way, and does not care what type of
+link is created.
+.PP
If the user wishes to make a link of a specific type only, (and signal an
error if for some reason that is not possible), then the optional
-\fI-linktype\fR argument should be given. Accepted values for
-\fI-linktype\fR are "-symbolic" and "-hard".
-.
-When creating links on filesystems that either do not support any links,
-or do not support the specific type requested, an error message will be
-returned. In particular Windows 95, 98 and ME do not support any links
-at present, but most Unix platforms support both symbolic and hard links
-(the latter for files only), MacOS supports symbolic links and Windows
-NT/2000/XP (on NTFS drives) support symbolic directory links and hard
-file links.
+\fI\-linktype\fR argument should be given. Accepted values for
+\fI\-linktype\fR are
+.QW \-symbolic
+and
+.QW \-hard .
+.PP
+On Unix, symbolic links can be made to relative paths, and those paths
+must be relative to the actual \fIlinkName\fR's location (not to the
+cwd), but on all other platforms where relative links are not supported,
+target paths will always be converted to absolute, normalized form
+before the link is created (and therefore relative paths are interpreted
+as relative to the cwd). Furthermore,
+.QW ~user
+paths are always expanded
+to absolute form. When creating links on filesystems that either do not
+support any links, or do not support the specific type requested, an
+error message will be returned. In particular Windows 95, 98 and ME do
+not support any links at present, but most Unix platforms support both
+symbolic and hard links (the latter for files only) and Windows
+NT/2000/XP (on NTFS drives) support symbolic
+directory links and hard file links.
+.RE
.TP
\fBfile lstat \fIname varName\fR
.
@@ -219,7 +246,7 @@ Same as \fBstat\fR option (see below) except uses the \fIlstat\fR
kernel call instead of \fIstat\fR. This means that if \fIname\fR
refers to a symbolic link the information returned in \fIvarName\fR
is for the link rather than the file it refers to. On systems that
-don't support symbolic links this option behaves exactly the same
+do not support symbolic links this option behaves exactly the same
as the \fBstat\fR option.
.TP
\fBfile mkdir \fIdir\fR ?\fIdir\fR ...?
@@ -237,32 +264,35 @@ 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
+1, 1970). If the file does not 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.
+filename is needed to pass to a platform-specific call, such as to a
+subprocess via \fBexec\fR under Windows (see \fBEXAMPLES\fR below).
.TP
\fBfile normalize \fIname\fR
.
-.RS
Returns a unique normalized path representation for the file-system
object (file, directory, link, etc), whose string value can be used as a
unique identifier for it. A normalized path is an absolute path which has
-all '../', './' removed. Also it is one which is in the ``standard''
-format for the native platform. On MacOS, Unix, this means the segments
+all
+.QW ../
+and
+.QW ./
+removed. Also it is one which is in the
+.QW standard
+format for the native platform. On Unix, this means the segments
leading up to the path must be free of symbolic links/aliases (but the
very last path component may be a symbolic link), and on Windows it also
means we want the long form with that form's case-dependence (which
gives us a unique, case-dependent path). The one exception concerning the
last link in the path is necessary, because Tcl or the user may wish to
-operate on the actual symbolic link itself (for example 'file delete', 'file
-rename', 'file copy' are defined to operate on symbolic links, not on the
-things that they point to).
-.RE
+operate on the actual symbolic link itself (for example \fBfile delete\fR,
+\fBfile rename\fR, \fBfile copy\fR are defined to operate on symbolic
+links, not on the things that they point to).
.TP
\fBfile owned \fIname\fR
.
@@ -271,13 +301,13 @@ otherwise.
.TP
\fBfile pathtype \fIname\fR
.
-Returns one of \fBabsolute\fR, \fBrelative\fR, \fBvolumerelative\fR. If
-\fIname\fR refers to a specific file on a specific volume, the path type
-will be \fBabsolute\fR. If \fIname\fR refers to a file relative to the
-current working directory, then the path type will be \fBrelative\fR. If
-\fIname\fR refers to a file relative to the current working directory on
-a specified volume, or to a specific file on the current working volume, then
-the path type is \fBvolumerelative\fR.
+Returns one of \fBabsolute\fR, \fBrelative\fR, \fBvolumerelative\fR. If
+\fIname\fR refers to a specific file on a specific volume, the path type will
+be \fBabsolute\fR. If \fIname\fR refers to a file relative to the current
+working directory, then the path type will be \fBrelative\fR. If \fIname\fR
+refers to a file relative to the current working directory on a specified
+volume, or to a specific file on the current working volume, then the path
+type is \fBvolumerelative\fR.
.TP
\fBfile readable \fIname\fR
.
@@ -287,14 +317,14 @@ Returns \fB1\fR if file \fIname\fR is readable by the current user,
\fBfile readlink \fIname\fR
.
Returns the value of the symbolic link given by \fIname\fR (i.e. the name
-of the file it points to). If \fIname\fR isn't a symbolic link or its
-value cannot be read, then an error is returned. On systems that don't
+of the file it points to). If \fIname\fR is not a symbolic link or its
+value cannot be read, then an error is returned. On systems that do not
support symbolic links this option is undefined.
.TP
\fBfile rename \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR \fItarget\fR
.TP
\fBfile rename \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR ?\fIsource\fR ...? \fItargetDir\fR
-.RS
+.
The first form takes the file or directory specified by pathname
\fIsource\fR and renames it to \fItarget\fR, moving the file if the
pathname \fItarget\fR specifies a name in a different directory. If
@@ -309,13 +339,14 @@ result in errors. Arguments are processed in the order specified,
halting at the first error, if any. A \fB\-\|\-\fR marks the end of
switches; the argument following the \fB\-\|\-\fR will be treated as a
\fIsource\fR even if it starts with a \fB\-\fR.
-.RE
.TP
\fBfile rootname \fIname\fR
.
Returns all of the characters in \fIname\fR up to but not including the
-last ``.'' character in the last component of name. If the last
-component of \fIname\fR doesn't contain a dot, then returns \fIname\fR.
+last
+.QW .
+character in the last component of name. If the last
+component of \fIname\fR does not contain a dot, then returns \fIname\fR.
.TP
\fBfile separator\fR ?\fIname\fR?
.
@@ -328,7 +359,7 @@ is generated.
\fBfile size \fIname\fR
.
Returns a decimal string giving the size of file \fIname\fR in bytes. If
-the file doesn't exist or its size cannot be queried then an error is
+the file does not exist or its size cannot be queried then an error is
generated.
.TP
\fBfile split \fIname\fR
@@ -336,7 +367,7 @@ generated.
Returns a list whose elements are the path components in \fIname\fR. The
first element of the list will have the same path type as \fIname\fR.
All other elements will be relative. Path separators will be discarded
-unless they are needed ensure that an element is unambiguously relative.
+unless they are needed to ensure that an element is unambiguously relative.
For example, under Unix
.RS
.CS
@@ -363,24 +394,32 @@ empty string.
.TP
\fBfile system \fIname\fR
.
-Returns a list of two elements, the first of which is the name of the
-filesystem to use for the file, and the second an arbitrary string
-representing the filesystem-specific nature or type of the location
-within that filesystem. If a filesystem only supports one type of file,
-the second element may be null. For example the native files have a
-first element 'native', and a second element which is a platform-specific
-type name for the file's system (e.g. 'NTFS', 'FAT', etc), or possibly
-the empty string if no further information is available or if this
-is not implemented. A generic virtual file system might return the
-list 'vfs ftp' to represent a file on a remote ftp site mounted as a
-virtual filesystem through an extension called 'vfs'. If the file does
-not belong to any filesystem, an error is generated.
+Returns a list of one or two elements, the first of which is the name of
+the filesystem to use for the file, and the second, if given, an
+arbitrary string representing the filesystem-specific nature or type of
+the location within that filesystem. If a filesystem only supports one
+type of file, the second element may not be supplied. For example the
+native files have a first element
+.QW native ,
+and a second element which when given is a platform-specific type name
+for the file's system (e.g.
+.QW NTFS ,
+.QW FAT ,
+on Windows). A generic virtual file system might return
+the list
+.QW "vfs ftp"
+to represent a file on a remote ftp site mounted as a
+virtual filesystem through an extension called
+.QW vfs .
+If the file does not belong to any filesystem, an error is generated.
.TP
\fBfile tail \fIname\fR
.
-Returns all of the characters in \fIname\fR after the last directory
-separator. If \fIname\fR contains no separators then returns
-\fIname\fR.
+Returns all of the characters in the last filesystem component of
+\fIname\fR. Any trailing directory separator in \fIname\fR is ignored.
+If \fIname\fR contains no separators then returns \fIname\fR. So,
+\fBfile tail a/b\fR, \fBfile tail a/b/\fR and \fBfile tail b\fR all
+return \fBb\fR.
.TP
\fBfile type \fIname\fR
.
@@ -391,10 +430,15 @@ Returns a string giving the type of file \fIname\fR, which will be one of
\fBfile volumes\fR
.
Returns the absolute paths to the volumes mounted on the system, as a
-proper Tcl list. On UNIX, the
-command will always return "/", since all filesystems are locally mounted.
+proper Tcl list. Without any virtual filesystems mounted as root
+volumes, on UNIX, the command will always return
+.QW / ,
+since all filesystems are locally mounted.
On Windows, it will return a list of the available local drives
-(e.g. {a:/ c:/}).
+(e.g.
+.QW "a:/ c:/" ).
+If any virtual filesystem has mounted additional
+volumes, they will be in the returned list.
.TP
\fBfile writable \fIname\fR
.
@@ -421,7 +465,7 @@ proc findMatchingCFiles {dir} {
set ext .o
}
}
- foreach file [glob -nocomplain -directory $dir *.c] {
+ foreach file [glob \-nocomplain \-directory $dir *.c] {
set objectFile [\fBfile tail\fR [\fBfile rootname\fR $file]]$ext
if {[\fBfile exists\fR $objectFile]} {
lappend files $file
@@ -441,12 +485,19 @@ if {![\fBfile isdirectory\fR [\fBfile dirname\fR $newName]]} {
\fBfile mkdir\fR [\fBfile dirname\fR $newName]
}
\fBfile rename\fR $oldName $newName
-\fBfile link\fR -symbolic $oldName $newName
+\fBfile link\fR \-symbolic $oldName $newName
+.CE
+.PP
+On Windows, a file can be
+.QW started
+easily enough (equivalent to double-clicking on it in the Explorer
+interface) but the name passed to the operating system must be in
+native format:
+.CS
+exec {*}[auto_execok start] {} [\fBfile nativename\fR ~/example.txt]
.CE
-
.SH "SEE ALSO"
filename(n), open(n), close(n), eof(n), gets(n), tell(n), seek(n),
fblocked(n), flush(n)
-
.SH KEYWORDS
attributes, copy files, delete files, directory, file, move files, name, rename files, stat
diff --git a/doc/fileevent.n b/doc/fileevent.n
index 99fe43a..eb555f5 100644
--- a/doc/fileevent.n
+++ b/doc/fileevent.n
@@ -28,17 +28,17 @@ interact with the user while waiting for the data to arrive. If an
application invokes \fBgets\fR or \fBread\fR on a blocking channel when
there is no input data available, the process will block; until the input
data arrives, it will not be able to service other events, so it will
-appear to the user to ``freeze up''. With \fBfileevent\fR, the process can
+appear to the user to
+.QW "freeze up" .
+With \fBfileevent\fR, the process can
tell when data is present and only invoke \fBgets\fR or \fBread\fR when
-they won't block.
+they will not block.
.PP
-.VS
The \fIchannelId\fR argument to \fBfileevent\fR refers to an open
channel such as a Tcl standard channel (\fBstdin\fR, \fBstdout\fR,
or \fBstderr\fR), the return value from an invocation of \fBopen\fR
or \fBsocket\fR, or the result of a channel creation command provided
by a Tcl extension.
-.VE
.PP
If the \fIscript\fR argument is specified, then \fBfileevent\fR
creates a new event handler: \fIscript\fR will be evaluated
@@ -94,7 +94,7 @@ The script for a file event is executed at global level (outside the
context of any Tcl procedure) in the interpreter in which the
\fBfileevent\fR command was invoked.
If an error occurs while executing the script then the
-\fBbgerror\fR mechanism is used to report the error.
+command registered with \fBinterp bgerror\fR is used to report the error.
In addition, the file event handler is deleted if it ever returns
an error; this is done in order to prevent infinite loops due to
buggy handlers.
@@ -117,7 +117,7 @@ proc GetData {chan} {
by Mark Diekhans.
.SH "SEE ALSO"
-bgerror(n), fconfigure(n), gets(n), puts(n), read(n), Tcl_StandardChannels(3)
+fconfigure(n), gets(n), interp(n), puts(n), read(n), Tcl_StandardChannels(3)
.SH KEYWORDS
asynchronous I/O, blocking, channel, event handler, nonblocking, readable,
diff --git a/doc/filename.n b/doc/filename.n
index 92d0eb7..1fe22f0 100644
--- a/doc/filename.n
+++ b/doc/filename.n
@@ -23,7 +23,6 @@ to be portable should not assume a particular form for file names.
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"
.PP
File names are grouped into three general types based on the starting point
@@ -36,21 +35,26 @@ qualified, either giving the path relative to the root directory on the
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"
.PP
The rules for native names depend on the value reported in the Tcl
array element \fBtcl_platform(platform)\fR:
.TP 10
-\fBunix\fR
-On Unix platforms, Tcl uses path names where the components are
-separated by slashes. Path names may be relative or absolute, and
-file names may contain any character other than slash. The file names
-\fB\&.\fR and \fB\&..\fR are special and refer to the current directory
-and the parent of the current directory respectively. Multiple
-adjacent slash characters are interpreted as a single separator.
-The following examples illustrate various forms of path names:
+\fBUnix\fR
+On Unix and Apple MacOS X platforms, Tcl uses path names where the
+components are separated by slashes. Path names may be relative or
+absolute, and file names may contain any character other than slash.
+The file names \fB\&.\fR and \fB\&..\fR are special and refer to the
+current directory and the parent of the current directory respectively.
+Multiple adjacent slash characters are interpreted as a single
+separator. Any number of trailing slash characters at the end of a
+path are simply ignored, so the paths \fBfoo\fR, \fBfoo/\fR and
+\fBfoo//\fR are all identical, and in particular \fBfoo/\fR does not
+necessarily mean a directory is being referred.
.RS
+.PP
+The following examples illustrate various forms of path
+names:
.TP 15
\fB/\fR
Absolute path to the root directory.
@@ -74,7 +78,7 @@ Relative path to the file \fBfoo\fR in the directory above the current
directory.
.RE
.TP
-\fBwindows\fR
+\fBWindows\fR
On Microsoft Windows platforms, Tcl supports both drive-relative and UNC
style names. Both \fB/\fR and \fB\e\fR may be used as directory separators
in either type of name. Drive-relative names consist of an optional drive
@@ -114,37 +118,39 @@ Volume-relative path to a file \fBfoo\fR in the root directory of the current
volume. This is not a valid UNC path, so the assumption is that the
extra backslashes are superfluous.
.RE
-
.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
-tilde, then the file name will be interpreted as if the first element
-is replaced with the location of the home directory for the given
-user. If the tilde is followed immediately by a separator, then the
-\fB$HOME\fR environment variable is substituted. Otherwise the
-characters between the tilde and the next separator are taken as a
-user name, which is used to retrieve the user's home directory for
-substitution.
+\fIcsh\fR-style tilde substitution. If a file name starts with a tilde,
+then the file name will be interpreted as if the first element is
+replaced with the location of the home directory for the given user. If
+the tilde is followed immediately by a separator, then the \fB$HOME\fR
+environment variable is substituted. Otherwise the characters between
+the tilde and the next separator are taken as a user name, which is used
+to retrieve the user's home directory for substitution. This works on
+Unix, MacOS X and Windows (except very old releases).
.PP
-The Windows platform does not support tilde substitution
-when a user name follows the tilde. On these platforms, attempts to
-use a tilde followed by a user name will generate an error that the
-user does not exist when Tcl attempts to interpret that part of the
-path or otherwise access the file. The behaviour of these paths
-when not trying to interpret them is the same as on Unix. File
-names that have a tilde without a user name will be correctly
-substituted using the \fB$HOME\fR environment variable, just like
-for Unix.
-
+Old Windows platforms do not support tilde substitution when a user name
+follows the tilde. On these platforms, attempts to use a tilde followed
+by a user name will generate an error that the user does not exist when
+Tcl attempts to interpret that part of the path or otherwise access the
+file. The behaviour of these paths when not trying to interpret them is
+the same as on Unix. File names that have a tilde without a user name
+will be correctly substituted using the \fB$HOME\fR environment
+variable, just like for Unix.
.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,
the character sets allowed on different devices may differ, so scripts
should choose file names that do not contain special characters like:
-\fB<>:"/\e|\fR. The safest approach is to use names consisting of
-alphanumeric characters only. Also Windows 3.1 only supports file
+\fB<>:?"/\e|\fR.
+'\""\" reset emacs highlighting
+The safest approach is to use names consisting of
+alphanumeric characters only. Care should be taken with filenames
+which contain spaces (common on Windows systems) and
+filenames where the backslash is the directory separator (Windows
+native path names). Also Windows 3.1 only supports file
names with a root of no more than 8 characters and an extension of no
more than 3 characters.
.PP
@@ -152,16 +158,21 @@ On Windows platforms there are file and path length restrictions.
Complete paths or filenames longer than about 260 characters will lead
to errors in most file operations.
.PP
-Another Windows peculiarity is that any number of trailing dots '.' in
-filenames are totally ignored, so, for example, attempts to create a
-file or directory with a name "foo." will result in the creation of a
-file/directory with name "foo". This fact is reflected in the
-results of 'file normalize'. Furthermore, a file name consisting only
-of dots '.........' or dots with trailing characters '.....abc' is
-illegal.
+Another Windows peculiarity is that any number of trailing dots
+.QW .
+in filenames are totally ignored, so, for example, attempts to create a
+file or directory with a name
+.QW foo.
+will result in the creation of a file/directory with name
+.QW foo .
+This fact is reflected in the results of \fBfile normalize\fR.
+Furthermore, a file name consisting only of dots
+.QW .........
+or dots with trailing characters
+.QW .....abc
+is illegal.
+.SH "SEE ALSO"
+file(n), glob(n)
.SH KEYWORDS
current directory, absolute file name, relative file name,
volume-relative file name, portability
-
-.SH "SEE ALSO"
-file(n), glob(n)
diff --git a/doc/flush.n b/doc/flush.n
index a288141..1c79ea0 100644
--- a/doc/flush.n
+++ b/doc/flush.n
@@ -19,13 +19,11 @@ flush \- Flush buffered output for a channel
.PP
Flushes any output that has been buffered for \fIchannelId\fR.
.PP
-.VS
\fIChannelId\fR must be an identifier for an open channel such as a
Tcl standard channel (\fBstdout\fR or \fBstderr\fR), the return
value from an invocation of \fBopen\fR or \fBsocket\fR, or the result
of a channel creation command provided by a Tcl extension. The
channel must have been opened for writing.
-.VE
.PP
If the channel is in blocking mode the command does not return until all the
buffered output has been flushed to the channel. If the channel is in
diff --git a/doc/for.n b/doc/for.n
index 14755cb..033903f 100644
--- a/doc/for.n
+++ b/doc/for.n
@@ -10,7 +10,7 @@
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
-for \- ``For'' loop
+for \- 'For' loop
.SH SYNOPSIS
\fBfor \fIstart test next body\fR
.BE
diff --git a/doc/foreach.n b/doc/foreach.n
index be7a6fb..654c0cf 100644
--- a/doc/foreach.n
+++ b/doc/foreach.n
@@ -35,9 +35,9 @@ In the general case there can be more than one value list
and each value list can be associated with a list of loop variables
(e.g., \fIvarlist1\fR and \fIvarlist2\fR).
During each iteration of the loop
-the variables of each \fIvarlist\fP are assigned
-consecutive values from the corresponding \fIlist\fP.
-Values in each \fIlist\fP are used in order from first to last,
+the variables of each \fIvarlist\fR are assigned
+consecutive values from the corresponding \fIlist\fR.
+Values in each \fIlist\fR are used in order from first to last,
and each value is used exactly once.
The total number of loop iterations is large enough to use
up all the values from all the value lists.
@@ -49,37 +49,48 @@ The \fBbreak\fR and \fBcontinue\fR statements may be
invoked inside \fIbody\fR, with the same effect as in the \fBfor\fR
command. \fBForeach\fR returns an empty string.
.SH EXAMPLES
+This loop prints every value in a list together with the square and
+cube of the value:
+.CS
+'\" Maintainers: notice the tab hacking below!
+.ta 3i
+set values {1 3 5 7 2 4 6 8} ;# Odd numbers first, for fun!
+puts "Value\etSquare\etCube" ;# Neat-looking header
+\fBforeach\fR x $values { ;# Now loop and print...
+ puts " $x\et [expr {$x**2}]\et [expr {$x**3}]"
+}
+.CE
.PP
The following loop uses i and j as loop variables to iterate over
pairs of elements of a single list.
-.DS
+.CS
set x {}
\fBforeach\fR {i j} {a b c d e f} {
lappend x $j $i
}
# The value of x is "b a d c f e"
# There are 3 iterations of the loop.
-.DE
+.CE
.PP
The next loop uses i and j to iterate over two lists in parallel.
-.DS
+.CS
set x {}
\fBforeach\fR i {a b c} j {d e f g} {
lappend x $i $j
}
# The value of x is "a d b e c f {} g"
# There are 4 iterations of the loop.
-.DE
+.CE
.PP
The two forms are combined in the following example.
-.DS
+.CS
set x {}
\fBforeach\fR i {a b c} {j k} {d e f g} {
lappend x $i $j $k
}
# The value of x is "a d e b f g c {} {}"
# There are 3 iterations of the loop.
-.DE
+.CE
.SH "SEE ALSO"
for(n), while(n), break(n), continue(n)
diff --git a/doc/format.n b/doc/format.n
index 0dea667..f842f16 100644
--- a/doc/format.n
+++ b/doc/format.n
@@ -17,9 +17,8 @@ format \- Format a string in the style of sprintf
.SH INTRODUCTION
.PP
-This command generates a formatted string in the same way as the
-ANSI C \fBsprintf\fR procedure (it uses \fBsprintf\fR in its
-implementation).
+This command generates a formatted string in a fashion similar to the
+ANSI C \fBsprintf\fR procedure.
\fIFormatString\fR indicates how to format the result, using
\fB%\fR conversion specifiers as in \fBsprintf\fR, and the additional
arguments, if any, provide values to be substituted into the result.
@@ -42,15 +41,15 @@ of all of the conversion specifiers in \fIformatString\fR.
.PP
Each conversion specifier may contain up to six different parts:
an XPG3 position specifier,
-a set of flags, a minimum field width, a precision, a length modifier,
+a set of flags, a minimum field width, a precision, a size modifier,
and a conversion character.
Any of these fields may be omitted except for the conversion character.
The fields that are present must appear in the order given above.
The paragraphs below discuss each of these fields in turn.
.PP
If the \fB%\fR is followed by a decimal number and a \fB$\fR, as in
-``\fB%2$d\fR'', then the value to convert is not taken from the
-next sequential argument.
+.QW \fB%2$d\fR ,
+then the value to convert 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 \fIarg\fR.
If the conversion specifier requires multiple arguments because
@@ -74,8 +73,8 @@ Specifies that a number should always be printed with a sign,
even if positive.
.TP 10
\fIspace\fR
-Specifies that a space should be added to the beginning of the
-number if the first character isn't a sign.
+Specifies that a space should be added to the beginning of the
+number if the first character is not a sign.
.TP 10
\fB0\fR
Specifies that the number should be padded on the left with
@@ -92,7 +91,7 @@ has a decimal point.
For \fBg\fR and \fBG\fR conversions it specifies that
trailing zeroes should not be removed.
.PP
-The third portion of a conversion specifier is a number giving a
+The third portion of a conversion specifier is a decimal number giving a
minimum field width for this conversion.
It is typically used to make columns line up in tabular printouts.
If the converted argument contains fewer characters than the
@@ -104,7 +103,7 @@ may be used to specify padding with zeroes on the left or with
spaces on the right, respectively.
If the minimum field width is specified as \fB*\fR rather than
a number, then the next argument to the \fBformat\fR command
-determines the minimum field width; it must be a numeric string.
+determines the minimum field width; it must be an integer value.
.PP
The fourth portion of a conversion specifier is a precision,
which consists of a period followed by a number.
@@ -123,17 +122,19 @@ If the precision is specified with \fB*\fR rather than a number
then the next argument to the \fBformat\fR command determines the precision;
it must be a numeric string.
.PP
-The fifth part of a conversion specifier is a length modifier,
-which must be \fBh\fR or \fBl\fR.
-If it is \fBh\fR it specifies that the numeric value should be
-truncated to a 16-bit value before converting.
-This option is rarely useful.
-.VS 8.4
-If it is \fBl\fR it specifies that the numeric value should be (at
-least) a 64-bit value. If neither \fBh\fR nor \fBl\fR are present,
-numeric values are interpreted as being values of the width of the
-native machine word, as described by \fBtcl_platform(wordSize)\fR.
-.VE
+The fifth part of a conversion specifier is a size modifier,
+which must be \fBll\fR, \fBh\fR, or \fBl\fR.
+If it is \fBll\fR it specifies that an integer value is taken
+without truncation for conversion to a formatted substring.
+If it is \fBh\fR it specifies that an integer value is
+truncated to a 16-bit range before converting. This option is rarely useful.
+If it is \fBl\fR it specifies that the integer value is
+truncated to the same range as that produced by the \fBwide()\fR
+function of the \fBexpr\fR command (at least a 64-bit range).
+If neither \fBh\fR nor \fBl\fR are present, the integer value is
+truncated to the same range as that produced by the \fBint()\fR
+function of the \fBexpr\fR command (at least a 32-bit range, but
+determined by the value of \fBtcl_platform(wordSize)\fR).
.PP
The last thing in a conversion specifier is an alphabetic character
that determines what kind of conversion to perform.
@@ -146,33 +147,32 @@ Convert integer to signed decimal string.
Convert integer to unsigned decimal string.
.TP 10
\fBi\fR
-Convert integer to signed decimal string; the integer may either be
-in decimal, in octal (with a leading \fB0\fR) or in hexadecimal
-(with a leading \fB0x\fR).
+Convert integer to signed decimal string (equivalent to \fBd\fR).
.TP 10
\fBo\fR
Convert integer to unsigned octal string.
.TP 10
\fBx\fR or \fBX\fR
Convert integer to unsigned hexadecimal string, using digits
-``0123456789abcdef'' for \fBx\fR and ``0123456789ABCDEF'' for \fBX\fR).
-.VS
+.QW 0123456789abcdef
+for \fBx\fR and
+.QW 0123456789ABCDEF
+for \fBX\fR).
.TP 10
\fBc\fR
Convert integer to the Unicode character it represents.
-.VE
.TP 10
\fBs\fR
No conversion; just insert string.
.TP 10
\fBf\fR
-Convert floating-point number to signed decimal string of
+Convert number to signed decimal string of
the form \fIxx.yyy\fR, where the number of \fIy\fR's is determined by
the precision (default: 6).
If the precision is 0 then no decimal point is output.
.TP 10
-\fBe\fR or \fBe\fR
-Convert floating-point number to scientific notation in the
+\fBe\fR or \fBE\fR
+Convert number to scientific notation in the
form \fIx.yyy\fBe\(+-\fIzz\fR, where the number of \fIy\fR's is determined
by the precision (default: 6).
If the precision is 0 then no decimal point is output.
@@ -181,40 +181,34 @@ printed instead of \fBe\fR.
.TP 10
\fBg\fR or \fBG\fR
If the exponent is less than \-4 or greater than or equal to the
-precision, then convert floating-point number as for \fB%e\fR or
+precision, then convert number as for \fB%e\fR or
\fB%E\fR.
Otherwise convert as for \fB%f\fR.
Trailing zeroes and a trailing decimal point are omitted.
.TP 10
\fB%\fR
No conversion: just insert \fB%\fR.
-.LP
-For the numerical conversions the argument being converted must
-be an integer or floating-point string; format converts the argument
-to binary and then converts it back to a string according to
-the conversion specifier.
.SH "DIFFERENCES FROM ANSI SPRINTF"
.PP
The behavior of the format command is the same as the
ANSI C \fBsprintf\fR procedure except for the following
differences:
.IP [1]
-\fB%p\fR and \fB%n\fR specifiers are not currently supported.
+\fB%p\fR and \fB%n\fR specifiers are not supported.
.IP [2]
-For \fB%c\fR conversions the argument must be a decimal string,
+For \fB%c\fR conversions the argument must be an integer value,
which will then be converted to the corresponding character value.
.IP [3]
-The \fBl\fR modifier
-.VS 8.4
-is ignored for real values and on 64-bit platforms, which are always
-converted as if the \fBl\fR modifier were present (i.e. the types
-\fBdouble\fR and \fBlong\fR are used for the internal representation
-of real and integer values, respectively).
-.VE 8.4
-If the \fBh\fR modifier is specified then integer values are truncated
-to \fBshort\fR before conversion. Both \fBh\fR and \fBl\fR modifiers
-are ignored on all other conversions.
+The size modifiers are ignored when formatting floating-point values.
+The \fBll\fR modifier has no \fBsprintf\fR counterpart.
.SH EXAMPLES
+Convert the numeric value of a UNICODE character to the character
+itself:
+.CS
+set value 120
+set char [\fBformat\fR %c $value]
+.CE
+.PP
Convert the output of \fBtime\fR into seconds to an accuracy of
hundredths of a second:
.CS
@@ -235,7 +229,7 @@ reordering the data values passed to \fBformat\fR:
set fmt1 "Today, %d shares in %s were bought at $%.2f each"
puts [\fBformat\fR $fmt1 123 "Global BigCorp" 19.37]
-set fmt2 "Bought %2\\$s equity ($%3$.2f x %1\\$d) today"
+set fmt2 "Bought %2\e$s equity ($%3$.2f x %1\e$d) today"
puts [\fBformat\fR $fmt2 123 "Global BigCorp" 19.37]
.CE
.PP
@@ -261,9 +255,7 @@ for {set i 0} {$i<=20} {incr i} {
# Finish off by printing the separator again
puts $sep
.CE
-
.SH "SEE ALSO"
scan(n), sprintf(3), string(n)
-
.SH KEYWORDS
conversion specifier, format, sprintf, string, substitution
diff --git a/doc/gets.n b/doc/gets.n
index d61d072..bed7e32 100644
--- a/doc/gets.n
+++ b/doc/gets.n
@@ -21,13 +21,11 @@ This command reads the next line from \fIchannelId\fR, returns everything
in the line up to (but not including) the end-of-line character(s), and
discards the end-of-line character(s).
.PP
-.VS
\fIChannelId\fR must be an identifier for an open channel such as the
Tcl standard input channel (\fBstdin\fR), the return value from an
invocation of \fBopen\fR or \fBsocket\fR, or the result of a channel
creation command provided by a Tcl extension. The channel must have
been opened for input.
-.VE
.PP
If \fIvarName\fR is omitted the line is returned as the result of the
command.
diff --git a/doc/glob.n b/doc/glob.n
index 1a08c7a..c257983 100644
--- a/doc/glob.n
+++ b/doc/glob.n
@@ -17,14 +17,17 @@ glob \- Return names of files that match patterns
.SH DESCRIPTION
.PP
-This command performs file name ``globbing'' in a fashion similar to
+This command performs file name
+.QW globbing
+in a fashion similar to
the csh shell. It returns a list of the files whose names match any
-of the \fIpattern\fR arguments.
+of the \fIpattern\fR arguments. No particular order is guaranteed
+in the list, so if a sorted list is required the caller should use
+\fBlsort\fR.
.LP
If the initial arguments to \fBglob\fR start with \fB\-\fR then
they are treated as switches. The following switches are
currently supported:
-.VS 8.3
.TP
\fB\-directory\fR \fIdirectory\fR
Search for files which match the given patterns starting in the given
@@ -35,14 +38,13 @@ characters explicitly. This option may not be used in conjunction with
whose names may contain glob-sensitive characters.
.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
+The remaining pattern arguments, after option processing, are treated
+as a single pattern obtained by joining the arguments with directory
+separators.
.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.
-.VS 8.3
.TP
\fB\-path\fR \fIpathPrefix\fR
Search for files with the given \fIpathPrefix\fR where the rest of the name
@@ -83,7 +85,13 @@ a directory will be returned if \fB\-types d\fR was specified.
.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.
+\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. Unrecognized 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.
@@ -94,10 +102,10 @@ The following are equivalent:
\fBglob */\fR
.CE
.RE
-except that the first case doesn't return the trailing ``/'' and
-is more platform independent.
+except that the first case doesn't return the trailing
+.QW /
+and is more platform independent.
.RE
-.VE 8.3
.TP
\fB\-\|\-\fR
Marks the end of switches. The argument following this one will
@@ -123,20 +131,35 @@ Matches the character \fIx\fR.
\fB{\fIa\fB,\fIb\fB,\fI...\fR}
Matches any of the strings \fIa\fR, \fIb\fR, etc.
.LP
-On Unix, as with csh, a ``.'' at the beginning of a file's name or just
-after a ``/'' must be matched explicitly or with a {} construct,
-unless the ``-types hidden'' flag is given (since ``.'' at the beginning
-of a file's name indicates that it is hidden). On other platforms,
-files beginning with a ``.'' are handled no differently to any others,
-except the special directories ``.'' and ``..'' which must be matched
-explicitly (this is to avoid a recursive pattern like ``glob -join * *
-* *'' from recursing up the directory hierarchy as well as down).
-In addition, all ``/'' characters must be matched explicitly.
+On Unix, as with csh, a
+.QW .
+at the beginning of a file's name or just after a
+.QW /
+must be matched explicitly or with a {} construct, unless the
+\fB\-types hidden\fR flag is given (since
+.QW .
+at the beginning of a file's name indicates that it is hidden). On
+other platforms, files beginning with a
+.QW .
+are handled no differently to any others, except the special directories
+.QW .
+and
+.QW ..
+which must be matched explicitly (this is to avoid a recursive pattern like
+.QW "glob -join * * * *"
+from recursing up the directory hierarchy as well as down). In addition, all
+.QW /
+characters must be matched explicitly.
.LP
-If the first character in a \fIpattern\fR is ``~'' then it refers
-to the home directory for the user whose name follows the ``~''.
-If the ``~'' is followed immediately by ``/'' then the value of
-the HOME environment variable is used.
+If the first character in a \fIpattern\fR is
+.QW ~
+then it refers to the home directory for the user whose name follows the
+.QW ~ .
+If the
+.QW ~
+is followed immediately by
+.QW /
+then the value of the HOME environment variable is used.
.LP
The \fBglob\fR command differs from csh globbing in two ways.
First, it does not sort its result list (use the \fBlsort\fR
@@ -146,29 +169,32 @@ exist; in csh no check for existence is made unless a pattern
contains a ?, *, or [] construct.
.LP
When the \fBglob\fR command returns relative paths whose filenames
-start with a tilde ``~'' (for example through \fBglob *\fR or
-\fBglob -tails\fR, the returned list will not quote the tilde with
-``./''. This means care must be taken if those names are later to
+start with a tilde
+.QW ~
+(for example through \fBglob *\fR or \fBglob -tails\fR, the returned
+list will not quote the tilde with
+.QW ./ .
+This means care must be taken if those names are later to
be used with \fBfile join\fR, to avoid them being interpreted as
absolute paths pointing to a given user's home directory.
.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.
-.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
+of the form
+.QW \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.
-
-.
+like
+.QW .../
+and
+.QW ..../
+for successively higher up parent directories.
+.PP
Since the backslash character has a special meaning to the glob
command, glob patterns containing Windows style path separators need
special care. The pattern \fIC:\e\efoo\e\e*\fR is interpreted as
@@ -195,7 +221,12 @@ Find all subdirectories of the current directory:
\fBglob\fR \-type d *
.CE
.PP
-Find all files whose name contains an "a", a "b" or the sequence "cde":
+Find all files whose name contains an
+.QW a ,
+a
+.QW b
+or the sequence
+.QW cde :
.CS
\fBglob\fR \-type f *{a,b,cde}*
.CE
diff --git a/doc/global.n b/doc/global.n
index b0e4389..c9d7a36 100644
--- a/doc/global.n
+++ b/doc/global.n
@@ -26,6 +26,10 @@ in the list returned by \fBinfo locals\fR).
If \fIvarname\fR contains namespace qualifiers, the local variable's name is
the unqualified name of the global variable, as determined by the
\fBnamespace tail\fR command.
+.PP
+\fIvarname\fR is always treated as the name of a variable, not an
+array element. An error is returned if the name looks like an array element,
+such as \fBa(b)\fR.
.SH EXAMPLES
This procedure sets the namespace variable \fI::a::x\fR
.CS
@@ -43,7 +47,7 @@ opened with \fBsocket\fR or as part of a counted HTTP response).
.CS
proc accum {string} {
\fBglobal\fR accumulator
- append accumulator $string \\n
+ append accumulator $string \en
}
.CE
diff --git a/doc/history.n b/doc/history.n
index 0ce7c4c..ba507b4 100644
--- a/doc/history.n
+++ b/doc/history.n
@@ -14,20 +14,20 @@ history \- Manipulate the history list
.SH SYNOPSIS
\fBhistory \fR?\fIoption\fR? ?\fIarg arg ...\fR?
.BE
-
.SH DESCRIPTION
.PP
The \fBhistory\fR command performs one of several operations related to
recently-executed commands recorded in a history list. Each of
-these recorded commands is referred to as an ``event''. When
-specifying an event to the \fBhistory\fR command, the following
+these recorded commands is referred to as an
+.QW event .
+When specifying an event to the \fBhistory\fR command, the following
forms may be used:
.IP [1]
A number: if positive, it refers to the event with
that number (all events are numbered starting at 1). If the number
is negative, it selects an event relative to the current event
(\fB\-1\fR refers to the previous event, \fB\-2\fR to the one before that, and
-so on). Event \fB0\fP refers to the current event.
+so on). Event \fB0\fR refers to the current event.
.IP [2]
A string: selects the most recent event that matches the string.
An event is considered to match the string either if the string is
@@ -43,7 +43,7 @@ as \fBhistory info\fR, described below.
\fBhistory add\fI command \fR?\fBexec\fR?
Adds the \fIcommand\fR argument to the history list as a new event. If
\fBexec\fR is specified (or abbreviated) then the command is also
-executed and its result is returned. If \fBexec\fR isn't specified
+executed and its result is returned. If \fBexec\fR is not specified
then an empty string is returned as result.
.TP
\fBhistory change\fI newValue\fR ?\fIevent\fR?
@@ -87,16 +87,16 @@ revision: see below for details.
.PP
Pre-8.0 Tcl had a complex history revision mechanism.
The current mechanism is more limited, and the old
-history operations \fBsubstitute\fP and \fBwords\fP have been removed.
-(As a consolation, the \fBclear\fP operation was added.)
+history operations \fBsubstitute\fR and \fBwords\fR have been removed.
+(As a consolation, the \fBclear\fR operation was added.)
.PP
-The history option \fBredo\fR results in much simpler ``history revision''.
+The history option \fBredo\fR results in much simpler
+.QW "history revision" .
When this option is invoked then the most recent event
is modified to eliminate the history command and replace it with
the result of the history command.
If you want to redo an event without modifying history, then use
-the \fBevent\fP operation to retrieve some event,
-and the \fBadd\fP operation to add it to history and execute it.
-
+the \fBevent\fR operation to retrieve some event,
+and the \fBadd\fR operation to add it to history and execute it.
.SH KEYWORDS
event, history, record
diff --git a/doc/http.n b/doc/http.n
index a563b5d..24b5f6a 100644
--- a/doc/http.n
+++ b/doc/http.n
@@ -7,21 +7,22 @@
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.so man.macros
-.TH "http" n 2.5 http "Tcl Bundled Packages"
+.TH "http" n 2.7 http "Tcl Bundled Packages"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
-http \- Client-side implementation of the HTTP/1.0 protocol.
+http \- Client-side implementation of the HTTP/1.1 protocol
.SH SYNOPSIS
-\fBpackage require http ?2.5?\fR
+\fBpackage require http ?2.7?\fR
+.\" See Also -useragent option documentation in body!
.sp
\fB::http::config \fI?options?\fR
.sp
\fB::http::geturl \fIurl ?options?\fR
.sp
-\fB::http::formatQuery\fP \fIkey value\fP ?\fIkey value\fP ...?
+\fB::http::formatQuery\fR \fIkey value\fR ?\fIkey value\fR ...?
.sp
-\fB::http::reset\fP \fItoken\fP ?\fIwhy\fP?
+\fB::http::reset\fR \fItoken\fR ?\fIwhy\fR?
.sp
\fB::http::wait \fItoken\fR
.sp
@@ -45,12 +46,12 @@ http \- Client-side implementation of the HTTP/1.0 protocol.
.sp
\fB::http::unregister \fIproto\fR
.BE
-
.SH DESCRIPTION
.PP
-The \fBhttp\fR package provides the client side of the HTTP/1.0
-protocol. The package implements the GET, POST, and HEAD operations
-of HTTP/1.0. It allows configuration of a proxy host to get through
+The \fBhttp\fR package provides the client side of the HTTP/1.1
+protocol, as defined in RFC 2616.
+The package implements the GET, POST, and HEAD operations
+of HTTP/1.1. 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. This package can be extended to support
@@ -63,9 +64,9 @@ 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.
+of this array are described in the \fBSTATE ARRAY\fR section.
.PP
-If the \fB-command\fP option is specified, then
+If the \fB\-command\fR option is specified, then
the HTTP operation is done in the background.
\fB::http::geturl\fR returns immediately after generating the
HTTP request and the callback is invoked
@@ -75,7 +76,7 @@ applications, the caller can use \fB::http::wait\fR after calling
\fB::http::geturl\fR to start the event loop.
.SH COMMANDS
.TP
-\fB::http::config\fP ?\fIoptions\fR?
+\fB::http::config\fR ?\fIoptions\fR?
The \fB::http::config\fR command is used to set and query the name of the
proxy server and port, and the User-Agent name used in the HTTP
requests. If no options are specified, then the current configuration
@@ -85,20 +86,21 @@ that setting is returned. Otherwise, the options should be a set of
flags and values that define the configuration:
.RS
.TP
-\fB\-accept\fP \fImimetypes\fP
+\fB\-accept\fR \fImimetypes\fR
The Accept header of the request. The default is */*, which means that
all types of documents are accepted. Otherwise you can supply a
comma-separated list of mime type patterns that you are
-willing to receive. For example, "image/gif, image/jpeg, text/*".
+willing to receive. For example,
+.QW "image/gif, image/jpeg, text/*" .
.TP
-\fB\-proxyhost\fP \fIhostname\fP
+\fB\-proxyhost\fR \fIhostname\fR
The name of the proxy host, if any. If this value is the
empty string, the URL host is contacted directly.
.TP
-\fB\-proxyport\fP \fInumber\fP
+\fB\-proxyport\fR \fInumber\fR
The proxy port number.
.TP
-\fB\-proxyfilter\fP \fIcommand\fP
+\fB\-proxyfilter\fR \fIcommand\fR
The command is a callback that is made during
\fB::http::geturl\fR
to determine if a proxy is required for a given host. One argument, a
@@ -109,7 +111,7 @@ an empty list. The default filter returns the values of the
\fB\-proxyhost\fR and \fB\-proxyport\fR settings if they are
non-empty.
.TP
-\fB\-urlencoding\fP \fIencoding\fP
+\fB\-urlencoding\fR \fIencoding\fR
The \fIencoding\fR used for creating the x-url-encoded URLs with
\fB::http::formatQuery\fR. The default is \fButf-8\fR, as specified by RFC
2718. Prior to http 2.5 this was unspecified, and that behavior can be
@@ -118,45 +120,46 @@ returned by specifying the empty string (\fB{}\fR), although
\fB::http::formatQuery\fR throwing an error processing non-latin-1
characters.
.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.4."\fR
+\fB\-useragent\fR \fIstring\fR
+The value of the User-Agent header in the HTTP request. The default is
+.QW "\fBTcl http client package 2.7\fR" .
.RE
.TP
-\fB::http::geturl\fP \fIurl\fP ?\fIoptions\fP?
+\fB::http::geturl\fR \fIurl\fR ?\fIoptions\fR?
The \fB::http::geturl\fR command is the main procedure in the package.
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 and ERRORS section for
+information about the transaction. See the \fBSTATE ARRAY\fR and
+\fBERRORS\fR 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.
\fB::http::geturl\fR takes several options:
.RS
.TP
-\fB\-binary\fP \fIboolean\fP
+\fB\-binary\fR \fIboolean\fR
Specifies whether to force interpreting the URL data as binary. Normally
this is auto-detected (anything not beginning with a \fBtext\fR content
type or whose content encoding is \fBgzip\fR or \fBcompress\fR is
considered binary data).
.TP
-\fB\-blocksize\fP \fIsize\fP
+\fB\-blocksize\fR \fIsize\fR
The block size used when reading the URL.
At most \fIsize\fR bytes are read at once. After each block, a call to the
\fB\-progress\fR callback is made (if that option is specified).
.TP
-\fB\-channel\fP \fIname\fP
+\fB\-channel\fR \fIname\fR
Copy the URL contents to channel \fIname\fR instead of saving it in
\fBstate(body)\fR.
.TP
-\fB\-command\fP \fIcallback\fP
-Invoke \fIcallback\fP after the HTTP transaction completes.
-This option causes \fB::http::geturl\fP to return immediately.
-The \fIcallback\fP gets an additional argument that is the \fItoken\fR returned
+\fB\-command\fR \fIcallback\fR
+Invoke \fIcallback\fR after the HTTP transaction completes.
+This option causes \fB::http::geturl\fR to return immediately.
+The \fIcallback\fR gets an additional argument that is the \fItoken\fR returned
from \fB::http::geturl\fR. This token is the name of an array that is
-described in the STATE ARRAY section. Here is a template for the
+described in the \fBSTATE ARRAY\fR section. Here is a template for the
callback:
.RS
.CS
@@ -167,27 +170,30 @@ proc httpCallback {token} {
.CE
.RE
.TP
-\fB\-handler\fP \fIcallback\fP
-Invoke \fIcallback\fP whenever HTTP data is available; if present, nothing
+\fB\-handler\fR \fIcallback\fR
+Invoke \fIcallback\fR whenever HTTP data is available; if present, nothing
else will be done with the HTTP data. This procedure gets two additional
arguments: the socket for the HTTP data and the \fItoken\fR returned from
-\fB::http::geturl\fR. The token is the name of a global array that is described
-in the STATE ARRAY section. The procedure is expected to return the number
-of bytes read from the socket. Here is a template for the callback:
+\fB::http::geturl\fR. The token is the name of a global array that is
+described in the \fBSTATE ARRAY\fR section. The procedure is expected
+to return the number of bytes read from the socket. Here is a
+template for the callback:
.RS
.CS
proc httpHandlerCallback {socket token} {
upvar #0 $token state
# Access socket, and state as a Tcl array
+ # For example...
...
- (example: set data [read $socket 1000];set nbytes [string length $data])
+ set data [read $socket 1000]
+ set nbytes [string length $data]
...
- return nbytes
+ return $nbytes
}
.CE
.RE
.TP
-\fB\-headers\fP \fIkeyvaluelist\fP
+\fB\-headers\fR \fIkeyvaluelist\fR
This option is used to add extra headers to the HTTP request. The
\fIkeyvaluelist\fR argument must be a list with an even number of
elements that alternate between keys and values. The keys become
@@ -199,7 +205,20 @@ HTTP request:
Pragma: no-cache
.CE
.TP
-\fB\-progress\fP \fIcallback\fP
+\fB\-keepalive\fR \fIboolean\fR
+If true, attempt to keep the connection open for servicing
+multiple requests. Default is 0.
+.TP
+\fB\-method\fR \fItype\fR
+Force the HTTP request method to \fItype\fR. \fB::http::geturl\fR will
+auto-select GET, POST or HEAD based on other options, but this option
+enables choices like PUT and DELETE for webdav support.
+.TP
+\fB\-myaddr\fR \fIaddress\fR
+Pass an specific local address to the underlying \fBsocket\fR call in case
+multiple interfaces are available.
+.TP
+\fB\-progress\fR \fIcallback\fR
The \fIcallback\fR is made after each transfer of data from the URL.
The callback gets three additional arguments: the \fItoken\fR from
\fB::http::geturl\fR, the expected total size of the contents from the
@@ -215,13 +234,18 @@ proc httpProgress {token total current} {
.CE
.RE
.TP
-\fB\-query\fP \fIquery\fP
+\fB\-protocol\fR \fIversion\fR
+Select the HTTP protocol version to use. This should be 1.0 or 1.1 (the
+default). Should only be necessary for servers that do not understand or
+otherwise complain about HTTP/1.1.
+.TP
+\fB\-query\fR \fIquery\fR
This flag causes \fB::http::geturl\fR to do a POST request that passes the
\fIquery\fR to the server. The \fIquery\fR must be an x-url-encoding
formatted query. The \fB::http::formatQuery\fR procedure can be used to
do the formatting.
.TP
-\fB\-queryblocksize\fP \fIsize\fP
+\fB\-queryblocksize\fR \fIsize\fR
The block size used when posting query data to the URL.
At most
\fIsize\fR
@@ -229,103 +253,106 @@ 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
+\fB\-querychannel\fR \fIchannelID\fR
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 an x-url-encoding
-formatted query unless the \fB\-type\fP option below is used.
+formatted query unless the \fB\-type\fR 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
+\fB\-queryprogress\fR \fIcallback\fR
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
+\fB\-strict\fR \fIboolean\fR
+Whether to enforce RFC 3986 URL validation on the request. Default is 1.
+.TP
+\fB\-timeout\fR \fImilliseconds\fR
If \fImilliseconds\fR is non-zero, then \fB::http::geturl\fR sets up a timeout
to occur after the specified number of milliseconds.
-A timeout results in a call to \fB::http::reset\fP and to
-the \fB-command\fP callback, if specified.
-The return value of \fB::http::status\fP is \fBtimeout\fP
+A timeout results in a call to \fB::http::reset\fR and to
+the \fB\-command\fR callback, if specified.
+The return value of \fB::http::status\fR is \fBtimeout\fR
after a timeout has occurred.
.TP
-\fB\-type\fP \fImime-type\fP
+\fB\-type\fR \fImime-type\fR
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
+\fB\-validate\fR \fIboolean\fR
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
contents are not returned. The meta information is available in the
-\fBstate(meta) \fR variable after the transaction. See the STATE
-ARRAY section for details.
+\fBstate(meta) \fR variable after the transaction. See the
+\fBSTATE ARRAY\fR section for details.
.RE
.TP
-\fB::http::formatQuery\fP \fIkey value\fP ?\fIkey value\fP ...?
+\fB::http::formatQuery\fR \fIkey value\fR ?\fIkey value\fR ...?
This procedure does x-url-encoding of query data. It takes an even
number of arguments that are the keys and values of the query. It
encodes the keys and values, and generates one string that has the
proper & and = separators. The result is suitable for the
\fB\-query\fR value passed to \fB::http::geturl\fR.
.TP
-\fB::http::reset\fP \fItoken\fP ?\fIwhy\fP?
+\fB::http::reset\fR \fItoken\fR ?\fIwhy\fR?
This command resets the HTTP transaction identified by \fItoken\fR, if
-any. This sets the \fBstate(status)\fP value to \fIwhy\fP, which defaults to \fBreset\fR, and then calls the registered \fB\-command\fR callback.
+any. This sets the \fBstate(status)\fR value to \fIwhy\fR, which defaults to \fBreset\fR, and then calls the registered \fB\-command\fR callback.
.TP
-\fB::http::wait\fP \fItoken\fP
+\fB::http::wait\fR \fItoken\fR
This is a convenience procedure that blocks and waits for the
transaction to complete. This only works in trusted code because it
-uses \fBvwait\fR. Also, it's not useful for the case where
-\fB::http::geturl\fP is called \fIwithout\fP the \fB-command\fP option
-because in this case the \fB::http::geturl\fP call doesn't return
-until the HTTP transaction is complete, and thus there's nothing to
+uses \fBvwait\fR. Also, it is not useful for the case where
+\fB::http::geturl\fR is called \fIwithout\fR the \fB\-command\fR option
+because in this case the \fB::http::geturl\fR call does not return
+until the HTTP transaction is complete, and thus there is nothing to
wait for.
.TP
-\fB::http::data\fP \fItoken\fP
-This is a convenience procedure that returns the \fBbody\fP element
+\fB::http::data\fR \fItoken\fR
+This is a convenience procedure that returns the \fBbody\fR 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
+\fB::http::error\fR \fItoken\fR
+This is a convenience procedure that returns the \fBerror\fR element
of the state array.
.TP
-\fB::http::status\fP \fItoken\fP
-This is a convenience procedure that returns the \fBstatus\fP element of
+\fB::http::status\fR \fItoken\fR
+This is a convenience procedure that returns the \fBstatus\fR element of
the state array.
.TP
-\fB::http::code\fP \fItoken\fP
-This is a convenience procedure that returns the \fBhttp\fP element of the
+\fB::http::code\fR \fItoken\fR
+This is a convenience procedure that returns the \fBhttp\fR element of the
state array.
.TP
-\fB::http::ncode\fP \fItoken\fP
+\fB::http::ncode\fR \fItoken\fR
This is a convenience procedure that returns just the numeric return
-code (200, 404, etc.) from the \fBhttp\fP element of the state array.
+code (200, 404, etc.) from the \fBhttp\fR element of the state array.
.TP
-\fB::http::size\fP \fItoken\fP
-This is a convenience procedure that returns the \fBcurrentsize\fP
+\fB::http::size\fR \fItoken\fR
+This is a convenience procedure that returns the \fBcurrentsize\fR
element of the state array, which represents the number of bytes
-received from the URL in the \fB::http::geturl\fP call.
+received from the URL in the \fB::http::geturl\fR call.
.TP
-\fB::http::meta\fP \fItoken\fP
-This is a convenience procedure that returns the \fBmeta\fP
+\fB::http::meta\fR \fItoken\fR
+This is a convenience procedure that returns the \fBmeta\fR
element of the state array which contains the HTTP response
headers. See below for an explanation of this element.
.TP
-\fB::http::cleanup\fP \fItoken\fP
+\fB::http::cleanup\fR \fItoken\fR
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
+identified by \fItoken\fR. After this call, the procedures
+like \fB::http::data\fR cannot be used to get information
+about the operation. It is \fIstrongly\fR recommended that you call
+this function after you are 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
+\fB::http::geturl\fR enough times, the memory leak could cause a
performance hit...or worse.
.TP
-\fB::http::register\fP \fIproto port command\fP
+\fB::http::register\fR \fIproto port command\fR
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.:
@@ -340,12 +367,11 @@ set token [::http::geturl https://my.secure.site/]
.CE
.RE
.TP
-\fB::http::unregister\fP \fIproto\fP
+\fB::http::unregister\fR \fIproto\fR
This procedure unregisters a protocol handler that was previously
registered via \fB::http::register\fR.
-
-.SH "ERRORS"
-The \fB::http::geturl\fP procedure will raise errors in the following cases:
+.SH ERRORS
+The \fB::http::geturl\fR procedure will raise errors in the following cases:
invalid command line options,
an invalid URL,
a URL on a non-existent host,
@@ -354,60 +380,59 @@ 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
+For synchronous \fB::http::geturl\fR calls (where \fB\-command\fR 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.
+reading the HTTP reply headers or data. Because \fB::http::geturl\fR
+does not return a token in these cases, it does all the required
+cleanup and there is no issue of your app having to call
+\fB::http::cleanup\fR.
.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
+For asynchronous \fB::http::geturl\fR calls, all of the above error
+situations apply, except that if there is 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
+after writing the HTTP headers, \fB::http::geturl\fR 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 its \fIerror\fP,
-calling \fB::http::error\fP to get the error message.
+\fB::http::status\fR to check the status and if its \fIerror\fR,
+calling \fB::http::error\fR 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
+\fB::http::wait\fR and then check status and error, just as the
callback does.
.PP
In any case, you must still call
-\fB::http::cleanup\fP to delete the state array when you're done.
+\fB::http::cleanup\fR to delete the state array when you are done.
.PP
There are other possible results of the HTTP transaction
-determined by examining the status from \fB::http::status\fP.
+determined by examining the status from \fB::http::status\fR.
These are described below.
.TP
ok
-If the HTTP transaction completes entirely, then status will be \fBok\fP.
-However, you should still check the \fB::http::code\fP value to get
-the HTTP status. The \fB::http::ncode\fP procedure provides just
-the numeric error (e.g., 200, 404 or 500) while the \fB::http::code\fP
-procedure returns a value like "HTTP 404 File not found".
+If the HTTP transaction completes entirely, then status will be \fBok\fR.
+However, you should still check the \fB::http::code\fR value to get
+the HTTP status. The \fB::http::ncode\fR procedure provides just
+the numeric error (e.g., 200, 404 or 500) while the \fB::http::code\fR
+procedure returns a value like
+.QW "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.
+is raised, but the status of the transaction will be \fBeof\fR.
.TP
error
-The error message will also be stored in the \fBerror\fP status
-array element, accessible via \fB::http::error\fP.
+The error message will also be stored in the \fBerror\fR status
+array element, accessible via \fB::http::error\fR.
.PP
-Another error possibility is that \fB::http::geturl\fP is unable to
+Another error possibility is that \fB::http::geturl\fR 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 \fB::http::geturl\fP attempts to complete the
+The error message is saved in the \fBposterror\fR status array
+element and then \fB::http::geturl\fR 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.
-
+it will end up with an \fBok\fR status, otherwise it will have
+an \fBeof\fR 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.
@@ -417,14 +442,14 @@ upvar #0 $token state
.CE
Once the data associated with the URL is no longer needed, the state
array should be unset to free up storage.
-The \fB::http::cleanup\fP procedure is provided for that purpose.
+The \fB::http::cleanup\fR procedure is provided for that purpose.
The following elements of
the array are supported:
.RS
.TP
\fBbody\fR
The contents of the URL. This will be empty if the \fB\-channel\fR
-option has been specified. This value is returned by the \fB::http::data\fP command.
+option has been specified. This value is returned by the \fB::http::data\fR command.
.TP
\fBcharset\fR
The value of the charset attribute from the \fBContent-Type\fR meta-data
@@ -437,7 +462,7 @@ A copy of the \fBContent-Encoding\fR meta-data value.
.TP
\fBcurrentsize\fR
The current number of bytes fetched from the URL.
-This value is returned by the \fB::http::size\fP command.
+This value is returned by the \fB::http::size\fR command.
.TP
\fBerror\fR
If defined, this is the error string seen when the HTTP transaction
@@ -445,10 +470,10 @@ was aborted.
.TP
\fBhttp\fR
The HTTP status reply from the server. This value
-is returned by the \fB::http::code\fP command. The format of this value is:
+is returned by the \fB::http::code\fR command. The format of this value is:
.RS
.CS
-\fIHTTP/1.0 code string\fP
+\fIHTTP/1.1 code string\fR
.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.
@@ -488,7 +513,7 @@ the post query data to the server.
.TP
\fBstatus\fR
Either \fBok\fR, for successful completion, \fBreset\fR for
-user-reset, \fBtimeout\fP if a timeout occurred before the transaction
+user-reset, \fBtimeout\fR 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
@@ -506,7 +531,7 @@ The requested URL.
# Copy a URL to a file and print meta-data
proc httpcopy { url file {chunk 4096} } {
set out [open $file w]
- set token [\fB::http::geturl\fR $url -channel $out \\
+ set token [\fB::http::geturl\fR $url -channel $out \e
-progress httpCopyProgress -blocksize $chunk]
close $out
@@ -537,9 +562,7 @@ proc httpCopyProgress {args} {
flush stderr
}
.CE
-
.SH "SEE ALSO"
safe(n), socket(n), safesock(n)
-
.SH KEYWORDS
security policy, socket
diff --git a/doc/if.n b/doc/if.n
index b9e9219..d84cf08 100644
--- a/doc/if.n
+++ b/doc/if.n
@@ -30,7 +30,8 @@ then \fBbody2\fR is executed, and so on.
If none of the expressions evaluates to true then \fIbodyN\fR is
executed.
The \fBthen\fR and \fBelse\fR arguments are optional
-``noise words'' to make the command easier to read.
+.QW "noise words"
+to make the command easier to read.
There may be any number of \fBelseif\fR clauses, including zero.
\fIBodyN\fR may also be omitted as long as \fBelse\fR is omitted too.
The return value from the command is the result of the body script
diff --git a/doc/incr.n b/doc/incr.n
index c98d795..72b3ff8 100644
--- a/doc/incr.n
+++ b/doc/incr.n
@@ -24,6 +24,12 @@ integer) is added to the value of variable \fIvarName\fR; otherwise
1 is added to \fIvarName\fR.
The new value is stored as a decimal string in variable \fIvarName\fR
and also returned as result.
+.PP
+.VS 8.5
+Starting with the Tcl 8.5 release, the variable \fIvarName\fR passed
+to \fBincr\fR may be unset, and in that case, it will be set to
+the value \fIincrement\fR or to the default increment value of \fB1\fR.
+.VE 8.5
.SH EXAMPLES
Add one to the contents of the variable \fIx\fR:
.CS
@@ -42,7 +48,7 @@ variable \fIx\fR:
.CE
.PP
Add nothing at all to the variable \fIx\fR (often useful for checking
-whether an argument to a procedure is actually numeric and generating
+whether an argument to a procedure is actually integral and generating
an error if it is not):
.CS
\fBincr\fR x 0
diff --git a/doc/info.n b/doc/info.n
index 1b11397..fae0d43 100644
--- a/doc/info.n
+++ b/doc/info.n
@@ -21,7 +21,7 @@ info \- Return information about the state of the Tcl interpreter
.PP
This command provides information about various internals of the Tcl
interpreter.
-The legal \fIoption\fR's (which may be abbreviated) are:
+The legal \fIoption\fRs (which may be abbreviated) are:
.TP
\fBinfo args \fIprocname\fR
Returns a list containing the names of the arguments to procedure
@@ -37,8 +37,11 @@ Returns a count of the total number of commands that have been invoked
in this interpreter.
.TP
\fBinfo commands \fR?\fIpattern\fR?
-If \fIpattern\fR isn't specified,
-returns a list of names of all the Tcl commands in the current namespace,
+If \fIpattern\fR is not specified,
+.\" Do not move this .VS above the .TP
+.VS 8.5
+returns a list of names of all the Tcl commands visible
+(i.e. executable without using a qualified name) to the current namespace,
including both the built-in commands written in C and
the command procedures defined using the \fBproc\fR command.
If \fIpattern\fR is specified,
@@ -51,21 +54,25 @@ and may have pattern matching special characters
at the end to specify a set of commands in that namespace.
If \fIpattern\fR is a qualified name,
the resulting list of command names has each one qualified with the name
-of the specified namespace.
+of the specified namespace, and only the commands defined in the named
+namespace are returned.
+.\" Technically, most of this hasn't changed; that's mostly just the
+.\" way it always worked. Hardly anyone knew that though.
+.VE 8.5
.TP
\fBinfo complete \fIcommand\fR
Returns 1 if \fIcommand\fR is a complete Tcl command in the sense of
having no unclosed quotes, braces, brackets or array element names.
-If the command doesn't appear to be complete then 0 is returned.
+If the command does not appear to be complete then 0 is returned.
This command is typically used in line-oriented input environments
to allow users to type in commands that span multiple lines; if the
-command isn't complete, the script can delay evaluating it until additional
+command is not complete, the script can delay evaluating it until additional
lines have been typed to complete the command.
.TP
\fBinfo default \fIprocname arg varname\fR
\fIProcname\fR must be the name of a Tcl command procedure and \fIarg\fR
must be the name of an argument to that procedure. If \fIarg\fR
-doesn't have a default value then the command returns \fB0\fR.
+does not have a default value then the command returns \fB0\fR.
Otherwise it returns \fB1\fR and places the default value of \fIarg\fR
into variable \fIvarname\fR.
.TP
@@ -73,18 +80,125 @@ into variable \fIvarname\fR.
Returns \fB1\fR if the variable named \fIvarName\fR exists in the
current context (either as a global or local variable) and has been
defined by being given a value, returns \fB0\fR otherwise.
-.VS 8.4
+.TP
+\fBinfo frame\fR ?\fInumber\fR?
+This command provides access to all frames on the stack, even those
+hidden from \fBinfo level\fR. If \fInumber\fR is not specified, this
+command returns a number giving the frame level of the command. This
+is 1 if the command is invoked at top-level. If \fInumber\fR is
+specified, then the result is a dictionary containing the location
+information for the command at the \fInumber\fRed level on the stack.
+.RS
+.PP
+If \fInumber\fR is positive (> 0) then it selects a particular stack
+level (1 refers to the top-most active command, i.e., \fBinfo frame\fR
+itself, 2 to the command it was called from, and so on); otherwise it
+gives a level relative to the current command (0 refers to the current
+command, i.e., \fBinfo frame\fR itself, -1 to its caller, and so on).
+.PP
+This is similar to how \fBinfo level\fR works, except that this
+subcommand reports all frames, like \fBsource\fRd scripts,
+\fBeval\fRs, \fBuplevel\fRs, etc.
+.PP
+Note that for nested commands, like
+.QW "foo [bar [x]]" ,
+only
+.QW x
+will be seen by an \fBinfo frame\fR invoked within
+.QW x .
+This is the same as for \fBinfo level\fR and error stack traces.
+.PP
+The result dictionary may contain the keys listed below, with the
+specified meanings for their values:
+.TP
+\fBtype\fR
+This entry is always present and describes the nature of the location
+for the command. The recognized values are \fBsource\fR, \fBproc\fR,
+\fBeval\fR, and \fBprecompiled\fR.
+.RS
+.TP
+\fBsource\fR\0\0\0\0\0\0\0\0
+means that the command is found in a script loaded by the \fBsource\fR
+command.
+.TP
+\fBproc\fR\0\0\0\0\0\0\0\0
+means that the command is found in dynamically created procedure body.
+.TP
+\fBeval\fR\0\0\0\0\0\0\0\0
+means that the command is executed by \fBeval\fR or \fBuplevel\fR.
+.TP
+\fBprecompiled\fR\0\0\0\0\0\0\0\0
+means that the command is found in a precompiled script (loadable by
+the package \fBtbcload\fR), and no further information will be
+available.
+.RE
+.TP
+\fBline\fR
+This entry provides the number of the line the command is at inside of
+the script it is a part of. This information is not present for type
+\fBprecompiled\fR. For type \fBsource\fR this information is counted
+relative to the beginning of the file, whereas for the last two types
+the line is counted relative to the start of the script.
+.TP
+\fBfile\fR
+This entry is present only for type \fBsource\fR. It provides the
+normalized path of the file the command is in.
+.TP
+\fBcmd\fR
+This entry provides the string representation of the command. This is
+usually the unsubstituted form, however for commands which are a pure
+list executed by eval it is the substituted form as they have no other
+string representation. Care is taken that the pure-List property of
+the latter is not spoiled.
+.TP
+\fBproc\fR
+This entry is present only if the command is found in the body of a
+regular Tcl procedure. It then provides the name of that procedure.
+.TP
+\fBlambda\fR
+This entry is present only if the command is found in the body of an
+anonymous Tcl procedure, i.e. a lambda. It then provides the entire
+definition of the lambda in question.
+.TP
+\fBlevel\fR
+This entry is present only if the queried frame has a corresponding
+frame returned by \fBinfo level\fR. It provides the index of this
+frame, relative to the current level (0 and negative numbers).
+.PP
+A thing of note is that for procedures statically defined in files the
+locations of commands in their bodies will be reported with type
+\fBsource\fR and absolute line numbers, and not as type
+\fBproc\fR. The same is true for procedures nested in statically
+defined procedures, and literal eval scripts in files or statically
+defined procedures.
+.PP
+In contrast, a procedure definition or \fBeval\fR within a dynamically
+\fBeval\fRuated environment count linenumbers relative to the start of
+their script, even if they would be able to count relative to the
+start of the outer dynamic script. That type of number usually makes
+more sense.
+.PP
+A different way of describing this behaviour is that file based
+locations are tracked as deeply as possible, and where this is not
+possible the lines are counted based on the smallest possible
+\fBeval\fR or procedure body, as that scope is usually easier to find
+than any dynamic outer scope.
+.PP
+The syntactic form \fB{*}\fR is handled like \fBeval\fR. I.e. if it
+is given a literal list argument the system tracks the linenumber
+within the list words as well, and otherwise all linenumbers are
+counted relative to the start of each word (smallest scope)
+.RE
.TP
\fBinfo functions \fR?\fIpattern\fR?
-If \fIpattern\fR isn't specified, returns a list of all the math
+If \fIpattern\fR is not specified, returns a list of all the math
functions currently defined.
If \fIpattern\fR is specified, only those functions whose name matches
\fIpattern\fR are returned. Matching is determined using the same
rules as for \fBstring match\fR.
-.VE
.TP
\fBinfo globals \fR?\fIpattern\fR?
-If \fIpattern\fR isn't specified, returns a list of all the names
+If \fIpattern\fR is not specified, returns a list of all the names
of currently-defined global variables.
Global variables are variables in the global namespace.
If \fIpattern\fR is specified, only those names matching \fIpattern\fR
@@ -94,13 +208,11 @@ are returned. Matching is determined using the same rules as for
\fBinfo hostname\fR
Returns the name of the computer on which this invocation is being
executed.
-.VS
Note that this name is not guaranteed to be the fully qualified domain
name of the host. Where machines have several different names (as is
common on systems with both TCP/IP (DNS) and NetBIOS-based networking
installed,) it is the name that is suitable for TCP/IP networking that
is returned.
-.VE
.TP
\fBinfo level\fR ?\fInumber\fR?
If \fInumber\fR is not specified, this command returns a number
@@ -135,7 +247,7 @@ To get a list of just the packages in the current interpreter, specify
an empty string for the \fIinterp\fR argument.
.TP
\fBinfo locals \fR?\fIpattern\fR?
-If \fIpattern\fR isn't specified, returns a list of all the names
+If \fIpattern\fR is not specified, returns a list of all the names
of currently-defined local variables, including arguments to the
current procedure, if any.
Variables defined with the \fBglobal\fR, \fBupvar\fR and
@@ -154,7 +266,7 @@ Returns the value of the global variable \fBtcl_patchLevel\fR; see
the \fBtclvars\fR manual entry for more information.
.TP
\fBinfo procs \fR?\fIpattern\fR?
-If \fIpattern\fR isn't specified, returns a list of all the
+If \fIpattern\fR is not specified, returns a list of all the
names of Tcl command procedures in the current namespace.
If \fIpattern\fR is specified,
only those procedure names in the current namespace
@@ -180,7 +292,7 @@ Otherwise the command returns an empty string.
\fBinfo sharedlibextension\fR
Returns the extension used on this platform for the names of files
containing shared libraries (for example, \fB.so\fR under Solaris).
-If shared libraries aren't supported on this platform then an empty
+If shared libraries are not supported on this platform then an empty
string is returned.
.TP
\fBinfo tclversion\fR
@@ -188,7 +300,7 @@ Returns the value of the global variable \fBtcl_version\fR; see
the \fBtclvars\fR manual entry for more information.
.TP
\fBinfo vars\fR ?\fIpattern\fR?
-If \fIpattern\fR isn't specified,
+If \fIpattern\fR is not specified,
returns a list of all the names of currently-visible variables.
This includes locals and currently-visible globals.
If \fIpattern\fR is specified, only those names matching \fIpattern\fR
@@ -203,11 +315,14 @@ If \fIpattern\fR is a qualified name,
the resulting list of variable names
has each matching namespace variable qualified with the name
of its namespace.
-Note that a currently-visible variable may not yet "exist" if it has not
+Note that a currently-visible variable may not yet
+.QW exist
+if it has not
been set (e.g. a variable declared but not set by \fBvariable\fR).
.SH EXAMPLE
This command prints out a procedure suitable for saving in a Tcl
script:
+.PP
.CS
proc printProc {procName} {
set result [list proc $procName]
@@ -224,13 +339,10 @@ proc printProc {procName} {
puts [lappend result $formals [\fBinfo body\fR $procName]]
}
.CE
-
.SH "SEE ALSO"
global(n), proc(n)
-
.SH KEYWORDS
command, information, interpreter, level, namespace, procedure, variable
-
-'\" Local Variables:
-'\" mode: nroff
-'\" End:
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
diff --git a/doc/interp.n b/doc/interp.n
index bbe7826..c753ee9 100644
--- a/doc/interp.n
+++ b/doc/interp.n
@@ -1,5 +1,6 @@
'\"
'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 2004 Donal K. Fellows
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
@@ -11,15 +12,14 @@
.SH NAME
interp \- Create and manipulate Tcl interpreters
.SH SYNOPSIS
-\fBinterp \fIoption \fR?\fIarg arg ...\fR?
+\fBinterp \fIsubcommand \fR?\fIarg arg ...\fR?
.BE
-
.SH DESCRIPTION
.PP
-This command makes it possible to create one or more new Tcl
+This command makes it possible to create one or more new Tcl
interpreters that co-exist with the creating interpreter in the
same application. The creating interpreter is called the \fImaster\fR
-and the new interpreter is called a \fIslave\fR.
+and the new interpreter is called a \fIslave\fR.
A master can create any number of slaves, and each slave can
itself create additional slaves for which it is master, resulting
in a hierarchy of interpreters.
@@ -32,7 +32,11 @@ a command in a slave interpreter which, when invoked, causes a
command to be invoked in its master interpreter or in another slave
interpreter. The only other connections between interpreters are
through environment variables (the \fBenv\fR variable), which are
-normally shared among all interpreters in the application. Note that the
+normally shared among all interpreters in the application,
+.VS 8.5
+and by resource limit exceeded callbacks.
+.VE 8.5
+Note that the
name space for files (such as the names returned by the \fBopen\fR command)
is no longer shared between interpreters. Explicit commands are provided to
share files and to transfer references to open files from one interpreter
@@ -45,7 +49,6 @@ scripts without fear of them damaging other interpreters or the
application's environment. For example, all IO channel creation
commands and subprocess creation commands are made inaccessible to safe
interpreters.
-.VS
See \fBSAFE INTERPRETERS\fR below for more information on
what features are present in a safe interpreter.
The dangerous functionality is not removed from the safe interpreter;
@@ -53,10 +56,9 @@ instead, it is \fIhidden\fR, so that only trusted interpreters can obtain
access to it. For a detailed explanation of hidden commands, see
\fBHIDDEN COMMANDS\fR, below.
The alias mechanism can be used for protected communication (analogous to a
-kernel call) between a slave interpreter and its master.
-See \fBALIAS INVOCATION\fR, below, for more details
+kernel call) between a slave interpreter and its master.
+See \fBALIAS INVOCATION\fR, below, for more details
on how the alias mechanism works.
-.VE
.PP
A qualified interpreter name is a proper Tcl lists containing a subset of its
ancestors in the interpreter hierarchy, terminated by the string naming the
@@ -78,7 +80,7 @@ Both restrictions are motivated by safety concerns.
The \fBinterp\fR command is used to create, delete, and manipulate
slave interpreters, and to share or transfer
channels between interpreters. It can have any of several forms, depending
-on the \fIoption\fR argument:
+on the \fIsubcommand\fR argument:
.TP
\fBinterp\fR \fBalias\fR \fIsrcPath\fR \fIsrcToken\fR
Returns a Tcl list whose elements are the \fItargetCmd\fR and
@@ -102,7 +104,9 @@ may be anywhere in the hierarchy of interpreters under the interpreter
invoking the command.
\fISrcPath\fR and \fIsrcCmd\fR identify the source of the alias.
\fISrcPath\fR is a Tcl list whose elements select a particular
-interpreter. For example, ``\fBa b\fR'' identifies an interpreter
+interpreter. For example,
+.QW "\fBa b\fR"
+identifies an interpreter
\fBb\fR, which is a slave of interpreter \fBa\fR, which is a slave
of the invoking interpreter. An empty list specifies the interpreter
invoking the command. \fIsrcCmd\fR gives the name of a new
@@ -116,7 +120,7 @@ already exist; it is not created by this command.
The alias arranges for the given target command to be invoked
in the target interpreter whenever the given source command is
invoked in the source interpreter. See \fBALIAS INVOCATION\fR below for
-more details.
+more details.
The command returns a token that uniquely identifies the command created
\fIsrcCmd\fR, even if the command is renamed afterwards. The token may but
does not have to be equal to \fIsrcCmd\fR.
@@ -124,16 +128,26 @@ does not have to be equal to \fIsrcCmd\fR.
\fBinterp\fR \fBaliases \fR?\fIpath\fR?
This command returns a Tcl list of the tokens of all the source commands for
aliases defined in the interpreter identified by \fIpath\fR. The tokens
-correspond to the values returned when
-the aliases were created (which may not be the same
+correspond to the values returned when
+the aliases were created (which may not be the same
as the current names of the commands).
.TP
+\fBinterp bgerror \fIpath\fR ?\fIcmdPrefix\fR?
+.VS 8.5
+This command either gets or sets the current background error handler
+for the interpreter identified by \fIpath\fR. If \fIcmdPrefix\fR is
+absent, the current background error handler is returned, and if it is
+present, it is a list of words (of minimum length one) that describes
+what to set the interpreter's background error to. See the
+\fBBACKGROUND ERROR HANDLING\fR section for more details.
+.VE 8.5
+.TP
\fBinterp\fR \fBcreate \fR?\fB\-safe\fR? ?\fB\-\|\-\fR? ?\fIpath\fR?
Creates a slave interpreter identified by \fIpath\fR and a new command,
called a \fIslave command\fR. The name of the slave command is the last
component of \fIpath\fR. The new slave interpreter and the slave command
are created in the interpreter identified by the path obtained by removing
-the last component from \fIpath\fR. For example, if \fIpath is \fBa b
+the last component from \fIpath\fR. For example, if \fIpath\fR is \fBa b
c\fR then a new slave interpreter and slave command named \fBc\fR are
created in the interpreter identified by the path \fBa b\fR.
The slave command may be used to manipulate the new interpreter as
@@ -152,6 +166,44 @@ given name already exists in this master.
The initial recursion limit of the slave interpreter is set to the
current recursion limit of its parent interpreter.
.TP
+\fBinterp\fR \fBdebug \fIpath\fR ?\fI\-frame\fR ?\fIbool\fR??
+.
+Controls whether frame-level stack information is captured in the
+slave interpreter identified by \fIpath\fR. If no arguments are
+given, option and current setting are returned. If \fI\-frame\fR
+is given, the debug setting is set to the given boolean if provided
+and the current setting is returned.
+This only effects the output of \fBinfo frame\fR, in that exact
+frame-level information for command invocation at the bytecode level
+is only captured with this setting on.
+.PP
+.RS
+For example, with code like
+.PP
+.CS
+\fBproc\fR mycontrol {... script} {
+ ...
+ \fBuplevel\fR 1 $script
+ ...
+}
+
+\fBproc\fR dosomething {...} {
+ ...
+ mycontrol {
+ somecode
+ }
+}
+.CE
+.PP
+the standard setting will provide a relative line number for the
+command \fBsomecode\fR and the relevant frame will be of type
+\fBeval\fR. With frame-debug active on the other hand the tracking
+extends so far that the system will be able to determine the file and
+absolute line number of this command, and return a frame of type
+\fBsource\fR. This more exact information is paid for with slower
+execution of all commands.
+.RE
+.TP
\fBinterp\fR \fBdelete \fR?\fIpath ...?\fR
Deletes zero or more interpreters given by the optional \fIpath\fR
arguments, and for each interpreter, it also deletes its slaves. The
@@ -163,9 +215,9 @@ exists, the command raises an error.
This command concatenates all of the \fIarg\fR arguments in the same
fashion as the \fBconcat\fR command, then evaluates the resulting string as
a Tcl script in the slave interpreter identified by \fIpath\fR. The result
-of this evaluation (including error information such as the \fBerrorInfo\fR
-and \fBerrorCode\fR variables, if an error occurs) is returned to the
-invoking interpreter.
+of this evaluation (including all \fBreturn\fR options,
+such as \fB\-errorinfo\fR and \fB\-errorcode\fR information, if an
+error occurs) is returned to the invoking interpreter.
Note that the script will be executed in the current context stack frame of the
\fIpath\fR interpreter; this is so that the implementations (in a master
interpreter) of aliases in a slave interpreter can execute scripts in
@@ -173,10 +225,9 @@ the slave that find out information about the slave's current state
and stack frame.
.TP
\fBinterp exists \fIpath\fR
-Returns \fB1\fR if a slave interpreter by the specified \fIpath\fR
+Returns \fB1\fR if a slave interpreter by the specified \fIpath\fR
exists in this master, \fB0\fR otherwise. If \fIpath\fR is omitted, the
invoking interpreter is used.
-.VS "" BR
.TP
\fBinterp expose \fIpath\fR \fIhiddenName\fR ?\fIexposedCmdName\fR?
Makes the hidden command \fIhiddenName\fR exposed, eventually bringing
@@ -191,11 +242,11 @@ Hidden commands are explained in more detail in \fBHIDDEN COMMANDS\fR, below.
\fBinterp\fR \fBhide\fR \fIpath\fR \fIexposedCmdName\fR ?\fIhiddenCmdName\fR?
Makes the exposed command \fIexposedCmdName\fR hidden, renaming
it to the hidden command \fIhiddenCmdName\fR, or keeping the same name if
-\fIhiddenCmdName\fR is not given, in the interpreter denoted
+\fIhiddenCmdName\fR is not given, in the interpreter denoted
by \fIpath\fR.
If a hidden command with the targeted name already exists, this command
fails.
-Currently both \fIexposedCmdName\fR and \fIhiddenCmdName\fR can
+Currently both \fIexposedCmdName\fR and \fIhiddenCmdName\fR can
not contain namespace qualifiers, or an error is raised.
Commands to be hidden by \fBinterp hide\fR are looked up in the global
namespace even if the current namespace is not the global one. This
@@ -207,21 +258,41 @@ Hidden commands are explained in more detail in \fBHIDDEN COMMANDS\fR, below.
Returns a list of the names of all hidden commands in the interpreter
identified by \fIpath\fR.
.TP
-\fBinterp\fR \fBinvokehidden\fR \fIpath\fR ?\fB-global\fR? \fIhiddenCmdName\fR ?\fIarg ...\fR?
+\fBinterp\fR \fBinvokehidden\fR \fIpath\fR ?\fI\-option ...\fR? \fIhiddenCmdName\fR ?\fIarg ...\fR?
Invokes the hidden command \fIhiddenCmdName\fR with the arguments supplied
in the interpreter denoted by \fIpath\fR. No substitutions or evaluation
-are applied to the arguments.
-If the \fB-global\fR flag is present, the hidden command is invoked at the
+are applied to the arguments. Three \fI\-option\fRs are supported, all
+of which start with \fB\-\fR: \fB\-namespace\fR (which takes a single
+argument afterwards, \fInsName\fR), \fB\-global\fR, and \fB\-\|\-\fR.
+If the \fB\-namespace\fR flag is present, the hidden command is invoked in
+the namespace called \fInsName\fR in the target interpreter.
+If the \fB\-global\fR flag is present, the hidden command is invoked at the
global level in the target interpreter; otherwise it is invoked at the
current call frame and can access local variables in that and outer call
frames.
+The \fB\-\|\-\fR flag allows the \fIhiddenCmdName\fR argument to start with a
+.QW \-
+character, and is otherwise unnecessary.
+If both the \fB\-namespace\fR and \fB\-global\fR flags are present, the
+\fB\-namespace\fR flag is ignored.
+Note that the hidden command will be executed (by default) in the
+current context stack frame of the \fIpath\fR interpreter.
Hidden commands are explained in more detail in \fBHIDDEN COMMANDS\fR, below.
-.VE
+.TP
+\fBinterp\fR \fBlimit\fR \fIpath\fR \fIlimitType\fR ?\fI\-option\fR? ?\fIvalue\fR \fI...\fR?
+.VS 8.5
+Sets up, manipulates and queries the configuration of the resource
+limit \fIlimitType\fR for the interpreter denoted by \fIpath\fR. If
+no \fI\-option\fR is specified, return the current configuration of the
+limit. If \fI\-option\fR is the sole argument, return the value of that
+option. Otherwise, a list of \fI\-option\fR/\fIvalue\fR argument pairs
+must supplied. See \fBRESOURCE LIMITS\fR below for a more detailed
+explanation of what limits and options are supported.
+.VE 8.5
.TP
\fBinterp issafe\fR ?\fIpath\fR?
Returns \fB1\fR if the interpreter identified by the specified \fIpath\fR
is safe, \fB0\fR otherwise.
-.VS "" BR
.TP
\fBinterp marktrusted\fR \fIpath\fR
Marks the interpreter identified by \fIpath\fR as trusted. Does
@@ -229,7 +300,6 @@ not expose the hidden commands. This command can only be invoked from a
trusted interpreter.
The command has no effect if the interpreter identified by \fIpath\fR is
already trusted.
-.VE
.TP
\fBinterp\fR \fBrecursionlimit\fR \fIpath\fR ?\fInewlimit\fR?
Returns the maximum allowable nesting depth for the interpreter
@@ -239,14 +309,16 @@ of more than \fInewlimit\fR calls to \fBTcl_Eval()\fR
and related procedures in that interpreter will return an error.
The \fInewlimit\fR value is also returned.
The \fInewlimit\fR value must be a positive integer between 1 and the
-maximum value of a non-long integer on the platform.
-.sp
+maximum value of a non-long integer on the platform.
+.RS
+.PP
The command sets the maximum size of the Tcl call stack only. It cannot
by itself prevent stack overflows on the C stack being used by the
application. If your machine has a limit on the size of the C stack, you
may get stack overflows before reaching the limit set by the command. If
this happens, see if there is a mechanism in your system for increasing
-the maximum size of the C stack.
+the maximum size of the C stack.
+.RE
.TP
\fBinterp\fR \fBshare\fR \fIsrcPath channelId destPath\fR
Causes the IO channel identified by \fIchannelId\fR to become shared
@@ -293,7 +365,7 @@ The valid forms of this command are:
\fIslave \fBaliases\fR
Returns a Tcl list whose elements are the tokens of all the
aliases in \fIslave\fR. The tokens correspond to the values returned when
-the aliases were created (which may not be the same
+the aliases were created (which may not be the same
as the current names of the commands).
.TP
\fIslave \fBalias \fIsrcToken\fR
@@ -320,19 +392,28 @@ The command returns a token that uniquely identifies the command created
\fIsrcCmd\fR, even if the command is renamed afterwards. The token may but
does not have to be equal to \fIsrcCmd\fR.
.TP
+\fIslave \fBbgerror\fR ?\fIcmdPrefix\fR?
+.VS 8.5
+This command either gets or sets the current background error handler
+for the \fIslave\fR interpreter. If \fIcmdPrefix\fR is
+absent, the current background error handler is returned, and if it is
+present, it is a list of words (of minimum length one) that describes
+what to set the interpreter's background error to. See the
+\fBBACKGROUND ERROR HANDLING\fR section for more details.
+.VE 8.5
+.TP
\fIslave \fBeval \fIarg \fR?\fIarg ..\fR?
This command concatenates all of the \fIarg\fR arguments in
the same fashion as the \fBconcat\fR command, then evaluates
the resulting string as a Tcl script in \fIslave\fR.
-The result of this evaluation (including error information
-such as the \fBerrorInfo\fR and \fBerrorCode\fR variables, if an
+The result of this evaluation (including all \fBreturn\fR options,
+such as \fB\-errorinfo\fR and \fB\-errorcode\fR information, if an
error occurs) is returned to the invoking interpreter.
Note that the script will be executed in the current context stack frame
of \fIslave\fR; this is so that the implementations (in a master
interpreter) of aliases in a slave interpreter can execute scripts in
the slave that find out information about the slave's current state
and stack frame.
-.VS "" BR
.TP
\fIslave \fBexpose \fIhiddenName \fR?\fIexposedCmdName\fR?
This command exposes the hidden command \fIhiddenName\fR, eventually bringing
@@ -344,12 +425,12 @@ fails.
For more details on hidden commands, see \fBHIDDEN COMMANDS\fR, below.
.TP
\fIslave \fBhide \fIexposedCmdName\fR ?\fIhiddenCmdName\fR?
-This command hides the exposed command \fIexposedCmdName\fR, renaming it to
+This command hides the exposed command \fIexposedCmdName\fR, renaming it to
the hidden command \fIhiddenCmdName\fR, or keeping the same name if the
argument is not given, in the \fIslave\fR interpreter.
If a hidden command with the targeted name already exists, this command
fails.
-Currently both \fIexposedCmdName\fR and \fIhiddenCmdName\fR can
+Currently both \fIexposedCmdName\fR and \fIhiddenCmdName\fR can
not contain namespace qualifiers, or an error is raised.
Commands to be hidden are looked up in the global
namespace even if the current namespace is not the global one. This
@@ -360,27 +441,46 @@ For more details on hidden commands, see \fBHIDDEN COMMANDS\fR, below.
\fIslave \fBhidden\fR
Returns a list of the names of all hidden commands in \fIslave\fR.
.TP
-\fIslave \fBinvokehidden\fR ?\fB-global\fR \fIhiddenName \fR?\fIarg ..\fR?
+\fIslave \fBinvokehidden\fR ?\fI\-option ...\fR? \fIhiddenName \fR?\fIarg ..\fR?
This command invokes the hidden command \fIhiddenName\fR with the
supplied arguments, in \fIslave\fR. No substitutions or evaluations are
-applied to the arguments.
-If the \fB-global\fR flag is given, the command is invoked at the global
+applied to the arguments. Three \fI\-option\fRs are supported, all
+of which start with \fB\-\fR: \fB\-namespace\fR (which takes a single
+argument afterwards, \fInsName\fR), \fB\-global\fR, and \fB\-\|\-\fR.
+If the \fB\-namespace\fR flag is given, the hidden command is invoked in
+the specified namespace in the slave.
+If the \fB\-global\fR flag is given, the command is invoked at the global
level in the slave; otherwise it is invoked at the current call frame and
can access local variables in that or outer call frames.
+The \fB\-\|\-\fR flag allows the \fIhiddenCmdName\fR argument to start with a
+.QW \-
+character, and is otherwise unnecessary.
+If both the \fB\-namespace\fR and \fB\-global\fR flags are given, the
+\fB\-namespace\fR flag is ignored.
+Note that the hidden command will be executed (by default) in the
+current context stack frame of \fIslave\fR.
For more details on hidden commands,
see \fBHIDDEN COMMANDS\fR, below.
-.VE
.TP
\fIslave \fBissafe\fR
Returns \fB1\fR if the slave interpreter is safe, \fB0\fR otherwise.
-.VS "" BR
+.TP
+\fIslave \fBlimit\fR \fIlimitType\fR ?\fI\-option\fR? ?\fIvalue\fR \fI...\fR?
+.VS 8.5
+Sets up, manipulates and queries the configuration of the resource
+limit \fIlimitType\fR for the slave interpreter. If no \fI\-option\fR
+is specified, return the current configuration of the limit. If
+\fI\-option\fR is the sole argument, return the value of that option.
+Otherwise, a list of \fI\-option\fR/\fIvalue\fR argument pairs must
+supplied. See \fBRESOURCE LIMITS\fR below for a more detailed explanation of
+what limits and options are supported.
+.VE 8.5
.TP
\fIslave \fBmarktrusted\fR
Marks the slave interpreter as trusted. Can only be invoked by a
trusted interpreter. This command does not expose any hidden
commands in the slave interpreter. The command has no effect if the slave
is already trusted.
-.VE
.TP
\fIslave\fR \fBrecursionlimit\fR ?\fInewlimit\fR?
Returns the maximum allowable nesting depth for the \fIslave\fR interpreter.
@@ -389,14 +489,16 @@ set so that nesting of more than \fInewlimit\fR calls to \fBTcl_Eval()\fR
and related procedures in \fIslave\fR will return an error.
The \fInewlimit\fR value is also returned.
The \fInewlimit\fR value must be a positive integer between 1 and the
-maximum value of a non-long integer on the platform.
-.sp
+maximum value of a non-long integer on the platform.
+.RS
+.PP
The command sets the maximum size of the Tcl call stack only. It cannot
by itself prevent stack overflows on the C stack being used by the
application. If your machine has a limit on the size of the C stack, you
may get stack overflows before reaching the limit set by the command. If
this happens, see if there is a mechanism in your system for increasing
-the maximum size of the C stack.
+the maximum size of the C stack.
+.RE
.SH "SAFE INTERPRETERS"
.PP
A safe interpreter is one with restricted functionality, so that
@@ -422,32 +524,33 @@ 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 binary
-break case catch clock
-close concat continue eof
-error eval expr fblocked
-fcopy fileevent flush for
-foreach format gets global
-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
-time trace unset update
-uplevel upvar variable vwait
-while\fR
+\fBafter\fR \fBappend\fR \fBapply\fR \fBarray\fR
+\fBbinary\fR \fBbreak\fR \fBcatch\fR \fBchan\fR
+\fBclock\fR \fBclose\fR \fBconcat\fR \fBcontinue\fR
+\fBdict\fR \fBeof\fR \fBerror\fR \fBeval\fR
+\fBexpr\fR \fBfblocked\fR \fBfcopy\fR \fBfileevent\fR
+\fBflush\fR \fBfor\fR \fBforeach\fR \fBformat\fR
+\fBgets\fR \fBglobal\fR \fBif\fR \fBincr\fR
+\fBinfo\fR \fBinterp\fR \fBjoin\fR \fBlappend\fR
+\fBlassign\fR \fBlindex\fR \fBlinsert\fR \fBlist\fR
+\fBllength\fR \fBlrange\fR \fBlrepeat\fR \fBlreplace\fR
+\fBlsearch\fR \fBlset\fR \fBlsort\fR \fBnamespace\fR
+\fBpackage\fR \fBpid\fR \fBproc\fR \fBputs\fR
+\fBread\fR \fBregexp\fR \fBregsub\fR \fBrename\fR
+\fBreturn\fR \fBscan\fR \fBseek\fR \fBset\fR
+\fBsplit\fR \fBstring\fR \fBsubst\fR \fBswitch\fR
+\fBtell\fR \fBtime\fR \fBtrace\fR \fBunset\fR
+\fBupdate\fR \fBuplevel\fR \fBupvar\fR \fBvariable\fR
+\fBvwait\fR \fBwhile\fR
.DE
-.VS "" BR
The following commands are hidden by \fBinterp create\fR when it
creates a safe interpreter:
.DS
.ta 1.2i 2.4i 3.6i
-\fBcd encoding exec exit
-fconfigure file glob load
-open pwd socket source\fR
+\fBcd\fR \fBencoding\fR \fBexec\fR \fBexit\fR
+\fBfconfigure\fR \fBfile\fR \fBglob\fR \fBload\fR
+\fBopen\fR \fBpwd\fR \fBsocket\fR \fBsource\fR
+\fBunload\fR
.DE
These commands can be recreated later as Tcl procedures or aliases, or
re-exposed by \fBinterp expose\fR.
@@ -456,25 +559,24 @@ The following commands from Tcl's library of support procedures are
not present in a safe interpreter:
.DS
.ta 1.6i 3.2i
-\fBauto_exec_ok auto_import auto_load
-auto_load_index auto_qualify unknown\fR
+\fBauto_exec_ok\fR \fBauto_import\fR \fBauto_load\fR
+\fBauto_load_index\fR \fBauto_qualify\fR \fBunknown\fR
.DE
Note in particular that safe interpreters have no default \fBunknown\fR
-command, so Tcl's default autoloading facilities are not available.
+command, so Tcl's default autoloading facilities are not available.
Autoload access to Tcl's commands that are normally autoloaded:
.DS
.ta 2.1i
-\fB
-auto_mkindex auto_mkindex_old
-auto_reset history
-parray pkg_mkIndex
-::pkg::create ::safe::interpAddToAccessPath
-::safe::interpCreate ::safe::interpConfigure
-::safe::interpDelete ::safe::interpFindInAccessPath
-::safe::interpInit ::safe::setLogCmd
-tcl_endOfWord tcl_findLibrary
-tcl_startOfNextWord tcl_startOfPreviousWord
-tcl_wordBreakAfter tcl_wordBreakBefore\fR
+\fBauto_mkindex\fR \fBauto_mkindex_old\fR
+\fBauto_reset\fR \fBhistory\fR
+\fBparray\fR \fBpkg_mkIndex\fR
+\fB::pkg::create\fR \fB::safe::interpAddToAccessPath\fR
+\fB::safe::interpCreate\fR \fB::safe::interpConfigure\fR
+\fB::safe::interpDelete\fR \fB::safe::interpFindInAccessPath\fR
+\fB::safe::interpInit\fR \fB::safe::setLogCmd\fR
+\fBtcl_endOfWord\fR \fBtcl_findLibrary\fR
+\fBtcl_startOfNextWord\fR \fBtcl_startOfPreviousWord\fR
+\fBtcl_wordBreakAfter\fR \fBtcl_wordBreakBefore\fR
.DE
can only be provided by explicit definition of an \fBunknown\fR command
in the safe interpreter. This will involve exposing the \fBsource\fR
@@ -482,7 +584,6 @@ command. This is most easily accomplished by creating the safe interpreter
with Tcl's \fBSafe\-Tcl\fR mechanism. \fBSafe\-Tcl\fR provides safe
versions of \fBsource\fR, \fBload\fR, and other Tcl commands needed
to support autoloading of commands and the loading of packages.
-.VE
.PP
In addition, the \fBenv\fR variable is not present in a safe interpreter,
so it cannot share environment variables with other interpreters. The
@@ -518,9 +619,10 @@ as they would be for any other command invoked in that interpreter.
The command procedure for the source command takes its arguments
and merges them with the \fItargetCmd\fR and \fIarg\fRs for the
alias to create a new array of arguments. If the words
-of \fIsrcCmd\fR were ``\fIsrcCmd arg1 arg2 ... argN\fR'',
+of \fIsrcCmd\fR were
+.QW "\fIsrcCmd arg1 arg2 ... argN\fR" ,
the new set of words will be
-``\fItargetCmd arg arg ... arg arg1 arg2 ... argN\fR'',
+.QW "\fItargetCmd arg arg ... arg arg1 arg2 ... argN\fR" ,
where \fItargetCmd\fR and \fIarg\fRs are the values supplied when the
alias was created. \fITargetCmd\fR is then used to locate a command
procedure in the target interpreter, and that command procedure
@@ -540,7 +642,6 @@ evaluated or substituted, since this would provide an escape
mechanism whereby the slave interpreter could execute arbitrary
code in the master. This in turn would compromise the security
of the system.
-.VS
.SH "HIDDEN COMMANDS"
.PP
Safe interpreters greatly restrict the functionality available to Tcl
@@ -608,10 +709,108 @@ Commands to be hidden by \fBinterp hide\fR are looked up in the global
namespace even if the current namespace is not the global one. This
prevents slaves from fooling a master interpreter into hiding the wrong
command, by making the current namespace be different from the global one.
-.VE
-.SH CREDITS
+.SH "RESOURCE LIMITS"
+.VS 8.5
.PP
-This mechanism is based on the Safe-Tcl prototype implemented
+Every interpreter has two kinds of resource limits that may be imposed by any
+master interpreter upon its slaves. Command limits (of type \fBcommand\fR)
+restrict the total number of Tcl commands that may be executed by an
+interpreter (as can be inspected via the \fBinfo cmdcount\fR command), and
+time limits (of type \fBtime\fR) place a limit by which execution within the
+interpreter must complete. Note that time limits are expressed as
+\fIabsolute\fR times (as in \fBclock seconds\fR) and not relative times (as in
+\fBafter\fR) because they may be modified after creation.
+.PP
+When a limit is exceeded for an interpreter, first any handler callbacks
+defined by master interpreters are called. If those callbacks increase or
+remove the limit, execution within the (previously) limited interpreter
+continues. If the limit is still in force, an error is generated at that point
+and normal processing of errors within the interpreter (by the \fBcatch\fR
+command) is disabled, so the error propagates outwards (building a stack-trace
+as it goes) to the point where the limited interpreter was invoked (e.g. by
+\fBinterp eval\fR) where it becomes the responsibility of the calling code to
+catch and handle.
+.SS "LIMIT OPTIONS"
+.PP
+Every limit has a number of options associated with it, some of which are
+common across all kinds of limits, and others of which are particular to the
+kind of limit.
+.VE 8.5
+.TP
+\fB\-command\fR
+.VS 8.5
+This option (common for all limit types) specifies (if non-empty) a Tcl script
+to be executed in the global namespace of the interpreter reading and writing
+the option when the particular limit in the limited interpreter is exceeded.
+The callback may modify the limit on the interpreter if it wishes the limited
+interpreter to continue executing. If the callback generates an error, it is
+reported through the background error mechanism (see \fBBACKGROUND ERROR
+HANDLING\fR). Note that the callbacks defined by one interpreter are
+completely isolated from the callbacks defined by another, and that the order
+in which those callbacks are called is undefined.
+.VE 8.5
+.TP
+\fB\-granularity\fR
+.VS 8.5
+This option (common for all limit types) specifies how frequently (out of the
+points when the Tcl interpreter is in a consistent state where limit checking
+is possible) that the limit is actually checked. This allows the tuning of how
+frequently a limit is checked, and hence how often the limit-checking overhead
+(which may be substantial in the case of time limits) is incurred.
+.VE 8.5
+.TP
+\fB\-milliseconds\fR
+.VS 8.5
+This option specifies the number of milliseconds after the moment defined in
+the \fB\-seconds\fR option that the time limit will fire. It should only ever
+be specified in conjunction with the \fB\-seconds\fR option (whether it was
+set previously or is being set this invocation.)
+.VE 8.5
+.TP
+\fB\-seconds\fR
+.VS 8.5
+This option specifies the number of seconds after the epoch (see \fBclock
+seconds\fR) that the time limit for the interpreter will be triggered. The
+limit will be triggered at the start of the second unless specified at a
+sub-second level using the \fB\-milliseconds\fR option. This option may be the
+empty string, which indicates that a time limit is not set for the
+interpreter.
+.VE 8.5
+.TP
+\fB\-value\fR
+.VS 8.5
+This option specifies the number of commands that the interpreter may execute
+before triggering the command limit. This option may be the empty string,
+which indicates that a command limit is not set for the interpreter.
+.PP
+Where an interpreter with a resource limit set on it creates a slave
+interpreter, that slave interpreter will have resource limits imposed on it
+that are at least as restrictive as the limits on the creating master
+interpreter. If the master interpreter of the limited master wishes to relax
+these conditions, it should hide the \fBinterp\fR command in the child and
+then use aliases and the \fBinterp invokehidden\fR subcommand to provide such
+access as it chooses to the \fBinterp\fR command to the limited master as
+necessary.
+.SH "BACKGROUND ERROR HANDLING"
+.PP
+When an error happens in a situation where it cannot be reported directly up
+the stack (e.g. when processing events in an \fBupdate\fR or \fBvwait\fR call)
+the error is instead reported through the background error handling mechanism.
+Every interpreter has a background error handler registered; the default error
+handler arranges for the \fBbgerror\fR command in the interpreter's global
+namespace to be called, but other error handlers may be installed and process
+background errors in substantially different ways.
+.PP
+A background error handler consists of a non-empty list of words to which will
+be appended two further words at invocation time. The first word will be the
+error message string, and the second will a dictionary of return options (this
+is also the sort of information that can be obtained by trapping a normal
+error using \fBcatch\fR of course.) The resulting list will then be executed
+in the interpreter's global namespace without further substitutions being
+performed.
+.VE 8.5
+.SH CREDITS
+The safe interpreter mechanism is based on the Safe-Tcl prototype implemented
by Nathaniel Borenstein and Marshall Rose.
.SH EXAMPLES
Creating and using an alias for a command in the current interpreter:
@@ -621,22 +820,33 @@ set idx [getIndex delta]
.CE
.PP
Executing an arbitrary command in a safe interpreter where every
-invokation of \fBlappend\fR is logged:
+invocation of \fBlappend\fR is logged:
.CS
set i [\fBinterp create\fR -safe]
\fBinterp hide\fR $i lappend
\fBinterp alias\fR $i lappend {} loggedLappend $i
proc loggedLappend {i args} {
- puts "logged invokation of lappend $args"
- # Be extremely careful about command construction
- eval [linsert $args 0 \\
- \fBinterp invokehidden\fR $i lappend]
+ puts "logged invocation of lappend $args"
+ \fBinterp invokehidden\fR $i lappend {*}$args
}
\fBinterp eval\fR $i $someUntrustedScript
.CE
-
+.PP
+.VS 8.5
+Setting a resource limit on an interpreter so that an infinite loop
+terminates.
+.CS
+set i [\fBinterp create\fR]
+\fBinterp limit\fR $i command -value 1000
+\fBinterp eval\fR $i {
+ set x 0
+ while {1} {
+ puts "Counting up... [incr x]"
+ }
+}
+.CE
+.VE 8.5
.SH "SEE ALSO"
-load(n), safe(n), Tcl_CreateSlave(3)
-
+bgerror(n), load(n), safe(n), Tcl_CreateSlave(3)
.SH KEYWORDS
alias, master interpreter, safe interpreter, slave interpreter
diff --git a/doc/join.n b/doc/join.n
index f28c07c..582b730 100644
--- a/doc/join.n
+++ b/doc/join.n
@@ -27,14 +27,14 @@ Making a comma-separated list:
.CS
set data {1 2 3 4 5}
\fBjoin\fR $data ", "
- \fB=> 1, 2, 3, 4, 5\fR
+ \fB\(-> 1, 2, 3, 4, 5\fR
.CE
.PP
Using \fBjoin\fR to flatten a list by a single level:
.CS
set data {1 {2 3} 4 {5 {6 7} 8}}
\fBjoin\fR $data
- \fB=> 1 2 3 4 5 {6 7} 8\fR
+ \fB\(-> 1 2 3 4 5 {6 7} 8\fR
.CE
.SH "SEE ALSO"
diff --git a/doc/lappend.n b/doc/lappend.n
index cb5d7fa..dbed3bb 100644
--- a/doc/lappend.n
+++ b/doc/lappend.n
@@ -1,7 +1,7 @@
'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\" Copyright (c) 2001 Kevin B. Kenny. All rights reserved.
+'\" Copyright (c) 2001 Kevin B. Kenny <kennykb@acm.org>. All rights reserved.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
@@ -21,14 +21,16 @@ lappend \- Append list elements onto a variable
This command treats the variable given by \fIvarName\fR as a list
and appends each of the \fIvalue\fR arguments to that list as a separate
element, with spaces between elements.
-If \fIvarName\fR doesn't exist, it is created as a list with elements
+If \fIvarName\fR does not exist, it is created as a list with elements
given by the \fIvalue\fR arguments.
\fBLappend\fR is similar to \fBappend\fR except that the \fIvalue\fRs
are appended as list elements rather than raw text.
This command provides a relatively efficient way to build up
-large lists. For example, ``\fBlappend a $b\fR'' is much
-more efficient than ``\fBset a [concat $a [list $b]]\fR'' when
-\fB$a\fR is long.
+large lists. For example,
+.QW "\fBlappend a $b\fR"
+is much more efficient than
+.QW "\fBset a [concat $a [list $b]]\fR"
+when \fB$a\fR is long.
.SH EXAMPLE
Using \fBlappend\fR to build up a list of numbers.
.CS
@@ -41,10 +43,7 @@ Using \fBlappend\fR to build up a list of numbers.
.CE
.SH "SEE ALSO"
-list(n), lindex(n), linsert(n), llength(n),
-.VS 8.4
-lset(n)
-.VE
+list(n), lindex(n), linsert(n), llength(n), lset(n),
lsort(n), lrange(n)
.SH KEYWORDS
diff --git a/doc/lassign.n b/doc/lassign.n
new file mode 100644
index 0000000..b791feb
--- /dev/null
+++ b/doc/lassign.n
@@ -0,0 +1,55 @@
+'\"
+'\" Copyright (c) 1992-1999 Karl Lehenbauer & Mark Diekhans
+'\" Copyright (c) 2004 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.so man.macros
+.TH lassign n 8.5 Tcl "Tcl Built-In Commands"
+.BS
+'\" Note: do not modify the .SH NAME line immediately below!
+.SH NAME
+lassign \- Assign list elements to variables
+.SH SYNOPSIS
+\fBlassign \fIlist varName \fR?\fIvarName ...\fR?
+.BE
+
+.SH DESCRIPTION
+.PP
+This command treats the value \fIlist\fR as a list and assigns
+successive elements from that list to the variables given by the
+\fIvarName\fR arguments in order. If there are more variable names
+than list elements, the remaining variables are set to the empty
+string. If there are more list elements than variables, a list of
+unassigned elements is returned.
+.SH EXAMPLES
+An illustration of how multiple assignment works, and what happens
+when there are either too few or too many elements.
+.CS
+lassign {a b c} x y z ;# Empty return
+puts $x ;# Prints "a"
+puts $y ;# Prints "b"
+puts $z ;# Prints "c"
+
+lassign {d e} x y z ;# Empty return
+puts $x ;# Prints "d"
+puts $y ;# Prints "e"
+puts $z ;# Prints ""
+
+lassign {f g h i} x y ;# Returns "h i"
+puts $x ;# Prints "f"
+puts $y ;# Prints "g"
+.CE
+The \fBlassign\fR command has other uses. It can be used to create
+the analogue of the
+.QW shift
+command in many shell languages like this:
+.CS
+set ::argv [lassign $::argv argumentToReadOff]
+.CE
+.SH "SEE ALSO"
+lindex(n), list(n), lset(n), set(n)
+
+.SH KEYWORDS
+assign, element, list, multiple, set, variable
diff --git a/doc/library.n b/doc/library.n
index 67b1037..f29af8b 100644
--- a/doc/library.n
+++ b/doc/library.n
@@ -21,15 +21,12 @@ auto_execok, auto_import, auto_load, auto_mkindex, auto_mkindex_old, auto_qualif
\fBauto_reset\fR
\fBtcl_findLibrary \fIbasename version patch initScript enVarName varName\fR
\fBparray \fIarrayName\fR
-.VS
\fBtcl_endOfWord \fIstr start\fR
\fBtcl_startOfNextWord \fIstr start\fR
\fBtcl_startOfPreviousWord \fIstr start\fR
\fBtcl_wordBreakAfter \fIstr start\fR
\fBtcl_wordBreakBefore \fIstr start\fR
-.VE
.BE
-
.SH INTRODUCTION
.PP
Tcl includes a library of Tcl procedures for commonly-needed functions.
@@ -55,7 +52,6 @@ If the library procedure \fBTcl_Init\fR is invoked from an application's
The code in \fBinit.tcl\fR will define the \fBunknown\fR procedure
and arrange for the other procedures to be loaded on-demand using
the auto-load mechanism defined below.
-
.SH "COMMAND PROCEDURES"
.PP
The following procedures are provided in the Tcl library:
@@ -68,7 +64,7 @@ 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
+directories and file extensions as used by \fBexec\fR. \fBAuto_execok\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
@@ -98,7 +94,7 @@ 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
+entry for \fIcmd\fR or if the script did not 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
@@ -136,9 +132,11 @@ unsophisticated way: if any line contains the word \fBproc\fR
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
+Procedure definitions that do not appear in this way (e.g. they
have spaces before the \fBproc\fR) will not be indexed. If your
-script contains "dangerous" code, such as global initialization
+script contains
+.QW 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
@@ -148,7 +146,7 @@ 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.
+loaded the next time that they are used.
.TP
\fBauto_qualify \fIcommand namespace\fR
Computes a list of fully qualified names for \fIcommand\fR. This list
@@ -174,18 +172,20 @@ This is a standard search procedure for use by extensions during
their initialization. They call this procedure to look for their
script library in several standard directories.
The last component of the name of the library directory is
-normally \fIbasenameversion\fP
-(e.g., tk8.0), but it might be "library" when in the build hierarchies.
+normally \fIbasenameversion\fR
+(e.g., tk8.0), but it might be
+.QW library
+when in the build hierarchies.
The \fIinitScript\fR file will be sourced into the interpreter
once it is found. The directory in which this file is found is
-stored into the global variable \fIvarName\fP.
+stored into the global variable \fIvarName\fR.
If this variable is already defined (e.g., by C code during
application initialization) then no searching is done.
Otherwise the search looks in these directories:
-the directory named by the environment variable \fIenVarName\fP;
+the directory named by the environment variable \fIenVarName\fR;
relative to the Tcl library directory;
relative to the executable file in the standard installation
-bin or bin/\fIarch\fP directory;
+bin or bin/\fIarch\fR directory;
relative to the executable file in the current build tree;
relative to the executable file in a parallel build tree.
.TP
@@ -196,7 +196,6 @@ in the array \fIarrayName\fR.
It may be either local or global.
.TP
\fBtcl_endOfWord \fIstr start\fR
-.VS
Returns the index of the first end-of-word location that occurs after
a starting index \fIstart\fR in the string \fIstr\fR. An end-of-word
location is defined to be the first non-word character following the
@@ -232,8 +231,6 @@ Returns the index of the first word boundary before the starting index
boundaries before the starting point in the given string. The index
returned refers to the second character of the pair that comprises a
boundary.
-.VE
-
.SH "VARIABLES"
.PP
The following global variables are defined or used by the procedures in
@@ -268,17 +265,18 @@ the directories listed in the $tcl_pkgPath variable.
If set, then it specifies the location of the directory containing
library scripts (the value of this variable will be
assigned to the \fBtcl_library\fR variable and therefore returned by
-the command \fBinfo library\fR). If this variable isn't set then
+the command \fBinfo library\fR). If this variable is not set then
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. Directories must be specified in
-Tcl format, using "/" as the path separator, regardless of platform.
+Tcl format, using
+.QW /
+as the path separator, regardless of platform.
This variable is only used when initializing the \fBauto_path\fR variable.
.TP
\fBtcl_nonwordchars\fR
-.VS
This variable contains a regular expression that is used by routines
like \fBtcl_endOfWord\fR to identify whether a character is part of a
word or not. If the pattern matches a character, the character is
@@ -294,17 +292,7 @@ word or not. If the pattern matches a character, the character is
considered to be a word character. On Windows platforms, words are
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_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"
info(n), re_syntax(n)
-
.SH KEYWORDS
auto-exec, auto-load, library, unknown, word, whitespace
diff --git a/doc/lindex.n b/doc/lindex.n
index a12fdcf..f0417ac 100644
--- a/doc/lindex.n
+++ b/doc/lindex.n
@@ -1,7 +1,7 @@
'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\" Copyright (c) 2001 by Kevin B. Kenny. All rights reserved.
+'\" Copyright (c) 2001 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
@@ -17,9 +17,8 @@ lindex \- Retrieve an element from a list
.BE
.SH DESCRIPTION
.PP
-.VS 8.4
-The \fBlindex\fP command accepts a parameter, \fIlist\fP, which
-it treats as a Tcl list. It also accepts zero or more \fIindices\fP into
+The \fBlindex\fR command accepts a parameter, \fIlist\fR, which
+it treats as a Tcl list. It also accepts zero or more \fIindices\fR into
the list. The indices may be presented either consecutively on the
command line, or grouped in a
Tcl list and presented as a single argument.
@@ -37,7 +36,6 @@ In this case, the return value of \fBlindex\fR is simply the value of the
.PP
When presented with a single index, the \fBlindex\fR command
treats \fIlist\fR as a Tcl list and returns the
-.VE
\fIindex\fR'th element from it (0 refers to the first element of the list).
In extracting the element, \fBlindex\fR observes the same rules
concerning braces and quotes and backslashes as the Tcl command
@@ -46,11 +44,12 @@ substitution and command substitution do not occur.
If \fIindex\fR is negative or greater than or equal to the number
of elements in \fIvalue\fR, then an empty
string is returned.
-If \fIindex\fR has the value \fBend\fR, it refers to the last element
-in the list, and \fBend\-\fIinteger\fR refers to the last element in
-the list minus the specified integer offset.
+.VS 8.5
+The interpretation of each simple \fIindex\fR value is the same as
+for the command \fBstring index\fR, supporting simple index
+arithmetic and indices relative to the end of the list.
+.VE 8.5
.PP
-.VS 8.4
If additional \fIindex\fR arguments are supplied, then each argument is
used in turn to select an element from the previous indexing operation,
allowing the script to select elements from sublists. The command,
@@ -67,25 +66,33 @@ lindex [lindex [lindex $a 1] 2] 3
.CE
.SH EXAMPLES
.CS
-\fBlindex\fR {a b c} \fI=> a b c\fR
-\fBlindex\fR {a b c} {} \fI=> a b c\fR
-\fBlindex\fR {a b c} 0 \fI=> a\fR
-\fBlindex\fR {a b c} 2 \fI=> c\fR
-\fBlindex\fR {a b c} end \fI=> c\fR
-\fBlindex\fR {a b c} end-1 \fI=> b\fR
-\fBlindex\fR {{a b c} {d e f} {g h i}} 2 1 \fI=> h\fR
-\fBlindex\fR {{a b c} {d e f} {g h i}} {2 1} \fI=> h\fR
-\fBlindex\fR {{{a b} {c d}} {{e f} {g h}}} 1 1 0 \fI=> g\fR
-\fBlindex\fR {{{a b} {c d}} {{e f} {g h}}} {1 1 0} \fI=> g\fR
+\fBlindex\fR {a b c}
+ \fI\(-> a b c\fR
+\fBlindex\fR {a b c} {}
+ \fI\(-> a b c\fR
+\fBlindex\fR {a b c} 0
+ \fI\(-> a\fR
+\fBlindex\fR {a b c} 2
+ \fI\(-> c\fR
+\fBlindex\fR {a b c} end
+ \fI\(-> c\fR
+\fBlindex\fR {a b c} end-1
+ \fI\(-> b\fR
+\fBlindex\fR {{a b c} {d e f} {g h i}} 2 1
+ \fI\(-> h\fR
+\fBlindex\fR {{a b c} {d e f} {g h i}} {2 1}
+ \fI\(-> h\fR
+\fBlindex\fR {{{a b} {c d}} {{e f} {g h}}} 1 1 0
+ \fI\(-> g\fR
+\fBlindex\fR {{{a b} {c d}} {{e f} {g h}}} {1 1 0}
+ \fI\(-> g\fR
.CE
-.VE
.SH "SEE ALSO"
list(n), lappend(n), linsert(n), llength(n), lsearch(n),
-.VS 8.4
-lset(n),
+lset(n), lsort(n), lrange(n), lreplace(n),
+.VS 8.5
+string(n)
.VE
-lsort(n),
-lrange(n), lreplace(n)
.SH KEYWORDS
element, index, list
diff --git a/doc/linsert.n b/doc/linsert.n
index 7b85adb..9f37fcd 100644
--- a/doc/linsert.n
+++ b/doc/linsert.n
@@ -1,7 +1,7 @@
'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\" Copyright (c) 2001 Kevin B. Kenny. All rights reserved.
+'\" Copyright (c) 2001 Kevin B. Kenny <kennykb@acm.org>. All rights reserved.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
@@ -22,11 +22,12 @@ This command produces a new list from \fIlist\fR by inserting all of the
\fIelement\fR arguments just before the \fIindex\fR'th 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.
+elements are inserted at the beginning of the list.
+.VS 8.5
+The interpretation of the \fIindex\fR value is the same as
+for the command \fBstring index\fR, supporting simple index
+arithmetic and indices relative to the end of the list.
+.VE
.SH EXAMPLE
Putting some values into a list, first indexing from the start and
then indexing from the end, and then chaining them together:
@@ -39,9 +40,10 @@ set newerList [\fBlinsert\fR [\fBlinsert\fR $oldList end-1 quick] 1 lazy]
.CE
.SH "SEE ALSO"
-.VS 8.4
list(n), lappend(n), lindex(n), llength(n), lsearch(n),
-lset(n), lsort(n), lrange(n), lreplace(n)
+lset(n), lsort(n), lrange(n), lreplace(n),
+.VS 8.5
+string(n)
.VE
.SH KEYWORDS
diff --git a/doc/list.n b/doc/list.n
index 21f9edb..2bcdafb 100644
--- a/doc/list.n
+++ b/doc/list.n
@@ -1,7 +1,7 @@
'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\" Copyright (c) 2001 Kevin B. Kenny. All rights reserved.
+'\" Copyright (c) 2001 Kevin B. Kenny <kennykb@acm.org>. All rights reserved.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
@@ -43,11 +43,10 @@ while \fBconcat\fR with the same arguments will return
.SH "SEE ALSO"
lappend(n), lindex(n), linsert(n), llength(n), lrange(n),
-lreplace(n), lsearch(n),
-.VS 8.4
-lset(n),
-.VE 8.4
-lsort(n)
+.VS 8.5
+lrepeat(n),
+.VE 8.5
+lreplace(n), lsearch(n), lset(n), lsort(n)
.SH KEYWORDS
element, list
diff --git a/doc/llength.n b/doc/llength.n
index 977d9ef..627800f 100644
--- a/doc/llength.n
+++ b/doc/llength.n
@@ -1,7 +1,7 @@
'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\" Copyright (c) 2001 Kevin B. Kenny. All rights reserved.
+'\" Copyright (c) 2001 Kevin B. Kenny <kennykb@acm.org>. All rights reserved.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
@@ -48,10 +48,8 @@ An empty list is not necessarily an empty string:
.CE
.SH "SEE ALSO"
-.VS 8.4
list(n), lappend(n), lindex(n), linsert(n), lsearch(n),
lset(n), lsort(n), lrange(n), lreplace(n)
-.VE
.SH KEYWORDS
element, list, length
diff --git a/doc/load.n b/doc/load.n
index 02fec35..e5501f6 100644
--- a/doc/load.n
+++ b/doc/load.n
@@ -9,7 +9,7 @@
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
-load \- Load machine code and initialize new commands.
+load \- Load machine code and initialize new commands
.SH SYNOPSIS
\fBload \fIfileName\fR
.br
@@ -71,7 +71,12 @@ in an application. If a given \fIfileName\fR is loaded into multiple
interpreters, then the first \fBload\fR will load the code and
call the initialization procedure; subsequent \fBload\fRs will
call the initialization procedure without loading the code again.
-It is not possible to unload or reload a package.
+.VS 8.5
+For Tcl versions lower than 8.5, it is not possible to unload or reload a
+package. From version 8.5 however, the \fBunload\fR command allows the unloading
+of libraries loaded with \fBload\fR, for libraries that are aware of the
+Tcl's unloading mechanism.
+.VE 8.5
.PP
The \fBload\fR command also supports packages that are statically
linked with the application, if those packages have been registered
@@ -85,13 +90,10 @@ This may be done differently on different platforms.
The default guess, which is used on most UNIX platforms, is to
take the last element of \fIfileName\fR, strip off the first
three characters if they are \fBlib\fR, and use any following
-.VS
alphabetic and underline characters as the module name.
-.VE
For example, the command \fBload libxyz4.2.so\fR uses the module
name \fBxyz\fR and the command \fBload bin/last.so {}\fR uses the
module name \fBlast\fR.
-.VS "" br
.PP
If \fIfileName\fR is an empty string, then \fIpackageName\fR must
be specified.
@@ -102,17 +104,20 @@ Otherwise, the \fBload\fR command searches for a dynamically loaded
package by that name, and uses it if it is found. If several
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
+When a load fails with
+.QW "library not found"
+error, it is also possible
that a dependent library was not found. To see the dependent libraries,
-type ``dumpbin -imports <dllname>'' 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.
+type
+.QW "dumpbin -imports <dllname>"
+in a DOS console to see what the library must import.
+When loading a DLL in the current directory, Windows will ignore
+.QW ./
+as a path specifier and use a search heuristic to find the DLL instead.
To avoid this, load the DLL with:
.CS
\fBload\fR [file join [pwd] mylib.DLL]
@@ -131,7 +136,7 @@ The following is a minimal extension:
#include <stdio.h>
static int fooCmd(ClientData clientData,
Tcl_Interp *interp, int objc, Tcl_Obj *const objv[]) {
- printf("called with %d arguments\\n", objc);
+ printf("called with %d arguments\en", objc);
return TCL_OK;
}
int Foo_Init(Tcl_Interp *interp) {
diff --git a/doc/lrange.n b/doc/lrange.n