| 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 |