Tcl_AddErrorInfo(3) Tcl Library Procedures Tcl_AddErrorInfo(3)______________________________________________________________________________NAME
Tcl_GetReturnOptions, Tcl_SetReturnOptions, Tcl_AddErrorInfo,
Tcl_AppendObjToErrorInfo, Tcl_AddObjErrorInfo, Tcl_SetObjErrorCode,
Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_PosixError, Tcl_LogCommand‐
Info - retrieve or record information about errors and other return
options
SYNOPSIS
#include <tcl.h>
Tcl_Obj * │
Tcl_GetReturnOptions(interp, code) │
int │
Tcl_SetReturnOptions(interp, options) │
Tcl_AddErrorInfo(interp, message)
Tcl_AppendObjToErrorInfo(interp, objPtr) │
Tcl_AddObjErrorInfo(interp, message, length)
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.
int code The code returned from script
evaluation.
Tcl_Obj *options A dictionary of return options.
char *message (in) For Tcl_AddErrorInfo, this is a
conventional C string to append
to the -errorinfo return option.
For Tcl_AddObjErrorInfo, this
points to the first byte of an
array of length bytes containing
a string to append to the
-errorinfo return option. This
byte array may contain embedded
null bytes unless length is neg‐
ative. │
Tcl_Obj *objPtr (in) │
A message to be appended to the │
-errorinfo return option in the │
form of a Tcl_Obj value.
int length (in) The number of bytes to copy from
message when appending to the
-errorinfo return option. If
negative, all bytes up to the
first null byte are used.
Tcl_Obj *errorObjPtr (in) The -errorcode return option
will be set to this value.
char *element (in) String to record as one element
of the -errorcode return option.
Last element argument must be
NULL.
va_list argList (in) An argument list which must have
been initialized using va_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
The Tcl_SetReturnOptions and Tcl_GetReturnOptions routines expose the │
same capabilities as the return and catch commands, respectively, in │
the form of a C interface. │
Tcl_GetReturnOptions retrieves the dictionary of return options from an │
interpreter following a script evaluation. Routines such as Tcl_Eval │
are called to evaluate a script in an interpreter. These routines │
return an integer completion code. These routines also leave in the │
interpreter both a result and a dictionary of return options generated │
by script evaluation. Just as Tcl_GetObjResult retrieves the result, │
Tcl_GetReturnOptions retrieves the dictionary of return options. The │
integer completion code should be passed as the code argument to │
Tcl_GetReturnOptions so that all required options will be present in │
the dictionary. Specifically, a code value of TCL_ERROR will ensure │
that entries for the keys -errorinfo, -errorcode, and -errorline will │
appear in the dictionary. Also, the entries for the keys -code and │
-level will be adjusted if necessary to agree with the value of code. │
The (Tcl_Obj *) returned by Tcl_GetReturnOptions points to an unshared │
Tcl_Obj with reference count of zero. The dictionary may be written │
to, either adding, removing, or overwriting any entries in it, with the │
need to check for a shared object. │
A typical usage for Tcl_GetReturnOptions is to retrieve the stack trace │
when script evaluation returns TCL_ERROR, like so: │
int code = Tcl_Eval(interp, script); │
if (code == TCL_ERROR) { │
Tcl_Obj *options = Tcl_GetReturnOptions(interp, code); │
Tcl_Obj *key = Tcl_NewStringObj("-errorinfo", -1); │
Tcl_Obj *stackTrace; │
Tcl_IncrRefCount(key); │
Tcl_DictObjGet(NULL, options, key, &stackTrace); │
Tcl_DecrRefCount(key); │
/* Do something with stackTrace */ │
} │
Tcl_SetReturnOptions sets the return options of interp to be options. │
If options contains any invalid value for any key, TCL_ERROR will be │
returned, and the interp result will be set to an appropriate error │
message. Otherwise, a completion code in agreement with the -code and │
-level keys in options will be returned. │
As an example, Tcl's return command itself could be implemented in │
terms of Tcl_SetReturnOptions like so: │
if ((objc % 2) == 0) { /* explicit result argument */ │
objc--; │
Tcl_SetObjResult(interp, objv[objc]); │
} │
return Tcl_SetReturnOptions(interp, Tcl_NewListObj(objc-1, objv+1));│
(It is not really implemented that way. Internal access privileges │
allow for a more efficient alternative that meshes better with the │
bytecode compiler.) │
Note that a newly created Tcl_Obj may be passed in as the options argu‐ │
ment without the need to tend to any reference counting. This is anal‐ │
ogous to Tcl_SetObjResult. │
While Tcl_SetReturnOptions provides a general interface to set any col‐ │
lection of return options, there are a handful of return options that │
are very frequently used. Most notably the -errorinfo and -errorcode │
return options should be set properly when the command procedure of a │
command returns TCL_ERROR. Tcl provides several simpler interfaces to │
more directly set these return options.
The -errorinfo option holds a stack trace of the operations that were
in progress when an error occurred, and is intended to be human-read‐
able. The -errorcode option holds a list of items that are intended to
be machine-readable. The first item in the -errorcode value identifies
the class of error that occurred (e.g. POSIX means an error occurred in
a POSIX system call) and additional elements hold additional pieces of
information that depend on the class. See the tclvars manual entry for
details on the various formats for the -errorcode option used by Tcl's
built-in commands.
The -errorinfo option value is gradually built up as an error unwinds
through the nested operations. Each time an error code is returned to
Tcl_Eval, or any of the routines that performs script evaluation, the
procedure Tcl_AddErrorInfo is called to add additional text to the
-errorinfo value 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 activ‐
ity in progress when the error occurred.
It is sometimes useful to add additional information to the -errorinfo
value beyond what can be supplied automatically by the script evalua‐
tion routines. Tcl_AddErrorInfo may be used for this purpose: its mes‐
sage argument is an additional string to be appended to the -errorinfo
option. For example, when an error arises during the source command,
the procedure Tcl_AddErrorInfo is called to record the name of the file
being processed and the line number on which the error occurred. Like‐
wise, when an error arises during evaluation of a 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 a script
evaluation routine has returned TCL_ERROR. The value of the -errorline
return option (retrieved via a call to Tcl_GetReturnOptions) often
makes up a useful part of the message passed to Tcl_AddErrorInfo.
Tcl_AppendObjToErrorInfo is an alternative interface to the same func‐ │
tionality as Tcl_AddErrorInfo. Tcl_AppendObjToErrorInfo is called when │
the string value to be appended to the -errorinfo option is available │
as a Tcl_Obj instead of as a char array.
Tcl_AddObjErrorInfo is nearly identical to Tcl_AddErrorInfo, except
that it has an additional length argument. This allows the message
string to contain embedded null bytes. This is essentially never a
good idea. If the message needs to contain the null character U+0000,
Tcl's usual internal encoding rules should be used to avoid the need
for a null byte. If the Tcl_AddObjErrorInfo interface is used at all,
it should be with a negative length value.
The procedure Tcl_SetObjErrorCode is used to set the -errorcode return
option to the list object errorObjPtr built up by the caller.
Tcl_SetObjErrorCode is typically invoked just before returning an
error. If an error is returned without calling Tcl_SetObjErrorCode or
Tcl_SetErrorCode the Tcl interpreter automatically sets the -errorcode
return option to NONE.
The procedure Tcl_SetErrorCode is also used to set the -errorcode
return option. However, it takes one or more strings to record instead
of an object. Otherwise, it is similar to Tcl_SetObjErrorCode in behav‐
ior.
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 the -errorcode return option in the POSIX for‐
mat. 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
the -errorcode value). 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 information about the command that was being executed when the
error occurred to the -errorinfo value, and the line number stored
internally in the interpreter is set.
In older releases of Tcl, there was no Tcl_GetReturnOptions routine.
In its place, the global Tcl variables errorInfo and errorCode were the
only place to retrieve the error information. Much existing code writ‐
ten for older Tcl releases still access this information via those
global variables.
It is important to realize that while reading from those global vari‐
ables remains a supported way to access these return option values, it
is important not to assume that writing to those global variables will
properly set the corresponding return options. It has long been empha‐
sized in this manual page that it is important to call the procedures
described here rather than setting errorInfo or errorCode directly with
Tcl_ObjSetVar2.
If the procedure Tcl_ResetResult is called, it clears all of the state
of the interpreter associated with script evaluation, including the
entire return options dictionary. In particular, the -errorinfo and
-errorcode options are reset. If an error had occurred, the Tcl_Rese‐
tResult call will clear the error state to make it appear as if no
error had occurred after all. The global variables errorInfo and
errorCode are not modified by Tcl_ResetResult so they continue to hold
a record of information about the most recent error seen in an inter‐
preter.
SEE ALSO
Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_Interp, Tcl_ResetResult,
Tcl_SetErrno
KEYWORDS
error, object, object result, stack, trace, variable
Tcl 8.5 Tcl_AddErrorInfo(3)
