From cdb56c6666e79fff211d91ee88b0c0e9a5a0dd23 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 16 Sep 2025 16:30:08 +0200 Subject: [PATCH] docs/libcurl: clarify some timeout option behavior Closes #18569 --- docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.md | 9 +++++++-- docs/libcurl/opts/CURLOPT_FTPPORT.md | 1 + .../libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT.md | 13 ++++++------- .../opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.md | 10 +++++----- 4 files changed, 19 insertions(+), 14 deletions(-) diff --git a/docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.md b/docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.md index 8fdbc96632..5dd19a708b 100644 --- a/docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.md +++ b/docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.md @@ -8,6 +8,7 @@ See-also: - CURLOPT_CONNECTTIMEOUT_MS (3) - CURLOPT_DEBUGFUNCTION (3) - CURLOPT_STDERR (3) + - CURLOPT_FTPPORT (3) Protocol: - FTP Added-in: 7.24.0 @@ -28,7 +29,11 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ACCEPTTIMEOUT_MS, long ms); # DESCRIPTION Pass a long telling libcurl the maximum number of milliseconds to wait for a -server to connect back to libcurl when an active FTP connection is used. +server to connect back to libcurl when an active FTP connection is used. When +active FTP is used, the client (libcurl) tells the server to do a TCP connect +back to the client, instead of vice versa for passive FTP. + +This option has no purpose for passive FTP. # DEFAULT @@ -45,7 +50,7 @@ int main(void) if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/path/file"); - /* wait no more than 5 seconds for FTP server responses */ + /* wait no more than 5 seconds for the FTP server to connect */ curl_easy_setopt(curl, CURLOPT_ACCEPTTIMEOUT_MS, 5000L); curl_easy_perform(curl); diff --git a/docs/libcurl/opts/CURLOPT_FTPPORT.md b/docs/libcurl/opts/CURLOPT_FTPPORT.md index c5eee3c0ac..59e4419512 100644 --- a/docs/libcurl/opts/CURLOPT_FTPPORT.md +++ b/docs/libcurl/opts/CURLOPT_FTPPORT.md @@ -9,6 +9,7 @@ Protocol: See-also: - CURLOPT_FTP_USE_EPRT (3) - CURLOPT_FTP_USE_EPSV (3) + - CURLOPT_ACCEPTTIMEOUT_MS (3) Added-in: 7.1 --- diff --git a/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT.md b/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT.md index 3d6ba1f9aa..30ae25b42a 100644 --- a/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT.md +++ b/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT.md @@ -33,13 +33,12 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SERVER_RESPONSE_TIMEOUT, # DESCRIPTION -Pass a long. Causes libcurl to set a *timeout* period (in seconds) on the -amount of time that the server is allowed to take in order to send a response -message for a command before the session is considered dead. While libcurl is -waiting for a response, this value overrides CURLOPT_TIMEOUT(3). It is -recommended that if used in conjunction with CURLOPT_TIMEOUT(3), you set -CURLOPT_SERVER_RESPONSE_TIMEOUT(3) to a value smaller than -CURLOPT_TIMEOUT(3). +Pass a long. It tells libcurl to wait no longer than *timeout* seconds for +responses on sent commands. If no response is received within this period, the +connection is considered dead and the transfer fails. + +It is recommended that if used in conjunction with CURLOPT_TIMEOUT(3), you set +CURLOPT_SERVER_RESPONSE_TIMEOUT(3) to a value smaller than CURLOPT_TIMEOUT(3). This option was formerly known as CURLOPT_FTP_RESPONSE_TIMEOUT. diff --git a/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.md b/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.md index 7acbd105ec..267659cde2 100644 --- a/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.md +++ b/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.md @@ -33,11 +33,11 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SERVER_RESPONSE_TIMEOUT_MS, # DESCRIPTION -Pass a long. Causes libcurl to set a *timeout* period (in milliseconds) on the -amount of time that the server is allowed to take in order to send a response -message for a command before the session is considered dead. While libcurl is -waiting for a response, this value overrides CURLOPT_TIMEOUT(3). It is -recommended that if used in conjunction with CURLOPT_TIMEOUT(3), you set +Pass a long. It tells libcurl to wait no longer than *timeout* milliseconds +for responses on sent commands. If no response is received within this period, +the connection is considered dead and the transfer fails. + +It is recommended that if used in conjunction with CURLOPT_TIMEOUT(3), you set CURLOPT_SERVER_RESPONSE_TIMEOUT_MS(3) to a value smaller than CURLOPT_TIMEOUT(3). -- 2.47.3