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 ad‐
132 dresses of procedures
133 that can be called to
134 perform I/O and other
135 functions on the chan‐
136 nel.
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 as‐
146 signed 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 in‐
160 voked.
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 in‐
191 dicates 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 up‐
213 per layer to enable C and Tcl programs to perform input and output us‐
214 ing 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 in‐
232 stances of that type of channel. For example, the Tcl open command cre‐
233 ates 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, be‐
254 low.
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 (or
308 other pending tasks like a write flush should be performed). See
309 WATCHPROC below for more details.
310 Tcl_BadChannelOption is called from driver specific setOptionProc or
312 getOptionProc to generate a complete error message.
313 Tcl_ChannelBuffered returns the number of bytes of input currently
315 buffered in the internal buffer (push back area) of the channel itself.
316 It does not report about the data in the overall buffers for the stack
317 of channels the supplied channel is part of.
318 Tcl_IsChannelShared checks the refcount of the specified channel and
320 returns whether the channel was shared among multiple interpreters (re‐
321 sult == 1) or not (result == 0).
322 Tcl_IsChannelRegistered checks whether the specified channel is regis‐
324 tered in the given interpreter (result == 1) or not (result == 0).
325 Tcl_IsChannelExisting checks whether a channel with the specified name
327 is registered in the (thread)-global list of all channels (result == 1)
328 or not (result == 0).
329 Tcl_CutChannel removes the specified channel from the (thread)global
331 list of all channels (of the current thread). Application to a channel
332 still registered in some interpreter is not allowed. Also notifies the
333 driver if the Tcl_ChannelType version is TCL_CHANNEL_VERSION_4 (or
334 higher), and Tcl_DriverThreadActionProc is defined for it.
335 Tcl_SpliceChannel adds the specified channel to the (thread)global list
337 of all channels (of the current thread). Application to a channel reg‐
338 istered in some interpreter is not allowed. Also notifies the driver
339 if the Tcl_ChannelType version is TCL_CHANNEL_VERSION_4 (or higher),
340 and Tcl_DriverThreadActionProc is defined for it.
341 Tcl_ClearChannelHandlers removes all channel handlers and event scripts
343 associated with the specified channel, thus shutting down all event
344 processing for this channel.
345
347 A channel driver provides a Tcl_ChannelType structure that contains
348 pointers to functions that implement the various operations on a chan‐
349 nel; these operations are invoked as needed by the generic layer. The
350 structure was versioned starting in Tcl 8.3.2/8.4 to correct a problem
351 with stacked channel drivers. See the OLD CHANNEL TYPES section below
352 for details about the old structure.
353 The Tcl_ChannelType structure contains the following fields:
355 typedef struct Tcl_ChannelType {
357 const char *typeName;
358 Tcl_ChannelTypeVersion version;
359 Tcl_DriverCloseProc *closeProc;
360 Tcl_DriverInputProc *inputProc;
361 Tcl_DriverOutputProc *outputProc;
362 Tcl_DriverSeekProc *seekProc;
363 Tcl_DriverSetOptionProc *setOptionProc;
364 Tcl_DriverGetOptionProc *getOptionProc;
365 Tcl_DriverWatchProc *watchProc;
366 Tcl_DriverGetHandleProc *getHandleProc;
367 Tcl_DriverClose2Proc *close2Proc;
368 Tcl_DriverBlockModeProc *blockModeProc;
369 Tcl_DriverFlushProc *flushProc;
370 Tcl_DriverHandlerProc *handlerProc;
371 Tcl_DriverWideSeekProc *wideSeekProc;
372 Tcl_DriverThreadActionProc *threadActionProc;
373 Tcl_DriverTruncateProc *truncateProc;
374 } Tcl_ChannelType;
375 It is not necessary to provide implementations for all channel opera‐
377 tions. Those which are not necessary may be set to NULL in the struct:
378 blockModeProc, seekProc, setOptionProc, getOptionProc, getHandleProc,
379 and close2Proc, in addition to flushProc, handlerProc, threadAction‐
380 Proc, and truncateProc. Other functions that cannot be implemented in
381 a meaningful way should return EINVAL when called, to indicate that the
382 operations they represent are not available. Also note that
383 wideSeekProc can be NULL if seekProc is.
384 The user should only use the above structure for Tcl_ChannelType in‐
386 stantiation. When referencing fields in a Tcl_ChannelType structure,
387 the following functions should be used to obtain the values: Tcl_Chan‐
388 nelName, Tcl_ChannelVersion, Tcl_ChannelBlockModeProc, Tcl_Channel‐
389 CloseProc, Tcl_ChannelClose2Proc, Tcl_ChannelInputProc, Tcl_ChannelOut‐
390 putProc, Tcl_ChannelSeekProc, Tcl_ChannelWideSeekProc, Tcl_Chan‐
391 nelThreadActionProc, Tcl_ChannelTruncateProc, Tcl_ChannelSetOptionProc,
392 Tcl_ChannelGetOptionProc, Tcl_ChannelWatchProc, Tcl_ChannelGetH‐
393 andleProc, Tcl_ChannelFlushProc, or Tcl_ChannelHandlerProc.
394 The change to the structures was made in such a way that standard chan‐
396 nel types are binary compatible. However, channel types that use
397 stacked channels (i.e. TLS, Trf) have new versions to correspond to the
398 above change since the previous code for stacked channels had problems.
399 TYPENAME
401 The typeName field contains a null-terminated string that identifies
402 the type of the device implemented by this driver, e.g. file or
403 socket.
404 This value can be retrieved with Tcl_ChannelName, which returns a
406 pointer to the string.
407 VERSION
409 The version field should be set to the version of the structure that
410 you require. TCL_CHANNEL_VERSION_2 is the minimum recommended.
411 TCL_CHANNEL_VERSION_3 must be set to specify the wideSeekProc member.
412 TCL_CHANNEL_VERSION_4 must be set to specify the threadActionProc mem‐
413 ber (includes wideSeekProc). TCL_CHANNEL_VERSION_5 must be set to
414 specify the truncateProc members (includes wideSeekProc and threadAc‐
415 tionProc). If it is not set to any of these, then this Tcl_ChannelType
416 is assumed to have the original structure. See OLD CHANNEL TYPES for
417 more details. While Tcl will recognize and function with either struc‐
418 tures, stacked channels must be of at least TCL_CHANNEL_VERSION_2 to
419 function correctly.
420 This value can be retrieved with Tcl_ChannelVersion, which returns one
422 of TCL_CHANNEL_VERSION_5, TCL_CHANNEL_VERSION_4, TCL_CHANNEL_VERSION_3,
423 TCL_CHANNEL_VERSION_2 or TCL_CHANNEL_VERSION_1.
424 BLOCKMODEPROC
426 The blockModeProc field contains the address of a function called by
427 the generic layer to set blocking and nonblocking mode on the device.
428 BlockModeProc should match the following prototype:
429 typedef int Tcl_DriverBlockModeProc(
431 ClientData instanceData,
432 int mode);
433 The instanceData is the same as the value passed to Tcl_CreateChannel
435 when this channel was created. The mode argument is either
436 TCL_MODE_BLOCKING or TCL_MODE_NONBLOCKING to set the device into block‐
437 ing or nonblocking mode. The function should return zero if the opera‐
438 tion was successful, or a nonzero POSIX error code if the operation
439 failed.
440 If the operation is successful, the function can modify the supplied
442 instanceData to record that the channel entered blocking or nonblocking
443 mode and to implement the blocking or nonblocking behavior. For some
444 device types, the blocking and nonblocking behavior can be implemented
445 by the underlying operating system; for other device types, the behav‐
446 ior must be emulated in the channel driver.
447 This value can be retrieved with Tcl_ChannelBlockModeProc, which re‐
449 turns a pointer to the function.
450 A channel driver not supplying a blockModeProc has to be very, very
452 careful. It has to tell the generic layer exactly which blocking mode
453 is acceptable to it, and should this also document for the user so that
454 the blocking mode of the channel is not changed to an unacceptable
455 value. Any confusion here may lead the interpreter into a (spurious and
456 difficult to find) deadlock.
457 CLOSEPROC AND CLOSE2PROC
459 The closeProc field contains the address of a function called by the
460 generic layer to clean up driver-related information when the channel
461 is closed. CloseProc must match the following prototype:
462 typedef int Tcl_DriverCloseProc(
464 ClientData instanceData,
465 Tcl_Interp *interp);
466 The instanceData argument is the same as the value provided to Tcl_Cre‐
468 ateChannel when the channel was created. The function should release
469 any storage maintained by the channel driver for this channel, and
470 close the input and output devices encapsulated by this channel. All
471 queued output will have been flushed to the device before this function
472 is called, and no further driver operations will be invoked on this in‐
473 stance after calling the closeProc. If the close operation is success‐
474 ful, the procedure should return zero; otherwise it should return a
475 nonzero POSIX error code. In addition, if an error occurs and interp is
476 not NULL, the procedure should store an error message in the inter‐
477 preter's result.
478 Alternatively, channels that support closing the read and write sides
480 independently may set closeProc to TCL_CLOSE2PROC and set close2Proc to
481 the address of a function that matches the following prototype:
482 typedef int Tcl_DriverClose2Proc(
484 ClientData instanceData,
485 Tcl_Interp *interp,
486 int flags);
487 The close2Proc will be called with flags set to an OR'ed combination of
489 TCL_CLOSE_READ or TCL_CLOSE_WRITE to indicate that the driver should
490 close the read and/or write side of the channel. The channel driver
491 may be invoked to perform additional operations on the channel after
492 close2Proc is called to close one or both sides of the channel. If
493 flags is 0 (zero), the driver should close the channel in the manner
494 described above for closeProc. No further operations will be invoked
495 on this instance after close2Proc is called with all flags cleared. In
496 all cases, the close2Proc function should return zero if the close op‐
497 eration was successful; otherwise it should return a nonzero POSIX er‐
498 ror code. In addition, if an error occurs and interp is not NULL, the
499 procedure should store an error message in the interpreter's result.
500 The closeProc and close2Proc values can be retrieved with Tcl_Channel‐
502 CloseProc or Tcl_ChannelClose2Proc, which return a pointer to the re‐
503 spective function.
504 INPUTPROC
506 The inputProc field contains the address of a function called by the
507 generic layer to read data from the file or device and store it in an
508 internal buffer. InputProc must match the following prototype:
509 typedef int Tcl_DriverInputProc(
511 ClientData instanceData,
512 char *buf,
513 int bufSize,
514 int *errorCodePtr);
515 InstanceData is the same as the value passed to Tcl_CreateChannel when
517 the channel was created. The buf argument points to an array of bytes
518 in which to store input from the device, and the bufSize argument indi‐
519 cates how many bytes are available at buf.
520 The errorCodePtr argument points to an integer variable provided by the
522 generic layer. If an error occurs, the function should set the variable
523 to a POSIX error code that identifies the error that occurred.
524 The function should read data from the input device encapsulated by the
526 channel and store it at buf. On success, the function should return a
527 nonnegative integer indicating how many bytes were read from the input
528 device and stored at buf. On error, the function should return -1. If
529 an error occurs after some data has been read from the device, that
530 data is lost.
531 If inputProc can determine that the input device has some data avail‐
533 able but less than requested by the bufSize argument, the function
534 should only attempt to read as much data as is available and return
535 without blocking. If the input device has no data available whatsoever
536 and the channel is in nonblocking mode, the function should return an
537 EAGAIN error. If the input device has no data available whatsoever and
538 the channel is in blocking mode, the function should block for the
539 shortest possible time until at least one byte of data can be read from
540 the device; then, it should return as much data as it can read without
541 blocking.
542 This value can be retrieved with Tcl_ChannelInputProc, which returns a
544 pointer to the function.
545 OUTPUTPROC
547 The outputProc field contains the address of a function called by the
548 generic layer to transfer data from an internal buffer to the output
549 device. OutputProc must match the following prototype:
550 typedef int Tcl_DriverOutputProc(
552 ClientData instanceData,
553 const char *buf,
554 int toWrite,
555 int *errorCodePtr);
556 InstanceData is the same as the value passed to Tcl_CreateChannel when
558 the channel was created. The buf argument contains an array of bytes to
559 be written to the device, and the toWrite argument indicates how many
560 bytes are to be written from the buf argument.
561 The errorCodePtr argument points to an integer variable provided by the
563 generic layer. If an error occurs, the function should set this vari‐
564 able to a POSIX error code that identifies the error.
565 The function should write the data at buf to the output device encapsu‐
567 lated by the channel. On success, the function should return a nonnega‐
568 tive integer indicating how many bytes were written to the output de‐
569 vice. The return value is normally the same as toWrite, but may be
570 less in some cases such as if the output operation is interrupted by a
571 signal. If an error occurs the function should return -1. In case of
572 error, some data may have been written to the device.
573 If the channel is nonblocking and the output device is unable to absorb
575 any data whatsoever, the function should return -1 with an EAGAIN error
576 without writing any data.
577 This value can be retrieved with Tcl_ChannelOutputProc, which returns a
579 pointer to the function.
580 SEEKPROC AND WIDESEEKPROC
582 The seekProc field contains the address of a function called by the
583 generic layer to move the access point at which subsequent input or
584 output operations will be applied. SeekProc must match the following
585 prototype:
586 typedef int Tcl_DriverSeekProc(
588 ClientData instanceData,
589 long offset,
590 int seekMode,
591 int *errorCodePtr);
592 The instanceData argument is the same as the value given to Tcl_Create‐
594 Channel when this channel was created. Offset and seekMode have the
595 same meaning as for the Tcl_Seek procedure (described in the manual en‐
596 try for Tcl_OpenFileChannel).
597 The errorCodePtr argument points to an integer variable provided by the
599 generic layer for returning errno values from the function. The func‐
600 tion should set this variable to a POSIX error code if an error occurs.
601 The function should store an EINVAL error code if the channel type does
602 not implement seeking.
603 The return value is the new access point or -1 in case of error. If an
605 error occurred, the function should not move the access point.
606 If there is a non-NULL seekProc field, the wideSeekProc field may con‐
608 tain the address of an alternative function to use which handles wide
609 (i.e. larger than 32-bit) offsets, so allowing seeks within files
610 larger than 2GB. The wideSeekProc will be called in preference to the
611 seekProc, but both must be defined if the wideSeekProc is defined.
612 WideSeekProc must match the following prototype:
613 typedef Tcl_WideInt Tcl_DriverWideSeekProc(
615 ClientData instanceData,
616 Tcl_WideInt offset,
617 int seekMode,
618 int *errorCodePtr);
619 The arguments and return values mean the same thing as with seekProc
621 above, except that the type of offsets and the return type are differ‐
622 ent.
623 The seekProc value can be retrieved with Tcl_ChannelSeekProc, which re‐
625 turns a pointer to the function, and similarly the wideSeekProc can be
626 retrieved with Tcl_ChannelWideSeekProc.
627 SETOPTIONPROC
629 The setOptionProc field contains the address of a function called by
630 the generic layer to set a channel type specific option on a channel.
631 setOptionProc must match the following prototype:
632 typedef int Tcl_DriverSetOptionProc(
634 ClientData instanceData,
635 Tcl_Interp *interp,
636 const char *optionName,
637 const char *newValue);
638 optionName is the name of an option to set, and newValue is the new
640 value for that option, as a string. The instanceData is the same as the
641 value given to Tcl_CreateChannel when this channel was created. The
642 function should do whatever channel type specific action is required to
643 implement the new value of the option.
644 Some options are handled by the generic code and this function is never
646 called to set them, e.g. -blockmode. Other options are specific to each
647 channel type and the setOptionProc procedure of the channel driver will
648 get called to implement them. The setOptionProc field can be NULL,
649 which indicates that this channel type supports no type specific op‐
650 tions.
651 If the option value is successfully modified to the new value, the
653 function returns TCL_OK. It should call Tcl_BadChannelOption which it‐
654 self returns TCL_ERROR if the optionName is unrecognized. If newValue
655 specifies a value for the option that is not supported or if a system
656 call error occurs, the function should leave an error message in the
657 result of interp if interp is not NULL. The function should also call
658 Tcl_SetErrno to store an appropriate POSIX error code.
659 This value can be retrieved with Tcl_ChannelSetOptionProc, which re‐
661 turns a pointer to the function.
662 GETOPTIONPROC
664 The getOptionProc field contains the address of a function called by
665 the generic layer to get the value of a channel type specific option on
666 a channel. getOptionProc must match the following prototype:
667 typedef int Tcl_DriverGetOptionProc(
669 ClientData instanceData,
670 Tcl_Interp *interp,
671 const char *optionName,
672 Tcl_DString *optionValue);
673 OptionName is the name of an option supported by this type of channel.
675 If the option name is not NULL, the function stores its current value,
676 as a string, in the Tcl dynamic string optionValue. If optionName is
677 NULL, the function stores in optionValue an alternating list of all
678 supported options and their current values. On success, the function
679 returns TCL_OK. It should call Tcl_BadChannelOption which itself re‐
680 turns TCL_ERROR if the optionName is unrecognized. If a system call er‐
681 ror occurs, the function should leave an error message in the result of
682 interp if interp is not NULL. The function should also call Tcl_SetEr‐
683 rno to store an appropriate POSIX error code.
684 Some options are handled by the generic code and this function is never
686 called to retrieve their value, e.g. -blockmode. Other options are spe‐
687 cific to each channel type and the getOptionProc procedure of the chan‐
688 nel driver will get called to implement them. The getOptionProc field
689 can be NULL, which indicates that this channel type supports no type
690 specific options.
691 This value can be retrieved with Tcl_ChannelGetOptionProc, which re‐
693 turns a pointer to the function.
694 WATCHPROC
696 The watchProc field contains the address of a function called by the
697 generic layer to initialize the event notification mechanism to notice
698 events of interest on this channel. WatchProc should match the follow‐
699 ing prototype:
700 typedef void Tcl_DriverWatchProc(
702 ClientData instanceData,
703 int mask);
704 The instanceData is the same as the value passed to Tcl_CreateChannel
706 when this channel was created. The mask argument is an OR-ed combina‐
707 tion of TCL_READABLE, TCL_WRITABLE and TCL_EXCEPTION; it indicates
708 events the caller is interested in noticing on this channel.
709 The function should initialize device type specific mechanisms to no‐
711 tice when an event of interest is present on the channel. When one or
712 more of the designated events occurs on the channel, the channel driver
713 is responsible for calling Tcl_NotifyChannel to inform the generic
714 channel module. The driver should take care not to starve other chan‐
715 nel drivers or sources of callbacks by invoking Tcl_NotifyChannel too
716 frequently. Fairness can be insured by using the Tcl event queue to
717 allow the channel event to be scheduled in sequence with other events.
718 See the description of Tcl_QueueEvent for details on how to queue an
719 event.
720 This value can be retrieved with Tcl_ChannelWatchProc, which returns a
722 pointer to the function.
723 GETHANDLEPROC
725 The getHandleProc field contains the address of a function called by
726 the generic layer to retrieve a device-specific handle from the chan‐
727 nel. GetHandleProc should match the following prototype:
728 typedef int Tcl_DriverGetHandleProc(
730 ClientData instanceData,
731 int direction,
732 ClientData *handlePtr);
733 InstanceData is the same as the value passed to Tcl_CreateChannel when
735 this channel was created. The direction argument is either TCL_READABLE
736 to retrieve the handle used for input, or TCL_WRITABLE to retrieve the
737 handle used for output.
738 If the channel implementation has device-specific handles, the function
740 should retrieve the appropriate handle associated with the channel, ac‐
741 cording the direction argument. The handle should be stored in the lo‐
742 cation referred to by handlePtr, and TCL_OK should be returned. If the
743 channel is not open for the specified direction, or if the channel im‐
744 plementation does not use device handles, the function should return
745 TCL_ERROR.
746 This value can be retrieved with Tcl_ChannelGetHandleProc, which re‐
748 turns a pointer to the function.
749 FLUSHPROC
751 The flushProc field is currently reserved for future use. It should be
752 set to NULL. FlushProc should match the following prototype:
753 typedef int Tcl_DriverFlushProc(
755 ClientData instanceData);
756 This value can be retrieved with Tcl_ChannelFlushProc, which returns a
758 pointer to the function.
759 HANDLERPROC
761 The handlerProc field contains the address of a function called by the
762 generic layer to notify the channel that an event occurred. It should
763 be defined for stacked channel drivers that wish to be notified of
764 events that occur on the underlying (stacked) channel. HandlerProc
765 should match the following prototype:
766 typedef int Tcl_DriverHandlerProc(
768 ClientData instanceData,
769 int interestMask);
770 InstanceData is the same as the value passed to Tcl_CreateChannel when
772 this channel was created. The interestMask is an OR-ed combination of
773 TCL_READABLE or TCL_WRITABLE; it indicates what type of event occurred
774 on this channel.
775 This value can be retrieved with Tcl_ChannelHandlerProc, which returns
777 a pointer to the function.
778 THREADACTIONPROC
781 The threadActionProc field contains the address of the function called
782 by the generic layer when a channel is created, closed, or going to
783 move to a different thread, i.e. whenever thread-specific driver state
784 might have to initialized or updated. It can be NULL. The action
785 TCL_CHANNEL_THREAD_REMOVE is used to notify the driver that it should
786 update or remove any thread-specific data it might be maintaining for
787 the channel.
788 The action TCL_CHANNEL_THREAD_INSERT is used to notify the driver that
790 it should update or initialize any thread-specific data it might be
791 maintaining using the calling thread as the associate. See Tcl_CutChan‐
792 nel and Tcl_SpliceChannel for more detail.
793 typedef void Tcl_DriverThreadActionProc(
795 ClientData instanceData,
796 int action);
797 InstanceData is the same as the value passed to Tcl_CreateChannel when
799 this channel was created.
800 These values can be retrieved with Tcl_ChannelThreadActionProc, which
802 returns a pointer to the function.
803 TRUNCATEPROC
805 The truncateProc field contains the address of the function called by
806 the generic layer when a channel is truncated to some length. It can be
807 NULL.
808 typedef int Tcl_DriverTruncateProc(
810 ClientData instanceData,
811 Tcl_WideInt length);
812 InstanceData is the same as the value passed to Tcl_CreateChannel when
814 this channel was created, and length is the new length of the underly‐
815 ing file, which should not be negative. The result should be 0 on suc‐
816 cess or an errno code (suitable for use with Tcl_SetErrno) on failure.
817 These values can be retrieved with Tcl_ChannelTruncateProc, which re‐
819 turns a pointer to the function.
820
822 This procedure generates a “bad option” error message in an (optional)
823 interpreter. It is used by channel drivers when an invalid Set/Get op‐
824 tion is requested. Its purpose is to concatenate the generic options
825 list to the specific ones and factorize the generic options error mes‐
826 sage string.
827 It always returns TCL_ERROR
829 An error message is generated in interp's result value to indicate that
831 a command was invoked with a bad option. The message has the form
832 bad option "blah": should be one of
833 <...generic options...>+<...specific options...>
834 so you get for instance:
835 bad option "-blah": should be one of -blocking,
836 -buffering, -buffersize, -eofchar, -translation,
837 -peername, or -sockname
838 when called with optionList equal to “peername sockname”
839 “blah” is the optionName argument and “<specific options>” is a space
841 separated list of specific option words. The function takes good care
842 of inserting minus signs before each option, commas after, and an “or”
843 before the last option.
844
846 The original (8.3.1 and below) Tcl_ChannelType structure contains the
847 following fields:
848 typedef struct Tcl_ChannelType {
850 const char *typeName;
851 Tcl_DriverBlockModeProc *blockModeProc;
852 Tcl_DriverCloseProc *closeProc;
853 Tcl_DriverInputProc *inputProc;
854 Tcl_DriverOutputProc *outputProc;
855 Tcl_DriverSeekProc *seekProc;
856 Tcl_DriverSetOptionProc *setOptionProc;
857 Tcl_DriverGetOptionProc *getOptionProc;
858 Tcl_DriverWatchProc *watchProc;
859 Tcl_DriverGetHandleProc *getHandleProc;
860 Tcl_DriverClose2Proc *close2Proc;
861 } Tcl_ChannelType;
862 It is still possible to create channel with the above structure. The
864 internal channel code will determine the version. It is imperative to
865 use the new Tcl_ChannelType structure if you are creating a stacked
866 channel driver, due to problems with the earlier stacked channel imple‐
867 mentation (in 8.2.0 to 8.3.1).
868 Prior to 8.4.0 (i.e. during the later releases of 8.3 and early part of
870 the 8.4 development cycle) the Tcl_ChannelType structure contained the
871 following fields:
872 typedef struct Tcl_ChannelType {
874 const char *typeName;
875 Tcl_ChannelTypeVersion version;
876 Tcl_DriverCloseProc *closeProc;
877 Tcl_DriverInputProc *inputProc;
878 Tcl_DriverOutputProc *outputProc;
879 Tcl_DriverSeekProc *seekProc;
880 Tcl_DriverSetOptionProc *setOptionProc;
881 Tcl_DriverGetOptionProc *getOptionProc;
882 Tcl_DriverWatchProc *watchProc;
883 Tcl_DriverGetHandleProc *getHandleProc;
884 Tcl_DriverClose2Proc *close2Proc;
885 Tcl_DriverBlockModeProc *blockModeProc;
886 Tcl_DriverFlushProc *flushProc;
887 Tcl_DriverHandlerProc *handlerProc;
888 Tcl_DriverTruncateProc *truncateProc;
889 } Tcl_ChannelType;
890 When the above structure is registered as a channel type, the version
892 field should always be TCL_CHANNEL_VERSION_2.
893
895 Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3),
896 Tcl_QueueEvent(3), Tcl_StackChannel(3), Tcl_GetStdChannel(3)
897
899 blocking, channel driver, channel registration, channel type, nonblock‐
900 ing
901Tcl 8.4 Tcl_CreateChannel(3)