7
zmq_tcp - 0MQ unicast transport using TCP
12
TCP is an ubiquitous, reliable, unicast transport. When connecting distributed
13
applications over a network with 0MQ, using the TCP transport will likely be
19
A 0MQ address string consists of two parts as follows:
20
'transport'`://`'endpoint'. The 'transport' part specifies the underlying
21
transport protocol to use, and for the TCP transport shall be set to `tcp`.
22
The meaning of the 'endpoint' part for the TCP transport is defined below.
25
Assigning a local address to a socket
26
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
27
When assigning a local address to a socket using _zmq_bind()_ with the 'tcp'
28
transport, the 'endpoint' shall be interpreted as an 'interface' followed by a
29
colon and the TCP port number to use.
31
An 'interface' may be specified by either of the following:
33
* The wild-card `*`, meaning all available interfaces.
34
* The primary IPv4 or IPv6 address assigned to the interface, in its numeric
36
* The interface name as defined by the operating system.
38
NOTE: Interface names are not standardised in any way and should be assumed to
39
be arbitrary and platform dependent. On Win32 platforms no short interface
40
names exist, thus only the primary IP address may be used to specify an
45
When connecting a socket to a peer address using _zmq_connect()_ with the 'tcp'
46
transport, the 'endpoint' shall be interpreted as a 'peer address' followed by
47
a colon and the TCP port number to use.
49
A 'peer address' may be specified by either of the following:
51
* The DNS name of the peer.
52
* The IPv4 or IPv6 address of the peer, in it's numeric representation.
57
0MQ messages are transmitted over TCP in frames consisting of an encoded
58
'payload length', followed by a 'flags' field and the message body. The 'payload
59
length' is defined as the combined length in octets of the message body and the
62
For frames with a 'payload length' not exceeding 254 octets, the 'payload
63
length' shall be encoded as a single octet. The minimum valid 'payload length'
64
of a frame is 1 octet, thus a 'payload length' of 0 octets is invalid and such
65
frames SHOULD be ignored.
67
For frames with a 'payload length' exceeding 254 octets, the 'payload length'
68
shall be encoded as a single octet with the value `255` followed by the
69
'payload length' represented as a 64-bit unsigned integer in network byte
72
The 'flags' field consists of a single octet containing various control flags:
74
Bit 0 (MORE): _More message parts to follow_. A value of 0 indicates that there
75
are no more message parts to follow; or that the message being sent is not a
76
multi-part message. A value of 1 indicates that the message being sent is a
77
multi-part message and more message parts are to follow.
79
Bits 1-7: _Reserved_. Bits 1-7 are reserved for future expansion and MUST be
82
The following ABNF grammar represents a single 'frame':
85
frame = (length flags data)
86
length = OCTET / (escape 8OCTET)
92
The following diagram illustrates the layout of a frame with a 'payload length'
93
not exceeding 254 octets:
97
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
98
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
99
| Payload length| Flags | Message body ... |
100
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
105
The following diagram illustrates the layout of a frame with a 'payload length'
106
exceeding 254 octets:
110
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
111
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
112
| 0xff | Payload length ... |
113
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
114
| Payload length ... |
115
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
116
| Payload length| Flags | Message body ... |
117
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
125
.Assigning a local address to a socket
127
/* TCP port 5555 on all available interfaces */
128
rc = zmq_bind(socket, "tcp://*:5555");
130
/* TCP port 5555 on the local loop-back interface on all platforms */
131
rc = zmq_bind(socket, "tcp://127.0.0.1:5555");
133
/* TCP port 5555 on the first Ethernet network interface on Linux */
134
rc = zmq_bind(socket, "tcp://eth0:5555");
140
/* Connecting using an IP address */
141
rc = zmq_connect(socket, "tcp://192.168.1.1:5555");
143
/* Connecting using a DNS name */
144
rc = zmq_connect(socket, "tcp://server1:5555");
152
linkzmq:zmq_connect[3]
155
linkzmq:zmq_inproc[7]
161
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
162
Martin Lucina <martin@lucina.net>.
added
removed
doc/zmq_tcp.txt
