Tcl Built-In Commands                               fileevent(1T)





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 pro-
     cess 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  chan-  
     nel  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 read-
     able  and one writable handler for a file at a given time in
     a given interpreter.  If fileevent is called when the speci-
     fied 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



Tcl                     Last change: 7.5                        1






Tcl Built-In Commands                               fileevent(1T)



     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  non-
     blocking 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 inter-
     preter 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
     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]
              }
          }




Tcl                     Last change: 7.5                        2






Tcl Built-In Commands                               fileevent(1T)



          fileevent $chan readable [list GetData $chan]


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


SEE ALSO
     bgerror(1T), fconfigure(1T), gets(1T),  puts(1T),  read(1T),
     TclStandardChannels(3TCL)


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

ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     
       ATRIBUTE TYPE     ATRIBUTE VALUE
    
     Availability         SUNWTcl        
    
     Interface Stability  Uncommitted    
    

NOTES
     Source for Tcl is available on http:/opensolaris.org.
























Tcl                     Last change: 7.5                        3