summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorpatthoyts <patthoyts@users.sourceforge.net>2008-06-24 14:42:48 (GMT)
committerpatthoyts <patthoyts@users.sourceforge.net>2008-06-24 14:42:48 (GMT)
commitd71d99fe46ff7df438501ced7d8e53a3bcd4dca3 (patch)
treeb29222533c11d67c48cd07370cd7affe81aa2792 /doc
parented6a7e090c4d40ac85fd33572d92347eb5a9e327 (diff)
downloadtcl-d71d99fe46ff7df438501ced7d8e53a3bcd4dca3.zip
tcl-d71d99fe46ff7df438501ced7d8e53a3bcd4dca3.tar.gz
tcl-d71d99fe46ff7df438501ced7d8e53a3bcd4dca3.tar.bz2
bug #1995063 fix examples and comment on eof use.
Diffstat (limited to 'doc')
-rw-r--r--doc/fileevent.n38
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