TclStackChannel(3) Tcl Library Procedures TclStackChannel(3)

NAME
       TclStackChannel,  TclUnstackChannel,  TclGetStackedChannel, TclGet-
       TopChannel - stack an I/O channel on top of another, and undo it

SYNOPSIS
       ##iinncclluuddee <>

       TclChannel
       TTccllSSttaacckkCChhaannnneell(interp, typePtr, clientData, mask, channel)

       int
       TTccllUUnnssttaacckkCChhaannnneell(interp, channel)

       TclChannel
       TTccllGGeettSSttaacckkeeddCChhaannnneell(channel)

       TclChannel
       TTccllGGeettTTooppCChhaannnneell(channel)


AARRGGUUMMEENNTTSS
       TclInterp        *interp        (in)      Interpreter    for     error
                                                  reporting.

       TclChannelType   *typePtr       (in)      The  new  channel I/O proce-
                                                  dures to use for channel.

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

       int               mask           (in)      Conditions under which chan-
                                                  nel will be used: OR-ed com-
                                                  bination  of   TTCCLLRREEAADDAABBLLEE,
                                                  TTCCLLWWRRIITTAABBLLEE  and TTCCLLEEXXCCEEPP-
                                                  TTIIOONN.  This can be a  subset
                                                  of  the operations currently
                                                  allowed on channel.

       TclChannel       channel        (in)      An existing Tcl channel such
                                                  as  returned  by TTccllCCrreeaattee-
                                                  CChhaannnneell.



DESCRIPTION
       These functions are for use by extensions that add processing layers to
       Tcl I/O channels.  Examples include compression and encryption modules.
       These functions transparently 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 implementation with  regard  to
       stacked  channels.   Anyone  using stacked channels or creating stacked
       channel  drivers  should  update  to  the   new   TTCCLLCCHHAANNNNEELLVVEERRSSIIOONN22
       TTccllCChhaannnneellTTyyppee structure.  See TTccllCCrreeaatteeCChhaannnneell for details.

       TTccllSSttaacckkCChhaannnneell  stacks  a new channel on an existing channel with the
       same name that was registered for channel by TTccllRReeggiisstteerrCChhaannnneell.

       TTccllSSttaacckkCChhaannnneell 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 encod-
       ing functions all remain at the top of the channel 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 origi-
       nal  channel.   For  example, a read-write channel may become read-only
       after the TTccllSSttaacckkCChhaannnneell 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.

       TTccllUUnnssttaacckkCChhaannnneell reverses the process.  The old channel is associated
       with   the   channel   name,   and   the  processing  module  added  by
       TTccllSSttaacckkCChhaannnneell is destroyed.   If  there  is  no  old  channel,  then
       TTccllUUnnssttaacckkCChhaannnneell  is  equivalent  to  TTccllCClloossee.   If an error occurs
       unstacking the channel, TTCCLLEERRRROORR  is  returned,  otherwise  TTCCLLOOKK  is
       returned.

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

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


SEE ALSO
       Notifier(3), TclCreateChannel(3), TclOpenFileChannel(3), vwait(n).


KKEEYYWWOORRDDSS
       channel, compression



Tcl                                   8.3                  TclStackChannel(3)