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   ad‐
132                                                        dresses  of procedures
133                                                        that can be called  to
134                                                        perform  I/O and other
135                                                        functions on the chan‐
136                                                        nel.
137
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 as‐
146                                                        signed  to  one of the
147                                                        standard      channels
148                                                        (stdin,    stdout   or
149                                                        stderr), the  assigned
150                                                        channel  name  will be
151                                                        the name of the  stan‐
152                                                        dard channel.
153
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  in‐
160                                                        voked.
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 in‐
191                                                        dicates  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 up‐
213       per layer to enable C and Tcl programs to perform input and output  us‐
214       ing  the  same  APIs  for a variety of files, devices, sockets etc. The
215       generic C APIs are described in the manual entry for  Tcl_OpenFileChan‐
216       nel.
217
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  in‐
232       stances of that type of channel. For example, the Tcl open command cre‐
233       ates channels that use the file and command channel  drivers,  and  the
234       Tcl  socket  command  creates channels that use TCP sockets for network
235       communication.
236
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, be‐
254       low.
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  (or
308       other  pending  tasks  like  a  write  flush should be performed).  See
309       WATCHPROC below for more details.
310
311       Tcl_BadChannelOption is called from driver  specific  setOptionProc  or
312       getOptionProc to generate a complete error message.
313
314       Tcl_ChannelBuffered  returns  the  number  of  bytes of input currently
315       buffered in the internal buffer (push back area) of the channel itself.
316       It  does not report about the data in the overall buffers for the stack
317       of channels the supplied channel is part of.
318
319       Tcl_IsChannelShared checks the refcount of the  specified  channel  and
320       returns whether the channel was shared among multiple interpreters (re‐
321       sult == 1) or not (result == 0).
322
323       Tcl_IsChannelRegistered checks whether the specified channel is  regis‐
324       tered in the given interpreter (result == 1) or not (result == 0).
325
326       Tcl_IsChannelExisting  checks whether a channel with the specified name
327       is registered in the (thread)-global list of all channels (result == 1)
328       or not (result == 0).
329
330       Tcl_CutChannel  removes  the  specified channel from the (thread)global
331       list of all channels (of the current thread).  Application to a channel
332       still registered in some interpreter is not allowed.  Also notifies the
333       driver if the  Tcl_ChannelType  version  is  TCL_CHANNEL_VERSION_4  (or
334       higher), and Tcl_DriverThreadActionProc is defined for it.
335
336       Tcl_SpliceChannel adds the specified channel to the (thread)global list
337       of all channels (of the current thread).  Application to a channel reg‐
338       istered  in  some interpreter is not allowed.  Also notifies the driver
339       if the Tcl_ChannelType version is  TCL_CHANNEL_VERSION_4  (or  higher),
340       and Tcl_DriverThreadActionProc is defined for it.
341
342       Tcl_ClearChannelHandlers removes all channel handlers and event scripts
343       associated with the specified channel, thus  shutting  down  all  event
344       processing for this channel.
345

TCL_CHANNELTYPE

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

TCL_BADCHANNELOPTION

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

OLD CHANNEL TYPES

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

SEE ALSO

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

KEYWORDS

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