quickjs-tart

quickjs-based runtime for wallet-core logic
Log | Files | Refs | README | LICENSE

CURLOPT_RESOLVE.md (3798B)

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