NAME¶
Tcl_GetReturnOptions, Tcl_SetReturnOptions, Tcl_AddErrorInfo,
Tcl_AppendObjToErrorInfo, Tcl_AddObjErrorInfo, Tcl_SetObjErrorCode,
Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_PosixError, Tcl_LogCommandInfo -
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 negative.
- 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, without
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
argument without the need to tend to any reference counting. This is analogous
to
Tcl_SetObjResult.
While
Tcl_SetReturnOptions provides a general interface to set any
collection 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-readable. 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 activity 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 evaluation
routines.
Tcl_AddErrorInfo may be used for this purpose: its
message 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. Likewise, 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
functionality 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 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 the
-errorcode return option 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 the
-errorcode value). 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 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 written
for older Tcl releases still access this information via those global
variables.
It is important to realize that while reading from those global variables
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 emphasized 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_ResetResult 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 interpreter.
SEE ALSO¶
Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_Interp, Tcl_ResetResult, Tcl_SetErrno
KEYWORDS¶
error, object, object result, stack, trace, variable