1CURLOPT_URL(3)             curl_easy_setopt options             CURLOPT_URL(3)
2
3
4

NAME

6       CURLOPT_URL - provide the URL to use in the request
7

SYNOPSIS

9       #include <curl/curl.h>
10
11       CURLcode curl_easy_setopt(CURL *handle, CURLOPT_URL, char *URL);
12

DESCRIPTION

14       Pass  in  a  pointer to the URL to work with. The parameter should be a
15       char * to a null-terminated string which must  be  URL-encoded  in  the
16       following format:
17
18       scheme://host:port/path
19
20       For a greater explanation of the format please see RFC3986.
21
22       libcurl  doesn't  validate  the  syntax  or use this variable until the
23       transfer  is  issued.  Even  if   you   set   a   crazy   value   here,
24       curl_easy_setopt(3) will still return CURLE_OK.
25
26       If  the  given  URL  is  missing  a  scheme  name (such as "http://" or
27       "ftp://" etc) then libcurl will make a guess based on the host. If  the
28       outermost  sub-domain  name matches DICT, FTP, IMAP, LDAP, POP3 or SMTP
29       then that protocol will be used, otherwise HTTP  will  be  used.  Since
30       7.45.0 guessing can be disabled by setting a default protocol, see CUR‐
31       LOPT_DEFAULT_PROTOCOL(3) for details.
32
33       Should the protocol, either that specified by the scheme or deduced  by
34       libcurl   from  the  host  name,  not  be  supported  by  libcurl  then
35       CURLE_UNSUPPORTED_PROTOCOL   will   be   returned   from   either   the
36       curl_easy_perform(3)  or  curl_multi_perform(3) functions when you call
37       them. Use curl_version_info(3) for detailed information of which proto‐
38       cols are supported by the build of libcurl you are using.
39
40       CURLOPT_PROTOCOLS(3)  can  be used to limit what protocols libcurl will
41       use for this transfer, independent of what libcurl has been compiled to
42       support.  That  may  be  useful  if you accept the URL from an external
43       source and want to limit the accessibility.
44
45       The CURLOPT_URL(3) string will be ignored if CURLOPT_CURLU(3) is set.
46
47       CURLOPT_URL(3) or CURLOPT_CURLU(3) must be set  before  a  transfer  is
48       started.
49
50       The  host  part  of the URL contains the address of the server that you
51       want to connect to. This can be the fully qualified domain name of  the
52       server, the local network name of the machine on your network or the IP
53       address of the server or machine represented by either an IPv4 or  IPv6
54       address. For example:
55
56       http://www.example.com/
57
58       http://hostname/
59
60       http://192.168.0.1/
61
62       http://[2001:1890:1112:1::20]/
63
64       It  is  also  possible  to specify the user name, password and any sup‐
65       ported login options as part of the host, for the following  protocols,
66       when connecting to servers that require authentication:
67
68       http://user:password@www.example.com
69
70       ftp://user:password@ftp.example.com
71
72       smb://domain%2fuser:password@server.example.com
73
74       imap://user:password;options@mail.example.com
75
76       pop3://user:password;options@mail.example.com
77
78       smtp://user:password;options@mail.example.com
79
80       At  present  only  IMAP, POP3 and SMTP support login options as part of
81       the host.  For more information about the login options in  URL  syntax
82       please   see   RFC2384,   RFC5092  and  IETF  draft  draft-earhart-url-
83       smtp-00.txt (Added in 7.31.0).
84
85       The port is optional and  when  not  specified  libcurl  will  use  the
86       default  port  based  on  the  determined or specified protocol: 80 for
87       HTTP, 21 for FTP and 25 for SMTP, etc. The following examples show  how
88       to specify the port:
89
90       http://www.example.com:8080/  - This will connect to a web server using
91       port 8080 rather than 80.
92
93       smtp://mail.example.com:587/ - This will connect to a  SMTP  server  on
94       the alternative mail port.
95
96       The  path part of the URL is protocol specific and whilst some examples
97       are given below this list is not conclusive:
98
99
100       HTTP   The path part of an HTTP request specifies the file to  retrieve
101              and  from what directory. If the directory is not specified then
102              the web server's root directory is used. If the file is  omitted
103              then  the  default  document  will  be  retrieved for either the
104              directory specified or the root directory.  The  exact  resource
105              returned for each URL is entirely dependent on the server's con‐
106              figuration.
107
108              http://www.example.com - This gets the main page  from  the  web
109              server.
110
111              http://www.example.com/index.html  -  This returns the main page
112              by explicitly requesting it.
113
114              http://www.example.com/contactus/ -  This  returns  the  default
115              document from the contactus directory.
116
117
118       FTP    The  path  part of an FTP request specifies the file to retrieve
119              and from what directory.  If  the  file  part  is  omitted  then
120              libcurl downloads the directory listing for the directory speci‐
121              fied. If the directory is omitted then the directory listing for
122              the root / home directory will be returned.
123
124              ftp://ftp.example.com - This retrieves the directory listing for
125              the root directory.
126
127              ftp://ftp.example.com/readme.txt  -  This  downloads  the   file
128              readme.txt from the root directory.
129
130              ftp://ftp.example.com/libcurl/readme.txt    -   This   downloads
131              readme.txt from the libcurl directory.
132
133              ftp://user:password@ftp.example.com/readme.txt - This  retrieves
134              the readme.txt file from the user's home directory. When a user‐
135              name and password is specified, everything that is specified  in
136              the  path  part  is  relative  to  the user's home directory. To
137              retrieve files from the root directory or a directory underneath
138              the  root  directory then the absolute path must be specified by
139              prepending an additional forward slash to the beginning  of  the
140              path.
141
142              ftp://user:password@ftp.example.com//readme.txt - This retrieves
143              the readme.txt from the root directory  when  logging  in  as  a
144              specified user.
145
146
147       FILE   When  a  FILE://  URL  is accessed on Windows systems, it can be
148              crafted in a way so  that  Windows  attempts  to  connect  to  a
149              (remote) machine when curl wants to read or write such a path.
150
151       SMTP   The  path  part  of  a  SMTP  request specifies the host name to
152              present during communication with the mail server. If  the  path
153              is  omitted  then libcurl will attempt to resolve the local com‐
154              puter's host name. However, this may not return the fully quali‐
155              fied domain name that is required by some mail servers and spec‐
156              ifying this path allows you to set an alternative name, such  as
157              your machine's fully qualified domain name, which you might have
158              obtained from an external function such as gethostname or getad‐
159              drinfo.
160
161              smtp://mail.example.com  -  This  connects to the mail server at
162              example.com and sends your local computer's  host  name  in  the
163              HELO / EHLO command.
164
165              smtp://mail.example.com/client.example.com   -  This  will  send
166              client.example.com in the HELO / EHLO command to the mail server
167              at example.com.
168
169
170       POP3   The  path  part  of  a  POP3 request specifies the message ID to
171              retrieve. If the ID is not specified then a list of waiting mes‐
172              sages is returned instead.
173
174              pop3://user:password@mail.example.com - This lists the available
175              messages for the user
176
177              pop3://user:password@mail.example.com/1  -  This  retrieves  the
178              first message for the user
179
180
181       IMAP   The  path part of an IMAP request not only specifies the mailbox
182              to list (Added in 7.30.0) or select, but can  also  be  used  to
183              check  the  UIDVALIDITY of the mailbox, to specify the UID, SEC‐
184              TION (Added in 7.30.0) and PARTIAL octets (Added in  7.37.0)  of
185              the  message to fetch and to specify what messages to search for
186              (Added in 7.37.0).
187
188              imap://user:password@mail.example.com -  Performs  a  top  level
189              folder list
190
191              imap://user:password@mail.example.com/INBOX  - Performs a folder
192              list on the user's inbox
193
194              imap://user:password@mail.example.com/INBOX/;UID=1 - Selects the
195              user's inbox and fetches message with uid = 1
196
197              imap://user:password@mail.example.com/INBOX/;MAILINDEX=1       -
198              Selects the user's inbox and fetches the first  message  in  the
199              mail box
200
201              imap://user:password@mail.example.com/INBOX;UIDVALID‐
202              ITY=50/;UID=2 - Selects the user's inbox, checks the UIDVALIDITY
203              of the mailbox is 50 and fetches message 2 if it is
204
205              imap://user:password@mail.example.com/INBOX/;UID=3/;SECTION=TEXT
206              - Selects the user's inbox and fetches the text portion of  mes‐
207              sage 3
208
209              imap://user:password@mail.example.com/INBOX/;UID=4/;PAR‐
210              TIAL=0.1024 - Selects the user's inbox  and  fetches  the  first
211              1024 octets of message 4
212
213              imap://user:password@mail.example.com/INBOX?NEW  -  Selects  the
214              user's inbox and checks for NEW messages
215
216              imap://user:password@mail.example.com/INBOX?SUBJECT%20shadows  -
217              Selects  the  user's  inbox and searches for messages containing
218              "shadows" in the subject line
219
220              For more information about the individual components of an  IMAP
221              URL please see RFC5092.
222
223
224       SCP    The  path  part  of a SCP request specifies the file to retrieve
225              and from what directory. The file part may not be  omitted.  The
226              file is taken as an absolute path from the root directory on the
227              server. To specify a path relative to the user's home  directory
228              on the server, prepend ~/ to the path portion.  If the user name
229              is not embedded in the URL, it can be set with the CURLOPT_USER‐
230              PWD(3) or CURLOPT_USERNAME(3) option.
231
232              scp://user@example.com/etc/issue   -  This  specifies  the  file
233              /etc/issue
234
235              scp://example.com/~/my-file - This specifies the file my-file in
236              the user's home directory on the server
237
238       SFTP   The  path  part of a SFTP request specifies the file to retrieve
239              and from what directory.  If  the  file  part  is  omitted  then
240              libcurl downloads the directory listing for the directory speci‐
241              fied.  If the path ends in a  /  then  a  directory  listing  is
242              returned  instead  of  a  file.  If the path is omitted entirely
243              then the directory listing for the root / home directory will be
244              returned.   If  the user name is not embedded in the URL, it can
245              be  set  with  the  CURLOPT_USERPWD(3)  or   CURLOPT_USERNAME(3)
246              option.
247
248              sftp://user:password@example.com/etc/issue  - This specifies the
249              file /etc/issue
250
251              sftp://user@example.com/~/my-file - This specifies the file  my-
252              file in the user's home directory
253
254              sftp://ssh.example.com/~/Documents/  - This requests a directory
255              listing of the Documents directory under the user's home  direc‐
256              tory
257
258
259       SMB    The  path  part  of a SMB request specifies the file to retrieve
260              and from what share and directory or the share to upload to  and
261              as  such,  may not be omitted.  If the user name is not embedded
262              in the URL, it can be set with the  CURLOPT_USERPWD(3)  or  CUR‐
263              LOPT_USERNAME(3) option. If the user name is embedded in the URL
264              then it must contain the domain name and as such, the  backslash
265              must be URL encoded as %2f.
266
267              smb://server.example.com/files/issue  -  This specifies the file
268              "issue" located in the root of the "files" share
269
270              smb://server.example.com/files/ -T issue -  This  specifies  the
271              file "issue" will be uploaded to the root of the "files" share.
272
273              curl supports SMB version 1 (only)
274
275       LDAP   The path part of a LDAP request can be used to specify the: Dis‐
276              tinguished Name, Attributes, Scope, Filter and Extension  for  a
277              LDAP search. Each field is separated by a question mark and when
278              that field is not required an empty  string  with  the  question
279              mark separator should be included.
280
281              ldap://ldap.example.com/o=My%20Organisation  - This will perform
282              a LDAP search with the DN as My Organisation.
283
284              ldap://ldap.example.com/o=My%20Organisation?postalAddress - This
285              will  perform the same search but will only return postalAddress
286              attributes.
287
288              ldap://ldap.example.com/?rootDomainNamingContext -  This  speci‐
289              fies  an empty DN and requests information about the rootDomain‐
290              NamingContext attribute for an Active Directory server.
291
292              For more information about the individual components of  a  LDAP
293              URL please see RFC4516.
294
295       RTMP   There's  no  official  URL spec for RTMP so libcurl uses the URL
296              syntax supported by the underlying librtmp  library.  It  has  a
297              syntax where it wants a traditional URL, followed by a space and
298              a series of space-separated name=value pairs.
299
300              While space is not typically a "legal" letter,  libcurl  accepts
301              them.  When  a  user  wants to pass in a '#' (hash) character it
302              will be treated as a fragment and get cut off by libcurl if pro‐
303              vided literally. You will instead have to escape it by providing
304              it as backslash and its ASCII value in hexadecimal: "\23".
305
306       The application does not have to keep the string around  after  setting
307       this option.
308

ENCODING

310       The  string  pointed  to  in  the  CURLOPT_URL(3) argument is generally
311       expected to be a sequence  of  characters  using  an  ASCII  compatible
312       encoding.
313
314       If  libcurl  is built with IDN support, the server name part of the URL
315       can use an "international name" by using the current encoding  (accord‐
316       ing to locale) or UTF-8 (when winidn is used).
317
318       If  libcurl  is  built  without  IDN  support,  the server name is used
319       exactly as specified when passed to the name resolver functions.
320

DEFAULT

322       There is no default URL. If this option isn't set, no transfer  can  be
323       performed.
324

SECURITY CONCERNS

326       Applications  may at times find it convenient to allow users to specify
327       URLs for various purposes and that string would then end up fed to this
328       option.
329
330       Getting  a  URL from an external untrusted party will bring reasons for
331       several security concerns:
332
333       If you have an application that runs as or  in  a  server  application,
334       getting an unfiltered URL can easily trick your application to access a
335       local resource instead of a remote. Protecting yourself against  local‐
336       host accesses is very hard when accepting user provided URLs.
337
338       Such  custom  URLs can also access other ports than you planned as port
339       numbers are part of the regular URL format. The combination of a  local
340       host  and  a custom port number can allow external users to play tricks
341       with your local services.
342
343       Accepting external URLs may also use other protocols  than  http://  or
344       other common ones. Restrict what accept with CURLOPT_PROTOCOLS(3).
345
346       User  provided  URLs  can  also be made to point to sites that redirect
347       further on (possibly  to  other  protocols  too).  Consider  your  CUR‐
348       LOPT_FOLLOWLOCATION(3) and CURLOPT_REDIR_PROTOCOLS(3) settings.
349

PROTOCOLS

351       All
352

EXAMPLE

354       CURL *curl = curl_easy_init();
355       if(curl) {
356         curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
357
358         curl_easy_perform(curl);
359       }
360

AVAILABILITY

362       POP3 and SMTP were added in 7.31.0
363

RETURN VALUE

365       Returns  CURLE_OK on success or CURLE_OUT_OF_MEMORY if there was insuf‐
366       ficient heap space.
367
368       Note that curl_easy_setopt(3) won't actually parse the given string  so
369       given  a bad URL, it will not be detected until curl_easy_perform(3) or
370       similar is called.
371

SEE ALSO

373       CURLOPT_VERBOSE(3), CURLOPT_PROTOCOLS(3), CURLOPT_FORBID_REUSE(3), CUR‐
374       LOPT_FRESH_CONNECT(3),  curl_easy_perform(3), CURLINFO_REDIRECT_URL(3),
375       CURLOPT_PATH_AS_IS(3), CURLOPT_CURLU(3),
376
377
378
379libcurl 7.71.1                   June 25, 2020                  CURLOPT_URL(3)
Impressum