diff options
Diffstat (limited to 'doc/CrtChannel.3')
| -rw-r--r-- | doc/CrtChannel.3 | 571 |
1 files changed, 571 insertions, 0 deletions
diff --git a/doc/CrtChannel.3 b/doc/CrtChannel.3 new file mode 100644 index 0000000..354665a --- /dev/null +++ b/doc/CrtChannel.3 @@ -0,0 +1,571 @@ +'\" +'\" Copyright (c) 1996-1997 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) CrtChannel.3 1.29 97/06/20 13:37:45 +.so man.macros +.TH Tcl_CreateChannel 3 8.0 Tcl "Tcl Library Procedures" +.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_SetDefaultTranslation, Tcl_SetChannelBufferSize, Tcl_NotifyChannel, Tcl_BadChannelOption \- 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 +Tcl_ChannelType * +\fBTcl_GetChannelType\fR(\fIchannel\fR) +.sp +char * +\fBTcl_GetChannelName\fR(\fIchannel\fR) +.VS +.sp +int +\fBTcl_GetChannelHandle\fR(\fIchannel, direction, handlePtr\fR) +.VE +.sp +int +\fBTcl_GetChannelFlags\fR(\fIchannel\fR) +.sp +\fBTcl_SetDefaultTranslation\fR(\fIchannel, transMode\fR) +.sp +int +\fBTcl_GetChannelBufferSize\fR(\fIchannel\fR) +.sp +\fBTcl_SetChannelBufferSize\fR(\fIchannel, size\fR) +.sp +.VS +\fBTcl_NotifyChannel\fR(\fIchannel, mask\fR) +.sp +int +\fBTcl_BadChannelOption\fR(\fIinterp, optionName, optionList\fR) +.VE +.sp +.SH ARGUMENTS +.AS Tcl_EolTranslation *channelName in +.AP 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 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. +.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. +.VS +.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. +.VE +.AP Tcl_EolTranslation transMode in +The translation mode; one of the constants \fBTCL_TRANSLATE_AUTO\fR, +\fBTCL_TRANSLATE_CR\fR, \fBTCL_TRANSLATE_LF\fR and \fBTCL_TRANSLATE_CRLF\fR. +.AP int size in +The size, in bytes, of buffers to allocate in this channel. +.VS +.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 char *optionName in +Name of the invalid option. +.AP char *optionList in +Specific options list (space separated words, without "-") +to append to the standard generic options list. +Can be NULL for generic options error message only. +.VE + +.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 +TCL_CHANNELTYPE, 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 TCL_CHANNELTYPE, below. +.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 +.VS +\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. +.VE +.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_SetDefaultTranslation\fR sets the default end of line translation +mode. This mode will be installed as the translation mode for the channel +if an attempt is made to output on the channel while it is still in +\fBTCL_TRANSLATE_AUTO\fR mode. For a description of end of line translation +modes, see the manual entry for \fBfconfigure\fR. +.PP +\fBTcl_GetChannelBufferSize\fR returns the size, in bytes, of buffers +allocated to store input or output in \fIchan\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 ten and one million, +allowing buffers of ten bytes to one million bytes. If \fIsize\fR is +outside this range, \fBTcl_SetChannelBufferSize\fR sets the buffer size to +4096. +.PP +.VS +\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. +.VE +.PP +.VS +\fBTcl_BadChannelOption\fR is called from driver specific set or get option +procs to generate a complete error message. +.VE + +.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 +\fBTcl_ChannelType\fR structure contains the following fields: +.PP +.VS +.CS +typedef struct Tcl_ChannelType { + 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_ChannelType; +.CE +.VE +.PP +The driver must provide implementations for all functions except +\fIblockModeProc\fR, \fIseekProc\fR, \fIsetOptionProc\fR, and +\fIgetOptionProc\fR, which may be specified as NULL to indicate that the +channel does not support seeking. Other functions that can not be +implemented for this type of device should return \fBEINVAL\fR when invoked +to indicate that they are not implemented. + +.SH 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. + +.SH 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 Tcl_DriverBlockModeProc( + 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. + +.SH CLOSEPROC +.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 Tcl_DriverCloseProc( + 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 \fIinterp->result\fR. + +.SH 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 Tcl_DriverInputProc( + 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. + +.SH 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 Tcl_DriverOutputProc( + ClientData \fIinstanceData\fR, + 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. + +.SH SEEKPROC +.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 Tcl_DriverSeekProc( + 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_SeekChannel\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. + +.SH 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 Tcl_DriverSetOptionProc( + ClientData \fIinstanceData\fR, + Tcl_Interp *\fIinterp\fR, + char *\fIoptionName\fR, + char *\fIoptionValue\fR); +.CE +.PP +\fIoptionName\fR is the name of an option to set, and \fIoptionValue\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. +.VS +It should call \fBTcl_BadChannelOption\fR which itself returns +\fBTCL_ERROR\fR if the \fIoptionName\fR is +unrecognized. +.VE +If \fIoptionValue\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. + +.SH 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 Tcl_DriverGetOptionProc( + ClientData \fIinstanceData\fR, +.VS + Tcl_Interp *\fIinterp\fR, +.VE + char *\fIoptionName\fR, + Tcl_DString *\fIdsPtr\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 \fIdsPtr\fR. +If \fIoptionName\fR is NULL, the function stores in \fIdsPtr\fR an +alternating list of all supported options and their current values. +On success, the function returns \fBTCL_OK\fR. +.VS +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 +\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. +.VE +.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. + +.SH WATCHPROC +.VS +.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 Tcl_DriverWatchProc( + ClientData \fIinstanceData\fR, + int \fImask\fR); +.CE +.VE +.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 +.VS +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. + +.SH 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 Tcl_DriverGetHandleProc( + ClientData \fIinstanceData\fR, + int \fIdirection\fR, + ClientData *\fIhandlePtr\fR); +.CE +.PP +\fIInstanceData 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. +.VE + +.VS +.SH TCL_BADCHANNELOPTION +.PP +This procedure generates a "bad option" error message in an +(optional) interpreter. It is used by channel drivers when +a 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 return \fBTCL_ERROR\fR +.PP +An error message is generated in interp's result object to +indicate that a command was invoked with the a bad option +The message has the form +.CS + bad option "blah": should be one of + <...generic options...>+<...specific options...> +so you get for instance: + bad option "-blah": should be one of -blocking, + -buffering, -buffersize, -eofchar, -translation, + -peername, or -sockname +when called with optionList="peername sockname" +.CE +"blah" is the optionName argument and "<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 "or" before the last option. +.VE + +.SH "SEE ALSO" +Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3), Tcl_QueueEvent(3) + +.SH KEYWORDS +blocking, channel driver, channel registration, channel type, nonblocking |