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

EXAMPLES
--------
.Assigning a local address to a socket
----
Pieter Hintjens's avatar
Pieter Hintjens committed
76
//  TCP port 5555 on all available interfaces
77
rc = zmq_bind(socket, "tcp://*:5555");
78
assert (rc == 0);
Pieter Hintjens's avatar
Pieter Hintjens committed
79
//  TCP port 5555 on the local loop-back interface on all platforms
Martin Lucina's avatar
Martin Lucina committed
80 81
rc = zmq_bind(socket, "tcp://127.0.0.1:5555");
assert (rc == 0);
Pieter Hintjens's avatar
Pieter Hintjens committed
82
//  TCP port 5555 on the first Ethernet network interface on Linux
Martin Lucina's avatar
Martin Lucina committed
83 84 85 86 87 88
rc = zmq_bind(socket, "tcp://eth0:5555");
assert (rc == 0);
----

.Connecting a socket
----
Pieter Hintjens's avatar
Pieter Hintjens committed
89
//  Connecting using an IP address
Martin Lucina's avatar
Martin Lucina committed
90 91
rc = zmq_connect(socket, "tcp://192.168.1.1:5555");
assert (rc == 0);
Pieter Hintjens's avatar
Pieter Hintjens committed
92
//  Connecting using a DNS name
Martin Lucina's avatar
Martin Lucina committed
93 94
rc = zmq_connect(socket, "tcp://server1:5555");
assert (rc == 0);
95 96 97 98 99 100
//  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);
101 102
----

Martin Sustrik's avatar
Martin Sustrik committed
103

104 105
SEE ALSO
--------
Martin Lucina's avatar
Martin Lucina committed
106 107
linkzmq:zmq_bind[3]
linkzmq:zmq_connect[3]
108 109 110
linkzmq:zmq_pgm[7]
linkzmq:zmq_ipc[7]
linkzmq:zmq_inproc[7]
Ilya Kulakov's avatar
Ilya Kulakov committed
111
linkzmq:zmq_vmci[7]
Martin Lucina's avatar
Martin Lucina committed
112
linkzmq:zmq[7]
113 114


115 116
AUTHORS
-------
117 118
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>.