Tcl_GetChannelError man page on OpenMandriva

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

Tcl_SetChannelError(3)	    Tcl Library Procedures	Tcl_SetChannelError(3)

______________________________________________________________________________

NAME
       Tcl_SetChannelError,   Tcl_SetChannelErrorInterp,  Tcl_GetChannelError,
       Tcl_GetChannelErrorInterp - functions to create/intercept Tcl errors by
       channel drivers.

SYNOPSIS
       #include <tcl.h>

       void
       Tcl_SetChannelError(chan, msg)

       void
       Tcl_SetChannelErrorInterp(interp, msg)

       void
       Tcl_GetChannelError(chan, msgPtr)

       void
       Tcl_GetChannelErrorInterp(interp, msgPtr)

ARGUMENTS
       Tcl_Channel chan (in)	      Refers  to  the Tcl channel whose bypass
				      area is accessed.

       Tcl_Interp* interp (in)	      Refers  to  the  Tcl  interpreter	 whose
				      bypass area is accessed.

       Tcl_Obj* msg (in)	      Error  message put into a bypass area. A
				      list of return options and values,  fol‐
				      lowed  by a string message. Both message
				      and  the	option/value  information  are
				      optional.

       Tcl_Obj** msgPtr (out)	      Reference	 to  a place where the message
				      stored in the accessed bypass  area  can
				      be stored in.
_________________________________________________________________

DESCRIPTION
       The  current  definition	 of  a	Tcl channel driver does not permit the
       direct return of arbitrary error messages, except for the  setting  and
       retrieval  of  channel  options.	 All other functions are restricted to
       POSIX error codes.

       The functions described here overcome this limitation. Channel  drivers
       are allowed to use Tcl_SetChannelError and Tcl_SetChannelErrorInterp to
       place arbitrary error messages in bypass areas defined for channels and
       interpreters.  And  the	generic I/O layer uses Tcl_GetChannelError and
       Tcl_GetChannelErrorInterp to look for messages in the bypass areas  and
       arrange	for  their  return  as	errors. The POSIX error codes set by a
       driver are used now if and only if no messages are present.

       Tcl_SetChannelError stores error information in the bypass area of  the
       specified channel. The number of references to the msg value goes up by
       one. Previously stored information will be discarded, by releasing  the
       reference held by the channel. The channel reference must not be NULL.

       Tcl_SetChannelErrorInterp  stores  error information in the bypass area
       of the specified interpreter. The number of references to the msg value
       goes  up	 by  one.  Previously stored information will be discarded, by
       releasing the reference held by the interpreter. The interpreter refer‐
       ence must not be NULL.

       Tcl_GetChannelError  places either the error message held in the bypass
       area of the specified channel into msgPtr,  or  NULL;  and  resets  the
       bypass,	that  is,  after  an invocation all following invocations will
       return NULL, until an  intervening  invocation  of  Tcl_SetChannelError
       with  a	non-NULL  message.  The msgPtr must not be NULL. The reference
       count of the message is not touched.  The reference previously held  by
       the  channel  is	 now  held by the caller of the function and it is its
       responsibility to release that reference	 when  it  is  done  with  the
       value.

       Tcl_GetChannelErrorInterp  places  either the error message held in the
       bypass area of the specified interpreter	 into  msgPtr,	or  NULL;  and
       resets  the  bypass, that is, after an invocation all following invoca‐
       tions will return NULL, until an intervening invocation of Tcl_SetChan‐
       nelErrorInterp  with  a	non-NULL message. The msgPtr must not be NULL.
       The reference count of the message is not touched.  The reference  pre‐
       viously	held by the interpreter is now held by the caller of the func‐
       tion and it is its responsibility to release that reference when it  is
       done with the value.

       Which  functions	 of  a	channel driver are allowed to use which bypass
       function is listed below, as is which functions of the  public  channel
       API may leave a messages in the bypass areas.

       Tcl_DriverCloseProc
	      May use Tcl_SetChannelErrorInterp, and only this function.

       Tcl_DriverInputProc
	      May use Tcl_SetChannelError, and only this function.

       Tcl_DriverOutputProc
	      May use Tcl_SetChannelError, and only this function.

       Tcl_DriverSeekProc
	      May use Tcl_SetChannelError, and only this function.

       Tcl_DriverWideSeekProc
	      May use Tcl_SetChannelError, and only this function.

       Tcl_DriverSetOptionProc
	      Has  already  the ability to pass arbitrary error messages. Must
	      not use any of the new functions.

       Tcl_DriverGetOptionProc
	      Has already the ability to pass arbitrary error  messages.  Must
	      not use any of the new functions.

       Tcl_DriverWatchProc
	      Must  not use any of the new functions. Is internally called and
	      has no ability to return any type of error whatsoever.

       Tcl_DriverBlockModeProc
	      May use Tcl_SetChannelError, and only this function.

       Tcl_DriverGetHandleProc
	      Must not use any of the new functions. It is  only  a  low-level
	      function, and not used by Tcl commands.

       Tcl_DriverHandlerProc
	      Must  not use any of the new functions. Is internally called and
	      has no ability to return any type of error whatsoever.

       Given the information above the following public functions of the Tcl C
       API are affected by these changes; when these functions are called, the
       channel may now contain a stored arbitrary error message requiring pro‐
       cessing	    by	    the	     caller.	   Tcl_Flush	      Tcl_Get‐
       sObj	     Tcl_Gets Tcl_ReadChars	 Tcl_ReadRaw	      Tcl_Read
       Tcl_Seek		  Tcl_StackChannel     Tcl_Tell
       Tcl_WriteChars	  Tcl_WriteObj	       Tcl_WriteRaw Tcl_Write

       All other API functions are unchanged.  In  particular,	the  functions
       below  leave  all  their	 error	information in the interpreter result.
       Tcl_Close	  Tcl_UnstackChannel   Tcl_UnregisterChannel

SEE ALSO
       Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3)

KEYWORDS
       channel driver, error messages, channel type

Tcl				      8.5		Tcl_SetChannelError(3)
[top]

List of man pages available for OpenMandriva

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