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