NAME

       bgerror - Command invoked to process background errors

SYNOPSIS

       bgerror message
________________________________________________________________________________________________________________

DESCRIPTION

       Release  8.5  of  Tcl  supports  the  interp bgerror command, which allows applications to register in an
       interpreter the command that will handle background errors in that interpreter.   In  older  releases  of
       Tcl,  this  level of control was not available, and applications could control the handling of background
       errors only by creating a command with the particular command name bgerror in the global namespace of  an
       interpreter.   The following documentation describes the interface requirements of the bgerror command an
       application might define to retain compatibility with pre-8.5 releases of Tcl.  Applications intending to
       support only Tcl releases 8.5 and later should simply make use of interp bgerror.

       The bgerror command does not exist as built-in part of Tcl.  Instead, individual  applications  or  users
       can define a bgerror command (e.g. as a Tcl procedure) if they wish to handle background errors.

       A  background  error  is one that occurs in an event handler or some other command that did not originate
       with the application.  For example, if an error occurs while executing a command specified with the after
       command, then it is a background error.  For a non-background error, the error can simply be returned  up
       through  nested  Tcl command evaluations until it reaches the top-level code in the application; then the
       application can report the error in whatever  way  it  wishes.   When  a  background  error  occurs,  the
       unwinding ends in the Tcl library and there is no obvious way for Tcl to report the error.

       When  Tcl  detects a background error, it saves information about the error and invokes a handler command
       registered by interp bgerror later as an idle event handler.  The default handler command in  turn  calls
       the  bgerror  command  .   Before invoking bgerror, Tcl restores the errorInfo and errorCode variables to
       their values at the time the error occurred, then it invokes bgerror with the error message as  its  only
       argument.   Tcl  assumes  that  the application has implemented the bgerror command, and that the command
       will report the error in a way that makes sense for the application.  Tcl will ignore any result returned
       by the bgerror command as long as no error is generated.

       If another Tcl error occurs within the bgerror command (for example, because no bgerror command has  been
       defined) then Tcl reports the error itself by writing a message to stderr.

       If  several  background  errors  accumulate  before  bgerror  is invoked to process them, bgerror will be
       invoked once for each error, in the order they occurred.   However,  if  bgerror  returns  with  a  break
       exception, then any remaining errors are skipped without calling bgerror.

       If  you  are  writing  code  that  will  be used by others as part of a package or other kind of library,
       consider avoiding bgerror.  The reason for this is that the  application  programmer  may  also  want  to
       define a bgerror, or use other code that does and thus will have trouble integrating your code.

EXAMPLE

       This bgerror procedure appends errors to a file, with a timestamp.

              proc bgerror {message} {
                  set timestamp [clock format [clock seconds]]
                  set fl [open mylog.txt {WRONLY CREAT APPEND}]
                  puts $fl "$timestamp: bgerror in $::argv '$message'"
                  close $fl
              }

SEE ALSO

       after(3tcl), errorCode(3tcl), errorInfo(3tcl), interp(3tcl)

KEYWORDS

       background error, reporting

Tcl                                                    7.5                                         bgerror(3tcl)