NAME
Tcl_StackChannel, Tcl_UnstackChannel, Tcl_GetStackedChan
nel - 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)
int
Tcl_UnstackChannel(interp, channel)
Tcl_Channel
Tcl_GetStackedChannel(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.
SEE ALSO
Notifier(3), Tcl_CreateChannel(3), Tcl_OpenFileChannel(3),
vwait(n).
channel, compression
Man(1) output converted with
man2html