#include <tcl.h> typedef ... Tcl_Channel; Tcl_Channel Tcl_OpenFileChannel(interp, fileName, mode, permissions) Tcl_Channel Tcl_OpenCommandChannel(interp, argc, argv, flags) Tcl_Channel Tcl_MakeFileChannel(handle, readOrWrite) Tcl_Channel Tcl_GetChannel(interp, channelName, modePtr) void Tcl_RegisterChannel(interp, channel) int Tcl_UnregisterChannel(interp, channel) int Tcl_Close(interp, channel) int Tcl_Read(channel, buf, toRead) int Tcl_Gets(channel, lineRead) int Tcl_GetsObj(channel, lineObjPtr) int Tcl_Write(channel, buf, toWrite) int Tcl_Flush(channel) int Tcl_Seek(channel, offset, seekMode) int Tcl_Tell(channel) int Tcl_GetChannelOption(channel, optionName, optionValue) int Tcl_SetChannelOption(interp, channel, optionName, newValue) int Tcl_Eof(channel) int Tcl_InputBlocked(channel) int Tcl_InputBuffered(channel)
The procedures described in this manual entry comprise the C APIs of the generic layer of the channel architecture. For a description of the channel driver architecture and how to implement channel drivers for new types of channels, see the manual entry for Tcl_CreateChannel.
The newly created channel is not registered in the supplied interpreter; to register it, use Tcl_RegisterChannel, described below. If one of the standard channels, stdin, stdout or stderr was previously closed, the act of creating the new channel also assigns it as a replacement for the standard channel.
If the TCL_STDIN flag is set then the standard input for the first subprocess will be tied to the channel: writing to the channel will provide input to the subprocess. If TCL_STDIN is not set, then standard input for the first subprocess will be the same as this application's standard input. If TCL_STDOUT is set then standard output from the last subprocess can be read from the channel; otherwise it goes to this application's standard output. If TCL_STDERR is set, standard error output for all subprocesses is returned to the channel and results in an error when the channel is closed; otherwise it goes to this application's standard error. If TCL_ENFORCE_MODE is not set, then argc and argv can redirect the stdio handles to override TCL_STDIN, TCL_STDOUT, and TCL_STDERR; if it is set, then it is an error for argc and argv to override stdio channels for which TCL_STDIN, TCL_STDOUT, and TCL_STDERR have been set.
If an error occurs while opening the channel, Tcl_OpenCommandChannel returns NULL and records a POSIX error code that can be retrieved with Tcl_GetErrno. In addition, Tcl_OpenCommandChannel leaves an error message in interp->result if interp is not NULL.
The newly created channel is not registered in the supplied interpreter; to register it, use Tcl_RegisterChannel, described below. If one of the standard channels, stdin, stdout or stderr was previously closed, the act of creating the new channel also assigns it as a replacement for the standard channel.
Code executing outside of any Tcl interpreter can call Tcl_RegisterChannel with interp as NULL, to indicate that it wishes to hold a reference to this channel. Subsequently, the channel can be registered in a Tcl interpreter and it will only be closed when the matching number of calls to Tcl_UnregisterChannel have been made. This allows code executing outside of any interpreter to safely hold a reference to a channel that is also registered in a Tcl interpreter.
Code not associated with a Tcl interpreter can call Tcl_UnregisterChannel with interp as NULL, to indicate to Tcl that it no longer holds a reference to that channel. If this is the last reference to the channel, it will now be closed.
If the channel was closed successfully, Tcl_Close returns TCL_OK. If an error occurs, Tcl_Close returns TCL_ERROR and records a POSIX error code that can be retrieved with Tcl_GetErrno. If the channel is being closed synchronously and an error occurs during closing of the channel and interp is not NULL, an error message is left in interp->result.
Note: it is not safe to call Tcl_Close on a channel that has been registered using Tcl_RegisterChannel; see the documentation for Tcl_RegisterChannel, above, for details. If the channel has ever been given as the chan argument in a call to Tcl_RegisterChannel, you should instead use Tcl_UnregisterChannel, which will internally call Tcl_Close when all calls to Tcl_RegisterChannel have been matched by corresponding calls to Tcl_UnregisterChannel.
The return value may be smaller than the value of toRead, indicating that less data than requested was available, also called a short read. In blocking mode, this can only happen on an end-of-file. In nonblocking mode, a short read can also occur if there is not enough input currently available: Tcl_Read returns a short count rather than waiting for more data.
If the channel is in blocking mode, a return value of zero indicates an end of file condition. If the channel is in nonblocking mode, a return value of zero indicates either that no input is currently available or an end of file condition. Use Tcl_Eof and Tcl_InputBlocked to tell which of these conditions actually occurred.
Tcl_Read translates platform-specific end-of-line representations into the canonical \n internal representation according to the current end-of-line recognition mode. End-of-line recognition and the various platform-specific modes are described in the manual entry for the Tcl fconfigure command.
If a line was successfully read, the return value is greater than or equal to zero, and it indicates the number of characters stored in the dynamic string. If an error occurs, Tcl_Gets returns -1 and records a POSIX error code that can be retrieved with Tcl_GetErrno. Tcl_Gets also returns -1 if the end of the file is reached; the Tcl_Eof procedure can be used to distinguish an error from an end-of-file condition.
If the channel is in nonblocking mode, the return value can also be -1 if no data was available or the data that was available did not contain an end-of-line character. When -1 is returned, the Tcl_InputBlocked procedure may be invoked to determine if the channel is blocked because of input unavailability.
Tcl_GetsObj is the same as Tcl_Gets except the resulting characters are appended to a Tcl object lineObjPtr rather than a dynamic string.
The toWrite argument specifies how many bytes of data are provided in the buf argument. If it is negative, Tcl_Write expects the data to be NULL terminated and it outputs everything up to the NULL.
The return value of Tcl_Write is a count of how many characters were accepted for output to the channel. This is either equal to toWrite or -1 to indicate that an error occurred. If an error occurs, Tcl_Write also records a POSIX error code that may be retrieved with Tcl_GetErrno.
Newline characters in the output data are translated to platform-specific end-of-line sequences according to the -translation option for the channel.
The return value is normally TCL_OK. If an error occurs, Tcl_Flush returns TCL_ERROR and records a POSIX error code that can be retrieved with Tcl_GetErrno.
Tcl_Seek normally returns the new access point. If an error occurs, Tcl_Seek returns -1 and records a POSIX error code that can be retrieved with Tcl_GetErrno. After an error, the access point may or may not have been moved.
PLATFORM ISSUES
The handles returned from Tcl_GetChannelHandle depend on the
platform and the channel type. On Unix platforms, the handle is
always a Unix file descriptor as returned from the open system
call. On Windows platforms, the handle is a file HANDLE when
the channel was created with Tcl_OpenFileChannel,
Tcl_OpenCommandChannel, or Tcl_MakeFileChannel. Other
channel types may return a different type of handle on Windows
platforms. On the Macintosh platform, the handle is a file reference
number as returned from HOpenDF.
Copyright © 1989-1994 The Regents of the University of California.
Copyright © 1994-1997 Sun Microsystems, Inc.