1 files changed, 135 insertions, 0 deletions
diff --git a/contrib/tcl/doc/AddErrInfo.3 b/contrib/tcl/doc/AddErrInfo.3
new file mode 100644
index 0000000..51e75c2
--- /dev/null
+++ b/contrib/tcl/doc/AddErrInfo.3
@@ -0,0 +1,135 @@
+'\"
+'\" Copyright (c) 1989-1993 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: @(#) AddErrInfo.3 1.21 96/03/25 19:55:32
+'\" 
+.so man.macros
+.TH Tcl_AddErrorInfo 3 7.5 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_PosixError \- record information about errors
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+\fBTcl_AddErrorInfo\fR(\fIinterp, message\fR)
+.sp
+\fBTcl_SetErrorCode\fR(\fIinterp, element, element, ...\fB (char *) NULL\fR)
+.sp
+char *
+\fBTcl_PosixError\fR(\fIinterp\fR)
+.SH ARGUMENTS
+.AS Tcl_Interp *message
+.AP Tcl_Interp *interp in
+Interpreter in which to record information.
+.AP char *message in
+Identifying string to record in \fBerrorInfo\fR variable.
+.AP char *element in
+String to record as one element of \fBerrorCode\fR variable.
+Last \fIelement\fR argument must be NULL.
+.BE
+
+.SH DESCRIPTION
+.PP
+These procedures are used to manipulate two Tcl global variables
+that hold information about errors.
+The variable \fBerrorInfo\fR holds a stack trace of the
+operations that were in progress when an error occurred, and
+is intended to be human-readable.
+The variable \fBerrorCode\fR holds a list of items that
+are intended to be machine-readable.
+The first item in \fBerrorCode\fR identifies the class of
+.VS
+error that occurred (e.g. POSIX means an error occurred in
+.VE
+a POSIX system call) and additional elements in \fBerrorCode\fR
+hold additional pieces of information that depend on the class.
+See the Tcl overview manual entry for details on the various
+formats for \fBerrorCode\fR.
+.PP
+The \fBerrorInfo\fR variable is gradually built up as an
+error unwinds through the nested operations.
+Each time an error code is returned to \fBTcl_Eval\fR
+it calls the procedure \fBTcl_AddErrorInfo\fR to add
+additional text to \fBerrorInfo\fR describing the
+command that was being executed when the error occurred.
+By the time the error has been passed all the way back
+to the application, it will contain a complete trace
+of the activity in progress when the error occurred.
+.PP
+It is sometimes useful to add additional information to
+\fBerrorInfo\fR beyond what can be supplied automatically
+by \fBTcl_Eval\fR.
+\fBTcl_AddErrorInfo\fR may be used for this purpose:
+its \fImessage\fR argument contains an additional
+string to be appended to \fBerrorInfo\fR.
+For example, the \fBsource\fR command calls \fBTcl_AddErrorInfo\fR
+to record the name of the file being processed and the
+line number on which the error occurred;  for Tcl procedures, the
+procedure name and line number within the procedure are recorded,
+and so on.
+The best time to call \fBTcl_AddErrorInfo\fR is just after
+\fBTcl_Eval\fR has returned \fBTCL_ERROR\fR.
+In calling \fBTcl_AddErrorInfo\fR, you may find it useful to
+use the \fBerrorLine\fR field of the interpreter (see the
+\fBTcl_Interp\fR manual entry for details).
+.PP
+The procedure \fBTcl_SetErrorCode\fR is used to set the
+\fBerrorCode\fR variable.
+Its \fIelement\fR arguments give one or more strings to record
+in \fBerrorCode\fR:  each \fIelement\fR will become one item
+of a properly-formed Tcl list stored in \fBerrorCode\fR.
+\fBTcl_SetErrorCode\fR is typically invoked just before returning
+an error.
+If an error is returned without calling \fBTcl_SetErrorCode\fR
+then the Tcl interpreter automatically sets \fBerrorCode\fR
+to \fBNONE\fR.
+.PP
+\fBTcl_PosixError\fR
+.VS
+sets the \fBerrorCode\fR variable after an error in a POSIX kernel call.
+It reads the value of the \fBerrno\fR C variable and calls
+\fBTcl_SetErrorCode\fR to set \fBerrorCode\fR in the \fBPOSIX\fR format.
+The caller must previously have called \fBTcl_SetErrno\fR to set
+\fBerrno\fR; this is necessary on some platforms (e.g. Windows) where Tcl
+is linked into an application as a shared library, or when the error
+occurs in a dynamically loaded extension. See the manual entry for
+\fBTcl_SetErrno\fR for more information.
+.PP
+\fBTcl_PosixError\fR returns a human-readable
+.VE
+diagnostic message for the error (this is the same value that
+will appear as the third element in \fBerrorCode\fR).
+It may be convenient to include this string as part of the
+error message returned to the application in \fIinterp->result\fR.
+.PP
+It is important to call the procedures described here rather than
+setting \fBerrorInfo\fR or \fBerrorCode\fR directly with
+\fBTcl_SetVar\fR.
+The reason for this is that the Tcl interpreter keeps information
+about whether these procedures have been called.
+For example, the first time \fBTcl_AppendResult\fR is called
+for an error, it clears the existing value of \fBerrorInfo\fR
+and adds the error message in \fIinterp->result\fR to the variable
+before appending \fImessage\fR;  in subsequent calls, it just
+appends the new \fImessage\fR.
+When \fBTcl_SetErrorCode\fR is called, it sets a flag indicating
+that \fBerrorCode\fR has been set;  this allows the Tcl interpreter
+to set \fBerrorCode\fR to \fBNONE\fB if it receives an error return
+when \fBTcl_SetErrorCode\fR hasn't been called.
+.PP
+If the procedure \fBTcl_ResetResult\fR is called, it clears all
+of the state associated with \fBerrorInfo\fR and \fBerrorCode\fR
+(but it doesn't actually modify the variables).
+If an error had occurred, this will clear the error state to
+make it appear as if no error had occurred after all.
+
+.SH "SEE ALSO"
+Tcl_Interp, Tcl_ResetResult, Tcl_SetErrno
+
+.SH KEYWORDS
+error, stack, trace, variable