NAME

       Tcl_OpenFileChannel,   Tcl_OpenCommandChannel,   Tcl_Make­
       FileChannel,     Tcl_GetChannel,      Tcl_GetChannelNames,
       Tcl_GetChannelNamesEx,  Tcl_RegisterChannel,  Tcl_Unregis­
       terChannel, Tcl_Close, Tcl_ReadChars,  Tcl_Read,  Tcl_Get­
       sObj,  Tcl_Gets,  Tcl_WriteObj, Tcl_WriteChars, Tcl_Write,
       Tcl_Flush,   Tcl_Seek,   Tcl_Tell,   Tcl_GetChannelOption,
       Tcl_SetChannelOption,      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)                           |
       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 chan­
                                                      nel  regis­
                                                      tered    in
                                                      it.

       char              *fileName          (in)      The name of
                                                      a  local or
                                                      network
                                                      how     the
                                                      file  is to
                                                      be
                                                      accessed.
                                                      May    have
                                                      any  of the
                                                      values
                                                      allowed for
                                                      the    mode
                                                      argument to
                                                      the     Tcl
                                                      open   com­
                                                      mand.   For
                                                      Tcl_Open­
                                                      Command­
                                                      Channel,
                                                      may      be
                                                      NULL.

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

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

       char              **argv             (in)      Arguments
                                                      for    con­
                                                      structing a
                                                      command
                                                      pipeline.
                                                      These  val­
                                                      ues    have
                                                      the    same
                                                      meaning  as
                                                      the    non-
                                                      switch
                                                      arguments
                                                      to  the Tcl
                                                      exec   com­
                                                      mand.

                                                      sition   of
                                                      the   stdio
                                                      handles  in
                                                      pipeline:
                                                      OR-ed  com­
                                                      bination 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  invok­
                                                      ing    pro­
                                                      cess; like­
                                                      wise    for
                                                      TCL_STDOUT
                                                      and
                                                      TCL_STDERR.
                                                      If
                                                      TCL_ENFORCE_MODE
                                                      is not set,
                                                      then    the
                                                      pipe    can
                                                      redirect
                                                      stdio  han­
                                                      dles     to
                                                      override
                                                      the   stdio
                                                      handles for
                                                      which
                                                      TCL_STDIN,
                                                      TCL_STDOUT
                                                      and
                                                      TCL_STDERR
                                                      have   been
                                                      set.  If it
                                                      is     set,
                                                      then   such
                                                      an error.   |

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

       int               readOrWrite        (in)                         ||
                                                      OR-ed  com­ |
                                                      bination of |
                                                      TCL_READ­   |
                                                      ABLE    and |
                                                      TCL_WRITABLE|
                                                      to indicate |
                                                      what opera­ |
                                                      tions   are |
                                                      valid    on |
                                                      handle.     |

       char              *channelName       (in)                         ||
                                                      The name of |
                                                      the   chan­ |
                                                      nel.

       int               *modePtr           (out)     Points   at
                                                      an  integer
                                                      variable
                                                      that   will
                                                      receive  an
                                                      OR-ed  com­
                                                      bination of
                                                      TCL_READ­
                                                      ABLE    and
                                                      TCL_WRITABLE
                                                      denoting
                                                      whether the
                                                      channel  is
                                                      open    for
                                                      reading and
                                                      writing.

       Tcl_Channel       channel            (in)      A Tcl chan­
                                                      nel     for
                                                      Must   have
                                                      been    the
                                                      return
                                                      value  from
                                                      a procedure
                                                      such     as
                                                      Tcl_Open­
                                                      FileChan­
                                                      nel.

       Tcl_Obj           *readObjPtr        (in/out)                     ||
                                                      A   pointer |
                                                      to   a  Tcl |
                                                      Object   in |
                                                      which    to |
                                                      store   the |
                                                      characters  |
                                                      read   from |
                                                      the   chan­ |
                                                      nel.        |

       int               charsToRead        (in)                         ||
                                                      The  number |
                                                      of  charac­ |
                                                      ters     to |
                                                      read   from |
                                                      the   chan­ |
                                                      nel.     If |
                                                      the   chan­ |
                                                      nel's       |
                                                      encoding is |
                                                      binary,     |
                                                      this     is |
                                                      equivalent  |
                                                      to the num­ |
                                                      ber      of |
                                                      bytes    to |
                                                      read   from |
                                                      the   chan­ |
                                                      nel.        |

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

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

       int               bytesToRead        (in)                         ||
                                                      The  number |
                                                      of bytes to |
                                                      read   from |
                                                      the   chan­ |
                                                      nel.    The |
                                                      buffer      |
                                                      readBuf     |
                                                      must     be |
                                                      large       |
                                                      enough   to |
                                                      hold   this |
                                                      many bytes. |

       Tcl_Obj           *lineObjPtr        (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 cur­ |
                                                      rent  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.    |
                                                      tialized by |
                                                      the caller. |
                                                      The    line |
                                                      read   will |
                                                      be appended |
                                                      to any data |
                                                      already  in |
                                                      the dynamic |
                                                      string.     |

       Tcl_Obj           *writeObjPtr       (in)                         ||
                                                      A   pointer |
                                                      to   a  Tcl |
                                                      Object      |
                                                      whose  con­ |
                                                      tents  will |
                                                      be   output |
                                                      to      the |
                                                      channel.    |

       CONST                                                      |
       char        *charBuf           (in)                         ||
                                                      A    buffer |
                                                      containing  |
                                                      the charac­ |
                                                      ters     to |
                                                      output   to |
                                                      the   chan­ |
                                                      nel.        |

       char              *byteBuf           (in)                         ||
                                                      A    buffer |
                                                      containing  |
                                                      the   bytes |
                                                      to   output |
                                                      to      the |
                                                      channel.    |

       int               bytesToWrite       (in)                         ||
                                                      The  number |
                                                      of bytes to |
                                                      consume     |
                                                      from  char­ |
                                                      Buf      or |
                                                      byteBuf and |
                                                      output   to |
                                                      the   chan­ |
                                                      nel.

       int               offset             (in)      How far  to
                                                      move    the
                                                      access
                                                      at    which
                                                      the    next
                                                      input    or
                                                      output
                                                      operation
                                                      will     be
                                                      applied,
                                                      measured in
                                                      bytes  from
                                                      the   posi­
                                                      tion  given
                                                      by    seek­
                                                      Mode.   May
                                                      be   either
                                                      positive or
                                                      negative.

       int               seekMode           (in)      Relative to
                                                      which point
                                                      to    seek;
                                                      used   with
                                                      offset   to
                                                      calculate
                                                      the     new
                                                      access
                                                      point   for
                                                      the   chan­
                                                      nel.  Legal
                                                      values  are
                                                      SEEK_SET,
                                                      SEEK_CUR,
                                                      and
                                                      SEEK_END.

       char              *optionName        (in)      The name of
                                                      an   option
                                                      applicable
                                                      to     this
                                                      channel,
                                                      such     as
                                                      -blocking.
                                                      May    have
                                                      any  of the
                                                      values
                                                      accepted by
                                                      the   fcon­
                                                      figure com­
                                                      mand.

       Tcl_DString       *optionValue       (in)      Where    to
                                                      store   the
                                                      value of an
                                                      options and
                                                      their  val­
                                                      ues.   Must
                                                      have   been
                                                      initialized
                                                      by      the
                                                      caller.

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

       char              *pattern           (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  indi­ |
                                                      cating      |
                                                      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 operations on a variety of file,  socket,
       for   the  new  type;  the  channel  driver  interface  is
       described in the manual entry for  Tcl_CreateChannel.  The
       channel  mechanism  provides  a  buffering  scheme modeled
       after Unix's standard I/O, and it  also  allows  for  non­
       blocking 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  chan­
       nels, 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  standard  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_OpenFileChan­
       nel 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 sup­
       plied interpreter; to register it,  use  Tcl_RegisterChan­
       nel,  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 commu­
       nicate with these subprocesses.  The flags argument  indi­
       cates  what sort of communication will exist with the com­
       mand pipeline.

       If the TCL_STDIN flag is set then the standard  input  for
       the  first subprocess will be tied to the channel: writing
       to the channel will provide 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
       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  chan­
       nels  for which TCL_STDIN, TCL_STDOUT, and TCL_STDERR have
       been set.

       If an error occurs while opening the channel, Tcl_OpenCom­
       mandChannel  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  sup­
       plied  interpreter;  to register it, use Tcl_RegisterChan­
       nel, 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-specific, 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 previ­
       ously 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_READABLE and TCL_WRITABLE describing whether the chan­
       nel is open for reading 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  fil­
       ter  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, oth­
       erwise it is TCL_ERROR, and the error message is  left  in
       the interpreter's result.



TCL_REGISTERCHANNEL

       cuting  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_RegisterChannel with interp as NULL, to indicate  that
       it  wishes  to  hold  a  reference to this channel. Subse­
       quently, the channel can be registered  in  a  Tcl  inter­
       preter 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 accessible in interp. After this call,  Tcl  pro­
       grams  will no longer be able to use the channel's name to
       refer to the channel in that interpreter.  If this  opera­
       tion  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_UnregisterChannel  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 channel, 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 regis­
       tered  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  writ­
       ten 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
       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  registered  using  Tcl_RegisterChannel; see the
       documentation for Tcl_RegisterChannel, 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 charac­ |
       ters,  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 nonblocking mode, a |
       short read can also occur if there  is  not  enough  input |
       currently  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 represen­ |
       tations 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 fcon­ |
       figure 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 read­ |
       ObjPtr's  internal  representation as a byte-array object. |
       The string representation of this object will only be con­ |
       structed  if  it  is  needed  (e.g.,  because of a call to |
       Tcl_GetStringFromObj).  In this  way,  byte-oriented  data |
       written  to a channel without the expense of ever convert­ |
       ing to or from UTF-8.                                      |

       Tcl_Read is  similar  to  Tcl_ReadChars,  except  that  it |
       doesn't  do  encoding conversions, regardless of the chan­ |
       nel's encoding.  It is deprecated 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 indicated |
       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 encod­ |
       ing  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_Get­ |
       sObj 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  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- |
       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  negative,  Tcl_WriteChars |
       expects  charBuf  to  be  NULL  terminated  and it outputs |
       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-specific 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  characters  in  writeObjPtr's  string |
       representation are converted to the channel's encoding and |
       queued for output to channel.  As a performance  optimiza­ |
       tion,  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 representa­ |
       tion as a byte-array object are written  to  the  channel. |
       The  byte-array  representation of the object will be con­ |
       structed if it is needed.  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 convert­ |
       ing to or from UTF-8.                                      |

       Tcl_Write is similar  to  Tcl_WriteChars  except  that  it |
       doesn't  do  encoding conversions, regardless of the chan­ |
       nel's encoding.  It is deprecated and exists for backwards |
       queues  them  for  output  to channel.  If bytesToWrite is |
       negative, Tcl_Write expects byteBuf to be NULL  terminated |
       and it outputs everything up to the NULL.



TCL_FLUSH

       Tcl_Flush causes all of the buffered output data for chan­
       nel 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 eventually, 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 subse­
       quent 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  argu­
       ment  identifies  the channel for which to query an option
       or retrieve all options and their values.   If  optionName
       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_DStringAppen­
       dElement. The various preexisting options and their possi­
       ble  values  are described in the manual entry for the Tcl
       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 chan­
       nel 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_Open­ |
       FileChannel, Tcl_OpenCommandChannel, or  Tcl_MakeFileChan­ |
       nel.   Other  channel types may return a different type of |
       handle on Windows platforms.  On the  Macintosh  platform, |
       the  handle  is  a  file reference number as returned from |
       HOpenDF.



SEE ALSO




KEYWORDS

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