DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

Tcl_WriteChars(3tcl)




Tcl_OpenFileChannel(3)Tcl Library ProcedureTcl_OpenFileChannel(3)

_________________________________________________________________


NAME

     Tcl_OpenFileChannel,                 Tcl_OpenCommandChannel,
     Tcl_MakeFileChannel,   Tcl_GetChannel,  Tcl_GetChannelNames,
     Tcl_GetChannelNamesEx,                  Tcl_RegisterChannel,
     Tcl_UnregisterChannel,                    Tcl_DetachChannel,
     Tcl_IsStandardChannel, Tcl_Close,  Tcl_ReadChars,  Tcl_Read,
     Tcl_GetsObj,    Tcl_Gets,    Tcl_WriteObj,   Tcl_WriteChars,
     Tcl_Write,       Tcl_Flush,       Tcl_Seek,        Tcl_Tell,
     Tcl_TruncateChannel,                   Tcl_GetChannelOption,
     Tcl_SetChannelOption,       Tcl_Eof,       Tcl_InputBlocked,
     Tcl_InputBuffered,      Tcl_OutputBuffered,      Tcl_Ungets,
     Tcl_ReadRaw, Tcl_WriteRaw - buffered  I/O  facilities  using
     channels


SYNOPSIS

     #include <tcl.h>

     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_DetachChannel(interp, channel)

     int
     Tcl_IsStandardChannel(channel)

     int
     Tcl_Close(interp, channel)

Tcl                     Last change: 8.3                        1

Tcl_OpenFileChannel(3)Tcl Library ProcedureTcl_OpenFileChannel(3)

     int
     Tcl_ReadChars(channel, readObjPtr, charsToRead, appendFlag)

     int
     Tcl_Read(channel, readBuf, 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_ReadRaw(channel, readBuf, bytesToRead)

     int
     Tcl_WriteRaw(channel, byteBuf, bytesToWrite)

     int
     Tcl_Eof(channel)

     int
     Tcl_Flush(channel)

     int
     Tcl_InputBlocked(channel)

     int
     Tcl_InputBuffered(channel)

     int
     Tcl_OutputBuffered(channel)

     Tcl_WideInt
     Tcl_Seek(channel, offset, seekMode)

     Tcl_WideInt
     Tcl_Tell(channel)

     int                                                           |

Tcl                     Last change: 8.3                        2

Tcl_OpenFileChannel(3)Tcl Library ProcedureTcl_OpenFileChannel(3)

     Tcl_TruncateChannel(channel, length)                          |

     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.

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

     const 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.

     int permissions (in)                   POSIX-style   permis-
                                            sion  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  ele-
                                            ments in argv.

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

     int flags (in)                         Specifies the  dispo-
                                            sition  of  the stdio
                                            handles in  pipeline:
                                            OR-ed  combination of
                                            TCL_STDIN,
                                            TCL_STDOUT,
                                            TCL_STDERR,       and

Tcl                     Last change: 8.3                        3

Tcl_OpenFileChannel(3)Tcl Library ProcedureTcl_OpenFileChannel(3)

                                            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 handle (in)                 Operating      system
                                            specific  handle  for
                                            I/O to  a  file.  For
                                            Unix  this  is a file
                                            descriptor, for  Win-
                                            dows it is a HANDLE.

     int readOrWrite (in)                   OR-ed combination  of
                                            TCL_READABLE      and
                                            TCL_WRITABLE to indi-
                                            cate  what operations
                                            are valid on handle.

     const 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_READABLE      and
                                            TCL_WRITABLE denoting
                                            whether  the  channel
                                            is  open  for reading
                                            and writing.

     const char *pattern (in)               The pattern to  match
                                            on,     passed     to

Tcl                     Last change: 8.3                        4

Tcl_OpenFileChannel(3)Tcl Library ProcedureTcl_OpenFileChannel(3)

                                            Tcl_StringMatch,   or
                                            NULL.

     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 *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
                                            channel.    If    the
                                            channel's encoding is
                                            binary,    this    is
                                            equivalent   to   the
                                            number  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.   Other-
                                            wise, the  data  will
                                            replace  the existing
                                            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
                                            channel.  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

Tcl                     Last change: 8.3                        5

Tcl_OpenFileChannel(3)Tcl Library ProcedureTcl_OpenFileChannel(3)

                                            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.

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

     int inputLen (in)                      Length of the input

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

     Tcl_Obj *writeObjPtr (in)              A pointer  to  a  Tcl
                                            Object whose contents
                                            will be output to the
                                            channel.

     const char *charBuf (in)               A  buffer  containing
                                            the   characters   to
                                            output to  the  chan-
                                            nel.

     const 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.

     Tcl_WideInt offset (in)                How far to  move  the
                                            access  point  in the
                                            channel at which  the
                                            next  input or output
                                            operation   will   be

Tcl                     Last change: 8.3                        6

Tcl_OpenFileChannel(3)Tcl Library ProcedureTcl_OpenFileChannel(3)

                                            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 calcu-
                                            late  the  new access
                                            point for  the  chan-
                                            nel. Legal values are
                                            SEEK_SET,   SEEK_CUR,
                                            and SEEK_END.

     Tcl_WideInt length (in)                The    (non-negative)
                                            length   to  truncate
                                            the channel the chan-
                                            nel to.

     const 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 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  ini-
                                            tialized    by    the
                                            caller.

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


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, and dev-
     ice types.  The channel mechanism is extensible to new chan-
     nel 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  mechanism
     provides  a  buffering  scheme modeled after Unix's standard
     I/O, and it also allows for nonblocking I/O on channels.

Tcl                     Last change: 8.3                        7

Tcl_OpenFileChannel(3)Tcl Library ProcedureTcl_OpenFileChannel(3)

     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 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_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. As of Tcl 8.4, the object-based  API
     Tcl_FSOpenFileChannel   should  be  used  in  preference  to
     Tcl_OpenFileChannel wherever possible.

     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_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 communi-
     cate with these subprocesses.  The flags argument  indicates
     what sort of communication will exist with the command pipe-
     line.

     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 subpro-
     cess can be read from the channel; otherwise it goes to this
     application's  standard output.  If TCL_STDERR is set, stan-
     dard 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 application'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                     Last change: 8.3                        8

Tcl_OpenFileChannel(3)Tcl Library ProcedureTcl_OpenFileChannel(3)

     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
     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_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  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 modePtr 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 channel
     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  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  occurred  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 execut-
     ing in that interpreter can refer to the channel in input or

Tcl                     Last change: 8.3                        9

Tcl_OpenFileChannel(3)Tcl Library ProcedureTcl_OpenFileChannel(3)

     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.  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 exe-
     cuting outside of any interpreter to safely hold a reference
     to a channel that is also registered in a Tcl interpreter.

     This procedure interacts with the code managing the standard
     channels.  If  no  standard channels were initialized before
     the first call to Tcl_RegisterChannel, they  will  get  ini-
     tialized  by  that call. See Tcl_StandardChannels for a gen-
     eral treatise about standard channels and the  behaviour  of
     the Tcl library with regard to them.


TCL_UNREGISTERCHANNEL

     Tcl_UnregisterChannel removes a  channel  from  the  set  of
     channels accessible 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_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_UnregisterChannel   is   very   similar    to
     Tcl_DetachChannel except that it will also close the channel
     if no further references to it exist.


TCL_DETACHCHANNEL

     Tcl_DetachChannel removes a channel from the set of channels
     accessible  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.  Beyond that, this command has
     no further effect.  It cannot be used on the standard  chan-
     nels  (stdout,  stderr, stdin), and will return TCL_ERROR if
     passed one of those channels.

     Code  not  associated  with  a  Tcl  interpreter  can   call
     Tcl_DetachChannel  with  interp  as NULL, to indicate to Tcl
     that it no longer holds a reference to that channel. If this

Tcl                     Last change: 8.3                       10

Tcl_OpenFileChannel(3)Tcl Library ProcedureTcl_OpenFileChannel(3)

     is    the    last   reference   to   the   channel,   unlike
     Tcl_UnregisterChannel, it will not be closed.


TCL_ISSTANDARDCHANNEL

     Tcl_IsStandardChannel tests whether a channel is one of  the
     three standard channels, stdin, stdout or stderr.  If so, it
     returns 1, otherwise 0.

     No attempt is made to check whether the given channel or the
     standard channels are initialized or otherwise valid.


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 destroy-
     ing 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 out-
     put  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 back-
     ground and the channel will be closed once all of  the  buf-
     fered  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  registered using Tcl_RegisterChannel; see the documen-
     tation 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 readObjPtr.  If

Tcl                     Last change: 8.3                       11

Tcl_OpenFileChannel(3)Tcl Library ProcedureTcl_OpenFileChannel(3)

     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.

     Setting charsToRead to -1 will cause the command to read all
     characters  currently available (non-blocking) or everything
     until eof (blocking mode).

     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 con-
     dition.  Use Tcl_Eof and Tcl_InputBlocked to tell  which  of
     these conditions actually occurred.

     Tcl_ReadChars translates the various end-of-line representa-
     tions  into the canonical \n internal representation accord-
     ing 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  com-
     mand.

     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  con-
     structed  if  it  is  needed  (e.g.,  because  of  a call to
     Tcl_GetStringFromObj).  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  does
     not  do  encoding  conversions,  regardless of the channel's
     encoding.  It is deprecated and exists for backwards  compa-
     tibility with non-internationalized Tcl extensions.  It con-
     sumes bytes from channel and stores them  in  readBuf,  per-
     forming  end-of-line  translations  on  the way.  The return
     value of Tcl_Read is the number of bytes, up to bytesToRead,
     written  in readBuf.  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

Tcl                     Last change: 8.3                       12

Tcl_OpenFileChannel(3)Tcl Library ProcedureTcl_OpenFileChannel(3)

     return value.

     Tcl_ReadRaw is the same as Tcl_Read but does not  compensate
     for stacking. While Tcl_Read (and the other functions in the
     API) always get their data from the topmost channel  in  the
     stack the supplied channel is part of, Tcl_ReadRaw does not.
     Thus this function is only usable for transformational chan-
     nel  drivers,  i.e. drivers used in the middle of a stack of
     channels, to move data  from  the  channel  below  into  the
     transformation.


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 character(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 una-
     vailability.

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


TCL_UNGETS

     Tcl_Ungets is used to add data to the input queue of a chan-
     nel,  at  either the head or tail of the queue.  The pointer
     input points to the data that is to be added.  The length of
     the  input to add is given by inputLen.  A non-zero value of
     addAtEnd 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                     Last change: 8.3                       13

Tcl_OpenFileChannel(3)Tcl Library ProcedureTcl_OpenFileChannel(3)


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 con-
     verted 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  every-
     thing 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  com-
     plete 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  indi-
     cate   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 out-
     put 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,  manipu-
     lated  by  calling Tcl_GetByteArrayFromObj and related func-
     tions, 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  does
     not  do  encoding  conversions,  regardless of the channel's
     encoding.  It is deprecated and exists for backwards  compa-
     tibility  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  out-
     puts everything up to the null.

Tcl                     Last change: 8.3                       14

Tcl_OpenFileChannel(3)Tcl Library ProcedureTcl_OpenFileChannel(3)

     Tcl_WriteRaw is the same as Tcl_Write but does  not  compen-
     sate  for stacking. While Tcl_Write (and the other functions
     in the API) always feed their input to the  topmost  channel
     in  the  stack the supplied channel is part of, Tcl_WriteRaw
     does not. Thus this function is only usable for  transforma-
     tional channel drivers, i.e. drivers used in the middle of a
     stack of channels, to move data from the transformation into
     the channel below it.


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  immedi-
     ately  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 seek-
     ing.


TCL_TRUNCATECHANNEL

     Tcl_TruncateChannel truncates the file underlying channel to  |
     a  given length of bytes. It returns TCL_OK if the operation  |
     succeeded, and TCL_ERROR otherwise.


TCL_GETCHANNELOPTION

     Tcl_GetChannelOption retrieves, in optionValue, the value of
     one  of  the options currently in effect for a channel, or a

Tcl                     Last change: 8.3                       15

Tcl_OpenFileChannel(3)Tcl Library ProcedureTcl_OpenFileChannel(3)

     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 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 option-
     Value.  If optionName is NULL, the function stores an alter-
     nating 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 fconfigure com-
     mand. 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 additional 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 newValue for an option
     optionName  on  channel.   The  procedure  normally  returns
     TCL_OK.  If an error occurs, it returns TCL_ERROR;  in addi-
     tion,  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.


TCL_OUTPUTBUFFERED

     Tcl_OutputBuffered returns the number  of  bytes  of  output
     currently buffered in the internal buffers for a channel. If
     the channel is not open for writing,  this  function  always

Tcl                     Last change: 8.3                       16

Tcl_OpenFileChannel(3)Tcl Library ProcedureTcl_OpenFileChannel(3)

     returns zero.


PLATFORM ISSUES

     The handles returned from Tcl_GetChannelHandle depend on the
     platform  and the channel type.  On Unix platforms, the han-
     dle 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_MakeFileChannel.  Other channel types may return a  dif-
     ferent type of handle on Windows platforms.


SEE ALSO

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


KEYWORDS

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

Tcl                     Last change: 8.3                       17


Man(1) output converted with man2html