Tribblix: manual page: Tcl_AddObjErrorInfo.3

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_SetErrorLine,
Tcl_GetErrorLine, 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)

Tcl_GetErrorLine(interp)

Tcl_SetErrorLine(interp, lineNum)

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.

const 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.

const char *element (in) String to record as one
element of the -errorcode
return option. Last element
argument must be (char *)NULL.

va_list argList (in) An argument list which must
have been initialized using
va_start, and cleared using
va_end.
int lineNum The line number of a script where an error
occurred.

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 value. As with any Tcl_Obj with reference count of
zero, it is up to the caller to arrange for its disposal with
Tcl_DecrRefCount or to a reference to it via Tcl_IncrRefCount (or one
of the many functions that call that, notably including
Tcl_SetObjResult and Tcl_SetVar2Ex).

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_DecrRefCount(options);
}

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. The -errorline return
option is also read by commands that evaluate scripts and wish to
supply detailed error location information in the stack trace text
they append to the -errorinfo option. 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 Tcl 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 manual entry on the errorCode variable 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 value 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 a value. 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.

The procedure Tcl_GetErrorLine is used to read the integer value of
the -errorline return option without the overhead of a full call to
Tcl_GetReturnOptions. Likewise, Tcl_SetErrorLine sets the -errorline
return option value.

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.

KEYWORDS

error, value, value result, stack, trace, variable

Tcl 8.5 Tcl_AddErrorInfo(3)

NAME

SYNOPSIS

ARGUMENTS

DESCRIPTION

SEE ALSO

KEYWORDS