NNG_SUB(7)

💖 NNG_SUB — the subscriber protocol, bestie edition 💖

okay so you're here for nng_sub, which lives in the NNG Reference Manual, and honestly? she's iconic. let's get into it 🫶

---

✨ SYNOPSIS ✨

#include <nng/nng.h>
#include <nng/protocol/pubsub0/sub.h>

---

🌸 DESCRIPTION 🌸

so sub is literally one half of the publisher/subscriber pattern, and it's giving dynamic duo. in this pattern, a publisher sends data, and that data gets broadcast to all the subscribers. the subscribing apps only ever see the data they actually subscribed to. slay 💅

sub is the subscriber side. pub is the publisher side. they're a matched set, no cap.

Note 📌 in this implementation, the publisher delivers every message to every subscriber. the subscribers keep their own subscriptions and filter them locally. so like… do not use this pattern trying to reduce bandwidth consumption. it is not that girl for that job 😭

the topics a subscriber subscribes to are just the first part of the message body. so applications need to construct their messages accordingly, fr fr.

---

🦋 Socket Operations 🦋

the nng_sub0_open() functions create a subscriber socket. this socket can receive messages but it literally cannot send them. if you try to send? you get NNG_ENOTSUP. periodt. 💀

---

🎀 Protocol Versions 🎀

only version 0 of this protocol is supported. (and at the time of writing, no other versions of this protocol have even been defined. like, none. zero.)

---

👑 Protocol Options 👑

here are the protocol-specific options available. sit down, hydrate, we're listing all of them 🍓

• NNG_OPT_SUB_SUBSCRIBE — this option registers a topic that the subscriber is interested in. it's write-only, and it takes an array of bytes of arbitrary size. every incoming message gets checked against the list of subscribed topics: if the body begins with the entire set of bytes in the topic, the message is accepted. if no topic matches, the message is just… discarded. bye 🙈

Note ⚠️ this option is deprecated. new applications should use the nng_sub0_socket_subscribe or nng_sub0_ctx_subscribe functions instead.

Note ⚠️ this option is a byte array. so if you use nng_setopt_string(), the NUL terminator byte gets included in the topic. if that isn't what you want, consider using nng_setopt() and passing strlen() of the topic as the topic size. iykyk.

Tip 💡 to receive all messages, you can use an empty topic (zero length). yes, empty. she contains multitudes ✨

• NNG_OPT_SUB_UNSUBSCRIBE — this option, also write-only, removes a topic from the subscription list. note that if the topic wasn't previously subscribed to with NNG_OPT_SUB_SUBSCRIBE, then you get an NNG_ENOENT error. + NOTE: this option is deprecated. new applications should use the nng_sub0_socket_unsubscribe or nng_sub0_ctx_unsubscribe functions.
• NNG_OPT_SUB_PREFNEW — (bool) this read/write option specifies the behavior of the subscriber when the queue is full. when true (and true is the default), the subscriber makes room in the queue by removing the oldest message. when false, the subscriber rejects messages if the message queue doesn't have room. choose your fighter 🌈

---

🧚 Protocol Headers 🧚

the sub protocol has no protocol-specific headers. that's it, that's the section. clean. minimal. main character energy. ⭐

---

💜 SEE ALSO 💜

• nng_sub_open(3)
• nng_sub_subscribe(3)
• nng_pub(7)
• nng(7)

---

and that's the whole page, bestie!! go forth and subscribe to things responsibly 🦋💖

— written up in the NNG Reference Manual, dated 2026-06-30. mwah 💅✨