NNG_RECV(3)

📦
version 1.12.0 · 4 versions
, in ubuntu stonking

✨ NAME ✨

nng_recv — recv data 💌 (like, it receives a message, that's the whole job, and it eats every time)

This is the nng_recv page from the NNG Reference Manual, section 3, so if you're here you're probably trying to scoop a message out of a socket. Say less bestie, I got you 🫶

🌸 SYNOPSIS 🌸

#include <nng/nng.h>

int nng_recv(nng_socket s, void *data, size_t *sizep, int flags);

💅 DESCRIPTION 💅

okay so nng_recv() receives a message. That's it, that's the vibe, that's the whole function ✨

The flags is a bit mask, which is just fancy talk for "you can stack these lil guys together with |" — and it may contain any of the following values:

  • NNG_FLAG_NONBLOCK — bestie the function bails immediately, even if there's literally no message waiting for you. Without this flag? It's gonna sit there and wait until a message gets received by socket s, or until some configured timer runs out. Patient queen behavior ⏳
  • NNG_FLAG_ALLOC — if this flag is present, then a zero-copy mode is used. In that case the caller must set the value of data to the location of another pointer (of type void *), and the sizep pointer must be set to a location to receive the size of the message body. Then the function will allocate a message buffer (as if by nng_alloc()), fill it with the message body, and store it at the address referenced by data, and update the size referenced by sizep. And now the caller is responsible for disposing of the received buffer either by the nng_free() function or by passing the message (also with the NNG_FLAG_ALLOC flag) in a call to nng_send(). Your buffer, your responsibility, no cap 🎀

If the special flag NNG_FLAG_ALLOC (see above, it's the second one 💖) is not specified, then the caller must set data to a buffer to receive the message body content, and must store the size of that buffer at the location pointed to by sizep. When the function returns, if it is successful, the size at sizep will be updated with the actual message body length copied into data. So you hand it a bucket, it tells you how full the bucket got 🪣

Note 📌 The NNG_FLAG_ALLOC flag is deprecated and may be removed in a future release. Applications should use nng_recvmsg() for zero copy performance improvements. Ma'am that flag is on thin ice, use the other one 🙈
Note 📌 The semantics of what receiving a message means vary from protocol to protocol, so examination of the protocol documentation is encouraged. Like, for example, with a req socket a message may only be received after a request has been sent, and a sub socket may only receive messages corresponding to topics to which it has subscribed. Every protocol has its own rules, it's giving ✨ lore ✨. Furthermore, some protocols may not support receiving data at all, such as pub. yeah, that one's just here to talk, not to listen 💀

🔥 RETURN VALUES 🔥

This function returns 0 on success, and non-zero otherwise. Zero is the slay outcome, anything else means something went sideways 🫠

😭 ERRORS 😭

  • NNG_EAGAIN — the operation would block, but NNG_FLAG_NONBLOCK was specified. You asked it not to wait and it had nothing to give, so.
  • NNG_ECLOSED — the socket s is not open. She's gone, bestie 🚪
  • NNG_EINVAL — an invalid set of flags was specified. You mixed a combo that doesn't exist 😬
  • NNG_EMSGSIZE — the received message did not fit in the size provided. Too big for the bucket 🍓
  • NNG_ENOMEM — insufficient memory is available. The machine is full 😵
  • NNG_ENOTSUP — the protocol for socket s does not support receiving. It said "not my job" 💅
  • NNG_ESTATE — the socket s cannot receive data in this state. Wrong moment, wrong state, wrong everything.
  • NNG_ETIMEDOUT — the operation timed out. You waited, the vibe expired ⏰

🦋 SEE ALSO 🦋

okay that's the whole page bestie, you're officially certified in receiving messages 🎓✨ this was NNG_RECV(3) from the NNG Reference Manual, dated 2026-06-30 — go forth, receive responsibly, and remember to free your buffers 💖👑🫶

📦 where this page comes from