Artifactspublic-v0

curl

master
ply4 git calls24 ms288 KiB3 cachedprotocol v2
97 lines2.7 KiBRaw

NAME

CURLOPT_DNS_CACHE_TIMEOUT - life-time for DNS cache entries

SYNOPSIS

c
#include <curl/curl.h>

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

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 hostnames 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 res_init(3)). 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.

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. Since curl 8.22.0, this only happens when the resolver answered that the name does not exist, not on transient or local resolver failures.

DEFAULT

60

%PROTOCOLS%

EXAMPLE

c
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);
  }
}

%AVAILABILITY%

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).

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)
13 - CURLMOPT_NETWORK_CHANGED (3)
14Protocol:
15 - All
16Added-in: 7.9.3
17---
19# NAME
21CURLOPT_DNS_CACHE_TIMEOUT - life-time for DNS cache entries
23# SYNOPSIS
25~~~c
26#include <curl/curl.h>
28CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_CACHE_TIMEOUT, long age);
29~~~
31# DESCRIPTION
33Pass a long, this sets the timeout in seconds. Name resolve results are kept
34in memory and used for this number of seconds. Set to zero to completely
35disable caching, or set to -1 to make the cached entries remain forever. By
36default, libcurl caches this info for 60 seconds.
38We recommend users not to tamper with this option unless strictly necessary.
39If you do, be careful of using large values that can make the cache size grow
40significantly if many different hostnames are used within that timeout period.
42The name resolve functions of various libc implementations do not re-read name
43server information unless explicitly told so (for example, by calling
44*res_init(3)*). This may cause libcurl to keep using the older server even
45if DHCP has updated the server info, and this may look like a DNS cache issue
46to the casual libcurl-app user.
48DNS entries have a "TTL" property but libcurl does not use that. This DNS
49cache timeout is entirely speculative that a name resolves to the same address
50for a small amount of time into the future.
52libcurl prunes entries from the DNS cache if it exceeds 30,000 entries no
53matter which timeout value is used. (Added in version 8.1.0)
55Since curl 8.16.0, failed name resolves are stored in the DNS cache for half
56the set timeout period. Since curl 8.22.0, this only happens when the
57resolver answered that the name does not exist, not on transient or local
58resolver failures.
60# DEFAULT
6260
64# %PROTOCOLS%
66# EXAMPLE
68~~~c
69int main(void)
71 CURL *curl = curl_easy_init();
72 if(curl) {
73 CURLcode result;
74 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
76 /* only reuse addresses for a short time */
77 curl_easy_setopt(curl, CURLOPT_DNS_CACHE_TIMEOUT, 2L);
79 result = curl_easy_perform(curl);
81 /* in this second request, the cache is not be used if more than
82 two seconds have passed since the previous name resolve */
83 result = curl_easy_perform(curl);
85 curl_easy_cleanup(curl);
86 }
88~~~
90# %AVAILABILITY%
92# RETURN VALUE
94curl_easy_setopt(3) returns a CURLcode indicating success or error.
96CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
97libcurl-errors(3).
Diagnostics4 git calls · 24 ms
CallStatusSizeTime024 ms
discover200152 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=152
git.server.agent=gitty/1.0
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch object-format
git.server.fetch=shallow filter sideband-all
git.protocol.version=2
git.pkt.frames=8
git.pkt.data=6
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=152
git.pkt.payload.max=34
ls-refs200149 B · hit3 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=149
git.response.cache=HIT
git.response.duration_ms=3
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=149
git.pkt.payload.max=78
git.ls_refs.count=2
git.ls_refs.head=refs/heads/master
fetchblob:none · deepen 10200287 KiB · hit2 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=19
git.response.bytes=293470
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=blob:none
git.fetch.filter.requested=tree:0
git.fetch.filter.fallback=blob:none
git.fetch.filter.learned=false
git.fetch.wants=31c911efe5652725e930f4d2e60c9060e5f6646d
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=10
git.pkt.data=8
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=293470
git.pkt.payload.max=65516
git.sideband.band1.bytes=293354
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=87
git.pack.bytes=293354
git.pack.ofs_delta=0
git.pack.ref_delta=1
git.pack.chain.max=1
git.pack.trailer=6a646bcda6740bab42e321b51998b52ea15146c0
git.pack.full=86
Open pack map
fetch2001.4 KiB · hit19 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=1474
git.response.cache=HIT
git.response.duration_ms=19
git.fetch.wants=893852d3ead916029930be9f438b8fb2c1b7c843
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=1474
git.pkt.payload.max=1453
git.sideband.band1.bytes=1452
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/curl.git
Ref
refs/heads/master
Commit
31c911efe5652725e930f4d2e60c9060e5f6646d
cf-ray
a5e375d18fd7a140
Request
f915e4c2…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format