HPUX FileHndlr[3]

 Tk_CreateFileHandler(3)             Tk              Tk_CreateFileHandler(3)

 Tk Library Procedures                                 Tk Library Procedures





 ___________________________________________________________________________

 NAME
      Tk_CreateFileHandler,  Tk_DeleteFileHandler  -   associate   procedure
      callback with a file or device

 SYNOPSIS
      #include <tk.h>

      Tk_CreateFileHandler(id, mask, proc, 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.

      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, then 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



                                    - 1 -        Formatted:  August 11, 1996






 Tk_CreateFileHandler(3)             Tk              Tk_CreateFileHandler(3)

 Tk Library Procedures                                 Tk Library Procedures





      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
      Tk_CreateEventHandler  is called when a handler already exists for id,
      then  the  mask,  proc,  and  clientData   for   the   new   call   to
      Tk_CreateEventHandler  replace  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  must  use  non-
      blocking  I/O operations on the files for which handlers are declared.
      Otherwise the application may be put to  sleep  if  it  specifies  too
      large an input or output buffer; 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






















                                    - 2 -        Formatted:  August 11, 1996