Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | '\" |
2 | '\" Copyright (c) 1996-1997 Sun Microsystems, Inc. | |
3 | '\" Copyright (c) 1997-2000 Ajuba Solutions. | |
4 | '\" | |
5 | '\" See the file "license.terms" for information on usage and redistribution | |
6 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. | |
7 | '\" | |
8 | '\" RCS: @(#) $Id: CrtChannel.3,v 1.16.2.4 2005/02/23 10:27:45 dkf Exp $ | |
9 | '\" The definitions below are for supplemental macros used in Tcl/Tk | |
10 | '\" manual entries. | |
11 | '\" | |
12 | '\" .AP type name in/out ?indent? | |
13 | '\" Start paragraph describing an argument to a library procedure. | |
14 | '\" type is type of argument (int, etc.), in/out is either "in", "out", | |
15 | '\" or "in/out" to describe whether procedure reads or modifies arg, | |
16 | '\" and indent is equivalent to second arg of .IP (shouldn't ever be | |
17 | '\" needed; use .AS below instead) | |
18 | '\" | |
19 | '\" .AS ?type? ?name? | |
20 | '\" Give maximum sizes of arguments for setting tab stops. Type and | |
21 | '\" name are examples of largest possible arguments that will be passed | |
22 | '\" to .AP later. If args are omitted, default tab stops are used. | |
23 | '\" | |
24 | '\" .BS | |
25 | '\" Start box enclosure. From here until next .BE, everything will be | |
26 | '\" enclosed in one large box. | |
27 | '\" | |
28 | '\" .BE | |
29 | '\" End of box enclosure. | |
30 | '\" | |
31 | '\" .CS | |
32 | '\" Begin code excerpt. | |
33 | '\" | |
34 | '\" .CE | |
35 | '\" End code excerpt. | |
36 | '\" | |
37 | '\" .VS ?version? ?br? | |
38 | '\" Begin vertical sidebar, for use in marking newly-changed parts | |
39 | '\" of man pages. The first argument is ignored and used for recording | |
40 | '\" the version when the .VS was added, so that the sidebars can be | |
41 | '\" found and removed when they reach a certain age. If another argument | |
42 | '\" is present, then a line break is forced before starting the sidebar. | |
43 | '\" | |
44 | '\" .VE | |
45 | '\" End of vertical sidebar. | |
46 | '\" | |
47 | '\" .DS | |
48 | '\" Begin an indented unfilled display. | |
49 | '\" | |
50 | '\" .DE | |
51 | '\" End of indented unfilled display. | |
52 | '\" | |
53 | '\" .SO | |
54 | '\" Start of list of standard options for a Tk widget. The | |
55 | '\" options follow on successive lines, in four columns separated | |
56 | '\" by tabs. | |
57 | '\" | |
58 | '\" .SE | |
59 | '\" End of list of standard options for a Tk widget. | |
60 | '\" | |
61 | '\" .OP cmdName dbName dbClass | |
62 | '\" Start of description of a specific option. cmdName gives the | |
63 | '\" option's name as specified in the class command, dbName gives | |
64 | '\" the option's name in the option database, and dbClass gives | |
65 | '\" the option's class in the option database. | |
66 | '\" | |
67 | '\" .UL arg1 arg2 | |
68 | '\" Print arg1 underlined, then print arg2 normally. | |
69 | '\" | |
70 | '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $ | |
71 | '\" | |
72 | '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. | |
73 | .if t .wh -1.3i ^B | |
74 | .nr ^l \n(.l | |
75 | .ad b | |
76 | '\" # Start an argument description | |
77 | .de AP | |
78 | .ie !"\\$4"" .TP \\$4 | |
79 | .el \{\ | |
80 | . ie !"\\$2"" .TP \\n()Cu | |
81 | . el .TP 15 | |
82 | .\} | |
83 | .ta \\n()Au \\n()Bu | |
84 | .ie !"\\$3"" \{\ | |
85 | \&\\$1 \\fI\\$2\\fP (\\$3) | |
86 | .\".b | |
87 | .\} | |
88 | .el \{\ | |
89 | .br | |
90 | .ie !"\\$2"" \{\ | |
91 | \&\\$1 \\fI\\$2\\fP | |
92 | .\} | |
93 | .el \{\ | |
94 | \&\\fI\\$1\\fP | |
95 | .\} | |
96 | .\} | |
97 | .. | |
98 | '\" # define tabbing values for .AP | |
99 | .de AS | |
100 | .nr )A 10n | |
101 | .if !"\\$1"" .nr )A \\w'\\$1'u+3n | |
102 | .nr )B \\n()Au+15n | |
103 | .\" | |
104 | .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n | |
105 | .nr )C \\n()Bu+\\w'(in/out)'u+2n | |
106 | .. | |
107 | .AS Tcl_Interp Tcl_CreateInterp in/out | |
108 | '\" # BS - start boxed text | |
109 | '\" # ^y = starting y location | |
110 | '\" # ^b = 1 | |
111 | .de BS | |
112 | .br | |
113 | .mk ^y | |
114 | .nr ^b 1u | |
115 | .if n .nf | |
116 | .if n .ti 0 | |
117 | .if n \l'\\n(.lu\(ul' | |
118 | .if n .fi | |
119 | .. | |
120 | '\" # BE - end boxed text (draw box now) | |
121 | .de BE | |
122 | .nf | |
123 | .ti 0 | |
124 | .mk ^t | |
125 | .ie n \l'\\n(^lu\(ul' | |
126 | .el \{\ | |
127 | .\" Draw four-sided box normally, but don't draw top of | |
128 | .\" box if the box started on an earlier page. | |
129 | .ie !\\n(^b-1 \{\ | |
130 | \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' | |
131 | .\} | |
132 | .el \}\ | |
133 | \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' | |
134 | .\} | |
135 | .\} | |
136 | .fi | |
137 | .br | |
138 | .nr ^b 0 | |
139 | .. | |
140 | '\" # VS - start vertical sidebar | |
141 | '\" # ^Y = starting y location | |
142 | '\" # ^v = 1 (for troff; for nroff this doesn't matter) | |
143 | .de VS | |
144 | .if !"\\$2"" .br | |
145 | .mk ^Y | |
146 | .ie n 'mc \s12\(br\s0 | |
147 | .el .nr ^v 1u | |
148 | .. | |
149 | '\" # VE - end of vertical sidebar | |
150 | .de VE | |
151 | .ie n 'mc | |
152 | .el \{\ | |
153 | .ev 2 | |
154 | .nf | |
155 | .ti 0 | |
156 | .mk ^t | |
157 | \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' | |
158 | .sp -1 | |
159 | .fi | |
160 | .ev | |
161 | .\} | |
162 | .nr ^v 0 | |
163 | .. | |
164 | '\" # Special macro to handle page bottom: finish off current | |
165 | '\" # box/sidebar if in box/sidebar mode, then invoked standard | |
166 | '\" # page bottom macro. | |
167 | .de ^B | |
168 | .ev 2 | |
169 | 'ti 0 | |
170 | 'nf | |
171 | .mk ^t | |
172 | .if \\n(^b \{\ | |
173 | .\" Draw three-sided box if this is the box's first page, | |
174 | .\" draw two sides but no top otherwise. | |
175 | .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c | |
176 | .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c | |
177 | .\} | |
178 | .if \\n(^v \{\ | |
179 | .nr ^x \\n(^tu+1v-\\n(^Yu | |
180 | \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c | |
181 | .\} | |
182 | .bp | |
183 | 'fi | |
184 | .ev | |
185 | .if \\n(^b \{\ | |
186 | .mk ^y | |
187 | .nr ^b 2 | |
188 | .\} | |
189 | .if \\n(^v \{\ | |
190 | .mk ^Y | |
191 | .\} | |
192 | .. | |
193 | '\" # DS - begin display | |
194 | .de DS | |
195 | .RS | |
196 | .nf | |
197 | .sp | |
198 | .. | |
199 | '\" # DE - end display | |
200 | .de DE | |
201 | .fi | |
202 | .RE | |
203 | .sp | |
204 | .. | |
205 | '\" # SO - start of list of standard options | |
206 | .de SO | |
207 | .SH "STANDARD OPTIONS" | |
208 | .LP | |
209 | .nf | |
210 | .ta 5.5c 11c | |
211 | .ft B | |
212 | .. | |
213 | '\" # SE - end of list of standard options | |
214 | .de SE | |
215 | .fi | |
216 | .ft R | |
217 | .LP | |
218 | See the \\fBoptions\\fR manual entry for details on the standard options. | |
219 | .. | |
220 | '\" # OP - start of full description for a single option | |
221 | .de OP | |
222 | .LP | |
223 | .nf | |
224 | .ta 4c | |
225 | Command-Line Name: \\fB\\$1\\fR | |
226 | Database Name: \\fB\\$2\\fR | |
227 | Database Class: \\fB\\$3\\fR | |
228 | .fi | |
229 | .IP | |
230 | .. | |
231 | '\" # CS - begin code excerpt | |
232 | .de CS | |
233 | .RS | |
234 | .nf | |
235 | .ta .25i .5i .75i 1i | |
236 | .. | |
237 | '\" # CE - end code excerpt | |
238 | .de CE | |
239 | .fi | |
240 | .RE | |
241 | .. | |
242 | .de UL | |
243 | \\$1\l'|0\(ul'\\$2 | |
244 | .. | |
245 | .TH Tcl_CreateChannel 3 8.4 Tcl "Tcl Library Procedures" | |
246 | .BS | |
247 | '\" Note: do not modify the .SH NAME line immediately below! | |
248 | .SH NAME | |
249 | Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType, Tcl_GetChannelName, Tcl_GetChannelHandle, Tcl_GetChannelMode, Tcl_GetChannelBufferSize, Tcl_SetChannelBufferSize, Tcl_NotifyChannel, Tcl_BadChannelOption, Tcl_ChannelName, Tcl_ChannelVersion, Tcl_ChannelBlockModeProc, Tcl_ChannelCloseProc, Tcl_ChannelClose2Proc, Tcl_ChannelInputProc, Tcl_ChannelOutputProc, Tcl_ChannelSeekProc, Tcl_ChannelWideSeekProc, Tcl_ChannelSetOptionProc, Tcl_ChannelGetOptionProc, Tcl_ChannelWatchProc, Tcl_ChannelGetHandleProc, Tcl_ChannelFlushProc, Tcl_ChannelHandlerProc, Tcl_ChannelThreadActionProc, Tcl_IsChannelShared, Tcl_IsChannelRegistered, Tcl_CutChannel, Tcl_SpliceChannel, Tcl_IsChannelExisting, Tcl_ClearChannelHandlers, Tcl_GetChannelThread, Tcl_ChannelBuffered \- procedures for creating and manipulating channels | |
250 | .SH SYNOPSIS | |
251 | .nf | |
252 | \fB#include <tcl.h>\fR | |
253 | .sp | |
254 | Tcl_Channel | |
255 | \fBTcl_CreateChannel\fR(\fItypePtr, channelName, instanceData, mask\fR) | |
256 | .sp | |
257 | ClientData | |
258 | \fBTcl_GetChannelInstanceData\fR(\fIchannel\fR) | |
259 | .sp | |
260 | Tcl_ChannelType * | |
261 | \fBTcl_GetChannelType\fR(\fIchannel\fR) | |
262 | .sp | |
263 | CONST char * | |
264 | \fBTcl_GetChannelName\fR(\fIchannel\fR) | |
265 | .sp | |
266 | int | |
267 | \fBTcl_GetChannelHandle\fR(\fIchannel, direction, handlePtr\fR) | |
268 | .sp | |
269 | .VS 8.4 | |
270 | Tcl_ThreadId | |
271 | \fBTcl_GetChannelThread\fR(\fIchannel\fR) | |
272 | .VE 8.4 | |
273 | .sp | |
274 | int | |
275 | \fBTcl_GetChannelMode\fR(\fIchannel\fR) | |
276 | .sp | |
277 | int | |
278 | \fBTcl_GetChannelBufferSize\fR(\fIchannel\fR) | |
279 | .sp | |
280 | \fBTcl_SetChannelBufferSize\fR(\fIchannel, size\fR) | |
281 | .sp | |
282 | \fBTcl_NotifyChannel\fR(\fIchannel, mask\fR) | |
283 | .sp | |
284 | int | |
285 | \fBTcl_BadChannelOption\fR(\fIinterp, optionName, optionList\fR) | |
286 | .VS 8.4 | |
287 | .sp | |
288 | int | |
289 | \fBTcl_IsChannelShared\fR(\fIchannel\fR) | |
290 | .sp | |
291 | int | |
292 | \fBTcl_IsChannelRegistered\fR(\fIinterp, channel\fR) | |
293 | .sp | |
294 | int | |
295 | \fBTcl_IsChannelExisting\fR(\fIchannelName\fR) | |
296 | .sp | |
297 | void | |
298 | \fBTcl_CutChannel\fR(\fIchannel\fR) | |
299 | .sp | |
300 | void | |
301 | \fBTcl_SpliceChannel\fR(\fIchannel\fR) | |
302 | .sp | |
303 | void | |
304 | \fBTcl_ClearChannelHandlers\fR(\fIchannel\fR) | |
305 | .VE 8.4 | |
306 | .sp | |
307 | int | |
308 | \fBTcl_ChannelBuffered\fR(\fIchannel\fR) | |
309 | .sp | |
310 | CONST char * | |
311 | \fBTcl_ChannelName\fR(\fItypePtr\fR) | |
312 | .sp | |
313 | Tcl_ChannelTypeVersion | |
314 | \fBTcl_ChannelVersion\fR(\fItypePtr\fR) | |
315 | .sp | |
316 | Tcl_DriverBlockModeProc * | |
317 | \fBTcl_ChannelBlockModeProc\fR(\fItypePtr\fR) | |
318 | .sp | |
319 | Tcl_DriverCloseProc * | |
320 | \fBTcl_ChannelCloseProc\fR(\fItypePtr\fR) | |
321 | .sp | |
322 | Tcl_DriverClose2Proc * | |
323 | \fBTcl_ChannelClose2Proc\fR(\fItypePtr\fR) | |
324 | .sp | |
325 | Tcl_DriverInputProc * | |
326 | \fBTcl_ChannelInputProc\fR(\fItypePtr\fR) | |
327 | .sp | |
328 | Tcl_DriverOutputProc * | |
329 | \fBTcl_ChannelOutputProc\fR(\fItypePtr\fR) | |
330 | .sp | |
331 | Tcl_DriverSeekProc * | |
332 | \fBTcl_ChannelSeekProc\fR(\fItypePtr\fR) | |
333 | .sp | |
334 | .VS 8.4 | |
335 | Tcl_DriverWideSeekProc * | |
336 | \fBTcl_ChannelWideSeekProc\fR(\fItypePtr\fR) | |
337 | .sp | |
338 | Tcl_DriverThreadActionProc * | |
339 | \fBTcl_ChannelThreadActionProc\fR(\fItypePtr\fR) | |
340 | .VE 8.4 | |
341 | .sp | |
342 | Tcl_DriverSetOptionProc * | |
343 | \fBTcl_ChannelSetOptionProc\fR(\fItypePtr\fR) | |
344 | .sp | |
345 | Tcl_DriverGetOptionProc * | |
346 | \fBTcl_ChannelGetOptionProc\fR(\fItypePtr\fR) | |
347 | .sp | |
348 | Tcl_DriverWatchProc * | |
349 | \fBTcl_ChannelWatchProc\fR(\fItypePtr\fR) | |
350 | .sp | |
351 | Tcl_DriverGetHandleProc * | |
352 | \fBTcl_ChannelGetHandleProc\fR(\fItypePtr\fR) | |
353 | .sp | |
354 | Tcl_DriverFlushProc * | |
355 | \fBTcl_ChannelFlushProc\fR(\fItypePtr\fR) | |
356 | .sp | |
357 | Tcl_DriverHandlerProc * | |
358 | \fBTcl_ChannelHandlerProc\fR(\fItypePtr\fR) | |
359 | .sp | |
360 | .SH ARGUMENTS | |
361 | .AS Tcl_ChannelType *channelName in | |
362 | .AP Tcl_ChannelType *typePtr in | |
363 | Points to a structure containing the addresses of procedures that | |
364 | can be called to perform I/O and other functions on the channel. | |
365 | .AP "CONST char" *channelName in | |
366 | The name of this channel, such as \fBfile3\fR; must not be in use | |
367 | by any other channel. Can be NULL, in which case the channel is | |
368 | created without a name. | |
369 | .AP ClientData instanceData in | |
370 | Arbitrary one-word value to be associated with this channel. This | |
371 | value is passed to procedures in \fItypePtr\fR when they are invoked. | |
372 | .AP int mask in | |
373 | OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR to indicate | |
374 | whether a channel is readable and writable. | |
375 | .AP Tcl_Channel channel in | |
376 | The channel to operate on. | |
377 | .AP int direction in | |
378 | \fBTCL_READABLE\fR means the input handle is wanted; \fBTCL_WRITABLE\fR | |
379 | means the output handle is wanted. | |
380 | .AP ClientData *handlePtr out | |
381 | Points to the location where the desired OS-specific handle should be | |
382 | stored. | |
383 | .AP int size in | |
384 | The size, in bytes, of buffers to allocate in this channel. | |
385 | .AP int mask in | |
386 | An OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR | |
387 | and \fBTCL_EXCEPTION\fR that indicates events that have occurred on | |
388 | this channel. | |
389 | .AP Tcl_Interp *interp in | |
390 | Current interpreter. (can be NULL) | |
391 | .AP "CONST char" *optionName in | |
392 | Name of the invalid option. | |
393 | .AP "CONST char" *optionList in | |
394 | Specific options list (space separated words, without "-") | |
395 | to append to the standard generic options list. | |
396 | Can be NULL for generic options error message only. | |
397 | ||
398 | .BE | |
399 | ||
400 | .SH DESCRIPTION | |
401 | .PP | |
402 | Tcl uses a two-layered channel architecture. It provides a generic upper | |
403 | layer to enable C and Tcl programs to perform input and output using the | |
404 | same APIs for a variety of files, devices, sockets etc. The generic C APIs | |
405 | are described in the manual entry for \fBTcl_OpenFileChannel\fR. | |
406 | .PP | |
407 | The lower layer provides type-specific channel drivers for each type | |
408 | of device supported on each platform. This manual entry describes the | |
409 | C APIs used to communicate between the generic layer and the | |
410 | type-specific channel drivers. It also explains how new types of | |
411 | channels can be added by providing new channel drivers. | |
412 | .PP | |
413 | Channel drivers consist of a number of components: First, each channel | |
414 | driver provides a \fBTcl_ChannelType\fR structure containing pointers to | |
415 | functions implementing the various operations used by the generic layer to | |
416 | communicate with the channel driver. The \fBTcl_ChannelType\fR structure | |
417 | and the functions referenced by it are described in the section | |
418 | TCL_CHANNELTYPE, below. | |
419 | .PP | |
420 | Second, channel drivers usually provide a Tcl command to create | |
421 | instances of that type of channel. For example, the Tcl \fBopen\fR | |
422 | command creates channels that use the file and command channel | |
423 | drivers, and the Tcl \fBsocket\fR command creates channels that use | |
424 | TCP sockets for network communication. | |
425 | .PP | |
426 | Third, a channel driver optionally provides a C function to open | |
427 | channel instances of that type. For example, \fBTcl_OpenFileChannel\fR | |
428 | opens a channel that uses the file channel driver, and | |
429 | \fBTcl_OpenTcpClient\fR opens a channel that uses the TCP network | |
430 | protocol. These creation functions typically use | |
431 | \fBTcl_CreateChannel\fR internally to open the channel. | |
432 | .PP | |
433 | To add a new type of channel you must implement a C API or a Tcl command | |
434 | that opens a channel by invoking \fBTcl_CreateChannel\fR. | |
435 | When your driver calls \fBTcl_CreateChannel\fR it passes in | |
436 | a \fBTcl_ChannelType\fR structure describing the driver's I/O | |
437 | procedures. | |
438 | The generic layer will then invoke the functions referenced in that | |
439 | structure to perform operations on the channel. | |
440 | .PP | |
441 | \fBTcl_CreateChannel\fR opens a new channel and associates the supplied | |
442 | \fItypePtr\fR and \fIinstanceData\fR with it. The channel is opened in the | |
443 | mode indicated by \fImask\fR. | |
444 | For a discussion of channel drivers, their operations and the | |
445 | \fBTcl_ChannelType\fR structure, see the section TCL_CHANNELTYPE, below. | |
446 | .PP | |
447 | \fBTcl_CreateChannel\fR interacts with the code managing the standard | |
448 | channels. Once a standard channel was initialized either through a | |
449 | call to \fBTcl_GetStdChannel\fR or a call to \fBTcl_SetStdChannel\fR | |
450 | closing this standard channel will cause the next call to | |
451 | \fBTcl_CreateChannel\fR to make the new channel the new standard | |
452 | channel too. See \fBTcl_StandardChannels\fR for a general treatise | |
453 | about standard channels and the behaviour of the Tcl library with | |
454 | regard to them. | |
455 | .PP | |
456 | \fBTcl_GetChannelInstanceData\fR returns the instance data associated with | |
457 | the channel in \fIchannel\fR. This is the same as the \fIinstanceData\fR | |
458 | argument in the call to \fBTcl_CreateChannel\fR that created this channel. | |
459 | .PP | |
460 | \fBTcl_GetChannelType\fR returns a pointer to the \fBTcl_ChannelType\fR | |
461 | structure used by the channel in the \fIchannel\fR argument. This is | |
462 | the same as the \fItypePtr\fR argument in the call to | |
463 | \fBTcl_CreateChannel\fR that created this channel. | |
464 | .PP | |
465 | \fBTcl_GetChannelName\fR returns a string containing the name associated | |
466 | with the channel, or NULL if the \fIchannelName\fR argument to | |
467 | \fBTcl_CreateChannel\fR was NULL. | |
468 | .PP | |
469 | \fBTcl_GetChannelHandle\fR places the OS-specific device handle | |
470 | associated with \fIchannel\fR for the given \fIdirection\fR in the | |
471 | location specified by \fIhandlePtr\fR and returns \fBTCL_OK\fR. If | |
472 | the channel does not have a device handle for the specified direction, | |
473 | then \fBTCL_ERROR\fR is returned instead. Different channel drivers | |
474 | will return different types of handle. Refer to the manual entries | |
475 | for each driver to determine what type of handle is returned. | |
476 | .PP | |
477 | .VS 8.4 | |
478 | \fBTcl_GetChannelThread\fR returns the id of the thread currently managing | |
479 | the specified \fIchannel\fR. This allows channel drivers to send their file | |
480 | events to the correct event queue even for a multi-threaded core. | |
481 | .VE 8.4 | |
482 | .PP | |
483 | \fBTcl_GetChannelMode\fR returns an OR-ed combination of \fBTCL_READABLE\fR | |
484 | and \fBTCL_WRITABLE\fR, indicating whether the channel is open for input | |
485 | and output. | |
486 | .PP | |
487 | \fBTcl_GetChannelBufferSize\fR returns the size, in bytes, of buffers | |
488 | allocated to store input or output in \fIchannel\fR. If the value was not set | |
489 | by a previous call to \fBTcl_SetChannelBufferSize\fR, described below, then | |
490 | the default value of 4096 is returned. | |
491 | .PP | |
492 | \fBTcl_SetChannelBufferSize\fR sets the size, in bytes, of buffers that | |
493 | will be allocated in subsequent operations on the channel to store input or | |
494 | output. The \fIsize\fR argument should be between ten and one million, | |
495 | allowing buffers of ten bytes to one million bytes. If \fIsize\fR is | |
496 | outside this range, \fBTcl_SetChannelBufferSize\fR sets the buffer size to | |
497 | 4096. | |
498 | .PP | |
499 | \fBTcl_NotifyChannel\fR is called by a channel driver to indicate to | |
500 | the generic layer that the events specified by \fImask\fR have | |
501 | occurred on the channel. Channel drivers are responsible for invoking | |
502 | this function whenever the channel handlers need to be called for the | |
503 | channel. See \fBWATCHPROC\fR below for more details. | |
504 | .PP | |
505 | \fBTcl_BadChannelOption\fR is called from driver specific set or get option | |
506 | procs to generate a complete error message. | |
507 | .PP | |
508 | \fBTcl_ChannelBuffered\fR returns the number of bytes of input | |
509 | currently buffered in the internal buffer (push back area) of the | |
510 | channel itself. It does not report about the data in the overall | |
511 | buffers for the stack of channels the supplied channel is part of. | |
512 | .PP | |
513 | .VS 8.4 | |
514 | \fBTcl_IsChannelShared\fR checks the refcount of the specified | |
515 | \fIchannel\fR and returns whether the \fIchannel\fR was shared among | |
516 | multiple interpreters (result == 1) or not (result == 0). | |
517 | .PP | |
518 | \fBTcl_IsChannelRegistered\fR checks whether the specified \fIchannel\fR is | |
519 | registered in the given \fIinterp\fRreter (result == 1) or not | |
520 | (result == 0). | |
521 | .PP | |
522 | \fBTcl_IsChannelExisting\fR checks whether a channel with the specified | |
523 | name is registered in the (thread)-global list of all channels (result | |
524 | == 1) or not (result == 0). | |
525 | .PP | |
526 | \fBTcl_CutChannel\fR removes the specified \fIchannel\fR from the | |
527 | (thread)global list of all channels (of the current thread). | |
528 | Application to a channel still registered in some interpreter | |
529 | is not allowed. | |
530 | .VS 8.4 | |
531 | Also notifies the driver if the \fBTcl_ChannelType\fR version is | |
532 | \fBTCL_CHANNEL_VERSION_4\fR (or higher), and | |
533 | \fBTcl_DriverThreadActionProc\fR is defined for it. | |
534 | .VE 8.4 | |
535 | .PP | |
536 | \fBTcl_SpliceChannel\fR adds the specified \fIchannel\fR to the | |
537 | (thread)global list of all channels (of the current thread). | |
538 | Application to a channel registered in some interpreter is not allowed. | |
539 | .VS 8.4 | |
540 | Also notifies the driver if the \fBTcl_ChannelType\fR version is | |
541 | \fBTCL_CHANNEL_VERSION_4\fR (or higher), and | |
542 | \fBTcl_DriverThreadActionProc\fR is defined for it. | |
543 | .VE 8.4 | |
544 | .PP | |
545 | \fBTcl_ClearChannelHandlers\fR removes all channelhandlers and event | |
546 | scripts associated with the specified \fIchannel\fR, thus shutting | |
547 | down all event processing for this channel. | |
548 | .VE 8.4 | |
549 | ||
550 | .SH TCL_CHANNELTYPE | |
551 | .PP | |
552 | A channel driver provides a \fBTcl_ChannelType\fR structure that contains | |
553 | pointers to functions that implement the various operations on a channel; | |
554 | these operations are invoked as needed by the generic layer. The structure | |
555 | was versioned starting in Tcl 8.3.2/8.4 to correct a problem with stacked | |
556 | channel drivers. See the \fBOLD CHANNEL TYPES\fR section below for | |
557 | details about the old structure. | |
558 | .PP | |
559 | The \fBTcl_ChannelType\fR structure contains the following fields: | |
560 | .CS | |
561 | typedef struct Tcl_ChannelType { | |
562 | char *\fItypeName\fR; | |
563 | Tcl_ChannelTypeVersion \fIversion\fR; | |
564 | Tcl_DriverCloseProc *\fIcloseProc\fR; | |
565 | Tcl_DriverInputProc *\fIinputProc\fR; | |
566 | Tcl_DriverOutputProc *\fIoutputProc\fR; | |
567 | Tcl_DriverSeekProc *\fIseekProc\fR; | |
568 | Tcl_DriverSetOptionProc *\fIsetOptionProc\fR; | |
569 | Tcl_DriverGetOptionProc *\fIgetOptionProc\fR; | |
570 | Tcl_DriverWatchProc *\fIwatchProc\fR; | |
571 | Tcl_DriverGetHandleProc *\fIgetHandleProc\fR; | |
572 | Tcl_DriverClose2Proc *\fIclose2Proc\fR; | |
573 | Tcl_DriverBlockModeProc *\fIblockModeProc\fR; | |
574 | Tcl_DriverFlushProc *\fIflushProc\fR; | |
575 | Tcl_DriverHandlerProc *\fIhandlerProc\fR; | |
576 | Tcl_DriverWideSeekProc *\fIwideSeekProc\fR; | |
577 | Tcl_DriverThreadActionProc *\fIthreadActionProc\fR; | |
578 | } Tcl_ChannelType; | |
579 | .CE | |
580 | .PP | |
581 | The driver must provide implementations for all functions except | |
582 | \fIblockModeProc\fR, \fIseekProc\fR, \fIsetOptionProc\fR, | |
583 | \fIgetOptionProc\fR, and \fIclose2Proc\fR, which may be specified as | |
584 | NULL. Other functions that can not be implemented for this type of | |
585 | device should return \fBEINVAL\fR when invoked to indicate that they | |
586 | are not implemented, except in the case of \fIflushProc\fR and | |
587 | \fIhandlerProc\fR, which should specified as NULL if not otherwise defined. | |
588 | .PP | |
589 | The user should only use the above structure for \fBTcl_ChannelType\fR | |
590 | instantiation. When referencing fields in a \fBTcl_ChannelType\fR | |
591 | structure, the following functions should be used to obtain the values: | |
592 | \fBTcl_ChannelName\fR, \fBTcl_ChannelVersion\fR, | |
593 | \fBTcl_ChannelBlockModeProc\fR, \fBTcl_ChannelCloseProc\fR, | |
594 | \fBTcl_ChannelClose2Proc\fR, \fBTcl_ChannelInputProc\fR, | |
595 | \fBTcl_ChannelOutputProc\fR, \fBTcl_ChannelSeekProc\fR, | |
596 | .VS 8.4 | |
597 | \fBTcl_ChannelWideSeekProc\fR, | |
598 | \fBTcl_ChannelThreadActionProc\fR, | |
599 | .VE 8.4 | |
600 | \fBTcl_ChannelSetOptionProc\fR, \fBTcl_ChannelGetOptionProc\fR, | |
601 | \fBTcl_ChannelWatchProc\fR, \fBTcl_ChannelGetHandleProc\fR, | |
602 | \fBTcl_ChannelFlushProc\fR, or \fBTcl_ChannelHandlerProc\fR. | |
603 | .PP | |
604 | The change to the structures was made in such a way that standard channel | |
605 | types are binary compatible. However, channel types that use stacked | |
606 | channels (ie: TLS, Trf) have new versions to correspond to the above change | |
607 | since the previous code for stacked channels had problems. | |
608 | ||
609 | .SH TYPENAME | |
610 | .PP | |
611 | The \fItypeName\fR field contains a null-terminated string that | |
612 | identifies the type of the device implemented by this driver, e.g. | |
613 | \fBfile\fR or \fBsocket\fR. | |
614 | .PP | |
615 | This value can be retrieved with \fBTcl_ChannelName\fR, which returns | |
616 | a pointer to the string. | |
617 | ||
618 | .SH VERSION | |
619 | .PP | |
620 | ||
621 | The \fIversion\fR field should be set to the version of the structure | |
622 | that you require. \fBTCL_CHANNEL_VERSION_2\fR is the minimum recommended. | |
623 | .VS 8.4 | |
624 | \fBTCL_CHANNEL_VERSION_3\fR must be set to specifiy the \fIwideSeekProc\fR member. | |
625 | .VE 8.4 | |
626 | .VS 8.4 | |
627 | \fBTCL_CHANNEL_VERSION_4\fR must be set to specifiy the | |
628 | \fIthreadActionProc\fR member (includes \fIwideSeekProc\fR). | |
629 | .VE 8.4 | |
630 | If it is not set to any of these, then this | |
631 | \fBTcl_ChannelType\fR is assumed to have the original structure. See | |
632 | \fBOLD CHANNEL TYPES\fR for more details. While Tcl will recognize | |
633 | and function with either structures, stacked channels must be of at | |
634 | least \fBTCL_CHANNEL_VERSION_2\fR to function correctly. | |
635 | .PP | |
636 | This value can be retrieved with \fBTcl_ChannelVersion\fR, which returns | |
637 | .VS 8.4 | |
638 | one of \fBTCL_CHANNEL_VERSION_4\fR, \fBTCL_CHANNEL_VERSION_3\fR, | |
639 | .VE 8.4 | |
640 | \fBTCL_CHANNEL_VERSION_2\fR, or \fBTCL_CHANNEL_VERSION_1\fR. | |
641 | ||
642 | .SH BLOCKMODEPROC | |
643 | .PP | |
644 | The \fIblockModeProc\fR field contains the address of a function called by | |
645 | the generic layer to set blocking and nonblocking mode on the device. | |
646 | \fIBlockModeProc\fR should match the following prototype: | |
647 | .PP | |
648 | .CS | |
649 | typedef int Tcl_DriverBlockModeProc( | |
650 | ClientData \fIinstanceData\fR, | |
651 | int \fImode\fR); | |
652 | .CE | |
653 | .PP | |
654 | The \fIinstanceData\fR is the same as the value passed to | |
655 | \fBTcl_CreateChannel\fR when this channel was created. The \fImode\fR | |
656 | argument is either \fBTCL_MODE_BLOCKING\fR or \fBTCL_MODE_NONBLOCKING\fR to | |
657 | set the device into blocking or nonblocking mode. The function should | |
658 | return zero if the operation was successful, or a nonzero POSIX error code | |
659 | if the operation failed. | |
660 | .PP | |
661 | If the operation is successful, the function can modify the supplied | |
662 | \fIinstanceData\fR to record that the channel entered blocking or | |
663 | nonblocking mode and to implement the blocking or nonblocking behavior. | |
664 | For some device types, the blocking and nonblocking behavior can be | |
665 | implemented by the underlying operating system; for other device types, the | |
666 | behavior must be emulated in the channel driver. | |
667 | .PP | |
668 | This value can be retrieved with \fBTcl_ChannelBlockModeProc\fR, which returns | |
669 | a pointer to the function. | |
670 | .PP | |
671 | A channel driver \fBnot\fR supplying a \fIblockModeProc\fR has to be | |
672 | very, very careful. It has to tell the generic layer exactly which | |
673 | blocking mode is acceptable to it, and should this also document for | |
674 | the user so that the blocking mode of the channel is not changed to an | |
675 | inacceptable value. Any confusion here may lead the interpreter into a | |
676 | (spurious and difficult to find) deadlock. | |
677 | ||
678 | ||
679 | .SH "CLOSEPROC AND CLOSE2PROC" | |
680 | .PP | |
681 | The \fIcloseProc\fR field contains the address of a function called by the | |
682 | generic layer to clean up driver-related information when the channel is | |
683 | closed. \fICloseProc\fR must match the following prototype: | |
684 | .PP | |
685 | .CS | |
686 | typedef int Tcl_DriverCloseProc( | |
687 | ClientData \fIinstanceData\fR, | |
688 | Tcl_Interp *\fIinterp\fR); | |
689 | .CE | |
690 | .PP | |
691 | The \fIinstanceData\fR argument is the same as the value provided to | |
692 | \fBTcl_CreateChannel\fR when the channel was created. The function should | |
693 | release any storage maintained by the channel driver for this channel, and | |
694 | close the input and output devices encapsulated by this channel. All queued | |
695 | output will have been flushed to the device before this function is called, | |
696 | and no further driver operations will be invoked on this instance after | |
697 | calling the \fIcloseProc\fR. If the close operation is successful, the | |
698 | procedure should return zero; otherwise it should return a nonzero POSIX | |
699 | error code. In addition, if an error occurs and \fIinterp\fR is not NULL, | |
700 | the procedure should store an error message in the interpreter's result. | |
701 | .PP | |
702 | Alternatively, channels that support closing the read and write sides | |
703 | independently may set \fIcloseProc\fR to \fBTCL_CLOSE2PROC\fR and set | |
704 | \fIclose2Proc\fR to the address of a function that matches the | |
705 | following prototype: | |
706 | .PP | |
707 | .CS | |
708 | typedef int Tcl_DriverClose2Proc( | |
709 | ClientData \fIinstanceData\fR, | |
710 | Tcl_Interp *\fIinterp\fR, | |
711 | int \fIflags\fR); | |
712 | .CE | |
713 | .PP | |
714 | The \fIclose2Proc\fR will be called with \fIflags\fR set to an OR'ed | |
715 | combination of \fBTCL_CLOSE_READ\fR or \fBTCL_CLOSE_WRITE\fR to | |
716 | indicate that the driver should close the read and/or write side of | |
717 | the channel. The channel driver may be invoked to perform | |
718 | additional operations on the channel after \fIclose2Proc\fR is | |
719 | called to close one or both sides of the channel. If \fIflags\fR is | |
720 | \fB0\fR (zero), the driver should close the channel in the manner | |
721 | described above for \fIcloseProc\fR. No further operations will be | |
722 | invoked on this instance after \fIclose2Proc\fR is called with all | |
723 | flags cleared. In all cases, the \fIclose2Proc\fR function should | |
724 | return zero if the close operation was successful; otherwise it should | |
725 | return a nonzero POSIX error code. In addition, if an error occurs and | |
726 | \fIinterp\fR is not NULL, the procedure should store an error message | |
727 | in the interpreter's result. | |
728 | .PP | |
729 | These value can be retrieved with \fBTcl_ChannelCloseProc\fR or | |
730 | \fBTcl_ChannelClose2Proc\fR, which returns a pointer to the respective | |
731 | function. | |
732 | ||
733 | .SH INPUTPROC | |
734 | .PP | |
735 | The \fIinputProc\fR field contains the address of a function called by the | |
736 | generic layer to read data from the file or device and store it in an | |
737 | internal buffer. \fIInputProc\fR must match the following prototype: | |
738 | .PP | |
739 | .CS | |
740 | typedef int Tcl_DriverInputProc( | |
741 | ClientData \fIinstanceData\fR, | |
742 | char *\fIbuf\fR, | |
743 | int \fIbufSize\fR, | |
744 | int *\fIerrorCodePtr\fR); | |
745 | .CE | |
746 | .PP | |
747 | \fIInstanceData\fR is the same as the value passed to | |
748 | \fBTcl_CreateChannel\fR when the channel was created. The \fIbuf\fR | |
749 | argument points to an array of bytes in which to store input from the | |
750 | device, and the \fIbufSize\fR argument indicates how many bytes are | |
751 | available at \fIbuf\fR. | |
752 | .PP | |
753 | The \fIerrorCodePtr\fR argument points to an integer variable provided by | |
754 | the generic layer. If an error occurs, the function should set the variable | |
755 | to a POSIX error code that identifies the error that occurred. | |
756 | .PP | |
757 | The function should read data from the input device encapsulated by the | |
758 | channel and store it at \fIbuf\fR. On success, the function should return | |
759 | a nonnegative integer indicating how many bytes were read from the input | |
760 | device and stored at \fIbuf\fR. On error, the function should return -1. If | |
761 | an error occurs after some data has been read from the device, that data is | |
762 | lost. | |
763 | .PP | |
764 | If \fIinputProc\fR can determine that the input device has some data | |
765 | available but less than requested by the \fIbufSize\fR argument, the | |
766 | function should only attempt to read as much data as is available and | |
767 | return without blocking. If the input device has no data available | |
768 | whatsoever and the channel is in nonblocking mode, the function should | |
769 | return an \fBEAGAIN\fR error. If the input device has no data available | |
770 | whatsoever and the channel is in blocking mode, the function should block | |
771 | for the shortest possible time until at least one byte of data can be read | |
772 | from the device; then, it should return as much data as it can read without | |
773 | blocking. | |
774 | .PP | |
775 | This value can be retrieved with \fBTcl_ChannelInputProc\fR, which returns | |
776 | a pointer to the function. | |
777 | ||
778 | .SH OUTPUTPROC | |
779 | .PP | |
780 | The \fIoutputProc\fR field contains the address of a function called by the | |
781 | generic layer to transfer data from an internal buffer to the output device. | |
782 | \fIOutputProc\fR must match the following prototype: | |
783 | .PP | |
784 | .CS | |
785 | typedef int Tcl_DriverOutputProc( | |
786 | ClientData \fIinstanceData\fR, | |
787 | CONST char *\fIbuf\fR, | |
788 | int \fItoWrite\fR, | |
789 | int *\fIerrorCodePtr\fR); | |
790 | .CE | |
791 | .PP | |
792 | \fIInstanceData\fR is the same as the value passed to | |
793 | \fBTcl_CreateChannel\fR when the channel was created. The \fIbuf\fR | |
794 | argument contains an array of bytes to be written to the device, and the | |
795 | \fItoWrite\fR argument indicates how many bytes are to be written from the | |
796 | \fIbuf\fR argument. | |
797 | .PP | |
798 | The \fIerrorCodePtr\fR argument points to an integer variable provided by | |
799 | the generic layer. If an error occurs, the function should set this | |
800 | variable to a POSIX error code that identifies the error. | |
801 | .PP | |
802 | The function should write the data at \fIbuf\fR to the output device | |
803 | encapsulated by the channel. On success, the function should return a | |
804 | nonnegative integer indicating how many bytes were written to the output | |
805 | device. The return value is normally the same as \fItoWrite\fR, but may be | |
806 | less in some cases such as if the output operation is interrupted by a | |
807 | signal. If an error occurs the function should return -1. In case of | |
808 | error, some data may have been written to the device. | |
809 | .PP | |
810 | If the channel is nonblocking and the output device is unable to absorb any | |
811 | data whatsoever, the function should return -1 with an \fBEAGAIN\fR error | |
812 | without writing any data. | |
813 | .PP | |
814 | This value can be retrieved with \fBTcl_ChannelOutputProc\fR, which returns | |
815 | a pointer to the function. | |
816 | ||
817 | .SH "SEEKPROC AND WIDESEEKPROC" | |
818 | .PP | |
819 | The \fIseekProc\fR field contains the address of a function called by the | |
820 | generic layer to move the access point at which subsequent input or output | |
821 | operations will be applied. \fISeekProc\fR must match the following | |
822 | prototype: | |
823 | .PP | |
824 | .CS | |
825 | typedef int Tcl_DriverSeekProc( | |
826 | ClientData \fIinstanceData\fR, | |
827 | long \fIoffset\fR, | |
828 | int \fIseekMode\fR, | |
829 | int *\fIerrorCodePtr\fR); | |
830 | .CE | |
831 | .PP | |
832 | The \fIinstanceData\fR argument is the same as the value given to | |
833 | \fBTcl_CreateChannel\fR when this channel was created. \fIOffset\fR and | |
834 | \fIseekMode\fR have the same meaning as for the \fBTcl_Seek\fR | |
835 | procedure (described in the manual entry for \fBTcl_OpenFileChannel\fR). | |
836 | .PP | |
837 | The \fIerrorCodePtr\fR argument points to an integer variable provided by | |
838 | the generic layer for returning \fBerrno\fR values from the function. The | |
839 | function should set this variable to a POSIX error code if an error occurs. | |
840 | The function should store an \fBEINVAL\fR error code if the channel type | |
841 | does not implement seeking. | |
842 | .PP | |
843 | The return value is the new access point or -1 in case of error. If an | |
844 | error occurred, the function should not move the access point. | |
845 | .PP | |
846 | .VS 8.4 | |
847 | If there is a non-NULL \fIseekProc\fR field, the \fIwideSeekProc\fR | |
848 | field may contain the address of an alternative function to use which | |
849 | handles wide (i.e. larger than 32-bit) offsets, so allowing seeks | |
850 | within files larger than 2GB. The \fIwideSeekProc\fR will be called | |
851 | in preference to the \fIseekProc\fR, but both must be defined if the | |
852 | \fIwideSeekProc\fR is defined. \fIWideSeekProc\fR must match the | |
853 | following prototype: | |
854 | .PP | |
855 | .CS | |
856 | typedef Tcl_WideInt Tcl_DriverWideSeekProc( | |
857 | ClientData \fIinstanceData\fR, | |
858 | Tcl_WideInt \fIoffset\fR, | |
859 | int \fIseekMode\fR, | |
860 | int *\fIerrorCodePtr\fR); | |
861 | .CE | |
862 | .PP | |
863 | The arguments and return values mean the same thing as with | |
864 | \fIseekProc\fR above, except that the type of offsets and the return | |
865 | type are different. | |
866 | .PP | |
867 | The \fIseekProc\fR value can be retrieved with | |
868 | \fBTcl_ChannelSeekProc\fR, which returns a pointer to the function, | |
869 | and similarly the \fIwideSeekProc\fR can be retrieved with | |
870 | \fBTcl_ChannelWideSeekProc\fR. | |
871 | .VE 8.4 | |
872 | ||
873 | .SH SETOPTIONPROC | |
874 | .PP | |
875 | The \fIsetOptionProc\fR field contains the address of a function called by | |
876 | the generic layer to set a channel type specific option on a channel. | |
877 | \fIsetOptionProc\fR must match the following prototype: | |
878 | .PP | |
879 | .CS | |
880 | typedef int Tcl_DriverSetOptionProc( | |
881 | ClientData \fIinstanceData\fR, | |
882 | Tcl_Interp *\fIinterp\fR, | |
883 | CONST char *\fIoptionName\fR, | |
884 | CONST char *\fInewValue\fR); | |
885 | .CE | |
886 | .PP | |
887 | \fIoptionName\fR is the name of an option to set, and \fInewValue\fR is | |
888 | the new value for that option, as a string. The \fIinstanceData\fR is the | |
889 | same as the value given to \fBTcl_CreateChannel\fR when this channel was | |
890 | created. The function should do whatever channel type specific action is | |
891 | required to implement the new value of the option. | |
892 | .PP | |
893 | Some options are handled by the generic code and this function is never | |
894 | called to set them, e.g. \fB-blockmode\fR. Other options are specific to | |
895 | each channel type and the \fIsetOptionProc\fR procedure of the channel | |
896 | driver will get called to implement them. The \fIsetOptionProc\fR field can | |
897 | be NULL, which indicates that this channel type supports no type specific | |
898 | options. | |
899 | .PP | |
900 | If the option value is successfully modified to the new value, the function | |
901 | returns \fBTCL_OK\fR. | |
902 | It should call \fBTcl_BadChannelOption\fR which itself returns | |
903 | \fBTCL_ERROR\fR if the \fIoptionName\fR is | |
904 | unrecognized. | |
905 | If \fInewValue\fR specifies a value for the option that | |
906 | is not supported or if a system call error occurs, | |
907 | the function should leave an error message in the | |
908 | \fIresult\fR field of \fIinterp\fR if \fIinterp\fR is not NULL. The | |
909 | function should also call \fBTcl_SetErrno\fR to store an appropriate POSIX | |
910 | error code. | |
911 | .PP | |
912 | This value can be retrieved with \fBTcl_ChannelSetOptionProc\fR, which returns | |
913 | a pointer to the function. | |
914 | ||
915 | .SH GETOPTIONPROC | |
916 | .PP | |
917 | The \fIgetOptionProc\fR field contains the address of a function called by | |
918 | the generic layer to get the value of a channel type specific option on a | |
919 | channel. \fIgetOptionProc\fR must match the following prototype: | |
920 | .PP | |
921 | .CS | |
922 | typedef int Tcl_DriverGetOptionProc( | |
923 | ClientData \fIinstanceData\fR, | |
924 | Tcl_Interp *\fIinterp\fR, | |
925 | CONST char *\fIoptionName\fR, | |
926 | Tcl_DString *\fIoptionValue\fR); | |
927 | .CE | |
928 | .PP | |
929 | \fIOptionName\fR is the name of an option supported by this type of | |
930 | channel. If the option name is not NULL, the function stores its current | |
931 | value, as a string, in the Tcl dynamic string \fIoptionValue\fR. | |
932 | If \fIoptionName\fR is NULL, the function stores in \fIoptionValue\fR an | |
933 | alternating list of all supported options and their current values. | |
934 | On success, the function returns \fBTCL_OK\fR. | |
935 | It should call \fBTcl_BadChannelOption\fR which itself returns | |
936 | \fBTCL_ERROR\fR if the \fIoptionName\fR is | |
937 | unrecognized. If a system call error occurs, | |
938 | the function should leave an error message in the | |
939 | result of \fIinterp\fR if \fIinterp\fR is not NULL. The | |
940 | function should also call \fBTcl_SetErrno\fR to store an appropriate POSIX | |
941 | error code. | |
942 | .PP | |
943 | Some options are handled by the generic code and this function is never | |
944 | called to retrieve their value, e.g. \fB-blockmode\fR. Other options are | |
945 | specific to each channel type and the \fIgetOptionProc\fR procedure of the | |
946 | channel driver will get called to implement them. The \fIgetOptionProc\fR | |
947 | field can be NULL, which indicates that this channel type supports no type | |
948 | specific options. | |
949 | .PP | |
950 | This value can be retrieved with \fBTcl_ChannelGetOptionProc\fR, which returns | |
951 | a pointer to the function. | |
952 | ||
953 | .SH WATCHPROC | |
954 | .PP | |
955 | The \fIwatchProc\fR field contains the address of a function called | |
956 | by the generic layer to initialize the event notification mechanism to | |
957 | notice events of interest on this channel. | |
958 | \fIWatchProc\fR should match the following prototype: | |
959 | .PP | |
960 | .CS | |
961 | typedef void Tcl_DriverWatchProc( | |
962 | ClientData \fIinstanceData\fR, | |
963 | int \fImask\fR); | |
964 | .CE | |
965 | .PP | |
966 | The \fIinstanceData\fR is the same as the value passed to | |
967 | \fBTcl_CreateChannel\fR when this channel was created. The \fImask\fR | |
968 | argument is an OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR | |
969 | and \fBTCL_EXCEPTION\fR; it indicates events the caller is interested in | |
970 | noticing on this channel. | |
971 | .PP | |
972 | The function should initialize device type specific mechanisms to | |
973 | notice when an event of interest is present on the channel. When one | |
974 | or more of the designated events occurs on the channel, the channel | |
975 | driver is responsible for calling \fBTcl_NotifyChannel\fR to inform | |
976 | the generic channel module. The driver should take care not to starve | |
977 | other channel drivers or sources of callbacks by invoking | |
978 | Tcl_NotifyChannel too frequently. Fairness can be insured by using | |
979 | the Tcl event queue to allow the channel event to be scheduled in sequence | |
980 | with other events. See the description of \fBTcl_QueueEvent\fR for | |
981 | details on how to queue an event. | |
982 | .PP | |
983 | This value can be retrieved with \fBTcl_ChannelWatchProc\fR, which returns | |
984 | a pointer to the function. | |
985 | ||
986 | .SH GETHANDLEPROC | |
987 | .PP | |
988 | The \fIgetHandleProc\fR field contains the address of a function called by | |
989 | the generic layer to retrieve a device-specific handle from the channel. | |
990 | \fIGetHandleProc\fR should match the following prototype: | |
991 | .PP | |
992 | .CS | |
993 | typedef int Tcl_DriverGetHandleProc( | |
994 | ClientData \fIinstanceData\fR, | |
995 | int \fIdirection\fR, | |
996 | ClientData *\fIhandlePtr\fR); | |
997 | .CE | |
998 | .PP | |
999 | \fIInstanceData\fR is the same as the value passed to | |
1000 | \fBTcl_CreateChannel\fR when this channel was created. The \fIdirection\fR | |
1001 | argument is either \fBTCL_READABLE\fR to retrieve the handle used | |
1002 | for input, or \fBTCL_WRITABLE\fR to retrieve the handle used for | |
1003 | output. | |
1004 | .PP | |
1005 | If the channel implementation has device-specific handles, the | |
1006 | function should retrieve the appropriate handle associated with the | |
1007 | channel, according the \fIdirection\fR argument. The handle should be | |
1008 | stored in the location referred to by \fIhandlePtr\fR, and | |
1009 | \fBTCL_OK\fR should be returned. If the channel is not open for the | |
1010 | specified direction, or if the channel implementation does not use | |
1011 | device handles, the function should return \fBTCL_ERROR\fR. | |
1012 | .PP | |
1013 | This value can be retrieved with \fBTcl_ChannelGetHandleProc\fR, which returns | |
1014 | a pointer to the function. | |
1015 | ||
1016 | .SH FLUSHPROC | |
1017 | .PP | |
1018 | The \fIflushProc\fR field is currently reserved for future use. | |
1019 | It should be set to NULL. | |
1020 | \fIFlushProc\fR should match the following prototype: | |
1021 | .PP | |
1022 | .CS | |
1023 | typedef int Tcl_DriverFlushProc( | |
1024 | ClientData \fIinstanceData\fR); | |
1025 | .CE | |
1026 | .PP | |
1027 | This value can be retrieved with \fBTcl_ChannelFlushProc\fR, which returns | |
1028 | a pointer to the function. | |
1029 | ||
1030 | .SH HANDLERPROC | |
1031 | .PP | |
1032 | The \fIhandlerProc\fR field contains the address of a function called by | |
1033 | the generic layer to notify the channel that an event occurred. It should | |
1034 | be defined for stacked channel drivers that wish to be notified of events | |
1035 | that occur on the underlying (stacked) channel. | |
1036 | \fIHandlerProc\fR should match the following prototype: | |
1037 | .PP | |
1038 | .CS | |
1039 | typedef int Tcl_DriverHandlerProc( | |
1040 | ClientData \fIinstanceData\fR, | |
1041 | int \fIinterestMask\fR); | |
1042 | .CE | |
1043 | .PP | |
1044 | \fIInstanceData\fR is the same as the value passed to \fBTcl_CreateChannel\fR | |
1045 | when this channel was created. The \fIinterestMask\fR is an OR-ed | |
1046 | combination of \fBTCL_READABLE\fR or \fBTCL_WRITABLE\fR; it indicates what | |
1047 | type of event occurred on this channel. | |
1048 | .PP | |
1049 | This value can be retrieved with \fBTcl_ChannelHandlerProc\fR, which returns | |
1050 | a pointer to the function. | |
1051 | ||
1052 | .VS 8.4 | |
1053 | .SH "THREADACTIONPROC" | |
1054 | .PP | |
1055 | The \fIthreadActionProc\fR field contains the address of the function | |
1056 | called by the generic layer when a channel is created, closed, or | |
1057 | going to move to a different thread, i.e. whenever thread-specific | |
1058 | driver state might have to initialized or updated. It can be NULL. | |
1059 | The action \fITCL_CHANNEL_THREAD_REMOVE\fR is used to notify the | |
1060 | driver that it should update or remove any thread-specific data it | |
1061 | might be maintaining for the channel. | |
1062 | .PP | |
1063 | The action \fITCL_CHANNEL_THREAD_INSERT\fR is used to notify the | |
1064 | driver that it should update or initialize any thread-specific data it | |
1065 | might be maintaining using the calling thread as the associate. See | |
1066 | \fBTcl_CutChannel\fR and \fBTcl_SpliceChannel\fR for more detail. | |
1067 | .PP | |
1068 | .CS | |
1069 | typedef void Tcl_DriverThreadActionProc( | |
1070 | ClientData \fIinstanceData\fR, | |
1071 | int \fIaction\fR); | |
1072 | .CE | |
1073 | .PP | |
1074 | \fIInstanceData\fR is the same as the value passed to | |
1075 | \fBTcl_CreateChannel\fR when this channel was created. | |
1076 | .PP | |
1077 | These values can be retrieved with \fBTcl_ChannelThreadActionProc\fR, | |
1078 | which returns a pointer to the function. | |
1079 | .VE 8.4 | |
1080 | ||
1081 | .SH TCL_BADCHANNELOPTION | |
1082 | .PP | |
1083 | This procedure generates a "bad option" error message in an | |
1084 | (optional) interpreter. It is used by channel drivers when | |
1085 | a invalid Set/Get option is requested. Its purpose is to concatenate | |
1086 | the generic options list to the specific ones and factorize | |
1087 | the generic options error message string. | |
1088 | .PP | |
1089 | It always return \fBTCL_ERROR\fR | |
1090 | .PP | |
1091 | An error message is generated in \fIinterp\fR's result object to | |
1092 | indicate that a command was invoked with the a bad option | |
1093 | The message has the form | |
1094 | .CS | |
1095 | bad option "blah": should be one of | |
1096 | <...generic options...>+<...specific options...> | |
1097 | so you get for instance: | |
1098 | bad option "-blah": should be one of -blocking, | |
1099 | -buffering, -buffersize, -eofchar, -translation, | |
1100 | -peername, or -sockname | |
1101 | when called with \fIoptionList\fR="peername sockname" | |
1102 | .CE | |
1103 | ``blah'' is the \fIoptionName\fR argument and ``<specific options>'' | |
1104 | is a space separated list of specific option words. | |
1105 | The function takes good care of inserting minus signs before | |
1106 | each option, commas after, and an ``or'' before the last option. | |
1107 | ||
1108 | .SH "OLD CHANNEL TYPES" | |
1109 | ||
1110 | The original (8.3.1 and below) \fBTcl_ChannelType\fR structure contains | |
1111 | the following fields: | |
1112 | .PP | |
1113 | .CS | |
1114 | typedef struct Tcl_ChannelType { | |
1115 | char *\fItypeName\fR; | |
1116 | Tcl_DriverBlockModeProc *\fIblockModeProc\fR; | |
1117 | Tcl_DriverCloseProc *\fIcloseProc\fR; | |
1118 | Tcl_DriverInputProc *\fIinputProc\fR; | |
1119 | Tcl_DriverOutputProc *\fIoutputProc\fR; | |
1120 | Tcl_DriverSeekProc *\fIseekProc\fR; | |
1121 | Tcl_DriverSetOptionProc *\fIsetOptionProc\fR; | |
1122 | Tcl_DriverGetOptionProc *\fIgetOptionProc\fR; | |
1123 | Tcl_DriverWatchProc *\fIwatchProc\fR; | |
1124 | Tcl_DriverGetHandleProc *\fIgetHandleProc\fR; | |
1125 | Tcl_DriverClose2Proc *\fIclose2Proc\fR; | |
1126 | } Tcl_ChannelType; | |
1127 | .CE | |
1128 | .PP | |
1129 | It is still possible to create channel with the above structure. The | |
1130 | internal channel code will determine the version. It is imperative to use | |
1131 | the new \fBTcl_ChannelType\fR structure if you are creating a stacked | |
1132 | channel driver, due to problems with the earlier stacked channel | |
1133 | implementation (in 8.2.0 to 8.3.1). | |
1134 | .PP | |
1135 | .VS 8.4 | |
1136 | Prior to 8.4.0 (i.e. during the later releases of 8.3 and early part | |
1137 | of the 8.4 development cycle) the \fBTcl_ChannelType\fR structure | |
1138 | contained the following fields: | |
1139 | .PP | |
1140 | .CS | |
1141 | typedef struct Tcl_ChannelType { | |
1142 | char *\fItypeName\fR; | |
1143 | Tcl_ChannelTypeVersion \fIversion\fR; | |
1144 | Tcl_DriverCloseProc *\fIcloseProc\fR; | |
1145 | Tcl_DriverInputProc *\fIinputProc\fR; | |
1146 | Tcl_DriverOutputProc *\fIoutputProc\fR; | |
1147 | Tcl_DriverSeekProc *\fIseekProc\fR; | |
1148 | Tcl_DriverSetOptionProc *\fIsetOptionProc\fR; | |
1149 | Tcl_DriverGetOptionProc *\fIgetOptionProc\fR; | |
1150 | Tcl_DriverWatchProc *\fIwatchProc\fR; | |
1151 | Tcl_DriverGetHandleProc *\fIgetHandleProc\fR; | |
1152 | Tcl_DriverClose2Proc *\fIclose2Proc\fR; | |
1153 | Tcl_DriverBlockModeProc *\fIblockModeProc\fR; | |
1154 | Tcl_DriverFlushProc *\fIflushProc\fR; | |
1155 | Tcl_DriverHandlerProc *\fIhandlerProc\fR; | |
1156 | } Tcl_ChannelType; | |
1157 | .CE | |
1158 | .PP | |
1159 | When the above structure is registered as a channel type, the | |
1160 | \fIversion\fR field should always be \fBTCL_CHANNEL_VERSION_2\fR. | |
1161 | .VE 8.4 | |
1162 | ||
1163 | .SH "SEE ALSO" | |
1164 | Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3), Tcl_QueueEvent(3), Tcl_StackChannel(3), Tcl_GetStdChannel(3) | |
1165 | ||
1166 | .SH KEYWORDS | |
1167 | blocking, channel driver, channel registration, channel type, nonblocking |