Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

RedHat 9 (Linux i386) - man page for fileevent (redhat section n)

fileevent(n)			      Tcl Built-In Commands			     fileevent(n)

_________________________________________________________________________________________________

NAME
       fileevent - Execute a script when a channel becomes readable or writable

SYNOPSIS
       fileevent channelId readable ?script?

       fileevent channelId writable ?script?
_________________________________________________________________

DESCRIPTION
       This  command  is  used	to create file event handlers.	A file event handler is a binding
       between a channel and a script, such that the script is	evaluated  whenever  the  channel
       becomes readable or writable.  File event handlers are most commonly used to allow data to
       be received from another 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 on a blocking channel 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  channelId  argument  to fileevent refers to an open channel, such as the return value
       from a previous open or socket  command.   If  the  script  argument  is  specified,  then
       fileevent  creates  a  new  event  handler:  script will be evaluated whenever the channel
       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 in a given inter-
       preter.	If fileevent is called when the specified handler already exists in the  invoking
       interpreter, the new script replaces the old one.

       If  the	script	argument is not specified, fileevent returns the current script for chan-
       nelId, 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 channel is closed or  its  inter-
       preter is deleted.

       A channel is considered to be readable if there is unread data available on the underlying
       device.	A channel is also considered to be readable if there is unread data in	an  input
       buffer,	except in the special case where the most recent attempt to read from the channel
       was a gets call that could not find a complete line in the  input  buffer.   This  feature
       allows  a file to be read a line at a time in nonblocking mode using events.  A channel is
       also considered to be readable if an end of file or error  condition  is  present  on  the
       underlying  file  or device.  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.

       A channel is considered to be writable if at least one byte of data can be written to  the
       underlying  file  or  device  without blocking, or if an error condition is present on the
       underlying file or device.

       Event-driven I/O works best for channels that have been placed into nonblocking mode  with
       the  fconfigure	command.   In blocking mode, a puts command may block if you give it more
       data than the underlying file or device can accept, and a gets or read command will  block
       if  you	attempt  to  read more data than is ready;  no events will be processed while the
       commands block.	In nonblocking mode puts, read, and gets never block.  See the documenta-
       tion for the individual commands for information on how they handle blocking and nonblock-
       ing channels.

       The script for a file event is executed at global level (outside the context  of  any  Tcl
       procedure)  in  the  interpreter  in which the fileevent command was invoked.  If an error
       occurs while executing the script then the bgerror 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
       bgerror(n), fconfigure(n), gets(n), puts(n), read(n)

KEYWORDS
       asynchronous  I/O,  blocking,  channel,	event  handler,  nonblocking,  readable,  script,
       writable.

Tcl					       7.5				     fileevent(n)


All times are GMT -4. The time now is 01:57 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password