Doc for Tcl 7.5 Channel IO system

The information contained below may be useful if you are writing new channel drivers for channels of types not yet supported by Tcl. The idea of the new IO system is to make this easy. Let me know if you run into any issues for which you believe there is not adequate support currently.

• CrtChannel.3 for a description of the channel architecture. Start here.
• GetFile.3 for a description of the Tcl_File layer.
• DoWhenIdle.3 , DoOneEvent.3 , Notifier.3 for a description of the notifier architecture.
• CrtChnlHdlr.3 for a description of the notifier's interaction with the Tcl_Channel level of the new IO system.
• CrtFileHdlr.3 for a description of the notifier's interaction with the Tcl_File level of the new IO system.
• GetOpnFl.3 for integration of the old Tcl_GetOpenFile command into the new IO system.
• OpenFileChnl.3 for a description of the file and command pipeline channel types.
• OpenTcp.3 for a description of the TCP channel type.
• GetStdChannel.3 for a description of the standard channel handles for standard input, standard output and standard error.
• CrtCloseHdlr.3 for how to install a callback that will be called when a channel is closed.

• open.n, gets.n, read.n ,
  flush.n, eof.n, close.n,
  seek.n, tell.n, puts.n
  for a description of what IO operations you can do with a channel.
• fconfigure.n for managing channel options such as its buffer size and whether IO is blocking or nonblocking.
• socket.n for how to create sockets (currently only for TCP).
• fileevent.n for how to make the notifier tell you when some event happens for a channel.

• Channels are created using Tcl_CreateChannel or one of the type specific channel creation APIs, e.g Tcl_OpenFileChannel, which uses Tcl_CreateChannel internally. Unless you're creating channels of a new type you're probably (99% of the time) better off using one of the type specific APIs.
• You can get the channel name (what it is registered with in interpreters) using Tcl_GetChannelName.
• You can get the channel type (a pointer to a Tcl_ChannelType data structure, defined in tcl.h) by using Tcl_GetChannelType.
• When you create a channel, you give up to two Tcl_File structures (more about those below). You can get them back again by calling the API Tcl_GetChannelFile.
• When you create a channel you (or the type specific API) supplies a client data, which you can get back from the channel using Tcl_GetChannelInstanceData.

The real definition of a Tcl_Channel (the concrete data type is called Channel, i.e without the Tcl_) is in generic/tclIO.c. Do not depend on its structure or fields to stay the same - this is an INTERNAL data structure.

To set up so that the notifier delivers events for your channel, use Tcl_CreateChannelHandler and Tcl_DeleteChannelHandler. This should work automatically with new types of channels unless you require the notifier to watch a new type of event source (i.e. an event source other than OS level files, pipes, sockets and timers) that it does not already know about. Currently the API does not let you do that. Contact us for help if you need this.

Tcl_Files are abstractions to wrap around OS specific data types for files, pipes etc. They provide a level of indirection that allows the IO system to be split into generic and type specific levels. Tcl_Files also provide ways to get at the data in them:

• Use Tcl_GetFileInfo to get the type (one of the constants defined in tcl.h) and the OS specific data type (as a ClientData).

The functionality provided by Tcl_Files is implemented in generic/tclFHandle.c which also provides the concrete data type for Tcl_Files (the name of which is FileHandle). Again this is an internal data structure which should not be relied on in any way.

It's also possible to interface with the notifier at the level of Tcl_File data structures, although you should not need to - you should be able to do most of what you want at the level of Tcl_Channel data structures. If you find this is really needed, you can use Tcl_CreateFileHandler and Tcl_DeleteFileHandler.

Some Conversion Functions

Abstractions:
    channel  - Exposed Tcl IO structure
    Tcl_File - Tcl Internal IO abstraction
        fd   - OS IO handle


    
(Unix) fd to Tcl_File :        Tcl_GetFile()

    
Tcl Channel Name to Channel:   Tcl_GetChannel()

    
Tcl_File to Channel:        Tcl_CreateChannel() 

    
Channel to  Tcl_File:       Tcl_GetChannelFile()

    
Tcl_File to (Unix) fd:      Tcl_GetFileInfo