Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
refchan(n)		     Tcl Built-In Commands		    refchan(n)

______________________________________________________________________________

NAME
       refchan - Command handler API of	reflected channels, version 1

SYNOPSIS
       cmdPrefix option	?arg arg ...?
______________________________________________________________________________

DESCRIPTION
       The  Tcl-level handler for a reflected channel has to be	a command with
       subcommands (termed an ensemble,	as it is a command such	as  that  cre-
       ated  by	 namespace  ensemble create, though the	implementation of han-
       dlers for reflected channel is not tied to namespace ensembles  in  any
       way). Note that cmdPrefix is whatever was specified in the call to chan
       create, and may consist of multiple arguments; this will	be expanded to
       multiple	words in place of the prefix.

       Of  all	the possible subcommands, the handler must support initialize,
       finalize, and watch. Support for	the other subcommands is optional.

   MANDATORY SUBCOMMANDS
       cmdPrefix initialize channelId mode
	      An invocation of this subcommand will be the first call the cmd-
	      Prefix  will  receive for	the specified new channelId. It	is the
	      responsibility of	this subcommand	to set up  any	internal  data
	      structures required to keep track	of the channel and its state.

	      The  return  value of the	method has to be a list	containing the
	      names of all subcommands supported by the	cmdPrefix.  This  also
	      tells  the Tcl core which	version	of the API for reflected chan-
	      nels is used by this command handler.

	      Any error	thrown by the method will abort	the  creation  of  the
	      channel  and  no	channel	will be	created. The thrown error will
	      appear as	error thrown by	chan create. Any exception other  than
	      an  error	(e.g. break, etc.) is treated as (and converted	to) an
	      error.

	      Note: If the creation of the channel was aborted due to failures
	      here, then the finalize subcommand will not be called.

	      The  mode	 argument  tells  the  handler whether the channel was
	      opened for reading, writing, or both. It is  a  list  containing
	      any  of  the strings read	or write. The list will	always contain
	      at least one element.

	      The subcommand must throw	an error if the	 chosen	 mode  is  not
	      supported	by the cmdPrefix.

       cmdPrefix finalize channelId
	      An  invocation of	this subcommand	will be	the last call the cmd-
	      Prefix will receive for the specified channelId. It will be gen-
	      erated just before the destruction of the	data structures	of the
	      channel held by the Tcl core. The	command	handler	must  not  ac-
	      cess the channelId anymore in no way. Upon this subcommand being
	      called, any internal resources allocated to this channel must be
	      cleaned up.

	      The return value of this subcommand is ignored.

	      If  the  subcommand throws an error the command which caused its
	      invocation (usually close) will appear to	have thrown  this  er-
	      ror. Any exception beyond	error (e.g. break, etc.) is treated as
	      (and converted to) an error.

	      This subcommand is not invoked if	the creation  of  the  channel
	      was aborted during initialize (See above).

       cmdPrefix watch channelId eventspec
	      This  subcommand notifies	the cmdPrefix that the specified chan-
	      nelId is interested in the events	listed in the eventspec.  This
	      argument	is  a  list containing any of read and write. The list
	      may be empty, which signals that the channel does	not wish to be
	      notified	of  any	 events. In that situation, the	handler	should
	      disable event generation completely.

	      Warning: Any return value	of the subcommand is ignored. This in-
	      cludes all errors	thrown by the subcommand, break, continue, and
	      custom return codes.

	      This subcommand interacts	with chan postevent. Trying to post an
	      event  which was not listed in the last call to watch will cause
	      chan postevent to	throw an error.

   OPTIONAL SUBCOMMANDS
       cmdPrefix read channelId	count
	      This optional subcommand is called when the user	requests  data
	      from  the	channel	channelId. count specifies how many bytes have
	      been requested. If the subcommand	is not supported  then	it  is
	      not possible to read from	the channel handled by the command.

	      The  return  value  of this subcommand is	taken as the requested
	      data bytes. If the returned data contains	more  bytes  than  re-
	      quested,	an error will be signaled and later thrown by the com-
	      mand which performed the read (usually gets or  read).  However,
	      returning	fewer bytes than requested is acceptable.

	      Note  that returning nothing (0 bytes) is	a signal to the	higher
	      layers that EOF has been reached on the channel. To signal  that
	      the  channel  is	out of data right now, but has not yet reached
	      EOF, it is necessary to throw the	error "EAGAIN",	i.e. to	either

		     return -code error	EAGAIN
	      or
		     error EAGAIN

	      For extensibility	any error whose	value is  a  negative  integer
	      number  will cause the higher layers to set the C-level variable
	      "errno" to the absolute value of this number, signaling a	system
	      error. This means	that both

		     return -code error	-11
	      and
		     error -11

	      are  equivalent  to  the examples	above, using the more readable
	      string "EAGAIN".	No other error value has such a	mapping	 to  a
	      symbolic string.

	      If  the  subcommand  throws  any	other error, the command which
	      caused its invocation (usually gets, or  read)  will  appear  to
	      have  thrown  this  error.  Any  exception  beyond  error, (e.g.
	      break, etc.) is treated as and converted to an error.

       cmdPrefix write channelId data
	      This optional subcommand is called when the user writes data  to
	      the  channel  channelId.	The  data argument contains bytes, not
	      characters. Any type of transformation (EOL,  encoding)  config-
	      ured  for	the channel has	already	been applied at	this point. If
	      this subcommand is not supported then  it	 is  not  possible  to
	      write to the channel handled by the command.

	      The  return  value  of  the subcommand is	taken as the number of
	      bytes written by the channel. Anything non-numeric will cause an
	      error  to	be signaled and	later thrown by	the command which per-
	      formed the write.	 A  negative  value  implies  that  the	 write
	      failed. Returning	a value	greater	than the number	of bytes given
	      to the handler, or zero, is forbidden and	 will  cause  the  Tcl
	      core to throw an error.

	      To  signal that the channel is not able to accept	data for writ-
	      ing right	now, it	is necessary to	throw the error	"EAGAIN", i.e.
	      to either

		     return -code error	EAGAIN
	      or
		     error EAGAIN

	      For  extensibility  any  error whose value is a negative integer
	      number will cause	the higher layers to set the C-level  variable
	      "errno" to the absolute value of this number, signaling a	system
	      error.  However, note that the exact mapping between these error
	      numbers and their	meanings is operating system dependent.

	      For example, while on Linux both

		     return -code error	-11
	      and
		     error -11

	      are  equivalent  to  the examples	above, using the more readable
	      string "EAGAIN", this is not true	for BSD, where the  equivalent
	      number is	-35.

	      The  symbolic string however is the same across systems, and in-
	      ternally translated to the correct number. No other error	 value
	      has such a mapping to a symbolic string.

	      If  the  subcommand  throws  any	other  error the command which
	      caused its invocation (usually puts) will	appear to have	thrown
	      this  error.   Any  exception beyond error (e.g. break, etc.) is
	      treated as and converted to an error.

       cmdPrefix seek channelId	offset base
	      This optional subcommand is responsible for the handling of seek
	      and  tell	 requests  on the channel channelId. If	it is not sup-
	      ported then seeking will not be possible for the channel.

	      The base argument	is one of

	      start	Seeking	is relative to the beginning of	the channel.

	      current	Seeking	is relative to the current seek	position.

	      end	Seeking	is relative to the end of the channel.

	      The base argument	of the builtin chan  seek  command  takes  the
	      same names.

	      The  offset  is an integer number	specifying the amount of bytes
	      to seek forward or backward. A positive number should seek  for-
	      ward, and	a negative number should seek backward.

	      A	 channel may provide only limited seeking. For example sockets
	      can seek forward,	but not	backward.

	      The return value of the subcommand is taken as the  (new)	 loca-
	      tion  of	the channel, counted from the start. This has to be an
	      integer number greater than or equal to zero.

	      If the subcommand	throws an error	the command which  caused  its
	      invocation  (usually  seek,  or tell) will appear	to have	thrown
	      this error. Any exception	beyond error  (e.g.  break,  etc.)  is
	      treated as and converted to an error.

	      The offset/base combination of 0/current signals a tell request,
	      i.e. seek	nothing	relative to the	current	location,  making  the
	      new  location  identical	to  the	current	one, which is then re-
	      turned.

       cmdPrefix configure channelId option value
	      This optional subcommand is for setting  the  type-specific  op-
	      tions  of	 channel  channelId. The option	argument indicates the
	      option to	be written, and	the value argument indicates the value
	      to set the option	to.

	      This subcommand will never try to	update more than one option at
	      a	time; that is behavior implemented in the Tcl channel core.

	      The return value of the subcommand is ignored.

	      If the subcommand	throws an error	the  command  which  performed
	      the  (re)configuration or	query (usually fconfigure or chan con-
	      figure) will appear to have thrown this error. Any exception be-
	      yond  error (e.g.	break, etc.) is	treated	as and converted to an
	      error.

       cmdPrefix cget channelId	option
	      This optional subcommand is used when reading a single type-spe-
	      cific  option  of	 channel channelId. If this subcommand is sup-
	      ported then the subcommand cgetall must be supported as well.

	      The subcommand should return the value of	the specified option.

	      If the subcommand	throws an error, the command  which  performed
	      the  (re)configuration or	query (usually fconfigure) will	appear
	      to have thrown this error.  Any  exception  beyond  error	 (e.g.
	      break, etc.) is treated as and converted to an error.

       cmdPrefix cgetall channelId
	      This  optional  subcommand is used for reading all type-specific
	      options of channel channelId. If this  subcommand	 is  supported
	      then the subcommand cget has to be supported as well.

	      The  subcommand  should  return  a list of all options and their
	      values.  This list must have an even number of elements.

	      If the subcommand	throws an error	the  command  which  performed
	      the  (re)configuration or	query (usually fconfigure) will	appear
	      to have thrown this error.  Any  exception  beyond  error	 (e.g.
	      break, etc.) is treated as and converted to an error.

       cmdPrefix blocking channelId mode
	      This optional subcommand handles changes to the blocking mode of
	      the channel channelId. The mode is a boolean flag. A true	 value
	      means  that  the	channel	has to be set to blocking, and a false
	      value means that the channel should be non-blocking.

	      The return value of the subcommand is ignored.

	      If the subcommand	throws an error	the command which  caused  its
	      invocation  (usually fconfigure) will appear to have thrown this
	      error. Any exception beyond error	(e.g. break, etc.) is  treated
	      as and converted to an error.

NOTES
       Some  of	 the functions supported in channels defined in	Tcl's C	inter-
       face are	not available to channels reflected to the Tcl level.

       The function Tcl_DriverGetHandleProc is not supported; i.e.   reflected
       channels	do not have OS specific	handles.

       The  function Tcl_DriverHandlerProc is not supported. This driver func-
       tion is relevant	only for stacked channels, i.e.	transformations.   Re-
       flected channels	are always base	channels, not transformations.

       The  function Tcl_DriverFlushProc is not	supported. This	is because the
       current generic I/O layer of Tcl	does not use this function anywhere at
       all. Therefore support at the Tcl level makes no	sense either. This may
       be altered in the future	(through extending the API  defined  here  and
       changing	 its  version number) should the function be used at some time
       in the future.

SEE ALSO
       chan(n)

KEYWORDS
       channel,	reflection

Tcl				      8.5			    refchan(n)

NAME | SYNOPSIS | DESCRIPTION | NOTES | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=refchan.tcl85&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help