Scroll to navigation

NNG_TCP_OPTIONS(5) NNG Reference Manual NNG_TCP_OPTIONS(5)

NAME

nng_tcp_options - TCP-specific options

SYNOPSIS

#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

(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

(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

(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:

•NNG_OPT_LOCADDR

•NNG_OPT_REMADDR

SEE ALSO

nng_tcp_dialer_getopt(3tcp), nng_tcp_dialer_setopt(3tcp), nng_tcp_getopt(3tcp), nng_tcp_listener_getopt(3tcp), nng_tcp_listener_setopt(3tcp), nng_tcp_setopt(3tcp), nng_options(5) nng(7)

2024-10-11