'\"
'\" Copyright (c) 1990 The Regents of the University of California.
'\" All rights reserved.
'\"
'\" Permission is hereby granted, without written agreement and without
'\" license or royalty fees, to use, copy, modify, and distribute this
'\" documentation for any purpose, provided that the above copyright
'\" notice and the following two paragraphs appear in all copies.
'\"
'\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
'\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
'\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
'\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
'\"
'\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
'\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
'\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
'\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
'\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
'\" 
'\" $Header: /user6/ouster/wish/man/RCS/FileHndlr.3,v 1.7 93/04/01 09:41:21 ouster Exp $ SPRITE (Berkeley)
'\" 
.so man.macros
.HS Tk_CreateFileHandler tkc
.BS
.SH NAME
Tk_CreateFileHandler, Tk_DeleteFileHandler \- associate procedure callback with a file or device
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_CreateFileHandler\fR(\fIid, mask, proc, clientData\fR)
.sp
\fBTk_DeleteFileHandler\fR(\fIid\fR)
.SH ARGUMENTS
.AS Tk_FileProc clientData
.AP int id in
Integer identifier for an open file or device (such as returned by
\fBopen\fR system call).
.AP int mask in
Conditions under which \fIproc\fR should be called:
OR-ed combination of \fBTK_READABLE\fR, \fBTK_WRITABLE\fR,
and \fBTK_EXCEPTION\fR.
.AP Tk_FileProc *proc in
Procedure to invoke whenever the file or device indicated
by \fIid\fR meets the conditions specified by \fImask\fR.
.AP ClientData clientData in
Arbitrary one-word value to pass to \fIproc\fR.
.BE

.SH DESCRIPTION
.PP
\fBTk_CreateFileHandler\fR arranges for \fIproc\fR 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 \fIid\fR, and the conditions of interest
are indicated by \fImask\fR.  For example, if \fImask\fR
is \fBTK_READABLE\fR, then \fIproc\fR will be called when
the file is readable.
The callback to \fIproc\fR is made by \fBTk_DoOneEvent\fR, so
\fBTk_CreateFileHandler\fR is only useful
in programs that dispatch events
through \fBTk_DoOneEvent\fR or through other Tk procedures that
call \fBTk_DoOneEvent\fR, such as \fBTk_MainLoop\fR.
.PP
\fIProc\fP should have arguments and result that match the
type \fBTk_FileProc\fR:
.nf
.RS
typedef void Tk_FileProc(
.RS
ClientData \fIclientData\fR,
int \fImask\fR);
.RE
.RE
.fi
The \fIclientData\fP parameter to \fIproc\fR is a copy
of the \fIclientData\fP
argument given to \fBTcl_CreateFileHandler\fR when the callback
was created.  Typically, \fIclientData\fR points to a data
structure containing application-specific information about
the file.  \fIMask\fR 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 \fImask\fR argument
to \fBTcl_CreateFileHandler\fR.
.PP
There may exist only one handler for a given file at a given
time.  If \fBTk_CreateEventHandler\fR is called when a handler
already exists for \fIid\fR, then the \fImask\fR, \fIproc\fR,
and \fIclientData\fR for the new call to
\fBTk_CreateEventHandler\fR replace the information that was
previously recorded.
.PP
\fBTk_DeleteFileHandler\fR may be called to delete the
file handler for \fIid\fR;  if no handler exists for the
file given by \fIid\fR then the procedure has no effect.
.PP
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 must use non-blocking I/O operations on the
files for which handlers are declared.  Otherwise the application
may be put to sleep if it specifies too large an input or
output buffer; 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 \fBfcntl\fR kernel call with the \fBFNDELAY\fR flag.

.SH KEYWORDS
callback, file, handler