home | help 
Tcl_AddErrorInfo(3)	     Tcl Library Procedures	     Tcl_AddErrorInfo(3)

________________________________________________________________________________

NAME
     Tcl_GetReturnOptions, Tcl_SetReturnOptions, Tcl_AddErrorInfo, Tcl_AppendOb-
     jToErrorInfo,  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 in-
					    formation.

     int	  code			    The code returned from script evalu-
					    ation.

     Tcl_Obj	  *options		    A dictionary of return options.

     const char *message (in)		    For Tcl_AddErrorInfo, this is a con-
					    ventional 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 nega-
					    tive.

     Tcl_Obj *objPtr (in)		    A message to be appended to the -er-
					    rorinfo 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 -er-
					    rorinfo 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 <=  com-
					    mand).

     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  nega-
					    tive 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 in-
     terpreter 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  re-
     trieves  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,  -er-
     rorcode,  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.  Other-
     wise, a completion code in agreement with the -code and -level keys in  op-
     tions 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  com-
     piler.)

     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 collec-
     tion 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 ma-
     chine-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 infor-
     mation 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  pro-
     cedure  Tcl_AddErrorInfo is called to add additional text to the -errorinfo
     value describing the command that was being executed  when  the  error  oc-
     curred.   By the time the error has been passed all the way back to the ap-
     plication, 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 argu-
     ment  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 function-
     ality 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  con-
     tain  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 op-
     tion to the list value errorObjPtr built up by the  caller.   Tcl_SetObjEr-
     rorCode 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_GetRe-
     turnOptions.   Likewise, Tcl_SetErrorLine sets the -errorline return option
     value.

     Tcl_PosixError sets the -errorcode variable after an error in a POSIX  ker-
     nel  call.  It reads the value of the errno C variable and calls Tcl_SetEr-
     rorCode to set the -errorcode return  option  in  the  POSIX  format.   The
     caller  must previously have called Tcl_SetErrno to set errno; this is nec-
     essary on some platforms (e.g. Windows) where Tcl is linked into an  appli-
     cation  as  a  shared  library,  or  when the error occurs in a dynamically
     loaded extension. See the manual entry for Tcl_SetErrno for  more	informa-
     tion.

     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  -er-
     rorcode 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 vari-
     ables.

     It is important to realize that while reading from those  global  variables
     remains  a supported way to access these return option values, it is impor-
     tant not to assume that writing to those global variables will properly set
     the corresponding return options.	It has long been emphasized in this man-
     ual 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 re-
     turn options dictionary.  In particular, the -errorinfo and -errorcode  op-
     tions  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(3),   Tcl_IncrRefCount(3),   Tcl_Interp(3),   Tcl_ResetRe-
     sult(3), Tcl_SetErrno(3), errorCode(n), errorInfo(n)

KEYWORDS
     error, value, value result, stack, trace, variable

Tcl				       8.5		     Tcl_AddErrorInfo(3)
home | help