NAME

       Tcl_CreateFileHandler,  Tcl_DeleteFileHandler  - associate
       procedure callbacks with files or devices (Unix only)


SYNOPSIS

       #include <tcl.h>

       Tcl_CreateFileHandler(fd, mask, proc, clientData)          |

       Tcl_DeleteFileHandler(fd)                                  |


ARGUMENTS

       int            fd           (in)                                  ||
                                             Unix file descriptor |
                                             for an open file  or |
                                             device.

       int            mask         (in)      Conditions     under
                                             which proc should be
                                             called: OR-ed combi­
                                             nation of  TCL_READ­
                                             ABLE,  TCL_WRITABLE,
                                             and   TCL_EXCEPTION.
                                             May  be  set to 0 to
                                             temporarily  disable
                                             a handler.

       Tcl_FileProc   *proc        (in)      Procedure  to invoke
                                             whenever the file or
                                             device  indicated by
                                             file meets the  con­
                                             ditions specified by
                                             mask.

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



DESCRIPTION

       Tcl_CreateFileHandler arranges for proc to be  invoked  in |
       the  future  whenever I/O becomes possible on a file or an |
       exceptional condition exists for the file.   The  file  is |
       indicated  by fd, and the conditions of interest are indi­
       cated by mask.  For example, if mask is TCL_READABLE, proc
       will be called when the file is readable.  The callback to
       proc is made by Tcl_DoOneEvent,  so  Tcl_CreateFileHandler
       is  only  useful  in programs that dispatch events through
       Tcl_DoOneEvent or through Tcl commands such as vwait.

              typedef void Tcl_FileProc(
                ClientData clientData,
                int mask);
       The  clientData parameter to proc is a copy of the client­
       Data argument  given  to  Tcl_CreateFileHandler  when  the
       callback  was  created.  Typically, clientData points to a
       data structure containing application-specific information
       about  the file.  Mask is an integer mask indicating which
       of the requested conditions actually exists for the  file;
       it  will contain a subset of the bits in the mask argument
       to Tcl_CreateFileHandler.


       There may exist only one handler for a  given  file  at  a
       given  time.   If  Tcl_CreateFileHandler  is called when a
       handler already exists  for  fd,  then  the  new  callback
       replaces the information that was previously recorded.

       Tcl_DeleteFileHandler  may  be  called  to delete the file
       handler for fd;  if no handler exists for the  file  given
       by fd then the procedure has no effect.

       The  purpose  of file handlers is to enable an application
       to respond to events while waiting  for  files  to  become
       ready  for  I/O.  For this to work correctly, the applica­
       tion may need to use non-blocking I/O  operations  on  the
       files  for  which  handlers  are  declared.  Otherwise the
       application may block if it reads or writes too much data;
       while  waiting  for  the  I/O  to complete the application
       won't be able to service other  events.  Use  Tcl_SetChan­
       nelOption  with -blocking to set the channel into blocking
       or nonblocking mode as required.

       Note that these interfaces are only supported by the  Unix |
       implementation of the Tcl notifier.



KEYWORDS

       callback, file, handler