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       const 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. If the
145                                                        created   channel   is
146                                                        assigned to one of the
147                                                        standard      channels
148                                                        (stdin,    stdout   or
149                                                        stderr), the  assigned
150                                                        channel  name  will be
151                                                        the name of the  stan‐
152                                                        dard channel.
153
154       ClientData instanceData (in)                     Arbitrary     one-word
155                                                        value to be associated
156                                                        with   this   channel.
157                                                        This value  is  passed
158                                                        to procedures in type‐
159                                                        Ptr  when   they   are
160                                                        invoked.
161
162       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
169       Tcl_Channel channel (in)                         The channel to operate
170                                                        on.
171
172       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
178       ClientData *handlePtr (out)                      Points to the location
179                                                        where the desired  OS-
180                                                        specific handle should
181                                                        be stored.
182
183       int size (in)                                    The size, in bytes, of
184                                                        buffers to allocate in
185                                                        this channel.
186
187       int mask (in)                                    An  OR-ed  combination
188                                                        of       TCL_READABLE,
189                                                        TCL_WRITABLE       and
190                                                        TCL_EXCEPTION     that
191                                                        indicates events  that
192                                                        have  occurred on this
193                                                        channel.
194
195       Tcl_Interp *interp (in)                          Current   interpreter.
196                                                        (can be NULL)
197
198       const char *optionName (in)                      Name  of  the  invalid
199                                                        option.
200
201       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

DESCRIPTION

212       Tcl  uses  a  two-layered  channel  architecture. It provides a generic
213       upper layer to enable C and Tcl programs to perform  input  and  output
214       using  the  same APIs for a variety of files, devices, sockets etc. The
215       generic C APIs are described in the manual entry for  Tcl_OpenFileChan‐
216       nel.
217
218       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
224       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
231       Second, channel  drivers  usually  provide  a  Tcl  command  to  create
232       instances  of  that  type of channel. For example, the Tcl open command
233       creates channels that use the file and command channel drivers, and the
234       Tcl  socket  command  creates channels that use TCP sockets for network
235       communication.
236
237       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
243       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
250       Tcl_CreateChannel opens a new channel and associates the supplied type‐
251       Ptr and instanceData with it. The channel is opened in the  mode  indi‐
252       cated  by  mask.  For a discussion of channel drivers, their operations
253       and the Tcl_ChannelType structure,  see  the  section  TCL_CHANNELTYPE,
254       below.
255
256       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
264       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
268       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
273       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
277       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
285       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
289       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
293       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
298       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
304       Tcl_NotifyChannel  is  called  by  a  channel driver to indicate to the
305       generic layer that the events specified by mask have  occurred  on  the
306       channel.   Channel  drivers  are responsible for invoking this function
307       whenever the channel handlers need to be called for the  channel.   See
308       WATCHPROC below for more details.
309
310       Tcl_BadChannelOption  is  called  from driver specific setOptionProc or
311       getOptionProc to generate a complete error message.
312
313       Tcl_ChannelBuffered returns the number  of  bytes  of  input  currently
314       buffered in the internal buffer (push back area) of the channel itself.
315       It does not report about the data in the overall buffers for the  stack
316       of channels the supplied channel is part of.
317
318       Tcl_IsChannelShared  checks  the  refcount of the specified channel and
319       returns whether the channel  was  shared  among  multiple  interpreters
320       (result == 1) or not (result == 0).
321
322       Tcl_IsChannelRegistered  checks whether the specified channel is regis‐
323       tered in the given interpreter (result == 1) or not (result == 0).
324
325       Tcl_IsChannelExisting checks whether a channel with the specified  name
326       is registered in the (thread)-global list of all channels (result == 1)
327       or not (result == 0).
328
329       Tcl_CutChannel removes the specified channel  from  the  (thread)global
330       list of all channels (of the current thread).  Application to a channel
331       still registered in some interpreter is not allowed.  Also notifies the
332       driver  if  the  Tcl_ChannelType  version  is TCL_CHANNEL_VERSION_4 (or
333       higher), and Tcl_DriverThreadActionProc is defined for it.
334
335       Tcl_SpliceChannel adds the specified channel to the (thread)global list
336       of all channels (of the current thread).  Application to a channel reg‐
337       istered in some interpreter is not allowed.  Also notifies  the  driver
338       if  the  Tcl_ChannelType  version is TCL_CHANNEL_VERSION_4 (or higher),
339       and Tcl_DriverThreadActionProc is defined for it.
340
341       Tcl_ClearChannelHandlers removes all channel handlers and event scripts
342       associated  with  the  specified  channel, thus shutting down all event
343       processing for this channel.
344

TCL_CHANNELTYPE

346       A channel driver provides a  Tcl_ChannelType  structure  that  contains
347       pointers  to functions that implement the various operations on a chan‐
348       nel; these operations are invoked as needed by the generic layer.   The
349       structure  was versioned starting in Tcl 8.3.2/8.4 to correct a problem
350       with stacked channel drivers.  See the OLD CHANNEL TYPES section  below
351       for details about the old structure.
352
353       The Tcl_ChannelType structure contains the following fields:
354
355              typedef struct Tcl_ChannelType {
356                      const char *typeName;
357                      Tcl_ChannelTypeVersion version;
358                      Tcl_DriverCloseProc *closeProc;
359                      Tcl_DriverInputProc *inputProc;
360                      Tcl_DriverOutputProc *outputProc;
361                      Tcl_DriverSeekProc *seekProc;
362                      Tcl_DriverSetOptionProc *setOptionProc;
363                      Tcl_DriverGetOptionProc *getOptionProc;
364                      Tcl_DriverWatchProc *watchProc;
365                      Tcl_DriverGetHandleProc *getHandleProc;
366                      Tcl_DriverClose2Proc *close2Proc;
367                      Tcl_DriverBlockModeProc *blockModeProc;
368                      Tcl_DriverFlushProc *flushProc;
369                      Tcl_DriverHandlerProc *handlerProc;
370                      Tcl_DriverWideSeekProc *wideSeekProc;
371                      Tcl_DriverThreadActionProc *threadActionProc;
372                      Tcl_DriverTruncateProc *truncateProc;
373              } Tcl_ChannelType;
374
375       It  is  not necessary to provide implementations for all channel opera‐
376       tions.  Those which are not necessary may be set to NULL in the struct:
377       blockModeProc,  seekProc,  setOptionProc, getOptionProc, getHandleProc,
378       and close2Proc, in addition to  flushProc,  handlerProc,  threadAction‐
379       Proc,  and truncateProc.  Other functions that cannot be implemented in
380       a meaningful way should return EINVAL when called, to indicate that the
381       operations   they   represent   are   not  available.  Also  note  that
382       wideSeekProc can be NULL if seekProc is.
383
384       The user should  only  use  the  above  structure  for  Tcl_ChannelType
385       instantiation.  When referencing fields in a Tcl_ChannelType structure,
386       the following functions should be used to obtain the values:  Tcl_Chan‐
387       nelName,   Tcl_ChannelVersion,  Tcl_ChannelBlockModeProc,  Tcl_Channel‐
388       CloseProc, Tcl_ChannelClose2Proc, Tcl_ChannelInputProc, Tcl_ChannelOut‐
389       putProc,    Tcl_ChannelSeekProc,   Tcl_ChannelWideSeekProc,   Tcl_Chan‐
390       nelThreadActionProc, Tcl_ChannelTruncateProc, Tcl_ChannelSetOptionProc,
391       Tcl_ChannelGetOptionProc,     Tcl_ChannelWatchProc,    Tcl_ChannelGetH‐
392       andleProc, Tcl_ChannelFlushProc, or Tcl_ChannelHandlerProc.
393
394       The change to the structures was made in such a way that standard chan‐
395       nel  types  are  binary  compatible.   However,  channel types that use
396       stacked channels (i.e. TLS, Trf) have new versions to correspond to the
397       above change since the previous code for stacked channels had problems.
398
399   TYPENAME
400       The  typeName  field  contains a null-terminated string that identifies
401       the type of the device  implemented  by  this  driver,  e.g.   file  or
402       socket.
403
404       This  value  can  be  retrieved  with  Tcl_ChannelName, which returns a
405       pointer to the string.
406
407   VERSION
408       The version field should be set to the version of  the  structure  that
409       you   require.   TCL_CHANNEL_VERSION_2   is  the  minimum  recommended.
410       TCL_CHANNEL_VERSION_3 must be set to specify the  wideSeekProc  member.
411       TCL_CHANNEL_VERSION_4  must be set to specify the threadActionProc mem‐
412       ber (includes wideSeekProc).   TCL_CHANNEL_VERSION_5  must  be  set  to
413       specify  the  truncateProc members (includes wideSeekProc and threadAc‐
414       tionProc).  If it is not set to any of these, then this Tcl_ChannelType
415       is  assumed  to have the original structure.  See OLD CHANNEL TYPES for
416       more details.  While Tcl will recognize and function with either struc‐
417       tures,  stacked  channels  must be of at least TCL_CHANNEL_VERSION_2 to
418       function correctly.
419
420       This value can be retrieved with Tcl_ChannelVersion, which returns  one
421       of TCL_CHANNEL_VERSION_5, TCL_CHANNEL_VERSION_4, TCL_CHANNEL_VERSION_3,
422       TCL_CHANNEL_VERSION_2 or TCL_CHANNEL_VERSION_1.
423
424   BLOCKMODEPROC
425       The blockModeProc field contains the address of a  function  called  by
426       the  generic  layer to set blocking and nonblocking mode on the device.
427       BlockModeProc should match the following prototype:
428
429              typedef int Tcl_DriverBlockModeProc(
430                      ClientData instanceData,
431                      int mode);
432
433       The instanceData is the same as the value passed  to  Tcl_CreateChannel
434       when   this   channel   was  created.   The  mode  argument  is  either
435       TCL_MODE_BLOCKING or TCL_MODE_NONBLOCKING to set the device into block‐
436       ing  or nonblocking mode. The function should return zero if the opera‐
437       tion was successful, or a nonzero POSIX error  code  if  the  operation
438       failed.
439
440       If  the  operation  is successful, the function can modify the supplied
441       instanceData to record that the channel entered blocking or nonblocking
442       mode  and  to implement the blocking or nonblocking behavior.  For some
443       device types, the blocking and nonblocking behavior can be  implemented
444       by  the underlying operating system; for other device types, the behav‐
445       ior must be emulated in the channel driver.
446
447       This  value  can  be  retrieved  with  Tcl_ChannelBlockModeProc,  which
448       returns a pointer to the function.
449
450       A  channel  driver  not  supplying a blockModeProc has to be very, very
451       careful. It has to tell the generic layer exactly which  blocking  mode
452       is acceptable to it, and should this also document for the user so that
453       the blocking mode of the channel is  not  changed  to  an  unacceptable
454       value. Any confusion here may lead the interpreter into a (spurious and
455       difficult to find) deadlock.
456
457   CLOSEPROC AND CLOSE2PROC
458       The closeProc field contains the address of a function  called  by  the
459       generic  layer  to clean up driver-related information when the channel
460       is closed. CloseProc must match the following prototype:
461
462              typedef int Tcl_DriverCloseProc(
463                      ClientData instanceData,
464                      Tcl_Interp *interp);
465
466       The instanceData argument is the same as the value provided to Tcl_Cre‐
467       ateChannel  when  the  channel was created. The function should release
468       any storage maintained by the channel  driver  for  this  channel,  and
469       close  the  input  and output devices encapsulated by this channel. All
470       queued output will have been flushed to the device before this function
471       is  called,  and  no  further driver operations will be invoked on this
472       instance after calling the closeProc. If the close  operation  is  suc‐
473       cessful, the procedure should return zero; otherwise it should return a
474       nonzero POSIX error code. In addition, if an error occurs and interp is
475       not  NULL,  the  procedure  should store an error message in the inter‐
476       preter's result.
477
478       Alternatively, channels that support closing the read and  write  sides
479       independently may set closeProc to TCL_CLOSE2PROC and set close2Proc to
480       the address of a function that matches the following prototype:
481
482              typedef int Tcl_DriverClose2Proc(
483                      ClientData instanceData,
484                      Tcl_Interp *interp,
485                      int flags);
486
487       The close2Proc will be called with flags set to an OR'ed combination of
488       TCL_CLOSE_READ  or  TCL_CLOSE_WRITE  to indicate that the driver should
489       close the read and/or write side of the channel.   The  channel  driver
490       may  be  invoked  to perform additional operations on the channel after
491       close2Proc is called to close one or both sides  of  the  channel.   If
492       flags  is  0  (zero), the driver should close the channel in the manner
493       described above for closeProc.  No further operations will  be  invoked
494       on this instance after close2Proc is called with all flags cleared.  In
495       all cases, the close2Proc function should  return  zero  if  the  close
496       operation  was  successful;  otherwise it should return a nonzero POSIX
497       error code. In addition, if an error occurs and interp is not NULL, the
498       procedure should store an error message in the interpreter's result.
499
500       The  closeProc and close2Proc values can be retrieved with Tcl_Channel‐
501       CloseProc or Tcl_ChannelClose2Proc,  which  return  a  pointer  to  the
502       respective function.
503
504   INPUTPROC
505       The  inputProc  field  contains the address of a function called by the
506       generic layer to read data from the file or device and store it  in  an
507       internal buffer. InputProc must match the following prototype:
508
509              typedef int Tcl_DriverInputProc(
510                      ClientData instanceData,
511                      char *buf,
512                      int bufSize,
513                      int *errorCodePtr);
514
515       InstanceData  is the same as the value passed to Tcl_CreateChannel when
516       the channel was created.  The buf argument points to an array of  bytes
517       in which to store input from the device, and the bufSize argument indi‐
518       cates how many bytes are available at buf.
519
520       The errorCodePtr argument points to an integer variable provided by the
521       generic layer. If an error occurs, the function should set the variable
522       to a POSIX error code that identifies the error that occurred.
523
524       The function should read data from the input device encapsulated by the
525       channel  and store it at buf.  On success, the function should return a
526       nonnegative integer indicating how many bytes were read from the  input
527       device  and  stored at buf. On error, the function should return -1. If
528       an error occurs after some data has been read  from  the  device,  that
529       data is lost.
530
531       If  inputProc  can determine that the input device has some data avail‐
532       able but less than requested by  the  bufSize  argument,  the  function
533       should  only  attempt  to  read as much data as is available and return
534       without blocking. If the input device has no data available  whatsoever
535       and  the  channel is in nonblocking mode, the function should return an
536       EAGAIN error. If the input device has no data available whatsoever  and
537       the  channel  is  in  blocking  mode, the function should block for the
538       shortest possible time until at least one byte of data can be read from
539       the  device; then, it should return as much data as it can read without
540       blocking.
541
542       This value can be retrieved with Tcl_ChannelInputProc, which returns  a
543       pointer to the function.
544
545   OUTPUTPROC
546       The  outputProc  field contains the address of a function called by the
547       generic layer to transfer data from an internal buffer  to  the  output
548       device.  OutputProc must match the following prototype:
549
550              typedef int Tcl_DriverOutputProc(
551                      ClientData instanceData,
552                      const char *buf,
553                      int toWrite,
554                      int *errorCodePtr);
555
556       InstanceData  is the same as the value passed to Tcl_CreateChannel when
557       the channel was created. The buf argument contains an array of bytes to
558       be  written  to the device, and the toWrite argument indicates how many
559       bytes are to be written from the buf argument.
560
561       The errorCodePtr argument points to an integer variable provided by the
562       generic  layer.  If an error occurs, the function should set this vari‐
563       able to a POSIX error code that identifies the error.
564
565       The function should write the data at buf to the output device encapsu‐
566       lated by the channel. On success, the function should return a nonnega‐
567       tive integer indicating how many  bytes  were  written  to  the  output
568       device.   The  return value is normally the same as toWrite, but may be
569       less in some cases such as if the output operation is interrupted by  a
570       signal.  If  an error occurs the function should return -1.  In case of
571       error, some data may have been written to the device.
572
573       If the channel is nonblocking and the output device is unable to absorb
574       any data whatsoever, the function should return -1 with an EAGAIN error
575       without writing any data.
576
577       This value can be retrieved with Tcl_ChannelOutputProc, which returns a
578       pointer to the function.
579
580   SEEKPROC AND WIDESEEKPROC
581       The  seekProc  field  contains  the address of a function called by the
582       generic layer to move the access point at  which  subsequent  input  or
583       output  operations  will  be applied. SeekProc must match the following
584       prototype:
585
586              typedef int Tcl_DriverSeekProc(
587                      ClientData instanceData,
588                      long offset,
589                      int seekMode,
590                      int *errorCodePtr);
591
592       The instanceData argument is the same as the value given to Tcl_Create‐
593       Channel  when  this  channel was created.  Offset and seekMode have the
594       same meaning as for the Tcl_Seek procedure  (described  in  the  manual
595       entry for Tcl_OpenFileChannel).
596
597       The errorCodePtr argument points to an integer variable provided by the
598       generic layer for returning errno values from the function.  The  func‐
599       tion should set this variable to a POSIX error code if an error occurs.
600       The function should store an EINVAL error code if the channel type does
601       not implement seeking.
602
603       The  return value is the new access point or -1 in case of error. If an
604       error occurred, the function should not move the access point.
605
606       If there is a non-NULL seekProc field, the wideSeekProc field may  con‐
607       tain  the  address of an alternative function to use which handles wide
608       (i.e. larger than 32-bit)  offsets,  so  allowing  seeks  within  files
609       larger  than 2GB.  The wideSeekProc will be called in preference to the
610       seekProc, but both must be defined  if  the  wideSeekProc  is  defined.
611       WideSeekProc must match the following prototype:
612
613              typedef Tcl_WideInt Tcl_DriverWideSeekProc(
614                      ClientData instanceData,
615                      Tcl_WideInt offset,
616                      int seekMode,
617                      int *errorCodePtr);
618
619       The  arguments  and  return values mean the same thing as with seekProc
620       above, except that the type of offsets and the return type are  differ‐
621       ent.
622
623       The  seekProc  value  can  be retrieved with Tcl_ChannelSeekProc, which
624       returns a pointer to the function, and similarly the  wideSeekProc  can
625       be retrieved with Tcl_ChannelWideSeekProc.
626
627   SETOPTIONPROC
628       The  setOptionProc  field  contains the address of a function called by
629       the generic layer to set a channel type specific option on  a  channel.
630       setOptionProc must match the following prototype:
631
632              typedef int Tcl_DriverSetOptionProc(
633                      ClientData instanceData,
634                      Tcl_Interp *interp,
635                      const char *optionName,
636                      const char *newValue);
637
638       optionName  is  the  name  of an option to set, and newValue is the new
639       value for that option, as a string. The instanceData is the same as the
640       value  given  to  Tcl_CreateChannel  when this channel was created. The
641       function should do whatever channel type specific action is required to
642       implement the new value of the option.
643
644       Some options are handled by the generic code and this function is never
645       called to set them, e.g. -blockmode. Other options are specific to each
646       channel type and the setOptionProc procedure of the channel driver will
647       get called to implement them. The  setOptionProc  field  can  be  NULL,
648       which  indicates  that  this  channel  type  supports  no type specific
649       options.
650
651       If the option value is successfully modified  to  the  new  value,  the
652       function  returns  TCL_OK.   It  should call Tcl_BadChannelOption which
653       itself returns TCL_ERROR if the optionName is  unrecognized.   If  new‐
654       Value  specifies  a  value for the option that is not supported or if a
655       system call error occurs, the function should leave an error message in
656       the  result  field of interp if interp is not NULL. The function should
657       also call Tcl_SetErrno to store an appropriate POSIX error code.
658
659       This  value  can  be  retrieved  with  Tcl_ChannelSetOptionProc,  which
660       returns a pointer to the function.
661
662   GETOPTIONPROC
663       The  getOptionProc  field  contains the address of a function called by
664       the generic layer to get the value of a channel type specific option on
665       a channel. getOptionProc must match the following prototype:
666
667              typedef int Tcl_DriverGetOptionProc(
668                      ClientData instanceData,
669                      Tcl_Interp *interp,
670                      const char *optionName,
671                      Tcl_DString *optionValue);
672
673       OptionName  is the name of an option supported by this type of channel.
674       If the option name is not NULL, the function stores its current  value,
675       as  a  string, in the Tcl dynamic string optionValue.  If optionName is
676       NULL, the function stores in optionValue an  alternating  list  of  all
677       supported  options  and their current values.  On success, the function
678       returns TCL_OK.   It  should  call  Tcl_BadChannelOption  which  itself
679       returns  TCL_ERROR  if the optionName is unrecognized. If a system call
680       error occurs, the function should leave an error message in the  result
681       of  interp  if  interp  is  not  NULL.  The  function  should also call
682       Tcl_SetErrno to store an appropriate POSIX error code.
683
684       Some options are handled by the generic code and this function is never
685       called to retrieve their value, e.g. -blockmode. Other options are spe‐
686       cific to each channel type and the getOptionProc procedure of the chan‐
687       nel  driver  will get called to implement them. The getOptionProc field
688       can be NULL, which indicates that this channel type  supports  no  type
689       specific options.
690
691       This  value  can  be  retrieved  with  Tcl_ChannelGetOptionProc,  which
692       returns a pointer to the function.
693
694   WATCHPROC
695       The watchProc field contains the address of a function  called  by  the
696       generic  layer to initialize the event notification mechanism to notice
697       events of interest on this channel.  WatchProc should match the follow‐
698       ing prototype:
699
700              typedef void Tcl_DriverWatchProc(
701                      ClientData instanceData,
702                      int mask);
703
704       The  instanceData  is the same as the value passed to Tcl_CreateChannel
705       when this channel was created. The mask argument is an  OR-ed  combina‐
706       tion  of  TCL_READABLE,  TCL_WRITABLE  and  TCL_EXCEPTION; it indicates
707       events the caller is interested in noticing on this channel.
708
709       The function should  initialize  device  type  specific  mechanisms  to
710       notice  when  an event of interest is present on the channel.  When one
711       or more of the designated events occurs on  the  channel,  the  channel
712       driver  is  responsible  for  calling  Tcl_NotifyChannel  to inform the
713       generic channel module.  The driver should  take  care  not  to  starve
714       other  channel  drivers or sources of callbacks by invoking Tcl_Notify‐
715       Channel too frequently.  Fairness can be insured by using the Tcl event
716       queue to allow the channel event to be scheduled in sequence with other
717       events.  See the description of Tcl_QueueEvent for details  on  how  to
718       queue an event.
719
720       This  value can be retrieved with Tcl_ChannelWatchProc, which returns a
721       pointer to the function.
722
723   GETHANDLEPROC
724       The getHandleProc field contains the address of a  function  called  by
725       the  generic  layer to retrieve a device-specific handle from the chan‐
726       nel.  GetHandleProc should match the following prototype:
727
728              typedef int Tcl_DriverGetHandleProc(
729                      ClientData instanceData,
730                      int direction,
731                      ClientData *handlePtr);
732
733       InstanceData is the same as the value passed to Tcl_CreateChannel  when
734       this channel was created. The direction argument is either TCL_READABLE
735       to retrieve the handle used for input, or TCL_WRITABLE to retrieve  the
736       handle used for output.
737
738       If the channel implementation has device-specific handles, the function
739       should retrieve the appropriate handle  associated  with  the  channel,
740       according  the  direction argument.  The handle should be stored in the
741       location referred to by handlePtr, and TCL_OK should be  returned.   If
742       the  channel is not open for the specified direction, or if the channel
743       implementation does not use device handles, the function should  return
744       TCL_ERROR.
745
746       This  value  can  be  retrieved  with  Tcl_ChannelGetHandleProc,  which
747       returns a pointer to the function.
748
749   FLUSHPROC
750       The flushProc field is currently reserved for future use.  It should be
751       set to NULL.  FlushProc should match the following prototype:
752
753              typedef int Tcl_DriverFlushProc(
754                      ClientData instanceData);
755
756       This  value can be retrieved with Tcl_ChannelFlushProc, which returns a
757       pointer to the function.
758
759   HANDLERPROC
760       The handlerProc field contains the address of a function called by  the
761       generic  layer to notify the channel that an event occurred.  It should
762       be defined for stacked channel drivers that  wish  to  be  notified  of
763       events  that  occur  on  the underlying (stacked) channel.  HandlerProc
764       should match the following prototype:
765
766              typedef int Tcl_DriverHandlerProc(
767                      ClientData instanceData,
768                      int interestMask);
769
770       InstanceData is the same as the value passed to Tcl_CreateChannel  when
771       this  channel was created.  The interestMask is an OR-ed combination of
772       TCL_READABLE or TCL_WRITABLE; it indicates what type of event  occurred
773       on this channel.
774
775       This  value can be retrieved with Tcl_ChannelHandlerProc, which returns
776       a pointer to the function.
777
778
779   THREADACTIONPROC
780       The threadActionProc field contains the address of the function  called
781       by  the  generic  layer  when a channel is created, closed, or going to
782       move to a different thread, i.e. whenever thread-specific driver  state
783       might  have  to  initialized  or  updated.  It can be NULL.  The action
784       TCL_CHANNEL_THREAD_REMOVE is used to notify the driver that  it  should
785       update  or  remove any thread-specific data it might be maintaining for
786       the channel.
787
788       The action TCL_CHANNEL_THREAD_INSERT is used to notify the driver  that
789       it  should  update  or  initialize any thread-specific data it might be
790       maintaining using the calling thread as the associate. See Tcl_CutChan‐
791       nel and Tcl_SpliceChannel for more detail.
792
793              typedef void Tcl_DriverThreadActionProc(
794                      ClientData instanceData,
795                      int action);
796
797       InstanceData  is the same as the value passed to Tcl_CreateChannel when
798       this channel was created.
799
800       These values can be retrieved with  Tcl_ChannelThreadActionProc,  which
801       returns a pointer to the function.
802
803   TRUNCATEPROC
804       The  truncateProc  field contains the address of the function called by
805       the generic layer when a channel is truncated to some length. It can be
806       NULL.
807
808              typedef int Tcl_DriverTruncateProc(
809                      ClientData instanceData,
810                      Tcl_WideInt length);
811
812       InstanceData  is the same as the value passed to Tcl_CreateChannel when
813       this channel was created, and length is the new length of the  underly‐
814       ing  file, which should not be negative. The result should be 0 on suc‐
815       cess or an errno code (suitable for use with Tcl_SetErrno) on failure.
816
817       These values  can  be  retrieved  with  Tcl_ChannelTruncateProc,  which
818       returns a pointer to the function.
819

TCL_BADCHANNELOPTION

821       This  procedure generates a “bad option” error message in an (optional)
822       interpreter.  It is used by channel drivers  when  an  invalid  Set/Get
823       option  is requested. Its purpose is to concatenate the generic options
824       list to the specific ones and factorize the generic options error  mes‐
825       sage string.
826
827       It always returns TCL_ERROR
828
829       An error message is generated in interp's result value to indicate that
830       a command was invoked with a bad option.  The message has the form
831                  bad option "blah": should be one of
832                  <...generic options...>+<...specific options...>
833       so you get for instance:
834                  bad option "-blah": should be one of -blocking,
835                  -buffering, -buffersize, -eofchar, -translation,
836                  -peername, or -sockname
837       when called with optionList equal to “peername sockname”
838
839       “blah” is the optionName argument and “<specific options>” is  a  space
840       separated  list of specific option words.  The function takes good care
841       of inserting minus signs before each option, commas after, and an  “or”
842       before the last option.
843

OLD CHANNEL TYPES

845       The  original  (8.3.1 and below) Tcl_ChannelType structure contains the
846       following fields:
847
848              typedef struct Tcl_ChannelType {
849                  const char *typeName;
850                  Tcl_DriverBlockModeProc *blockModeProc;
851                  Tcl_DriverCloseProc *closeProc;
852                  Tcl_DriverInputProc *inputProc;
853                  Tcl_DriverOutputProc *outputProc;
854                  Tcl_DriverSeekProc *seekProc;
855                  Tcl_DriverSetOptionProc *setOptionProc;
856                  Tcl_DriverGetOptionProc *getOptionProc;
857                  Tcl_DriverWatchProc *watchProc;
858                  Tcl_DriverGetHandleProc *getHandleProc;
859                  Tcl_DriverClose2Proc *close2Proc;
860              } Tcl_ChannelType;
861
862       It is still possible to create channel with the above  structure.   The
863       internal  channel code will determine the version.  It is imperative to
864       use the new Tcl_ChannelType structure if you  are  creating  a  stacked
865       channel driver, due to problems with the earlier stacked channel imple‐
866       mentation (in 8.2.0 to 8.3.1).
867
868       Prior to 8.4.0 (i.e. during the later releases of 8.3 and early part of
869       the  8.4 development cycle) the Tcl_ChannelType structure contained the
870       following fields:
871
872              typedef struct Tcl_ChannelType {
873                  const char *typeName;
874                  Tcl_ChannelTypeVersion version;
875                  Tcl_DriverCloseProc *closeProc;
876                  Tcl_DriverInputProc *inputProc;
877                  Tcl_DriverOutputProc *outputProc;
878                  Tcl_DriverSeekProc *seekProc;
879                  Tcl_DriverSetOptionProc *setOptionProc;
880                  Tcl_DriverGetOptionProc *getOptionProc;
881                  Tcl_DriverWatchProc *watchProc;
882                  Tcl_DriverGetHandleProc *getHandleProc;
883                  Tcl_DriverClose2Proc *close2Proc;
884                  Tcl_DriverBlockModeProc *blockModeProc;
885                  Tcl_DriverFlushProc *flushProc;
886                  Tcl_DriverHandlerProc *handlerProc;
887                  Tcl_DriverTruncateProc *truncateProc;
888              } Tcl_ChannelType;
889
890       When the above structure is registered as a channel type,  the  version
891       field should always be TCL_CHANNEL_VERSION_2.
892

SEE ALSO

894       Tcl_Close(3),          Tcl_OpenFileChannel(3),         Tcl_SetErrno(3),
895       Tcl_QueueEvent(3), Tcl_StackChannel(3), Tcl_GetStdChannel(3)
896

KEYWORDS

898       blocking, channel driver, channel registration, channel type, nonblock‐
899       ing
900
901
902
903Tcl                                   8.4                 Tcl_CreateChannel(3)
Impressum