* 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.

1 files changed, 35 insertions, 37 deletions

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.