Tcl_StackChannel(3)

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

SYNOPSIS
#include <tcl.h>

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

void
Tcl_UnstackChannel(interp, channel)

Tcl_Channel
Tcl_GetStackedChannel(channel)

ARGUMENTS
Interpreter for error reporting - can be NULL. The new channel I/O procedures to use for channel. Arbitrary one-word value to pass to channel I/O procedures. Conditions under which channel will be used: OR-ed combination of TCL_READABLE, TCL_WRITABLE and TCL_EXCEPTION. This can be a subset of the operations currently allowed on channel. An existing Tcl channel such as returned by Tcl_CreateChannel.

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.

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 .

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

KEYWORDS
channel, compression