1--- 2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3SPDX-License-Identifier: curl 4Title: CURLOPT_FOLLOWLOCATION 5Section: 3 6Source: libcurl 7See-also: 8 - CURLINFO_REDIRECT_COUNT (3) 9 - CURLINFO_REDIRECT_URL (3) 10 - CURLOPT_POSTREDIR (3) 11 - CURLOPT_PROTOCOLS (3) 12 - CURLOPT_REDIR_PROTOCOLS (3) 13Protocol: 14 - HTTP 15--- 16 17# NAME 18 19CURLOPT_FOLLOWLOCATION - follow HTTP 3xx redirects 20 21# SYNOPSIS 22 23~~~c 24#include <curl/curl.h> 25 26CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FOLLOWLOCATION, long enable); 27~~~ 28 29# DESCRIPTION 30 31A long parameter set to 1 tells the library to follow any Location: header 32redirects that an HTTP server sends in a 30x response. The Location: header 33can specify a relative or an absolute URL to follow. 34 35libcurl issues another request for the new URL and follows subsequent new 36Location: redirects all the way until no more such headers are returned or the 37maximum limit is reached. CURLOPT_MAXREDIRS(3) is used to limit the 38number of redirects libcurl follows. 39 40libcurl restricts what protocols it automatically follow redirects to. The 41accepted target protocols are set with CURLOPT_REDIR_PROTOCOLS(3). By 42default libcurl allows HTTP, HTTPS, FTP and FTPS on redirects. 43 44When following a redirect, the specific 30x response code also dictates which 45request method libcurl uses in the subsequent request: For 301, 302 and 303 46responses libcurl switches method from POST to GET unless 47CURLOPT_POSTREDIR(3) instructs libcurl otherwise. All other redirect 48response codes make libcurl use the same method again. 49 50For users who think the existing location following is too naive, too simple 51or just lacks features, it is easy to instead implement your own redirect 52follow logic with the use of curl_easy_getinfo(3)'s 53CURLINFO_REDIRECT_URL(3) option instead of using 54CURLOPT_FOLLOWLOCATION(3). 55 56# NOTE 57 58Since libcurl changes method or not based on the specific HTTP response code, 59setting CURLOPT_CUSTOMREQUEST(3) while following redirects may change 60what libcurl would otherwise do and if not that carefully may even make it 61misbehave since CURLOPT_CUSTOMREQUEST(3) overrides the method libcurl 62would otherwise select internally. 63 64# DEFAULT 65 660, disabled 67 68# EXAMPLE 69 70~~~c 71int main(void) 72{ 73 CURL *curl = curl_easy_init(); 74 if(curl) { 75 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); 76 77 /* example.com is redirected, so we tell libcurl to follow redirection */ 78 curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); 79 80 curl_easy_perform(curl); 81 } 82} 83~~~ 84 85# AVAILABILITY 86 87Along with HTTP 88 89# RETURN VALUE 90 91Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. 92