CURLOPT_*TIMEOUT*: extend and clarify

Closes #11686

diff --git a/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.3 b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.3
index f15197fd17b564ab11a885c2d8f7a72d2d8879a9..5cc580aa6b554e632f9a78d13b016f86702c9c94 100644 (file)
--- a/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.3
+++ b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.3
@@ -33,19 +33,33 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONNECTTIMEOUT, long timeout);
 .fi
 .SH DESCRIPTION
 Pass a long. It should contain the maximum time in seconds that you allow the
-connection phase to the server to take.  This 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
+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
 \fICURLOPT_TIMEOUT(3)\fP option.
 
-In unix-like systems, this might cause signals to be used unless
-\fICURLOPT_NOSIGNAL(3)\fP is set.
+\fICURLOPT_CONNECTTIMEOUT_MS(3)\fP is the same function but set in milliseconds.
 
 If both \fICURLOPT_CONNECTTIMEOUT(3)\fP and \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP
 are set, the value set last will be used.
 
 The "connection phase" is considered complete when the requested TCP, TLS or
 QUIC handshakes are done.
+
+The connection timeout set with \fICURLOPT_CONNECTTIMEOUT(3)\fP is included in
+the general all-covering \fICURLOPT_TIMEOUT(3)\fP.
+
+With \fICURLOPT_CONNECTTIMEOUT(3)\fP set to 3 and \fICURLOPT_TIMEOUT(3)\fP set
+to 5, the operation can never last longer than 5 seconds, and the connection
+phase cannot last longer than 3 seconds.
+
+With \fICURLOPT_CONNECTTIMEOUT(3)\fP set to 4 and \fICURLOPT_TIMEOUT(3)\fP set
+to 2, the operation can never last longer than 2 seconds. 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 \fICURLOPT_NOSIGNAL(3)\fP is set.
 .SH DEFAULT
 300
 .SH PROTOCOLS

diff --git a/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.3 b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.3
index 67ce3ec4939953ad5b2570987430e5f5b6936846..ffe3f66ce7a7fbd8af593aad64a23f1bc58ba6c8 100644 (file)
--- a/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.3
+++ b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.3
@@ -34,19 +34,9 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONNECTTIMEOUT_MS,
 .fi
 .SH DESCRIPTION
 Pass a long. It should contain the maximum time in milliseconds that you allow
-the connection phase to the server to take.  This 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
-\fICURLOPT_TIMEOUT_MS(3)\fP option.
+the connection phase to the server to take.
 
-In unix-like systems, this might cause signals to be used unless
-\fICURLOPT_NOSIGNAL(3)\fP is set.
-
-If both \fICURLOPT_CONNECTTIMEOUT(3)\fP and \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP
-are set, the value set last will be used.
-
-The "connection phase" is considered complete when the requested TCP, TLS or
-QUIC handshakes are done.
+See \fICURLOPT_CONNECTTIMEOUT(3)\fP for details.
 .SH DEFAULT
 300000
 .SH PROTOCOLS

diff --git a/docs/libcurl/opts/CURLOPT_TIMEOUT.3 b/docs/libcurl/opts/CURLOPT_TIMEOUT.3
index ab1dd27076d17bd8b4ca0a906ce8d653441cfe9e..37e84b05907587f649e5f190aa837f1aeb7e6b62 100644 (file)
--- a/docs/libcurl/opts/CURLOPT_TIMEOUT.3
+++ b/docs/libcurl/opts/CURLOPT_TIMEOUT.3
@@ -33,23 +33,34 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TIMEOUT, long timeout);
 .fi
 .SH DESCRIPTION
 Pass a long as parameter containing \fItimeout\fP - the maximum time in
-seconds that you allow the libcurl transfer operation to take. Normally, name
-lookups can take a considerable time and limiting operations risk aborting
-perfectly normal operations. This option may cause libcurl to use the SIGALRM
-signal to timeout system calls.
+seconds that you allow the entire transfer operation to take. The whole thing,
+from start to end. Normally, name lookups can take a considerable time and
+limiting operations risk aborting perfectly normal operations.
 
-In unix-like systems, this might cause signals to be used unless
-\fICURLOPT_NOSIGNAL(3)\fP is set.
+\fICURLOPT_TIMEOUT_MS(3)\fP is the same function but set in milliseconds.
 
 If both \fICURLOPT_TIMEOUT(3)\fP and \fICURLOPT_TIMEOUT_MS(3)\fP are set, the
 value set last will be used.
 
 Since this option puts a hard limit on how long time a request is allowed to
-take, it has limited use in dynamic use cases with varying transfer times. That
-is especially apparent when using the multi interface, which may queue the
-transfer, and that time is included. You are advised to explore
+take, it has limited use in dynamic use cases with varying transfer
+times. That is especially apparent when using the multi interface, which may
+queue the transfer, and that time is included. You are advised to explore
 \fICURLOPT_LOW_SPEED_LIMIT(3)\fP, \fICURLOPT_LOW_SPEED_TIME(3)\fP or using
 \fICURLOPT_PROGRESSFUNCTION(3)\fP to implement your own timeout logic.
+
+The connection timeout set with \fICURLOPT_CONNECTTIMEOUT(3)\fP is included in
+this general all-covering timeout.
+
+With \fICURLOPT_CONNECTTIMEOUT(3)\fP set to 3 and \fICURLOPT_TIMEOUT(3)\fP set
+to 5, the operation can never last longer than 5 seconds.
+
+With \fICURLOPT_CONNECTTIMEOUT(3)\fP set to 4 and \fICURLOPT_TIMEOUT(3)\fP set
+to 2, the operation can never last longer than 2 seconds.
+
+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 \fICURLOPT_NOSIGNAL(3)\fP is set.
 .SH DEFAULT
 Default timeout is 0 (zero) which means it never times out during transfer.
 .SH PROTOCOLS

diff --git a/docs/libcurl/opts/CURLOPT_TIMEOUT_MS.3 b/docs/libcurl/opts/CURLOPT_TIMEOUT_MS.3
index d2087691f84403d036305964f20c6d98612f15d2..3017bd3079d751c9e64e62211ef5a3fe83003380 100644 (file)
--- a/docs/libcurl/opts/CURLOPT_TIMEOUT_MS.3
+++ b/docs/libcurl/opts/CURLOPT_TIMEOUT_MS.3
@@ -33,26 +33,9 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TIMEOUT_MS, long timeout);
 .fi
 .SH DESCRIPTION
 Pass a long as parameter containing \fItimeout\fP - the maximum time in
-milliseconds that you allow the libcurl transfer operation to take. Normally,
-name lookups can take a considerable time and limiting operations to less than
-a few minutes risk aborting perfectly normal operations. This option may cause
-libcurl to use the SIGALRM signal to timeout system calls.
+milliseconds that you allow the libcurl transfer operation to take.
 
-If libcurl is built to use the standard system name resolver, that portion of
-the transfer will still use full-second resolution for timeouts with a minimum
-timeout allowed of one second.
-
-In unix-like systems, this might cause signals to be used unless
-\fICURLOPT_NOSIGNAL(3)\fP is set.
-
-If both \fICURLOPT_TIMEOUT(3)\fP and \fICURLOPT_TIMEOUT_MS(3)\fP are set, the
-value set last will be used.
-
-Since this puts a hard limit for how long time a request is allowed to take,
-it has limited use in dynamic use cases with varying transfer times. You are
-then advised to explore \fICURLOPT_LOW_SPEED_LIMIT(3)\fP,
-\fICURLOPT_LOW_SPEED_TIME(3)\fP or using \fICURLOPT_PROGRESSFUNCTION(3)\fP to
-implement your own timeout logic.
+See \fICURLOPT_TIMEOUT(3)\fP for details.
 .SH DEFAULT
 Default timeout is 0 (zero) which means it never times out during transfer.
 .SH PROTOCOLS