CURLOPT_HTTP_VERSION: seting this to 3 forces HTTP/3 use directly

Even though it cannot fall-back to a lower HTTP version automatically. The
safer way to upgrade remains via CURLOPT_ALTSVC.

CURLOPT_H3 no longer has any bits that do anything and might be removed
before we remove the experimental label.

Updated the curl tool accordingly to use "--http3".

Closes #4197

4 files changed, 16 insertions, 12 deletions

diff --git a/docs/libcurl/opts/CURLINFO_HTTP_VERSION.3 b/docs/libcurl/opts/CURLINFO_HTTP_VERSION.3
index b0f43e549..7e8931812 100644
--- a/docs/libcurl/opts/CURLINFO_HTTP_VERSION.3
+++ b/docs/libcurl/opts/CURLINFO_HTTP_VERSION.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2016, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -28,9 +28,10 @@ CURLINFO_HTTP_VERSION \- get the http version used in the connection
 
 CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_HTTP_VERSION, long *p);
 .SH DESCRIPTION
-Pass a pointer to a long to receive the version used in the last http connection.
-The returned value will be CURL_HTTP_VERSION_1_0, CURL_HTTP_VERSION_1_1, or
-CURL_HTTP_VERSION_2_0, or 0 if the version can't be determined.
+Pass a pointer to a long to receive the version used in the last http
+connection.  The returned value will be CURL_HTTP_VERSION_1_0,
+CURL_HTTP_VERSION_1_1, CURL_HTTP_VERSION_2_0, CURL_HTTP_VERSION_3 or 0 if the
+version can't be determined.
 .SH PROTOCOLS
 HTTP
 .SH EXAMPLE
diff --git a/docs/libcurl/opts/CURLOPT_H3.3 b/docs/libcurl/opts/CURLOPT_H3.3
index be521b6bf..3411073fd 100644
--- a/docs/libcurl/opts/CURLOPT_H3.3
+++ b/docs/libcurl/opts/CURLOPT_H3.3
@@ -35,10 +35,6 @@ production before the experimental label is removed.
 .SH DESCRIPTION
 This function accepts a long \fIbitmask\fP with a set of flags set that
 controls the HTTP/3 behavior for this transfer.
-.IP "CURLH3_DIRECT"
-If this bit is set in \fIbitmask\fP, the host name and port number given in
-the URL will be used to connect to directly with QUIC and the port number then
-being a UDP port number.
 .SH DEFAULT
 0
 .SH PROTOCOLS
@@ -49,7 +45,7 @@ CURL *curl = curl_easy_init();
 if(curl) {
   CURLcode ret;
   curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
-  curl_easy_setopt(curl, CURLOPT_H3, (long)CURLH3_DIRECT);
+  curl_easy_setopt(curl, CURLOPT_H3, (long)0);
   ret = curl_easy_perform(curl);
 }
 .fi
diff --git a/docs/libcurl/opts/CURLOPT_HTTP_VERSION.3 b/docs/libcurl/opts/CURLOPT_HTTP_VERSION.3
index 741dfaa6c..564c0dc16 100644
--- a/docs/libcurl/opts/CURLOPT_HTTP_VERSION.3
+++ b/docs/libcurl/opts/CURLOPT_HTTP_VERSION.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -57,6 +57,14 @@ Issue non-TLS HTTP requests using HTTP/2 without HTTP/1.1 Upgrade. It requires
 prior knowledge that the server supports HTTP/2 straight away. HTTPS requests
 will still do HTTP/2 the standard way with negotiated protocol version in the
 TLS handshake. (Added in 7.49.0)
+.IP CURL_HTTP_VERSION_3
+(Added in 7.66.0) Setting this value will make libcurl attempt to use HTTP/3
+directly to server given in the URL. Note that this cannot gracefully
+downgrade to earlier HTTP version if the server doesn't support HTTP/3.
+
+For more reliably upgrading into HTTP/3, set the prefered version to something
+lower and let the server announce its HTTP/3 support via Alt-Svc:. See
+\fICURLOPT_ALTSVC(3)\fP.
 .SH DEFAULT
 Since curl 7.62.0: CURL_HTTP_VERSION_2TLS
 
@@ -82,4 +90,4 @@ Along with HTTP
 Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not.
 .SH "SEE ALSO"
 .BR CURLOPT_SSLVERSION "(3), " CURLOPT_HTTP200ALIASES "(3), "
-.BR CURLOPT_HTTP09_ALLOWED "(3), "
+.BR CURLOPT_HTTP09_ALLOWED "(3), " CURLOPT_H3 "(3), " CURLOPT_ALTSVC "(3) "
diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions
index 79243e25b..9a4cec2b0 100644
--- a/docs/libcurl/symbols-in-versions
+++ b/docs/libcurl/symbols-in-versions
@@ -209,7 +209,6 @@ CURLFTP_CREATE_DIR_RETRY        7.19.4
 CURLGSSAPI_DELEGATION_FLAG      7.22.0
 CURLGSSAPI_DELEGATION_NONE      7.22.0
 CURLGSSAPI_DELEGATION_POLICY_FLAG 7.22.0
-CURLH3_DIRECT                   7.66.0
 CURLHEADER_SEPARATE             7.37.0
 CURLHEADER_UNIFIED              7.37.0
 CURLINFO_ACTIVESOCKET           7.45.0