1Tcl_OpenFileChannel(3)      Tcl Library Procedures      Tcl_OpenFileChannel(3)
2
3
4
5______________________________________________________________________________
6

NAME

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

SYNOPSIS

19       #include <tcl.h>
20
21       Tcl_Channel
22       Tcl_OpenFileChannel(interp, fileName, mode, permissions)
23
24       Tcl_Channel
25       Tcl_OpenCommandChannel(interp, argc, argv, flags)
26
27       Tcl_Channel
28       Tcl_MakeFileChannel(handle, readOrWrite)
29
30       Tcl_Channel
31       Tcl_GetChannel(interp, channelName, modePtr)
32
33       int
34       Tcl_GetChannelNames(interp)
35
36       int
37       Tcl_GetChannelNamesEx(interp, pattern)
38
39       void
40       Tcl_RegisterChannel(interp, channel)
41
42       int
43       Tcl_UnregisterChannel(interp, channel)
44
45       int
46       Tcl_DetachChannel(interp, channel)
47
48       int
49       Tcl_IsStandardChannel(channel)
50
51       int
52       Tcl_Close(interp, channel)
53
54       int
55       Tcl_ReadChars(channel, readObjPtr, charsToRead, appendFlag)
56
57       int
58       Tcl_Read(channel, readBuf, bytesToRead)
59
60       int
61       Tcl_GetsObj(channel, lineObjPtr)
62
63       int
64       Tcl_Gets(channel, lineRead)
65
66       int
67       Tcl_Ungets(channel, input, inputLen, addAtEnd)
68
69       int
70       Tcl_WriteObj(channel, writeObjPtr)
71
72       int
73       Tcl_WriteChars(channel, charBuf, bytesToWrite)
74
75       int
76       Tcl_Write(channel, byteBuf, bytesToWrite)
77
78       int
79       Tcl_ReadRaw(channel, readBuf, bytesToRead)
80
81       int
82       Tcl_WriteRaw(channel, byteBuf, bytesToWrite)
83
84       int
85       Tcl_Eof(channel)
86
87       int
88       Tcl_Flush(channel)
89
90       int
91       Tcl_InputBlocked(channel)
92
93       int
94       Tcl_InputBuffered(channel)
95
96       int
97       Tcl_OutputBuffered(channel)
98
99       Tcl_WideInt
100       Tcl_Seek(channel, offset, seekMode)
101
102       Tcl_WideInt
103       Tcl_Tell(channel)
104
105       int                                                                     │
106       Tcl_TruncateChannel(channel, length)                                    │
107
108       int
109       Tcl_GetChannelOption(interp, channel, optionName, optionValue)
110
111       int
112       Tcl_SetChannelOption(interp, channel, optionName, newValue)
113
114

ARGUMENTS

116       Tcl_Interp *interp (in)                Used  for error reporting and to
117                                              look up a channel registered  in
118                                              it.
119
120       const char *fileName (in)              The  name  of a local or network
121                                              file.
122
123       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
129       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
134       int argc (in)                          The number of elements in argv.
135
136       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
142       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
162       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
167       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
172       const char *channelName (in)           The name of the channel.
173
174       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
181       const char *pattern (in)               The pattern to match on,  passed
182                                              to Tcl_StringMatch, or NULL.
183
184       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
189       Tcl_Obj *readObjPtr (in/out)           A pointer to  a  Tcl  Object  in
190                                              which  to  store  the characters
191                                              read from the channel.
192
193       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
199       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
205       char *readBuf (out)                    A buffer in which to  store  the
206                                              bytes read from the channel.
207
208       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
213       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
219       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
227       const char *input (in)                 The input to add  to  a  channel
228                                              buffer.
229
230       int inputLen (in)                      Length of the input
231
232       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
237       Tcl_Obj *writeObjPtr (in)              A pointer to a Tcl Object  whose
238                                              contents  will  be output to the
239                                              channel.
240
241       const char *charBuf (in)               A buffer containing the  charac‐
242                                              ters to output to the channel.
243
244       const char *byteBuf (in)               A buffer containing the bytes to
245                                              output to the channel.
246
247       int bytesToWrite (in)                  The number of bytes  to  consume
248                                              from charBuf or byteBuf and out‐
249                                              put to the channel.
250
251       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
259       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
266       Tcl_WideInt length (in)                The   (non-negative)  length  to
267                                              truncate the channel the channel
268                                              to.
269
270       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
276       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
281       const char *newValue (in)              New value for the  option  given
282                                              by optionName.
283_________________________________________________________________
284
285

DESCRIPTION

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

TCL_OPENFILECHANNEL

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

TCL_OPENCOMMANDCHANNEL

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
330       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
345       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
350       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
356

TCL_MAKEFILECHANNEL

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
365

TCL_GETCHANNEL

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

TCL_REGISTERCHANNEL

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
393       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
401       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
407

TCL_UNREGISTERCHANNEL

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

TCL_DETACHCHANNEL

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

TCL_ISSTANDARDCHANNEL

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
442       No attempt is made to check whether the given channel or  the  standard
443       channels are initialized or otherwise valid.
444
445

TCL_CLOSE

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
459       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
466       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
474

TCL_READCHARS AND TCL_READ

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
484       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
488       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
495       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
501       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
507       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
517       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
527       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
535

TCL_GETSOBJ AND TCL_GETS

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
545       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
552       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
558       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
562

TCL_UNGETS

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
572

TCL_WRITECHARS, TCL_WRITEOBJ, AND TCL_WRITE

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
580       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
587       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
593       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
597       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
610       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
618       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
626

TCL_FLUSH

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

TCL_SEEK

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

TCL_TELL

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
656

TCL_TRUNCATECHANNEL

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
662

TCL_GETCHANNELOPTION

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
682

TCL_SETCHANNELOPTION

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
690

TCL_EOF

692       Tcl_Eof returns a nonzero value if channel encountered an end  of  file
693       during the last input operation.
694
695

TCL_INPUTBLOCKED

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
702

TCL_INPUTBUFFERED

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
708

TCL_OUTPUTBUFFERED

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
714

PLATFORM ISSUES

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
724

SEE ALSO

726       DString(3), fconfigure(n), filename(n), fopen(3), Tcl_CreateChannel(3)
727
728

KEYWORDS

730       access point, blocking, buffered I/O, channel, channel driver,  end  of
731       file, flush, input, nonblocking, output, read, seek, write
732
733
734
735Tcl                                   8.3               Tcl_OpenFileChannel(3)
Impressum