1Tcl_CreateChannel(3)        Tcl Library Procedures        Tcl_CreateChannel(3)
2
3
4
5______________________________________________________________________________
6

NAME

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

SYNOPSIS

23       #include <tcl.h>
24
25       Tcl_Channel
26       Tcl_CreateChannel(typePtr, channelName, instanceData, mask)
27
28       ClientData
29       Tcl_GetChannelInstanceData(channel)
30
31       Tcl_ChannelType *
32       Tcl_GetChannelType(channel)
33
34       const char *
35       Tcl_GetChannelName(channel)
36
37       int
38       Tcl_GetChannelHandle(channel, direction, handlePtr)
39
40       Tcl_ThreadId
41       Tcl_GetChannelThread(channel)
42
43       int
44       Tcl_GetChannelMode(channel)
45
46       int
47       Tcl_GetChannelBufferSize(channel)
48
49       Tcl_SetChannelBufferSize(channel, size)
50
51       Tcl_NotifyChannel(channel, mask)
52
53       int
54       Tcl_BadChannelOption(interp, optionName, optionList)
55
56       int
57       Tcl_IsChannelShared(channel)
58
59       int
60       Tcl_IsChannelRegistered(interp, channel)
61
62       int
63       Tcl_IsChannelExisting(channelName)
64
65       void
66       Tcl_CutChannel(channel)
67
68       void
69       Tcl_SpliceChannel(channel)
70
71       void
72       Tcl_ClearChannelHandlers(channel)
73
74       int
75       Tcl_ChannelBuffered(channel)
76
77       const char *
78       Tcl_ChannelName(typePtr)
79
80       Tcl_ChannelTypeVersion
81       Tcl_ChannelVersion(typePtr)
82
83       Tcl_DriverBlockModeProc *
84       Tcl_ChannelBlockModeProc(typePtr)
85
86       Tcl_DriverCloseProc *
87       Tcl_ChannelCloseProc(typePtr)
88
89       Tcl_DriverClose2Proc *
90       Tcl_ChannelClose2Proc(typePtr)
91
92       Tcl_DriverInputProc *
93       Tcl_ChannelInputProc(typePtr)
94
95       Tcl_DriverOutputProc *
96       Tcl_ChannelOutputProc(typePtr)
97
98       Tcl_DriverSeekProc *
99       Tcl_ChannelSeekProc(typePtr)
100
101       Tcl_DriverWideSeekProc *
102       Tcl_ChannelWideSeekProc(typePtr)
103
104       Tcl_DriverThreadActionProc *
105       Tcl_ChannelThreadActionProc(typePtr)
106
107       Tcl_DriverTruncateProc *                                                │
108       Tcl_ChannelTruncateProc(typePtr)                                        │
109
110       Tcl_DriverSetOptionProc *
111       Tcl_ChannelSetOptionProc(typePtr)
112
113       Tcl_DriverGetOptionProc *
114       Tcl_ChannelGetOptionProc(typePtr)
115
116       Tcl_DriverWatchProc *
117       Tcl_ChannelWatchProc(typePtr)
118
119       Tcl_DriverGetHandleProc *
120       Tcl_ChannelGetHandleProc(typePtr)
121
122       Tcl_DriverFlushProc *
123       Tcl_ChannelFlushProc(typePtr)
124
125       Tcl_DriverHandlerProc *
126       Tcl_ChannelHandlerProc(typePtr)
127
128

ARGUMENTS

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
138       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
146       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
154       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
161       Tcl_Channel channel (in)                         The channel to operate
162                                                        on.
163
164       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
170       ClientData *handlePtr (out)                      Points to the location
171                                                        where the desired  OS-
172                                                        specific handle should
173                                                        be stored.
174
175       int size (in)                                    The size, in bytes, of
176                                                        buffers to allocate in
177                                                        this channel.
178
179       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
187       Tcl_Interp *interp (in)                          Current   interpreter.
188                                                        (can be NULL)
189
190       const char *optionName (in)                      Name  of  the  invalid
191                                                        option.
192
193       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
202_________________________________________________________________
203
204

DESCRIPTION

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
212       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
218       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
225       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
231       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
237       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
244       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
250       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
258       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
262       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
267       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
271       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
279       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
283       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
287       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
292       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
298       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
304       Tcl_BadChannelOption  is  called  from driver specific setOptionProc or
305       getOptionProc to generate a complete error message.
306
307       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
312       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
316       Tcl_IsChannelRegistered  checks whether the specified channel is regis‐
317       tered in the given interpreter (result == 1) or not (result == 0).
318
319       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
323       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
329       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
335       Tcl_ClearChannelHandlers removes all channel handlers and event scripts
336       associated  with  the  specified  channel, thus shutting down all event
337       processing for this channel.
338

TCL_CHANNELTYPE

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
347       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
368       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
377       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
387       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
392   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
397       This  value  can  be  retrieved  with  Tcl_ChannelName, which returns a
398       pointer to the string.
399
400   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 specify the  wideSeekProc  member.
404       TCL_CHANNEL_VERSION_4  must be set to specify the threadActionProc mem‐
405       ber (includes wideSeekProc).   TCL_CHANNEL_VERSION_5  must  be  set  to │
406       specify  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
413       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
417   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
422              typedef int Tcl_DriverBlockModeProc(
423                      ClientData instanceData,
424                      int mode);
425
426       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
433       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
440       This  value  can  be  retrieved  with  Tcl_ChannelBlockModeProc,  which
441       returns a pointer to the function.
442
443       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  unacceptable
447       value. Any confusion here may lead the interpreter into a (spurious and
448       difficult to find) deadlock.
449
450   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
455              typedef int Tcl_DriverCloseProc(
456                      ClientData instanceData,
457                      Tcl_Interp *interp);
458
459       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
471       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
475              typedef int Tcl_DriverClose2Proc(
476                      ClientData instanceData,
477                      Tcl_Interp *interp,
478                      int flags);
479
480       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
493       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
497   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
502              typedef int Tcl_DriverInputProc(
503                      ClientData instanceData,
504                      char *buf,
505                      int bufSize,
506                      int *errorCodePtr);
507
508       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
513       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
517       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
524       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
535       This value can be retrieved with Tcl_ChannelInputProc, which returns  a
536       pointer to the function.
537
538   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
543              typedef int Tcl_DriverOutputProc(
544                      ClientData instanceData,
545                      const char *buf,
546                      int toWrite,
547                      int *errorCodePtr);
548
549       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
554       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
558       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
566       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
570       This value can be retrieved with Tcl_ChannelOutputProc, which returns a
571       pointer to the function.
572
573   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
579              typedef int Tcl_DriverSeekProc(
580                      ClientData instanceData,
581                      long offset,
582                      int seekMode,
583                      int *errorCodePtr);
584
585       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
590       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
596       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
599       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
606              typedef Tcl_WideInt Tcl_DriverWideSeekProc(
607                      ClientData instanceData,
608                      Tcl_WideInt offset,
609                      int seekMode,
610                      int *errorCodePtr);
611
612       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
616       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
620   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
625              typedef int Tcl_DriverSetOptionProc(
626                      ClientData instanceData,
627                      Tcl_Interp *interp,
628                      const char *optionName,
629                      const char *newValue);
630
631       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
637       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
644       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
652       This  value  can  be  retrieved  with  Tcl_ChannelSetOptionProc,  which
653       returns a pointer to the function.
654
655   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
660              typedef int Tcl_DriverGetOptionProc(
661                      ClientData instanceData,
662                      Tcl_Interp *interp,
663                      const char *optionName,
664                      Tcl_DString *optionValue);
665
666       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
677       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
684       This  value  can  be  retrieved  with  Tcl_ChannelGetOptionProc,  which
685       returns a pointer to the function.
686
687   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
693              typedef void Tcl_DriverWatchProc(
694                      ClientData instanceData,
695                      int mask);
696
697       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
702       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
713       This  value can be retrieved with Tcl_ChannelWatchProc, which returns a
714       pointer to the function.
715
716   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
721              typedef int Tcl_DriverGetHandleProc(
722                      ClientData instanceData,
723                      int direction,
724                      ClientData *handlePtr);
725
726       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
731       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
739       This  value  can  be  retrieved  with  Tcl_ChannelGetHandleProc,  which
740       returns a pointer to the function.
741
742   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
746              typedef int Tcl_DriverFlushProc(
747                      ClientData instanceData);
748
749       This  value can be retrieved with Tcl_ChannelFlushProc, which returns a
750       pointer to the function.
751
752   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
759              typedef int Tcl_DriverHandlerProc(
760                      ClientData instanceData,
761                      int interestMask);
762
763       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
768       This  value can be retrieved with Tcl_ChannelHandlerProc, which returns
769       a pointer to the function.
770
771
772   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
781       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
786              typedef void Tcl_DriverThreadActionProc(
787                      ClientData instanceData,
788                      int        action);
789
790       InstanceData  is the same as the value passed to Tcl_CreateChannel when
791       this channel was created.
792
793       These values can be retrieved with  Tcl_ChannelThreadActionProc,  which
794       returns a pointer to the function.
795
796   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
801              typedef int Tcl_DriverTruncateProc(
802                      ClientData instanceData,
803                      Tcl_WideInt length);
804
805       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
810       These values  can  be  retrieved  with  Tcl_ChannelTruncateProc,  which
811       returns a pointer to the function.
812

TCL_BADCHANNELOPTION

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
820       It always returns TCL_ERROR
821
822       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
832       “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

OLD CHANNEL TYPES

838       The  original  (8.3.1 and below) Tcl_ChannelType structure contains the
839       following fields:
840
841              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
855       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
861       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
865              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
883       When the above structure is registered as a channel type,  the  version
884       field should always be TCL_CHANNEL_VERSION_2.
885
886

SEE ALSO

888       Tcl_Close(3),          Tcl_OpenFileChannel(3),         Tcl_SetErrno(3),
889       Tcl_QueueEvent(3), Tcl_StackChannel(3), Tcl_GetStdChannel(3)
890
891

KEYWORDS

893       blocking, channel driver, channel registration, channel type, nonblock‐
894       ing
895
896
897
898Tcl                                   8.4                 Tcl_CreateChannel(3)
Impressum