libzmq/doc/zmq_tcp.txt

118 lines
3.7 KiB
Plaintext
Raw Normal View History

2010-02-10 16:18:46 +01:00
zmq_tcp(7)
==========
2010-01-12 13:08:37 +01:00
2010-02-10 16:18:46 +01:00
NAME
----
2010-03-09 18:47:31 +01:00
zmq_tcp - 0MQ unicast transport using TCP
2010-02-10 16:18:46 +01:00
SYNOPSIS
--------
2010-03-09 18:47:31 +01:00
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.
2010-01-12 13:08:37 +01:00
2010-03-09 18:47:31 +01:00
ADDRESSING
----------
2012-10-27 02:43:19 +02:00
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.
2010-01-12 13:08:37 +01:00
2010-03-09 18:47:31 +01:00
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.
2010-03-09 18:47:31 +01:00
An 'interface' may be specified by either of the following:
2010-01-12 13:08:37 +01:00
* The wild-card `*`, meaning all available interfaces.
* The primary IPv4 or IPv6 address assigned to the interface, in its numeric
representation.
2012-10-27 02:43:19 +02:00
* 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.
2010-01-12 13:08:37 +01:00
2014-11-05 15:16:56 +01:00
Unbinding wild-card address from a socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When wild-card `*` 'endpoint' was used in _zmq_bind()_, the caller should use
2014-11-05 15:24:22 +01:00
real 'endpoint' obtained from the ZMQ_LAST_ENDPOINT socket option to unbind
this 'endpoint' from a socket using _zmq_unbind()_.
2010-01-12 13:08:37 +01:00
2010-03-09 18:47:31 +01:00
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.
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.
2010-01-12 13:08:37 +01:00
2010-03-09 18:47:31 +01:00
A 'peer address' may be specified by either of the following:
2010-01-12 13:08:37 +01:00
2010-03-09 18:47:31 +01:00
* The DNS name of the peer.
2012-10-27 02:43:19 +02:00
* The IPv4 or IPv6 address of the peer, in its numeric representation.
2010-03-09 18:47:31 +01:00
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>
2010-03-09 18:47:31 +01:00
EXAMPLES
--------
.Assigning a local address to a socket
----
2012-10-27 02:43:19 +02:00
// TCP port 5555 on all available interfaces
2014-06-23 20:24:36 +02:00
rc = zmq_bind(socket, "tcp://*:5555");
assert (rc == 0);
2012-10-27 02:43:19 +02:00
// TCP port 5555 on the local loop-back interface on all platforms
2010-03-09 18:47:31 +01:00
rc = zmq_bind(socket, "tcp://127.0.0.1:5555");
assert (rc == 0);
2012-10-27 02:43:19 +02:00
// TCP port 5555 on the first Ethernet network interface on Linux
2010-03-09 18:47:31 +01:00
rc = zmq_bind(socket, "tcp://eth0:5555");
assert (rc == 0);
----
.Connecting a socket
----
2012-10-27 02:43:19 +02:00
// Connecting using an IP address
2010-03-09 18:47:31 +01:00
rc = zmq_connect(socket, "tcp://192.168.1.1:5555");
assert (rc == 0);
2012-10-27 02:43:19 +02:00
// Connecting using a DNS name
2010-03-09 18:47:31 +01:00
rc = zmq_connect(socket, "tcp://server1:5555");
assert (rc == 0);
// 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);
2010-02-10 16:18:46 +01:00
----
2010-01-12 13:08:37 +01:00
2010-02-10 16:18:46 +01:00
SEE ALSO
--------
2010-03-09 18:47:31 +01:00
linkzmq:zmq_bind[3]
linkzmq:zmq_connect[3]
2010-02-10 16:18:46 +01:00
linkzmq:zmq_pgm[7]
linkzmq:zmq_ipc[7]
linkzmq:zmq_inproc[7]
2010-03-09 18:47:31 +01:00
linkzmq:zmq[7]
2010-01-13 15:15:01 +01:00
AUTHORS
-------
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>.