diff options
Diffstat (limited to 'doc/refchan.n')
| -rw-r--r-- | doc/refchan.n | 64 |
1 files changed, 52 insertions, 12 deletions
diff --git a/doc/refchan.n b/doc/refchan.n index 6032340..2232d50 100644 --- a/doc/refchan.n +++ b/doc/refchan.n @@ -4,9 +4,8 @@ '\" 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.17 2009/08/06 22:28:11 andreas_kupries Exp $ -.so man.macros .TH refchan n 8.5 Tcl "Tcl Built-In Commands" +.so man.macros .BS .\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -18,10 +17,10 @@ refchan \- command handler API of reflected channels .PP The Tcl-level handler for a reflected channel has to be a command with subcommands (termed an \fIensemble\fR, as it is a command such as that -created by \fBnamespace ensemble create\fR, though the implementation +created by \fBnamespace ensemble\fR \fBcreate\fR, though the implementation of handlers for reflected channel \fIis not\fR tied to \fBnamespace -ensemble\fRs in any way; see \fBEXAMPLE\fR below for how to build a -\fBclass\fR that supports the API). Note that \fIcmdPrefix\fR is whatever was +ensemble\fRs in any way; see \fBEXAMPLE\fR below for how to build an +\fBoo::class\fR that supports the API). Note that \fIcmdPrefix\fR is whatever was specified in the call to \fBchan create\fR, and may consist of multiple arguments; this will be expanded to multiple words in place of the prefix. @@ -132,8 +131,11 @@ error EAGAIN .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 +to the absolute value of this number, signaling a system error. +However, note that the exact mapping between these error numbers and +their meanings is operating system dependent. +.PP +For example, while on Linux both .PP .CS return -code error -11 @@ -143,8 +145,12 @@ and 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. +are equivalent to the examples above, using the more readable string "EAGAIN", +this is not true for BSD, where the equivalent number is -35. +.PP +The symbolic string however is the same across systems, and internally +translated to the correct number. 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 @@ -169,7 +175,41 @@ negative value implies that the write failed. Returning a value greater than the number of bytes given to the handler, or zero, is forbidden and will cause the Tcl core to throw an error. .PP -If the subcommand throws an error the command which caused its +To signal that the channel is not able to accept data for writing +right now, 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. +However, note that the exact mapping between these error numbers and +their meanings is operating system dependent. +.PP +For example, while on Linux 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", +this is not true for BSD, where the equivalent number is -35. +.PP +The symbolic string however is the same across systems, and internally +translated to the correct number. 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 \fBputs\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. @@ -230,8 +270,8 @@ time; that is behavior implemented in the Tcl channel core. The return value of the subcommand is ignored. .PP If the subcommand throws an error the command which performed the -(re)configuration or query (usually \fBfconfigure\fR or \fBchan -configure\fR) will appear to have thrown this error. Any exception +(re)configuration or query (usually \fBfconfigure\fR or +\fBchan configure\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. .RE |