CURLOPT_HTTP_VERSION(3)

1CURLOPT_HTTP_VERSION(3)             libcurl            CURLOPT_HTTP_VERSION(3)
2
3
4

NAME

6       CURLOPT_HTTP_VERSION - HTTP protocol version to use
7

SYNOPSIS

9       #include <curl/curl.h>
10
11       CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTP_VERSION, long version);
12

DESCRIPTION

14       Pass version a long, set to one of the values described below. They ask
15       libcurl to use the specific HTTP versions.
16
17       Note that the HTTP version is just a request. libcurl will still prior‐
18       itize  to  re-use an existing connection so it might then re-use a con‐
19       nection using a HTTP version you have not asked for.
20
21
22       CURL_HTTP_VERSION_NONE
23              We do not care about what version the library uses. libcurl will
24              use whatever it thinks fit.
25
26       CURL_HTTP_VERSION_1_0
27              Enforce HTTP 1.0 requests.
28
29       CURL_HTTP_VERSION_1_1
30              Enforce HTTP 1.1 requests.
31
32       CURL_HTTP_VERSION_2_0
33              Attempt  HTTP  2 requests. libcurl will fall back to HTTP 1.1 if
34              HTTP 2 cannot be negotiated with the server. (Added in 7.33.0)
35
36              When libcurl uses HTTP/2 over HTTPS, it does not  itself  insist
37              on  TLS 1.2 or higher even though that is required by the speci‐
38              fication. A user can add  this  version  requirement  with  CUR‐
39              LOPT_SSLVERSION(3).
40
41              The  alias CURL_HTTP_VERSION_2 was added in 7.43.0 to better re‐
42              flect the actual protocol name.
43
44       CURL_HTTP_VERSION_2TLS
45              Attempt HTTP 2 over TLS (HTTPS) only. libcurl will fall back  to
46              HTTP  1.1  if HTTP 2 cannot be negotiated with the HTTPS server.
47              For clear text HTTP servers, libcurl will  use  1.1.  (Added  in
48              7.47.0)
49
50       CURL_HTTP_VERSION_2_PRIOR_KNOWLEDGE
51              Issue  non-TLS  HTTP  requests using HTTP/2 without HTTP/1.1 Up‐
52              grade. It requires prior  knowledge  that  the  server  supports
53              HTTP/2  straight  away.  HTTPS requests will still do HTTP/2 the
54              standard way with negotiated protocol version in the  TLS  hand‐
55              shake. (Added in 7.49.0)
56
57       CURL_HTTP_VERSION_3
58              (Added  in  7.66.0)  This  option  makes  libcurl attempt to use
59              HTTP/3 to the host given in the URL, with  fallback  to  earlier
60              HTTP versions if needed.
61
62       CURL_HTTP_VERSION_3ONLY
63              (Added  in  7.88.0) Setting this value will make libcurl attempt
64              to use HTTP/3 directly to server given in the URL but  will  not
65              downgrade to earlier HTTP version if the server does not support
66              HTTP/3.
67

DEFAULT

69       Since curl 7.62.0: CURL_HTTP_VERSION_2TLS
70
71       Before that: CURL_HTTP_VERSION_1_1
72

PROTOCOLS

74       HTTP
75

EXAMPLE

77       CURL *curl = curl_easy_init();
78       if(curl) {
79         CURLcode ret;
80         curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
81         curl_easy_setopt(curl, CURLOPT_HTTP_VERSION,
82                          (long)CURL_HTTP_VERSION_2TLS);
83         ret = curl_easy_perform(curl);
84         if(ret == CURLE_HTTP_RETURNED_ERROR) {
85           /* an HTTP response error problem */
86         }
87       }
88

AVAILABILITY

90       Along with HTTP
91

RETURN VALUE

93       Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not.
94