Tcl_CreateFileHandler(3) Tcl Library Procedures Tcl_CreateFileHandler(3)
Tcl_CreateFileHandler, Tcl_DeleteFileHandler - associate procedure callbacks with files or
devices (Unix only)
Tcl_CreateFileHandler(fd, mask, proc, clientData)
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 temporarily dis-
able a handler.
Tcl_FileProc *proc (in) Procedure to invoke whenever the file or device
indicated by file meets the conditions specified by
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 exceptional 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.
Proc should have arguments and result that match the type Tcl_FileProc:
typedef void Tcl_FileProc(
The clientData parameter to proc is a copy of the clientData argument given to Tcl_Create-
FileHandler 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 con-
tain 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_CreateFileHan-
dler 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 wait-
ing 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 will not be able to service other events. Use
Tcl_SetChannelOption with -blocking to set the channel into blocking or nonblocking mode
Note that these interfaces are only supported by the Unix implementation of the Tcl noti-
callback, file, handler
Tcl 8.0 Tcl_CreateFileHandler(3)