= nng_options(5)
//
// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
// Copyright 2018 Capitar IT Group BV <info@capitar.com>
// Copyright 2019 Devolutions <info@devolutions.net>
//
// This document is supplied under the terms of the MIT License, a
// copy of which should be located in the distribution where this
// file was obtained (LICENSE.txt).  A copy of the license may also be
// found online at https://opensource.org/licenses/MIT.
//

== NAME

nng_options - socket, dialer, listener, and pipe options

== SYNOPSIS

[source, c]
----
#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"
----

== DESCRIPTION

This page documents the various standard options that can be set or
retrieved on objects.

Sockets (xref:nng_socket.5.adoc[`nng_socket`] objects) use the functions
xref:nng_getopt.3.adoc[`nng_getopt()`]
and xref:nng_setopt.3.adoc[`nng_setopt()`] to set and retrieve option values.

Dialers (xref:nng_dialer.5.adoc[`nng_dialer`] objects) use the functions
xref:nng_dialer_getopt.3.adoc[`nng_dialer_getopt()`] and
xref:nng_dialer_setopt.3.adoc[`nng_dialer_setopt()`] to set and retrieve option
values.

Listeners (xref:nng_listener.5.adoc[`nng_listener`] objects) use the functions
xref:nng_listener_getopt.3.adoc[`nng_listener_getopt()`]
and xref:nng_listener_setopt.3.adoc[`nng_listener_setopt()`] to set and
retrieve option values.

Pipes (xref:nng_pipe.5.adoc[`nng_pipe`] objects) can only retrieve option values using
the xref:nng_pipe_getopt.3.adoc[`nng_pipe_getopt()`] function.

Other object types may have additional methods to access these options.

In addition to the options listed here, transports and protocols will generally
have some of their own options, which will be documented with the transport
or protocol.

=== Generic Options

In the following list of options, 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.

[[NNG_OPT_LOCADDR]]
((`NNG_OPT_LOCADDR`))::
(xref:nng_sockaddr.5.adoc[`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.

[[NNG_OPT_RAW]]
((`NNG_OPT_RAW`))::
(((raw mode)))
(((cooked mode)))
(`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 xref:nng_rep.7.adoc[_rep_] socket would
automatically copy message headers from a received message to the corresponding
reply, whereas in raw mode this is not done.)
See xref:nng.7.adoc#raw_mode[Raw Mode] for more details.

[[NNG_OPT_RECONNMINT]]
((`NNG_OPT_RECONNMINT`))::
(((reconnect time, minimum)))
(xref:nng_duration.5.adoc[`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.

[[NNG_OPT_RECONNMAXT]]
((`NNG_OPT_RECONNMAXT`))::
(((`NNG_OPT_RECONNMAXT`)))
(((reconnect time, maximum)))
(xref:nng_duration.5.adoc[`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]]
((`NNG_OPT_RECVBUF`))::
(((buffer, receive)))
(((receive, buffer)))
(`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 xref:nng_req.7.adoc[_req_] can only deal with a single reply at a time.

[[NNG_OPT_RECVFD]]
((`NNG_OPT_RECVFD`))::
(((poll)))
(((select)))
(((receive, polling)))
(`int`)
This read-only option is used to obtain an integer file descriptor suitable
for use with
http://pubs.opengroup.org/onlinepubs/7908799/xsh/poll.html[`poll()`],
http://pubs.opengroup.org/onlinepubs/7908799/xsh/select.html[`select()`],
(or on Windows systems
https://msdn.microsoft.com/en-us/library/windows/desktop/ms741669(v=vs.85).aspx[`WSAPoll()`])
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
xref:nng_ctx.5.adoc[`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 xref:nng_aio_alloc.3.adoc[`nng_aio_alloc()`].

[[NNG_OPT_RECVMAXSZ]]
((`NNG_OPT_RECVMAXSZ`))::
(((receive, maximum size)))
(`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.
+
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_OPT_RECVTIMEO`))::
(((receive, timeout)))
(((timeout, receive)))
(xref:nng_duration.5.adoc[`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`.

[[NNG_OPT_REMADDR]]
((`NNG_OPT_REMADDR`))::
(xref:nng_sockaddr.5.adoc[`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]]
((`NNG_OPT_SENDBUF`))::
(((send, buffer)))
(((buffer, send)))
(`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;
generally multicast protocols like xref:nng_pub.7.adoc[_pub_] will
simply discard messages when they cannot be delivered immediately.

[[NNG_OPT_SENDFD]]
((`NNG_OPT_SENDFD`))::
(((poll)))
(((select)))
(((send, polling)))
(`int`)
This read-only option is used to obtain an integer file descriptor suitable
for use with
http://pubs.opengroup.org/onlinepubs/7908799/xsh/poll.html[`poll()`],
http://pubs.opengroup.org/onlinepubs/7908799/xsh/select.html[`select()`],
(or on Windows systems
https://msdn.microsoft.com/en-us/library/windows/desktop/ms741669(v=vs.85).aspx[`WSAPoll()`])
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
xref:nng_ctx.5.adoc[`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 xref:nng_aio_alloc.3.adoc[`nng_aio_alloc()`].

[[NNG_OPT_SENDTIMEO]]
((`NNG_OPT_SENDTIMEO`))::
(((send, timeout)))
(((timeout, send)))
(xref:nng_duration.5.adoc[`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]]
((`NNG_OPT_SOCKNAME`))::
(((name, socket)))
(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.

[[NNG_OPT_MAXTTL]]
((`NNG_OPT_MAXTTL`))::
(`int`)
(((time-to-live)))
This is the maximum number of times a message may traverse across
a xref:nng_device.3.adoc[`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.
+
NOTE: Not all protocols support this option.
Those that do generally have a default value of 8.
+
TIP: Each node along a forwarding path may have its own value for the
maximum time-to-live, and performs its own checks before forwarding a message.
Therefore it is helpful if all nodes in the topology use the same value for
this option.

[[NNG_OPT_URL]]
((`NNG_OPT_URL`))::
(((URI)))
(((URL)))
(string)
This read-only option is used to obtain the URL with which a listener
or dialer was configured.
Accordingly it can only be used with dialers, listeners, and pipes.
+
NOTE: Some transports will canonify URLs before returning them to the
application.

[[NNG_OPT_PROTO]]
((`NNG_OPT_PROTO`))::
(`int`)
This read-only option is used to obtain the 16-bit number for the socket's protocol.

[[NNG_OPT_PEER]]
((`NNG_OPT_PEER`))::
(`int`)
This read-only option is used to obtain the 16-bit number of the
peer protocol for the socket.

[[NNG_OPT_PROTONAME]]
((`NNG_OPT_PROTONAME`))::
(string)
This read-only option is used to obtain the name of the socket's protocol.

[[NNG_OPT_PEERNAME]]
((`NNG_OPT_PEERNAME`))::
(string)
This read-only option is used to obtain the name of the peer protocol for
the socket.

== SEE ALSO

[.text-left]
xref:nng_dialer_getopt.3.adoc[nng_dialer_getopt(3)],
xref:nng_dialer_setopt.3.adoc[nng_dialer_setopt(3)],
xref:nng_getopt.3.adoc[nng_getopt(3)],
xref:nng_listener_getopt.3.adoc[nng_listener_getopt(3)],
xref:nng_listener_setopt.3.adoc[nng_listener_setopt(3)],
xref:nng_pipe_getopt.3.adoc[nng_pipe_getopt(3)],
xref:nng_setopt.3.adoc[nng_setopt(3)],
xref:nng_ipc_options.5.adoc[nng_ipc_options(5)],
xref:nng_tcp_options.5.adoc[nng_tcp_options(5)],
xref:nng_tls_options.5.adoc[nng_tls_options(5)],
xref:nng.7.adoc[nng(7)]