CURLOPT_DNS_CACHE_TIMEOUT(3)

1CURLOPT_DNS_CACHE_TIMEOUT(3)        libcurl       CURLOPT_DNS_CACHE_TIMEOUT(3)
2
3
4

NAME

6       CURLOPT_DNS_CACHE_TIMEOUT - life-time for DNS cache entries
7

SYNOPSIS

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

DESCRIPTION

14       Pass  a  long,  this sets the timeout in seconds. Name resolves will be
15       kept in memory and used for this number of seconds. Set to zero to com‐
16       pletely disable caching, or set to -1 to make the cached entries remain
17       forever. By default, libcurl caches this info for 60 seconds.
18
19       We recommend users not to tamper with this option unless strictly  nec‐
20       essary.   If you do, be careful of using large values that can make the
21       cache size grow significantly if many different  host  names  are  used
22       within that timeout period.
23
24       The  name  resolve functions of various libc implementations do not re-
25       read name server information unless explicitly told so (for example, by
26       calling  res_init(3)).  This  may cause libcurl to keep using the older
27       server even if DHCP has updated the server info, and this may look like
28       a DNS cache issue to the casual libcurl-app user.
29
30       DNS  entries  have a "TTL" property but libcurl does not use that. This
31       DNS cache timeout is entirely speculative that a name will  resolve  to
32       the same address for a certain small amount of time into the future.
33
34       Since  version  8.1.0,  libcurl prunes entries from the DNS cache if it
35       exceeds 30,000 entries no matter which timeout value is used.
36

DEFAULT

38       60
39

PROTOCOLS

41       All
42

EXAMPLE

44       CURL *curl = curl_easy_init();
45       if(curl) {
46         curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
47
48         /* only reuse addresses for a short time */
49         curl_easy_setopt(curl, CURLOPT_DNS_CACHE_TIMEOUT, 2L);
50
51         ret = curl_easy_perform(curl);
52
53         /* in this second request, the cache will not be used if more than
54            two seconds have passed since the previous name resolve */
55         ret = curl_easy_perform(curl);
56
57         curl_easy_cleanup(curl);
58       }
59

AVAILABILITY

61       Always
62

RETURN VALUE

64       Returns CURLE_OK
65