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