tcpkeepalive: add CURLOPT_TCP_KEEPCNT and --keepalive-cnt

Closes #13885

docs/cmdline-opts/Makefile.inc

@@ -142,6 +142,7 @@ DPAGES = \
   ipv6.md \
   json.md \
   junk-session-cookies.md \
+  keepalive-cnt.md \
   keepalive-time.md \
   key-type.md \
   key.md \

docs/cmdline-opts/keepalive-cnt.md

@@ -0,0 +1,27 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Long: keepalive-cnt
+Arg: <integer>
+Help: Maximum number of keepalive probes
+Added: 8.9.0
+Category: connection
+Multi: single
+See-also:
+  - keepalive-time
+  - no-keepalive
+Example:
+  - --keepalive-cnt 3 $URL
+---
+
+# `--keepalive-cnt`
+
+Set the maximum number of keepalive probes TCP should send but get no response
+before dropping the connection. This option is usually used in conjunction
+with --keepalive-time.
+
+This option is supported on Linux, *BSD/macOS, Windows \>=10.0.16299, Solaris
+11.4, and recent AIX, HP-UX and more. This option has no effect if
+--no-keepalive is used.
+
+If unspecified, the option defaults to 9.

docs/cmdline-opts/keepalive-time.md

@@ -9,6 +9,7 @@ Category: connection
 Multi: single
 See-also:
   - no-keepalive
+  - keepalive-cnt
   - max-time
 Example:
   - --keepalive-time 20 $URL
@@ -22,7 +23,8 @@ operating systems offering the `TCP_KEEPIDLE` and `TCP_KEEPINTVL` socket
 options (meaning Linux, *BSD/macOS, Windows, Solaris, and recent AIX, HP-UX and more).
 Keepalive is used by the TCP stack to detect broken networks on idle connections.
 The number of missed keepalive probes before declaring the connection down is OS
-dependent and is commonly 8 (*BSD/macOS/AIX), 9 (Linux/AIX) or 5/10 (Windows).
-This option has no effect if --no-keepalive is used.
+dependent and is commonly 8 (*BSD/macOS/AIX), 9 (Linux/AIX) or 5/10 (Windows), and
+this number can be changed by specifying the curl option `keepalive-cnt`.
+Note that this option has no effect if --no-keepalive is used.
 
 If unspecified, the option defaults to 60 seconds.

docs/cmdline-opts/no-keepalive.md

@@ -8,6 +8,7 @@ Added: 7.18.0
 Multi: boolean
 See-also:
   - keepalive-time
+  - keepalive-cnt
 Example:
   - --no-keepalive $URL
 ---

docs/examples/keepalive.c

@@ -44,6 +44,9 @@ int main(void)
     /* interval time between keep-alive probes: 60 seconds */
     curl_easy_setopt(curl, CURLOPT_TCP_KEEPINTVL, 60L);
 
+    /* maximum number of keep-alive probes: 3 */
+    curl_easy_setopt(curl, CURLOPT_TCP_KEEPCNT, 3L);
+
     curl_easy_setopt(curl, CURLOPT_URL, "https://curl.se/");
 
     res = curl_easy_perform(curl);

docs/libcurl/curl_easy_setopt.md

@@ -417,6 +417,10 @@ Idle time before sending keep-alive. See CURLOPT_TCP_KEEPIDLE(3)
 
 Interval between keep-alive probes. See CURLOPT_TCP_KEEPINTVL(3)
 
+## CURLOPT_TCP_KEEPCNT
+
+Maximum number of keep-alive probes. See CURLOPT_TCP_KEEPCNT(3)
+
 ## CURLOPT_UNIX_SOCKET_PATH
 
 Path to a Unix domain socket. See CURLOPT_UNIX_SOCKET_PATH(3)

docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.md

@@ -9,8 +9,9 @@ See-also:
   - CURLOPT_MAX_RECV_SPEED_LARGE (3)
   - CURLOPT_TCP_KEEPIDLE (3)
   - CURLOPT_TCP_KEEPINTVL (3)
+  - CURLOPT_TCP_KEEPCNT (3)
 Protocol:
-  - All
+  - TCP
 ---
 
 # NAME
@@ -29,9 +30,9 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_KEEPALIVE, long probe);
 
 Pass a long. If set to 1, TCP keepalive probes are used. The delay and
 frequency of these probes can be controlled by the
-CURLOPT_TCP_KEEPIDLE(3) and CURLOPT_TCP_KEEPINTVL(3) options,
-provided the operating system supports them. Set to 0 (default behavior) to
-disable keepalive probes
+CURLOPT_TCP_KEEPIDLE(3), CURLOPT_TCP_KEEPINTVL(3), and CURLOPT_TCP_KEEPCNT(3)
+options, provided the operating system supports them. Set to 0 (default behavior)
+to disable keepalive probes.
 
 # DEFAULT
 
@@ -55,6 +56,9 @@ int main(void)
     /* interval time between keep-alive probes: 60 seconds */
     curl_easy_setopt(curl, CURLOPT_TCP_KEEPINTVL, 60L);
 
+    /* maximum number of keep-alive probes: 3 */
+    curl_easy_setopt(curl, CURLOPT_TCP_KEEPCNT, 3L);
+
     curl_easy_perform(curl);
   }
 }

docs/libcurl/opts/CURLOPT_TCP_KEEPCNT.md

@@ -0,0 +1,73 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: CURLOPT_TCP_KEEPCNT
+Section: 3
+Source: libcurl
+See-also:
+  - CURLOPT_TCP_KEEPALIVE (3)
+  - CURLOPT_TCP_KEEPIDLE (3)
+  - CURLOPT_TCP_KEEPINTVL (3)
+Protocol:
+  - TCP
+---
+
+# NAME
+
+CURLOPT_TCP_KEEPCNT - Maximum number of TCP keep-alive probes
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_KEEPCNT, long cnt);
+~~~
+
+# DESCRIPTION
+
+Pass a long. Sets the number of probes to send before dropping
+the connection. Not all operating systems support this option.
+(Added in 8.9.0)
+
+The maximum value this option accepts is INT_MAX or whatever your
+system allows.
+Any larger value is capped to this amount.
+
+# DEFAULT
+
+9
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  CURL *curl = curl_easy_init();
+  if(curl) {
+    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
+
+    /* enable TCP keep-alive for this transfer */
+    curl_easy_setopt(curl, CURLOPT_TCP_KEEPALIVE, 1L);
+
+    /* set keep-alive idle time to 120 seconds */
+    curl_easy_setopt(curl, CURLOPT_TCP_KEEPIDLE, 120L);
+
+    /* interval time between keep-alive probes: 60 seconds */
+    curl_easy_setopt(curl, CURLOPT_TCP_KEEPINTVL, 60L);
+
+    /* maximum number of keep-alive probes: 3 */
+    curl_easy_setopt(curl, CURLOPT_TCP_KEEPCNT, 3L);
+
+    curl_easy_perform(curl);
+  }
+}
+~~~
+
+# AVAILABILITY
+
+Added in v8.9.0
+
+# RETURN VALUE
+
+Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.

docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.md

@@ -7,8 +7,9 @@ Source: libcurl
 See-also:
   - CURLOPT_TCP_KEEPALIVE (3)
   - CURLOPT_TCP_KEEPINTVL (3)
+  - CURLOPT_TCP_KEEPCNT (3)
 Protocol:
-  - All
+  - TCP
 ---
 
 # NAME
@@ -54,6 +55,9 @@ int main(void)
     /* interval time between keep-alive probes: 60 seconds */
     curl_easy_setopt(curl, CURLOPT_TCP_KEEPINTVL, 60L);
 
+    /* maximum number of keep-alive probes: 3 */
+    curl_easy_setopt(curl, CURLOPT_TCP_KEEPCNT, 3L);
+
     curl_easy_perform(curl);
   }
 }

docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.md

@@ -7,8 +7,9 @@ Source: libcurl
 See-also:
   - CURLOPT_TCP_KEEPALIVE (3)
   - CURLOPT_TCP_KEEPIDLE (3)
+  - CURLOPT_TCP_KEEPCNT (3)
 Protocol:
-  - All
+  - TCP
 ---
 
 # NAME
@@ -53,6 +54,9 @@ int main(void)
     /* interval time between keep-alive probes: 60 seconds */
     curl_easy_setopt(curl, CURLOPT_TCP_KEEPINTVL, 60L);
 
+    /* maximum number of keep-alive probes: 3 */
+    curl_easy_setopt(curl, CURLOPT_TCP_KEEPCNT, 3L);
+
     curl_easy_perform(curl);
   }
 }

docs/libcurl/opts/CURLOPT_TCP_NODELAY.md

@@ -9,7 +9,7 @@ See-also:
   - CURLOPT_SOCKOPTFUNCTION (3)
   - CURLOPT_TCP_KEEPALIVE (3)
 Protocol:
-  - All
+  - TCP
 ---
 
 # NAME

docs/libcurl/opts/Makefile.inc

@@ -384,6 +384,7 @@ man_MANS =                                      \
   CURLOPT_TCP_KEEPALIVE.3                       \
   CURLOPT_TCP_KEEPIDLE.3                        \
   CURLOPT_TCP_KEEPINTVL.3                       \
+  CURLOPT_TCP_KEEPCNT.3                         \
   CURLOPT_TCP_NODELAY.3                         \
   CURLOPT_TELNETOPTIONS.3                       \
   CURLOPT_TFTP_BLKSIZE.3                        \

docs/libcurl/symbols-in-versions

@@ -864,6 +864,7 @@ CURLOPT_TCP_FASTOPEN            7.49.0
 CURLOPT_TCP_KEEPALIVE           7.25.0
 CURLOPT_TCP_KEEPIDLE            7.25.0
 CURLOPT_TCP_KEEPINTVL           7.25.0
+CURLOPT_TCP_KEEPCNT             8.9.0
 CURLOPT_TCP_NODELAY             7.11.2
 CURLOPT_TELNETOPTIONS           7.7
 CURLOPT_TFTP_BLKSIZE            7.19.4

docs/options-in-versions

@@ -107,6 +107,7 @@
 --ipv6 (-6)                          7.10.8
 --json                               7.82.0
 --junk-session-cookies (-j)          7.9.7
+--keepalive-cnt                      8.9.0
 --keepalive-time                     7.18.0
 --key                                7.9.3
 --key-type                           7.9.3