NAME

       Tcl_CreateChannel,             Tcl_GetChannelInstanceData,
       Tcl_GetChannelType, Tcl_GetChannelName, Tcl_GetChannelHan­
       dle,     Tcl_GetChannelMode,     Tcl_GetChannelBufferSize,
       Tcl_SetChannelBufferSize, Tcl_NotifyChannel,  Tcl_BadChan­
       nelOption,  Tcl_ChannelName, Tcl_ChannelVersion, Tcl_Chan­
       nelBlockModeProc,    Tcl_ChannelCloseProc,    Tcl_Channel­
       Close2Proc,  Tcl_ChannelInputProc,  Tcl_ChannelOutputProc,
       Tcl_ChannelSeekProc,  Tcl_ChannelSetOptionProc,  Tcl_Chan­
       nelGetOptionProc,  Tcl_ChannelWatchProc,  Tcl_ChannelGetH­
       andleProc, Tcl_ChannelFlushProc, Tcl_ChannelHandlerProc, -
       procedures 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)

       int
       Tcl_GetChannelHandle(channel, direction, handlePtr)

       int
       Tcl_GetChannelBufferSize(channel)

       Tcl_SetChannelBufferSize(channel, size)

       Tcl_NotifyChannel(channel, mask)

       int
       Tcl_BadChannelOption(interp, optionName, optionList)

       char *                                                     |
       Tcl_ChannelName(typePtr)                                   |

       Tcl_ChannelTypeVersion                                     |
       Tcl_ChannelVersion(typePtr)                                |

       Tcl_DriverBlockModeProc *                                  |
       Tcl_ChannelBlockModeProc(typePtr)                          |

       Tcl_DriverCloseProc *                                      |
       Tcl_ChannelCloseProc(typePtr)                              |

       Tcl_ChannelClose2Proc(typePtr)                             |

       Tcl_DriverInputProc *                                      |
       Tcl_ChannelInputProc(typePtr)                              |

       Tcl_DriverOutputProc *                                     |
       Tcl_ChannelOutputProc(typePtr)                             |

       Tcl_DriverSeekProc *                                       |
       Tcl_ChannelSeekProc(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

       Tcl_ChannelType      *typePtr       (in)      Points  to a
                                                     structure
                                                     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   chan­
                                                     nel, such as
                                                     file3;  must
                                                     not   be  in
                                                     use  by  any
                                                     other  chan­
                                                     nel. Can  be
                                                     NULL,     in

                                                     the  channel
                                                     is   created
                                                     without    a
                                                     name.

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

       int                  mask           (in)      OR-ed combi­
                                                     nation    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
                                                     output  han­
                                                     dle       is
                                                     wanted.

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

       Tcl_EolTranslation   transMode      (in)      The

                                                     mode; one of
                                                     the     con­
                                                     stants
                                                     TCL_TRANS­
                                                     LATE_AUTO,
                                                     TCL_TRANS­
                                                     LATE_CR,
                                                     TCL_TRANS­
                                                     LATE_LF  and
                                                     TCL_TRANS­
                                                     LATE_CRLF.

       int                  size           (in)      The size, in
                                                     bytes,    of
                                                     buffers   to
                                                     allocate  in
                                                     this   chan­
                                                     nel.

       int                  mask           (in)      An     OR-ed
                                                     combination
                                                     of TCL_READ­
                                                     ABLE,
                                                     TCL_WRITABLE
                                                     and
                                                     TCL_EXCEP­
                                                     TION    that
                                                     indicates
                                                     events  that
                                                     have
                                                     occurred  on
                                                     this   chan­
                                                     nel.

       Tcl_Interp           *interp        (in)      Current
                                                     interpreter.
                                                     (can      be
                                                     NULL)

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

       char                 *optionList    (in)      Specific
                                                     options list
                                                     (space sepa­
                                                     rated words,
                                                     without "-")
                                                     to append to
                                                     the standard
                                                     generic
                                                     options
                                                     list.    Can

                                                     generic
                                                     options
                                                     error   mes­
                                                     sage only.

_________________________________________________________________


DESCRIPTION

       Tcl uses a two-layered channel architecture. It provides a
       generic upper layer to enable C and Tcl programs  to  per­
       form 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 man­
       ual 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
       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
       functions  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
       command  channel  drivers, and the Tcl socket command cre­
       ates channels that use TCP sockets for network  communica­
       tion.

       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
       channel driver, and Tcl_OpenTcpClient opens a channel that
       uses  the  TCP network protocol.  These creation functions
       typically 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_Create­
       Channel.   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  per­
       form operations on the channel.

       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 asso­
       ciated 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_Channel­
       Type  structure  used  by the channel in the channel argu­
       ment. 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
       location  specified  by  handlePtr and returns TCL_OK.  If
       the channel does not have a device handle for  the  speci­
       fied  direction, then TCL_ERROR is returned instead.  Dif­
       ferent channel drivers will return different types of han­
       dle.   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
       channel is open for input and output.

        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_SetChannel­
       BufferSize,  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 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  indi­
       cate  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 chan­
       nel handlers need to  be  called  for  the  channel.   See
       WATCHPROC below for more details.

       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 structure was versioned
       starting in  Tcl  8.3.2/8.4  to  correct  a  problem  with
       stacked  channel  drivers.   See  the  OLD_CHANNEL 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_ChannelType;

       The  driver must provide implementations for all functions
       except blockModeProc, seekProc, setOptionProc,  getOption­
       Proc,  and  close2Proc,  which  may  be specified as NULL.
       Other functions that can not be implemented for this  type
       of  device  should  return EINVAL when invoked to indicate
       that they are not  implemented,  except  in  the  case  of
       flushProc  and handlerProc, which should specified as NULL
       if not otherwise defined.

       The user should only use the above structure for Tcl_Chan­ |
       nelType  instantiation.   When  referencing  fields  in  a |
       Tcl_ChannelType structure, the following functions  should |
       be  used  to obtain the values: Tcl_ChannelName, Tcl_Chan­ |
       nelVersion,  Tcl_ChannelBlockModeProc,   Tcl_ChannelClose­ |
       Proc,     Tcl_ChannelClose2Proc,     Tcl_ChannelInputProc, |
       Tcl_ChannelOutputProc, Tcl_ChannelSeekProc, Tcl_ChannelSe­ |
       tOptionProc,  Tcl_ChannelGetOptionProc,  Tcl_ChannelWatch­ |
       Proc, Tcl_ChannelGetHandleProc,  Tcl_ChannelFlushProc,  or |
       Tcl_ChannelHandlerProc.                                    |

       The  change  to the structures was made in such a way that |
       standard channel types are  binary  compatible.   However, |

       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  TCL_CHANNEL_VERSION_2. |
       If it is not set to this value TCL_CHANNEL_VERSION_2, then |
       this Tcl_ChannelType is assumed to have the  older  struc­ |
       ture.   See  OLD_CHANNEL for more details.  While Tcl will |
       recognize and  function  with  either  structure,  stacked |
       channels must be of the newer style to function correctly. |

       This value can be retrieved with Tcl_ChannelVersion, which |
       returns  either  TCL_CHANNEL_VERSION_2 or TCL_CHANNEL_VER­ |
       SION_1.


BLOCKMODEPROC

       The blockModeProc field contains the address of a function
       called  by the generic layer to set blocking and nonblock­
       ing mode on the device.  BlockModeProc  should  match  the
       following 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_NONBLOCK­
       ING to set the device into blocking or  nonblocking  mode.
       The  function should return zero if the operation was suc­
       cessful, 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  blocking  and nonblocking behavior can be implemented
       by the  underlying  operating  system;  for  other  device
       types,  the  behavior  must  be  emulated  in  the channel
       driver.

       which returns a pointer to the function.


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  pro­
       vided  to  Tcl_CreateChannel when the channel was created.
       The function should release any storage maintained by  the
       channel  driver  for this channel, and close the input and
       output devices 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
       function that matches the following prototype:

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

       The  close2Proc  will be called with flags set to an OR'ed
       combination of TCL_CLOSE_READ or TCL_CLOSE_WRITE to  indi­
       cate  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 function should return zero if the
       close operation was successful; 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.

       Tcl_ChannelClose2Proc, which  returns  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_Creat­
       eChannel  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
       provided  by  the  generic  layer. If an error occurs, the
       function should set the variable to  a  POSIX  error  code
       that identifies the error that occurred.

       The function should read data from the input device encap­
       sulated by the channel and store it at buf.   On  success,
       the  function should return a nonnegative integer indicat­
       ing 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
       argument, 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  func­
       tion  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.

       The  outputProc  field  contains the address of a function
       called by the generic  layer  to  transfer  data  from  an
       internal  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_Creat­
       eChannel  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
       provided  by  the  generic  layer. If an error occurs, the
       function should set this variable to a  POSIX  error  code
       that identifies the error.

       The  function  should  write the data at buf to the output
       device encapsulated by the channel. On success, the  func­
       tion  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.

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


SEEKPROC

       The seekProc field contains  the  address  of  a  function
       called  by  the  generic layer to move the access point at
       which  subsequent  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

       set and seekMode have the same meaning as for the Tcl_Seek
       procedure (described in the  manual  entry  for  Tcl_Open­
       FileChannel).

       The  errorCodePtr  argument  points to an integer variable
       provided 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.

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


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 follow­
       ing prototype:

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

       optionName is the name of an option to set, and  optionVa­
       lue  is  the  new  value for that option, as a string. The
       instanceData is the same as the value given to Tcl_Create­
       Channel 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
       function 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  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 mes­
       sage  in the result field of interp if interp is not NULL.

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

       Some options are handled by  the  generic  code  and  this
       function  is  never  called  to retrieve their value, e.g.
       -blockmode. 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 sup­
       ports 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  noti­
       fication  mechanism  to  notice events of interest on this
       channel.  WatchProc should match the following prototype:

              typedef void Tcl_DriverWatchProc(
                ClientData instanceData,
                int mask);

       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 mecha­
       nisms  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 calling Tcl_NotifyChannel to inform the generic  chan­
       nel  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
       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_Creat­
       eChannel when this  channel  was  created.  The  direction
       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  asso­
       ciated 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.

       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 occured.  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 following prototype:                             |

              typedef int Tcl_DriverHandlerProc(                  |
                ClientData instanceData,                          |
                int interestMask);                                |

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

       This value can be retrieved  with  Tcl_ChannelHandlerProc, |
       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 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"
       ``blah''  is  the  optionName  argument  and   ``<specific

       words.  The function takes good care  of  inserting  minus
       signs  before  each  option,  commas  after, and an ``or''
       before the last option.


OLD_CHANNEL

       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;

       It  is  still  possible  to  create channel with the above
       structure.  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 implemen­
       tation (in 8.2.0 to 8.3.1).


SEE ALSO

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


KEYWORDS

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


Man(1) output converted with man2html