TIP #208: ADD A 'CHAN' COMMAND ================================ Version: $Revision: 1.8 $ Author: Jeff Hobbs State: Final Type: Project Tcl-Version: 8.5 Vote: Done Created: Friday, 02 July 2004 URL: https://tip.tcl-lang.org208.html Post-History: Obsoletes: TIP #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 [TIP #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. ------------------------------------------------------------------------- TIP AutoGenerator - written by Donal K. Fellows