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       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       SMTP   The  path  part  of  a  SMTP  request specifies the host name to
148              present during communication with the mail server. If  the  path
149              is  omitted  then libcurl will attempt to resolve the local com‐
150              puter's host name. However, this may not return the fully quali‐
151              fied domain name that is required by some mail servers and spec‐
152              ifying this path allows you to set an alternative name, such  as
153              your machine's fully qualified domain name, which you might have
154              obtained from an external function such as gethostname or getad‐
155              drinfo.
156
157              smtp://mail.example.com  -  This  connects to the mail server at
158              example.com and sends your local computer's  host  name  in  the
159              HELO / EHLO command.
160
161              smtp://mail.example.com/client.example.com   -  This  will  send
162              client.example.com in the HELO / EHLO command to the mail server
163              at example.com.
164
165
166       POP3   The  path  part  of  a  POP3 request specifies the message ID to
167              retrieve. If the ID is not specified then a list of waiting mes‐
168              sages is returned instead.
169
170              pop3://user:password@mail.example.com - This lists the available
171              messages for the user
172
173              pop3://user:password@mail.example.com/1  -  This  retrieves  the
174              first message for the user
175
176
177       IMAP   The  path part of an IMAP request not only specifies the mailbox
178              to list (Added in 7.30.0) or select, but can  also  be  used  to
179              check  the  UIDVALIDITY of the mailbox, to specify the UID, SEC‐
180              TION (Added in 7.30.0) and PARTIAL octets (Added in  7.37.0)  of
181              the  message to fetch and to specify what messages to search for
182              (Added in 7.37.0).
183
184              imap://user:password@mail.example.com -  Performs  a  top  level
185              folder list
186
187              imap://user:password@mail.example.com/INBOX  - Performs a folder
188              list on the user's inbox
189
190              imap://user:password@mail.example.com/INBOX/;UID=1 - Selects the
191              user's inbox and fetches message with uid = 1
192
193              imap://user:password@mail.example.com/INBOX/;MAILINDEX=1       -
194              Selects the user's inbox and fetches the first  message  in  the
195              mail box
196
197              imap://user:password@mail.example.com/INBOX;UIDVALID‐
198              ITY=50/;UID=2 - Selects the user's inbox, checks the UIDVALIDITY
199              of the mailbox is 50 and fetches message 2 if it is
200
201              imap://user:password@mail.example.com/INBOX/;UID=3/;SECTION=TEXT
202              - Selects the user's inbox and fetches the text portion of  mes‐
203              sage 3
204
205              imap://user:password@mail.example.com/INBOX/;UID=4/;PAR‐
206              TIAL=0.1024 - Selects the user's inbox  and  fetches  the  first
207              1024 octets of message 4
208
209              imap://user:password@mail.example.com/INBOX?NEW  -  Selects  the
210              user's inbox and checks for NEW messages
211
212              imap://user:password@mail.example.com/INBOX?SUBJECT%20shadows  -
213              Selects  the  user's  inbox and searches for messages containing
214              "shadows" in the subject line
215
216              For more information about the individual components of an  IMAP
217              URL please see RFC5092.
218
219
220       SCP    The  path  part  of a SCP request specifies the file to retrieve
221              and from what directory. The file part may not be  omitted.  The
222              file is taken as an absolute path from the root directory on the
223              server. To specify a path relative to the user's home  directory
224              on the server, prepend ~/ to the path portion.  If the user name
225              is not embedded in the URL, it can be set with the CURLOPT_USER‐
226              PWD(3) or CURLOPT_USERNAME(3) option.
227
228              scp://user@example.com/etc/issue   -  This  specifies  the  file
229              /etc/issue
230
231              scp://example.com/~/my-file - This specifies the file my-file in
232              the user's home directory on the server
233
234
235       SFTP   The  path  part of a SFTP request specifies the file to retrieve
236              and from what directory.  If  the  file  part  is  omitted  then
237              libcurl downloads the directory listing for the directory speci‐
238              fied.  If the path ends in a  /  then  a  directory  listing  is
239              returned  instead  of  a  file.  If the path is omitted entirely
240              then the directory listing for the root / home directory will be
241              returned.   If  the user name is not embedded in the URL, it can
242              be  set  with  the  CURLOPT_USERPWD(3)  or   CURLOPT_USERNAME(3)
243              option.
244
245              sftp://user:password@example.com/etc/issue  - This specifies the
246              file /etc/issue
247
248              sftp://user@example.com/~/my-file - This specifies the file  my-
249              file in the user's home directory
250
251              sftp://ssh.example.com/~/Documents/  - This requests a directory
252              listing of the Documents directory under the user's home  direc‐
253              tory
254
255
256       SMB    The  path  part  of a SMB request specifies the file to retrieve
257              and from what share and directory or the share to upload to  and
258              as  such,  may not be omitted.  If the user name is not embedded
259              in the URL, it can be set with the  CURLOPT_USERPWD(3)  or  CUR‐
260              LOPT_USERNAME(3) option. If the user name is embedded in the URL
261              then it must contain the domain name and as such, the  backslash
262              must be URL encoded as %2f.
263
264              smb://server.example.com/files/issue  -  This specifies the file
265              "issue" located in the root of the "files" share
266
267              smb://server.example.com/files/ -T issue -  This  specifies  the
268              file "issue" will be uploaded to the root of the "files" share.
269
270
271       LDAP   The path part of a LDAP request can be used to specify the: Dis‐
272              tinguished Name, Attributes, Scope, Filter and Extension  for  a
273              LDAP search. Each field is separated by a question mark and when
274              that field is not required an empty  string  with  the  question
275              mark separator should be included.
276
277              ldap://ldap.example.com/o=My%20Organisation  - This will perform
278              a LDAP search with the DN as My Organisation.
279
280              ldap://ldap.example.com/o=My%20Organisation?postalAddress - This
281              will  perform the same search but will only return postalAddress
282              attributes.
283
284              ldap://ldap.example.com/?rootDomainNamingContext -  This  speci‐
285              fies  an empty DN and requests information about the rootDomain‐
286              NamingContext attribute for an Active Directory server.
287
288              For more information about the individual components of  a  LDAP
289              URL please see RFC4516.
290
291       RTMP   There's  no  official  URL spec for RTMP so libcurl uses the URL
292              syntax supported by the underlying librtmp  library.  It  has  a
293              syntax where it wants a traditional URL, followed by a space and
294              a series of space-separated name=value pairs.
295
296              While space is not typically a "legal" letter,  libcurl  accepts
297              them.  When  a  user  wants to pass in a '#' (hash) character it
298              will be treated as a fragment and get cut off by libcurl if pro‐
299              vided literally. You will instead have to escape it by providing
300              it as backslash and its ASCII value in hexadecimal: "\23".
301
302       The application does not have to keep the string around  after  setting
303       this option.
304

ENCODING

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

DEFAULT

318       There is no default URL. If this option isn't set, no transfer  can  be
319       performed.
320

SECURITY CONCERNS

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

PROTOCOLS

347       All
348

EXAMPLE

350       CURL *curl = curl_easy_init();
351       if(curl) {
352         curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
353
354         curl_easy_perform(curl);
355       }
356

AVAILABILITY

358       POP3 and SMTP were added in 7.31.0
359

RETURN VALUE

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

SEE ALSO

369       CURLOPT_VERBOSE(3), CURLOPT_PROTOCOLS(3), CURLOPT_FORBID_REUSE(3), CUR‐
370       LOPT_FRESH_CONNECT(3),  curl_easy_perform(3), CURLINFO_REDIRECT_URL(3),
371       CURLOPT_PATH_AS_IS(3), CURLOPT_CURLU(3),
372
373
374
375libcurl 7.64.0                 November 11, 2018                CURLOPT_URL(3)
Impressum