Author: Jeff Hobbs <firstname.lastname@example.org> State: Final Type: Project Vote: Done Created: 02-Jul-2004 Post-History: Keywords: Tcl Tcl-Version: 8.5 Obsoletes: 206
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.
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".
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  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.
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.
This document has been placed in the public domain.