zmq_tcp.txt 2.95 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


Martin Lucina's avatar
Martin Lucina committed
50 51 52 53 54
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.
Martin Sustrik's avatar
Martin Sustrik committed
55

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

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

61 62
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
63 64 65 66 67

EXAMPLES
--------
.Assigning a local address to a socket
----
Pieter Hintjens's avatar
Pieter Hintjens committed
68 69
//  TCP port 5555 on all available interfaces
rc = zmq_bind(socket, "tcp:/// :5555");
70
assert (rc == 0);
Pieter Hintjens's avatar
Pieter Hintjens committed
71
//  TCP port 5555 on the local loop-back interface on all platforms
Martin Lucina's avatar
Martin Lucina committed
72 73
rc = zmq_bind(socket, "tcp://127.0.0.1:5555");
assert (rc == 0);
Pieter Hintjens's avatar
Pieter Hintjens committed
74
//  TCP port 5555 on the first Ethernet network interface on Linux
Martin Lucina's avatar
Martin Lucina committed
75 76 77 78 79 80
rc = zmq_bind(socket, "tcp://eth0:5555");
assert (rc == 0);
----

.Connecting a socket
----
Pieter Hintjens's avatar
Pieter Hintjens committed
81
//  Connecting using an IP address
Martin Lucina's avatar
Martin Lucina committed
82 83
rc = zmq_connect(socket, "tcp://192.168.1.1:5555");
assert (rc == 0);
Pieter Hintjens's avatar
Pieter Hintjens committed
84
//  Connecting using a DNS name
Martin Lucina's avatar
Martin Lucina committed
85 86
rc = zmq_connect(socket, "tcp://server1:5555");
assert (rc == 0);
87 88
----

Martin Sustrik's avatar
Martin Sustrik committed
89

90 91
SEE ALSO
--------
Martin Lucina's avatar
Martin Lucina committed
92 93
linkzmq:zmq_bind[3]
linkzmq:zmq_connect[3]
94 95 96
linkzmq:zmq_pgm[7]
linkzmq:zmq_ipc[7]
linkzmq:zmq_inproc[7]
Martin Lucina's avatar
Martin Lucina committed
97
linkzmq:zmq[7]
98 99


100 101
AUTHORS
-------
Pieter Hintjens's avatar
Pieter Hintjens committed
102 103
This 0MQ manual page was written by Pieter Hintjens <ph@imatix.com>,
Martin Sustrik <sustrik@250bpm.com> and Martin Lucina <mato@kotelna.sk>.