TclCreateChannelHandler(3) Tcl Library Procedures TclCreateChannelHandler(3)

NAME
       TclCreateChannelHandler,  TclDeleteChannelHandler  - call a procedure
       when a channel becomes readable or writable

SYNOPSIS
       ##iinncclluuddee <>

       void
       TTccllCCrreeaatteeCChhaannnneellHHaannddlleerr(channel, mask, proc, clientData)

       void
       TTccllDDeelleetteeCChhaannnneellHHaannddlleerr(channel, proc, clientData)


AARRGGUUMMEENNTTSS
       TclChannel       channel      (in)      Tcl channel such  as  returned
                                                by TTccllCCrreeaatteeCChhaannnneell.

       int               mask         (in)      Conditions  under  which  proc
                                                should be called: OR-ed combi-
                                                nation     of    TTCCLLRREEAADDAABBLLEE,
                                                TTCCLLWWRRIITTAABBLLEE  and   TTCCLLEEXXCCEEPP-
                                                TTIIOONN.  Specify a zero value to
                                                temporarily disable an  exist-
                                                ing handler.

       TclFileProc      *proc        (in)      Procedure  to  invoke whenever
                                                the channel indicated by chan-
                                                nel meets the conditions spec-
                                                ified by mask.

       ClientData        clientData   (in)      Arbitrary  one-word  value  to
                                                pass to proc.



DESCRIPTION
       TTccllCCrreeaatteeCChhaannnneellHHaannddlleerr  arranges  for proc to be called in the future
       whenever input or output becomes possible on the channel identified  by
       channel,  or  whenever an exceptional condition exists for channel. The
       conditions of interest under which proc will be invoked  are  specified
       by the mask argument.  See the manual entry for ffiilleeeevveenntt for a precise
       description of what it means for a channel to be readable or  writable.
       Proc must conform to the following prototype:
              typedef void TclChannelProc(
                ClientData clientData,
                int mask);

       The  clientData argument is the same as the value passed to TTccllCCrreeaattee-
       CChhaannnneellHHaannddlleerr when the  handler  was  created.  Typically,  clientData
       points  to a data structure containing application-specific information
       about the channel. Mask is an integer  mask  indicating  which  of  the
       requested conditions actually exists for the channel; it will contain a
       subset of the bits from the mask argument  to  TTccllCCrreeaatteeCChhaannnneellHHaannddlleerr
       when the handler was created.

       Each  channel handler is identified by a unique combination of channel,
       proc and clientData.  There may be many handlers for a given channel as
       long  as  they  don't  have the same channel, proc, and clientData.  If
       TTccllCCrreeaatteeCChhaannnneellHHaannddlleerr is invoked when there is already a handler for
       channel,  proc,  and  clientData,  then  no  new  handler  is  created;
       instead, the mask is changed for the existing handler.

       TTccllDDeelleetteeCChhaannnneellHHaannddlleerr deletes a channel handler identified by  chan-
       nel,  proc  and  clientData; if no such handler exists, the call has no
       effect.

       Channel handlers are invoked via the Tcl event mechanism, so  they  are
       only  useful in applications that are event-driven.  Note also that the
       conditions specified in the mask argument to proc may no  longer  exist
       when  proc  is  invoked:   for  example,  if there are two handlers for
       TTCCLLRREEAADDAABBLLEE on the same channel, the first handler could  consume  all
       of  the  available input so that the channel is no longer readable when
       the second handler is invoked.  For this reason it may be useful to use
       nonblocking I/O on channels for which there are event handlers.


SEE ALSO
       Notifier(3), TclCreateChannel(3), TclOpenFileChannel(3), vwait(n).


KKEEYYWWOORRDDSS
       blocking, callback, channel, events, handler, nonblocking.



Tcl                                   7.5          TclCreateChannelHandler(3)