Tk_CreateFileHandler(id, mask, proc, clientData)
Tk_CreateFileHandler2(id, proc2, clientData)
Tk_DeleteFileHandler(id)
int id
(in) int mask
(in) Tk_FileProc *proc
(in) Tk_FileProc2 *proc2
(in) ClientData clientData
(in) 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.