zmq_recv(3)

SYNOPSIS

int zmq_recv (void *socket, zmq_msg_t *msg, int flags);

DESCRIPTION

The zmq_recv() function shall receive a message from the socket referenced by +the socket argument and store it in the message referenced by the msg +argument. Any content previously stored in msg shall be properly deallocated. +If there are no messages available on the specified socket the zmq_recv() +function shall block until the request can be satisfied. The flags argument +is a combination of the flags defined below:

+ZMQ_NOBLOCK +: +
+Specifies that the operation should be performed in non-blocking mode. If there +are no messages available on the specified socket, the zmq_recv() function +shall fail with errno set to EAGAIN. +
+

Multi-part messages

A ØMQ message is composed of 1 or more message parts; each message part is an +independent zmq_msg_t in its own right. ØMQ ensures atomic delivery of +messages; peers shall receive either all message parts of a message or none +at all.

The total number of message parts is unlimited.

An application wishing to determine if a message is composed of multiple parts +does so by retrieving the value of the ZMQ_RCVMORE socket option on the +socket it is receiving the message from. If there are no message parts to +follow, or if the message is not composed of multiple parts, ZMQ_RCVMORE +shall report a value of zero. Otherwise, ZMQ_RCVMORE shall report a value of +1, indicating that more message parts are to follow.

RETURN VALUE

The zmq_recv() function shall return zero if successful. Otherwise it shall +return -1 and set errno to one of the values defined below.

ERRORS

+EAGAIN +: +
+Non-blocking mode was requested and no messages are available at the moment. +
+
+ENOTSUP +: +
+The zmq_recv() operation is not supported by this socket type. +
+
+EFSM +: +
+The zmq_recv() operation cannot be performed on this socket at the moment due +to the socket not being in the appropriate state. This error may occur with +socket types that switch between several states, such as ZMQ_REP. See the +messaging patterns section of zmq_socket(3) for more information. +
+
+ETERM +: +
+The ØMQ context associated with the specified socket was terminated. +
+
+EFAULT +: +
+The provided socket was not valid (NULL). +
+
+EINTR +: +
+The operation was interrupted by delivery of a signal before a message was +available. +
+

EXAMPLE

Receiving a message from a socket

/* Create an empty 0MQ message */
+zmq_msg_t msg;
+int rc = zmq_msg_init (&msg);
+assert (rc == 0);
+/* Block until a message is available to be received from socket */
+rc = zmq_recv (socket, &msg, 0);
+assert (rc == 0);
+/* Release message */
+zmq_msg_close (&msg);

Receiving a multi-part message

int64_t more;
+size_t more_size = sizeof more;
+do {
+    /* Create an empty 0MQ message to hold the message part */
+    zmq_msg_t part;
+    int rc = zmq_msg_init (&part);
+    assert (rc == 0);
+    /* Block until a message is available to be received from socket */
+    rc = zmq_recv (socket, &part, 0);
+    assert (rc == 0);
+    /* Determine if more message parts are to follow */
+    rc = zmq_getsockopt (socket, ZMQ_RCVMORE, &more, &more_size);
+    assert (rc == 0);
+    zmq_msg_close (&part);
+} while (more);

AUTHORS

This ØMQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>.

+zmq_recv(3) Manual Page +

NAME