zmq_connect.txt 3.67 KB
Newer Older
1 2 3 4 5 6
zmq_connect(3)
==============


NAME
----
Pieter Hintjens's avatar
Pieter Hintjens committed
7
zmq_connect - create outgoing connection from socket
8 9 10 11


SYNOPSIS
--------
12
*int zmq_connect (void '*socket', const char '*endpoint');*
13 14 15 16


DESCRIPTION
-----------
Pieter Hintjens's avatar
Pieter Hintjens committed
17 18
The _zmq_connect()_ function connects the 'socket' to an 'endpoint' and then
accepts incoming connections on that endpoint.
19

Pieter Hintjens's avatar
Pieter Hintjens committed
20 21 22
The '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.
Martin Lucina's avatar
Martin Lucina committed
23

Pieter Hintjens's avatar
Pieter Hintjens committed
24
0MQ provides the the following transports:
Martin Lucina's avatar
Martin Lucina committed
25

26
'tcp':: unicast transport using TCP, see linkzmq:zmq_tcp[7]
Pieter Hintjens's avatar
Pieter Hintjens committed
27 28
'ipc':: local inter-process communication transport, see linkzmq:zmq_ipc[7]
'inproc':: local in-process (inter-thread) communication transport, see linkzmq:zmq_inproc[7]
29
'pgm', 'epgm':: reliable multicast transport using PGM, see linkzmq:zmq_pgm[7]
Ilya Kulakov's avatar
Ilya Kulakov committed
30
'vmci':: virtual machine communications interface (VMCI), see linkzmq:zmq_vmci[7]
Martin Lucina's avatar
Martin Lucina committed
31

Pieter Hintjens's avatar
Pieter Hintjens committed
32 33 34 35 36 37 38 39 40
Every 0MQ socket type except 'ZMQ_PAIR' supports one-to-many and many-to-one
semantics. The precise semantics depend on the socket type and are defined in
linkzmq:zmq_socket[3].

NOTE: for most transports and socket types the connection is not performed
immediately but as needed by 0MQ. Thus a successful call to _zmq_connect()_
does not mean that the connection was or could actually be established.
Because of this, for most transports and socket types the order in which
a 'server' socket is bound and a 'client' socket is connected to it does not
41 42
matter. The _ZMQ_PAIR_ sockets are an exception, as they do not automatically
reconnect to endpoints.
Martin Lucina's avatar
Martin Lucina committed
43

44 45 46 47 48 49 50
NOTE: following a _zmq_connect()_, for socket types except for ZMQ_ROUTER,
the socket enters its normal 'ready' state. By contrast, following a
_zmq_bind()_ alone, the socket enters a 'mute' state in which the socket
blocks or drops messages according to the socket type, as defined in
linkzmq:zmq_socket[3]. A ZMQ_ROUTER socket enters its normal 'ready' state
for a specific peer only when handshaking is complete for that peer, which
may take an arbitrary time.
51

52 53 54 55 56 57 58 59
NOTE: for some socket types, multiple connections to the same endpoint
don't really make sense
(see https://github.com/zeromq/libzmq/issues/788).
For those socket types, any attempt to connect to an already connected endpoint
is silently ignored (i.e., returns zero).  This behavior applies to ZMQ_DEALER,
ZMQ_SUB, ZMQ_PUB, and ZMQ_REQ socket types.


60 61
RETURN VALUE
------------
Pieter Hintjens's avatar
Pieter Hintjens committed
62 63
The _zmq_connect()_ function returns zero if successful. Otherwise it returns
`-1` and sets 'errno' to one of the values defined below.
64 65 66 67


ERRORS
------
68 69
*EINVAL*::
The endpoint supplied is invalid.
70
*EPROTONOSUPPORT*::
Martin Lucina's avatar
Martin Lucina committed
71
The requested 'transport' protocol is not supported.
72
*ENOCOMPATPROTO*::
Martin Lucina's avatar
Martin Lucina committed
73
The requested 'transport' protocol is not compatible with the socket type.
74
*ETERM*::
75
The 0MQ 'context' associated with the specified 'socket' was terminated.
76 77
*ENOTSOCK*::
The provided 'socket' was invalid.
78 79
*EMTHREAD*::
No I/O thread is available to accomplish the task.
80 81 82 83


EXAMPLE
-------
Martin Lucina's avatar
Martin Lucina committed
84
.Connecting a subscriber socket to an in-process and a TCP transport
85
----
Martin Lucina's avatar
Martin Lucina committed
86 87 88
/* Create a ZMQ_SUB socket */
void *socket = zmq_socket (context, ZMQ_SUB);
assert (socket);
89
/* Connect it to an in-process transport with the address 'my_publisher' */
Martin Lucina's avatar
Martin Lucina committed
90
int rc = zmq_connect (socket, "inproc://my_publisher");
91
assert (rc == 0);
Martin Lucina's avatar
Martin Lucina committed
92 93
/* Connect it to the host server001, port 5555 using a TCP transport */
rc = zmq_connect (socket, "tcp://server001:5555");
94 95 96 97 98 99 100 101 102 103 104
assert (rc == 0);
----


SEE ALSO
--------
linkzmq:zmq_bind[3]
linkzmq:zmq_socket[3]
linkzmq:zmq[7]


105 106
AUTHORS
-------
107 108
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>.