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