


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


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

SYNOPSIS
       fileevent fileId readable ?script?
       fileevent fileId writable ?script?


DESCRIPTION
       This command is used to create  file  event  handlers.   A
       file  event  handler  is  a  binding  between a file and a
       script, such that the script  is  evaluated  whenever  the
       file  becomes  readable  or writable.  File event handlers
       are most commonly used to allow data to be received from a
       child  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 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  fileId  argument to fileevent refers to an open file;
       it must be stdin, stdout, stderr, or the return value from
       some  previous  open  command.   If the script argument is
       specified, then fileevent creates  a  new  event  handler:
       script  will  be evaluated whenever the file becomes read-
       able 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 sepa-
       rately.  However, there may be at most  one  readable  and
       one  writable  handler  for  a  file  at a given time.  If
       fileevent is called when  the  specified  handler  already
       exists, the new script replaces the old one.

       If the script argument is not specified, fileevent returns
       the current script for fileId, 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 file is closed  or  its
       interpreter is deleted.

       A  file is considered to be readable whenever the gets and
       read commands can return without blocking.  A file is also
       considered  to be readable if an end-of-file or error con-
       dition is present.  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,



Tk                             4.0                              1





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


       returns, and is immediately invoked again.

       When using fileevent for event-driven I/O, it's  important
       to  read  the file in the same units that are written from
       the other end.  For example, suppose that  you  are  using
       fileevent  to  read data generated by a child process.  If
       the child process is writing whole lines, then you  should
       use  gets to read those lines.  If the child generates one
       line at a time then you shouldn't make more than a  single
       call  to  gets  in script: the first call will consume all
       the available data, so the second call may block.  You can
       also  use  read  to read the child's data, but only if you
       know how many bytes the child is writing at  a  time:   if
       you try to read more bytes than the child has written, the
       read call will block.

       A file is considered to be writable if at least  one  byte
       of data can be written to the file without blocking, or if
       an error condition is present.  Write handlers are  proba-
       bly  not  very  useful without additional command support.
       The puts command is dangerous since it write more than one
       byte  at a time and may thus block.  What is really needed
       is a new non-blocking form of write that  saves  any  data
       that couldn't be written to the file.

       The  script  for  a file event is executed at global level
       (outside the context of any Tcl procedure).  If  an  error
       occurs  while executing the script then the tkerror mecha-
       nism 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.


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


SEE ALSO
       tkerror


KEYWORDS
       asynchronous I/O, event handler, file,  readable,  script,
       writable
