summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--doc/ChnlStack.3 (renamed from doc/ChnlReplace.3)69
1 files changed, 38 insertions, 31 deletions
diff --git a/doc/ChnlReplace.3 b/doc/ChnlStack.3
index 3c56cb3..2d9c2ec 100644
--- a/doc/ChnlReplace.3
+++ b/doc/ChnlStack.3
@@ -4,28 +4,31 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: ChnlReplace.3,v 1.3 1999/06/30 17:46:51 welch Exp $
+'\" RCS: @(#) $Id: ChnlStack.3,v 1.1 1999/07/02 19:51:14 welch Exp $
.so man.macros
-.TH Tcl_ReplaceChannel 3 8.2 Tcl "Tcl Library Procedures"
+.TH Tcl_StackChannel 3 8.2 Tcl "Tcl Library Procedures"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
-Tcl_ReplaceChannel, Tcl_UndoReplaceChannel \- stack an I/O channel on top of another, and undo it
+Tcl_StackChannel, Tcl_UnstackChannel \- stack an I/O channel on top of another, and undo it
.SH SYNOPSIS
.nf
.nf
\fB#include <tcl.h>\fR
.sp
Tcl_Channel
-\fBTcl_ReplaceChannel\fR(\fIinterp, typePtr, clientData, mask, channel\fR)
+\fBTcl_StackChannel\fR(\fIinterp, typePtr, clientData, mask, channel\fR)
.sp
void
-\fBTcl_UndoReplaceChannel\fR(\fIinterp, channel\fR)
+\fBTcl_UnstackChannel\fR(\fIinterp, channel\fR)
+.sp
+Tcl_Channel
+\fBTcl_GetStackedChannel\fR(\fIchannel\fR)
.sp
.SH ARGUMENTS
.AS Tcl_ChannelType
.AP Tcl_Interp *interp in
-The Tcl interpreter in which \fIchannel\fP is registered.
+Interpreter for error reporting - can be NULL.
.AP Tcl_ChannelType *typePtr in
The new channel I/O procedures to use for \fIchannel\fP.
.AP ClientData clientData in
@@ -41,51 +44,55 @@ An existing Tcl channel such as returned by \fBTcl_CreateChannel\fR.
.SH DESCRIPTION
.PP
These functions are for use by extensions that add processing
-layers on top of Tcl I/O channels. Examples include compression
+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
-\fBTcl_ReplaceChannel\fR
+\fBTcl_StackChannel\fR
replaces an existing \fIchannel\fP with a new channel by
the same name that was registered for \fIchannel\fP
with \fBTcl_RegisterChannel\fP.
-Because the channel name is the same, all Tcl-level I/O
-operations will automatically use the new channel instead
-of the old one.
-The new channel uses the I/O channel functions
+.PP
+\fBTcl_StackChannel\fR
+works by creating a new channel structure under the existing
+\fIchannel\fP 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 \fItypePtr\fP, and the channel functions are passed
the new \fIclientData\fP.
-A pointer to the new channel structure is returned.
-If an error occurs when creating the new channel,
+The existing \fIchannel\fP structure is modified in place,
+so C applications that continue to use \fIchannel\fP 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
+\fBTcl_GetStackedChannel\fP call.)
+If an error occurs when stacking the channel,
NULL is returned instead.
.PP
The \fImask\fP 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_ReplaceChannel\fR call.
-.PP
-The old Tcl_Channel data structure
-is linked to the new channel
-using the \fBsupercedes\fP structure member of the
-Tcl_Channel that is returned by
-\fBTcl_ReplaceChannel\fR.
-The new channel functions
-should use the standard channel APIs like
-\fBTcl_Read\fP, \fBTcl_ReadChars\fP and \fBTcl_Write\fP
-to get at the underlying channel instead of
-accessing the other channel data structure directly.
+read-only after the \fBTcl_StackChannel\fR call.
.PP
-Closing the new channel closes the channels stacked below it.
+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_UndoReplaceChannel\fP reverses the process.
+\fBTcl_UnstackChannel\fP reverses the process.
The old channel is associated with the channel name,
-and the new channel created by
-\fBTcl_ReplaceChannel\fR is destroyed.
-If there is no old channel, then \fBTcl_UndoReplaceChannel\fP
+and the processing module added by
+\fBTcl_StackChannel\fR is destroyed.
+If there is no old channel, then \fBTcl_UnstackChannel\fP
is equivalent to \fBTcl_Close\fP .
.SH "SEE ALSO"