CURLOPT_IPRESOLVE: preventing wrong IP version from being used

In some situations, it was possible that a transfer was setup to
use an specific IP version, but due do DNS caching or connection
reuse, it ended up using a different IP version from requested.

This commit changes the effect of CURLOPT_IPRESOLVE from simply
restricting address resolution to preventing the wrong connection
type being used, when choosing a connection from the pool, and
to restricting what addresses could be used when establishing
a new connection.

It is important that all addresses versions are resolved, even if
not used in that transfer in particular, because the result is
cached, and could be useful for a different transfer with a
different CURLOPT_IPRESOLVE setting.

Closes #6853

3 files changed, 10 insertions, 9 deletions

diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3
index 0c4f9b7ca..ecba0d5d4 100644
--- a/docs/libcurl/curl_easy_setopt.3
+++ b/docs/libcurl/curl_easy_setopt.3
@@ -494,7 +494,7 @@ Timeout for the connection phase. See \fICURLOPT_CONNECTTIMEOUT(3)\fP
 .IP CURLOPT_CONNECTTIMEOUT_MS
 Millisecond timeout for the connection phase. See \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP
 .IP CURLOPT_IPRESOLVE
-IP version to resolve to. See \fICURLOPT_IPRESOLVE(3)\fP
+IP version to use. See \fICURLOPT_IPRESOLVE(3)\fP
 .IP CURLOPT_CONNECT_ONLY
 Only connect, nothing else. See \fICURLOPT_CONNECT_ONLY(3)\fP
 .IP CURLOPT_USE_SSL
diff --git a/docs/libcurl/opts/CURLOPT_IPRESOLVE.3 b/docs/libcurl/opts/CURLOPT_IPRESOLVE.3
index 4bdd8b2fe..6d534da9e 100644
--- a/docs/libcurl/opts/CURLOPT_IPRESOLVE.3
+++ b/docs/libcurl/opts/CURLOPT_IPRESOLVE.3
@@ -29,14 +29,15 @@ CURLOPT_IPRESOLVE \- specify which IP protocol version to use
 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_IPRESOLVE, long resolve);
 .SH DESCRIPTION
 Allows an application to select what kind of IP addresses to use when
-resolving host names. This is only interesting when using host names that
-resolve addresses using more than one version of IP. The allowed values are:
+establishing a connection or choosing one from the connection pool. This is
+interesting when using host names that resolve addresses using more than
+one version of IP. The allowed values are:
 .IP CURL_IPRESOLVE_WHATEVER
-Default, resolves addresses to all IP versions that your system allows.
+Default, can use addresses of all IP versions that your system allows.
 .IP CURL_IPRESOLVE_V4
-Resolve to IPv4 addresses.
+Uses only IPv4 addresses.
 .IP CURL_IPRESOLVE_V6
-Resolve to IPv6 addresses.
+Uses only IPv6 addresses.
 .SH DEFAULT
 CURL_IPRESOLVE_WHATEVER
 .SH PROTOCOLS
@@ -47,7 +48,7 @@ CURL *curl = curl_easy_init();
 if(curl) {
   curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
 
-  /* resolve host name using IPv6-names only */
+  /* of all addresses example.com resolves to, only IPv6 ones are used */
   curl_easy_setopt(curl, CURLOPT_IPRESOLVE, CURL_IPRESOLVE_V6);
 
   ret = curl_easy_perform(curl);
diff --git a/docs/libcurl/opts/CURLOPT_RESOLVE.3 b/docs/libcurl/opts/CURLOPT_RESOLVE.3
index 20ee69b0c..57a5401e4 100644
--- a/docs/libcurl/opts/CURLOPT_RESOLVE.3
+++ b/docs/libcurl/opts/CURLOPT_RESOLVE.3
@@ -57,8 +57,8 @@ this entry will be removed and a new entry will be created. This is because
 the old entry may have have different addresses or a different time-out
 setting.
 
-The provided ADDRESS set by this option will be used even if
-\fICURLOPT_IPRESOLVE(3)\fP is set to make libcurl use another IP version.
+An ADDRESS provided by this option will only be use if not restricted by
+the setting of \fICURLOPT_IPRESOLVE(3)\fP to a different IP version.
 
 Remove names from the DNS cache again, to stop providing these fake resolves,
 by including a string in the linked list that uses the format