Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
Tcl_CreateFileHandler(3)     Tcl Library Procedures	Tcl_CreateFileHandler(3)

________________________________________________________________________________

NAME
     Tcl_CreateFileHandler,  Tcl_DeleteFileHandler  -  associate procedure call-
     backs with files or devices (Unix only)

SYNOPSIS
     #include <tcl.h>

     Tcl_CreateFileHandler(fd, mask, proc, clientData)

     Tcl_DeleteFileHandler(fd)

ARGUMENTS
     int fd (in)			   Unix file descriptor for an open file
					   or device.

     int mask (in)			   Conditions under which proc should be
					   called:    OR-ed    combination    of
					   TCL_READABLE,    TCL_WRITABLE,    and
					   TCL_EXCEPTION.  May be set  to  0  to
					   temporarily disable a handler.

     Tcl_FileProc *proc (in)		   Procedure to invoke whenever the file
					   or device indicated by file meets the
					   conditions specified by mask.

     ClientData clientData (in) 	   Arbitrary  one-word	value to pass to
					   proc.
________________________________________________________________________________

DESCRIPTION
     Tcl_CreateFileHandler arranges for proc to be invoked in the  future  when-
     ever  I/O becomes possible on a file or an exceptional condition exists for
     the file.	The file is indicated by fd, and the conditions of interest  are
     indicated	by  mask.   For  example,  if mask is TCL_READABLE, proc will be
     called when the file  is  readable.   The	callback  to  proc  is	made  by
     Tcl_DoOneEvent,  so  Tcl_CreateFileHandler  is only useful in programs that
     dispatch events through Tcl_DoOneEvent or	through  Tcl  commands	such  as
     vwait.

     Proc should have arguments and result that match the type Tcl_FileProc:

	    typedef void Tcl_FileProc(
		    ClientData clientData,
		    int mask);

     The clientData parameter to proc is a copy of the clientData argument given
     to Tcl_CreateFileHandler when the callback was created.  Typically, client-
     Data 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 Tcl_CreateFileHandler.

     There  may  exist	only  one  handler for a given file at a given time.  If
     Tcl_CreateFileHandler is called when a handler already exists for fd,  then
     the new callback replaces the information that was previously recorded.

     Tcl_DeleteFileHandler  may be called to delete the file handler for fd;  if
     no handler exists for the file given by fd then the procedure  has  no  ef-
     fect.

     The  purpose  of  file  handlers  is to enable an application to respond to
     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
     block  if	it  reads  or writes too much data; while waiting for the I/O to
     complete the application will not be able	to  service  other  events.  Use
     Tcl_SetChannelOption  with  -blocking  to	set the channel into blocking or
     nonblocking mode as required.

     Note that these interfaces are only supported by the Unix implementation of
     the Tcl notifier.

SEE ALSO
     fileevent(n), Tcl_CreateTimerHandler(3), Tcl_DoWhenIdle(3)

KEYWORDS
     callback, file, handler

Tcl				       8.0		Tcl_CreateFileHandler(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=Tcl_CreateFileHandler.tcl86&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help