NAME

       Tcl_CancelEval, Tcl_Canceled - cancel Tcl scripts

SYNOPSIS

       #include <tcl.h>
       int
       Tcl_CancelEval(interp, clientData, flags)

       int
       Tcl_Canceled(interp, flags)

ARGUMENTS

       Tcl_Interp *interp (in)                   Interpreter in which to cancel the script.

       int flags (in)                            ORed  combination  of  flag  bits  that  specify
                                                 additional options.   For  Tcl_CancelEval,  only
                                                 TCL_CANCEL_UNWIND  is  currently supported.  For
                                                 Tcl_Canceled,   only    TCL_LEAVE_ERR_MSG    and
                                                 TCL_CANCEL_UNWIND are currently supported.

       ClientData clientData (in)                Currently,  reserved  for future use.  It should
                                                 be set to NULL.
_________________________________________________________________

DESCRIPTION

       Tcl_CancelEval cancels or unwinds the script in progress soon after the next invocation of
       asynchronous  handlers,  causing  TCL_ERROR  to  be the return code for that script.  This
       function is thread-safe and may be called from any thread in the process.

       Tcl_Canceled checks if the script in progress has been canceled and returns  TCL_ERROR  if
       it  has.  Otherwise, TCL_OK 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.

FLAG BITS

       Any  ORed  combination  of  the  following  values  may  be used for the flags argument to
       procedures such as Tcl_CancelEval:

       TCL_CANCEL_UNWIND      This  flag  is  used  by  Tcl_CancelEval  and  Tcl_Canceled.    For
                              Tcl_CancelEval,  if  this  flag  is  set, the script in progress is
                              canceled and the evaluation stack for the interpreter  is  unwound.
                              For  Tcl_Canceled,  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.

       TCL_LEAVE_ERR_MSG      This  flag  is  only  used  by Tcl_Canceled; it is ignored by other
                              procedures.  If an error is returned and this bit is set in  flags,
                              then  an  error  message  will be left in the interpreter's result,
                              where   it   can   be   retrieved    with    Tcl_GetObjResult    or
                              Tcl_GetStringResult.   If  this  flag  bit is not set then no error
                              message is left and the interpreter's result will not be modified.

SEE ALSO

       TIP 285

KEYWORDS

       cancel, unwind