NN_SETSOCKOPT(3)

📦
version 1.2.2 · 5 versions
, in fedora 44

💖 NN_SETSOCKOPT(3) — like, the nanomsg page for setting socket options 💖

okay bestie, gather round 🫶 this is the nn_setsockopt page from the nanomsg manual (that's the nanomsg 1.2.2 manual, section 3, iykyk) — it's the one that tells your socket how to be. ✨

🌸 NAME 🌸

nn_setsockopt — set a socket option. that's it, that's the whole vibe. 💅

🎀 SYNOPSIS 🎀

#include <nanomsg/nn.h>

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

✨ DESCRIPTION ✨

So basically: it sets the value of the option. 👑

The level argument says which protocol level the option lives at, and this part actually matters so pay attention bestie:

  • 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 new value is pointed to by optval, and the size of the option is given by optvallen. 🎯

The <nanomsg/nn.h> header defines the generic socket-level options (that's the NN_SOL_SOCKET level, keep up 💖). The options are as follows:

  • NN_SNDBUF — size of the send buffer, in bytes. To prevent blocking for messages larger than the buffer, exactly one message may be buffered in addition to the data in the send buffer. Type is int. Default value is 128kB. 🧺
  • NN_RCVBUF — size of the receive buffer, in bytes. To prevent blocking for messages larger than the buffer, exactly one message may be buffered in addition to the data in the receive buffer. Type 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. Type 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, an ETIMEDOUT error is returned. A negative value means infinite timeout. Type 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, an ETIMEDOUT error is returned. A negative value means infinite timeout. Type is int. Default value is -1. ⏳
  • NN_RECONNECT_IVL — for connection-based transports such as TCP, this one specifies how long to wait, in milliseconds, when a 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. 🌪️ Type is int. Default value is 100 (that's 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 no exponential backoff is performed and the reconnect interval is based only on NN_RECONNECT_IVL. If NN_RECONNECT_IVL_MAX is less than NN_RECONNECT_IVL, it is ignored. Type is int. Default value is 0. 📈
  • NN_SNDPRIO — sets outbound priority for endpoints subsequently added to the socket. This option has no effect on socket types that send messages to all the peers. But 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. Type 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. Type 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. Type is int. Default value is 1. 🌐
  • NN_SOCKET_NAME — socket name for error reporting and statistics. Type is string. Default value is "socket.N" where N is the socket integer. 🏷️ This option is experimental, see nn_env(7) for details.
  • NN_MAXTTL — sets 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. 🔁
  • NN_LINGER — > 🚨 bestie no 🚨 this option is not implemented, and should not be used in new code. Applications which need to be sure that their messages are delivered to a remote peer should either use an acknowledgement (implied when receiving a reply on NN_REQ sockets), or insert a suitable delay before calling nn_close(3) or exiting the application. 💀

🌈 RETURN VALUE 🌈

If the function succeeds, zero is returned. 🥳 Otherwise, -1 is returned and errno is set to one of the values defined below. 😭

💅 ERRORS 💅

  • EBADF — the provided socket is invalid. 🙈
  • ENOPROTOOPT — the option is unknown at the level indicated. 🧐
  • EINVAL — the specified option value is invalid. 💀
  • ETERM — the library is terminating. 🪦

🦋 EXAMPLE 🦋

okay so here's the little snippet, look at her go:

int linger = 1000;
nn_setsockopt (s, NN_SOL_SOCKET, NN_LINGER, &linger, sizeof (linger));
nn_setsockopt (s, NN_SUB, NN_SUB_SUBSCRIBE, "ABC", 3);

(yes bestie, NN_LINGER is right there in the example even though it's not implemented — that's just what the page says, don't come for me 🙈)

👑 SEE ALSO 👑

🎀 AUTHORS 🎀

Martin Sustrik <sustrik@250bpm.com> and Garrett D’Amore <garrett@damore.org> — absolute icons, we stan. 🫶

and that's the whole page, bestie!! ✨ this was nanomsg 1.2.2, dated 2026-01-16, page NN_SETSOCKOPT(3). slay, go set some options, and remember: read your return values, periodt. 💅💖🦋

📦 where this page comes from