bug #1995063 fix examples and comment on eof use.

1 files changed, 33 insertions, 5 deletions

diff --git a/doc/fileevent.n b/doc/fileevent.n
index cf5231e..ba35bdf 100644
--- a/doc/fileevent.n
+++ b/doc/fileevent.n
@@ -1,11 +1,12 @@
 '\"
 '\" 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.
 '\" 
-'\" RCS: @(#) $Id: fileevent.n,v 1.13 2007/12/13 15:22:32 dgp Exp $
+'\" RCS: @(#) $Id: fileevent.n,v 1.14 2008/06/24 14:42:51 patthoyts Exp $
 '\" 
 .so man.macros
 .TH fileevent n 7.5 Tcl "Tcl Built-In Commands"
@@ -92,6 +93,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.
@@ -102,15 +108,37 @@ an error;  this is done in order to prevent infinite loops due to
 buggy handlers.
 .SH EXAMPLE
 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.
+.CS
+proc GetData {chan} {
+    set data [read $chan]
+    puts "[string length $data] $data"
+    if {[eof $chan]} {
+        fileevent $chan readable {}
+    }
+}
+
+fconfigure $chan -blocking 0 -encoding binary
+fileevent $chan readable [list GetData $chan]
+.CE
+The next example demonstrates use of \fBgets\fR to read line-oriented
+data.
 .CS
 proc GetData {chan} {
-    if {![eof $chan]} {
-        puts [gets $chan]
+    if {[gets $chan line] >= 0} {
+        puts $line
+    }
+    if {[eof $chan]} {
+        close $chan
     }
 }
 
-\fBfileevent\fR $chan readable [list GetData $chan]
+fconfigure $chan -blocking 0 -buffering line -translation crlf
+fileevent $chan readable [list GetData $chan]
 .CE
 
 .SH CREDITS