fileevent - Execute a script when a file becomes readable or writable
fileevent fileId readable ?script?
fileevent fileId writable ?script?
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
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
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.
fileevent is based on the addinput command created by Mark Diekhans.
asynchronous I/O, event handler, file, readable, script, writable
PPPPaaaaggggeeee 2222 [ Back ]