summaryrefslogtreecommitdiffstats
path: root/doc/CrtChannel.3
diff options
context:
space:
mode:
Diffstat (limited to 'doc/CrtChannel.3')
-rw-r--r--doc/CrtChannel.3125
1 files changed, 55 insertions, 70 deletions
diff --git a/doc/CrtChannel.3 b/doc/CrtChannel.3
index 969267d..2335de1 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,
@@ -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,
@@ -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
@@ -859,7 +846,7 @@ 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
@@ -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