1Tcl_CreateChannel(3) Tcl Library Procedures Tcl_CreateChannel(3)
2______________________________________________________________________________
6
8 Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType,
9 Tcl_GetChannelName, Tcl_GetChannelHandle, Tcl_GetChannelMode,
10 Tcl_GetChannelBufferSize, Tcl_SetChannelBufferSize, Tcl_NotifyChannel,
11 Tcl_BadChannelOption, Tcl_ChannelName, Tcl_ChannelVersion, Tcl_Channel‐
12 BlockModeProc, Tcl_ChannelCloseProc, Tcl_ChannelClose2Proc, Tcl_Chan‐
13 nelInputProc, Tcl_ChannelOutputProc, Tcl_ChannelSeekProc, Tcl_Channel‐
14 WideSeekProc, Tcl_ChannelTruncateProc, Tcl_ChannelSetOptionProc,
15 Tcl_ChannelGetOptionProc, Tcl_ChannelWatchProc, Tcl_ChannelGetH‐
16 andleProc, Tcl_ChannelFlushProc, Tcl_ChannelHandlerProc, Tcl_Chan‐
17 nelThreadActionProc, Tcl_IsChannelShared, Tcl_IsChannelRegistered,
18 Tcl_CutChannel, Tcl_SpliceChannel, Tcl_IsChannelExisting,
19 Tcl_ClearChannelHandlers, Tcl_GetChannelThread, Tcl_ChannelBuffered -
20 procedures for creating and manipulating channels
21
23 #include <tcl.h>
24 Tcl_Channel
26 Tcl_CreateChannel(typePtr, channelName, instanceData, mask)
27 ClientData
29 Tcl_GetChannelInstanceData(channel)
30 const Tcl_ChannelType *
32 Tcl_GetChannelType(channel)
33 const char *
35 Tcl_GetChannelName(channel)
36 int
38 Tcl_GetChannelHandle(channel, direction, handlePtr)
39 Tcl_ThreadId
41 Tcl_GetChannelThread(channel)
42 int
44 Tcl_GetChannelMode(channel)
45 int
47 Tcl_GetChannelBufferSize(channel)
48 Tcl_SetChannelBufferSize(channel, size)
50 Tcl_NotifyChannel(channel, mask)
52 int
54 Tcl_BadChannelOption(interp, optionName, optionList)
55 int
57 Tcl_IsChannelShared(channel)
58 int
60 Tcl_IsChannelRegistered(interp, channel)
61 int
63 Tcl_IsChannelExisting(channelName)
64 void
66 Tcl_CutChannel(channel)
67 void
69 Tcl_SpliceChannel(channel)
70 void
72 Tcl_ClearChannelHandlers(channel)
73 int
75 Tcl_ChannelBuffered(channel)
76 const char *
78 Tcl_ChannelName(typePtr)
79 Tcl_ChannelTypeVersion
81 Tcl_ChannelVersion(typePtr)
82 Tcl_DriverBlockModeProc *
84 Tcl_ChannelBlockModeProc(typePtr)
85 Tcl_DriverCloseProc *
87 Tcl_ChannelCloseProc(typePtr)
88 Tcl_DriverClose2Proc *
90 Tcl_ChannelClose2Proc(typePtr)
91 Tcl_DriverInputProc *
93 Tcl_ChannelInputProc(typePtr)
94 Tcl_DriverOutputProc *
96 Tcl_ChannelOutputProc(typePtr)
97 Tcl_DriverSeekProc *
99 Tcl_ChannelSeekProc(typePtr)
100 Tcl_DriverWideSeekProc *
102 Tcl_ChannelWideSeekProc(typePtr)
103 Tcl_DriverThreadActionProc *
105 Tcl_ChannelThreadActionProc(typePtr)
106 Tcl_DriverTruncateProc *
108 Tcl_ChannelTruncateProc(typePtr)
109 Tcl_DriverSetOptionProc *
111 Tcl_ChannelSetOptionProc(typePtr)
112 Tcl_DriverGetOptionProc *
114 Tcl_ChannelGetOptionProc(typePtr)
115 Tcl_DriverWatchProc *
117 Tcl_ChannelWatchProc(typePtr)
118 Tcl_DriverGetHandleProc *
120 Tcl_ChannelGetHandleProc(typePtr)
121 Tcl_DriverFlushProc *
123 Tcl_ChannelFlushProc(typePtr)
124 Tcl_DriverHandlerProc *
126 Tcl_ChannelHandlerProc(typePtr)
127
130 const Tcl_ChannelType *typePtr (in) Points to a structure
131 containing the
132 addresses of proce‐
133 dures that can be
134 called to perform I/O
135 and other functions on
136 the channel.
137 const char *channelName (in) The name of this chan‐
139 nel, such as file3;
140 must not be in use by
141 any other channel. Can
142 be NULL, in which case
143 the channel is created
144 without a name. If the
145 created channel is
146 assigned to one of the
147 standard channels
148 (stdin, stdout or
149 stderr), the assigned
150 channel name will be
151 the name of the stan‐
152 dard channel.
153 ClientData instanceData (in) Arbitrary one-word
155 value to be associated
156 with this channel.
157 This value is passed
158 to procedures in type‐
159 Ptr when they are
160 invoked.
161 int mask (in) OR-ed combination of
163 TCL_READABLE and
164 TCL_WRITABLE to indi‐
165 cate whether a channel
166 is readable and
167 writable.
168 Tcl_Channel channel (in) The channel to operate
170 on.
171 int direction (in) TCL_READABLE means the
173 input handle is
174 wanted; TCL_WRITABLE
175 means the output han‐
176 dle is wanted.
177 ClientData *handlePtr (out) Points to the location
179 where the desired OS-
180 specific handle should
181 be stored.
182 int size (in) The size, in bytes, of
184 buffers to allocate in
185 this channel.
186 int mask (in) An OR-ed combination
188 of TCL_READABLE,
189 TCL_WRITABLE and
190 TCL_EXCEPTION that
191 indicates events that
192 have occurred on this
193 channel.
194 Tcl_Interp *interp (in) Current interpreter.
196 (can be NULL)
197 const char *optionName (in) Name of the invalid
199 option.
200 const char *optionList (in) Specific options list
202 (space separated
203 words, without “-”) to
204 append to the standard
205 generic options list.
206 Can be NULL for
207 generic options error
208 message only.
209______________________________________________________________________________
210
212 Tcl uses a two-layered channel architecture. It provides a generic
213 upper layer to enable C and Tcl programs to perform input and output
214 using the same APIs for a variety of files, devices, sockets etc. The
215 generic C APIs are described in the manual entry for Tcl_OpenFileChan‐
216 nel.
217 The lower layer provides type-specific channel drivers for each type of
219 device supported on each platform. This manual entry describes the C
220 APIs used to communicate between the generic layer and the type-spe‐
221 cific channel drivers. It also explains how new types of channels can
222 be added by providing new channel drivers.
223 Channel drivers consist of a number of components: First, each channel
225 driver provides a Tcl_ChannelType structure containing pointers to
226 functions implementing the various operations used by the generic layer
227 to communicate with the channel driver. The Tcl_ChannelType structure
228 and the functions referenced by it are described in the section
229 TCL_CHANNELTYPE, below.
230 Second, channel drivers usually provide a Tcl command to create
232 instances of that type of channel. For example, the Tcl open command
233 creates channels that use the file and command channel drivers, and the
234 Tcl socket command creates channels that use TCP sockets for network
235 communication.
236 Third, a channel driver optionally provides a C function to open chan‐
238 nel instances of that type. For example, Tcl_OpenFileChannel opens a
239 channel that uses the file channel driver, and Tcl_OpenTcpClient opens
240 a channel that uses the TCP network protocol. These creation functions
241 typically use Tcl_CreateChannel internally to open the channel.
242 To add a new type of channel you must implement a C API or a Tcl com‐
244 mand that opens a channel by invoking Tcl_CreateChannel. When your
245 driver calls Tcl_CreateChannel it passes in a Tcl_ChannelType structure
246 describing the driver's I/O procedures. The generic layer will then
247 invoke the functions referenced in that structure to perform operations
248 on the channel.
249 Tcl_CreateChannel opens a new channel and associates the supplied type‐
251 Ptr and instanceData with it. The channel is opened in the mode indi‐
252 cated by mask. For a discussion of channel drivers, their operations
253 and the Tcl_ChannelType structure, see the section TCL_CHANNELTYPE,
254 below.
255 Tcl_CreateChannel interacts with the code managing the standard chan‐
257 nels. Once a standard channel was initialized either through a call to
258 Tcl_GetStdChannel or a call to Tcl_SetStdChannel closing this standard
259 channel will cause the next call to Tcl_CreateChannel to make the new
260 channel the new standard channel too. See Tcl_StandardChannels for a
261 general treatise about standard channels and the behavior of the Tcl
262 library with regard to them.
263 Tcl_GetChannelInstanceData returns the instance data associated with
265 the channel in channel. This is the same as the instanceData argument
266 in the call to Tcl_CreateChannel that created this channel.
267 Tcl_GetChannelType returns a pointer to the Tcl_ChannelType structure
269 used by the channel in the channel argument. This is the same as the
270 typePtr argument in the call to Tcl_CreateChannel that created this
271 channel.
272 Tcl_GetChannelName returns a string containing the name associated with
274 the channel, or NULL if the channelName argument to Tcl_CreateChannel
275 was NULL.
276 Tcl_GetChannelHandle places the OS-specific device handle associated
278 with channel for the given direction in the location specified by han‐
279 dlePtr and returns TCL_OK. If the channel does not have a device han‐
280 dle for the specified direction, then TCL_ERROR is returned instead.
281 Different channel drivers will return different types of handle. Refer
282 to the manual entries for each driver to determine what type of handle
283 is returned.
284 Tcl_GetChannelThread returns the id of the thread currently managing
286 the specified channel. This allows channel drivers to send their file
287 events to the correct event queue even for a multi-threaded core.
288 Tcl_GetChannelMode returns an OR-ed combination of TCL_READABLE and
290 TCL_WRITABLE, indicating whether the channel is open for input and out‐
291 put.
292 Tcl_GetChannelBufferSize returns the size, in bytes, of buffers allo‐
294 cated to store input or output in channel. If the value was not set by
295 a previous call to Tcl_SetChannelBufferSize, described below, then the
296 default value of 4096 is returned.
297 Tcl_SetChannelBufferSize sets the size, in bytes, of buffers that will
299 be allocated in subsequent operations on the channel to store input or
300 output. The size argument should be between one and one million, allow‐
301 ing buffers of one byte to one million bytes. If size is outside this
302 range, Tcl_SetChannelBufferSize sets the buffer size to 4096.
303 Tcl_NotifyChannel is called by a channel driver to indicate to the
305 generic layer that the events specified by mask have occurred on the
306 channel. Channel drivers are responsible for invoking this function
307 whenever the channel handlers need to be called for the channel. See
308 WATCHPROC below for more details.
309 Tcl_BadChannelOption is called from driver specific setOptionProc or
311 getOptionProc to generate a complete error message.
312 Tcl_ChannelBuffered returns the number of bytes of input currently
314 buffered in the internal buffer (push back area) of the channel itself.
315 It does not report about the data in the overall buffers for the stack
316 of channels the supplied channel is part of.
317 Tcl_IsChannelShared checks the refcount of the specified channel and
319 returns whether the channel was shared among multiple interpreters
320 (result == 1) or not (result == 0).
321 Tcl_IsChannelRegistered checks whether the specified channel is regis‐
323 tered in the given interpreter (result == 1) or not (result == 0).
324 Tcl_IsChannelExisting checks whether a channel with the specified name
326 is registered in the (thread)-global list of all channels (result == 1)
327 or not (result == 0).
328 Tcl_CutChannel removes the specified channel from the (thread)global
330 list of all channels (of the current thread). Application to a channel
331 still registered in some interpreter is not allowed. Also notifies the
332 driver if the Tcl_ChannelType version is TCL_CHANNEL_VERSION_4 (or
333 higher), and Tcl_DriverThreadActionProc is defined for it.
334 Tcl_SpliceChannel adds the specified channel to the (thread)global list
336 of all channels (of the current thread). Application to a channel reg‐
337 istered in some interpreter is not allowed. Also notifies the driver
338 if the Tcl_ChannelType version is TCL_CHANNEL_VERSION_4 (or higher),
339 and Tcl_DriverThreadActionProc is defined for it.
340 Tcl_ClearChannelHandlers removes all channel handlers and event scripts
342 associated with the specified channel, thus shutting down all event
343 processing for this channel.
344
346 A channel driver provides a Tcl_ChannelType structure that contains
347 pointers to functions that implement the various operations on a chan‐
348 nel; these operations are invoked as needed by the generic layer. The
349 structure was versioned starting in Tcl 8.3.2/8.4 to correct a problem
350 with stacked channel drivers. See the OLD CHANNEL TYPES section below
351 for details about the old structure.
352 The Tcl_ChannelType structure contains the following fields:
354 typedef struct Tcl_ChannelType {
356 const char *typeName;
357 Tcl_ChannelTypeVersion version;
358 Tcl_DriverCloseProc *closeProc;
359 Tcl_DriverInputProc *inputProc;
360 Tcl_DriverOutputProc *outputProc;
361 Tcl_DriverSeekProc *seekProc;
362 Tcl_DriverSetOptionProc *setOptionProc;
363 Tcl_DriverGetOptionProc *getOptionProc;
364 Tcl_DriverWatchProc *watchProc;
365 Tcl_DriverGetHandleProc *getHandleProc;
366 Tcl_DriverClose2Proc *close2Proc;
367 Tcl_DriverBlockModeProc *blockModeProc;
368 Tcl_DriverFlushProc *flushProc;
369 Tcl_DriverHandlerProc *handlerProc;
370 Tcl_DriverWideSeekProc *wideSeekProc;
371 Tcl_DriverThreadActionProc *threadActionProc;
372 Tcl_DriverTruncateProc *truncateProc;
373 } Tcl_ChannelType;
374 It is not necessary to provide implementations for all channel opera‐
376 tions. Those which are not necessary may be set to NULL in the struct:
377 blockModeProc, seekProc, setOptionProc, getOptionProc, getHandleProc,
378 and close2Proc, in addition to flushProc, handlerProc, threadAction‐
379 Proc, and truncateProc. Other functions that cannot be implemented in
380 a meaningful way should return EINVAL when called, to indicate that the
381 operations they represent are not available. Also note that
382 wideSeekProc can be NULL if seekProc is.
383 The user should only use the above structure for Tcl_ChannelType
385 instantiation. When referencing fields in a Tcl_ChannelType structure,
386 the following functions should be used to obtain the values: Tcl_Chan‐
387 nelName, Tcl_ChannelVersion, Tcl_ChannelBlockModeProc, Tcl_Channel‐
388 CloseProc, Tcl_ChannelClose2Proc, Tcl_ChannelInputProc, Tcl_ChannelOut‐
389 putProc, Tcl_ChannelSeekProc, Tcl_ChannelWideSeekProc, Tcl_Chan‐
390 nelThreadActionProc, Tcl_ChannelTruncateProc, Tcl_ChannelSetOptionProc,
391 Tcl_ChannelGetOptionProc, Tcl_ChannelWatchProc, Tcl_ChannelGetH‐
392 andleProc, Tcl_ChannelFlushProc, or Tcl_ChannelHandlerProc.
393 The change to the structures was made in such a way that standard chan‐
395 nel types are binary compatible. However, channel types that use
396 stacked channels (i.e. TLS, Trf) have new versions to correspond to the
397 above change since the previous code for stacked channels had problems.
398 TYPENAME
400 The typeName field contains a null-terminated string that identifies
401 the type of the device implemented by this driver, e.g. file or
402 socket.
403 This value can be retrieved with Tcl_ChannelName, which returns a
405 pointer to the string.
406 VERSION
408 The version field should be set to the version of the structure that
409 you require. TCL_CHANNEL_VERSION_2 is the minimum recommended.
410 TCL_CHANNEL_VERSION_3 must be set to specify the wideSeekProc member.
411 TCL_CHANNEL_VERSION_4 must be set to specify the threadActionProc mem‐
412 ber (includes wideSeekProc). TCL_CHANNEL_VERSION_5 must be set to
413 specify the truncateProc members (includes wideSeekProc and threadAc‐
414 tionProc). If it is not set to any of these, then this Tcl_ChannelType
415 is assumed to have the original structure. See OLD CHANNEL TYPES for
416 more details. While Tcl will recognize and function with either struc‐
417 tures, stacked channels must be of at least TCL_CHANNEL_VERSION_2 to
418 function correctly.
419 This value can be retrieved with Tcl_ChannelVersion, which returns one
421 of TCL_CHANNEL_VERSION_5, TCL_CHANNEL_VERSION_4, TCL_CHANNEL_VERSION_3,
422 TCL_CHANNEL_VERSION_2 or TCL_CHANNEL_VERSION_1.
423 BLOCKMODEPROC
425 The blockModeProc field contains the address of a function called by
426 the generic layer to set blocking and nonblocking mode on the device.
427 BlockModeProc should match the following prototype:
428 typedef int Tcl_DriverBlockModeProc(
430 ClientData instanceData,
431 int mode);
432 The instanceData is the same as the value passed to Tcl_CreateChannel
434 when this channel was created. The mode argument is either
435 TCL_MODE_BLOCKING or TCL_MODE_NONBLOCKING to set the device into block‐
436 ing or nonblocking mode. The function should return zero if the opera‐
437 tion was successful, or a nonzero POSIX error code if the operation
438 failed.
439 If the operation is successful, the function can modify the supplied
441 instanceData to record that the channel entered blocking or nonblocking
442 mode and to implement the blocking or nonblocking behavior. For some
443 device types, the blocking and nonblocking behavior can be implemented
444 by the underlying operating system; for other device types, the behav‐
445 ior must be emulated in the channel driver.
446 This value can be retrieved with Tcl_ChannelBlockModeProc, which
448 returns a pointer to the function.
449 A channel driver not supplying a blockModeProc has to be very, very
451 careful. It has to tell the generic layer exactly which blocking mode
452 is acceptable to it, and should this also document for the user so that
453 the blocking mode of the channel is not changed to an unacceptable
454 value. Any confusion here may lead the interpreter into a (spurious and
455 difficult to find) deadlock.
456 CLOSEPROC AND CLOSE2PROC
458 The closeProc field contains the address of a function called by the
459 generic layer to clean up driver-related information when the channel
460 is closed. CloseProc must match the following prototype:
461 typedef int Tcl_DriverCloseProc(
463 ClientData instanceData,
464 Tcl_Interp *interp);
465 The instanceData argument is the same as the value provided to Tcl_Cre‐
467 ateChannel when the channel was created. The function should release
468 any storage maintained by the channel driver for this channel, and
469 close the input and output devices encapsulated by this channel. All
470 queued output will have been flushed to the device before this function
471 is called, and no further driver operations will be invoked on this
472 instance after calling the closeProc. If the close operation is suc‐
473 cessful, the procedure should return zero; otherwise it should return a
474 nonzero POSIX error code. In addition, if an error occurs and interp is
475 not NULL, the procedure should store an error message in the inter‐
476 preter's result.
477 Alternatively, channels that support closing the read and write sides
479 independently may set closeProc to TCL_CLOSE2PROC and set close2Proc to
480 the address of a function that matches the following prototype:
481 typedef int Tcl_DriverClose2Proc(
483 ClientData instanceData,
484 Tcl_Interp *interp,
485 int flags);
486 The close2Proc will be called with flags set to an OR'ed combination of
488 TCL_CLOSE_READ or TCL_CLOSE_WRITE to indicate that the driver should
489 close the read and/or write side of the channel. The channel driver
490 may be invoked to perform additional operations on the channel after
491 close2Proc is called to close one or both sides of the channel. If
492 flags is 0 (zero), the driver should close the channel in the manner
493 described above for closeProc. No further operations will be invoked
494 on this instance after close2Proc is called with all flags cleared. In
495 all cases, the close2Proc function should return zero if the close
496 operation was successful; otherwise it should return a nonzero POSIX
497 error code. In addition, if an error occurs and interp is not NULL, the
498 procedure should store an error message in the interpreter's result.
499 The closeProc and close2Proc values can be retrieved with Tcl_Channel‐
501 CloseProc or Tcl_ChannelClose2Proc, which return a pointer to the
502 respective function.
503 INPUTPROC
505 The inputProc field contains the address of a function called by the
506 generic layer to read data from the file or device and store it in an
507 internal buffer. InputProc must match the following prototype:
508 typedef int Tcl_DriverInputProc(
510 ClientData instanceData,
511 char *buf,
512 int bufSize,
513 int *errorCodePtr);
514 InstanceData is the same as the value passed to Tcl_CreateChannel when
516 the channel was created. The buf argument points to an array of bytes
517 in which to store input from the device, and the bufSize argument indi‐
518 cates how many bytes are available at buf.
519 The errorCodePtr argument points to an integer variable provided by the
521 generic layer. If an error occurs, the function should set the variable
522 to a POSIX error code that identifies the error that occurred.
523 The function should read data from the input device encapsulated by the
525 channel and store it at buf. On success, the function should return a
526 nonnegative integer indicating how many bytes were read from the input
527 device and stored at buf. On error, the function should return -1. If
528 an error occurs after some data has been read from the device, that
529 data is lost.
530 If inputProc can determine that the input device has some data avail‐
532 able but less than requested by the bufSize argument, the function
533 should only attempt to read as much data as is available and return
534 without blocking. If the input device has no data available whatsoever
535 and the channel is in nonblocking mode, the function should return an
536 EAGAIN error. If the input device has no data available whatsoever and
537 the channel is in blocking mode, the function should block for the
538 shortest possible time until at least one byte of data can be read from
539 the device; then, it should return as much data as it can read without
540 blocking.
541 This value can be retrieved with Tcl_ChannelInputProc, which returns a
543 pointer to the function.
544 OUTPUTPROC
546 The outputProc field contains the address of a function called by the
547 generic layer to transfer data from an internal buffer to the output
548 device. OutputProc must match the following prototype:
549 typedef int Tcl_DriverOutputProc(
551 ClientData instanceData,
552 const char *buf,
553 int toWrite,
554 int *errorCodePtr);
555 InstanceData is the same as the value passed to Tcl_CreateChannel when
557 the channel was created. The buf argument contains an array of bytes to
558 be written to the device, and the toWrite argument indicates how many
559 bytes are to be written from the buf argument.
560 The errorCodePtr argument points to an integer variable provided by the
562 generic layer. If an error occurs, the function should set this vari‐
563 able to a POSIX error code that identifies the error.
564 The function should write the data at buf to the output device encapsu‐
566 lated by the channel. On success, the function should return a nonnega‐
567 tive integer indicating how many bytes were written to the output
568 device. The return value is normally the same as toWrite, but may be
569 less in some cases such as if the output operation is interrupted by a
570 signal. If an error occurs the function should return -1. In case of
571 error, some data may have been written to the device.
572 If the channel is nonblocking and the output device is unable to absorb
574 any data whatsoever, the function should return -1 with an EAGAIN error
575 without writing any data.
576 This value can be retrieved with Tcl_ChannelOutputProc, which returns a
578 pointer to the function.
579 SEEKPROC AND WIDESEEKPROC
581 The seekProc field contains the address of a function called by the
582 generic layer to move the access point at which subsequent input or
583 output operations will be applied. SeekProc must match the following
584 prototype:
585 typedef int Tcl_DriverSeekProc(
587 ClientData instanceData,
588 long offset,
589 int seekMode,
590 int *errorCodePtr);
591 The instanceData argument is the same as the value given to Tcl_Create‐
593 Channel when this channel was created. Offset and seekMode have the
594 same meaning as for the Tcl_Seek procedure (described in the manual
595 entry for Tcl_OpenFileChannel).
596 The errorCodePtr argument points to an integer variable provided by the
598 generic layer for returning errno values from the function. The func‐
599 tion should set this variable to a POSIX error code if an error occurs.
600 The function should store an EINVAL error code if the channel type does
601 not implement seeking.
602 The return value is the new access point or -1 in case of error. If an
604 error occurred, the function should not move the access point.
605 If there is a non-NULL seekProc field, the wideSeekProc field may con‐
607 tain the address of an alternative function to use which handles wide
608 (i.e. larger than 32-bit) offsets, so allowing seeks within files
609 larger than 2GB. The wideSeekProc will be called in preference to the
610 seekProc, but both must be defined if the wideSeekProc is defined.
611 WideSeekProc must match the following prototype:
612 typedef Tcl_WideInt Tcl_DriverWideSeekProc(
614 ClientData instanceData,
615 Tcl_WideInt offset,
616 int seekMode,
617 int *errorCodePtr);
618 The arguments and return values mean the same thing as with seekProc
620 above, except that the type of offsets and the return type are differ‐
621 ent.
622 The seekProc value can be retrieved with Tcl_ChannelSeekProc, which
624 returns a pointer to the function, and similarly the wideSeekProc can
625 be retrieved with Tcl_ChannelWideSeekProc.
626 SETOPTIONPROC
628 The setOptionProc field contains the address of a function called by
629 the generic layer to set a channel type specific option on a channel.
630 setOptionProc must match the following prototype:
631 typedef int Tcl_DriverSetOptionProc(
633 ClientData instanceData,
634 Tcl_Interp *interp,
635 const char *optionName,
636 const char *newValue);
637 optionName is the name of an option to set, and newValue is the new
639 value for that option, as a string. The instanceData is the same as the
640 value given to Tcl_CreateChannel when this channel was created. The
641 function should do whatever channel type specific action is required to
642 implement the new value of the option.
643 Some options are handled by the generic code and this function is never
645 called to set them, e.g. -blockmode. Other options are specific to each
646 channel type and the setOptionProc procedure of the channel driver will
647 get called to implement them. The setOptionProc field can be NULL,
648 which indicates that this channel type supports no type specific
649 options.
650 If the option value is successfully modified to the new value, the
652 function returns TCL_OK. It should call Tcl_BadChannelOption which
653 itself returns TCL_ERROR if the optionName is unrecognized. If new‐
654 Value specifies a value for the option that is not supported or if a
655 system call error occurs, the function should leave an error message in
656 the result field of interp if interp is not NULL. The function should
657 also call Tcl_SetErrno to store an appropriate POSIX error code.
658 This value can be retrieved with Tcl_ChannelSetOptionProc, which
660 returns a pointer to the function.
661 GETOPTIONPROC
663 The getOptionProc field contains the address of a function called by
664 the generic layer to get the value of a channel type specific option on
665 a channel. getOptionProc must match the following prototype:
666 typedef int Tcl_DriverGetOptionProc(
668 ClientData instanceData,
669 Tcl_Interp *interp,
670 const char *optionName,
671 Tcl_DString *optionValue);
672 OptionName is the name of an option supported by this type of channel.
674 If the option name is not NULL, the function stores its current value,
675 as a string, in the Tcl dynamic string optionValue. If optionName is
676 NULL, the function stores in optionValue an alternating list of all
677 supported options and their current values. On success, the function
678 returns TCL_OK. It should call Tcl_BadChannelOption which itself
679 returns TCL_ERROR if the optionName is unrecognized. If a system call
680 error occurs, the function should leave an error message in the result
681 of interp if interp is not NULL. The function should also call
682 Tcl_SetErrno to store an appropriate POSIX error code.
683 Some options are handled by the generic code and this function is never
685 called to retrieve their value, e.g. -blockmode. Other options are spe‐
686 cific to each channel type and the getOptionProc procedure of the chan‐
687 nel driver will get called to implement them. The getOptionProc field
688 can be NULL, which indicates that this channel type supports no type
689 specific options.
690 This value can be retrieved with Tcl_ChannelGetOptionProc, which
692 returns a pointer to the function.
693 WATCHPROC
695 The watchProc field contains the address of a function called by the
696 generic layer to initialize the event notification mechanism to notice
697 events of interest on this channel. WatchProc should match the follow‐
698 ing prototype:
699 typedef void Tcl_DriverWatchProc(
701 ClientData instanceData,
702 int mask);
703 The instanceData is the same as the value passed to Tcl_CreateChannel
705 when this channel was created. The mask argument is an OR-ed combina‐
706 tion of TCL_READABLE, TCL_WRITABLE and TCL_EXCEPTION; it indicates
707 events the caller is interested in noticing on this channel.
708 The function should initialize device type specific mechanisms to
710 notice when an event of interest is present on the channel. When one
711 or more of the designated events occurs on the channel, the channel
712 driver is responsible for calling Tcl_NotifyChannel to inform the
713 generic channel module. The driver should take care not to starve
714 other channel drivers or sources of callbacks by invoking Tcl_Notify‐
715 Channel too frequently. Fairness can be insured by using the Tcl event
716 queue to allow the channel event to be scheduled in sequence with other
717 events. See the description of Tcl_QueueEvent for details on how to
718 queue an event.
719 This value can be retrieved with Tcl_ChannelWatchProc, which returns a
721 pointer to the function.
722 GETHANDLEPROC
724 The getHandleProc field contains the address of a function called by
725 the generic layer to retrieve a device-specific handle from the chan‐
726 nel. GetHandleProc should match the following prototype:
727 typedef int Tcl_DriverGetHandleProc(
729 ClientData instanceData,
730 int direction,
731 ClientData *handlePtr);
732 InstanceData is the same as the value passed to Tcl_CreateChannel when
734 this channel was created. The direction argument is either TCL_READABLE
735 to retrieve the handle used for input, or TCL_WRITABLE to retrieve the
736 handle used for output.
737 If the channel implementation has device-specific handles, the function
739 should retrieve the appropriate handle associated with the channel,
740 according the direction argument. The handle should be stored in the
741 location referred to by handlePtr, and TCL_OK should be returned. If
742 the channel is not open for the specified direction, or if the channel
743 implementation does not use device handles, the function should return
744 TCL_ERROR.
745 This value can be retrieved with Tcl_ChannelGetHandleProc, which
747 returns a pointer to the function.
748 FLUSHPROC
750 The flushProc field is currently reserved for future use. It should be
751 set to NULL. FlushProc should match the following prototype:
752 typedef int Tcl_DriverFlushProc(
754 ClientData instanceData);
755 This value can be retrieved with Tcl_ChannelFlushProc, which returns a
757 pointer to the function.
758 HANDLERPROC
760 The handlerProc field contains the address of a function called by the
761 generic layer to notify the channel that an event occurred. It should
762 be defined for stacked channel drivers that wish to be notified of
763 events that occur on the underlying (stacked) channel. HandlerProc
764 should match the following prototype:
765 typedef int Tcl_DriverHandlerProc(
767 ClientData instanceData,
768 int interestMask);
769 InstanceData is the same as the value passed to Tcl_CreateChannel when
771 this channel was created. The interestMask is an OR-ed combination of
772 TCL_READABLE or TCL_WRITABLE; it indicates what type of event occurred
773 on this channel.
774 This value can be retrieved with Tcl_ChannelHandlerProc, which returns
776 a pointer to the function.
777 THREADACTIONPROC
780 The threadActionProc field contains the address of the function called
781 by the generic layer when a channel is created, closed, or going to
782 move to a different thread, i.e. whenever thread-specific driver state
783 might have to initialized or updated. It can be NULL. The action
784 TCL_CHANNEL_THREAD_REMOVE is used to notify the driver that it should
785 update or remove any thread-specific data it might be maintaining for
786 the channel.
787 The action TCL_CHANNEL_THREAD_INSERT is used to notify the driver that
789 it should update or initialize any thread-specific data it might be
790 maintaining using the calling thread as the associate. See Tcl_CutChan‐
791 nel and Tcl_SpliceChannel for more detail.
792 typedef void Tcl_DriverThreadActionProc(
794 ClientData instanceData,
795 int action);
796 InstanceData is the same as the value passed to Tcl_CreateChannel when
798 this channel was created.
799 These values can be retrieved with Tcl_ChannelThreadActionProc, which
801 returns a pointer to the function.
802 TRUNCATEPROC
804 The truncateProc field contains the address of the function called by
805 the generic layer when a channel is truncated to some length. It can be
806 NULL.
807 typedef int Tcl_DriverTruncateProc(
809 ClientData instanceData,
810 Tcl_WideInt length);
811 InstanceData is the same as the value passed to Tcl_CreateChannel when
813 this channel was created, and length is the new length of the underly‐
814 ing file, which should not be negative. The result should be 0 on suc‐
815 cess or an errno code (suitable for use with Tcl_SetErrno) on failure.
816 These values can be retrieved with Tcl_ChannelTruncateProc, which
818 returns a pointer to the function.
819
821 This procedure generates a “bad option” error message in an (optional)
822 interpreter. It is used by channel drivers when an invalid Set/Get
823 option is requested. Its purpose is to concatenate the generic options
824 list to the specific ones and factorize the generic options error mes‐
825 sage string.
826 It always returns TCL_ERROR
828 An error message is generated in interp's result value to indicate that
830 a command was invoked with a bad option. The message has the form
831 bad option "blah": should be one of
832 <...generic options...>+<...specific options...>
833 so you get for instance:
834 bad option "-blah": should be one of -blocking,
835 -buffering, -buffersize, -eofchar, -translation,
836 -peername, or -sockname
837 when called with optionList equal to “peername sockname”
838 “blah” is the optionName argument and “<specific options>” is a space
840 separated list of specific option words. The function takes good care
841 of inserting minus signs before each option, commas after, and an “or”
842 before the last option.
843
845 The original (8.3.1 and below) Tcl_ChannelType structure contains the
846 following fields:
847 typedef struct Tcl_ChannelType {
849 const char *typeName;
850 Tcl_DriverBlockModeProc *blockModeProc;
851 Tcl_DriverCloseProc *closeProc;
852 Tcl_DriverInputProc *inputProc;
853 Tcl_DriverOutputProc *outputProc;
854 Tcl_DriverSeekProc *seekProc;
855 Tcl_DriverSetOptionProc *setOptionProc;
856 Tcl_DriverGetOptionProc *getOptionProc;
857 Tcl_DriverWatchProc *watchProc;
858 Tcl_DriverGetHandleProc *getHandleProc;
859 Tcl_DriverClose2Proc *close2Proc;
860 } Tcl_ChannelType;
861 It is still possible to create channel with the above structure. The
863 internal channel code will determine the version. It is imperative to
864 use the new Tcl_ChannelType structure if you are creating a stacked
865 channel driver, due to problems with the earlier stacked channel imple‐
866 mentation (in 8.2.0 to 8.3.1).
867 Prior to 8.4.0 (i.e. during the later releases of 8.3 and early part of
869 the 8.4 development cycle) the Tcl_ChannelType structure contained the
870 following fields:
871 typedef struct Tcl_ChannelType {
873 const char *typeName;
874 Tcl_ChannelTypeVersion version;
875 Tcl_DriverCloseProc *closeProc;
876 Tcl_DriverInputProc *inputProc;
877 Tcl_DriverOutputProc *outputProc;
878 Tcl_DriverSeekProc *seekProc;
879 Tcl_DriverSetOptionProc *setOptionProc;
880 Tcl_DriverGetOptionProc *getOptionProc;
881 Tcl_DriverWatchProc *watchProc;
882 Tcl_DriverGetHandleProc *getHandleProc;
883 Tcl_DriverClose2Proc *close2Proc;
884 Tcl_DriverBlockModeProc *blockModeProc;
885 Tcl_DriverFlushProc *flushProc;
886 Tcl_DriverHandlerProc *handlerProc;
887 Tcl_DriverTruncateProc *truncateProc;
888 } Tcl_ChannelType;
889 When the above structure is registered as a channel type, the version
891 field should always be TCL_CHANNEL_VERSION_2.
892
894 Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3),
895 Tcl_QueueEvent(3), Tcl_StackChannel(3), Tcl_GetStdChannel(3)
896
898 blocking, channel driver, channel registration, channel type, nonblock‐
899 ing
900Tcl 8.4 Tcl_CreateChannel(3)