| |
Tcl_AddErrorInfo(3) Tcl Library Procedures Tcl_AddErrorInfo(3)
_________________________________________________________________________________________________
NAME
Tcl_AddObjErrorInfo, Tcl_AddErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tcl_SetEr-
rorCodeVA, Tcl_PosixError, Tcl_LogCommandInfo - record information about errors
SYNOPSIS
#include <tcl.h>
Tcl_AddObjErrorInfo(interp, message, length)
Tcl_AddErrorInfo(interp, message)
Tcl_SetObjErrorCode(interp, errorObjPtr)
Tcl_SetErrorCode(interp, element, element, ... (char *) NULL)
Tcl_SetErrorCodeVA(interp, argList)
CONST char *
Tcl_PosixError(interp)
void
Tcl_LogCommandInfo(interp, script, command, commandLength)
ARGUMENTS
Tcl_Interp *interp (in) Interpreter in which to record information.
char *message (in) For Tcl_AddObjErrorInfo, this points to the first byte
of an array of bytes containing a string to record in
the errorInfo variable. This byte array may contain
embedded null bytes unless length is negative. For
Tcl_AddErrorInfo, this is a conventional C string to
record in the errorInfo variable.
int length (in) The number of bytes to copy from message when setting
the errorInfo variable. If negative, all bytes up to
the first null byte are used.
Tcl_Obj *errorObjPtr(in) This variable errorCode will be set to this value.
char *element (in) String to record as one element of errorCode variable.
Last element argument must be NULL.
va_list argList (in) An argument list which must have been initialized using
TCL_VARARGS_START, and cleared using va_end.
CONST char *script (in) Pointer to first character in script containing command
(must be <= command)
CONST char *command (in) Pointer to first character in command that generated the
error
int commandLength(in) Number of bytes in command; -1 means use all bytes up to
first null byte
_________________________________________________________________
DESCRIPTION
These procedures are used to manipulate two Tcl 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 opera-
tions. Each time an error code is returned to Tcl_EvalObjEx (or Tcl_Eval, which calls
Tcl_EvalObjEx) it calls the procedure Tcl_AddObjErrorInfo to add additional text to error-
Info 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 sup-
plied automatically by Tcl_EvalObjEx. Tcl_AddObjErrorInfo may be used for this purpose:
its message and length arguments describe an additional string to be appended to error-
Info. For example, the source command calls Tcl_AddObjErrorInfo 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_AddObjErrorInfo is just after Tcl_EvalObjEx has returned TCL_ERROR. In
calling Tcl_AddObjErrorInfo, you may find it useful to use the errorLine field of the
interpreter (see the Tcl_Interp manual entry for details).
Tcl_AddErrorInfo resembles Tcl_AddObjErrorInfo but differs in initializing errorInfo from
the string value of the interpreter's result if the error is just starting to be logged.
It does not use the result as a Tcl object so any embedded null characters in the result
will cause information to be lost. It also takes a conventional C string in message
instead of Tcl_AddObjErrorInfo's counted string.
The procedure Tcl_SetObjErrorCode is used to set the errorCode variable. errorObjPtr con-
tains a list object built up by the caller. errorCode is set to this value. Tcl_SetObjEr-
rorCode is typically invoked just before returning an error in an object command. If an
error is returned without calling Tcl_SetObjErrorCode or Tcl_SetErrorCode the Tcl inter-
preter automatically sets errorCode to NONE.
The procedure Tcl_SetErrorCode is also used to set the errorCode variable. However, it
takes one or more strings to record instead of an object. Otherwise, it is similar to
Tcl_SetObjErrorCode in behavior.
Tcl_SetErrorCodeVA is the same as Tcl_SetErrorCode except that instead of taking a vari-
able number of arguments it takes an argument list.
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 the inter-
preter's result.
Tcl_LogCommandInfo is invoked after an error occurs in an interpreter. It adds informa-
tion about the command that was being executed when the error occurred to the errorInfo
variable, and the line number stored internally in the interpreter is set. On the first
call to Tcl_LogCommandInfo or Tcl_AddObjErrorInfo since an error occurred, the old infor-
mation in errorInfo is deleted.
It is important to call the procedures described here rather than setting errorInfo or
errorCode directly with Tcl_ObjSetVar2. The reason for this is that the Tcl interpreter
keeps information about whether these procedures have been called. For example, the first
time Tcl_AddObjErrorInfo is called for an error, it clears the existing value of errorInfo
and adds the error message in the interpreter's 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 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_DecrRefCount, Tcl_IncrRefCount, Tcl_Interp, Tcl_ResetResult, Tcl_SetErrno
KEYWORDS
error, object, object result, stack, trace, variable
Tcl 8.0 Tcl_AddErrorInfo(3) |
|
