Tcl_PosixError man page on BSDi

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



Tcl_AddErrorInfo(3)   Tcl Library Procedures  Tcl_AddErrorInfo(3)

_________________________________________________________________

NAME
       Tcl_AddErrorInfo,   Tcl_SetErrorCode,   Tcl_PosixError	-
       record information about errors

SYNOPSIS
       #include <tcl.h>

       Tcl_AddErrorInfo(interp, message)

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

       char *
       Tcl_PosixError(interp)

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

       char	    *message   (in)	 Identifying   string  to
					 record	  in	errorInfo
					 variable.

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

DESCRIPTION
       These procedures are used to  manipulate	 two  Tcl  global
       variables  that	hold information about errors.	The vari-
       able 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 vari-
       ous 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_Eval	 it  calls  the procedure
       Tcl_AddErrorInfo	 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 com-
       plete trace of the activity in  progress	 when  the  error
       occurred.

Tcl			       7.5				1

Tcl_AddErrorInfo(3)   Tcl Library Procedures  Tcl_AddErrorInfo(3)

       It  is  sometimes  useful to add additional information to
       errorInfo beyond what can  be  supplied	automatically  by
       Tcl_Eval.   Tcl_AddErrorInfo may be used for this purpose:
       its message argument contains an additional string  to  be
       appended	 to  errorInfo.	  For example, the source command
       calls Tcl_AddErrorInfo 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_AddErrorInfo is just after	 Tcl_Eval
       has  returned TCL_ERROR.	 In calling Tcl_AddErrorInfo, you
       may find it useful to  use  the	errorLine  field  of  the
       interpreter (see the Tcl_Interp manual entry for details).

       The procedure Tcl_SetErrorCode is used to set  the  error-
       Code  variable.	 Its  element  arguments give one or more
       strings to record in errorCode:	each element will  become
       one  item  of  a properly-formed Tcl list stored in error-
       Code.  Tcl_SetErrorCode is typically invoked  just  before
       returning an error.  If an error is returned without call-
       ing Tcl_SetErrorCode then the  Tcl  interpreter	automati-
       cally sets errorCode to NONE.

       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 plat-
       forms (e.g. Windows) where Tcl is linked into an	 applica-
       tion  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 interp->result.

       It  is  important  to  call  the procedures described here
       rather than setting errorInfo or errorCode  directly  with
       Tcl_SetVar.   The  reason  for this is that the Tcl inter-
       preter keeps information about  whether	these  procedures
       have  been called.  For example, the first time Tcl_Appen-
       dResult is called for an error,	it  clears  the	 existing
       value   of   errorInfo  and  adds  the  error  message  in
       interp->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 inter-
       preter 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

Tcl			       7.5				2

Tcl_AddErrorInfo(3)   Tcl Library Procedures  Tcl_AddErrorInfo(3)

       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_Interp, Tcl_ResetResult, Tcl_SetErrno

KEYWORDS
       error, stack, trace, variable

Tcl			       7.5				3

[top]

List of man pages available for BSDi

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