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