manpagez: man pages & more
man Tcl_SetErrorCodeVA(3)
Home | html | info | man
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
                                              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(3), Tcl_IncrRefCount(3), Tcl_Interp(3),
       Tcl_ResetResult(3), Tcl_SetErrno(3), errorCode(n), errorInfo(n)


KEYWORDS

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

Tcl                                   8.5                  Tcl_AddErrorInfo(3)

tcl 8.6.14 - Generated Sun Mar 3 16:17:00 CST 2024
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.