CURLOPT_DOH_URL(3)

💅 CURLOPT_DOH_URL(3) 💅

okay bestie, welcome to the Library Functions Manual page for CURLOPT_DOH_URL — this is the one where you hand libcurl a DNS-over-HTTPS URL and let it do its resolver thing. no cap. 🦋

---

✨ NAME ✨

CURLOPT_DOH_URL — provide the DNS-over-HTTPS URL. literally the whole vibe. 💖

📜 SYNOPSIS 📜

#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DOH_URL, char *URL);

🌸 DESCRIPTION 🌸

okay so you pass in a pointer to a URL for the DoH server to use for name resolving. the parameter should be a char pointer to a null-terminated string which must be a valid and correct HTTPS URL. like, actually correct, bestie. 🎀

libcurl does not validate the syntax or use this variable until the transfer is issued. even if you set a crazy value here, curl_easy_setopt(3) still returns CURLE_OK. yes, really. 💀

curl sends POST requests to the given DNS-over-HTTPS URL. periodt. 🔥

to find the DoH server itself, which might be specified using a name, libcurl uses the default name lookup function. you can bootstrap that by providing the address for the DoH server with CURLOPT_RESOLVE(3). iykyk. 🧚

the application does not have to keep the string around after setting this option. set it and forget it, basically. 💅

using this option multiple times makes the last set string override the previous ones. set it to NULL to disable its use again. 🌈

🔐 INHERIT OPTIONS 🔐

DoH lookups use SSL and some SSL settings from your transfer are inherited, like CURLOPT_SSL_CTX_FUNCTION(3). cute, right? 🫶

the hostname and peer certificate verification settings are not inherited but can be controlled separately via CURLOPT_DOH_SSL_VERIFYHOST(3) and CURLOPT_DOH_SSL_VERIFYPEER(3). keep that in mind, bestie. ⭐

a set CURLOPT_OPENSOCKETFUNCTION(3) callback is not inherited. nope, not that one. 🙈

💀 KNOWN BUGS 💀

even when DoH is set to be used with this option, there are still some name resolves that are performed without it, using the default name resolver mechanism. this includes name resolves done for CURLOPT_INTERFACE(3), CURLOPT_FTPPORT(3), a proxy type set to CURLPROXY_SOCKS4 or CURLPROXY_SOCKS5 and probably some more. so yeah, not every resolve is invited to the DoH party. 😭

🎀 DEFAULT 🎀

NULL

🌈 PROTOCOLS 🌈

this functionality affects all supported protocols. all of them. slay. 👑

🍓 EXAMPLE 🍓

int main(void)
{
  CURL *curl = curl_easy_init();
  if(curl) {
    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
    curl_easy_setopt(curl, CURLOPT_DOH_URL, "https://dns.example.com");
    curl_easy_perform(curl);
  }
}

⭐ AVAILABILITY ⭐

added in curl 7.62.0. iconic. 💖

🔥 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). no cap. 💅

note that curl_easy_setopt(3) does immediately parse the given string so when given a bad DoH URL, libcurl might not detect the problem until it later tries to resolve a name with it. so like, the bad URL can sneak by for a minute. 🙈

👀 SEE ALSO 👀

• CURLOPT_DNS_CACHE_TIMEOUT(3)
• CURLOPT_RESOLVE(3)
• CURLOPT_VERBOSE(3)

---

xoxo, libcurl 💖 — 2026-10-12