Tcl_BackgroundError(3)Tcl

_________________________________________________________________

NAME
       Tcl_BackgroundError  -  report  Tcl error that occurred in
       background processing

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_BackgroundError is invoked, interp-&gt;result
       is  expected  to  contain  an  error  message.   Tcl_Back-
       groundError  will invoke the bgerror Tcl command to report
       the error in an application-specific fashion.  If no bger-
       ror  command exists, or if it returns with an error condi-
       tion, 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_Back-
       groundError  saves  the values of the errorInfo and error-
       Code 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 remaining  error  reports  for
       the interpreter are skipped.

KEYWORDS
       background, bgerror, error