fileevent(3Tk)

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