1 files changed, 34 insertions, 5 deletions
diff --git a/doc/fileevent.n b/doc/fileevent.n
index eb555f5..df48d2a 100644
--- a/doc/fileevent.n
+++ b/doc/fileevent.n
@@ -1,6 +1,7 @@
 '\"
 '\" Copyright (c) 1994 The Regents of the University of California.
 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 2008 Pat Thoyts
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
@@ -90,6 +91,11 @@ In nonblocking mode \fBputs\fR, \fBread\fR, and \fBgets\fR never block.
 See the documentation for the individual commands for information
 on how they handle blocking and nonblocking channels.
 .PP
+Testing for the end of file condition should be done after any attempts
+read the channel data. The eof flag is set once an attempt to read the
+end of data has occurred and testing before this read will require an
+additional event to be fired.
+.PP
 The script for a file event is executed at global level (outside the
 context of any Tcl procedure) in the interpreter in which the
 \fBfileevent\fR command was invoked.
@@ -99,26 +105,49 @@ 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.
 .SH EXAMPLE
+.PP
 In this setup \fBGetData\fR will be called with the channel as an
-argument whenever $chan becomes readable.
+argument whenever $chan becomes readable. The \fBread\fR call will
+read whatever binary data is currently available without blocking.
+Here the channel has the fileevent removed when an end of file 
+occurs to avoid being continually called (see above). Alternatively
+the channel may be closed on this condition.
+.PP
 .CS
 proc GetData {chan} {
-    if {![eof $chan]} {
-        puts [gets $chan]
+    set data [read $chan]
+    puts "[string length $data] $data"
+    if {[eof $chan]} {
+        fileevent $chan readable {}
     }
 }
 
+fconfigure $chan -blocking 0 -encoding binary
 \fBfileevent\fR $chan readable [list GetData $chan]
 .CE
+.PP
+The next example demonstrates use of \fBgets\fR to read line-oriented
+data.
+.PP
+.CS
+proc GetData {chan} {
+    if {[gets $chan line] >= 0} {
+        puts $line
+    }
+    if {[eof $chan]} {
+        close $chan
+    }
+}
 
+fconfigure $chan -blocking 0 -buffering line -translation crlf
+\fBfileevent\fR $chan readable [list GetData $chan]
+.CE
 .SH CREDITS
 .PP
 \fBfileevent\fR is based on the \fBaddinput\fR command created
 by Mark Diekhans.
-
 .SH "SEE ALSO"
 fconfigure(n), gets(n), interp(n), puts(n), read(n), Tcl_StandardChannels(3)
-
 .SH KEYWORDS
 asynchronous I/O, blocking, channel, event handler, nonblocking, readable,
 script, writable.