TIP#208 implementation

It's crude (especially in the tests and docs department) and incomplete (no truncation on non-POSIX platforms).

3 files changed, 197 insertions, 25 deletions

diff --git a/doc/CrtChannel.3 b/doc/CrtChannel.3
index d4f3a20..570cd2d 100644
--- a/doc/CrtChannel.3
+++ b/doc/CrtChannel.3
@@ -5,13 +5,13 @@
 '\" 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.29 2005/05/10 18:33:54 kennykb Exp $
+'\" RCS: @(#) $Id: CrtChannel.3,v 1.30 2005/06/06 23:45:42 dkf Exp $
 .so man.macros
 .TH Tcl_CreateChannel 3 8.4 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, 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_ChannelThreadActionProc, Tcl_IsChannelShared, Tcl_IsChannelRegistered, Tcl_CutChannel, Tcl_SpliceChannel, Tcl_IsChannelExisting, Tcl_ClearChannelHandlers, Tcl_GetChannelThread, Tcl_ChannelBuffered \- 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_ChannelTruncateProc, Tcl_ChannelSetOptionProc, Tcl_ChannelGetOptionProc, Tcl_ChannelWatchProc, Tcl_ChannelGetHandleProc, Tcl_ChannelFlushProc, Tcl_ChannelHandlerProc, Tcl_ChannelThreadActionProc, 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
@@ -98,6 +98,11 @@ Tcl_DriverWideSeekProc *
 Tcl_DriverThreadActionProc *
 \fBTcl_ChannelThreadActionProc\fR(\fItypePtr\fR)
 .sp
+.VS 8.5
+Tcl_DriverTruncateProc *
+\fBTcl_ChannelTruncateProc\fR(\fItypePtr\fR)
+.VE 8.5
+.sp
 Tcl_DriverSetOptionProc *
 \fBTcl_ChannelSetOptionProc\fR(\fItypePtr\fR)
 .sp
@@ -314,22 +319,25 @@ details about the old structure.
 The \fBTcl_ChannelType\fR structure contains the following fields:
 .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_DriverWideSeekProc *\fIwideSeekProc\fR;
-	Tcl_DriverThreadActionProc *\fIthreadActionProc\fR;
+        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_DriverWideSeekProc *\fIwideSeekProc\fR;
+.VS 8.5
+        Tcl_DriverThreadActionProc *\fIthreadActionProc\fR;
+        Tcl_DriverTruncateProc *\fItruncateProc\fR;
+.VE 8.5
 } Tcl_ChannelType;
 .CE
 .PP
@@ -349,6 +357,9 @@ structure, the following functions should be used to obtain the values:
 \fBTcl_ChannelClose2Proc\fR, \fBTcl_ChannelInputProc\fR,
 \fBTcl_ChannelOutputProc\fR, \fBTcl_ChannelSeekProc\fR,
 \fBTcl_ChannelWideSeekProc\fR, \fBTcl_ChannelThreadActionProc\fR,
+.VS 8.5
+\fBTcl_ChannelTruncateProc\fR,
+.VE 8.5
 \fBTcl_ChannelSetOptionProc\fR, \fBTcl_ChannelGetOptionProc\fR,
 \fBTcl_ChannelWatchProc\fR, \fBTcl_ChannelGetHandleProc\fR,
 \fBTcl_ChannelFlushProc\fR, or \fBTcl_ChannelHandlerProc\fR.
@@ -373,7 +384,10 @@ that you require. \fBTCL_CHANNEL_VERSION_2\fR is the minimum recommended.
 \fBTCL_CHANNEL_VERSION_3\fR must be set to specifiy the \fIwideSeekProc\fR member.
 .VS 8.5
 \fBTCL_CHANNEL_VERSION_4\fR must be set to specifiy the
-\fIthreadActionProc\fR member (includes \fIwideSeekProc\fR).
+\fIthreadActionProc\fR member (includes \fIwideSeekProc\fR), and
+\fBTCL_CHANNEL_VERSION_5\fR must be set to specify the
+\fItruncateProc\fR member (includes \fIwideSeekProc\fR and
+\fIthreadActionProc\fR).
 .VE 8.5
 If it is not set to any of these, then this
 \fBTcl_ChannelType\fR is assumed to have the original structure.  See
@@ -382,7 +396,11 @@ and function with either structures, 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
-one of \fBTCL_CHANNEL_VERSION_4\fR, \fBTCL_CHANNEL_VERSION_3\fR,
+one of
+.VS 8.5
+\fBTCL_CHANNEL_VERSION_5\fR, \fBTCL_CHANNEL_VERSION_4\fR,
+.VE 8.5
+\fBTCL_CHANNEL_VERSION_3\fR,
 \fBTCL_CHANNEL_VERSION_2\fR or \fBTCL_CHANNEL_VERSION_1\fR.
 .SS BLOCKMODEPROC
 .PP
@@ -798,8 +816,8 @@ might be maintaining using the calling thread as the associate. See
 .PP
 .CS
 typedef void Tcl_DriverThreadActionProc(
-	ClientData \fIinstanceData\fR,
-      int        \fIaction\fR);
+        ClientData \fIinstanceData\fR,
+        int        \fIaction\fR);
 .CE
 .PP
 \fIInstanceData\fR is the same as the value passed to
@@ -807,7 +825,26 @@ typedef void Tcl_DriverThreadActionProc(
 .PP
 These values can be retrieved with \fBTcl_ChannelThreadActionProc\fR,
 which returns a pointer to the function.
-
+.SS "TRUNCATEPROC"
+.PP
+The \fItruncateProc\fR field contains the address of the function
+called by the generic layer when a channel is truncated to some
+length. It can be NULL.
+.PP
+.CS
+typedef int Tcl_DriverTruncateProc(
+        ClientData \fIinstanceData\fR,
+        Tcl_WideInt \fIlength\fR);
+.CE
+.PP
+\fIInstanceData\fR is the same as the value passed to
+\fBTcl_CreateChannel\fR when this channel was created, and
+\fIlength\fR is the new length of the underlying file, which should
+not be negative. The result should be 0 on success or an errno code
+(suitable for use with \fBTcl_SetErrno\fR) on failure.
+.PP
+These values can be retrieved with \fBTcl_ChannelTruncateProc\fR,
+which returns a pointer to the function.
 .SH TCL_BADCHANNELOPTION
 .PP
 This procedure generates a "bad option" error message in an
@@ -883,6 +920,7 @@ typedef struct Tcl_ChannelType {
         Tcl_DriverBlockModeProc *\fIblockModeProc\fR;
         Tcl_DriverFlushProc *\fIflushProc\fR;
         Tcl_DriverHandlerProc *\fIhandlerProc\fR;
+        Tcl_DriverTruncateProc *\fItruncateProc\fR;
 } Tcl_ChannelType;
 .CE
 .PP
diff --git a/doc/OpenFileChnl.3 b/doc/OpenFileChnl.3
index 73494ce..a5caee4 100644
--- a/doc/OpenFileChnl.3
+++ b/doc/OpenFileChnl.3
@@ -4,13 +4,13 @@
 '\" 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.31 2005/05/10 18:33:56 kennykb Exp $
+'\" RCS: @(#) $Id: OpenFileChnl.3,v 1.32 2005/06/06 23:45:42 dkf Exp $
 .so man.macros
 .TH Tcl_OpenFileChannel 3 8.3 Tcl "Tcl Library Procedures"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-Tcl_OpenFileChannel, Tcl_OpenCommandChannel, Tcl_MakeFileChannel, Tcl_GetChannel, Tcl_GetChannelNames, Tcl_GetChannelNamesEx, Tcl_RegisterChannel, Tcl_UnregisterChannel, Tcl_DetachChannel, Tcl_IsStandardChannel, Tcl_Close, Tcl_ReadChars, Tcl_Read, Tcl_GetsObj, Tcl_Gets, Tcl_WriteObj, Tcl_WriteChars, Tcl_Write, Tcl_Flush, Tcl_Seek, Tcl_Tell, Tcl_GetChannelOption, Tcl_SetChannelOption, Tcl_Eof, Tcl_InputBlocked, Tcl_InputBuffered, Tcl_OutputBuffered, Tcl_Ungets, Tcl_ReadRaw, Tcl_WriteRaw \- buffered I/O facilities using channels
+Tcl_OpenFileChannel, Tcl_OpenCommandChannel, Tcl_MakeFileChannel, Tcl_GetChannel, Tcl_GetChannelNames, Tcl_GetChannelNamesEx, Tcl_RegisterChannel, Tcl_UnregisterChannel, Tcl_DetachChannel, Tcl_IsStandardChannel, Tcl_Close, Tcl_ReadChars, Tcl_Read, Tcl_GetsObj, Tcl_Gets, Tcl_WriteObj, Tcl_WriteChars, Tcl_Write, Tcl_Flush, Tcl_Seek, Tcl_Tell, Tcl_TruncateChannel, Tcl_GetChannelOption, Tcl_SetChannelOption, Tcl_Eof, Tcl_InputBlocked, Tcl_InputBuffered, Tcl_OutputBuffered, Tcl_Ungets, Tcl_ReadRaw, Tcl_WriteRaw \- buffered I/O facilities using channels
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -99,6 +99,11 @@ Tcl_WideInt
 Tcl_WideInt
 \fBTcl_Tell\fR(\fIchannel\fR)
 .sp
+.VS 8.5
+int
+\fBTcl_TruncateChannel\fR(\fIchannel, length\fR)
+.VE 8.5
+.sp
 int
 \fBTcl_GetChannelOption\fR(\fIinterp, channel, optionName, optionValue\fR)
 .sp
@@ -196,6 +201,8 @@ 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 Tcl_WideInt length in
+The (non-negative) length to truncate the channel the channel to.
 .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.
@@ -592,6 +599,14 @@ After an error, the access point may or may not have been moved.
 \fBTcl_Tell\fR returns the current access point for a channel. The returned
 value is \-1 if the channel does not support seeking.
 
+.SH TCL_TRUNCATECHANNEL
+.PP
+.VS 8.5
+\fBTcl_TruncateChannel\fR truncates the file underlying \fIchannel\fR
+to a given \fIlength\fR of bytes. It returns \fBTCL_OK\fR if the
+operation succeeded, and \fBTCL_ERROR\fR otherwise.
+.VE 8.5
+
 .SH TCL_GETCHANNELOPTION
 .PP
 \fBTcl_GetChannelOption\fR retrieves, in \fIoptionValue\fR, the value of one of
diff --git a/doc/chan.n b/doc/chan.n
new file mode 100644
index 0000000..19753cd
--- /dev/null
+++ b/doc/chan.n
@@ -0,0 +1,119 @@
+'\" 
+'\" Copyright (c) 2005 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+'\" RCS: @(#) $Id: chan.n,v 1.1 2005/06/06 23:45:41 dkf Exp $
+.so man.macros
+.TH chan n 8.5 Tcl "Tcl Built-In Commands"
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+chan \- Read, write and manipulate channels
+.SH SYNOPSIS
+\fBchan \fIoption\fR ?\fIarg arg ...\fR?
+.BE
+
+.SH DESCRIPTION
+.PP
+This command provides several operations for reading from, writing to
+and otherwise manipulating open channels (such as have been created
+with the \fBopen\fR and \fBsocket\fR commands). \fIOption\fR indicates
+what to do with the channel; any unique abbreviation for \fIoption\fR
+is acceptable. Valid options are:
+.TP
+\fBchan blocked \fIchannelId\fR
+Test whether the last input operation on the channel called
+\fIchannelId\fR failed because it would have otherwise caused the
+process to block.
+.TP
+\fBchan close \fIchannelId\fR
+Close and destroy the channel called \fIchannelId\fR. Note that this
+deletes all existing file-events registered on the channel.
+.TP
+\fBchan configure \fIchannelId\fR ?\fIoptionName\fR? ?\fIvalue\fR? ?\fIoptionName value\fR?...
+Query or set the configuration options of the channel named
+\fIchannelId\fR (see \fBfconfigure\fR for details).
+'\" FIXME: describe common channel options here and refer to creator
+'\" commands for special option descriptions.
+.TP
+\fBchan copy \fIinput output\fR ?\fB\-size \fIsize\fR? ?\fB\-command \fIcallback\fR?
+Copy the contents of the channel \fIinput\fR, which must have been
+opened for reading, to the channel \fIoutput\fR, which must have been
+opened for writing. If \fIsize\fR is specified, only that many bytes
+will be transferred. If \fIcallback\fR is specified, this command
+returns immediately and arranges for \fIcallback\fR to be called when
+the requested transfer has completed or an error occurs (assuming that
+the event loop is running) with extra arguments appended to
+\fIcallback\fR to indicate what happened.
+.TP
+\fBchan eof \fIchannelId\fR
+Test whether the last input operation on the channel called
+\fIchannelId\fR failed because the end of the data stream was reached.
+.TP
+\fBchan event \fIchannelId mode\fR ?\fIscript\fR?
+Arrange for the Tcl script \fIscript\fR to be called whenever the
+channel called \fIchannelId\fR enters the state described by
+\fImode\fR (which must be either \fBreadable\fR or \fBwritable\fR). If
+\fIscript\fR is omitted, the currently installed script is returned.
+The callback is only performed if the event loop is being serviced.
+.TP
+\fBchan flush \fIchannelId\fR
+Ensures that all pending output for the channel called \fIchannelId\fR
+is written.
+.TP
+\fBchan gets \fIchannelId\fR ?\fIvarName\fR?
+Reads a line from the channel called \fIchannelId\fR. If \fIvarName\fR
+is not specified, the result of the command will be the line that has
+been read (without a trailing newline character) or an empty string
+upon error. If \fIvarName\fR is specified, the line that has been read
+will be written to the variable called \fIvarName\fR and result will
+be the number of characters that have been read or -1 if an error
+occurred.
+.TP
+\fBchan names\fR ?\fIpattern\fR?
+Produces a list of all channel names. If \fIpattern\fR is specified,
+only those channel names that match it (according to the rules of
+\fBstring match\fR) will be returned.
+.TP
+\fBchan puts\fR ?\fB\-nonewline\fR? ?\fIchannelId\fR? \fIstring\fR
+Writes \fIstring\fR to the channel named \fIchannelId\fR (by default,
+to the standard output stream) followed by a newline character. If the
+optional flag \fB\-nonewline\fR is given, no trailing newline
+character is written.
+.TP
+\fBchan read \fIchannelId\fR ?\fInumChars\fR?
+.TP
+\fBchan read \fR?\fB\-nonewline\fR? \fIchannelId\fR
+In the first form, the result will be the next \fInumChars\fR
+characters read from the channel named \fIchannelId\fR; if
+\fInumChars\fR is omitted, all characters up to the point when the
+channel would signal a failure (whether an end-of-file, blocked or
+other error condition) are read. In the second form (i.e. when
+\fInumChars\fR has been omitted) the flag \fB\-nonewline\fR may be
+given to indicate that any trailing newline in the string that has
+been read should be trimmed.
+.TP
+\fBchan seek \fIchannelId offset\fR ?\fIorigin\fR?
+Sets the current position within the underlying data stream for the
+channel named \fIchannelId\fR to be \fIoffset\fR bytes relative to
+\fIorigin\fR. \fIOrigin\fR should be one of \fBstart\fR (the default
+origin), \fBcurrent\fR or \fBend\fR.
+.TP
+\fBchan tell \fIchannelId\fR
+Reports the current byte offset within the underlying data stream for
+the channel named \fIchannelId\fR.
+.TP
+\fBchan truncate \fIchannelId\fR ?\fIlength\fR?
+Sets the byte length of the underlying data stream for the channel
+named \fIchannelId\fR to be \fIlength\fR (or to the current byte
+offset within the underlying data stream if \fIlength\fR is omitted).
+
+.SH "SEE ALSO"
+close(n), eof(n), fblocked(n), fconfigure(n), fcopy(n), file(n),
+fileevent(n), flush(n), gets(n), open(n), puts(n), read(n), seek(n),
+socket(n), tell(n)
+
+.SH KEYWORDS
+channel, input, output, events, offset