The errorInfo variable is gradually built up as an error unwinds through the nested operations. Each time an error code is returned to Tcl_Eval it calls the procedure Tcl_AddErrorInfo to add additional text to errorInfo 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.
It is sometimes useful to add additional information to errorInfo beyond what can be supplied automatically by Tcl_Eval. Tcl_AddErrorInfo may be used for this purpose: its message argument contains an additional string to be appended to errorInfo. For example, the source command calls Tcl_AddErrorInfo 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 Tcl_AddErrorInfo is just after Tcl_Eval has returned TCL_ERROR. In calling Tcl_AddErrorInfo, you may find it useful to use the errorLine field of the interpreter (see the Tcl_Interp manual entry for details).
The procedure Tcl_SetErrorCode is used to set the errorCode variable. Its element arguments give one or more strings to record in errorCode: each element will become one item of a properly-formed Tcl list stored in errorCode. Tcl_SetErrorCode is typically invoked just before returning an error. If an error is returned without calling Tcl_SetErrorCode then the Tcl interpreter automatically sets errorCode to NONE.
Tcl_PosixError sets the errorCode variable after an error in a POSIX kernel call. It reads the value of the errno C variable and calls Tcl_SetErrorCode to set errorCode in the POSIX format. The caller must previously have called Tcl_SetErrno to set errno; 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 Tcl_SetErrno for more information.
Tcl_PosixError returns a human-readable diagnostic message for the error (this is the same value that will appear as the third element in errorCode). It may be convenient to include this string as part of the error message returned to the application in interp->result.
It is important to call the procedures described here rather than setting errorInfo or errorCode directly with Tcl_SetVar. The reason for this is that the Tcl interpreter keeps information about whether these procedures have been called. For example, the first time Tcl_AppendResult is called for an error, it clears the existing value of errorInfo and adds the error message in interp->result to the variable before appending message; in subsequent calls, it just appends the new message. When Tcl_SetErrorCode is called, it sets a flag indicating that errorCode has been set; this allows the Tcl interpreter to set errorCode to NONE if it receives an error return when Tcl_SetErrorCode hasn't been called.
If the procedure Tcl_ResetResult is called, it clears all of the state associated with errorInfo and errorCode (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.
Copyright © 1989-1993 The Regents of the University of California. Copyright © 1994-1996 Sun Microsystems, Inc. Copyright © 1995, 1996 Roger E. Critchlow Jr.