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