CURLOPT_RESOLVE(3)

1CURLOPT_RESOLVE(3)         curl_easy_setopt options         CURLOPT_RESOLVE(3)
2
3
4

NAME

6       CURLOPT_RESOLVE - provide custom host name to IP address resolves
7

SYNOPSIS

9       #include <curl/curl.h>
10
11       CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RESOLVE,
12                                 struct curl_slist *hosts);
13

DESCRIPTION

15       Pass  a  pointer to a linked list of strings with host name resolve in‐
16       formation to use for requests with this handle. The linked list  should
17       be  a fully valid list of struct curl_slist structs properly filled in.
18       Use curl_slist_append(3) to create the list and  curl_slist_free_all(3)
19       to clean up an entire list.
20
21       Each  single  name  resolve  string  should be written using the format
22       [+]HOST:PORT:ADDRESS[,ADDRESS]... where HOST is the name  libcurl  will
23       try  to  resolve,  PORT is the port number of the service where libcurl
24       wants to connect to the HOST and ADDRESS is one or  more  numerical  IP
25       addresses.  If  you specify multiple ip addresses they need to be sepa‐
26       rated by comma. If libcurl is built to support IPv6, each  of  the  AD‐
27       DRESS entries can of course be either IPv4 or IPv6 style addressing.
28
29       This  option  effectively  pre-populates the DNS cache with entries for
30       the host+port pair so redirects and everything that operations  against
31       the HOST+PORT will instead use your provided ADDRESS.
32
33       The  optional  leading "+" signifies whether the new entry should time-
34       out or not. Entries added with "HOST:..." will never  time-out  whereas
35       entries  added  with  "+HOST:..."  will time-out just like ordinary DNS
36       cache entries.
37
38       If the DNS cache already has an entry for  the  given  host+port  pair,
39       then  this  entry will be removed and a new entry will be created. This
40       is because the old entry may have have different addresses or a differ‐
41       ent time-out setting.
42
43       The  provided  ADDRESS  set  by  this  option will be used even if CUR‐
44       LOPT_IPRESOLVE(3) is set to make libcurl use another IP version.
45
46       Remove names from the DNS cache again, to stop providing these fake re‐
47       solves,  by  including a string in the linked list that uses the format
48       "-HOST:PORT". The host name must be prefixed with a dash, and the  host
49       name  and  port number must exactly match what was already added previ‐
50       ously.
51
52       Support for providing  the  ADDRESS  within  [brackets]  was  added  in
53       7.57.0.
54
55       Support  for  providing  multiple  IP  addresses per entry was added in
56       7.59.0.
57
58       Support for adding non-permanent entries by using the  "+"  prefix  was
59       added in 7.75.0.
60

DEFAULT

62       NULL
63

PROTOCOLS

65       All
66

EXAMPLE

68       CURL *curl;
69       struct curl_slist *host = NULL;
70       host = curl_slist_append(NULL, "example.com:80:127.0.0.1");
71
72       curl = curl_easy_init();
73       if(curl) {
74         curl_easy_setopt(curl, CURLOPT_RESOLVE, host);
75         curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
76
77         curl_easy_perform(curl);
78
79         /* always cleanup */
80         curl_easy_cleanup(curl);
81       }
82
83       curl_slist_free_all(host);
84

AVAILABILITY

86       Added in 7.21.3. Removal support added in 7.42.0.
87

RETURN VALUE

89       Returns  CURLE_OK  if the option is supported, and CURLE_UNKNOWN_OPTION
90       if not.
91