Tcl_StackChannel(3)   Tcl Library Procedures  Tcl_StackChannel(3)



_________________________________________________________________

NAME
       Tcl_StackChannel,  Tcl_UnstackChannel, Tcl_GetStackedChan-
       nel, Tcl_GetTopChannel - stack an I/O channel  on  top  of
       another, and undo it

SYNOPSIS
       #include 

       Tcl_Channel
       Tcl_StackChannel(interp, typePtr, clientData, mask, channel)

       int
       Tcl_UnstackChannel(interp, channel)

       Tcl_Channel
       Tcl_GetStackedChannel(channel)

       Tcl_Channel
       Tcl_GetTopChannel(channel)


ARGUMENTS
       Tcl_Interp        *interp        (in)      Interpreter for
                                                  error reporting
                                                  -  can be NULL.

       Tcl_ChannelType   *typePtr       (in)      The new channel
                                                  I/O  procedures
                                                  to   use    for
                                                  channel.

       ClientData        clientData     (in)      Arbitrary  one-
                                                  word  value  to
                                                  pass to channel
                                                  I/O procedures.

       int               mask           (in)      Conditions
                                                  under     which
                                                  channel will be
                                                  used:     OR-ed
                                                  combination  of
                                                  TCL_READABLE,
                                                  TCL_WRITABLE
                                                  and  TCL_EXCEP-
                                                  TION.  This can
                                                  be a subset  of
                                                  the  operations
                                                  currently
                                                  allowed      on
                                                  channel.

       Tcl_Channel       channel        (in)      An existing Tcl
                                                  channel such as
                                                  returned     by
                                                  Tcl_CreateChan-
                                                  nel.
_________________________________________________________________


DESCRIPTION
       These functions are for use by extensions  that  add  pro-
       cessing layers to Tcl I/O channels.  Examples include com-
       pression and encryption modules.  These  functions  trans-
       parently  stack  and  unstack  a  new channel on top of an
       existing one.  Any  number  of  channels  can  be  stacked
       together.

       The  implementation  of the Tcl channel code was rewritten
       in 8.3.2 to correct some problems with the previous imple-
       mentation  with  regard to stacked channels.  Anyone using
       stacked  channels  or  creating  stacked  channel  drivers
       should  update  to the new TCL_CHANNEL_VERSION_2 Tcl_Chan-
       nelType structure.  See Tcl_CreateChannel for details.

       Tcl_StackChannel stacks a new channel on an existing chan-
       nel  with the same name that was registered for channel by
       Tcl_RegisterChannel.

       Tcl_StackChannel works by creating a new channel structure
       and  placing  itself  on  top  of  the channel stack.  EOL
       translation, encoding and  buffering  options  are  shared
       between  all  channels  in  the stack.  The hidden channel
       does no buffering, newline translations, or character  set
       encoding.   Instead,  the buffering, newline translations,
       and encoding functions all remain at the top of the  chan-
       nel  stack.  A pointer to the new top channel structure is
       returned.  If an error occurs when stacking  the  channel,
       NULL is returned instead.

       The  mask  parameter  specifies  the  operations  that are
       allowed on the new channel.  These can be a subset of  the
       operations  allowed on the original channel.  For example,
       a  read-write  channel  may  become  read-only  after  the
       Tcl_StackChannel call.

       Closing  a  channel  closes the channels stacked below it.
       The close of stacked channels is executed in  a  way  that
       allows buffered data to be properly flushed.

       Tcl_UnstackChannel  reverses the process.  The old channel
       is associated with the channel name,  and  the  processing
       module  added  by Tcl_StackChannel is destroyed.  If there
       is no old channel, then Tcl_UnstackChannel  is  equivalent
       to  Tcl_Close.  If an error occurs unstacking the channel,
       TCL_ERROR is returned, otherwise TCL_OK is returned.

       Tcl_GetTopChannel returns the top channel in the stack  of
       channels the supplied channel is part of.

       Tcl_GetStackedChannel  returns the channel in the stack of
       channels which is just below the supplied channel.


SEE ALSO
       Notifier(3), Tcl_CreateChannel(3), Tcl_OpenFileChannel(3),
       vwait(n).


KEYWORDS
       channel, compression



Tcl                            8.3            Tcl_StackChannel(3)