| 1 | '\" |
|---|
| 2 | '\" Copyright (c) 1992-1994 The Regents of the University of California. |
|---|
| 3 | '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. |
|---|
| 4 | '\" |
|---|
| 5 | '\" See the file "license.terms" for information on usage and redistribution |
|---|
| 6 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
|---|
| 7 | '\" |
|---|
| 8 | '\" RCS: @(#) $Id: BackgdErr.3,v 1.8 2007/12/13 15:22:30 dgp Exp $ |
|---|
| 9 | '\" |
|---|
| 10 | .so man.macros |
|---|
| 11 | .TH Tcl_BackgroundError 3 7.5 Tcl "Tcl Library Procedures" |
|---|
| 12 | .BS |
|---|
| 13 | .SH NAME |
|---|
| 14 | Tcl_BackgroundError \- report Tcl error that occurred in background processing |
|---|
| 15 | .SH SYNOPSIS |
|---|
| 16 | .nf |
|---|
| 17 | \fB#include <tcl.h>\fR |
|---|
| 18 | .sp |
|---|
| 19 | \fBTcl_BackgroundError\fR(\fIinterp\fR) |
|---|
| 20 | .SH ARGUMENTS |
|---|
| 21 | .AS Tcl_Interp *interp |
|---|
| 22 | .AP Tcl_Interp *interp in |
|---|
| 23 | Interpreter in which the error occurred. |
|---|
| 24 | .BE |
|---|
| 25 | |
|---|
| 26 | .SH DESCRIPTION |
|---|
| 27 | .PP |
|---|
| 28 | This procedure is typically invoked when a Tcl error occurs during |
|---|
| 29 | .QW "background processing" |
|---|
| 30 | such as executing an event handler. |
|---|
| 31 | When such an error occurs, the error condition is reported to Tcl |
|---|
| 32 | or to a widget or some other C code, and there is not usually any |
|---|
| 33 | obvious way for that code to report the error to the user. |
|---|
| 34 | In these cases the code calls \fBTcl_BackgroundError\fR with an |
|---|
| 35 | \fIinterp\fR argument identifying the interpreter in which the |
|---|
| 36 | error occurred. At the time \fBTcl_BackgroundError\fR is invoked, |
|---|
| 37 | the interpreter's result is expected to contain an error message. |
|---|
| 38 | \fBTcl_BackgroundError\fR will invoke the command registered |
|---|
| 39 | in that interpreter to handle background errors by the |
|---|
| 40 | \fBinterp bgerror\fR command. |
|---|
| 41 | The registered handler command is meant to report the error |
|---|
| 42 | in an application-specific fashion. The handler command |
|---|
| 43 | receives two arguments, the result of the interp, and the |
|---|
| 44 | return options of the interp at the time the error occurred. |
|---|
| 45 | If the application registers no handler command, the default |
|---|
| 46 | handler command will attempt to call \fBbgerror\fR to report |
|---|
| 47 | the error. If an error condition arises while invoking the |
|---|
| 48 | handler command, then \fBTcl_BackgroundError\fR reports the |
|---|
| 49 | error itself by printing a message on the standard error file. |
|---|
| 50 | .PP |
|---|
| 51 | \fBTcl_BackgroundError\fR does not invoke the handler command immediately |
|---|
| 52 | because this could potentially interfere with scripts that are in process |
|---|
| 53 | at the time the error occurred. |
|---|
| 54 | Instead, it invokes the handler command later as an idle callback. |
|---|
| 55 | .PP |
|---|
| 56 | It is possible for many background errors to accumulate before |
|---|
| 57 | the handler command is invoked. When this happens, each of the errors |
|---|
| 58 | is processed in order. However, if the handle command returns a |
|---|
| 59 | break exception, then all remaining error reports for the |
|---|
| 60 | interpreter are skipped. |
|---|
| 61 | |
|---|
| 62 | .SH KEYWORDS |
|---|
| 63 | background, bgerror, error, interp |
|---|
