Tk_CreateFileHandler(3Tk)Tk_CreateFileHandler(3Tk)NAME
Tk_CreateFileHandler, Tk_CreateFileHandler2, Tk_DeleteFileHandler -
associate procedure callbacks with files or devices
SYNOPSIS
#include <tk.h>
Tk_CreateFileHandler(id, mask, proc, clientData)
Tk_CreateFileHandler2(id, proc2, 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.
Tk_FileProc2 *proc2 (in) Procedure to invoke from event loop
to check whether fd is ready and, if
so, handle it.
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,
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 Tk_CreateFileHandler when the callback was created. Typically,
clientData points to a data structure containing application-specific
Page 1
Tk_CreateFileHandler(3Tk)Tk_CreateFileHandler(3Tk)
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 Tk_CreateFileHandler.
Tk_CreateFileHandler2 also creates a file handler, but it provides a |
lower-level and more flexible interface. The callback procedure proc2 |
must have arguments and result that match the following prototype: |
typedef int Tk_FileProc2( |
ClientData clientData, |
int mask, |
int flags); |
Whereas a file handler created by Tk_CreateFileHandler is only invoked |
when the file is known to be ``ready'', a file handler created by |
Tk_CreateFileHandler2 is invoked on every pass through the the event loop|
(Tk_DoWhenIdle); it gets to determine whether the file is ``ready'' or |
not. The mask argument contains an OR'ed combination of the bits |
TK_READABLE, TK_WRITABLE, and TK_EXCEPTION, which indicate whether the |
file is known to be readable, writable, or to have an exceptional |
condition present (this is the case if select has been invoked since the |
previous call to proc2, and if it indicated that the specified conditions|
were present). proc2 may use this information along with additional |
information of its own, such as knowledge about buffered data, to decide |
whether the file is really ``ready''. The flags argument is a copy of |
the flags passed to Tk_DoOneEvent, which may be used by proc2 to ignore |
the file if the appropriate bit, such as TK_FILE_EVENTS, is not present. |
proc2 must return an integer value that is either TK_FILE_HANDLED or an |
OR-ed combination of TK_READABLE, TK_WRITABLE, and TK_EXCEPTION. If the |
return value is TK_FILE_HANDLED it means that the file was ``ready'' and |
that proc2 handled the ready condition; Tk_DoOneEvent will return |
immediately. If the return value is not TK_FILE_HANDLED, then it |
indicates the set of conditions that should be checked for the file if |
the current invocation of Tk_DoWhenIdle invokes select. Typically the |
return value reflects all of the conditions that proc2 cares about. A |
zero return value means that the file should be ignored if Tk_DoWhenIdle |
calls select (this could happen, for example, if the flags argument |
specified that this file's events should be ignored). The value returned|
by proc2 only affects a select call from the current invocation of |
Tk_DoOneEvent; the next invocation of Tk_DoOneEvent will call proc2 |
afresh to get new information.
There may exist only one handler for a given file at a given time. If
Tk_CreateFileHandler or Tk_CreateFileHandler2 is called when a handler
already exists for id, then the new callback replaces 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.
Page 2
Tk_CreateFileHandler(3Tk)Tk_CreateFileHandler(3Tk)
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 may need to use non-blocking
I/O operations on the files for which handlers are declared. Otherwise
the application may be put to sleep 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. 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
Page 3
