docs/libcurl: clarify some timeout option behavior

Closes #18569

diff --git a/docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.md b/docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.md
index 8fdbc96632475a638acea778d6396ca47fe54218..5dd19a708b137069276b4f3892c7d014189b4cd4 100644 (file)
--- 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 c5eee3c0ac73c083a894944de8881e9f4291e851..59e4419512c5c5050ead3b192f2f9db7ba97629c 100644 (file)
--- 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 3d6ba1f9aad468e6a3eda42dda98aab99949705f..30ae25b42ac58cb4c0c98f330c7d9cdbe82abc15 100644 (file)
--- 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 7acbd105ec879bd450295fb5c594731391417494..267659cde2dbfd6e53d5cdddc7ad5279581e3289 100644 (file)
--- 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).