doc/fileevent.n

   1 '\"
   2 '\" Copyright (c) 1994 The Regents of the University of California.
   3 '\" Copyright (c) 1994 Sun Microsystems, Inc.
   4 '\" Copyright (c) 1996-1999 Christian Werner
   5 '\"
   6 '\" See the file "license.terms" for information on usage and redistribution
   7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   8 '\"
   9 .so man.macros
  10 .TH fileevent n 8.0 Ck "Ck Built-In Commands"
  11 .BS
  12 '\" Note:  do not modify the .SH NAME line immediately below!
  13 .SH NAME
  14 fileevent \- Execute a script when a file becomes readable or writable
  15 .SH SYNOPSIS
  16 \fBfileevent \fIfileId \fBreadable \fR?\fIscript\fR?
  17 .br
  18 \fBfileevent \fIfileId \fBwritable \fR?\fIscript\fR?
  19 .BE
  20
  21 .SH DESCRIPTION
  22 .PP
  23 This command is used to create \fIfile event handlers\fR.
  24 A file event handler is a binding between a file and a script,
  25 such that the script is evaluated whenever the file becomes
  26 readable or writable.
  27 File event handlers are most commonly used to allow data to be
  28 received from a child process on an event-driven basis, so that
  29 the receiver can continue to interact with the user while
  30 waiting for the data to arrive.
  31 If an application invokes \fBgets\fR or \fBread\fR when there
  32 is no input data available, the process will block;  until the
  33 input data arrives, it will not be able to service other events,
  34 so it will appear to the user to ``freeze up''.
  35 With \fBfileevent\fR, the process can tell when data is present
  36 and only invoke \fBgets\fR or \fBread\fR when they won't block.
  37 .PP
  38 The \fIfileId\fR argument to \fBfileevent\fR refers to an open file;
  39 it must be \fBstdin\fR, \fBstdout\fR, \fBstderr\fR, or the return value
  40 from some previous \fBopen\fR command.
  41 If the \fIscript\fR argument is specified, then \fBfileevent\fR
  42 creates a new event handler:  \fIscript\fR will be evaluated
  43 whenever the file becomes readable or writable (depending on the
  44 second argument to \fBfileevent\fR).
  45 In this case \fBfileevent\fR returns an empty string.
  46 The \fBreadable\fR and \fBwritable\fR event handlers for a file
  47 are independent, and may be created and deleted separately.
  48 However, there may be at most one \fBreadable\fR and one \fBwritable\fR
  49 handler for a file at a given time.
  50 If \fBfileevent\fR is called when the specified handler already
  51 exists, the new script replaces the old one.
  52 .PP
  53 If the \fIscript\fR argument is not specified, \fBfileevent\fR
  54 returns the current script for \fIfileId\fR, or an empty string
  55 if there is none.
  56 If the \fIscript\fR argument is specified as an empty string
  57 then the event handler is deleted, so that no script will be invoked.
  58 A file event handler is also deleted automatically whenever
  59 its file is closed or its interpreter is deleted.
  60 .PP
  61 A file is considered to be readable whenever the \fBgets\fR
  62 and \fBread\fR commands can return without blocking.
  63 A file is also considered to be readable if an end-of-file or
  64 error condition is present.
  65 It is important for \fIscript\fR to check for these conditions
  66 and handle them appropriately;  for example, if there is no special
  67 check for end-of-file, an infinite loop may occur where \fIscript\fR
  68 reads no data, returns, and is immediately invoked again.
  69 .PP
  70 When using \fBfileevent\fR for event-driven I/O, it's important
  71 to read the file in the same units that are written
  72 from the other end.
  73 For example, suppose that you are using \fBfileevent\fR to
  74 read data generated by a child process.
  75 If the child process is writing whole lines, then you should use
  76 \fBgets\fR to read those lines.
  77 If the child generates one line at a time then you shouldn't
  78 make more than a single call to \fBgets\fR in \fIscript\fR: the first call
  79 will consume all the available data, so the second call may block.
  80 You can also use \fBread\fR to read the child's data, but only
  81 if you know how many bytes the child is writing at a time:  if
  82 you try to read more bytes than the child has written, the
  83 \fBread\fR call will block.
  84 .PP
  85 A file is considered to be writable if at least one byte of data
  86 can be written to the file without blocking, or if an error condition
  87 is present.
  88 Write handlers are probably not very useful without additional command
  89 support.
  90 The \fBputs\fR command is dangerous since it write more than
  91 one byte at a time and may thus block.
  92 What is really needed is a new non-blocking form of write that
  93 saves any data that couldn't be written to the file.
  94 .PP
  95 The script for a file event is executed at global level (outside the
  96 context of any Tcl procedure).
  97 If an error occurs while executing the script then the
  98 \fBtkerror\fR mechanism is used to report the error.
  99 In addition, the file event handler is deleted if it ever returns
 100 an error;  this is done in order to prevent infinite loops due to
 101 buggy handlers.
 102
 103 .SH CREDITS
 104 .PP
 105 \fBfileevent\fR is based on the \fBaddinput\fR command created
 106 by Mark Diekhans.
 107
 108 .SH "SEE ALSO"
 109 tkerror
 110
 111 .SH KEYWORDS
 112 asynchronous I/O, event handler, file, readable, script, writable