_________________________________________________________________

     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 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.  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
          condition 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, 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 probably 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 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.


     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