diff options
Diffstat (limited to 'doc/CrtChannel.3')
| -rw-r--r-- | doc/CrtChannel.3 | 135 |
1 files changed, 60 insertions, 75 deletions
diff --git a/doc/CrtChannel.3 b/doc/CrtChannel.3 index 969267d..6ef94b5 100644 --- a/doc/CrtChannel.3 +++ b/doc/CrtChannel.3 @@ -20,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 * @@ -96,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) @@ -127,7 +125,9 @@ 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. @@ -157,9 +157,7 @@ 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 @@ -213,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 @@ -252,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 @@ -288,20 +286,16 @@ 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 channel handlers and event scripts associated with the specified \fIchannel\fR, thus shutting @@ -316,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; @@ -334,10 +329,8 @@ 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 @@ -358,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. @@ -385,11 +376,9 @@ 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). -.VS 8.5 \fBTCL_CHANNEL_VERSION_5\fR must be set to specify the \fItruncateProc\fR members (includes \fIwideSeekProc\fR and \fIthreadActionProc\fR). -.VE 8.5 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 @@ -398,9 +387,7 @@ 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, -.VE 8.5 \fBTCL_CHANNEL_VERSION_4\fR, \fBTCL_CHANNEL_VERSION_3\fR, \fBTCL_CHANNEL_VERSION_2\fR or \fBTCL_CHANNEL_VERSION_1\fR. @@ -411,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 @@ -446,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 @@ -468,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); @@ -499,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, @@ -543,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, @@ -582,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, @@ -612,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, @@ -634,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, @@ -652,13 +639,13 @@ 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 @@ -675,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, @@ -687,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, @@ -713,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 @@ -744,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); @@ -773,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 @@ -788,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 @@ -817,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 @@ -834,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 @@ -852,18 +839,18 @@ which returns a pointer to the function. This procedure generates a .QW "bad option" error message in an -(optional) interpreter. It is used by channel drivers when +(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: @@ -889,18 +876,18 @@ 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 @@ -915,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 |