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 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 specified 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_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 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 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 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(3tcl), Tcl_OpenFileChannel(3tcl), Tcl_SetErrno(3tcl)

KEYWORDS

       channel driver, error messages, channel type