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