After this patch `://` schemes are lowercase and enclosed in backticks.
Also:
- docs/libcurl/libcurl-multi.md: drop a stray C code fence.
- docs/libcurl/libcurl-tutorial.md: replace single/double quotes with
Markdown markup where applicable.
Ref: #21646
Closes #21674
curl supports FTPS (sometimes known as FTP-SSL) both implicit and explicit
mode.
-When a URL is used that starts with `FTPS://`, curl assumes implicit SSL on
+When a URL is used that starts with `ftps://`, curl assumes implicit SSL on
the control connection and therefore immediately connects and tries to speak
-SSL. `FTPS://` connections default to port 990.
+SSL. `ftps://` connections default to port 990.
-To use explicit FTPS, you use an `FTP://` URL and the `--ssl-reqd` option (or
+To use explicit FTPS, you use an `ftp://` URL and the `--ssl-reqd` option (or
one of its related flavors). This is the most common method, and the one
mandated by RFC 4217. This kind of connection then of course uses the standard
FTP port 21 by default.
anything else. This makes (lib)curl to consider the connection connected
and thus the connect timeout does not trigger.
-## file:// URLs containing drive letters (Windows, NetWare)
+## `file://` URLs containing drive letters (Windows, NetWare)
When using curl to try to download a local file, one might use a URL in this
format:
May: first Debian package.
-August: LDAP:// and FILE:// support added. The curl website gets 1300 visits
-weekly. Moved site to curl.haxx.nu.
+August: `ldap://` and `file://` support added. The curl website gets 1300
+visits weekly. Moved site to curl.haxx.nu.
September: Released curl 6.0. 15000 lines of code.
March 22: curl supports HTTP 1.1 starting with the release of 7.7. This
also introduced libcurl's ability to do persistent connections. 24000 lines of
code. The libcurl major SONAME number was bumped to 2 due to this overhaul.
-The first experimental ftps:// support was added.
+The first experimental `ftps://` support was added.
August: The curl website gets 8000 visits weekly. Curl Corporation contacted
Daniel to discuss "the name issue". After Daniel's reply, they have never
The list of ALPN IDs is parsed but may not be completely respected because of
what the HTTP version preference is set to, which is a problem we are working
-on. Also, getting an `HTTP/1.1` ALPN in the HTTPS RR field for an HTTP://
+on. Also, getting an `HTTP/1.1` ALPN in the HTTPS RR field for an `http://`
transfer should imply switching to HTTPS, HSTS style. Which curl currently
does not.
the globe.
The CDN servers support HTTP/1, HTTP/2 and HTTP/3. They set HSTS for a year.
-The `HTTP://` version of the site redirects to `HTTPS://`.
+The `http://` version of the site redirects to `https://`.
Fastly manages the TLS certificates from Let's Encrypt for the servers they
run on the behalf of curl.
It is like FTP, but you may also want to specify and use SSL-specific options
for certificates etc.
-Note that using `FTPS://` as prefix is the *implicit* way as described in the
-standards while the recommended *explicit* way is done by using `FTP://` and
+Note that using `ftps://` as prefix is the *implicit* way as described in the
+standards while the recommended *explicit* way is done by using `ftp://` and
the `--ssl-reqd` option.
### SFTP / SCP
the functionality with the libssh2 backend. Presumably, this support can/could
be added for the libssh backend as well.
-## SFTP with `SCP://`
+## SFTP with `scp://`
OpenSSH 9 switched their `scp` tool to speak SFTP under the hood. Going
forward it might be worth having curl or libcurl attempt SFTP if SCP fails to
## FILE
-When a `FILE://` URL is accessed on Windows systems, it can be crafted in a
+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.
## DICT
Lets you lookup words using online dictionaries.
## FILE
-Read or write local files. curl does not support accessing file:// URL
+Read or write local files. curl does not support accessing `file://` URL
remotely, but when running on Microsoft Windows using the native UNC approach
works. Only absolute paths.
## FTP(S)
<!-- Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. -->
<!-- SPDX-License-Identifier: curl -->
# PROXY PROTOCOL PREFIXES
-The proxy string may be specified with a protocol:// prefix to specify
+The proxy string may be specified with a `protocol://` prefix to specify
alternative proxy protocols. (Added in 7.21.7)
If no protocol is specified in the proxy string or if the string does not
match a supported one, the proxy is treated as an HTTP proxy.
The supported proxy protocol prefixes are as follows:
-## http://
+## `http://`
Makes it use it as an HTTP proxy. The default if no scheme prefix is used.
-## https://
+## `https://`
Makes it treated as an **HTTPS** proxy.
-## socks4://
+## `socks4://`
Makes it the equivalent of --socks4
-## socks4a://
+## `socks4a://`
Makes it the equivalent of --socks4a
-## socks5://
+## `socks5://`
Makes it the equivalent of --socks5
-## socks5h://
+## `socks5h://`
Makes it the equivalent of --socks5-hostname
The URL syntax is protocol-dependent. You can find a detailed description in
RFC 3986.
-If you provide a URL without a leading **protocol://** scheme, curl guesses
+If you provide a URL without a leading `protocol://` scheme, curl guesses
what protocol you want. It then defaults to HTTP but assumes others based on
often-used hostname prefixes. For example, for hostnames starting with `ftp.`
curl assumes you want FTP.
file, that is used. After a completed transfer, the cache is saved to the
filename again if it has been modified.
-If curl is told to use HTTP:// for a transfer involving a hostname that exists
-in the HSTS cache, it upgrades the transfer to use HTTPS. Each HSTS cache
-entry has an individual lifetime after which the upgrade is no longer
+If curl is told to use `http://` for a transfer involving a hostname that
+exists in the HSTS cache, it upgrades the transfer to use HTTPS. Each HSTS
+cache entry has an individual lifetime after which the upgrade is no longer
performed.
Specify a "" filename (zero length) to avoid loading/saving and make curl
# `--http1.1`
-Use HTTP version 1.1. This is the default with HTTP:// URLs.
+Use HTTP version 1.1. This is the default with `http://` URLs.
such a case curl first connects to the SOCKS proxy and then connects (through
SOCKS) to the HTTP or HTTPS proxy. Hence pre proxy.
-The pre proxy string should be specified with a protocol:// prefix to specify
-alternative proxy protocols. Use socks4://, socks4a://, socks5:// or
-socks5h:// to request the specific SOCKS version to be used. No protocol
+The pre proxy string should be specified with a `protocol://` prefix to specify
+alternative proxy protocols. Use `socks4://`, `socks4a://`, `socks5://` or
+`socks5h://` to request the specific SOCKS version to be used. No protocol
specified makes curl default to SOCKS4.
If the port number is not specified in the proxy string, it is assumed to be
Use the specified proxy.
-The proxy string can be specified with a protocol:// prefix. No protocol
-specified or http:// it is treated as an HTTP proxy. Use socks4://,
-socks4a://, socks5:// or socks5h:// to request a specific SOCKS version to be
-used. (Added in 7.21.7)
+The proxy string can be specified with a `protocol://` prefix. No protocol
+specified or http:// it is treated as an HTTP proxy. Use `socks4://`,
+`socks4a://`, `socks5://` or `socks5h://` to request a specific SOCKS version
+to be used. (Added in 7.21.7)
Unix domain sockets are supported for socks proxy. Set localhost for the host
part. e.g. socks5h://localhost/path/to/socket.sock
-HTTPS proxy support works with the https:// protocol prefix for OpenSSL and
+HTTPS proxy support works with the `https://` protocol prefix for OpenSSL and
GnuTLS (added in 7.52.0). It also works for mbedTLS, Rustls, Schannel and
wolfSSL (added in 7.87.0).
or pass in a colon with %3a.
The proxy host can be specified the same way as the proxy environment
-variables, including the protocol prefix (http://) and the embedded user +
+variables, including the protocol prefix (`http://`) and the embedded user +
password.
When a proxy is used, the active FTP mode as set with --ftp-port, cannot be
exclusive.
This option is superfluous since you can specify a socks4 proxy with --proxy
-using a socks4:// protocol prefix. (Added in 7.21.7)
+using a `socks4://` protocol prefix. (Added in 7.21.7)
--preproxy can be used to specify a SOCKS proxy at the same time proxy is used
with an HTTP/HTTPS proxy (added in 7.52.0). In such a case, curl first
exclusive.
This option is superfluous since you can specify a socks4a proxy with --proxy
-using a socks4a:// protocol prefix. (Added in 7.21.7)
+using a `socks4a://` protocol prefix. (Added in 7.21.7)
--preproxy can be used to specify a SOCKS proxy at the same time --proxy is
used with an HTTP/HTTPS proxy (added in 7.52.0). In such a case, curl first
exclusive.
This option is superfluous since you can specify a socks5 hostname proxy with
---proxy using a socks5h:// protocol prefix. (Added in 7.21.7)
+--proxy using a `socks5h://` protocol prefix. (Added in 7.21.7)
--preproxy can be used to specify a SOCKS proxy at the same time --proxy is
used with an HTTP/HTTPS proxy (added in 7.52.0). In such a case, curl first
exclusive.
This option is superfluous since you can specify a socks5 proxy with --proxy
-using a socks5:// protocol prefix. (Added in 7.21.7)
+using a `socks5://` protocol prefix. (Added in 7.21.7)
--preproxy can be used to specify a SOCKS proxy at the same time --proxy is
used with an HTTP/HTTPS proxy (added in 7.52.0). In such a case, curl first
if(curl) {
/*
* You better replace the URL with one that works! Note that we use an
- * FTP:// URL with standard explicit FTPS. You can also do FTPS:// URLs if
+ * ftp:// URL with standard explicit FTPS. You can also do ftps:// URLs if
* you want to do the rarer kind of transfers: implicit.
*/
curl_easy_setopt(curl, CURLOPT_URL,
# LIMITATIONS
The pausing of transfers does not work with protocols that work without
-network connectivity, like FILE://. Trying to pause such a transfer, in any
+network connectivity, like `file://`. Trying to pause such a transfer, in any
direction, might cause problems or error.
# MULTIPLEXED
## CURLE_FILE_COULDNT_READ_FILE (37)
-A file given with FILE:// could not be opened. Most likely because the file
+A file given with `file://` could not be opened. Most likely because the file
path does not identify an existing file. Did you check file permissions?
## CURLE_LDAP_CANNOT_BIND (38)
## CURLUE_BAD_FILE_URL (19)
-The file:// URL is invalid.
+The `file://` URL is invalid.
## CURLUE_BAD_FRAGMENT (20)
multi interface. While we certainly want and intend for these to get fixed in
the future, you should be aware of the following current restrictions:
-~~~c
- Name resolves unless the c-ares or threaded-resolver backends are used
-- file:// transfers
+- `file://` transfers
- TELNET transfers
-~~~
Applications must not allow unsanitized SCP: URLs to be passed in for
downloads.
-# file://
+# `file://`
-By default curl and libcurl support file:// URLs. Such a URL is always an
+By default curl and libcurl support `file://` URLs. Such a URL is always an
access, or attempted access, to a local resource. If your application wants to
avoid that, keep control of what URLs to use and/or prevent curl/libcurl from
using the protocol.
-By default, libcurl prohibits redirects to file:// URLs.
+By default, libcurl prohibits redirects to `file://` URLs.
-# Warning: file:// on Windows
+# Warning: `file://` on Windows
The Windows operating system tries automatically, and without any way for
applications to disable it, to establish a connection to another host over the
libcurl also provides options to set various passwords. The username and
password as shown embedded in the URL can instead get set with the
CURLOPT_USERPWD(3) option. The argument passed to libcurl should be a
-char * to a string in the format "user:password". In a manner like this:
+`char *` to a string in the format `"user:password"`. In a manner like this:
~~~c
curl_easy_setopt(handle, CURLOPT_USERPWD, "myname:thesecret");
There is a long time Unix "standard" way of storing FTP usernames and
passwords, namely in the $HOME/.netrc file (on Windows, libcurl also checks
the *%USERPROFILE% environment* variable if *%HOME%* is unset, and tries
-"_netrc" as name). The file should be made private so that only the user may
+`_netrc` as name). The file should be made private so that only the user may
read it (see also the "Security Considerations" chapter), as it might contain
the password in plain text. libcurl has the ability to use this file to figure
out what set of username and password to use for a particular host. As an
libcurl automatically checks and uses a set of environment variables to know
what proxies to use for certain protocols. The names of the variables are
-following an old tradition and are built up as "[protocol]_proxy" (note the
-lower casing). Which makes the variable 'http_proxy' checked for a name of a
+following an old tradition and are built up as `[protocol]_proxy` (note the
+lower casing). Which makes the variable `http_proxy` checked for a name of a
proxy to use when the input URL is HTTP. Following the same rule, the variable
-named 'ftp_proxy' is checked for FTP URLs. Again, the proxies are always HTTP
+named `ftp_proxy` is checked for FTP URLs. Again, the proxies are always HTTP
proxies, the different names of the variables allow different HTTP
proxies to be used.
The proxy environment variable contents should be in the format
-"[protocol://][user:password@]machine[:port]". Where the protocol:// part
+`[protocol://][user:password@]machine[:port]`. Where the `protocol://` part
specifies which type of proxy it is, and the optional port number specifies on
which port the proxy operates. If not specified, the internal default port
number is used and that is most likely not the one you would like it to be.
-There are two special environment variables. 'all_proxy' is what sets proxy
-for any URL in case the protocol specific variable was not set, and 'no_proxy'
+There are two special environment variables. `all_proxy` is what sets proxy
+for any URL in case the protocol specific variable was not set, and `no_proxy`
defines a list of hosts that should not use a proxy even though a variable may
-say so. If 'no_proxy' is a plain asterisk ("*") it matches all hosts.
+say so. If `no_proxy` is a plain asterisk (`*`) it matches all hosts.
To explicitly disable libcurl's checking for and using the proxy environment
variables, set the proxy name to "" - an empty string - with
specified in RFC 6455.
To initiate a WebSocket session with libcurl, setup an easy handle to use a
-URL with a "WS://" or "WSS://" scheme. "WS" is for cleartext communication
+URL with a `ws://` or `wss://` scheme. "WS" is for cleartext communication
over HTTP and "WSS" is for doing WebSocket securely over HTTPS.
A WebSocket request is done as an HTTP/1 GET request with an "Upgrade
# SECURITY CONCERNS
-We strongly urge users to stick to `HTTPS://` URLs, which makes this option
+We strongly urge users to stick to `https://` URLs, which makes this option
unnecessary.
libcurl cannot fully protect against attacks where an attacker has write
If you set *maxspeed* to a value lower than CURLOPT_BUFFERSIZE(3),
libcurl might download faster than the set limit initially.
-This option does not affect transfer speeds done with FILE:// URLs.
+This option does not affect transfer speeds done with `file://` URLs.
# DEFAULT
CURLOPT_UPLOAD_BUFFERSIZE(3), libcurl might "shoot over" the limit on
its first send and still send off a full buffer.
-This option does not affect transfer speeds done with FILE:// URLs.
+This option does not affect transfer speeds done with `file://` URLs.
# DEFAULT
Pass a long as a parameter, containing the value of the permissions that is
set on newly created directories on the remote server. The default value is
*0755*, but any valid value can be used. The only protocols that can use
-this are *sftp://*, *scp://*, and *file://*.
+this are `sftp://`, `scp://`, and `file://`.
# DEFAULT
Pass a long as a parameter, containing the value of the permissions that are
set on newly created files on the remote server. The default value is *0644*.
-The only protocols that can use this are *sftp://*, *scp://*, and *file://*.
+The only protocols that can use this are `sftp://`, `scp://`, and `file://`.
# DEFAULT
HTTP(S) proxy specified in the CURLOPT_PROXY(3) option. The pre proxy
can only be a SOCKS proxy.
-The pre proxy string should be prefixed with [scheme]:// to specify which kind
-of socks is used. Use socks4://, socks4a://, socks5:// or socks5h:// (the last
-one to enable socks5 and asking the proxy to do the resolving, also known as
-*CURLPROXY_SOCKS5_HOSTNAME* type) to request the specific SOCKS version to
-be used. Otherwise SOCKS4 is used as default.
+The pre proxy string should be prefixed with `[scheme]://` to specify which
+kind of socks is used. Use `socks4://`, `socks4a://`, `socks5://` or
+`socks5h://` (the last one to enable socks5 and asking the proxy to do the
+resolving, also known as *CURLPROXY_SOCKS5_HOSTNAME* type) to request the
+specific SOCKS version to be used. Otherwise SOCKS4 is used as default.
Setting the pre proxy string to "" (an empty string) explicitly disables the
use of a pre proxy.
numerical IP address. A numerical IPv6 address must be written within
[brackets].
-To specify port number in this string, append :[port] to the end of the host
+To specify port number in this string, append `:[port]` to the end of the host
name. The proxy's port number may optionally (but discouraged) be specified
with the separate option CURLOPT_PROXYPORT(3). If not specified, libcurl
defaults to using port 1080 for proxies.
-The proxy string may be prefixed with [scheme]:// to specify which kind of
+The proxy string may be prefixed with `[scheme]://` to specify which kind of
proxy is used.
Using this option multiple times makes the last set string override the
The application does not have to keep the string around after setting this
option.
-## http://
+## `http://`
HTTP Proxy. Default when no scheme or proxy type is specified.
-## https://
+## `https://`
HTTPS Proxy. (with OpenSSL, GnuTLS, mbedTLS, Rustls, Schannel or wolfSSL.)
This uses HTTP/1 by default. Setting CURLOPT_PROXYTYPE(3) to
**CURLPROXY_HTTPS2** allows libcurl to negotiate using HTTP/2 with proxy.
-## socks4://
+## `socks4://`
SOCKS4 Proxy.
-## socks4a://
+## `socks4a://`
SOCKS4a Proxy. Proxy resolves URL hostname.
-## socks5://
+## `socks5://`
SOCKS5 Proxy.
-## socks5h://
+## `socks5h://`
SOCKS5 Proxy. Proxy resolves URL hostname.
libcurl respects the proxy environment variables named **http_proxy**,
**ftp_proxy**, **sftp_proxy** etc. If set, libcurl uses the specified proxy
-for that URL scheme. For an "FTP://" URL, the **ftp_proxy** is
+for that URL scheme. For an `ftp://` URL, the **ftp_proxy** is
considered. **all_proxy** is used if no protocol specific proxy was set.
If **no_proxy** (or **NO_PROXY**) is set, it is the exact equivalent of
started. Even if you set a crazy value here, curl_easy_setopt(3) might still
return *CURLE_OK*.
-If the given URL is missing a scheme name (such as "http://" or "ftp://" etc)
+If the given URL is missing a scheme name (such as `http://` or `ftp://` etc)
then libcurl guesses based on the host. If the outermost subdomain name
matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that protocol gets used,
otherwise HTTP is used. Scheme guessing can be disabled by setting a default
custom port number can allow external users to play tricks with your local
services.
-Accepting external URLs may also use other protocols than http:// or other
+Accepting external URLs may also use other protocols than `http://` or other
common ones. Restrict what accept with CURLOPT_PROTOCOLS_STR(3).
User provided URLs can also be made to point to sites that redirect further on
- `%SOCKSPORT` - Port number of the SOCKS4/5 server
- `%SOCKSUNIXPATH` - Path to the Unix socket of the SOCKS server
- `%SRCDIR` - Full path to the source dir
-- `%SCP_PWD` - Current directory friendly for the SSH server for the scp:// protocol
-- `%SFTP_PWD` - Current directory friendly for the SSH server for the sftp:// protocol
+- `%SCP_PWD` - Current directory friendly for the SSH server for the `scp://` protocol
+- `%SFTP_PWD` - Current directory friendly for the SSH server for the `sftp://` protocol
- `%SSHKEYALGO` - SSH host and client key algorithm, e.g. `ssh-rsa` or `ssh-ed25519`
- `%SSHPORT` - Port number of the SCP/SFTP server
- `%SSHSRVMD5` - MD5 of SSH server's public key
if(nwritten == CURL_WRITEFUNC_PAUSE) {
if(data->conn->scheme->flags & PROTOPT_NONETWORK) {
/* Protocols that work without network cannot be paused. This is
- actually only FILE:// now, and it cannot pause since the transfer is
+ actually only file:// now, and it cannot pause since the transfer is
not done using the "normal" procedure. */
failf(data, "Write callback asked for PAUSE when not supported");
return CURLE_WRITE_ERROR;
case CURL_READFUNC_PAUSE:
if(data->conn->scheme->flags & PROTOPT_NONETWORK) {
/* protocols that work without network cannot be paused. This is
- actually only FILE:// now, and it cannot pause since the transfer
+ actually only file:// now, and it cannot pause since the transfer
is not done using the "normal" procedure. */
failf(data, "Read callback asked for PAUSE when not supported");
result = CURLE_READ_ERROR;
projects / thirdparty / curl.git / commitdiff
