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

NAME

8       Tcl_CreateChannelHandler,  Tcl_DeleteChannelHandler  - call a procedure
9       when a channel becomes readable or writable
10

SYNOPSIS

12       #include <tcl.h>
13
14       void
15       Tcl_CreateChannelHandler(channel, mask, proc, clientData)
16
17       void
18       Tcl_DeleteChannelHandler(channel, proc, clientData)
19
20

ARGUMENTS

22       Tcl_Channel       channel      (in)      Tcl channel such  as  returned
23                                                by Tcl_CreateChannel.
24
25       int               mask         (in)      Conditions  under  which  proc
26                                                should be called: OR-ed combi‐
27                                                nation     of    TCL_READABLE,
28                                                TCL_WRITABLE  and   TCL_EXCEP‐
29                                                TION.  Specify a zero value to
30                                                temporarily disable an  exist‐
31                                                ing handler.
32
33       Tcl_FileProc      *proc        (in)      Procedure  to  invoke whenever
34                                                the channel indicated by chan‐
35                                                nel meets the conditions spec‐
36                                                ified by mask.
37
38       ClientData        clientData   (in)      Arbitrary  one-word  value  to
39                                                pass to proc.
40_________________________________________________________________
41
42

DESCRIPTION

44       Tcl_CreateChannelHandler  arranges  for proc to be called in the future
45       whenever input or output becomes possible on the channel identified  by
46       channel,  or  whenever an exceptional condition exists for channel. The
47       conditions of interest under which proc will be invoked  are  specified
48       by the mask argument.  See the manual entry for fileevent for a precise
49       description of what it means for a channel to be readable or  writable.
50       Proc must conform to the following prototype:
51              typedef void Tcl_ChannelProc(
52                ClientData clientData,
53                int mask);
54
55       The  clientData argument is the same as the value passed to Tcl_Create‐
56       ChannelHandler when the  handler  was  created.  Typically,  clientData
57       points  to a data structure containing application-specific information
58       about the channel. Mask is an integer  mask  indicating  which  of  the
59       requested conditions actually exists for the channel; it will contain a
60       subset of the bits from the mask argument  to  Tcl_CreateChannelHandler
61       when the handler was created.
62
63       Each  channel handler is identified by a unique combination of channel,
64       proc and clientData.  There may be many handlers for a given channel as
65       long  as  they  don't  have the same channel, proc, and clientData.  If
66       Tcl_CreateChannelHandler is invoked when there is already a handler for
67       channel,  proc,  and  clientData,  then  no  new  handler  is  created;
68       instead, the mask is changed for the existing handler.
69
70       Tcl_DeleteChannelHandler deletes a channel handler identified by  chan‐
71       nel,  proc  and  clientData; if no such handler exists, the call has no
72       effect.
73
74       Channel handlers are invoked via the Tcl event mechanism, so  they  are
75       only  useful in applications that are event-driven.  Note also that the
76       conditions specified in the mask argument to proc may no  longer  exist
77       when  proc  is  invoked:   for  example,  if there are two handlers for
78       TCL_READABLE on the same channel, the first handler could  consume  all
79       of  the  available input so that the channel is no longer readable when
80       the second handler is invoked.  For this reason it may be useful to use
81       nonblocking I/O on channels for which there are event handlers.
82
83

SEE ALSO

85       Notifier(3), Tcl_CreateChannel(3), Tcl_OpenFileChannel(3), vwait(n).
86
87

KEYWORDS

89       blocking, callback, channel, events, handler, nonblocking.
90
91
92
93Tcl                                   7.5          Tcl_CreateChannelHandler(3)
Impressum