Tcl_AddErrorInfo(3) Tcl Library Procedures Tcl_AddErrorInfo(3)_________________________________________________________________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 Tcl global
variables that hold information about errors. The vari-
able 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 vari-
ous 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 com-
plete trace of the activity in progress when the error
occurred.
Tcl 7.5 1
Tcl_AddErrorInfo(3) Tcl Library Procedures Tcl_AddErrorInfo(3)
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 error-
Code 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 error-
Code. Tcl_SetErrorCode is typically invoked just before
returning an error. If an error is returned without call-
ing Tcl_SetErrorCode then the Tcl interpreter automati-
cally 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 plat-
forms (e.g. Windows) where Tcl is linked into an applica-
tion 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 inter-
preter keeps information about whether these procedures
have been called. For example, the first time Tcl_Appen-
dResult 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 inter-
preter 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
Tcl 7.5 2
Tcl_AddErrorInfo(3) Tcl Library Procedures Tcl_AddErrorInfo(3)
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_Interp, Tcl_ResetResult, Tcl_SetErrno
KEYWORDS
error, stack, trace, variable
Tcl 7.5 3
