1--- 2c: Copyright (C) Daniel Stenberg, <daniel.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) 13--- 14 15# NAME 16 17CURLOPT_DNS_CACHE_TIMEOUT - life-time for DNS cache entries 18 19# SYNOPSIS 20 21~~~c 22#include <curl/curl.h> 23 24CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_CACHE_TIMEOUT, long age); 25~~~ 26 27# DESCRIPTION 28 29Pass a long, this sets the timeout in seconds. Name resolve results are kept 30in memory and used for this number of seconds. Set to zero to completely 31disable caching, or set to -1 to make the cached entries remain forever. By 32default, libcurl caches this info for 60 seconds. 33 34We recommend users not to tamper with this option unless strictly necessary. 35If you do, be careful of using large values that can make the cache size grow 36significantly if many different host names are used within that timeout 37period. 38 39The name resolve functions of various libc implementations do not re-read name 40server information unless explicitly told so (for example, by calling 41*res_init(3)*). This may cause libcurl to keep using the older server even 42if DHCP has updated the server info, and this may look like a DNS cache issue 43to the casual libcurl-app user. 44 45DNS entries have a "TTL" property but libcurl does not use that. This DNS 46cache timeout is entirely speculative that a name resolves to the same address 47for a small amount of time into the future. 48 49Since version 8.1.0, libcurl prunes entries from the DNS cache if it exceeds 5030,000 entries no matter which timeout value is used. 51 52# DEFAULT 53 5460 55 56# PROTOCOLS 57 58All 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 86Always 87 88# RETURN VALUE 89 90Returns CURLE_OK 91