docs/libcurl/opts/CURLOPT_RESOLVE.3

   1 .\" **************************************************************************
   2 .\" *                                  _   _ ____  _
   3 .\" *  Project                     ___| | | |  _ \| |
   4 .\" *                             / __| | | | |_) | |
   5 .\" *                            | (__| |_| |  _ <| |___
   6 .\" *                             \___|\___/|_| \_\_____|
   7 .\" *
   8 .\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
   9 .\" *
  10 .\" * This software is licensed as described in the file COPYING, which
  11 .\" * you should have received as part of this distribution. The terms
  12 .\" * are also available at https://curl.haxx.se/docs/copyright.html.
  13 .\" *
  14 .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
  15 .\" * copies of the Software, and permit persons to whom the Software is
  16 .\" * furnished to do so, under the terms of the COPYING file.
  17 .\" *
  18 .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
  19 .\" * KIND, either express or implied.
  20 .\" *
  21 .\" **************************************************************************
  22 .\"
  23 .TH CURLOPT_RESOLVE 3 "January 30, 2018" "libcurl 7.59.0" "curl_easy_setopt options"
  24
  25 .SH NAME
  26 CURLOPT_RESOLVE \- provide custom host name to IP address resolves
  27 .SH SYNOPSIS
  28 .nf
  29 #include <curl/curl.h>
  30
  31 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RESOLVE,
  32                           struct curl_slist *hosts);
  33 .SH DESCRIPTION
  34 Pass a pointer to a linked list of strings with host name resolve information
  35 to use for requests with this handle. The linked list should be a fully valid
  36 list of \fBstruct curl_slist\fP structs properly filled in. Use
  37 \fIcurl_slist_append(3)\fP to create the list and \fIcurl_slist_free_all(3)\fP
  38 to clean up an entire list.
  39
  40 Each single name resolve string should be written using the format
  41 HOST:PORT:ADDRESS[,ADDRESS]... where HOST is the name libcurl will try
  42 to resolve, PORT is the port number of the service where libcurl wants
  43 to connect to the HOST and ADDRESS is one or more numerical IP
  44 addresses. If you specify multiple ip addresses they need to be
  45 separated by comma. If libcurl is built to support IPv6, each of the
  46 ADDRESS entries can of course be either IPv4 or IPv6 style addressing.
  47
  48 This option effectively pre-populates the DNS cache with entries for the
  49 host+port pair so redirects and everything that operations against the
  50 HOST+PORT will instead use your provided ADDRESS. Addresses set with
  51 \fICURLOPT_RESOLVE(3)\fP will not time-out from the DNS cache like ordinary
  52 entries.
  53
  54 The provided ADDRESS set by this option will be used even if
  55 \fICURLOPT_IPRESOLVE(3)\fP is set to make libcurl use another IP version.
  56
  57 Remove names from the DNS cache again, to stop providing these fake resolves,
  58 by including a string in the linked list that uses the format
  59 \&"-HOST:PORT". The host name must be prefixed with a dash, and the host name
  60 and port number must exactly match what was already added previously.
  61
  62 Support for providing the ADDRESS within [brackets] was added in 7.57.0.
  63
  64 Support for providing multiple IP addresses per entry was added in 7.59.0.
  65 .SH DEFAULT
  66 NULL
  67 .SH PROTOCOLS
  68 All
  69 .SH EXAMPLE
  70 .nf
  71 CURL *curl;
  72 struct curl_slist *host = NULL;
  73 host = curl_slist_append(NULL, "example.com:80:127.0.0.1");
  74
  75 curl = curl_easy_init();
  76 if(curl) {
  77   curl_easy_setopt(curl, CURLOPT_RESOLVE, host);
  78   curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
  79
  80   curl_easy_perform(curl);
  81
  82   /* always cleanup */
  83   curl_easy_cleanup(curl);
  84 }
  85
  86 curl_slist_free_all(host);
  87 .fi
  88 .SH AVAILABILITY
  89 Added in 7.21.3. Removal support added in 7.42.0.
  90 .SH RETURN VALUE
  91 Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
  92 .SH "SEE ALSO"
  93 .BR CURLOPT_IPRESOLVE "(3), " CURLOPT_DNS_CACHE_TIMEOUT "(3), " CURLOPT_CONNECT_TO "(3), "