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

ENCODING

300       The  string  pointed  to  in  the  CURLOPT_URL(3) argument is generally
301       expected to be a sequence  of  characters  using  an  ASCII  compatible
302       encoding.
303
304       If  libcurl  is built with IDN support, the server name part of the URL
305       can use an "international name" by using the current encoding  (accord‐
306       ing to locale) or UTF-8 (when winidn is used).
307
308       If  libcurl  is  built  without  IDN  support,  the server name is used
309       exactly as specified when passed to the name resolver functions.
310

DEFAULT

312       There is no default URL. If this option isn't set, no transfer  can  be
313       performed.
314

SECURITY CONCERNS

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

PROTOCOLS

341       All
342

EXAMPLE

344       CURL *curl = curl_easy_init();
345       if(curl) {
346         curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
347
348         curl_easy_perform(curl);
349       }
350

AVAILABILITY

352       POP3 and SMTP were added in 7.31.0
353

RETURN VALUE

355       Returns  CURLE_OK on success or CURLE_OUT_OF_MEMORY if there was insuf‐
356       ficient heap space.
357
358       Note that curl_easy_setopt(3) won't actually parse the given string  so
359       given  a bad URL, it will not be detected until curl_easy_perform(3) or
360       similar is called.
361

SEE ALSO

363       CURLOPT_VERBOSE(3), CURLOPT_PROTOCOLS(3), CURLOPT_FORBID_REUSE(3), CUR‐
364       LOPT_FRESH_CONNECT(3),  curl_easy_perform(3), CURLINFO_REDIRECT_URL(3),
365       CURLOPT_PATH_AS_IS(3),
366
367
368
369libcurl 7.61.1                   July 24, 2018                  CURLOPT_URL(3)
Impressum