Tcl_StackChannel replaces an existing channel with a new channel by the same name that was registered for channel with Tcl_RegisterChannel.
Tcl_StackChannel works by creating a new channel structure under the existing channel and pushing the existing channel functions down to the newly created channel. 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 channel stack. The top-most channel gets changed to use the I/O channel functions defined in typePtr, and the channel functions are passed the new clientData. The existing channel structure is modified in place, so C applications that continue to use channel will also see the effects of the new processing module. A pointer to a new channel structure is returned, although this new data structure is the one that has been pushed down below the top of the channel module stack. (This pointer can also be obtained with the Tcl_GetStackedChannel call.) 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 .
Copyright © 1999 Scriptics Corporation Copyright © 1995-1997 Roger E. Critchlow Jr.