summaryrefslogtreecommitdiffstats
path: root/doc/BackgdErr.3
diff options
context:
space:
mode:
Diffstat (limited to 'doc/BackgdErr.3')
-rw-r--r--doc/BackgdErr.332
1 files changed, 18 insertions, 14 deletions
diff --git a/doc/BackgdErr.3 b/doc/BackgdErr.3
index 1ac84c4..315e3b9 100644
--- a/doc/BackgdErr.3
+++ b/doc/BackgdErr.3
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: BackgdErr.3,v 1.3 2000/04/14 23:01:48 hobbs Exp $
+'\" RCS: @(#) $Id: BackgdErr.3,v 1.4 2004/11/20 00:17:31 dgp Exp $
'\"
.so man.macros
.TH Tcl_BackgroundError 3 7.5 Tcl "Tcl Library Procedures"
@@ -34,25 +34,29 @@ In these cases the code calls \fBTcl_BackgroundError\fR with an
\fIinterp\fR argument identifying the interpreter in which the
error occurred. At the time \fBTcl_BackgroundError\fR is invoked,
the interpreter's result is expected to contain an error message.
-\fBTcl_BackgroundError\fR will invoke the \fBbgerror\fR
-Tcl command to report the error in an application-specific fashion.
-If no \fBbgerror\fR command exists, or if it returns with an error condition,
-then \fBTcl_BackgroundError\fR reports the error itself by printing
-a message on the standard error file.
+\fBTcl_BackgroundError\fR will invoke the command registered
+in that interpreter to handle background errors by the
+\fBinterp bgerror\fR command.
+The registered handler command is meant to report the error
+in an application-specific fashion. The handler command
+receives two arguments, the result of the interp, and the
+return options of the interp at the time the error occurred.
+If the application registers no handler command, the default
+handler command will attempt to call \fBbgerror\fR to report
+the error. If an error condition arises while invoking the
+handler command, then \fBTcl_BackgroundError\fR reports the
+error itself by printing a message on the standard error file.
.PP
-\fBTcl_BackgroundError\fR does not invoke \fBbgerror\fR immediately
+\fBTcl_BackgroundError\fR does not invoke the handler command immediately
because this could potentially interfere with scripts that are in process
at the time the error occurred.
-Instead, it invokes \fBbgerror\fR later as an idle callback.
-\fBTcl_BackgroundError\fR saves the values of the \fBerrorInfo\fR and
-\fBerrorCode\fR variables and restores these values just before
-invoking \fBbgerror\fR.
+Instead, it invokes the handler command later as an idle callback.
.PP
It is possible for many background errors to accumulate before
-\fBbgerror\fR is invoked. When this happens, each of the errors
-is processed in order. However, if \fBbgerror\fR returns a
+the handler command is invoked. When this happens, each of the errors
+is processed in order. However, if the handle command returns a
break exception, then all remaining error reports for the
interpreter are skipped.
.SH KEYWORDS
-background, bgerror, error
+background, bgerror, error, interp