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, 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
       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 reference 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 invocations will return NULL, until an intervening invocation of
       Tcl_SetChannelErrorInterp 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
       interpreter 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.

       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 processing by the caller.

              Tcl_Flush          Tcl_GetsObj          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(3tcl), Tcl_OpenFileChannel(3tcl), Tcl_SetErrno(3tcl)

KEYWORDS

       channel driver, error messages, channel type