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