mirror of
https://github.com/curl/curl.git
synced 2025-04-12 16:20:35 +08:00
CURLOPT_URL.3: remove scheme specific details
... that are now found in URL-SYNTAX.md Closes #6307
This commit is contained in:
Daniel Stenberg
parent
2a264d494e
commit
a0f0c7149f
@ -64,236 +64,6 @@ set.
|
||||
\fICURLOPT_URL(3)\fP or \fICURLOPT_CURLU(3)\fP \fBmust\fP be set before a
|
||||
transfer is started.
|
||||
|
||||
The host part of the URL contains the address of the server that you want to
|
||||
connect to. This can be the fully qualified domain name of the server, the
|
||||
local network name of the machine on your network or the IP address of the
|
||||
server or machine represented by either an IPv4 or IPv6 address. For example:
|
||||
|
||||
http://www.example.com/
|
||||
|
||||
http://hostname/
|
||||
|
||||
http://192.168.0.1/
|
||||
|
||||
http://[2001:1890:1112:1::20]/
|
||||
|
||||
It is also possible to specify the user name, password and any supported login
|
||||
options as part of the host, for the following protocols, when connecting to
|
||||
servers that require authentication:
|
||||
|
||||
http://user:password@www.example.com
|
||||
|
||||
ftp://user:password@ftp.example.com
|
||||
|
||||
smb://domain%2fuser:password@server.example.com
|
||||
|
||||
imap://user:password;options@mail.example.com
|
||||
|
||||
pop3://user:password;options@mail.example.com
|
||||
|
||||
smtp://user:password;options@mail.example.com
|
||||
|
||||
At present only IMAP, POP3 and SMTP support login options as part of the host.
|
||||
For more information about the login options in URL syntax please see RFC2384,
|
||||
RFC5092 and IETF draft draft-earhart-url-smtp-00.txt (Added in 7.31.0).
|
||||
|
||||
The port is optional and when not specified libcurl will use the default port
|
||||
based on the determined or specified protocol: 80 for HTTP, 21 for FTP and 25
|
||||
for SMTP, etc. The following examples show how to specify the port:
|
||||
|
||||
http://www.example.com:8080/ - This will connect to a web server using port
|
||||
8080 rather than 80.
|
||||
|
||||
smtp://mail.example.com:587/ - This will connect to a SMTP server on the
|
||||
alternative mail port.
|
||||
|
||||
The path part of the URL is protocol specific and whilst some examples are
|
||||
given below this list is not conclusive:
|
||||
|
||||
.IP HTTP
|
||||
The path part of an HTTP request specifies the file to retrieve and from what
|
||||
directory. If the directory is not specified then the web server's root
|
||||
directory is used. If the file is omitted then the default document will be
|
||||
retrieved for either the directory specified or the root directory. The exact
|
||||
resource returned for each URL is entirely dependent on the server's
|
||||
configuration.
|
||||
|
||||
http://www.example.com - This gets the main page from the web server.
|
||||
|
||||
http://www.example.com/index.html - This returns the main page by explicitly
|
||||
requesting it.
|
||||
|
||||
http://www.example.com/contactus/ - This returns the default document from
|
||||
the contactus directory.
|
||||
|
||||
.IP FTP
|
||||
The path part of an FTP request specifies the file to retrieve and from what
|
||||
directory. If the file part is omitted then libcurl downloads the directory
|
||||
listing for the directory specified. If the directory is omitted then
|
||||
the directory listing for the root / home directory will be returned.
|
||||
|
||||
ftp://ftp.example.com - This retrieves the directory listing for the root
|
||||
directory.
|
||||
|
||||
ftp://ftp.example.com/readme.txt - This downloads the file readme.txt from the
|
||||
root directory.
|
||||
|
||||
ftp://ftp.example.com/libcurl/readme.txt - This downloads readme.txt from the
|
||||
libcurl directory.
|
||||
|
||||
ftp://user:password@ftp.example.com/readme.txt - This retrieves the readme.txt
|
||||
file from the user's home directory. When a username and password is
|
||||
specified, everything that is specified in the path part is relative to the
|
||||
user's home directory. To retrieve files from the root directory or a
|
||||
directory underneath the root directory then the absolute path must be
|
||||
specified by prepending an additional forward slash to the beginning of the
|
||||
path.
|
||||
|
||||
ftp://user:password@ftp.example.com//readme.txt - This retrieves the readme.txt
|
||||
from the root directory when logging in as a specified user.
|
||||
|
||||
.IP FILE
|
||||
When a FILE:// URL is accessed on Windows systems, it can be crafted in a way
|
||||
so that Windows attempts to connect to a (remote) machine when curl wants to
|
||||
read or write such a path.
|
||||
.IP SMTP
|
||||
The path part of a SMTP request specifies the host name to present during
|
||||
communication with the mail server. If the path is omitted then libcurl will
|
||||
attempt to resolve the local computer's host name. However, this may not
|
||||
return the fully qualified domain name that is required by some mail servers
|
||||
and specifying this path allows you to set an alternative name, such as
|
||||
your machine's fully qualified domain name, which you might have obtained
|
||||
from an external function such as gethostname or getaddrinfo.
|
||||
|
||||
smtp://mail.example.com - This connects to the mail server at example.com and
|
||||
sends your local computer's host name in the HELO / EHLO command.
|
||||
|
||||
smtp://mail.example.com/client.example.com - This will send client.example.com in
|
||||
the HELO / EHLO command to the mail server at example.com.
|
||||
|
||||
.IP POP3
|
||||
The path part of a POP3 request specifies the message ID to retrieve. If the
|
||||
ID is not specified then a list of waiting messages is returned instead.
|
||||
|
||||
pop3://user:password@mail.example.com - This lists the available messages for
|
||||
the user
|
||||
|
||||
pop3://user:password@mail.example.com/1 - This retrieves the first message for
|
||||
the user
|
||||
|
||||
.IP IMAP
|
||||
The path part of an IMAP request not only specifies the mailbox to list (Added
|
||||
in 7.30.0) or select, but can also be used to check the UIDVALIDITY of the
|
||||
mailbox, to specify the UID, SECTION (Added in 7.30.0) and PARTIAL octets
|
||||
(Added in 7.37.0) of the message to fetch and to specify what messages to
|
||||
search for (Added in 7.37.0).
|
||||
|
||||
imap://user:password@mail.example.com - Performs a top level folder list
|
||||
|
||||
imap://user:password@mail.example.com/INBOX - Performs a folder list on the
|
||||
user's inbox
|
||||
|
||||
imap://user:password@mail.example.com/INBOX/;UID=1 - Selects the user's inbox
|
||||
and fetches message with uid = 1
|
||||
|
||||
imap://user:password@mail.example.com/INBOX/;MAILINDEX=1 - Selects the user's inbox
|
||||
and fetches the first message in the mail box
|
||||
|
||||
imap://user:password@mail.example.com/INBOX;UIDVALIDITY=50/;UID=2 - Selects
|
||||
the user's inbox, checks the UIDVALIDITY of the mailbox is 50 and fetches
|
||||
message 2 if it is
|
||||
|
||||
imap://user:password@mail.example.com/INBOX/;UID=3/;SECTION=TEXT - Selects the
|
||||
user's inbox and fetches the text portion of message 3
|
||||
|
||||
imap://user:password@mail.example.com/INBOX/;UID=4/;PARTIAL=0.1024 - Selects
|
||||
the user's inbox and fetches the first 1024 octets of message 4
|
||||
|
||||
imap://user:password@mail.example.com/INBOX?NEW - Selects the user's inbox and
|
||||
checks for NEW messages
|
||||
|
||||
imap://user:password@mail.example.com/INBOX?SUBJECT%20shadows - Selects the
|
||||
user's inbox and searches for messages containing "shadows" in the subject
|
||||
line
|
||||
|
||||
For more information about the individual components of an IMAP URL please
|
||||
see RFC5092.
|
||||
|
||||
.IP SCP
|
||||
The path part of an SCP URL specifies the path and file to retrieve or
|
||||
upload. The file part may not be omitted. The file is taken as an absolute
|
||||
path from the root directory on the server. To specify a path relative to the
|
||||
user's home directory on the server, prepend ~/ to the path portion. If the
|
||||
user name is not embedded in the URL, it can be set with the
|
||||
\fICURLOPT_USERPWD(3)\fP or \fICURLOPT_USERNAME(3)\fP option.
|
||||
|
||||
scp://user@example.com/etc/issue - This specifies the file /etc/issue
|
||||
|
||||
scp://example.com/~/my-file - This specifies the file my-file in the
|
||||
user's home directory on the server
|
||||
.IP SFTP
|
||||
The path part of an SFTP URL specifies the file to retrieve or upload. If the
|
||||
path ends in a / then a directory listing is returned instead of a file. If
|
||||
the path is omitted entirely then the directory listing for the root / home
|
||||
directory will be returned. If the user name is not embedded in the URL, it
|
||||
can be set with the \fICURLOPT_USERPWD(3)\fP or \fICURLOPT_USERNAME(3)\fP
|
||||
option.
|
||||
|
||||
sftp://user:password@example.com/etc/issue - This specifies the file
|
||||
/etc/issue
|
||||
|
||||
sftp://user@example.com/~/my-file - This specifies the file my-file in the
|
||||
user's home directory
|
||||
|
||||
sftp://ssh.example.com/~/Documents/ - This requests a directory listing
|
||||
of the Documents directory under the user's home directory
|
||||
|
||||
.IP SMB
|
||||
The path part of a SMB request specifies the file to retrieve and from what
|
||||
share and directory or the share to upload to and as such, may not be omitted.
|
||||
If the user name is not embedded in the URL, it can be set with the
|
||||
\fICURLOPT_USERPWD(3)\fP or \fICURLOPT_USERNAME(3)\fP option. If the user name
|
||||
is embedded in the URL then it must contain the domain name and as such, the
|
||||
backslash must be URL encoded as %2f.
|
||||
|
||||
smb://server.example.com/files/issue - This specifies the file "issue" located
|
||||
in the root of the "files" share
|
||||
|
||||
smb://server.example.com/files/ -T issue - This specifies the file "issue" will
|
||||
be uploaded to the root of the "files" share.
|
||||
|
||||
curl supports SMB version 1 (only)
|
||||
.IP LDAP
|
||||
The path part of a LDAP request can be used to specify the: Distinguished
|
||||
Name, Attributes, Scope, Filter and Extension for a LDAP search. Each field
|
||||
is separated by a question mark and when that field is not required an empty
|
||||
string with the question mark separator should be included.
|
||||
|
||||
ldap://ldap.example.com/o=My%20Organisation - This will perform a LDAP search
|
||||
with the DN as My Organisation.
|
||||
|
||||
ldap://ldap.example.com/o=My%20Organisation?postalAddress - This will perform
|
||||
the same search but will only return postalAddress attributes.
|
||||
|
||||
ldap://ldap.example.com/?rootDomainNamingContext - This specifies an empty DN
|
||||
and requests information about the rootDomainNamingContext attribute for an
|
||||
Active Directory server.
|
||||
|
||||
For more information about the individual components of a LDAP URL please
|
||||
see RFC4516.
|
||||
.IP RTMP
|
||||
There's no official URL spec for RTMP so libcurl uses the URL syntax supported
|
||||
by the underlying librtmp library. It has a syntax where it wants a
|
||||
traditional URL, followed by a space and a series of space-separated
|
||||
name=value pairs.
|
||||
|
||||
While space is not typically a "legal" letter, libcurl accepts them. When a
|
||||
user wants to pass in a '#' (hash) character it will be treated as a fragment
|
||||
and get cut off by libcurl if provided literally. You will instead have to
|
||||
escape it by providing it as backslash and its ASCII value in hexadecimal:
|
||||
"\\23".
|
||||
|
||||
.RS 0
|
||||
The application does not have to keep the string around after setting this
|
||||
option.
|
||||
.SH ENCODING
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user