= nng_tcp_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_tcp_options - TCP-specific options

== SYNOPSIS

[source, c]
----
#include <nng/nng.h>

#define NNG_OPT_TCP_NODELAY    "tcp-nodelay"
#define NNG_OPT_TCP_KEEPALIVE  "tcp-keepalive"
#define NNG_OPT_TCP_BOUND_PORT "tcp-bound-port"
----

== DESCRIPTION

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

The option names should always be used by their symbolic definitions.

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, or may
have other access restrictions.
An attempt has been made to include details about such restrictions in the
description of the option.

The following options are generally application to objects making use of
TCP/IP communications.

=== TCP Options

[[NNG_OPT_TCP_NODELAY]]
((`NNG_OPT_TCP_NODELAY`))::
(`bool`)
This option is used to disable (or enable) the use of ((Nagle's algorithm))
for TCP connections.
+
NOTE: This setting may apply to transports that are built on top of TCP.
See the transport documentation for each transport for details.
+
When `true` (the default), messages are sent immediately by the underlying
TCP stream without waiting to gather more data.
+
When `false`, Nagle's algorithm is enabled, and the TCP stream may
wait briefly in attempt to coalesce messages.
Nagle's algorithm is useful on low-bandwidth connections to reduce overhead,
but it comes at a cost to latency.
+
When used on a dialer or a listener, the value affects how newly
created connections will be configured.

[[NNG_OPT_TCP_KEEPALIVE]]
((`NNG_OPT_TCP_KEEPALIVE`))::
(`bool`)
This option is used to enable the sending of keep-alive messages on
the underlying TCP stream.
This option is `false` by default.
+
NOTE: This setting may apply to transports that are built on top of TCP.
See the transport documentation for each transport for details.
+
When enabled, if no messages are seen for a period of time, then
a zero length TCP message is sent with the ACK flag set in an attempt
to tickle some traffic from the peer.
If none is still seen (after some platform-specific number of retries and
timeouts), then the remote peer is presumed dead, and the connection is closed.
+
When used on a dialer or a listener, the value affects how newly
created connections will be configured.
+
TIP: This option has two purposes.
First, it can be used to detect dead peers on an otherwise quiescent network.
Second, it can be used to keep connection table entries in NAT and other
middleware from being expiring due to lack of activity.

[[NNG_OPT_TCP_BOUND_PORT]]
((`NNG_OPT_TCP_BOUND_PORT`))::
(`int`)
This option is available on listeners, after the listern has bound to
a port, and provides the port bound to in native byte order.
This is most useful when using a listener with an ephemeral port
(configured by using port 0 at configuration time), as it allows
the caller to determine the actual ephemeral port that was chosen by the
system.
While the value is of type `int`, it will be a legal TCP port number, that
is a value between 1 and 65535, inclusive.

[[NNG_OPT_LISTEN_FD]]
((`NNG_OPT_LISTEN_FD`)):
(`int`)
This option is a write-only option for listeners, that can be used on a
listener that has not yet been started.  It is used to pass in a file descriptor
(or for Windows, a `SOCKET`) that has already been set up for listening.
The intended use for this is with configurations such as socket activation,
where some system service pre-establishes the listening sockets before starting
the application.

=== Inherited Options

Generally, the following option values are also available for TCP objects,
when appropriate for the context:

* xref:nng_options.5.adoc#NNG_OPT_LOCADDR[`NNG_OPT_LOCADDR`]
* xref:nng_options.5.adoc#NNG_OPT_REMADDR[`NNG_OPT_REMADDR`]

== SEE ALSO

[.text-left]
xref:nng_options.5.adoc[nng_options(5)]
xref:nng.7.adoc[nng(7)]
