ZMQ_RECVMSG(3)

💌 ZMQ_RECVMSG(3) — the 0MQ manual, but make it make sense

okay bestie, pull up a chair, we're learning zmq_recvmsg today and honestly? it's giving main character energy for anyone doing message passing. this is the page from the 0MQ manual, so like, you're in the right place. 🎀

---

✨ NAME ✨

zmq_recvmsg — receive a message part from a socket 🫶

---

✨ SYNOPSIS ✨

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

---

✨ DESCRIPTION ✨

so basically, zmq_recvmsg() receives a message part from the socket that socket points at, and it stores that part in the message that msg points at. 💅

and listen — anything that was already chillin' inside msg beforehand? it gets properly deallocated. no leaks, no leftovers, we clean up after ourselves in this house.

if there are literally no message parts available on that socket yet, zmq_recvmsg() shall block until the request can be satisfied. it's patient like that. it'll just wait. 🧘

the flags argument is a combination of the flags defined below:

• ZMQ_DONTWAIT — says the operation should run in non-blocking mode. so if there are no messages available on the specified socket, zmq_recvmsg() shall fail with errno set to EAGAIN. no waiting around, we move on. ✨

⚠️ note: this API method is deprecated in favor of zmq_msg_recv(3). it still works, but like, the new one is the moment. 👑

🌸 Multi-part messages 🌸

a 0MQ message is composed of 1 or more message parts. each message part is an independent zmq_msg_t in its own right — they're individuals, not a group project. 🌈

0MQ ensures atomic delivery of messages: peers shall receive either all message parts of a message or none at all. no half-delivered situationships here, periodt. 💀

the total number of message parts is unlimited except by available memory. yes bestie, unlimited. go feral.

if your application processes multi-part messages, you must use the ZMQ_RCVMORE zmq_getsockopt(3) option after calling zmq_recvmsg() to figure out if there are further parts to receive. otherwise you'll be standing there wondering if that was it, and that's embarrassing. 😭

---

✨ RETURN VALUE ✨

the zmq_recvmsg() function shall return the number of bytes in the message if it succeeds. slay. 💖

otherwise it shall return -1 and set errno to one of the values defined below. not slay, but informative.

---

✨ ERRORS ✨

• EAGAIN — either the timeout set via the socket-option ZMQ_RCVTIMEO (see zmq_setsockopt(3)) has been reached (with flag ZMQ_DONTWAIT not set) without being able to read a message from the socket, or there are no messages available at the moment (with flag ZMQ_DONTWAIT set) and the operation would block. either way: nothing to read right now, bestie. 🙈
• ENOTSUP — the zmq_recvmsg() operation is not supported by this socket type. this socket said "not my job." 💅
• EFSM — the zmq_recvmsg() operation cannot be performed on this socket at the moment because the socket is not 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 info. it's a timing thing, it's not you. 🦋
• ETERM — the 0MQ context associated with the specified socket was terminated. it's gone, babes. 💀
• ENOTSOCK — the provided socket was invalid. that's not a socket, that's a stranger. 😭
• EINTR — the operation was interrupted by delivery of a signal before a message was available. rude of that signal, honestly.
• EFAULT — the message passed to the function was invalid. 👑 (derogatory)

---

✨ 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_recvmsg (socket, &msg, 0);
assert (rc != -1);
/* Release message */
zmq_msg_close (&msg);

receiving a multi-part message. 🌈✨

int 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_recvmsg (socket, &part, 0);
    assert (rc != -1);
    /* 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);

---

✨ SEE ALSO ✨

zmq_recv(3) zmq_send(3) zmq_getsockopt(3) zmq_setsockopt(3) zmq_socket(7) zmq(7) — go read these too, they're the friend group. 🫶

---

✨ AUTHORS ✨

this page was written by the 0MQ community. if you wanna make a change, please read the 0MQ Contribution Policy at http://www.zeromq.org/docs:contributing. they'd love to have you. 💜

---

and that's the whole page, bestie!! this was the 0MQ 4.3.5 version, dated 10/09/2023, and honestly it ate. go forth and receive your messages responsibly. mwah 💅✨