Annotation of embedaddon/curl/docs/libcurl/opts/CURLOPT_URL.3, revision 1.1
1.1 ! misho 1: .\" **************************************************************************
! 2: .\" * _ _ ____ _
! 3: .\" * Project ___| | | | _ \| |
! 4: .\" * / __| | | | |_) | |
! 5: .\" * | (__| |_| | _ <| |___
! 6: .\" * \___|\___/|_| \_\_____|
! 7: .\" *
! 8: .\" * Copyright (C) 1998 - 2020, 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 "March 09, 2020" "libcurl 7.70.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: The \fICURLOPT_URL(3)\fP string will be ignored if \fICURLOPT_CURLU(3)\fP is
! 63: set.
! 64:
! 65: \fICURLOPT_URL(3)\fP or \fICURLOPT_CURLU(3)\fP \fBmust\fP be set before a
! 66: transfer is started.
! 67:
! 68: The host part of the URL contains the address of the server that you want to
! 69: connect to. This can be the fully qualified domain name of the server, the
! 70: local network name of the machine on your network or the IP address of the
! 71: server or machine represented by either an IPv4 or IPv6 address. For example:
! 72:
! 73: http://www.example.com/
! 74:
! 75: http://hostname/
! 76:
! 77: http://192.168.0.1/
! 78:
! 79: http://[2001:1890:1112:1::20]/
! 80:
! 81: It is also possible to specify the user name, password and any supported login
! 82: options as part of the host, for the following protocols, when connecting to
! 83: servers that require authentication:
! 84:
! 85: http://user:password@www.example.com
! 86:
! 87: ftp://user:password@ftp.example.com
! 88:
! 89: smb://domain%2fuser:password@server.example.com
! 90:
! 91: imap://user:password;options@mail.example.com
! 92:
! 93: pop3://user:password;options@mail.example.com
! 94:
! 95: smtp://user:password;options@mail.example.com
! 96:
! 97: At present only IMAP, POP3 and SMTP support login options as part of the host.
! 98: For more information about the login options in URL syntax please see RFC2384,
! 99: RFC5092 and IETF draft draft-earhart-url-smtp-00.txt (Added in 7.31.0).
! 100:
! 101: The port is optional and when not specified libcurl will use the default port
! 102: based on the determined or specified protocol: 80 for HTTP, 21 for FTP and 25
! 103: for SMTP, etc. The following examples show how to specify the port:
! 104:
! 105: http://www.example.com:8080/ - This will connect to a web server using port
! 106: 8080 rather than 80.
! 107:
! 108: smtp://mail.example.com:587/ - This will connect to a SMTP server on the
! 109: alternative mail port.
! 110:
! 111: The path part of the URL is protocol specific and whilst some examples are
! 112: given below this list is not conclusive:
! 113:
! 114: .IP HTTP
! 115: The path part of an HTTP request specifies the file to retrieve and from what
! 116: directory. If the directory is not specified then the web server's root
! 117: directory is used. If the file is omitted then the default document will be
! 118: retrieved for either the directory specified or the root directory. The exact
! 119: resource returned for each URL is entirely dependent on the server's
! 120: configuration.
! 121:
! 122: http://www.example.com - This gets the main page from the web server.
! 123:
! 124: http://www.example.com/index.html - This returns the main page by explicitly
! 125: requesting it.
! 126:
! 127: http://www.example.com/contactus/ - This returns the default document from
! 128: the contactus directory.
! 129:
! 130: .IP FTP
! 131: The path part of an FTP request specifies the file to retrieve and from what
! 132: directory. If the file part is omitted then libcurl downloads the directory
! 133: listing for the directory specified. If the directory is omitted then
! 134: the directory listing for the root / home directory will be returned.
! 135:
! 136: ftp://ftp.example.com - This retrieves the directory listing for the root
! 137: directory.
! 138:
! 139: ftp://ftp.example.com/readme.txt - This downloads the file readme.txt from the
! 140: root directory.
! 141:
! 142: ftp://ftp.example.com/libcurl/readme.txt - This downloads readme.txt from the
! 143: libcurl directory.
! 144:
! 145: ftp://user:password@ftp.example.com/readme.txt - This retrieves the readme.txt
! 146: file from the user's home directory. When a username and password is
! 147: specified, everything that is specified in the path part is relative to the
! 148: user's home directory. To retrieve files from the root directory or a
! 149: directory underneath the root directory then the absolute path must be
! 150: specified by prepending an additional forward slash to the beginning of the
! 151: path.
! 152:
! 153: ftp://user:password@ftp.example.com//readme.txt - This retrieves the readme.txt
! 154: from the root directory when logging in as a specified user.
! 155:
! 156: .IP FILE
! 157: When a FILE:// URL is accessed on Windows systems, it can be crafted in a way
! 158: so that Windows attempts to connect to a (remote) machine when curl wants to
! 159: read or write such a path.
! 160: .IP SMTP
! 161: The path part of a SMTP request specifies the host name to present during
! 162: communication with the mail server. If the path is omitted then libcurl will
! 163: attempt to resolve the local computer's host name. However, this may not
! 164: return the fully qualified domain name that is required by some mail servers
! 165: and specifying this path allows you to set an alternative name, such as
! 166: your machine's fully qualified domain name, which you might have obtained
! 167: from an external function such as gethostname or getaddrinfo.
! 168:
! 169: smtp://mail.example.com - This connects to the mail server at example.com and
! 170: sends your local computer's host name in the HELO / EHLO command.
! 171:
! 172: smtp://mail.example.com/client.example.com - This will send client.example.com in
! 173: the HELO / EHLO command to the mail server at example.com.
! 174:
! 175: .IP POP3
! 176: The path part of a POP3 request specifies the message ID to retrieve. If the
! 177: ID is not specified then a list of waiting messages is returned instead.
! 178:
! 179: pop3://user:password@mail.example.com - This lists the available messages for
! 180: the user
! 181:
! 182: pop3://user:password@mail.example.com/1 - This retrieves the first message for
! 183: the user
! 184:
! 185: .IP IMAP
! 186: The path part of an IMAP request not only specifies the mailbox to list (Added
! 187: in 7.30.0) or select, but can also be used to check the UIDVALIDITY of the
! 188: mailbox, to specify the UID, SECTION (Added in 7.30.0) and PARTIAL octets
! 189: (Added in 7.37.0) of the message to fetch and to specify what messages to
! 190: search for (Added in 7.37.0).
! 191:
! 192: imap://user:password@mail.example.com - Performs a top level folder list
! 193:
! 194: imap://user:password@mail.example.com/INBOX - Performs a folder list on the
! 195: user's inbox
! 196:
! 197: imap://user:password@mail.example.com/INBOX/;UID=1 - Selects the user's inbox
! 198: and fetches message with uid = 1
! 199:
! 200: imap://user:password@mail.example.com/INBOX/;MAILINDEX=1 - Selects the user's inbox
! 201: and fetches the first message in the mail box
! 202:
! 203: imap://user:password@mail.example.com/INBOX;UIDVALIDITY=50/;UID=2 - Selects
! 204: the user's inbox, checks the UIDVALIDITY of the mailbox is 50 and fetches
! 205: message 2 if it is
! 206:
! 207: imap://user:password@mail.example.com/INBOX/;UID=3/;SECTION=TEXT - Selects the
! 208: user's inbox and fetches the text portion of message 3
! 209:
! 210: imap://user:password@mail.example.com/INBOX/;UID=4/;PARTIAL=0.1024 - Selects
! 211: the user's inbox and fetches the first 1024 octets of message 4
! 212:
! 213: imap://user:password@mail.example.com/INBOX?NEW - Selects the user's inbox and
! 214: checks for NEW messages
! 215:
! 216: imap://user:password@mail.example.com/INBOX?SUBJECT%20shadows - Selects the
! 217: user's inbox and searches for messages containing "shadows" in the subject
! 218: line
! 219:
! 220: For more information about the individual components of an IMAP URL please
! 221: see RFC5092.
! 222:
! 223: .IP SCP
! 224: The path part of a SCP request specifies the file to retrieve and from what
! 225: directory. The file part may not be omitted. The file is taken as an absolute
! 226: path from the root directory on the server. To specify a path relative to the
! 227: user's home directory on the server, prepend ~/ to the path portion. If the
! 228: user name is not embedded in the URL, it can be set with the
! 229: \fICURLOPT_USERPWD(3)\fP or \fICURLOPT_USERNAME(3)\fP option.
! 230:
! 231: scp://user@example.com/etc/issue - This specifies the file /etc/issue
! 232:
! 233: scp://example.com/~/my-file - This specifies the file my-file in the
! 234: user's home directory on the server
! 235: .IP SFTP
! 236: The path part of a SFTP request specifies the file to retrieve and from what
! 237: directory. If the file part is omitted then libcurl downloads the directory
! 238: listing for the directory specified. If the path ends in a / then a directory
! 239: listing is returned instead of a file. If the path is omitted entirely then
! 240: the directory listing for the root / home directory will be returned. If the
! 241: user name is not embedded in the URL, it can be set with the
! 242: \fICURLOPT_USERPWD(3)\fP or \fICURLOPT_USERNAME(3)\fP option.
! 243:
! 244: sftp://user:password@example.com/etc/issue - This specifies the file
! 245: /etc/issue
! 246:
! 247: sftp://user@example.com/~/my-file - This specifies the file my-file in the
! 248: user's home directory
! 249:
! 250: sftp://ssh.example.com/~/Documents/ - This requests a directory listing
! 251: of the Documents directory under the user's home directory
! 252:
! 253: .IP SMB
! 254: The path part of a SMB request specifies the file to retrieve and from what
! 255: share and directory or the share to upload to and as such, may not be omitted.
! 256: If the user name is not embedded in the URL, it can be set with the
! 257: \fICURLOPT_USERPWD(3)\fP or \fICURLOPT_USERNAME(3)\fP option. If the user name
! 258: is embedded in the URL then it must contain the domain name and as such, the
! 259: backslash must be URL encoded as %2f.
! 260:
! 261: smb://server.example.com/files/issue - This specifies the file "issue" located
! 262: in the root of the "files" share
! 263:
! 264: smb://server.example.com/files/ -T issue - This specifies the file "issue" will
! 265: be uploaded to the root of the "files" share.
! 266:
! 267: curl supports SMB version 1 (only)
! 268: .IP LDAP
! 269: The path part of a LDAP request can be used to specify the: Distinguished
! 270: Name, Attributes, Scope, Filter and Extension for a LDAP search. Each field
! 271: is separated by a question mark and when that field is not required an empty
! 272: string with the question mark separator should be included.
! 273:
! 274: ldap://ldap.example.com/o=My%20Organisation - This will perform a LDAP search
! 275: with the DN as My Organisation.
! 276:
! 277: ldap://ldap.example.com/o=My%20Organisation?postalAddress - This will perform
! 278: the same search but will only return postalAddress attributes.
! 279:
! 280: ldap://ldap.example.com/?rootDomainNamingContext - This specifies an empty DN
! 281: and requests information about the rootDomainNamingContext attribute for an
! 282: Active Directory server.
! 283:
! 284: For more information about the individual components of a LDAP URL please
! 285: see RFC4516.
! 286: .IP RTMP
! 287: There's no official URL spec for RTMP so libcurl uses the URL syntax supported
! 288: by the underlying librtmp library. It has a syntax where it wants a
! 289: traditional URL, followed by a space and a series of space-separated
! 290: name=value pairs.
! 291:
! 292: While space is not typically a "legal" letter, libcurl accepts them. When a
! 293: user wants to pass in a '#' (hash) character it will be treated as a fragment
! 294: and get cut off by libcurl if provided literally. You will instead have to
! 295: escape it by providing it as backslash and its ASCII value in hexadecimal:
! 296: "\\23".
! 297:
! 298: .RS 0
! 299: The application does not have to keep the string around after setting this
! 300: option.
! 301: .SH ENCODING
! 302: The string pointed to in the \fICURLOPT_URL(3)\fP argument is generally
! 303: expected to be a sequence of characters using an ASCII compatible encoding.
! 304:
! 305: If libcurl is built with IDN support, the server name part of the URL can use
! 306: an "international name" by using the current encoding (according to locale) or
! 307: UTF-8 (when winidn is used).
! 308:
! 309: If libcurl is built without IDN support, the server name is used exactly as
! 310: specified when passed to the name resolver functions.
! 311: .SH DEFAULT
! 312: There is no default URL. If this option isn't set, no transfer can be
! 313: performed.
! 314: .SH SECURITY CONCERNS
! 315: Applications may at times find it convenient to allow users to specify URLs
! 316: for various purposes and that string would then end up fed to this option.
! 317:
! 318: Getting a URL from an external untrusted party will bring reasons for several
! 319: security concerns:
! 320:
! 321: If you have an application that runs as or in a server application, getting an
! 322: unfiltered URL can easily trick your application to access a local resource
! 323: instead of a remote. Protecting yourself against localhost accesses is very
! 324: hard when accepting user provided URLs.
! 325:
! 326: Such custom URLs can also access other ports than you planned as port numbers
! 327: are part of the regular URL format. The combination of a local host and a
! 328: custom port number can allow external users to play tricks with your local
! 329: services.
! 330:
! 331: Accepting external URLs may also use other protocols than http:// or other
! 332: common ones. Restrict what accept with \fICURLOPT_PROTOCOLS(3)\fP.
! 333:
! 334: User provided URLs can also be made to point to sites that redirect further on
! 335: (possibly to other protocols too). Consider your
! 336: \fICURLOPT_FOLLOWLOCATION(3)\fP and \fICURLOPT_REDIR_PROTOCOLS(3)\fP settings.
! 337: .SH PROTOCOLS
! 338: All
! 339: .SH EXAMPLE
! 340: .nf
! 341: CURL *curl = curl_easy_init();
! 342: if(curl) {
! 343: curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
! 344:
! 345: curl_easy_perform(curl);
! 346: }
! 347: .fi
! 348: .SH AVAILABILITY
! 349: POP3 and SMTP were added in 7.31.0
! 350: .SH RETURN VALUE
! 351: Returns CURLE_OK on success or CURLE_OUT_OF_MEMORY if there was insufficient
! 352: heap space.
! 353:
! 354: Note that \fIcurl_easy_setopt(3)\fP won't actually parse the given string so
! 355: given a bad URL, it will not be detected until \fIcurl_easy_perform(3)\fP or
! 356: similar is called.
! 357: .SH "SEE ALSO"
! 358: .BR CURLOPT_VERBOSE "(3), " CURLOPT_PROTOCOLS "(3), "
! 359: .BR CURLOPT_FORBID_REUSE "(3), " CURLOPT_FRESH_CONNECT "(3), "
! 360: .BR curl_easy_perform "(3), "
! 361: .BR CURLINFO_REDIRECT_URL "(3), " CURLOPT_PATH_AS_IS "(3), " CURLOPT_CURLU "(3), "
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to CURLOPT_URL.3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs / libcurl / opts