--- /dev/null
+#!/usr/bin/perl
+# Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
+#
+# SPDX-License-Identifier: curl
+#
+# bad[:=]correct
+#
+# If separator is '=', the string will be compared case sensitively.
+# If separator is ':', the check is done case insensitively.
+#
+my $w;
+while(<STDIN>) {
+ chomp;
+ if($_ =~ /^#/) {
+ next;
+ }
+ if($_ =~ /^([^:=]*)([:=])(.*)/) {
+ my ($bad, $sep, $better)=($1, $2, $3);
+ push @w, $bad;
+ $alt{$bad} = $better;
+ if($sep eq "=") {
+ $exactcase{$bad} = 1;
+ }
+ }
+}
+
+my $errors;
+
+sub file {
+ my ($f) = @_;
+ my $l = 0;
+ open(F, "<$f");
+ while(<F>) {
+ my $in = $_;
+ $l++;
+ chomp $in;
+ if($in =~ /^ /) {
+ next;
+ }
+ # remove the link part
+ $in =~ s/(\[.*\])\(.*\)/$1/g;
+ # remove backticked texts
+ $in =~ s/\`.*\`//g;
+ foreach my $w (@w) {
+ my $case = $exactcase{$w};
+ if(($in =~ /^(.*)$w/i && !$case) ||
+ ($in =~ /^(.*)$w/ && $case) ) {
+ my $p = $1;
+ my $c = length($p)+1;
+ print STDERR "$f:$l:$c: error: found bad word \"$w\"\n";
+ printf STDERR " %4d | $in\n", $l;
+ printf STDERR " | %*s^%s\n", length($p), " ",
+ "~" x (length($w)-1);
+ printf STDERR " maybe use \"%s\" instead?\n", $alt{$w};
+ $errors++;
+ }
+ }
+ }
+ close(F);
+}
+
+my @files = @ARGV;
+
+foreach my $each (@files) {
+ file($each);
+}
+exit $errors;
--- /dev/null
+# Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
+#
+# SPDX-License-Identifier: curl
+#
+back-end:backend
+e-mail:email
+run-time:runtime
+set-up:setup
+tool chain:toolchain
+tool-chain:toolchain
+wild-card:wildcard
+wild card:wildcard
+i'm:I am
+you've:You have
+they've:They have
+they're:They are
+should've:should have
+don't:do not
+could've:could have
+doesn't:does not
+isn't:is not
+ a html: an html
+ a http: an http
+ a ftp: an ftp
+ url =URL
+internet\W=Internet
+isation:ization
+it's:it is
+there's:there is
+[^.]\. And: Rewrite it somehow?
+\. But: Rewrite it somehow?
+file name :filename
+\. So : Rewrite without "so" ?
+ dir :directory
+you'd:you would
+you'll:you will
+can't:cannot
+that's:that is
+web page:webpage
+host name\W:hostname
+file name\W:filename
+didn't:did not
+doesn't:does not
+won't:will not
+couldn't:could not
web page
WebDAV
WebOS
+webpage
WebSocket
WEBSOCKET
WHATWG
--- /dev/null
+# Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
+#
+# SPDX-License-Identifier: curl
+
+name: badwords
+
+on:
+ # Trigger the workflow on push or pull requests, but only for the
+ # master branch
+ push:
+ branches:
+ - master
+ - '*/ci'
+ pull_request:
+ branches:
+ - master
+
+jobs:
+ check:
+
+ runs-on: ubuntu-latest
+
+ steps:
+ - uses: actions/checkout@v2
+
+ - name: check
+ run: ./.github/scripts/badwords.pl < .github/scripts/badwords.txt docs/*.md docs/libcurl/*.md docs/libcurl/opts/*.md
## Fields
1. The ALPN id for the source origin
-2. The host name for the source origin
+2. The hostname for the source origin
3. The port number for the source origin
4. The ALPN id for the destination host
-5. The host name for the destination host
+5. The hostname for the destination host
6. The host number for the destination host
7. The expiration date and time of this entry within double quotes. The date format is "YYYYMMDD HH:MM:SS" and the time zone is GMT.
8. Boolean (1 or 0) if "persist" was set for this entry
9. Integer priority value (not currently used)
-If the host name is an IPv6 numerical address, it is stored with brackets such
+If the hostname is an IPv6 numerical address, it is stored with brackets such
as `[::1]`.
# TODO
Curl and libcurl keep being developed. Adding features and changing code
means that bugs will sneak in, no matter how hard we try to keep them out.
- Of course there are lots of bugs left. And lots of misfeatures.
+ Of course there are lots of bugs left. Not to mention misfeatures.
To help us make curl the stable and solid product we want it to be, we need
bug reports and bug fixes.
`TLS_AES_128_CCM_8_SHA256`
`TLS_AES_128_CCM_SHA256`
-Note if you set TLS 1.3 ciphers without also setting the minimum TLS version to
-1.3 then it's possible Schannel may negotiate an earlier TLS version and cipher
-suite if your libcurl and OS settings allow it. You can set the minimum TLS
-version by using `CURLOPT_SSLVERSION` or `--tlsv1.3`.
+Note if you set TLS 1.3 ciphers without also setting the minimum TLS version
+to 1.3 then it is possible Schannel may negotiate an earlier TLS version and
+cipher suite if your libcurl and OS settings allow it. You can set the minimum
+TLS version by using `CURLOPT_SSLVERSION` or `--tlsv1.3`.
## BearSSL
#define CLIENTWRITE_TRAILER (1<<6) /* a trailer HEADER */
```
-The main types here are `CLIENTWRITE_BODY` and `CLIENTWRITE_HEADER`. They are mutually exclusive. The other bits are enhancements to `CLIENTWRITE_HEADER` to specify what the header is about. And they are only used in HTTP and related protocols (RTSP and WebSocket).
+The main types here are `CLIENTWRITE_BODY` and `CLIENTWRITE_HEADER`. They are
+mutually exclusive. The other bits are enhancements to `CLIENTWRITE_HEADER` to
+specify what the header is about. They are only used in HTTP and related
+protocols (RTSP and WebSocket).
The implementation of `Curl_client_write()` uses a chain of *client writer* instances to process the call and make sure that the bytes reach the proper application callbacks. This is similar to the design of connection filters: client writers can be chained to process the bytes written through them. The definition is:
above. In such a case the statement will span multiple lines.
If a continuation line is part of an expression or sub-expression then you
-should align on the appropriate column so that it's easy to tell what part of
+should align on the appropriate column so that it is easy to tell what part of
the statement it is. Operators should not start continuation lines. In other
cases follow the 2-space indent guideline. Here are some examples from
libcurl:
* `TCP`, `UDP`, `UNIX`: filters that operate on a socket, providing raw I/O.
* `SOCKET-ACCEPT`: special TCP socket that has a socket that has been `accept()`ed in a `listen()`
* `SSL`: filter that applies TLS en-/decryption and handshake. Manages the underlying TLS backend implementation.
-* `HTTP-PROXY`, `H1-PROXY`, `H2-PROXY`: the first manages the connection to a HTTP proxy server and uses the other depending on which ALPN protocol has been negotiated.
+* `HTTP-PROXY`, `H1-PROXY`, `H2-PROXY`: the first manages the connection to an
+ HTTP proxy server and uses the other depending on which ALPN protocol has
+ been negotiated.
* `SOCKS-PROXY`: filter for the various SOCKS proxy protocol variations
* `HAPROXY`: filter for the protocol of the same name, providing client IP information to a server.
-* `HTTP/2`: filter for handling multiplexed transfers over a HTTP/2 connection
-* `HTTP/3`: filter for handling multiplexed transfers over a HTTP/3+QUIC connection
+* `HTTP/2`: filter for handling multiplexed transfers over an HTTP/2 connection
+* `HTTP/3`: filter for handling multiplexed transfers over an HTTP/3+QUIC connection
* `HAPPY-EYEBALLS`: meta filter that implements IPv4/IPv6 "happy eyeballing". It creates up to 2 sub-filters that race each other for a connection.
* `SETUP`: meta filter that manages the creation of sub-filter chains for a specific transport (e.g. TCP or QUIC).
* `HTTPS-CONNECT`: meta filter that races a TCP+TLS and a QUIC connection against each other to determine if HTTP/1.1, HTTP/2 or HTTP/3 shall be used for a transfer.
Filters may make use of special trace macros like `CURL_TRC_CF(data, cf, msg, ...)`. With `data` being the transfer and `cf` being the filter instance. These traces are normally not active and their execution is guarded so that they are cheap to ignore.
-Users of `curl` may activate them by adding the name of the filter type to the `--trace-config` argument. For example, in order to get more detailed tracing of a HTTP/2 request, invoke curl with:
+Users of `curl` may activate them by adding the name of the filter type to the
+`--trace-config` argument. For example, in order to get more detailed tracing
+of an HTTP/2 request, invoke curl with:
```
> curl -v --trace-config ids,time,http/2 https://curl.se
Meta filters is a catch-all name for filter types that do not change the transfer data in any way but provide other important services to curl. In general, it is possible to do all sorts of silly things with them. One of the commonly used, important things is "eyeballing".
-The `HAPPY-EYEBALLS` filter is involved in the connect phase. It's job is to try the various IPv4 and IPv6 addresses that are known for a server. If only one address family is known (or configured), it tries the addresses one after the other with timeouts calculated from the amount of addresses and the overall connect timeout.
+The `HAPPY-EYEBALLS` filter is involved in the connect phase. Its job is to
+try the various IPv4 and IPv6 addresses that are known for a server. If only
+one address family is known (or configured), it tries the addresses one after
+the other with timeouts calculated from the amount of addresses and the
+overall connect timeout.
When more than one address family is to be tried, it splits the address list into IPv4 and IPv6 and makes parallel attempts. The connection filter chain will look like this:
### Documentation
Writing docs is dead boring and one of the big problems with many open source
-projects. But someone's gotta do it. It makes things a lot easier if you
-submit a small description of your fix or your new features with every
-contribution so that it can be swiftly added to the package documentation.
+projects but someone's gotta do it. It makes things a lot easier if you submit
+a small description of your fix or your new features with every contribution
+so that it can be swiftly added to the package documentation.
The documentation is always made in man pages (nroff formatted) or plain
ASCII files. All HTML files on the website and in the release archives are
you commit.
Add whichever header lines as appropriate, with one line per person if more
-than one person was involved. There is no need to credit yourself unless you are
-using --author=... which hides your identity. Do not include people's e-mail
-addresses in headers to avoid spam, unless they are already public from a
-previous commit; saying `{userid} on github` is OK.
+than one person was involved. There is no need to credit yourself unless you
+are using --author=... which hides your identity. Do not include people's
+email addresses in headers to avoid spam, unless they are already public from
+a previous commit; saying `{userid} on github` is OK.
### Write Access to git Repository
This is *italics*.
-Due to how man pages don't support backticks especially formatted, such
+Due to how man pages do not support backticks especially formatted, such
occurrences in the source will instead just use italics in the generated
output:
This NTLM authentication method is powered by a separate tool,
`ntlm_auth`. Barely anyone uses this method. It was always a quirky
-implementation (including fork + exec), it has limited portability and we
-don't test it in the test suite and CI.
+implementation (including fork + exec), it has limited portability and we do
+not test it in the test suite and CI.
We keep the native NTLM implementation.
- custom maximum download time
- custom least download speed acceptable
- custom output result after completion
- - guesses protocol from host name unless specified
+ - guesses protocol from hostname unless specified
- uses .netrc
- progress bar with time statistics while downloading
- "standard" proxy environment variables support
- active/passive using PORT, EPRT, PASV or EPSV
- single file size information (compare to HTTP HEAD)
- 'type=' URL support
- - dir listing
- - dir listing names-only
+ - directory listing
+ - directory listing names-only
- upload
- upload append
- upload via http-proxy as HTTP PUT
- via HTTP proxy, HTTPS proxy or SOCKS proxy
- all operations can be tunneled through proxy
- customizable to retrieve file modification date
- - no dir depth limit
+ - no directory depth limit
## FTPS (1)
## Behavior
libcurl features an in-memory cache for HSTS hosts, so that subsequent
-HTTP-only requests to a host name present in the cache will get internally
+HTTP-only requests to a hostname present in the cache will get internally
"redirected" to the HTTPS version.
## `curl_easy_setopt()` options:
- `CURLOPT_HSTS_CTRL` - enable HSTS for this easy handle
- - `CURLOPT_HSTS` - specify file name where to store the HSTS cache on close
+ - `CURLOPT_HSTS` - specify filename where to store the HSTS cache on close
(and possibly read from at startup)
## curl command line options
To fix before we remove the experimental label:
- the used QUIC library needs to consider itself non-beta
- - it's fine to "leave" individual backends as experimental if necessary
+ - it is fine to "leave" individual backends as experimental if necessary
# ngtcp2 version
Note that all this happens in addition to IP version happy eyeballing. If the
name resolution for the server gives more than one IP address, curl will try
-all those until one succeeds - just as with all other protocols. And if those
-IP addresses contain both IPv6 and IPv4, those attempts will happen, delayed,
-in parallel (the actual eyeballing).
+all those until one succeeds - just as with all other protocols. If those IP
+addresses contain both IPv6 and IPv4, those attempts will happen, delayed, in
+parallel (the actual eyeballing).
## Known Bugs
options with the `--enable-debug` option.
curl can be built to use a whole range of libraries to provide various useful
-services, and configure will try to auto-detect a decent default. But if you
-want to alter it, you can select how to deal with each individual library.
+services, and configure will try to auto-detect a decent default. If you want
+to alter it, you can select how to deal with each individual library.
## Select TLS backend
conflicting identical symbol names.
When you build with multiple TLS backends, you can select the active one at
-run-time when curl starts up.
+runtime when curl starts up.
## configure finding libs in wrong directory
KB140584 is a must for any Windows developer. Especially important is full
understanding if you are not going to follow the advice given above.
- - [How To Use the C Run-Time](https://support.microsoft.com/help/94248/how-to-use-the-c-run-time)
- - [Run-Time Library Compiler Options](https://docs.microsoft.com/cpp/build/reference/md-mt-ld-use-run-time-library)
+ - [How To Use the C Runtime](https://support.microsoft.com/help/94248/how-to-use-the-c-run-time)
+ - [Runtime Library Compiler Options](https://docs.microsoft.com/cpp/build/reference/md-mt-ld-use-run-time-library)
- [Potential Errors Passing CRT Objects Across DLL Boundaries](https://docs.microsoft.com/cpp/c-runtime-library/potential-errors-passing-crt-objects-across-dll-boundaries)
If your app is misbehaving in some strange way, or it is suffering from memory
# Android
-When building curl for Android it's recommended to use a Linux/macOS environment
-since using curl's `configure` script is the easiest way to build curl
-for Android. Before you can build curl for Android, you need to install the
-Android NDK first. This can be done using the SDK Manager that is part of
-Android Studio. Once you have installed the Android NDK, you need to figure out
-where it has been installed and then set up some environment variables before
-launching `configure`. On macOS, those variables could look like this to compile
-for `aarch64` and API level 29:
+When building curl for Android it is recommended to use a Linux/macOS
+environment since using curl's `configure` script is the easiest way to build
+curl for Android. Before you can build curl for Android, you need to install
+the Android NDK first. This can be done using the SDK Manager that is part of
+Android Studio. Once you have installed the Android NDK, you need to figure
+out where it has been installed and then set up some environment variables
+before launching `configure`. On macOS, those variables could look like this
+to compile for `aarch64` and API level 29:
```bash
export ANDROID_NDK_HOME=~/Library/Android/sdk/ndk/25.1.8937393 # Point into your NDK.
./configure --host aarch64-linux-android --with-pic --disable-shared
-Note that this will not give you SSL/TLS support. If you need SSL/TLS, you have
-to build curl against a SSL/TLS layer, e.g. OpenSSL, because it's impossible for
-curl to access Android's native SSL/TLS layer. To build curl for Android using
-OpenSSL, follow the OpenSSL build instructions and then install `libssl.a` and
-`libcrypto.a` to `$TOOLCHAIN/sysroot/usr/lib` and copy `include/openssl` to
-`$TOOLCHAIN/sysroot/usr/include`. Now you can build curl for Android using
-OpenSSL like this:
+Note that this will not give you SSL/TLS support. If you need SSL/TLS, you
+have to build curl against a SSL/TLS layer, e.g. OpenSSL, because it is
+impossible for curl to access Android's native SSL/TLS layer. To build curl
+for Android using OpenSSL, follow the OpenSSL build instructions and then
+install `libssl.a` and `libcrypto.a` to `$TOOLCHAIN/sysroot/usr/lib` and copy
+`include/openssl` to `$TOOLCHAIN/sysroot/usr/include`. Now you can build curl
+for Android using OpenSSL like this:
```bash
LIBS="-lssl -lcrypto -lc++" # For OpenSSL/BoringSSL. In general, you will need to the SSL/TLS layer's transitive dependencies if you are linking statically.
This enables users to use untrusted, public gateways without worrying they might return invalid/malicious bytes.
## IPFS and IPNS protocol handling
-There are various ways to access data from the IPFS network. One such way is through the concept of public "[gateways](https://docs.ipfs.tech/concepts/ipfs-gateway/#overview)". The short version is that entities can offer gateway services. An example here that is hosted by Protocol Labs (who also makes IPFS) is `dweb.link` and `ipfs.io`. Both sites expose gateway functionality. Getting a file through `ipfs.io` looks like this: `https://ipfs.io/ipfs/bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi`
-If you were to be [running your own IPFS node](https://docs.ipfs.tech/how-to/command-line-quick-start/) then you, by default, also have a [local gateway](https://specs.ipfs.tech/http-gateways/) running. In it's default configuration the earlier example would then also work in this link: `http://127.0.0.1:8080/ipfs/bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi`
+There are various ways to access data from the IPFS network. One such way is
+through the concept of public
+"[gateways](https://docs.ipfs.tech/concepts/ipfs-gateway/#overview)". The
+short version is that entities can offer gateway services. An example here
+that is hosted by Protocol Labs (who also makes IPFS) is `dweb.link` and
+`ipfs.io`. Both sites expose gateway functionality. Getting a file through
+`ipfs.io` looks like this:
+`https://ipfs.io/ipfs/bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi`
+
+If you were to be [running your own IPFS
+node](https://docs.ipfs.tech/how-to/command-line-quick-start/) then you, by
+default, also have a [local gateway](https://specs.ipfs.tech/http-gateways/)
+running. In its default configuration the earlier example would then also work
+in this link:
+
+`http://127.0.0.1:8080/ipfs/bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi`
## cURL handling of the IPFS protocols
-The IPFS integration in cURL hides this gateway logic for you. So instead of providing a full URL to a file on IPFS like this:
+
+The IPFS integration in cURL hides this gateway logic for you. Instead of
+providing a full URL to a file on IPFS like this:
+
```
curl http://127.0.0.1:8080/ipfs/bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi
```
curl ipfs://bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi
```
-With the IPFS protocol way of asking a file, cURL still needs to know the gateway. curl essentially just rewrites the IPFS based URL to a gateway URL.
+With the IPFS protocol way of asking a file, cURL still needs to know the
+gateway. curl essentially just rewrites the IPFS based URL to a gateway URL.
### IPFS_GATEWAY environment variable
-If the `IPFS_GATEWAY` environment variable is found, it's value is used as gateway.
+
+If the `IPFS_GATEWAY` environment variable is found, its value is used as
+gateway.
### Automatic gateway detection
When you provide no additional details to cURL then cURL will:
-1. First look for the `IPFS_GATEWAY` environment variable and use that if it's set.
-2. Look for the file: `~/.ipfs/gateway`. If it can find that file then it means that you have a local gateway running and that file contains the URL to your local gateway.
+1. First look for the `IPFS_GATEWAY` environment variable and use that if it
+ is set.
+2. Look for the file: `~/.ipfs/gateway`. If it can find that file then it
+ means that you have a local gateway running and that file contains the URL
+ to your local gateway.
-If cURL fails you'll be presented with an error message and a link to this page to the option most applicable to solving the issue.
+If cURL fails you will be presented with an error message and a link to this
+page to the option most applicable to solving the issue.
### `--ipfs-gateway` argument
-You can also provide a `--ipfs-gateway` argument to cURL. This overrules any other gateway setting. curl won't fallback to the other options if the provided gateway didn't work.
+
+You can also provide a `--ipfs-gateway` argument to cURL. This overrules any
+other gateway setting. curl will not fallback to the other options if the
+provided gateway did not work.
## Gateway redirects
-A gateway could redirect to another place. For example, `dweb.link` redirects [path based](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#path-gateway) requests to [subdomain based](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#subdomain-gateway) ones. So a request to:
-```
-curl ipfs://bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi --ipfs-gateway https://dweb.link
-```
+
+A gateway could redirect to another place. For example, `dweb.link` redirects
+[path based](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#path-gateway)
+requests to [subdomain
+based](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#subdomain-gateway)
+ones. A request using:
+
+ curl ipfs://bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi --ipfs-gateway https://dweb.link
+
Which would be translated to:
-```
-https://dweb.link/ipfs/bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi
-```
+
+ https://dweb.link/ipfs/bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi
+
Will redirect to:
-```
-https://bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi.ipfs.dweb.link
-```
+
+ https://bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi.ipfs.dweb.link
+
If you trust this behavior from your gateway of choice then passing the `-L` option will follow the redirect.
## Error messages and hints
+
Depending on the arguments, cURL could present the user with an error.
### Gateway file and environment variable
-cURL tried to look for the file: `~/.ipfs/gateway` but couldn't find it. It also tried to look for the `IPFS_GATEWAY` environment variable but couldn't find that either. This happens when no extra arguments are passed to cURL and letting it try to figure it out [automatically](#automatic-gateway-detection).
-Any IPFS implementation that has gateway support should expose it's URL in `~/.ipfs/gateway`. If you are already running a gateway, make sure it exposes the file where cURL expects to find it.
+cURL tried to look for the file: `~/.ipfs/gateway` but could not find it. It
+also tried to look for the `IPFS_GATEWAY` environment variable but could not
+find that either. This happens when no extra arguments are passed to cURL and
+letting it try to figure it out [automatically](#automatic-gateway-detection).
-Alternatively you could set the `IPFS_GATEWAY` environment variable or pass the `--ipfs-gateway` flag to the cURL command.
+Any IPFS implementation that has gateway support should expose its URL in
+`~/.ipfs/gateway`. If you are already running a gateway, make sure it exposes
+the file where cURL expects to find it.
+
+Alternatively you could set the `IPFS_GATEWAY` environment variable or pass
+the `--ipfs-gateway` flag to the cURL command.
### Malformed gateway URL
-The command executed evaluates in an invalid URL. This could be anywhere in the URL, but a likely point is a wrong gateway URL.
-Inspect the URL set via the `IPFS_GATEWAY` environment variable or passed with the `--ipfs-gateway` flag.
-Alternatively opt to go for the [automatic](#automatic-gateway-detection) gateway detection.
+The command executed evaluates in an invalid URL. This could be anywhere in
+the URL, but a likely point is a wrong gateway URL.
+
+Inspect the URL set via the `IPFS_GATEWAY` environment variable or passed with
+the `--ipfs-gateway` flag. Alternatively opt to go for the
+[automatic](#automatic-gateway-detection) gateway detection.
curl ftp://ftp.example.com/README
-Get a web page from a server using port 8000:
+Get a webpage from a server using port 8000:
curl http://www.example.com:8000/
## Download to a File
-Get a web page and store in a local file with a specific name:
+Get a webpage and store in a local file with a specific name:
curl -o thatpage.html http://www.example.com/
-Get a web page and store in a local file, make the local file get the name of
-the remote document (if no file name part is specified in the URL, this will
+Get a webpage and store in a local file, make the local file get the name of
+the remote document (if no filename part is specified in the URL, this will
fail):
curl -O http://www.example.com/index.html
curl -T uploadfile -u user:passwd ftp://ftp.example.com/myfile
-Upload a local file to the remote site, and use the local file name at the
+Upload a local file to the remote site, and use the local filename at the
remote site too:
curl -T uploadfile -u user:passwd ftp://ftp.example.com/
curl -v ftp://ftp.example.com/
To get even more details and information on what curl does, try using the
-`--trace` or `--trace-ascii` options with a given file name to log to, like
+`--trace` or `--trace-ascii` options with a given filename to log to, like
this:
curl --trace trace.txt www.haxx.se
`-F` accepts parameters like `-F "name=contents"`. If you want the contents to
be read from a file, use `@filename` as contents. When specifying a file, you
can also specify the file content type by appending `;type=<mime type>` to the
-file name. You can also post the contents of several files in one field. For
+filename. You can also post the contents of several files in one field. For
example, the field name `coolfiles` is used to send three files, with
different content types using the following syntax:
default type `application/octet-stream`.
Emulate a fill-in form with `-F`. Let's say you fill in three fields in a
-form. One field is a file name which to post, one field is your name and one
+form. One field is a filename which to post, one field is your name and one
field is a file description. We want to post the file we have written named
`cooltext.txt`. To let curl do the posting of this data instead of your
favorite browser, you have to read the HTML source of the form page and find
## Config File
Curl automatically tries to read the `.curlrc` file (or `_curlrc` file on
-Microsoft Windows systems) from the user's home dir on startup.
+Microsoft Windows systems) from the user's home directory on startup.
The config file could be made up with normal command line switches, but you
can also specify the long options without the dashes to make it more
url = "http://help.with.curl.example.com/curlhelp.html"
You can specify another config file to be read by using the `-K`/`--config`
-flag. If you set config file name to `-` it will read the config from stdin,
+flag. If you set config filename to `-` it will read the config from stdin,
which can be handy if you want to hide options from being visible in process
tables etc:
## Extra Headers
When using curl in your own programs, you may end up needing to pass on your
-own custom headers when getting a web page. You can do this by using the `-H`
+own custom headers when getting a webpage. You can do this by using the `-H`
flag.
Example, send the header `X-you-and-me: yes` to the server when getting a
curl ftp://user:passwd@my.example.com/README
If you want the README file from the root directory of that same site, you
-need to specify the absolute file name:
+need to specify the absolute filename:
curl ftp://user:passwd@my.example.com//README
-(I.e with an extra slash in front of the file name.)
+(I.e with an extra slash in front of the filename.)
## SFTP and SCP and Path Names
## Network Interface
-Get a web page from a server using a specified port for the interface:
+Get a webpage from a server using a specified port for the interface:
curl --interface eth0:1 http://www.example.com/
NO_PROXY
-If the host name matches one of these strings, or the host is within the
+If the hostname matches one of these strings, or the host is within the
domain of one of these strings, transactions with that node will not be done
over proxy. When a domain is used, it needs to start with a period. A user can
specify that both www.example.com and foo.example.com should not use a proxy
## Behavior differences
Connections are shared fine between different easy handles, but the
-"authentication contexts" are not. So for example doing HTTP Digest auth with
-one handle for a particular transfer and then continue on with another handle
-that reuses the same connection, the second handle cannot send the necessary
+"authentication contexts" are not. For example doing HTTP Digest auth with one
+handle for a particular transfer and then continue on with another handle that
+reuses the same connection, the second handle cannot send the necessary
Authorization header at once since the context is only kept in the original
easy handle.
### `Makefile`
-The new CVE web page file name needs to be added in the `Makefile`'s `CVELIST`
+The new CVE webpage filename needs to be added in the `Makefile`'s `CVELIST`
macro.
When the markdown is in place and the `Makefile` and `vuln.pm` are updated,
The Uniform Resource Locator format is how you specify the address of a
particular resource on the Internet. You know these, you have seen URLs like
https://curl.se or https://example.com a million times. RFC 3986 is the
- canonical spec. And yeah, the formal name is not URL, it is URI.
+ canonical spec. The formal name is not URL, it is **URI**.
## Host
- The host name is usually resolved using DNS or your /etc/hosts file to an IP
+ The hostname is usually resolved using DNS or your /etc/hosts file to an IP
address and that is what curl will communicate with. Alternatively you specify
the IP address directly in the URL instead of a name.
For development and other trying out situations, you can point to a different
- IP address for a host name than what would otherwise be used, by using curl's
+ IP address for a hostname than what would otherwise be used, by using curl's
[`--resolve`](https://curl.se/docs/manpage.html#--resolve) option:
curl --resolve www.example.org:80:127.0.0.1 http://www.example.org/
or in some cases UDP. Normally you do not have to take that into
consideration, but at times you run test servers on other ports or
similar. Then you can specify the port number in the URL with a colon and a
- number immediately following the host name. Like when doing HTTP to port
+ number immediately following the hostname. Like when doing HTTP to port
1234:
curl http://www.example.org:1234/
The path part is just sent off to the server to request that it sends back
the associated response. The path is what is to the right side of the slash
- that follows the host name and possibly port number.
+ that follows the hostname and possibly port number.
# Fetch a page
## GET
The simplest and most common request/operation made using HTTP is to GET a
- URL. The URL could itself refer to a web page, an image or a file. The client
+ URL. The URL could itself refer to a webpage, an image or a file. The client
issues a GET request to the server and receives the document it asked for.
If you issue the command line
curl https://curl.se
- you get a web page returned in your terminal window. The entire HTML document
+ you get a webpage returned in your terminal window. The entire HTML document
that that URL holds.
All HTTP replies contain a set of response headers that are normally hidden,
This method is mainly designed to better support file uploads. A form that
allows a user to upload a file could be written like this in HTML:
-```html
-<form method="POST" enctype='multipart/form-data' action="upload.cgi">
- <input type=file name=upload>
- <input type=submit name=press value="OK">
-</form>
-```
+ <form method="POST" enctype='multipart/form-data' action="upload.cgi">
+ <input name=upload type=file>
+ <input type=submit name=press value="OK">
+ </form>
This clearly shows that the Content-Type about to be sent is
`multipart/form-data`.
The way the web browsers do "client side state control" is by using
cookies. Cookies are just names with associated contents. The cookies are
sent to the client by the server. The server tells the client for what path
- and host name it wants the cookie sent back, and it also sends an expiration
+ and hostname it wants the cookie sent back, and it also sends an expiration
date and a few more properties.
When a client communicates with a server with a name and path as previously
It should be noted that curl selects which methods to use on its own
depending on what action to ask for. `-d` will do POST, `-I` will do HEAD and
- so on. If you use the
- [`--request`](https://curl.se/docs/manpage.html#-X) / `-X` option you
- can change the method keyword curl selects, but you will not modify curl's
- behavior. This means that if you for example use -d "data" to do a POST, you
- can modify the method to a `PROPFIND` with `-X` and curl will still think it
- sends a POST . You can change the normal GET to a POST method by simply
- adding `-X POST` in a command line like:
+ so on. If you use the [`--request`](https://curl.se/docs/manpage.html#-X) /
+ `-X` option you can change the method keyword curl selects, but you will not
+ modify curl's behavior. This means that if you for example use -d "data" to
+ do a POST, you can modify the method to a `PROPFIND` with `-X` and curl will
+ still think it sends a POST. You can change the normal GET to a POST method
+ by simply adding `-X POST` in a command line like:
curl -X POST http://example.org/
- ... but curl will still think and act as if it sent a GET so it will not send
- any request body etc.
+ curl will however still act as if it sent a GET so it will not send any
+ request body etc.
# Web Login
considered a security risk to mix different implementations and assume the
same behavior!
-For example, if you use one parser to check if a URL uses a good host name or
+For example, if you use one parser to check if a URL uses a good hostname or
the correct auth field, and then pass on that same URL to a *second* parser,
there will always be a risk it treats the same URL differently. There is no
right and wrong in URL land, only differences of opinions.
any of the specifications. This is a shortcut to entering URLs that was
supported by browsers early on and has been mimicked by curl.
-Based on what the host name starts with, curl will "guess" what protocol to
+Based on what the hostname starts with, curl will "guess" what protocol to
use:
- `ftp.` means FTP
## SMTP
-The path part of a SMTP request specifies the host name to present during
+The path part of a SMTP request specifies the hostname 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
+attempt to resolve the local computer's hostname. 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
the same manner we always announce releases. It gets sent to the
curl-announce, curl-library and curl-users mailing lists.
-- The security web page on the website should get the new vulnerability
+- The security webpage on the website should get the new vulnerability
mentioned.
## security (at curl dot se)
## --vernum
Outputs version information about the installed libcurl, in numerical mode.
-This outputs the version number, in hexadecimal, with 8 bits for each part:
-major, minor, and patch. So that libcurl 7.7.4 would appear as 070704 and libcurl
-12.13.14 would appear as 0c0d0e... Note that the initial zero might be
+This shows the version number, in hexadecimal, using 8 bits for each part:
+major, minor, and patch numbers. This makes libcurl 7.7.4 appear as 070704 and
+libcurl 12.13.14 appear as 0c0d0e... Note that the initial zero might be
omitted. (This option was broken in the 7.15.0 release.)
# EXAMPLES
or options (created as if CURLOPT_SHARE(3) was set to NULL).
If the source handle has HSTS or alt-svc enabled, the duplicate gets data read
-data from the main file name to populate the cache.
+data from the main filename to populate the cache.
In multi-threaded programs, this function must be called in a synchronous way,
the input handle may not be in use when cloned.
curl_easy_send(3) does not work on connections that were created without
this option.
-The call returns **CURLE_AGAIN** if it's not possible to send data right now
+The call returns **CURLE_AGAIN** if it is not possible to send data right now
- the socket is used in non-blocking mode internally. When **CURLE_AGAIN**
is returned, use your operating system facilities like *select(2)* to wait
until the socket is writable. The socket may be obtained using
curl_easy_getinfo(3) with CURLINFO_ACTIVESOCKET(3).
-Furthermore if you wait on the socket and it tells you it's writable,
-curl_easy_send(3) may return **CURLE_AGAIN** if the only data that was
-sent was for internal SSL processing, and no other data could be sent.
+Furthermore if you wait on the socket and it tells you it is writable,
+curl_easy_send(3) may return **CURLE_AGAIN** if the only data that was sent
+was for internal SSL processing, and no other data could be sent.
# EXAMPLE
## CURLOPT_WILDCARDMATCH
-Transfer multiple files according to a file name pattern. See
+Transfer multiple files according to a filename pattern. See
CURLOPT_WILDCARDMATCH(3)
# CALLBACK OPTIONS
## CURLOPT_NETRC_FILE
-&.netrc file name. See CURLOPT_NETRC_FILE(3)
+.netrc filename. See CURLOPT_NETRC_FILE(3)
## CURLOPT_USERPWD
## CURLOPT_ALTSVC
-Specify the Alt-Svc: cache file name. See CURLOPT_ALTSVC(3)
+Specify the Alt-Svc: cache filename. See CURLOPT_ALTSVC(3)
## CURLOPT_ALTSVC_CTRL
## CURLOPT_SSL_VERIFYHOST
-Verify the host name in the SSL certificate. See CURLOPT_SSL_VERIFYHOST(3)
+Verify the hostname in the SSL certificate. See CURLOPT_SSL_VERIFYHOST(3)
## CURLOPT_DOH_SSL_VERIFYHOST
-Verify the host name in the DoH (DNS-over-HTTPS) SSL certificate. See
+Verify the hostname in the DoH (DNS-over-HTTPS) SSL certificate. See
CURLOPT_DOH_SSL_VERIFYHOST(3)
## CURLOPT_PROXY_SSL_VERIFYHOST
-Verify the host name in the proxy SSL certificate. See
+Verify the hostname in the proxy SSL certificate. See
CURLOPT_PROXY_SSL_VERIFYHOST(3)
## CURLOPT_SSL_VERIFYPEER
## CURLOPT_SSH_PUBLIC_KEYFILE
-File name of public key. See CURLOPT_SSH_PUBLIC_KEYFILE(3)
+Filename of the public key. See CURLOPT_SSH_PUBLIC_KEYFILE(3)
## CURLOPT_SSH_PRIVATE_KEYFILE
-File name of private key. See CURLOPT_SSH_PRIVATE_KEYFILE(3)
+Filename of the private key. See CURLOPT_SSH_PRIVATE_KEYFILE(3)
## CURLOPT_SSH_KNOWNHOSTS
-File name with known hosts. See CURLOPT_SSH_KNOWNHOSTS(3)
+Filename with known hosts. See CURLOPT_SSH_KNOWNHOSTS(3)
## CURLOPT_SSH_KEYFUNCTION
## CURLFORM_FILENAME
is used in combination with *CURLFORM_FILE*. Followed by a pointer to a
-string, it tells libcurl to use the given string as the *filename* in the
-file upload part instead of the actual file name.
+string, it tells libcurl to use the given string as the *filename* in the file
+upload part instead of the actual filename.
## CURLFORM_BUFFER
## http-proxy
-Involved when transfers are tunneled through a HTTP proxy. "h1-proxy" or
+Involved when transfers are tunneled through an HTTP proxy. "h1-proxy" or
"h2-proxy" are also involved, depending on the HTTP version negotiated with
the proxy.
be NULL to detach the previous part contents settings. Filename storage can
be safely be reused after this call.
-As a side effect, the part's remote file name is set to the base name of the
+As a side effect, the part's remote filename is set to the base name of the
given *filename* if it is a valid named file. This can be undone or
overridden by a subsequent call to curl_mime_filename(3).
# DESCRIPTION
-curl_mime_filename(3) sets a mime part's remote file name. When remote
-file name is set, content data is processed as a file, whatever is the part's
-content source. A part's remote file name is transmitted to the server in the
+curl_mime_filename(3) sets a mime part's remote filename. When remote
+filename is set, content data is processed as a file, whatever is the part's
+content source. A part's remote filename is transmitted to the server in the
associated Content-Disposition generated header.
-*part* is the part's handle to assign the remote file name to.
+*part* is the part's handle to assign the remote filename to.
-*filename* points to the null-terminated file name string; it may be set
-to NULL to remove a previously attached remote file name.
+*filename* points to the null-terminated filename string; it may be set
+to NULL to remove a previously attached remote filename.
-The remote file name string is copied into the part, thus the associated
+The remote filename string is copied into the part, thus the associated
storage may safely be released or reused after call. Setting a part's file
name multiple times is valid: only the value set by the last call is retained.
- application/form-data for an HTTP form post.
-- If a remote file name is set, the mime type is taken from the file name
+- If a remote filename is set, the mime type is taken from the file name
extension, or application/octet-stream by default.
- For a multipart part, multipart/mixed.
## CURLU_URLENCODE
-If set, curl_url_get(3) URL encodes the host name part when a full URL
+If set, curl_url_get(3) URL encodes the hostname part when a full URL
is retrieved. If not set (default), libcurl returns the URL with the host name
"raw" to support IDN names to appear as-is. IDN host names are typically using
non-ASCII bytes that otherwise gets percent-encoded.
Note that even when not asking for URL encoding, the '%' (byte 37) is URL
-encoded to make sure the host name remains valid.
+encoded to make sure the hostname remains valid.
## CURLU_PUNYCODE
IDN name).
If libcurl is built without IDN capabilities, using this bit makes
-curl_url_get(3) return *CURLUE_LACKS_IDN* if the host name contains
+curl_url_get(3) return *CURLUE_LACKS_IDN* if the hostname contains
anything outside the ASCII range.
(Added in curl 7.88.0)
## CURLU_PUNY2IDN
If set and asked to retrieve the **CURLUPART_HOST** or **CURLUPART_URL**
-parts, libcurl returns the host name in its IDN (International Domain Name)
+parts, libcurl returns the hostname in its IDN (International Domain Name)
UTF-8 version if it otherwise is a punycode version. If the punycode name
cannot be converted to IDN correctly, libcurl returns
*CURLUE_BAD_HOSTNAME*.
If libcurl is built without IDN capabilities, using this bit makes
-curl_url_get(3) return *CURLUE_LACKS_IDN* if the host name is using
+curl_url_get(3) return *CURLUE_LACKS_IDN* if the hostname is using
punycode.
(Added in curl 8.3.0)
## CURLUPART_HOST
-The host name. If it is an IPv6 numeric address, the zone id is not part of it
+The hostname. If it is an IPv6 numeric address, the zone id is not part of it
but is provided separately in *CURLUPART_ZONEID*. IPv6 numerical addresses
are returned within brackets ([]).
## CURLUPART_ZONEID
-If the host name is a numeric IPv6 address, this field might also be set.
+If the hostname is a numeric IPv6 address, this field might also be set.
## CURLUPART_PORT
string must point to a correctly formatted "RFC 3986+" URL or be a NULL
pointer.
-Unless *CURLU_NO_AUTHORITY* is set, a blank host name is not allowed in
+Unless *CURLU_NO_AUTHORITY* is set, a blank hostname is not allowed in
the URL.
## CURLUPART_SCHEME
## CURLUPART_HOST
-The host name. If it is International Domain Name (IDN) the string must then
-be encoded as your locale says or UTF-8 (when WinIDN is used). If it is a
+The hostname. If it is International Domain Name (IDN) the string must then be
+encoded as your locale says or UTF-8 (when WinIDN is used). If it is a
bracketed IPv6 numeric address it may contain a zone id (or you can use
*CURLUPART_ZONEID*).
-Unless *CURLU_NO_AUTHORITY* is set, a blank host name is not allowed to set.
+Unless *CURLU_NO_AUTHORITY* is set, a blank hostname is not allowed to set.
## CURLUPART_ZONEID
-If the host name is a numeric IPv6 address, this field can also be set.
+If the hostname is a numeric IPv6 address, this field can also be set.
## CURLUPART_PORT
## CURLU_GUESS_SCHEME
If set, allows the URL to be set without a scheme and it instead "guesses"
-which scheme that was intended based on the host name. If the outermost
-subdomain name matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that scheme
-is used, otherwise it picks HTTP. Conflicts with the
-*CURLU_DEFAULT_SCHEME* option which takes precedence if both are set.
+which scheme that was intended based on the hostname. If the outermost
+subdomain name matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that scheme is
+used, otherwise it picks HTTP. Conflicts with the *CURLU_DEFAULT_SCHEME*
+option which takes precedence if both are set.
## CURLU_NO_AUTHORITY
## CURL_OPENLDAP_TRACE
OpenLDAP tracing is enabled if this variable exists and its value is 1 or
-greater. There's a number of debug levels, refer to *openldap.c* comments.
+greater. There is a number of debug levels, refer to *openldap.c* comments.
## NO_PROXY
This has the same functionality as the CURLOPT_NOPROXY(3) option: it
-gives libcurl a comma-separated list of host name patterns for which libcurl
+gives libcurl a comma-separated list of hostname patterns for which libcurl
should not use a proxy.
## NTLMUSER
## SSLKEYLOGFILE
When set and libcurl runs with a SSL backend that supports this feature,
-libcurl saves SSL secrets into the given file name. Using those SSL secrets,
+libcurl saves SSL secrets into the given filename. Using those SSL secrets,
other tools (such as Wireshark) can decrypt the SSL communication and
analyze/view the traffic.
## CURLE_AGAIN (81)
-Socket is not ready for send/recv wait till it's ready and try again. This
-return code is only returned from curl_easy_recv(3) and
-curl_easy_send(3) (Added in 7.18.2)
+Socket is not ready for send/recv. Wait until it is ready and try again. This
+return code is only returned from curl_easy_recv(3) and curl_easy_send(3)
+(Added in 7.18.2)
## CURLE_SSL_CRL_BADFILE (82)
Protocols that do not have any form of cryptographic authentication cannot
with any certainty know that they communicate with the right remote server.
-If your application is using a fixed scheme or fixed host name, it is not safe
+If your application is using a fixed scheme or fixed hostname, it is not safe
as long as the connection is unauthenticated. There can be a man-in-the-middle
or in fact the whole server might have been replaced by an evil actor.
# Server-supplied Names
A server can supply data which the application may, in some cases, use as a
-file name. The curl command-line tool does this with
-*--remote-header-name*, using the Content-disposition: header to generate
-a file name. An application could also use CURLINFO_EFFECTIVE_URL(3) to
-generate a file name from a server-supplied redirect URL. Special care must be
-taken to sanitize such names to avoid the possibility of a malicious server
-supplying one like **"/etc/passwd"**, **"autoexec.bat"**, **"prn:"**
-or even **".bashrc"**.
+filename. The curl command-line tool does this with *--remote-header-name*,
+using the Content-disposition: header to generate a filename. An application
+could also use CURLINFO_EFFECTIVE_URL(3) to generate a filename from a
+server-supplied redirect URL. Special care must be taken to sanitize such
+names to avoid the possibility of a malicious server supplying one like
+**"/etc/passwd"**, **"autoexec.bat"**, **"prn:"** or even **".bashrc"**.
# Server Certificates
curl_mime_data(3), file using curl_mime_filedata(3) and user-defined data
read callback using curl_mime_data_cb(3). curl_mime_name(3) sets a part's
(i.e.: form field) name, while curl_mime_filename(3) fills in the remote
-file name. With curl_mime_type(3), you can tell the MIME type of a part,
+filename. With curl_mime_type(3), you can tell the MIME type of a part,
curl_mime_headers(3) allows defining the part's headers. When a multi-part
body is no longer needed, you can destroy it using curl_mime_free(3).
curl_mime_filename(part, NULL);
~~~
-Use of curl_mime_filedata(3) sets the remote file name as a side effect:
-it is therefore necessary to clear it for *CURLFORM_FILECONTENT*
-emulation.
+Use of curl_mime_filedata(3) sets the remote filename as a side effect: it is
+therefore necessary to clear it for *CURLFORM_FILECONTENT* emulation.
# Showing Progress
function pointer you pass to libcurl is then called on irregular intervals
with information about the current transfer.
-Set the progress callback by using CURLOPT_PROGRESSFUNCTION(3). And pass
-a pointer to a function that matches this prototype:
+Set the progress callback by using CURLOPT_PROGRESSFUNCTION(3). Pass a pointer
+to a function that matches this prototype:
~~~c
int progress_callback(void *clientp,
~~~c
curl_easy_setopt(handle, CURLOPT_PROXYUSERPWD, "user:password");
~~~
-If you want to, you can specify the host name only in the
+If you want to, you can specify the hostname only in the
CURLOPT_PROXY(3) option, and set the port number separately with
CURLOPT_PROXYPORT(3).
## Proxy Auto-Config
-Netscape first came up with this. It is basically a web page (usually using a
-&.pac extension) with a JavaScript that when executed by the browser with the
+Netscape first came up with this. It is basically a webpage (usually using a
+.pac extension) with a JavaScript that when executed by the browser with the
requested URL as input, returns information to the browser on how to connect
to the URL. The returned information might be "DIRECT" (which means no proxy
should be used), "PROXY host:port" (to tell the browser where the proxy for
Perhaps the most advanced cookie operation libcurl offers, is saving the
entire internal cookie state back into a Netscape/Mozilla formatted cookie
-file. We call that the cookie-jar. When you set a file name with
-CURLOPT_COOKIEJAR(3), that file name is created and all received cookies
-get stored in it when curl_easy_cleanup(3) is called. This enables
-cookies to get passed on properly between multiple handles without any
-information getting lost.
+file. We call that the cookie-jar. When you set a filename with
+CURLOPT_COOKIEJAR(3), that filename is created and all received cookies get
+stored in it when curl_easy_cleanup(3) is called. This enables cookies to get
+passed on properly between multiple handles without any information getting
+lost.
# FTP Peculiarities We Need
the remote server which IP address and port number to connect to. This is made
with the CURLOPT_FTPPORT(3) option. If you set it to "-", libcurl uses your
system's "default IP address". If you want to use a particular IP, you can set
-the full IP address, a host name to resolve to an IP address or even a local
+the full IP address, a hostname to resolve to an IP address or even a local
network interface name that libcurl gets the IP address from.
When doing the "PORT" approach, libcurl attempts to use the EPRT and the LPRT
You can call both of these multiple times, as long as all calls meet
these requirements and the number of calls to each is the same.
-The global constant situation merits special consideration when the
-code you are writing to use libcurl is not the main program, but rather
-a modular piece of a program, e.g. another library. As a module,
-your code does not know about other parts of the program -- it does not
-know whether they use libcurl or not. And its code does not necessarily
-run at the start and end of the whole program.
+The global constant situation merits special consideration when the code you
+are writing to use libcurl is not the main program, but rather a modular piece
+of a program, e.g. another library. As a module, your code does not know about
+other parts of the program -- it does not know whether they use libcurl or
+not. Its code does not necessarily run at the start and end of the whole
+program.
A module like this must have global constant functions of its own, just like
curl_global_init(3) and curl_global_cleanup(3). The module thus
This option has not been thoroughly tested with clear text protocols that can
be upgraded/downgraded to/from SSL: FTP, SMTP, POP3, IMAP when used with
-CURLOPT_USE_SSL(3). Though you can to retrieve the SSL pointer, it's
-possible that before you can do that, data (including auth) may have already
-been sent over a connection after it was upgraded.
+CURLOPT_USE_SSL(3). Though you can to retrieve the SSL pointer, it is possible
+that before you can do that, data (including auth) may have already been sent
+over a connection after it was upgraded.
Renegotiation. If unsafe renegotiation or renegotiation in a way that the
certificate is allowed to change is allowed by your SSL library this may occur
# DESCRIPTION
-Pass a long to indicate **max**. The set number is used as the maximum
-amount of simultaneously open connections to a single host (a host being the
-same as a host name + port number pair). For each new session to a host,
-libcurl might open a new connection up to the limit set by
-CURLMOPT_MAX_HOST_CONNECTIONS(3). When the limit is reached, new
-sessions are kept pending until a connection becomes available.
+Pass a long to indicate **max**. The set number is used as the maximum amount
+of simultaneously open connections to a single host (a host being the same as
+a hostname + port number pair). For each new session to a host, libcurl might
+open a new connection up to the limit set by
+CURLMOPT_MAX_HOST_CONNECTIONS(3). When the limit is reached, new sessions are
+kept pending until a connection becomes available.
The default **max** value is 0, unlimited. This set limit is also used for
proxy connections, and then the proxy is considered to be the host for which
it back to after a transfer, unless **CURLALTSVC_READONLYFILE** is set in
CURLOPT_ALTSVC_CTRL(3).
-Specify a blank file name ("") to make libcurl not load from a file at all.
+Specify a blank filename ("") to make libcurl not load from a file at all.
# DEFAULT
## www.example.comp
-Host name for the source origin
+Hostname for the source origin
## 8443
## second.example.com
-Host name for the destination host
+Hostname for the destination host
## 443
## region
The argument is a geographic area of a resources collection.
-It is extracted from the host name specified in the URL if omitted.
+It is extracted from the hostname specified in the URL if omitted.
## service
-The argument is a function provided by a cloud.
-It is extracted from the host name specified in the URL if omitted.
+The argument is a function provided by a cloud. It is extracted from the
+hostname specified in the URL if omitted.
NOTE: This call set CURLOPT_HTTPAUTH(3) to CURLAUTH_AWS_SIGV4.
Calling CURLOPT_HTTPAUTH(3) with CURLAUTH_AWS_SIGV4 is the same
A sha256 checksum of the request payload is used as input to the signature
calculation. For POST requests, this is a checksum of the provided
-CURLOPT_POSTFIELDS(3). Otherwise, it's the checksum of an empty buffer.
-For requests like PUT, you can provide your own checksum in an HTTP header named
+CURLOPT_POSTFIELDS(3). Otherwise, it is the checksum of an empty buffer. For
+requests like PUT, you can provide your own checksum in an HTTP header named
**x-provider2-content-sha256**.
For **aws:s3**, a **x-amz-content-sha256** header is added to every request
Each single string should be written using the format
HOST:PORT:CONNECT-TO-HOST:CONNECT-TO-PORT where HOST is the host of the
-request, PORT is the port of the request, CONNECT-TO-HOST is the host name to
+request, PORT is the port of the request, CONNECT-TO-HOST is the hostname to
connect to, and CONNECT-TO-PORT is the port to connect to.
The first string that matches the request's host and port is used.
# NAME
-CURLOPT_COOKIEFILE - file name to read cookies from
+CURLOPT_COOKIEFILE - filename to read cookies from
# SYNOPSIS
# DESCRIPTION
Pass a pointer to a null-terminated string as parameter. It should point to
-the file name of your file holding cookie data to read. The cookie data can be
+the filename of your file holding cookie data to read. The cookie data can be
in either the old Netscape / Mozilla cookie data format or just regular HTTP
headers (Set-Cookie style) dumped to a file.
subsequent requests with this handle.
By passing the empty string ("") to this option, you enable the cookie engine
-without reading any initial cookies. If you tell libcurl the file name is "-"
+without reading any initial cookies. If you tell libcurl the filename is "-"
(just a single minus sign), libcurl instead reads from stdin.
This option only **reads** cookies. To make libcurl write cookies to file,
# NAME
-CURLOPT_COOKIEJAR - file name to store cookies to
+CURLOPT_COOKIEJAR - filename to store cookies to
# SYNOPSIS
regular HTTP-style header (Set-Cookie: ...) format. This option also enables
the cookie engine. This adds that single cookie to the internal cookie store.
-We strongly advice against loading cookies from a HTTP header file, as that is
-an inferior data exchange format.
+We strongly advice against loading cookies from an HTTP header file, as that
+is an inferior data exchange format.
Exercise caution if you are using this option and multiple transfers may
occur. If you use the Set-Cookie format and the string does not specify a
# NAME
-CURLOPT_DOH_SSL_VERIFYHOST - verify the host name in the DoH SSL certificate
+CURLOPT_DOH_SSL_VERIFYHOST - verify the hostname in the DoH SSL certificate
# SYNOPSIS
# DESCRIPTION
Pass a long set to 2L as asking curl to *verify* the DoH (DNS-over-HTTPS)
-server's certificate name fields against the host name.
+server's certificate name fields against the hostname.
This option is the DoH equivalent of CURLOPT_SSL_VERIFYHOST(3) and
only affects requests to the DoH server.
name to which you meant to connect to, or the connection fails.
Curl considers the DoH server the intended one when the Common Name field or a
-Subject Alternate Name field in the certificate matches the host name in the
+Subject Alternate Name field in the certificate matches the hostname in the
DoH URL to which you told Curl to connect.
When the *verify* value is set to 1L it is treated the same as 2L. However
Authenticating the certificate is not enough to be sure about the server. You
typically also want to ensure that the server is the server you mean to be
talking to. Use CURLOPT_DOH_SSL_VERIFYHOST(3) for that. The check that the
-host name in the certificate is valid for the host name you are connecting to
+hostname in the certificate is valid for the hostname you are connecting to
is done independently of the CURLOPT_DOH_SSL_VERIFYPEER(3) option.
WARNING: disabling verification of the certificate allows bad guys to
# DESCRIPTION
A long parameter set to 1 tells the library to follow any Location: header
-redirects that a HTTP server sends in a 30x response. The Location: header can
-specify a relative or an absolute URL to follow.
+redirects that an HTTP server sends in a 30x response. The Location: header
+can specify a relative or an absolute URL to follow.
libcurl issues another request for the new URL and follows subsequent new
Location: redirects all the way until no more such headers are returned or the
IP address to use for the FTP PORT instruction.
The PORT instruction tells the remote server to do a TCP connect to our
-specified IP address. The string may be a plain IP address, a host name, a
+specified IP address. The string may be a plain IP address, a hostname, a
network interface name (under Unix) or just a '-' symbol to let the library
use your system's default IP address. Default FTP operations are passive, and
does not use the PORT command.
CURLOPT_WRITEFUNCTION(3), or if it is not specified or NULL - the
default, stream-writing function.
-It's important to note that the callback is invoked for the headers of all
+It is important to note that the callback is invoked for the headers of all
responses received after initiating a request and not just the final
response. This includes all responses which occur during authentication
negotiation. If you need to operate on only the headers from the final
# DESCRIPTION
-Make the *filename* point to a file name to load an existing HSTS cache
+Make the *filename* point to a filename to load an existing HSTS cache
from, and to store the cache in when the easy handle is closed. Setting a file
name with this option also enables HSTS for this handle (the equivalent of
setting *CURLHSTS_ENABLE* with CURLOPT_HSTS_CTRL(3)).
If the given file does not exist or contains no HSTS entries at startup, the
-HSTS cache simply starts empty. Setting the file name to NULL or "" only
+HSTS cache simply starts empty. Setting the filename to NULL or "" only
enables HSTS without reading from or writing to any file.
If this option is set multiple times, libcurl loads cache entries from each
or it is NULL.
When this callback is invoked, the *sts* pointer points to a populated
-struct: Copy the host name to *name* (no longer than *namelen*
+struct: Copy the hostname to *name* (no longer than *namelen*
bytes). Make it null-terminated. Set *includeSubDomains* to TRUE or
FALSE. Set *expire* to a date stamp or a zero length string for *forever*
(wrong date stamp format might cause the name to not get accepted)
Set the *clientp* argument with the CURLOPT_HSTSWRITEDATA(3) option
or it is NULL.
When the callback is invoked, the *sts* pointer points to a populated
-struct: Read the host name to 'name' (it is *namelen* bytes long and null
+struct: Read the hostname to 'name' (it is *namelen* bytes long and null
terminated. The *includeSubDomains* field is non-zero if the entry matches
subdomains. The *expire* string is a date stamp null-terminated string
using the syntax YYYYMMDD HH:MM:SS.
## Host:
-The specified host name is used for cookie matching if the cookie engine is
+The specified hostname is used for cookie matching if the cookie engine is
also enabled for this transfer. If the request is done over HTTP/2 or HTTP/3,
-the custom host name is instead used in the ":authority" header field and
+the custom hostname is instead used in the ":authority" header field and
Host: is not sent at all over the wire.
## Transfer-Encoding: chunked
# SPECIFIC MIME HEADERS
-When used to build a MIME e-mail for IMAP or SMTP, the following
-document-level headers can be set to override libcurl-generated values:
+When used to build a MIME email for IMAP or SMTP, the following document-level
+headers can be set to override libcurl-generated values:
## Mime-Version:
libcurl to use the specific HTTP versions.
Note that the HTTP version is just a request. libcurl still prioritizes to
-reuse existing connections so it might then reuse a connection using a HTTP
+reuse existing connections so it might then reuse a connection using an HTTP
version you have not asked for.
## CURL_HTTP_VERSION_NONE
To unset this value again, set it to -1.
-Using CURLOPT_UPLOAD(3) to a HTTP/1.1 server and this value set to -1,
-makes libcurl do a chunked transfer-encoded upload.
+Using CURLOPT_UPLOAD(3) to an HTTP/1.1 server and this value set to -1, makes
+libcurl do a chunked transfer-encoded upload.
When sending emails using SMTP, this command can be used to specify the
optional SIZE parameter for the MAIL FROM command.
Pass a char pointer as parameter. This sets the *interface* name to use as
outgoing network interface. The name can be an interface name, an IP address,
-or a host name.
+or a hostname.
If the parameter starts with "if!" then it is treated only as an interface
name. If the parameter starts with &"host!" it is treated as either an IP
setting this.
This option is an alternative to CURLOPT_ISSUERCERT(3) which instead
-expects a file name as input.
+expects a filename as input.
# DEFAULT
transitioned to use percent-encoding. This option allows one to address
server-side applications that have not yet have been converted.
-As an example, consider field or file name *strangename"kind*.
-When the containing multipart form is sent, this is normally transmitted as
+As an example, consider field or filename *strangename"kind*. When the
+containing multipart form is sent, this is normally transmitted as
*strangename%22kind*. When this option is set, it is sent as
*strangename"kind*.
On Windows, libcurl uses the file as *%HOME%/_netrc*. If *%HOME%* is
not set on Windows, libcurl falls back to *%USERPROFILE%*.
-You can also tell libcurl a different file name to use with
+You can also tell libcurl a different filename to use with
CURLOPT_NETRC_FILE(3).
libcurl uses a user name (and supplied or prompted password) supplied with
## machine <name>
Provides credentials for a host called **name**. libcurl searches the .netrc
-file for a machine token that matches the host name specified in the URL. Once
+file for a machine token that matches the hostname specified in the URL. Once
a match is made, the subsequent tokens are processed, stopping when the end of
file is reached or another "machine" is encountered.
# NAME
-CURLOPT_NETRC_FILE - file name to read .netrc info from
+CURLOPT_NETRC_FILE - filename to read .netrc info from
# SYNOPSIS
# DESCRIPTION
Pass a pointer to a null-terminated string as parameter. The string can be the
-file name of your pinned public key. The file format expected is "PEM" or
+filename of your pinned public key. The file format expected is "PEM" or
"DER". The string can also be any number of base64 encoded sha256 hashes
preceded by "sha256//" and separated by ";"
reused handle, you must explicitly set the new request type using
CURLOPT_NOBODY(3) or CURLOPT_HTTPGET(3) or similar.
-When setting CURLOPT_POST(3) to 0, libcurl resets the request type to
-the default to disable the POST. Typically that would mean it's reset to GET.
-Instead you should set a new request type explicitly as described above.
+When setting CURLOPT_POST(3) to 0, libcurl resets the request type to the
+default to disable the POST. Typically that means gets reset to GET. Instead
+you should set a new request type explicitly as described above.
# DEFAULT
# DESCRIPTION
-Set the *preproxy* to use for the upcoming request. The parameter
-should be a char * to a null-terminated string holding the host name or dotted
-numerical IP address. A numerical IPv6 address must be written within
-[brackets].
+Set the *preproxy* to use for the upcoming request. The parameter should be a
+char * to a null-terminated string holding the hostname or dotted 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
name. The proxy's port number may optionally be specified with the separate
Default is NULL, meaning no pre proxy is used.
-When you set a host name to use, do not assume that there is any particular
+When you set a hostname to use, do not assume that there is any particular
single port number used widely for proxies. Specify it!
# PROTOCOLS
# DESCRIPTION
Set the *proxy* to use for transfers with this easy handle. The parameter
-should be a char * to a null-terminated string holding the host name or dotted
+should be a char * to a null-terminated string holding the hostname or dotted
numerical IP address. A numerical IPv6 address must be written within
[brackets].
# Environment variables
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. So for a "FTP://" URL, the **ftp_proxy** is
+**ftp_proxy**, **sftp_proxy** etc. If set, libcurl uses the specified proxy
+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
setting the CURLOPT_NOPROXY(3) option.
-The CURLOPT_PROXY(3) and CURLOPT_NOPROXY(3) options override
-environment variables.
+The CURLOPT_PROXY(3) and CURLOPT_NOPROXY(3) options override environment
+variables.
# DEFAULT
Default is NULL, meaning no proxy is used.
-When you set a host name to use, do not assume that there is any particular
+When you set a hostname to use, do not assume that there is any particular
single port number used widely for proxies. Specify it!
# PROTOCOLS
setting this.
This option is an alternative to CURLOPT_PROXY_ISSUERCERT(3) which
-instead expects a file name as input.
+instead expects a filename as input.
# DEFAULT
# DESCRIPTION
Pass a pointer to a null-terminated string as parameter. The string can be the
-file name of your pinned public key. The file format expected is "PEM" or
+filename of your pinned public key. The file format expected is "PEM" or
"DER". The string can also be any number of base64 encoded sha256 hashes
preceded by "sha256//" and separated by ";"
This option is for connecting to an HTTPS proxy, not an HTTPS server.
Pass a pointer to a null-terminated string as parameter. The string should be
-the file name of your client certificate used to connect to the HTTPS proxy.
+the filename of your client certificate used to connect to the HTTPS proxy.
The default format is "P12" on Secure Transport and "PEM" on other engines,
and can be changed with CURLOPT_PROXY_SSLCERTTYPE(3).
setting this.
This option is an alternative to CURLOPT_PROXY_SSLCERT(3) which instead
-expects a file name as input.
+expects a filename as input.
# DEFAULT
# DESCRIPTION
Pass a pointer to a null-terminated string as parameter. The string should be
-the file name of your private key used for connecting to the HTTPS proxy. The
+the filename of your private key used for connecting to the HTTPS proxy. The
default format is "PEM" and can be changed with
CURLOPT_PROXY_SSLKEYTYPE(3).
connection fails.
Curl considers the proxy the intended one when the Common Name field or a
-Subject Alternate Name field in the certificate matches the host name in the
+Subject Alternate Name field in the certificate matches the hostname in the
proxy string which you told curl to use.
If *verify* value is set to 1:
Authenticating the certificate is not enough to be sure about the server. You
typically also want to ensure that the server is the server you mean to be
talking to. Use CURLOPT_PROXY_SSL_VERIFYHOST(3) for that. The check that the
-host name in the certificate is valid for the host name you are connecting to
-is done independently of the CURLOPT_PROXY_SSL_VERIFYPEER(3) option.
+hostname in the certificate is valid for the hostname you are connecting to is
+done independently of the CURLOPT_PROXY_SSL_VERIFYPEER(3) option.
WARNING: disabling verification of the certificate allows bad guys to
man-in-the-middle the communication without you knowing it. Disabling
Deprecated option. It serves no purpose anymore.
-Pass a char pointer to a null-terminated file name. The file might be used to
+Pass a char pointer to a null-terminated filename. The file might be used to
read from to seed the random engine for SSL and more.
The application does not have to keep the string around after setting this
# NAME
-CURLOPT_RESOLVE - provide custom host name to IP address resolves
+CURLOPT_RESOLVE - provide custom hostname to IP address resolves
# SYNOPSIS
# DESCRIPTION
-Pass a pointer to a linked list of strings with host name resolve information
+Pass a pointer to a linked list of strings with hostname resolve information
to use for requests with this handle. The linked list should be a fully valid
list of **struct curl_slist** structs properly filled in. Use
-curl_slist_append(3) to create the list and curl_slist_free_all(3)
-to clean up an entire list.
+curl_slist_append(3) to create the list and curl_slist_free_all(3) to clean up
+an entire list.
Each resolve rule to add should be written using the format
-HOST:PORT
~~~
-The entry to remove must be prefixed with a dash, and the host name and port
+The entry to remove must be prefixed with a dash, and the hostname and port
number must exactly match what was added previously.
# DEFAULT
This callback function gets called by libcurl every time before a new resolve
request is started.
-*resolver_state* points to a backend-specific resolver state. Currently
-only the ares resolver backend has a resolver state. It can be used to set up
-any desired option on the ares channel before it's used, for example setting up
+*resolver_state* points to a backend-specific resolver state. Currently only
+the ares resolver backend has a resolver state. It can be used to set up any
+desired option on the ares channel before it is used, for example setting up
socket callback options.
*reserved* is reserved.
## CURL_RTSPREQ_SET_PARAMETER
-Set a parameter on the server. By default, libcurl uses a
-*Content-Type: text/parameters* header unless a custom one is set.
-The interaction with SET_PARAMETER is much like an HTTP PUT or POST. An
-application may either use CURLOPT_UPLOAD(3) with
-CURLOPT_READDATA(3) like a HTTP PUT, or it may use
-CURLOPT_POSTFIELDS(3) like an HTTP POST. No chunked transfers are
-allowed, so the application must set the CURLOPT_INFILESIZE(3) in the
-former and CURLOPT_POSTFIELDSIZE(3) in the latter. Also, there is no use
-of multi-part POSTs within RTSP.
+Set a parameter on the server. By default, libcurl uses a *Content-Type:
+text/parameters* header unless a custom one is set. The interaction with
+SET_PARAMETER is much like an HTTP PUT or POST. An application may either use
+CURLOPT_UPLOAD(3) with CURLOPT_READDATA(3) like an HTTP PUT, or it may use
+CURLOPT_POSTFIELDS(3) like an HTTP POST. No chunked transfers are allowed, so
+the application must set the CURLOPT_INFILESIZE(3) in the former and
+CURLOPT_POSTFIELDSIZE(3) in the latter. Also, there is no use of multi-part
+POSTs within RTSP.
## CURL_RTSPREQ_RECORD
# NAME
-CURLOPT_SSH_KNOWNHOSTS - file name holding the SSH known hosts
+CURLOPT_SSH_KNOWNHOSTS - filename holding the SSH known hosts
# SYNOPSIS
# DESCRIPTION
-Pass a pointer to a null-terminated string holding the file name of the
+Pass a pointer to a null-terminated string holding the filename of the
known_host file to use. The known_hosts file should use the OpenSSH file
format as supported by libssh2. If this file is specified, libcurl only
accepts connections with hosts that are known and present in that file, with a
# DESCRIPTION
Pass a pointer to a null-terminated string as parameter. The string should be
-the file name of your client certificate. The default format is "P12" on
-Secure Transport and "PEM" on other engines, and can be changed with
+the filename of your client certificate. The default format is "P12" on Secure
+Transport and "PEM" on other engines, and can be changed with
CURLOPT_SSLCERTTYPE(3).
With Secure Transport, this can also be the nickname of the certificate you
setting this.
This option is an alternative to CURLOPT_SSLCERT(3) which instead
-expects a file name as input.
+expects a filename as input.
# DEFAULT
# DESCRIPTION
Pass a pointer to a null-terminated string as parameter. The string should be
-the file name of your private key. The default format is "PEM" and can be
+the filename of your private key. The default format is "PEM" and can be
changed with CURLOPT_SSLKEYTYPE(3).
(Windows, iOS and Mac OS X) This option is ignored by Secure Transport and
CURL_BLOB_COPY, the application does not have to keep the buffer around after
setting this.
-This option is an alternative to CURLOPT_SSLKEY(3) which instead expects
-a file name as input.
+This option is an alternative to CURLOPT_SSLKEY(3) which instead expects a
+filename as input.
# DEFAULT
is in the URL you operate against.
Curl considers the server the intended one when the Common Name field or a
-Subject Alternate Name field in the certificate matches the host name in the
+Subject Alternate Name field in the certificate matches the hostname in the
URL to which you told Curl to connect.
If *verify* value is set to 1:
Authenticating the certificate is not enough to be sure about the server. You
typically also want to ensure that the server is the server you mean to be
-talking to. Use CURLOPT_SSL_VERIFYHOST(3) for that. The check that the
-host name in the certificate is valid for the host name you are connecting to
-is done independently of the CURLOPT_SSL_VERIFYPEER(3) option.
+talking to. Use CURLOPT_SSL_VERIFYHOST(3) for that. The check that the host
+name in the certificate is valid for the hostname you are connecting to is
+done independently of the CURLOPT_SSL_VERIFYPEER(3) option.
WARNING: disabling verification of the certificate allows bad guys to
man-in-the-middle the communication without you knowing it. Disabling
See section 5.3 of RFC 7540 for protocol details.
Streams with the same parent should be allocated resources proportionally
-based on their weight. So if you have two streams going, stream A with weight
-16 and stream B with weight 32, stream B gets two thirds (32/48) of the
-available bandwidth (assuming the server can send off the data equally for
-both streams).
+based on their weight. If you have two streams going, stream A with weight 16
+and stream B with weight 32, stream B gets two thirds (32/48) of the available
+bandwidth (assuming the server can send off the data equally for both
+streams).
# DEFAULT
suppress proxy CONNECT response headers from the user callback functions
CURLOPT_HEADERFUNCTION(3) and CURLOPT_WRITEFUNCTION(3).
-Proxy CONNECT response headers can complicate header processing since it's
+Proxy CONNECT response headers can complicate header processing since it is
essentially a separate set of headers. You can enable this option to suppress
those headers.
to other hosts than the one used for the initial URL.
By default, libcurl only sends credentials and Authentication headers to the
-initial host name as given in the original URL, to avoid leaking username +
+initial hostname as given in the original URL, to avoid leaking username +
password to other sites.
This option should be used with caution: when curl follows redirects it
blindly fetches the next URL as instructed by the server. Setting
-CURLOPT_UNRESTRICTED_AUTH(3) to 1L therefore also makes curl trust the
-server and sends possibly sensitive credentials to any host the server points
-out. And then maybe again and again as the following hosts can keep
-redirecting to new hosts.
+CURLOPT_UNRESTRICTED_AUTH(3) to 1L makes curl trust the server and sends
+possibly sensitive credentials to any host the server points to, possibly
+again and again as the following hosts can keep redirecting to new hosts.
# DEFAULT
default protocol, see CURLOPT_DEFAULT_PROTOCOL(3) for details.
Should the protocol, either as specified by the URL scheme or deduced by
-libcurl from the host name, not be supported by libcurl then
-*CURLE_UNSUPPORTED_PROTOCOL* is returned from either the
-curl_easy_perform(3) or curl_multi_perform(3) functions when you
-call them. Use curl_version_info(3) for detailed information of which
-protocols are supported by the build of libcurl you are using.
+libcurl from the hostname, not be supported by libcurl then
+*CURLE_UNSUPPORTED_PROTOCOL* is returned from either the curl_easy_perform(3)
+or curl_multi_perform(3) functions when you call them. Use
+curl_version_info(3) for detailed information of which protocols are supported
+by the build of libcurl you are using.
CURLOPT_PROTOCOLS_STR(3) can be used to limit what protocols libcurl may
use for this transfer, independent of what libcurl has been compiled to
Some HTTP servers (on Windows) support inclusion of the domain for Basic
authentication as well.
-When using HTTP and CURLOPT_FOLLOWLOCATION(3), libcurl might perform
-several requests to possibly different hosts. libcurl only sends this user and
-password information to hosts using the initial host name (unless
-CURLOPT_UNRESTRICTED_AUTH(3) is set), so if libcurl follows redirects to
-other hosts, it does not send the user and password to those. This is enforced
-to prevent accidental information leakage.
+When using HTTP and CURLOPT_FOLLOWLOCATION(3), libcurl might perform several
+requests to possibly different hosts. libcurl only sends this user and
+password information to hosts using the initial hostname (unless
+CURLOPT_UNRESTRICTED_AUTH(3) is set), so if libcurl follows redirects to other
+hosts, it does not send the user and password to those. This is enforced to
+prevent accidental information leakage.
Use CURLOPT_HTTPAUTH(3) to specify the authentication method for HTTP
based connections or CURLOPT_LOGIN_OPTIONS(3) to control IMAP, POP3 and
# DESCRIPTION
Set *onoff* to 1 if you want to transfer multiple files according to a
-file name pattern. The pattern can be specified as part of the
-CURLOPT_URL(3) option, using an **fnmatch**-like pattern (Shell
-Pattern Matching) in the last part of URL (file name).
+filename pattern. The pattern can be specified as part of the CURLOPT_URL(3)
+option, using an **fnmatch**-like pattern (Shell Pattern Matching) in the last
+part of URL (filename).
By default, libcurl uses its internal wildcard matching implementation. You
can provide your own matching function by the
## * - ASTERISK
-~~~c
- ftp://example.com/some/path/*.txt
-~~~
+ ftp://example.com/some/path/*.txt
+
for all txt's from the root directory. Only two asterisks are allowed within
the same pattern string.
## ? - QUESTION MARK
Question mark matches any (exactly one) character.
-~~~c
- ftp://example.com/some/path/photo?.jpg
-~~~
+
+ ftp://example.com/some/path/photo?.jpg
## [ - BRACKET EXPRESSION
**[^abc]** or **[!abc]** - negation
-**[[:name:]]** class expression. Supported classes are
-**alnum**,**lower**, **space**, **alpha**, **digit**, **print**,
-**upper**, **blank**, **graph**, **xdigit**.
+**[[:name:]]** class expression. Supported classes are **alnum**,**lower**,
+**space**, **alpha**, **digit**, **print**, **upper**, **blank**, **graph**,
+**xdigit**.
**[][-!^]** - special case - matches only '-', ']', '[', '!' or '^'. These
characters have no special purpose.
**[[]]** - escape syntax. Matches '[', ']' or 'e'.
-Using the rules above, a file name pattern can be constructed:
-~~~c
- ftp://example.com/some/path/[a-z[:upper:]\\].jpg
-~~~
+Using the rules above, a filename pattern can be constructed:
+
+ ftp://example.com/some/path/[a-z[:upper:]\\].jpg
# PROTOCOLS
# EXAMPLE
~~~c
-
extern long begin_cb(struct curl_fileinfo *, void *, int);
extern long end_cb(void *ptr);
projects / thirdparty / curl.git / commitdiff
