DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

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