diff options
Diffstat (limited to 'doc/CrtChannel.3')
| -rw-r--r-- | doc/CrtChannel.3 | 182 |
1 files changed, 88 insertions, 94 deletions
diff --git a/doc/CrtChannel.3 b/doc/CrtChannel.3 index f4ff280..6ef94b5 100644 --- a/doc/CrtChannel.3 +++ b/doc/CrtChannel.3 @@ -4,10 +4,8 @@ '\" '\" 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.32 2005/10/05 20:36:16 andreas_kupries Exp $ -.so man.macros .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 @@ -22,7 +20,7 @@ Tcl_Channel ClientData \fBTcl_GetChannelInstanceData\fR(\fIchannel\fR) .sp -Tcl_ChannelType * +const Tcl_ChannelType * \fBTcl_GetChannelType\fR(\fIchannel\fR) .sp const char * @@ -98,10 +96,8 @@ Tcl_DriverWideSeekProc * Tcl_DriverThreadActionProc * \fBTcl_ChannelThreadActionProc\fR(\fItypePtr\fR) .sp -.VS 8.5 Tcl_DriverTruncateProc * \fBTcl_ChannelTruncateProc\fR(\fItypePtr\fR) -.VE 8.5 .sp Tcl_DriverSetOptionProc * \fBTcl_ChannelSetOptionProc\fR(\fItypePtr\fR) @@ -122,14 +118,16 @@ Tcl_DriverHandlerProc * \fBTcl_ChannelHandlerProc\fR(\fItypePtr\fR) .sp .SH ARGUMENTS -.AS Tcl_ChannelType *channelName -.AP Tcl_ChannelType *typePtr in +.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. +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. @@ -155,12 +153,11 @@ 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 "-") +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 @@ -214,7 +211,7 @@ 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 behaviour of the Tcl library with +about standard channels and the behavior of the Tcl library with regard to them. .PP \fBTcl_GetChannelInstanceData\fR returns the instance data associated with @@ -253,8 +250,8 @@ 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 +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 @@ -289,22 +286,18 @@ name is registered in the (thread)-global list of all channels (result (thread)global list of all channels (of the current thread). Application to a channel still registered in some interpreter is not allowed. -.VS 8.5 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. -.VE 8.5 .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. -.VS 8.5 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. -.VE 8.5 .PP -\fBTcl_ClearChannelHandlers\fR removes all channelhandlers and event +\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 @@ -317,9 +310,10 @@ 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 { - char *\fItypeName\fR; + const char *\fItypeName\fR; Tcl_ChannelTypeVersion \fIversion\fR; Tcl_DriverCloseProc *\fIcloseProc\fR; Tcl_DriverInputProc *\fIinputProc\fR; @@ -335,16 +329,14 @@ typedef struct Tcl_ChannelType { Tcl_DriverHandlerProc *\fIhandlerProc\fR; Tcl_DriverWideSeekProc *\fIwideSeekProc\fR; Tcl_DriverThreadActionProc *\fIthreadActionProc\fR; -.VS 8.5 Tcl_DriverTruncateProc *\fItruncateProc\fR; -.VE 8.5 -} Tcl_ChannelType; +} \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, and \fIclose2Proc\fR, in addition to +\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 @@ -359,9 +351,7 @@ structure, the following functions should be used to obtain the values: \fBTcl_ChannelClose2Proc\fR, \fBTcl_ChannelInputProc\fR, \fBTcl_ChannelOutputProc\fR, \fBTcl_ChannelSeekProc\fR, \fBTcl_ChannelWideSeekProc\fR, \fBTcl_ChannelThreadActionProc\fR, -.VS 8.5 \fBTcl_ChannelTruncateProc\fR, -.VE 8.5 \fBTcl_ChannelSetOptionProc\fR, \fBTcl_ChannelGetOptionProc\fR, \fBTcl_ChannelWatchProc\fR, \fBTcl_ChannelGetHandleProc\fR, \fBTcl_ChannelFlushProc\fR, or \fBTcl_ChannelHandlerProc\fR. @@ -383,12 +373,12 @@ a pointer to the string. 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 specifiy the \fIwideSeekProc\fR member. -.VS 8.5 -\fBTCL_CHANNEL_VERSION_4\fR must be set to specifiy the -\fIthreadActionProc\fR and \fItruncateProc\fR members (includes -\fIwideSeekProc\fR). -.VE 8.5 +\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 @@ -397,9 +387,8 @@ least \fBTCL_CHANNEL_VERSION_2\fR to function correctly. .PP This value can be retrieved with \fBTcl_ChannelVersion\fR, which returns one of -.VS 8.5 +\fBTCL_CHANNEL_VERSION_5\fR, \fBTCL_CHANNEL_VERSION_4\fR, -.VE 8.5 \fBTCL_CHANNEL_VERSION_3\fR, \fBTCL_CHANNEL_VERSION_2\fR or \fBTCL_CHANNEL_VERSION_1\fR. .SS BLOCKMODEPROC @@ -409,7 +398,7 @@ 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( +typedef int \fBTcl_DriverBlockModeProc\fR( ClientData \fIinstanceData\fR, int \fImode\fR); .CE @@ -435,7 +424,7 @@ 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 -inacceptable value. Any confusion here may lead the interpreter into a +unacceptable value. Any confusion here may lead the interpreter into a (spurious and difficult to find) deadlock. .SS "CLOSEPROC AND CLOSE2PROC" .PP @@ -444,7 +433,7 @@ 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( +typedef int \fBTcl_DriverCloseProc\fR( ClientData \fIinstanceData\fR, Tcl_Interp *\fIinterp\fR); .CE @@ -466,7 +455,7 @@ independently may set \fIcloseProc\fR to \fBTCL_CLOSE2PROC\fR and set following prototype: .PP .CS -typedef int Tcl_DriverClose2Proc( +typedef int \fBTcl_DriverClose2Proc\fR( ClientData \fIinstanceData\fR, Tcl_Interp *\fIinterp\fR, int \fIflags\fR); @@ -497,7 +486,7 @@ 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( +typedef int \fBTcl_DriverInputProc\fR( ClientData \fIinstanceData\fR, char *\fIbuf\fR, int \fIbufSize\fR, @@ -541,7 +530,7 @@ 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( +typedef int \fBTcl_DriverOutputProc\fR( ClientData \fIinstanceData\fR, const char *\fIbuf\fR, int \fItoWrite\fR, @@ -580,7 +569,7 @@ operations will be applied. \fISeekProc\fR must match the following prototype: .PP .CS -typedef int Tcl_DriverSeekProc( +typedef int \fBTcl_DriverSeekProc\fR( ClientData \fIinstanceData\fR, long \fIoffset\fR, int \fIseekMode\fR, @@ -610,7 +599,7 @@ in preference to the \fIseekProc\fR, but both must be defined if the following prototype: .PP .CS -typedef Tcl_WideInt Tcl_DriverWideSeekProc( +typedef Tcl_WideInt \fBTcl_DriverWideSeekProc\fR( ClientData \fIinstanceData\fR, Tcl_WideInt \fIoffset\fR, int \fIseekMode\fR, @@ -632,7 +621,7 @@ 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( +typedef int \fBTcl_DriverSetOptionProc\fR( ClientData \fIinstanceData\fR, Tcl_Interp *\fIinterp\fR, const char *\fIoptionName\fR, @@ -646,17 +635,17 @@ 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 +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. +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. +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 @@ -673,7 +662,7 @@ 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( +typedef int \fBTcl_DriverGetOptionProc\fR( ClientData \fIinstanceData\fR, Tcl_Interp *\fIinterp\fR, const char *\fIoptionName\fR, @@ -685,7 +674,7 @@ 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. +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, @@ -695,7 +684,7 @@ 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 +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 @@ -711,7 +700,7 @@ notice events of interest on this channel. \fIWatchProc\fR should match the following prototype: .PP .CS -typedef void Tcl_DriverWatchProc( +typedef void \fBTcl_DriverWatchProc\fR( ClientData \fIinstanceData\fR, int \fImask\fR); .CE @@ -742,7 +731,7 @@ 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( +typedef int \fBTcl_DriverGetHandleProc\fR( ClientData \fIinstanceData\fR, int \fIdirection\fR, ClientData *\fIhandlePtr\fR); @@ -771,7 +760,7 @@ It should be set to NULL. \fIFlushProc\fR should match the following prototype: .PP .CS -typedef int Tcl_DriverFlushProc( +typedef int \fBTcl_DriverFlushProc\fR( ClientData \fIinstanceData\fR); .CE .PP @@ -786,7 +775,7 @@ that occur on the underlying (stacked) channel. \fIHandlerProc\fR should match the following prototype: .PP .CS -typedef int Tcl_DriverHandlerProc( +typedef int \fBTcl_DriverHandlerProc\fR( ClientData \fIinstanceData\fR, int \fIinterestMask\fR); .CE @@ -815,9 +804,9 @@ 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 Tcl_DriverThreadActionProc( +typedef void \fBTcl_DriverThreadActionProc\fR( ClientData \fIinstanceData\fR, - int \fIaction\fR); + int \fIaction\fR); .CE .PP \fIInstanceData\fR is the same as the value passed to @@ -832,7 +821,7 @@ called by the generic layer when a channel is truncated to some length. It can be NULL. .PP .CS -typedef int Tcl_DriverTruncateProc( +typedef int \fBTcl_DriverTruncateProc\fR( ClientData \fIinstanceData\fR, Tcl_WideInt \fIlength\fR); .CE @@ -847,19 +836,21 @@ These values can be retrieved with \fBTcl_ChannelTruncateProc\fR, which returns a pointer to the function. .SH TCL_BADCHANNELOPTION .PP -This procedure generates a "bad option" error message in an -(optional) interpreter. It is used by channel drivers when +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 object to +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 + bad option "blah": should be one of <...generic options...>+<...specific options...> .CE so you get for instance: @@ -868,30 +859,35 @@ so you get for instance: -buffering, -buffersize, -eofchar, -translation, -peername, or -sockname .CE -when called with \fIoptionList\fR="peername sockname" +when called with \fIoptionList\fR equal to +.QW "peername sockname" .PP -``blah'' is the \fIoptionName\fR argument and ``<specific options>'' +.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 ``or'' before the last option. +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 { - 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; + 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 @@ -906,29 +902,27 @@ contained the following fields: .PP .CS typedef struct Tcl_ChannelType { - 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; -} 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 |