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                         NNG_TCP_OPTIONS(5)