summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorandreas_kupries <akupries@shaw.ca>2009-08-06 22:28:11 (GMT)
committerandreas_kupries <akupries@shaw.ca>2009-08-06 22:28:11 (GMT)
commitf92b24a616e3a96bef3765e9bda4b66f3c7e5010 (patch)
treed37280b808ac19ae14bb5ba244e3b8616d7fd540 /doc
parentdff3fc1f53f49695e31f07d4b00ac359c4f1e728 (diff)
downloadtcl-f92b24a616e3a96bef3765e9bda4b66f3c7e5010.zip
tcl-f92b24a616e3a96bef3765e9bda4b66f3c7e5010.tar.gz
tcl-f92b24a616e3a96bef3765e9bda4b66f3c7e5010.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 80a4305..6032340 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.16 2009/07/11 11:23:06 dkf Exp $
+'\" RCS: @(#) $Id: refchan.n,v 1.17 2009/08/06 22:28:11 andreas_kupries Exp $
.so man.macros
.TH refchan n 8.5 Tcl "Tcl Built-In Commands"
.BS
@@ -117,7 +117,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 \fBerror\fR, (e.g.,\ \fBbreak\fR,
etc.) is treated as and converted to an error.