docs/libcurl/opts/CURLOPT_URL.3

   1 .\" **************************************************************************
   2 .\" *                                  _   _ ____  _
   3 .\" *  Project                     ___| | | |  _ \| |
   4 .\" *                             / __| | | | |_) | |
   5 .\" *                            | (__| |_| |  _ <| |___
   6 .\" *                             \___|\___/|_| \_\_____|
   7 .\" *
   8 .\" * Copyright (C) 1998 - 2014, 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 http://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 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options"
  24 .SH NAME
  25 CURLOPT_URL \- provide the URL to use in the reqest
  26 .SH SYNOPSIS
  27 #include <curl/curl.h>
  28
  29 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_URL, char *URL);
  30 .SH DESCRIPTION
  31 Pass in a pointer to the \fIURL\fP to work with. The parameter should be a
  32 char * to a zero terminated string which must be URL-encoded in the following
  33 format:
  34
  35 scheme://host:port/path
  36
  37 For a greater explanation of the format please see RFC3986.
  38
  39 libcurl doesn't validate the syntax or use this variable until the transfer is
  40 issued. Even if you set a crazy value here, \fIcurl_easy_setopt(3)\fP will
  41 still return \fICURLE_OK\fP.
  42
  43 If the given URL lacks the scheme (such as "http://" or "ftp://" etc) then
  44 libcurl will attempt to resolve the protocol based on one of the following
  45 given host names: HTTP, FTP, DICT, LDAP, IMAP, POP3 or SMTP
  46
  47 Should the protocol, either that specified by the scheme or deduced by libcurl
  48 from the host name, not be supported by libcurl then
  49 \fICURLE_UNSUPPORTED_PROTOCOL\fP will be returned from either the
  50 \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP functions when you
  51 call them. Use \fIcurl_version_info(3)\fP for detailed information of which
  52 protocols are supported by the build of libcurl you are using.
  53
  54 The host part of the URL contains the address of the server that you want to
  55 connect to. This can be the fully qualified domain name of the server, the
  56 local network name of the machine on your network or the IP address of the
  57 server or machine represented by either an IPv4 or IPv6 address. For example:
  58
  59 http://www.example.com/
  60
  61 http://hostname/
  62
  63 http://192.168.0.1/
  64
  65 http://[2001:1890:1112:1::20]/
  66
  67 It is also possible to specify the user name, password and any supported login
  68 options as part of the host, for the following protocols, when connecting to
  69 servers that require authentication:
  70
  71 http://user:password@www.example.com
  72
  73 ftp://user:password@ftp.example.com
  74
  75 imap://user:password;options@mail.example.com
  76
  77 pop3://user:password;options@mail.example.com
  78
  79 smtp://user:password;options@mail.example.com
  80
  81 At present only IMAP, POP3 and SMTP support login options as part of the host.
  82 For more information about the login options in URL syntax please see RFC2384,
  83 RFC5092 and IETF draft draft-earhart-url-smtp-00.txt (Added in 7.31.0).
  84
  85 The port is optional and when not specified libcurl will use the default port
  86 based on the determined or specified protocol: 80 for HTTP, 21 for FTP and 25
  87 for SMTP, etc. The following examples show how to specify the port:
  88
  89 http://www.example.com:8080/ - This will connect to a web server using port
  90 8080 rather than 80.
  91
  92 smtp://mail.example.com:587/ - This will connect to a SMTP server on the
  93 alternative mail port.
  94
  95 The path part of the URL is protocol specific and whilst some examples are
  96 given below this list is not conclusive:
  97
  98 .IP HTTP
  99 The path part of a HTTP request specifies the file to retrieve and from what
 100 directory. If the directory is not specified then the web server's root
 101 directory is used. If the file is omitted then the default document will be
 102 retrieved for either the directory specified or the root directory. The exact
 103 resource returned for each URL is entirely dependent on the server's
 104 configuration.
 105
 106 http://www.example.com - This gets the main page from the web server.
 107
 108 http://www.example.com/index.html - This returns the main page by explicitly
 109 requesting it.
 110
 111 http://www.example.com/contactus/ - This returns the default document from
 112 the contactus directory.
 113
 114 .IP FTP
 115 The path part of an FTP request specifies the file to retrieve and from what
 116 directory. If the file part is omitted then libcurl downloads the directory
 117 listing for the directory specified. If the directory is omitted then
 118 the directory listing for the root / home directory will be returned.
 119
 120 ftp://ftp.example.com - This retrieves the directory listing for the root
 121 directory.
 122
 123 ftp://ftp.example.com/readme.txt - This downloads the file readme.txt from the
 124 root directory.
 125
 126 ftp://ftp.example.com/libcurl/readme.txt - This downloads readme.txt from the
 127 libcurl directory.
 128
 129 ftp://user:password@ftp.example.com/readme.txt - This retrieves the readme.txt
 130 file from the user's home directory. When a username and password is
 131 specified, everything that is specified in the path part is relative to the
 132 user's home directory. To retrieve files from the root directory or a
 133 directory underneath the root directory then the absolute path must be
 134 specified by prepending an additional forward slash to the beginning of the
 135 path.
 136
 137 ftp://user:password@ftp.example.com//readme.txt - This retrieves the readme.txt
 138 from the root directory when logging in as a specified user.
 139
 140 .IP SMTP
 141 The path part of a SMTP request specifies the host name to present during
 142 communication with the mail server. If the path is omitted then libcurl will
 143 attempt to resolve the local computer's host name. However, this may not
 144 return the fully qualified domain name that is required by some mail servers
 145 and specifying this path allows you to set an alternative name, such as
 146 your machine's fully qualified domain name, which you might have obtained
 147 from an external function such as gethostname or getaddrinfo.
 148
 149 smtp://mail.example.com - This connects to the mail server at example.com and
 150 sends your local computer's host name in the HELO / EHLO command.
 151
 152 smtp://mail.example.com/client.example.com - This will send client.example.com in
 153 the HELO / EHLO command to the mail server at example.com.
 154
 155 .IP POP3
 156 The path part of a POP3 request specifies the message ID to retrieve. If the
 157 ID is not specified then a list of waiting messages is returned instead.
 158
 159 pop3://user:password@mail.example.com - This lists the available messages for
 160 the user
 161
 162 pop3://user:password@mail.example.com/1 - This retrieves the first message for
 163 the user
 164
 165 .IP IMAP
 166 The path part of an IMAP request not only specifies the mailbox to list (Added
 167 in 7.30.0) or select, but can also be used to check the UIDVALIDITY of the
 168 mailbox, to specify the UID, SECTION (Added in 7.30.0) and PARTIAL octets
 169 (Added in 7.37.0) of the message to fetch and to specify what nessages to
 170 search for (Added in 7.37.0).
 171
 172 imap://user:password@mail.example.com - Performs a top level folder list
 173
 174 imap://user:password@mail.example.com/INBOX - Performs a folder list on the
 175 user's inbox
 176
 177 imap://user:password@mail.example.com/INBOX/;UID=1 - Selects the user's inbox
 178 and fetches message 1
 179
 180 imap://user:password@mail.example.com/INBOX;UIDVALIDITY=50/;UID=2 - Selects
 181 the user's inbox, checks the UIDVALIDITY of the mailbox is 50 and fetches
 182 message 2 if it is
 183
 184 imap://user:password@mail.example.com/INBOX/;UID=3/;SECTION=TEXT - Selects the
 185 user's inbox and fetches the text portial of message 3
 186
 187 imap://user:password@mail.example.com/INBOX/;UID=4/;PARTIAL=0.1024 - Selects
 188 the user's inbox and fetches the first 1024 octets of message 4
 189
 190 imap://user:password@mail.example.com/INBOX?NEW - Selects the user's inbox and
 191 checks for NEW messages
 192
 193 imap://user:password@mail.example.com/INBOX?SUBJECT%20shadows - Selects the
 194 user's inbox and searches for messages containing "shadows" in the subject
 195 line
 196
 197 For more information about the individual components of an IMAP URL please
 198 see RFC5092.
 199
 200 .IP SCP
 201 The path part of a SCP request specifies the file to retrieve and from what
 202 directory. The file part may not be omitted. The file is taken as an absolute
 203 path from the root directory on the server. To specify a path relative to the
 204 user's home directory on the server, prepend ~/ to the path portion.  If the
 205 user name is not embedded in the URL, it can be set with the
 206 \fICURLOPT_USERPWD(3)\fP or \fICURLOPT_USERNAME(3)\fP option.
 207
 208 scp://user@example.com/etc/issue - This specifies the file /etc/issue
 209
 210 scp://example.com/~/my-file - This specifies the file my-file in the
 211 user's home directory on the server
 212
 213 .IP SFTP
 214 The path part of a SFTP request specifies the file to retrieve and from what
 215 directory. If the file part is omitted then libcurl downloads the directory
 216 listing for the directory specified.  If the path ends in a / then a directory
 217 listing is returned instead of a file.  If the path is omitted entirely then
 218 the directory listing for the root / home directory will be returned.  If the
 219 user name is not embedded in the URL, it can be set with the
 220 \fICURLOPT_USERPWD(3)\fP or \fICURLOPT_USERNAME(3)\fP option.
 221
 222 sftp://user:password@example.com/etc/issue - This specifies the file
 223 /etc/issue
 224
 225 sftp://user@example.com/~/my-file - This specifies the file my-file in the
 226 user's home directory
 227
 228 sftp://ssh.example.com/~/Documents/ - This requests a directory listing
 229 of the Documents directory under the user's home directory
 230
 231 .IP LDAP
 232 The path part of a LDAP request can be used to specify the: Distinguished
 233 Name, Attributes, Scope, Filter and Extension for a LDAP search. Each field
 234 is separated by a question mark and when that field is not required an empty
 235 string with the question mark separator should be included.
 236
 237 ldap://ldap.example.com/o=My%20Organisation - This will perform a LDAP search
 238 with the DN as My Organisation.
 239
 240 ldap://ldap.example.com/o=My%20Organisation?postalAddress - This will perform
 241 the same search but will only return postalAddress attributes.
 242
 243 ldap://ldap.example.com/?rootDomainNamingContext - This specifies an empty DN
 244 and requests information about the rootDomainNamingContext attribute for an
 245 Active Directory server.
 246
 247 For more information about the individual components of a LDAP URL please
 248 see RFC4516.
 249 .IP RTMP
 250 There's no official URL spec for RTMP so libcurl uses the URL syntax supported
 251 by the underlying librtmp library. It has a syntax where it wants a
 252 traditional URL, followed by a space and a series of space-separated
 253 name=value pairs.
 254
 255 While space is not typically a "legal" letter, libcurl accepts them. When a
 256 user wants to pass in a '#' (hash) character it will be treated as a fragment
 257 and get cut off by libcurl if provided literally. You will instead have to
 258 escape it by providing it as backslash and its ASCII value in hexadecimal:
 259 "\\23".
 260
 261 .IP NOTES
 262 \fICURLOPT_URL(3)\fP is the only option that \fBmust\fP be set before a
 263 transfer is started.
 264
 265 \fICURLOPT_PROTOCOLS(3)\fP can be used to limit what protocols libcurl will
 266 use for this transfer, independent of what libcurl has been compiled to
 267 support. That may be useful if you accept the URL from an external source and
 268 want to limit the accessibility.
 269 .SH DEFAULT
 270 There is no default URL. If this option isn't set, no transfer can be
 271 performed.
 272 .SH PROTOCOLS
 273 All
 274 .SH EXAMPLE
 275 .nf
 276    curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
 277 .SH AVAILABILITY
 278 POP3 and SMTP added in 7.31.0
 279 .SH RETURN VALUE
 280 Returns CURLE_OK
 281 .SH "SEE ALSO"
 282 .BR CURLOPT_VERBOSE "(3), " CURLOPT_PROTOCOLS "(3), "
 283 .BR curl_easy_perform "(3)"