NN_RECV(3)

🎀 NN_RECV(3) 🎀

okay bestie, welcome to nn_recv — the nanomsg 1.2.2 era, the "receive a message" girlie. she's giving inbox energy, and she's about to hand you a whole message. sit down, hydrate, let's go 💖

---

✨ NAME ✨

nn_recv — receive a message 🫶

---

🌸 SYNOPSIS 🌸

#include <nanomsg/nn.h>

int nn_recv (int s, void *buf, size_t len, int flags);

---

💅 DESCRIPTION 💅

So basically: you pull a message off the socket s and it gets dropped into the buffer that buf points at. Anything in the message that's longer than len? Truncated. gone. bye. ✂️ The bytes that exceed the length you specified in len get cut off, no cap.

BUT WAIT — there's a second option and it's lowkey iconic. nanomsg can allocate the buffer for you 🧚. To do that, you let the buf parameter be a pointer to a void* variable (yes, a pointer to pointer, we're being fancy), pointing at the receive buffer, and you set len to NN_MSG. If the call succeeds, guess what — the user is responsible for deallocating the message using the nn_freemsg(3) function. that's on you, bestie, not on the library 🙈

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

• NN_DONTWAIT — says the operation should happen in non-blocking mode. If the message can't be received straight away, the function will fail with errno set to EAGAIN. no waiting, no queuing, no patience 💀

---

⭐ RETURN VALUE ⭐

If it works? you get the number of bytes in the message. slay. ✨

If it doesn't? you get -1, and errno is set to one of the values defined right down below 👇

---

🔥 ERRORS 🔥

• EBADF — the socket you handed over is invalid. girl, that socket does not exist 😭
• ENOTSUP — this socket type simply doesn't support this operation. not every socket is built for this, and that's fine 💅
• EFSM — the operation can't be performed on this socket right now because the socket isn't in the appropriate state. this one can pop up with socket types that switch between several states, so like… mood swings, but for sockets 🦋
• EAGAIN — non-blocking mode was requested and there's literally no message to receive at this moment. empty inbox behaviour 📭
• EINTR — the operation got interrupted by a signal being delivered before the message was actually received 😵
• ETIMEDOUT — individual socket types may define their own specific timeouts, and if such a timeout gets hit, this error is what you get. time's up, babe ⏰
• ETERM — the library is terminating. we're shutting the whole thing down 🫡

---

🌈 EXAMPLES 🌈

💜 Receiving a message into a buffer allocated by the user

This example code will retrieve a message of either 100 bytes or less. If a larger message was sent it will be truncated to 100 bytes.

char buf [100];
nbytes = nn_recv (s, buf, sizeof (buf), 0);

💜 Receiving a message into a buffer allocated by nanomsg

The following will get a message from the pipe with a buffer allocated by the system. It is large enough to accommodate the entire message. This is a good way to get the entire message without truncating if the size of the message is unknown. It is the user's responsibility to call nn_freemsg(3) after processing the message.

void *buf = NULL;
nbytes = nn_recv (s, &buf, NN_MSG, 0);

if (nbytes < 0) {
    /* handle error */
    ...
}
else {
    /* process message */
    ...
    nn_freemsg (buf);
}

Note that this can be more efficient than manually allocating a buffer since it is a zero-copy operation. no copying, just vibes ✨

---

👑 SEE ALSO 👑

nn_send(3) nn_recvmsg(3) nn_socket(3) nanomsg(7)

---

🍓 AUTHORS 🍓

Martin Sustrik <sustrik@250bpm.com>

---

and that's the whole page, bestie!! 💖 this one was dated 2026-01-16 and it's serving pure nanomsg 1.2.2 realness, mwah 😘 go receive some messages, you've got this 🫶✨