[25] | 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 |
---|