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 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.
145 ClientData instanceData (in) Arbitrary one-word
147 value to be associated
148 with this channel.
149 This value is passed
150 to procedures in type‐
151 Ptr when they are
152 invoked.
153 int mask (in) OR-ed combination of
155 TCL_READABLE and
156 TCL_WRITABLE to indi‐
157 cate whether a channel
158 is readable and
159 writable.
160 Tcl_Channel channel (in) The channel to operate
162 on.
163 int direction (in) TCL_READABLE means the
165 input handle is
166 wanted; TCL_WRITABLE
167 means the output han‐
168 dle is wanted.
169 ClientData *handlePtr (out) Points to the location
171 where the desired OS-
172 specific handle should
173 be stored.
174 int size (in) The size, in bytes, of
176 buffers to allocate in
177 this channel.
178 int mask (in) An OR-ed combination
180 of TCL_READABLE,
181 TCL_WRITABLE and
182 TCL_EXCEPTION that
183 indicates events that
184 have occurred on this
185 channel.
186 Tcl_Interp *interp (in) Current interpreter.
188 (can be NULL)
189 const char *optionName (in) Name of the invalid
191 option.
192 const char *optionList (in) Specific options list
194 (space separated
195 words, without “-”) to
196 append to the standard
197 generic options list.
198 Can be NULL for
199 generic options error
200 message only.
201_________________________________________________________________
203
206 Tcl uses a two-layered channel architecture. It provides a generic
207 upper layer to enable C and Tcl programs to perform input and output
208 using the same APIs for a variety of files, devices, sockets etc. The
209 generic C APIs are described in the manual entry for Tcl_OpenFileChan‐
210 nel.
211 The lower layer provides type-specific channel drivers for each type of
213 device supported on each platform. This manual entry describes the C
214 APIs used to communicate between the generic layer and the type-spe‐
215 cific channel drivers. It also explains how new types of channels can
216 be added by providing new channel drivers.
217 Channel drivers consist of a number of components: First, each channel
219 driver provides a Tcl_ChannelType structure containing pointers to
220 functions implementing the various operations used by the generic layer
221 to communicate with the channel driver. The Tcl_ChannelType structure
222 and the functions referenced by it are described in the section
223 TCL_CHANNELTYPE, below.
224 Second, channel drivers usually provide a Tcl command to create
226 instances of that type of channel. For example, the Tcl open command
227 creates channels that use the file and command channel drivers, and the
228 Tcl socket command creates channels that use TCP sockets for network
229 communication.
230 Third, a channel driver optionally provides a C function to open chan‐
232 nel instances of that type. For example, Tcl_OpenFileChannel opens a
233 channel that uses the file channel driver, and Tcl_OpenTcpClient opens
234 a channel that uses the TCP network protocol. These creation functions
235 typically use Tcl_CreateChannel internally to open the channel.
236 To add a new type of channel you must implement a C API or a Tcl com‐
238 mand that opens a channel by invoking Tcl_CreateChannel. When your
239 driver calls Tcl_CreateChannel it passes in a Tcl_ChannelType structure
240 describing the driver's I/O procedures. The generic layer will then
241 invoke the functions referenced in that structure to perform operations
242 on the channel.
243 Tcl_CreateChannel opens a new channel and associates the supplied type‐
245 Ptr and instanceData with it. The channel is opened in the mode indi‐
246 cated by mask. For a discussion of channel drivers, their operations
247 and the Tcl_ChannelType structure, see the section TCL_CHANNELTYPE,
248 below.
249 Tcl_CreateChannel interacts with the code managing the standard chan‐
251 nels. Once a standard channel was initialized either through a call to
252 Tcl_GetStdChannel or a call to Tcl_SetStdChannel closing this standard
253 channel will cause the next call to Tcl_CreateChannel to make the new
254 channel the new standard channel too. See Tcl_StandardChannels for a
255 general treatise about standard channels and the behaviour of the Tcl
256 library with regard to them.
257 Tcl_GetChannelInstanceData returns the instance data associated with
259 the channel in channel. This is the same as the instanceData argument
260 in the call to Tcl_CreateChannel that created this channel.
261 Tcl_GetChannelType returns a pointer to the Tcl_ChannelType structure
263 used by the channel in the channel argument. This is the same as the
264 typePtr argument in the call to Tcl_CreateChannel that created this
265 channel.
266 Tcl_GetChannelName returns a string containing the name associated with
268 the channel, or NULL if the channelName argument to Tcl_CreateChannel
269 was NULL.
270 Tcl_GetChannelHandle places the OS-specific device handle associated
272 with channel for the given direction in the location specified by han‐
273 dlePtr and returns TCL_OK. If the channel does not have a device han‐
274 dle for the specified direction, then TCL_ERROR is returned instead.
275 Different channel drivers will return different types of handle. Refer
276 to the manual entries for each driver to determine what type of handle
277 is returned.
278 Tcl_GetChannelThread returns the id of the thread currently managing
280 the specified channel. This allows channel drivers to send their file
281 events to the correct event queue even for a multi-threaded core.
282 Tcl_GetChannelMode returns an OR-ed combination of TCL_READABLE and
284 TCL_WRITABLE, indicating whether the channel is open for input and out‐
285 put.
286 Tcl_GetChannelBufferSize returns the size, in bytes, of buffers allo‐
288 cated to store input or output in channel. If the value was not set by
289 a previous call to Tcl_SetChannelBufferSize, described below, then the
290 default value of 4096 is returned.
291 Tcl_SetChannelBufferSize sets the size, in bytes, of buffers that will
293 be allocated in subsequent operations on the channel to store input or
294 output. The size argument should be between ten and one million, allow‐
295 ing buffers of ten bytes to one million bytes. If size is outside this
296 range, Tcl_SetChannelBufferSize sets the buffer size to 4096.
297 Tcl_NotifyChannel is called by a channel driver to indicate to the
299 generic layer that the events specified by mask have occurred on the
300 channel. Channel drivers are responsible for invoking this function
301 whenever the channel handlers need to be called for the channel. See
302 WATCHPROC below for more details.
303 Tcl_BadChannelOption is called from driver specific setOptionProc or
305 getOptionProc to generate a complete error message.
306 Tcl_ChannelBuffered returns the number of bytes of input currently
308 buffered in the internal buffer (push back area) of the channel itself.
309 It does not report about the data in the overall buffers for the stack
310 of channels the supplied channel is part of.
311 Tcl_IsChannelShared checks the refcount of the specified channel and
313 returns whether the channel was shared among multiple interpreters
314 (result == 1) or not (result == 0).
315 Tcl_IsChannelRegistered checks whether the specified channel is regis‐
317 tered in the given interpreter (result == 1) or not (result == 0).
318 Tcl_IsChannelExisting checks whether a channel with the specified name
320 is registered in the (thread)-global list of all channels (result == 1)
321 or not (result == 0).
322 Tcl_CutChannel removes the specified channel from the (thread)global
324 list of all channels (of the current thread). Application to a channel
325 still registered in some interpreter is not allowed. Also notifies the │
326 driver if the Tcl_ChannelType version is TCL_CHANNEL_VERSION_4 (or │
327 higher), and Tcl_DriverThreadActionProc is defined for it.
328 Tcl_SpliceChannel adds the specified channel to the (thread)global list
330 of all channels (of the current thread). Application to a channel reg‐
331 istered in some interpreter is not allowed. Also notifies the driver │
332 if the Tcl_ChannelType version is TCL_CHANNEL_VERSION_4 (or higher), │
333 and Tcl_DriverThreadActionProc is defined for it.
334 Tcl_ClearChannelHandlers removes all channelhandlers and event scripts
336 associated with the specified channel, thus shutting down all event
337 processing for this channel.
338
340 A channel driver provides a Tcl_ChannelType structure that contains
341 pointers to functions that implement the various operations on a chan‐
342 nel; these operations are invoked as needed by the generic layer. The
343 structure was versioned starting in Tcl 8.3.2/8.4 to correct a problem
344 with stacked channel drivers. See the OLD CHANNEL TYPES section below
345 for details about the old structure.
346 The Tcl_ChannelType structure contains the following fields:
348 typedef struct Tcl_ChannelType {
349 char *typeName;
350 Tcl_ChannelTypeVersion version;
351 Tcl_DriverCloseProc *closeProc;
352 Tcl_DriverInputProc *inputProc;
353 Tcl_DriverOutputProc *outputProc;
354 Tcl_DriverSeekProc *seekProc;
355 Tcl_DriverSetOptionProc *setOptionProc;
356 Tcl_DriverGetOptionProc *getOptionProc;
357 Tcl_DriverWatchProc *watchProc;
358 Tcl_DriverGetHandleProc *getHandleProc;
359 Tcl_DriverClose2Proc *close2Proc;
360 Tcl_DriverBlockModeProc *blockModeProc;
361 Tcl_DriverFlushProc *flushProc;
362 Tcl_DriverHandlerProc *handlerProc;
363 Tcl_DriverWideSeekProc *wideSeekProc;
364 Tcl_DriverThreadActionProc *threadActionProc;
365 Tcl_DriverTruncateProc *truncateProc; │
366 } Tcl_ChannelType;
367 It is not necessary to provide implementations for all channel opera‐
369 tions. Those which are not necessary may be set to NULL in the struct:
370 blockModeProc, seekProc, setOptionProc, getOptionProc, and close2Proc,
371 in addition to flushProc, handlerProc, threadActionProc, and trun‐
372 cateProc. Other functions that cannot be implemented in a meaningful
373 way should return EINVAL when called, to indicate that the operations
374 they represent are not available. Also note that wideSeekProc can be
375 NULL if seekProc is.
376 The user should only use the above structure for Tcl_ChannelType
378 instantiation. When referencing fields in a Tcl_ChannelType structure,
379 the following functions should be used to obtain the values: Tcl_Chan‐
380 nelName, Tcl_ChannelVersion, Tcl_ChannelBlockModeProc, Tcl_Channel‐
381 CloseProc, Tcl_ChannelClose2Proc, Tcl_ChannelInputProc, Tcl_ChannelOut‐
382 putProc, Tcl_ChannelSeekProc, Tcl_ChannelWideSeekProc, Tcl_Chan‐
383 nelThreadActionProc, Tcl_ChannelTruncateProc, Tcl_ChannelSetOptionProc, │
384 Tcl_ChannelGetOptionProc, Tcl_ChannelWatchProc, Tcl_ChannelGetH‐
385 andleProc, Tcl_ChannelFlushProc, or Tcl_ChannelHandlerProc.
386 The change to the structures was made in such a way that standard chan‐
388 nel types are binary compatible. However, channel types that use
389 stacked channels (i.e. TLS, Trf) have new versions to correspond to the
390 above change since the previous code for stacked channels had problems.
391 TYPENAME
393 The typeName field contains a null-terminated string that identifies
394 the type of the device implemented by this driver, e.g. file or
395 socket.
396 This value can be retrieved with Tcl_ChannelName, which returns a
398 pointer to the string.
399 VERSION
401 The version field should be set to the version of the structure that
402 you require. TCL_CHANNEL_VERSION_2 is the minimum recommended.
403 TCL_CHANNEL_VERSION_3 must be set to specifiy the wideSeekProc member.
404 TCL_CHANNEL_VERSION_4 must be set to specifiy the threadActionProc mem‐
405 ber (includes wideSeekProc). TCL_CHANNEL_VERSION_5 must be set to │
406 specifiy the truncateProc members (includes wideSeekProc and threadAc‐ │
407 tionProc). If it is not set to any of these, then this Tcl_ChannelType
408 is assumed to have the original structure. See OLD CHANNEL TYPES for
409 more details. While Tcl will recognize and function with either struc‐
410 tures, stacked channels must be of at least TCL_CHANNEL_VERSION_2 to
411 function correctly.
412 This value can be retrieved with Tcl_ChannelVersion, which returns one
414 of TCL_CHANNEL_VERSION_5, TCL_CHANNEL_VERSION_4, TCL_CHANNEL_VERSION_3, │
415 TCL_CHANNEL_VERSION_2 or TCL_CHANNEL_VERSION_1.
416 BLOCKMODEPROC
418 The blockModeProc field contains the address of a function called by
419 the generic layer to set blocking and nonblocking mode on the device.
420 BlockModeProc should match the following prototype:
421 typedef int Tcl_DriverBlockModeProc(
423 ClientData instanceData,
424 int mode);
425 The instanceData is the same as the value passed to Tcl_CreateChannel
427 when this channel was created. The mode argument is either
428 TCL_MODE_BLOCKING or TCL_MODE_NONBLOCKING to set the device into block‐
429 ing or nonblocking mode. The function should return zero if the opera‐
430 tion was successful, or a nonzero POSIX error code if the operation
431 failed.
432 If the operation is successful, the function can modify the supplied
434 instanceData to record that the channel entered blocking or nonblocking
435 mode and to implement the blocking or nonblocking behavior. For some
436 device types, the blocking and nonblocking behavior can be implemented
437 by the underlying operating system; for other device types, the behav‐
438 ior must be emulated in the channel driver.
439 This value can be retrieved with Tcl_ChannelBlockModeProc, which
441 returns a pointer to the function.
442 A channel driver not supplying a blockModeProc has to be very, very
444 careful. It has to tell the generic layer exactly which blocking mode
445 is acceptable to it, and should this also document for the user so that
446 the blocking mode of the channel is not changed to an inacceptable
447 value. Any confusion here may lead the interpreter into a (spurious and
448 difficult to find) deadlock.
449 CLOSEPROC AND CLOSE2PROC
451 The closeProc field contains the address of a function called by the
452 generic layer to clean up driver-related information when the channel
453 is closed. CloseProc must match the following prototype:
454 typedef int Tcl_DriverCloseProc(
456 ClientData instanceData,
457 Tcl_Interp *interp);
458 The instanceData argument is the same as the value provided to Tcl_Cre‐
460 ateChannel when the channel was created. The function should release
461 any storage maintained by the channel driver for this channel, and
462 close the input and output devices encapsulated by this channel. All
463 queued output will have been flushed to the device before this function
464 is called, and no further driver operations will be invoked on this
465 instance after calling the closeProc. If the close operation is suc‐
466 cessful, the procedure should return zero; otherwise it should return a
467 nonzero POSIX error code. In addition, if an error occurs and interp is
468 not NULL, the procedure should store an error message in the inter‐
469 preter's result.
470 Alternatively, channels that support closing the read and write sides
472 independently may set closeProc to TCL_CLOSE2PROC and set close2Proc to
473 the address of a function that matches the following prototype:
474 typedef int Tcl_DriverClose2Proc(
476 ClientData instanceData,
477 Tcl_Interp *interp,
478 int flags);
479 The close2Proc will be called with flags set to an OR'ed combination of
481 TCL_CLOSE_READ or TCL_CLOSE_WRITE to indicate that the driver should
482 close the read and/or write side of the channel. The channel driver
483 may be invoked to perform additional operations on the channel after
484 close2Proc is called to close one or both sides of the channel. If
485 flags is 0 (zero), the driver should close the channel in the manner
486 described above for closeProc. No further operations will be invoked
487 on this instance after close2Proc is called with all flags cleared. In
488 all cases, the close2Proc function should return zero if the close
489 operation was successful; otherwise it should return a nonzero POSIX
490 error code. In addition, if an error occurs and interp is not NULL, the
491 procedure should store an error message in the interpreter's result.
492 The closeProc and close2Proc values can be retrieved with Tcl_Channel‐
494 CloseProc or Tcl_ChannelClose2Proc, which return a pointer to the
495 respective function.
496 INPUTPROC
498 The inputProc field contains the address of a function called by the
499 generic layer to read data from the file or device and store it in an
500 internal buffer. InputProc must match the following prototype:
501 typedef int Tcl_DriverInputProc(
503 ClientData instanceData,
504 char *buf,
505 int bufSize,
506 int *errorCodePtr);
507 InstanceData is the same as the value passed to Tcl_CreateChannel when
509 the channel was created. The buf argument points to an array of bytes
510 in which to store input from the device, and the bufSize argument indi‐
511 cates how many bytes are available at buf.
512 The errorCodePtr argument points to an integer variable provided by the
514 generic layer. If an error occurs, the function should set the variable
515 to a POSIX error code that identifies the error that occurred.
516 The function should read data from the input device encapsulated by the
518 channel and store it at buf. On success, the function should return a
519 nonnegative integer indicating how many bytes were read from the input
520 device and stored at buf. On error, the function should return -1. If
521 an error occurs after some data has been read from the device, that
522 data is lost.
523 If inputProc can determine that the input device has some data avail‐
525 able but less than requested by the bufSize argument, the function
526 should only attempt to read as much data as is available and return
527 without blocking. If the input device has no data available whatsoever
528 and the channel is in nonblocking mode, the function should return an
529 EAGAIN error. If the input device has no data available whatsoever and
530 the channel is in blocking mode, the function should block for the
531 shortest possible time until at least one byte of data can be read from
532 the device; then, it should return as much data as it can read without
533 blocking.
534 This value can be retrieved with Tcl_ChannelInputProc, which returns a
536 pointer to the function.
537 OUTPUTPROC
539 The outputProc field contains the address of a function called by the
540 generic layer to transfer data from an internal buffer to the output
541 device. OutputProc must match the following prototype:
542 typedef int Tcl_DriverOutputProc(
544 ClientData instanceData,
545 const char *buf,
546 int toWrite,
547 int *errorCodePtr);
548 InstanceData is the same as the value passed to Tcl_CreateChannel when
550 the channel was created. The buf argument contains an array of bytes to
551 be written to the device, and the toWrite argument indicates how many
552 bytes are to be written from the buf argument.
553 The errorCodePtr argument points to an integer variable provided by the
555 generic layer. If an error occurs, the function should set this vari‐
556 able to a POSIX error code that identifies the error.
557 The function should write the data at buf to the output device encapsu‐
559 lated by the channel. On success, the function should return a nonnega‐
560 tive integer indicating how many bytes were written to the output
561 device. The return value is normally the same as toWrite, but may be
562 less in some cases such as if the output operation is interrupted by a
563 signal. If an error occurs the function should return -1. In case of
564 error, some data may have been written to the device.
565 If the channel is nonblocking and the output device is unable to absorb
567 any data whatsoever, the function should return -1 with an EAGAIN error
568 without writing any data.
569 This value can be retrieved with Tcl_ChannelOutputProc, which returns a
571 pointer to the function.
572 SEEKPROC AND WIDESEEKPROC
574 The seekProc field contains the address of a function called by the
575 generic layer to move the access point at which subsequent input or
576 output operations will be applied. SeekProc must match the following
577 prototype:
578 typedef int Tcl_DriverSeekProc(
580 ClientData instanceData,
581 long offset,
582 int seekMode,
583 int *errorCodePtr);
584 The instanceData argument is the same as the value given to Tcl_Create‐
586 Channel when this channel was created. Offset and seekMode have the
587 same meaning as for the Tcl_Seek procedure (described in the manual
588 entry for Tcl_OpenFileChannel).
589 The errorCodePtr argument points to an integer variable provided by the
591 generic layer for returning errno values from the function. The func‐
592 tion should set this variable to a POSIX error code if an error occurs.
593 The function should store an EINVAL error code if the channel type does
594 not implement seeking.
595 The return value is the new access point or -1 in case of error. If an
597 error occurred, the function should not move the access point.
598 If there is a non-NULL seekProc field, the wideSeekProc field may con‐
600 tain the address of an alternative function to use which handles wide
601 (i.e. larger than 32-bit) offsets, so allowing seeks within files
602 larger than 2GB. The wideSeekProc will be called in preference to the
603 seekProc, but both must be defined if the wideSeekProc is defined.
604 WideSeekProc must match the following prototype:
605 typedef Tcl_WideInt Tcl_DriverWideSeekProc(
607 ClientData instanceData,
608 Tcl_WideInt offset,
609 int seekMode,
610 int *errorCodePtr);
611 The arguments and return values mean the same thing as with seekProc
613 above, except that the type of offsets and the return type are differ‐
614 ent.
615 The seekProc value can be retrieved with Tcl_ChannelSeekProc, which
617 returns a pointer to the function, and similarly the wideSeekProc can
618 be retrieved with Tcl_ChannelWideSeekProc.
619 SETOPTIONPROC
621 The setOptionProc field contains the address of a function called by
622 the generic layer to set a channel type specific option on a channel.
623 setOptionProc must match the following prototype:
624 typedef int Tcl_DriverSetOptionProc(
626 ClientData instanceData,
627 Tcl_Interp *interp,
628 const char *optionName,
629 const char *newValue);
630 optionName is the name of an option to set, and newValue is the new
632 value for that option, as a string. The instanceData is the same as the
633 value given to Tcl_CreateChannel when this channel was created. The
634 function should do whatever channel type specific action is required to
635 implement the new value of the option.
636 Some options are handled by the generic code and this function is never
638 called to set them, e.g. -blockmode. Other options are specific to each
639 channel type and the setOptionProc procedure of the channel driver will
640 get called to implement them. The setOptionProc field can be NULL,
641 which indicates that this channel type supports no type specific
642 options.
643 If the option value is successfully modified to the new value, the
645 function returns TCL_OK. It should call Tcl_BadChannelOption which
646 itself returns TCL_ERROR if the optionName is unrecognized. If new‐
647 Value specifies a value for the option that is not supported or if a
648 system call error occurs, the function should leave an error message in
649 the result field of interp if interp is not NULL. The function should
650 also call Tcl_SetErrno to store an appropriate POSIX error code.
651 This value can be retrieved with Tcl_ChannelSetOptionProc, which
653 returns a pointer to the function.
654 GETOPTIONPROC
656 The getOptionProc field contains the address of a function called by
657 the generic layer to get the value of a channel type specific option on
658 a channel. getOptionProc must match the following prototype:
659 typedef int Tcl_DriverGetOptionProc(
661 ClientData instanceData,
662 Tcl_Interp *interp,
663 const char *optionName,
664 Tcl_DString *optionValue);
665 OptionName is the name of an option supported by this type of channel.
667 If the option name is not NULL, the function stores its current value,
668 as a string, in the Tcl dynamic string optionValue. If optionName is
669 NULL, the function stores in optionValue an alternating list of all
670 supported options and their current values. On success, the function
671 returns TCL_OK. It should call Tcl_BadChannelOption which itself
672 returns TCL_ERROR if the optionName is unrecognized. If a system call
673 error occurs, the function should leave an error message in the result
674 of interp if interp is not NULL. The function should also call
675 Tcl_SetErrno to store an appropriate POSIX error code.
676 Some options are handled by the generic code and this function is never
678 called to retrieve their value, e.g. -blockmode. Other options are spe‐
679 cific to each channel type and the getOptionProc procedure of the chan‐
680 nel driver will get called to implement them. The getOptionProc field
681 can be NULL, which indicates that this channel type supports no type
682 specific options.
683 This value can be retrieved with Tcl_ChannelGetOptionProc, which
685 returns a pointer to the function.
686 WATCHPROC
688 The watchProc field contains the address of a function called by the
689 generic layer to initialize the event notification mechanism to notice
690 events of interest on this channel. WatchProc should match the follow‐
691 ing prototype:
692 typedef void Tcl_DriverWatchProc(
694 ClientData instanceData,
695 int mask);
696 The instanceData is the same as the value passed to Tcl_CreateChannel
698 when this channel was created. The mask argument is an OR-ed combina‐
699 tion of TCL_READABLE, TCL_WRITABLE and TCL_EXCEPTION; it indicates
700 events the caller is interested in noticing on this channel.
701 The function should initialize device type specific mechanisms to
703 notice when an event of interest is present on the channel. When one
704 or more of the designated events occurs on the channel, the channel
705 driver is responsible for calling Tcl_NotifyChannel to inform the
706 generic channel module. The driver should take care not to starve
707 other channel drivers or sources of callbacks by invoking Tcl_Notify‐
708 Channel too frequently. Fairness can be insured by using the Tcl event
709 queue to allow the channel event to be scheduled in sequence with other
710 events. See the description of Tcl_QueueEvent for details on how to
711 queue an event.
712 This value can be retrieved with Tcl_ChannelWatchProc, which returns a
714 pointer to the function.
715 GETHANDLEPROC
717 The getHandleProc field contains the address of a function called by
718 the generic layer to retrieve a device-specific handle from the chan‐
719 nel. GetHandleProc should match the following prototype:
720 typedef int Tcl_DriverGetHandleProc(
722 ClientData instanceData,
723 int direction,
724 ClientData *handlePtr);
725 InstanceData is the same as the value passed to Tcl_CreateChannel when
727 this channel was created. The direction argument is either TCL_READABLE
728 to retrieve the handle used for input, or TCL_WRITABLE to retrieve the
729 handle used for output.
730 If the channel implementation has device-specific handles, the function
732 should retrieve the appropriate handle associated with the channel,
733 according the direction argument. The handle should be stored in the
734 location referred to by handlePtr, and TCL_OK should be returned. If
735 the channel is not open for the specified direction, or if the channel
736 implementation does not use device handles, the function should return
737 TCL_ERROR.
738 This value can be retrieved with Tcl_ChannelGetHandleProc, which
740 returns a pointer to the function.
741 FLUSHPROC
743 The flushProc field is currently reserved for future use. It should be
744 set to NULL. FlushProc should match the following prototype:
745 typedef int Tcl_DriverFlushProc(
747 ClientData instanceData);
748 This value can be retrieved with Tcl_ChannelFlushProc, which returns a
750 pointer to the function.
751 HANDLERPROC
753 The handlerProc field contains the address of a function called by the
754 generic layer to notify the channel that an event occurred. It should
755 be defined for stacked channel drivers that wish to be notified of
756 events that occur on the underlying (stacked) channel. HandlerProc
757 should match the following prototype:
758 typedef int Tcl_DriverHandlerProc(
760 ClientData instanceData,
761 int interestMask);
762 InstanceData is the same as the value passed to Tcl_CreateChannel when
764 this channel was created. The interestMask is an OR-ed combination of
765 TCL_READABLE or TCL_WRITABLE; it indicates what type of event occurred
766 on this channel.
767 This value can be retrieved with Tcl_ChannelHandlerProc, which returns
769 a pointer to the function.
770 THREADACTIONPROC
773 The threadActionProc field contains the address of the function called
774 by the generic layer when a channel is created, closed, or going to
775 move to a different thread, i.e. whenever thread-specific driver state
776 might have to initialized or updated. It can be NULL. The action
777 TCL_CHANNEL_THREAD_REMOVE is used to notify the driver that it should
778 update or remove any thread-specific data it might be maintaining for
779 the channel.
780 The action TCL_CHANNEL_THREAD_INSERT is used to notify the driver that
782 it should update or initialize any thread-specific data it might be
783 maintaining using the calling thread as the associate. See Tcl_CutChan‐
784 nel and Tcl_SpliceChannel for more detail.
785 typedef void Tcl_DriverThreadActionProc(
787 ClientData instanceData,
788 int action);
789 InstanceData is the same as the value passed to Tcl_CreateChannel when
791 this channel was created.
792 These values can be retrieved with Tcl_ChannelThreadActionProc, which
794 returns a pointer to the function.
795 TRUNCATEPROC
797 The truncateProc field contains the address of the function called by
798 the generic layer when a channel is truncated to some length. It can be
799 NULL.
800 typedef int Tcl_DriverTruncateProc(
802 ClientData instanceData,
803 Tcl_WideInt length);
804 InstanceData is the same as the value passed to Tcl_CreateChannel when
806 this channel was created, and length is the new length of the underly‐
807 ing file, which should not be negative. The result should be 0 on suc‐
808 cess or an errno code (suitable for use with Tcl_SetErrno) on failure.
809 These values can be retrieved with Tcl_ChannelTruncateProc, which
811 returns a pointer to the function.
812
814 This procedure generates a “bad option” error message in an (optional)
815 interpreter. It is used by channel drivers when an invalid Set/Get
816 option is requested. Its purpose is to concatenate the generic options
817 list to the specific ones and factorize the generic options error mes‐
818 sage string.
819 It always returns TCL_ERROR
821 An error message is generated in interp's result object to indicate
823 that a command was invoked with a bad option. The message has the form
824 bad option "blah": should be one of
825 <...generic options...>+<...specific options...>
826 so you get for instance:
827 bad option "-blah": should be one of -blocking,
828 -buffering, -buffersize, -eofchar, -translation,
829 -peername, or -sockname
830 when called with optionList equal to “peername sockname”
831 “blah” is the optionName argument and “<specific options>” is a space
833 separated list of specific option words. The function takes good care
834 of inserting minus signs before each option, commas after, and an “or”
835 before the last option.
836
838 The original (8.3.1 and below) Tcl_ChannelType structure contains the
839 following fields:
840 typedef struct Tcl_ChannelType {
842 char *typeName;
843 Tcl_DriverBlockModeProc *blockModeProc;
844 Tcl_DriverCloseProc *closeProc;
845 Tcl_DriverInputProc *inputProc;
846 Tcl_DriverOutputProc *outputProc;
847 Tcl_DriverSeekProc *seekProc;
848 Tcl_DriverSetOptionProc *setOptionProc;
849 Tcl_DriverGetOptionProc *getOptionProc;
850 Tcl_DriverWatchProc *watchProc;
851 Tcl_DriverGetHandleProc *getHandleProc;
852 Tcl_DriverClose2Proc *close2Proc;
853 } Tcl_ChannelType;
854 It is still possible to create channel with the above structure. The
856 internal channel code will determine the version. It is imperative to
857 use the new Tcl_ChannelType structure if you are creating a stacked
858 channel driver, due to problems with the earlier stacked channel imple‐
859 mentation (in 8.2.0 to 8.3.1).
860 Prior to 8.4.0 (i.e. during the later releases of 8.3 and early part of
862 the 8.4 development cycle) the Tcl_ChannelType structure contained the
863 following fields:
864 typedef struct Tcl_ChannelType {
866 char *typeName;
867 Tcl_ChannelTypeVersion version;
868 Tcl_DriverCloseProc *closeProc;
869 Tcl_DriverInputProc *inputProc;
870 Tcl_DriverOutputProc *outputProc;
871 Tcl_DriverSeekProc *seekProc;
872 Tcl_DriverSetOptionProc *setOptionProc;
873 Tcl_DriverGetOptionProc *getOptionProc;
874 Tcl_DriverWatchProc *watchProc;
875 Tcl_DriverGetHandleProc *getHandleProc;
876 Tcl_DriverClose2Proc *close2Proc;
877 Tcl_DriverBlockModeProc *blockModeProc;
878 Tcl_DriverFlushProc *flushProc;
879 Tcl_DriverHandlerProc *handlerProc;
880 Tcl_DriverTruncateProc *truncateProc;
881 } Tcl_ChannelType;
882 When the above structure is registered as a channel type, the version
884 field should always be TCL_CHANNEL_VERSION_2.
885
888 Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3),
889 Tcl_QueueEvent(3), Tcl_StackChannel(3), Tcl_GetStdChannel(3)
890
893 blocking, channel driver, channel registration, channel type, nonblock‐
894 ing
895Tcl 8.4 Tcl_CreateChannel(3)