setopt: add CURLOPT_DOH_URL

Timeout for DNS cache. See \fICURLOPT_DNS_CACHE_TIMEOUT(3)\fP

.IP CURLOPT_DNS_USE_GLOBAL_CACHE

OBSOLETE Enable global DNS cache. See \fICURLOPT_DNS_USE_GLOBAL_CACHE(3)\fP

.IP CURLOPT_DOH_URL

Use this DOH server for name resolves. See \fICURLOPT_DOH_URL(3)\fP

.IP CURLOPT_BUFFERSIZE

Ask for alternate buffer size. See \fICURLOPT_BUFFERSIZE(3)\fP

.IP CURLOPT_PORT

.\" **************************************************************************

.\" *                                  _   _ ____  _

.\" *  Project                     ___| | | |  _ \| |

.\" *                             / __| | | | |_) | |

.\" *                            | (__| |_| |  _ <| |___

.\" *                             \___|\___/|_| \_\_____|

.\" *

.\" * Copyright (C) 2018, 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.haxx.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.

.\" *

.\" **************************************************************************

.\"

.TH CURLOPT_DOH_URL 3 "18 Jun 2018" "libcurl 7.62.0" "curl_easy_setopt options"

.SH NAME

CURLOPT_DOH_URL \- provide the DNS-over-HTTPS URL

.SH SYNOPSIS

#include <curl/curl.h>

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

.SH DESCRIPTION

Pass in a pointer to a \fIURL\fP for the DOH server to use for name

resolving. The parameter should be a char * to a zero terminated string which

must be URL-encoded in the following format: "https://host:port/path". It MUST

specify a HTTPS URL.

libcurl doesn't validate the syntax or use this variable until the transfer is

issued. Even if you set a crazy value here, \fIcurl_easy_setopt(3)\fP will

still return \fICURLE_OK\fP.

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

To find the DOH server itself, which might be specified using a name, libcurl

will use the default name lookup function. You can bootstrap that by providing

the address for the DOH server with \fICURLOPT_RESOLVE(3)\fP.

Disable DOH use again by setting this option to NULL.

.SH DEFAULT

NULL - there is no default DOH URL. If this option isn't set, libcurl will use

the default name resolver.

.SH PROTOCOLS

All

.SH EXAMPLE

.nf

CURL *curl = curl_easy_init();

if(curl) {

  curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");

  curl_easy_setopt(curl, CURLOPT_DOH_URL, "https://dns.example.com");

  curl_easy_perform(curl);

}

.fi

.SH AVAILABILITY

Added in 7.62.0

.SH RETURN VALUE

Returns CURLE_OK on success or CURLE_OUT_OF_MEMORY if there was insufficient

heap space.

Note that \fIcurl_easy_setopt(3)\fP won't actually parse the given string so

given a bad DOH URL, curl will not detect a problem until it tries to resolve

a name with it.

.SH "SEE ALSO"

.BR CURLOPT_VERBOSE "(3), " CURLOPT_RESOLVE "(3), "

  CURLOPT_DNS_SERVERS.3                         \

  CURLOPT_DNS_SHUFFLE_ADDRESSES.3               \

  CURLOPT_DNS_USE_GLOBAL_CACHE.3                \

  CURLOPT_DOH_URL.3                             \

  CURLOPT_EGDSOCKET.3                           \

  CURLOPT_ERRORBUFFER.3                         \

  CURLOPT_EXPECT_100_TIMEOUT_MS.3               \

CURLOPT_DNS_SERVERS             7.24.0

CURLOPT_DNS_SHUFFLE_ADDRESSES   7.60.0

CURLOPT_DNS_USE_GLOBAL_CACHE    7.9.3         7.11.1

CURLOPT_DOH_URL                 7.62.0

CURLOPT_EGDSOCKET               7.7

CURLOPT_ENCODING                7.10

CURLOPT_ERRORBUFFER             7.1

  /* Disallow specifying username/login in URL. */

  CINIT(DISALLOW_USERNAME_IN_URL, LONG, 278),

  /* DNS-over-HTTPS URL */

  CINIT(DOH_URL, STRINGPOINT, 279),

  CURLOPT_LASTENTRY /* the last unused */

} CURLoption;