NN_POLL(3compat)

💅 NN_POLL(3compat) — the NNG Reference Manual, bestie edition ✨

okay so you found nn_poll in the NNG Reference Manual and you're like "what is this legacy situation" — don't worry, I got you 🫶

---

🌸 NAME 🌸

nn_poll — poll sockets (compatible API). that's it, that's the vibe. it's the compatibility-flavoured poll 🎀

---

✨ SYNOPSIS ✨

#include <nanomsg/nn.h>

#define NN_POLLIN  1
#define NN_POLLOUT 2

struct nn_pollfd {
    int      fd;
    uint16_t events;
    uint16_t revents;
};

int nn_poll(struct nn_pollfd *pfds, int npfd, int timeout);

like, literally copy that struct exactly, bestie, don't be creative with it 💀

---

🦋 DESCRIPTION 🦋

nn_poll() polls a whole group of sockets to see who's ready to send and who's ready to receive. very "who's up, who's not" energy 👑

Note — this function is here for API compatibility with legacy libnanomsg. consider using the relevant modern API instead. fr fr, this is the nostalgia tour, not the main event 🙈

you pass in pfds, the array of sockets to poll — the manpage calls it nfds sockets in the prose while the argument is literally npfd, and honestly? we love a little inconsistency, iykyk 😭. each member of that array gets set up with:

• fd — set it to the socket 🎀
• events — set it to a mask that can contain either or both of NN_POLLIN and NN_POLLOUT ⭐

and what do those flags mean?

• NN_POLLIN — the socket is ready for receiving without blocking (meaning: a message is available on the socket, come get it bestie 🍓)
• NN_POLLOUT — the socket is ready for sending without blocking 💌

on success, the function returns the number of updates to the revents field of each member of the pfds array, setting it to show whether the requested status is true or not. slay ✨

Note — revents will only have a flag set if the corresponding flag was ALSO set in the events field. no sneaky extra flags, that's the rule 💅

now the timeout field, and this is the part where people get confused, so focus 🧚

• if timeout is positive, the function waits up to that many milliseconds. if none of the requested events happens before the timeout hits, the function returns -1 and sets the error to ETIMEDOUT 😭
• if timeout is zero, the function returns immediately, right after updating the current status of the sockets. instant. no waiting. main character speed 🔥
• if timeout is -1, the function waits forever, or until one of the requested events occurs. literally forever. committing to the bit 👑

Important — this function is ONLY suitable for sockets you got with nn_socket(). it is not compatible with file descriptors obtained via any other means — and yes, that includes file descriptors you got using the NN_SNDFD or NN_RCVFD options with nn_getsockopt(). do not try it. i'm serious 🙈

Note — this function is significantly less efficient than other polling or asynchronous I/O mechanisms, and it's provided for API compatibility only. its use is discouraged. it's giving "kept alive for the elders" 💀

Note — this function is not supported on systems other than POSIX derived platforms and Windows. if you're on something exotic, sorry babe 🌈

---

💖 RETURN VALUES 💖

this function returns the number of sockets with events on success, or -1 on error. simple as that ✨

---

🎀 ERRORS 🎀

• ENOMEM — insufficient memory available 😭
• EBADF — one of the sockets is not open 💀
• ETIMEDOUT — operation timed out ⏰
• ENOTSUP — this function is not supported on this platform 🚫

---

👑 SEE ALSO 👑

nn_errno(3compat), nn_recv(3compat), nn_send(3compat), nn_socket(3compat), nn_compat(3compat), nng(7)

go read those next, bestie, they're iconic 🫶

---

and that's the whole page!! this little gem is from the NNG Reference Manual, dated 2026-01-13, and it lives at NN_POLL(3compat) — mwah, go poll something responsibly 💅✨