docs/libcurl/opts/CURLOPT_RESOLVE.3

   1 .\" **************************************************************************
   2 .\" *                                  _   _ ____  _
   3 .\" *  Project                     ___| | | |  _ \| |
   4 .\" *                             / __| | | | |_) | |
   5 .\" *                            | (__| |_| |  _ <| |___
   6 .\" *                             \___|\___/|_| \_\_____|
   7 .\" *
   8 .\" * Copyright (C) 1998 - 2014, 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 http://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 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options"
  24 .SH NAME
  25 CURLOPT_RESOLVE \- provide custom host name to IP address resolves
  26 .SH SYNOPSIS
  27 .nf
  28 #include <curl/curl.h>
  29
  30 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RESOLVE,
  31                           struct curl_slist *hosts);
  32 .SH DESCRIPTION
  33 Pass a pointer to a linked list of strings with host name resolve information
  34 to use for requests with this handle. The linked list should be a fully valid
  35 list of \fBstruct curl_slist\fP structs properly filled in. Use
  36 \fIcurl_slist_append(3)\fP to create the list and \fIcurl_slist_free_all(3)\fP
  37 to clean up an entire list.
  38
  39 Each single name resolve string should be written using the format
  40 HOST:PORT:ADDRESS where HOST is the name libcurl will try to resolve, PORT is
  41 the port number of the service where libcurl wants to connect to the HOST and
  42 ADDRESS is the numerical IP address. If libcurl is built to support IPv6,
  43 ADDRESS can of course be either IPv4 or IPv6 style addressing.
  44
  45 This option effectively pre-populates the DNS cache with entries for the
  46 host+port pair so redirects and everything that operations against the
  47 HOST+PORT will instead use your provided ADDRESS. Addresses to set with
  48 \fICURL_RESOLVE\fP will not time-out from the DNS cache like ordinary
  49 entries.
  50
  51 You can remove names from the DNS cache again, to stop providing these fake
  52 resolves, by including a string in the linked list that uses the format
  53 \&"-HOST:PORT". The host name must be prefixed with a dash, and the host name
  54 and port number must exactly match what was already added previously.
  55 .SH DEFAULT
  56 NULL
  57 .SH PROTOCOLS
  58 All
  59 .SH EXAMPLE
  60 .nf
  61 CURL *curl;
  62 struct curl_slist *host = NULL;
  63 host = curl_slist_append(NULL, "example.com:80:127.0.0.1");
  64
  65 curl = curl_easy_init();
  66 if(curl) {
  67   curl_easy_setopt(curl, CURLOPT_RESOLVE, host);
  68   curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
  69   res = curl_easy_perform(curl);
  70
  71   /* always cleanup */
  72   curl_easy_cleanup(curl);
  73 }
  74
  75 curl_slist_free_all(host);
  76 .fi
  77 .SH AVAILABILITY
  78 Added in 7.21.3
  79 .SH RETURN VALUE
  80 Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
  81 .SH "SEE ALSO"
  82 .BR CURLOPT_IPRESOLVE "(3), " CURLOPT_DNS_CACHE_TIMEOUT "(3), "