1refchan(n) Tcl Built-In Commands refchan(n)
2______________________________________________________________________________
6
8 refchan - Command handler API of reflected channels, version 1
9
11 cmdPrefix option ?arg arg ...?
12_________________________________________________________________
13
15 The Tcl-level handler for a reflected channel has to be a command with
16 subcommands (termed an ensemble, as it is a command such as that cre‐
17 ated by namespace ensemble create, though the implementation of han‐
18 dlers for reflected channel is not tied to namespace ensembles in any
19 way). Note that cmdPrefix is whatever was specified in the call to chan
20 create, and may consist of multiple arguments; this will be expanded to
21 multiple words in place of the prefix.
22 Of all the possible subcommands, the handler must support initialize,
24 finalize, and watch. Support for the other subcommands is optional.
25 MANDATORY SUBCOMMANDS
27 cmdPrefix initialize channelId mode
28 An invocation of this subcommand will be the first call the cmd‐
29 Prefix will receive for the specified new channelId. It is the
30 responsibility of this subcommand to set up any internal data
31 structures required to keep track of the channel and its state.
32 The return value of the method has to be a list containing the
34 names of all subcommands supported by the cmdPrefix. This also
35 tells the Tcl core which version of the API for reflected chan‐
36 nels is used by this command handler.
37 Any error thrown by the method will abort the creation of the
39 channel and no channel will be created. The thrown error will
40 appear as error thrown by chan create. Any exception other than
41 an error (e.g. break, etc.) is treated as (and converted to) an
42 error.
43 Note: If the creation of the channel was aborted due to failures
45 here, then the finalize subcommand will not be called.
46 The mode argument tells the handler whether the channel was
48 opened for reading, writing, or both. It is a list containing
49 any of the strings read or write. The list will always contain
50 at least one element.
51 The subcommand must throw an error if the chosen mode is not
53 supported by the cmdPrefix.
54 cmdPrefix finalize channelId
56 An invocation of this subcommand will be the last call the cmd‐
57 Prefix will receive for the specified channelId. It will be gen‐
58 erated just before the destruction of the data structures of the
59 channel held by the Tcl core. The command handler must not
60 access the channelId anymore in no way. Upon this subcommand
61 being called, any internal resources allocated to this channel
62 must be cleaned up.
63 The return value of this subcommand is ignored.
65 If the subcommand throws an error the command which caused its
67 invocation (usually close) will appear to have thrown this
68 error. Any exception beyond error (e.g. break, etc.) is treated
69 as (and converted to) an error.
70 This subcommand is not invoked if the creation of the channel
72 was aborted during initialize (See above).
73 cmdPrefix watch channelId eventspec
75 This subcommand notifies the cmdPrefix that the specified chan‐
76 nelId is interested in the events listed in the eventspec. This
77 argument is a list containing any of read and write. The list
78 may be empty, which signals that the channel does not wish to be
79 notified of any events. In that situation, the handler should
80 disable event generation completely.
81 Warning: Any return value of the subcommand is ignored. This
83 includes all errors thrown by the subcommand, break, continue,
84 and custom return codes.
85 This subcommand interacts with chan postevent. Trying to post an
87 event which was not listed in the last call to watch will cause
88 chan postevent to throw an error.
89 OPTIONAL SUBCOMMANDS
91 cmdPrefix read channelId count
92 This optional subcommand is called when the user requests data
93 from the channel channelId. count specifies how many bytes have
94 been requested. If the subcommand is not supported then it is
95 not possible to read from the channel handled by the command.
96 The return value of this subcommand is taken as the requested
98 data bytes. If the returned data contains more bytes than
99 requested, an error will be signaled and later thrown by the
100 command which performed the read (usually gets or read). How‐
101 ever, returning fewer bytes than requested is acceptable.
102 Note that returning nothing (0 bytes) is a signal to the higher
104 layers that EOF has been reached on the channel. To signal that
105 the channel is out of data right now, but has not yet reached
106 EOF, it is necessary to throw the error "EAGAIN", i.e. to either
107 return -code error EAGAIN
109 or
110 error EAGAIN
111 For extensibility any error whose value is a negative integer
113 number will cause the higher layers to set the C-level variable
114 "errno" to the absolute value of this number, signaling a system
115 error. This means that both
116 return -code error -11
118 and
119 error -11
120 are equivalent to the examples above, using the more readable
122 string "EAGAIN". No other error value has such a mapping to a
123 symbolic string.
124 If the subcommand throws any other error, the command which
126 caused its invocation (usually gets, or read) will appear to
127 have thrown this error. Any exception beyond error, (e.g.
128 break, etc.) is treated as and converted to an error.
129 cmdPrefix write channelId data
131 This optional subcommand is called when the user writes data to
132 the channel channelId. The data argument contains bytes, not
133 characters. Any type of transformation (EOL, encoding) config‐
134 ured for the channel has already been applied at this point. If
135 this subcommand is not supported then it is not possible to
136 write to the channel handled by the command.
137 The return value of the subcommand is taken as the number of
139 bytes written by the channel. Anything non-numeric will cause an
140 error to be signaled and later thrown by the command which per‐
141 formed the write. A negative value implies that the write
142 failed. Returning a value greater than the number of bytes given
143 to the handler, or zero, is forbidden and will cause the Tcl
144 core to throw an error.
145 To signal that the channel is not able to accept data for writ‐
147 ing right now, it is necessary to throw the error "EAGAIN", i.e.
148 to either
149 return -code error EAGAIN
151 or
152 error EAGAIN
153 For extensibility any error whose value is a negative integer
155 number will cause the higher layers to set the C-level variable
156 "errno" to the absolute value of this number, signaling a system
157 error. However, note that the exact mapping between these error
158 numbers and their meanings is operating system dependent.
159 For example, while on Linux both
161 return -code error -11
163 and
164 error -11
165 are equivalent to the examples above, using the more readable
167 string "EAGAIN", this is not true for BSD, where the equivalent
168 number is -35.
169 The symbolic string however is the same across systems, and
171 internally translated to the correct number. No other error
172 value has such a mapping to a symbolic string.
173 If the subcommand throws any other error the command which
175 caused its invocation (usually puts) will appear to have thrown
176 this error. Any exception beyond error (e.g. break, etc.) is
177 treated as and converted to an error.
178 cmdPrefix seek channelId offset base
180 This optional subcommand is responsible for the handling of seek
181 and tell requests on the channel channelId. If it is not sup‐
182 ported then seeking will not be possible for the channel.
183 The base argument is one of
185 start Seeking is relative to the beginning of the channel.
187 current Seeking is relative to the current seek position.
189 end Seeking is relative to the end of the channel.
191 The base argument of the builtin chan seek command takes the
193 same names.
194 The offset is an integer number specifying the amount of bytes
196 to seek forward or backward. A positive number should seek for‐
197 ward, and a negative number should seek backward.
198 A channel may provide only limited seeking. For example sockets
200 can seek forward, but not backward.
201 The return value of the subcommand is taken as the (new) loca‐
203 tion of the channel, counted from the start. This has to be an
204 integer number greater than or equal to zero.
205 If the subcommand throws an error the command which caused its
207 invocation (usually seek, or tell) will appear to have thrown
208 this error. Any exception beyond error (e.g. break, etc.) is
209 treated as and converted to an error.
210 The offset/base combination of 0/current signals a tell request,
212 i.e. seek nothing relative to the current location, making the
213 new location identical to the current one, which is then
214 returned.
215 cmdPrefix configure channelId option value
217 This optional subcommand is for setting the type-specific
218 options of channel channelId. The option argument indicates the
219 option to be written, and the value argument indicates the value
220 to set the option to.
221 This subcommand will never try to update more than one option at
223 a time; that is behavior implemented in the Tcl channel core.
224 The return value of the subcommand is ignored.
226 If the subcommand throws an error the command which performed
228 the (re)configuration or query (usually fconfigure or chan con‐
229 figure) will appear to have thrown this error. Any exception
230 beyond error (e.g. break, etc.) is treated as and converted to
231 an error.
232 cmdPrefix cget channelId option
234 This optional subcommand is used when reading a single type-spe‐
235 cific option of channel channelId. If this subcommand is sup‐
236 ported then the subcommand cgetall must be supported as well.
237 The subcommand should return the value of the specified option.
239 If the subcommand throws an error, the command which performed
241 the (re)configuration or query (usually fconfigure) will appear
242 to have thrown this error. Any exception beyond error (e.g.
243 break, etc.) is treated as and converted to an error.
244 cmdPrefix cgetall channelId
246 This optional subcommand is used for reading all type-specific
247 options of channel channelId. If this subcommand is supported
248 then the subcommand cget has to be supported as well.
249 The subcommand should return a list of all options and their
251 values. This list must have an even number of elements.
252 If the subcommand throws an error the command which performed
254 the (re)configuration or query (usually fconfigure) will appear
255 to have thrown this error. Any exception beyond error (e.g.
256 break, etc.) is treated as and converted to an error.
257 cmdPrefix blocking channelId mode
259 This optional subcommand handles changes to the blocking mode of
260 the channel channelId. The mode is a boolean flag. A true value
261 means that the channel has to be set to blocking, and a false
262 value means that the channel should be non-blocking.
263 The return value of the subcommand is ignored.
265 If the subcommand throws an error the command which caused its
267 invocation (usually fconfigure) will appear to have thrown this
268 error. Any exception beyond error (e.g. break, etc.) is treated
269 as and converted to an error.
270
272 Some of the functions supported in channels defined in Tcl's C inter‐
273 face are not available to channels reflected to the Tcl level.
274 The function Tcl_DriverGetHandleProc is not supported; i.e. reflected
276 channels do not have OS specific handles.
277 The function Tcl_DriverHandlerProc is not supported. This driver func‐
279 tion is relevant only for stacked channels, i.e. transformations.
280 Reflected channels are always base channels, not transformations.
281 The function Tcl_DriverFlushProc is not supported. This is because the
283 current generic I/O layer of Tcl does not use this function anywhere at
284 all. Therefore support at the Tcl level makes no sense either. This may
285 be altered in the future (through extending the API defined here and
286 changing its version number) should the function be used at some time
287 in the future.
288
290 chan(n)
291
293 channel, reflection
294Tcl 8.5 refchan(n)