Unix/Linux Go Back    


OpenDarwin 7.2.1 - man page for tcl_channelbuffered (opendarwin section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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_SetChannelBuffer-
       Size,   Tcl_NotifyChannel,   Tcl_BadChannelOption,   Tcl_ChannelName,  Tcl_ChannelVersion,
       Tcl_ChannelBlockModeProc, Tcl_ChannelCloseProc,	Tcl_ChannelClose2Proc,	Tcl_ChannelInput-
       Proc,  Tcl_ChannelOutputProc, Tcl_ChannelSeekProc, Tcl_ChannelWideSeekProc, Tcl_ChannelSe-
       tOptionProc,  Tcl_ChannelGetOptionProc,	Tcl_ChannelWatchProc,	Tcl_ChannelGetHandleProc,
       Tcl_ChannelFlushProc,   Tcl_ChannelHandlerProc,	Tcl_IsChannelShared,  Tcl_IsChannelRegis-
       tered, Tcl_CutChannel, Tcl_SpliceChannel, Tcl_IsChannelExisting, Tcl_ClearChannelHandlers,
       Tcl_GetChannelThread, Tcl_ChannelBuffered - procedures for creating and manipulating chan-
       nels

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_GetChannelBufferSize(channel)

       Tcl_SetChannelBufferSize(channel, size)

       Tcl_NotifyChannel(channel, mask)

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

       CONST 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 associated with
						  this channel.  This value is passed  to  proce-
						  dures in typePtr when they are invoked.

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

       Tcl_Channel	 channel	(in)	  The channel to operate on.

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

       ClientData	 *handlePtr	(out)	  Points to the location where	the  desired  OS-
						  specific handle 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 indicates
						  events that have occurred on this channel.

       Tcl_Interp	 *interp	(in)	  Current interpreter. (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 standard 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_Open-
       FileChannel.

       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 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 opera-
       tions  used  by the generic layer to communicate with the channel driver. The Tcl_Channel-
       Type structure and the functions referenced by it are described in the  section	TCL_CHAN-
       NELTYPE, 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 creates channels that use TCP sockets for net-
       work 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 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_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 operations  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_CHANNEL-
       TYPE, below.

       Tcl_CreateChannel interacts with the code managing the standard channels. Once a  standard
       channel was initialized either through a call to Tcl_GetStdChannel or a call to Tcl_SetSt-
       dChannel 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 associated with the channel in  chan-
       nel.  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_Cre-
       ateChannel 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 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 chan- |
       nel. 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, indicat-
       ing 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 channel. If the value was not set by a previous call to Tcl_SetChannelBuffer-
       Size, 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 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 chan-
       nel.  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_ChannelBuffered  returns the number of bytes of input currently buffered in the inter-
       nal 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 interpreter is |
       not allowed.										  |

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

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

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_ChannelType;

       The  driver must provide implementations for all functions except blockModeProc, seekProc,
       setOptionProc, getOptionProc, and close2Proc, which may be specified as NULL.  Other func-
       tions  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_ChannelType instantiation.	When ref-
       erencing 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_ChannelSetOptionProc, Tcl_ChannelGetOp- |
       tionProc,   Tcl_ChannelWatchProc,   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, channel types that use stacked channels (ie: TLS, Trf) have new ver-
       sions  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_3, then this Tcl_ChannelType is assumed to have the	older  structure.
       See OLD CHANNEL TYPES for more details.	While Tcl will recognize and function with either
       structure, stacked channels must be of at least	TCL_CHANNEL_VERSION_2  to  function  cor-
       rectly.

       This value can be retrieved with Tcl_ChannelVersion, which returns one of TCL_CHANNEL_VER- |
       SION_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 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_NONBLOCKING to set
       the device into blocking or nonblocking mode. The function should return zero if the oper-
       ation 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 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.

       This  value can be retrieved with Tcl_ChannelBlockModeProc, 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 provided 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 chan-
       nel.  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 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  chan-
       nel  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 addi-
       tion, if an error occurs and interp is not NULL, the procedure should store an error  mes-
       sage in the interpreter's result.

       These  value  can  be  retrieved with Tcl_ChannelCloseProc or 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_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 provided 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 encapsulated 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 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 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 with-
       out 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  internal 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 provided 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 device encapsulated by  the  chan-
       nel.  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 whatso-
       ever, 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 AND WIDESEEKPROC
       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 to Tcl_CreateChannel when this
       channel was created.  Offset and seekMode have the same meaning as for the Tcl_Seek proce-
       dure (described in the manual entry for Tcl_OpenFileChannel).

       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.

       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 prefer- |
       ence 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   function,	and  similarly	the  wideSeekProc  can	be  retrieved  with  Tcl_Channel- |
       WideSeekProc.

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 function is never called to set
       them, e.g. -blockmode. Other options are specific to each channel type and the  setOption-
       Proc  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 option-
       Name  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 function 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_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 option-
       Name 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 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 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 ini-
       tialize the event notification mechanism to notice events of  interest  on  this  channel.
       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 mechanisms 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 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 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  fol-
       lowing 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 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 associated 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 following 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 driv-
       ers 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_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.

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 con-
       catenate 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 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;

       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 struc-
       ture 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 develop- |
       ment 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_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_StackChan-
       nel(3), Tcl_GetStdChannel(3)

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

Tcl					       8.3			     Tcl_CreateChannel(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 11:32 PM.