1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_DNS_CACHE_TIMEOUT
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_CONNECTTIMEOUT_MS (3)
9  - CURLOPT_DNS_SERVERS (3)
10  - CURLOPT_DNS_USE_GLOBAL_CACHE (3)
11  - CURLOPT_MAXAGE_CONN (3)
12  - CURLOPT_RESOLVE (3)
13Protocol:
14  - All
15Added-in: 7.9.3
16---
17
18# NAME
19
20CURLOPT_DNS_CACHE_TIMEOUT - life-time for DNS cache entries
21
22# SYNOPSIS
23
24~~~c
25#include <curl/curl.h>
26
27CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_CACHE_TIMEOUT, long age);
28~~~
29
30# DESCRIPTION
31
32Pass a long, this sets the timeout in seconds. Name resolve results are kept
33in memory and used for this number of seconds. Set to zero to completely
34disable caching, or set to -1 to make the cached entries remain forever. By
35default, libcurl caches this info for 60 seconds.
36
37We recommend users not to tamper with this option unless strictly necessary.
38If you do, be careful of using large values that can make the cache size grow
39significantly if many different hostnames are used within that timeout period.
40
41The name resolve functions of various libc implementations do not re-read name
42server information unless explicitly told so (for example, by calling
43*res_init(3)*). This may cause libcurl to keep using the older server even
44if DHCP has updated the server info, and this may look like a DNS cache issue
45to the casual libcurl-app user.
46
47DNS entries have a "TTL" property but libcurl does not use that. This DNS
48cache timeout is entirely speculative that a name resolves to the same address
49for a small amount of time into the future.
50
51Since version 8.1.0, libcurl prunes entries from the DNS cache if it exceeds
5230,000 entries no matter which timeout value is used.
53
54# DEFAULT
55
5660
57
58# %PROTOCOLS%
59
60# EXAMPLE
61
62~~~c
63int main(void)
64{
65  CURL *curl = curl_easy_init();
66  if(curl) {
67    CURLcode res;
68    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
69
70    /* only reuse addresses for a short time */
71    curl_easy_setopt(curl, CURLOPT_DNS_CACHE_TIMEOUT, 2L);
72
73    res = curl_easy_perform(curl);
74
75    /* in this second request, the cache is not be used if more than
76       two seconds have passed since the previous name resolve */
77    res = curl_easy_perform(curl);
78
79    curl_easy_cleanup(curl);
80  }
81}
82~~~
83
84# %AVAILABILITY%
85
86# RETURN VALUE
87
88Returns CURLE_OK
89