.\" **************************************************************************
.\" *                                  _   _ ____  _
.\" *  Project                     ___| | | |  _ \| |
.\" *                             / __| | | | |_) | |
.\" *                            | (__| |_| |  _ <| |___
.\" *                             \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_DNS_CACHE_TIMEOUT 3 "17 Jun 2014" libcurl libcurl
.SH NAME
CURLOPT_DNS_CACHE_TIMEOUT \- life-time for DNS cache entries
.SH SYNOPSIS
.nf
#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_CACHE_TIMEOUT, long age);
.fi
.SH DESCRIPTION
Pass a long, this sets the timeout in seconds. Name resolve results are kept
in memory and used for this number of seconds. Set to zero to completely
disable caching, or set to -1 to make the cached entries remain forever. By
default, libcurl caches this info for 60 seconds.

We recommend users not to tamper with this option unless strictly necessary.
If you do, be careful of using large values that can make the cache size grow
significantly if many different host names are used within that timeout
period.

The name resolve functions of various libc implementations do not re-read name
server information unless explicitly told so (for example, by calling
\fIres_init(3)\fP). This may cause libcurl to keep using the older server even
if DHCP has updated the server info, and this may look like a DNS cache issue
to the casual libcurl-app user.

DNS entries have a "TTL" property but libcurl does not use that. This DNS
cache timeout is entirely speculative that a name resolves to the same address
for a small amount of time into the future.

Since version 8.1.0, libcurl prunes entries from the DNS cache if it exceeds
30,000 entries no matter which timeout value is used.
.SH DEFAULT
60
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
int main(void)
{
  CURL *curl = curl_easy_init();
  if(curl) {
    CURLcode res;
    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);

    res = 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 */
    res = curl_easy_perform(curl);

    curl_easy_cleanup(curl);
  }
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_CONNECTTIMEOUT_MS (3),
.BR CURLOPT_DNS_SERVERS (3),
.BR CURLOPT_DNS_USE_GLOBAL_CACHE (3),
.BR CURLOPT_MAXAGE_CONN (3),
.BR CURLOPT_RESOLVE (3)