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 combina-
                                             tion       of       TCL_READABLE,
                                             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 conditions 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 indicated by mask.  For example, if mask  is  TCL_READ-
       ABLE,  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.

       Proc should have arguments and result that match the type Tcl_FileProc:
              typedef void Tcl_FileProc(
                ClientData clientData,
                int mask);
       The  clientData  parameter to proc is a copy of the clientData argument
       given to Tcl_CreateFileHandler when the callback  was  created.   Typi-
       cally,  clientData  points  to a data structure containing application-
       specific information about the file.  Mask is an integer mask  indicat-
       ing which of the requested conditions actually exists for the file;  it
       will contain a subset of the bits in the mask argument  to  Tcl_Create-
       work correctly, the application may need to use non-blocking I/O opera-
       tions  on  the  files  for  which handlers are declared.  Otherwise the
       application may block if it reads or writes too much data; while  wait-
       ing  for  the  I/O to complete the application won't be able to service
       other events. Use Tcl_SetChannelOption with -blocking to set the  chan-
       nel into blocking or nonblocking mode as required.

       Note  that  these interfaces are only supported by the Unix implementa- |
       tion of the Tcl notifier.

KEYWORDS

       callback, file, handler



Tcl                                   8.0             Tcl_CreateFileHandler(3)