#  Copyright (c) 1990-1994 The Regents of the University of California.
#  Copyright (c) 1994 Sun Microsystems, Inc.
#  See the file "license.terms" for information on usage and redistribution
#  of this file, and for a DISCLAIMER OF ALL WARRANTIES.
#
#  @(#) FileHndlr.3 1.12 95/05/06 15:29:24
#

=head1 NAME

Tk_CreateFileHandler, Tk_CreateFileHandler2, Tk_DeleteFileHandler - associate procedure callbacks with files or devices

=for category C Programming

=head1 SYNOPSIS

B<#include E<lt>tk.hE<gt>>

B<Tk_CreateFileHandler>(I<id, mask, proc, clientData>)

B<Tk_CreateFileHandler2>(I<id, proc2, clientData>)

B<Tk_DeleteFileHandler>(I<id>)

=head1 ARGUMENTS

=over 4

=item int id (in)

Integer identifier for an open file or device (such as returned by
B<open> system call).

=item int mask (in)

Conditions under which I<proc> should be called:
OR-ed combination of B<TK_READABLE>, B<TK_WRITABLE>,
and B<TK_EXCEPTION>.

=item Tk_FileProc *proc (in)

Procedure to invoke whenever the file or device indicated
by I<id> meets the conditions specified by I<mask>.

=item Tk_FileProc2 *proc2 (in)

Procedure to invoke from event loop to check whether I<fd>
is ready and, if so, handle it.

=item ClientData clientData (in)

Arbitrary one-word value to pass to I<proc>.

=back

=head1 DESCRIPTION

B<Tk_CreateFileHandler> arranges for I<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 I<id>, and the conditions of interest
are indicated by I<mask>.  For example, if I<mask>
is B<TK_READABLE>, I<proc> will be called when
the file is readable.
The callback to I<proc> is made by B<Tk_DoOneEvent>, so
B<Tk_CreateFileHandler> is only useful
in programs that dispatch events
through B<Tk_DoOneEvent> or through other Tk procedures that
call B<Tk_DoOneEvent>, such as B<Tk_MainLoop>.

I<Proc> should have arguments and result that match the
type B<Tk_FileProc>:

=over 4

typedef void Tk_FileProc(

=over 4

ClientData I<clientData>,
int I<mask>);

=back

=back

The I<clientData> parameter to I<proc> is a copy
of the I<clientData>
argument given to B<Tk_CreateFileHandler> when the callback
was created.  Typically, I<clientData> points to a data
structure containing application-specific information about
the file.  I<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 I<mask> argument
to B<Tk_CreateFileHandler>.

B<Tk_CreateFileHandler2> also creates a file handler,
but it provides a lower-level and more flexible interface.
The callback procedure I<proc2> must have arguments and result
that match the following prototype:

=over 4

typedef int Tk_FileProc2(

=over 4

ClientData I<clientData>,
int I<mask>,
int I<flags>);

=back

=back

Whereas a file handler created by B<Tk_CreateFileHandler> is
only invoked when the file is known to be ``ready'', a file handler
created by B<Tk_CreateFileHandler2> is invoked on every pass
through the the event loop (B<Tk_DoWhenIdle>); it gets to
determine whether the file is ``ready'' or not.
The I<mask> argument contains an OR'ed combination of the
bits B<TK_READABLE>, B<TK_WRITABLE>, and B<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
B<select> has been invoked since the previous call to I<proc2>,
and if it indicated that the specified conditions were present).
I<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 I<flags> argument is a copy of the flags passed to
B<Tk_DoOneEvent>, which may be used by I<proc2> to ignore
the file if the appropriate bit, such as B<TK_FILE_EVENTS>,
is not present.

I<proc2> must return an integer value that is either B<TK_FILE_HANDLED>
or an OR-ed combination of B<TK_READABLE>, B<TK_WRITABLE>, and
B<TK_EXCEPTION>.
If the return value is B<TK_FILE_HANDLED> it means that the file
was ``ready'' and that I<proc2> handled the ready condition;
B<Tk_DoOneEvent> will return immediately.
If the return value is not B<TK_FILE_HANDLED>, then it indicates
the set of conditions that should be checked for the file if the
current invocation of B<Tk_DoWhenIdle> invokes B<select>.
Typically the return value reflects all of the conditions that
I<proc2> cares about.
A zero return value means that the file should be ignored if
B<Tk_DoWhenIdle> calls B<select> (this could happen, for
example, if the I<flags>
argument specified that this file's events should be ignored).
The value returned by I<proc2> only affects a B<select> call
from the current invocation of B<Tk_DoOneEvent>;  the next
invocation of B<Tk_DoOneEvent> will call I<proc2> afresh
to get new information.

There may exist only one handler for a given file at a given
time.  If B<Tk_CreateFileHandler> or B<Tk_CreateFileHandler2>
is called when a handler already exists for I<id>, then the
new callback replaces the information that was
previously recorded.

B<Tk_DeleteFileHandler> may be called to delete the
file handler for I<id>;  if no handler exists for the
file given by I<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 B<fcntl> kernel call with the B<FNDELAY> flag.

=head1 KEYWORDS

callback, file, handler