tcl7.6 C API - OpenFileChnl






NAME

     Tcl_OpenFileChannel,   Tcl_OpenCommandChannel,    Tcl_Close,
     Tcl_Read,    Tcl_Gets,   Tcl_Write,   Tcl_Flush,   Tcl_Seek,
     Tcl_Tell, Tcl_Eof,  Tcl_InputBlocked,  Tcl_GetChannelOption,
     Tcl_SetChannelOption  -  buffered I/O facilities using chan-
     nels


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(inOsFile, outOsFile, readOrWrite)

     Tcl_Channel
     Tcl_GetChannel(interp, channelName, modePtr)

     void
     Tcl_RegisterChannel(interp, channel)

     int
     Tcl_UnregisterChannel(interp, channel)

     int
     Tcl_Close(interp, channel)

     int
     Tcl_Read(channel, buf, toRead)

     int
     Tcl_Gets(channel, lineRead)

     int
     Tcl_Write(channel, buf, toWrite)

     int
     Tcl_Flush(channel)

     int
     Tcl_Seek(channel, offset, seekMode)

     int
     Tcl_Tell(channel)
     int
     Tcl_GetChannelOption(channel, optionName, optionValue)

     int
     Tcl_SetChannelOption(interp, channel, optionName, newValue)

     int
     Tcl_Eof(channel)

     int
     Tcl_InputBlocked(channel)

     int
     Tcl_InputBuffered(channel)



ARGUMENTS

     Tcl_Interp        *interp            (in)      Used      for
                                                    error report-
                                                    ing  and   to
                                                    look   up   a
                                                    channel
                                                    registered in
                                                    it.

     char              *fileName          (in)      The name of a
                                                    local or net-
                                                    work file.

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

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

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

     char              **argv             (in)      Arguments for
                                                    constructing
                                                    a     command
                                                    pipeline.
                                                    These  values
                                                    have the same
                                                    meaning    as
                                                    the      non-
                                                    switch  argu-
                                                    ments  to the
                                                    Tcl exec com-
                                                    mand.

     int               flags              (in)      Specifies the
                                                    disposition
                                                    of the  stdio
                                                    handles    in
                                                    pipeline:
                                                    OR-ed  combi-
                                                    nation     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  stan-
                                                    dard 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 redirec-
                                                    tions   cause
                                                    an error.

     ClientData        inOsFile           (in)      Operating
                                                    system
                                                    specific han-
                                                    dle for input
                                                    from a  file.
                                                    For Unix this
                                                    is   a   file
                                                    descriptor,
                                                    for   Windows
                                                    it  is a HAN-
                                                    DLE, etc.

     ClientData        outOsFile          (in)      Operating
                                                    system
                                                    specific han-
                                                    dle  for out-
                                                    put   to    a
                                                    file.

     int               readOrWrite        (in)      OR-ed  combi-
                                                    nation     of
                                                    TCL_READABLE
                                                    and
                                                    TCL_WRITABLE
                                                    to   indicate
                                                    which      of
                                                    inOsFile  and
                                                    outOsFile
                                                    contains    a
                                                    valid value.

     int               *modePtr           (out)     Points at  an
                                                    integer vari-
                                                    able     that
                                                    will  receive
                                                    an      OR-ed
                                                    combination
                                                    of
                                                    TCL_READABLE
                                                    and
                                                    TCL_WRITABLE
                                                    denoting
                                                    whether   the
                                                    channel    is
                                                    open      for
                                                    reading   and
                                                    writing.

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

     char              *buf               (in)      An  array  of
                                                    bytes      in
                                                    which      to
                                                    store channel
                                                    input,     or
                                                    from which to
                                                    read  channel
                                                    output.

     int               len                (in)      The length of
                                                    the  input or
                                                    output.

     int               atEnd              (in)      If   nonzero,
                                                    store     the
                                                    input at  the
                                                    end   of  the
                                                    input  queue,
                                                    otherwise
                                                    store  it  at
                                                    the  head  of
                                                    the     input
                                                    queue.

     int               toRead             (in)      The number of
                                                    bytes to read
                                                    from      the
                                                    channel.

     Tcl_DString       *lineRead          (in)      A pointer  to
                                                    a Tcl dynamic
                                                    string     in
                                                    which      to
                                                    store     the
                                                    line     read
                                                    from      the
                                                    channel.
                                                    Must     have
                                                    been initial-
                                                    ized  by  the
                                                    caller.

     int               toWrite            (in)      The number of
                                                    bytes to read
                                                    from buf  and
                                                    output to the
                                                    channel.

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

     int               seekMode           (in)      Relative   to
                                                    which   point
                                                    to seek; used
                                                    with   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  fconfig-
                                                    ure 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 initial-
                                                    ized  by  the
                                                    caller.

     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 modelled after Unix's standard
     I/O, and it also allows for nonblocking I/O on channels.

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



TCL_OPENFILECHANNEL

     Tcl_OpenFileChannel opens a file specified by  fileName  and
     returns  a  channel handle that can be used to perform input
     and output on the file. This API is modelled 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-
     >result after any error.

     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_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
     interp->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 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 channel
     is open for reading and writing.



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



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_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 interp->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_READ

     Tcl_Read consumes up to toRead bytes of  data  from  channel
     and  stores  it at buf.  The return value of Tcl_Read is the
     number of characters written at buf.  The buffer produced by
     Tcl_Read is not NULL terminated. Its contents are valid from
     the zeroth position up to and excluding the  position  indi-
     cated  by  the return value.  If an error occurs, the return
     value is -1 and Tcl_Read records a POSIX error code that can
     be retrieved with Tcl_GetErrno.


     The return value may be smaller than the  value  of  toRead,
     indicating that less data than requested was available, also
     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_Read  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_Read translates platform-specific 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  fconfigure
     command.



TCL_GETS

     Tcl_Gets reads a line of input from a  channel  and  appends
     all of the characters of the line except for the terminating
     end-of-line character(s) to  the  dynamic  string  given  by
     dsPtr.  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 it indicates the number of char-
     acters stored in the dynamic string.  If  an  error  occurs,
     Tcl_Gets  returns -1 and records a POSIX error code that can
     be retrieved with Tcl_GetErrno.  Tcl_Gets 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_WRITE

     Tcl_Write accepts toWrite bytes of data at buf for output on
     channel.  This  data  may  not  appear  on the output device
     immediately. If the data  should  appear  immediately,  call
     Tcl_Flush after the call to Tcl_Write, or set the -buffering
     option on the channel to none.  If  you  wish  the  data  to
     appear as soon as an end of line is accepted for output, set
     the -buffering option on the channel to line mode.

     The toWrite argument specifies how many bytes  of  data  are
     provided  in  the buf argument. If it is negative, Tcl_Write
     expects the data to be NULL terminated and it outputs every-
     thing up to the NULL.

     The return value of Tcl_Write is a count of how many charac-
     ters were accepted for output to the channel. This is either
     equal to toWrite or -1 to indicate that an  error  occurred.
     If  an  error  occurs,  Tcl_Write also 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.



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_GETCHANNELOPTION

     Tcl_GetChannelOption retrieves, in dsPtr, the value  of  one
     of  the options currently in effect for a channel, or a list
     of all options and their values.  The channel argument iden-
     tifies  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_DStringAppendElement. The various
     preexisting options and their possible values are  described
     in  the  manual  entry for the Tcl fconfigure command. Other
     options can be added by each channel  type.   These  channel
     type  specific options are described in the manual entry for
     the Tcl command that creates a channel  of  that  type;  for
     example,  the  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 for an option on chan-
     nel.   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
     interp->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.



SEE ALSO

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



KEYWORDS

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