Unix/Linux Go Back    


OpenDarwin 7.2.1 - man page for fileevent (opendarwin section n)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


fileevent(n)			      Tcl Built-In Commands			     fileevent(n)

_________________________________________________________________________________________________

NAME
       fileevent - Execute a script when a channel becomes readable or writable

SYNOPSIS
       fileevent channelId readable ?script?

       fileevent channelId writable ?script?
_________________________________________________________________

DESCRIPTION
       This  command  is  used	to create file event handlers.	A file event handler is a binding
       between a channel and a script, such that the script is	evaluated  whenever  the  channel
       becomes readable or writable.  File event handlers are most commonly used to allow data to
       be received from another process on an event-driven basis, so that the receiver	can  con-
       tinue  to  interact with the user while waiting for the data to arrive.	If an application
       invokes gets or read on a blocking channel when there is  no  input  data  available,  the
       process	will  block;  until  the input data arrives, it will not be able to service other
       events, so it will appear to the user to ``freeze up''.	With fileevent, the  process  can
       tell when data is present and only invoke gets or read when they won't block.

       The channelId argument to fileevent refers to an open channel such as a Tcl standard chan- |
       nel (stdin, stdout, or stderr), the return value from an invocation of open or socket,  or |
       the result of a channel creation command provided by a Tcl extension.

       If  the	script argument is specified, then fileevent creates a new event handler:  script
       will be evaluated whenever the channel becomes readable or writable (depending on the sec-
       ond argument to fileevent).  In this case fileevent returns an empty string.  The readable
       and writable event handlers for a file are independent, and may	be  created  and  deleted
       separately.   However,  there  may  be at most one readable and one writable handler for a
       file at a given time in a given interpreter.  If fileevent is called  when  the	specified
       handler already exists in the invoking interpreter, the new script replaces the old one.

       If  the	script	argument is not specified, fileevent returns the current script for chan-
       nelId, or an empty string if there is none.  If the script argument  is	specified  as  an
       empty string then the event handler is deleted, so that no script will be invoked.  A file
       event handler is also deleted automatically whenever its channel is closed or  its  inter-
       preter is deleted.

       A channel is considered to be readable if there is unread data available on the underlying
       device.	A channel is also considered to be readable if there is unread data in	an  input
       buffer,	except in the special case where the most recent attempt to read from the channel
       was a gets call that could not find a complete line in the  input  buffer.   This  feature
       allows  a file to be read a line at a time in nonblocking mode using events.  A channel is
       also considered to be readable if an end of file or error  condition  is  present  on  the
       underlying  file  or device.  It is important for script to check for these conditions and
       handle them appropriately;  for example, if there is no special check for end of file,  an
       infinite  loop  may  occur where script reads no data, returns, and is immediately invoked
       again.

       A channel is considered to be writable if at least one byte of data can be written to  the
       underlying  file  or  device  without blocking, or if an error condition is present on the
       underlying file or device.

       Event-driven I/O works best for channels that have been placed into nonblocking mode  with
       the  fconfigure	command.   In blocking mode, a puts command may block if you give it more
       data than the underlying file or device can accept, and a gets or read command will  block
       if  you	attempt  to  read more data than is ready;  no events will be processed while the
       commands block.	In nonblocking mode puts, read, and gets never block.  See the documenta-
       tion for the individual commands for information on how they handle blocking and nonblock-
       ing channels.

       The script for a file event is executed at global level (outside the context  of  any  Tcl
       procedure)  in  the  interpreter  in which the fileevent command was invoked.  If an error
       occurs while executing the script then the bgerror mechanism is used to report the  error.
       In  addition, the file event handler is deleted if it ever returns an error;  this is done
       in order to prevent infinite loops due to buggy handlers.

EXAMPLE
	       proc GetData {chan} {
		  if {![eof $chan]} {
		      puts [gets $chan]
		  }
	       }

	       fileevent $chan readable [list GetData $chan]

       In this setup GetData will be called with  the  channel	as  an	argument  whenever  $chan
       becomes readable.

CREDITS
       fileevent is based on the addinput command created by Mark Diekhans.

SEE ALSO
       bgerror(n), fconfigure(n), gets(n), puts(n), read(n), Tcl_StandardChannels(3)

KEYWORDS
       asynchronous  I/O,  blocking,  channel,	event  handler,  nonblocking,  readable,  script,
       writable.

Tcl					       7.5				     fileevent(n)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 07:08 PM.