1 files changed, 52 insertions, 57 deletions
diff --git a/doc/ChnlStack.3 b/doc/ChnlStack.3
index 45fb277..b046cd2 100644
--- a/doc/ChnlStack.3
+++ b/doc/ChnlStack.3
@@ -1,16 +1,14 @@
 '\"
-'\" Copyright (c) 1999 Scriptics Corporation
+'\" 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.
-'\"
-'\" RCS: @(#) $Id: ChnlStack.3,v 1.2 2000/07/24 00:03:02 jenglish Exp $
+.TH Tcl_StackChannel 3 8.3 Tcl "Tcl Library Procedures"
 .so man.macros
-.TH Tcl_StackChannel 3 8.2 Tcl "Tcl Library Procedures"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-Tcl_StackChannel, Tcl_UnstackChannel, Tcl_GetStackedChannel \- stack an I/O channel on top of another, and undo it
+Tcl_StackChannel, Tcl_UnstackChannel, Tcl_GetStackedChannel, Tcl_GetTopChannel \- manipulate stacked I/O channels
 .SH SYNOPSIS
 .nf
 .nf
@@ -19,81 +17,78 @@ Tcl_StackChannel, Tcl_UnstackChannel, Tcl_GetStackedChannel \- stack an I/O chan
 Tcl_Channel
 \fBTcl_StackChannel\fR(\fIinterp, typePtr, clientData, mask, channel\fR)
 .sp
-void
+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
+.AS Tcl_ChannelType clientData
 .AP Tcl_Interp *interp in
-Interpreter for error reporting - can be NULL.
-.AP Tcl_ChannelType *typePtr in
-The new channel I/O procedures to use for \fIchannel\fP.
+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\fP.
+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.
+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
-\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.
+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
-\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.
-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. 
+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
-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_StackChannel\fR call.
+\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
-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.
+\fBTcl_GetTopChannel\fR returns the top channel in the stack of
+channels the supplied channel is part of.
 .PP
-\fBTcl_UnstackChannel\fP 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\fP 
-is equivalent to \fBTcl_Close\fP .
+\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).