Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

RedHat 9 (Linux i386) - man page for comm (redhat section n)

comm(n) 			       remote communication				  comm(n)

NAME
       comm - A remote communications facility for Tcl (7.6, 8.0, and later)

SYNOPSIS
       package require Tcl 8.2

       package require comm ?4.0?

       ::comm::comm send ?-async? id cmd ?arg arg ...?

       ::comm::comm self

       ::comm::comm interps

       ::comm::comm connect ?id?

       ::comm::comm new chan ?name value ...?

       ::comm::comm channels

       ::comm::comm config

       ::comm::comm config name

       ::comm::comm config ?name value ...?

       ::comm::comm shutdown Iid

       ::comm::comm abort

       ::comm::comm destroy

       ::comm::comm hook event ?+? ?script?

       ::comm::comm remoteid

       ::comm::comm_send

DESCRIPTION
       The  comm  command  provides an inter-interpreter remote execution facility much like Tk's
       send(n), except that it uses sockets rather than the X server for the communication  path.
       As  a  result,  comm works with multiple interpreters, works on Windows and Macintosh sys-
       tems, and provides control over the remote execution path.

       These commands work just like send and winfo interps :
	::comm::comm send ?-async? id cmd ?arg arg ...?
	::comm::comm interps

       This is all that is really needed to know in order to use comm

COMMANDS
       The package initializes ::comm::comm as the default chan.

       comm names communication endpoints with an id unique to each machine.  Before sending com-
       mands, the id of another interpreter is needed.	Unlike Tk's send, comm doesn't implicitly
       know the id's of all the interpreters on the system.  The following four methods  make  up
       the basic comm interface.

       ::comm::comm send ?-async? id cmd ?arg arg ...?
	      This  invokes  the given command in the interpreter named by id.	The command waits
	      for the result and remote errors are returned unless the -async option is given.

       ::comm::comm self
	      Returns the id for this channel.

       ::comm::comm interps
	      Returns a list of all the remote id's to which this  channel  is	connected.   comm
	      learns a new remote id when a command is first issued it, or when a remote id first
	      issues a command to this comm channel.  ::comm::comm  ids  is  an  alias	for  this
	      method.

       ::comm::comm connect ?id?
	      Whereas ::comm::comm send will automatically connect to the given id, this forces a
	      connection to a remote id without sending a command.  After  this,  the  remote  id
	      will appear in ::comm::comm interps.

EVAL SEMANTICS
       The  evaluation	semantics  of  ::comm::comm send are intended to match Tk's send exactly.
       This means that comm evaluates arguments on the remote side.

       If you find that ::comm::comm send doesn't work for a particular  command,  try	the  same
       thing  with  Tk's  send and see if the result is different.  If there is a problem, please
       report it.  For instance, there was had one report that this command  produced  an  error.
       Note that the equivalent send command also produces the same error.

	% ::comm::comm send id llength {a b c}
	wrong # args: should be "llength list"
	% send name llength {a b c}
	wrong # args: should be "llength list"

       The eval hook (described below) can be used to change from send's double eval semantics to
       single eval semantics.

MULTIPLE CHANNELS
       More than one comm channel (or listener) can be created	in  each  Tcl  interpeter.   This
       allows flexibility to create full and restricted channels.  For instance, hook scripts are
       specific to the channel they are defined against.

       ::comm::comm new chan ?name value ...?
	      This creates a new channel and Tcl command with the given channel name.	This  new
	      command  controls the new channel and takes all the same arguments as ::comm::comm.
	      Any remaining arguments are passed to the config method.

       ::comm::comm channels
	      This lists all the channels allocated in this Tcl interpreter.

       The default configuration parameters for a new channel are:

	 "-port 0 -local 1 -listen 0"

       The default channel ::comm::comm is created with:

	 "::comm::comm new ::comm::comm -port 0 -local 1 -listen 1"

CHANNEL CONFIGURATION
       The config method acts similar to fconfigure in that  it  sets  or  queries  configuration
       variables associated with a channel.

       ::comm::comm config

       ::comm::comm config name

       ::comm::comm config ?name value ...?
	      When  given  no  arguments,  config returns a list of all variables and their value
	      With one argument, config returns the value of just that argument.   With  an  even
	      number of arguments, the given variables are set to the given values.

       These  configuration  variables can be changed (descriptions of them are elsewhere in this
       manual page):

       -listen ?0|1?

       -local  ?0|1?

       -port   ?port?

       These configuration variables are readonly:

       -chan	chan

       -serial	n

       -socket	sockIn

       When config changes the parameters of an existing channel, it closes and reopens the  lis-
       tening socket.  An automatically assigned channel id will change when this happens.  Recy-
       cling the socket is done by invoking ::comm::comm abort, which causes all active sends  to
       terminate.

ID/PORT ASSIGNMENTS
       comm  uses  a  TCP port for endpoint id.  The interps (or ids) method merely lists all the
       TCP ports to which the channel is connected.  By default, each channel's  id  is  randomly
       assigned  by  the  operating  system  (but  usually  starts at a low value around 1024 and
       increases each time a new socket is opened).  This behavior is accomplished by giving  the
       -port config option a value of 0.  Alternately, a specific TCP port number may be provided
       for a given channel.  As a special case, comm contains code to allocate a a  high-numbered
       TCP port (>10000) by using -port {}.  Note that a channel won't be created and initialized
       unless the specific port can be allocated.

       As a special case, if the channel is configured with -listen 0, then it will not create	a
       listening socket and will use an id of 0 for itself.  Such a channel is only good for out-
       going connections (although once a connection is established, it can carry send traffic in
       both directions).

REMOTE INTERPRETERS
       By  default,  each  channel  is restricted to accepting connections from the local system.
       This can be overriden by using the -local 0 configuration option For such channels, the id
       parameter takes the form { id host }.

       WARNING: The host must always be specified in the same form (e.g., as either a fully qual-
       ified domain name, plain hostname or an IP address).

CLOSING CONNECTIONS
       These methods give control over closing connections:

       ::comm::comm shutdown Iid
	      This closes the connection to id, aborting all outstanding  commands  in	progress.
	      Note  that  nothing  prevents  the  connection  from  being immediately reopened by
	      another incoming or outgoing command.

       ::comm::comm abort
	      This invokes shutdown on all open connections in this comm channel.

       ::comm::comm destroy
	      This aborts all connections and then destroys the this comm channel itself, includ-
	      ing  closing  the  listening  socket.  Special code allows the default ::comm::comm
	      channel to be closed such that the ::comm::comm command it is not destroyed.  Doing
	      so  closes  the listening socket, preventing both incoming and outgoing commands on
	      the channel.  This sequence reinitializes the default channel:

	       "::comm::comm destroy; ::comm::comm new ::comm::comm"

       When a remote connection is lost (because the remote exited or called shutdown), comm  can
       invoke  an  application	callback.   This  can  be used to cleanup or restart an ancillary
       process, for instance.  See the lost callback below.

CALLBACKS
       This is a mechanism for setting hooks for particular events:

       ::comm::comm hook event ?+? ?script?
	      This uses a syntax similar to Tk's bind command.	Prefixing script with a +  causes
	      the  new	script	to be appended.  Without this, a new script replaces any existing
	      script.  When invoked without a script, no change is made.  In all cases,  the  new
	      hook script is returned by the command.

	      When  an	event  occurs, the script associated with it is evaluated with the listed
	      variables in scope and available.  The return code ( not the return value)  of  the
	      script is commonly used decide how to further process after the hook.

	      Common variables include:

	      chan   the name of the comm channel (and command)

	      id     the id of the remote in question

	      fid    the file id for the socket of the connection

       These are the defined events:

       connecting
	      Variables: chan id host port

	      This  hook  is  invoked  before  making a connection to the remote named in id.  An
	      error return (via error) will abort the connection attempt with the  error.   Exam-
	      ple:

	       % ::comm::comm hook connecting {
		   if [lb]string match {*[lb]02468[rb]} $id[rb] {
		       error "Can't connect to even ids"
		   }
	       }
	       % ::comm::comm send 10000 puts ok
	       Connect to remote failed: Can't connect to even ids
	       %

       connected
	      Variables: chan fid id host port

	      This  hook  is invoked immediately after making a remote connection to id, allowing
	      arbitrary authentication over the socket named by fid.  An error return (via  error
	      )  will  close  the  connection with the error.  host and port are merely extracted
	      from the id; changing any of these will have no effect on the connection,  however.
	      It is also possible to substitute and replace fid.

       incoming
	      Variables: chan fid addr remport

	      Hook  invoked when receiving an incoming connection, allowing arbitrary authentica-
	      tion over socket named by fid.  An error return (via error) will close the  connec-
	      tion  with the error.  Note that the peer is named by remport and addr but that the
	      remote id is still unknown.  Example:

	       ::comm::comm hook incoming {
		   if [lb]string match 127.0.0.1 $addr[rb] {
		       error "I don't talk to myself"
		   }
	       }

       eval   Variables: chan id cmd buffer

	      This hook is invoked after collecting a complete script from a  remote  but  before
	      evalutating  it.	This allows complete control over the processing of incoming com-
	      mands.  cmd contains either send or async.  buffer holds the  script  to	evaluate.
	      At the time the hook is called, $chan remoteid is identical in value to id.

	      By  changing  buffer, the hook can change the script to be evaluated.  The hook can
	      short circuit evaluation and cause a value to  be  immediately  returned	by  using
	      return  result (or, from within a procedure, return -code return result).  An error
	      return (via error) will return an error result, as is  if  the  script  caused  the
	      error.  Any other return will evaluate the script in buffer as normal.  For compat-
	      ibility with 3.2, break and return -code break result is	supported,  acting  simi-
	      larly to return {} and return -code return result.

	      Examples:

	      [1]    augmenting a command

		      % ::comm::comm send [lb]::comm::comm self[rb] pid
		      5013
		      % ::comm::comm hook eval {puts "going to execute $buffer"}
		      % ::comm::comm send [lb]::comm::comm self[rb] pid
		      going to execute pid
		      5013

	      [2]    short circuting a command

		      % ::comm::comm hook eval {puts "would have executed $buffer"; return 0}
		      % ::comm::comm send [lb]::comm::comm self[rb] pid
		      would have executed pid
		      0

	      [3]    Replacing double eval semantics

		      % ::comm::comm send [lb]::comm::comm self[rb] llength {a b c}
		      wrong # args: should be "llength list"
		      % ::comm::comm hook eval {return [uplevel #0 $buffer]}
		      return [lb]uplevel #0 $buffer[rb]
		      % ::comm::comm send [lb]::comm::comm self[rb] llength {a b c}
		      3

	      [4]    Using a slave interpreter

		      % interp create foo
		      % ::comm::comm hook eval {return [lb]foo eval $buffer[rb]}
		      % ::comm::comm send [lb]::comm::comm self[rb] set myvar 123
		      123
		      % set myvar
		      can't read "myvar": no such variable
		      % foo eval set myvar
		      123

	      [5]    Using a slave interpreter (double eval)

		      % ::comm::comm hook eval {return [lb]eval foo eval $buffer[rb]}

	      [6]    Subverting the script to execute

		      % ::comm::comm hook eval {
			  switch -- $buffer {
			      a {return A-OK} b {return B-OK} default {error "$buffer is a no-no"}
			  }
		      }
		      % ::comm::comm send [lb]::comm::comm self[rb] pid
		      pid is a no-no
		      % ::comm::comm send [lb]::comm::comm self[rb] a
		      A-OK

       reply  Variables: chan id buffer ret return()

	      This  hook  is  invoked  after collecting a complete reply script from a remote but
	      before evalutating it.  This allows complete control over the processing of replies
	      to sent commands.  The reply buffer is in one of the following forms

	      o      return result

	      o      return -code code result

	      o      return -code code -errorinfo info -errorcode ecode msg
       For  safety  reasons,  this  is	decomposed.   The return result is in ret, and the return
       switches are in the return array:

	      o      return(-code)

	      o      return(-errorinfo)

	      o      return(-errordcode)
       Any of these may be the empty string.  Modifying  these	four  variables  can  change  the
       return value, whereas modifying buffer has no effect.

       lost   Variables: chan id reason

	      This  hook  is  invoked when the connection to id is lost.  Return value (or thrown
	      error) is ignored.  reason is an explanatory string indicating why  the  connection
	      was lost.  Example:

	       ::comm::comm hook lost {
		   global myvar
		   if {$myvar(id) == $id} {
		       myfunc
		       return
		   }
	       }

UNSUPPORTED
       These interfaces may change or go away in subsequence releases.

       ::comm::comm remoteid
	      Returns  the  id of the sender of the last remote command executed on this channel.
	      If used by a proc being invoked remotely, it must be called before any  events  are
	      processed.  Otherwise, another command may get invoked and change the value.

       ::comm::comm_send
	      Invoking this procedure will substitute the Tk send and winfo interps commands with
	      these equivalents that use ::comm::comm.

	       proc send {args} {
		   eval ::comm::comm send $args
	       }
	       rename winfo tk_winfo
	       proc winfo {cmd args} {
		   if ![lb]string match in* $cmd[rb] {return [lb]eval [lb]list tk_winfo $cmd[rb] $args[rb]}
		   return [lb]::comm::comm interps[rb]
	       }

SECURITY
       Something here soon.

BLOCKING SEMANTICS
       There is one outstanding difference between comm and send.  When blocking in a synchronous
       remote command, send uses an internal C hook (Tk_RestrictEvents) to the event loop to look
       ahead for send-related events and only process those without processing any other  events.
       In contrast, comm uses the vwait command as a semaphore to indicate the return message has
       arrived.  The difference is that a synchronous send will block the application and prevent
       all  events (including window related ones) from being processed, while a synchronous comm
       will block the application but still allow other events will still get processed.  In par-
       ticular, after idle handlers will fire immediately when comm blocks.

       What can be done about this?  First, note that this behavior will come from any code using
       vwait to block and wait for an event to occur.  At the cost of multiple	channel  support,
       comm  could  be changed to do blocking I/O on the socket, giving send-like blocking seman-
       tics.  However, multiple channel support is a very useful  feature  of  comm  that  it  is
       deemed  too  important  to  lose.   The remaining approaches involve a new loadable module
       written in C (which is somewhat against the philosophy of comm) One way would be to create
       a   modified  version  of  the  vwait  command  that  allow  the  event	flags  passed  to
       Tcl_DoOneEvent to be specified.	For comm, just the TCL_FILE_EVENTS  would  be  processed.
       Another	way would be to implement a mechanism like Tk_RestrictEvents, but apply it to the
       Tcl event loop (since comm doesn't require Tk).	One of these approaches will be available
       in a future comm release as an optional component.

COMPATIBILITY
       comm  exports  itself  as  a  package.	The package version number is in the form major .
       minor, where the major version will only change when a non-compatible  change  happens  to
       the  API or protocol.  Minor bug fixes and changes will only affect the minor version.  To
       load comm this command is usually used:

	package require comm 3

       Note that requiring no version (or a specific version) can also be done.

       The revision history of comm includes these releases:

       4.0    Per request by John LoVerso. Improved handling of error for async invoked commands.

       3.7    Moved into tcllib and placed in a proper namespace.

       3.6    A bug in the looking up of the remoteid for a executed command could  be	triggered
	      when  the  connection was closed while several asynchronous sends were queued to be
	      executed.

       3.5    Internal change to how reply messages from a send are handled.  Reply messages  are
	      now decoded into the value to pass to return; a new return statement is then cons'd
	      up to with this value.  Previously, the return code was passed in from  the  remote
	      as  a  command to evaluate.  Since the wire protocol has not changed, this is still
	      the case.  Instead, the reply handling code decodes the reply message.

       3.4    Added more source commentary, as well as documenting config variables in	this  man
	      page.   Fixed  bug  were loss of connection would give error about a variable named
	      pending rather than the message about the lost connection.   comm  ids  is  now  an
	      alias  for comm interps (previously, it an alias for comm chans).  Since the method
	      invocation change of 3.0, break and other exceptional  conditions  were  not  being
	      returned correctly from comm send.  This has been fixed by removing the extra level
	      of indirection into the internal procedure commSend.  Also added propogation of the
	      errorCode  variable.   This  means that these commands return exactly as they would
	      with send:
	       comm send id break
	       catch {comm send id break}
	       comm send id expr 1 / 0

	      Added a new hook for reply messages.  Reworked method invocation to avoid  the  use
	      of  comm:*  procedures;  this also cut the invocation time down by 40%.  Documented
	      comm config (as this manual page still listed the defunct comm init!)

       3.3    Some minor bugs were corrected and the documentation was cleaned	up.   Added  some
	      examples for hooks.  The return semantics of the eval hook were changed.

       3.2    A  new wire protocol, version 3, was added.  This is backwards compatible with ver-
	      sion 2 but adds an exchange of supported protocol versions to allow protocol  nego-
	      tiation  in  the	future.  Several bugs with the hook implementation were fixed.	A
	      new section of the man page on blocking semantics was added.

       3.1    All the documented hooks were implemented.  commLostHook was  removed.   A  bug  in
	      comm new was fixed.

       3.0    This  is	a  new version of comm with several major changes.  There is a new way of
	      creating the methods available under the comm command.  The comm	init  method  has
	      been  retired  and is replaced by comm configure which allows access to many of the
	      well-defined internal variables.	This also generalizes the  options  available  to
	      comm  new.  Finally, there is now a protocol version exchanged when a connection is
	      established.  This will allow for future on-wire protocol changes.  Currently,  the
	      protocol version is set to 2.

       2.3    comm  ids  was  renamed  to comm channels.  General support for comm hook was fully
	      implemented, but only the lost hook exists, and it was changed to follow	the  gen-
	      eral hook API.  commLostHook was unsupported (replaced by comm hook lost) and comm-
	      Lost was removed.

       2.2    The died hook was renamed lost, to be accessed by commLostHook and an early  imple-
	      mentation of comm lost hook.  As such, commDied is now commLost.

       2.1    Unsupported method comm remoteid was added.

       2.0    comm  has been rewritten from scratch (but is fully compatible with Comm 1.0, with-
	      out the requirement to use obTcl).

AUTHOR
       John LoVerso, John@LoVerso.Southborough.MA.US

       http://www.opengroup.org/~loverso/tcl-tk/#comm

COPYRIGHT
       Copyright (C) 1995-1998 The Open Group.	  All  Rights  Reserved.   Please  see	the  file
       comm.LICENSE	 that	   accompanied	    this      source,	  or	 http://www.open-
       group.org/www/dist_client/caubweb/COPYRIGHT.free.html.

       This license for comm, new as of version 3.2, allows it to be used for free,  without  any
       licensing fee or royalty.

BUGS
       o      If  there  is  a failure initializing a channel created with ::comm::comm new, then
	      the channel should be destroyed.	Currently, it is left in an inconsistent state.

       o      There should be a way to force a channel to quiesce when	changing  the  configura-
	      tion.

       The  following  items  can be implemented with the existing hooks and are listed here as a
       reminder to provide a sample hook in a future version.

       o      Allow easier use of a slave interp for actual command  execution	(especially  when
	      operating in "not local" mode).

       o      Add host list (xhost-like) or "magic cookie" (xauth-like) authentication to initial
	      handshake.

       The following are outstanding todo items.

       o      Add an interp discovery and name->port mapping.  This is likely to be  in  a  sepa-
	      rate, optional nameserver.  (See also the related work, below.)

       o      Fix  the	{id  host} form so as not to be dependent upon canonical hostnames.  This
	      requires fixes to Tcl to resolve hostnames!

       This man page is bigger than the source file.

ON USING OLD VERSIONS OF TCL
       Tcl7.5 under Windows contains a bug that causes	the  interpreter  to  hang  when  EOF  is
       reached on non-blocking sockets.  This can be triggered with a command such as this:

	"comm send $other exit"

       Always  make  sure  the channel is quiescent before closing/exiting or use at least Tcl7.6
       under Windows.

       Tcl7.6 on the Mac contains several bugs.  It is recommended you use at least Tcl7.6p2.

       Tcl8.0 on UNIX contains a socket bug that can  crash  Tcl.   It	is  recommended  you  use
       Tcl8.0p1 (or Tcl7.6p2).

RELATED WORK
       Tcl-DP  provides an RPC-based remote execution interface, but is a compiled Tcl extension.
       See http://www.cs.cornell.edu/Info/Projects/zeno/Projects/Tcl-DP.html.

       Michael Doyle <miked@eolas.com> has code that implements the Tcl-DP  RPC  interface  using
       standard Tcl sockets, much like comm

       Andreas	Kupries  <andreas_kupries@users.sourceforge.net> uses comm and has built a simple
       nameserver   as	 part	of   his   Pool   library.    See    http://www.purl.org/net/aku-
       pries/soft/pool/index.htm.

SEE ALSO
       send(n)

comm					       4.0					  comm(n)


All times are GMT -4. The time now is 04:12 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password