summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorandreas_kupries <akupries@shaw.ca>2009-08-06 22:28:44 (GMT)
committerandreas_kupries <akupries@shaw.ca>2009-08-06 22:28:44 (GMT)
commit9b60842d16319877dbd4d5690699e7f17908392b (patch)
tree70a5194faa31375e3bc159e95e899ab9b76ad7e2 /doc
parent53b1f467a9e16c6358a0e6d06db9413e1bc4c2c8 (diff)
downloadtcl-9b60842d16319877dbd4d5690699e7f17908392b.zip
tcl-9b60842d16319877dbd4d5690699e7f17908392b.tar.gz
tcl-9b60842d16319877dbd4d5690699e7f17908392b.tar.bz2
* doc/refchan.n [Bug 2827000]: Extended the implementation of
* generic/tclIORChan.c: reflective channels (TIP 219, method * tests/ioCmd.test: 'read'), enabling handlers to signal EAGAIN to indicate 'no data, but not at EOF either', and other system errors. Updated documentation, extended testsuite (New test cases iocmd*-23.{9,10}).
Diffstat (limited to 'doc')
-rw-r--r--doc/refchan.n33
1 files changed, 31 insertions, 2 deletions
diff --git a/doc/refchan.n b/doc/refchan.n
index d007c0f..42e5588 100644
--- a/doc/refchan.n
+++ b/doc/refchan.n
@@ -4,7 +4,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: refchan.n,v 1.11 2008/03/26 09:59:22 dkf Exp $
+'\" RCS: @(#) $Id: refchan.n,v 1.11.2.1 2009/08/06 22:28:44 andreas_kupries Exp $
.so man.macros
.TH refchan n 8.5 Tcl "Tcl Built-In Commands"
.BS
@@ -116,7 +116,36 @@ an error will be signaled and later thrown by the command which
performed the read (usually \fBgets\fR or \fBread\fR). However,
returning fewer bytes than requested is acceptable.
.PP
-If the subcommand throws an error, the command which caused its
+Note that returning nothing (0 bytes) is a signal to the higher layers
+that \fBEOF\fR has been reached on the channel. To signal that the
+channel is out of data right now, but has not yet reached \fBEOF\fR,
+it is necessary to throw the error "EAGAIN", i.e. to either
+.PP
+.CS
+return -code error EAGAIN
+.CE
+or
+.CS
+error EAGAIN
+.CE
+.PP
+For extensibility any error whose value is a negative integer number
+will cause the higher layers to set the C-level variable "\fBerrno\fR"
+to the absolute value of this number, signaling a system error. This
+means that both
+.PP
+.CS
+return -code error -11
+.CE
+and
+.CS
+error -11
+.CE
+.PP
+are equivalent to the examples above, using the more readable string "EAGAIN".
+No other error value has such a mapping to a symbolic string.
+.PP
+If the subcommand throws any other error, the command which caused its
invocation (usually \fBgets\fR, or \fBread\fR) will appear to have
thrown this error. Any exception beyond \fIerror\fR, (e.g.
\fIbreak\fR, etc.) is treated as and converted to an error.