man page(1) manual page
Table of Contents

_________________________________________________________________

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


Table of Contents