From a15854bd92db69fcd0b4444fe1b8fe3610a7acf6 Mon Sep 17 00:00:00 2001 From: Martin Lucina Date: Mon, 23 Jan 2012 08:53:19 +0100 Subject: Imported Upstream version 2.0.7.dfsg --- doc/zmq_tcp.html | 753 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 753 insertions(+) create mode 100644 doc/zmq_tcp.html (limited to 'doc/zmq_tcp.html') diff --git a/doc/zmq_tcp.html b/doc/zmq_tcp.html new file mode 100644 index 0000000..6a7ca72 --- /dev/null +++ b/doc/zmq_tcp.html @@ -0,0 +1,753 @@ + + + + + +zmq_tcp(7) + + + + + +
+

SYNOPSIS

+
+

TCP is an ubiquitous, reliable, unicast transport. When connecting distributed +applications over a network with ØMQ, using the TCP transport will likely be +your first choice.

+
+

ADDRESSING

+
+

A ØMQ address string consists of two parts as follows: +transport://endpoint. The transport part specifies the underlying +transport protocol to use, and for the TCP transport shall be set to tcp. +The meaning of the endpoint part for the TCP transport is defined below.

+

Assigning a local address to a socket

+

When assigning a local address to a socket using zmq_bind() with the tcp +transport, the endpoint shall be interpreted as an interface followed by a +colon and the TCP port number to use.

+

An interface may be specified by either of the following:

+
    +
  • +

    +The interface name as defined by the operating system. +

    +
    • +
  • +

    +The primary IPv4 address assigned to the interface, in it’s numeric representation. +

    +
    • +
  • +

    +The wildcard *, meaning that the interface address is unspecified. +

    +
    • +
+
+ + + +
+
Note
+		Interface names are not standardised in any way and should be assumed to +be arbitrary and platform dependent. On Win32 platforms no short interface +names exist, thus only the primary IPv4 address may be used to specify an +interface.
+
+

Connecting a socket

+

When connecting a socket to a peer address using zmq_connect() with the tcp +transport, the endpoint shall be interpreted as a peer address followed by +a colon and the TCP port number to use.

+

A peer address may be specified by either of the following:

+
    +
  • +

    +The DNS name of the peer. +

    +
    • +
  • +

    +The IPv4 address of the peer, in it’s numeric representation. +

    +
    • +
+
+

WIRE FORMAT

+
+

ØMQ messages are transmitted over TCP in frames consisting of an encoded +payload length, followed by a flags field and the message body. The payload +length is defined as the combined length in octets of the message body and the +flags field.

+

For frames with a payload length not exceeding 254 octets, the payload +length shall be encoded as a single octet. The minimum valid payload length +of a frame is 1 octet, thus a payload length of 0 octets is invalid and such +frames SHOULD be ignored.

+

For frames with a payload length exceeding 254 octets, the payload length +shall be encoded as a single octet with the value 255 followed by the +payload length represented as a 64-bit unsigned integer in network byte +order.

+

The flags field consists of a single octet containing various control flags:

+

Bit 0 (MORE): More message parts to follow. A value of 0 indicates that there +are no more message parts to follow; or that the message being sent is not a +multi-part message. A value of 1 indicates that the message being sent is a +multi-part message and more message parts are to follow.

+

Bits 1-7: Reserved. Bits 1-7 are reserved for future expansion and MUST be +set to zero.

+

The following ABNF grammar represents a single frame:

+
+
+
    frame           = (length flags data)
+    length          = OCTET / (escape 8OCTET)
+    flags           = OCTET
+    escape          = %xFF
+    data            = *OCTET
+
+

The following diagram illustrates the layout of a frame with a payload length +not exceeding 254 octets:

+
+
+
0                   1                   2                   3
+0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+| Payload length|     Flags     |       Message body        ... |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+| Message body ...
++-+-+-+-+-+-+- ...
+
+

The following diagram illustrates the layout of a frame with a payload length +exceeding 254 octets:

+
+
+
0                   1                   2                   3
+0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|     0xff      |               Payload length              ... |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|                       Payload length                      ... |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+| Payload length|     Flags     |        Message body       ... |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|  Message body ...
++-+-+-+-+-+-+-+ ...
+
+
+

EXAMPLES

+
+
+
Assigning a local address to a socket
+
+
/* TCP port 5555 on the local loopback interface on all platforms */
+rc = zmq_bind(socket, "tcp://127.0.0.1:5555");
+assert (rc == 0);
+/* TCP port 5555 on the first ethernet network interface on Linux */
+rc = zmq_bind(socket, "tcp://eth0:5555");
+assert (rc == 0);
+/* TCP port 5555 with an unspecified interface */
+rc = zmq_bind(socket, "tcp://*:5555");
+assert (rc == 0);
+
+
+
Connecting a socket
+
+
/* Connecting using an IP address */
+rc = zmq_connect(socket, "tcp://192.168.1.1:5555");
+assert (rc == 0);
+/* Connecting using a DNS name */
+rc = zmq_connect(socket, "tcp://server1:5555");
+assert (rc == 0);
+
+
+

SEE ALSO

+
+

zmq_bind(3) +zmq_connect(3) +zmq_pgm(7) +zmq_ipc(7) +zmq_inproc(7) +zmq(7)

+
+

AUTHORS

+
+

The ØMQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>.

+
+
+
+ + + -- cgit v1.2.3