tcl7.6 C API - CrtFileHdlr






NAME

     Tcl_CreateFileHandler,  Tcl_DeleteFileHandler  -   associate
     procedure callbacks with files or devices


SYNOPSIS

     #include <tcl.h>

     Tcl_CreateFileHandler(file, mask, proc, clientData)

     Tcl_DeleteFileHandler(file)


ARGUMENTS

     Tcl_File       file         (in)      Generic  file   handle
                                           for  an  open  file or
                                           device    (such     as
                                           returned            by
                                           Tcl_GetFile call).

     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   tem-
                                           porarily   disable   a
                                           handler.

     Tcl_FileProc   *proc        (in)      Procedure  to   invoke
                                           whenever  the  file or
                                           device  indicated   by
                                           file  meets the condi-
                                           tions   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 excep-
     tional condition exists for the file.  The file is indicated
     by  file,  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  struc-
     ture  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 file, then the new callback replaces  the
     information that was previously recorded.

     Tcl_DeleteFileHandler may  be  called  to  delete  the  file
     handler  for  file;  if no handler exists for the file given
     by file 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.



KEYWORDS

     callback, file, handler