plucky (3) Tcl_AddErrorInfo.3tcl.gz

Provided by: tcl9.0-doc_9.0.1+dfsg-1_all bug

NAME

       Tcl_GetReturnOptions,       Tcl_SetReturnOptions,       Tcl_AddErrorInfo,       Tcl_AppendObjToErrorInfo,
       Tcl_AddObjErrorInfo,   Tcl_SetObjErrorCode,   Tcl_SetErrorCode,    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)

       int
       Tcl_GetErrorLine(interp)

       Tcl_SetErrorLine(interp, lineNum)

       const char *
       Tcl_PosixError(interp)

       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.

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

       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  the  command  that  generated  the
                                              error; must point within the string given by script.

       Tcl_Size commandLength (in)            Number  of  bytes in command; a negative value means use all bytes
                                              up to the 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_EvalEx(interp, script, -1, 0);
              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.

       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.

REFERENCE COUNT MANAGEMENT

       The result of Tcl_GetReturnOptions will have at least one reference to it from the  Tcl  interpreter.  If
       not using it immediately, you should use Tcl_IncrRefCount to add your own reference.

       The  options  argument to Tcl_SetReturnOptions will have a reference added by the Tcl interpreter; it may
       safely be called with a zero-reference value.

       Tcl_AppendObjToErrorInfo only reads its objPtr argument; it does not modify its reference count at all.

       The errorObjPtr argument to Tcl_SetObjErrorCode will have a reference added by the  Tcl  interpreter;  it
       may safely be called with a zero-reference value.

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