Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


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


       Tcl_GetReturnOptions,  Tcl_SetReturnOptions,  Tcl_AddErrorInfo, Tcl_Ap-
       pendObjToErrorInfo,	Tcl_AddObjErrorInfo,	  Tcl_SetObjErrorCode,
       Tcl_SetErrorCode,  Tcl_SetErrorCodeVA,  Tcl_PosixError, Tcl_LogCommand-
       Info - retrieve or record information about errors and other return op-

       #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_LogCommandInfo(interp, script, command, commandLength)

       Tcl_Interp *interp (in)		      Interpreter  in  which to	record

       int	    code		      The code	returned  from	script

       Tcl_Obj	    *options		      A	dictionary of return options.

       char *message (in)		      For  Tcl_AddErrorInfo, this is a
					      conventional 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 -er-
					      rorinfo  return  option.	  This
					      byte  array may contain embedded
					      null bytes unless	length is neg-
					      ative.			       |

       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

       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	 (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

       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 |
       interpreter  following  a script	evaluation.  Routines such as Tcl_Eval |
       are called to evaluate a	script in an interpreter.  These routines  re- |
       turn  an	integer	completion code.  These	routines also leave in the in- |
       terpreter 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_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 completion code in agreement with	the -code  and |
       -level keys in options 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 al- |
       low  for	a more efficient alternative that meshes better	with the byte- |
       code compiler.)							       |

       Note that a newly created Tcl_Obj may be	passed in as the options argu- |
       ment without the	need to	tend to	any reference counting.	 This is anal- |
       ogous to	Tcl_SetObjResult.					       |

       While Tcl_SetReturnOptions provides a general interface to set any col- |
       lection	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-read-
       able.  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 additional 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 -er-
       rorinfo	value  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 the  -errorinfo
       value  beyond  what can be supplied automatically by the	script evalua-
       tion routines.  Tcl_AddErrorInfo	may be used for	this purpose: its mes-
       sage  argument 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.	 Like-
       wise,  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	 func- |
       tionality 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 -errorcode	return
       option to the list object errorObjPtr built up by the caller.   Tcl_Se-
       tObjErrorCode  is  typically invoked just before	returning an error. If
       an error	is returned without calling Tcl_SetObjErrorCode	or  Tcl_SetEr-
       rorCode	the  Tcl  interpreter automatically sets the -errorcode	return
       option to NONE.

       The procedure Tcl_SetErrorCode is also used to set the  -errorcode  re-
       turn 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_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 for-
       mat.  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  er-
       ror  (this  is  the same	value that will	appear as the third element in
       the -errorcode value).  It may be convenient to include this string  as
       part  of	 the  error  message returned to the application in the	inter-
       preter'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  in-
       ternally	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 writ-
       ten for older Tcl releases still	 access	 this  information  via	 those
       global variables.

       It  is  important to realize that while reading from those global vari-
       ables 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	empha-
       sized  in  this manual page that	it is important	to call	the procedures
       described here rather than setting errorInfo or errorCode directly with

       If  the procedure Tcl_ResetResult is called, it clears all of the state
       of the interpreter associated with script evaluation, including the en-
       tire return options dictionary.	In particular, the -errorinfo and -er-
       rorcode options are reset.  If an error had occurred, the  Tcl_ResetRe-
       sult  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.

       Tcl_DecrRefCount,   Tcl_IncrRefCount,   Tcl_Interp,    Tcl_ResetResult,

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

Tcl				      8.5		   Tcl_AddErrorInfo(3)


Want to link to this manual page? Use this URL:

home | help