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
       callbacks 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  combina-
					     tion	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
       whenever	I/O becomes possible on	a file or an exceptional condition ex-
       ists 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 pro-
       grams that dispatch events through Tcl_DoOneEvent or through  Tcl  com-
       mands 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.	 Typi-
       cally,  clientData  points  to a	data structure containing application-
       specific	information about the file.  Mask is an	integer	mask  indicat-
       ing which of the	requested conditions actually exists for the file;  it
       will  contain  a	subset of the bits in the mask argument	to Tcl_Create-
       FileHandler.

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

       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	opera-
       tions on	the files for which handlers are declared.  Otherwise the  ap-
       plication  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 chan-
       nel into	blocking or nonblocking	mode as	required.

       Note that these interfaces are only supported by	the  Unix  implementa-
       tion 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+14.3.quarterly>

home | help