98 lines
3.8 KiB
Groff
98 lines
3.8 KiB
Groff
|
'\"
|
||
|
|
'\" Copyright (c) 1999-2000 Ajuba Solutions.
|
||
|
|
'\"
|
||
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
||
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||
|
|
.TH Tcl_StackChannel 3 8.3 Tcl "Tcl Library Procedures"
|
||
|
|
.so man.macros
|
||
|
|
.BS
|
||
|
|
'\" Note: do not modify the .SH NAME line immediately below!
|
||
|
|
.SH NAME
|
||
|
|
Tcl_StackChannel, Tcl_UnstackChannel, Tcl_GetStackedChannel, Tcl_GetTopChannel \- manipulate stacked I/O channels
|
||
|
|
.SH SYNOPSIS
|
||
|
|
.nf
|
||
|
|
.nf
|
||
|
|
\fB#include <tcl.h>\fR
|
||
|
|
.sp
|
||
|
|
Tcl_Channel
|
||
|
|
\fBTcl_StackChannel\fR(\fIinterp, typePtr, clientData, mask, channel\fR)
|
||
|
|
.sp
|
||
|
|
int
|
||
|
|
\fBTcl_UnstackChannel\fR(\fIinterp, channel\fR)
|
||
|
|
.sp
|
||
|
|
Tcl_Channel
|
||
|
|
\fBTcl_GetStackedChannel\fR(\fIchannel\fR)
|
||
|
|
.sp
|
||
|
|
Tcl_Channel
|
||
|
|
\fBTcl_GetTopChannel\fR(\fIchannel\fR)
|
||
|
|
.sp
|
||
|
|
.SH ARGUMENTS
|
||
|
|
.AS Tcl_ChannelType clientData
|
||
|
|
.AP Tcl_Interp *interp in
|
||
|
|
Interpreter for error reporting.
|
||
|
|
.AP "const Tcl_ChannelType" *typePtr in
|
||
|
|
The new channel I/O procedures to use for \fIchannel\fR.
|
||
|
|
.AP ClientData clientData in
|
||
|
|
Arbitrary one-word value to pass to channel I/O procedures.
|
||
|
|
.AP int mask in
|
||
|
|
Conditions under which \fIchannel\fR will be used: OR-ed combination of
|
||
|
|
\fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR and \fBTCL_EXCEPTION\fR.
|
||
|
|
This can be a subset of the operations currently allowed on \fIchannel\fR.
|
||
|
|
.AP Tcl_Channel channel in
|
||
|
|
An existing Tcl channel such as returned by \fBTcl_CreateChannel\fR.
|
||
|
|
.BE
|
||
|
|
|
||
|
|
.SH DESCRIPTION
|
||
|
|
.PP
|
||
|
|
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.
|
||
|
|
.PP
|
||
|
|
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 \fBTCL_CHANNEL_VERSION_2\fR
|
||
|
|
\fBTcl_ChannelType\fR structure. See \fBTcl_CreateChannel\fR for details.
|
||
|
|
.PP
|
||
|
|
\fBTcl_StackChannel\fR stacks a new \fIchannel\fR on an existing channel
|
||
|
|
with the same name that was registered for \fIchannel\fR by
|
||
|
|
\fBTcl_RegisterChannel\fR.
|
||
|
|
.PP
|
||
|
|
\fBTcl_StackChannel\fR 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 channel stack. A pointer to the new top channel
|
||
|
|
structure is returned. If an error occurs when stacking the channel, NULL
|
||
|
|
is returned instead.
|
||
|
|
.PP
|
||
|
|
The \fImask\fR 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 \fBTcl_StackChannel\fR call.
|
||
|
|
.PP
|
||
|
|
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.
|
||
|
|
.PP
|
||
|
|
\fBTcl_UnstackChannel\fR reverses the process. The old channel is
|
||
|
|
associated with the channel name, and the processing module added by
|
||
|
|
\fBTcl_StackChannel\fR is destroyed. If there is no old channel, then
|
||
|
|
\fBTcl_UnstackChannel\fR is equivalent to \fBTcl_Close\fR. If an error
|
||
|
|
occurs unstacking the channel, \fBTCL_ERROR\fR is returned, otherwise
|
||
|
|
\fBTCL_OK\fR is returned.
|
||
|
|
.PP
|
||
|
|
\fBTcl_GetTopChannel\fR returns the top channel in the stack of
|
||
|
|
channels the supplied channel is part of.
|
||
|
|
.PP
|
||
|
|
\fBTcl_GetStackedChannel\fR returns the channel in the stack of
|
||
|
|
channels which is just below the supplied channel.
|
||
|
|
|
||
|
|
.SH "SEE ALSO"
|
||
|
|
Notifier(3), Tcl_CreateChannel(3), Tcl_OpenFileChannel(3), vwait(n).
|
||
|
|
|
||
|
|
.SH KEYWORDS
|
||
|
|
channel, compression
|