#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)
char * Tcl_PosixError(interp)
void Tcl_LogCommandInfo(interp, script,
command, commandLength)
- 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.
- char *script (in)
-
Pointer to first character in script containing command (must be <=
command)
- 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
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
(for example, 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 reference page 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_EvalObjEx()
(or Tcl_Eval(), which calls
Tcl_EvalObjEx())
it calls the procedure Tcl_AddObjErrorInfo() 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_EvalObjEx().
Tcl_AddObjErrorInfo() may be used for this purpose:
its message and length arguments describe an
additional
string to be appended to errorInfo.
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() reference page 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 contains a list
object
built up by the caller. errorCode is set to this
value. Tcl_SetObjErrorCode() 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 interpreter 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 variable 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 (for example, Windows)
where Tcl
is linked into an application as a shared library, or when the error
occurs in a dynamically loaded extension. See the reference page 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 interpreter's result.
Tcl_LogCommandInfo() is invoked after an error occurs in an
interpreter. It adds information 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 information 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 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.
Windows 10. Windows Server 2016. Windows Server 2019. Windows 11. Windows Server 2022. Windows Server 2025.
PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition
- Functions:
- Tcl_DecrRefCount(), Tcl_IncrRefCount(), Tcl_Interp(), Tcl_ResetResult(), Tcl_SetErrno()
PTC MKS Toolkit 10.5 Documentation Build 40.