docs: minor polish
- "an HTTP*" (not "a") - remove a few contractions - remove a spurious "a" - reduce use of "I" in texts Closes #11040
This commit is contained in:
parent
bb0b245cc1
commit
4578ada4a0
@ -64,7 +64,7 @@ resolution screens:
|
|||||||
newspapers have used columns for decades or centuries.
|
newspapers have used columns for decades or centuries.
|
||||||
|
|
||||||
2. Narrower columns allow developers to easier show multiple pieces of code
|
2. Narrower columns allow developers to easier show multiple pieces of code
|
||||||
next to each other in different windows. I often have two or three source
|
next to each other in different windows. It allows two or three source
|
||||||
code windows next to each other on the same screen - as well as multiple
|
code windows next to each other on the same screen - as well as multiple
|
||||||
terminal and debugging windows.
|
terminal and debugging windows.
|
||||||
|
|
||||||
|
|||||||
@ -25,7 +25,7 @@ Curl_easy *data connectdata *conn cf-ssl cf-socket
|
|||||||
|
|
||||||
While connection filters all do different things, they look the same from the "outside". The code in `data` and `conn` does not really know **which** filters are installed. `conn` just writes into the first filter, whatever that is.
|
While connection filters all do different things, they look the same from the "outside". The code in `data` and `conn` does not really know **which** filters are installed. `conn` just writes into the first filter, whatever that is.
|
||||||
|
|
||||||
Same is true for filters. Each filter has a pointer to the `next` filter. When SSL has encrypted the data, it does not write to a socket, it writes to the next filter. If that is indeed a socket, or a file, or a HTTP/2 connection is of no concern to the SSL filter.
|
Same is true for filters. Each filter has a pointer to the `next` filter. When SSL has encrypted the data, it does not write to a socket, it writes to the next filter. If that is indeed a socket, or a file, or an HTTP/2 connection is of no concern to the SSL filter.
|
||||||
|
|
||||||
And this allows the stacking, as in:
|
And this allows the stacking, as in:
|
||||||
|
|
||||||
@ -91,13 +91,13 @@ struct Curl_cfilter {
|
|||||||
BIT(connected); /* != 0 iff this filter is connected */
|
BIT(connected); /* != 0 iff this filter is connected */
|
||||||
};
|
};
|
||||||
```
|
```
|
||||||
The filter type `cft` is a singleton, one static struct for each type of filter. The `ctx` is where a filter will hold its specific data. That varies by filter type. A http-proxy filter will keep the ongoing state of the CONNECT here, but free it after its has been established. The SSL filter will keep the `SSL*` (if OpenSSL is used) here until the connection is closed. So, this varies.
|
The filter type `cft` is a singleton, one static struct for each type of filter. The `ctx` is where a filter will hold its specific data. That varies by filter type. An http-proxy filter will keep the ongoing state of the CONNECT here, but free it after its has been established. The SSL filter will keep the `SSL*` (if OpenSSL is used) here until the connection is closed. So, this varies.
|
||||||
|
|
||||||
`conn` is a reference to the connection this filter belongs to, so nothing extra besides the pointer itself.
|
`conn` is a reference to the connection this filter belongs to, so nothing extra besides the pointer itself.
|
||||||
|
|
||||||
Several things, that before were kept in `struct connectdata`, will now go into the `filter->ctx` *when needed*. So, the memory footprint for connections that do *not* use a http proxy, or socks, or https will be lower.
|
Several things, that before were kept in `struct connectdata`, will now go into the `filter->ctx` *when needed*. So, the memory footprint for connections that do *not* use an http proxy, or socks, or https will be lower.
|
||||||
|
|
||||||
As to transfer efficiency, writing and reading through a filter comes at near zero cost *if the filter does not transform the data*. A http proxy or socks filter, once it is connected, will just pass the calls through. Those filters implementations will look like this:
|
As to transfer efficiency, writing and reading through a filter comes at near zero cost *if the filter does not transform the data*. An http proxy or socks filter, once it is connected, will just pass the calls through. Those filters implementations will look like this:
|
||||||
|
|
||||||
```
|
```
|
||||||
ssize_t Curl_cf_def_send(struct Curl_cfilter *cf, struct Curl_easy *data,
|
ssize_t Curl_cf_def_send(struct Curl_cfilter *cf, struct Curl_easy *data,
|
||||||
|
|||||||
@ -205,9 +205,9 @@ A short guide to how to write git commit messages in the curl project.
|
|||||||
followed by an -- empty line -- ]
|
followed by an -- empty line -- ]
|
||||||
[Bug: URL to the source of the report or more related discussion; use Fixes
|
[Bug: URL to the source of the report or more related discussion; use Fixes
|
||||||
for GitHub issues instead when that is appropriate]
|
for GitHub issues instead when that is appropriate]
|
||||||
[Approved-by: John Doe - credit someone who approved the PR; if you're
|
[Approved-by: John Doe - credit someone who approved the PR; if you are
|
||||||
committing this for someone else using --author=... you don't need this
|
committing this for someone else using --author=... you don't need this
|
||||||
as you're implicitly approving it by committing]
|
as you are implicitly approving it by committing]
|
||||||
[Authored-by: John Doe - credit the original author of the code; only use
|
[Authored-by: John Doe - credit the original author of the code; only use
|
||||||
this if you can't use "git commit --author=..."]
|
this if you can't use "git commit --author=..."]
|
||||||
{Signed-off-by: John Doe - we don't use this, but don't bother removing it]
|
{Signed-off-by: John Doe - we don't use this, but don't bother removing it]
|
||||||
|
|||||||
@ -275,7 +275,7 @@ The `happy-eyeballs-timeout-ms` value is the **hard** timeout, meaning after tha
|
|||||||
|
|
||||||
So, without you specifying anything, the hard timeout is 200ms and the soft is 100ms:
|
So, without you specifying anything, the hard timeout is 200ms and the soft is 100ms:
|
||||||
|
|
||||||
* Ideally, the whole QUIC handshake happens and curl has a HTTP/3 connection in less than 100ms.
|
* Ideally, the whole QUIC handshake happens and curl has an HTTP/3 connection in less than 100ms.
|
||||||
* When QUIC is not supported (or UDP does not work for this network path), no reply is seen and the HTTP/2 TLS+TCP connection starts 100ms later.
|
* When QUIC is not supported (or UDP does not work for this network path), no reply is seen and the HTTP/2 TLS+TCP connection starts 100ms later.
|
||||||
* In the worst case, UDP replies start before 100ms, but drag on. This will start the TLS+TCP connection after 200ms.
|
* In the worst case, UDP replies start before 100ms, but drag on. This will start the TLS+TCP connection after 200ms.
|
||||||
* When the QUIC handshake fails, the TLS+TCP connection is attempted right away. For example, when the QUIC server presents the wrong certificate.
|
* When the QUIC handshake fails, the TLS+TCP connection is attempted right away. For example, when the QUIC server presents the wrong certificate.
|
||||||
@ -300,8 +300,8 @@ ones. You can easily create huge local files like `truncate -s=8G 8GB` - they
|
|||||||
are huge but do not occupy that much space on disk since they are just big
|
are huge but do not occupy that much space on disk since they are just big
|
||||||
holes.
|
holes.
|
||||||
|
|
||||||
In my Debian setup I just installed **apache2**. It runs on port 80 and has a
|
In a Debian setup you can install **apache2**. It runs on port 80 and has a
|
||||||
document root in `/var/www/html`. I can get the 8GB file from it with `curl
|
document root in `/var/www/html`. Download the 8GB file from apache with `curl
|
||||||
localhost/8GB -o dev/null`
|
localhost/8GB -o dev/null`
|
||||||
|
|
||||||
In this description we setup and run an HTTP/3 reverse-proxy in front of the
|
In this description we setup and run an HTTP/3 reverse-proxy in front of the
|
||||||
|
|||||||
@ -423,7 +423,7 @@ OpenSSL, follow the OpenSSL build instructions and then install `libssl.a` and
|
|||||||
OpenSSL like this:
|
OpenSSL like this:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
LIBS="-lssl -lcrypto -lc++" # For OpenSSL/BoringSSL. In general, you'll need to the SSL/TLS layer's transtive dependencies if you're linking statically.
|
LIBS="-lssl -lcrypto -lc++" # For OpenSSL/BoringSSL. In general, you will need to the SSL/TLS layer's transtive dependencies if you are linking statically.
|
||||||
./configure --host aarch64-linux-android --with-pic --disable-shared --with-openssl="$TOOLCHAIN/sysroot/usr"
|
./configure --host aarch64-linux-android --with-pic --disable-shared --with-openssl="$TOOLCHAIN/sysroot/usr"
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|||||||
@ -786,18 +786,16 @@ by default.
|
|||||||
Default protocol version used by curl is LDAP version 3. Version 2 will be
|
Default protocol version used by curl is LDAP version 3. Version 2 will be
|
||||||
used as a fallback mechanism in case version 3 fails to connect.
|
used as a fallback mechanism in case version 3 fails to connect.
|
||||||
|
|
||||||
LDAP is a complex thing and writing an LDAP query is not an easy task. I do
|
LDAP is a complex thing and writing an LDAP query is not an easy
|
||||||
advise you to dig up the syntax description for that elsewhere. One such place
|
task. Familiarize yourself with the exact syntax description elsewhere. One
|
||||||
might be: [RFC 2255, The LDAP URL Format](https://curl.se/rfc/rfc2255.txt)
|
such place might be: [RFC 2255, The LDAP URL
|
||||||
|
Format](https://curl.se/rfc/rfc2255.txt)
|
||||||
|
|
||||||
To show you an example, this is how I can get all people from my local LDAP
|
To show you an example, this is how to get all people from an LDAP server that
|
||||||
server that has a certain sub-domain in their email address:
|
has a certain sub-domain in their email address:
|
||||||
|
|
||||||
curl -B "ldap://ldap.frontec.se/o=frontec??sub?mail=*sth.frontec.se"
|
curl -B "ldap://ldap.frontec.se/o=frontec??sub?mail=*sth.frontec.se"
|
||||||
|
|
||||||
If I want the same info in HTML format, I can get it by not using the `-B`
|
|
||||||
(enforce ASCII) flag.
|
|
||||||
|
|
||||||
You also can use authentication when accessing LDAP catalog:
|
You also can use authentication when accessing LDAP catalog:
|
||||||
|
|
||||||
curl -u user:passwd "ldap://ldap.frontec.se/o=frontec??sub?mail=*"
|
curl -u user:passwd "ldap://ldap.frontec.se/o=frontec??sub?mail=*"
|
||||||
|
|||||||
@ -11,8 +11,9 @@
|
|||||||
|
|
||||||
Curl is a command line tool for doing all sorts of URL manipulations and
|
Curl is a command line tool for doing all sorts of URL manipulations and
|
||||||
transfers, but this particular document will focus on how to use it when
|
transfers, but this particular document will focus on how to use it when
|
||||||
doing HTTP requests for fun and profit. I will assume that you know how to
|
doing HTTP requests for fun and profit. This documents assumes that you know
|
||||||
invoke `curl --help` or `curl --manual` to get basic information about it.
|
how to invoke `curl --help` or `curl --manual` to get basic information about
|
||||||
|
it.
|
||||||
|
|
||||||
Curl is not written to do everything for you. It makes the requests, it gets
|
Curl is not written to do everything for you. It makes the requests, it gets
|
||||||
the data, it sends data and it retrieves the information. You probably need
|
the data, it sends data and it retrieves the information. You probably need
|
||||||
|
|||||||
@ -12,7 +12,7 @@ Category: http proxy
|
|||||||
Example: --proxy-http2 -x proxy $URL
|
Example: --proxy-http2 -x proxy $URL
|
||||||
Multi: boolean
|
Multi: boolean
|
||||||
---
|
---
|
||||||
Tells curl to try negotiate HTTP version 2 with a HTTPS proxy. The proxy might
|
Tells curl to try negotiate HTTP version 2 with an HTTPS proxy. The proxy might
|
||||||
still only offer HTTP/1 and then curl will stick to using that version.
|
still only offer HTTP/1 and then curl will stick to using that version.
|
||||||
|
|
||||||
This has no effect for any other kinds of proxies.
|
This has no effect for any other kinds of proxies.
|
||||||
|
|||||||
@ -34,7 +34,7 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ALTSVC, char *filename);
|
|||||||
.SH DESCRIPTION
|
.SH DESCRIPTION
|
||||||
Pass in a pointer to a \fIfilename\fP to instruct libcurl to use that file as
|
Pass in a pointer to a \fIfilename\fP to instruct libcurl to use that file as
|
||||||
the Alt-Svc cache to read existing cache contents from and possibly also write
|
the Alt-Svc cache to read existing cache contents from and possibly also write
|
||||||
it back to a after a transfer, unless \fBCURLALTSVC_READONLYFILE\fP is set in
|
it back to after a transfer, unless \fBCURLALTSVC_READONLYFILE\fP is set in
|
||||||
\fICURLOPT_ALTSVC_CTRL(3)\fP.
|
\fICURLOPT_ALTSVC_CTRL(3)\fP.
|
||||||
|
|
||||||
Specify a blank file name ("") to make libcurl not load from a file at all.
|
Specify a blank file name ("") to make libcurl not load from a file at all.
|
||||||
|
|||||||
@ -99,7 +99,7 @@ method special. This method cannot be combined with other auth types.
|
|||||||
A sha256 checksum of the request payload is used as input to the signature
|
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
|
calculation. For POST requests, this is a checksum of the provided
|
||||||
\fICURLOPT_POSTFIELDS(3)\fP. Otherwise, it's the checksum of an empty buffer.
|
\fICURLOPT_POSTFIELDS(3)\fP. Otherwise, it's the checksum of an empty buffer.
|
||||||
For requests like PUT, you can provide your own checksum in a HTTP header named
|
For requests like PUT, you can provide your own checksum in an HTTP header named
|
||||||
\fBx-provider2-content-sha256\fP.
|
\fBx-provider2-content-sha256\fP.
|
||||||
.PP
|
.PP
|
||||||
For \fBaws:s3\fP, a \fBx-amz-content-sha256\fP header is added to every request
|
For \fBaws:s3\fP, a \fBx-amz-content-sha256\fP header is added to every request
|
||||||
|
|||||||
@ -124,7 +124,7 @@ Since 7.21.7 the proxy string supports the socks protocols as "schemes".
|
|||||||
Since 7.50.2, unsupported schemes in proxy strings cause libcurl to return
|
Since 7.50.2, unsupported schemes in proxy strings cause libcurl to return
|
||||||
error.
|
error.
|
||||||
|
|
||||||
curl built to use NSS cannot connect to a HTTPS server over a unix domain
|
curl built to use NSS cannot connect to an HTTPS server over a unix domain
|
||||||
socket.
|
socket.
|
||||||
.SH RETURN VALUE
|
.SH RETURN VALUE
|
||||||
Returns CURLE_OK if proxies are supported, CURLE_UNKNOWN_OPTION if not, or
|
Returns CURLE_OK if proxies are supported, CURLE_UNKNOWN_OPTION if not, or
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user