docs/libcurl/opts/CURLOPT_URL.3

   1 .\" **************************************************************************
   2 .\" *                                  _   _ ____  _
   3 .\" *  Project                     ___| | | |  _ \| |
   4 .\" *                             / __| | | | |_) | |
   5 .\" *                            | (__| |_| |  _ <| |___
   6 .\" *                             \___|\___/|_| \_\_____|
   7 .\" *
   8 .\" * Copyright (C) 1998 - 2016, Daniel Stenberg, <daniel@haxx.se>, et al.
   9 .\" *
  10 .\" * This software is licensed as described in the file COPYING, which
  11 .\" * you should have received as part of this distribution. The terms
  12 .\" * are also available at https://curl.haxx.se/docs/copyright.html.
  13 .\" *
  14 .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
  15 .\" * copies of the Software, and permit persons to whom the Software is
  16 .\" * furnished to do so, under the terms of the COPYING file.
  17 .\" *
  18 .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
  19 .\" * KIND, either express or implied.
  20 .\" *
  21 .\" **************************************************************************
  22 .\"
  23 .TH CURLOPT_URL 3 "December 21, 2016" "libcurl 7.59.0" "curl_easy_setopt options"
  24
  25 .SH NAME
  26 CURLOPT_URL \- provide the URL to use in the request
  27 .SH SYNOPSIS
  28 #include <curl/curl.h>
  29
  30 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_URL, char *URL);
  31 .SH DESCRIPTION
  32 Pass in a pointer to the \fIURL\fP to work with. The parameter should be a
  33 char * to a zero terminated string which must be URL-encoded in the following
  34 format:
  35
  36 scheme://host:port/path
  37
  38 For a greater explanation of the format please see RFC3986.
  39
  40 libcurl doesn't validate the syntax or use this variable until the transfer is
  41 issued. Even if you set a crazy value here, \fIcurl_easy_setopt(3)\fP will
  42 still return \fICURLE_OK\fP.
  43
  44 If the given URL is missing a scheme name (such as "http://" or "ftp://" etc)
  45 then libcurl will make a guess based on the host. If the outermost sub-domain
  46 name matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that protocol will be
  47 used, otherwise HTTP will be used. Since 7.45.0 guessing can be disabled by
  48 setting a default protocol, see \fICURLOPT_DEFAULT_PROTOCOL(3)\fP for details.
  49
  50 Should the protocol, either that specified by the scheme or deduced by libcurl
  51 from the host name, not be supported by libcurl then
  52 \fICURLE_UNSUPPORTED_PROTOCOL\fP will be returned from either the
  53 \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP functions when you
  54 call them. Use \fIcurl_version_info(3)\fP for detailed information of which
  55 protocols are supported by the build of libcurl you are using.
  56
  57 \fICURLOPT_PROTOCOLS(3)\fP can be used to limit what protocols libcurl will
  58 use for this transfer, independent of what libcurl has been compiled to
  59 support. That may be useful if you accept the URL from an external source and
  60 want to limit the accessibility.
  61
  62 \fICURLOPT_URL(3)\fP is the only option that \fBmust\fP be set before a
  63 transfer is started.
  64
  65 The host part of the URL contains the address of the server that you want to
  66 connect to. This can be the fully qualified domain name of the server, the
  67 local network name of the machine on your network or the IP address of the
  68 server or machine represented by either an IPv4 or IPv6 address. For example:
  69
  70 http://www.example.com/
  71
  72 http://hostname/
  73
  74 http://192.168.0.1/
  75
  76 http://[2001:1890:1112:1::20]/
  77
  78 It is also possible to specify the user name, password and any supported login
  79 options as part of the host, for the following protocols, when connecting to
  80 servers that require authentication:
  81
  82 http://user:password@www.example.com
  83
  84 ftp://user:password@ftp.example.com
  85
  86 smb://domain%2fuser:password@server.example.com
  87
  88 imap://user:password;options@mail.example.com
  89
  90 pop3://user:password;options@mail.example.com
  91
  92 smtp://user:password;options@mail.example.com
  93
  94 At present only IMAP, POP3 and SMTP support login options as part of the host.
  95 For more information about the login options in URL syntax please see RFC2384,
  96 RFC5092 and IETF draft draft-earhart-url-smtp-00.txt (Added in 7.31.0).
  97
  98 The port is optional and when not specified libcurl will use the default port
  99 based on the determined or specified protocol: 80 for HTTP, 21 for FTP and 25
 100 for SMTP, etc. The following examples show how to specify the port:
 101
 102 http://www.example.com:8080/ - This will connect to a web server using port
 103 8080 rather than 80.
 104
 105 smtp://mail.example.com:587/ - This will connect to a SMTP server on the
 106 alternative mail port.
 107
 108 The path part of the URL is protocol specific and whilst some examples are
 109 given below this list is not conclusive:
 110
 111 .IP HTTP
 112 The path part of a HTTP request specifies the file to retrieve and from what
 113 directory. If the directory is not specified then the web server's root
 114 directory is used. If the file is omitted then the default document will be
 115 retrieved for either the directory specified or the root directory. The exact
 116 resource returned for each URL is entirely dependent on the server's
 117 configuration.
 118
 119 http://www.example.com - This gets the main page from the web server.
 120
 121 http://www.example.com/index.html - This returns the main page by explicitly
 122 requesting it.
 123
 124 http://www.example.com/contactus/ - This returns the default document from
 125 the contactus directory.
 126
 127 .IP FTP
 128 The path part of an FTP request specifies the file to retrieve and from what
 129 directory. If the file part is omitted then libcurl downloads the directory
 130 listing for the directory specified. If the directory is omitted then
 131 the directory listing for the root / home directory will be returned.
 132
 133 ftp://ftp.example.com - This retrieves the directory listing for the root
 134 directory.
 135
 136 ftp://ftp.example.com/readme.txt - This downloads the file readme.txt from the
 137 root directory.
 138
 139 ftp://ftp.example.com/libcurl/readme.txt - This downloads readme.txt from the
 140 libcurl directory.
 141
 142 ftp://user:password@ftp.example.com/readme.txt - This retrieves the readme.txt
 143 file from the user's home directory. When a username and password is
 144 specified, everything that is specified in the path part is relative to the
 145 user's home directory. To retrieve files from the root directory or a
 146 directory underneath the root directory then the absolute path must be
 147 specified by prepending an additional forward slash to the beginning of the
 148 path.
 149
 150 ftp://user:password@ftp.example.com//readme.txt - This retrieves the readme.txt
 151 from the root directory when logging in as a specified user.
 152
 153 .IP SMTP
 154 The path part of a SMTP request specifies the host name to present during
 155 communication with the mail server. If the path is omitted then libcurl will
 156 attempt to resolve the local computer's host name. However, this may not
 157 return the fully qualified domain name that is required by some mail servers
 158 and specifying this path allows you to set an alternative name, such as
 159 your machine's fully qualified domain name, which you might have obtained
 160 from an external function such as gethostname or getaddrinfo.
 161
 162 smtp://mail.example.com - This connects to the mail server at example.com and
 163 sends your local computer's host name in the HELO / EHLO command.
 164
 165 smtp://mail.example.com/client.example.com - This will send client.example.com in
 166 the HELO / EHLO command to the mail server at example.com.
 167
 168 .IP POP3
 169 The path part of a POP3 request specifies the message ID to retrieve. If the
 170 ID is not specified then a list of waiting messages is returned instead.
 171
 172 pop3://user:password@mail.example.com - This lists the available messages for
 173 the user
 174
 175 pop3://user:password@mail.example.com/1 - This retrieves the first message for
 176 the user
 177
 178 .IP IMAP
 179 The path part of an IMAP request not only specifies the mailbox to list (Added
 180 in 7.30.0) or select, but can also be used to check the UIDVALIDITY of the
 181 mailbox, to specify the UID, SECTION (Added in 7.30.0) and PARTIAL octets
 182 (Added in 7.37.0) of the message to fetch and to specify what messages to
 183 search for (Added in 7.37.0).
 184
 185 imap://user:password@mail.example.com - Performs a top level folder list
 186
 187 imap://user:password@mail.example.com/INBOX - Performs a folder list on the
 188 user's inbox
 189
 190 imap://user:password@mail.example.com/INBOX/;UID=1 - Selects the user's inbox
 191 and fetches message 1
 192
 193 imap://user:password@mail.example.com/INBOX;UIDVALIDITY=50/;UID=2 - Selects
 194 the user's inbox, checks the UIDVALIDITY of the mailbox is 50 and fetches
 195 message 2 if it is
 196
 197 imap://user:password@mail.example.com/INBOX/;UID=3/;SECTION=TEXT - Selects the
 198 user's inbox and fetches the text portion of message 3
 199
 200 imap://user:password@mail.example.com/INBOX/;UID=4/;PARTIAL=0.1024 - Selects
 201 the user's inbox and fetches the first 1024 octets of message 4
 202
 203 imap://user:password@mail.example.com/INBOX?NEW - Selects the user's inbox and
 204 checks for NEW messages
 205
 206 imap://user:password@mail.example.com/INBOX?SUBJECT%20shadows - Selects the
 207 user's inbox and searches for messages containing "shadows" in the subject
 208 line
 209
 210 For more information about the individual components of an IMAP URL please
 211 see RFC5092.
 212
 213 .IP SCP
 214 The path part of a SCP request specifies the file to retrieve and from what
 215 directory. The file part may not be omitted. The file is taken as an absolute
 216 path from the root directory on the server. To specify a path relative to the
 217 user's home directory on the server, prepend ~/ to the path portion.  If the
 218 user name is not embedded in the URL, it can be set with the
 219 \fICURLOPT_USERPWD(3)\fP or \fICURLOPT_USERNAME(3)\fP option.
 220
 221 scp://user@example.com/etc/issue - This specifies the file /etc/issue
 222
 223 scp://example.com/~/my-file - This specifies the file my-file in the
 224 user's home directory on the server
 225
 226 .IP SFTP
 227 The path part of a SFTP request specifies the file to retrieve and from what
 228 directory. If the file part is omitted then libcurl downloads the directory
 229 listing for the directory specified.  If the path ends in a / then a directory
 230 listing is returned instead of a file.  If the path is omitted entirely then
 231 the directory listing for the root / home directory will be returned.  If the
 232 user name is not embedded in the URL, it can be set with the
 233 \fICURLOPT_USERPWD(3)\fP or \fICURLOPT_USERNAME(3)\fP option.
 234
 235 sftp://user:password@example.com/etc/issue - This specifies the file
 236 /etc/issue
 237
 238 sftp://user@example.com/~/my-file - This specifies the file my-file in the
 239 user's home directory
 240
 241 sftp://ssh.example.com/~/Documents/ - This requests a directory listing
 242 of the Documents directory under the user's home directory
 243
 244 .IP SMB
 245 The path part of a SMB request specifies the file to retrieve and from what
 246 share and directory or the share to upload to and as such, may not be omitted.
 247 If the user name is not embedded in the URL, it can be set with the
 248 \fICURLOPT_USERPWD(3)\fP or \fICURLOPT_USERNAME(3)\fP option. If the user name
 249 is embedded in the URL then it must contain the domain name and as such, the
 250 backslash must be URL encoded as %2f.
 251
 252 smb://server.example.com/files/issue - This specifies the file "issue" located
 253 in the root of the "files" share
 254
 255 smb://server.example.com/files/ -T issue - This specifies the file "issue" will
 256 be uploaded to the root of the "files" share.
 257
 258 .IP LDAP
 259 The path part of a LDAP request can be used to specify the: Distinguished
 260 Name, Attributes, Scope, Filter and Extension for a LDAP search. Each field
 261 is separated by a question mark and when that field is not required an empty
 262 string with the question mark separator should be included.
 263
 264 ldap://ldap.example.com/o=My%20Organisation - This will perform a LDAP search
 265 with the DN as My Organisation.
 266
 267 ldap://ldap.example.com/o=My%20Organisation?postalAddress - This will perform
 268 the same search but will only return postalAddress attributes.
 269
 270 ldap://ldap.example.com/?rootDomainNamingContext - This specifies an empty DN
 271 and requests information about the rootDomainNamingContext attribute for an
 272 Active Directory server.
 273
 274 For more information about the individual components of a LDAP URL please
 275 see RFC4516.
 276 .IP RTMP
 277 There's no official URL spec for RTMP so libcurl uses the URL syntax supported
 278 by the underlying librtmp library. It has a syntax where it wants a
 279 traditional URL, followed by a space and a series of space-separated
 280 name=value pairs.
 281
 282 While space is not typically a "legal" letter, libcurl accepts them. When a
 283 user wants to pass in a '#' (hash) character it will be treated as a fragment
 284 and get cut off by libcurl if provided literally. You will instead have to
 285 escape it by providing it as backslash and its ASCII value in hexadecimal:
 286 "\\23".
 287
 288 The application does not have to keep the string around after setting this
 289 option.
 290 .SH DEFAULT
 291 There is no default URL. If this option isn't set, no transfer can be
 292 performed.
 293 .SH SECURITY CONCERNS
 294 Applications may at times find it convenient to allow users to specify URLs
 295 for various purposes and that string would then end up fed to this option.
 296
 297 Getting a URL from an external untrusted party will bring reasons for several
 298 security concerns:
 299
 300 If you have an application that runs as or in a server application, getting an
 301 unfiltered URL can easily trick your application to access a local resource
 302 instead of a remote. Protecting yourself against localhost accesses is very
 303 hard when accepting user provided URLs.
 304
 305 Such custom URLs can also access other ports than you planned as port numbers
 306 are part of the regular URL format. The combination of a local host and a
 307 custom port number can allow external users to play tricks with your local
 308 services.
 309
 310 Accepting external URLs may also use other protocols than http:// or other
 311 common ones. Restrict what accept with \fICURLOPT_PROTOCOLS(3)\fP.
 312
 313 User provided URLs can also be made to point to sites that redirect further on
 314 (possibly to other protocols too). Consider your
 315 \fICURLOPT_FOLLOWLOCATION(3)\fP and \fICURLOPT_REDIR_PROTOCOLS(3)\fP settings.
 316 .SH PROTOCOLS
 317 All
 318 .SH EXAMPLE
 319 .nf
 320 CURL *curl = curl_easy_init();
 321 if(curl) {
 322   curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
 323
 324   curl_easy_perform(curl);
 325 }
 326 .fi
 327 .SH AVAILABILITY
 328 POP3 and SMTP were added in 7.31.0
 329 .SH RETURN VALUE
 330 Returns CURLE_OK on success or CURLE_OUT_OF_MEMORY if there was insufficient
 331 heap space.
 332
 333 Note that \fIcurl_easy_setopt(3)\fP won't actually parse the given string so
 334 given a bad URL, it will not be detected until \fIcurl_easy_perform(3)\fP or
 335 similar is called.
 336 .SH "SEE ALSO"
 337 .BR CURLOPT_VERBOSE "(3), " CURLOPT_PROTOCOLS "(3), "
 338 .BR CURLOPT_FORBID_REUSE "(3), " CURLOPT_FRESH_CONNECT "(3), "
 339 .BR curl_easy_perform "(3), "
 340 .BR CURLINFO_REDIRECT_URL "(3), " CURLOPT_PATH_AS_IS "(3), "