AddErrInfo man page on DigitalUNIX

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
DigitalUNIX logo
[printable version]

Tcl_AddErrorInfo(3)	    Tcl Library Procedures	   Tcl_AddErrorInfo(3)


       Tcl_AddObjErrorInfo, Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_PosixError
       - record information about errors

       #include <tcl.h>

       Tcl_AddObjErrorInfo(interp, message, length)

       Tcl_AddErrorInfo(interp, message)

       Tcl_SetObjErrorCode(interp, errorObjPtr)

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

       char *

       Tcl_Interp   *interp    (in)	 Interpreter in which to record infor‐

       char	    *message   (in)	 For  Tcl_AddObjErrorInfo, this points
					 to the first  byte  of	 an  array  of
					 bytes	containing  a string to record
					 in the errorInfo variable.  This byte
					 array may contain embedded null bytes
					 unless	 length	 is   negative.	   For
					 Tcl_AddErrorInfo,  this  is a conven‐
					 tional C  string  to  record  in  the
					 errorInfo variable.

       int	    length     (in)	 The number of bytes to copy from mes‐
					 sage when setting the errorInfo vari‐
					 able.	 If  negative, all bytes up to
					 the first null byte are used.

       Tcl_Obj	    *errorObjPtr(in)	 This variable errorCode will  be  set
					 to this value.

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

       These  procedures  are used to manipulate two Tcl global variables that
       hold information about errors.  The variable 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 various
       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_EvalObj (or Tcl_Eval, which calls Tcl_EvalObj) it calls the	proce‐
       dure Tcl_AddObjErrorInfo 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 complete trace of the  activity  in  progress  when  the
       error occurred.

       It  is  sometimes  useful  to  add  additional information to errorInfo
       beyond what can be supplied automatically by  Tcl_EvalObj.   Tcl_AddOb‐
       jErrorInfo  may	be used for this purpose: its message and length argu‐
       ments describe an additional string to be appended to  errorInfo.   For
       example,	 the  source  command  calls Tcl_AddObjErrorInfo 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_AddObjErrorInfo  is	just after Tcl_EvalObj has returned TCL_ERROR.
       In calling Tcl_AddObjErrorInfo, you may	find  it  useful  to  use  the
       errorLine field of the interpreter (see the Tcl_Interp manual entry for

       Tcl_AddErrorInfo resembles Tcl_AddObjErrorInfo but differs in  initial‐
       izing  errorInfo	 from  the string value of the interpreter's result if
       the error is just starting to be logged.	 It does not use the result as
       a  Tcl  object so any embedded null characters in the result will cause
       information to be lost.	It also takes a conventional C string in  mes‐
       sage instead of Tcl_AddObjErrorInfo's counted string.

       The  procedure  Tcl_SetObjErrorCode  is used to set the errorCode vari‐
       able. errorObjPtr contains a list object built up by the caller. error‐
       Code  is	 set  to  this value. Tcl_SetObjErrorCode is typically invoked
       just before returning an error in an object command.  If	 an  error  is
       returned	 without  calling  Tcl_SetObjErrorCode or Tcl_SetErrorCode the
       Tcl interpreter automatically sets errorCode to NONE.

       The procedure Tcl_SetErrorCode is also used to set the errorCode	 vari‐
       able.  However,	it  takes  one or more strings to record instead of an
       object. Otherwise, it is similar to Tcl_SetObjErrorCode in behavior.

       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 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
       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 the interpreter's result.

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

       If  the procedure Tcl_ResetResult is called, it clears all of the state
       associated with errorInfo and errorCode (but 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.

       Tcl_DecrRefCount,   Tcl_IncrRefCount,   Tcl_Interp,    Tcl_ResetResult,

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

Tcl				      7.5		   Tcl_AddErrorInfo(3)

List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net