NN_SETSOCKOPT(3compat)

📦 version 1.11, in alpine 3.24

💅 NN_SETSOCKOPT(3compat) 💅

okay so bestie, welcome to the NNG Reference Manual page for NN_SETSOCKOPT(3compat) — yes, that manual name is folded in right here at the top, iconic behavior only ✨. This is the compatibility-API page, and we’re gonna get through every single detail together, no cap 🫶.

🎀 NAME 🎀

nn_setsockopt — set socket option (compatible API) 💖

✨ SYNOPSIS ✨

#include <nanomsg/nn.h>

int nn_setsockopt(int sock, int level, int option, const void *val, size_t sz);

🌸 DESCRIPTION 🌸

okay so nn_setsockopt() sets a socket option on socket sock, and it 100% affects the behavior of the socket. The option set is determined by level and option. The value of the option is set by val, and sz, which are pointers to the actual value and the size of the value, respectively. slay, that’s the whole setup 💅.

Note: This function is provided for API compatibility with legacy libnanomsg. Consider using the relevant modern API instead. like, respect the legacy era, but maybe don’t make it your whole personality bestie 🦋

The level determines whether the option is a generic socket option, or is transport-specific. The values possible for level are as follows:

  • NN_SOL_SOCKET — Generic socket option 🌈
  • NN_IPC — Transport specific option for IPC.
  • NN_TCP — Transport specific option for TCP.
  • NN_WS — Transport specific option for WebSocket.

The following generic socket options are possible — all are of type int and thus size 4, unless otherwise indicated. clock that caveat, bestie ⭐

  • NN_SNDBUF — Send buffer size in bytes.
Note: In NNG buffers are sized as a count of messages rather than bytes, and so an attempt to estimate a conversion based upon a predetermined message size of 1kB is made. The value supplied is rounded up to the nearest value divisible by 1024, and then divided by 1024 to convert to a message count. Applications that have unusual message sizes may wish to adjust the value used here accordingly. math girlie behavior, but make it sockets 🧚
  • NN_RCVBUF — Receive buffer size in bytes.
Note: The same caveats for NN_SNDBUF apply here as well. 💀
  • NN_SNDTIMEO — Send time-out in milliseconds. Send operations will fail with ETIMEDOUT if no message can be received after this many milliseconds have transpired since the operation was started. A value of -1 means that no timeout is applied. ⏳
  • NN_RCVTIMEO — Receive time-out in milliseconds. Receive operations will fail with ETIMEDOUT if no message can be received after this many milliseconds have transpired since the operation was started. A value of -1 means that no timeout is applied. 🕰️
  • NN_RCVMAXSIZE — Maximum receive size in bytes. The socket will discard messages larger than this on receive. The default, 1MB, is intended to prevent denial-of-service attacks. The value -1 removes any limit. security girlie said not today 🛡️
  • NN_RECONNECT_IVL — Reconnect interval in milliseconds. After an outgoing connection is closed or fails, the socket will automatically attempt to reconnect after this many milliseconds. This is the starting value for the time, and is used in the first reconnection attempt after a successful connection is made. The default is 100. 🔁
  • NN_RECONNECT_IVL_MAX — Maximum reconnect interval in milliseconds. Subsequent reconnection attempts after a failed attempt are made at exponentially increasing intervals (back-off), but the interval is capped by this value. If this value is smaller than NN_RECONNECT_IVL, then no exponential back-off is performed, and each reconnect interval will be determined solely by NN_RECONNECT_IVL. The default is zero. 📈
  • NN_LINGER — This option is ignored, and exists only for compatibility.
Note: This option was unreliable in early releases of libnanomsg, and is unsupported in NNG and recent libnanomsg releases. Applications needing assurance of message delivery should either include an explicit notification (automatic with the NN_REQ protocol) or allow sufficient time for the socket to drain before closing the socket or exiting. read that note twice, bestie, it’s giving important 🚨
  • NN_SNDPRIO — This option is not implemented at this time. 🙈
  • NN_RCVPRIO — This option is not implemented at this time. 🙈
  • NN_IPV4ONLY — This option is not implemented at this time. 🙈
  • NN_SOCKET_NAME — This option is a string, and represents the socket name. It can be changed to help with identifying different sockets with their different application-specific purposes. 🏷️
  • NN_MAXTTL — Maximum number of times a message may traverse devices or proxies. This value, if positive, provides some protection against forwarding loops in device chains.
Note: Not all protocols offer this protection, so care should still be used in configuring device forwarding. lowkey a loop-protection era, but not universally 🌀

The following option is available for NN_REQ sockets using the NN_REQ level:

  • NN_REQ_RESEND_IVL — Request retry interval in milliseconds. If an NN_REQ socket does not receive a reply to a request within this period of time, the socket will automatically resend the request. The default value is 60000 (one minute). ⏱️

The following options are available for NN_SUB sockets using the NN_SUB level:

  • NN_SUB_SUBSCRIBE — Subscription topic, for NN_SUB sockets. This sets a subscription topic. When a message from a publisher arrives, it is compared against all subscriptions. If the first sz bytes of the message are not identical to val, then the message is silently discarded.
Tip: To receive all messages, subscribe to an empty topic (sz equal to zero). the “subscribe to everything” hack, iykyk 🍓
  • NN_SUB_UNSUBSCRIBE — Removes a subscription topic that was earlier established. ✂️

The following option is available for NN_SURVEYOR sockets using the NN_SURVEYOR level:

  • NN_SURVEYOR_DEADLINE — Survey deadline in milliseconds for NN_SURVEYOR sockets. After sending a survey message, the socket will only accept responses from respondents for this long. Any responses arriving after this expires are silently discarded. 📬

In addition, the following transport specific options are offered:

  • NN_IPC_SEC_ATTR — This NN_IPC option is not supported at this time. 💀
  • NN_IPC_OUTBUFSZ — This NN_IPC option is not supported at this time. 💀
  • NN_IPC_INBUFSZE — This NN_IPC option is not supported at this time. 💀
  • NN_TCP_NODELAY — This NN_TCP option is not supported at this time. 💀
  • NN_WS_MSG_TYPE — This NN_WS option is not supported at this time. 💀

🌈 RETURN VALUES 🌈

This function returns zero on success, and -1 on failure. simple, clean, main-character return values 👑

💀 ERRORS 💀

  • EBADF — The socket sock is not an open socket.
  • ENOMEM — Insufficient memory is available.
  • ENOPROTOOPT — The level and/or option is invalid.
  • EINVAL — The option, or the value passed, is invalid.
  • ETERM — The library is shutting down.
  • EACCES — The option cannot be changed.

🔥 SEE ALSO 🔥

nng_socket(5), nn_close(3compat), nn_errno(3compat), nn_getsockopt(3compat), nng_compat(3compat), nng(7)

mwah 💋 — this NN_SETSOCKOPT(3compat) page is from the NNG Reference Manual and dated 2026-01-13, and that’s the whole cute little sign-off bestie 🎀✨

📦 where this page comes from