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 13Added-in: 7.21.3 14--- 15 16# NAME 17 18CURLOPT_RESOLVE - provide custom hostname to IP address resolves 19 20# SYNOPSIS 21 22~~~c 23#include <curl/curl.h> 24 25CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RESOLVE, 26 struct curl_slist *hosts); 27~~~ 28 29# DESCRIPTION 30 31Pass a pointer to a linked list of strings with hostname resolve information 32to use for requests with this handle. The linked list should be a fully valid 33list of **struct curl_slist** structs properly filled in. Use 34curl_slist_append(3) to create the list and curl_slist_free_all(3) to clean up 35an entire list. 36 37libcurl does not copy the list, it needs to be kept around until after the 38transfer has completed. 39 40Each resolve rule to add should be written using the format 41 42 [+]HOST:PORT:ADDRESS[,ADDRESS] 43 44HOST is the name libcurl wants to resolve, PORT is the port number of the 45service where libcurl wants to connect to the HOST and ADDRESS is one or more 46numerical IP addresses. If you specify multiple IP addresses they need to be 47separated by comma. If libcurl is built to support IPv6, each of the ADDRESS 48entries can of course be either IPv4 or IPv6 style addressing. 49 50Specify the host as a single ampersand (`*`) to match all names. This wildcard 51is resolved last so any resolve with a specific host and port number is given 52priority. 53 54This option effectively populates the DNS cache with entries for the host+port 55pair so redirects and everything that operations against the HOST+PORT instead 56use your provided ADDRESS. 57 58The optional leading plus (`+`) specifies that the new entry should timeout. 59Entries added without the leading plus character never times out whereas 60entries added with `+HOST:...` times out just like ordinary DNS cache entries. 61 62If the DNS cache already has an entry for the given host+port pair, the new 63entry overrides the former one. 64 65An ADDRESS provided by this option is only used if not restricted by the 66setting of CURLOPT_IPRESOLVE(3) to a different IP version. 67 68To remove names from the DNS cache again, to stop providing these fake 69resolves, include a string in the linked list that uses the format 70 71 -HOST:PORT 72 73The entry to remove must be prefixed with a dash, and the hostname and port 74number must exactly match what was added previously. 75 76Using this option multiple times makes the last set list override the previous 77ones. Set it to NULL to disable its use again. 78 79# DEFAULT 80 81NULL 82 83# %PROTOCOLS% 84 85# EXAMPLE 86 87~~~c 88int main(void) 89{ 90 CURL *curl; 91 struct curl_slist *host = NULL; 92 host = curl_slist_append(NULL, "example.com:443:127.0.0.1"); 93 94 curl = curl_easy_init(); 95 if(curl) { 96 curl_easy_setopt(curl, CURLOPT_RESOLVE, host); 97 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); 98 99 curl_easy_perform(curl); 100 101 /* always cleanup */ 102 curl_easy_cleanup(curl); 103 } 104 105 curl_slist_free_all(host); 106} 107~~~ 108 109# HISTORY 110 111Added in 7.21.3. Removal support added in 7.42.0. 112 113Support for providing the ADDRESS within [brackets] was added in 7.57.0. 114 115Support for providing multiple IP addresses per entry was added in 7.59.0. 116 117Support for adding non-permanent entries by using the "+" prefix was added in 1187.75.0. 119 120# %AVAILABILITY% 121 122# RETURN VALUE 123 124Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. 125
