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_STR (3)
12  - CURLOPT_REDIR_PROTOCOLS_STR (3)
13  - CURLOPT_UNRESTRICTED_AUTH (3)
14Protocol:
15  - HTTP
16Added-in: 7.1
17---
18
19# NAME
20
21CURLOPT_FOLLOWLOCATION - follow HTTP 3xx redirects
22
23# SYNOPSIS
24
25~~~c
26#include <curl/curl.h>
27
28CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FOLLOWLOCATION, long enable);
29~~~
30
31# DESCRIPTION
32
33A long parameter set to 1 tells the library to follow any Location: header
34redirects that an HTTP server sends in a 30x response. The Location: header
35can specify a relative or an absolute URL to follow.
36
37libcurl issues another request for the new URL and follows subsequent new
38`Location:` redirects all the way until no more such headers are returned or
39the maximum limit is reached. CURLOPT_MAXREDIRS(3) is used to limit the number
40of redirects libcurl follows.
41
42libcurl restricts what protocols it automatically follow redirects to. The
43accepted target protocols are set with CURLOPT_REDIR_PROTOCOLS_STR(3). By
44default libcurl allows HTTP, HTTPS, FTP and FTPS on redirects.
45
46When following a redirect, the specific 30x response code also dictates which
47request method libcurl uses in the subsequent request: For 301, 302 and 303
48responses libcurl switches method from POST to GET unless CURLOPT_POSTREDIR(3)
49instructs libcurl otherwise. All other redirect response codes make libcurl
50use the same method again.
51
52For users who think the existing location following is too naive, too simple
53or just lacks features, it is easy to instead implement your own redirect
54follow logic with the use of curl_easy_getinfo(3)'s CURLINFO_REDIRECT_URL(3)
55option instead of using CURLOPT_FOLLOWLOCATION(3).
56
57By default, libcurl only sends `Authentication:` or explicitly set `Cookie:`
58headers to the initial host given in the original URL, to avoid leaking
59username + password to other sites. CURLOPT_UNRESTRICTED_AUTH(3) is provided
60to change that behavior.
61
62Due to the way HTTP works, almost any header can be made to contain data a
63client may not want to pass on to other servers than the initially intended
64host and for all other headers than the two mentioned above, there is no
65protection from this happening when libcurl is told to follow redirects.
66
67# NOTE
68
69Since libcurl changes method or not based on the specific HTTP response code,
70setting CURLOPT_CUSTOMREQUEST(3) while following redirects may change what
71libcurl would otherwise do and if not that carefully may even make it
72misbehave since CURLOPT_CUSTOMREQUEST(3) overrides the method libcurl would
73otherwise select internally.
74
75# DEFAULT
76
770, disabled
78
79# %PROTOCOLS%
80
81# EXAMPLE
82
83~~~c
84int main(void)
85{
86  CURL *curl = curl_easy_init();
87  if(curl) {
88    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
89
90    /* example.com is redirected, so we tell libcurl to follow redirection */
91    curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
92
93    curl_easy_perform(curl);
94  }
95}
96~~~
97
98# %AVAILABILITY%
99
100# RETURN VALUE
101
102Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not.
103