Author: Jeff Hobbs <[email protected]>
State: Final
Type: Project
Vote: Done
Created: 02-Jul-2004
Post-History:
Keywords: Tcl
Tcl-Version: 8.5
Obsoletes: 206
Abstract
This TIP proposes adding a chan command that would serve as a top-level command container for all the related channel commands that have proliferated over time, as well as future new channel-based commands.
Rationale
Tcl's channel system has evolved over time from a thin layer on top of the OS into a very complex, multi-platform system. There are numerous top-level commands for channels already, with more being proposed for Tcl 8.5. This command would centralize them, making it easier for new users to see all the related channel commands, much as string or file operate today.
The name chan was chosen over "channel" because it is a clearly recognizable abbreviation, much like eval vs. "evaluate" and interp vs "interpreter".
Specification
A new command chan will be added with the following syntax:
chan blocked ; # fblocked
chan close ; # close
chan configure ; # fconfigure
chan copy ; # fcopy
chan eof ; # eof
chan event ; # fileevent
chan flush ; # flush
chan gets ; # gets
chan names ; # file channels
chan puts ; # puts
chan read ; # read
chan seek ; # seek
chan tell ; # tell
chan truncate ; # ftruncate (if TIP#206 had been accepted)
Each represents the existing command that is commented. The arguments to each would remain what the current command takes.
Note that open is not included above, as it is a channel creation function, just like socket.
Specification of the 'truncate' Subcommand
[See [206] for Rationale]
chan truncate channelId ?length?
The channel specified by channelId must refer to a file that was opened for writing. The length argument must be greater than or equal to zero and can be bigger than the current size of the file. If the length argument is omitted, the file will be truncated at the current access position. The result of this command will normally be the empty string; any errors from the filesystem when truncating will generate error results in the normal fashion.
Deprecation of Existing Commands
In addition, I would recommend only the following commands be marked deprecated so as to help systematize their names better:
fblocked
fconfigure
fcopy
fileevent
file channels
Related C API Changes
A new function named Tcl_TruncateChannel would be added to the Tcl C API (taking two arguments, the channel to truncate and the length (as a wide integer to facilitate use with large files) to truncate it to in bytes).
int Tcl_TruncateChannel(Tcl_Channel chan, Tcl_WideInt length)
The channel API would be modified to add the new functionality for standard disk file channels and to allow extension authors to implement it for their custom channel types through specifying in their Tcl_ChannelType structure a value for the new field truncateProc (of type pointer to Tcl_DriverTruncateProc, which will be a function with the obvious type signature). Finally, the maximum TCL_CHANNEL_VERSION would be increased to TCL_CHANNEL_VERSION_4 to accommodate this new field.
Reference Implementation
The implementation of the Tcl-level TIP is really a simple command that makes use of the existing command implementations. It could be a namespace ensemble or a C-based command. The chan truncate part will require C code.
Copyright
This document has been placed in the public domain.