From: Daniel Stenberg Date: Thu, 17 Aug 2023 09:25:22 +0000 (+0200) Subject: CURLOPT_*TIMEOUT*: extend and clarify X-Git-Tag: curl-8_3_0~148 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=dd094ba547d52c61431f15519891d6e3ec185212;p=thirdparty%2Fcurl.git CURLOPT_*TIMEOUT*: extend and clarify Closes #11686 --- diff --git a/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.3 b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.3 index f15197fd17..5cc580aa6b 100644 --- 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 67ce3ec493..ffe3f66ce7 100644 --- 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 ab1dd27076..37e84b0590 100644 --- 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 d2087691f8..3017bd3079 100644 --- 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