NN_POLL(3)

💖 NN_POLL(3) 💖

okay bestie, welcome to nn_poll(3) from the nanomsg fam (manual name NN_POLL, section 3, if you were wondering 🫶). this is the page where we learn how to peek at a whole lil squad of SP sockets and go "hey, can any of y'all talk to me right now?" no cap.

---

✨ NAME ✨

nn_poll — poll a set of SP sockets for readability and/or writability

---

🌸 SYNOPSIS 🌸

#include <nanomsg/nn.h>

int nn_poll (struct nn_pollfd *fds, int nfds, int timeout);

---

🦋 DESCRIPTION 🦋

so basically this function checks a set of SP sockets and reports back whether it's possible to send a message to the socket and/or receive a message from each socket. it's giving "vibe check but for sockets" 💅

the fds argument is an array of nn_pollfd structures, and the nfds argument specifies the size of that array:

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

every entry in the array = one SP socket you want checked. the events field says which events you're checking for. its value is a bitwise combination of these icons here:

• NN_POLLIN — check whether at least one message can be received from the fd socket without blocking. like, is there mail in the mailbox? 📬
• NN_POLLOUT — check whether at least one message can be sent to the fd socket without blocking. like, is the mailbox open for business? 📮

after the function returns, the revents field contains a bitwise combination of NN_POLLIN and NN_POLLOUT depending on whether the socket is readable or writable. so that's where the receipts show up 🧾

the timeout parameter specifies how long — in milliseconds — the function should block if there are no events to report. (yes bestie, milliseconds, don't come at me with seconds 🙈)

---

👑 RETURN VALUE 👑

upon successful completion, the number of nn_pollfds structures with events signaled is returned. slay. ✨

if it times out, the return value is 0. 💀

if there's an error, -1 is returned and errno is set to one of the values below. not the vibe.

---

💜 ERRORS 💜

• EBADF — some of the provided sockets are invalid. bestie... those sockets don't exist 😭
• EINTR — the operation was interrupted by delivery of a signal before the message was sent. rude of that signal, honestly.
• ETERM — the library is terminating. it's over, periodt.

---

🎀 NOTE 🎀

nn_poll is a convenience function. you can achieve the same behaviour by using the NN_RCVFD and NN_SNDFD socket options. however, using the socket options allows for usage that's not possible with nn_poll — such as simultaneous polling for both SP and OS-level sockets, integration of SP sockets with external event loops, etc. so like, nn_poll is the cute little shortcut, but the socket options are the main character energy version 🫶

---

🌈 EXAMPLE 🌈

struct nn_pollfd pfd [2];
pfd [0].fd = s1;
pfd [0].events = NN_POLLIN | NN_POLLOUT;
pfd [1].fd = s2;
pfd [1].events = NN_POLLIN;
rc = nn_poll (pfd, 2, 2000);
if (rc == 0) {
    printf ("Timeout!");
    exit (1);
}
if (rc == -1) {
    printf ("Error!");
    exit (1);
}
if (pfd [0].revents & NN_POLLIN) {
    printf ("Message can be received from s1!");
    exit (1);
}

---

🔥 SEE ALSO 🔥

nn_socket(3) nn_getsockopt(3) nanomsg(7)

---

💖 AUTHORS 💖

Martin Sustrik <sustrik@250bpm.com> — the icon who made this, we stan 🫡

---

and that's the whole page bestie!! this was nanomsg version 1.2.2, dated 2026-01-16, and yes it's literally NN_POLL(3) again because we came full circle 🦋✨ go poll something, you got this 💅