1Tcl_OpenFileChannel(3) Tcl Library Procedures Tcl_OpenFileChannel(3)
2______________________________________________________________________________
6
8 Tcl_OpenFileChannel, Tcl_OpenCommandChannel, Tcl_MakeFileChannel,
9 Tcl_GetChannel, Tcl_GetChannelNames, Tcl_GetChannelNamesEx, Tcl_Regis‐
10 terChannel, Tcl_UnregisterChannel, Tcl_DetachChannel, Tcl_IsStandard‐
11 Channel, Tcl_Close, Tcl_ReadChars, Tcl_Read, Tcl_GetsObj, Tcl_Gets,
12 Tcl_WriteObj, Tcl_WriteChars, Tcl_Write, Tcl_Flush, Tcl_Seek, Tcl_Tell,
13 Tcl_GetChannelOption, Tcl_SetChannelOption, Tcl_Eof, Tcl_InputBlocked,
14 Tcl_InputBuffered, Tcl_OutputBuffered, Tcl_Ungets, Tcl_ReadRaw,
15 Tcl_WriteRaw - buffered I/O facilities using channels
16
18 #include <tcl.h>
19 Tcl_Channel
21 Tcl_OpenFileChannel(interp, fileName, mode, permissions)
22 Tcl_Channel
24 Tcl_OpenCommandChannel(interp, argc, argv, flags)
25 Tcl_Channel
27 Tcl_MakeFileChannel(handle, readOrWrite)
28 Tcl_Channel
30 Tcl_GetChannel(interp, channelName, modePtr)
31 int │
33 Tcl_GetChannelNames(interp) │
34 int │
36 Tcl_GetChannelNamesEx(interp, pattern) │
37 void
39 Tcl_RegisterChannel(interp, channel)
40 int
42 Tcl_UnregisterChannel(interp, channel)
43 int
45 Tcl_DetachChannel(interp, channel)
46 int
48 Tcl_IsStandardChannel(channel)
49 int
51 Tcl_Close(interp, channel)
52 int │
54 Tcl_ReadChars(channel, readObjPtr, charsToRead, appendFlag) │
55 int │
57 Tcl_Read(channel, readBuf, bytesToRead) │
58 int │
60 Tcl_GetsObj(channel, lineObjPtr) │
61 int │
63 Tcl_Gets(channel, lineRead) │
64 int │
66 Tcl_Ungets(channel, input, inputLen, addAtEnd) │
67 int │
69 Tcl_WriteObj(channel, writeObjPtr) │
70 int │
72 Tcl_WriteChars(channel, charBuf, bytesToWrite) │
73 int │
75 Tcl_Write(channel, byteBuf, bytesToWrite) │
76 int │
78 Tcl_ReadRaw(channel, readBuf, bytesToRead) │
79 int │
81 Tcl_WriteRaw(channel, byteBuf, bytesToWrite) │
82 int
84 Tcl_Eof(channel)
85 int
87 Tcl_Flush(channel)
88 int
90 Tcl_InputBlocked(channel)
91 int
93 Tcl_InputBuffered(channel)
94 int │
96 Tcl_OutputBuffered(channel) │
97 Tcl_WideInt │
99 Tcl_Seek(channel, offset, seekMode) │
100 Tcl_WideInt │
102 Tcl_Tell(channel) │
103 int
105 Tcl_GetChannelOption(interp, channel, optionName, optionValue)
106 int
108 Tcl_SetChannelOption(interp, channel, optionName, newValue)
109
112 Tcl_Interp *interp (in) Used for error reporting
113 and to look up a channel
114 registered in it.
115 CONST char *fileName (in) The name of a local or
117 network file.
118 CONST char *mode (in) Specifies how the file
120 is to be accessed. May
121 have any of the values
122 allowed for the mode
123 argument to the Tcl open
124 command.
125 int permissions (in) POSIX-style permission
127 flags such as 0644. If
128 a new file is created,
129 these permissions will
130 be set on the created
131 file.
132 int argc (in) The number of elements
134 in argv.
135 CONST char **argv (in) Arguments for construct‐
137 ing a command pipeline.
138 These values have the
139 same meaning as the non-
140 switch arguments to the
141 Tcl exec command.
142 int flags (in) Specifies the disposi‐
144 tion of the stdio han‐
145 dles in pipeline: OR-ed
146 combination of
147 TCL_STDIN, TCL_STDOUT,
148 TCL_STDERR, and
149 TCL_ENFORCE_MODE. If
150 TCL_STDIN is set, stdin
151 for the first child in
152 the pipe is the pipe
153 channel, otherwise it is
154 the same as the standard
155 input of the invoking
156 process; likewise for
157 TCL_STDOUT and
158 TCL_STDERR. If
159 TCL_ENFORCE_MODE is not
160 set, then the pipe can
161 redirect stdio handles
162 to override the stdio
163 handles for which
164 TCL_STDIN, TCL_STDOUT
165 and TCL_STDERR have been
166 set. If it is set, then
167 such redirections cause
168 an error.
169 ClientData handle (in) Operating system spe‐
171 cific handle for I/O to
172 a file. For Unix this is
173 a file descriptor, for
174 Windows it is a HANDLE.
175 int readOrWrite (in) OR-ed combination of
177 TCL_READABLE and
178 TCL_WRITABLE to indicate
179 what operations are
180 valid on handle.
181 CONST char *channelName (in) The name of the channel.
183 int *modePtr (out) Points at an integer
185 variable that will
186 receive an OR-ed combi‐
187 nation of TCL_READABLE
188 and TCL_WRITABLE denot‐
189 ing whether the channel
190 is open for reading and
191 writing. │
192 CONST char *pattern (in) │
194 The pattern to match on, │
195 passed to Tcl_String‐ │
196 Match, or NULL.
197 Tcl_Channel channel (in) A Tcl channel for input
199 or output. Must have
200 been the return value
201 from a procedure such as
202 Tcl_OpenFileChannel.
203 Tcl_Obj *readObjPtr (in/out) │
205 A pointer to a Tcl │
206 Object in which to store │
207 the characters read from │
208 the channel. │
209 int charsToRead (in) │
211 The number of characters │
212 to read from the chan‐ │
213 nel. If the channel's │
214 encoding is binary, this │
215 is equivalent to the │
216 number of bytes to read │
217 from the channel. │
218 int appendFlag (in) │
220 If non-zero, data read │
221 from the channel will be │
222 appended to the object. │
223 Otherwise, the data will │
224 replace the existing │
225 contents of the object. │
226 char *readBuf (out) │
228 A buffer in which to │
229 store the bytes read │
230 from the channel. │
231 int bytesToRead (in) │
233 The number of bytes to │
234 read from the channel. │
235 The buffer readBuf must │
236 be large enough to hold │
237 this many bytes. │
238 Tcl_Obj *lineObjPtr (in/out) │
240 A pointer to a Tcl │
241 object in which to store │
242 the line read from the │
243 channel. The line read │
244 will be appended to the │
245 current value of the │
246 object. │
247 Tcl_DString *lineRead (in/out) │
249 A pointer to a Tcl │
250 dynamic string in which │
251 to store the line read │
252 from the channel. Must │
253 have been initialized by │
254 the caller. The line │
255 read will be appended to │
256 any data already in the │
257 dynamic string. │
258 CONST char *input (in) │
260 The input to add to a │
261 channel buffer. │
262 int inputLen (in) │
264 Length of the input │
265 int addAtEnd (in) │
267 Flag indicating whether │
268 the input should be │
269 added to the end or │
270 beginning of the channel │
271 buffer.
272 Tcl_Obj *writeObjPtr (in) A pointer to a Tcl
274 Object whose contents
275 will be output to the
276 channel.
277 CONST char *charBuf (in) A buffer containing the
279 characters to output to
280 the channel.
281 CONST char *byteBuf (in) A buffer containing the
283 bytes to output to the
284 channel.
285 int bytesToWrite (in) The number of bytes to
287 consume from charBuf or
288 byteBuf and output to
289 the channel.
290 Tcl_WideInt offset (in) How far to move the
292 access point in the
293 channel at which the
294 next input or output
295 operation will be
296 applied, measured in
297 bytes from the position
298 given by seekMode. May
299 be either positive or
300 negative.
301 int seekMode (in) Relative to which point
303 to seek; used with off‐
304 set to calculate the new
305 access point for the
306 channel. Legal values
307 are SEEK_SET, SEEK_CUR,
308 and SEEK_END.
309 CONST char *optionName (in) The name of an option
311 applicable to this chan‐
312 nel, such as -blocking.
313 May have any of the val‐
314 ues accepted by the
315 fconfigure command.
316 Tcl_DString *optionValue (in) Where to store the value
318 of an option or a list
319 of all options and their
320 values. Must have been
321 initialized by the call‐
322 er.
323 CONST char *newValue (in) New value for the option
325 given by optionName.
326_________________________________________________________________
327
330 The Tcl channel mechanism provides a device-independent and platform-
331 independent mechanism for performing buffered input and output opera‐
332 tions on a variety of file, socket, and device types. The channel
333 mechanism is extensible to new channel types, by providing a low level
334 channel driver for the new type; the channel driver interface is
335 described in the manual entry for Tcl_CreateChannel. The channel mecha‐
336 nism provides a buffering scheme modeled after Unix's standard I/O, and
337 it also allows for nonblocking I/O on channels.
338 The procedures described in this manual entry comprise the C APIs of
340 the generic layer of the channel architecture. For a description of the
341 channel driver architecture and how to implement channel drivers for
342 new types of channels, see the manual entry for Tcl_CreateChannel.
343
346 Tcl_OpenFileChannel opens a file specified by fileName and returns a
347 channel handle that can be used to perform input and output on the
348 file. This API is modeled after the fopen procedure of the Unix stan‐
349 dard I/O library. The syntax and meaning of all arguments is similar
350 to those given in the Tcl open command when opening a file. If an
351 error occurs while opening the channel, Tcl_OpenFileChannel returns
352 NULL and records a POSIX error code that can be retrieved with
353 Tcl_GetErrno. In addition, if interp is non-NULL, Tcl_OpenFileChannel
354 leaves an error message in interp's result after any error. As of Tcl
355 8.4, the object-based API Tcl_FSOpenFileChannel should be used in pref‐
356 erence to Tcl_OpenFileChannel wherever possible.
357 The newly created channel is not registered in the supplied inter‐
359 preter; to register it, use Tcl_RegisterChannel, described below. If
360 one of the standard channels, stdin, stdout or stderr was previously
361 closed, the act of creating the new channel also assigns it as a
362 replacement for the standard channel.
363
366 Tcl_OpenCommandChannel provides a C-level interface to the functions of
367 the exec and open commands. It creates a sequence of subprocesses
368 specified by the argv and argc arguments and returns a channel that can
369 be used to communicate with these subprocesses. The flags argument
370 indicates what sort of communication will exist with the command pipe‐
371 line.
372 If the TCL_STDIN flag is set then the standard input for the first sub‐
374 process will be tied to the channel: writing to the channel will pro‐
375 vide input to the subprocess. If TCL_STDIN is not set, then standard
376 input for the first subprocess will be the same as this application's
377 standard input. If TCL_STDOUT is set then standard output from the
378 last subprocess can be read from the channel; otherwise it goes to this
379 application's standard output. If TCL_STDERR is set, standard error
380 output for all subprocesses is returned to the channel and results in
381 an error when the channel is closed; otherwise it goes to this applica‐
382 tion's standard error. If TCL_ENFORCE_MODE is not set, then argc and
383 argv can redirect the stdio handles to override TCL_STDIN, TCL_STDOUT,
384 and TCL_STDERR; if it is set, then it is an error for argc and argv to
385 override stdio channels for which TCL_STDIN, TCL_STDOUT, and TCL_STDERR
386 have been set.
387 If an error occurs while opening the channel, Tcl_OpenCommandChannel
389 returns NULL and records a POSIX error code that can be retrieved with
390 Tcl_GetErrno. In addition, Tcl_OpenCommandChannel leaves an error mes‐
391 sage in the interpreter's result if interp is not NULL.
392 The newly created channel is not registered in the supplied inter‐
394 preter; to register it, use Tcl_RegisterChannel, described below. If
395 one of the standard channels, stdin, stdout or stderr was previously
396 closed, the act of creating the new channel also assigns it as a
397 replacement for the standard channel.
398
401 Tcl_MakeFileChannel makes a Tcl_Channel from an existing, platform-spe‐
402 cific, file handle. The newly created channel is not registered in the
403 supplied interpreter; to register it, use Tcl_RegisterChannel,
404 described below. If one of the standard channels, stdin, stdout or
405 stderr was previously closed, the act of creating the new channel also
406 assigns it as a replacement for the standard channel.
407
410 Tcl_GetChannel returns a channel given the channelName used to create
411 it with Tcl_CreateChannel and a pointer to a Tcl interpreter in interp.
412 If a channel by that name is not registered in that interpreter, the
413 procedure returns NULL. If the modePtr argument is not NULL, it points
414 at an integer variable that will receive an OR-ed combination of
415 TCL_READABLE and TCL_WRITABLE describing whether the channel is open
416 for reading and writing.
417 Tcl_GetChannelNames and Tcl_GetChannelNamesEx write the names of the
419 registered channels to the interpreter's result as a list object.
420 Tcl_GetChannelNamesEx will filter these names according to the pattern.
421 If pattern is NULL, then it will not do any filtering. The return
422 value is TCL_OK if no errors occurred writing to the result, otherwise
423 it is TCL_ERROR, and the error message is left in the interpreter's
424 result.
425
428 Tcl_RegisterChannel adds a channel to the set of channels accessible in
429 interp. After this call, Tcl programs executing in that interpreter can
430 refer to the channel in input or output operations using the name given
431 in the call to Tcl_CreateChannel. After this call, the channel becomes
432 the property of the interpreter, and the caller should not call
433 Tcl_Close for the channel; the channel will be closed automatically
434 when it is unregistered from the interpreter.
435 Code executing outside of any Tcl interpreter can call Tcl_Register‐
437 Channel with interp as NULL, to indicate that it wishes to hold a ref‐
438 erence to this channel. Subsequently, the channel can be registered in
439 a Tcl interpreter and it will only be closed when the matching number
440 of calls to Tcl_UnregisterChannel have been made. This allows code
441 executing outside of any interpreter to safely hold a reference to a
442 channel that is also registered in a Tcl interpreter.
443 This procedure interacts with the code managing the standard channels.
445 If no standard channels were initialized before the first call to
446 Tcl_RegisterChannel they will get initialized by that call. See
447 Tcl_StandardChannels for a general treatise about standard channels and
448 the behaviour of the Tcl library with regard to them.
449
452 Tcl_UnregisterChannel removes a channel from the set of channels acces‐
453 sible in interp. After this call, Tcl programs will no longer be able
454 to use the channel's name to refer to the channel in that interpreter.
455 If this operation removed the last registration of the channel in any
456 interpreter, the channel is also closed and destroyed.
457 Code not associated with a Tcl interpreter can call Tcl_UnregisterChan‐
459 nel with interp as NULL, to indicate to Tcl that it no longer holds a
460 reference to that channel. If this is the last reference to the chan‐
461 nel, it will now be closed. Tcl_UnregisterChannel is very similar to
462 Tcl_DetachChannel except that it will also close the channel if no fur‐
463 ther references to it exist.
464
467 Tcl_DetachChannel removes a channel from the set of channels accessible
468 in interp. After this call, Tcl programs will no longer be able to use
469 the channel's name to refer to the channel in that interpreter. Beyond
470 that, this command has no further effect. It cannot be used on the
471 standard channels (stdout, stderr, stdin), and will return TCL_ERROR if
472 passed one of those channels.
473 Code not associated with a Tcl interpreter can call Tcl_DetachChannel
475 with interp as NULL, to indicate to Tcl that it no longer holds a ref‐
476 erence to that channel. If this is the last reference to the channel,
477 unlike Tcl_UnregisterChannel, it will not be closed.
478
481 Tcl_IsStandardChannel tests whether a channel is one of the three stan‐
482 dard channels, stdin, stdout or stderr. If so, it returns 1, otherwise
483 0.
484 No attempt is made to check whether the given channel or the standard
486 channels are initialized or otherwise valid.
487
490 Tcl_Close destroys the channel channel, which must denote a currently
491 open channel. The channel should not be registered in any interpreter
492 when Tcl_Close is called. Buffered output is flushed to the channel's
493 output device prior to destroying the channel, and any buffered input
494 is discarded. If this is a blocking channel, the call does not return
495 until all buffered data is successfully sent to the channel's output
496 device. If this is a nonblocking channel and there is buffered output
497 that cannot be written without blocking, the call returns immediately;
498 output is flushed in the background and the channel will be closed once
499 all of the buffered data has been output. In this case errors during
500 flushing are not reported.
501 If the channel was closed successfully, Tcl_Close returns TCL_OK. If
503 an error occurs, Tcl_Close returns TCL_ERROR and records a POSIX error
504 code that can be retrieved with Tcl_GetErrno. If the channel is being
505 closed synchronously and an error occurs during closing of the channel
506 and interp is not NULL, an error message is left in the interpreter's
507 result.
508 Note: it is not safe to call Tcl_Close on a channel that has been reg‐
510 istered using Tcl_RegisterChannel; see the documentation for Tcl_Regis‐
511 terChannel, above, for details. If the channel has ever been given as
512 the chan argument in a call to Tcl_RegisterChannel, you should instead
513 use Tcl_UnregisterChannel, which will internally call Tcl_Close when
514 all calls to Tcl_RegisterChannel have been matched by corresponding
515 calls to Tcl_UnregisterChannel.
516
519 Tcl_ReadChars consumes bytes from channel, converting the bytes to │
520 UTF-8 based on the channel's encoding and storing the produced data in │
521 readObjPtr's string representation. The return value of Tcl_ReadChars │
522 is the number of characters, up to charsToRead, that were stored in │
523 readObjPtr. If an error occurs while reading, the return value is -1 │
524 and Tcl_ReadChars records a POSIX error code that can be retrieved with │
525 Tcl_GetErrno. │
526 Setting charsToRead to -1 will cause the command to read all characters │
528 currently available (non-blocking) or everything until eof (blocking │
529 mode). │
530 The return value may be smaller than the value to read, indicating that │
532 less data than requested was available. This is called a short read. │
533 In blocking mode, this can only happen on an end-of-file. In nonblock‐ │
534 ing mode, a short read can also occur if there is not enough input cur‐ │
535 rently available: Tcl_ReadChars returns a short count rather than │
536 waiting for more data. │
537 If the channel is in blocking mode, a return value of zero indicates an │
539 end-of-file condition. If the channel is in nonblocking mode, a return │
540 value of zero indicates either that no input is currently available or │
541 an end-of-file condition. Use Tcl_Eof and Tcl_InputBlocked to tell │
542 which of these conditions actually occurred. │
543 Tcl_ReadChars translates the various end-of-line representations into │
545 the canonical \n internal representation according to the current end- │
546 of-line recognition mode. End-of-line recognition and the various │
547 platform-specific modes are described in the manual entry for the Tcl │
548 fconfigure command. │
549 As a performance optimization, when reading from a channel with the │
551 encoding binary, the bytes are not converted to UTF-8 as they are read. │
552 Instead, they are stored in readObjPtr's internal representation as a │
553 byte-array object. The string representation of this object will only │
554 be constructed if it is needed (e.g., because of a call to Tcl_Get‐ │
555 StringFromObj). In this way, byte-oriented data can be read from a │
556 channel, manipulated by calling Tcl_GetByteArrayFromObj and related │
557 functions, and then written to a channel without the expense of ever │
558 converting to or from UTF-8. │
559 Tcl_Read is similar to Tcl_ReadChars, except that it doesn't do encod‐ │
561 ing conversions, regardless of the channel's encoding. It is depre‐ │
562 cated and exists for backwards compatibility with non-internationalized │
563 Tcl extensions. It consumes bytes from channel and stores them in │
564 readBuf, performing end-of-line translations on the way. The return │
565 value of Tcl_Read is the number of bytes, up to bytesToRead, written in │
566 readBuf. The buffer produced by Tcl_Read is not null-terminated. Its │
567 contents are valid from the zeroth position up to and excluding the │
568 position indicated by the return value. │
569 Tcl_ReadRaw is the same as Tcl_Read but does not compensate for stack‐ │
571 ing. While Tcl_Read (and the other functions in the API) always get │
572 their data from the topmost channel in the stack the supplied channel │
573 is part of, Tcl_ReadRaw does not. Thus this function is only usable for │
574 transformational channel drivers, i.e. drivers used in the middle of a │
575 stack of channels, to move data from the channel below into the trans‐ │
576 formation. │
577
580 Tcl_GetsObj consumes bytes from channel, converting the bytes to UTF-8 │
581 based on the channel's encoding, until a full line of input has been │
582 seen. If the channel's encoding is binary, each byte read from the │
583 channel is treated as an individual Unicode character. All of the │
584 characters of the line except for the terminating end-of-line charac‐ │
585 ter(s) are appended to lineObjPtr's string representation. The end-of- │
586 line character(s) are read and discarded. │
587 If a line was successfully read, the return value is greater than or │
589 equal to zero and indicates the number of bytes stored in lineObjPtr. │
590 If an error occurs, Tcl_GetsObj returns -1 and records a POSIX error │
591 code that can be retrieved with Tcl_GetErrno. Tcl_GetsObj also returns │
592 -1 if the end of the file is reached; the Tcl_Eof procedure can be used │
593 to distinguish an error from an end-of-file condition. │
594 If the channel is in nonblocking mode, the return value can also be -1 │
596 if no data was available or the data that was available did not contain │
597 an end-of-line character. When -1 is returned, the Tcl_InputBlocked │
598 procedure may be invoked to determine if the channel is blocked because │
599 of input unavailability. │
600 Tcl_Gets is the same as Tcl_GetsObj except the resulting characters are │
602 appended to the dynamic string given by lineRead rather than a Tcl │
603 object. │
604
607 Tcl_Ungets is used to add data to the input queue of a channel, at │
608 either the head or tail of the queue. The pointer input points to the │
609 data that is to be added. The length of the input to add is given by │
610 inputLen. A non-zero value of addAtEnd indicates that the data is to │
611 be added at the end of queue; otherwise it will be added at the head of │
612 the queue. If channel has a "sticky" EOF set, no data will be added to │
613 the input queue. Tcl_Ungets returns inputLen or -1 if an error occurs. │
614
617 Tcl_WriteChars accepts bytesToWrite bytes of character data at charBuf. │
618 The UTF-8 characters in the buffer are converted to the channel's │
619 encoding and queued for output to channel. If bytesToWrite is nega‐ │
620 tive, Tcl_WriteChars expects charBuf to be null-terminated and it out‐ │
621 puts everything up to the null. │
622 Data queued for output may not appear on the output device immediately, │
624 due to internal buffering. If the data should appear immediately, call │
625 Tcl_Flush after the call to Tcl_WriteChars, or set the -buffering │
626 option on the channel to none. If you wish the data to appear as soon │
627 as a complete line is accepted for output, set the -buffering option on │
628 the channel to line mode. │
629 The return value of Tcl_WriteChars is a count of how many bytes were │
631 accepted for output to the channel. This is either greater than zero │
632 to indicate success or -1 to indicate that an error occurred. If an │
633 error occurs, Tcl_WriteChars records a POSIX error code that may be │
634 retrieved with Tcl_GetErrno. │
635 Newline characters in the output data are translated to platform-spe‐ │
637 cific end-of-line sequences according to the -translation option for │
638 the channel. This is done even if the channel has no encoding. │
639 Tcl_WriteObj is similar to Tcl_WriteChars except it accepts a Tcl │
641 object whose contents will be output to the channel. The UTF-8 charac‐ │
642 ters in writeObjPtr's string representation are converted to the chan‐ │
643 nel's encoding and queued for output to channel. As a performance │
644 optimization, when writing to a channel with the encoding binary, UTF-8 │
645 characters are not converted as they are written. Instead, the bytes │
646 in writeObjPtr's internal representation as a byte-array object are │
647 written to the channel. The byte-array representation of the object │
648 will be constructed if it is needed. In this way, byte-oriented data │
649 can be read from a channel, manipulated by calling Tcl_GetByteArrayFro‐ │
650 mObj and related functions, and then written to a channel without the │
651 expense of ever converting to or from UTF-8. │
652 Tcl_Write is similar to Tcl_WriteChars except that it doesn't do encod‐ │
654 ing conversions, regardless of the channel's encoding. It is depre‐ │
655 cated and exists for backwards compatibility with non-internationalized │
656 Tcl extensions. It accepts bytesToWrite bytes of data at byteBuf and │
657 queues them for output to channel. If bytesToWrite is negative, │
658 Tcl_Write expects byteBuf to be null-terminated and it outputs every‐ │
659 thing up to the null. │
660 Tcl_WriteRaw is the same as Tcl_Write but does not compensate for │
662 stacking. While Tcl_Write (and the other functions in the API) always │
663 feed their input to the topmost channel in the stack the supplied chan‐ │
664 nel is part of, Tcl_WriteRaw does not. Thus this function is only │
665 usable for transformational channel drivers, i.e. drivers used in the │
666 middle of a stack of channels, to move data from the transformation │
667 into the channel below it.
668
671 Tcl_Flush causes all of the buffered output data for channel to be
672 written to its underlying file or device as soon as possible. If the
673 channel is in blocking mode, the call does not return until all the
674 buffered data has been sent to the channel or some error occurred. The
675 call returns immediately if the channel is nonblocking; it starts a
676 background flush that will write the buffered data to the channel even‐
677 tually, as fast as the channel is able to absorb it.
678 The return value is normally TCL_OK. If an error occurs, Tcl_Flush
680 returns TCL_ERROR and records a POSIX error code that can be retrieved
681 with Tcl_GetErrno.
682
685 Tcl_Seek moves the access point in channel where subsequent data will
686 be read or written. Buffered output is flushed to the channel and
687 buffered input is discarded, prior to the seek operation.
688 Tcl_Seek normally returns the new access point. If an error occurs,
690 Tcl_Seek returns -1 and records a POSIX error code that can be
691 retrieved with Tcl_GetErrno. After an error, the access point may or
692 may not have been moved.
693
696 Tcl_Tell returns the current access point for a channel. The returned
697 value is -1 if the channel does not support seeking.
698
701 Tcl_GetChannelOption retrieves, in optionValue, the value of one of the
702 options currently in effect for a channel, or a list of all options and
703 their values. The channel argument identifies the channel for which to
704 query an option or retrieve all options and their values. If option‐
705 Name is not NULL, it is the name of the option to query; the option's
706 value is copied to the Tcl dynamic string denoted by optionValue. If
707 optionName is NULL, the function stores an alternating list of option
708 names and their values in optionValue, using a series of calls to
709 Tcl_DStringAppendElement. The various preexisting options and their
710 possible values are described in the manual entry for the Tcl fconfig‐
711 ure command. Other options can be added by each channel type. These
712 channel type specific options are described in the manual entry for the
713 Tcl command that creates a channel of that type; for example, the addi‐
714 tional options for TCP based channels are described in the manual entry
715 for the Tcl socket command. The procedure normally returns TCL_OK. If
716 an error occurs, it returns TCL_ERROR and calls Tcl_SetErrno to store
717 an appropriate POSIX error code.
718
721 Tcl_SetChannelOption sets a new value newValue for an option optionName
722 on channel. The procedure normally returns TCL_OK. If an error
723 occurs, it returns TCL_ERROR; in addition, if interp is non-NULL,
724 Tcl_SetChannelOption leaves an error message in the interpreter's
725 result.
726
729 Tcl_Eof returns a nonzero value if channel encountered an end of file
730 during the last input operation.
731
734 Tcl_InputBlocked returns a nonzero value if channel is in nonblocking
735 mode and the last input operation returned less data than requested
736 because there was insufficient data available. The call always returns
737 zero if the channel is in blocking mode.
738
741 Tcl_InputBuffered returns the number of bytes of input currently
742 buffered in the internal buffers for a channel. If the channel is not
743 open for reading, this function always returns zero.
744
747 Tcl_OutputBuffered returns the number of bytes of output currently │
748 buffered in the internal buffers for a channel. If the channel is not │
749 open for writing, this function always returns zero.
750
753 The handles returned from Tcl_GetChannelHandle depend on the platform
754 and the channel type. On Unix platforms, the handle is always a Unix
755 file descriptor as returned from the open system call. On Windows
756 platforms, the handle is a file HANDLE when the channel was created
757 with Tcl_OpenFileChannel, Tcl_OpenCommandChannel, or Tcl_MakeFileChan‐
758 nel. Other channel types may return a different type of handle on Win‐
759 dows platforms. On the Macintosh platform, the handle is a file refer‐
760 ence number as returned from HOpenDF.
761
764 DString(3), fconfigure(n), filename(n), fopen(3), Tcl_CreateChannel(3)
765
768 access point, blocking, buffered I/O, channel, channel driver, end of
769 file, flush, input, nonblocking, output, read, seek, write
770Tcl 8.3 Tcl_OpenFileChannel(3)