Tcl_CreateChannel man page on BSDi

Man page or keyword search:  
man Server   6284 pages
apropos Keyword Search (all sections)
Output format
BSDi logo
[printable version]



Tcl_CreateChannel(3)  Tcl Library Procedures Tcl_CreateChannel(3)

_________________________________________________________________

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

SYNOPSIS
       #include <tcl.h>

       Tcl_Channel
       Tcl_CreateChannel(typePtr, channelName, instanceData, mask)

       ClientData
       Tcl_GetChannelInstanceData(channel)

       Tcl_ChannelType *
       Tcl_GetChannelType(channel)

       char *
       Tcl_GetChannelName(channel)

       Tcl_File
       Tcl_GetChannelFile(channel, direction)

       int
       Tcl_GetChannelFlags(channel)

       void
       Tcl_SetDefaultTranslation(channel, transMode)

       int
       Tcl_GetChannelBufferSize(channel)

       void
       Tcl_SetChannelBufferSize(channel, size)

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

       char		*channelName   (in)	 The name of this
						 channel, such as
						 file3; must  not

Tcl			       7.5				1

Tcl_CreateChannel(3)  Tcl Library Procedures Tcl_CreateChannel(3)

						 be in use by any
						 other	 channel.
						 Can  be NULL, in
						 which	case  the
						 channel  is cre-
						 ated  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	 combina-
						 tion	       of
						 TCL_READABLE and
						 TCL_WRITABLE  to
						 indicate whether
						 a   channel   is
						 readable     and
						 writable.

       Tcl_Channel	channel	       (in)	 The  channel  to
						 operate on.

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

       Tcl_EolTranslation	       transMode(in)
						 The  translation
						 mode; one of the
						 constants
						 TCL_TRANS-
						 LATE_AUTO,
						 TCL_TRANS-
						 LATE_CR,
						 TCL_TRANSLATE_LF
						 and   TCL_TRANS-
						 LATE_CRLF.

       int		size	       (in)	 The   size,   in
						 bytes,	       of
						 buffers to allo-
						 cate	in   this
						 channel.

Tcl			       7.5				2

Tcl_CreateChannel(3)  Tcl Library Procedures Tcl_CreateChannel(3)

_________________________________________________________________

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  file,  socket and device supported on each
       platform.  This manual entry describes the C APIs used  by
       the  generic layer to communicate with type-specific chan-
       nel drivers to perform the input and output operations. It
       also  explains  how  new types of channels can be added by
       providing new channel drivers.

       Channel drivers consist of a number of components:  First,
       each  channel  driver provides a Tcl_ChannelType structure
       containing pointers to functions implementing the  various
       operations  used	 by the generic layer to communicate with
       the channel driver. The Tcl_ChannelType structure and  the
       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.

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

Tcl			       7.5				3

Tcl_CreateChannel(3)  Tcl Library Procedures Tcl_CreateChannel(3)

       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_GetChannelFile  returns  the	 inFile	 associated  with
       channel if direction is TCL_READABLE, or	 the  outFile  if
       direction  is  TCL_WRITABLE. The operation returns NULL if
       the channel is not based on Tcl_Files or if the channel is
       not open for the specified direction.

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

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

       Tcl_GetChannelBufferSize returns the size,  in  bytes,  of
       buffers allocated to store input or output in chan. If the
       value was not set by a previous	call  to  Tcl_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_CHANNELTYPE
       A channel driver provides a Tcl_ChannelType structure that
       contains	 pointers to functions that implement the various
       operations on a channel; these operations are  invoked  as
       needed by the generic layer. The Tcl_ChannelType structure
       contains the following fields:

	      typedef struct Tcl_ChannelType {

Tcl			       7.5				4

Tcl_CreateChannel(3)  Tcl Library Procedures Tcl_CreateChannel(3)

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

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

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

BLOCKMODEPROC
       The blockModeProc field contains the address of a function
       called  by the generic layer to set blocking and 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.

Tcl			       7.5				5

Tcl_CreateChannel(3)  Tcl Library Procedures Tcl_CreateChannel(3)

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

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

       The  instanceData  argument  is the same as the value 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
       interp->result.

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

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

       InstanceData is the same as the value passed to Tcl_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

Tcl			       7.5				6

Tcl_CreateChannel(3)  Tcl Library Procedures Tcl_CreateChannel(3)

       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.

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

Tcl			       7.5				7

Tcl_CreateChannel(3)  Tcl Library Procedures Tcl_CreateChannel(3)

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
       to Tcl_CreateChannel when this channel was created.   Off-
       set  and	 seekMode  have	 the  same  meaning  as	 for  the
       Tcl_SeekChannel procedure (described in the  manual  entry
       for Tcl_OpenFileChannel).

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

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

Tcl			       7.5				8

Tcl_CreateChannel(3)  Tcl Library Procedures Tcl_CreateChannel(3)

       NULL,  which  indicates that this channel type supports no
       type specific options.

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

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

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

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

       Some options are handled by  the	 generic  code	and  this
       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.

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

	      typeded void Tcl_DriverWatchChannelProc(
		ClientData instanceData,
		int mask);

Tcl			       7.5				9

Tcl_CreateChannel(3)  Tcl Library Procedures Tcl_CreateChannel(3)

       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 mecha-
       nisms  to  notice  when an event of interest is present on
       the channel. It may invoke Tcl_SetMaxBlockTime to  specify
       an upper limit on the length of time to wait for an event,
       and it may invoke Tcl_WatchFile if the channel implementa-
       tion is based on Tcl_Files.

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

	      typedef int Tcl_DriverChannelReadyProc(
		ClientData instanceData,
		int mask);

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

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

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

	      typedef Tcl_File Tcl_DriverGetFileProc(
		ClientData instanceData,
		int direction);

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

Tcl			       7.5			       10

Tcl_CreateChannel(3)  Tcl Library Procedures Tcl_CreateChannel(3)

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

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

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

Tcl			       7.5			       11

[top]

List of man pages available for BSDi

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net