ABCDEFGHIJKLMNOPQRSTUVWXYZ

OpenFileChnl

Tcl_OpenFileChannel(3)      Tcl Library Procedures      Tcl_OpenFileChannel(3)



______________________________________________________________________________

NAME
       Tcl_OpenFileChannel,    Tcl_OpenCommandChannel,    Tcl_MakeFileChannel,
       Tcl_GetChannel, Tcl_GetChannelNames, Tcl_GetChannelNamesEx,  Tcl_Regis-
       terChannel,  Tcl_UnregisterChannel, Tcl_Close, Tcl_ReadChars, Tcl_Read,
       Tcl_GetsObj,   Tcl_Gets,   Tcl_WriteObj,   Tcl_WriteChars,   Tcl_Write,
       Tcl_Flush,  Tcl_Seek, Tcl_Tell, Tcl_GetChannelOption, Tcl_SetChannelOp-
       tion,  Tcl_Eof,  Tcl_InputBlocked,  Tcl_InputBuffered,   Tcl_Ungets   -
       buffered I/O facilities using channels

SYNOPSIS
       #include <tcl.h>

       typedef ... Tcl_Channel;

       Tcl_Channel
       Tcl_OpenFileChannel(interp, fileName, mode, permissions)

       Tcl_Channel
       Tcl_OpenCommandChannel(interp, argc, argv, flags)

       Tcl_Channel                                                             |
       Tcl_MakeFileChannel(handle, readOrWrite)                                |

       Tcl_Channel
       Tcl_GetChannel(interp, channelName, modePtr)

       int                                                                     |
       Tcl_GetChannelNames(interp)                                             |

       int                                                                     |
       Tcl_GetChannelNamesEx(interp, pattern)                                  |

       void
       Tcl_RegisterChannel(interp, channel)

       int
       Tcl_UnregisterChannel(interp, channel)

       int
       Tcl_Close(interp, channel)

       int                                                                     |
       Tcl_ReadChars(channel, readObjPtr, charsToRead, appendFlag)             |

       int                                                                     |
       Tcl_Read(channel, byteBuf, bytesToRead)                                 |

       int                                                                     |
       Tcl_GetsObj(channel, lineObjPtr)                                        |

       int                                                                     |
       Tcl_Gets(channel, lineRead)                                             |

       int                                                                     |
       Tcl_Ungets(channel, input, inputLen, addAtEnd)                          |

       int                                                                     |
       Tcl_WriteObj(channel, writeObjPtr)                                      |

       int                                                                     |
       Tcl_WriteChars(channel, charBuf, bytesToWrite)                          |

       int                                                                     |
       Tcl_Write(channel, byteBuf, bytesToWrite)                               |

       int
       Tcl_Eof(channel)

       int
       Tcl_Flush(channel)

       int
       Tcl_InputBlocked(channel)

       int
       Tcl_InputBuffered(channel)

       int
       Tcl_Seek(channel, offset, seekMode)

       int
       Tcl_Tell(channel)

       int
       Tcl_GetChannelOption(interp, channel, optionName, optionValue)

       int
       Tcl_SetChannelOption(interp, channel, optionName, newValue)


ARGUMENTS
       Tcl_Interp        *interp            (in)      Used for error reporting
                                                      and to look up a channel
                                                      registered in it.

       char              *fileName          (in)      The  name  of a local or
                                                      network file.

       char              *mode              (in)      Specifies how  the  file
                                                      is  to be accessed.  May
                                                      have any of  the  values
                                                      allowed   for  the  mode
                                                      argument to the Tcl open
                                                      command.   For Tcl_Open-
                                                      CommandChannel,  may  be
                                                      NULL.

       int               permissions        (in)      POSIX-style   permission
                                                      flags such as 0644.   If
                                                      a  new  file is created,
                                                      these  permissions  will
                                                      be  set  on  the created
                                                      file.

       int               argc               (in)      The number  of  elements
                                                      in argv.

       char              **argv             (in)      Arguments for construct-
                                                      ing a command  pipeline.
                                                      These  values  have  the
                                                      same meaning as the non-
                                                      switch  arguments to the
                                                      Tcl exec command.

       int               flags              (in)      Specifies  the  disposi-
                                                      tion    of   the   stdio
                                                      handles in pipeline: OR-
                                                      ed     combination    of
                                                      TCL_STDIN,   TCL_STDOUT,
                                                      TCL_STDERR,          and
                                                      TCL_ENFORCE_MODE.     If
                                                      TCL_STDIN  is set, stdin
                                                      for the first  child  in
                                                      the  pipe  is  the  pipe
                                                      channel, otherwise it is
                                                      the same as the standard
                                                      input  of  the  invoking
                                                      process;   likewise  for
                                                      TCL_STDOUT           and
                                                      TCL_STDERR.           If
                                                      TCL_ENFORCE_MODE is  not
                                                      set,  then  the pipe can
                                                      redirect  stdio  handles
                                                      to  override  the  stdio
                                                      handles    for     which
                                                      TCL_STDIN,    TCL_STDOUT
                                                      and TCL_STDERR have been
                                                      set.  If it is set, then
                                                      such redirections  cause
                                                      an error.                |

       ClientData        han-                                                  |
       dle             (in)                               |                    |
                                                      Operating  system   spe- |
                                                      cific  handle for I/O to |
                                                      a file. For Unix this is |
                                                      a  file  descriptor, for |
                                                      Windows it is a  HANDLE. |

       int               readOr-                                               |
       Write        (in)                               |                       |
                                                      OR-ed   combination   of |
                                                      TCL_READABLE         and |
                                                      TCL_WRITABLE to indicate |
                                                      what    operations   are |
                                                      valid on handle.         |

       char              *channel-                                             |
       Name       (in)                               |                         |
                                                      The name of the channel.

       int               *modePtr           (out)     Points  at  an   integer
                                                      variable    that    will
                                                      receive an OR-ed  combi-
                                                      nation  of  TCL_READABLE
                                                      and TCL_WRITABLE  denot-
                                                      ing  whether the channel
                                                      is open for reading  and
                                                      writing.

       Tcl_Channel       channel            (in)      A  Tcl channel for input
                                                      or  output.   Must  have
                                                      been  the  return  value
                                                      from a procedure such as
                                                      Tcl_OpenFileChannel.

       Tcl_Obj           *readOb-                                              |
       jPtr        (in/out)                           |                        |
                                                      A  pointer  to   a   Tcl |
                                                      Object in which to store |
                                                      the characters read from |
                                                      the channel.             |

       int               char-                                                 |
       sToRead        (in)                               |                     |
                                                      The number of characters |
                                                      to  read  from the chan- |
                                                      nel.  If  the  channel's |
                                                      encoding is binary, this |
                                                      is  equivalent  to   the |
                                                      number  of bytes to read |
                                                      from the channel.        |

       int               append-                                               |
       Flag         (in)                               |                       |
                                                      If  non-zero,  data read |
                                                      from the channel will be |
                                                      appended  to the object. |
                                                      Otherwise, the data will |
                                                      replace   the   existing |
                                                      contents of the  object. |

       char              *read-                                                |
       Buf           (out)                              |                      |
                                                      A  buffer  in  which  to |
                                                      store   the  bytes  read |
                                                      from the channel.        |

       int               byte-                                                 |
       sToRead        (in)                               |                     |
                                                      The  number  of bytes to |
                                                      read from  the  channel. |
                                                      The  buffer readBuf must |
                                                      be large enough to  hold |
                                                      this many bytes.         |

       Tcl_Obj           *lineOb-                                              |
       jPtr        (in/out)                           |                        |
                                                      A  pointer  to   a   Tcl |
                                                      object in which to store |
                                                      the line read  from  the |
                                                      channel.   The line read |
                                                      will be appended to  the |
                                                      current   value  of  the |
                                                      object.                  |

       Tcl_DString       *lineRead          (in/out)                           ||
                                                      A   pointer   to  a  Tcl |
                                                      dynamic string in  which |
                                                      to  store  the line read |
                                                      from the channel.   Must |
                                                      have been initialized by |
                                                      the  caller.   The  line |
                                                      read will be appended to |
                                                      any data already in  the |
                                                      dynamic string.          |

       Tcl_Obj           *writeOb-                                             |
       jPtr       (in)                               |                         |
                                                      A  pointer  to   a   Tcl |
                                                      Object   whose  contents |
                                                      will be  output  to  the |
                                                      channel.                 |

       CONST char        *char-                                                |
       Buf           (in)                               |                      |
                                                      A buffer containing  the |
                                                      characters  to output to |
                                                      the channel.             |

       char              *byte-                                                |
       Buf           (in)                               |                      |
                                                      A  buffer containing the |
                                                      bytes to output  to  the |
                                                      channel.                 |

       int               bytesToWrite       (in)                               ||
                                                      The number of  bytes  to |
                                                      consume  from charBuf or |
                                                      byteBuf  and  output  to |
                                                      the channel.

       int               offset             (in)      How   far  to  move  the
                                                      access  point   in   the
                                                      channel   at  which  the
                                                      next  input  or   output
                                                      operation     will    be
                                                      applied,   measured   in
                                                      bytes  from the position
                                                      given by seekMode.   May
                                                      be  either  positive  or
                                                      negative.

       int               seekMode           (in)      Relative to which  point
                                                      to  seek; used with off-
                                                      set to calculate the new
                                                      access   point  for  the
                                                      channel.  Legal   values
                                                      are  SEEK_SET, SEEK_CUR,
                                                      and SEEK_END.

       char              *optionName        (in)      The name  of  an  option
                                                      applicable to this chan-
                                                      nel, such as  -blocking.
                                                      May have any of the val-
                                                      ues  accepted   by   the
                                                      fconfigure command.

       Tcl_DString       *optionValue       (in)      Where to store the value
                                                      of an option or  a  list
                                                      of all options and their
                                                      values. Must  have  been
                                                      initialized    by    the
                                                      caller.

       char              *newValue          (in)      New value for the option
                                                      given by optionName.     |

       char              *pat-                                                 |
       tern           (in)                               |                     |
                                                      The pattern to match on, |
                                                      passed   to  Tcl_String- |
                                                      Match, or NULL.          |

       char              *input             (in)                               ||
                                                      The  input  to  add to a |
                                                      channel buffer.          |

       int               inputLen           (in)                               ||
                                                      Length of the input      |

       int               addToEnd           (in)                               ||
                                                      Flag indicating  whether |
                                                      the   input   should  be |
                                                      added  to  the  end   or |
                                                      beginning of the channel |
                                                      buffer.
_________________________________________________________________


DESCRIPTION
       The Tcl channel mechanism provides a device-independent  and  platform-
       independent  mechanism  for performing buffered input and output opera-
       tions on a variety of file, socket,  and  device  types.   The  channel
       mechanism  is extensible to new channel types, by providing a low level
       channel driver for the  new  type;  the  channel  driver  interface  is
       described in the manual entry for Tcl_CreateChannel. The channel mecha-
       nism provides a buffering scheme modeled after Unix's standard I/O, and
       it also allows for nonblocking I/O on channels.

       The  procedures  described  in this manual entry comprise the C APIs of
       the generic layer of the channel architecture. For a description of the
       channel  driver  architecture  and how to implement channel drivers for
       new types of channels, see the manual entry for Tcl_CreateChannel.


TCL_OPENFILECHANNEL
       Tcl_OpenFileChannel opens a file specified by fileName  and  returns  a
       channel  handle  that  can  be  used to perform input and output on the
       file. This API is modeled after the fopen procedure of the  Unix  stan-
       dard  I/O  library.  The syntax and meaning of all arguments is similar
       to those given in the Tcl open command when  opening  a  file.   If  an
       error  occurs  while  opening  the channel, Tcl_OpenFileChannel returns
       NULL and records  a  POSIX  error  code  that  can  be  retrieved  with
       Tcl_GetErrno.   In addition, if interp is non-NULL, Tcl_OpenFileChannel
       leaves an error message in interp's result after any error.

       The newly created channel is not  registered  in  the  supplied  inter-
       preter;  to  register it, use Tcl_RegisterChannel, described below.  If
       one of the standard channels, stdin, stdout or  stderr  was  previously
       closed,  the  act  of  creating  the  new  channel also assigns it as a
       replacement for the standard channel.


TCL_OPENCOMMANDCHANNEL
       Tcl_OpenCommandChannel provides a C-level interface to the functions of
       the  exec  and  open  commands.   It creates a sequence of subprocesses
       specified by the argv and argc arguments and returns a channel that can
       be  used  to  communicate  with these subprocesses.  The flags argument
       indicates what sort  of  communication  will  exist  with  the  command
       pipeline.

       If the TCL_STDIN flag is set then the standard input for the first sub-
       process will be tied to the channel: writing to the channel  will  pro-
       vide  input  to the subprocess.  If TCL_STDIN is not set, then standard
       input for the first subprocess will be the same as  this  application's
       standard  input.   If  TCL_STDOUT  is set then standard output from the
       last subprocess can be read from the channel; otherwise it goes to this
       application's  standard  output.   If TCL_STDERR is set, standard error
       output for all subprocesses is returned to the channel and  results  in
       an error when the channel is closed; otherwise it goes to this applica-
       tion's standard error.  If TCL_ENFORCE_MODE is not set, then  argc  and
       argv  can redirect the stdio handles to override TCL_STDIN, TCL_STDOUT,
       and TCL_STDERR; if it is set, then it is an error for argc and argv  to
       override stdio channels for which TCL_STDIN, TCL_STDOUT, and TCL_STDERR
       have been set.

       If an error occurs while opening  the  channel,  Tcl_OpenCommandChannel
       returns  NULL and records a POSIX error code that can be retrieved with
       Tcl_GetErrno.  In  addition,  Tcl_OpenCommandChannel  leaves  an  error
       message in the interpreter's result if interp is not NULL.

       The  newly  created  channel  is  not registered in the supplied inter-
       preter; to register it, use Tcl_RegisterChannel, described  below.   If
       one  of  the  standard channels, stdin, stdout or stderr was previously
       closed, the act of creating the  new  channel  also  assigns  it  as  a
       replacement for the standard channel.


TCL_MAKEFILECHANNEL
       Tcl_MakeFileChannel makes a Tcl_Channel from an existing, platform-spe-
       cific, file handle.  The newly created channel is not registered in the
       supplied   interpreter;   to   register  it,  use  Tcl_RegisterChannel,
       described below.  If one of the standard  channels,  stdin,  stdout  or
       stderr  was previously closed, the act of creating the new channel also
       assigns it as a replacement for the standard channel.


TCL_GETCHANNEL
       Tcl_GetChannel returns a channel given the channelName used  to  create
       it with Tcl_CreateChannel and a pointer to a Tcl interpreter in interp.
       If a channel by that name is not registered in  that  interpreter,  the
       procedure  returns NULL. If the mode argument is not NULL, it points at
       an integer variable that will receive an OR-ed combination of TCL_READ-
       ABLE  and TCL_WRITABLE describing whether the channel is open for read-
       ing and writing.

       Tcl_GetChannelNames and Tcl_GetChannelNamesEx write the  names  of  the
       registered  channels  to  the  interpreter's  result  as a list object.
       Tcl_GetChannelNamesEx will filter these names according to the pattern.
       If  pattern  is  NULL,  then  it will not do any filtering.  The return
       value is TCL_OK if no errors occured writing to the  result,  otherwise
       it  is  TCL_ERROR,  and  the error message is left in the interpreter's
       result.


TCL_REGISTERCHANNEL
       Tcl_RegisterChannel adds a channel to the set of channels accessible in
       interp. After this call, Tcl programs executing in that interpreter can
       refer to the channel in input or output operations using the name given
       in the call to Tcl_CreateChannel.  After this call, the channel becomes
       the property of  the  interpreter,  and  the  caller  should  not  call
       Tcl_Close  for  the  channel;  the channel will be closed automatically
       when it is unregistered from the interpreter.

       Code executing outside of any Tcl interpreter  can  call  Tcl_Register-
       Channel  with interp as NULL, to indicate that it wishes to hold a ref-
       erence to this channel. Subsequently, the channel can be registered  in
       a  Tcl  interpreter and it will only be closed when the matching number
       of calls to Tcl_UnregisterChannel have been  made.   This  allows  code
       executing  outside  of  any interpreter to safely hold a reference to a
       channel that is also registered in a Tcl interpreter.


TCL_UNREGISTERCHANNEL
       Tcl_UnregisterChannel removes a channel from the set of channels acces-
       sible  in  interp. After this call, Tcl programs will no longer be able
       to use the channel's name to refer to the channel in that  interpreter.
       If  this  operation removed the last registration of the channel in any
       interpreter, the channel is also closed and destroyed.

       Code not associated with a Tcl interpreter can call Tcl_UnregisterChan-
       nel  with  interp as NULL, to indicate to Tcl that it no longer holds a
       reference to that channel. If this is the last reference to  the  chan-
       nel, it will now be closed.


TCL_CLOSE
       Tcl_Close  destroys  the channel channel, which must denote a currently
       open channel. The channel should not be registered in  any  interpreter
       when  Tcl_Close  is called. Buffered output is flushed to the channel's
       output device prior to destroying the channel, and any  buffered  input
       is  discarded.  If this is a blocking channel, the call does not return
       until all buffered data is successfully sent to  the  channel's  output
       device.   If this is a nonblocking channel and there is buffered output
       that cannot be written without blocking, the call returns  immediately;
       output is flushed in the background and the channel will be closed once
       all of the buffered data has been output.  In this case  errors  during
       flushing are not reported.

       If  the  channel was closed successfully, Tcl_Close returns TCL_OK.  If
       an error occurs, Tcl_Close returns TCL_ERROR and records a POSIX  error
       code  that can be retrieved with Tcl_GetErrno.  If the channel is being
       closed synchronously and an error occurs during closing of the  channel
       and  interp  is not NULL, an error message is left in the interpreter's
       result.

       Note: it is not safe to call Tcl_Close on a channel that has been  reg-
       istered using Tcl_RegisterChannel; see the documentation for Tcl_Regis-
       terChannel, above, for details. If the channel has ever been  given  as
       the  chan argument in a call to Tcl_RegisterChannel, you should instead
       use Tcl_UnregisterChannel, which will internally  call  Tcl_Close  when
       all  calls  to  Tcl_RegisterChannel  have been matched by corresponding
       calls to Tcl_UnregisterChannel.


TCL_READCHARS AND TCL_READ                                                     |
       Tcl_ReadChars consumes bytes from  channel,  converting  the  bytes  to |
       UTF-8  based on the channel's encoding and storing the produced data in |
       readObjPtr's string representation.  The return value of  Tcl_ReadChars |
       is  the  number  of  characters, up to charsToRead, that were stored in |
       objPtr.  If an error occurs while reading, the return value is  -1  and |
       Tcl_ReadChars  records  a  POSIX  error code that can be retrieved with |
       Tcl_GetErrno.                                                           |

       The return value may be smaller than the value to read, indicating that |
       less  data  than requested was available.  This is called a short read. |
       In blocking mode, this can only happen on an end-of-file.  In nonblock- |
       ing mode, a short read can also occur if there is not enough input cur- |
       rently available:  Tcl_ReadChars returns  a  short  count  rather  than |
       waiting for more data.                                                  |

       If the channel is in blocking mode, a return value of zero indicates an |
       end-of-file condition.  If the channel is in nonblocking mode, a return |
       value  of zero indicates either that no input is currently available or |
       an end-of-file condition.  Use Tcl_Eof  and  Tcl_InputBlocked  to  tell |
       which of these conditions actually occurred.                            |

       Tcl_ReadChars  translates  the various end-of-line representations into |
       the canonical \n internal representation according to the current  end- |
       of-line  recognition  mode.   End-of-line  recognition  and the various |
       platform-specific modes are described in the manual entry for  the  Tcl |
       fconfigure command.                                                     |

       As  a  performance  optimization,  when reading from a channel with the |
       encoding binary, the bytes are not converted to UTF-8 as they are read. |
       Instead,  they  are stored in readObjPtr's internal representation as a |
       byte-array object.  The string representation of this object will  only |
       be  constructed  if  it  is needed (e.g., because of a call to Tcl_Get- |
       StringFromObj).  In this way, byte-oriented data can  be  read  from  a |
       channel,  manipulated  by  calling  Tcl_GetByteArrayFromObj and related |
       functions, and then written to a channel without the  expense  of  ever |
       converting to or from UTF-8.                                            |

       Tcl_Read  is similar to Tcl_ReadChars, except that it doesn't do encod- |
       ing conversions, regardless of the channel's encoding.   It  is  depre- |
       cated and exists for backwards compatibility with non-internationalized |
       Tcl extensions.  It consumes bytes from channel and stores them in buf, |
       performing  end-of-line  translations  on the way.  The return value of |
       Tcl_Read is the number of bytes, up to toRead,  written  in  buf.   The |
       buffer  produced  by Tcl_Read is not NULL terminated.  Its contents are |
       valid from the zeroth position up to and excluding the  position  indi- |
       cated by the return value.                                              |


TCL_GETSOBJ AND TCL_GETS                                                       |
       Tcl_GetsObj  consumes bytes from channel, converting the bytes to UTF-8 |
       based on the channel's encoding, until a full line of  input  has  been |
       seen.   If  the  channel's  encoding is binary, each byte read from the |
       channel is treated as an individual  Unicode  character.   All  of  the |
       characters  of  the line except for the terminating end-of-line charac- |
       ter(s) are appended to lineObjPtr's string representation.  The end-of- |
       line character(s) are read and discarded.                               |

       If  a  line  was successfully read, the return value is greater than or |
       equal to zero and indicates the number of bytes stored  in  lineObjPtr. |
       If  an  error  occurs, Tcl_GetsObj returns -1 and records a POSIX error |
       code that can be retrieved with Tcl_GetErrno.  Tcl_GetsObj also returns |
       -1 if the end of the file is reached; the Tcl_Eof procedure can be used |
       to distinguish an error from an end-of-file condition.                  |

       If the channel is in nonblocking mode, the return value can also be  -1 |
       if no data was available or the data that was available did not contain |
       an end-of-line character.  When -1 is  returned,  the  Tcl_InputBlocked |
       procedure may be invoked to determine if the channel is blocked because |
       of input unavailability.                                                |

       Tcl_Gets is the same as Tcl_GetsObj except the resulting characters are |
       appended to the dynamic string given by dsPtr rather than a Tcl object. |


TCL_UNGETS                                                                     |
       Tcl_Ungets is used to add data to the input  queue  of  a  channel,  at |
       either  the  head or tail of the queue.  Input is a pointer to the data |
       that is to be added.  InputLen gives the length of the  input  to  add. |
       AddAtEnd,  in  non-zero,  indicates that the data is to be added at the |
       end of queue; otherwise it will be added at the head of the queue.   If |
       channel  has  a  "sticky"  EOF  set, no data will be added to the input |
       queue.  Tcl_Ungets returns inputLen or -1 if an error occurs.           |


TCL_WRITECHARS, TCL_WRITEOBJ, AND TCL_WRITE                                    |
       Tcl_WriteChars accepts bytesToWrite bytes of character data at charBuf. |
       The  UTF-8  characters  in  the  buffer  are converted to the channel's |
       encoding and queued for output to channel.  If  bytesToWrite  is  nega- |
       tive,  Tcl_WriteChars expects charBuf to be NULL terminated and it out- |
       puts everything up to the NULL.                                         |

       Data queued for output may not appear on the output device immediately, |
       due to internal buffering.  If the data should appear immediately, call |
       Tcl_Flush after the call  to  Tcl_WriteChars,  or  set  the  -buffering |
       option  on the channel to none.  If you wish the data to appear as soon |
       as a complete line is accepted for output, set the -buffering option on |
       the channel to line mode.                                               |

       The  return  value  of Tcl_WriteChars is a count of how many bytes were |
       accepted for output to the channel.  This is either greater  than  zero |
       to  indicate  success  or -1 to indicate that an error occurred.  If an |
       error occurs, Tcl_WriteChars records a POSIX error  code  that  may  be |
       retrieved with Tcl_GetErrno.                                            |

       Newline  characters  in the output data are translated to platform-spe- |
       cific end-of-line sequences according to the  -translation  option  for |
       the channel.  This is done even if the channel has no encoding.         |

       Tcl_WriteObj  is  similar  to  Tcl_WriteChars  except  it accepts a Tcl |
       object whose contents will be output to the channel.  The UTF-8 charac- |
       ters  in writeObjPtr's string representation are converted to the chan- |
       nel's encoding and queued for output  to  channel.   As  a  performance |
       optimization, when writing to a channel with the encoding binary, UTF-8 |
       characters are not converted as they are written.  Instead,  the  bytes |
       in  writeObjPtr's  internal  representation  as a byte-array object are |
       written to the channel.  The byte-array representation  of  the  object |
       will  be  constructed if it is needed.  In this way, byte-oriented data |
       can be read from a channel, manipulated by calling Tcl_GetByteArrayFro- |
       mObj  and  related functions, and then written to a channel without the |
       expense of ever converting to or from UTF-8.                            |

       Tcl_Write is similar to Tcl_WriteChars except that it doesn't do encod- |
       ing  conversions,  regardless  of the channel's encoding.  It is depre- |
       cated and exists for backwards compatibility with non-internationalized |
       Tcl  extensions.   It accepts bytesToWrite bytes of data at byteBuf and |
       queues them for  output  to  channel.   If  bytesToWrite  is  negative, |
       Tcl_Write  expects  byteBuf to be NULL terminated and it outputs every- |
       thing up to the NULL.


TCL_FLUSH
       Tcl_Flush causes all of the buffered output  data  for  channel  to  be
       written  to  its underlying file or device as soon as possible.  If the
       channel is in blocking mode, the call does not  return  until  all  the
       buffered data has been sent to the channel or some error occurred.  The
       call returns immediately if the channel is  nonblocking;  it  starts  a
       background flush that will write the buffered data to the channel even-
       tually, as fast as the channel is able to absorb it.

       The return value is normally TCL_OK.  If  an  error  occurs,  Tcl_Flush
       returns  TCL_ERROR and records a POSIX error code that can be retrieved
       with Tcl_GetErrno.


TCL_SEEK
       Tcl_Seek moves the access point in channel where subsequent  data  will
       be  read  or  written.  Buffered  output  is flushed to the channel and
       buffered input is discarded, prior to the seek operation.

       Tcl_Seek normally returns the new access point.  If  an  error  occurs,
       Tcl_Seek  returns  -1  and  records  a  POSIX  error  code  that can be
       retrieved with Tcl_GetErrno.  After an error, the access point  may  or
       may not have been moved.


TCL_TELL
       Tcl_Tell  returns  the current access point for a channel. The returned
       value is -1 if the channel does not support seeking.


TCL_GETCHANNELOPTION
       Tcl_GetChannelOption retrieves, in dsPtr,  the  value  of  one  of  the
       options currently in effect for a channel, or a list of all options and
       their values.  The channel argument identifies the channel for which to
       query  an  option or retrieve all options and their values.  If option-
       Name is not NULL, it is the name of the option to query;  the  option's
       value  is  copied  to the Tcl dynamic string denoted by optionValue. If
       optionName is NULL, the function stores an alternating list  of  option
       names  and  their  values  in  optionValue,  using a series of calls to
       Tcl_DStringAppendElement. The various  preexisting  options  and  their
       possible  values are described in the manual entry for the Tcl fconfig-
       ure command. Other options can be added by each  channel  type.   These
       channel type specific options are described in the manual entry for the
       Tcl command that creates a channel of that type; for example, the addi-
       tional options for TCP based channels are described in the manual entry
       for the Tcl socket command.  The procedure normally returns TCL_OK.  If
       an  error  occurs, it returns TCL_ERROR and calls Tcl_SetErrno to store
       an appropriate POSIX error code.


TCL_SETCHANNELOPTION
       Tcl_SetChannelOption sets  a  new  value  for  an  option  on  channel.
       OptionName  is the option to set and newValue is the value to set.  The
       procedure normally returns TCL_OK.  If  an  error  occurs,  it  returns
       TCL_ERROR;   in  addition,  if interp is non-NULL, Tcl_SetChannelOption
       leaves an error message in the interpreter's result.


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


TCL_INPUTBLOCKED
       Tcl_InputBlocked  returns  a nonzero value if channel is in nonblocking
       mode and the last input operation returned  less  data  than  requested
       because there was insufficient data available.  The call always returns
       zero if the channel is in blocking mode.


TCL_INPUTBUFFERED
       Tcl_InputBuffered returns  the  number  of  bytes  of  input  currently
       buffered  in  the internal buffers for a channel. If the channel is not
       open for reading, this function always returns zero.


PLATFORM ISSUES                                                                |
       The handles returned from Tcl_GetChannelHandle depend on  the  platform |
       and  the  channel type.  On Unix platforms, the handle is always a Unix |
       file descriptor as returned from the  open  system  call.   On  Windows |
       platforms,  the  handle  is  a file HANDLE when the channel was created |
       with Tcl_OpenFileChannel, Tcl_OpenCommandChannel, or  Tcl_MakeFileChan- |
       nel.  Other channel types may return a different type of handle on Win- |
       dows platforms.  On the Macintosh platform, the handle is a file refer- |
       ence number as returned from HOpenDF.


SEE ALSO
       DString(3), fconfigure(n), filename(n), fopen(2), Tcl_CreateChannel(3)


KEYWORDS
       access  point,  blocking, buffered I/O, channel, channel driver, end of
       file, flush, input, nonblocking, output, read, seek, write



Tcl                                   8.3               Tcl_OpenFileChannel(3)