oxmox
7063e2102e
git-subtree-dir: external/nng git-subtree-split: 29b73962b939a6fbbf6ea8d5d7680bb06d0eeb99
122 lines
4.3 KiB
Text
122 lines
4.3 KiB
Text
= 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.
|
|
|
|
=== 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_tcp_dialer_getopt.3tcp.adoc[nng_tcp_dialer_getopt(3tcp)],
|
|
xref:nng_tcp_dialer_setopt.3tcp.adoc[nng_tcp_dialer_setopt(3tcp)],
|
|
xref:nng_tcp_getopt.3tcp.adoc[nng_tcp_getopt(3tcp)],
|
|
xref:nng_tcp_listener_getopt.3tcp.adoc[nng_tcp_listener_getopt(3tcp)],
|
|
xref:nng_tcp_listener_setopt.3tcp.adoc[nng_tcp_listener_setopt(3tcp)],
|
|
xref:nng_tcp_setopt.3tcp.adoc[nng_tcp_setopt(3tcp)],
|
|
xref:nng_options.5.adoc[nng_options(5)]
|
|
xref:nng.7.adoc[nng(7)]
|