NAME

       Tcl_AddObjErrorInfo,   Tcl_AddErrorInfo,   Tcl_SetObjErrorCode,   Tcl_SetErrorCode,   Tcl_SetErrorCodeVA,
       Tcl_PosixError, Tcl_LogCommandInfo - record information about errors

SYNOPSIS

       #include <tcl.h>

       Tcl_AddObjErrorInfo(interp, message, length)

       Tcl_AddErrorInfo(interp, message)

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

       char         *message   (in)      For Tcl_AddObjErrorInfo, this points to the first byte of an  array  of
                                         bytes  containing  a  string to record in the errorInfo variable.  This
                                         byte array may contain embedded null bytes unless length  is  negative.
                                         For  Tcl_AddErrorInfo, this is a conventional C string to record in the
                                         errorInfo variable.

       int          length     (in)      The number of bytes to copy from message  when  setting  the  errorInfo
                                         variable.  If negative, all bytes up to the first null byte are used.

       Tcl_Obj      *errorObjPtr(in)     This variable errorCode will be set to this value.

       char         *element   (in)      String  to  record  as one element of errorCode variable.  Last element
                                         argument must be NULL.

       va_list      argList    (in)      An   argument   list   which   must   have   been   initialized   using
                                         TCL_VARARGS_START, and cleared using va_end.

       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

       These procedures are used to manipulate two Tcl global variables that hold information about errors.  The
       variable errorInfo holds a stack trace of the operations that were in progress when  an  error  occurred,
       and  is intended to be human-readable.  The variable errorCode holds a list of items that are intended to
       be machine-readable.  The first item in errorCode identifies the class of error that occurred (e.g. POSIX
       means  an  error  occurred  in  a POSIX system call) and additional elements in errorCode hold additional
       pieces of information that depend on the class.  See the Tcl overview manual entry  for  details  on  the
       various formats for errorCode.

       The  errorInfo  variable  is  gradually built up as an error unwinds through the nested operations.  Each
       time an error code is returned to Tcl_EvalObjEx (or Tcl_Eval, which calls  Tcl_EvalObjEx)  it  calls  the
       procedure  Tcl_AddObjErrorInfo  to add additional text to errorInfo 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  errorInfo  beyond  what  can be supplied
       automatically by Tcl_EvalObjEx.  Tcl_AddObjErrorInfo may be used for this purpose: its message and length
       arguments  describe  an  additional  string to be appended to errorInfo.  For example, the source command
       calls Tcl_AddObjErrorInfo to record the name of the file being processed and the line number on which the
       error occurred; for Tcl procedures, the procedure name and line number within the procedure are recorded,
       and so on.  The best time to call Tcl_AddObjErrorInfo is just after Tcl_EvalObjEx has returned TCL_ERROR.
       In calling Tcl_AddObjErrorInfo, you may find it useful to use the errorLine field of the interpreter (see
       the Tcl_Interp manual entry for details).

       Tcl_AddErrorInfo resembles Tcl_AddObjErrorInfo but differs in  initializing  errorInfo  from  the  string
       value of the interpreter's result if the error is just starting to be logged.  It does not use the result
       as a Tcl object so any embedded null characters in the result will cause information to be lost.  It also
       takes a conventional C string in message instead of Tcl_AddObjErrorInfo's counted string.

       The  procedure  Tcl_SetObjErrorCode  is  used  to set the errorCode variable. errorObjPtr contains a list
       object built up by the caller. errorCode is set to this value. Tcl_SetObjErrorCode is  typically  invoked
       just  before  returning  an  error  in  an  object  command.  If  an  error  is  returned without calling
       Tcl_SetObjErrorCode or Tcl_SetErrorCode the Tcl interpreter automatically sets errorCode to NONE.

       The procedure Tcl_SetErrorCode is also used to set the errorCode variable. 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_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 errorCode 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 errorCode).  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 variable, and the line number
       stored  internally  in  the  interpreter  is  set.   On  the  first   call   to   Tcl_LogCommandInfo   or
       Tcl_AddObjErrorInfo since an error occurred, the old information in errorInfo is deleted.

       It is important to call the procedures described here rather than setting errorInfo or errorCode directly
       with Tcl_ObjSetVar2.  The reason for this is that the Tcl interpreter  keeps  information  about  whether
       these  procedures  have  been  called.   For example, the first time Tcl_AddObjErrorInfo is called for an
       error, it clears the existing value of errorInfo and adds the error message in the  interpreter's  result
       to  the  variable  before  appending message; in subsequent calls, it just appends the new message.  When
       Tcl_SetErrorCode is called, it sets a flag indicating that errorCode has been set; this  allows  the  Tcl
       interpreter  to  set  errorCode  to NONE if it receives an error return when Tcl_SetErrorCode hasn't been
       called.

       If the procedure Tcl_ResetResult is called, it clears all of the  state  associated  with  errorInfo  and
       errorCode  (but it doesn't actually modify the variables).  If an error had occurred, this will clear the
       error state to make it appear as if no error had occurred after all.

SEE ALSO

       Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_Interp, Tcl_ResetResult, Tcl_SetErrno

KEYWORDS

       error, object, object result, stack, trace, variable