Tcl_PosixError man page on UnixWare

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

Tcl_AddErrorInfo(3)	    Tcl Library Procedures	   Tcl_AddErrorInfo(3)

______________________________________________________________________________

NAME
       Tcl_AddObjErrorInfo,  Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_SetError‐
       CodeVA, Tcl_PosixError - record information about errors

SYNOPSIS
       #include <tcl.h>

       Tcl_AddObjErrorInfo(interp, message, length)

       Tcl_AddErrorInfo(interp, message)

       Tcl_SetObjErrorCode(interp, errorObjPtr)

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

       Tcl_SetErrorCodeVA(interp, argList)

       char *
       Tcl_PosixError(interp)

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

       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.

       va_list	    argList    (in)	 An argument list which must have been
					 initialised using  TCL_VARARGS_START,
					 and cleared using va_end.
_________________________________________________________________

DESCRIPTION
       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
       details).

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

SEE ALSO
       Tcl_DecrRefCount,    Tcl_IncrRefCount,	Tcl_Interp,   Tcl_ResetResult,
       Tcl_SetErrno

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

Tcl				      7.5		   Tcl_AddErrorInfo(3)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server UnixWare

List of man pages available for UnixWare

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]
Tweet
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