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

Linux & Unix Commands - Search Man Pages

Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


Tcl_SetChannelError(3)		      Tcl Library Procedures		   Tcl_SetChannelError(3)

_________________________________________________________________________________________________

NAME
       Tcl_SetChannelError,  Tcl_SetChannelErrorInterp, Tcl_GetChannelError, Tcl_GetChannelError-
       Interp - 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, followed 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  arbi-
       trary  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 object 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 object goes up by one. Previously stored
       information will be discarded, by releasing the reference held  by  the	interpreter.  The
       interpreter reference must not be NULL.

       Tcl_GetChannelError  places either the error message held in the bypass area of the speci-
       fied channel into msgPtr, or NULL; and resets the bypass. I.e.  after  an  invocation  all
       following invocations will return NULL, until an intervening invocation of Tcl_SetChannel-
       Error 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 object.

       Tcl_GetChannelErrorInterp  places  either the error message held in the bypass area of the
       specified interpreter into msgPtr, or NULL; and resets the bypass. I.e. after  an  invoca-
       tion  all  following  invocations  will	return	NULL,  until an intervening invocation of
       Tcl_SetChannelErrorInterp with a non-NULL message. The msgPtr must not be NULL. The refer-
       ence  count  of	the  message is not touched.  The reference previously held by the inter-
       preter is now held by the caller of the function and it is its responsibility  to  release
       that reference when it is done with the object.

       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.  I.e.  when	these  functions are called the channel may now contain a
       stored arbitrary error message requiring processing by the caller.

       Tcl_StackChannel

       Tcl_Seek

       Tcl_Tell

       Tcl_ReadRaw

       Tcl_Read

       Tcl_ReadChars

       Tcl_Gets

       Tcl_GetsObj

       Tcl_Flush

       Tcl_WriteRaw

       Tcl_WriteObj

       Tcl_Write

       Tcl_WriteChars

       All other API functions are unchanged. Especially the  functions  below	leave  all  their
       error information in the interpreter result.

       Tcl_Close

       Tcl_UnregisterChannel

       Tcl_UnstackChannel

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

KEYWORDS
       channel driver, error messages, channel type

Tcl					       8.5			   Tcl_SetChannelError(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 02:01 AM.

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





Not a Forum Member?
Forgot Password?