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 value 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 value. Otherwise, the data will
202 replace the existing contents of
203 the value.
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 value 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 value.
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 value 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
286 The Tcl channel mechanism provides a device-independent and platform-
287 independent mechanism for performing buffered input and output opera‐
288 tions on a variety of file, socket, and device types. The channel
289 mechanism is extensible to new channel types, by providing a low-level
290 channel driver for the new type; the channel driver interface is
291 described in the manual entry for Tcl_CreateChannel. The channel mecha‐
292 nism provides a buffering scheme modeled after Unix's standard I/O, and
293 it also allows for nonblocking I/O on channels.
294 The procedures described in this manual entry comprise the C APIs of
296 the generic layer of the channel architecture. For a description of the
297 channel driver architecture and how to implement channel drivers for
298 new types of channels, see the manual entry for Tcl_CreateChannel.
299
301 Tcl_OpenFileChannel opens a file specified by fileName and returns a
302 channel handle that can be used to perform input and output on the
303 file. This API is modeled after the fopen procedure of the Unix stan‐
304 dard I/O library. The syntax and meaning of all arguments is similar
305 to those given in the Tcl open command when opening a file. If an
306 error occurs while opening the channel, Tcl_OpenFileChannel returns
307 NULL and records a POSIX error code that can be retrieved with
308 Tcl_GetErrno. In addition, if interp is non-NULL, Tcl_OpenFileChannel
309 leaves an error message in interp's result after any error. As of Tcl
310 8.4, the value-based API Tcl_FSOpenFileChannel should be used in pref‐
311 erence to Tcl_OpenFileChannel wherever possible.
312 The newly created channel is not registered in the supplied inter‐
314 preter; to register it, use Tcl_RegisterChannel, described below. If
315 one of the standard channels, stdin, stdout or stderr was previously
316 closed, the act of creating the new channel also assigns it as a
317 replacement for the standard channel.
318
320 Tcl_OpenCommandChannel provides a C-level interface to the functions of
321 the exec and open commands. It creates a sequence of subprocesses
322 specified by the argv and argc arguments and returns a channel that can
323 be used to communicate with these subprocesses. The flags argument
324 indicates what sort of communication will exist with the command pipe‐
325 line.
326 If the TCL_STDIN flag is set then the standard input for the first sub‐
328 process will be tied to the channel: writing to the channel will pro‐
329 vide input to the subprocess. If TCL_STDIN is not set, then standard
330 input for the first subprocess will be the same as this application's
331 standard input. If TCL_STDOUT is set then standard output from the
332 last subprocess can be read from the channel; otherwise it goes to this
333 application's standard output. If TCL_STDERR is set, standard error
334 output for all subprocesses is returned to the channel and results in
335 an error when the channel is closed; otherwise it goes to this applica‐
336 tion's standard error. If TCL_ENFORCE_MODE is not set, then argc and
337 argv can redirect the stdio handles to override TCL_STDIN, TCL_STDOUT,
338 and TCL_STDERR; if it is set, then it is an error for argc and argv to
339 override stdio channels for which TCL_STDIN, TCL_STDOUT, and TCL_STDERR
340 have been set.
341 If an error occurs while opening the channel, Tcl_OpenCommandChannel
343 returns NULL and records a POSIX error code that can be retrieved with
344 Tcl_GetErrno. In addition, Tcl_OpenCommandChannel leaves an error mes‐
345 sage in the interpreter's result. interp cannot be NULL.
346 The newly created channel is not registered in the supplied inter‐
348 preter; to register it, use Tcl_RegisterChannel, described below. If
349 one of the standard channels, stdin, stdout or stderr was previously
350 closed, the act of creating the new channel also assigns it as a
351 replacement for the standard channel.
352
354 Tcl_MakeFileChannel makes a Tcl_Channel from an existing, platform-spe‐
355 cific, file handle. The newly created channel is not registered in the
356 supplied interpreter; to register it, use Tcl_RegisterChannel,
357 described below. If one of the standard channels, stdin, stdout or
358 stderr was previously closed, the act of creating the new channel also
359 assigns it as a replacement for the standard channel.
360
362 Tcl_GetChannel returns a channel given the channelName used to create
363 it with Tcl_CreateChannel and a pointer to a Tcl interpreter in interp.
364 If a channel by that name is not registered in that interpreter, the
365 procedure returns NULL. If the modePtr argument is not NULL, it points
366 at an integer variable that will receive an OR-ed combination of
367 TCL_READABLE and TCL_WRITABLE describing whether the channel is open
368 for reading and writing.
369 Tcl_GetChannelNames and Tcl_GetChannelNamesEx write the names of the
371 registered channels to the interpreter's result as a list value.
372 Tcl_GetChannelNamesEx will filter these names according to the pattern.
373 If pattern is NULL, then it will not do any filtering. The return
374 value is TCL_OK if no errors occurred writing to the result, otherwise
375 it is TCL_ERROR, and the error message is left in the interpreter's
376 result.
377
379 Tcl_RegisterChannel adds a channel to the set of channels accessible in
380 interp. After this call, Tcl programs executing in that interpreter can
381 refer to the channel in input or output operations using the name given
382 in the call to Tcl_CreateChannel. After this call, the channel becomes
383 the property of the interpreter, and the caller should not call
384 Tcl_Close for the channel; the channel will be closed automatically
385 when it is unregistered from the interpreter.
386 Code executing outside of any Tcl interpreter can call Tcl_Register‐
388 Channel with interp as NULL, to indicate that it wishes to hold a ref‐
389 erence to this channel. Subsequently, the channel can be registered in
390 a Tcl interpreter and it will only be closed when the matching number
391 of calls to Tcl_UnregisterChannel have been made. This allows code
392 executing outside of any interpreter to safely hold a reference to a
393 channel that is also registered in a Tcl interpreter.
394 This procedure interacts with the code managing the standard channels.
396 If no standard channels were initialized before the first call to
397 Tcl_RegisterChannel, they will get initialized by that call. See
398 Tcl_StandardChannels for a general treatise about standard channels and
399 the behavior of the Tcl library with regard to them.
400
402 Tcl_UnregisterChannel removes a channel from the set of channels acces‐
403 sible in interp. After this call, Tcl programs will no longer be able
404 to use the channel's name to refer to the channel in that interpreter.
405 If this operation removed the last registration of the channel in any
406 interpreter, the channel is also closed and destroyed.
407 Code not associated with a Tcl interpreter can call Tcl_UnregisterChan‐
409 nel with interp as NULL, to indicate to Tcl that it no longer holds a
410 reference to that channel. If this is the last reference to the chan‐
411 nel, it will now be closed. Tcl_UnregisterChannel is very similar to
412 Tcl_DetachChannel except that it will also close the channel if no fur‐
413 ther references to it exist.
414
416 Tcl_DetachChannel removes a channel from the set of channels accessible
417 in interp. After this call, Tcl programs will no longer be able to use
418 the channel's name to refer to the channel in that interpreter. Beyond
419 that, this command has no further effect. It cannot be used on the
420 standard channels (stdout, stderr, stdin), and will return TCL_ERROR if
421 passed one of those channels.
422 Code not associated with a Tcl interpreter can call Tcl_DetachChannel
424 with interp as NULL, to indicate to Tcl that it no longer holds a ref‐
425 erence to that channel. If this is the last reference to the channel,
426 unlike Tcl_UnregisterChannel, it will not be closed.
427
429 Tcl_IsStandardChannel tests whether a channel is one of the three stan‐
430 dard channels, stdin, stdout or stderr. If so, it returns 1, otherwise
431 0.
432 No attempt is made to check whether the given channel or the standard
434 channels are initialized or otherwise valid.
435
437 Tcl_Close destroys the channel channel, which must denote a currently
438 open channel. The channel should not be registered in any interpreter
439 when Tcl_Close is called. Buffered output is flushed to the channel's
440 output device prior to destroying the channel, and any buffered input
441 is discarded. If this is a blocking channel, the call does not return
442 until all buffered data is successfully sent to the channel's output
443 device. If this is a nonblocking channel and there is buffered output
444 that cannot be written without blocking, the call returns immediately;
445 output is flushed in the background and the channel will be closed once
446 all of the buffered data has been output. In this case errors during
447 flushing are not reported.
448 If the channel was closed successfully, Tcl_Close returns TCL_OK. If
450 an error occurs, Tcl_Close returns TCL_ERROR and records a POSIX error
451 code that can be retrieved with Tcl_GetErrno. If the channel is being
452 closed synchronously and an error occurs during closing of the channel
453 and interp is not NULL, an error message is left in the interpreter's
454 result.
455 Note: it is not safe to call Tcl_Close on a channel that has been reg‐
457 istered using Tcl_RegisterChannel; see the documentation for Tcl_Regis‐
458 terChannel, above, for details. If the channel has ever been given as
459 the chan argument in a call to Tcl_RegisterChannel, you should instead
460 use Tcl_UnregisterChannel, which will internally call Tcl_Close when
461 all calls to Tcl_RegisterChannel have been matched by corresponding
462 calls to Tcl_UnregisterChannel.
463
465 Tcl_ReadChars consumes bytes from channel, converting the bytes to
466 UTF-8 based on the channel's encoding and storing the produced data in
467 readObjPtr's string representation. The return value of Tcl_ReadChars
468 is the number of characters, up to charsToRead, that were stored in
469 readObjPtr. If an error occurs while reading, the return value is -1
470 and Tcl_ReadChars records a POSIX error code that can be retrieved with
471 Tcl_GetErrno.
472 Setting charsToRead to -1 will cause the command to read all characters
474 currently available (non-blocking) or everything until eof (blocking
475 mode).
476 The return value may be smaller than the value to read, indicating that
478 less data than requested was available. This is called a short read.
479 In blocking mode, this can only happen on an end-of-file. In nonblock‐
480 ing mode, a short read can also occur if there is not enough input cur‐
481 rently available: Tcl_ReadChars returns a short count rather than
482 waiting for more data.
483 If the channel is in blocking mode, a return value of zero indicates an
485 end-of-file condition. If the channel is in nonblocking mode, a return
486 value of zero indicates either that no input is currently available or
487 an end-of-file condition. Use Tcl_Eof and Tcl_InputBlocked to tell
488 which of these conditions actually occurred.
489 Tcl_ReadChars translates the various end-of-line representations into
491 the canonical \n internal representation according to the current end-
492 of-line recognition mode. End-of-line recognition and the various
493 platform-specific modes are described in the manual entry for the Tcl
494 fconfigure command.
495 As a performance optimization, when reading from a channel with the
497 encoding binary, the bytes are not converted to UTF-8 as they are read.
498 Instead, they are stored in readObjPtr's internal representation as a
499 byte-array value. The string representation of this value will only be
500 constructed if it is needed (e.g., because of a call to Tcl_Get‐
501 StringFromObj). In this way, byte-oriented data can be read from a
502 channel, manipulated by calling Tcl_GetByteArrayFromObj and related
503 functions, and then written to a channel without the expense of ever
504 converting to or from UTF-8.
505 Tcl_Read is similar to Tcl_ReadChars, except that it does not do encod‐
507 ing conversions, regardless of the channel's encoding. It is depre‐
508 cated and exists for backwards compatibility with non-internationalized
509 Tcl extensions. It consumes bytes from channel and stores them in
510 readBuf, performing end-of-line translations on the way. The return
511 value of Tcl_Read is the number of bytes, up to bytesToRead, written in
512 readBuf. The buffer produced by Tcl_Read is not null-terminated. Its
513 contents are valid from the zeroth position up to and excluding the
514 position indicated by the return value.
515 Tcl_ReadRaw is the same as Tcl_Read but does not compensate for stack‐
517 ing. While Tcl_Read (and the other functions in the API) always get
518 their data from the topmost channel in the stack the supplied channel
519 is part of, Tcl_ReadRaw does not. Thus this function is only usable for
520 transformational channel drivers, i.e. drivers used in the middle of a
521 stack of channels, to move data from the channel below into the trans‐
522 formation.
523
525 Tcl_GetsObj consumes bytes from channel, converting the bytes to UTF-8
526 based on the channel's encoding, until a full line of input has been
527 seen. If the channel's encoding is binary, each byte read from the
528 channel is treated as an individual Unicode character. All of the
529 characters of the line except for the terminating end-of-line charac‐
530 ter(s) are appended to lineObjPtr's string representation. The end-of-
531 line character(s) are read and discarded.
532 If a line was successfully read, the return value is greater than or
534 equal to zero and indicates the number of bytes stored in lineObjPtr.
535 If an error occurs, Tcl_GetsObj returns -1 and records a POSIX error
536 code that can be retrieved with Tcl_GetErrno. Tcl_GetsObj also returns
537 -1 if the end of the file is reached; the Tcl_Eof procedure can be used
538 to distinguish an error from an end-of-file condition.
539 If the channel is in nonblocking mode, the return value can also be -1
541 if no data was available or the data that was available did not contain
542 an end-of-line character. When -1 is returned, the Tcl_InputBlocked
543 procedure may be invoked to determine if the channel is blocked because
544 of input unavailability.
545 Tcl_Gets is the same as Tcl_GetsObj except the resulting characters are
547 appended to the dynamic string given by lineRead rather than a Tcl
548 value.
549
551 Tcl_Ungets is used to add data to the input queue of a channel, at
552 either the head or tail of the queue. The pointer input points to the
553 data that is to be added. The length of the input to add is given by
554 inputLen. A non-zero value of addAtEnd indicates that the data is to
555 be added at the end of queue; otherwise it will be added at the head of
556 the queue. If channel has a “sticky” EOF set, no data will be added to
557 the input queue. Tcl_Ungets returns inputLen or -1 if an error occurs.
558
560 Tcl_WriteChars accepts bytesToWrite bytes of character data at charBuf.
561 The UTF-8 characters in the buffer are converted to the channel's
562 encoding and queued for output to channel. If bytesToWrite is nega‐
563 tive, Tcl_WriteChars expects charBuf to be null-terminated and it out‐
564 puts everything up to the null.
565 Data queued for output may not appear on the output device immediately,
567 due to internal buffering. If the data should appear immediately, call
568 Tcl_Flush after the call to Tcl_WriteChars, or set the -buffering
569 option on the channel to none. If you wish the data to appear as soon
570 as a complete line is accepted for output, set the -buffering option on
571 the channel to line mode.
572 The return value of Tcl_WriteChars is a count of how many bytes were
574 accepted for output to the channel. This is either greater than zero
575 to indicate success or -1 to indicate that an error occurred. If an
576 error occurs, Tcl_WriteChars records a POSIX error code that may be
577 retrieved with Tcl_GetErrno.
578 Newline characters in the output data are translated to platform-spe‐
580 cific end-of-line sequences according to the -translation option for
581 the channel. This is done even if the channel has no encoding.
582 Tcl_WriteObj is similar to Tcl_WriteChars except it accepts a Tcl value
584 whose contents will be output to the channel. The UTF-8 characters in
585 writeObjPtr's string representation are converted to the channel's
586 encoding and queued for output to channel. As a performance optimiza‐
587 tion, when writing to a channel with the encoding binary, UTF-8 charac‐
588 ters are not converted as they are written. Instead, the bytes in
589 writeObjPtr's internal representation as a byte-array value are written
590 to the channel. The byte-array representation of the value will be
591 constructed if it is needed. In this way, byte-oriented data can be
592 read from a channel, manipulated by calling Tcl_GetByteArrayFromObj and
593 related functions, and then written to a channel without the expense of
594 ever converting to or from UTF-8.
595 Tcl_Write is similar to Tcl_WriteChars except that it does not do
597 encoding conversions, regardless of the channel's encoding. It is dep‐
598 recated and exists for backwards compatibility with non-international‐
599 ized Tcl extensions. It accepts bytesToWrite bytes of data at byteBuf
600 and queues them for output to channel. If bytesToWrite is negative,
601 Tcl_Write expects byteBuf to be null-terminated and it outputs every‐
602 thing up to the null.
603 Tcl_WriteRaw is the same as Tcl_Write but does not compensate for
605 stacking. While Tcl_Write (and the other functions in the API) always
606 feed their input to the topmost channel in the stack the supplied chan‐
607 nel is part of, Tcl_WriteRaw does not. Thus this function is only
608 usable for transformational channel drivers, i.e. drivers used in the
609 middle of a stack of channels, to move data from the transformation
610 into the channel below it.
611
613 Tcl_Flush causes all of the buffered output data for channel to be
614 written to its underlying file or device as soon as possible. If the
615 channel is in blocking mode, the call does not return until all the
616 buffered data has been sent to the channel or some error occurred. The
617 call returns immediately if the channel is nonblocking; it starts a
618 background flush that will write the buffered data to the channel even‐
619 tually, as fast as the channel is able to absorb it.
620 The return value is normally TCL_OK. If an error occurs, Tcl_Flush
622 returns TCL_ERROR and records a POSIX error code that can be retrieved
623 with Tcl_GetErrno.
624
626 Tcl_Seek moves the access point in channel where subsequent data will
627 be read or written. Buffered output is flushed to the channel and
628 buffered input is discarded, prior to the seek operation.
629 Tcl_Seek normally returns the new access point. If an error occurs,
631 Tcl_Seek returns -1 and records a POSIX error code that can be
632 retrieved with Tcl_GetErrno. After an error, the access point may or
633 may not have been moved.
634
636 Tcl_Tell returns the current access point for a channel. The returned
637 value is -1 if the channel does not support seeking.
638
640 Tcl_TruncateChannel truncates the file underlying channel to a given
641 length of bytes. It returns TCL_OK if the operation succeeded, and
642 TCL_ERROR otherwise.
643
645 Tcl_GetChannelOption retrieves, in optionValue, the value of one of the
646 options currently in effect for a channel, or a list of all options and
647 their values. The channel argument identifies the channel for which to
648 query an option or retrieve all options and their values. If option‐
649 Name is not NULL, it is the name of the option to query; the option's
650 value is copied to the Tcl dynamic string denoted by optionValue. If
651 optionName is NULL, the function stores an alternating list of option
652 names and their values in optionValue, using a series of calls to
653 Tcl_DStringAppendElement. The various preexisting options and their
654 possible values are described in the manual entry for the Tcl fconfig‐
655 ure command. Other options can be added by each channel type. These
656 channel type specific options are described in the manual entry for the
657 Tcl command that creates a channel of that type; for example, the addi‐
658 tional options for TCP based channels are described in the manual entry
659 for the Tcl socket command. The procedure normally returns TCL_OK. If
660 an error occurs, it returns TCL_ERROR and calls Tcl_SetErrno to store
661 an appropriate POSIX error code.
662
664 Tcl_SetChannelOption sets a new value newValue for an option optionName
665 on channel. The procedure normally returns TCL_OK. If an error
666 occurs, it returns TCL_ERROR; in addition, if interp is non-NULL,
667 Tcl_SetChannelOption leaves an error message in the interpreter's
668 result.
669
671 Tcl_Eof returns a nonzero value if channel encountered an end of file
672 during the last input operation.
673
675 Tcl_InputBlocked returns a nonzero value if channel is in nonblocking
676 mode and the last input operation returned less data than requested
677 because there was insufficient data available. The call always returns
678 zero if the channel is in blocking mode.
679
681 Tcl_InputBuffered returns the number of bytes of input currently
682 buffered in the internal buffers for a channel. If the channel is not
683 open for reading, this function always returns zero.
684
686 Tcl_OutputBuffered returns the number of bytes of output currently
687 buffered in the internal buffers for a channel. If the channel is not
688 open for writing, this function always returns zero.
689
691 The handles returned from Tcl_GetChannelHandle depend on the platform
692 and the channel type. On Unix platforms, the handle is always a Unix
693 file descriptor as returned from the open system call. On Windows
694 platforms, the handle is a file HANDLE when the channel was created
695 with Tcl_OpenFileChannel, Tcl_OpenCommandChannel, or Tcl_MakeFileChan‐
696 nel. Other channel types may return a different type of handle on Win‐
697 dows platforms.
698
700 DString(3), fconfigure(n), filename(n), fopen(3), Tcl_CreateChannel(3)
701
703 access point, blocking, buffered I/O, channel, channel driver, end of
704 file, flush, input, nonblocking, output, read, seek, write
705Tcl 8.3 Tcl_OpenFileChannel(3)