NN_PUBSUB(7)

💖 NN_PUBSUB(7) — the nanomsg pub/sub glow-up 💖

okay bestie, sit down, hydrate, and let me tell you about nn_pubsub — the publish/subscribe scalability protocol from nanomsg 1.2.2. it's giving group chat but for sockets 🫶

---

✨ NAME ✨

nn_pubsub — the publish/subscribe scalability protocol 💌

---

✨ SYNOPSIS ✨

#include <nanomsg/nn.h>

#include <nanomsg/pubsub.h>

---

✨ DESCRIPTION ✨

Broadcasts messages to multiple destinations. No cap, that's the whole vibe. 📢

Messages get sent out from NN_PUB sockets and will only be received by NN_SUB sockets that have subscribed to the matching topic. And what's a topic, you ask? It's an arbitrary sequence of bytes at the beginning of the message body. That's it. That's the topic. 🎀

The NN_SUB socket figures out whether a message should be handed to the user by comparing the subscribed topics (using NN_SUB_SUBSCRIBE on a full SUB socket) against the bytes at the start of the incoming message — up to the size of the topic. So it's a prefix match, basically. iykyk.

nn_setsockopt (s, NN_SUB, NN_SUB_SUBSCRIBE, "Hello", 5);

This will match any message whose initial 5 bytes are "Hello" — for example, the message "Hello, World!" matches. Slay. 💅

A topic with zero length matches any message. (yes, that's the "subscribe to everything" button, bestie.)

If the socket is subscribed to multiple topics, a message matching any of them will be delivered to the user. ✨

Since the filtering is performed on the Subscriber side, all the messages from the Publisher will be sent over the transport layer. Like, ALL of them. The network doesn't know who's listening. That's just how it is, fr fr. 😭

The entire message, including the topic, is delivered to the user. 🎁

---

🌸 Socket Types 🌸

• NN_PUB — This socket is used to distribute messages to multiple destinations. Receive operation is not defined. 🙈 (so don't try to receive on it, bestie, it's not that kind of socket.)
• NN_SUB — Receives messages from the publisher. Only messages that the socket is subscribed to are received. When the socket is created there are no subscriptions and thus no messages will be received. Send operation is not defined on this socket. 💀 brand new SUB socket = a phone on Do Not Disturb. subscribe first or you get nothing.

---

💅 Socket Options 💅

• NN_SUB_SUBSCRIBE — Defined on full SUB socket. Subscribes for a particular topic. Type of the option is string. A single NN_SUB socket can handle multiple subscriptions. 👑
• NN_SUB_UNSUBSCRIBE — Defined on full SUB socket. Unsubscribes from a particular topic. Type of the option is string. 🦋

---

⭐ EXAMPLE ⭐

okay this is the part where it all comes together, watch this 👑

int pub = nn_socket (AF_SP, NN_PUB);
int sub = nn_socket (AF_SP, NN_SUB);
int nbytes;
void *buf = NULL;
char *addr = "inproc://example";

nn_setsockopt (sub, NN_SUB, NN_SUB_SUBSCRIBE, "foo", 3);
nn_setsockopt (sub, NN_SUB, NN_SUB_SUBSCRIBE, "bar", 3);

nn_bind(pub, addr);
nn_connect(sub, addr);

nbytes = nn_send (pub, "foo|Hello!", 10);
assert(nbytes == 10);
nbytes = nn_recv (sub, &buf, NN_MSG, 0);
assert (nbytes == 10);
nn_freemsg (buf);

nbytes = nn_send (pub, "baz|World!", 10);

/* Message is not delivered because if matches no subscription. */
nbytes = nn_recv(sub, &buf, NN_MSG, 0);

notice how that last nn_recv is just… sitting there. no assert. no message. because "baz|World!" matches literally nothing we subscribed to. not me getting secondhand embarrassment for that message 😭

---

✨ SEE ALSO ✨

nn_bus(7) nn_reqrep(7) nn_pipeline(7) nn_survey(7) nn_pair(7) nanomsg(7) — go read these next, bestie, they're all part of the family 🫶

---

✨ AUTHORS ✨

Martin Sustrik <sustrik@250bpm.com> — thank you for your service, king 👑

---

and that's the whole page! this absolute banger of a manpage is from nanomsg 1.2.2, dated 2026-01-16. mwah 💋 go forth and broadcast, bestie 🌈💖✨