NNG_DIAL(3)

💅 NNG_DIAL(3) — the nng_dial era 💅

okay bestie, this is a page out of the NNG Reference Manual and it's all about nng_dial, and honestly? it eats. 🎀

---

✨ NAME ✨

nng_dial — create and start dialer 🦋

---

✨ SYNOPSIS ✨

#include <nng/nng.h>

int nng_dial(nng_socket s, const char *url, nng_dialer *dp, int flags);

---

✨ DESCRIPTION ✨

So the nng_dial() function does a lot in one little call, and we love an overachiever. It creates a freshly initialized nng_dialer object, ties it to the socket s, configures it to dial the address you give it in url, and then starts it immediately. If dp isn't NULL, the brand-new dialer gets stored at the address that dp points to. cute, right? 🙈

Dialers are the ones who initiate — they make the remote connection to a listener. Once that connection lands, they create a pipe, add it to the socket, and then just... wait for that pipe to close. The moment the pipe closes? The dialer is already trying to re-establish the connection again. no cap, it does not give up. 💪 Dialers will also periodically retry a connection automatically if an attempt to connect asynchronously fails.

Tip 💡 It's comfy to think of dialers as clients, but plot twist: the listener-vs-dialer thing is orthogonal to whatever server or client status a given protocol might have. Like, a req socket might have associated dialers, but it might also have associated listeners. It may even have some of each at the same time! main character energy fr fr 👑

Normally, that first attempt to connect to the address in url happens synchronously, including any name resolution you might need. Which means a failure — say the connection gets refused — comes right back at you immediately, and no further action is taken. brutal but honest. 😭

BUT. If you pass the special value NNG_FLAG_NONBLOCK in flags, then the connection attempt is made asynchronously instead. slay. ✨

And one more thing: if the connection was closed for a synchronously dialed connection, the dialer will still attempt to redial asynchronously. it's giving persistence. 🌈

Tip 💡 NNG_FLAG_NONBLOCK can help an application be more resilient, for sure — but ngl, it also generally makes diagnosing failures somewhat more difficult. pick your fighter. 🫶

Because the dialer is started immediately, it's generally not possible to apply extra configuration afterwards. If you need that, the move is to use nng_dialer_create() and nng_dialer_start() instead. iykyk. 💅

---

✨ RETURN VALUES ✨

This function returns 0 on success, and non-zero otherwise. that's it, that's the vibe check. ⭐

---

✨ ERRORS ✨

• NNG_EADDRINVAL — An invalid url was specified. 🚫
• NNG_ECLOSED — The socket s is not open.
• NNG_ECONNREFUSED — The remote peer refused the connection. rude. 😤
• NNG_ECONNRESET — The remote peer reset the connection.
• NNG_EINVAL — An invalid set of flags or an invalid url was specified.
• NNG_ENOMEM — Insufficient memory is available. 💀
• NNG_EPEERAUTH — Authentication or authorization failure. 🔒
• NNG_EPROTO — A protocol error occurred.
• NNG_EUNREACHABLE — The remote address is not reachable. 🛰️

---

✨ SEE ALSO ✨

nng_dialer_close(3), nng_dialer_create(3) nng_dialer_start(3), nng_listen(3), nng_strerror(3), nng_dialer(5), nng_pipe(5), nng(7) 🌸

---

and that's the whole page bestie, no notes. this came straight out of the NNG Reference Manual, dated 2026-06-30, and the page itself is NNG_DIAL(3) — so go forth and dial responsibly. periodt. 💖✨🎀🦋