tcl7.6 C API - CrtChannel






NAME

     Tcl_CreateChannel,               Tcl_GetChannelInstanceData,
     Tcl_GetChannelType,  Tcl_GetChannelName, Tcl_GetChannelFile,
     Tcl_GetChannelMode,                Tcl_GetChannelBufferSize,
     Tcl_SetDefaultTranslation,  Tcl_SetChannelBufferSize  - pro-
     cedures for creating and manipulating channels


SYNOPSIS

     #include <tcl.h>

     Tcl_Channel
     Tcl_CreateChannel(typePtr, channelName, instanceData, mask)

     ClientData
     Tcl_GetChannelInstanceData(channel)

     Tcl_ChannelType *
     Tcl_GetChannelType(channel)

     char *
     Tcl_GetChannelName(channel)

     Tcl_File
     Tcl_GetChannelFile(channel, direction)

     int
     Tcl_GetChannelFlags(channel)

     void
     Tcl_SetDefaultTranslation(channel, transMode)

     int
     Tcl_GetChannelBufferSize(channel)

     void
     Tcl_SetChannelBufferSize(channel, size)



ARGUMENTS

     Tcl_ChannelType  *typePtr       (in)      Points to a struc-
                                               ture    containing
                                               the  addresses  of
                                               procedures    that
                                               can be  called  to
                                               perform   I/O  and
                                               other functions on
                                               the channel.

     char             *channelName   (in)      The name  of  this
                                               channel,  such  as
                                               file3; must not be
                                               in   use   by  any
                                               other channel. Can
                                               be  NULL, in which
                                               case  the  channel
                                               is created without
                                               a name.

     ClientData       instanceData   (in)      Arbitrary one-word
                                               value  to be asso-
                                               ciated  with  this
                                               channel.      This
                                               value is passed to
                                               procedures      in
                                               typePtr when  they
                                               are invoked.

     int              mask           (in)      OR-ed  combination
                                               of    TCL_READABLE
                                               and   TCL_WRITABLE
                                               to        indicate
                                               whether a  channel
                                               is   readable  and
                                               writable.

     Tcl_Channel      channel        (in)      The   channel   to
                                               operate on.

     int              direction      (in)      TCL_READABLE means
                                               the  input file is
                                               wanted;
                                               TCL_WRITABLE means
                                               the output file is
                                               wanted.

     Tcl_EolTranslation              transMode(in)
                                               The    translation
                                               mode;  one  of the
                                               constants
                                               TCL_TRANSLATE_AUTO,
                                               TCL_TRANSLATE_CR,
                                               TCL_TRANSLATE_LF
                                               and
                                               TCL_TRANSLATE_CRLF.

     int              size           (in)      The    size,    in
                                               bytes,  of buffers
                                               to   allocate   in
                                               this channel.





DESCRIPTION

     Tcl uses a two-layered channel architecture. It  provides  a
     generic  upper layer to enable C and Tcl programs to perform
     input and output using the same APIs for a variety of files,
     devices,  sockets  etc.  The generic C APIs are described in
     the manual entry for Tcl_OpenFileChannel.

     The lower layer provides type-specific channel  drivers  for
     each type of file, socket and device supported on each plat-
     form.  This manual entry describes the C APIs  used  by  the
     generic  layer  to  communicate  with  type-specific channel
     drivers to perform the input and output operations. It  also
     explains how new types of channels can be added by providing
     new channel drivers.

     Channel drivers consist of a number  of  components:  First,
     each  channel  driver  provides  a Tcl_ChannelType structure
     containing pointers to functions  implementing  the  various
     operations used by the generic layer to communicate with the
     channel driver. The Tcl_ChannelType structure and the  func-
     tions   referenced  by  it  are  described  in  the  section
     TCL_CHANNELTYPE, below.

     Second, channel drivers usually provide  a  Tcl  command  to
     create  instances  of that type of channel. For example, the
     Tcl open command creates channels that use the file and com-
     mand  channel  drivers,  and  the Tcl socket command creates
     channels that use TCP sockets for network communication.

     Third, a channel driver optionally provides a C function  to
     open   channel   instances   of   that  type.  For  example,
     Tcl_OpenFileChannel opens a channel that uses the file chan-
     nel  driver, and Tcl_OpenTcpClient opens a channel that uses
     the TCP network protocol.  These  creation  functions  typi-
     cally use Tcl_CreateChannel internally to open the channel.

     To add a new type of channel you must implement a C API or a
     Tcl    command    that   opens   a   channel   by   invoking
     Tcl_CreateChannel.  When your driver calls Tcl_CreateChannel
     it  passes  in  a  Tcl_ChannelType  structure describing the
     driver's I/O procedures.  The generic layer will then invoke
     the functions referenced in that structure to perform opera-
     tions on the channel.

     Tcl_CreateChannel opens a new  channel  and  associates  the
     supplied  typePtr  and  instanceData with it. The channel is
     opened in the mode indicated by mask.  For a  discussion  of
     channel  drivers,  their  operations and the Tcl_ChannelType
     structure, see the section TCL_CHANNELTYPE, below.

     Tcl_GetChannelInstanceData returns the instance data associ-
     ated  with  the  channel in channel. This is the same as the
     instanceData argument in the call to Tcl_CreateChannel  that
     created this channel.

     Tcl_GetChannelType returns a pointer to the  Tcl_ChannelType
     structure  used by the channel in the channel argument. This
     is  the  same  as  the  typePtr  argument  in  the  call  to
     Tcl_CreateChannel that created this channel.

     Tcl_GetChannelName returns  a  string  containing  the  name
     associated  with  the  channel,  or  NULL if the channelName
     argument to Tcl_CreateChannel was NULL.

     Tcl_GetChannelFile returns the inFile associated with  chan-
     nel  if  direction is TCL_READABLE, or the outFile if direc-
     tion is TCL_WRITABLE. The  operation  returns  NULL  if  the
     channel  is  not based on Tcl_Files or if the channel is not
     open for the specified direction.

     Tcl_GetChannelMode   returns   an   OR-ed   combination   of
     TCL_READABLE  and TCL_WRITABLE, indicating whether the chan-
     nel is open for input and output.

     Tcl_SetDefaultTranslation  sets  the  default  end  of  line
     translation  mode. This mode will be installed as the trans-
     lation mode for the channel if an attempt is made to  output
     on the channel while it is still in TCL_TRANSLATE_AUTO mode.
     For a description of end of line translation modes, see  the
     manual entry for fconfigure.

     Tcl_GetChannelBufferSize returns  the  size,  in  bytes,  of
     buffers  allocated  to store input or output in chan. If the
     value   was   not   set    by    a    previous    call    to
     Tcl_SetChannelBufferSize,  described below, then the default
     value of 4096 is returned.

     Tcl_SetChannelBufferSize sets the size, in bytes, of buffers
     that will be allocated in subsequent operations on the chan-
     nel to store input or output. The size  argument  should  be
     between  ten  and one million, allowing buffers of ten bytes
     to one  million  bytes.  If  size  is  outside  this  range,
     Tcl_SetChannelBufferSize sets the buffer size to 4096.



TCL_CHANNELTYPE

     A channel driver provides a Tcl_ChannelType  structure  that
     contains  pointers  to  functions that implement the various
     operations on a channel; these  operations  are  invoked  as
     needed  by  the generic layer. The Tcl_ChannelType structure
     contains the following fields:

          typedef struct Tcl_ChannelType {
            char *typeName;
            Tcl_DriverBlockModeProc *blockModeProc;
            Tcl_DriverCloseProc *closeProc;
            Tcl_DriverInputProc *inputProc;
            Tcl_DriverOutputProc *outputProc;
            Tcl_DriverSeekProc *seekProc;
            Tcl_DriverSetOptionProc *setOptionProc;
            Tcl_DriverGetOptionProc *getOptionProc;
            Tcl_DriverWatchChannelProc *watchChannelProc;
            Tcl_DriverChannelReadyProc *channelReadyProc;
            Tcl_DriverGetFileProc *getFileProc;
          } Tcl_ChannelType;

     The driver must provide implementations  for  all  functions
     except  blockModeProc,  seekProc,  setOptionProc, and getOp-
     tionProc, which may be specified as NULL  to  indicate  that
     the  channel does not support seeking.  Other functions that
     can not be implemented for this type of device should return
     EINVAL  when  invoked  to  indicate that they are not imple-
     mented.



TYPENAME

     The typeName field contains a  null-terminated  string  that
     identifies  the  type  of  the  device  implemented  by this
     driver, e.g.  file or socket.



BLOCKMODEPROC

     The blockModeProc field contains the address of  a  function
     called  by the generic layer to set blocking and nonblocking
     mode on the device.  BlockModeProc should match the  follow-
     ing prototype:

          typedef int Tcl_DriverBlockModeProc(
            ClientData instanceData,
            int mode);

     The  instanceData  is  the  same  as  the  value  passed  to
     Tcl_CreateChannel  when  this channel was created.  The mode
     argument is either TCL_MODE_BLOCKING or TCL_MODE_NONBLOCKING
     to  set  the  device  into blocking or nonblocking mode. The
     function should return zero if the operation was successful,
     or a nonzero POSIX error code if the operation failed.

     If the operation is successful, the function can modify  the
     supplied  instanceData  to  record  that the channel entered
     blocking or nonblocking mode and to implement  the  blocking
     or  nonblocking behavior.  For some device types, the block-
     ing and nonblocking  behavior  can  be  implemented  by  the
     underlying  operating  system;  for  other device types, the
     behavior must be emulated in the channel driver.


CLOSEPROC

     The closeProc field  contains  the  address  of  a  function
     called  by  the  generic  layer  to  clean up driver-related
     information when the channel is closed. CloseProc must match
     the following prototype:

          typedef int Tcl_DriverCloseProc(
            ClientData instanceData,
            Tcl_Interp *interp);

     The instanceData argument is the same as the value  provided
     to Tcl_CreateChannel when the channel was created. The func-
     tion should release any storage maintained  by  the  channel
     driver for this channel, and close the input and output dev-
     ices encapsulated by this channel. All  queued  output  will
     have  been  flushed  to  the  device before this function is
     called, and no further driver operations will be invoked  on
     this  instance  after  calling  the  closeProc. If the close
     operation is successful, the procedure should  return  zero;
     otherwise  it  should  return a nonzero POSIX error code. In
     addition, if an error occurs and interp  is  not  NULL,  the
     procedure should store an error message in interp->result.



INPUTPROC

     The inputProc field  contains  the  address  of  a  function
     called  by  the  generic layer to read data from the file or
     device and store it in an internal  buffer.  InputProc  must
     match the following prototype:

          typedef int Tcl_DriverInputProc(
            ClientData instanceData,
            char *buf,
            int bufSize,
            int *errorCodePtr);

     InstanceData  is  the  same   as   the   value   passed   to
     Tcl_CreateChannel  when  the  channel  was created.  The buf
     argument points to an array of bytes in which to store input
     from the device, and the bufSize argument indicates how many
     bytes are available at buf.

     The errorCodePtr argument points to an integer variable pro-
     vided by the generic layer. If an error occurs, the function
     should set the variable to a POSIX error code  that  identi-
     fies the error that occurred.

     The function should read data from the input device encapsu-
     lated  by  the channel and store it at buf.  On success, the
     function should return a nonnegative integer indicating  how
     many  bytes  were  read  from the input device and stored at
     buf. On error, the function should return -1.  If  an  error
     occurs  after  some data has been read from the device, that
     data is lost.

     If inputProc can determine that the input  device  has  some
     data  available but less than requested by the bufSize argu-
     ment, the function should only attempt to read as much  data
     as  is  available  and return without blocking. If the input
     device has no data available whatsoever and the  channel  is
     in  nonblocking  mode,  the function should return an EAGAIN
     error. If the input device has no data available  whatsoever
     and  the  channel  is  in blocking mode, the function should
     block for the shortest possible time until at least one byte
     of  data can be read from the device; then, it should return
     as much data as it can read without blocking.



OUTPUTPROC

     The outputProc field contains  the  address  of  a  function
     called  by the generic layer to transfer data from an inter-
     nal buffer to the output device.  OutputProc must match  the
     following prototype:

          typedef int Tcl_DriverOutputProc(
            ClientData instanceData,
            char *buf,
            int toWrite,
            int *errorCodePtr);

     InstanceData  is  the  same   as   the   value   passed   to
     Tcl_CreateChannel  when  the  channel  was  created. The buf
     argument contains an array of bytes to  be  written  to  the
     device,  and  the  toWrite argument indicates how many bytes
     are to be written from the buf argument.

     The errorCodePtr argument points to an integer variable pro-
     vided by the generic layer. If an error occurs, the function
     should set this variable to a POSIX error code that  identi-
     fies the error.

     The function should write the data at buf to the output dev-
     ice  encapsulated  by  the channel. On success, the function
     should return a  nonnegative  integer  indicating  how  many
     bytes  were  written to the output device.  The return value
     is normally the same as toWrite, but may  be  less  in  some
     cases  such  as  if the output operation is interrupted by a
     signal. If an error occurs the function  should  return  -1.
     In  case  of  error,  some data may have been written to the
     device.

     If the channel is  nonblocking  and  the  output  device  is
     unable  to  absorb  any data whatsoever, the function should
     return -1 with an EAGAIN error without writing any data.


SEEKPROC

     The seekProc field contains the address of a function called
     by  the generic layer to move the access point at which sub-
     sequent input or output operations will be applied. SeekProc
     must match the following prototype:

          typedef int Tcl_DriverSeekProc(
            ClientData instanceData,
            long offset,
            int seekMode,
            int *errorCodePtr);

     The instanceData argument is the same as the value given  to
     Tcl_CreateChannel when this channel was created.  Offset and
     seekMode have the same meaning as  for  the  Tcl_SeekChannel
     procedure    (described    in    the    manual   entry   for
     Tcl_OpenFileChannel).

     The errorCodePtr argument points to an integer variable pro-
     vided  by  the generic layer for returning errno values from
     the function.  The function should set this  variable  to  a
     POSIX  error  code  if an error occurs.  The function should
     store an EINVAL error code if  the  channel  type  does  not
     implement seeking.

     The return value is the new access point or -1  in  case  of
     error.  If  an  error occurred, the function should not move
     the access point.



SETOPTIONPROC

     The setOptionProc field contains the address of  a  function
     called  by  the generic layer to set a channel type specific
     option on a channel.  setOptionProc must match the following
     prototype:

          typedef int Tcl_DriverSetOptionProc(
            ClientData instanceData,
            Tcl_Interp *interp,
            char *optionName,
            char *optionValue);

     optionName is the name of an option to set, and  optionValue
     is the new value for that option, as a string. The instance-
     Data is the same as the  value  given  to  Tcl_CreateChannel
     when  this channel was created. The function should do what-
     ever channel type specific action is required  to  implement
     the new value of the option.

     Some options are handled by the generic code and this  func-
     tion  is  never  called  to set them, e.g. -blockmode. Other
     options  are  specific  to  each  channel   type   and   the
     setOptionProc  procedure  of  the  channel  driver  will get
     called to implement them. The  setOptionProc  field  can  be
     NULL,  which  indicates  that  this channel type supports no
     type specific options.

     If the option value is  successfully  modified  to  the  new
     value,  the function returns TCL_OK. It returns TCL_ERROR if
     the optionName is unrecognized or if optionValue specifies a
     value  for  the  option that is not supported. In this case,
     the function leaves an error message in the result field  of
     interp  if interp is not NULL. The function should also call
     Tcl_SetErrno to store an appropriate POSIX error code.



GETOPTIONPROC

     The getOptionProc field contains the address of  a  function
     called  by  the  generic layer to get the value of a channel
     type specific option on a channel. getOptionProc must  match
     the following prototype:

          typedef int Tcl_DriverGetOptionProc(
            ClientData instanceData,
            char *optionName,
            Tcl_DString *dsPtr);

     OptionName is the name of an option supported by  this  type
     of  channel.  If  the  option name is not NULL, the function
     stores its current value, as a string, in  the  Tcl  dynamic
     string dsPtr.  If optionName is NULL, the function stores in
     dsPtr an alternating list of all supported options and their
     current values.  On success, the function returns TCL_OK. If
     an error occurs, the function returns  TCL_ERROR  and  calls
     Tcl_SetErrno to store an appropriate POSIX error code.

     Some options are handled by the generic code and this  func-
     tion  is  never called to retrieve their value, e.g. -block-
     mode. Other options are specific to each  channel  type  and
     the  getOptionProc  procedure of the channel driver will get
     called to implement them. The  getOptionProc  field  can  be
     NULL,  which  indicates  that  this channel type supports no
     type specific options.



WATCHCHANNELPROC

     The watchChannelProc field contains the address of  a  func-
     tion  called  by  the  generic layer to initialize the event
     notification mechanism to notice events of interest on  this
     channel.  WatchChannelProc should match the following proto-
     type:

          typeded void Tcl_DriverWatchChannelProc(
            ClientData instanceData,
            int mask);

     The  instanceData  is  the  same  as  the  value  passed  to
     Tcl_CreateChannel  when  this  channel was created. The mask
     argument  is   an   OR-ed   combination   of   TCL_READABLE,
     TCL_WRITABLE  and  TCL_EXCEPTION;  it  indicates  events the
     caller is interested in noticing on this channel.

     The function should initialize device type specific  mechan-
     isms  to  notice when an event of interest is present on the
     channel. It may invoke  Tcl_SetMaxBlockTime  to  specify  an
     upper  limit on the length of time to wait for an event, and
     it may invoke Tcl_WatchFile if the channel implementation is
     based on Tcl_Files.



CHANNELREADYPROC

     The channelReadyProc field contains the address of  a  func-
     tion  called by the generic layer to sense whether events of
     interest have occurred for this  channel.   ChannelReadyProc
     should match the following prototype:

          typedef int Tcl_DriverChannelReadyProc(
            ClientData instanceData,
            int mask);

     InstanceData  is  the  same   as   the   value   passed   to
     Tcl_CreateChannel  when  this  channel was created. The mask
     argument  is   an   OR-ed   combination   of   TCL_READABLE,
     TCL_WRITABLE and TCL_EXCEPTION indicating what events are of
     interest. The function returns a mask  containing  an  OR-ed
     combination  of  a  subset  of the flags in mask to indicate
     what events have actually occurred on the channel.

     The function should use a device type dependent mechanism to
     detect whether events of interest have occurred on the chan-
     nel. It may invoke Tcl_FileReady if the channel  implementa-
     tion is based on Tcl_Files.



GETFILEPROC

     The getFileProc field contains the  address  of  a  function
     called  by the generic layer to retrieve a Tcl_File from the
     channel.  GetFileProc should match the following prototype:

          typedef Tcl_File Tcl_DriverGetFileProc(
            ClientData instanceData,
            int direction);

     InstanceData  is  the  same   as   the   value   passed   to
     Tcl_CreateChannel  when this channel was created. The direc-
     tion  argument  is  either  TCL_READABLE  to  retrieve   the
     Tcl_File  used  for  input,  or TCL_WRITABLE to retrieve the
     Tcl_File used for output.

     If the channel implementation is  based  on  Tcl_Files,  the
     function should retrieve the appropriate Tcl_File associated
     with the channel, according the direction argument;  it  can
     return  NULL  if the channel is not open for that direction.
     If the channel implementation does not  use  Tcl_Files,  the
     function should always return NULL.



SEE ALSO

     Tcl_Close(3),    Tcl_OpenFileChannel(3),    Tcl_SetErrno(3),
     Tcl_SetMaxBlockTime(3), Tcl_WatchFile(3), Tcl_FileReady(3)




KEYWORDS

     blocking,  channel  driver,  channel  registration,  channel
     type, nonblocking