diff options
author | William Joye <wjoye@cfa.harvard.edu> | 2016-12-21 22:13:18 (GMT) |
---|---|---|
committer | William Joye <wjoye@cfa.harvard.edu> | 2016-12-21 22:13:18 (GMT) |
commit | 07e464099b99459d0a37757771791598ef3395d9 (patch) | |
tree | 4ba7d8aad13735e52f59bdce7ca5ba3151ebd7e3 /tcl8.6/doc/CrtChannel.3 | |
parent | deb3650e37f26f651f280e480c4df3d7dde87bae (diff) | |
download | blt-07e464099b99459d0a37757771791598ef3395d9.zip blt-07e464099b99459d0a37757771791598ef3395d9.tar.gz blt-07e464099b99459d0a37757771791598ef3395d9.tar.bz2 |
new subtree for tcl/tk
Diffstat (limited to 'tcl8.6/doc/CrtChannel.3')
-rw-r--r-- | tcl8.6/doc/CrtChannel.3 | 928 |
1 files changed, 0 insertions, 928 deletions
diff --git a/tcl8.6/doc/CrtChannel.3 b/tcl8.6/doc/CrtChannel.3 deleted file mode 100644 index 6ef94b5..0000000 --- a/tcl8.6/doc/CrtChannel.3 +++ /dev/null @@ -1,928 +0,0 @@ -'\" -'\" Copyright (c) 1996-1997 Sun Microsystems, Inc. -'\" Copyright (c) 1997-2000 Ajuba Solutions. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -.TH Tcl_CreateChannel 3 8.4 Tcl "Tcl Library Procedures" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType, Tcl_GetChannelName, Tcl_GetChannelHandle, Tcl_GetChannelMode, Tcl_GetChannelBufferSize, Tcl_SetChannelBufferSize, Tcl_NotifyChannel, Tcl_BadChannelOption, Tcl_ChannelName, Tcl_ChannelVersion, Tcl_ChannelBlockModeProc, Tcl_ChannelCloseProc, Tcl_ChannelClose2Proc, Tcl_ChannelInputProc, Tcl_ChannelOutputProc, Tcl_ChannelSeekProc, Tcl_ChannelWideSeekProc, Tcl_ChannelTruncateProc, Tcl_ChannelSetOptionProc, Tcl_ChannelGetOptionProc, Tcl_ChannelWatchProc, Tcl_ChannelGetHandleProc, Tcl_ChannelFlushProc, Tcl_ChannelHandlerProc, Tcl_ChannelThreadActionProc, Tcl_IsChannelShared, Tcl_IsChannelRegistered, Tcl_CutChannel, Tcl_SpliceChannel, Tcl_IsChannelExisting, Tcl_ClearChannelHandlers, Tcl_GetChannelThread, Tcl_ChannelBuffered \- procedures for creating and manipulating channels -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -Tcl_Channel -\fBTcl_CreateChannel\fR(\fItypePtr, channelName, instanceData, mask\fR) -.sp -ClientData -\fBTcl_GetChannelInstanceData\fR(\fIchannel\fR) -.sp -const Tcl_ChannelType * -\fBTcl_GetChannelType\fR(\fIchannel\fR) -.sp -const char * -\fBTcl_GetChannelName\fR(\fIchannel\fR) -.sp -int -\fBTcl_GetChannelHandle\fR(\fIchannel, direction, handlePtr\fR) -.sp -Tcl_ThreadId -\fBTcl_GetChannelThread\fR(\fIchannel\fR) -.sp -int -\fBTcl_GetChannelMode\fR(\fIchannel\fR) -.sp -int -\fBTcl_GetChannelBufferSize\fR(\fIchannel\fR) -.sp -\fBTcl_SetChannelBufferSize\fR(\fIchannel, size\fR) -.sp -\fBTcl_NotifyChannel\fR(\fIchannel, mask\fR) -.sp -int -\fBTcl_BadChannelOption\fR(\fIinterp, optionName, optionList\fR) -.sp -int -\fBTcl_IsChannelShared\fR(\fIchannel\fR) -.sp -int -\fBTcl_IsChannelRegistered\fR(\fIinterp, channel\fR) -.sp -int -\fBTcl_IsChannelExisting\fR(\fIchannelName\fR) -.sp -void -\fBTcl_CutChannel\fR(\fIchannel\fR) -.sp -void -\fBTcl_SpliceChannel\fR(\fIchannel\fR) -.sp -void -\fBTcl_ClearChannelHandlers\fR(\fIchannel\fR) -.sp -int -\fBTcl_ChannelBuffered\fR(\fIchannel\fR) -.sp -const char * -\fBTcl_ChannelName\fR(\fItypePtr\fR) -.sp -Tcl_ChannelTypeVersion -\fBTcl_ChannelVersion\fR(\fItypePtr\fR) -.sp -Tcl_DriverBlockModeProc * -\fBTcl_ChannelBlockModeProc\fR(\fItypePtr\fR) -.sp -Tcl_DriverCloseProc * -\fBTcl_ChannelCloseProc\fR(\fItypePtr\fR) -.sp -Tcl_DriverClose2Proc * -\fBTcl_ChannelClose2Proc\fR(\fItypePtr\fR) -.sp -Tcl_DriverInputProc * -\fBTcl_ChannelInputProc\fR(\fItypePtr\fR) -.sp -Tcl_DriverOutputProc * -\fBTcl_ChannelOutputProc\fR(\fItypePtr\fR) -.sp -Tcl_DriverSeekProc * -\fBTcl_ChannelSeekProc\fR(\fItypePtr\fR) -.sp -Tcl_DriverWideSeekProc * -\fBTcl_ChannelWideSeekProc\fR(\fItypePtr\fR) -.sp -Tcl_DriverThreadActionProc * -\fBTcl_ChannelThreadActionProc\fR(\fItypePtr\fR) -.sp -Tcl_DriverTruncateProc * -\fBTcl_ChannelTruncateProc\fR(\fItypePtr\fR) -.sp -Tcl_DriverSetOptionProc * -\fBTcl_ChannelSetOptionProc\fR(\fItypePtr\fR) -.sp -Tcl_DriverGetOptionProc * -\fBTcl_ChannelGetOptionProc\fR(\fItypePtr\fR) -.sp -Tcl_DriverWatchProc * -\fBTcl_ChannelWatchProc\fR(\fItypePtr\fR) -.sp -Tcl_DriverGetHandleProc * -\fBTcl_ChannelGetHandleProc\fR(\fItypePtr\fR) -.sp -Tcl_DriverFlushProc * -\fBTcl_ChannelFlushProc\fR(\fItypePtr\fR) -.sp -Tcl_DriverHandlerProc * -\fBTcl_ChannelHandlerProc\fR(\fItypePtr\fR) -.sp -.SH ARGUMENTS -.AS "const Tcl_ChannelType" *channelName -.AP "const Tcl_ChannelType" *typePtr in -Points to a structure containing the addresses of procedures that -can be called to perform I/O and other functions on the channel. -.AP "const char" *channelName in -The name of this channel, such as \fBfile3\fR; must not be in use -by any other channel. Can be NULL, in which case the channel is -created without a name. If the created channel is assigned to one -of the standard channels (\fBstdin\fR, \fBstdout\fR or \fBstderr\fR), -the assigned channel name will be the name of the standard channel. -.AP ClientData instanceData in -Arbitrary one-word value to be associated with this channel. This -value is passed to procedures in \fItypePtr\fR when they are invoked. -.AP int mask in -OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR to indicate -whether a channel is readable and writable. -.AP Tcl_Channel channel in -The channel to operate on. -.AP int direction in -\fBTCL_READABLE\fR means the input handle is wanted; \fBTCL_WRITABLE\fR -means the output handle is wanted. -.AP ClientData *handlePtr out -Points to the location where the desired OS-specific handle should be -stored. -.AP int size in -The size, in bytes, of buffers to allocate in this channel. -.AP int mask in -An OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR -and \fBTCL_EXCEPTION\fR that indicates events that have occurred on -this channel. -.AP Tcl_Interp *interp in -Current interpreter. (can be NULL) -.AP "const char" *optionName in -Name of the invalid option. -.AP "const char" *optionList in -Specific options list (space separated words, without -.QW \- ) -to append to the standard generic options list. -Can be NULL for generic options error message only. -.BE -.SH DESCRIPTION -.PP -Tcl uses a two-layered channel architecture. It provides a generic upper -layer to enable C and Tcl programs to perform input and output using the -same APIs for a variety of files, devices, sockets etc. The generic C APIs -are described in the manual entry for \fBTcl_OpenFileChannel\fR. -.PP -The lower layer provides type-specific channel drivers for each type -of device supported on each platform. This manual entry describes the -C APIs used to communicate between the generic layer and the -type-specific channel drivers. It also explains how new types of -channels can be added by providing new channel drivers. -.PP -Channel drivers consist of a number of components: First, each channel -driver provides a \fBTcl_ChannelType\fR structure containing pointers to -functions implementing the various operations used by the generic layer to -communicate with the channel driver. The \fBTcl_ChannelType\fR structure -and the functions referenced by it are described in the section -\fBTCL_CHANNELTYPE\fR, below. -.PP -Second, channel drivers usually provide a Tcl command to create -instances of that type of channel. For example, the Tcl \fBopen\fR -command creates channels that use the file and command channel -drivers, and the Tcl \fBsocket\fR command creates channels that use -TCP sockets for network communication. -.PP -Third, a channel driver optionally provides a C function to open -channel instances of that type. For example, \fBTcl_OpenFileChannel\fR -opens a channel that uses the file channel driver, and -\fBTcl_OpenTcpClient\fR opens a channel that uses the TCP network -protocol. These creation functions typically use -\fBTcl_CreateChannel\fR internally to open the channel. -.PP -To add a new type of channel you must implement a C API or a Tcl command -that opens a channel by invoking \fBTcl_CreateChannel\fR. -When your driver calls \fBTcl_CreateChannel\fR it passes in -a \fBTcl_ChannelType\fR structure describing the driver's I/O -procedures. -The generic layer will then invoke the functions referenced in that -structure to perform operations on the channel. -.PP -\fBTcl_CreateChannel\fR opens a new channel and associates the supplied -\fItypePtr\fR and \fIinstanceData\fR with it. The channel is opened in the -mode indicated by \fImask\fR. -For a discussion of channel drivers, their operations and the -\fBTcl_ChannelType\fR structure, see the section \fBTCL_CHANNELTYPE\fR, below. -.PP -\fBTcl_CreateChannel\fR interacts with the code managing the standard -channels. Once a standard channel was initialized either through a -call to \fBTcl_GetStdChannel\fR or a call to \fBTcl_SetStdChannel\fR -closing this standard channel will cause the next call to -\fBTcl_CreateChannel\fR to make the new channel the new standard -channel too. See \fBTcl_StandardChannels\fR for a general treatise -about standard channels and the behavior of the Tcl library with -regard to them. -.PP -\fBTcl_GetChannelInstanceData\fR returns the instance data associated with -the channel in \fIchannel\fR. This is the same as the \fIinstanceData\fR -argument in the call to \fBTcl_CreateChannel\fR that created this channel. -.PP -\fBTcl_GetChannelType\fR returns a pointer to the \fBTcl_ChannelType\fR -structure used by the channel in the \fIchannel\fR argument. This is -the same as the \fItypePtr\fR argument in the call to -\fBTcl_CreateChannel\fR that created this channel. -.PP -\fBTcl_GetChannelName\fR returns a string containing the name associated -with the channel, or NULL if the \fIchannelName\fR argument to -\fBTcl_CreateChannel\fR was NULL. -.PP -\fBTcl_GetChannelHandle\fR places the OS-specific device handle -associated with \fIchannel\fR for the given \fIdirection\fR in the -location specified by \fIhandlePtr\fR and returns \fBTCL_OK\fR. If -the channel does not have a device handle for the specified direction, -then \fBTCL_ERROR\fR is returned instead. Different channel drivers -will return different types of handle. Refer to the manual entries -for each driver to determine what type of handle is returned. -.PP -\fBTcl_GetChannelThread\fR returns the id of the thread currently managing -the specified \fIchannel\fR. This allows channel drivers to send their file -events to the correct event queue even for a multi-threaded core. -.PP -\fBTcl_GetChannelMode\fR returns an OR-ed combination of \fBTCL_READABLE\fR -and \fBTCL_WRITABLE\fR, indicating whether the channel is open for input -and output. -.PP -\fBTcl_GetChannelBufferSize\fR returns the size, in bytes, of buffers -allocated to store input or output in \fIchannel\fR. If the value was not set -by a previous call to \fBTcl_SetChannelBufferSize\fR, described below, then -the default value of 4096 is returned. -.PP -\fBTcl_SetChannelBufferSize\fR sets the size, in bytes, of buffers that -will be allocated in subsequent operations on the channel to store input or -output. The \fIsize\fR argument should be between one and one million, -allowing buffers of one byte to one million bytes. If \fIsize\fR is -outside this range, \fBTcl_SetChannelBufferSize\fR sets the buffer size to -4096. -.PP -\fBTcl_NotifyChannel\fR is called by a channel driver to indicate to -the generic layer that the events specified by \fImask\fR have -occurred on the channel. Channel drivers are responsible for invoking -this function whenever the channel handlers need to be called for the -channel. See \fBWATCHPROC\fR below for more details. -.PP -\fBTcl_BadChannelOption\fR is called from driver specific -\fIsetOptionProc\fR or \fIgetOptionProc\fR to generate a complete -error message. -.PP -\fBTcl_ChannelBuffered\fR returns the number of bytes of input -currently buffered in the internal buffer (push back area) of the -channel itself. It does not report about the data in the overall -buffers for the stack of channels the supplied channel is part of. -.PP -\fBTcl_IsChannelShared\fR checks the refcount of the specified -\fIchannel\fR and returns whether the \fIchannel\fR was shared among -multiple interpreters (result == 1) or not (result == 0). -.PP -\fBTcl_IsChannelRegistered\fR checks whether the specified \fIchannel\fR is -registered in the given \fIinterp\fRreter (result == 1) or not -(result == 0). -.PP -\fBTcl_IsChannelExisting\fR checks whether a channel with the specified -name is registered in the (thread)-global list of all channels (result -== 1) or not (result == 0). -.PP -\fBTcl_CutChannel\fR removes the specified \fIchannel\fR from the -(thread)global list of all channels (of the current thread). -Application to a channel still registered in some interpreter -is not allowed. -Also notifies the driver if the \fBTcl_ChannelType\fR version is -\fBTCL_CHANNEL_VERSION_4\fR (or higher), and -\fBTcl_DriverThreadActionProc\fR is defined for it. -.PP -\fBTcl_SpliceChannel\fR adds the specified \fIchannel\fR to the -(thread)global list of all channels (of the current thread). -Application to a channel registered in some interpreter is not allowed. -Also notifies the driver if the \fBTcl_ChannelType\fR version is -\fBTCL_CHANNEL_VERSION_4\fR (or higher), and -\fBTcl_DriverThreadActionProc\fR is defined for it. -.PP -\fBTcl_ClearChannelHandlers\fR removes all channel handlers and event -scripts associated with the specified \fIchannel\fR, thus shutting -down all event processing for this channel. -.SH TCL_CHANNELTYPE -.PP -A channel driver provides a \fBTcl_ChannelType\fR structure that contains -pointers to functions that implement the various operations on a channel; -these operations are invoked as needed by the generic layer. The structure -was versioned starting in Tcl 8.3.2/8.4 to correct a problem with stacked -channel drivers. See the \fBOLD CHANNEL TYPES\fR section below for -details about the old structure. -.PP -The \fBTcl_ChannelType\fR structure contains the following fields: -.PP -.CS -typedef struct Tcl_ChannelType { - const char *\fItypeName\fR; - Tcl_ChannelTypeVersion \fIversion\fR; - Tcl_DriverCloseProc *\fIcloseProc\fR; - Tcl_DriverInputProc *\fIinputProc\fR; - Tcl_DriverOutputProc *\fIoutputProc\fR; - Tcl_DriverSeekProc *\fIseekProc\fR; - Tcl_DriverSetOptionProc *\fIsetOptionProc\fR; - Tcl_DriverGetOptionProc *\fIgetOptionProc\fR; - Tcl_DriverWatchProc *\fIwatchProc\fR; - Tcl_DriverGetHandleProc *\fIgetHandleProc\fR; - Tcl_DriverClose2Proc *\fIclose2Proc\fR; - Tcl_DriverBlockModeProc *\fIblockModeProc\fR; - Tcl_DriverFlushProc *\fIflushProc\fR; - Tcl_DriverHandlerProc *\fIhandlerProc\fR; - Tcl_DriverWideSeekProc *\fIwideSeekProc\fR; - Tcl_DriverThreadActionProc *\fIthreadActionProc\fR; - Tcl_DriverTruncateProc *\fItruncateProc\fR; -} \fBTcl_ChannelType\fR; -.CE -.PP -It is not necessary to provide implementations for all channel -operations. Those which are not necessary may be set to NULL in the -struct: \fIblockModeProc\fR, \fIseekProc\fR, \fIsetOptionProc\fR, -\fIgetOptionProc\fR, \fIgetHandleProc\fR, and \fIclose2Proc\fR, in addition to -\fIflushProc\fR, \fIhandlerProc\fR, \fIthreadActionProc\fR, and -\fItruncateProc\fR. Other functions that cannot be implemented in a -meaningful way should return \fBEINVAL\fR when called, to indicate -that the operations they represent are not available. Also note that -\fIwideSeekProc\fR can be NULL if \fIseekProc\fR is. -.PP -The user should only use the above structure for \fBTcl_ChannelType\fR -instantiation. When referencing fields in a \fBTcl_ChannelType\fR -structure, the following functions should be used to obtain the values: -\fBTcl_ChannelName\fR, \fBTcl_ChannelVersion\fR, -\fBTcl_ChannelBlockModeProc\fR, \fBTcl_ChannelCloseProc\fR, -\fBTcl_ChannelClose2Proc\fR, \fBTcl_ChannelInputProc\fR, -\fBTcl_ChannelOutputProc\fR, \fBTcl_ChannelSeekProc\fR, -\fBTcl_ChannelWideSeekProc\fR, \fBTcl_ChannelThreadActionProc\fR, -\fBTcl_ChannelTruncateProc\fR, -\fBTcl_ChannelSetOptionProc\fR, \fBTcl_ChannelGetOptionProc\fR, -\fBTcl_ChannelWatchProc\fR, \fBTcl_ChannelGetHandleProc\fR, -\fBTcl_ChannelFlushProc\fR, or \fBTcl_ChannelHandlerProc\fR. -.PP -The change to the structures was made in such a way that standard channel -types are binary compatible. However, channel types that use stacked -channels (i.e. TLS, Trf) have new versions to correspond to the above change -since the previous code for stacked channels had problems. -.SS TYPENAME -.PP -The \fItypeName\fR field contains a null-terminated string that -identifies the type of the device implemented by this driver, e.g. -\fBfile\fR or \fBsocket\fR. -.PP -This value can be retrieved with \fBTcl_ChannelName\fR, which returns -a pointer to the string. -.SS VERSION -.PP - -The \fIversion\fR field should be set to the version of the structure -that you require. \fBTCL_CHANNEL_VERSION_2\fR is the minimum recommended. -\fBTCL_CHANNEL_VERSION_3\fR must be set to specify the \fIwideSeekProc\fR member. -\fBTCL_CHANNEL_VERSION_4\fR must be set to specify the \fIthreadActionProc\fR member -(includes \fIwideSeekProc\fR). -\fBTCL_CHANNEL_VERSION_5\fR must be set to specify the -\fItruncateProc\fR members (includes -\fIwideSeekProc\fR and \fIthreadActionProc\fR). -If it is not set to any of these, then this -\fBTcl_ChannelType\fR is assumed to have the original structure. See -\fBOLD CHANNEL TYPES\fR for more details. While Tcl will recognize -and function with either structures, stacked channels must be of at -least \fBTCL_CHANNEL_VERSION_2\fR to function correctly. -.PP -This value can be retrieved with \fBTcl_ChannelVersion\fR, which returns -one of -\fBTCL_CHANNEL_VERSION_5\fR, -\fBTCL_CHANNEL_VERSION_4\fR, -\fBTCL_CHANNEL_VERSION_3\fR, -\fBTCL_CHANNEL_VERSION_2\fR or \fBTCL_CHANNEL_VERSION_1\fR. -.SS BLOCKMODEPROC -.PP -The \fIblockModeProc\fR field contains the address of a function called by -the generic layer to set blocking and nonblocking mode on the device. -\fIBlockModeProc\fR should match the following prototype: -.PP -.CS -typedef int \fBTcl_DriverBlockModeProc\fR( - ClientData \fIinstanceData\fR, - int \fImode\fR); -.CE -.PP -The \fIinstanceData\fR is the same as the value passed to -\fBTcl_CreateChannel\fR when this channel was created. The \fImode\fR -argument is either \fBTCL_MODE_BLOCKING\fR or \fBTCL_MODE_NONBLOCKING\fR to -set the device into blocking or nonblocking mode. The function should -return zero if the operation was successful, or a nonzero POSIX error code -if the operation failed. -.PP -If the operation is successful, the function can modify the supplied -\fIinstanceData\fR to record that the channel entered blocking or -nonblocking mode and to implement the blocking or nonblocking behavior. -For some device types, the blocking and nonblocking behavior can be -implemented by the underlying operating system; for other device types, the -behavior must be emulated in the channel driver. -.PP -This value can be retrieved with \fBTcl_ChannelBlockModeProc\fR, which returns -a pointer to the function. -.PP -A channel driver \fBnot\fR supplying a \fIblockModeProc\fR has to be -very, very careful. It has to tell the generic layer exactly which -blocking mode is acceptable to it, and should this also document for -the user so that the blocking mode of the channel is not changed to an -unacceptable value. Any confusion here may lead the interpreter into a -(spurious and difficult to find) deadlock. -.SS "CLOSEPROC AND CLOSE2PROC" -.PP -The \fIcloseProc\fR field contains the address of a function called by the -generic layer to clean up driver-related information when the channel is -closed. \fICloseProc\fR must match the following prototype: -.PP -.CS -typedef int \fBTcl_DriverCloseProc\fR( - ClientData \fIinstanceData\fR, - Tcl_Interp *\fIinterp\fR); -.CE -.PP -The \fIinstanceData\fR argument is the same as the value provided to -\fBTcl_CreateChannel\fR when the channel was created. The function should -release any storage maintained by the channel driver for this channel, and -close the input and output devices encapsulated by this channel. All queued -output will have been flushed to the device before this function is called, -and no further driver operations will be invoked on this instance after -calling the \fIcloseProc\fR. If the close operation is successful, the -procedure should return zero; otherwise it should return a nonzero POSIX -error code. In addition, if an error occurs and \fIinterp\fR is not NULL, -the procedure should store an error message in the interpreter's result. -.PP -Alternatively, channels that support closing the read and write sides -independently may set \fIcloseProc\fR to \fBTCL_CLOSE2PROC\fR and set -\fIclose2Proc\fR to the address of a function that matches the -following prototype: -.PP -.CS -typedef int \fBTcl_DriverClose2Proc\fR( - ClientData \fIinstanceData\fR, - Tcl_Interp *\fIinterp\fR, - int \fIflags\fR); -.CE -.PP -The \fIclose2Proc\fR will be called with \fIflags\fR set to an OR'ed -combination of \fBTCL_CLOSE_READ\fR or \fBTCL_CLOSE_WRITE\fR to -indicate that the driver should close the read and/or write side of -the channel. The channel driver may be invoked to perform -additional operations on the channel after \fIclose2Proc\fR is -called to close one or both sides of the channel. If \fIflags\fR is -\fB0\fR (zero), the driver should close the channel in the manner -described above for \fIcloseProc\fR. No further operations will be -invoked on this instance after \fIclose2Proc\fR is called with all -flags cleared. In all cases, the \fIclose2Proc\fR function should -return zero if the close operation was successful; otherwise it should -return a nonzero POSIX error code. In addition, if an error occurs and -\fIinterp\fR is not NULL, the procedure should store an error message -in the interpreter's result. -.PP -The \fIcloseProc\fR and \fIclose2Proc\fR values can be retrieved with -\fBTcl_ChannelCloseProc\fR or \fBTcl_ChannelClose2Proc\fR, which -return a pointer to the respective function. -.SS INPUTPROC -.PP -The \fIinputProc\fR field contains the address of a function called by the -generic layer to read data from the file or device and store it in an -internal buffer. \fIInputProc\fR must match the following prototype: -.PP -.CS -typedef int \fBTcl_DriverInputProc\fR( - ClientData \fIinstanceData\fR, - char *\fIbuf\fR, - int \fIbufSize\fR, - int *\fIerrorCodePtr\fR); -.CE -.PP -\fIInstanceData\fR is the same as the value passed to -\fBTcl_CreateChannel\fR when the channel was created. The \fIbuf\fR -argument points to an array of bytes in which to store input from the -device, and the \fIbufSize\fR argument indicates how many bytes are -available at \fIbuf\fR. -.PP -The \fIerrorCodePtr\fR argument points to an integer variable provided by -the generic layer. If an error occurs, the function should set the variable -to a POSIX error code that identifies the error that occurred. -.PP -The function should read data from the input device encapsulated by the -channel and store it at \fIbuf\fR. On success, the function should return -a nonnegative integer indicating how many bytes were read from the input -device and stored at \fIbuf\fR. On error, the function should return -1. If -an error occurs after some data has been read from the device, that data is -lost. -.PP -If \fIinputProc\fR can determine that the input device has some data -available but less than requested by the \fIbufSize\fR argument, the -function should only attempt to read as much data as is available and -return without blocking. If the input device has no data available -whatsoever and the channel is in nonblocking mode, the function should -return an \fBEAGAIN\fR error. If the input device has no data available -whatsoever and the channel is in blocking mode, the function should block -for the shortest possible time until at least one byte of data can be read -from the device; then, it should return as much data as it can read without -blocking. -.PP -This value can be retrieved with \fBTcl_ChannelInputProc\fR, which returns -a pointer to the function. -.SS OUTPUTPROC -.PP -The \fIoutputProc\fR field contains the address of a function called by the -generic layer to transfer data from an internal buffer to the output device. -\fIOutputProc\fR must match the following prototype: -.PP -.CS -typedef int \fBTcl_DriverOutputProc\fR( - ClientData \fIinstanceData\fR, - const char *\fIbuf\fR, - int \fItoWrite\fR, - int *\fIerrorCodePtr\fR); -.CE -.PP -\fIInstanceData\fR is the same as the value passed to -\fBTcl_CreateChannel\fR when the channel was created. The \fIbuf\fR -argument contains an array of bytes to be written to the device, and the -\fItoWrite\fR argument indicates how many bytes are to be written from the -\fIbuf\fR argument. -.PP -The \fIerrorCodePtr\fR argument points to an integer variable provided by -the generic layer. If an error occurs, the function should set this -variable to a POSIX error code that identifies the error. -.PP -The function should write the data at \fIbuf\fR to the output device -encapsulated by the channel. On success, the function should return a -nonnegative integer indicating how many bytes were written to the output -device. The return value is normally the same as \fItoWrite\fR, but may be -less in some cases such as if the output operation is interrupted by a -signal. If an error occurs the function should return -1. In case of -error, some data may have been written to the device. -.PP -If the channel is nonblocking and the output device is unable to absorb any -data whatsoever, the function should return -1 with an \fBEAGAIN\fR error -without writing any data. -.PP -This value can be retrieved with \fBTcl_ChannelOutputProc\fR, which returns -a pointer to the function. -.SS "SEEKPROC AND WIDESEEKPROC" -.PP -The \fIseekProc\fR field contains the address of a function called by the -generic layer to move the access point at which subsequent input or output -operations will be applied. \fISeekProc\fR must match the following -prototype: -.PP -.CS -typedef int \fBTcl_DriverSeekProc\fR( - ClientData \fIinstanceData\fR, - long \fIoffset\fR, - int \fIseekMode\fR, - int *\fIerrorCodePtr\fR); -.CE -.PP -The \fIinstanceData\fR argument is the same as the value given to -\fBTcl_CreateChannel\fR when this channel was created. \fIOffset\fR and -\fIseekMode\fR have the same meaning as for the \fBTcl_Seek\fR -procedure (described in the manual entry for \fBTcl_OpenFileChannel\fR). -.PP -The \fIerrorCodePtr\fR argument points to an integer variable provided by -the generic layer for returning \fBerrno\fR values from the function. The -function should set this variable to a POSIX error code if an error occurs. -The function should store an \fBEINVAL\fR error code if the channel type -does not implement seeking. -.PP -The return value is the new access point or -1 in case of error. If an -error occurred, the function should not move the access point. -.PP -If there is a non-NULL \fIseekProc\fR field, the \fIwideSeekProc\fR -field may contain the address of an alternative function to use which -handles wide (i.e. larger than 32-bit) offsets, so allowing seeks -within files larger than 2GB. The \fIwideSeekProc\fR will be called -in preference to the \fIseekProc\fR, but both must be defined if the -\fIwideSeekProc\fR is defined. \fIWideSeekProc\fR must match the -following prototype: -.PP -.CS -typedef Tcl_WideInt \fBTcl_DriverWideSeekProc\fR( - ClientData \fIinstanceData\fR, - Tcl_WideInt \fIoffset\fR, - int \fIseekMode\fR, - int *\fIerrorCodePtr\fR); -.CE -.PP -The arguments and return values mean the same thing as with -\fIseekProc\fR above, except that the type of offsets and the return -type are different. -.PP -The \fIseekProc\fR value can be retrieved with -\fBTcl_ChannelSeekProc\fR, which returns a pointer to the function, -and similarly the \fIwideSeekProc\fR can be retrieved with -\fBTcl_ChannelWideSeekProc\fR. -.SS SETOPTIONPROC -.PP -The \fIsetOptionProc\fR field contains the address of a function called by -the generic layer to set a channel type specific option on a channel. -\fIsetOptionProc\fR must match the following prototype: -.PP -.CS -typedef int \fBTcl_DriverSetOptionProc\fR( - ClientData \fIinstanceData\fR, - Tcl_Interp *\fIinterp\fR, - const char *\fIoptionName\fR, - const char *\fInewValue\fR); -.CE -.PP -\fIoptionName\fR is the name of an option to set, and \fInewValue\fR is -the new value for that option, as a string. The \fIinstanceData\fR is the -same as the value given to \fBTcl_CreateChannel\fR when this channel was -created. The function should do whatever channel type specific action is -required to implement the new value of the option. -.PP -Some options are handled by the generic code and this function is never -called to set them, e.g. \fB\-blockmode\fR. Other options are specific to -each channel type and the \fIsetOptionProc\fR procedure of the channel -driver will get called to implement them. The \fIsetOptionProc\fR field can -be NULL, which indicates that this channel type supports no type specific -options. -.PP -If the option value is successfully modified to the new value, the function -returns \fBTCL_OK\fR. -It should call \fBTcl_BadChannelOption\fR which itself returns -\fBTCL_ERROR\fR if the \fIoptionName\fR is -unrecognized. -If \fInewValue\fR specifies a value for the option that -is not supported or if a system call error occurs, -the function should leave an error message in the -\fIresult\fR field of \fIinterp\fR if \fIinterp\fR is not NULL. The -function should also call \fBTcl_SetErrno\fR to store an appropriate POSIX -error code. -.PP -This value can be retrieved with \fBTcl_ChannelSetOptionProc\fR, which returns -a pointer to the function. -.SS GETOPTIONPROC -.PP -The \fIgetOptionProc\fR field contains the address of a function called by -the generic layer to get the value of a channel type specific option on a -channel. \fIgetOptionProc\fR must match the following prototype: -.PP -.CS -typedef int \fBTcl_DriverGetOptionProc\fR( - ClientData \fIinstanceData\fR, - Tcl_Interp *\fIinterp\fR, - const char *\fIoptionName\fR, - Tcl_DString *\fIoptionValue\fR); -.CE -.PP -\fIOptionName\fR is the name of an option supported by this type of -channel. If the option name is not NULL, the function stores its current -value, as a string, in the Tcl dynamic string \fIoptionValue\fR. -If \fIoptionName\fR is NULL, the function stores in \fIoptionValue\fR an -alternating list of all supported options and their current values. -On success, the function returns \fBTCL_OK\fR. -It should call \fBTcl_BadChannelOption\fR which itself returns -\fBTCL_ERROR\fR if the \fIoptionName\fR is -unrecognized. If a system call error occurs, -the function should leave an error message in the -result of \fIinterp\fR if \fIinterp\fR is not NULL. The -function should also call \fBTcl_SetErrno\fR to store an appropriate POSIX -error code. -.PP -Some options are handled by the generic code and this function is never -called to retrieve their value, e.g. \fB\-blockmode\fR. Other options are -specific to each channel type and the \fIgetOptionProc\fR procedure of the -channel driver will get called to implement them. The \fIgetOptionProc\fR -field can be NULL, which indicates that this channel type supports no type -specific options. -.PP -This value can be retrieved with \fBTcl_ChannelGetOptionProc\fR, which returns -a pointer to the function. -.SS WATCHPROC -.PP -The \fIwatchProc\fR field contains the address of a function called -by the generic layer to initialize the event notification mechanism to -notice events of interest on this channel. -\fIWatchProc\fR should match the following prototype: -.PP -.CS -typedef void \fBTcl_DriverWatchProc\fR( - ClientData \fIinstanceData\fR, - int \fImask\fR); -.CE -.PP -The \fIinstanceData\fR is the same as the value passed to -\fBTcl_CreateChannel\fR when this channel was created. The \fImask\fR -argument is an OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR -and \fBTCL_EXCEPTION\fR; it indicates events the caller is interested in -noticing on this channel. -.PP -The function should initialize device type specific mechanisms to -notice when an event of interest is present on the channel. When one -or more of the designated events occurs on the channel, the channel -driver is responsible for calling \fBTcl_NotifyChannel\fR to inform -the generic channel module. The driver should take care not to starve -other channel drivers or sources of callbacks by invoking -Tcl_NotifyChannel too frequently. Fairness can be insured by using -the Tcl event queue to allow the channel event to be scheduled in sequence -with other events. See the description of \fBTcl_QueueEvent\fR for -details on how to queue an event. -.PP -This value can be retrieved with \fBTcl_ChannelWatchProc\fR, which returns -a pointer to the function. -.SS GETHANDLEPROC -.PP -The \fIgetHandleProc\fR field contains the address of a function called by -the generic layer to retrieve a device-specific handle from the channel. -\fIGetHandleProc\fR should match the following prototype: -.PP -.CS -typedef int \fBTcl_DriverGetHandleProc\fR( - ClientData \fIinstanceData\fR, - int \fIdirection\fR, - ClientData *\fIhandlePtr\fR); -.CE -.PP -\fIInstanceData\fR is the same as the value passed to -\fBTcl_CreateChannel\fR when this channel was created. The \fIdirection\fR -argument is either \fBTCL_READABLE\fR to retrieve the handle used -for input, or \fBTCL_WRITABLE\fR to retrieve the handle used for -output. -.PP -If the channel implementation has device-specific handles, the -function should retrieve the appropriate handle associated with the -channel, according the \fIdirection\fR argument. The handle should be -stored in the location referred to by \fIhandlePtr\fR, and -\fBTCL_OK\fR should be returned. If the channel is not open for the -specified direction, or if the channel implementation does not use -device handles, the function should return \fBTCL_ERROR\fR. -.PP -This value can be retrieved with \fBTcl_ChannelGetHandleProc\fR, which returns -a pointer to the function. -.SS FLUSHPROC -.PP -The \fIflushProc\fR field is currently reserved for future use. -It should be set to NULL. -\fIFlushProc\fR should match the following prototype: -.PP -.CS -typedef int \fBTcl_DriverFlushProc\fR( - ClientData \fIinstanceData\fR); -.CE -.PP -This value can be retrieved with \fBTcl_ChannelFlushProc\fR, which returns -a pointer to the function. -.SS HANDLERPROC -.PP -The \fIhandlerProc\fR field contains the address of a function called by -the generic layer to notify the channel that an event occurred. It should -be defined for stacked channel drivers that wish to be notified of events -that occur on the underlying (stacked) channel. -\fIHandlerProc\fR should match the following prototype: -.PP -.CS -typedef int \fBTcl_DriverHandlerProc\fR( - ClientData \fIinstanceData\fR, - int \fIinterestMask\fR); -.CE -.PP -\fIInstanceData\fR is the same as the value passed to \fBTcl_CreateChannel\fR -when this channel was created. The \fIinterestMask\fR is an OR-ed -combination of \fBTCL_READABLE\fR or \fBTCL_WRITABLE\fR; it indicates what -type of event occurred on this channel. -.PP -This value can be retrieved with \fBTcl_ChannelHandlerProc\fR, which returns -a pointer to the function. - -.SS "THREADACTIONPROC" -.PP -The \fIthreadActionProc\fR field contains the address of the function -called by the generic layer when a channel is created, closed, or -going to move to a different thread, i.e. whenever thread-specific -driver state might have to initialized or updated. It can be NULL. -The action \fITCL_CHANNEL_THREAD_REMOVE\fR is used to notify the -driver that it should update or remove any thread-specific data it -might be maintaining for the channel. -.PP -The action \fITCL_CHANNEL_THREAD_INSERT\fR is used to notify the -driver that it should update or initialize any thread-specific data it -might be maintaining using the calling thread as the associate. See -\fBTcl_CutChannel\fR and \fBTcl_SpliceChannel\fR for more detail. -.PP -.CS -typedef void \fBTcl_DriverThreadActionProc\fR( - ClientData \fIinstanceData\fR, - int \fIaction\fR); -.CE -.PP -\fIInstanceData\fR is the same as the value passed to -\fBTcl_CreateChannel\fR when this channel was created. -.PP -These values can be retrieved with \fBTcl_ChannelThreadActionProc\fR, -which returns a pointer to the function. -.SS "TRUNCATEPROC" -.PP -The \fItruncateProc\fR field contains the address of the function -called by the generic layer when a channel is truncated to some -length. It can be NULL. -.PP -.CS -typedef int \fBTcl_DriverTruncateProc\fR( - ClientData \fIinstanceData\fR, - Tcl_WideInt \fIlength\fR); -.CE -.PP -\fIInstanceData\fR is the same as the value passed to -\fBTcl_CreateChannel\fR when this channel was created, and -\fIlength\fR is the new length of the underlying file, which should -not be negative. The result should be 0 on success or an errno code -(suitable for use with \fBTcl_SetErrno\fR) on failure. -.PP -These values can be retrieved with \fBTcl_ChannelTruncateProc\fR, -which returns a pointer to the function. -.SH TCL_BADCHANNELOPTION -.PP -This procedure generates a -.QW "bad option" -error message in an -(optional) interpreter. It is used by channel drivers when -an invalid Set/Get option is requested. Its purpose is to concatenate -the generic options list to the specific ones and factorize -the generic options error message string. -.PP -It always returns \fBTCL_ERROR\fR -.PP -An error message is generated in \fIinterp\fR's result value to -indicate that a command was invoked with a bad option. -The message has the form -.CS - bad option "blah": should be one of - <...generic options...>+<...specific options...> -.CE -so you get for instance: -.CS - bad option "-blah": should be one of -blocking, - -buffering, -buffersize, -eofchar, -translation, - -peername, or -sockname -.CE -when called with \fIoptionList\fR equal to -.QW "peername sockname" -.PP -.QW blah -is the \fIoptionName\fR argument and -.QW "<specific options>" -is a space separated list of specific option words. -The function takes good care of inserting minus signs before -each option, commas after, and an -.QW or -before the last option. -.SH "OLD CHANNEL TYPES" -The original (8.3.1 and below) \fBTcl_ChannelType\fR structure contains -the following fields: -.PP -.CS -typedef struct Tcl_ChannelType { - const char *\fItypeName\fR; - Tcl_DriverBlockModeProc *\fIblockModeProc\fR; - Tcl_DriverCloseProc *\fIcloseProc\fR; - Tcl_DriverInputProc *\fIinputProc\fR; - Tcl_DriverOutputProc *\fIoutputProc\fR; - Tcl_DriverSeekProc *\fIseekProc\fR; - Tcl_DriverSetOptionProc *\fIsetOptionProc\fR; - Tcl_DriverGetOptionProc *\fIgetOptionProc\fR; - Tcl_DriverWatchProc *\fIwatchProc\fR; - Tcl_DriverGetHandleProc *\fIgetHandleProc\fR; - Tcl_DriverClose2Proc *\fIclose2Proc\fR; -} \fBTcl_ChannelType\fR; -.CE -.PP -It is still possible to create channel with the above structure. The -internal channel code will determine the version. It is imperative to use -the new \fBTcl_ChannelType\fR structure if you are creating a stacked -channel driver, due to problems with the earlier stacked channel -implementation (in 8.2.0 to 8.3.1). -.PP -Prior to 8.4.0 (i.e. during the later releases of 8.3 and early part -of the 8.4 development cycle) the \fBTcl_ChannelType\fR structure -contained the following fields: -.PP -.CS -typedef struct Tcl_ChannelType { - const char *\fItypeName\fR; - Tcl_ChannelTypeVersion \fIversion\fR; - Tcl_DriverCloseProc *\fIcloseProc\fR; - Tcl_DriverInputProc *\fIinputProc\fR; - Tcl_DriverOutputProc *\fIoutputProc\fR; - Tcl_DriverSeekProc *\fIseekProc\fR; - Tcl_DriverSetOptionProc *\fIsetOptionProc\fR; - Tcl_DriverGetOptionProc *\fIgetOptionProc\fR; - Tcl_DriverWatchProc *\fIwatchProc\fR; - Tcl_DriverGetHandleProc *\fIgetHandleProc\fR; - Tcl_DriverClose2Proc *\fIclose2Proc\fR; - Tcl_DriverBlockModeProc *\fIblockModeProc\fR; - Tcl_DriverFlushProc *\fIflushProc\fR; - Tcl_DriverHandlerProc *\fIhandlerProc\fR; - Tcl_DriverTruncateProc *\fItruncateProc\fR; -} \fBTcl_ChannelType\fR; -.CE -.PP -When the above structure is registered as a channel type, the -\fIversion\fR field should always be \fBTCL_CHANNEL_VERSION_2\fR. -.SH "SEE ALSO" -Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3), Tcl_QueueEvent(3), Tcl_StackChannel(3), Tcl_GetStdChannel(3) -.SH KEYWORDS -blocking, channel driver, channel registration, channel type, nonblocking |