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_SetErrorLine, Tcl_GetError-
       Line, Tcl_PosixError, Tcl_LogCommandInfo	- retrieve or record  informa-
       tion about errors and other return options

       #include	<tcl.h>

       Tcl_Obj *
       Tcl_GetReturnOptions(interp, code)

       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)


       Tcl_SetErrorLine(interp,	lineNum)

       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.

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

       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.

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

       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 <= 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 value.  As with any Tcl_Obj with	refer-
       ence 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_SetOb-
       jResult 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_DictObjGet(NULL, options,	key, &stackTrace);
		  /* 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 */
		  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.  The -errorline return option is also read
       by commands that	evaluate scripts and wish to supply detailed error lo-
       cation  information  in the stack trace text they append	to the -error-
       info 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-read-
       able.   The  -errorcode	option	holds a	Tcl list of items that are in-
       tended 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	 addi-
       tional  pieces of information 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
       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 value	errorObjPtr built up by	the caller.  Tcl_SetO-
       bjErrorCode  is typically invoked just before returning an error. If an
       error is	returned without calling Tcl_SetObjErrorCode or	 Tcl_SetError-
       Code  the  Tcl interpreter automatically	sets the -errorcode return op-
       tion 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
       a value.	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.
       Interfaces using	argument lists have been found to  be  nonportable  in
       practice.  This function	is deprecated and will be removed in Tcl 9.0.

       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_Ge-
       tReturnOptions.	 Likewise, Tcl_SetErrorLine sets the -errorline	return
       option value.

       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.

       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-ref-
       erence 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-ref-
       erence value.

       Tcl_DecrRefCount(3), Tcl_IncrRefCount(3),  Tcl_Interp(3),  Tcl_ResetRe-
       sult(3),	Tcl_SetErrno(3), errorCode(n), errorInfo(n)

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

Tcl				      8.5		   Tcl_AddErrorInfo(3)


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

home | help