import tcl 8.4.0

1 files changed, 188 insertions, 80 deletions

diff --git a/tcl/doc/CrtChannel.3 b/tcl/doc/CrtChannel.3
index 0030b7f61d4..45d043b816a 100644
--- a/tcl/doc/CrtChannel.3
+++ b/tcl/doc/CrtChannel.3
@@ -11,7 +11,7 @@
 .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, 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
+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_ChannelWideSeekProc, Tcl_ChannelSetOptionProc, Tcl_ChannelGetOptionProc, Tcl_ChannelWatchProc, Tcl_ChannelGetHandleProc, Tcl_ChannelFlushProc, Tcl_ChannelHandlerProc, Tcl_IsChannelShared, Tcl_IsChannelRegistered, Tcl_CutChannel, Tcl_SpliceChannel, Tcl_IsChannelExisting, Tcl_ClearChannelHandlers, Tcl_GetChannelThread, Tcl_ChannelBuffered \- procedures for creating and manipulating channels
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -25,12 +25,17 @@ ClientData
 Tcl_ChannelType *
 \fBTcl_GetChannelType\fR(\fIchannel\fR)
 .sp
-char *
+CONST char *
 \fBTcl_GetChannelName\fR(\fIchannel\fR)
 .sp
 int
 \fBTcl_GetChannelHandle\fR(\fIchannel, direction, handlePtr\fR)
 .sp
+.VS 8.4
+Tcl_ThreadId
+\fBTcl_GetChannelThread\fR(\fIchannel\fR)
+.VE 8.4
+.sp
 int
 \fBTcl_GetChannelBufferSize\fR(\fIchannel\fR)
 .sp
@@ -40,9 +45,31 @@ int
 .sp
 int
 \fBTcl_BadChannelOption\fR(\fIinterp, optionName, optionList\fR)
-.VS 8.3.2
+.VS 8.4
+.sp
+int
+\fBTcl_IsChannelShared\fR(\fIchannel\fR)
+.sp
+int
+\fBTcl_IsChannelRegistered\fR(\fIinterp, channel\fR)
+.sp
+int
+\fBTcl_IsChannelExisting\fR(\fIchannelName\fR)
 .sp
-char *
+void
+\fBTcl_CutChannel\fR(\fIchannel\fR)
+.sp
+void
+\fBTcl_SpliceChannel\fR(\fIchannel\fR)
+.sp
+void
+\fBTcl_ClearChannelHandlers\fR(\fIchannel\fR)
+.VE 8.4
+.sp
+int
+\fBTcl_ChannelBuffered\fR(\fIchannel\fR)
+.sp
+CONST char *
 \fBTcl_ChannelName\fR(\fItypePtr\fR)
 .sp
 Tcl_ChannelTypeVersion
@@ -66,6 +93,11 @@ Tcl_DriverOutputProc *
 Tcl_DriverSeekProc *
 \fBTcl_ChannelSeekProc\fR(\fItypePtr\fR)
 .sp
+.VS 8.4
+Tcl_DriverWideSeekProc *
+\fBTcl_ChannelWideSeekProc\fR(\fItypePtr\fR)
+.VE 8.4
+.sp
 Tcl_DriverSetOptionProc *
 \fBTcl_ChannelSetOptionProc\fR(\fItypePtr\fR)
 .sp
@@ -83,14 +115,13 @@ Tcl_DriverFlushProc *
 .sp
 Tcl_DriverHandlerProc *
 \fBTcl_ChannelHandlerProc\fR(\fItypePtr\fR)
-.VE
 .sp
 .SH ARGUMENTS
-.AS Tcl_EolTranslation *channelName in
+.AS Tcl_ChannelType *channelName in
 .AP Tcl_ChannelType *typePtr in
 Points to a structure containing the addresses of procedures that
 can be called to perform I/O and other functions on the channel.
-.AP char *channelName in
+.AP "CONST char" *channelName in
 The name of this channel, such as \fBfile3\fR; must not be in use
 by any other channel. Can be NULL, in which case the channel is
 created without a name.
@@ -108,9 +139,6 @@ means the output handle is wanted.
 .AP ClientData *handlePtr out
 Points to the location where the desired OS-specific handle should be
 stored.
-.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.
 .AP int mask in
@@ -119,9 +147,9 @@ and \fBTCL_EXCEPTION\fR that indicates events that have occurred on
 this channel.
 .AP Tcl_Interp *interp in
 Current interpreter. (can be NULL)
-.AP char *optionName in
+.AP "CONST char" *optionName in
 Name of the invalid option.
-.AP char *optionList in
+.AP "CONST char" *optionList in
 Specific options list (space separated words, without "-") 
 to append to the standard generic options list.
 Can be NULL for generic options error message only.
@@ -175,6 +203,15 @@ mode indicated by \fImask\fR.
 For a discussion of channel drivers, their operations and the
 \fBTcl_ChannelType\fR structure, see the section TCL_CHANNELTYPE, below.
 .PP
+\fBTcl_CreateChannel\fR interacts with the code managing the standard
+channels. Once a standard channel was initialized either through a
+call to \fBTcl_GetStdChannel\fR or a call to \fBTcl_SetStdChannel\fR
+closing this standard channel will cause the next call to
+\fBTcl_CreateChannel\fR to make the new channel the new standard
+channel too. See \fBTcl_StandardChannels\fR for a general treatise
+about standard channels and the behaviour of the Tcl library with
+regard to them.
+.PP
 \fBTcl_GetChannelInstanceData\fR returns the instance data associated with
 the channel in \fIchannel\fR. This is the same as the \fIinstanceData\fR
 argument in the call to \fBTcl_CreateChannel\fR that created this channel.
@@ -195,13 +232,19 @@ 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.
+.VS 8.4
+.PP
+\fBTcl_GetChannelThread\fR returns the id of the thread currently managing
+the specified \fIchannel\fR. This allows channel drivers to send their file
+events to the correct event queue even for a multi-threaded core.
+.VE 8.4
 .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
 and output.
 .PP
- \fBTcl_GetChannelBufferSize\fR returns the size, in bytes, of buffers
-allocated to store input or output in \fIchan\fR. If the value was not set
+\fBTcl_GetChannelBufferSize\fR returns the size, in bytes, of buffers
+allocated to store input or output in \fIchannel\fR. If the value was not set
 by a previous call to \fBTcl_SetChannelBufferSize\fR, described below, then
 the default value of 4096 is returned.
 .PP
@@ -220,6 +263,38 @@ channel.  See \fBWATCHPROC\fR below for more details.
 .PP
 \fBTcl_BadChannelOption\fR is called from driver specific set or get option
 procs to generate a complete error message.
+.PP
+\fBTcl_ChannelBuffered\fR returns the number of bytes of input
+currently buffered in the internal buffer (push back area) of the
+channel itself. It does not report about the data in the overall
+buffers for the stack of channels the supplied channel is part of.
+.PP
+.VS 8.4
+\fBTcl_IsChannelShared\fR checks the refcount of the specified
+\fIchannel\fR and returns whether the \fIchannel\fR was shared among
+multiple interpreters (result == 1) or not (result == 0).
+.PP
+\fBTcl_IsChannelRegistered\fR checks whether the specified \fIchannel\fR is
+registered in the given \fIinterp\fRreter (result == 1) or not
+(result == 0).
+.PP
+\fBTcl_IsChannelExisting\fR checks whether a channel with the specified
+name is registered in the (thread)-global list of all channels (result
+== 1) or not (result == 0).
+.PP
+\fBTcl_CutChannel\fR removes the specified \fIchannel\fR from the
+(thread)global list of all channels (of the current thread).
+Application to a channel still registered in some interpreter
+is not allowed.
+.PP
+\fBTcl_SpliceChannel\fR adds the specified \fIchannel\fR to the
+(thread)global list of all channels (of the current thread).
+Application to a channel registered in some interpreter is not allowed.
+.PP
+\fBTcl_ClearChannelHandlers\fR removes all channelhandlers and event
+scripts associated with the specified \fIchannel\fR, thus shutting
+down all event processing for this channel.
+.VE 8.4
 
 .SH TCL_CHANNELTYPE
 .PP
@@ -227,8 +302,8 @@ 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 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.
+channel drivers.  See the \fBOLD CHANNEL TYPES\fR section below for
+details about the old structure.
 .PP
 The \fBTcl_ChannelType\fR structure contains the following fields:
 .CS
@@ -247,6 +322,7 @@ typedef struct Tcl_ChannelType {
 	Tcl_DriverBlockModeProc *\fIblockModeProc\fR;	
 	Tcl_DriverFlushProc *\fIflushProc\fR;	
 	Tcl_DriverHandlerProc *\fIhandlerProc\fR;	
+	Tcl_DriverWideSeekProc *\fIwideSeekProc\fR;
 } Tcl_ChannelType;
 .CE
 .PP
@@ -258,7 +334,6 @@ device should return \fBEINVAL\fR when invoked to indicate that they
 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:
@@ -266,6 +341,9 @@ structure, the following functions should be used to obtain the values:
 \fBTcl_ChannelBlockModeProc\fR, \fBTcl_ChannelCloseProc\fR,
 \fBTcl_ChannelClose2Proc\fR, \fBTcl_ChannelInputProc\fR,
 \fBTcl_ChannelOutputProc\fR, \fBTcl_ChannelSeekProc\fR,
+.VS 8.4
+\fBTcl_ChannelWideSeekProc\fR,
+.VE 8.4
 \fBTcl_ChannelSetOptionProc\fR, \fBTcl_ChannelGetOptionProc\fR,
 \fBTcl_ChannelWatchProc\fR, \fBTcl_ChannelGetHandleProc\fR,
 \fBTcl_ChannelFlushProc\fR, or \fBTcl_ChannelHandlerProc\fR.
@@ -274,7 +352,6 @@ 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
@@ -282,24 +359,23 @@ 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
+This value can be retrieved 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
+If it is not set to this value \fBTCL_CHANNEL_VERSION_3\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
+\fBOLD CHANNEL TYPES\fR for more details.  While Tcl will recognize
+and function with either structure, stacked channels must be of at
+least \fBTCL_CHANNEL_VERSION_2\fR to function correctly.
+.PP
+This value can be retrieved with \fBTcl_ChannelVersion\fR, which returns
+.VS 8.4
+one of \fBTCL_CHANNEL_VERSION_3\fR,
+.VE 8.4
+\fBTCL_CHANNEL_VERSION_2\fR or \fBTCL_CHANNEL_VERSION_1\fR.
 
 .SH BLOCKMODEPROC
 .PP
@@ -327,10 +403,8 @@ 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
+This value can be retrieved with \fBTcl_ChannelBlockModeProc\fR, which returns
 a pointer to the function.
-.VE
 
 .SH "CLOSEPROC AND CLOSE2PROC"
 .PP
@@ -382,11 +456,9 @@ 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
+These value can be retrieved with \fBTcl_ChannelCloseProc\fR or
 \fBTcl_ChannelClose2Proc\fR, which returns a pointer to the respective
 function.
-.VE
 
 .SH INPUTPROC
 .PP
@@ -430,10 +502,8 @@ 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
+This value can be retrieved with \fBTcl_ChannelInputProc\fR, which returns
 a pointer to the function.
-.VE
 
 .SH OUTPUTPROC
 .PP
@@ -444,7 +514,7 @@ generic layer to transfer data from an internal buffer to the output device.
 .CS
 typedef int Tcl_DriverOutputProc(
 	ClientData \fIinstanceData\fR,
-	char *\fIbuf\fR,
+	CONST char *\fIbuf\fR,
 	int \fItoWrite\fR,
 	int *\fIerrorCodePtr\fR);
 .CE
@@ -471,12 +541,10 @@ 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
+This value can be retrieved with \fBTcl_ChannelOutputProc\fR, which returns
 a pointer to the function.
-.VE
 
-.SH SEEKPROC
+.SH "SEEKPROC AND WIDESEEKPROC"
 .PP
 The \fIseekProc\fR field contains the address of a function called by the
 generic layer to move the access point at which subsequent input or output
@@ -505,10 +573,32 @@ does not implement seeking.
 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
+.VS 8.4
+If there is a non-NULL \fIseekProc\fR field, the \fIwideSeekProc\fR
+field may contain the address of an alternative function to use which
+handles wide (i.e. larger than 32-bit) offsets, so allowing seeks
+within files larger than 2GB.  The \fIwideSeekProc\fR will be called
+in preference to the \fIseekProc\fR, but both must be defined if the
+\fIwideSeekProc\fR is defined.  \fIWideSeekProc\fR must match the
+following prototype:
+.PP
+.CS
+typedef Tcl_WideInt Tcl_DriverWideSeekProc(
+	ClientData \fIinstanceData\fR,
+	Tcl_WideInt \fIoffset\fR,
+	int \fIseekMode\fR,
+	int *\fIerrorCodePtr\fR);
+.CE
+.PP
+The arguments and return values mean the same thing as with
+\fIseekProc\fR above, except that the type of offsets and the return
+type are different.
+.PP
+The \fIseekProc\fR value can be retrieved with
+\fBTcl_ChannelSeekProc\fR, which returns a pointer to the function,
+and similarly the \fIwideSeekProc\fR can be retrieved with
+\fBTcl_ChannelWideSeekProc\fR.
+.VE 8.4
 
 .SH SETOPTIONPROC
 .PP
@@ -520,11 +610,11 @@ the generic layer to set a channel type specific option on a channel.
 typedef int Tcl_DriverSetOptionProc(
 	ClientData \fIinstanceData\fR,
 	Tcl_Interp *\fIinterp\fR,
-	char *\fIoptionName\fR,
-	char *\fIoptionValue\fR);
+	CONST char *\fIoptionName\fR,
+	CONST char *\fInewValue\fR);
 .CE
 .PP
-\fIoptionName\fR is the name of an option to set, and \fIoptionValue\fR is
+\fIoptionName\fR is the name of an option to set, and \fInewValue\fR is
 the new value for that option, as a string. The \fIinstanceData\fR is the
 same as the value given to \fBTcl_CreateChannel\fR when this channel was
 created. The function should do whatever channel type specific action is
@@ -542,17 +632,15 @@ returns \fBTCL_OK\fR.
 It should call \fBTcl_BadChannelOption\fR which itself returns
 \fBTCL_ERROR\fR if the \fIoptionName\fR is
 unrecognized. 
-If \fIoptionValue\fR specifies a value for the option that
+If \fInewValue\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
+This value can be retrieved with \fBTcl_ChannelSetOptionProc\fR, which returns
 a pointer to the function.
-.VE
 
 .SH GETOPTIONPROC
 .PP
@@ -564,21 +652,21 @@ channel. \fIgetOptionProc\fR must match the following prototype:
 typedef int Tcl_DriverGetOptionProc(
 	ClientData \fIinstanceData\fR,
 	Tcl_Interp *\fIinterp\fR,
-	char *\fIoptionName\fR,
-	Tcl_DString *\fIdsPtr\fR);
+	CONST char *\fIoptionName\fR,
+	Tcl_DString *\fIoptionValue\fR);
 .CE
 .PP
 \fIOptionName\fR is the name of an option supported by this type of
 channel. If the option name is not NULL, the function stores its current
-value, as a string, in the Tcl dynamic string \fIdsPtr\fR.
-If \fIoptionName\fR is NULL, the function stores in \fIdsPtr\fR an
+value, as a string, in the Tcl dynamic string \fIoptionValue\fR.
+If \fIoptionName\fR is NULL, the function stores in \fIoptionValue\fR an
 alternating list of all supported options and their current values.
 On success, the function returns \fBTCL_OK\fR. 
 It should call \fBTcl_BadChannelOption\fR which itself returns
 \fBTCL_ERROR\fR if the \fIoptionName\fR is
 unrecognized. 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
+result 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
@@ -589,10 +677,8 @@ 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
+This value can be retrieved with \fBTcl_ChannelGetOptionProc\fR, which returns
 a pointer to the function.
-.VE
 
 .SH WATCHPROC
 .PP
@@ -624,10 +710,8 @@ 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
+This value can be retrieved with \fBTcl_ChannelWatchProc\fR, which returns
 a pointer to the function.
-.VE
 
 .SH GETHANDLEPROC
 .PP
@@ -656,12 +740,9 @@ stored in the location referred to by \fIhandlePtr\fR, and
 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
+This value can be retrieved 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.
@@ -673,13 +754,13 @@ typedef int Tcl_DriverFlushProc(
 	ClientData \fIinstanceData\fR);
 .CE
 .PP
-This value can be retried with \fBTcl_ChannelFlushProc\fR, which returns
+This value can be retrieved 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
+the generic layer to notify the channel that an event occurred.  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:
@@ -693,11 +774,10 @@ typedef int Tcl_DriverHandlerProc(
 \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.
+type of event occurred on this channel.
 .PP
-This value can be retried with \fBTcl_ChannelHandlerProc\fR, which returns
+This value can be retrieved with \fBTcl_ChannelHandlerProc\fR, which returns
 a pointer to the function.
-.VE
 
 .SH TCL_BADCHANNELOPTION
 .PP
@@ -709,7 +789,7 @@ the generic options error message string.
 .PP
 It always return \fBTCL_ERROR\fR
 .PP
-An error message is generated in interp's result object to
+An error message is generated in \fIinterp\fR's result object to
 indicate that a command was invoked with the a bad option
 The message has the form
 .CS
@@ -719,14 +799,14 @@ so you get for instance:
     bad option "-blah": should be one of -blocking,
     -buffering, -buffersize, -eofchar, -translation,
     -peername, or -sockname
-when called with optionList="peername sockname"
+when called with \fIoptionList\fR="peername sockname"
 .CE
-``blah'' is the optionName argument and ``<specific options>''
+``blah'' is the \fIoptionName\fR 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.
 
-.SH OLD_CHANNEL
+.SH "OLD CHANNEL TYPES"
 
 The original (8.3.1 and below) \fBTcl_ChannelType\fR structure contains
 the following fields:
@@ -752,9 +832,37 @@ 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).
+.PP
+.VS 8.4
+Prior to 8.4.0 (i.e. during the later releases of 8.3 and early part
+of the 8.4 development cycle) the \fBTcl_ChannelType\fR structure
+contained the following fields:
+.PP
+.CS
+typedef struct Tcl_ChannelType {
+	char *\fItypeName\fR;
+	Tcl_ChannelTypeVersion \fIversion\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_DriverBlockModeProc *\fIblockModeProc\fR;	
+	Tcl_DriverFlushProc *\fIflushProc\fR;	
+	Tcl_DriverHandlerProc *\fIhandlerProc\fR;	
+} Tcl_ChannelType;
+.CE
+.PP
+When the above structure is registered as a channel type, the
+\fIversion\fR field should always be \fBTCL_CHANNEL_VERSION_2\fR.
+.VE 8.4
 
 .SH "SEE ALSO"
-Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3), Tcl_QueueEvent(3), Tcl_StackChannel(3)
+Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3), Tcl_QueueEvent(3), Tcl_StackChannel(3), Tcl_GetStdChannel(3)
 
 .SH KEYWORDS
 blocking, channel driver, channel registration, channel type, nonblocking