1Tcl_StackChannel(3)         Tcl Library Procedures         Tcl_StackChannel(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_StackChannel,  Tcl_UnstackChannel,  Tcl_GetStackedChannel, Tcl_Get‐
9       TopChannel - manipulate stacked I/O channels
10

SYNOPSIS

12       #include <tcl.h>
13
14       Tcl_Channel
15       Tcl_StackChannel(interp, typePtr, clientData, mask, channel)
16
17       int
18       Tcl_UnstackChannel(interp, channel)
19
20       Tcl_Channel
21       Tcl_GetStackedChannel(channel)
22
23       Tcl_Channel
24       Tcl_GetTopChannel(channel)
25
26

ARGUMENTS

28       Tcl_Interp *interp (in)                  Interpreter for error  report‐
29                                                ing.
30
31       Tcl_ChannelType *typePtr (in)            The new channel I/O procedures
32                                                to use for channel.
33
34       ClientData clientData (in)               Arbitrary  one-word  value  to
35                                                pass  to  channel  I/O  proce‐
36                                                dures.
37
38       int mask (in)                            Conditions under which channel
39                                                will  be  used: OR-ed combina‐
40                                                tion     of      TCL_READABLE,
41                                                TCL_WRITABLE   and  TCL_EXCEP‐
42                                                TION.  This can be a subset of
43                                                the    operations    currently
44                                                allowed on channel.
45
46       Tcl_Channel channel (in)                 An existing Tcl  channel  such
47                                                as returned by Tcl_CreateChan‐
48                                                nel.
49_________________________________________________________________
50
51

DESCRIPTION

53       These functions are for use by extensions that add processing layers to
54       Tcl I/O channels.  Examples include compression and encryption modules.
55       These functions transparently stack and unstack a new channel on top of
56       an existing one.  Any number of channels can be stacked together.
57
58       The  implementation  of  the Tcl channel code was rewritten in 8.3.2 to
59       correct some problems with the previous implementation with  regard  to
60       stacked  channels.   Anyone  using stacked channels or creating stacked
61       channel  drivers  should  update  to  the   new   TCL_CHANNEL_VERSION_2
62       Tcl_ChannelType structure.  See Tcl_CreateChannel for details.
63
64       Tcl_StackChannel  stacks  a new channel on an existing channel with the
65       same name that was registered for channel by Tcl_RegisterChannel.
66
67       Tcl_StackChannel works by creating a new channel structure and  placing
68       itself  on  top  of  the  channel stack.  EOL translation, encoding and
69       buffering options are shared between all channels in  the  stack.   The
70       hidden  channel  does  no buffering, newline translations, or character
71       set encoding.  Instead, the buffering, newline translations, and encod‐
72       ing functions all remain at the top of the channel stack.  A pointer to
73       the new top channel structure is returned.  If  an  error  occurs  when
74       stacking the channel, NULL is returned instead.
75
76       The mask parameter specifies the operations that are allowed on the new
77       channel.  These can be a subset of the operations allowed on the origi‐
78       nal  channel.   For  example, a read-write channel may become read-only
79       after the Tcl_StackChannel call.
80
81       Closing a channel closes the channels stacked below it.  The  close  of
82       stacked  channels  is executed in a way that allows buffered data to be
83       properly flushed.
84
85       Tcl_UnstackChannel reverses the process.  The old channel is associated
86       with   the   channel   name,   and   the  processing  module  added  by
87       Tcl_StackChannel is destroyed.   If  there  is  no  old  channel,  then
88       Tcl_UnstackChannel  is  equivalent  to  Tcl_Close.   If an error occurs
89       unstacking the channel, TCL_ERROR  is  returned,  otherwise  TCL_OK  is
90       returned.
91
92       Tcl_GetTopChannel  returns the top channel in the stack of channels the
93       supplied channel is part of.
94
95       Tcl_GetStackedChannel returns the channel  in  the  stack  of  channels
96       which is just below the supplied channel.
97
98

SEE ALSO

100       Notifier(3), Tcl_CreateChannel(3), Tcl_OpenFileChannel(3), vwait(n).
101
102

KEYWORDS

104       channel, compression
105
106
107
108Tcl                                   8.3                  Tcl_StackChannel(3)
Impressum