Tcl_AddObjErrorInfo(3tcl)
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_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 informa-
tion.
int code The code returned
from script evalua-
tion.
Tcl_Obj *options A dictionary of
return options.
char *message (in) For Tcl_AddErrorInfo,
this is a conven-
tional C string to
Tcl Last change: 8.5 1
Tcl_AddErrorInfo(3) Tcl Library Procedures Tcl_AddErrorInfo(3)
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
Tcl Last change: 8.5 2
Tcl_AddErrorInfo(3) Tcl Library Procedures Tcl_AddErrorInfo(3)
(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 com- |
mands, 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 Last change: 8.5 3
Tcl_AddErrorInfo(3) Tcl Library Procedures Tcl_AddErrorInfo(3)
} |
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 comple- |
tion code in agreement with the -code and -level keys in |
options will be returned. |
As an example, Tcl's return command itself could be imple- |
mented 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 addi-
tional 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 exe-
cuted 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
Tcl Last change: 8.5 4
Tcl_AddErrorInfo(3) Tcl Library Procedures Tcl_AddErrorInfo(3)
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 addi-
tional 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 -error-
code 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 Last change: 8.5 5
Tcl_AddErrorInfo(3) Tcl Library Procedures Tcl_AddErrorInfo(3)
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 previ-
ously have called Tcl_SetErrno to set errno; this is neces-
sary 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 con-
venient 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 inter-
preter 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 pro-
cedures 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 evalua-
tion, 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 con-
tinue to hold a record of information about the most recent
error seen in an interpreter.
SEE ALSO
Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_Interp,
Tcl Last change: 8.5 6
Tcl_AddErrorInfo(3) Tcl Library Procedures Tcl_AddErrorInfo(3)
Tcl_ResetResult, Tcl_SetErrno
KEYWORDS
error, object, object result, stack, trace, variable
Tcl Last change: 8.5 7
Man(1) output converted with
man2html