DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

Tcl_ChannelHandlerProc(3tcl)




Tcl_CreateChannel(3) Tcl Library Procedures  Tcl_CreateChannel(3)

_________________________________________________________________


NAME

     Tcl_CreateChannel,               Tcl_GetChannelInstanceData,
     Tcl_GetChannelType,                      Tcl_GetChannelName,
     Tcl_GetChannelHandle,                    Tcl_GetChannelMode,
     Tcl_GetChannelBufferSize,          Tcl_SetChannelBufferSize,
     Tcl_NotifyChannel,  Tcl_BadChannelOption,   Tcl_ChannelName,
     Tcl_ChannelVersion,                Tcl_ChannelBlockModeProc,
     Tcl_ChannelCloseProc,                 Tcl_ChannelClose2Proc,
     Tcl_ChannelInputProc,                 Tcl_ChannelOutputProc,
     Tcl_ChannelSeekProc,                Tcl_ChannelWideSeekProc,
     Tcl_ChannelTruncateProc,           Tcl_ChannelSetOptionProc,
     Tcl_ChannelGetOptionProc,              Tcl_ChannelWatchProc,
     Tcl_ChannelGetHandleProc,              Tcl_ChannelFlushProc,
     Tcl_ChannelHandlerProc,         Tcl_ChannelThreadActionProc,
     Tcl_IsChannelShared,                Tcl_IsChannelRegistered,
     Tcl_CutChannel,  Tcl_SpliceChannel,   Tcl_IsChannelExisting,
     Tcl_ClearChannelHandlers,              Tcl_GetChannelThread,
     Tcl_ChannelBuffered - procedures for creating and manipulat-
     ing channels


SYNOPSIS

     #include <tcl.h>

     Tcl_Channel
     Tcl_CreateChannel(typePtr, channelName, instanceData, mask)

     ClientData
     Tcl_GetChannelInstanceData(channel)

     Tcl_ChannelType *
     Tcl_GetChannelType(channel)

     const char *
     Tcl_GetChannelName(channel)

     int
     Tcl_GetChannelHandle(channel, direction, handlePtr)

     Tcl_ThreadId
     Tcl_GetChannelThread(channel)

     int
     Tcl_GetChannelMode(channel)

     int
     Tcl_GetChannelBufferSize(channel)

     Tcl_SetChannelBufferSize(channel, size)

     Tcl_NotifyChannel(channel, mask)

Tcl                     Last change: 8.4                        1

Tcl_CreateChannel(3) Tcl Library Procedures  Tcl_CreateChannel(3)

     int
     Tcl_BadChannelOption(interp, optionName, optionList)

     int
     Tcl_IsChannelShared(channel)

     int
     Tcl_IsChannelRegistered(interp, channel)

     int
     Tcl_IsChannelExisting(channelName)

     void
     Tcl_CutChannel(channel)

     void
     Tcl_SpliceChannel(channel)

     void
     Tcl_ClearChannelHandlers(channel)

     int
     Tcl_ChannelBuffered(channel)

     const char *
     Tcl_ChannelName(typePtr)

     Tcl_ChannelTypeVersion
     Tcl_ChannelVersion(typePtr)

     Tcl_DriverBlockModeProc *
     Tcl_ChannelBlockModeProc(typePtr)

     Tcl_DriverCloseProc *
     Tcl_ChannelCloseProc(typePtr)

     Tcl_DriverClose2Proc *
     Tcl_ChannelClose2Proc(typePtr)

     Tcl_DriverInputProc *
     Tcl_ChannelInputProc(typePtr)

     Tcl_DriverOutputProc *
     Tcl_ChannelOutputProc(typePtr)

     Tcl_DriverSeekProc *
     Tcl_ChannelSeekProc(typePtr)

     Tcl_DriverWideSeekProc *
     Tcl_ChannelWideSeekProc(typePtr)

     Tcl_DriverThreadActionProc *

Tcl                     Last change: 8.4                        2

Tcl_CreateChannel(3) Tcl Library Procedures  Tcl_CreateChannel(3)

     Tcl_ChannelThreadActionProc(typePtr)

     Tcl_DriverTruncateProc *                                      |
     Tcl_ChannelTruncateProc(typePtr)                              |

     Tcl_DriverSetOptionProc *
     Tcl_ChannelSetOptionProc(typePtr)

     Tcl_DriverGetOptionProc *
     Tcl_ChannelGetOptionProc(typePtr)

     Tcl_DriverWatchProc *
     Tcl_ChannelWatchProc(typePtr)

     Tcl_DriverGetHandleProc *
     Tcl_ChannelGetHandleProc(typePtr)

     Tcl_DriverFlushProc *
     Tcl_ChannelFlushProc(typePtr)

     Tcl_DriverHandlerProc *
     Tcl_ChannelHandlerProc(typePtr)


ARGUMENTS

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

     const char *channelName (in)                     The name of
                                                      this  chan-
                                                      nel,   such
                                                      as   file3;
                                                      must not be
                                                      in  use  by
                                                      any   other
                                                      channel.
                                                      Can      be
                                                      NULL,    in
                                                      which  case
                                                      the channel

Tcl                     Last change: 8.4                        3

Tcl_CreateChannel(3) Tcl Library Procedures  Tcl_CreateChannel(3)

                                                      is  created
                                                      without   a
                                                      name.

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

     int mask (in)                                    OR-ed  com-
                                                      bination of
                                                      TCL_READABLE
                                                      and
                                                      TCL_WRITABLE
                                                      to indicate
                                                      whether   a
                                                      channel  is
                                                      readable
                                                      and   writ-
                                                      able.

     Tcl_Channel channel (in)                         The channel
                                                      to  operate
                                                      on.

     int direction (in)                               TCL_READABLE
                                                      means   the
                                                      input  han-
                                                      dle      is
                                                      wanted;
                                                      TCL_WRITABLE
                                                      means   the
                                                      output han-
                                                      dle      is
                                                      wanted.

     ClientData *handlePtr (out)                      Points   to
                                                      the   loca-
                                                      tion  where
                                                      the desired
                                                      OS-specific
                                                      handle

Tcl                     Last change: 8.4                        4

Tcl_CreateChannel(3) Tcl Library Procedures  Tcl_CreateChannel(3)

                                                      should   be
                                                      stored.

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

     int mask (in)                                    An    OR-ed
                                                      combination
                                                      of
                                                      TCL_READABLE,
                                                      TCL_WRITABLE
                                                      and
                                                      TCL_EXCEPTION
                                                      that  indi-
                                                      cates
                                                      events that
                                                      have
                                                      occurred on
                                                      this  chan-
                                                      nel.

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

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

     const char *optionList (in)                      Specific
                                                      options
                                                      list (space
                                                      separated
                                                      words,
                                                      without
                                                      "-")     to
                                                      append   to
                                                      the   stan-
                                                      dard   gen-
                                                      eric
                                                      options
                                                      list.   Can
                                                      be NULL for
                                                      generic
                                                      options
                                                      error

Tcl                     Last change: 8.4                        5

Tcl_CreateChannel(3) Tcl Library Procedures  Tcl_CreateChannel(3)

                                                      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.

     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

Tcl                     Last change: 8.4                        6

Tcl_CreateChannel(3) Tcl Library Procedures  Tcl_CreateChannel(3)

     channel  drivers,  their  operations and the Tcl_ChannelType
     structure, see the section TCL_CHANNELTYPE, below.

     Tcl_CreateChannel interacts with the code managing the stan-
     dard  channels.  Once  a  standard  channel  was initialized
     either through a call to  Tcl_GetStdChannel  or  a  call  to
     Tcl_SetStdChannel  closing  this standard channel will cause
     the next call to Tcl_CreateChannel to make the  new  channel
     the new standard channel too. See Tcl_StandardChannels for a
     general treatise about standard channels and  the  behaviour
     of the Tcl library with regard to them.

     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_GetChannelThread returns the id of the thread  currently
     managing  the specified channel. This allows channel drivers
     to send their file events to the correct  event  queue  even
     for a multi-threaded core.

     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_GetChannelBufferSize returns  the  size,  in  bytes,  of
     buffers  allocated  to  store input or output in channel. 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

Tcl                     Last change: 8.4                        7

Tcl_CreateChannel(3) Tcl Library Procedures  Tcl_CreateChannel(3)

     channel 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  setOp-
     tionProc  or getOptionProc to generate a complete error mes-
     sage.

     Tcl_ChannelBuffered returns the number  of  bytes  of  input
     currently  buffered  in the internal buffer (push back area)
     of the channel itself. It does not report about the data  in
     the  overall  buffers for the stack of channels the supplied
     channel is part of.

     Tcl_IsChannelShared checks the  refcount  of  the  specified
     channel  and  returns  whether  the channel was shared among
     multiple interpreters (result == 1) or not (result == 0).

     Tcl_IsChannelRegistered checks whether the specified channel
     is  registered in the given interpreter (result == 1) or not
     (result == 0).

     Tcl_IsChannelExisting checks  whether  a  channel  with  the
     specified  name is registered in the (thread)-global list of
     all channels (result == 1) or not (result == 0).

     Tcl_CutChannel  removes  the  specified  channel  from   the
     (thread)global list of all channels (of the current thread).
     Application to a channel still  registered  in  some  inter-
     preter  is  not  allowed.   Also  notifies the driver if the  |
     Tcl_ChannelType   version   is   TCL_CHANNEL_VERSION_4   (or  |
     higher), and Tcl_DriverThreadActionProc is defined for it.

     Tcl_SpliceChannel  adds  the  specified   channel   to   the
     (thread)global list of all channels (of the current thread).
     Application to a channel registered in some  interpreter  is
     not    allowed.    Also   notifies   the   driver   if   the  |
     Tcl_ChannelType   version   is   TCL_CHANNEL_VERSION_4   (or  |
     higher), and Tcl_DriverThreadActionProc is defined for it.

     Tcl_ClearChannelHandlers removes all  channel  handlers  and
     event  scripts  associated  with the specified channel, thus
     shutting down all event processing for this channel.

Tcl                     Last change: 8.4                        8

Tcl_CreateChannel(3) Tcl Library Procedures  Tcl_CreateChannel(3)


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 structure was versioned
     starting in Tcl 8.3.2/8.4 to correct a problem with  stacked
     channel  drivers.   See  the OLD CHANNEL TYPES section below
     for details about the old structure.

     The Tcl_ChannelType structure contains the following fields:
          typedef struct Tcl_ChannelType {
                  char *typeName;
                  Tcl_ChannelTypeVersion version;
                  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_DriverClose2Proc *close2Proc;
                  Tcl_DriverBlockModeProc *blockModeProc;
                  Tcl_DriverFlushProc *flushProc;
                  Tcl_DriverHandlerProc *handlerProc;
                  Tcl_DriverWideSeekProc *wideSeekProc;
                  Tcl_DriverThreadActionProc *threadActionProc;
                  Tcl_DriverTruncateProc *truncateProc;            |
          } Tcl_ChannelType;

     It is not necessary to provide implementations for all chan-
     nel operations.  Those which are not necessary may be set to
     NULL in the struct: blockModeProc, seekProc,  setOptionProc,
     getOptionProc,  and  close2Proc,  in  addition to flushProc,
     handlerProc,  threadActionProc,  and  truncateProc.    Other
     functions  that  cannot  be  implemented in a meaningful way
     should return EINVAL  when  called,  to  indicate  that  the
     operations  they represent are not available. Also note that
     wideSeekProc can be NULL if seekProc is.

     The  user  should  only  use   the   above   structure   for
     Tcl_ChannelType instantiation.  When referencing fields in a
     Tcl_ChannelType structure, the following functions should be
     used     to    obtain    the    values:     Tcl_ChannelName,
     Tcl_ChannelVersion,                Tcl_ChannelBlockModeProc,
     Tcl_ChannelCloseProc,                 Tcl_ChannelClose2Proc,
     Tcl_ChannelInputProc,                 Tcl_ChannelOutputProc,
     Tcl_ChannelSeekProc,                Tcl_ChannelWideSeekProc,
     Tcl_ChannelThreadActionProc,        Tcl_ChannelTruncateProc,  |
     Tcl_ChannelSetOptionProc,          Tcl_ChannelGetOptionProc,
     Tcl_ChannelWatchProc,              Tcl_ChannelGetHandleProc,
     Tcl_ChannelFlushProc, or Tcl_ChannelHandlerProc.

Tcl                     Last change: 8.4                        9

Tcl_CreateChannel(3) Tcl Library Procedures  Tcl_CreateChannel(3)

     The change to the structures was made in  such  a  way  that
     standard  channel  types  are  binary  compatible.  However,
     channel types that use stacked channels (i.e. TLS, Trf) have
     new  versions  to  correspond  to the above change since the
     previous code for stacked channels had problems.

  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.

     This value can  be  retrieved  with  Tcl_ChannelName,  which
     returns a pointer to the string.

  VERSION
     The version field should be set to the version of the struc-
     ture  that you require. TCL_CHANNEL_VERSION_2 is the minimum
     recommended.  TCL_CHANNEL_VERSION_3 must be set  to  specify
     the  wideSeekProc member.  TCL_CHANNEL_VERSION_4 must be set
     to   specify   the   threadActionProc    member    (includes
     wideSeekProc).  TCL_CHANNEL_VERSION_5 must be set to specify  |
     the  truncateProc   members   (includes   wideSeekProc   and  |
     threadActionProc).   If  it is not set to any of these, then
     this Tcl_ChannelType is assumed to have the original  struc-
     ture.   See  OLD  CHANNEL TYPES for more details.  While Tcl
     will recognize and function with either structures,  stacked
     channels  must be of at least TCL_CHANNEL_VERSION_2 to func-
     tion correctly.

     This value can be retrieved with  Tcl_ChannelVersion,  which
     returns one of TCL_CHANNEL_VERSION_5, TCL_CHANNEL_VERSION_4,  |
     TCL_CHANNEL_VERSION_3,       TCL_CHANNEL_VERSION_2        or
     TCL_CHANNEL_VERSION_1.

  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.

Tcl                     Last change: 8.4                       10

Tcl_CreateChannel(3) Tcl Library Procedures  Tcl_CreateChannel(3)

     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.

     This value can be retrieved  with  Tcl_ChannelBlockModeProc,
     which returns a pointer to the function.

     A channel driver not supplying a  blockModeProc  has  to  be
     very, very careful. It has to tell the generic layer exactly
     which blocking mode is acceptable to  it,  and  should  this
     also  document for the user so that the blocking mode of the
     channel is not changed to an unacceptable value. Any  confu-
     sion here may lead the interpreter into a (spurious and dif-
     ficult to find) deadlock.

  CLOSEPROC AND CLOSE2PROC
     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 the interpreter's
     result.

     Alternatively, channels that support closing  the  read  and
     write    sides    independently   may   set   closeProc   to
     TCL_CLOSE2PROC and set close2Proc to the address of a  func-
     tion that matches the following prototype:

          typedef int Tcl_DriverClose2Proc(
                  ClientData instanceData,
                  Tcl_Interp *interp,
                  int flags);

Tcl                     Last change: 8.4                       11

Tcl_CreateChannel(3) Tcl Library Procedures  Tcl_CreateChannel(3)

     The close2Proc will be called with flags  set  to  an  OR'ed
     combination of TCL_CLOSE_READ or TCL_CLOSE_WRITE to indicate
     that the driver should close the read and/or write  side  of
     the  channel.   The channel driver may be invoked to perform
     additional operations on the  channel  after  close2Proc  is
     called  to close one or both sides of the channel.  If flags
     is 0 (zero), the driver should  close  the  channel  in  the
     manner described above for closeProc.  No further operations
     will be invoked on this instance after close2Proc is  called
     with  all flags cleared.  In all cases, the close2Proc func-
     tion should return zero if the close operation was  success-
     ful;  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 the interpreter's
     result.

     The closeProc and close2Proc values can  be  retrieved  with
     Tcl_ChannelCloseProc  or Tcl_ChannelClose2Proc, which return
     a pointer to the respective function.

  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.

Tcl                     Last change: 8.4                       12

Tcl_CreateChannel(3) Tcl Library Procedures  Tcl_CreateChannel(3)

     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.

     This value can be retrieved with Tcl_ChannelInputProc, which
     returns a pointer to the function.

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

Tcl                     Last change: 8.4                       13

Tcl_CreateChannel(3) Tcl Library Procedures  Tcl_CreateChannel(3)

     This value  can  be  retrieved  with  Tcl_ChannelOutputProc,
     which returns a pointer to the function.

  SEEKPROC AND WIDESEEKPROC
     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_Seek 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.

     If there is a  non-NULL  seekProc  field,  the  wideSeekProc
     field  may contain the address of an alternative function to
     use which handles wide (i.e. larger than 32-bit) offsets, so
     allowing   seeks   within   files   larger  than  2GB.   The
     wideSeekProc will be called in preference to  the  seekProc,
     but  both  must  be  defined if the wideSeekProc is defined.
     WideSeekProc must match the following prototype:

          typedef Tcl_WideInt Tcl_DriverWideSeekProc(
                  ClientData instanceData,
                  Tcl_WideInt offset,
                  int seekMode,
                  int *errorCodePtr);

     The arguments and return values mean the same thing as  with
     seekProc  above,  except  that  the  type of offsets and the
     return type are different.

     The    seekProc    value    can    be     retrieved     with
     Tcl_ChannelSeekProc,  which  returns  a pointer to the func-
     tion, and similarly the wideSeekProc can be  retrieved  with

Tcl                     Last change: 8.4                       14

Tcl_CreateChannel(3) Tcl Library Procedures  Tcl_CreateChannel(3)

     Tcl_ChannelWideSeekProc.

  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,
                  const char *optionName,
                  const char *newValue);

     optionName is the name of an option to set, and newValue  is
     the new value for that option, as a string. The instanceData
     is the same as the value  given  to  Tcl_CreateChannel  when
     this  channel  was  created. The function should do whatever
     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 newValue 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.

     This value can be retrieved  with  Tcl_ChannelSetOptionProc,
     which returns a pointer to the function.

  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,
                  Tcl_Interp *interp,
                  const char *optionName,

Tcl                     Last change: 8.4                       15

Tcl_CreateChannel(3) Tcl Library Procedures  Tcl_CreateChannel(3)

                  Tcl_DString *optionValue);

     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  optionValue.   If  optionName  is NULL, the function
     stores in optionValue 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 message in the result 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.

     This value can be retrieved  with  Tcl_ChannelGetOptionProc,
     which returns a pointer to the function.

  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
     by using the Tcl event queue to allow the channel  event  to
     be  scheduled  in  sequence  with  other  events.   See  the

Tcl                     Last change: 8.4                       16

Tcl_CreateChannel(3) Tcl Library Procedures  Tcl_CreateChannel(3)

     description of Tcl_QueueEvent for details on how to queue an
     event.

     This value can be retrieved with Tcl_ChannelWatchProc, which
     returns a pointer to the function.

  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.

     This value can be retrieved  with  Tcl_ChannelGetHandleProc,
     which returns a pointer to the function.

  FLUSHPROC
     The flushProc field is currently reserved  for  future  use.
     It  should  be set to NULL.  FlushProc should match the fol-
     lowing prototype:

          typedef int Tcl_DriverFlushProc(
                  ClientData instanceData);

     This value can be retrieved with Tcl_ChannelFlushProc, which
     returns a pointer to the function.

  HANDLERPROC
     The handlerProc field contains the  address  of  a  function
     called  by  the  generic layer to notify the channel that an
     event occurred.  It should be defined  for  stacked  channel
     drivers that wish to be notified of events that occur on the
     underlying (stacked) channel.  HandlerProc should match  the

Tcl                     Last change: 8.4                       17

Tcl_CreateChannel(3) Tcl Library Procedures  Tcl_CreateChannel(3)

     following prototype:

          typedef int Tcl_DriverHandlerProc(
                  ClientData instanceData,
                  int interestMask);

     InstanceData  is  the  same   as   the   value   passed   to
     Tcl_CreateChannel   when  this  channel  was  created.   The
     interestMask is an  OR-ed  combination  of  TCL_READABLE  or
     TCL_WRITABLE;  it  indicates  what type of event occurred on
     this channel.

     This value can  be  retrieved  with  Tcl_ChannelHandlerProc,
     which returns a pointer to the function.

  THREADACTIONPROC
     The threadActionProc field contains the address of the func-
     tion  called by the generic layer when a channel is created,
     closed, or going to move to a different thread,  i.e.  when-
     ever  thread-specific driver state might have to initialized
     or    updated.    It    can    be    NULL.     The    action
     TCL_CHANNEL_THREAD_REMOVE  is used to notify the driver that
     it should update or remove any thread-specific data it might
     be maintaining for the channel.

     The action TCL_CHANNEL_THREAD_INSERT is used to  notify  the
     driver  that  it  should  update  or  initialize any thread-
     specific data it might  be  maintaining  using  the  calling
     thread    as   the   associate.   See   Tcl_CutChannel   and
     Tcl_SpliceChannel for more detail.

          typedef void Tcl_DriverThreadActionProc(
                  ClientData instanceData,
                  int        action);

     InstanceData  is  the  same   as   the   value   passed   to
     Tcl_CreateChannel when this channel was created.

     These      values      can      be      retrieved       with
     Tcl_ChannelThreadActionProc,  which returns a pointer to the
     function.

  TRUNCATEPROC
     The truncateProc field contains the address of the  function
     called  by  the generic layer when a channel is truncated to
     some length. It can be NULL.

          typedef int Tcl_DriverTruncateProc(
                  ClientData instanceData,
                  Tcl_WideInt length);

Tcl                     Last change: 8.4                       18

Tcl_CreateChannel(3) Tcl Library Procedures  Tcl_CreateChannel(3)

     InstanceData  is  the  same   as   the   value   passed   to
     Tcl_CreateChannel  when this channel was created, and length
     is the new length of the underlying file, which  should  not
     be  negative.  The result should be 0 on success or an errno
     code (suitable for use with Tcl_SetErrno) on failure.

     These values can be retrieved with  Tcl_ChannelTruncateProc,
     which returns a pointer to the function.


TCL_BADCHANNELOPTION

     This procedure generates a "bad option" error message in  an
     (optional)  interpreter.  It is used by channel drivers when
     an 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 returns TCL_ERROR

     An error message is generated in interp's result  object  to
     indicate  that a command was invoked with 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 equal to "peername sockname"

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


OLD CHANNEL TYPES

     The original (8.3.1  and  below)  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_DriverClose2Proc *close2Proc;
          } Tcl_ChannelType;

Tcl                     Last change: 8.4                       19

Tcl_CreateChannel(3) Tcl Library Procedures  Tcl_CreateChannel(3)

     It is still possible to create channel with the above struc-
     ture.  The internal channel code will determine the version.
     It is imperative to use the new Tcl_ChannelType structure if
     you  are  creating a stacked channel driver, due to problems
     with the earlier stacked channel implementation (in 8.2.0 to
     8.3.1).

     Prior to 8.4.0 (i.e. during the later releases  of  8.3  and
     early part of the 8.4 development cycle) the Tcl_ChannelType
     structure contained the following fields:

          typedef struct Tcl_ChannelType {
                  char *typeName;
                  Tcl_ChannelTypeVersion version;
                  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_DriverClose2Proc *close2Proc;
                  Tcl_DriverBlockModeProc *blockModeProc;
                  Tcl_DriverFlushProc *flushProc;
                  Tcl_DriverHandlerProc *handlerProc;
                  Tcl_DriverTruncateProc *truncateProc;
          } Tcl_ChannelType;

     When the above structure is registered as  a  channel  type,
     the version field should always be TCL_CHANNEL_VERSION_2.


SEE ALSO

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


KEYWORDS

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

Tcl                     Last change: 8.4                       20


Man(1) output converted with man2html