NN_GETSOCKOPT(3)

📦
version 1.2.2 · 5 versions
, in fedora 44

🦋 NN_GETSOCKOPT(3) 🦋

okay bestie, picture this: you've got a socket, right? and you're sitting there like "girl… what is your deal? what's your linger? what's your buffer size?" — and this function right here is the one that spills the tea. it's nn_getsockopt, straight out of the nanomsg 1.2.2 manual, section 3 (the library-calls girlies). she's a getter, she only reads, she never writes. 💅

🎀 NAME 🎀

nn_getsockopt — retrieve a socket option. that's the whole job. no notes. ✨

✨ SYNOPSIS ✨

#include <nanomsg/nn.h>

int nn_getsockopt (int s, int level, int option, void *optval, size_t
*optvallen);

💖 DESCRIPTION 💖

so basically she retrieves the value for the option. that's the vibe. 🫶

the level argument tells her which protocol level the option lives at. here's the breakdown, no cap:

  • for generic socket-level options, use the NN_SOL_SOCKET level.
  • for socket-type-specific options, use the socket type as the level argument (e.g. NN_SUB).
  • for transport-specific options, use the ID of the transport as the level argument (e.g. NN_TCP).

the value lands in the buffer that optval points to, and the size of that buffer is what you hand over in optvallen. now listen, this next part is important bestie: if the size of the option is greater than the size of the buffer, the value gets silently truncated. like, no warning, no error, just vibes and missing data 😭. otherwise — meaning if everything fits — optvallen gets modified to indicate the actual length of the option. so it's an in-out situation. she tells you how much she actually wrote.

the <nanomsg/nn.h> header defines the generic socket-level options (that's the NN_SOL_SOCKET level, iykyk). and the options are as follows, queen 👑

🌈 the generic socket-level options 🌈

  • NN_DOMAIN — returns the domain constant exactly as it was passed to nn_socket(). no glow-up, no edits. 💅
  • NN_PROTOCOL — returns the protocol constant exactly as it was passed to nn_socket(). same energy. ✨
  • NN_LINGER — specifies how long the socket should try to send pending outbound messages after nn_close() has been called, in milliseconds. a negative value means infinite linger (she will simply never stop trying, main character energy). the type of the option is int. default value is 1000 (1 second).
  • NN_SNDBUF — size of the send buffer, in bytes. and here's the little detail everyone forgets: to prevent blocking for messages larger than the buffer, exactly one message may be buffered in addition to the data in the send buffer. the type of this option is int. default value is 128kB.
  • NN_RCVBUF — size of the receive buffer, in bytes. same deal, flipped: to prevent blocking for messages larger than the buffer, exactly one message may be buffered in addition to the data in the receive buffer. the type of this option is int. default value is 128kB.
  • NN_RCVMAXSIZE — maximum message size that can be received, in bytes. a negative value means the received size is limited only by available addressable memory (chaotic, honestly). the type of this option is int. default is 1024kB.
  • NN_SNDTIMEO — the timeout for send operation on the socket, in milliseconds. if the message cannot be sent within the specified timeout, the ETIMEDOUT error is returned. negative value means infinite timeout. the type of the option is int. default value is -1.
  • NN_RCVTIMEO — the timeout for recv operation on the socket, in milliseconds. if the message cannot be received within the specified timeout, the ETIMEDOUT error is returned. negative value means infinite timeout. the type of the option is int. default value is -1.
  • NN_RECONNECT_IVL — for connection-based transports such as TCP, this option specifies how long to wait, in milliseconds, when the connection is broken before trying to re-establish it. note that the actual reconnect interval may be randomised to some extent to prevent severe reconnection storms — yes bestie, the jitter is on purpose, it's protecting you from a stampede. the type of the option is int. default value is 100 (0.1 second).
  • NN_RECONNECT_IVL_MAX — this option is to be used only in addition to the NN_RECONNECT_IVL option. it specifies the maximum reconnection interval. on each reconnect attempt, the previous interval is doubled until NN_RECONNECT_IVL_MAX is reached. a value of zero means that no exponential backoff is performed and the reconnect interval is based only on NN_RECONNECT_IVL. and if NN_RECONNECT_IVL_MAX is less than NN_RECONNECT_IVL, it is ignored. the type of the option is int. default value is 0.
  • NN_SNDPRIO — retrieves the outbound priority currently set on the socket. this option has no effect on socket types that send messages to all the peers. however, if the socket type sends each message to a single peer (or a limited set of peers), peers with high priority take precedence over peers with low priority. the type of the option is int. highest priority is 1, lowest priority is 16. default value is 8.
  • NN_RCVPRIO — sets inbound priority for endpoints subsequently added to the socket. this option has no effect on socket types that are not able to receive messages. when receiving a message, messages from a peer with higher priority are received before messages from a peer with lower priority. the type of the option is int. highest priority is 1, lowest priority is 16. default value is 8.
  • NN_IPV4ONLY — if set to 1, only IPv4 addresses are used. if set to 0, both IPv4 and IPv6 addresses are used. the type of the option is int. default value is 1.
  • NN_SNDFD — retrieves a file descriptor that is readable when a message can be sent to the socket. 🫶 the descriptor should be used only for polling and never read from or written to — like, do not touch, look only. the type of the option is the same as the type of file descriptor on the platform. that is, int on POSIX-complaint platforms and SOCKET on Windows. the descriptor becomes invalid and should not be used any more once the socket is closed. this socket option is not available for unidirectional recv-only socket types.
  • NN_RCVFD — retrieves a file descriptor that is readable when a message can be received from the socket. same rules, bestie: use it only for polling and never read from or write to it. the type of the option is the same as the type of file descriptor on the platform. that is, int on POSIX-complaint platforms and SOCKET on Windows. the descriptor becomes invalid and should not be used any more once the socket is closed. this socket option is not available for unidirectional send-only socket types.
  • NN_SOCKET_NAME — socket name for error reporting and statistics. the type of the option is string. default value is "N" where N is the socket integer. 🎀 this option is experimental, see nn_env(7) for details.
  • NN_MAXTTL — retrieves the maximum number of "hops" a message can go through before it is dropped. each time the message is received (for example via the nn_device(3) function) counts as a single hop. this provides a form of protection against inadvertent loops — she's the bouncer at the club, stopping messages from going in circles forever. 🔥

🏆 RETURN VALUE 🏆

if the function succeeds, zero is returned — the humble little 0, the "we ate" of return codes. otherwise, -1 is returned and errno is set to one of the values defined below. 😭

💀 ERRORS 💀

  • EBADF — the provided socket is invalid. (who even is she? not a socket we know.)
  • ENOPROTOOPT — the option is unknown at the level indicated. (you asked the wrong girl about the wrong thing, babe.)
  • ETERM — the library is terminating. (it's not you, it's the shutdown. 🙈)

🌸 EXAMPLE 🌸

here's the whole thing in action, so you can copy it and slay:

int linger;
size_t sz = sizeof (linger);
nn_getsockopt (s, NN_SOL_SOCKET, NN_LINGER, &linger, &sz);

that's it. linger gets the value, sz gets updated, and you get to feel iconic. ✨

👑 SEE ALSO 👑

nn_socket(3) nn_setsockopt(3) nanomsg(7)

💜 AUTHORS 💜

Martin Sustrik <sustrik@250bpm.com> Garrett D'Amore <garrett@damore.org>

and that's the whole page, bestie 🫶 this was nanomsg 1.2.2, dated 2026-01-16, and it's the NN_GETSOCKOPT(3) page in all her glory. go forth, read your socket options, stay hydrated, and never read from a NN_SNDFD. 💅🎀🦋

📦 where this page comes from