* doc/ChnlStack.3:

	* doc/CrtChannel.3: updated the docs to be aware of the
	TCL_CHANNEL_VERSION_2 style of Tcl channels.


FossilOrigin-Name: a6a05b752c7c5fb5e3475085be75eff59916885a

2 files changed, 246 insertions, 90 deletions

diff --git a/doc/ChnlStack.3 b/doc/ChnlStack.3
index 2187b69..7c736e3 100644
--- a/doc/ChnlStack.3
+++ b/doc/ChnlStack.3
@@ -1,12 +1,12 @@
 '\"
-'\" 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.1.10.1 2000/08/07 21:29:37 hobbs Exp $
+'\" RCS: @(#) $Id: ChnlStack.3,v 1.1.10.2 2000/08/08 00:57:52 hobbs Exp $
 .so man.macros
-.TH Tcl_StackChannel 3 8.2 Tcl "Tcl Library Procedures"
+.TH Tcl_StackChannel 3 8.3 Tcl "Tcl Library Procedures"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -19,7 +19,7 @@ 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
@@ -43,57 +43,45 @@ 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 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
-\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 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
-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. 
+\fBTcl_StackChannel\fR stacks a new \fIchannel\fP on an existing channel
+with the same name that was registered for \fIchannel\fP by
+\fBTcl_RegisterChannel\fP.
 .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_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
-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.
+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.
 .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 .
+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\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.  If an error
+occurs unstacking the channel, \fBTCL_ERROR\fR is returned, otherwise
+\fBTCL_OK\fR is returned.
 
 .SH "SEE ALSO"
 Notifier(3), Tcl_CreateChannel(3), Tcl_OpenFileChannel(3), vwait(n).
diff --git a/doc/CrtChannel.3 b/doc/CrtChannel.3
index f95f653..6feeac3 100644
--- a/doc/CrtChannel.3
+++ b/doc/CrtChannel.3
@@ -1,16 +1,17 @@
 '\"
 '\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
+'\" Copyright (c) 1997-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: CrtChannel.3,v 1.5 2000/04/14 23:01:49 hobbs Exp $
+'\" RCS: @(#) $Id: CrtChannel.3,v 1.5.2.1 2000/08/08 00:57:52 hobbs Exp $
 .so man.macros
-.TH Tcl_CreateChannel 3 8.0 Tcl "Tcl Library Procedures"
+.TH Tcl_CreateChannel 3 8.3 Tcl "Tcl Library Procedures"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType, Tcl_GetChannelName, Tcl_GetChannelHandle, Tcl_GetChannelMode, Tcl_GetChannelBufferSize, Tcl_SetChannelBufferSize, Tcl_NotifyChannel, Tcl_BadChannelOption \- procedures for creating and manipulating channels
+Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType, Tcl_GetChannelName, Tcl_GetChannelHandle, Tcl_GetChannelMode, Tcl_GetChannelBufferSize, Tcl_SetChannelBufferSize, Tcl_NotifyChannel, Tcl_BadChannelOption, Tcl_ChannelName, Tcl_ChannelVersion, Tcl_ChannelBlockModeProc, Tcl_ChannelCloseProc, Tcl_ChannelClose2Proc, Tcl_ChannelInputProc, Tcl_ChannelOutputProc, Tcl_ChannelSeekProc, Tcl_ChannelSetOptionProc, Tcl_ChannelGetOptionProc, Tcl_ChannelWatchProc, Tcl_ChannelGetHandleProc, Tcl_ChannelFlushProc, Tcl_ChannelHandlerProc, \- procedures for creating and manipulating channels
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -26,22 +27,62 @@ Tcl_ChannelType *
 .sp
 char *
 \fBTcl_GetChannelName\fR(\fIchannel\fR)
-.VS
 .sp
 int
 \fBTcl_GetChannelHandle\fR(\fIchannel, direction, handlePtr\fR)
-.VE
 .sp
 int
 \fBTcl_GetChannelBufferSize\fR(\fIchannel\fR)
 .sp
 \fBTcl_SetChannelBufferSize\fR(\fIchannel, size\fR)
 .sp
-.VS
 \fBTcl_NotifyChannel\fR(\fIchannel, mask\fR)
 .sp
 int
 \fBTcl_BadChannelOption\fR(\fIinterp, optionName, optionList\fR)
+.VS 8.3.2
+.sp
+char *
+\fBTcl_ChannelName\fR(\fItypePtr\fR)
+.sp
+Tcl_ChannelTypeVersion
+\fBTcl_ChannelVersion\fR(\fItypePtr\fR)
+.sp
+Tcl_DriverBlockModeProc *
+\fBTcl_ChannelBlockModeProc\fR(\fItypePtr\fR)
+.sp
+Tcl_DriverCloseProc *
+\fBTcl_ChannelCloseProc\fR(\fItypePtr\fR)
+.sp
+Tcl_DriverClose2Proc *
+\fBTcl_ChannelClose2Proc\fR(\fItypePtr\fR)
+.sp
+Tcl_DriverInputProc *
+\fBTcl_ChannelInputProc\fR(\fItypePtr\fR)
+.sp
+Tcl_DriverOutputProc *
+\fBTcl_ChannelOutputProc\fR(\fItypePtr\fR)
+.sp
+Tcl_DriverSeekProc *
+\fBTcl_ChannelSeekProc\fR(\fItypePtr\fR)
+.sp
+Tcl_DriverSetOptionProc *
+\fBTcl_ChannelSetOptionProc\fR(\fItypePtr\fR)
+.sp
+Tcl_DriverGetOptionProc *
+\fBTcl_ChannelGetOptionProc\fR(\fItypePtr\fR)
+.sp
+Tcl_DriverWatchProc *
+\fBTcl_ChannelWatchProc\fR(\fItypePtr\fR)
+.sp
+Tcl_DriverGetHandleProc *
+\fBTcl_ChannelGetHandleProc\fR(\fItypePtr\fR)
+.sp
+Tcl_DriverFlushProc *
+\fBTcl_ChannelFlushProc\fR(\fItypePtr\fR)
+.sp
+Tcl_DriverHandlerProc *
+\fBTcl_ChannelHandlerProc\fR(\fItypePtr\fR)
 .VE
 .sp
 .SH ARGUMENTS
@@ -61,20 +102,17 @@ OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR to indicate
 whether a channel is readable and writable.
 .AP Tcl_Channel channel in
 The channel to operate on.
-.VS
 .AP int direction in
 \fBTCL_READABLE\fR means the input handle is wanted; \fBTCL_WRITABLE\fR
 means the output handle is wanted.
 .AP ClientData *handlePtr out
 Points to the location where the desired OS-specific handle should be
 stored.
-.VE
 .AP Tcl_EolTranslation transMode in
 The translation mode; one of the constants \fBTCL_TRANSLATE_AUTO\fR,
 \fBTCL_TRANSLATE_CR\fR, \fBTCL_TRANSLATE_LF\fR and \fBTCL_TRANSLATE_CRLF\fR.
 .AP int size in
 The size, in bytes, of buffers to allocate in this channel.
-.VS
 .AP int mask in
 An OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR
 and \fBTCL_EXCEPTION\fR that indicates events that have occurred on
@@ -87,7 +125,6 @@ Name of the invalid option.
 Specific options list (space separated words, without "-") 
 to append to the standard generic options list.
 Can be NULL for generic options error message only.
-.VE
 
 .BE
 
@@ -151,7 +188,6 @@ the same as the \fItypePtr\fR argument in the call to
 with the channel, or NULL if the \fIchannelName\fR argument to
 \fBTcl_CreateChannel\fR was NULL.
 .PP
-.VS
 \fBTcl_GetChannelHandle\fR places the OS-specific device handle
 associated with \fIchannel\fR for the given \fIdirection\fR in the
 location specified by \fIhandlePtr\fR and returns \fBTCL_OK\fR.  If
@@ -159,7 +195,6 @@ the channel does not have a device handle for the specified direction,
 then \fBTCL_ERROR\fR is returned instead.  Different channel drivers
 will return different types of handle.  Refer to the manual entries
 for each driver to determine what type of handle is returned.
-.VE
 .PP
 \fBTcl_GetChannelMode\fR returns an OR-ed combination of \fBTCL_READABLE\fR
 and \fBTCL_WRITABLE\fR, indicating whether the channel is open for input
@@ -177,31 +212,29 @@ allowing buffers of ten bytes to one million bytes. If \fIsize\fR is
 outside this range, \fBTcl_SetChannelBufferSize\fR sets the buffer size to
 4096.
 .PP
-.VS
 \fBTcl_NotifyChannel\fR is called by a channel driver to indicate to
 the generic layer that the events specified by \fImask\fR have
 occurred on the channel.  Channel drivers are responsible for invoking
 this function whenever the channel handlers need to be called for the
 channel.  See \fBWATCHPROC\fR below for more details.
-.VE
 .PP
-.VS
 \fBTcl_BadChannelOption\fR is called from driver specific set or get option
 procs to generate a complete error message.
-.VE
 
 .SH TCL_CHANNELTYPE
 .PP
 A channel driver provides a \fBTcl_ChannelType\fR structure that contains
 pointers to functions that implement the various operations on a channel;
-these operations are invoked as needed by the generic layer. The
-\fBTcl_ChannelType\fR structure contains the following fields:
+these operations are invoked as needed by the generic layer.  The structure
+was versioned starting in Tcl 8.3.2/8.4 to correct a problem with stacked
+channel drivers.  See the \fBOLD_CHANNEL\fR section below for details about
+the old structure.
 .PP
-.VS
+The \fBTcl_ChannelType\fR structure contains the following fields:
 .CS
 typedef struct Tcl_ChannelType {
 	char *\fItypeName\fR;
-	Tcl_DriverBlockModeProc *\fIblockModeProc\fR;	
+	Tcl_ChannelTypeVersion \fIversion\fR;
 	Tcl_DriverCloseProc *\fIcloseProc\fR;
 	Tcl_DriverInputProc *\fIinputProc\fR;
 	Tcl_DriverOutputProc *\fIoutputProc\fR;
@@ -211,24 +244,62 @@ typedef struct Tcl_ChannelType {
 	Tcl_DriverWatchProc *\fIwatchProc\fR;
 	Tcl_DriverGetHandleProc *\fIgetHandleProc\fR;
 	Tcl_DriverClose2Proc *\fIclose2Proc\fR;
+	Tcl_DriverBlockModeProc *\fIblockModeProc\fR;	
+	Tcl_DriverFlushProc *\fIflushProc\fR;	
+	Tcl_DriverHandlerProc *\fIhandlerProc\fR;	
 } Tcl_ChannelType;
 .CE
-.VE
 .PP
 The driver must provide implementations for all functions except
 \fIblockModeProc\fR, \fIseekProc\fR, \fIsetOptionProc\fR,
-.VS
 \fIgetOptionProc\fR, and \fIclose2Proc\fR, which may be specified as
-.VE
 NULL.  Other functions that can not be implemented for this type of
 device should return \fBEINVAL\fR when invoked to indicate that they
-are not implemented.
+are not implemented, except in the case of \fIflushProc\fR and
+\fIhandlerProc\fR, which should specified as NULL if not otherwise defined.
+.PP
+.VS 8.3.2
+The user should only use the above structure for \fBTcl_ChannelType\fR
+instantiation.  When referencing fields in a \fBTcl_ChannelType\fR
+structure, the following functions should be used to obtain the values:
+\fBTcl_ChannelName\fR, \fBTcl_ChannelVersion\fR,
+\fBTcl_ChannelBlockModeProc\fR, \fBTcl_ChannelCloseProc\fR,
+\fBTcl_ChannelClose2Proc\fR, \fBTcl_ChannelInputProc\fR,
+\fBTcl_ChannelOutputProc\fR, \fBTcl_ChannelSeekProc\fR,
+\fBTcl_ChannelSetOptionProc\fR, \fBTcl_ChannelGetOptionProc\fR,
+\fBTcl_ChannelWatchProc\fR, \fBTcl_ChannelGetHandleProc\fR,
+\fBTcl_ChannelFlushProc\fR, or \fBTcl_ChannelHandlerProc\fR.
+.PP
+The change to the structures was made in such a way that standard channel
+types are binary compatible.  However, channel types that use stacked
+channels (ie: TLS, Trf) have new versions to correspond to the above change
+since the previous code for stacked channels had problems.
+.VE
 
 .SH TYPENAME
 .PP
 The \fItypeName\fR field contains a null-terminated string that
 identifies the type of the device implemented by this driver, e.g.
 \fBfile\fR or \fBsocket\fR.
+.PP
+.VS 8.3.2
+This value can be retried with \fBTcl_ChannelName\fR, which returns
+a pointer to the string.
+.VE
+
+.VS 8.3.2
+.SH VERSION
+.PP
+The \fIversion\fR field should be set to \fBTCL_CHANNEL_VERSION_2\fR.
+If it is not set to this value \fBTCL_CHANNEL_VERSION_2\fR, then this
+\fBTcl_ChannelType\fR is assumed to have the older structure.  See
+\fBOLD_CHANNEL\fR for more details.  While Tcl will recognize and
+function with either structure, stacked channels must be of the newer
+style to function correctly.
+.PP
+This value can be retried with \fBTcl_ChannelVersion\fR, which returns
+either \fBTCL_CHANNEL_VERSION_2\fR or \fBTCL_CHANNEL_VERSION_1\fR.
+.VE
 
 .SH BLOCKMODEPROC
 .PP
@@ -255,6 +326,11 @@ nonblocking mode and to implement the blocking or nonblocking behavior.
 For some device types, the blocking and nonblocking behavior can be
 implemented by the underlying operating system; for other device types, the
 behavior must be emulated in the channel driver.
+.PP
+.VS 8.3.2
+This value can be retried with \fBTcl_ChannelBlockModeProc\fR, which returns
+a pointer to the function.
+.VE
 
 .SH "CLOSEPROC AND CLOSE2PROC"
 .PP
@@ -279,7 +355,6 @@ procedure should return zero; otherwise it should return a nonzero POSIX
 error code. In addition, if an error occurs and \fIinterp\fR is not NULL,
 the procedure should store an error message in the interpreter's result.
 .PP
-.VS
 Alternatively, channels that support closing the read and write sides
 independently may set \fIcloseProc\fR to \fBTCL_CLOSE2PROC\fR and set
 \fIclose2Proc\fR to the address of a function that matches the
@@ -306,6 +381,11 @@ return zero if the close operation was successful; otherwise it should
 return a nonzero POSIX error code. In addition, if an error occurs and
 \fIinterp\fR is not NULL, the procedure should store an error message
 in the interpreter's result.
+.PP
+.VS 8.3.2
+These value can be retried with \fBTcl_ChannelCloseProc\fR or
+\fBTcl_ChannelClose2Proc\fR, which returns a pointer to the respective
+function.
 .VE
 
 .SH INPUTPROC
@@ -349,6 +429,11 @@ whatsoever and the channel is in blocking mode, the function should block
 for the shortest possible time until at least one byte of data can be read
 from the device; then, it should return as much data as it can read without
 blocking.
+.PP
+.VS 8.3.2
+This value can be retried with \fBTcl_ChannelInputProc\fR, which returns
+a pointer to the function.
+.VE
 
 .SH OUTPUTPROC
 .PP
@@ -385,6 +470,11 @@ error, some data may have been written to the device.
 If the channel is nonblocking and the output device is unable to absorb any
 data whatsoever, the function should return -1 with an \fBEAGAIN\fR error
 without writing any data.
+.PP
+.VS 8.3.2
+This value can be retried with \fBTcl_ChannelOutputProc\fR, which returns
+a pointer to the function.
+.VE
 
 .SH SEEKPROC
 .PP
@@ -414,6 +504,11 @@ does not implement seeking.
 .PP
 The return value is the new access point or -1 in case of error. If an
 error occurred, the function should not move the access point.
+.PP
+.VS 8.3.2
+This value can be retried with \fBTcl_ChannelSeekProc\fR, which returns
+a pointer to the function.
+.VE
 
 .SH SETOPTIONPROC
 .PP
@@ -444,17 +539,20 @@ options.
 .PP
 If the option value is successfully modified to the new value, the function
 returns \fBTCL_OK\fR.
-.VS
 It should call \fBTcl_BadChannelOption\fR which itself returns
 \fBTCL_ERROR\fR if the \fIoptionName\fR is
 unrecognized. 
-.VE
 If \fIoptionValue\fR specifies a value for the option that
 is not supported or if a system call error occurs,
 the function should leave an error message in the
 \fIresult\fR field of \fIinterp\fR if \fIinterp\fR is not NULL. The
 function should also call \fBTcl_SetErrno\fR to store an appropriate POSIX
 error code.
+.PP
+.VS 8.3.2
+This value can be retried with \fBTcl_ChannelSetOptionProc\fR, which returns
+a pointer to the function.
+.VE
 
 .SH GETOPTIONPROC
 .PP
@@ -465,9 +563,7 @@ channel. \fIgetOptionProc\fR must match the following prototype:
 .CS
 typedef int Tcl_DriverGetOptionProc(
 	ClientData \fIinstanceData\fR,
-.VS
 	Tcl_Interp *\fIinterp\fR,
-.VE
 	char *\fIoptionName\fR,
 	Tcl_DString *\fIdsPtr\fR);
 .CE
@@ -478,7 +574,6 @@ value, as a string, in the Tcl dynamic string \fIdsPtr\fR.
 If \fIoptionName\fR is NULL, the function stores in \fIdsPtr\fR an
 alternating list of all supported options and their current values.
 On success, the function returns \fBTCL_OK\fR. 
-.VS
 It should call \fBTcl_BadChannelOption\fR which itself returns
 \fBTCL_ERROR\fR if the \fIoptionName\fR is
 unrecognized. If a system call error occurs,
@@ -486,7 +581,6 @@ the function should leave an error message in the
 \fIresult\fR field of \fIinterp\fR if \fIinterp\fR is not NULL. The
 function should also call \fBTcl_SetErrno\fR to store an appropriate POSIX
 error code.
-.VE
 .PP
 Some options are handled by the generic code and this function is never
 called to retrieve their value, e.g. \fB-blockmode\fR. Other options are
@@ -494,9 +588,13 @@ specific to each channel type and the \fIgetOptionProc\fR procedure of the
 channel driver will get called to implement them. The \fIgetOptionProc\fR
 field can be NULL, which indicates that this channel type supports no type
 specific options.
+.PP
+.VS 8.3.2
+This value can be retried with \fBTcl_ChannelGetOptionProc\fR, which returns
+a pointer to the function.
+.VE
 
 .SH WATCHPROC
-.VS
 .PP
 The \fIwatchProc\fR field contains the address of a function called
 by the generic layer to initialize the event notification mechanism to
@@ -508,7 +606,6 @@ typedef void Tcl_DriverWatchProc(
 	ClientData \fIinstanceData\fR,
 	int \fImask\fR);
 .CE
-.VE
 .PP
 The \fIinstanceData\fR is the same as the value passed to
 \fBTcl_CreateChannel\fR when this channel was created. The \fImask\fR
@@ -516,7 +613,6 @@ argument is an OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR
 and \fBTCL_EXCEPTION\fR; it indicates events the caller is interested in
 noticing on this channel.
 .PP
-.VS
 The function should initialize device type specific mechanisms to
 notice when an event of interest is present on the channel.  When one
 or more of the designated events occurs on the channel, the channel
@@ -527,6 +623,11 @@ Tcl_NotifyChannel too frequently.  Fairness can be insured by using
 the Tcl event queue to allow the channel event to be scheduled in sequence
 with other events.  See the description of \fBTcl_QueueEvent\fR for
 details on how to queue an event.
+.PP
+.VS 8.3.2
+This value can be retried with \fBTcl_ChannelWatchProc\fR, which returns
+a pointer to the function.
+.VE
 
 .SH GETHANDLEPROC
 .PP
@@ -541,7 +642,7 @@ typedef int Tcl_DriverGetHandleProc(
 	ClientData *\fIhandlePtr\fR);
 .CE
 .PP
-\fIInstanceData is the same as the value passed to
+\fIInstanceData\fR is the same as the value passed to
 \fBTcl_CreateChannel\fR when this channel was created. The \fIdirection\fR
 argument is either \fBTCL_READABLE\fR to retrieve the handle used
 for input, or \fBTCL_WRITABLE\fR to retrieve the handle used for
@@ -554,9 +655,50 @@ stored in the location referred to by \fIhandlePtr\fR, and
 \fBTCL_OK\fR should be returned.  If the channel is not open for the
 specified direction, or if the channel implementation does not use
 device handles, the function should return \fBTCL_ERROR\fR.
+.PP
+.VS 8.3.2
+This value can be retried with \fBTcl_ChannelGetHandleProc\fR, which returns
+a pointer to the function.
+.VE
+
+.VS 8.3.2
+.SH FLUSHPROC
+.PP
+The \fIflushProc\fR field is currently reserved for future use.
+It should be set to NULL.
+\fIFlushProc\fR should match the following prototype:
+.PP
+.CS
+typedef int Tcl_DriverFlushProc(
+	ClientData \fIinstanceData\fR);
+.CE
+.PP
+This value can be retried with \fBTcl_ChannelFlushProc\fR, which returns
+a pointer to the function.
+
+.SH HANDLERPROC
+.PP
+The \fIhandlerProc\fR field contains the address of a function called by
+the generic layer to notify the channel that an event occured.  It should
+be defined for stacked channel drivers that wish to be notified of events
+that occur on the underlying (stacked) channel.
+\fIHandlerProc\fR should match the following prototype:
+.PP
+.CS
+typedef int Tcl_DriverHandlerProc(
+	ClientData \fIinstanceData\fR,
+	int \fIinterestMask\fR);
+.CE
+.PP
+\fIInstanceData\fR is the same as the value passed to \fBTcl_CreateChannel\fR
+when this channel was created.  The \fIinterestMask\fR is an OR-ed
+combination of \fBTCL_READABLE\fR or \fBTCL_WRITABLE\fR; it indicates what
+type of event occured on this channel.
+.PP
+This value can be retried with \fBTcl_ChannelHandlerProc\fR, which returns
+a pointer to the function.
 .VE
 
-.VS
 .SH TCL_BADCHANNELOPTION
 .PP
 This procedure generates a "bad option" error message in an
@@ -579,14 +721,40 @@ so you get for instance:
     -peername, or -sockname
 when called with optionList="peername sockname"
 .CE
-"blah" is the optionName argument and "<specific options>"
+``blah'' is the optionName argument and ``<specific options>''
 is a space separated list of specific option words.
 The function takes good care of inserting minus signs before
-each option, commas after, and an "or" before the last option.
-.VE
+each option, commas after, and an ``or'' before the last option.
+
+.SH OLD_CHANNEL
+
+The original (8.3.1 and below) \fBTcl_ChannelType\fR structure contains
+the following fields:
+.PP
+.CS
+typedef struct Tcl_ChannelType {
+	char *\fItypeName\fR;
+	Tcl_DriverBlockModeProc *\fIblockModeProc\fR;	
+	Tcl_DriverCloseProc *\fIcloseProc\fR;
+	Tcl_DriverInputProc *\fIinputProc\fR;
+	Tcl_DriverOutputProc *\fIoutputProc\fR;
+	Tcl_DriverSeekProc *\fIseekProc\fR;
+	Tcl_DriverSetOptionProc *\fIsetOptionProc\fR;
+	Tcl_DriverGetOptionProc *\fIgetOptionProc\fR;
+	Tcl_DriverWatchProc *\fIwatchProc\fR;
+	Tcl_DriverGetHandleProc *\fIgetHandleProc\fR;
+	Tcl_DriverClose2Proc *\fIclose2Proc\fR;
+} Tcl_ChannelType;
+.CE
+.PP
+It is still possible to create channel with the above structure.  The
+internal channel code will determine the version.  It is imperative to use
+the new \fBTcl_ChannelType\fR structure if you are creating a stacked
+channel driver, due to problems with the earlier stacked channel
+implementation (in 8.2.0 to 8.3.1).
 
 .SH "SEE ALSO"
-Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3), Tcl_QueueEvent(3)
+Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3), Tcl_QueueEvent(3), Tcl_StackChannel(3)
 
 .SH KEYWORDS
 blocking, channel driver, channel registration, channel type, nonblocking