About Us Documentation

Contact Site Map




Prepared by Ready-to-Run Software, Inc. 

Tcl_CreateFileHandler(Tcl Library Procedures 8.0



Tcl_CreateFileHandler, Tcl_DeleteFileHandler - associate procedure callbacks with files or devices (Unix only)


#include <tcl.h> Tcl_CreateFileHandler(fd, mask, proc, clientData) | Tcl_DeleteFileHandler(fd) |


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 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. _________________________________________________________________


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 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. Tcl 1 Prepared by Ready-to-Run Software, Inc.

Tcl_CreateFileHandler(Tcl Library Procedures 8.0

     Proc should have arguments and result that  match  the  type
          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

     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.


callback, file, handler Tcl 2 Prepared by Ready-to-Run Software, Inc.


Email addresses listed on this site may  NOT be used for unsolicited commercial email.

Ready-to-Run Software, Inc Privacy Statement

Portions (c)Copyright, 1996-2005 by Ready-to-Run Software, Inc
(All rights reserved.)
212 Cedar Cove
Lansing, NY 14882
Phone: 607 533 UNIX (8649)
Fax: 607 533 4002

To return to the Ready-to-Run Software WinPak Table of contents please presshere