1--- 2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3SPDX-License-Identifier: curl 4Title: CURLOPT_RESOLVE 5Section: 3 6Source: libcurl 7See-also: 8 - CURLOPT_CONNECT_TO (3) 9 - CURLOPT_DNS_CACHE_TIMEOUT (3) 10 - CURLOPT_IPRESOLVE (3) 11Protocol: 12 - All 13--- 14 15# NAME 16 17CURLOPT_RESOLVE - provide custom hostname to IP address resolves 18 19# SYNOPSIS 20 21~~~c 22#include <curl/curl.h> 23 24CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RESOLVE, 25 struct curl_slist *hosts); 26~~~ 27 28# DESCRIPTION 29 30Pass a pointer to a linked list of strings with hostname resolve information 31to use for requests with this handle. The linked list should be a fully valid 32list of **struct curl_slist** structs properly filled in. Use 33curl_slist_append(3) to create the list and curl_slist_free_all(3) to clean up 34an entire list. 35 36Each resolve rule to add should be written using the format 37 38~~~c 39 [+]HOST:PORT:ADDRESS[,ADDRESS] 40~~~ 41 42HOST is the name libcurl wants to resolve, PORT is the port number of the 43service where libcurl wants to connect to the HOST and ADDRESS is one or more 44numerical IP addresses. If you specify multiple IP addresses they need to be 45separated by comma. If libcurl is built to support IPv6, each of the ADDRESS 46entries can of course be either IPv4 or IPv6 style addressing. 47 48This option effectively populates the DNS cache with entries for the host+port 49pair so redirects and everything that operations against the HOST+PORT instead 50use your provided ADDRESS. 51 52The optional leading "+" specifies that the new entry should time-out. Entries 53added without the leading plus character never times out whereas entries added 54with "+HOST:..." times out just like ordinary DNS cache entries. 55 56If the DNS cache already has an entry for the given host+port pair, the new 57entry overrides the former one. 58 59An ADDRESS provided by this option is only used if not restricted by the 60setting of CURLOPT_IPRESOLVE(3) to a different IP version. 61 62To remove names from the DNS cache again, to stop providing these fake 63resolves, include a string in the linked list that uses the format 64 65~~~c 66 -HOST:PORT 67~~~ 68 69The entry to remove must be prefixed with a dash, and the hostname and port 70number must exactly match what was added previously. 71 72# DEFAULT 73 74NULL 75 76# EXAMPLE 77 78~~~c 79int main(void) 80{ 81 CURL *curl; 82 struct curl_slist *host = NULL; 83 host = curl_slist_append(NULL, "example.com:443:127.0.0.1"); 84 85 curl = curl_easy_init(); 86 if(curl) { 87 curl_easy_setopt(curl, CURLOPT_RESOLVE, host); 88 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); 89 90 curl_easy_perform(curl); 91 92 /* always cleanup */ 93 curl_easy_cleanup(curl); 94 } 95 96 curl_slist_free_all(host); 97} 98~~~ 99 100# AVAILABILITY 101 102Added in 7.21.3. Removal support added in 7.42.0. 103 104Support for providing the ADDRESS within [brackets] was added in 7.57.0. 105 106Support for providing multiple IP addresses per entry was added in 7.59.0. 107 108Support for adding non-permanent entries by using the "+" prefix was added in 1097.75.0. 110 111# RETURN VALUE 112 113Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. 114
