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_TruncateChannel, Tcl_GetChannelOption, Tcl_SetChannelOption,
14 Tcl_Eof, Tcl_InputBlocked, Tcl_InputBuffered, Tcl_OutputBuffered,
15 Tcl_Ungets, Tcl_ReadRaw, Tcl_WriteRaw - buffered I/O facilities using
16 channels
17
19 #include <tcl.h>
20 Tcl_Channel
22 Tcl_OpenFileChannel(interp, fileName, mode, permissions)
23 Tcl_Channel
25 Tcl_OpenCommandChannel(interp, argc, argv, flags)
26 Tcl_Channel
28 Tcl_MakeFileChannel(handle, readOrWrite)
29 Tcl_Channel
31 Tcl_GetChannel(interp, channelName, modePtr)
32 int
34 Tcl_GetChannelNames(interp)
35 int
37 Tcl_GetChannelNamesEx(interp, pattern)
38 void
40 Tcl_RegisterChannel(interp, channel)
41 int
43 Tcl_UnregisterChannel(interp, channel)
44 int
46 Tcl_DetachChannel(interp, channel)
47 int
49 Tcl_IsStandardChannel(channel)
50 int
52 Tcl_Close(interp, channel)
53 int
55 Tcl_ReadChars(channel, readObjPtr, charsToRead, appendFlag)
56 int
58 Tcl_Read(channel, readBuf, bytesToRead)
59 int
61 Tcl_GetsObj(channel, lineObjPtr)
62 int
64 Tcl_Gets(channel, lineRead)
65 int
67 Tcl_Ungets(channel, input, inputLen, addAtEnd)
68 int
70 Tcl_WriteObj(channel, writeObjPtr)
71 int
73 Tcl_WriteChars(channel, charBuf, bytesToWrite)
74 int
76 Tcl_Write(channel, byteBuf, bytesToWrite)
77 int
79 Tcl_ReadRaw(channel, readBuf, bytesToRead)
80 int
82 Tcl_WriteRaw(channel, byteBuf, bytesToWrite)
83 int
85 Tcl_Eof(channel)
86 int
88 Tcl_Flush(channel)
89 int
91 Tcl_InputBlocked(channel)
92 int
94 Tcl_InputBuffered(channel)
95 int
97 Tcl_OutputBuffered(channel)
98 Tcl_WideInt
100 Tcl_Seek(channel, offset, seekMode)
101 Tcl_WideInt
103 Tcl_Tell(channel)
104 int │
106 Tcl_TruncateChannel(channel, length) │
107 int
109 Tcl_GetChannelOption(interp, channel, optionName, optionValue)
110 int
112 Tcl_SetChannelOption(interp, channel, optionName, newValue)
113
116 Tcl_Interp *interp (in) Used for error reporting and to
117 look up a channel registered in
118 it.
119 const char *fileName (in) The name of a local or network
121 file.
122 const char *mode (in) Specifies how the file is to be
124 accessed. May have any of the
125 values allowed for the mode
126 argument to the Tcl open com‐
127 mand.
128 int permissions (in) POSIX-style permission flags
130 such as 0644. If a new file is
131 created, these permissions will
132 be set on the created file.
133 int argc (in) The number of elements in argv.
135 const char **argv (in) Arguments for constructing a
137 command pipeline. These values
138 have the same meaning as the
139 non-switch arguments to the Tcl
140 exec command.
141 int flags (in) Specifies the disposition of the
143 stdio handles in pipeline: OR-ed
144 combination of TCL_STDIN,
145 TCL_STDOUT, TCL_STDERR, and
146 TCL_ENFORCE_MODE. If TCL_STDIN
147 is set, stdin for the first
148 child in the pipe is the pipe
149 channel, otherwise it is the
150 same as the standard input of
151 the invoking process; likewise
152 for TCL_STDOUT and TCL_STDERR.
153 If TCL_ENFORCE_MODE is not set,
154 then the pipe can redirect stdio
155 handles to override the stdio
156 handles for which TCL_STDIN,
157 TCL_STDOUT and TCL_STDERR have
158 been set. If it is set, then
159 such redirections cause an
160 error.
161 ClientData handle (in) Operating system specific handle
163 for I/O to a file. For Unix this
164 is a file descriptor, for Win‐
165 dows it is a HANDLE.
166 int readOrWrite (in) OR-ed combination of TCL_READ‐
168 ABLE and TCL_WRITABLE to indi‐
169 cate what operations are valid
170 on handle.
171 const char *channelName (in) The name of the channel.
173 int *modePtr (out) Points at an integer variable
175 that will receive an OR-ed com‐
176 bination of TCL_READABLE and
177 TCL_WRITABLE denoting whether
178 the channel is open for reading
179 and writing.
180 const char *pattern (in) The pattern to match on, passed
182 to Tcl_StringMatch, or NULL.
183 Tcl_Channel channel (in) A Tcl channel for input or out‐
185 put. Must have been the return
186 value from a procedure such as
187 Tcl_OpenFileChannel.
188 Tcl_Obj *readObjPtr (in/out) A pointer to a Tcl Object in
190 which to store the characters
191 read from the channel.
192 int charsToRead (in) The number of characters to read
194 from the channel. If the chan‐
195 nel's encoding is binary, this
196 is equivalent to the number of
197 bytes to read from the channel.
198 int appendFlag (in) If non-zero, data read from the
200 channel will be appended to the
201 object. Otherwise, the data
202 will replace the existing con‐
203 tents of the object.
204 char *readBuf (out) A buffer in which to store the
206 bytes read from the channel.
207 int bytesToRead (in) The number of bytes to read from
209 the channel. The buffer readBuf
210 must be large enough to hold
211 this many bytes.
212 Tcl_Obj *lineObjPtr (in/out) A pointer to a Tcl object in
214 which to store the line read
215 from the channel. The line read
216 will be appended to the current
217 value of the object.
218 Tcl_DString *lineRead (in/out) A pointer to a Tcl dynamic
220 string in which to store the
221 line read from the channel.
222 Must have been initialized by
223 the caller. The line read will
224 be appended to any data already
225 in the dynamic string.
226 const char *input (in) The input to add to a channel
228 buffer.
229 int inputLen (in) Length of the input
231 int addAtEnd (in) Flag indicating whether the
233 input should be added to the end
234 or beginning of the channel buf‐
235 fer.
236 Tcl_Obj *writeObjPtr (in) A pointer to a Tcl Object whose
238 contents will be output to the
239 channel.
240 const char *charBuf (in) A buffer containing the charac‐
242 ters to output to the channel.
243 const char *byteBuf (in) A buffer containing the bytes to
245 output to the channel.
246 int bytesToWrite (in) The number of bytes to consume
248 from charBuf or byteBuf and out‐
249 put to the channel.
250 Tcl_WideInt offset (in) How far to move the access point
252 in the channel at which the next
253 input or output operation will
254 be applied, measured in bytes
255 from the position given by seek‐
256 Mode. May be either positive or
257 negative.
258 int seekMode (in) Relative to which point to seek;
260 used with offset to calculate
261 the new access point for the
262 channel. Legal values are
263 SEEK_SET, SEEK_CUR, and
264 SEEK_END.
265 Tcl_WideInt length (in) The (non-negative) length to
267 truncate the channel the channel
268 to.
269 const char *optionName (in) The name of an option applicable
271 to this channel, such as -block‐
272 ing. May have any of the values
273 accepted by the fconfigure com‐
274 mand.
275 Tcl_DString *optionValue (in) Where to store the value of an
277 option or a list of all options
278 and their values. Must have been
279 initialized by the caller.
280 const char *newValue (in) New value for the option given
282 by optionName.
283_________________________________________________________________
284
287 The Tcl channel mechanism provides a device-independent and platform-
288 independent mechanism for performing buffered input and output opera‐
289 tions on a variety of file, socket, and device types. The channel
290 mechanism is extensible to new channel types, by providing a low-level
291 channel driver for the new type; the channel driver interface is
292 described in the manual entry for Tcl_CreateChannel. The channel mecha‐
293 nism provides a buffering scheme modeled after Unix's standard I/O, and
294 it also allows for nonblocking I/O on channels.
295 The procedures described in this manual entry comprise the C APIs of
297 the generic layer of the channel architecture. For a description of the
298 channel driver architecture and how to implement channel drivers for
299 new types of channels, see the manual entry for Tcl_CreateChannel.
300
303 Tcl_OpenFileChannel opens a file specified by fileName and returns a
304 channel handle that can be used to perform input and output on the
305 file. This API is modeled after the fopen procedure of the Unix stan‐
306 dard I/O library. The syntax and meaning of all arguments is similar
307 to those given in the Tcl open command when opening a file. If an
308 error occurs while opening the channel, Tcl_OpenFileChannel returns
309 NULL and records a POSIX error code that can be retrieved with
310 Tcl_GetErrno. In addition, if interp is non-NULL, Tcl_OpenFileChannel
311 leaves an error message in interp's result after any error. As of Tcl
312 8.4, the object-based API Tcl_FSOpenFileChannel should be used in pref‐
313 erence to Tcl_OpenFileChannel wherever possible.
314 The newly created channel is not registered in the supplied inter‐
316 preter; to register it, use Tcl_RegisterChannel, described below. If
317 one of the standard channels, stdin, stdout or stderr was previously
318 closed, the act of creating the new channel also assigns it as a
319 replacement for the standard channel.
320
323 Tcl_OpenCommandChannel provides a C-level interface to the functions of
324 the exec and open commands. It creates a sequence of subprocesses
325 specified by the argv and argc arguments and returns a channel that can
326 be used to communicate with these subprocesses. The flags argument
327 indicates what sort of communication will exist with the command pipe‐
328 line.
329 If the TCL_STDIN flag is set then the standard input for the first sub‐
331 process will be tied to the channel: writing to the channel will pro‐
332 vide input to the subprocess. If TCL_STDIN is not set, then standard
333 input for the first subprocess will be the same as this application's
334 standard input. If TCL_STDOUT is set then standard output from the
335 last subprocess can be read from the channel; otherwise it goes to this
336 application's standard output. If TCL_STDERR is set, standard error
337 output for all subprocesses is returned to the channel and results in
338 an error when the channel is closed; otherwise it goes to this applica‐
339 tion's standard error. If TCL_ENFORCE_MODE is not set, then argc and
340 argv can redirect the stdio handles to override TCL_STDIN, TCL_STDOUT,
341 and TCL_STDERR; if it is set, then it is an error for argc and argv to
342 override stdio channels for which TCL_STDIN, TCL_STDOUT, and TCL_STDERR
343 have been set.
344 If an error occurs while opening the channel, Tcl_OpenCommandChannel
346 returns NULL and records a POSIX error code that can be retrieved with
347 Tcl_GetErrno. In addition, Tcl_OpenCommandChannel leaves an error mes‐
348 sage in the interpreter's result if interp is not NULL.
349 The newly created channel is not registered in the supplied inter‐
351 preter; to register it, use Tcl_RegisterChannel, described below. If
352 one of the standard channels, stdin, stdout or stderr was previously
353 closed, the act of creating the new channel also assigns it as a
354 replacement for the standard channel.
355
358 Tcl_MakeFileChannel makes a Tcl_Channel from an existing, platform-spe‐
359 cific, file handle. The newly created channel is not registered in the
360 supplied interpreter; to register it, use Tcl_RegisterChannel,
361 described below. If one of the standard channels, stdin, stdout or
362 stderr was previously closed, the act of creating the new channel also
363 assigns it as a replacement for the standard channel.
364
367 Tcl_GetChannel returns a channel given the channelName used to create
368 it with Tcl_CreateChannel and a pointer to a Tcl interpreter in interp.
369 If a channel by that name is not registered in that interpreter, the
370 procedure returns NULL. If the modePtr argument is not NULL, it points
371 at an integer variable that will receive an OR-ed combination of
372 TCL_READABLE and TCL_WRITABLE describing whether the channel is open
373 for reading and writing.
374 Tcl_GetChannelNames and Tcl_GetChannelNamesEx write the names of the
376 registered channels to the interpreter's result as a list object.
377 Tcl_GetChannelNamesEx will filter these names according to the pattern.
378 If pattern is NULL, then it will not do any filtering. The return
379 value is TCL_OK if no errors occurred writing to the result, otherwise
380 it is TCL_ERROR, and the error message is left in the interpreter's
381 result.
382
385 Tcl_RegisterChannel adds a channel to the set of channels accessible in
386 interp. After this call, Tcl programs executing in that interpreter can
387 refer to the channel in input or output operations using the name given
388 in the call to Tcl_CreateChannel. After this call, the channel becomes
389 the property of the interpreter, and the caller should not call
390 Tcl_Close for the channel; the channel will be closed automatically
391 when it is unregistered from the interpreter.
392 Code executing outside of any Tcl interpreter can call Tcl_Register‐
394 Channel with interp as NULL, to indicate that it wishes to hold a ref‐
395 erence to this channel. Subsequently, the channel can be registered in
396 a Tcl interpreter and it will only be closed when the matching number
397 of calls to Tcl_UnregisterChannel have been made. This allows code
398 executing outside of any interpreter to safely hold a reference to a
399 channel that is also registered in a Tcl interpreter.
400 This procedure interacts with the code managing the standard channels.
402 If no standard channels were initialized before the first call to
403 Tcl_RegisterChannel, they will get initialized by that call. See
404 Tcl_StandardChannels for a general treatise about standard channels and
405 the behaviour of the Tcl library with regard to them.
406
409 Tcl_UnregisterChannel removes a channel from the set of channels acces‐
410 sible in interp. After this call, Tcl programs will no longer be able
411 to use the channel's name to refer to the channel in that interpreter.
412 If this operation removed the last registration of the channel in any
413 interpreter, the channel is also closed and destroyed.
414 Code not associated with a Tcl interpreter can call Tcl_UnregisterChan‐
416 nel with interp as NULL, to indicate to Tcl that it no longer holds a
417 reference to that channel. If this is the last reference to the chan‐
418 nel, it will now be closed. Tcl_UnregisterChannel is very similar to
419 Tcl_DetachChannel except that it will also close the channel if no fur‐
420 ther references to it exist.
421
424 Tcl_DetachChannel removes a channel from the set of channels accessible
425 in interp. After this call, Tcl programs will no longer be able to use
426 the channel's name to refer to the channel in that interpreter. Beyond
427 that, this command has no further effect. It cannot be used on the
428 standard channels (stdout, stderr, stdin), and will return TCL_ERROR if
429 passed one of those channels.
430 Code not associated with a Tcl interpreter can call Tcl_DetachChannel
432 with interp as NULL, to indicate to Tcl that it no longer holds a ref‐
433 erence to that channel. If this is the last reference to the channel,
434 unlike Tcl_UnregisterChannel, it will not be closed.
435
438 Tcl_IsStandardChannel tests whether a channel is one of the three stan‐
439 dard channels, stdin, stdout or stderr. If so, it returns 1, otherwise
440 0.
441 No attempt is made to check whether the given channel or the standard
443 channels are initialized or otherwise valid.
444
447 Tcl_Close destroys the channel channel, which must denote a currently
448 open channel. The channel should not be registered in any interpreter
449 when Tcl_Close is called. Buffered output is flushed to the channel's
450 output device prior to destroying the channel, and any buffered input
451 is discarded. If this is a blocking channel, the call does not return
452 until all buffered data is successfully sent to the channel's output
453 device. If this is a nonblocking channel and there is buffered output
454 that cannot be written without blocking, the call returns immediately;
455 output is flushed in the background and the channel will be closed once
456 all of the buffered data has been output. In this case errors during
457 flushing are not reported.
458 If the channel was closed successfully, Tcl_Close returns TCL_OK. If
460 an error occurs, Tcl_Close returns TCL_ERROR and records a POSIX error
461 code that can be retrieved with Tcl_GetErrno. If the channel is being
462 closed synchronously and an error occurs during closing of the channel
463 and interp is not NULL, an error message is left in the interpreter's
464 result.
465 Note: it is not safe to call Tcl_Close on a channel that has been reg‐
467 istered using Tcl_RegisterChannel; see the documentation for Tcl_Regis‐
468 terChannel, above, for details. If the channel has ever been given as
469 the chan argument in a call to Tcl_RegisterChannel, you should instead
470 use Tcl_UnregisterChannel, which will internally call Tcl_Close when
471 all calls to Tcl_RegisterChannel have been matched by corresponding
472 calls to Tcl_UnregisterChannel.
473
476 Tcl_ReadChars consumes bytes from channel, converting the bytes to
477 UTF-8 based on the channel's encoding and storing the produced data in
478 readObjPtr's string representation. The return value of Tcl_ReadChars
479 is the number of characters, up to charsToRead, that were stored in
480 readObjPtr. If an error occurs while reading, the return value is -1
481 and Tcl_ReadChars records a POSIX error code that can be retrieved with
482 Tcl_GetErrno.
483 Setting charsToRead to -1 will cause the command to read all characters
485 currently available (non-blocking) or everything until eof (blocking
486 mode).
487 The return value may be smaller than the value to read, indicating that
489 less data than requested was available. This is called a short read.
490 In blocking mode, this can only happen on an end-of-file. In nonblock‐
491 ing mode, a short read can also occur if there is not enough input cur‐
492 rently available: Tcl_ReadChars returns a short count rather than
493 waiting for more data.
494 If the channel is in blocking mode, a return value of zero indicates an
496 end-of-file condition. If the channel is in nonblocking mode, a return
497 value of zero indicates either that no input is currently available or
498 an end-of-file condition. Use Tcl_Eof and Tcl_InputBlocked to tell
499 which of these conditions actually occurred.
500 Tcl_ReadChars translates the various end-of-line representations into
502 the canonical \n internal representation according to the current end-
503 of-line recognition mode. End-of-line recognition and the various
504 platform-specific modes are described in the manual entry for the Tcl
505 fconfigure command.
506 As a performance optimization, when reading from a channel with the
508 encoding binary, the bytes are not converted to UTF-8 as they are read.
509 Instead, they are stored in readObjPtr's internal representation as a
510 byte-array object. The string representation of this object will only
511 be constructed if it is needed (e.g., because of a call to Tcl_Get‐
512 StringFromObj). In this way, byte-oriented data can be read from a
513 channel, manipulated by calling Tcl_GetByteArrayFromObj and related
514 functions, and then written to a channel without the expense of ever
515 converting to or from UTF-8.
516 Tcl_Read is similar to Tcl_ReadChars, except that it does not do encod‐
518 ing conversions, regardless of the channel's encoding. It is depre‐
519 cated and exists for backwards compatibility with non-internationalized
520 Tcl extensions. It consumes bytes from channel and stores them in
521 readBuf, performing end-of-line translations on the way. The return
522 value of Tcl_Read is the number of bytes, up to bytesToRead, written in
523 readBuf. The buffer produced by Tcl_Read is not null-terminated. Its
524 contents are valid from the zeroth position up to and excluding the
525 position indicated by the return value.
526 Tcl_ReadRaw is the same as Tcl_Read but does not compensate for stack‐
528 ing. While Tcl_Read (and the other functions in the API) always get
529 their data from the topmost channel in the stack the supplied channel
530 is part of, Tcl_ReadRaw does not. Thus this function is only usable for
531 transformational channel drivers, i.e. drivers used in the middle of a
532 stack of channels, to move data from the channel below into the trans‐
533 formation.
534
537 Tcl_GetsObj consumes bytes from channel, converting the bytes to UTF-8
538 based on the channel's encoding, until a full line of input has been
539 seen. If the channel's encoding is binary, each byte read from the
540 channel is treated as an individual Unicode character. All of the
541 characters of the line except for the terminating end-of-line charac‐
542 ter(s) are appended to lineObjPtr's string representation. The end-of-
543 line character(s) are read and discarded.
544 If a line was successfully read, the return value is greater than or
546 equal to zero and indicates the number of bytes stored in lineObjPtr.
547 If an error occurs, Tcl_GetsObj returns -1 and records a POSIX error
548 code that can be retrieved with Tcl_GetErrno. Tcl_GetsObj also returns
549 -1 if the end of the file is reached; the Tcl_Eof procedure can be used
550 to distinguish an error from an end-of-file condition.
551 If the channel is in nonblocking mode, the return value can also be -1
553 if no data was available or the data that was available did not contain
554 an end-of-line character. When -1 is returned, the Tcl_InputBlocked
555 procedure may be invoked to determine if the channel is blocked because
556 of input unavailability.
557 Tcl_Gets is the same as Tcl_GetsObj except the resulting characters are
559 appended to the dynamic string given by lineRead rather than a Tcl
560 object.
561
564 Tcl_Ungets is used to add data to the input queue of a channel, at
565 either the head or tail of the queue. The pointer input points to the
566 data that is to be added. The length of the input to add is given by
567 inputLen. A non-zero value of addAtEnd indicates that the data is to
568 be added at the end of queue; otherwise it will be added at the head of
569 the queue. If channel has a “sticky” EOF set, no data will be added to
570 the input queue. Tcl_Ungets returns inputLen or -1 if an error occurs.
571
574 Tcl_WriteChars accepts bytesToWrite bytes of character data at charBuf.
575 The UTF-8 characters in the buffer are converted to the channel's
576 encoding and queued for output to channel. If bytesToWrite is nega‐
577 tive, Tcl_WriteChars expects charBuf to be null-terminated and it out‐
578 puts everything up to the null.
579 Data queued for output may not appear on the output device immediately,
581 due to internal buffering. If the data should appear immediately, call
582 Tcl_Flush after the call to Tcl_WriteChars, or set the -buffering
583 option on the channel to none. If you wish the data to appear as soon
584 as a complete line is accepted for output, set the -buffering option on
585 the channel to line mode.
586 The return value of Tcl_WriteChars is a count of how many bytes were
588 accepted for output to the channel. This is either greater than zero
589 to indicate success or -1 to indicate that an error occurred. If an
590 error occurs, Tcl_WriteChars records a POSIX error code that may be
591 retrieved with Tcl_GetErrno.
592 Newline characters in the output data are translated to platform-spe‐
594 cific end-of-line sequences according to the -translation option for
595 the channel. This is done even if the channel has no encoding.
596 Tcl_WriteObj is similar to Tcl_WriteChars except it accepts a Tcl
598 object whose contents will be output to the channel. The UTF-8 charac‐
599 ters in writeObjPtr's string representation are converted to the chan‐
600 nel's encoding and queued for output to channel. As a performance
601 optimization, when writing to a channel with the encoding binary, UTF-8
602 characters are not converted as they are written. Instead, the bytes
603 in writeObjPtr's internal representation as a byte-array object are
604 written to the channel. The byte-array representation of the object
605 will be constructed if it is needed. In this way, byte-oriented data
606 can be read from a channel, manipulated by calling Tcl_GetByteArrayFro‐
607 mObj and related functions, and then written to a channel without the
608 expense of ever converting to or from UTF-8.
609 Tcl_Write is similar to Tcl_WriteChars except that it does not do
611 encoding conversions, regardless of the channel's encoding. It is dep‐
612 recated and exists for backwards compatibility with non-international‐
613 ized Tcl extensions. It accepts bytesToWrite bytes of data at byteBuf
614 and queues them for output to channel. If bytesToWrite is negative,
615 Tcl_Write expects byteBuf to be null-terminated and it outputs every‐
616 thing up to the null.
617 Tcl_WriteRaw is the same as Tcl_Write but does not compensate for
619 stacking. While Tcl_Write (and the other functions in the API) always
620 feed their input to the topmost channel in the stack the supplied chan‐
621 nel is part of, Tcl_WriteRaw does not. Thus this function is only
622 usable for transformational channel drivers, i.e. drivers used in the
623 middle of a stack of channels, to move data from the transformation
624 into the channel below it.
625
628 Tcl_Flush causes all of the buffered output data for channel to be
629 written to its underlying file or device as soon as possible. If the
630 channel is in blocking mode, the call does not return until all the
631 buffered data has been sent to the channel or some error occurred. The
632 call returns immediately if the channel is nonblocking; it starts a
633 background flush that will write the buffered data to the channel even‐
634 tually, as fast as the channel is able to absorb it.
635 The return value is normally TCL_OK. If an error occurs, Tcl_Flush
637 returns TCL_ERROR and records a POSIX error code that can be retrieved
638 with Tcl_GetErrno.
639
642 Tcl_Seek moves the access point in channel where subsequent data will
643 be read or written. Buffered output is flushed to the channel and
644 buffered input is discarded, prior to the seek operation.
645 Tcl_Seek normally returns the new access point. If an error occurs,
647 Tcl_Seek returns -1 and records a POSIX error code that can be
648 retrieved with Tcl_GetErrno. After an error, the access point may or
649 may not have been moved.
650
653 Tcl_Tell returns the current access point for a channel. The returned
654 value is -1 if the channel does not support seeking.
655
658 Tcl_TruncateChannel truncates the file underlying channel to a given │
659 length of bytes. It returns TCL_OK if the operation succeeded, and │
660 TCL_ERROR otherwise.
661
664 Tcl_GetChannelOption retrieves, in optionValue, the value of one of the
665 options currently in effect for a channel, or a list of all options and
666 their values. The channel argument identifies the channel for which to
667 query an option or retrieve all options and their values. If option‐
668 Name is not NULL, it is the name of the option to query; the option's
669 value is copied to the Tcl dynamic string denoted by optionValue. If
670 optionName is NULL, the function stores an alternating list of option
671 names and their values in optionValue, using a series of calls to
672 Tcl_DStringAppendElement. The various preexisting options and their
673 possible values are described in the manual entry for the Tcl fconfig‐
674 ure command. Other options can be added by each channel type. These
675 channel type specific options are described in the manual entry for the
676 Tcl command that creates a channel of that type; for example, the addi‐
677 tional options for TCP based channels are described in the manual entry
678 for the Tcl socket command. The procedure normally returns TCL_OK. If
679 an error occurs, it returns TCL_ERROR and calls Tcl_SetErrno to store
680 an appropriate POSIX error code.
681
684 Tcl_SetChannelOption sets a new value newValue for an option optionName
685 on channel. The procedure normally returns TCL_OK. If an error
686 occurs, it returns TCL_ERROR; in addition, if interp is non-NULL,
687 Tcl_SetChannelOption leaves an error message in the interpreter's
688 result.
689
692 Tcl_Eof returns a nonzero value if channel encountered an end of file
693 during the last input operation.
694
697 Tcl_InputBlocked returns a nonzero value if channel is in nonblocking
698 mode and the last input operation returned less data than requested
699 because there was insufficient data available. The call always returns
700 zero if the channel is in blocking mode.
701
704 Tcl_InputBuffered returns the number of bytes of input currently
705 buffered in the internal buffers for a channel. If the channel is not
706 open for reading, this function always returns zero.
707
710 Tcl_OutputBuffered returns the number of bytes of output currently
711 buffered in the internal buffers for a channel. If the channel is not
712 open for writing, this function always returns zero.
713
716 The handles returned from Tcl_GetChannelHandle depend on the platform
717 and the channel type. On Unix platforms, the handle is always a Unix
718 file descriptor as returned from the open system call. On Windows
719 platforms, the handle is a file HANDLE when the channel was created
720 with Tcl_OpenFileChannel, Tcl_OpenCommandChannel, or Tcl_MakeFileChan‐
721 nel. Other channel types may return a different type of handle on Win‐
722 dows platforms.
723
726 DString(3), fconfigure(n), filename(n), fopen(3), Tcl_CreateChannel(3)
727
730 access point, blocking, buffered I/O, channel, channel driver, end of
731 file, flush, input, nonblocking, output, read, seek, write
732Tcl 8.3 Tcl_OpenFileChannel(3)