Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

CentOS 7.0 - man page for tcl_seterrorcodeva (centos section 3)

Tcl_AddErrorInfo(3)		      Tcl Library Procedures		      Tcl_AddErrorInfo(3)

_________________________________________________________________________________________________

NAME
       Tcl_GetReturnOptions,  Tcl_SetReturnOptions,  Tcl_AddErrorInfo,	Tcl_AppendObjToErrorInfo,
       Tcl_AddObjErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_Posix-
       Error,  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)

       Tcl_SetErrorCodeVA(interp, argList)

       const char *
       Tcl_PosixError(interp)

       void
       Tcl_LogCommandInfo(interp, script, command, commandLength)

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

       int	    code		      The code returned from script evaluation.

       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 -errorinfo  return  option.
					      This  byte  array  may  contain embedded null bytes
					      unless length is negative.			  |

       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 neg-
					      ative,  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 NULL.

       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  gener-
					      ated the error

       int commandLength (in)		      Number  of bytes in command; -1 means use all bytes
					      up to 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 interpreter fol- |
       lowing 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 |
       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 evalu- |
       ation 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_SetRe- |
       turnOptions 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 effi- |
       cient alternative that meshes better with the bytecode compiler.)			  |

       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  collection  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  com- |
       mand 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-readable.  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 -errorinfo 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 evaluation routines.  Tcl_AddErrorInfo may  be
       used  for this purpose: its message argument is an additional string to be appended to the
       -errorinfo option.  For example, when an error arises during the source command, the  pro-
       cedure  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  rou-
       tine  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	functionality  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 addi-
       tional 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_SetObjErrorCode 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 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  vari-
       able 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 format.  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 exten-
       sion. 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 the -errorcode value).  It may be conve-
       nient 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 informa-
       tion 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 informa-
       tion via those global variables.

       It is important to realize that while reading from those global variables remains  a  sup-
       ported  way to access these return option values, it is important not to assume that writ-
       ing to those global variables will properly set the corresponding return options.  It  has
       long  been  emphasized  in  this  manual  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 return options dictionary.  In
       particular, the -errorinfo and -errorcode options 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.

SEE ALSO
       Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_Interp, Tcl_ResetResult, Tcl_SetErrno

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

Tcl					       8.5			      Tcl_AddErrorInfo(3)


All times are GMT -4. The time now is 09:38 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password