Provided by: tcl8.5-doc_8.5.15-2ubuntu1_all bug

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
       continue  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 will not
       block.

       The channelId argument to fileevent refers to an open  channel  such  as  a  Tcl  standard
       channel (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
       second 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
       channelId, 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
       interpreter 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
       documentation  for the individual commands for information on how they handle blocking and
       nonblocking 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 command registered with interp bgerror 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

       In this setup GetData will be called with  the  channel  as  an  argument  whenever  $chan
       becomes readable.
              proc GetData {chan} {
                  if {![eof $chan]} {
                      puts [gets $chan]
                  }
              }

              fileevent $chan readable [list GetData $chan]

CREDITS

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

SEE ALSO

       fconfigure(3tcl),       gets(3tcl),       interp(3tcl),       puts(3tcl),      read(3tcl),
       Tcl_StandardChannels(3tcl)

KEYWORDS

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