Provided by: tcl8.6-doc_8.6.1-4ubuntu1_all 
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.
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.
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.
SEE ALSO
Tcl_DecrRefCount(3tcl), Tcl_IncrRefCount(3tcl), Tcl_Interp(3tcl), Tcl_ResetResult(3tcl),
Tcl_SetErrno(3tcl), errorCode(3tcl), errorInfo(3tcl)
KEYWORDS
error, value, value result, stack, trace, variable