diff options
Diffstat (limited to 'doc/CrtChannel.3')
| -rw-r--r-- | doc/CrtChannel.3 | 248 |
1 files changed, 208 insertions, 40 deletions
diff --git a/doc/CrtChannel.3 b/doc/CrtChannel.3 index f95f653..6feeac3 100644 --- a/doc/CrtChannel.3 +++ b/doc/CrtChannel.3 @@ -1,16 +1,17 @@ '\" '\" 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. '\" -'\" RCS: @(#) $Id: CrtChannel.3,v 1.5 2000/04/14 23:01:49 hobbs Exp $ +'\" RCS: @(#) $Id: CrtChannel.3,v 1.5.2.1 2000/08/08 00:57:52 hobbs Exp $ .so man.macros -.TH Tcl_CreateChannel 3 8.0 Tcl "Tcl Library Procedures" +.TH Tcl_CreateChannel 3 8.3 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_SetChannelBufferSize, Tcl_NotifyChannel, Tcl_BadChannelOption \- procedures for creating and manipulating channels +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_ChannelSetOptionProc, Tcl_ChannelGetOptionProc, Tcl_ChannelWatchProc, Tcl_ChannelGetHandleProc, Tcl_ChannelFlushProc, Tcl_ChannelHandlerProc, \- procedures for creating and manipulating channels .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -26,22 +27,62 @@ Tcl_ChannelType * .sp char * \fBTcl_GetChannelName\fR(\fIchannel\fR) -.VS .sp int \fBTcl_GetChannelHandle\fR(\fIchannel, direction, handlePtr\fR) -.VE .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) +.VS 8.3.2 +.sp +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_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) .VE .sp .SH ARGUMENTS @@ -61,20 +102,17 @@ 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 @@ -87,7 +125,6 @@ Name of the invalid option. 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 @@ -151,7 +188,6 @@ the same as the \fItypePtr\fR argument in the call to 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 @@ -159,7 +195,6 @@ 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 @@ -177,31 +212,29 @@ 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: +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\fR section below for details about +the old structure. .PP -.VS +The \fBTcl_ChannelType\fR structure contains the following fields: .CS typedef struct Tcl_ChannelType { char *\fItypeName\fR; - Tcl_DriverBlockModeProc *\fIblockModeProc\fR; + Tcl_ChannelTypeVersion \fIversion\fR; Tcl_DriverCloseProc *\fIcloseProc\fR; Tcl_DriverInputProc *\fIinputProc\fR; Tcl_DriverOutputProc *\fIoutputProc\fR; @@ -211,24 +244,62 @@ typedef struct Tcl_ChannelType { 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_ChannelType; .CE -.VE .PP The driver must provide implementations for all functions except \fIblockModeProc\fR, \fIseekProc\fR, \fIsetOptionProc\fR, -.VS \fIgetOptionProc\fR, and \fIclose2Proc\fR, which may be specified as -.VE NULL. 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. +are not implemented, except in the case of \fIflushProc\fR and +\fIhandlerProc\fR, which should specified as NULL if not otherwise defined. +.PP +.VS 8.3.2 +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_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 (ie: TLS, Trf) have new versions to correspond to the above change +since the previous code for stacked channels had problems. +.VE .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. +.PP +.VS 8.3.2 +This value can be retried with \fBTcl_ChannelName\fR, which returns +a pointer to the string. +.VE + +.VS 8.3.2 +.SH VERSION +.PP +The \fIversion\fR field should be set to \fBTCL_CHANNEL_VERSION_2\fR. +If it is not set to this value \fBTCL_CHANNEL_VERSION_2\fR, then this +\fBTcl_ChannelType\fR is assumed to have the older structure. See +\fBOLD_CHANNEL\fR for more details. While Tcl will recognize and +function with either structure, stacked channels must be of the newer +style to function correctly. +.PP +This value can be retried with \fBTcl_ChannelVersion\fR, which returns +either \fBTCL_CHANNEL_VERSION_2\fR or \fBTCL_CHANNEL_VERSION_1\fR. +.VE .SH BLOCKMODEPROC .PP @@ -255,6 +326,11 @@ 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 +.VS 8.3.2 +This value can be retried with \fBTcl_ChannelBlockModeProc\fR, which returns +a pointer to the function. +.VE .SH "CLOSEPROC AND CLOSE2PROC" .PP @@ -279,7 +355,6 @@ 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 -.VS 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 @@ -306,6 +381,11 @@ 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 +.VS 8.3.2 +These value can be retried with \fBTcl_ChannelCloseProc\fR or +\fBTcl_ChannelClose2Proc\fR, which returns a pointer to the respective +function. .VE .SH INPUTPROC @@ -349,6 +429,11 @@ 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 +.VS 8.3.2 +This value can be retried with \fBTcl_ChannelInputProc\fR, which returns +a pointer to the function. +.VE .SH OUTPUTPROC .PP @@ -385,6 +470,11 @@ error, some data may have been written to the device. 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 +.VS 8.3.2 +This value can be retried with \fBTcl_ChannelOutputProc\fR, which returns +a pointer to the function. +.VE .SH SEEKPROC .PP @@ -414,6 +504,11 @@ 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 +.VS 8.3.2 +This value can be retried with \fBTcl_ChannelSeekProc\fR, which returns +a pointer to the function. +.VE .SH SETOPTIONPROC .PP @@ -444,17 +539,20 @@ 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. +.PP +.VS 8.3.2 +This value can be retried with \fBTcl_ChannelSetOptionProc\fR, which returns +a pointer to the function. +.VE .SH GETOPTIONPROC .PP @@ -465,9 +563,7 @@ channel. \fIgetOptionProc\fR must match the following prototype: .CS typedef int Tcl_DriverGetOptionProc( ClientData \fIinstanceData\fR, -.VS Tcl_Interp *\fIinterp\fR, -.VE char *\fIoptionName\fR, Tcl_DString *\fIdsPtr\fR); .CE @@ -478,7 +574,6 @@ 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, @@ -486,7 +581,6 @@ 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 @@ -494,9 +588,13 @@ 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 +.VS 8.3.2 +This value can be retried with \fBTcl_ChannelGetOptionProc\fR, which returns +a pointer to the function. +.VE .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 @@ -508,7 +606,6 @@ 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 @@ -516,7 +613,6 @@ 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 @@ -527,6 +623,11 @@ 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 +.VS 8.3.2 +This value can be retried with \fBTcl_ChannelWatchProc\fR, which returns +a pointer to the function. +.VE .SH GETHANDLEPROC .PP @@ -541,7 +642,7 @@ typedef int Tcl_DriverGetHandleProc( ClientData *\fIhandlePtr\fR); .CE .PP -\fIInstanceData is the same as the value passed to +\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 @@ -554,9 +655,50 @@ 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 +.VS 8.3.2 +This value can be retried with \fBTcl_ChannelGetHandleProc\fR, which returns +a pointer to the function. +.VE + +.VS 8.3.2 +.SH 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 Tcl_DriverFlushProc( + ClientData \fIinstanceData\fR); +.CE +.PP +This value can be retried with \fBTcl_ChannelFlushProc\fR, which returns +a pointer to the function. + +.SH HANDLERPROC +.PP +The \fIhandlerProc\fR field contains the address of a function called by +the generic layer to notify the channel that an event occured. 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 Tcl_DriverHandlerProc( + 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 occured on this channel. +.PP +This value can be retried with \fBTcl_ChannelHandlerProc\fR, which returns +a pointer to the function. .VE -.VS .SH TCL_BADCHANNELOPTION .PP This procedure generates a "bad option" error message in an @@ -579,14 +721,40 @@ so you get for instance: -peername, or -sockname when called with optionList="peername sockname" .CE -"blah" is the optionName argument and "<specific options>" +``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 +each option, commas after, and an ``or'' before the last option. + +.SH OLD_CHANNEL + +The original (8.3.1 and below) \fBTcl_ChannelType\fR structure contains +the following fields: +.PP +.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_DriverClose2Proc *\fIclose2Proc\fR; +} Tcl_ChannelType; +.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). .SH "SEE ALSO" -Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3), Tcl_QueueEvent(3) +Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3), Tcl_QueueEvent(3), Tcl_StackChannel(3) .SH KEYWORDS blocking, channel driver, channel registration, channel type, nonblocking |