* Updated APIs in the file generic/tclIO.c according to the guidelines

        of TIP 27.  Several minor documentation corrections as well.

	* Updated channel driver interface according to the guidelines of
	TIP 27.  See also [Bug 500348].

	* Moved Tcl_EolTranslation enum declaration from generic/tcl.h to
        generic/tclInt.h (renamed to TclEolTranslation).  It is not used
        anywhere in Tcl's public interface.

2 files changed, 57 insertions, 62 deletions

diff --git a/doc/CrtChannel.3 b/doc/CrtChannel.3
index 3ca35b5..1f809bc 100644
--- a/doc/CrtChannel.3
+++ b/doc/CrtChannel.3
@@ -5,7 +5,7 @@
 '\" 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.12 2001/12/10 15:50:46 dgp Exp $
+'\" RCS: @(#) $Id: CrtChannel.3,v 1.13 2002/01/15 17:55:29 dgp Exp $
 .so man.macros
 .TH Tcl_CreateChannel 3 8.3 Tcl "Tcl Library Procedures"
 .BS
@@ -25,7 +25,7 @@ ClientData
 Tcl_ChannelType *
 \fBTcl_GetChannelType\fR(\fIchannel\fR)
 .sp
-char *
+CONST char *
 \fBTcl_GetChannelName\fR(\fIchannel\fR)
 .sp
 int
@@ -73,7 +73,7 @@ int
 Tcl_Channel
 \fBTcl_GetTopChannel\fR(\fIchannel\fR)
 .sp
-char *
+CONST char *
 \fBTcl_ChannelName\fR(\fItypePtr\fR)
 .sp
 Tcl_ChannelTypeVersion
@@ -117,11 +117,11 @@ Tcl_DriverHandlerProc *
 .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.
@@ -139,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
@@ -150,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.
@@ -247,7 +244,7 @@ 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
+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
@@ -301,7 +298,7 @@ is not allowed.
 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 \fIchannels\fR, thus shutting
+scripts associated with the specified \fIchannel\fR, thus shutting
 down all event processing for this channel.
 .VE
 
@@ -528,7 +525,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
@@ -604,11 +601,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
@@ -626,7 +623,7 @@ 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
@@ -648,21 +645,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
@@ -793,7 +790,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
@@ -803,9 +800,9 @@ 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.
diff --git a/doc/OpenFileChnl.3 b/doc/OpenFileChnl.3
index d778007..c694c45 100644
--- a/doc/OpenFileChnl.3
+++ b/doc/OpenFileChnl.3
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-'\" RCS: @(#) $Id: OpenFileChnl.3,v 1.15 2001/12/10 15:50:46 dgp Exp $
+'\" RCS: @(#) $Id: OpenFileChnl.3,v 1.16 2002/01/15 17:55:29 dgp Exp $
 .so man.macros
 .TH Tcl_OpenFileChannel 3 8.3 Tcl "Tcl Library Procedures"
 .BS
@@ -15,8 +15,6 @@ Tcl_OpenFileChannel, Tcl_OpenCommandChannel, Tcl_MakeFileChannel, Tcl_GetChannel
 .nf
 \fB#include <tcl.h>\fR
 .sp
-typedef ... Tcl_Channel;
-.sp
 Tcl_Channel
 \fBTcl_OpenFileChannel\fR(\fIinterp, fileName, mode, permissions\fR)
 .sp
@@ -57,7 +55,7 @@ int
 \fBTcl_ReadChars\fR(\fIchannel, readObjPtr, charsToRead, appendFlag\fR)
 .sp
 int
-\fBTcl_Read\fR(\fIchannel, byteBuf, bytesToRead\fR)
+\fBTcl_Read\fR(\fIchannel, readBuf, bytesToRead\fR)
 .sp
 int
 \fBTcl_GetsObj\fR(\fIchannel, lineObjPtr\fR)
@@ -80,10 +78,10 @@ int
 .VS 8.3.2
 .sp
 int
-\fBTcl_ReadRaw\fR(\fIchannel, bufPtr, bytesToRead\fR)
+\fBTcl_ReadRaw\fR(\fIchannel, readBuf, bytesToRead\fR)
 .sp
 int
-\fBTcl_WriteRaw\fR(\fIchannel, bufPtr, bytesToWrite\fR)
+\fBTcl_WriteRaw\fR(\fIchannel, byteBuf, bytesToWrite\fR)
 .VE
 .sp
 int
@@ -123,8 +121,7 @@ Used for error reporting and to look up a channel registered in it.
 The name of a local or network file.
 .AP char *mode in
 Specifies how the file is to be accessed.  May have any of the values
-allowed for the \fImode\fR argument to the Tcl \fBopen\fR command.  For
-\fBTcl_OpenCommandChannel\fR, may be NULL.
+allowed for the \fImode\fR argument to the Tcl \fBopen\fR command.  
 .AP int permissions in
 POSIX-style permission flags such as 0644.  If a new file is created, these
 permissions will be set on the created file.
@@ -149,12 +146,16 @@ file descriptor, for Windows it is a HANDLE.
 .AP int readOrWrite in
 OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR to indicate
 what operations are valid on \fIhandle\fR.
-.AP char *channelName in
+.AP "CONST char" *channelName in
 The name of the channel. 
 .AP int *modePtr out
 Points at an integer variable that will receive an OR-ed combination of
 \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR denoting whether the channel is
 open for reading and writing.
+.VS 8.3
+.AP "CONST char" *pattern in
+The pattern to match on, passed to Tcl_StringMatch, or NULL.
+.VE
 .AP Tcl_Channel channel in
 A Tcl channel for input or output.  Must have been the return value
 from a procedure such as \fBTcl_OpenFileChannel\fR.
@@ -182,11 +183,20 @@ object.
 A pointer to a Tcl dynamic string in which to store the line read from the
 channel.  Must have been initialized by the caller.  The line read will be
 appended to any data already in the dynamic string.
+.VS 8.3
+.AP "CONST char" *input in
+The input to add to a channel buffer.
+.AP int inputLen in
+Length of the input
+.AP int addAtEnd in
+Flag indicating whether the input should be added to the end or
+beginning of the channel buffer.
+.VE
 .AP Tcl_Obj *writeObjPtr in
 A pointer to a Tcl Object whose contents will be output to the channel.
 .AP "CONST char" *charBuf in
 A buffer containing the characters to output to the channel.
-.AP char *byteBuf in
+.AP "CONST char" *byteBuf in
 A buffer containing the bytes to output to the channel.
 .AP int bytesToWrite in
 The number of bytes to consume from \fIcharBuf\fR or \fIbyteBuf\fR and
@@ -200,25 +210,14 @@ given by \fIseekMode\fR.  May be either positive or negative.
 Relative to which point to seek; used with \fIoffset\fR to calculate the new
 access point for the channel. Legal values are \fBSEEK_SET\fR,
 \fBSEEK_CUR\fR, and \fBSEEK_END\fR.
-.AP char *optionName in
+.AP "CONST char" *optionName in
 The name of an option applicable to this channel, such as \fB\-blocking\fR.
 May have any of the values accepted by the \fBfconfigure\fR command.
 .AP Tcl_DString *optionValue in
 Where to store the value of an option or a list of all options and their
 values. Must have been initialized by the caller.
-.AP char *newValue in
+.AP "CONST char" *newValue in
 New value for the option given by \fIoptionName\fR.
-.VS 8.3
-.AP char *pattern in
-The pattern to match on, passed to Tcl_StringMatch, or NULL.
-.AP char *input in
-The input to add to a channel buffer.
-.AP int inputLen in
-Length of the input
-.AP int addToEnd in
-Flag indicating whether the input should be added to the end or
-beginning of the channel buffer.
-.VE
 .BE
 
 .SH DESCRIPTION
@@ -316,7 +315,7 @@ replacement for the standard channel.
 \fBTcl_GetChannel\fR returns a channel given the \fIchannelName\fR used to
 create it with \fBTcl_CreateChannel\fR and a pointer to a Tcl interpreter in
 \fIinterp\fR. If a channel by that name is not registered in that interpreter,
-the procedure returns NULL. If the \fImode\fR argument is not NULL, it
+the procedure returns NULL. If the \fImodePtr\fR argument is not NULL, it
 points at an integer variable that will receive an OR-ed combination of
 \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR describing whether the channel is
 open for reading and writing.
@@ -430,7 +429,7 @@ corresponding calls to \fBTcl_UnregisterChannel\fR.
 to UTF-8 based on the channel's encoding and storing the produced data in 
 \fIreadObjPtr\fR's string representation.  The return value of
 \fBTcl_ReadChars\fR is the number of characters, up to \fIcharsToRead\fR,
-that were stored in \fIobjPtr\fR.  If an error occurs while reading, the
+that were stored in \fIreadObjPtr\fR.  If an error occurs while reading, the
 return value is \-1 and \fBTcl_ReadChars\fR records a POSIX error code that
 can be retrieved with \fBTcl_GetErrno\fR.
 .PP
@@ -467,9 +466,9 @@ converting to or from UTF-8.
 encoding conversions, regardless of the channel's encoding.  It is deprecated
 and exists for backwards compatibility with non-internationalized Tcl
 extensions.  It consumes bytes from \fIchannel\fR and stores them in
-\fIbuf\fR, performing end-of-line translations on the way.  The return value
-of \fBTcl_Read\fR is the number of bytes, up to \fItoRead\fR, written in
-\fIbuf\fR.  The buffer produced by \fBTcl_Read\fR is not NULL terminated.
+\fIreadBuf\fR, performing end-of-line translations on the way.  The return value
+of \fBTcl_Read\fR is the number of bytes, up to \fIbytesToRead\fR, written in
+\fIreadBuf\fR.  The buffer produced by \fBTcl_Read\fR is not NULL terminated.
 Its contents are valid from the zeroth position up to and excluding the
 position indicated by the return value.  
 .PP
@@ -506,15 +505,15 @@ of input unavailability.
 .PP
 \fBTcl_Gets\fR is the same as \fBTcl_GetsObj\fR except the resulting
 characters are appended to the dynamic string given by
-\fIdsPtr\fR rather than a Tcl object.
+\fIlineRead\fR rather than a Tcl object.
 
 .SH "TCL_UNGETS"
 .PP
 \fBTcl_Ungets\fR is used to add data to the input queue of a channel,
-at either the head or tail of the queue.  \fIInput\fR is a pointer to
-the data that is to be added.  \fIInputLen\fR gives the length of the
-input to add.  \fIAddAtEnd\fR, in non-zero, indicates that the data is
-to be added at the end of queue; otherwise it will be added at the
+at either the head or tail of the queue.  The pointer \fIinput\fR points
+to the data that is to be added.  The length of the input to add is given
+by \fIinputLen\fR.  A non-zero value of \fIaddAtEnd\fR indicates that the
+data is to be added at the end of queue; otherwise it will be added at the
 head of the queue.  If \fIchannel\fR has a "sticky" EOF set, no data will be
 added to the input queue.  \fBTcl_Ungets\fR returns \fIinputLen\fR or
 -1 if an error occurs.
@@ -607,7 +606,7 @@ value is \-1 if the channel does not support seeking.
 
 .SH TCL_GETCHANNELOPTION
 .PP
-\fBTcl_GetChannelOption\fR retrieves, in \fIdsPtr\fR, the value of one of
+\fBTcl_GetChannelOption\fR retrieves, in \fIoptionValue\fR, the value of one of
 the options currently in effect for a channel, or a list of all options and
 their values.  The \fIchannel\fR argument identifies the channel for which
 to query an option or retrieve all options and their values.
@@ -629,9 +628,8 @@ error code.
 
 .SH TCL_SETCHANNELOPTION
 .PP
-\fBTcl_SetChannelOption\fR sets a new value for an option on \fIchannel\fR.
-\fIOptionName\fR is the option to set and \fInewValue\fR is the value to
-set.
+\fBTcl_SetChannelOption\fR sets a new value \fInewValue\fR
+for an option \fIoptionName\fR on \fIchannel\fR.
 The procedure normally returns \fBTCL_OK\fR.  If an error occurs,
 it returns \fBTCL_ERROR\fR;  in addition, if \fIinterp\fR is non-NULL,
 \fBTcl_SetChannelOption\fR leaves an error message in the interpreter's result.