zmq_tcp.txt 4.77 KB
Newer Older
1 2
zmq_tcp(7)
==========
Martin Sustrik's avatar
Martin Sustrik committed
3

4 5 6

NAME
----
Martin Lucina's avatar
Martin Lucina committed
7
zmq_tcp - 0MQ unicast transport using TCP
8 9 10 11


SYNOPSIS
--------
Martin Lucina's avatar
Martin Lucina committed
12 13 14
TCP is an ubiquitous, reliable, unicast transport. When connecting distributed
applications over a network with 0MQ, using the TCP transport will likely be
your first choice.
Martin Sustrik's avatar
Martin Sustrik committed
15 16


Martin Lucina's avatar
Martin Lucina committed
17 18
ADDRESSING
----------
Pieter Hintjens's avatar
Pieter Hintjens committed
19 20 21 22 23 24
A 0MQ endpoint is a string consisting of a 'transport'`://` followed by an
'address'. The 'transport' specifies the underlying protocol to use. The
'address' specifies the transport-specific address to connect to.

For the TCP transport, the transport is `tcp`, and the meaning of the
'address' part is defined below.
Martin Sustrik's avatar
Martin Sustrik committed
25 26


Martin Lucina's avatar
Martin Lucina committed
27 28 29 30 31
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.
32

Martin Lucina's avatar
Martin Lucina committed
33
An 'interface' may be specified by either of the following:
Martin Sustrik's avatar
Martin Sustrik committed
34

35
* The wild-card `*`, meaning all available interfaces.
Steven McCoy's avatar
Steven McCoy committed
36
* The primary IPv4 or IPv6 address assigned to the interface, in its numeric
37
  representation.
Pieter Hintjens's avatar
Pieter Hintjens committed
38 39 40 41 42 43 44 45 46 47
* The non-portable interface name as defined by the operating system.

The TCP port number may be specified by:

* A numeric value, usually above 1024 on POSIX systems.
* The wild-card `*`, meaning a system-assigned ephemeral port.

When using ephemeral ports, the caller should retrieve the actual assigned
port using the ZMQ_LAST_ENDPOINT socket option. See linkzmq:zmq_getsockopt[3]
for details.
Martin Sustrik's avatar
Martin Sustrik committed
48

49
Unbinding wild-card address from a socket
50 51
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When wild-card `*` 'endpoint' was used in _zmq_bind()_, the caller should use
52
real 'endpoint' obtained from the ZMQ_LAST_ENDPOINT socket option to unbind 
53
this 'endpoint' from a socket using _zmq_unbind()_.
Martin Sustrik's avatar
Martin Sustrik committed
54

Martin Lucina's avatar
Martin Lucina committed
55 56 57 58 59
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.
60 61 62
You can optionally specify a 'source_endpoint' which will be used as the source
address for your connection; tcp://'source_endpoint';'endpoint', see the
'interface' description above for details.
Martin Sustrik's avatar
Martin Sustrik committed
63

Martin Lucina's avatar
Martin Lucina committed
64
A 'peer address' may be specified by either of the following:
Martin Sustrik's avatar
Martin Sustrik committed
65

Martin Lucina's avatar
Martin Lucina committed
66
* The DNS name of the peer.
Pieter Hintjens's avatar
Pieter Hintjens committed
67
* The IPv4 or IPv6 address of the peer, in its numeric representation.
Martin Lucina's avatar
Martin Lucina committed
68

69 70
Note: A description of the ZeroMQ Message Transport Protocol (ZMTP) which is 
used by the TCP transport can be found at <http://rfc.zeromq.org/spec:15>
Martin Lucina's avatar
Martin Lucina committed
71

72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95

HWM
---

For the TCP transport, the high water mark (HWM) mechanism works in conjunction
with the TCP socket buffers handled at OS level.
Depending on the OS and several other factors the size of such TCP buffers will
be different. Moreover TCP buffers provided by the OS will accomodate a varying
number of messages depending on the size of messages (unlike ZMQ HWM settings
the TCP socket buffers are measured in bytes and not messages).

This may result in apparently inexplicable behaviors: e.g., you may expect that
setting ZMQ_SNDHWM to 100 on a socket using TCP transport will have the effect
of blocking the transmission of the 101-th message if the receiver is slow.
This is very unlikely when using TCP transport since OS TCP buffers will typically
provide enough buffering to allow you sending much more than 100 messages.

Of course if the receiver is slow, transmitting on a TCP ZMQ socket will eventually trigger
the "mute state" of the socket; simply don't rely on the exact HWM value.

Obviously the same considerations apply for the receive HWM (see ZMQ_RCVHWM).



Martin Lucina's avatar
Martin Lucina committed
96 97 98 99
EXAMPLES
--------
.Assigning a local address to a socket
----
Pieter Hintjens's avatar
Pieter Hintjens committed
100
//  TCP port 5555 on all available interfaces
101
rc = zmq_bind(socket, "tcp://*:5555");
102
assert (rc == 0);
Pieter Hintjens's avatar
Pieter Hintjens committed
103
//  TCP port 5555 on the local loop-back interface on all platforms
Martin Lucina's avatar
Martin Lucina committed
104 105
rc = zmq_bind(socket, "tcp://127.0.0.1:5555");
assert (rc == 0);
Pieter Hintjens's avatar
Pieter Hintjens committed
106
//  TCP port 5555 on the first Ethernet network interface on Linux
Martin Lucina's avatar
Martin Lucina committed
107 108 109 110 111 112
rc = zmq_bind(socket, "tcp://eth0:5555");
assert (rc == 0);
----

.Connecting a socket
----
Pieter Hintjens's avatar
Pieter Hintjens committed
113
//  Connecting using an IP address
Martin Lucina's avatar
Martin Lucina committed
114 115
rc = zmq_connect(socket, "tcp://192.168.1.1:5555");
assert (rc == 0);
Pieter Hintjens's avatar
Pieter Hintjens committed
116
//  Connecting using a DNS name
Martin Lucina's avatar
Martin Lucina committed
117 118
rc = zmq_connect(socket, "tcp://server1:5555");
assert (rc == 0);
119 120 121 122 123 124
//  Connecting using a DNS name and bind to eth1
rc = zmq_connect(socket, "tcp://eth1:0;server1:5555");
assert (rc == 0);
//  Connecting using a IP address and bind to an IP address
rc = zmq_connect(socket, "tcp://192.168.1.17:5555;192.168.1.1:5555");
assert (rc == 0);
125 126
----

Martin Sustrik's avatar
Martin Sustrik committed
127

128 129
SEE ALSO
--------
Martin Lucina's avatar
Martin Lucina committed
130 131
linkzmq:zmq_bind[3]
linkzmq:zmq_connect[3]
132 133 134
linkzmq:zmq_pgm[7]
linkzmq:zmq_ipc[7]
linkzmq:zmq_inproc[7]
Ilya Kulakov's avatar
Ilya Kulakov committed
135
linkzmq:zmq_vmci[7]
Martin Lucina's avatar
Martin Lucina committed
136
linkzmq:zmq[7]
137 138


139 140
AUTHORS
-------
141 142
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.