NNG_OPTIONS(5)

📦
version 1.12.0 · 4 versions
, in ubuntu stonking

🌸 nng_options — the NNG Reference Manual, §5 🌸

okay bestie, sit down, get comfy, because this is the nng_options page and it's a big one. 💖 This is part 1 of 2, so don't you dare go anywhere.

✨ NAME ✨

nng_options — socket, dialer, listener, and pipe options 🎀

✨ SYNOPSIS ✨

#include <nng/nng.h>

#define NNG_OPT_SOCKNAME      "socket-name"
#define NNG_OPT_RAW           "raw"
#define NNG_OPT_PROTO         "protocol"
#define NNG_OPT_PROTONAME     "protocol-name"
#define NNG_OPT_PEER          "peer"
#define NNG_OPT_PEERNAME      "peer-name"
#define NNG_OPT_RECVBUF       "recv-buffer"
#define NNG_OPT_SENDBUF       "send-buffer"
#define NNG_OPT_RECVFD        "recv-fd"
#define NNG_OPT_SENDFD        "send-fd"
#define NNG_OPT_RECVTIMEO     "recv-timeout"
#define NNG_OPT_SENDTIMEO     "send-timeout"
#define NNG_OPT_LOCADDR       "local-address"
#define NNG_OPT_REMADDR       "remote-address"
#define NNG_OPT_URL           "url"
#define NNG_OPT_MAXTTL        "ttl-max"
#define NNG_OPT_RECVMAXSZ     "recv-size-max"
#define NNG_OPT_RECONNMINT    "reconnect-time-min"
#define NNG_OPT_RECONNMAXT    "reconnect-time-max"
#define NNG_OPT_PEER_GID      "ipc:peer-gid"
#define NNG_OPT_PEER_PID      "ipc:peer-pid"
#define NNG_OPT_PEER_UID      "ipc:peer-uid"
#define NNG_OPT_PEER_ZONEID   "ipc:peer-zoneid"

✨ DESCRIPTION ✨

so this page is literally the master list of all the standard options you can get and set on objects. iconic. 💅

Sockets (that's nng_socket objects) use nng_socket_get() and nng_socket_set() to get and set option values. 🫶

Dialers (nng_dialer objects) use nng_dialer_get() and nng_dialer_set() to get and set option values.

Listeners (nng_listener objects) use nng_listener_get() and nng_listener_set() to get and set option values.

Pipes (nng_pipe objects) can only retrieve option values, using the nng_pipe_get() function. read-only queen. 👑

Other object types may have additional methods to access these options. no gatekeeping, just ~extra routes~.

And heads up — in addition to the options listed here, transports and protocols will generally have some of their own options, which get documented with the transport or protocol. so this page is the main character, but not the only character.

🦋 Generic Options 🦋

In the following list, the name of the option is supplied, along with the data type of the underlying value.

Some options are only meaningful or supported in certain contexts; for example there is no single meaningful address for a socket, since sockets can have multiple dialers and endpoints associated with them. An attempt has been made to include details about such restrictions in the description of the option. (they tried, bestie 😭)

NNG_OPT_LOCADDR

(nng_sockaddr) This read-only option may be used on listeners, dialers and connected pipes, and represents the local address used for communication. NOTE: Not all transports support this option, and some transports may support it on listeners but not dialers. 🙈

When used on a TCP dialer, this option is used to configure the source IP address that will be used when initiating outgoing connections. The specific port number will be ignored, however, and the system will choose a random ephemeral port instead. (the system said "nah, I got this" ✨)

NNG_OPT_RAW

(bool) This read-only option indicates whether the socket is in raw mode. If true, the socket is in raw mode, and if false the socket is in normal mode.

Raw mode sockets generally do not have any protocol-specific semantics applied to them; instead the application is expected to perform such semantics itself. (For example, in normal mode a rep socket would automatically copy message headers from a received message to the corresponding reply, whereas in raw mode this is not done.) See Raw Mode for more details.

Note 💀 This option is deprecated. Use the nng_socket_raw function instead.

NNG_OPT_RECONNMINT

(nng_duration) This is the minimum amount of time (milliseconds) to wait before attempting to establish a connection after a previous attempt has failed. This can be set on a socket, but it can also be overridden on an individual dialer. The option is irrelevant for listeners. (listeners literally don't care, they're just vibing 🌈)

NNG_OPT_RECONNMAXT

(nng_duration) This is the maximum amount of time (milliseconds) to wait before attempting to establish a connection after a previous attempt has failed. If this is non-zero, then the time between successive connection attempts will start at the value of NNG_OPT_RECONNMINT, and grow exponentially, until it reaches this value. If this value is zero, then no exponential back-off between connection attempts is done, and each attempt will wait the time specified by NNG_OPT_RECONNMINT. This can be set on a socket, but it can also be overridden on an individual dialer. The option is irrelevant for listeners.

NNG_OPT_RECVBUF

(int) This is the depth of the socket's receive buffer as a number of messages. Messages received by a transport may be buffered until the application has accepted them for delivery. This value must be an integer between 0 and 8192, inclusive. NOTE: Not all protocols support buffering received messages. For example req can only deal with a single reply at a time. one. at. a. time. 😤

NNG_OPT_RECVFD

(int) This read-only option is used to obtain an integer file descriptor suitable for use with poll() (http://pubs.opengroup.org/onlinepubs/7908799/xsh/poll.html), select() (http://pubs.opengroup.org/onlinepubs/7908799/xsh/select.html), (or on Windows systems WSAPoll() (https://msdn.microsoft.com/en-us/library/windows/desktop/ms741669(v=vs.85).aspx)) and similar functions. This descriptor will be readable when a message is available for receiving on the socket. When no message is ready for receiving, then this file descriptor will not be readable.

Important ⚠️ Applications should never attempt to read or write to the returned file descriptor.
Important ⚠️ This option is incompatible with nng_ctx contexts and should not be used on a socket where they are in use.
Tip ✨ While this option may help applications integrate into existing polling loops, it is more efficient, and often easier, to use the asynchronous I/O objects instead. See nng_aio_alloc().

NNG_OPT_RECVMAXSZ

(size_t) This is the maximum message size that the will be accepted from a remote peer. If a peer attempts to send a message larger than this, then the message will be discarded. If the value of this is zero, then no limit on message sizes is enforced. This option exists to prevent certain kinds of denial-of-service attacks, where a malicious agent can claim to want to send an extraordinarily large message, without sending any data. This option can be set for the socket, but may be overridden for on a per-dialer or per-listener basis.

Important 🔥 Applications on hostile networks should set this to a non-zero value to prevent denial-of-service attacks. (fr fr, protect yourself bestie)
Important ⚠️ This option should be set before any listeners or dialers are added. Ideally this option should be set on specific dialers or listeners; setting it on the socket globally is deprecated behavior, and might not work in a future release, or might only work for endpoints that have not yet been created. (Maximum receive sizes might be negotiated during connection establishment for future transports, which means that the option needs to be set before any connections are established.)
Note 🎀 Some transports may have further message size restrictions.

NNG_OPT_RECVTIMEO

(nng_duration) This is the socket receive timeout in milliseconds. When no message is available for receiving at the socket for this period of time, receive operations will fail with a return value of NNG_ETIMEDOUT. yeah. it'll just time out on you. 😭

NNG_OPT_REMADDR

(nng_sockaddr) This read-only option may be used on dialers and connected pipes, and represents the address of a remote peer. Not all transports support this option.

NNG_OPT_SENDBUF

(int) This is the depth of the socket send buffer as a number of messages. Messages sent by an application may be buffered by the socket until a transport is ready to accept them for delivery. This value must be an integer between 0 and 8192, inclusive.

Note 🍓 Not all protocols support buffering sent messages. For example, req can only have a single request outstanding at a time (per context). again: ONE. 😤 one request. that's it. that's the whole vibe.

NNG_OPT_SENDFD

(int) This read-only option is used to obtain an integer file descriptor suitable for use with poll() (http://pubs.opengroup.org/onlinepubs/7908799/xsh/poll.html), select() (http://pubs.opengroup.org/onlinepubs/7908799/xsh/select.html), (or on Windows systems WSAPoll() (https://msdn.microsoft.com/en-us/library/windows/desktop/ms741669(v=vs.85).aspx)) and similar functions.

This descriptor will be readable when the socket is able to accept a message for sending without blocking. When the socket is no longer able to accept such messages without blocking, the descriptor will not be readable.

Important ⚠️ Applications should never attempt to read or write to the returned file descriptor; use should be limited to polling system calls only.
Important ⚠️ This option is incompatible with nng_ctx contexts and should not be used on a socket where they are in use.
Tip ✨ While this option may help applications integrate into existing polling loops, it is more efficient, and often easier, to use the asynchronous I/O objects instead. See nng_aio_alloc().

NNG_OPT_SENDTIMEO

(nng_duration) This is the socket send timeout in milliseconds. When a message cannot be queued for delivery by the socket for this period of time (such as if send buffers are full), the operation will fail with a return value of NNG_ETIMEDOUT.

NNG_OPT_SOCKNAME

(string) This the socket name. By default, this is a string corresponding to the value of the socket. The string must fit within 64-bytes, including the terminating NUL byte. The value is intended for application use, and is not used for anything in the library itself. (it's just a name. a little name. a little guy. 🥺)

NNG_OPT_MAXTTL

(int)

This is the maximum number of times a message may traverse across a nng_device() forwarders. The intention here is to prevent forwarding loops in device chains. When this is supported, it can have a value between 1 and 255, inclusive. 🌈

…and that's only part 1, bestie — there's so much more coming in part 2 💅

a lil note, bestie 💅 — not every protocol supports this option, okay? The ones that do generally ship with a default value of 8.

and a tip ✨ — every single node along a forwarding path may have its own value for the maximum time-to-live, and each node runs its own checks before forwarding a message. So it's genuinely helpful if, like, all the nodes in your topology use the same value for this option. Matching fits = main character energy, fr fr.

  • NNG_OPT_URL — (string) this read-only cutie is how you get the URL that a listener or dialer was configured with. Which means it can only be used with dialers, listeners, and pipes. periodt.
    • heads up tho 🌸 — some transports will canonify URLs before handing them back to your application, so don't be gagged if the string isn't character-for-character what you typed.
  • NNG_OPT_PROTO — (int) read-only, and it grabs the 16-bit number for the socket's protocol. iconic, but...
💀 deprecated, bestie. Use the nng_socket_proto_id function instead.
  • NNG_OPT_PEER — (int) read-only, gives you the 16-bit number of the peer protocol for the socket.
💀 deprecated too. Use the nng_socket_peer_id function instead.
  • NNG_OPT_PEER_GID — (uint64_t) read-only, and it serves up a connected peer's primary group id, when it's known. This is the effective group id of the peer at the moment either the underlying listen() or connect() calls were made, and it is not forgeable 🔒. Lowkey only available on POSIX systems, and only on certain transports.
  • NNG_OPT_PEER_PID — (uint64_t) read-only, this one hands you the process id of the connected peer, when known. Only available on certain platforms and transports.
⚠️ do NOT assume the process ID never changes, because it may be possible for a process to pass a file descriptor between processes. However — and this is the slay part — it is not possible for a nefarious application to forge the identity of a well-behaved one using this method. 🛡️
  • NNG_OPT_PEER_UID — (uint64_t) read-only, providing a connected peer's user id. Same deal: this is the effective user id of the peer when either the underlying listen() or connect() calls were made, and it cannot be forged 🔐. Generally only available on POSIX systems, on certain transports.
  • NNG_OPT_PEER_ZONEID — (uint64_t) read-only, providing a connected peer's zone id. Zones (and therefore this option) are only supported on Solaris and illumos systems, on select transports. niche but valid 💜
  • NNG_OPT_PEERNAME — (string) read-only, used to obtain the name of the peer protocol for the socket.
💀 deprecated, sadly. Use the nng_socket_peer_name function instead.
  • NNG_OPT_PROTONAME — (string) read-only, used to obtain the name of the socket's protocol.
💀 also deprecated. Use the nng_socket_proto_name function instead.

🫶 SEE ALSO 🫶

go read these next, they're the whole friend group, no cap:

that's the whole page bestie, u made it 🌈✨ this is NNG_OPTIONS(5), dated 2026-06-30, from the NNG manual set. go forth and set your options, ily, bye 💖🦋🎀

📦 where this page comes from