NNG_PIPE_NOTIFY(3)

💅 NNG_PIPE_NOTIFY(3) — the nng_pipe_notify page, bestie edition

okay so first things first: this is a page from the NNG Reference Manual, and we're talking about nng_pipe_notify. Buckle up, it's actually so good. 🎀

---

✨ NAME ✨

nng_pipe_notify — register pipe notification callback 👑 (yes that's the whole job, and she does it flawlessly)

---

🌸 SYNOPSIS 🌸

#include <nng/nng.h>

typedef enum {
        NNG_PIPE_EV_ADD_PRE,
        NNG_PIPE_EV_ADD_POST,
        NNG_PIPE_EV_REM_POST,
} nng_pipe_ev;

typedef void (*nng_pipe_cb)(nng_pipe, nng_pipe_ev, void *);

int nng_pipe_notify(nng_socket s, nng_pipe_ev ev, nng_pipe_cb cb, void *arg);

---

🦋 DESCRIPTION 🦋

So nng_pipe_notify() signs up the callback function cb to get called whenever the pipe event you picked with ev happens on the socket s. And your callback? She gets handed arg as her final argument. So cute. 🫶

You can have a different callback for each event, slay. But here's the tea: each event can have at most one callback registered. And registering a new one? It implicitly unregisters whatever was registered before. One in, one out. Periodt. 💅

Here are the pipe events that are supported:

• NNG_PIPE_EV_ADD_PRE — this one fires after a connection and negotiation have both completed, but before the pipe gets added to the socket. And listen: if you close the pipe here (with nng_pipe_close()), the socket will never see that pipe, and no further events will happen for that pipe. Gone. Girlboss move, honestly.
• NNG_PIPE_EV_ADD_POST — this fires after the pipe is fully added to the socket. And real talk: before this moment, it is not possible to communicate over the pipe with the socket. So don't even try it. 😭
• NNG_PIPE_EV_REM_POST — this fires after the pipe has been removed from the socket. The underlying transport may be closed at this point, and it is not possible to communicate using this pipe. It's over, it's giving ex-pipe. 💀

Warning 🚨🚨 The callback cb function must not attempt to perform any accesses to the socket, because it is called with a lock on the socket held! Doing so would thus result in a deadlock. Like literally do not. You will freeze forever. The worst vibe imaginable. 💀

Tip ✨ The callback cb may close a pipe for any reason by simply closing it using nng_pipe_close(). This might be done before the pipe is added to the socket (during NNG_PIPE_EV_ADD_PRE), for example, if the remote peer is not authorized. Kick them out, respectfully. 🚪👑

Tip 🌈 It is totally possible to register the same cb and arg for different events — just call this function separately for the different values of ev. Recycling is iconic. 🧚

Note 📝 This function ignores invalid values for ev. Not mad, just ignoring you.

---

⭐ RETURN VALUES ⭐

This function returns 0 on success, and non-zero otherwise. That's it, that's the whole scale. No in-between, no "it's complicated." 🌸

---

🍓 ERRORS 🍓

• NNG_ECLOSED — the socket s does not refer to an open socket. She's closed, bestie, there's nothing to talk to. 😭

---

💜 SEE ALSO 💜

nng_pipe_close(3), nng_pipe_getopt(3), nng_pipe(5), nng_socket(5), nng(7)

---

and that's the whole page!! 🎀 source/version is NNG Reference Manual, dated 2026-06-30, footer still says NNG_PIPE_NOTIFY(3) which is so on brand. go forth and notify your pipes, bestie. no cap. 🦋✨💖