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 combination  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_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.

       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.  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 application 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_SetChannelOption 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