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

FreeBSD Manual Pages


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


       Tcl_CreateFileHandler,	Tcl_DeleteFileHandler  -  associate  procedure
       callbacks with files or devices (Unix only)

       #include	<tcl.h>

       Tcl_CreateFileHandler(fd, mask, proc, clientData)


       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,
					     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

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

       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-

       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

       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

       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.

       callback, file, handler

Tcl				      8.0	      Tcl_CreateFileHandler(3)


Want to link to this manual page? Use this URL:

home | help