Provided by: tcllib_1.21+dfsg-1_all bug

NAME

       comm_wire - The comm wire protocol

SYNOPSIS

       package require comm

_________________________________________________________________________________________________

DESCRIPTION

       The  comm  command  provides an inter-interpreter remote execution facility much like Tk's
       send(3tk), 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
       systems, and provides control over the remote execution path.

       This document contains a specification of the various versions of the wire  protocol  used
       by  comm  internally  for  the communication between its endpoints. It has no relevance to
       users of comm, only to developers who wish to  modify  the  package,  write  a  compatible
       facility in a different language, or some other facility based on the same protocol.

WIRE PROTOCOL VERSION 3

   BASIC LAYER
       The  basic encoding for all data is UTF-8. Because of this binary data, including the NULL
       character, can be sent over the wire as is, without the need for armoring it.

   BASIC MESSAGE LAYER
       On top of the Basic Layer we have a message oriented exchange of data.   The  totality  of
       all characters written to the channel is a Tcl list, with each element a separate message,
       each itself a list. The messages in the overall list are separated by EOL. Note  that  EOL
       characters  can occur within the list as well. They can be distinguished from the message-
       separating EOL by the fact that the data from the beginning up to their location is not  a
       valid Tcl list.

       EOL  is  signaled  through the linefeed character, i.e LF, or, hex 0x0a. This is following
       the unix convention for line-endings.

       As a list each message is composed of words. Their meaning depends on when the message was
       sent in the overall exchange. This is described in the upcoming sections.

   NEGOTIATION MESSAGES - INITIAL HANDSHAKE
       The command protocol is defined like this:

       •      The  first  message  send  by  a  client  to a server, when opening the connection,
              contains two words. The first word is a list as well, and contains the versions  of
              the  wire protocol the client is willing to accept, with the most preferred version
              first. The second word is the TCP port the client is listening on  for  connections
              to  itself.  The value 0 is used here to signal that the client will not listen for
              connections, i.e. that it is purely for sending commands, and not receiving them.

       •      The first message sent by the server to the client,  in  response  to  the  message
              above  contains  only  one word. This word is a list, containing the string vers as
              its first element, and the version of the wire protocol  the  server  has  selected
              from the offered versions as the second.

   SCRIPT/COMMAND MESSAGES
       All  messages  coming  after  the  initial  handshake consist of three words. These are an
       instruction, a transaction id, and the payload. The valid instructions  are  shown  below.
       The  transaction  ids  are used by the client to match any incoming replies to the command
       messages it sent. This means that a server has to copy the transaction id from  a  command
       message to the reply it sends for that message.

       send

       async

       command
              The  payload  is  the  Tcl  script  to execute on the server. It is actually a list
              containing the script fragments. These fragment are concatenated  together  by  the
              server  to  form  the full script to execute on the server side.  This emulates the
              Tcl "eval" semantics.  In most cases it is best to have only one word in the  list,
              a list containing the exact command.

              Examples:

                  (a)     {send 1 {{array get tcl_platform}}}
                  (b)     {send 1 {array get tcl_platform}}
                  (c)     {send 1 {array {get tcl_platform}}}

                  are all valid representations of the same command. They are
                  generated via

                  (a')    send {array get tcl_platform}
                  (b')    send array get tcl_platform
                  (c')    send array {get tcl_platform}

                  respectively

       Note  that  (a), generated by (a'), is the usual form, if only single commands are sent by
       the client.  For  example  constructed  using  list,  if  the  command  contains  variable
       arguments. Like

                  send [list array get $the_variable]

       These  three instructions all invoke the script on the server side. Their difference is in
       the treatment of result values, and thus determines if a reply is expected.

              send   A reply is expected. The sender is waiting for the result.

              async  No reply is expected, the sender has no interest in the result  and  is  not
                     waiting for any.

              command
                     A  reply  is expected, but the sender is not waiting for it. It has arranged
                     to get a process-internal notification when the result arrives.

       reply  Like the previous three command, however the tcl script in the  payload  is  highly
              restricted.   It  has to be a syntactically valid Tcl return command. This contains
              result code, value, error code, and error info.

              Examples:

                  {reply 1 {return -code 0 {}}}
                  {reply 1 {return -code 0 {osVersion 2.4.21-99-default byteOrder littleEndian machine i686 platform unix os Linux user andreask wordSize 4}}}

BUGS, IDEAS, FEEDBACK

       This document, and the package it describes,  will  undoubtedly  contain  bugs  and  other
       problems.    Please   report   such   in   the   category  comm  of  the  Tcllib  Trackers
       [http://core.tcl.tk/tcllib/reportlist].  Please also report any ideas for enhancements you
       may have for either package and/or documentation.

       When proposing code changes, please provide unified diffs, i.e the output of diff -u.

       Note further that attachments are strongly preferred over inlined patches. Attachments can
       be made by going to the Edit form of the ticket immediately after its creation,  and  then
       using the left-most button in the secondary navigation bar.

SEE ALSO

       comm

KEYWORDS

       comm, communication, ipc, message, remote communication, remote execution, rpc, socket

CATEGORY

       Programming tools

COPYRIGHT

       Copyright (c) 2005 Docs. Andreas Kupries <andreas_kupries@users.sourceforge.net>