NNG_PIPE_GET(3)

📦
version 1.12.0 · 4 versions
, in ubuntu stonking

✨ NNG_PIPE_GET(3) ✨

okay bestie, welcome to nng_pipe_get from the NNG Reference Manual 💖 this is the one where we read stuff off a pipe, no cap.

🌸 NAME 🌸

nng_pipe_get — get pipe option. that's it, that's the whole vibe 🎀

🦋 SYNOPSIS 🦋

#include <nng/nng.h>

int nng_pipe_get(nng_pipe p, const char *opt, void *val, size_t *valszp);

int nng_pipe_get_bool(nng_pipe p, const char *opt, bool *bvalp);

int nng_pipe_get_int(nng_pipe p, const char *opt, int *ivalp);

int nng_pipe_get_ms(nng_pipe p, const char *opt, nng_duration *durp);

int nng_pipe_get_ptr(nng_pipe p, const char *opt, void **ptr);

int nng_pipe_get_addr(nng_pipe p, const char *opt, nng_sockaddr *sap);

int nng_pipe_get_string(nng_pipe p, const char *opt, char **strp);

int nng_pipe_get_size(nng_pipe p, const char *opt, size_t *zp);

int nng_pipe_get_uint64(nng_pipe p, const char *opt, uint64_t *u64p);

💅 DESCRIPTION 💅

so the nng_pipe_get() functions are literally how you pull option values off the pipe p. 🌈 which options you can grab this way? it varies, babes — a whole bunch of them live in nng_options(5), and also some transport-specific options and protocol-specific options are documented with the transports and protocols themselves. iykyk 🫶

Note — every single option on a pipe is read-only. if you wanna modify options, you gotta do it before the pipe even exists, using nng_listener_set() or nng_dialer_set(). periodt. 💅

also: any option that's set on a dialer or listener will normally be retrievable from pipes created by that dialer or listener. cute, right? ✨

🎀 Forms 🎀

in every one of these forms, the option opt gets retrieved from the pipe p.

the type, size, and semantics of the option? depends entirely on the actual option, and it's documented with the option itself. no guessing here bestie 🙈

  • nng_pipe_get() — this one is untyped and can fetch the value of any option. you hand it val, a pointer to the buffer that'll receive the value, and valszp, the location where the buffer size is stored.

when the function comes back, the location referenced by valszp holds the actual size of the data that got copied (or that would have been copied if there'd been enough room 👀). if your buffer isn't big enough to hold the whole object, the copy gets truncated. so pls, check for truncation by verifying that the size returned in valszp does not exceed your original buffer size. do not skip this, fr fr 😭

it's totally acceptable to pass NULL for val when the value in valszp is zero. that trick lets you figure out how big a buffer you actually need. main character energy 🎀

Tip — it may be easier to use one of the typed forms of this function. just saying 👑
  • nng_pipe_get_bool() — for options that take a Boolean (bool). the value lands at bvalp. ✅
  • nng_pipe_get_int() — for options that take an integer (int). the value lands at ivalp. 🔢
  • nng_pipe_get_ms() — retrieves time durations (nng_duration) in milliseconds, stored in durp. ⏱️
  • nng_pipe_get_ptr() — retrieves a pointer, ptr, to structured data. the data that ptr points at is generally managed using other functions. note this form is somewhat special: the object is generally not copied, instead the pointer to the object is copied. 😳 big difference, okay?
  • nng_pipe_get_size() — retrieves a size into the pointer zp. typically for buffer sizes, message maximum sizes, and similar options. 📏
  • nng_pipe_get_addr() — retrieves an nng_sockaddr into sap. 🌐
  • nng_pipe_get_string() — retrieves a string into strp. heads up: this string is created from the source using nng_strdup() and consequently must be freed by the caller using nng_strfree() when it's no longer needed. don't leak, bestie 🍓
  • nng_pipe_get_uint64() — retrieves a 64-bit unsigned value into the value referenced by u64p. typically used for options related to identifiers, network numbers, and similar. 🧚

⭐ RETURN VALUES ⭐

these functions return 0 on success, and non-zero otherwise. that's the whole thing 💜

💀 ERRORS 💀

  • NNG_EBADTYPE — incorrect type for option. wrong vibe, wrong shape 🙈
  • NNG_ECLOSED — parameter p does not refer to an open pipe. it's giving closed, bestie 😭
  • NNG_ENOENT — parameter p does not refer to an existing pipe. doesn't exist. nowhere. gone. 💀
  • NNG_ENOTSUP — the option opt is not supported. not on the menu 🚫
  • NNG_ENOMEM — insufficient memory exists. out of RAM, out of luck 🌧️
  • NNG_EINVAL — size of destination val too small for object. you said no to truncation, remember? 👑
  • NNG_EWRITEONLY — the option opt is write-only. you can write it, you just can't read it. the audacity 😤

🌈 SEE ALSO 🌈

nng_dialer_set(3) nng_socket_get(3), nng_listener_set(3) nng_msg_get_pipe(3) nng_strdup(3), nng_strerror(3), nng_strfree(3), nng_duration(5), nng_options(5), nng_pipe(5), nng_sockaddr(5), nng(7)

and that's the page, bestie 🫶 this was NNG_PIPE_GET(3) from the NNG Reference Manual, dated 2026-06-30 — go forth and read those options, you absolute icon 👑💖✨

📦 where this page comes from