1Tcl_Cancel(3)               Tcl Library Procedures               Tcl_Cancel(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_CancelEval, Tcl_Canceled - cancel Tcl scripts
9

SYNOPSIS

11       #include <tcl.h>
12       int
13       Tcl_CancelEval(interp, resultObjPtr, clientData, flags)
14
15       int
16       Tcl_Canceled(interp, flags)
17

ARGUMENTS

19       Tcl_Interp *interp (in)          Interpreter  in  which  to  cancel the
20                                        script.
21
22       Tcl_Obj *resultObjPtr (in)       Error message to use in the  cancella‐
23                                        tion,  or  NULL  to use a default mes‐
24                                        sage. If not NULL,  this  object  will
25                                        have  its  reference count decremented
26                                        before Tcl_CancelEval returns.
27
28       int flags (in)                   ORed combination  of  flag  bits  that
29                                        specify   additional   options.    For
30                                        Tcl_CancelEval, only TCL_CANCEL_UNWIND
31                                        is  currently supported.  For Tcl_Can‐
32                                        celed,  only   TCL_LEAVE_ERR_MSG   and
33                                        TCL_CANCEL_UNWIND  are  currently sup‐
34                                        ported.
35
36       ClientData clientData (in)       Currently reserved for future use.  It
37                                        should be set to NULL.
38______________________________________________________________________________
39

DESCRIPTION

41       Tcl_CancelEval cancels or unwinds the script in progress soon after the
42       next invocation of asynchronous handlers, causing TCL_ERROR to  be  the
43       return  code  for that script.  This function is thread-safe and may be
44       called from any thread in the process.
45
46       Tcl_Canceled checks if the script in progress  has  been  canceled  and
47       returns  TCL_ERROR  if  it has.  Otherwise, TCL_OK is returned.  Exten‐
48       sions can use this function to check to see if they should abort a long
49       running  command.   This  function  is thread sensitive and may only be
50       called from the thread the interpreter was created in.
51
52   FLAG BITS
53       Any ORed combination of the following values may be used for the  flags
54       argument to procedures such as Tcl_CancelEval:
55
56       TCL_CANCEL_UNWIND   This  flag  is  used by Tcl_CancelEval and Tcl_Can‐
57                           celed.  For Tcl_CancelEval, if this  flag  is  set,
58                           the  script in progress is canceled and the evalua‐
59                           tion stack for the  interpreter  is  unwound.   For
60                           Tcl_Canceled,  if  this  flag is set, the script in
61                           progress is considered to be canceled only  if  the
62                           evaluation  stack  for  the  interpreter  is  being
63                           unwound.
64
65       TCL_LEAVE_ERR_MSG   This flag is  only  used  by  Tcl_Canceled;  it  is
66                           ignored  by  other  procedures.   If  an  error  is
67                           returned and this bit is  set  in  flags,  then  an
68                           error  message  will  be  left in the interpreter's
69                           result, where it can be retrieved  with  Tcl_GetOb‐
70                           jResult  or  Tcl_GetStringResult.  If this flag bit
71                           is not set then no error message is  left  and  the
72                           interpreter's result will not be modified.
73

SEE ALSO

75       interp(n), Tcl_Eval(3), TIP 285
76

KEYWORDS

78       cancel, unwind
79
80
81
82Tcl                                   8.6                        Tcl_Cancel(3)