Initial revision

1 files changed, 58 insertions, 0 deletions

diff --git a/doc/BackgdErr.3 b/doc/BackgdErr.3
new file mode 100644
index 0000000..005f5b6
--- /dev/null
+++ b/doc/BackgdErr.3
@@ -0,0 +1,58 @@
+'\"
+'\" Copyright (c) 1992-1994 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+'\" SCCS: @(#) BackgdErr.3 1.3 96/03/25 19:56:51
+'\" 
+.so man.macros
+.TH Tcl_BackgroundError 3 7.5 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_BackgroundError \- report Tcl error that occurred in background processing
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+\fBTcl_BackgroundError\fR(\fIinterp\fR)
+.SH ARGUMENTS
+.AS Tcl_Interp *interp
+.AP Tcl_Interp *interp in
+Interpreter in which the error occurred.
+.BE
+
+.SH DESCRIPTION
+.PP
+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 \fBTcl_BackgroundError\fR with an
+\fIinterp\fR argument identifying the interpreter in which the
+error occurred.  At the time \fBTcl_BackgroundError\fR is invoked,
+\fIinterp->result\fR 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.
+.PP
+\fBTcl_BackgroundError\fR does not invoke \fBbgerror\fR 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.
+.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
+break exception, then all remaining error reports for the
+interpreter are skipped.
+
+.SH KEYWORDS
+background, bgerror, error