Seth Woolley's Man Viewer

Tcl_SetErrorCode(3) - Tcl_AddErrorInfo, Tcl_AddObjErrorInfo, Tcl_LogCommandInfo, Tcl_PosixError, Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_SetObjErrorCode - record information about errors - man 3 Tcl_SetErrorCode

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

Tcl_AddErrorInfo(3)         Tcl Library Procedures         Tcl_AddErrorInfo(3)



______________________________________________________________________________

NAME
       Tcl_AddObjErrorInfo,  Tcl_AddErrorInfo, Tcl_SetObjErrorCode, Tcl_SetEr-
       rorCode,  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(1,8))      Interpreter in(1,8) which to record infor-
                                         mation.

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

       int          length     (in(1,8))      The number of bytes to copy from mes-
                                         sage when setting the errorInfo vari-
                                         able.  If negative, all bytes  up  to
                                         the first null byte are used.

       Tcl_Obj      *errorObjPtr(in(1,8))     This  variable  errorCode will be set(7,n,1 builtins)
                                         to this value.

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

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

       CONST char   *script    (in(1,8))      Pointer to first character in(1,8)  script
                                         containing  command  (must be <= com-
                                         mand)

       CONST char   *command   (in(1,8))      Pointer to first character in(1,8) command
                                         that generated the error(8,n)

       int          commandLength(in(1,8))    Number  of bytes in(1,8) 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(3x,n,3x _nc_tracebits) of the operations that were in(1,8) progress when an  error(8,n)  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(1,8)  errorCode  identifies  the class of error(8,n) that occurred (e.g. POSIX
       means an error(8,n) occurred in(1,8) a POSIX system call) and additional elements
       in(1,8)  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(8,n) unwinds
       through the nested operations.  Each time(1,2,n) an error(8,n) 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(8,n) occurred.
       By the time(1,2,n) the error(8,n) has been passed all the way back to the  applica-
       tion, it will contain a complete trace(3x,n,3x _nc_tracebits) of the activity in(1,8) progress when
       the error(8,n) occurred.

       It is sometimes useful  to  add  additional  information  to  errorInfo
       beyond what can be supplied automatically by Tcl_EvalObjEx.  Tcl_AddOb-
       jErrorInfo may be used for this purpose: its message and  length  argu-
       ments  describe  an additional string(3,n) to be appended to errorInfo.  For
       example, the source command calls  Tcl_AddObjErrorInfo  to  record  the
       name of the file(1,n) being processed and the line number on which the error(8,n)
       occurred; for Tcl procedures, the procedure name and line number within
       the  procedure  are  recorded,  and  so  on.   The  best  time(1,2,n)  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(1,8) initial-
       izing errorInfo from the string(3,n) value of the  interpreter's  result  if(3,n)
       the error(8,n) is just starting to be logged.  It does not use the result as
       a Tcl object so any embedded null characters in(1,8) the result  will  cause
       information  to be lost.  It also takes a conventional C string(3,n) in(1,8) mes-
       sage instead of Tcl_AddObjErrorInfo's counted string.

       The procedure Tcl_SetObjErrorCode is used to set(7,n,1 builtins)  the  errorCode  vari-
       able. errorObjPtr contains a list object built up by the caller. error-
       Code is set(7,n,1 builtins) to this value.  Tcl_SetObjErrorCode  is  typically  invoked
       just  before  returning  an  error(8,n) in(1,8) an object command. If an error(8,n) 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(7,n,1 builtins) the errorCode vari-
       able. However, it takes one or more strings to  record  instead  of  an
       object. Otherwise, it is similar to Tcl_SetObjErrorCode in(1,8) 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(8,n)  in(1,8)  a  POSIX
       kernel  call.   It  reads  the  value of the errno C variable and calls
       Tcl_SetErrorCode to set(7,n,1 builtins) errorCode in(1,8) the POSIX format.  The caller must
       previously  have called Tcl_SetErrno to set(7,n,1 builtins) 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(8,n) occurs in(1,8) 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(8,n) (this is the same value that will appear as the third element  in(1,8)
       errorCode).  It may be convenient to include this string(3,n) as part of the
       error(8,n) message returned to the application in(1,8) the interpreter's  result.

       Tcl_LogCommandInfo  is invoked after an error(8,n) occurs in(1,8) an interpreter.
       It adds information about the command that was being executed when  the
       error(8,n)  occurred  to  the errorInfo variable, and the line number stored
       internally in(1,8) the interpreter is set.  On the first call to Tcl_LogCom-
       mandInfo or Tcl_AddObjErrorInfo since an error(8,n) occurred, the old infor-
       mation in(1,8) errorInfo is deleted.

       It is important to call the procedures described here rather than  set-
       ting  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(1,2,n)
       Tcl_AddObjErrorInfo is called for an  error(8,n),  it  clears  the  existing
       value  of  errorInfo  and  adds  the error(8,n) message in(1,8) the interpreter's
       result to the variable before appending message; in(1,8)  subsequent  calls,
       it  just  appends the new message.  When Tcl_SetErrorCode is called, it
       sets a flag indicating that errorCode has been set(7,n,1 builtins); this allows the Tcl
       interpreter  to  set(7,n,1 builtins)  errorCode  to NONE if(3,n) it receives an error(8,n) 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(8,n) had occurred, this will  clear(1,3x,3x clrtobot)  the  error(8,n)
       state to make it appear as if(3,n) no error(8,n) had occurred after all.


SEE ALSO
       Tcl_DecrRefCount,    Tcl_IncrRefCount,   Tcl_Interp,   Tcl_ResetResult,
       Tcl_SetErrno


KEYWORDS
       error(8,n), object, object result, stack, trace(3x,n,3x _nc_tracebits), variable



Tcl                                   8.0                  Tcl_AddErrorInfo(3)

References for this manual (incoming links)