NAME

       Tcl_AddErrorInfo,   Tcl_SetErrorCode,   Tcl_PosixError   -
       record information about errors

SYNOPSIS

       #include <tcl.h>

       Tcl_AddErrorInfo(interp, message)

       Tcl_SetErrorCode(interp, element, element, ... (char *) NULL)

       char *
       Tcl_PosixError(interp)

ARGUMENTS

       Tcl_Interp   *interp    (in)      Interpreter in which  to
                                         record information.

       char         *message   (in)      Identifying   string  to
                                         record   in    errorInfo
                                         variable.

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

DESCRIPTION

       These procedures are used to  manipulate  two  Tcl  global
       variables  that  hold information about errors.  The vari-
       able 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 vari-
       ous 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_Eval  it  calls  the procedure
       Tcl_AddErrorInfo  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 com-
       plete trace of the activity in  progress  when  the  error
       errorInfo beyond what can  be  supplied  automatically  by
       Tcl_Eval.   Tcl_AddErrorInfo may be used for this purpose:
       its message argument contains an additional string  to  be
       appended  to  errorInfo.   For example, the source command
       calls Tcl_AddErrorInfo 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_AddErrorInfo is just after  Tcl_Eval
       has  returned TCL_ERROR.  In calling Tcl_AddErrorInfo, you
       may find it useful to  use  the  errorLine  field  of  the
       interpreter (see the Tcl_Interp manual entry for details).

       The procedure Tcl_SetErrorCode is used to set  the  error-
       Code  variable.   Its  element  arguments give one or more
       strings to record in errorCode:  each element will  become
       one  item  of  a properly-formed Tcl list stored in error-
       Code.  Tcl_SetErrorCode is typically invoked  just  before
       returning an error.  If an error is returned without call-
       ing Tcl_SetErrorCode then the  Tcl  interpreter  automati-
       cally sets errorCode to NONE.

       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 plat-
       forms (e.g. Windows) where Tcl is linked into an  applica-
       tion  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 interp->result.

       It  is  important  to  call  the procedures described here
       rather than setting errorInfo or errorCode  directly  with
       Tcl_SetVar.   The  reason  for this is that the Tcl inter-
       preter keeps information about  whether  these  procedures
       have   been   called.    For   example,   the  first  time
       Tcl_AppendResult is called for an  error,  it  clears  the
       existing  value of errorInfo and adds the error message in
       interp->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 inter-
       preter to set errorCode to NONE if it  receives  an  error
       return when Tcl_SetErrorCode hasn't been called.

       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_Interp, Tcl_ResetResult, Tcl_SetErrno

KEYWORDS

       error, stack, trace, variable