Tcl_AddErrorInfo(3Tcl)Tcl_AddErrorInfo(3Tcl)NAME
Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_PosixError - record information
about errors
SYNOPSIS
#include <tcl.h>
Tcl_AddErrorInfo(interp, message)
Tcl_SetErrorCode(interp, element, element, ... (char *) NULL)
char *
Tcl_PosixError(interp)ARGUMENTS
Tcl_Interp *interp (in) Interpreter in which to record
information.
char *message (in) Identifying string to record in
errorInfo variable.
char *element (in) String to record as one element of
errorCode variable. Last element
argument must be NULL.
DESCRIPTION
These procedures are used to manipulate two global variables that hold
information about errors. The variable errorInfo holds a stack trace of
the operations that were in progress when an error occurred, and is
intended to be human-readable. The variable errorCode holds a list of
items that are intended to be machine-readable. The first item in
errorCode identifies the class of error that occurred (e.g. POSIX means |
an error occurred in a POSIX system call) and additional elements in
errorCode hold additional pieces of information that depend on the class.
See the Tcl overview manual entry for details on the various formats for
errorCode.
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
Page 1
Tcl_AddErrorInfo(3Tcl)Tcl_AddErrorInfo(3Tcl)
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. In addition, |
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.
SEE ALSO
Tcl_ResetResult, Tcl_Interp
KEYWORDS
error, stack, trace, variable
Page 2
