About Us Documentation

Contact Site Map
 

  

WinPak
Documentation

CrtChannel





Tcl_CreateChannel(3) Tcl Library Procedures                   8.0



_________________________________________________________________

NAME

Tcl_CreateChannel,               Tcl_GetChannelInstanceData,
     Tcl_GetChannelType,                      Tcl_GetChannelName,
     Tcl_GetChannelHandle,                    Tcl_GetChannelMode,
     Tcl_GetChannelBufferSize,         Tcl_SetDefaultTranslation,
     Tcl_SetChannelBufferSize,                 Tcl_NotifyChannel,
     Tcl_BadChannelOption  -  procedures for creating and manipu-
     lating 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)

     int                                                           |
     Tcl_GetChannelHandle(channel, direction, handlePtr)           |

     int
     Tcl_GetChannelFlags(channel)

     Tcl_SetDefaultTranslation(channel, transMode)

     int
     Tcl_GetChannelBufferSize(channel)

     Tcl_SetChannelBufferSize(channel, size)

     Tcl_NotifyChannel(channel, mask)                              |

     int                                                           |
     Tcl_BadChannelOption(interp, optionName, optionList)          |


ARGUMENTS

Tcl_ChannelType      *typePtr       (in)      Points  to   a
                                                   structure con-
                                                   taining    the
                                                   addresses   of
                                                   procedures
                                                   that   can  be



Tcl                                                             1






Tcl_CreateChannel(3) Tcl Library Procedures                   8.0



                                                   called to per-
                                                   form  I/O  and
                                                   other    func-
                                                   tions  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  associ-
                                                   ated with this
                                                   channel.  This
                                                   value       is
                                                   passed to pro-
                                                   cedures     in
                                                   typePtr   when
                                                   they       are
                                                   invoked.

     int                  mask           (in)      OR-ed combina-
                                                   tion        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   handle  |
                                                   is     wanted;  |
                                                   TCL_WRITABLE  |
                                                   means      the  |



Tcl                                                             2






Tcl_CreateChannel(3) Tcl Library Procedures                   8.0



                                                   output  handle  |
                                                   is wanted.      |

     ClientData           *handlePtr     (out)                          ||
                                                   Points  to the  |
                                                   location where  |
                                                   the    desired  |
                                                   OS-specific  |
                                                   handle  should  |
                                                   be stored.

     Tcl_EolTranslation   transMode      (in)      The   transla-
                                                   tion mode; one
                                                   of  the   con-
                                                   stants
                                                   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.   |

     int                  mask           (in)                           ||
                                                   An  OR-ed com-  |
                                                   bination    of  |
                                                   TCL_READABLE,  |
                                                   TCL_WRITABLE  |
                                                   and  |
                                                   TCL_EXCEPTION  |
                                                   that indicates  |
                                                   events    that  |
                                                   have  occurred  |
                                                   on this  chan-  |
                                                   nel.            |

     Tcl_Interp           *interp        (in)                           ||
                                                   Current inter-  |
                                                   preter.   (can  |
                                                   be NULL)        |

     char                 *optionName    (in)                           ||
                                                   Name   of  the  |
                                                   invalid  |
                                                   option.         |

     char                 *optionList    (in)                           ||
                                                   Specific  |



Tcl                                                             3






Tcl_CreateChannel(3) Tcl Library Procedures                   8.0



                                                   options   list  |
                                                   (space  |
                                                   separated  |
                                                   words, without  |
                                                   "-") to append  |
                                                   to  the  stan-  |
                                                   dard   generic  |
                                                   options  list.  |
                                                   Can  be   NULL  |
                                                   for    generic  |
                                                   options  error  |
                                                   message only.

_________________________________________________________________


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 device supported on each platform.  This manual
     entry describes the C APIs used to communicate  between  the
     generic  layer  and  the  type-specific channel drivers.  It
     also explains how new types of channels can be added by pro-
     viding 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.





Tcl                                                             4






Tcl_CreateChannel(3) Tcl Library Procedures                   8.0



     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_GetChannelHandle places the  OS-specific  device  handle  |
     associated with channel for the given direction in the loca-  |
     tion specified by handlePtr  and  returns  TCL_OK.   If  the  |
     channel  does  not  have  a  device handle for the specified  |
     direction, then TCL_ERROR is  returned  instead.   Different  |
     channel  drivers  will  return  different  types  of handle.  |
     Refer to the manual entries for  each  driver  to  determine  |
     what type of handle is returned.

     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



Tcl                                                             5






Tcl_CreateChannel(3) Tcl Library Procedures                   8.0



     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_NotifyChannel is called by a channel driver to  indicate  |
     to  the generic layer that the events specified by mask have  |
     occurred on the channel.  Channel  drivers  are  responsible  |
     for  invoking  this  function  whenever the channel handlers  |
     need to be called for the channel.  See WATCHPROC below  for  |
     more details.

     Tcl_BadChannelOption is called from driver specific  set  or  |
     get option procs to generate a complete error message.


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_DriverWatchProc *watchProc;                        |
            Tcl_DriverGetHandleProc *getHandleProc;                |
          } 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.


TYPE

NAME

The typeName field contains a  null-terminated  string  that
     identifies  the  type  of  the  device  implemented  by this



Tcl                                                             6






Tcl_CreateChannel(3) Tcl Library Procedures                   8.0



     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.




Tcl                                                             7






Tcl_CreateChannel(3) Tcl Library Procedures                   8.0



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,



Tcl                                                             8






Tcl_CreateChannel(3) Tcl Library Procedures                   8.0



            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



Tcl                                                             9






Tcl_CreateChannel(3) Tcl Library Procedures                   8.0



     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  setOp-
     tionProc  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  should  call  |
     Tcl_BadChannelOption which itself returns TCL_ERROR  if  the  |
     optionName is unrecognized. If optionValue specifies a value
     for the option that is not supported or  if  a  system  call
     error  occurs, the function should leave an error message in
     the result field of interp if interp is not NULL. The  func-
     tion  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:




Tcl                                                            10






Tcl_CreateChannel(3) Tcl Library Procedures                   8.0



          typedef int Tcl_DriverGetOptionProc(
            ClientData instanceData,
            Tcl_Interp *interp,                                    |
            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. It  |
     should  call  Tcl_BadChannelOption  which   itself   returns  |
     TCL_ERROR  if  the  optionName  is unrecognized. If a system  |
     call error occurs, the function should leave an  error  mes-  |
     sage  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.

     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.


WATCHPROC
     The watchProc field  contains  the  address  of  a  function  |
     called  by the generic layer to initialize the event notifi-  |
     cation mechanism to notice events of interest on this  chan-  |
     nel.  WatchProc should match the following prototype:         |

          typedef void Tcl_DriverWatchProc(                        |
            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.  When one or more of the designated  events  occurs  |
     on  the  channel, the channel driver is responsible for cal-  |
     ling Tcl_NotifyChannel to inform the generic channel module.  |
     The  driver  should  take  care  not to starve other channel  |
     drivers   or    sources    of    callbacks    by    invoking  |
     Tcl_NotifyChannel  too  frequently.  Fairness can be insured  |



Tcl                                                            11






Tcl_CreateChannel(3) Tcl Library Procedures                   8.0



     by using the Tcl event queue to allow the channel  event  to  |
     be  scheduled  in  sequence  with  other  events.   See  the  |
     description of Tcl_QueueEvent for details on how to queue an  |
     event.                                                        |


GETHANDLEPROC                                                      |
     The getHandleProc field contains the address of  a  function  |
     called  by  the  generic layer to retrieve a device-specific  |
     handle from the channel.   GetHandleProc  should  match  the  |
     following prototype:                                          |

          typedef int Tcl_DriverGetHandleProc(                     |
            ClientData instanceData,                               |
            int direction,                                         |
            ClientData *handlePtr);                                |

     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  handle  |
     used  for input, or TCL_WRITABLE to retrieve the handle used  |
     for output.                                                   |

     If the channel implementation has  device-specific  handles,  |
     the  function should retrieve the appropriate handle associ-  |
     ated with the channel,  according  the  direction  argument.  |
     The  handle  should be stored in the location referred to by  |
     handlePtr, and TCL_OK should be returned.  If the channel is  |
     not  open  for  the  specified  direction, or if the channel  |
     implementation does not use  device  handles,  the  function  |
     should return TCL_ERROR.


TCL_BADCHANNELOPTION                                               |
     This procedure generates a "bad option" error message in  an  |
     (optional)  interpreter.  It is used by channel drivers when  |
     a invalid Set/Get option is requested.  Its  purpose  is  to  |
     concatenate  the  generic  options list to the specific ones  |
     and factorize the generic options error message string.       |

     It always return TCL_ERROR                                    |

     An error message is generated in interp's result  object  to  |
     indicate  that  a  command was invoked with the a bad option  |
     The message has the form                                      |
              bad option "blah": should be one of                  |
              <...generic options...>+<...specific options...>     |
          so you get for instance:                                 |
              bad option "-blah": should be one of -blocking,      |
              -buffering, -buffersize, -eofchar, -translation,     |
              -peername, or -sockname                              |
          when called with optionList="peername sockname"          |



Tcl                                                            12






Tcl_CreateChannel(3) Tcl Library Procedures                   8.0



     "blah" is the optionName argument and  "<specific  options>"  |
     is  a  space  separated  list of specific option words.  The  |
     function takes good care of  inserting  minus  signs  before  |
     each  option,  commas  after,  and  an  "or" before the last  |
     option.


SEE ALSO

Tcl_Close(3),    Tcl_OpenFileChannel(3),    Tcl_SetErrno(3),
     Tcl_QueueEvent(3)


KEYWORDS

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








































Tcl                                                            13



Prepared by Ready-to-Run Software, Inc. 

To return to the Ready-to-Run Software Super ReadyPak Table of contents please presshere

 

Email addresses listed on this site may  NOT be used for unsolicited commercial email.

Ready-to-Run Software, Inc Privacy Statement

Portions (c)Copyright, 1996-2005 by Ready-to-Run Software, Inc
(All rights reserved.)
212 Cedar Cove
Lansing, NY 14882
Phone: 607 533 UNIX (8649)
Fax: 607 533 4002