NNG_LISTENER_GET(3)

📦
version 1.12.0 · 4 versions
, in ubuntu stonking

💖 NNG_LISTENER_GET(3) 💖

okay bestie, so this is a page from the NNG Reference Manual and it's all about peeking at your listener's settings. pull up a chair, grab a boba, we're doing this. 🧋✨

🌸 NAME 🌸

nng_listener_get — get listener option

✨ SYNOPSIS ✨

#include <nng/nng.h>

int nng_listener_get(nng_listener l, const char *opt, void *val, size_t *valszp);

int nng_listener_get_bool(nng_listener l, const char *opt, bool *bvalp);

int nng_listener_get_int(nng_listener l, const char *opt, int *ivalp);

int nng_listener_get_ms(nng_listener l, const char *opt, nng_duration *durp);

int nng_listener_get_ptr(nng_listener l, const char *opt, void **ptr);

int nng_listener_get_size(nng_listener l, const char *opt, size_t *zp);

int nng_listener_get_addr(nng_listener l, const char *opt, nng_sockaddr *sap);

int nng_listener_get_string(nng_listener l, const char *opt, char **strp);

int nng_listener_get_uint64(nng_listener l, const char *opt, uint64_t *u64p);

int nng_listener_get_url(nng_listener l, const nng_url **url);
no cap, that's a LOT of forms. but they're all just the same vibe with different types, we'll get there 💅

🦋 DESCRIPTION 🦋

So the nng_listener_get() functions are how you retrieve option values for the listener l. and like, which options you can actually pull depends on stuff — a bunch of them are documented over in nng_options(5).

on top of that, some transport-specific options are documented with the transports themselves. iykyk. 🌈

🎀 Forms 🎀

In all of these forms, the option opt is retrieved from the listener l. that's the constant. the forms just vary based on the type of the option they take.

the details of the type, size, and semantics of the option totally depend on the actual option, and they'll be documented with the option itself. don't @ me, @ the option. 😌

nng_listener_get()

this one is untyped and it's the multitasker — it can retrieve the value of any option. your job: stash a pointer to a buffer that'll receive the value in val, and the size of that buffer shall be stored at the location referenced by valszp. yes bestie, shall. the manpage said it, not me.

when the function returns, the actual size of the data copied — or the size that would have been copied if there were enough room — gets stored at the location referenced by valszp. and here's the tea: if your buffer isn't big enough to hold the whole entire object, the copy is truncated. 😭 so you gotta validate that the returned size in valszp doesn't exceed your original buffer size, to check for truncation. protect yourself.

it's acceptable to pass NULL for val if the value in valszp is zero. this is the lil hack you use to figure out how big the buffer needs to be to receive the object. iconic behavior honestly. 💅

Tip — it might be easier to use one of the typed forms of this function. just saying. 🫶

nng_listener_get_bool()

for options that take a Boolean (bool). the value gets stored at bvalp. true or false, no in between, no "it's complicated". ✨

nng_listener_get_int()

for options that take an integer (int). the value gets stored at ivalp. 🔢

nng_listener_get_ms()

used to retrieve time durations — think timeouts — stored in durp as a number of milliseconds. ticking clock energy. ⏰

nng_listener_get_ptr()

used to retrieve a pointer, ptr, to structured data. the data referenced by ptr is generally managed using other functions. and lowkey this form is a lil special: the object is generally not copied — instead, the pointer to the object is copied. so you're holding hands with the original, not a lookalike. 🙈

nng_listener_get_size()

used to retrieve a size into the pointer zp — typically for buffer sizes, message maximum sizes, and similar options. sizes stay sizes. 📏

nng_listener_get_addr()

used to retrieve an nng_sockaddr into the value referenced by sap. address acquired. 🏠

nng_listener_get_string()

used to retrieve a string into strp. important: this string is created from the source using nng_strdup(), so consequently it must be freed by the caller using nng_strfree() when it's no longer needed. do NOT forget, that's a memory leak and it's giving chaos. 💀

nng_listener_get_uint64()

used to retrieve a 64-bit unsigned value into the value referenced by u64p. typically used for options related to identifiers, network numbers, and similar. big numbers, big vibes. 🔥

nng_listener_get_url()

used to obtain the URL that the listener is configured for. and listen — this is the actual URL, which may be different than what you requested. for example: when using TCP, if port 0 was requested, but then the listener was started, a real port will have been chosen by the operating system. this URL will reflect that final port, so it can be used for dialing. the glow-up is real. 👑

💜 RETURN VALUES 💜

these functions return 0 on success, and non-zero otherwise. that's it, that's the whole deal. periodt.

💅 ERRORS 💅

  • NNG_EBADTYPE — incorrect type for option. wrong type, wrong vibe. 🙅
  • NNG_ECLOSED — parameter l does not refer to an open listener. she's closed bestie. 🚪
  • NNG_EINVAL — size of destination val too small for object. your buffer said "not today". 😭
  • NNG_ENOMEM — insufficient memory exists. the RAM said no. 💀
  • NNG_ENOTSUP — the option opt is not supported. not supported, not on the menu. 🚫
  • NNG_EWRITEONLY — the option opt is write-only. read-only's chaotic cousin — you write it, you don't read it. 📝

🌈 SEE ALSO 🌈

okay that's the whole page, you ate that. 🍓✨ this was the NNG_LISTENER_GET(3) page from the NNG Reference Manual, dated 2026-06-30 — and yeah, it's still called NNG_LISTENER_GET(3) at the bottom too, because some things never change. mwah, go read your options, bestie. 💖🦋🎀

📦 where this page comes from