summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authordkf <donal.k.fellows@manchester.ac.uk>2016-01-01 17:46:45 (GMT)
committerdkf <donal.k.fellows@manchester.ac.uk>2016-01-01 17:46:45 (GMT)
commit97e52f918d3e35ec3f61e099424ccf966aae3101 (patch)
tree9d5872ff0a6f581e7b2f6a59050179bc4ecf0f27 /doc
parent9766a76000f4b621c0fa1ef9f7ad6d41d0f36a74 (diff)
downloadtcl-97e52f918d3e35ec3f61e099424ccf966aae3101.zip
tcl-97e52f918d3e35ec3f61e099424ccf966aae3101.tar.gz
tcl-97e52f918d3e35ec3f61e099424ccf966aae3101.tar.bz2
Document the Tcl_CancelEval function correctly. It was missing its second argument, making using it correctly impossible, especially from C++.
Diffstat (limited to 'doc')
-rw-r--r--doc/Cancel.318
1 files changed, 13 insertions, 5 deletions
diff --git a/doc/Cancel.3 b/doc/Cancel.3
index 5d258b7..f6b1636 100644
--- a/doc/Cancel.3
+++ b/doc/Cancel.3
@@ -13,20 +13,25 @@ Tcl_CancelEval, Tcl_Canceled \- cancel Tcl scripts
.nf
\fB#include <tcl.h>\fR
int
-\fBTcl_CancelEval\fR(\fIinterp, clientData, flags\fR)
+\fBTcl_CancelEval\fR(\fIinterp, resultObjPtr, clientData, flags\fR)
.sp
int
\fBTcl_Canceled\fR(\fIinterp, flags\fR)
.SH ARGUMENTS
+.AS Tcl_Interp *interp
.AP Tcl_Interp *interp in
Interpreter in which to cancel the script.
+.AP Tcl_Obj *resultObjPtr in
+Error message to use in the cancellation, or NULL to use a default message. If
+not NULL, this object will have its reference count decremented before
+\fBTcl_CancelEval\fR returns.
.AP int flags in
ORed combination of flag bits that specify additional options.
For \fBTcl_CancelEval\fR, only \fBTCL_CANCEL_UNWIND\fR is currently
supported. For \fBTcl_Canceled\fR, only \fBTCL_LEAVE_ERR_MSG\fR and
\fBTCL_CANCEL_UNWIND\fR are currently supported.
.AP ClientData clientData in
-Currently, reserved for future use.
+Currently reserved for future use.
It should be set to NULL.
.BE
.SH DESCRIPTION
@@ -41,19 +46,21 @@ returns \fBTCL_ERROR\fR if it has. Otherwise, \fBTCL_OK\fR is returned.
Extensions can use this function to check to see if they should abort a long
running command. This function is thread sensitive and may only be called
from the thread the interpreter was created in.
-.SH "FLAG BITS"
+.SS "FLAG BITS"
Any ORed combination of the following values may be used for the
\fIflags\fR argument to procedures such as \fBTcl_CancelEval\fR:
-.TP 23
+.TP 20
\fBTCL_CANCEL_UNWIND\fR
+.
This flag is used by \fBTcl_CancelEval\fR and \fBTcl_Canceled\fR.
For \fBTcl_CancelEval\fR, if this flag is set, the script in progress
is canceled and the evaluation stack for the interpreter is unwound.
For \fBTcl_Canceled\fR, if this flag is set, the script in progress
is considered to be canceled only if the evaluation stack for the
interpreter is being unwound.
-.TP 23
+.TP 20
\fBTCL_LEAVE_ERR_MSG\fR
+.
This flag is only used by \fBTcl_Canceled\fR; it is ignored by
other procedures. If an error is returned and this bit is set in
\fIflags\fR, then an error message will be left in the interpreter's
@@ -61,6 +68,7 @@ result, where it can be retrieved with \fBTcl_GetObjResult\fR or
\fBTcl_GetStringResult\fR. If this flag bit is not set then no error
message is left and the interpreter's result will not be modified.
.SH "SEE ALSO"
+interp(n), Tcl_Eval(3),
TIP 285
.SH KEYWORDS
cancel, unwind