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  value  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                                              value.  Otherwise, the data will
202                                              replace the existing contents of
203                                              the value.
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  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
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  value  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

DESCRIPTION

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
295       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

TCL_OPENFILECHANNEL

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
313       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

TCL_OPENCOMMANDCHANNEL

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
327       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
342       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
347       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

TCL_MAKEFILECHANNEL

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

TCL_GETCHANNEL

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
370       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

TCL_REGISTERCHANNEL

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
387       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
395       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

TCL_UNREGISTERCHANNEL

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
408       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

TCL_DETACHCHANNEL

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
423       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

TCL_ISSTANDARDCHANNEL

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
433       No attempt is made to check whether the given channel or  the  standard
434       channels are initialized or otherwise valid.
435

TCL_CLOSE

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
449       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
456       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

TCL_READCHARS AND TCL_READ

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
473       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
477       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
484       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
490       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
496       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
506       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
516       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

TCL_GETSOBJ AND TCL_GETS

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
533       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
540       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
546       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

TCL_UNGETS

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

TCL_WRITECHARS, TCL_WRITEOBJ, AND TCL_WRITE

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
566       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
573       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
579       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
583       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
596       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
604       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

TCL_FLUSH

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
621       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

TCL_SEEK

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
630       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

TCL_TELL

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

TCL_TRUNCATECHANNEL

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

TCL_GETCHANNELOPTION

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

TCL_SETCHANNELOPTION

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

TCL_EOF

671       Tcl_Eof returns a nonzero value if channel encountered an end  of  file
672       during the last input operation.
673

TCL_INPUTBLOCKED

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

TCL_INPUTBUFFERED

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

TCL_OUTPUTBUFFERED

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

PLATFORM ISSUES

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

SEE ALSO

700       DString(3), fconfigure(n), filename(n), fopen(3), Tcl_CreateChannel(3)
701

KEYWORDS

703       access point, blocking, buffered I/O, channel, channel driver,  end  of
704       file, flush, input, nonblocking, output, read, seek, write
705
706
707
708Tcl                                   8.3               Tcl_OpenFileChannel(3)
Impressum