NN_RECVMSG(3)

💖 NN_RECVMSG 💖

okay bestie so this is nn_recvmsg(3) from nanomsg — it's the fine-grained alternative to nn_recv, and yes she's a whole different girl. same energy, way more control. let's get into it 🫶

---

✨ SYNOPSIS ✨

#include <nanomsg/nn.h>

NN_EXPORT int nn_recvmsg (int s, struct nn_msghdr *msghdr, int flags);

---

🌸 DESCRIPTION 🌸

So basically: this function receives a message from socket s, and it drops that message into the buffers you specify with the msghdr parameter — plus any additional control data that came along for the ride. 💌

important bestie moment: the msghdr parameter should be nullified before being used. zero it out first, no cap.

The structure nn_msghdr contains at least these members:

struct nn_iovec *msg_iov;
int msg_iovlen;
void *msg_control;
size_t msg_controllen;

Let's break the girls down one by one 👑

• msg_iov — points to a gather array of buffers that need to get filled in.
• msg_iovlen — specifies the size of that array.
• msg_control — points to the buffer that holds control information associated with the received message.
• msg_controllen — specifies the length of that buffer.

Now, if you don't want the control information retrieved at all? Just set msg_control to NULL. easy. 💅 And for a detailed discussion of how to actually parse the control information, go check the nn_cmsg(3) man page — she's got the tea. 🍓

The structure nn_iovec defines one element in the gather array (aka one buffer to be filled in by message data) and contains these members:

void *iov_base;
size_t iov_len;

Now here's the cute part ✨ — alternatively, the nanomsg library can allocate the buffer for you. to do so:

1. Let the iov_base point to a void* variable to receive the buffer.
2. Set iov_len to NN_MSG.

After successful completion, you (yes you, bestie) are responsible for deallocating the message using the nn_freemsg(3) function. don't forget, or it's giving memory leak 😭

heads up: the gather array in the nn_msghdr structure can contain only one element in this case.

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

• NN_DONTWAIT — specifies that the operation should be performed in non-blocking mode. If the message cannot be received straight away, the function will fail with errno set to EAGAIN. she's impatient, periodt.

---

⭐ RETURN VALUE ⭐

If the function succeeds, the number of bytes in the message is returned. iconic.

Otherwise, -1 is returned and errno is set to one of the values defined below. 💀

---

💀 ERRORS 💀

• EBADF — the provided socket is invalid.
• ENOTSUP — the operation is not supported by this socket type.
• EFSM — the 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.
• EAGAIN — non-blocking mode was requested and there's no message to receive at the moment.
• EINTR — the operation was interrupted by delivery of a signal before the message was received.
• ETIMEDOUT — individual socket types may define their own specific timeouts. If such a timeout is hit, this error will be returned.
• ETERM — the library is terminating. 😭

---

🎀 EXAMPLE 🎀

struct nn_msghdr hdr;
struct nn_iovec iov [2];
char buf0 [4];
char buf1 [2];
iov [0].iov_base = buf0;
iov [0].iov_len = sizeof (buf0);
iov [1].iov_base = buf1;
iov [1].iov_len = sizeof (buf1);
memset (&hdr, 0, sizeof (hdr));
hdr.msg_iov = iov;
hdr.msg_iovlen = 2;
nn_recvmsg (s, &hdr, 0);

see how she memsets the hdr first? that's the move. 🧚

---

🦋 SEE ALSO 🦋

nn_recv(3) nn_sendmsg(3) nn_allocmsg(3) nn_freemsg(3) nn_cmsg(3) nanomsg(7)

---

💜 AUTHORS 💜

Martin Sustrik <sustrik@250bpm.com>

---

and that's the whole page bestie!! this absolute banger of a man page is from nanomsg version 1.2.2, dated 2026-01-16. go forth and receive those messages, you main character 💅✨🫶