1
2CURLOPT_URL(3) libcurl CURLOPT_URL(3)
3
4
5
7 CURLOPT_URL - URL for this transfer
8
10 #include <curl/curl.h>
11
12 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_URL, char *URL);
13
15 Pass in a pointer to the URL to work with. The parameter should be a
16 char * to a null-terminated string which must be URL-encoded in the
17 following format:
18
19 scheme://host:port/path
20
21 For a greater explanation of the format please see RFC 3986.
22
23 libcurl does not validate the syntax or use this variable until the
24 transfer is issued. Even if you set a crazy value here, curl_easy_se‐
25 topt(3) will still return CURLE_OK.
26
27 If the given URL is missing a scheme name (such as "http://" or
28 "ftp://" etc) then libcurl will make a guess based on the host. If the
29 outermost sub-domain name matches DICT, FTP, IMAP, LDAP, POP3 or SMTP
30 then that protocol will be used, otherwise HTTP will be used. Since
31 7.45.0 guessing can be disabled by setting a default protocol, see CUR‐
32 LOPT_DEFAULT_PROTOCOL(3) for details.
33
34 Should the protocol, either that specified by the scheme or deduced by
35 libcurl from the host name, not be supported by libcurl then CURLE_UN‐
36 SUPPORTED_PROTOCOL will be returned from either the curl_easy_per‐
37 form(3) or curl_multi_perform(3) functions when you call them. Use
38 curl_version_info(3) for detailed information of which protocols are
39 supported by the build of libcurl you are using.
40
41 CURLOPT_PROTOCOLS(3) can be used to limit what protocols libcurl will
42 use for this transfer, independent of what libcurl has been compiled to
43 support. That may be useful if you accept the URL from an external
44 source and want to limit the accessibility.
45
46 The CURLOPT_URL(3) string will be ignored if CURLOPT_CURLU(3) is set.
47
48 CURLOPT_URL(3) or CURLOPT_CURLU(3) must be set before a transfer is
49 started.
50
51 The application does not have to keep the string around after setting
52 this option.
53
55 The string pointed to in the CURLOPT_URL(3) argument is generally ex‐
56 pected to be a sequence of characters using an ASCII compatible encod‐
57 ing.
58
59 If libcurl is built with IDN support, the server name part of the URL
60 can use an "international name" by using the current encoding (accord‐
61 ing to locale) or UTF-8 (when winidn is used; or a Windows Unicode
62 build using libidn2).
63
64 If libcurl is built without IDN support, the server name is used ex‐
65 actly as specified when passed to the name resolver functions.
66
68 There is no default URL. If this option is not set, no transfer can be
69 performed.
70
72 Applications may at times find it convenient to allow users to specify
73 URLs for various purposes and that string would then end up fed to this
74 option.
75
76 Getting a URL from an external untrusted party will bring reasons for
77 several security concerns:
78
79 If you have an application that runs as or in a server application,
80 getting an unfiltered URL can easily trick your application to access a
81 local resource instead of a remote. Protecting yourself against local‐
82 host accesses is hard when accepting user provided URLs.
83
84 Such custom URLs can also access other ports than you planned as port
85 numbers are part of the regular URL format. The combination of a local
86 host and a custom port number can allow external users to play tricks
87 with your local services.
88
89 Accepting external URLs may also use other protocols than http:// or
90 other common ones. Restrict what accept with CURLOPT_PROTOCOLS(3).
91
92 User provided URLs can also be made to point to sites that redirect
93 further on (possibly to other protocols too). Consider your CUR‐
94 LOPT_FOLLOWLOCATION(3) and CURLOPT_REDIR_PROTOCOLS(3) settings.
95
97 All
98
100 CURL *curl = curl_easy_init();
101 if(curl) {
102 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
103
104 curl_easy_perform(curl);
105 }
106
108 POP3 and SMTP were added in 7.31.0
109
111 Returns CURLE_OK on success or CURLE_OUT_OF_MEMORY if there was insuf‐
112 ficient heap space.
113
114 Note that curl_easy_setopt(3) will not actually parse the given string
115 so given a bad URL, it will not be detected until curl_easy_perform(3)
116 or similar is called.
117
119 CURLOPT_VERBOSE(3), CURLOPT_PROTOCOLS(3), CURLOPT_FORBID_REUSE(3), CUR‐
120 LOPT_FRESH_CONNECT(3), curl_easy_perform(3), CURLINFO_REDIRECT_URL(3),
121 CURLOPT_PATH_AS_IS(3), CURLOPT_CURLU(3),
122
123
124
125ibcurl 8.2.1 June 25, 2023 CURLOPT_URL(3)