Author:         Jeff Hobbs <jeffh@activestate.com>
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.