1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS
5Section: 3
6Source: libcurl
7Protocol:
8  - All
9See-also:
10  - CURLOPT_CONNECTTIMEOUT_MS (3)
11  - CURLOPT_LOW_SPEED_LIMIT (3)
12  - CURLOPT_TIMEOUT (3)
13---
14
15# NAME
16
17CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS - head start for IPv6 for happy eyeballs
18
19# SYNOPSIS
20
21~~~c
22#include <curl/curl.h>
23
24CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS,
25                          long timeout);
26~~~
27
28# DESCRIPTION
29
30Happy eyeballs is an algorithm that attempts to connect to both IPv4 and IPv6
31addresses for dual-stack hosts, preferring IPv6 first for *timeout*
32milliseconds. If the IPv6 address cannot be connected to within that time then
33a connection attempt is made to the IPv4 address in parallel. The first
34connection to be established is the one that is used.
35
36The range of suggested useful values for *timeout* is limited. Happy
37Eyeballs RFC 6555 says "It is RECOMMENDED that connection attempts be paced
38150-250 ms apart to balance human factors against network load." libcurl
39currently defaults to 200 ms. Firefox and Chrome currently default to 300 ms.
40
41# DEFAULT
42
43CURL_HET_DEFAULT (currently defined as 200L)
44
45# EXAMPLE
46
47~~~c
48int main(void)
49{
50  CURL *curl = curl_easy_init();
51  if(curl) {
52    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
53    curl_easy_setopt(curl, CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS, 300L);
54
55    curl_easy_perform(curl);
56
57    /* always cleanup */
58    curl_easy_cleanup(curl);
59  }
60}
61~~~
62
63# AVAILABILITY
64
65Added in 7.59.0
66
67# RETURN VALUE
68
69Returns CURLE_OK
70