1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_HTTP_VERSION
5Section: 3
6Source: libcurl
7Protocol:
8  - HTTP
9See-also:
10  - CURLOPT_ALTSVC (3)
11  - CURLOPT_HTTP09_ALLOWED (3)
12  - CURLOPT_HTTP200ALIASES (3)
13  - CURLOPT_SSLVERSION (3)
14---
15
16# NAME
17
18CURLOPT_HTTP_VERSION - HTTP protocol version to use
19
20# SYNOPSIS
21
22~~~c
23#include <curl/curl.h>
24
25CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTP_VERSION, long version);
26~~~
27
28# DESCRIPTION
29
30Pass *version* a long, set to one of the values described below. They ask
31libcurl to use the specific HTTP versions.
32
33Note that the HTTP version is just a request. libcurl still prioritizes to
34reuse existing connections so it might then reuse a connection using an HTTP
35version you have not asked for.
36
37## CURL_HTTP_VERSION_NONE
38
39We do not care about what version the library uses. libcurl uses whatever it
40thinks fit.
41
42## CURL_HTTP_VERSION_1_0
43
44Enforce HTTP 1.0 requests.
45
46## CURL_HTTP_VERSION_1_1
47
48Enforce HTTP 1.1 requests.
49
50## CURL_HTTP_VERSION_2_0
51
52Attempt HTTP 2 requests. libcurl falls back to HTTP 1.1 if HTTP 2 cannot be
53negotiated with the server. (Added in 7.33.0)
54
55When libcurl uses HTTP/2 over HTTPS, it does not itself insist on TLS 1.2 or
56higher even though that is required by the specification. A user can add this
57version requirement with CURLOPT_SSLVERSION(3).
58
59The alias *CURL_HTTP_VERSION_2* was added in 7.43.0 to better reflect the
60actual protocol name.
61
62## CURL_HTTP_VERSION_2TLS
63
64Attempt HTTP 2 over TLS (HTTPS) only. libcurl falls back to HTTP 1.1 if HTTP 2
65cannot be negotiated with the HTTPS server. For clear text HTTP servers,
66libcurl uses 1.1. (Added in 7.47.0)
67
68## CURL_HTTP_VERSION_2_PRIOR_KNOWLEDGE
69
70Issue non-TLS HTTP requests using HTTP/2 without HTTP/1.1 Upgrade. It requires
71prior knowledge that the server supports HTTP/2 straight away. HTTPS requests
72still do HTTP/2 the standard way with negotiated protocol version in the TLS
73handshake. (Added in 7.49.0)
74
75## CURL_HTTP_VERSION_3
76
77(Added in 7.66.0) This option makes libcurl attempt to use HTTP/3 to the host
78given in the URL, with fallback to earlier HTTP versions if needed.
79
80## CURL_HTTP_VERSION_3ONLY
81
82(Added in 7.88.0) Setting this makes libcurl attempt to use HTTP/3 directly to
83server given in the URL and does not downgrade to earlier HTTP version if the
84server does not support HTTP/3.
85
86# DEFAULT
87
88Since curl 7.62.0: CURL_HTTP_VERSION_2TLS
89
90Before that: CURL_HTTP_VERSION_1_1
91
92# EXAMPLE
93
94~~~c
95int main(void)
96{
97  CURL *curl = curl_easy_init();
98  if(curl) {
99    CURLcode ret;
100    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
101    curl_easy_setopt(curl, CURLOPT_HTTP_VERSION,
102                     (long)CURL_HTTP_VERSION_2TLS);
103    ret = curl_easy_perform(curl);
104    if(ret == CURLE_HTTP_RETURNED_ERROR) {
105      /* an HTTP response error problem */
106    }
107  }
108}
109~~~
110
111# AVAILABILITY
112
113Along with HTTP
114
115# RETURN VALUE
116
117Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not.
118