fileevent(n)		     Ck 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 han-
       dler 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 con-
       tinue 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 com-
       mand.   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 inter-
       preter 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 exam-
       ple, 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 sec-
       ond  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	 addi-
       tional  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



Ck				      8.0			  fileevent(n)
