Tcl_BackgroundError(3tcl)

______________________________________________________________________________

NAME

       Tcl_BackgroundError - report Tcl error that occurred in background pro-
       cessing

SYNOPSIS

       #include <tcl.h>

       Tcl_BackgroundError(interp)

ARGUMENTS

       Tcl_Interp   *interp   (in)      Interpreter   in   which   the   error
                                        occurred.
_________________________________________________________________

DESCRIPTION

       This  procedure  is  typically  invoked  when a Tcl error occurs during
       ``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.  In these cases the code
       calls Tcl_BackgroundError  with  an  interp  argument  identifying  the
       interpreter in which the error occurred.  At the time Tcl_BackgroundEr-
       ror is invoked, the interpreter's result  is  expected  to  contain  an
       error message.  Tcl_BackgroundError will invoke the bgerror Tcl command
       to report the error in an application-specific fashion.  If no  bgerror
       command  exists,  or  if  it  returns  with  an  error  condition, then
       Tcl_BackgroundError reports the error itself by printing a  message  on
       the standard error file.

       Tcl_BackgroundError  does  not  invoke bgerror immediately because this
       could potentially interfere with scripts that are  in  process  at  the
       time  the error occurred.  Instead, it invokes bgerror later as an idle
       callback.  Tcl_BackgroundError saves the values of  the  errorInfo  and
       errorCode  variables  and  restores  these  values just before invoking
       bgerror.

       It is possible for many background errors to accumulate before  bgerror
       is  invoked.   When  this  happens,  each of the errors is processed in
       order.  However, if bgerror returns a break exception, then all remain-
       ing error reports for the interpreter are skipped.

KEYWORDS

       background, bgerror, error

Tcl                                   7.5               Tcl_BackgroundError(3)