filehndlr(3Tk)

NAME
     Tk_CreateFileHandler, Tk_CreateFileHandler2, Tk_DeleteFileHandler -
     associate procedure callbacks with files or devices

SYNOPSIS
     #include <tk.h>

     Tk_CreateFileHandler(id, mask, proc, clientData)

     Tk_CreateFileHandler2(id, proc2, clientData)                             |

     Tk_DeleteFileHandler(id)

ARGUMENTS
     int           id           (in)      Integer identifier for an open file
                                          or device (such as returned by open
                                          system call).

     int           mask         (in)      Conditions under which proc should
                                          be called:  OR-ed combination of
                                          TK_READABLE, TK_WRITABLE, and
                                          TK_EXCEPTION.

     Tk_FileProc   *proc        (in)      Procedure to invoke whenever the
                                          file or device indicated by id meets
                                          the conditions specified by mask.

     Tk_FileProc2  *proc2       (in)      Procedure to invoke from event loop
                                          to check whether fd is ready and, if
                                          so, handle it.

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


DESCRIPTION
     Tk_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 id, and the conditions of
     interest are indicated by mask.  For example, if mask is TK_READABLE,
     proc will be called when the file is readable.  The callback to proc is
     made by Tk_DoOneEvent, so Tk_CreateFileHandler is only useful in programs
     that dispatch events through Tk_DoOneEvent or through other Tk procedures
     that call Tk_DoOneEvent, such as Tk_MainLoop.

     Proc should have arguments and result that match the type Tk_FileProc:
          typedef void Tk_FileProc(
               ClientData clientData,
               int mask);
     The clientData parameter to proc is a copy of the clientData argument
     given to Tk_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 Tk_CreateFileHandler.

     Tk_CreateFileHandler2 also creates a file handler, but it provides a     |
     lower-level and more flexible interface.  The callback procedure proc2   |
     must have arguments and result that match the following prototype:       |
          typedef int Tk_FileProc2(                                           |
               ClientData clientData,                                         |
               int mask,                                                      |
               int flags);                                                    |

     Whereas a file handler created by Tk_CreateFileHandler is only invoked   |
     when the file is known to be ``ready'', a file handler created by        |
     Tk_CreateFileHandler2 is invoked on every pass through the the event loop|
     (Tk_DoWhenIdle); it gets to determine whether the file is ``ready'' or   |
     not.  The mask argument contains an OR'ed combination of the bits        |
     TK_READABLE, TK_WRITABLE, and TK_EXCEPTION, which indicate whether the   |
     file is known to be readable, writable, or to have an exceptional        |
     condition present (this is the case if select has been invoked since the |
     previous call to proc2, and if it indicated that the specified conditions|
     were present).  proc2 may use this information along with additional     |
     information of its own, such as knowledge about buffered data, to decide |
     whether the file is really ``ready''.  The flags argument is a copy of   |
     the flags passed to Tk_DoOneEvent, which may be used by proc2 to ignore  |
     the file if the appropriate bit, such as TK_FILE_EVENTS, is not present. |

     proc2 must return an integer value that is either TK_FILE_HANDLED or an  |
     OR-ed combination of TK_READABLE, TK_WRITABLE, and TK_EXCEPTION.  If the |
     return value is TK_FILE_HANDLED it means that the file was ``ready'' and |
     that proc2 handled the ready condition; Tk_DoOneEvent will return        |
     immediately.  If the return value is not TK_FILE_HANDLED, then it        |
     indicates the set of conditions that should be checked for the file if   |
     the current invocation of Tk_DoWhenIdle invokes select.  Typically the   |
     return value reflects all of the conditions that proc2 cares about.  A   |
     zero return value means that the file should be ignored if Tk_DoWhenIdle |
     calls select (this could happen, for example, if the flags argument      |
     specified that this file's events should be ignored).  The value returned|
     by proc2 only affects a select call from the current invocation of       |
     Tk_DoOneEvent;  the next invocation of Tk_DoOneEvent will call proc2     |
     afresh to get new information.

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

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

     The purpose of file handlers is to enable an application to respond to X
     events and other 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 be put to sleep 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.  In BSD-based UNIX systems, non-blocking I/O can be
     specified for a file using the fcntl kernel call with the FNDELAY flag.


KEYWORDS
     callback, file, handler