From: Daniel Stenberg <daniel@haxx.se>
Date: Fri, 7 Jun 2024 08:44:28 +0000 (+0200)
Subject: CURLOPT_CONNECTTIMEOUT*: clarify, document the milliseond version
X-Git-Tag: curl-8_9_0~276
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=7d934267ab185123e7eaa5e974b61527dbbf14e1;p=thirdparty%2Fcurl.git

CURLOPT_CONNECTTIMEOUT*: clarify, document the milliseond version

Provide an explanation in the CURLOPT_CONNECTTIMEOUT_MS page instead of
just referring to the non-MS version.

Closes #13905
---

diff --git a/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.md b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.md
index f8e51d88e2..bdb4596bfe 100644
--- a/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.md
+++ b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.md
@@ -5,7 +5,6 @@ Title: CURLOPT_CONNECTTIMEOUT
 Section: 3
 Source: libcurl
 See-also:
-  - CURLOPT_CONNECTTIMEOUT_MS (3)
   - CURLOPT_LOW_SPEED_LIMIT (3)
   - CURLOPT_MAX_RECV_SPEED_LARGE (3)
   - CURLOPT_TIMEOUT (3)
@@ -27,22 +26,22 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONNECTTIMEOUT, long timeout);
 
 # DESCRIPTION
 
-Pass a long. It should contain the maximum time in seconds that you allow the
-connection phase to the server to take. This timeout only limits the
-connection phase, it has no impact once it has connected. Set to zero to
-switch to the default built-in connection timeout - 300 seconds. See also the
-CURLOPT_TIMEOUT(3) option.
+Pass a long. It sets the maximum time in seconds that you allow the connection
+phase to take. This timeout only limits the connection phase, it has no impact
+once libcurl has connected. The connection phase includes the name resolve
+(DNS) and all protocol handshakes and negotiations until there is an
+established connection with the remote side.
+
+Set this option to zero to switch to the default built-in connection timeout -
+300 seconds. See also the CURLOPT_TIMEOUT(3) option.
 
 CURLOPT_CONNECTTIMEOUT_MS(3) is the same function but set in milliseconds.
 
 If both CURLOPT_CONNECTTIMEOUT(3) and CURLOPT_CONNECTTIMEOUT_MS(3)
 are set, the value set last is used.
 
-The "connection phase" is considered complete when the requested TCP, TLS or
-QUIC handshakes are done.
-
-The connection timeout set with CURLOPT_CONNECTTIMEOUT(3) is included in
-the general all-covering CURLOPT_TIMEOUT(3).
+The connection timeout is included in the general all-covering
+CURLOPT_TIMEOUT(3):
 
 With CURLOPT_CONNECTTIMEOUT(3) set to 3 and CURLOPT_TIMEOUT(3) set
 to 5, the operation can never last longer than 5 seconds, and the connection
diff --git a/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.md b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.md
index 1c22fd8727..90c44f2665 100644
--- a/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.md
+++ b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.md
@@ -5,9 +5,9 @@ Title: CURLOPT_CONNECTTIMEOUT_MS
 Section: 3
 Source: libcurl
 See-also:
-  - CURLOPT_CONNECTTIMEOUT (3)
   - CURLOPT_LOW_SPEED_LIMIT (3)
-  - CURLOPT_TIMEOUT (3)
+  - CURLOPT_MAX_RECV_SPEED_LARGE (3)
+  - CURLOPT_TIMEOUT_MS (3)
 Protocol:
   - All
 ---
@@ -27,10 +27,34 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONNECTTIMEOUT_MS,
 
 # DESCRIPTION
 
-Pass a long. It should contain the maximum time in milliseconds that you allow
-the connection phase to the server to take.
+Pass a long. It sets the maximum time in milliseconds that you allow the
+connection phase to take. This timeout only limits the connection phase, it
+has no impact once libcurl has connected. The connection phase includes the
+name resolve (DNS) and all protocol handshakes and negotiations until there is
+an established connection with the remote side.
 
-See CURLOPT_CONNECTTIMEOUT(3) for details.
+Set this option to zero to switch to the default built-in connection timeout -
+300 seconds. See also the CURLOPT_TIMEOUT_MS(3) option.
+
+CURLOPT_CONNECTTIMEOUT(3) is the same function but set in seconds.
+
+If both CURLOPT_CONNECTTIMEOUT(3) and CURLOPT_CONNECTTIMEOUT_MS(3) are set,
+the value set last is used.
+
+The connection timeout is included in the general all-covering
+CURLOPT_TIMEOUT_MS(3):
+
+With CURLOPT_CONNECTTIMEOUT_MS(3) set to 3000 and CURLOPT_TIMEOUT_MS(3) set to
+5000, the operation can never last longer than 5000 milliseconds, and the
+connection phase cannot last longer than 3000 milliseconds.
+
+With CURLOPT_CONNECTTIMEOUT_MS(3) set to 4000 and CURLOPT_TIMEOUT_MS(3) set to
+2000, the operation can never last longer than 2000 milliseconds. Including
+the connection phase.
+
+This option may cause libcurl to use the SIGALRM signal to timeout system
+calls on builds not using asynch DNS. In unix-like systems, this might cause
+signals to be used unless CURLOPT_NOSIGNAL(3) is set.
 
 # DEFAULT