docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.3

   1 .\" **************************************************************************
   2 .\" *                                  _   _ ____  _
   3 .\" *  Project                     ___| | | |  _ \| |
   4 .\" *                             / __| | | | |_) | |
   5 .\" *                            | (__| |_| |  _ <| |___
   6 .\" *                             \___|\___/|_| \_\_____|
   7 .\" *
   8 .\" * Copyright (C) 1998 - 2015, 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_FOLLOWLOCATION 3 "February 03, 2016" "libcurl 7.59.0" "curl_easy_setopt options"
  24
  25 .SH NAME
  26 CURLOPT_FOLLOWLOCATION \- follow HTTP 3xx redirects
  27 .SH SYNOPSIS
  28 #include <curl/curl.h>
  29
  30 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FOLLOWLOCATION, long enable);
  31 .SH DESCRIPTION
  32 A long parameter set to 1 tells the library to follow any Location: header
  33 that the server sends as part of a HTTP header in a 3xx response. The
  34 Location: header can specify a relative or an absolute URL to follow.
  35
  36 libcurl will issue another request for the new URL and follow new Location:
  37 headers all the way until no more such headers are returned.
  38 \fICURLOPT_MAXREDIRS(3)\fP can be used to limit the number of redirects
  39 libcurl will follow.
  40
  41 libcurl limits what protocols it automatically follows to. The accepted
  42 protocols are set with \fICURLOPT_REDIR_PROTOCOLS(3)\fP. By default libcurl
  43 will allow all protocols on redirect except those disabled for security
  44 reasons: Since 7.19.4 FILE and SCP are disabled, and since 7.40.0 SMB and SMBS
  45 are also disabled.
  46
  47 When following a Location:, the 3xx response code that redirected it also
  48 dictates which request method it will use in the subsequent request: For 301,
  49 302 and 303 responses libcurl will switch method to GET unless
  50 \fICURLOPT_POSTREDIR(3)\fP instructs libcurl otherwise. All other 3xx codes
  51 will make libcurl send the same method again.
  52
  53 For users who think the existing location following is too naive, too simple
  54 or just lacks features, it is very easy to instead implement your own redirect
  55 follow logic with the use of \fIcurl_easy_getinfo(3)\fP's
  56 \fICURLINFO_REDIRECT_URL(3)\fP option instead of using
  57 \fICURLOPT_FOLLOWLOCATION(3)\fP.
  58 .SH DEFAULT
  59 0, disabled
  60 .SH PROTOCOLS
  61 HTTP(S)
  62 .SH EXAMPLE
  63 .nf
  64 CURL *curl = curl_easy_init();
  65 if(curl) {
  66   curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
  67
  68   /* example.com is redirected, so we tell libcurl to follow redirection */
  69   curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
  70
  71   curl_easy_perform(curl);
  72 }
  73 .fi
  74 .SH AVAILABILITY
  75 Along with HTTP
  76 .SH RETURN VALUE
  77 Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not.
  78 .SH "SEE ALSO"
  79 .BR CURLOPT_REDIR_PROTOCOLS "(3), " CURLOPT_PROTOCOLS "(3), "
  80 .BR CURLOPT_POSTREDIR "(3), "
  81 .BR CURLINFO_REDIRECT_URL "(3), ", CURLINFO_REDIRECT_COUNT "(3), "