CURLOPT_DNS_CACHE_TIMEOUT(3)

💅 CURLOPT_DNS_CACHE_TIMEOUT — like, the manual (Library Functions Manual, bestie)

okay so real talk: this page is from the Library Functions Manual and it's all about how long libcurl holds onto DNS glow-ups before it forgets them. stay with me, it's actually iconic 🎀

✨ NAME ✨

CURLOPT_DNS_CACHE_TIMEOUT — the life-time for DNS cache entries, periodt

🌸 SYNOPSIS 🌸

#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_CACHE_TIMEOUT, long age);

🦋 DESCRIPTION 🦋

okay so you pass a long, and that's your timeout in seconds. Name resolve results get kept in memory and used for exactly that many seconds. It's giving "how long do we trust this address" energy 💅

• Set it to zero and you completely disable caching. No cache, no memories, we move on.
• Set it to -1 and the cached entries remain forever. Ride or die, no cap.
• By default, libcurl caches this info for 60 seconds.

⚠️ We recommend users not to tamper with this option unless it's strictly necessary. Like, seriously. And if you do, be careful of using large values — those can make the cache size grow significantly if many different hostnames are used within that timeout period. Big timeout + lots of hostnames = a cache that ate and left no crumbs (in a bad way 😭).

Here's the lowkey cursed part: the name resolve functions of various libc implementations do not re-read name server information unless they're explicitly told so (for example, by calling res_init(3)). So libcurl may keep using the older server even if DHCP has updated the server info — and to the casual libcurl-app user that looks like a DNS cache issue. Spoiler: it's not. 🙈

Also, DNS entries have a "TTL" property but libcurl does not use that. nope. This DNS cache timeout is entirely speculative — it's just vibes that a name resolves to the same address for a small amount of time into the future. ✨

Two more things so you're not blindsided:

• libcurl prunes entries from the DNS cache if it exceeds 30,000 entries, no matter which timeout value is used. (Added in version 8.1.0)
• Since curl 8.16.0, failed name resolves are stored in the DNS cache for half the set timeout period. half! 🍓

🎀 DEFAULT 🎀

60

💜 PROTOCOLS 💜

This functionality affects all supported protocols. all of them. every single one. 👑

🌈 EXAMPLE 🌈

int main(void)
{
  CURL *curl = curl_easy_init();
  if(curl) {
    CURLcode result;
    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");

    /* only reuse addresses for a short time */
    curl_easy_setopt(curl, CURLOPT_DNS_CACHE_TIMEOUT, 2L);

    result = curl_easy_perform(curl);

    /* in this second request, the cache is not be used if more than
       two seconds have passed since the previous name resolve */
    result = curl_easy_perform(curl);

    curl_easy_cleanup(curl);
  }
}

see how that works? two seconds and we're already forgetting. main character memory loss fr fr 💀

⭐ AVAILABILITY ⭐

Added in curl 7.9.3 — she's been around, she's a legend 🫶

💖 RETURN VALUE 💖

curl_easy_setopt(3) returns a CURLcode indicating success or error.

CURLE_OK (0) means everything was OK. non-zero means an error occurred — see libcurl-errors(3) for the whole tea. ☕

🧚 SEE ALSO 🧚

• CURLMOPT_NETWORK_CHANGED(3)
• CURLOPT_CONNECTTIMEOUT_MS(3)
• CURLOPT_DNS_SERVERS(3)
• CURLOPT_DNS_USE_GLOBAL_CACHE(3)
• CURLOPT_MAXAGE_CONN(3)
• CURLOPT_RESOLVE(3)

---

and that's the whole page bestie, you ate 💅✨ — this was libcurl, dated 2026-10-12, page CURLOPT_DNS_CACHE_TIMEOUT(3), signing off 🎀🦋