| 1 | '\" |
| 2 | '\" Copyright (c) 1996-1997 Sun Microsystems, Inc. |
| 3 | '\" |
| 4 | '\" See the file "license.terms" for information on usage and redistribution |
| 5 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
| 6 | '\" |
| 7 | '\" RCS: @(#) $Id: OpenFileChnl.3,v 1.20.2.4 2004/07/16 22:22:15 andreas_kupries Exp $ |
| 8 | '\" The definitions below are for supplemental macros used in Tcl/Tk |
| 9 | '\" manual entries. |
| 10 | '\" |
| 11 | '\" .AP type name in/out ?indent? |
| 12 | '\" Start paragraph describing an argument to a library procedure. |
| 13 | '\" type is type of argument (int, etc.), in/out is either "in", "out", |
| 14 | '\" or "in/out" to describe whether procedure reads or modifies arg, |
| 15 | '\" and indent is equivalent to second arg of .IP (shouldn't ever be |
| 16 | '\" needed; use .AS below instead) |
| 17 | '\" |
| 18 | '\" .AS ?type? ?name? |
| 19 | '\" Give maximum sizes of arguments for setting tab stops. Type and |
| 20 | '\" name are examples of largest possible arguments that will be passed |
| 21 | '\" to .AP later. If args are omitted, default tab stops are used. |
| 22 | '\" |
| 23 | '\" .BS |
| 24 | '\" Start box enclosure. From here until next .BE, everything will be |
| 25 | '\" enclosed in one large box. |
| 26 | '\" |
| 27 | '\" .BE |
| 28 | '\" End of box enclosure. |
| 29 | '\" |
| 30 | '\" .CS |
| 31 | '\" Begin code excerpt. |
| 32 | '\" |
| 33 | '\" .CE |
| 34 | '\" End code excerpt. |
| 35 | '\" |
| 36 | '\" .VS ?version? ?br? |
| 37 | '\" Begin vertical sidebar, for use in marking newly-changed parts |
| 38 | '\" of man pages. The first argument is ignored and used for recording |
| 39 | '\" the version when the .VS was added, so that the sidebars can be |
| 40 | '\" found and removed when they reach a certain age. If another argument |
| 41 | '\" is present, then a line break is forced before starting the sidebar. |
| 42 | '\" |
| 43 | '\" .VE |
| 44 | '\" End of vertical sidebar. |
| 45 | '\" |
| 46 | '\" .DS |
| 47 | '\" Begin an indented unfilled display. |
| 48 | '\" |
| 49 | '\" .DE |
| 50 | '\" End of indented unfilled display. |
| 51 | '\" |
| 52 | '\" .SO |
| 53 | '\" Start of list of standard options for a Tk widget. The |
| 54 | '\" options follow on successive lines, in four columns separated |
| 55 | '\" by tabs. |
| 56 | '\" |
| 57 | '\" .SE |
| 58 | '\" End of list of standard options for a Tk widget. |
| 59 | '\" |
| 60 | '\" .OP cmdName dbName dbClass |
| 61 | '\" Start of description of a specific option. cmdName gives the |
| 62 | '\" option's name as specified in the class command, dbName gives |
| 63 | '\" the option's name in the option database, and dbClass gives |
| 64 | '\" the option's class in the option database. |
| 65 | '\" |
| 66 | '\" .UL arg1 arg2 |
| 67 | '\" Print arg1 underlined, then print arg2 normally. |
| 68 | '\" |
| 69 | '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $ |
| 70 | '\" |
| 71 | '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. |
| 72 | .if t .wh -1.3i ^B |
| 73 | .nr ^l \n(.l |
| 74 | .ad b |
| 75 | '\" # Start an argument description |
| 76 | .de AP |
| 77 | .ie !"\\$4"" .TP \\$4 |
| 78 | .el \{\ |
| 79 | . ie !"\\$2"" .TP \\n()Cu |
| 80 | . el .TP 15 |
| 81 | .\} |
| 82 | .ta \\n()Au \\n()Bu |
| 83 | .ie !"\\$3"" \{\ |
| 84 | \&\\$1 \\fI\\$2\\fP (\\$3) |
| 85 | .\".b |
| 86 | .\} |
| 87 | .el \{\ |
| 88 | .br |
| 89 | .ie !"\\$2"" \{\ |
| 90 | \&\\$1 \\fI\\$2\\fP |
| 91 | .\} |
| 92 | .el \{\ |
| 93 | \&\\fI\\$1\\fP |
| 94 | .\} |
| 95 | .\} |
| 96 | .. |
| 97 | '\" # define tabbing values for .AP |
| 98 | .de AS |
| 99 | .nr )A 10n |
| 100 | .if !"\\$1"" .nr )A \\w'\\$1'u+3n |
| 101 | .nr )B \\n()Au+15n |
| 102 | .\" |
| 103 | .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n |
| 104 | .nr )C \\n()Bu+\\w'(in/out)'u+2n |
| 105 | .. |
| 106 | .AS Tcl_Interp Tcl_CreateInterp in/out |
| 107 | '\" # BS - start boxed text |
| 108 | '\" # ^y = starting y location |
| 109 | '\" # ^b = 1 |
| 110 | .de BS |
| 111 | .br |
| 112 | .mk ^y |
| 113 | .nr ^b 1u |
| 114 | .if n .nf |
| 115 | .if n .ti 0 |
| 116 | .if n \l'\\n(.lu\(ul' |
| 117 | .if n .fi |
| 118 | .. |
| 119 | '\" # BE - end boxed text (draw box now) |
| 120 | .de BE |
| 121 | .nf |
| 122 | .ti 0 |
| 123 | .mk ^t |
| 124 | .ie n \l'\\n(^lu\(ul' |
| 125 | .el \{\ |
| 126 | .\" Draw four-sided box normally, but don't draw top of |
| 127 | .\" box if the box started on an earlier page. |
| 128 | .ie !\\n(^b-1 \{\ |
| 129 | \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
| 130 | .\} |
| 131 | .el \}\ |
| 132 | \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
| 133 | .\} |
| 134 | .\} |
| 135 | .fi |
| 136 | .br |
| 137 | .nr ^b 0 |
| 138 | .. |
| 139 | '\" # VS - start vertical sidebar |
| 140 | '\" # ^Y = starting y location |
| 141 | '\" # ^v = 1 (for troff; for nroff this doesn't matter) |
| 142 | .de VS |
| 143 | .if !"\\$2"" .br |
| 144 | .mk ^Y |
| 145 | .ie n 'mc \s12\(br\s0 |
| 146 | .el .nr ^v 1u |
| 147 | .. |
| 148 | '\" # VE - end of vertical sidebar |
| 149 | .de VE |
| 150 | .ie n 'mc |
| 151 | .el \{\ |
| 152 | .ev 2 |
| 153 | .nf |
| 154 | .ti 0 |
| 155 | .mk ^t |
| 156 | \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' |
| 157 | .sp -1 |
| 158 | .fi |
| 159 | .ev |
| 160 | .\} |
| 161 | .nr ^v 0 |
| 162 | .. |
| 163 | '\" # Special macro to handle page bottom: finish off current |
| 164 | '\" # box/sidebar if in box/sidebar mode, then invoked standard |
| 165 | '\" # page bottom macro. |
| 166 | .de ^B |
| 167 | .ev 2 |
| 168 | 'ti 0 |
| 169 | 'nf |
| 170 | .mk ^t |
| 171 | .if \\n(^b \{\ |
| 172 | .\" Draw three-sided box if this is the box's first page, |
| 173 | .\" draw two sides but no top otherwise. |
| 174 | .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 |
| 175 | .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c |
| 176 | .\} |
| 177 | .if \\n(^v \{\ |
| 178 | .nr ^x \\n(^tu+1v-\\n(^Yu |
| 179 | \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c |
| 180 | .\} |
| 181 | .bp |
| 182 | 'fi |
| 183 | .ev |
| 184 | .if \\n(^b \{\ |
| 185 | .mk ^y |
| 186 | .nr ^b 2 |
| 187 | .\} |
| 188 | .if \\n(^v \{\ |
| 189 | .mk ^Y |
| 190 | .\} |
| 191 | .. |
| 192 | '\" # DS - begin display |
| 193 | .de DS |
| 194 | .RS |
| 195 | .nf |
| 196 | .sp |
| 197 | .. |
| 198 | '\" # DE - end display |
| 199 | .de DE |
| 200 | .fi |
| 201 | .RE |
| 202 | .sp |
| 203 | .. |
| 204 | '\" # SO - start of list of standard options |
| 205 | .de SO |
| 206 | .SH "STANDARD OPTIONS" |
| 207 | .LP |
| 208 | .nf |
| 209 | .ta 5.5c 11c |
| 210 | .ft B |
| 211 | .. |
| 212 | '\" # SE - end of list of standard options |
| 213 | .de SE |
| 214 | .fi |
| 215 | .ft R |
| 216 | .LP |
| 217 | See the \\fBoptions\\fR manual entry for details on the standard options. |
| 218 | .. |
| 219 | '\" # OP - start of full description for a single option |
| 220 | .de OP |
| 221 | .LP |
| 222 | .nf |
| 223 | .ta 4c |
| 224 | Command-Line Name: \\fB\\$1\\fR |
| 225 | Database Name: \\fB\\$2\\fR |
| 226 | Database Class: \\fB\\$3\\fR |
| 227 | .fi |
| 228 | .IP |
| 229 | .. |
| 230 | '\" # CS - begin code excerpt |
| 231 | .de CS |
| 232 | .RS |
| 233 | .nf |
| 234 | .ta .25i .5i .75i 1i |
| 235 | .. |
| 236 | '\" # CE - end code excerpt |
| 237 | .de CE |
| 238 | .fi |
| 239 | .RE |
| 240 | .. |
| 241 | .de UL |
| 242 | \\$1\l'|0\(ul'\\$2 |
| 243 | .. |
| 244 | .TH Tcl_OpenFileChannel 3 8.3 Tcl "Tcl Library Procedures" |
| 245 | .BS |
| 246 | '\" Note: do not modify the .SH NAME line immediately below! |
| 247 | .SH NAME |
| 248 | Tcl_OpenFileChannel, Tcl_OpenCommandChannel, Tcl_MakeFileChannel, Tcl_GetChannel, Tcl_GetChannelNames, Tcl_GetChannelNamesEx, Tcl_RegisterChannel, Tcl_UnregisterChannel, Tcl_DetachChannel, Tcl_IsStandardChannel, Tcl_Close, Tcl_ReadChars, Tcl_Read, Tcl_GetsObj, Tcl_Gets, Tcl_WriteObj, Tcl_WriteChars, Tcl_Write, Tcl_Flush, Tcl_Seek, Tcl_Tell, Tcl_GetChannelOption, Tcl_SetChannelOption, Tcl_Eof, Tcl_InputBlocked, Tcl_InputBuffered, Tcl_OutputBuffered, Tcl_Ungets, Tcl_ReadRaw, Tcl_WriteRaw \- buffered I/O facilities using channels |
| 249 | .SH SYNOPSIS |
| 250 | .nf |
| 251 | \fB#include <tcl.h>\fR |
| 252 | .sp |
| 253 | Tcl_Channel |
| 254 | \fBTcl_OpenFileChannel\fR(\fIinterp, fileName, mode, permissions\fR) |
| 255 | .sp |
| 256 | Tcl_Channel |
| 257 | \fBTcl_OpenCommandChannel\fR(\fIinterp, argc, argv, flags\fR) |
| 258 | .sp |
| 259 | Tcl_Channel |
| 260 | \fBTcl_MakeFileChannel\fR(\fIhandle, readOrWrite\fR) |
| 261 | .sp |
| 262 | Tcl_Channel |
| 263 | \fBTcl_GetChannel\fR(\fIinterp, channelName, modePtr\fR) |
| 264 | .VS 8.3 |
| 265 | .sp |
| 266 | int |
| 267 | \fBTcl_GetChannelNames\fR(\fIinterp\fR) |
| 268 | .sp |
| 269 | int |
| 270 | \fBTcl_GetChannelNamesEx\fR(\fIinterp, pattern\fR) |
| 271 | .VE |
| 272 | .sp |
| 273 | void |
| 274 | \fBTcl_RegisterChannel\fR(\fIinterp, channel\fR) |
| 275 | .sp |
| 276 | int |
| 277 | \fBTcl_UnregisterChannel\fR(\fIinterp, channel\fR) |
| 278 | .sp |
| 279 | int |
| 280 | \fBTcl_DetachChannel\fR(\fIinterp, channel\fR) |
| 281 | .sp |
| 282 | int |
| 283 | \fBTcl_IsStandardChannel\fR(\fIchannel\fR) |
| 284 | .sp |
| 285 | int |
| 286 | \fBTcl_Close\fR(\fIinterp, channel\fR) |
| 287 | .sp |
| 288 | .VS 8.1 |
| 289 | int |
| 290 | \fBTcl_ReadChars\fR(\fIchannel, readObjPtr, charsToRead, appendFlag\fR) |
| 291 | .sp |
| 292 | int |
| 293 | \fBTcl_Read\fR(\fIchannel, readBuf, bytesToRead\fR) |
| 294 | .sp |
| 295 | int |
| 296 | \fBTcl_GetsObj\fR(\fIchannel, lineObjPtr\fR) |
| 297 | .sp |
| 298 | int |
| 299 | \fBTcl_Gets\fR(\fIchannel, lineRead\fR) |
| 300 | .sp |
| 301 | int |
| 302 | \fBTcl_Ungets\fR(\fIchannel, input, inputLen, addAtEnd\fR) |
| 303 | .sp |
| 304 | int |
| 305 | \fBTcl_WriteObj\fR(\fIchannel, writeObjPtr\fR) |
| 306 | .sp |
| 307 | int |
| 308 | \fBTcl_WriteChars\fR(\fIchannel, charBuf, bytesToWrite\fR) |
| 309 | .sp |
| 310 | int |
| 311 | \fBTcl_Write\fR(\fIchannel, byteBuf, bytesToWrite\fR) |
| 312 | .VE |
| 313 | .VS 8.3.2 |
| 314 | .sp |
| 315 | int |
| 316 | \fBTcl_ReadRaw\fR(\fIchannel, readBuf, bytesToRead\fR) |
| 317 | .sp |
| 318 | int |
| 319 | \fBTcl_WriteRaw\fR(\fIchannel, byteBuf, bytesToWrite\fR) |
| 320 | .VE |
| 321 | .sp |
| 322 | int |
| 323 | \fBTcl_Eof\fR(\fIchannel\fR) |
| 324 | .sp |
| 325 | int |
| 326 | \fBTcl_Flush\fR(\fIchannel\fR) |
| 327 | .sp |
| 328 | int |
| 329 | \fBTcl_InputBlocked\fR(\fIchannel\fR) |
| 330 | .sp |
| 331 | int |
| 332 | \fBTcl_InputBuffered\fR(\fIchannel\fR) |
| 333 | .VS 8.4 |
| 334 | .sp |
| 335 | int |
| 336 | \fBTcl_OutputBuffered\fR(\fIchannel\fR) |
| 337 | .VE |
| 338 | .sp |
| 339 | .VS 8.4 |
| 340 | Tcl_WideInt |
| 341 | \fBTcl_Seek\fR(\fIchannel, offset, seekMode\fR) |
| 342 | .sp |
| 343 | Tcl_WideInt |
| 344 | \fBTcl_Tell\fR(\fIchannel\fR) |
| 345 | .VE 8.4 |
| 346 | .sp |
| 347 | int |
| 348 | \fBTcl_GetChannelOption\fR(\fIinterp, channel, optionName, optionValue\fR) |
| 349 | .sp |
| 350 | int |
| 351 | \fBTcl_SetChannelOption\fR(\fIinterp, channel, optionName, newValue\fR) |
| 352 | .sp |
| 353 | .SH ARGUMENTS |
| 354 | .AS Tcl_ChannelType newClientProcPtr in |
| 355 | .AP Tcl_Interp *interp in |
| 356 | Used for error reporting and to look up a channel registered in it. |
| 357 | .AP "CONST char" *fileName in |
| 358 | The name of a local or network file. |
| 359 | .AP "CONST char" *mode in |
| 360 | Specifies how the file is to be accessed. May have any of the values |
| 361 | allowed for the \fImode\fR argument to the Tcl \fBopen\fR command. |
| 362 | .AP int permissions in |
| 363 | POSIX-style permission flags such as 0644. If a new file is created, these |
| 364 | permissions will be set on the created file. |
| 365 | .AP int argc in |
| 366 | The number of elements in \fIargv\fR. |
| 367 | .AP "CONST char" **argv in |
| 368 | Arguments for constructing a command pipeline. These values have the same |
| 369 | meaning as the non-switch arguments to the Tcl \fBexec\fR command. |
| 370 | .AP int flags in |
| 371 | Specifies the disposition of the stdio handles in pipeline: OR-ed |
| 372 | combination of \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, \fBTCL_STDERR\fR, and |
| 373 | \fBTCL_ENFORCE_MODE\fR. If \fBTCL_STDIN\fR is set, stdin for the first child |
| 374 | in the pipe is the pipe channel, otherwise it is the same as the standard |
| 375 | input of the invoking process; likewise for \fBTCL_STDOUT\fR and |
| 376 | \fBTCL_STDERR\fR. If \fBTCL_ENFORCE_MODE\fR is not set, then the pipe can |
| 377 | redirect stdio handles to override the stdio handles for which |
| 378 | \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR and \fBTCL_STDERR\fR have been set. If it |
| 379 | is set, then such redirections cause an error. |
| 380 | .AP ClientData handle in |
| 381 | Operating system specific handle for I/O to a file. For Unix this is a |
| 382 | file descriptor, for Windows it is a HANDLE. |
| 383 | .AP int readOrWrite in |
| 384 | OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR to indicate |
| 385 | what operations are valid on \fIhandle\fR. |
| 386 | .AP "CONST char" *channelName in |
| 387 | The name of the channel. |
| 388 | .AP int *modePtr out |
| 389 | Points at an integer variable that will receive an OR-ed combination of |
| 390 | \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR denoting whether the channel is |
| 391 | open for reading and writing. |
| 392 | .VS 8.3 |
| 393 | .AP "CONST char" *pattern in |
| 394 | The pattern to match on, passed to Tcl_StringMatch, or NULL. |
| 395 | .VE |
| 396 | .AP Tcl_Channel channel in |
| 397 | A Tcl channel for input or output. Must have been the return value |
| 398 | from a procedure such as \fBTcl_OpenFileChannel\fR. |
| 399 | .VS 8.1 br |
| 400 | .AP Tcl_Obj *readObjPtr in/out |
| 401 | A pointer to a Tcl Object in which to store the characters read from the |
| 402 | channel. |
| 403 | .AP int charsToRead in |
| 404 | The number of characters to read from the channel. If the channel's encoding |
| 405 | is \fBbinary\fR, this is equivalent to the number of bytes to read from the |
| 406 | channel. |
| 407 | .AP int appendFlag in |
| 408 | If non-zero, data read from the channel will be appended to the object. |
| 409 | Otherwise, the data will replace the existing contents of the object. |
| 410 | .AP char *readBuf out |
| 411 | A buffer in which to store the bytes read from the channel. |
| 412 | .AP int bytesToRead in |
| 413 | The number of bytes to read from the channel. The buffer \fIreadBuf\fR must |
| 414 | be large enough to hold this many bytes. |
| 415 | .AP Tcl_Obj *lineObjPtr in/out |
| 416 | A pointer to a Tcl object in which to store the line read from the |
| 417 | channel. The line read will be appended to the current value of the |
| 418 | object. |
| 419 | .AP Tcl_DString *lineRead in/out |
| 420 | A pointer to a Tcl dynamic string in which to store the line read from the |
| 421 | channel. Must have been initialized by the caller. The line read will be |
| 422 | appended to any data already in the dynamic string. |
| 423 | .VS 8.3 |
| 424 | .AP "CONST char" *input in |
| 425 | The input to add to a channel buffer. |
| 426 | .AP int inputLen in |
| 427 | Length of the input |
| 428 | .AP int addAtEnd in |
| 429 | Flag indicating whether the input should be added to the end or |
| 430 | beginning of the channel buffer. |
| 431 | .VE |
| 432 | .AP Tcl_Obj *writeObjPtr in |
| 433 | A pointer to a Tcl Object whose contents will be output to the channel. |
| 434 | .AP "CONST char" *charBuf in |
| 435 | A buffer containing the characters to output to the channel. |
| 436 | .AP "CONST char" *byteBuf in |
| 437 | A buffer containing the bytes to output to the channel. |
| 438 | .AP int bytesToWrite in |
| 439 | The number of bytes to consume from \fIcharBuf\fR or \fIbyteBuf\fR and |
| 440 | output to the channel. |
| 441 | .VE |
| 442 | .AP Tcl_WideInt offset in |
| 443 | How far to move the access point in the channel at which the next input or |
| 444 | output operation will be applied, measured in bytes from the position |
| 445 | given by \fIseekMode\fR. May be either positive or negative. |
| 446 | .AP int seekMode in |
| 447 | Relative to which point to seek; used with \fIoffset\fR to calculate the new |
| 448 | access point for the channel. Legal values are \fBSEEK_SET\fR, |
| 449 | \fBSEEK_CUR\fR, and \fBSEEK_END\fR. |
| 450 | .AP "CONST char" *optionName in |
| 451 | The name of an option applicable to this channel, such as \fB\-blocking\fR. |
| 452 | May have any of the values accepted by the \fBfconfigure\fR command. |
| 453 | .AP Tcl_DString *optionValue in |
| 454 | Where to store the value of an option or a list of all options and their |
| 455 | values. Must have been initialized by the caller. |
| 456 | .AP "CONST char" *newValue in |
| 457 | New value for the option given by \fIoptionName\fR. |
| 458 | .BE |
| 459 | |
| 460 | .SH DESCRIPTION |
| 461 | .PP |
| 462 | The Tcl channel mechanism provides a device-independent and |
| 463 | platform-independent mechanism for performing buffered input |
| 464 | and output operations on a variety of file, socket, and device |
| 465 | types. |
| 466 | The channel mechanism is extensible to new channel types, by |
| 467 | providing a low level channel driver for the new type; the channel driver |
| 468 | interface is described in the manual entry for \fBTcl_CreateChannel\fR. The |
| 469 | channel mechanism provides a buffering scheme modeled after |
| 470 | Unix's standard I/O, and it also allows for nonblocking I/O on |
| 471 | channels. |
| 472 | .PP |
| 473 | The procedures described in this manual entry comprise the C APIs of the |
| 474 | generic layer of the channel architecture. For a description of the channel |
| 475 | driver architecture and how to implement channel drivers for new types of |
| 476 | channels, see the manual entry for \fBTcl_CreateChannel\fR. |
| 477 | |
| 478 | .SH TCL_OPENFILECHANNEL |
| 479 | .PP |
| 480 | \fBTcl_OpenFileChannel\fR opens a file specified by \fIfileName\fR and |
| 481 | returns a channel handle that can be used to perform input and output on |
| 482 | the file. This API is modeled after the \fBfopen\fR procedure of |
| 483 | the Unix standard I/O library. |
| 484 | The syntax and meaning of all arguments is similar to those |
| 485 | given in the Tcl \fBopen\fR command when opening a file. |
| 486 | If an error occurs while opening the channel, \fBTcl_OpenFileChannel\fR |
| 487 | returns NULL and records a POSIX error code that can be |
| 488 | retrieved with \fBTcl_GetErrno\fR. |
| 489 | In addition, if \fIinterp\fR is non-NULL, \fBTcl_OpenFileChannel\fR |
| 490 | leaves an error message in \fIinterp\fR's result after any error. |
| 491 | As of Tcl 8.4, the object-based API \fBTcl_FSOpenFileChannel\fR should |
| 492 | be used in preference to \fBTcl_OpenFileChannel\fR wherever possible. |
| 493 | .PP |
| 494 | |
| 495 | .PP |
| 496 | The newly created channel is not registered in the supplied interpreter; to |
| 497 | register it, use \fBTcl_RegisterChannel\fR, described below. |
| 498 | If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was |
| 499 | previously closed, the act of creating the new channel also assigns it as a |
| 500 | replacement for the standard channel. |
| 501 | |
| 502 | .SH TCL_OPENCOMMANDCHANNEL |
| 503 | .PP |
| 504 | \fBTcl_OpenCommandChannel\fR provides a C-level interface to the |
| 505 | functions of the \fBexec\fR and \fBopen\fR commands. |
| 506 | It creates a sequence of subprocesses specified |
| 507 | by the \fIargv\fR and \fIargc\fR arguments and returns a channel that can |
| 508 | be used to communicate with these subprocesses. |
| 509 | The \fIflags\fR argument indicates what sort of communication will |
| 510 | exist with the command pipeline. |
| 511 | .PP |
| 512 | If the \fBTCL_STDIN\fR flag is set then the standard input for the |
| 513 | first subprocess will be tied to the channel: writing to the channel |
| 514 | will provide input to the subprocess. If \fBTCL_STDIN\fR is not set, |
| 515 | then standard input for the first subprocess will be the same as this |
| 516 | application's standard input. If \fBTCL_STDOUT\fR is set then |
| 517 | standard output from the last subprocess can be read from the channel; |
| 518 | otherwise it goes to this application's standard output. If |
| 519 | \fBTCL_STDERR\fR is set, standard error output for all subprocesses is |
| 520 | returned to the channel and results in an error when the channel is |
| 521 | closed; otherwise it goes to this application's standard error. If |
| 522 | \fBTCL_ENFORCE_MODE\fR is not set, then \fIargc\fR and \fIargv\fR can |
| 523 | redirect the stdio handles to override \fBTCL_STDIN\fR, |
| 524 | \fBTCL_STDOUT\fR, and \fBTCL_STDERR\fR; if it is set, then it is an |
| 525 | error for argc and argv to override stdio channels for which |
| 526 | \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, and \fBTCL_STDERR\fR have been set. |
| 527 | .PP |
| 528 | If an error occurs while opening the channel, \fBTcl_OpenCommandChannel\fR |
| 529 | returns NULL and records a POSIX error code that can be retrieved with |
| 530 | \fBTcl_GetErrno\fR. |
| 531 | In addition, \fBTcl_OpenCommandChannel\fR leaves an error message in |
| 532 | the interpreter's result if \fIinterp\fR is not NULL. |
| 533 | .PP |
| 534 | The newly created channel is not registered in the supplied interpreter; to |
| 535 | register it, use \fBTcl_RegisterChannel\fR, described below. |
| 536 | If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was |
| 537 | previously closed, the act of creating the new channel also assigns it as a |
| 538 | replacement for the standard channel. |
| 539 | |
| 540 | .SH TCL_MAKEFILECHANNEL |
| 541 | .PP |
| 542 | \fBTcl_MakeFileChannel\fR makes a \fBTcl_Channel\fR from an existing, |
| 543 | platform-specific, file handle. |
| 544 | The newly created channel is not registered in the supplied interpreter; to |
| 545 | register it, use \fBTcl_RegisterChannel\fR, described below. |
| 546 | If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was |
| 547 | previously closed, the act of creating the new channel also assigns it as a |
| 548 | replacement for the standard channel. |
| 549 | |
| 550 | .SH TCL_GETCHANNEL |
| 551 | .PP |
| 552 | \fBTcl_GetChannel\fR returns a channel given the \fIchannelName\fR used to |
| 553 | create it with \fBTcl_CreateChannel\fR and a pointer to a Tcl interpreter in |
| 554 | \fIinterp\fR. If a channel by that name is not registered in that interpreter, |
| 555 | the procedure returns NULL. If the \fImodePtr\fR argument is not NULL, it |
| 556 | points at an integer variable that will receive an OR-ed combination of |
| 557 | \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR describing whether the channel is |
| 558 | open for reading and writing. |
| 559 | .PP |
| 560 | \fBTcl_GetChannelNames\fR and \fBTcl_GetChannelNamesEx\fR write the |
| 561 | names of the registered channels to the interpreter's result as a |
| 562 | list object. \fBTcl_GetChannelNamesEx\fR will filter these names |
| 563 | according to the \fIpattern\fR. If \fIpattern\fR is NULL, then it |
| 564 | will not do any filtering. The return value is \fBTCL_OK\fR if no |
| 565 | errors occurred writing to the result, otherwise it is \fBTCL_ERROR\fR, |
| 566 | and the error message is left in the interpreter's result. |
| 567 | |
| 568 | .SH TCL_REGISTERCHANNEL |
| 569 | .PP |
| 570 | \fBTcl_RegisterChannel\fR adds a channel to the set of channels accessible |
| 571 | in \fIinterp\fR. After this call, Tcl programs executing in that |
| 572 | interpreter can refer to the channel in input or output operations using |
| 573 | the name given in the call to \fBTcl_CreateChannel\fR. After this call, |
| 574 | the channel becomes the property of the interpreter, and the caller should |
| 575 | not call \fBTcl_Close\fR for the channel; the channel will be closed |
| 576 | automatically when it is unregistered from the interpreter. |
| 577 | .PP |
| 578 | Code executing outside of any Tcl interpreter can call |
| 579 | \fBTcl_RegisterChannel\fR with \fIinterp\fR as NULL, to indicate that it |
| 580 | wishes to hold a reference to this channel. Subsequently, the channel can |
| 581 | be registered in a Tcl interpreter and it will only be closed when the |
| 582 | matching number of calls to \fBTcl_UnregisterChannel\fR have been made. |
| 583 | This allows code executing outside of any interpreter to safely hold a |
| 584 | reference to a channel that is also registered in a Tcl interpreter. |
| 585 | .PP |
| 586 | This procedure interacts with the code managing the standard |
| 587 | channels. If no standard channels were initialized before the first |
| 588 | call to \fBTcl_RegisterChannel\fR they will get initialized by that |
| 589 | call. See \fBTcl_StandardChannels\fR for a general treatise about |
| 590 | standard channels and the behaviour of the Tcl library with regard to |
| 591 | them. |
| 592 | |
| 593 | .SH TCL_UNREGISTERCHANNEL |
| 594 | .PP |
| 595 | \fBTcl_UnregisterChannel\fR removes a channel from the set of channels |
| 596 | accessible in \fIinterp\fR. After this call, Tcl programs will no longer be |
| 597 | able to use the channel's name to refer to the channel in that interpreter. |
| 598 | If this operation removed the last registration of the channel in any |
| 599 | interpreter, the channel is also closed and destroyed. |
| 600 | .PP |
| 601 | Code not associated with a Tcl interpreter can call |
| 602 | \fBTcl_UnregisterChannel\fR with \fIinterp\fR as NULL, to indicate to Tcl |
| 603 | that it no longer holds a reference to that channel. If this is the last |
| 604 | reference to the channel, it will now be closed. \fBTcl_UnregisterChannel\fR |
| 605 | is very similar to \fBTcl_DetachChannel\fR except that it will also |
| 606 | close the channel if no further references to it exist. |
| 607 | |
| 608 | .SH TCL_DETACHCHANNEL |
| 609 | .PP |
| 610 | \fBTcl_DetachChannel\fR removes a channel from the set of channels |
| 611 | accessible in \fIinterp\fR. After this call, Tcl programs will no longer be |
| 612 | able to use the channel's name to refer to the channel in that interpreter. |
| 613 | Beyond that, this command has no further effect. It cannot be used on |
| 614 | the standard channels (stdout, stderr, stdin), and will return |
| 615 | TCL_ERROR if passed one of those channels. |
| 616 | .PP |
| 617 | Code not associated with a Tcl interpreter can call |
| 618 | \fBTcl_DetachChannel\fR with \fIinterp\fR as NULL, to indicate to Tcl |
| 619 | that it no longer holds a reference to that channel. If this is the last |
| 620 | reference to the channel, unlike \fBTcl_UnregisterChannel\fR, |
| 621 | it will not be closed. |
| 622 | |
| 623 | .SH TCL_ISSTANDARDCHANNEL |
| 624 | .PP |
| 625 | \fBTcl_IsStandardChannel\fR tests whether a channel is one of the |
| 626 | three standard channels, stdin, stdout or stderr. If so, it returns |
| 627 | 1, otherwise 0. |
| 628 | .PP |
| 629 | No attempt is made to check whether the given channel or the standard |
| 630 | channels are initialized or otherwise valid. |
| 631 | |
| 632 | .SH TCL_CLOSE |
| 633 | .PP |
| 634 | \fBTcl_Close\fR destroys the channel \fIchannel\fR, which must denote a |
| 635 | currently open channel. The channel should not be registered in any |
| 636 | interpreter when \fBTcl_Close\fR is called. Buffered output is flushed to |
| 637 | the channel's output device prior to destroying the channel, and any |
| 638 | buffered input is discarded. If this is a blocking channel, the call does |
| 639 | not return until all buffered data is successfully sent to the channel's |
| 640 | output device. If this is a nonblocking channel and there is buffered |
| 641 | output that cannot be written without blocking, the call returns |
| 642 | immediately; output is flushed in the background and the channel will be |
| 643 | closed once all of the buffered data has been output. In this case errors |
| 644 | during flushing are not reported. |
| 645 | .PP |
| 646 | If the channel was closed successfully, \fBTcl_Close\fR returns \fBTCL_OK\fR. |
| 647 | If an error occurs, \fBTcl_Close\fR returns \fBTCL_ERROR\fR and records a |
| 648 | POSIX error code that can be retrieved with \fBTcl_GetErrno\fR. |
| 649 | If the channel is being closed synchronously and an error occurs during |
| 650 | closing of the channel and \fIinterp\fR is not NULL, an error message is |
| 651 | left in the interpreter's result. |
| 652 | .PP |
| 653 | Note: it is not safe to call \fBTcl_Close\fR on a channel that has been |
| 654 | registered using \fBTcl_RegisterChannel\fR; see the documentation for |
| 655 | \fBTcl_RegisterChannel\fR, above, for details. If the channel has ever |
| 656 | been given as the \fBchan\fR argument in a call to |
| 657 | \fBTcl_RegisterChannel\fR, you should instead use |
| 658 | \fBTcl_UnregisterChannel\fR, which will internally call \fBTcl_Close\fR |
| 659 | when all calls to \fBTcl_RegisterChannel\fR have been matched by |
| 660 | corresponding calls to \fBTcl_UnregisterChannel\fR. |
| 661 | |
| 662 | .VS 8.1 br |
| 663 | .SH "TCL_READCHARS AND TCL_READ" |
| 664 | .PP |
| 665 | \fBTcl_ReadChars\fR consumes bytes from \fIchannel\fR, converting the bytes |
| 666 | to UTF-8 based on the channel's encoding and storing the produced data in |
| 667 | \fIreadObjPtr\fR's string representation. The return value of |
| 668 | \fBTcl_ReadChars\fR is the number of characters, up to \fIcharsToRead\fR, |
| 669 | that were stored in \fIreadObjPtr\fR. If an error occurs while reading, the |
| 670 | return value is \-1 and \fBTcl_ReadChars\fR records a POSIX error code that |
| 671 | can be retrieved with \fBTcl_GetErrno\fR. |
| 672 | .PP |
| 673 | Setting \fIcharsToRead\fR to \fB-1\fR will cause the command to read |
| 674 | all characters currently available (non-blocking) or everything until |
| 675 | eof (blocking mode). |
| 676 | .PP |
| 677 | The return value may be smaller than the value to read, indicating that less |
| 678 | data than requested was available. This is called a \fIshort read\fR. In |
| 679 | blocking mode, this can only happen on an end-of-file. In nonblocking mode, |
| 680 | a short read can also occur if there is not enough input currently |
| 681 | available: \fBTcl_ReadChars\fR returns a short count rather than waiting |
| 682 | for more data. |
| 683 | .PP |
| 684 | If the channel is in blocking mode, a return value of zero indicates an |
| 685 | end-of-file condition. If the channel is in nonblocking mode, a return |
| 686 | value of zero indicates either that no input is currently available or an |
| 687 | end-of-file condition. Use \fBTcl_Eof\fR and \fBTcl_InputBlocked\fR to tell |
| 688 | which of these conditions actually occurred. |
| 689 | .PP |
| 690 | \fBTcl_ReadChars\fR translates the various end-of-line representations into |
| 691 | the canonical \fB\en\fR internal representation according to the current |
| 692 | end-of-line recognition mode. End-of-line recognition and the various |
| 693 | platform-specific modes are described in the manual entry for the Tcl |
| 694 | \fBfconfigure\fR command. |
| 695 | .PP |
| 696 | As a performance optimization, when reading from a channel with the encoding |
| 697 | \fBbinary\fR, the bytes are not converted to UTF-8 as they are read. |
| 698 | Instead, they are stored in \fIreadObjPtr\fR's internal representation as a |
| 699 | byte-array object. The string representation of this object will only be |
| 700 | constructed if it is needed (e.g., because of a call to |
| 701 | \fBTcl_GetStringFromObj\fR). In this way, byte-oriented data can be read |
| 702 | from a channel, manipulated by calling \fBTcl_GetByteArrayFromObj\fR and |
| 703 | related functions, and then written to a channel without the expense of ever |
| 704 | converting to or from UTF-8. |
| 705 | .PP |
| 706 | \fBTcl_Read\fR is similar to \fBTcl_ReadChars\fR, except that it doesn't do |
| 707 | encoding conversions, regardless of the channel's encoding. It is deprecated |
| 708 | and exists for backwards compatibility with non-internationalized Tcl |
| 709 | extensions. It consumes bytes from \fIchannel\fR and stores them in |
| 710 | \fIreadBuf\fR, performing end-of-line translations on the way. The return value |
| 711 | of \fBTcl_Read\fR is the number of bytes, up to \fIbytesToRead\fR, written in |
| 712 | \fIreadBuf\fR. The buffer produced by \fBTcl_Read\fR is not null-terminated. |
| 713 | Its contents are valid from the zeroth position up to and excluding the |
| 714 | position indicated by the return value. |
| 715 | .PP |
| 716 | \fBTcl_ReadRaw\fR is the same as \fBTcl_Read\fR but does not |
| 717 | compensate for stacking. While \fBTcl_Read\fR (and the other functions |
| 718 | in the API) always get their data from the topmost channel in the |
| 719 | stack the supplied channel is part of, \fBTcl_ReadRaw\fR does |
| 720 | not. Thus this function is \fBonly\fR usable for transformational |
| 721 | channel drivers, i.e. drivers used in the middle of a stack of |
| 722 | channels, to move data from the channel below into the transformation. |
| 723 | |
| 724 | .SH "TCL_GETSOBJ AND TCL_GETS" |
| 725 | .PP |
| 726 | \fBTcl_GetsObj\fR consumes bytes from \fIchannel\fR, converting the bytes to |
| 727 | UTF-8 based on the channel's encoding, until a full line of input has been |
| 728 | seen. If the channel's encoding is \fBbinary\fR, each byte read from the |
| 729 | channel is treated as an individual Unicode character. All of the |
| 730 | characters of the line except for the terminating end-of-line character(s) |
| 731 | are appended to \fIlineObjPtr\fR's string representation. The end-of-line |
| 732 | character(s) are read and discarded. |
| 733 | .PP |
| 734 | If a line was successfully read, the return value is greater than or equal |
| 735 | to zero and indicates the number of bytes stored in \fIlineObjPtr\fR. If an |
| 736 | error occurs, \fBTcl_GetsObj\fR returns \-1 and records a POSIX error code |
| 737 | that can be retrieved with \fBTcl_GetErrno\fR. \fBTcl_GetsObj\fR also |
| 738 | returns \-1 if the end of the file is reached; the \fBTcl_Eof\fR procedure |
| 739 | can be used to distinguish an error from an end-of-file condition. |
| 740 | .PP |
| 741 | If the channel is in nonblocking mode, the return value can also be \-1 if |
| 742 | no data was available or the data that was available did not contain an |
| 743 | end-of-line character. When \-1 is returned, the \fBTcl_InputBlocked\fR |
| 744 | procedure may be invoked to determine if the channel is blocked because |
| 745 | of input unavailability. |
| 746 | .PP |
| 747 | \fBTcl_Gets\fR is the same as \fBTcl_GetsObj\fR except the resulting |
| 748 | characters are appended to the dynamic string given by |
| 749 | \fIlineRead\fR rather than a Tcl object. |
| 750 | |
| 751 | .SH "TCL_UNGETS" |
| 752 | .PP |
| 753 | \fBTcl_Ungets\fR is used to add data to the input queue of a channel, |
| 754 | at either the head or tail of the queue. The pointer \fIinput\fR points |
| 755 | to the data that is to be added. The length of the input to add is given |
| 756 | by \fIinputLen\fR. A non-zero value of \fIaddAtEnd\fR indicates that the |
| 757 | data is to be added at the end of queue; otherwise it will be added at the |
| 758 | head of the queue. If \fIchannel\fR has a "sticky" EOF set, no data will be |
| 759 | added to the input queue. \fBTcl_Ungets\fR returns \fIinputLen\fR or |
| 760 | -1 if an error occurs. |
| 761 | |
| 762 | .SH "TCL_WRITECHARS, TCL_WRITEOBJ, AND TCL_WRITE" |
| 763 | .PP |
| 764 | \fBTcl_WriteChars\fR accepts \fIbytesToWrite\fR bytes of character data at |
| 765 | \fIcharBuf\fR. The UTF-8 characters in the buffer are converted to the |
| 766 | channel's encoding and queued for output to \fIchannel\fR. If |
| 767 | \fIbytesToWrite\fR is negative, \fBTcl_WriteChars\fR expects \fIcharBuf\fR |
| 768 | to be null-terminated and it outputs everything up to the null. |
| 769 | .PP |
| 770 | Data queued for output may not appear on the output device immediately, due |
| 771 | to internal buffering. If the data should appear immediately, call |
| 772 | \fBTcl_Flush\fR after the call to \fBTcl_WriteChars\fR, or set the |
| 773 | \fB\-buffering\fR option on the channel to \fBnone\fR. If you wish the data |
| 774 | to appear as soon as a complete line is accepted for output, set the |
| 775 | \fB\-buffering\fR option on the channel to \fBline\fR mode. |
| 776 | .PP |
| 777 | The return value of \fBTcl_WriteChars\fR is a count of how many bytes were |
| 778 | accepted for output to the channel. This is either greater than zero to |
| 779 | indicate success or \-1 to indicate that an error occurred. If an error |
| 780 | occurs, \fBTcl_WriteChars\fR records a POSIX error code that may be |
| 781 | retrieved with \fBTcl_GetErrno\fR. |
| 782 | .PP |
| 783 | Newline characters in the output data are translated to platform-specific |
| 784 | end-of-line sequences according to the \fB\-translation\fR option for the |
| 785 | channel. This is done even if the channel has no encoding. |
| 786 | .PP |
| 787 | \fBTcl_WriteObj\fR is similar to \fBTcl_WriteChars\fR except it |
| 788 | accepts a Tcl object whose contents will be output to the channel. The |
| 789 | UTF-8 characters in \fIwriteObjPtr\fR's string representation are converted |
| 790 | to the channel's encoding and queued for output to \fIchannel\fR. |
| 791 | As a performance optimization, when writing to a channel with the encoding |
| 792 | \fBbinary\fR, UTF-8 characters are not converted as they are written. |
| 793 | Instead, the bytes in \fIwriteObjPtr\fR's internal representation as a |
| 794 | byte-array object are written to the channel. The byte-array representation |
| 795 | of the object will be constructed if it is needed. In this way, |
| 796 | byte-oriented data can be read from a channel, manipulated by calling |
| 797 | \fBTcl_GetByteArrayFromObj\fR and related functions, and then written to a |
| 798 | channel without the expense of ever converting to or from UTF-8. |
| 799 | .PP |
| 800 | \fBTcl_Write\fR is similar to \fBTcl_WriteChars\fR except that it doesn't do |
| 801 | encoding conversions, regardless of the channel's encoding. It is |
| 802 | deprecated and exists for backwards compatibility with non-internationalized |
| 803 | Tcl extensions. It accepts \fIbytesToWrite\fR bytes of data at |
| 804 | \fIbyteBuf\fR and queues them for output to \fIchannel\fR. If |
| 805 | \fIbytesToWrite\fR is negative, \fBTcl_Write\fR expects \fIbyteBuf\fR to be |
| 806 | null-terminated and it outputs everything up to the null. |
| 807 | .PP |
| 808 | \fBTcl_WriteRaw\fR is the same as \fBTcl_Write\fR but does not |
| 809 | compensate for stacking. While \fBTcl_Write\fR (and the other |
| 810 | functions in the API) always feed their input to the topmost channel |
| 811 | in the stack the supplied channel is part of, \fBTcl_WriteRaw\fR does |
| 812 | not. Thus this function is \fBonly\fR usable for transformational |
| 813 | channel drivers, i.e. drivers used in the middle of a stack of |
| 814 | channels, to move data from the transformation into the channel below |
| 815 | it. |
| 816 | .VE |
| 817 | |
| 818 | .SH TCL_FLUSH |
| 819 | .PP |
| 820 | \fBTcl_Flush\fR causes all of the buffered output data for \fIchannel\fR |
| 821 | to be written to its underlying file or device as soon as possible. |
| 822 | If the channel is in blocking mode, the call does not return until |
| 823 | all the buffered data has been sent to the channel or some error occurred. |
| 824 | The call returns immediately if the channel is nonblocking; it starts |
| 825 | a background flush that will write the buffered data to the channel |
| 826 | eventually, as fast as the channel is able to absorb it. |
| 827 | .PP |
| 828 | The return value is normally \fBTCL_OK\fR. |
| 829 | If an error occurs, \fBTcl_Flush\fR returns \fBTCL_ERROR\fR and |
| 830 | records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR. |
| 831 | |
| 832 | .SH TCL_SEEK |
| 833 | .PP |
| 834 | \fBTcl_Seek\fR moves the access point in \fIchannel\fR where subsequent |
| 835 | data will be read or written. Buffered output is flushed to the channel and |
| 836 | buffered input is discarded, prior to the seek operation. |
| 837 | .PP |
| 838 | \fBTcl_Seek\fR normally returns the new access point. |
| 839 | If an error occurs, \fBTcl_Seek\fR returns \-1 and records a POSIX error |
| 840 | code that can be retrieved with \fBTcl_GetErrno\fR. |
| 841 | After an error, the access point may or may not have been moved. |
| 842 | |
| 843 | .SH TCL_TELL |
| 844 | .PP |
| 845 | \fBTcl_Tell\fR returns the current access point for a channel. The returned |
| 846 | value is \-1 if the channel does not support seeking. |
| 847 | |
| 848 | .SH TCL_GETCHANNELOPTION |
| 849 | .PP |
| 850 | \fBTcl_GetChannelOption\fR retrieves, in \fIoptionValue\fR, the value of one of |
| 851 | the options currently in effect for a channel, or a list of all options and |
| 852 | their values. The \fIchannel\fR argument identifies the channel for which |
| 853 | to query an option or retrieve all options and their values. |
| 854 | If \fIoptionName\fR is not NULL, it is the name of the |
| 855 | option to query; the option's value is copied to the Tcl dynamic string |
| 856 | denoted by \fIoptionValue\fR. If |
| 857 | \fIoptionName\fR is NULL, the function stores an alternating list of option |
| 858 | names and their values in \fIoptionValue\fR, using a series of calls to |
| 859 | \fBTcl_DStringAppendElement\fR. The various preexisting options and |
| 860 | their possible values are described in the manual entry for the Tcl |
| 861 | \fBfconfigure\fR command. Other options can be added by each channel type. |
| 862 | These channel type specific options are described in the manual entry for |
| 863 | the Tcl command that creates a channel of that type; for example, the |
| 864 | additional options for TCP based channels are described in the manual entry |
| 865 | for the Tcl \fBsocket\fR command. |
| 866 | The procedure normally returns \fBTCL_OK\fR. If an error occurs, it returns |
| 867 | \fBTCL_ERROR\fR and calls \fBTcl_SetErrno\fR to store an appropriate POSIX |
| 868 | error code. |
| 869 | |
| 870 | .SH TCL_SETCHANNELOPTION |
| 871 | .PP |
| 872 | \fBTcl_SetChannelOption\fR sets a new value \fInewValue\fR |
| 873 | for an option \fIoptionName\fR on \fIchannel\fR. |
| 874 | The procedure normally returns \fBTCL_OK\fR. If an error occurs, |
| 875 | it returns \fBTCL_ERROR\fR; in addition, if \fIinterp\fR is non-NULL, |
| 876 | \fBTcl_SetChannelOption\fR leaves an error message in the interpreter's result. |
| 877 | |
| 878 | .SH TCL_EOF |
| 879 | .PP |
| 880 | \fBTcl_Eof\fR returns a nonzero value if \fIchannel\fR encountered |
| 881 | an end of file during the last input operation. |
| 882 | |
| 883 | .SH TCL_INPUTBLOCKED |
| 884 | .PP |
| 885 | \fBTcl_InputBlocked\fR returns a nonzero value if \fIchannel\fR is in |
| 886 | nonblocking mode and the last input operation returned less data than |
| 887 | requested because there was insufficient data available. |
| 888 | The call always returns zero if the channel is in blocking mode. |
| 889 | |
| 890 | .SH TCL_INPUTBUFFERED |
| 891 | .PP |
| 892 | \fBTcl_InputBuffered\fR returns the number of bytes of input currently |
| 893 | buffered in the internal buffers for a channel. If the channel is not open |
| 894 | for reading, this function always returns zero. |
| 895 | |
| 896 | .SH TCL_OUTPUTBUFFERED |
| 897 | .VS 8.4 |
| 898 | \fBTcl_OutputBuffered\fR returns the number of bytes of output |
| 899 | currently buffered in the internal buffers for a channel. If the |
| 900 | channel is not open for writing, this function always returns zero. |
| 901 | .VE |
| 902 | |
| 903 | .SH "PLATFORM ISSUES" |
| 904 | .PP |
| 905 | The handles returned from \fBTcl_GetChannelHandle\fR depend on the |
| 906 | platform and the channel type. On Unix platforms, the handle is |
| 907 | always a Unix file descriptor as returned from the \fBopen\fR system |
| 908 | call. On Windows platforms, the handle is a file \fBHANDLE\fR when |
| 909 | the channel was created with \fBTcl_OpenFileChannel\fR, |
| 910 | \fBTcl_OpenCommandChannel\fR, or \fBTcl_MakeFileChannel\fR. Other |
| 911 | channel types may return a different type of handle on Windows |
| 912 | platforms. On the Macintosh platform, the handle is a file reference |
| 913 | number as returned from \fBHOpenDF\fR. |
| 914 | |
| 915 | .SH "SEE ALSO" |
| 916 | DString(3), fconfigure(n), filename(n), fopen(3), Tcl_CreateChannel(3) |
| 917 | |
| 918 | .SH KEYWORDS |
| 919 | access point, blocking, buffered I/O, channel, channel driver, end of file, |
| 920 | flush, input, nonblocking, output, read, seek, write |