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.
Copyright © 1994 The Regents of the University of California. Copyright © 1994 Sun Microsystems, Inc. Copyright © 1995 Roger E. Critchlow Jr.